@jwilleke/ngdpbase-types 0.0.0 → 5.19.0

package/lib/src/managers/DatabaseManager.d.ts

@@ -0,0 +1,188 @@
+import BaseManager from './BaseManager.js';
+import type { WikiEngine } from '../types/WikiEngine.js';
+import type { Migration } from '../providers/sqliteMigrations.js';
+import { type ActorContext } from '../context/ActorContext.js';
+import type { BackupData, ManagerBackupOptions, ManagerRestoreOptions } from './BaseManager.js';
+import { type AddonDatabaseDeclaration } from '../utils/addonDatabaseRules.js';
+import { type StagedRestoreManifest } from '../providers/sqliteBackup.js';
+/** The environment variable holding the SQLCipher key. Never a config key: config is readable from the admin screens. */
+export declare const DATABASE_KEY_ENV = "NGDPBASE_DATABASE_KEY";
+/**
+ * The environment variable holding the key every database backup is encrypted
+ * under (#1723). Its own secret, not the database key: the copy that travels
+ * and the copy that stays should not fall to the same compromise. Never a
+ * config key. Unset, no database is backed up, and admins are told.
+ */
+export declare const BACKUP_KEY_ENV = "NGDPBASE_BACKUP_KEY";
+/** How long a database backup or restore staging may run on its worker before it is stopped, when not configured. */
+export declare const DEFAULT_BACKUP_WORKER_TIMEOUT_MS = 3600000;
+/**
+ * A short fingerprint of a backup key (#1723, D3): the first 16 hex digits of
+ * an HMAC of a fixed label under the key. Recorded in each backup so a restore
+ * under another key says so plainly; it never reveals the key.
+ */
+export declare function backupKeyFingerprint(key: string): string;
+/** One database in a backup, as DatabaseManager's entry in the backup document lists it. */
+export interface DatabaseBackupEntry {
+    /** `application`, or `addon-<owner>`. */
+    name: string;
+    kind: 'application' | 'addon';
+    owner?: string;
+    /** The encrypted file beside the backup document: `<stem>.<name>.db`. */
+    file: string;
+    sizeBytes: number;
+    tables: number;
+}
+/** DatabaseManager's `data` in a backup document. */
+export interface DatabaseBackupData {
+    format: 1;
+    /** `backupKeyFingerprint()` of the key the files are encrypted under. */
+    keyFingerprint?: string;
+    databases: DatabaseBackupEntry[];
+    /** Declared databases with no file yet (an add-on that never opened it). */
+    absent: string[];
+    /** Databases that could not be copied; the backup carries the others. */
+    failed: Array<{
+        name: string;
+        error: string;
+    }>;
+}
+/** What an add-on hands over to have its database opened and migrated. */
+export interface AddonDatabaseOptions {
+    /** Dated migrations, strictly ascending by id — the same rules as core's ledger. */
+    migrations: Migration[];
+    /** Where the applied ids are recorded. Must start with the owner's slug (dashes as underscores) and `_`. */
+    ledgerTable: string;
+}
+/** A declared add-on database as Admin → Add-ons and the backup (#1723) see it. */
+export interface DeclaredAddonDatabase extends AddonDatabaseDeclaration {
+    /** `<owner>.db` beside the application database; null when no application database is configured. */
+    file: string | null;
+    /** Whether this declaration's ledger is open in this process. */
+    open: boolean;
+}
+/**
+ * The request rules (addonDatabaseRules): the owner is a canonical slug, and
+ * the ledger table starts with its prefix. `openAddonDatabase` applies them,
+ * and so does the test kit's in-memory database
+ * (`@jwilleke/ngdpbase-types/testing`, #1865), so a test refuses what a site
+ * refuses.
+ */
+export declare function checkAddonDatabaseRequest(owner: string, options: AddonDatabaseOptions): void;
+/**
+ * The declaration of this owner's ledger among `declarations`, or a refusal
+ * naming what is missing (#1860). `openAddonDatabase` asks it of the site's
+ * declarations; the test kit asks it of the add-on's own (#1865).
+ */
+export declare function addonDatabaseDeclarationFor(declarations: readonly AddonDatabaseDeclaration[], owner: string, ledgerTable: string): AddonDatabaseDeclaration;
+declare class DatabaseManager extends BaseManager {
+    private provider;
+    private databaseFile;
+    private busyTimeoutMs;
+    private readonly addonDatabases;
+    /** What the start did with a staged restore (#1723), reported once the notifications exist. */
+    private restoreAtStart;
+    /** Why this manager is degraded, one entry per cause, so one cause clearing leaves the others. */
+    private readonly faults;
+    constructor(engine: WikiEngine);
+    initialize(config?: Record<string, unknown>): Promise<void>;
+    /** Whether an application database is open. */
+    isEnabled(): boolean;
+    /**
+     * The open connection, for a row-storing provider's constructor. Throws when
+     * no database is configured, so a provider that needs one fails at boot with
+     * the key to set rather than at its first write.
+     */
+    getHandle<Handle = unknown>(): Handle;
+    /**
+     * Open (or join) an add-on's own database and run its migrations
+     * (ngdp-accounting-addons#13). The file is `<owner>.db` beside the application
+     * database, opened by the same provider under the same key, so it gets the
+     * same network-filesystem refusal, WAL, integrity check and newer-schema
+     * refusal. The first call for an owner opens the file; a later call — from an
+     * add-on that depends on the owner — adds its own ledger to the same file.
+     *
+     * Requires the application database: an operator who has not set
+     * `ngdpbase.database.provider` to `sqlite` has not chosen to keep a database.
+     *
+     * Opens only a declared database (#1860): an enabled add-on declares this
+     * owner and this ledger in `ngdpbase.addons.<slug>.database`. A declaration
+     * with `encrypt: "required"` is refused when `NGDPBASE_DATABASE_KEY` is not
+     * set; nothing is opened in the clear.
+     */
+    openAddonDatabase<Handle = unknown>(owner: string, options: AddonDatabaseOptions): Handle;
+    /**
+     * Every add-on database declared on this site (#1860), whether or not its
+     * add-on is turned on — so a turned-off add-on's file is still listed and
+     * backed up (#1723). One entry per declared ledger; several may share an
+     * owner's file.
+     */
+    getDeclaredDatabases(): DeclaredAddonDatabase[];
+    /**
+     * Why this add-on must not load, decided before it is imported (#1860): it
+     * declares a database `encrypt: "required"` and no key is set. Null when it
+     * may load. Asked by AddonsManager, as the configuration merge's refusals
+     * are (#1559).
+     */
+    addonRefusal(slug: string): string | null;
+    private declarations;
+    /** The one rule: a database declared `encrypt: "required"` is never opened without the key. */
+    private static keyRefusal;
+    /**
+     * Copy every database into the backup BackupManager is writing: the
+     * application database and every declared add-on database, on or off, at
+     * one point in time, on a worker thread. Each goes into its own file,
+     * `<stem>.<name>.db`, beside the document, encrypted under
+     * `NGDPBASE_BACKUP_KEY`; the document references them. A database that
+     * fails is named in `warnings`, and the others are still written.
+     *
+     * Throws when there is no backup key: nothing is ever written unencrypted.
+     */
+    backup(options?: ManagerBackupOptions): Promise<BackupData>;
+    /**
+     * Stage a restore of the databases in a backup, for the next start. Each
+     * backed-up database is opened under the backup key, integrity-checked, and
+     * copied into `<live>.staged` under this site's database key. All or
+     * nothing: if any fails, none is staged. A database the backup does not
+     * contain is left as it is. Live files are never touched here.
+     *
+     * BackupManager takes a fresh backup of the live data before calling this.
+     * A backed-up add-on database that no add-on on this site declares is not
+     * staged, and admins are told.
+     */
+    restore(backupData: BackupData, options?: ManagerRestoreOptions): Promise<void>;
+    /** The restore staged and waiting for the next start, or null. */
+    getStagedRestore(): StagedRestoreManifest | null;
+    /**
+     * Throw away a staged restore before the restart applies it (#1723, D5):
+     * the staged files and the manifest are removed, the live databases are
+     * untouched. Recorded first (`backup-restore-cancel`, refuse): a cancel that
+     * cannot be recorded does not happen.
+     */
+    cancelStagedRestore(ctx: ActorContext): Promise<StagedRestoreManifest>;
+    /**
+     * Tell admins what the start found (#1723): what it did with a staged
+     * restore, and a backup key that is missing or the database key. Called by
+     * the engine once every manager exists: DatabaseManager starts before the
+     * notifications do.
+     */
+    reportAtBoot(): Promise<void>;
+    /** The application database and every declared add-on database (one per owner), on or off. */
+    private backupSources;
+    /** Put a staged restore in place, before any database opens; loud when it cannot. */
+    private applyRestoreAtStart;
+    private backupKey;
+    /** What is wrong with the backup key: missing, or the database key itself (D3). Null when sound. */
+    private backupKeyProblem;
+    /** `ngdpbase.database.backup.worker-timeout-ms`, read at use. */
+    private workerTimeoutMs;
+    /** Degrade for one cause; the dashboard shows every cause still standing. */
+    private fault;
+    private clearFault;
+    private notify;
+    /** Whether every open database passes SQLite's quick check; true when none is configured. */
+    integrityOk(): boolean;
+    /** Closes the add-on databases, then the application database. */
+    shutdown(): Promise<void>;
+}
+export default DatabaseManager;