backupdrill 0.2.0 → 0.2.1

package/README.md

@@ -150,13 +150,15 @@ Backups record your installed Postgres extensions in the manifest, and the drill
 
 ### 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:
+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, and `--keep` leaves the sandbox container running when a drill fails so you can inspect it (`docker rm -f <id>` when done).
+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:
 

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 {
@@ -36,8 +41,9 @@ export declare function postDataResult(code: number | null, stderr: string): Pos
 export declare const APP_CHECK_TIMEOUT_MS: number;
 /**
  * 语义层钩子:结构检查全绿后、销毁沙箱前,把沙箱连接串经 BACKUPDRILL_SANDBOX_URL
- * 交给用户命令执行(RLS 行为、业务流可用性——判据只存在于应用侧,引擎不解释
- * 命令输出,只裁决退出码:0 = pass)。
+ * 交给用户命令执行,校验数据/业务不变量(判据只存在于应用侧,引擎不解释命令输出,
+ * 只裁决退出码:0 = pass)。注意这不是 RLS 行为测试:连接身份是沙箱超级用户
+ * (绕过 RLS),且引用 Supabase 托管角色的策略在恢复时已被归类跳过。
  * 子进程输出定向到 stderr:stdout 是 CLI 的机器可读 JSON 通道,不能被污染。
  * 红线:托管 worker 绝不能把用户输入传到这里(任意代码执行);此钩子只属于
  * 用户在自己机器上运行的 CLI(见 PRD §1.4 演练后应用自检钩子)。

package/dist/drill.js

@@ -313,8 +313,9 @@ async function verifyStorage(s3, config, manifest, verifyAll) {
 export const APP_CHECK_TIMEOUT_MS = 10 * 60 * 1000;
 /**
  * 语义层钩子:结构检查全绿后、销毁沙箱前,把沙箱连接串经 BACKUPDRILL_SANDBOX_URL
- * 交给用户命令执行(RLS 行为、业务流可用性——判据只存在于应用侧,引擎不解释
- * 命令输出,只裁决退出码:0 = pass)。
+ * 交给用户命令执行,校验数据/业务不变量(判据只存在于应用侧,引擎不解释命令输出,
+ * 只裁决退出码:0 = pass)。注意这不是 RLS 行为测试:连接身份是沙箱超级用户
+ * (绕过 RLS),且引用 Supabase 托管角色的策略在恢复时已被归类跳过。
  * 子进程输出定向到 stderr:stdout 是 CLI 的机器可读 JSON 通道,不能被污染。
  * 红线:托管 worker 绝不能把用户输入传到这里(任意代码执行);此钩子只属于
  * 用户在自己机器上运行的 CLI(见 PRD §1.4 演练后应用自检钩子)。
@@ -326,10 +327,22 @@ export function runAppCheck(command, connString, timeoutMs = APP_CHECK_TIMEOUT_M
             shell: true,
             stdio: ["ignore", 2, 2],
             env: { ...process.env, BACKUPDRILL_SANDBOX_URL: connString },
-            timeout: timeoutMs,
-            killSignal: "SIGKILL",
+            // 独立进程组:超时必须杀整棵进程树。只杀 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,
@@ -337,12 +350,21 @@ export function runAppCheck(command, connString, timeoutMs = APP_CHECK_TIMEOUT_M
             });
         });
         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 (timeout ${timeoutMs / 1000}s)`,
+                    detail: `terminated by ${signal} after ${seconds}s`,
                 });
                 return;
             }
@@ -362,6 +384,12 @@ export function runAppCheck(command, connString, timeoutMs = APP_CHECK_TIMEOUT_M
  * 与 S3 解耦,便于离线测试。`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 是否保留沙箱
@@ -414,12 +442,12 @@ export async function drillDump(dumpPath, manifest, snapshot, preChecks = [], op
         checks.push(...verify.checks);
         // 语义层钩子:只在结构层全绿时才跑——结构已失败时再跑应用检查,只会把
         // 一次失败报成两层失败,误导排查方向。没配置则不跑、报告里不出现该行。
-        if (opts.appCheckCommand && checks.every((c) => c.pass)) {
+        if (appCheckCommand && checks.every((c) => c.pass)) {
             log.step("Running app checks…");
-            checks.push(await runAppCheck(opts.appCheckCommand, pg.connString));
+            checks.push(await runAppCheck(appCheckCommand, pg.connString));
         }
         pass = checks.every((c) => c.pass);
-        return {
+        const report = {
             snapshot,
             pass,
             checks,
@@ -427,6 +455,20 @@ export async function drillDump(dumpPath, manifest, snapshot, preChecks = [], op
             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 {
         if (opts.keepSandboxOnFailure && !pass) {

package/dist/index.js

@@ -76,10 +76,16 @@ program
     .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')")
+    "(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: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "backupdrill",
-  "version": "0.2.0",
+  "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": {