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
2 changes: 1 addition & 1 deletion doc/lib/rs/moq-net.md
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,7 @@ What you use it for, beyond what the concept page already describes:
- **Dial and accept sockets.** `socket::Endpoint::new(&origin, prefix, id)` is a server, a client, or both: its first dial announces a hidden client endpoint at `<prefix>/.client/<id>`, and its first accept a hidden server endpoint at `<prefix>/.server/<id>`, both used only to route sessions, so grants decide which roles it may take. A session speaks one of two protocols, each with its own dial and accept. `accept_tcp()` and `accept_track()` yield an `Incoming` dial to `accept` or `reject` (dropping it rejects). `dial_tcp(server)` and an accepted `tcp` dial yield a `socket::TcpStream`, a `group::Producer` and `group::Consumer` pair carrying one reliable, ordered byte pipe each way (finish is FIN, abort is RST, and `ready` paces the writer to the reader); `dial_track(server, info)` and an accepted `track` dial yield a `socket::TrackStream`, this side's `track::Producer` and a `track::Subscriber` of the peer's half, subscribed reliably and in order until the application updates it, one message per group. A dial resolves once the peer accepts, and an accept checks that the claimed dialer really dialed this endpoint, waiting for its endpoint while the dial stays open. Every hop needs moq-lite-07 or moq-transport: while the origin has an older moq-lite client session whose publish half doesn't opt into hidden broadcasts (`with_hidden(true)`), dials and accepts fail with `Unsupported`. A dial to a peer behind such a hop waits, as for a peer not online yet. Session tracks are never announced or listed. See [Sockets](/concept/socket).
- **One track per name.** Concurrent subscriptions share one request and producer. The application owns sequence numbers: the broadcast keeps nothing of an ended track, so a producer that replaces it starts at 0. A name always means the same content, so the replacement continues past its predecessor's groups with `create_group` at an explicit sequence. Readers of an aborted track resume onto the replacement when they read through an origin request, whose route always names an instance; otherwise their subscription ends with the error.
- **Authored tracks default to a zero `max_age`.** `track::Info::default()` sets `max_age` to `Some(Duration::ZERO)`, the live edge only; a publisher that wants readers to reach history sets a longer bound, or `with_max_age(None)` for no publisher limit. Media tracks from `hang::container::track_info` declare `hang::container::MAX_AGE` (30 seconds). `max_age` is how long a superseded group stays fresh, never the newest group; it frees no bytes, which the cache pool's expiry reclaims. Received metadata keeps absence as no limit, and an origin's `cache_duration` can only cap it lower.
- **End content by finishing tracks.** A broadcast has no finished state. When the input ends, finish each track; the broadcast stays announced and keeps serving them until you close it or drop its route. How long to keep it up for late readers is yours to decide: `moq_mux::Linger` holds a hang broadcast for a fixed window.
- **End content by finishing tracks.** A broadcast has no finished state. When the input ends, finish each track: `finish(self)` consumes the producer and returns a `track::Finished`, which can still take an older group below the end, be read, or be aborted, but not append. Hold it, and the broadcast stays announced and keeps serving the track until you close it or drop its route; dropping the last handle releases the track, so new readers no longer find it. How long to keep it up for late readers is yours to decide: `moq_mux::Linger` holds a hang broadcast for a fixed window. A finished group returns a `group::Finished`, which can be read or aborted to release its cache.
- **Demand says whether anyone is watching.** `demand()` on a track, group, or broadcast says whether a subscriber is attached. First-party capture does not wait for it: video encodes while enabled and audio keeps raw PCM to encode when someone listens, so a late subscription's `delay.max` or a FETCH finds the recent past. Demand gates bandwidth reservations, transcode rungs, and on-demand video where a publisher opts in, which saves the encode but leaves nothing from before the first subscriber. Holding a broadcast or track consumer is not demand: a track consumer requests nothing until it queries, subscribes, or fetches, and those count until dropped. A shared fetch stays up until its last reader leaves. Demand rolls up: a frame being read keeps its group wanted, a group a subscription or fetch handed out keeps its track wanted until read to its end, and any wanted track keeps its broadcast wanted.
- **Use the model without a runtime.** By default `moq-net` is its `poll_*` APIs and origin driver with caller-supplied time. The `async` feature adds their async wrappers, `time::run`, and both wire sessions.
- **You drive the session, or `moq-tokio` does.** `connect` and `accept` return a session plus a driver that never reads the clock itself. `moq_net::time::run` polls it on tokio. `moq-tokio` hides that. A custom transport implements `moq_net::transport::poll`, and `moq_net::transport::memory::pair` links two sessions in one process with no sockets, for tests or in-process links. `Server` bounds each accept with one deadline (10 s by default, `with_timeout`) across SETUP, your admission decision (`Handshake::expired`), and moq-lite 01/02's SETUP reply, and opens a receive window the transport held back once you admit (`with_receive_window`).
Expand Down
19 changes: 17 additions & 2 deletions js/net/api/index.api.md
Original file line number Diff line number Diff line change
Expand Up @@ -404,6 +404,11 @@ export namespace Group {
sequence: number;
} & Group.Frame | undefined;
}
export interface Finished {
readonly closed: Signals.GetPromise<Error | null>;
consume(): Group.Consumer;
readonly sequence: bigint;
}
export interface Frame {
arrived?: Instant;
payload: Uint8Array;
Expand All @@ -418,7 +423,7 @@ export namespace Group {
get closed(): Signals.GetPromise<Error | null>;
consume(): Group.Consumer;
createFrame(info: Frame.Info): Frame.Producer;
finish(): void;
finish(): Group.Finished;
get isClosed(): boolean;
readonly sequence: bigint;
writeFrame(frame: Group.Frame): void;
Expand Down Expand Up @@ -731,6 +736,16 @@ export namespace Track {
wanted(): bigint | undefined;
wantedChanged(): Promise<bigint | undefined>;
}
export interface Finished {
abort(error: Error): void;
close(): void;
readonly closed: Signals.GetPromise<Error | null>;
createGroup(sequence: bigint): Group.Producer;
info(): Promise<Track.Info>;
readonly name: string;
requests(): Track.Requests;
subscribe(options?: Track.Subscription): Track.Subscriber;
}
export interface Groups {
end?: Track.Bound;
start?: Track.Bound;
Expand Down Expand Up @@ -781,7 +796,7 @@ export namespace Track {
get closed(): Signals.GetPromise<Error | null>;
createGroup(sequence: bigint): Group.Producer;
demand(): Track.Demand;
finish(): void;
finish(): Track.Finished;
finishAt(end: Track.Position, error?: Error): void;
info(): Promise<Track.Info>;
largest(): Track.Position | undefined;
Expand Down
4 changes: 3 additions & 1 deletion js/net/bench/frames.ts
Original file line number Diff line number Diff line change
Expand Up @@ -54,7 +54,9 @@ const lite: Protocol = {
const producer = new Producer(0n);
const done = readFrames(new Reader(stream, undefined, LiteVersion.DRAFT_06), producer, {
scale: 1_000_000,
}).then(() => producer.finish());
}).then(() => {
producer.finish();
});
return { group: Promise.resolve(producer.consume()), done };
};
return { open, close: () => {} };
Expand Down
24 changes: 22 additions & 2 deletions js/net/src/group.ts
Original file line number Diff line number Diff line change
Expand Up @@ -210,6 +210,22 @@ export class Demand {
}
}

/**
* A group its producer finished: every frame is written, and it can still be read, but not
* written to. {@link Producer.finish} returns it, mirroring the Rust `group::Finished`; the
* producer itself still refuses a write after the finish.
*
* @public
*/
export interface Finished {
/** Sequence number of this group within its track. */
readonly sequence: bigint;
/** Settles once the group closes: `null` on a clean close, or the abort {@link Error}. */
readonly closed: GetPromise<Error | null>;
/** A read handle for this group. */
consume(): Consumer;
}

/**
* The write side of an ordered stream of frames within a track.
*
Expand Down Expand Up @@ -644,9 +660,13 @@ export class Producer {
return this.#state.closed.peek() !== undefined;
}

/** Marks the group complete: no more frames will be written. Idempotent. */
finish() {
/**
* Marks the group complete, returning it as {@link Finished}: no more frames will be written.
* Idempotent.
*/
finish(): Finished {
this.#end(null);
return this;
}

/**
Expand Down
4 changes: 3 additions & 1 deletion js/net/src/ietf/publisher.ts
Original file line number Diff line number Diff line change
Expand Up @@ -899,7 +899,9 @@ export class Publisher {
timescale,
priority: datagramPriority,
}).then(
() => datagramTrack?.finish(),
() => {
datagramTrack?.finish();
},
(err: unknown) => {
if (datagramTrack) datagramTrack.abort(error(err));
else console.debug(`stopping datagrams on this subscription: ${reason(err)}`);
Expand Down
28 changes: 28 additions & 0 deletions js/net/src/track.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -4722,3 +4722,31 @@ test("group sequences stop at 2^64-1, as a u64 does", () => {
producer.skipGroups(1n << 63n, 1n << 64n);
expect(() => producer.skipGroups(0n, (1n << 64n) + 1n)).toThrow(RangeError);
});

// Mirrors the Rust `track::Finished` doctests: the handle `finish` returns takes no new
// writes, at compile time and at run time, yet still fills a late group below the end.
test("finishing returns handles that write nothing new but fill a late group", async () => {
const producer = new TrackProducer("test");
const subscriber = producer.subscribe({ delay: { max: null }, ranges: [{ start: { absolute: 0n } }] });
producer.createGroup(1n).finish();
const finished = producer.finish();
// @ts-expect-error a finished track appends no group
expect(() => finished.appendGroup()).toThrow("at or past the track's end");
expect(() => finished.createGroup(2n)).toThrow("at or past the track's end");

const late = finished.createGroup(0n);
late.writeFrame(textFrame("late"));
const group = late.finish();
// @ts-expect-error a finished group takes no frame
expect(() => group.writeFrame(textFrame("later"))).toThrow();
const reader = group.consume();
expect(dec.decode((await reader.readFrame())?.payload)).toBe("late");
expect(await reader.readFrame()).toBeUndefined();
expect(await group.closed).toBeNull();

const got: bigint[] = [];
for (let next = subscriber.tryRecvGroup(); next; next = subscriber.tryRecvGroup()) got.push(next.sequence);
expect(got.sort()).toEqual([0n, 1n]);
expect(hooks.tryRecvGroup(subscriber, false)).toEqual({ kind: "done" });
finished.close();
});
40 changes: 35 additions & 5 deletions js/net/src/track.ts
Original file line number Diff line number Diff line change
Expand Up @@ -2116,15 +2116,18 @@ export class Producer {
}

/**
* Declare the track's end after the highest sequence written. A no-op once an end is declared or the track closed,
* so a cleanup path can finish whatever the track's state.
* Declare the track's end after the highest sequence written, returning it as {@link Finished}.
* A no-op once an end is declared or the track closed, so a cleanup path can finish whatever
* the track's state. A track that closed first keeps its outcome and declares no end, so its
* readers' `finished()` rejects.
*
* Not terminal: groups below the end may still be written. Readers end once the live edge
* reaches it.
*/
finish(): void {
if (this.#state.end.peek() !== undefined || this.#state.closed.peek() !== undefined) return;
this.finishAt({ group: this.#received, frame: 0 });
finish(): Finished {
if (this.#state.end.peek() === undefined && this.#state.closed.peek() === undefined)
this.finishAt({ group: this.#received, frame: 0 });
return this;
Comment thread
coderabbitai[bot] marked this conversation as resolved.
Resolved
}

/**
Expand Down Expand Up @@ -2235,6 +2238,33 @@ type Superseded = { successor?: Successor };
// the oldest held.
type Successor = { sequence: bigint; arrived: Instant; fate: () => Error | undefined };

/**
* A track its producer finished: its end is declared unless it closed first, and it can still
* take an older group below that end, be read, or be aborted or closed, but not append. {@link Producer.finish} returns it,
* mirroring the Rust `track::Finished`; the producer itself still refuses a group at or past the
* end.
*
* @public
*/
export interface Finished {
/** The track name. */
readonly name: string;
/** Settles once the track's outcome is final; see {@link Producer.closed}. */
readonly closed: GetPromise<Error | null>;
/** The track's info, once accepted. */
info(): Promise<Info>;
/** Create an older group below the end, which arrived late; see {@link Producer.createGroup}. */
createGroup(sequence: bigint): GroupProducer;
/** Serve the groups readers miss below the end; see {@link Producer.requests}. */
requests(): Requests;
/** Subscribe to this in-process track; see {@link Producer.subscribe}. */
subscribe(options?: Subscription): Subscriber;
/** Abort the track; see {@link Producer.abort}. */
abort(error: Error): void;
/** Release the track, like dropping the last Rust handle; see {@link Producer.close}. */
close(): void;
}

/**
* The read side of a live track subscription, mirroring the Rust `Subscriber`.
*
Expand Down
2 changes: 1 addition & 1 deletion quest/m2/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -201,7 +201,7 @@ quests that require them.
- [Connection state carries each phase's data](/quest/m2/connection-state-phases.md) - moq-tokio's `Observation`, moq-ffi's `MoqConnectionState`, and moq-c's `moq_connection_state` each hold one phase per value, so no field is readable in a phase where it means nothing
- [JS time values are types, not numbers](/quest/m2/js-time-types.md) - every public JS duration and instant is a `Clock.Duration` or `Clock.Instant` object, so a unit mistake fails to compile
- [Small API fixes before the cut](/quest/m2/api-shape/README.md) - one path and one spelling per item, names by role, and no dead or wrong-role public surface across net, transport, media, native, apps, JS, and bindings
- [Finishing a producer returns a Finished handle](/quest/m2/finished-handle.md) - `finish(self)` consumes moq-net's and the media crates' producers, so appending after finish doesn't compile
- [Finishing a media producer returns a Finished handle](/quest/m2/finished-handle.md) - `finish(self)` consumes the media crates' producers, as it does moq-net's, so appending after finish doesn't compile
- [Cut readiness](/quest/m2/cut-gate/README.md) - the checks the cut needs that break nothing: main no slower than release, vendored fixes ported, and moq-c at parity
- [Probe](/quest/m2/probe/README.md) - a session probes up to the bitrate it wants to send or receive, so a stopped simulcast rendition resumes and a viewer up-switches; browser padding is parked in m3 (held in m2 by open claims; moves to m3)
- [Finish the milestone re-cut](/quest/m2/recut-held.md) - claim-held epics move to the milestone their kind and priority give them once their claims merge
Expand Down
Loading
Loading