Skip to content
Closed
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
21 changes: 21 additions & 0 deletions drafts/draft-lcurley-moq-lite.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,7 @@ author:
normative:
moqt: I-D.ietf-moq-transport
qmux: I-D.ietf-quic-qmux
reset-stream-at: I-D.ietf-quic-reliable-stream-reset
qmuxws:
title: "QMux over WebSocket"
target: https://datatracker.ietf.org/doc/draft-lcurley-qmux-websocket/
Expand Down Expand Up @@ -714,6 +715,7 @@ A subscriber assembling a Group from more than one publisher does so across sepa

Both the publisher and subscriber MAY reset the stream at any time.
This is not a fatal error and the session remains active.
A publisher that declared [Reliable Reset](#reliable-reset-parameter) resets a Group Stream with RESET_STREAM_AT, so the GROUP message still arrives and the subscriber can account for the stream.
The subscriber MAY cache the error and potentially retry later.

## Datagrams
Expand Down Expand Up @@ -840,6 +842,8 @@ The following Setup Parameters are defined:
|------|-----------|-------------|
| 0x5 | Hop | Hop ID (i) |
|------|-----------|-------------|
| 0x6 | Reliable Reset | Flag (i) |
|------|-----------|-------------|

### Probe Parameter {#probe-parameter}
The Probe Parameter advertises the sender's capability level when acting as a publisher on a [Probe Stream](#probe).
Expand Down Expand Up @@ -901,6 +905,21 @@ Declaring it at setup gives the receiver the peer's identity before any other st
Either endpoint MAY send it; a subscriber-only endpoint with no identity MAY omit it, but a publisher SHOULD have a Hop ID regardless (see [ANNOUNCE_OK](#announce-ok)).
A relay MUST NOT forward it.

### Reliable Reset Parameter {#reliable-reset-parameter}
The Reliable Reset Parameter declares that every Group Stream the sender counts in a [SUBSCRIBE_END](#subscribe-end) `Stream Count` delivers its GROUP message, even when the sender resets it.
The Parameter Value is a variable-length integer: `1` declares it, and `0` is equivalent to omitting the parameter.
A receiver MUST close the session with a PROTOCOL_VIOLATION on any other value.

A sender that declares it MUST count a Group Stream only once its GROUP message is written, and MUST reset a counted Group Stream with RESET_STREAM_AT [reset-stream-at], giving a Reliable Size that covers the GROUP message.
A Group Stream reset before its GROUP message is written is not counted.
It MUST NOT declare it unless the peer negotiated the reset_stream_at transport parameter, so it applies only to bindings 1 and 2, and only on a version whose SUBSCRIBE_END carries a `Stream Count`.
An endpoint whose transport API cannot reset a stream that way does not declare it.

A subscriber whose publisher declared it waits for every counted Group Stream without a bound, since each is sure to arrive; see [SUBSCRIBE_END](#subscribe-end).
A lost datagram is not counted and does not change that.

Either endpoint MAY send it, and the two directions are independent. A relay MUST NOT forward it: each hop declares what its own transport does.


## ANNOUNCE_REQUEST {#announce-request}
A subscriber sends an ANNOUNCE_REQUEST message to indicate it wants to receive announcements for any broadcasts with a path that starts with the requested prefix.
Expand Down Expand Up @@ -1331,6 +1350,7 @@ A relay counts the Group Streams it opened itself, never the count it received u
The publisher MUST NOT send SUBSCRIBE_END until every Group Stream it will open for the subscription has been opened, so the count is final; it does not wait for them to finish.
The subscriber has received every Group Stream once it has read the header of `Stream Count` of them, which MAY happen after SUBSCRIBE_END or the FIN since streams are not ordered.
A Group Stream reset before its header arrived is never seen, so a subscriber SHOULD bound how long it waits for the rest, for example by `Subscriber Max Age`.
When the publisher declared [Reliable Reset](#reliable-reset-parameter), every counted Group Stream delivers its header, so the subscriber SHOULD NOT bound the wait.

## FETCH
FETCH is sent by a subscriber to request a single group from a track.
Expand Down Expand Up @@ -1600,6 +1620,7 @@ The `Message Length` describes the payload size on the wire.
- Hid routes with a `.`-prefixed segment below the requested prefix from announce discovery, and added the ANNOUNCE_REQUEST `Hidden` field to opt in.
- Added `Stream Count` to SUBSCRIBE_END: the number of Group Streams opened for the subscription. SUBSCRIBE_END is now sent once every counted Group Stream has opened, rather than as soon as the final group is known.
- Removed SUBSCRIBE_DROP and its type 0x2; a group without a Group Stream is not counted.
- Added the SETUP `Reliable Reset` parameter (0x6): the sender counts a Group Stream only once its GROUP message is written and resets it with RESET_STREAM_AT keeping that message, so a subscriber waits for every counted stream without a bound.
- The Subscribe Stream FIN now follows once every counted Group Stream has finished or been reset.
- Added the Spread Hash tie-break after the shortest path: a hash of the requested path and the route's Hop IDs, so equal-cost advertisers of one prefix share its paths.
- Added a local link preference to route selection, after the newest Epoch and before the 0 Hop ID check: the higher preference a subscriber assigns to the arriving link wins, and an unassigned link is neutral. Not carried on the wire.
Expand Down
9 changes: 9 additions & 0 deletions js/net/src/lite/setup.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,7 @@ const PARAM_PROBE = 0x1n;
const PARAM_PATH = 0x2n;
const PARAM_ROLE = 0x3n;
const PARAM_HOP = 0x5n;
const PARAM_RELIABLE_RESET = 0x6n;

function concat(chunks: Uint8Array[]): Uint8Array {
const total = chunks.reduce((sum, c) => sum + c.byteLength, 0);
Expand Down Expand Up @@ -147,6 +148,14 @@ test("hop 0 decodes as absent", async () => {
expect(got.hop).toBeUndefined();
});

test("reliable reset round-trips as a 0/1 flag", async () => {
expect((await roundTrip(new Setup({ reliableReset: true }))).reliableReset).toBe(true);
expect((await roundTrip(new Setup())).reliableReset).toBe(false);
expect((await decodeParam(PARAM_RELIABLE_RESET, Varint.encode(0))).reliableReset).toBe(false);
expect((await decodeParam(PARAM_RELIABLE_RESET, Varint.encode(1))).reliableReset).toBe(true);
await expect(decodeParam(PARAM_RELIABLE_RESET, Varint.encode(2))).rejects.toThrow();
});

test("SETUP is rejected before draft-05", async () => {
await expect(bytes((w) => new Setup().encode(w, Version.DRAFT_04), Version.DRAFT_04)).rejects.toThrow();
});
Expand Down
26 changes: 24 additions & 2 deletions js/net/src/lite/setup.ts
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,8 @@ const PARAM_PATH = 0x2n;
const PARAM_ROLE = 0x3n;
/** Setup Parameter id for the endpoint's Hop ID. */
const PARAM_HOP = 0x5n;
/** Setup Parameter id declaring that the endpoint's group resets keep their header. */
const PARAM_RELIABLE_RESET = 0x6n;

/** Cap on the number of parameters in a bag, matching the Rust decoder. */
const MAX_PARAMS = 64;
Expand Down Expand Up @@ -182,6 +184,8 @@ export interface SetupProps {
role?: Role;
/** See {@link Setup.hop}. Omitted by default. */
hop?: Hop;
/** See {@link Setup.reliableReset}. Defaults to `false`. */
reliableReset?: boolean;
}

/**
Expand Down Expand Up @@ -219,11 +223,20 @@ export class Setup {
*/
hop?: Hop;

constructor({ probe, path, role, hop }: SetupProps = {}) {
/**
* Whether this endpoint counts a group stream only once its GROUP message is written,
* and delivers that message even when it resets the stream (lite-07+). The peer then
* waits for each counted stream rather than giving up after a grace. A browser cannot
* reset that way, so `@moq/net` never declares it.
*/
reliableReset: boolean;

constructor({ probe, path, role, hop, reliableReset }: SetupProps = {}) {
this.probe = probe ?? ProbeLevel.None;
this.path = path;
this.role = role ?? Role.Both;
this.hop = hop;
this.reliableReset = reliableReset ?? false;
}

static #guard(version: Version) {
Expand All @@ -248,6 +261,9 @@ export class Setup {
if (this.hop !== undefined && this.hop !== 0n) {
params.setVarint(PARAM_HOP, this.hop, version);
}
if (this.reliableReset) {
params.setVarint(PARAM_RELIABLE_RESET, 1n, version);
}
await params.encode(w);
}

Expand All @@ -269,7 +285,13 @@ export class Setup {
const hopRaw = await params.getVarint(PARAM_HOP, version);
const hop = hopRaw === undefined || hopRaw === 0n ? undefined : HopSchema.parse(hopRaw);

const setup = new Setup({ probe, path, role, hop });
const reliableRaw = await params.getVarint(PARAM_RELIABLE_RESET, version);
if (reliableRaw !== undefined && reliableRaw > 1n) {
throw new Error(`invalid reliable reset value: ${reliableRaw}`);
}
const reliableReset = reliableRaw === 1n;

const setup = new Setup({ probe, path, role, hop, reliableReset });
if (pathBytes !== undefined || roleCode !== undefined) clientParameters.add(setup);
return setup;
}
Expand Down
6 changes: 4 additions & 2 deletions js/net/src/lite/subscriber.ts
Original file line number Diff line number Diff line change
Expand Up @@ -1192,7 +1192,8 @@ export class Subscriber {
//
// lite-07 counts streams, so skipped sequences owe nothing. Older drafts account for
// the range using received headers and SUBSCRIBE_DROP. A counted stream reset before
// its header leaves no trace, so the grace still bounds that wait. Streams whose
// its header leaves no trace, so the grace still bounds that wait, unless the publisher
// declared reliable reset: then every counted stream delivers its header. Streams whose
// headers arrived keep reading until their own FIN or reset.
#settleTail(entry: SubscribeEntry): Promise<void> {
const { tail, track } = entry;
Expand All @@ -1213,7 +1214,8 @@ export class Subscriber {
return tail.covers(start, end);
};

return tail.settle(complete, track.closed);
const exact = entry.streams !== undefined && this.#peerSetup?.peek()?.reliableReset === true;
return tail.settle(complete, track.closed, { exact });
}

/**
Expand Down
49 changes: 46 additions & 3 deletions js/net/src/lite/tail.test.ts
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
import { describe, expect, test } from "bun:test";
import { Milli } from "@moq/clock";
import { Signal } from "@moq/signals";
import { ProtocolViolation, StreamCode, StreamError } from "../error.ts";
import type { Consumer as GroupConsumer } from "../group.ts";
import { randomHop } from "../hop.ts";
Expand All @@ -9,6 +10,7 @@ import { Reader, Stream } from "../stream.ts";
import { Timescale } from "../time.ts";
import type { Groups } from "../track.ts";
import { Group as GroupMessage } from "./group.ts";
import { Setup } from "./setup.ts";
import { StreamId } from "./stream.ts";
import {
encodeSubscribeResponse,
Expand Down Expand Up @@ -53,9 +55,15 @@ function groupStream(subscriber: Subscriber, sequence: number) {
* it answers TRACK_INFO, then writes whatever responses the test asks for on the subscribe
* stream and FINs it when told.
*/
async function subscribed(version: Version, maxDelay = GRACE, groups?: Groups) {
async function subscribed(version: Version, maxDelay = GRACE, groups?: Groups, peerSetup?: Setup) {
const pair = createMockTransportPair(ALPN_05);
const subscriber = new Subscriber(pair.client, version, randomHop());
const subscriber = new Subscriber(
pair.client,
version,
randomHop(),
undefined,
new Signal<Setup | undefined>(peerSetup),
);
const reader = subscriber.consume(Path.from("room")).track("video").subscribe({ maxDelay, groups });

const info = await Stream.accept(pair.server, version);
Expand Down Expand Up @@ -92,7 +100,7 @@ async function readAll(group: GroupConsumer | undefined): Promise<string[]> {
}

/** Whether `promise` settles within `ms`. */
async function settlesWithin(promise: Promise<unknown>, ms: number): Promise<boolean> {
async function settlesWithin(promise: PromiseLike<unknown>, ms: number): Promise<boolean> {
let timer: ReturnType<typeof setTimeout> | undefined;
const pending = new Promise<false>((resolve) => {
timer = setTimeout(() => resolve(false), ms);
Expand Down Expand Up @@ -363,6 +371,41 @@ test("lite-07 zero count ends without grace even when the announced range is non
expect(reader.end()).toEqual({ group: 3, frame: 0 });
});

// A publisher that declared reliable reset delivers the header of every stream it counts, so
// a missing one is still on its way: the subscription waits past the grace for it.
for (const reliableReset of [false, true]) {
test(`lite-07 ${reliableReset ? "waits past" : "gives up after"} the grace for a counted stream with reliable reset ${reliableReset ? "declared" : "undeclared"}`, async () => {
const peer = new Setup({ reliableReset });
const { subscriber, reader, respond, fin } = await subscribed(Version.DRAFT_07, GRACE, undefined, peer);
await respond({ start: new SubscribeStart(0) });
await respond({ end: new SubscribeEnd(1, 1) });
await fin();

const ended = settlesWithin(reader.closed, GRACE * 3);
expect(await ended).toBe(!reliableReset);
if (!reliableReset) return;

const late = groupStream(subscriber, 0);
late.write("late");
late.finish();
await late.handled;
expect(await readAll(await reader.recvGroup())).toEqual(["late"]);
expect(await settlesWithin(reader.recvGroup(), 1000)).toBe(true);
expect(await reader.closed).toBeNull();
});
}

// The declaration only drops the grace where SUBSCRIBE_END counts streams; older drafts
// cannot tell a datagram hole from a stream in flight.
test("lite-06 keeps the grace even when the publisher declared reliable reset", async () => {
const peer = new Setup({ reliableReset: true });
const { reader, respond, fin } = await subscribed(Version.DRAFT_06, GRACE, undefined, peer);
await respond({ start: new SubscribeStart(0) });
await respond({ end: new SubscribeEnd(1) });
await fin();
expect(await settlesWithin(reader.closed, GRACE * 3)).toBe(true);
});

for (const started of [false, true]) {
test(`a bare FIN ${started ? "after SUBSCRIBE_START" : "without responses"} aborts the track`, async () => {
const { reader, respond, fin } = await subscribed(Version.DRAFT_05);
Expand Down
23 changes: 13 additions & 10 deletions js/net/src/tail.ts
Original file line number Diff line number Diff line change
Expand Up @@ -30,7 +30,8 @@ export interface TailOptions {
* waits on them.
*
* A lost datagram is not owed: it leaves a hole that waits out the grace like a stream reset
* before its header.
* before its header. A publisher whose resets keep the header (reliable reset) needs no
* grace: on lite-07 every stream it counts arrives.
*
* @internal
*/
Expand Down Expand Up @@ -103,21 +104,23 @@ export class Tail {
*
* A stream still being read is always waited for: a group ends on its own stream's FIN
* or reset, never because its track ended. The grace only gives up on streams that never
* arrived.
* arrived, and `exact` skips it for a publisher that promised every owed stream arrives.
*/
async settle(complete: () => boolean, closed: GetPromise<unknown>): Promise<void> {
async settle(complete: () => boolean, closed: GetPromise<unknown>, { exact = false } = {}): Promise<void> {
// A gap that aged past the grace since the last insert is no longer waited for either.
this.#expire(now());

let expired = false;
const timer = new AbortController();
void sleep(Nano.fromMilli(this.#grace()), { signal: timer.signal }).then(
() => {
expired = true;
this.#bump();
},
() => {},
);
if (!exact) {
void sleep(Nano.fromMilli(this.#grace()), { signal: timer.signal }).then(
() => {
expired = true;
this.#bump();
},
() => {},
);
}
try {
while (closed.peek() === undefined) {
if (this.#active === 0 && (expired || complete())) return;
Expand Down
1 change: 1 addition & 0 deletions rs/moq-net/src/client.rs
Original file line number Diff line number Diff line change
Expand Up @@ -200,6 +200,7 @@ impl Client {
cost: self.cost,
// Filled by `lite::start` from the attached origin handles.
hop: None,
reliable_reset: lite::Setup::detect_reliable_reset(&session, version),
}
} else {
lite::Setup::default()
Expand Down
7 changes: 7 additions & 0 deletions rs/moq-net/src/coding/writer.rs
Original file line number Diff line number Diff line change
Expand Up @@ -211,6 +211,13 @@ impl<S: crate::transport::poll::SendStream, V: StreamCodes> Writer<S, V> {
self.stream.as_mut().unwrap().set_priority(send_order.into());
}

/// Mark what has flushed so far for a later reset to still deliver, where the session
/// supports it. See [`crate::transport::poll::SendStream::checkpoint`].
pub fn checkpoint(&mut self) {
debug_assert_eq!(self.flushed, self.buffer.len(), "checkpoint with unflushed bytes");
self.stream.as_mut().unwrap().checkpoint();
}

/// Cast the writer to a different version, used during version negotiation.
pub fn with_version<O>(mut self, version: O) -> Writer<S, O> {
Writer {
Expand Down
Loading
Loading