backupdrill 0.1.3 → 0.2.0

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,16 @@ 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 — RLS behavior and business workflows 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, and `--keep` leaves the sandbox container running when a drill fails so you can inspect it (`docker rm -f <id>` when done).
+
 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

@@ -33,14 +33,30 @@ 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
+ * 交给用户命令执行(RLS 行为、业务流可用性——判据只存在于应用侧,引擎不解释
+ * 命令输出,只裁决退出码:0 = pass)。
+ * 子进程输出定向到 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,63 @@ 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
+ * 交给用户命令执行(RLS 行为、业务流可用性——判据只存在于应用侧,引擎不解释
+ * 命令输出,只裁决退出码:0 = pass)。
+ * 子进程输出定向到 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 },
+            timeout: timeoutMs,
+            killSignal: "SIGKILL",
+        });
+        proc.on("error", (error) => {
+            resolve({
+                name: "app checks",
+                pass: false,
+                detail: `command failed to start: ${error.message}`,
+            });
+        });
+        proc.on("close", (code, signal) => {
+            const seconds = Math.round((Date.now() - started) / 100) / 10;
+            if (signal) {
+                resolve({
+                    name: "app checks",
+                    pass: false,
+                    detail: `terminated by ${signal} after ${seconds}s (timeout ${timeoutMs / 1000}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 = {}) {
     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,9 +412,16 @@ export async function drillDump(dumpPath, manifest, snapshot, preChecks = []) {
         });
         const verify = await verifyRestored(pg.connString, manifest);
         checks.push(...verify.checks);
+        // 语义层钩子:只在结构层全绿时才跑——结构已失败时再跑应用检查,只会把
+        // 一次失败报成两层失败,误导排查方向。没配置则不跑、报告里不出现该行。
+        if (opts.appCheckCommand && checks.every((c) => c.pass)) {
+            log.step("Running app checks…");
+            checks.push(await runAppCheck(opts.appCheckCommand, pg.connString));
+        }
+        pass = checks.every((c) => c.pass);
         return {
             snapshot,
-            pass: checks.every((c) => c.pass),
+            pass,
             checks,
             restoreSeconds,
             restoredTableCount: verify.tableCount,
@@ -373,8 +429,15 @@ export async function drillDump(dumpPath, manifest, snapshot, preChecks = []) {
         };
     }
     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 +478,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,6 +75,9 @@ 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')")
+    .option("--keep", "if the drill fails, keep the sandbox container running for inspection")
     .action(async (opts) => {
     try {
         const config = await loadConfig({
@@ -94,6 +97,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.0",
   "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": {