@rocicorp/zero 0.0.0-202410031711

package/out/zero-cache/src/services/view-syncer/schema/types.d.ts.map

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

package/out/zero-cache/src/services/view-syncer/schema/types.js

@@ -0,0 +1,213 @@
+import * as v from '../../../../../shared/src/valita.js';
+import { astSchema } from '../../../../../zero-protocol/src/mod.js';
+import { versionFromLexi, versionToLexi } from '../../../types/lexi-version.js';
+import { jsonValueSchema } from '../../../types/bigint-json.js';
+export const cvrVersionSchema = v.object({
+    /**
+     * The database `stateVersion` with which the rows in the CVR are consistent.
+     */
+    stateVersion: v.string(), // LexiVersion
+    /**
+     * `minorVersion` is subversion of `stateVersion` that is initially absent for each
+     * `stateVersion`, and incremented for configuration changes that affect the contents
+     * of the CVR such as:
+     *
+     * * client set changes
+     * * query set changes
+     * * query transformation changes (which may happen for changes
+     *   in server-side logic or authorization policies)
+     *
+     * Such configuration changes are always correlated with a change to one or more
+     * `/meta/...` records in the CVR, often (but not always) with corresponding
+     * patches in `/patches/meta/...`.
+     *
+     * When the `stateVersion` moves forward, the `minorVersion` is reset to absent.
+     * In this manner it behaves like the analogous concept in semantic versioning.
+     */
+    minorVersion: v.number().optional(),
+});
+export function oneAfter(v) {
+    return v === null
+        ? { stateVersion: versionToLexi(0) }
+        : {
+            stateVersion: v.stateVersion,
+            minorVersion: (v.minorVersion ?? 0) + 1,
+        };
+}
+export function cmpVersions(a, b) {
+    return a === null && b === null
+        ? 0
+        : a === null
+            ? -1
+            : b === null
+                ? 1
+                : a.stateVersion < b.stateVersion
+                    ? -1
+                    : a.stateVersion > b.stateVersion
+                        ? 1
+                        : (a.minorVersion ?? 0) - (b.minorVersion ?? 0);
+}
+export function versionToCookie(v) {
+    return versionString(v);
+}
+export function versionToNullableCookie(v) {
+    return v === null ? null : versionToCookie(v);
+}
+export function cookieToVersion(cookie) {
+    if (cookie === null) {
+        return null;
+    }
+    return versionFromString(cookie);
+}
+// Last Active tracking.
+export const lastActiveSchema = v.object({ epochMillis: v.number() });
+export const cvrIDSchema = v.object({ id: v.string() });
+const cvrRecordSchema = v.object({
+    /**
+     * CVR records store the CVRVersion at which the record was last patched into
+     * the CVR, which corresponds with a patch row that is cleaned up when the
+     * record is changed (updated, deleted, and re-added in the case of rows).
+     *
+     * Tombstones are stored for row records but not for config records. This means
+     * that "orphaned" delete patches for config records may exist, and therefore
+     * scans of config patches must always run until the end of the list. On the
+     * contrary, for row patches, the row record tombstones allow cleanup of delete
+     * patches.
+     */
+    patchVersion: cvrVersionSchema,
+});
+export const clientRecordSchema = cvrRecordSchema.extend({
+    /** The client ID, of which there can be multiple for a client group view. */
+    id: v.string(),
+    /** The client's desired query IDs. Patch information is stored in the QueryRecord. */
+    desiredQueryIDs: v.array(v.string()),
+});
+export const baseQueryRecordSchema = v.object({
+    /** The client-specified ID used to identify this query. Typically a hash. */
+    id: v.string(),
+    /** The original AST as supplied by the client. */
+    ast: astSchema,
+    /**
+     * The hash of the query after server-side transformations, which include:
+     *
+     * * Normalization (which may differ from what the client does)
+     * * Query "expansion" to include primary keys and query-execution-related columns
+     * * Authorization transforms
+     *
+     * Transformations depend on conditions that are independent of the db state version,
+     * such as server-side logic and authorization policies. As such, the version of a CVR
+     * version may need to be advanced independent of db state changes. This is done
+     * via the `minorVersion` counter of the CVRVersion object, which is used to account
+     * for both changes to the query set and changes to query transformations (which are
+     * effectively remove-old-query + add-new-query).
+     *
+     * Note that the transformed AST itself is **not** stored, as the result of the previous
+     * transformation is not useful in and of itself. If the current transformation results in
+     * a different hash than that of the transformation used for the last version of the CVR,
+     * it is simply handled by invalidating the existing rows, re-executed the query with
+     * the new transformation, and advancing the CVR's `minorVersion` and this query's
+     * `transformationVersion`.
+     *
+     * Note that the transformationHash is only stored when the query has reached the "gotten"
+     * state. If the query is in the "desired" but not yet "gotten" state, the field is absent.
+     */
+    transformationHash: v.string().optional(),
+    /**
+     * The CVR version corresponding to the `transformationHash`. This essentially tracks when
+     * this version of the query was effectively added to the CVR (as opposed to the
+     * `patchVersion`, which is simply when the client was notified that its query was added
+     * to the gotten set). Catchup of clients from old CVR versions require executing all
+     * queries with a newer `transformationVersion`.
+     */
+    transformationVersion: cvrVersionSchema.optional(),
+});
+/**
+ * Internal queries track rows in the database for internal use, such as the
+ * `lastMutationID`s in the `zero.clients` table. They participate in the standard
+ * invalidation / update logic for row contents, but not in the desired/got or
+ * size-based quota logic for client-requested queries.
+ */
+export const internalQueryRecordSchema = baseQueryRecordSchema.extend({
+    internal: v.literal(true),
+});
+export const clientQueryRecordSchema = baseQueryRecordSchema.extend({
+    internal: v.literal(false).optional(),
+    // For queries, the `patchVersion` indicates when query was added to the got set,
+    // and is absent if not yet gotten.
+    patchVersion: cvrVersionSchema.optional(),
+    // Maps each of the desiring client's IDs to the version at which
+    // the queryID was added to their desired query set (i.e. individual `patchVersion`s).
+    desiredBy: v.record(cvrVersionSchema),
+    // TODO: Iron this out.
+    // estimatedBytes: v.number(),
+    // lru information?
+});
+export const queryRecordSchema = v.union(clientQueryRecordSchema, internalQueryRecordSchema);
+export const rowIDSchema = v.object({
+    schema: v.string(),
+    table: v.string(),
+    rowKey: v.record(jsonValueSchema),
+});
+export const metaRecordSchema = v.union(cvrVersionSchema, lastActiveSchema, clientRecordSchema, queryRecordSchema);
+export const rowRecordSchema = cvrRecordSchema.extend({
+    id: rowIDSchema,
+    rowVersion: v.string(), // '_0_version' of the row
+    // query hashes => refCount, or `null` for a row that was removed from the
+    // view (i.e. tombstone).
+    refCounts: v.record(v.number()).nullable(),
+});
+export const patchSchema = v.object({
+    type: v.union(v.literal('client'), v.literal('row'), v.literal('query')),
+    op: v.union(v.literal('put'), v.literal('del')),
+});
+export const putRowPatchSchema = patchSchema.extend({
+    type: v.literal('row'),
+    op: v.literal('put'),
+    id: rowIDSchema,
+    rowVersion: v.string(), // '_0_version' of the row
+});
+export const delRowPatchSchema = patchSchema.extend({
+    type: v.literal('row'),
+    op: v.literal('del'),
+    id: rowIDSchema,
+});
+export const rowPatchSchema = v.union(putRowPatchSchema, delRowPatchSchema);
+export const queryPatchSchema = patchSchema.extend({
+    type: v.literal('query'),
+    id: v.string(),
+    clientID: v.string().optional(), // defined for "desired", undefined for "got"
+});
+export const clientPatchSchema = patchSchema.extend({
+    type: v.literal('client'),
+    id: v.string(),
+});
+export const metadataPatchSchema = v.union(clientPatchSchema, queryPatchSchema);
+export function versionString(v) {
+    // The separator (e.g. ":") needs to be lexicographically greater than the
+    // storage key path separator (e.g. "/") so that "01/row-hash" is less than "01:01/row-hash".
+    // In particular, the traditional separator for major.minor versions (".") does not
+    // satisfy this quality.
+    return v.minorVersion
+        ? `${v.stateVersion}:${versionToLexi(v.minorVersion)}`
+        : v.stateVersion;
+}
+export function versionFromString(str) {
+    const parts = str.split(':');
+    const stateVersion = parts[0];
+    switch (parts.length) {
+        case 1: {
+            versionFromLexi(stateVersion); // Purely for validation.
+            return { stateVersion };
+        }
+        case 2: {
+            const minorVersion = versionFromLexi(parts[1]);
+            if (minorVersion > BigInt(Number.MAX_SAFE_INTEGER)) {
+                throw new Error(`minorVersion ${parts[1]} exceeds max safe integer`);
+            }
+            return { stateVersion, minorVersion: Number(minorVersion) };
+        }
+        default:
+            throw new TypeError(`Invalid version string ${str}`);
+    }
+}
+//# sourceMappingURL=types.js.map

package/out/zero-cache/src/services/view-syncer/schema/types.js.map

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

package/out/zero-cache/src/services/view-syncer/snapshotter.d.ts

@@ -0,0 +1,166 @@
+import { LogContext } from '@rocicorp/logger';
+import { StatementRunner } from '../../../../zero-cache/src/db/statements.js';
+import { type RowValue } from '../../../../zero-cache/src/types/row-key.js';
+/**
+ * A `Snapshotter` manages the progression of database snapshots for a
+ * ViewSyncer.
+ *
+ * The Replicator and ViewSyncers operate on the same SQLite file, with the
+ * Replicator being the sole writer to the database. The IVM logic in
+ * ViewSyncers, however, rely on incrementally applying changes to the DB to
+ * update the state of its pipelines.
+ *
+ * To avoid coupling the progress of the Replicator and all IVM pipelines on
+ * each other, ViewSyncers operate on ephemeral forks of the database by holding
+ * [concurrent](https://sqlite.org/src/doc/begin-concurrent/doc/begin_concurrent.md)
+ * snapshots of the database and simulating (but ultimately rolling back)
+ * mutations on these snapshots.
+ *
+ * Example:
+ * 1. ViewSyncer takes `snapshot_a` at version `t1` of the database and
+ *    hydrates its pipeline(s).
+ * 2. Replicator applies a new transaction to the database and notifies
+ *    subscribers.
+ * 3. ViewSyncer takes `snapshot_b` at `t2`, and queries the `ChangeLog` at
+ *    that snapshot for changes since `t1`.
+ * 4. ViewSyncer applies those changes to `snapshot_a` for IVM, but does not
+ *    commit them. (Recall that the Replicator is the sole writer to the db, so
+ *    the ViewSyncer never commits any writes.)
+ * 5. Replicator applies the next transaction and advances the database to `t3`.
+ * 6. ViewSyncer rolls back `snapshot_a` and opens `snapshot_c` at `t3`, using
+ *    `snapshot_b` to simulate changes from `t2` to `t3`.
+ *
+ * ```
+ * Replicator:  t1 --------------> t2 --------------> t3 --------------->
+ * ViewSyncer:       [snapshot_a] ----> [snapshot_b] ----> [snapshot_c]
+ * ```
+ *
+ * Note that the Replicator (and ViewSyncers) do not wait on the progress of
+ * other ViewSyncers. If a ViewSyncer is busy hydrating at `t1`, the Replicator
+ * and other ViewSyncers can progress through `t2`, `t3`, etc. independently,
+ * as the busy ViewSyncer simply takes its own snapshot when it is ready.
+ *
+ * ```
+ * Replicator:   t1 --------------> t2 --------------> t3 --------------->
+ * ViewSyncer1:       [snapshot_a] ----> [snapshot_b] ----> [snapshot_c]
+ * ViewSyncer2:       [.......... snapshot_a ..........] ----> [snapshot_b]
+ * ```
+ *
+ * To minimize Database connections (and statement preparation, etc.), the
+ * Snapshotter reuses the connection from the previous (rolled back)
+ * snapshot when opening the new one.
+ *
+ * ```
+ * Replicator:  t1 --------------> t2 --------------> t3 --------------->
+ * ViewSyncer:       [snapshot_a] ----> [snapshot_b] ----> [snapshot_c]
+ *                     (conn_1)           (conn_2)           (conn_1)
+ * ```
+ *
+ * In this manner, each ViewSyncer uses two connections that continually
+ * "leapfrog" each other to replay the timeline of changes in isolation from
+ * the Replicator and other ViewSyncers.
+ */
+export declare class Snapshotter {
+    #private;
+    constructor(lc: LogContext, dbFile: string);
+    /**
+     * Initializes the snapshot to the current head of the database. This must be
+     * only be called once. The state of whether a Snapshotter has been initialized
+     * can be determined by calling {@link initialized()}.
+     */
+    init(): this;
+    initialized(): boolean;
+    /** Returns the current snapshot. Asserts if {@link initialized()} is false. */
+    current(): {
+        db: StatementRunner;
+        version: string;
+    };
+    /**
+     * Advances to the head of the Database, returning a diff between the
+     * previously current Snapshot and a new Snapshot at head. This is called
+     * in response to a notification from a Replicator subscription. Subsequent
+     * calls to {@link current()} return the new Snapshot. Note that the Snapshotter
+     * must be initialized before advancing.
+     *
+     * The returned {@link SnapshotDiff} contains snapshots at the endpoints
+     * of the database timeline. Iterating over the diff generates a sequence
+     * of {@link Change}s between the two snapshots.
+     *
+     * Note that this sequence is not chronological; rather, the sequence is
+     * ordered by `<table, row-key>`, such that a row can appear at most once
+     * in the common case, or twice if its table is `TRUNCATE`'d and a new value
+     * is subsequently `INSERT`'ed. This results in dropping most intermediate
+     * changes to a row and bounds the amount of work needed to catch up;
+     * however, as a consequence, a consistent database state is only guaranteed
+     * when the sequence has been fully consumed.
+     *
+     * Note that Change generation relies on the state of the underlying
+     * database connections, and because the connection for the previous snapshot
+     * is reused to produce the next snapshot, the diff object is only valid
+     * until the next call to `advance()`.
+     *
+     * It is okay for the caller to apply `Change`s to the `prev` snapshot
+     * during the iteration (e.g. this is necessary for IVM); the remainder
+     * of the iteration is not affected because a given row can appear at most
+     * once in the sequence (with the exception being TRUNCATE, after which the
+     * deleted rows can be re-inserted, but this will also behave correctly if
+     * the changes are applied).
+     *
+     * Once the changes have been applied, however, a _subsequent_ iteration
+     * will not produce the correct results. In order to perform multiple
+     * change-applying iterations, the caller must (1) create a save point
+     * on `prev` before each iteration, and (2) rollback to the save point after
+     * the iteration.
+     */
+    advance(): SnapshotDiff;
+    /**
+     * Releases all locks on the database. Call {@link advance()}
+     * to reestablish a snapshot.
+     *
+     * This must only be called if the Snapshotter has been initialized.
+     */
+    release(): void;
+    /**
+     * Call this to close the database connections when the Snapshotter is
+     * no longer needed.
+     */
+    destroy(): void;
+}
+export type Change = {
+    readonly table: string;
+    readonly prevValue: Readonly<RowValue> | null;
+    readonly nextValue: Readonly<RowValue> | null;
+};
+/**
+ * Represents the difference between two database Snapshots.
+ * Iterating over the object will produce a sequence of {@link Change}s
+ * between the two snapshots.
+ *
+ * See {@link Snapshotter.advance()} for semantics and usage.
+ */
+export interface SnapshotDiff extends Iterable<Change> {
+    readonly prev: {
+        readonly db: StatementRunner;
+        readonly version: string;
+    };
+    readonly curr: {
+        readonly db: StatementRunner;
+        readonly version: string;
+    };
+    /**
+     * The number of ChangeLog entries between the snapshots. Note that this
+     * may not necessarily equal the number of `Change` objects that the iteration
+     * will produce, as `TRUNCATE` entries are counted as a single log entry which
+     * may be expanded into many changes (i.e. row deletes).
+     *
+     * TODO: Determine if it is worth changing the definition to count the
+     *       truncated rows. This would make diff computation more expensive
+     *       (requiring the count to be aggregated by operation type), which
+     *       may not be worth it for a presumable rare operation.
+     */
+    readonly changes: number;
+}
+export declare class InvalidDiffError extends Error {
+    constructor(msg: string);
+}
+//# sourceMappingURL=snapshotter.d.ts.map

package/out/zero-cache/src/services/view-syncer/snapshotter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshotter.d.ts","sourceRoot":"","sources":["../../../../../../zero-cache/src/services/view-syncer/snapshotter.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,UAAU,EAAC,MAAM,kBAAkB,CAAC;AAI5C,OAAO,EAAC,eAAe,EAAC,MAAM,iCAAiC,CAAC;AAKhE,OAAO,EAGL,KAAK,QAAQ,EACd,MAAM,iCAAiC,CAAC;AAYzC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0DG;AACH,qBAAa,WAAW;;gBAMV,EAAE,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM;IAK1C;;;;OAIG;IACH,IAAI,IAAI,IAAI;IAOZ,WAAW,IAAI,OAAO;IAItB,+EAA+E;IAC/E,OAAO,IAAI;QAAC,EAAE,EAAE,eAAe,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAC;IAKjD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAoCG;IACH,OAAO,IAAI,YAAY;IAUvB;;;;;OAKG;IACH,OAAO;IAMP;;;OAGG;IACH,OAAO;CAKR;AAED,MAAM,MAAM,MAAM,GAAG;IACnB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,SAAS,EAAE,QAAQ,CAAC,QAAQ,CAAC,GAAG,IAAI,CAAC;IAC9C,QAAQ,CAAC,SAAS,EAAE,QAAQ,CAAC,QAAQ,CAAC,GAAG,IAAI,CAAC;CAC/C,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,WAAW,YAAa,SAAQ,QAAQ,CAAC,MAAM,CAAC;IACpD,QAAQ,CAAC,IAAI,EAAE;QACb,QAAQ,CAAC,EAAE,EAAE,eAAe,CAAC;QAC7B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;KAC1B,CAAC;IACF,QAAQ,CAAC,IAAI,EAAE;QACb,QAAQ,CAAC,EAAE,EAAE,eAAe,CAAC;QAC7B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;KAC1B,CAAC;IAEF;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AA6QD,qBAAa,gBAAiB,SAAQ,KAAK;gBAC7B,GAAG,EAAE,MAAM;CAGxB"}