diff --git a/dart/moq_ffi/lib/src/moq.dart b/dart/moq_ffi/lib/src/moq.dart index a0c2169c173..469ee931747 100644 --- a/dart/moq_ffi/lib/src/moq.dart +++ b/dart/moq_ffi/lib/src/moq.dart @@ -22146,7 +22146,7 @@ void _checkApiChecksums() { if (uniffi_moq_ffi_checksum_method_moqpublication_unannounce() != 21154) { throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); } - if (uniffi_moq_ffi_checksum_method_moqbroadcastproducer_close() != 26090) { + if (uniffi_moq_ffi_checksum_method_moqbroadcastproducer_close() != 21298) { throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); } if (uniffi_moq_ffi_checksum_method_moqbroadcastproducer_consume() != 27634) { diff --git a/doc/concept/identity.md b/doc/concept/identity.md index c663bc6d85f..3e626bd79a0 100644 --- a/doc/concept/identity.md +++ b/doc/concept/identity.md @@ -122,10 +122,13 @@ fresh broadcast. Choose between two kinds of reader. **Follow announcements** when the reader should outlive any one stream, as a player does. Start on each broadcast, drop all decoder and buffer state on a restart, and wait on an end. Rust uses `consumer.follow(path, None)` (or -`moq_mux::follow::Instances`), and JavaScript `origin.follow(path)`. -`@moq/watch`, `moq play`, and `moqsrc` follow this way, and -`moq export ts --stitch` can splice a replacement as a marked program switch. -A request failing is never the signal to restart; the announcement is. +`moq_mux::follow::Instances`), JavaScript `origin.follow(path)`, and the +moq-ffi bindings `follow(path)` with `available()`. `@moq/watch`, `moq play`, +and `moqsrc` follow this way, and `moq export ts --stitch` can splice a +replacement as a marked program switch. A request failing is never the signal +to restart; the announcement is. Nor is a track's error kind: a track withdrawn +unfinished ends `Unroutable` over moq-lite but `Internal` over moq-transport, +whose wire has no code for it. **Hold one stream** when the output must not splice two, as an exporter or recorder does. Rust and JavaScript `request(path)` and `moq_mux::Source` keep diff --git a/doc/lib/c/index.md b/doc/lib/c/index.md index fccde265737..a9b5d6533cc 100644 --- a/doc/lib/c/index.md +++ b/doc/lib/c/index.md @@ -105,7 +105,7 @@ inside. The header is the reference: each function carries a doc comment. - **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. Pass that cadence as `moq_audio_init.hint.group_duration_us`. - **Catalog hints.** Give the catalog what the encoder knows instead of having it estimated: `moq_video_init.hint` (coded size, bitrate, frame rate, group duration) and `moq_audio_init.hint` (bitrate, group duration). A supplied bitrate is never re-estimated. `group_duration_us` is the longest span between two group starts: the GOP, or your cut cadence. Leave a field's `has_*` flag false to have it measured. A bitrate or `group_duration_us` flag set with a 0 value returns `MOQ_ERROR_INVALID_CONFIG`. - **Discovery.** Announcement captures are always a list of wildcard matches, empty when the filter has no wildcards. -- **Ending cleanly.** When the input ends, finish every track, then call `moq_publish_catalog_finish()` to finish the catalog, which ends the content. The broadcast stays announced and keeps serving the finished tracks, so a subscriber still catching up can drain them, until `moq_publish_close()` takes it offline. How long to keep it up is yours to decide. A track still open at the close ends with `UNROUTABLE`, which readers take as the publisher leaving, and its handle is released. +- **Ending cleanly.** When the input ends, finish every track, then call `moq_publish_catalog_finish()` to finish the catalog, which ends the content. The broadcast stays announced and keeps serving the finished tracks, so a subscriber still catching up can drain them, until `moq_publish_close()` takes it offline. How long to keep it up is yours to decide. A track still open at the close ends with `UNROUTABLE` (an internal error over moq-transport, which has no such code), and its handle is released. Readers follow a publisher's runs by announcement, not by that error: see [identity and recovery](/concept/identity). - **Timeline breaks.** On a seek or pause, call `moq_publish_media_discontinuity`, then keep timestamps moving forward and resume video on a keyframe. - **Timestamps.** A `moq_timestamp` is exact: `value` units at `scale` units per second, so a 90 kHz tick survives a read and republish. Frames, datagrams, and JSON values point `timestamp` at theirs, NULL on an untimed track and valid as long as the payload. Tracks moq-c creates are timed, so their raw writes need one. JSON writes, including window pushes and pops, take one too, converted to their track's milliseconds; NULL stamps the broadcast clock's current time. A zero scale or an out-of-range value fails with `MOQ_ERROR_TIMESTAMP_OVERFLOW`. - **JSON values.** `moq_consume_json_value` fills `moq_json_value` with the document and its frame's timestamp. A snapshot consumer's callback fires for each state in order, but a group superseded before it is read is skipped. diff --git a/doc/lib/cpp/index.md b/doc/lib/cpp/index.md index c5a4339f6c1..4b139d69663 100644 --- a/doc/lib/cpp/index.md +++ b/doc/lib/cpp/index.md @@ -250,8 +250,9 @@ its `moq::MediaCatalogProducer` to finish the catalog, which ends the content. The broadcast stays announced and keeps serving the finished tracks, so a subscriber still catching up can drain them, until `broadcast->close()` takes it offline. How long to keep it up is yours to decide. A track still open at the -close, or released without a finish, ends with `Unroutable`, which readers take -as the publisher leaving. +close, or released without a finish, ends with `Unroutable` (`Internal` over +moq-transport, which has no such code). Readers follow a publisher's runs by +announcement, not by that error: see [identity and recovery](/concept/identity). `moq::shutdown()` stops the `moq-ffi` runtime workers, then the executor. Pending calls resolve `Cancelled`, and every object stays safe to drop. Call diff --git a/doc/lib/dart/index.md b/doc/lib/dart/index.md index d01410bb6da..106c767cb72 100644 --- a/doc/lib/dart/index.md +++ b/doc/lib/dart/index.md @@ -153,7 +153,7 @@ shows which module holds each. - **Media reads.** `media.TrackConsumer`, `audio.Consumer`, and `video.Consumer` return a `Read` in order: a `ReadFrame`, a `ReadGap` where media was lost, or a `ReadEnd` where the publisher stopped its encoder. A gap breaks continuity. An encoder end is not stream EOF: following frames before its endpoint are the old encoder's drain; the first at or past it starts fresh. A decoder reads everything the track still holds unless a live player sets `start: media.DecodeStart.latest` in its decoder output, which joins at the newest group and skips the cached backlog. - **Decoded frames hold decoder buffers.** `dispose()` each frame from a `video.Consumer` promptly rather than waiting for the garbage collector, or the decoder stalls. `resize` is best effort, so read each frame's `width()` and `height()`. - **Closing.** `await moq.close()` drains for up to one second and reports its result. `session.shutdown()` requests the drain synchronously; `await session.closed()` waits for its result. `session.cancel(code: 0)` closes at once. Finish or abort live tracks first. Awaiting cancellation of an announcement, grant, or request subscription releases its pending native read. Announcements and grants also release their consumer; server listeners leave their shared server usable. moq-lite-05 and newer wait for the peer to receive finished tails; older Lite versions and IETF wait only for transport ACKs. -- **Ending cleanly.** When the input ends, finish every track, then call `finish()` on its `CatalogProducer` to finish the catalog, which ends the content. The broadcast stays announced and keeps serving the finished tracks, so a subscriber still catching up can drain them, until `broadcast.close()` takes it offline; disposing its `Publication` does not. How long to keep it up is yours to decide. A track still open at the close, or released without a finish, ends with `Unroutable`, which readers take as the publisher leaving. +- **Ending cleanly.** When the input ends, finish every track, then call `finish()` on its `CatalogProducer` to finish the catalog, which ends the content. The broadcast stays announced and keeps serving the finished tracks, so a subscriber still catching up can drain them, until `broadcast.close()` takes it offline; disposing its `Publication` does not. How long to keep it up is yours to decide. A track still open at the close, or released without a finish, ends with `Unroutable` (`Internal` over moq-transport, which has no such code). Readers follow a publisher's runs by announcement, not by that error: see [identity and recovery](/concept/identity). - **Stats.** `session.stats()` reports `rtt`, `estimatedSendRateBps`, 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. `version` names the negotiated protocol. Connect returns a connecting session; read its coherent `state()` snapshot and wait with that snapshot's revision to observe first-dial failures and reconnects. Each watcher keeps its own revision. Hold the owned `BandwidthConsumer` returned by `session.recvBandwidth()` to receive bandwidth estimates. `rate()` reads the current estimate in bits per second and `rateChanged()` waits for a new one. Release the consumer or call `cancel()` when finished; releasing the last consumer stops PROBE; the session and stats snapshots do not request it. Client consumers survive reconnects and report no estimate while disconnected. - **Authorization.** On `moq-lite-07-wip` (opt in with `ConnectOptions(versions: ...)`) and on moq-transport draft-18+ with the [MoQ Auth extension](/draft/moq-auth), listen to `moq.grants().updates()` for the `Grant` the relay sent back and each change, `null` until it answers and while a client session reconnects. - **Tokens.** Pass `ConnectOptions(tokens: [...])` instead of putting the credential in the URL. The first is the connection credential, sent in SETUP and, while an offered version can't carry it there (lite before 07), as the URL's `?jwt=`; each other token widens the grant over AUTH. `moq.tokens().set_(tokens: [...])` replaces them before they expire: the next dial presents them, a live AUTH session at once, and after an authorization refusal the session redials only if they changed. `await tokens().answered()` returns once the relay accepts them and throws its refusal with the relay's code. A `?jwt=` already in the URL stays the connection credential, which is how to reach a relay older than this release. diff --git a/doc/lib/go/index.md b/doc/lib/go/index.md index 3e5a5679925..5ad9e4eb92e 100644 --- a/doc/lib/go/index.md +++ b/doc/lib/go/index.md @@ -135,7 +135,7 @@ shows which module holds each. - **Media reads.** `media.TrackConsumer`, `audio.Consumer`, and `video.Consumer` return a `Read` in order: `ReadFrame`, a `ReadGap` where media was lost, or a `ReadEnd` where the publisher stopped its encoder. A gap breaks continuity. An encoder end is not stream EOF: following frames before its endpoint are the old encoder's drain; the first at or past it starts fresh. A decoder reads everything the track still holds unless a live player sets `Start: media.DecodeStartLatest` in its decoder output, which joins at the newest group and skips the cached backlog. - **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()` drains for up to one second and returns an error on failure. `session.Shutdown()` requests that drain immediately; `session.Closed(ctx)` waits for its result, and `session.Cancel(code)` closes at once. Finish or abort live tracks first. moq-lite-05 and newer wait for the peer to receive finished tails; older Lite versions and IETF wait only for transport ACKs. -- **Ending cleanly.** When the input ends, finish every track, then call `Finish()` on its `media.CatalogProducer` to finish the catalog, which ends the content. The broadcast stays announced and keeps serving the finished tracks, so a subscriber still catching up can drain them, until `broadcast.Close()` takes it offline. How long to keep it up is yours to decide. A track still open at the close, or released without a finish, ends with `Unroutable`, which readers take as the publisher leaving. +- **Ending cleanly.** When the input ends, finish every track, then call `Finish()` on its `media.CatalogProducer` to finish the catalog, which ends the content. The broadcast stays announced and keeps serving the finished tracks, so a subscriber still catching up can drain them, until `broadcast.Close()` takes it offline. How long to keep it up is yours to decide. A track still open at the close, or released without a finish, ends with `Unroutable` (`Internal` over moq-transport, which has no such code). Readers follow a publisher's runs by announcement, not by that error: see [identity and recovery](/concept/identity). - **Stats.** `Session().Stats()` reports `RTT`, `EstimatedSendRateBps`, 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. `Version` names the negotiated protocol. `Dial` returns a connecting session; read `Session().State()` and wait with `StateChanged(ctx, state.Revision)` to observe first-dial failures and reconnects. Hold the owned `BandwidthConsumer` returned by `Session().RecvBandwidth()` to receive bandwidth estimates. `Rate()` reads the current estimate in bits per second and `RateChanged(ctx)` waits for a new one. Calling `Close()` on the last consumer stops PROBE; the session and stats snapshots do not request it. Client consumers survive reconnects and report no estimate while disconnected. - **Authorization.** On `moq-lite-07-wip` (opt in with `ClientConfig.Versions`) and on moq-transport draft-18+ with the [MoQ Auth extension](/draft/moq-auth), `Session().Grants()` returns a `GrantConsumer`: `Grant()` is the `Grant` the relay sent back, nil until it answers and while a client session reconnects, and `Changed(ctx)` waits for the next one. `Close()` it when done. - **Tokens.** Set `ClientConfig.Tokens` instead of putting the credential in the URL. The first is the connection credential, sent in SETUP and, while an offered version can't carry it there (lite before 07), as the URL's `?jwt=`; each other token widens the grant over AUTH. `Session().Tokens().Set(...)` replaces a client session's tokens before they expire: the next dial presents them, a live AUTH session at once, and after an authorization refusal the session redials only if they changed. `Answered(ctx)` returns nil once the relay accepts them, or its refusal with the relay's code. A `?jwt=` already in the URL stays the connection credential, which is how to reach a relay older than this release. diff --git a/doc/lib/kt/index.md b/doc/lib/kt/index.md index 719e662c68e..d7c33fb9fe5 100644 --- a/doc/lib/kt/index.md +++ b/doc/lib/kt/index.md @@ -108,7 +108,7 @@ shows which module holds each. - **Media reads.** `dev.moq.media.TrackConsumer`, `dev.moq.audio.Consumer`, and `dev.moq.video.Consumer` return a `Read` in order: `ReadFrame`, a `ReadGap` where media was lost, or a `ReadEnd` where the publisher stopped its encoder. A gap breaks continuity. An encoder end is not stream EOF: following frames before its endpoint are the old encoder's drain; the first at or past it starts fresh. A decoder reads everything the track still holds unless a live player sets `start = DecodeStart.LATEST` in its decoder output, which joins at the newest group and skips the cached backlog. - **Decoded frames hold decoder buffers.** `close()` each frame from a `dev.moq.video.Consumer` promptly (or `use { }` it), or the decoder stalls. `resize` is best effort, so read each frame's `width()` and `height()`. - **Closing.** `moq.shutdown()` requests a drain immediately; suspending `moq.session.closed()` waits up to one second and reports its result. `Moq.close()`, and so `use { }`, cancels at once. Finish or abort live tracks first. moq-lite-05 and newer wait for the peer to receive finished tails; older Lite versions and IETF wait only for transport ACKs. -- **Ending cleanly.** When the input ends, finish every track, then call `finish()` on its `CatalogProducer` to finish the catalog, which ends the content. The broadcast stays announced and keeps serving the finished tracks, so a subscriber still catching up can drain them, until `broadcast.end()` takes it offline. How long to keep it up is yours to decide. A track still open at the end, or released without a finish, ends with `Unroutable`, which readers take as the publisher leaving. +- **Ending cleanly.** When the input ends, finish every track, then call `finish()` on its `CatalogProducer` to finish the catalog, which ends the content. The broadcast stays announced and keeps serving the finished tracks, so a subscriber still catching up can drain them, until `broadcast.end()` takes it offline. How long to keep it up is yours to decide. A track still open at the end, or released without a finish, ends with `Unroutable` (`Internal` over moq-transport, which has no such code). Readers follow a publisher's runs by announcement, not by that error: see [identity and recovery](/concept/identity). - **Stats.** `session.stats()` reports `rtt`, `estimatedSendRateBps`, 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. `version` names the negotiated protocol. Connect returns a connecting session; read its coherent `state()` snapshot and wait with that snapshot's revision to observe first-dial failures and reconnects. Each watcher keeps its own revision. Hold the owned `BandwidthConsumer` returned by `session.recvBandwidth()` to receive bandwidth estimates. `rate()` reads the current estimate in bits per second and `rateChanged()` waits for a new one. Release the consumer or call `cancel()` when finished; releasing the last consumer stops PROBE; the session and stats snapshots do not request it. Client consumers survive reconnects and report no estimate while disconnected. - **Authorization.** On `moq-lite-07-wip` (opt in with `ClientConfig(versions = ...)`) and on moq-transport draft-18+ with the [MoQ Auth extension](/draft/moq-auth), collect `moq.grants().updates()` for the `Grant` the relay sent back and each change, `null` until it answers and while a client session reconnects. Ending the collection cancels the consumer. - **Tokens.** Pass `ClientConfig(tokens = listOf(...))` instead of putting the credential in the URL. The first is the connection credential, sent in SETUP and, while an offered version can't carry it there (lite before 07), as the URL's `?jwt=`; each other token widens the grant over AUTH. `moq.tokens().set(listOf(...))` replaces them before they expire: the next dial presents them, a live AUTH session at once, and after an authorization refusal the session redials only if they changed. Suspending `tokens().answered()` returns once the relay accepts them and throws its refusal with the relay's code. A `?jwt=` already in the URL stays the connection credential, which is how to reach a relay older than this release. diff --git a/doc/lib/py/index.md b/doc/lib/py/index.md index 52d1044c992..3f1a8d5ae3f 100644 --- a/doc/lib/py/index.md +++ b/doc/lib/py/index.md @@ -123,7 +123,7 @@ shows which module holds each. - **Media reads.** `media.TrackConsumer`, `moq.audio.Consumer`, and `moq.video.Consumer` yield, in order, frames, a `Gap` where media was lost, and an `End` where the publisher stopped its encoder. A gap breaks continuity. An encoder end is not stream EOF: following frames before its endpoint are the old encoder's drain; the first at or past it starts fresh. A decoder reads everything the track still holds unless a live player sets `start=moq.media.DecodeStart.LATEST` in its decoder output, which joins at the newest group and skips the cached backlog. - **Decoded frames hold decoder buffers.** Drop each frame from a `moq.video.Consumer` promptly, or the decoder stalls. `resize` is best effort, so read each frame's `width()` and `height()`. - **Closing.** `session.shutdown()` requests a drain immediately; `await session.closed()` waits up to one second and reports its result. `cancel(code)` closes at once. Finish or abort live tracks first. moq-lite-05 and newer wait for the peer to receive finished tails; older Lite versions and IETF wait only for transport ACKs. -- **Ending cleanly.** When the input ends, finish every track, then call `finish()` on its `moq.media.CatalogProducer` to finish the catalog, which ends the content. The broadcast stays announced and keeps serving the finished tracks, so a subscriber still catching up can drain them, until `broadcast.close()` takes it offline. How long to keep it up is yours to decide. A track still open at the close, or released without a finish, ends with `Unroutable`, which readers take as the publisher leaving. +- **Ending cleanly.** When the input ends, finish every track, then call `finish()` on its `moq.media.CatalogProducer` to finish the catalog, which ends the content. The broadcast stays announced and keeps serving the finished tracks, so a subscriber still catching up can drain them, until `broadcast.close()` takes it offline. How long to keep it up is yours to decide. A track still open at the close, or released without a finish, ends with `Unroutable` (`Internal` over moq-transport, which has no such code). Readers follow a publisher's runs by announcement, not by that error: see [identity and recovery](/concept/identity). - **Stats.** `session.stats()` reports `rtt`, `estimated_send_rate_bps`, and the byte and packet counters (`bytes_sent`, `bytes_received`, `bytes_lost`, `packets_sent`, `packets_received`, `packets_lost`). A field is `None` when the transport does not report it, which is not the same as zero. `version` names the negotiated protocol. Connect returns a connecting session; read its coherent `state()` snapshot and wait with that snapshot's revision to observe first-dial failures and reconnects. Each watcher keeps its own revision. Hold the owned `BandwidthConsumer` returned by `session.recv_bandwidth()` to receive bandwidth estimates. `rate()` reads the current estimate in bits per second and `rate_changed()` waits for a new one. Release the consumer or call `cancel()` when finished; releasing the last consumer stops PROBE; the session and stats snapshots do not request it. Client consumers survive reconnects and report no estimate while disconnected. - **Authorization.** On `moq-lite-07-wip` (opt in with `versions=`) and on moq-transport draft-18+ with the [MoQ Auth extension](/draft/moq-auth), `async for grant in session.grants()` yields the `Grant` the relay sent back and each change, `None` until it answers and while a client session reconnects. `grants().grant()` reads it once; cancelling or leaving an `async with` releases the wait. - **Tokens.** Pass `tokens=[...]` instead of putting the credential in the URL. The first is the connection credential, sent in SETUP and, while an offered version can't carry it there (lite before 07), as the URL's `?jwt=`; each other token widens the grant over AUTH. `session.tokens().set([...])` replaces a client session's tokens before they expire: the next dial presents them, a live AUTH session at once, and after an authorization refusal the session redials only if they changed. `await tokens.answered()` returns once the relay accepts them and raises its refusal with the relay's code. A `?jwt=` already in the URL stays the connection credential, which is how to reach a relay older than this release. diff --git a/doc/lib/swift/index.md b/doc/lib/swift/index.md index cebbed1cda6..ec0ae5b804a 100644 --- a/doc/lib/swift/index.md +++ b/doc/lib/swift/index.md @@ -108,7 +108,7 @@ shows which module holds each. - **Media reads.** `Media.TrackConsumer`, `Audio.Consumer`, and `Video.Consumer` yield `Read` cases in order: `.frame`, a `.gap` where media was lost, or an `.end` where the publisher stopped its encoder. A gap breaks continuity. An encoder end is not stream EOF: following frames before its endpoint are the old encoder's drain; the first at or past it starts fresh. A decoder reads everything the track still holds unless a live player sets `start: .latest` in its decoder output, which joins at the newest group and skips the cached backlog. - **Decoded frames hold decoder buffers.** Release each frame from a `Video.Consumer` promptly, or the decoder stalls. `resize` is best effort, so read each frame's `width()` and `height()`. - **Closing.** `session.shutdown()` requests a drain immediately; `try await session.closed()` waits up to one second and reports its result. `session.cancel(code:)` closes at once. Finish or abort live tracks first. moq-lite-05 and newer wait for the peer to receive finished tails; older Lite versions and IETF wait only for transport ACKs. -- **Ending cleanly.** When the input ends, finish every track, then call `try finish()` on its `Media.CatalogProducer` to finish the catalog, which ends the content. The broadcast stays announced and keeps serving the finished tracks, so a subscriber still catching up can drain them, until `broadcast.close()` takes it offline. How long to keep it up is yours to decide. A track still open at the close, or released without a finish, ends with `Unroutable`, which readers take as the publisher leaving. +- **Ending cleanly.** When the input ends, finish every track, then call `try finish()` on its `Media.CatalogProducer` to finish the catalog, which ends the content. The broadcast stays announced and keeps serving the finished tracks, so a subscriber still catching up can drain them, until `broadcast.close()` takes it offline. How long to keep it up is yours to decide. A track still open at the close, or released without a finish, ends with `Unroutable` (`Internal` over moq-transport, which has no such code). Readers follow a publisher's runs by announcement, not by that error: see [identity and recovery](/concept/identity). - **Stats.** `session.stats()` reports `rtt`, `estimatedSendRateBps`, 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. `version` names the negotiated protocol. Connect returns a connecting session; read its coherent `state()` snapshot and wait with that snapshot's revision to observe first-dial failures and reconnects. Each watcher keeps its own revision. Hold the owned `BandwidthConsumer` returned by `session.recvBandwidth()` to receive bandwidth estimates. `rate()` reads the current estimate in bits per second and `rateChanged()` waits for a new one. Release the consumer or call `cancel()` when finished; releasing the last consumer stops PROBE; the session and stats snapshots do not request it. Client consumers survive reconnects and report no estimate while disconnected. - **Authorization.** On `moq-lite-07-wip` (opt in with `Client(versions:)`) and on moq-transport draft-18+ with the [MoQ Auth extension](/draft/moq-auth), `for try await grant in session.grants()` yields the `Grant` the relay sent back and each change, `nil` until it answers and while a client session reconnects. Cancelling the iterating task cancels the native wait. - **Tokens.** Pass `Client(tokens: [...])` instead of putting the credential in the URL. The first is the connection credential, sent in SETUP and, while an offered version can't carry it there (lite before 07), as the URL's `?jwt=`; each other token widens the grant over AUTH. `try session.tokens()?.set([...])` replaces them before they expire: the next dial presents them, a live AUTH session at once, and after an authorization refusal the session redials only if they changed. `try await tokens.answered()` returns once the relay accepts them and throws its refusal with the relay's code. A `?jwt=` already in the URL stays the connection credential, which is how to reach a relay older than this release. diff --git a/go/wrapper/publish.go b/go/wrapper/publish.go index aa808095ccc..6608d494210 100644 --- a/go/wrapper/publish.go +++ b/go/wrapper/publish.go @@ -61,9 +61,9 @@ func (b *BroadcastProducer) Consume() (*BroadcastConsumer, error) { } // Close ends the broadcast for good: it retracts and serves no new tracks. -// Tracks still open on it end with Unroutable, which readers take as the -// publisher leaving, and their later calls fail with ErrClosed; finish a track -// first to end it cleanly. Closing again is a no-op. +// Tracks still open on it end with Unroutable (Internal to a moq-transport +// reader), and their later calls fail with ErrClosed; finish a track first to +// end it cleanly. Closing again is a no-op. func (b *BroadcastProducer) Close() error { return b.inner.Close() } diff --git a/py/moq-rs/moq/publish.py b/py/moq-rs/moq/publish.py index bb48b38ae2a..6b1456b9c31 100644 --- a/py/moq-rs/moq/publish.py +++ b/py/moq-rs/moq/publish.py @@ -359,8 +359,8 @@ def consume(self) -> BroadcastConsumer: def close(self) -> None: """End the broadcast for good: retract it and serve no new tracks. - Tracks still open on it end with ``Unroutable``, which readers take as the publisher - leaving, and their later calls raise ``moq.Error.Closed``; finish a track first to end it - cleanly. Closing again is a no-op. + Tracks still open on it end with ``Unroutable`` (``Internal`` to a moq-transport reader), + and their later calls raise ``moq.Error.Closed``; finish a track first to end it cleanly. + Closing again is a no-op. """ self._inner.close() diff --git a/quest/m1/README.md b/quest/m1/README.md index 7cb047d9dcb..d61b9d69fb3 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -142,7 +142,6 @@ per-frame CPU growth since #5926. - [moq-c at parity](/quest/m1/c/README.md) - the hand-written `moq-c` ships at the cut with every m1 binding feature moq-ffi gains - [JSON writes take a broadcast-clock timestamp](/quest/m1/json-required-timestamp.md) - every binding's JSON write requires one, moq-c's NULL fails, and C gains `moq_publish_catalog_now()`, so C media stops advertising an 8 s delay - [Catalog delay is the least a track trails](/quest/m1/catalog-delay-min.md) - the estimator keeps the minimum trail, so B-frame reorder never becomes `delay` -- [Bindings see a moq-transport run end as an end](/quest/m1/ffi-ietf-run-end.md) - an IETF publisher ending its run reaches moq-ffi consumers as an end, not `Internal` - [Byte-stream renditions form a ladder](/quest/m1/stream-ladder.md) - moq-ffi stream producers link as `lower` and disable unfundable rungs like frame producers - [A job's exact route continues its claim's readers](/quest/m1/announce-takeover.md) - a job's route inherits its claim's instance, replacing the ANNOUNCE_TAKEOVER predecessor design - [Subscribe ranges](/quest/m1/subscribe-ranges/README.md) - a lite-07 SUBSCRIBE asks for past and live ranges with absolute or relative ends, in either order, and replaces FETCH; merged ranges never starve a subscriber; relays fill misses by range, including over moq-transport diff --git a/quest/m1/ffi-ietf-run-end.md b/quest/m1/ffi-ietf-run-end.md deleted file mode 100644 index 5daa053b84f..00000000000 --- a/quest/m1/ffi-ietf-run-end.md +++ /dev/null @@ -1,30 +0,0 @@ -# [S] Bindings see a moq-transport run end as an end - -## Goal - -When a moq-transport publisher ends a run, a moq-ffi consumer (Python, Swift, -Kotlin, Go) sees the same kind of end it sees over moq-lite, not -`MoqError.Internal`. A binding can then follow a replaced publisher over -either protocol by error kind, without treating an IETF run's end as fatal. - -## Plan - -Decided 2026-10-31 (maintainer, /quest-plan of the follow-ups from -[moq-dev/moq.pro#3169](https://github.com/moq-dev/moq.pro/pull/3169)). That -PR's Go and Kotlin samples follow a lite run's end, which reaches the FFI as -a protocol reset (`MoqException.Protocol`), but over moq-transport the old -run's catalog ends with a stream reset that decodes as -`moq_net::Error::Remote(0)`. `rs/moq-net/src/error.rs` maps every `Remote(_)` -to `StreamError::Internal`, so the FFI raises `Internal` and the samples stop. - -- First establish what code 0 means on the moq-transport drafts we keep - ([the IETF drop](/quest/m1/ietf-drop/README.md)): a clean end of the - publisher's run, or a real internal error. Only a code that means the run - ended maps to an end; others stay errors. -- Map it in one place (moq-net's `Remote` conversion or the FFI's - `From`), keep the JS consumer consistent, and cover it with a - moq-transport publisher that ends a run under an FFI consumer. -- The broadcast-closed signal itself already shipped on main as - `MoqBroadcastConsumer.closed()` - ([moq-dev/moq#7304](https://github.com/moq-dev/moq/pull/7304)); it reaches - the bindings with the next release, which moq.pro's reader quest adopts. diff --git a/rs/moq-c/src/api.rs b/rs/moq-c/src/api.rs index e669383f31e..763b64a9d99 100644 --- a/rs/moq-c/src/api.rs +++ b/rs/moq-c/src/api.rs @@ -2465,10 +2465,9 @@ pub extern "C" fn moq_publication_free(publication: u32) -> i32 { /// End a broadcast for good and release its handle. /// /// The origin retracts the path immediately and serves no new tracks. Every media, raw track, -/// container, encoder, and JSON handle still open on the broadcast ends with `UNROUTABLE`, -/// the way a reader sees a publisher leave, and is released; finish a track first to end it -/// cleanly. The -/// handles are invalid afterwards, so closing it again fails like any unknown handle, and so +/// container, encoder, and JSON handle still open on the broadcast ends with `UNROUTABLE` +/// (an internal error to a moq-transport reader), and is released; finish a track first to end +/// it cleanly. The handles are invalid afterwards, so closing it again fails like any unknown handle, and so /// does any later call on a released child. /// /// Returns a zero on success, or a negative code on failure. diff --git a/rs/moq-c/src/publish.rs b/rs/moq-c/src/publish.rs index 8b157e5fba9..31b8f557b56 100644 --- a/rs/moq-c/src/publish.rs +++ b/rs/moq-c/src/publish.rs @@ -97,8 +97,8 @@ enum Family { /// The track-publishing handles of one broadcast. /// -/// Closing the broadcast ends every child still open with `Unroutable`, the way a reader sees a -/// publisher leave, and frees its handle. A finished track stops being served once its last +/// Closing the broadcast ends every child still open with `Unroutable` (`Internal` to a +/// moq-transport reader), and frees its handle. A finished track stops being served once its last /// producer drops, and a `*_finish` call frees its handle, so the broadcast keeps the finished /// producer here instead: a subscriber arriving after the end still finds the track until /// [`State::publish_close`]. diff --git a/rs/moq-ffi/src/audio.rs b/rs/moq-ffi/src/audio.rs index 9db217d564e..6570e536f31 100644 --- a/rs/moq-ffi/src/audio.rs +++ b/rs/moq-ffi/src/audio.rs @@ -382,7 +382,7 @@ impl TryFrom for moq_audio::Frame { /// passed at publish time. /// /// Released before its finish, or still open when its broadcast closes, it ends its track with -/// `Unroutable`, which readers take as the publisher leaving. +/// `Unroutable`, which a moq-transport reader sees as `Internal`: its wire has no such code. #[derive(uniffi::Object)] pub struct MoqAudioProducer { inner: std::sync::Mutex>, diff --git a/rs/moq-ffi/src/json.rs b/rs/moq-ffi/src/json.rs index 0deb1e44df8..5be662a8f28 100644 --- a/rs/moq-ffi/src/json.rs +++ b/rs/moq-ffi/src/json.rs @@ -88,7 +88,7 @@ mod tests { /// still reads the cached group first. /// /// Released before its finish, or still open when its broadcast closes, it ends its track with -/// `Unroutable`, which readers take as the publisher leaving. +/// `Unroutable`, which a moq-transport reader sees as `Internal`: its wire has no such code. #[derive(uniffi::Object)] pub struct MoqJsonSnapshotProducer { inner: Arc>>>, @@ -279,7 +279,7 @@ impl MoqJsonSnapshotConsumer { /// Publishes an ordered log of JSON records, one record per append. /// /// Released before its finish, or still open when its broadcast closes, it ends its track with -/// `Unroutable`, which readers take as the publisher leaving. +/// `Unroutable`, which a moq-transport reader sees as `Internal`: its wire has no such code. #[derive(uniffi::Object)] pub struct MoqJsonStreamProducer { inner: std::sync::Mutex>>, @@ -406,7 +406,7 @@ impl MoqJsonStreamConsumer { /// restated in a fresh group, by a task this producer runs until it is finished or dropped. /// /// Released before its finish, or still open when its broadcast closes, it ends its track with -/// `Unroutable`, which readers take as the publisher leaving. +/// `Unroutable`, which a moq-transport reader sees as `Internal`: its wire has no such code. #[derive(uniffi::Object)] pub struct MoqJsonWindowProducer { inner: Arc>>>, diff --git a/rs/moq-ffi/src/media.rs b/rs/moq-ffi/src/media.rs index 923d794dabb..57c3bb1d7ec 100644 --- a/rs/moq-ffi/src/media.rs +++ b/rs/moq-ffi/src/media.rs @@ -895,7 +895,7 @@ struct MediaStreamProducer { /// Imports a container into a broadcast, from chunks split anywhere such as a raw byte stream. /// /// Released before its finish, or still open when its broadcast closes, it ends its tracks with -/// `Unroutable`, which readers take as the publisher leaving. +/// `Unroutable`, which a moq-transport reader sees as `Internal`: its wire has no such code. #[derive(uniffi::Object)] pub struct MoqMediaContainerProducer { driver: crate::ffi::Background, @@ -906,7 +906,7 @@ pub struct MoqMediaContainerProducer { /// Imports complete encoded frames onto one track. /// /// Released before its finish, or still open when its broadcast closes, it ends its track with -/// `Unroutable`, which readers take as the publisher leaving. +/// `Unroutable`, which a moq-transport reader sees as `Internal`: its wire has no such code. #[derive(uniffi::Object)] pub struct MoqMediaTrackProducer { inner: std::sync::Mutex>, @@ -916,7 +916,7 @@ pub struct MoqMediaTrackProducer { /// Imports a video byte stream onto one track. /// /// Released before its finish, or still open when its broadcast closes, it ends its track with -/// `Unroutable`, which readers take as the publisher leaving. +/// `Unroutable`, which a moq-transport reader sees as `Internal`: its wire has no such code. #[derive(uniffi::Object)] pub struct MoqMediaTrackStreamProducer { inner: std::sync::Mutex>, diff --git a/rs/moq-ffi/src/producer.rs b/rs/moq-ffi/src/producer.rs index 59fe0df5703..fc2469d7235 100644 --- a/rs/moq-ffi/src/producer.rs +++ b/rs/moq-ffi/src/producer.rs @@ -374,8 +374,8 @@ impl MoqBroadcastProducer { /// End the broadcast for good: retract it, serve no new tracks, and finalize the catalog. /// - /// Every track handle still open on it ends with `Unroutable`, the way a reader sees a - /// publisher leave, and its later calls fail with `Closed`. Finish a track first to end it + /// Every track handle still open on it ends with `Unroutable` (`Internal` to a moq-transport + /// reader), and its later calls fail with `Closed`. Finish a track first to end it /// cleanly. Every later call on this producer fails with `Closed`; closing again is a no-op. pub fn close(&self) -> Result<(), MoqError> { let _guard = crate::ffi::enter(); @@ -632,7 +632,7 @@ impl MoqTrackRequest { /// A track to which groups, frames, or datagrams can be published. /// /// Released before its finish, or still open when its broadcast closes, it ends its track with -/// `Unroutable`, which readers take as the publisher leaving. +/// `Unroutable`, which a moq-transport reader sees as `Internal`: its wire has no such code. #[derive(uniffi::Object)] pub struct MoqTrackProducer { inner: std::sync::Mutex>, diff --git a/rs/moq-ffi/src/test.rs b/rs/moq-ffi/src/test.rs index 169cc9bdfe0..39cb5a24998 100644 --- a/rs/moq-ffi/src/test.rs +++ b/rs/moq-ffi/src/test.rs @@ -5901,10 +5901,32 @@ fn without_runtime() { #[tokio::test] async fn server_client_roundtrip() { + server_client_run_end("moq-lite-07-wip").await; +} + +#[tokio::test] +async fn server_client_run_end_draft18() { + server_client_run_end("moq-transport-18").await; +} + +#[tokio::test] +async fn server_client_run_end_draft20() { + server_client_run_end("moq-transport-20").await; +} + +#[tokio::test] +async fn server_client_run_end_draft22() { + server_client_run_end("moq-transport-22").await; +} + +/// Finishing content and withdrawing a run are distinct from aborting an open track, and a +/// follower picks up the next run by announcement over every protocol. The aborted track keeps +/// the error its wire carries, so readers follow runs by lifecycle, not by error kind. +async fn server_client_run_end(version: &str) { // Server side: bind, set a publish origin, accept incoming sessions. let server_origin = MoqOriginProducer::new(MoqOriginConfig::default()); let server = MoqServer::new(MoqServerConfig { - versions: vec!["moq-lite-07-wip".into()], + versions: vec![version.into()], bind: Some("127.0.0.1:0".into()), tls: localhost_tls(), publish: Some(server_origin.clone()), @@ -5935,7 +5957,7 @@ async fn server_client_roundtrip() { // Client side: connect, subscribe via a consume origin. let client_origin = MoqOriginProducer::new(MoqOriginConfig::default()); let client = MoqClient::new(MoqClientConfig { - versions: vec!["moq-lite-07-wip".into()], + versions: vec![version.into()], tls: insecure_tls(), bind: Some("127.0.0.1:0".into()), consume: Some(client_origin.clone()), @@ -5969,8 +5991,28 @@ async fn server_client_roundtrip() { let announcement = next_announced(&announced).await; assert_eq!(announcement.prefix, "hello"); - // Subscribe to the audio track and verify a frame round-trips. - let bc = await_announced(&consumer, "hello").await; + // Follow the path as a player does, then subscribe and verify a frame round-trips. + let following = consumer.follow("hello".into(), None).unwrap(); + let bc = kio::clock::timeout(TIMEOUT, following.available()) + .await + .expect("timed out waiting for the first run") + .unwrap(); + let unfinished = broadcast + .publish_track("unfinished".into(), Some(timed_info())) + .unwrap(); + let unfinished_consumer = bc.subscribe_track("unfinished".into(), None).await.unwrap(); + let group = unfinished.create_group(0).unwrap(); + group.write_frame(group_frame(b"still live")).unwrap(); + group.finish().unwrap(); + assert_eq!( + kio::clock::timeout(TIMEOUT, unfinished_consumer.read_frame()) + .await + .expect("unfinished track read timed out") + .unwrap() + .unwrap() + .payload, + b"still live" + ); let catalog_consumer = MoqMediaCatalogConsumer::subscribe(&bc).await.unwrap(); let catalog = kio::clock::timeout(TIMEOUT, catalog_consumer.next()) .await @@ -6007,10 +6049,65 @@ async fn server_client_roundtrip() { assert_eq!(frame.payload, payload); assert_eq!(micros(frame.timestamp), 1_000_000); - // Clean up. Exercise `shutdown()` on the client side and the underlying - // `cancel(code)` on the server side, so both shutdown paths run. media.finish().unwrap(); + assert!( + kio::clock::timeout(TIMEOUT, next_encoded_frame(&media_consumer)) + .await + .expect("media end timed out") + .unwrap() + .is_none(), + "{version}: finished media did not end cleanly" + ); broadcast.close().unwrap(); + let Err(error) = kio::clock::timeout(TIMEOUT, unfinished_consumer.read_frame()) + .await + .expect("unfinished track end timed out") + else { + panic!("withdrawal falsely declared the unfinished track complete"); + }; + if version == "moq-lite-07-wip" { + assert_protocol(&error, crate::error::MoqErrorScope::Stream, MoqProtocolKind::Unroutable); + } else { + // The IETF PUBLISH_DONE registry has no Unroutable, so the publisher sends INTERNAL_ERROR + // and the reader keeps it. Neither TRACK_ENDED nor an EOF fits withdrawn content. + assert!(matches!(error, MoqError::Internal { .. }), "{version}: {error:?}"); + } + while kio::clock::timeout(TIMEOUT, catalog_consumer.next()) + .await + .expect("catalog end timed out") + .unwrap() + .is_some() + {} + kio::clock::timeout(TIMEOUT, bc.closed()) + .await + .expect("broadcast end timed out") + .unwrap(); + + // The announcement, not the track's error, ends the run. + match next_event(&announced).await { + MoqAnnounceEvent::End { announce } => assert_eq!(announce.prefix, "hello"), + other => panic!("{version}: expected the run's end, got {other:?}"), + } + + // A replacement run at the same path reaches the follower on its next `available()`. + let replacement = create_announced(&server_origin, "hello"); + let replacement_media = MoqMediaTrackProducer::audio( + &replacement, + MoqMediaTarget::Named { name: None }, + audio_init(MoqAudioFormat::Opus, opus_head()), + ) + .unwrap(); + let next = kio::clock::timeout(TIMEOUT, following.available()) + .await + .unwrap_or_else(|_| panic!("{version}: the next run was never handed out")) + .unwrap(); + let next_track = subscribe_audio(&next).await; + roundtrip(&replacement_media, &next_track, b"next run", 2_000_000).await; + replacement_media.finish().unwrap(); + replacement.close().unwrap(); + following.cancel(); + + // Exercise both shutdown paths after content ended with the session still open. cs.shutdown(); cs.closed().await.unwrap(); server_session.cancel(0); diff --git a/rs/moq-ffi/src/video.rs b/rs/moq-ffi/src/video.rs index e81b086fabc..e5e43380d16 100644 --- a/rs/moq-ffi/src/video.rs +++ b/rs/moq-ffi/src/video.rs @@ -499,7 +499,7 @@ impl VideoProducer { /// pixel format declared by the [`MoqVideoEncoderInput`] passed at publish time. /// /// Released before its finish, or still open when its broadcast closes, it ends its track with -/// `Unroutable`, which readers take as the publisher leaving. +/// `Unroutable`, which a moq-transport reader sees as `Internal`: its wire has no such code. #[derive(uniffi::Object)] pub struct MoqVideoProducer { inner: Arc>>, diff --git a/swift/Sources/Moq/Broadcast.swift b/swift/Sources/Moq/Broadcast.swift index 5cec9e7dc11..db36dfc9449 100644 --- a/swift/Sources/Moq/Broadcast.swift +++ b/swift/Sources/Moq/Broadcast.swift @@ -87,9 +87,9 @@ public final class BroadcastProducer: Sendable { /// End the broadcast for good: retract it and serve no new tracks. /// - /// Tracks still open on it end with `Unroutable`, which readers take as the publisher - /// leaving, and their later calls throw `MoqError.Closed`; finish a track first to end it - /// cleanly. Closing again is a no-op. + /// Tracks still open on it end with `Unroutable` (`Internal` to a moq-transport reader), + /// and their later calls throw `MoqError.Closed`; finish a track first to end it cleanly. + /// Closing again is a no-op. public func close() throws { try ffi.close() }