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: 2 additions & 2 deletions doc/concept/standard.md
Original file line number Diff line number Diff line change
Expand Up @@ -26,11 +26,11 @@ maps everything else to "not supported" or a harmless equivalent. The
subset drops. What a peer actually observes against this implementation:

- **Pull.** Subscribers ask. Single-track `PUBLISH` offers are declined; announce a namespace and serve the resulting subscriptions. Announcements go out unsolicited, and we also ask for every prefix we may discover. The solicit `SETUP` option makes us wait to be asked. Without it, a draft 16+ peer also gets each match as a `NAMESPACE` on its `SUBSCRIBE_NAMESPACE` stream, so it hears the namespace twice. We never send `PUBLISH`: on drafts 16 and 17 a `SUBSCRIBE_NAMESPACE` asking only for `PUBLISH` is refused, one asking for both gets only `NAMESPACE`, and any other Subscribe Options value closes the session.
- **History is one group.** A `FETCH` returns one group from the cache, or on drafts 14 through 19 the saved prefix of the group a new subscription just joined. A range of groups is refused, as is a draft 20+ `LOCATION_FILTER` that ends at Largest Object rather than an absolute End Location. On draft 20 and later, `FETCH_OK`'s End Location is the requested end, capped at Largest Object: a range holding no objects gets an empty fetch stream, and only a start past Largest Object is refused, with `INVALID_RANGE`. A relay's copy with no upstream subscription can't know Largest Object short of the track's end, so it echoes the requested end instead. JavaScript publishing refuses every `FETCH`. Datagrams are never fetchable. A Rust reader that only fetches learns the track from `TRACK_STATUS` instead of subscribing, so a finished track stays fetchable; draft 17 still subscribes, since its `TRACK_STATUS` answer cannot say whether the track is timed, and so does a reader whose publisher refuses `TRACK_STATUS` as `NOT_SUPPORTED`, as JavaScript does.
- **History is one group.** A `FETCH` returns one group from the cache, or on drafts 14 through 19 the saved prefix of the group a new subscription just joined. A range of groups is refused, as is a draft 20+ `LOCATION_FILTER` that ends at Largest Object rather than an absolute End Location. On draft 20 and later, `FETCH_OK`'s End Location is the requested end, capped at Largest Object: a range holding no objects gets an empty fetch stream, and only a start past Largest Object is refused, with `INVALID_RANGE`. A relay's copy with no upstream subscription can't know Largest Object short of the track's end, so it echoes the requested end instead. JavaScript publishing refuses every `FETCH`. Datagrams are never fetchable. A Rust reader that only fetches learns the track from `TRACK_STATUS` instead of subscribing, so a finished track stays fetchable; draft 17 still subscribes, since its `TRACK_STATUS` answer cannot say whether the track is timed, and so does a reader whose publisher refuses `TRACK_STATUS` as `NOT_SUPPORTED`.
- **Timing.** A track whose `SUBSCRIBE_OK` declares no `TIMESCALE` is untimed, as is every track on drafts 14 through 16. A Rust reader that never subscribed takes the units from `TRACK_STATUS` on draft 18 and later.
- **Strict SETUP and parameters.** Repeated unknown `SETUP` options, GREASE included, are accepted if well-formed; a repeated known option is rejected. On draft 17 and later, a `GROUP_ORDER` other than Ascending (1) or Descending (2) closes the session. Message parameters follow the negotiated draft's lists: drafts 14 and 15 ignore an unknown or misplaced parameter, draft 16 ignores one defined only for another message but closes the session on an unknown one, and draft 17 and later close it on both.
- **One `SETUP` credential**, forwarded to the [auth server](/bin/relay/auth#the-contract) unverified. A second `SETUP` token closes the session. We advertise no token cache, so an alias reference in `SETUP` closes it with `PROTOCOL_VIOLATION`, one on a request with `UNKNOWN_AUTH_TOKEN_ALIAS`, and a registration on a request with `AUTH_TOKEN_CACHE_OVERFLOW`. A token attached to an individual request is otherwise decoded and grants nothing, and a request repeating one is refused with `MALFORMED_AUTH_TOKEN`. `SUBSCRIBE_TRACKS` is refused unread, so its token is not decoded. On draft 17 and later, the negotiated [MoQ Auth extension](/concept/moq-lite#authorization) accepts additional session tokens in band.
- **Refused, not fatal.** A legal request this stack does not serve is rejected on its own and the session stays up: `FORWARD=0`, range filters, `TRACK_STATUS` to a JavaScript publisher, `SUBSCRIBE_TRACKS`, and the fetch forms above. On draft 19 and later, and in Rust on drafts 14 through 16, a subscription update may change only priority; any other update ends that subscription.
- **Refused, not fatal.** A legal request this stack does not serve is rejected on its own and the session stays up: `FORWARD=0`, range filters, `SUBSCRIBE_TRACKS`, and the fetch forms above. On draft 19 and later, and in Rust on drafts 14 through 16, a subscription update may change only priority; any other update ends that subscription.
- **Datagrams** are a single normal object at object 0, forwarded without renumbering. Anything else is dropped, and a malformed one closes the session. Rust and JavaScript both carry them on every draft.
- **Priority.** Higher is served first. The IETF default of 128 is this stack's 127, and a track that never sets one is 127.
- **Size.** An object extension block larger than 64 KiB ends that subgroup stream. The session stays up. This cap is ours, not the draft's.
Expand Down
8 changes: 8 additions & 0 deletions js/net/src/broadcast.ts
Original file line number Diff line number Diff line change
Expand Up @@ -247,6 +247,12 @@ async function resolveTrackInfo(state: BroadcastState, name: string, hold?: Abor
return untilAborted(info, hold);
}

// The newest frame cached for `name`, without subscribing: undefined when nobody serves it yet.
function largest(state: BroadcastState, name: string): track.Location | undefined {
const producer = lookup(state, name);
return producer && hooks.cachedLargest(producer);
}

// Serve a group from the local retained window by subscribing and scanning to the
// requested sequence. The default for a produced broadcast; the consuming wire layer
// overrides it to fetch over the network (or to reject when the transport has no FETCH).
Expand Down Expand Up @@ -350,6 +356,7 @@ export class Producer {
registerWire(this, {
subscribe: (name, options) => subscribe(this.#state, name, options),
resolveTrackInfo: (name, hold) => resolveTrackInfo(this.#state, name, hold),
largest: (name) => largest(this.#state, name),
fetchGroup: (name, sequence, options) => fetchGroup(this.#state, name, sequence, options),
requested: () => requested(this.#state),
});
Expand Down Expand Up @@ -519,6 +526,7 @@ export class Consumer {
registerWire(this, {
subscribe: (name, options) => subscribe(this.#state, name, options),
resolveTrackInfo: (name, hold) => resolveTrackInfo(this.#state, name, hold),
largest: (name) => largest(this.#state, name),
fetchGroup: (name, sequence, options) => fetchGroup(this.#state, name, sequence, options),
requested: () => requested(this.#state),
});
Expand Down
5 changes: 2 additions & 3 deletions js/net/src/ietf/connection.ts
Original file line number Diff line number Diff line change
Expand Up @@ -34,7 +34,7 @@ import {
} from "./subscribe_namespace.ts";
import { Subscriber } from "./subscriber.ts";
import { MalformedAuthToken } from "./token.ts";
import { TrackStatusRequest } from "./track.ts";
import { TRACK_STATUS_ERROR_14, TrackStatusRequest } from "./track.ts";
import { type IetfVersion, Version, versionName } from "./version.ts";

// The PADDING stream type (draft-18+): bytes a peer sends to probe for bandwidth.
Expand Down Expand Up @@ -519,8 +519,7 @@ export class Connection implements Established {
publish: PublishError.id,
publish_namespace: PublishNamespaceError.id,
subscribe_namespace: SubscribeNamespaceError.id,
// TRACK_STATUS_ERROR
track_status: 0x0f,
track_status: TRACK_STATUS_ERROR_14,
}[kind];
const legacy = version === Version.DRAFT_14 || version === Version.DRAFT_15 || version === Version.DRAFT_16;
await stream.writer.u53(version === Version.DRAFT_14 ? id14 : RequestError.id);
Expand Down
43 changes: 26 additions & 17 deletions js/net/src/ietf/ietf.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -504,23 +504,31 @@ test("TrackStatusRequest: round trip", async () => {
expect(decoded.trackName).toBe("main");
});

test("TrackStatus v14: round trip", async () => {
const msg = new Track.TrackStatus({
trackNamespace: Path.from("test"),
trackName: "status",
statusCode: 200,
lastGroupId: 42n,
lastObjectId: 100n,
});

const encoded = await encodeVersioned(msg, Version.DRAFT_14);
const decoded = await decodeVersioned(encoded, Track.TrackStatus.decode, Version.DRAFT_14);

expect(decoded.trackNamespace).toBe("test" as Path.Valid);
expect(decoded.trackName).toBe("status");
expect(decoded.statusCode).toBe(200);
expect(decoded.lastGroupId).toBe(42n);
expect(decoded.lastObjectId).toBe(100n);
// TRACK_STATUS_OK carries what SUBSCRIBE_OK would, as far as each draft's answer has room.
test("TrackStatusOk: round trip on every draft", async () => {
const properties = { timescale: Timescale.MILLI, priority: 7, groupOrder: 0x02, maxCacheDuration: 1000n };
for (const version of Object.values(Version).filter((v): v is IetfVersion => v !== Version.DRAFT_07)) {
const legacy = version === Version.DRAFT_14 || version === Version.DRAFT_15 || version === Version.DRAFT_16;
const msg = new Track.TrackStatusOk({
requestId: legacy ? 3n : undefined,
largest: { groupId: 4n, objectId: 1n },
properties,
});
const encoded = await encodeVersioned(msg, version);
const decoded = await decodeVersioned(encoded, Track.TrackStatusOk.decode, version);

expect(decoded.requestId).toBe(legacy ? 3n : undefined);
expect(decoded.largest).toEqual({ groupId: 4n, objectId: 1n });
// GROUP_ORDER is a field on draft-14 and a parameter on draft-15; REQUEST_OK has no
// properties block until draft-18.
const expected =
version === Version.DRAFT_14 || version === Version.DRAFT_15
? { groupOrder: 0x02 }
: version >= Version.DRAFT_18
? properties
: {};
expect(decoded.properties).toEqual(expected);
}
});

// Validation tests
Expand Down Expand Up @@ -2058,6 +2066,7 @@ test("TrackStatusRequest: carries SUBSCRIBE fields", async () => {
for (const [version, rest] of cases) {
const msg = await decodeVersioned(framed([...TRACK_HEAD, ...rest]), Track.TrackStatusRequest.decode, version);
expect(msg.trackName).toBe("video");
expect(msg.propertiesWanted).toBe(version !== Version.DRAFT_20);
}
});

Expand Down
Loading
Loading