@synapse-sdk/client 0.3.0 → 0.3.4

package/dist/topics.js

@@ -12,11 +12,11 @@
 // when every listed publisher not held is tried again; no timer of our own. A datagram publisher
 // whose own `desc` has `fec` gets a follower (the video path: `FecReader` per publisher).
 import * as Moq from "@moq/net";
-import { FLAGS, MSGPACK, SynapseError, TYPES, decode as decodeBody, decodeHeader, encode as encodeBody, fecSymbolSizeFor, frame, moqPriority, nowUs, stampSentUs, hasPendingSentUs, mediaHeader, topicPath, validateSync, } from "@synapse-sdk/core";
+import { FLAGS, MSGPACK, SynapseError, TYPES, auParamSets, auSyncPoints, decode as decodeBody, decodeHeader, encode as encodeBody, fecSymbolSizeFor, frame, isVideo, mediaFlags, moqPriority, nowUs, stampSentUs, hasPendingSentUs, mediaHeader, topicPath, validateSync, } from "@synapse-sdk/core";
 import { Handle, start as startHandle } from "./channel.js";
 import { FecReader, FecWriter, ReportWriter, feedbackListener, requireFec } from "./fec.js";
 import { RETAINED_FRAME_MAX_AGE_MS, StreamWriter, latestSubscription, moqTimestamp, streamTopicSubscription, waitActive, writeLatest } from "./session.js";
-import { AsyncQueue, deferred, withTimeout, TIMEOUT } from "./util.js";
+import { AsyncQueue, deferred, rethrowLater, withTimeout, TIMEOUT } from "./util.js";
 /** moq's cap on one `stream` frame (a group's cache). */
 const STREAM_FRAME_MAX = 32 * 1024 * 1024;
 /** The bound on adding one publisher (its broadcast, its `desc`, its `data` subscription). */
@@ -152,26 +152,35 @@ export class TopicPublisher {
         else
             this.droppedDisconnected++;
     }
-    /** The typed form: validates against the contract's schema, encodes (msgpack, or the bytes of a raw topic). */
+    /**
+     * 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, opts = {}) {
-        let body;
+        const tUs = opts.tUs ?? nowUs();
         if (this.contract.raw) {
             if (!(value instanceof Uint8Array))
                 throw new SynapseError("invalid_input", `topic ${this.name} (${this.contract.contentType}) takes bytes`);
-            body = value;
-        }
-        else {
-            let v = value;
-            if (this.contract.schema) {
-                const r = validateSync(this.contract.schema, value);
-                if (r.issues)
-                    throw new SynapseError("invalid_input", { message: r.issues[0]?.message ?? "invalid value", data: { issues: r.issues } });
-                v = r.value;
+            if (!isVideo(this.contract.contentType)) {
+                this.publishFrame(TYPES.PUB, opts.flags ?? 0, tUs, [], value);
+                return;
             }
-            body = encodeBody(v);
+            const { idr, recovery } = auSyncPoints(value);
+            this.publishFrame(TYPES.MEDIA, mediaFlags({ key: idr, config: auParamSets(value) !== undefined, recovery }) | (opts.flags ?? 0), tUs, [], value);
+            return;
         }
-        this.publishFrame(TYPES.PUB, opts.flags ?? 0, opts.tUs ?? nowUs(), [], body);
+        let v = value;
+        if (this.contract.schema) {
+            const r = validateSync(this.contract.schema, value);
+            if (r.issues)
+                throw new SynapseError("invalid_input", { message: r.issues[0]?.message ?? "invalid value", data: { issues: r.issues } });
+            v = r.value;
+        }
+        this.publishFrame(TYPES.PUB, opts.flags ?? 0, tUs, [], encodeBody(v));
     }
+    /** 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) { const h = mediaHeader(f, 0); this.publishFrame(h.type, h.flags, f.tUs || nowUs(), h.tlvs ?? [], f.data); }
     stats() {
         const s = { published: this.published, droppedDisconnected: this.droppedDisconnected };
         if (this.fecStats)
@@ -199,6 +208,12 @@ function finish(b) {
     }
     catch { /* closed */ }
 }
+/**
+ * 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 const PUBLISH_MEDIA_FRAME = Symbol.for("@synapse-sdk/client:publishMediaFrame");
 /** The application's handle: the last one closed ends the publisher's task (`unregister`). */
 export class PublisherHandle {
     p;
@@ -216,10 +231,8 @@ export class PublisherHandle {
     #open() { if (this.#closed)
         throw new SynapseError("not_connected", "publisher closed"); }
     publish(value, opts) { this.#open(); this.p.publish(value, opts); }
-    /** Any frame type and TLVs (`MEDIA` with `STAGES`, WP §4); raw topics only. */
-    publishFrame(type, flags, tUs, tlvs, body) { this.#open(); this.p.publishFrame(type, flags, tUs, tlvs, body); }
-    /** `tUs` 0 = capture now (as the Rust client stamps it). */
-    publishMedia(f) { this.#open(); const h = mediaHeader(f, 0); this.p.publishFrame(h.type, h.flags, f.tUs || nowUs(), h.tlvs ?? [], f.data); }
+    /** `@synapse-sdk/media`'s video publisher: an encoder's frame with its flags and `STAGES` (see `PUBLISH_MEDIA_FRAME`). */
+    [PUBLISH_MEDIA_FRAME](f) { this.#open(); this.p.publishMediaFrame(f); }
     stats() { return this.p.stats(); }
     close() {
         if (this.#closed)
@@ -415,7 +428,12 @@ export class TopicSubscription {
     /** A new session (or none): the `fec` frames and a batch held by `throttleMs` are the previous session's and go. */
     clearFec() { this.#fec.length = 0; this.#throttled = undefined; }
     #signal() { const w = this.#wake; this.#wake = undefined; w?.resolve(); }
-    /** The decoding step: header facts plus the body through the contract, or `mismatch` and dropped. */
+    /**
+     * 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;
+    /** 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, publisher, dom) {
         let header, hlen;
         try {
@@ -427,7 +445,7 @@ export class TopicSubscription {
         }
         const body = payload.subarray(hlen);
         let data;
-        if (this.contract.raw)
+        if ((this.contentType ?? this.contract.contentType) !== MSGPACK)
             data = body;
         else {
             let v;
@@ -448,7 +466,8 @@ export class TopicSubscription {
             }
             data = v;
         }
-        return { data, tUs: Number(header.tUs), seq: header.seq, publisher, dom, flags: header.flags, type: header.type, tlvs: header.tlvs ?? [] };
+        const f = header.flags;
+        return { data, tUs: Number(header.tUs), seq: header.seq, publisher, dom, flags: f, type: header.type, tlvs: header.tlvs ?? [], key: (f & FLAGS.KEY) !== 0, config: (f & FLAGS.CONFIG) !== 0, recovery: (f & FLAGS.RECOVERY) !== 0 };
     }
     /** One payload taken from `src` (Rust `drain_source`'s step): every-message mode keeps it, latest mode keeps the newest `seq`. */
     #take(src, payload, t, nowUs_) {
@@ -608,6 +627,22 @@ export class TopicSubscription {
         this.#signal();
     }
     async [Symbol.asyncDispose]() { this.unsubscribe(); }
+    /** The callback form's read loop (`node.subscribe(topic, cb)`): `cb` with each batch `next()` returns, until the subscription ends; a throwing `cb` is rethrown later and the loop goes on. */
+    deliverTo(cb) {
+        void (async () => {
+            for (;;) {
+                const b = await this.next();
+                if (!b)
+                    return;
+                try {
+                    cb(b);
+                }
+                catch (e) {
+                    rethrowLater(e);
+                }
+            }
+        })();
+    }
 }
 /** A source is done: its subscription and its request are closed (its pending read settles as the end). */
 function closeSource(src) {
@@ -676,6 +711,8 @@ async function followTopic(sub) {
             if (session && snapshot) {
                 const entry = snapshot.topics[contract.name];
                 delivery = entry?.desc?.delivery ?? contract.delivery;
+                // ... and so is the body's `content_type` (what the read decodes by).
+                sub.contentType = entry?.desc?.content_type;
                 const wanted = new Map();
                 if (entry)
                     for (const [prefix, l] of Object.entries(entry.publishers))