@earendil-works/chord 1.5.0 → 1.5.1

package/dist/sync/batch.js

@@ -0,0 +1,125 @@
+// Bodies on the remote, encoded and decoded as streams, so neither side holds a whole batch or snapshot in memory:
+// gzip-compressed JSON lines, one outbox commit (a batch) or one archive part (a snapshot) per line. gzip, because
+// `CompressionStream` offers it in Node, Workers, and browsers alike, and a browser viewer reads batches too.
+import { decodeJsonl, encodeJsonl } from "../store/jsonl.js";
+import { decodeLogLine, encodeLogLine, LogFormatError } from "./lines.js";
+/** The bytes a chunk of encoded lines collects before it is compressed. */
+const CHUNK = 64 * 1024;
+/** A batch body: `commits` as gzip-compressed JSON lines, read from `commits` only as the body is read. */
+export function encodeBatch(commits) {
+    return encodeLines((async function* () {
+        for await (const commit of commits)
+            yield encodeLogLine(commit);
+    })());
+}
+/** The commits of a batch body, in order, as they arrive. */
+export async function* decodeBatch(body) {
+    for await (const { commit } of decodeBatchLines(body))
+        yield commit;
+}
+/** The commits of a batch body with the size of each line, for callers that bound what they hold. */
+export async function* decodeBatchLines(body) {
+    let previous = 0;
+    for await (const { text, number } of lines(gunzip(body))) {
+        const commit = decodeLogLine(text, number);
+        if (commit.seq <= previous)
+            throw new LogFormatError(`Log line ${number} does not increase the sequence`);
+        previous = commit.seq;
+        yield { commit, bytes: text.length + 1 };
+    }
+}
+/** A snapshot body: a store archive (`store.export()`), one part per JSON line, gzip-compressed. */
+export function encodeSnapshot(parts) {
+    return gzip(encodeJsonl(parts));
+}
+/** The parts of a snapshot body as they arrive, unchecked: `importStore()` checks them (a trust boundary). */
+export function decodeSnapshot(body) {
+    return decodeJsonl(gunzip(body));
+}
+/** Text lines, already newline-terminated, gzip-compressed in chunks of whole lines. */
+function encodeLines(lines) {
+    return gzip((async function* () {
+        const encoder = new TextEncoder();
+        let pending = "";
+        for await (const line of lines) {
+            pending += line;
+            if (pending.length >= CHUNK) {
+                yield encoder.encode(pending);
+                pending = "";
+            }
+        }
+        if (pending.length > 0)
+            yield encoder.encode(pending);
+    })());
+}
+/** The lines of decompressed `chunks` without their newlines; a body that ends inside a line is an error. */
+async function* lines(chunks) {
+    const decoder = new TextDecoder("utf-8", { fatal: true });
+    let rest = "";
+    let number = 0;
+    const decode = (chunk) => {
+        try {
+            return chunk === undefined ? decoder.decode() : decoder.decode(chunk, { stream: true });
+        }
+        catch (error) {
+            throw new LogFormatError(`Log line ${number + 1} is not UTF-8`, { cause: error });
+        }
+    };
+    for await (const chunk of chunks) {
+        rest += decode(chunk);
+        let start = 0;
+        for (let end = rest.indexOf("\n"); end >= 0; end = rest.indexOf("\n", start)) {
+            yield { text: rest.slice(start, end), number: ++number };
+            start = end + 1;
+        }
+        rest = rest.slice(start);
+    }
+    rest += decode();
+    if (rest.length > 0)
+        throw new LogFormatError(`The body ends inside log line ${number + 1}`);
+}
+function gzip(chunks) {
+    return pipe(chunks, new CompressionStream("gzip"));
+}
+function gunzip(chunks) {
+    return pipe(chunks, new DecompressionStream("gzip"));
+}
+/**
+ * `chunks` through `transform`, as they come: the source is written while the output is read, so each holds no more
+ * than the stream's buffers. Stopping early, or a failure on either side, ends the source too (its `return()`, which
+ * for an export gives the store's commit queue back).
+ */
+async function* pipe(chunks, transform) {
+    const writer = transform.writable.getWriter();
+    const reader = transform.readable.getReader();
+    const writing = (async () => {
+        try {
+            for await (const chunk of chunks)
+                await writer.write(chunk);
+            await writer.close();
+        }
+        catch (error) {
+            await writer.abort(error).catch(() => { });
+            throw error;
+        }
+    })();
+    // Its failure reaches the reader too (the abort errors the readable side); this only keeps it from going unhandled.
+    writing.catch(() => { });
+    let done = false;
+    try {
+        while (true) {
+            const result = await reader.read();
+            if (result.done)
+                break;
+            yield result.value;
+        }
+        done = true;
+        await writing;
+    }
+    finally {
+        if (!done)
+            await reader.cancel().catch(() => { });
+        reader.releaseLock();
+    }
+}
+//# sourceMappingURL=batch.js.map

package/dist/sync/batch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"batch.js","sourceRoot":"","sources":["../../src/sync/batch.ts"],"names":[],"mappings":"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","sourcesContent":["// Bodies on the remote, encoded and decoded as streams, so neither side holds a whole batch or snapshot in memory:\n// gzip-compressed JSON lines, one outbox commit (a batch) or one archive part (a snapshot) per line. gzip, because\n// `CompressionStream` offers it in Node, Workers, and browsers alike, and a browser viewer reads batches too.\n\nimport type { ArchivePart } from \"../store/archive.ts\";\nimport { decodeJsonl, encodeJsonl } from \"../store/jsonl.ts\";\nimport type { OutboxCommit } from \"../store/outbox.ts\";\nimport { decodeLogLine, encodeLogLine, LogFormatError } from \"./lines.ts\";\n\n/** A body on the remote: its bytes in chunks, read once. */\nexport type SyncBody = AsyncIterable<Uint8Array>;\n\n/** The bytes a chunk of encoded lines collects before it is compressed. */\nconst CHUNK = 64 * 1024;\n\n/** A batch body: `commits` as gzip-compressed JSON lines, read from `commits` only as the body is read. */\nexport function encodeBatch(commits: Iterable<OutboxCommit> | AsyncIterable<OutboxCommit>): SyncBody {\n\treturn encodeLines(\n\t\t(async function* () {\n\t\t\tfor await (const commit of commits) yield encodeLogLine(commit);\n\t\t})(),\n\t);\n}\n\n/** The commits of a batch body, in order, as they arrive. */\nexport async function* decodeBatch(body: SyncBody): AsyncGenerator<OutboxCommit> {\n\tfor await (const { commit } of decodeBatchLines(body)) yield commit;\n}\n\n/** The commits of a batch body with the size of each line, for callers that bound what they hold. */\nexport async function* decodeBatchLines(\n\tbody: SyncBody,\n): AsyncGenerator<{ readonly commit: OutboxCommit; readonly bytes: number }> {\n\tlet previous = 0;\n\tfor await (const { text, number } of lines(gunzip(body))) {\n\t\tconst commit = decodeLogLine(text, number);\n\t\tif (commit.seq <= previous) throw new LogFormatError(`Log line ${number} does not increase the sequence`);\n\t\tprevious = commit.seq;\n\t\tyield { commit, bytes: text.length + 1 };\n\t}\n}\n\n/** A snapshot body: a store archive (`store.export()`), one part per JSON line, gzip-compressed. */\nexport function encodeSnapshot(parts: AsyncIterable<ArchivePart>): SyncBody {\n\treturn gzip(encodeJsonl(parts));\n}\n\n/** The parts of a snapshot body as they arrive, unchecked: `importStore()` checks them (a trust boundary). */\nexport function decodeSnapshot(body: SyncBody): AsyncIterable<unknown> {\n\treturn decodeJsonl(gunzip(body));\n}\n\n/** Text lines, already newline-terminated, gzip-compressed in chunks of whole lines. */\nfunction encodeLines(lines: AsyncIterable<string>): SyncBody {\n\treturn gzip(\n\t\t(async function* () {\n\t\t\tconst encoder = new TextEncoder();\n\t\t\tlet pending = \"\";\n\t\t\tfor await (const line of lines) {\n\t\t\t\tpending += line;\n\t\t\t\tif (pending.length >= CHUNK) {\n\t\t\t\t\tyield encoder.encode(pending);\n\t\t\t\t\tpending = \"\";\n\t\t\t\t}\n\t\t\t}\n\t\t\tif (pending.length > 0) yield encoder.encode(pending);\n\t\t})(),\n\t);\n}\n\n/** The lines of decompressed `chunks` without their newlines; a body that ends inside a line is an error. */\nasync function* lines(chunks: AsyncIterable<Uint8Array>): AsyncGenerator<{ readonly text: string; number: number }> {\n\tconst decoder = new TextDecoder(\"utf-8\", { fatal: true });\n\tlet rest = \"\";\n\tlet number = 0;\n\tconst decode = (chunk?: Uint8Array): string => {\n\t\ttry {\n\t\t\treturn chunk === undefined ? decoder.decode() : decoder.decode(chunk, { stream: true });\n\t\t} catch (error) {\n\t\t\tthrow new LogFormatError(`Log line ${number + 1} is not UTF-8`, { cause: error });\n\t\t}\n\t};\n\tfor await (const chunk of chunks) {\n\t\trest += decode(chunk);\n\t\tlet start = 0;\n\t\tfor (let end = rest.indexOf(\"\\n\"); end >= 0; end = rest.indexOf(\"\\n\", start)) {\n\t\t\tyield { text: rest.slice(start, end), number: ++number };\n\t\t\tstart = end + 1;\n\t\t}\n\t\trest = rest.slice(start);\n\t}\n\trest += decode();\n\tif (rest.length > 0) throw new LogFormatError(`The body ends inside log line ${number + 1}`);\n}\n\nfunction gzip(chunks: AsyncIterable<Uint8Array>): SyncBody {\n\treturn pipe(chunks, new CompressionStream(\"gzip\"));\n}\n\nfunction gunzip(chunks: SyncBody): AsyncIterable<Uint8Array> {\n\treturn pipe(chunks, new DecompressionStream(\"gzip\"));\n}\n\n/**\n * `chunks` through `transform`, as they come: the source is written while the output is read, so each holds no more\n * than the stream's buffers. Stopping early, or a failure on either side, ends the source too (its `return()`, which\n * for an export gives the store's commit queue back).\n */\nasync function* pipe(\n\tchunks: AsyncIterable<Uint8Array>,\n\ttransform: CompressionStream | DecompressionStream,\n): AsyncGenerator<Uint8Array> {\n\tconst writer = transform.writable.getWriter();\n\tconst reader = transform.readable.getReader();\n\tconst writing = (async () => {\n\t\ttry {\n\t\t\tfor await (const chunk of chunks) await writer.write(chunk as Uint8Array<ArrayBuffer>);\n\t\t\tawait writer.close();\n\t\t} catch (error) {\n\t\t\tawait writer.abort(error).catch(() => {});\n\t\t\tthrow error;\n\t\t}\n\t})();\n\t// Its failure reaches the reader too (the abort errors the readable side); this only keeps it from going unhandled.\n\twriting.catch(() => {});\n\tlet done = false;\n\ttry {\n\t\twhile (true) {\n\t\t\tconst result = await reader.read();\n\t\t\tif (result.done) break;\n\t\t\tyield result.value;\n\t\t}\n\t\tdone = true;\n\t\tawait writing;\n\t} finally {\n\t\tif (!done) await reader.cancel().catch(() => {});\n\t\treader.releaseLock();\n\t}\n}\n"]}

package/dist/sync/client.d.ts

@@ -0,0 +1,166 @@
+import type { Context } from "../context/index.ts";
+import type { Backend } from "../store/backend.ts";
+import type { OutboxCommit } from "../store/outbox.ts";
+import { type Store } from "../store/store.ts";
+import { type Seq, type SessionSyncMaintenance, type SessionSyncStore } from "./remote.ts";
+/**
+ * Where an upload ends a batch: once its lines (before compression) reach this size. One commit larger than this is
+ * a batch of its own.
+ */
+export declare const BATCH_BYTES: number;
+/** How much of a batch a pull holds before it applies it: commits are applied in chunks of about this size. */
+export declare const APPLY_BYTES: number;
+/**
+ * What a host keeps for each copy of a session it syncs: the last sequence the copy shares with the remote. Commits
+ * after it are the copy's own and not uploaded yet. When this is lost, a copy without commits of its own takes the
+ * remote's head; one with commits finds out by uploading.
+ */
+export type SyncState = {
+    readonly syncedHead: Seq | undefined;
+    /**
+     * Set while a pull applies a batch or snapshot ending here: a local head up to it holds the remote's commits, not
+     * the copy's own, even when the pull stopped partway.
+     */
+    readonly pulling?: Seq;
+};
+export interface SyncStateStore {
+    get(sessionId: string, context: Context): Promise<SyncState | undefined>;
+    set(sessionId: string, state: SyncState, context: Context): Promise<void>;
+}
+/** A store's head as a sequence: `lastSeq`, 0 for a store without commits. */
+export declare function storeHead(store: Store): Seq;
+/** The store keeps no outbox, or its outbox no longer holds the commits a sync needs. */
+export declare class OutboxUnavailableError extends Error {
+    constructor(message: string);
+}
+/** The outbox commits after `after`, a page of at most `limit`. */
+export declare function readOutbox(store: Store, after: Seq, limit: number, context: Context): Promise<OutboxCommit[]>;
+export type UploadResult = {
+    readonly type: "uploaded";
+    readonly head: Seq;
+}
+/** Nothing was committed since the last upload. */
+ | {
+    readonly type: "idle";
+}
+/**
+ * Another device continued the session from `at` first. This copy's commits after `at` are a different history:
+ * the host renames the copy to a new session (forked from this one at `at`) and uploads it there, and the session
+ * itself restores into a fresh store.
+ */
+ | {
+    readonly type: "diverged";
+    readonly at: Seq;
+}
+/**
+ * The copy lost commits it had uploaded, for example to a power loss: its head is below `syncedHead`. Its next
+ * commits would reuse their sequences, so nothing is uploaded. Pull what it lost before the copy commits again; a pull
+ * applies from the local head.
+ */
+ | {
+    readonly type: "behind";
+    readonly head: Seq;
+    readonly syncedHead: Seq;
+}
+/**
+ * The remote refused this device's epoch: another device holds the right to write the session now. Like
+ * `diverged`, the copy's commits after `at` are a different history, so the host forks the copy (S7).
+ */
+ | {
+    readonly type: "stale_epoch";
+    readonly at: Seq;
+    readonly epoch: number;
+};
+/**
+ * Upload what this copy committed since it last shared the remote's history, from the store's outbox, and trim the
+ * outbox through what the remote acknowledged. Every device continues a session as its own; whichever creates the slot
+ * first continues the session, so an upload that is acknowledged stays.
+ *
+ * A session the remote does not have yet, whose outbox does not reach back to its first commit (turned on later, or
+ * trimmed, as for a copy renamed after it diverged), starts with an archive slot: the store's `export()` at its head.
+ *
+ * A slot this device created already is an upload whose response was lost: the remote has the history up to its end,
+ * and the upload goes on from there.
+ */
+export declare function uploadSession(options: {
+    readonly sessionId: string;
+    readonly device: string;
+    readonly source: Store;
+    readonly store: SessionSyncStore;
+    readonly state: SyncStateStore;
+    /** The writer's epoch, from whatever grants it (the remote, Radius); sent with every slot. */
+    readonly epoch?: number;
+    readonly context: Context;
+}): Promise<UploadResult>;
+/** This copy has commits it has not uploaded: upload them first, which may find that the copy diverged. */
+export declare class UnsyncedCommitsError extends Error {
+    constructor(sessionId: string, localHead: Seq, syncedHead: Seq);
+}
+/** The copy a pull applies to: an open store, or an empty backend to restore the session into. */
+export type LocalCopy = {
+    readonly kind: "store";
+    readonly store: Store;
+} | {
+    readonly kind: "empty";
+    readonly backend: Backend;
+};
+/**
+ * Apply what the remote has after the local head; into an empty backend, that restores the session (from an archive
+ * when the history starts with one) and opens its store with an outbox. Resolves with the store, which the caller
+ * owns and closes. Nothing may hold the store's claims (no `StoreStorage`, no Harness): `applyBatch()` refuses then.
+ *
+ * A copy with commits it has not uploaded rejects with `UnsyncedCommitsError` instead of getting the remote's commits
+ * spliced onto its own. A copy whose history folding removed rejects with `HistoryUnavailableError` and restores into
+ * a fresh backend.
+ */
+export declare function pullSession(options: {
+    readonly sessionId: string;
+    readonly store: SessionSyncStore;
+    readonly local: LocalCopy;
+    readonly state: SyncStateStore;
+    readonly context: Context;
+}): Promise<{
+    readonly store: Store;
+    readonly head: Seq;
+}>;
+/**
+ * Fold a session's history into one snapshot: restore it into `scratch` (an empty backend; a file or a Durable Object's
+ * SQLite storage, not `:memory:`, so the restored store is not held in memory), upload its `export()` as a snapshot, drop the commits of the batches it covers, keeping their
+ * slots taken, and delete older snapshots. The remote runs this, not clients.
+ */
+export declare function foldSession(options: {
+    readonly sessionId: string;
+    readonly store: SessionSyncMaintenance;
+    readonly scratch: Backend;
+    readonly context: Context;
+}): Promise<Seq | undefined>;
+export type FlushSchedulerOptions = {
+    readonly flush: () => Promise<unknown>;
+    /** Arms a timer and returns its disarm. */
+    readonly setTimer: (callback: () => void, delayMs: number) => () => void;
+    readonly now: () => number;
+    /** A failed flush; the scheduler retries it with backoff. */
+    readonly onError: (error: unknown) => void;
+    /** Delay of an ordinary flush after a commit. Default 5 seconds. */
+    readonly intervalMs?: number;
+    /** Delay of a flush after an urgent commit. Default 200 milliseconds. */
+    readonly urgentMs?: number;
+    /** First retry delay after a failed flush, doubling up to `maxRetryMs`. Default 1 second. */
+    readonly retryMs?: number;
+    /** Default 1 minute. */
+    readonly maxRetryMs?: number;
+};
+/**
+ * Decides when to flush: some time after a commit, sooner after an urgent one, one flush at a time. Commits that arrive
+ * during a flush keep their urgency and schedule the next one when it ends. A failed flush is retried with backoff
+ * until one succeeds, so the last commits of a turn do not wait for the next commit.
+ */
+export declare class FlushScheduler {
+    #private;
+    constructor(options: FlushSchedulerOptions);
+    /** A commit landed. */
+    notify(urgent: boolean): void;
+    /** Flush now, after a flush underway, and stop scheduling. A failure rejects. */
+    close(): Promise<void>;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/sync/client.d.ts.map

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