From 568282875a2ea682f5db2ffd380d985b2934f73c Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Mon, 5 Oct 2026 23:48:29 -0700 Subject: [PATCH 1/8] quest: claim json-stream-budget Co-Authored-By: Claude Opus 5.5 From 0a8cbc7dfdd5143f412d94984a592fa113153fad Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 6 Oct 2026 00:31:31 -0700 Subject: [PATCH 2/8] fix(json): refuse a stream record past the group budget without ending the log A moq-json or @moq/json Stream append that might not fit the group budget (32 MiB or 8192 frames) now fails with GroupTooLarge before it is encoded, leaving the log intact in both compression modes. The check counts the raw size plus DEFLATE's worst-case overhead, tracked inside the encoders. A JS subscribe to a track a broadcast does not have, with nothing serving requests on demand, now answers NotFound like Rust instead of waiting forever, and a finished inserted track keeps serving its cache. Co-Authored-By: Claude Opus 5.5 --- doc/lib/js/json.md | 8 +++ doc/lib/js/net.md | 2 +- doc/lib/rs/moq-json.md | 6 ++ js/json/src/stream/codec.test.ts | 20 ++++-- js/json/src/stream/encoder.ts | 41 +++++++++-- js/json/src/stream/index.ts | 7 ++ js/json/src/stream/producer.ts | 17 +++-- js/json/src/stream/stream.test.ts | 34 ++++++++- js/net/src/broadcast.test.ts | 73 +++++++++++++------ js/net/src/broadcast.ts | 111 ++++++++++++++++++----------- quest/m1/README.md | 1 - quest/m1/json-stream-budget.md | 40 ----------- rs/moq-json/src/stream/encoder.rs | 75 +++++++++++++++++-- rs/moq-json/src/stream/mod.rs | 84 ++++++++++++++++++++-- rs/moq-json/src/stream/producer.rs | 15 ++-- rs/moq-mux/src/json.rs | 31 +++++++- 16 files changed, 426 insertions(+), 139 deletions(-) delete mode 100644 quest/m1/json-stream-budget.md diff --git a/doc/lib/js/json.md b/doc/lib/js/json.md index a7f56953d1e..0d5ae63626a 100644 --- a/doc/lib/js/json.md +++ b/doc/lib/js/json.md @@ -36,4 +36,12 @@ for await (const value of consumer) { A value is stamped when written, unless you pass its capture time: `producer.update(value, at)`. +A Stream rides one group, so the whole log shares `@moq/net`'s group budget: +32 MiB of payload and 8192 records. An `append` that might not fit throws +`GroupTooLarge` before it is encoded and leaves the log intact, compressed or +not. With `"deflate"` the check counts the raw JSON plus DEFLATE's worst-case +overhead. Once the budget is spent every `append` throws; start a new track to +keep going. Any other failed append aborts the track, so readers see the error +rather than a log that looks complete. + The Rust twin is [`moq-json`](/lib/rs/moq-json). diff --git a/doc/lib/js/net.md b/doc/lib/js/net.md index aae825f85f4..55006da00c2 100644 --- a/doc/lib/js/net.md +++ b/doc/lib/js/net.md @@ -55,7 +55,7 @@ for (;;) { - **Discovery** by any pattern scope (`origin.announced(scope)`, such as `room/*/chat`; default everything). A route event's `kind` says whether the route started, updated, or ended; its `prefix` is the covered prefix relative to the origin, and `captures` reports what the scope's wildcards matched when the prefix pins them. One `{ kind: "live" }` marker, with no prefix, follows the routes live at subscribe time. The consumer is an async iterable. `origin.broadcasts(scope)` is a live `Getter>` of the same covered prefixes for UIs that need the current set. A borrowed `Connection.origin` also exposes `dynamic(prefix, route)` for serving paths on demand. - **Publisher retention** is optional `Track.Info.maxAge`: omission sets no limit, while zero keeps the live edge. No implicit five-second window is applied. - **Subscriptions** carry a priority, a `Time.Milli` max age, and optional `groups` bounds. Groups arrive out of order and are read frame by frame, with `Error.TooFarBehind` when a reader asks for a frame the group never held and `Error.GroupTooLarge` when a write exceeds the cache budget and aborts the group. -- **Track ends**: `close()` ends a track at its live edge, while `finishAt(n)` declares the exclusive end ahead of it and still accepts the groups below. A subscriber reads the end with `final()` or awaits `finished()`. Group and datagram readers end once the live edge reaches the declared boundary, even while missing lower groups wait out the grace. The `closed` signal settles separately once every group below the end has arrived or was dropped; one reset before its header arrived is skipped after the subscription's max age on moq-lite (one second without one), or after one second on IETF. +- **Track ends**: `close()` ends a track at its live edge, while `finishAt(n)` declares the exclusive end ahead of it and still accepts the groups below. A finished track stays on its broadcast and serves its cache to late subscribers until `removeTrack`; an aborted one is removed, and subscribing to a track the broadcast does not have rejects with `Error.NotFound`, as in Rust. A subscriber reads the end with `final()` or awaits `finished()`. Group and datagram readers end once the live edge reaches the declared boundary, even while missing lower groups wait out the grace. The `closed` signal settles separately once every group below the end has arrived or was dropped; one reset before its header arrived is skipped after the subscription's max age on moq-lite (one second without one), or after one second on IETF. - **Datagrams** on moq-lite 05+ and fetch-by-sequence for history. `track.fetchGroup(sequence)` on moq-lite resolves when the publisher sends the first response byte or finishes an empty group. A missing group rejects the fetch with `StreamCode.NotFound`, including every concurrent caller sharing that fetch. `fetchGroup(sequence, { signal })` abandons a pending fetch with the signal's reason; the shared stream is cancelled only once every caller has left. Once resolved, close the group instead. - **Errors**: deliberately closing a connection ends its received tracks cleanly. A peer close ends received tracks and open group readers with the session error and its close code. Errors live under one namespace: a stream reset throws `Error.Stream` with a `StreamCode`, while a session close gives `Error.Session` with a `SessionCode`. The registries are disjoint, so the same number means different things in each, and 64+ is yours. Named conditions such as `Error.TooFarBehind`, `Error.FrameTooLarge`, and `Error.GroupTooLarge` subclass `Error.Stream`, so one `code` check handles a condition raised here or reported by the peer. IETF streams use their own mapping: cancellation sends CANCELLED, other local failures send INTERNAL\_ERROR, and received codes remain opaque. - **Paths** with `Path.relative` for the cross-broadcast catalog references hang uses. A `Broadcast.Consumer` names its broadcast by `path`: the path it was requested at relative to the origin handle's root, or empty for a standalone broadcast. Those references resolve against it. Path patterns (`Path.Pattern`, `Path.Patterns`) are re-exported from [`@moq/pattern`](https://www.npmjs.com/package/@moq/pattern). Literal `Path` stays a coordinate. diff --git a/doc/lib/rs/moq-json.md b/doc/lib/rs/moq-json.md index 40e8ef812fa..172074e0395 100644 --- a/doc/lib/rs/moq-json.md +++ b/doc/lib/rs/moq-json.md @@ -32,6 +32,12 @@ A value is stamped when written, unless it carries its capture time: `moq_net::Timed::from(&value).at(captured)`. Writes return the encoded frame size, and an unchanged snapshot `update` returns `None`. +A stream rides one group, so the whole log shares moq-net's group budget: +32 MiB of payload and 8192 records. An `append` that might not fit returns +`moq_net::Error::GroupTooLarge` before it is encoded and leaves the log intact, +compressed or not. Once the budget is spent every `append` is refused; start a +new track to keep going. + A snapshot producer also edits in place, so independent owners each touch only their own keys instead of clobbering one another. `mutate(|value| ...)` runs a closure and publishes the result, matching `Producer.mutate` in TypeScript; diff --git a/js/json/src/stream/codec.test.ts b/js/json/src/stream/codec.test.ts index 29cb62fe8e8..07c4a2b3fc7 100644 --- a/js/json/src/stream/codec.test.ts +++ b/js/json/src/stream/codec.test.ts @@ -1,5 +1,5 @@ -import { expect, test } from "bun:test"; -import { Group, Error as NetError, Track } from "@moq/net"; +import { expect, spyOn, test } from "bun:test"; +import { Group, Track } from "@moq/net"; import * as z from "@zod/mini"; import { Desync } from "../error.ts"; import { Decoder } from "./decoder.ts"; @@ -175,15 +175,23 @@ test("a failed write on the very first record still ends the track", async () => const subscriber = track.subscribe().ordered(); const producer = new Producer({ track }); - // Serializes past the group cache limit, so `appendGroup` succeeds and `writeFrame` rejects it. - const oversized = "x".repeat(Group.MAX_GROUP_CACHE_BYTES + 1); - expect(() => producer.append(oversized)).toThrow(NetError.FrameTooLarge); + // The budget check refuses anything the group would, so stub the write to stand in for any + // rejection past it: `appendGroup` succeeds and `writeFrame` throws. + const failure = new Error("write rejected"); + const write = spyOn(Group.Producer.prototype, "writeFrame").mockImplementation(() => { + throw failure; + }); + try { + expect(() => producer.append("x")).toThrow(failure); + } finally { + write.mockRestore(); + } // The consumer is handed the group that was already published, and reading it surfaces the // abort. Without ending the track that group stays open and empty, so this read hangs instead. const group = await subscriber.nextGroup(); expect(group).toBeDefined(); - await expect(group?.readFrame()).rejects.toThrow(NetError.FrameTooLarge); + await expect(group?.readFrame()).rejects.toThrow(failure); }); test("stream schema validates on both sides", () => { diff --git a/js/json/src/stream/encoder.ts b/js/json/src/stream/encoder.ts index 5aa441026d8..6aa718b1bb9 100644 --- a/js/json/src/stream/encoder.ts +++ b/js/json/src/stream/encoder.ts @@ -1,4 +1,5 @@ -import { DEFAULT_MAX_FRAME_SIZE, Encoder as Flate } from "@moq/flate"; +import { Encoder as Flate } from "@moq/flate"; +import { Group, Error as NetError } from "@moq/net"; import type * as z from "@zod/mini"; import { type Compression, isDeflate } from "../compression.ts"; @@ -65,6 +66,10 @@ export class Encoder { // Bumped for each record handed out, so a commit that arrives after the encoder has moved on can // tell that it is acknowledging a record that is no longer the outstanding one. #generation = 0; + // Frames and payload bytes committed to the current group, checked against the group budget + // before each record is encoded. Replaced on reset, so a commit that lands after one charges the + // old group rather than the new. + #budget = { frames: 0, bytes: 0 }; constructor(config: Config = {}) { this.#schema = config.schema; @@ -82,6 +87,7 @@ export class Encoder { this.#flate = this.#compress ? new Flate() : undefined; this.#desynced = false; this.#pending = false; + this.#budget = { frames: 0, bytes: 0 }; } /** @@ -90,6 +96,10 @@ export class Encoder { * The record comes back as a {@link Pending} the caller writes and then commits. Throws if a * previous compressed record was left uncommitted, since every frame after it would be * undecodable. + * + * Throws `GroupTooLarge` if the record might not fit in what is left of the group's budget + * (`MAX_GROUP_CACHE_BYTES` and `MAX_GROUP_FRAMES`), counting every record committed since the + * last {@link reset}. The refused record leaves the encoder untouched. */ encode(value: T): Pending { // An uncompressed record carries no shared state, so losing one leaves a gap in the log rather @@ -109,20 +119,31 @@ export class Encoder { const bytes = new TextEncoder().encode(text); - // Every consumer decodes with `@moq/flate`'s default output cap, so a record past it would be - // unreadable however small it compresses to. Reject it here, where the caller still learns - // why, rather than publishing something only the producer can read. - if (this.#compress && bytes.byteLength > DEFAULT_MAX_FRAME_SIZE) { - throw new Error(`record larger than the decoder's ${DEFAULT_MAX_FRAME_SIZE} byte limit`); + // Check before compressing: encoding advances the window, so a record refused afterwards + // would leave the encoder ahead of every reader. The worst case is checked rather than the + // actual size for the same reason. The budget is also below `@moq/flate`'s per-frame decode + // cap, so any record that fits is one every consumer can inflate. + const budget = this.#budget; + const bound = this.#compress ? deflateBound(bytes.byteLength) : bytes.byteLength; + if (budget.frames >= Group.MAX_GROUP_FRAMES || budget.bytes + bound > Group.MAX_GROUP_CACHE_BYTES) { + throw new NetError.GroupTooLarge(); } + const payload = this.#flate ? this.#flate.frame(bytes) : bytes; this.#pending = true; const generation = ++this.#generation; + let charged = false; return { payload, commit: () => { + // The record landed once, however often it is acknowledged. + if (!charged) { + charged = true; + budget.frames++; + budget.bytes += payload.byteLength; + } // A caller that starts the next encode before this record settles has already made the // encoder account for it. Acknowledging it now would clear the flag belonging to the newer // record, so a later loss of that one would go unnoticed. @@ -131,3 +152,11 @@ export class Encoder { }; } } + +// The largest a sync-flushed DEFLATE frame of `len` raw bytes can grow to: zlib's `deflateBound` for +// its default window and memory level, which both pako and moq-flate use. Incompressible input falls +// back to stored blocks, 5 bytes per 16 KiB; the constant covers the block headers and the flush, +// whose fixed 4-byte marker is stripped anyway. Division rather than shifts, which wrap past 2^31. +function deflateBound(len: number): number { + return len + Math.floor(len / 4096) + Math.floor(len / 16384) + Math.floor(len / 33554432) + 13; +} diff --git a/js/json/src/stream/index.ts b/js/json/src/stream/index.ts index 3cbb9a60fec..86c96b4a0a0 100644 --- a/js/json/src/stream/index.ts +++ b/js/json/src/stream/index.ts @@ -10,6 +10,13 @@ * bound the record rate throttles at the source. Interoperable on the wire with the Rust * `moq_json::stream`. * + * That one group bounds the log at `@moq/net`'s group budget: 32 MiB of payload and 8192 frames. An + * append that might not fit throws `GroupTooLarge` before it is encoded, and the log stays intact and + * writable. With compression the check counts the record's raw size plus DEFLATE's worst-case + * overhead, since the compressed size is only known once the window has moved. The budget covers the + * whole log, so once it is spent every append throws and a publisher with more to say opens a new + * track. + * * {@link Producer} and {@link Consumer} own a track: pass `{ track, ... }`. {@link Encoder} and * {@link Decoder} are the same logic without it, for when something else is already in charge of the * track; they carry the shared DEFLATE window and nothing else, since a log has no group boundaries diff --git a/js/json/src/stream/producer.ts b/js/json/src/stream/producer.ts index 346c50cb0ed..ee752bfc640 100644 --- a/js/json/src/stream/producer.ts +++ b/js/json/src/stream/producer.ts @@ -1,5 +1,5 @@ import type * as Moq from "@moq/net"; -import { Time } from "@moq/net"; +import { Error as NetError, Time } from "@moq/net"; import { type Config as CodecConfig, Encoder, type Pending } from "./encoder.ts"; @@ -25,10 +25,14 @@ export class Producer { /** * Append one record to the log. * - * A record that cannot be written ends the track: a log missing a record is not the lossless log - * this mode promises, so the failure is surfaced rather than papered over with a second group. - * The track is aborted rather than closed cleanly, so a consumer sees the failure instead of a - * log that merely looks complete. + * A record that might not fit in what is left of the group's budget throws `GroupTooLarge` + * before anything is written, leaving the log intact. The budget covers the whole log, so once it + * is spent every append throws; a publisher with more to say opens a new track. + * + * Any other record that cannot be written ends the track: a log missing a record is not the + * lossless log this mode promises, so the failure is surfaced rather than papered over with a + * second group. The track is aborted rather than closed cleanly, so a consumer sees the failure + * instead of a log that merely looks complete. * * `at` is when the value was captured, written as its frame timestamp. Defaults to now. */ @@ -40,6 +44,9 @@ export class Producer { try { record = this.#encoder.encode(value); } catch (err) { + // Refused before encoding, so nothing is missing from the log and nothing desynced. + if (err instanceof NetError.GroupTooLarge) throw err; + // A record that can't be encoded is as lost as one the group rejects: the log is missing it // either way. Nothing was published, so this only has to end the track. this.#abort(err); diff --git a/js/json/src/stream/stream.test.ts b/js/json/src/stream/stream.test.ts index 1e14c3cb2a9..a09d4ae9122 100644 --- a/js/json/src/stream/stream.test.ts +++ b/js/json/src/stream/stream.test.ts @@ -1,5 +1,5 @@ import { expect, spyOn, test } from "bun:test"; -import { Time, Track } from "@moq/net"; +import { Group, Error as NetError, Time, Track } from "@moq/net"; import { Consumer, Producer, Rolled } from "./index.ts"; type Rec = { n: number }; @@ -161,3 +161,35 @@ test("each record keeps its capture timestamp", async () => { expect((await group?.readFrame())?.timestamp.as(Time.Timescale.MILLI)).toBe(1_000); expect((await group?.readFrame())?.timestamp.as(Time.Timescale.MILLI)).toBe(2_000); }); + +// A record past the group budget is refused before anything is written, so the log carries on: the +// next record lands and decodes, which with compression proves the window never moved. +for (const compression of [false, true]) { + test(`an oversized record is refused and the log continues (compression=${compression})`, async () => { + const track = new Track.Producer("test"); + const producer = new Producer({ track, compression: compression ? "deflate" : "none" }); + producer.append({ n: 0 }); + + expect(() => producer.append("x".repeat(Group.MAX_GROUP_CACHE_BYTES))).toThrow(NetError.GroupTooLarge); + + producer.append({ n: 1 }); + producer.finish(); + expect(await drain(track.subscribe(), compression)).toEqual([0, 1]); + }); +} + +// The budget covers the whole log, so once its frames are spent every append is refused, and the log +// written so far still finishes cleanly and reads back whole. +test("a spent budget refuses every append", async () => { + const track = new Track.Producer("test"); + const producer = new Producer({ track, compression: "deflate" }); + for (let n = 0; n < Group.MAX_GROUP_FRAMES; n++) producer.append({ n }); + + expect(() => producer.append({ n: -1 })).toThrow(NetError.GroupTooLarge); + expect(() => producer.append({ n: -2 })).toThrow(NetError.GroupTooLarge); + producer.finish(); + + const records = await drain(track.subscribe(), true); + expect(records.length).toBe(Group.MAX_GROUP_FRAMES); + expect(records.at(-1)).toBe(Group.MAX_GROUP_FRAMES - 1); +}); diff --git a/js/net/src/broadcast.test.ts b/js/net/src/broadcast.test.ts index 1895c3365ed..bf9758fcbb8 100644 --- a/js/net/src/broadcast.test.ts +++ b/js/net/src/broadcast.test.ts @@ -1,6 +1,6 @@ import { expect, setSystemTime, test } from "bun:test"; import { Consumer as BroadcastConsumer, Producer as BroadcastProducer } from "./broadcast.ts"; -import { GroupTooLarge } from "./error.ts"; +import { GroupTooLarge, NotFound } from "./error.ts"; import { Producer as GroupProducer, MAX_GROUP_FRAMES } from "./group.ts"; import { Milli, Timestamp } from "./time.ts"; import type { Request as TrackRequest } from "./track.ts"; @@ -58,8 +58,10 @@ test("consumer dedupes repeat subscriptions onto one upstream request", async () test("dynamic track sequences continue across producer replacements", async () => { const broadcast = new BroadcastProducer(); + // Pull before subscribing: a broadcast nobody serves on demand answers NotFound instead. + const firstPull = wireOf(broadcast).requested(); const firstSubscriber = broadcast.track("media").subscribe(); - const firstRequest = await wireOf(broadcast).requested(); + const firstRequest = await firstPull; if (!firstRequest) throw new Error("expected first request"); const firstProducer = firstRequest.accept(); expect(firstProducer.appendGroup().sequence).toBe(0); @@ -76,8 +78,9 @@ test("dynamic track sequences continue across producer replacements", async () = expect(secondProducer.appendGroup().sequence).toBe(13); const nextGeneration = new BroadcastProducer(); + const nextPull = wireOf(nextGeneration).requested(); const nextSubscriber = nextGeneration.track("media").subscribe(); - const nextRequest = await wireOf(nextGeneration).requested(); + const nextRequest = await nextPull; if (!nextRequest) throw new Error("expected next-generation request"); expect(nextRequest.accept().appendGroup().sequence).toBe(0); @@ -90,9 +93,10 @@ test("dynamic track sequences continue across producer replacements", async () = test("concurrent dynamic producers share a sequence namespace", async () => { const broadcast = new BroadcastProducer(); + const pulled = wireOf(broadcast).requested(); const firstSubscriber = broadcast.track("media").subscribe(); const secondSubscriber = broadcast.track("media").subscribe(); - const firstRequest = await wireOf(broadcast).requested(); + const firstRequest = await pulled; const secondRequest = await wireOf(broadcast).requested(); if (!firstRequest || !secondRequest) throw new Error("expected requests"); const firstProducer = firstRequest.accept(); @@ -111,9 +115,10 @@ test("concurrent dynamic producers share a sequence namespace", async () => { test("a sibling producer's groups do not settle an aborted end", async () => { const broadcast = new BroadcastProducer(); + const pulled = wireOf(broadcast).requested(); const firstSubscriber = broadcast.track("media").subscribe(); const secondSubscriber = broadcast.track("media").subscribe(); - const firstRequest = await wireOf(broadcast).requested(); + const firstRequest = await pulled; const secondRequest = await wireOf(broadcast).requested(); if (!firstRequest || !secondRequest) throw new Error("expected requests"); const firstProducer = firstRequest.accept(); @@ -137,9 +142,10 @@ test("a sibling producer's groups do not settle an aborted end", async () => { test("a clean close ends at the track's own last group, not a sibling's", async () => { const broadcast = new BroadcastProducer(); + const pulled = wireOf(broadcast).requested(); const firstSubscriber = broadcast.track("media").subscribe(); const secondSubscriber = broadcast.track("media").subscribe(); - const firstRequest = await wireOf(broadcast).requested(); + const firstRequest = await pulled; const secondRequest = await wireOf(broadcast).requested(); if (!firstRequest || !secondRequest) throw new Error("expected requests"); const firstProducer = firstRequest.accept(); @@ -161,9 +167,10 @@ test("a clean close ends at the track's own last group, not a sibling's", async test("finishAt accepts an end below a sibling's groups", async () => { const broadcast = new BroadcastProducer(); + const pulled = wireOf(broadcast).requested(); const firstSubscriber = broadcast.track("media").subscribe(); const secondSubscriber = broadcast.track("media").subscribe(); - const firstRequest = await wireOf(broadcast).requested(); + const firstRequest = await pulled; const secondRequest = await wireOf(broadcast).requested(); if (!firstRequest || !secondRequest) throw new Error("expected requests"); const firstProducer = firstRequest.accept(); @@ -185,8 +192,9 @@ test("finishAt accepts an end below a sibling's groups", async () => { test("closing a broadcast rejects a dequeued request", async () => { const broadcast = new BroadcastProducer(); + const pulled = wireOf(broadcast).requested(); const subscriber = broadcast.track("media").subscribe(); - const request = await wireOf(broadcast).requested(); + const request = await pulled; if (!request) throw new Error("expected request"); broadcast.close(); await expect(subscriber.info()).rejects.toThrow("track closed before info was known"); @@ -418,19 +426,42 @@ test("insertTrack rejects a duplicate live name", () => { expect(() => broadcast.insertTrack(new TrackProducer("dup").accept())).toThrow(); }); -test("a closed track is evicted and re-subscribing falls through to a request", async () => { +test("a finished track is still served from its cache", async () => { const broadcast = new BroadcastProducer(); + const track = broadcast.createTrack("track1"); + track.writeString("last"); + track.close(); + + // Like Rust, finishing keeps the track: a late subscriber reads the cache, then the clean end. + const late = broadcast + .consume() + .track("track1") + .subscribe({ maxAge: Milli(5000) }) + .ordered(); + expect(await late.readString()).toBe("last"); + expect(await late.nextGroup()).toBeUndefined(); + expect(await broadcast.track("track1").info()).toBeDefined(); + expect(await pendingRequest(broadcast)).toBeUndefined(); +}); - const track1 = broadcast.createTrack("track1"); - track1.close(); +test("an aborted track is gone, so a subscribe with no handler answers NotFound", async () => { + const broadcast = new BroadcastProducer(); + broadcast.createTrack("track1").close(new Error("boom")); - // The stale entry is gone, so subscribe creates an on-demand request instead. - const pending = broadcast.track("track1").subscribe(); - expect(pending).toBeDefined(); + // Nothing serves requests on demand, so this must fail rather than wait forever. + const subscriber = broadcast.consume().track("track1").subscribe(); + await expect(subscriber.info()).rejects.toBeInstanceOf(NotFound); + await expect(subscriber.recvGroup()).rejects.toBeInstanceOf(NotFound); + await expect(broadcast.track("track1").info()).rejects.toBeInstanceOf(NotFound); +}); + +test("an aborted track falls through to a request when a handler is serving", async () => { + const broadcast = new BroadcastProducer(); + const pulled = wireOf(broadcast).requested(); + broadcast.createTrack("track1").close(new Error("boom")); - // That on-demand request is now waiting to be answered. - const request = await wireOf(broadcast).requested(); - expect(request?.name).toBe("track1"); + broadcast.track("track1").subscribe(); + expect((await pulled)?.name).toBe("track1"); }); test("removeTrack drops the static entry", async () => { @@ -440,12 +471,11 @@ test("removeTrack drops the static entry", async () => { kept.track("track1").subscribe(); expect(await pendingRequest(kept)).toBeUndefined(); - // With the entry removed, subscribing falls through to an on-demand request. + // With the entry removed and nothing serving on demand, the track is not found. const removed = new BroadcastProducer(); removed.createTrack("track1"); removed.removeTrack("track1"); - removed.track("track1").subscribe(); - expect((await pendingRequest(removed))?.name).toBe("track1"); + await expect(removed.track("track1").subscribe().info()).rejects.toBeInstanceOf(NotFound); }); test("close rejects a still-pending track request so its subscriber unblocks", async () => { @@ -513,8 +543,9 @@ test("broadcast demand watches static and pending tracks rather than broadcast h const first = video.subscribe(); await Promise.resolve(); expect(demand.used.peek()).toBe(true); + const pulled = wireOf(broadcast).requested(); const second = consumer.track("audio").subscribe(); - const request = await wireOf(broadcast).requested(); + const request = await pulled; if (!request) throw new Error("expected request"); const requested = request.demand(); expect(requested.used.peek()).toBe(true); diff --git a/js/net/src/broadcast.ts b/js/net/src/broadcast.ts index 99efcd09c33..1d51736fe34 100644 --- a/js/net/src/broadcast.ts +++ b/js/net/src/broadcast.ts @@ -29,7 +29,15 @@ class BroadcastState { requested = new Signal([]); pending = new Set(); closed = new Once(); + // The tracks the application inserted. A finished one stays and keeps serving its cache; only an + // abort or removeTrack drops it, the way only a dropped producer leaves a Rust broadcast. tracks = new Map(); + // Upstream subscriptions a consumer opened, shared by repeat subscribes until they close. + upstream = new Map(); + // Whether something answers on-demand track requests: a wire layer's consumed broadcast, or a + // publisher that has started pulling them. The counterpart of a live Rust `broadcast::Dynamic`; + // without one, a track nobody publishes is `NotFound` rather than a request nobody will answer. + served = false; sequences = new Map(); // Live consumer handles sharing this state (see {@link Consumer.clone}). The broadcast // closes once the last one closes, so a shared consumer can be handed to several callers. @@ -78,6 +86,20 @@ function dequeueRequest(state: BroadcastState): track.Request | undefined { return requested.pop(); } +// The next on-demand track request, or undefined once the broadcast closes. +async function requested(state: BroadcastState): Promise { + // Pulling requests is what makes a broadcast serve tracks on demand. + state.served = true; + for (;;) { + const request = dequeueRequest(state); + if (request) return request; + + if (state.closed.peek() !== undefined) return undefined; + + await Signal.race(state.requested, state.closed); + } +} + // Close the broadcast and reject any requests still pending in the queue, so a // subscriber blocked on the track's info() or group reads is unblocked rather // than left waiting on a producer that will never be served. @@ -94,13 +116,30 @@ function closeState(state: BroadcastState) { }); } +// The producer already serving `name`, evicting entries that can no longer serve it. +function lookup(state: BroadcastState, name: string): track.Producer | undefined { + const inserted = state.tracks.get(name); + if (inserted) { + if (!(inserted.closed.peek() instanceof Error)) return inserted; + state.tracks.delete(name); + } + + const upstream = state.upstream.get(name); + if (upstream) { + if (upstream.closed.peek() === undefined) return upstream; + state.upstream.delete(name); + } + + return undefined; +} + // `register` is set on the subscribing (consumer) side: the fresh producer is cached in -// `state.tracks` so repeat subscriptions to the same track fan out from one upstream subscription +// `state.upstream` so repeat subscriptions to the same track fan out from one upstream subscription // instead of opening a new one, mirroring the Rust `broadcast::Consumer::track` weak-dedup. The // consumer wire watches the producer's demand ({@link track.Demand.used}) and tears the upstream // down once its last subscriber leaves, closing the producer, which evicts the cache entry below. -// The publishing side leaves `register` false: `state.tracks` there holds only the tracks the app -// inserted, and a dynamic serve stays one request per peer subscription. +// The publishing side leaves `register` false, so a dynamic serve stays one request per peer +// subscription. function subscribe( state: BroadcastState, name: string, @@ -111,22 +150,26 @@ function subscribe( throw new Error("broadcast is closed"); } - const existing = state.tracks.get(name); - if (existing) { - if (existing.closed.peek() === undefined) return existing.subscribe(options); - state.tracks.delete(name); - } + const existing = lookup(state, name); + if (existing) return existing.subscribe(options); const producer = new track.Producer(name); + if (!state.served) { + // Answer through the subscriber rather than throwing, so a peer's subscribe is refused with + // the code instead of an unhandled error. + producer.close(new NotFound(`track ${name}`)); + return producer.subscribe(options); + } + watchDemand(state, producer); const subscriber = producer.subscribe(options); if (register) { - state.tracks.set(name, producer); + state.upstream.set(name, producer); // Drop the cache entry once the upstream closes (the wire tears it down when its last // subscriber leaves), so a later subscribe re-opens it. void producer.closed.then(() => { - if (state.tracks.get(name) === producer) state.tracks.delete(name); + if (state.upstream.get(name) === producer) state.upstream.delete(name); }); } @@ -138,14 +181,13 @@ function subscribe( } async function resolveTrackInfo(state: BroadcastState, name: string): Promise { - const existing = state.tracks.get(name); - if (existing && existing.closed.peek() === undefined) { - return existing.info(); - } + const existing = lookup(state, name); + if (existing) return existing.info(); if (state.closed.peek() !== undefined) { return Promise.reject(new Error("broadcast is closed")); } + if (!state.served) return Promise.reject(new NotFound(`track ${name}`)); const producer = new track.Producer(name); watchDemand(state, producer); @@ -266,17 +308,6 @@ export class Producer { return makeConsumer({ state: this.#state, path: this.#path }); } - async #requested(): Promise { - for (;;) { - const request = dequeueRequest(this.#state); - if (request) return request; - - if (this.#state.closed.peek() !== undefined) return undefined; - - await Signal.race(this.#state.requested, this.#state.closed); - } - } - /** Insert a track that is served directly, without an on-demand request round-trip. */ insertTrack(track: track.Producer): void { if (this.#state.closed.peek() !== undefined) { @@ -291,8 +322,9 @@ export class Producer { watchDemand(this.#state, track); this.#state.tracks.set(track.name, track); - void track.closed.then(() => { - if (this.#state.tracks.get(track.name) === track) { + // A finished track keeps serving its cache, so only an abort evicts it. + void track.closed.then((closed) => { + if (closed instanceof Error && this.#state.tracks.get(track.name) === track) { this.#state.tracks.delete(track.name); } }); @@ -305,7 +337,7 @@ export class Producer { return producer; } - /** Remove a statically inserted track by name. */ + /** Remove a statically inserted track by name, including a finished one still serving its cache. */ removeTrack(name: string): void { this.#state.tracks.delete(name); } @@ -320,7 +352,7 @@ export class Producer { subscribe: (name, options) => subscribe(this.#state, name, options, register), resolveTrackInfo: (name) => resolveTrackInfo(this.#state, name), fetchGroup: (name, sequence, options) => fetchGroup(this.#state, name, sequence, options), - requested: () => this.#requested(), + requested: () => requested(this.#state), }; } @@ -383,14 +415,20 @@ export class Consumer { protected constructor(shared?: never); protected constructor(shared?: Shared) { - this.#state = shared?.state ?? new BroadcastState(); this.#path = shared?.path ?? Path.empty(); + if (shared) { + this.#state = shared.state; + } else { + // A standalone consumer is a wire layer's, which serves every track on demand. + this.#state = new BroadcastState(); + this.#state.served = true; + } this.#state.consumers++; registerWire(this, { subscribe: (name, options) => subscribe(this.#state, name, options, true), resolveTrackInfo: (name) => resolveTrackInfo(this.#state, name), fetchGroup: (name, sequence, options) => fetchGroup(this.#state, name, sequence, options), - requested: () => this.#requested(), + requested: () => requested(this.#state), }); } @@ -448,17 +486,6 @@ export class Consumer { return trackOf(name, this); } - async #requested(): Promise { - for (;;) { - const request = dequeueRequest(this.#state); - if (request) return request; - - if (this.#state.closed.peek() !== undefined) return undefined; - - await Signal.race(this.#state.requested, this.#state.closed); - } - } - /** * Release this handle. The broadcast is closed once this was the last live handle; * while other {@link clone}s remain open it stays live. diff --git a/quest/m1/README.md b/quest/m1/README.md index 14a665f59c1..d8b284de32a 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -61,7 +61,6 @@ blocks. The quests that gated m0 lines moved under them. - [Untimed lite-07](/quest/m1/lite-untimed.md) - lite-07 carries an untimed track in both languages; lite-05/06 write send time - [Finalize moq-lite-07](/quest/m1/lite07-finalize.md) - when the maintainer cuts it, lite-07 negotiates as `moq-lite-07` and the next release ships it - [Late lower groups](/quest/m1/lite-late-lower-group.md) - a moq-lite subscriber with a floor receives a group created below the first served one, as moq-transport does -- [JSON stream budget](/quest/m1/json-stream-budget.md) - an oversized JSON stream record is refused without ending the log, and a JS subscribe to a gone track answers NotFound - [A watch and publish release ships assets()](/quest/m1/assets-release.md) - the release that lets the sites host the worklets - [Dogfood hosted worklets](/quest/m1/dogfood-assets.md) - moq.dev and the moq.pro dashboard host the worklets and call `assets()` after the release - [More tests under load](/quest/m1/test-flakes-2/README.md) - the second round of load-only failures, one quest per flake, fixed at the cause diff --git a/quest/m1/json-stream-budget.md b/quest/m1/json-stream-budget.md deleted file mode 100644 index 9d45bfaf6e4..00000000000 --- a/quest/m1/json-stream-budget.md +++ /dev/null @@ -1,40 +0,0 @@ -# [S] A JSON stream refuses an oversized record without ending - -## Goal - -A `@moq/json` or `moq-json` Stream append that cannot fit the group budget -(32 MiB or 8192 frames) throws `GroupTooLarge` and leaves the log intact, -compressed or not. A JS subscriber to a track that is gone gets `NotFound`, as -in Rust, instead of waiting forever. - -## Plan - -Today `js/net/src/group.ts` wipes and closes the group on overflow and -`js/json/src/stream/producer.ts` aborts the track, which ends the log for -every reader. Ending the log is deliberate for a failed write -(`rs/moq-json/src/stream/mod.rs`), but a refused record is not a hole. - -Decided (2026-10-04): - -- Before encoding, check the record's raw size plus deflate's worst-case - overhead against the remaining budget. Encoding advances the DEFLATE window, - so a check after encoding would desync readers. The budget is tracked - inside @moq/json and moq-json, not exposed by moq-net. A failure past the - check still aborts the track. -- The budget covers the whole log, so once it is spent every append throws. - The check spares the log from one oversized record; it does not extend a - full one, which still needs a new track. -- Track lifetime, as Rust already behaves: a finished track stays cached and - new subscribers get it from the cache; only a dropped or aborted producer - removes it, after which a subscribe with no handler alive answers - `NotFound`. `js/net/src/broadcast.ts` queues an unserved request instead; - make it match, and check that JS keeps a finished track servable. -- Document the budget in `doc/lib/js/json.md` and the Rust crate docs. - -Tests: an oversized record throws and the next record is readable, in both -compression modes; a JS subscribe to an aborted local track errors with -`NotFound`; a finished track is still served. - -## Closes - -- [#4771](https://github.com/moq-dev/moq/issues/4771) - close this issue when the quest finishes diff --git a/rs/moq-json/src/stream/encoder.rs b/rs/moq-json/src/stream/encoder.rs index a1e6d94ec0f..faab346d3d8 100644 --- a/rs/moq-json/src/stream/encoder.rs +++ b/rs/moq-json/src/stream/encoder.rs @@ -51,6 +51,8 @@ impl Pending<'_, T> { /// Only call this once the write has actually succeeded. pub fn commit(mut self) { self.committed = true; + self.encoder.frames += 1; + self.encoder.bytes += self.payload.len() as u64; } } @@ -80,6 +82,11 @@ pub struct Encoder { /// consumer for the rest of the group, so encoding stops until the caller rolls a new one. desynced: bool, + /// Frames and payload bytes committed to the current group, checked against moq-net's group + /// budget before each record is encoded. + frames: usize, + bytes: u64, + _marker: PhantomData, } @@ -90,6 +97,8 @@ impl Encoder { flate: config.compression.is_deflate().then(moq_flate::Encoder::new), compression: config.compression.is_deflate(), desynced: false, + frames: 0, + bytes: 0, _marker: PhantomData, } } @@ -101,6 +110,8 @@ impl Encoder { pub fn reset(&mut self) { self.flate = self.compression.then(moq_flate::Encoder::new); self.desynced = false; + self.frames = 0; + self.bytes = 0; } /// Mark the window as ahead of the consumer, after a record that was never written. @@ -118,6 +129,11 @@ impl Encoder { /// The record comes back as a [`Pending`] the caller writes and then /// [`commit`](Pending::commit)s. Errors with [`Error::Desync`] if a previous compressed record /// was left uncommitted, since every frame after it would be undecodable. + /// + /// Errors with [`moq_net::Error::GroupTooLarge`] if the record might not fit in what is left of + /// the group's budget ([`moq_net::group::MAX_CACHE_BYTES`] and + /// [`moq_net::group::MAX_GROUP_FRAMES`]), counting every record committed since the last + /// [`reset`](Self::reset). The refused record leaves the encoder untouched. pub fn encode(&mut self, value: &T) -> Result> { if self.desynced { return Err(Error::Desync); @@ -125,12 +141,18 @@ impl Encoder { let bytes = serde_json::to_vec(value)?; - // Every consumer decodes with moq-flate's default output cap, so a record past it would be - // unreadable however small it compresses to. Reject it here, where the caller still learns - // why, rather than publishing something only the producer can read. - if self.compression && bytes.len() as u64 > moq_flate::DEFAULT_MAX_FRAME_SIZE { - return Err(moq_flate::Error::TooLarge(moq_flate::DEFAULT_MAX_FRAME_SIZE).into()); + // Check before compressing: encoding advances the window, so a record refused afterwards + // would leave the encoder ahead of every reader. The worst case is checked rather than the + // actual size for the same reason. The budget is also below moq-flate's per-frame decode cap, + // so any record that fits is one every consumer can inflate. + let size = bytes.len() as u64; + let bound = if self.compression { deflate_bound(size) } else { size }; + if self.frames >= moq_net::group::MAX_GROUP_FRAMES + || self.bytes.saturating_add(bound) > moq_net::group::MAX_CACHE_BYTES + { + return Err(moq_net::Error::GroupTooLarge.into()); } + let payload = match self.flate.as_mut() { Some(flate) => flate.frame(&bytes), None => Bytes::from(bytes), @@ -143,3 +165,46 @@ impl Encoder { }) } } + +/// The largest a sync-flushed DEFLATE frame of `len` raw bytes can grow to. +/// +/// zlib's `deflateBound` for its default window and memory level, which both moq-flate and the +/// browser's pako use: incompressible input falls back to stored blocks, 5 bytes per 16 KiB. The +/// constant covers the block headers and the flush, whose fixed 4-byte marker is stripped anyway. +fn deflate_bound(len: u64) -> u64 { + len + (len >> 12) + (len >> 14) + (len >> 25) + 13 +} + +#[cfg(test)] +mod test { + use super::*; + + /// The bound holds for incompressible input, the worst case, at sizes straddling the 16 KiB + /// block boundary, and on a window already primed by earlier frames. + #[test] + fn deflate_bound_covers_incompressible_frames() { + // xorshift: incompressible enough to force stored blocks, and deterministic. + let mut state = 0x9e37_79b9_7f4a_7c15u64; + let mut noise = |len: usize| { + (0..len) + .map(|_| { + state ^= state << 13; + state ^= state >> 7; + state ^= state << 17; + state as u8 + }) + .collect::>() + }; + + let mut flate = moq_flate::Encoder::new(); + for len in [1, 2, 100, 16_383, 16_384, 16_385, 65_535, 65_536, 1 << 20, 3 << 20] { + let payload = flate.frame(&noise(len)); + assert!( + payload.len() as u64 <= deflate_bound(len as u64), + "{len} raw bytes deflated to {}, past the bound {}", + payload.len(), + deflate_bound(len as u64) + ); + } + } +} diff --git a/rs/moq-json/src/stream/mod.rs b/rs/moq-json/src/stream/mod.rs index 5c2e217fa3a..31ab41105ce 100644 --- a/rs/moq-json/src/stream/mod.rs +++ b/rs/moq-json/src/stream/mod.rs @@ -17,12 +17,21 @@ //! second group: a log missing a record is not lossless, and a gap dressed up as a complete log is //! worse than a visible failure. A publisher with more to say opens a new track. //! -//! That single group is what bounds the log's history. moq-net caps a group's cached bytes and -//! frame count, and a consumer always starts at frame 0, so a write that would outgrow the -//! budget aborts the group with [`moq_net::Error::GroupTooLarge`] rather than dropping a prefix -//! some readers missed. (With compression the retained suffix would be undecodable anyway, -//! since its DEFLATE window depends on the dropped prefix.) The live stream is therefore -//! bounded history by design; deep history is served from a recording. +//! # Budget +//! +//! That single group is what bounds the log. moq-net caps a group at +//! [`MAX_CACHE_BYTES`](moq_net::group::MAX_CACHE_BYTES) (32 MiB) of payload and +//! [`MAX_GROUP_FRAMES`](moq_net::group::MAX_GROUP_FRAMES) (8192) frames, and a consumer always +//! starts at frame 0, so the cap is never met by dropping a prefix some readers missed. (With +//! compression the retained suffix would be undecodable anyway, since its DEFLATE window depends +//! on the dropped prefix.) +//! +//! Instead an append that might not fit is refused with [`moq_net::Error::GroupTooLarge`] before +//! it is encoded, and the log stays intact and writable. With compression the check counts the +//! record's raw size plus DEFLATE's worst-case overhead, since the compressed size is only known +//! once the window has moved. The budget covers the whole log rather than a single record, so once +//! it is spent every append is refused: the live stream is bounded history by design, a publisher +//! with more to say opens a new track, and deep history is served from a recording. //! //! # Choosing a layer //! @@ -349,6 +358,69 @@ mod test { )); } + fn config(compression: bool) -> Config { + if compression { compressed() } else { Config::default() } + } + + fn refused(result: crate::Result) -> bool { + matches!(result, Err(crate::Error::Net(moq_net::Error::GroupTooLarge))) + } + + /// A record past the group budget is refused before anything is written, so the log carries on: + /// the next record lands and decodes, which with compression proves the window never moved. + #[test] + fn an_oversized_record_is_refused_and_the_log_continues() { + for compression in [false, true] { + let (mut producer, track) = producer(config(compression)); + producer.append(&json!({ "n": 0 })).unwrap(); + + let oversized = Value::String("x".repeat(moq_net::group::MAX_CACHE_BYTES as usize)); + assert!(refused(producer.append(&oversized)), "compression={compression}"); + + producer.append(&json!({ "n": 1 })).unwrap(); + producer.finish().unwrap(); + + assert_eq!( + drain(consume(track, compression)), + vec![json!({ "n": 0 }), json!({ "n": 1 })], + "compression={compression}" + ); + } + } + + /// The budget covers the whole log, so once its frames are spent every append is refused, and + /// the log written so far still finishes cleanly and reads back whole. + #[test] + fn a_spent_budget_refuses_every_append() { + for compression in [false, true] { + let (mut producer, track) = producer(config(compression)); + for n in 0..moq_net::group::MAX_GROUP_FRAMES { + producer.append(&json!({ "n": n })).unwrap(); + } + + assert!( + refused(producer.append(&json!({ "n": -1 }))), + "compression={compression}" + ); + assert!( + refused(producer.append(&json!({ "n": -2 }))), + "compression={compression}" + ); + producer.finish().unwrap(); + + let records = drain(consume(track, compression)); + assert_eq!( + records.len(), + moq_net::group::MAX_GROUP_FRAMES, + "compression={compression}" + ); + assert_eq!( + records.last(), + Some(&json!({ "n": moq_net::group::MAX_GROUP_FRAMES - 1 })) + ); + } + } + #[test] fn embedded_newlines_survive() { // Each record is its own frame (one JSON object), and JSON escapes control characters, so a diff --git a/rs/moq-json/src/stream/producer.rs b/rs/moq-json/src/stream/producer.rs index 6e9626abd6b..aea5e2012bf 100644 --- a/rs/moq-json/src/stream/producer.rs +++ b/rs/moq-json/src/stream/producer.rs @@ -67,10 +67,15 @@ impl Producer { /// Append one record to the log. /// - /// Any failure ends the track. A log missing a record is not the lossless log a stream promises, - /// and that holds whether the group rejected the record or it never encoded at all, so the - /// failure is surfaced rather than papered over with a second group. The track is aborted rather - /// than closed cleanly, so a consumer sees the failure instead of a log that merely looks + /// A record that might not fit in what is left of the group's budget is refused with + /// [`moq_net::Error::GroupTooLarge`] before anything is written, leaving the log intact. The + /// budget covers the whole log, so once it is spent every append is refused; a publisher with + /// more to say opens a new track. + /// + /// Any other failure ends the track. A log missing a record is not the lossless log a stream + /// promises, and that holds whether the group rejected the record or it never encoded at all, so + /// the failure is surfaced rather than papered over with a second group. The track is aborted + /// rather than closed cleanly, so a consumer sees the failure instead of a log that merely looks /// complete. Every later append fails on the ended track. /// /// Returns the encoded size of the frame written. @@ -107,6 +112,8 @@ impl Inner { // `record` guards the window: any failure below drops it uncommitted. let record = match encoder.encode(payload.value) { Ok(record) => record, + // Refused before encoding, so nothing is missing from the log and nothing desynced. + Err(err @ crate::Error::Net(moq_net::Error::GroupTooLarge)) => return Err(err), Err(err) => { // A record that can't be encoded is as lost as one the group rejects: the log is // missing it either way, and carrying on would present that gap as a complete log. diff --git a/rs/moq-mux/src/json.rs b/rs/moq-mux/src/json.rs index 09f7240ae6b..6709a0a1c5b 100644 --- a/rs/moq-mux/src/json.rs +++ b/rs/moq-mux/src/json.rs @@ -303,7 +303,8 @@ impl Stream { /// Append one record to the log. /// /// A record that cannot be written ends the track (see [`moq_json::stream::Producer::append`]) - /// and retires the catalog entry with it. A catalog error publishing the measured bitrate is + /// and retires the catalog entry with it. A record refused with + /// [`moq_net::Error::GroupTooLarge`] leaves both intact, since nothing was written. A catalog error publishing the measured bitrate is /// returned after the record was written, so the track stays open and a retry would duplicate it. pub fn append<'a>(&mut self, value: impl Into>) -> crate::Result<()> where @@ -316,6 +317,8 @@ impl Stream { }; let size = match self.inner.append(value) { Ok(size) => size, + // Refused before anything was written, so the log and its entry carry on. + Err(err @ moq_json::Error::Net(moq_net::Error::GroupTooLarge)) => return Err(err.into()), Err(err) => { // The inner producer has already ended the track. Dropping the listing retires the // catalog entry: waiting for the handle to drop would keep advertising a track that @@ -810,6 +813,32 @@ mod test { assert!(matches!(track.poll_recv_group(&waiter), Poll::Ready(Err(_)))); } + /// A record past the group budget is refused before anything is written, so the log stays + /// advertised and the next record still lands. + #[test] + fn an_oversized_record_keeps_the_track_and_the_entry() { + let (mut broadcast, catalog) = catalog(); + let mut chat = catalog + .json_stream::(track(&mut broadcast, "chat"), Config::default()) + .unwrap(); + let track = chat.consume(); + + let oversized = Value::String("x".repeat(moq_net::group::MAX_CACHE_BYTES as usize)); + assert!(matches!( + chat.append(&oversized), + Err(crate::Error::Json(moq_json::Error::Net(moq_net::Error::GroupTooLarge))) + )); + assert!(catalog.snapshot().json.tracks.contains_key("chat")); + + chat.append(&json!({ "n": 1 })).unwrap(); + let entry = entry(&catalog, "chat"); + chat.finish().unwrap(); + assert_eq!( + drain(Consumer::from_track(track, &entry).unwrap()), + vec![json!({ "n": 1 })] + ); + } + /// A consumer that can't tell a log from a latest-value document would silently drop records, /// so an unreadable entry is an error rather than a guess. #[test] From a0ca767c9fc0ee8368d7f6a65c43b310c5293a4e Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 6 Oct 2026 01:00:59 -0700 Subject: [PATCH 3/8] docs(moq-mux): rewrap json::Stream::append doc Co-Authored-By: Claude Opus 5.5 --- rs/moq-mux/src/json.rs | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/rs/moq-mux/src/json.rs b/rs/moq-mux/src/json.rs index 6709a0a1c5b..506071ea6a3 100644 --- a/rs/moq-mux/src/json.rs +++ b/rs/moq-mux/src/json.rs @@ -304,8 +304,9 @@ impl Stream { /// /// A record that cannot be written ends the track (see [`moq_json::stream::Producer::append`]) /// and retires the catalog entry with it. A record refused with - /// [`moq_net::Error::GroupTooLarge`] leaves both intact, since nothing was written. A catalog error publishing the measured bitrate is - /// returned after the record was written, so the track stays open and a retry would duplicate it. + /// [`moq_net::Error::GroupTooLarge`] leaves both intact, since nothing was written. A catalog + /// error publishing the measured bitrate is returned after the record was written, so the track + /// stays open and a retry would duplicate it. pub fn append<'a>(&mut self, value: impl Into>) -> crate::Result<()> where T: 'a, From c9ad1f1c470b34ad5495985c52763d06b1d84042 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 6 Oct 2026 01:34:47 -0700 Subject: [PATCH 4/8] test(json): check the DEFLATE bound against pako, cover a spent budget uncompressed Also note on the JS on-demand latch that a publisher pulls before it publishes. Co-Authored-By: Claude Opus 5.5 --- js/json/src/stream/codec.test.ts | 26 +++++++++++++++++++++++++- js/json/src/stream/encoder.ts | 2 +- js/json/src/stream/stream.test.ts | 24 +++++++++++++----------- js/net/src/broadcast.ts | 5 ++++- 4 files changed, 43 insertions(+), 14 deletions(-) diff --git a/js/json/src/stream/codec.test.ts b/js/json/src/stream/codec.test.ts index 07c4a2b3fc7..b3304271bc5 100644 --- a/js/json/src/stream/codec.test.ts +++ b/js/json/src/stream/codec.test.ts @@ -1,9 +1,10 @@ import { expect, spyOn, test } from "bun:test"; +import { Encoder as Flate } from "@moq/flate"; import { Group, Track } from "@moq/net"; import * as z from "@zod/mini"; import { Desync } from "../error.ts"; import { Decoder } from "./decoder.ts"; -import { Encoder } from "./encoder.ts"; +import { deflateBound, Encoder } from "./encoder.ts"; import { Producer } from "./producer.ts"; type Rec = { n: number }; @@ -208,3 +209,26 @@ test("a lost compressed stream frame has a typed error", () => { encoder.encode({ n: 1 }); expect(() => encoder.encode({ n: 2 })).toThrow(Desync); }); + +// The bound holds for incompressible input, the worst case, at sizes straddling the 16 KiB block +// boundary, and on a window already primed by earlier frames. Twin of the Rust test, since pako is a +// separate implementation from the zlib the Rust side checks. +test("deflate bound covers incompressible frames", () => { + // xorshift: incompressible enough to force stored blocks, and deterministic. + let state = 0x9e3779b9; + const noise = (len: number) => { + const out = new Uint8Array(len); + for (let i = 0; i < len; i++) { + state ^= state << 13; + state ^= state >>> 17; + state ^= state << 5; + out[i] = state & 0xff; + } + return out; + }; + + const flate = new Flate(); + for (const len of [1, 2, 100, 16_383, 16_384, 16_385, 65_535, 65_536, 1 << 20, 3 << 20]) { + expect(flate.frame(noise(len)).byteLength).toBeLessThanOrEqual(deflateBound(len)); + } +}); diff --git a/js/json/src/stream/encoder.ts b/js/json/src/stream/encoder.ts index 6aa718b1bb9..a921f09e464 100644 --- a/js/json/src/stream/encoder.ts +++ b/js/json/src/stream/encoder.ts @@ -157,6 +157,6 @@ export class Encoder { // its default window and memory level, which both pako and moq-flate use. Incompressible input falls // back to stored blocks, 5 bytes per 16 KiB; the constant covers the block headers and the flush, // whose fixed 4-byte marker is stripped anyway. Division rather than shifts, which wrap past 2^31. -function deflateBound(len: number): number { +export function deflateBound(len: number): number { return len + Math.floor(len / 4096) + Math.floor(len / 16384) + Math.floor(len / 33554432) + 13; } diff --git a/js/json/src/stream/stream.test.ts b/js/json/src/stream/stream.test.ts index a09d4ae9122..1315075e064 100644 --- a/js/json/src/stream/stream.test.ts +++ b/js/json/src/stream/stream.test.ts @@ -180,16 +180,18 @@ for (const compression of [false, true]) { // The budget covers the whole log, so once its frames are spent every append is refused, and the log // written so far still finishes cleanly and reads back whole. -test("a spent budget refuses every append", async () => { - const track = new Track.Producer("test"); - const producer = new Producer({ track, compression: "deflate" }); - for (let n = 0; n < Group.MAX_GROUP_FRAMES; n++) producer.append({ n }); +for (const compression of [false, true]) { + test(`a spent budget refuses every append (compression=${compression})`, async () => { + const track = new Track.Producer("test"); + const producer = new Producer({ track, compression: compression ? "deflate" : "none" }); + for (let n = 0; n < Group.MAX_GROUP_FRAMES; n++) producer.append({ n }); - expect(() => producer.append({ n: -1 })).toThrow(NetError.GroupTooLarge); - expect(() => producer.append({ n: -2 })).toThrow(NetError.GroupTooLarge); - producer.finish(); + expect(() => producer.append({ n: -1 })).toThrow(NetError.GroupTooLarge); + expect(() => producer.append({ n: -2 })).toThrow(NetError.GroupTooLarge); + producer.finish(); - const records = await drain(track.subscribe(), true); - expect(records.length).toBe(Group.MAX_GROUP_FRAMES); - expect(records.at(-1)).toBe(Group.MAX_GROUP_FRAMES - 1); -}); + const records = await drain(track.subscribe(), compression); + expect(records.length).toBe(Group.MAX_GROUP_FRAMES); + expect(records.at(-1)).toBe(Group.MAX_GROUP_FRAMES - 1); + }); +} diff --git a/js/net/src/broadcast.ts b/js/net/src/broadcast.ts index 1d51736fe34..082b1f1416c 100644 --- a/js/net/src/broadcast.ts +++ b/js/net/src/broadcast.ts @@ -88,7 +88,10 @@ function dequeueRequest(state: BroadcastState): track.Request | undefined { // The next on-demand track request, or undefined once the broadcast closes. async function requested(state: BroadcastState): Promise { - // Pulling requests is what makes a broadcast serve tracks on demand. + // Pulling requests is what makes a broadcast serve tracks on demand, and it latches for the + // broadcast's lifetime since JS has no drop to mark the handler gone. A subscribe before the first + // pull is answered NotFound, so an on-demand publisher starts pulling before it publishes and keeps + // pulling until the broadcast closes. state.served = true; for (;;) { const request = dequeueRequest(state); From f802ca979c8a0b35f3bb9e5cc4816435e256b6d9 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 6 Oct 2026 23:06:50 -0700 Subject: [PATCH 5/8] quest: remove completed JSON stream prerequisite Co-Authored-By: GPT-6 --- quest/m1/flate-stream-budget.md | 4 ---- 1 file changed, 4 deletions(-) diff --git a/quest/m1/flate-stream-budget.md b/quest/m1/flate-stream-budget.md index 8a946a9c2c3..84b23dec60b 100644 --- a/quest/m1/flate-stream-budget.md +++ b/quest/m1/flate-stream-budget.md @@ -27,7 +27,3 @@ prior records readable and allows a later fitting append; a failed write after encoding still aborts, as JSON does. Mirror #4911's tests in both compression modes, including the decoder-size refusal, and document the budget and refusal behavior in the flate library docs. - -## Required - -- [JSON stream budget](/quest/m1/json-stream-budget.md) - #4911 provides the preflight budget model and DEFLATE bound From b0a55b829b82529e6d91f6e822a2b13cf87dca4f Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Wed, 7 Oct 2026 00:01:31 -0700 Subject: [PATCH 6/8] docs: qualify missing track refusal by handler state Co-Authored-By: GPT-6 --- doc/lib/js/net.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/lib/js/net.md b/doc/lib/js/net.md index 117d39b24f0..813095d9f2c 100644 --- a/doc/lib/js/net.md +++ b/doc/lib/js/net.md @@ -54,7 +54,7 @@ for (;;) { - **Discovery** by any pattern scope (`origin.announced(scope)`, such as `room/*/chat`; default everything). A route event's `kind` says whether the route started, updated, or ended; its `prefix` is the covered prefix relative to the origin, and `captures` reports what the scope's wildcards matched when the prefix pins them. The consumer is an async iterable. `origin.broadcasts(scope)` is a live `Getter>` of the same covered prefixes for UIs that need the current set. A borrowed `Connection.origin` also exposes `dynamic(prefix, route)` for serving paths on demand. - **Publisher retention** is optional `Track.Info.maxAge`, measured against media timestamps: omission sets no limit, while zero serves only the live edge. It clamps every subscriber's max age, and stalled media does not age out merely because wall time passes. Separately, cached groups nobody writes for 30 seconds are reclaimed, except a live track's newest group, which stays replayable until the track closes. - **Subscriptions** carry a priority, a `Time.Milli` max age measured against media timestamps, and optional `groups` bounds. Groups arrive out of order and are read frame by frame, with `Error.TooFarBehind` when a reader asks for a frame the group never held and `Error.GroupTooLarge` when a write exceeds the cache budget and aborts the group. -- **Track ends**: `close()` ends a track at its live edge, while `finishAt(n)` declares the exclusive end ahead of it and still accepts the groups below. A finished track stays on its broadcast and serves its cache to late subscribers until `removeTrack`; an aborted one is removed, and subscribing to a track the broadcast does not have rejects with `Error.NotFound`, as in Rust. A subscriber reads the end with `final()` or awaits `finished()`. Group and datagram readers end once the live edge reaches the declared boundary, even while missing lower groups wait out the grace. The `closed` signal settles separately once every group below the end has arrived or was dropped; one reset before its header arrived is skipped after the subscription's max age on moq-lite (one second without one), or after one second on IETF. +- **Track ends**: `close()` ends a track at its live edge, while `finishAt(n)` declares the exclusive end ahead of it and still accepts the groups below. A finished track stays on its broadcast and serves its cache to late subscribers until `removeTrack`; an aborted one is removed, and subscribing to a track the broadcast does not have rejects with `Error.NotFound` when no on-demand handler is pulling requests, as in Rust. With a pulling handler, an absent track queues an on-demand request. A subscriber reads the end with `final()` or awaits `finished()`. Group and datagram readers end once the live edge reaches the declared boundary, even while missing lower groups wait out the grace. The `closed` signal settles separately once every group below the end has arrived or was dropped; one reset before its header arrived is skipped after the subscription's max age on moq-lite (one second without one), or after one second on IETF. - **Datagrams** on moq-lite 05+ and fetch-by-sequence for history. `track.fetchGroup(sequence)` on moq-lite resolves when the publisher sends the first response byte or finishes an empty group. A missing group rejects the fetch with `StreamCode.NotFound`, including every concurrent caller sharing that fetch. `fetchGroup(sequence, { signal })` abandons a pending fetch with the signal's reason; the shared stream is cancelled only once every caller has left. Once resolved, close the group instead. - **Errors**: deliberately closing a connection ends its received tracks cleanly. A peer close ends received tracks and open group readers with the session error and its close code. Errors live under one namespace: a stream reset throws `Error.Stream` with a `StreamCode`, while a session close gives `Error.Session` with a `SessionCode`. The registries are disjoint, so the same number means different things in each, and 64+ is yours. Named conditions such as `Error.TooFarBehind`, `Error.FrameTooLarge`, and `Error.GroupTooLarge` subclass `Error.Stream`, so one `code` check handles a condition raised here or reported by the peer. IETF streams use their own mapping: cancellation sends CANCELLED, other local failures send INTERNAL\_ERROR, and received codes remain opaque. - **Paths** with `Path.relative` for the cross-broadcast catalog references hang uses. A `Broadcast.Consumer` names its broadcast by `path`: the path it was requested at relative to the origin handle's root, or empty for a standalone broadcast. Those references resolve against it. Path patterns (`Path.Pattern`, `Path.Patterns`) are re-exported from [`@moq/pattern`](https://www.npmjs.com/package/@moq/pattern). Literal `Path` stays a coordinate. From 0fdef2caf50f617f7399acc6668988202262f4da Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Wed, 7 Oct 2026 11:17:03 -0700 Subject: [PATCH 7/8] test(net): use maxDelay in finished cache regression Co-Authored-By: GPT-6 --- js/net/src/broadcast.test.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/js/net/src/broadcast.test.ts b/js/net/src/broadcast.test.ts index 3bd8af6d02e..39fa01fd6d3 100644 --- a/js/net/src/broadcast.test.ts +++ b/js/net/src/broadcast.test.ts @@ -437,7 +437,7 @@ test("a finished track is still served from its cache", async () => { const late = broadcast .consume() .track("track1") - .subscribe({ maxAge: Milli(5000) }) + .subscribe({ maxDelay: Milli(5000) }) .ordered(); expect(await late.readString()).toBe("last"); expect(await late.nextGroup()).toBeUndefined(); From 98608f132fb9db8450cf072831616d02361e213e Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Wed, 7 Oct 2026 11:17:48 -0700 Subject: [PATCH 8/8] test(net): start handler before querying on-demand track Co-Authored-By: GPT-6 --- js/net/src/broadcast.test.ts | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/js/net/src/broadcast.test.ts b/js/net/src/broadcast.test.ts index 39fa01fd6d3..08cc430d17a 100644 --- a/js/net/src/broadcast.test.ts +++ b/js/net/src/broadcast.test.ts @@ -582,10 +582,11 @@ test("a pending track info query counts as broadcast demand", async () => { const broadcast = new BroadcastProducer(); const demand = broadcast.demand(); + const pending = wireOf(broadcast).requested(); const info = wireOf(broadcast).resolveTrackInfo("video"); expect(demand.used.peek()).toBe(true); - const request = await wireOf(broadcast).requested(); + const request = await pending; if (!request) throw new Error("expected request"); // Nobody subscribes to the queried track itself. expect(request.demand().used.peek()).toBe(false);