snapback4 0.0.1 → 0.0.2

package/dist/client.js

@@ -0,0 +1,262 @@
+// The online tier (LLP 2000.000 §7.4): no store, no interpreter. Reads go
+// to the server and are `fresh` when it answered; an observed read re-runs
+// when a commit touches its tables; a write is sent with a client-minted id
+// and applies at most once, and waits as `pending` while the link is down.
+// Every word a screen reads is on the card (contract.ts).
+const ALPHABET = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
+/** A time-ordered 128-bit id: 48 bits of milliseconds, 80 bits of entropy, 26 base32 digits. */
+export function mintId(now = Date.now()) {
+    const bytes = new Uint8Array(10);
+    if (typeof crypto !== "undefined" && crypto.getRandomValues)
+        crypto.getRandomValues(bytes);
+    else
+        for (let i = 0; i < bytes.length; i++)
+            bytes[i] = Math.floor(Math.random() * 256);
+    let value = BigInt(now) << 80n;
+    for (const byte of bytes)
+        value = (value << 8n) | BigInt(byte);
+    let out = "";
+    for (let i = 0; i < 26; i++) {
+        out = ALPHABET[Number(value & 31n)] + out;
+        value >>= 5n;
+    }
+    return out;
+}
+export function createClient(options) {
+    const doFetch = options.fetch ?? globalThis.fetch.bind(globalThis);
+    const base = options.url.replace(/\/$/, "");
+    const headers = { "content-type": "application/json" };
+    if (options.persona)
+        headers["x-snapback-persona"] = options.persona;
+    const token = options.session?.token ?? options.token;
+    if (token)
+        headers.authorization = `Bearer ${token}`;
+    const viewer = options.persona ? `dev:${options.persona}` : options.session ? options.session.principal : null;
+    let link = viewer ? "online" : "signed-out";
+    let closed = false;
+    const aborter = new AbortController();
+    let seq = 0;
+    const linkListeners = new Set();
+    const watches = new Map();
+    const pending = [];
+    const setLink = (next) => {
+        if (link === next)
+            return;
+        link = next;
+        for (const listener of linkListeners)
+            listener(next);
+        if (next === "online") {
+            void flush();
+            for (const watch of watches.values())
+                void refresh(watch);
+        }
+        else {
+            for (const watch of watches.values()) {
+                if (watch.lastServer) {
+                    watch.snapshot = { ...watch.lastServer, fresh: false, since: watch.lastServerAt };
+                    notify(watch);
+                }
+            }
+        }
+    };
+    const offline = () => ({ code: "E_OFFLINE", family: "link", message: "the server is unreachable", retryable: true });
+    async function post(path, body) {
+        try {
+            const response = await doFetch(`${base}${path}`, { method: "POST", headers, body: JSON.stringify(body) });
+            const json = (await response.json());
+            if (response.status === 503)
+                return { ok: false };
+            if (link !== "online" && viewer)
+                setLink("online");
+            return { ok: true, json };
+        }
+        catch {
+            if (viewer)
+                setLink("offline");
+            return { ok: false };
+        }
+    }
+    async function runQuery(op, args) {
+        if (!viewer)
+            return { read: { denied: { code: "E_AUTH", family: "auth", message: "sign in to read" } }, tables: [], seq };
+        const result = await post(`/q/${op.name}`, { args });
+        if (!result.ok)
+            return { read: { denied: offline() }, tables: [], seq };
+        const json = result.json;
+        if (json.denied)
+            return { read: { denied: json.denied }, tables: [], seq };
+        const at = Number(json.seq ?? 0);
+        if (at > seq)
+            seq = at;
+        const next = json.next ?? null;
+        return { read: { data: json.data, complete: json.complete !== false, fresh: true, next }, tables: json.tables ?? [], seq: at };
+    }
+    function notify(watch) {
+        for (const subscriber of watch.subscribers)
+            subscriber();
+    }
+    async function refresh(watch) {
+        if (watch.inFlight) {
+            watch.dirty = true;
+            return;
+        }
+        watch.inFlight = true;
+        try {
+            const { read, tables } = await runQuery(watch.op, watch.args);
+            if (closed)
+                return;
+            if ("data" in read) {
+                watch.lastServer = read;
+                watch.lastServerAt = Date.now();
+                watch.tables = new Set(tables);
+                watch.snapshot = read;
+            }
+            else if ("denied" in read && read.denied.code === "E_OFFLINE" && watch.lastServer) {
+                watch.snapshot = { ...watch.lastServer, fresh: false, since: watch.lastServerAt };
+            }
+            else {
+                watch.snapshot = read;
+            }
+            notify(watch);
+        }
+        finally {
+            watch.inFlight = false;
+            if (watch.dirty) {
+                watch.dirty = false;
+                void refresh(watch);
+            }
+        }
+    }
+    let polling = false;
+    async function poll() {
+        if (polling)
+            return;
+        polling = true;
+        while (!closed && watches.size > 0) {
+            if (link !== "online") {
+                await new Promise((r) => setTimeout(r, 1000));
+                if (viewer && link === "offline") {
+                    const probe = await post("/q/__probe", {});
+                    if (probe.ok)
+                        setLink("online");
+                }
+                continue;
+            }
+            try {
+                const response = await doFetch(`${base}/changes?since=${seq}&wait=${options.waitSeconds ?? 25}`, { headers, signal: aborter.signal });
+                const json = (await response.json());
+                if (json.seq > seq) {
+                    seq = json.seq;
+                    const touched = new Set(json.tables);
+                    for (const watch of watches.values()) {
+                        if ([...watch.tables].some((t) => touched.has(t)))
+                            void refresh(watch);
+                    }
+                }
+            }
+            catch {
+                if (closed)
+                    break;
+                if (viewer)
+                    setLink("offline");
+                await new Promise((r) => setTimeout(r, 1000));
+            }
+        }
+        polling = false;
+    }
+    async function send(entry) {
+        const result = await post(`/m/${entry.op.name}`, { id: entry.id, args: entry.args });
+        if (!result.ok)
+            return false;
+        const json = result.json;
+        if (json.state === "sent") {
+            const at = Number(json.seq ?? 0);
+            if (at > seq)
+                seq = at;
+            entry.resolve({ state: "sent", id: entry.id, seq: at });
+            for (const watch of watches.values())
+                void refresh(watch);
+        }
+        else {
+            entry.resolve({ state: "failed", id: entry.id, why: json.why ?? offline() });
+        }
+        return true;
+    }
+    async function flush() {
+        while (pending.length > 0 && link === "online") {
+            const entry = pending[0];
+            const sent = await send(entry);
+            if (!sent)
+                return;
+            pending.shift();
+        }
+    }
+    const client = {
+        async query(op, args) {
+            return (await runQuery(op, args)).read;
+        },
+        observe(op, args) {
+            const key = `${op.name}:${JSON.stringify(args)}`;
+            let watch = watches.get(key);
+            if (!watch) {
+                watch = { op: op, args, key, tables: new Set(), snapshot: { loading: true }, lastServer: null, lastServerAt: 0, subscribers: new Set(), inFlight: false, dirty: false };
+                watches.set(key, watch);
+                void refresh(watch);
+                void poll();
+            }
+            const own = watch;
+            const mine = new Set();
+            return {
+                getSnapshot: () => own.snapshot,
+                subscribe(notifyMe) {
+                    mine.add(notifyMe);
+                    own.subscribers.add(notifyMe);
+                    return () => {
+                        mine.delete(notifyMe);
+                        own.subscribers.delete(notifyMe);
+                    };
+                },
+                close() {
+                    for (const s of mine)
+                        own.subscribers.delete(s);
+                    if (own.subscribers.size === 0)
+                        watches.delete(own.key);
+                },
+            };
+        },
+        async mutate(op, args) {
+            const id = mintId();
+            if (!viewer)
+                return { state: "failed", id, why: { code: "E_AUTH", family: "auth", message: "sign in to write" } };
+            let settle;
+            const settled = new Promise((resolve) => { settle = resolve; });
+            const entry = { id, op: op, args, resolve: settle };
+            if (link === "offline" || pending.length > 0) {
+                pending.push(entry);
+                void flush();
+                return { state: "pending", id };
+            }
+            pending.push(entry);
+            const sent = await send(entry);
+            if (sent) {
+                pending.shift();
+                return settled;
+            }
+            // Durable admission on this device: the write waits for the link.
+            return { state: "pending", id };
+        },
+        link: () => link,
+        onLink(listener) {
+            linkListeners.add(listener);
+            return () => linkListeners.delete(listener);
+        },
+        viewer: () => viewer,
+        async close() {
+            closed = true;
+            aborter.abort();
+            watches.clear();
+            linkListeners.clear();
+        },
+    };
+    return client;
+}

package/dist/local.d.ts

@@ -0,0 +1,34 @@
+import type { Client } from "./contract.ts";
+import { Replica } from "./replica/replica.ts";
+import { type Row, type SchemaJson, type Store } from "./replica/store.ts";
+import { type Session, type SessionStore } from "./auth.ts";
+export interface LocalOptions {
+    readonly url: string;
+    /** A development persona (loopback only): `alice` acts as `dev:alice`. */
+    readonly persona?: string;
+    /** A session from `guest()`, `login()` or `signup()`; the client keeps it
+     * and restores it on the next start, so an app passes it once. */
+    readonly session?: Session;
+    /** With no session kept for this server, mint a guest (`use identity guests`). */
+    readonly guest?: boolean;
+    /** Where the session is kept: `localStorage` by default, memory without one. */
+    readonly sessionStore?: SessionStore;
+    readonly fetch?: typeof fetch;
+    /** `"indexeddb"` on the web (the default when available), `"memory"` for
+     * tests, or an opener for another store (`openSqlite` from
+     * `snapback4/replica` on Expo and Node). */
+    readonly store?: "indexeddb" | "memory" | {
+        open(name: string, schema: SchemaJson): Promise<Store>;
+    };
+    readonly waitSeconds?: number;
+}
+export type LocalClient = Client & {
+    readonly replica: Replica;
+    sync(): Promise<void>;
+    /** The session this device holds, or null once the server has refused it. */
+    session(): Session | null;
+    /** End the session on the server and forget it here; the client closes. */
+    signOut(): Promise<void>;
+};
+export declare function createLocalClient(options: LocalOptions): Promise<LocalClient>;
+export type { Row };

package/dist/local.js

@@ -0,0 +1,358 @@
+// The local-first tier (LLP 2000.000 §7): a replica of the viewer's
+// partitions, a durable outbox of client-minted writes, and the interpreter,
+// on the same card as the online tier. Queries run locally and are
+// `complete` inside the horizon; `fresh` says the replica has everything the
+// server had at the last sync; a predictable mutation renders its rows as
+// `pending` before the server confirms them.
+import { mintId } from "./client.js";
+import { Interpreter, Refused } from "./replica/interpreter.js";
+import { Replica } from "./replica/replica.js";
+import { MemoryStore, openIndexedDb } from "./replica/store.js";
+import { defaultSessionStore, forgetSession, guest, keepSession, logout, restoreSession } from "./auth.js";
+export async function createLocalClient(options) {
+    const doFetch = options.fetch ?? globalThis.fetch.bind(globalThis);
+    const base = options.url.replace(/\/$/, "");
+    const headers = { "content-type": "application/json" };
+    const sessions = options.sessionStore ?? defaultSessionStore;
+    let session = null;
+    if (options.persona)
+        headers["x-snapback-persona"] = options.persona;
+    else {
+        // The device's session: the one passed, else the one kept for this
+        // server, else a fresh guest when the app allows one.
+        if (options.session) {
+            session = options.session;
+            await keepSession(base, session, sessions);
+        }
+        else
+            session = await restoreSession(base, sessions);
+        if (!session && options.guest) {
+            const signedIn = await guest(base, doFetch);
+            if (!signedIn.ok)
+                throw new Error(`createLocalClient: ${signedIn.why.code}: ${signedIn.why.message}`);
+            session = signedIn.session;
+            await keepSession(base, session, sessions);
+        }
+        if (!session)
+            throw new Error(`createLocalClient: no session for ${base}; pass one from guest(), login() or signup(), or say guest: true`);
+        headers.authorization = `Bearer ${session.token}`;
+    }
+    const viewer = (options.persona ? `dev:${options.persona}` : session.principal);
+    const principal = viewer;
+    let sessionDead = false;
+    const refusedSession = async (denied) => {
+        if (session && !sessionDead && denied?.code === "E_AUTH") {
+            sessionDead = true;
+            await forgetSession(base, sessions);
+        }
+    };
+    const backend = await loadBackend(doFetch, base, headers);
+    const storeName = `snapback4:${base}:${viewer}`;
+    const useIdb = options.store === "indexeddb" || (options.store === undefined && typeof indexedDB !== "undefined");
+    const store = typeof options.store === "object" ? await options.store.open(storeName, backend.schema) : useIdb ? await openIndexedDb(storeName, backend.schema) : new MemoryStore(backend.schema);
+    let link = "online";
+    let closed = false;
+    let seq = 0;
+    const aborter = new AbortController();
+    const linkListeners = new Set();
+    const watches = new Map();
+    const offline = () => ({ code: "E_OFFLINE", family: "link", message: "the server is unreachable", retryable: true });
+    const setLink = (next) => {
+        if (link === next)
+            return;
+        link = next;
+        for (const listener of linkListeners)
+            listener(next);
+        if (next === "online")
+            void flush();
+        for (const watch of watches.values())
+            void rerun(watch);
+    };
+    async function post(path, body) {
+        try {
+            const response = await doFetch(`${base}${path}`, { method: "POST", headers, body: JSON.stringify(body) });
+            if (response.status >= 500)
+                return { ok: false };
+            const json = (await response.json());
+            if (link !== "online")
+                setLink("online");
+            return { ok: true, json };
+        }
+        catch {
+            setLink("offline");
+            return { ok: false };
+        }
+    }
+    const replica = new Replica(store, backend.schema, {
+        async sync(from, limit) {
+            try {
+                const response = await doFetch(`${base}/sync?from=${from}&limit=${limit}`, { headers });
+                if (response.status >= 500)
+                    return { denied: offline() };
+                const page = (await response.json());
+                if (page.denied) {
+                    await refusedSession(page.denied);
+                    return { denied: page.denied };
+                }
+                if (link !== "online")
+                    setLink("online");
+                if (page.watermark > seq)
+                    seq = page.watermark;
+                if (page.generation !== undefined && page.generation !== backend.generation) {
+                    // Day two: the server adopted a new generation. Load it, then let
+                    // the replica re-derive the partition on its next round.
+                    const next = await loadBackend(doFetch, base, headers);
+                    backend.generation = next.generation;
+                    backend.schema = next.schema;
+                    backend.programs = next.programs;
+                    replica.adopt(next.schema, next.generation);
+                    return { denied: { code: "E_GENERATION", family: "generation", message: "the backend changed; re-deriving the partition", retryable: true } };
+                }
+                return page;
+            }
+            catch {
+                setLink("offline");
+                return { denied: offline() };
+            }
+        },
+    }, backend.generation);
+    // Every applied batch re-runs the queries whose tables it touched.
+    replica.onChange((touched) => {
+        for (const watch of watches.values())
+            if ([...watch.tables].some((t) => touched.has(t)))
+                void rerun(watch);
+    });
+    async function waitForChange() {
+        if (link !== "online") {
+            await new Promise((r) => setTimeout(r, 1000));
+            const probe = await post("/q/__probe", {});
+            if (probe.ok)
+                setLink("online");
+            return;
+        }
+        try {
+            const response = await doFetch(`${base}/changes?since=${seq}&wait=${options.waitSeconds ?? 25}`, { headers, signal: aborter.signal });
+            const json = (await response.json());
+            if (json.seq > seq)
+                seq = json.seq;
+        }
+        catch {
+            if (closed)
+                return;
+            setLink("offline");
+            await new Promise((r) => setTimeout(r, 1000));
+        }
+    }
+    async function runLocal(op, args) {
+        const program = backend.programs[op.name];
+        if (!program)
+            return { read: { denied: { code: "E_OP", family: "op", message: `unknown query ${op.name}` } }, tables: new Set() };
+        try {
+            const outcome = await store.read((tx) => new Interpreter(tx, backend.schema, { viewer: principal, args: args, now: Date.now(), newIds: [], mint: mintId }, "query").run(program));
+            const read = { data: outcome.data, complete: outcome.complete, fresh: link === "online" && replica.isCaughtUp, next: outcome.next, ...(link === "online" && replica.isCaughtUp ? {} : { since: lastSyncAt }) };
+            return { read, tables: outcome.tables };
+        }
+        catch (error) {
+            if (error instanceof Refused)
+                return { read: { denied: error.refusal }, tables: new Set() };
+            throw error;
+        }
+    }
+    let lastSyncAt = Date.now();
+    function notify(watch) {
+        for (const subscriber of watch.subscribers)
+            subscriber();
+    }
+    async function rerun(watch) {
+        if (watch.running) {
+            watch.dirty = true;
+            return;
+        }
+        watch.running = true;
+        try {
+            const { read, tables } = await runLocal(watch.op, watch.args);
+            if (closed)
+                return;
+            watch.tables = tables;
+            watch.snapshot = read;
+            notify(watch);
+        }
+        finally {
+            watch.running = false;
+            if (watch.dirty) {
+                watch.dirty = false;
+                void rerun(watch);
+            }
+        }
+    }
+    // ----- the outbox -----
+    async function queued() {
+        return store.read(async (tx) => (await tx.side("outbox").all()).map((e) => e.value).sort((a, b) => (a.id < b.id ? -1 : 1)));
+    }
+    let flushing = false;
+    async function flush() {
+        if (flushing)
+            return;
+        flushing = true;
+        try {
+            for (const entry of await queued()) {
+                if (link !== "online")
+                    return;
+                const result = await post(`/m/${entry.op}`, { id: entry.id, args: entry.args, newIds: entry.newIds });
+                if (!result.ok)
+                    return;
+                const json = result.json;
+                await store.write(async (tx) => {
+                    await tx.side("outbox").delete(entry.id);
+                    if (json.state !== "sent") {
+                        // The prediction is withdrawn: the rows it wrote go, the stream
+                        // restores anything it replaced.
+                        for (const key of entry.predicted) {
+                            const [table, id] = key.split("/");
+                            const row = await tx.get(table, id);
+                            if (row && row.pending)
+                                await tx.delete(table, id);
+                        }
+                    }
+                });
+                if (json.denied)
+                    await refusedSession(json.denied);
+                settled.get(entry.id)?.(json.state === "sent" ? { state: "sent", id: entry.id, seq: Number(json.seq ?? 0) } : { state: "failed", id: entry.id, why: json.why ?? json.denied ?? offline() });
+                settled.delete(entry.id);
+                if (json.state === "sent" && Number(json.seq) > seq)
+                    seq = Number(json.seq);
+                if (json.state === "sent")
+                    await replica.syncOnce();
+                else
+                    for (const watch of watches.values())
+                        void rerun(watch);
+            }
+        }
+        finally {
+            flushing = false;
+        }
+    }
+    const settled = new Map();
+    const client = {
+        replica,
+        async sync() {
+            await replica.syncOnce();
+            lastSyncAt = Date.now();
+        },
+        async query(op, args) {
+            return (await runLocal(op, args)).read;
+        },
+        observe(op, args) {
+            const key = `${op.name}:${JSON.stringify(args)}`;
+            let watch = watches.get(key);
+            if (!watch) {
+                watch = { op: op, args, key, tables: new Set(), snapshot: { loading: true }, lastServerAt: 0, subscribers: new Set(), running: false, dirty: false };
+                watches.set(key, watch);
+                void rerun(watch);
+            }
+            const own = watch;
+            const mine = new Set();
+            return {
+                getSnapshot: () => own.snapshot,
+                subscribe(listener) {
+                    mine.add(listener);
+                    own.subscribers.add(listener);
+                    return () => { mine.delete(listener); own.subscribers.delete(listener); };
+                },
+                close() {
+                    for (const s of mine)
+                        own.subscribers.delete(s);
+                    if (own.subscribers.size === 0)
+                        watches.delete(own.key);
+                },
+            };
+        },
+        async mutate(op, args) {
+            const id = mintId();
+            const program = backend.programs[op.name];
+            if (!program)
+                return { state: "failed", id, why: { code: "E_OP", family: "op", message: `unknown mutation ${op.name}` } };
+            const newIds = [];
+            const mint = () => { const minted = mintId(); newIds.push(minted); return minted; };
+            // Predict: run the mutation over the replica; its rows render as pending.
+            let predicted = [];
+            let refused = null;
+            try {
+                await store.write(async (tx) => {
+                    const interpreter = new Interpreter(tx, backend.schema, { viewer: principal, args: args, now: Date.now(), newIds: [], mint }, "mutation");
+                    await interpreter.run(program);
+                    predicted = interpreter.writes.map((w) => `${w.table}/${w.row.id}`);
+                    await tx.side("outbox").put(id, { id, op: op.name, args, newIds: [...newIds], predicted });
+                });
+            }
+            catch (error) {
+                if (!(error instanceof Refused))
+                    throw error;
+                if (error.refusal.code === "E_PREDICT") {
+                    // Not predictable here: queue it without local rows.
+                    await store.write((tx) => tx.side("outbox").put(id, { id, op: op.name, args, newIds: [], predicted: [] }));
+                }
+                else
+                    refused = error.refusal;
+            }
+            if (refused)
+                return { state: "failed", id, why: refused };
+            for (const watch of watches.values())
+                void rerun(watch);
+            const outcome = new Promise((resolve) => settled.set(id, resolve));
+            void flush();
+            if (link !== "online")
+                return { state: "pending", id };
+            const first = await Promise.race([outcome, new Promise((resolve) => setTimeout(() => resolve({ state: "pending", id }), 4_000))]);
+            return first;
+        },
+        link: () => link,
+        onLink(listener) {
+            linkListeners.add(listener);
+            return () => linkListeners.delete(listener);
+        },
+        viewer: () => viewer,
+        session: () => (sessionDead ? null : session),
+        async signOut() {
+            if (session && !sessionDead)
+                await logout(base, session.token, doFetch);
+            await forgetSession(base, sessions);
+            sessionDead = true;
+            await client.close();
+        },
+        async close() {
+            closed = true;
+            aborter.abort();
+            watches.clear();
+            linkListeners.clear();
+            await replica.close();
+        },
+    };
+    // First: catch up, then re-apply any predictions still in the outbox.
+    await client.sync();
+    await reapplyPredictions();
+    replica.follow(waitForChange);
+    void flush();
+    async function reapplyPredictions() {
+        for (const entry of await queued()) {
+            const program = backend.programs[entry.op];
+            if (!program || entry.predicted.length === 0)
+                continue;
+            try {
+                await store.write(async (tx) => {
+                    const interpreter = new Interpreter(tx, backend.schema, { viewer: principal, args: entry.args, now: Date.now(), newIds: [...entry.newIds], mint: mintId }, "mutation");
+                    await interpreter.run(program);
+                });
+            }
+            catch {
+                // The server will judge it; the rows stay absent until then.
+            }
+        }
+    }
+    return client;
+}
+async function loadBackend(doFetch, base, headers) {
+    const response = await doFetch(`${base}/schema`, { headers });
+    const json = (await response.json());
+    return { generation: json.generation, schema: json.schema, programs: Object.fromEntries(json.programs.map((p) => [p.name, p])) };
+}

package/dist/replica/cursor.d.ts

@@ -0,0 +1,15 @@
+export type ColumnTypeJson = unknown;
+export interface CursorPosition {
+    table: string;
+    index: string;
+    order: "Asc" | "Desc";
+    suffix: {
+        name: string;
+        kind: ColumnTypeJson;
+    }[];
+    values: unknown[];
+}
+/** Canonical JSON: compact, object keys sorted, as serde_json writes a BTreeMap. */
+export declare function canonicalJson(value: unknown): string;
+export declare function encodeCursor(position: CursorPosition): string;
+export declare function decodeCursor(token: string): CursorPosition | null;