From 928efb3c6820724c9fea3296a02005772a3f44c4 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sat, 31 Oct 2026 22:31:27 -0700 Subject: [PATCH 1/5] chore(quest): claim quest/m1/ffi-ietf-run-end.md Quest-Claim: 7719874c06f60ee8 From 9c886cbb82a1602f1f658226bf385428d5a8da56 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sat, 31 Oct 2026 22:35:59 -0700 Subject: [PATCH 2/5] test(ffi): prove publisher run ends on retained IETF drafts Co-Authored-By: GPT-6.1 Sol --- quest/m1/README.md | 1 - quest/m1/ffi-ietf-run-end.md | 30 ------------------------------ 2 files changed, 31 deletions(-) delete mode 100644 quest/m1/ffi-ietf-run-end.md diff --git a/quest/m1/README.md b/quest/m1/README.md index 0b06ea53230..b6c93459945 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -132,7 +132,6 @@ removed). - [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 - [Lite-05/06 timestamps pass through](/quest/m1/lite-timestamps-through.md) - a timed track received over lite-05/06 stays timed and is forwarded with its timestamps over every version - [Exact timestamps in every binding](/quest/m1/binding-timestamps.md) - bindings carry `{value, scale}` timestamps instead of lossy microseconds -- [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` - [A broadcast stamps everything from one clock](/quest/m1/broadcast-clock.md) - catalog, MSF, and HLS record groups are stamped from the broadcast's clock, never the ambient one - [A job's exact route continues its claim's readers](/quest/m1/announce-takeover.md) - a job's route inherits its claim's identity, 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. From de6bc9a9db170e844487435455ceb419ea143a37 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sat, 31 Oct 2026 22:36:05 -0700 Subject: [PATCH 3/5] test(ffi): cover clean and failed ends over live sessions Co-Authored-By: GPT-6.1 Sol --- rs/moq-ffi/src/test.rs | 67 +++++++++++++++++++++++++++++++++++++++--- 1 file changed, 63 insertions(+), 4 deletions(-) diff --git a/rs/moq-ffi/src/test.rs b/rs/moq-ffi/src/test.rs index fd119bcfa2a..88af14ec6cd 100644 --- a/rs/moq-ffi/src/test.rs +++ b/rs/moq-ffi/src/test.rs @@ -5727,10 +5727,30 @@ 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. +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()), @@ -5761,7 +5781,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()), @@ -5797,6 +5817,20 @@ async fn server_client_roundtrip() { // Subscribe to the audio track and verify a frame round-trips. let bc = await_announced(&consumer, "hello").await; + let unfinished = broadcast + .publish_track("unfinished".into(), Some(timed_info())) + .unwrap(); + let unfinished_consumer = bc.subscribe_track("unfinished".into(), None).await.unwrap(); + unfinished.write_frame(group_frame(b"still live")).unwrap(); + assert_eq!( + moq_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 = moq_clock::timeout(TIMEOUT, catalog_consumer.next()) .await @@ -5833,10 +5867,35 @@ async fn server_client_roundtrip() { assert_eq!(frame.payload, payload); assert_eq!(frame.timestamp_us, 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!( + moq_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(); + assert!( + moq_clock::timeout(TIMEOUT, unfinished_consumer.read_frame()) + .await + .expect("unfinished track end timed out") + .is_err(), + "{version}: withdrawal falsely declared the unfinished track complete" + ); + while moq_clock::timeout(TIMEOUT, catalog_consumer.next()) + .await + .expect("catalog end timed out") + .unwrap() + .is_some() + {} + moq_clock::timeout(TIMEOUT, bc.closed()) + .await + .expect("broadcast end timed out") + .unwrap(); + + // Exercise both shutdown paths after content ended with the session still open. cs.shutdown(); cs.closed().await.unwrap(); server_session.cancel(0); From 9d9e9fa055ce566ca6344260e6eed0790ab77bfc Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sat, 31 Oct 2026 22:41:22 -0700 Subject: [PATCH 4/5] test(ffi): reproduce unfinished IETF run error kinds Keep the quest open for a publisher-side mapping or lifecycle decision. Stream reset zero cannot safely be decoded as an end. Co-Authored-By: GPT-6.1 Sol --- quest/m1/README.md | 1 + quest/m1/ffi-ietf-run-end.md | 43 ++++++++++++++++++++++++++++++++++++ rs/moq-ffi/src/test.rs | 24 +++++++++++++------- 3 files changed, 60 insertions(+), 8 deletions(-) create mode 100644 quest/m1/ffi-ietf-run-end.md diff --git a/quest/m1/README.md b/quest/m1/README.md index b6c93459945..0b06ea53230 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -132,6 +132,7 @@ removed). - [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 - [Lite-05/06 timestamps pass through](/quest/m1/lite-timestamps-through.md) - a timed track received over lite-05/06 stays timed and is forwarded with its timestamps over every version - [Exact timestamps in every binding](/quest/m1/binding-timestamps.md) - bindings carry `{value, scale}` timestamps instead of lossy microseconds +- [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` - [A broadcast stamps everything from one clock](/quest/m1/broadcast-clock.md) - catalog, MSF, and HLS record groups are stamped from the broadcast's clock, never the ambient one - [A job's exact route continues its claim's readers](/quest/m1/announce-takeover.md) - a job's route inherits its claim's identity, 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 new file mode 100644 index 00000000000..e0de0f945d9 --- /dev/null +++ b/quest/m1/ffi-ietf-run-end.md @@ -0,0 +1,43 @@ +# [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 unfinished track becomes `MoqError.Internal` and the samples stop. + +The broadcast-closed signal 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. + +Investigation 2026-10-31: stream reset 0 means INTERNAL_ERROR, not a normal +end, on retained drafts [18 section 3.3.3](https://datatracker.ietf.org/doc/html/draft-ietf-moq-transport-18#section-3.3.3), +[20 section 3.3.4](https://datatracker.ietf.org/doc/html/draft-ietf-moq-transport-20#section-3.3.4), +and [22 section 12.5](https://datatracker.ietf.org/doc/html/draft-ietf-moq-transport-22#section-12.5). +Cancellation is 1. PUBLISH_DONE has a separate registry: TRACK_ENDED is 2, +and 0 is INTERNAL_ERROR there too. Incoming 0 must remain an error. + +The current FFI publisher already finishes its catalog cleanly on close. +Live-session FFI tests now cover media EOF, catalog EOF, broadcast closure, +and an unfinished track on lite-07 and all retained IETF drafts. The unfinished +track still reproduces the divergence: lite reports Protocol/Unroutable; +IETF's publisher maps Unroutable to PUBLISH_DONE/INTERNAL_ERROR, which arrives +as Remote(0) and becomes MoqError.Internal. Group resets lose the cause too. +No retained draft has an Unroutable code in either registry. + +Remaining decision: preserve the wire's errors and use broadcast lifecycle +signals to follow runs (recommended, consistent with announcement-driven +restart), or choose a publisher-side cancellation mapping for route loss in +Rust and JS. Neither TRACK_ENDED nor decoding 0 as EOF is correct for +unfinished content. Do not select a wire mapping without the maintainer's +decision. diff --git a/rs/moq-ffi/src/test.rs b/rs/moq-ffi/src/test.rs index 88af14ec6cd..1ac63099451 100644 --- a/rs/moq-ffi/src/test.rs +++ b/rs/moq-ffi/src/test.rs @@ -5821,7 +5821,9 @@ async fn server_client_run_end(version: &str) { .publish_track("unfinished".into(), Some(timed_info())) .unwrap(); let unfinished_consumer = bc.subscribe_track("unfinished".into(), None).await.unwrap(); - unfinished.write_frame(group_frame(b"still live")).unwrap(); + let group = unfinished.create_group(0).unwrap(); + group.write_frame(group_frame(b"still live")).unwrap(); + group.finish().unwrap(); assert_eq!( moq_clock::timeout(TIMEOUT, unfinished_consumer.read_frame()) .await @@ -5877,13 +5879,19 @@ async fn server_client_run_end(version: &str) { "{version}: finished media did not end cleanly" ); broadcast.close().unwrap(); - assert!( - moq_clock::timeout(TIMEOUT, unfinished_consumer.read_frame()) - .await - .expect("unfinished track end timed out") - .is_err(), - "{version}: withdrawal falsely declared the unfinished track complete" - ); + let Err(error) = moq_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 cannot carry Unroutable, so the publisher sends + // INTERNAL_ERROR. This is the remaining run-end divergence, not a clean EOF. + assert!(matches!(error, MoqError::Internal { .. }), "{version}: {error:?}"); + } while moq_clock::timeout(TIMEOUT, catalog_consumer.next()) .await .expect("catalog end timed out") From 14a2271d5d23e1efeb8b4cd381b17d0ce8fa569e Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sun, 1 Nov 2026 10:34:52 -0800 Subject: [PATCH 5/5] fix(ffi): follow publisher runs by lifecycle, keeping wire errors A track withdrawn unfinished keeps the error its wire carries: Unroutable over moq-lite, INTERNAL_ERROR over moq-transport, which has no code for it. Readers follow runs by announcement instead. The live FFI run-end test now follows the path on lite-07 and IETF drafts 18, 20, and 22, sees the announcement end, and picks up a replacement run from the next available(). Drop the doc claim that readers take Unroutable as the publisher leaving, and finish the ffi-ietf-run-end quest. Co-Authored-By: Claude Opus 5.5 --- dart/moq_ffi/lib/src/moq.dart | 2 +- doc/concept/identity.md | 9 ++++-- doc/lib/c/index.md | 2 +- doc/lib/cpp/index.md | 5 ++-- doc/lib/dart/index.md | 2 +- doc/lib/go/index.md | 2 +- doc/lib/kt/index.md | 2 +- doc/lib/py/index.md | 2 +- doc/lib/swift/index.md | 2 +- go/wrapper/publish.go | 6 ++-- py/moq-rs/moq/publish.py | 6 ++-- quest/m1/README.md | 1 - quest/m1/ffi-ietf-run-end.md | 43 -------------------------- rs/moq-c/src/api.rs | 7 ++--- rs/moq-c/src/publish.rs | 4 +-- rs/moq-ffi/src/audio.rs | 2 +- rs/moq-ffi/src/json.rs | 6 ++-- rs/moq-ffi/src/media.rs | 6 ++-- rs/moq-ffi/src/producer.rs | 6 ++-- rs/moq-ffi/src/test.rs | 50 ++++++++++++++++++++++++------- rs/moq-ffi/src/video.rs | 2 +- swift/Sources/Moq/Broadcast.swift | 6 ++-- 22 files changed, 81 insertions(+), 92 deletions(-) delete mode 100644 quest/m1/ffi-ietf-run-end.md diff --git a/dart/moq_ffi/lib/src/moq.dart b/dart/moq_ffi/lib/src/moq.dart index 64ecbf455ab..90a36c19cd8 100644 --- a/dart/moq_ffi/lib/src/moq.dart +++ b/dart/moq_ffi/lib/src/moq.dart @@ -21369,7 +21369,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 3b97e804373..0148f43dbcb 100644 --- a/doc/concept/identity.md +++ b/doc/concept/identity.md @@ -81,11 +81,14 @@ Choose between two kinds of reader. **Follow announcements** when the reader should outlive any one publisher run, as a player does. Start on each instance, 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`, +`consumer.follow(path, None)` (or `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. +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 instance** when the output must not splice two runs, as an exporter or recorder does. Rust and JavaScript diff --git a/doc/lib/c/index.md b/doc/lib/c/index.md index f8c2b4f62c2..6f04ed8b0d3 100644 --- a/doc/lib/c/index.md +++ b/doc/lib/c/index.md @@ -104,7 +104,7 @@ inside. The header is the reference: each function carries a doc comment. - **fMP4 import.** `MOQ_CONTAINER_FORMAT_FMP4` splits each fragment into one frame per sample. - **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`. -- **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. - **JSON values.** `moq_consume_json_value` fills `moq_json_value` with the document and its frame's `timestamp_us`, rounded down to a whole microsecond; `timestamp_present` is false on an untimed track. A snapshot consumer's callback fires for each state in order, but a group superseded before it is read is skipped. - **JSON windows.** `moq_publish_json_window` publishes a sliding run of records: `moq_publish_json_window_push` appends at the back, `moq_publish_json_window_pop` drops from the front, and `moq_publish_json_window_cut` closes the open group at a natural boundary. The catalog has no window mode, so a reader names the track. `moq_consume_json_window_event` fills `moq_json_window_event` with a push (the record at `start`, in `json`), a pop of `[start, end)`, or a skip of `[start, end)` that this reader joined too late to receive. Set `checkpoint_records` to bound what each new group restates for a window you never pop. diff --git a/doc/lib/cpp/index.md b/doc/lib/cpp/index.md index 51c6c21f214..76cb6f881a4 100644 --- a/doc/lib/cpp/index.md +++ b/doc/lib/cpp/index.md @@ -242,8 +242,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 3de97e2603e..63ad8deab4c 100644 --- a/doc/lib/dart/index.md +++ b/doc/lib/dart/index.md @@ -150,7 +150,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. Application delivery requires explicitly selecting `moq-lite-07-wip` on both peers; older Lite versions (including default lite-06) 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 daf44b06e13..1ce4b4e57bd 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. Application delivery requires explicitly selecting `moq-lite-07-wip` on both peers; older Lite versions (including default lite-06) 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 d6d2b9d35da..cdf52b7ea1e 100644 --- a/doc/lib/kt/index.md +++ b/doc/lib/kt/index.md @@ -106,7 +106,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. Application delivery requires explicitly selecting `moq-lite-07-wip` on both peers; older Lite versions (including default lite-06) 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 cbd2f82acf0..ca4b77f46b3 100644 --- a/doc/lib/py/index.md +++ b/doc/lib/py/index.md @@ -122,7 +122,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. Application delivery requires explicitly selecting `moq-lite-07-wip` on both peers; older Lite versions (including default lite-06) 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 21b9195faf8..d70829713b4 100644 --- a/doc/lib/swift/index.md +++ b/doc/lib/swift/index.md @@ -105,7 +105,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. Application delivery requires explicitly selecting `moq-lite-07-wip` on both peers; older Lite versions (including default lite-06) 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 a179024d830..75a092f250d 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 1dd057f7f0b..2c7e5904e7c 100644 --- a/py/moq-rs/moq/publish.py +++ b/py/moq-rs/moq/publish.py @@ -358,8 +358,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 dfde045a690..63750ae89c8 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -130,7 +130,6 @@ removed). - [Routing guide](/quest/m1/routing-guide.md) - concepts and practical outbound federation setup - [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 - [Exact timestamps in every binding](/quest/m1/binding-timestamps.md) - bindings carry `{value, scale}` timestamps instead of lossy microseconds -- [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` - [A broadcast stamps everything from one clock](/quest/m1/broadcast-clock.md) - catalog, MSF, and HLS record groups are stamped from the broadcast's clock, never the ambient one - [A job's exact route continues its claim's readers](/quest/m1/announce-takeover.md) - a job's route inherits its claim's identity, 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 e0de0f945d9..00000000000 --- a/quest/m1/ffi-ietf-run-end.md +++ /dev/null @@ -1,43 +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 unfinished track becomes `MoqError.Internal` and the samples stop. - -The broadcast-closed signal 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. - -Investigation 2026-10-31: stream reset 0 means INTERNAL_ERROR, not a normal -end, on retained drafts [18 section 3.3.3](https://datatracker.ietf.org/doc/html/draft-ietf-moq-transport-18#section-3.3.3), -[20 section 3.3.4](https://datatracker.ietf.org/doc/html/draft-ietf-moq-transport-20#section-3.3.4), -and [22 section 12.5](https://datatracker.ietf.org/doc/html/draft-ietf-moq-transport-22#section-12.5). -Cancellation is 1. PUBLISH_DONE has a separate registry: TRACK_ENDED is 2, -and 0 is INTERNAL_ERROR there too. Incoming 0 must remain an error. - -The current FFI publisher already finishes its catalog cleanly on close. -Live-session FFI tests now cover media EOF, catalog EOF, broadcast closure, -and an unfinished track on lite-07 and all retained IETF drafts. The unfinished -track still reproduces the divergence: lite reports Protocol/Unroutable; -IETF's publisher maps Unroutable to PUBLISH_DONE/INTERNAL_ERROR, which arrives -as Remote(0) and becomes MoqError.Internal. Group resets lose the cause too. -No retained draft has an Unroutable code in either registry. - -Remaining decision: preserve the wire's errors and use broadcast lifecycle -signals to follow runs (recommended, consistent with announcement-driven -restart), or choose a publisher-side cancellation mapping for route loss in -Rust and JS. Neither TRACK_ENDED nor decoding 0 as EOF is correct for -unfinished content. Do not select a wire mapping without the maintainer's -decision. diff --git a/rs/moq-c/src/api.rs b/rs/moq-c/src/api.rs index 16800ceca47..1a6e8038731 100644 --- a/rs/moq-c/src/api.rs +++ b/rs/moq-c/src/api.rs @@ -2487,10 +2487,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 0f2bf7defb7..dd0e6783f4d 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 f0cd65ff311..f0fb27fa810 100644 --- a/rs/moq-ffi/src/audio.rs +++ b/rs/moq-ffi/src/audio.rs @@ -393,7 +393,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 7efb874fc37..529aca50cad 100644 --- a/rs/moq-ffi/src/json.rs +++ b/rs/moq-ffi/src/json.rs @@ -87,7 +87,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>>>, @@ -280,7 +280,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>>, @@ -407,7 +407,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 3da7421872b..a74a032d8e1 100644 --- a/rs/moq-ffi/src/media.rs +++ b/rs/moq-ffi/src/media.rs @@ -853,7 +853,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, @@ -864,7 +864,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>, @@ -874,7 +874,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 db3e02b6c2d..64f4db82524 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 ffe771229d9..a1fe58363be 100644 --- a/rs/moq-ffi/src/test.rs +++ b/rs/moq-ffi/src/test.rs @@ -5761,7 +5761,9 @@ 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. +/// 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()); @@ -5831,8 +5833,12 @@ async fn server_client_run_end(version: &str) { 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(); @@ -5841,7 +5847,7 @@ async fn server_client_run_end(version: &str) { group.write_frame(group_frame(b"still live")).unwrap(); group.finish().unwrap(); assert_eq!( - moq_clock::timeout(TIMEOUT, unfinished_consumer.read_frame()) + kio::clock::timeout(TIMEOUT, unfinished_consumer.read_frame()) .await .expect("unfinished track read timed out") .unwrap() @@ -5887,7 +5893,7 @@ async fn server_client_run_end(version: &str) { media.finish().unwrap(); assert!( - moq_clock::timeout(TIMEOUT, next_encoded_frame(&media_consumer)) + kio::clock::timeout(TIMEOUT, next_encoded_frame(&media_consumer)) .await .expect("media end timed out") .unwrap() @@ -5895,7 +5901,7 @@ async fn server_client_run_end(version: &str) { "{version}: finished media did not end cleanly" ); broadcast.close().unwrap(); - let Err(error) = moq_clock::timeout(TIMEOUT, unfinished_consumer.read_frame()) + let Err(error) = kio::clock::timeout(TIMEOUT, unfinished_consumer.read_frame()) .await .expect("unfinished track end timed out") else { @@ -5904,21 +5910,45 @@ async fn server_client_run_end(version: &str) { if version == "moq-lite-07-wip" { assert_protocol(&error, crate::error::MoqErrorScope::Stream, MoqProtocolKind::Unroutable); } else { - // The IETF PUBLISH_DONE registry cannot carry Unroutable, so the publisher sends - // INTERNAL_ERROR. This is the remaining run-end divergence, not a clean EOF. + // 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 moq_clock::timeout(TIMEOUT, catalog_consumer.next()) + while kio::clock::timeout(TIMEOUT, catalog_consumer.next()) .await .expect("catalog end timed out") .unwrap() .is_some() {} - moq_clock::timeout(TIMEOUT, bc.closed()) + 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(); diff --git a/rs/moq-ffi/src/video.rs b/rs/moq-ffi/src/video.rs index 6dafb4fc784..369df0a8275 100644 --- a/rs/moq-ffi/src/video.rs +++ b/rs/moq-ffi/src/video.rs @@ -498,7 +498,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 49dcd773699..887d1fcc6a7 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() }