@hachej/boring-files 0.0.0-stage → 0.2.1

package/dist/remote.js

@@ -0,0 +1,92 @@
+import { PublicationNotDispatchedError, identifier, publicationDigest, publicationSnapshot } from './publication-input.js';
+import { contentType, encode, envelope, identity, jsonBody, limit, lookupResult, observe, publicationResult, readResult, readSnapshot, sameIdentity, schema, version } from './remote-protocol.js';
+import { randomUUID } from './platform.js';
+export { createResourceHandler } from './remote-handler.js';
+export function createResourceClient(options) {
+    if (options.publication && !options.reconciliation)
+        throw new TypeError('A publishing resource client needs reconciliation: a lost save acknowledgement could otherwise never be resolved');
+    const selected = identity(options.identity), endpoint = new URL(options.endpoint);
+    if (!['https:', 'http:'].includes(endpoint.protocol) || endpoint.username || endpoint.password || endpoint.hash)
+        throw new TypeError('Expected an HTTP endpoint without credentials or fragment');
+    const fetch = options.fetch;
+    const requestLimit = limit(options.maxRequestBytes ?? 4_194_304), responseLimit = limit(options.maxResponseBytes ?? 8_388_608);
+    async function invoke(call, signal) {
+        let dispatched = false;
+        const abort = new AbortController();
+        const combined = signal ? AbortSignal.any([signal, abort.signal]) : abort.signal;
+        try {
+            if (combined.aborted)
+                throw new Error('Resource observation aborted');
+            const requestId = randomUUID();
+            const body = encode({ schema, version, requestId, identity: selected, ...call }, requestLimit);
+            const request = new Request(endpoint, { method: 'POST', headers: { 'content-type': contentType }, body, redirect: 'error', signal: combined });
+            if (combined.aborted)
+                throw new Error('Resource observation aborted');
+            dispatched = true;
+            const pending = fetch(request);
+            void pending.then(response => { if (combined.aborted)
+                void response.body?.cancel().catch(() => { }); }, () => { });
+            const response = await observe(pending, combined);
+            if (response.redirected || response.status !== 200) {
+                void response.body?.cancel().catch(() => { });
+                throw new Error('Remote resource response unavailable');
+            }
+            const result = envelope(await jsonBody(response, responseLimit, combined));
+            if (result.requestId !== requestId || result.kind !== call.kind || !sameIdentity(result.identity, selected))
+                throw new TypeError('Resource response association mismatch');
+            return result.value;
+        }
+        catch {
+            if (call.kind === 'publish' && !dispatched)
+                throw new PublicationNotDispatchedError(call.value.operationId);
+            throw new Error('Remote resource operation is unconfirmed');
+        }
+        finally {
+            abort.abort();
+        }
+    }
+    return {
+        read: async (request, signal) => {
+            const captured = readSnapshot(request);
+            try {
+                return readResult(await invoke({ kind: 'read', value: captured }, signal), captured, true);
+            }
+            catch {
+                return { kind: 'unavailable', reason: 'Remote resource read is unconfirmed' };
+            }
+        },
+        ...(options.publication ? {
+            publish: async (request, signal) => {
+                const captured = publicationSnapshot(request);
+                let digest;
+                try {
+                    if (captured.atomicity !== 'all-or-nothing')
+                        throw new TypeError('Remote per-change publication is not qualified');
+                    digest = await publicationDigest(captured);
+                }
+                catch {
+                    throw new PublicationNotDispatchedError(captured.operationId);
+                }
+                try {
+                    return publicationResult(await invoke({ kind: 'publish', value: captured }, signal), captured.operationId, selected, captured, digest);
+                }
+                catch (error) {
+                    if (error instanceof PublicationNotDispatchedError)
+                        throw error;
+                    return { kind: 'unknown', operationId: captured.operationId, reason: 'Remote publication is unconfirmed; reconcile the original operation without automatic replay' };
+                }
+            },
+        } : {}),
+        ...(options.reconciliation ? {
+            lookup: async (operationId, signal) => {
+                const captured = identifier(operationId);
+                try {
+                    return lookupResult(await invoke({ kind: 'lookup', value: captured }, signal), captured, selected);
+                }
+                catch {
+                    return { kind: 'unknown', operationId: captured, reason: 'Remote operation lookup is unconfirmed' };
+                }
+            },
+        } : {}),
+    };
+}

package/dist/request-guard.d.ts

@@ -0,0 +1,20 @@
+/**
+ * The one request-body guard of every `create*Handler` in the packages (resource, remote files, remote shell, chat
+ * transport): a JSON content type is required and the body is streamed under a byte cap, so a cross-site `text/plain`
+ * form POST and an oversized body are both refused before any parsing or full buffering. `npm run check` fails when a
+ * `create*Handler` does not import this module, so the handlers cannot drift apart.
+ */
+export declare const JSON_CONTENT_TYPE = "application/json";
+/** A refused request body. `status` is the HTTP status the handler answers with. */
+export declare class RequestGuardError extends Error {
+    readonly status: 400 | 413 | 415;
+    constructor(status: 400 | 413 | 415, message: string);
+}
+/** The HTTP status for a guard refusal, or 400 for any other body failure. */
+export declare function guardStatus(error: unknown): 400 | 413 | 415;
+export declare function hasJsonContentType(headers: Headers): boolean;
+/** Read a stream as JSON without ever holding more than `maximum` bytes. No content-type check: see `readJsonBody`. */
+export declare function readBoundedJson(body: ReadableStream<Uint8Array> | null, maximum: number, signal?: AbortSignal): Promise<unknown>;
+/** Require `application/json`, refuse a declared length over the cap early, then read the body under the cap. */
+export declare function readJsonBody(message: Request | Response, maximum: number, signal?: AbortSignal): Promise<unknown>;
+//# sourceMappingURL=request-guard.d.ts.map

package/dist/request-guard.js

@@ -0,0 +1,75 @@
+/**
+ * The one request-body guard of every `create*Handler` in the packages (resource, remote files, remote shell, chat
+ * transport): a JSON content type is required and the body is streamed under a byte cap, so a cross-site `text/plain`
+ * form POST and an oversized body are both refused before any parsing or full buffering. `npm run check` fails when a
+ * `create*Handler` does not import this module, so the handlers cannot drift apart.
+ */
+export const JSON_CONTENT_TYPE = 'application/json';
+/** A refused request body. `status` is the HTTP status the handler answers with. */
+export class RequestGuardError extends Error {
+    status;
+    constructor(status, message) { super(message); this.name = 'RequestGuardError'; this.status = status; }
+}
+/** The HTTP status for a guard refusal, or 400 for any other body failure. */
+export function guardStatus(error) {
+    return error instanceof RequestGuardError ? error.status : 400;
+}
+export function hasJsonContentType(headers) {
+    return headers.get('content-type')?.split(';')[0]?.trim().toLowerCase() === JSON_CONTENT_TYPE;
+}
+/** Read a stream as JSON without ever holding more than `maximum` bytes. No content-type check: see `readJsonBody`. */
+export async function readBoundedJson(body, maximum, signal) {
+    if (!Number.isSafeInteger(maximum) || maximum < 1)
+        throw new TypeError('Expected a positive byte limit');
+    if (!body)
+        throw new RequestGuardError(400, 'Missing request body');
+    const reader = body.getReader();
+    let fail;
+    const abort = new Promise((_, reject) => {
+        fail = () => reject(new Error('Request body read aborted'));
+        if (signal?.aborted)
+            fail();
+        else
+            signal?.addEventListener('abort', fail, { once: true });
+    });
+    abort.catch(() => { });
+    try {
+        let size = 0, buffer = new Uint8Array(Math.min(maximum, 16_384));
+        while (true) {
+            const item = await (signal ? Promise.race([reader.read(), abort]) : reader.read());
+            if (item.done)
+                break;
+            if (item.value.byteLength > maximum - size)
+                throw new RequestGuardError(413, 'Request body exceeds its byte limit');
+            const next = size + item.value.byteLength;
+            if (next > buffer.byteLength) {
+                const grown = new Uint8Array(Math.min(maximum, Math.max(next, buffer.byteLength * 2)));
+                grown.set(buffer.subarray(0, size));
+                buffer = grown;
+            }
+            buffer.set(item.value, size);
+            size = next;
+        }
+        try {
+            return JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(buffer.subarray(0, size)));
+        }
+        catch {
+            throw new RequestGuardError(400, 'Request body is not valid JSON');
+        }
+    }
+    finally {
+        if (fail)
+            signal?.removeEventListener('abort', fail);
+        void reader.cancel().catch(() => { });
+        reader.releaseLock();
+    }
+}
+/** Require `application/json`, refuse a declared length over the cap early, then read the body under the cap. */
+export async function readJsonBody(message, maximum, signal) {
+    if (!hasJsonContentType(message.headers))
+        throw new RequestGuardError(415, 'Request content type must be application/json');
+    const declared = Number(message.headers.get('content-length'));
+    if (Number.isFinite(declared) && declared > maximum)
+        throw new RequestGuardError(413, 'Request body exceeds its byte limit');
+    return readBoundedJson(message.body, maximum, signal);
+}

package/dist/revision-contracts.d.ts

@@ -0,0 +1,89 @@
+import type { ResourceClient } from './client.js';
+import type { ResourceAccess, ResourceLocator } from './contracts.js';
+import type { ResourceIdentity } from './remote-protocol.js';
+import type { WorkspaceKey } from './workspace-identity.js';
+export interface FileEntry {
+    readonly path: string;
+    readonly kind: 'file' | 'directory';
+    readonly size: number;
+}
+export interface FilePage {
+    readonly entries: readonly FileEntry[];
+    readonly cursor?: string;
+}
+export interface FileListRequest {
+    readonly directory?: string;
+    readonly cursor?: string;
+    readonly limit?: number;
+}
+export interface FileSearchRequest {
+    readonly query: string;
+    readonly cursor?: string;
+    readonly limit?: number;
+}
+export interface SavedRevision {
+    readonly revision: string;
+    readonly savedAt: number;
+    /** Who wrote it: `publish` (a conditional write), `agent` (a Pi `write` or `edit`: observed, never receipted) or `observed` (retained as found). */
+    readonly source?: 'publish' | 'agent' | 'observed';
+}
+/**
+ * One entry of a workspace's change feed (ruling 2 of 2026-10-10): an invalidation hint, never content or a receipt. Bytes and
+ * the publication journal stay authoritative; a viewer that receives one reads again.
+ *
+ * - `change`: something at `path` changed. `revision` is the Git blob id now there, or `null` when the path is absent or is a
+ *   directory (`directory: true`: something below it may have changed). `source`: `publish` (a conditional write), `agent` (a Pi
+ *   `write` or `edit`), `poll` (found by hashing, for example after a `bash` command) or `watch` (reported by the file system).
+ * - `resnapshot`: events were lost (the cursor is older than the retained window, from another provider lifetime, or the watcher
+ *   overflowed or restarted). Reload everything shown, then continue after this `seq`.
+ *
+ * `seq` increases strictly within one provider lifetime; `at` is milliseconds since the epoch.
+ */
+export type WorkspaceChangeEvent = {
+    readonly kind: 'change';
+    readonly path: string;
+    readonly revision: string | null;
+    readonly source: 'publish' | 'agent' | 'poll' | 'watch';
+    readonly seq: number;
+    readonly at: number;
+    readonly directory?: true;
+    readonly conversationId?: string;
+} | {
+    readonly kind: 'resnapshot';
+    readonly seq: number;
+    readonly at: number;
+};
+export interface ChangeFeedRequest {
+    /** The last `seq` already seen: only later events are delivered (a gap is a `resnapshot`). Absent: live events only. */
+    readonly since?: number | undefined;
+    /** The provider lifetime `since` came from (`ready` event). A cursor from another lifetime is a `resnapshot`, whatever its number. */
+    readonly incarnation?: string | undefined;
+    readonly signal?: AbortSignal | undefined;
+}
+export interface WorkspaceCatalog {
+    readonly list: (request: FileListRequest, access: ResourceAccess) => Promise<FilePage>;
+    readonly search: (request: FileSearchRequest, access: ResourceAccess) => Promise<FilePage>;
+    readonly history: (path: string, access: ResourceAccess) => Promise<readonly SavedRevision[]>;
+}
+export declare class RevisionError extends Error {
+    readonly kind: 'denied' | 'unavailable' | 'invalid' | 'aborted';
+    constructor(kind: 'denied' | 'unavailable' | 'invalid' | 'aborted', message: string);
+}
+/** One authenticated binding for viewers, file browsing and publication. */
+export interface RevisionProvider extends ResourceClient {
+    readonly identity: ResourceIdentity;
+    readonly workspace: WorkspaceKey;
+    readonly locate: (path: string) => ResourceLocator;
+    readonly publish: NonNullable<ResourceClient['publish']>;
+    readonly lookup: NonNullable<ResourceClient['lookup']>;
+    readonly list: (request: FileListRequest, signal?: AbortSignal) => Promise<FilePage>;
+    readonly search: (request: FileSearchRequest, signal?: AbortSignal) => Promise<FilePage>;
+    readonly history: (path: string, signal?: AbortSignal) => Promise<readonly SavedRevision[]>;
+    /**
+     * The workspace's change feed (`GET ?op=changes`, server-sent events), reconnecting after the last `seq` seen until `signal`
+     * aborts; a refused binding (another workspace, revoked access) ends it with a `RevisionError`. Optional: a hand-built provider
+     * may have none, and a viewer then refreshes on its own schedule.
+     */
+    readonly changes?: (request?: ChangeFeedRequest) => AsyncIterable<WorkspaceChangeEvent>;
+}
+//# sourceMappingURL=revision-contracts.d.ts.map

package/dist/revision-contracts.js

@@ -0,0 +1,8 @@
+export class RevisionError extends Error {
+    kind;
+    constructor(kind, message) {
+        super(message);
+        this.kind = kind;
+        this.name = 'RevisionError';
+    }
+}

package/dist/revision-handler.d.ts

@@ -0,0 +1,14 @@
+import type { ResourceAccess } from './contracts.js';
+import type { WorkspaceResourceProvider } from './workspace.js';
+export interface RevisionHandlerOptions {
+    /** The host's authentication and workspace selection, once per request. For the change feed the lease is held until the stream ends. */
+    readonly resolve: (request: Request) => Promise<null | {
+        readonly provider: WorkspaceResourceProvider;
+        readonly access: ResourceAccess;
+        readonly release?: () => void | Promise<void>;
+    }>;
+    /** How often the change feed sends a comment line so proxies keep it open, in milliseconds (default 15 000). */
+    readonly heartbeatMs?: number;
+}
+export declare function createRevisionHandler(options: RevisionHandlerOptions): (request: Request) => Promise<Response>;
+//# sourceMappingURL=revision-handler.d.ts.map

package/dist/revision-handler.js

@@ -0,0 +1,213 @@
+import { createResourceHandler } from './remote-handler.js';
+import { binding, bindingHeader, bindingValue, catalogHeader, filePage, record, savedRevisions } from './revision-protocol.js';
+import { guardStatus, readJsonBody, RequestGuardError } from './request-guard.js';
+import { accessSnapshot, identifier } from './publication-input.js';
+import { RevisionError } from './revision-contracts.js';
+const encoder = new TextEncoder();
+/**
+ * `GET ?op=changes[&since=<seq>&incarnation=<id>]`: the workspace's change feed as server-sent events (`event: change | resnapshot`,
+ * `id:` the seq, `data:` the JSON event), after an `event: ready` naming the current seq and the provider's incarnation, with a
+ * comment every `heartbeatMs` while idle. Plain streamed responses, so it runs on Node and on Workers alike.
+ *
+ * The stream is pull-based with no queue (`highWaterMark: 0`): the provider is read only while the client is reading, so a slow
+ * client costs the provider's bounded replay buffer (and a `resnapshot` when it falls behind), never unbounded memory here. The
+ * stream ends when the person disconnects or their access is revoked, discarding anything not yet read, and the workspace lease is
+ * released then.
+ */
+function changeStream(provider, access, request, heartbeatMs, release) {
+    const stop = new AbortController();
+    const signal = AbortSignal.any([access.signal, stop.signal, provider.lifetime]);
+    let iterator;
+    let pending;
+    let ready = false, ended = false;
+    const finish = () => {
+        if (ended)
+            return;
+        ended = true;
+        stop.abort();
+        void iterator?.return?.().catch(() => { });
+        void release();
+    };
+    const body = new ReadableStream({
+        start: controller => {
+            const close = () => { finish(); try {
+                controller.close();
+            }
+            catch { /* already closed or cancelled */ } };
+            signal.addEventListener('abort', close, { once: true });
+            if (signal.aborted)
+                close();
+        },
+        pull: async (controller) => {
+            if (ended)
+                return;
+            const send = (text) => { try {
+                controller.enqueue(encoder.encode(text));
+            }
+            catch {
+                finish();
+            } };
+            const end = () => { finish(); try {
+                controller.close();
+            }
+            catch { /* already closed */ } };
+            try {
+                if (!ready) {
+                    ready = true;
+                    // Without a cursor the feed starts at the current seq, which the client learns first and resumes from after a disconnect.
+                    const start = request.since ?? provider.changeHead();
+                    iterator = provider.changes({ since: start, ...(request.incarnation === undefined ? {} : { incarnation: request.incarnation }), signal }, { ...access, signal })[Symbol.asyncIterator]();
+                    // An async iterator runs its body only on the first pull, so prime it here: the watcher then starts before `ready`, and a
+                    // write the client makes after reading `ready` is not missed.
+                    pending = iterator.next();
+                    pending.catch(() => { });
+                    send(`event: ready\ndata: ${JSON.stringify({ seq: start, incarnation: provider.changeIncarnation })}\n\n`);
+                    return;
+                }
+                pending ??= iterator.next();
+                pending.catch(() => { });
+                let timer;
+                const beat = new Promise(resolve => { timer = setTimeout(() => resolve('beat'), heartbeatMs); });
+                const outcome = await Promise.race([pending, beat]).finally(() => clearTimeout(timer));
+                if (signal.aborted)
+                    return end();
+                if (outcome === 'beat')
+                    return send(': heartbeat\n\n');
+                pending = undefined;
+                if (outcome.done)
+                    return end();
+                const event = outcome.value;
+                send(`id: ${event.seq}\nevent: ${event.kind}\ndata: ${JSON.stringify(event)}\n\n`);
+            }
+            catch {
+                end(); /* the client reconnects from its last seq */
+            }
+        },
+        cancel: () => { finish(); },
+    }, { highWaterMark: 0 });
+    return new Response(body, { headers: { 'content-type': 'text/event-stream; charset=utf-8', 'cache-control': 'no-store', 'x-accel-buffering': 'no' } });
+}
+function listRequest(value) {
+    const data = record(value);
+    if ((data.directory !== undefined && typeof data.directory !== 'string') || (data.cursor !== undefined && typeof data.cursor !== 'string') || (data.limit !== undefined && typeof data.limit !== 'number'))
+        throw new RevisionError('invalid', 'Invalid listing request');
+    return { ...(typeof data.directory === 'string' ? { directory: data.directory } : {}), ...(typeof data.cursor === 'string' ? { cursor: data.cursor } : {}), ...(typeof data.limit === 'number' ? { limit: data.limit } : {}) };
+}
+export function createRevisionHandler(options) {
+    const heartbeatMs = options.heartbeatMs ?? 15_000;
+    if (!Number.isSafeInteger(heartbeatMs) || heartbeatMs < 1)
+        throw new RangeError('The heartbeat interval must be a positive integer');
+    return async (request) => {
+        let release;
+        const operations = new Set();
+        const hold = (pending) => {
+            operations.add(pending);
+            void pending.then(() => operations.delete(pending), () => operations.delete(pending));
+            return pending;
+        };
+        const refuse = (status) => new Response(null, { status, headers: { 'cache-control': 'no-store' } });
+        try {
+            if (request.method !== 'GET' && request.method !== 'POST')
+                return refuse(405);
+            if (request.signal.aborted)
+                return refuse(403);
+            const selected = await options.resolve(request);
+            if (!selected)
+                return refuse(403);
+            release = selected.release;
+            const captured = accessSnapshot(selected.access);
+            const access = { ...captured, signal: captured.signal ? AbortSignal.any([captured.signal, request.signal]) : request.signal };
+            if (access.signal.aborted)
+                return refuse(403);
+            const association = binding({ identity: captured, workspace: selected.provider.identity });
+            const respond = (value) => Response.json(value, { headers: { 'cache-control': 'no-store' } });
+            const op = new URL(request.url).searchParams.get('op');
+            if (request.method === 'GET' && op === null)
+                return respond(association);
+            const header = request.headers.get(bindingHeader);
+            if (!header || header.length > 16384)
+                return refuse(403);
+            let requested;
+            try {
+                requested = bindingValue(binding(JSON.parse(decodeURIComponent(header))));
+            }
+            catch {
+                return refuse(403);
+            }
+            if (requested !== bindingValue(association))
+                return refuse(409);
+            const provider = selected.provider;
+            if (request.method === 'GET') {
+                if (op !== 'changes')
+                    return refuse(400);
+                const cursor = new URL(request.url).searchParams.get('since');
+                if (cursor !== null && !/^\d{1,16}$/.test(cursor))
+                    return refuse(400);
+                const since = cursor === null ? undefined : Number(cursor);
+                const incarnation = new URL(request.url).searchParams.get('incarnation') ?? undefined;
+                if (incarnation !== undefined && !/^[\w-]{1,64}$/.test(incarnation))
+                    return refuse(400);
+                if (since !== undefined && !Number.isSafeInteger(since))
+                    return refuse(400);
+                // The stream owns the lease from here: it is released when the stream ends, not when this function returns.
+                const lease = release;
+                release = undefined;
+                return changeStream(provider, access, { since, incarnation }, heartbeatMs, async () => { try {
+                    await lease?.();
+                }
+                catch { /* the stream already ended */ } });
+            }
+            if (!request.headers.has(catalogHeader))
+                return await createResourceHandler({
+                    authenticate: async () => access,
+                    reader: { read: (value, context) => hold(provider.read(value, context)) },
+                    publisher: { publish: (value, context) => hold(provider.publication.publish(value, context)) },
+                    lookup: { lookup: (value, context) => hold(provider.reconciliation.lookup(value, context)) },
+                })(request);
+            const input = record(await readJsonBody(request, 32_768, access.signal));
+            const requestId = identifier(input.requestId);
+            let value;
+            switch (input.kind) {
+                case 'list':
+                    value = filePage(await provider.catalog.list(listRequest(input.value), access));
+                    break;
+                case 'search': {
+                    const data = record(input.value);
+                    if (typeof data.query !== 'string')
+                        throw new RevisionError('invalid', 'Invalid filename query');
+                    const query = { ...listRequest(data), query: data.query };
+                    value = filePage(await provider.catalog.search(query, access));
+                    break;
+                }
+                case 'history':
+                    if (typeof input.value !== 'string')
+                        throw new RevisionError('invalid', 'Invalid history path');
+                    value = savedRevisions(await provider.catalog.history(input.value, access));
+                    break;
+                default: return refuse(400);
+            }
+            if (access.signal.aborted)
+                return refuse(403);
+            const body = JSON.stringify({ ...association, requestId, kind: input.kind, value });
+            if (new TextEncoder().encode(body).byteLength > 8_388_608)
+                return refuse(503);
+            return new Response(body, { headers: { 'content-type': 'application/json', 'cache-control': 'no-store' } });
+        }
+        catch (error) {
+            return refuse(error instanceof RevisionError ? error.kind === 'invalid' ? 400 : error.kind === 'denied' || error.kind === 'aborted' ? 403 : 503 : error instanceof RequestGuardError || error instanceof TypeError ? guardStatus(error) : 503);
+        }
+        finally {
+            await Promise.allSettled([...operations]);
+            try {
+                await release?.();
+            }
+            catch {
+                return refuse(503);
+            }
+            finally {
+                if (!request.bodyUsed)
+                    void request.body?.cancel().catch(() => { });
+            }
+        }
+    };
+}

package/dist/revision-protocol.d.ts

@@ -0,0 +1,22 @@
+import type { ResourceIdentity } from './remote-protocol.js';
+import type { WorkspaceKey } from './workspace.js';
+import type { FilePage, SavedRevision, WorkspaceChangeEvent } from './revision-contracts.js';
+export declare const bindingHeader = "x-boring-workspace";
+export declare const catalogHeader = "x-boring-catalog";
+export interface RevisionBinding {
+    readonly identity: ResourceIdentity;
+    readonly workspace: WorkspaceKey;
+}
+export declare function record(value: unknown): Record<string, unknown>;
+export declare function binding(value: unknown): RevisionBinding;
+export declare const bindingValue: (value: RevisionBinding) => string;
+export declare function filePage(value: unknown): FilePage;
+export declare function savedRevisions(value: unknown): readonly SavedRevision[];
+/** One change-feed event as the server sent it, checked field by field (`data:` of `event: change | resnapshot`). */
+export declare function changeEvent(value: unknown): WorkspaceChangeEvent;
+/** Server-sent events from a response body: `{ event, data }` per message, comments skipped, a line longer than `limit` refused. */
+export declare function serverEvents(body: ReadableStream<Uint8Array>, limit?: number): AsyncGenerator<{
+    readonly event: string;
+    readonly data: string;
+}>;
+//# sourceMappingURL=revision-protocol.d.ts.map

package/dist/revision-protocol.js

@@ -0,0 +1,106 @@
+import { identifier, locator } from './publication-input.js';
+import { RevisionError } from './revision-contracts.js';
+const catalogPath = (path) => locator({ resource: { providerId: 'catalog', path }, view: { kind: 'published' } }).resource.path;
+export const bindingHeader = 'x-boring-workspace';
+export const catalogHeader = 'x-boring-catalog';
+export function record(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw new RevisionError('invalid', 'Invalid revision response');
+    return value;
+}
+export function binding(value) {
+    const data = record(value), workspace = record(data.workspace), person = record(data.identity);
+    return { identity: { principalId: identifier(person.principalId), scopeId: identifier(person.scopeId), initiatorId: identifier(person.initiatorId) }, workspace: {
+            providerId: identifier(workspace.providerId), instanceId: identifier(workspace.instanceId),
+            incarnation: identifier(workspace.incarnation), viewId: identifier(workspace.viewId),
+        } };
+}
+export const bindingValue = (value) => encodeURIComponent(JSON.stringify(binding(value)));
+export function filePage(value) {
+    const data = record(value);
+    if (!Array.isArray(data.entries) || data.entries.length > 500 || (data.cursor !== undefined && (typeof data.cursor !== 'string' || data.cursor.length > 16384)))
+        throw new RevisionError('invalid', 'Invalid file page');
+    const entries = data.entries.map((item) => {
+        const entry = record(item);
+        if ((entry.kind !== 'file' && entry.kind !== 'directory') || typeof entry.size !== 'number' || !Number.isSafeInteger(entry.size) || entry.size < 0 || typeof entry.path !== 'string')
+            throw new RevisionError('invalid', 'Invalid file entry');
+        return { path: catalogPath(entry.path), kind: entry.kind, size: entry.size };
+    });
+    if (new Set(entries.map(entry => entry.path)).size !== entries.length)
+        throw new RevisionError('invalid', 'Duplicate file entries');
+    return { entries, ...(typeof data.cursor === 'string' ? { cursor: data.cursor } : {}) };
+}
+export function savedRevisions(value) {
+    if (!Array.isArray(value) || value.length > 100_000)
+        throw new RevisionError('invalid', 'Invalid file history');
+    return value.map(item => {
+        const entry = record(item);
+        if (typeof entry.savedAt !== 'number' || !Number.isSafeInteger(entry.savedAt) || entry.savedAt < 0)
+            throw new RevisionError('invalid', 'Invalid save timestamp');
+        const source = entry.source === 'publish' || entry.source === 'agent' || entry.source === 'observed' ? entry.source : undefined;
+        return { revision: identifier(entry.revision), savedAt: entry.savedAt, ...(source ? { source } : {}) };
+    });
+}
+const sources = new Set(['publish', 'agent', 'poll', 'watch']);
+const sequence = (value, what) => {
+    if (typeof value !== 'number' || !Number.isSafeInteger(value) || value < 0)
+        throw new RevisionError('invalid', `Invalid ${what}`);
+    return value;
+};
+/** One change-feed event as the server sent it, checked field by field (`data:` of `event: change | resnapshot`). */
+export function changeEvent(value) {
+    const data = record(value);
+    const seq = sequence(data.seq, 'change sequence'), at = sequence(data.at, 'change time');
+    if (data.kind === 'resnapshot')
+        return { kind: 'resnapshot', seq, at };
+    if (data.kind !== 'change' || typeof data.path !== 'string' || typeof data.source !== 'string' || !sources.has(data.source))
+        throw new RevisionError('invalid', 'Invalid change event');
+    if (data.directory !== undefined && data.directory !== true)
+        throw new RevisionError('invalid', 'Invalid change event');
+    const path = data.path === '' && data.directory === true ? '' : catalogPath(data.path);
+    const revision = data.revision === null ? null : identifier(data.revision);
+    return {
+        kind: 'change', path, revision, source: data.source, seq, at,
+        ...(data.directory === true ? { directory: true } : {}),
+        ...(data.conversationId !== undefined ? { conversationId: identifier(data.conversationId) } : {}),
+    };
+}
+/** Server-sent events from a response body: `{ event, data }` per message, comments skipped, a line longer than `limit` refused. */
+export async function* serverEvents(body, limit = 1_048_576) {
+    const reader = body.getReader(), decoder = new TextDecoder();
+    let pending = '', event = 'message', data = [];
+    try {
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                return;
+            pending += decoder.decode(value, { stream: true });
+            let newline;
+            while ((newline = pending.search(/\r?\n/)) !== -1) {
+                const line = pending.slice(0, newline);
+                pending = pending.slice(pending[newline] === '\r' ? newline + 2 : newline + 1);
+                if (line === '') {
+                    if (data.length)
+                        yield { event, data: data.join('\n') };
+                    event = 'message';
+                    data = [];
+                    continue;
+                }
+                if (line.startsWith(':'))
+                    continue;
+                const colon = line.indexOf(':');
+                const field = colon === -1 ? line : line.slice(0, colon);
+                const content = colon === -1 ? '' : line.slice(colon + 1).replace(/^ /, '');
+                if (field === 'event')
+                    event = content;
+                else if (field === 'data')
+                    data.push(content);
+            }
+            if (pending.length > limit)
+                throw new RevisionError('invalid', 'Change feed line exceeds the limit');
+        }
+    }
+    finally {
+        void reader.cancel().catch(() => { });
+    }
+}

package/dist/revision.d.ts

@@ -0,0 +1,8 @@
+import type { RevisionProvider } from './revision-contracts.js';
+export * from './revision-contracts.js';
+export declare function connectRevisionProvider(options: {
+    readonly endpoint: string | URL;
+    readonly fetch: (request: Request) => Promise<Response>;
+    readonly signal?: AbortSignal;
+}): Promise<RevisionProvider>;
+//# sourceMappingURL=revision.d.ts.map