@net-mesh/browser 0.37.0

package/dist/org.js

@@ -0,0 +1,567 @@
+/**
+ * Organization-scoped streaming, as a page wants it (plan §4.5).
+ *
+ * The eight org verbs — {@link OrgUnaryHandler call}, streaming,
+ * client-streaming and duplex, each calling and serving — share one
+ * credential/option vocabulary and one terminal error taxonomy
+ * (`errors.ts`'s `OrgStreamError` family). The same eight names exist
+ * on {@link BrowserNode} and on {@link MeshSession}; the wrappers here
+ * serve both, so the two surfaces cannot drift into two spellings of
+ * one contract.
+ *
+ * **Suspension and closure (plan §4.5).** Deadlines are absolute: a
+ * frozen tab extends no lease and no window, so a call whose deadline
+ * passes while its tab is suspended retires with its deadline
+ * terminal on wake — {@link OrgTimeoutError}, or
+ * {@link OrgIndeterminateError} where the work may already be
+ * executing in another tab. Nothing resumes automatically: a retired
+ * call is never transparently re-opened, because re-opening is a
+ * fresh call with a fresh proof and MAY repeat effects. Node or tab
+ * close retires ownership — pending calls fail typed, and each
+ * dropped caller handle emits exactly one CANCEL.
+ *
+ * **Handler drop (F-S3.1-2), verbatim.** The retire supervisor may
+ * drop the handler future without a final poll — cancellation is
+ * observed through the retirement observables (the terminal item, the
+ * sink's typed closed refusal, and `retired`), never assumed as a
+ * handler-side event; a detached observer holding `retired` observes
+ * the signal. After retirement a handler sees typed refusals from
+ * `send`/`close`, and any return value it produces is discarded.
+ */
+import { fromWasmError, orgRetireReason, orgTerminalError, OrgCancelledError, ORG_SINK_CLOSED_REFUSAL, UnknownLeafError, } from './errors.js';
+/**
+ * The live org handles one node or session handed out, so its
+ * teardown can retire them: node close retires ownership — pending
+ * calls fail typed, one CANCEL per dropped caller handle.
+ */
+export class OrgHandleRegistry {
+    live = new Set();
+    add(handle) {
+        this.live.add(handle);
+    }
+    delete(handle) {
+        this.live.delete(handle);
+    }
+    /**
+     * Retire every live handle with one typed terminal. Drains first,
+     * so a handle's own teardown cannot re-enter this loop. Every
+     * handle is attempted; the raw failures come back rather than being
+     * swallowed, for the owner's teardown ledger.
+     */
+    retireAll(error) {
+        const open = [...this.live];
+        this.live.clear();
+        const failures = [];
+        for (const handle of open) {
+            try {
+                handle.retire(error);
+            }
+            catch (failure) {
+                failures.push(failure);
+            }
+        }
+        return failures;
+    }
+}
+/**
+ * The response half of an org call, wrapped: terminal items become
+ * the §4.3 typed errors, and the async iterator throws them.
+ */
+export class OrgStream {
+    inner;
+    onCancel;
+    onDone;
+    terminal = null;
+    /** A boundary rejection, latched so a second pull sees the same typed failure. */
+    failure = null;
+    handleDropped = false;
+    waiters = [];
+    /**
+     * @param `onCancel` drops the underlying handle — at most once, so
+     * one CANCEL leaves however many halves initiate the drop.
+     */
+    constructor(inner, onCancel, onDone) {
+        this.inner = inner;
+        this.onCancel = onCancel;
+        this.onDone = onDone;
+    }
+    next() {
+        if (this.failure !== null)
+            return Promise.reject(this.failure);
+        if (this.terminal !== null)
+            return Promise.resolve(this.terminal);
+        const { promise, resolve, reject } = Promise.withResolvers();
+        const waiter = { resolve, reject };
+        this.waiters.push(waiter);
+        void this.inner.next().then((raw) => {
+            // BROWSER-4: this pull's waiter leaves the list the moment the
+            // pull settles — a completed pull retains nothing to the
+            // terminal.
+            spliceWaiter(this.waiters, waiter);
+            const item = byteItem(raw);
+            if (item.done)
+                this.complete(item);
+            // With-resolvers settlement is first-wins, so a pull a
+            // retirement already settled simply keeps that outcome.
+            resolve(item);
+        }, (error) => {
+            // A boundary rejection propagates as its classified self —
+            // a proxied `LeaderLost` is the existing `RpcError` kind,
+            // re-typed by the one mapper — and is latched for the next
+            // pull. Not folded into an error item: the item vocabulary
+            // is the §4.3 terminal set, and inventing a translation for
+            // a throw this package cannot name is how a taxonomy turns
+            // into guessing.
+            spliceWaiter(this.waiters, waiter);
+            const failure = fromWasmError(error);
+            // `fail` settles every still-parked pull and latches the
+            // failure for the next one; this pull settles itself.
+            this.fail(failure);
+            reject(failure);
+        });
+        return promise;
+    }
+    cancel() {
+        this.retire(new OrgCancelledError());
+    }
+    /**
+     * Retire this stream: one CANCEL at most, every parked and future
+     * `next()` settled with `error` as the terminal item.
+     */
+    retire(error) {
+        if (this.terminal !== null || this.failure !== null)
+            return;
+        this.dropHandle();
+        this.complete({ done: true, error });
+    }
+    [Symbol.asyncIterator]() {
+        // A terminal's final body is yielded BEFORE the end (BROWSER-1):
+        // one done item carrying bytes is one yield plus one end, so the
+        // end is this iterator's own latch, not the item's `done`.
+        let ended = false;
+        return {
+            next: async () => {
+                if (ended)
+                    return { done: true, value: undefined };
+                const item = await this.next();
+                // THROWS the typed error at the terminal error item — the
+                // idiomatic `for await` shape, so `catch` sees the §4.3 class.
+                if (item.error !== undefined)
+                    throw item.error;
+                if (item.value === undefined) {
+                    ended = true;
+                    return { done: true, value: undefined };
+                }
+                if (item.done)
+                    ended = true;
+                return { done: false, value: item.value };
+            },
+            return: async () => {
+                ended = true;
+                this.cancel();
+                return { done: true, value: undefined };
+            },
+        };
+    }
+    complete(item) {
+        if (this.terminal !== null)
+            return;
+        this.terminal = item;
+        this.onDone?.();
+        const waiters = [...this.waiters];
+        this.waiters.length = 0;
+        for (const waiter of waiters)
+            waiter.resolve(item);
+    }
+    fail(error) {
+        if (this.terminal !== null || this.failure !== null)
+            return;
+        this.failure = error;
+        this.onDone?.();
+        const waiters = [...this.waiters];
+        this.waiters.length = 0;
+        for (const waiter of waiters)
+            waiter.reject(error);
+    }
+    dropHandle() {
+        if (this.handleDropped)
+            return;
+        this.handleDropped = true;
+        try {
+            this.onCancel();
+        }
+        catch {
+            // A handle that refuses its own drop is already retired at the
+            // boundary; the typed terminal below is what the consumer sees.
+        }
+    }
+}
+/** A client-streaming upload, wrapped. */
+export class OrgUpload {
+    inner;
+    onDone;
+    failure = null;
+    handleDropped = false;
+    waiters = [];
+    constructor(inner, onDone) {
+        this.inner = inner;
+        this.onDone = onDone;
+    }
+    async send(payload) {
+        if (this.failure !== null)
+            throw this.failure;
+        try {
+            await this.inner.send(payload);
+        }
+        catch (error) {
+            throw fromWasmError(error);
+        }
+    }
+    finish() {
+        if (this.failure !== null)
+            return Promise.reject(this.failure);
+        const { promise, resolve, reject } = Promise.withResolvers();
+        const waiter = { reject };
+        this.waiters.push(waiter);
+        void this.inner.finish().then((body) => {
+            spliceWaiter(this.waiters, waiter);
+            this.onDone?.();
+            resolve(body);
+        }, (error) => {
+            spliceWaiter(this.waiters, waiter);
+            this.onDone?.();
+            // finish() rejects with the typed terminal error (§4.3).
+            reject(fromWasmError(error));
+        });
+        return promise;
+    }
+    cancel() {
+        this.retire(new OrgCancelledError());
+    }
+    /** Retire this upload: one CANCEL at most; parked `finish()` rejects typed. */
+    retire(error) {
+        if (this.failure !== null)
+            return;
+        this.failure = error;
+        if (!this.handleDropped) {
+            this.handleDropped = true;
+            try {
+                this.inner.cancel();
+            }
+            catch {
+                // Already retired at the boundary; `error` is the outcome.
+            }
+        }
+        this.onDone?.();
+        const waiters = [...this.waiters];
+        this.waiters.length = 0;
+        for (const waiter of waiters)
+            waiter.reject(error);
+    }
+}
+/** A duplex call, wrapped: one call-level CANCEL however both halves end. */
+export class OrgDuplex {
+    inner;
+    onDone;
+    /** The two halves share one drop, so one CANCEL leaves per call. */
+    handleDropped = false;
+    failure = null;
+    sink;
+    stream;
+    constructor(inner, onDone) {
+        this.inner = inner;
+        this.onDone = onDone;
+        this.stream = new OrgStream(inner.stream(), () => this.dropHandle(), () => this.onDone?.());
+        this.sink = {
+            send: async (payload) => {
+                if (this.failure !== null)
+                    throw this.failure;
+                try {
+                    await this.inner.send(payload);
+                }
+                catch (error) {
+                    throw fromWasmError(error);
+                }
+            },
+            finishSending: async () => {
+                if (this.failure !== null)
+                    throw this.failure;
+                try {
+                    await this.inner.finish_sending();
+                }
+                catch (error) {
+                    throw fromWasmError(error);
+                }
+            },
+            cancel: () => {
+                this.retire(new OrgCancelledError());
+            },
+        };
+    }
+    /** Retire the whole call: one CANCEL, both halves settled typed. */
+    retire(error) {
+        this.failure ??= error;
+        this.dropHandle();
+        // Idempotent one level down: a stream that already reached its
+        // own terminal keeps that outcome.
+        this.stream.retire(error);
+        this.onDone?.();
+    }
+    dropHandle() {
+        if (this.handleDropped)
+            return;
+        this.handleDropped = true;
+        try {
+            this.inner.cancel();
+        }
+        catch {
+            // Already retired at the boundary; `error` is the outcome.
+        }
+    }
+}
+/**
+ * The response sink a handler receives, wrapped. `retired` is
+ * memoized at construction — the boundary's `retired()` is called
+ * exactly once and the one signal is what a detached observer holds.
+ */
+export class OrgSink {
+    inner;
+    retired;
+    verdict = null;
+    constructor(inner) {
+        this.inner = inner;
+        this.retired = inner.retired().then((raw) => {
+            this.verdict ??= orgRetireReason(raw);
+            return this.verdict;
+        }, () => {
+            // A `retired()` that itself fails is reported as a teardown
+            // verdict rather than left unsettled — an observer must get
+            // ONE signal, never a hang and never a rejection.
+            this.verdict ??= 'replaced';
+            return this.verdict;
+        });
+    }
+    async send(payload) {
+        if (this.verdict !== null)
+            throw new OrgCancelledError(ORG_SINK_CLOSED_REFUSAL);
+        try {
+            await this.inner.send(payload);
+        }
+        catch (error) {
+            throw fromWasmError(error);
+        }
+    }
+    /** Half-close the response direction: the call's normal ending. */
+    async close() {
+        if (this.verdict !== null)
+            throw new OrgCancelledError(ORG_SINK_CLOSED_REFUSAL);
+        try {
+            await this.inner.close();
+        }
+        catch (error) {
+            throw fromWasmError(error);
+        }
+    }
+}
+/**
+ * The request stream a handler receives, wrapped. Its terminal is the
+ * `done` item; the abnormal record is `retired`, memoized once as
+ * {@link OrgResponseSink.retired} is.
+ */
+export class OrgRequests {
+    inner;
+    retired;
+    verdict = null;
+    waiters = [];
+    constructor(inner) {
+        this.inner = inner;
+        this.retired = inner.retired().then((raw) => {
+            this.settle(orgRetireReason(raw));
+            return this.verdict;
+        }, () => {
+            this.settle('replaced');
+            return this.verdict;
+        });
+    }
+    next() {
+        if (this.verdict !== null)
+            return Promise.resolve({ done: true });
+        const { promise, resolve } = Promise.withResolvers();
+        this.waiters.push(resolve);
+        void this.inner.next().then((raw) => {
+            spliceWaiter(this.waiters, resolve);
+            resolve(requestItem(raw));
+        }, () => {
+            // A boundary throw here ends the iteration: the request
+            // direction is over one way or the other, and `retired` is
+            // where a handler reads which.
+            spliceWaiter(this.waiters, resolve);
+            resolve({ done: true });
+        });
+        return promise;
+    }
+    [Symbol.asyncIterator]() {
+        return {
+            next: async () => {
+                const item = await this.next();
+                if (item.done || item.value === undefined)
+                    return { done: true, value: undefined };
+                return { done: false, value: item.value };
+            },
+            return: async () => ({ done: true, value: undefined }),
+        };
+    }
+    settle(verdict) {
+        if (this.verdict !== null)
+            return;
+        this.verdict = verdict;
+        const waiters = [...this.waiters];
+        this.waiters.length = 0;
+        for (const waiter of waiters)
+            waiter({ done: true });
+    }
+}
+/**
+ * One serve registration, wrapped. `close()` is C9's protected-split
+ * retirement: it retires the registration's live protected calls with
+ * their exact terminals and refuses new openings on the service.
+ */
+export class OrgServe {
+    inner;
+    onDone;
+    closed = false;
+    constructor(inner, onDone) {
+        this.inner = inner;
+        this.onDone = onDone;
+    }
+    get service() {
+        return this.inner.service();
+    }
+    /**
+     * **A retirement, not a graceful unregister (C9's protected
+     * split).** Every live protected call this registration admitted is
+     * retired with its exact retirement terminal — the
+     * deadline/cancel/revocation vocabulary — and new openings on the
+     * service are refused. Deliberately NOT the public path's
+     * let-existing-calls-finish behavior.
+     */
+    close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        this.onDone?.();
+        this.inner.close();
+    }
+    /** The registry's teardown verb: for a registration it is `close()`. */
+    retire(_error) {
+        this.close();
+    }
+}
+/**
+ * Build exactly the options object `call_org*` reads.
+ *
+ * A fresh object, so a caller mutating its own afterwards cannot
+ * change a call already in flight. The byte fields are forwarded as
+ * the `Uint8Array`s they must be — the leaf refuses anything else
+ * loudly, and a silent re-encode here would be a second codec.
+ */
+export function toWasmOrgCallOptions(options) {
+    const credentials = {
+        membership: options.credentials.membership,
+        dispatcher: options.credentials.dispatcher,
+        ...(options.credentials.capabilityGrant === undefined
+            ? {}
+            : { capabilityGrant: options.credentials.capabilityGrant }),
+        actingOrg: options.credentials.actingOrg,
+        providerOwnerOrg: options.credentials.providerOwnerOrg,
+        provider: options.credentials.provider,
+        ...(options.credentials.proofTtlSecs === undefined
+            ? {}
+            : { proofTtlSecs: options.credentials.proofTtlSecs }),
+    };
+    return {
+        credentials,
+        ...(options.deadlineMs === undefined ? {} : { deadlineMs: options.deadlineMs }),
+        ...(options.streamWindowInitial === undefined
+            ? {}
+            : { streamWindowInitial: options.streamWindowInitial }),
+        ...(options.requestWindowInitial === undefined
+            ? {}
+            : { requestWindowInitial: options.requestWindowInitial }),
+    };
+}
+/** Build exactly the options object `serve_org*` reads. */
+export function toWasmOrgServeOptions(options) {
+    return { ownerOrg: options.ownerOrg };
+}
+/**
+ * Read one handler invocation's caller attribution.
+ *
+ * The boundary hands the crate's `to_json` JSON **string** (the same
+ * convention `on_event` uses), camelCase keys verbatim
+ * {@link OrgCaller}'s; anything that does not parse to an object is
+ * refused rather than served with an attribution this build cannot
+ * vouch for.
+ */
+export function parseOrgCaller(raw) {
+    const value = JSON.parse(raw);
+    if (value === null || typeof value !== 'object') {
+        throw new UnknownLeafError('the caller attribution is not an OrgCaller object');
+    }
+    const record = value;
+    return {
+        entity: String(record.entity ?? ''),
+        actingOrg: String(record.actingOrg ?? ''),
+        providerOrg: String(record.providerOrg ?? ''),
+        provider: String(record.provider ?? ''),
+        capability: String(record.capability ?? ''),
+        isSameOrg: record.isSameOrg === true,
+    };
+}
+/** Adapt a unary handler to the boundary's `(caller, request)` trampoline. */
+export function unaryOrgTrampoline(handler) {
+    return async (caller, request) => await handler(parseOrgCaller(caller), request);
+}
+/**
+ * Adapt a streaming handler to `(caller, request, sink)`. The sink is
+ * wrapped once per invocation; its `retired` is the one signal the
+ * F-S3.1-2 level names.
+ */
+export function streamingOrgTrampoline(handler) {
+    return async (caller, request, sink) => {
+        await handler(parseOrgCaller(caller), request, new OrgSink(sink));
+    };
+}
+/** Adapt a client-streaming handler to `(caller, requests)`. */
+export function clientStreamOrgTrampoline(handler) {
+    return async (caller, requests) => await handler(parseOrgCaller(caller), new OrgRequests(requests));
+}
+/** Adapt a duplex handler to `(caller, requests, sink)`. */
+export function duplexOrgTrampoline(handler) {
+    return async (caller, requests, sink) => {
+        await handler(parseOrgCaller(caller), new OrgRequests(requests), new OrgSink(sink));
+    };
+}
+/**
+ * One waiter leaves its list the moment its pull settles (BROWSER-4):
+ * a resolved pull retains no closure until the terminal.
+ */
+function spliceWaiter(waiters, waiter) {
+    const index = waiters.indexOf(waiter);
+    if (index >= 0)
+        waiters.splice(index, 1);
+}
+/** The boundary's byte item, typed through the §4.3 vocabulary. */
+function byteItem(raw) {
+    if (!raw.done)
+        return { done: false, value: raw.value };
+    if (raw.error !== undefined)
+        return { done: true, error: orgTerminalError(raw.error) };
+    // A terminal that carries a final body keeps it (BROWSER-1): the
+    // item is `{ done: true, value }`, never a flattened end.
+    return raw.value === undefined ? { done: true } : { done: true, value: raw.value };
+}
+/** The boundary's request item: no error arm, by contract. */
+function requestItem(raw) {
+    return raw.done ? { done: true } : { done: false, value: raw.value };
+}

package/dist/peer-driver.d.ts

@@ -0,0 +1,117 @@
+/**
+ * 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 type { PeerAttemptStatus, PeerConnectOutcome } from './node.js';
+/**
+ * The four steps an attempt needs, as whichever surface provides
+ * them.
+ *
+ * `candidate` and `handshake` take the dialog because the leaf
+ * requires it: a peer-only poll is resolved against whatever attempt
+ * is live when it runs, which for a request that crossed a channel is
+ * how a superseded request drives its own replacement.
+ */
+export interface PeerPrimitives {
+    /** Mint an offer and start an attempt; resolves to its dialog. */
+    offer(peer: string): Promise<string>;
+    /** Answer the offer already filed; resolves to its dialog. */
+    acceptOffer(peer: string): Promise<string>;
+    /** Service one polling step of `dialog`; resolves to the reading JSON. */
+    candidate(peer: string, dialog: string): Promise<string>;
+    /** Run the Noise handshake for `dialog`; resolves to the dialog it ran for. */
+    handshake(peer: string, dialog: string): Promise<string>;
+}
+/**
+ * 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 declare const NO_ANNOUNCEMENT_PREFIX = "no verified announcement for";
+/** `wasm.rs`'s `NO_LIVE_ATTEMPT_PREFIX`. */
+export declare const NO_LIVE_ATTEMPT_PREFIX = "no live attempt with";
+/** `wasm.rs`'s refusal when no verified offer is waiting yet. */
+export declare 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 declare const REPLACED_ATTEMPT_MARKER = "is not the live attempt";
+/** How long the drive loop waits between candidate steps. */
+export declare 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 declare const PEER_OFFER_WAIT_MS = 5000;
+/** Offer, drive to an open channel, then handshake (§9 steps 3-4). */
+export declare function connectPeer(peer: string, primitives: PeerPrimitives, parse: (json: string) => PeerAttemptStatus): Promise<PeerConnectOutcome>;
+/**
+ * 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 declare function acceptPeer(peer: string, primitives: PeerPrimitives, parse: (json: string) => PeerAttemptStatus): Promise<PeerConnectOutcome>;
+/**
+ * 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 declare function handshakePeer(peer: string, dialog: string, primitives: PeerPrimitives): Promise<PeerConnectOutcome>;
+/**
+ * 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 declare function driveAttempt(peer: string, dialog: string, done: (status: PeerAttemptStatus) => boolean, primitives: PeerPrimitives, parse: (json: string) => PeerAttemptStatus): Promise<PeerConnectOutcome>;