@marinoscar/platform-api 0.0.0-stage → 0.1.0-next.10

package/dist/db-backup/db-backup-runner.service.d.ts

@@ -0,0 +1,816 @@
+import { Readable } from 'node:stream';
+import { ConfigService } from '@nestjs/config';
+import type { DbBackupRunResult } from '@marinoscar/platform-contract/db-backup';
+import { JobsService } from '../jobs/index';
+import type { Job } from '../jobs/index';
+import { type DatabaseBackupRun, type DatabaseBackupTrigger, type DbBackupPrisma } from './data/db-backup-db';
+import { type ResolvedDbBackupModuleOptions } from './options';
+import { type DbBackupMetrics, type DbBackupNotifier } from './ports';
+import { SystemSettingsService } from '../settings/index';
+import { type StorageProvider } from '../storage/index';
+import { StorageConfigService } from '../storage/index';
+import { type BackupTarget } from './backup-target';
+import { DbBackupEvents } from './db-backup-events';
+import { type PgProcess } from './pg-dump.util';
+import { type PgVersionCheck } from './pg-version.util';
+/**
+ * How often the heartbeat writes `lastHeartbeatAt` and the live
+ * `bytesWritten`.
+ *
+ * ⚠ THIS IS PROGRESS REPORTING, NOT THE LIVENESS SIGNAL — that changed in
+ * #351 and the distinction matters when tuning it. While the dump was
+ * detached, this beat was the ONLY evidence a run was still alive, and #282's
+ * stale sweep was the only thing that could settle an abandoned one. The dump
+ * is now a queue job, and #347's LEASE RENEWAL is what says "the executor is
+ * still there": the worker renews on a ticker derived from the type's
+ * `maxRuntimeMs`, and `JobStuckService` reaps a lease that stops being
+ * renewed. What this beat still owns — and nothing else does — is
+ * `bytesWritten`, the number the admin UI's progress bar reads.
+ *
+ * TWENTY SECONDS, and the number is still bounded on both sides by things
+ * that already exist. `databaseBackup.runStaleMinutes` starts at 120 and its
+ * minimum is 1, so the interval must stay comfortably under a minute: the
+ * stale sweep remains the backstop for the `pre_restore` path, which has no
+ * job and therefore no lease. At the other end each beat is one indexed
+ * UPDATE by primary key, so a tighter interval would be affordable but
+ * pointless: the progress bar it feeds is read by a human.
+ *
+ * A CONSTANT, not an environment variable. Nothing an operator could set here
+ * would be a better answer than "well inside the smallest stale window", and a
+ * knob whose only wrong settings are silent (too slow → false stale sweeps)
+ * is a knob worth not having.
+ *
+ * @stability experimental
+ */
+export declare const BACKUP_HEARTBEAT_INTERVAL_MS = 20000;
+/**
+ * The name of the partial unique index that enforces one active run.
+ *
+ * Declared in
+ * `prisma/migrations/20260907120000_add_database_backup_runs/migration.sql`;
+ * repeated here because a P2002 has to be attributed to *this* constraint and
+ * not to some other unique constraint a fork may add to the table.
+ */
+/**
+ * How far a worker node's reported finish time may be from this server's clock
+ * before the completing write logs a warning.
+ *
+ * FIVE MINUTES, and it is a WARNING AND NOTHING ELSE — never a refusal. A
+ * skewed clock does not make an archive less valid, and refusing a verified
+ * multi-gigabyte backup over NTP would be the wrong trade by a wide margin.
+ * The reason it is worth a line in the log at all is that the node's lease
+ * renewal (#347) runs on the very same clock, so a node this far out is a node
+ * whose next long job may lose its claim for reasons nobody will connect to
+ * the time.
+ *
+ * @stability experimental
+ */
+export declare const NODE_CLOCK_SKEW_WARN_MS: number;
+/**
+ * The raw-SQL partial unique index that admits ONE `pending`/`running` run
+ * (intentional schema drift: never `@@unique`, never a `findFirst` pre-check).
+ *
+ * @stability experimental
+ */
+export declare const ACTIVE_RUN_INDEX_NAME = "database_backup_runs_active_uniq_idx";
+/**
+ * The statuses the index's predicate covers — "an active run".
+ *
+ * @stability experimental
+ */
+export declare const ACTIVE_RUN_STATUSES: readonly ["pending", "running"];
+/**
+ * The `Job.type` a queued dump runs under (issue #351, epic #345).
+ *
+ * DECLARED HERE RATHER THAN IN THE HANDLER, and the direction is the reason:
+ * this file ENQUEUES the job and the handler EXECUTES it, so the handler can
+ * import the runner but the runner must never import the handler (that would
+ * be a cycle, and a module-evaluation-order one at that). The single
+ * definition therefore lives on the enqueueing side, and
+ * `handlers/db-backup-run.handler.ts` imports it for its `type`.
+ *
+ * ⚠ PERMANENT once jobs of this type exist, exactly as
+ * `JobHandler.type` says: `jobs` rows outlive the handler that produced them,
+ * so renaming this string orphans every historical row and every job already
+ * queued under the old name.
+ *
+ * @stability experimental
+ */
+export declare const BACKUP_JOB_TYPE = "db.backup.run";
+/**
+ * The one dedup key EVERY backup enqueue uses.
+ *
+ * CONSTANT, and that is the entire single-active-backup guard at the queue
+ * layer. A backup has no subject — there is one database and one archive per
+ * run — so `buildDedupKey` folds the null subject pair away and every caller
+ * lands on the same string. `jobs_active_dedup_uniq_idx` then makes a second
+ * enqueue while one is `pending`/`running` a P2002, which is exactly what
+ * BOTH callers want: the scheduler stands down, and #283's endpoint reports
+ * "already running" with the winner's run id.
+ *
+ * Derived through `buildDedupKey` rather than written out as a literal,
+ * because the index enforces uniqueness over whatever string the enqueue path
+ * puts in the column — and a literal here that drifted from the builder would
+ * silently stop colliding with the rows it is supposed to collide with.
+ *
+ * @stability experimental
+ */
+export declare const BACKUP_JOB_DEDUP_KEY: string;
+/**
+ * What a `db.backup.run` job carries.
+ *
+ * IDENTIFIERS AND PROVENANCE ONLY, per the queue's payload rule. It exists
+ * for ONE narrow case: a handler that finds no run row for its job (see
+ * `runQueuedBackup`) has to create one, and `trigger` has no default —
+ * a run nobody can attribute is a run nobody can explain. On the ordinary
+ * path the run row already exists and this payload is never read, which is
+ * why it carries nothing else: everything an operator wants about a backup
+ * lives on `database_backup_runs`, not in opaque JSONB.
+ *
+ * @stability experimental
+ */
+export interface BackupJobPayload {
+    /** Trigger. */
+    trigger: DatabaseBackupTrigger;
+    /** Created by id. */
+    createdById: string | null;
+}
+/**
+ * What a caller may say about the backup it wants taken.
+ *
+ * @stability experimental
+ */
+export interface StartBackupInput {
+    /** Why this run exists. No default: an unattributable run is a run nobody can explain. */
+    trigger: DatabaseBackupTrigger;
+    /**
+     * The administrator who asked, when a person did.
+     *
+     * `null`/omitted for a `scheduled` run — a timer has no user, and inventing
+     * one (the last admin to log in, the seeded admin) would put a name on an
+     * action nobody took.
+     */
+    createdById?: string | null;
+}
+/**
+ * A queued backup: the job that will execute it, and the row it will fill in.
+ *
+ * @stability experimental
+ */
+export interface QueuedBackup {
+    /** `pending`, with its server-chosen `storageKey` already set. */
+    run: DatabaseBackupRun;
+    /** The `db.backup.run` row a worker will claim. */
+    job: Job;
+}
+/**
+ * The provenance every terminal write carries — success or failure alike.
+ *
+ * ONE TYPE BECAUSE THERE ARE NOW TWO EXECUTORS. `executeRun` fills it from
+ * this process (the API image's `pg_dump`, this server's Prisma connection);
+ * `completeNodeRun` fills it from a worker node's reported result, where the
+ * three dump-side facts are things ONLY the node can know. A shared type is
+ * what stops the two paths from writing different subsets of the same audit
+ * block — see `completeRun`.
+ *
+ * All four are nullable-by-nature and NONE of them may fail a backup: a run
+ * that could not read the server version is still a valid archive. `appVersion`
+ * is the one exception in practice — it is this process's own build and is
+ * always available — and it is deliberately the API's version on BOTH paths,
+ * because it records which application wrote the row, not which binary wrote
+ * the file. That is what `pgDumpVersion` is for.
+ *
+ * @stability experimental
+ */
+export interface BackupRunAudit {
+    /** Db version. */
+    dbVersion: string | null;
+    /** App version. */
+    appVersion: string;
+    /** Migration name. */
+    migrationName: string | null;
+    /** Pg dump version. */
+    pgDumpVersion: string | null;
+}
+/**
+ * How a dump ended, as a VALUE rather than as a thrown error.
+ *
+ * `executeRun` records every failure it anticipates on the run row and then
+ * returns one of these, because its two callers need opposite things from the
+ * same code: the detached `pre_restore` path must not reject (there is nobody
+ * left to tell), and the queued path MUST reject (the worker settles the job
+ * from that rejection). Returning the outcome lets each caller decide, rather
+ * than having the engine guess which of the two it is serving.
+ *
+ * @stability experimental
+ */
+export type BackupRunOutcome = {
+    /** Status. */
+    status: 'completed';
+} | {
+    /** Status. */
+    status: 'failed';
+    /** Error. */
+    error: Error;
+};
+/**
+ * What `cancel` actually managed to do.
+ *
+ * A DISCRIMINATED RESULT RATHER THAN A `boolean` OR A THROW, because the
+ * honest answer has three cases and two of them are not errors. Cancellation
+ * works through a PROCESS-LOCAL handle — only the process that spawned the
+ * child can signal it — so a run started on another replica cannot be
+ * cancelled from here, and reporting that as `true` would tell an operator
+ * their dump had stopped when it is still streaming.
+ *
+ * @stability experimental
+ */
+export type CancelBackupResult = 
+/** The child was signalled and the upload torn down; the run will settle as `failed`. */
+{
+    /** Outcome. */
+    outcome: 'signalled';
+    /** Run id. */
+    runId: string;
+}
+/**
+ * No in-process handle exists. Either the run belongs to another replica, or
+ * it already settled. Either way THIS process cannot stop it, and #283 must
+ * say so rather than reporting success.
+ */
+ | {
+    /** Outcome. */
+    outcome: 'not_running_here';
+    /** Run id. */
+    runId: string;
+};
+/**
+ * The `pg_*` seam.
+ *
+ * Every child process this service starts goes through it, so the unit suite
+ * can drive a dump that dies mid-stream, an archive with an empty table of
+ * contents, and a blocked version pair WITH NO PostgreSQL BINARIES INSTALLED.
+ * A suite that needs `pg_dump` on the runner is a suite CI skips, and a skipped
+ * test guards nothing — the same argument `PgSpawnFn` makes one layer down.
+ *
+ * @stability experimental
+ */
+export interface DatabaseBackupEngine {
+    /** Starts `pg_dump -Fc` against this deployment's database. */
+    startDump(options: {
+        compressionLevel: number;
+        timeoutMs: number;
+    }): PgProcess;
+    /** Counts the table-of-contents entries in an archive stream. Zero means "restores nothing". */
+    readTocEntryCount(source: Readable): Promise<number>;
+    /** Compares the installed client against the server it would have to dump. */
+    checkClientVersion(): Promise<PgVersionCheck>;
+}
+/**
+ * DI token for {@link DatabaseBackupEngine}.
+ *
+ * OPTIONAL, and DELIBERATELY NOT PROVIDED in `DbBackupModule` — exactly like
+ * `JOB_CLOCK`. The application always gets {@link systemDatabaseBackupEngine};
+ * only a test that constructs this service directly can substitute one, so a
+ * fork cannot ship a stubbed dump engine by accident.
+ *
+ * @stability experimental
+ */
+export declare const DB_BACKUP_ENGINE: unique symbol;
+/**
+ * The real engine: real binaries, real database.
+ *
+ * @stability experimental
+ */
+export declare const systemDatabaseBackupEngine: DatabaseBackupEngine;
+/**
+ * The heartbeat's timer seam.
+ *
+ * @stability experimental
+ */
+export interface BackupTimers {
+    /** `setInterval`: the heartbeat's timer. */
+    setInterval(handler: () => void, ms: number): NodeJS.Timeout;
+    /** `clearInterval`. */
+    clearInterval(handle: NodeJS.Timeout): void;
+}
+/**
+ * DI token for {@link BackupTimers}. Optional and unprovided, as {@link DB_BACKUP_ENGINE} is.
+ *
+ * @stability experimental
+ */
+export declare const DB_BACKUP_TIMERS: unique symbol;
+/**
+ * The real timers, with the interval UNREF'D.
+ *
+ * A refed 20-second interval would hold a shutting-down process open, turning
+ * a graceful deploy into an orchestrator kill for as long as a dump lasts.
+ * Unref'd, the heartbeat stops mattering the moment nothing else is keeping
+ * the process alive — which is correct, because at that point there is no dump
+ * left to report progress for either. (The `typeof` guard is for fake-timer
+ * configurations whose handle is a bare number.)
+ *
+ * @stability experimental
+ */
+export declare const systemBackupTimers: BackupTimers;
+/**
+ * Whether `error` is a unique-constraint violation on the SINGLE-ACTIVE-RUN
+ * index specifically — as opposed to any other P2002 this table (or a fork's
+ * additions to it) might raise.
+ *
+ * THIS DISCRIMINATION IS LOAD-BEARING, for the same reason
+ * `isActiveDedupConflict` gives in `jobs.service.ts`: treating every P2002 as
+ * "already running" would report a genuine constraint bug as an ordinary busy
+ * signal, and that is the exact class of error that must stay loud. Anything
+ * this function does not positively recognise propagates untouched.
+ *
+ * Two metadata shapes are inspected because Prisma reports the violation
+ * differently depending on how the client is talking to Postgres — the driver
+ * adapter (`@prisma/adapter-pg`, which `PrismaService` uses) puts it under
+ * `meta.driverAdapterError.cause`, the classic engine under `meta.target`. Both
+ * are checked so that switching adapters degrades to "the P2002 propagates",
+ * never to "an unrelated conflict is silently swallowed".
+ *
+ * @stability experimental
+ */
+export declare function isActiveRunConflict(error: unknown): boolean;
+/**
+ * The backup engine: the ONE writer of `database_backup_runs`. Claims a run (the partial unique index arbitrates), streams `pg_dump` into object storage without buffering, verifies the archive, prunes by retention and records the outcome. Drive it through `queueBackup` (the queue) or `startBackup`.
+ *
+ * @stability experimental
+ */
+export declare class DatabaseBackupRunnerService {
+    private readonly prisma;
+    private readonly settings;
+    private readonly notifications;
+    private readonly config;
+    private readonly jobs;
+    private readonly metrics;
+    private readonly events?;
+    private readonly logger;
+    private readonly engine;
+    private readonly timers;
+    /** See {@link ActiveRunHandle}: process-local, never shared, never persisted. */
+    private readonly active;
+    constructor(prisma: DbBackupPrisma, settings: SystemSettingsService, storage: StorageProvider, storageConfig: StorageConfigService, notifications: DbBackupNotifier, config: ConfigService, jobs: JobsService, engine?: DatabaseBackupEngine, timers?: BackupTimers, metrics?: DbBackupMetrics, options?: ResolvedDbBackupModuleOptions, target?: BackupTarget, mirrors?: readonly BackupTarget[], events?: DbBackupEvents | undefined);
+    /** Where every archive is written, read back and deleted. */
+    private readonly target;
+    /** Where copies are written after the primary succeeded. */
+    private readonly mirrors;
+    /**
+     * Whether a worker node can take this deployment's backups: its presigned PUT
+     * writes through the storage provider, so only the default target qualifies.
+     * `DatabaseBackupRunHandler.nodeOffloadEnabled` withholds the type otherwise.
+     */
+    supportsNodeOffload(): boolean;
+    /** The application version recorded on a run (`DbBackupModuleOptions.appVersion`). */
+    private readonly appVersion;
+    /**
+     * The kind of the storage provider in force, for the rows and the rule that
+     * record or compare it: `STORAGE_PROVIDER`'s own `kind` (the configured
+     * `s3`/`r2`/`s3compatible` for the default provider, the app backend's id for
+     * a `StorageModule.forRoot({ provider })` binding).
+     *
+     * The settings read comes first, and only for the default provider's sake:
+     * `ResolvingStorageProvider.kind` is synchronous and answers from the last
+     * settings read, so awaiting one here keeps this exactly as fresh as the
+     * `activeProvider()` call it replaces.
+     */
+    private activeProviderKind;
+    /**
+     * Validates a `databaseBackup.storageProvider` value against the provider
+     * this deployment actually has.
+     *
+     * Exposed on the service so #283's `PUT` config handler can call it without
+     * importing storage internals, and so there is exactly ONE rule shared by
+     * the write path and the run path. The rule itself is pure and lives in
+     * `db-backup-storage.ts`.
+     *
+     * ⚠ ASYNC SINCE #373 (epic #372), and unavoidably so: "the active provider"
+     * is a setting now, so answering the question means reading it. This is the
+     * ONE place that read happens for both call sites — the `PUT` config endpoint
+     * (`DatabaseBackupAdminService.updateConfig`) and the run paths below — which
+     * is what keeps the form and the runner from ever judging the same value
+     * against two different answers.
+     *
+     * @throws {@link DatabaseBackupStorageProviderError} → a 400.
+     */
+    assertStorageProviderUsable(configured: string | null | undefined): Promise<void>;
+    /**
+     * Queues a backup: writes the `jobs` row and its `pending` run row, and
+     * returns. A worker claims the job and `runQueuedBackup` takes the dump.
+     *
+     * THE NORMAL PATH — #283's `POST /api/admin/db-backup/runs` and #282's cron
+     * both come through here. Only the `pre_restore` dump still uses
+     * {@link startBackup}.
+     *
+     * ---------------------------------------------------------------------------
+     * ⚠ BOTH INSERTS ARE ONE TRANSACTION. THIS IS THE PART TO READ.
+     * ---------------------------------------------------------------------------
+     *
+     * The endpoint must keep answering with a real run id immediately (its 202
+     * shape and `GET /runs/{id}` polling are unchanged), so the run row is
+     * created at ENQUEUE time as `pending` and the handler flips it to `running`
+     * when a worker actually claims it. That is strictly more honest than the
+     * old behaviour, which reported `running` before anything ran. It also
+     * creates two rows that must agree, and there are exactly three ways for
+     * two rows written separately to disagree. All three are made
+     * UNREPRESENTABLE by putting both inserts in ONE COMMIT:
+     *
+     *   1. A CLAIMED JOB WITH NO RUN ROW. A worker can claim within
+     *      milliseconds of the enqueue. Insert the job first and there is a real
+     *      window in which the handler resolves its run and finds nothing.
+     *      Inside one transaction the job row is invisible to every other
+     *      session — the claim's `FOR UPDATE SKIP LOCKED` included — until the
+     *      same commit that publishes the run row. The window has no duration
+     *      because it has no state.
+     *   2. AN ORPHAN `pending` RUN ROW. Insert the run row first and a failed
+     *      enqueue (or a process death between the two statements) leaves a
+     *      `pending` row behind. That is not a cosmetic leak: the TIGHTENED
+     *      `database_backup_runs_active_uniq_idx` admits exactly ONE active row
+     *      across `pending` and `running` COMBINED, so a leaked row blocks every
+     *      future backup — manual and scheduled — until somebody deletes it by
+     *      hand. A rolled-back transaction leaves nothing at all.
+     *   3. A RUN ROW WHOSE `job_id` WAS FILLED IN AFTERWARDS. Insert-then-UPDATE
+     *      reintroduces (1) for the length of the gap. The `jobId` is written
+     *      BY THE INSERT, never by a second statement.
+     *
+     * REJECTED: two statements with compensating deletes ("insert the run,
+     * enqueue, delete the run if the enqueue throws"). The compensation is
+     * itself a write that can fail, and its failure mode is precisely (2) —
+     * the leak that blocks every future backup. A rollback the database
+     * performs cannot fail in that way.
+     *
+     * REJECTED: `JobsService.enqueue` inside the transaction. Its
+     * catch-the-P2002-and-re-read loop cannot run there at all — Postgres aborts
+     * a transaction at the first failed statement — which is why
+     * `enqueueWithin` exists and why the conflict is resolved out here, after
+     * the transaction has ended.
+     *
+     * ⚠ THE ORDER OF THE TWO INSERTS INSIDE THE TRANSACTION IS NOT LOAD-BEARING
+     * (that is the point of a transaction), but the job goes first anyway so
+     * that its id can be written onto the run row by the insert rather than by
+     * an update. See (3).
+     *
+     * @throws {@link DatabaseBackupAlreadyRunningError} when either guard refused —
+     * the queue's dedup index (a backup job is already in flight) or the run
+     * table's single-active index (a `pre_restore` dump, say) — carrying the id
+     * of the run that won where one can be identified.
+     * @throws {@link DatabaseBackupStorageProviderError} when the configured provider
+     * is not the active one. Raised BEFORE anything is written, so a
+     * misconfigured provider is a clean 400 at request time and not a job that
+     * fails an hour later.
+     */
+    queueBackup(input: StartBackupInput): Promise<QueuedBackup>;
+    /**
+     * Classifies a failed {@link queueBackup} transaction.
+     *
+     * Returns the error to throw, or the literal `'retry'` when the conflict
+     * has already resolved itself and the caller should insert again.
+     *
+     * ⚠ IT RUNS AFTER THE TRANSACTION HAS ROLLED BACK, never inside it — see
+     * `JobsService.enqueueWithin` for why an aborted transaction can execute no
+     * further statement. Both discriminators are the EXISTING exported ones
+     * (`isActiveDedupConflict`, `isActiveRunConflict`), so anything neither
+     * positively recognises propagates untouched: a genuine constraint bug must
+     * stay loud rather than be reported as an ordinary busy signal.
+     */
+    private resolveQueueConflict;
+    /**
+     * Takes a backup WITHOUT a job: claims the single active slot as `running`,
+     * then streams the dump into storage in the background.
+     *
+     * ⚠ ONE CALLER REMAINS, AND IT IS NOT A LEGACY ONE. `DatabaseRestoreService`
+     * takes the `pre_restore` safety dump through here, deliberately outside the
+     * queue: it runs in the middle of a restore, and making it wait for a worker
+     * slot would make the safety net depend on `JOBS_WORKER_MODE`, on the queue
+     * being drained, and on this process still polling seconds from now — three
+     * things that are least trustworthy at exactly the moment a database is
+     * being replaced. Everything else must use {@link queueBackup}.
+     *
+     * @returns the freshly claimed run, ALREADY `running` and with its
+     * server-chosen `storageKey` set. The dump has not finished — see property 1
+     * in this file's header for why it must not have.
+     *
+     * @throws {@link DatabaseBackupAlreadyRunningError} when the index refused the
+     * claim, carrying the id of the run that won.
+     * @throws {@link DatabaseBackupStorageProviderError} when the configured provider
+     * is not the active one.
+     */
+    startBackup(input: StartBackupInput): Promise<DatabaseBackupRun>;
+    /**
+     * Takes the dump a `db.backup.run` job was queued for, AWAITED.
+     *
+     * THE JOB'S LIFETIME IS THE DUMP'S LIFETIME — this method returns when
+     * `pg_dump` has finished, the archive has been uploaded, and the stored
+     * object has been read back and verified. That is the whole point of #351:
+     * a handler that returned early would buy a dashboard row and nothing else
+     * (no lease, no slot accounting, no timeout, no possibility of node
+     * execution). `handlers/db-backup-run.handler.ts` calls exactly this and
+     * does nothing else.
+     *
+     * ---------------------------------------------------------------------------
+     * IT IS AUTHORITATIVE ABOUT THE RUN ROW, AND IT IS IDEMPOTENT
+     * ---------------------------------------------------------------------------
+     *
+     * `job_id` is `@unique`, so "the run for this job" is a single lookup that
+     * CANNOT return two rows — the resolution below is not a heuristic. What it
+     * finds decides what happens:
+     *
+     *   - `pending` (the ordinary case) → flipped to `running` with `startedAt`
+     *     and a seeded heartbeat. Only now has anything actually started, which
+     *     is why the row did not claim otherwise before.
+     *   - `running` → adopted with a warning. Unreachable while the profile says
+     *     `maxAttempts: 1` (the reaper's give-up phase fails such a job rather
+     *     than requeueing it), but a fork that raises that budget makes it
+     *     reachable, and stranding the row would be worse than re-dumping to a
+     *     key that is overwritten anyway.
+     *   - `completed` → returns without doing anything. The queue is
+     *     at-least-once; re-running a job whose work is already durable must be
+     *     a no-op, not a second dump.
+     *   - `failed` / `stale` → throws. Something already gave up on this run
+     *     (an operator, or the stale sweep), and it is no longer holding the
+     *     active slot — so re-dumping could run alongside a backup started since.
+     *   - NOTHING AT ALL → creates the row, from the job's payload. `queueBackup`
+     *     makes this unreachable for jobs it queued (both rows land in one
+     *     commit), so it covers the paths that are not `queueBackup`: a job
+     *     enqueued by hand, or a run row an administrator deleted while its job
+     *     was still queued. Failing the job there would be a worse answer than
+     *     taking the backup that was asked for.
+     *
+     * @throws whatever the dump failed with, AFTER `executeRun` has recorded it
+     * on the run row. The worker turns that into `Job.lastError` and — with
+     * `maxAttempts: 1` — a terminal `failed`, never a retry.
+     */
+    runQueuedBackup(job: Job): Promise<void>;
+    /**
+     * The run row this job owns, made ready to execute — or `null` when the work
+     * is already done. See {@link runQueuedBackup} for the full decision table.
+     */
+    private resolveRunForJob;
+    /**
+     * Stops a run THIS PROCESS is executing.
+     *
+     * Cancellation is not a second teardown mechanism: it destroys the metering
+     * stream with a {@link DatabaseBackupCancelledError}, which tears the upload
+     * down, which fails the `Promise.all`, which reaches the ORDINARY failure
+     * path — partial object deleted, row marked `failed`, heartbeat cleared. A
+     * bespoke "cancelled" cleanup would be a second chance to leave a
+     * half-written object in the bucket.
+     *
+     * Reports honestly when it holds no handle; see {@link CancelBackupResult}.
+     */
+    cancel(runId: string): CancelBackupResult;
+    /**
+     * INSERTs the run, letting the partial unique index decide the race.
+     *
+     * There is deliberately no `findFirst({ where: { status: 'running' } })`
+     * anywhere in this path. That is a check-then-act race and it is racy
+     * exactly when it matters — a scheduled tick on one replica and an admin's
+     * click on another, in the same second. Only the database can make "is one
+     * already active" atomic with the insert that would violate it.
+     */
+    private claimRun;
+    /**
+     * The columns every new run row carries, whichever path creates it.
+     *
+     * ONE BUILDER, THREE CALLERS (`claimRun`, `queueBackup`,
+     * `resolveRunForJob`), and the reason is the storage triple: provider, key
+     * and bucket are chosen by the SERVER and must be chosen the same way every
+     * time, or two paths produce archives that a restore looks for in different
+     * places. What it deliberately does NOT set is the lifecycle trio —
+     * `status`, `startedAt`, `lastHeartbeatAt` — because that is precisely where
+     * the three callers legitimately differ.
+     *
+     * ⚠ `provider` AND `bucket` BOTH ARRIVE IN `args`, and this method reads
+     * neither for itself. Both are live values since #373 (epic #372) — the
+     * bucket from `StorageProvider.getBucket()`, the provider from
+     * `StorageConfigService.activeProvider()` — and both must be resolved by the
+     * caller, which is `async` and can await, rather than here, which is
+     * synchronous because it is sometimes called inside a transaction callback.
+     * Passing them in also keeps the pair together: a row names one
+     * configuration's bucket and that same configuration's provider.
+     *
+     * ⚠ `Unchecked` INPUT, DELIBERATELY. `createdById` is a real relation
+     * (`createdBy`), and Prisma's *Checked* create input stops accepting the raw
+     * scalar the moment a scalar FK is promoted to one — it wants
+     * `createdBy: { connect: { id } }` instead, which cannot express "and also
+     * null". The unchecked variant takes the column as written, which is what a
+     * nullable audit FK wants.
+     */
+    private buildRunData;
+    /** The id of whichever run currently occupies the active slot, or `null`. */
+    private findActiveRunId;
+    /**
+     * The dump itself. NEVER REJECTS for a failure it anticipates — it records
+     * the failure on the run and REPORTS it as a {@link BackupRunOutcome},
+     * because one of its two callers has nobody left to tell and the other must
+     * fail a job.
+     *
+     * ⚠ THE RETURN VALUE IS NOT A SECOND RECORD OF THE FAILURE. The run row is
+     * written first and is the durable fact; this is how the caller learns of
+     * it. `startBackup` discards it (detached, nobody to tell);
+     * `runQueuedBackup` rethrows `error` so the worker settles the job.
+     */
+    private executeRun;
+    /**
+     * Marks a run `completed`: the terminal write, plus the enqueue of the
+     * retention prune that may only ever follow it.
+     *
+     * ⚠ BOTH EXECUTION PATHS COME THROUGH HERE, AND THAT IS THE POINT.
+     * `executeRun` calls it with what THIS process streamed and hashed;
+     * {@link completeNodeRun} calls it with what a worker node reported and this
+     * server then verified. A run's stored state therefore cannot depend on
+     * which executor produced it — the same "one write, two paths" rule
+     * `example-checksum.handler.ts` states for a node-eligible handler, applied
+     * to the row that a restore later reads.
+     *
+     * ⚠ IT ASSUMES VERIFICATION HAS ALREADY HAPPENED, and takes `tocEntries` as
+     * the evidence rather than the trust: both callers download the STORED
+     * object and count its table of contents before calling, and `verifiedAt` is
+     * written here precisely because it is unreachable without having done so.
+     * Do not add a `skipVerification` parameter; the day this method can be
+     * called without a server-side read-back is the day `verified_at` stops
+     * meaning anything.
+     *
+     * The prune's ENQUEUE lives here rather than at the two call sites for the
+     * reason the long comment below gives four times over: every one of its
+     * ordering constraints is a property of "a run just completed", not of who
+     * ran it.
+     */
+    private completeRun;
+    /**
+     * Copies a verified archive to every mirror target, one at a time, and
+     * records each result. NEVER THROWS, and never changes the run.
+     *
+     * Each copy STREAMS the primary's bytes (`openRead`) into the mirror's sink
+     * (`openWrite`): the dump is not run twice and the archive is not buffered.
+     * The copy is then read back from the mirror and its SHA-256 compared with
+     * the one computed over what the primary served, so a mirror holds a proven
+     * copy or a recorded failure, never a silent half-file (a failed copy is
+     * deleted from the mirror). The result of each is an `audit_events` row
+     * (`db_backup.mirror.completed` / `.failed`) that the `backup.mirrors` Doctor
+     * check reads, plus a log line.
+     */
+    private mirrorArchive;
+    /** One mirror copy: stream, read back, compare. Resolves the outcome; never throws. */
+    private copyToMirror;
+    /** Records one mirror result: a log line and an audit row (best effort). */
+    private recordMirrorResult;
+    /**
+     * Where a worker node must write this job's archive — the run's OWN key,
+     * re-read by `jobId`.
+     *
+     * This is what `DatabaseBackupRunHandler.deriveOutputKey` delegates to, and
+     * it exists because the data plane's default (`node-outputs/<jobId>/<uuid>`)
+     * is exactly wrong for this artifact: `database_backup_runs.storage_key` is
+     * what the retention sweep, the download endpoint and the whole restore path
+     * look the archive up by, so a backup written anywhere else is a backup none
+     * of them can find.
+     *
+     * ⚠ IDEMPOTENT BY CONSTRUCTION, NOT BY CONVENTION. A node asks for its
+     * upload URL more than once as a matter of course (a timed-out transfer, a
+     * lost response, a process restarted while holding the lease), and every one
+     * of those calls must yield the SAME key or a retry silently writes a second
+     * archive that no row points at. The key is read back from the run row, and
+     * `DatabaseBackupRun.jobId` is `@unique`, so "there is at most one to find"
+     * is enforced by the database rather than remembered by this method.
+     *
+     * ⚠ IT ALSO FLIPS `pending` → `running`, AND THAT IS DELIBERATE. This
+     * request is the ONLY moment the server learns that a remote executor has
+     * actually begun dumping: on the node path nothing else writes to the row
+     * between the claim and the result. Leaving it `pending` would mean the
+     * admin list reports "queued" for a dump that has been streaming for twenty
+     * minutes, and `startedAt` — which the failure notification and every
+     * duration render — would stay NULL. The flip is idempotent: a second call
+     * finds `running` and only reads.
+     *
+     * @throws when there is no run row for this job, or when the run has already
+     * settled. Both fail the upload-URL request (a 500 the node reports as a job
+     * failure), which is the correct answer: there is nowhere legitimate for
+     * those bytes to go, and signing a URL anyway would put an unreferenced
+     * archive in the bucket.
+     */
+    resolveNodeOutputKey(job: Job): Promise<string>;
+    /**
+     * Writes down a backup a WORKER NODE took — after this server has read the
+     * uploaded archive back and proven it is one.
+     *
+     * This is the whole of `DatabaseBackupRunHandler.persistNodeResult`, and the
+     * order of its four steps is the design:
+     *
+     *   1. FIND THE RUN by `jobId` (one lookup on a UNIQUE column, which cannot
+     *      return two rows).
+     *   2. REFUSE A KEY WE DID NOT HAND OUT. A node may only report the key
+     *      `resolveNodeOutputKey` gave it. Anything else is either a confused
+     *      executor or an attempt to point this deployment's restore path at
+     *      bytes of somebody else's choosing, and neither is something to
+     *      "correct" by trusting the node's spelling.
+     *   3. VERIFY SERVER-SIDE, ALWAYS. `download(key)` → `readTocEntryCount` →
+     *      `> 0`. The node's `sha256` is recorded as THE NODE'S CLAIM about what
+     *      it streamed; `verifiedAt` is set only because THIS process read the
+     *      object back out of the bucket. docs/specs/database-backup.md,
+     *      "Read-back verification", already settled that verification means
+     *      "what the bucket holds", and the cost — one download per backup — is
+     *      the cost this path already pays on the server.
+     *   4. WRITE THROUGH `completeRun`, the same method `executeRun` uses.
+     *
+     * ⚠ THIS IS NOT A SECOND DUMP ENGINE AND MUST NOT BECOME ONE. It does not
+     * re-hash the archive, does not recompute the size, and does not "fix" a
+     * digest it dislikes — `job-handler.interface.ts` states why (the moment the
+     * server redoes the work, the node's answer is decorative and the reason for
+     * the node plane is gone). The read-back is not a recomputation of the
+     * node's result: it is the one check whose whole point is that it must not
+     * be delegated.
+     *
+     * FAILURE GOES THROUGH THE ORDINARY FAILURE PATH — delete the partial
+     * object, then mark the run `failed` — for the reason property 5 of this
+     * file's header gives: a `failed` run must never leave an object behind, or
+     * the bucket accumulates archives that nothing points at and retention has
+     * no row to prune them by. The throw then reaches `NodesService.submitResult`,
+     * which settles the JOB as failed. Both rows end up telling the truth.
+     */
+    completeNodeRun(job: Job, result: DbBackupRunResult): Promise<void>;
+    /**
+     * The node path's failure path: delete, mark, throw.
+     *
+     * ALWAYS THROWS, and the throw is the contract — `persistNodeResult` failing
+     * is how `NodesService.submitResult` learns to settle the job as failed. A
+     * variant that returned quietly would leave a `failed` run row under a
+     * `succeeded` job, which is precisely the pair of rows that must never
+     * disagree.
+     *
+     * The DELETE comes first, for the reason `executeRun`'s catch does the same:
+     * a `failed` run that leaves its object behind is an archive nothing points
+     * at and retention has no row to prune it by.
+     */
+    private failNodeRun;
+    /**
+     * One heartbeat: liveness plus live progress, in one indexed UPDATE.
+     *
+     * SWALLOWS ITS OWN FAILURES. A transient write failure — a connection
+     * recycled, a brief failover, a lock wait — is not evidence that a dump
+     * streaming perfectly well should be abandoned. Aborting a two-hour backup
+     * because one progress UPDATE failed would be the definition of a
+     * self-inflicted outage. A sustained failure is not silent either: the
+     * heartbeat stops advancing, and #282's stale sweep is exactly the mechanism
+     * that notices.
+     */
+    private writeHeartbeat;
+    /**
+     * Removes the object a failed run may have partially written.
+     *
+     * BEST-EFFORT, AND IT NEVER MASKS THE ORIGINAL ERROR. Whatever broke the
+     * backup is what the operator needs on the row; "and the cleanup also failed"
+     * is a log line. Deleting a key that was never created is a no-op on every
+     * provider this interface targets, so there is no need to check first.
+     */
+    private deletePartialObject;
+    /** Writes the terminal `failed` row. Never throws — it is the last thing in a failure path. */
+    private markFailed;
+    /**
+     * Raise `db_backup.backup_failed` for a settled run. Never throws.
+     *
+     * SHARED WITH THE STALE SWEEP in shape but not in code — the sweep
+     * (`tasks/db-backup-schedule.task.ts`) writes its own rows and raises its own
+     * event, because it is a different process settling a run this one never saw.
+     * What IS shared is the event key, the permission and the template; the two
+     * differ only in `outcome`, which is exactly the field that exists to record
+     * that difference.
+     */
+    private announceFailure;
+    /**
+     * The application root, trailing slashes trimmed, or `undefined`.
+     *
+     * Same shape as `UsersService.appUrl()`; `undefined` makes the template omit
+     * its CTA rather than render a button that goes nowhere.
+     */
+    private appUrl;
+    /**
+     * The PostgreSQL server version, for the run's audit trio.
+     *
+     * `current_setting('server_version')` rather than `version()`, which returns
+     * a whole banner including the compiler and platform — provenance we neither
+     * need nor want to store per run.
+     *
+     * BEST-EFFORT: a failure here is `null`, never a failed backup. A run that
+     * could not read the server version is still a perfectly valid archive.
+     */
+    private readServerVersion;
+    /**
+     * The newest applied migration, for the run's audit trio.
+     *
+     * THE MOST IMPORTANT OF THE THREE: it says which SCHEMA the archive
+     * contains, so an operator can tell — before replaying it — whether the code
+     * that is running will understand what comes back.
+     *
+     * ⚠ THE QUERY LIVES IN `migration-state.util.ts` AND IS SHARED WITH #284's
+     * RESTORE PRE-FLIGHT, which compares the value recorded here against the one
+     * live at restore time. Two copies of "the newest applied migration" — one
+     * that excludes rolled-back rows and one that does not, say — would make that
+     * comparison meaningless: the gate would block restores of compatible
+     * archives, or pass an incompatible one. Best-effort, like the version above.
+     */
+    private readLatestMigrationName;
+}
+//# sourceMappingURL=db-backup-runner.service.d.ts.map