@marinoscar/platform-contract 0.0.0-stage → 0.1.0-next.4

package/dist/esm/db-backup/config.js

@@ -0,0 +1,112 @@
+// =============================================================================
+// The backup policy, read and written (issue #283, epic #254)
+// =============================================================================
+//
+// One settings namespace (`databaseBackup`) seen from two directions: what an
+// administrator sends to change it, and what they get back to look at.
+//
+// -----------------------------------------------------------------------------
+// THE REQUEST SCHEMA IS `systemDatabaseBackupPatchSchema`, IMPORTED AND NOT
+// RE-DECLARED
+// -----------------------------------------------------------------------------
+//
+// Every bound in it — `compressionLevel` 0-9, `retentionCount` 1-365,
+// `timeOfDay` matching `BACKUP_TIME_OF_DAY_PATTERN`, `dayOfMonth` stopping at
+// 28 so that "monthly" never skips February — is already stated once in
+// `common/schemas/settings.schema.ts`, and `PUT /api/system-settings` already
+// enforces exactly that schema over exactly this namespace. A second copy here
+// would be two schemas over one column, and the copy that drifts is always the
+// one nobody is looking at: the settings page would accept a value this route
+// refuses, or worse, this route would accept one the settings page refuses and
+// write it to the same JSONB.
+//
+// This is the same argument `db-backup-storage.ts` makes for having ONE
+// storage-provider rule shared by the write path and the run path.
+//
+// EVERY FIELD IS OPTIONAL, which is what makes the route a partial update in
+// the sense the issue asks for: `{ "enabled": true }` is a legal body. An
+// administrator changing the hour must not have to echo back twelve fields they
+// did not touch — a form that re-sends everything is a form that silently
+// reverts whatever another admin changed while it was open.
+//
+// -----------------------------------------------------------------------------
+// THE RESPONSE IS THE POLICY PLUS TWO COMPUTED FIELDS
+// -----------------------------------------------------------------------------
+//
+// `nextRunAt` and `activeRunId` are not stored anywhere and are not settings.
+// They are here because the question an administrator actually has on this
+// screen is not "what did I save" but "is this going to do what I meant, and is
+// something happening right now" — and both were previously unanswerable
+// without waiting a day to find out.
+//
+// See `DatabaseBackupAdminService.getConfig` for why `nextRunAt` is computed
+// rather than stored, and why it is `null` in two quite different situations.
+// =============================================================================
+import { z } from 'zod';
+import { RESTORE_UNAVAILABLE_REASONS } from './constants.js';
+import { systemDatabaseBackupPatchSchema, systemDatabaseBackupSchema } from './settings-schemas.js';
+/**
+ * The `PUT config` body: the settings namespace's own patch schema, unchanged.
+ *
+ * Not `.strict()`. The global `ZodValidationPipe` strips unknown keys, which is
+ * the behaviour every other settings write in this API already has: a client
+ * that sends a field a newer build understands and this one does not gets its
+ * known fields applied rather than a 400 it cannot act on.
+ *
+ * @stability stable
+ */
+export const updateDatabaseBackupConfigSchema = systemDatabaseBackupPatchSchema;
+/**
+ * `GET`/`PUT /api/admin/db-backup/config` response: the stored policy plus three computed fields.
+ *
+ * @stability stable
+ */
+export const databaseBackupConfigSchema = systemDatabaseBackupSchema.extend({
+    /**
+     * When the schedule will next fire, in UTC.
+     *
+     * COMPUTED ON EVERY READ from the settings above, never stored. The cron in
+     * `tasks/db-backup-schedule.task.ts` is the only thing that fires a scheduled
+     * backup; this field is a projection of the same rules and writes nothing, so
+     * reading this endpoint can never cause, delay or skip a backup.
+     *
+     * `null` means "no next run", and there are two ways to get one — a client
+     * rendering this field should say "not scheduled" rather than guessing which:
+     *
+     *   1. `enabled` is false. Nothing is scheduled, which is the answer.
+     *   2. The schedule cannot be projected — a `timezone` this runtime does not
+     *      know. `PUT config` refuses such a value, so this can only be a row
+     *      that predates the check (a seed, a restored settings blob, a
+     *      hand-edited JSONB), and the response stays a 200 precisely so the
+     *      screen that can FIX it still loads. See
+     *      `DatabaseBackupAdminService.getConfig`.
+     */
+    nextRunAt: z.iso.datetime().nullable(),
+    /**
+     * The run currently holding the single-active-run slot, or `null`.
+     *
+     * ⚠ A DISPLAY VALUE, AND NOT A PRE-FLIGHT CHECK. Nothing may read this and
+     * conclude that a `POST runs` will succeed: between this read and that write
+     * the scheduler on another replica can claim the slot. The arbiter is the
+     * partial unique index and it always will be — see
+     * `docs/specs/database-backup.md`, "Indexes and the single-active-run guard",
+     * for why a `findFirst` before the insert is racy exactly when it matters.
+     */
+    activeRunId: z.uuid().nullable(),
+    /**
+     * Whether this deployment offers in-app restore and rollback (#685).
+     *
+     * A DEPLOYMENT FACT, not part of the stored policy and not settable through
+     * `PUT config`: it comes from `DEPLOYMENT_MODE`, which only whoever runs the
+     * infrastructure can change. `available: false` means the restore and
+     * rollback routes answer 403 for everyone; `reason` says why, with the same
+     * token those 403s carry in `details.reason`. Backups are unaffected.
+     */
+    restore: z.object({
+        /** Available. */
+        available: z.boolean(),
+        /** Reason. */
+        reason: z.enum(RESTORE_UNAVAILABLE_REASONS).nullable(),
+    }),
+});
+//# sourceMappingURL=config.js.map

package/dist/esm/db-backup/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../../src/db-backup/config.ts"],"names":[],"mappings":"AAAA,gFAAgF;AAChF,8DAA8D;AAC9D,gFAAgF;AAChF,EAAE;AACF,8EAA8E;AAC9E,uEAAuE;AACvE,EAAE;AACF,gFAAgF;AAChF,4EAA4E;AAC5E,cAAc;AACd,gFAAgF;AAChF,EAAE;AACF,sEAAsE;AACtE,8EAA8E;AAC9E,wEAAwE;AACxE,8EAA8E;AAC9E,+EAA+E;AAC/E,+EAA+E;AAC/E,8EAA8E;AAC9E,+EAA+E;AAC/E,8BAA8B;AAC9B,EAAE;AACF,wEAAwE;AACxE,mEAAmE;AACnE,EAAE;AACF,6EAA6E;AAC7E,0EAA0E;AAC1E,gFAAgF;AAChF,0EAA0E;AAC1E,4DAA4D;AAC5D,EAAE;AACF,gFAAgF;AAChF,sDAAsD;AACtD,gFAAgF;AAChF,EAAE;AACF,8EAA8E;AAC9E,2EAA2E;AAC3E,gFAAgF;AAChF,yEAAyE;AACzE,qCAAqC;AACrC,EAAE;AACF,6EAA6E;AAC7E,8EAA8E;AAC9E,gFAAgF;AAEhF,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,2BAA2B,EAAqB,MAAM,gBAAgB,CAAC;AAEhF,OAAO,EAAE,+BAA+B,EAAE,0BAA0B,EAAE,MAAM,uBAAuB,CAAC;AAEpG;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,gCAAgC,GAAG,+BAA+B,CAAC;AAShF;;;;GAIG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAG,0BAA0B,CAAC,MAAM,CAAC;IAC1E;;;;;;;;;;;;;;;;;;OAkBG;IACH,SAAS,EAAE,CAAC,CAAC,GAAG,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE;IAEtC;;;;;;;;;OASG;IACH,WAAW,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,QAAQ,EAAE;IAEhC;;;;;;;;OAQG;IACH,OAAO,EAAE,CAAC,CAAC,MAAM,CAAC;QAChB,iBAAiB;QACjB,SAAS,EAAE,CAAC,CAAC,OAAO,EAAE;QACtB,cAAc;QACd,MAAM,EAAG,CAAC,CAAC,IAAI,CAAC,2BAA2B,CAAiE,CAAC,QAAQ,EAAE;KACxH,CAAC;CACH,CAAC,CAAC"}

package/dist/esm/db-backup/constants.d.ts

@@ -0,0 +1,314 @@
+/**
+ * The five `DatabaseBackupStatus` values, as a tuple Zod can build an enum
+ * from.
+ *
+ * A hand-copied list guarded in BOTH directions, exactly as
+ * `jobs/dto/job-response.dto.ts` guards its own: `satisfies` catches a value
+ * listed here that the schema does not have, and `BackupStatusesAreExhaustive` (in the API)
+ * catches a value the schema has that this file forgot — the direction that
+ * would otherwise fail silently, publishing a filter enum that cannot express a
+ * real row's status.
+ *
+ * @stability stable
+ */
+export declare const BACKUP_STATUSES: readonly ["pending", "running", "completed", "failed", "stale"];
+/**
+ * One {@link BACKUP_STATUSES} value.
+ *
+ * @stability stable
+ */
+export type BackupStatusName = (typeof BACKUP_STATUSES)[number];
+/**
+ * The three `DatabaseBackupTrigger` values, with the same two guards.
+ *
+ * @stability stable
+ */
+export declare const BACKUP_TRIGGERS: readonly ["manual", "scheduled", "pre_restore"];
+/**
+ * One {@link BACKUP_TRIGGERS} value.
+ *
+ * @stability stable
+ */
+export type BackupTriggerName = (typeof BACKUP_TRIGGERS)[number];
+/**
+ * The six values `database_backup_runs.restore_status` can hold.
+ *
+ * ⚠ NO `satisfies` GUARD IS POSSIBLE HERE, and that is a property of the
+ * column rather than an oversight: `restore_status` is a plain `text` in
+ * `schema.prisma`, not a Postgres enum, precisely so that adding `rolled_back`
+ * cost no migration. There is therefore no generated union for the compiler to
+ * check this tuple against.
+ *
+ * Re-derived rather than imported from `database-restore.service.ts` so that a
+ * DTO file does not depend on a service — the same discipline
+ * `ACTIVE_BACKUP_STATUSES` follows — and `db-backup-restore.dto.spec.ts`
+ * asserts the two lists agree, so they cannot drift apart in silence.
+ *
+ * @stability stable
+ */
+export declare const RESTORE_STATUSES: readonly ["restoring", "verifying", "swapping", "completed", "failed", "rolled_back"];
+/**
+ * One {@link RESTORE_STATUSES} value.
+ *
+ * @stability stable
+ */
+export type RestoreStatusName = (typeof RESTORE_STATUSES)[number];
+/**
+ * The statuses that hold the single-active-run slot.
+ *
+ * Re-derived from {@link BACKUP_STATUSES} rather than imported from
+ * `db-backup-runner.service.ts` so that a DTO file does not depend on a service
+ * — but it is the same pair, and `db-backup-admin.service.spec.ts` asserts the
+ * two lists agree, so they cannot drift apart in silence.
+ *
+ * @stability stable
+ */
+export declare const ACTIVE_BACKUP_STATUSES: readonly ["pending", "running"];
+/**
+ * The two outcomes `CancelBackupResultDto` can report.
+ *
+ * Mirrors `CancelBackupResult` in `db-backup-runner.service.ts` one-for-one and
+ * on purpose: this is that type on the wire, not a summary of it.
+ *
+ * @stability stable
+ */
+export declare const CANCEL_OUTCOMES: readonly ["signalled", "not_running_here"];
+/**
+ * The two normal answers. There is deliberately no third, and no error one.
+ *
+ * @stability stable
+ */
+export declare const NODE_CREDENTIAL_PREFLIGHT_OUTCOMES: readonly ["ok", "guided"];
+/**
+ * Why `restore.available` is false. One today; the enum is the contract.
+ *
+ * @stability stable
+ */
+export declare const RESTORE_UNAVAILABLE_REASONS: readonly ["deployment_mode_saas"];
+/**
+ * The word `POST runs/:id/restore` requires. See this file's header.
+ *
+ * @stability stable
+ */
+export declare const RESTORE_CONFIRMATION = "RESTORE";
+/**
+ * The word `POST runs/:id/rollback` requires. Deliberately not the same word.
+ *
+ * @stability stable
+ */
+export declare const ROLLBACK_CONFIRMATION = "ROLLBACK";
+/**
+ * The three normal answers. `mode`, not the status code, is the discriminator.
+ *
+ * @stability stable
+ */
+export declare const RESTORE_MODES: readonly ["running", "guided", "blocked"];
+/**
+ * One {@link RESTORE_MODES} value.
+ *
+ * @stability stable
+ */
+export type RestoreMode = (typeof RESTORE_MODES)[number];
+/**
+ * The three normal answers.
+ *
+ * Mirrors `RestoreRollbackResult` in `database-restore.service.ts` one-for-one
+ * and on purpose: this is that type on the wire, not a summary of it — the same
+ * discipline `CANCEL_OUTCOMES` follows.
+ *
+ * @stability stable
+ */
+export declare const ROLLBACK_MODES: readonly ["renamed", "restore_started", "unavailable"];
+/**
+ * One {@link ROLLBACK_MODES} value.
+ *
+ * @stability stable
+ */
+export type RollbackMode = (typeof ROLLBACK_MODES)[number];
+/**
+ * The name of the `POST runs/:id/restore` body field that overrides the
+ * `schema_compatibility` gate.
+ *
+ * ⚠ IT IS THE API'S FIELD NAME, NOT THE PRE-FLIGHT SERVICE'S OPTION NAME, and
+ * the difference is the whole point. A `blocked` restore's `overrideParameter`
+ * exists to tell a CLIENT which field to set on its next request, so publishing
+ * the internal option name (`overrideSchemaMismatch`) would hand an operator a
+ * parameter the endpoint rejects.
+ *
+ * The API's restore DTO ties its own schema to it at compile time
+ * (`RestoreOverrideFieldIsReal`) and at run time in its spec.
+ *
+ * @stability stable
+ */
+export declare const RESTORE_SCHEMA_OVERRIDE_FIELD = "overrideSchemaCheck";
+/**
+ * The restore pre-flight's BUILT-IN gates, in the order they are evaluated and
+ * reported. `rls_bypass` (#740) reports how the restore session gets past
+ * row-level security, on pass as well as on failure.
+ *
+ * Not a closed list of every gate: an app registers its own with
+ * `registerRestoreGate` (`@marinoscar/platform-api/db-backup`), which run after
+ * these and report under their own ids (see `restoreGateIdSchema`). This
+ * list names the eight the platform ships, for labels and defaults.
+ *
+ * @stability stable
+ */
+export declare const BUILTIN_RESTORE_GATE_IDS: readonly ["pg_client_version", "admin_connection", "createdb_privilege", "extensions", "rls_bypass", "disk_space", "replicas", "schema_compatibility"];
+/**
+ * The same eight ids under their former name.
+ *
+ * @deprecated Renamed {@link BUILTIN_RESTORE_GATE_IDS}: the gate id is an open
+ * vocabulary now, so this is no longer "every gate id". Kept as an alias for
+ * one release.
+ * @stability stable
+ */
+export declare const RESTORE_GATE_IDS: readonly ["pg_client_version", "admin_connection", "createdb_privilege", "extensions", "rls_bypass", "disk_space", "replicas", "schema_compatibility"];
+/**
+ * One built-in restore gate id.
+ *
+ * @stability stable
+ */
+export type BuiltinRestoreGateId = (typeof BUILTIN_RESTORE_GATE_IDS)[number];
+/**
+ * A restore gate id: one of the built-ins, or an id an app registered.
+ * Widened to `string` (an open vocabulary); narrow with
+ * {@link BuiltinRestoreGateId} where only the platform's own gates matter.
+ *
+ * @stability stable
+ */
+export type RestoreGateId = BuiltinRestoreGateId | (string & {});
+/**
+ * The shape of a restore gate id: lowercase letters, digits, `_` and `-`,
+ * starting with a letter. Every built-in id matches, and so does an app's
+ * `cdn-quiesced`.
+ *
+ * @stability experimental
+ */
+export declare const RESTORE_GATE_ID_PATTERN: RegExp;
+/**
+ * `databaseBackup.timeOfDay`: 24-hour `HH:MM`, zero-padded.
+ *
+ * A string rather than two numbers because it is one field on one form and one
+ * value in one cron-ish schedule; the regex is what stops `"2:00"`, `"25:00"`
+ * and `"02:60"` from reaching a scheduler that would have to guess.
+ *
+ * @stability stable
+ */
+export declare const BACKUP_TIME_OF_DAY_PATTERN: RegExp;
+/**
+ * How often a scheduled backup runs (`databaseBackup.frequency`).
+ *
+ * @stability stable
+ */
+export declare const BACKUP_FREQUENCIES: readonly ["daily", "weekly", "monthly", "cron"];
+/**
+ * The shortest gap, in minutes, a `frequency: 'cron'` expression may leave
+ * between two fires (one hour). The scheduler ticks every ten minutes and a
+ * dump is a whole-database read, so a finer cadence would stack dumps rather
+ * than protect anything.
+ *
+ * @stability experimental
+ */
+export declare const BACKUP_CRON_MIN_INTERVAL_MINUTES = 60;
+/**
+ * The characters a `cron` expression may contain: digits, `*`, `/`, `,`, `-`
+ * and spaces. A shape check only; the API validates the expression with the
+ * scheduler's own parser (and the minimum interval) when it is written.
+ *
+ * @stability experimental
+ */
+export declare const BACKUP_CRON_PATTERN: RegExp;
+/**
+ * What a restore does with the database it displaced
+ * (`databaseBackup.restoreRollbackMode`).
+ *
+ * @stability stable
+ */
+export declare const RESTORE_ROLLBACK_MODES: readonly ["retain_database", "drop_database"];
+/**
+ * The entries of a zod enum built from a value list (`{ manual: 'manual', ... }`):
+ * the schemas cast `z.enum(list)` to `z.ZodEnum<DbBackupEnum<typeof list>>`
+ * so the declarations name the list instead of spelling every entry.
+ *
+ * @typeParam T - the value list.
+ *
+ * @stability experimental
+ */
+export type DbBackupEnum<T extends readonly string[]> = {
+    [K in T[number]]: K;
+};
+/**
+ * The event emitted once a backup run settles (`completed`, `failed`,
+ * `stale`), after the row is written and outside any transaction. The payload
+ * is {@link DbBackupRunCompletedEvent}. Permanent: a listener subscribes by
+ * this string.
+ *
+ * @extensionPoint event
+ * @stability experimental
+ */
+export declare const DB_BACKUP_RUN_COMPLETED_EVENT = "db_backup.run.completed";
+/**
+ * The event emitted once a restore settles (`completed` after the swap,
+ * `failed`), after the audit write and outside any transaction. The payload is
+ * {@link DbBackupRestoreCompletedEvent}. Permanent.
+ *
+ * @extensionPoint event
+ * @stability experimental
+ */
+export declare const DB_BACKUP_RESTORE_COMPLETED_EVENT = "db_backup.restore.completed";
+/**
+ * What `db_backup.run.completed` carries. JSON-safe (it also travels the
+ * cross-replica event bus), and free of secrets.
+ *
+ * @stability experimental
+ */
+export interface DbBackupRunCompletedEvent {
+    /** The `database_backup_runs` row. */
+    runId: string;
+    /** How the run ended: `completed`, `failed` or `stale`. */
+    status: BackupStatusName;
+    /** The id of the target the archive was written to (the run's `storageProvider`). */
+    targetId: string;
+    /** The archive's size in bytes (`0` when none was written). A JSON number: exact up to 2^53. */
+    sizeBytes: number;
+    /** Wall-clock milliseconds from start to settle (`0` when the run never started). */
+    durationMs: number;
+}
+/**
+ * What `db_backup.restore.completed` carries: the same shape as
+ * {@link DbBackupRunCompletedEvent}, for the restore of the archive `runId`.
+ * `status` is `completed` or `failed`; `sizeBytes` is the archive's size and
+ * `durationMs` the restore's own duration.
+ *
+ * @stability experimental
+ */
+export interface DbBackupRestoreCompletedEvent {
+    /** The backup run whose archive was restored. */
+    runId: string;
+    /** `completed` (the swap landed) or `failed`. */
+    status: 'completed' | 'failed';
+    /** The id of the target the archive was read from. */
+    targetId: string;
+    /** The archive's size in bytes. */
+    sizeBytes: number;
+    /** Milliseconds from the restore's start to its end. */
+    durationMs: number;
+}
+/**
+ * How one mirror target fared for one run (the `meta` of its
+ * `db_backup.mirror.*` audit row, and what the `backup.mirrors` Doctor check
+ * reads).
+ *
+ * @stability experimental
+ */
+export interface BackupMirrorResult {
+    /** The mirror target's id. */
+    targetId: string;
+    /** `ok` when the copy landed and was read back; `failed` otherwise. */
+    status: 'ok' | 'failed';
+    /** Bytes written to the mirror (`0` on failure). */
+    sizeBytes: number;
+    /** Why it failed; absent on success. Never carries a credential. */
+    error?: string;
+}
+//# sourceMappingURL=constants.d.ts.map

package/dist/esm/db-backup/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../../src/db-backup/constants.ts"],"names":[],"mappings":"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"}

package/dist/esm/db-backup/constants.js

@@ -0,0 +1,240 @@
+// =============================================================================
+// Database backup and restore: plain values of the slice's wire shapes
+// (issue #740, PP-8.7)
+// =============================================================================
+//
+// Zod-free, so a consumer that needs only a status list or a confirmation word
+// (the web app) never bundles the schemas or zod. Moved from the API's
+// `db-backup/dto/*.dto.ts`, `db-backup/restore-preflight.service.ts` and
+// `common/schemas/settings.schema.ts` with their comments; the API re-exports
+// them.
+// =============================================================================
+/**
+ * The five `DatabaseBackupStatus` values, as a tuple Zod can build an enum
+ * from.
+ *
+ * A hand-copied list guarded in BOTH directions, exactly as
+ * `jobs/dto/job-response.dto.ts` guards its own: `satisfies` catches a value
+ * listed here that the schema does not have, and `BackupStatusesAreExhaustive` (in the API)
+ * catches a value the schema has that this file forgot — the direction that
+ * would otherwise fail silently, publishing a filter enum that cannot express a
+ * real row's status.
+ *
+ * @stability stable
+ */
+export const BACKUP_STATUSES = [
+    'pending',
+    'running',
+    'completed',
+    'failed',
+    'stale',
+];
+/**
+ * The three `DatabaseBackupTrigger` values, with the same two guards.
+ *
+ * @stability stable
+ */
+export const BACKUP_TRIGGERS = [
+    'manual',
+    'scheduled',
+    'pre_restore',
+];
+/**
+ * The six values `database_backup_runs.restore_status` can hold.
+ *
+ * ⚠ NO `satisfies` GUARD IS POSSIBLE HERE, and that is a property of the
+ * column rather than an oversight: `restore_status` is a plain `text` in
+ * `schema.prisma`, not a Postgres enum, precisely so that adding `rolled_back`
+ * cost no migration. There is therefore no generated union for the compiler to
+ * check this tuple against.
+ *
+ * Re-derived rather than imported from `database-restore.service.ts` so that a
+ * DTO file does not depend on a service — the same discipline
+ * `ACTIVE_BACKUP_STATUSES` follows — and `db-backup-restore.dto.spec.ts`
+ * asserts the two lists agree, so they cannot drift apart in silence.
+ *
+ * @stability stable
+ */
+export const RESTORE_STATUSES = [
+    'restoring',
+    'verifying',
+    'swapping',
+    'completed',
+    'failed',
+    'rolled_back',
+];
+/**
+ * The statuses that hold the single-active-run slot.
+ *
+ * Re-derived from {@link BACKUP_STATUSES} rather than imported from
+ * `db-backup-runner.service.ts` so that a DTO file does not depend on a service
+ * — but it is the same pair, and `db-backup-admin.service.spec.ts` asserts the
+ * two lists agree, so they cannot drift apart in silence.
+ *
+ * @stability stable
+ */
+export const ACTIVE_BACKUP_STATUSES = ['pending', 'running'];
+/**
+ * The two outcomes `CancelBackupResultDto` can report.
+ *
+ * Mirrors `CancelBackupResult` in `db-backup-runner.service.ts` one-for-one and
+ * on purpose: this is that type on the wire, not a summary of it.
+ *
+ * @stability stable
+ */
+export const CANCEL_OUTCOMES = ['signalled', 'not_running_here'];
+/**
+ * The two normal answers. There is deliberately no third, and no error one.
+ *
+ * @stability stable
+ */
+export const NODE_CREDENTIAL_PREFLIGHT_OUTCOMES = ['ok', 'guided'];
+/**
+ * Why `restore.available` is false. One today; the enum is the contract.
+ *
+ * @stability stable
+ */
+export const RESTORE_UNAVAILABLE_REASONS = ['deployment_mode_saas'];
+/**
+ * The word `POST runs/:id/restore` requires. See this file's header.
+ *
+ * @stability stable
+ */
+export const RESTORE_CONFIRMATION = 'RESTORE';
+/**
+ * The word `POST runs/:id/rollback` requires. Deliberately not the same word.
+ *
+ * @stability stable
+ */
+export const ROLLBACK_CONFIRMATION = 'ROLLBACK';
+/**
+ * The three normal answers. `mode`, not the status code, is the discriminator.
+ *
+ * @stability stable
+ */
+export const RESTORE_MODES = ['running', 'guided', 'blocked'];
+/**
+ * The three normal answers.
+ *
+ * Mirrors `RestoreRollbackResult` in `database-restore.service.ts` one-for-one
+ * and on purpose: this is that type on the wire, not a summary of it — the same
+ * discipline `CANCEL_OUTCOMES` follows.
+ *
+ * @stability stable
+ */
+export const ROLLBACK_MODES = ['renamed', 'restore_started', 'unavailable'];
+/**
+ * The name of the `POST runs/:id/restore` body field that overrides the
+ * `schema_compatibility` gate.
+ *
+ * ⚠ IT IS THE API'S FIELD NAME, NOT THE PRE-FLIGHT SERVICE'S OPTION NAME, and
+ * the difference is the whole point. A `blocked` restore's `overrideParameter`
+ * exists to tell a CLIENT which field to set on its next request, so publishing
+ * the internal option name (`overrideSchemaMismatch`) would hand an operator a
+ * parameter the endpoint rejects.
+ *
+ * The API's restore DTO ties its own schema to it at compile time
+ * (`RestoreOverrideFieldIsReal`) and at run time in its spec.
+ *
+ * @stability stable
+ */
+export const RESTORE_SCHEMA_OVERRIDE_FIELD = 'overrideSchemaCheck';
+/**
+ * The restore pre-flight's BUILT-IN gates, in the order they are evaluated and
+ * reported. `rls_bypass` (#740) reports how the restore session gets past
+ * row-level security, on pass as well as on failure.
+ *
+ * Not a closed list of every gate: an app registers its own with
+ * `registerRestoreGate` (`@marinoscar/platform-api/db-backup`), which run after
+ * these and report under their own ids (see `restoreGateIdSchema`). This
+ * list names the eight the platform ships, for labels and defaults.
+ *
+ * @stability stable
+ */
+export const BUILTIN_RESTORE_GATE_IDS = [
+    'pg_client_version',
+    'admin_connection',
+    'createdb_privilege',
+    'extensions',
+    'rls_bypass',
+    'disk_space',
+    'replicas',
+    'schema_compatibility',
+];
+/**
+ * The same eight ids under their former name.
+ *
+ * @deprecated Renamed {@link BUILTIN_RESTORE_GATE_IDS}: the gate id is an open
+ * vocabulary now, so this is no longer "every gate id". Kept as an alias for
+ * one release.
+ * @stability stable
+ */
+export const RESTORE_GATE_IDS = BUILTIN_RESTORE_GATE_IDS;
+/**
+ * The shape of a restore gate id: lowercase letters, digits, `_` and `-`,
+ * starting with a letter. Every built-in id matches, and so does an app's
+ * `cdn-quiesced`.
+ *
+ * @stability experimental
+ */
+export const RESTORE_GATE_ID_PATTERN = /^[a-z][a-z0-9_-]{1,63}$/;
+/**
+ * `databaseBackup.timeOfDay`: 24-hour `HH:MM`, zero-padded.
+ *
+ * A string rather than two numbers because it is one field on one form and one
+ * value in one cron-ish schedule; the regex is what stops `"2:00"`, `"25:00"`
+ * and `"02:60"` from reaching a scheduler that would have to guess.
+ *
+ * @stability stable
+ */
+export const BACKUP_TIME_OF_DAY_PATTERN = /^([01]\d|2[0-3]):[0-5]\d$/;
+/**
+ * How often a scheduled backup runs (`databaseBackup.frequency`).
+ *
+ * @stability stable
+ */
+export const BACKUP_FREQUENCIES = ['daily', 'weekly', 'monthly', 'cron'];
+/**
+ * The shortest gap, in minutes, a `frequency: 'cron'` expression may leave
+ * between two fires (one hour). The scheduler ticks every ten minutes and a
+ * dump is a whole-database read, so a finer cadence would stack dumps rather
+ * than protect anything.
+ *
+ * @stability experimental
+ */
+export const BACKUP_CRON_MIN_INTERVAL_MINUTES = 60;
+/**
+ * The characters a `cron` expression may contain: digits, `*`, `/`, `,`, `-`
+ * and spaces. A shape check only; the API validates the expression with the
+ * scheduler's own parser (and the minimum interval) when it is written.
+ *
+ * @stability experimental
+ */
+export const BACKUP_CRON_PATTERN = /^[0-9*/,\-\s]+$/;
+/**
+ * What a restore does with the database it displaced
+ * (`databaseBackup.restoreRollbackMode`).
+ *
+ * @stability stable
+ */
+export const RESTORE_ROLLBACK_MODES = ['retain_database', 'drop_database'];
+/**
+ * The event emitted once a backup run settles (`completed`, `failed`,
+ * `stale`), after the row is written and outside any transaction. The payload
+ * is {@link DbBackupRunCompletedEvent}. Permanent: a listener subscribes by
+ * this string.
+ *
+ * @extensionPoint event
+ * @stability experimental
+ */
+export const DB_BACKUP_RUN_COMPLETED_EVENT = 'db_backup.run.completed';
+/**
+ * The event emitted once a restore settles (`completed` after the swap,
+ * `failed`), after the audit write and outside any transaction. The payload is
+ * {@link DbBackupRestoreCompletedEvent}. Permanent.
+ *
+ * @extensionPoint event
+ * @stability experimental
+ */
+export const DB_BACKUP_RESTORE_COMPLETED_EVENT = 'db_backup.restore.completed';
+//# sourceMappingURL=constants.js.map

package/dist/esm/db-backup/constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../../../src/db-backup/constants.ts"],"names":[],"mappings":"AAAA,gFAAgF;AAChF,uEAAuE;AACvE,uBAAuB;AACvB,gFAAgF;AAChF,EAAE;AACF,+EAA+E;AAC/E,uEAAuE;AACvE,yEAAyE;AACzE,8EAA8E;AAC9E,QAAQ;AACR,gFAAgF;AAEhF;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG;IAC7B,SAAS;IACT,SAAS;IACT,WAAW;IACX,QAAQ;IACR,OAAO;CACC,CAAC;AASX;;;;GAIG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG;IAC7B,QAAQ;IACR,WAAW;IACX,aAAa;CACL,CAAC;AASX;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG;IAC9B,WAAW;IACX,WAAW;IACX,UAAU;IACV,WAAW;IACX,QAAQ;IACR,aAAa;CACL,CAAC;AASX;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC,SAAS,EAAE,SAAS,CAAgD,CAAC;AAE5G;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,WAAW,EAAE,kBAAkB,CAAU,CAAC;AAE1E;;;;GAIG;AACH,MAAM,CAAC,MAAM,kCAAkC,GAAG,CAAC,IAAI,EAAE,QAAQ,CAAU,CAAC;AAE5E;;;;GAIG;AACH,MAAM,CAAC,MAAM,2BAA2B,GAAG,CAAC,sBAAsB,CAAU,CAAC;AAE7E;;;;GAIG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,SAAS,CAAC;AAE9C;;;;GAIG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,UAAU,CAAC;AAEhD;;;;GAIG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,SAAS,EAAE,QAAQ,EAAE,SAAS,CAAU,CAAC;AASvE;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,SAAS,EAAE,iBAAiB,EAAE,aAAa,CAAU,CAAC;AASrF;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,MAAM,6BAA6B,GAAG,qBAAqB,CAAC;AAEnE;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG;IACtC,mBAAmB;IACnB,kBAAkB;IAClB,oBAAoB;IACpB,YAAY;IACZ,YAAY;IACZ,YAAY;IACZ,UAAU;IACV,sBAAsB;CACd,CAAC;AAEX;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,wBAAwB,CAAC;AAkBzD;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,yBAAyB,CAAC;AAEjE;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAG,2BAA2B,CAAC;AAEtE;;;;GAIG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,CAAU,CAAC;AAElF;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,gCAAgC,GAAG,EAAE,CAAC;AAEnD;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,iBAAiB,CAAC;AAErD;;;;;GAKG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC,iBAAiB,EAAE,eAAe,CAAU,CAAC;AAapF;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,6BAA6B,GAAG,yBAAyB,CAAC;AAEvE;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,iCAAiC,GAAG,6BAA6B,CAAC"}