@earendil-works/chord 1.4.0 → 1.5.1

package/dist/sync/filesystem.js

@@ -0,0 +1,185 @@
+import { isNotFound, unwrap } from "./files.js";
+import { remoteHead, } from "./remote.js";
+const pad = (value) => String(value).padStart(16, "0");
+/** How much of a body is read from its file at a time. */
+const READ_CHUNK = 256 * 1024;
+/** One buffer as a body. */
+async function* once(bytes) {
+    yield bytes;
+}
+const SLOT_NAME = /^(\d{16})\.json$/;
+const SNAPSHOT_NAME = /^(\d{16})\.batch$/;
+const SESSION_ID = /^[A-Za-z0-9_-][A-Za-z0-9._-]*$/;
+/** A session ID names a file or directory: refuse anything that could leave the root. */
+export function checkSessionId(sessionId) {
+    if (!SESSION_ID.test(sessionId))
+        throw new Error(`Invalid session ID for a sync directory: ${sessionId}`);
+    return sessionId;
+}
+/**
+ * A remote store in a directory, laid out as the real remote is: per session, one slot per batch start, holding where
+ * the batch ends and which device created it, and snapshots named by their end. As the real remote, it creates a slot
+ * only where the history ends. Creating a slot is check-then-write,
+ * without the atomicity of the real remote across processes: for development and tests, with one process writing.
+ *
+ * ```text
+ * {root}/{session}/slots/{after}.json     { after, to, device, archive?, folded? }, written once
+ * {root}/{session}/batches/{after}.batch  the commits (or an archive), until folded
+ * {root}/{session}/snapshots/{to}.batch   a store archive
+ * {root}/{session}/meta.json             the host's description, last write wins
+ * ```
+ */
+export class FileSystemSyncRemote {
+    #fs;
+    #root;
+    constructor(fs, root) {
+        this.#fs = fs;
+        this.#root = root;
+    }
+    async putBatch(sessionId, after, to, device, body, context, options = {}) {
+        const existing = await this.#slot(sessionId, after, context);
+        if (existing !== undefined)
+            return { type: "exists", to: existing.to, device: existing.device };
+        const head = remoteHead(await this.list(sessionId, context));
+        if (after !== head)
+            return { type: "not_head", head };
+        await this.#write(sessionId, ["batches"], `${pad(after)}.batch`, body, context);
+        // The slot is written last: it is what makes the batch exist.
+        const slot = { after, to, device, ...(options.archive === true ? { archive: true } : {}) };
+        await this.#write(sessionId, ["slots"], `${pad(after)}.json`, once(new TextEncoder().encode(JSON.stringify(slot))), context);
+        return { type: "created" };
+    }
+    async getBatch(sessionId, after, context) {
+        const slot = await this.#slot(sessionId, after, context);
+        if (slot === undefined || slot.folded)
+            return undefined;
+        return this.#stream(context, sessionId, "batches", `${pad(after)}.batch`);
+    }
+    getSnapshot(sessionId, to, context) {
+        return this.#stream(context, sessionId, "snapshots", `${pad(to)}.batch`);
+    }
+    async putSnapshot(sessionId, to, body, context) {
+        await this.#write(sessionId, ["snapshots"], `${pad(to)}.batch`, body, context);
+    }
+    async foldBatches(sessionId, afters, context) {
+        for (const after of afters) {
+            const slot = await this.#slot(sessionId, after, context);
+            if (slot === undefined || slot.folded)
+                continue;
+            const folded = { ...slot, folded: true };
+            await this.#write(sessionId, ["slots"], `${pad(after)}.json`, once(new TextEncoder().encode(JSON.stringify(folded))), context);
+            const body = await this.#path(context, sessionId, "batches", `${pad(after)}.batch`);
+            unwrap(await this.#fs.remove(body, { force: true }, context));
+        }
+    }
+    async deleteSnapshots(sessionId, snapshots, context) {
+        for (const to of snapshots) {
+            const path = await this.#path(context, sessionId, "snapshots", `${pad(to)}.batch`);
+            unwrap(await this.#fs.remove(path, { force: true }, context));
+        }
+    }
+    async list(sessionId, context) {
+        const batches = [];
+        for (const name of await this.#names(context, sessionId, "slots")) {
+            const match = SLOT_NAME.exec(name);
+            if (match === null)
+                continue;
+            const slot = await this.#slot(sessionId, Number(match[1]), context);
+            if (slot !== undefined)
+                batches.push(slot);
+        }
+        const snapshots = [];
+        for (const name of await this.#names(context, sessionId, "snapshots")) {
+            const match = SNAPSHOT_NAME.exec(name);
+            if (match !== null)
+                snapshots.push(Number(match[1]));
+        }
+        return { batches, snapshots };
+    }
+    /** Every session, every time: a directory keeps no change order. */
+    async sessions(_cursor, context) {
+        const result = await this.#fs.listDir(this.#root, context);
+        const names = isNotFound(result)
+            ? []
+            : unwrap(result)
+                .filter((info) => info.kind === "directory" && SESSION_ID.test(info.name))
+                .map((info) => info.name)
+                .sort();
+        const sessions = [];
+        for (const id of names) {
+            sessions.push({
+                id,
+                head: remoteHead(await this.list(id, context)),
+                meta: await this.getMeta(id, context),
+            });
+        }
+        return { sessions, cursor: "", more: false };
+    }
+    async putMeta(sessionId, meta, context) {
+        await this.#write(sessionId, [], "meta.json", once(new TextEncoder().encode(JSON.stringify(meta))), context);
+    }
+    async getMeta(sessionId, context) {
+        const bytes = await this.#read(context, sessionId, "meta.json");
+        return bytes === undefined ? undefined : JSON.parse(new TextDecoder().decode(bytes));
+    }
+    async #slot(sessionId, after, context) {
+        const bytes = await this.#read(context, sessionId, "slots", `${pad(after)}.json`);
+        return bytes === undefined ? undefined : JSON.parse(new TextDecoder().decode(bytes));
+    }
+    async #names(context, sessionId, ...parts) {
+        const result = await this.#fs.listDir(await this.#path(context, sessionId, ...parts), context);
+        if (isNotFound(result))
+            return [];
+        return unwrap(result).map((info) => info.name);
+    }
+    async #read(context, sessionId, ...parts) {
+        const result = await this.#fs.readBinaryFile(await this.#path(context, sessionId, ...parts), context);
+        if (isNotFound(result))
+            return undefined;
+        return unwrap(result);
+    }
+    /** A body streamed back from its file, a chunk at a time; undefined when the file is missing. */
+    async #stream(context, sessionId, ...parts) {
+        const opened = await this.#fs.openBinaryReader(await this.#path(context, sessionId, ...parts), undefined, context);
+        if (isNotFound(opened))
+            return undefined;
+        const reader = unwrap(opened);
+        return (async function* () {
+            try {
+                for (let offset = 0;;) {
+                    const chunk = unwrap(await reader.read(offset, READ_CHUNK, context));
+                    if (chunk.length === 0)
+                        return;
+                    offset += chunk.length;
+                    yield chunk;
+                }
+            }
+            finally {
+                await reader.close(context);
+            }
+        })();
+    }
+    /**
+     * Write a body through a temporary file and a rename, so a reader never sees half a file; the body is appended chunk
+     * by chunk as it streams.
+     */
+    async #write(sessionId, directory, name, body, context) {
+        unwrap(await this.#fs.createDir(await this.#path(context, sessionId, ...directory), { recursive: true }, context));
+        const path = await this.#path(context, sessionId, ...directory, name);
+        const temporary = await this.#path(context, sessionId, ...directory, `${name}.tmp`);
+        unwrap(await this.#fs.writeFile(temporary, new Uint8Array(), context));
+        try {
+            for await (const chunk of body)
+                unwrap(await this.#fs.appendFile(temporary, chunk, context));
+        }
+        catch (error) {
+            await this.#fs.remove(temporary, { force: true }, context);
+            throw error;
+        }
+        unwrap(await this.#fs.renameFile(temporary, path, context));
+    }
+    async #path(context, sessionId, ...parts) {
+        return unwrap(await this.#fs.joinPath([this.#root, checkSessionId(sessionId), ...parts], context));
+    }
+}
+//# sourceMappingURL=filesystem.js.map

package/dist/sync/filesystem.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"filesystem.js","sourceRoot":"","sources":["../../src/sync/filesystem.ts"],"names":[],"mappings":"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","sourcesContent":["import type { Context } from \"../context/index.ts\";\nimport type { SyncBody } from \"./batch.ts\";\nimport { isNotFound, type SyncFileSystem, unwrap } from \"./files.ts\";\nimport {\n\ttype BatchInfo,\n\ttype JsonObject,\n\ttype PutBatchResult,\n\ttype RemoteListing,\n\tremoteHead,\n\ttype Seq,\n\ttype SessionChanges,\n\ttype SessionSyncMaintenance,\n} from \"./remote.ts\";\n\nconst pad = (value: number): string => String(value).padStart(16, \"0\");\n/** How much of a body is read from its file at a time. */\nconst READ_CHUNK = 256 * 1024;\n\n/** One buffer as a body. */\nasync function* once(bytes: Uint8Array): SyncBody {\n\tyield bytes;\n}\nconst SLOT_NAME = /^(\\d{16})\\.json$/;\nconst SNAPSHOT_NAME = /^(\\d{16})\\.batch$/;\nconst SESSION_ID = /^[A-Za-z0-9_-][A-Za-z0-9._-]*$/;\n\n/** A session ID names a file or directory: refuse anything that could leave the root. */\nexport function checkSessionId(sessionId: string): string {\n\tif (!SESSION_ID.test(sessionId)) throw new Error(`Invalid session ID for a sync directory: ${sessionId}`);\n\treturn sessionId;\n}\n\n/**\n * A remote store in a directory, laid out as the real remote is: per session, one slot per batch start, holding where\n * the batch ends and which device created it, and snapshots named by their end. As the real remote, it creates a slot\n * only where the history ends. Creating a slot is check-then-write,\n * without the atomicity of the real remote across processes: for development and tests, with one process writing.\n *\n * ```text\n * {root}/{session}/slots/{after}.json     { after, to, device, archive?, folded? }, written once\n * {root}/{session}/batches/{after}.batch  the commits (or an archive), until folded\n * {root}/{session}/snapshots/{to}.batch   a store archive\n * {root}/{session}/meta.json             the host's description, last write wins\n * ```\n */\nexport class FileSystemSyncRemote implements SessionSyncMaintenance {\n\treadonly #fs: SyncFileSystem;\n\treadonly #root: string;\n\n\tconstructor(fs: SyncFileSystem, root: string) {\n\t\tthis.#fs = fs;\n\t\tthis.#root = root;\n\t}\n\n\tasync putBatch(\n\t\tsessionId: string,\n\t\tafter: Seq,\n\t\tto: Seq,\n\t\tdevice: string,\n\t\tbody: SyncBody,\n\t\tcontext: Context,\n\t\toptions: { readonly archive?: boolean } = {},\n\t): Promise<PutBatchResult> {\n\t\tconst existing = await this.#slot(sessionId, after, context);\n\t\tif (existing !== undefined) return { type: \"exists\", to: existing.to, device: existing.device };\n\t\tconst head = remoteHead(await this.list(sessionId, context));\n\t\tif (after !== head) return { type: \"not_head\", head };\n\t\tawait this.#write(sessionId, [\"batches\"], `${pad(after)}.batch`, body, context);\n\t\t// The slot is written last: it is what makes the batch exist.\n\t\tconst slot: BatchInfo = { after, to, device, ...(options.archive === true ? { archive: true as const } : {}) };\n\t\tawait this.#write(\n\t\t\tsessionId,\n\t\t\t[\"slots\"],\n\t\t\t`${pad(after)}.json`,\n\t\t\tonce(new TextEncoder().encode(JSON.stringify(slot))),\n\t\t\tcontext,\n\t\t);\n\t\treturn { type: \"created\" };\n\t}\n\n\tasync getBatch(sessionId: string, after: Seq, context: Context): Promise<SyncBody | undefined> {\n\t\tconst slot = await this.#slot(sessionId, after, context);\n\t\tif (slot === undefined || slot.folded) return undefined;\n\t\treturn this.#stream(context, sessionId, \"batches\", `${pad(after)}.batch`);\n\t}\n\n\tgetSnapshot(sessionId: string, to: Seq, context: Context): Promise<SyncBody | undefined> {\n\t\treturn this.#stream(context, sessionId, \"snapshots\", `${pad(to)}.batch`);\n\t}\n\n\tasync putSnapshot(sessionId: string, to: Seq, body: SyncBody, context: Context): Promise<void> {\n\t\tawait this.#write(sessionId, [\"snapshots\"], `${pad(to)}.batch`, body, context);\n\t}\n\n\tasync foldBatches(sessionId: string, afters: readonly Seq[], context: Context): Promise<void> {\n\t\tfor (const after of afters) {\n\t\t\tconst slot = await this.#slot(sessionId, after, context);\n\t\t\tif (slot === undefined || slot.folded) continue;\n\t\t\tconst folded: BatchInfo = { ...slot, folded: true };\n\t\t\tawait this.#write(\n\t\t\t\tsessionId,\n\t\t\t\t[\"slots\"],\n\t\t\t\t`${pad(after)}.json`,\n\t\t\t\tonce(new TextEncoder().encode(JSON.stringify(folded))),\n\t\t\t\tcontext,\n\t\t\t);\n\t\t\tconst body = await this.#path(context, sessionId, \"batches\", `${pad(after)}.batch`);\n\t\t\tunwrap(await this.#fs.remove(body, { force: true }, context));\n\t\t}\n\t}\n\n\tasync deleteSnapshots(sessionId: string, snapshots: readonly Seq[], context: Context): Promise<void> {\n\t\tfor (const to of snapshots) {\n\t\t\tconst path = await this.#path(context, sessionId, \"snapshots\", `${pad(to)}.batch`);\n\t\t\tunwrap(await this.#fs.remove(path, { force: true }, context));\n\t\t}\n\t}\n\n\tasync list(sessionId: string, context: Context): Promise<RemoteListing> {\n\t\tconst batches: BatchInfo[] = [];\n\t\tfor (const name of await this.#names(context, sessionId, \"slots\")) {\n\t\t\tconst match = SLOT_NAME.exec(name);\n\t\t\tif (match === null) continue;\n\t\t\tconst slot = await this.#slot(sessionId, Number(match[1]), context);\n\t\t\tif (slot !== undefined) batches.push(slot);\n\t\t}\n\t\tconst snapshots: Seq[] = [];\n\t\tfor (const name of await this.#names(context, sessionId, \"snapshots\")) {\n\t\t\tconst match = SNAPSHOT_NAME.exec(name);\n\t\t\tif (match !== null) snapshots.push(Number(match[1]));\n\t\t}\n\t\treturn { batches, snapshots };\n\t}\n\n\t/** Every session, every time: a directory keeps no change order. */\n\tasync sessions(_cursor: string | undefined, context: Context): Promise<SessionChanges> {\n\t\tconst result = await this.#fs.listDir(this.#root, context);\n\t\tconst names = isNotFound(result)\n\t\t\t? []\n\t\t\t: unwrap(result)\n\t\t\t\t\t.filter((info) => info.kind === \"directory\" && SESSION_ID.test(info.name))\n\t\t\t\t\t.map((info) => info.name)\n\t\t\t\t\t.sort();\n\t\tconst sessions = [];\n\t\tfor (const id of names) {\n\t\t\tsessions.push({\n\t\t\t\tid,\n\t\t\t\thead: remoteHead(await this.list(id, context)),\n\t\t\t\tmeta: await this.getMeta(id, context),\n\t\t\t});\n\t\t}\n\t\treturn { sessions, cursor: \"\", more: false };\n\t}\n\n\tasync putMeta(sessionId: string, meta: JsonObject, context: Context): Promise<void> {\n\t\tawait this.#write(sessionId, [], \"meta.json\", once(new TextEncoder().encode(JSON.stringify(meta))), context);\n\t}\n\n\tasync getMeta(sessionId: string, context: Context): Promise<JsonObject | undefined> {\n\t\tconst bytes = await this.#read(context, sessionId, \"meta.json\");\n\t\treturn bytes === undefined ? undefined : (JSON.parse(new TextDecoder().decode(bytes)) as JsonObject);\n\t}\n\n\tasync #slot(sessionId: string, after: Seq, context: Context): Promise<BatchInfo | undefined> {\n\t\tconst bytes = await this.#read(context, sessionId, \"slots\", `${pad(after)}.json`);\n\t\treturn bytes === undefined ? undefined : (JSON.parse(new TextDecoder().decode(bytes)) as BatchInfo);\n\t}\n\n\tasync #names(context: Context, sessionId: string, ...parts: string[]): Promise<string[]> {\n\t\tconst result = await this.#fs.listDir(await this.#path(context, sessionId, ...parts), context);\n\t\tif (isNotFound(result)) return [];\n\t\treturn unwrap(result).map((info) => info.name);\n\t}\n\n\tasync #read(context: Context, sessionId: string, ...parts: string[]): Promise<Uint8Array | undefined> {\n\t\tconst result = await this.#fs.readBinaryFile(await this.#path(context, sessionId, ...parts), context);\n\t\tif (isNotFound(result)) return undefined;\n\t\treturn unwrap(result);\n\t}\n\n\t/** A body streamed back from its file, a chunk at a time; undefined when the file is missing. */\n\tasync #stream(context: Context, sessionId: string, ...parts: string[]): Promise<SyncBody | undefined> {\n\t\tconst opened = await this.#fs.openBinaryReader(\n\t\t\tawait this.#path(context, sessionId, ...parts),\n\t\t\tundefined,\n\t\t\tcontext,\n\t\t);\n\t\tif (isNotFound(opened)) return undefined;\n\t\tconst reader = unwrap(opened);\n\t\treturn (async function* () {\n\t\t\ttry {\n\t\t\t\tfor (let offset = 0; ; ) {\n\t\t\t\t\tconst chunk = unwrap(await reader.read(offset, READ_CHUNK, context));\n\t\t\t\t\tif (chunk.length === 0) return;\n\t\t\t\t\toffset += chunk.length;\n\t\t\t\t\tyield chunk;\n\t\t\t\t}\n\t\t\t} finally {\n\t\t\t\tawait reader.close(context);\n\t\t\t}\n\t\t})();\n\t}\n\n\t/**\n\t * Write a body through a temporary file and a rename, so a reader never sees half a file; the body is appended chunk\n\t * by chunk as it streams.\n\t */\n\tasync #write(\n\t\tsessionId: string,\n\t\tdirectory: readonly string[],\n\t\tname: string,\n\t\tbody: SyncBody,\n\t\tcontext: Context,\n\t): Promise<void> {\n\t\tunwrap(\n\t\t\tawait this.#fs.createDir(await this.#path(context, sessionId, ...directory), { recursive: true }, context),\n\t\t);\n\t\tconst path = await this.#path(context, sessionId, ...directory, name);\n\t\tconst temporary = await this.#path(context, sessionId, ...directory, `${name}.tmp`);\n\t\tunwrap(await this.#fs.writeFile(temporary, new Uint8Array(), context));\n\t\ttry {\n\t\t\tfor await (const chunk of body) unwrap(await this.#fs.appendFile(temporary, chunk, context));\n\t\t} catch (error) {\n\t\t\tawait this.#fs.remove(temporary, { force: true }, context);\n\t\t\tthrow error;\n\t\t}\n\t\tunwrap(await this.#fs.renameFile(temporary, path, context));\n\t}\n\n\tasync #path(context: Context, sessionId: string, ...parts: string[]): Promise<string> {\n\t\treturn unwrap(await this.#fs.joinPath([this.#root, checkSessionId(sessionId), ...parts], context));\n\t}\n}\n"]}

package/dist/sync/index.d.ts

@@ -0,0 +1,8 @@
+export { decodeBatch, decodeBatchLines, decodeSnapshot, encodeBatch, encodeSnapshot, type SyncBody, } from "./batch.ts";
+export { APPLY_BYTES, BATCH_BYTES, FlushScheduler, type FlushSchedulerOptions, foldSession, type LocalCopy, OutboxUnavailableError, pullSession, readOutbox, type SyncState, type SyncStateStore, storeHead, UnsyncedCommitsError, type UploadResult, uploadSession, } from "./client.ts";
+export type { FileResult, SyncFileInfo, SyncFileReader, SyncFileSystem } from "./files.ts";
+export { checkSessionId, FileSystemSyncRemote } from "./filesystem.ts";
+export { decodeLogLine, encodeLogLine, LOG_VERSION, LogFormatError } from "./lines.ts";
+export { type BatchInfo, HistoryUnavailableError, type JsonObject, LOG_START, type PutBatchResult, type RemoteHistory, type RemoteListing, remoteHead, remoteHistory, type Seq, type SessionChanges, type SessionSummary, type SessionSyncMaintenance, type SessionSyncStore, } from "./remote.ts";
+export { FileSyncStateStore } from "./state.ts";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/sync/index.ts"],"names":[],"mappings":"AAGA,OAAO,EACN,WAAW,EACX,gBAAgB,EAChB,cAAc,EACd,WAAW,EACX,cAAc,EACd,KAAK,QAAQ,GACb,MAAM,YAAY,CAAC;AACpB,OAAO,EACN,WAAW,EACX,WAAW,EACX,cAAc,EACd,KAAK,qBAAqB,EAC1B,WAAW,EACX,KAAK,SAAS,EACd,sBAAsB,EACtB,WAAW,EACX,UAAU,EACV,KAAK,SAAS,EACd,KAAK,cAAc,EACnB,SAAS,EACT,oBAAoB,EACpB,KAAK,YAAY,EACjB,aAAa,GACb,MAAM,aAAa,CAAC;AACrB,YAAY,EAAE,UAAU,EAAE,YAAY,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAC3F,OAAO,EAAE,cAAc,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AACvE,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AACvF,OAAO,EACN,KAAK,SAAS,EACd,uBAAuB,EACvB,KAAK,UAAU,EACf,SAAS,EACT,KAAK,cAAc,EACnB,KAAK,aAAa,EAClB,KAAK,aAAa,EAClB,UAAU,EACV,aAAa,EACb,KAAK,GAAG,EACR,KAAK,cAAc,EACnB,KAAK,cAAc,EACnB,KAAK,sBAAsB,EAC3B,KAAK,gBAAgB,GACrB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC"}

package/dist/sync/index.js

@@ -0,0 +1,9 @@
+// Session sync over a store's outbox (`@earendil-works/chord/sync`, experimental). Portable: the remote and the host's
+// sync state are interfaces, and the directory-backed ones take their file operations (`SyncFileSystem`).
+export { decodeBatch, decodeBatchLines, decodeSnapshot, encodeBatch, encodeSnapshot, } from "./batch.js";
+export { APPLY_BYTES, BATCH_BYTES, FlushScheduler, foldSession, OutboxUnavailableError, pullSession, readOutbox, storeHead, UnsyncedCommitsError, uploadSession, } from "./client.js";
+export { checkSessionId, FileSystemSyncRemote } from "./filesystem.js";
+export { decodeLogLine, encodeLogLine, LOG_VERSION, LogFormatError } from "./lines.js";
+export { HistoryUnavailableError, LOG_START, remoteHead, remoteHistory, } from "./remote.js";
+export { FileSyncStateStore } from "./state.js";
+//# sourceMappingURL=index.js.map

package/dist/sync/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/sync/index.ts"],"names":[],"mappings":"AAAA,uHAAuH;AACvH,0GAA0G;AAE1G,OAAO,EACN,WAAW,EACX,gBAAgB,EAChB,cAAc,EACd,WAAW,EACX,cAAc,GAEd,MAAM,YAAY,CAAC;AACpB,OAAO,EACN,WAAW,EACX,WAAW,EACX,cAAc,EAEd,WAAW,EAEX,sBAAsB,EACtB,WAAW,EACX,UAAU,EAGV,SAAS,EACT,oBAAoB,EAEpB,aAAa,GACb,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,cAAc,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AACvE,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AACvF,OAAO,EAEN,uBAAuB,EAEvB,SAAS,EAIT,UAAU,EACV,aAAa,GAMb,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC","sourcesContent":["// Session sync over a store's outbox (`@earendil-works/chord/sync`, experimental). Portable: the remote and the host's\n// sync state are interfaces, and the directory-backed ones take their file operations (`SyncFileSystem`).\n\nexport {\n\tdecodeBatch,\n\tdecodeBatchLines,\n\tdecodeSnapshot,\n\tencodeBatch,\n\tencodeSnapshot,\n\ttype SyncBody,\n} from \"./batch.ts\";\nexport {\n\tAPPLY_BYTES,\n\tBATCH_BYTES,\n\tFlushScheduler,\n\ttype FlushSchedulerOptions,\n\tfoldSession,\n\ttype LocalCopy,\n\tOutboxUnavailableError,\n\tpullSession,\n\treadOutbox,\n\ttype SyncState,\n\ttype SyncStateStore,\n\tstoreHead,\n\tUnsyncedCommitsError,\n\ttype UploadResult,\n\tuploadSession,\n} from \"./client.ts\";\nexport type { FileResult, SyncFileInfo, SyncFileReader, SyncFileSystem } from \"./files.ts\";\nexport { checkSessionId, FileSystemSyncRemote } from \"./filesystem.ts\";\nexport { decodeLogLine, encodeLogLine, LOG_VERSION, LogFormatError } from \"./lines.ts\";\nexport {\n\ttype BatchInfo,\n\tHistoryUnavailableError,\n\ttype JsonObject,\n\tLOG_START,\n\ttype PutBatchResult,\n\ttype RemoteHistory,\n\ttype RemoteListing,\n\tremoteHead,\n\tremoteHistory,\n\ttype Seq,\n\ttype SessionChanges,\n\ttype SessionSummary,\n\ttype SessionSyncMaintenance,\n\ttype SessionSyncStore,\n} from \"./remote.ts\";\nexport { FileSyncStateStore } from \"./state.ts\";\n"]}

package/dist/sync/lines.d.ts

@@ -0,0 +1,18 @@
+import type { OutboxCommit } from "../store/outbox.ts";
+/**
+ * Version of the line envelope. It changes when the envelope changes; the writes inside carry the store outbox's own
+ * `format`, which `applyBatch()` checks.
+ */
+export declare const LOG_VERSION = 2;
+export declare class LogFormatError extends Error {
+    constructor(message: string, options?: ErrorOptions);
+}
+/** One outbox commit as a JSON line, terminated by a newline. */
+export declare function encodeLogLine(commit: OutboxCommit): string;
+/**
+ * One line (without its newline) as an outbox commit; `number` names the line in errors. A line of an unknown version
+ * is an error: an older pi must not apply writes it does not understand. The writes themselves are checked by
+ * `applyBatch()`, a trust boundary.
+ */
+export declare function decodeLogLine(text: string, number: number): OutboxCommit;
+//# sourceMappingURL=lines.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"lines.d.ts","sourceRoot":"","sources":["../../src/sync/lines.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAEvD;;;GAGG;AACH,eAAO,MAAM,WAAW,IAAI,CAAC;AAS7B,qBAAa,cAAe,SAAQ,KAAK;IACxC,YAAY,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY,EAGlD;CACD;AAED,iEAAiE;AACjE,wBAAgB,aAAa,CAAC,MAAM,EAAE,YAAY,GAAG,MAAM,CAG1D;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,YAAY,CAoBxE"}

package/dist/sync/lines.js

@@ -0,0 +1,46 @@
+/**
+ * Version of the line envelope. It changes when the envelope changes; the writes inside carry the store outbox's own
+ * `format`, which `applyBatch()` checks.
+ */
+export const LOG_VERSION = 2;
+export class LogFormatError extends Error {
+    constructor(message, options) {
+        super(message, options);
+        this.name = "LogFormatError";
+    }
+}
+/** One outbox commit as a JSON line, terminated by a newline. */
+export function encodeLogLine(commit) {
+    const line = { v: LOG_VERSION, seq: commit.seq, nextId: commit.nextId, writes: commit.writes };
+    return `${JSON.stringify(line)}\n`;
+}
+/**
+ * One line (without its newline) as an outbox commit; `number` names the line in errors. A line of an unknown version
+ * is an error: an older pi must not apply writes it does not understand. The writes themselves are checked by
+ * `applyBatch()`, a trust boundary.
+ */
+export function decodeLogLine(text, number) {
+    let value;
+    try {
+        value = JSON.parse(text);
+    }
+    catch (error) {
+        throw new LogFormatError(`Log line ${number} is not JSON`, { cause: error });
+    }
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        throw new LogFormatError(`Log line ${number} is not an object`);
+    }
+    const line = value;
+    if (line.v !== LOG_VERSION)
+        throw new LogFormatError(`Log line ${number} has unknown version ${String(line.v)}`);
+    if (typeof line.seq !== "number" || !Number.isSafeInteger(line.seq) || line.seq < 1) {
+        throw new LogFormatError(`Log line ${number} has no valid sequence`);
+    }
+    if (typeof line.nextId !== "number" || !Number.isSafeInteger(line.nextId)) {
+        throw new LogFormatError(`Log line ${number} has no valid next id`);
+    }
+    if (!Array.isArray(line.writes))
+        throw new LogFormatError(`Log line ${number} has no writes`);
+    return { seq: line.seq, nextId: line.nextId, writes: line.writes };
+}
+//# sourceMappingURL=lines.js.map

package/dist/sync/lines.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lines.js","sourceRoot":"","sources":["../../src/sync/lines.ts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,CAAC;AAS7B,MAAM,OAAO,cAAe,SAAQ,KAAK;IACxC,YAAY,OAAe,EAAE,OAAsB;QAClD,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACxB,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAC;IAC9B,CAAC;CACD;AAED,iEAAiE;AACjE,MAAM,UAAU,aAAa,CAAC,MAAoB;IACjD,MAAM,IAAI,GAAY,EAAE,CAAC,EAAE,WAAW,EAAE,GAAG,EAAE,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC;IACxG,OAAO,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC;AACpC,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,aAAa,CAAC,IAAY,EAAE,MAAc;IACzD,IAAI,KAAc,CAAC;IACnB,IAAI,CAAC;QACJ,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC1B,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QAChB,MAAM,IAAI,cAAc,CAAC,YAAY,MAAM,cAAc,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC;IAC9E,CAAC;IACD,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACzE,MAAM,IAAI,cAAc,CAAC,YAAY,MAAM,mBAAmB,CAAC,CAAC;IACjE,CAAC;IACD,MAAM,IAAI,GAAG,KAAoD,CAAC;IAClE,IAAI,IAAI,CAAC,CAAC,KAAK,WAAW;QAAE,MAAM,IAAI,cAAc,CAAC,YAAY,MAAM,wBAAwB,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;IACjH,IAAI,OAAO,IAAI,CAAC,GAAG,KAAK,QAAQ,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,IAAI,CAAC,GAAG,GAAG,CAAC,EAAE,CAAC;QACrF,MAAM,IAAI,cAAc,CAAC,YAAY,MAAM,wBAAwB,CAAC,CAAC;IACtE,CAAC;IACD,IAAI,OAAO,IAAI,CAAC,MAAM,KAAK,QAAQ,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC;QAC3E,MAAM,IAAI,cAAc,CAAC,YAAY,MAAM,uBAAuB,CAAC,CAAC;IACrE,CAAC;IACD,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC;QAAE,MAAM,IAAI,cAAc,CAAC,YAAY,MAAM,gBAAgB,CAAC,CAAC;IAC9F,OAAO,EAAE,GAAG,EAAE,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,CAAC;AACpE,CAAC","sourcesContent":["import type { OutboxCommit } from \"../store/outbox.ts\";\n\n/**\n * Version of the line envelope. It changes when the envelope changes; the writes inside carry the store outbox's own\n * `format`, which `applyBatch()` checks.\n */\nexport const LOG_VERSION = 2;\n\ntype LogLine = {\n\treadonly v: typeof LOG_VERSION;\n\treadonly seq: number;\n\treadonly nextId: number;\n\treadonly writes: OutboxCommit[\"writes\"];\n};\n\nexport class LogFormatError extends Error {\n\tconstructor(message: string, options?: ErrorOptions) {\n\t\tsuper(message, options);\n\t\tthis.name = \"LogFormatError\";\n\t}\n}\n\n/** One outbox commit as a JSON line, terminated by a newline. */\nexport function encodeLogLine(commit: OutboxCommit): string {\n\tconst line: LogLine = { v: LOG_VERSION, seq: commit.seq, nextId: commit.nextId, writes: commit.writes };\n\treturn `${JSON.stringify(line)}\\n`;\n}\n\n/**\n * One line (without its newline) as an outbox commit; `number` names the line in errors. A line of an unknown version\n * is an error: an older pi must not apply writes it does not understand. The writes themselves are checked by\n * `applyBatch()`, a trust boundary.\n */\nexport function decodeLogLine(text: string, number: number): OutboxCommit {\n\tlet value: unknown;\n\ttry {\n\t\tvalue = JSON.parse(text);\n\t} catch (error) {\n\t\tthrow new LogFormatError(`Log line ${number} is not JSON`, { cause: error });\n\t}\n\tif (typeof value !== \"object\" || value === null || Array.isArray(value)) {\n\t\tthrow new LogFormatError(`Log line ${number} is not an object`);\n\t}\n\tconst line = value as Partial<LogLine> & { readonly v?: unknown };\n\tif (line.v !== LOG_VERSION) throw new LogFormatError(`Log line ${number} has unknown version ${String(line.v)}`);\n\tif (typeof line.seq !== \"number\" || !Number.isSafeInteger(line.seq) || line.seq < 1) {\n\t\tthrow new LogFormatError(`Log line ${number} has no valid sequence`);\n\t}\n\tif (typeof line.nextId !== \"number\" || !Number.isSafeInteger(line.nextId)) {\n\t\tthrow new LogFormatError(`Log line ${number} has no valid next id`);\n\t}\n\tif (!Array.isArray(line.writes)) throw new LogFormatError(`Log line ${number} has no writes`);\n\treturn { seq: line.seq, nextId: line.nextId, writes: line.writes };\n}\n"]}

package/dist/sync/remote.d.ts

@@ -0,0 +1,130 @@
+import type { Context } from "../context/index.ts";
+import type { SyncBody } from "./batch.ts";
+/** A store's commit sequence (`store.lastSeq`, an outbox commit's `seq`); 0 is before every commit. */
+export type Seq = number;
+/** A JSON object: a session's description on the remote. */
+export type JsonObject = {
+    [key: string]: unknown;
+};
+/** The sequence before every commit: a store without commits is at it. */
+export declare const LOG_START: Seq;
+/**
+ * A slot of a session's remote history: the batch of outbox commits after `after`, up to `to`, uploaded by `device`. A
+ * store creates each slot once and never replaces it, so the device whose upload creates it continues the session from
+ * `after`, and a device that finds it taken by another one holds a different history.
+ */
+export type BatchInfo = {
+    readonly after: Seq;
+    readonly to: Seq;
+    readonly device: string;
+    /** Folding dropped its commits into a snapshot; the slot stays taken. */
+    readonly folded?: true;
+    /**
+     * The body is a store archive at `to` instead of commits: the first upload of a session whose outbox does not reach
+     * back to its first commit. Only the slot after 0 can be one.
+     */
+    readonly archive?: true;
+};
+/** What a remote store holds for one session. A snapshot is a store archive at its sequence, folded from batches. */
+export type RemoteListing = {
+    readonly batches: readonly BatchInfo[];
+    readonly snapshots: readonly Seq[];
+};
+export type PutBatchResult = {
+    readonly type: "created";
+}
+/** The slot is taken; by this device, after an upload whose response was lost, or by another one. */
+ | {
+    readonly type: "exists";
+    readonly to: Seq;
+    readonly device: string;
+}
+/**
+ * No slot starts at `after`, and the history does not end there: a slot there would branch the chain inside a batch
+ * or leave a gap. The uploader's history is not the remote's from `after` on.
+ */
+ | {
+    readonly type: "not_head";
+    readonly head: Seq;
+}
+/**
+ * The upload's `epoch` is not the session's current one: another device was given the right to write the session
+ * since this one was. Who grants it, and when, is the remote's (RFC 0074's single writer); Chord only reports it.
+ */
+ | {
+    readonly type: "stale_epoch";
+    readonly epoch: number;
+};
+/** A session as the remote's listing describes it. */
+export type SessionSummary = {
+    readonly id: string;
+    /** Where its history ends; `LOG_START` for a session with a description and no history. */
+    readonly head: Seq;
+    readonly meta: JsonObject | undefined;
+};
+/** Sessions changed after a cursor, and the cursor to continue from. */
+export type SessionChanges = {
+    readonly sessions: readonly SessionSummary[];
+    /** Pass it to the next call; opaque. */
+    readonly cursor: string;
+    /** More changes follow right away: call again with `cursor`. */
+    readonly more: boolean;
+};
+/** The client's view of a remote store. Clients never delete or fold. */
+export interface SessionSyncStore {
+    /**
+     * Create the slot after `after` unless it exists or the history does not end at `after`. `body` is a stream read once;
+     * a remote that answers without reading it (`exists`, `not_head`) leaves it unread.
+     */
+    putBatch(sessionId: string, after: Seq, to: Seq, device: string, body: SyncBody, context: Context, options?: {
+        readonly archive?: boolean;
+        /** The writer's epoch: a remote that issues epochs refuses a stale one (`stale_epoch`); others ignore it. */
+        readonly epoch?: number;
+    }): Promise<PutBatchResult>;
+    /** A batch's body; `undefined` when its slot is folded or absent. */
+    getBatch(sessionId: string, after: Seq, context: Context): Promise<SyncBody | undefined>;
+    getSnapshot(sessionId: string, to: Seq, context: Context): Promise<SyncBody | undefined>;
+    list(sessionId: string, context: Context): Promise<RemoteListing>;
+    /**
+     * The sessions changed after `cursor` (all of them without one). A remote may also list sessions that did not change,
+     * so a caller compares what it gets with what it has.
+     */
+    sessions(cursor: string | undefined, context: Context): Promise<SessionChanges>;
+    /**
+     * The host's description of a session (title, location, which device started it), outside its history: the last
+     * write wins, and it may be ahead of or behind the batches.
+     */
+    putMeta(sessionId: string, meta: JsonObject, context: Context): Promise<void>;
+    getMeta(sessionId: string, context: Context): Promise<JsonObject | undefined>;
+}
+/** The remote's own side: folding history into snapshots, which clients never do. */
+export interface SessionSyncMaintenance extends SessionSyncStore {
+    putSnapshot(sessionId: string, to: Seq, body: SyncBody, context: Context): Promise<void>;
+    /** Drop the bodies of these slots, keeping the slots taken so nobody can create them again. */
+    foldBatches(sessionId: string, afters: readonly Seq[], context: Context): Promise<void>;
+    deleteSnapshots(sessionId: string, snapshots: readonly Seq[], context: Context): Promise<void>;
+}
+/** What a copy applies to reach the remote's head. */
+export type RemoteHistory = {
+    /** The snapshot a restore starts from. */
+    readonly snapshot?: Seq;
+    /**
+     * The batches to apply in order. The first may start before the copy's head, when a pull stopped inside it; its
+     * commits at or below the head are skipped.
+     */
+    readonly batches: readonly BatchInfo[];
+    /** Where applying them ends. */
+    readonly head: Seq;
+};
+/** The remote's history no longer continues from a copy's head, after folding: restore into a fresh store. */
+export declare class HistoryUnavailableError extends Error {
+    constructor(head: Seq);
+}
+/**
+ * The history a copy at `from` applies, or a restore without `from`. Slots are created once, so at most one batch
+ * starts at each sequence and the history is a single chain.
+ */
+export declare function remoteHistory(listing: RemoteListing, from?: Seq): RemoteHistory;
+/** The furthest head the remote's history reaches. */
+export declare function remoteHead(listing: RemoteListing): Seq;
+//# sourceMappingURL=remote.d.ts.map

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

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

package/dist/sync/remote.js

@@ -0,0 +1,46 @@
+/** The sequence before every commit: a store without commits is at it. */
+export const LOG_START = 0;
+/** The remote's history no longer continues from a copy's head, after folding: restore into a fresh store. */
+export class HistoryUnavailableError extends Error {
+    constructor(head) {
+        super(`The remote history does not continue from ${head}`);
+        this.name = "HistoryUnavailableError";
+    }
+}
+/**
+ * The history a copy at `from` applies, or a restore without `from`. Slots are created once, so at most one batch
+ * starts at each sequence and the history is a single chain.
+ */
+export function remoteHistory(listing, from) {
+    const chain = new Map(listing.batches.map((batch) => [batch.after, batch]));
+    let snapshot;
+    let at;
+    const batches = [];
+    if (from === undefined || from === LOG_START) {
+        snapshot = listing.snapshots.length === 0 ? undefined : Math.max(...listing.snapshots);
+        at = snapshot ?? LOG_START;
+    }
+    else {
+        at = from;
+        // A pull that stopped inside a batch finishes it; only one batch can contain the head.
+        const inside = listing.batches.find((batch) => batch.after < from && from < batch.to);
+        if (inside !== undefined) {
+            batches.push(inside);
+            at = inside.to;
+        }
+    }
+    for (let next = chain.get(at); next !== undefined; next = chain.get(at)) {
+        batches.push(next);
+        at = next.to;
+    }
+    return { ...(snapshot === undefined ? {} : { snapshot }), batches, head: at };
+}
+/** The furthest head the remote's history reaches. */
+export function remoteHead(listing) {
+    const chain = new Map(listing.batches.map((batch) => [batch.after, batch]));
+    let at = LOG_START;
+    for (let next = chain.get(at); next !== undefined; next = chain.get(at))
+        at = next.to;
+    return at;
+}
+//# sourceMappingURL=remote.js.map

package/dist/sync/remote.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"remote.js","sourceRoot":"","sources":["../../src/sync/remote.ts"],"names":[],"mappings":"AASA,0EAA0E;AAC1E,MAAM,CAAC,MAAM,SAAS,GAAQ,CAAC,CAAC;AAmHhC,8GAA8G;AAC9G,MAAM,OAAO,uBAAwB,SAAQ,KAAK;IACjD,YAAY,IAAS;QACpB,KAAK,CAAC,6CAA6C,IAAI,EAAE,CAAC,CAAC;QAC3D,IAAI,CAAC,IAAI,GAAG,yBAAyB,CAAC;IACvC,CAAC;CACD;AAED;;;GAGG;AACH,MAAM,UAAU,aAAa,CAAC,OAAsB,EAAE,IAAU;IAC/D,MAAM,KAAK,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC;IAC5E,IAAI,QAAyB,CAAC;IAC9B,IAAI,EAAO,CAAC;IACZ,MAAM,OAAO,GAAgB,EAAE,CAAC;IAChC,IAAI,IAAI,KAAK,SAAS,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;QAC9C,QAAQ,GAAG,OAAO,CAAC,SAAS,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAE,IAAI,CAAC,GAAG,CAAC,GAAG,OAAO,CAAC,SAAS,CAAS,CAAC;QAChG,EAAE,GAAG,QAAQ,IAAI,SAAS,CAAC;IAC5B,CAAC;SAAM,CAAC;QACP,EAAE,GAAG,IAAI,CAAC;QACV,uFAAuF;QACvF,MAAM,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,KAAK,GAAG,IAAI,IAAI,IAAI,GAAG,KAAK,CAAC,EAAE,CAAC,CAAC;QACtF,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;YAC1B,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;YACrB,EAAE,GAAG,MAAM,CAAC,EAAE,CAAC;QAChB,CAAC;IACF,CAAC;IACD,KAAK,IAAI,IAAI,GAAG,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,IAAI,KAAK,SAAS,EAAE,IAAI,GAAG,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,CAAC;QACzE,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACnB,EAAE,GAAG,IAAI,CAAC,EAAE,CAAC;IACd,CAAC;IACD,OAAO,EAAE,GAAG,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC;AAC/E,CAAC;AAED,sDAAsD;AACtD,MAAM,UAAU,UAAU,CAAC,OAAsB;IAChD,MAAM,KAAK,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC;IAC5E,IAAI,EAAE,GAAQ,SAAS,CAAC;IACxB,KAAK,IAAI,IAAI,GAAG,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,IAAI,KAAK,SAAS,EAAE,IAAI,GAAG,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC;QAAE,EAAE,GAAG,IAAI,CAAC,EAAE,CAAC;IACtF,OAAO,EAAE,CAAC;AACX,CAAC","sourcesContent":["import type { Context } from \"../context/index.ts\";\nimport type { SyncBody } from \"./batch.ts\";\n\n/** A store's commit sequence (`store.lastSeq`, an outbox commit's `seq`); 0 is before every commit. */\nexport type Seq = number;\n\n/** A JSON object: a session's description on the remote. */\nexport type JsonObject = { [key: string]: unknown };\n\n/** The sequence before every commit: a store without commits is at it. */\nexport const LOG_START: Seq = 0;\n\n/**\n * A slot of a session's remote history: the batch of outbox commits after `after`, up to `to`, uploaded by `device`. A\n * store creates each slot once and never replaces it, so the device whose upload creates it continues the session from\n * `after`, and a device that finds it taken by another one holds a different history.\n */\nexport type BatchInfo = {\n\treadonly after: Seq;\n\treadonly to: Seq;\n\treadonly device: string;\n\t/** Folding dropped its commits into a snapshot; the slot stays taken. */\n\treadonly folded?: true;\n\t/**\n\t * The body is a store archive at `to` instead of commits: the first upload of a session whose outbox does not reach\n\t * back to its first commit. Only the slot after 0 can be one.\n\t */\n\treadonly archive?: true;\n};\n\n/** What a remote store holds for one session. A snapshot is a store archive at its sequence, folded from batches. */\nexport type RemoteListing = {\n\treadonly batches: readonly BatchInfo[];\n\treadonly snapshots: readonly Seq[];\n};\n\nexport type PutBatchResult =\n\t| { readonly type: \"created\" }\n\t/** The slot is taken; by this device, after an upload whose response was lost, or by another one. */\n\t| { readonly type: \"exists\"; readonly to: Seq; readonly device: string }\n\t/**\n\t * No slot starts at `after`, and the history does not end there: a slot there would branch the chain inside a batch\n\t * or leave a gap. The uploader's history is not the remote's from `after` on.\n\t */\n\t| { readonly type: \"not_head\"; readonly head: Seq }\n\t/**\n\t * The upload's `epoch` is not the session's current one: another device was given the right to write the session\n\t * since this one was. Who grants it, and when, is the remote's (RFC 0074's single writer); Chord only reports it.\n\t */\n\t| { readonly type: \"stale_epoch\"; readonly epoch: number };\n\n/** A session as the remote's listing describes it. */\nexport type SessionSummary = {\n\treadonly id: string;\n\t/** Where its history ends; `LOG_START` for a session with a description and no history. */\n\treadonly head: Seq;\n\treadonly meta: JsonObject | undefined;\n};\n\n/** Sessions changed after a cursor, and the cursor to continue from. */\nexport type SessionChanges = {\n\treadonly sessions: readonly SessionSummary[];\n\t/** Pass it to the next call; opaque. */\n\treadonly cursor: string;\n\t/** More changes follow right away: call again with `cursor`. */\n\treadonly more: boolean;\n};\n\n/** The client's view of a remote store. Clients never delete or fold. */\nexport interface SessionSyncStore {\n\t/**\n\t * Create the slot after `after` unless it exists or the history does not end at `after`. `body` is a stream read once;\n\t * a remote that answers without reading it (`exists`, `not_head`) leaves it unread.\n\t */\n\tputBatch(\n\t\tsessionId: string,\n\t\tafter: Seq,\n\t\tto: Seq,\n\t\tdevice: string,\n\t\tbody: SyncBody,\n\t\tcontext: Context,\n\t\toptions?: {\n\t\t\treadonly archive?: boolean;\n\t\t\t/** The writer's epoch: a remote that issues epochs refuses a stale one (`stale_epoch`); others ignore it. */\n\t\t\treadonly epoch?: number;\n\t\t},\n\t): Promise<PutBatchResult>;\n\t/** A batch's body; `undefined` when its slot is folded or absent. */\n\tgetBatch(sessionId: string, after: Seq, context: Context): Promise<SyncBody | undefined>;\n\tgetSnapshot(sessionId: string, to: Seq, context: Context): Promise<SyncBody | undefined>;\n\tlist(sessionId: string, context: Context): Promise<RemoteListing>;\n\t/**\n\t * The sessions changed after `cursor` (all of them without one). A remote may also list sessions that did not change,\n\t * so a caller compares what it gets with what it has.\n\t */\n\tsessions(cursor: string | undefined, context: Context): Promise<SessionChanges>;\n\t/**\n\t * The host's description of a session (title, location, which device started it), outside its history: the last\n\t * write wins, and it may be ahead of or behind the batches.\n\t */\n\tputMeta(sessionId: string, meta: JsonObject, context: Context): Promise<void>;\n\tgetMeta(sessionId: string, context: Context): Promise<JsonObject | undefined>;\n}\n\n/** The remote's own side: folding history into snapshots, which clients never do. */\nexport interface SessionSyncMaintenance extends SessionSyncStore {\n\tputSnapshot(sessionId: string, to: Seq, body: SyncBody, context: Context): Promise<void>;\n\t/** Drop the bodies of these slots, keeping the slots taken so nobody can create them again. */\n\tfoldBatches(sessionId: string, afters: readonly Seq[], context: Context): Promise<void>;\n\tdeleteSnapshots(sessionId: string, snapshots: readonly Seq[], context: Context): Promise<void>;\n}\n\n/** What a copy applies to reach the remote's head. */\nexport type RemoteHistory = {\n\t/** The snapshot a restore starts from. */\n\treadonly snapshot?: Seq;\n\t/**\n\t * The batches to apply in order. The first may start before the copy's head, when a pull stopped inside it; its\n\t * commits at or below the head are skipped.\n\t */\n\treadonly batches: readonly BatchInfo[];\n\t/** Where applying them ends. */\n\treadonly head: Seq;\n};\n\n/** The remote's history no longer continues from a copy's head, after folding: restore into a fresh store. */\nexport class HistoryUnavailableError extends Error {\n\tconstructor(head: Seq) {\n\t\tsuper(`The remote history does not continue from ${head}`);\n\t\tthis.name = \"HistoryUnavailableError\";\n\t}\n}\n\n/**\n * The history a copy at `from` applies, or a restore without `from`. Slots are created once, so at most one batch\n * starts at each sequence and the history is a single chain.\n */\nexport function remoteHistory(listing: RemoteListing, from?: Seq): RemoteHistory {\n\tconst chain = new Map(listing.batches.map((batch) => [batch.after, batch]));\n\tlet snapshot: Seq | undefined;\n\tlet at: Seq;\n\tconst batches: BatchInfo[] = [];\n\tif (from === undefined || from === LOG_START) {\n\t\tsnapshot = listing.snapshots.length === 0 ? undefined : (Math.max(...listing.snapshots) as Seq);\n\t\tat = snapshot ?? LOG_START;\n\t} else {\n\t\tat = from;\n\t\t// A pull that stopped inside a batch finishes it; only one batch can contain the head.\n\t\tconst inside = listing.batches.find((batch) => batch.after < from && from < batch.to);\n\t\tif (inside !== undefined) {\n\t\t\tbatches.push(inside);\n\t\t\tat = inside.to;\n\t\t}\n\t}\n\tfor (let next = chain.get(at); next !== undefined; next = chain.get(at)) {\n\t\tbatches.push(next);\n\t\tat = next.to;\n\t}\n\treturn { ...(snapshot === undefined ? {} : { snapshot }), batches, head: at };\n}\n\n/** The furthest head the remote's history reaches. */\nexport function remoteHead(listing: RemoteListing): Seq {\n\tconst chain = new Map(listing.batches.map((batch) => [batch.after, batch]));\n\tlet at: Seq = LOG_START;\n\tfor (let next = chain.get(at); next !== undefined; next = chain.get(at)) at = next.to;\n\treturn at;\n}\n"]}

package/dist/sync/state.d.ts

@@ -0,0 +1,17 @@
+import type { Context } from "../context/index.ts";
+import type { SyncState, SyncStateStore } from "./client.ts";
+import { type SyncFileSystem } from "./files.ts";
+/**
+ * Sync state in a directory, one JSON file per session, replaced through a temporary file and a rename. Losing the
+ * directory loses nothing that matters: a copy without commits of its own takes the remote's head, and one with
+ * commits finds out by uploading.
+ */
+export declare class FileSyncStateStore implements SyncStateStore {
+    #private;
+    constructor(fs: SyncFileSystem, directory: string);
+    get(sessionId: string, context: Context): Promise<SyncState | undefined>;
+    set(sessionId: string, state: SyncState, context: Context): Promise<void>;
+    /** Forget a session, as when its copy is renamed or deleted. */
+    delete(sessionId: string, context: Context): Promise<void>;
+}
+//# sourceMappingURL=state.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"state.d.ts","sourceRoot":"","sources":["../../src/sync/state.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,KAAK,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC7D,OAAO,EAAc,KAAK,cAAc,EAAU,MAAM,YAAY,CAAC;AAIrE;;;;GAIG;AACH,qBAAa,kBAAmB,YAAW,cAAc;;IAIxD,YAAY,EAAE,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,EAGhD;IAEK,GAAG,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,SAAS,GAAG,SAAS,CAAC,CAQ7E;IAEK,GAAG,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAM9E;IAED,gEAAgE;IAC1D,MAAM,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAE/D;CAKD"}

package/dist/sync/state.js

@@ -0,0 +1,40 @@
+import { isNotFound, unwrap } from "./files.js";
+import { checkSessionId } from "./filesystem.js";
+/**
+ * Sync state in a directory, one JSON file per session, replaced through a temporary file and a rename. Losing the
+ * directory loses nothing that matters: a copy without commits of its own takes the remote's head, and one with
+ * commits finds out by uploading.
+ */
+export class FileSyncStateStore {
+    #fs;
+    #directory;
+    constructor(fs, directory) {
+        this.#fs = fs;
+        this.#directory = directory;
+    }
+    async get(sessionId, context) {
+        const result = await this.#fs.readTextFile(await this.#path(sessionId, ".json", context), context);
+        if (isNotFound(result))
+            return undefined;
+        const stored = JSON.parse(unwrap(result));
+        return {
+            syncedHead: stored.syncedHead,
+            ...(stored.pulling === undefined ? {} : { pulling: stored.pulling }),
+        };
+    }
+    async set(sessionId, state, context) {
+        unwrap(await this.#fs.createDir(this.#directory, { recursive: true }, context));
+        const path = await this.#path(sessionId, ".json", context);
+        const temporary = await this.#path(sessionId, ".json.tmp", context);
+        unwrap(await this.#fs.writeFile(temporary, JSON.stringify(state), context));
+        unwrap(await this.#fs.renameFile(temporary, path, context));
+    }
+    /** Forget a session, as when its copy is renamed or deleted. */
+    async delete(sessionId, context) {
+        unwrap(await this.#fs.remove(await this.#path(sessionId, ".json", context), { force: true }, context));
+    }
+    async #path(sessionId, suffix, context) {
+        return unwrap(await this.#fs.joinPath([this.#directory, `${checkSessionId(sessionId)}${suffix}`], context));
+    }
+}
+//# sourceMappingURL=state.js.map

package/dist/sync/state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"state.js","sourceRoot":"","sources":["../../src/sync/state.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,UAAU,EAAuB,MAAM,EAAE,MAAM,YAAY,CAAC;AACrE,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAGjD;;;;GAIG;AACH,MAAM,OAAO,kBAAkB;IACrB,GAAG,CAAiB;IACpB,UAAU,CAAS;IAE5B,YAAY,EAAkB,EAAE,SAAiB;QAChD,IAAI,CAAC,GAAG,GAAG,EAAE,CAAC;QACd,IAAI,CAAC,UAAU,GAAG,SAAS,CAAC;IAC7B,CAAC;IAED,KAAK,CAAC,GAAG,CAAC,SAAiB,EAAE,OAAgB;QAC5C,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,GAAG,CAAC,YAAY,CAAC,MAAM,IAAI,CAAC,KAAK,CAAC,SAAS,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,OAAO,CAAC,CAAC;QACnG,IAAI,UAAU,CAAC,MAAM,CAAC;YAAE,OAAO,SAAS,CAAC;QACzC,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAwC,CAAC;QACjF,OAAO;YACN,UAAU,EAAE,MAAM,CAAC,UAAU;YAC7B,GAAG,CAAC,MAAM,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,CAAC,OAAO,EAAE,CAAC;SACpE,CAAC;IACH,CAAC;IAED,KAAK,CAAC,GAAG,CAAC,SAAiB,EAAE,KAAgB,EAAE,OAAgB;QAC9D,MAAM,CAAC,MAAM,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC,IAAI,CAAC,UAAU,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,EAAE,OAAO,CAAC,CAAC,CAAC;QAChF,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,SAAS,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;QAC3D,MAAM,SAAS,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,SAAS,EAAE,WAAW,EAAE,OAAO,CAAC,CAAC;QACpE,MAAM,CAAC,MAAM,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC,SAAS,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC;QAC5E,MAAM,CAAC,MAAM,IAAI,CAAC,GAAG,CAAC,UAAU,CAAC,SAAS,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC;IAC7D,CAAC;IAED,gEAAgE;IAChE,KAAK,CAAC,MAAM,CAAC,SAAiB,EAAE,OAAgB;QAC/C,MAAM,CAAC,MAAM,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,MAAM,IAAI,CAAC,KAAK,CAAC,SAAS,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE,OAAO,CAAC,CAAC,CAAC;IACxG,CAAC;IAED,KAAK,CAAC,KAAK,CAAC,SAAiB,EAAE,MAAc,EAAE,OAAgB;QAC9D,OAAO,MAAM,CAAC,MAAM,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,UAAU,EAAE,GAAG,cAAc,CAAC,SAAS,CAAC,GAAG,MAAM,EAAE,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC;IAC7G,CAAC;CACD","sourcesContent":["import type { Context } from \"../context/index.ts\";\nimport type { SyncState, SyncStateStore } from \"./client.ts\";\nimport { isNotFound, type SyncFileSystem, unwrap } from \"./files.ts\";\nimport { checkSessionId } from \"./filesystem.ts\";\nimport type { Seq } from \"./remote.ts\";\n\n/**\n * Sync state in a directory, one JSON file per session, replaced through a temporary file and a rename. Losing the\n * directory loses nothing that matters: a copy without commits of its own takes the remote's head, and one with\n * commits finds out by uploading.\n */\nexport class FileSyncStateStore implements SyncStateStore {\n\treadonly #fs: SyncFileSystem;\n\treadonly #directory: string;\n\n\tconstructor(fs: SyncFileSystem, directory: string) {\n\t\tthis.#fs = fs;\n\t\tthis.#directory = directory;\n\t}\n\n\tasync get(sessionId: string, context: Context): Promise<SyncState | undefined> {\n\t\tconst result = await this.#fs.readTextFile(await this.#path(sessionId, \".json\", context), context);\n\t\tif (isNotFound(result)) return undefined;\n\t\tconst stored = JSON.parse(unwrap(result)) as { syncedHead?: Seq; pulling?: Seq };\n\t\treturn {\n\t\t\tsyncedHead: stored.syncedHead,\n\t\t\t...(stored.pulling === undefined ? {} : { pulling: stored.pulling }),\n\t\t};\n\t}\n\n\tasync set(sessionId: string, state: SyncState, context: Context): Promise<void> {\n\t\tunwrap(await this.#fs.createDir(this.#directory, { recursive: true }, context));\n\t\tconst path = await this.#path(sessionId, \".json\", context);\n\t\tconst temporary = await this.#path(sessionId, \".json.tmp\", context);\n\t\tunwrap(await this.#fs.writeFile(temporary, JSON.stringify(state), context));\n\t\tunwrap(await this.#fs.renameFile(temporary, path, context));\n\t}\n\n\t/** Forget a session, as when its copy is renamed or deleted. */\n\tasync delete(sessionId: string, context: Context): Promise<void> {\n\t\tunwrap(await this.#fs.remove(await this.#path(sessionId, \".json\", context), { force: true }, context));\n\t}\n\n\tasync #path(sessionId: string, suffix: string, context: Context): Promise<string> {\n\t\treturn unwrap(await this.#fs.joinPath([this.#directory, `${checkSessionId(sessionId)}${suffix}`], context));\n\t}\n}\n"]}