@synapse-sdk/client 0.1.0 → 0.3.0

package/dist/fec.d.ts

@@ -0,0 +1,85 @@
+import * as Moq from "@moq/net";
+import { type FecParams, type FecReport, type FecWasm, type Header } from "@synapse-sdk/core";
+import { type Session } from "./session.ts";
+/** The most symbols one write puts on the track at once (the relay's datagram ring). */
+export declare const RING_BURST = 64;
+/** The pause between two bursts of one frame's remainder. */
+export declare const BURST_GAP_MS = 1;
+/** How long a `fec` follower waits before following its publisher again (shared with `channel.ts`'s re-ask pace). */
+export declare const REFOLLOW_PACE_MS = 100;
+/** The wasm codec, or `not_supported` with the reason it is not there. */
+export declare function requireFec(what: string): Promise<FecWasm>;
+export interface FecPubStats {
+    blocks: number;
+    plain: number;
+    superseded: number;
+    symbols: number;
+    reports: number;
+    repairPct: number;
+}
+export declare class FecWriter {
+    #private;
+    readonly topic: string;
+    readonly track: Moq.Track.Producer;
+    readonly params: FecParams;
+    readonly stats: FecPubStats;
+    private readonly onError;
+    /** `stats` is the publisher's (cumulative across sessions); `params.repair_pct` is the ratio to start from. */
+    constructor(topic: string, track: Moq.Track.Producer, wasm: FecWasm, params: FecParams, stats: FecPubStats, onError: (e: unknown) => void);
+    /** WP §6.4: the repair ratio for the next blocks (clamped 0..100). */
+    setRepairPct(pct: number): void;
+    /** Would this frame go as one plain datagram? */
+    isPlain(header: Header, bodyLen: number): boolean;
+    /**
+     * Encodes one frame and writes its first [`RING_BURST`] symbols; a larger frame's remainder is
+     * written from the timer. A `STAGES.sent_us` of 0 is stamped here, before the encode (the symbols
+     * are derived from those bytes). Throws when the frame cannot be encoded (nothing written) or the
+     * track refuses (the session is going).
+     */
+    publish(header: Header, body: Uint8Array): void;
+    close(): void;
+}
+/** `<sub prefix>/feedback/<pub name>/<pub sid>/<topic>`: where subscriber session `sub` reports to publisher session `publisher` (both `client/<name>/<sid>`). */
+export declare function feedbackPath(sub: string, publisher: string, topic: string): string;
+/**
+ * Publisher side of WP §6.4: follows every subscriber session's reports on `topic` for the
+ * publisher session `s` and adapts `setRepairPct` through a `RepairAdapter`. Ends when `signal` aborts.
+ */
+export declare function feedbackListener(s: Session, topic: string, basePct: number, setRepairPct: (pct: number) => void, onReport: () => void, signal: AbortSignal, warn: (msg: string) => void): Promise<void>;
+/** A frame the receiver put together: `frame` is header ++ body. */
+export interface ReceivedFrame {
+    seq: number;
+    frame: Uint8Array;
+    repaired: boolean;
+}
+export interface ReceiverStats {
+    symbols: number;
+    late: number;
+    surplus: number;
+    bad: number;
+    frames: number;
+    repaired: number;
+    lost: number;
+    expired: number;
+}
+/** The receiver for one publisher: `push` every datagram, `poll` for frames (after each push and on the 10 ms tick). */
+export declare class FecReader {
+    #private;
+    constructor(wasm: FecWasm, params: FecParams | undefined, deadlineOverrideMs: number | undefined);
+    /** `false` when the datagram was undecodable or inconsistent (counted `bad`). */
+    push(payload: Uint8Array, nowUs: number): boolean;
+    poll(nowUs: number): ReceivedFrame[];
+    pending(): number;
+    stats(): ReceiverStats;
+    takeReport(): FecReport;
+    close(): void;
+}
+/** Subscriber side of WP §6.4: the report track, created on the first report; bound to one session like the follower that owns it. */
+export declare class ReportWriter {
+    #private;
+    private readonly s;
+    readonly path: string;
+    constructor(s: Session, pubPrefix: string, topic: string);
+    write(report: FecReport): void;
+    close(): void;
+}

package/dist/fec.js

@@ -0,0 +1,281 @@
+// The datagram path of `fec` topics (WP §6.2–§6.4), the JS spelling of the Rust client's `fec.rs`.
+// The codec is synapse-core's RaptorQ sender/receiver compiled to wasm (`loadFec`); a `fec` topic
+// without it is refused (`not_supported`) — there is no second encoder in TypeScript.
+//
+// Publisher ([`FecWriter`], the send rule, WP §6.3): `publish` encodes the frame and writes its
+// first [`RING_BURST`] symbols to the track in the call; a larger frame's remainder follows in
+// bursts of at most [`RING_BURST`], [`BURST_GAP_MS`] apart, from a timer; a newer frame published
+// while a remainder is still due replaces it (newest wins, counted `superseded`). Subscriber
+// ([`FecReader`]): every datagram goes through the receiver (symbols and plain frames alike), which
+// delivers frames in `seq` order, repair applied; polled after each datagram and every 10 ms so a
+// lost block gives up on its own. Feedback (WP §6.4): a subscriber session writes one `REPORT` a
+// second on `<own prefix>/feedback/<pub name>/<pub sid>/<topic>` track `report`; the publisher
+// follows `client/*/*/feedback/<own name>/<own sid>/<topic>` and adapts its repair ratio
+// (`RepairAdapter`, worst subscriber wins).
+import * as Moq from "@moq/net";
+import { RepairAdapter, SynapseError, TYPES, decode as decodeBody, encode as encodeBody, encodeHeader, hasPendingSentUs, headerLength, loadFec, moqPriority, nowUs, splitFrame, stampSentUs, } from "@synapse-sdk/core";
+import { CallWriter, moqTimestamp, streamSubscription, waitActive } from "./session.js";
+/** The most symbols one write puts on the track at once (the relay's datagram ring). */
+export const RING_BURST = 64;
+/** The pause between two bursts of one frame's remainder. */
+export const BURST_GAP_MS = 1;
+/** How long a `fec` follower waits before following its publisher again (shared with `channel.ts`'s re-ask pace). */
+export const REFOLLOW_PACE_MS = 100;
+/** The wasm codec, or `not_supported` with the reason it is not there. */
+export async function requireFec(what) {
+    try {
+        return await loadFec();
+    }
+    catch (e) {
+        throw new SynapseError("not_supported", { message: `${what}: fec needs the synapse-wasm codec, which could not be loaded: ${e instanceof Error ? e.message : String(e)}`, cause: e });
+    }
+}
+export class FecWriter {
+    topic;
+    track;
+    params;
+    stats;
+    onError;
+    #sender;
+    #rest;
+    #timer;
+    #closed = false;
+    /** `stats` is the publisher's (cumulative across sessions); `params.repair_pct` is the ratio to start from. */
+    constructor(topic, track, wasm, params, stats, onError) {
+        this.topic = topic;
+        this.track = track;
+        this.params = params;
+        this.stats = stats;
+        this.onError = onError;
+        this.#sender = new wasm.FecSender(params.symbol_size, params.repair_pct, params.deadline_ms);
+        this.#sender.setRepairPct(stats.repairPct);
+    }
+    /** WP §6.4: the repair ratio for the next blocks (clamped 0..100). */
+    setRepairPct(pct) { this.stats.repairPct = Math.max(0, Math.min(100, Math.trunc(pct))); this.#sender.setRepairPct(this.stats.repairPct); }
+    /** Would this frame go as one plain datagram? */
+    isPlain(header, bodyLen) { return this.#sender.isPlain(encodeHeader(header), bodyLen); }
+    /**
+     * Encodes one frame and writes its first [`RING_BURST`] symbols; a larger frame's remainder is
+     * written from the timer. A `STAGES.sent_us` of 0 is stamped here, before the encode (the symbols
+     * are derived from those bytes). Throws when the frame cannot be encoded (nothing written) or the
+     * track refuses (the session is going).
+     */
+    publish(header, body) {
+        if (this.#closed)
+            throw new SynapseError("connection_lost", "fec writer closed");
+        if (hasPendingSentUs(header))
+            stampSentUs(header, nowUs());
+        let block;
+        try {
+            block = this.#sender.encode(encodeHeader(header), body);
+        }
+        catch (e) {
+            throw new SynapseError("invalid_input", { message: `fec topic ${this.topic}: ${e instanceof Error ? e.message : String(e)} (${headerLength(header) + body.length} bytes)`, cause: e });
+        }
+        if (block.plain)
+            this.stats.plain++;
+        else
+            this.stats.blocks++;
+        this.stats.symbols += block.symbols.length;
+        // A remainder still due is replaced: the newer frame is what the subscriber wants.
+        if (this.#rest) {
+            this.stats.superseded++;
+            this.#rest = undefined;
+        }
+        const ts = moqTimestamp(block.tUs);
+        const first = Math.min(block.symbols.length, RING_BURST);
+        for (let i = 0; i < first; i++)
+            this.track.appendDatagram(ts, block.symbols[i]);
+        if (block.symbols.length > first) {
+            this.#rest = { tUs: block.tUs, symbols: block.symbols, next: first, dueMs: performance.now() + BURST_GAP_MS };
+            this.#arm();
+        }
+    }
+    #arm() {
+        if (this.#timer !== undefined || !this.#rest || this.#closed)
+            return;
+        this.#timer = setTimeout(() => { this.#timer = undefined; this.#burst(); }, Math.max(0, this.#rest.dueMs - performance.now()));
+    }
+    /** Writes the next burst of the remainder; re-arms while symbols are left. */
+    #burst() {
+        const r = this.#rest;
+        if (!r || this.#closed)
+            return;
+        const ts = moqTimestamp(r.tUs);
+        const end = Math.min(r.symbols.length, r.next + RING_BURST);
+        try {
+            for (; r.next < end; r.next++)
+                this.track.appendDatagram(ts, r.symbols[r.next]);
+        }
+        catch (e) {
+            this.close();
+            this.onError(e);
+            return;
+        }
+        if (r.next >= r.symbols.length)
+            this.#rest = undefined;
+        else {
+            r.dueMs = performance.now() + BURST_GAP_MS;
+            this.#arm();
+        }
+    }
+    close() {
+        this.#closed = true;
+        if (this.#timer !== undefined) {
+            clearTimeout(this.#timer);
+            this.#timer = undefined;
+        }
+        this.#rest = undefined;
+        try {
+            this.#sender.free();
+        }
+        catch { /* freed */ }
+    }
+}
+/** `<sub prefix>/feedback/<pub name>/<pub sid>/<topic>`: where subscriber session `sub` reports to publisher session `publisher` (both `client/<name>/<sid>`). */
+export function feedbackPath(sub, publisher, topic) { return `${sub}/feedback/${publisher.startsWith("client/") ? publisher.slice("client/".length) : publisher}/${topic}`; }
+/**
+ * Publisher side of WP §6.4: follows every subscriber session's reports on `topic` for the
+ * publisher session `s` and adapts `setRepairPct` through a `RepairAdapter`. Ends when `signal` aborts.
+ */
+export async function feedbackListener(s, topic, basePct, setRepairPct, onReport, signal, warn) {
+    let pattern, announced;
+    try {
+        pattern = Moq.Path.Pattern.parse(feedbackPath("client/*/*", s.prefix, topic));
+        announced = s.sub.announced(pattern);
+    }
+    catch (e) {
+        warn(`topic ${topic}: feedback pattern refused: ${e instanceof Error ? e.message : String(e)}`);
+        return;
+    }
+    const adapter = new RepairAdapter(basePct);
+    const onAbort = () => announced.close();
+    signal.addEventListener("abort", onAbort, { once: true });
+    try {
+        for (;;) {
+            const u = await announced.next();
+            if (!u)
+                return;
+            if (u.kind !== "announced")
+                continue;
+            // The cursor delivers every announcement whose subtree overlaps the pattern (a client's `hello` among them): only an exact match is a report broadcast.
+            if (!pattern.matches(String(u.prefix)))
+                continue;
+            void (async () => {
+                const req = s.request(String(u.prefix));
+                try {
+                    const bc = await waitActive(req, 5000, signal);
+                    const sub = bc.track("report").subscribe(streamSubscription(moqPriority(3)));
+                    // Reports are read as they arrive (as in Rust): only the newest matters to the adapter, so a missing older one is never waited for.
+                    let g;
+                    const onStop = () => { sub.close(); g?.close(); };
+                    signal.addEventListener("abort", onStop, { once: true });
+                    try {
+                        for (;;) {
+                            g = await sub.recvGroup();
+                            if (!g)
+                                break;
+                            for (;;) {
+                                const f = await g.readFrame();
+                                if (!f)
+                                    break;
+                                let header, body;
+                                try {
+                                    ({ header, body } = splitFrame(f.payload));
+                                }
+                                catch {
+                                    continue;
+                                }
+                                if (header.type !== TYPES.REPORT)
+                                    continue;
+                                let report;
+                                try {
+                                    report = decodeBody(body);
+                                }
+                                catch {
+                                    continue;
+                                }
+                                if (!report || typeof report.lost !== "number" || typeof report.frames !== "number")
+                                    continue;
+                                onReport();
+                                const pct = adapter.observe(report);
+                                if (pct !== undefined)
+                                    setRepairPct(pct);
+                            }
+                        }
+                    }
+                    finally {
+                        signal.removeEventListener("abort", onStop);
+                        onStop();
+                    }
+                }
+                catch { /* the subscriber left */ }
+                finally {
+                    req.close();
+                }
+            })();
+        }
+    }
+    catch (e) {
+        if (!signal.aborted)
+            warn(`topic ${topic}: feedback listener ended: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    finally {
+        signal.removeEventListener("abort", onAbort);
+        announced.close();
+    }
+}
+/** The receiver for one publisher: `push` every datagram, `poll` for frames (after each push and on the 10 ms tick). */
+export class FecReader {
+    #rx;
+    constructor(wasm, params, deadlineOverrideMs) {
+        this.#rx = new wasm.FecReceiver(params?.deadline_ms ?? 0, 0, deadlineOverrideMs ?? 0);
+    }
+    /** `false` when the datagram was undecodable or inconsistent (counted `bad`). */
+    push(payload, nowUs) { return this.#rx.push(payload, nowUs) !== 2 /* Pushed.Bad */; }
+    poll(nowUs) { return this.#rx.poll(nowUs); }
+    pending() { return this.#rx.pending(); }
+    stats() { return this.#rx.stats(); }
+    takeReport() { return this.#rx.takeReport(); }
+    close() { try {
+        this.#rx.free();
+    }
+    catch { /* freed */ } }
+}
+/** Subscriber side of WP §6.4: the report track, created on the first report; bound to one session like the follower that owns it. */
+export class ReportWriter {
+    s;
+    path;
+    #bc;
+    #writer;
+    #seq = 0;
+    constructor(s, pubPrefix, topic) {
+        this.s = s;
+        this.path = feedbackPath(s.prefix, pubPrefix, topic);
+    }
+    write(report) {
+        if (!this.#writer) {
+            const bc = this.s.createBroadcast(this.path);
+            this.#writer = new CallWriter(bc.createTrack("report", { priority: moqPriority(3) }));
+            bc.announce();
+            this.#bc = bc;
+        }
+        const rtt = this.s.clock.get().rttUs;
+        if (rtt !== undefined)
+            report.rtt_us = rtt;
+        this.#seq = (this.#seq + 1) >>> 0;
+        this.#writer.write({ flags: 0, type: TYPES.REPORT, seq: this.#seq, tUs: nowUs(), tlvs: [] }, encodeBody(report));
+    }
+    close() {
+        try {
+            this.#writer?.close();
+        }
+        catch { /* closed */ }
+        try {
+            this.#bc?.close();
+        }
+        catch { /* closed */ }
+        this.#writer = undefined;
+        this.#bc = undefined;
+    }
+}

package/dist/index.d.ts

@@ -1,74 +1,10 @@
-import { A as SynapseOptions, C as ServiceCard, D as StreamEvent, E as StateDiff, F as VerifyFn, I as VerifyHandle, L as WebSocketCtor, M as SystemState, N as Target, O as SubscribeOptions, P as TokenInput, R as WebSocketLike, S as Serializer, T as ServiceRegistration, _ as Message, a as Channel, b as Reply, c as CallOptions, d as ConnectTarget, f as ConnectionOptions, g as Logger, h as Frame, i as Connection, j as SystemRole, k as Subscription, l as CatalogChange, m as ConnectionStatus, n as StateHandle, o as ChannelHandler, p as ConnectionState, r as Synapse, s as CallContext, t as LatestValue, u as ChannelHost, v as Params, w as ServiceHandler, x as ResourceInfo, y as ParamsInput } from "./node-DbD7G0Nx.js";
-
-//#region src/serializer.d.ts
-/**
- * The wire serializer — the **installed** Phoenix `Serializer` (v2 text + binary frames),
- * wrapped to our `Serializer` interface so wire-compat tracks the `phoenix` package. Its
- * `encode`/`decode` are callback-style but synchronous, so we capture the result inline.
- */
-declare const serializer: Serializer;
-//#endregion
-//#region src/address.d.ts
-interface Address {
-  realm: string;
-  name: string;
-}
-/**
- * Split a `[realm:]name` address into `{ realm, name }`; default realm `synapse`.
- * Only a bare-identifier prefix counts as a realm, so a synapse name with `/` and no realm
- * passes through unchanged. Mirrors the Python client.
- *
- *   "camera/capture"          -> { realm: "synapse",   name: "camera/capture" }
- *   "rosbridge:/add_two_ints" -> { realm: "rosbridge", name: "/add_two_ints" }
- */
-declare function address(addr: string): Address;
-//#endregion
-//#region src/errors.d.ts
-declare class ConnectionError extends Error {
-  constructor(message: string, options?: {
-    cause?: unknown;
-  });
-}
-declare class TimeoutError extends ConnectionError {
-  constructor(message: string);
-}
-/** A newer `connect(...)` (or `disconnect()`) replaced the target this promise was awaiting. */
-declare class SupersededError extends ConnectionError {
-  constructor();
-}
-declare class ChannelError extends Error {
-  topic: string;
-  response: unknown;
-  constructor(topic: string, message: string, response?: unknown);
-}
-interface BusErrorPayload {
-  code?: string;
-  message?: string;
-}
-/**
- * Known bus error codes — server-emitted (`unauthorized`, `service_unavailable`,
- * `provider_error`, `invalid_input`, `unknown_event`, `ros_error`) plus client-side
- * (`bad_ack`, `not_connected`, `timeout`, `cancelled`). Match on these to avoid magic
- * strings; treat the set as **non-exhaustive** (the server may add codes).
- */
-declare const BusErrorCode: {
-  readonly Unauthorized: "unauthorized";
-  readonly ServiceUnavailable: "service_unavailable";
-  readonly ProviderError: "provider_error";
-  readonly InvalidInput: "invalid_input";
-  readonly UnknownEvent: "unknown_event";
-  readonly RosError: "ros_error";
-  readonly BadAck: "bad_ack";
-  readonly NotConnected: "not_connected";
-  readonly Timeout: "timeout";
-  readonly Cancelled: "cancelled";
-};
-type BusErrorCode = (typeof BusErrorCode)[keyof typeof BusErrorCode];
-/** Raised when a service call fails — at accept time or mid-flight (see the bus error model). */
-declare class BusError extends Error {
-  code: string;
-  detail: unknown;
-  constructor(error: BusErrorPayload | unknown);
-}
-//#endregion
-export { type Address, BusError, BusErrorCode, type BusErrorPayload, type CallContext, type CallOptions, type CatalogChange, Channel, ChannelError, type ChannelHandler, type ChannelHost, type ConnectTarget, Connection, ConnectionError, type ConnectionOptions, type ConnectionState, type ConnectionStatus, type Frame, LatestValue, type Logger, type Message, type Params, type ParamsInput, type Reply, type ResourceInfo, type Serializer, type ServiceCard, type ServiceHandler, type ServiceRegistration, type StateDiff, StateHandle, type StreamEvent, type SubscribeOptions, type Subscription, SupersededError, Synapse, type SynapseOptions, SystemRole, type SystemState, type Target, TimeoutError, type TokenInput, type VerifyFn, type VerifyHandle, type WebSocketCtor, type WebSocketLike, address, serializer };
+export * from "@synapse-sdk/core";
+export { Synapse, FIRST_CONNECT_GIVE_UP_MS } from "./synapse.ts";
+export { defaultReconnectPolicy, exponentialPolicy, fixedPolicy, withMaxAttempts } from "./node.ts";
+export { callStream } from "./calls.ts";
+export { setMoqDebug } from "./moq_log.ts";
+export type * from "./types.ts";
+export { brokerCertHelperUrl, discoverBrokerCertSha256, ensureWebTransport } from "./session.ts";
+export { replaceEqualDeep, shallowEqual } from "./util.ts";
+export { orderAfter, orderBefore, orderBetween, ulid } from "./scene.ts";
+export { derivedFrameKey, derivedFrameName, materializeFrames, materializeHardpoints, validateDerivedFrame, type MaterializeReport } from "./scene_frames.ts";

package/dist/index.js

@@ -1,15 +1,10 @@
-import { a as Connection, c as BusError, d as ConnectionError, f as SupersededError, i as address, l as BusErrorCode, n as StateHandle, o as serializer, p as TimeoutError, r as Synapse, s as Channel, t as LatestValue, u as ChannelError } from "./node-CSSIXG4k.js";
-//#region src/types.ts
-/**
-* Server-assigned session role from the `synapse:system` handshake. **Open-ended** — the
-* server may assign roles beyond these (the Python node already has `agent`), so the type is
-* any string; the constants are just for ergonomic, typo-safe comparison
-* (`role === SystemRole.Controller`). Add entries here as the server grows.
-*/
-const SystemRole = {
-	Viewer: "viewer",
-	Controller: "controller",
-	Agent: "agent"
-};
-//#endregion
-export { BusError, BusErrorCode, Channel, ChannelError, Connection, ConnectionError, LatestValue, StateHandle, SupersededError, Synapse, SystemRole, TimeoutError, address, serializer };
+// @synapse-sdk/client: the Synapse node over @moq/net. Re-exports the core so one import suffices.
+export * from "@synapse-sdk/core";
+export { Synapse, FIRST_CONNECT_GIVE_UP_MS } from "./synapse.js";
+export { defaultReconnectPolicy, exponentialPolicy, fixedPolicy, withMaxAttempts } from "./node.js";
+export { callStream } from "./calls.js";
+export { setMoqDebug } from "./moq_log.js";
+export { brokerCertHelperUrl, discoverBrokerCertSha256, ensureWebTransport } from "./session.js";
+export { replaceEqualDeep, shallowEqual } from "./util.js";
+export { orderAfter, orderBefore, orderBetween, ulid } from "./scene.js";
+export { derivedFrameKey, derivedFrameName, materializeFrames, materializeHardpoints, validateDerivedFrame } from "./scene_frames.js";

package/dist/moq_log.d.ts

@@ -0,0 +1,23 @@
+/** Show @moq/net's debug narration (and the demoted routine-end lines) on `console.debug`; default off, or `SYNAPSE_MOQ_DEBUG=1`. */
+export declare function setMoqDebug(on: boolean): void;
+/** Exported for tests: whether a `console.debug` call is @moq/net's narration. */
+export declare function isMoqDebug(args: readonly unknown[]): boolean;
+/** One session's share of the registry: the paths it announced and whether we are closing it. */
+export interface MoqLogScope {
+    /** Records a broadcast path this session announces (`client/<name>/<sid>/...`). */
+    announced(path: string): void;
+    /** Records a broadcast path this session requests (subscribes to). */
+    requested(path: string): void;
+    /** Marks the session as closed by us: its tracks now end on purpose. */
+    closing(): void;
+    /** Drops the scope once @moq/net's late lines have had time to arrive. */
+    release(): void;
+}
+/** Registers a session with the filter; installs the `console.warn` wrapper on first use. */
+export declare function moqLogScope(): MoqLogScope;
+/** Forgets every scope; for tests, whose earlier nodes would otherwise still count as closing. */
+export declare function resetMoqLogScopes(): void;
+/** Restores the original `console.warn`/`console.debug`; for tests. */
+export declare function uninstallMoqLogFilter(): void;
+/** Exported for tests: whether a `console.warn` call from @moq/net describes the normal end of one of our tracks. */
+export declare function isRoutineEnd(args: readonly unknown[]): boolean;