@platformatic/sqlite-js-stream 0.0.0-stage → 0.1.1

package/dist/store.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Store manages one or more Replicas (a litestream instance).
+ *
+ * MVP: a thin orchestration layer that opens replicas for database paths with
+ * their replica clients, syncs/snapshots them, and closes. Monitor loops,
+ * scheduling, and retention are future work.
+ */
+import type { Replica, RetentionOptions, ReplicaRunOptions } from './replica.js';
+import type { ReplicaClient } from './replica-client.js';
+/** Store coordinates multiple replicated databases. */
+export declare class Store {
+    private items;
+    /** OpenDB opens a replica for a database path and wires it to a client. */
+    openDB(path: string, client: ReplicaClient): Promise<Replica>;
+    /** Replicas returns all open replicas. */
+    replicas(): Replica[];
+    /** SyncAll syncs every database (local writes then replica upload). */
+    syncAll(): Promise<void>;
+    /** SnapshotAll writes & uploads level-9 snapshots for every database. */
+    snapshotAll(): Promise<void>;
+    /** CompactAll compacts pending LTX files for every database. */
+    compactAll(): Promise<void>;
+    /** EnforceRetentionAll prunes old snapshots/files for every database. */
+    enforceRetentionAll(options?: RetentionOptions): Promise<void>;
+    /**
+     * Run starts each replica's continuous sync/compaction/retention loop and
+     * resolves once `options.signal` is aborted. Pass per-replica intervals and a
+     * retention policy via {@link ReplicaRunOptions}.
+     */
+    run(options?: ReplicaRunOptions): Promise<void>;
+    /** Close releases all replicas' internal connections. */
+    close(): void;
+}
+//# sourceMappingURL=store.d.ts.map

package/dist/store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../src/store.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAEjF,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEzD,uDAAuD;AACvD,qBAAa,KAAK;IAChB,OAAO,CAAC,KAAK,CAAiB;IAE9B,2EAA2E;IACrE,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,aAAa,GAAG,OAAO,CAAC,OAAO,CAAC;IAMnE,0CAA0C;IAC1C,QAAQ,IAAI,OAAO,EAAE;IAIrB,uEAAuE;IACjE,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAM9B,yEAAyE;IACnE,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC;IAMlC,gEAAgE;IAC1D,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAMjC,yEAAyE;IACnE,mBAAmB,CAAC,OAAO,GAAE,gBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC;IAMxE;;;;OAIG;IACG,GAAG,CAAC,OAAO,GAAE,iBAAsB,GAAG,OAAO,CAAC,IAAI,CAAC;IAIzD,yDAAyD;IACzD,KAAK,IAAI,IAAI;CAId"}

package/dist/store.js

@@ -0,0 +1,60 @@
+/**
+ * Store manages one or more Replicas (a litestream instance).
+ *
+ * MVP: a thin orchestration layer that opens replicas for database paths with
+ * their replica clients, syncs/snapshots them, and closes. Monitor loops,
+ * scheduling, and retention are future work.
+ */
+import { Replica as ReplicaClass } from "./replica.js";
+/** Store coordinates multiple replicated databases. */
+export class Store {
+    items = [];
+    /** OpenDB opens a replica for a database path and wires it to a client. */
+    async openDB(path, client) {
+        const replica = new ReplicaClass(path, client);
+        this.items.push(replica);
+        return replica;
+    }
+    /** Replicas returns all open replicas. */
+    replicas() {
+        return [...this.items];
+    }
+    /** SyncAll syncs every database (local writes then replica upload). */
+    async syncAll() {
+        for (const replica of this.items) {
+            await replica.sync();
+        }
+    }
+    /** SnapshotAll writes & uploads level-9 snapshots for every database. */
+    async snapshotAll() {
+        for (const replica of this.items) {
+            await replica.snapshot();
+        }
+    }
+    /** CompactAll compacts pending LTX files for every database. */
+    async compactAll() {
+        for (const replica of this.items) {
+            await replica.compact();
+        }
+    }
+    /** EnforceRetentionAll prunes old snapshots/files for every database. */
+    async enforceRetentionAll(options = {}) {
+        for (const replica of this.items) {
+            await replica.enforceRetention(options);
+        }
+    }
+    /**
+     * Run starts each replica's continuous sync/compaction/retention loop and
+     * resolves once `options.signal` is aborted. Pass per-replica intervals and a
+     * retention policy via {@link ReplicaRunOptions}.
+     */
+    async run(options = {}) {
+        await Promise.all(this.items.map((replica) => replica.run(options)));
+    }
+    /** Close releases all replicas' internal connections. */
+    close() {
+        for (const replica of this.items)
+            replica.close();
+        this.items = [];
+    }
+}

package/dist/util/fs.d.ts

@@ -0,0 +1,28 @@
+/** File-system helpers for atomic writes and directory fsync. */
+import { type FileHandle } from 'node:fs/promises';
+import type { ByteSink } from '../ltx/sink.js';
+/** Ensures a directory (and parents) exists; no-op if already present. */
+export declare function mkdirAll(path: string): Promise<void>;
+/** Fsyncs a directory so a preceding rename within it is durable. */
+export declare function fsyncDir(path: string): Promise<void>;
+/** Returns the parent directory of a path (portable). */
+export declare function parentDir(path: string): string;
+/**
+ * A file-backed {@link ByteSink}. It batches bytes into fixed-size blocks and
+ * writes them synchronously, so the LTX encoder can stream a large file to disk
+ * without buffering the whole file (or the whole database) in memory.
+ */
+export declare class FileSink implements ByteSink {
+    private fh;
+    private buf;
+    private pos;
+    private filePos;
+    constructor(fh: FileHandle, chunkSize?: number);
+    write(bytes: Uint8Array): void;
+    /** Returns the number of bytes written so far. */
+    get length(): number;
+    private flushSync;
+    /** Flushes any remaining buffered bytes and fsyncs the file. */
+    flush(): Promise<void>;
+}
+//# sourceMappingURL=fs.d.ts.map

package/dist/util/fs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fs.d.ts","sourceRoot":"","sources":["../../src/util/fs.ts"],"names":[],"mappings":"AAAA,iEAAiE;AAGjE,OAAO,EAAe,KAAK,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAEhE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAE/C,0EAA0E;AAC1E,wBAAsB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAE1D;AAED,qEAAqE;AACrE,wBAAsB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAO1D;AAED,yDAAyD;AACzD,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE9C;AAED;;;;GAIG;AACH,qBAAa,QAAS,YAAW,QAAQ;IACvC,OAAO,CAAC,EAAE,CAAa;IACvB,OAAO,CAAC,GAAG,CAAa;IACxB,OAAO,CAAC,GAAG,CAAK;IAChB,OAAO,CAAC,OAAO,CAAK;gBAER,EAAE,EAAE,UAAU,EAAE,SAAS,SAAa;IAKlD,KAAK,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI;IAW9B,kDAAkD;IAClD,IAAI,MAAM,IAAI,MAAM,CAEnB;IAED,OAAO,CAAC,SAAS;IAOjB,gEAAgE;IAC1D,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAI7B"}

package/dist/util/fs.js

@@ -0,0 +1,73 @@
+/** File-system helpers for atomic writes and directory fsync. */
+import { writeSync } from 'node:fs';
+import { mkdir, open } from 'node:fs/promises';
+import { dirname } from 'node:path';
+/** Ensures a directory (and parents) exists; no-op if already present. */
+export async function mkdirAll(path) {
+    await mkdir(path, { recursive: true });
+}
+/** Fsyncs a directory so a preceding rename within it is durable. */
+export async function fsyncDir(path) {
+    const handle = await open(path, 'r');
+    try {
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+}
+/** Returns the parent directory of a path (portable). */
+export function parentDir(path) {
+    return dirname(path);
+}
+/**
+ * A file-backed {@link ByteSink}. It batches bytes into fixed-size blocks and
+ * writes them synchronously, so the LTX encoder can stream a large file to disk
+ * without buffering the whole file (or the whole database) in memory.
+ */
+export class FileSink {
+    fh;
+    buf;
+    pos = 0;
+    filePos = 0;
+    constructor(fh, chunkSize = 256 * 1024) {
+        this.fh = fh;
+        this.buf = new Uint8Array(chunkSize);
+    }
+    write(bytes) {
+        let o = 0;
+        while (o < bytes.length) {
+            if (this.pos === this.buf.length)
+                this.flushSync();
+            const take = Math.min(this.buf.length - this.pos, bytes.length - o);
+            this.buf.set(bytes.subarray(o, o + take), this.pos);
+            this.pos += take;
+            o += take;
+        }
+    }
+    /** Returns the number of bytes written so far. */
+    get length() {
+        return this.filePos + this.pos;
+    }
+    flushSync() {
+        if (this.pos === 0)
+            return;
+        writeAllSync(this.fh, this.buf, this.pos, this.filePos);
+        this.filePos += this.pos;
+        this.pos = 0;
+    }
+    /** Flushes any remaining buffered bytes and fsyncs the file. */
+    async flush() {
+        this.flushSync();
+        await this.fh.sync();
+    }
+}
+/** Writes all of `buf[0..len)` to `handle`'s fd starting at `position`. */
+function writeAllSync(handle, buf, len, position) {
+    const fd = handle.fd;
+    let offset = 0;
+    while (offset < len) {
+        const written = writeSync(fd, buf, offset, len - offset, position + offset);
+        offset += written;
+    }
+}

package/dist/util/logger.d.ts

@@ -0,0 +1,10 @@
+/** Minimal structured logger interface (stand-in for Go's slog.Logger). */
+export interface Logger {
+    debug(msg: string, ...args: unknown[]): void;
+    info(msg: string, ...args: unknown[]): void;
+    warn(msg: string, ...args: unknown[]): void;
+    error(msg: string, ...args: unknown[]): void;
+}
+/** A no-op logger used when none is provided. */
+export declare const noopLogger: Logger;
+//# sourceMappingURL=logger.d.ts.map

package/dist/util/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/util/logger.ts"],"names":[],"mappings":"AAAA,2EAA2E;AAC3E,MAAM,WAAW,MAAM;IACrB,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;IAC7C,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;IAC5C,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;IAC5C,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;CAC9C;AAED,iDAAiD;AACjD,eAAO,MAAM,UAAU,EAAE,MAKxB,CAAC"}

package/dist/util/logger.js

@@ -0,0 +1,7 @@
+/** A no-op logger used when none is provided. */
+export const noopLogger = {
+    debug() { },
+    info() { },
+    warn() { },
+    error() { },
+};

package/dist/util/stream.d.ts

@@ -0,0 +1,11 @@
+/** Stream helpers for consuming/capturing LTX byte streams. */
+/** Concatenates an array of byte chunks into a single Uint8Array. */
+export declare function concatBytes(chunks: readonly Uint8Array[]): Uint8Array;
+/**
+ * Reads an entire async iterable of byte chunks into a single Uint8Array.
+ * String chunks are encoded as UTF-8.
+ */
+export declare function readAll(stream: AsyncIterable<Uint8Array | string> | {
+    [Symbol.asyncIterator](): AsyncIterator<Uint8Array | string>;
+}): Promise<Uint8Array>;
+//# sourceMappingURL=stream.d.ts.map

package/dist/util/stream.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream.d.ts","sourceRoot":"","sources":["../../src/util/stream.ts"],"names":[],"mappings":"AAAA,+DAA+D;AAE/D,qEAAqE;AACrE,wBAAgB,WAAW,CAAC,MAAM,EAAE,SAAS,UAAU,EAAE,GAAG,UAAU,CAUrE;AAED;;;GAGG;AACH,wBAAsB,OAAO,CAC3B,MAAM,EAAE,aAAa,CAAC,UAAU,GAAG,MAAM,CAAC,GAAG;IAAE,CAAC,MAAM,CAAC,aAAa,CAAC,IAAI,aAAa,CAAC,UAAU,GAAG,MAAM,CAAC,CAAA;CAAE,GAC5G,OAAO,CAAC,UAAU,CAAC,CAMrB"}

package/dist/util/stream.js

@@ -0,0 +1,25 @@
+/** Stream helpers for consuming/capturing LTX byte streams. */
+/** Concatenates an array of byte chunks into a single Uint8Array. */
+export function concatBytes(chunks) {
+    let total = 0;
+    for (const c of chunks)
+        total += c.length;
+    const out = new Uint8Array(total);
+    let o = 0;
+    for (const c of chunks) {
+        out.set(c, o);
+        o += c.length;
+    }
+    return out;
+}
+/**
+ * Reads an entire async iterable of byte chunks into a single Uint8Array.
+ * String chunks are encoded as UTF-8.
+ */
+export async function readAll(stream) {
+    const chunks = [];
+    for await (const chunk of stream) {
+        chunks.push(typeof chunk === 'string' ? new TextEncoder().encode(chunk) : Uint8Array.from(chunk));
+    }
+    return concatBytes(chunks);
+}

package/dist/wal/checksum.d.ts

@@ -0,0 +1,17 @@
+/**
+ * SQLite WAL checksum.
+ *
+ * Matches litestream's `WALChecksum` and SQLite's wal-checksum algorithm.
+ * The byte order is chosen from the WAL magic: 0x377f0682 => little-endian,
+ * 0x377f0683 => big-endian. The checksum runs over 8-byte units:
+ *   s0 += u32[a] + s1 ; s1 += u32[a+4] + s0
+ */
+export type ByteOrder = 'le' | 'be';
+/** Reads a u32 from `buf` at `off` using the given byte order. */
+export declare function readWalU32(bo: ByteOrder, buf: Uint8Array, off: number): number;
+/**
+ * walChecksum computes a running SQLite WAL checksum over a byte slice whose
+ * length is a multiple of 8. Returns the updated (s0, s1) pair.
+ */
+export declare function walChecksum(bo: ByteOrder, s0: number, s1: number, b: Uint8Array): [number, number];
+//# sourceMappingURL=checksum.d.ts.map

package/dist/wal/checksum.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"checksum.d.ts","sourceRoot":"","sources":["../../src/wal/checksum.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAKH,MAAM,MAAM,SAAS,GAAG,IAAI,GAAG,IAAI,CAAC;AAEpC,kEAAkE;AAClE,wBAAgB,UAAU,CAAC,EAAE,EAAE,SAAS,EAAE,GAAG,EAAE,UAAU,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAG9E;AAED;;;GAGG;AACH,wBAAgB,WAAW,CACzB,EAAE,EAAE,SAAS,EACb,EAAE,EAAE,MAAM,EACV,EAAE,EAAE,MAAM,EACV,CAAC,EAAE,UAAU,GACZ,CAAC,MAAM,EAAE,MAAM,CAAC,CASlB"}

package/dist/wal/checksum.js

@@ -0,0 +1,30 @@
+/**
+ * SQLite WAL checksum.
+ *
+ * Matches litestream's `WALChecksum` and SQLite's wal-checksum algorithm.
+ * The byte order is chosen from the WAL magic: 0x377f0682 => little-endian,
+ * 0x377f0683 => big-endian. The checksum runs over 8-byte units:
+ *   s0 += u32[a] + s1 ; s1 += u32[a+4] + s0
+ */
+import { readU32BE, readU32LE } from "../ltx/bytes.js";
+import { WALFormatError } from "../errors.js";
+/** Reads a u32 from `buf` at `off` using the given byte order. */
+export function readWalU32(bo, buf, off) {
+    if (bo === 'le')
+        return readU32LE(buf, off);
+    return readU32BE(buf, off);
+}
+/**
+ * walChecksum computes a running SQLite WAL checksum over a byte slice whose
+ * length is a multiple of 8. Returns the updated (s0, s1) pair.
+ */
+export function walChecksum(bo, s0, s1, b) {
+    if (b.length % 8 !== 0) {
+        throw new WALFormatError('misaligned checksum byte slice');
+    }
+    for (let i = 0; i < b.length; i += 8) {
+        s0 = (s0 + readWalU32(bo, b, i) + s1) >>> 0;
+        s1 = (s1 + readWalU32(bo, b, i + 4) + s0) >>> 0;
+    }
+    return [s0, s1];
+}

package/dist/wal/constants.d.ts

@@ -0,0 +1,8 @@
+/** SQLite WAL (Write-Ahead Log) file constants. */
+export declare const WALHeaderSize = 32;
+export declare const WALFrameHeaderSize = 24;
+/** WAL magic values (always read big-endian; determines checksum byte order). */
+export declare const WALMagicLE = 931071618;
+export declare const WALMagicBE = 931071619;
+export declare const WALVersion = 3007000;
+//# sourceMappingURL=constants.d.ts.map

package/dist/wal/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../src/wal/constants.ts"],"names":[],"mappings":"AAAA,mDAAmD;AAEnD,eAAO,MAAM,aAAa,KAAK,CAAC;AAChC,eAAO,MAAM,kBAAkB,KAAK,CAAC;AAErC,iFAAiF;AACjF,eAAO,MAAM,UAAU,YAAa,CAAC;AACrC,eAAO,MAAM,UAAU,YAAa,CAAC;AAErC,eAAO,MAAM,UAAU,UAAU,CAAC"}

package/dist/wal/constants.js

@@ -0,0 +1,7 @@
+/** SQLite WAL (Write-Ahead Log) file constants. */
+export const WALHeaderSize = 32;
+export const WALFrameHeaderSize = 24;
+/** WAL magic values (always read big-endian; determines checksum byte order). */
+export const WALMagicLE = 0x377f0682; // checksums are computed little-endian
+export const WALMagicBE = 0x377f0683; // checksums are computed big-endian
+export const WALVersion = 3007000;

package/dist/wal/index.d.ts

@@ -0,0 +1,5 @@
+/** SQLite WAL module — public surface for reading WAL files. */
+export * from './constants.js';
+export * from './checksum.js';
+export * from './reader.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/wal/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/wal/index.ts"],"names":[],"mappings":"AAAA,gEAAgE;AAEhE,cAAc,gBAAgB,CAAC;AAC/B,cAAc,eAAe,CAAC;AAC9B,cAAc,aAAa,CAAC"}

package/dist/wal/index.js

@@ -0,0 +1,4 @@
+/** SQLite WAL module — public surface for reading WAL files. */
+export * from "./constants.js";
+export * from "./checksum.js";
+export * from "./reader.js";

package/dist/wal/reader.d.ts

@@ -0,0 +1,61 @@
+/**
+ * WALReader parses a SQLite WAL file and verifies salt & checksum integrity
+ * while reading. It does not enforce transaction boundaries; the caller is
+ * responsible for handling uncommitted frames.
+ *
+ * Mirrors litestream's `WALReader` (wal_reader.go).
+ */
+/** Raised when the WAL ends, or when a salt/checksum mismatch is detected. */
+export declare class WALEOFError extends Error {
+}
+/** Raised when starting mid-WAL and the previous frame does not match. */
+export declare class PrevFrameMismatchError extends Error {
+    readonly cause: Error;
+    constructor(cause: Error);
+}
+export interface WALFrame {
+    pgno: number;
+    commit: number;
+}
+export interface WALPageMap {
+    /** Latest committed offset (file offset) for each page. */
+    pageIndex: Map<number, number>;
+    /** Offset just past the last read frame. */
+    maxOffset: number;
+    /** Final database size in pages (from the last commit frame). */
+    commit: number;
+    /** Whether the scan was bounded by maxBytes. */
+    limited: boolean;
+}
+/** WALReader reads and validates frames from an in-memory WAL byte buffer. */
+export declare class WALReader {
+    private data;
+    private bo;
+    private pageSizeVal;
+    private seqVal;
+    private salt1Value;
+    private salt2Value;
+    private chksum1;
+    private chksum2;
+    private frameN;
+    constructor(data: Uint8Array);
+    /** Creates a reader positioned at `offset`, loading salts from the caller. */
+    static withOffset(data: Uint8Array, offset: number, salt1: number, salt2: number): WALReader;
+    /** PageSize returns the page size from the header. */
+    pageSize(): number;
+    /** Seq returns the checkpoint sequence from the header. */
+    seq(): number;
+    /** Salt1 returns the header salt-1 value. */
+    salt1(): number;
+    /** Salt2 returns the header salt-2 value. */
+    salt2(): number;
+    /** Offset returns the file offset of the last read frame (0 if none). */
+    offset(): number;
+    /** ReadFrame reads the next frame, verifying salt & checksum. */
+    readFrame(data: Uint8Array): WALFrame;
+    /** PageMap scans committed frames and returns the latest page offsets. */
+    pageMap(maxBytes?: number): WALPageMap;
+    private readHeader;
+    private readFrameInternal;
+}
+//# sourceMappingURL=reader.d.ts.map

package/dist/wal/reader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reader.d.ts","sourceRoot":"","sources":["../../src/wal/reader.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAQH,8EAA8E;AAC9E,qBAAa,WAAY,SAAQ,KAAK;CAAG;AAEzC,0EAA0E;AAC1E,qBAAa,sBAAuB,SAAQ,KAAK;IAC/C,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;gBACV,KAAK,EAAE,KAAK;CAIzB;AAED,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,UAAU;IACzB,2DAA2D;IAC3D,SAAS,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B,4CAA4C;IAC5C,SAAS,EAAE,MAAM,CAAC;IAClB,iEAAiE;IACjE,MAAM,EAAE,MAAM,CAAC;IACf,gDAAgD;IAChD,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,8EAA8E;AAC9E,qBAAa,SAAS;IACpB,OAAO,CAAC,IAAI,CAAa;IACzB,OAAO,CAAC,EAAE,CAAa;IACvB,OAAO,CAAC,WAAW,CAAK;IACxB,OAAO,CAAC,MAAM,CAAK;IACnB,OAAO,CAAC,UAAU,CAAK;IACvB,OAAO,CAAC,UAAU,CAAK;IACvB,OAAO,CAAC,OAAO,CAAK;IACpB,OAAO,CAAC,OAAO,CAAK;IACpB,OAAO,CAAC,MAAM,CAAK;gBAEP,IAAI,EAAE,UAAU;IAK5B,8EAA8E;IAC9E,MAAM,CAAC,UAAU,CAAC,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,SAAS;IAiC5F,sDAAsD;IACtD,QAAQ,IAAI,MAAM;IAIlB,2DAA2D;IAC3D,GAAG,IAAI,MAAM;IAIb,6CAA6C;IAC7C,KAAK,IAAI,MAAM;IAIf,6CAA6C;IAC7C,KAAK,IAAI,MAAM;IAIf,yEAAyE;IACzE,MAAM,IAAI,MAAM;IAKhB,iEAAiE;IACjE,SAAS,CAAC,IAAI,EAAE,UAAU,GAAG,QAAQ;IAIrC,0EAA0E;IAC1E,OAAO,CAAC,QAAQ,SAAI,GAAG,UAAU;IAsDjC,OAAO,CAAC,UAAU;IA+BlB,OAAO,CAAC,iBAAiB;CAqD1B"}

package/dist/wal/reader.js

@@ -0,0 +1,207 @@
+/**
+ * WALReader parses a SQLite WAL file and verifies salt & checksum integrity
+ * while reading. It does not enforce transaction boundaries; the caller is
+ * responsible for handling uncommitted frames.
+ *
+ * Mirrors litestream's `WALReader` (wal_reader.go).
+ */
+import { WALFrameHeaderSize, WALHeaderSize, WALMagicBE, WALMagicLE, WALVersion } from "./constants.js";
+import { walChecksum } from "./checksum.js";
+import { readU32BE } from "../ltx/bytes.js";
+import { WALFormatError } from "../errors.js";
+/** Raised when the WAL ends, or when a salt/checksum mismatch is detected. */
+export class WALEOFError extends Error {
+}
+/** Raised when starting mid-WAL and the previous frame does not match. */
+export class PrevFrameMismatchError extends Error {
+    cause;
+    constructor(cause) {
+        super(`prev frame mismatch: ${cause.message}`);
+        this.cause = cause;
+    }
+}
+/** WALReader reads and validates frames from an in-memory WAL byte buffer. */
+export class WALReader {
+    data;
+    bo;
+    pageSizeVal = 0;
+    seqVal = 0;
+    salt1Value = 0;
+    salt2Value = 0;
+    chksum1 = 0;
+    chksum2 = 0;
+    frameN = 0;
+    constructor(data) {
+        this.data = data;
+        this.readHeader();
+    }
+    /** Creates a reader positioned at `offset`, loading salts from the caller. */
+    static withOffset(data, offset, salt1, salt2) {
+        if (offset <= WALHeaderSize) {
+            throw new WALFormatError(`offset (${offset}) must be greater than the wal header size (${WALHeaderSize})`);
+        }
+        const r = new WALReader(data);
+        // Load the salt from the caller; the beginning of the file may be gone.
+        r.salt1Value = salt1;
+        r.salt2Value = salt2;
+        // Ensure the offset is positioned on a frame start.
+        const frameSize = r.pageSizeVal + WALFrameHeaderSize;
+        if ((offset - WALHeaderSize) % frameSize !== 0) {
+            throw new WALFormatError(`unaligned wal offset ${offset} for page size ${r.pageSizeVal}`);
+        }
+        r.frameN = Math.floor((offset - WALHeaderSize) / frameSize);
+        // Read the previous page to load the checksum state.
+        r.frameN--;
+        try {
+            r.readFrameInternal(new Uint8Array(r.pageSizeVal), false);
+        }
+        catch (err) {
+            if (err instanceof WALEOFError) {
+                throw new PrevFrameMismatchError(err);
+            }
+            throw err;
+        }
+        return r;
+    }
+    /** PageSize returns the page size from the header. */
+    pageSize() {
+        return this.pageSizeVal;
+    }
+    /** Seq returns the checkpoint sequence from the header. */
+    seq() {
+        return this.seqVal;
+    }
+    /** Salt1 returns the header salt-1 value. */
+    salt1() {
+        return this.salt1Value;
+    }
+    /** Salt2 returns the header salt-2 value. */
+    salt2() {
+        return this.salt2Value;
+    }
+    /** Offset returns the file offset of the last read frame (0 if none). */
+    offset() {
+        if (this.frameN === 0)
+            return 0;
+        return WALHeaderSize + (this.frameN - 1) * (WALFrameHeaderSize + this.pageSizeVal);
+    }
+    /** ReadFrame reads the next frame, verifying salt & checksum. */
+    readFrame(data) {
+        return this.readFrameInternal(data, true);
+    }
+    /** PageMap scans committed frames and returns the latest page offsets. */
+    pageMap(maxBytes = 0) {
+        const m = new Map();
+        const txMap = new Map();
+        const data = new Uint8Array(this.pageSizeVal);
+        const frameSize = WALFrameHeaderSize + this.pageSizeVal;
+        const startOffset = WALHeaderSize + this.frameN * frameSize;
+        let commit = 0;
+        let limited = false;
+        for (;;) {
+            let frame;
+            try {
+                frame = this.readFrame(data);
+            }
+            catch (err) {
+                if (err instanceof WALEOFError)
+                    break;
+                throw err;
+            }
+            // Buffer the latest offset for each page in the current transaction.
+            const offset = this.offset();
+            txMap.set(frame.pgno, offset);
+            // On a commit record, flush pending pages into the full map.
+            if (frame.commit !== 0) {
+                for (const [pgno, off] of txMap)
+                    m.set(pgno, off);
+                txMap.clear();
+                commit = frame.commit;
+                if (maxBytes > 0 && this.offset() + frameSize - startOffset >= maxBytes) {
+                    limited = true;
+                    break;
+                }
+            }
+        }
+        // Drop pages beyond the final commit size (DB may have shrunk via VACUUM).
+        for (const pgno of [...m.keys()]) {
+            if (pgno > commit)
+                m.delete(pgno);
+        }
+        if (m.size === 0) {
+            return { pageIndex: m, maxOffset: 0, commit: 0, limited };
+        }
+        // Compute the highest frame offset and extend past its data.
+        let end = 0;
+        for (const offset of m.values()) {
+            if (end === 0 || offset > end)
+                end = offset;
+        }
+        end += frameSize;
+        return { pageIndex: m, maxOffset: end, commit, limited };
+    }
+    readHeader() {
+        if (this.data.length < WALHeaderSize) {
+            throw new WALEOFError();
+        }
+        const hdr = this.data.subarray(0, WALHeaderSize);
+        const magic = readU32BE(hdr, 0);
+        if (magic === WALMagicLE)
+            this.bo = 'le';
+        else if (magic === WALMagicBE)
+            this.bo = 'be';
+        else
+            throw new WALFormatError(`invalid wal header magic: ${magic.toString(16)}`);
+        const chksum1 = readU32BE(hdr, 24);
+        const chksum2 = readU32BE(hdr, 28);
+        const [v0, v1] = walChecksum(this.bo, 0, 0, hdr.subarray(0, 24));
+        if (v0 !== chksum1 || v1 !== chksum2) {
+            throw new WALEOFError();
+        }
+        const version = readU32BE(hdr, 4);
+        if (version !== WALVersion) {
+            throw new WALFormatError(`unsupported wal version: ${version}`);
+        }
+        this.pageSizeVal = readU32BE(hdr, 8);
+        this.seqVal = readU32BE(hdr, 12);
+        this.salt1Value = readU32BE(hdr, 16);
+        this.salt2Value = readU32BE(hdr, 20);
+        this.chksum1 = chksum1;
+        this.chksum2 = chksum2;
+    }
+    readFrameInternal(data, verifyChecksum) {
+        if (data.length !== this.pageSizeVal) {
+            throw new WALFormatError(`buffer size (${data.length}) must match page size (${this.pageSizeVal})`);
+        }
+        const frameSize = this.pageSizeVal + WALFrameHeaderSize;
+        const offset = WALHeaderSize + this.frameN * frameSize;
+        if (offset + frameSize > this.data.length) {
+            throw new WALEOFError();
+        }
+        const hdr = this.data.subarray(offset, offset + WALFrameHeaderSize);
+        const page = this.data.subarray(offset + WALFrameHeaderSize, offset + frameSize);
+        // Verify the frame salt matches the header salt.
+        const salt1 = readU32BE(hdr, 8);
+        const salt2 = readU32BE(hdr, 12);
+        if (this.salt1Value !== salt1 || this.salt2Value !== salt2) {
+            throw new WALEOFError();
+        }
+        const fchksum1 = readU32BE(hdr, 16);
+        const fchksum2 = readU32BE(hdr, 20);
+        if (verifyChecksum) {
+            [this.chksum1, this.chksum2] = walChecksum(this.bo, this.chksum1, this.chksum2, hdr.subarray(0, 8));
+            [this.chksum1, this.chksum2] = walChecksum(this.bo, this.chksum1, this.chksum2, page);
+            if (this.chksum1 !== fchksum1 || this.chksum2 !== fchksum2) {
+                throw new WALEOFError();
+            }
+        }
+        else {
+            this.chksum1 = fchksum1;
+            this.chksum2 = fchksum2;
+        }
+        const pgno = readU32BE(hdr, 0);
+        const commit = readU32BE(hdr, 4);
+        this.frameN++;
+        return { pgno, commit };
+    }
+}