backupdrill 1.0.0 → 2.0.0

package/dist/storage-catalog.d.ts

@@ -0,0 +1,19 @@
+import type { BucketAttrs } from "./manifest.js";
+interface BucketRow {
+    id: string;
+    name: string;
+    public: boolean | null;
+    file_size_limit: string | number | null;
+    allowed_mime_types: string[] | null;
+}
+/**
+ * 行 → manifest 形状的纯映射,含完整性关口:查询结果必须覆盖每一个请求的 bucket。
+ * storage.buckets 上的 RLS 或并发删除会**静默**少返回行——把不完整清单写进 manifest,
+ * 恢复端就会漏建 bucket 还以为自己全知。缺任何一个 → 抛错,由调用方整体降级为"未捕获"。
+ * 请求标识来自 S3 层(ListBuckets),优先按 buckets.id 匹配(id 与 name 允许不同),
+ * 无中再退 name。null 属性原样保留(= 源端未设置,不是猜测值)。
+ */
+export declare function bucketAttrsFromRows(requestedBuckets: string[], bucketRows: BucketRow[]): BucketAttrs[];
+/** 查询源库的 bucket 属性。bucketNames 含空 bucket(恢复端要能重建它们)。 */
+export declare function inspectBucketAttrs(databaseUrl: string, bucketNames: string[]): Promise<BucketAttrs[]>;
+export {};

package/dist/storage-catalog.js

@@ -0,0 +1,50 @@
+// Bucket 属性采集(Manifest v2,恢复闭环 PRD §5.1.3):public / 大小限制 / MIME 限制。
+// 通道 = 源库 storage.buckets —— S3 兼容端点看不到这些属性,而备份本来就持有只读库连接,
+// 零新增凭据(R0 spike 实证)。per-file 元数据不在这里:它随 syncStorage 的 GetObject
+// 响应原子捕获(见 storage.ts fileMetadataFromS3)。
+// 任何失败都由调用方降级为"未捕获"(manifest 缺 buckets 字段),绝不弄失败一次备份。
+import { Client } from "pg";
+import { pgConnectOptions } from "./supabase-ca.js";
+/**
+ * 行 → manifest 形状的纯映射,含完整性关口:查询结果必须覆盖每一个请求的 bucket。
+ * storage.buckets 上的 RLS 或并发删除会**静默**少返回行——把不完整清单写进 manifest,
+ * 恢复端就会漏建 bucket 还以为自己全知。缺任何一个 → 抛错,由调用方整体降级为"未捕获"。
+ * 请求标识来自 S3 层(ListBuckets),优先按 buckets.id 匹配(id 与 name 允许不同),
+ * 无中再退 name。null 属性原样保留(= 源端未设置,不是猜测值)。
+ */
+export function bucketAttrsFromRows(requestedBuckets, bucketRows) {
+    const attrs = [];
+    const missing = [];
+    for (const req of requestedBuckets) {
+        const row = bucketRows.find((r) => r.id === req) ?? bucketRows.find((r) => r.name === req);
+        if (!row) {
+            missing.push(req);
+            continue;
+        }
+        attrs.push({
+            name: req, // 快照对象布局用的标识(S3 层名),恢复端按它重建
+            public: row.public,
+            fileSizeLimit: row.file_size_limit === null ? null : Number(row.file_size_limit),
+            allowedMimeTypes: row.allowed_mime_types,
+        });
+    }
+    if (missing.length) {
+        throw new Error(`storage.buckets returned no row for: ${missing.join(", ")} ` +
+            `(RLS filtering or concurrent deletion) — refusing a partial bucket capture`);
+    }
+    return attrs;
+}
+/** 查询源库的 bucket 属性。bucketNames 含空 bucket(恢复端要能重建它们)。 */
+export async function inspectBucketAttrs(databaseUrl, bucketNames) {
+    const client = new Client(pgConnectOptions(databaseUrl));
+    await client.connect();
+    try {
+        const bucketRows = await client.query(`select id, name, public, file_size_limit, allowed_mime_types
+         from storage.buckets where id = any($1::text[]) or name = any($1::text[])
+        order by name`, [bucketNames]);
+        return bucketAttrsFromRows(bucketNames, bucketRows.rows);
+    }
+    finally {
+        await client.end();
+    }
+}

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>;