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

package/dist/db-backup/pg-version.util.js

@@ -0,0 +1,310 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CLIENT_VERSION_TIMEOUT_MS = exports.MIN_PG_CLIENT_MAJOR = void 0;
+exports.parsePgClientMajor = parsePgClientMajor;
+exports.parseServerVersionNum = parseServerVersionNum;
+exports.serverMajorFromVersionNum = serverMajorFromVersionNum;
+exports.readPgClientVersion = readPgClientVersion;
+exports.readServerVersionNumWithPgClient = readServerVersionNumWithPgClient;
+exports.checkPgClientVersion = checkPgClientVersion;
+const pg_1 = require("pg");
+const index_1 = require("../core/index");
+const pg_dump_util_1 = require("./pg-dump.util");
+// =============================================================================
+// The client/server version guard (issue #280, epic #254)
+// =============================================================================
+//
+// `pg_dump` REFUSES to dump a server newer than itself. That is not a warning
+// and not a degraded mode — it is a hard error, on every invocation, forever,
+// and the deployment that hits it is a deployment whose backups all fail
+// silently from the day someone upgraded the server.
+//
+// This template is unusually exposed to it. `infra/compose/base.compose.yml`
+// declares NO `db` service: the application's PostgreSQL is EXTERNAL, managed
+// by the operator or by a cloud provider, and the client lives in the API
+// image (`apps/api/Dockerfile`). Those two things are upgraded by different
+// people, on different schedules, through different mechanisms. A managed
+// provider can move a server's major in a maintenance window nobody in this
+// repository hears about.
+//
+// So the version pair is checked BEFORE a dump starts, and the check has two
+// deliberately asymmetric outcomes:
+//
+//   - `client < server`  → BLOCK. The dump cannot succeed; running it would
+//     produce a failed run whose error message is `pg_dump`'s rather than one
+//     that says what to do. Blocking early is how the operator gets told to
+//     rebuild the image with a newer client instead of being told "server
+//     version 18.1; pg_dump version 17.4".
+//   - ANYTHING UNREADABLE → WARN AND PROCEED. An unparseable `--version`
+//     banner, a `server_version_num` that comes back as something unexpected,
+//     a query that fails: none of these are evidence that the backup would
+//     fail, and AN UNPARSEABLE VERSION STRING MUST NEVER BE THE REASON A
+//     BACKUP DID NOT HAPPEN. The check is a guard rail, not a gate; failing
+//     open here costs a confusing error later, while failing closed costs
+//     every backup from now on.
+//
+// The client's own major is also compared against {@link MIN_PG_CLIENT_MAJOR},
+// which `test/pg-client-version.spec.ts` holds equal to the pin in the
+// Dockerfile. See docs/runbooks/postgres-client-version.md.
+// =============================================================================
+/**
+ * The PostgreSQL client major this image is built with.
+ *
+ * ⚠ THIS NUMBER AND THE `postgresql<N>-client` PIN IN `apps/api/Dockerfile`
+ * ARE ONE DECISION. `test/pg-client-version.spec.ts` asserts they are equal,
+ * so changing either alone fails the suite — which is the whole guard: the
+ * Dockerfile line is edited by whoever is fixing an image, this constant is
+ * read by whoever is debugging a backup, and nothing else would ever bring the
+ * two people together.
+ *
+ * @stability experimental
+ */
+exports.MIN_PG_CLIENT_MAJOR = 17;
+/**
+ * Pulls the major out of a `pg_dump --version` banner.
+ *
+ * The banner has been `pg_dump (PostgreSQL) <version>` for the whole of the
+ * period this code can encounter, but packagers append to it freely
+ * (`pg_dump (PostgreSQL) 17.4 (Ubuntu 17.4-1.pgdg24.04+2)`), so this takes the
+ * FIRST version-looking number rather than trying to match the whole line.
+ * Both the modern `17.4` and the pre-10 `9.6.24` shapes reduce to their major
+ * correctly.
+ *
+ * Returns `null` for anything it cannot read, which the caller turns into
+ * "warn and proceed" — never into a failure.
+ *
+ * @stability experimental
+ */
+function parsePgClientMajor(output) {
+    if (output === null || output === undefined)
+        return null;
+    const match = /(\d+)(?:\.\d+)*/.exec(output);
+    if (match === null)
+        return null;
+    const major = Number.parseInt(match[1], 10);
+    // A sanity bound, not a policy: `pg_dump 0` or `pg_dump 4200` means this
+    // parsed something that was not a version, and reporting a nonsense major
+    // would produce a nonsense block.
+    if (!Number.isInteger(major) || major < 1 || major > 999)
+        return null;
+    return major;
+}
+/**
+ * Normalises whatever a raw query returned into a `server_version_num` integer.
+ *
+ * Accepts a string, a number or a bigint because all three genuinely occur:
+ * `server_version_num` is a `text` setting in `pg_settings`,
+ * `SHOW server_version_num` returns text, and drivers differ on what they do
+ * with `current_setting(...)::int`. Handling the union here is what keeps the
+ * call site from having to know which it got.
+ *
+ * @stability experimental
+ */
+function parseServerVersionNum(value) {
+    const numeric = typeof value === 'bigint'
+        ? Number(value)
+        : typeof value === 'number'
+            ? value
+            : typeof value === 'string'
+                ? Number.parseInt(value, 10)
+                : Number.NaN;
+    if (!Number.isFinite(numeric) || numeric <= 0)
+        return null;
+    return Math.trunc(numeric);
+}
+/**
+ * Converts `server_version_num` to a major.
+ *
+ * PostgreSQL packs the number as `major * 10000 + minor` from 10 onwards
+ * (`170004` → 17) and as `major * 10000 + minor * 100 + patch` before it
+ * (`90624` → 9). Integer division by 10000 is correct for both, which is why
+ * there is no special case here for the older shape.
+ *
+ * @stability experimental
+ */
+function serverMajorFromVersionNum(versionNum) {
+    if (versionNum === null || !Number.isFinite(versionNum) || versionNum <= 0)
+        return null;
+    const major = Math.floor(versionNum / 10000);
+    return major >= 1 && major <= 999 ? major : null;
+}
+/**
+ * How long `pg_dump --version` is given.
+ *
+ * It prints a line and exits; it opens no socket and reads no file. Anything
+ * that takes longer than a few seconds is a broken or missing binary, and the
+ * whole point of this reader is to answer quickly and never to be the thing
+ * that hangs a backup.
+ *
+ * @stability experimental
+ */
+exports.CLIENT_VERSION_TIMEOUT_MS = 10_000;
+/**
+ * Runs `pg_dump --version` and returns its output, or `null` if it could not
+ * be run.
+ *
+ * NEVER THROWS, deliberately. Every failure — the binary is missing, it is not
+ * executable, it timed out — becomes `null`, which becomes the `unknown`
+ * status, which proceeds. The output is bounded because the reader only ever
+ * needs the first line and a wedged binary streaming megabytes at us is not a
+ * reason to grow the heap.
+ *
+ * @stability experimental
+ */
+async function readPgClientVersion(options = {}) {
+    const child = (0, pg_dump_util_1.spawnPgProcess)({
+        command: options.command ?? pg_dump_util_1.PG_DUMP_COMMAND,
+        args: ['--version'],
+        timeoutMs: options.timeoutMs ?? exports.CLIENT_VERSION_TIMEOUT_MS,
+        spawnFn: options.spawnFn,
+    });
+    let output = '';
+    try {
+        for await (const chunk of child.stdout) {
+            output += String(chunk);
+            if (output.length >= 1024) {
+                child.kill('SIGKILL');
+                break;
+            }
+        }
+        await child.done;
+    }
+    catch {
+        // A non-zero exit with usable output on stdout is still an answer; an
+        // empty one is `null` by the return below.
+    }
+    return output === '' ? null : output;
+}
+const defaultPgClientFactory = (connectionString) => new pg_1.Client({ connectionString });
+/**
+ * Reads `server_version_num` over a short-lived connection of its own.
+ *
+ * A {@link ServerVersionNumReader} for callers that do not want to spend a
+ * Prisma query on it (or cannot - see the note above). It always closes the
+ * connection, including on failure: a version probe that leaks a connection
+ * every night is a slow way to exhaust `max_connections` on the very server
+ * the backups are protecting.
+ *
+ * Returns `null` rather than throwing on any failure, because its one consumer
+ * ({@link checkPgClientVersion}) treats an unreadable version as "warn and
+ * proceed" and nothing else should be able to turn it into a blocked backup.
+ *
+ * @stability experimental
+ */
+async function readServerVersionNumWithPgClient(options = {}) {
+    const factory = options.clientFactory ?? defaultPgClientFactory;
+    const client = factory((0, index_1.buildDatabaseUrl)(options.env ?? process.env));
+    try {
+        await client.connect();
+        const result = await client.query('SHOW server_version_num');
+        return parseServerVersionNum(result.rows[0]?.server_version_num);
+    }
+    catch {
+        return null;
+    }
+    finally {
+        // `end()` on a client that never connected rejects in some versions; this
+        // probe's whole contract is that it cannot throw.
+        await client.end().catch(() => undefined);
+    }
+}
+/**
+ * Compares the installed client against the server it would have to dump.
+ *
+ * @returns `blocked` only when BOTH majors are known and the client is the
+ * older one. Every other uncertainty is `unknown`, which the caller logs and
+ * ignores — see the module header for why this fails open.
+ *
+ * @stability experimental
+ */
+async function checkPgClientVersion(options) {
+    const readClient = options.readClientVersion ?? (() => readPgClientVersion());
+    // KEPT, not just parsed. The banner is the part a human reads; the major is
+    // the part this function compares. Reading it twice would run `pg_dump
+    // --version` twice for one backup, and the second read could disagree with
+    // the first on a host mid-upgrade.
+    const client = normaliseBanner(await readSafely(readClient));
+    const clientMajor = parsePgClientMajor(client);
+    const serverMajor = serverMajorFromVersionNum(await readSafely(options.readServerVersionNum));
+    if (clientMajor === null || serverMajor === null) {
+        return {
+            status: 'unknown',
+            client,
+            clientMajor,
+            serverMajor,
+            message: 'Could not determine the PostgreSQL version pair ' +
+                `(client: ${describe(clientMajor)}, server: ${describe(serverMajor)}). ` +
+                'Proceeding without the client/server compatibility check; if the backup then fails ' +
+                'with a version error, see docs/runbooks/postgres-client-version.md.',
+        };
+    }
+    if (clientMajor < serverMajor) {
+        return {
+            status: 'blocked',
+            client,
+            clientMajor,
+            serverMajor,
+            message: `The PostgreSQL client in this image is major ${clientMajor}, but the server is major ` +
+                `${serverMajor}. pg_dump refuses to dump a server newer than itself, so no backup can ` +
+                `succeed until the image is rebuilt with a postgresql${serverMajor}-client (or newer) ` +
+                'package: update the apk pin in apps/api/Dockerfile and MIN_PG_CLIENT_MAJOR in ' +
+                'packages/platform-api/src/db-backup/pg-version.util.ts together, then redeploy. See ' +
+                'docs/runbooks/postgres-client-version.md.',
+        };
+    }
+    return {
+        status: 'ok',
+        client,
+        clientMajor,
+        serverMajor,
+        message: `PostgreSQL client major ${clientMajor} can dump server major ${serverMajor}.`,
+        // Not a block: a client older than the pin still dumps this server
+        // correctly. It does mean the running image is not the one this build
+        // expects — an old image left behind by a partial deploy, or a `command`
+        // override pointing at a system binary — which is worth one log line.
+        ...(clientMajor < exports.MIN_PG_CLIENT_MAJOR
+            ? {
+                warning: `The PostgreSQL client is major ${clientMajor}, older than the ${exports.MIN_PG_CLIENT_MAJOR} ` +
+                    'this build pins in apps/api/Dockerfile. The current server is dumpable, but the ' +
+                    'image is not the one this build expects.',
+            }
+            : {}),
+    };
+}
+/**
+ * One trimmed line, bounded — or `null`.
+ *
+ * BOUNDED AT 128 CHARACTERS because this string is written to a database
+ * column and, on the node path, arrives from off-machine (the result contract
+ * caps it at the same width). `pg_dump --version` prints one short line; a
+ * wrapper script that prints a page of banner must not be able to put a page
+ * in every backup row.
+ */
+function normaliseBanner(value) {
+    if (value === null)
+        return null;
+    const line = value.split('\n')[0]?.trim() ?? '';
+    return line === '' ? null : line.slice(0, 128);
+}
+/** `17`, or `unknown` — used only to build messages. */
+function describe(major) {
+    return major === null ? 'unknown' : String(major);
+}
+/**
+ * Runs a reader, turning any rejection into `null`.
+ *
+ * The server reader is a database call made by a backup that is about to
+ * happen; a transient failure of that ONE query must not be what stops it. The
+ * `unknown` path it falls into already says so in its message.
+ */
+async function readSafely(reader) {
+    if (reader === undefined)
+        return null;
+    try {
+        return await reader();
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=pg-version.util.js.map

package/dist/db-backup/pg-version.util.js.map

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

package/dist/db-backup/ports.d.ts

@@ -0,0 +1,212 @@
+/**
+ * Injection token of the app's {@link DbBackupNotifier}. Required.
+ *
+ * @example
+ * ```ts
+ * // DbBackupHostModule: { provide: DB_BACKUP_NOTIFIER, useExisting: NotificationsService }
+ * ```
+ *
+ * @extensionPoint token
+ * @stability experimental
+ */
+export declare const DB_BACKUP_NOTIFIER: unique symbol;
+/**
+ * Options of {@link DbBackupNotifier.notifyPermissionHoldersNow}.
+ *
+ * @stability experimental
+ */
+export interface DbBackupNotifyOptions {
+    /** Users notified besides the permission holders (the restore's actor), de-duplicated. */
+    alsoNotifyUserIds?: readonly string[];
+}
+/**
+ * The app's notification dispatcher, as the slice raises its two events
+ * (`db_backup.backup_failed`, `db_backup.restore_completed`). The reference
+ * app binds its `NotificationsService`; the events and their templates are
+ * declared by the app's notification registry.
+ *
+ * Both are called AFTER the triggering write committed and outside any
+ * transaction (CLAUDE.md, `notify()` rule).
+ *
+ * @stability experimental
+ */
+export interface DbBackupNotifier {
+    /**
+     * Fire-and-forget: notifies every holder of `permission`. Must never reject
+     * (the slice still attaches a `.catch`).
+     *
+     * @param event - the event key.
+     * @param permission - the permission whose holders are notified (`db_backup:read`).
+     * @param payload - the template data.
+     */
+    notifyPermissionHolders(event: string, permission: string, payload: object): Promise<unknown>;
+    /**
+     * Awaited dispatch: resolves once every channel has been attempted. The
+     * restore calls it immediately before `process.exit(0)`, so a detached form
+     * would lose the one notification that cannot be turned off.
+     *
+     * @param event - the event key.
+     * @param permission - the permission whose holders are notified.
+     * @param payload - the template data.
+     * @param options - extra recipients.
+     */
+    notifyPermissionHoldersNow(
+    /** Event. */
+    event: string, 
+    /** Permission. */
+    permission: string, 
+    /** Payload. */
+    payload: object, 
+    /** Options. */
+    options?: DbBackupNotifyOptions): Promise<unknown>;
+}
+/**
+ * Injection token of the app's {@link DbBackupMaintenance}. Required.
+ *
+ * @example
+ * ```ts
+ * // DbBackupHostModule: { provide: DB_BACKUP_MAINTENANCE, useExisting: MaintenanceModeService }
+ * ```
+ *
+ * @extensionPoint token
+ * @stability experimental
+ */
+export declare const DB_BACKUP_MAINTENANCE: unique symbol;
+/**
+ * An in-memory maintenance override, as the restore sets it for its swap.
+ *
+ * @stability experimental
+ */
+export interface DbBackupMaintenanceOverride {
+    /** Whether the gate is closed. */
+    enabled: boolean;
+    /** The banner text. */
+    message?: string;
+    /** Whether administrators pass the gate. */
+    allowAdmins?: boolean;
+}
+/**
+ * The app's maintenance mode, as the restore uses it: an in-memory override
+ * for the swap window (the settings row is about to be replaced by the
+ * archive's, so it cannot carry the gate). The reference app binds its
+ * `MaintenanceModeService`.
+ *
+ * @stability experimental
+ */
+export interface DbBackupMaintenance {
+    /**
+     * Sets (or, with `null`, clears) this process's in-memory override.
+     *
+     * @param override - the override, or `null`.
+     */
+    setInMemoryOverride(override: DbBackupMaintenanceOverride | null): void;
+}
+/**
+ * Injection token of the app's {@link DbBackupMetrics}. Optional: without it
+ * the slice records nothing.
+ *
+ * @example
+ * ```ts
+ * // DbBackupHostModule: { provide: DB_BACKUP_METRICS, useExisting: AppMetricsService }
+ * ```
+ *
+ * @extensionPoint token
+ * @stability experimental
+ */
+export declare const DB_BACKUP_METRICS: unique symbol;
+/**
+ * The app's backup instruments (`app.backup.*`, declared by
+ * `DB_BACKUP_APP_METRICS`). The reference app binds its `AppMetricsService`
+ * (same instruments, same labels as before the move).
+ *
+ * @stability experimental
+ */
+export interface DbBackupMetrics {
+    /**
+     * A backup run settled.
+     *
+     * @param outcome - `'completed'` or `'failed'`.
+     * @param durationMs - start to settlement, or `null` when unknown.
+     * @param sizeBytes - the archive size, recorded for a completed run only.
+     */
+    backupSettled(outcome: 'completed' | 'failed', durationMs: number | null, sizeBytes?: number | bigint | null): void;
+}
+/**
+ * The metrics used when the app binds none: every call is a no-op.
+ *
+ * @stability experimental
+ */
+export declare const NOOP_DB_BACKUP_METRICS: DbBackupMetrics;
+/**
+ * Injection token of the app's {@link DbBackupDeploymentMode}. Optional:
+ * without it (and without the `deploymentMode` / `restoreEnabled` options) the
+ * deployment is `self-hosted` and in-app restore is on.
+ *
+ * @example
+ * ```ts
+ * // DbBackupHostModule: { provide: DB_BACKUP_DEPLOYMENT_MODE, useExisting: DeploymentModeService }
+ * ```
+ *
+ * @extensionPoint token
+ * @stability experimental
+ */
+export declare const DB_BACKUP_DEPLOYMENT_MODE: unique symbol;
+/**
+ * The deployment mode, as the slice reads it once at boot (`DEPLOYMENT_MODE`,
+ * #685). `saas` turns in-app restore off; backups keep working.
+ *
+ * @stability experimental
+ */
+export interface DbBackupDeploymentMode {
+    /** `'self-hosted'`, `'saas'` or the id of a mode the app registered. */
+    readonly mode: 'self-hosted' | 'saas' | (string & {});
+    /**
+     * Whether the mode permits in-app restore (the host's `inAppRestore`
+     * capability, `DeploymentModeService.inAppRestoreEnabled`). When present it
+     * decides; when absent only `saas` turns restore off.
+     */
+    readonly inAppRestoreEnabled?: boolean;
+}
+/**
+ * Injection token of the app's {@link DbBackupSystemData}: the bypass client.
+ * Required by the `backup.rls-bypass` Doctor check only.
+ *
+ * @example
+ * ```ts
+ * // DbBackupHostModule: { provide: DB_BACKUP_SYSTEM_DATA, useExisting: PrismaSystemService }
+ * ```
+ *
+ * @extensionPoint token
+ * @stability experimental
+ */
+export declare const DB_BACKUP_SYSTEM_DATA: unique symbol;
+/**
+ * The transaction client the bypass client hands its callback.
+ *
+ * @stability experimental
+ */
+export interface DbBackupSystemTx {
+    /**
+     * An unsafe raw query (the check's table names come from a closed list).
+     *
+     * @param query - the SQL.
+     */
+    $queryRawUnsafe<T = unknown>(query: string): Promise<T>;
+}
+/**
+ * The app's bypass client (`PrismaSystemService`), as the Doctor's
+ * `backup.rls-bypass` check uses it: one transaction with `app.rls_bypass`
+ * set transaction-locally, under a named reason.
+ *
+ * @stability experimental
+ */
+export interface DbBackupSystemData {
+    /**
+     * Runs `fn` in one transaction that bypasses row-level security.
+     *
+     * @param reason - the `SystemAccessReason` (`'doctor'`).
+     * @param fn - the unit of work.
+     */
+    runAsSystem<T>(reason: 'doctor', fn: (tx: DbBackupSystemTx) => Promise<T>): Promise<T>;
+}
+//# sourceMappingURL=ports.d.ts.map

package/dist/db-backup/ports.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ports.d.ts","sourceRoot":"","sources":["../../src/db-backup/ports.ts"],"names":[],"mappings":"AAsBA;;;;;;;;;;GAUG;AACH,eAAO,MAAM,kBAAkB,EAAE,OAAO,MAA8D,CAAC;AAEvG;;;;GAIG;AACH,MAAM,WAAW,qBAAqB;IACpC,0FAA0F;IAC1F,iBAAiB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACvC;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;;;;;OAOG;IACH,uBAAuB,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAC9F;;;;;;;;;OASG;IACH,0BAA0B;IACxB,aAAa;IACb,KAAK,EAAE,MAAM;IACb,kBAAkB;IAClB,UAAU,EAAE,MAAM;IAClB,eAAe;IACf,OAAO,EAAE,MAAM;IACf,eAAe;IACf,OAAO,CAAC,EAAE,qBAAqB,GAC9B,OAAO,CAAC,OAAO,CAAC,CAAC;CACrB;AAID;;;;;;;;;;GAUG;AACH,eAAO,MAAM,qBAAqB,EAAE,OAAO,MAAiE,CAAC;AAE7G;;;;GAIG;AACH,MAAM,WAAW,2BAA2B;IAC1C,kCAAkC;IAClC,OAAO,EAAE,OAAO,CAAC;IACjB,uBAAuB;IACvB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,4CAA4C;IAC5C,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;;OAIG;IACH,mBAAmB,CAAC,QAAQ,EAAE,2BAA2B,GAAG,IAAI,GAAG,IAAI,CAAC;CACzE;AAID;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,iBAAiB,EAAE,OAAO,MAA6D,CAAC;AAErG;;;;;;GAMG;AACH,MAAM,WAAW,eAAe;IAC9B;;;;;;OAMG;IACH,aAAa,CAAC,OAAO,EAAE,WAAW,GAAG,QAAQ,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,GAAG,IAAI,CAAC;CACrH;AAED;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,EAAE,eAEnC,CAAC;AAIH;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,yBAAyB,EAAE,OAAO,MAAqE,CAAC;AAErH;;;;;GAKG;AACH,MAAM,WAAW,sBAAsB;IACrC,wEAAwE;IACxE,QAAQ,CAAC,IAAI,EAAE,aAAa,GAAG,MAAM,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;IACtD;;;;OAIG;IACH,QAAQ,CAAC,mBAAmB,CAAC,EAAE,OAAO,CAAC;CACxC;AAID;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,qBAAqB,EAAE,OAAO,MAAiE,CAAC;AAE7G;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;;OAIG;IACH,eAAe,CAAC,CAAC,GAAG,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;CACzD;AAED;;;;;;GAMG;AACH,MAAM,WAAW,kBAAkB;IACjC;;;;;OAKG;IACH,WAAW,CAAC,CAAC,EAAE,MAAM,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC,EAAE,EAAE,gBAAgB,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;CACxF"}

package/dist/db-backup/ports.js

@@ -0,0 +1,100 @@
+"use strict";
+// =============================================================================
+// The db-backup slice's host ports (issue #740, PP-8.7)
+// =============================================================================
+//
+// Every capability the backup and restore engine needs from the application,
+// as ONE injection token per capability. The slice injects these and never
+// imports an app service; the app binds each token in a `@Global()` module of
+// its own (the reference app: `apps/api/src/platform/db-backup/
+// db-backup-host.module.ts`), passed to `DbBackupModule.forRoot({ imports })`.
+// Each interface is derived from the exact calls the slice makes; nothing
+// wider.
+//
+// The database is the core port `PLATFORM_PRISMA`, seen as `DbBackupPrisma`
+// (`data/db-backup-db.ts`). `DB_BACKUP_NOTIFIER` and `DB_BACKUP_MAINTENANCE`
+// are REQUIRED (a restore must announce itself and must close the gate while
+// it swaps); the others are optional.
+//
+// The tokens are `Symbol.for(...)` keys, so two copies of this file agree.
+// =============================================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DB_BACKUP_SYSTEM_DATA = exports.DB_BACKUP_DEPLOYMENT_MODE = exports.NOOP_DB_BACKUP_METRICS = exports.DB_BACKUP_METRICS = exports.DB_BACKUP_MAINTENANCE = exports.DB_BACKUP_NOTIFIER = void 0;
+// ---- notifications ----------------------------------------------------------------------
+/**
+ * Injection token of the app's {@link DbBackupNotifier}. Required.
+ *
+ * @example
+ * ```ts
+ * // DbBackupHostModule: { provide: DB_BACKUP_NOTIFIER, useExisting: NotificationsService }
+ * ```
+ *
+ * @extensionPoint token
+ * @stability experimental
+ */
+exports.DB_BACKUP_NOTIFIER = Symbol.for('@marinoscar/platform/db-backup/NOTIFIER');
+// ---- maintenance mode -----------------------------------------------------------------
+/**
+ * Injection token of the app's {@link DbBackupMaintenance}. Required.
+ *
+ * @example
+ * ```ts
+ * // DbBackupHostModule: { provide: DB_BACKUP_MAINTENANCE, useExisting: MaintenanceModeService }
+ * ```
+ *
+ * @extensionPoint token
+ * @stability experimental
+ */
+exports.DB_BACKUP_MAINTENANCE = Symbol.for('@marinoscar/platform/db-backup/MAINTENANCE');
+// ---- metrics ----------------------------------------------------------------------------
+/**
+ * Injection token of the app's {@link DbBackupMetrics}. Optional: without it
+ * the slice records nothing.
+ *
+ * @example
+ * ```ts
+ * // DbBackupHostModule: { provide: DB_BACKUP_METRICS, useExisting: AppMetricsService }
+ * ```
+ *
+ * @extensionPoint token
+ * @stability experimental
+ */
+exports.DB_BACKUP_METRICS = Symbol.for('@marinoscar/platform/db-backup/METRICS');
+/**
+ * The metrics used when the app binds none: every call is a no-op.
+ *
+ * @stability experimental
+ */
+exports.NOOP_DB_BACKUP_METRICS = Object.freeze({
+    backupSettled: () => undefined,
+});
+// ---- deployment mode -------------------------------------------------------------------
+/**
+ * Injection token of the app's {@link DbBackupDeploymentMode}. Optional:
+ * without it (and without the `deploymentMode` / `restoreEnabled` options) the
+ * deployment is `self-hosted` and in-app restore is on.
+ *
+ * @example
+ * ```ts
+ * // DbBackupHostModule: { provide: DB_BACKUP_DEPLOYMENT_MODE, useExisting: DeploymentModeService }
+ * ```
+ *
+ * @extensionPoint token
+ * @stability experimental
+ */
+exports.DB_BACKUP_DEPLOYMENT_MODE = Symbol.for('@marinoscar/platform/db-backup/DEPLOYMENT_MODE');
+// ---- the bypass client -------------------------------------------------------------------
+/**
+ * Injection token of the app's {@link DbBackupSystemData}: the bypass client.
+ * Required by the `backup.rls-bypass` Doctor check only.
+ *
+ * @example
+ * ```ts
+ * // DbBackupHostModule: { provide: DB_BACKUP_SYSTEM_DATA, useExisting: PrismaSystemService }
+ * ```
+ *
+ * @extensionPoint token
+ * @stability experimental
+ */
+exports.DB_BACKUP_SYSTEM_DATA = Symbol.for('@marinoscar/platform/db-backup/SYSTEM_DATA');
+//# sourceMappingURL=ports.js.map

package/dist/db-backup/ports.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ports.js","sourceRoot":"","sources":["../../src/db-backup/ports.ts"],"names":[],"mappings":";AAAA,gFAAgF;AAChF,wDAAwD;AACxD,gFAAgF;AAChF,EAAE;AACF,6EAA6E;AAC7E,2EAA2E;AAC3E,8EAA8E;AAC9E,gEAAgE;AAChE,+EAA+E;AAC/E,0EAA0E;AAC1E,SAAS;AACT,EAAE;AACF,4EAA4E;AAC5E,6EAA6E;AAC7E,6EAA6E;AAC7E,sCAAsC;AACtC,EAAE;AACF,2EAA2E;AAC3E,gFAAgF;;;AAEhF,4FAA4F;AAE5F;;;;;;;;;;GAUG;AACU,QAAA,kBAAkB,GAAkB,MAAM,CAAC,GAAG,CAAC,yCAAyC,CAAC,CAAC;AAuDvG,0FAA0F;AAE1F;;;;;;;;;;GAUG;AACU,QAAA,qBAAqB,GAAkB,MAAM,CAAC,GAAG,CAAC,4CAA4C,CAAC,CAAC;AAiC7G,4FAA4F;AAE5F;;;;;;;;;;;GAWG;AACU,QAAA,iBAAiB,GAAkB,MAAM,CAAC,GAAG,CAAC,wCAAwC,CAAC,CAAC;AAoBrG;;;;GAIG;AACU,QAAA,sBAAsB,GAAoB,MAAM,CAAC,MAAM,CAAC;IACnE,aAAa,EAAE,GAAG,EAAE,CAAC,SAAS;CAC/B,CAAC,CAAC;AAEH,2FAA2F;AAE3F;;;;;;;;;;;;GAYG;AACU,QAAA,yBAAyB,GAAkB,MAAM,CAAC,GAAG,CAAC,gDAAgD,CAAC,CAAC;AAmBrH,6FAA6F;AAE7F;;;;;;;;;;;GAWG;AACU,QAAA,qBAAqB,GAAkB,MAAM,CAAC,GAAG,CAAC,4CAA4C,CAAC,CAAC"}

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

@@ -0,0 +1,34 @@
+import { type ResolvedDbBackupModuleOptions } from './options';
+import { type DbBackupDeploymentMode } from './ports';
+/**
+ * Whether in-app restore is on, decided once at boot.
+ *
+ * @stability experimental
+ */
+export declare class DbBackupRestoreGate {
+    /** The deployment mode the gate was decided from (the option, else the port, else `self-hosted`). */
+    readonly mode: 'self-hosted' | 'saas' | (string & {});
+    /** Whether the application may restore its own database here. */
+    readonly inAppRestoreEnabled: boolean;
+    /**
+     * @param options - the resolved `forRoot()` options, when the module provides them.
+     * @param deployment - the app's deployment mode, when bound.
+     */
+    constructor(options?: ResolvedDbBackupModuleOptions, deployment?: DbBackupDeploymentMode);
+    /**
+     * The restore path's first statement.
+     *
+     * @throws {@link DatabaseRestoreDisabledError} when in-app restore is off (`saas`).
+     */
+    assertInAppRestoreEnabled(): void;
+}
+/**
+ * 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
+ */
+export declare function restoreGateFor(mode?: 'self-hosted' | 'saas' | (string & {})): DbBackupRestoreGate;
+//# sourceMappingURL=restore-gate.d.ts.map