@synapse-sdk/client 0.1.0 → 0.3.0

package/dist/session.d.ts

@@ -0,0 +1,189 @@
+import * as Moq from "@moq/net";
+import { ClockSync, SynapseError, type CallId, type ClockInfo, type ErrorBody, type Header, type Hello, type Identity, type ProjectSnapshot, type Role, type ServicesSnapshot, type TimeOffsets, type TopicsSnapshot } from "@synapse-sdk/core";
+import { type MoqLogScope } from "./moq_log.ts";
+import { Cell, deferred } from "./util.ts";
+import type { Notice } from "./types.ts";
+/** Default datagram budget (WP §6.2): Chrome reports `maxDatagramSize` 1024; native quinn hops allow about 1150. */
+export declare function defaultMaxDatagram(): number;
+export declare function isNodeLike(): boolean;
+/** A `stream` reader never abandons a finished group: an effectively infinite moq latency budget (`u32::MAX` ms, as the Rust client). */
+export declare const STREAM_READER_MAX_AGE_MS = 4294967295;
+export declare const streamSubscription: (priority: number) => Moq.Track.Subscription;
+/** The latest-value subscription (snapshot tracks, `desc`, `card`): newest group only. */
+export declare const latestSubscription: (priority: number, maxAgeMs?: number) => Moq.Track.Subscription;
+/**
+ * The age budget of a call track's group (Rust `CALL_GROUP_MAX_AGE`, 60 s): the retention every call
+ * track we write (`req`, `out`) declares, the budget its readers (`res`, `calls`) subscribe with, and how
+ * long a reader waits for the group due while a later group is held.
+ */
+export declare const CALL_GROUP_MAX_AGE_MS = 60000;
+export declare const callTrackInfo: (priority: number) => Partial<Moq.Track.Info>;
+/** A call track reader's subscription (`res`, `calls`): the call track budget. */
+export declare const callTrackSubscription: (priority: number) => Moq.Track.Subscription;
+/**
+ * Retention of a one-frame track (`card`, `desc`): the frame lives as long as the track. The Rust moq
+ * keeps a track's latest group for the track's life; the JS one prunes it after its default 5 s, so a
+ * subscriber joining later would get nothing.
+ */
+export declare const RETAINED_FRAME_MAX_AGE_MS = 4294967295;
+/** A call track starts a new group after this many frames (moq's cap on a group). */
+export declare const CALL_GROUP_FRAMES = 8192;
+/** A `stream` topic subscriber's age budget (`STREAM_SUBSCRIBE_MAX_AGE`, 3 × the group span): a reader further behind skips whole groups. */
+export declare const streamTopicSubscription: (priority: number) => Moq.Track.Subscription;
+/**
+ * A `stream` topic's writer (WP §6, the Rust `TrackWriter`): frames go into one MoQ group at a time, in
+ * order; the writer finishes the open group and starts the next when the open one is older than
+ * `STREAM_GROUP_SPAN_MS`, or when the next frame would pass moq's caps. A late joiner reads from the
+ * start of the group the relay holds, so it is at most one span behind.
+ */
+export declare class StreamWriter {
+    #private;
+    readonly track: Moq.Track.Producer;
+    constructor(track: Moq.Track.Producer);
+    write(header: Header, body: Uint8Array): void;
+    close(): void;
+}
+export declare function moqTimestamp(tUs: number | bigint): Moq.Time.Timestamp;
+/** The error for a frame refused because it is over moq's 32 MiB limit (Rust `frame_too_large`): `invalid_input`, naming the limit. */
+export declare function frameTooLarge(what: string, len: number): SynapseError;
+/**
+ * A call track writer (`req`, `out`): frames into one group after another. The open group is finished
+ * and the next one started when the next frame would pass `CALL_GROUP_FRAMES` frames or moq's 32 MiB of
+ * bytes in the group. A frame over 32 MiB on its own is refused (`frameTooLarge`) before anything is written.
+ */
+export declare class CallWriter {
+    #private;
+    readonly track: Moq.Track.Producer;
+    constructor(track: Moq.Track.Producer);
+    static create(bc: Moq.Broadcast.Producer, name: string): CallWriter;
+    write(header: Header, body: Uint8Array): void;
+    close(): void;
+}
+/** One latest-value frame (`desc`, `card`, a snapshot): its own group, one frame, closed; the relay caches the newest. */
+export declare function writeLatest(track: Moq.Track.Producer, header: Header, body: Uint8Array): void;
+/** Waits for a requested broadcast to become routable. */
+export declare function waitActive(req: Moq.Origin.Requesting, timeoutMs: number, signal?: AbortSignal): Promise<Moq.Broadcast.Consumer>;
+/** A frame sink; a returned promise is awaited before the next frame. */
+export type FrameSink = (payload: Uint8Array) => void | Promise<void>;
+/**
+ * Reads a call track (`res`, `calls`, a FEC `report`) frame by frame, as the Rust `read_call_track`:
+ * groups are taken strictly in sequence from group 0, group k read to its end before group k+1. A
+ * group that arrives before its turn is held (a track's groups travel on streams of their own, so
+ * group 1 can arrive before group 0). The read ends with an error when a group older than the one due
+ * arrives, when a group's read fails (reset or expired), when the subscription fails, or when the
+ * group due has not arrived within `CALL_GROUP_MAX_AGE_MS` while a later group is held (that wait
+ * is armed only then; with nothing later held the reader waits for the next group with no timer).
+ * Returns `null` when the track ended cleanly or `signal` aborted, otherwise the error.
+ */
+export declare function readTrack(sub: Moq.Track.Subscriber, onFrame: FrameSink, signal?: AbortSignal): Promise<unknown>;
+export declare function readDatagrams(sub: Moq.Track.Subscriber, onDatagram: FrameSink, signal?: AbortSignal): Promise<unknown>;
+/** Installs `@moq/web-transport` in Bun/Node when the runtime has no WebTransport. Browsers skip this. */
+export declare function ensureWebTransport(): Promise<void>;
+/** A connect failure's text (`@moq/net` races WebTransport against WebSocket and rejects with an `AggregateError`). */
+export declare function describeError(e: unknown): string;
+/**
+ * The error of a session's close (`classify_close`): `admission_refused` travels as the application
+ * close code (retryable: a live session may hold this name, the project may be settling), another
+ * application code is a broker-side failure, `unauthorized` is the relay's own refusal, everything
+ * else is the transport (`connection_lost`); a clean close is a drop too (in one-shot mode a broker
+ * GOAWAY looks like one).
+ */
+export declare function closeError(err: Error | null): SynapseError;
+/** `https://host:port/<root>` → `http://host:port/certificate.sha256`, the broker's plain-HTTP helper. */
+export declare function brokerCertHelperUrl(brokerUrl: string): string;
+/** The certificate pin when the caller gave none (SDK §13): `SYNAPSE_BROKER_CERT_SHA256` (Bun/Node), then the helper, then `undefined` = unpinned. Per attempt. */
+export declare function discoverBrokerCertSha256(brokerUrl: string, opts?: {
+    timeoutMs?: number;
+    signal?: AbortSignal;
+}): Promise<string | undefined>;
+export interface RespFrame {
+    header: Header;
+    body: Uint8Array;
+}
+/** What one attempt dials (`Dial`). */
+export interface Dial {
+    url: string;
+    identity: Identity;
+    cert: string | undefined;
+}
+export interface SessionKnobs {
+    transport: "auto" | "webtransport" | "websocket";
+    connectTimeoutMs: number;
+    maxDatagram: number;
+    project?: "operator";
+}
+/** A notice the broker wrote on this session's `res` track, handed to the node's loop. */
+export type BrokerNotice = {
+    kind: "error";
+    body: ErrorBody;
+} | {
+    kind: "project";
+    notice: Notice;
+};
+/** The key of a call in the session's pending map. */
+export declare const callKey: (id: CallId) => string;
+export declare class Session {
+    #private;
+    readonly url: string;
+    readonly conn: Moq.Connection.Established;
+    readonly pub: Moq.Origin.Producer;
+    readonly sub: Moq.Origin.Producer;
+    readonly hello: Hello;
+    readonly maxDatagram: number;
+    readonly log: MoqLogScope;
+    /** Counts *established* sessions of the node (SDK §2); set by the node when attached. */
+    epoch: number;
+    readonly startedMs: number;
+    readonly transport: "webtransport" | "websocket";
+    /** Datagrams travel only over WebTransport; the WebSocket fallback is stream-only. */
+    readonly datagrams: boolean;
+    /** The views this session reads (latest values). */
+    readonly topics: Cell<TopicsSnapshot>;
+    readonly services: Cell<ServicesSnapshot>;
+    readonly timeOffsets: Cell<TimeOffsets>;
+    readonly project: Cell<ProjectSnapshot | undefined>;
+    readonly clock: Cell<ClockInfo>;
+    /** Where notices go: the node's loop sets this at attach. */
+    onNotice: ((n: BrokerNotice) => void) | undefined;
+    /** Settles with the close's error once the connection closed. */
+    readonly closed: Promise<Error | null>;
+    constructor(url: string, conn: Moq.Connection.Established, pub: Moq.Origin.Producer, sub: Moq.Origin.Producer, hello: Hello, maxDatagram: number, log: MoqLogScope, reqBc: Moq.Broadcast.Producer, res: Moq.Broadcast.Consumer, resSub: Moq.Track.Subscriber, dom: string);
+    get prefix(): string;
+    get role(): Role;
+    nowUs(): number;
+    /** Whether the session still takes requests (not torn down). */
+    get isLive(): boolean;
+    /** The broker's reason, when it closed this session with a closing notice (or a watcher lost its track). */
+    get closingReason(): string | undefined;
+    /** Appends a frame to our `req` track (WP §8.6). `connection_lost` once the session has ended. */
+    writeReq(header: Header, body: Uint8Array): void;
+    /** Writes call `id`'s request and registers where its frames go, both while the session takes requests. */
+    /** `deliver(null)` = the session ended with the call pending. */
+    writeCall(header: Header, body: Uint8Array, id: CallId, deliver: (f: RespFrame | null) => void): void;
+    forgetCall(id: CallId): void;
+    /** Stops taking requests and fails every call pending here (`deliver(null)`: `connection_lost`). The first step of a teardown; idempotent. */
+    endCalls(): void;
+    /** A task of this session lost what it reads, or the broker announced the close: record `reason` (the first stands) and close the connection. The loop does the rest. */
+    lost(reason: string): void;
+    /** Starts the session's tasks: the `res` demux, the four snapshot watchers, the clock probe (unless the broker shares our domain). Each writes only into this session. */
+    start(sync: ClockSync, startCall: (svc: string, args: unknown) => Promise<unknown>): void;
+    /** Stops and awaits the tasks (bounded), then closes the session: track finished, MoQ close sent. */
+    teardown(graceMs?: number): Promise<void>;
+    /** The synchronous end: fail its calls, finish our track, close the connection. Idempotent. */
+    close(): void;
+    createBroadcast(path: string): Moq.Broadcast.Producer;
+    request(path: string): Moq.Origin.Requesting;
+}
+/**
+ * Opens one session to `dial`: connect with our identity as query parameters (WP §3.1), wait for
+ * the hello on `client/<name>/hello` (readiness + grant proof + our prefix), find our `res` track at
+ * `runtime/rpc/<sid>`, announce our `req` track under the prefix. A refused admission shows up as
+ * the session closing before the hello: the close decides the error. `signal` abandons the dial: every
+ * wait stops at once and the half-open connection is closed (`canceled`), as the connect timeout does
+ * (`connection_lost`).
+ */
+export declare function openSession(knobs: SessionKnobs, dial: Dial, dom: string, signal?: AbortSignal): Promise<Session>;
+/** The error a call pending on a session that ended reports (WP §8.4: the request was written, so it may have run). */
+/** `data` is `{ outcome: "unknown" }`, with `reason` when the session's close had one (Rust `outcome_unknown_data`). */
+export declare function outcomeUnknown(closing: string | undefined): SynapseError;
+export { deferred };