@marinoscar/platform-api 0.1.0-next.3 → 0.1.0-next.4

package/dist/db-backup/restore-gate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"restore-gate.d.ts","sourceRoot":"","sources":["../../src/db-backup/restore-gate.ts"],"names":[],"mappings":"AAeA,OAAO,EAA4C,KAAK,6BAA6B,EAAE,MAAM,WAAW,CAAC;AACzG,OAAO,EAA6B,KAAK,sBAAsB,EAAE,MAAM,SAAS,CAAC;AAEjF;;;;GAIG;AACH,qBACa,mBAAmB;IAC9B,qGAAqG;IACrG,QAAQ,CAAC,IAAI,EAAE,aAAa,GAAG,MAAM,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;IAEtD,iEAAiE;IACjE,QAAQ,CAAC,mBAAmB,EAAE,OAAO,CAAC;IAEtC;;;OAGG;gBAEsC,OAAO,CAAC,EAAE,6BAA6B,EAC/B,UAAU,CAAC,EAAE,sBAAsB;IAMpF;;;;OAIG;IACH,yBAAyB,IAAI,IAAI;CAGlC;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,IAAI,GAAE,aAAa,GAAG,MAAM,GAAG,CAAC,MAAM,GAAG,EAAE,CAAiB,GAAG,mBAAmB,CAEhH"}

package/dist/db-backup/restore-gate.js

@@ -0,0 +1,80 @@
+"use strict";
+// =============================================================================
+// The deployment-mode restore gate (issue #740; the mode is #685's)
+// =============================================================================
+//
+// One provider answers "may this deployment restore its own database?", read
+// ONCE at boot from the `forRoot()` options and the `DB_BACKUP_DEPLOYMENT_MODE`
+// port (see `resolveRestoreEnabled`). It replaces the reference app's
+// `DeploymentModeService` inside the slice, with the same two members, so the
+// three layers that enforce the gate (the admin service, the restore service
+// and the `db.restore.run` handler) read exactly as they did.
+// =============================================================================
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DbBackupRestoreGate = void 0;
+exports.restoreGateFor = restoreGateFor;
+const common_1 = require("@nestjs/common");
+const db_backup_errors_1 = require("./db-backup.errors");
+const options_1 = require("./options");
+const ports_1 = require("./ports");
+/**
+ * Whether in-app restore is on, decided once at boot.
+ *
+ * @stability experimental
+ */
+let DbBackupRestoreGate = class DbBackupRestoreGate {
+    /** The deployment mode the gate was decided from (the option, else the port, else `self-hosted`). */
+    mode;
+    /** Whether the application may restore its own database here. */
+    inAppRestoreEnabled;
+    /**
+     * @param options - the resolved `forRoot()` options, when the module provides them.
+     * @param deployment - the app's deployment mode, when bound.
+     */
+    constructor(options, deployment) {
+        this.mode = options?.deploymentMode ?? deployment?.mode ?? 'self-hosted';
+        this.inAppRestoreEnabled = (0, options_1.resolveRestoreEnabled)(options ?? {}, deployment?.mode, deployment?.inAppRestoreEnabled);
+    }
+    /**
+     * The restore path's first statement.
+     *
+     * @throws {@link DatabaseRestoreDisabledError} when in-app restore is off (`saas`).
+     */
+    assertInAppRestoreEnabled() {
+        if (!this.inAppRestoreEnabled)
+            throw new db_backup_errors_1.DatabaseRestoreDisabledError();
+    }
+};
+exports.DbBackupRestoreGate = DbBackupRestoreGate;
+exports.DbBackupRestoreGate = DbBackupRestoreGate = __decorate([
+    (0, common_1.Injectable)(),
+    __param(0, (0, common_1.Optional)()),
+    __param(0, (0, common_1.Inject)(options_1.DB_BACKUP_OPTIONS)),
+    __param(1, (0, common_1.Optional)()),
+    __param(1, (0, common_1.Inject)(ports_1.DB_BACKUP_DEPLOYMENT_MODE)),
+    __metadata("design:paramtypes", [Object, Object])
+], DbBackupRestoreGate);
+/**
+ * A gate for a fixed answer, for a test or a script that builds the services
+ * by hand.
+ *
+ * @param mode - the deployment mode.
+ * @returns the gate.
+ * @stability experimental
+ */
+function restoreGateFor(mode = 'self-hosted') {
+    return new DbBackupRestoreGate({ deploymentMode: mode });
+}
+//# sourceMappingURL=restore-gate.js.map

package/dist/db-backup/restore-gate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"restore-gate.js","sourceRoot":"","sources":["../../src/db-backup/restore-gate.ts"],"names":[],"mappings":";AAAA,gFAAgF;AAChF,oEAAoE;AACpE,gFAAgF;AAChF,EAAE;AACF,6EAA6E;AAC7E,gFAAgF;AAChF,sEAAsE;AACtE,8EAA8E;AAC9E,6EAA6E;AAC7E,8DAA8D;AAC9D,gFAAgF;;;;;;;;;;;;;;;AAmDhF,wCAEC;AAnDD,2CAA8D;AAE9D,yDAAkE;AAClE,uCAAyG;AACzG,mCAAiF;AAEjF;;;;GAIG;AAEI,IAAM,mBAAmB,GAAzB,MAAM,mBAAmB;IAC9B,qGAAqG;IAC5F,IAAI,CAAyC;IAEtD,iEAAiE;IACxD,mBAAmB,CAAU;IAEtC;;;OAGG;IACH,YACyC,OAAuC,EAC/B,UAAmC;QAElF,IAAI,CAAC,IAAI,GAAG,OAAO,EAAE,cAAc,IAAI,UAAU,EAAE,IAAI,IAAI,aAAa,CAAC;QACzE,IAAI,CAAC,mBAAmB,GAAG,IAAA,+BAAqB,EAAC,OAAO,IAAI,EAAE,EAAE,UAAU,EAAE,IAAI,EAAE,UAAU,EAAE,mBAAmB,CAAC,CAAC;IACrH,CAAC;IAED;;;;OAIG;IACH,yBAAyB;QACvB,IAAI,CAAC,IAAI,CAAC,mBAAmB;YAAE,MAAM,IAAI,+CAA4B,EAAE,CAAC;IAC1E,CAAC;CACF,CAAA;AA3BY,kDAAmB;8BAAnB,mBAAmB;IAD/B,IAAA,mBAAU,GAAE;IAaR,WAAA,IAAA,iBAAQ,GAAE,CAAA;IAAE,WAAA,IAAA,eAAM,EAAC,2BAAiB,CAAC,CAAA;IACrC,WAAA,IAAA,iBAAQ,GAAE,CAAA;IAAE,WAAA,IAAA,eAAM,EAAC,iCAAyB,CAAC,CAAA;;GAbrC,mBAAmB,CA2B/B;AAED;;;;;;;GAOG;AACH,SAAgB,cAAc,CAAC,OAA+C,aAAa;IACzF,OAAO,IAAI,mBAAmB,CAAC,EAAE,cAAc,EAAE,IAAI,EAAmC,CAAC,CAAC;AAC5F,CAAC"}

package/dist/db-backup/restore-gate.registry.d.ts

@@ -0,0 +1,253 @@
+import type { SystemDatabaseBackupValue } from '@marinoscar/platform-contract/db-backup';
+import { type Registry } from '../core/index';
+import type { AdminConnection } from './admin-connection.util';
+import type { PgVersionCheck } from './pg-version.util';
+/**
+ * Longest a single gate may take before the pre-flight records it as failed.
+ *
+ * @stability experimental
+ */
+export declare const RESTORE_GATE_TIMEOUT_MS = 10000;
+/**
+ * What kind of problem a gate reports, which is what decides how a failure is
+ * handled.
+ *
+ *  - `capability` — this deployment cannot perform the automated restore. Fails
+ *    to `guided`, except the version pair; see that gate.
+ *  - `disk` — there is not room for something. Downgrades, never refuses.
+ *  - `replicas` — a heuristic about the deployment's shape. Warning only.
+ *  - `overridable` — a correctness question a human may answer. Blocks until
+ *    they do.
+ *  - `app` — an app gate. A `fail` blocks the restore outright.
+ *
+ * @stability experimental
+ */
+export type RestoreGateKind = 'capability' | 'disk' | 'replicas' | 'overridable' | 'app';
+/**
+ * One gate's answer.
+ *
+ * @stability experimental
+ */
+export interface RestoreGateOutcome {
+    /** `pass` and `warn` proceed (a warn is shown); `fail` blocks (see the file header for what a built-in `fail` does). */
+    readonly status: 'pass' | 'fail' | 'warn';
+    /** What was found, in one or two sentences an operator can act on. */
+    readonly message: string;
+    /** What to DO about it; absent or `null` when there is nothing to do. */
+    readonly action?: string | null;
+}
+/**
+ * One gate's verdict in the pre-flight result. `warning` is a pass that says
+ * something. (A gate's own answer is a {@link RestoreGateOutcome}; this is that
+ * answer as the result and the wire carry it: `pass` stays `pass`, `warn` becomes
+ * `warning` and `fail` becomes `block`.)
+ *
+ * @stability experimental
+ */
+export type RestoreGateVerdict = 'pass' | 'warning' | 'block';
+/**
+ * One gate's finding in the pre-flight result.
+ *
+ * EVERY GATE PRODUCES ONE OF THESE, INCLUDING THE ONES THAT PASSED: the
+ * restore dialog renders the whole list, so an operator about to replace their
+ * production database sees what was checked, not only what failed.
+ *
+ * @stability experimental
+ */
+export interface RestoreGateResult {
+    /** Id: a built-in's, or the id an app registered. */
+    id: string;
+    /** Kind. */
+    kind: RestoreGateKind;
+    /** Verdict. */
+    verdict: RestoreGateVerdict;
+    /** Short label, safe to render as a row heading. */
+    title: string;
+    /** What was found, in one or two sentences an operator can act on. */
+    detail: string;
+    /** What to DO about it, or `null` when there is nothing to do. */
+    action: string | null;
+}
+/**
+ * What a gate may know about the archive being restored: the run's fields,
+ * read-only, as plain values.
+ *
+ * @stability experimental
+ */
+export interface RestoreGateRun {
+    /** The backup run. */
+    readonly id: string;
+    /** The archive's key. */
+    readonly storageKey: string;
+    /** The target the archive lives on. */
+    readonly storageProvider: string;
+    /** The archive's size, as a decimal string. */
+    readonly sizeBytes: string;
+    /** The migration the archive was taken at, if recorded. */
+    readonly migrationName: string | null;
+    /** When the run was created. */
+    readonly createdAt: Date;
+}
+/**
+ * What the cluster probes found, for the built-in gates (and any app gate that
+ * wants the same facts). Every field survives a failed probe.
+ *
+ * @stability experimental
+ */
+export interface RestoreClusterFacts {
+    /** Whether the maintenance connection could be opened. */
+    readonly reachable: boolean;
+    /** Why it was not, when it was not. */
+    readonly error: string | null;
+    /** Whether the role may create databases; `null` when not read. */
+    readonly canCreateDatabase: boolean | null;
+    /** Extensions installed in the live database that this cluster cannot offer. */
+    readonly missingExtensions: readonly string[];
+    /** `null` when the extension check itself could not be performed. */
+    readonly checkedExtensions: number | null;
+    /** The live database's size, when read. */
+    readonly databaseSizeBytes: bigint | null;
+    /** The server's data directory, when visible. */
+    readonly dataDirectory: string | null;
+    /** Distinct client addresses holding sessions on the live database. */
+    readonly distinctClientAddresses: number | null;
+    /** How the session's role lifts row-level security; `null` when not read. */
+    readonly rlsBypass: {
+        /** The session's role is a superuser. */
+        readonly superuser: boolean;
+        /** The session's role has `BYPASSRLS`. */
+        readonly bypassRls: boolean;
+        /** `app.rls_bypass` was accepted by the connection. */
+        readonly optionApplied: boolean;
+    } | null;
+}
+/**
+ * The probes the pre-flight ran once, shared by every gate. A password is never
+ * part of them.
+ *
+ * @stability experimental
+ */
+export interface RestorePreflightFacts {
+    /** The PostgreSQL client/server version pair. */
+    readonly version: PgVersionCheck;
+    /** The cluster probes. */
+    readonly cluster: RestoreClusterFacts;
+    /** The admin connection's coordinates (host, port, user, databases): no password. */
+    readonly connection: Pick<AdminConnection, 'host' | 'port' | 'user' | 'database' | 'liveDatabase'>;
+    /** Free bytes where the server keeps its data, when readable from this process. */
+    readonly freeDiskBytes: bigint | null;
+    /** The archive's migration against the live one. */
+    readonly migrationComparison: 'match' | 'archive_older' | 'archive_newer' | 'unknown';
+}
+/**
+ * A read handle on the system settings a gate may consult. It cannot write.
+ *
+ * @stability experimental
+ */
+export interface RestoreGateSettings {
+    /**
+     * One system settings namespace's stored value, or `undefined` when no such
+     * namespace is registered (a gate that depends on an app setting stays inert
+     * until the app registers it).
+     *
+     * @param namespace - the namespace key.
+     */
+    get(namespace: string): Promise<Record<string, unknown> | undefined>;
+}
+/**
+ * What a gate is given. Everything on it is read-only.
+ *
+ * @stability experimental
+ */
+export interface RestoreGateContext {
+    /** The archive being restored. */
+    readonly run: RestoreGateRun;
+    /** The `databaseBackup` policy. */
+    readonly policy: SystemDatabaseBackupValue;
+    /** The pre-flight's clock. */
+    readonly now: Date;
+    /** The application's database: the one a restore would displace. */
+    readonly targetDatabase: string;
+    /** The migration live right now, if readable. */
+    readonly liveMigration: string | null;
+    /** Whether the caller asked to override the schema gate. */
+    readonly overrideSchemaMismatch: boolean;
+    /** Read-only system settings. */
+    readonly settings: RestoreGateSettings;
+    /** The probes the pre-flight already ran. */
+    readonly facts: RestorePreflightFacts;
+}
+/**
+ * One restore gate.
+ *
+ * @example
+ * ```ts
+ * registerRestoreGate({
+ *   id: 'cdn-quiesced',
+ *   label: 'CDN quiesced',
+ *   check: async (ctx) => ({ status: 'pass', message: 'ok' }),
+ * });
+ * ```
+ *
+ * @extensionPoint registry
+ * @stability experimental
+ */
+export interface RestoreGateDefinition {
+    /** Lowercase id (letters, digits, `_`, `-`; starts with a letter): `cdn-quiesced`. Unique. */
+    readonly id: string;
+    /** Short label, the row heading in the restore dialog. */
+    readonly label: string;
+    /** How a failure is handled; default `'app'` (a hard block). The built-ins declare their own. */
+    readonly kind?: RestoreGateKind;
+    /**
+     * Evaluates the gate. Read-only (see the file header); bounded by
+     * {@link RESTORE_GATE_TIMEOUT_MS}.
+     *
+     * @param ctx - the read-only context.
+     */
+    check(ctx: RestoreGateContext): Promise<RestoreGateOutcome>;
+}
+/**
+ * The registry of {@link RestoreGateDefinition} entries: the eight built-ins in
+ * their evaluation order, then the app's gates in registration order. A
+ * duplicate id is refused; frozen after bootstrap.
+ *
+ * @extensionPoint registry
+ * @stability experimental
+ */
+export declare const restoreGateRegistry: Registry<RestoreGateDefinition>;
+/**
+ * Registers one restore gate. Call it at import time, from a file the app
+ * imports before `NestFactory.create` (the reference app:
+ * `apps/api/src/app-registrations/db-backup.ts`).
+ *
+ * @param gate - the gate.
+ * @throws RegistryError on a duplicate id, an invalid gate or a frozen registry.
+ *
+ * @extensionPoint registry
+ * @stability experimental
+ */
+export declare function registerRestoreGate(gate: RestoreGateDefinition): void;
+/**
+ * One gate's outcome as the pre-flight's result row: a throw, a timeout or a
+ * malformed answer is a `fail` naming the gate (fail closed).
+ *
+ * @param gate - the definition.
+ * @param ctx - the read-only context.
+ * @param timeoutMs - the bound on the check.
+ * @returns the result row.
+ *
+ * @stability experimental
+ */
+export declare function evaluateRestoreGate(gate: RestoreGateDefinition, ctx: RestoreGateContext, timeoutMs?: number): Promise<RestoreGateResult>;
+/**
+ * Evaluates every registered gate, in registration order (the built-ins, then
+ * the app's), one at a time.
+ *
+ * @param ctx - the read-only context.
+ * @returns one result row per gate.
+ *
+ * @stability experimental
+ */
+export declare function evaluateRestoreGates(ctx: RestoreGateContext): Promise<RestoreGateResult[]>;
+//# sourceMappingURL=restore-gate.registry.d.ts.map

package/dist/db-backup/restore-gate.registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"restore-gate.registry.d.ts","sourceRoot":"","sources":["../../src/db-backup/restore-gate.registry.ts"],"names":[],"mappings":"AAmDA,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,yCAAyC,CAAC;AAEzF,OAAO,EAAkB,KAAK,QAAQ,EAAE,MAAM,eAAe,CAAC;AAC9D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAC/D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAExD;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,QAAS,CAAC;AAE9C;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,eAAe,GAAG,YAAY,GAAG,MAAM,GAAG,UAAU,GAAG,aAAa,GAAG,KAAK,CAAC;AAEzF;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC,wHAAwH;IACxH,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,CAAC;IAC1C,sEAAsE;IACtE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,yEAAyE;IACzE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACjC;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,kBAAkB,GAAG,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC;AAE9D;;;;;;;;GAQG;AACH,MAAM,WAAW,iBAAiB;IAChC,qDAAqD;IACrD,EAAE,EAAE,MAAM,CAAC;IACX,YAAY;IACZ,IAAI,EAAE,eAAe,CAAC;IACtB,eAAe;IACf,OAAO,EAAE,kBAAkB,CAAC;IAC5B,oDAAoD;IACpD,KAAK,EAAE,MAAM,CAAC;IACd,sEAAsE;IACtE,MAAM,EAAE,MAAM,CAAC;IACf,kEAAkE;IAClE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CACvB;AAED;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC7B,sBAAsB;IACtB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,yBAAyB;IACzB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,uCAAuC;IACvC,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,+CAA+C;IAC/C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,2DAA2D;IAC3D,QAAQ,CAAC,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IACtC,gCAAgC;IAChC,QAAQ,CAAC,SAAS,EAAE,IAAI,CAAC;CAC1B;AAED;;;;;GAKG;AACH,MAAM,WAAW,mBAAmB;IAClC,0DAA0D;IAC1D,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,uCAAuC;IACvC,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,mEAAmE;IACnE,QAAQ,CAAC,iBAAiB,EAAE,OAAO,GAAG,IAAI,CAAC;IAC3C,gFAAgF;IAChF,QAAQ,CAAC,iBAAiB,EAAE,SAAS,MAAM,EAAE,CAAC;IAC9C,qEAAqE;IACrE,QAAQ,CAAC,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1C,2CAA2C;IAC3C,QAAQ,CAAC,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1C,iDAAiD;IACjD,QAAQ,CAAC,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IACtC,uEAAuE;IACvE,QAAQ,CAAC,uBAAuB,EAAE,MAAM,GAAG,IAAI,CAAC;IAChD,6EAA6E;IAC7E,QAAQ,CAAC,SAAS,EAAE;QAClB,yCAAyC;QACzC,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;QAC5B,0CAA0C;QAC1C,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;QAC5B,uDAAuD;QACvD,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;KACjC,GAAG,IAAI,CAAC;CACV;AAED;;;;;GAKG;AACH,MAAM,WAAW,qBAAqB;IACpC,iDAAiD;IACjD,QAAQ,CAAC,OAAO,EAAE,cAAc,CAAC;IACjC,0BAA0B;IAC1B,QAAQ,CAAC,OAAO,EAAE,mBAAmB,CAAC;IACtC,qFAAqF;IACrF,QAAQ,CAAC,UAAU,EAAE,IAAI,CAAC,eAAe,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,UAAU,GAAG,cAAc,CAAC,CAAC;IACnG,mFAAmF;IACnF,QAAQ,CAAC,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IACtC,oDAAoD;IACpD,QAAQ,CAAC,mBAAmB,EAAE,OAAO,GAAG,eAAe,GAAG,eAAe,GAAG,SAAS,CAAC;CACvF;AAED;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;;;;OAMG;IACH,GAAG,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC,CAAC;CACtE;AAED;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC,kCAAkC;IAClC,QAAQ,CAAC,GAAG,EAAE,cAAc,CAAC;IAC7B,mCAAmC;IACnC,QAAQ,CAAC,MAAM,EAAE,yBAAyB,CAAC;IAC3C,8BAA8B;IAC9B,QAAQ,CAAC,GAAG,EAAE,IAAI,CAAC;IACnB,oEAAoE;IACpE,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,iDAAiD;IACjD,QAAQ,CAAC,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IACtC,4DAA4D;IAC5D,QAAQ,CAAC,sBAAsB,EAAE,OAAO,CAAC;IACzC,iCAAiC;IACjC,QAAQ,CAAC,QAAQ,EAAE,mBAAmB,CAAC;IACvC,6CAA6C;IAC7C,QAAQ,CAAC,KAAK,EAAE,qBAAqB,CAAC;CACvC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,qBAAqB;IACpC,8FAA8F;IAC9F,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,0DAA0D;IAC1D,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,iGAAiG;IACjG,QAAQ,CAAC,IAAI,CAAC,EAAE,eAAe,CAAC;IAChC;;;;;OAKG;IACH,KAAK,CAAC,GAAG,EAAE,kBAAkB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAAC;CAC7D;AAwBD;;;;;;;GAOG;AACH,eAAO,MAAM,mBAAmB,EAAE,QAAQ,CAAC,qBAAqB,CAS9D,CAAC;AAEH;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,qBAAqB,GAAG,IAAI,CAErE;AAaD;;;;;;;;;;GAUG;AACH,wBAAsB,mBAAmB,CACvC,IAAI,EAAE,qBAAqB,EAC3B,GAAG,EAAE,kBAAkB,EACvB,SAAS,GAAE,MAAgC,GAC1C,OAAO,CAAC,iBAAiB,CAAC,CAmC5B;AAED;;;;;;;;GAQG;AACH,wBAAsB,oBAAoB,CAAC,GAAG,EAAE,kBAAkB,GAAG,OAAO,CAAC,iBAAiB,EAAE,CAAC,CAIhG"}

package/dist/db-backup/restore-gate.registry.js

@@ -0,0 +1,182 @@
+"use strict";
+// =============================================================================
+// The restore gate registry (PP-14.12)
+// =============================================================================
+//
+// A restore either works or it destroys the production database, and almost
+// everything that can go wrong is knowable BEFORE anything is created. The
+// pre-flight (`restore-preflight.service.ts`) asks a list of GATES; each answers
+// pass, warn or fail. The list is a registry, so an app adds a gate of its own
+// ("is the CDN quiesced?", "is the nightly ETL idle?") without editing the
+// pre-flight:
+//
+//   registerRestoreGate({
+//     id: 'cdn-quiesced',
+//     label: 'CDN quiesced',
+//     async check(ctx) {
+//       const cdn = await ctx.settings.get('cdn');
+//       return cdn?.quiesced ? { status: 'pass', message: 'The CDN is quiesced.' }
+//                            : { status: 'fail', message: 'Quiesce the CDN first.', action: 'Pause the CDN, then retry.' };
+//     },
+//   });
+//
+// The eight gates the platform ships (`BUILTIN_RESTORE_GATE_IDS`) register
+// through the same function (`restore-gates.builtin.ts`), in their historical
+// order; app gates run after them, in registration order.
+//
+// -----------------------------------------------------------------------------
+// THE RULES A GATE HONOURS (the `describeRestoreGateConformance` kit asserts them)
+// -----------------------------------------------------------------------------
+//
+//   1. A GATE IS READ-ONLY. It creates, drops, renames and alters nothing: not
+//      in the database, not on disk, not in a remote system. An operator asks
+//      "can I restore this?" precisely when they have not decided to, and a
+//      question that leaves something half-changed is a question nobody can
+//      afford to ask. The context hands a gate only read handles (`settings.get`,
+//      `facts`); the kit runs it against a context whose every mutating member
+//      records a violation, and against a client that records every SQL
+//      statement it is given.
+//   2. A GATE ANSWERS. It returns `pass`, `warn` or `fail` with a message an
+//      operator can act on; it does not throw for an expected condition.
+//   3. A THROW OR A TIMEOUT IS A `fail`. A gate that cannot be evaluated blocks
+//      the restore (fail closed) with a message naming the gate: "unknown" must
+//      not read as "safe" on the path that replaces the database. Every gate is
+//      bounded by `RESTORE_GATE_TIMEOUT_MS`.
+//   4. WHAT EACH STATUS DOES. `pass` and `warn` let the restore proceed (a warn
+//      is a pass that says something and is shown to the operator). `fail` from
+//      an app gate BLOCKS the restore, and cannot be overridden from the
+//      request: the override (`overrideSchemaCheck`) answers the schema gate
+//      only. A built-in gate's `fail` follows its own kind (see `RestoreGateKind`).
+// =============================================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.restoreGateRegistry = exports.RESTORE_GATE_TIMEOUT_MS = void 0;
+exports.registerRestoreGate = registerRestoreGate;
+exports.evaluateRestoreGate = evaluateRestoreGate;
+exports.evaluateRestoreGates = evaluateRestoreGates;
+const db_backup_1 = require("@marinoscar/platform-contract/db-backup");
+const index_1 = require("../core/index");
+/**
+ * Longest a single gate may take before the pre-flight records it as failed.
+ *
+ * @stability experimental
+ */
+exports.RESTORE_GATE_TIMEOUT_MS = 10_000;
+function assertGate(gate) {
+    if (!db_backup_1.RESTORE_GATE_ID_PATTERN.test(gate.id)) {
+        throw new Error(`restore gate id ${JSON.stringify(gate.id)} must match ${db_backup_1.RESTORE_GATE_ID_PATTERN} (lowercase letters, digits, "_" and "-", starting with a letter)`);
+    }
+    if (typeof gate.label !== 'string' || gate.label.trim() === '') {
+        throw new Error(`restore gate "${gate.id}" needs a non-empty label`);
+    }
+    if (typeof gate.check !== 'function') {
+        throw new Error(`restore gate "${gate.id}" needs a check(ctx) function`);
+    }
+    if (gate.kind !== undefined && !['capability', 'disk', 'replicas', 'overridable', 'app'].includes(gate.kind)) {
+        throw new Error(`restore gate "${gate.id}" has an unknown kind ${JSON.stringify(gate.kind)}`);
+    }
+}
+function gateRank(gate) {
+    const index = db_backup_1.BUILTIN_RESTORE_GATE_IDS.indexOf(gate.id);
+    return index === -1 ? db_backup_1.BUILTIN_RESTORE_GATE_IDS.length : index;
+}
+/**
+ * The registry of {@link RestoreGateDefinition} entries: the eight built-ins in
+ * their evaluation order, then the app's gates in registration order. A
+ * duplicate id is refused; frozen after bootstrap.
+ *
+ * @extensionPoint registry
+ * @stability experimental
+ */
+exports.restoreGateRegistry = (0, index_1.defineRegistry)({
+    name: 'db-backup-restore-gates',
+    idOf: (gate) => gate.id,
+    idPattern: db_backup_1.RESTORE_GATE_ID_PATTERN,
+    validate: (gate) => assertGate(gate),
+    // The built-ins first, in their historical order, WHATEVER THE IMPORT ORDER
+    // was; every other gate after them, in registration order (the sort is
+    // stable, so equal ranks keep it).
+    order: (a, b) => gateRank(a) - gateRank(b),
+});
+/**
+ * Registers one restore gate. Call it at import time, from a file the app
+ * imports before `NestFactory.create` (the reference app:
+ * `apps/api/src/app-registrations/db-backup.ts`).
+ *
+ * @param gate - the gate.
+ * @throws RegistryError on a duplicate id, an invalid gate or a frozen registry.
+ *
+ * @extensionPoint registry
+ * @stability experimental
+ */
+function registerRestoreGate(gate) {
+    exports.restoreGateRegistry.register(gate);
+}
+function withTimeout(work, ms, what) {
+    let timer;
+    const timeout = new Promise((_resolve, reject) => {
+        timer = setTimeout(() => reject(new Error(`${what} did not answer within ${ms} ms`)), ms);
+        timer.unref?.();
+    });
+    return Promise.race([work, timeout]).finally(() => {
+        if (timer !== undefined)
+            clearTimeout(timer);
+    });
+}
+/**
+ * One gate's outcome as the pre-flight's result row: a throw, a timeout or a
+ * malformed answer is a `fail` naming the gate (fail closed).
+ *
+ * @param gate - the definition.
+ * @param ctx - the read-only context.
+ * @param timeoutMs - the bound on the check.
+ * @returns the result row.
+ *
+ * @stability experimental
+ */
+async function evaluateRestoreGate(gate, ctx, timeoutMs = exports.RESTORE_GATE_TIMEOUT_MS) {
+    const kind = gate.kind ?? 'app';
+    let outcome;
+    try {
+        outcome = await withTimeout(Promise.resolve().then(() => gate.check(ctx)), timeoutMs, `Restore gate "${gate.id}"`);
+        if (typeof outcome !== 'object' ||
+            outcome === null ||
+            !['pass', 'warn', 'fail'].includes(outcome.status) ||
+            typeof outcome.message !== 'string') {
+            throw new Error(`Restore gate "${gate.id}" returned an answer that is not { status: 'pass' | 'warn' | 'fail', message }`);
+        }
+    }
+    catch (error) {
+        return {
+            id: gate.id,
+            kind,
+            verdict: 'block',
+            title: gate.label,
+            detail: `The "${gate.label}" check could not be evaluated, so the restore is held back: ${error instanceof Error ? error.message : String(error)}`,
+            action: 'Fix the check, or ask whoever registered it, then run the pre-flight again.',
+        };
+    }
+    return {
+        id: gate.id,
+        kind,
+        verdict: outcome.status === 'fail' ? 'block' : outcome.status === 'warn' ? 'warning' : 'pass',
+        title: gate.label,
+        detail: outcome.message,
+        action: outcome.action ?? null,
+    };
+}
+/**
+ * Evaluates every registered gate, in registration order (the built-ins, then
+ * the app's), one at a time.
+ *
+ * @param ctx - the read-only context.
+ * @returns one result row per gate.
+ *
+ * @stability experimental
+ */
+async function evaluateRestoreGates(ctx) {
+    const results = [];
+    for (const gate of exports.restoreGateRegistry.list())
+        results.push(await evaluateRestoreGate(gate, ctx));
+    return results;
+}
+//# sourceMappingURL=restore-gate.registry.js.map

package/dist/db-backup/restore-gate.registry.js.map

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