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

package/dist/db-backup/db-backup.registrations.js

@@ -0,0 +1,129 @@
+"use strict";
+// =============================================================================
+// What the db-backup slice registers with the other registries (issue #740)
+// =============================================================================
+//
+// Pure data, no side effect on import. Each list is the slice's own, declared
+// beside the code that uses it, and the app registers it where its registry
+// lives:
+//
+//   - DB_BACKUP_APP_METRICS        -> the otel-core metric-name registry
+//                                     (`registerAppMetrics`, #700), spliced
+//                                     into the app's platform list at its
+//                                     historical position;
+//   - DB_BACKUP_NOTIFICATION_EVENTS -> the app's notification registry (the
+//                                     event definitions and browser templates
+//                                     stay app-side until the notifications
+//                                     slice, #738, packages the registry);
+//   - DB_BACKUP_EMAIL_TEMPLATES    -> the email slice's template registry,
+//                                     which already ships both templates;
+//   - DB_BACKUP_JOB_TYPES          -> the jobs slice's handler registry, which
+//                                     each handler joins on `onModuleInit`
+//                                     (with its own `label`).
+//
+// The key-prefix registration is `db-backup-key-prefix.ts`; the permissions
+// `db-backup.permissions.ts`; the settings namespace
+// `db-backup.system-settings.ts`.
+// =============================================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DB_BACKUP_JOB_TYPES = exports.DB_BACKUP_EMAIL_TEMPLATES = exports.DB_BACKUP_NOTIFICATION_EVENTS = exports.DB_BACKUP_APP_METRICS = void 0;
+const outcome = { kind: 'enum', values: ['completed', 'failed'] };
+/**
+ * The `app.backup.*` instruments, exactly as the reference app exported them
+ * before the move (a name or unit is a GreptimeDB table name: changing one
+ * orphans every dashboard query that reads it). The duration buckets are in
+ * seconds, the size buckets in bytes.
+ *
+ * @example
+ * ```ts
+ * registerAppMetrics([...JOBS_METRICS, ...DB_BACKUP_APP_METRICS, ...AUTH_METRICS]);
+ * ```
+ *
+ * @stability stable
+ */
+exports.DB_BACKUP_APP_METRICS = [
+    {
+        key: 'backupRuns',
+        name: 'app.backup.runs',
+        kind: 'counter',
+        unit: '{run}',
+        description: 'Database backup runs settled, by outcome.',
+        attributes: { outcome },
+    },
+    {
+        key: 'backupDuration',
+        name: 'app.backup.duration',
+        kind: 'histogram',
+        unit: 's',
+        description: 'Wall time of a settled database backup run.',
+        buckets: [1, 5, 15, 30, 60, 120, 300, 600, 1200, 1800, 3600, 7200, 14400],
+        attributes: { outcome },
+    },
+    {
+        key: 'backupSize',
+        name: 'app.backup.size',
+        kind: 'histogram',
+        unit: 'By',
+        description: 'Size of a completed, verified database backup archive.',
+        buckets: [1e6, 1e7, 5e7, 1e8, 5e8, 1e9, 5e9, 1e10, 5e10, 1e11],
+        attributes: { outcome },
+    },
+    {
+        key: 'backupLastSuccessTimestamp',
+        name: 'app.backup.last_success.timestamp',
+        kind: 'gauge',
+        unit: 's',
+        description: 'When the most recent completed database backup finished (unix seconds).',
+    },
+    {
+        key: 'backupLastSuccessSize',
+        name: 'app.backup.last_success.size',
+        kind: 'gauge',
+        unit: 'By',
+        description: 'Size of the most recent completed database backup archive.',
+    },
+];
+/**
+ * The notification event keys the slice raises. Persisted (preferences,
+ * delivery rows): never rename one. `db_backup.restore_completed` is
+ * mandatory (cannot be turned off).
+ *
+ * @stability stable
+ */
+exports.DB_BACKUP_NOTIFICATION_EVENTS = Object.freeze({
+    /** A backup run failed or went stale. */
+    BACKUP_FAILED: 'db_backup.backup_failed',
+    /** A restore swapped the restored copy in. */
+    RESTORE_COMPLETED: 'db_backup.restore_completed',
+});
+/**
+ * The email templates those events render (shipped by the email slice's
+ * template registry).
+ *
+ * @stability stable
+ */
+exports.DB_BACKUP_EMAIL_TEMPLATES = Object.freeze({
+    /** For `db_backup.backup_failed`. */
+    BACKUP_FAILED: 'backup-failed',
+    /** For `db_backup.restore_completed`. */
+    RESTORE_COMPLETED: 'restore-completed',
+});
+/**
+ * The four job types the slice registers. PERMANENT once jobs of a type exist
+ * (`apps/api/test/jobs/job-type-snapshot.spec.ts` pins them). `db.backup.run`
+ * is node-eligible (profile `{ maxRuntimeMs: 6 h, maxAttempts: 1 }`, its
+ * credential brokered per job); `db.restore.run` is server-only, permanently.
+ *
+ * @stability stable
+ */
+exports.DB_BACKUP_JOB_TYPES = Object.freeze({
+    /** The dump. */
+    BACKUP_RUN: 'db.backup.run',
+    /** Stale-run release and retention, enqueued by the schedule tick. */
+    BACKUP_SWEEP: 'db.backup.sweep',
+    /** The restore. Server-only. */
+    RESTORE_RUN: 'db.restore.run',
+    /** Drops retained `<live>_old_<ts>` databases past their window. */
+    RESTORE_OLD_DB_DROP: 'db.restore.old-db-drop',
+});
+//# sourceMappingURL=db-backup.registrations.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"db-backup.registrations.js","sourceRoot":"","sources":["../../src/db-backup/db-backup.registrations.ts"],"names":[],"mappings":";AAAA,gFAAgF;AAChF,4EAA4E;AAC5E,gFAAgF;AAChF,EAAE;AACF,8EAA8E;AAC9E,4EAA4E;AAC5E,SAAS;AACT,EAAE;AACF,yEAAyE;AACzE,4EAA4E;AAC5E,0EAA0E;AAC1E,2DAA2D;AAC3D,4EAA4E;AAC5E,8EAA8E;AAC9E,4EAA4E;AAC5E,2EAA2E;AAC3E,2EAA2E;AAC3E,0EAA0E;AAC1E,+EAA+E;AAC/E,2EAA2E;AAC3E,8DAA8D;AAC9D,EAAE;AACF,4EAA4E;AAC5E,qDAAqD;AACrD,kCAAkC;AAClC,gFAAgF;;;AAIhF,MAAM,OAAO,GAAuB,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,WAAW,EAAE,QAAQ,CAAC,EAAE,CAAC;AActF;;;;;;;;;;;;GAYG;AACU,QAAA,qBAAqB,GAM9B;IACF;QACE,GAAG,EAAE,YAAY;QACjB,IAAI,EAAE,iBAAiB;QACvB,IAAI,EAAE,SAAS;QACf,IAAI,EAAE,OAAO;QACb,WAAW,EAAE,2CAA2C;QACxD,UAAU,EAAE,EAAE,OAAO,EAAE;KACxB;IACD;QACE,GAAG,EAAE,gBAAgB;QACrB,IAAI,EAAE,qBAAqB;QAC3B,IAAI,EAAE,WAAW;QACjB,IAAI,EAAE,GAAG;QACT,WAAW,EAAE,6CAA6C;QAC1D,OAAO,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,CAAC;QACzE,UAAU,EAAE,EAAE,OAAO,EAAE;KACxB;IACD;QACE,GAAG,EAAE,YAAY;QACjB,IAAI,EAAE,iBAAiB;QACvB,IAAI,EAAE,WAAW;QACjB,IAAI,EAAE,IAAI;QACV,WAAW,EAAE,wDAAwD;QACrE,OAAO,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC;QAC9D,UAAU,EAAE,EAAE,OAAO,EAAE;KACxB;IACD;QACE,GAAG,EAAE,4BAA4B;QACjC,IAAI,EAAE,mCAAmC;QACzC,IAAI,EAAE,OAAO;QACb,IAAI,EAAE,GAAG;QACT,WAAW,EAAE,yEAAyE;KACvF;IACD;QACE,GAAG,EAAE,uBAAuB;QAC5B,IAAI,EAAE,8BAA8B;QACpC,IAAI,EAAE,OAAO;QACb,IAAI,EAAE,IAAI;QACV,WAAW,EAAE,4DAA4D;KAC1E;CACF,CAAC;AAEF;;;;;;GAMG;AACU,QAAA,6BAA6B,GAAG,MAAM,CAAC,MAAM,CAAC;IACzD,yCAAyC;IACzC,aAAa,EAAE,yBAAyB;IACxC,8CAA8C;IAC9C,iBAAiB,EAAE,6BAA6B;CACxC,CAAC,CAAC;AAEZ;;;;;GAKG;AACU,QAAA,yBAAyB,GAAG,MAAM,CAAC,MAAM,CAAC;IACrD,qCAAqC;IACrC,aAAa,EAAE,eAAe;IAC9B,yCAAyC;IACzC,iBAAiB,EAAE,mBAAmB;CAC9B,CAAC,CAAC;AAEZ;;;;;;;GAOG;AACU,QAAA,mBAAmB,GAAG,MAAM,CAAC,MAAM,CAAC;IAC/C,gBAAgB;IAChB,UAAU,EAAE,eAAe;IAC3B,sEAAsE;IACtE,YAAY,EAAE,iBAAiB;IAC/B,gCAAgC;IAChC,WAAW,EAAE,gBAAgB;IAC7B,oEAAoE;IACpE,mBAAmB,EAAE,wBAAwB;CACrC,CAAC,CAAC"}

package/dist/db-backup/db-backup.system-settings.d.ts

@@ -0,0 +1,200 @@
+import { type DatabaseBackupSettingsPatchInput, type SystemDatabaseBackupValue } from '@marinoscar/platform-contract/db-backup';
+/**
+ * The `databaseBackup` PATCH merge: a field the patch names replaces the
+ * stored one, an absent field is kept (`''` for `storageProvider` clears the
+ * pin back to "whatever provider is active").
+ *
+ * `retentionCount` and `retention.count` are ONE value under two names, kept in
+ * step on every write so an older client that only knows `retentionCount` and
+ * a newer one that sends `retention` both read back what they wrote:
+ *
+ *   - a patch that sets `retention.count` also sets `retentionCount` (and wins
+ *     over a `retentionCount` in the same patch);
+ *   - a patch that sets `retentionCount` alone also moves a stored
+ *     `retention.count`;
+ *   - `retention` replaces the stored object whole (`retention: {}` clears the
+ *     age rule), as every other field of the namespace is replaced.
+ *
+ * @param current - the stored value.
+ * @param patch - the PATCH body's `databaseBackup` branch, when present.
+ * @returns the merged value.
+ *
+ * @stability experimental
+ */
+export declare function mergeDatabaseBackupSettings(current: SystemDatabaseBackupValue, patch?: DatabaseBackupSettingsPatchInput): SystemDatabaseBackupValue;
+/**
+ * The retention rules in force, as {@link resolveBackupRetention} returns them.
+ *
+ * @stability experimental
+ */
+export interface ResolvedBackupRetention {
+    /** How many completed archives to keep. */
+    count: number;
+    /** Delete a completed archive older than this many days; absent for no age bound. */
+    maxAgeDays?: number;
+}
+/**
+ * The retention rules in force: the count (`retention.count`, else the
+ * `retentionCount` alias) and, when set, the age bound in days.
+ *
+ * @param policy - the stored `databaseBackup` value.
+ * @returns the effective rules.
+ *
+ * @stability experimental
+ */
+export declare function resolveBackupRetention(policy: Pick<SystemDatabaseBackupValue, 'retentionCount' | 'retention'>): ResolvedBackupRetention;
+/**
+ * The `databaseBackup` system-settings namespace (#256, epic #254): the
+ * schedule, retention, target provider, compression, rollback mode and node
+ * offload. Registered by the app's system settings manifest. Inert by default:
+ * backups ship disabled.
+ *
+ * @stability experimental
+ */
+export declare const DATABASE_BACKUP_SYSTEM_SETTINGS: {
+    /** The namespace key (permanent). */
+    key: "databaseBackup";
+    /** What it holds. */
+    description: string;
+    /** The stored shape. */
+    storedSchema: import("zod").ZodObject<{
+        enabled: import("zod").ZodBoolean;
+        frequency: import("zod").ZodEnum<import("@marinoscar/platform-contract/db-backup").DbBackupEnum<readonly ["daily", "weekly", "monthly", "cron"]>>;
+        dayOfWeek: import("zod").ZodNumber;
+        dayOfMonth: import("zod").ZodNumber;
+        timeOfDay: import("zod").ZodString;
+        timezone: import("zod").ZodString;
+        retentionCount: import("zod").ZodNumber;
+        cron: import("zod").ZodOptional<import("zod").ZodString>;
+        retention: import("zod").ZodOptional<import("zod").ZodObject<{
+            count: import("zod").ZodOptional<import("zod").ZodNumber>;
+            maxAgeDays: import("zod").ZodOptional<import("zod").ZodNumber>;
+        }, import("zod/v4/core").$strip>>;
+        storageProvider: import("zod").ZodString;
+        runStaleMinutes: import("zod").ZodNumber;
+        compressionLevel: import("zod").ZodNumber;
+        restoreRollbackMode: import("zod").ZodEnum<import("@marinoscar/platform-contract/db-backup").DbBackupEnum<["retain_database", "drop_database"]>>;
+        oldDatabaseRetentionHours: import("zod").ZodNumber;
+        nodeOffloadEnabled: import("zod").ZodBoolean;
+    }, import("zod/v4/core").$strip>;
+    /** The stored partial. */
+    patchSchema: import("zod").ZodObject<{
+        enabled: import("zod").ZodOptional<import("zod").ZodBoolean>;
+        frequency: import("zod").ZodOptional<import("zod").ZodEnum<import("@marinoscar/platform-contract/db-backup").DbBackupEnum<readonly ["daily", "weekly", "monthly", "cron"]>>>;
+        dayOfWeek: import("zod").ZodOptional<import("zod").ZodNumber>;
+        dayOfMonth: import("zod").ZodOptional<import("zod").ZodNumber>;
+        timeOfDay: import("zod").ZodOptional<import("zod").ZodString>;
+        timezone: import("zod").ZodOptional<import("zod").ZodString>;
+        retentionCount: import("zod").ZodOptional<import("zod").ZodNumber>;
+        cron: import("zod").ZodOptional<import("zod").ZodString>;
+        retention: import("zod").ZodOptional<import("zod").ZodObject<{
+            count: import("zod").ZodOptional<import("zod").ZodNumber>;
+            maxAgeDays: import("zod").ZodOptional<import("zod").ZodNumber>;
+        }, import("zod/v4/core").$strip>>;
+        storageProvider: import("zod").ZodOptional<import("zod").ZodString>;
+        runStaleMinutes: import("zod").ZodOptional<import("zod").ZodNumber>;
+        compressionLevel: import("zod").ZodOptional<import("zod").ZodNumber>;
+        restoreRollbackMode: import("zod").ZodOptional<import("zod").ZodEnum<import("@marinoscar/platform-contract/db-backup").DbBackupEnum<["retain_database", "drop_database"]>>>;
+        oldDatabaseRetentionHours: import("zod").ZodOptional<import("zod").ZodNumber>;
+        nodeOffloadEnabled: import("zod").ZodOptional<import("zod").ZodBoolean>;
+    }, import("zod/v4/core").$strip>;
+    /** The PUT body's branch. */
+    putSchema: import("zod").ZodObject<{
+        enabled: import("zod").ZodBoolean;
+        frequency: import("zod").ZodEnum<import("@marinoscar/platform-contract/db-backup").DbBackupEnum<readonly ["daily", "weekly", "monthly", "cron"]>>;
+        dayOfWeek: import("zod").ZodNumber;
+        dayOfMonth: import("zod").ZodNumber;
+        timeOfDay: import("zod").ZodString;
+        timezone: import("zod").ZodString;
+        retentionCount: import("zod").ZodNumber;
+        cron: import("zod").ZodOptional<import("zod").ZodString>;
+        retention: import("zod").ZodOptional<import("zod").ZodObject<{
+            count: import("zod").ZodOptional<import("zod").ZodNumber>;
+            maxAgeDays: import("zod").ZodOptional<import("zod").ZodNumber>;
+        }, import("zod/v4/core").$strip>>;
+        storageProvider: import("zod").ZodString;
+        runStaleMinutes: import("zod").ZodNumber;
+        compressionLevel: import("zod").ZodNumber;
+        restoreRollbackMode: import("zod").ZodEnum<import("@marinoscar/platform-contract/db-backup").DbBackupEnum<["retain_database", "drop_database"]>>;
+        oldDatabaseRetentionHours: import("zod").ZodNumber;
+        nodeOffloadEnabled: import("zod").ZodBoolean;
+    }, import("zod/v4/core").$strip>;
+    /** The PATCH body's branch. */
+    wirePatchSchema: import("zod").ZodObject<{
+        enabled: import("zod").ZodOptional<import("zod").ZodBoolean>;
+        frequency: import("zod").ZodOptional<import("zod").ZodEnum<import("@marinoscar/platform-contract/db-backup").DbBackupEnum<readonly ["daily", "weekly", "monthly", "cron"]>>>;
+        dayOfWeek: import("zod").ZodOptional<import("zod").ZodNumber>;
+        dayOfMonth: import("zod").ZodOptional<import("zod").ZodNumber>;
+        timeOfDay: import("zod").ZodOptional<import("zod").ZodString>;
+        timezone: import("zod").ZodOptional<import("zod").ZodString>;
+        retentionCount: import("zod").ZodOptional<import("zod").ZodNumber>;
+        cron: import("zod").ZodOptional<import("zod").ZodString>;
+        retention: import("zod").ZodOptional<import("zod").ZodObject<{
+            count: import("zod").ZodOptional<import("zod").ZodNumber>;
+            maxAgeDays: import("zod").ZodOptional<import("zod").ZodNumber>;
+        }, import("zod/v4/core").$strip>>;
+        storageProvider: import("zod").ZodOptional<import("zod").ZodString>;
+        runStaleMinutes: import("zod").ZodOptional<import("zod").ZodNumber>;
+        compressionLevel: import("zod").ZodOptional<import("zod").ZodNumber>;
+        restoreRollbackMode: import("zod").ZodOptional<import("zod").ZodEnum<import("@marinoscar/platform-contract/db-backup").DbBackupEnum<["retain_database", "drop_database"]>>>;
+        oldDatabaseRetentionHours: import("zod").ZodOptional<import("zod").ZodNumber>;
+        nodeOffloadEnabled: import("zod").ZodOptional<import("zod").ZodBoolean>;
+    }, import("zod/v4/core").$strip>;
+    /** The GET response's branch. */
+    responseSchema: import("zod").ZodObject<{
+        enabled: import("zod").ZodBoolean;
+        frequency: import("zod").ZodEnum<import("@marinoscar/platform-contract/db-backup").DbBackupEnum<readonly ["daily", "weekly", "monthly", "cron"]>>;
+        dayOfWeek: import("zod").ZodNumber;
+        dayOfMonth: import("zod").ZodNumber;
+        timeOfDay: import("zod").ZodString;
+        timezone: import("zod").ZodString;
+        retentionCount: import("zod").ZodNumber;
+        cron: import("zod").ZodOptional<import("zod").ZodString>;
+        retention: import("zod").ZodOptional<import("zod").ZodObject<{
+            count: import("zod").ZodOptional<import("zod").ZodNumber>;
+            maxAgeDays: import("zod").ZodOptional<import("zod").ZodNumber>;
+        }, import("zod/v4/core").$strip>>;
+        storageProvider: import("zod").ZodString;
+        runStaleMinutes: import("zod").ZodNumber;
+        compressionLevel: import("zod").ZodNumber;
+        restoreRollbackMode: import("zod").ZodEnum<import("@marinoscar/platform-contract/db-backup").DbBackupEnum<["retain_database", "drop_database"]>>;
+        oldDatabaseRetentionHours: import("zod").ZodNumber;
+        nodeOffloadEnabled: import("zod").ZodBoolean;
+    }, import("zod/v4/core").$strip>;
+    /** Inert: backups ship disabled. */
+    defaults: {
+        enabled: boolean;
+        frequency: "cron" | "daily" | "weekly" | "monthly";
+        dayOfWeek: number;
+        dayOfMonth: number;
+        timeOfDay: string;
+        timezone: string;
+        retentionCount: number;
+        storageProvider: string;
+        runStaleMinutes: number;
+        compressionLevel: number;
+        restoreRollbackMode: "retain_database" | "drop_database";
+        oldDatabaseRetentionHours: number;
+        nodeOffloadEnabled: boolean;
+        cron?: string | undefined;
+        retention?: {
+            count?: number | undefined;
+            maxAgeDays?: number | undefined;
+        } | undefined;
+    };
+    /** Optional in a PUT body. */
+    requiredOnPut: false;
+    /** The PATCH merge (`mergeDatabaseBackupSettings`). */
+    merge: typeof mergeDatabaseBackupSettings;
+};
+declare module '../settings/index' {
+    interface SystemSettingsNamespaces {
+        /** Database backup/restore policy (#256, epic #254). REQUIRED for the reason `jobs` gives. */
+        databaseBackup: SystemDatabaseBackupValue;
+    }
+    interface SystemSettingsNamespaceDeclarations {
+        /** The `databaseBackup` declaration. */
+        databaseBackup: typeof DATABASE_BACKUP_SYSTEM_SETTINGS;
+    }
+}
+//# sourceMappingURL=db-backup.system-settings.d.ts.map

package/dist/db-backup/db-backup.system-settings.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"db-backup.system-settings.d.ts","sourceRoot":"","sources":["../../src/db-backup/db-backup.system-settings.ts"],"names":[],"mappings":"AASA,OAAO,EAML,KAAK,gCAAgC,EACrC,KAAK,yBAAyB,EAC/B,MAAM,yCAAyC,CAAC;AAoCjD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,2BAA2B,CACzC,OAAO,EAAE,yBAAyB,EAClC,KAAK,CAAC,EAAE,gCAAgC,GACvC,yBAAyB,CA+B3B;AAED;;;;GAIG;AACH,MAAM,WAAW,uBAAuB;IACtC,2CAA2C;IAC3C,KAAK,EAAE,MAAM,CAAC;IACd,qFAAqF;IACrF,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,IAAI,CAAC,yBAAyB,EAAE,gBAAgB,GAAG,WAAW,CAAC,GACtE,uBAAuB,CAMzB;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,+BAA+B;IAC1C,qCAAqC;;IAErC,qBAAqB;;IAErB,wBAAwB;;;;;;;;;;;;;;;;;;;;;IAExB,0BAA0B;;;;;;;;;;;;;;;;;;;;;IAE1B,6BAA6B;;;;;;;;;;;;;;;;;;;;;IAE7B,+BAA+B;;;;;;;;;;;;;;;;;;;;;IAE/B,iCAAiC;;;;;;;;;;;;;;;;;;;;;IAEjC,oCAAoC;;;;;;;;;;;;;;;;;;;;;IAEpC,8BAA8B;;IAE9B,uDAAuD;;CAEyD,CAAC;AAEnH,OAAO,QAAQ,mBAAmB,CAAC;IACjC,UAAU,wBAAwB;QAChC,8FAA8F;QAC9F,cAAc,EAAE,yBAAyB,CAAC;KAC3C;IACD,UAAU,mCAAmC;QAC3C,wCAAwC;QACxC,cAAc,EAAE,OAAO,+BAA+B,CAAC;KACxD;CACF"}

package/dist/db-backup/db-backup.system-settings.js

@@ -0,0 +1,145 @@
+"use strict";
+// =============================================================================
+// System settings namespace `databaseBackup` (issue #677; namespace #256, epic #254)
+// =============================================================================
+//
+// A declaration file: pure data, imports only leaf modules (the schemas are
+// `@marinoscar/platform-contract/db-backup`'s since #740). Registered by the
+// app's system-settings manifest. Recipe: packages/platform-api/src/settings/README.md.
+// =============================================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DATABASE_BACKUP_SYSTEM_SETTINGS = void 0;
+exports.mergeDatabaseBackupSettings = mergeDatabaseBackupSettings;
+exports.resolveBackupRetention = resolveBackupRetention;
+const db_backup_1 = require("@marinoscar/platform-contract/db-backup");
+// Inert, like every operations namespace: backups ship disabled.
+const DATABASE_BACKUP_SYSTEM_DEFAULTS = {
+    enabled: false,
+    frequency: 'daily',
+    dayOfWeek: 0,
+    dayOfMonth: 1,
+    timeOfDay: '02:00',
+    timezone: 'UTC',
+    retentionCount: 7,
+    // EMPTY MEANS "WHATEVER PROVIDER IS ACTIVE", and that is the only honest
+    // default (#373, epic #372). This field is a PIN: a non-empty value must
+    // equal `storage.provider` or every backup is a loud 400
+    // (`db-backup/db-backup-storage.ts`), which is exactly what should happen
+    // to a value an operator typed and then contradicted. It is exactly what
+    // should NOT happen to a value they never typed — and shipping the literal
+    // `'s3'` here did precisely that: once `storage.provider` became a live
+    // setting, every deployment that selected R2 inherited a pin on `s3` and
+    // failed EVERY backup, from `queueBackup`, `startBackup`, `runQueuedBackup`
+    // and `PUT config` alike, on nobody's decision. Empty is inert in the same
+    // sense as the rest of this block: it defers, it does not choose.
+    storageProvider: '',
+    runStaleMinutes: 120,
+    compressionLevel: 6,
+    restoreRollbackMode: 'retain_database',
+    oldDatabaseRetentionHours: 48,
+    // OFF, like `nodes.jobSecretBrokerEnabled` and for a related-but-distinct
+    // reason (#352, epic #345): a fresh deployment does not ship its entire
+    // database off the API server because somebody registered a worker node.
+    // Both switches must be on, and the credential broker must report itself
+    // usable, before `db.backup.run` is offered to a node at all.
+    nodeOffloadEnabled: false,
+};
+/**
+ * The `databaseBackup` PATCH merge: a field the patch names replaces the
+ * stored one, an absent field is kept (`''` for `storageProvider` clears the
+ * pin back to "whatever provider is active").
+ *
+ * `retentionCount` and `retention.count` are ONE value under two names, kept in
+ * step on every write so an older client that only knows `retentionCount` and
+ * a newer one that sends `retention` both read back what they wrote:
+ *
+ *   - a patch that sets `retention.count` also sets `retentionCount` (and wins
+ *     over a `retentionCount` in the same patch);
+ *   - a patch that sets `retentionCount` alone also moves a stored
+ *     `retention.count`;
+ *   - `retention` replaces the stored object whole (`retention: {}` clears the
+ *     age rule), as every other field of the namespace is replaced.
+ *
+ * @param current - the stored value.
+ * @param patch - the PATCH body's `databaseBackup` branch, when present.
+ * @returns the merged value.
+ *
+ * @stability experimental
+ */
+function mergeDatabaseBackupSettings(current, patch) {
+    const patchedCount = patch?.retention?.count;
+    const retentionCount = patchedCount ?? patch?.retentionCount ?? current.retentionCount;
+    let retention = patch?.retention !== undefined ? patch.retention : current.retention;
+    if (patch?.retention === undefined && patch?.retentionCount !== undefined && retention?.count !== undefined) {
+        retention = { ...retention, count: patch.retentionCount };
+    }
+    const merged = {
+        enabled: patch?.enabled ?? current.enabled,
+        frequency: patch?.frequency ?? current.frequency,
+        dayOfWeek: patch?.dayOfWeek ?? current.dayOfWeek,
+        dayOfMonth: patch?.dayOfMonth ?? current.dayOfMonth,
+        timeOfDay: patch?.timeOfDay ?? current.timeOfDay,
+        timezone: patch?.timezone ?? current.timezone,
+        retentionCount,
+        storageProvider: patch?.storageProvider ?? current.storageProvider,
+        runStaleMinutes: patch?.runStaleMinutes ?? current.runStaleMinutes,
+        compressionLevel: patch?.compressionLevel ?? current.compressionLevel,
+        restoreRollbackMode: patch?.restoreRollbackMode ?? current.restoreRollbackMode,
+        oldDatabaseRetentionHours: patch?.oldDatabaseRetentionHours ?? current.oldDatabaseRetentionHours,
+        nodeOffloadEnabled: patch?.nodeOffloadEnabled ?? current.nodeOffloadEnabled,
+    };
+    // Absent stays absent: a row that never had these keeps its stored shape.
+    const cron = patch?.cron ?? current.cron;
+    if (cron !== undefined)
+        merged.cron = cron;
+    if (retention !== undefined)
+        merged.retention = retention;
+    return merged;
+}
+/**
+ * The retention rules in force: the count (`retention.count`, else the
+ * `retentionCount` alias) and, when set, the age bound in days.
+ *
+ * @param policy - the stored `databaseBackup` value.
+ * @returns the effective rules.
+ *
+ * @stability experimental
+ */
+function resolveBackupRetention(policy) {
+    const maxAgeDays = policy.retention?.maxAgeDays;
+    return {
+        count: policy.retention?.count ?? policy.retentionCount,
+        ...(maxAgeDays !== undefined ? { maxAgeDays } : {}),
+    };
+}
+/**
+ * The `databaseBackup` system-settings namespace (#256, epic #254): the
+ * schedule, retention, target provider, compression, rollback mode and node
+ * offload. Registered by the app's system settings manifest. Inert by default:
+ * backups ship disabled.
+ *
+ * @stability experimental
+ */
+exports.DATABASE_BACKUP_SYSTEM_SETTINGS = {
+    /** The namespace key (permanent). */
+    key: 'databaseBackup',
+    /** What it holds. */
+    description: 'Database backup and restore policy: the schedule, retention, target provider, compression, rollback mode and node offload.',
+    /** The stored shape. */
+    storedSchema: db_backup_1.systemDatabaseBackupSchema,
+    /** The stored partial. */
+    patchSchema: db_backup_1.systemDatabaseBackupPatchSchema,
+    /** The PUT body's branch. */
+    putSchema: db_backup_1.databaseBackupSettingsSchema,
+    /** The PATCH body's branch. */
+    wirePatchSchema: db_backup_1.databaseBackupSettingsPatchSchema,
+    /** The GET response's branch. */
+    responseSchema: db_backup_1.databaseBackupResponseSchema,
+    /** Inert: backups ship disabled. */
+    defaults: DATABASE_BACKUP_SYSTEM_DEFAULTS,
+    /** Optional in a PUT body. */
+    requiredOnPut: false,
+    /** The PATCH merge (`mergeDatabaseBackupSettings`). */
+    merge: mergeDatabaseBackupSettings,
+};
+//# sourceMappingURL=db-backup.system-settings.js.map

package/dist/db-backup/db-backup.system-settings.js.map

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

package/dist/db-backup/doctor/backup-mirrors.doctor-check.d.ts

@@ -0,0 +1,58 @@
+import { OnModuleInit } from '@nestjs/common';
+import { DoctorCheck, DoctorCheckOutcome } from '../../doctor/index';
+import { DoctorCheckRegistry } from '../../doctor/index';
+import { type BackupTarget } from '../backup-target';
+import type { DbBackupPrisma } from '../data/db-backup-db';
+/**
+ * The most recent result recorded for one mirror target.
+ *
+ * @stability experimental
+ */
+export interface MirrorFact {
+    /** The mirror target's id. */
+    targetId: string;
+    /** `ok` or `failed`; `null` when no copy has been recorded for it yet. */
+    status: 'ok' | 'failed' | null;
+    /** When the result was recorded. */
+    at: Date | null;
+    /** Why it failed. */
+    error: string | null;
+}
+/**
+ * Pure: judges the configured mirrors by their latest recorded result.
+ *
+ * - `pass`: no mirror is configured, or every mirror's latest copy landed.
+ * - `warn`: at least one mirror's latest copy failed (the primary archive is
+ *   fine and restorable; the second copy is missing), or has never run.
+ *
+ * It never reports `fail`: a mirror is a second line of defence, and the
+ * `backup.schedule` check owns "the primary backup works".
+ *
+ * @param facts - one per configured mirror.
+ * @returns the outcome.
+ *
+ * @stability experimental
+ */
+export declare function decideBackupMirrors(facts: readonly MirrorFact[]): DoctorCheckOutcome;
+/**
+ * `backup` / `backup.mirrors`: every mirror target received the latest
+ * backup. Read-only: it reads the `audit_events` rows the runner wrote
+ * (`db_backup.mirror.completed` / `.failed`) with one bounded `findMany`; it never touches a target.
+ *
+ * @stability experimental
+ */
+export declare class BackupMirrorsDoctorCheck implements DoctorCheck, OnModuleInit {
+    private readonly registry;
+    private readonly prisma;
+    readonly id = "backup.mirrors";
+    readonly category = "backup";
+    readonly label = "Backup mirrors";
+    readonly settingsPath = "/admin/settings/db-backup";
+    readonly dependsOn: string[];
+    private readonly mirrors;
+    constructor(registry: DoctorCheckRegistry, prisma: DbBackupPrisma, mirrors?: readonly BackupTarget[]);
+    /** Registers the check with the Doctor registry. */
+    onModuleInit(): void;
+    run(): Promise<DoctorCheckOutcome>;
+}
+//# sourceMappingURL=backup-mirrors.doctor-check.d.ts.map

package/dist/db-backup/doctor/backup-mirrors.doctor-check.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"backup-mirrors.doctor-check.d.ts","sourceRoot":"","sources":["../../../src/db-backup/doctor/backup-mirrors.doctor-check.ts"],"names":[],"mappings":"AAAA,OAAO,EAAsB,YAAY,EAAY,MAAM,gBAAgB,CAAC;AAE5E,OAAO,EAAE,WAAW,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AACrE,OAAO,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAEzD,OAAO,EAA4B,KAAK,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAE/E,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAS3D;;;;GAIG;AACH,MAAM,WAAW,UAAU;IACzB,8BAA8B;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,0EAA0E;IAC1E,MAAM,EAAE,IAAI,GAAG,QAAQ,GAAG,IAAI,CAAC;IAC/B,oCAAoC;IACpC,EAAE,EAAE,IAAI,GAAG,IAAI,CAAC;IAChB,qBAAqB;IACrB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CACtB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,SAAS,UAAU,EAAE,GAAG,kBAAkB,CAmCpF;AAED;;;;;;GAMG;AACH,qBACa,wBAAyB,YAAW,WAAW,EAAE,YAAY;IAUtE,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACA,OAAO,CAAC,QAAQ,CAAC,MAAM;IAVlD,QAAQ,CAAC,EAAE,oBAAoB;IAC/B,QAAQ,CAAC,QAAQ,YAAY;IAC7B,QAAQ,CAAC,KAAK,oBAAoB;IAClC,QAAQ,CAAC,YAAY,+BAAwB;IAC7C,QAAQ,CAAC,SAAS,WAAqB;IAEvC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA0B;gBAG/B,QAAQ,EAAE,mBAAmB,EACJ,MAAM,EAAE,cAAc,EAClB,OAAO,CAAC,EAAE,SAAS,YAAY,EAAE;IAKjF,oDAAoD;IACpD,YAAY,IAAI,IAAI;IAId,GAAG,IAAI,OAAO,CAAC,kBAAkB,CAAC;CAqCzC"}