From 709e0206663231b1f398025ca6654b45178fe45a Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Thu, 22 Oct 2026 18:17:52 -0700 Subject: [PATCH 1/4] chore(quest): claim quest/m1/ffi-shutdown-sync.md Quest-Claim: 218c559c5bf0b025 From 6473077d6180ddad848c1d243acf882af6c40e2c Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Thu, 22 Oct 2026 18:54:17 -0700 Subject: [PATCH 2/4] fix(ffi): own draining shutdown requests synchronously Co-Authored-By: GPT-6 --- cpp/moq/MIGRATE.md | 5 + cpp/obs/MIGRATE.md | 5 + cpp/obs/src/moq-output.cpp | 26 +--- cpp/obs/src/moq-output.h | 4 - dart/moq/MIGRATE.md | 5 + dart/moq/lib/src/client.dart | 3 +- dart/moq_ffi/MIGRATE.md | 5 + dart/moq_ffi/lib/src/moq.dart | 33 ++--- dart/moq_ffi/lib/src/uniffi_runtime.dart | 2 + doc/bin/obs.md | 2 +- doc/lib/c/index.md | 2 +- doc/lib/cpp/index.md | 2 +- doc/lib/dart/index.md | 2 +- doc/lib/go/index.md | 2 +- doc/lib/kt/index.md | 3 +- doc/lib/py/index.md | 2 +- doc/lib/swift/index.md | 5 +- go/ffi/MIGRATE.md | 5 + go/wrapper/MIGRATE.md | 5 + go/wrapper/client.go | 3 +- go/wrapper/session.go | 16 +-- kt/moq-ffi/MIGRATE.md | 5 + kt/moq/MIGRATE.md | 5 + .../jvmAndAndroidMain/kotlin/dev/moq/Moq.kt | 12 +- py/moq-ffi/MIGRATE.md | 5 + py/moq-rs/MIGRATE.md | 5 + py/moq-rs/README.md | 2 +- py/moq-rs/moq/client.py | 3 +- py/moq-rs/moq/session.py | 14 +- quest/m0/ffi-shutdown-backport.md | 8 +- quest/m1/README.md | 1 - quest/m1/api-audit/migrate.md | 9 +- quest/m1/ffi-shutdown-sync.md | 41 ------ rs/moq-c/MIGRATE.md | 5 + rs/moq-c/src/session.rs | 6 +- rs/moq-c/src/test.rs | 30 ++++- rs/moq-ffi/MIGRATE.md | 5 + rs/moq-ffi/src/error.rs | 2 +- rs/moq-ffi/src/session.rs | 109 +++++++++++----- rs/moq-ffi/src/test.rs | 120 +++++++++++++++++- swift/MIGRATE.md | 7 +- swift/README.md | 5 +- swift/Sources/Moq/Client.swift | 9 +- swift/ffi/MIGRATE.md | 5 + test/interop/clients/cpp/main.cpp | 6 +- 45 files changed, 380 insertions(+), 176 deletions(-) delete mode 100644 quest/m1/ffi-shutdown-sync.md diff --git a/cpp/moq/MIGRATE.md b/cpp/moq/MIGRATE.md index e128eb16e37..4836cd6cb71 100644 --- a/cpp/moq/MIGRATE.md +++ b/cpp/moq/MIGRATE.md @@ -4,6 +4,11 @@ How to update your code for each breaking change, newest first. ## Unreleased +### Shutdown requests the drain synchronously + +`session->shutdown()` returns `void` and requests the drain synchronously. Use `session->closed().get()` to wait and report delivery failures, or `session->cancel(0)` to cancel immediately. A shutdown request survives session disposal and discarded waiters. +When upgrading from the release-line additive async `drain()` backport, replace `session->drain().get()` with `session->shutdown(); session->closed().get()`; `main` has no separate `drain()` method. + ### Priorities are signed (#6142) `TrackInfo::priority`, `Subscription::priority`, and `FetchGroupOptions::priority` are `int8_t`, and `GroupRequest::priority()` returns one. diff --git a/cpp/obs/MIGRATE.md b/cpp/obs/MIGRATE.md index 398682fc872..f1edc7a4215 100644 --- a/cpp/obs/MIGRATE.md +++ b/cpp/obs/MIGRATE.md @@ -4,6 +4,11 @@ How to update your OBS setup for each breaking change, newest first. ## Unreleased +### Shutdown requests the drain synchronously + +Stopping an output requests an owned native drain; output destruction no longer retains or waits on shutdown futures. Finished tracks still drain after the output is disposed. Wait on a session's `closed()` before global runtime shutdown when its result is needed. +When upgrading from the release-line additive async `drain()` backport, replace an async session `drain()` with synchronous `shutdown()` followed by `closed()`; `main` has no separate `drain()` method. + ### Key logging is opt-in (#5907) `SSLKEYLOGFILE` alone no longer writes TLS session secrets. diff --git a/cpp/obs/src/moq-output.cpp b/cpp/obs/src/moq-output.cpp index b6e12385428..2f114dcf117 100644 --- a/cpp/obs/src/moq-output.cpp +++ b/cpp/obs/src/moq-output.cpp @@ -103,16 +103,6 @@ MoQOutput::~MoQOutput() // stop on an output that is going away. Stop(); - // Let the sessions finish draining, so the relay sees the tracks end rather than a - // cancel. moq-ffi bounds each drain to about a second. - std::vector> drains; - { - std::lock_guard signal_lock(signal_mutex); - drains.swap(draining); - } - for (auto &drain : drains) - drain.wait(); - // Drops whatever is still queued and waits out a continuation in flight, which // may be parked on signal_mutex; so this must not hold it. Nothing touches this // object once it returns. @@ -445,18 +435,10 @@ void MoQOutput::Reset() broadcast.reset(); origin.reset(); - // Drain once tracks finish. Default lite-06 waits for transport ACKs, not - // confirmation that the peer received the tail. Keep the future past this - // attempt because dropping it aborts the drain. - if (retired) { - draining.erase(std::remove_if(draining.begin(), draining.end(), - [](const moq::Future &drain) { - return drain.wait_for(std::chrono::seconds(0)) == - std::future_status::ready; - }), - draining.end()); - draining.push_back(retired->shutdown()); - } + // The session owns the drain after this request, even if the output dies now. + if (retired) + retired->shutdown(); + lock.unlock(); for (auto &[encoder, bitrate] : restore) diff --git a/cpp/obs/src/moq-output.h b/cpp/obs/src/moq-output.h index 230dcbb5d1e..d1421e6cf98 100644 --- a/cpp/obs/src/moq-output.h +++ b/cpp/obs/src/moq-output.h @@ -201,10 +201,6 @@ class MoQOutput { // read empty while disconnected and resume on the next connection. std::shared_ptr bandwidth; - // Retired sessions still draining their finished tracks, which the destructor - // waits out. Guarded by signal_mutex. - std::vector> draining; - std::string path; size_t total_bytes_sent; diff --git a/dart/moq/MIGRATE.md b/dart/moq/MIGRATE.md index d466a24a91f..6eccab73caa 100644 --- a/dart/moq/MIGRATE.md +++ b/dart/moq/MIGRATE.md @@ -4,6 +4,11 @@ How to update your code for each breaking change, newest first. ## Unreleased +### Shutdown requests the drain synchronously + +`session.shutdown()` requests a drain synchronously; `await session.closed()` waits for its result. `Moq.close()` returns `Future` and drains before stopping the client, so await it. Use `session.cancel(code: 0)` for immediate cancellation. +When upgrading from the release-line additive async `drain()` backport, replace `await session.drain()` with `session.shutdown(); await session.closed()`; `main` has no separate `drain()` method. + ### JSON snapshot `deltaRatio` is `deltas` `SnapshotConfig.deltaRatio` is replaced by `bool deltas` (default `true`). diff --git a/dart/moq/lib/src/client.dart b/dart/moq/lib/src/client.dart index c8d069dac90..e11781c8277 100644 --- a/dart/moq/lib/src/client.dart +++ b/dart/moq/lib/src/client.dart @@ -268,7 +268,8 @@ final class Moq { /// IETF also waits for transport ACKs. Future close() async { try { - await session.shutdown(); + session.shutdown(); + await session.closed(); } finally { _client.cancel(); } diff --git a/dart/moq_ffi/MIGRATE.md b/dart/moq_ffi/MIGRATE.md index 8df537cb61c..ab6e9f2348a 100644 --- a/dart/moq_ffi/MIGRATE.md +++ b/dart/moq_ffi/MIGRATE.md @@ -4,6 +4,11 @@ How to update your code for each breaking change, newest first. ## Unreleased +### Shutdown requests the drain synchronously + +`shutdown()` requests a drain synchronously; `await closed()` waits for its result and reports delivery failures. Regenerate bindings and link the matching native library together. See the [core migration guide](https://github.com/moq-dev/moq/blob/main/rs/moq-ffi/MIGRATE.md) for the core contract. +When upgrading from the release-line additive async `drain()` backport, replace the release-line async `drain()` with `shutdown()` followed by `await closed()`; `main` has no separate `drain()` method. + ### Priorities are signed (#6142) `MoqTrackInfo.priority`, `MoqSubscription.priority`, `MoqFetchGroupOptions.priority`, and `MoqGroupRequest.priority()` take `-128..=127`, higher first, and 0 is the unset midpoint. diff --git a/dart/moq_ffi/lib/src/moq.dart b/dart/moq_ffi/lib/src/moq.dart index f530ade4eea..83f8b91b618 100644 --- a/dart/moq_ffi/lib/src/moq.dart +++ b/dart/moq_ffi/lib/src/moq.dart @@ -8,7 +8,9 @@ import "dart:ffi"; import "dart:io" show Platform, File, Directory; import "dart:isolate"; import "dart:typed_data"; + import "package:ffi/ffi.dart"; + import "uniffi_runtime.dart"; export "uniffi_runtime.dart"; @@ -12572,7 +12574,7 @@ abstract class MoqSessionInterface { MoqException? failure(); MoqOriginProducer publish(); MoqBandwidthConsumer? recvBandwidth(); - Future shutdown(); + void shutdown(); MoqConnectionStats stats(); Future status(); } @@ -12706,15 +12708,13 @@ class MoqSession implements MoqSessionInterface { ); } - Future shutdown() { - return uniffiRustCallAsync( - () => uniffi_moq_ffi_fn_method_moqsession_shutdown(uniffiClonePointer()), - ffi_moq_ffi_rust_future_poll_void, - ffi_moq_ffi_rust_future_complete_void, - ffi_moq_ffi_rust_future_free_void, - (_) {}, - moqExceptionErrorHandler, - ); + void shutdown() { + return rustCall((status) { + uniffi_moq_ffi_fn_method_moqsession_shutdown( + uniffiClonePointer(), + status, + ); + }, null); } MoqConnectionStats stats() { @@ -17951,9 +17951,12 @@ external RustBuffer uniffi_moq_ffi_fn_method_moqsession_recv_bandwidth( Pointer uniffiStatus, ); -@Native Function(Pointer)>(assetId: _uniffiAssetId) -external Pointer uniffi_moq_ffi_fn_method_moqsession_shutdown( +@Native, Pointer)>( + assetId: _uniffiAssetId, +) +external void uniffi_moq_ffi_fn_method_moqsession_shutdown( Pointer ptr, + Pointer uniffiStatus, ); @Native, Pointer)>( @@ -19802,7 +19805,7 @@ void _checkApiChecksums() { if (uniffi_moq_ffi_checksum_method_moqsession_cancel() != 39476) { throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); } - if (uniffi_moq_ffi_checksum_method_moqsession_closed() != 7901) { + if (uniffi_moq_ffi_checksum_method_moqsession_closed() != 20675) { throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); } if (uniffi_moq_ffi_checksum_method_moqsession_connects() != 18791) { @@ -19820,13 +19823,13 @@ void _checkApiChecksums() { if (uniffi_moq_ffi_checksum_method_moqsession_recv_bandwidth() != 46568) { throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); } - if (uniffi_moq_ffi_checksum_method_moqsession_shutdown() != 1301) { + if (uniffi_moq_ffi_checksum_method_moqsession_shutdown() != 32451) { throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); } if (uniffi_moq_ffi_checksum_method_moqsession_stats() != 36396) { throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); } - if (uniffi_moq_ffi_checksum_method_moqsession_status() != 49725) { + if (uniffi_moq_ffi_checksum_method_moqsession_status() != 22056) { throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); } if (uniffi_moq_ffi_checksum_method_moqvideoconsumer_cancel() != 21122) { diff --git a/dart/moq_ffi/lib/src/uniffi_runtime.dart b/dart/moq_ffi/lib/src/uniffi_runtime.dart index ab87a64ed3f..1eefdf6293d 100644 --- a/dart/moq_ffi/lib/src/uniffi_runtime.dart +++ b/dart/moq_ffi/lib/src/uniffi_runtime.dart @@ -8,6 +8,7 @@ import "dart:ffi"; import "dart:io" show Platform, File, Directory; import "dart:isolate"; import "dart:typed_data"; + import "package:ffi/ffi.dart"; class UniffiInternalError implements Exception { @@ -247,6 +248,7 @@ mixin FfiConverterPrimitive on FfiConverter { @override T lower(T value) => value; } + Uint8List createUint8ListFromInt(int value) { int length = value.bitLength ~/ 8 + 1; if (length != 4 && length != 8) { diff --git a/doc/bin/obs.md b/doc/bin/obs.md index 5bce66618d5..82a59bc1134 100644 --- a/doc/bin/obs.md +++ b/doc/bin/obs.md @@ -95,7 +95,7 @@ alone writes nothing, and the toggle without it fails the connection. The plugin is C++ over the [generated C++ bindings](/lib/cpp/) and ships with every moq-cpp release. Stopping finishes the tracks and drains for up to one -second. The default lite-06 waits for transport ACKs, which do not confirm that +second. The native runtime owns the drain even when the output is destroyed. The default lite-06 waits for transport ACKs, which do not confirm that the peer received the tail. If the relay closes the session for too many requests, reduce the broadcasts diff --git a/doc/lib/c/index.md b/doc/lib/c/index.md index 19d163948b2..7cd51edc690 100644 --- a/doc/lib/c/index.md +++ b/doc/lib/c/index.md @@ -58,7 +58,7 @@ here, from media publish and consume to raw pixels and PCM with the codec inside. The header is the reference: each function carries a doc comment. [Layers](/lib/layers) maps each wrapped Rust layer to its function prefixes. -- **Handles and callbacks.** Every object is an integer handle, and every async result arrives on a `moq_status_callback` with your `void *user_data`. A status `> 0` is a live result, `0` a clean close, and `< 0` an error. The last two are terminal: moq-c never touches `user_data` again, so free it there. `*_close` and `*_cancel` only request shutdown; the terminal callback still fires. +- **Handles and callbacks.** Every object is an integer handle, and every async result arrives on a `moq_status_callback` with your `void *user_data`. A status `> 0` is a live result, `0` a clean close, and `< 0` an error. The last two are terminal: moq-c never touches `user_data` again, so free it there. `*_close` and `*_cancel` only request shutdown; the terminal callback still fires. `moq_session_close()` drains finished tracks for dialed and accepted sessions; wait for its terminal callback to learn the result. - **Errors.** Negative return codes are named by `MOQ_ERROR_*`, and `moq_error()` gives the reason on the calling thread. Auth rejections have their own codes so you don't retry them. For the peer's protocol code use `moq_error_protocol()`; do not parse `moq_error()`. A panic in a binding background task reports `MOQ_ERROR_PANIC` through its terminal callback; unrelated objects keep running. A session closed because its credential expired has kind `MOQ_PROTOCOL_KIND_EXPIRED`, and a request refused for an expired token returns `MOQ_ERROR_EXPIRED`; refresh the token before retrying. A catalog that needs a newer moq-hang draft than this build reads returns `MOQ_ERROR_UNSUPPORTED_CATALOG`; upgrade the library to read it. A request-cap closure has kind `MOQ_PROTOCOL_KIND_TOO_MANY_REQUESTS`; reduce the workload or adjust the relay's [session limits](/bin/relay/config#session-and-peer) before reconnecting. - **Threading.** Call any function from any thread. Raw publish calls block until the codec takes the frame, which paces a publisher. - **Zeroed config is the default.** A zeroed `moq_client_config` means the default for every field, so new fields don't break callers. A field whose default isn't zero has a `has_*` flag: `backoff_timeout_us = 0` means "retry forever" only with `has_backoff_timeout = true`. diff --git a/doc/lib/cpp/index.md b/doc/lib/cpp/index.md index 725a713349c..37432121667 100644 --- a/doc/lib/cpp/index.md +++ b/doc/lib/cpp/index.md @@ -211,7 +211,7 @@ On `moq-lite-07-wip` (opt in with `ClientConfig::versions`) and on moq-transport ## Shutdown -`session->shutdown().get()` drains for up to one second and reports any error. +`session->shutdown()` requests a drain immediately; `session->closed().get()` waits up to one second and reports its result. 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. Finish or abort live tracks first. diff --git a/doc/lib/dart/index.md b/doc/lib/dart/index.md index 84f76c2113c..4e404030a56 100644 --- a/doc/lib/dart/index.md +++ b/doc/lib/dart/index.md @@ -137,7 +137,7 @@ shows which module holds each. - **Audio needs cuts.** Video groups at its keyframes, but audio forms a group only where you call `cut()`: after every frame, or at a segment cadence to align with video. - **Live encoder timing.** After writing a frame you encoded yourself, call `flush(timestampUs: ...)` with the same timestamp so the catalog advertises your jitter. Skip it for file and network imports. On a seek or pause, call `discontinuity()`, then keep timestamps moving forward and resume video on a keyframe. - **Decoded frames hold decoder buffers.** `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()` or `session.shutdown()` drains for up to one second and reports any error. `session.cancel(code: 0)` closes at once. Finish or abort live tracks first. Cancelling a stream subscription releases its native cursor. 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. +- **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. Cancelling a stream subscription releases its native cursor. 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 `broadcast.finish()`. The returned `BroadcastFinish` keeps the broadcast announced and serving the finished tracks for `linger`, their longest max age, so a subscriber still catching up can drain them. `await finish.wait()` completes once the linger passes, and `finish.close()` closes the broadcast at once, completing the wait. `broadcast.close()` stays the abrupt end. - **Stats.** `session.stats()` reports `rttUs`, `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, and while a client session reconnects `session.failure()` says why. Before the first connect, `client.failure()` says why the dial is retrying. Hold the owned `BandwidthConsumer` returned by `session.recvBandwidth()` to receive bandwidth estimates. `peek()` reads the current estimate in bits per second and `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 `ConnectOptions(versions: ...)`) and on moq-transport draft-17+ with the [MoQ Auth extension](/draft/moq-auth), listen to `moq.auth().grants()` for the `Grant` the relay sent back, `null` until it answers and while a client session reconnects. `await auth().add(token: ...)` presents a fresh token without reconnecting, returns an `AuthToken` whose grant joins the union until `cancel()`, and is presented again on every reconnect. A refusal throws with the relay's code. diff --git a/doc/lib/go/index.md b/doc/lib/go/index.md index 50534897fde..0a2659772b1 100644 --- a/doc/lib/go/index.md +++ b/doc/lib/go/index.md @@ -126,7 +126,7 @@ shows which module holds each. - **Audio needs cuts.** Video groups at its keyframes, but audio forms a group only where you call `Cut()`: after every frame, or at a segment cadence to align with video. - **Live encoder timing.** After writing a frame you encoded yourself, call `Flush(timestamp)` with the same timestamp so the catalog advertises your jitter. Skip it for file and network imports. On a seek or pause, call `Discontinuity()`, then keep timestamps moving forward and resume video on a keyframe. - **Decoded frames hold decoder buffers.** `Close` each `VideoDecodedFrame` promptly, or the decoder stalls. `Resize` is best effort, so read each frame's `Width()` and `Height()`. -- **Closing.** `client.Close()` drains for up to one second and returns an error on failure. `session.Shutdown(ctx)` does the same, 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. +- **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 `broadcast.Finish()`. The returned `*BroadcastFinish` keeps the broadcast announced and serving the finished tracks for `Linger()`, their longest max age, so a subscriber still catching up can drain them. `finish.Wait(ctx)` returns once the linger passes; ending `ctx`, or `finish.Close()`, closes the broadcast at once. `broadcast.Close()` stays the abrupt end. - **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, and while a client session reconnects `Session().Failure()` says why. Hold the owned `BandwidthConsumer` returned by `Session().RecvBandwidth()` to receive bandwidth estimates. `Peek()` reads the current estimate in bits per second and `Changed(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 `moq.WithVersions`) and on moq-transport draft-17+ with the [MoQ Auth extension](/draft/moq-auth), `Session().Auth().Grant()` is the `Grant` the relay sent back, nil until it answers and while a client session reconnects; `GrantChanged(ctx)` waits for the next one. `Add(ctx, token)` presents a fresh token without reconnecting, returns an `AuthToken` whose grant joins the union until `Close()`, and is presented again on every reconnect. A refusal returns the relay's code. diff --git a/doc/lib/kt/index.md b/doc/lib/kt/index.md index 802721741f9..3e4017058ff 100644 --- a/doc/lib/kt/index.md +++ b/doc/lib/kt/index.md @@ -85,6 +85,7 @@ Moq.connect("https://relay.example.com").use { moq -> video.finish() broadcast.end() moq.shutdown() + moq.session.closed() } ``` @@ -98,7 +99,7 @@ shows which module holds each. - **Audio needs cuts.** Video groups at its keyframes, but audio forms a group only where you call `cut()`: after every frame, or at a segment cadence to align with video. - **Live encoder timing.** After writing a frame you encoded yourself, call `flush(timestampUs)` with the same timestamp so the catalog advertises your jitter. Skip it for file and network imports. On a seek or pause, call `discontinuity()`, then keep timestamps moving forward and resume video on a keyframe. - **Decoded frames hold decoder buffers.** `close()` each 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.** Suspending `moq.shutdown()` drains for up to one second and throws on failure. `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. +- **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 `broadcast.finish()`. The returned `BroadcastFinish` keeps the broadcast announced and serving the finished tracks for `linger`, their longest max age, so a subscriber still catching up can drain them. Suspending `finish.wait()` returns once the linger passes; cancelling its coroutine, or `finish.end()`, closes the broadcast at once. `broadcast.end()` stays the abrupt end. - **Stats.** `session.stats()` reports `rttUs`, `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, and while a client session reconnects `session.failure()` says why. Before the first connect, `client.failure()` says why the dial is retrying. Hold the owned `BandwidthConsumer` returned by `session.recvBandwidth()` to receive bandwidth estimates. `peek()` reads the current estimate in bits per second and `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 `ClientConfig(versions = ...)`) and on moq-transport draft-17+ with the [MoQ Auth extension](/draft/moq-auth), collect `moq.auth().grants()` for the `Grant` the relay sent back, `null` until it answers and while a client session reconnects. Suspending `auth().add(token)` presents a fresh token without reconnecting, returns an `AuthToken` whose grant joins the union until `cancel()`, and is presented again on every reconnect. A refusal throws with the relay's code. diff --git a/doc/lib/py/index.md b/doc/lib/py/index.md index abeb6c4a8ce..156d4581303 100644 --- a/doc/lib/py/index.md +++ b/doc/lib/py/index.md @@ -113,7 +113,7 @@ shows which module holds each. - **Audio needs cuts.** Video groups at its keyframes, but audio forms a group only where you call `cut()`: after every frame, or at a segment cadence to align with video. - **Live encoder timing.** After writing a frame you encoded yourself, call `flush(timestamp)` with the same timestamp so the catalog advertises your jitter. Skip it for file and network imports. On a seek or pause, call `discontinuity()`, then keep timestamps moving forward and resume video on a keyframe. - **Decoded frames hold decoder buffers.** 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.** `await session.shutdown()` drains for up to one second and raises on failure. `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. +- **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 `broadcast.finish()`. The returned `BroadcastFinish` keeps the broadcast announced and serving the finished tracks for `linger`, their longest max age, so a subscriber still catching up can drain them. `await finish.wait()` returns once the linger passes; cancelling it, or `finish.close()`, closes the broadcast at once. `broadcast.close()` stays the abrupt end. - **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, and while a client session reconnects `session.failure()` says why. Before the first connect, `client.failure()` says why the dial is retrying. Hold the owned `Bandwidth.Consumer` returned by `session.recv_bandwidth()` to receive bandwidth estimates. `peek()` reads the current estimate in bits per second and `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-17+ with the [MoQ Auth extension](/draft/moq-auth), `session.auth().grant()` is the `Grant` the relay sent back, `None` until it answers and while a client session reconnects; `await auth.grant_changed()` waits for the next one. `await auth.add(token)` presents a fresh token without reconnecting, returns an `AuthToken` whose grant joins the union until `cancel()`, and is presented again on every reconnect. A refusal raises with the relay's code. diff --git a/doc/lib/swift/index.md b/doc/lib/swift/index.md index 9af56d5a1da..9eac55d4cc5 100644 --- a/doc/lib/swift/index.md +++ b/doc/lib/swift/index.md @@ -85,7 +85,8 @@ try audio.finish() try video.finish() try broadcast.close() -try await session.shutdown() +session.shutdown() +try await session.closed() ``` ## Things to know @@ -97,7 +98,7 @@ shows which module holds each. - **Audio needs cuts.** Video groups at its keyframes, but audio forms a group only where you call `cut()`: after every frame, or at a segment cadence to align with video. - **Live encoder timing.** After writing a frame you encoded yourself, call `flush(timestampUs:)` with the same timestamp so the catalog advertises your jitter. Skip it for file and network imports. On a seek or pause, call `discontinuity()`, then keep timestamps moving forward and resume video on a keyframe. - **Decoded frames hold decoder buffers.** 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.** `try await session.shutdown()` drains for up to one second and throws on failure. `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. +- **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 broadcast.finish()`. The returned `BroadcastFinish` keeps the broadcast announced and serving the finished tracks for `lingerUs`, their longest max age, so a subscriber still catching up can drain them. `try await finish.wait()` returns once the linger passes; cancelling its task, or `finish.close()`, closes the broadcast at once. `broadcast.close()` stays the abrupt end. - **Stats.** `session.stats()` reports `rttUs`, `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, and while a client session reconnects `session.failure()` says why. Before the first connect, `client.failure()` says why the dial is retrying. Hold the owned `Bandwidth.Consumer` returned by `session.recvBandwidth()` to receive bandwidth estimates. `peek()` reads the current estimate in bits per second and `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 `Client(versions:)`) and on moq-transport draft-17+ with the [MoQ Auth extension](/draft/moq-auth), `session.auth().grant()` is the `Grant` the relay sent back, `nil` until it answers and while a client session reconnects; `try await auth.grantChanged()` waits for the next one. `try await auth.add(token:)` presents a fresh token without reconnecting, returns an `AuthToken` whose grant joins the union until `cancel()`, and is presented again on every reconnect. A refusal throws with the relay's code. diff --git a/go/ffi/MIGRATE.md b/go/ffi/MIGRATE.md index 5319a4adb04..bfafe978f0f 100644 --- a/go/ffi/MIGRATE.md +++ b/go/ffi/MIGRATE.md @@ -4,6 +4,11 @@ How to update your code for each breaking change, newest first. ## Unreleased +### Shutdown requests the drain synchronously + +`Shutdown()` requests a drain synchronously; `Closed(ctx)` waits for its result and reports delivery failures. Regenerate bindings and link the matching native library together. See the [core migration guide](https://github.com/moq-dev/moq/blob/main/rs/moq-ffi/MIGRATE.md) for the core contract. +When upgrading from the release-line additive async `drain()` backport, replace the release-line async `drain()` with `Shutdown()` followed by `Closed(ctx)`; `main` has no separate `drain()` method. + ### Priorities are signed (#6142) `MoqTrackInfo.Priority`, `MoqSubscription.Priority`, `MoqFetchGroupOptions.Priority`, and `MoqGroupRequest.Priority()` are `int8`, higher first, and 0 is the unset midpoint. diff --git a/go/wrapper/MIGRATE.md b/go/wrapper/MIGRATE.md index 765675dbae7..7371c1ab04e 100644 --- a/go/wrapper/MIGRATE.md +++ b/go/wrapper/MIGRATE.md @@ -4,6 +4,11 @@ How to update your code for each breaking change, newest first. ## Unreleased +### Shutdown requests the drain synchronously + +`session.Shutdown()` requests a drain synchronously with no context or error result. Call `session.Closed(ctx)` to wait and report delivery failures, or `session.Cancel(0)` for immediate cancellation. `Client.Close()` now waits for the drain and returns an error. +When upgrading from the release-line additive async `drain()` backport, replace `session.Drain(ctx)` with `session.Shutdown(); session.Closed(ctx)`; `main` has no separate `drain()` method. + ### JSON snapshot `DeltaRatio` is `Deltas` `json.SnapshotOptions.DeltaRatio *uint32` and `json.DefaultDeltaRatio` are replaced by `Deltas *bool` (nil enables deltas). diff --git a/go/wrapper/client.go b/go/wrapper/client.go index 050107de43d..fa4826fd618 100644 --- a/go/wrapper/client.go +++ b/go/wrapper/client.go @@ -400,7 +400,8 @@ func (c *Client) Session() *Session { func (c *Client) Close() error { c.closeOnce.Do(func() { if c.session != nil { - c.closeErr = c.session.Shutdown(context.Background()) + c.session.Shutdown() + c.closeErr = c.session.Closed(context.Background()) } if c.inner != nil { c.inner.Cancel() diff --git a/go/wrapper/session.go b/go/wrapper/session.go index bf5f2f57373..e8f9ef9bf1d 100644 --- a/go/wrapper/session.go +++ b/go/wrapper/session.go @@ -15,7 +15,8 @@ type Session struct { } // Closed blocks until the session closes and returns the reason. A graceful -// close reports an error for which IsShutdown returns true. Cancelling ctx gives +// close reports an error for which IsShutdown returns true. After Shutdown, it +// waits for the drain and reports delivery failures. Cancelling ctx gives // up waiting and shuts the session down, so a caller that no longer cares about // the connection can tear it down by cancelling. func (s *Session) Closed(ctx context.Context) error { @@ -186,13 +187,12 @@ func (s *Session) Consume() *OriginConsumer { return &OriginConsumer{inner: s.inner.Consume()} } -// Shutdown drains finished tracks within one second, returning any drain error. -// Explicit moq-lite-07-wip waits for the peer to receive finished tails; older Lite -// versions, including the default lite-06, wait only for transport ACKs. -// IETF also waits for transport ACKs. -// Cancelling ctx aborts the session immediately. -func (s *Session) Shutdown(ctx context.Context) error { - return bridge.CallErr(ctx, s.abort, s.inner.Shutdown) +// Shutdown requests a draining close now; wait for its result with Closed. +// Explicit moq-lite-07-wip waits for the peer to receive finished tails; older +// Lite versions (including default lite-06) and IETF wait only for transport ACKs. +// Finish or abort live tracks first; the drain times out after one second. +func (s *Session) Shutdown() { + s.inner.Shutdown() } // abort tears the session down without draining, for a cancelled ctx. diff --git a/kt/moq-ffi/MIGRATE.md b/kt/moq-ffi/MIGRATE.md index a87e06daea2..1a300b63a99 100644 --- a/kt/moq-ffi/MIGRATE.md +++ b/kt/moq-ffi/MIGRATE.md @@ -4,6 +4,11 @@ How to update your code for each breaking change, newest first. ## Unreleased +### Shutdown requests the drain synchronously + +`shutdown()` requests a drain synchronously; suspending `closed()` waits for its result and reports delivery failures. Regenerate bindings and link the matching native library together. See the [core migration guide](https://github.com/moq-dev/moq/blob/main/rs/moq-ffi/MIGRATE.md) for the core contract. +When upgrading from the release-line additive async `drain()` backport, replace the release-line async `drain()` with `shutdown()` followed by suspending `closed()`; `main` has no separate `drain()` method. + ### A client asks only about what it watches (#6165) On moq-lite, a client session asks its relay for announcements only under paths something watches, through `announced()` or `announcedBroadcast()`, instead of under its whole scope at connect. diff --git a/kt/moq/MIGRATE.md b/kt/moq/MIGRATE.md index 6e1db97c770..31dfad1652f 100644 --- a/kt/moq/MIGRATE.md +++ b/kt/moq/MIGRATE.md @@ -4,6 +4,11 @@ How to update your code for each breaking change, newest first. ## Unreleased +### Shutdown requests the drain synchronously + +`session.shutdown()` and `moq.shutdown()` request a drain synchronously. Await `session.closed()` (or `moq.session.closed()`) to wait and report delivery failures. `Moq.close()` still cancels immediately. +When upgrading from the release-line additive async `drain()` backport, replace suspending `session.drain()` with `session.shutdown(); session.closed()`; `main` has no separate `drain()` method. + ### JSON snapshot `deltaRatio` is `deltas` `SnapshotConfig.deltaRatio: UInt` is replaced by `deltas: Boolean` (default `true`). diff --git a/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/Moq.kt b/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/Moq.kt index 22af44a7a77..9d5e51391cf 100644 --- a/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/Moq.kt +++ b/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/Moq.kt @@ -8,7 +8,7 @@ package dev.moq * auto-created), so you can [createBroadcast] and collect [announced] updates * without touching the raw [Client] handle. * - * Call [shutdown] to drain finished tracks before disconnecting. [AutoCloseable] + * Call [shutdown], then await [Session.closed] to drain finished tracks before disconnecting. [AutoCloseable] * disposal through `use { ... }` or [close] cancels immediately. */ class Moq internal constructor( @@ -77,17 +77,13 @@ class Moq internal constructor( fun auth(): Auth = session.auth() /** - * Drain finished tracks within one second, throwing on failure. + * Request a draining close now; await `session.closed()` for its result. * Explicit `moq-lite-07-wip` waits for the peer to receive finished tails; older * Lite versions, including the default lite-06, wait only for transport ACKs. * IETF also waits for transport ACKs. */ - suspend fun shutdown() { - try { - session.shutdown() - } finally { - client.cancel() - } + fun shutdown() { + session.shutdown() } /** Cancel immediately and release the client. */ diff --git a/py/moq-ffi/MIGRATE.md b/py/moq-ffi/MIGRATE.md index 3390d71fffd..f550c269113 100644 --- a/py/moq-ffi/MIGRATE.md +++ b/py/moq-ffi/MIGRATE.md @@ -4,6 +4,11 @@ How to update your code for each breaking change, newest first. ## Unreleased +### Shutdown requests the drain synchronously + +`shutdown()` requests a drain synchronously; `await closed()` waits for its result and reports delivery failures. Regenerate bindings and link the matching native library together. See the [core migration guide](https://github.com/moq-dev/moq/blob/main/rs/moq-ffi/MIGRATE.md) for the core contract. +When upgrading from the release-line additive async `drain()` backport, replace the release-line async `drain()` with `shutdown()` followed by `await closed()`; `main` has no separate `drain()` method. + ### A client asks only about what it watches (#6165) On moq-lite, a client session asks its relay for announcements only under paths something watches, through `announced()` or `announced_broadcast()`, instead of under its whole scope at connect. diff --git a/py/moq-rs/MIGRATE.md b/py/moq-rs/MIGRATE.md index b9a85594a45..89a24f5ec8e 100644 --- a/py/moq-rs/MIGRATE.md +++ b/py/moq-rs/MIGRATE.md @@ -4,6 +4,11 @@ How to update your code for each breaking change, newest first. ## Unreleased +### Shutdown requests the drain synchronously + +`session.shutdown()` requests the drain synchronously. Use `session.shutdown(); await session.closed()` to wait and raise delivery failures, or `session.cancel(0)` for immediate cancellation. A clean `async with` exit now waits for the drain. +When upgrading from the release-line additive async `drain()` backport, replace `await session.drain()` with `session.shutdown(); await session.closed()`; `main` has no separate `drain()` method. + ### JSON snapshot `delta_ratio` is `deltas` `SnapshotProducer(delta_ratio=...)` is replaced by `deltas: bool = True`. diff --git a/py/moq-rs/README.md b/py/moq-rs/README.md index 1b37695547c..c0f4d156bc4 100644 --- a/py/moq-rs/README.md +++ b/py/moq-rs/README.md @@ -153,7 +153,7 @@ client = moq.Client( - `.cancel()`. Cancel an in-flight `accept()`/`reject()` call. - **`Session`**. An established connection. Holding it keeps the connection alive; it is also an `async with` context manager that drains on a clean exit and cancels on an error. - `await .closed()`. Wait until the session closes. - - `.cancel(code)`, `await session.shutdown()`. Cancel immediately, or drain within one second, raising on failure. Explicit `moq-lite-07-wip` waits for the peer to receive finished tails; older Lite versions, including default lite-06, wait only for transport ACKs. IETF also waits for transport ACKs. + - `.cancel(code)`, `session.shutdown()`. Cancel immediately, or request a drain now and await `session.closed()` for its result, including a delivery timeout after one second. Explicit `moq-lite-07-wip` waits for the peer to receive finished tails; older Lite versions, including default lite-06, wait only for transport ACKs. IETF also waits for transport ACKs. - `.publish() → OriginProducer`, `.consume() → OriginConsumer`. The wired origin sides. - `.stats() → ConnectionStats`. Snapshot RTT, bandwidth estimates, and byte/packet counters. - `await .status() → ConnectionStatus`, `.connects()`, `.failure()`. Watch reconnects; `connects()` counts connections, 1 on the first, and `failure()` says why a reconnect is under way. Before the first connect, `Client.failure()` says why the dial is retrying. diff --git a/py/moq-rs/moq/client.py b/py/moq-rs/moq/client.py index 2fc83120bdc..e240debb0af 100644 --- a/py/moq-rs/moq/client.py +++ b/py/moq-rs/moq/client.py @@ -179,7 +179,8 @@ async def __aexit__(self, *exc) -> None: # rather than skip: dropping the last session closes the transport, so # one the caller kept a reference to would otherwise stay open. if exc[0] is None: - await self._session.shutdown() + self._session.shutdown() + await self._session.closed() else: self._session.cancel(0) finally: diff --git a/py/moq-rs/moq/session.py b/py/moq-rs/moq/session.py index e1782c99579..8d258909669 100644 --- a/py/moq-rs/moq/session.py +++ b/py/moq-rs/moq/session.py @@ -31,7 +31,8 @@ async def __aexit__(self, *exc) -> None: # A body error is the failure worth reporting. Draining behind it would wait # out the deadline and replace it with a delivery timeout. if exc[0] is None: - await self.shutdown() + self.shutdown() + await self.closed() else: self.cancel(0) @@ -40,9 +41,10 @@ async def closed(self) -> None: A client session resolves when its connection stops for good: it raises the terminal error when the connection gave up, and returns normally after a local - :meth:`shutdown`/:meth:`cancel`. Transient drops the reconnect loop rides out + :meth:`cancel`. After :meth:`shutdown`, it waits for the drain and raises + delivery failures. Transient drops the reconnect loop rides out do not resolve this; watch :meth:`status` for those. A server-accepted session - raises the session's close reason.""" + reports a requested drain's result, otherwise raises the session's close reason.""" await self._inner.closed() async def status(self) -> ConnectionStatus: @@ -80,14 +82,14 @@ def cancel(self, code: int) -> None: """Close the session with the given error code.""" self._inner.cancel(code) - async def shutdown(self) -> None: - """Drain within one second, raising on failure. + def shutdown(self) -> None: + """Request a draining close now; await :meth:`closed` for its result. Explicit ``moq-lite-07-wip`` waits for the peer to receive finished tails; older Lite versions, including the default lite-06, wait only for transport ACKs. IETF also waits for transport ACKs. """ - await self._inner.shutdown() + self._inner.shutdown() def publish(self) -> OriginProducer: """The publish-side origin: where local broadcasts are advertised to diff --git a/quest/m0/ffi-shutdown-backport.md b/quest/m0/ffi-shutdown-backport.md index 1be2190de10..e22030e6f30 100644 --- a/quest/m0/ffi-shutdown-backport.md +++ b/quest/m0/ffi-shutdown-backport.md @@ -7,7 +7,7 @@ Kotlin) and moq-tokio whose sessions can drain before closing and whose qmux sessions accept the QUIC stream limit: - An async `MoqSession.drain()` drains finished tracks within one second - and returns any delivery error, as `main`'s async `shutdown()` does + and returns any delivery error, as the earlier async shutdown implementation did (7bbac3272, with 03fb0d1c1, f9de31167, and #5558's explicit Lite 07 test). Explicit `moq-lite-07-wip` waits for the peer to receive the tail; older Lite versions, including the default lite-06, and IETF wait only for @@ -25,8 +25,10 @@ that gain `drain()`) expose it too. Decided 2026-10-20 (maintainer): additive `drain()` on `release` rather than backporting async `shutdown()` as-is. Why: making `shutdown()` async breaks -the 0.4.x Python, Swift, and Kotlin bindings. `main` keeps async `shutdown()` -and gains no `drain()`; callers move to it at the next breaking cut. +the 0.4.x Python, Swift, and Kotlin bindings. `main` requests the drain with synchronous `shutdown()` and reports its result +through `closed()`; it gains no separate `drain()`. Callers replace the release +line's awaited `drain()` with `shutdown()` followed by awaiting `closed()` at the +next breaking cut. Decided 2026-10-20 (maintainer): keep #5609 in the backport, on a qmux 0.5.3 published from web-transport's `qmux-v0.5.x`. Why: `release` locks diff --git a/quest/m1/README.md b/quest/m1/README.md index 81f1f845876..a73cf7f611f 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -90,7 +90,6 @@ tracks, so per-group stats stop costing cluster announces. - [Exact timestamps in every binding](/quest/m1/binding-timestamps.md) - bindings carry `{value, scale}` timestamps instead of lossy microseconds - [Video preference in bindings](/quest/m1/ffi-video-preference.md) - every binding's video catalog record carries hang's rendition `preference` - [Binding encoder config](/quest/m1/binding-encoder-config.md) - binding encoders take an exact rational framerate, and the publication track name moves to options only the producers take -- [FFI shutdown requests the drain synchronously](/quest/m1/ffi-shutdown-sync.md) - `shutdown()` becomes a sync drain request awaited with `closed()`, so a dropped future can no longer cancel - [moq-transport passthrough](/quest/m1/ietf-extension/README.md) - object IDs, properties, end status, datagram objects, and unknown track properties survive moq-transport -> moq-relay (and a relay cluster) -> moq-transport; moxygen's moq-test sections 1-7 pass nightly, except cases that use a subgroup other than 0 - [Refresh](/quest/m1/refresh/README.md) - a join asks for a fresh group once the current group's deltas exceed a publisher-advertised byte ratio, at every hop; replaces `Demand::used`/`unused` and moq-json's `delta_ratio` - [Announcement takeover](/quest/m1/announce-takeover.md) - a new independent route explicitly continues instances served through its predecessor, with shared Rust/JS semantics and lite-07 wire diff --git a/quest/m1/api-audit/migrate.md b/quest/m1/api-audit/migrate.md index e35e053117b..0160c292643 100644 --- a/quest/m1/api-audit/migrate.md +++ b/quest/m1/api-audit/migrate.md @@ -12,11 +12,10 @@ packages that were never published carry no migration entries. Decided 2026-10-22 (API audit). Known gaps, verify each against `git show origin/release:`: -- Bindings: `MoqSession::shutdown` went from sync `()` to async `Result` - (7bbac32721); only `swift/MIGRATE.md` says so. Add it to `rs/moq-ffi`, - `py/moq-rs` (an un-awaited call is now a silent no-op), `go/wrapper` - (`Shutdown(ctx) error`, and `Client.Close()` now blocks while draining), - `kt/moq`, `dart/moq` (`Moq.close()` returns `Future`). +- Bindings: the synchronous shutdown request and awaited `closed()` result are + synchronized by [the shutdown change](https://github.com/moq-dev/moq/pull/6436). + Verify its entries against `release`, including the additive async `drain()` + backport mapping, rather than documenting the intermediate async shutdown. - Bindings: merge the contradictory `finish` entries ("removed (#4152)" and "the new `finish` lets go (#6157)") into one: `finish()` now returns a linger handle; call `close()` for the old behavior. diff --git a/quest/m1/ffi-shutdown-sync.md b/quest/m1/ffi-shutdown-sync.md deleted file mode 100644 index 5671aa784a6..00000000000 --- a/quest/m1/ffi-shutdown-sync.md +++ /dev/null @@ -1,41 +0,0 @@ -# [M] FFI shutdown requests the drain synchronously - -## Goal - -`MoqSession::shutdown()` in moq-ffi is a plain (non-async) call that requests -the draining close before it returns, like `cancel(code)`. A caller waits for -the drain with the existing async `closed()`. Dropping or never polling a -future can no longer turn a shutdown into a cancel. Every binding and wrapper -follows, with a `MIGRATE.md` entry in each affected package. - -## Plan - -Today `shutdown` is async and runs the close through `ffi::detached` -(`rs/moq-ffi/src/ffi.rs`), which aborts its task when the caller drops the -future. The async body only runs on first poll, so a caller that drops the -future early, as OBS's `MoQOutput::Stop` must avoid by holding it, gets a cancel -instead of a drain (found in [moq-dev/moq#6277](https://github.com/moq-dev/moq/pull/6277)). - -Decided 2026-10-22 (maintainer): a synchronous `shutdown()` that only requests -the drain, waited on with `closed()`. Rejected: keeping it async and never -aborting the close (no API change, but the request still waits for a poll), and -an extra `begin_shutdown()` beside the async one (two methods for one action). - -- Start the close on the FFI runtime before `shutdown()` returns, and report a - close that fails through `closed()`. -- Follow the Cross-Package Sync row for `rs/moq-ffi`: `rs/moq-c` (or the - generated C package, whichever ships first), the py, swift, kt, dart, and go - wrappers, `cpp/moq`, `cpp/obs/src` (drop the "keep the future" workaround in - `MoQOutput::Stop`), and `doc/lib/*`. -- Test: a shutdown whose result is never awaited still drains a finished track, - with mocked time, in moq-ffi and through the OBS output test. -- The `release` line's additive async `drain()` - ([FFI shutdown backport](/quest/m0/ffi-shutdown-backport.md)) maps onto this - at the next breaking cut; say so in each MIGRATE entry. - -Public API: breaking in moq-ffi and every binding. Wire: none. - -## Related - -- [FFI shutdown backport](/quest/m0/ffi-shutdown-backport.md) - the release line's async `drain()` -- [MIGRATE matches release](/quest/m1/api-audit/migrate.md) - plans entries saying `shutdown` became an async `Result`; they must describe the final sync shape instead diff --git a/rs/moq-c/MIGRATE.md b/rs/moq-c/MIGRATE.md index 2a7b6e6571d..8e8a5f78c75 100644 --- a/rs/moq-c/MIGRATE.md +++ b/rs/moq-c/MIGRATE.md @@ -4,6 +4,11 @@ How to update your code for each breaking change, newest first. ## Unreleased +### Shutdown requests the drain synchronously + +`moq_session_close()` keeps its synchronous request/terminal-callback ABI. Accepted sessions now drain finished tracks too; a failed drain is reported by the terminal `on_status` callback. Finish or abort live published tracks before requesting close. +The UniFFI release-line additive async `drain()` backport maps to `shutdown()` then `closed()` on main. The C ABI continues to use `moq_session_close()` and its terminal callback; no function is renamed. + ### JSON snapshot `delta_ratio` is `deltas` `moq_json_snapshot_config.delta_ratio` is replaced by `bool deltas`. diff --git a/rs/moq-c/src/session.rs b/rs/moq-c/src/session.rs index df02aa46a63..855c5d05b8d 100644 --- a/rs/moq-c/src/session.rs +++ b/rs/moq-c/src/session.rs @@ -182,7 +182,11 @@ impl Session { // Close the transport now rather than whenever the last clone drops. if let Link::Accepted(Some(accepted)) = &entry.link && let Err(error) = ffi::run(async { - accepted.session.abort(moq_net::Error::Cancel); + if res.is_ok() { + accepted.session.clone().close().await?; + } else { + accepted.session.abort(moq_net::Error::Cancel); + } accepted.driver.finished().await }) .await diff --git a/rs/moq-c/src/test.rs b/rs/moq-c/src/test.rs index d98cc3fe827..45fc945854a 100644 --- a/rs/moq-c/src/test.rs +++ b/rs/moq-c/src/test.rs @@ -5645,11 +5645,35 @@ fn server_accepts_a_session() { let consumed = id(announced_cb.recv()); assert_eq!(moq_origin_announced_broadcast_cancel(task), 0); assert_eq!(announced_cb.recv_terminal(), 0); - assert_eq!(moq_consume_close(consumed), 0); - - // Closing the accepted session is a clean terminal close. + // Prime the subscription, then queue a finished tail before closing the accepted + // session. Its terminal callback must not report success after aborting the tail. + let track = publish_named_track(broadcast, b"tail"); + let (consumer, frames) = subscribe_named_track(consumed, b"tail"); + let first = b"ready"; + assert_eq!( + unsafe { moq_publish_track_frame(track, first.as_ptr(), first.len(), 0) }, + 0 + ); + assert_eq!(moq_consume_track_frame_free(id(frames.recv())), 0); + let tail = vec![42; 64 * 1024]; + assert_eq!( + unsafe { moq_publish_track_frame(track, tail.as_ptr(), tail.len(), 1) }, + 0 + ); + assert_eq!(moq_publish_track_finish(track), 0); assert_eq!(moq_session_close(session), 0); + let frame_id = id(frames.recv()); + let mut frame: moq_frame = unsafe { std::mem::zeroed() }; + assert_eq!(unsafe { moq_consume_track_frame(frame_id, &mut frame) }, 0); + assert_eq!( + unsafe { std::slice::from_raw_parts(frame.payload, frame.payload_size) }, + tail + ); + assert_eq!(moq_consume_track_frame_free(frame_id), 0); + assert_eq!(frames.recv_terminal(), 0, "the tail ends cleanly"); assert_eq!(session_cb.recv_terminal(), 0); + assert!(moq_consume_track_cancel(consumer) < 0, "the consumer ended"); + assert_eq!(moq_consume_close(consumed), 0); assert_eq!(moq_session_close(client), 0); client_cb.recv_terminal(); diff --git a/rs/moq-ffi/MIGRATE.md b/rs/moq-ffi/MIGRATE.md index 8ed40b7a0a6..b0497875430 100644 --- a/rs/moq-ffi/MIGRATE.md +++ b/rs/moq-ffi/MIGRATE.md @@ -5,6 +5,11 @@ These are the UniFFI names; each language wrapper has its own `MIGRATE.md` in it ## Unreleased +### Shutdown requests the drain synchronously + +`MoqSession::shutdown()` requests the drain synchronously. Use `shutdown(); closed().await?` to wait and report delivery failures, or `cancel(0)` for immediate cancellation. +When upgrading from the release-line additive async `drain()` backport, replace `drain().await?` with `shutdown(); closed().await?`; `main` has no separate `drain()` method. + ### JSON snapshot `delta_ratio` is `deltas` `MoqJsonSnapshotConfig::delta_ratio` is replaced by `deltas: bool` (default `true`). diff --git a/rs/moq-ffi/src/error.rs b/rs/moq-ffi/src/error.rs index 5fc89ceff14..3b195549561 100644 --- a/rs/moq-ffi/src/error.rs +++ b/rs/moq-ffi/src/error.rs @@ -161,7 +161,7 @@ fn stream_kind(err: &moq_net::StreamError) -> MoqProtocolKind { /// /// Exports `Display`, which the bindings surface as the error's string form. /// Diagnostic payloads are named `reason`; structured protocol failures use `details`. -#[derive(Debug, thiserror::Error, uniffi::Error)] +#[derive(Debug, Clone, thiserror::Error, uniffi::Error)] #[uniffi::export(Display)] #[non_exhaustive] pub enum MoqError { diff --git a/rs/moq-ffi/src/session.rs b/rs/moq-ffi/src/session.rs index 660c67ee6e2..4698edc37b8 100644 --- a/rs/moq-ffi/src/session.rs +++ b/rs/moq-ffi/src/session.rs @@ -930,10 +930,34 @@ impl Accepted { } } +/// An owned drain; dropping its waiter or the foreign session cannot cancel it. +struct Shutdown { + result: kio::Consumer>>, + task: crate::ffi::Background, +} + +impl Shutdown { + async fn finished(&self) -> Result<(), MoqError> { + // Publish a background panic before reading the channel it dropped. + #[cfg(not(target_arch = "wasm32"))] + self.task.finished().await?; + #[cfg(target_arch = "wasm32")] + self.task.check()?; + self.result + .wait(|result| match &**result { + Some(result) => std::task::Poll::Ready(result.clone()), + None => std::task::Poll::Pending, + }) + .await + .map_err(|_| MoqError::Cancelled)? + } +} + /// A connection that exchanges broadcasts with a peer. #[derive(uniffi::Object)] pub struct MoqSession { inner: Inner, + shutdown: std::sync::OnceLock, /// Serializes `closed()` calls onto the FFI runtime; holds its own `Inner` clone /// so a parked `closed()` doesn't block the rest of the surface. closed: Task, @@ -996,6 +1020,7 @@ impl MoqSession { let bandwidth = Arc::new(MoqBandwidth::new(Self::mint_allocator(&inner))); Self { inner: inner.clone(), + shutdown: Default::default(), closed: Task::new(inner.clone()), status: Task::new(inner), publisher, @@ -1029,7 +1054,9 @@ impl Drop for MoqSession { // lingering CLOSE task, which panics if no reactor is in context. We can't leave this to the last `Session` clone's drop: clones // live in the `closed`/`status` tasks and the connection state, released after // this guard, off-runtime. Close-once dedup then makes those trailing drops no-ops. - self.teardown(moq_net::Error::Cancel); + if self.shutdown.get().is_none() { + self.teardown(moq_net::Error::Cancel); + } } } @@ -1040,19 +1067,24 @@ impl MoqSession { /// A client session resolves when its connection stops for good: `Err` with the /// terminal error when it gave up (retries exhausted, or the session's close reason /// with reconnecting disabled), `Ok` after a local [`shutdown`](Self::shutdown) / - /// [`cancel`](Self::cancel). Transient drops the reconnect loop rides out do not + /// [`cancel`](Self::cancel), or the drain error if shutdown failed. Transient drops the reconnect loop rides out do not /// resolve this; watch [`status`](Self::status) for those. A server-accepted - /// session resolves with the session's close reason. + /// session reports a requested drain's result, otherwise the session's close reason. pub async fn closed(&self) -> Result<(), MoqError> { // We have a task to run all of the closed calls juuuuust so they use the same tokio runtime. - self.watch(self.closed.run(|inner| async move { - match &*inner { - #[cfg(not(target_arch = "wasm32"))] - Inner::Connection(connection) => connection.closed().await.map_err(map_closed_error), - Inner::Session(session) => session.closed().await, - } - })) - .await + let terminal = self + .watch(self.closed.run(|inner| async move { + match &*inner { + #[cfg(not(target_arch = "wasm32"))] + Inner::Connection(connection) => connection.closed().await.map_err(map_closed_error), + Inner::Session(session) => session.closed().await, + } + })) + .await; + match self.shutdown.get() { + Some(shutdown) => shutdown.finished().await, + None => terminal, + } } /// Wait for the connection status to differ from the one this handle last reported. @@ -1060,7 +1092,8 @@ impl MoqSession { /// A client session reports `Connected` first (the connect it was built from), then /// follows the reconnect loop: `Disconnected` while redialing, `Connected` again on /// success, `Migrating` during a GOAWAY handover. It returns an error once the - /// connection stops for good (same terminal result as [`closed`](Self::closed)). + /// connection stops for good. After requesting shutdown, use [`closed`](Self::closed) + /// to wait for the drain and its delivery result. /// A server-accepted session is a single transport, so its only transition is /// terminal: this waits for the close and returns its reason. /// @@ -1100,26 +1133,42 @@ impl MoqSession { // (with the close reason, or Ok once the connection loop stops). } - /// Drain finished tracks within one second, returning any drain error. + /// Request a draining close now; wait for its result with [`closed`](Self::closed). /// - /// Finish or abort live tracks first. `cancel` stays immediate. The name - /// avoids Kotlin's generated `AutoCloseable.close()`, which releases the handle. + /// Finish or abort live tracks first. The request survives disposal of this + /// handle or a `closed()` waiter; repeated requests share the same drain. + /// `cancel` stays immediate. The name avoids Kotlin's generated + /// `AutoCloseable.close()`, which releases the handle. /// Explicit `moq-lite-07-wip` waits for the peer to receive the tail. Older Lite - /// versions, including the default lite-06, wait only for transport ACKs. - /// IETF also waits for transport ACKs. - pub async fn shutdown(&self) -> Result<(), MoqError> { - let inner = self.inner.clone(); - let result = crate::ffi::detached(async move { - match inner { - #[cfg(not(target_arch = "wasm32"))] - Inner::Connection(connection) => connection.close().await.map_err(map_closed_error), - Inner::Session(session) => session.close().await, - } - }) - .await; - self.publisher.inner().driver.check()?; - self.consumer.driver.check()?; - result + /// versions, including the default lite-06, and IETF wait only for transport ACKs. + /// A drain that takes longer than one second ends with a delivery timeout. + pub fn shutdown(&self) { + let _guard = crate::ffi::enter(); + self.shutdown.get_or_init(|| { + let result = kio::Producer::new(None); + let receiver = result.consume(); + let inner = self.inner.clone(); + // Keep the origins, not just the connection, alive through the drain. + let publisher = self.publisher.clone(); + let consumer = self.consumer.clone(); + let task = crate::ffi::spawn(async move { + let completed = match inner { + #[cfg(not(target_arch = "wasm32"))] + Inner::Connection(connection) => connection.close().await.map_err(map_closed_error), + Inner::Session(session) => session.close().await, + }; + let completed = publisher + .inner() + .driver + .check() + .and(consumer.driver.check()) + .and(completed); + *result + .write() + .unwrap_or_else(|_| unreachable!("the drain owns its completion")) = Some(completed); + }); + Shutdown { result: receiver, task } + }); } /// The publish-side origin: where local broadcasts get advertised diff --git a/rs/moq-ffi/src/test.rs b/rs/moq-ffi/src/test.rs index 67c72461817..eecad2664ff 100644 --- a/rs/moq-ffi/src/test.rs +++ b/rs/moq-ffi/src/test.rs @@ -4883,7 +4883,8 @@ async fn server_client_roundtrip() { // `cancel(code)` on the server side, so both shutdown paths run. media.finish().unwrap(); broadcast.close().unwrap(); - cs.shutdown().await.unwrap(); + cs.shutdown(); + cs.closed().await.unwrap(); server_session.cancel(0); server.cancel(); } @@ -4996,14 +4997,16 @@ async fn announced_broadcast_follows_an_epochless_replacement() { .await .expect("the replacement was never handed out") .unwrap(); - first.shutdown().await.unwrap(); + first.shutdown(); + first.closed().await.unwrap(); let fresh_track = subscribe_audio(&fresh).await; roundtrip(&media, &fresh_track, b"after", 2_000_000).await; media.finish().unwrap(); broadcast.close().unwrap(); - second.shutdown().await.unwrap(); + second.shutdown(); + second.closed().await.unwrap(); server.cancel(); drop(accept.await.unwrap()); } @@ -5261,7 +5264,8 @@ async fn server_client_roundtrip_auto_origin() { media.finish().unwrap(); broadcast.close().unwrap(); - cs.shutdown().await.unwrap(); + cs.shutdown(); + cs.closed().await.unwrap(); server_session.cancel(0); server.cancel(); } @@ -6962,6 +6966,108 @@ async fn data_track_names_cannot_collide() { first.finish().unwrap(); } +/// In-memory sessions whose protocol and origin drivers use the paused test clock. +async fn memory_shutdown_pair() -> (Arc, Arc) { + async fn drive(driver: impl moq_net::time::Driver) -> moq_tokio::Result<()> { + match moq_net::time::run(driver).await { + moq_net::Error::Closed + | moq_net::Error::Cancel + | moq_net::Error::Session(moq_net::SessionError::Cancel) => Ok(()), + error => Err(error.into()), + } + } + + fn origin() -> crate::origin::Origin { + let mut config = moq_net::origin::Config::default(); + config.pool = moq_net::cache::Pool::unbounded(); + let (inner, driver) = moq_net::origin::Producer::new(config); + tokio::spawn(moq_net::time::run(driver)); + crate::origin::Origin { + inner, + driver: Default::default(), + } + } + let a = origin(); + let b = origin(); + let version: moq_net::Version = "moq-lite-07-wip".parse().unwrap(); + let mut transport = moq_net::transport::memory::Config::default(); + transport.protocol = Some(version.alpn().into()); + transport.stream_buffer = 1024; + let (client, server) = moq_net::transport::memory::pair(transport); + let connect = async { + let (session, driver) = moq_net::Client::new() + .with_origin(a.inner.clone()) + .with_versions(version.into()) + .connect(moq_clock::Instant::now(), client) + .await + .unwrap(); + let driver = tokio::spawn(drive(driver)); + Arc::new(MoqSession::accepted(session, a.clone(), a, driver)) + }; + let accept = async { + let (session, driver) = moq_net::Server::new() + .with_origin(b.inner.clone()) + .with_versions(version.into()) + .accept(moq_clock::Instant::now(), server) + .await + .unwrap(); + let driver = tokio::spawn(drive(driver)); + Arc::new(MoqSession::accepted(session, b.clone(), b, driver)) + }; + tokio::join!(connect, accept) +} + +#[tokio::test(start_paused = true)] +async fn shutdown_without_waiter_survives_session_disposal() { + let (publisher, subscriber) = memory_shutdown_pair().await; + let broadcast = create_announced(&publisher.publish(), "tail"); + let track = broadcast.publish_track("data".into(), Some(timed_info())).unwrap(); + let remote = await_announced(&subscriber.consume(), "tail").await; + let reader = remote.subscribe_track("data".into(), None).await.unwrap(); + shutdown_ready(&track, &reader).await; + let group = track.append_group().unwrap(); + group + .write_frame(MoqFrame { + timestamp_us: Some(1), + payload: vec![42; 64 * 1024], + }) + .unwrap(); + group.finish().unwrap(); + track.finish().unwrap(); + // The foreign caller neither polls the result nor retains the session handle. + publisher.shutdown(); + drop(publisher); + let frame = reader.read_frame().await.expect("finished tail").expect("last frame"); + assert_eq!(frame.payload, vec![42; 64 * 1024]); + assert!(reader.read_frame().await.expect("clean end").is_none()); + subscriber.cancel(0); +} + +#[tokio::test(start_paused = true)] +async fn shutdown_failure_survives_a_discarded_waiter() { + let (publisher, subscriber) = memory_shutdown_pair().await; + let broadcast = create_announced(&publisher.publish(), "live"); + let track = broadcast.publish_track("data".into(), Some(timed_info())).unwrap(); + let remote = await_announced(&subscriber.consume(), "live").await; + let reader = remote.subscribe_track("data".into(), None).await.unwrap(); + shutdown_ready(&track, &reader).await; + publisher.shutdown(); + publisher.shutdown(); + let mut waiter = Box::pin(publisher.closed()); + assert!( + waiter + .as_mut() + .poll(&mut std::task::Context::from_waker(std::task::Waker::noop())) + .is_pending() + ); + drop(waiter); + for _ in 0..2 { + let error = publisher.closed().await.expect_err("unfinished track must time out"); + assert!(matches!(error, MoqError::Protocol { details } if details.kind == MoqProtocolKind::DeliveryTimeout)); + } + subscriber.cancel(0); +} + /// Real sockets exercise the FFI runtime and both accepted/client session handles. /// Only lite-07 acknowledges the received tail; default lite-06 closes after transport ACKs. async fn shutdown_pair() -> (Arc, Arc, Arc) { @@ -7052,7 +7158,8 @@ async fn shutdown_delivers_the_finished_track() { })?; group.finish()?; track.finish()?; - closing.shutdown().await?; + closing.shutdown(); + closing.closed().await?; Ok::<(), MoqError>(()) }), ) @@ -7091,7 +7198,8 @@ async fn shutdown_times_out_on_an_unfinished_track() { shutdown_ready(&track, &reader).await; let receiving = tokio::spawn(async move { reader.read_frame().await }); let start = moq_clock::Instant::now(); - let err = tokio::time::timeout(TIMEOUT, publisher.shutdown()) + publisher.shutdown(); + let err = tokio::time::timeout(TIMEOUT, publisher.closed()) .await .expect("shutdown") .expect_err("unfinished track must time out"); diff --git a/swift/MIGRATE.md b/swift/MIGRATE.md index ea2f0d9cce8..aafd558ad12 100644 --- a/swift/MIGRATE.md +++ b/swift/MIGRATE.md @@ -4,6 +4,11 @@ How to update your code for each breaking change, newest first. ## Unreleased +### Shutdown requests the drain synchronously + +`session.shutdown()` is synchronous and requests a drain. Follow it with `try await session.closed()` to wait and report delivery failures; use `session.cancel(code: 0)` for immediate cancellation. +When upgrading from the release-line additive async `drain()` backport, replace `try await session.drain()` with `session.shutdown(); try await session.closed()`; `main` has no separate `drain()` method. + ### JSON snapshot `deltaRatio` is `deltas` `Json.SnapshotProducer(deltaRatio:)` and `MoqJsonSnapshotConfig.deltaRatio` are replaced by `deltas: Bool` (default `true`). @@ -166,7 +171,7 @@ The `Client` setters are `Client(...)` arguments, with `tls`, `quic`, `websocket `setReconnect(false)` is `once: true`. A value the native side cannot use throws `MoqError.Config`, including a bad bind address. `Server` takes its config at init too, and a request takes its origins in `accept(publish:consume:)`, where `nil` inherits the server's origin. -`Session.shutdown()` is `async throws` and drains before returning. +`Session.shutdown()` requests a drain synchronously; `try await session.closed()` waits for its result. ```swift let client = try Client(tls: ClientTls(insecure: true), consume: origin) diff --git a/swift/README.md b/swift/README.md index c43736d19bb..0e0e5a4d191 100644 --- a/swift/README.md +++ b/swift/README.md @@ -53,7 +53,8 @@ for try await event in announced { } } -try await session.shutdown() +session.shutdown() +try await session.closed() ``` To publish through the auto-created origin: @@ -64,7 +65,7 @@ let broadcast = try session.publish.createBroadcast(path: "my-stream") try broadcast.announce() // unannounced broadcasts are invisible ``` -Cancelling the surrounding Swift `Task` propagates through to the underlying `cancel()` calls on each consumer. `try await session.shutdown()` drains finished tracks within one second and throws on delivery failure. `cancel(code: 0)` remains immediate. +Cancelling the surrounding Swift `Task` propagates through to the underlying `cancel()` calls on each consumer. `session.shutdown()` requests a drain immediately; `try await session.closed()` waits for it and throws on delivery failure. `cancel(code: 0)` remains immediate. A note on enum casing: `MoqError` keeps Rust's PascalCase variants, each carrying `message: String` (e.g. `MoqError.Closed(message: "...")`); plain enums round-trip to lowerCamelCase (`AudioSampleFormat.s16`). Audio codecs are objects with constructors (`AudioCodec.opus()`). diff --git a/swift/Sources/Moq/Client.swift b/swift/Sources/Moq/Client.swift index 4f0bb638118..5d9ead99bb6 100644 --- a/swift/Sources/Moq/Client.swift +++ b/swift/Sources/Moq/Client.swift @@ -107,7 +107,8 @@ public final class Session: Sendable { } /// Suspend until the session is over: an error when the connection gave up for - /// good, a normal return after a local `shutdown()`/`cancel()`. Transient drops + /// good, a normal return after a local `cancel()`. After `shutdown()`, wait for + /// the drain and throw on delivery failure. Transient drops /// the reconnect loop rides out don't resolve this; watch `status()` for those. public func closed() async throws { try await ffi.closed() @@ -151,12 +152,12 @@ public final class Session: Sendable { ffi.cancel(code: code) } - /// Drain finished tracks within one second, throwing on failure. + /// Request a draining close now; await `closed()` for its result. /// Explicit `moq-lite-07-wip` waits for the peer to receive finished tails; older /// Lite versions, including the default lite-06, wait only for transport ACKs. /// IETF also waits for transport ACKs. - public func shutdown() async throws { - try await ffi.shutdown() + public func shutdown() { + ffi.shutdown() } /// Snapshot the current connection statistics (RTT, bandwidth estimates, diff --git a/swift/ffi/MIGRATE.md b/swift/ffi/MIGRATE.md index e50bf21fcd7..d6b8699b347 100644 --- a/swift/ffi/MIGRATE.md +++ b/swift/ffi/MIGRATE.md @@ -4,6 +4,11 @@ How to update your code for each breaking change, newest first. ## Unreleased +### Shutdown requests the drain synchronously + +`shutdown()` requests a drain synchronously; `try await closed()` waits for its result and reports delivery failures. Regenerate bindings and link the matching native library together. See the [core migration guide](https://github.com/moq-dev/moq/blob/main/rs/moq-ffi/MIGRATE.md) for the core contract. +When upgrading from the release-line additive async `drain()` backport, replace the release-line async `drain()` with `shutdown()` followed by `try await closed()`; `main` has no separate `drain()` method. + ### A client asks only about what it watches (#6165) On moq-lite, a client session asks its relay for announcements only under paths something watches, through `announced()` or `announcedBroadcast()`, instead of under its whole scope at connect. diff --git a/test/interop/clients/cpp/main.cpp b/test/interop/clients/cpp/main.cpp index 64831d6f13d..ff4a67b93ca 100644 --- a/test/interop/clients/cpp/main.cpp +++ b/test/interop/clients/cpp/main.cpp @@ -68,7 +68,8 @@ std::shared_ptr open_session; [[noreturn]] void exit_failed() { // Taken first, so a failure while closing cannot close it again. if (auto session = std::exchange(open_session, nullptr)) { - session->shutdown().wait_for(std::chrono::seconds(5)); + session->shutdown(); + session->closed().wait_for(std::chrono::seconds(5)); } std::exit(1); } @@ -151,7 +152,8 @@ std::shared_ptr connect(const std::string &url, const Dial &dial, // once, and stopping the runtime right after it can leave the relay to time the connection out. void close_session(const std::shared_ptr &session) { open_session = nullptr; - until(session->shutdown(), Clock::now() + std::chrono::seconds(5), "session shutdown"); + session->shutdown(); + until(session->closed(), Clock::now() + std::chrono::seconds(5), "session shutdown"); } // Feeds the encoder a real-time tone per channel, interleaved, until `stop` is set. From 95d9a366e1112b3a744b71c844ecbbc40eb644fa Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Thu, 22 Oct 2026 19:11:12 -0700 Subject: [PATCH 3/4] fix(ffi): serialize shutdown completion publication Co-Authored-By: GPT-6 --- rs/moq-ffi/src/session.rs | 60 +++++++++++++++++++++------------------ rs/moq-ffi/src/test.rs | 9 +++++- 2 files changed, 41 insertions(+), 28 deletions(-) diff --git a/rs/moq-ffi/src/session.rs b/rs/moq-ffi/src/session.rs index 4698edc37b8..c8fc63e8189 100644 --- a/rs/moq-ffi/src/session.rs +++ b/rs/moq-ffi/src/session.rs @@ -931,6 +931,7 @@ impl Accepted { } /// An owned drain; dropping its waiter or the foreign session cannot cancel it. +#[derive(Clone)] struct Shutdown { result: kio::Consumer>>, task: crate::ffi::Background, @@ -957,7 +958,7 @@ impl Shutdown { #[derive(uniffi::Object)] pub struct MoqSession { inner: Inner, - shutdown: std::sync::OnceLock, + shutdown: std::sync::Mutex>, /// Serializes `closed()` calls onto the FFI runtime; holds its own `Inner` clone /// so a parked `closed()` doesn't block the rest of the surface. closed: Task, @@ -1054,7 +1055,7 @@ impl Drop for MoqSession { // lingering CLOSE task, which panics if no reactor is in context. We can't leave this to the last `Session` clone's drop: clones // live in the `closed`/`status` tasks and the connection state, released after // this guard, off-runtime. Close-once dedup then makes those trailing drops no-ops. - if self.shutdown.get().is_none() { + if self.shutdown.get_mut().unwrap().is_none() { self.teardown(moq_net::Error::Cancel); } } @@ -1081,7 +1082,10 @@ impl MoqSession { } })) .await; - match self.shutdown.get() { + // The client loop can stop as soon as the drain starts. Serialize this read + // with publication so an existing waiter cannot miss the drain's result. + let shutdown = self.shutdown.lock().unwrap().clone(); + match shutdown { Some(shutdown) => shutdown.finished().await, None => terminal, } @@ -1144,31 +1148,33 @@ impl MoqSession { /// A drain that takes longer than one second ends with a delivery timeout. pub fn shutdown(&self) { let _guard = crate::ffi::enter(); - self.shutdown.get_or_init(|| { - let result = kio::Producer::new(None); - let receiver = result.consume(); - let inner = self.inner.clone(); - // Keep the origins, not just the connection, alive through the drain. - let publisher = self.publisher.clone(); - let consumer = self.consumer.clone(); - let task = crate::ffi::spawn(async move { - let completed = match inner { - #[cfg(not(target_arch = "wasm32"))] - Inner::Connection(connection) => connection.close().await.map_err(map_closed_error), - Inner::Session(session) => session.close().await, - }; - let completed = publisher - .inner() - .driver - .check() - .and(consumer.driver.check()) - .and(completed); - *result - .write() - .unwrap_or_else(|_| unreachable!("the drain owns its completion")) = Some(completed); - }); - Shutdown { result: receiver, task } + let mut shutdown = self.shutdown.lock().unwrap(); + if shutdown.is_some() { + return; + } + let result = kio::Producer::new(None); + let receiver = result.consume(); + let inner = self.inner.clone(); + // Keep the origins, not just the connection, alive through the drain. + let publisher = self.publisher.clone(); + let consumer = self.consumer.clone(); + let task = crate::ffi::spawn(async move { + let completed = match inner { + #[cfg(not(target_arch = "wasm32"))] + Inner::Connection(connection) => connection.close().await.map_err(map_closed_error), + Inner::Session(session) => session.close().await, + }; + let completed = publisher + .inner() + .driver + .check() + .and(consumer.driver.check()) + .and(completed); + *result + .write() + .unwrap_or_else(|_| unreachable!("the drain owns its completion")) = Some(completed); }); + *shutdown = Some(Shutdown { result: receiver, task }); } /// The publish-side origin: where local broadcasts get advertised diff --git a/rs/moq-ffi/src/test.rs b/rs/moq-ffi/src/test.rs index eecad2664ff..fec577fee83 100644 --- a/rs/moq-ffi/src/test.rs +++ b/rs/moq-ffi/src/test.rs @@ -7198,8 +7198,15 @@ async fn shutdown_times_out_on_an_unfinished_track() { shutdown_ready(&track, &reader).await; let receiving = tokio::spawn(async move { reader.read_frame().await }); let start = moq_clock::Instant::now(); + let mut closed = Box::pin(publisher.closed()); + assert!( + closed + .as_mut() + .poll(&mut std::task::Context::from_waker(std::task::Waker::noop())) + .is_pending() + ); publisher.shutdown(); - let err = tokio::time::timeout(TIMEOUT, publisher.closed()) + let err = tokio::time::timeout(TIMEOUT, closed) .await .expect("shutdown") .expect_err("unfinished track must time out"); From 8c68d5dece7793b95fe5920e6d41475db4047b29 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Fri, 23 Oct 2026 17:07:08 -0700 Subject: [PATCH 4/4] fix(obs): wait out retired drains before module unload moq_ffi_shutdown() drops every runtime task, so an owned drain still running when OBS unloads the module on exit was cancelled. Keep each retired session's closed() waiter and let the destructor wait them out. Note in the Kotlin migration that moq.shutdown() no longer releases the client. Co-Authored-By: Claude Opus 5.5 --- cpp/obs/MIGRATE.md | 5 ----- cpp/obs/src/moq-output.cpp | 22 ++++++++++++++++++- cpp/obs/src/moq-output.h | 4 ++++ doc/bin/obs.md | 2 +- kt/moq/MIGRATE.md | 2 +- .../jvmAndAndroidMain/kotlin/dev/moq/Moq.kt | 3 ++- 6 files changed, 29 insertions(+), 9 deletions(-) diff --git a/cpp/obs/MIGRATE.md b/cpp/obs/MIGRATE.md index f1edc7a4215..398682fc872 100644 --- a/cpp/obs/MIGRATE.md +++ b/cpp/obs/MIGRATE.md @@ -4,11 +4,6 @@ How to update your OBS setup for each breaking change, newest first. ## Unreleased -### Shutdown requests the drain synchronously - -Stopping an output requests an owned native drain; output destruction no longer retains or waits on shutdown futures. Finished tracks still drain after the output is disposed. Wait on a session's `closed()` before global runtime shutdown when its result is needed. -When upgrading from the release-line additive async `drain()` backport, replace an async session `drain()` with synchronous `shutdown()` followed by `closed()`; `main` has no separate `drain()` method. - ### Key logging is opt-in (#5907) `SSLKEYLOGFILE` alone no longer writes TLS session secrets. diff --git a/cpp/obs/src/moq-output.cpp b/cpp/obs/src/moq-output.cpp index b51b6accb13..f393b845597 100644 --- a/cpp/obs/src/moq-output.cpp +++ b/cpp/obs/src/moq-output.cpp @@ -103,6 +103,16 @@ MoQOutput::~MoQOutput() // stop on an output that is going away. Stop(); + // Wait out the drains: OBS unloads the module, stopping the runtime, right + // after destroying its outputs on exit. moq-ffi bounds each drain to about a second. + std::vector> drains; + { + std::lock_guard signal_lock(signal_mutex); + drains.swap(draining); + } + for (auto &drain : drains) + drain.wait(); + // Drops whatever is still queued and waits out a continuation in flight, which // may be parked on signal_mutex; so this must not hold it. Nothing touches this // object once it returns. @@ -436,8 +446,18 @@ void MoQOutput::Reset() origin.reset(); // The session owns the drain after this request, even if the output dies now. - if (retired) + // Keep a waiter only so the destructor can hold off module unload, which + // stops the runtime and would cancel the drain. + if (retired) { retired->shutdown(); + draining.erase(std::remove_if(draining.begin(), draining.end(), + [](const moq::Future &drain) { + return drain.wait_for(std::chrono::seconds(0)) == + std::future_status::ready; + }), + draining.end()); + draining.push_back(retired->closed()); + } lock.unlock(); diff --git a/cpp/obs/src/moq-output.h b/cpp/obs/src/moq-output.h index d1421e6cf98..e95f2525a7a 100644 --- a/cpp/obs/src/moq-output.h +++ b/cpp/obs/src/moq-output.h @@ -201,6 +201,10 @@ class MoQOutput { // read empty while disconnected and resume on the next connection. std::shared_ptr bandwidth; + // `closed()` of retired sessions still draining, which the destructor waits + // out. Guarded by signal_mutex. + std::vector> draining; + std::string path; size_t total_bytes_sent; diff --git a/doc/bin/obs.md b/doc/bin/obs.md index 82a59bc1134..5bce66618d5 100644 --- a/doc/bin/obs.md +++ b/doc/bin/obs.md @@ -95,7 +95,7 @@ alone writes nothing, and the toggle without it fails the connection. The plugin is C++ over the [generated C++ bindings](/lib/cpp/) and ships with every moq-cpp release. Stopping finishes the tracks and drains for up to one -second. The native runtime owns the drain even when the output is destroyed. The default lite-06 waits for transport ACKs, which do not confirm that +second. The default lite-06 waits for transport ACKs, which do not confirm that the peer received the tail. If the relay closes the session for too many requests, reduce the broadcasts diff --git a/kt/moq/MIGRATE.md b/kt/moq/MIGRATE.md index 307038049ca..23cb133f163 100644 --- a/kt/moq/MIGRATE.md +++ b/kt/moq/MIGRATE.md @@ -6,7 +6,7 @@ How to update your code for each breaking change, newest first. ### Shutdown requests the drain synchronously -`session.shutdown()` and `moq.shutdown()` request a drain synchronously. Await `session.closed()` (or `moq.session.closed()`) to wait and report delivery failures. `Moq.close()` still cancels immediately. +`session.shutdown()` and `moq.shutdown()` request a drain synchronously. Await `session.closed()` (or `moq.session.closed()`) to wait and report delivery failures. `moq.shutdown()` no longer releases the client, so close the `Moq` (or leave its `use { }`) after `closed()` returns; `Moq.close()` still cancels immediately. When upgrading from the release-line additive async `drain()` backport, replace suspending `session.drain()` with `session.shutdown(); session.closed()`; `main` has no separate `drain()` method. ### Video rendition preference diff --git a/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/Moq.kt b/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/Moq.kt index 9d5e51391cf..a77f30d9993 100644 --- a/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/Moq.kt +++ b/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/Moq.kt @@ -77,7 +77,8 @@ class Moq internal constructor( fun auth(): Auth = session.auth() /** - * Request a draining close now; await `session.closed()` for its result. + * Request a draining close now; await `session.closed()` for its result, then [close] + * to release the client. * Explicit `moq-lite-07-wip` waits for the peer to receive finished tails; older * Lite versions, including the default lite-06, wait only for transport ACKs. * IETF also waits for transport ACKs.