@synapse-sdk/client 0.1.0 → 0.3.3

package/dist/topics.d.ts

@@ -0,0 +1,151 @@
+import * as Moq from "@moq/net";
+import { type FecParams, type FecWasm, type MediaFrame, type TopicContract, type TrackDesc, type Tlv } from "@synapse-sdk/core";
+import { Handle, type Event as HandleEvent, type Intent } from "./channel.ts";
+import { type FecPubStats } from "./fec.ts";
+import type { Node } from "./node.ts";
+import { type Session } from "./session.ts";
+import type { Envelope, PublishOptions, Publisher, PublisherStats, SubStats, SubscribeOptions, Subscription, Verdict } from "./types.ts";
+export type Warn = (msg: string) => void;
+/** The publisher shared by every `publisher(topic)` handle of one topic on this node. */
+export declare class TopicPublisher<TIn, TOut> implements Intent {
+    #private;
+    readonly node: Node;
+    readonly contract: TopicContract<TIn, TOut>;
+    private readonly wasm;
+    readonly warn: Warn;
+    readonly name: string;
+    readonly registerSvc = "synapse/topic/register";
+    readonly unregisterSvc = "synapse/topic/unregister";
+    readonly desc: TrackDesc;
+    readonly fecParams: FecParams | undefined;
+    readonly fecStats: FecPubStats | undefined;
+    published: number;
+    droppedDisconnected: number;
+    handles: number;
+    readonly handle: Handle;
+    constructor(node: Node, contract: TopicContract<TIn, TOut>, maxDatagram: number, wasm: FecWasm | undefined, warn: Warn);
+    get verdict(): Verdict;
+    get isBound(): boolean;
+    registerArgs(bind: string): unknown;
+    unregisterArgs(bind: string): unknown;
+    /** Admitted: the broadcast is created, the descriptor written, the data track made, then announced (WP §7.1). */
+    install(s: Session, bind: string, _mailbox: (e: HandleEvent) => void): void;
+    retract(): void;
+    setVerdict(v: Verdict): void;
+    /**
+     * Publishes one frame (SDK §13: synchronous, never awaits the network). While nothing is installed
+     * (between sessions, a refused register being asked again) the frame is dropped and counted. A
+     * `stream` frame over moq's cap, a plain datagram over the session's datagram size, or a `fec`
+     * frame the codec refuses is refused (`invalid_input`) without taking a `seq`.
+     */
+    publishFrame(type: number, flags: number, tUs: number, tlvs: Tlv[], body: Uint8Array): void;
+    /**
+     * The typed form: validates against the contract's schema and encodes msgpack; a raw topic's bytes
+     * go as given, and on a `video/*` topic as a `MEDIA` frame whose `KEY`/`CONFIG`/`RECOVERY` flags
+     * are read off the bitstream (Rust `Publisher<RawBody>::publish`).
+     */
+    publish(value: TIn, opts?: PublishOptions): void;
+    /** An encoder's frame with the flags it already carries and its `STAGES` stamps (no re-parse); `tUs` 0 = now. The video helper's path (Rust `publish_media_frame`), not a user verb. */
+    publishMediaFrame(f: MediaFrame): void;
+    stats(): PublisherStats;
+}
+/**
+ * The key of a publisher handle's encoder-frame path, the JS spelling of Rust's `pub(crate)
+ * publish_media_frame`: `@synapse-sdk/media`'s `videoPublisher` reaches it by the same
+ * `Symbol.for` key (the two packages share no module), so it is on no public type.
+ */
+export declare const PUBLISH_MEDIA_FRAME: unique symbol;
+/** The application's handle: the last one closed ends the publisher's task (`unregister`). */
+export declare class PublisherHandle<TIn, TOut> implements Publisher<TIn> {
+    #private;
+    private readonly p;
+    private readonly onLast;
+    constructor(p: TopicPublisher<TIn, TOut>, onLast: () => void);
+    get topic(): string;
+    get verdict(): Verdict;
+    ready(): Promise<void>;
+    publish(value: TIn, opts?: PublishOptions): void;
+    /** `@synapse-sdk/media`'s video publisher: an encoder's frame with its flags and `STAGES` (see `PUBLISH_MEDIA_FRAME`). */
+    [PUBLISH_MEDIA_FRAME](f: MediaFrame): void;
+    stats(): PublisherStats;
+    close(): void;
+    [Symbol.asyncDispose](): Promise<void>;
+}
+/** Resolves the codec a `fec` topic needs (once per process). */
+export declare function wasmFor(contract: TopicContract<unknown, unknown>): Promise<FecWasm | undefined>;
+/** What a source gives when its track ended. */
+declare const END: unique symbol;
+/**
+ * One plain publisher the read takes from (Rust `Source`). A stream source is read synchronously
+ * by `next()` (`tryRecvGroup` / `tryReadFrame`, as Rust's poll); when nothing is buffered it holds
+ * exactly one pending read (`recvGroup` / `readFrame`) as the wake, whose result is the first item
+ * of the next drain. A datagram source has one reader (one `recvDatagram` at a time) filling
+ * `held`: latest mode keeps one (the newest `seq`), every-message mode at most `DATAGRAM_RING`.
+ */
+interface Source {
+    path: string;
+    prefix: string;
+    publisher: string;
+    dom: string;
+    /** The request for the publisher's broadcast: closed with the source. */
+    req: Moq.Origin.Requesting;
+    sub: Moq.Track.Subscriber;
+    /** Read as a stream (groups of frames) or as datagrams: the catalog's delivery for the topic. */
+    stream: boolean;
+    /** A stream source: the group being read. */
+    group: Moq.Group.Consumer | undefined;
+    /** A stream source: the pending read that wakes the read when nothing is buffered. */
+    wait: Promise<void> | undefined;
+    /** A stream source: what that pending read gave (a frame, or the track's end), taken first. */
+    ready: Uint8Array | typeof END | undefined;
+    /** A datagram source: the datagrams its reader took and the read has not. */
+    held: Uint8Array[];
+    /** A datagram source in latest mode: the `seq` of the one held. */
+    heldSeq: number | undefined;
+    /** A datagram source: its reader saw the track end; the end is given once `held` is drained. */
+    done: boolean;
+    /** The `seq` last returned (latest mode): not newer is superseded. */
+    last: number | undefined;
+    ended: boolean;
+}
+export declare class TopicSubscription<T> implements Subscription<T> {
+    #private;
+    readonly node: Node;
+    readonly contract: TopicContract<unknown, T>;
+    readonly opts: SubscribeOptions;
+    readonly warn: Warn;
+    readonly topic: string;
+    readonly stats: SubStats;
+    readonly latest: boolean;
+    constructor(node: Node, contract: TopicContract<unknown, T>, opts: SubscribeOptions, warn: Warn);
+    get signal(): AbortSignal;
+    get ownDom(): string;
+    /** The follow task hands a plain publisher here (a datagram source's reader starts); the waiting `next()` is woken. */
+    addSource(src: Source): void;
+    /** The publisher leaves the read: its subscription and request are closed, a payload it gave is never returned. */
+    removeSource(src: Source): void;
+    /** A `fec` follower's frame: latest mode replaces the publisher's pending one. */
+    pushFec(env: Envelope<T>): void;
+    dropFecOf(publisher: string): void;
+    /** A new session (or none): the `fec` frames and a batch held by `throttleMs` are the previous session's and go. */
+    clearFec(): void;
+    /**
+     * The established descriptor's `content_type` (the catalog's, the runtime's statement), set by the
+     * follow task from each snapshot: bodies decode by it, not by what this subscription declared.
+     */
+    contentType: string | undefined;
+    /** The decoding step: header facts plus the body by the established `content_type` (msgpack → a value, validated when the contract has a schema; anything else → bytes), or `mismatch` and dropped. */
+    envelope(payload: Uint8Array, publisher: string, dom: string): Envelope<T> | undefined;
+    /**
+     * The next batch, never empty; `undefined` once the subscription or the node ended. Drains what
+     * every source has ready, synchronously (at most `DRAIN_PER_READ` per source), and the `fec`
+     * frames; with nothing to return it waits for a source's pending read or reader, a `fec` frame,
+     * a change of the set or the end of a `throttleMs` interval, and drains again.
+     */
+    next(): Promise<Envelope<T>[] | undefined>;
+    [Symbol.asyncIterator](): AsyncGenerator<Envelope<T>[], void, undefined>;
+    /** Ends the subscription: the follow task stops, every track is closed, a pending `next()` returns `undefined`. */
+    unsubscribe(): void;
+    [Symbol.asyncDispose](): Promise<void>;
+}
+export {};