diff --git a/cpp/obs/src/moq-output.cpp b/cpp/obs/src/moq-output.cpp index 9b140785e60..83bda0a2387 100644 --- a/cpp/obs/src/moq-output.cpp +++ b/cpp/obs/src/moq-output.cpp @@ -86,8 +86,8 @@ 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. + // 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); @@ -401,18 +401,20 @@ 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. + // The session owns the drain after this request, even if the output dies now. + // 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->shutdown()); + draining.push_back(retired->closed()); } + lock.unlock(); for (auto &[encoder, bitrate] : restore) diff --git a/cpp/obs/src/moq-output.h b/cpp/obs/src/moq-output.h index 2f6da43221e..036a7d580bb 100644 --- a/cpp/obs/src/moq-output.h +++ b/cpp/obs/src/moq-output.h @@ -196,8 +196,8 @@ 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. + // `closed()` of retired sessions still draining, which the destructor waits + // out. Guarded by signal_mutex. std::vector> draining; std::string path; diff --git a/dart/moq/lib/src/client.dart b/dart/moq/lib/src/client.dart index dd15f1e463e..a12fdd00929 100644 --- a/dart/moq/lib/src/client.dart +++ b/dart/moq/lib/src/client.dart @@ -265,7 +265,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/lib/src/moq.dart b/dart/moq_ffi/lib/src/moq.dart index 48f643ad1af..fbcfe89e19e 100644 --- a/dart/moq_ffi/lib/src/moq.dart +++ b/dart/moq_ffi/lib/src/moq.dart @@ -13388,7 +13388,7 @@ abstract class MoqSessionInterface { MoqOriginConsumer consume(); MoqOriginProducer publish(); MoqBandwidthConsumer? recvBandwidth(); - UniffiRustFuture shutdown(); + void shutdown(); MoqConnectionState state(); UniffiRustFuture stateChanged({required int after}); MoqConnectionStats stats(); @@ -13502,16 +13502,13 @@ class MoqSession implements MoqSessionInterface { ); } - UniffiRustFuture 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_cancel_void, - ffi_moq_ffi_rust_future_free_void, - (_) {}, - moqExceptionErrorHandler, - ); + void shutdown() { + return rustCall((status) { + uniffi_moq_ffi_fn_method_moqsession_shutdown( + uniffiClonePointer(), + status, + ); + }, null); } MoqConnectionState state() { @@ -18845,9 +18842,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)>( @@ -20701,7 +20701,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() != 8167) { + if (uniffi_moq_ffi_checksum_method_moqsession_closed() != 9326) { throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); } if (uniffi_moq_ffi_checksum_method_moqsession_consume() != 57909) { @@ -20713,7 +20713,7 @@ 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_state() != 32292) { diff --git a/doc/lib/c/index.md b/doc/lib/c/index.md index 2c292d6edad..57e661339a7 100644 --- a/doc/lib/c/index.md +++ b/doc/lib/c/index.md @@ -60,7 +60,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. A session reports on a `moq_state_callback` instead: each `moq_connection_state` carries its `phase`, `connects`, the negative `failure` of the latest attempt, and the live `protocol`, and the `MOQ_CONNECTION_PHASE_CLOSED` snapshot is terminal, delivered after the handle is released. +- **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. A session reports on a `moq_state_callback` instead: each `moq_connection_state` carries its `phase`, `connects`, the negative `failure` of the latest attempt, and the live `protocol`, and the `MOQ_CONNECTION_PHASE_CLOSED` snapshot is terminal, delivered after the handle is released. `moq_session_close()` drains finished tracks for dialed and accepted sessions; wait for that terminal snapshot 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 73b1dbcbca7..41fe064fb50 100644 --- a/doc/lib/cpp/index.md +++ b/doc/lib/cpp/index.md @@ -213,7 +213,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 87da0c36b5e..43b86ca64f5 100644 --- a/doc/lib/dart/index.md +++ b/doc/lib/dart/index.md @@ -141,7 +141,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. Awaiting cancellation of an announcement, grant, or request subscription releases its pending native read. Announcements also release their cursor; authorization and server listeners leave their shared owner 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. +- **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 also release their cursor; authorization and server listeners leave their shared owner 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 `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. An unreferenced `BroadcastFinish` closes the broadcast only when the garbage collector reclaims it, possibly long after, so wait on or close it rather than dropping it. - **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. 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-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 64305e23b90..e23327d3aed 100644 --- a/doc/lib/go/index.md +++ b/doc/lib/go/index.md @@ -129,7 +129,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. An unreferenced `*BroadcastFinish` closes the broadcast only when the garbage collector reclaims it, possibly long after, so wait on or close it rather than dropping it. - **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 `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 f34a154df27..7294f2ce8c2 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() } ``` @@ -100,7 +101,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. An unreferenced `BroadcastFinish` closes the broadcast only when the garbage collector reclaims it, possibly long after, so wait on or close it rather than dropping it. - **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. 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-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 e18ba4772d8..4b31eaa602f 100644 --- a/doc/lib/py/index.md +++ b/doc/lib/py/index.md @@ -115,7 +115,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. 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 `Bandwidth.Consumer` 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-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 87678487a21..95fe2fb586b 100644 --- a/doc/lib/swift/index.md +++ b/doc/lib/swift/index.md @@ -86,7 +86,8 @@ try audio.finish() try video.finish() try broadcast.close() -try await session.shutdown() +session.shutdown() +try await session.closed() ``` Raw video encoders take an exact numerator/denominator frame rate, such as 30000/1001. Pass the publication track name to the producer, alongside its input and codec settings. @@ -100,7 +101,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. 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 `Bandwidth.Consumer` 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-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/wrapper/client.go b/go/wrapper/client.go index 15733de285c..e97b4a079c5 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 16a1c248241..2af7b7246df 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 { @@ -179,13 +180,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/src/jvmAndAndroidMain/kotlin/dev/moq/Moq.kt b/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/Moq.kt index 1dc8addd5f6..4fd1f624deb 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( @@ -69,17 +69,14 @@ 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, 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. */ - suspend fun shutdown() { - try { - session.shutdown() - } finally { - client.cancel() - } + fun shutdown() { + session.shutdown() } /** Cancel immediately and release the client. */ diff --git a/py/moq-rs/README.md b/py/moq-rs/README.md index 5a84e8a11f2..ac5faf8750d 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`**. A connection, connecting or connected. 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. - `.state()` and `await .state_changed(after)`. Read one lifecycle snapshot and wait with its revision; first-dial failures and reconnects share the same session. diff --git a/py/moq-rs/moq/client.py b/py/moq-rs/moq/client.py index ed7c2a77c8b..c609dfc69de 100644 --- a/py/moq-rs/moq/client.py +++ b/py/moq-rs/moq/client.py @@ -178,7 +178,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 6ffe9dda56a..acf7fce30cb 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:`state_changed` 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() def state(self) -> ConnectionState: @@ -62,14 +64,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 b25e1a2af05..ce9b96d0d35 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -102,7 +102,6 @@ audit's receive-memory, priority, and lease bugs rank ahead of that reshape. - [Rust request credit](/quest/m1/rs-request-credit.md) - a moq-net request fails at once without stream credit instead of waiting - [Generated C bindings](/quest/m1/c/README.md) - C generated from moq-ffi ships as `moq-c` 0.8.0 and replaces the hand-written libmoq - [Exact timestamps in every binding](/quest/m1/binding-timestamps.md) - bindings carry `{value, scale}` timestamps instead of lossy microseconds -- [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 under the relay conformance profile, except cases that use a subgroup other than 0 - [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 - [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/api-audit/migrate.md b/quest/m1/api-audit/migrate.md index dd33ba38bf9..386725e58b3 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 that names the final API: once [stateless broadcasts](/quest/m1/broadcast-lifecycle/stateless.md) diff --git a/quest/m1/ffi-shutdown-sync.md b/quest/m1/ffi-shutdown-sync.md deleted file mode 100644 index 12a948acedd..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, and the Impact bullet says how to migrate 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 the Impact bullet. - -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/src/session.rs b/rs/moq-c/src/session.rs index eef6651fd1c..33b187a1123 100644 --- a/rs/moq-c/src/session.rs +++ b/rs/moq-c/src/session.rs @@ -239,7 +239,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 a07199245b5..7423725b216 100644 --- a/rs/moq-c/src/test.rs +++ b/rs/moq-c/src/test.rs @@ -5765,12 +5765,36 @@ 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"); let terminal = session_cb.recv_terminal(); assert_eq!((terminal.failure, terminal.connects), (0, 1)); + 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/src/error.rs b/rs/moq-ffi/src/error.rs index cc29d2bd5f0..d736221e88a 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 06a688d13f5..137a068ad84 100644 --- a/rs/moq-ffi/src/session.rs +++ b/rs/moq-ffi/src/session.rs @@ -899,10 +899,35 @@ 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, +} + +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::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, @@ -965,6 +990,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()), publisher, consumer, @@ -1000,7 +1026,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` task 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_mut().unwrap().is_none() { + self.teardown(moq_net::Error::Cancel); + } } } @@ -1011,22 +1039,30 @@ 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 [`state_changed`](Self::state_changed) 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), - #[cfg(not(target_arch = "wasm32"))] - Inner::Session(session) => session.closed().await, - #[cfg(target_arch = "wasm32")] - Inner::Dial(dial) => dial.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), + #[cfg(not(target_arch = "wasm32"))] + Inner::Session(session) => session.closed().await, + #[cfg(target_arch = "wasm32")] + Inner::Dial(dial) => dial.closed().await, + } + })) + .await; + // 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, + } } /// Read the connection lifecycle fields together without advancing any watcher. @@ -1084,29 +1120,47 @@ 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> { + /// 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(); + 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(); - let result = crate::ffi::detached(async move { - match inner { + // 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), #[cfg(not(target_arch = "wasm32"))] Inner::Session(session) => session.close().await, #[cfg(target_arch = "wasm32")] Inner::Dial(dial) => dial.close().await, - } - }) - .await; - self.publisher.inner().driver.check()?; - self.consumer.driver.check()?; - result + }; + 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 8a59c8bff7c..b15f6172d97 100644 --- a/rs/moq-ffi/src/test.rs +++ b/rs/moq-ffi/src/test.rs @@ -5284,7 +5284,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(); } @@ -5397,14 +5398,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()); } @@ -5662,7 +5665,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(); } @@ -7374,6 +7378,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) { @@ -7464,7 +7570,8 @@ async fn shutdown_delivers_the_finished_track() { })?; group.finish()?; track.finish()?; - closing.shutdown().await?; + closing.shutdown(); + closing.closed().await?; Ok::<(), MoqError>(()) }), ) @@ -7503,7 +7610,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 err = tokio::time::timeout(TIMEOUT, publisher.shutdown()) + 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, closed) .await .expect("shutdown") .expect_err("unfinished track must time out"); diff --git a/swift/README.md b/swift/README.md index 9f4e11e2d2e..84d598e4fb1 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 cfdfc349968..c4e602ecb85 100644 --- a/swift/Sources/Moq/Client.swift +++ b/swift/Sources/Moq/Client.swift @@ -99,7 +99,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 `stateChanged(after:)` for those. public func closed() async throws { try await ffi.closed() @@ -121,12 +122,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/test/interop/clients/cpp/main.cpp b/test/interop/clients/cpp/main.cpp index c77c42e00f4..f58605b0a9d 100644 --- a/test/interop/clients/cpp/main.cpp +++ b/test/interop/clients/cpp/main.cpp @@ -70,7 +70,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); } @@ -153,7 +154,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.