Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions drafts/draft-lcurley-moq-hang.md
Original file line number Diff line number Diff line change
Expand Up @@ -399,6 +399,10 @@ A consumer MUST NOT skip to the newest group, since a later group does not super
It reads the one group the track carries, and MUST fail the read if the track carries a second, since whatever would have completed the first group is gone and yielding the remainder would present that gap as a continuous log.
This is why a consumer takes groups in arrival order rather than by ascending sequence: groups are separate streams, so a second group MAY arrive with a lower sequence than the first, and skipping it would report a truncated log as a whole one.

A consumer MUST NOT wait for the first group to end before it looks for a second.
A publisher that opens a second group while the first is still open is broken in exactly the way this rule exists to catch, and a consumer that only checks at the group boundary waits forever on a group that publisher may never finish.
A consumer MAY yield payloads it has already received from the first group before it fails, since those payloads precede the gap, but it MUST fail rather than block once they run out.

Retention is bounded, and this is the limit of "lossless".
A group's cache is finite, so a publisher that writes more than it holds evicts the log's earliest frames.
A consumer that has not kept up, or that subscribes later, then cannot read the log at all: the read fails once it reaches the evicted prefix, rather than silently resuming at whatever the cache still holds.
Expand Down
94 changes: 79 additions & 15 deletions js/binary/src/stream/consumer.ts
Original file line number Diff line number Diff line change
Expand Up @@ -30,14 +30,25 @@ export class Rolled extends Error {
* the payloads that would have completed the first are gone, so a publisher that cannot write ends
* the track instead. A second group is therefore a broken publisher, and reading it would present
* a gap as a continuous log, so it throws {@link Rolled} rather than yielding the remainder.
*
* The failure does not wait for the first group to end: whatever has already arrived in it is
* yielded, and the read then throws rather than blocking on a group a broken publisher may never
* finish.
*/
export class Consumer {
#track: Moq.Track.Subscriber;
#decompress: boolean;

#group?: Moq.Group.Consumer;
// Whether a read is in flight, so a second concurrent one is refused rather than served wrong.
#reading = false;
// Whether the log's one group has been taken, so a second is a rolled log rather than the first.
#taken = false;
// The in-flight `recvGroup`, tagged for the race and built once: a frame read that wins leaves it
// outstanding, a second call would take a second group off the track, and tagging it per read
// would chain a reaction onto it for every payload in the log. Cleared only when the group it
// carries is taken, so a second group stays resolved here and every later read fails on it again.
#pending?: Promise<{ group: Moq.Group.Consumer | undefined }>;
// The DEFLATE window for the group, present while decompressing.
#flate?: Flate;

Expand All @@ -47,29 +58,82 @@ export class Consumer {
}

/** Get the next payload, or `undefined` once the track ends. */
async next(): Promise<Uint8Array | undefined> {
next(): Promise<Uint8Array | undefined> {
// One reader at a time. Two concurrent calls await the same `recvGroup`, so the second would
// take the first's group for a rolled log and fail a perfectly good one.
if (this.#reading) throw new Error("multiple calls to next not supported");
this.#reading = true;
return this.#read().finally(() => {
this.#reading = false;
});
}

async #read(): Promise<Uint8Array | undefined> {
for (;;) {
if (!this.#group) {
// Arrival order rather than sequence order, because there is only ever one group to
// take and a second one has to be seen whatever its sequence. The monotonic
// `nextGroup` would drop a late lower sequence, which is the very loss this reports.
this.#group = await this.#track.recvGroup();
if (!this.#group) return undefined;
if (this.#taken) throw new Rolled();
const { group } = await this.#recvGroup();
if (!group) return undefined;
// The resolved `#pending` is the whole record of the failure: it is left in place, so
// every later read arrives back here and throws again rather than reading on.
if (this.#taken) {
group.close();
throw new Rolled();
}
this.#pending = undefined;
this.#taken = true;
this.#flate = this.#decompress ? new Flate() : undefined;
this.#group = group;
}

const frame = await this.#group.readFrame();
if (frame === undefined) {
// The log's one group is exhausted. Keep reading the track so a clean end still
// reports the log as complete, and so a second group is caught as Rolled.
this.#group = undefined;
continue;
}
const frame = await this.#readFrame(this.#group);
if (frame) return this.#flate ? this.#flate.frame(frame.payload) : frame.payload;

// The log's one group is exhausted. Keep reading the track so a clean end still
// reports the log as complete, and so a second group is caught as Rolled.
this.#group = undefined;
}
}

return this.#flate ? this.#flate.frame(frame.payload) : frame.payload;
// Read the group's next frame, throwing {@link Rolled} if the track hands over a second group
// first. A stream is one group, so the track is watched while the group is held: a publisher
// that opens a second and leaves the first open would otherwise park this read forever on a log
// that has already lost payloads.
async #readFrame(group: Moq.Group.Consumer): Promise<Moq.Group.Frame | undefined> {
// Drain what already arrived before consulting the track, so only a read that would really
// block depends on which of the two lands first. `skipped` is the evicted prefix that
// `readFrame` reports as lagged and `tryReadFrame` would hand back across the gap.
if (!group.skipped) {
const buffered = group.tryReadFrame();
if (buffered) return buffered;
}

const frame = group.readFrame();
const winner = await Promise.race([frame.then((frame) => ({ frame }) as const), this.#recvGroup()]);
Comment on lines +110 to +111

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Cancel the losing frame read

When the second group wins this race while the first group remains open, the losing readFrame() cannot be cancelled and stays subscribed to the first group's signals indefinitely. That pending async operation retains the Group.Consumer, whose expiry closure retains the track subscriber, so the exact broken-publisher scenario handled here can keep the subscription and its state alive even after the caller discards the stream consumer. Race group.readable() or another cancellable readiness primitive and only start readFrame() after readiness wins; the identical JSON implementation needs the same correction. (Written by GPT-5.6 Sol)

Useful? React with 👍 / 👎.

if ("frame" in winner) return winner.frame;

if (winner.group) {
// Close both rather than drain the rest of a log that has already lost payloads. Closing the
// held group settles the read that just lost, which otherwise stays registered on the
// group's signals and keeps this consumer's subscription reachable after the caller drops
// it. The next read then waits on the track, where the second group is still resolved.
group.close();
winner.group.close();
this.#group = undefined;
throw new Rolled();
}

// The track is finished, which does not truncate the group in hand.
return await frame;
}

// Receive the track's next group, reusing the in-flight read a frame may have raced and won.
//
// Arrival order rather than sequence order, because there is only ever one group to take and a
// second one has to be seen whatever its sequence. The monotonic `nextGroup` would drop a late
// lower sequence, which is the very loss this reports.
#recvGroup(): Promise<{ group: Moq.Group.Consumer | undefined }> {
this.#pending ??= this.#track.recvGroup().then((group) => ({ group }));
return this.#pending;
}

/** Iterate over every payload in order, until the track ends. */
Expand Down
40 changes: 40 additions & 0 deletions js/binary/src/stream/stream.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -89,6 +89,46 @@ test("a second group is a rolled log, not a continuation", async () => {
await expect(consumer.next()).rejects.toThrow(Rolled);
});

test("a second concurrent read is refused rather than served the first one's group", async () => {
// Both calls would await the same in-flight `recvGroup`, and the loser would take the winner's
// group for a second one and fail a perfectly good log. Rust gets this from `&mut self`.
const track = new Track.Producer("test");
const producer = new Producer(track);
producer.append(payloads(1)[0]);
producer.finish();

const consumer = new Consumer(track.subscribe());
const first = consumer.next();
expect(() => consumer.next()).toThrow("multiple calls to next not supported");
expect(await first).toEqual(payloads(1)[0]);
});

test("a second group is reported while the first is still open", async () => {
// A boundary-only check would never look at the track again while a group is open, so a
// publisher that opens a second group and leaves the first one running parks the read forever
// on a log that already lost payloads. The payloads already in hand are still delivered.
const track = new Track.Producer("test");

// Both groups stay open, the way a publisher writing to two at once leaves them.
const first = track.appendGroup();
first.writeFrame({ payload: payloads(1)[0], timestamp: Time.Timestamp.now() });
const second = track.appendGroup();
second.writeFrame({ payload: payloads(2)[1], timestamp: Time.Timestamp.now() });

const consumer = new Consumer(track.subscribe({ maxAge: REPLAY_LATENCY }));
expect(await consumer.next()).toEqual(payloads(1)[0]);
await expect(consumer.next()).rejects.toThrow(Rolled);

// Both mirrors are released. The read that lost the race would otherwise stay registered on the
// first group, keeping this consumer's subscription reachable after the caller drops it.
expect(first.used.peek()).toBe(false);
expect(second.used.peek()).toBe(false);

// Sticky: a later read must not report the rest of the first group as a whole log.
first.writeFrame({ payload: payloads(3)[2], timestamp: Time.Timestamp.now() });
await expect(consumer.next()).rejects.toThrow(Rolled);
});

test("an undecodable payload ends the log for a reader already inside the group", async () => {
// The decoder-limit check ends the track like any other lost record, and by then an earlier
// append may already have opened the group. A reader that pulled that group has to see the
Expand Down
94 changes: 79 additions & 15 deletions js/json/src/stream/consumer.ts
Original file line number Diff line number Diff line change
Expand Up @@ -27,45 +27,109 @@ export class Rolled extends Error {
* instead. A second group is therefore a broken publisher, and reading it would present a gap as a
* continuous log, so it throws {@link Rolled} rather than yielding the remainder. When something
* else already owns the track, use the {@link Decoder} directly.
*
* The failure does not wait for the first group to end: whatever has already arrived in it is
* yielded, and the read then throws rather than blocking on a group a broken publisher may never
* finish.
*/
export class Consumer<T> {
#track: Moq.Track.Subscriber;
#decoder: Decoder<T>;

#group?: Moq.Group.Consumer;
// Whether a read is in flight, so a second concurrent one is refused rather than served wrong.
#reading = false;
// Whether the log's one group has been taken, so a second is a rolled log rather than the first.
#taken = false;
// The in-flight `recvGroup`, tagged for the race and built once: a frame read that wins leaves it
// outstanding, a second call would take a second group off the track, and tagging it per read
// would chain a reaction onto it for every record in the log. Cleared only when the group it
// carries is taken, so a second group stays resolved here and every later read fails on it again.
#pending?: Promise<{ group: Moq.Group.Consumer | undefined }>;

constructor(track: Moq.Track.Subscriber, config: ConsumerConfig = {}) {
this.#track = track;
this.#decoder = new Decoder(config);
}

/** Get the next record, or `undefined` once the track ends. */
async next(): Promise<T | undefined> {
next(): Promise<T | undefined> {
// One reader at a time. Two concurrent calls await the same `recvGroup`, so the second would
// take the first's group for a rolled log and fail a perfectly good one.
if (this.#reading) throw new Error("multiple calls to next not supported");
this.#reading = true;
return this.#read().finally(() => {
this.#reading = false;
});
}

async #read(): Promise<T | undefined> {
for (;;) {
if (!this.#group) {
// Arrival order rather than sequence order, because there is only ever one group to
// take and a second one has to be seen whatever its sequence. The monotonic
// `nextGroup` would drop a late lower sequence, which is the very loss this reports.
this.#group = await this.#track.recvGroup();
if (!this.#group) return undefined;
if (this.#taken) throw new Rolled();
const { group } = await this.#recvGroup();
if (!group) return undefined;
// The resolved `#pending` is the whole record of the failure: it is left in place, so
// every later read arrives back here and throws again rather than reading on.
if (this.#taken) {
group.close();
throw new Rolled();
}
this.#pending = undefined;
this.#taken = true;
// Each group is its own compressed stream, so the window starts cold.
this.#decoder.reset();
this.#group = group;
}

const frame = await this.#group.readFrame();
if (frame === undefined) {
// The log's one group is exhausted. Keep reading the track so a clean end still
// reports the log as complete, and so a second group is caught as Rolled.
this.#group = undefined;
continue;
}
const frame = await this.#readFrame(this.#group);
if (frame) return this.#decoder.decode(frame.payload);

// The log's one group is exhausted. Keep reading the track so a clean end still
// reports the log as complete, and so a second group is caught as Rolled.
this.#group = undefined;
}
}

return this.#decoder.decode(frame.payload);
// Read the group's next frame, throwing {@link Rolled} if the track hands over a second group
// first. A stream is one group, so the track is watched while the group is held: a publisher
// that opens a second and leaves the first open would otherwise park this read forever on a log
// that has already lost records.
async #readFrame(group: Moq.Group.Consumer): Promise<Moq.Group.Frame | undefined> {
// Drain what already arrived before consulting the track, so only a read that would really
// block depends on which of the two lands first. `skipped` is the evicted prefix that
// `readFrame` reports as lagged and `tryReadFrame` would hand back across the gap.
if (!group.skipped) {
const buffered = group.tryReadFrame();
if (buffered) return buffered;
}

const frame = group.readFrame();
const winner = await Promise.race([frame.then((frame) => ({ frame }) as const), this.#recvGroup()]);
if ("frame" in winner) return winner.frame;

if (winner.group) {
// Close both rather than drain the rest of a log that has already lost records. Closing the
// held group settles the read that just lost, which otherwise stays registered on the
// group's signals and keeps this consumer's subscription reachable after the caller drops
// it. The next read then waits on the track, where the second group is still resolved.
group.close();
winner.group.close();
this.#group = undefined;
throw new Rolled();
}

// The track is finished, which does not truncate the group in hand.
return await frame;
}

// Receive the track's next group, reusing the in-flight read a frame may have raced and won.
//
// Arrival order rather than sequence order, because there is only ever one group to take and a
// second one has to be seen whatever its sequence. The monotonic `nextGroup` would drop a late
// lower sequence, which is the very loss this reports.
#recvGroup(): Promise<{ group: Moq.Group.Consumer | undefined }> {
this.#pending ??= this.#track.recvGroup().then((group) => ({ group }));
return this.#pending;
}

async *[Symbol.asyncIterator](): AsyncIterator<T> {
Expand Down
48 changes: 46 additions & 2 deletions js/json/src/stream/stream.test.ts
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
import { expect, test } from "bun:test";
import { Track } from "@moq/net";
import { Consumer, Producer } from "./index.ts";
import { Time, Track } from "@moq/net";
import { Consumer, Producer, Rolled } from "./index.ts";

type Rec = { n: number };

Expand Down Expand Up @@ -66,3 +66,47 @@ test("records with embedded newlines round-trip (JSON escapes the newline)", asy
}
expect(out).toEqual([value, value, value, value]);
});

test("a second group is reported while the first is still open", async () => {
// A stream is one group. A publisher that opens a second lost whatever would have completed the
// first, so the read reports that rather than handing back the remainder as a continuous log.
// A boundary-only check would never look at the track again while the first group is open, so
// this parks forever without the eager check. Written by hand because this producer never rolls.
const track = new Track.Producer("test");
const encode = (record: Rec) => new TextEncoder().encode(JSON.stringify(record));

// Both groups stay open, the way a publisher writing to two at once leaves them.
const first = track.appendGroup();
first.writeFrame({ payload: encode({ n: 0 }), timestamp: Time.Timestamp.now() });
const second = track.appendGroup();
second.writeFrame({ payload: encode({ n: 1 }), timestamp: Time.Timestamp.now() });

// Ask for a replay window, so the first group is delivered rather than skipped by the
// subscriber's default max-age budget once a newer group exists.
const consumer = new Consumer<Rec>(track.subscribe({ maxAge: 30_000 }));
expect(await consumer.next()).toEqual({ n: 0 });
await expect(consumer.next()).rejects.toThrow(Rolled);

// Both mirrors are released. The read that lost the race would otherwise stay registered on the
// first group, keeping this consumer's subscription reachable after the caller drops it.
expect(first.used.peek()).toBe(false);
expect(second.used.peek()).toBe(false);

// Sticky: a later read must not report the rest of the first group as a whole log.
first.writeFrame({ payload: encode({ n: 2 }), timestamp: Time.Timestamp.now() });
await expect(consumer.next()).rejects.toThrow(Rolled);
});

test("a second concurrent read is refused rather than served the first one's group", async () => {
// Both calls would await the same in-flight `recvGroup`, and the loser would take the winner's
// group for a second one and fail a perfectly good log. Rust gets this from `&mut self`.
const track = new Track.Producer("test");
const producer = new Producer<Rec>(track);
producer.append({ n: 0 });
producer.finish();

const consumer = new Consumer<Rec>(track.subscribe());
const first = consumer.next();
expect(() => consumer.next()).toThrow("multiple calls to next not supported");
expect(await first).toEqual({ n: 0 });
});
Loading
Loading