@synapse-sdk/client 0.1.0 → 0.3.3

package/dist/session.d.ts

@@ -0,0 +1,250 @@
+import * as Moq from "@moq/net";
+import { ClockSync, SynapseError, type CallId, type ClockInfo, type ConnectRequest, 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 runtime's URL when the caller gave none: `SYNAPSE_ENDPOINT` (Bun/Node; the runtime sets it for every task it starts).
+ * A browser has no environment: there, as with neither, `invalid_input`.
+ */
+export declare function urlOrEndpoint(url: string | undefined): 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>;
+/**
+ * `token_from_url`: `url` without its `jwt=` query parameters, and the last non-empty one (as the relays
+ * read it). A URL without `jwt=`, or one that does not parse, is returned as it is (the dial reports it).
+ */
+export declare function tokenFromUrl(url: string): {
+    url: string;
+    token: string | undefined;
+};
+/**
+ * `Dial::new`: the one place a user's target becomes a dial. A `jwt=` in the URL is the token (the form
+ * the relays read), moved out of the URL here so no URL kept or printed afterwards holds it; a `token`
+ * given as such wins over one in the URL.
+ */
+export declare function makeDial(url: string, identity: Identity, cert: string | undefined, token: string | undefined): Dial;
+/** `root_runtime_id`: a root names a runtime when it is exactly `runtimes/<runtime id>` (a canonical lowercase UUID). */
+export declare function isRuntimeRoot(root: string): boolean;
+/**
+ * `with_root`: the URL to dial for `url`. `url` itself when it names a path (a runtime's root, or a
+ * relay's `runtimes/<runtime_id>`); else `url` with the root the runtime names at its plain-HTTP helper
+ * (`http://<host>:<port>/root`, the port of `url`, 443 when it has none), asked at every attempt. A
+ * helper that cannot be reached, answers non-2xx or answers incompletely is `connection_lost` (the
+ * runtime may be coming back); an answer that is not a root (`runtimes/<runtime id>` exactly; a relay has
+ * none: it serves many runtimes) is `invalid_input`, naming the fix. `signal` abandons the ask (its reason).
+ */
+export declare function withRoot(url: string, signal?: AbortSignal): Promise<string>;
+export interface RespFrame {
+    header: Header;
+    body: Uint8Array;
+}
+/** What one attempt dials (`Dial`): built by `makeDial` only, so `url` never holds the token. */
+export interface Dial {
+    url: string;
+    identity: Identity;
+    cert: string | undefined;
+    token: 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, connect: ConnectTrack, 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: withdraw our connect request (the runtime ends the session), fail its calls, finish our track, close the connection. Idempotent. */
+    close(): void;
+    createBroadcast(path: string): Moq.Broadcast.Producer;
+    request(path: string): Moq.Origin.Requesting;
+}
+/** What a connect attempt that got no answer reports (PLAN v0.26 §4 step 1): the request may have gone nowhere. */
+export declare const NO_ANSWER = "no runtime answered under this root (a relay drops out-of-scope publishes silently: check the token)";
+/** A session id for one connect attempt (PLAN v0.26 §5.1): 8 lowercase hex characters, 32 random bits. */
+export declare function mintSid(): string;
+/** Our connect request broadcast `client/<name>/<sid>/connect` and its `hello` track: the session lasts as long as it is announced. */
+export interface ConnectTrack {
+    bc: Moq.Broadcast.Producer;
+    track: CallWriter;
+}
+/** What the runtime answered a connect request with: the hello, and our `res` track at the path it grants (`hello.res`). */
+export interface Answered {
+    connect: ConnectTrack;
+    hello: Hello;
+    res: Moq.Broadcast.Consumer;
+    resSub: Moq.Track.Subscriber;
+}
+/**
+ * Asks the runtime for a session over an established connection (PLAN v0.26 §3.1): mint a `sid` for
+ * this attempt, write our connect request (`RPC_CALL`, `END`) on track `hello` of
+ * `client/<name>/<sid>/connect` and announce it on `pub`, then wait on `sub` for the answer on
+ * `client/<name>/<sid>/hello`: the hello (our prefix and role), or an error frame (`END|ERR`, the
+ * runtime's refusal, which is the attempt's error as it is: `admission_refused` when a live session
+ * holds the name, `invalid_input`, ...). Then our `res` track at the path the hello grants (`hello.res`,
+ * `runtime/rpc/@<epoch>`, PLAN v0.26 §7.2). No answer within
+ * `timeoutMs` is `not_connected` (`NO_ANSWER`). On any failure the request is withdrawn. `signal`
+ * abandons the wait (its reason is the error).
+ */
+export declare function requestSession(pub: Moq.Origin.Producer, sub: Moq.Origin.Producer, request: ConnectRequest, timeoutMs: number, log: MoqLogScope, signal: AbortSignal): Promise<Answered>;
+/**
+ * Opens one session to `dial` (PLAN v0.26 §3.1): the path to dial is the URL's own or, for a bare
+ * `https://host:port`, the root the runtime names (`withRoot`, asked at every attempt); dial with our name
+ * (the relay level's scope) and the token (`jwt=`, through a relay) as the only query parameters; ask the runtime for a session (`requestSession`: our identity and project
+ * intent go in the connect request), then announce our `req` track on the path the hello grants (`hello.rpc`).
+ * A relay's refusal of the connection shows up as the session closing: an observed close wins, and a
+ * transport failure of a step is settled against the close (`CLOSE_GRACE_MS`). `signal` abandons the
+ * dial: every wait stops at once and the half-open connection is closed (`canceled`); the connection
+ * not established within the connect timeout is `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 };