backupdrill 2.4.0 → 2.6.0

package/dist/exporter.js

@@ -0,0 +1,305 @@
+import { createServer } from "node:http";
+import { performance } from "node:perf_hooks";
+import { GetObjectCommand, ListObjectsV2Command } from "@aws-sdk/client-s3";
+import { requireBucket } from "./config.js";
+import { withDeadline } from "./deadline.js";
+import { drillRecordsPrefix, parseDrillRecord, parseDrillRecordName } from "./drill-record.js";
+import { log } from "./log.js";
+import { parseManifest } from "./manifest.js";
+import { listSnapshotPrefixes, targetClient } from "./snapshots.js";
+import { TOOL_VERSION } from "./version.js";
+/**
+ * `backupdrill exporter`:按 Prometheus 文本格式暴露桶里备份与演练的状态。
+ * 规矩照 https://prometheus.io/docs/instrumenting/writing_exporters/ :
+ *  - 每次抓取现读桶,不按自己的定时器预取,不报旧值;
+ *  - 读不了桶时照样回 200,backupdrill_up 为 0,其余业务指标不出(半套数据比没有更误导);
+ *  - 指标不带标签(一个 exporter 进程只看一个项目,项目名属于 Prometheus 那边的 target 标签),
+ *    连接串、key、桶名一律不进指标。
+ */
+/** 10059:Prometheus wiki「Default port allocations」上 10058 之后的第一个空位(2026-10-20 查)。 */
+export const DEFAULT_EXPORTER_PORT = 10059;
+/** 没有 Prometheus 超时头时(手动 curl)给读桶留的时间,与 Prometheus 默认 scrape_timeout 一致 */
+const DEFAULT_SCRAPE_TIMEOUT_MS = 10_000;
+const MAX_SCRAPE_TIMEOUT_MS = 5 * 60_000;
+/**
+ * 记录里的时间最多可以比这台机器的时钟快多少。备份、演练、exporter 可能在不同机器上跑,
+ * 几分钟的时钟差是正常的;再多就不可信。
+ */
+const CLOCK_SKEW_TOLERANCE_MS = 10 * 60_000;
+function httpStatusOf(error) {
+    return error.$metadata?.httpStatusCode;
+}
+async function readObject(s3, bucket, key, abortSignal, ifNoneMatch) {
+    try {
+        const res = await s3.send(new GetObjectCommand({ Bucket: bucket, Key: key, IfNoneMatch: ifNoneMatch }), { abortSignal });
+        return { status: "ok", text: await res.Body.transformToString(), etag: res.ETag };
+    }
+    catch (error) {
+        const status = httpStatusOf(error);
+        if (status === 304)
+            return { status: "not-modified" };
+        if (status === 404 || error.name === "NoSuchKey")
+            return { status: "missing" };
+        throw error;
+    }
+}
+function summarize(text, key) {
+    const manifest = parseManifest(text);
+    // parseManifest 不校验 createdAt(演练和恢复用不到),这里要拿它当备份时间,自己把关
+    const createdAt = Date.parse(manifest.createdAt);
+    if (!Number.isFinite(createdAt)) {
+        throw new Error(`${key} is malformed: createdAt`);
+    }
+    assertNotInFuture(createdAt, key, "createdAt");
+    const summary = {
+        createdAt,
+        dumpBytes: manifest.dump.bytes,
+        storageFiles: manifest.storage?.fileCount ?? 0,
+        storageBytes: manifest.storage?.totalBytes ?? 0,
+        tables: manifest.database.tableCount,
+        estimatedRows: manifest.database.estimatedRowTotal,
+    };
+    // 这些数会原样写进指标文本。parseManifest 只管演练和恢复要用的字段(estimatedRowTotal 就不查),
+    // 一个字符串或带换行的值能让整次抓取在 Prometheus 那边解析失败,甚至塞进假样本
+    for (const [field, value] of Object.entries(summary)) {
+        if (typeof value !== "number" || !Number.isFinite(value) || value < 0) {
+            throw new Error(`${key} is malformed: ${field} is not a non-negative number`);
+        }
+    }
+    return summary;
+}
+/**
+ * 时间在将来的记录会让"距今多久"的告警永远不响(time() - 将来的时间是负数)。
+ * 报成读桶失败(up=0),让人去看是记录被改了还是哪台机器的时钟不对。
+ */
+function assertNotInFuture(at, key, field) {
+    if (at > Date.now() + CLOCK_SKEW_TOLERANCE_MS) {
+        throw new Error(`${key} has ${field} ${new Date(at).toISOString()}, more than 10 minutes in the future ` +
+            `(check the clock on the machine that wrote it)`);
+    }
+}
+/** <prefix>/<project>.drills/ 下的对象名,分页列完 */
+async function listDrillRecordNames(s3, bucket, prefix, abortSignal) {
+    const names = [];
+    let token;
+    do {
+        const res = await s3.send(new ListObjectsV2Command({ Bucket: bucket, Prefix: prefix, Delimiter: "/", ContinuationToken: token }), { abortSignal });
+        for (const object of res.Contents ?? []) {
+            if (object.Key)
+                names.push(object.Key.slice(prefix.length));
+        }
+        token = res.IsTruncated ? res.NextContinuationToken : undefined;
+    } while (token);
+    return names;
+}
+/**
+ * 最近一次演练和最近一次通过的演练。结束时间和结论都在文件名里,列一下目录就够;
+ * 只为了恢复用时读一次通过的那份。时间在将来的记录(写它的机器时钟快了,或被改过)跳过并警告:
+ * 它会一直排在最前面,让"距今多久"的告警算出负数。记录从不删除,所以不能让它把读桶整个弄成失败。
+ */
+async function readDrills(s3, config, abortSignal) {
+    const bucket = requireBucket(config).bucket;
+    const prefix = drillRecordsPrefix(config);
+    const now = Date.now();
+    let lastDrill = null;
+    let lastPassed = null;
+    for (const name of await listDrillRecordNames(s3, bucket, prefix, abortSignal)) {
+        const parsed = parseDrillRecordName(name);
+        if (!parsed)
+            continue;
+        if (parsed.finishedAt > now + CLOCK_SKEW_TOLERANCE_MS) {
+            log.warn(`Ignoring ${prefix}${name}: it is dated more than 10 minutes in the future (check the clock on the machine that ran the drill).`);
+            continue;
+        }
+        if (!lastDrill || parsed.finishedAt > lastDrill.finishedAt)
+            lastDrill = { ...parsed, name };
+        if (parsed.pass && (!lastPassed || parsed.finishedAt > lastPassed.finishedAt)) {
+            lastPassed = { finishedAt: parsed.finishedAt, name };
+        }
+    }
+    let lastPassedDrill = null;
+    if (lastPassed) {
+        const key = prefix + lastPassed.name;
+        const read = await readObject(s3, bucket, key, abortSignal);
+        // 刚列出来就不见了:生命周期规则正好删了它,或者有人手动删了。按读失败处理,下次抓取再看
+        if (read.status !== "ok")
+            throw new Error(`${key} disappeared while it was being read`);
+        const record = parseDrillRecord(read.text, key);
+        if (!record.pass || Date.parse(record.finishedAt) !== lastPassed.finishedAt) {
+            throw new Error(`${key} is malformed: its content does not match its name`);
+        }
+        lastPassedDrill = { finishedAt: lastPassed.finishedAt, restoreSeconds: record.restoreSeconds };
+    }
+    return {
+        lastDrill: lastDrill ? { finishedAt: lastDrill.finishedAt, pass: lastDrill.pass } : null,
+        lastPassedDrill,
+    };
+}
+/**
+ * 读桶的函数。每次调用都现读;唯一记住的是最新一份 manifest 的 ETag 和摘要:
+ * 下次带 If-None-Match 去问,没变就是 304、不传正文。快照写完就不再改,而一份 manifest 列着
+ * 每个 Storage 文件,可能有几十 MB,每 30 秒整份下载一遍会变成用户账单上的流量。
+ */
+export function createBucketReader(s3, config) {
+    const storage = requireBucket(config);
+    const root = `${storage.prefix}/${config.projectName}/`;
+    let remembered = null;
+    return async (abortSignal) => {
+        const prefixes = (await listSnapshotPrefixes(s3, storage.bucket, root, abortSignal))
+            .sort()
+            .reverse();
+        // manifest 是快照的完成标记,最后写。目录在、manifest 不在 = 备份还在跑或中途失败了,
+        // 往前找上一份完整的。不设上限:找太久就撞上抓取超时,报 up=0,这本身就该有人去看
+        let latest = null;
+        for (const prefix of prefixes) {
+            const key = `${prefix}manifest.json`;
+            const known = remembered?.key === key ? remembered : null;
+            const read = await readObject(s3, storage.bucket, key, abortSignal, known?.etag);
+            if (read.status === "missing")
+                continue;
+            if (read.status === "not-modified" && known) {
+                // 内容没变,但"是不是在将来"取决于现在几点:本机时钟被校正回来之后要重新判断
+                assertNotInFuture(known.summary.createdAt, key, "createdAt");
+                latest = known.summary;
+            }
+            else if (read.status === "ok") {
+                latest = summarize(read.text, key);
+                remembered = read.etag ? { key, etag: read.etag, summary: latest } : null;
+            }
+            else {
+                // 没带 If-None-Match 却收到 304:对端行为不对,别猜
+                throw new Error(`unexpected 304 Not Modified for ${key}`);
+            }
+            break;
+        }
+        const drills = await readDrills(s3, config, abortSignal);
+        return { snapshots: prefixes.length, latest, ...drills };
+    };
+}
+const escapeHelp = (s) => s.replace(/\\/g, "\\\\").replace(/\n/g, "\\n");
+const escapeLabel = (s) => s.replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/\n/g, "\\n");
+const seconds = (ms) => ms / 1000;
+function gauge(name, help, value) {
+    return value === null ? null : { name, help, samples: [{ value }] };
+}
+/** state 为 null = 这次没读成桶。全部是 gauge:都是"某一刻的状态",没有一个会只增不减。 */
+export function renderMetrics(state, scrapeSeconds) {
+    const latest = state?.latest ?? null;
+    const lastDrill = state?.lastDrill ?? null;
+    const lastPassed = state?.lastPassedDrill ?? null;
+    const families = [
+        gauge("backupdrill_up", "Whether the last read of the backup bucket worked (1) or failed (0).", state ? 1 : 0),
+        gauge("backupdrill_scrape_duration_seconds", "How long this scrape took to read the backup bucket.", scrapeSeconds),
+        {
+            name: "backupdrill_build_info",
+            help: "The backupdrill CLI version running this exporter. Always 1.",
+            samples: [{ labels: { version: TOOL_VERSION }, value: 1 }],
+        },
+    ];
+    if (state) {
+        families.push(gauge("backupdrill_snapshots", "Snapshot folders under <prefix>/<project>/, including ones without a manifest.json yet.", state.snapshots), gauge("backupdrill_backup_last_success_timestamp_seconds", "When the newest complete snapshot finished (its manifest.json createdAt), as a Unix timestamp. 0 if there is none.", latest ? seconds(latest.createdAt) : 0), gauge("backupdrill_latest_snapshot_dump_bytes", "Size of the database dump (pg_dump custom format) in the newest complete snapshot.", latest?.dumpBytes ?? null), gauge("backupdrill_latest_snapshot_storage_files", "Supabase Storage files in the newest complete snapshot. 0 for a database-only backup.", latest?.storageFiles ?? null), gauge("backupdrill_latest_snapshot_storage_bytes", "Total size of the Supabase Storage files in the newest complete snapshot.", latest?.storageBytes ?? null), gauge("backupdrill_latest_snapshot_tables", "Tables, partitioned tables and materialized views captured in the newest complete snapshot.", latest?.tables ?? null), gauge("backupdrill_latest_snapshot_estimated_rows", "Row count of the newest complete snapshot, estimated from Postgres statistics (n_live_tup) at backup time.", latest?.estimatedRows ?? null), gauge("backupdrill_drill_last_run_timestamp_seconds", "When the last drill recorded with --record finished, passed or not, as a Unix timestamp. 0 if none is recorded.", lastDrill ? seconds(lastDrill.finishedAt) : 0), gauge("backupdrill_drill_last_run_passed", "Whether the last recorded drill passed (1) or not (0).", lastDrill ? (lastDrill.pass ? 1 : 0) : null), gauge("backupdrill_drill_last_success_timestamp_seconds", "When the last passing drill recorded with --record finished, as a Unix timestamp. 0 if none is recorded.", lastPassed ? seconds(lastPassed.finishedAt) : 0), gauge("backupdrill_drill_last_success_restore_duration_seconds", "How long the database restore took in the last passing recorded drill.", lastPassed?.restoreSeconds ?? null));
+    }
+    const lines = [];
+    for (const family of families) {
+        if (!family)
+            continue;
+        lines.push(`# HELP ${family.name} ${escapeHelp(family.help)}`, `# TYPE ${family.name} gauge`);
+        for (const sample of family.samples) {
+            const labels = sample.labels
+                ? `{${Object.entries(sample.labels)
+                    .map(([k, v]) => `${k}="${escapeLabel(v)}"`)
+                    .join(",")}}`
+                : "";
+            lines.push(`${family.name}${labels} ${sample.value}`);
+        }
+    }
+    return lines.join("\n") + "\n";
+}
+/**
+ * 读桶的时限跟着 Prometheus 走:它在请求头里告诉我们这次抓取最多等多久,留半秒余量,
+ * 好让超时的这次还能回一个 up=0,而不是被 Prometheus 当成 exporter 挂了。
+ */
+export function scrapeTimeoutMs(header) {
+    const value = Number(Array.isArray(header) ? header[0] : header);
+    if (!Number.isFinite(value) || value <= 0)
+        return DEFAULT_SCRAPE_TIMEOUT_MS;
+    // AbortSignal.timeout 只收整数毫秒(1.1 秒算出来是 600.0000000000001,直接抛错);
+    // 上限防一个离谱的头把读桶拖成几小时
+    return Math.min(Math.max(1, Math.floor(Math.max(value - 0.5, value / 2) * 1000)), MAX_SCRAPE_TIMEOUT_MS);
+}
+const LANDING_PAGE = `<!doctype html>
+<html lang="en">
+<head><meta charset="utf-8"><title>backupdrill exporter</title></head>
+<body>
+<h1>backupdrill exporter</h1>
+<p>Version ${TOOL_VERSION}. Prometheus metrics for the backups and recorded restore drills in one project's bucket.</p>
+<p><a href="/metrics">Metrics</a></p>
+</body>
+</html>
+`;
+export function createExporterServer(read) {
+    return createServer((req, res) => {
+        // 处理函数是 async:里面任何没接住的异常都会变成未处理的 rejection,把整个进程带走。
+        // 端口对 Prometheus 开着,一个怪请求不能让 exporter 停掉
+        handle(req, res, read).catch((error) => {
+            log.warn(`Request failed: ${error.message}`);
+            if (!res.headersSent)
+                res.writeHead(500, { "Content-Type": "text/plain; charset=utf-8" });
+            res.end();
+        });
+    });
+}
+async function handle(req, res, read) {
+    // 只要路径,不用 new URL:"GET // HTTP/1.1" 这种请求行会让它抛 Invalid URL
+    const path = (req.url ?? "/").split("?")[0];
+    if (req.method !== "GET") {
+        res.writeHead(405, { Allow: "GET", "Content-Type": "text/plain; charset=utf-8" });
+        res.end("Method Not Allowed\n");
+        return;
+    }
+    if (path === "/") {
+        res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
+        res.end(LANDING_PAGE);
+        return;
+    }
+    if (path !== "/metrics") {
+        res.writeHead(404, { "Content-Type": "text/plain; charset=utf-8" });
+        res.end("Not Found\n");
+        return;
+    }
+    const started = performance.now();
+    const timeoutMs = scrapeTimeoutMs(req.headers["x-prometheus-scrape-timeout-seconds"]);
+    let state = null;
+    try {
+        state = await withDeadline(read, timeoutMs);
+    }
+    catch (error) {
+        const e = error;
+        const reason = e.name === "TimeoutError" || e.name === "AbortError"
+            ? `timed out after ${(timeoutMs / 1000).toFixed(1)}s`
+            : e.message;
+        log.warn(`Could not read the backup bucket: ${reason}`);
+    }
+    // 微秒够用,免得样本里出现 0.021267749999999978 这种浮点尾巴
+    const body = renderMetrics(state, Number(((performance.now() - started) / 1000).toFixed(6)));
+    res.writeHead(200, { "Content-Type": "text/plain; version=0.0.4; charset=utf-8" });
+    res.end(body);
+}
+/** CLI 的 `backupdrill exporter`:起 HTTP 服务,直到进程被停掉。 */
+export async function startExporter(config, opts) {
+    const storage = requireBucket(config);
+    const server = createExporterServer(createBucketReader(targetClient(config), config));
+    await new Promise((resolve, reject) => {
+        server.once("error", reject);
+        server.listen(opts.port, opts.host, () => {
+            server.off("error", reject);
+            resolve();
+        });
+    });
+    // 报实际绑定的端口:--port 0 时由系统挑
+    const port = server.address().port;
+    const shownHost = opts.host.includes(":") ? `[${opts.host}]` : opts.host;
+    log.ok(`Serving metrics for s3://${storage.bucket}/${storage.prefix}/${config.projectName}/ ` +
+        `at http://${shownHost}:${port}/metrics`);
+    return server;
+}

package/dist/index.js

@@ -1,12 +1,15 @@
 #!/usr/bin/env node
 import { Command } from "commander";
-import { loadConfig } from "./config.js";
+import { loadConfig, resolvePingUrl } from "./config.js";
+import { backupSummary, createPinger, drillOutcome, pingMessageOf, sensitiveValuesOf } from "./ping.js";
 import { runBackup } from "./backup.js";
 import { runEstimate } from "./estimate.js";
 import { runDrill } from "./drill.js";
 import { createInterface } from "node:readline/promises";
 import { Writable } from "node:stream";
 import { runRestore, NO_SOURCE_DATABASE } from "./restore.js";
+import { recordDrillOutcome } from "./drill-record.js";
+import { DEFAULT_EXPORTER_PORT, startExporter } from "./exporter.js";
 /** 隐藏式秘密输入(PRD §5.3.1):终端不回显;无 TTY(CI/脚本)时明确要求走环境变量。 */
 async function promptSecret(label) {
     if (!process.stdin.isTTY) {
@@ -37,6 +40,10 @@ const EGRESS_PRICING = {
     pro: { planLabel: "Pro", includedGb: 250, pricePerGb: 0.09, hardCap: false },
     team: { planLabel: "Team", includedGb: 250, pricePerGb: 0.09, hardCap: false },
 };
+// backup 和 drill 共用:按 Healthchecks.io 的约定报告开始、成功、失败
+const PING_FLAG = "--ping-url <url>";
+const PING_HELP = "Healthchecks.io ping URL (or BACKUPDRILL_PING_URL): pings <url>/start, then <url> on " +
+    "success or <url>/fail on failure. A ping that fails only prints a warning";
 const program = new Command();
 program
     .name("backupdrill")
@@ -55,9 +62,13 @@ program
     .option("--endpoint <url>", "S3-compatible endpoint (required for R2/B2; omit for AWS S3)")
     .option("--region <region>", "bucket region (default: auto)")
     .option("--prefix <prefix>", "key prefix inside the bucket (default: backupdrill)")
+    .option(PING_FLAG, PING_HELP)
     .action(async (opts) => {
+    const ping = createPinger(await resolvePingUrl({ flag: opts.pingUrl, configPath: opts.config }));
+    await ping.start();
+    let config;
     try {
-        const config = await loadConfig({
+        config = await loadConfig({
             configPath: opts.config,
             overrides: {
                 databaseUrl: opts.databaseUrl,
@@ -79,10 +90,13 @@ program
             `${storageNote}.`);
         // stdout 输出机器可读结果,便于在 CI / GitHub Action 里消费
         process.stdout.write(JSON.stringify({ ok: true, manifest }) + "\n");
+        await ping.success(backupSummary(manifest));
     }
     catch (error) {
-        log.error(error.message);
+        const message = error.message;
+        log.error(message);
         process.exitCode = 1;
+        await ping.fail(`backupdrill ${TOOL_VERSION}: backup failed. ${pingMessageOf(error)}`, sensitiveValuesOf(config, opts.databaseUrl));
     }
 });
 program
@@ -101,13 +115,20 @@ program
     "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")
+    .option(PING_FLAG, PING_HELP)
+    .option("--record", "write the outcome as a small JSON file in <prefix>/<project>.drills/, where " +
+    "`backupdrill exporter` reads it. Needs write access to the bucket")
     .action(async (opts) => {
+    const ping = createPinger(await resolvePingUrl({ flag: opts.pingUrl, configPath: opts.config }));
+    await ping.start();
+    // config 放在 try 外面:出错时 /fail 要用它抹敏感值,--record 要用它记一笔"没通过"
+    let config;
     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({
+        config = await loadConfig({
             configPath: opts.config,
             overrides: {
                 projectName: opts.projectName,
@@ -136,12 +157,25 @@ program
             `${report.restoredTableCount} tables / ${report.restoredRowTotal.toLocaleString()} rows ` +
             `restored in ${report.restoreSeconds}s`);
         process.stdout.write(JSON.stringify({ ok: report.pass, report }) + "\n");
-        if (!report.pass)
+        if (opts.record)
+            await recordDrillOutcome(config, report);
+        const outcome = drillOutcome(report);
+        if (outcome.pass) {
+            await ping.success(outcome.text);
+        }
+        else {
             process.exitCode = 1;
+            await ping.fail(outcome.text, sensitiveValuesOf(config));
+        }
     }
     catch (error) {
-        log.error(error.message);
+        const message = error.message;
+        log.error(message);
         process.exitCode = 1;
+        // 没装 Docker、桶里没快照这类中途失败也算一次没通过的演练;配置都没读成就无处可记
+        if (opts.record && config)
+            await recordDrillOutcome(config, null);
+        await ping.fail(`backupdrill ${TOOL_VERSION}: drill failed. ${pingMessageOf(error)}`, sensitiveValuesOf(config));
     }
 });
 program
@@ -273,6 +307,44 @@ program
         process.exitCode = 1;
     }
 });
+program
+    .command("exporter")
+    .description("Serve Prometheus metrics about the backups (and drills run with --record) in your bucket")
+    .option("-c, --config <path>", "path to a JSON config file", "backupdrill.config.json")
+    .option("--bucket <name>", "bucket the backups live in")
+    .option("--endpoint <url>", "S3-compatible endpoint (for R2/B2)")
+    .option("--region <region>", "bucket region")
+    .option("--prefix <prefix>", "key prefix inside the bucket (default: backupdrill)")
+    .option("--project-name <name>", "project name used in the object key")
+    .option("--host <address>", "address to listen on; use 0.0.0.0 when Prometheus runs on another machine", "127.0.0.1")
+    .option("--port <port>", "port to listen on", String(DEFAULT_EXPORTER_PORT))
+    .action(async (opts) => {
+    try {
+        const port = Number(opts.port);
+        if (!Number.isInteger(port) || port < 1 || port > 65535) {
+            throw new Error(`--port must be a whole number from 1 to 65535, got "${opts.port}"`);
+        }
+        const config = await loadConfig({
+            configPath: opts.config,
+            overrides: {
+                projectName: opts.projectName,
+                // exporter 只读桶,不连源库;给 databaseUrl 占位以通过校验
+                databaseUrl: "postgresql://unused",
+                storage: {
+                    bucket: opts.bucket,
+                    endpoint: opts.endpoint,
+                    region: opts.region,
+                    prefix: opts.prefix,
+                },
+            },
+        });
+        await startExporter(config, { host: opts.host, port });
+    }
+    catch (error) {
+        log.error(error.message);
+        process.exitCode = 1;
+    }
+});
 program.parseAsync().catch((error) => {
     log.error(error.message);
     process.exitCode = 1;

package/dist/ping.d.ts

@@ -0,0 +1,31 @@
+import type { BackupConfig } from "./config.js";
+import type { DrillReport } from "./drill.js";
+import type { Manifest } from "./manifest.js";
+export interface Pinger {
+    start(): Promise<void>;
+    success(summary: string): Promise<void>;
+    /** sensitive:这次运行用到的连接串、密钥等,发出去之前从 reason 里抹掉 */
+    fail(reason: string, sensitive?: string[]): Promise<void>;
+}
+export declare function createPinger(rawUrl: string | undefined, opts?: {
+    timeoutMs?: number;
+    attempts?: number;
+    retryDelayMs?: number;
+}): Pinger;
+/** backup 成功时发给监控的一行。快照名取对象键里的目录名(和 drill --snapshot 认的是同一个) */
+export declare function backupSummary(manifest: Manifest): string;
+/** drill 跑完(没抛错)后发哪种 ping、带什么:通过 = 成功;没通过 = 失败,列出没过的检查 */
+export declare function drillOutcome(report: DrillReport): {
+    pass: boolean;
+    text: string;
+};
+/** 报错可以自带一句发给监控用的说法(pingMessage),比如不能复述配置文件原文的那种 */
+export declare function pingMessageOf(error: unknown): string;
+/**
+ * 失败原因发出去之前抹掉连接信息。先按值抹(这次运行确实用到的连接串、密码、主机、密钥),
+ * 再按形状兜底:pg / S3 的报错会带主机名、IP、整条连接串,配置文件解析失败时 JSON.parse
+ * 的报错还会带一截文件原文,这些都不是事先知道的值。
+ */
+export declare function scrubForPing(text: string, sensitive: string[]): string;
+/** 这次运行里不该出现在 ping 里的值:连接串、密码、主机、项目 ref、桶和 Storage 的密钥。 */
+export declare function sensitiveValuesOf(config: BackupConfig | undefined, extraDatabaseUrl?: string): string[];