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/js/net.md
Original file line number Diff line number Diff line change
Expand Up @@ -49,7 +49,7 @@ publication.announce();
- **One send estimate per connection.** `Bandwidth.Allocator` divides it by track priority, max-min fair within a tier. An idle track claims nothing, though its reservation still reads the share it would get. Publishers reserve against it so their targets sum to the estimate. A connection samples the estimate from its transport only while a reservation reads it, so receive-only and lingering connections do no stats work, and the first reservation after none reads `undefined` until one fresh snapshot lands. A transport that cannot report one is never sampled and reads `undefined`: the WebSocket fallback, WebRTC, and WebTransport without `getStats()` (shipping Chromium and Safari).
- **List a broadcast's tracks.** `for await (const event of broadcast.tracks())` reports each track the broadcast lists (`added`, with its `Track.Info`), one `synced`, then `added` and `removed` as tracks come and go, until the broadcast ends; leaving the loop stops listing. Over a session it needs `moq-lite-07-wip`, syncs at once with what this side holds, and the peer's tracks follow as `added`. A track served only on request is never listed. See [discovery](/concept/moq-lite#discovery).
- **One track per name.** Concurrent subscriptions share one request and producer. `createTrack` on a name with a request still queued answers it. The application owns sequence numbers: the broadcast keeps nothing of an ended track, so a track that replaces it, created or requested, starts at 0. A name always means the same content, so the replacement continues past its predecessor's groups by writing its first group with an explicit sequence. Sequences are `bigint`, so every ID the wire carries fits, past 2^53 included: `track.createGroup(5n)`, `{ absolute: 10n }`. Frame indices and relative anchors stay `number`.
- **Serve history on request.** `track.requests()` opens a handle that serves the groups readers miss: ones their ranges name below the newest group written that the cache no longer holds, or never did. Each run of misses arrives as a `Track.Fill` from `await requests.requestedFill()`, shared by every reader missing it. `accept(sequence)` it into the cache and write the group's frames as first published, `dropGroups(start, end)` what the source lacks (sequences are `bigint`), and serve `wanted()` until it is `undefined`: a reader that leaves or narrows stops wanting its groups. `close()` the fill when done; whatever is still wanted is named dropped. A `fetchGroup` of an uncached group asks the handle at once, even for a group not written yet, which a live write then answers; with no handle open it fails with `NotFound`, as in Rust, and a reader's miss is given up. A reader only asks for what its `delay.max` still wants, so a reader at the live edge never asks. This serves lite FETCH and lite-07 ranged subscriptions from the same track, as Rust's `requests()` does.
- **Serve history on request.** `track.requests()` opens a handle that serves the groups readers miss: ones their ranges name below the newest group written that the cache no longer holds, or never did. Each run of misses arrives as a `Track.Fill` from `await requests.requestedFill()`, shared by every reader missing it. `accept(sequence)` it into the cache and write the group's frames as first published, `dropGroups(start, end)` what the source lacks (sequences are `bigint`), and serve `wanted()` until it is `undefined`: a reader that leaves or narrows stops wanting its groups. `close()` the fill when done; whatever is still wanted is named dropped. A `fetchGroup` of an uncached group asks the handle at once, even for a group not written yet, which a live write then answers; with no handle open it fails with `NotFound`, as in Rust, and a reader's miss is given up. A reader only asks for what its `delay.max` still wants, so a reader at the live edge never asks. This serves lite FETCH, single-group IETF FETCH, and lite-07 ranged subscriptions from the same track, as Rust's `requests()` does.
- **Timing is per track, with no default.** A track that declares a `timescale` carries a `timestamp` on every frame; one without is [untimed](/concept/moq-lite#subscriptions) and its frames carry none. Omitting it means untimed, as in Rust. Nothing stamps a frame for you: the publisher passes the timestamp, and the `Timed` type (`{ value, at }`) carries one into the `@moq/json` producers.
- **A subscription's `delay` is a `Track.Delay { min, max }`, as in Rust.** Staleness is `delay.max`: it counts from a group's successor, by media time and by wall clock, whichever reaches it first. `delay.min` is the target latency, carried on moq-lite 07; a peer that cannot carry it leaves it `null` (not stated). Passing the old `maxAge` or `maxDelay` key throws a `TypeError` naming `delay.max`. The publisher's own staleness bound is the separate `Track.Info.maxAge`, which caps `delay.max` and fetches.
- **The cache keeps an idle group for 30 seconds.** A track evicts a group nothing has written for 30 seconds, matching the Rust cache's default expiry; a live track's newest group is exempt until a newer one arrives, unless it failed. Neither `Track.Info.maxAge` nor `delay.max` changes that window: they only decide which cached groups a reader still receives.
Expand Down
4 changes: 4 additions & 0 deletions js/net/MIGRATE.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,10 @@ How to update your code for each breaking change, newest first.

## Unreleased

### IETF FETCH serves on-demand history ([#7794](https://github.com/moq-dev/moq/pull/7794))

A single-group IETF FETCH now asks `track.requests()` for groups the publisher's cache no longer holds, or never held, using the same `Track.Fill` responder as moq-lite. Existing responders need no changes. Multi-group IETF FETCH remains unsupported.

### A timestamp out of range at the track's timescale is a `TimestampMismatch` ([#7702](https://github.com/moq-dev/moq/pull/7702))

A frame or datagram whose timestamp leaves the safe range once converted to the track's timescale is refused at the write with `TimestampMismatch`, as Rust refuses it, rather than with a `RangeError` when it is encoded.
Expand Down
146 changes: 145 additions & 1 deletion js/net/src/ietf/fetch.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -2,13 +2,17 @@ import { expect, test } from "bun:test";
import { Manual, Milli, Nano } from "@moq/clock";
import { Signal } from "@moq/signals";
import type { Grant } from "../auth.ts";
import { accept as acceptSession, connect as connectSession } from "../connection/index.ts";
import { error } from "../error.ts";
import { hooks } from "../internal.ts";
import { CACHE_EXPIRY } from "../ledger.ts";
import * as Lite from "../lite/index.ts";
import { createMockTransportPair } from "../mock.ts";
import { Producer as OriginProducer } from "../origin.ts";
import * as Path from "../path.ts";
import { Reader, Stream, Writer } from "../stream.ts";
import { Timescale, Timestamp } from "../time.ts";
import type { Order, Producer as TrackProducer } from "../track.ts";
import type { Fill, Order, Producer as TrackProducer } from "../track.ts";
import { SEGMENT_BYTES } from "../util/limits.ts";
import { wireOf } from "../wire.ts";
import { Fetch, FetchHeader, FetchOk, type FetchType, type Location } from "./fetch.ts";
Expand Down Expand Up @@ -56,6 +60,7 @@ function serve(version: IetfVersion, grant?: Signal<Grant | undefined>, priority
return {
pair,
pub,
origin,
broadcast: publication.broadcast,
track,
uni,
Expand Down Expand Up @@ -423,6 +428,145 @@ test("a FETCH the cache cannot answer is refused before FETCH_OK", async () => {
}
});

test("a FETCH fills never-cached and evicted history, then reuses the cache", async () => {
for (const version of VERSIONS) {
for (const evicted of [false, true]) {
using clock = manual();
using fx = serve(version);
if (evicted) {
writeGroup(fx.track, 1n, ["1-0", "1-1", "1-2"]);
await clock.advance(ms(CACHE_EXPIRY * 2));
}
writeGroup(fx.track, 3n, ["live"]);
const cache = fx.track.subscribe({ ranges: [] });
expect(hooks.holdsGroup(cache, 1n)).toBe(false);
cache.close();
using requests = fx.track.requests();
let fill: Fill | undefined;
const requested = requests.requestedFill().then((value) => {
fill = value;
});
const msg = new Fetch({
requestId: FETCH_ID,
type: range(version, at(1, 1), at(1, 3)),
subscriberPriority: 3,
groupOrder: "ascending",
});
const fetching = fetch(fx, msg);
await flush();
expect(fill).toBeDefined();
if (!fill) throw new Error("no history fill");
expect([fill.start, fill.end, fill.priority, fill.maxDelay]).toEqual([1n, 2n, 124, null]);
const group = fill.accept(1n);
for (let object = 0; object < 3; object++)
group.writeFrame({
payload: new TextEncoder().encode(`1-${object}`),
timestamp: Timestamp.fromMillis(object),
});
group.finish();
fill.close();
await requested;
const first = served(await fetching);
expect(first.objects).toEqual([
[1, 1, "1-1"],
[1, 2, "1-2"],
]);
expect(first.ok.endLocation).toEqual(endAt(version, 1, 2));
expect(first.ok.endOfTrack).toBe(false);
// No handler remains: the same responder serves the filled group from cache.
requests.close();
expect(served(await fetch(fx, msg)).objects).toEqual(first.objects);
}
}
});

test("a FETCH preserves relayed metadata and cached groups without upstream FETCH", async () => {
for (const version of VERSIONS) {
for (const warm of [false, true]) {
using fx = serve(version);
const upstream = new OriginProducer();
const publication = upstream.createBroadcast(Path.from("archive"));
publication.announce();
const track = publication.broadcast.createTrack("video", { timescale: Timescale.MILLI });
writeGroup(track, 3n, ["3-0", "3-1"]);
// lite-04 has no FETCH; lite-05 can fetch, but refuses empty subscription ranges.
const pair = createMockTransportPair(warm ? Lite.ALPN_04 : Lite.ALPN_05);
const url = new URL("https://localhost:4443/test");
const [client, server] = await Promise.all([
connectSession({ url, transport: pair.client }),
acceptSession({ url, transport: pair.server, publish: upstream.consume() }),
]);
try {
const source = wireOf(client).consume(Path.from("archive"));
const cached = warm ? source.track("video").subscribe({ delay: { max: null } }) : undefined;
if (cached) {
const group = await cached.recvGroup();
expect(group?.sequence).toBe(3n);
while (await group?.readFrame()) {}
group?.close();
}
const requests = fx.origin.requestsRoute(Path.from("relayed"));
const cursor = requests.requested();
const requested = cursor.next();
const type = { ...range(version, at(3, 0), at(3, 0)), trackNamespace: Path.from("relayed") };
const fetching = fetch(fx, new Fetch({ requestId: FETCH_ID, type }));
const next = await requested;
if (next.done) throw new Error("no relayed broadcast request");
next.value.serve(source);
await cursor.return?.();
expect(served(await fetching).objects).toEqual(pairs([3]));
cached?.close();
} finally {
client.abort();
server.abort();
upstream.close();
}
}
}
});

test("a FETCH refused by its history responder sends no FETCH_OK", async () => {
for (const version of VERSIONS) {
using fx = serve(version);
writeGroup(fx.track, 3n, ["live"]);
using requests = fx.track.requests();
const responding = (async () => {
using fill = await requests.requestedFill();
expect(fill?.wanted()).toBe(1n);
})();
const fetching = fetch(fx, new Fetch({ requestId: FETCH_ID, type: range(version, at(1, 0), at(1, 0)) }));
expect(refused(await fetching)).toBe(DOES_NOT_EXIST);
requests.close();
await responding;
}
});

test("a cancelled or unauthorized FETCH withdraws its unanswered history fill", async () => {
for (const version of VERSIONS) {
for (const revoke of [false, true]) {
const grant = new Signal<Grant | undefined>(undefined);
using fx = serve(version, grant);
writeGroup(fx.track, 3n, ["live"]);
using requests = fx.track.requests();
const requested = requests.requestedFill();
const request = requestStream(version);
const fetching = fx.pub.runFetch(
new Fetch({ requestId: FETCH_ID, type: range(version, at(1, 0), at(1, 0)) }),
request.stream,
);
using fill = await requested;
expect(fill?.wanted()).toBe(1n);
if (revoke) grant.set({ publish: new Path.Patterns([]), subscribe: new Path.Patterns([]) });
else request.withdraw();
if (revoke) expect(refused(await answer(fx, request.answer, "ascending"))).toBe(UNAUTHORIZED);
await fetching;
expect(await fill?.wantedChanged()).toBeUndefined();
const read = await request.answer.done().catch(error);
expect(read === true || read instanceof Error).toBe(true);
}
}
});

// Datagrams are never cached, so a FETCH reaching one finds no group there.
test("a FETCH of a datagram is refused", async () => {
for (const version of VERSIONS) {
Expand Down
21 changes: 12 additions & 9 deletions js/net/src/ietf/publisher.ts
Original file line number Diff line number Diff line change
Expand Up @@ -2232,7 +2232,8 @@ export class Publisher {

/**
* Handles an incoming FETCH on a bidi stream: a range of the named track, or a joining
* FETCH's head of its subscription's group, answered from the cache.
* FETCH's head of its subscription's group. A named range missing from the cache asks
* the producer's request handler; a joining head must already be cached.
*
* @internal
*/
Expand All @@ -2242,7 +2243,8 @@ export class Publisher {
}

async #runFetch(msg: Fetch, request: RequestStream) {
// FILL_TIMEOUT is accepted and ignored: a one-group read ends with the group.
// FILL_TIMEOUT does not truncate a group or time out its application fill. Both remain
// wanted until answered, refused, or cancelled by the requester or its grant.
const version = this.#session.version;
const type = msg.type;
const named = type.kind === "standalone" || type.kind === "filtered" ? type : undefined;
Expand Down Expand Up @@ -2341,8 +2343,8 @@ export class Publisher {
}

/**
* Resolve a standalone or draft-22 FETCH to its group reader and end metadata,
* or the refusal to answer with.
* Resolve a standalone or draft-22 FETCH to its group reader and end metadata, filling
* uncached history through the producer's request handler, or the refusal to answer with.
*
* A whole-group request waits for the group to finish, so a downstream cache never
* mistakes a prefix for a complete group.
Expand Down Expand Up @@ -2386,9 +2388,8 @@ export class Publisher {

const broadcast = await this.#resolve(named.trackNamespace, signal);
const priority = fromWire(msg.subscriberPriority);
const cache = broadcast
.track(named.trackName)
.subscribe({ priority, delay: { max: Milli(Varint.MAX_U53), min: null } });
const track = broadcast.track(named.trackName);
const cache = track.subscribe({ priority, delay: { max: Milli(Varint.MAX_U53), min: null } });
let answer: FetchAnswer | undefined;
try {
const info = await untilAborted(cache.info(), signal);
Expand Down Expand Up @@ -2420,8 +2421,10 @@ export class Publisher {
}

const selected = range.start.group;
const group = hooks.cachedGroup(cache, selected);
if (!group) return { condition: "does_not_exist", reasonPhrase: `group ${range.start.group}` };
// A relayed track may hold the group even when its upstream cannot FETCH. Only a
// cache miss asks the producer's handler or fetches the group from its serving route.
const group =
hooks.cachedGroup(cache, selected) ?? (await track.fetchGroup(selected, { priority, signal }));
const slice = fetchSlice(range, selected);
// Wait for the selected headers or the group's end, through this reader's recovery
// and verdict. The reader holds only the normal tail, not a copied slice.
Expand Down
1 change: 0 additions & 1 deletion quest/m1/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -155,7 +155,6 @@ per-frame CPU growth since #5926.
- [A smaller, safer API than release](/quest/m1/api-audit/README.md) - every surface added since release has a consumer or is gone, overlapping operations are collapsed, names mirror across Rust, JS, and the bindings, and every break says how to migrate
- [Register moq-dev draft 20 in the interop runner](/quest/m1/ietf-drop/README.md) - land the external registry, notes, and README correction for drafts 18, 20, and 22
- [moq-quic's API improves on quinn's](/quest/m1/quic-api/README.md) - moq-quic and both QUIC drivers ship one mirrored API: `send::`/`recv::` namespaces, one error per direction, consuming terminal operations, plain configs, no quinn baggage
- [On-demand JavaScript FETCH](/quest/m1/js-fetch-on-demand.md) - browser publishers answer IETF FETCH for evicted or uncached groups through the JS ranges request surface
- [Native rung disable proof](/quest/m1/simulcast-rung-disable.md) - a shaped uplink through moq-ffi proves the top rendition stops and resumes over real BBR3 probing
- [Audio jitter target](/quest/m1/audio-jitter-target/README.md) - the playout target is default in both languages; time-stretched browser playback without steady-state underruns and a native trace replay remain
- [A/V clock](/quest/m1/av-clock.md) - the audio playhead drives Sync.reference while audio plays, through per-track sync handles
Expand Down
25 changes: 0 additions & 25 deletions quest/m1/js-fetch-on-demand.md

This file was deleted.

4 changes: 2 additions & 2 deletions test/interop/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -55,8 +55,8 @@ Node and Bun. The current CLI also FETCHes group 1 of a finished track from the
publisher and each selected native JS runtime, requires exactly its three objects, each
with its own bytes, and closes under the relay idle-out check. Each native JS runtime also serves
that FETCH from history (`CLI FETCH history`): its publisher writes only group 3 live and answers
groups 0 through 2, which it never cached, from an in-memory responder on `track.requests()`. A
moq-transport pass skips it, since JavaScript does not route an IETF FETCH to the responder yet.
groups 0 through 2, which it never cached, from an in-memory responder on `track.requests()`.
This runs on moq-lite and every supported IETF draft.

A late-join lane runs Rust-to-Rust and Rust/Node/Bun in both directions. The publisher
writes the first two objects of group 0 before any subscriber exists and leaves the group
Expand Down
6 changes: 2 additions & 4 deletions test/interop/interop.sh
Original file line number Diff line number Diff line change
Expand Up @@ -504,8 +504,7 @@ plan_pass() {
for runtime in js-native-node js-native-bun; do
needs "$runtime" || continue
record "not run" case="CLI FETCH" publisher="$runtime" subscriber=rust
# run_tails skips it on moq-transport, so only plan it where it runs.
[[ "$VERSION" == moq-transport-* ]] || record "not run" case="CLI FETCH history" publisher="$runtime" subscriber=rust
record "not run" case="CLI FETCH history" publisher="$runtime" subscriber=rust
record "not run" case="late join" publisher=rust subscriber="$runtime"
record "not run" case="late join" publisher="$runtime" subscriber=rust
record "not run" case=tail publisher=rust subscriber="$runtime"
Expand Down Expand Up @@ -2421,8 +2420,7 @@ run_tails() {
for runtime in js-native-node js-native-bun; do
needs "$runtime" || continue
run_fetch_round "$runtime"
# A moq-transport FETCH is not served from the request handler yet.
[[ "$(pinned_version)" == moq-transport-* ]] || run_fetch_round "$runtime" history
run_fetch_round "$runtime" history
done
echo "=== late join ==="
run_late_pair rust rust
Expand Down
Loading