slopkit 0.1.2 → 0.3.0

package/dist/server/web.js

@@ -5,7 +5,7 @@
  * from the page's own Origin. Responses carry a strict CSP and no framing.
  *
  * Routes are contract endpoints: the request is checked against its schema before the handler runs and the reply
- * after, so neither side can drift from the contract. Failures answer `{ kind, message }` with the kind's status.
+ * after, so neither side can drift from the contract. Failures answer `{ kind, message, path? }` with the kind's status.
  * The socket is a hint channel: the app sends small messages (pokes, pings); nothing correct depends on it.
  * Every API request is logged with an id, status, time and whether a person or a service asked.
  */
@@ -32,12 +32,17 @@ const SECURITY = {
     "x-frame-options": "DENY",
     "content-security-policy": "default-src 'self'; connect-src 'self'; img-src 'self' data:; style-src 'self'; script-src 'self'; manifest-src 'self'; worker-src 'self'; frame-ancestors 'none'; base-uri 'none'; form-action 'self'",
 };
-/** A handler's refusal, answered as a typed failure. */
+/**
+ * A handler's refusal, answered as a typed failure: the kit's error body, so the page can tell it from a proxy's.
+ * `path` names where a request broke its schema (`request.commands[1].command.value`).
+ */
 export class Refusal extends Error {
     kind;
-    constructor(kind, message) {
+    path;
+    constructor(kind, message, path) {
         super(message);
         this.kind = kind;
+        this.path = path;
     }
 }
 export function route(endpoint, handle) {
@@ -52,7 +57,7 @@ export function route(endpoint, handle) {
             }
             catch (error) {
                 if (error instanceof Invalid) {
-                    throw new Refusal("invalid", error.message);
+                    throw new Refusal("invalid", error.message, error.path);
                 }
                 throw error;
             }
@@ -90,18 +95,30 @@ function send(request, response, status, body, headers = {}) {
     });
     response.end(request.method === "HEAD" ? undefined : bytes);
 }
-function failure(request, response, kind, message) {
-    send(request, response, STATUS[kind], JSON.stringify({ kind, message }), {
-        "content-type": "application/json",
-    });
+function failure(request, response, kind, message, path) {
+    send(request, response, STATUS[kind], JSON.stringify({ kind, message, ...(path === undefined ? {} : { path }) }), { "content-type": "application/json" });
 }
+/**
+ * The body as JSON: its bytes collected and counted against `limit`, then decoded once, so a character split between
+ * chunks arrives whole. Bytes that aren't UTF-8 are refused, never replaced.
+ */
 async function readBody(request, limit) {
-    let text = "";
+    const chunks = [];
+    let size = 0;
     for await (const chunk of request) {
-        text += String(chunk);
-        if (text.length > limit) {
+        const bytes = Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk));
+        size += bytes.length;
+        if (size > limit) {
             throw new Refusal("invalid", "the request is too large");
         }
+        chunks.push(bytes);
+    }
+    let text;
+    try {
+        text = new TextDecoder("utf-8", { fatal: true }).decode(Buffer.concat(chunks));
+    }
+    catch {
+        throw new Refusal("invalid", "the request is not UTF-8");
     }
     try {
         return text ? JSON.parse(text) : {};
@@ -212,7 +229,7 @@ export async function serveWeb(options) {
                     reason: message,
                 });
             }
-            failure(request, response, kind, error instanceof Refusal ? message : "the server failed; see its log");
+            failure(request, response, kind, error instanceof Refusal ? message : "the server failed; see its log", error instanceof Refusal ? error.path : undefined);
         }
         log(status < 400 ? "info" : "warn", "request", {
             request: caller.request,

package/dist/sync.d.ts

@@ -5,23 +5,47 @@
  * headless simulation over real stores and in the browser alike.
  *
  * Invariants it owns:
- * - **The replica only moves forward.** A pull applies only if newer (or a reset for another dataset). The disk commit
- *   is decided again against what the disk holds, inside its own transaction (`commitPlan`), so another tab or a
- *   failed write can't make the disk go back or skip a patch.
+ * - **The replica only moves forward.** A delta applies only to the same dataset with `since ≤ copy.revision ≤
+ *   reply.revision`; only a reset replaces the copy (a late one is dropped), and a reply it can't follow asks for a
+ *   real reset instead of leaving a gap. The disk commit is decided again against what the disk holds, inside its own
+ *   transaction (`commitPlan`), so another tab or a failed write can't make the disk go back or skip a patch.
+ * - **A copy never claims more history than it holds.** It is complete or partial (`History`): every row it holds is
+ *   the server's row at its revision, and a partial copy holds every row at or above its cursor, so every row at or
+ *   above `through`. The first reply draws the newest rows at once; the cursor moves only when a reply answers the
+ *   copy's own `next`, a reply without a page never changes it, and a row merged below `through` never deepens it.
+ *   The disk takes a page's history only from the cursor it moved from, in the transaction that writes its rows.
+ * - **A partial copy owes its next page**, back to back, until it is complete; a reply that doesn't move it on counts
+ *   as a failed pull, for backoff. An old server's reply to a partial copy asks for its whole copy instead.
+ * - **Only a complete copy is checked.** No fingerprint is asked for or compared while the copy is partial.
+ * - **A chunk costs its own size.** Merging a reply doesn't copy the tables it lands in (`Layered`).
  * - **Observed is not saved.** `saved` is what the disk is known to hold; a failed commit is retried whole until the
- *   disk catches up, and until then the page says so.
+ *   disk catches up (a later page the disk takes as a delta under its own history doesn't), and until then the page
+ *   says so.
  * - **A pull is owed while the server is ahead.** `target` is the newest revision the server is known to have (pokes,
  *   which also beat every 20 s, push replies, receipts); while the replica is behind it a pull is in flight or
  *   scheduled, whatever the socket says. Liveness, the known head and the last reconciliation are separate facts.
  * - **A command id is never reused.** Each page load is a new client with its own numbers; commands loaded from an
  *   earlier page keep theirs.
  * - **Nothing is sent before it is kept.** An intent the device can't keep fails at once, visibly, and is never sent.
+ *   A push is journalled before it goes: its commands are kept as `sending` (one write per push), so a page that dies
+ *   mid-push leaves them uncertain on disk, and none goes unless that write lands.
  * - **Every command reaches an outcome, and is settled only once the replica holds its effects** (a receipt names the
- *   revision that made it visible); until then a pull is owed.
+ *   revision that made it visible; on a partial copy, only a pull reply that carried the receipt, with the rows it
+ *   names, settles it); until then a pull is owed, and names the commands it waits on, any page's.
  * - **Every waiting state ends.** Pulling, pushing, retrying and saving have deadlines or backoff; storage that is slow
  *   to load or keep is said (the page goes on from the server meanwhile), and its late answer still counts: a slow
  *   write is not a failed one.
  * - **An intent belongs to the dataset it was made against**: the server refuses it against a replacement.
+ * - **A refusal proves only that attempt didn't act.** Only the kit's own error body is final; anything else may have
+ *   acted and leaves the command unknown, kept so. A command an attempt of which may have acted never becomes a final
+ *   failure: a refusal naming it parks it (never sent again, still named in pulls, done when a receipt comes). A schema
+ *   refusal naming one command of a push is that command's alone; the rest return to what they were and go again.
+ * - **A push fits the server's bounds**: at most `pushMax` commands and `pushBytes` bytes, oldest first, stopping at
+ *   the first command that doesn't fit. One too large even alone is answered at the tap and never kept; one already
+ *   kept is refused (or parked) and passed over, so it never strands the rest.
+ * - **The outbox is bounded across tabs.** The store admits a new command inside its own write transaction, from its
+ *   own count; one it has no room for is answered and never retained. Kept commands always update and are never
+ *   dropped for room.
  */
 import type { Failure } from "./contract.ts";
 import type { Schema } from "./schema.ts";
@@ -65,12 +89,39 @@ export declare function table<T, P, R>(def: {
     get: (tables: T) => ReadonlyMap<Key, R>;
     set: (tables: T, rows: ReadonlyMap<Key, R>) => T;
 }): Lens<T, P>;
+/**
+ * How much of the server's history a copy holds. Complete: every row. Partial: every row at or above the keyset cursor
+ * `next` (the server's opaque cursor of the next older page), so every row at or above `through` (the fully covered
+ * boundary, as the app formats it; null while no order group is whole); `held` of `total` is progress, not a claim.
+ */
+export type History = {
+    kind: "complete";
+} | {
+    kind: "partial";
+    next: string;
+    through: string | null;
+    held: number;
+    total: number;
+};
+/**
+ * A paged reply's place in the history: `from` is the cursor it answered (null on a reset's first page), `next` the
+ * next older one (null once complete), `through`, `held` and `total` as in `History`, at the reply's revision.
+ */
+export type Page = {
+    from: string | null;
+    next: string | null;
+    through: string | null;
+    held: number;
+    total: number;
+};
 export type Replica<T, S> = {
     dataset: string | null;
     revision: number;
     tables: T;
     /** What the server says about itself, read with every pull. */
     server: S | null;
+    /** How much of the history it holds; absent (a copy from before paging) is complete. */
+    history?: History;
 };
 /** A pull reply as sync sees it: rows changed since the pull's `since`, or everything (`reset`). */
 export type Patch<P, S> = {
@@ -80,12 +131,18 @@ export type Patch<P, S> = {
     rows: P;
     server: S;
     checksum?: string;
+    /** A paging server's place in the history: absent from an old server, whose reset is the whole copy. */
+    page?: Page;
 };
-/** A command's outcome as the server recorded it, and the revision at which its effects are visible. */
+/**
+ * A command's outcome as the server recorded it, and the revision at which its effects are visible. `client` names an
+ * earlier page's command (absent: the pull's or push's own client).
+ */
 export type Receipt<O> = {
     id: number;
     outcome: O;
     revision: number;
+    client?: string;
 };
 export type CommandState<O> = {
     kind: "saving";
@@ -93,9 +150,16 @@ export type CommandState<O> = {
     kind: "queued";
 } | {
     kind: "sending";
-} | {
+}
+/**
+ * An attempt's outcome was lost: it may have acted. `parked`: the server refused it by name since, which proves only
+ * that attempt didn't act, so it is never sent again and waits on a pull to bring the receipt an earlier one left; it
+ * needs the person's attention meanwhile.
+ */
+ | {
     kind: "unknown";
     failure: string;
+    parked?: true;
 } | {
     kind: "done";
     outcome: O;
@@ -131,6 +195,22 @@ export type Connection = {
     kind: "incompatible";
     failure: string;
 };
+/**
+ * The outbox's room, as a closed subject for the app's state table: full when it holds `max` commands. `waiting`
+ * (unsent or unknown) needs a connection; `finished` (done, kept until dismissed) needs the person to dismiss them.
+ */
+export type OutboxState = {
+    kind: "ok";
+} | {
+    kind: "full";
+    waiting: number;
+    finished: number;
+    max: number;
+};
+/** The store's answer to a new command it had no room for: its own counts, across every tab. */
+export type OutboxFull = Extract<OutboxState, {
+    kind: "full";
+}>;
 /** This device's copy: fine, failing (writes are retried), or forgotten under this page by another tab. */
 export type Storage = {
     kind: "ok";
@@ -160,8 +240,18 @@ export type Model<T, S, C, O> = {
         writing: number;
         failures: number;
         nextAt: number;
+        /**
+         * A write failed and only a whole one (or one the disk took whole) repairs it: a later page landing as a delta
+         * doesn't, since the disk still lacks the failed page's rows.
+         */
+        owed: boolean;
     };
     target: number;
+    /**
+     * A reset this copy asks for: `paged` after a reply it couldn't apply (another dataset without a reset, a gap),
+     * `whole` (no `page`, as an old server understands) after an old server answered a partial copy.
+     */
+    restart: "paged" | "whole" | null;
     /** When a pull last succeeded: freshness, apart from the socket's liveness. */
     reconciledAt: number | null;
     connection: Connection;
@@ -186,9 +276,23 @@ export type Model<T, S, C, O> = {
         kind: "pushing";
         client: string;
         ids: readonly number[];
+        /** Each command's state before this attempt, by position in `ids`: what a refusal restores. */
+        was: readonly CommandState<O>[];
         failures: number;
     };
     commands: readonly Pending<C, O>[];
+    /**
+     * The most commands the outbox admits, and the store's counts when it last refused one for room (it is shared with
+     * other tabs, whose commands this page doesn't hold); cleared once one is admitted or this page drops some.
+     */
+    outbox: {
+        max: number;
+        full: OutboxFull | null;
+    };
+    /** Where the next pull's list of waiting commands starts, when more wait than one pull names. */
+    asking: number;
+    /** Commands (`client:id`) whose receipt came in a pull reply this copy applied, so with the rows it names. */
+    carried: ReadonlySet<string>;
     /** Commands an earlier page kept that this version can't read: left on disk, and said. */
     unreadable: number;
     visible: boolean;
@@ -242,11 +346,24 @@ export type Msg<T, P, S, C, O> = {
     failure: Failure;
     now: number;
 }
-/** The disk holds the replica at `revision` (perhaps newer than asked, from another tab). */
+/** A push's in-flight mark couldn't be kept, so it was never sent. */
+ | {
+    type: "unsent";
+    client: string;
+    ids: number[];
+    reason: string;
+    replaced: boolean;
+    now: number;
+}
+/**
+ * The disk holds the replica at `revision` (perhaps newer than asked, from another tab); `whole: false` when it took
+ * the patch as a delta under its own, other history.
+ */
  | {
     type: "committed";
     dataset: string;
     revision: number;
+    whole?: boolean;
     now: number;
 } | {
     type: "commitFailed";
@@ -265,6 +382,13 @@ export type Msg<T, P, S, C, O> = {
     reason: string;
     now: number;
 }
+/** The outbox had no room for a new command: it was not kept. */
+ | ({
+    type: "full";
+    client: string;
+    id: number;
+    now: number;
+} & Omit<OutboxFull, "kind">)
 /** Finished commands left the outbox (`failure` if not: they fade again on the next load). */
  | {
     type: "dropped";
@@ -311,6 +435,8 @@ export type Commit<T, S> = {
     reset: boolean;
     /** The revision the patch starts from: the disk takes it as a delta only if it is at least there. */
     base: number;
+    /** The cursor the copy held before this patch: the disk adopts the patch's history only from that same cursor. */
+    from?: string | null;
     /** The dataset this page last knew the disk to hold: the only one it may replace with another. */
     replaces: string | null;
 };
@@ -322,6 +448,13 @@ export type Effect<T, S, C, O> = {
     dataset: string | null;
     since: number;
     verify: boolean;
+    /** The older page wanted (null: none, but a paged reset is understood); absent asks an old server's whole reply. */
+    page?: string | null;
+    /** Commands still waiting on an outcome or on their effects, any page's: their receipts come with their rows. */
+    commands: {
+        client: string;
+        id: number;
+    }[];
 } | {
     kind: "push";
     client: string;
@@ -337,9 +470,12 @@ export type Effect<T, S, C, O> = {
     }[];
 } | ({
     kind: "commit";
-} & Commit<T, S>) | {
+} & Commit<T, S>)
+/** Keep a command: a new one only while the outbox holds fewer than `max` (decided by the store). */
+ | {
     kind: "keep";
     pending: Pending<C, O>;
+    max: number;
 } | {
     kind: "drop";
     keys: {
@@ -380,6 +516,13 @@ export type Spec<T, P, S, C, O> = {
     resolved?: (pending: Pending<C, O>, model: Model<T, S, C, O>) => boolean;
     /** The most commands one push carries: the push endpoint's own bound. Default `PUSH_MAX`. */
     pushMax?: number;
+    /**
+     * The most UTF-8 bytes of one push request, encoded whole: the push endpoint's body limit (`serveWeb.bodyLimit`)
+     * must be at least this. Default `PUSH_BYTES`.
+     */
+    pushBytes?: number;
+    /** The most commands the device's outbox admits, shared by every tab. Default `OUTBOX_MAX`. */
+    outboxMax?: number;
 };
 /** The socket must be heard this often (the server pokes every 20 s); quieter, the page polls. */
 export declare const SOCKET_DEADLINE_MS = 45000;
@@ -389,37 +532,99 @@ export declare const POLL_MS = 4000;
 export declare const STORAGE_DEADLINE_MS = 3000;
 /** Commands per push unless the spec says otherwise; the rest wait for the next push. */
 export declare const PUSH_MAX = 50;
+/** UTF-8 bytes of one push request unless the spec says otherwise (48 KiB). */
+export declare const PUSH_BYTES = 49152;
+/** Commands the outbox admits unless the spec says otherwise; updates to kept ones always are. */
+export declare const OUTBOX_MAX = 500;
 /** Settled commands stay drawn this long. */
 export declare const DONE_KEEP_MS = 60000;
+/**
+ * Where the outbox stands: full once it holds `max` commands, by this page's count or, failing that, by the store's
+ * last refusal (other tabs' commands count too). Unreadable kept commands take room as well.
+ */
+export declare function deriveOutboxState<T, S, C, O>(model: Model<T, S, C, O>): OutboxState;
 /** Whether the server can be asked now. */
 export declare function reachable(connection: Connection): boolean;
-/** Whether the replica holds this command's effects. */
+/**
+ * Whether the replica holds this command's effects: it is done, and the copy is at its revision and either complete or
+ * holding the rows its receipt names (a pull reply carried them). One that failed on the page has none.
+ */
 export declare function settled<T, S, C, O>(model: Model<T, S, C, O>, pending: Pending<C, O>): boolean;
-/** Whether what the page shows is also on the disk. */
+/**
+ * Whether what the page shows is also on the disk: by revision only, so tabs at different cursors never chase each
+ * other's writes. A failed write is owed again even at the same revision (a page that failed to land).
+ */
 export declare function saved<T, S, C, O>(model: Model<T, S, C, O>): boolean;
 /**
  * What a commit does to the disk, decided inside the disk's own transaction from what it holds: nothing when the disk
- * already has this or newer (another tab got there), the patch alone when the disk is at least at its base, else the
- * whole replica, so a skipped or failed patch is never covered by a later checkpoint. A page may replace the disk's
+ * already has this or newer (another tab got there; a complete copy at the same revision is newer than any page), the
+ * patch alone when the disk is at least at its base, else the whole replica, so a skipped or failed patch is never
+ * covered by a later checkpoint. A delta keeps the disk's own history, and takes the patch's only when the disk is at
+ * the cursor the patch moved from (`adopt`): coverage never lands without its rows. A page may replace the disk's
  * dataset only with one it moved to from that very dataset (`replaces`): a tab still on a dataset the server has since
  * replaced is `stale` and never writes it back.
  */
 export declare function commitPlan(stored: {
     dataset: string | null;
     revision: number;
+    history?: History;
 }, commit: {
     dataset: string | null;
     revision: number;
     reset: boolean;
     base: number;
     replaces: string | null;
-}): "skip" | "delta" | "whole" | "stale";
+    from?: string | null;
+}): "skip" | "delta" | "adopt" | "whole" | "stale";
+/** How much history the page holds, as a closed subject for the app's state table. */
+export type HistoryState = {
+    kind: "loading";
+} | {
+    kind: "none";
+} | {
+    kind: "complete";
+} | {
+    kind: "partial";
+    through: string | null;
+    held: number;
+    total: number;
+};
+/**
+ * The copy's history: loading while storage loads, none without a dataset, else partial or complete. Partial is a claim
+ * beside the numbers ("history from <through>, loading older · held of total"), and totals cover only `through` and
+ * above. Complete says nothing about storage: that is `deriveDurabilityState`, its own subject.
+ */
+export declare function deriveHistoryState<T, S, C, O>(model: Model<T, S, C, O>): HistoryState;
+/** Whether the page's copy is kept on this device, as a closed subject apart from how much history it holds. */
+export type DurabilityState = {
+    kind: "loading";
+} | {
+    kind: "unsaved";
+} | {
+    kind: "lost";
+    reason: string;
+} | {
+    kind: "failing";
+    reason: string;
+} | {
+    kind: "replaced";
+} | {
+    kind: "unreadable";
+    count: number;
+} | {
+    kind: "ok";
+};
+/**
+ * The copy's durability at the model's clock: loading, replaced by another tab, a failing store (lost while the page
+ * shows more than the disk holds), unsaved past the storage deadline, commands kept that this version can't read, or ok.
+ */
+export declare function deriveDurabilityState<T, S, C, O>(model: Model<T, S, C, O>): DurabilityState;
 export declare function createSync<T, P, S, C, O>(spec: Spec<T, P, S, C, O>): {
     initial: (client: string, now: number) => Model<T, S, C, O>;
     update: (model: Model<T, S, C, O>, msg: Msg<T, P, S, C, O>) => readonly [Model<T, S, C, O>, readonly Effect<T, S, C, O>[]];
-    merge: (replica: Replica<T, S>, patch: Patch<P, S>) => {
+    merge: (replica: Replica<T, S>, patch: Patch<P, S>, since: number) => {
         replica: Replica<T, S>;
         ops: Op[];
         reset: boolean;
-    } | undefined;
+    } | "gap" | undefined;
 };