@net-mesh/browser 0.37.0

package/dist/peer-driver.js

@@ -0,0 +1,224 @@
+/**
+ * The peer-attempt drive loop, once, for both surfaces.
+ *
+ * `BrowserNode` drives an attempt on this tab's own node;
+ * `MeshSession` drives one on whichever tab holds the lock. The steps
+ * and the classification are identical, and they must stay identical:
+ * the offerer and the answerer disagreeing about what supersession or
+ * a terminal reading looks like is a defect neither side can detect.
+ * So the loop lives here and each surface supplies only the four
+ * primitives ({@link PeerPrimitives}).
+ *
+ * **Supersession now has two sources, and that is the reason this
+ * file exists rather than a second copy of the loop.**
+ *
+ * 1. *Client-side*, as before: the reading names the dialog that is
+ *    live, so a reading for a different dialog means this attempt was
+ *    replaced.
+ * 2. *Server-side*, new with the proxy: a request that named a dialog
+ *    is refused by the leaf **before** it services anything, because
+ *    the attempt it was issued for is no longer the live one. A
+ *    proxied request crosses a channel and is served later, so this is
+ *    the common case for a follower rather than an edge.
+ *
+ * Both are the same disposition to a caller, and both are classified
+ * here. A direct caller sees (1) almost always and (2) never; a
+ * proxied caller sees either.
+ */
+import { fromWasmError } from './errors.js';
+/**
+ * The exact prefix the leaf's "peer not discovered" refusal carries
+ * (`wasm.rs`'s `NO_ANNOUNCEMENT_PREFIX`).
+ *
+ * Pinned because the wasm boundary carries messages, so a message is
+ * a contract: a reworded refusal demotes a typed disposition to a
+ * thrown error with nothing red.
+ */
+export const NO_ANNOUNCEMENT_PREFIX = 'no verified announcement for';
+/** `wasm.rs`'s `NO_LIVE_ATTEMPT_PREFIX`. */
+export const NO_LIVE_ATTEMPT_PREFIX = 'no live attempt with';
+/** `wasm.rs`'s refusal when no verified offer is waiting yet. */
+export const NO_OFFER_PREFIX = 'no verified offer from';
+/**
+ * `wasm.rs`'s `attempt_for` refusal: the named dialog is not the one
+ * now live.
+ *
+ * Distinct from {@link NO_LIVE_ATTEMPT_PREFIX} on purpose — "your
+ * attempt was replaced" and "there is no attempt" are different
+ * facts, and the leaf says which. Both classify as `superseded`, but
+ * only this one can name the replacement.
+ */
+export const REPLACED_ATTEMPT_MARKER = 'is not the live attempt';
+/** How long the drive loop waits between candidate steps. */
+export const PEER_TICK_MS = 50;
+/**
+ * How long {@link acceptPeer} waits for the offer envelope to arrive
+ * before it treats "no offer" as the answer.
+ *
+ * Two anchor hops and one pump, so it is generous rather than tight.
+ */
+export const PEER_OFFER_WAIT_MS = 5_000;
+/** Offer, drive to an open channel, then handshake (§9 steps 3-4). */
+export async function connectPeer(peer, primitives, parse) {
+    let dialog;
+    try {
+        dialog = await primitives.offer(peer);
+    }
+    catch (thrown) {
+        const error = fromWasmError(thrown);
+        if (error.message.includes(NO_ANNOUNCEMENT_PREFIX)) {
+            return { type: 'noAnnouncement', peer, detail: error.message };
+        }
+        throw error;
+    }
+    const gathered = await driveAttempt(peer, dialog, (status) => status.state === 'open', primitives, parse);
+    if (gathered.type !== 'direct')
+        return gathered;
+    return handshakePeer(peer, dialog, primitives);
+}
+/**
+ * Answer an offer and drive to a direct session.
+ *
+ * The accept is retried while the leaf reports no offer yet: the
+ * envelope crosses A → anchor → B, so a page reacting to "the peer is
+ * here" a moment before it lands would be told there is no offer,
+ * which is true and not an answer. Every other refusal is returned or
+ * thrown at once, because retrying those would only hide them.
+ */
+export async function acceptPeer(peer, primitives, parse) {
+    let dialog = null;
+    const until = Date.now() + PEER_OFFER_WAIT_MS;
+    for (;;) {
+        try {
+            dialog = await primitives.acceptOffer(peer);
+            break;
+        }
+        catch (thrown) {
+            const error = fromWasmError(thrown);
+            if (error.message.includes(NO_ANNOUNCEMENT_PREFIX)) {
+                return { type: 'noAnnouncement', peer, detail: error.message };
+            }
+            if (!error.message.includes(NO_OFFER_PREFIX) || Date.now() >= until) {
+                throw error;
+            }
+            await tick();
+        }
+    }
+    return driveAttempt(peer, dialog, (status) => status.direct, primitives, parse);
+}
+/**
+ * Run the offerer's handshake on an attempt whose channel is open.
+ *
+ * The dialog is **checked** rather than assumed: the handshake
+ * resolves to the dialog it actually ran for, and a mismatch is this
+ * caller's attempt having been replaced underneath it. Reporting
+ * `direct` with the caller's own dialog on any success is how a stale
+ * caller was once told its superseded attempt had connected, while
+ * the leaf had handshaken the attempt that replaced it.
+ */
+export async function handshakePeer(peer, dialog, primitives) {
+    let handshaken;
+    try {
+        handshaken = await primitives.handshake(peer, dialog);
+    }
+    catch (thrown) {
+        const superseded = classifySuperseded(thrown, peer, dialog);
+        if (superseded !== null)
+            return superseded;
+        return { type: 'handshakeFailed', peer, dialog, detail: fromWasmError(thrown).message };
+    }
+    if (handshaken !== dialog) {
+        return { type: 'superseded', peer, dialog, liveDialog: handshaken };
+    }
+    return { type: 'direct', peer, dialog };
+}
+/**
+ * Pump one attempt until `done`, its terminal transition, or a newer
+ * attempt replaces it.
+ *
+ * `{ type: 'direct' }` here means only "`done` answered true" — the
+ * caller decides what remains.
+ *
+ * **Every terminal state ends the loop**, not only the two ICE ones.
+ * An answerer waits for `direct`, and a channel that opened with a
+ * session that never installed satisfies neither `direct` nor
+ * `iceTimeout`: the leaf reports `failed`, which is this loop's exit.
+ * The bound is the leaf's, which owns the attempt's deadline — a
+ * timeout added here would be a second clock disagreeing with it.
+ */
+export async function driveAttempt(peer, dialog, done, primitives, parse) {
+    for (;;) {
+        let status;
+        try {
+            status = parse(await primitives.candidate(peer, dialog));
+        }
+        catch (thrown) {
+            const superseded = classifySuperseded(thrown, peer, dialog);
+            if (superseded !== null)
+                return superseded;
+            throw fromWasmError(thrown);
+        }
+        if (status.dialog !== dialog) {
+            return { type: 'superseded', peer, dialog, liveDialog: status.dialog };
+        }
+        if (done(status))
+            return { type: 'direct', peer, dialog };
+        if (status.state === 'iceTimeout')
+            return { type: 'iceTimeout', peer, dialog };
+        if (status.state === 'udpBlocked')
+            return { type: 'udpBlocked', peer, dialog };
+        if (status.state === 'failed') {
+            return {
+                type: 'handshakeFailed',
+                peer,
+                dialog,
+                detail: status.candidateError ??
+                    'the attempt reached its terminal transition without installing a session',
+            };
+        }
+        await tick();
+    }
+}
+/**
+ * `superseded` when `thrown` is one of the leaf's two
+ * attempt-ownership refusals, `null` when it is anything else.
+ *
+ * The two are kept apart in the reading, not collapsed: an ended
+ * attempt cannot name a successor (`liveDialog: null`), while a
+ * replaced one is refused by a leaf that knows which dialog took over
+ * — so the replacement's id is recovered from the message rather than
+ * reported as absent.
+ */
+function classifySuperseded(thrown, peer, dialog) {
+    const { message } = fromWasmError(thrown);
+    if (message.includes(REPLACED_ATTEMPT_MARKER)) {
+        return { type: 'superseded', peer, dialog, liveDialog: liveDialogFrom(message) };
+    }
+    if (message.includes(NO_LIVE_ATTEMPT_PREFIX)) {
+        return { type: 'superseded', peer, dialog, liveDialog: null };
+    }
+    return null;
+}
+/**
+ * The dialog `attempt_for`'s refusal names as live, or `null` if the
+ * message does not carry one.
+ *
+ * Reads the parenthesised `(dialog <id> is)` the leaf writes, in the
+ * **16-hex spelling** every dialog on every surface uses — so a
+ * recovered `liveDialog` compares equal to one that came out of a
+ * reading. The leaf's message was decimal when this was first
+ * written, which would have produced a `liveDialog` matching nothing.
+ *
+ * A refusal whose wording changed yields `null` — a missing successor
+ * id, which is honest — rather than a wrong one.
+ */
+function liveDialogFrom(message) {
+    const match = /\(dialog ([0-9a-f]{16}) is\)/.exec(message);
+    return match?.[1] ?? null;
+}
+/** One drive-loop tick. */
+async function tick() {
+    const waited = Promise.withResolvers();
+    setTimeout(waited.resolve, PEER_TICK_MS);
+    await waited.promise;
+}

package/dist/store/assembly.d.ts

@@ -0,0 +1,176 @@
+/**
+ * Snapshot assembly, and what it refuses (brief §1.12, §2).
+ *
+ * The rules are short and every one of them is a refusal a partial
+ * snapshot would otherwise slip through:
+ *
+ * - `n ≥ 1`; every `i` in `0..n-1` present **exactly once**;
+ * - all chunks carry the same `(h, g, r, n)`;
+ * - the sum of decoded chunk lengths equals `bytes` **exactly**;
+ * - **the assembled document** — not each chunk envelope — is then
+ *   JSON-parsed under the same depth and duplicate-key rules and
+ *   validated by the definition's `state()` before anything is
+ *   published.
+ *
+ * That last one is the distinction the earlier draft got wrong: the
+ * per-chunk checks validate the *envelopes*, not the snapshot. A
+ * document can be assembled from thirteen individually perfect
+ * envelopes and still be a duplicate-keyed depth bomb.
+ *
+ * Reclamation is equally explicit, because an assembly is the one
+ * place a replica holds a megabyte on a stranger's say-so: **one**
+ * in-flight per `(handle, generation)`, discarded on generation
+ * change, deadline and handle expiry, never merged into a later one,
+ * and bounded in total across handles so a peer cannot open many
+ * cheap assemblies to hold expensive memory.
+ */
+import type { StoreErrorCode } from './errors.js';
+import { type JsonValue } from './json.js';
+import { type Decimal, type Hex } from './wire.js';
+/** How long an assembly may stay open (brief §2). */
+export declare const ASSEMBLY_DEADLINE_MS = 10000;
+/** Total in-flight assembly bytes one owner or replica may hold (§2). */
+export declare const MAX_ASSEMBLY_BYTES_TOTAL: number;
+/** The manifest an assembly is opened against. */
+export interface AssemblyManifest {
+    readonly h: Hex;
+    readonly g: Decimal;
+    readonly r: Decimal;
+    readonly n: number;
+    /** Declared decoded byte total. */
+    readonly bytes: Decimal;
+}
+/** One chunk, as decoded from the wire. */
+export interface AssemblyChunk {
+    readonly h: Hex;
+    readonly g: Decimal;
+    readonly r: Decimal;
+    readonly n: number;
+    readonly i: number;
+    readonly d: string;
+}
+/** Why an assembly refused something. Stable and countable. */
+export type AssemblyRefusal = 'manifest-chunk-count' | 'manifest-bytes' | 'assembly-too-large' | 'chunk-wrong-assembly' | 'chunk-index' | 'chunk-non-canonical' | 'chunk-conflict' | 'chunk-duplicate' | 'byte-total-mismatch' | 'assembled-not-json' | 'assembled-invalid' | 'deadline';
+export interface AssemblyRejected {
+    readonly ok: false;
+    readonly code: StoreErrorCode;
+    readonly reason: AssemblyRefusal;
+    /**
+     * Whether this ends the assembly. A conflicting duplicate restarts
+     * it (§5.1), an out-of-assembly chunk is merely dropped.
+     */
+    readonly fatal: boolean;
+}
+export type ChunkOutcome = {
+    readonly ok: true;
+    readonly done: false;
+    readonly have: number;
+} | {
+    readonly ok: true;
+    readonly done: true;
+    readonly document: JsonValue;
+} | AssemblyRejected;
+/**
+ * One in-flight snapshot assembly.
+ *
+ * Holds the chunks it has admitted and nothing else: no partial
+ * document is exposed, and there is no accessor that would let a
+ * caller read half a world.
+ */
+export declare class Assembly {
+    readonly manifest: AssemblyManifest;
+    /** When this assembly was opened, for the deadline. */
+    private readonly openedAt;
+    private readonly pieces;
+    private readonly encoded;
+    private admitted;
+    private held;
+    private closed;
+    constructor(manifest: AssemblyManifest, 
+    /** When this assembly was opened, for the deadline. */
+    openedAt: number);
+    /** Decoded bytes currently held. */
+    get bytesHeld(): number;
+    /**
+     * Bytes this assembly is COMMITTED to, for the total-bytes bound.
+     *
+     * The manifest's declared total, not what has arrived: an assembly
+     * that has admitted one chunk of twenty still intends to hold the
+     * whole snapshot, and a bound tested against arrivals lets every
+     * one of them in while each is still nearly empty. A reclaimed
+     * assembly is committed to nothing.
+     */
+    get bytesReserved(): number;
+    /** How many distinct `i` have been admitted. */
+    get have(): number;
+    /** Whether this assembly has been reclaimed. */
+    get reclaimed(): boolean;
+    /** Give up every chunk. A reclaimed assembly admits nothing. */
+    reclaim(): void;
+    /** Whether `now` is past this assembly's deadline. */
+    expired(now: number): boolean;
+    /**
+     * Admit one chunk.
+     *
+     * Returns the assembled document on the chunk that completes it, and
+     * **only** then: `done: false` carries a count, never a partial
+     * document.
+     */
+    accept(chunk: AssemblyChunk, validate: (raw: unknown) => unknown, now: number): ChunkOutcome;
+}
+/**
+ * The assemblies one side holds, with the bounds that keep them from
+ * being a memory lever.
+ *
+ * One in-flight per `(handle, generation)` — a second manifest for the
+ * same pair replaces it rather than accumulating — and a total byte
+ * ceiling across handles, because a count bound alone is not a memory
+ * bound (§2).
+ *
+ * **The deadline is the HOLDER's to drive.** Nothing inside this class
+ * reads a clock: a host holding its own table MUST call {@link
+ * AssemblyTable.sweep} from its own. The store's own replica needs no
+ * such call — it enforces the assembly deadline in its `tick`, where
+ * an expired assembly is abandoned and re-asked for rather than
+ * silently dropped, and clears the table through `reclaimHandle`.
+ */
+export declare class AssemblyTable {
+    private readonly maxTotalBytes;
+    private readonly live;
+    constructor(maxTotalBytes?: number);
+    private static key;
+    /** Bytes currently held across every open assembly. */
+    get bytesHeld(): number;
+    /** Bytes every open assembly is committed to holding. */
+    get bytesReserved(): number;
+    get size(): number;
+    /** The open assembly for a pair, if any. */
+    get(h: Hex, g: Decimal): Assembly | undefined;
+    /**
+     * Open an assembly for a manifest.
+     *
+     * Refuses the **newest** when the total would exceed the ceiling:
+     * the ones already in flight have a replica waiting on them, and
+     * dropping those to admit an arrival is how a peer evicts another's
+     * progress.
+     */
+    open(manifest: AssemblyManifest, now: number): Assembly | AssemblyRejected;
+    /** Reclaim one pair's assembly. */
+    reclaim(h: Hex, g: Decimal): void;
+    /**
+     * Reclaim every assembly for a handle — a generation change, a
+     * handle expiry, a session loss.
+     */
+    reclaimHandle(h: Hex): void;
+    /**
+     * Reclaim everything past its deadline. Returns how many went.
+     *
+     * The one deadline enforcer for a table this module does not drive:
+     * a host holding its own `AssemblyTable` must call this from its own
+     * clock (see the class note), or its assemblies hold their
+     * reservations for ever.
+     */
+    sweep(now: number): number;
+    /** Give up everything. */
+    clear(): void;
+}