import type { Readable } from "node:stream";
import { type S3Client } from "@aws-sdk/client-s3";
import { type BackupConfig } from "./config.js";
import type { Manifest } from "./manifest.js";
/**
 * 快照放在哪里,对引擎来说只是这几个动作:建一份新快照往里写、打开一份已有快照往外读。
 * 备份、演练、恢复都只经这层读写快照。CLI 只用 S3 兼容桶(s3SnapshotStore);托管服务
 * 的 worker 可以传入自己的实现(Google Drive 目标,实现不进公开包)。
 */
export interface SnapshotStore {
    /** name = 快照名(备份开始时的 UTC 时间戳) */
    createSnapshot(name: string): Promise<SnapshotWriter>;
    /** name 省略 = 最新一份 */
    openSnapshot(name?: string): Promise<SnapshotReader>;
}
/** 快照里 Storage 文件的位置(<base>/storage/<bucket>/<key>)。只有 S3 兼容目标能放 Storage 文件。 */
export interface StorageFilesLocation {
    s3: S3Client;
    bucket: string;
    base: string;
}
export interface DumpUpload {
    /** 转储全部写完才 resolve;任何失败都 reject */
    done: Promise<void>;
    /** 中止写入,尽量不留下半截文件 */
    abort(): Promise<void>;
}
export interface SnapshotWriter {
    /** 记进 manifest.dump.key 的值 */
    readonly dumpKey: string;
    /** 这份快照能不能放 Storage 文件;不能时为 null */
    readonly storageFiles: StorageFilesLocation | null;
    /** 日志里显示的位置 */
    describe(file: string): string;
    /** relationBytes = 要转储的表的磁盘占用(量不出为 null),实现可据此决定分块 */
    uploadDump(body: Readable, relationBytes: number | null): DumpUpload;
    /**
     * 可选(2.10.0 起):Auth 用户归档 auth.dump 写到哪、记进 manifest.auth.dump.key 的值。
     * 没实现的存储(例如还没适配的托管目标)备份时自动跳过 Auth,其余行为不变。
     */
    readonly authDumpKey?: string;
    uploadAuthDump?(body: Readable): DumpUpload;
    /** RECOVERY.md 写的是"从这个位置怎么恢复",所以由各实现自己渲染 */
    writeRecoveryDoc(manifest: Manifest): Promise<void>;
    /** manifest 是快照的"完成标记",调用方保证最后写 */
    writeManifest(manifest: Manifest): Promise<void>;
}
export interface SnapshotReader {
    readonly name: string;
    readManifest(): Promise<string>;
    /** 断点续传下载转储到本地文件,返回实际落盘的字节数与 sha256 */
    downloadDump(manifest: Manifest, dest: string): Promise<{
        bytes: number;
        sha256: string;
    }>;
    /** 可选(2.10.0 起):下载 auth.dump。没实现时,带 Auth 的快照按不带 Auth 处理 */
    downloadAuthDump?(manifest: Manifest, dest: string, opts?: {
        signal?: AbortSignal;
    }): Promise<{
        bytes: number;
        sha256: string;
    }>;
    /** 这份快照的 Storage 文件从哪读;实现不支持 Storage 文件时为 null */
    storageFiles(manifest: Manifest): StorageFilesLocation | null;
}
/** S3 兼容桶(S3 / R2 / B2 / Wasabi)。行为与抽出这层之前逐字一致。 */
export declare function s3SnapshotStore(config: BackupConfig): SnapshotStore;