From 73cc023f4eaee4b5d5bbd1b8bde0e82a0828eace Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Wed, 7 Oct 2026 13:50:10 -0700 Subject: [PATCH 01/12] docs: keep the site on features and correct publisher restarts The concept and library pages had grown into wire and API notes. Cut those back to the behavior a newcomer needs, and describe a moq or moqsink restart as a new publisher epoch. Co-authored-by: Grok 4.7 --- doc/bin/cli.md | 66 ++--- doc/bin/gstreamer.md | 24 +- doc/concept/hang.md | 28 +- doc/concept/index.md | 2 +- doc/concept/moq-lite.md | 394 ++++++--------------------- doc/concept/standard.md | 101 ++----- doc/concept/use-case/contribution.md | 16 +- doc/concept/use-case/index.md | 2 +- doc/lib/js/json.md | 53 ++-- doc/lib/js/net.md | 124 +-------- doc/lib/rs/index.md | 33 +-- doc/lib/rs/moq-audio.md | 149 ++-------- doc/lib/rs/moq-json.md | 43 +-- doc/lib/rs/moq-mux.md | 177 ++---------- doc/lib/rs/moq-net.md | 199 +------------- doc/lib/rs/moq-video.md | 310 ++++----------------- js/net/README.md | 2 +- rs/moq-e2ee/README.md | 2 +- 18 files changed, 334 insertions(+), 1391 deletions(-) diff --git a/doc/bin/cli.md b/doc/bin/cli.md index edd7ae84772..be7227ad38c 100644 --- a/doc/bin/cli.md +++ b/doc/bin/cli.md @@ -79,37 +79,17 @@ ends the import like any other rewind. The same flag on an elementary PID other continuity-counter gap, and the 33-bit timestamp rollover move no clock and declare nothing. FLV covers H.264 + AAC. -`import ts` samples each elementary stream's access-unit count once a second and -logs a stream whose count stopped advancing, with how long it has been quiet on -the program clock, once per silence. The mux can keep flowing, PCR and -continuity intact, around a PID that delivers nothing, and no transport check -downstream sees it. A sparse stream such as SCTE-35 goes quiet between cues, so -the line reports rather than alarms; `Import::stats` carries the same counters -for a caller that sets its own limit. - -`import ts` also counts the ETSI TR 101 290 errors of the feed it receives, at -that standard's fixed limits: `TS_sync_loss`, `Sync_byte_error`, `PAT_error`, -`Continuity_count_error`, `PMT_error`, `Transport_error`, `CRC_error` (PAT and -PMT), `PCR_repetition_error`, `PCR_discontinuity_indicator_error` and -`PTS_error`. They are cumulative, logged with their totals in the sample after -any of them moves, and carried on `Import::stats` stream-wide and per PID. They -change nothing that is published. They grade the stream as it reached the -importer, not the wire a receiver sees downstream, and the PCR checks grade -consecutive PCR values rather than arrival times, so they speak for the encoder -and not for the network in front of the importer. Table, PCR and PTS intervals -run on the program clock, which starts at the first PCR after the PMT. -`PID_error` is covered, more strictly, by the access-unit counts above. -`PCR_accuracy_error` is not measured. +`import ts` logs a video or audio PID that stops delivering access units, and +counts ETSI TR 101 290 errors on the feed it receives. A sparse PID such as +SCTE-35 goes quiet between cues, so that line reports rather than alarms. +Neither check changes what is published, and the PCR checks grade the encoder's +timestamps rather than the network in front of the importer. A corrupt media packet, malformed PES header, or damaged codec access unit is -refused whole and counted in the PID's cumulative `damaged` counter, beside -`resyncs`, `discarded`, and `unconfirmed`. Ingest continues on every other PID. -Video closes its group at the break and resumes at its next keyframe, as it does -after a continuity-counter gap: the pictures in between may reference the lost -one, so they are dropped rather than decoded with artefacts. Each break freezes -video for up to one GOP. The shared TS stats log reports each counter increase, -including at the end of input. Publishing, catalog, and clock errors still end -the import. +dropped for that PID. Ingest continues on every other PID. Video closes its +group at the break and resumes at its next keyframe, so each break freezes +video for up to one GOP. Publishing, catalog, and clock errors still end the +import. MPEG-TS import takes one program. A multi-program stream is refused before anything is published, naming its programs, rather than merged onto one clock; @@ -211,17 +191,6 @@ is scheduled against where the speaker actually is. While video owns the clock, pulls playback forward, so a late start catches up to live instead of staying behind it. Once the speaker owns the clock, video follows the speaker instead. -Video receives encoded frames independently of decoding, so a tune-in burst can -update that clock even while the window is waiting for its first picture. -Encoded video is retained within the delay budget with byte accounting; a skip -resumes at a keyframe. Decoding starts 100 ms before the earliest picture still -owed is due, so B-frame reordering and pictures the decoder holds back are -covered however deep they go. The window holds at most three decoded pictures; -a larger decoder batch waits for room rather than pushing out pictures not yet -shown. A stalled window loses its oldest picture once a newer one is due, -instead of blocking reception. The configured delay therefore does not turn -into seconds of raw video surfaces. - Each role follows the catalog for as long as it lasts. Each decoder starts at the newest cached group, including when a rendition is reopened, so playback does not replay the retained backlog. A publisher that retires the rendition @@ -388,13 +357,18 @@ moq --connect https://relay.example.com/anon \ -- export --broadcast event.hang archive file:///recordings/event ``` -## Redundant publishers +## Publisher runs + +Each publishing command (`import`, `transcode`, archive replay, HLS or WebRTC +ingest) announces a fresh [publisher epoch](/concept/moq-lite#publisher-epochs) +for that process. A restart is a new run: viewers move to it instead of waiting +for its group numbers to catch the old sequence. Reconnects inside one process +keep the epoch, so a blip resumes mid-group. -Two publishers of the same broadcast name are interchangeable sources: -relays hold both routes and fail over between them mid-group. They must -produce identical tracks with aligned groups. A restarted encoder is the same -broadcast too, so one whose groups restart from 0 must publish under a new -name, or viewers wait for its sequence to catch up. +Each process mints its own epoch, so the newer run takes the name and viewers +of the older run move to it. Mid-group failover needs both routes to carry the +same epoch. The CLI keeps one epoch for the life of the process and does not +share it with another process. ## Cluster diff --git a/doc/bin/gstreamer.md b/doc/bin/gstreamer.md index abcc8449afa..f8da91af426 100644 --- a/doc/bin/gstreamer.md +++ b/doc/bin/gstreamer.md @@ -62,21 +62,15 @@ restarted pipeline at once instead of stalling on the old one; reconnects within a run keep it. `connection-stats` is null while disconnected. While connected it is a -`GstStructure` named `moq-connection-stats` containing the transport metrics -available from the active backend. Missing metrics are omitted rather than -reported as zero. Its possible `guint64` fields are `rtt-us`, -`estimated-send-rate-bps`, `estimated-recv-rate-bps`, `bytes-sent`, -`bytes-received`, `bytes-lost`, `packets-sent`, `packets-received`, and -`packets-lost`. Poll the property for current counters; property notification -marks connection and disconnection edges. - -`sessions` is a `GstStructure` named `moq-sessions` with `guint64` fields -`started` and `ended`, the cumulative connect and disconnect counts for the -current element session in the same shape as the relay's sessions track. One -read returns both counters from the same instant, so `started - ended` is 1 -while connected and 0 otherwise, reconnects are `started - 1` once `started` -is at least 1, and a rate is the delta over any window you sample. Unlike -`status`, a connection that drops before you poll still moves both counters. +structure of the transport counters the active backend has (RTT, send and +receive estimates, bytes, packets, loss). Missing ones are omitted rather than +reported as zero. Poll it for the current values; property notification marks +connect and disconnect. + +`sessions` is the cumulative connect and disconnect counts for this element, +in the same shape as the relay's sessions track. One read returns both from +the same instant, so their difference is 1 while connected. Unlike `status`, a +drop you did not poll still moves both counters. Set `encoder=true` on audio and video pads a local encoder feeds (`x264enc`, `opusenc`, ...). The pad then measures how late each frame reaches diff --git a/doc/concept/hang.md b/doc/concept/hang.md index 51ddd0d346e..3e839d933b2 100644 --- a/doc/concept/hang.md +++ b/doc/concept/hang.md @@ -14,7 +14,7 @@ browser can decode it directly. The spec is broadcasts live at ``, derived from the credential and a semantic name such as `foo.hang`, and the [epoch](/concept/moq-lite#publisher-epochs) on their route identifies each publisher run. The path exposes no format or protection marker; the -payloads follow [moq-e2ee](/draft/moq-e2ee). +payloads follow [moq-e2ee](/draft/moq-e2ee). See [Encryption](#encryption). ## Catalog @@ -103,6 +103,10 @@ document would silently discard everything but the last payload: - `snapshot` is lossy. Each group supersedes the previous one, so a consumer reads only the newest. A JSON track may follow the first frame with merge-patch deltas. - `stream` is an ordered log: one payload per frame, all in a single group that is never rolled. Retention is still bounded by the group cache, and a consumer that falls behind fails the read rather than silently resuming mid-log. +A sliding window, a bounded log a reader can join in the middle, is a framing +in [`moq-json`](/lib/rs/moq-json) rather than a catalog mode. Both ends opt +into it on a raw track. + The rest is descriptive: `compression` (`deflate`, the same group-scoped `deflate-raw` the catalog uses), `schema` on a JSON track, `mime` on a binary one, `bitrate`, `jitter`, and `delay` with the same meaning as for media, plus @@ -111,13 +115,9 @@ only from payloads stamped with their capture time on the broadcast clock. A consumer that doesn't recognize a `mode` or `compression` ignores that track and round-trips it verbatim. -In Rust the catalog owns the lifetime: `catalog.json_stream(track, config)` (or -`json_snapshot` / `binary_snapshot` / `binary_stream`) writes the entry and -retracts it when the producer drops. Read the config from `catalog.json.tracks` -or `catalog.binary.tracks`, then pair its name and config with -`moq_mux::catalog::Entry::new` to subscribe. In C, `moq_publish_json_*` and -`moq_publish_binary_*` do the same, retracting on `_finish`. In the browser, read the same map, -subscribe by name, and hand the track to `@moq/json` or `@moq/flate`. +The catalog entry lives as long as its producer: dropping it retracts the +track. [`moq-json`](/lib/rs/moq-json) and [`moq-flate`](/lib/rs/moq-flate) (and +their TypeScript twins) are what read and write the payloads. An application with its own per-track fields can list a data track in its own root section instead, nesting the JSON or binary config in a `config` field @@ -160,6 +160,18 @@ The `description` field carries out-of-band codec setup (an `avcC` box for H.264). When it is absent, the parameter sets ride inline before each keyframe, which is what `avc3`/`hev1` tracks do. Decoders should handle both. +## Encryption + +[moq-e2ee](/draft/moq-e2ee) encrypts groups, datagrams, and track names so a +relay forwards ciphertext and never sees a content key. The application +distributes the credential on its own channel. Each publisher run binds that +credential to its [epoch](/concept/moq-lite#publisher-epochs), which derives +the track names and keys for that run alone. A restart is a new epoch, and +nothing from the previous one decrypts. The broadcast path is an opaque name +derived from the credential and a semantic name such as `foo.hang`; it carries +no format marker. `moq-e2ee` is the Rust implementation. Relays need no +configuration to carry it. + ## Your own format hang is a convention, not a requirement. If you control both ends, publish diff --git a/doc/concept/index.md b/doc/concept/index.md index fae0751a116..b8869a965be 100644 --- a/doc/concept/index.md +++ b/doc/concept/index.md @@ -35,7 +35,7 @@ watched at 100 ms by one viewer and 10 s by another. - [Transport](/concept/transport): why QUIC, and the WebTransport, WebSocket, raw QUIC, and iroh paths onto it. - [moq-lite](/concept/moq-lite): the pub/sub protocol, discovery, path patterns, subscriptions, and congestion behavior. -- [hang](/concept/hang): the media catalog, containers, and how to extend both. +- [hang](/concept/hang): the media catalog, containers, encryption, and how to extend both. - [Audio jitter](/concept/audio-jitter): how a receiver sizes its audio playout target from arrival timing. - [Stats](/concept/stats): the traffic counters a relay publishes as broadcasts, and how to read them. - [Standards](/concept/standard): how this relates to the IETF moq-transport, MSF, LOC, and this project's own drafts, including [e2ee](/draft/moq-e2ee). diff --git a/doc/concept/moq-lite.md b/doc/concept/moq-lite.md index ff5e6d433c1..574874f7637 100644 --- a/doc/concept/moq-lite.md +++ b/doc/concept/moq-lite.md @@ -12,6 +12,11 @@ against any moq-transport relay (including implement in an afternoon. The wire spec is [draft-lcurley-moq-lite](/draft/moq-lite). +Rust and TypeScript speak moq-lite 01 through 06 and moq-transport drafts 14 +through 22. Clients offer `moq-lite-06` first. moq-lite 07 is still in progress +(`moq-lite-07-wip`, and only when both sides enable it). It is the version that +carries [publisher epochs](#publisher-epochs). + ## Terminology | moq-lite | Meaning | moq-transport name | @@ -24,62 +29,6 @@ implement in an afternoon. The wire spec is | **Frame** | A sized chunk of bytes. | Object | | **Datagram** | One unreliable frame sent as a QUIC datagram instead of a group. | Datagram | -## Session setup - -A dedicated ALPN selects the wire version for moq-lite 03 and newer. The -legacy `moql` ALPN negotiates moq-lite 01 or 02 via `SETUP`. In moq-lite 05 -and newer, each side also sends a `SETUP` message with its capabilities. -Streams that depend on negotiated capabilities wait for the peer's `SETUP`; -everything else proceeds immediately. A Rust server holds unidirectional streams -that arrive before the client's `SETUP`, since it routes by the path in `SETUP`. A second Setup Stream closes the session -with `PROTOCOL_VIOLATION`. -Rust and TypeScript speak moq-lite 01 through 06 and moq-transport drafts -14 through 22. Clients offer `moq-lite-06` first by default. moq-lite 07 is -still in progress: it negotiates as `moq-lite-07-wip`, and only when both -sides explicitly enable it. moq-lite 07 also switches every varint from QUIC's -two-bit length prefix to moq-transport's leading-ones form, so values up to 127 -take one byte instead of up to 63, and the range widens from 62 to 64 bits. -A relay cannot forward a value past 2^62 - 1 to an older peer, so it fails -that subscription or group and keeps the session. - -## Subscription completion - -On moq-lite 07, `SUBSCRIBE_END` counts the group streams opened for the -subscription. Rust and TypeScript stop waiting for missing streams once that -many headers have arrived; skipped group sequences add no wait. A stream whose -header arrived is always read to its end before the subscription completes. - -A stream reset before its header arrived cannot be counted, so the subscriber -still allows a grace period for late streams. The grace uses the subscription's -nonzero effective maximum age, or one second when no maximum age is set. -moq-lite 05 and 06 instead account for group sequences using received headers, -datagrams, and `SUBSCRIBE_DROP`, from the start group the subscription last -asked for. A lost datagram is not owed, but its hole waits out the grace like a -lost stream. - -From moq-lite 06, an end that contradicts the groups received aborts the track: -a group at or past `SUBSCRIBE_END`, or a `SUBSCRIBE_END` below a group already -received. moq-lite 05 specified an inclusive end, so there it only drops that -group or the early boundary. - -On moq-lite 07, a subscription ends with both sides' FIN. The subscriber sends -its FIN after settling the tail. A publisher closing gracefully waits for that -FIN or a reset before closing the connection, within its close deadline. -moq-lite 05 and 06 retain transport acknowledgement based draining. - -## Group reads across failover - -Rust origin readers can keep reading an in-flight group after its source fails. -A group reader waiting on a replacement copy subscribes to it from the frame it -needs, even when the caller is not polling for the next group, and holds that -subscription until the group ends. If that copy refuses the subscription, the -read ends with an error. The copy's declared start says whether the group is -still coming, so a newer group overtaking it on the wire does not end the wait. -A copy that declares no start (a local track) and has advanced past the group -ends the read with an error. This also applies when waiting for the group's -completion; no FETCH is issued. A replacement that later drops the group it is -serving still needs SUBSCRIBE\_DROP support to resolve that wait. - ## Discovery A session can ask for announcements matching a path prefix. The peer replies @@ -90,133 +39,83 @@ each other. An announcement is a **route**: a claim that broadcasts at a path prefix, and every path beneath it, can be served. By convention a publisher announces each -broadcast's exact path, so subscribers enumerate broadcasts by listing routes, -but a service can announce one short prefix and serve whatever is requested +broadcast's exact path, so subscribers enumerate broadcasts by listing routes. +A service can instead announce one short prefix and serve whatever is requested beneath it, advertising capability without enumerating inventory. A route is -always a prefix, on every wire version and on moq-transport alike; a service -that serves only some of the paths beneath its prefix refuses the rest as they -are requested. Each route carries the chain of relay identities it passed -through, which is how forwarding loops are caught, and a cost, which is how a -subscriber picks among several routes to the same broadcast. A route may also -carry a [publisher epoch](#publisher-epochs), which says which routes serve the -same bytes. A hop of 0 is -the anonymous mark and travels the chain unchanged; when it is the first hop, a -relay puts a random ID, fresh per connection, in front of it. A route that passed through an -anonymous hop at any depth ranks below every fully identified route, whatever -the costs say; among anonymous routes, cost keeps ordering. - -On moq-lite 07, an announcement may copy the head of its path and the tail of -its relay chain from one still live on the same stream, so many broadcasts -from a few origins behind the same relays stop repeating those bytes. Rust -compresses when it helps; TypeScript decodes it but always sends literally. - -A broadcast exists only while it is announced, for consumers in the same -process and across a session alike: one that is created but never announced -can be neither discovered nor requested. A broadcast published locally -competes with remote routes to its path like any other route: a newer epoch -beats it whatever the cost, so a local broadcast without an epoch loses to any -remote route that carries one, and among equal epochs it wins a cost tie. -Retracting a route (an unannounce, or the peer's `ANNOUNCE_END`) -stops new requests from resolving through it but leaves subscriptions already -in flight alone: each track runs to its own end or failure, or until its last -subscriber leaves, which cancels it upstream. On moq-lite 05 and -newer, a clean end requires `SUBSCRIBE_END` before the publisher's FIN. A FIN -without that declaration fails the subscription with `ProtocolViolation`; older -moq-lite versions use FIN alone. moq-transport requires `PUBLISH_DONE` before FIN. -moq-transport sessions behave the same when a namespace is withdrawn. A route -update that changes its first hop, the original publisher, is not a retraction: -subscriptions in flight carry on through it. - -A graceful session close withdraws its announcements and waits up to one -second for transport acknowledgement before disconnecting. Rust uses -`session.close().await`; JavaScript uses `await connection.close()` on an -established connection. An abort skips the withdrawal and ends immediately. -The source origin remains usable by other sessions. Acknowledgement confirms -transport delivery, not that the peer application has finished processing it. -IETF drafts 14 through 16 send their withdrawals on the shared control stream -without waiting, since it has no FIN to acknowledge. +always a prefix. A service that serves only some of the paths beneath it +refuses the rest as they are requested. Announcements are hints; the request is +what decides. + +Each route carries the chain of relay identities it passed through, which is +how forwarding loops are caught, and a cost, which is how a subscriber picks +among several routes to the same broadcast. It may also carry a +[publisher epoch](#publisher-epochs), which says which routes serve the same +bytes. A hop of 0 is the anonymous mark and travels the chain unchanged; when +it is the first hop, a relay puts a random ID, fresh per connection, in front +of it. A route that passed through an anonymous hop at any depth ranks below +every fully identified route, whatever the costs say. + +A broadcast exists only while it is announced, in the same process and across +a session: one that is created but never announced can be neither discovered +nor requested. Retracting a route stops new requests from resolving through it +and leaves subscriptions already in flight alone until each track ends or its +last subscriber leaves. A graceful session close withdraws its announcements +and waits up to one second for them to be delivered. An abort skips that. ### Publisher epochs -A route may carry an `Epoch`: a UUIDv7 naming the publisher instance behind it, -ordered newest last, with its creation time available as `Epoch::time()` in -Rust or `Epoch.time(epoch)` in TypeScript. A path and an epoch name one -broadcast. The path never changes, so authorization, patterns, and hidden -names work exactly as without one. - -- **Publishing**: the epoch is whatever the route names, and nothing is minted - for you. A publisher mints one per run (`Epoch::mint()` with - `Route::with_epoch`, or `announce({ epoch: Epoch.mint() })`), so a restart is - a new broadcast. Replicas of the same content announce the same one. A route - without an epoch, such as a prefix claim, names no instance. -- **Resolution** ranks the newest epoch first among routes at the same prefix, - ahead of cost, and a route without an epoch last. Newest means the latest - UUIDv7 timestamp, so ordering instances minted on different hosts trusts - their clocks: a restart on a host whose clock runs behind loses to the old - instance until that one retracts. -- **Re-pricing**: announcing again (or `update` on a dynamic route) replaces - the whole route, epoch included. Start from the current route, as in - `broadcast.route()` or `dynamic.route()`, and change the cost, or the update - names another instance. -- **Resume**: a subscription moves between routes with the same epoch without a - seam, continuing from the first frame it lacks. A route without an epoch - names no instance, so its subscriptions stay on that route (a transcoder - claim stays on the worker that first served it) and end when it goes. -- **Replacement**: when a newer epoch wins the path, subscriptions to the old - one end with `Unroutable`, even ones in flight, and announcement streams see - the old route end and the new one start. Clients re-request and get the new - broadcast instead of stalling on the old. - -The epoch travels on moq-lite 07 in `ANNOUNCE_START`, and relays fill it into -the `TRACK`, `SUBSCRIBE`, and `FETCH` they send upstream; a publisher refuses a -request naming another epoch. Older moq-lite versions and moq-transport cannot -carry it: their routes have no epoch, so they keep their subscriptions on one -route and see a replacement as an ordinary end and start at the same path. In -a mixed deployment, where the same content reaches a relay over both an older -link (no epoch) and a moq-lite 07 link (with one), the epoch-carrying route -supersedes the other each time it appears, so a flapping moq-lite 07 link cuts -the viewers resolved through the older one. +A route may carry an epoch: a UUIDv7 naming the publisher instance behind it. +A path and an epoch name one broadcast. The path never changes, so +authorization and hidden names work exactly as without one. + +- **One instance, one epoch.** A publisher mints an epoch per run. Replicas of + the same content announce that same epoch. A prefix claim, and any route + without an epoch, names no instance. +- **Newest wins.** Among routes at the same prefix, the newest epoch ranks + first, ahead of cost, and a route without an epoch ranks last. Newest means + the latest UUIDv7 timestamp, so hosts with skewed clocks can lose a restart + until the old instance retracts. +- **Same epoch resumes.** A subscription moves between routes with the same + epoch without a seam, continuing from the first frame it lacks. A route + without an epoch keeps its subscriptions until that route goes, which is how + a transcoder claim stays on the worker that first served it. +- **A newer epoch replaces.** Subscriptions to the old instance end, and + clients re-request the path to get the new broadcast. That is how a restarted + encoder, whose group numbers start over, takes the name instead of stalling + viewers on the old sequence. + +The epoch travels on moq-lite 07. Older moq-lite versions and moq-transport +cannot carry it, so their routes have no epoch and a replacement looks like an +ordinary end and start at the same path. In a mixed deployment the +epoch-carrying route supersedes the one without each time it appears, so a +flapping moq-lite 07 link cuts viewers that resolved through the older link. + +`moq` and `moqsink` mint a fresh epoch per run. Reconnects inside that run keep +it. See [Clustering](/bin/relay/cluster) for how a relay uses this. ### Hidden broadcasts A path segment starting with `.` hides a route from discovery, the way a dotfile hides from `ls`. A platform publishes its own broadcasts there (relay -stats under `.stats/`) without them turning up in an app that lists -everything and plays what it finds. Only segments -below the requested prefix count: listing the root skips `.stats/node`, but -listing `.stats` shows `node`. A `.` elsewhere in a segment (`catalog.pro`) is -part of the name. - -Hiding narrows discovery and nothing else. Subscribing to a hidden path by -name works without asking, and tokens authorize it like any other path. To -list hidden routes too, opt in per announce request: - -```rust -let announced = origin.consume().with_hidden(true).announced(); -``` - -```typescript -const announced = connection.announced(Path.Pattern.all(), { hidden: true }); -``` - -On the wire, moq-lite 07 (`moq-lite-07-wip`, opt-in only) carries the opt-in -on each announce request, and -moq-transport carries it as a `SUBSCRIBE_NAMESPACE` parameter once the peer's -`SETUP` says it understands one ([hidden](/draft/moq-hidden)). An older MoQ Lite peer -never opts in, so it never discovers hidden routes. -IETF peers that omit the MoQ Hidden setup option receive all authorized -namespaces, including dot-prefixed namespaces. Peers that declare it opt in -per subscription; a prefix naming the dot segment itself also lists its -children. Rust sessions always opt in -on the wire and filter per local reader, so a relay mirrors everything and -each consumer decides. +stats under `.stats/`) without them turning up in an app that lists everything +and plays what it finds. Only segments below the requested prefix count: +listing the root skips `.stats/node`, but listing `.stats` shows `node`. + +Hiding narrows discovery and nothing else. Subscribing to a hidden path by name +works, and tokens authorize it like any other path. Listing hidden routes is an +explicit opt-in on the announce request. On moq-transport that opt-in is the +[hidden](/draft/moq-hidden) extension; a peer that never declares it receives +every authorized namespace, dot-prefixed ones included. ## Path patterns -Rust's `moq_net::Pattern` and TypeScript's `Path.Pattern` from `@moq/net` -describe sets of literal paths. Patterns match the whole path. `room` matches -only `room`, while `room/**` matches `room` and every descendant. Segments are -separated by `/`: +Patterns describe sets of literal paths. They are how a token scopes what a +session may publish and subscribe to, and how a consumer filters the +announcements it is told about. They never travel as announcements: the wire +carries prefixes, and each side filters locally. + +A pattern matches the whole path. `room` matches only `room`, while `room/**` +matches `room` and every descendant. Segments are separated by `/`: | Segment | Matches | | --- | --- | @@ -226,88 +125,21 @@ separated by `/`: | `pre*suf` | One segment with that prefix and suffix, without overlapping them. | | `**` | Zero or more segments. | -A pattern may contain at most 32 segments and one `**`. Leading, trailing, -or repeated separators are invalid pattern syntax. The empty pattern matches -the empty path. There is no escape syntax for a literal `*`. -Construction normalizes adjacent `*` and `**`: `*/**` prints as `**/*`, -so equivalent wildcard placements have the same identity. - -Patterns never travel as announcements. `origin.dynamic(prefix, route)` -advertises a prefix: the call claims that `prefix` and every path beneath it -*can* be served, not that any exist. A route is a capability, not an inventory: -a subscriber must not treat a prefix as a concrete broadcast name. Use -`publish(path, route)` when the path is known; use -`dynamic` when the set of paths is not, and refuse the requests you will not -serve. A pattern lives in two places: the token, which scopes what a session -may publish and subscribe to, and a local filter a consumer applies to the -prefixes it is told about. +A pattern may contain at most 32 segments and one `**`. There is no escape for +a literal `*`. The empty pattern matches the empty path. A subscriber watching under a root sees advertisements named relative to that -root. The pattern scope filters which prefixes are visible without changing a -route's prefix. When several routes advertise one prefix, each reader sees the -best route its scope can use, so a cheaper route scoped elsewhere never hides -it. Announce events carry the covered path, captures, and what -happened to it: Rust `announce::Event::{Start, Update, End}`, each -holding an `announce::Announce { prefix, captures: Option>, route }`, -and TypeScript `Announce.Event`, whose `kind` is `"start"`, `"update"`, or -`"end"` alongside the same `Announce.Announce` fields. An update is a -reprice in place. Captures are present when the announced prefix pins every -wildcard in the most-specific matching scope member. The Rust consumer is a -`Stream` and the TypeScript one an async iterable. Neither marks when the -routes live at subscribe time have all arrived: an origin merges many sessions -that connect and reconnect independently, so drive loading and offline UI from -the connection status instead. - -Announcements are hints; requests are the authority. When a subscriber asks -for a covered path the advertiser will not serve, the advertiser refuses that -request rather than narrowing the claim, and no message narrows a route. Token -scope is any pattern union; the session asks for each member's literal head on -the prefix-only wire and filters locally. In Rust and TypeScript, -`origin.scope(root, patterns)` narrows the handle's permissions and presents paths -relative to `root`. Nested scopes intersect with their parent. In Rust, -`origin.mount(at, target)` reads the subtree at `at` from `target` instead: a -request for `at/rest` joins the one front at `target/rest`, announcements under -`target` present under `at`, the handle's patterns still authorize `at/rest`, -and nothing is published beneath `at`. Mounts never chain: a mount point that -overlaps another mount's point or any target, its own included, is refused. A session receiving -into that scoped origin asks for the literal heads of its allowed patterns, -coalescing duplicate or nested heads. An unscoped origin still asks for the empty -prefix, covering every namespace. These subscriptions include hidden routes; -each local announcement reader decides whether to show them. - -```typescript -import { Path } from "@moq/net"; - -const scope = Path.Pattern.parse("room/**"); -scope.matches("room/alice"); // true -scope.contains(Path.Pattern.parse("room/camera-*")); // true -scope.overlaps(Path.Pattern.parse("*/alice")); // true -scope.rebase("room").toJSON(); // ["**"] -Path.Pattern.parse("camera-*").rooted("room").text; // "room/camera-*" -``` - -`contains` asks whether every path matched by the other pattern is allowed by -this one. `overlaps` asks whether they share any matching path. `rebase` returns -the matching paths relative to a literal root; `rooted` places a pattern beneath -that root and rejects results exceeding the segment limit. Rebasing can require -several patterns: `**/a` rebased at `a` yields both `""` (the root itself) and -`**/a` (deeper paths ending in `a`). - -`Patterns` is a union that removes members contained by another member and -orders the remaining members canonically. Its containment check requires one -member to cover the entire requested pattern; it does not combine several -members to prove joint coverage. Equality compares those reduced members. -Use `specificity` to rank structural constraints when selecting rules, and -`contains` to check whether a rule stays within a scope. +root. When several routes advertise one prefix, each reader sees the best route +its scope can use. ## Subscriptions A subscriber names a broadcast and track. Delivery starts at the oldest group it can still use, which at the default budget is the latest one, so every group must begin at a point a fresh subscriber can decode from (a keyframe, a full -JSON snapshot). Groups can be fetched by sequence number too, optionally -bounded to a range of frames, which is how the [HLS gateway](/bin/hls) and the -relay's [HTTP fetch](/bin/relay/http) serve history. +JSON snapshot). Groups can also be fetched by sequence number, which is how the +[HLS gateway](/bin/hls) and the relay's [HTTP fetch](/bin/relay/http) serve +history. Each subscription carries the knobs that decide behavior under congestion: @@ -323,40 +155,17 @@ anything on its own. Both ends apply it: the publisher skips a group rather than sending it, and the subscriber skips it again as it reads, since the publisher only ever sees the most tolerant budget across its subscribers. -A route failover is invisible to max delay: a group open across the change carries -on from the new route at the frame where the old one stopped, and a group only a -replaced route that went quiet still holds is given up once it falls a full -budget behind the new route's live edge. A successor group with no timestamp -leaves the preceding group's reach unbounded until its first frame arrives; if -it is dropped first, the next group takes its place. - A relay cancels its upstream subscription once nobody subscribes, but keeps its copy of the track for 30 seconds after the last reader leaves, so a returning -reader or the next fetch finds its cache. That copy is not live meanwhile: -readers get nothing from its cache until the source answers again, since how -stale it is cannot be told. lite-07 and moq-transport answer with their largest -position, and older lite versions are asked from the head of the newest cached -group, so their first frame says where their feed is. A feed that has moved on -past everything cached leaves the cache below it to fetches. +reader or the next fetch finds it. That copy is not live meanwhile: readers get +nothing from it until the source answers again. The publisher may declare a retention window per track. Omission sets no limit; -zero keeps only the live edge. The origin cache ceiling and cache pool may still -evict content sooner. Relays preserve the publisher's declaration rather than -substituting a local default. Media tracks explicitly use 30 seconds so a -segmented egress can still find its segments. - -IETF carries this value as MAX\_CACHE\_DURATION, received on every supported draft -and sent from draft 17 onward. A relay reads it from FETCH\_OK as well as SUBSCRIBE\_OK, so a track it -only fetches still learns its window. Drafts 14–16 remain receive-only for compatibility -with older implementations. This is an approximate mapping: IETF measures wall -time, while the publisher's retention window uses media timestamps and always keeps the newest group. -EXPIRES describes subscription lifetime and does not set retention. - -Lite-07 encodes a finite limit as milliseconds plus one, with zero meaning no limit. -Lite-05/06 send no limit as `2^53 - 1` milliseconds so older JavaScript readers can -parse it. New readers treat every value at or above that boundary as no limit; -older readers treat it as a finite window of approximately 285,000 years. Their -timer cap schedules periodic age checks and does not shorten that window. +zero keeps only the live edge. Relays preserve that declaration, and may still +evict sooner under their own cache ceiling. Media tracks explicitly use 30 +seconds so a segmented egress can still find its segments. Retention uses media +timestamps and always keeps the newest group. IETF carries the same idea as +`MAX_CACHE_DURATION`, measured in wall time, which is only an approximate match. Put together, a conference might use: @@ -379,10 +188,12 @@ fallback, so a datagram that doesn't fit isn't delivered that way. Compared with moq-transport: no request IDs (a stream per request instead), no push (subscribers always ask), fetches within a single group only, no -sub-groups (use a track per SVC layer), no gaps in object numbering, no per-object metadata -(encode it in the payload), no pausing (unsubscribe instead), and UTF-8 names -instead of byte arrays. When a peer negotiates moq-transport the implementation -still enforces this simpler model, faking or refusing the rest. +sub-groups (use a track per SVC layer), no gaps in object numbering, no +per-object metadata (encode it in the payload), no pausing (unsubscribe +instead), and UTF-8 names instead of byte arrays. When a peer negotiates +moq-transport the implementation still enforces this simpler model, faking or +refusing the rest. The [standards](/concept/standard) page lists the limits a +peer actually observes. | Client | Relay | Works | | --- | --- | --- | @@ -390,28 +201,3 @@ still enforces this simpler model, faking or refusing the rest. | moq-lite | moq-transport | yes | | moq-transport | moq-lite | without moq-transport-only features | | moq-transport | moq-transport | depends on the implementations | - -## Protocol errors - -Session close codes and stream reset codes use separate registries: session code 0 -is a clean close, while stream code 0 is an internal error. Rust preserves received -codes as `moq_net::Error::Session(SessionError)` or `Error::Stream(StreamError)`; -JavaScript exposes `SessionError` and `StreamError`. Match the registry before -interpreting the number. Native bindings expose scope, code, kind, and a diagnostic -message; unknown and application codes retain their numeric value. Transport -failures without a protocol code remain separate. A deliberate local close ends -received tracks cleanly after their delivered groups; a peer close ends tracks -and open group readers with the session error. - -## Local read limits - -Group ranges name which groups a reader may deliver. In Rust, -`set_groups(2..=5)` includes group 5, while `set_groups(2..5)` excludes it. -TypeScript spells the endpoints explicitly: -`reader.setGroups({ start: { included: 2 }, end: { included: 5 } })`. - -Changing these local limits preserves read progress. Raising the start skips -lower groups; lowering it never rewinds the reader. Raising or removing the -end cap makes unread buffered groups available again. These local limits do -not change upstream demand; subscription preferences control that separately. -The wire encoding is unchanged. diff --git a/doc/concept/standard.md b/doc/concept/standard.md index 9b4730a7953..6b222a2a1ad 100644 --- a/doc/concept/standard.md +++ b/doc/concept/standard.md @@ -18,84 +18,20 @@ with it, while shipping a simpler profile you can use today. ## moq-transport -moq-transport is the full protocol: namespaces (broadcasts) that several -publishers may share, sub-groups for layered codecs, object-level metadata and -gaps, `FETCH` for ranges of history, joining fetches, `PUBLISH` push, and +moq-transport is the full protocol: namespaces that several publishers may +share, sub-groups, object metadata and gaps, ranged `FETCH`, push, and pausing. moq-lite keeps the parts a CDN can implement without conflicts and maps everything else to "not supported" or a harmless equivalent. The -[moq-lite page](/concept/moq-lite#what-moq-lite-leaves-out) lists the -differences. - -On draft 19 and later, a requester can FIN its request stream while its -subscription or namespace advertisement stays active. Cancellation uses -`RESET_STREAM` or `STOP_SENDING`. Subscription `REQUEST_UPDATE` can change -subscriber priority; other changes are refused with `NOT_SUPPORTED` and end -the subscription with `UPDATE_FAILED`. Drafts 17 and 18 retain FIN cancellation. - -Rust and JavaScript subscribers accept object extension blocks up to 64 KiB. -This is an implementation limit, not a limit in the IETF draft. A larger -declared block stops its subgroup stream with `MALFORMED_TRACK` before reading -the block; other groups and the session stay open. - -Rust and JavaScript read an incoming padding stream (draft-18 and later) to -the end and discard it, without sending `STOP_SENDING`. A unidirectional stream type the negotiated draft does not -define, or a `SUBGROUP_HEADER` type it marks invalid, closes the session with -`PROTOCOL_VIOLATION`, as the draft requires. - -An IETF publisher declares the track's default priority in `SUBSCRIBE_OK` or -`PUBLISH` when that draft carries track properties. Groups without a priority -flag inherit it. If the property is absent, the IETF wire default of 128 maps -to model priority 127, where higher values are served first. A track that -never sets a priority is 127 as well, so it goes out as 128 on IETF and 127 -on moq-lite. - -On drafts 14–19, the Rust publisher answers a standalone `FETCH` within one -group from the cache. A relay fetches a missing group upstream with a `FETCH` -of that one whole group, and an upstream refusal is the refusal the fetcher -sees. Once its last reader leaves, the relay cancels the upstream fetch, even -before `FETCH_OK`, and aborts an incomplete group instead of caching it as whole. -Drafts 14–16 use `FETCH_CANCEL`; drafts 17–19 stop and reset the request stream. -A range touching several groups is refused with `NOT_SUPPORTED`, as is -any `FETCH` on draft-20 and later, which moved the range into -`LOCATION_FILTER`. A standalone `FETCH` -carries no timestamps, since no `SUBSCRIBE_OK` declared a timescale for it. - -On drafts 14–19, the Rust publisher also serves relative and absolute joining -`FETCH` requests for `NextObject` subscriptions, for the subscription group's -saved prefix only, while the subscription delivers later objects. One reaching -back to earlier groups is refused with `NOT_SUPPORTED`. Draft-20 uses -subscription fills instead. JavaScript -publishing refuses every `FETCH` with `NOT_SUPPORTED`; -Rust and JavaScript subscribers request unfiltered delivery on older drafts -because they do not issue joining fetches. Other publishers may replay a cached -backlog for that filter; selecting the next group instead would leave static -tracks waiting for a group that never arrives. - -A moq-lite datagram is a single-frame group, so on moq-transport it travels -as an `OBJECT_DATAGRAM` at object 0 whose Group ID is the sequence, and a relay -forwards it without renumbering. A datagram carrying any other Object ID, or a -status other than Normal, is dropped. JavaScript does not yet carry datagrams -on moq-transport. - -A client may present one credential in its `SETUP` with the `AUTHORIZATION -TOKEN` option. The server reads a value (`USE_VALUE`, or `REGISTER`, which it -treats as a value since it advertises no token cache) and hands its Token Type -and bytes to the application unverified; a relay forwards them to its -[auth server](/bin/relay/auth#the-contract). An alias reference (`DELETE`, -`USE_ALIAS`) closes the session with `PROTOCOL_VIOLATION`, a structure that -does not decode with `KEY_VALUE_FORMATTING_ERROR`, and a second token is -refused. An `AUTHORIZATION TOKEN` parameter on a request is read and ignored: -the session's credential is what authorizes it. - -A legal request that is not served is refused on its own with `NOT_SUPPORTED`, -leaving the session open: a `SUBSCRIBE` with `FORWARD=0`, a `SUBSCRIBE` or -`FETCH` carrying Range Filters (no `MAX_FILTER_RANGES` is advertised), a -`FETCH` carrying `FILL_TIMEOUT` (Timed-Out gaps are not written), -`TRACK_STATUS`, `SUBSCRIBE_TRACKS` (draft-18 and later), and the `FETCH` -forms above. `NEW_GROUP_REQUEST` is ignored, as -the draft allows a publisher without dynamic groups to do. A parameter the -negotiated draft does not define still closes the session with -`PROTOCOL_VIOLATION`, as the draft requires. +[moq-lite page](/concept/moq-lite#what-moq-lite-leaves-out) lists what 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. +- **History is one group.** On drafts 14 through 19 a `FETCH` returns one whole group from the cache, or the saved prefix of the group a new subscription just joined. A range of groups is refused, as is any `FETCH` on draft 20 and later. JavaScript publishing refuses every `FETCH`. A standalone fetch carries no timestamps. +- **One credential per session**, carried in `SETUP` and forwarded to the [auth server](/bin/relay/auth#the-contract) unverified. A token attached to an individual request is ignored. An alias reference, a second token, or a parameter the negotiated draft does not define closes the session. +- **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`, `SUBSCRIBE_TRACKS`, and the fetch forms above. On draft 19 and later, the only subscription update that is applied is a priority change. +- **Datagrams** are a single normal object at object 0, forwarded without renumbering. Anything else is dropped. JavaScript does not carry datagrams on moq-transport. +- **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. Several project drafts extend the IETF wire without breaking it, since `SETUP` ignores unknown parameters: [cluster](/draft/moq-cluster) routing hop lists, @@ -104,8 +40,9 @@ ignores unknown parameters: [cluster](/draft/moq-cluster) routing hop lists, [active-count](/draft/moq-active-count) to count the `NAMESPACE` messages before a `SUBSCRIBE_NAMESPACE` is caught up, and [probe](/draft/moq-probe) for bandwidth estimation. -[moq-e2ee](/draft/moq-e2ee) is not a transport extension: it encrypts application -payloads so relays still forward named tracks they cannot read. +[moq-e2ee](/draft/moq-e2ee) is not a transport extension. It encrypts +application payloads, so relays still forward named tracks they cannot read. +See [Encryption](/concept/hang#encryption). ## MSF @@ -138,9 +75,5 @@ moq --connect https://relay.example.com --broadcast test.hang export ts | ffplay Add `--connect-tls-insecure` for a self-signed relay on your own test network (it accepts any certificate, so never point it at a remote relay) and -`RUST_LOG=info,moq_net=debug` to see the negotiated version. Behavior worth -knowing when pointing another implementation at ours: we announce every -namespace we can offer unsolicited *and* ask for every prefix we may discover; -set the solicit `SETUP` option to make us wait to be asked. Single-track -`PUBLISH` offers are declined; announce a namespace and serve the resulting -`SUBSCRIBE`s instead. +`RUST_LOG=info,moq_net=debug` to see the negotiated version. The limits above +are the ones that surprise another implementation. diff --git a/doc/concept/use-case/contribution.md b/doc/concept/use-case/contribution.md index 4b45fdc9f9a..973c6d6e12b 100644 --- a/doc/concept/use-case/contribution.md +++ b/doc/concept/use-case/contribution.md @@ -1,6 +1,6 @@ --- title: MoQ vs RTMP/SRT -description: Pull-based contribution, on-demand encoding, and redundant ingest +description: Pull-based contribution, on-demand encoding, and restarts that take the name --- # MoQ vs RTMP/SRT @@ -22,14 +22,14 @@ That matters for long-tail content: hundreds of security cameras uploading a captions track backed by an expensive model runs only while someone has captions on. -## Redundant ingest for free +## Restarts take the name -Because tracks are only pulled where they're needed, a publisher can open -several connections that might be used. Primary and secondary ingest is two -connections and no business logic: subscriptions ride the primary until it -fails, then move. Two encoders publishing the same broadcast name are -interchangeable sources that relays fail over between mid-group; see -[redundant publishers](/bin/cli#redundant-publishers). +A publisher announces an [epoch](/concept/moq-lite#publisher-epochs) naming the +instance behind a broadcast. Replicas of that instance, announced with the same +epoch, fail over mid-group. A restart mints a new epoch, and viewers switch to +it instead of stitching its group numbers onto the old run. `moq` and +`moqsink` mint a fresh epoch per run. A second process publishing the same name +is a newer epoch, so viewers move to it. ## One protocol both ways diff --git a/doc/concept/use-case/index.md b/doc/concept/use-case/index.md index 9547e751fae..0beec4bf318 100644 --- a/doc/concept/use-case/index.md +++ b/doc/concept/use-case/index.md @@ -12,6 +12,6 @@ of scale come from. | Use case | Replaces | Why MoQ fits | | --- | --- | --- | | [Distribution](/concept/use-case/distribution) | HLS, DASH | Sub-second latency at CDN scale, with the viewer choosing its buffer. | -| [Contribution](/concept/use-case/contribution) | RTMP, SRT | Pull-based delivery, optional on-demand encoding, and simple redundant ingest. | +| [Contribution](/concept/use-case/contribution) | RTMP, SRT | Pull-based delivery, on-demand encoding, and a restart that takes the name over. | | [Conferencing](/concept/use-case/conferencing) | WebRTC | Bidirectional on one session, browser control of the pipeline, no SDP or TURN. | | [AI](/concept/use-case/ai) | WebRTC, WebSockets | Adjustable reliability, on-demand inference, media and prompts on one connection. | diff --git a/doc/lib/js/json.md b/doc/lib/js/json.md index 0d5ae63626a..5b2679780eb 100644 --- a/doc/lib/js/json.md +++ b/doc/lib/js/json.md @@ -7,41 +7,22 @@ description: JSON over MoQ tracks, as snapshots, streams, or a sliding window [![npm](https://img.shields.io/npm/v/@moq/json)](https://www.npmjs.com/package/@moq/json) -JSON over [`@moq/net`](/lib/js/net) tracks, in three modes: - -- **Snapshot**: lossy latest-value, with RFC 7396 merge-patch deltas. -- **Stream**: lossless append-log in a single group. -- **Window**: a bounded run of records a reader can join at any point. - -On Snapshot and Stream, `Config` is the codec options. `Producer.Config` / -`Consumer.Config` add the track. Compression is a shared `"none" | "deflate"` -enum, not a boolean: both sides set the same field. `Stream.Config` also -accepts a `schema` for record validation on encode and decode. A delta without -a snapshot raises `MissingSnapshot`; an uncommitted compressed stream frame -raises `Desync`. Unexpected frame read errors propagate to the caller. Window still uses -`ProducerConfig` / `ConsumerConfig` and a boolean `compression` flag. - -```ts -import { Snapshot } from "@moq/json"; - -const producer = new Snapshot.Producer({ track, compression: "deflate" }); -producer.update({ hello: "world" }); - -const consumer = new Snapshot.Consumer({ track: track.subscribe(), compression: "deflate" }); -for await (const value of consumer) { - console.log(value); -} -``` - -A value is stamped when written, unless you pass its capture time: -`producer.update(value, at)`. - -A Stream rides one group, so the whole log shares `@moq/net`'s group budget: -32 MiB of payload and 8192 records. An `append` that might not fit throws -`GroupTooLarge` before it is encoded and leaves the log intact, compressed or -not. With `"deflate"` the check counts the raw JSON plus DEFLATE's worst-case -overhead. Once the budget is spent every `append` throws; start a new track to -keep going. Any other failed append aborts the track, so readers see the error -rather than a log that looks complete. +JSON over [`@moq/net`](/lib/js/net) tracks, in three modes. Snapshot and stream +are the catalog modes on the [hang](/concept/hang#data-tracks) page. Window is +a third framing for a raw track: both ends opt into it, and a generic catalog +reader will not pick it up. + +- **Snapshot**: lossy latest value, with RFC 7396 merge-patch deltas. A delta before any snapshot is an error. +- **Stream**: lossless append-log in a single group. A reader that falls behind fails the read rather than resuming mid-log. +- **Window**: a bounded run of records a reader can join at any point. Trimming a record is explicit, so a reader that was keeping up is not handed that record again when the publisher rolls a group. + +Both sides choose the same compression, `"none"` or `"deflate"`. A value is +stamped when written, unless you pass its capture time. + +A stream rides one group, so the whole log shares `@moq/net`'s group budget: +32 MiB of payload and 8192 records. An append that might not fit is refused +before it is encoded and leaves the log intact. Once the budget is spent, +start a new track. Any other failed append aborts the track, so readers see +the error rather than a log that looks complete. The Rust twin is [`moq-json`](/lib/rs/moq-json). diff --git a/doc/lib/js/net.md b/doc/lib/js/net.md index bf33ec0defc..4ce41ed80b8 100644 --- a/doc/lib/js/net.md +++ b/doc/lib/js/net.md @@ -9,16 +9,15 @@ description: The pub/sub layer in TypeScript The TypeScript twin of [`moq-net`](/lib/rs/moq-net): connections, origins, broadcasts, tracks, groups, and frames, negotiating moq-lite or moq-transport -at setup. `Epoch` provides the shared publisher identity, carried on each -route as `route.epoch`; see [publisher epochs](/concept/moq-lite#publisher-epochs). +at setup. The model is [moq-lite](/concept/moq-lite). This page is the behavior +the types do not spell out. ```ts import * as Moq from "@moq/net"; const url = new URL("https://cdn.moq.dev/anon?jwt=..."); -// Publish. The origin is the routing table the connection announces and serves, -// so a broadcast survives a reconnect. +// The origin is the routing table. The broadcast survives a reconnect. const origin = new Moq.Origin.Producer(); const connection = await Moq.Connection.connect({ url, @@ -29,116 +28,21 @@ const connection = await Moq.Connection.connect({ const broadcast = origin.createBroadcast(Moq.Path.from("chat.room")); const track = broadcast.createTrack("messages"); const group = track.appendGroup(); -group.writeString("hello"); // or writeFrame({ payload, timestamp }) +group.writeString("hello"); group.close(); broadcast.announce(); - -// Subscribe -const request = origin.request(Moq.Path.from("chat.room")); -let active = request.active.peek(); -while (!active) { - await request.active.changed(); - active = request.active.peek(); -} -const consumer = active.track("messages").subscribe({ priority: 0 }); -for (;;) { - const group = await consumer.recvGroup(); - if (!group) break; - console.log(await group.readString()); -} -``` - -- **Origins** hold the broadcasts, not the connection: closing a session unannounces them but leaves them created for the next one. `origin.request(path)` resolves an announced local broadcast with no round trip, so a page that watches what it publishes reads its own copy, unless a cheaper route announces the same path. A refusal from the most specific route ends the request: `request.closed` settles with the handler's error and no broader route is asked. Create, populate, then `announce()` for an exact path; use `dynamic(prefix, route)` when the set of paths is not known: an exact-path subscribe before the tracks exist is refused, and nobody, local or remote, can see or reach a broadcast until it announces. -- **Connections** race WebTransport against WebSocket. `new Connection({ url })` pools one connection per relay URL and reconnects with backoff, which the elements use. Supplying WebTransport/WebSocket options, discovery, delay, `goaway`, or a caller-owned origin selects a private loop; explicit `share: true` refuses those options. On a relay's GOAWAY the connection dials the replacement at once while the old session keeps serving its groups until it closes or the `goaway.handover` cap (default 10s, lowered to the relay's deadline) passes; the handle and its origin stay the same. An empty GOAWAY redials the same URL through a fresh DNS resolve. A redirect is followed onto the same host by default (`goaway.redirect: "follow"` lets the relay pick the host, `"ignore"` never moves), and moves the pooled entry to the new URL; a malformed or refused one, including a host change under a pinned certificate, ends the connection with `Error.RefusedRedirect` instead of reconnecting. `closed` settles when the handle is released (`null` on a clean close); the failure that stopped retrying the current URL is `error`, and a new URL recovers the same handle. A connection owns one send-rate sampler and one `Bandwidth.Allocator`; publishers reserve against it so their encoder targets sum to the estimate instead of each matching it. -- **Bandwidth** (`Bandwidth.Allocator`) divides the connection's send-rate estimate by track priority, max-min fair within a tier. An idle track claims nothing. The receive side is untouched. -- **Discovery** by any pattern scope (`origin.announced(scope)`, such as `room/*/chat`; default everything). A route event's `kind` says whether the route started, updated, or ended; its `prefix` is the covered prefix relative to the origin, and `captures` reports what the scope's wildcards matched when the prefix pins them. The consumer is an async iterable. `origin.broadcasts(scope)` is a live `Getter>` of the same covered prefixes for UIs that need the current set. A borrowed `Connection.origin` also exposes `dynamic(prefix, route)` for serving paths on demand. -- **Publisher retention** is optional `Track.Info.maxAge`, measured against media timestamps: omission sets no limit, while zero serves only the live edge. It clamps every subscriber's max delay, and stalled media does not age out merely because wall time passes. Separately, cached groups nobody writes for 30 seconds are reclaimed, except a live track's newest group, which stays replayable until the track closes. -- **Subscriptions** carry a priority, a `Time.Milli` max delay measured against media timestamps, and optional `groups` bounds. Subscription options use `maxDelay`; supplying the obsolete subscriber `maxAge` key throws a `TypeError` naming its replacement, including on `update()`. Groups arrive out of order and are read frame by frame, with `Error.TooFarBehind` when a reader asks for a frame the group never held and `Error.GroupTooLarge` when a write exceeds the cache budget and aborts the group. -- **Track ends**: `close()` ends a track at its live edge, while `finishAt(n)` declares the exclusive end ahead of it and still accepts the groups below. A finished track stays on its broadcast and serves its cache to late subscribers until `removeTrack`; an aborted one is removed, and subscribing to a track the broadcast does not have rejects with `Error.NotFound` when no on-demand handler is pulling requests, as in Rust. With a pulling handler, an absent track queues an on-demand request. A subscriber reads the end with `final()` or awaits `finished()`. Group and datagram readers end once the live edge reaches the declared boundary, even while missing lower groups wait out the grace. The `closed` signal settles separately once every group below the end has arrived or was dropped; one reset before its header arrived is skipped after the subscription's max delay on moq-lite (one second without one), or after one second on IETF. -- **Datagrams** on moq-lite 05+ and fetch-by-sequence for history. `track.fetchGroup(sequence)` on moq-lite resolves when the publisher sends the first response byte or finishes an empty group. A missing group rejects the fetch with `StreamCode.NotFound`, including every concurrent caller sharing that fetch. `fetchGroup(sequence, { signal })` abandons a pending fetch with the signal's reason; the shared stream is cancelled only once every caller has left. Once resolved, close the group instead. -- **Errors**: deliberately closing a connection ends its received tracks cleanly. A peer close ends received tracks and open group readers with the session error and its close code. Errors live under one namespace: a stream reset throws `Error.Stream` with a `StreamCode`, while a session close gives `Error.Session` with a `SessionCode`. The registries are disjoint, so the same number means different things in each, and 64+ is yours. Named conditions such as `Error.TooFarBehind`, `Error.FrameTooLarge`, and `Error.GroupTooLarge` subclass `Error.Stream`, so one `code` check handles a condition raised here or reported by the peer. IETF streams use their own mapping: cancellation sends CANCELLED, other local failures send INTERNAL\_ERROR, and received codes remain opaque. -- **Paths** with `Path.relative` for the cross-broadcast catalog references hang uses. A `Broadcast.Consumer` names its broadcast by `path`: the path it was requested at relative to the origin handle's root, or empty for a standalone broadcast. Those references resolve against it. Path patterns (`Path.Pattern`, `Path.Patterns`) are re-exported from [`@moq/pattern`](https://www.npmjs.com/package/@moq/pattern). Literal `Path` stays a coordinate. - -The [path pattern](/concept/moq-lite#path-patterns) grammar lives on the -concept page. - -## Patterns - -`Path.Pattern` describes a set of paths; `Path.Patterns` is a union reduced -by containment. `contains` is the authorization check. `overlaps` asks -whether they share any path. `rooted` places a pattern under a literal root; -`rebase` is the inverse, and can return several residuals. `intersect` returns -the exact overlap as a union, and `captures` reports what one pattern's -wildcards stand for in a contained pattern. - -```ts -import * as Moq from "@moq/net"; - -const scope = Moq.Path.Pattern.parse("room/**"); -scope.matches("room/alice"); // true -scope.contains(Moq.Path.Pattern.parse("room/camera-*")); // true -scope.overlaps(Moq.Path.Pattern.parse("*/alice")); // true -scope.intersect(Moq.Path.Pattern.parse("*/alice")).toJSON(); // ["room/alice"] -scope.captures(Moq.Path.Pattern.parse("room/alice"))?.map((capture) => capture.text); // ["alice"] -scope.rebase("room").toJSON(); // ["**"] -Moq.Path.Pattern.parse("camera-*").rooted("room").text; // "room/camera-*" ``` -## Advertising - -Three operations, on an origin: - -- `origin.createBroadcast(path)` returns a producer. The broadcast is - invisible and unreachable, for local consumers and peers alike, until - `broadcast.announce()`. -- `broadcast.announce(route)` / `broadcast.unannounce()` own that - advertisement. Announcing again replaces the standing route as given, epoch - included, so re-price from the current one - (`broadcast.announce({ ...broadcast.route, cost })`); another epoch, or - none, announces a new broadcast. `Origin.Dynamic` has the same `route` and - `update(route)`. -- `origin.dynamic(prefix, route)` claims `prefix` and every path beneath it - (`""` claims everything). Hold the returned `Origin.Dynamic` while the - claim should stay advertised; `close()` retracts it. A request beneath it - that no announced local broadcast wins is an `Origin.Request` to `accept` or `reject`; - reject what you will not serve rather than narrowing the claim, since a - route is always a prefix on every wire. +- **The origin holds the broadcasts, not the connection.** Closing a session unannounces them and leaves them created for the next one. A broadcast is invisible, locally and remotely, until `announce()`. `dynamic(prefix, route)` claims a prefix and yields each requested path to accept or reject. +- **One connection per URL, unless you opt out.** `new Connection({ url })` pools and reconnects with backoff, which the elements use. Supplying your own transport options, discovery, or origin selects a private loop. +- **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). An empty GOAWAY redials the same URL. A redirect stays on the same host unless `goaway.redirect` is `"follow"`. +- **One send estimate per connection.** `Bandwidth.Allocator` divides it by track priority, max-min fair within a tier. An idle track claims nothing. Publishers reserve against it so their targets sum to the estimate. +- **Subscriber staleness is `maxDelay`.** It is media time. Passing the old `maxAge` key throws a `TypeError` naming `maxDelay`. Publisher retention is the separate `Track.Info.maxAge`. +- **Hidden paths** stay out of discovery unless the announce request opts in. See [hidden broadcasts](/concept/moq-lite#hidden-broadcasts). +- **A graceful close waits.** `await connection.close()` withdraws announcements and gives finished tracks up to one second. `abort()` ends immediately. -A route is a capability, not an inventory. `origin.announced(scope)` yields -`Announce.Event` values. `kind` is `"start"`, `"update"` (a reprice in -place), or `"end"`, each also carrying an `Announce.Announce`: `prefix` -is the covered prefix relative to the origin, `captures` is one pattern per -scope wildcard when the prefix pins a complete match (otherwise `undefined`), -and `route` carries hops and cost (on a retraction, its last values). The -consumer is an async iterable. A prefix is -not a broadcast name; the scope filters locally while sessions request its -literal head on the wire. Paths with a `.`-prefixed segment below that head -are [hidden](/concept/moq-lite#hidden-broadcasts) unless `announced(scope, { hidden: true })` opts in; -`broadcasts(scope, { hidden: true })` takes the same option. - -An established connection's `await connection.close()` withdraws its -announcements and waits up to one second for delivery before disconnecting. -On moq-lite it also waits for the requests it serves: a subscription to a -finished track delivers its remaining groups, and on moq-lite-07 waits for the -subscriber's FIN, which says it read the tail. A live track never ends on its -own, so its subscription holds the close until the deadline. -It rejects if an announcement withdrawal fails or the deadline passes, and -closes the transport either way. -Use `connection.abort()` for immediate shutdown. Reconnecting connection -handles keep their synchronous `close()` disposal behavior. IETF drafts 14 -through 16 send their withdrawals without waiting. - -Examples in +Examples: [`js/net/examples/`](https://github.com/moq-dev/moq/tree/main/js/net/examples). Runs in the browser and, over WebSocket, in Node, Bun, and Deno; see -[server-side](/lib/js/#server-side). - -## Subscriber demand - -Call `demand()` on a track producer or pending track request, a group producer, -or a broadcast producer. The returned `Track.Demand`, `Group.Demand`, or -`Broadcast.Demand` exposes a read-only `used` signal, `unused()`, and `closed`. -A broadcast watches subscribers to its tracks; holding a broadcast consumer -alone is not demand. A group's demand counts its mirror readers, preserving -fetch coalescing: the shared download becomes unused only after every reader -leaves. Demand handles cannot write or close the producer. +[server-side](/lib/js/#server-side). Path patterns are on the +[concept page](/concept/moq-lite#path-patterns). diff --git a/doc/lib/rs/index.md b/doc/lib/rs/index.md index eb232992793..04ae0b24cbb 100644 --- a/doc/lib/rs/index.md +++ b/doc/lib/rs/index.md @@ -93,34 +93,13 @@ at a group boundary and draining the WebSocket session; `Connection::transport() which is live. A refused or stalled QUIC session leaves the WebSocket session serving, and moq-lite-03 and -04, which give no sign of admission, never upgrade. -The `Default::default()` above is the QUIC transport section, and the same value -serves a dial and a listener: - -```rust -let mut quic = moq_tokio::quic::Config::default(); -quic.congestion_control = Some(moq_tokio::quic::CongestionControl::Delay); -quic.receive_window = Some(64 << 20); // whole connection, in bytes -quic.stream_receive_window = Some(8 << 20); // per stream -quic.send_window = Some(32 << 20); // unacknowledged data we may hold - -let client = moq_tokio::connect::Config::default().init(quic)?; -``` - -Unset flow-control windows keep the transport defaults, except `receive_window`, -which defaults to 64 MiB because the transport's is unlimited. `init` errors on a -knob the transport cannot honor rather than dropping it: iroh cannot disable -GSO. `quic::Resolved::default()` is what an -untouched config resolves to, so read the defaults from there. The +The same QUIC config serves a dial and a listener: congestion control, flow +windows, and the rest. Unset windows keep the transport defaults, except the +connection receive window, which defaults to 64 MiB because the transport's is +unlimited. `init` errors on a knob the transport cannot honor. The [relay reference](/bin/relay/config#quic) documents each field. - -## Connection monitoring - -`Connection::monitor()` returns a cloneable `moq_tokio::connection::Monitor` -that observes the live session across reconnects without keeping the connection -loop alive. Its `stats()` and `snapshot()` return `None` between connections; -`connection::Snapshot` pairs transport statistics with the negotiated protocol. -Use `presence()` for cumulative connects and disconnects, or -`presence_changed().await` to wait for those counters to change. +`Connection::monitor()` observes the live session across reconnects, including +when none is up. ## WebAssembly diff --git a/doc/lib/rs/moq-audio.md b/doc/lib/rs/moq-audio.md index 352b9f2e2c6..d42a0bf1992 100644 --- a/doc/lib/rs/moq-audio.md +++ b/doc/lib/rs/moq-audio.md @@ -9,143 +9,48 @@ description: Native audio capture, codecs, playback, and echo cancellation [![docs.rs](https://docs.rs/moq-audio/badge.svg)](https://docs.rs/moq-audio) The audio half of a native call: microphone in, hang track out, speaker at -the far end. Everything is Rust, so there is no C toolchain, CMake step, or -codec to install. - -`Layout` names speaker meaning separately from a channel count. `Mono` is center, -`Stereo` is left then right, and the surround layouts up to `SevenPointOne` -interleave in the SMPTE/WAVE order (front left, front right, center, LFE, back, -side). A catalog carries only a count, which reads as that count's WAVE default -(`Layout::from_channels`: 6 is 5.1, 8 is 7.1). `Discrete(n)` preserves unnamed -channels without inventing speaker positions, so it passes through but never -remixes. Decoding and playback downmix with the ITU-R BS.775 coefficients and -upmix by leaving the extra speakers silent; the playback mix runs in whatever -layout the output device opened. Encoding keeps source PCM in `encode::Input` and -codec requirements in `encode::Settings`; `encode::Options` adds publication -policy. Decoding likewise separates low-level `decode::Config`, PCM -`decode::Output`, and subscription `decode::Options`. - -`encode::Settings::with_preset` applies an `encode::Preset` without touching -codec, rate, layout, bitrate, or DTX. `LowLatency` (the default preset) packs -10 ms of audio per packet, `Balanced` and `Quality` 20 ms, which is also what -`Settings` defaults to without a preset. AAC frames are fixed at 1024 samples, -so a preset leaves AAC's frame duration alone. That is packetization, not a delay -guarantee: Opus adds its 6.5 ms lookahead either way. libopus already runs at -full complexity, where a 10 ms stereo packet takes about 0.1 ms to encode, so -Quality has nothing further to spend and matches Balanced. +the far end. `moq import capture` and `moq play` use it. There is no C +toolchain or codec package to install, apart from ALSA headers on Linux when +capture or playback is enabled. | Module | Does | | --- | --- | | `capture` | Microphones via CoreAudio, WASAPI, ALSA (and PipeWire/PulseAudio hosts), plus macOS system audio | -| `encode` | PCM to Opus (with DTX and voice-activity signaling), raw PCM for the lowest latency, or AAC-LC through a platform encoder | +| `encode` | PCM to Opus (with DTX and voice-activity signaling), raw PCM, or AAC-LC through a platform encoder | | `decode` | Opus, PCM, and AAC-LC back to PCM, resampled to the rate you want | | `playback` | One output device mixing every track in a call, with click-free volume ramps | | `aec` | Acoustic echo cancellation (a port of WebRTC's), so a laptop with no headset doesn't feed itself back | -`decode` picks a backend per track the way `moq-video` does: a platform decoder -first, then software. `decode::Config::kind` narrows it: `Kind::Software` skips -the platform tier, and `Kind::Named` requires the track to be a codec, by its -name (`"opus"`, `"pcm"`, or `"aac"`), and refuses any other. Backends are never -named; `Decoder::name()` reports which one opened. - -| Backend | Decodes | Hosts | -| --- | --- | --- | -| `libopus` | Opus, mono or stereo, and surround up to 7.1 (channel mapping family 1) | all | -| `pcm` | PCM | all | -| `symphonia` | AAC-LC, mono or stereo (the default-on `aac` feature) | all | - -No platform decoder is wired in yet, so multichannel AAC and HE-AAC declared in -its config are refused at construction on every host. HE-AAC signaled only in -band plays as its half-rate LC core. Linux has no OS audio decoder, so it will -stay that way there. Surround Opus is pure Rust, so it is the one multichannel -path every host has. Opus mapping families other than 0 and 1 (ambisonics, and -255's unpositioned channels) are refused, since they declare no speakers. - -Opus always decodes at 48 kHz, its own clock, whatever input rate the OpusHead -records (44.1 kHz and unknown included), and applies the head's pre-skip and -output gain. A track without a description decodes mono or stereo from the -catalog with neither. A description that is present but malformed (truncated, -wrong signature, a new major version, or a channel count its mapping family -forbids) is refused rather than falling back to the catalog's fields. - -`encode` selects the same way, through `encode::Settings::kind`, where -`Kind::Named` requires `Settings::codec` to match the codec name, and -`Encoder::name()` reports what opened. - -| Backend | Encodes | Hosts | -| --- | --- | --- | -| `libopus` | Opus, mono or stereo | all | -| `pcm` | PCM | all | - -`encode::Codec::Aac` is AAC-LC (`mp4a.40.2`) at the input's rate and layout: -mono, stereo, 3.0, 4.0, 5.0, 5.1, or 7.1, the layouts with an AAC -channelConfiguration. Frames are 1024 samples, so `Settings::from_input` sets -`frame_duration` to match. The catalog's AudioSpecificConfig is built from the -settings when the track is registered, and since it has no field for the -encoder's delay, packets are stamped that much earlier so the first input -sample still lands at the first timestamp. There is no software AAC encoder, -and no platform encoder is wired in yet, so `Codec::Aac` is refused at -construction on every host for now. Linux has no OS encoder, so it will stay -that way there. +The microphone opens only while someone listens, and can be swapped without +changing the track subscribers know. Opus packetization is 10 ms at the +default low-latency preset and 20 ms otherwise. That is packetization, not a +delay guarantee: Opus adds its lookahead either way. AAC frames stay 1024 +samples. -Highlights: +What actually decodes and encodes today: -- **`encode::Control`** advertises the track and opens the microphone only while someone listens. Stop, swap devices, and restart without changing the track subscribers know; read a level meter for the UI. -- **A/V sync signal.** `Sink::buffered()` reports how far ahead the speaker is, which is what a video clock steers by. -- **Activity per packet**, read off the Opus stream, so a call UI shows who is talking without a second voice detector. -- **One Linux build dependency**: ALSA headers, and only when `capture` or `playback` is enabled. +- **Opus** decode is mono, stereo, or surround up to 7.1 on every host. Encode is mono or stereo. Ambisonics and unpositioned channel mappings are refused. +- **PCM** in both directions. +- **AAC-LC** decodes mono or stereo. HE-AAC signaled only in band plays as its half-rate LC core. Encoding AAC is refused on every host until a platform encoder is wired in, and Linux has no OS encoder to wire. -```rust -let mut audio = moq_audio::decode::Consumer::new(&broadcast, &rendition, "audio", Default::default()).await?; -let engine = moq_audio::playback::Engine::open(Default::default()).await?; -let mut input = moq_audio::playback::Input::default(); -input.sample_rate = audio.sample_rate(); -input.layout = audio.layout(); -let mut sink = engine.sink(input)?; -while let Some(frame) = audio.read().await? { - let write = sink.write(&frame.data)?; - if write.dropped_sample_frames > 0 { - eprintln!("dropped {} live audio frames", write.dropped_sample_frames); - } -} -sink.finish().await; -``` - -Playback writes never block. Inspect the returned input sample-frame counts for -telemetry, but do not retry dropped live audio because that would add latency. -Await `sink.finish()` to play its queued tail before leaving the mix; dropping -its `Drain` stops immediately. An unavailable device keeps it pending. When -sample rates differ, the current resampling channel cannot flush its partial -input block, so completion covers the output ring. - -For a speakerphone, build one echo-cancellation control set from the playback -engine and give a clone to the microphone configuration. Other clones are safe -for UI toggles, but only one live microphone can attach the adaptive state: - -```rust -let aec = engine.canceller(moq_audio::aec::Config::default())?; -let controls = aec.clone(); - -let mut microphone = moq_audio::capture::Config::default(); -microphone.aec = Some(aec); - -controls.set_enabled(false); // passthrough without reopening the device -``` +Playback writes never block. Dropped live samples are reported and should not +be retried, since a retry would add latency. `Sink::buffered()` is how far +ahead the speaker is, which is what a video clock steers by. Voice activity is +read off the Opus stream, so a call UI does not need a second detector. -A second `Engine::canceller` call, or a second microphone using the same -controls while the first is live, returns `Error::Busy`. Dropping the live -capture frees the microphone slot. The engine slot frees only once every -`Control` clone and the live capture have dropped, since a capture holds the -controls alive. +Echo cancellation is one control set per playback engine and one live +microphone. A second microphone, or a second canceller on the same engine, +is refused until the first capture is dropped. Disabling it is a passthrough; +the device stays open. ```bash -cargo add moq-audio --features playback # decode and play the example above -cargo add moq-audio --features capture,playback,aec # microphone, speaker, echo cancellation (Linux: cpal links libasound) -cargo add moq-audio --features capture,pipewire # capture through the PipeWire cpal host +cargo add moq-audio --features playback +cargo add moq-audio --features capture,playback,aec # Linux: cpal links libasound +cargo add moq-audio --features capture,pipewire ``` -`pipewire` and `pulseaudio` only configure cpal when `capture` or `playback` -also enables device I/O. A host flag by itself does not compile or link cpal. +`pipewire` and `pulseaudio` only take effect alongside `capture` or `playback`. API: [docs.rs/moq-audio](https://docs.rs/moq-audio). Pair with -[`moq-video`](/lib/rs/moq-video). +[`moq-video`](/lib/rs/moq-video). The playout target `moq play` and +`` share is [audio jitter](/concept/audio-jitter). diff --git a/doc/lib/rs/moq-json.md b/doc/lib/rs/moq-json.md index 172074e0395..103a8d51cc5 100644 --- a/doc/lib/rs/moq-json.md +++ b/doc/lib/rs/moq-json.md @@ -8,41 +8,22 @@ description: JSON over MoQ tracks, as snapshots, streams, or a sliding window [![crates.io](https://img.shields.io/crates/v/moq-json)](https://crates.io/crates/moq-json) [![docs.rs](https://docs.rs/moq-json/badge.svg)](https://docs.rs/moq-json) -JSON over [`moq-net`](/lib/rs/moq-net) tracks, in three modes: +JSON over [`moq-net`](/lib/rs/moq-net) tracks, in three modes. Snapshot and +stream are the catalog modes on the [hang](/concept/hang#data-tracks) page. +Window is a third framing for a raw track: both ends opt into it, and a +generic catalog reader will not pick it up. -- **snapshot**: lossy latest-value, with RFC 7396 merge-patch deltas. -- **stream**: lossless append-log in a single group. -- **window**: a bounded run of records a reader can join at any point. +- **snapshot**: lossy latest value, with RFC 7396 merge-patch deltas. An unchanged update publishes nothing. Several owners can edit their own keys in place instead of clobbering one document. +- **stream**: lossless append-log in a single group. A reader that falls behind fails the read rather than resuming mid-log. +- **window**: a bounded run of records a reader can join at any point. Trimming a record is explicit, so a reader that was keeping up is not handed that record again when the publisher rolls a group. -On snapshot and stream, `Config` is the codec options. The track-owning pair is -`producer::Config` / `consumer::Config`. Compression is a shared `Compression` -enum (`None` or `Deflate`), not a bool: both sides set the same field. Window -still uses `ProducerConfig` / `ConsumerConfig` and a boolean `compression` -flag. - -```rust -let mut config = moq_json::snapshot::Config::default(); -config.compression = moq_json::Compression::Deflate; - -let mut producer = moq_json::snapshot::Producer::new(track, config); -producer.update(&value)?; -``` - -A value is stamped when written, unless it carries its capture time: -`moq_net::Timed::from(&value).at(captured)`. Writes return the encoded frame -size, and an unchanged snapshot `update` returns `None`. +Both sides choose the same compression. A value is stamped when written, +unless it carries its capture time. A stream rides one group, so the whole log shares moq-net's group budget: -32 MiB of payload and 8192 records. An `append` that might not fit returns -`moq_net::Error::GroupTooLarge` before it is encoded and leaves the log intact, -compressed or not. Once the budget is spent every `append` is refused; start a -new track to keep going. - -A snapshot producer also edits in place, so independent owners each touch only -their own keys instead of clobbering one another. `mutate(|value| ...)` runs a -closure and publishes the result, matching `Producer.mutate` in TypeScript; -`modify()` returns a guard that holds the lock across several edits and -publishes on drop. +32 MiB of payload and 8192 records. An append that might not fit is refused +before it is encoded and leaves the log intact. Once the budget is spent, +start a new track. The TypeScript twin is [`@moq/json`](/lib/js/json). API: [docs.rs/moq-json](https://docs.rs/moq-json). diff --git a/doc/lib/rs/moq-mux.md b/doc/lib/rs/moq-mux.md index 8e9b7a838df..f8e67fe10fb 100644 --- a/doc/lib/rs/moq-mux.md +++ b/doc/lib/rs/moq-mux.md @@ -8,165 +8,44 @@ description: Container import and export [![crates.io](https://img.shields.io/crates/v/moq-mux)](https://crates.io/crates/moq-mux) [![docs.rs](https://docs.rs/moq-mux/badge.svg)](https://docs.rs/moq-mux) -Turns existing container formats into hang broadcasts and back. This is what -`moq import`/`export` and the gateways are built on. +Turns existing container formats into [hang](/concept/hang) broadcasts and +back. This is what `moq import` / `export` and the gateways are built on. | Format | Import | Export | Notes | | --- | --- | --- | --- | | fMP4 / CMAF | yes | yes | Passthrough as `cmaf` or repackaged as `legacy`. | -| MPEG-TS | yes | yes | H.264/H.265; AAC, MP2, AC-3, E-AC-3, Opus up to 7.1; SCTE-35 and subtitle PIDs carried as tracks; service tables round-trip; signalled timebase discontinuities preserved; paced export. | +| MPEG-TS | yes | yes | H.264/H.265; AAC, MP2, AC-3, E-AC-3, Opus up to 7.1; SCTE-35 and subtitle PIDs as tracks; service tables round-trip. | | FLV / RTMP | yes | yes | Legacy H.264 + AAC + MP3, plus enhanced-RTMP HEVC, AV1, VP9, Opus, AC-3, E-AC-3, and multitrack. | | Matroska / WebM | yes | yes | | | Annex-B (H.264, H.265) | yes | yes | Parameter sets extracted to the catalog or re-injected per keyframe. | -Importers parse the bitstream to fill the catalog (resolution, codec string, -`description`), split groups at keyframes, and stamp timestamps. Exporters do -the inverse and skip stalled groups past a max delay. Per-codec -producers (`import::Opus`, H.264, and so on) are available for feeding frames -you already have. - -MPEG-TS `Import::stats` returns a `ts::stats::Snapshot` of cumulative per-PID -`ts::stats::Stream` rows: delivered `units`, transport-clock `quiet` time, a -`class` of audio, video, or data, audio `resyncs`, scanned bytes `discarded`, -frames `unconfirmed`, damaged units refused in `damaged`, and the PID's share of -the TR 101 290 counters. A malformed media packet, PES header, or codec unit is -dropped whole; only that PID loses sync, and video closes its group at the break -and waits for its next keyframe. Publishing and catalog failures remain fatal. `ts::stats::Log` reports these counters for -both the CLI and SRT gateway, and grades a stopped stream for audio and video -only; a sparse data PID such as SCTE-35 stays in the row and is not logged for a -quiet second. `Export::stats` returns a `ts::stats::Export` of the same rows, -where only `units` and `quiet` move. - -fMP4 export emits one fragment per publisher group by default, including audio. -A closed group flushes even if the live publisher pauses before its next frame. -`fmp4::Export::with_fragment_duration` adds an explicit duration cap. A zero cap -emits one fragment per frame; video with unknown duration waits for the next -timestamp or endpoint marker. Audio and samples with explicit durations remain -immediate. CMAF audio -samples are always encoded as sync samples; the decoded `Frame::keyframe` marks -only the first audio sample of a MoQ group. - -`fmp4::Export` writes its init segment once every rendition can be described, -queueing other tracks' fragments (up to 30 seconds) behind it. The track set is -then fixed. A rendition that returns with the same sample entry reuses its track -id; `fmp4::Error::TrackAdded`, `TrackChanged`, and `TrackRewound` end the export -for a new rendition, a changed sample entry, or a replay of media already -written, and `TrackUndescribed` names a track that never delivered its codec -configuration. An Opus entry synthesized without a catalog `description` guesses -its pre-skip and input sample rate, so a later OpusHead that agrees on everything -else settles it instead of changing it. An OpusHead whose channel count -contradicts its catalog entry fails with `fmp4::Error::OpusChannelCount`. - -Each catalog track constructor returns one `container::Producer` that owns the -media stream and its catalog entry. `set` publishes or replaces its config, -`modify` edits the published config through a guard, and dropping the producer -retires the entry. Calling `modify` before the first `set` returns -`Error::NotPublished`. Container writes measure bitrate; importers can also -measure batch span or reorder delay for jitter. Locally encoded frames call -`container::Producer::flush(timestamp, Instant::now())`; jitter is the spread -above that track's own recent minimum lateness, and delay is how far that -minimum trails the earliest track on the same catalog. The first rise publishes -the catalog at once; later rises within a second stay in the catalog and go out -with the first frame after that second, or with any earlier structural edit. -There is no timer, so a rise held when media stops waits for the next frame, -and `finish` does not publish it. -`import::Track::discontinuity()` marks a source seek or -pause, clears partial input, and restarts the flush baseline without lowering -advertised values. It forwards the container timeline marker, so resumed -timestamps must continue forward on the broadcast clock. Generic imports remain -clock-free. Invalid or decreasing jitter or delay is rejected before the edit is -retained, including while the initial catalog is reserved. -Codec importers propagate catalog and media errors through their configuration -and frame-writing methods. - -Data tracks go through the catalog too. `catalog.json_stream(track, config)` -(or `json_snapshot`, `binary_snapshot`, `binary_stream`) writes the track's -`json` or `binary` entry, measures an absent `bitrate` from the writes, and -retires the entry when the producer drops. To list the track in your own -section beside application fields, pass that section's entry instead of a -`json::Config` or `binary::Config`: any `RenditionConfig` that embeds the data -config through `AsMut`. - -```rust -#[derive(Serialize, Deserialize, Clone)] -struct Mavlink { - config: hang::catalog::BinaryConfig, // mode, compression, bitrate, ... - sysid: u8, -} - -impl AsMut for Mavlink { - fn as_mut(&mut self) -> &mut hang::catalog::BinaryConfig { - &mut self.config - } -} - -// Plus `RenditionConfig` writing to `catalog.ext.mavlink`, a map -// serialized under the `com.example.mavlink` root key. -let config = hang::catalog::BinaryConfig::new(hang::catalog::Mode::Stream); -let mut telemetry = catalog.binary_stream(track, Mavlink { config, sysid: 1 })?; -telemetry.append(packet)?; -``` - -The producer sets the entry's `mode` and encodes the track with its -`compression`. Read it back from `Catalog` and subscribe with -`catalog::Entry::new(name, &entry.config)`. - -A payload timed on the broadcast clock is written at that timestamp as given, -and the entry advertises `jitter` and `delay` the way a media rendition does, so -telemetry lagging its video shows up as `delay`. A capture `Instant` (a -datagram's arrival, a sensor read) converts with `Clock::capture` on the -catalog's clock, which refuses an instant ahead of now. A timestamp ahead of now -is published anyway and measured as zero delay, so a source clock running -slightly fast is not rejected. Capture inputs stay `std::time::Instant` on -native; browser targets refuse these native instants. - -```rust -let at = catalog.clock().capture(received_at)?; -telemetry.append(moq_net::Timed::from(packet).at(at))?; -``` - -A timestamp carried over from elsewhere is published unchanged too: a source's -own timestamp on a catalog clock anchored to that source (KLV beside video from -one MPEG-TS program), or the `at` of a consumed `Timed` the payload was derived -from. It lines up with media only on a broadcast sharing the source's clock -mapping. A device's own clock is an unrelated epoch; keep it in the payload. - -The fMP4, MPEG-TS, FLV, and MKV importers publish the source's own timestamps -(MPEG-TS after unwrapping its 33-bit PTS; fMP4 passthrough keeps each `tfdt`) -and anchor the catalog's broadcast clock instead: the first frame's timestamp -maps to the time it arrived, and every track of the input, like every importer -sharing the catalog, keeps that one mapping. Each importer withholds the -catalog until that first frame, so its first snapshot already carries the -anchored root `clock` for readers that copy it once. Data tracks stamp on the -clock too, even one created before that first frame, though anything it wrote -earlier stays on the clock the catalog started with. A clock set with -`Config::with_clock` is never re-anchored, for a recording whose zero names its -real start. The broadcast clock uses the async runtime's monotonic time, so -native tests can pause and advance it with Tokio; its wall mapping stays fixed. - -Group starts never go backwards. A group starting before the previous group's -start ends the import with `TimestampRewind`, whose `timestamp` and `floor` fields -name the refused frame and the previous group's start; the message gives both in -microseconds. A restarted encoder or a looping file wrapping to the top does this, -flagged MPEG-TS discontinuity or not; republish it as a new broadcast. Frames may -still dip below the previous group's content: -B-frames, and a keyframe overlapping the previous group's last frame. A flagged -MPEG-TS discontinuity that jumps forward continues the broadcast. +Importers fill the catalog from the bitstream, split groups at keyframes, and +publish the source's own timestamps. The catalog clock maps the first frame to +the time it arrived, and every track keeps that one mapping. The catalog is +held until that first frame, so the first snapshot already carries the final +clock. A group that starts before the previous group's start ends the import; +a keyframe that merely overlaps the previous group's last frame does not. A +flagged MPEG-TS discontinuity that jumps forward continues the broadcast and +is declared on the exported clock. + +fMP4 export writes one fragment per group, and fixes the track set at the init +segment. A rendition that returns with the same configuration reuses its track. +A new rendition, a changed configuration, or a replay of media already written +ends the export. Restart it to pick up the new set. Other tracks queue for up +to 30 seconds while the init waits on a description. + +MPEG-TS import takes one program unless asked otherwise. The +[CLI page](/bin/cli) covers multi-program publishing, damaged packets, and the +feed checks. Those checks grade the input; they do not change the broadcast. + +Data tracks are catalog entries too. The [hang page](/concept/hang#data-tracks) +describes the modes. A capture time converts onto the broadcast clock; a +timestamp taken from the source is published as given and lines up with media +only when they share that clock. ```bash cargo add moq-mux ``` -API: [docs.rs/moq-mux](https://docs.rs/moq-mux). Real-world usage: -[`rs/moq-cli`](https://github.com/moq-dev/moq/tree/main/rs/moq-cli). - -Container producers and consumers take a format configured from the track's audio -or video catalog entry (`catalog::hang::Container::try_from(&config)`). For a raw -track, supply `container::Kind` explicitly. `cut(Some(end))` flushes and closes the -group immediately. Legacy and LOC video write an empty timestamped frame at that end; -audio and CMAF do not. With no explicit end, the producer uses a known sample -duration or observed cadence, independently of batching and reorder jitter. -Streaming consumers deliver frames immediately. The live fMP4 exporter receives -duration endpoints as metadata and uses them to time samples still buffered when -the group closes. Fetched groups retain their trailing frame until the marker or -group completion arrives. +API: [docs.rs/moq-mux](https://docs.rs/moq-mux). The commands that exercise it +are [`moq-cli`](/bin/cli). diff --git a/doc/lib/rs/moq-net.md b/doc/lib/rs/moq-net.md index 34ca1486b18..a0c2b741186 100644 --- a/doc/lib/rs/moq-net.md +++ b/doc/lib/rs/moq-net.md @@ -9,30 +9,16 @@ description: The pub/sub layer [![docs.rs](https://docs.rs/moq-net/badge.svg)](https://docs.rs/moq-net) The networking layer: real-time pub/sub with caching, fan-out, and -prioritization on top of QUIC. It negotiates [moq-lite](/concept/moq-lite) or -IETF moq-transport at setup and presents one API either way. Media is a layer -above ([hang](/lib/rs/hang)); relays and CDNs implement only this. +prioritization. It negotiates [moq-lite](/concept/moq-lite) or IETF +moq-transport at setup and presents one API either way. Media is a layer above +([hang](/lib/rs/hang)); relays and CDNs implement only this. -## What it gives you +What you use it for, beyond what the concept page already describes: -- **Origins** scope what a session can see, and merge duplicate subscriptions so a broadcast is pulled upstream once no matter how many local readers. -- **Broadcasts** are created unannounced and invisible to everyone, then announced as an exact route, or served below a prefix with `dynamic`. A consumer of the same origin sees exactly what a peer sees. Discovery accepts pattern unions; events carry the advertised prefix and captures for a complete match. -- **Epochs** identify publisher instances with a canonical UUIDv7 carried on each route (`Route::epoch`): the newest wins a path, and only routes with the same epoch resume a subscription; see [publisher epochs](/concept/moq-lite#publisher-epochs). -- **Patterns** (`Pattern`, `Patterns`) are re-exported from [`moq-pattern`](https://docs.rs/moq-pattern). Literal `Path` stays a coordinate. -- **Tracks** carry groups with a priority, an optional publisher retention window (`Info::max_age`), and a timescale. Subscribers set their own priority and max delay and can change them live. -- **Groups** are written frame by frame and delivered on independent streams. Old groups are cached for fetch-by-sequence; stale groups are skipped per the subscriber's budget. -- **Track ends**: `finish()` ends a track at its live edge, while `finish_at(n)` declares the exclusive end ahead of it and still accepts the groups below. A subscriber awaits it with `finished()`. A remote track ends only once every group below its end has arrived or was dropped; one reset before its header arrived is skipped after the subscription's max delay on moq-lite (one second without one), or after one second on IETF. -- **Datagrams** send a single small frame unreliably on moq-lite 05+ and moq-transport. -- **Routes** record the relay hops and a cost, which is what the relay [cluster](/bin/relay/cluster) routes on. A hop of 0 marks the chain anonymous: `Route::is_anonymous()` is true, and that route ranks below every fully identified one. `Route::source()` says where a delivered route entered: `Source::Local`, or `Source::Peer(hop)` when a handle marked `origin::Producer::peer()` announced it. `origin::Consumer::local()` sees only the local ones. A handle marked `origin::Producer::upstream()` announces as a peer, and a consumer taken from it never sees a route another upstream handle announced, so a relay never transits between two upstream links. -- **Stats** counters per broadcast and session, drained by [`moq-stats`](https://docs.rs/moq-stats). - -It runs over its own `moq_net::transport::poll::Session`, `SendStream`, and -`RecvStream` traits. Implement these for a custom transport; session clones keep -independent operation state, and errors expose session and stream codes separately. -[`moq-tokio`](https://docs.rs/moq-tokio) adapts native backends, `moq-wasm` adapts -browser WebTransport, and `moq-uring::transport::Session::new` wraps a poll backend -without adding thread bounds. `moq-net` does not depend on `web-transport-trait`, -so backend trait upgrades affect their adapters rather than this public API. +- **An origin outlives the session.** Broadcasts are created on the origin, and a reconnect announces them again. Closing the session does not delete them. +- **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 consumer is not demand. A shared fetch stays up until its last reader leaves. +- **You drive the session, or `moq-tokio` does.** `connect` and `accept` return a session plus a driver that never reads the clock itself. `moq_net::time::run` polls it on tokio or in the browser. `moq-tokio` and `moq-wasm` hide that. A custom transport implements `moq_net::transport::poll`. +- **A graceful close waits.** `session.close().await` withdraws announcements and gives finished tracks up to one second to deliver. `abort` ends immediately. IETF drafts 14 through 16 send withdrawals without waiting. ```bash cargo add moq-net moq-tokio @@ -40,170 +26,5 @@ cargo add moq-net moq-tokio See the [Rust quick start](/lib/rs/#quick-start) and [docs.rs/moq-net](https://docs.rs/moq-net). The TypeScript twin is -[`@moq/net`](/lib/js/net). The [path pattern](/concept/moq-lite#path-patterns) -grammar lives on the concept page. - -## Driving sessions - -`Client::connect(now, transport)`, `Server::accept(now, transport)`, and -`server::Handshake::ok()` return `(Session, Driver)`. Drivers never spawn -tasks or read the clock: the caller polls the driver and supplies the time. -`moq_net::time::run` does that on tokio or in the browser. - -```rust -let now = tokio::time::Instant::now().into_std(); -let (session, driver) = client.connect(now, transport).await?; -tokio::spawn(moq_net::time::run(driver)); -``` - -On moq-lite-05+ and moq-transport draft 17+, `Client::connect` returns before -the server's SETUP arrives, so a request made at once may still be -refused along with it. `session.setup().await` waits for the server's SETUP -and returns the close reason if the session is already closed, even after SETUP. A moq-rs -server sends its SETUP only once it admits the client; neither protocol -requires that, so another server may still refuse afterward. Older versions -read that SETUP during the handshake and resolve at once, except moq-lite-03 -and -04, which carry none and return `Error::Unsupported`. - -A custom event loop calls `driver.poll(now, waiter)` with a nondecreasing -`moq_net::time::Instant`. `Ok(Some(at))` asks to be polled again by `at` or -on external activity, `Ok(None)` only on external activity, and `Err` is the -terminal error (`Error::Closed` for a clean finish): stop polling. Tests drive -the same interface with explicitly advanced instants. - -Dropping the last session handle requests closure on the next poll, and -`session.abort(err)` closes with `err`'s code. Either discards stream data the -peer has not acknowledged yet. `session.close().await` first waits, up to one -second, for finished tracks to deliver their last groups and FIN, returning -`Error::Timeout` if it gave up. Finish or abort live tracks before calling it. -Both protocols withdraw the session's announcements and wait for delivery -under that same deadline. IETF drafts 14 through 16 send withdrawals without -waiting. Dropping the driver cancels the session. `moq-tokio` and `moq-wasm` -drive sessions for their callers. A deliberate local session close ends -received tracks cleanly after their delivered groups. A peer close ends -received tracks and open group readers with the session error, preserving its -close code. - -`origin::Producer::new` returns a driver with the same `time::Driver` -interface. It calls `cache::Pool::gc(now)` after each poll and folds the next -cleanup time into its returned deadline. A standalone pool needs `gc(now)` -called by its owner, at least by the returned deadline; `None` means expiry is -disabled. - -The origin driver finishes once every owner is gone: each `origin::Producer` -clone, published broadcast, and `origin::Dynamic`. Producer-side children pin -their parent where no cycle exists, so a handler can drop its producer and keep -serving. Read handles (`origin::Consumer`, announce cursors) never pin it: they -see `Closed` once the owners are gone. - -Cache activity is dated lazily: reads and writes mark a group active without -reading a clock, and the next `gc` pass stamps it with the supplied instant. -Expiry is therefore approximate; a late `gc` extends retention. - -## Patterns - -`Pattern` describes a set of paths; `Patterns` is a union reduced by -containment. `contains` is the authorization check (every path the other -matches, this one matches too). `overlaps` asks whether they share any path. -`rooted` places a pattern under a literal root; `rebase` is the inverse, and -can return several residuals (`**/a` at `a` is both `""` and `**/a`). -`intersect` returns the exact overlap as a union, and `captures` reports what -one pattern's wildcards stand for in a contained pattern. - -```rust -use moq_net::Pattern; - -let scope: Pattern = "room/**".parse()?; -assert!(scope.matches("room/alice")); -assert!(scope.contains(&"room/camera-*".parse()?)); -assert!(scope.overlaps(&"*/alice".parse()?)); -assert_eq!( - scope.intersect(&"*/alice".parse()?)? - .iter().map(Pattern::as_str).collect::>(), - ["room/alice"] -); -assert_eq!( - scope.rebase("room").iter().map(Pattern::as_str).collect::>(), - ["**"] -); -assert_eq!( - "camera-*".parse::()?.rooted("room")?.as_str(), - "room/camera-*" -); -``` - -## Advertising - -Three operations, on an origin: - -- `origin.publish(path, route)` creates and advertises a broadcast in one call. -- `origin.create_broadcast(path)` returns a producer. The broadcast is - invisible and unroutable, for local consumers and peers alike, until - `broadcast.announce(route)`. -- `broadcast.announce(route)` / `broadcast.unannounce()` own that - advertisement. Announcing again replaces the standing route as given, epoch - included, so re-price from the current one - (`broadcast.announce(broadcast.route().unwrap_or_default().with_cost(c))`); - another epoch, or none, announces a new broadcast; `origin::Dynamic` has the - same `route()` and `update(route)`. The route competes with - remote routes at the same path: the newest epoch wins, then the cheapest (a - tie goes to the local broadcast). The route retracts on `unannounce()`, `close()`, or the last - producer dropping; tracks already in flight carry on to their own end. -- `broadcast.close()` ends the broadcast for good: it retracts, leaves local - discovery, and answers every later track lookup with `Unroutable`. Tracks - already subscribed carry on to their own end. It can never be announced - again. Dropping the last producer does the same. -- `origin.dynamic(prefix, route)` claims `prefix` and every path beneath it - (`""` claims everything). Hold the returned `origin::Dynamic` while the - claim should stay advertised; drop it to retract. A request beneath it with - no winning announced local broadcast is a `Request` to `accept` or `reject`; reject what you - will not serve rather than narrowing the claim, since a route is always a - prefix on every wire. - -A route is a capability, not an inventory. Producer and consumer handles are -scoped by any `Patterns` union. A prefix route is allowed when its subtree -overlaps that scope; exact creates and requests must match it, so a broad -route can advertise the wire-compatible prefix while excluded requests are -refused locally. A disjoint route is `Unauthorized`. - -`origin.consume().announced()` yields `announce::Event`s: `Start`, -`Update` (a reprice in place), or `End`, each holding an -`announce::Announce` with `prefix`, the covered prefix relative to the -consumer's root; `captures`, what the most specific matching scope member's -wildcards stood for when the prefix pins them; and `route`, its hops and cost -(on a retraction, its last values). The consumer is also a -`futures::Stream`. A prefix is not a broadcast name; -sessions request each scope member's literal head and filter locally. Routes -with a `.`-prefixed segment below that head are [hidden](/concept/moq-lite#hidden-broadcasts) -unless `with_hidden(true)` opts the consumer in. Sessions always ask the peer -for hidden routes, so each local consumer decides. - -## Limiting reads - -Use `Subscription::default().with_groups(2..=5)` to request only groups 2 -through 5. `2..5` excludes group 5, and `..` leaves both ends unbounded. -The range limits the data eligible under the subscription's max delay budget; -it does not fetch historical data by itself. - -A reader's `set_groups(2..=5)` applies a local limit. It preserves read -progress: a lower start does not rewind the reader, and an omitted start -keeps its current floor. An omitted end removes the cap, making unread -buffered groups available again. Local limits do not update the -subscription's upstream request. - -Inside a group, `set_frames(...)` applies the same range syntax to frame -indices. - -## Subscriber demand - -Track producers, pending track requests, and dynamic track handlers return a -`track::Demand` from `demand()`. Group producers and pending group requests -return `group::Demand`; broadcast producers return `broadcast::Demand`. -Watch `used()` / `unused()` (or `poll_used` / `poll_unused`) on these handles, -or take a snapshot with `is_used()`. Demand handles cannot write or abort and -do not keep a producer or request alive. A pending group request counts every -caller sharing its fetch, so one caller leaving does not cancel the others. -The last caller to leave withdraws the fetch, so a later fetch of that group -starts a fresh request; a handler that sees the request unused just drops it. -Use the producer's `abort_unused` to atomically end an idle track; observing -unused demand alone does not protect against a new subscriber arriving. +[`@moq/net`](/lib/js/net). Path patterns are on the +[concept page](/concept/moq-lite#path-patterns). diff --git a/doc/lib/rs/moq-video.md b/doc/lib/rs/moq-video.md index 5b11f376746..b25e9afd0fd 100644 --- a/doc/lib/rs/moq-video.md +++ b/doc/lib/rs/moq-video.md @@ -9,7 +9,8 @@ description: Native capture, hardware codecs, and GPU rendering [![docs.rs](https://docs.rs/moq-video/badge.svg)](https://docs.rs/moq-video) What a browser gets from `getUserMedia` and WebCodecs, for native Rust: no -ffmpeg, no GStreamer, no system codec to install. +ffmpeg, no GStreamer, no system codec to install. `moq import capture` and +`moq play` are built on it. | Module | Does | Backends | | --- | --- | --- | @@ -18,263 +19,56 @@ ffmpeg, no GStreamer, no system codec to install. | `decode` | A subscribed track back to frames | VideoToolbox, Media Foundation/DXVA, NVDEC, VAAPI, V4L2 M2M, MediaCodec (Android), openh264, libvpx | | `render` | A frame as a `wgpu` texture | wgpu, with zero-copy Metal and Vulkan imports | -Highlights: - -- **Automatic backend selection**, hardware first. Linux GPU libraries are `dlopen`ed at runtime, so one binary starts anywhere and warns when it falls back to software. openh264 (the default-on `openh264` feature) is statically linked as the H.264 fallback; H.265 is hardware-only; AV1 decodes via NVDEC. VP8 and VP9 decode in software through libvpx (the opt-in `vpx` feature), 8-bit 4:2:0 only: other VP9 profiles are refused rather than converted. The VAAPI encoder, decoder, and GPU resize share one render node: the first whose driver does all three, or the one the `MOQ_VAAPI_DEVICE` environment variable names (for example `/dev/dri/renderD129`). -- **Publish on demand.** `encode::publish_capture` advertises the track up front and opens the camera only while someone subscribes. `encode::Control::new` is the same with a handle kept, the mirror of `moq-audio`'s: `Control::cut()` asks for a keyframe, requests coalesce, any keyframe serves them (the GOP cadence included), and a forced one lands at least 500ms after any other. On a backend that cannot force one, `cut()` returns `Error::CutUnsupported` once the startup probe or a reopen has found that out, and the publish carries on at its cadence. Frames are stamped on the catalog's clock, and dropping the last `Control` ends the driver promptly, even mid-open. -- **GPU ownership where the platform allows.** Matching codec backends consume their native GPU surfaces directly. The renderer imports `CVPixelBuffer` and supported DMA-BUF formats. Linux/NVIDIA producers can import dedicated Vulkan RGBA8 slots into CUDA with timeline-semaphore ordering and completion-driven slot return. Vulkan/CUDA surfaces deliberately have no CPU pixel fallback; other surfaces use the typed `Surface::into_i420()` and configured `Surface::to_rgba(config)` when needed. -- **Live bitrate control** where the selected backend supports it, without forcing a keyframe. An unsupported backend keeps its opening rate. -- **Latency presets.** `encode::Config::preset` picks `Preset::LowLatency` (the default), `Balanced`, or `Quality`, with bitrate set separately. `Encoder::applied()` and `Sink::applied()` report the preset whose controls actually took effect and names them for display. See [Encoder presets](#encoder-presets). -- **Typed group structure.** `encode::Config::gop` is a `Gop` enum (`Keyframe { interval }` today), so a later mode adds a variant instead of replacing the field. `cut()` opens a group at the next frame on both `Encoder` and `Sink`, and refuses with `Error::CutUnsupported` on a backend that cannot force one rather than letting the boundary silently slip to the interval. -- **Device enumeration** for cameras, displays, windows, and apps, matching `moq devices`. - -With `capture` enabled, `capture::camera_modes` lists a Linux camera's convertible -sizes and exact rates before configuring it. Rates are `moq_video::Rate`, an -exact rational that preserves 30000/1001: `frames(duration)` counts frames, -`rounded()` gives the nearest whole frame rate for integer-only platform APIs, -and `as_f64()` yields the catalog value. -Sizes and rates shared by YUYV and MJPEG are combined; invalid I420 dimensions -are excluded. A size range contributes its smallest and largest valid sizes aligned to the -driver's step, -and an empty rate list means no discrete intervals were reported. Device errors -are returned rather than treated as an empty list. Other platforms return -`Error::Unsupported`. - -Windows display and window capture require Windows 10 2004 (build 19041) or -newer and use Windows.Graphics.Capture without a Desktop Duplication or GDI -fallback. `Config::cursor` controls cursor capture. Frames leave the capture -pool as owned GPU NV12 textures; odd native edges are cropped to even sizes. -The conversion declares BT.601 limited range through 576 lines and BT.709 -limited range above it, preserving that color through resize and CPU download. -Media Foundation encodes on the capture device; openh264 uses the download path. -Display enumeration covers all adapters, and window enumeration excludes -DWM-cloaked windows and reports visible frame bounds. Windows `display:N` -selectors are enumeration indices, not persistent monitor identities. Switching -from Desktop Duplication to WGC can change their mapping; enumerate displays -again and reselect the intended monitor after upgrading. Enumeration does not -start capture. A settled source resize ends the stream so callers can reopen; -closing the captured item returns `Error::SourceUnavailable`. Dropping the -stream releases its session even when no new frames arrive. -If no usable first frame arrives within five seconds after capture starts, -opening fails with `Error::SourceUnavailable` and releases the session. - -Windows shows a capture border by default. On build 20348 or newer the backend -requests borderless access; denial keeps the border and does not fail capture. -Older supported builds keep the border. Application capture and system audio -are not provided by this backend. - -X11 display and window capture use MIT-SHM 1.2 fd-backed buffers on local Unix -connections. Remote connections and servers without that support use -`GetImage`. Shared-memory setup or read failures are reported rather than -silently switching paths. RandR events refresh monitor geometry; window -`ConfigureNotify` events update the captured size. A settled size or monitor -change ends the stream so callers can reopen. Unmapped windows hold capture -until viewable again. RGB conversion reuses its buffer. - -On Linux, `just rs x11-bench` compares the production SHM and `GetImage` -capture paths on the current local X display, which must be at least 1920×1080 -and support MIT-SHM 1.2. It checks pixels for static and changing images at -three sizes and records paired median frame times and their ratio. Timings -include RGB and I420 conversion; capture pacing and fixture drawing are not -measured. The GetImage baseline keeps the same event handling and buffer reuse, -so it isolates transport rather than comparing the entire pre-quest backend. -`just rs x11-rgb-bench` isolates conversion-buffer allocation. - -`just rs x11-bench-ci` runs both workloads with an isolated Xvfb server and -writes `.scratch/x11-capture-benchmark.log` (override with `MOQ_X11_BENCH_LOG`). -PR and nightly CI retain the log for 30 days, including the source commit, -paired GetImage baseline and SHM/baseline ratios. Compare those -records across runs to investigate regressions; timing has no hard threshold -until runner variance is measured. Missing SHM support or incorrect pixels -fails the test. Xvfb coverage does not replace real-desktop capture, lifecycle -and before/after performance checks. - -With `pipewire` enabled, `capture::cameras` also lists PipeWire camera nodes as -`pipewire:` after the V4L2 devices. V4L2 lists only devices offering -YUYV or MJPEG. A PipeWire V4L2 node is hidden only when its device path was -already listed by V4L2, so identical webcams stay distinct, and PipeWire-only -cameras and NV12- or RGB-only V4L2 devices remain visible through PipeWire. Explicit `pipewire:` -selectors still open hidden nodes, and `pipewire` alone opens the -camera with the highest session priority, the session manager's default. That -reaches cameras V4L2 cannot: a Raspberry Pi CSI camera behind libcamera, and any -camera from inside a Flatpak or Snap sandbox, where the default camera comes -through the xdg-desktop-portal Camera interface. The mode is chosen from the -node's own format list by the same rules as V4L2 (below) and offered exactly, -across YUY2, NV12, RGB, and MJPEG, and `camera_modes` lists the same modes. - -`capture::Config::framerate` is an `Option` request in the same exact -type; the stream reports the rate the device accepted, or `None` when the -driver reported none. -V4L2 and PipeWire cameras choose the closest geometry, then the format whose -accepted rate is nearest the request, then the cheaper conversion when both -match equally well. - -```rust -let mut video = moq_video::decode::Consumer::new(&broadcast, &rendition, "video", Default::default()).await?; -let mut renderer = moq_video::render::Renderer::new(&device, &queue, Default::default())?; -while let Some(frame) = video.read().await? { - let texture = renderer.render(&frame)?; -} -``` - -```bash -cargo add moq-video # nvidia, mediacodec, openh264 on by default -cargo add moq-video --features capture # camera + screen capture, no system build deps -cargo add moq-video --features render # wgpu rendering -cargo add moq-video --features v4l2 # Linux V4L2 M2M codecs, no system build deps -cargo add moq-video --features vaapi # Linux VAAPI codecs (bindgen needs libclang) -cargo add moq-video --features pipewire # Wayland screen + PipeWire cameras (links libpipewire) -cargo add moq-video --features vpx # VP8/VP9 decode (links libvpx; VPX_STATIC=1 for the archive) -cargo add moq-video --no-default-features --features openh264 # software H.264 only -cargo add moq-video --no-default-features --features nvidia # Linux NVIDIA only, no C++ or wgpu -``` - -The language bindings use the codec-only shape, which is what keeps their -Android floor at API 24 instead of MediaCodec's API 26 entry points. +Selection is automatic and hardware first. Linux GPU libraries are `dlopen`ed, +so one binary starts anywhere and warns when it falls back to software. +openh264 is the H.264 fallback and is on by default. H.265 is hardware-only. +AV1 decodes through NVDEC. VP8 and VP9 decode in software through the opt-in +`vpx` feature, 8-bit 4:2:0 only. + +`encode::publish_capture` advertises the track up front and opens the camera +only while someone subscribes. Backends that can change bitrate live follow +the connection's send estimate without forcing a keyframe. `cut()` asks for a +keyframe and returns an error on a backend that cannot force one, rather than +quietly waiting for the GOP. + +Where the platform allows it, frames stay on the GPU: the renderer imports +`CVPixelBuffer` and supported DMA-BUF formats, and an NVIDIA path can pass +Vulkan frames to NVENC without a CPU copy. Vulkan and CUDA surfaces have no +CPU fallback; other surfaces can be read back. + +`encode::Config::preset` is `LowLatency` (the default), `Balanced`, or +`Quality`. The encoder reports the preset whose controls actually took effect. +Only NVENC and openh264 change compression with the preset. VideoToolbox and +VAAPI have one low-latency mode and report that. Media Foundation, MediaCodec, +and V4L2 do not report one. A preset does not change keyframe interval or +viewer buffering. + +## Windows + +Display and window capture need Windows 10 2004 (build 19041) or newer and use +Windows.Graphics.Capture. There is no Desktop Duplication fallback. The system +capture border stays unless the OS grants borderless capture (build 20348 or +newer). Application capture and system audio are not provided. +`display:N` is an enumeration index, not a stable monitor id, so a saved +selector can name a different screen after an upgrade. Enumerate again with +`moq devices`. A resize or a closed window ends the stream so the caller can +reopen. If no frame arrives within five seconds, opening fails. + +## Linux + +Local X11 display and window capture uses shared memory. Remote displays and +servers without it use `GetImage`, and a failure is reported rather than +switched over silently. A settled resize ends the stream. Unmapped windows +hold capture until they are viewable again. + +Intel QuickSync is the opt-in `vaapi` feature, off by default because the +build needs libclang. It encodes and decodes 8-bit H.264. At runtime, libva +and the Intel `iHD` driver must be installed and the user must be able to open +`/dev/dri/renderD*`. `MOQ_VAAPI_DEVICE` picks a node when several GPUs are +present. Automatic selection uses VAAPI when it opens, and H.264 can still +fall back to openh264. Naming the backend requires it. + +PipeWire cameras and `--display` on the CLI need the `pipewire` feature. API: [docs.rs/moq-video](https://docs.rs/moq-video). Pair with [`moq-audio`](/lib/rs/moq-audio). - -`decode::Config::output` chooses where decoded pictures live. `Output::Native`, -the default, hands back whatever the backend decoded into: a `CVPixelBuffer`, a -Direct3D11 texture, a CUDA buffer, a VAAPI DMA-BUF for zero-copy rendering, or -CPU pixels from a software decoder. `Output::Cpu` delivers every picture as -`Surface::I420`, decoded straight to system memory where the backend can. -Native surfaces still answer `Surface::into_i420()`, which returns an `I420` -with geometry and color metadata intact; call `I420::into_data()` only when -packed bytes are required. `decode::Config::scale_hint` is best effort and only -a decoder with a hardware scaler honors it; `Frame::resize` is the exact-size -operation. `decode::Consumer` takes `decode::Options`, which carries the -subscription's `start` and `max_delay` beside the decoder config. - -Linux/NVIDIA applications with a native Vulkan producer use -`frame::vulkan::Importer`. Each reusable image is a dedicated, optimal-tiling -`VK_FORMAT_R8G8B8A8_UNORM` allocation exported with an opaque memory FD, plus an -opaque-FD timeline semaphore and the physical-device UUID. Publishing consumes -the producer-owned slot; awaiting its completion returns that slot only after -CUDA readers finish. Import capacity bounds retained images. Unsupported -devices, formats, layouts, and synchronization are errors, with no CPU mapping -or staging fallback. A non-exportable application image needs one Vulkan GPU -copy into an exportable slot. The image is `VK_FORMAT_B8G8R8A8_UNORM` when -imported through `Image::bgra8` instead. - -`frame::cuda::Converter` turns a published Vulkan frame into the NV12 -`Surface::Cuda` NVENC encodes in place, on the GPU, in one declared color space -(matrix and range) with 4:2:0 chroma averaged per 2x2 block and no transfer -function applied. Its buffers come from a pool sized at construction: -`Converter::reserve` holds one as a `cuda::Slot`, which `Slot::convert` fills -with the captured frame or `Slot::resize` with a smaller rendition of it. One -captured frame feeding HD and SD holds a fixed number of buffers, and a producer -that outruns its encoder gets `None` from `reserve`, its cue to drop the frame, -instead of unbounded device memory. A slot dropped unfilled, or consumed by a -failed conversion, returns its buffer, so only a real failure is an error. Open the encoder with `encode::Kind::Named("nvenc")` -and the same `encode::Config::color`: `Kind::Auto` could fall back to a software -encoder that reads the frame back, and the portable `Surface::resize` downloads -when the GPU scaler fails. Everything under `frame::cuda` and `frame::vulkan` -runs on the device or returns an error. - -## Encoder presets - -A preset trades per-frame encode time for compression at the configured -bitrate. None reorders frames, and none describes keyframe join time, transport -delay, or viewer playout. Each backend maps a preset onto the controls it has, -and reports what it applied rather than echoing the request: - -| Backend | Low latency | Balanced | Quality | -| --- | --- | --- | --- | -| NVENC | P1 | P4 | P7 | -| openh264 | low complexity | medium complexity | medium complexity, reported as Balanced | -| VAAPI | IDR/P only, one frame in flight | same, reported as Low latency | same, reported as Low latency | -| VideoToolbox | real-time, no reordering | same, reported as Low latency | same, reported as Low latency | -| Media Foundation, MediaCodec, V4L2 | unconfirmed, no preset reported | unconfirmed | unconfirmed | - -NVENC always uses low-latency tuning, CBR, and a one-frame VBV. Only NVENC and -openh264 were measured. VAAPI and VideoToolbox report the one set of controls -their code applies. Media Foundation and MediaCodec only request low latency, -and V4L2 leaves frame reordering to the driver, so they report no preset until -someone measures that hardware. - -Measured on an RTX 3070 Ti and a 32-thread x86 host under load from other jobs, -encoding Big Buck Bunny at 720p30 and 1.5 Mbps. Frame-to-packet is the time -from `encode` to the packet stamped with that frame, including the CPU upload. -Encode is NVENC's submit and output lock alone, timed with temporary -instrumentation. Quality is PSNR and SSIM against the source. - -| Backend | Preset | Frame-to-packet p50 | Encode p50 | PSNR | SSIM | -| --- | --- | --- | --- | --- | --- | -| NVENC H.264 | Low latency | 4.6 ms | 1.6 ms | 39.19 dB | 0.9787 | -| NVENC H.264 | Balanced | 5.7 ms | 2.1 ms | 39.22 dB | 0.9789 | -| NVENC H.264 | Quality | 6.3 ms | 3.3 ms | 39.26 dB | 0.9792 | -| NVENC H.265 | Low latency | 5.7 to 8.0 ms | 1.9 to 2.2 ms | 39.62 dB | 0.9809 | -| NVENC H.265 | Balanced | 7.2 to 8.2 ms | 2.9 to 3.3 ms | 39.72 dB | 0.9815 | -| NVENC H.265 | Quality | 7.6 to 8.1 ms | 3.1 to 3.4 ms | 39.73 dB | 0.9816 | -| openh264 | Low latency | 10.6 ms | | 39.87 dB | 0.9818 | -| openh264 | Balanced | 12.2 ms | | 39.92 dB | 0.9823 | - -Ranges span two runs. About half of NVENC's frame-to-packet time is allocating -input and output buffers per frame, the same cost for every preset. - -At 1080p30 and 4 Mbps on synthetic moving content, NVENC H.264 encode rises from -3.2 ms (P1) to 3.8 ms (P4) and 6.7 ms (P7), and openh264 frame-to-packet from -20.8 to 22.4 ms. No backend measured here held a frame: each packet came back -from the call that submitted it. openh264 skips frames to hold its rate (11 of -300 at 720p). p95 frame-to-packet ranged 6 to 25 ms and tracked host load, not -the preset. Other backends need their own run: -`cargo run --release -p moq-video --example encode-presets` reports -frame-to-packet latency, throughput, CPU time, held and skipped frames, and -bitrate per preset, and writes each stream for scoring with ffmpeg. - -An `Encoder` or `Sink` takes one frame per call and queues none of its own. A -source that outruns the codec should drop raw frames it has not submitted, -never encoded packets. - -`just rs vulkan-cuda` runs the opt-in native Vulkan/CUDA/NVENC hardware -exercise, including a three-view 1280x720 workload that reports per-stage -latency and CPU time. - -## Intel QuickSync on Linux - -Enable the `vaapi` feature to use Intel QuickSync through VA-API. It is off by -default because building `moq-vaapi` needs libclang. The backend currently -encodes and decodes 8-bit H.264; HEVC and AV1 support in the Intel driver does -not make those codecs available through this backend yet. No oneVPL or Media -SDK installation is needed. - -At runtime, install libva and the Intel `iHD` media driver, and make sure your -user can open the GPU's `/dev/dri/renderD*` node. On Ubuntu: - -```bash -sudo apt install intel-media-va-driver-non-free vainfo -vainfo --display drm --device /dev/dri/renderD128 -``` - -Use the render node present on your machine. `vainfo` should report the Intel -iHD driver with H.264 `VAEntrypointVLD`, `VAEntrypointEncSlice` or -`VAEntrypointEncSliceLP`, and `VAEntrypointVideoProc`. Intel's -[media driver documentation](https://github.com/intel/media-driver) lists -supported GPUs and the differences between the full-feature and free-kernel -packages. - -Automatic encoder and decoder selection uses VAAPI when it opens successfully, -otherwise H.264 can fall back to openh264. Set `encode::Kind::Named("vaapi".into())` -and `decode::Kind::Named("vaapi".into())` to require this backend and report an -unavailable driver instead. `MOQ_VAAPI_DEVICE` selects a render node when -multiple GPUs are present. - -Verified on Intel Core Ultra 7 270K Plus / Arrow Lake with iHD 26.2.4: CPU -uploads, hardware decode, DMA-BUF re-encoding, GPU resize, live bitrate changes, -color metadata, and Vulkan rendering with decoder surface reuse. To run the -same checks from this repository: - -```bash -just rs test -p moq-video --features vaapi,render --no-capture -just rs test -p moq-video --features vaapi,render --run-ignored only --no-capture \ - -E 'test(nv12_dmabuf) | test(i420_dmabuf) | test(decoded_frames_reach) | test(recycled_decoder_surfaces)' -``` - -Hardware tests can return early on a host without a usable driver. Check their -output for `skipping:` before treating a passing run as hardware verification. -Nix-built tests also need their runtime loaders and drivers to be discoverable: -`LD_LIBRARY_PATH` for libva and Vulkan, `LIBVA_DRIVERS_PATH` for the Intel media -driver, and `VK_DRIVER_FILES` for the Intel Vulkan ICD. Use matching Nix -libraries and drivers to avoid mixing incompatible host dependencies. diff --git a/js/net/README.md b/js/net/README.md index c992b87e514..c3ee496576a 100644 --- a/js/net/README.md +++ b/js/net/README.md @@ -12,7 +12,7 @@ A TypeScript [Media over QUIC](https://moq.dev/) (MoQ) client for both browsers Check out [hang](../hang) for a higher-level media library that uses this package. -> **Note:** moq-lite is a subset of moq-transport and is forwards compatible with it, so this client works with any moq-transport CDN (ex. [Cloudflare](https://moq.dev/blog/first-cdn/)). See the [compatibility docs](https://doc.moq.dev/concept/moq-lite#compatibility) for details. +> **Note:** moq-lite is a subset of moq-transport and is forwards compatible with it, so this client works with any moq-transport CDN (ex. [Cloudflare](https://moq.dev/blog/first-cdn/)). See the [compatibility docs](https://doc.moq.dev/concept/moq-lite#what-moq-lite-leaves-out) for details. ## Quick Start diff --git a/rs/moq-e2ee/README.md b/rs/moq-e2ee/README.md index c6c85d68b21..f19dc518bb3 100644 --- a/rs/moq-e2ee/README.md +++ b/rs/moq-e2ee/README.md @@ -8,7 +8,7 @@ End-to-end encryption for [Media over QUIC](https://moq.dev) groups, datagrams, and track names. Profile `moq-e2ee-00` from [draft-lcurley-moq-e2ee](https://datatracker.ietf.org/doc/draft-lcurley-moq-e2ee/). -Relays forward ciphertext. Content keys never enter `moq-net`. The TypeScript twin is `@moq/e2ee`. +Relays forward ciphertext. Content keys never enter `moq-net`. ```bash cargo add moq-e2ee From 36e27657d5edc576cda70b32c659dde7970c8503 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Wed, 7 Oct 2026 14:28:57 -0700 Subject: [PATCH 02/12] docs: scope epoch claims to lite-07, add doc/AGENTS.md Restart takeover only happens on opt-in moq-lite 07, and the RTMP, SRT, and WHIP ingests announce without an epoch. Also fixes the draft-19 update wording, the window-mode reason, and the import ts silence line. doc/AGENTS.md keeps the site an entry point for features, with reference detail left to API docs and drafts. Co-Authored-By: Claude Opus 5.5 --- doc/.vitepress/config.ts | 3 +++ doc/AGENTS.md | 10 ++++++++++ doc/bin/cli.md | 19 ++++++++----------- doc/bin/gstreamer.md | 6 +++--- doc/concept/standard.md | 2 +- doc/concept/use-case/contribution.md | 16 ++++++++-------- doc/concept/use-case/index.md | 2 +- doc/lib/js/json.md | 2 +- doc/lib/rs/moq-json.md | 2 +- 9 files changed, 36 insertions(+), 26 deletions(-) create mode 100644 doc/AGENTS.md diff --git a/doc/.vitepress/config.ts b/doc/.vitepress/config.ts index bb6d10e60cb..973ccbcf7c2 100644 --- a/doc/.vitepress/config.ts +++ b/doc/.vitepress/config.ts @@ -263,6 +263,9 @@ export default defineConfig({ ], }, + // Agent instructions, not a page. + srcExclude: ["AGENTS.md"], + ignoreDeadLinks: [ // Localhost URLs are intentional for development examples and aren't // reachable at build time (e.g. the relay on :4443, the dev server on :5173). diff --git a/doc/AGENTS.md b/doc/AGENTS.md new file mode 100644 index 00000000000..0a30d36e678 --- /dev/null +++ b/doc/AGENTS.md @@ -0,0 +1,10 @@ +`doc/` is the entry point to the repo: what exists, what it is for, and how to start. +It is not the reference. Rustdoc, TSDoc, `--help`, and `drafts/` are, and they sit next to the code so they stay accurate. + +- Document features, and the behavior a user must know to choose or use one. +- Leave method and field lists, wire encodings, error codes, and per-version accounting to the API docs and drafts. Link to them. +- A code change touches `doc/` only when it changes what a reader would do. A fix, a new knob, or an edge case belongs in the API doc. +- Edit the paragraph that already covers the topic instead of appending a new one. When a page grows, cut something. +- Weight follows importance to a user, not how recently something changed. +- State a claim's conditions with it: opt-in or experimental versions, and the paths it does not cover. +- Describe only what ships. Plans live in quests. diff --git a/doc/bin/cli.md b/doc/bin/cli.md index be7227ad38c..19f45630de9 100644 --- a/doc/bin/cli.md +++ b/doc/bin/cli.md @@ -79,7 +79,7 @@ ends the import like any other rewind. The same flag on an elementary PID other continuity-counter gap, and the 33-bit timestamp rollover move no clock and declare nothing. FLV covers H.264 + AAC. -`import ts` logs a video or audio PID that stops delivering access units, and +`import ts` logs an elementary stream that stops delivering access units, and counts ETSI TR 101 290 errors on the feed it receives. A sparse PID such as SCTE-35 goes quiet between cues, so that line reports rather than alarms. Neither check changes what is published, and the PCR checks grade the encoder's @@ -359,16 +359,13 @@ moq --connect https://relay.example.com/anon \ ## Publisher runs -Each publishing command (`import`, `transcode`, archive replay, HLS or WebRTC -ingest) announces a fresh [publisher epoch](/concept/moq-lite#publisher-epochs) -for that process. A restart is a new run: viewers move to it instead of waiting -for its group numbers to catch the old sequence. Reconnects inside one process -keep the epoch, so a blip resumes mid-group. - -Each process mints its own epoch, so the newer run takes the name and viewers -of the older run move to it. Mid-group failover needs both routes to carry the -same epoch. The CLI keeps one epoch for the life of the process and does not -share it with another process. +Each run of `moq` announces its own +[publisher epoch](/concept/moq-lite#publisher-epochs), kept across reconnects. +On moq-lite 07 (opt-in), a restarted or second process is a newer epoch, so +viewers move to it instead of waiting for its group numbers to catch up. On +older versions a subscription stays on the route it first resolved through +until that route goes. The RTMP, SRT, and WHIP ingests announce without an +epoch. ## Cluster diff --git a/doc/bin/gstreamer.md b/doc/bin/gstreamer.md index f8da91af426..3e101b0425a 100644 --- a/doc/bin/gstreamer.md +++ b/doc/bin/gstreamer.md @@ -57,9 +57,9 @@ Each `sink_%u` request pad is one track. Pad properties: `track` names it `sessions`. The sink reconnects for as long as the pipeline runs and only reports `failed` on an answer redialing can't change, such as a rejected token. Each run from `READY` publishes under a fresh -[publisher epoch](/concept/moq-lite#publisher-epochs), so viewers switch to a -restarted pipeline at once instead of stalling on the old one; reconnects -within a run keep it. +[publisher epoch](/concept/moq-lite#publisher-epochs), so on moq-lite 07 +viewers switch to a restarted pipeline at once instead of stalling on the old +one; reconnects within a run keep it. `connection-stats` is null while disconnected. While connected it is a structure of the transport counters the active backend has (RTT, send and diff --git a/doc/concept/standard.md b/doc/concept/standard.md index 6b222a2a1ad..858c46360be 100644 --- a/doc/concept/standard.md +++ b/doc/concept/standard.md @@ -28,7 +28,7 @@ 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. - **History is one group.** On drafts 14 through 19 a `FETCH` returns one whole group from the cache, or the saved prefix of the group a new subscription just joined. A range of groups is refused, as is any `FETCH` on draft 20 and later. JavaScript publishing refuses every `FETCH`. A standalone fetch carries no timestamps. - **One credential per session**, carried in `SETUP` and forwarded to the [auth server](/bin/relay/auth#the-contract) unverified. A token attached to an individual request is ignored. An alias reference, a second token, or a parameter the negotiated draft does not define closes the session. -- **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`, `SUBSCRIBE_TRACKS`, and the fetch forms above. On draft 19 and later, the only subscription update that is applied is a priority change. +- **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`, `SUBSCRIBE_TRACKS`, and the fetch forms above. On draft 19 and later, 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. JavaScript does not carry datagrams on moq-transport. - **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. diff --git a/doc/concept/use-case/contribution.md b/doc/concept/use-case/contribution.md index 973c6d6e12b..0724ea251c7 100644 --- a/doc/concept/use-case/contribution.md +++ b/doc/concept/use-case/contribution.md @@ -1,6 +1,6 @@ --- title: MoQ vs RTMP/SRT -description: Pull-based contribution, on-demand encoding, and restarts that take the name +description: Pull-based contribution, on-demand encoding, and failover --- # MoQ vs RTMP/SRT @@ -22,14 +22,14 @@ That matters for long-tail content: hundreds of security cameras uploading a captions track backed by an expensive model runs only while someone has captions on. -## Restarts take the name +## Failover and restarts -A publisher announces an [epoch](/concept/moq-lite#publisher-epochs) naming the -instance behind a broadcast. Replicas of that instance, announced with the same -epoch, fail over mid-group. A restart mints a new epoch, and viewers switch to -it instead of stitching its group numbers onto the old run. `moq` and -`moqsink` mint a fresh epoch per run. A second process publishing the same name -is a newer epoch, so viewers move to it. +Because tracks are only pulled where they're needed, a publisher can hold +several connections and subscriptions move to another when one fails. A +[publisher epoch](/concept/moq-lite#publisher-epochs) (moq-lite 07, opt-in) +names the instance behind a broadcast: replicas sharing one fail over +mid-group, and a restart is a newer epoch that viewers switch to instead of +stalling on the old group numbers. ## One protocol both ways diff --git a/doc/concept/use-case/index.md b/doc/concept/use-case/index.md index 0beec4bf318..d15fd86edb3 100644 --- a/doc/concept/use-case/index.md +++ b/doc/concept/use-case/index.md @@ -12,6 +12,6 @@ of scale come from. | Use case | Replaces | Why MoQ fits | | --- | --- | --- | | [Distribution](/concept/use-case/distribution) | HLS, DASH | Sub-second latency at CDN scale, with the viewer choosing its buffer. | -| [Contribution](/concept/use-case/contribution) | RTMP, SRT | Pull-based delivery, on-demand encoding, and a restart that takes the name over. | +| [Contribution](/concept/use-case/contribution) | RTMP, SRT | Pull-based delivery, optional on-demand encoding, and simple failover. | | [Conferencing](/concept/use-case/conferencing) | WebRTC | Bidirectional on one session, browser control of the pipeline, no SDP or TURN. | | [AI](/concept/use-case/ai) | WebRTC, WebSockets | Adjustable reliability, on-demand inference, media and prompts on one connection. | diff --git a/doc/lib/js/json.md b/doc/lib/js/json.md index 5b2679780eb..43682ffe677 100644 --- a/doc/lib/js/json.md +++ b/doc/lib/js/json.md @@ -14,7 +14,7 @@ reader will not pick it up. - **Snapshot**: lossy latest value, with RFC 7396 merge-patch deltas. A delta before any snapshot is an error. - **Stream**: lossless append-log in a single group. A reader that falls behind fails the read rather than resuming mid-log. -- **Window**: a bounded run of records a reader can join at any point. Trimming a record is explicit, so a reader that was keeping up is not handed that record again when the publisher rolls a group. +- **Window**: a bounded run of records a reader can join at any point. A new group restates what it keeps explicitly, so a reader that was keeping up is not handed a record twice. Both sides choose the same compression, `"none"` or `"deflate"`. A value is stamped when written, unless you pass its capture time. diff --git a/doc/lib/rs/moq-json.md b/doc/lib/rs/moq-json.md index 103a8d51cc5..921774abc1c 100644 --- a/doc/lib/rs/moq-json.md +++ b/doc/lib/rs/moq-json.md @@ -15,7 +15,7 @@ generic catalog reader will not pick it up. - **snapshot**: lossy latest value, with RFC 7396 merge-patch deltas. An unchanged update publishes nothing. Several owners can edit their own keys in place instead of clobbering one document. - **stream**: lossless append-log in a single group. A reader that falls behind fails the read rather than resuming mid-log. -- **window**: a bounded run of records a reader can join at any point. Trimming a record is explicit, so a reader that was keeping up is not handed that record again when the publisher rolls a group. +- **window**: a bounded run of records a reader can join at any point. A new group restates what it keeps explicitly, so a reader that was keeping up is not handed a record twice. Both sides choose the same compression. A value is stamped when written, unless it carries its capture time. From ade212c297e6d197970f1bde3aab7e92e19201ba Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Wed, 7 Oct 2026 14:53:20 -0700 Subject: [PATCH 03/12] docs: second trim pass toward a feature entry point Trims the relay, library, binding, gateway, and setup pages, leaving field catalogs and edge cases to API docs, --help, and drafts. Fixes claims that were wrong: hang's scope, moq export hls serving one broadcast (and DASH), --cluster-tier applying only to dialed links, moq auth serve never granting peer, the AAC encoder, the moq-room sample, the @moq/auth CLI invocation, and the stale IETF drain caveat. The root AGENTS.md points doc edits at doc/AGENTS.md instead of asking every change to keep doc/ up to date, and drops the moq-token rows for crates that no longer exist. Co-Authored-By: Claude Opus 5.5 --- AGENTS.md | 5 +- doc/bin/cli.md | 377 +++++++++++---------------------------- doc/bin/demo.md | 4 +- doc/bin/hls.md | 111 +++--------- doc/bin/obs.md | 66 +++---- doc/bin/relay/auth.md | 319 ++++++++++++--------------------- doc/bin/relay/cluster.md | 165 +++++------------ doc/bin/relay/config.md | 150 +++++----------- doc/bin/relay/http.md | 104 ++++------- doc/bin/relay/index.md | 49 ++--- doc/bin/rtmp.md | 33 +--- doc/bin/srt.md | 27 +-- doc/concept/stats.md | 12 +- doc/concept/transport.md | 20 +-- doc/lib/c/index.md | 71 +++----- doc/lib/dart/index.md | 104 ++--------- doc/lib/go/index.md | 110 ++---------- doc/lib/index.md | 20 +-- doc/lib/js/auth.md | 11 +- doc/lib/js/hang.md | 53 ++---- doc/lib/js/publish.md | 104 +++-------- doc/lib/js/room.md | 16 +- doc/lib/js/signals.md | 22 +-- doc/lib/js/watch.md | 100 +++-------- doc/lib/kt/index.md | 99 ++-------- doc/lib/py/index.md | 99 ++-------- doc/lib/rs/hang.md | 28 ++- doc/lib/rs/index.md | 43 ++--- doc/lib/rs/moq-audio.md | 32 ++-- doc/lib/rs/moq-auth.md | 12 +- doc/lib/rs/moq-mux.md | 22 +-- doc/lib/rs/moq-room.md | 10 +- doc/lib/rs/moq-video.md | 68 ++----- doc/lib/swift/index.md | 96 ++-------- doc/setup/dev.md | 24 +-- doc/setup/index.md | 2 +- doc/setup/install.md | 10 +- 37 files changed, 682 insertions(+), 1916 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 1f5f6ed8369..c07eecf5a15 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -8,7 +8,7 @@ This file is split into nested `AGENTS.md` files based on the language/situation - Read `CONTRIBUTING.md` when dealing with PRs. - Read `PROMPTING.md` before instructing other agents via context, memory, plans, or reviews. - Read `*/AGENTS.md` if the file exists before touching a root directory. -- Read (and keep up-to-date) `doc/*.md` for user-facing documentation. +- `doc/` is the feature entry point, not a reference. Update it only when a change alters what a user would do; see `doc/AGENTS.md`. # Required @@ -101,11 +101,10 @@ The `quest` binary comes from the kixelated/quest flake input and serves the que | `rs/moq-ffi` | `rs/moq-c`, `{py,swift,kt,dart}/`, `go/wrapper/moq/*.go` (the `go/ffi` and `dart/moq_ffi` bindings regenerate automatically, but a new method needs a hand-written wrapper too, like `py/moq-rs` or `dart/moq`), `doc/lib/{py,swift,kt,go,dart,c}` | | `rs/moq-net` wire/API | `js/net`, `doc/concept`, `drafts/draft-lcurley-moq-lite.md` (if the wire spec changes) | | `rs/hang` catalog/container | `js/hang`, `doc/concept`, `drafts/draft-lcurley-moq-hang.md` (if the format spec changes) | -| `rs/moq-token` | `js/token` | +| `rs/moq-auth` | `js/auth`, `doc/bin/relay/auth.md` | | `rs/moq-stats` wire (track names, frame shapes) | `doc/bin/relay/config.md` (stats section) | | `rs/moq-relay` config/behavior | `doc/bin/relay/` | | `rs/moq-cli` | `doc/bin/cli.md` | -| `rs/moq-token-cli` | `doc/bin/relay/auth.md`, `doc/lib/rs/moq-token.md`, `doc/lib/rs/index.md` | | `rs/moq-gst` | `doc/bin/gstreamer.md` | | `rs/moq-c` C ABI (`moq.h`) | `cpp/obs/src`, `doc/bin/obs.md` | | `js/{watch,publish}` UI/API | `demo/web` if it consumes the API | diff --git a/doc/bin/cli.md b/doc/bin/cli.md index 19f45630de9..dea68f6fae6 100644 --- a/doc/bin/cli.md +++ b/doc/bin/cli.md @@ -44,11 +44,10 @@ moq fetch [options] The **MoQ side** goes first and attaches the process to the network: `--connect ` dials a relay (the path is the auth path, `?jwt=` carries a token), and `--broadcast ` names the broadcast. A process can -instead host sessions with `--listen`, or both at once. A listener admits -clients by `--auth-url` or `--auth-public`, as the relay does (see -[Authentication](/bin/relay/auth)); public rules ignore certificates, so -`--auth-public` refuses to start with `--listen-tls-root`, and only `--listen` -(QUIC) verifies one. `moq import --help` lists the sources and `moq import rtmp --help` a specific one. +instead host sessions with `--listen`, or both at once, admitting clients the +way the relay does (see [Authentication](/bin/relay/auth)). +`moq import --help` lists the sources and `moq import rtmp --help` a specific +one; every flag is documented there. ```bash # Publish a file (remux to MPEG-TS without re-encoding) @@ -62,102 +61,42 @@ moq --connect https://relay.example.com/anon --broadcast my-stream.hang export t moq --connect "https://relay.example.com/rooms/1?jwt=$TOKEN" --broadcast alice.hang import ts ``` -The `ts`, `fmp4`, and `flv` imports publish the input's own timestamps, and -the catalog clock maps the first frame to the time it arrived. So a feed whose -PTS starts hours in still names the right wall time, and every track keeps its -offset from the others. A group starting before the previous group's start, -such as a restarted encoder or a looping file wrapping to the top, ends the -import with an error; run it again to publish anew. A keyframe that merely -overlaps the previous group's last frame is not a rewind. - -MPEG-TS import carries H.264/H.265 and AAC/MP2/AC-3/E-AC-3, passes SCTE-35 and -subtitle PIDs through as tracks, and round-trips the service tables. A -`discontinuity_indicator` on the program's PCR PID is a system time-base reset, -so it breaks every track's timeline and the exported clock declares the break in -turn. A new timeline whose first group starts before the previous group's start -ends the import like any other rewind. The same flag on an elementary PID other than the program PCR PID, a -continuity-counter gap, and the 33-bit timestamp rollover move no clock and -declare nothing. FLV covers H.264 + AAC. - -`import ts` logs an elementary stream that stops delivering access units, and -counts ETSI TR 101 290 errors on the feed it receives. A sparse PID such as -SCTE-35 goes quiet between cues, so that line reports rather than alarms. -Neither check changes what is published, and the PCR checks grade the encoder's -timestamps rather than the network in front of the importer. - -A corrupt media packet, malformed PES header, or damaged codec access unit is -dropped for that PID. Ingest continues on every other PID. Video closes its -group at the break and resumes at its next keyframe, so each break freezes -video for up to one GOP. Publishing, catalog, and clock errors still end the -import. - -MPEG-TS import takes one program. A multi-program stream is refused before -anything is published, naming its programs, rather than merged onto one clock; -a PAT that adds a program mid-stream ends the import the same way. -`--program 2` imports program 2 alone. `--program all` publishes each program -the first PAT lists as its own broadcast, with its own clock and catalog, keeping -the catalog suffix last: `--broadcast event.hang` publishes `event/1.hang`, -`event/2.hang`, and so on. `export ts` writes one program per broadcast. -`import srt` takes the same `--program`. -A selected program's SI describes that service alone: its SDT lists only the -selected service, and other services' EIT is dropped. Network-wide tables (NIT, -BAT, TDT/TOT, and the SDT and EIT of other transport streams) pass through. -SI matches the selection by DVB `service_id`, which is assumed to equal the PAT -`program_number`. +## Import -```bash -moq --connect https://relay.example.com/anon --broadcast event.hang import ts --program all < mux.ts -``` +The `ts`, `fmp4`, and `flv` imports publish the input's own timestamps, mapped +to the wall time the first frame arrived. A timeline that rewinds, such as a +restarted encoder or a looping file wrapping to the top, ends the import with +an error; run it again to publish anew. A flagged MPEG-TS discontinuity that +jumps forward continues the broadcast and is declared on the exported clock. + +MPEG-TS import carries H.264/H.265 and AAC/MP2/AC-3/E-AC-3, and passes SCTE-35 +and subtitle PIDs through as tracks. It takes one program: a multi-program +stream is refused until `--program` picks one, or `--program all` publishes +each as its own broadcast (`event.hang` becomes `event/1.hang`, +`event/2.hang`). A damaged packet is dropped on its own PID, so video freezes +until its next keyframe while the other tracks carry on. The importer also +logs feed health (stalled streams, TR 101 290 errors) without changing what it +publishes. FLV covers H.264 + AAC. + +## Export -MPEG-TS export restarts its clock and table cadence after a declared marker, -discarding the old mux buffer. The first new clock packet signals the break and -stdout pacing re-anchors. Every rendition joins the new program generation; -no track is fenced across the marker. - -MPEG-TS export frames AAC as ADTS, which labels only the AAC Main, LC, SSR, -and LTP profiles. HE-AAC and HE-AACv2 go out as their AAC-LC core, and decoders -find the SBR and PS in band, as ffmpeg's ADTS output does. A track whose -profile or channel layout ADTS cannot label is refused rather than mislabeled. - -A constant-rate MPEG-TS source records its multiplex rate in the catalog -(`mpegts.muxRate`, measured off the PCR clock, null stuffing included), and -`export ts` pads its output with null packets back to that rate so an IRD or -groomer receives a constant-rate stream. `--mux-rate 5000000` pads to an explicit -rate instead, including for a broadcast that recorded none. Media is never delayed -or dropped to fit: a source that sustains more than the rate overruns it, and a -VBR source records nothing, so export without either stays unpadded. - -The `fmp4`, `mkv`, `flv`, `h264`, and `h265` exports select renditions with -flags before the sink: `--video-name` and `--audio-name` pick a rendition, -`--video-codec` and `--audio-codec` keep a codec family, and `--no-video` or -`--no-audio` leaves a role out. `h264` and `h265` refuse `--no-video` and the -audio selection flags. `ts`, `archive`, and the gateways don't apply selection, so they -refuse these flags. +The `fmp4`, `mkv`, `flv`, `h264`, and `h265` exports pick renditions with +`--video-name`, `--audio-name`, `--video-codec`, `--audio-codec`, `--no-video`, +and `--no-audio`. `ts`, `archive`, and the gateways export everything. ```bash moq ... export --no-video fmp4 > audio.mp4 moq ... export --video-name hd --no-audio mkv > hd.mkv ``` -fMP4 export writes one fragment per publisher group on each track. Audio follows -the publisher's cuts; video normally follows GOPs. Closing a group flushes it -even when the live publisher pauses. `--fragment-duration 2s` caps -the fragment span as frames arrive, including audio whose publisher never cuts. -MKV uses the same flag to cap clusters, which otherwise follow video GOPs. - -The fMP4 init segment declares every rendition in the catalog, so it waits until -each can be described. An Annex-B H.264 or H.265 track, or video whose catalog -leaves out its dimensions, waits for its first keyframe; the other tracks keep -reading meanwhile and their fragments follow the init. A track that is still -waiting once another has queued 30 seconds fails the export. After the init the -track set is fixed: a rendition that leaves and returns with the same codec -configuration is written under its original track, while a new rendition, a -changed configuration, or a return that replays media already written ends the -export with an error naming it. Restart the export to pick up a new rendition. -An Opus rendition declared without its OpusHead gets a guessed pre-skip. A -head that arrives later with the same channel count, decode rate, and gain is -accepted even if its pre-skip and input rate differ. An init already written -keeps the guess, and later heads must match the first one. +fMP4 writes one fragment per publisher group; `--fragment-duration` caps it. +The init segment declares every rendition, so it is written only once each can +be described, and the track set is then fixed: a new rendition or a changed +codec configuration ends the export. Restart it to pick up the change. + +MPEG-TS export pads to the source's constant mux rate when the catalog +recorded one, or to `--mux-rate`, so an IRD or groomer receives CBR. Media is +never delayed or dropped to fit. ## Play @@ -167,38 +106,18 @@ moq ... play --delay 500ms # fix the delay instead of measuring it moq ... play --no-video # audio only ``` -Decodes H.264, H.265, and AV1 video using the platform hardware decoder where -available, and Opus, PCM, and AAC-LC (mono or stereo) audio in software. The -opt-in `vpx` feature adds software VP8 and VP9 (8-bit 4:2:0) through libvpx, -which the build host must provide. The log names the decoder each track -opened. `--video-name` and `--audio-name` pick a rendition, and `--no-video` or -`--no-audio` leaves a role out. `--no-video` still opens a window, which stays -blank; closing it stops playback. HE-AAC signaled only in band (implicit SBR, as -over MPEG-TS) plays as its half-rate AAC-LC core. - -Playback runs on a clock it owns. `--delay` is how far it trails the live -edge: the jitter a late frame may absorb. The default, `auto`, measures how -unevenly audio arrives and sizes the speaker's buffer to match, using the same -[algorithm](/concept/audio-jitter) as the browser player, so a publisher that -flushes 100 ms at a time gets a buffer deep enough to play through the next -flush. It waits up to 2 s on a stalled group before skipping it, since a budget -any shorter would hide the very lateness it measures; a broadcast with no audio -has nothing to measure, so video trails by 100 ms and skips past that. A duration fixes the delay -instead, and doubles as the point past which a stalled group is skipped. The -speaker holds the delay, with a 50 ms floor under it: it pads back up to the -delay after running dry and skips back down onto it after a burst. The picture -is scheduled against where the speaker actually is. While video owns the clock, a frame arriving earlier than predicted -pulls playback forward, so a late start catches up to live instead of staying -behind it. Once the speaker owns the clock, video follows the speaker instead. - -Each role follows the catalog for as long as it lasts. Each decoder starts at -the newest cached group, including when a rendition is reopened, so playback -does not replay the retained backlog. A publisher that retires the rendition -being played ends that track and the role picks a replacement. A retired audio -rendition plays out what the speaker holds while its replacement fills, so the -switch does not cost a delay of silence. Playback is -behind the `play` feature, since it pulls in windowing and audio-device -dependencies: +Decodes H.264, H.265, and AV1 video with the platform hardware decoder where +available, and Opus, PCM, and AAC-LC audio in software. The opt-in `vpx` +feature adds software VP8 and VP9 through the build host's libvpx. The log +names the decoder each track opened. + +Playback starts at the newest group and trails the live edge by `--delay`. The +default, `auto`, sizes the buffer to how unevenly audio arrives, with the same +[algorithm](/concept/audio-jitter) as the browser player. A duration fixes the +delay and is also how long a stalled group is waited on before it is skipped. +Each role follows the catalog, switching rendition when the publisher retires +the one playing. Playback is behind the `play` feature, since it pulls in +windowing and audio-device dependencies: ```bash cargo install moq-cli --no-default-features --features "iroh,noq,websocket,play" @@ -213,25 +132,17 @@ moq ... import capture --window 39193 --no-audio # one window (macOS, Wi moq ... import capture --camera 0 --width 1280 --height 720 --fps 30 --bitrate 3000000 --codec h265 ``` -Video goes through the platform hardware encoder (VideoToolbox, Media -Foundation, NVENC, and with the opt-in `vaapi` / `v4l2` features VAAPI and V4L2 -M2M) with a built-in H.264 software fallback; -audio is Opus. The camera is opened only while someone is watching, and -`--bitrate` is the opening ceiling. Backends with live bitrate control lower it -to fit the connection's bandwidth estimate. `moq devices` prints every source -id. Requires the `capture` feature; on Linux that needs the ALSA headers for -the microphone, and `--display` and `pipewire:` cameras also need the -`pipewire` feature (links libpipewire). - -On Windows, display and window capture use Windows.Graphics.Capture and -require Windows 10 2004 (build 19041) or newer. Cursor capture follows the -capture configuration. The system capture border stays visible unless the OS -supports borderless capture and grants access. Frames are converted to NV12 -on the GPU; software encoding reads them back. Windows application capture -and system audio are separate capabilities, not enabled by this backend. -Windows `display:N` selectors are enumeration indices; switching from Desktop -Duplication to WGC can change which monitor a saved selector names. Run -`moq devices` again and reselect the intended display after upgrading. +Video goes through the platform hardware encoder with an H.264 software +fallback, and audio is Opus; [moq-video](/lib/rs/moq-video) lists the +backends. The camera opens only while someone is watching, and `--bitrate` is a +ceiling that backends with live bitrate control lower to fit the connection. +`moq devices` prints every source id. On Windows, `display:N` is an +enumeration index rather than a stable monitor id, so re-run `moq devices` if a +saved selector picks the wrong screen. + +Requires the `capture` feature. On Linux the microphone needs the ALSA +headers, and `--display` and `pipewire:` cameras also need the `pipewire` +feature (links libpipewire). ## Transcode @@ -242,27 +153,12 @@ moq ... transcode --rung 720:2500000 --rung 360:600000 --encoder nvenc --decoder Publishes `cam.hang/transcode.hang` whose catalog references the source's rendition and adds lower rungs that are decoded and encoded only while someone -watches them. On NVIDIA the whole pipeline stays on the GPU; `--frames cpu` -forces decoded frames into CPU memory instead of the default `native`. -Requires the `transcode` feature. - -The source is the largest rendition this host can decode with `--decoder`, so a -software-only host transcodes from an H.264 rendition rather than a larger H.265 -or AV1 one. When no rendition decodes, the command exits naming the decoder's -refusal. - -The ladder is sized against the source picture and follows it, so a source that -changes resolution mid-stream (a window capture renegotiated by a resize, a -publisher reconnecting at a new size) resolves the rungs again. Rungs that still -fit keep serving. A rung the new picture has no room for finishes its track, as -does one whose own picture moved, and the latter comes back under a new name -(`video/360p.2`), so a viewer on either reselects as it would on any other -rendition change. - -Custom `--rung` values may be supplied in any order. Heights round down to even; -heights and bitrates must then increase strictly together. Duplicate heights or -bitrates, inverted rankings, and zero-sized or zero-bitrate rungs are rejected -before connecting. +watches them. On NVIDIA the whole pipeline stays on the GPU. The source is the +largest rendition this host can decode, so a software-only host transcodes +from H.264 rather than a larger H.265 or AV1 one. When the source changes +resolution, rungs are resolved again: one that no longer fits finishes, and +one whose size changed comes back under a new name (`video/360p.2`). Requires +the `transcode` feature. ## Announced @@ -273,21 +169,9 @@ moq ... announced room --json Follows the broadcasts announced on a relay over MoQ, with the session's own auth: the live counterpart of the relay's HTTP `/announced/`. Paths are -relative to the `--connect` path. On a terminal it shows what is announced -under `prefix` right now, redrawn as broadcasts start and end, and a list -taller than the terminal ends in a count of the rest. Piped, it prints -`+ path` for each broadcast already announced, then `+ path` and `- path` as -broadcasts come and go. `--json` prints `{"path": "room/alice", "active": true}` -per line instead, on a terminal or not. It runs until interrupted, and exits -non-zero if the session ends. - -Like `/announced`, it follows announced prefixes, which by convention are -broadcast paths. A new route to a path already announced prints nothing. A name -starting with `.` stays hidden unless `prefix` names it. `announced` only dials -`--connect`, and refuses any other MoQ-side flag. - -[Inspect a relay](/bin/inspect) walks through `announced` and `fetch` next to -their `curl` equivalents, including reading the relay's stats. +relative to the `--connect` path. On a terminal it redraws the live list; +piped, it prints `+ path` and `- path` as broadcasts come and go. A name +starting with `.` stays hidden unless `prefix` names it. ## Fetch @@ -296,19 +180,11 @@ moq --connect https://relay.example.com/anon --broadcast my-stream.hang fetch ca moq ... fetch video/hd --group 42 --json ``` -Writes one group of a track to stdout over MoQ, with the session's own auth: -the counterpart of the relay's HTTP `/fetch//?group=N`. Without -`--group` it reads the newest group. By default stdout carries the frame -payloads back to back, byte for byte what `curl` gets from `/fetch`. `--json` -prints one line per frame instead: -`{"group": 42, "frame": 0, "size": 1234, "payload": ""}`, with a -zero-based `frame` and padded standard base64. - -`` is the literal track name. `/fetch` splits its path on the last `/`, -so the two agree only for names without one. Fetch only dials `--connect`, and -refuses any listener, cluster, auth, or `--hop` flag. It gives up after 30 -seconds, as `/fetch` does, and exits non-zero when the broadcast or group is not -found (before writing anything), the relay refuses, or the deadline passes. +Writes one group of a track (the newest unless `--group` says otherwise) to +stdout over MoQ: the counterpart of the relay's HTTP `/fetch`. It exits +non-zero when the broadcast or group is not found. [Inspect a +relay](/bin/inspect) walks through `announced` and `fetch` next to their `curl` +equivalents. ## Archive @@ -321,29 +197,17 @@ moq --connect https://relay.example.com/anon --broadcast event-replay.hang impor ``` `export archive` records one broadcast with -[moq-archive](https://docs.rs/moq-archive), reading its catalog as it changes. -Every track gets its own timeline, stored in spans cut at group boundaries -between 2s and 10s. The catalog and every text, JSON, and binary track are -sparse data, so each of their groups is stored as soon as it finishes, and a -group that never closes is stored in pieces as it grows. It refuses a rendition served -from another broadcast, and one that returns after the catalog dropped it. The -stage ends once the broadcast does. A store URL that already holds a -recording is continued: each track resumes after its newest stored span. `--retention 1h` keeps only the last hour (a DVR), -deleting expired objects, and timeline objects no longer needed to recover it, -`--retention-grace` (default 30s) after the timeline stops needing them. Every -track keeps at least its newest span, so a catalog that never changes outlives -the video it was published with. - -`import archive` republishes a recording: each track's timeline replays as a -live track and every track's groups are served on request, one object GET per -stored span. By default it replays what is stored and ends the timelines there; -`--follow 2s` keeps checking for new spans, and newly recorded tracks, of a +[moq-archive](https://docs.rs/moq-archive), cutting each track into 2-10 s +spans at group boundaries. A store that already holds the recording is +continued. `--retention 1h` keeps only the last hour, a DVR. + +`import archive` republishes a recording as live tracks, fetching spans on +request. It ends where the recording ends; `--follow 2s` keeps polling a recording still being made. Store URLs are `file:///absolute/path`, `s3://bucket/prefix`, -`gs://bucket/prefix`, or `az://container/prefix`. Cloud credentials come from -the usual `AWS_*`, `GOOGLE_*`, and `AZURE_*` environment variables. The `s3`, -`gcs`, and `azure` cargo features are on by default. +`gs://bucket/prefix`, or `az://container/prefix`, with credentials from the +usual `AWS_*`, `GOOGLE_*`, and `AZURE_*` environment variables. ## Multiple stages @@ -369,35 +233,20 @@ epoch. ## Cluster -The CLI reads the same `--cluster-*` flags as `moq-relay`, LAN and WAN alike, -and publishes on the cluster origin. A `moq --cluster-lan` process and a -`moq-relay` with `[cluster.lan]` on the same network mesh with each other. - -`--cluster-lan` advertises this process on the LAN over mDNS and meshes with -every other participating MoQ process. It reuses `--listen`, filling in an -ephemeral port and a generated certificate when those are unset. A LAN peer -authenticates with its mDNS credential; `cluster.token` is for -`--cluster-connect` and `--cluster-connect-api` peers only. +The CLI reads the same `--cluster-*` flags as `moq-relay` and publishes on the +cluster origin, so a `moq` process can join a relay mesh directly. See +[Clustering](/bin/relay/cluster). ```bash moq --cluster-lan import capture moq --cluster-lan --cluster-lan-secret /etc/moq/cluster.key import capture ``` -`--cluster-lan-secret` restricts the mesh to peers holding the same key. -Without it, anyone who can reach the listener joins, so leave it unset only -on networks you trust. mDNS is still an open channel: the secret -authenticates the record, it does not hide the credential or the node URL. - -`--cluster-lan-app` names the DNS-SD application this process advertises -under. Peers using a different name never discover this one. It defaults to -`default`, which moq-relay shares, so the two find each other with no -configuration. An application built on the library picks its own name. - -The WAN flags (`--cluster-connect`, `--cluster-connect-api`, `--cluster-node`, -`--cluster-token`, `--cluster-id`, `--cluster-tier`) match the relay. `--cluster-connect` and `--cluster-connect-api` are a MoQ side on -their own, so `moq --cluster-connect https://relay.example import ts` needs -no `--connect`. See [Clustering](/bin/relay/cluster). +`--cluster-lan` advertises this process over mDNS and meshes with every other +MoQ process and `moq-relay` on the LAN, with no other configuration. Without +`--cluster-lan-secret`, anyone who can reach the listener joins, so leave it +unset only on networks you trust. `--cluster-connect` is a MoQ side on its own, +so it needs no `--connect`. ## Auth @@ -405,56 +254,30 @@ no `--connect`. See [Clustering](/bin/relay/cluster). moq auth generate --algorithm ES256 --out private.jwk --public public.jwk moq auth sign --key private.jwk --root rooms/123 --publish 'alice/**' --subscribe '**' > alice.jwt moq auth verify --key public.jwk --in alice.jwt -``` - -`--publish` and `--subscribe` take patterns: `alice` is one broadcast, -`alice/**` is a subtree, `**` is everything under `--root`. - -`moq auth serve` answers a relay's auth requests with the same keys, public -rules, an explicit mTLS grant, tiers, and session limits; see -[Auth server](/bin/relay/auth#auth-server). - -```bash moq auth serve --listen 127.0.0.1:4440 --key-dir keys/ --public-subscribe 'anon/**' ``` -`moq auth serve` also accepts `--key-set keys.jwks` to verify tokens from a JWK Set. - -`moq auth sessions` and `moq auth revalidate` talk to a relay's internal -listener. A push is a re-check: the auth server's reply is what kicks. An -empty filter is every session on that node. - -```bash -# Kick one session by id. -moq auth revalidate --internal-url http://127.0.0.1:9101 --id 00ff - -# Re-check everyone under a path. -moq auth revalidate --internal-url http://127.0.0.1:9101 --path 'rooms/123/**' -moq auth sessions --internal-url http://127.0.0.1:9101 --path 'rooms/123/**' -``` - +`--publish` and `--subscribe` take patterns: `alice` is one broadcast, +`alice/**` is a subtree, `**` is everything under `--root`. `moq auth serve` +answers a relay's auth requests with the same keys (see [Auth +server](/bin/relay/auth#auth-server)). `moq auth sessions` and +`moq auth revalidate` list and re-check sessions on a relay's internal +listener; a re-check asks the auth server again, and its reply is what kicks. See [Authentication](/bin/relay/auth). ## Retention and latency -`import --max-age` (default 30 s) tells relays how long to keep old -groups fetchable, which the [HLS gateway](/bin/hls) depends on. `export --max-delay` (default 500 ms) is how far a stalled group may fall -behind the live edge before *this* consumer skips it. Raising the first never delays playback. -`export ts` still spells its budget `--max-age`. - -For `export ts`, `--max-age` also bounds how long the muxer holds a leading -track for a lagging one. Frames go out in media-time order across all tracks, -not arrival order, so two exporters of one broadcast emit them in one order. A -track quiet for longer is muxed around until it catches up; a sparse track -(SCTE-35) costs that wait once per cue. `--max-age 0` keeps arrival order. +`import --max-age` (default 30 s) tells relays how long to keep old groups +fetchable, which the [HLS gateway](/bin/hls) depends on. `export --max-delay` +(default 500 ms) is how far a stalled group may fall behind the live edge +before *this* consumer skips it. Raising the first never delays playback. +`export ts` still spells its budget `--max-age`, and it also bounds how long +the muxer holds a leading track to interleave a lagging one in media-time order. A stdout export ends with the broadcast. `export ts --linger 10s` waits that -long for the broadcast to come back instead: a publisher that restarts within -it is picked up under the same PIDs, with the break flagged (PCR discontinuity, -PAT/PMT re-sent). Nothing is written while it is gone. When the linger runs out, -the exit code is that of the last end: 0 if the broadcast finished cleanly, 1 if -it dropped or failed. The default is `0s`, which exits on the first end the same -way. Only `ts` can mark the restart, so the other formats refuse `--linger`. +long for a restarted publisher instead, and marks the break in the stream +(PCR discontinuity, PAT/PMT re-sent). Only `ts` can mark a restart, so the +other formats refuse `--linger`. ## Debugging diff --git a/doc/bin/demo.md b/doc/bin/demo.md index f2bfbe7c670..d1471186465 100644 --- a/doc/bin/demo.md +++ b/doc/bin/demo.md @@ -43,9 +43,7 @@ What it demonstrates: - **Bidirectional data.** Button presses go up on a raw JSON `command` track; a `status` track comes down with everyone's held buttons and latency. Same relay, same protocol as the media. - **Split trust.** In production the game prefix is authenticated (only the server publishes games) while the viewer prefix is anonymous. -Tracks: `catalog.json`, `video0.avc3` (160x144 H.264 at 60 fps), `audio0.opus`, -and the raw `status` and `command` tracks. Code: -[`rs/moq-boy`](https://github.com/moq-dev/moq/tree/main/rs/moq-boy) (emulator +Code: [`rs/moq-boy`](https://github.com/moq-dev/moq/tree/main/rs/moq-boy) (emulator and publisher), [`js/moq-boy`](https://github.com/moq-dev/moq/tree/main/js/moq-boy) (the `` element, published as `@moq/boy`), and [`demo/boy`](https://github.com/moq-dev/moq/tree/main/demo/boy). The same diff --git a/doc/bin/hls.md b/doc/bin/hls.md index c1b86864fac..188226effad 100644 --- a/doc/bin/hls.md +++ b/doc/bin/hls.md @@ -1,109 +1,52 @@ --- title: HLS -description: Serve any broadcast as HLS, or import an HLS playlist +description: Serve a broadcast as HLS or DASH, or import an HLS playlist --- # HLS -`moq export hls` serves a MoQ broadcast as HLS over HTTP for players that -can't speak MoQ. `moq import hls` pulls a remote HLS master or media playlist -into a broadcast. +`moq export hls` serves a MoQ broadcast as HLS and DASH over HTTP for players +that can't speak MoQ. `moq import hls` pulls a remote HLS master or media +playlist into a broadcast. ```bash -# Serve. Players open http://localhost:8089/my-stream.hang/master.m3u8 +# Serve. Players open http://localhost:8089/my-stream.hang/master.m3u8 (or manifest.mpd for DASH) moq --connect https://relay.example.com/anon --broadcast my-stream.hang export hls --listen '[::]:8089' # Import moq --connect https://relay.example.com/anon --broadcast my-stream.hang import hls https://example.com/live/master.m3u8 ``` +The CLI serves the one `--broadcast` it was given, at +`/{broadcast}/master.m3u8` and `/{broadcast}/manifest.mpd`. + +## How export works + Export never subscribes to media. It reads each rendition's [timeline track](/concept/hang#catalog), a small index of that rendition's -groups, to build playlists, then fetches exactly the frames a requested segment -covers from the relay's cache and transmuxes them to CMAF on demand. So a -segment is servable for as long as the relay's -[cache](/bin/relay/config#cache) retains it, and idle renditions cost nothing. -Segment boundaries come from one reference rendition (the first video -rendition by name, or the first audio one without video) and are numbered by -its records, so every edge and every reload agree. Every other video rendition -snaps each boundary to its nearest keyframe within about a second, and a -segment with none in range renders as `EXT-X-GAP`; audio takes every frame -inside the segment's span. A jump in content time renders as -`EXT-X-DISCONTINUITY`. Gaps are a fallback: a publisher wanting clean HLS -export should align video GOPs across renditions. A timeline that fails -(malformed, refused, or lost) is not retried, since the relay already rides out -transient source failures. The reference timeline failing ends every playlist -with `EXT-X-ENDLIST`, and any other rendition's timeline failing ends that -rendition's playlist at the last segment it covers. A broadcast -whose catalog advertises no timelines is skipped. One server exposes every -broadcast by path: +groups, to build playlists. A segment request fetches exactly the frames it +covers from the relay's cache and transmuxes them to CMAF. Media is never +transcoded, so the player must support the publisher's codecs. -```text -/{broadcast}/master.m3u8 -/{broadcast}/manifest.mpd -/{broadcast}/{video|audio}/{rendition}/media.m3u8 -/{broadcast}/{video|audio}/{rendition}/init.{hash}.mp4 -/{broadcast}/{video|audio}/{rendition}/seg/{reference}.{segment}.m4s -/{broadcast}/{video|audio}/{rendition}/seg/{reference}.t{pts}.m4s -``` +What that means for you: -Segment boundaries come from one reference rendition's timeline, and its records -number the segments. `{reference}` is a short hash of that rendition's kind and -name, so every edge derives the same URL, and a reference that changes (a new -first video rendition) starts a new numbering under new URLs rather than reusing -the old ones for other content. +- **Idle renditions cost nothing**, and a segment is servable for as long as the relay's [cache](/bin/relay/config#cache) retains it. Keep `--window` (the live playlist length, default 16 s) within that retention. +- **Publish timelines.** A broadcast whose catalog advertises no timelines is skipped. +- **Align GOPs across video renditions.** Segment boundaries come from one reference rendition. Other video renditions snap to their nearest keyframe, and a segment with none nearby becomes an `EXT-X-GAP`. +- **Segment URLs are stable.** Every edge and every reload derive the same URLs, so a CDN in front of export caches them. A [`moq-archive`](https://docs.rs/moq-archive) recording replayed through its -`Reader` is served the same way, with no second stored copy. Playlists come -from the replayed timelines alone, and a segment GETs only its rendition's -stored objects, so switching renditions never downloads both. An -inline-parameter-set codec with no catalog `description` is the exception: -the first playlist render GETs one keyframe group to build the init segment, -then caches it. Out-of-band configs need no media GET. When the catalog's -`archive` entry names a `store` and no `replay` path, its spans are durable on -this broadcast, so the playlists list the whole retained timeline and only the -recording's own retention trims them; DASH `timeShiftBufferDepth` is the listed -span. The playlist ends with `EXT-X-ENDLIST` only once the reader's caller -declares the recording finished; the store holds no completion marker. +`Reader` is served the same way, with no second stored copy, and lists the +whole retained recording. -The init URL carries a hash of its bytes, so a reconfigured rendition gets a -new one. An embedder of the library can also label the publisher's run with -`Broadcaster::set_generation`. Every segment URL then carries it -(`seg/{generation}.{reference}.{segment}.m4s`), since a restarted publisher reuses segment -numbers for different media. - -`--window` sets the live playlist duration (default 16 s) and caps segment -`Cache-Control: max-age` for every broadcast, `--listen-tls-cert`/`--listen-tls-key` or `--listen-tls-generate` serve HTTPS, -and `--cors-origin` opens it to browsers. -H.264/H.265 and AAC/Opus renditions are served. Import handles classic HLS; -LL-HLS parts are not implemented yet. It publishes the playlist's own media -times, and the catalog clock maps the first imported segment to the time it -arrived, one mapping for every rendition. The library is -[`moq-hls`](https://docs.rs/moq-hls). - -## Recording segments - -`moq_hls::export::segments::Segment::discontinuity` is the absolute timeline -sequence within one `Broadcaster`. Cursors created at different times report -the same sequence for the same timeline span, including after a rendition -rebinds. Skipping unavailable segments does not reset the sequence. +and `--cors-origin` opens it to browsers. See `moq export hls --help`. -HLS numbers a segment as `EXT-X-DISCONTINUITY-SEQUENCE` plus the -`EXT-X-DISCONTINUITY` tags before it (RFC 8216, section 6.2.1), and matching -content in every rendition must share that number. A recorder writes the first -retained segment's value as `EXT-X-DISCONTINUITY-SEQUENCE`, then writes -`current - previous` `EXT-X-DISCONTINUITY` tags before each later segment. The -difference can exceed one when the cursor skipped every segment of an epoch, and -one tag per change would then fall behind sibling renditions. Retain the -absolute value in the index alongside each segment. +## Import -Recreating the broadcaster starts a new sequence namespace. Start a new -recording/playlist, or explicitly map the new broadcaster's sequences into a -recording-wide sequence with a discontinuity at the boundary. Do not compare -raw values across broadcaster instances or infer a restart from zero alone. +Import handles classic HLS; LL-HLS parts are not implemented. It publishes the +playlist's own media times, and anchors the catalog clock on the first imported +segment. -When updating moq.pro's moq-hls pin to this breaking release, update its recorder -and index together: store the returned sequence directly instead of accumulating -per-cursor break counts. Existing indexes containing counts need conversion -within their original recording namespace before combining them with new data. +The library, including the recorder cursors for mirroring a broadcast to +storage, is [`moq-hls`](https://docs.rs/moq-hls). diff --git a/doc/bin/obs.md b/doc/bin/obs.md index 7f1de4429db..af1acf69810 100644 --- a/doc/bin/obs.md +++ b/doc/bin/obs.md @@ -10,52 +10,32 @@ OBS Studio install. - **Publish**: Settings > Stream, choose "MoQ", enter the relay URL (with `?jwt=` if needed) and broadcast path, Start Streaming. - **Subscribe**: add a "MoQ Source", enter the relay URL and broadcast path, and the stream appears in the scene. -- **Dock**: **Stream** contains the relay URL, optional publish token and - broadcast name, Go Live, and connection state. Leave the broadcast name empty - to publish at the relay URL path. Paste a URL with `?jwt=` to fill the token - field automatically. Enter a relay URL explicitly; on the shared anonymous - relay, use a unique path such as `https://cdn.moq.dev/anon/your-stream`. - Reconnect settings live under **Advanced**. - **Encoding** chooses between **Use OBS Output settings** and **Custom settings - for MoQ**. Both use OBS encoders; custom settings apply only to this MoQ stream. - **Encoder latency** defaults to **Low latency** in both modes. It overrides - buffering settings only for this MoQ stream; **Keep encoder settings** preserves - them. x264 uses its zero-latency tune, VideoToolbox disables B-frames, NVENC - uses ultra-low tuning without B-frames/lookahead, and Quick Sync uses ultra-low - mode without B-frames. Other encoders retain their settings. **Stats** reports - the applied policy. This trades compression efficiency for less buffering, - not a guaranteed end-to-end delay: OBS VideoToolbox and NVENC can still queue - frames internally. Keyframe join delay and viewer buffering are separate. - Custom profiles offer Auto, Quality, or Performance, with hardware/software, - video codec, encoder, and audio codec choices. - **Stats** shows the active encoding, negotiated draft, dial scheme, and one - minute of RTT, estimated send/receive bandwidth, packet loss, and bytes sent. - **About** lists plugin and moq-c versions, documentation links, and available - video encoders. - -OBS reports each locally encoded packet's handoff to moq-c against the shared -broadcast media clock. Each track's catalog `jitter` is the largest measured -delay above that track's own recent minimum, and its `delay` is how far that -minimum trails the earliest track, both rounded up to milliseconds. +- **Dock**: a **MoQ** dock with Go Live, its own encoding settings, and live stats (negotiated draft, RTT, bandwidth, loss). + +Enter a relay URL explicitly. On the shared anonymous relay, use a unique path +such as `https://cdn.moq.dev/anon/your-stream`. A URL with `?jwt=` fills the +token field. + +By default the dock tunes the encoder for low latency on this stream only: +no B-frames or lookahead on the encoders that support turning them off. This +trades compression for less buffering; it does not guarantee an end-to-end +delay. Pick **Keep encoder settings** to leave the encoder alone. ## Source quality and moq-transcode -OBS publishes **one** hang mezzanine. It does not encode a viewer ladder inside -the plugin. When a relay or moq.pro enables [`moq-transcode`](/bin/cli#transcode), -the ladder catalog appears beside that source as `{broadcast}/transcode.hang` -(the same path the `moq … transcode` CLI uses). Prefer a broadcast name ending -in `.hang`, a canvas at least as tall as the top rung you want (1080p for the -default ladder), and a source bitrate above the top rung ceiling (Quality -targets 8 Mbps CBR so the default 5 Mbps 1080p rung can undercut it). The catalog -carries coded size and configured CBR bitrate so the transcoder can size rungs -before measured rates arrive. +OBS publishes **one** rendition and does not encode a viewer ladder. When a +relay or moq.pro runs [`moq-transcode`](/bin/cli#transcode), the ladder appears +beside the source as `{broadcast}/transcode.hang`. For a good ladder, name the +broadcast with a `.hang` suffix, use a canvas at least as tall as the top rung +(1080p by default), and a source bitrate above that rung (the Quality profile's +8 Mbps clears the default 5 Mbps 1080p rung). Local check before moq.pro (requires a CLI built with the `transcode` feature): ```bash cargo install --locked moq-cli --features transcode # OBS Go Live to e.g. my-obs.hang on a local relay, then: -moq --connect https://localhost:4443/anon --broadcast my-obs.hang transcode +moq --connect http://localhost:4443/anon --broadcast my-obs.hang transcode # Watch my-obs.hang/transcode.hang ``` @@ -77,13 +57,11 @@ Xcode or Visual Studio 2022; see ## Advanced settings -Off by default; the defaults suit a normal relay. When enabled they cover the -things you'd otherwise pass to `moq` on the command line: pinning a protocol -draft or QUIC backend, trusting a self-signed relay by fingerprint or a -private CA, an SNI override, reconnect pacing, congestion control (delay-based -BBR or loss-based CUBIC), stream limits and timeouts, qlog traces for -diagnosing stalls, and the WebSocket fallback race. A rejected value stops the -stream with the reason in the log rather than silently using a default. +Off by default; the defaults suit a normal relay. They cover what you would +otherwise pass to `moq` on the command line: pinning a draft or QUIC backend, +trusting a self-signed relay or private CA, reconnect pacing, congestion +control, and qlog traces. A rejected value stops the stream with the reason in +the log rather than silently using a default. The plugin is C++ over [moq-c](/lib/c/)'s C ABI and ships with every moq-c release. diff --git a/doc/bin/relay/auth.md b/doc/bin/relay/auth.md index e227663ec28..bcaf7a18a16 100644 --- a/doc/bin/relay/auth.md +++ b/doc/bin/relay/auth.md @@ -15,124 +15,73 @@ A relay admits a session in exactly one of two ways: Setting both, or neither, fails at startup; an application that embeds the relay may leave both unset and decide [in process](#in-process) instead. Nothing else admits anyone: a verified client certificate is a fact the server -weighs, never a grant on its own. A grant names publish and subscribe rights as path patterns under a root, -and the session can only see that part of the tree. +weighs, never a grant on its own. A grant names publish and subscribe rights as +path patterns under a root, and the session can only see that part of the tree. ## The contract -The relay POSTs one JSON body per session event to `--auth-url` and reads a -grant back. The schemas are `moq_auth::Request` and `moq_auth::Grant` +The relay POSTs one JSON body per session event (`connect`, `revalidate`, +`end`) to `--auth-url` and reads a grant back. The request carries everything +the relay knows: a session id, its own `node` name, the transport, addresses, +SNI and ALPN, the path and query exactly as dialed, a moq-transport SETUP +token, the declared role, and the verified client certificate. Nothing is +parsed on the server's behalf: the `jwt` query parameter is a convention of +`moq auth serve`, not of the relay. The grant answers with `publish` and +`subscribe` pattern unions and optionally a `root` alias, read-only `mounts`, +`expires`, a `revalidate` cadence, a stats `tier`, and `peer` / `upstream` to +mark another relay and an [upstream link](/bin/relay/cluster#upstream-links). +The fields are documented on `moq_auth::Request` and `moq_auth::Grant` ([Rust](/lib/rs/moq-auth), [TypeScript](/lib/js/auth)). -**Request.** `id` (random 128-bit hex, unique per session), `event` -(`connect`, `revalidate`, or `end`), `node` (the relay's `--stats-node`, else -`--cluster-node`), `transport` (`quic`, `websocket`, `tcp`, `unix`, `iroh`, `rtmp`, `srt`, `webrtc`, or -`http` for a one-shot `/fetch` or `/announced` request), `remote` and `local` -socket addresses, `server_name` (the SNI or the host the client addressed), -`alpn` (the negotiated moq protocol), `path` exactly as dialed, `query` raw, -`token` with the credential a moq-transport client put in its SETUP's -`AUTHORIZATION TOKEN` option (`kind`, the draft's Token Type, and `value`, the -bytes as unpadded base64url), `role` the client declared at SETUP -(`publisher`, `subscriber`, absent for both), and `tls` with the verified client certificate when one was presented: -`name` (first SAN DNS name, else CN, else the fingerprint; a server cannot tell which), `fingerprint` -(SHA-256 of the leaf), `expires`, `issuer`. Nothing is parsed on the server's -behalf: the `jwt` query parameter is a convention of `moq auth serve`, not of -the relay, and the relay forwards a SETUP token without reading it. An `end` adds `reason`, `duration` in seconds, and `bytes` sent and -received. - -**Grant.** `publish` and `subscribe` as pattern unions (`foo/**` is a subtree, -`**` is everything, an empty list is nothing), `root` (optional; replaces the -dialed path, which is how a slug aliases to a canonical id), `mounts` -(optional object; each key, a path relative to the root, reads from the -absolute path it maps to: `{".svc": ".svc/pid"}` resolves `.svc/foo` at -`.svc/pid/foo` and presents its announcements under `.svc`, the patterns still -authorize `.svc/foo`, and nothing may be published beneath a key; a key -that holds a wildcard or overlaps another key or any value, its own included, -refuses the grant), -`expires` -(optional unix seconds; the session closes then), `revalidate` (optional -seconds until the relay asks again), `tier` (optional label handed to -[stats](/bin/relay/config#stats)), `peer` (optional; `true` marks another -relay, so what it announces counts as entering the cluster elsewhere, not as -ingest here), and `upstream` (optional; `true` marks that peer as an -[upstream link](/bin/relay/cluster#upstream-links), and requires `peer`). A 2xx with a grant admits. A 401 or 403 refuses. -Anything else at connect, a timeout, a 5xx, or an unparseable body, refuses and -logs an error; nothing is admitted because the server was down. A grant that -names nothing refuses, and one with `revalidate` but no `expires` is refused -as invalid, as is one whose `expires` is already at or before now: expiry is -exact, with no grace for clock skew, so keep the auth server's clock in sync. -The client and relay snapshot each accepted grant's deadline on a monotonic -clock, so later polls, outages, and wall-clock adjustments do not restart it. - -**Revalidate and outage.** On the cadence the relay POSTs `revalidate` with the -same request. A grant applies: a changed `root` or `mounts`, or one that no longer covers -what the session holds closes it with `Unauthorized` (the live session is not -resized in place), and so does a flipped `peer` or `upstream`; a changed `tier` keeps the -session and moves its stats: its presence counts under the new tier from then -on, as does each group and subscription it starts afterwards, while one already -in flight finishes where it began. A 401 or 403 closes the session now, as does a 2xx -whose grant names nothing. A 2xx that fails validation otherwise (already -expired, `revalidate` without `expires`, or a zero cadence) closes it as -`invalid`. Anything else (408, 429, 404, 400, 5xx, a timeout, a transport -error) retries with jittered backoff and the session lives until `expires`, so -an outage always has the bound the server chose. There is no `Cache-Control` -and no cache on the relay. - -**End.** Every close reports `end` with the reason: `expired`, `refused`, -`invalid`, `narrowed` when a re-check removes its scope, `shutdown` when the -relay drains it, the session's own close classification, or `dropped`. The byte -totals are what the transport reports; QUIC reports them, the qmux stream -transports do not yet. - -**Push.** An operator or the auth server can ask this node to re-check now, -instead of waiting for the cadence, so a kick, a gate, or a retier lands in -one round trip. The internal listener takes the same filter on -`GET /sessions` and `POST /sessions/revalidate`: any subset of the fields the -server already saw (`id`, `path` as a pattern, `remote` as an IP or CIDR, -`transport`, `tls.name`, ...). Every given field must match. An empty filter -is every session on this node, so a node under load is nudged through a -selector. A push does not decide anything: the relay re-POSTs `revalidate` -and the server's reply kicks, narrows, retiers, or keeps the session exactly -as a scheduled re-check would. Closing a session with no server in the loop -is not a route. +**Connect.** A 2xx with a grant admits. A 401 or 403 refuses. Anything else, +including a timeout or an unparseable body, refuses and logs an error, so +nothing is admitted because the server was down. A grant that names nothing +refuses, and so does one already expired: expiry is exact, with no grace for +clock skew, so keep the auth server's clock in sync. -```bash -# Kick one session. -curl -X POST 'http://127.0.0.1:9101/sessions/revalidate?id=00ff' - -# Re-check everyone under a path, then see who is still there. -curl 'http://127.0.0.1:9101/sessions?path=demo/**' -curl -X POST 'http://127.0.0.1:9101/sessions/revalidate?path=demo/**' - -moq auth revalidate --internal-url http://127.0.0.1:9101 --id 00ff -moq auth sessions --internal-url http://127.0.0.1:9101 --path 'demo/**' -``` +**Revalidate.** On the grant's cadence the relay asks again. A grant that no +longer covers what the session holds, or that changes `root`, `mounts`, +`peer`, or `upstream`, closes the session; it is not resized in place. A +changed `tier` keeps the session and moves its stats from then on. A 401 or +403 closes it. Any other failure retries with backoff and the session lives +until `expires`, so an outage always has the bound the server chose. A grant +with `revalidate` must set `expires` for that reason. -`GET /sessions` is the dry run: the same matches, each request plus start -time, with `query` and `token` omitted so a credential on the plane cannot be replayed. A -matching POST returns 202 and the ids; no match is 200 with an empty list. -An unknown field, including `query`, is 400. One node, no cluster fan-out: -the server already knows each session's `node` from `connect` and calls that -relay. +**End.** Every close reports `end` with the reason, the duration, and the +bytes sent and received. **The link.** `https://` presents the relay's `connect.tls` client certificate when one is configured, so a remote server can tell which relay is asking; `unix://` speaks HTTP over a socket; `http://` is accepted for a loopback host only. There is no shared secret. -**Patterns.** A grant is any pattern union and means exactly what it says: -`foo/**` is a subtree, a bare `foo` is that one broadcast, `live/*` is every -broadcast one segment under `live`, and `room/*/chat` is each room's chat and -nothing beside it. The relay announces, publishes, and resolves only the paths -inside the grant. Announcements travel by literal head on the wire, so a -non-prefix grant is filtered locally on each side while the announced route -stays a prefix on every protocol version. - ```toml [auth] url = "http://127.0.0.1:4440/" ``` +### Push + +An operator or the auth server can ask a node to re-check sessions now instead +of waiting for the cadence, so a kick, a gate, or a retier lands in one round +trip. A push decides nothing: the relay asks the server again and applies its +answer exactly as a scheduled re-check would. The internal listener selects +sessions by the fields the server already saw; see +[`/sessions`](/bin/relay/http#get-sessions). + +```bash +# Kick one session. +curl -X POST 'http://127.0.0.1:9101/sessions/revalidate?id=00ff' + +# Re-check everyone under a path. +curl -X POST 'http://127.0.0.1:9101/sessions/revalidate?path=demo/**' + +moq auth revalidate --internal-url http://127.0.0.1:9101 --id 00ff +``` + +A push reaches one node. The server already knows each session's `node` from +`connect` and calls that relay. + ## Tokens With `moq auth serve`, a client presents a JWT in `?jwt=`. Generate a key, @@ -155,10 +104,9 @@ moq auth serve --key public.jwk # or --key-dir /etc/moq/keys/ or --key-set /et The client dials `https://relay.example.com/rooms/123?jwt=`. A moq-transport client can instead put the JWT in its SETUP's `AUTHORIZATION -TOKEN` option with Token Type 0; `moq auth serve` verifies it the same way. HMAC -(HS256/384/512), RSA (RS/PS), ECDSA (ES256/384), and EdDSA keys all work. A key -can itself be **scoped** at generation (`--root`, `--publish`, `--subscribe`), -after which it can never sign a broader token. +TOKEN` option with Token Type 0. HMAC, RSA, ECDSA, and EdDSA keys all work. A +key can itself be **scoped** at generation (`--root`, `--publish`, +`--subscribe`), after which it can never sign a broader token. ### Claims @@ -175,22 +123,18 @@ claim may narrow the grant, and a misspelled `root` would otherwise widen it to everything. Put application data somewhere other than the token. Tokens and key scopes from the older `moq-token` format still work: each `put` -and `get` prefix `p` reads as the subtree `p/**`, and `""` as `**`. When every -grant is a subtree, signing writes that older form so relays and auth servers -that predate patterns accept it too. A grant only a pattern can express (an -exact `foo`, or `*/chat`) is written as `publish`/`subscribe`, which an older -verifier refuses. +and `get` prefix `p` reads as the subtree `p/**`. ### Path matching Grants are [patterns](https://docs.rs/moq-pattern) relative to `root`: `foo` -is exactly `foo`, `foo/**` is `foo` and everything beneath it, and `**` is -everything. Matching is on path boundaries (`foo/**` covers `foo/bar` but not -`foobar`). The relay scopes a session by the exact union, including literals, -segment wildcards, suffixes, and subtrees. `moq auth serve` authorizes the token -at the dialed path: the path may equal the root, extend it (which narrows the -grant), or be a parent of it (the grant still applies at the root). An unrelated -path is rejected. The relay forwards the raw path and enforces the grant it gets. +is exactly `foo`, `foo/**` is `foo` and everything beneath it, `live/*` is +every broadcast one segment under `live`, and `**` is everything. Matching is +on path boundaries (`foo/**` covers `foo/bar` but not `foobar`), and the relay +announces, publishes, and resolves only paths inside the grant. `moq auth +serve` authorizes the token at the dialed path: the path may equal the root, +extend it (which narrows the grant), or be a parent of it (the grant still +applies at the root). An unrelated path is rejected. The session's root is always the path it dialed, and what it sees is named relative to that. For a grant of `demo/**` from the root: @@ -225,34 +169,29 @@ public_publish = ["anon/**"] ``` A static grant with no expiry and no re-check. Nothing here verifies a token, -so a session presenting one (a `jwt` query or any SETUP token) is refused -rather than admitted on the public grant. The patterns are rooted at `/`, -like a token with an empty root (see [Path matching](#path-matching)): `anon/**` -admits a session dialed at `/`, `/anon`, or `/anon/room`, scoped to `anon/`, -and refuses one dialed anywhere else. A pattern with no wildcard, such as -`anon`, refuses to start: 0.14 read it as a prefix and a pattern reads it as one -broadcast, so write `anon/**` for the subtree. `public = "**"` opens everything -and is for development only. With `--auth-url` the anonymous rules live on the -server instead (`moq auth serve --public-*`). +so a session presenting one is refused rather than admitted on the public +grant. The patterns are rooted at `/`, like a token with an empty root (see +[Path matching](#path-matching)): `anon/**` admits a session dialed at `/`, +`/anon`, or `/anon/room`, and refuses one dialed anywhere else. A pattern with +no wildcard, such as `anon`, refuses to start; write `anon/**` for the subtree. +`public = "**"` opens everything and is for development only. With +`--auth-url` the anonymous rules live on the server instead +(`moq auth serve --public-*`). ## mTLS `listen.tls.root` verifies a client certificate chain at the handshake, and a -bad chain still fails there. What the certificate admits is the server's -decision: the relay reports its facts in the request's `tls` and enforces the -grant it gets back. `moq auth serve` grants a certificate only what -`--mtls-publish` and `--mtls-subscribe` name, empty by default. Public rules -ignore certificates, so a relay or `moq --listen` on `--auth-public` refuses -to start with `listen.tls.root` or `web.https.root`. Only the QUIC listener -verifies `listen.tls.root`, so a stream-only relay (no `listen.bind`) refuses -to start with it too. +bad chain fails there. What the certificate admits is the server's decision: +the relay reports it in the request and enforces the grant it gets back. +`moq auth serve` grants a certificate only what `--mtls-publish` and +`--mtls-subscribe` name, nothing by default. Public rules ignore certificates, +so `--auth-public` with a client CA refuses to start. Only the QUIC listener +verifies client certificates, so a relay without `listen.bind` refuses +`listen.tls.root` too. Cluster peers are admitted the same way, so a mesh runs `moq auth serve --mtls-publish '**' --mtls-subscribe '**'` (or a server granting its cluster CA everything); see [Clustering](/bin/relay/cluster). -The LAN mesh credential on `/.cluster/` stays relay-internal: it -is a secret the relay minted for itself, checked locally, and never a request -to the server. ```toml [listen.tls] @@ -265,8 +204,7 @@ key = "/etc/moq/relay.key" ## Auth server -`moq auth serve` is the reference auth server: the policy the relay used to -hold, answered over the contract above. +`moq auth serve` is the reference auth server, answering the contract above. ```bash moq auth serve --listen 127.0.0.1:4440 \ @@ -286,49 +224,33 @@ evaluated or refused: nothing is ignored, and no two are combined. | a certificate | never requested: a client CA refuses to start | `--mtls-*`, or refused | | a JWT and a certificate | never requested | refused | -A JWT, from the `jwt` query or a SETUP `token` of `kind` 0, is verified -against `--key FILE`, `--key-dir DIR`, or `--key-set FILE` (by `kid`, read per -request so rotation needs no restart) and authorized at the dialed path, as in -[Path matching](#path-matching). A malformed, expired, or unknown-key token is -refused; it never falls through to the anonymous rules. So is a SETUP token of -any other `kind`. A SETUP token and a `jwt` query with the same value are one -JWT, verified once; different values are refused. -A JWT presented with a certificate is refused, because neither can safely win: -the certificate would override a JWT meant to narrow it, and the JWT would -narrow or refuse a peer by accident. So a peer presents `cluster.token` or a -certificate, not both. - -`--mtls-*` and `--public-*` are rooted at `/`, like a token with an empty root, -and a session they reach nothing at is refused. Cluster peers are admitted by -certificate; a mesh needs `--mtls-publish '**' --mtls-subscribe '**'`. - -Every grant carries `--tier`. As in 0.14, nothing is re-checked or closed by -default: a session lives until its token's `exp` or its certificate's notAfter. -`--expires D` bounds a grant with no bound of its own (an anonymous session, a -token without `exp`, a certificate without notAfter). `--revalidate D` has the -relay re-check each grant on that cadence and needs `--expires`, so an outage -still has a bound. Without `--revalidate`, rotating or deleting a key does not -close live sessions. - -`--limit-token N` and `--limit-remote N` need `--revalidate`, and cap live sessions per token and -per remote address (port dropped, IPv4-mapped IPv6 folded), counted from -`connect` and `end` by session id. The cap is a nuisance limit, not a security -boundary: it gates admission and never revokes. A relay that dies without an -`end` holds its slots until they miss two cadences, a restart empties the table -until the fleet's next cadence refills it, and a session admitted while a live -one's slot was missing stays over the cap. A refusal names the rule in the 403 -body. +A JWT is verified against `--key FILE`, `--key-dir DIR`, or `--key-set FILE` +(by `kid`, read per request so rotation needs no restart) and authorized at the +dialed path, as in [Path matching](#path-matching). A bad token is refused; it +never falls through to the anonymous rules. A JWT presented with a certificate +is refused too, because neither can safely win, so a peer presents +`cluster.token` or a certificate, not both. + +Nothing is re-checked or closed by default: a session lives until its token's +`exp` or its certificate's notAfter. `--expires D` bounds a grant with no bound +of its own. `--revalidate D` has the relay re-check each grant on that cadence, +and needs `--expires` so an outage still has a bound. Without `--revalidate`, +rotating or deleting a key does not close live sessions. + +`--limit-token N` and `--limit-remote N` cap live sessions per token and per +remote address. They need `--revalidate`, and are a nuisance limit, not a +security boundary: approximate across relay crashes and server restarts, and +they gate admission without revoking. `--listen unix:/run/moq-auth.sock` serves a socket. Binding anything but a loopback address needs `--listen-public`: the server has no authentication of -its own. +its own. See `moq auth serve --help` for the rest. ### Migrating from the relay flags -Most of the 0.14 relay flags below were deleted; their policy moves to the -server and the relay gets `--auth-url`. A relay without a server keeps -`--auth-public`, as patterns: `--auth-public 'PREFIX/**'`. With a server, the -anonymous rules move too. +The 0.14 relay's auth flags moved to `moq auth serve`, and the relay points +`--auth-url` at it. A relay without a server keeps `--auth-public`, as +patterns: `--auth-public 'PREFIX/**'`. | 0.14 relay flag | `moq auth serve` | | --- | --- | @@ -351,35 +273,24 @@ moq-relay --auth-url http://127.0.0.1:4440/ ### In process -An application that [embeds](/bin/relay/#embed) the relay can be the auth -server without the HTTP: leave `[auth]` empty and take `relay.admissions()` -before `run`. Each `Admission` carries the same `moq_auth::Request` the server -would have read, and is answered with `grant(lease)` or `refuse(err)`. A -`lease::Consumer::fixed(grant)` never changes. A `lease::Producer` the -application keeps owns the re-check clock: `due()` -yields `Revalidate` or `Expired`, `update(grant)` resets it, and `failed()` -schedules bounded backoff after an outage. The producer also learns when the -session ends. Either way the relay closes the session at the -grant's `expires`. `run` refuses to start while nobody has taken the -admissions, a dropped `Admissions` fails every later session as unavailable, -and an admission left unanswered for ten seconds (the bound an auth server -gets) is refused the same way. Gateway accept loops can call -`Cluster::admit(&auth, request)` for the same scoped publisher, subscriber, -stats tier, and lease as a native connection, then run work under -`auth::hold(lease, work)` so a revoke cancels it. - -The decider keeps each `lease::Producer` after answering `Admission::grant`. -It waits for `producer.due()` alongside `producer.closed()`, updates on a fresh -grant, calls `failed()` after an outage, and revokes on refusal or expiry. A -re-check request from the session wakes `due()` before the cadence. +An application that [embeds](/bin/relay/#embed) the relay can decide +admissions itself, without the HTTP: leave `[auth]` empty and take +`relay.admissions()` before `run`. Each `Admission` carries the same +`moq_auth::Request` a server would read, and is answered with a lease or a +refusal. A fixed lease never changes; a `lease::Producer` the application keeps +re-checks, updates, and revokes on its own clock. The relay still closes the +session at the grant's `expires`, and an admission left unanswered for ten +seconds is refused. Gateway accept loops can call `Cluster::admit` for the same +scoped session as a native connection. See +[docs.rs/moq-relay](https://docs.rs/moq-relay) and +[moq-auth](/lib/rs/moq-auth). ## Stream listeners The plaintext TCP and Unix-socket listeners are admitted exactly like QUIC: the path and query ride the `SETUP` (`tcp://127.0.0.1:4444/room?jwt=...`) and -reach the auth server in the same request shape, with `transport` set to `tcp` -or `unix` and no addresses on a socket. A Unix socket can also -require a specific uid, gid, or pid: +reach the auth server with `transport` set to `tcp` or `unix`. A Unix socket +can also require a specific uid, gid, or pid: ```toml [listen.unix] @@ -389,10 +300,8 @@ allow.uid = [1001] Bind plaintext TCP to loopback or a private interface; it carries no peer identity. The Unix socket is created mode `0666`, so gate it with a restrictive -parent directory or an explicit allowlist. -These are native-only paths for gateways and stats publishers on the same host. +parent directory or an allowlist. -`listen.tcp.tls = true` serves the TCP listener over TLS with the listen -certificate instead, for `tls://` dials such as [cluster links](/bin/relay/cluster#tls-links) -that need neither QUIC nor a WebSocket. It still carries no peer identity: it -asks for no client certificate, so a peer on it presents a token, not mTLS. +`listen.tcp.tls = true` serves the TCP listener over TLS instead, for `tls://` +dials such as [cluster links](/bin/relay/cluster#tls-links). It asks for no +client certificate, so a peer on it presents a token, not mTLS. diff --git a/doc/bin/relay/cluster.md b/doc/bin/relay/cluster.md index 5aba2c0ff5b..93afe5a13d5 100644 --- a/doc/bin/relay/cluster.md +++ b/doc/bin/relay/cluster.md @@ -16,43 +16,27 @@ same way so the cluster converges instead of flapping. Both wire protocols carry it: natively on moq-lite, and via the [cluster extension](/draft/moq-cluster) on moq-transport 17+. -When a moq-lite-04 or later peer withdraws its last advertisement for a broadcast, a relay -drops every other route to it that passed through that peer, since each was -relayed from what the peer just withdrew, rather than falling back to them one -by one. During reconnect, another session from that peer can still advertise -the broadcast; an old session's withdrawal does not invalidate that route. - -A relay two hops from the publisher's still holds routes relayed through others. -So a change of a broadcast's best route waits 300 ms before it is announced, -while a new broadcast and a removed one go out at once. By then the withdrawal -has usually removed the other stale routes too, and the relay sends one -retraction instead of advertising each stale path in turn. Requests still -follow the current best route immediately; only the announcement waits. +When a moq-lite-04 or later peer withdraws a broadcast, the routes relayed +through it go with it at once. A change of best route is announced after +300 ms, so stale paths are retracted once instead of advertised in turn; +requests follow the new best route immediately. Routes carrying the same [publisher epoch](/concept/moq-lite#publisher-epochs) serve one broadcast. When the route serving it dies, withdraws, or is beaten by -a cheaper route with that epoch, each subscription continues on the new route -from the first frame its readers lack, so they see -every frame once, mid-group included. A route that is still up finishes the -groups it has open, overlapping the new one. A group neither route delivers is -dropped once the readers' max delay has passed it. A route through the subscribing peer -itself is never used. A publisher whose groups restart, such as an encoder -restarting from group 0, publishes under a new epoch, which replaces the old -broadcast instead of resuming it. A route without an epoch, including every -route on moq-lite 06 and older or moq-transport, keeps its subscriptions until it -goes. Seamless failover needs both: a publisher that announces an epoch, and -moq-lite 07 on every link the route crosses, since epochs travel on nothing -older. A cluster that mixes moq-lite 06 and 07 links to the same content has a -second cost: the route that carries the epoch supersedes the one that does not -each time it appears, so a flapping moq-lite 07 link cuts the viewers resolved -through the older one. - -Failover routes must carry copies of the same broadcast. For each track, the -relay requires matching timescale, retention window, publisher priority, and -group ordering. A source with different properties is refused before it serves -the track. If no compatible source remains, the track fails with -`Unsupported`. New immutable properties require a new track name or broadcast -name. +a cheaper one with that epoch, each subscription continues on the new route +from the first frame its readers lack, so they see every frame once. A +publisher whose groups restart, such as an encoder restarting from group 0, +publishes under a new epoch, which replaces the old broadcast instead of +resuming it. Seamless failover needs a publisher that announces an epoch and +moq-lite 07 on every link the route crosses. A route without an epoch, +including every route on moq-lite 06 and older or moq-transport, keeps its +subscriptions until it goes. In a cluster that mixes moq-lite 06 and 07 links +to the same content, a flapping 07 link cuts the viewers resolved through the +06 one. + +Failover routes must carry copies of the same broadcast: a source whose track +differs in timescale, retention, publisher priority, or group order is refused +for that track. A route whose original publisher (its first hop) changes is updated in place on both wire protocols, so the broadcast never briefly vanishes downstream, and @@ -102,18 +86,12 @@ connect = [ ] ``` -The mark belongs to the link, whichever side dialed. A peer this relay dials -is upstream when its `connect` or `connect_api` entry says so. A peer that -dials in is upstream when its [grant](/bin/relay/auth#the-contract) sets -`"upstream": true` beside `"peer": true`, so an edge whose auth server grants -that to core certificates treats a core that dials it as upstream too. A -relay that predates the mark treats every link as transit, so a cluster -migrates one region at a time. - -Which relay dials which is still the peer list's job: there are no roles and -no topology check, so whatever generates the list applies the layout's rules. -Hiding a core from clients is admission, not routing: its auth refuses any -session that is not a cluster peer. +The mark belongs to the link, whichever side dialed: a dialed peer is upstream +when its `connect` entry says so, and a peer that dials in when its +[grant](/bin/relay/auth#the-contract) sets `"upstream": true` beside +`"peer": true`. A relay that predates the mark treats every link as transit, +so a cluster migrates one region at a time. There are no roles and no topology +check; whatever generates the peer list applies the layout's rules. ## TLS links @@ -142,60 +120,32 @@ link costs 1, which reproduces plain hop counting. Each relay adds the price of the link an announcement arrived on before forwarding it, so a route's cost is the sum of what it crossed. -Prefix advertisements are forwarded and costed the same way as an exact-path -route: each hop appends its identity, adds the link price, and passes the -claim on. An advertised prefix must overlap the publisher's grant, or it is -refused. A prefix wider than the grant is accepted, but it only routes requests -for paths the grant covers. - Routing prefers the longest covering prefix, then a fully identified hop list -over one that holds a 0 (an anonymous hop) at any depth, then the lowest cost, -then the shortest hop list, then a hash of the requested path and the hop list, -breaking any remaining tie toward the newest announcement so a reconnecting -publisher isn't outranked by the session it replaced. Hashing the requested -path spreads equal-cost advertisers of one prefix, such as a transcode pool, -across its paths instead of sending every path to one of them, and every relay -that holds the same routes picks the same one for a given path. An assigned -identity for an anonymous peer is local selection state and is never written -into the hop list. +over one holding an anonymous hop (0), then the lowest cost, then the shortest +hop list. Remaining ties hash the requested path, so equal-cost advertisers of +one prefix, such as a transcode pool, split its paths, and every relay picks +the same one for a given path. ```toml [cluster] connect = ["https://sibling.same-dc/?cost=0", "https://us-east.example.com/?cost=10"] ``` -The same policy reads as an object, which is the only form that accepts -`egress`, `token`, and [`upstream`](#upstream-links). A bare URL stays valid, and an object whose `url` still -carries `?cost=` or `?jwt=` alongside those fields is rejected rather than -given a precedence a migration could silently get wrong. +The same policy reads as an object, the only form that accepts `token` and +[`upstream`](#upstream-links): ```toml [cluster] connect = [ { url = "https://sibling.same-dc/", cost = 0 }, - { url = "https://us-east.example.com/", cost = 10, egress = 10, token = "PEER_JWT" }, + { url = "https://us-east.example.com/", cost = 10, token = "PEER_JWT" }, ] ``` -`cost` is what this relay charges to pull from the peer. `egress` is what it -declares in SETUP as its own price toward the peer and defaults to `cost`; -anything else is refused until asymmetric routing lands, so the two are always -equal today. `token` replaces an inline `?jwt=` with identical authorization -and redaction. - -Price is per direction: pulling from a metered origin can cost far more than -pushing to it, so each end declares its own and the two need not match. Prices -aren't static either. A publisher can re-price a live announcement, which is how -a standby transcoder pool seeds a high cost and drops it once it's working, and -a relay receiving a GOAWAY re-prices every route learned from that peer to the -maximum so new subscriptions go elsewhere while existing ones finish. - -moq-lite-06 announcements carry two prices, *warm* and *cold*. Both accumulate -identically today, so routing runs on link costs alone; the split reserves room -for a warm-copy discount, letting a relay advertise its cached copy cheaper on -the warm side while the cold price still says who sits closest to the publisher. -moq-transport has nowhere to carry the cold price, so a route learned from it -ranks with an unknown (worst-case) one. +Prices aren't static. A publisher can re-price a live announcement, which is +how a standby transcoder pool seeds a high cost and drops it once it's working, +and a relay receiving a GOAWAY re-prices every route learned from that peer to +the maximum so new subscriptions go elsewhere while existing ones finish. ## LAN discovery @@ -216,20 +166,12 @@ enabled = true # app = "default" # DNS-SD subtype; moq-cli shares this name. ``` -A LAN peer authenticates with its mDNS credential on `/.cluster/` -and is never handed `cluster.token`; that token is for `connect` and -`connect_api` peers only. The advertisement carries the listener fingerprint -when the certificate was generated or supplied in-memory, the `node` URL when -one is configured, and at least one of them. `secret` is optional. Without it, anyone who can -reach the listener joins, so leave it unset only on networks you trust. With -it, only peers that prove they hold the same key are discovered or accepted. -mDNS is still an open channel: the secret authenticates the record, it does -not hide the credential or the node URL. `app` names the DNS-SD application -this relay advertises under; peers using a different name never discover it. -It defaults to `default`, which moq-cli shares so the two find each other -with no configuration. An application built on the library picks its own -name. Startup waits for at least one interface to announce before the relay -reports itself ready. +A LAN peer authenticates with a credential carried in its mDNS record and is +never handed `cluster.token`. Without `secret`, anyone who can reach the +listener joins, so leave it unset only on networks you trust. With it, only +peers that hold the same key are discovered or accepted. The secret +authenticates the record; it does not hide the node URL. Peers advertising a +different `app` never discover each other. ## Dynamic peer lists @@ -276,24 +218,13 @@ timeout; WebSocket links keep their own 30s deadline. Peers dial with **mTLS** (recommended: `listen.tls.root` on the listener, `connect.tls.cert`/`key` on the dialer) or a **JWT** (inline `?jwt=` on a peer URL, `token` on a peer object, or a shared `cluster.token` file for every -listed peer). The -accepting relay admits a peer through the same lease as any client: its -certificate is reported to the auth server, which grants it, so a mesh needs -`moq auth serve --mtls-publish '**' --mtls-subscribe '**'` (or a server of -your own that grants the cluster CA) behind `--auth-url`. A relay on -`--auth-public '**'` admits peers through that grant instead, as long as they -send no `cluster.token`: public rules refuse a token. LAN peers -authenticate with the mDNS credential on `/.cluster/`, a secret -the relay minted for itself and checks locally, and never receive -`cluster.token`. Dials retry forever with capped backoff, so a rejected peer -is loud in the logs rather than fatal. See [Authentication](/bin/relay/auth#mtls). - -A relay records whether each route entered here or came from a peer, which the -hop list alone cannot say: a client and a peer each add one hop. Routes over a -dial this relay made, and over an accepted LAN peer, count as a peer's. An -accepted peer counts only when its grant sets `peer: true`; otherwise it looks -like a client ingesting here. An embedder reads this as `Route::source()` and -filters with `origin::Consumer::local()`. +listed peer). The accepting relay admits a peer like any client, so a mesh +needs an auth server that grants the cluster CA, such as +`moq auth serve --mtls-publish '**' --mtls-subscribe '**'`. An accepted peer +counts as a cluster peer only when its grant sets `peer: true`, which +`moq auth serve` never does; otherwise what it announces counts as ingest +here, like a client's. Dials retry forever with capped backoff, so a rejected +peer is loud in the logs rather than fatal. See [Authentication](/bin/relay/auth#mtls). The `/nodes` [internal endpoint](/bin/relay/http#get-nodes) lists the peers this relay dialed and holds a session with. diff --git a/doc/bin/relay/config.md b/doc/bin/relay/config.md index d7fc698709e..ab36ee3f5b7 100644 --- a/doc/bin/relay/config.md +++ b/doc/bin/relay/config.md @@ -5,13 +5,11 @@ description: TOML reference for moq-relay # Configuration -`moq-relay relay.toml`. Every key is also a CLI flag and environment variable. -Most names join the section and key: `listen.tls.cert` is -`--listen-tls-cert` / `MOQ_LISTEN_TLS_CERT`. The `listen.bind` key deliberately -uses the shorter `--listen` / `MOQ_LISTEN` spelling. -Precedence is CLI > env > file > defaults: a flag or environment variable that -was actually supplied overrides the file, and a file key that was actually -written (an empty list, a `false` boolean) overrides the built-in default. +`moq-relay relay.toml`. Every key is also a CLI flag and environment variable +that joins the section and key: `listen.tls.cert` is `--listen-tls-cert` / +`MOQ_LISTEN_TLS_CERT`. The exception is `listen.bind`, spelled `--listen` / +`MOQ_LISTEN`. Precedence is CLI, then env, then file, then defaults. +`moq-relay --help` lists every flag. ## \[listen] @@ -36,13 +34,9 @@ bind = "/run/moq/internal.sock" allow.uid = [1001] ``` -`timeout` bounds how long an accepted connection has to finish its handshake: -the QUIC, WebTransport, WebSocket, or qmux one, then the MoQ SETUP, through the -relay accepting the session. After that it is an ordinary session. A peer that -connects and never speaks is closed instead of being held open by keep-alives, -with the MoQ timeout code once its transport is up. The `[web]` listeners apply it to reading HTTP request -headers and, for the WebSocket fallback, to the SETUP after the upgrade. The -`io_uring` workers do not apply it yet. +`timeout` bounds the whole handshake, transport through MoQ SETUP, so a peer +that connects and never speaks is closed instead of held open by keep-alives. +The `io_uring` workers do not apply it. ## \[quic] @@ -62,27 +56,16 @@ send_window = 33554432 # Unacknowledged outgoing data. Omit for th qlog = "/var/log/moq/qlog" # Existing directory. Needs the `qlog` build feature. ``` -The native QUIC stack uses BBRv3 for delay-based congestion control. Iroh also -uses noq and the same congestion controller. - `idle_timeout` is how long a peer that vanished without a close keeps its sessions, and so its [cluster routes](/bin/relay/cluster#failure-detection). -QUIC uses the smaller of the two endpoints' values -([RFC 9000 section 10.1](https://www.rfc-editor.org/rfc/rfc9000#section-10.1)), -so this also bounds the clients and peers on the other end. Keep `keep_alive` -under a third of it, so a quiet connection that loses one ping still pings -again before the deadline. - -Raise the receive windows when a fat, long path idles below the link rate: a -window under the bandwidth-delay product stalls the sender waiting for credit. -`receive_window` bounds how much unread data one peer can make the relay buffer -across all of its streams; the transport's own default is unlimited, so it -defaults to 64 MiB, enough for a relay-to-relay session to carry several Gbps at -a 100 ms RTT. -Keep `stream_receive_window` well under `receive_window` so one slow group -cannot starve the connection. `send_window` caps unacknowledged outgoing data -whatever the peer allows, bounding the transport send buffer. A zero window is refused, and the receive windows must fit a QUIC -varint since they ride on the wire as transport parameters. +QUIC uses the smaller of the two endpoints' values, so this also bounds the +other end. Keep `keep_alive` under a third of it. + +Raise the receive windows when a fat, long path idles below the link rate. The +64 MiB `receive_window` default carries several Gbps at a 100 ms RTT and bounds +how much unread data one peer can make the relay buffer. Keep +`stream_receive_window` well under it so one slow group cannot starve the +connection. ## \[runtime] @@ -99,23 +82,13 @@ io_uring = false # Drive them with io_uring instead of tokio ``` Packets are steered by connection ID, so a client that migrates stays with its -worker. The group shares one port, including an ephemeral (zero) port, which is -resolved once and joined by every worker. Use an explicit port unless -something reads the bound address at startup. `workers` needs the `noq` -feature and real certificate files rather than `tls.generate`. A build without -QUIC rejects `workers` instead of -ignoring it. An embedding process leaves this group inside `Relay::run`; -taking the sockets out and driving them yourself is how a later library -update can drop QUIC while still compiling. `io_uring` additionally needs Linux 6.12+, the `io-uring` cargo -feature, and exactly one certificate read at startup; it serves moq-lite only, -and refuses to start anywhere it cannot deliver. `[quic]` applies either way, -except that `mtu_discovery` (its datagram path sends a fixed payload) and the -three flow-control windows (these workers run fixed ones) are refused under -`io_uring` rather than quietly ignored. Each worker reports its own counters at -[`/metrics`](/bin/relay/http#get-metrics). The kernel charges each worker's -ring (~56 KiB, plus a page per socket) to `RLIMIT_MEMLOCK`, a budget shared by -every io\_uring the user runs; raise it (`LimitMEMLOCK=` under systemd) if -workers fail to start with a message naming that limit. +worker. `workers` needs the `noq` feature and real certificate files rather +than `tls.generate`. `io_uring` additionally needs Linux 6.12+, the `io-uring` +cargo feature, and exactly one certificate; it serves moq-lite only, and +refuses `mtu_discovery` and the flow-control windows. A setting the build or +host cannot deliver refuses to start rather than being ignored. If io\_uring +workers fail to start naming `RLIMIT_MEMLOCK`, raise it (`LimitMEMLOCK=` under +systemd). ## \[web] @@ -181,15 +154,10 @@ goaway.handover = "10s" # Cap on how long the drained upstream keep ``` A draining upstream may name a replacement URI. `same-host` follows it only -onto the host we already dialed, so a peer moves us between ports and schemes; -`follow` also lets it choose the host, which means trusting it not to point us -into the local network, since a name it controls resolves wherever it likes; -`ignore` keeps the current address list. An empty URI also keeps it, including -caller-configured fallbacks; an accepted redirect replaces the list with the -peer's URI. A malformed or refused redirect ends the connection with an error -rather than redialing the old address or a fallback, and so does one leaving -the host a `tls.fingerprint` pin verifies. `handover` is a cap: a shorter deadline on -the received GOAWAY wins, a longer one does not extend it. +onto the host already dialed, so a peer can move us between ports and schemes; +`follow` also lets it choose the host, which trusts it not to point us into +the local network; `ignore` keeps the current address. `handover` caps how long +the old connection keeps serving after a GOAWAY. ## \[cache] @@ -200,21 +168,10 @@ headroom = "2GiB" # Or: keep this much system memory free and duration = "30s" # Cap how long a non-latest group is kept, whatever the publisher asked. ``` -`duration` defaults to 30s and bounds memory by age, where `capacity` bounds it -by bytes. The latest group of every track is always kept. The two reclaim -differently: the byte budget is repaid as tracks write, so it caps what *active* -publishers build up, while `duration` sweeps on a wall-clock cadence, so a -publisher that stalls but stays connected still has its idle groups reclaimed -(an open one included, and a subscriber parked inside it is told rather than -waiting forever). - -`headroom` starts a background task that re-samples system memory every few -seconds and resizes the pool. Embedders calling `cache::Config::init` directly -should know that the task is owned by the `cache::Pool` it resizes, not by the -`cache::Cache` struct or the `Relay`: it stops on its next tick once the last `Pool` -clone drops. Handing the `cache::Cache` to `cluster::Cluster::new` therefore moves the -task's lifetime onto the cluster, and keeping a `Pool` clone of your own keeps -the task running for as long as you hold it. +`capacity` bounds memory by bytes, as active publishers write. `duration` +(30s by default) bounds it by age, and sweeps on a timer, so a publisher that +stalls but stays connected still has its idle groups reclaimed. The latest +group of every track is always kept. ## \[stats] @@ -228,12 +185,11 @@ depth = 1 # Also bucket by the first N path segments linger = "5m" # Keep an empty group's broadcast announced this long. Default. ``` -Each node publishes `publisher.json`, `subscriber.json`, and `sessions.json` -tracks (plus compressed `.json.z` twins) of cumulative counters per broadcast -and auth root, split by a **tier** label chosen by the auth server's grant or -`--cluster-tier`, which is what makes billing per customer or per region -possible. [Stats](/concept/stats) describes the paths, tracks, and encodings; -read them with the [`moq-stats`](https://docs.rs/moq-stats) crate. +Each node publishes its traffic and session counters as MoQ tracks, split by a +**tier** label from the auth server's grant (`--cluster-tier` for links this +relay dials), which is what makes billing per customer or per region possible. +[Stats](/concept/stats) describes the paths, tracks, and encodings; read them +with the [`moq-stats`](https://docs.rs/moq-stats) crate. ## \[iroh] @@ -253,20 +209,12 @@ drain_timeout = "10s" # Top-level key, as --drain-timeout / MOQ_D ``` The first SIGTERM or SIGINT starts a drain: every session is sent a GOAWAY -asking it to reconnect, and is force-closed if it is still connected when the -window ends. A session that connects during the drain, such as a client with a -cached DNS answer, is sent a GOAWAY immediately, with only the time left in -the window. The relay exits as soon as every session has left, when the window -ends, or immediately on a second signal. `0` skips the GOAWAY and closes every -session at once. - -The exit is logged with how long the drain took, as either -`drain complete: every session left` or `drain deadline force-closed sessions` -with the number `forced`. A session still in its handshake when the last one -leaves is not waited for. -Only moq-lite-04+ and moq-transport clients act on a GOAWAY; older ones are -closed when the window ends. An embedder can take over the signals and start -the drain itself; see [Embed](/bin/relay/#embed). +asking it to reconnect elsewhere, including any that connect during the drain, +and is force-closed if it is still connected when the window ends. The relay +exits as soon as every session has left, when the window ends, or immediately +on a second signal. `0` skips the GOAWAY. Only moq-lite-04+ and moq-transport +clients act on a GOAWAY; older ones are closed when the window ends. An +embedder can take over the signals; see [Embed](/bin/relay/#embed). ## \[log] @@ -275,19 +223,11 @@ the drain itself; see [Embed](/bin/relay/#embed). level = "info" # RUST_LOG overrides this. ``` -At `info` the relay logs one `listening` record for the `[listen]` QUIC socket -and each public `[web]` listener as it binds. Each record carries the bound -address and a `kind` naming the listener: +At `info` the relay logs a `listening` record with the bound address for each +QUIC and public `[web]` listener, so a port of `0` reports the port the OS +picked. ``` INFO listening addr=[::]:4443 kind=quic INFO listening addr=[::]:4443 kind=http -INFO listening addr=[::]:8443 kind=https ``` - -For these listeners, `addr` is the address the socket bound, not the one -configured, so a `listen` port of `0` reports the port the OS picked. That is -the only way to learn it from outside the process, and the QUIC and TCP ports -are chosen independently. -A relay with no `[listen]` UDP socket logs `listening (stream transports only)` -instead of the `quic` line. diff --git a/doc/bin/relay/http.md b/doc/bin/relay/http.md index 7975a39e29e..10e2c33f910 100644 --- a/doc/bin/relay/http.md +++ b/doc/bin/relay/http.md @@ -22,24 +22,12 @@ curl http://localhost:4443/announced/demo curl http://localhost:4443/fetch/demo/bbb.hang/catalog.json ``` -The announcement listing names each announced route by the prefix it covers; -by convention a publisher announces each broadcast's exact path, so the list -reads as broadcast names. - `moq announced` and `moq fetch` answer the same questions over MoQ; see [Inspect a relay](/bin/inspect). -A relay configured with more than one certificate has no single fingerprint to -publish, and this endpoint answers for the first. The others are reachable over -`https://`, which selects a certificate by SNI at the handshake. - -GET responses on the public router receive a wildcard CORS origin unless the -route sets its own policy. This includes routes merged by an embedding -application. GET preflights are supported; routes using other methods configure -their own CORS policy. - -Tokens sent over plain HTTP are visible on the wire, so use HTTPS in -production. +GET routes on the public router, including ones an embedder merges in, get a +wildcard CORS origin unless the route sets its own. Tokens sent over plain HTTP +are visible on the wire, so use HTTPS in production. ## Internal @@ -51,64 +39,33 @@ listen = "127.0.0.1:9101" ### GET /metrics Prometheus text: bytes, frames, groups, subscriptions, viewers, and sessions -split by `tier` and `role`, plus accept-loop counters per TCP listener. Alert -on `moq_relay_accept_failures_total{class="exhausted"}`, which means the -process ran out of a resource `accept` needs. Content dropped for drifting past -a subscriber's budget is counted separately as `moq_relay_stale_bytes_total` -and friends. During a [shutdown drain](/bin/relay/config#shutdown), -`moq_relay_draining_sessions` counts the sessions sent a GOAWAY that have not -left yet. Host CPU and memory belong to a node exporter. - -`moq_relay_sessions_refused_total` counts the session attempts admission turned -away, by `reason`: - -- `refused`: the decider said no (the auth server, the public rules, or an - embedder). -- `unavailable`: the decider could not answer, so the client is told to retry - (the auth server was unreachable or answered with neither a grant nor a - refusal, a decider sent a grant the relay cannot use, or an embedder did not - answer). -- `request`: an embedder refused the request as one it cannot decide. -- `forbidden`: the grant allows nothing the session asked for, or an embedder - refused the session as forbidden. -- `lan`: a LAN peer's membership proof was missing or wrong, or LAN discovery - is off. - -Only sessions are counted. The HTTP routes admit through the same decider but -open no session, so like `moq_relay_sessions_opened_total` this leaves them out, -and a refusal earlier in the handshake, such as TLS, never reaches admission. A -rise in `unavailable` points at the auth server; a rise in `refused` at the -credentials clients present. - -Each attempt counts once, so this is refused attempts, not refused clients, and -one connect can be refused more than once. A client that races WebSocket against -QUIC can be refused on both when its WebSocket upgrade goes out before QUIC -connects; the browser client starts WebSocket after a head start, or at once for -a URL where WebSocket won before. A client that cannot tell a refusal from a -failure retries, and each retry counts: a browser refused over WebSocket sees no -status and retries until its reconnect window closes, while a credential refusal -over QUIC closes the session as unauthorized, which stops it. - -Traffic and session counters accumulate for the node's lifetime, including -broadcasts and sessions that have ended. The stats publishing prefix (normally -`.stats`) is excluded to avoid counting the feed's own traffic. - -With `--runtime-io-uring`, each QUIC worker thread also reports its own -`moq_relay_uring_*` counters under a `worker` label: datagrams and syscalls -(the ratios are the GRO/GSO batching and the syscall amortization the runtime -exists for), buffer-pool backpressure (`rx_enobufs`, `rx_exhausted`, -`tx_stalls`), cross-thread wakes, and timer churn. Every worker reports from -the moment the port is bound, so a dead one shows stuck zeros rather than -disappearing. These describe the process, not the traffic, so they never appear -on the `.stats` broadcast. +split by `tier` and `role`, plus accept-loop counters per TCP listener. Traffic +counters accumulate for the node's lifetime and leave out the stats feed's own +traffic. Host CPU and memory belong to a node exporter. + +A few worth alerting on: + +- `moq_relay_accept_failures_total{class="exhausted"}`: the process ran out of + a resource `accept` needs. +- `moq_relay_sessions_refused_total`, by `reason`. A rise in `unavailable` + points at the auth server; a rise in `refused` at the credentials clients + present. Each attempt counts, so a client that retries is counted again. +- `moq_relay_stale_bytes_total` and friends: content dropped for drifting past + a subscriber's latency budget. +- `moq_relay_draining_sessions`: sessions sent a GOAWAY during a + [shutdown drain](/bin/relay/config#shutdown) that have not left yet. + +With `--runtime-io-uring`, each QUIC worker also reports `moq_relay_uring_*` +counters under a `worker` label. A dead worker shows stuck zeros rather than +disappearing. ### GET /sessions -Live sessions on this node. The filter is query parameters: any subset of -the fields the auth server already saw (`id`, `path` as a pattern, `remote` -as an IP or CIDR, `transport`, `tls.name`, ...). Every given field must -match; an empty filter is everyone. Each entry is the request plus start -time, with `query` omitted. An unknown field, including `query`, is 400. +Live sessions on this node. Query parameters filter on the fields the auth +server already saw (`id`, `path` as a pattern, `remote` as an IP or CIDR, +`transport`, `tls.name`, ...); every given field must match, and an empty +filter is everyone. Each entry is the auth request plus start time, without +`query` or `token`. ```bash curl 'http://127.0.0.1:9101/sessions?path=demo/**' @@ -116,10 +73,9 @@ curl 'http://127.0.0.1:9101/sessions?path=demo/**' ### POST /sessions/revalidate -The same filter, a re-check now. Matching sessions are nudged and the -response is 202 with their ids; no match is 200 with an empty list. The -relay re-POSTs `revalidate` and the auth server's reply is the verdict. -One node, no cluster fan-out. +The same filter, re-checked now: the relay asks the auth server again for each +match and applies its answer. See [push](/bin/relay/auth#push). One node, no +cluster fan-out. ```bash curl -X POST 'http://127.0.0.1:9101/sessions/revalidate?id=00ff' diff --git a/doc/bin/relay/index.md b/doc/bin/relay/index.md index a897c95c67a..481dc1a1e91 100644 --- a/doc/bin/relay/index.md +++ b/doc/bin/relay/index.md @@ -52,11 +52,10 @@ working configs for development, production, and a cluster. ## Embed -`moq-relay` is also a library. An application that wants extra HTTP routes -or in-process workers against the cluster origin loads a `Relay` and calls -`run`. The owner keeps the listeners, QUIC workers, and shutdown joins, so a -new socket added in a library update cannot be dropped by a `..` pattern that -still compiles. +`moq-relay` is also a library, for an application that wants extra HTTP +routes or in-process workers against the cluster origin. Load a `Relay`, take +what you need, and call `run`, which keeps the listeners, QUIC workers, and +shutdown inside the relay. ```rust use axum::routing::get; @@ -69,33 +68,19 @@ let web = relay.web().routes().route("/hello", get(|| async { "hello" })); relay.with_web(web).run().await?; ``` -`Relay::load` binds every socket, so a taken port fails there. Read the actual -addresses with `quic_addr()`, `tcp_addr()`, `web_addrs()`, and -`internal().addr()`, including ports assigned for `:0`. Clone -`ready()` before spawning `run`, then await `ready.wait()` when startup must -finish before other workers begin. `config()` returns the resolved settings; -`cluster().id()` returns the chosen origin ID. `with_listeners()` registers an -extra TCP listener's accept health at the relay's `/metrics`. The -`test-support` feature provides `test_relay()` with ephemeral ports, generated -TLS, and a certificate fingerprint for client pinning. - -The accessors borrow and `run` consumes the relay, so clone `cluster`, -`auth`, `client`, `stats`, `shutdown`, and `shutdown_trigger` for application -tasks before calling it. `trigger.start()` drains every session with a GOAWAY, -including any that connect afterwards, and `run` returns once every session -has left or the drain window elapses, with the listeners released and the -workers joined. `run` also starts -the drain on SIGTERM or SIGINT. An application that owns those signals, for -example to withdraw the node from DNS and wait out the TTL before draining, -calls `with_signals(false)` and fires the trigger itself. Build routes from `web().routes()` (or -`internal().routes()`): `with_web` replaces the router, so `Router::new()` -drops the built-in routes. Extra listeners (RTMP, SRT, ...) sit beside `run` -in the application's `select!`. The drain reaches only MoQ sessions: an -extra listener has no GOAWAY, so the application stops it on its own deadline -and leaves the encoder to reconnect. `runtime.workers` and `runtime.io_uring` stay -inside the owner; do not split the worker group yourself. An application that -decides admissions itself leaves `[auth]` empty and answers -`relay.admissions()`; see [Authentication](/bin/relay/auth#in-process). See +- `Relay::load` binds every socket, so a taken port fails there, and the + accessors report the bound addresses, including ports assigned for `:0`. +- `run` consumes the relay, so clone the handles your tasks need first. +- Build on `web().routes()`: `with_web` replaces the router, so `Router::new()` + drops the built-in routes. +- `run` drains on SIGTERM or SIGINT. To own the signals, for example to leave + DNS before draining, call `with_signals(false)` and fire `shutdown_trigger()` + yourself. The drain reaches only MoQ sessions, so stop any extra listener + (RTMP, SRT, ...) on your own deadline. +- To decide admissions yourself, leave `[auth]` empty and answer + `relay.admissions()`; see [Authentication](/bin/relay/auth#in-process). + +See [docs.rs/moq-relay](https://docs.rs/moq-relay) and [`rs/moq-relay/examples/embed.rs`](https://github.com/moq-dev/moq/blob/main/rs/moq-relay/examples/embed.rs). ## Operate diff --git a/doc/bin/rtmp.md b/doc/bin/rtmp.md index c40a914d9ca..4f8989295ae 100644 --- a/doc/bin/rtmp.md +++ b/doc/bin/rtmp.md @@ -39,34 +39,7 @@ Any other player receives one video rendition: the largest picture (then highest bitrate) in a codec it advertised. A push carries the largest one. Implemented in pure Rust (no librtmp). The CLI speaks plaintext `rtmp://` -only. The library adds RTMPS on the same port when the embedder supplies a TLS -config, and by default still accepts plaintext `rtmp://` there, so stream keys -can arrive unencrypted. The embedder can set `plaintext` to `false` to serve -`rtmps://` only: a plaintext client is refused at its first byte and the refusal -is logged with the peer address. Refusing plaintext without a TLS config fails -at startup. FLAC and MP3 enhanced-audio payloads are dropped because hang has no +only, so stream keys cross the network unencrypted. The library adds RTMPS on +the same port when the embedder supplies a TLS config, and can refuse plaintext +there. FLAC and MP3 enhanced-audio payloads are dropped because hang has no catalog codec for them. - -Incoming chunk streams are reassembled independently, including interleaved -control, audio, and video messages. Each connection retains at most 256 chunk -stream IDs, including completed streams' header history needed by compressed -headers. Reusing an ID does not consume another slot; the connection releases -all slots on teardown. A 257th distinct ID is refused, even if its numeric ID is -small. The limit counts streams rather than constraining their numeric IDs. - -Incomplete messages reserve their declared payload lengths against a 64 MiB -connection budget before allocation. Completion or an RTMP Abort releases that reservation; -malformed input or exhaustion closes the connection and releases its parser -state. The 24-bit RTMP message length still allows a payload up to 16 MiB minus -one byte. Four maximal payloads fit, with exactly four bytes remaining. - -These internal limits leave room for the gateway's five chunk-stream roles -and [FFmpeg's fixed control/audio/video channels](https://github.com/FFmpeg/FFmpeg/blob/master/libavformat/rtmppkt.h) -as well as [OBS's control and media channels](https://github.com/obsproject/obs-studio/blob/master/plugins/obs-outputs/librtmp/rtmp.c). -They bound retained state independently of chunk size and retain support for -large keyframes. Undecoded input has a separate 64 MiB buffer limit. -Connections exceeding these limits are unsupported. - -Run `just rs bench-rtmp` to compare decoding one active stream while 1, 16, 64, -or 256 streams retain state, across 128-byte, 4 KiB, and 64 KiB messages with -128-byte and 4 KiB chunks. The benchmark smoke runs nightly. diff --git a/doc/bin/srt.md b/doc/bin/srt.md index 12828b9c49b..2d2976dc4fb 100644 --- a/doc/bin/srt.md +++ b/doc/bin/srt.md @@ -7,14 +7,10 @@ description: SRT contribution and playback `moq import srt` accepts SRT pushes (`--listen`) or pulls from a remote SRT source (`--connect`); `moq export srt` serves SRT to players or pushes to a -remote. The payload is MPEG-TS, so the same codecs as [`import ts`](/bin/cli) -apply: H.264/H.265 video and AAC, MP2, AC-3, or E-AC-3 audio. Ingest logs the -same per-stream lines as `import ts`, under an `srt{path=...}` span: an -elementary stream that stopped delivering access units, audio frame sync lost, -damaged units refused on each PID, and the TR 101 290 counters when one moves. -They grade the TS as SRT delivered it, after retransmission. Damage drops that -unit and keeps the session alive; video closes its group at the break and -resumes at its next keyframe, freezing for up to one GOP. +remote. The payload is MPEG-TS, so the same codecs and behavior as +[`import ts`](/bin/cli) apply: H.264/H.265 video and AAC, MP2, AC-3, or E-AC-3 +audio. A damaged unit is dropped and the session stays up; video resumes at its +next keyframe, freezing for up to one GOP. ```bash # Accept a contribution feed and publish it @@ -28,10 +24,7 @@ ffplay srt://localhost:9000 moq --connect https://relay.example.com/anon --broadcast event.hang import srt --connect 'srt://encoder.example.com:9000?streamid=live/cam' ``` -Import publishes the feed's own PTS and anchors the catalog clock on its first -frame, as [`import ts`](/bin/cli) does. - -A multi-program feed is refused, as with `import ts`, unless `--program` +A multi-program feed is refused unless `--program` picks one: `--program 2` imports program 2 alone, and `--program all` publishes each program as its own broadcast (`event.hang` becomes `event/1.hang`, `event/2.hang`, and so on). @@ -40,9 +33,7 @@ publishes each program as its own broadcast (`event.hang` becomes moq --connect https://relay.example.com/anon --broadcast event.hang import srt --listen '[::]:9000' --program all ``` -`--latency` sets the SRT receive buffer and doubles as the skip threshold on -export. Export paces each SRT payload on the media clock, and re-anchors that -pacing on a declared marker, so a restarted timeline plays out from the -live edge instead of stalling until it catches up. A `--connect` URL needs a `streamid` query or a path; a listener -bridges one `--broadcast` and ignores the stream id it is offered. The -library is [`moq-srt`](https://docs.rs/moq-srt). +`--latency` (default 500 ms) sets the SRT receive buffer and doubles as the +skip threshold on export. A `--connect` URL needs a `streamid` query or a path; +a listener bridges one `--broadcast` and ignores the stream id it is offered. +The library is [`moq-srt`](https://docs.rs/moq-srt). diff --git a/doc/concept/stats.md b/doc/concept/stats.md index 8d23a0b01e9..5c8e719dde4 100644 --- a/doc/concept/stats.md +++ b/doc/concept/stats.md @@ -39,15 +39,14 @@ for a linger (five minutes by default) after its last one leaves. A group that returns within the linger keeps its broadcast, so viewer churn doesn't unannounce and re-announce it across the mesh; while it lingers empty, its tracks hold `{}`. Once the linger elapses with the group still empty, the -broadcast is unannounced. Group numbers keep increasing across recreated -tracks and group broadcasts for the producer's life; they may have gaps. A -recreated compressed track starts a new group with a full snapshot, never a -delta whose compression state belonged to its previous writer. +broadcast is unannounced. Group numbers keep increasing for the producer's +life, across recreated broadcasts, and may have gaps. ## Tracks Traffic is split by **tier**, an arbitrary label (a billing class, a region) -the relay takes from the auth grant or `--cluster-tier`. Each tier has three +the relay takes from the auth grant, or from `--cluster-tier` for links it +dials. Each tier has three tracks, each in two encodings: | Track | Frame keyed by | Entry | @@ -158,8 +157,7 @@ fraction of the plain track's bytes. - **Groups.** A group's first frame is the full object. Each later frame is an [RFC 7396](https://www.rfc-editor.org/rfc/rfc7396) merge patch against the value so far: it carries only the changed counters, and `null` removes a - dropped entry. The producer starts a new group once the patches outgrow - eight times the snapshot's compressed size, or after 256 frames. + dropped entry. - **DEFLATE.** Each group's frames form one raw DEFLATE stream, sync flushed per frame with the trailing `00 00 ff ff` stripped, as [moq-flate](/draft/moq-flate) specifies. The window starts cold at every diff --git a/doc/concept/transport.md b/doc/concept/transport.md index 5035e90d424..cdac0498b9d 100644 --- a/doc/concept/transport.md +++ b/doc/concept/transport.md @@ -42,11 +42,9 @@ connection (`wss://`) and keep whichever wins. A small multiplexer, [qmux](/draft/qmux-websocket), carries MoQ streams over the socket. It works everywhere but cannot escape TCP head-of-line blocking, so priority and resets only help once bytes leave the TCP queue. The fallback is automatic in every -client; the relay enables it with `[web.https]`. A native Rust client that lands on -WebSocket keeps dialing QUIC and moves the session onto it once the QUIC -session receives the peer's SETUP, staying on WebSocket if the relay refuses it -before SETUP. This crate's relays send SETUP after admission; other servers may -still refuse afterward. +client; the relay enables it with `[web.https]`. A native Rust client that +lands on WebSocket keeps dialing QUIC and moves the session over once QUIC +succeeds. ## Raw QUIC (native) @@ -90,12 +88,6 @@ endpoint id survives restarts. See the [config reference](/bin/relay/config#iroh ## Custom Rust transports -`moq-net` owns the poll traits a transport implements: sessions open and accept -streams, outgoing streams write and reset, and incoming streams read and stop. -Transport errors keep session-close codes separate from stream-reset codes. - -`moq-tokio` and `moq-wasm` adapt their backends at the connection boundary; -`moq-uring::transport::Session::new` wraps a thread-local poll backend. A custom -transport can implement moq-net's traits directly. Backend trait upgrades then -change the adapter without changing moq-net's public transport bounds. See the -[moq-net API](/lib/rs/moq-net). +`moq-net` runs over its own poll traits, so a custom transport implements +those directly. `moq-tokio`, `moq-wasm`, and `moq-uring` are the built-in +adapters. See the [moq-net API](/lib/rs/moq-net). diff --git a/doc/lib/c/index.md b/doc/lib/c/index.md index cfd0fb660ed..a0f1338d4e4 100644 --- a/doc/lib/c/index.md +++ b/doc/lib/c/index.md @@ -10,8 +10,8 @@ description: moq-c, the stable C ABI over the Rust core `moq-c` exposes MoQ to C, C++, and any language with a C FFI through a stable ABI: a generated `moq.h`, a static `libmoq.a` that links the whole Rust runtime in, and a pkg-config file for its native link dependencies. The -[OBS plugin](/bin/obs) is built on it. It was published as `libmoq` through -0.6; the header and library file names did not change. +[OBS plugin](/bin/obs) is built on it. Releases through 0.6 were named +`libmoq`. ## Install @@ -30,29 +30,11 @@ With CMake, point `CMAKE_PREFIX_PATH` at the extracted archive, then `find_package(moq-c)` and link `moq::c`. From source, `add_subdirectory(rs/moq-c)` in CMake gives the same `moq::c` -target. A bare `cargo build --release -p moq-c` writes `target/release/libmoq.a`, -and `moq.h` lands in the build script's `OUT_DIR` under `include/`, a hashed -path that `--message-format=json` reports as `out_dir`. It writes no `moq-c.pc`; -`nix build .#moq-c` produces the same install layout as the release tarball, -pkg-config file included. - -## Shape of the API - -- **Handles and callbacks.** Every object is an integer handle; every async result arrives on a required `moq_status_callback` with a `void *user_data`. A status `> 0` is a live result, `0` a clean close, `< 0` an error, and the last two are terminal: moq-c never touches `user_data` again, so free it there. `*_cancel` only requests shutdown; the terminal callback still fires. -- **Errors.** Negative return codes named by `MOQ_ERROR_*` in `moq.h`, with `moq_error()` giving the reason for the last failure on the calling thread. Auth rejections (401, 403) have their own codes so you don't retry them. A protocol failure also fills `moq_error_protocol()` with the session or stream scope, the verbatim wire code, and a known kind; do not parse `moq_error()` for that. -- **Threading.** Any function from any thread. Raw publish calls block until the codec takes the frame, which paces a publisher. -- **Connection health.** `moq_session_stats()` reports available metrics with per-field validity flags. `moq_session_snapshot()` samples those metrics and the negotiated draft name together from the same connection. Its protocol string is backed by static storage. Both return an offline error between reconnects and leave the destination untouched. `moq_session_bandwidth()` mints an allocator over the send estimate; `moq_bandwidth_reserve` claims a share for an app-owned track, and `moq_encode_video` / `moq_encode_audio` take the same handle so the built-in video encoder follows the grant. -- **Raw playback.** Raw audio and video consumers start at the newest cached group when opened, so rebuilding a live decoder skips the retained backlog. -- **Raw audio encode.** `moq_audio_encoder_output.codec` names the codec: `"opus"`, `"pcm"`, or `"aac"`. `frame_duration_us` sets the Opus frame length: 2500, 5000, 10000, 20000, 40000, or 60000, with 0 meaning the codec's default (20 ms for Opus, 1024 samples for AAC). AAC-LC encodes through the platform's encoder, so a host without one refuses it. -- **Audio channel layouts.** A `channels` count also names the speaker layout, by the WAVE convention: 1 is mono, 2 stereo, 3 2.1, 4 quad, 5 5.0, 6 5.1, 7 6.1, and 8 7.1, interleaved front left, front right, center, LFE, back, then side. `moq_decode_audio` remixes to the count you ask for; past 8 channels the samples pass through but can't be remixed. -- **Raw decode output.** `moq_video_decoder_output` selects the decoded CPU pixel format (`MOQ_VIDEO_PIXEL_FORMAT_I420` or `_RGBA`) and target size (`width`/`height`, both zero for native; otherwise even and non-zero). Unknown formats and invalid sizes fail `moq_decode_video` before subscribing. -- **Decoded frames.** Each frame id owns its decoded picture until `moq_decode_video_frame_free`, including after `moq_decode_video_cancel` and the terminal callback. The first `moq_decode_video_frame` call converts it to the requested layout and size; its `data` pointer then stays put until the id is freed. A conversion failure returns a negative code for that frame only. Free frames promptly: held frames hold decoder buffers, and a decoder whose buffers are all held stalls. -- **Encoded video metadata.** `moq_video_init.hint` is a zero-initialized `moq_video_hint` with `has_*` flags for coded dimensions, bitrate (bits per second), frame rate, and latency preference. Hints seed a video codec track's catalog; detected dimensions take precedence. -- **Client config.** A zeroed `moq_client_config` means the defaults for every knob, which is what lets a new one be appended without disturbing callers. Fields cover protocol (`versions`), TLS (`tls_fingerprints`, `tls_roots`, `tls_cert`/`_key`, `tls_host_name`), transport (`bind`, `connect_timeout_us`, `failover_delay_us`/`resolution_delay_us` for Happy Eyeballs, `websocket_enabled`/`_delay_us`), and tuning (reconnect backoff, `quic_*`). Every duration is in microseconds. A knob whose default isn't zero carries a `has_*` flag, so setting `backoff_timeout_us = 0` needs `has_backoff_timeout = true` to mean "retry forever" rather than "use the default". `moq_client_defaults()` reports what a NULL config dials with. -- **Server.** `moq_server_listen` binds before it returns (a bad address or certificate fails there) and hands each incoming session to `on_request` as a request handle. Read `moq_session_request_path` and `_query` to route and authenticate, then `moq_session_request_accept` (a session handle, with origins like `moq_session_connect`) or `moq_session_request_reject` with an HTTP-style code (401 and 403 become the protocol's unauthorized close). An accepted session reports `1` once SETUP completes and never reconnects. `moq_server_addr` reports an ephemeral port and `moq_server_fingerprints` the hashes a client pins for a `tls_generate` certificate. `moq_server_close` stops listening; its terminal callback fires once the sockets are released. -- **Demand.** A watcher on a published track (`moq_publish_track_demand`, `moq_publish_media_demand`, `moq_encode_video_demand`, `moq_encode_audio_demand`) calls `on_demand` with `MOQ_DEMAND_USED` or `MOQ_DEMAND_UNUSED` right away and again on every change, so an encoder on a battery-powered device runs only while someone is watching. The first call is the current state, so a track that went unused before the watcher existed still reports it. `moq_publish_demand_cancel` stops it; the terminal callback still fires. A container has no single demand and is refused. Demand follows the last real subscriber: an origin that served the track drops its source copy on the unused edge, so a cache linger never delays it. Only a relay keeps what it already delivered warm for 30 seconds, and a returning subscriber is served that cache only once the publisher confirms it is still current. -- **Requests.** `moq_publish_dynamic` serves subscriptions to tracks the broadcast never declared: each arrives as a request handle, read its name with `moq_track_request_name`, then `moq_track_request_accept` (a raw track handle), `moq_track_request_video` / `_audio` (the media handle `moq_publish_video` / `_audio` return), or `moq_track_request_abort` with an application code the subscriber sees. Without a live handler an unknown name is refused. `moq_publish_track_dynamic` does the same for fetches of groups a track no longer has cached, delivered as `moq_group_request_*` (`sequence`, `priority`, `frame_start`); `moq_group_request_accept` starts the producer at `frame_start` so written frames keep their group indices. Register it with `moq_track_request_dynamic` before accepting a track that was itself requested by a fetch, so that pending group survives the transition. Both handlers stop with `moq_publish_dynamic_cancel`. -- **Everything the bindings can do** ([list](/lib/#what-every-binding-can-do)): media publish and consume with the catalog managed for you, raw pixels and PCM with the codec inside (`moq_encode_video`, `moq_encode_audio`, and the `moq_decode_*` mirrors), raw tracks with timestamps and datagrams, JSON and binary data tracks (snapshot or stream, each advertised in the catalog for as long as it lives), group fetch, catalog sections, shared video properties, and stalled hints. The three advertising operations are `moq_origin_create_broadcast` (unannounced producer, invisible to everyone), `moq_publish_announce` / `moq_publish_unannounce` (exact-path advertisement), `moq_publish_close` (ends the broadcast for good and releases its handle), and `moq_origin_dynamic` (a claim over a path prefix and everything beneath it; `""` for everything). A route is a capability, not an inventory. `moq_origin_announced` takes a `moq_announce_config` (NULL or zeroed for everything): a literal prefix and an optional relative pattern filter; each `moq_announce_event` has a `kind` (`MOQ_ANNOUNCE_KIND_START`, `_UPDATE`, or `_END`); `prefix` stays relative to the origin, while `captures` reports what each wildcard matched when `has_captures` is true. Paths with a `.`-prefixed segment below the prefix are [hidden](/concept/moq-lite#hidden-broadcasts); set `hidden` or name the dot segment in `prefix` to list them. +target, and `nix build .#moq-c` produces the release layout. A bare +`cargo build -p moq-c` leaves `moq.h` in a hashed `OUT_DIR` and writes no +pkg-config file. + +## Connect ```c moq_client_config config; @@ -67,31 +49,22 @@ if (session < 0) return fail(moq_error()); ``` -For a locally encoded media track, call `moq_publish_media_flush(media, timestamp_us)` after `moq_publish_media_frame` with the same broadcast-clock PTS. The monotonic handoff time is sampled inside moq-c. Do not call it for file, pipe, or network imports; those remain clock-free. Invalid handles and unrepresentable timestamps return a negative error code. - -Call `moq_publish_media_discontinuity(media)` when the source seeks, pauses, or changes its time base. It publishes a timeline marker and restarts handoff measurement without lowering advertised jitter. Resume with timestamps that continue forward on the broadcast media clock; this does not permit timestamp rewinds. On a video track, resume with a keyframe: a delta frame before it fails. - -## Connection stats +## Things to know -Every field in `moq_connection_stats` carries a matching `_valid` flag, -`false` when the transport backend does not report it (a `false` flag is not the -same as zero). Native QUIC reports every metric; the browser WebTransport -reports few or none. +The rest of the [shared feature list](/lib/#what-every-binding-can-do) is +here, from media publish and consume to raw pixels and PCM with the codec +inside. The header is the reference: each function carries a doc comment. -| Field | Unit | Meaning | -| --- | --- | --- | -| `rtt_us` | microseconds | Smoothed round-trip time. | -| `estimated_send_rate_bps` | bits per second | Send bandwidth from the congestion controller. | -| `estimated_recv_rate_bps` | bits per second | Receive bandwidth from MoQ PROBE. | -| `bytes_sent` | bytes | Total sent, including retransmissions and overhead. | -| `bytes_received` | bytes | Total received, including duplicates and overhead. | -| `bytes_lost` | bytes | Total lost, detected via retransmission or acknowledgement. | -| `packets_sent` | datagrams | Total datagrams sent. | -| `packets_received` | datagrams | Total datagrams received. | -| `packets_lost` | datagrams | Total datagrams detected as lost. | +- **Handles and callbacks.** Every object is an integer handle, and every async result arrives on a `moq_status_callback` with your `void *user_data`. A status `> 0` is a live result, `0` a clean close, and `< 0` an error. The last two are terminal: moq-c never touches `user_data` again, so free it there. `*_close` and `*_cancel` only request shutdown; the terminal callback still fires. +- **Errors.** Negative return codes are named by `MOQ_ERROR_*`, and `moq_error()` gives the reason on the calling thread. Auth rejections have their own codes so you don't retry them. For the peer's protocol code use `moq_error_protocol()`; do not parse `moq_error()`. +- **Threading.** Call any function from any thread. Raw publish calls block until the codec takes the frame, which paces a publisher. +- **Zeroed config is the default.** A zeroed `moq_client_config` means the default for every field, so new fields don't break callers. A field whose default isn't zero has a `has_*` flag: `backoff_timeout_us = 0` means "retry forever" only with `has_backoff_timeout = true`. +- **Audio needs cuts.** Video groups at its keyframes, but audio forms a group only where you call `moq_publish_media_cut`: after every frame, or at a segment cadence to align with video. +- **Live encoder timing.** After writing a frame you encoded yourself, call `moq_publish_media_flush` with the same timestamp so the catalog advertises your jitter. Skip it for file and network imports. On a seek or pause, call `moq_publish_media_discontinuity`, then keep timestamps moving forward and resume video on a keyframe. +- **Decoded frames hold decoder buffers.** Free each frame id with `moq_decode_video_frame_free` promptly, or the decoder stalls. +- **Stats.** `moq_session_stats()` fills `moq_connection_stats` with `rtt_us`, `estimated_send_rate_bps`, `estimated_recv_rate_bps`, and the byte and packet counters (`bytes_sent`, `bytes_received`, `bytes_lost`, `packets_sent`, `packets_received`, `packets_lost`). Each has a `_valid` flag, false when the transport does not report it, which is not the same as zero. -The header is the reference; each function carries a doc comment. Source and -a worked example: [`rs/moq-c`](https://github.com/moq-dev/moq/tree/main/rs/moq-c), -API docs on [docs.rs/moq-c](https://docs.rs/moq-c). +## Reference -Raw track publisher metadata has an optional maximum age. Omitting it imposes no publisher age limit; zero keeps the live edge. Local cache limits still apply, and media imports explicitly retain 30 seconds. See [publisher retention](/concept/moq-lite). +- API reference: [docs.rs/moq-c](https://docs.rs/moq-c) +- Source and a worked example: [`rs/moq-c`](https://github.com/moq-dev/moq/tree/main/rs/moq-c) diff --git a/doc/lib/dart/index.md b/doc/lib/dart/index.md index d78a6368844..7fbd4f90083 100644 --- a/doc/lib/dart/index.md +++ b/doc/lib/dart/index.md @@ -13,10 +13,6 @@ futures and streams. A Native Assets hook supplies the Rust core for Android (API 24+), iOS (16+), Linux, macOS, and Windows. Flutter web is not supported, since it can't load a native library. -Media frames use `keyframe` to mark a group start or a video keyframe. For audio, -it is true only on the first frame of each group, even when every sample can be -decoded independently. - ```bash dart pub add moq # or: flutter pub add moq ``` @@ -54,98 +50,20 @@ mine.close(); await moq.close(); ``` -```dart -// Serve. Server.listen binds the socket and streams the sessions that arrive. -final server = await Server.listen( - options: const ListenOptions( - bind: '127.0.0.1:4443', - tlsGenerate: ['localhost'], - ), -); -final live = server.createBroadcast('live/camera'); -live.announce(route: MoqRoute()); // unannounced broadcasts are invisible -await for (final request in server.requests()) { - final session = await request.accept(); - print(session.epoch()); -} -``` - -The three advertising operations: `moq.createBroadcast(path)` (or -`origin.createBroadcast`) returns an unannounced producer, invisible to everyone; -`broadcast.announce(route:)` / `broadcast.unannounce()` own that exact-path -advertisement, and `broadcast.close()` ends the broadcast for good (a second -call is a no-op); `origin.dynamic_(prefix:, route:)` claims `prefix` and -every path beneath it (`''` for everything; Dart spells the origin method -`dynamic_` because `dynamic` is reserved). Hold the returned handle while the -claim should stay advertised, and reject the requests you will not serve. A -route is a capability, not an inventory. `announcements(options:)` takes a -literal prefix plus an optional relative pattern and yields `AnnounceEvent`s: -`AnnounceEventStart`, `AnnounceEventUpdate`, or `AnnounceEventEnd` -carrying an `Announce`, whose `prefix` stays origin-relative and whose -`captures` reports the wildcard matches. Paths with -a `.`-prefixed segment below the prefix are [hidden](/concept/moq-lite#hidden-broadcasts) unless `hidden: true`. - -Sessions reconnect with backoff when the transport drops and re-announce local -broadcasts. `Moq.connect` and `Server.listen` take a `ConnectOptions` / -`ListenOptions` struct, like Rust: `reconnect: false` makes the dial one-shot -and `backoff:` re-paces the retries. `moq.epoch` counts the connections, 1 on the first, pairing with -`session.status()` to log each reconnect; `maxStreams` raises the peer's -inbound stream cap for a subscriber to many tracks. - -The [WebSocket fallback](/concept/transport#websocket-fallback) races QUIC after -a 200 ms head start. `websocketEnabled: false` turns it off for a QUIC-only -relay, and a `websocketDelay` `Duration` changes the head start. - -Types are spelled without the `Moq` prefix (`Session`, `BroadcastProducer`, -`Backoff`); the generated names stay valid, since these are aliases rather than -wrappers. `Container`, `Route`, and the exceptions keep theirs, because -`Container` and `Route` are Flutter's. Microsecond fields read back as a -`Duration`: `stats.rtt`, `backoff.initial`, `frame.timestamp`. +## Things to know -Cancelling a stream releases the native cursor. The package re-exports -`moq_ffi`, so the full generated API is available without a second import. -Generated configuration setters throw if a connect, listen, or accept is in -flight, or after `cancel()`. Incoming requests report a `MoqTransport` enum. -`ProtocolMoqException` carries a `MoqProtocolException` as `details` (scope, verbatim -code, kind) when the peer sent a session or stream code. An exception's -`toString()` is the Rust error message. +The rest of the [shared feature list](/lib/#what-every-binding-can-do) maps +one to one; the API reference has the names. -`moq.bandwidth()` divides the connection's send estimate; `reserve` a share -for an app-owned encoder so several publishers on one session split the -uplink instead of each targeting the whole thing. +- **No codecs.** Unlike the other bindings, the published Dart binaries carry no encoder or decoder. Already-encoded frames flow through `MediaProducer` and `MediaConsumer`; encoding is up to `package:camera`, platform channels, or another codec package. +- **Names.** Types drop the `Moq` prefix (`Session`, `BroadcastProducer`) as aliases, so the generated names still work. `Container`, `Route`, and the exceptions keep it, since Flutter owns those names. `dynamic` is reserved, so the origin method is `dynamic_`. +- **Audio needs cuts.** Video groups at its keyframes, but audio forms a group only where you call `cut()`: after every frame, or at a segment cadence to align with video. +- **Live encoder timing.** After writing a frame you encoded yourself, call `flush(timestampUs: ...)` with the same timestamp so the catalog advertises your jitter. Skip it for file and network imports. On a seek or pause, call `discontinuity()`, then keep timestamps moving forward and resume video on a keyframe. +- **Closing.** `await moq.close()` or `session.shutdown()` gives finished tracks up to one second to deliver and fails if they did not. `session.cancel(code: 0)` closes at once. Finish or abort live tracks first. Cancelling a stream subscription releases its native cursor. +- **Stats.** `session.stats()` reports `rttUs`, `estimatedSendRateBps`, `estimatedRecvRateBps`, and the byte and packet counters (`bytesSent`, `bytesReceived`, `bytesLost`, `packetsSent`, `packetsReceived`, `packetsLost`). A field is `null` when the transport does not report it, which is not the same as zero. -Unlike the other bindings, the published Dart binaries carry **no codecs**: -catalog and container types are there, so already-encoded frames flow through -`MoqMediaProducer`/`MoqMediaConsumer`, but encoding is up to -`package:camera`, platform channels, or another codec package. - -`MediaProducer.flush(timestampUs: ...)` records the handoff of a locally encoded frame on the broadcast media clock. Call it after `writeFrame` only for live encoder output; file, pipe, and network imports stay clock-free. `MediaProducer` aliases the generated FFI object, so its method is available directly. - -Call `media.discontinuity()` when the source seeks, pauses, or changes its time base. It publishes a timeline marker and restarts handoff measurement without lowering advertised jitter. Resume with timestamps that continue forward on the broadcast media clock; this does not permit timestamp rewinds. On a video track, resume with a keyframe: a delta frame before it fails. - -## Connection stats - -`session.stats()` returns a `ConnectionStats` snapshot. Each field is `null` -when the transport backend does not report it (native QUIC reports all of them; -browser WebTransport reports few or none) or before it is available, which is -not the same as zero. `rttUs` is microseconds; the `rtt` extension reads it as a -`Duration`. - -| Field | Unit | Meaning | -| --- | --- | --- | -| `rttUs` | microseconds | Smoothed round-trip time. | -| `estimatedSendRateBps` | bits per second | Send bandwidth from the congestion controller. | -| `estimatedRecvRateBps` | bits per second | Receive bandwidth from MoQ PROBE. | -| `bytesSent` | bytes | Total sent, including retransmissions and overhead. | -| `bytesReceived` | bytes | Total received, including duplicates and overhead. | -| `bytesLost` | bytes | Total lost, detected via retransmission or acknowledgement. | -| `packetsSent` | datagrams | Total datagrams sent. | -| `packetsReceived` | datagrams | Total datagrams received. | -| `packetsLost` | datagrams | Total datagrams detected as lost. | +## Reference +- API reference: [pub.dev/documentation/moq](https://pub.dev/documentation/moq/latest/) - Source: [`dart/`](https://github.com/moq-dev/moq/tree/main/dart) - Packages: [moq](https://pub.dev/packages/moq), [moq\_ffi](https://pub.dev/packages/moq_ffi) - -Raw track publisher metadata has an optional maximum age. Omitting it imposes no publisher age limit; zero keeps the live edge. Local cache limits still apply, and media imports explicitly retain 30 seconds. See [publisher retention](/concept/moq-lite). - -Await `session.shutdown()` or `moq.close()` to drain finished tracks before disconnecting. These futures fail if delivery has not completed within one second. `session.cancel(code: 0)` remains immediate. Finish or abort live tracks before shutdown. IETF media streams are not drained yet. diff --git a/doc/lib/go/index.md b/doc/lib/go/index.md index 72ed046adea..32de9ae2bf9 100644 --- a/doc/lib/go/index.md +++ b/doc/lib/go/index.md @@ -63,6 +63,7 @@ for event, err := range announced.All(ctx) { broadcast, _ := client.CreateBroadcast("my-stream.hang") audio, _ := broadcast.PublishAudio(moq.AudioFormatOpus, opusInit) _ = audio.WriteFrame(moq.Frame{Payload: packet, TimestampUs: 20_000}) +_ = audio.Cut() // audio has no keyframes, so this is what gives it groups track := "camera" video, _ := broadcast.EncodeVideo( @@ -77,108 +78,21 @@ _ = video.Finish() broadcast.Close() // keep the producer reachable while publishing, then close explicitly ``` -For locally encoded media, call `MediaProducer.Flush(timestampUs)` after `WriteFrame` with the same broadcast-clock PTS. It measures catalog jitter at the transport handoff. File, pipe, and network imports should omit `Flush`; built-in encoders observe their own output. +## Things to know -Call `media.Discontinuity()` when the source seeks, pauses, or changes its time base. It publishes a timeline marker and restarts handoff measurement without lowering advertised jitter. Resume with timestamps that continue forward on the broadcast media clock; this does not permit timestamp rewinds. On a video track, resume with a keyframe: a delta frame before it fails. +The rest of the [shared feature list](/lib/#what-every-binding-can-do) maps +one to one; the API reference has the names. -The three advertising operations: `client.CreateBroadcast(path)` (or -`origin.CreateBroadcast`) returns an unannounced producer, invisible to everyone; -`broadcast.Announce(route)` / `broadcast.Unannounce()` own that exact-path -advertisement, and `broadcast.Close()` ends the broadcast for good (a second -call is a no-op); `origin.Dynamic(prefix, route)` claims `prefix` and every -path beneath it (`""` for everything). Hold the returned `OriginDynamic` -while the claim should stay advertised, and reject the requests you will not -serve. A route is a capability, not an inventory. `Announced(options)` combines -a literal prefix with an optional relative pattern and yields an `AnnounceEvent`: -`AnnounceEventStart`, `AnnounceEventUpdate`, or `AnnounceEventEnd` -carrying an `Announce`, whose `Prefix` stays relative to the origin and whose -`Captures` reports the wildcard matches. -Paths with a `.`-prefixed segment below the prefix are [hidden](/concept/moq-lite#hidden-broadcasts) unless -`Hidden: true`. +- **Context cancellation.** Every call that can block takes a `context.Context` first, and cancelling it tears down the native work, not just your wait. A one-shot call (`RequestBroadcast`, `FetchGroup`, `Server.Accept`) aborts alone; a stream read (`Next`, `ReadFrame`, and the iterators over them) cancels the stream it reads. +- **Keep owners reachable.** An origin from `moq.NewOriginProducer` has no `Close`. It ends when the garbage collector reaches its last owner (each producer, published broadcast, and `OriginDynamic`), and its consumers then fail with `moq.ErrClosed`. +- **Audio needs cuts.** Video groups at its keyframes, but audio forms a group only where you call `Cut()`: after every frame, or at a segment cadence to align with video. +- **Live encoder timing.** After writing a frame you encoded yourself, call `Flush(timestampUs)` with the same timestamp so the catalog advertises your jitter. Skip it for file and network imports. On a seek or pause, call `Discontinuity()`, then keep timestamps moving forward and resume video on a keyframe. +- **Decoded frames hold decoder buffers.** `Close` each `VideoDecodedFrame` promptly, or the decoder stalls. `Resize` is best effort, so read each frame's `Width()` and `Height()`. +- **Closing.** `client.Close()` gives finished tracks up to one second to deliver and returns an error if they did not. `session.Shutdown(ctx)` does the same, and `session.Cancel(code)` closes at once. Finish or abort live tracks first. +- **Stats.** `Session().Stats()` reports `RttUs`, `EstimatedSendRateBps`, `EstimatedRecvRateBps`, and the byte and packet counters (`BytesSent`, `BytesReceived`, `BytesLost`, `PacketsSent`, `PacketsReceived`, `PacketsLost`). A field is nil when the transport does not report it, which is not the same as zero. -An `OriginProducer` from `moq.NewOriginProducer` has no `Close`: its origin -ends when the garbage collector reaches the last owner (each producer, published -broadcast, and `OriginDynamic`), and every consumer made from it then fails with -`moq.ErrClosed`. Keep an owner reachable (a field on a long-lived struct, or -`runtime.KeepAlive`) for as long as the origin should serve. - -Every call that can block takes a `context.Context` first. Cancelling it -returns `ctx.Err()` promptly and tears the in-flight native work down, so a -per-call deadline bounds resource use rather than just your wait. What it tears -down depends on the call: a one-shot (`SubscribeTrack`, `FetchGroup`, -`RequestBroadcast`, `Server.Accept`, ...) aborts alone and leaves its object -usable, while a stream read (`Next`, `RecvGroup`, `ReadFrame`, and the -`iter.Seq2` iterators over them) cancels the stream it reads, which is what a -range loop over a cancelled context wants. - -Sessions reconnect with backoff when the transport drops and re-announce local -broadcasts, so a worker rides out a relay restart. `Session().Epoch()` counts -the connections, 1 on the first, pairing with `Session().Status(ctx)` to log -each reconnect by number; `moq.WithBackoff` tunes the pacing, with -`moq.RetryForever` as the timeout; and `moq.WithQUICMaxStreams` raises the -peer's inbound stream cap for a subscriber to many tracks. - -The [WebSocket fallback](/concept/transport#websocket-fallback) races QUIC after -a 200 ms head start. `moq.WithWebSocketEnabled(false)` turns it off for a -QUIC-only relay, and `moq.WithWebSocketDelay` changes the head start. - -`moq.Listen` accepts sessions with per-request `Accept`/`Reject`; `Request.Transport()` -returns the closed `moq.Transport` enum. -`Request.SetPublish`/`SetConsume` return an error if the request is already -answered, cancelled, or currently accepting; `ErrBusy` is the race with an -in-flight Accept. JSON tracks -take anything `encoding/json` handles and return `json.RawMessage`. The rest -of the [shared feature list](/lib/#what-every-binding-can-do) maps one to -one: `FetchGroup`/`FetchMediaGroup`, `Dynamic()` with `Requests(ctx)`, -`Session.Bandwidth()` to divide the send estimate, -`AppendDatagram`/`Datagrams(ctx)`, `SetCatalogSection`, `Demand()` for `Used`/`Unused`, -`Session().Stats()`. `moq.IsAuthError` and `moq.IsShutdown` classify errors. `moq.ProtocolError(err)` is the structured protocol failure (scope, verbatim code, kind) when the peer sent one. `err.Error()` is the Rust error message. - -`EncodeAudio` encodes raw PCM inside the binding. Its codec is `OpusAudioCodec()` -or `AacAudioCodec()`, and `AudioEncoderOutput.FrameDurationUs` sets the Opus -frame length: 2500, 5000, 10000, 20000 (the default), 40000, or 60000. 0 takes -the codec's own frame, which AAC needs. AAC-LC encodes through the platform's -encoder, so a host without one refuses it. - -Audio `Channels` also names the speaker layout, by the WAVE convention: 1 is -mono, 2 stereo, 3 2.1, 4 quad, 5 5.0, 6 5.1, 7 6.1, and 8 7.1, interleaved -front left, front right, center, LFE, back, then side. Decoding remixes to the -count you ask for; past 8 channels the samples pass through but can't be -remixed. - -Each `VideoDecodedFrame` from `DecodeVideo` owns its decoded picture until -`Close`, including after the consumer is cancelled. `Pixels(format)` converts it -on demand: `VideoPixelFormatI420`, or `VideoPixelFormatRgba` for four bytes a -pixel. Close frames promptly, since held frames hold decoder buffers. `Resize` -is best effort: only NVDEC has a built-in scaler, so read each frame's own -`Width()` and `Height()` rather than assuming it took. `VideoDecoderOutput{Surface: true}` -keeps the decoder's surface for `frame.Surface()` instead of downloading it: a -`VideoSurfacePixelBuffer` whose `Pointer` is the `CVPixelBufferRef`, valid until -`Close`. Only macOS has one, so `DecodeVideo` fails with `ErrUnsupported` elsewhere. - -## Connection stats - -`Session().Stats()` returns a `ConnectionStats` snapshot. Each field is a -pointer, nil when the transport backend does not report it (native QUIC reports -all of them; browser WebTransport reports few or none) or before it is -available, which is not the same as zero. - -| Field | Unit | Meaning | -| --- | --- | --- | -| `RttUs` | microseconds | Smoothed round-trip time. | -| `EstimatedSendRateBps` | bits per second | Send bandwidth from the congestion controller. | -| `EstimatedRecvRateBps` | bits per second | Receive bandwidth from MoQ PROBE. | -| `BytesSent` | bytes | Total sent, including retransmissions and overhead. | -| `BytesReceived` | bytes | Total received, including duplicates and overhead. | -| `BytesLost` | bytes | Total lost, detected via retransmission or acknowledgement. | -| `PacketsSent` | datagrams | Total datagrams sent. | -| `PacketsReceived` | datagrams | Total datagrams received. | -| `PacketsLost` | datagrams | Total datagrams detected as lost. | +## Reference - API reference: [pkg.go.dev/moq.dev/moq](https://pkg.go.dev/moq.dev/moq) - Source: [`go/`](https://github.com/moq-dev/moq/tree/main/go); `just go check` builds and tests locally - Mirrors the vanity path resolves to: [moq-dev/moq-go](https://github.com/moq-dev/moq-go) (wrapper), [moq-dev/moq-go-ffi](https://github.com/moq-dev/moq-go-ffi) (raw bindings and static libraries) - -Raw track publisher metadata has an optional maximum age. Omitting it imposes no publisher age limit; zero keeps the live edge. Local cache limits still apply, and media imports explicitly retain 30 seconds. See [publisher retention](/concept/moq-lite). - -`session.Shutdown(ctx)` drains finished tracks and returns a delivery error if the one-second deadline expires. Cancelling the context aborts immediately. `client.Close()` waits for shutdown and returns the same error; `session.Cancel(code)` remains immediate. Finish or abort live tracks before shutdown. IETF media streams are not drained yet. diff --git a/doc/lib/index.md b/doc/lib/index.md index 718627a6467..1139445aa22 100644 --- a/doc/lib/index.md +++ b/doc/lib/index.md @@ -33,18 +33,16 @@ wrapped in an idiomatic layer, while C gets a hand-written stable ABI The wrapped bindings share one feature set, so the language pages only show how it looks in that language: -- **Connect** to a relay with TLS options (system roots, custom CA, fingerprint pinning, mTLS) and a JWT in the URL, or **serve** sessions yourself and accept or reject each request by path. -- **Reconnect** automatically with backoff when the transport drops, with `status`/`epoch` reporting each (re)connect and backoff tunable down to retrying forever. The peer's inbound QUIC stream limit is configurable for subscribe-heavy clients. -- **Discover** broadcasts by prefix, wait for a specific one, or request one by path, including a path a prefix claim serves on demand. Advertise an exact path with `create_broadcast` then `announce` / `unannounce` (a broadcast is invisible to local consumers and peers alike until announced), or claim a path prefix with `dynamic(prefix, route)`. -- **Publish and subscribe to media** with the hang catalog filled in from the bitstream, plus raw pixels or PCM in and out with the codec running inside the binding (VideoToolbox, Media Foundation, NVENC, openh264, Opus). A publisher follows the connection's send estimate through `session.bandwidth()`: reserve a share for an app-owned encoder, or pass the handle when encoding so the built-in video encoder follows the grant. -- **Connection health.** `stats()` snapshots RTT, send/receive estimates, and byte/packet counters. `bandwidth()` divides that send estimate among tracks sharing the connection. -- **Raw tracks** of arbitrary bytes with timestamps, sparse or replayed groups, per-subscriber priority and max delay, and best-effort datagrams. -- **JSON tracks** in snapshot mode (latest value, merge-patch deltas, optional compression) or stream mode (append log). -- **Fetch** a single group by sequence from the cache, decoded through the container or raw. -- **Serve on demand**: accept track and broadcast requests as they arrive instead of publishing up front. +- **Connect** to a relay with TLS options and a JWT in the URL, or **serve** sessions yourself and accept or reject each request by path. +- **Reconnect** automatically with backoff when the transport drops. +- **Discover** broadcasts by prefix, wait for a specific one, or request one by path. Advertise an exact path (a created broadcast is invisible until announced), or claim a prefix and serve requests beneath it on demand. +- **Publish and subscribe to media** with the hang catalog filled in from the bitstream, or hand over raw pixels and PCM and let the binding encode and decode (VideoToolbox, Media Foundation, NVENC, openh264, Opus). The built-in video encoder can follow the connection's send estimate. +- **Raw tracks** of arbitrary bytes, with per-subscriber priority and max delay, and best-effort datagrams. +- **JSON tracks** as a latest value with merge-patch deltas, or as an append log. +- **Fetch** a single cached group by sequence. - **Catalog extensions**: write your own section next to `video` and `audio`, and read others' back. -- **Routes**: see which relays a broadcast came through, and advertise a cost as a standby publisher: warm `cost` for what pulling costs today, undiscounted `cold` for what it costs with nothing cached (omit `cold` to price both alike). -- **Errors** distinguish auth rejection (don't retry) from shutdown (expected) from transport failure. A protocol error carries the peer's session or stream code, a known kind when recognized, and keeps an application or unknown code without loss. +- **Routes**: see which relays a broadcast came through, and advertise a cost as a standby publisher. +- **Connection stats** and **errors** that tell an auth rejection (don't retry) from a shutdown or a transport failure. Dart is the exception on codecs: its published binaries carry no encoder or decoder, so it moves already-encoded frames. diff --git a/doc/lib/js/auth.md b/doc/lib/js/auth.md index 44233d198b6..df57295ec3c 100644 --- a/doc/lib/js/auth.md +++ b/doc/lib/js/auth.md @@ -10,17 +10,16 @@ description: Answer a relay and mint its JWTs in TypeScript The TypeScript twin of [`moq-auth`](/lib/rs/moq-auth). `RequestSchema` and `GrantSchema` validate what [moq-relay](/bin/relay/auth) POSTs per session and what an auth server answers, so a Worker or a Node server implements the -contract with one import. Generate keys (HMAC, RSA, ECDSA, EdDSA, individually -or as a JWK set), `Key.sign` and `Key.verify` strict claims, `Key.decode` an unvalidated signed payload, and `authorize` a connection path -against the claims exactly as `moq auth serve` does. Tokens are interchangeable with -the Rust side. Grants and claims are +contract with one import. It also generates keys, signs and verifies JWTs, and +checks a connection path against a token's claims exactly as `moq auth serve` +does. Tokens are interchangeable with the Rust side. Grants and claims are [`Pattern`](https://www.npmjs.com/package/@moq/pattern) unions: `foo` is one broadcast, `foo/**` is a subtree, `**` is everything. ```bash bun add @moq/auth -bun run @moq/auth generate --out root.jwk -bun run @moq/auth sign --key root.jwk --root "rooms/123" --publish 'alice/**' +bunx @moq/auth generate --out root.jwk +bunx @moq/auth sign --key root.jwk --root "rooms/123" --publish 'alice/**' ``` Mint tokens on a server, never in the browser, and prefer asymmetric keys so diff --git a/doc/lib/js/hang.md b/doc/lib/js/hang.md index 57b9e8e79af..6412f1032b9 100644 --- a/doc/lib/js/hang.md +++ b/doc/lib/js/hang.md @@ -10,33 +10,25 @@ description: The media layer in TypeScript The [hang media format](/concept/hang) as TypeScript types and codecs, shared by [`@moq/watch`](/lib/js/watch) and [`@moq/publish`](/lib/js/publish). -- **Catalog**: zod schemas for the root, video, audio and text renditions, the JSON and binary data track sections, containers, and the `archive` entry (timeline track plus optional replay, store, and version). The root is a loose object, so `z.extend(Catalog.RootSchema, { yourSection })` adds your own. -- **Containers**: `Container.Legacy` producer/consumer and `Container.Cmaf` init and data segment helpers. Group starts may match or increase, and frames may overlap the previous group's content, but cannot precede its start. An estimated end marker is metadata, not a timestamp floor. A backwards group start requires a new broadcast. -- **Utilities**: hex, priority and latency math, an Opus polyfill for browsers without a native decoder, and the browser quirks the media packages work around. +- **Catalog**: zod schemas for the root, renditions, data tracks, and `archive`. The root is a loose object, so `z.extend(Catalog.RootSchema, { yourSection })` adds your own. `Catalog.watch(broadcast)` iterates validated catalog updates. +- **Containers**: `Container.Legacy` producer/consumer and `Container.Cmaf` init and data segment helpers. +- **Utilities**: priority and latency math, an Opus polyfill for browsers without a native decoder, and the browser quirks the media packages work around. ```ts import * as Catalog from "@moq/hang/catalog"; import * as Container from "@moq/hang/container"; ``` -`Catalog.watch(broadcast)` iterates validated catalog roots. It throws -`Catalog.TooManyRenditions` for an update above the 64 rendition limit, and -`Catalog.EscapingBroadcast` for a `broadcast` reference that walks above the -handle's `path`. Run the same checks on a catalog from another source with -`Catalog.checkRenditions(root)` and `Catalog.checkResolvable(root, base)`. -`Hang.Timeline.Consumer.subscribe(broadcast, root.archive, track)` reads one -track's timeline as record `push`, `pop`, and `skip` events when a root advertises it. - Most apps never import it directly; the elements and `Broadcast` classes in the watch and publish packages do. Reach for it when hand-rolling a catalog or building a custom player. ## Wall clock -A catalog root may carry a `clock`: `{ wall, timescale }`, the wall-clock time -of PTS zero in `timescale` units (microseconds by default) since 2020-01-01. -`Catalog.wallClockTime(clock, pts, ptsTimescale)` maps a frame's PTS to a -`Date`. A `Container.Legacy` frame timestamp is microseconds, so pass `1_000_000`. +A catalog root may carry a `clock` that maps PTS zero to wall time. +`Catalog.wallClockTime(clock, pts, ptsTimescale)` turns a frame's timestamp +into a `Date`. A `Container.Legacy` timestamp is microseconds, so pass +`1_000_000`. ```ts for await (const root of Catalog.watch(broadcast)) { @@ -46,29 +38,8 @@ for await (const root of Catalog.watch(broadcast)) { } ``` -- The mapping is fixed for the life of the broadcast. A discontinuity or a - system-clock adjustment on the publisher does not change it. -- It is independent of `archive`. A live-only broadcast carries a `clock` with - no segment index, so a DVR view can label its timeline from it either way. -- A `Date` holds whole milliseconds, so anything finer in the clock is - truncated. -- A result past the `Date` range comes back as an invalid `Date`, not an - exception, so check it before use. - -Two machines' wall times are only comparable when your application already -knows their clocks are synchronized. The catalog says where PTS zero was on the -publisher's clock, never whether the viewer's clock agrees with it. If you do -know, set `delay` to `target - (arrived - captured)`, where `arrived` is the -viewer's `Date.now()` for the frame that arrived earliest relative to its -timestamp, since `` anchors playback on that frame. That holds only -with the default zero `buffer`; a lookahead moves the anchor. `` adds -the largest active rendition's buffer on top, so a frame renders at about -`captured + target` plus that buffer: the rendition's catalog `delay` plus its -`jitter` (one video frame or one codec frame when unset), and for audio the -worklet quantum too. Viewers only line up when that buffer matches, and a -negative result means the target is already missed. - -The library never does this for you. Playback stays arrival-based: it does not -read the `clock`, estimate the viewer's clock from the session RTT, or -exchange time over a track, and a timestamp stays relative to the broadcast -rather than a reading of any wall clock. +The mapping is fixed for the life of the broadcast and does not need an +`archive`. It says where PTS zero was on the publisher's clock, never whether +the viewer's clock agrees. Playback never reads it: `` stays +arrival-based, so lining viewers up on wall time is the application's job and +needs clocks it already knows are synchronized. diff --git a/doc/lib/js/publish.md b/doc/lib/js/publish.md index 8b496b9cea3..e05ec27a3f1 100644 --- a/doc/lib/js/publish.md +++ b/doc/lib/js/publish.md @@ -31,74 +31,36 @@ WebCodecs, writes the catalog, and publishes a hang broadcast. | `source` | `camera`, `screen`, or `file`. | | `muted`, `invisible` | Disable audio or video capture. | | `preview` | What the nested element shows: the raw `source` (default), a decoded copy of the `encoded` stream to see what viewers get, or `none`. | -| `announce` | When to advertise: once a `source` is live (default), `always`, or `never`. A camera source waits for every enabled track, and `source` waits until each captured track's config resolves or fails, so the first catalog lists every rendition. The broadcast is created while connected either way, but nobody can see or subscribe to it until it is announced. | +| `announce` | When to advertise: once the `source` is live (default), `always`, or `never`. Nobody can see or subscribe to the broadcast until it is announced. | +Every attribute is also a reactive property. The +[README](https://www.npmjs.com/package/@moq/publish) lists types and defaults. A nested `