camusdb 0.1.0

package/dist/backup.d.ts

@@ -0,0 +1,98 @@
+/**
+ * This file is part of CamusDB
+ *
+ * For the full copyright and license information, please view the LICENSE.txt
+ * file that was distributed with this source code.
+ */
+import type { ClientRuntime } from './runtime.js';
+/** One backup in the node's catalog. */
+export interface CamusBackupInfo {
+    readonly backupId: string;
+    readonly formatVersion: number;
+    /** `full`, `incremental`, or `coordinated`. */
+    readonly type: string;
+    readonly createdAtUtc?: string | undefined;
+    /** The backup this one builds on. Absent for a full backup. */
+    readonly parentBackupId?: string | undefined;
+    readonly partitionCount: number;
+    readonly clusterSnapshotNode?: number | undefined;
+    readonly clusterSnapshotPhysical?: number | undefined;
+    readonly clusterSnapshotCounter?: number | undefined;
+    /** What the caller asked for, and what the server actually took. */
+    readonly requestedKind?: string | undefined;
+    readonly actualKind?: string | undefined;
+    /** Why the server took a different kind than the one requested. */
+    readonly substitutionReason?: string | undefined;
+    /** True when the server marked this backup unusable for a restore. */
+    readonly isInvalid: boolean;
+    readonly invalidReason?: string | undefined;
+    /** The window this backup can restore to, in Unix milliseconds. */
+    readonly minRecoverablePhysicalMs?: number | undefined;
+    readonly maxRecoverablePhysicalMs?: number | undefined;
+    readonly clusterId?: string | undefined;
+    readonly coordinatorNode?: string | undefined;
+    /** True when the server took a different kind of backup than the one requested. */
+    readonly wasSubstituted: boolean;
+}
+/** One backup that retention deleted, or would delete. */
+export interface CamusBackupGcDeletion {
+    readonly backupId: string;
+    readonly type: string;
+    readonly createdAtUtc?: string | undefined;
+    readonly bytes: number;
+    readonly reason: string;
+}
+/** One file or directory that belongs to no backup. */
+export interface CamusBackupGcOrphan {
+    readonly name: string;
+    readonly isDirectory: boolean;
+    readonly reason: string;
+}
+/** What a retention run did, or would do. */
+export interface CamusBackupGcResult {
+    /** False for a preview: nothing was deleted. */
+    readonly applied: boolean;
+    readonly bytesReclaimed: number;
+    readonly retentionDeletions: CamusBackupGcDeletion[];
+    readonly orphanReclamations: CamusBackupGcOrphan[];
+}
+/**
+ * The node's online backup administration API: take a full, incremental, or coordinated backup,
+ * list the catalog, resolve a restore chain, and run retention.
+ *
+ * It is server-level and node-wide, not scoped to the client's database. Every database on the
+ * server shares one storage node, so a backup captures all of them. It needs a superuser token
+ * when authentication is on.
+ *
+ * Restore is an offline operator procedure and is deliberately not reachable here.
+ *
+ * The routes are REST and JSON only. They have no SQL form and no gRPC service, so a gRPC client
+ * must configure `backupEndpoint` to say where the HTTP port is.
+ */
+export declare class CamusBackupClient {
+    private readonly runtime;
+    /** @internal Reach it through `client.backups`. */
+    constructor(runtime: ClientRuntime);
+    /** Takes a full backup: a complete copy of the node's base image. */
+    takeFullBackup(signal?: AbortSignal): Promise<CamusBackupInfo>;
+    /** Takes an incremental backup, relative to `parentBackupId`. */
+    takeIncrementalBackup(parentBackupId: string, signal?: AbortSignal): Promise<CamusBackupInfo>;
+    /** Takes a cluster-coordinated backup. It must reach the coordinator node specifically. */
+    takeCoordinatedBackup(signal?: AbortSignal): Promise<CamusBackupInfo>;
+    /** Every backup in the node's catalog. */
+    listBackups(signal?: AbortSignal): Promise<CamusBackupInfo[]>;
+    /**
+     * The chain of backups a restore of `leafBackupId` needs, from its base full backup to the leaf.
+     * Use it to check that every link is present and valid before relying on the leaf.
+     */
+    getChain(leafBackupId: string, signal?: AbortSignal): Promise<CamusBackupInfo[]>;
+    /** Reports what retention would delete, without deleting anything. */
+    previewGarbageCollection(signal?: AbortSignal): Promise<CamusBackupGcResult>;
+    /** Runs retention: deletes the backups its policy has aged out, and reclaims orphaned files. */
+    collectGarbage(signal?: AbortSignal): Promise<CamusBackupGcResult>;
+    private takeBackup;
+    private list;
+    private collect;
+    private send;
+}
+//# sourceMappingURL=backup.d.ts.map

package/dist/backup.d.ts.map

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

package/dist/backup.js

@@ -0,0 +1,153 @@
+/**
+ * This file is part of CamusDB
+ *
+ * For the full copyright and license information, please view the LICENSE.txt
+ * file that was distributed with this source code.
+ */
+import { CamusError } from './errors.js';
+import { CamusErrorCode } from './error-codes.js';
+import { asNumber } from './json.js';
+import { sendJson } from './transport/http.js';
+/**
+ * The node's online backup administration API: take a full, incremental, or coordinated backup,
+ * list the catalog, resolve a restore chain, and run retention.
+ *
+ * It is server-level and node-wide, not scoped to the client's database. Every database on the
+ * server shares one storage node, so a backup captures all of them. It needs a superuser token
+ * when authentication is on.
+ *
+ * Restore is an offline operator procedure and is deliberately not reachable here.
+ *
+ * The routes are REST and JSON only. They have no SQL form and no gRPC service, so a gRPC client
+ * must configure `backupEndpoint` to say where the HTTP port is.
+ */
+export class CamusBackupClient {
+    runtime;
+    /** @internal Reach it through `client.backups`. */
+    constructor(runtime) {
+        this.runtime = runtime;
+    }
+    /** Takes a full backup: a complete copy of the node's base image. */
+    takeFullBackup(signal) {
+        return this.takeBackup(['v1', 'backups', 'full'], undefined, 'Take full backup failed', signal);
+    }
+    /** Takes an incremental backup, relative to `parentBackupId`. */
+    takeIncrementalBackup(parentBackupId, signal) {
+        return this.takeBackup(['v1', 'backups', 'incremental'], { parentBackupId }, 'Take incremental backup failed', signal);
+    }
+    /** Takes a cluster-coordinated backup. It must reach the coordinator node specifically. */
+    takeCoordinatedBackup(signal) {
+        return this.takeBackup(['v1', 'backups', 'coordinated'], undefined, 'Take coordinated backup failed', signal);
+    }
+    /** Every backup in the node's catalog. */
+    listBackups(signal) {
+        return this.list(['v1', 'backups'], 'List backups failed', signal);
+    }
+    /**
+     * The chain of backups a restore of `leafBackupId` needs, from its base full backup to the leaf.
+     * Use it to check that every link is present and valid before relying on the leaf.
+     */
+    getChain(leafBackupId, signal) {
+        return this.list(['v1', 'backups', leafBackupId, 'chain'], 'Get backup chain failed', signal);
+    }
+    /** Reports what retention would delete, without deleting anything. */
+    previewGarbageCollection(signal) {
+        return this.collect(true, signal);
+    }
+    /** Runs retention: deletes the backups its policy has aged out, and reclaims orphaned files. */
+    collectGarbage(signal) {
+        return this.collect(false, signal);
+    }
+    async takeBackup(path, body, failureMessage, signal) {
+        const reply = await this.send(path, 'POST', body, undefined, signal);
+        if (reply.status !== 'ok' || reply.backup === undefined || reply.backup === null) {
+            throw new CamusError(reply.code ?? CamusErrorCode.Generic, reply.message ?? failureMessage);
+        }
+        return readBackupInfo(reply.backup);
+    }
+    async list(path, failureMessage, signal) {
+        const reply = await this.send(path, 'GET', undefined, undefined, signal);
+        if (reply.status !== 'ok') {
+            throw new CamusError(reply.code ?? CamusErrorCode.Generic, reply.message ?? failureMessage);
+        }
+        return (reply.backups ?? []).map(readBackupInfo);
+    }
+    async collect(dryRun, signal) {
+        const reply = await this.send(['v1', 'backups', 'gc'], 'POST', undefined, { dryRun: dryRun ? 'true' : 'false' }, signal);
+        if (reply.status !== 'ok') {
+            throw new CamusError(reply.code ?? CamusErrorCode.Generic, reply.message ?? 'Backup garbage collection failed');
+        }
+        return {
+            applied: reply.applied === true,
+            bytesReclaimed: asNumber(reply.bytesReclaimed),
+            retentionDeletions: (reply.retentionDeletions ?? []).map(readDeletion),
+            orphanReclamations: (reply.orphanReclamations ?? []).map(readOrphan),
+        };
+    }
+    async send(path, method, body, query, signal) {
+        const endpoint = this.runtime.backupEndpoint();
+        return sendJson(this.runtime.pool, {
+            endpoint,
+            path,
+            method,
+            body,
+            query,
+            token: await this.runtime.auth.getToken(signal),
+            timeoutSeconds: this.runtime.config.backupTimeoutSeconds,
+            signal,
+        });
+    }
+}
+function readBackupInfo(value) {
+    const record = (value ?? {});
+    const requestedKind = readString(record.requestedKind);
+    const actualKind = readString(record.actualKind);
+    return {
+        backupId: readString(record.backupId) ?? '',
+        formatVersion: asNumber(record.formatVersion),
+        type: readString(record.type) ?? '',
+        createdAtUtc: readString(record.createdAtUtc),
+        parentBackupId: readString(record.parentBackupId),
+        partitionCount: asNumber(record.partitionCount),
+        clusterSnapshotNode: readOptionalNumber(record.clusterSnapshotNode),
+        clusterSnapshotPhysical: readOptionalNumber(record.clusterSnapshotPhysical),
+        clusterSnapshotCounter: readOptionalNumber(record.clusterSnapshotCounter),
+        requestedKind,
+        actualKind,
+        substitutionReason: readString(record.substitutionReason),
+        isInvalid: record.isInvalid === true,
+        invalidReason: readString(record.invalidReason),
+        minRecoverablePhysicalMs: readOptionalNumber(record.minRecoverablePhysicalMs),
+        maxRecoverablePhysicalMs: readOptionalNumber(record.maxRecoverablePhysicalMs),
+        clusterId: readString(record.clusterId),
+        coordinatorNode: readString(record.coordinatorNode),
+        wasSubstituted: requestedKind !== undefined && actualKind !== undefined && requestedKind !== actualKind,
+    };
+}
+function readDeletion(value) {
+    const record = (value ?? {});
+    return {
+        backupId: readString(record.backupId) ?? '',
+        type: readString(record.type) ?? '',
+        createdAtUtc: readString(record.createdAtUtc),
+        bytes: asNumber(record.bytes),
+        reason: readString(record.reason) ?? '',
+    };
+}
+function readOrphan(value) {
+    const record = (value ?? {});
+    return {
+        name: readString(record.name) ?? '',
+        isDirectory: record.isDirectory === true,
+        reason: readString(record.reason) ?? '',
+    };
+}
+function readString(value) {
+    return typeof value === 'string' && value.length > 0 ? value : undefined;
+}
+function readOptionalNumber(value) {
+    if (value === undefined || value === null)
+        return undefined;
+    return asNumber(value);
+}
+//# sourceMappingURL=backup.js.map

package/dist/backup.js.map

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

package/dist/cache.d.ts

@@ -0,0 +1,90 @@
+/**
+ * This file is part of CamusDB
+ *
+ * For the full copyright and license information, please view the LICENSE.txt
+ * file that was distributed with this source code.
+ */
+import type { CamusHlcTimestamp } from './hlc.js';
+/** How the server resolved a cache-hinted `SELECT`. */
+export declare const CamusCacheStatus: {
+    /** The statement carried no hint, so the cache was not consulted. */
+    readonly None: "none";
+    /** A stored result answered the statement. */
+    readonly Hit: "hit";
+    /** No stored result answered it; this one may now be stored. */
+    readonly Miss: "miss";
+    /** The cache path was entered and abandoned. `bypassReason` says why. */
+    readonly Bypass: "bypass";
+    /** A stored result was past its age and was recomputed. */
+    readonly StaleRevalidated: "stale-revalidated";
+    /** The computed result was dropped before it could be stored. */
+    readonly EvictedBeforePublish: "evicted-before-publish";
+    /** A status this driver does not know. Read `rawStatus`. */
+    readonly Unknown: "unknown";
+};
+export type CamusCacheStatus = (typeof CamusCacheStatus)[keyof typeof CamusCacheStatus];
+/**
+ * What the server reported about a cache-hinted `SELECT`.
+ *
+ * It is present only when the statement entered the cache path, so `undefined` means the statement
+ * carried no `{cache=…}` hint. A hinted statement that skipped the cache reports
+ * `status: 'bypass'` with a `bypassReason`.
+ */
+export interface CamusCacheMetadata {
+    /** The parsed status. */
+    readonly status: CamusCacheStatus;
+    /** The status exactly as the server wrote it. Read it when `status` is `unknown`. */
+    readonly rawStatus?: string | undefined;
+    /** Why the cache was skipped, or why the result was not stored. Absent otherwise. */
+    readonly bypassReason?: string | undefined;
+    /** The logical cache family from the hint. Always set when this object is present. */
+    readonly name?: string | undefined;
+    /** When a served result was computed. Present only on a hit. */
+    readonly cachedAtHlc?: CamusHlcTimestamp | undefined;
+    /** Roughly how old a served result is, in milliseconds. Present only on a hit. */
+    readonly ageMs?: number | undefined;
+    /** True when a stored result answered the statement. */
+    readonly isHit: boolean;
+}
+/** Builds the public object from the parts a transport decoded. */
+export declare function makeCacheMetadata(parts: {
+    rawStatus?: string | undefined;
+    bypassReason?: string | undefined;
+    name?: string | undefined;
+    cachedAtHlc?: CamusHlcTimestamp | undefined;
+    ageMs?: number | undefined;
+}): CamusCacheMetadata;
+/**
+ * Builds the `{cache=…}` hint a `SELECT` carries to ask for its result to be cached.
+ *
+ * Put the returned text **immediately after the table reference**, and after its alias when it has
+ * one. The hint applies to the whole statement, not only to the table it is attached to, and only
+ * one hint per statement is allowed.
+ *
+ * ```ts
+ * const hint = cacheHint('recent_orders', { ttlMs: 30_000 });
+ * const result = await client.query(`SELECT id, total FROM orders ${hint} WHERE status = @status`, {
+ *   status: 1,
+ * });
+ * ```
+ *
+ * @param name the logical cache family. It is written into the statement as a bare identifier, so
+ * it must be one: a letter or an underscore, then letters, digits, or underscores. A hyphen, a dot
+ * and a colon are all parse errors on the server, and are refused here rather than sent.
+ * @param options.ttlMs how long a stored result stays fresh, in milliseconds.
+ * @param options.strict when true, the server validates each hit against live storage.
+ */
+export declare function cacheHint(name: string, options?: {
+    ttlMs?: number;
+    strict?: boolean;
+}): string;
+/**
+ * The statement that drops every cached result in one family, for the current database.
+ *
+ * The family name is a quoted string here rather than a bare identifier, so it accepts more than
+ * `cacheHint` does — a name minted elsewhere, with a hyphen in it, can still be evicted.
+ */
+export declare function evictCacheStatement(name: string): string;
+/** The statement that drops every cached result for the current database. */
+export declare function evictAllCacheStatement(): string;
+//# sourceMappingURL=cache.d.ts.map

package/dist/cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../src/cache.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAGlD,uDAAuD;AACvD,eAAO,MAAM,gBAAgB;IAC3B,qEAAqE;;IAErE,8CAA8C;;IAE9C,gEAAgE;;IAEhE,yEAAyE;;IAEzE,2DAA2D;;IAE3D,iEAAiE;;IAEjE,4DAA4D;;CAEpD,CAAC;AAEX,MAAM,MAAM,gBAAgB,GAAG,CAAC,OAAO,gBAAgB,CAAC,CAAC,MAAM,OAAO,gBAAgB,CAAC,CAAC;AAExF;;;;;;GAMG;AACH,MAAM,WAAW,kBAAkB;IACjC,yBAAyB;IACzB,QAAQ,CAAC,MAAM,EAAE,gBAAgB,CAAC;IAElC,qFAAqF;IACrF,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAExC,qFAAqF;IACrF,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAE3C,sFAAsF;IACtF,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAEnC,gEAAgE;IAChE,QAAQ,CAAC,WAAW,CAAC,EAAE,iBAAiB,GAAG,SAAS,CAAC;IAErD,kFAAkF;IAClF,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAEpC,wDAAwD;IACxD,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;CACzB;AAED,mEAAmE;AACnE,wBAAgB,iBAAiB,CAAC,KAAK,EAAE;IACvC,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/B,YAAY,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAClC,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1B,WAAW,CAAC,EAAE,iBAAiB,GAAG,SAAS,CAAC;IAC5C,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC5B,GAAG,kBAAkB,CAYrB;AAuBD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,MAAM,CAkB9F;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAGxD;AAsBD,6EAA6E;AAC7E,wBAAgB,sBAAsB,IAAI,MAAM,CAE/C"}

package/dist/cache.js

@@ -0,0 +1,121 @@
+/**
+ * This file is part of CamusDB
+ *
+ * For the full copyright and license information, please view the LICENSE.txt
+ * file that was distributed with this source code.
+ */
+import { validateBareName } from './sql-syntax.js';
+/** How the server resolved a cache-hinted `SELECT`. */
+export const CamusCacheStatus = {
+    /** The statement carried no hint, so the cache was not consulted. */
+    None: 'none',
+    /** A stored result answered the statement. */
+    Hit: 'hit',
+    /** No stored result answered it; this one may now be stored. */
+    Miss: 'miss',
+    /** The cache path was entered and abandoned. `bypassReason` says why. */
+    Bypass: 'bypass',
+    /** A stored result was past its age and was recomputed. */
+    StaleRevalidated: 'stale-revalidated',
+    /** The computed result was dropped before it could be stored. */
+    EvictedBeforePublish: 'evicted-before-publish',
+    /** A status this driver does not know. Read `rawStatus`. */
+    Unknown: 'unknown',
+};
+/** Builds the public object from the parts a transport decoded. */
+export function makeCacheMetadata(parts) {
+    const status = parseCacheStatus(parts.rawStatus);
+    return {
+        status,
+        rawStatus: parts.rawStatus,
+        bypassReason: parts.bypassReason,
+        name: parts.name,
+        cachedAtHlc: parts.cachedAtHlc,
+        ageMs: parts.ageMs,
+        isHit: status === CamusCacheStatus.Hit,
+    };
+}
+function parseCacheStatus(status) {
+    switch (status) {
+        case undefined:
+            return CamusCacheStatus.None;
+        case 'hit':
+            return CamusCacheStatus.Hit;
+        case 'miss':
+            return CamusCacheStatus.Miss;
+        case 'bypass':
+            return CamusCacheStatus.Bypass;
+        case 'stale-revalidated':
+            return CamusCacheStatus.StaleRevalidated;
+        case 'evicted-before-publish':
+            return CamusCacheStatus.EvictedBeforePublish;
+        default:
+            return CamusCacheStatus.Unknown;
+    }
+}
+const MAX_CACHE_NAME_LENGTH = 128;
+/**
+ * Builds the `{cache=…}` hint a `SELECT` carries to ask for its result to be cached.
+ *
+ * Put the returned text **immediately after the table reference**, and after its alias when it has
+ * one. The hint applies to the whole statement, not only to the table it is attached to, and only
+ * one hint per statement is allowed.
+ *
+ * ```ts
+ * const hint = cacheHint('recent_orders', { ttlMs: 30_000 });
+ * const result = await client.query(`SELECT id, total FROM orders ${hint} WHERE status = @status`, {
+ *   status: 1,
+ * });
+ * ```
+ *
+ * @param name the logical cache family. It is written into the statement as a bare identifier, so
+ * it must be one: a letter or an underscore, then letters, digits, or underscores. A hyphen, a dot
+ * and a colon are all parse errors on the server, and are refused here rather than sent.
+ * @param options.ttlMs how long a stored result stays fresh, in milliseconds.
+ * @param options.strict when true, the server validates each hit against live storage.
+ */
+export function cacheHint(name, options) {
+    validateCacheFamilyIdentifier(name);
+    let hint = `{cache=${name}`;
+    if (options?.ttlMs !== undefined) {
+        const ttl = options.ttlMs;
+        if (!Number.isInteger(ttl) || ttl <= 0 || ttl > 2_147_483_647) {
+            throw new RangeError('ttlMs must be a positive whole number of milliseconds below 2^31.');
+        }
+        hint += `, ttl=${String(ttl)}`;
+    }
+    if (options?.strict === true)
+        hint += ', strict';
+    return `${hint}}`;
+}
+/**
+ * The statement that drops every cached result in one family, for the current database.
+ *
+ * The family name is a quoted string here rather than a bare identifier, so it accepts more than
+ * `cacheHint` does — a name minted elsewhere, with a hyphen in it, can still be evicted.
+ */
+export function evictCacheStatement(name) {
+    validateBareName(name, MAX_CACHE_NAME_LENGTH, 'name');
+    return `EVICT CACHE '${name}'`;
+}
+/**
+ * Refuses a family name the server's hint grammar cannot read.
+ *
+ * The name goes into the statement as a bare identifier, with nothing around it to escape it, so a
+ * character outside the identifier set is a parse error rather than an oddly named family. Refusing
+ * it here reports the problem where the name was written, rather than as a syntax error naming a
+ * column position.
+ */
+function validateCacheFamilyIdentifier(name) {
+    validateBareName(name, MAX_CACHE_NAME_LENGTH, 'name');
+    if (!/^[\p{L}_][\p{L}\p{Nd}_]*$/u.test(name)) {
+        throw new TypeError(`The cache family '${name}' is not a bare identifier. A hint writes the name into the ` +
+            'statement unquoted, so it must start with a letter or an underscore and hold only ' +
+            'letters, digits, and underscores.');
+    }
+}
+/** The statement that drops every cached result for the current database. */
+export function evictAllCacheStatement() {
+    return 'EVICT CACHE ALL';
+}
+//# sourceMappingURL=cache.js.map

package/dist/cache.js.map

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