@rocicorp/zero 0.0.0-202410031711

package/out/zero-cache/src/db/migration.js

@@ -0,0 +1,139 @@
+import { assert } from '../../../shared/src/asserts.js';
+import { randInt } from '../../../shared/src/rand.js';
+import * as v from '../../../shared/src/valita.js';
+/**
+ * Ensures that the schema is compatible with the current code, updating and
+ * migrating the schema if necessary.
+ */
+export async function runSchemaMigrations(log, debugName, schemaName, db, versionMigrationMap) {
+    log = log.withContext('initSchema', randInt(0, Number.MAX_SAFE_INTEGER).toString(36));
+    try {
+        const versionMigrations = sorted(versionMigrationMap);
+        if (versionMigrations.length === 0) {
+            log.info?.(`No versions/migrations to manage.`);
+            return;
+        }
+        const codeSchemaVersion = versionMigrations[versionMigrations.length - 1][0];
+        log.info?.(`Checking schema for compatibility with ${debugName} at schema v${codeSchemaVersion}`);
+        let meta = await db.begin(async (tx) => {
+            const meta = await getSchemaVersions(tx, schemaName);
+            if (codeSchemaVersion < meta.minSafeRollbackVersion) {
+                throw new Error(`Cannot run ${debugName} at schema v${codeSchemaVersion} because rollback limit is v${meta.minSafeRollbackVersion}`);
+            }
+            if (meta.version > codeSchemaVersion) {
+                log.info?.(`Schema is at v${meta.version}. Resetting to v${codeSchemaVersion}`);
+                return setSchemaVersion(tx, schemaName, meta, codeSchemaVersion);
+            }
+            return meta;
+        });
+        if (meta.version < codeSchemaVersion) {
+            for (const [dest, migration] of versionMigrations) {
+                if (meta.version < dest) {
+                    log.info?.(`Migrating schema from v${meta.version} to v${dest}`);
+                    void log.flush(); // Flush logs before each migration to help debug crash-y migrations.
+                    // Run the optional PreMigration step before starting the transaction.
+                    if ('pre' in migration) {
+                        await migration.pre(log, db);
+                    }
+                    meta = await db.begin(async (tx) => {
+                        // Fetch meta from within the transaction to make the migration atomic.
+                        let meta = await getSchemaVersions(tx, schemaName);
+                        if (meta.version < dest) {
+                            meta = await migrateSchemaVersion(log, schemaName, tx, meta, dest, migration);
+                            assert(meta.version === dest);
+                        }
+                        return meta;
+                    });
+                }
+            }
+        }
+        assert(meta.version === codeSchemaVersion);
+        log.info?.(`Running ${debugName} at schema v${codeSchemaVersion}`);
+    }
+    catch (e) {
+        log.error?.('Error in ensureSchemaMigrated', e);
+        throw e;
+    }
+    finally {
+        void log.flush(); // Flush the logs but do not block server progress on it.
+    }
+}
+function sorted(versionMigrationMap) {
+    const versionMigrations = [];
+    for (const [v, m] of Object.entries(versionMigrationMap)) {
+        versionMigrations.push([Number(v), m]);
+    }
+    return versionMigrations.sort(([a], [b]) => a - b);
+}
+// Exposed for tests.
+export const schemaVersions = v.object({
+    version: v.number(),
+    maxVersion: v.number(),
+    minSafeRollbackVersion: v.number(),
+});
+// Exposed for tests
+export async function getSchemaVersions(sql, schemaName) {
+    // Note: The `schema_meta.lock` column transparently ensures that at most one row exists.
+    const results = await sql `
+    CREATE SCHEMA IF NOT EXISTS ${sql(schemaName)};
+    CREATE TABLE IF NOT EXISTS ${sql(schemaName)}."SchemaVersions" (
+      version int NOT NULL,
+      "maxVersion" int NOT NULL,
+      "minSafeRollbackVersion" int NOT NULL,
+
+      lock char(1) NOT NULL CONSTRAINT DF_schema_meta_lock DEFAULT 'v',
+      CONSTRAINT PK_schema_meta_lock PRIMARY KEY (lock),
+      CONSTRAINT CK_schema_meta_lock CHECK (lock='v')
+    );
+    SELECT version, "maxVersion", "minSafeRollbackVersion" FROM ${sql(schemaName)}."SchemaVersions";
+  `.simple();
+    const rows = results[1];
+    if (rows.length === 0) {
+        return { version: 0, maxVersion: 0, minSafeRollbackVersion: 0 };
+    }
+    return v.parse(rows[0], schemaVersions);
+}
+async function setSchemaVersion(sql, schemaName, prev, newVersion) {
+    assert(newVersion > 0);
+    const meta = {
+        ...prev,
+        version: newVersion,
+        maxVersion: Math.max(newVersion, prev.maxVersion),
+    };
+    if (prev.version === 0) {
+        await sql `INSERT INTO ${sql(schemaName)}."SchemaVersions" ${sql(meta)}`;
+    }
+    else {
+        await sql `UPDATE ${sql(schemaName)}."SchemaVersions" set ${sql(meta)}`;
+    }
+    return meta;
+}
+async function migrateSchemaVersion(log, schemaName, tx, meta, destinationVersion, migration) {
+    if ('run' in migration) {
+        await migration.run(log, tx);
+    }
+    else {
+        meta = ensureRollbackLimit(migration.minSafeRollbackVersion, log, meta);
+    }
+    return setSchemaVersion(tx, schemaName, meta, destinationVersion);
+}
+/**
+ * Bumps the rollback limit [[toAtLeast]] the specified version.
+ * Leaves the rollback limit unchanged if it is equal or greater.
+ */
+function ensureRollbackLimit(toAtLeast, log, meta) {
+    // Sanity check to maintain the invariant that running code is never
+    // earlier than the rollback limit.
+    assert(toAtLeast <= meta.version + 1);
+    if (meta.minSafeRollbackVersion >= toAtLeast) {
+        // The rollback limit must never move backwards.
+        log.debug?.(`rollback limit is already at ${meta.minSafeRollbackVersion}, don't need to bump to ${toAtLeast}`);
+        return meta;
+    }
+    log.info?.(`bumping rollback limit from ${meta.minSafeRollbackVersion} to ${toAtLeast}`);
+    return {
+        ...meta,
+        minSafeRollbackVersion: toAtLeast,
+    };
+}
+//# sourceMappingURL=migration.js.map

package/out/zero-cache/src/db/migration.js.map

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

package/out/zero-cache/src/db/statements.d.ts

@@ -0,0 +1,31 @@
+import type { RunResult } from 'better-sqlite3';
+import { Database } from '../../../zqlite/src/db.js';
+import { StatementCache } from '../../../zqlite/src/internal/statement-cache.js';
+/**
+ * A stateless wrapper around a {@link StatementCache} that facilitates single-line
+ * `printf()` style invocations of cached prepared statement operations.
+ */
+export declare class StatementRunner {
+    readonly db: Database;
+    readonly statementCache: StatementCache;
+    constructor(db: Database);
+    /**
+     * Prepares a statement (or retrieves it from the cache) and runs it
+     * with the given args.
+     */
+    run(sql: string, ...args: unknown[]): RunResult;
+    /**
+     * Prepares a statement (or retrieves it from the cache) and returns
+     * the first result.
+     */
+    get(sql: string, ...args: unknown[]): any;
+    /**
+     * Prepares a statement (or retrieves it from the cache) and returns
+     * all of its results.
+     */
+    all(sql: string, ...args: unknown[]): any[];
+    beginConcurrent(): RunResult;
+    commit(): RunResult;
+    rollback(): RunResult;
+}
+//# sourceMappingURL=statements.d.ts.map

package/out/zero-cache/src/db/statements.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"statements.d.ts","sourceRoot":"","sources":["../../../../../zero-cache/src/db/statements.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAC,QAAQ,EAAC,MAAM,kBAAkB,CAAC;AAC1C,OAAO,EAAC,cAAc,EAAC,MAAM,wCAAwC,CAAC;AAEtE;;;GAGG;AACH,qBAAa,eAAe;IAC1B,QAAQ,CAAC,EAAE,EAAE,QAAQ,CAAC;IACtB,QAAQ,CAAC,cAAc,EAAE,cAAc,CAAC;gBAE5B,EAAE,EAAE,QAAQ;IAKxB;;;OAGG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,SAAS;IAM/C;;;OAGG;IAEH,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,GAAG;IAMzC;;;OAGG;IAEH,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,GAAG,EAAE;IAO3C,eAAe,IAAI,SAAS;IAI5B,MAAM,IAAI,SAAS;IAInB,QAAQ,IAAI,SAAS;CAGtB"}

package/out/zero-cache/src/db/statements.js

@@ -0,0 +1,48 @@
+import { Database } from '../../../zqlite/src/db.js';
+import { StatementCache } from '../../../zqlite/src/internal/statement-cache.js';
+/**
+ * A stateless wrapper around a {@link StatementCache} that facilitates single-line
+ * `printf()` style invocations of cached prepared statement operations.
+ */
+export class StatementRunner {
+    db;
+    statementCache;
+    constructor(db) {
+        this.db = db;
+        this.statementCache = new StatementCache(db);
+    }
+    /**
+     * Prepares a statement (or retrieves it from the cache) and runs it
+     * with the given args.
+     */
+    run(sql, ...args) {
+        return this.statementCache.use(sql, cached => cached.statement.run(...args));
+    }
+    /**
+     * Prepares a statement (or retrieves it from the cache) and returns
+     * the first result.
+     */
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    get(sql, ...args) {
+        return this.statementCache.use(sql, cached => cached.statement.get(...args));
+    }
+    /**
+     * Prepares a statement (or retrieves it from the cache) and returns
+     * all of its results.
+     */
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    all(sql, ...args) {
+        return this.statementCache.use(sql, cached => cached.statement.all(...args));
+    }
+    // Syntactic sugar methods
+    beginConcurrent() {
+        return this.run('BEGIN CONCURRENT');
+    }
+    commit() {
+        return this.run('COMMIT');
+    }
+    rollback() {
+        return this.run('ROLLBACK');
+    }
+}
+//# sourceMappingURL=statements.js.map

package/out/zero-cache/src/db/statements.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"statements.js","sourceRoot":"","sources":["../../../../../zero-cache/src/db/statements.ts"],"names":[],"mappings":"AACA,OAAO,EAAC,QAAQ,EAAC,MAAM,kBAAkB,CAAC;AAC1C,OAAO,EAAC,cAAc,EAAC,MAAM,wCAAwC,CAAC;AAEtE;;;GAGG;AACH,MAAM,OAAO,eAAe;IACjB,EAAE,CAAW;IACb,cAAc,CAAiB;IAExC,YAAY,EAAY;QACtB,IAAI,CAAC,EAAE,GAAG,EAAE,CAAC;QACb,IAAI,CAAC,cAAc,GAAG,IAAI,cAAc,CAAC,EAAE,CAAC,CAAC;IAC/C,CAAC;IAED;;;OAGG;IACH,GAAG,CAAC,GAAW,EAAE,GAAG,IAAe;QACjC,OAAO,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,GAAG,EAAE,MAAM,CAAC,EAAE,CAC3C,MAAM,CAAC,SAAS,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,CAC9B,CAAC;IACJ,CAAC;IAED;;;OAGG;IACH,8DAA8D;IAC9D,GAAG,CAAC,GAAW,EAAE,GAAG,IAAe;QACjC,OAAO,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,GAAG,EAAE,MAAM,CAAC,EAAE,CAC3C,MAAM,CAAC,SAAS,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,CAC9B,CAAC;IACJ,CAAC;IAED;;;OAGG;IACH,8DAA8D;IAC9D,GAAG,CAAC,GAAW,EAAE,GAAG,IAAe;QACjC,OAAO,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,GAAG,EAAE,MAAM,CAAC,EAAE,CAC3C,MAAM,CAAC,SAAS,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,CAC9B,CAAC;IACJ,CAAC;IAED,0BAA0B;IAC1B,eAAe;QACb,OAAO,IAAI,CAAC,GAAG,CAAC,kBAAkB,CAAC,CAAC;IACtC,CAAC;IAED,MAAM;QACJ,OAAO,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IAC5B,CAAC;IAED,QAAQ;QACN,OAAO,IAAI,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;IAC9B,CAAC;CACF"}

package/out/zero-cache/src/db/transaction-pool.d.ts

@@ -0,0 +1,187 @@
+import type { LogContext } from '@rocicorp/logger';
+import type postgres from 'postgres';
+import type { PostgresDB, PostgresTransaction } from '../types/pg.js';
+type MaybePromise<T> = Promise<T> | T;
+export type Statement = postgres.PendingQuery<(postgres.Row & Iterable<postgres.Row>)[]> | postgres.PendingQuery<postgres.Row[]>;
+/**
+ * A {@link Task} is logic run from within a transaction in a {@link TransactionPool}.
+ * It returns a list of `Statements` that the transaction executes asynchronously and
+ * awaits when it receives the 'done' signal.
+ *
+ */
+export type Task = (tx: PostgresTransaction, lc: LogContext) => MaybePromise<Statement[]>;
+/**
+ * A {@link ReadTask} is run from within a transaction, but unlike a {@link Task},
+ * the results of a ReadTask are opaque to the TransactionPool and returned to the
+ * caller of {@link TransactionPool.processReadTask}.
+ */
+export type ReadTask<T> = (tx: PostgresTransaction, lc: LogContext) => MaybePromise<T>;
+export declare enum Mode {
+    SERIALIZABLE = "ISOLATION LEVEL SERIALIZABLE",
+    READONLY = "ISOLATION LEVEL REPEATABLE READ READ ONLY"
+}
+/**
+ * A TransactionPool is a pool of one or more {@link postgres.TransactionSql}
+ * objects that participate in processing a dynamic queue of tasks.
+ *
+ * This can be used for serializing a set of tasks that arrive asynchronously
+ * to a single transaction (for writing) or performing parallel reads across
+ * multiple connections at the same snapshot (e.g. read only snapshot transactions).
+ */
+export declare class TransactionPool {
+    #private;
+    /**
+     * @param init A {@link Task} that is run in each Transaction before it begins
+     *             processing general tasks. This can be used to to set the transaction
+     *             mode, export/set snapshots, etc. This will be run even if
+     *             {@link fail} has been called on the pool.
+     * @param cleanup A {@link Task} that is run in each Transaction before it closes.
+     *                This will be run even if {@link fail} has been called, or if a
+     *                preceding Task threw an Error.
+     * @param initialWorkers The initial number of transaction workers to process tasks.
+     *                       This is the steady state number of workers that will be kept
+     *                       alive if the TransactionPool is long lived.
+     *                       This must be greater than 0. Defaults to 1.
+     * @param maxWorkers When specified, allows the pool to grow to `maxWorkers`. This
+     *                   must be greater than or equal to `initialWorkers`. On-demand
+     *                   workers will be shut down after an idle timeout of 5 seconds.
+     */
+    constructor(lc: LogContext, mode: Mode, init?: Task, cleanup?: Task, initialWorkers?: number, maxWorkers?: number, timeoutTasks?: TimeoutTasks);
+    /**
+     * Starts the pool of workers to process Tasks with transactions opened from the
+     * specified {@link db}.
+     */
+    run(db: PostgresDB): this;
+    /**
+     * Adds context parameters to internal LogContext. This is useful for context values that
+     * are not known when the TransactionPool is constructed (e.g. determined after a database
+     * call when the pool is running).
+     *
+     * Returns an object that can be used to add more parameters.
+     */
+    addLoggingContext(key: string, value: string): {
+        addLoggingContext: (key: string, value: string) => any;
+    };
+    /**
+     * Returns a promise that:
+     *
+     * * resolves after {@link setDone} has been called (or the the pool as been {@link unref}ed
+     *   to a 0 ref count), once all added tasks have been processed and all transactions have been
+     *   committed or closed.
+     *
+     * * rejects if processing was aborted with {@link fail} or if processing any of
+     *   the tasks resulted in an error. All uncommitted transactions will have been
+     *   rolled back.
+     *
+     * Note that partial failures are possible if processing writes with multiple workers
+     * (e.g. `setDone` is called, allowing some workers to commit, after which other
+     *  workers encounter errors). Using a TransactionPool in this manner does not make
+     * sense in terms of transactional semantics, and is thus not recommended.
+     *
+     * For reads, however, multiple workers is useful for performing parallel reads
+     * at the same snapshot. See {@link synchronizedSnapshots} for an example.
+     * Resolves or rejects when all workers are done or failed.
+     */
+    done(): Promise<void>;
+    process(task: Task): void;
+    processReadTask<T>(readTask: ReadTask<T>): Promise<T>;
+    /**
+     * Signals to all workers to end their transaction once all pending tasks have
+     * been completed.
+     */
+    setDone(): void;
+    /**
+     * An alternative to explicitly calling {@link setDone}, `ref()` increments an internal reference
+     * count, and {@link unref} decrements it. When the reference count reaches 0, {@link setDone} is
+     * automatically called. A TransactionPool is initialized with a reference count of 1.
+     *
+     * `ref()` should be called before sharing the pool with another component, and only after the
+     * pool has been started with {@link run()}. It must not be called on a TransactionPool that is
+     * already done (either via {@link unref()} or {@link setDone()}. (Doing so indicates a logical
+     * error in the code.)
+     *
+     * It follows that:
+     * * The creator of the TransactionPool is responsible for running it.
+     * * The TransactionPool should be ref'ed before being sharing.
+     * * The receiver of the TransactionPool is only responsible for unref'ing it.
+     *
+     * On the other hand, a transaction pool that fails with a runtime error can still be ref'ed;
+     * attempts to use the pool will result in the runtime error as expected.
+     */
+    ref(count?: number): void;
+    /**
+     * Decrements the internal reference count, automatically invoking {@link setDone} when it reaches 0.
+     */
+    unref(count?: number): void;
+    isRunning(): boolean;
+    /**
+     * Signals all workers to fail their transactions with the given {@link err}.
+     */
+    fail(err: unknown): void;
+}
+type SynchronizeSnapshotTasks = {
+    /**
+     * The `init` Task for the TransactionPool from which the snapshot originates.
+     * The pool must have Mode.SERIALIZABLE, and will be set to READ ONLY by the
+     * `exportSnapshot` init task. If the TransactionPool has multiple workers, the
+     * first worker will export a snapshot that the others set.
+     */
+    exportSnapshot: Task;
+    /**
+     * The `cleanup` Task for the TransactionPool from which the snapshot
+     * originates. This Task will wait for the follower pool to `setSnapshot`
+     * to ensure that the snapshot is successfully shared before the originating
+     * transaction is closed.
+     */
+    cleanupExport: Task;
+    /**
+     * The `init` Task for the TransactionPool in which workers will
+     * consequently see the same snapshot as that of the first pool. The pool
+     * must have Mode.SERIALIZABLE, and will have the ability to perform writes.
+     */
+    setSnapshot: Task;
+    /** The ID of the shared snapshot. */
+    snapshotID: Promise<string>;
+};
+/**
+ * Init Tasks for Postgres snapshot synchronization across transactions.
+ *
+ * https://www.postgresql.org/docs/9.3/functions-admin.html#:~:text=Snapshot%20Synchronization%20Functions,identical%20content%20in%20the%20database.
+ */
+export declare function synchronizedSnapshots(): SynchronizeSnapshotTasks;
+/**
+ * Returns `init` and `cleanup` {@link Task}s for a TransactionPool that ensure its workers
+ * share a single view of the database. This is used for View Notifier and View Syncer logic
+ * that allows multiple entities to perform parallel reads on the same snapshot of the database.
+ */
+export declare function sharedSnapshot(): {
+    init: Task;
+    cleanup: Task;
+    snapshotID: Promise<string>;
+};
+/**
+ * @returns An `init` Task for importing a snapshot from another transaction.
+ */
+export declare function importSnapshot(snapshotID: string): {
+    init: Task;
+    imported: Promise<void>;
+};
+/**
+ * A superclass of Errors used for control flow that is needed to handle
+ * another Error but does not constitute an error condition itself (e.g.
+ * aborting transactions after a previous one fails). Subclassing this Error
+ * will result in lowering the log level from `error` to `debug`.
+ */
+export declare class ControlFlowError extends Error {
+    constructor(err: unknown);
+}
+type TimeoutTask = {
+    timeoutMs: number;
+    task: Task | 'done';
+};
+type TimeoutTasks = {
+    forInitialWorkers: TimeoutTask;
+    forExtraWorkers: TimeoutTask;
+};
+export {};
+//# sourceMappingURL=transaction-pool.d.ts.map

package/out/zero-cache/src/db/transaction-pool.d.ts.map

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