@hyperdrive.bot/fleet-server 0.3.164 → 0.3.166

package/dist/server/server/state/state-db.d.ts

@@ -0,0 +1,263 @@
+import type { DatabaseSync, StatementSync } from "node:sqlite";
+import type { Logger } from "pino";
+import { LegacyManifest } from "./legacy-manifest.js";
+import { LegacyMirror } from "./legacy-mirror.js";
+import { type WorkerStatement } from "./state-worker.js";
+import { type DocTableName } from "./state-schema.js";
+export declare const STATE_DB_FILENAME = "state.sqlite";
+/** Kill switch: `PASEO_STATE_SQLITE=0` keeps every store on its legacy files. */
+export declare const STATE_SQLITE_ENV = "PASEO_STATE_SQLITE";
+/** Kill switch: `PASEO_STATE_FILE_MIRROR=0` stops writing the legacy files. */
+export declare const STATE_FILE_MIRROR_ENV = "PASEO_STATE_FILE_MIRROR";
+type DatabaseSyncCtor = new (path: string) => DatabaseSync;
+export interface DocRow {
+    scope: string;
+    id: string;
+    body: string;
+    rev: number;
+}
+/** A row including tombstones, for reconciliation. */
+export interface StoredRow {
+    scope: string;
+    id: string;
+    rev: number;
+    deletedAt: number | null;
+    body: string | null;
+}
+export interface ChangedRow {
+    scope: string;
+    id: string;
+    rev: number;
+    /** Epoch ms, set on a tombstone. */
+    deletedAt: number | null;
+    /** Null on a tombstone. */
+    body: string | null;
+}
+export interface ImportMarker {
+    status: "running" | "done";
+    cursor: string | null;
+    imported: number;
+    skipped: number;
+}
+export interface StateWriteStats {
+    transactions: number;
+    rows: number;
+    /** Most recent transaction durations in ms, newest last, capped. */
+    recentTxnMs: number[];
+    maxTxnMs: number;
+}
+/**
+ * The one handle on `state.sqlite`.
+ *
+ * Writes are queued and committed together in one transaction per turn of the
+ * event loop (`setImmediate`), so a burst of 50 agent updates is one commit, not
+ * 50. Reads on the hot path never come here: every store keeps its in-memory
+ * index and treats this file as its durable log. The only reads are at load, in
+ * explicit paged queries, and in `listChangedSince`.
+ */
+export declare class StateDb {
+    readonly dbPath: string;
+    readonly mirror: LegacyMirror;
+    readonly manifest: LegacyManifest;
+    private readonly db;
+    readonly logger: Logger;
+    private readonly statements;
+    private readonly docs;
+    private pending;
+    private waiters;
+    private flushScheduled;
+    private revCounter;
+    private closed;
+    private worker;
+    private consecutiveFailures;
+    private retryAttempts;
+    private retryStartedAt;
+    private retryTimer;
+    private readonly stats;
+    constructor(options: {
+        db: DatabaseSync;
+        dbPath: string;
+        logger: Logger;
+        mirror: LegacyMirror;
+    });
+    prepare(sql: string): StatementSync;
+    doc(name: DocTableName, options?: {
+        tombstones?: boolean;
+    }): DocTable;
+    /** Next value of the daemon-wide change sequence. Persisted with each commit. */
+    nextRev(): number;
+    get currentRev(): number;
+    /**
+     * The rev a mirror write reflects: the last rev already committed. Commits
+     * are synchronous, so every row the caller's in-memory state was built from
+     * has a rev at or below it. Deliberately no flush: flushing here would stamp
+     * the file with revs of writes queued after its content was captured, and a
+     * crash would then leave a lagging file the boot catch-up cannot see
+     * (re-review R1). Capture it where the content is captured.
+     */
+    mirrorRev(): number;
+    /**
+     * Shutdown has begun (SIGTERM, SIGINT, the updater stopping the daemon):
+     * commit the queue and start every pending legacy file write now, instead of
+     * after the rest of the daemon has wound down.
+     */
+    beginShutdown(): Promise<void>;
+    /**
+     * Queue a write for the next batched commit. The promise settles when that
+     * commit lands. When a batch fails, its ops are retried one transaction each,
+     * so only the op that actually fails rejects.
+     */
+    enqueue(op: () => void): Promise<void>;
+    /** Commit everything queued, now. Safe to call with nothing queued. */
+    flushSync(): void;
+    private commitPending;
+    /**
+     * Put a batch whose transaction failed back at the head of the queue and
+     * retry it after a backoff. Once the batch has been failing for
+     * `COMMIT_RETRY_BUDGET_MS` it rejects, so a writer that holds the lock for good surfaces as
+     * failed writes and `failedCommits`, not as a queue that grows forever.
+     */
+    private requeue;
+    private clearRetry;
+    /** Commits that failed in a row; a health signal once it keeps climbing. */
+    get failedCommits(): number;
+    private recordFailure;
+    /**
+     * Move WAL checkpoints and bulk writes to a worker thread (see
+     * `StateWorker`). If the worker cannot start, SQLite keeps checkpointing
+     * inside commits and bulk writes run here, as usual.
+     */
+    startWorker(): void;
+    /** See `StateWorker.pause`. */
+    pauseCheckpoints(): void;
+    resumeCheckpoints(): void;
+    /**
+     * Commit a bulk batch as one transaction, off the event loop when the worker
+     * is up. Only for work nothing else is writing concurrently (the import runs
+     * before any store exists); the rev counter is persisted with the batch.
+     */
+    commitBatch(statements: WorkerStatement[]): Promise<void>;
+    metaStatement(key: string, value: string): WorkerStatement;
+    /** Run `fn` in one IMMEDIATE transaction, rolling back on throw. */
+    transaction<T>(fn: () => T): T;
+    getMeta(key: string): string | null;
+    setMeta(key: string, value: string): void;
+    /** Every meta entry whose key starts with `prefix`, keyed by the rest of the key. */
+    getMetaWithPrefix(prefix: string): Map<string, string>;
+    deleteMeta(key: string): void;
+    /** `setMeta` for use inside an open transaction. */
+    setMetaInTransaction(key: string, value: string): void;
+    getImportMarker(store: string): ImportMarker | null;
+    /** Write an import marker. Call inside `transaction` to commit it with the rows it covers. */
+    putImportMarker(store: string, marker: ImportMarker): void;
+    /** `putImportMarker` as a statement for `commitBatch`, to commit with its rows. */
+    importMarkerStatement(store: string, marker: ImportMarker): WorkerStatement;
+    get writeStats(): StateWriteStats;
+    private recordTxn;
+    /** Flush queued writes and the legacy mirror, then close the handle. */
+    close(): Promise<void>;
+    /**
+     * Close without flushing the mirror or the queue, and drop pending mirror
+     * writes. Tests use it to simulate a kill -9.
+     */
+    closeImmediately(): void;
+}
+/** A keyed-document table. See `state-schema.ts`. */
+export declare class DocTable {
+    private readonly state;
+    readonly name: DocTableName;
+    private readonly tombstones;
+    constructor(state: StateDb, name: DocTableName, tombstones: boolean);
+    /** Serialize now (so later mutation of `value` cannot leak in) and queue the upsert. */
+    put(scope: string, id: string, value: unknown, ord?: number): Promise<void>;
+    putRaw(scope: string, id: string, body: string, ord?: number): Promise<void>;
+    /** `put`, resolving with the rev the row was committed at. */
+    putWithRev(scope: string, id: string, value: unknown): Promise<number>;
+    /** Upsert inside the caller's transaction. */
+    putNow(scope: string, id: string, body: string, ord?: number): void;
+    /** The upsert as a statement for `StateDb.commitBatch`; takes its rev now. */
+    putStatement(scope: string, id: string, body: string, ord?: number): WorkerStatement;
+    remove(scope: string, id: string): Promise<void>;
+    removeNow(scope: string, id: string): void;
+    /** The removal (a tombstone on a tombstoned table) as a batch statement; takes its rev now. */
+    removeStatement(scope: string, id: string): WorkerStatement;
+    /**
+     * Rows, tombstones included, optionally narrowed to one scope and one id. No
+     * flush: for reconciliation, which runs before any store writes.
+     */
+    storedRows(filter?: {
+        scope?: string;
+        id?: string;
+    }): StoredRow[];
+    /** Drop every row of a scope (a deleted schedule's runs). Never tombstoned. */
+    removeScope(scope: string): Promise<void>;
+    /** Live rows, ordered by scope, ord, id. Flushes queued writes first. */
+    loadAll(scope?: string): DocRow[];
+    /** `loadAll` for use inside an open transaction (no flush). */
+    loadAllInTransaction(scope?: string): DocRow[];
+    get(scope: string, id: string): string | null;
+    /** `get` for use inside an open transaction (no flush). */
+    getInTransaction(scope: string, id: string): string | null;
+    /**
+     * Drop tombstones deleted before `before`, except ids in `keep`. Returns how
+     * many went.
+     */
+    purgeTombstones(before: number, keep?: ReadonlySet<string>): number;
+    /** Highest rev in the table, tombstones included (0 when empty). */
+    maxRev(): number;
+    count(): number;
+    /**
+     * Rows (live and tombstoned) whose rev is greater than `rev`, oldest change
+     * first. Internal for now; the delta protocol exposes it in a later release.
+     */
+    listChangedSince(rev: number, limit?: number): ChangedRow[];
+}
+export declare class ScopeSync {
+    private readonly table;
+    private readonly written;
+    constructor(table: DocTable);
+    /** Seed from rows already in the table, so the first sync does not rewrite them. */
+    seed(rows: DocRow[]): void;
+    /** Queue the diff inside the next batch. `prune` removes rows no longer listed. */
+    sync(scope: string, items: ReadonlyArray<{
+        id: string;
+        value: unknown;
+    }>, options: {
+        prune: boolean;
+    }): Promise<void>;
+    /**
+     * Drop every tracked scope not in `live` (a deleted room's messages, a
+     * deleted loop's logs), so children never outlive their parent.
+     */
+    dropScopesExcept(live: ReadonlySet<string>): Promise<void>;
+    dropScope(scope: string): Promise<void>;
+    private scopeMap;
+}
+export interface OpenStateDbOptions {
+    paseoHome: string;
+    logger: Logger;
+    env?: NodeJS.ProcessEnv;
+    /** Test seam: simulate a runtime without `node:sqlite`. */
+    loadCtor?: () => DatabaseSyncCtor;
+    mirrorDebounceMs?: number;
+    /** Default true: checkpoints and bulk import writes on a worker thread. */
+    worker?: boolean;
+}
+/**
+ * Open and probe `state.sqlite`, or return null so every store stays on its
+ * legacy files. Never throws: a runtime without `node:sqlite` (Node 20, Node
+ * 22 before 22.13 without the flag), a locked or corrupt file, or a schema
+ * newer than this build all degrade to the file stores with one warning.
+ */
+export declare function openStateDb(options: OpenStateDbOptions): StateDb | null;
+/**
+ * Stores constructed deep inside other services (schedules, fleet decisions,
+ * push tokens, extension storage) find the daemon's handle by PASEO_HOME
+ * instead of having it threaded through every constructor in between. Nothing
+ * attached means file stores, which is also what every unit test gets.
+ */
+export declare function attachStateDb(paseoHome: string, stateDb: StateDb): void;
+export declare function detachStateDb(paseoHome: string): void;
+export declare function stateDbFor(paseoHome: string): StateDb | null;
+export {};
+//# sourceMappingURL=state-db.d.ts.map