@hachej/boring-files 0.0.0-stage → 0.2.1

package/dist/revision.js

@@ -0,0 +1,145 @@
+import { createResourceClient } from './remote.js';
+import { binding, bindingHeader, bindingValue, catalogHeader, changeEvent, filePage, record, savedRevisions, serverEvents } from './revision-protocol.js';
+import { readJsonBody } from './request-guard.js';
+import { RevisionError } from './revision-contracts.js';
+import { observe } from './remote-protocol.js';
+import { randomUUID } from './platform.js';
+import { locator } from './publication-input.js';
+export * from './revision-contracts.js';
+export async function connectRevisionProvider(options) {
+    const endpoint = new URL(options.endpoint), fetch = options.fetch;
+    if (!['http:', 'https:'].includes(endpoint.protocol) || endpoint.username || endpoint.password || endpoint.hash)
+        throw new TypeError('Expected an HTTP endpoint without credentials or fragment');
+    async function send(request) {
+        try {
+            const pending = fetch(request);
+            void pending.then(response => { if (request.signal.aborted)
+                void response.body?.cancel().catch(() => { }); }, () => { });
+            const response = await observe(pending, request.signal);
+            if (request.signal.aborted) {
+                void response.body?.cancel().catch(() => { });
+                throw new RevisionError('aborted', 'File request was cancelled');
+            }
+            if (response.redirected || !response.ok) {
+                void response.body?.cancel().catch(() => { });
+                throw new RevisionError(response.status === 403 || response.status === 409 ? 'denied' : response.status === 400 ? 'invalid' : 'unavailable', 'The selected workspace is unavailable or no longer authorized');
+            }
+            return await readJsonBody(response, 8_388_608, request.signal);
+        }
+        catch (error) {
+            if (request.signal.aborted)
+                throw new RevisionError('aborted', 'File request was cancelled');
+            if (error instanceof RevisionError)
+                throw error;
+            throw new RevisionError('unavailable', 'The file request could not be completed');
+        }
+    }
+    const selected = binding(await send(new Request(endpoint, { method: 'GET', redirect: 'error', ...(options.signal ? { signal: options.signal } : {}) })));
+    const bound = bindingValue(selected);
+    const client = createResourceClient({ endpoint, identity: selected.identity, publication: true, reconciliation: true,
+        fetch: request => { const headers = new Headers(request.headers); headers.set(bindingHeader, bound); return fetch(new Request(request, { headers })); } });
+    async function invoke(kind, value, signal) {
+        const requestId = randomUUID();
+        const result = record(await send(new Request(endpoint, { method: 'POST', redirect: 'error', headers: { 'content-type': 'application/json', [bindingHeader]: bound, [catalogHeader]: '1' }, body: JSON.stringify({ requestId, kind, value }), ...(signal ? { signal } : {}) })));
+        if (bindingValue(binding(result)) !== bound || result.kind !== kind || result.requestId !== requestId)
+            throw new RevisionError('denied', 'The response belongs to another workspace');
+        return result.value;
+    }
+    /** One feed across reconnections: each resumes after the last seq delivered; a refused binding ends it. */
+    async function* changes(request = {}) {
+        const signal = request.signal;
+        let cursor = request.since, incarnation = request.incarnation, staged, delay = 500;
+        const pause = () => new Promise(resolve => {
+            const timer = setTimeout(done, delay);
+            function done() { clearTimeout(timer); signal?.removeEventListener('abort', done); resolve(); }
+            signal?.addEventListener('abort', done, { once: true });
+            delay = Math.min(delay * 2, 30_000);
+        });
+        while (!signal?.aborted) {
+            const url = new URL(endpoint);
+            url.searchParams.set('op', 'changes');
+            if (cursor !== undefined) {
+                url.searchParams.set('since', String(cursor));
+                if (incarnation !== undefined)
+                    url.searchParams.set('incarnation', incarnation);
+            }
+            const connection = new AbortController();
+            const stop = () => connection.abort();
+            signal?.addEventListener('abort', stop, { once: true });
+            try {
+                let response;
+                try {
+                    response = await fetch(new Request(url, { method: 'GET', redirect: 'error', headers: { accept: 'text/event-stream', [bindingHeader]: bound }, signal: connection.signal }));
+                }
+                catch {
+                    if (signal?.aborted)
+                        return;
+                    await pause();
+                    continue;
+                }
+                if (response.redirected || !response.ok || !response.body) {
+                    void response.body?.cancel().catch(() => { });
+                    if (response.status === 403 || response.status === 409)
+                        throw new RevisionError('denied', 'The selected workspace is unavailable or no longer authorized');
+                    if (response.status === 400)
+                        throw new RevisionError('invalid', 'The change feed request was refused');
+                    await pause();
+                    continue;
+                }
+                try {
+                    for await (const message of serverEvents(response.body)) {
+                        if (message.event === 'ready') {
+                            const ready = record(JSON.parse(message.data)), seq = ready.seq;
+                            // A new provider lifetime is adopted with its resnapshot, not with `ready`: a disconnect in between must reconnect with the
+                            // old cursor and incarnation, which the server answers with a resnapshot again.
+                            if (typeof ready.incarnation === 'string') {
+                                if (cursor === undefined || incarnation === undefined)
+                                    incarnation = ready.incarnation;
+                                else
+                                    staged = ready.incarnation;
+                            }
+                            if (cursor === undefined && typeof seq === 'number' && Number.isSafeInteger(seq))
+                                cursor = seq;
+                            delay = 500;
+                            continue;
+                        }
+                        if (message.event !== 'change' && message.event !== 'resnapshot')
+                            continue;
+                        const event = changeEvent(JSON.parse(message.data));
+                        if (event.kind === 'change' && cursor !== undefined && event.seq <= cursor)
+                            continue;
+                        if (event.kind === 'resnapshot' && staged !== undefined) {
+                            incarnation = staged;
+                            staged = undefined;
+                        }
+                        cursor = event.seq;
+                        yield event;
+                    }
+                }
+                catch (error) {
+                    if (signal?.aborted)
+                        return;
+                    if (error instanceof RevisionError && error.kind === 'invalid')
+                        throw error;
+                }
+            }
+            finally {
+                signal?.removeEventListener('abort', stop);
+                connection.abort();
+            }
+            if (signal?.aborted)
+                return;
+            await pause();
+        }
+    }
+    if (!client.publish || !client.lookup)
+        throw new Error('Publishing client lacks reconciliation');
+    return {
+        ...client, publish: client.publish, lookup: client.lookup, identity: Object.freeze(selected.identity), workspace: Object.freeze(selected.workspace),
+        locate: path => locator({ resource: { providerId: selected.workspace.providerId, path }, view: { kind: 'published' } }),
+        list: async (request, signal) => filePage(await invoke('list', request, signal)),
+        search: async (request, signal) => filePage(await invoke('search', request, signal)),
+        history: async (path, signal) => savedRevisions(await invoke('history', path, signal)),
+        changes: request => changes(request),
+    };
+}

package/dist/sqlite-batch.d.ts

@@ -0,0 +1,19 @@
+import type { SqliteConnection } from './sqlite.js';
+/**
+ * Internal (not a package export): what the workspace provider needs from the SQLite file system to commit a multi-file batch in
+ * one transaction. Registered by `openSqliteFileSystem` against the file system object it returns, so the provider keeps taking a
+ * plain Pi `FileSystem`. Both functions are synchronous and run inside `connection.transaction`.
+ */
+export interface SqliteBatch {
+    readonly connection: SqliteConnection;
+    /** The bytes of the regular file at an absolute path, `null` when nothing is there, `undefined` when it is not a file. */
+    readonly bytes: (path: string) => Uint8Array | null | undefined;
+    /** Write a regular file at an absolute path, creating its missing parent directories. Throws a Pi `FileError` on failure. */
+    readonly write: (path: string, bytes: Uint8Array) => void;
+}
+export declare const registerSqliteBatch: (fs: object, batch: SqliteBatch) => void;
+export declare const sqliteBatchOf: (fs: object) => SqliteBatch | undefined;
+/** The journal's connection, so the provider can commit the bytes and the receipt in one transaction when they share a database. */
+export declare const registerJournalConnection: (journal: object, connection: SqliteConnection) => void;
+export declare const journalConnectionOf: (journal: object) => SqliteConnection | undefined;
+//# sourceMappingURL=sqlite-batch.d.ts.map

package/dist/sqlite-batch.js

@@ -0,0 +1,7 @@
+const batches = new WeakMap();
+const journals = new WeakMap();
+export const registerSqliteBatch = (fs, batch) => { batches.set(fs, batch); };
+export const sqliteBatchOf = (fs) => batches.get(fs);
+/** The journal's connection, so the provider can commit the bytes and the receipt in one transaction when they share a database. */
+export const registerJournalConnection = (journal, connection) => { journals.set(journal, connection); };
+export const journalConnectionOf = (journal) => journals.get(journal);

package/dist/sqlite-durable-object.d.ts

@@ -0,0 +1,24 @@
+import type { SqliteConnection } from './sqlite.js';
+type DurableValue = ArrayBuffer | string | number | null;
+/**
+ * The part of a Cloudflare Durable Object's `ctx.storage` this adapter uses, declared structurally so the package needs no
+ * Cloudflare types: `sql.exec(query, ...bindings)` returns a cursor and `transactionSync(work)` runs `work` as one SQLite transaction.
+ */
+export interface DurableObjectSqlStorage {
+    readonly sql: {
+        readonly exec: (query: string, ...bindings: DurableValue[]) => {
+            readonly toArray: () => Record<string, unknown>[];
+        };
+    };
+    readonly transactionSync: <Value>(work: () => Value) => Value;
+}
+/**
+ * A `SqliteConnection` over a SQLite-backed Durable Object's storage, for `openSqliteFileSystem({ connection })` and `createWorkspaceJournal(connection)`. Statements run on
+ * the object's own synchronous SQL API. A `write` transaction is `transactionSync`: SQLite commits every statement of the callback
+ * together, or rolls all of them back when it throws, and nothing else in the object runs in between because the callback is
+ * synchronous. A `read` runs the callback directly, which is consistent for the same reason. The object owns the database:
+ * the connection has no `close`.
+ */
+export declare function durableObjectSqliteConnection(storage: DurableObjectSqlStorage): SqliteConnection;
+export {};
+//# sourceMappingURL=sqlite-durable-object.d.ts.map

package/dist/sqlite-durable-object.js

@@ -0,0 +1,49 @@
+function binding(value) {
+    if (typeof value === 'bigint') {
+        if (value > BigInt(Number.MAX_SAFE_INTEGER) || value < BigInt(Number.MIN_SAFE_INTEGER))
+            throw new RangeError('SQLite integer is outside the safe range');
+        return Number(value);
+    }
+    return value instanceof Uint8Array ? value.buffer.slice(value.byteOffset, value.byteOffset + value.byteLength) : value;
+}
+/** Blobs come back as ArrayBuffers; the provider reads Uint8Arrays. */
+function row(raw) {
+    for (const key of Object.keys(raw)) {
+        const value = raw[key];
+        if (value instanceof ArrayBuffer)
+            raw[key] = new Uint8Array(value);
+    }
+    return raw;
+}
+/**
+ * A `SqliteConnection` over a SQLite-backed Durable Object's storage, for `openSqliteFileSystem({ connection })` and `createWorkspaceJournal(connection)`. Statements run on
+ * the object's own synchronous SQL API. A `write` transaction is `transactionSync`: SQLite commits every statement of the callback
+ * together, or rolls all of them back when it throws, and nothing else in the object runs in between because the callback is
+ * synchronous. A `read` runs the callback directly, which is consistent for the same reason. The object owns the database:
+ * the connection has no `close`.
+ */
+export function durableObjectSqliteConnection(storage) {
+    const exec = (sql, params) => storage.sql.exec(sql, ...params.map(binding));
+    let depth = 0;
+    return {
+        exec: sql => { exec(sql, []).toArray(); },
+        run: (sql, ...params) => { exec(sql, params).toArray(); },
+        get: (sql, ...params) => {
+            const [first] = exec(sql, params).toArray();
+            return first === undefined ? undefined : row(first);
+        },
+        all: (sql, ...params) => exec(sql, params).toArray().map(item => row(item)),
+        // A transaction opened inside another one joins it.
+        transaction: (mode, work) => {
+            if (mode === 'read' || depth > 0)
+                return work();
+            depth++;
+            try {
+                return storage.transactionSync(work);
+            }
+            finally {
+                depth--;
+            }
+        },
+    };
+}

package/dist/sqlite-filesystem.d.ts

@@ -0,0 +1,16 @@
+import type { FileSystem } from '@earendil-works/pi-durable/env';
+import type { SqliteConnection } from './sqlite.js';
+export interface SqliteFileSystemOptions {
+    /** The database. The host owns it: `cleanup` leaves it open. */
+    readonly connection: SqliteConnection;
+    /** Which workspace's rows: one database can hold several workspaces. */
+    readonly workspace: string;
+    /** The absolute working directory, created when missing (for example `/workspace`). Relative paths resolve against `cwd`. */
+    readonly cwd: string;
+}
+/** A Pi `FileSystem` plus the incarnation of its rows: new when the workspace was first created in this database. */
+export interface SqliteFileSystem extends FileSystem {
+    readonly incarnation: string;
+}
+export declare function openSqliteFileSystem(options: SqliteFileSystemOptions): SqliteFileSystem;
+//# sourceMappingURL=sqlite-filesystem.d.ts.map