backupdrill 1.1.0 → 2.0.1

package/dist/storage-restore.d.ts

@@ -0,0 +1,79 @@
+import { type S3Client } from "@aws-sdk/client-s3";
+import type { Manifest, StorageFile } from "./manifest.js";
+export interface StorageRestoreTarget {
+    supabaseUrl: string;
+    serviceRoleKey: string;
+}
+export interface ReconcileReport {
+    /** manifest 文件在目标上逐键找到且尺寸一致的数量 */
+    verified: number;
+    missing: string[];
+    sizeMismatched: string[];
+    /** 目标上存在但 manifest 没有的对象数——非快照内容混在恢复目标里 = 不是干净恢复,计入失败裁决 */
+    extras: number;
+    matches: boolean;
+}
+export interface StorageRestoreSummary {
+    bucketsCreated: string[];
+    bucketsExisting: string[];
+    /** manifest 未捕获属性的 bucket(以默认设置创建,如实上报,不猜测) */
+    bucketsWithoutAttrs: string[];
+    /** 既有 bucket 与 manifest 属性不一致的描述(warn 级:可能是用户有意配置) */
+    bucketAttrDrift: string[];
+    filesUploaded: number;
+    bytesUploaded: number;
+    /** 目标已有同 key 同尺寸对象而跳过的数量(重试残留;字节级抽样校验覆盖) */
+    filesSkippedIdentical: number;
+    filesFailed: {
+        file: string;
+        reason: string;
+    }[];
+    /** 429/5xx/超时后的成功重试次数(可观测性:PRD §10.3) */
+    retries: number;
+    reconcile: ReconcileReport;
+    checksumSample: {
+        checked: number;
+        mismatched: string[];
+    };
+    /** 元数据降级说明(如 TUS 路径不保真的字段)——如实上报,不静默丢 */
+    metadataNotes: string[];
+    /** PRD §5.4.3:owner 语义边界,报告必须显示 */
+    ownerNote: string;
+}
+/** bucket 名单 = manifest.buckets(含空桶)∪ files 里出现过的桶(v1 快照没有 buckets 字段) */
+export declare function bucketsToRestore(manifest: Manifest): {
+    name: string;
+    attrs: boolean;
+}[];
+export declare const STANDARD_UPLOAD_LIMIT_BYTES: number;
+/**
+ * TUS 启用阈值:默认 = 6MB(Supabase 官方对 resumable 的建议线)——大文件从零重传
+ * 的标准上传既脆弱又贵;env 可覆盖(验证时压低,特殊网络环境可调高)。
+ */
+export declare function tusThresholdBytes(): number;
+/**
+ * 递归遍历目标 bucket 的全部对象(list API 是目录级的:id === null 的条目是"目录")。
+ * 返回 key → size。不依赖目标 DB 凭据 → storage-only 恢复也有完整对账。
+ */
+export declare function walkTargetObjects(target: StorageRestoreTarget, bucket: string, counters?: {
+    retries: number;
+}): Promise<Map<string, number>>;
+/**
+ * 写前净度检查(纯函数,可测):既有桶里只允许"本快照的同尺寸残留"。
+ * 任何外来对象或尺寸冲突都在**写第一个字节之前**整体拒绝——部分写入的脏目标
+ * 比干净失败难收拾得多(评审第 14 轮)。
+ */
+export declare function targetResidueViolations(files: StorageFile[], preexisting: Map<string, Map<string, number>>): string[];
+/** 逐键对账(纯函数,可测):manifest 每个文件都必须在目标出现且尺寸一致;多余对象另计。 */
+export declare function reconcileFiles(files: StorageFile[], actualByBucket: Map<string, Map<string, number>>): ReconcileReport;
+/** dry-run / 执行前预检的公开形态:一次性 scratch 摘要,只返回计划概要与警告。 */
+export declare function planStorageRestore(target: StorageRestoreTarget, manifest: Manifest): Promise<{
+    bucketsToCreate: string[];
+    verifiedResidue: number;
+    warnings: string[];
+}>;
+export declare function restoreStorage(source: {
+    s3: S3Client;
+    bucket: string;
+    base: string;
+}, target: StorageRestoreTarget, manifest: Manifest): Promise<StorageRestoreSummary>;