backupdrill 0.1.3 → 0.2.1

package/README.md

@@ -6,6 +6,8 @@ Backups stream through the CLI on your machine (or your CI) straight to your buc
 
 > Want this on a schedule, with **restore drills that prove your backup actually restores**, plus alerts and reports? That's the hosted service → **[backupdrill.com](https://backupdrill.com)**. This CLI is the DIY layer; the cloud adds scheduling, drills, alerting, and reports on top.
 
+🎥 Prefer watching? [Where do your backups actually go — explained in about a minute](https://backupdrill.com/guides/test-supabase-backup-restore#explainer-video).
+
 ## Why
 
 - Supabase's own database restore only brings back `storage.objects` **metadata**, not your actual Storage files.
@@ -146,6 +148,18 @@ backupdrill drill --verify-all-files # also checksum every Storage file, not jus
 
 Backups record your installed Postgres extensions in the manifest, and the drill pre-installs them in the sandbox before restoring — including switching to a pgvector-enabled sandbox image when your database uses `vector` columns.
 
+### Run your own checks against the restored copy
+
+The drill's structural checks (tables, rows, checksums) can't know what "working" means for *your* app — business invariants only have answers in your code. `--check-cmd` hands you the restored sandbox before it's destroyed:
+
+```bash
+backupdrill drill --check-cmd "npm run smoke"   # BACKUPDRILL_SANDBOX_URL points at the restored copy
+```
+
+Your command runs after all structural checks pass, with `BACKUPDRILL_SANDBOX_URL` set to the sandbox's connection string. Exit 0 means pass; the result shows up in the report as an `app checks` line, and a non-zero exit fails the drill (the report keeps structural and app-level failures clearly separate). Entirely optional — without the flag, nothing changes and the report has no `app checks` line. There's a 10-minute timeout (the whole process tree is killed), and `--keep` leaves the sandbox container running when a drill fails so you can inspect it — the report JSON then includes a `keptSandbox` object with the container id and connection string (`docker rm -f <id>` when done).
+
+**What this can and cannot verify, honestly:** `BACKUPDRILL_SANDBOX_URL` connects as the sandbox **superuser**, and superusers bypass row-level security — plus policies referencing Supabase-managed roles (`authenticated`, `anon`) are skipped during restore, since those roles don't exist outside the platform. So use `--check-cmd` for data and business invariants ("orders reference existing users", "the row count I care about is sane"). It is **not** an RLS behavior test — verifying RLS takes an authenticated client stack with real JWTs, which no restore sandbox can fake generically.
+
 When you actually need to recover, `restore` puts the database back into a target you name and pulls the Storage files down to a local folder:
 
 ```bash

package/dist/drill.d.ts

@@ -20,6 +20,11 @@ export interface DrillReport {
     restoreSeconds: number;
     restoredTableCount: number;
     restoredRowTotal: number;
+    /** --keep 且演练失败时:被保留的沙箱(供排查/脚本消费);其余情况不存在 */
+    keptSandbox?: {
+        containerId: string;
+        connString: string;
+    };
 }
 /** post-data 第二遍恢复的结果:用户对象失败 vs Supabase 托管对象的沙箱预期跳过。 */
 interface PostDataResult {
@@ -33,14 +38,31 @@ export declare function classifyPostDataErrors(stderr: string): PostDataResult;
  * 归档器致命错误等)绝不能谎报"全部恢复"——记为通用失败。
  */
 export declare function postDataResult(code: number | null, stderr: string): PostDataResult;
+export declare const APP_CHECK_TIMEOUT_MS: number;
+/**
+ * 语义层钩子:结构检查全绿后、销毁沙箱前,把沙箱连接串经 BACKUPDRILL_SANDBOX_URL
+ * 交给用户命令执行,校验数据/业务不变量(判据只存在于应用侧,引擎不解释命令输出,
+ * 只裁决退出码:0 = pass)。注意这不是 RLS 行为测试:连接身份是沙箱超级用户
+ * (绕过 RLS),且引用 Supabase 托管角色的策略在恢复时已被归类跳过。
+ * 子进程输出定向到 stderr:stdout 是 CLI 的机器可读 JSON 通道,不能被污染。
+ * 红线:托管 worker 绝不能把用户输入传到这里(任意代码执行);此钩子只属于
+ * 用户在自己机器上运行的 CLI(见 PRD §1.4 演练后应用自检钩子)。
+ */
+export declare function runAppCheck(command: string, connString: string, timeoutMs?: number): Promise<DrillCheck>;
 /**
  * 演练核心:把一份本地 dump 恢复进临时 Postgres 并对照 manifest 校验,然后销毁容器。
  * 与 S3 解耦,便于离线测试。`preChecks` 用于把下载阶段的校验(如归档校验和)带进报告。
  */
-export declare function drillDump(dumpPath: string, manifest: Manifest, snapshot: string, preChecks?: DrillCheck[]): Promise<DrillReport>;
+export declare function drillDump(dumpPath: string, manifest: Manifest, snapshot: string, preChecks?: DrillCheck[], opts?: {
+    appCheckCommand?: string;
+    keepSandboxOnFailure?: boolean;
+}): Promise<DrillReport>;
 /** 演练一份快照:从桶里下载→drillDump(含 Storage 校验)→报告。 */
 export declare function runDrill(config: BackupConfig, opts?: {
     snapshot?: string;
     verifyAllFiles?: boolean;
+    /** CLI 专用。红线:托管 worker 绝不能传入(在 worker 上执行用户命令 = RCE)。 */
+    appCheckCommand?: string;
+    keepSandboxOnFailure?: boolean;
 }): Promise<DrillReport>;
 export {};

package/dist/drill.js

@@ -308,14 +308,91 @@ async function verifyStorage(s3, config, manifest, verifyAll) {
             : `${mismatches.length} failed in ${scope}: ${mismatches.slice(0, 5).join(", ")}`,
     };
 }
+// ── 应用自检钩子(语义层)────────────────────────────────────────────
+// 挂死的 smoke test 不能永远挡住沙箱销毁;10 分钟对"冒烟"级检查绰绰有余
+export const APP_CHECK_TIMEOUT_MS = 10 * 60 * 1000;
+/**
+ * 语义层钩子:结构检查全绿后、销毁沙箱前,把沙箱连接串经 BACKUPDRILL_SANDBOX_URL
+ * 交给用户命令执行,校验数据/业务不变量(判据只存在于应用侧,引擎不解释命令输出,
+ * 只裁决退出码:0 = pass)。注意这不是 RLS 行为测试:连接身份是沙箱超级用户
+ * (绕过 RLS),且引用 Supabase 托管角色的策略在恢复时已被归类跳过。
+ * 子进程输出定向到 stderr:stdout 是 CLI 的机器可读 JSON 通道,不能被污染。
+ * 红线:托管 worker 绝不能把用户输入传到这里(任意代码执行);此钩子只属于
+ * 用户在自己机器上运行的 CLI(见 PRD §1.4 演练后应用自检钩子)。
+ */
+export function runAppCheck(command, connString, timeoutMs = APP_CHECK_TIMEOUT_MS) {
+    const started = Date.now();
+    return new Promise((resolve) => {
+        const proc = spawn(command, {
+            shell: true,
+            stdio: ["ignore", 2, 2],
+            env: { ...process.env, BACKUPDRILL_SANDBOX_URL: connString },
+            // 独立进程组:超时必须杀整棵进程树。只杀 shell 的话,npm/测试运行器这类
+            // 孙进程会在沙箱销毁后继续跑(xreview 抓出的资源泄漏)。
+            detached: true,
+        });
+        let timedOut = false;
+        const timer = setTimeout(() => {
+            timedOut = true;
+            try {
+                process.kill(-proc.pid, "SIGKILL"); // 负 pid = 杀整个进程组
+            }
+            catch {
+                proc.kill("SIGKILL");
+            }
+        }, timeoutMs);
+        proc.on("error", (error) => {
+            clearTimeout(timer);
+            resolve({
+                name: "app checks",
+                pass: false,
+                detail: `command failed to start: ${error.message}`,
+            });
+        });
+        proc.on("close", (code, signal) => {
+            clearTimeout(timer);
+            const seconds = Math.round((Date.now() - started) / 100) / 10;
+            if (timedOut) {
+                resolve({
+                    name: "app checks",
+                    pass: false,
+                    detail: `timed out after ${timeoutMs / 1000}s — process tree killed`,
+                });
+                return;
+            }
+            if (signal) {
+                resolve({
+                    name: "app checks",
+                    pass: false,
+                    detail: `terminated by ${signal} after ${seconds}s`,
+                });
+                return;
+            }
+            resolve({
+                name: "app checks",
+                pass: code === 0,
+                detail: code === 0
+                    ? `command exited 0 in ${seconds}s`
+                    : `command exited ${code} after ${seconds}s`,
+            });
+        });
+    });
+}
 // ── 主流程 ──────────────────────────────────────────────────────────
 /**
  * 演练核心:把一份本地 dump 恢复进临时 Postgres 并对照 manifest 校验,然后销毁容器。
  * 与 S3 解耦,便于离线测试。`preChecks` 用于把下载阶段的校验(如归档校验和)带进报告。
  */
-export async function drillDump(dumpPath, manifest, snapshot, preChecks = []) {
+export async function drillDump(dumpPath, manifest, snapshot, preChecks = [], opts = {}) {
+    // 空/纯空白命令 = 危险的假配置(CI 里变量没展开的典型形态):跑了会以 exit 0
+    // 假通过,忽略会让用户以为检查在跑。拒绝,且要在起沙箱之前拒绝。
+    const appCheckCommand = opts.appCheckCommand?.trim();
+    if (opts.appCheckCommand !== undefined && !appCheckCommand) {
+        throw new Error("--check-cmd is empty (did an env var fail to expand?) — refusing to report a check that would never run");
+    }
     const checks = [...preChecks];
     const pg = await startEphemeralPostgres(sandboxImage(manifest));
+    let pass = false; // 异常路径视为失败,供 finally 决定 --keep 是否保留沙箱
     try {
         // 旧 manifest(≤0.1.1)没有 extensions 字段 → 不装任何扩展,行为与从前一致
         const extensions = manifest.database.extensions ?? [];
@@ -363,18 +440,46 @@ export async function drillDump(dumpPath, manifest, snapshot, preChecks = []) {
         });
         const verify = await verifyRestored(pg.connString, manifest);
         checks.push(...verify.checks);
-        return {
+        // 语义层钩子:只在结构层全绿时才跑——结构已失败时再跑应用检查,只会把
+        // 一次失败报成两层失败,误导排查方向。没配置则不跑、报告里不出现该行。
+        if (appCheckCommand && checks.every((c) => c.pass)) {
+            log.step("Running app checks…");
+            checks.push(await runAppCheck(appCheckCommand, pg.connString));
+        }
+        pass = checks.every((c) => c.pass);
+        const report = {
             snapshot,
-            pass: checks.every((c) => c.pass),
+            pass,
             checks,
             restoreSeconds,
             restoredTableCount: verify.tableCount,
             restoredRowTotal: verify.rowTotal,
         };
+        if (opts.keepSandboxOnFailure && !pass) {
+            // 写进报告让 --keep 可被脚本消费(拿连接串排查),不只靠人眼看日志
+            report.keptSandbox = { containerId: pg.containerId, connString: pg.connString };
+        }
+        return report;
+    }
+    catch (error) {
+        // 异常路径(恢复/校验抛出)没有报告对象可挂 keptSandbox;把沙箱坐标并入
+        // 错误信息,让脚本和人都拿得到被保留容器的清理线索
+        if (opts.keepSandboxOnFailure) {
+            error.message +=
+                ` [sandbox kept: ${pg.connString} — remove with: docker rm -f ${pg.containerId.slice(0, 12)}]`;
+        }
+        throw error;
     }
     finally {
-        log.step("Tearing down ephemeral Postgres…");
-        await execFileAsync("docker", ["rm", "-f", pg.containerId]).catch(() => { });
+        if (opts.keepSandboxOnFailure && !pass) {
+            // --rm 容器不 docker rm 就一直活着;用户排查完 stop/rm 时 --rm 自动清理
+            log.warn(`--keep: sandbox left running for inspection — ${pg.connString} ` +
+                `(remove with: docker rm -f ${pg.containerId.slice(0, 12)})`);
+        }
+        else {
+            log.step("Tearing down ephemeral Postgres…");
+            await execFileAsync("docker", ["rm", "-f", pg.containerId]).catch(() => { });
+        }
     }
 }
 /** 演练一份快照:从桶里下载→drillDump(含 Storage 校验)→报告。 */
@@ -415,7 +520,10 @@ export async function runDrill(config, opts = {}) {
             log.step("Verifying Storage files…");
             preChecks.push(await verifyStorage(s3, config, manifest, opts.verifyAllFiles ?? false));
         }
-        return await drillDump(dumpPath, manifest, snapshot, preChecks);
+        return await drillDump(dumpPath, manifest, snapshot, preChecks, {
+            appCheckCommand: opts.appCheckCommand,
+            keepSandboxOnFailure: opts.keepSandboxOnFailure,
+        });
     }
     finally {
         await rm(workdir, { recursive: true, force: true }).catch(() => { });

package/dist/index.js

@@ -75,8 +75,17 @@ program
     .option("--prefix <prefix>", "key prefix inside the bucket (default: backupdrill)")
     .option("--project-name <name>", "project name used in the object key")
     .option("--verify-all-files", "checksum every Storage file, not just a sample")
+    .option("--check-cmd <command>", "after structural checks pass, run your own smoke test against the restored sandbox " +
+    "(connection string in BACKUPDRILL_SANDBOX_URL; exit 0 = pass, reported as 'app checks'). " +
+    "Note: connects as the sandbox superuser, so RLS policies are NOT enforced — " +
+    "verify data and business invariants here, not RLS behavior")
+    .option("--keep", "if the drill fails, keep the sandbox container running for inspection")
     .action(async (opts) => {
     try {
+        if (opts.checkCmd !== undefined && !String(opts.checkCmd).trim()) {
+            throw new Error("--check-cmd is empty (did an env var fail to expand?) — refusing to run a drill " +
+                "that would report a check that never executes");
+        }
         const config = await loadConfig({
             configPath: opts.config,
             overrides: {
@@ -94,6 +103,8 @@ program
         const report = await runDrill(config, {
             snapshot: opts.snapshot,
             verifyAllFiles: opts.verifyAllFiles,
+            appCheckCommand: opts.checkCmd,
+            keepSandboxOnFailure: opts.keep,
         });
         console.error("");
         for (const c of report.checks) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "backupdrill",
-  "version": "0.1.3",
+  "version": "0.2.1",
   "description": "Open-source CLI to back up a Supabase project — Postgres database and Storage files — to your own S3/R2/B2 bucket, with a checksummed manifest.",
   "type": "module",
   "bin": {