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 @@ -53,7 +53,7 @@ route.announce();
- **One receive estimate per connection.** `connection.viewers` divides it among watched broadcasts, max-min fair by each viewer's ceiling, so several players on one pooled connection don't each select against the whole downlink. Holding a viewer requests PROBE, and the viewers' ceilings, summed, are the PROBE target a relay advertising `Increase` probes the downlink up to. `setTarget(0)` opts out. `watch`, `update`, and `setTarget` throw a `RangeError` when the ceilings or the target would pass `Viewers.MAX_TARGET` (`Number.MAX_SAFE_INTEGER`), the most a PROBE target carries.
- **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`, and syncs when the peer does, so a track added after `synced` is new at the source. 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. Groups are addressed by their start: `appendGroup(start)` opens one at a `Time.Timestamp`, in the track's timescale (rounded down), past every group the track holds, and declares the starts between it and the previous append skipped. The broadcast keeps nothing of an ended track, and a name always means the same content, so a track that replaces it keeps its starts moving forward, as its media time does. Starts are `bigint`, so every ID the wire carries fits, past 2^53 included: `track.createGroup(5n)`, `{ time: 10n }`. A frame's position in its group is its `index`, a `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.FillGroups` (`kind: "groups"`) from `await requests.requestedFill()`, shared by every reader missing it. `accept(start)` it into the cache and write the group's frames as first published, `dropGroups(start, end)` what the source lacks (starts 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. A range starting at a `time` before every cached group arrives as a `Track.FillLookup` (`kind: "lookup"`) instead: `accept` the group containing its `time` (a `bigint` in the track's timescale), or `close()` it and the reader falls back to the groups cached. This serves lite FETCH and lite-07 ranged subscriptions from the same track, as Rust's `requests()` does. A moq-transport FETCH is refused, so a moq-transport reader never reaches it.
- **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.FillGroups` from `await requests.requestedFill()`, shared by every reader missing it. `accept(start)` it into the cache and write the group's frames as first published, `dropGroups(start, end)` what the source lacks (starts 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. A range starting at a `time` no cached group places asks for the group containing it as a fill one key wide from that time, whose `floor` says how far below it that group may start: a handler that knows its groups only by key serves the key as any other, one with an index may `accept` the group below it or `dropGroups` the key when no group starts from the floor through the time, and the reader starts where the answer says, never where the cached groups happen to. A refusal fails the reader with its error until its ranges change. This serves lite FETCH and lite-07 ranged subscriptions from the same track, as Rust's `requests()` does. A moq-transport FETCH is refused, so a moq-transport reader never reaches it.
- **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 each frame carries `Time.Timestamp.unscaled(group.start)`, its group's key, which has no time: `as`, `asMillis`, and `asMicros` throw on it. A scaled timestamp on an untimed track, an unscaled one on a timed track, or another key throws `TimestampMismatch`. Omitting it means untimed, as in Rust. Nothing stamps a frame for you: the publisher passes the timestamp, and the `@moq/json` producers take it beside each value, as `update(value, at)`.
- **Durations and instants are `Clock` types.** Every duration (`maxAge`, `delay`, timeouts, RTT) is a `Clock.Duration` and every monotonic time a `Clock.Instant`, from [`@moq/clock`](./clock), which `@moq/net` re-exports as `Clock`: `maxAge: Moq.Clock.Duration.secs(30)`. Neither converts to a number implicitly; read one with an explicit unit, such as `asMillis()`. The wire still carries whole milliseconds, rounded up. Frame timestamps stay `Time.Timestamp`, a tick count at the track's timescale.
- **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.
Expand Down
14 changes: 2 additions & 12 deletions js/net/api/index.api.md
Original file line number Diff line number Diff line change
Expand Up @@ -695,15 +695,14 @@ export namespace Track {
priority?: number;
signal?: AbortSignal;
}
export type Fill = Track.FillGroups | Track.FillLookup;
export class FillGroups {
[Symbol.dispose](): void;
accept(start: bigint, info?: Track.Info): Group.Producer | undefined;
close(): void;
dropGroups(start: bigint, end: bigint): void;
readonly end: bigint;
readonly floor: bigint;
isWanted(key: bigint): boolean;
readonly kind: "groups";
get maxDelay(): Clock.Duration | null;
get order(): Track.Order;
get priority(): number;
Expand All @@ -713,15 +712,6 @@ export namespace Track {
wanted(): bigint | undefined;
wantedChanged(): Promise<bigint | undefined>;
}
export class FillLookup {
[Symbol.dispose](): void;
accept(start: bigint, info?: Track.Info): Group.Producer | undefined;
close(): void;
readonly kind: "lookup";
get maxDelay(): Clock.Duration | null;
get priority(): number;
readonly time: bigint;
}
export interface Finished {
abort(error: Error): void;
close(): void;
Expand Down Expand Up @@ -826,7 +816,7 @@ export namespace Track {
[Symbol.dispose](): void;
close(): void;
get name(): string;
requestedFill(): Promise<Track.Fill | undefined>;
requestedFill(): Promise<Track.FillGroups | undefined>;
}
export class Subscriber {
close(abort?: Error): void;
Expand Down
3 changes: 1 addition & 2 deletions js/net/src/cache.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,6 @@ import { Manual } from "@moq/clock/test";
import * as cache from "./cache.ts";
import { StreamCode, StreamError, TooFarBehind } from "./error.ts";
import { hooks, staleHole } from "./internal.ts";
import { groupsOf } from "./mock.ts";
import { Timestamp } from "./time.ts";
import { Producer as TrackProducer } from "./track.ts";

Expand Down Expand Up @@ -185,7 +184,7 @@ test("a forgotten stale run is asked of a fill", async () => {
const next = reader.recvGroup();
const asked: bigint[][] = [];
for (;;) {
const fill = groupsOf(await Promise.race([requests.requestedFill(), yieldNow().then(() => undefined)]));
const fill = await Promise.race([requests.requestedFill(), yieldNow().then(() => undefined)]);
if (!fill) break;
asked.push([fill.start, fill.end]);
}
Expand Down
Loading