diff --git a/AGENTS.md b/AGENTS.md index 1f5f6ed8369..f275e74c683 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-stats` wire (track names, frame shapes) | `doc/bin/relay/config.md` (stats section) | +| `rs/moq-auth` | `js/auth`, `doc/bin/relay/auth.md` | +| `rs/moq-stats` wire (track names, frame shapes) | `doc/concept/stats.md` | | `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/.vitepress/config.ts b/doc/.vitepress/config.ts index 14559dc31d6..05ed444d6ee 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 1bf1a9b230b..e6af71843ba 100644 --- a/doc/bin/cli.md +++ b/doc/bin/cli.md @@ -44,12 +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; without a listener, -the `--listen-*` and `--auth-*` flags are refused. 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) @@ -63,118 +61,28 @@ 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` 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. - -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. - -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 starts a new clock after a declared marker, and the first new -clock packet signals the break. Each track goes out on the old clock until it -reaches the marker, then joins the new one, unless an old-clock frame would go -out after the new clock's first, which is dropped. Once the export has measured -each track's lead over the others (two seconds of media), the new clock keeps -it, so a track the source sends later than the rest crosses without losing -frames. 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. -An Opus track is labeled with the plain channel code its extension descriptor -can name: a family 0 head, a family 1 head with the Vorbis mapping, or mono or -stereo when the track has no OpusHead. Any other head is refused rather than -written with a guessed channel code. - -An AAC layout without a channelConfiguration, such as quad, rides in a program -config element. `export ts` repeats it in the first frame after each PAT/PMT, so a -receiver tuning in mid-stream can decode. ffmpeg writes it in the first frame -only, so `import ts` joining an ffmpeg source mid-stream publishes the rest of -the program without that AAC track, and adds the track if an element arrives. - -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 on a constant-rate -schedule, so an IRD or groomer recovering its clock from packet arrival can lock: -every PCR is the time of its own byte position at the rate. `--mux-rate 5000000` -pads to an explicit rate instead, including for a broadcast that recorded none. - -Each frame goes out as early as a receiver's buffers for its PID admit (the -ISO 13818-1 T-STD: no more of a PID's packets per interval than its transport -buffer passes on, and no more bytes than its decoder buffer holds, sized from the -SPS's HRD or level for video and per codec for audio), up to `--delay` ahead of its -decode time on the output's PCR clock, earliest decode time first. So a heavy passage rides the intervals -before it, and the output trails the source by twice the delay. A frame that cannot -arrive by its decode time at the rate fails the export with an error naming both -knobs; a broadcast-sized decoder buffer (a CPB of a second or more) needs a delay to -match. A VBR source records no rate, so export without one 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 +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 and refuse these flags. ```bash @@ -182,25 +90,16 @@ 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`, on a constant-rate schedule an IRD or groomer +can lock to. Each frame goes out as early as the receiver's buffers admit, up +to `--delay` ahead of its decode time on the output's clock, so the output trails the source by twice +the delay; a frame that cannot arrive in time at the rate fails the export. ## Play @@ -210,49 +109,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. - -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 -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" @@ -267,25 +135,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 @@ -296,27 +156,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 @@ -327,21 +172,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 @@ -350,19 +183,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 `--epoch` 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 @@ -375,34 +200,20 @@ 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, one that returns after the catalog dropped it, and an -untimed track, which has no timestamps to record (any track over moq-lite before -05, or moq-transport without `TIMESCALE`, such as drafts 14–16). 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. A source -announced under another [epoch](/concept/moq-lite#publisher-epochs) than the recording -restarted, so the export fails; start a new prefix. A source without an epoch fails the -same way once its timestamps jump back before the 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, unless the source now announces another +[epoch](/concept/moq-lite#publisher-epochs): that is a restart, so the export +fails; record it under a new prefix. `--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 @@ -416,62 +227,42 @@ moq --connect https://relay.example.com/anon \ -- export --broadcast event.hang archive file:///recordings/event ``` -## Redundant publishers - -Each run announces a fresh epoch, so a restarted publisher replaces the old -broadcast instead of resuming into it. Two publishers that pass the same -`--epoch` (a lowercase, hyphenated UUIDv7, such as util-linux `uuidgen -7` -prints) are interchangeable sources: relays hold both routes and fail over -between them mid-group. They must produce identical tracks with aligned groups, -which no importer guarantees yet (see -[#4352](https://github.com/moq-dev/moq/issues/4352) and -[#4354](https://github.com/moq-dev/moq/issues/4354)). A member restarted with -the same epoch rejoins as the same content, so if its groups restart from 0, -viewers wait for its sequence to catch up. +## Publisher runs -```bash -EPOCH=$(uuidgen -7) -# On each of the two hosts: -moq --connect https://relay.example.com/anon --broadcast event.hang --epoch "$EPOCH" import ts < feed.ts -``` +Each run of `moq` announces a fresh +[publisher epoch](/concept/moq-lite#publisher-epochs), kept across reconnects. +The RTMP, SRT, and WHIP ingests mint one per connection instead, and +`import ts --program all` one per program. -`--epoch` applies to the sources announced once per run. The RTMP, SRT, and -WHIP ingests and `import ts --program all` announce their own, so they refuse it. +Epochs cross a connection only on moq-lite 07, which is opt-in. There, a +restarted process takes the name at once, as long as its host's clock is not +behind the old run's: subscriptions to the old run end with +`Unroutable`, and a viewer's next subscribe reaches the new run instead of +waiting for its group numbers to catch up. On older versions and moq-transport +the relay sees no epoch and keeps a subscription on the route it first resolved +through, so viewers of a restarted process wait until the old session closes. -`--epoch` replaces the removed `--hop`. `MOQ_HOP` is no longer read, so drop it -from any deployment and pass `MOQ_EPOCH` instead. +On moq-lite 07, two processes that pass the same `--epoch` (a UUIDv7, such as +`uuidgen -7` prints) are one publisher: relays fail over between them +mid-group, so they must produce identical tracks with aligned groups, which no +importer guarantees yet. The ingests that mint their own refuse `--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 @@ -479,75 +270,35 @@ 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` takes `--delay` (default 500 ms) instead, and works like an SRT -receiver's latency. Every frame is released to the multiplexer that long after -its decode time, on a clock that keeps the source's pace and muxes all tracks in decode order -whatever their arrival skew: two exporters of one broadcast emit them in one -order. The export joins at the newest group and holds its output until it -has heard from every audio, video, DVB AC-3 and teletext track (two delays at most) and a -track starts its next group, or one of the frames it holds falls due. It then -starts the clock on the track the source sends latest against its decode time, -from that track's freshest frame: a broadcast TS sends video most of a second -ahead and audio just in time, and the audio must keep the delay too. What of -the joined group is older than the delay is dropped, so a joiner runs at the -delay from its first output. A frame that arrives later than its deadline is -dropped, and video then resumes at its next keyframe. The clock follows the -source's, measured from the frames that arrive least delayed on the track sent -latest, so a source whose clock runs a -little fast or slow neither goes late nor piles up over a long run, and a -spell of network queueing does not move it. The output's PCR is that clock, -so it keeps to what ISO/IEC 13818-1 allows a system clock: within 30 ppm of -the exporter's, its rate changing by at most 0.075 Hz/s. Catching up with a -source near that limit takes hours; one further off is counted in the -export's stats, and fails the export once it has used half the delay. Each -25 ms slice of the output is written when the clock reaches it. A stalled group -is skipped once it falls half the delay behind, leaving the group after it the -other half. `--delay 0` holds nothing and drops -nothing, writing frames in arrival order as they come. +`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` takes `--delay` (default 500 ms) instead, like an SRT receiver's +latency: each frame is muxed that long after its decode time, all tracks in +decode order, so two exporters of one broadcast emit the same order. A frame +arriving after its deadline is dropped, and video resumes at its next +keyframe. The output's PCR follows the source's clock within what ISO/IEC +13818-1 allows. `--delay 0` writes frames in arrival order and drops nothing. 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/gstreamer.md b/doc/bin/gstreamer.md index 7dc75236aa5..02bf4803d7d 100644 --- a/doc/bin/gstreamer.md +++ b/doc/bin/gstreamer.md @@ -64,26 +64,20 @@ 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 (opt-in) +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 -`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/bin/hls.md b/doc/bin/hls.md index 81739d3ad2d..502c2a8e0c8 100644 --- a/doc/bin/hls.md +++ b/doc/bin/hls.md @@ -1,129 +1,53 @@ --- 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. A video choice sticks while the rendition stays in the catalog, so -a newer rendition that sorts earlier does not rewind `EXT-X-MEDIA-SEQUENCE`; an -audio choice switches to video once a video rendition has a timeline. 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 that chose it derives the same URL. A reference that leaves -the catalog 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 playlist length, default 16 s) within that retention. +- **Joining costs the window, not the broadcast's age.** The exporter reads only what the timeline restates on join, and the window lists at most 256 segments. +- **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. A recording's playlists -list the same capped window as a live broadcast. A library embedder can set -`export::Config::history` to list past it instead: when the catalog's `archive` -entry names a `store` and no `replay` path, its spans are durable on this -broadcast, so only the recording's own retention trims the playlists and DASH -`timeShiftBufferDepth` is the listed span. The listing starts at the records -the timeline restates when the exporter joins (at most 256 from a `moq-mux` -publisher). The playlist ends with `EXT-X-ENDLIST` only once the reader's caller -declares the recording finished; the store holds no completion marker. - -A viewer joining a days-old broadcast costs what the window lists, not the -broadcast's age: the exporter reads only the records its timeline restates on -join, never the whole history. The window lists at most 256 -segments however short they are, so every edge shows the same -`EXT-X-MEDIA-SEQUENCE`. Below that cap the window never evicts its newest -segment that starts on a video sync point, so a GOP longer than `--window` -stretches the window to that one GOP rather than leave nothing a player can -start at. A rendition with no media for a span lists that span as -a duration-preserving `EXT-X-GAP` and goes on listing after it. The master -playlist advertises a video rendition only once a listed segment starts at a -group start that is a sync point, so an early master may list audio alone, and -answers 404 while no rendition can start. Once advertised, a rendition stays in -the master for the rest of the publisher run, even if a GOP longer than 256 -records evicts its sync segment. +`Reader` is served the same way, with no second stored copy, and lists the +same window as a live broadcast. -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 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..3f6f26111c2 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, encoding that uses the OBS Output settings or custom settings for this stream only, 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 17df3535cbc..1c60ff2b669 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,42 +169,35 @@ 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 '**' --mtls-peer` (or a server granting its cluster CA everything with `peer: true`); see [Clustering](/bin/relay/cluster). `--mtls-peer` marks every certificate as -another relay, whose broadcasts entered the cluster elsewhere; leave it off -when certificates identify clients. `--mtls-upstream` also marks those relays -[upstream](/bin/relay/cluster#upstream-links) and needs `--mtls-peer`. -Adding or removing either flag on a running server ends each live mTLS session -at its next re-check, from the `--revalidate` cadence or a -[push](#the-contract) such as `moq auth revalidate`, so the mesh redials once; -until then, a session keeps its old marks. -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. +another relay; leave it off when certificates identify clients. +`--mtls-upstream`, which needs `--mtls-peer`, also marks them +[upstream](/bin/relay/cluster#upstream-links). Changing either flag ends each +live mTLS session at its next re-check (the `--revalidate` cadence or a +`moq auth revalidate` push), so the mesh redials once. ```toml [listen.tls] @@ -273,8 +210,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 \ @@ -294,49 +230,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 '**' --mtls-peer`. - -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` | | --- | --- | @@ -359,35 +279,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] @@ -397,10 +306,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 f825bba3105..76857192e41 100644 --- a/doc/bin/relay/cluster.md +++ b/doc/bin/relay/cluster.md @@ -16,52 +16,35 @@ 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+. -moq-transport drafts 14 and 15 cannot ask for every broadcast, since an empty -namespace prefix is illegal before draft 16. On such a link to a peer without -the MoQ Solicit extension, such as moxygen, the relay does not ask for the -whole namespace and learns only what the peer announces unasked. moxygen -announces nothing unasked on draft 14, so that link discovers no broadcasts. - -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. +moq-transport drafts 14 and 15 cannot ask for every broadcast (an empty +namespace prefix is illegal before draft 16), so a link to a peer without the +MoQ Solicit extension, such as moxygen, learns only what that peer announces +unasked. moxygen announces nothing unasked on draft 14. + +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. RTMP, SRT, and WHIP ingest mint one per -connection, so an encoder reconnecting to the same path replaces its stale -connection at once. Epochs order by their creation time, so a reconnect to a -different gateway assumes the two gateways' clocks roughly agree. 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; the RTMP, SRT, and WHIP ingests mint one per connection. Epochs +order by creation time, so a reconnect to a different gateway assumes the two +gateways' clocks roughly agree. 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, the route carrying the epoch +supersedes the one without each time it appears, so 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 @@ -105,21 +88,15 @@ 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. -`moq auth serve --mtls-peer --mtls-upstream` grants it to every certificate, -so use it only where nothing but cores dial in with mTLS: on a hub that -leaves dial into, it marks every leaf upstream, and the hub stops forwarding -between them. 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`. `moq auth serve --mtls-peer --mtls-upstream` grants that to +every certificate, so use it only where cores are the only relays dialing in +with mTLS: on a hub that leaf relays dial into, it marks every leaf upstream +and the hub stops forwarding between them. 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 @@ -148,57 +125,35 @@ 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. - -Routes carry one static price: the publisher's production cost plus the configured link costs. A live publisher seeds 0; a standby uses a higher price than any live route it competes with. Caching does not change the route price. +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. -moq-lite-07-wip carries that one cost. For lite-06 compatibility, the relay reads Warm as the cost, ignores Cold, and writes Cold at the saturation ceiling. A protocol without a route cost adds only the local link price. +A route's price is the publisher's production cost plus the link costs it +crosses. A live publisher seeds 0, and caching never changes it. ## LAN discovery @@ -219,20 +174,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 @@ -287,26 +234,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 '**' --mtls-peer` (or a -server of your own that grants the cluster CA with `peer: true`) 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. -Such a peer is admitted as a client, so what it forwards counts as ingested -here. 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`, as `--mtls-peer` -does; 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 '**' --mtls-peer`. An +accepted peer counts as a cluster peer only when its grant sets `peer: true`, +as `--mtls-peer` 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 b4909825a2e..ed46c2f4ef4 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. A setting no configured listener reads stops startup rather than being ignored. A stream-only relay refuses `preferred_v4`, `preferred_v6`, and `lb_id` (or `load_balancer`), which @@ -68,27 +62,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] @@ -105,22 +88,12 @@ 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) is 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`. 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] @@ -187,15 +160,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] @@ -206,21 +174,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` is a byte target, repaid as active publishers write. `duration` +(30s by default) bounds memory 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, even past `capacity`. ## \[stats] @@ -234,16 +191,13 @@ 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. Each run, and each group returning after its linger, announces under -a fresh [epoch](/concept/moq-lite#publisher-epochs) on its route, so a restart -is a new broadcast at the same path. Each `sessions.json` row also carries -`announces_peak` and `subscriptions_peak`: the most any one session under that -root held against the per-session limits, past which a session is closed with -`TOO_MANY_REQUESTS`. [Stats](/concept/stats) describes the paths, tracks, and +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 and LAN peers it admits), which is what makes billing per customer or per region possible. +Each run, and each group returning after its linger, announces under a fresh +[epoch](/concept/moq-lite#publisher-epochs), so a restart is a new broadcast at +the same path. Session rows report how close sessions come to the per-session +limits, past which one is closed with `TOO_MANY_REQUESTS`. [Stats](/concept/stats) describes the paths, tracks, and encodings; read them with the [`moq-stats`](https://docs.rs/moq-stats) crate. ## \[iroh] @@ -264,20 +218,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] @@ -286,19 +232,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 2742ab690a2..cd6483e9b56 100644 --- a/doc/bin/rtmp.md +++ b/doc/bin/rtmp.md @@ -43,34 +43,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 fe16815c16e..2022b372a2b 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,14 +24,13 @@ 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. Each connection publishes under a fresh -[epoch](/concept/moq-lite#publisher-epochs) per broadcast: an encoder that -reconnects while its stale connection is still open replaces it at once. -Subscriptions to the stale feed end with `Unroutable` instead of stalling, and -a viewer's next subscribe reaches the new feed. +Each connection publishes under a fresh +[epoch](/concept/moq-lite#publisher-epochs), so an encoder that reconnects +while its stale connection is still open replaces it at once: subscriptions to +the stale feed end with `Unroutable`, and a viewer's next subscribe reaches the +new feed. -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). @@ -44,10 +39,8 @@ 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 export's jitter -buffer delay, as `export ts --delay` in the [CLI](/bin/cli): each frame is muxed that -long after its decode time, and one arriving later is dropped. 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 +export's jitter buffer, like `export ts --delay` in the [CLI](/bin/cli#export): +a frame arriving later than that is dropped. 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/hang.md b/doc/concept/hang.md index 721a4ae0b9d..a35b1e5a834 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 @@ -153,8 +153,9 @@ on data tracks remain data, including empty text cues. A video group is a GoP: it begins with a keyframe and holds the frames that depend on it. That alignment is what makes MoQ's congestion behavior safe. A relay can drop a whole group, a viewer can join at any group boundary, and the -decoder never sees a frame whose reference is missing. Audio groups are -independent too and typically hold about a second. +decoder never sees a frame whose reference is missing. Audio frames are +independent, so an audio group can end at any frame; the first-party encoders +put one packet in each unless told otherwise. 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, @@ -163,6 +164,21 @@ exception: its samples are always length-prefixed, so an `avc3`/`hev1` CMAF track keeps the configuration record as its `description` for the NAL length size, even when the parameter sets ride in the samples. +## 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 under a fresh epoch +shares no names or keys with the previous run. Never share or reuse an epoch +under one credential, whether for a replica or a later run: two instances on +one epoch derive the same keys from the same group sequences and repeat +AES-GCM nonces. 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 6e09b5a1b7d..2ce675053a6 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,132 +39,85 @@ 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. 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. 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, which is opt-in. Older moq-lite versions and +moq-transport cannot carry it, so their routes have no epoch: a relay keeps a +subscription on the route it first resolved through, and viewers of a +restarted publisher wait until the old session closes. 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, kept across reconnects, and the +RTMP, SRT, and WHIP ingests mint one per connection. Replicas share one by +passing the same `moq --epoch`, except under [encryption](/concept/hang#encryption). 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 | | --- | --- | @@ -225,88 +127,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: @@ -322,53 +157,25 @@ 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 track is all timed or all untimed: it declares a timescale or none, and a -frame that doesn't match is refused. An untimed track stays untimed at every -hop: no receiver fills in arrival time, which would change whenever a route -fails over. An untimed group is never too old, so the cache's own expiry is what -reclaims it, and a new subscriber to an untimed track starts at its latest group -unless it names a start. Tracks from lite before 05, or from moq-transport -without a `TIMESCALE` (every track on drafts 14–16), arrive untimed. Lite cannot -mark a track untimed yet, so a lite-05 or later publisher sends each frame of an -untimed track with its send time. - -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 track is timed or untimed: it declares a timescale or none, and a frame that +doesn't match is refused. No receiver fills in an arrival time. An untimed +group never falls past max delay, so a new subscriber starts at its latest +group unless it names a start. Tracks from moq-lite before 05, or from +moq-transport without a `TIMESCALE` (every track on drafts 14-16), arrive +untimed. No moq-lite version can declare an untimed track, so on 05 and later +its frames go out stamped with their send time. 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. Readers resume once the -cache shows the answered position: a received group stays hidden until its -first frame lands or its stream ends, since a bare group header would leave the -older cached group looking like the live edge. 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: @@ -397,10 +204,12 @@ a datagram refuses with `NOT_FETCHABLE` (moq-lite-07), otherwise with 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 | | --- | --- | --- | @@ -408,28 +217,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 3a985f86eac..478d49ea0ef 100644 --- a/doc/concept/standard.md +++ b/doc/concept/standard.md @@ -18,105 +18,22 @@ 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. -In Rust, drafts 14 to 16 apply a subscription's `SUBSCRIBE_UPDATE` -(`REQUEST_UPDATE` on draft 16) the same way. Draft 14 sends no answer and has -no `UPDATE_FAILED`, so a refused update ends the subscription with -`INTERNAL_ERROR`. On those drafts an update to any other request is ignored. - -Rust and JavaScript accept repeated unknown `SETUP` options, including GREASE, -while still requiring every value to be well-formed. Repeated known options -are rejected. On draft-17 and later, a `GROUP_ORDER` message parameter must be -Ascending (1) or Descending (2); any other value closes the session with -`PROTOCOL_VIOLATION`. - -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` keeps each object's Timestamp, in the -units the track's `SUBSCRIBE_OK` declares. `FETCH_OK` doesn't declare them yet, -so a reader that never subscribed reads the objects untimed. - -A track whose `SUBSCRIBE_OK` declares no `TIMESCALE` is untimed: its objects -arrive untimed, and an object-scope Timescale or a Timestamp on them is -ignored, as on imquic's LOC objects. A relay serves such a track downstream -untimed, without a `TIMESCALE` of its own. On a track that declares one, an -object without a Timestamp is malformed. Drafts 14–16 can't carry `TIMESCALE`, -so every track there is untimed. - -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. Datagrams are never fetchable: a fetch -object flagged as a datagram fails only that fetch, as `NotFetchable`, and a -relay answers its own downstream FETCH with `DOES_NOT_EXIST`, or `NOT_FETCHABLE` -to a moq-lite-07 peer. 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. Without it, a draft 16+ peer also gets each match as a `NAMESPACE` on its `SUBSCRIBE_NAMESPACE` stream, so it hears the namespace twice. We never send `PUBLISH`: on drafts 16 and 17 a `SUBSCRIBE_NAMESPACE` asking only for `PUBLISH` is refused, one asking for both gets only `NAMESPACE`, and any other Subscribe Options value closes the session. +- **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`. Datagrams are never fetchable. +- **Timing.** A track whose `SUBSCRIBE_OK` declares no `TIMESCALE` is untimed, as is every track on drafts 14 through 16. A reader that never subscribed reads a standalone fetch untimed. +- **Strict SETUP and parameters.** Repeated unknown `SETUP` options, GREASE included, are accepted if well-formed; a repeated known option is rejected. On draft 17 and later, a `GROUP_ORDER` other than Ascending (1) or Descending (2) closes the session. +- **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, and in Rust on drafts 14 through 16, 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. Several project drafts extend the IETF wire without breaking it, since `SETUP` ignores unknown parameters: [cluster](/draft/moq-cluster) routing hop lists, @@ -125,8 +42,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). ### Deliberate deviations @@ -185,14 +103,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. A peer that does not -set that option still gets each match as a `NAMESPACE` on its `SUBSCRIBE_NAMESPACE` -stream on draft-16 and later, so it hears the namespace twice. We never send -`PUBLISH`: on drafts 16 and 17 a `SUBSCRIBE_NAMESPACE` asking only for `PUBLISH` -is refused, one asking for both gets only `NAMESPACE`, and any other Subscribe -Options value closes the session. 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/stats.md b/doc/concept/stats.md index b7a2a1f7055..94d11bc6d0b 100644 --- a/doc/concept/stats.md +++ b/doc/concept/stats.md @@ -51,14 +51,13 @@ 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 and its counters dropped; a group that returns later announces a new epoch counted from zero. Within one epoch, group numbers keep -increasing across recreated tracks; 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. +increasing across recreated tracks 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 and LAN peers it admits. Each tier has three tracks, each in two encodings: | Track | Frame keyed by | Entry | @@ -178,8 +177,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/concept/use-case/contribution.md b/doc/concept/use-case/contribution.md index 4b45fdc9f9a..760dcb153fd 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 failover --- # MoQ vs RTMP/SRT @@ -22,14 +22,16 @@ 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 +## Failover and restarts -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 broadcast can be announced over several connections. Seamless failover +between them needs a [publisher epoch](/concept/moq-lite#publisher-epochs) +(moq-lite 07, opt-in), which 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, given hosts whose +clocks roughly agree. The RTMP, SRT, and +WHIP ingests mint one per connection. Without an epoch, a subscription stays on +the route it first resolved through until that route goes. ## One protocol both ways diff --git a/doc/concept/use-case/index.md b/doc/concept/use-case/index.md index 9547e751fae..5c1b8036df3 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, optional on-demand encoding, and epoch-based 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/c/index.md b/doc/lib/c/index.md index 90c4eae199b..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 (one read from an untimed track has `timestamp_present` false), 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 whether a video rendition is enabled (`moq_consume_video_enabled`). 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 a2d98d474bb..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,100 +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`. - -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. +## Things to know -`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. +The rest of the [shared feature list](/lib/#what-every-binding-can-do) maps +one to one; the API reference has the names. -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. +- **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. -`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). - -A raw `MoqFrame` or `MoqDatagram` has a null `timestampUs` (and `timestamp`) when it was read from an untimed track; see [untimed tracks](/concept/moq-lite#subscriptions). A raw track you publish is always timed. - -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 f080ae30d15..af34aabbb58 100644 --- a/doc/lib/go/index.md +++ b/doc/lib/go/index.md @@ -64,6 +64,7 @@ broadcast, _ := client.CreateBroadcast("my-stream.hang") audio, _ := broadcast.PublishAudio(moq.AudioFormatOpus, opusInit) pts := uint64(20_000) _ = audio.WriteFrame(moq.Frame{Payload: packet, TimestampUs: &pts}) +_ = audio.Cut() // audio has no keyframes, so this is what gives it groups track := "camera" video, _ := broadcast.EncodeVideo( @@ -78,110 +79,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). - -A raw `Frame` or `Datagram` has a nil `TimestampUs` when it was read from an untimed track; see [untimed tracks](/concept/moq-lite#subscriptions). A raw track you publish is always timed. - -`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 0a1169ace21..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: one static `cost` for production and the links the route crosses. -- **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 8f31bc78bc4..b3ddb203e72 100644 --- a/doc/lib/js/hang.md +++ b/doc/lib/js/hang.md @@ -10,39 +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, and `Catalog.ranked(renditions)` orders video renditions best first, the order `` picks from. +- **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)`. - -`Catalog.ranked(renditions)` orders a video rendition map best first: largest -coded picture, then highest bitrate, then name. A missing width, height, or -bitrate ranks below a known value. `` uses that order when nothing -caps the rendition. - -`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)) { @@ -52,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/json.md b/doc/lib/js/json.md index 1ae7662e2ac..1a7b5d91297 100644 --- a/doc/lib/js/json.md +++ b/doc/lib/js/json.md @@ -7,42 +7,23 @@ 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)`. Every frame carries a timestamp, so the track must -declare a timescale, such as `createTrack(name, { timescale: Time.Timescale.MILLI })`. - -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. 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, so the track must +declare a timescale. + +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 anything is written 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 8a1daa2673b..c2121e9f3ff 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,121 +28,23 @@ const connection = await Moq.Connection.connect({ const broadcast = origin.createBroadcast(Moq.Path.from("chat.room")); const track = broadcast.createTrack("messages", { timescale: Moq.Time.Timescale.MILLI }); 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. -- **Epoch pinning**: `consumer.request(path, { epoch })` pins an announced publisher instance. The request stays unresolved and reports `unroutable` when the winning route names a different or missing epoch, including while an asynchronous handler answers. Omit `epoch` for unpinned lookup. The resolved broadcast's `epoch` names the route it actually resolved through, pinned or not. -- **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. New requests keep opening on the old session until the replacement's route outranks it. 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. -- **Timing** is per track. A timed track declares `Track.Info.timescale` (such as `Time.Timescale.MILLI`); omitting it (or passing `null`, which means the same) declares an untimed track. There is no default, unlike Rust's millisecond default. A frame or datagram carries a `timestamp` exactly when its track has a timescale, and a write that disagrees throws `Error.TimestampMismatch`. Nothing fills in a time on receive: moq-lite before 05, and moq-transport without TIMESCALE (always so on drafts 14-16), deliver untimed tracks. moq-lite 05 and 06 can't declare an untimed track, so it goes out at milliseconds with each frame's send time. An untimed group is never stale, so a subscription without a `groups.start` begins at the latest group. -- **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. JS apps do not proxy: `accept` - throws on a broadcast a session delivered, since it would go out labeled - with this origin's hop. Copy its tracks into a broadcast you produce and - accept that instead. - -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 +- **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. `accept` throws on a broadcast a session delivered, since JS apps do not proxy; copy its tracks into a broadcast you produce instead. +- **Requests can pin an epoch.** `consumer.request(path, { epoch })` resolves only through a route announcing that [publisher epoch](/concept/moq-lite#publisher-epochs) and reports `unroutable` otherwise. The resolved broadcast's `epoch` names the route it came through, pinned or not. +- **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). New requests keep opening on the old session until the replacement's route outranks it. 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. +- **Timing is per track, with no default.** A track that declares a `timescale` carries a `timestamp` on every frame; one without is [untimed](/concept/moq-lite#subscriptions) and its frames carry none. Unlike Rust, omitting it means untimed. +- **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. + +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/js/publish.md b/doc/lib/js/publish.md index 572c7d86a3a..df70c8320ed 100644 --- a/doc/lib/js/publish.md +++ b/doc/lib/js/publish.md @@ -31,87 +31,41 @@ 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 `