@harperfast/harper 5.2.0-beta.4 → 5.2.0

package/dist/dataLayer/restoreMarker.js

@@ -0,0 +1,261 @@
+'use strict';
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RESTORING_MARKER_SUFFIX = exports.RESTORE_LOCK_SUFFIX = exports.RESTORE_META_DIR = void 0;
+exports.restoreMetaDir = restoreMetaDir;
+exports.restoreLockPath = restoreLockPath;
+exports.restoringMarkerPath = restoringMarkerPath;
+exports.restoreMarkerPresent = restoreMarkerPresent;
+exports.checkRestoreState = checkRestoreState;
+exports.acquireRestoreLock = acquireRestoreLock;
+exports.releaseRestoreLock = releaseRestoreLock;
+exports.beginRestore = beginRestore;
+exports.completeRestore = completeRestore;
+exports.abandonRestore = abandonRestore;
+exports.clearRestoreMarker = clearRestoreMarker;
+exports.scanBlockedRestores = scanBlockedRestores;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const node_crypto_1 = require("node:crypto");
+const rocksdb_js_1 = require("@harperfast/rocksdb-js");
+/**
+ * Restore lock + marker protocol for RocksDB database restores (online operation and offline CLI),
+ * and the shared per-database exclusion used by `dropDatabase` so a drop and a restore can never
+ * mutate the same directory concurrently.
+ *
+ * Restore metadata lives in an isolated `` `restore` `` directory *beside* the database directory
+ * (never inside it, since a restore purges the destination). Each database's two files are keyed by
+ * a hash of the database directory name rather than being suffixed onto the name itself. That keeps
+ * them out of the database-name namespace — a legal database literally named `orders.restoring`
+ * would otherwise be mistaken for the restore marker of `orders`, and a 250-character name plus a
+ * `.restore.lock` suffix would exceed the 255-byte `NAME_MAX` on most filesystems. The directory
+ * name deliberately contains a backtick: `schemaRegex` (the database-name validator) forbids only
+ * `/` and `` ` `` among filesystem-legal characters, so no legal database can ever occupy this path
+ * — including a database literally named `.restore` (which *is* a legal name, so a plain `.restore`
+ * directory would collide with it and land the markers inside the live database). The directory is
+ * not itself a RocksDB/LMDB database (no `CURRENT`/`MANIFEST-`/`.mdb`), so the startup scan ignores
+ * it, and no user can create a database that resolves to it.
+ *
+ * - `<meta-dir>/<key>.lock` — an OS-level exclusive file lock (via rocksdb-js `tryFileLock`),
+ *   effective across processes, containers, and worker threads, auto-released on process exit.
+ *   Only *held-ness* is meaningful; the file itself persists after release (harmless). Held for the
+ *   duration of a restore, and briefly by `dropDatabase` so the two serialize on the same primitive.
+ *   Known limitation: the lock is owned by the process, so if the restore job's worker *thread*
+ *   dies without the process exiting, the lock stays held (restores 409) until Harper restarts.
+ * - `<meta-dir>/<key>.restoring` — the completion marker. Written (and fsynced) after the lock is
+ *   acquired and before the destructive restore begins; deleted only after the restore completes
+ *   successfully, while still holding the lock. Its *existence* means "a restore started and has
+ *   not finished successfully". Its first line records the database directory name so the startup
+ *   scan can map a marker back to the database it blocks without decoding the hashed key.
+ */
+// The backtick makes this an illegal database name (schemaRegex rejects `/` and backtick only), so
+// it can never collide with a real database directory — see the module header.
+exports.RESTORE_META_DIR = '`restore`';
+exports.RESTORE_LOCK_SUFFIX = '.lock';
+exports.RESTORING_MARKER_SUFFIX = '.restoring';
+/**
+ * Directory holding the restore metadata for a database — the reserved `` `restore` `` sibling of
+ * the database directory (see the module header for why the name contains a backtick). Shared by
+ * every database under the same parent, so a single readdir surfaces all pending restores during
+ * the startup scan.
+ */
+function restoreMetaDir(dbPath) {
+    return (0, node_path_1.join)((0, node_path_1.dirname)(dbPath), exports.RESTORE_META_DIR);
+}
+/**
+ * Filesystem-safe, length-bounded key for a database's restore metadata files. Hashing the
+ * database directory name (not the full path, so it is stable regardless of where the databases
+ * root lives) keeps the metadata filenames short and collision-free while staying independent of
+ * the database-name namespace. Database directory names are unique within a databases root, so
+ * their hashes are too.
+ */
+function restoreMetaKey(dbPath) {
+    return (0, node_crypto_1.createHash)('sha256').update((0, node_path_1.basename)(dbPath)).digest('hex').slice(0, 32);
+}
+function restoreLockPath(dbPath) {
+    return (0, node_path_1.join)(restoreMetaDir(dbPath), restoreMetaKey(dbPath) + exports.RESTORE_LOCK_SUFFIX);
+}
+function restoringMarkerPath(dbPath) {
+    return (0, node_path_1.join)(restoreMetaDir(dbPath), restoreMetaKey(dbPath) + exports.RESTORING_MARKER_SUFFIX);
+}
+/**
+ * Whether a `.restoring` marker exists for a database. Cheaper than `checkRestoreState` and, unlike
+ * it, safe to call while *this* thread holds the restore lock: `checkRestoreState` would re-probe
+ * the lock (which reads as held from the same thread) and report 'in-progress' rather than telling
+ * a caller that a *leftover* marker is present. `dropDatabase` uses this after acquiring the lock to
+ * distinguish debris from a crashed restore.
+ */
+function restoreMarkerPresent(dbPath) {
+    return (0, node_fs_1.existsSync)(restoringMarkerPath(dbPath));
+}
+/**
+ * Determine the restore state of a database directory. Used by startup database detection and
+ * the open-database guards:
+ * - 'in-progress': marker present and the restore lock is held (a restore is running in some
+ *   process) — do not load.
+ * - 'incomplete': marker present but the lock is free (crashed mid-restore; the directory may
+ *   be partial garbage) — do not load; rerun the restore.
+ * - 'clear': no marker — load normally (a stale, unheld lock file alone is fine).
+ *
+ * The marker is checked FIRST and the lock is only probed when the marker exists. Probing takes
+ * and releases the flock, and probes are mutually exclusive across threads — if every rescan on
+ * every thread probed the (persistent) lock file of a long-ago-restored database, concurrent
+ * rescans would collide and misclassify healthy databases as 'in-progress'. Marker-first is
+ * safe: `beginRestore` writes (and fsyncs) the marker immediately after taking the lock and
+ * before any destructive step, so a database without a marker has nothing to protect yet.
+ */
+function checkRestoreState(dbPath) {
+    if (!(0, node_fs_1.existsSync)(restoringMarkerPath(dbPath)))
+        return 'clear';
+    const lockPath = restoreLockPath(dbPath);
+    if ((0, node_fs_1.existsSync)(lockPath)) {
+        const token = (0, rocksdb_js_1.tryFileLock)(lockPath);
+        if (token === 0)
+            return 'in-progress';
+        (0, rocksdb_js_1.fileLockRelease)(token);
+    }
+    return 'incomplete';
+}
+/**
+ * fsync a directory so a create/unlink of an entry within it is durable. Best-effort: Windows (and
+ * some filesystems) reject opening a directory for fsync with EPERM/EISDIR/ENOTSUP — the durability
+ * flush is a POSIX nicety, so treat those as a no-op rather than failing the restore.
+ */
+function fsyncDir(dir) {
+    let dirFd;
+    try {
+        dirFd = (0, node_fs_1.openSync)(dir, 'r');
+    }
+    catch (error) {
+        if (error.code === 'EPERM' || error.code === 'EISDIR' || error.code === 'ENOTSUP')
+            return;
+        throw error;
+    }
+    try {
+        (0, node_fs_1.fsyncSync)(dirFd);
+    }
+    finally {
+        (0, node_fs_1.closeSync)(dirFd);
+    }
+}
+/**
+ * Take the per-database restore lock without writing a marker. Used by `dropDatabase` so a drop and
+ * a restore serialize on the same primitive: whichever takes the lock first runs to completion; the
+ * other gets a 409. Throws (statusCode 409) if the lock is already held.
+ */
+function acquireRestoreLock(dbPath) {
+    (0, node_fs_1.mkdirSync)(restoreMetaDir(dbPath), { recursive: true });
+    const token = (0, rocksdb_js_1.tryFileLock)(restoreLockPath(dbPath));
+    if (token === 0) {
+        const error = new Error(`Restore already in progress for database at ${dbPath}`);
+        error.statusCode = 409;
+        throw error;
+    }
+    return { token, dbPath, preexisting: false };
+}
+/**
+ * Release a lock taken by `acquireRestoreLock` (no marker to remove).
+ */
+function releaseRestoreLock(lock) {
+    (0, rocksdb_js_1.fileLockRelease)(lock.token);
+}
+/**
+ * Acquire the per-database restore lock and write the restoring marker. Call before any
+ * destructive step. Returns the lock (with `preexisting` set when a marker was already present, so
+ * a failed recovery attempt knows not to clear it). Throws (statusCode 409) if another restore
+ * already holds the lock.
+ */
+function beginRestore(dbPath) {
+    const markerPath = restoringMarkerPath(dbPath);
+    const preexisting = (0, node_fs_1.existsSync)(markerPath);
+    const lock = acquireRestoreLock(dbPath);
+    try {
+        const fd = (0, node_fs_1.openSync)(markerPath, 'w');
+        try {
+            // first line is the database directory name so the startup scan can map this marker back to
+            // the database it blocks without reversing the hashed key
+            (0, node_fs_1.writeSync)(fd, `${(0, node_path_1.basename)(dbPath)}\nrestore started ${new Date().toISOString()}\n`);
+            (0, node_fs_1.fsyncSync)(fd);
+        }
+        finally {
+            (0, node_fs_1.closeSync)(fd);
+        }
+        // fsync the metadata directory so the marker's directory entry is durable — without this a
+        // power loss can lose the entry, and a half-purged database would load as healthy
+        fsyncDir(restoreMetaDir(dbPath));
+    }
+    catch (error) {
+        (0, rocksdb_js_1.fileLockRelease)(lock.token);
+        throw error;
+    }
+    return { ...lock, preexisting };
+}
+/**
+ * Mark the restore successful: delete the marker (while still holding the lock), then release
+ * the lock.
+ */
+function completeRestore(lock) {
+    try {
+        (0, node_fs_1.unlinkSync)(restoringMarkerPath(lock.dbPath));
+        // fsync the metadata directory so the marker's *removal* is durable — symmetric with the
+        // creation fsync in beginRestore. Without it, a power loss could resurrect the marker's
+        // directory entry and misclassify a fully-restored database as incomplete.
+        fsyncDir(restoreMetaDir(lock.dbPath));
+    }
+    finally {
+        (0, rocksdb_js_1.fileLockRelease)(lock.token);
+    }
+}
+/**
+ * Release the lock after a failed restore, leaving the marker in place so the database is
+ * detected as an incomplete restore (and not loaded) until a rerun succeeds.
+ */
+function abandonRestore(lock) {
+    (0, rocksdb_js_1.fileLockRelease)(lock.token);
+}
+/**
+ * Remove a database's restore marker if one is present, then release the lock. Used by
+ * `dropDatabase`: a dropped database that carried an incomplete-restore marker should not leave the
+ * marker behind to block a future database of the same name. No-op on the marker if none exists.
+ */
+function clearRestoreMarker(lock) {
+    try {
+        const markerPath = restoringMarkerPath(lock.dbPath);
+        if ((0, node_fs_1.existsSync)(markerPath)) {
+            (0, node_fs_1.unlinkSync)(markerPath);
+            fsyncDir(restoreMetaDir(lock.dbPath));
+        }
+    }
+    finally {
+        (0, rocksdb_js_1.fileLockRelease)(lock.token);
+    }
+}
+/**
+ * Scan a databases root's reserved `` `restore` `` metadata directory and report every database currently blocked from
+ * loading, mapping each surviving marker back to its database name via the marker's first line.
+ * Returns `[dbName, state]` pairs for markers whose state is `in-progress` or `incomplete`
+ * (a `clear` result means the marker was removed concurrently and the database is loadable).
+ */
+function scanBlockedRestores(databasesRoot) {
+    const metaDir = (0, node_path_1.join)(databasesRoot, exports.RESTORE_META_DIR);
+    if (!(0, node_fs_1.existsSync)(metaDir))
+        return [];
+    const blocked = [];
+    for (const entry of (0, node_fs_1.readdirSync)(metaDir, { withFileTypes: true })) {
+        if (!entry.isFile() || !entry.name.endsWith(exports.RESTORING_MARKER_SUFFIX))
+            continue;
+        let dbName;
+        try {
+            dbName = (0, node_fs_1.readFileSync)((0, node_path_1.join)(metaDir, entry.name), 'utf8').split('\n', 1)[0];
+        }
+        catch {
+            continue; // marker removed concurrently
+        }
+        if (!dbName)
+            continue;
+        const state = checkRestoreState((0, node_path_1.join)(databasesRoot, dbName));
+        if (state !== 'clear')
+            blocked.push([dbName, state]);
+    }
+    return blocked;
+}
+//# sourceMappingURL=restoreMarker.js.map

package/dist/dataLayer/restoreMarker.js.map

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

package/dist/dataLayer/rocksdbBackup.d.ts

@@ -0,0 +1,127 @@
+import { PassThrough } from 'node:stream';
+import { RocksDatabase, type BackupInfo } from '@harperfast/rocksdb-js';
+import { ClientError } from '../utility/errors/hdbError.ts';
+/**
+ * Shared core for the RocksDB managed-backup operations (`create_backup`, `list_backups`,
+ * `verify_backup`, `delete_backup`, `purge_backups`, `restore_backup`) and the RocksDB path of
+ * `get_backup`. Used by both the operation API (running server) and the CLI (stopped server) so
+ * the two behave identically.
+ *
+ * Directory backups are confined to `<backupsRoot>/<database>/` where the backups root comes
+ * from the `storage.backupPath` config (default `<hdb_root>/backups`); operations never accept
+ * arbitrary filesystem paths.
+ */
+export declare class BackupNotFoundError extends ClientError {
+    constructor(message: string);
+}
+export declare class BackupInProgressError extends ClientError {
+    constructor(message: string);
+}
+export declare function getBackupsRoot(): string;
+/**
+ * The database name becomes a path segment under the backups root and the databases root —
+ * reject anything that could traverse outside them.
+ */
+export declare function validateDatabaseName(databaseName: any): void;
+export declare function backupDirForDatabase(databaseName: string): string;
+/**
+ * Resolve the single root store for a database. A database can span multiple root stores when a
+ * table has a per-table `path` config; backing up such a database is not supported and errors
+ * descriptively. Engine gating (RocksDB vs LMDB) is done inline at each call site.
+ */
+export declare function resolveSingleRootStore(databaseName: string): any;
+export declare function listBackupsInDir(backupDir: string): Promise<BackupInfo[]>;
+export declare function listBackups(request: any): Promise<{
+    backup_id: number;
+    timestamp: number;
+    size: number;
+    file_count: number;
+    blobs: boolean;
+}[]>;
+export declare function deleteBackup(request: any): Promise<{
+    ok: boolean;
+}>;
+export declare function purgeBackups(request: any): Promise<{
+    deleted: number;
+    remaining: number;
+}>;
+export declare function validateCreateBackup(request: any): Promise<void>;
+export declare function createBackup(request: any): Promise<{
+    size?: number;
+    timestamp?: any;
+    database: string;
+    backup_id: any;
+    blobs: boolean;
+}>;
+export declare function validateVerifyBackup(request: any): Promise<void>;
+export declare function verifyBackup(request: any): Promise<{
+    database: string;
+    backup_id: number;
+    ok: boolean;
+    blobs: boolean;
+}>;
+export declare function validateRestoreBackup(request: any): Promise<void>;
+/**
+ * Online restore of a user database (see the design's restore lock + marker protocol):
+ * take the per-database restore lock, write the restoring marker, close the database across all
+ * worker threads, restore, delete the marker, release the lock, and reload everywhere.
+ */
+export declare function restoreBackup(request: any): Promise<{
+    database: string;
+    backup_id: number;
+}>;
+/**
+ * Returns a Readable (with `.headers`) streaming a full-snapshot tar (optionally gzipped) of the
+ * database's current state. No scratch disk; a consumer error aborts the native backup cleanly.
+ * `noCompression` opts out of serverHandlers' accept-encoding auto-gzip — this response must never
+ * be compressed by the server.
+ *
+ * With blobs included (the default; `excludeBlobs` opts out), the database's file-backed blob roots
+ * are appended to the same archive under `blobs/<rootIndex>/<relpath>` so a downloaded backup is a
+ * complete Harper database. Blob capture is best-effort point-in-time (the archive contains whatever
+ * files exist while it streams); a blob deleted mid-stream is skipped.
+ */
+export declare function createBackupStream(rootStore: RocksDatabase, databaseName: string, gzip: boolean, excludeBlobs?: boolean): PassThrough;
+/**
+ * Offline create: open the RocksDatabase directly, run an ordinary incremental directory backup
+ * into the configured backup root, and close. RocksDB is single-writer, so this collides on the
+ * database lock if the server is running — callers guard on the server being stopped.
+ */
+export declare function createBackupOffline(databaseName: string, excludeBlobs?: boolean): Promise<{
+    size?: number;
+    timestamp?: any;
+    database: string;
+    backup_id: any;
+    blobs: boolean;
+}>;
+/**
+ * Offline restore (required for the `system` database; works for any database). Runs the same
+ * lock + marker protocol as the online operation so a crashed CLI restore is detected at next
+ * server start. `targetDatabase` restores into a different database directory (non-destructive
+ * for the source database); the server picks it up on next start via normal engine detection.
+ */
+export declare function restoreBackupOffline(databaseName: string, backupId?: number, targetDatabase?: string): Promise<{
+    database: string;
+    backup_id: number;
+    restored_to: string;
+}>;
+export declare function listBackupsOffline(databaseName: string): Promise<{
+    backup_id: number;
+    timestamp: number;
+    size: number;
+    file_count: number;
+    blobs: boolean;
+}[]>;
+export declare function verifyBackupOffline(databaseName: string, backupId: number, verifyChecksum?: boolean): Promise<{
+    database: string;
+    backup_id: number;
+    ok: boolean;
+    blobs: boolean;
+}>;
+export declare function deleteBackupOffline(databaseName: string, backupId: number): Promise<{
+    ok: boolean;
+}>;
+export declare function purgeBackupsOffline(databaseName: string, keepCount: number): Promise<{
+    deleted: number;
+    remaining: number;
+}>;