@synapse-sdk/client 0.1.0 → 0.3.0

package/dist/moq_log.js

@@ -0,0 +1,176 @@
+// @moq/net has no logger hook: its background tasks write straight to `console.warn`. Some of those
+// lines describe the *normal* end of a track we published, not a failure:
+//
+//   publish error: broadcast=client/<name>/<sid>/svc/<name> track=card error=RESET_STREAM: 1
+//
+// The broker reads a one-shot track (`card`, `desc`, the retained `data` group, the `req` log) and
+// drops its subscription with a QUIC RESET_STREAM carrying `StreamCode.Cancel` (1: "the sender is
+// done with this stream, not failing; a routine unsubscribe"), which @moq/net's publisher still
+// reports as an error. Likewise, our own `close()` tears every track and the discovery stream down
+// before @moq/net's session-closed promise settles, so each track reports "session error:
+// connection error: closed" and `forwardAnnounced` reports "broadcast discovery failed".
+//
+// This module wraps `console.warn` once per process and demotes exactly those lines to @moq/net
+// debug chatter: a `publish error` on a path *this SDK announced* whose reason is the Cancel code,
+// a `subscribe error` on a path *this SDK requested* whose reason is the relay's "source gone" reset
+// (the publisher we followed left; the SDK reports that itself), or any track/discovery failure of a
+// session *we* are closing. Everything else passes through untouched — a reset with another code
+// (NotFound, GroupTooLarge, Unauthorized, ...), a line about a path that is not ours, and every track
+// that dies because the *broker* dropped us (that failure is real and the node also reports it
+// through `watchStatus`/`connection_lost`).
+//
+// @moq/net also narrates every announce, subscribe and connect through `console.debug`, which Bun
+// and the browser print by default. The same wrapper covers `console.debug`: lines in @moq/net's
+// own formats (`announced: …`, `subscribe ok: …`, `<url> connected via WebTransport`, …) are dropped
+// unless moq debugging is on (`setMoqDebug(true)`, or `SYNAPSE_MOQ_DEBUG=1` in Bun/Node); every
+// other `console.debug` call passes through. So an application never has to silence `console.debug`
+// itself (D 2026-09-27).
+import { ADMISSION_REFUSED_CLOSE_CODE } from "@synapse-sdk/core";
+let debugOn;
+/** Show @moq/net's debug narration (and the demoted routine-end lines) on `console.debug`; default off, or `SYNAPSE_MOQ_DEBUG=1`. */
+export function setMoqDebug(on) { debugOn = on; }
+function moqDebugEnabled() {
+    if (debugOn !== undefined)
+        return debugOn;
+    const env = globalThis.process?.env?.SYNAPSE_MOQ_DEBUG;
+    return env !== undefined && env !== "" && env !== "0" && env.toLowerCase() !== "false";
+}
+/**
+ * The first argument of every `console.debug` @moq/net makes (0.4.0): `<subject>[ <verb>]: …` with a
+ * subject from its fixed vocabulary (`announced: broadcast=…`, `subscribe ok: id=…`, `track info: …`,
+ * `datagram send stopped: sub=…`, `dropping oversize datagram: …`), or a redacted URL followed by a
+ * fixed phrase.
+ */
+const MOQ_DEBUG_PREFIX = /^(announced?|subscribe(_namespace)?|publish(_namespace|_blocked)?|track|fetch|fill|datagram (send|receive) stopped|dropping( [a-z]+)*|adapter)( [a-z_]+)*: |^(session stream closed|message write)$/;
+const MOQ_DEBUG_URL_PHRASE = /^(connected via |negotiated ALPN:|performing an insecure fingerprint fetch)/;
+/** Exported for tests: whether a `console.debug` call is @moq/net's narration. */
+export function isMoqDebug(args) {
+    const [first, second] = args;
+    if (typeof first !== "string")
+        return false;
+    if (MOQ_DEBUG_PREFIX.test(first))
+        return true;
+    return /^(https?|wss?):\/\//.test(first) && typeof second === "string" && MOQ_DEBUG_URL_PHRASE.test(second);
+}
+const scopes = new Set();
+/**
+ * A released scope stays known for this long: @moq/net logs a track's end from its own tasks, after
+ * our close has returned. Expiry is checked at lookup, not by a timer, so nothing keeps the event
+ * loop alive.
+ */
+const LINGER_MS = 10_000;
+const PUBLISH_ERROR = /^publish error: broadcast=(\S+) track=\S+ error=(.*)$/s;
+const SUBSCRIBE_ERROR = /^subscribe error: id=\d+ broadcast=(\S+) track=\S+ error=(.*)$/s;
+const DISCOVERY_FAILED = "broadcast discovery failed; broadcasts resolve on request only.";
+/** `StreamCode.Cancel` (1) as the three runtimes spell a peer's reset: the napi polyfill, @moq/net's own `Error.Stream`, Chromium's `WebTransportError`. */
+const CANCEL_RESET = /^RESET_STREAM: 1(?!\d)|^remote error: 1(?!\d)|\bcode=1(?!\d)/;
+/**
+ * A peer reset with `Cancel` (1) or `Internal` (0) on a subscription of ours: the relay ends a
+ * subscription this way when the broadcast it fed went away (its publisher left). The SDK reports
+ * that itself (`publisher left` on the subscription's status, the feedback listener's return), so
+ * @moq/net's line is a duplicate. Any other code (NotFound, Unauthorized, GroupTooLarge, a control
+ * timeout) is a real answer and passes through.
+ */
+const SOURCE_GONE_RESET = /^RESET_STREAM: [01](?!\d)|^remote error: [01](?!\d)|\bcode=[01](?!\d)/;
+/** The session went away under the track. */
+const SESSION_GONE = /session error|connection error|connection closed|\bclosed\b/i;
+/**
+ * The broker refused admission with `admission_refused` (application session code `ADMISSION_REFUSED_CLOSE_CODE`,
+ * spelled `app code=502` by the transport) while our `res` subscribe and `req` announce were still
+ * pending. The node reports that itself (`reconnecting` with `error.code === "admission_refused"`); the
+ * per-track line @moq/net prints on every retry is a duplicate.
+ */
+const REFUSED_ADMISSION = new RegExp(`app code=${ADMISSION_REFUSED_CLOSE_CODE}(?!\\d)`);
+let installed = false;
+let original;
+let originalDebug;
+/** Registers a session with the filter; installs the `console.warn` wrapper on first use. */
+export function moqLogScope() {
+    install();
+    const s = { paths: new Set(), requests: new Set(), closing: false };
+    scopes.add(s);
+    return {
+        announced: path => { s.paths.add(path); },
+        requested: path => { s.requests.add(path); },
+        closing: () => { s.closing = true; },
+        release: () => { s.releasedAt = Date.now(); },
+    };
+}
+function live() {
+    const now = Date.now();
+    for (const s of scopes)
+        if (s.releasedAt !== undefined && now - s.releasedAt > LINGER_MS)
+            scopes.delete(s);
+    return scopes;
+}
+/** Forgets every scope; for tests, whose earlier nodes would otherwise still count as closing. */
+export function resetMoqLogScopes() { scopes.clear(); }
+function install() {
+    if (installed)
+        return;
+    installed = true;
+    original = console.warn;
+    originalDebug = console.debug;
+    console.warn = function warn(...args) {
+        if (isRoutineEnd(args)) {
+            if (moqDebugEnabled())
+                originalDebug.call(console, "[moq]", ...args);
+            return;
+        }
+        original.apply(this ?? console, args);
+    };
+    console.debug = function debug(...args) {
+        if (isMoqDebug(args) && !moqDebugEnabled())
+            return;
+        originalDebug.apply(this ?? console, args);
+    };
+}
+/** Restores the original `console.warn`/`console.debug`; for tests. */
+export function uninstallMoqLogFilter() {
+    if (!installed)
+        return;
+    installed = false;
+    console.warn = original;
+    console.debug = originalDebug;
+    original = undefined;
+    originalDebug = undefined;
+}
+/** Exported for tests: whether a `console.warn` call from @moq/net describes the normal end of one of our tracks. */
+export function isRoutineEnd(args) {
+    const line = args[0];
+    if (typeof line !== "string")
+        return false;
+    const known = live();
+    if (line === DISCOVERY_FAILED) {
+        for (const s of known)
+            if (s.closing)
+                return true;
+        return false;
+    }
+    const pub = PUBLISH_ERROR.exec(line);
+    if (pub) {
+        const [, path, reason] = pub;
+        for (const s of known) {
+            if (!s.paths.has(path))
+                continue;
+            if (CANCEL_RESET.test(reason) || REFUSED_ADMISSION.test(reason))
+                return true;
+            if (s.closing && SESSION_GONE.test(reason))
+                return true;
+        }
+        return false;
+    }
+    const sub = SUBSCRIBE_ERROR.exec(line);
+    if (sub) {
+        const [, path, reason] = sub;
+        for (const s of known) {
+            if (!s.requests.has(path))
+                continue;
+            if (SOURCE_GONE_RESET.test(reason) || REFUSED_ADMISSION.test(reason))
+                return true;
+            if (s.closing && SESSION_GONE.test(reason))
+                return true;
+        }
+    }
+    return false;
+}

package/dist/node.d.ts

@@ -0,0 +1,145 @@
+import { SynapseError, type ClientType, type ErrorBody, type Identity, type TimeDomain } from "@synapse-sdk/core";
+import { Session, type Dial, type SessionKnobs } from "./session.ts";
+import type { ConnectOptions, ConnectTarget, ConnectionState, Notice, ReconnectPolicy } from "./types.ts";
+import { Cell, type Deferred } from "./util.ts";
+/** `initial × 2^(attempt−1)` capped at `max`, times an equal jitter U(0.5, 1); never gives up. */
+export declare function exponentialPolicy(initialMs: number, maxMs: number): ReconnectPolicy;
+/** A fixed delay (tests). */
+export declare function fixedPolicy(ms: number): ReconnectPolicy;
+/** Stops after `maxAttempts` attempts in one phase. */
+export declare function withMaxAttempts(p: ReconnectPolicy, maxAttempts: number): ReconnectPolicy;
+export declare const defaultReconnectPolicy: ReconnectPolicy;
+/** The node's declared target: bumped `generation` per change; `dial` undefined = deliberately disconnected. */
+export interface Target {
+    generation: number;
+    dial: Dial | undefined;
+    identity: Identity;
+}
+/** The one lifecycle cell: `ConnectionState` with the session on `connected`. State, not history. */
+export type Link = {
+    status: "connecting";
+    attempt: number;
+} | {
+    status: "connected";
+    session: Session;
+} | {
+    status: "reconnecting";
+    attempt: number;
+    reason: string;
+    error: SynapseError;
+    nextRetryAtMs: number;
+} | {
+    status: "closing";
+} | {
+    status: "closed";
+    reason: string;
+} | {
+    status: "failed";
+    error: SynapseError;
+};
+export declare function stateOf(l: Link): ConnectionState;
+/** What a handle task is told about the node's session, in its own mailbox, in order with its other events. */
+export type SessionEvent = {
+    kind: "started";
+    session: Session;
+} | {
+    kind: "ended";
+} | {
+    kind: "nodeEnded";
+};
+/** Where the loop replies to a `connect`/`setTarget` call waiting for a target generation. */
+type Reply = Deferred<void>;
+/** Why the loop is dialing. */
+type Pursuit = {
+    kind: "first";
+    deadlineMs: number;
+} | {
+    kind: "reconnect";
+} | {
+    kind: "target";
+};
+type Stand = {
+    kind: "live";
+    session: Session;
+} | {
+    kind: "dialing";
+    pursuit: Pursuit;
+    attempt: number;
+    delayMs: number;
+    reason: string;
+    error: SynapseError;
+} | {
+    kind: "resting";
+};
+type Next = {
+    kind: "retry";
+    delayMs: number;
+} | {
+    kind: "failed";
+} | {
+    kind: "closed";
+};
+/** The rules (SDK §2, WP §10.4) for the delay before attempt `attempt`. */
+export declare function decide(pursuit: Pursuit, policy: ReconnectPolicy | null, err: SynapseError, attempt: number, nowMs: number): Next;
+export declare class Node {
+    #private;
+    readonly link: Cell<Link>;
+    readonly target: Cell<Target>;
+    readonly dom: TimeDomain;
+    readonly knobs: SessionKnobs;
+    readonly policy: ReconnectPolicy | null;
+    /** Broker notices addressed to this node, across its sessions (fed by the loop from the current session's). */
+    readonly notices: Set<(n: ErrorBody) => void>;
+    readonly projectNotices: Set<(n: Notice) => void>;
+    /** Resolves once the node has ended for good (`close()`, the first connect failing, the policy giving up). */
+    readonly ended: Deferred<void>;
+    epochs: number;
+    reconnects: number;
+    callsSent: number;
+    callsAnswered: number;
+    constructor(target: Target, dom: TimeDomain, knobs: SessionKnobs, policy: ReconnectPolicy | null);
+    get isEnded(): boolean;
+    get isConnected(): boolean;
+    currentSession(): Session | undefined;
+    state(): ConnectionState;
+    /** The loop's one write. A write that names a session or withdraws one tells every monitoring handle, in the same step. */
+    setLink(next: Link): void;
+    /**
+     * Registers a handle to be told about sessions (and the node's end) and returns the session the
+     * node has right now; the next event is its end. `deliver` returns `false` once the handle's
+     * mailbox is gone, which unregisters it; `unmonitor` unregisters it at once.
+     */
+    monitor(deliver: (e: SessionEvent) => boolean): {
+        session: Session | undefined;
+        unmonitor: () => void;
+    };
+    /** The node ends for good in `link`: handles are told, feeds end. */
+    end(link: Link): void;
+    /** Builds the freshly opened session completely (its epoch, its tasks running), then names it. */
+    attach(session: Session): Session;
+    /** `close()`: posts the command; resolves once the node has ended. */
+    close(): Promise<void>;
+    /** `setTarget()`: declares the target under the cell's write, posts the command with its reply, and awaits it. */
+    setTarget(dial: Dial | undefined): Promise<void>;
+    /** Starts the loop. `first` is the `connect()` call's reply. `signals`: close on SIGINT/SIGTERM (Bun/Node). */
+    run(stand: Stand, first: Reply | undefined, signals: boolean): void;
+}
+/** Resolves the identity a node declares (`resolve_identity`): a missing name is minted, a `web`/`hmi` node without a `user_id` mints one. */
+export declare function resolveIdentity(o: {
+    type: ClientType;
+    name?: string;
+    userId?: string;
+    credential?: string;
+}): Identity;
+/** Resolves a `ConnectTarget` against the node's current identity (fields left out are kept). */
+export declare function resolveTarget(node: Node, t: ConnectTarget): Dial;
+/**
+ * Builds the node and starts its loop in the first pursuit. Resolves as soon as the loop runs, with
+ * the node (so a `close()` can reach it during the first dial) and `connected`: the loop's reply to
+ * the first connect, a session established or why there is none (`not_connected` after a `close()`).
+ */
+export declare function startNode(opts: ConnectOptions, giveUpAfterMs: number): Promise<{
+    node: Node;
+    connected: Promise<void>;
+}>;
+export {};