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 dart/moq_ffi/lib/src/moq.dart
Original file line number Diff line number Diff line change
Expand Up @@ -21353,11 +21353,11 @@ void _checkApiChecksums() {
throw UniffiInternalError.panicked("UniFFI API checksum mismatch");
}
if (uniffi_moq_ffi_checksum_method_moqoriginconsumer_announced_broadcast() !=
56171) {
40619) {
throw UniffiInternalError.panicked("UniFFI API checksum mismatch");
}
if (uniffi_moq_ffi_checksum_method_moqoriginconsumer_request_broadcast() !=
54627) {
36974) {
throw UniffiInternalError.panicked("UniFFI API checksum mismatch");
}
if (uniffi_moq_ffi_checksum_method_moqoriginproducer_consume() != 52357) {
Expand Down
4 changes: 2 additions & 2 deletions doc/lib/js/net.md
Original file line number Diff line number Diff line change
Expand Up @@ -42,8 +42,8 @@ publication.announce();
- **Answer claimed paths with `using`.** `requests(prefix)` claims a prefix and yields each requested path. Use `using prepared = request.prepare(epoch)`, fill its broadcast, then `prepared.publish()` to answer with a new publisher instance and keep the `Publication` it returns. Leaving the scope without publishing, including on a throw, refuses the request as unroutable. Explicit `prepared.close()` or closing its unpublished broadcast does the same; disposal after publishing leaves the returned publication and its fill broadcast live. Reject before preparing with `request.reject(err)`. A retained, unclosed prepared answer keeps the request pending; JavaScript garbage collection provides no prompt cleanup guarantee.
- **End content by finishing tracks.** A broadcast has no finished state. When the input ends, `finish()` each track, then `close()` it; closing a track without finishing aborts it. The broadcast stays announced and keeps serving them until you `close()` it. How long to keep it up for late readers is yours to decide.
- **Requests can pin an epoch.** `consumer.request(path, { epoch })` resolves only through a route announcing that [publisher epoch](/concept/moq-lite#publisher-epochs). The resolved broadcast's `epoch` names the route it came through, pinned or not.
- **Follow restarts.** `origin.request(path, { announced: true })` follows whichever publisher instance serves the path: its `active` changes to a fresh broadcast on a restart, clears on an end, and resolves again on the next start, so read it reactively and close the request when done. Instances are never stitched, so subscribe again to each new broadcast. Another route of the same epoch taking over (epochs travel only on `moq-lite-07-wip`) keeps `active` as is, and each track subscription resumes there from the first group it lacks. A refusal ends the request. Add `epoch` to pin one instance; a plain `request(path)` keeps its accepted instance, can resolve blindly, and ends once that instance stops serving. To list what is live, iterate `announced(scope)`.
- **Discovery follows what you watch.** A `consume` origin asks the relay for announcements only under the prefixes its readers watch with `announced(scope)` or `request(path, { announced: true })`, stops asking about a prefix 2s after nothing at or beneath it is watched, and asks again on reconnect. A plain `request(path)` asks nothing and subscribes blind, but once it resolves through a discovered route it watches its path until closed, so it outlives the listing that found it. A relay that refuses an announce request turns that session's announced requests blind too.
- **Follow restarts.** `origin.request(path, { announced: true })` follows whichever publisher instance serves the path: its `active` changes to a fresh broadcast on a restart, clears on an end, and resolves again on the next start, so read it reactively and close the request when done. Instances are never stitched, so subscribe again to each new broadcast. Another route of the same epoch taking over (epochs travel only on `moq-lite-07-wip`) keeps `active` as is, and each track subscription resumes there from the first group it lacks. A refusal ends the request. Add `epoch` to pin one instance, which the request waits for again after an end. A plain `request(path)` keeps its accepted instance and ends once that instance stops serving; while pending, it fails `Unroutable` once discovery of its path has synced without a route for it. To list what is live, iterate `announced(scope)`.
- **Discovery follows what you watch.** A `consume` origin asks the relay for announcements only under the prefixes its readers watch with `announced(scope)` or `request(path)`, stops asking about a prefix 2s after nothing at or beneath it is watched, and asks again on reconnect. Every request watches its path from creation until closed, so it outlives the listing that found it. A relay that refuses an announce request downgrades that session: plain requests subscribe blind through it, and announced requests keep waiting for a session that can discover.
- **Connections share by URL and versions.** `new Connection({ url })` pools and reconnects with backoff, which the elements use. An ordered `versions` list, spelled like `moq-lite-06` as in Rust, applies to both WebTransport and WebSocket; equivalent lists share, while a different order or an omitted list gets its own pool entry. Supplying your own transport options or origin selects a private loop. Receive estimates are on demand: observe `connection.probe` reactively or subscribe while you need them; `peek()` alone opens no PROBE stream.
- **GOAWAY moves the session.** The connection dials the replacement at once while the old session keeps serving its groups, up to `goaway.handover` (default 10s, or the relay's deadline when that is sooner). New requests keep opening on the old session until the replacement's route outranks it, which is a restart without an epoch: an unpinned announced request follows the replacement, while a blind or epoch-pinned request stays on its accepted instance. With an epoch, which travels only when `moq-lite-07-wip` is offered, the replacement serves the same broadcast, so open subscriptions move across without missing a group. An empty GOAWAY redials the same URL. A redirect stays on the same host unless `goaway.redirect` is `"follow"`, which also presents the tokens on the connection's `auth` handle to the new host.
- **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.
Expand Down
2 changes: 1 addition & 1 deletion doc/lib/rs/moq-net.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ What you use it for, beyond what the concept page already describes:
- **Requests can pin an epoch.** `consumer.request_broadcast(path, Some(epoch))` resolves only through a route announcing that [publisher epoch](/concept/moq-lite#publisher-epochs); `None` takes whichever route wins. The resolved consumer names its epoch in `info().epoch`, pinned or not.
- **Rank several CDNs.** Dial each with its own subscribe handle, `origin.clone().with_preference(origin::Preference::new(rank))` (higher wins; 0 is neutral and a negative rank demotes), all on one origin. Requests use the preferred link that has a route and fail over to the next; see [multiple CDNs](/concept/moq-lite#multiple-cdns).
- **Follow restarts.** `consumer.announced_broadcast(path, None)` hands out each publisher instance serving a path from `available()`: the first once announced, then each one that takes over or returns after an end, like JS `request(path, { announced: true })`. A broadcast already resolved stays on the old instance until dropped or its route goes. `consumer.follow(path)` yields the underlying start, update, restart, and end of the route a request resolves.
- **Discovery follows what you watch.** A client session asks the relay for announcements only under the prefixes its subscribe origin's readers watch, with `announced()`, `routed_broadcast`, or `announced_broadcast`, stops asking about a prefix 2s after nothing at or beneath it is watched, and asks again on reconnect. A broadcast resolved through a discovered route keeps its path watched until dropped. `request_broadcast` watches nothing, so a path nobody watches is unroutable. A server session, or a client fed into an origin handle marked `with_link(origin::Link::Peer)` or `Link::Upstream`, asks for everything it may, so a relay discovers everything. An HTTP gateway (the moq-hls `Server`, the moq-rtc WHEP router) watches its whole scope while it lives, so the paths its callers name never open a request each. moq-lite-03/04 sessions, whose announcements mark no initial set, still ask for everything.
- **Discovery follows what you watch.** A client session asks the relay for announcements only under the prefixes its subscribe origin's readers watch, with `announced()`, `routed_broadcast`, or `announced_broadcast`, stops asking about a prefix 2s after nothing at or beneath it is watched, and asks again on reconnect. A broadcast resolved through a discovered route keeps its path watched until dropped. `request_broadcast` owns discovery of its path and reports absence only once discovery has synced; no separate watch is needed. A server session, or a client fed into an origin handle marked `with_link(origin::Link::Peer)` or `Link::Upstream`, asks for everything it may, so a relay discovers everything. An HTTP gateway (the moq-hls `Server`, the moq-rtc WHEP router) watches its whole scope while it lives, so the paths its callers name never open a request each. moq-lite-03/04 sessions, whose announcements mark no initial set, still ask for everything.
- **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 only when the broadcast announces an epoch; otherwise their subscription ends with the error.
- **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 last producer. How long to keep it up for late readers is yours to decide: `moq_mux::Linger` holds a hang broadcast for a fixed window.
- **Publish only while someone is watching.** `demand()` on a track, group, or broadcast says whether a subscriber is attached, which is how capture and transcode skip work nobody asked for. 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.
Expand Down
36 changes: 35 additions & 1 deletion js/net/bench/requests.ts
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
/** Sweep request restart and cancellation over independent origin and waiter dimensions. */
/** Sweep request restart, cancellation, and discovery settlement over independent origin and waiter dimensions. */
import { Producer as Broadcast } from "../src/broadcast";
import * as Epoch from "../src/epoch";
import { Publisher as IetfPublisher } from "../src/ietf/publisher";
Expand Down Expand Up @@ -94,6 +94,40 @@ for (const unrelated of [8, 128, 2048])
origin.close();
}

// An initial set landing settles only the pending requests beneath its prefix, never every
// request in the table, however many land in one task.
console.log("pending,landed,settle_us");
for (const pending of [128, 1024, 8192])
for (const landed of [1, 16, 128]) {
const samples: number[] = [];
for (let round = 0; round < 5; round++) {
const origin = new Producer();
const wire = wireOf(origin);
const detach = wire.attach(true);
const initialSets = new Map<Path.Valid, () => void>();
const stop = wire.interests((prefix, wanted) => {
if (wanted) initialSets.set(prefix, wire.snapshot(prefix));
});
const held = Array.from({ length: pending }, (_, i) => origin.request(Path.from(`held/${i}`)));
const touched = Array.from({ length: landed }, (_, i) => origin.request(Path.from(`touched/${i}`)));
await settle();
const start = performance.now();
for (let i = 0; i < landed; i++) initialSets.get(Path.from(`touched/${i}`))?.();
// The settlement is one microtask queued by the first landing, ahead of this one.
await Promise.resolve();
if (round > 0) samples.push((performance.now() - start) * 1000);
if (touched.some((request) => request.closed.peek() === undefined)) throw new Error("absence unsettled");
if (held.some((request) => request.closed.peek() !== undefined)) throw new Error("unsynced path settled");
for (const request of [...held, ...touched]) request.close();
for (const release of initialSets.values()) release();
stop();
detach();
origin.close();
}
samples.sort((a, b) => a - b);
console.log(`${pending},${landed},${samples[2].toFixed(2)}`);
}

// Keep old instances on distinct same-epoch failovers, then cancel new demand.
// This exercises ownership checks inside one cleanup, independently of wire sharing.
console.log("failovers,extra_routes,cancel_us");
Expand Down
62 changes: 51 additions & 11 deletions js/net/src/connection/forward.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -124,17 +124,21 @@ function record(stream: Announce.Consumer): string[] {
return events;
}

test("no watcher opens no announce request, and a plain request answers blind", async () => {
test("a plain request discovers an unwatched path and waits for its initial set", async () => {
const origin = new OriginProducer();
const session = new FakeSession();
forwardAnnounced(session.session, origin);

expect(session.requests).toEqual([]);
const request = origin.request(Path.from("room"));
await settle();
expect(session.requests).toEqual([]);
expect(session.open()).toEqual(["room/**"]);
expect(request.active.peek()).toBeUndefined();
expect(session.consumes(Path.from("room"))).toBe(0);
start(session.stream("room/**"), "room");
session.stream("room/**").synced();
await settle();
expect(request.active.peek()).toBeDefined();
expect(session.consumes(Path.from("room"))).toBe(1);

request.close();
session.die();
origin.close();
Expand Down Expand Up @@ -466,15 +470,20 @@ test("a refused announce request downgrades the session once, and later watches
session.stream("room/**").close(new Error("namespace rejected"));
await settle();
expect(origin.discovery.peek()).toBe(false);
// The gated request falls back to a blind answer on the live session.
expect(watched.active.peek()).toBeDefined();
// Following cannot use a peer that no longer announces; a plain request can.
expect(watched.active.peek()).toBeUndefined();
expect(session.consumes(path)).toBe(0);
const plain = origin.request(path);
await settle();
expect(plain.active.peek()).toBeDefined();
expect(session.consumes(path)).toBe(1);

const later = origin.announced(Path.Pattern.subtree(Path.from("other")));
await settle();
expect(session.requests.length).toBe(1);

later.close();
plain.close();
watched.close();
session.die();
origin.close();
Expand Down Expand Up @@ -503,13 +512,17 @@ test("a discovery failure under a live session retracts what it fed and answers
expect(wireOf(origin).routes(path)).toBe(false);
expect(origin.discovery.peek()).toBe(false);

// The same request falls back to a blind answer on the live session.
// The follower stays offline; a separate plain request can use the blind peer.
expect(watched.closed.peek()).toBeUndefined();
expect(watched.active.peek()).toBeDefined();
expect(watched.active.peek()).toBeUndefined();
const plain = origin.request(path);
await settle();
expect(plain.active.peek()).toBeDefined();
// The announcement's own consume, plus the blind answer standing in for it now.
expect(session.consumes(path)).toBe(2);

watched.close();
plain.close();
session.die();
origin.close();
});
Expand Down Expand Up @@ -544,6 +557,11 @@ test("a request replaced across one coalesced wakeup still gets answered", async
const path = Path.from("wanted");

forwardAnnounced(session.session, origin);
// Refusing discovery downgrades the session, so plain requests take its blind answers.
const listing = origin.announced(Path.Pattern.subtree(path));
await settle();
session.stream("wanted/**").close(new Error("namespace rejected"));
await settle();

const first = origin.request(path);
await settle();
Expand All @@ -563,6 +581,7 @@ test("a request replaced across one coalesced wakeup still gets answered", async
expect(session.consumes(path)).toBe(2);

second.close();
listing.close();
session.die();
origin.close();
});
Expand Down Expand Up @@ -606,7 +625,7 @@ test("a scoped origin narrows a root watch to its disjoint literal heads", async
origin.close();
});

test("a scoped session filters announcements and blind requests under its root", async () => {
test("a scoped session filters discovered routes and requests under its root", async () => {
const origin = new OriginProducer();
const scoped = origin.scope(Path.from("tenant"), new Path.Patterns([Path.Pattern.parse("room/*/chat")]));
const session = new FakeSession();
Expand All @@ -617,12 +636,13 @@ test("a scoped session filters announcements and blind requests under its root",
await settle();
// Session-relative: the scope's root is the session's.
expect(session.open()).toEqual(["room/**"]);
for (const prefix of ["room/alice/video", "room/alice/chat"]) start(session.stream("room/**"), prefix);
for (const prefix of ["room/alice/video", "room/alice/chat", "room/bob/chat"])
start(session.stream("room/**"), prefix);

const allowed = origin.request(Path.from("tenant/room/bob/chat"));
const denied = origin.request(Path.from("tenant/room/bob/video"));
await settle();
expect(events).toEqual(["start tenant/room/alice/chat"]);
expect(events).toEqual(["start tenant/room/alice/chat", "start tenant/room/bob/chat"]);
expect(session.consumes(Path.from("room/bob/chat"))).toBe(1);
expect(session.consumes(Path.from("room/bob/video"))).toBe(0);

Expand Down Expand Up @@ -728,3 +748,23 @@ test("a request synced as it opens releases the watcher", async () => {
session.die();
origin.close();
});

test("a scoped session refuses blind requests outside its allowed paths", async () => {
const origin = new OriginProducer();
const scoped = origin.scope(Path.from("tenant"), new Path.Patterns([Path.Pattern.parse("room/*/chat")]));
const session = new FakeSession();
forwardAnnounced(session.session, scoped);
const allowed = origin.request(Path.from("tenant/room/bob/chat"));
const denied = origin.request(Path.from("tenant/room/bob/video"));
await settle();
for (const request of session.requests) request.stream.close(new Error("no discovery"));
await settle();
expect(allowed.active.peek()).toBeDefined();
expect(session.consumes(Path.from("room/bob/chat"))).toBe(1);
expect(denied.active.peek()).toBeUndefined();
expect(session.consumes(Path.from("room/bob/video"))).toBe(0);
allowed.close();
denied.close();
session.die();
origin.close();
});
Loading
Loading