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 bench/browser/page/transport.ts
Original file line number Diff line number Diff line change
Expand Up @@ -73,7 +73,7 @@ async function prepare(config: Transport): Promise<string> {
websocket: { enabled: false },
});
if (connection.transport !== "webtransport") throw new Error(`consumer negotiated ${connection.transport}`);
const request = origin.request(Moq.Path.from(config.path), { announced: true });
const request = origin.follow(Moq.Path.from(config.path));
cleanup.push(() => {
request.close();
connection.abort();
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, 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.
- **Follow restarts.** `origin.follow(path)` 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 it 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 it. Pass `{ epoch }` to pin one instance, which it waits for again after an end. `request(path)` instead 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)`, `request(path)`, or `follow(path)`, stops asking about a prefix 2s after nothing at or beneath it is watched, and asks again on reconnect. Every request and follower 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: requests subscribe blind through it, and followers 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 @@ -18,7 +18,7 @@ What you use it for, beyond what the concept page already describes:
- **An origin outlives the session.** Creating a broadcast returns an origin publication that controls its announcement and exposes the broadcast to fill. Standalone and Prepared fill producers cannot announce; only publishing the Prepared answer admits its publication. A reconnect announces existing publications again, and closing the session does not delete them.
- **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.
- **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 `follow(path)`. 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` 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.
Expand Down
2 changes: 1 addition & 1 deletion js/e2ee/src/transport.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -39,7 +39,7 @@ async function session(protocol: string) {
}

async function active(origin: Origin.Producer, path: Path.Valid): Promise<Broadcast.Consumer> {
const request = origin.request(path, { announced: true });
const request = origin.follow(path);
for (;;) {
const front = request.active.peek();
if (front) return front;
Expand Down
4 changes: 3 additions & 1 deletion js/net/api/index.api.md
Original file line number Diff line number Diff line change
Expand Up @@ -362,6 +362,7 @@ export namespace Origin {
announced(scope?: Path.Pattern, options?: Announce.Options): Announce.Consumer;
get closed(): Signals.GetPromise<Error | null>;
get discovery(): Signals.Getter<boolean | undefined>;
follow(path: Path.Valid, options?: Origin.RequestOptions): Origin.Requesting;
request(path: Path.Valid, options?: Origin.RequestOptions): Origin.Requesting;
}
export type Cost = bigint;
Expand All @@ -381,6 +382,7 @@ export namespace Origin {
consume(): Origin.Consumer;
createBroadcast(path: Path.Valid): Origin.Publication;
get discovery(): Signals.Getter<boolean | undefined>;
follow(path: Path.Valid, options?: Origin.RequestOptions): Origin.Requesting;
request(path: Path.Valid, options?: Origin.RequestOptions): Origin.Requesting;
requests(prefix: Path.Valid): Origin.Requests;
scope(root: Path.Valid, patterns: Path.Patterns): Origin.Producer;
Expand All @@ -402,7 +404,6 @@ export namespace Origin {
reject(err: Error): void;
}
export interface RequestOptions {
announced?: boolean;
epoch?: Epoch.Valid;
}
export class Requesting {
Expand All @@ -428,6 +429,7 @@ export namespace Origin {
readonly closed: Signals.GetPromise<Error | null>;
createBroadcast(path: Path.Valid): Origin.Publication;
readonly discovery: Signals.Getter<boolean | undefined>;
follow(path: Path.Valid, options?: Origin.RequestOptions): Origin.Requesting;
request(path: Path.Valid, options?: Origin.RequestOptions): Origin.Requesting;
requests(prefix: Path.Valid): Origin.Requests;
}
Expand Down
2 changes: 1 addition & 1 deletion js/net/bench/requests.ts
Original file line number Diff line number Diff line change
Expand Up @@ -34,7 +34,7 @@ for (const touched of ["watched", "unrelated"])
broadcastPublication.announce();
return broadcast;
});
const requests = Array.from({ length: followers }, () => origin.request(path, { announced: true }));
const requests = Array.from({ length: followers }, () => origin.follow(path));
await settle();
let current = broadcasts[0];
let unrelated: (typeof broadcasts)[number] | undefined;
Expand Down
2 changes: 1 addition & 1 deletion js/net/examples/discovery.ts
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ async function main() {
console.log("New stream available:", announcement.prefix);

// One request per path follows its publisher restarts until closed.
const request = origin.request(announcement.prefix, { announced: true });
const request = origin.follow(announcement.prefix);
request.active.subscribe((broadcast) => console.log(request.path, broadcast ? "live" : "offline"));
requests.set(announcement.prefix, request);
}
Expand Down
2 changes: 1 addition & 1 deletion js/net/examples/wait.ts
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ async function main() {

// Wait for a broadcast that may not exist yet. a plain `request` would subscribe blind and get reset
// if nobody is publishing the path; this waits for the announcement instead.
const broadcast = origin.request(Moq.Path.from("my-broadcast"), { announced: true });
const broadcast = origin.follow(Moq.Path.from("my-broadcast"));

const effect = new Effect();
effect.run((effect) => {
Expand Down
4 changes: 2 additions & 2 deletions js/net/src/announced.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -111,7 +111,7 @@ test("an origin handle resolves a local publish with no session attached", async
const origin = new OriginProducer();
const path = p("loopback");

const watch = origin.request(path, { announced: true });
const watch = origin.follow(path);
await settle();
expect(watch.active.peek()).toBeUndefined();

Expand Down Expand Up @@ -149,7 +149,7 @@ test("the local route wins over a blind request on a no-discovery origin", async
const detach = wireOf(origin).attach(false);
const broadcast = publish(origin, path);

const watch = origin.request(path, { announced: true });
const watch = origin.follow(path);
await settle();
expect(watch.active.peek()).toBeDefined();

Expand Down
2 changes: 1 addition & 1 deletion js/net/src/connection/connect.ts
Original file line number Diff line number Diff line change
Expand Up @@ -208,7 +208,7 @@ export interface ConnectProps {
* nothing.
*
* What the peer announces under the prefixes the origin's readers watch
* (`announced(scope)` or `request(path, { announced: true })`) appears in its table for
* (`announced(scope)`, `request(path)`, or `follow(path)`) appears in its table for
* the session's lifetime, consumable by path; nothing is asked until something watches,
* and the entries retract when the session dies. Pass the producer behind
* {@link ConnectProps.publish} to route both directions through one origin: a locally
Expand Down
20 changes: 10 additions & 10 deletions js/net/src/connection/forward.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -124,7 +124,7 @@ function record(stream: Announce.Consumer): string[] {
return events;
}

test("a plain request discovers an unwatched path and waits for its initial set", async () => {
test("a request discovers an unwatched path and waits for its initial set", async () => {
const origin = new OriginProducer();
const session = new FakeSession();
forwardAnnounced(session.session, origin);
Expand Down Expand Up @@ -209,17 +209,17 @@ test("a watch change reports only its prefix and the watches it covers", () => {
const unlisten = wireOf(origin).interests((prefix, wanted) => events.push(`${wanted ? "+" : "-"}${prefix}`));
const state = origin.consume();

const ab = state.request(Path.from("a/b"), { announced: true });
const ac = state.request(Path.from("a/c"), { announced: true });
const x = state.request(Path.from("x"), { announced: true });
const ab = state.follow(Path.from("a/b"));
const ac = state.follow(Path.from("a/c"));
const x = state.follow(Path.from("x"));
expect(events.splice(0)).toEqual(["+a/b", "+a/c", "+x"]);

// The broader watch opens first, then releases the ones it now covers; unrelated `x` is untouched.
const a = state.request(Path.from("a"), { announced: true });
const a = state.follow(Path.from("a"));
expect(events.splice(0)).toEqual(["+a", "-a/b", "-a/c"]);

// A watch beneath a covered prefix changes nothing.
const abd = state.request(Path.from("a/b/d"), { announced: true });
const abd = state.follow(Path.from("a/b/d"));
abd.close();
expect(events.splice(0)).toEqual([]);

Expand All @@ -237,12 +237,12 @@ test("a watch change reports only its prefix and the watches it covers", () => {
origin.close();
});

test("an announced request is a watch on its path", async () => {
test("a follower is a watch on its path", async () => {
const origin = new OriginProducer();
const session = new FakeSession();
forwardAnnounced(session.session, origin);

const request = origin.request(Path.from("room/alice"), { announced: true });
const request = origin.follow(Path.from("room/alice"));
await settle();
expect(session.open()).toEqual(["room/alice/**"]);
// Gated on the announcement, so nothing answers it blind meanwhile.
Expand Down Expand Up @@ -461,7 +461,7 @@ test("a refused announce request downgrades the session once, and later watches
const path = Path.from("room");
forwardAnnounced(session.session, origin);

const watched = origin.request(path, { announced: true });
const watched = origin.follow(path);
await settle();
expect(origin.discovery.peek()).toBe(true);
expect(watched.active.peek()).toBeUndefined();
Expand Down Expand Up @@ -495,7 +495,7 @@ test("a discovery failure under a live session retracts what it fed and answers
const path = Path.from("room");
forwardAnnounced(session.session, origin);

const watched = origin.request(path, { announced: true });
const watched = origin.follow(path);
await settle();
start(session.stream("room/**"), "room");
await settle();
Expand Down
6 changes: 3 additions & 3 deletions js/net/src/connection/migrate.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -76,7 +76,7 @@ const url = new URL("https://relay.example/room");
// Short enough to watch, long enough that a handover visibly overlaps the replacement.
const handover = Milli(200);

test("an empty GOAWAY migrates the announced request to the replacement session", async () => {
test("an empty GOAWAY migrates the follower to the replacement session", async () => {
const clock = new Manual();
const installed = clock.install();
const { dials, origin } = fleet();
Expand All @@ -93,7 +93,7 @@ test("an empty GOAWAY migrates the announced request to the replacement session"
// A session younger than this counts as redirected immediately and backs off first.
delay: { initial: Milli(1) },
});
const watched = consume.request(Path.from("cam"), { announced: true });
const watched = consume.follow(Path.from("cam"));

try {
await waitUntil(() => watched.active.peek() !== undefined);
Expand All @@ -113,7 +113,7 @@ test("an empty GOAWAY migrates the announced request to the replacement session"
expect(reload.status.peek()).toBe("connected");

// Without an epoch the replacement route is a new publisher instance.
// The announced request follows it while the old session finishes draining.
// The follower follows it while the old session finishes draining.
await elapse(clock, () => watched.active.peek() !== undefined && watched.active.peek() !== served);
expect(watched.closed.peek()).toBeUndefined();
await elapse(clock, () => drained.closed);
Expand Down
4 changes: 2 additions & 2 deletions js/net/src/connection/reload.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -206,7 +206,7 @@ async function waitUntil(pred: () => boolean): Promise<void> {
throw new Error("timed out waiting for condition");
}

test("an announced request follows the reconnect on the same handle", async () => {
test("a follower follows the reconnect on the same handle", async () => {
const original = globalThis.WebTransport;
const url = new URL("https://example.com/");

Expand All @@ -233,7 +233,7 @@ test("an announced request follows the reconnect on the same handle", async () =
delay: { initial: Milli(10), multiplier: 1, max: Milli(10) },
consume: clientOrigin,
});
const watched = clientOrigin.request(Path.from("late"), { announced: true });
const watched = clientOrigin.follow(Path.from("late"));

try {
await waitUntil(() => watched.active.peek() !== undefined);
Expand Down
Loading
Loading