diff --git a/cpp/moq/MIGRATE.md b/cpp/moq/MIGRATE.md index 8aa26869dfd..ec0b7243cd4 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 +### Finished tracks stay until the broadcast ends (#6157) + +A finished track now stays listed, with its catalog rendition and demand, until its broadcast closes or the new `BroadcastProducer::finish` lets go. +Publish a replacement under a new name, and expect a finished track's demand watch to end with the broadcast. + ### A claim answers by publishing (#5678) `OriginProducer::dynamic(prefix)` takes no route, and `OriginDynamic::update` is gone. diff --git a/cpp/moq/test/probe.cpp b/cpp/moq/test/probe.cpp index 678b7118f3e..d2c07c81c6d 100644 --- a/cpp/moq/test/probe.cpp +++ b/cpp/moq/test/probe.cpp @@ -109,6 +109,18 @@ int main() { CHECK(!moq::MediaTimebase::init(timebase_owner)); ok(timebase_other->close(), "close timebase other"); + // A finished broadcast lingers for its longest max age; closing the handle ends the wait early. + auto finished = ok(moq::BroadcastProducer::init(), "finished broadcast"); + moq::TrackInfo aged; + aged.max_age_us = 3600000000; + ok(ok(finished->publish_track("status", aged), "publish aged track")->finish(), "finish aged track"); + auto finish = ok(finished->finish(), "broadcast finish"); + CHECK(finish->linger_us() == 3600000000); + CHECK(!finished->publish_track("events", {})); + auto lingering = finish->wait(); + finish->close(); + ok(lingering.get(), "finish wait"); + // A synchronous error is a returned value, not an exception. auto unbound = ok(moq::Server::init({}), "server init"); auto fingerprints = unbound->cert_fingerprints(); diff --git a/dart/moq/MIGRATE.md b/dart/moq/MIGRATE.md index aba199c2d55..7a1f1be6ca3 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 +### Finished tracks stay until the broadcast ends (#6157) + +A finished track now stays listed, with its catalog rendition and demand, until its broadcast closes or the new `BroadcastProducer.finish()` lets go. +Publish a replacement under a new name, and expect a finished track's demand watch to end with the broadcast. + ### A claim answers by publishing (#5678) `origin.dynamic_(prefix:)` takes no route, and `update` is gone. diff --git a/dart/moq/lib/src/aliases.dart b/dart/moq/lib/src/aliases.dart index 5ec3cc7f852..d026dbbf33a 100644 --- a/dart/moq/lib/src/aliases.dart +++ b/dart/moq/lib/src/aliases.dart @@ -84,6 +84,10 @@ typedef BroadcastConsumer = MoqBroadcastConsumer; /// Receives tracks requested from a dynamically served broadcast. typedef BroadcastDynamic = MoqBroadcastDynamic; +/// A cleanly ended broadcast, still announced and serving its finished tracks +/// until its linger ends; close it to end the linger early. +typedef BroadcastFinish = MoqBroadcastFinish; + /// The write side of a raw track: append groups of frames. typedef TrackProducer = MoqTrackProducer; diff --git a/dart/moq/lib/src/durations.dart b/dart/moq/lib/src/durations.dart index d5786188a44..f6ffdcaa0aa 100644 --- a/dart/moq/lib/src/durations.dart +++ b/dart/moq/lib/src/durations.dart @@ -46,6 +46,12 @@ extension TrackInfoDuration on MoqTrackInfo { maxAgeUs == null ? null : Duration(microseconds: maxAgeUs!); } +/// Duration view over how long a finished broadcast stays up. +extension BroadcastFinishDuration on MoqBroadcastFinish { + /// The longest max age of the finished tracks the broadcast holds. + Duration get linger => Duration(microseconds: lingerUs()); +} + /// Duration view over a raw frame's presentation time. extension FrameDuration on MoqFrame { /// Presentation timestamp, or null for an untimed frame. diff --git a/dart/moq/test/moq_test.dart b/dart/moq/test/moq_test.dart index f958bb77b8b..aec7681201e 100644 --- a/dart/moq/test/moq_test.dart +++ b/dart/moq/test/moq_test.dart @@ -387,6 +387,26 @@ void main() { second.close(); }); + test('a finished broadcast lingers until closed', () async { + final broadcast = BroadcastProducer(); + final track = broadcast.publishTrack( + name: 'status', + info: TrackInfo(maxAgeUs: 3600000000), + ); + track.finish(); + final finish = broadcast.finish(); + expect(finish.linger, const Duration(hours: 1)); + expect( + () => broadcast.publishTrack(name: 'events', info: null), + throwsA(isA()), + ); + // A Dart future can't be cancelled, so closing is the interrupt: the wait + // ends instead of lingering for an hour. + final wait = finish.wait(); + finish.close(); + await wait.timeout(timeout); + }); + test('microsecond fields read back as Durations', () { final backoff = Backoff(initialUs: 1000, maxUs: 2000, timeoutUs: 3000); expect(backoff.initial, const Duration(milliseconds: 1)); diff --git a/dart/moq_ffi/MIGRATE.md b/dart/moq_ffi/MIGRATE.md index fcfb6c6b00a..3e8c381a845 100644 --- a/dart/moq_ffi/MIGRATE.md +++ b/dart/moq_ffi/MIGRATE.md @@ -4,6 +4,12 @@ How to update your code for each breaking change, newest first. ## Unreleased +### Finished tracks stay until the broadcast ends (#6157) + +A finished track, raw or media, now stays listed, with its catalog rendition and demand, until its broadcast closes or the new `MoqBroadcastProducer.finish()` lets go, instead of unlisting when its producer finishes or is released. +Publish a replacement under a new name, and expect a finished track's demand watch to end with the broadcast. +Regenerate the bindings for the new `MoqBroadcastFinish` and the changed checksums. + ### Regenerate the matching bindings Documentation on `MoqAudioProducer::write` and `finish` changes their UniFFI metadata checksums. diff --git a/dart/moq_ffi/lib/src/moq.dart b/dart/moq_ffi/lib/src/moq.dart index 7ee68359a25..1d0d4121dcd 100644 --- a/dart/moq_ffi/lib/src/moq.dart +++ b/dart/moq_ffi/lib/src/moq.dart @@ -11263,11 +11263,111 @@ class FfiConverterMoqBroadcastDynamic { } } +abstract class MoqBroadcastFinishInterface { + void close(); + int lingerUs(); + Future wait(); +} + +final _MoqBroadcastFinishFinalizer = Finalizer>((ptr) { + rustCall((status) => uniffi_moq_ffi_fn_free_moqbroadcastfinish(ptr, status)); +}); + +class MoqBroadcastFinish implements MoqBroadcastFinishInterface { + late final Pointer _ptr; + bool _isDisposed = false; + MoqBroadcastFinish._(this._ptr) { + _MoqBroadcastFinishFinalizer.attach(this, _ptr, detach: this); + } + factory MoqBroadcastFinish.lift(Pointer ptr) { + return MoqBroadcastFinish._(ptr); + } + Pointer uniffiClonePointer() { + if (_isDisposed) { + throw StateError("Object has already been disposed"); + } + return rustCall( + (status) => uniffi_moq_ffi_fn_clone_moqbroadcastfinish(_ptr, status), + ); + } + + void dispose() { + if (_isDisposed) { + return; + } + _isDisposed = true; + _MoqBroadcastFinishFinalizer.detach(this); + rustCall( + (status) => uniffi_moq_ffi_fn_free_moqbroadcastfinish(_ptr, status), + ); + } + + void close() { + return rustCall((status) { + uniffi_moq_ffi_fn_method_moqbroadcastfinish_close( + uniffiClonePointer(), + status, + ); + }, null); + } + + int lingerUs() { + return rustCallWithLifter( + (status) => uniffi_moq_ffi_fn_method_moqbroadcastfinish_linger_us( + uniffiClonePointer(), + status, + ), + FfiConverterUInt64.lift, + null, + ); + } + + Future wait() { + return uniffiRustCallAsync( + () => uniffi_moq_ffi_fn_method_moqbroadcastfinish_wait( + uniffiClonePointer(), + ), + ffi_moq_ffi_rust_future_poll_void, + ffi_moq_ffi_rust_future_complete_void, + ffi_moq_ffi_rust_future_free_void, + (_) {}, + moqExceptionErrorHandler, + ); + } +} + +class FfiConverterMoqBroadcastFinish { + static MoqBroadcastFinish lift(Pointer ptr) { + return MoqBroadcastFinish.lift(ptr); + } + + static Pointer lower(MoqBroadcastFinish value) { + return value.uniffiClonePointer(); + } + + static int allocationSize(MoqBroadcastFinish value) { + return 8; + } + + static LiftRetVal read(Uint8List buf) { + final handle = buf.buffer.asByteData(buf.offsetInBytes).getInt64(0); + final pointer = Pointer.fromAddress(handle); + return LiftRetVal(MoqBroadcastFinish.lift(pointer), 8); + } + + static int write(MoqBroadcastFinish value, Uint8List buf) { + final handle = lower(value); + buf.buffer.asByteData(buf.offsetInBytes).setInt64(0, handle.address); + return 8; + } +} + abstract class MoqBroadcastProducerInterface { void announce({required MoqRoute route}); void close(); MoqBroadcastConsumer consume(); MoqBroadcastDynamic dynamic_(); + MoqBroadcastFinish finish(); MoqTrackProducer publishTrack({ required String name, required MoqTrackInfo? info, @@ -11359,6 +11459,17 @@ class MoqBroadcastProducer implements MoqBroadcastProducerInterface { ); } + MoqBroadcastFinish finish() { + return rustCallWithLifter( + (status) => uniffi_moq_ffi_fn_method_moqbroadcastproducer_finish( + uniffiClonePointer(), + status, + ), + FfiConverterMoqBroadcastFinish.lift, + moqExceptionErrorHandler, + ); + } + MoqTrackProducer publishTrack({ required String name, required MoqTrackInfo? info, @@ -17098,6 +17209,43 @@ external void uniffi_moq_ffi_fn_method_moqbroadcastdynamic_cancel( external Pointer uniffi_moq_ffi_fn_method_moqbroadcastdynamic_requested_track(Pointer ptr); +@Native Function(Pointer, Pointer)>( + assetId: _uniffiAssetId, +) +external Pointer uniffi_moq_ffi_fn_clone_moqbroadcastfinish( + Pointer handle, + Pointer uniffiStatus, +); + +@Native, Pointer)>( + assetId: _uniffiAssetId, +) +external void uniffi_moq_ffi_fn_free_moqbroadcastfinish( + Pointer handle, + Pointer uniffiStatus, +); + +@Native, Pointer)>( + assetId: _uniffiAssetId, +) +external void uniffi_moq_ffi_fn_method_moqbroadcastfinish_close( + Pointer ptr, + Pointer uniffiStatus, +); + +@Native, Pointer)>( + assetId: _uniffiAssetId, +) +external int uniffi_moq_ffi_fn_method_moqbroadcastfinish_linger_us( + Pointer ptr, + Pointer uniffiStatus, +); + +@Native Function(Pointer)>(assetId: _uniffiAssetId) +external Pointer uniffi_moq_ffi_fn_method_moqbroadcastfinish_wait( + Pointer ptr, +); + @Native Function(Pointer, Pointer)>( assetId: _uniffiAssetId, ) @@ -17154,6 +17302,14 @@ external Pointer uniffi_moq_ffi_fn_method_moqbroadcastproducer_dynamic( Pointer uniffiStatus, ); +@Native Function(Pointer, Pointer)>( + assetId: _uniffiAssetId, +) +external Pointer uniffi_moq_ffi_fn_method_moqbroadcastproducer_finish( + Pointer ptr, + Pointer uniffiStatus, +); + @Native< Pointer Function( Pointer, @@ -18711,6 +18867,15 @@ external int uniffi_moq_ffi_checksum_method_moqbroadcastdynamic_cancel(); external int uniffi_moq_ffi_checksum_method_moqbroadcastdynamic_requested_track(); +@Native(assetId: _uniffiAssetId) +external int uniffi_moq_ffi_checksum_method_moqbroadcastfinish_close(); + +@Native(assetId: _uniffiAssetId) +external int uniffi_moq_ffi_checksum_method_moqbroadcastfinish_linger_us(); + +@Native(assetId: _uniffiAssetId) +external int uniffi_moq_ffi_checksum_method_moqbroadcastfinish_wait(); + @Native(assetId: _uniffiAssetId) external int uniffi_moq_ffi_checksum_method_moqbroadcastproducer_announce(); @@ -18723,6 +18888,9 @@ external int uniffi_moq_ffi_checksum_method_moqbroadcastproducer_consume(); @Native(assetId: _uniffiAssetId) external int uniffi_moq_ffi_checksum_method_moqbroadcastproducer_dynamic(); +@Native(assetId: _uniffiAssetId) +external int uniffi_moq_ffi_checksum_method_moqbroadcastproducer_finish(); + @Native(assetId: _uniffiAssetId) external int uniffi_moq_ffi_checksum_method_moqbroadcastproducer_publish_track(); @@ -19090,7 +19258,7 @@ void _checkApiChecksums() { if (uniffi_moq_ffi_checksum_method_moqaudioproducer_demand() != 42822) { throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); } - if (uniffi_moq_ffi_checksum_method_moqaudioproducer_finish() != 52976) { + if (uniffi_moq_ffi_checksum_method_moqaudioproducer_finish() != 14521) { throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); } if (uniffi_moq_ffi_checksum_method_moqaudioproducer_reanchor() != 34412) { @@ -19279,7 +19447,7 @@ void _checkApiChecksums() { throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); } if (uniffi_moq_ffi_checksum_method_moqmediacontainerproducer_finish() != - 5827) { + 25121) { throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); } if (uniffi_moq_ffi_checksum_method_moqmediacontainerproducer_seek() != 6771) { @@ -19315,7 +19483,7 @@ void _checkApiChecksums() { 32931) { throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); } - if (uniffi_moq_ffi_checksum_method_moqmediatrackproducer_finish() != 15731) { + if (uniffi_moq_ffi_checksum_method_moqmediatrackproducer_finish() != 45426) { throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); } if (uniffi_moq_ffi_checksum_method_moqmediatrackproducer_flush() != 51126) { @@ -19333,7 +19501,7 @@ void _checkApiChecksums() { throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); } if (uniffi_moq_ffi_checksum_method_moqmediatrackstreamproducer_finish() != - 6627) { + 2377) { throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); } if (uniffi_moq_ffi_checksum_method_moqmediatrackstreamproducer_write() != @@ -19404,6 +19572,15 @@ void _checkApiChecksums() { 5884) { throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); } + if (uniffi_moq_ffi_checksum_method_moqbroadcastfinish_close() != 21540) { + throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); + } + if (uniffi_moq_ffi_checksum_method_moqbroadcastfinish_linger_us() != 30748) { + throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); + } + if (uniffi_moq_ffi_checksum_method_moqbroadcastfinish_wait() != 36521) { + throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); + } if (uniffi_moq_ffi_checksum_method_moqbroadcastproducer_announce() != 13700) { throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); } @@ -19416,6 +19593,9 @@ void _checkApiChecksums() { if (uniffi_moq_ffi_checksum_method_moqbroadcastproducer_dynamic() != 55635) { throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); } + if (uniffi_moq_ffi_checksum_method_moqbroadcastproducer_finish() != 50394) { + throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); + } if (uniffi_moq_ffi_checksum_method_moqbroadcastproducer_publish_track() != 44452) { throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); @@ -19483,7 +19663,7 @@ void _checkApiChecksums() { if (uniffi_moq_ffi_checksum_method_moqtrackproducer_dynamic() != 58584) { throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); } - if (uniffi_moq_ffi_checksum_method_moqtrackproducer_finish() != 3278) { + if (uniffi_moq_ffi_checksum_method_moqtrackproducer_finish() != 38052) { throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); } if (uniffi_moq_ffi_checksum_method_moqtrackproducer_finish_at() != 24581) { @@ -19628,7 +19808,7 @@ void _checkApiChecksums() { if (uniffi_moq_ffi_checksum_method_moqvideoproducer_demand() != 283) { throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); } - if (uniffi_moq_ffi_checksum_method_moqvideoproducer_finish() != 59081) { + if (uniffi_moq_ffi_checksum_method_moqvideoproducer_finish() != 40208) { throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); } if (uniffi_moq_ffi_checksum_method_moqvideoproducer_reservation() != 64430) { diff --git a/doc/lib/c/index.md b/doc/lib/c/index.md index 0eb9fbaa143..c498dbe57cc 100644 --- a/doc/lib/c/index.md +++ b/doc/lib/c/index.md @@ -64,6 +64,7 @@ inside. The header is the reference: each function carries a doc comment. - **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`. - **Compressed tracks.** `moq_track_info.compress` on a raw track sends each group DEFLATE-compressed to opt-in `moq-lite-07-wip` peers; other peers, and every reader here, get the original frames. `@moq/net` cannot read a compressed track yet. - **Audio needs cuts.** Video groups at its keyframes, but audio forms a group only where you call `moq_publish_media_cut`: after every frame, or at a segment cadence to align with video. +- **Ending cleanly.** When the input ends, finish every track, then call `moq_publish_finish()`. It consumes the broadcast and returns a finish handle that keeps it announced and serving the finished tracks, writing the linger, their longest max age, to `linger_us`. Keep the handle for that long on your own clock so a subscriber still catching up can drain them, then `moq_publish_finish_close()` it; closing early is the interrupt. `moq_publish_close()` stays the abrupt end. - **Live encoder timing.** After writing a frame you encoded yourself, call `moq_publish_media_flush` with the same timestamp so the catalog advertises your jitter. Skip it for file and network imports. On a seek or pause, call `moq_publish_media_discontinuity`, then keep timestamps moving forward and resume video on a keyframe. - **JSON values.** `moq_consume_json_value` fills `moq_json_value` with the document and its frame's `timestamp_us`, rounded down to a whole microsecond; `timestamp_present` is false on an untimed track. A snapshot consumer's callback fires for each state in order, but a group superseded before it is read is skipped. - **Decoded frames hold decoder buffers.** Free each frame id with `moq_decode_video_frame_free` promptly, or the decoder stalls. diff --git a/doc/lib/cpp/index.md b/doc/lib/cpp/index.md index ab3b7c2e2f6..bf6baaa3cd1 100644 --- a/doc/lib/cpp/index.md +++ b/doc/lib/cpp/index.md @@ -215,6 +215,13 @@ 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. +To end a broadcast cleanly, finish every track, then call `broadcast->finish()`. +The returned `moq::BroadcastFinish` keeps the broadcast announced and serving the +finished tracks for `linger_us()`, their longest max age, so a subscriber still +catching up can drain them. `finish->wait()` resolves once the linger passes, and +`finish->close()` closes the broadcast at once, resolving the wait. +`broadcast->close()` stays the abrupt end. + `moq::shutdown()` stops the `moq-ffi` runtime workers, then the executor. Pending calls resolve `Cancelled`, and every object stays safe to drop. Call it once before a plugin or engine module unloads, from a thread that is not diff --git a/doc/lib/dart/index.md b/doc/lib/dart/index.md index a7038d555d5..92146a65564 100644 --- a/doc/lib/dart/index.md +++ b/doc/lib/dart/index.md @@ -136,6 +136,7 @@ shows which module holds each. - **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. +- **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. - **Errors.** Read diagnostic payloads from `reason` and structured protocol failures from `details`. diff --git a/doc/lib/go/index.md b/doc/lib/go/index.md index ae7cc6a3776..545793d4dbd 100644 --- a/doc/lib/go/index.md +++ b/doc/lib/go/index.md @@ -126,6 +126,7 @@ shows which module holds each. - **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. +- **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. - **Errors.** Read diagnostic payloads from `Reason` and structured protocol failures from `Details`. diff --git a/doc/lib/kt/index.md b/doc/lib/kt/index.md index ea0004a54a9..5632dddf2c4 100644 --- a/doc/lib/kt/index.md +++ b/doc/lib/kt/index.md @@ -98,6 +98,7 @@ shows which module holds each. - **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. +- **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. - **Errors.** Read diagnostic payloads from `reason` and structured protocol failures from `details`. diff --git a/doc/lib/py/index.md b/doc/lib/py/index.md index 3b0974b412f..3170d27e35f 100644 --- a/doc/lib/py/index.md +++ b/doc/lib/py/index.md @@ -113,6 +113,7 @@ shows which module holds each. - **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. +- **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. - **Errors.** Read diagnostic payloads from `reason` and structured protocol failures from `details`. diff --git a/doc/lib/swift/index.md b/doc/lib/swift/index.md index 3fe646d2d46..58eeea26118 100644 --- a/doc/lib/swift/index.md +++ b/doc/lib/swift/index.md @@ -97,6 +97,7 @@ shows which module holds each. - **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. +- **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. - **Errors.** Diagnostic cases use the `reason:` argument label; match their associated value to inspect it. Protocol errors carry `details`. diff --git a/go/ffi/MIGRATE.md b/go/ffi/MIGRATE.md index 943e86f1f17..d7abfc288f8 100644 --- a/go/ffi/MIGRATE.md +++ b/go/ffi/MIGRATE.md @@ -4,6 +4,12 @@ How to update your code for each breaking change, newest first. ## Unreleased +### Finished tracks stay until the broadcast ends (#6157) + +A finished track, raw or media, now stays listed, with its catalog rendition and demand, until its broadcast closes or the new `MoqBroadcastProducer.Finish()` lets go, instead of unlisting when its producer finishes or is released. +Publish a replacement under a new name, and expect a finished track's demand watch to end with the broadcast. +Regenerate the bindings for the new `MoqBroadcastFinish` and the changed checksums. + ### Regenerate the matching bindings Documentation on `MoqAudioProducer::write` and `finish` changes their UniFFI metadata checksums. diff --git a/go/wrapper/MIGRATE.md b/go/wrapper/MIGRATE.md index 946849b1655..b5e60cf4cc7 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 +### Finished tracks stay until the broadcast ends (#6157) + +A finished track now stays listed, with its catalog rendition and demand, until its broadcast closes or the new `BroadcastProducer.Finish()` lets go. +Publish a replacement under a new name, and expect a finished track's demand watch to end with the broadcast. + ### A claim answers by publishing (#5678) `OriginProducer.Dynamic(prefix)` takes no route, and `OriginDynamic.Update` is gone. diff --git a/go/wrapper/moq_test.go b/go/wrapper/moq_test.go index 60843a0c634..bb56e47a29d 100644 --- a/go/wrapper/moq_test.go +++ b/go/wrapper/moq_test.go @@ -153,6 +153,69 @@ func TestPublishAudioLifecycle(t *testing.T) { } } +func TestBroadcastFinishLingersUntilCancelled(t *testing.T) { + broadcast, err := moq.NewBroadcastProducer() + if err != nil { + t.Fatal(err) + } + maxAge := time.Hour + track, err := broadcast.PublishTrack("status", &moq.TrackInfo{Priority: 127, MaxAge: &maxAge}) + if err != nil { + t.Fatal(err) + } + if err := track.Finish(); err != nil { + t.Fatal(err) + } + finish, err := broadcast.Finish() + if err != nil { + t.Fatal(err) + } + if got := finish.Linger(); got != time.Hour { + t.Fatalf("Linger = %v, want 1h", got) + } + if _, err := broadcast.Consume(); err == nil { + t.Fatal("Consume after Finish succeeded") + } + + // A cancelled wait is the interrupt: it returns at once instead of lingering. + ctx, cancel := context.WithTimeout(context.Background(), 50*time.Millisecond) + defer cancel() + if err := finish.Wait(ctx); !errors.Is(err, context.DeadlineExceeded) { + t.Fatalf("Wait = %v, want the deadline", err) + } + finish.Close() +} + +func TestBroadcastFinishWaitOnDoneContextCloses(t *testing.T) { + broadcast, err := moq.NewBroadcastProducer() + if err != nil { + t.Fatal(err) + } + maxAge := time.Hour + track, err := broadcast.PublishTrack("status", &moq.TrackInfo{Priority: 127, MaxAge: &maxAge}) + if err != nil { + t.Fatal(err) + } + if err := track.Finish(); err != nil { + t.Fatal(err) + } + finish, err := broadcast.Finish() + if err != nil { + t.Fatal(err) + } + ctx, cancel := context.WithCancel(context.Background()) + cancel() + if err := finish.Wait(ctx); !errors.Is(err, context.Canceled) { + t.Fatalf("Wait = %v, want cancelled", err) + } + // Closed by the cancelled wait, so a second wait fails at once instead of lingering. + ctx, cancel = context.WithTimeout(context.Background(), 5*time.Second) + defer cancel() + if err := finish.Wait(ctx); !errors.Is(err, moq.ErrClosed) { + t.Fatalf("second Wait = %v, want closed", err) + } +} + func TestBroadcastCloseTwiceIsNoop(t *testing.T) { broadcast, err := moq.NewBroadcastProducer() if err != nil { diff --git a/go/wrapper/publish.go b/go/wrapper/publish.go index 172a43dc645..16c70cdf307 100644 --- a/go/wrapper/publish.go +++ b/go/wrapper/publish.go @@ -3,6 +3,8 @@ package moq import ( "context" "iter" + "math" + "time" ffi "moq.dev/moq-ffi/moq" "moq.dev/moq/internal/bridge" @@ -79,6 +81,52 @@ func (b *BroadcastProducer) Close() error { return b.inner.Close() } +// Finish ends the broadcast cleanly, keeping it servable until its media goes stale. +// +// Finish every track first: the returned handle holds the tracks finished by now +// and keeps the broadcast announced, so a subscriber still catching up can drain +// them. A track still live is not held. Every later call on this producer fails, +// as after [BroadcastProducer.Close]. +func (b *BroadcastProducer) Finish() (*BroadcastFinish, error) { + inner, err := b.inner.Finish() + if err != nil { + return nil, err + } + return &BroadcastFinish{inner: inner}, nil +} + +// BroadcastFinish is a cleanly ended broadcast, still announced and serving its +// finished tracks. Closing it, or cancelling a [BroadcastFinish.Wait], closes +// the broadcast at once. +type BroadcastFinish struct { + inner *ffi.MoqBroadcastFinish +} + +// Linger is how long to keep the broadcast: the longest max age of the held tracks. +func (f *BroadcastFinish) Linger() time.Duration { + us := f.inner.LingerUs() + if us > math.MaxInt64/uint64(time.Microsecond) { + return math.MaxInt64 + } + return time.Duration(us) * time.Microsecond +} + +// Wait keeps the broadcast up for its linger, or until [BroadcastFinish.Close], +// then closes it. Cancelling ctx closes the broadcast at once. +func (f *BroadcastFinish) Wait(ctx context.Context) error { + // The bridge starts no call on a done ctx, so it would never reach the close. + if err := ctx.Err(); err != nil { + f.inner.Close() + return err + } + return bridge.CallErr(ctx, f.inner.Close, f.inner.Wait) +} + +// Close closes the broadcast now, ending the linger and any wait. Closing again is a no-op. +func (f *BroadcastFinish) Close() { + f.inner.Close() +} + // BroadcastDynamic is a stream of subscriber-requested tracks. type BroadcastDynamic struct { inner *ffi.MoqBroadcastDynamic diff --git a/kt/moq-ffi/MIGRATE.md b/kt/moq-ffi/MIGRATE.md index 2eecf897139..6e9627fd6a6 100644 --- a/kt/moq-ffi/MIGRATE.md +++ b/kt/moq-ffi/MIGRATE.md @@ -4,6 +4,12 @@ How to update your code for each breaking change, newest first. ## Unreleased +### Finished tracks stay until the broadcast ends (#6157) + +A finished track, raw or media, now stays listed, with its catalog rendition and demand, until its broadcast closes or the new `MoqBroadcastProducer.finish()` lets go, instead of unlisting when its producer finishes or is released. +Publish a replacement under a new name, and expect a finished track's demand watch to end with the broadcast. +Regenerate the bindings for the new `MoqBroadcastFinish` and the changed checksums. + ### Regenerate the matching bindings Documentation on `MoqAudioProducer::write` and `finish` changes their UniFFI metadata checksums. diff --git a/kt/moq/MIGRATE.md b/kt/moq/MIGRATE.md index 7a2c218d7ad..2ff652f9212 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 +### Finished tracks stay until the broadcast ends (#6157) + +A finished track now stays listed, with its catalog rendition and demand, until its broadcast ends or the new `BroadcastProducer.finish()` lets go. +Publish a replacement under a new name, and expect a finished track's demand watch to end with the broadcast. + ### A claim answers by publishing (#5678) `OriginProducer.dynamic(prefix)` takes no route, and `OriginDynamic.update` is gone. diff --git a/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/Aliases.kt b/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/Aliases.kt index d9ba1179c4d..016772c6ba9 100644 --- a/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/Aliases.kt +++ b/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/Aliases.kt @@ -75,6 +75,8 @@ typealias BroadcastProducer = uniffi.moq.MoqBroadcastProducer typealias BroadcastConsumer = uniffi.moq.MoqBroadcastConsumer /** Receives tracks requested from a dynamically served broadcast. */ typealias BroadcastDynamic = uniffi.moq.MoqBroadcastDynamic +/** A cleanly ended broadcast, still announced and serving its finished tracks until its linger ends. */ +typealias BroadcastFinish = uniffi.moq.MoqBroadcastFinish /** The write side of a raw track: append groups of frames. */ typealias TrackProducer = uniffi.moq.MoqTrackProducer /** A subscriber-requested track not yet accepted: accept it for a [TrackProducer] or abort it. */ diff --git a/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/Durations.kt b/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/Durations.kt index d771680811a..436a92a6717 100644 --- a/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/Durations.kt +++ b/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/Durations.kt @@ -69,6 +69,10 @@ val AudioDecoderOutput.maxDelay: Duration? val AudioDecoderOutput.delay: Duration? get() = delayUs?.toLong()?.microseconds +/** How long to keep a finished broadcast: the longest max age of the tracks it holds. */ +val BroadcastFinish.linger: Duration + get() = lingerUs().coerceAtMost(Long.MAX_VALUE.toULong()).toLong().microseconds + /** Playout delay to hold ahead of the playhead: the fixed one, or the estimate from every frame read so far. */ val dev.moq.audio.Consumer.delay: Duration get() = delayUs().toLong().microseconds diff --git a/kt/moq/src/jvmAndAndroidTest/kotlin/dev/moq/SmokeTest.kt b/kt/moq/src/jvmAndAndroidTest/kotlin/dev/moq/SmokeTest.kt index 03fc616575e..919113a6a63 100644 --- a/kt/moq/src/jvmAndAndroidTest/kotlin/dev/moq/SmokeTest.kt +++ b/kt/moq/src/jvmAndAndroidTest/kotlin/dev/moq/SmokeTest.kt @@ -29,6 +29,7 @@ import kotlin.test.assertIs import kotlin.test.assertNotNull import kotlin.test.assertNull import kotlin.test.assertTrue +import kotlin.time.Duration.Companion.hours import kotlin.time.Duration.Companion.microseconds import kotlin.time.Duration.Companion.milliseconds import kotlin.time.Duration @@ -229,6 +230,23 @@ class SmokeTest { } } + @Test + fun `finishing a broadcast lingers until the wait is cancelled`() = runTest { + val broadcast = BroadcastProducer() + val track = broadcast.publishTrack("status", TrackInfo(maxAgeUs = 3_600_000_000uL)) + track.finish() + broadcast.finish().use { finish -> + assertEquals(1.hours, finish.linger) + assertFailsWith { broadcast.consume() } + // Cancelling the wait is the interrupt: it ends instead of lingering for an hour. + val wait = async { finish.wait() } + yield() + wait.cancel() + wait.join() + finish.end() + } + } + @Test fun `broadcast updates shared video properties`() { BroadcastProducer().use { broadcast -> diff --git a/py/moq-ffi/MIGRATE.md b/py/moq-ffi/MIGRATE.md index e88a41ac96f..a009932892c 100644 --- a/py/moq-ffi/MIGRATE.md +++ b/py/moq-ffi/MIGRATE.md @@ -4,6 +4,12 @@ How to update your code for each breaking change, newest first. ## Unreleased +### Finished tracks stay until the broadcast ends (#6157) + +A finished track, raw or media, now stays listed, with its catalog rendition and demand, until its broadcast closes or the new `MoqBroadcastProducer.finish()` lets go, instead of unlisting when its producer finishes or is released. +Publish a replacement under a new name, and expect a finished track's demand watch to end with the broadcast. +Regenerate the bindings for the new `MoqBroadcastFinish` and the changed checksums. + ### Regenerate the matching bindings Documentation on `MoqAudioProducer::write` and `finish` changes their UniFFI metadata checksums. diff --git a/py/moq-rs/MIGRATE.md b/py/moq-rs/MIGRATE.md index dd162bff915..4175ecd3ec6 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 +### Finished tracks stay until the broadcast ends (#6157) + +A finished track now stays listed, with its catalog rendition and demand, until its broadcast closes or the new `BroadcastProducer.finish()` lets go. +Publish a replacement under a new name, and expect a finished track's demand watch to end with the broadcast. + ### A claim answers by publishing (#5678) `OriginProducer.dynamic(prefix)` takes no route, and `OriginDynamic.update` is gone. diff --git a/py/moq-rs/moq/__init__.py b/py/moq-rs/moq/__init__.py index 6f75533a545..25530525006 100644 --- a/py/moq-rs/moq/__init__.py +++ b/py/moq-rs/moq/__init__.py @@ -32,6 +32,7 @@ ) from .publish import ( BroadcastDynamic, + BroadcastFinish, BroadcastProducer, GroupDemand, GroupProducer, @@ -95,6 +96,7 @@ "Bandwidth", "BroadcastConsumer", "BroadcastDynamic", + "BroadcastFinish", "BroadcastPrepared", "BroadcastProducer", "BroadcastRequest", diff --git a/py/moq-rs/moq/publish.py b/py/moq-rs/moq/publish.py index c041bb2aeb7..57ba12e828c 100644 --- a/py/moq-rs/moq/publish.py +++ b/py/moq-rs/moq/publish.py @@ -2,11 +2,14 @@ from __future__ import annotations +import asyncio +from collections.abc import Coroutine, Generator from datetime import timedelta -from typing import TYPE_CHECKING +from typing import TYPE_CHECKING, Any from moq_ffi import ( MoqBroadcastDynamic, + MoqBroadcastFinish, MoqBroadcastProducer, MoqGroupDemand, MoqGroupProducer, @@ -17,7 +20,7 @@ MoqTrackRequest, ) -from ._records import _subscription, _track_info +from ._records import _from_us, _subscription, _track_info from ._stream import _Stream from .types import ( Frame, @@ -344,3 +347,74 @@ def close(self) -> None: Tracks already subscribed carry on to their own end. Closing again is a no-op. """ self._inner.close() + + def finish(self) -> BroadcastFinish: + """End the broadcast cleanly, keeping it servable until its media goes stale. + + Finish every track first: the returned handle holds the tracks finished by now and + keeps the broadcast announced, so a subscriber still catching up can drain them. A + track still live is not held. Every later call on this producer fails, as after + :meth:`close`. + """ + return BroadcastFinish(self._inner.finish()) + + +class BroadcastFinish: + """A cleanly ended broadcast, still announced and serving its finished tracks. + + Await :meth:`wait` to keep it up for its :attr:`linger`. Cancelling the wait, or + :meth:`close`, closes the broadcast at once. + """ + + def __init__(self, inner: MoqBroadcastFinish) -> None: + self._inner = inner + + @property + def linger(self) -> timedelta: + """How long to keep the broadcast: the longest max age of the held tracks.""" + return _from_us(self._inner.linger_us()) + + def wait(self) -> Coroutine[Any, Any, None]: + """Keep the broadcast up for its linger, or until :meth:`close`, then close it.""" + return _FinishWait(self._inner) + + def close(self) -> None: + """Close the broadcast now, ending the linger and any wait. Closing again is a no-op.""" + self._inner.close() + + +class _FinishWait(Coroutine[Any, Any, None]): + """A finish's wait that closes the broadcast when cancelled. + + A coroutine body never runs when its task is cancelled before the first step, so the + close hooks the cancellation thrown in rather than an ``except`` inside the body. + """ + + def __init__(self, inner: MoqBroadcastFinish) -> None: + self._inner = inner + self._wait = inner.wait() + + def __await__(self) -> Generator[Any, None, None]: + return self + + def __iter__(self) -> Generator[Any, None, None]: + return self + + def __next__(self) -> Any: + return self.send(None) + + def send(self, value: Any) -> Any: + return self._wait.send(value) + + def throw(self, typ: Any, val: Any = None, tb: Any = None) -> Any: + error = typ if val is None else val + if isinstance(error, asyncio.CancelledError) or ( + isinstance(error, type) and issubclass(error, asyncio.CancelledError) + ): + self._inner.close() + if val is None and tb is None: + return self._wait.throw(typ) + return self._wait.throw(typ, val, tb) + + def close(self) -> None: + self._wait.close() diff --git a/py/moq-rs/tests/test_local.py b/py/moq-rs/tests/test_local.py index 6b754cc3700..09756545ff2 100644 --- a/py/moq-rs/tests/test_local.py +++ b/py/moq-rs/tests/test_local.py @@ -416,6 +416,56 @@ async def test_announced_epoch_restarts(): broadcast.close() +async def test_finish_lingers_until_closed(): + origin = moq.OriginProducer() + consumer = origin.consume() + announced = consumer.announced() + broadcast = create_announced(origin, "finish") + assert isinstance(await next_route(announced), moq.AnnounceEventStart) + + track = broadcast.publish_track("status", moq.TrackInfo(max_age=timedelta(hours=1))) + track.write_frame(b"tail") + track.finish() + finish = broadcast.finish() + assert finish.linger == timedelta(hours=1) + with pytest.raises(moq.Error.Closed): # type: ignore[attr-defined] + broadcast.consume() + + # Cancelling the wait is the interrupt: the broadcast closes at once. + wait = asyncio.ensure_future(finish.wait()) + await asyncio.sleep(0) + wait.cancel() + with pytest.raises(asyncio.CancelledError): + await wait + assert isinstance(await next_route(announced), moq.AnnounceEventEnd) + finish.close() + + +async def test_finish_wait_cancelled_before_it_starts_closes(): + origin = moq.OriginProducer() + consumer = origin.consume() + announced = consumer.announced() + broadcast = create_announced(origin, "finish") + assert isinstance(await next_route(announced), moq.AnnounceEventStart) + + broadcast.publish_track("status", moq.TrackInfo(max_age=timedelta(hours=1))).finish() + finish = broadcast.finish() + # Cancelled before the loop first steps it, so the wait's body never runs. + wait = asyncio.create_task(finish.wait()) + wait.cancel() + with pytest.raises(asyncio.CancelledError): + await wait + assert isinstance(await next_route(announced), moq.AnnounceEventEnd) + + +async def test_finish_without_a_max_age_closes_on_wait(): + broadcast = moq.BroadcastProducer() + broadcast.publish_track("status").finish() + finish = broadcast.finish() + assert finish.linger == timedelta(0) + await asyncio.wait_for(finish.wait(), timeout=5.0) + + def test_publish_lifecycle(): broadcast = moq.BroadcastProducer() track = broadcast.publish_track("status") diff --git a/py/moq-rs/tests/test_testing_clock.py b/py/moq-rs/tests/test_testing_clock.py index 10f6256de7d..8dd4a345221 100644 --- a/py/moq-rs/tests/test_testing_clock.py +++ b/py/moq-rs/tests/test_testing_clock.py @@ -60,6 +60,53 @@ async def main(): ) +def test_a_finished_broadcast_lingers_for_its_max_age() -> None: + _run( + """ + import asyncio + from datetime import timedelta + + import moq + from moq.testing import Clock + + clock = Clock() + + async def main(): + origin = moq.OriginProducer() + consumer = origin.consume() + announced = consumer.announced() + broadcast = origin.create_broadcast("linger") + broadcast.announce() + start = await asyncio.wait_for(anext(announced), timeout=5) + assert isinstance(start, moq.AnnounceEventStart) + track = broadcast.publish_track("track", moq.TrackInfo(max_age=timedelta(seconds=2))) + track.write_frame(b"tail") + track.finish() + + finish = broadcast.finish() + assert finish.linger == timedelta(seconds=2) + done = asyncio.ensure_future(finish.wait()) + + # A late subscriber within the max age still drains the finished track. + clock.advance(1.999) + late = await consumer.request_broadcast("linger") + reader = await late.subscribe_track("track") + frame = await asyncio.wait_for(reader.read_frame(), timeout=5) + assert frame is not None and frame.payload == b"tail" + await asyncio.sleep(0.05) + assert not done.done() + + # Once the max age passes, the broadcast closes. + clock.advance(0.001) + await asyncio.wait_for(done, timeout=5) + end = await asyncio.wait_for(anext(announced), timeout=5) + assert isinstance(end, moq.AnnounceEventEnd) + + asyncio.run(main()) + """ + ) + + def test_clock_refuses_invalid_advances() -> None: _run( """ diff --git a/rs/moq-c/MIGRATE.md b/rs/moq-c/MIGRATE.md index a6765ccfdcf..45a2f272283 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 +### Finished tracks stay until the broadcast ends (#6157) + +`moq_publish_track_finish`, `moq_publish_media_finish`, `moq_publish_container_finish`, and the encoder finishes now release the handle while the broadcast keeps the finished track listed, with its catalog rendition and demand, until `moq_publish_close` or the new `moq_publish_finish_close`. +Publish a replacement under a new name, and expect a finished track's demand terminal callback when the broadcast closes rather than at the finish. + ### A claim answers by publishing (#5678) `moq_origin_dynamic` takes no route, and `moq_origin_dynamic_update` is gone. diff --git a/rs/moq-c/src/api.rs b/rs/moq-c/src/api.rs index 01e777efc35..23c285c6003 100644 --- a/rs/moq-c/src/api.rs +++ b/rs/moq-c/src/api.rs @@ -2201,6 +2201,40 @@ pub extern "C" fn moq_publish_close(broadcast: u32) -> i32 { }) } +/// End a broadcast cleanly and release its handle, keeping it servable until its media is stale. +/// +/// Finish every track first: the returned finish handle holds the tracks finished by now and +/// keeps the broadcast announced, so a subscriber still catching up can drain them. A track still +/// live is not held. `linger_us` receives how long to keep the handle, in microseconds: the +/// longest max age among the held tracks, or zero. Keep it that long on your own clock, then +/// [moq_publish_finish_close]; closing it sooner is how an interrupt ends the linger. +/// +/// Returns a non-zero finish handle on success, or a negative code on failure. +/// +/// # Safety +/// - `linger_us` must be a valid pointer. +#[unsafe(no_mangle)] +pub unsafe extern "C" fn moq_publish_finish(broadcast: u32, linger_us: *mut u64) -> i32 { + ffi::enter(move || { + let broadcast = ffi::parse_id(broadcast)?; + let linger_us = unsafe { linger_us.as_mut() }.ok_or(Error::InvalidPointer)?; + let (finish, linger) = State::lock().publish.finish(broadcast)?; + *linger_us = u64::try_from(linger.as_micros()).unwrap_or(u64::MAX); + Ok(finish) + }) +} + +/// Close a finished broadcast and release its handle, ending its linger. +/// +/// Returns a zero on success, or a negative code on failure. +#[unsafe(no_mangle)] +pub extern "C" fn moq_publish_finish_close(finish: u32) -> i32 { + ffi::enter(move || { + let finish = ffi::parse_id(finish)?; + State::lock().publish.finish_close(finish) + }) +} + /// Publish one audio codec as a new media track. /// /// The track is named after the format (`0.opus`), so a subscriber finds it @@ -2327,6 +2361,9 @@ pub extern "C" fn moq_publish_media_seek(media: u32, sequence: u64) -> i32 { /// Finish a media track, flushing any buffered frames. No more frames can be written. /// +/// The broadcast keeps the finished track, catalog rendition included, until it closes or its +/// [moq_publish_finish] linger ends, so a late subscriber can still drain it. +/// /// Returns a zero on success, or a negative code on failure. #[unsafe(no_mangle)] pub extern "C" fn moq_publish_media_finish(export: u32) -> i32 { @@ -2451,6 +2488,9 @@ pub extern "C" fn moq_publish_container_seek(container: u32, sequence: u64) -> i /// Finish every track the container publishes and release the handle. /// +/// The broadcast keeps the finished tracks, catalog renditions included, until it closes or its +/// [moq_publish_finish] linger ends, so a late subscriber can still drain them. +/// /// Returns zero on success, or a negative code on failure. #[unsafe(no_mangle)] pub extern "C" fn moq_publish_container_finish(container: u32) -> i32 { @@ -2849,7 +2889,10 @@ pub unsafe extern "C" fn moq_publish_track_datagram( }) } -/// Finish a raw track. No more groups or frames can be written. +/// Finish a raw track and release its handle. No more groups or frames can be written. +/// +/// The broadcast keeps the finished track until it closes or its [moq_publish_finish] linger +/// ends, so a late subscriber can still drain it. /// /// Returns a zero on success, or a negative code on failure. #[unsafe(no_mangle)] diff --git a/rs/moq-c/src/audio.rs b/rs/moq-c/src/audio.rs index 6bd963c3185..0fc94c55d41 100644 --- a/rs/moq-c/src/audio.rs +++ b/rs/moq-c/src/audio.rs @@ -150,6 +150,7 @@ pub struct moq_audio_frame { pub(crate) struct AudioEncoder { producer: moq_audio::encode::Producer, reservation: Option>, + finished: crate::publish::Finished, } type AudioProducer = Shared; @@ -166,16 +167,18 @@ impl Audio { /// Encode PCM frames into an audio track and return its handle. pub fn publish( &mut self, - broadcast: &mut moq_net::broadcast::Producer, - catalog: moq_mux::catalog::Producer, + target: crate::publish::Target<'_>, input: moq_audio::encode::Input, options: moq_audio::encode::Options, reserve: bool, ) -> Result { - let producer = moq_audio::encode::Producer::new(broadcast, catalog, input, &options)?; + let producer = moq_audio::encode::Producer::new(target.producer, target.catalog.clone(), input, &options)?; let reservation = reserve.then(|| Arc::new(options.bandwidth.reserve(&producer.demand(), producer.bitrate()))); - self.producers - .insert(Shared::new(AudioEncoder { producer, reservation })) + self.producers.insert(Shared::new(AudioEncoder { + producer, + reservation, + finished: target.finished.clone(), + })) } pub(crate) fn reservation(&self, id: Id) -> Result>, Error> { @@ -364,15 +367,7 @@ pub unsafe extern "C" fn moq_encode_audio( options.bandwidth = state.bandwidth.allocator(id)?; } let State { publish, audio, .. } = &mut *state; - let (broadcast_producer, catalog) = publish.pair_mut(broadcast)?; - - audio.publish( - broadcast_producer, - catalog.clone(), - encoder_input, - options, - bandwidth.is_some(), - ) + audio.publish(publish.target(broadcast)?, encoder_input, options, bandwidth.is_some()) }) } @@ -453,6 +448,9 @@ pub unsafe extern "C" fn moq_encode_audio_frame(producer: u32, frame: *const moq } /// Flush any pending samples and finalize an audio producer. +/// +/// The broadcast keeps the finished track, catalog rendition included, until it closes or its +/// `moq_publish_finish` linger ends, so a late subscriber can still drain it. #[unsafe(no_mangle)] pub extern "C" fn moq_encode_audio_finish(producer: u32) -> i32 { ffi::enter(move || { @@ -460,8 +458,12 @@ pub extern "C" fn moq_encode_audio_finish(producer: u32) -> i32 { // The id is dropped first, so nothing new queues behind the flush; whatever // is mid-encode still finishes before this takes the producer. let producer = State::lock().audio.remove(producer)?; - let mut producer = producer.take().ok_or(Error::MediaNotFound)?.producer; + let AudioEncoder { + mut producer, finished, .. + } = producer.take().ok_or(Error::MediaNotFound)?; producer.finish()?; + // The broadcast keeps the finished track, so its finish still holds it. + finished.keep(producer); Ok(()) }) } diff --git a/rs/moq-c/src/publish.rs b/rs/moq-c/src/publish.rs index 6ed31705677..55aeee33ee8 100644 --- a/rs/moq-c/src/publish.rs +++ b/rs/moq-c/src/publish.rs @@ -18,6 +18,8 @@ struct DemandEntry { /// broadcast it was made on so media can be published onto it under that broadcast's catalog. struct TrackRequest { broadcast: Id, + // Carried, not looked up, so a raw accept still works after the broadcast handle is released. + finished: Finished, request: moq_net::track::Request, } @@ -31,7 +33,7 @@ enum Request { /// What a request handler serves. enum Dynamic { /// Track requests on a broadcast, remembered so media can be published onto them. - Broadcast(moq_net::broadcast::Dynamic, Id), + Broadcast(moq_net::broadcast::Dynamic, Id, Finished), /// Group requests (fetches of uncached groups) on a track. Track(moq_net::track::Dynamic), } @@ -47,6 +49,84 @@ struct Broadcast { catalog: moq_mux::catalog::Producer, video: BTreeMap, audio: BTreeMap, + finished: Finished, +} + +impl Drop for Broadcast { + fn drop(&mut self) { + self.finished.release(); + } +} + +/// The finished producers a broadcast keeps, or `None` once it ended. +type Keeping = Option>>; + +/// Finished producers a broadcast keeps until it ends. +/// +/// A track unlists once its last producer drops, and a finish holds only listed tracks. A +/// `*_finish` call frees its handle, so the broadcast keeps the finished producer here instead, +/// and [`Publish::finish`] still holds the track. +#[derive(Clone)] +pub struct Finished(std::sync::Arc>); + +impl Default for Finished { + fn default() -> Self { + Self(std::sync::Arc::new(std::sync::Mutex::new(Some(Vec::new())))) + } +} + +impl Finished { + /// Keep a finished producer until the broadcast ends, or drop it now if it already has. + pub(crate) fn keep(&self, producer: impl Send + 'static) { + let producer: Box = Box::new(producer); + let mut kept = self.0.lock().unwrap_or_else(std::sync::PoisonError::into_inner); + if let Some(kept) = kept.as_mut() { + kept.push(producer); + } + } + + /// Stop keeping, handing back what was kept so the caller decides when it drops. + fn release(&self) -> Vec> { + self.0 + .lock() + .unwrap_or_else(std::sync::PoisonError::into_inner) + .take() + .unwrap_or_default() + } +} + +/// What a producer publishing on a broadcast needs from it. +pub struct Target<'a> { + pub producer: &'a mut moq_net::broadcast::Producer, + pub catalog: &'a mut moq_mux::catalog::Producer, + /// Where the broadcast keeps the producer once it finishes. + pub finished: &'a Finished, +} + +/// A producer handle, with where its broadcast keeps it once finished. +struct Kept { + inner: T, + finished: Finished, +} + +impl Kept { + fn keep(self) { + self.finished.keep(self.inner); + } +} + +impl std::ops::Deref for Kept { + type Target = T; + + fn deref(&self) -> &T { + &self.inner + } +} + +impl std::ops::DerefMut for Kept { + fn deref_mut(&mut self) -> &mut T { + &mut self.inner + } } // Legacy C data methods stamp writes on one fixed broadcast clock without retaining @@ -59,6 +139,7 @@ struct Data { struct Container { inner: import::Container, driver: crate::ffi::Background, + finished: Finished, } #[derive(Default)] @@ -68,7 +149,7 @@ pub struct Publish { /// Single-codec media importers, fed timestamped frames. // Boxed because the codec splitters/imports are much larger than the container ones. - media: NonZeroSlab>, + media: NonZeroSlab>>, /// Container importers, fed whole chunks. A separate space from `media` because a /// container publishes several tracks and carries its own timing, so it takes no @@ -76,7 +157,7 @@ pub struct Publish { containers: NonZeroSlab, /// Raw track producers (no media/container/catalog framing). - tracks: NonZeroSlab, + tracks: NonZeroSlab>, /// Raw group producers, created from a raw track producer. groups: NonZeroSlab, @@ -106,6 +187,9 @@ pub struct Publish { /// Group requests delivered to a handler, freed on accept, abort, or free. group_request: NonZeroSlab, + + /// Finished broadcasts, serving their finished tracks until closed. + finishes: NonZeroSlab, } impl Publish { @@ -137,6 +221,7 @@ impl Publish { catalog, video: BTreeMap::new(), audio: BTreeMap::new(), + finished: Finished::default(), })?; Ok(id) } @@ -176,58 +261,78 @@ impl Publish { Ok(self.catalog(id)?.snapshot()) } - /// Mutable access to both the broadcast and its catalog producer. + /// What a producer publishing on the broadcast needs from it. /// Used by sibling modules (e.g. `audio`) that need to attach a new /// track to an existing publish. - pub fn pair_mut( - &mut self, - id: Id, - ) -> Result< - ( - &mut moq_net::broadcast::Producer, - &mut moq_mux::catalog::Producer, - ), - Error, - > { + pub fn target(&mut self, id: Id) -> Result, Error> { let broadcast = self.broadcast_mut(id)?; - Ok((&mut broadcast.producer, &mut broadcast.catalog)) + Ok(Target { + producer: &mut broadcast.producer, + catalog: &mut broadcast.catalog, + finished: &broadcast.finished, + }) } /// End the broadcast for good and release it, finalizing the catalog stream. pub fn close(&mut self, broadcast: Id) -> Result<(), Error> { - let Broadcast { - driver, - producer, - mut catalog, - video, - audio, - .. - } = self.broadcasts.remove(broadcast).ok_or(Error::BroadcastNotFound)?; + let mut broadcast = self.broadcasts.remove(broadcast).ok_or(Error::BroadcastNotFound)?; let result = (|| { // Retire caller-authored entries while the catalog track is still open. { - let mut guard = catalog.modify()?; - for name in video.keys() { + let mut guard = broadcast.catalog.modify()?; + for name in broadcast.video.keys() { guard.video.renditions.remove(name); } - for name in audio.keys() { + for name in broadcast.audio.keys() { guard.audio.renditions.remove(name); } guard.commit()?; } // Close the broadcast first so it ends even if finalizing the catalog fails. - producer.close(); - catalog.finish()?; + broadcast.producer.close(); + broadcast.catalog.finish()?; Ok(()) })(); - driver.check()?; + broadcast.driver.check()?; result } + /// End the broadcast cleanly and release it, returning a finish handle and its linger. + /// + /// The catalog finishes with its entries still listed, so a late subscriber finds the + /// finished tracks the handle holds. + pub fn finish(&mut self, broadcast: Id) -> Result<(Id, std::time::Duration), Error> { + let mut broadcast = self.broadcasts.remove(broadcast).ok_or(Error::BroadcastNotFound)?; + // On failure the handle is gone, so close the broadcast rather than leave a dynamic holding it. + let ready = broadcast.catalog.finish().map_err(Error::from); + if let Err(err) = ready.and_then(|()| broadcast.driver.check()) { + broadcast.producer.close(); + return Err(err); + } + // Released only once the finish holds their tracks. + let finished = broadcast.finished.release(); + let finish = broadcast.producer.clone().finish(); + drop(finished); + let linger = finish.linger(); + Ok((self.finishes.insert(finish)?, linger)) + } + + /// Close a finished broadcast, ending its linger. + pub fn finish_close(&mut self, finish: Id) -> Result<(), Error> { + self.finishes.remove(finish).ok_or(Error::BroadcastNotFound)?; + Ok(()) + } + + /// Where a broadcast keeps the producers finished on it. + fn finished(&self, broadcast: Id) -> Result { + Ok(self.broadcast(broadcast)?.finished.clone()) + } + pub fn audio(&mut self, broadcast: Id, init: import::AudioInit) -> Result { let Broadcast { producer: broadcast, catalog, + finished, .. } = self.broadcast(broadcast)?; let broadcast = broadcast.clone(); @@ -235,7 +340,11 @@ impl Publish { let request = broadcast.reserve_track(name)?; let track = import::Track::audio(request, catalog.reserve(), init)?; - let id = self.media.insert(Box::new(track))?; + let finished = finished.clone(); + let id = self.media.insert(Kept { + inner: Box::new(track), + finished, + })?; Ok(id) } @@ -243,6 +352,7 @@ impl Publish { let Broadcast { producer: broadcast, catalog, + finished, .. } = self.broadcast(broadcast)?; let broadcast = broadcast.clone(); @@ -250,7 +360,11 @@ impl Publish { let request = broadcast.reserve_track(name)?; let track = import::Track::video(request, catalog.reserve(), init)?; - let id = self.media.insert(Box::new(track))?; + let finished = finished.clone(); + let id = self.media.insert(Kept { + inner: Box::new(track), + finished, + })?; Ok(id) } @@ -259,12 +373,14 @@ impl Publish { producer: broadcast, catalog, driver, + finished, .. } = self.broadcast(broadcast)?; let container = import::Container::new(broadcast.clone(), catalog.reserve(), &init)?; let container = Container { inner: container, driver: driver.clone(), + finished: finished.clone(), }; let id = self.containers.insert(container)?; Ok(id) @@ -317,6 +433,7 @@ impl Publish { pub fn media_finish(&mut self, media: Id) -> Result<(), Error> { let mut track = self.media.remove(media).ok_or(Error::MediaNotFound)?; track.finish()?; + track.keep(); Ok(()) } @@ -352,7 +469,9 @@ impl Publish { let mut container = self.containers.remove(container).ok_or(Error::MediaNotFound)?; let result = container.inner.finish(); container.driver.check()?; - Ok(result?) + result?; + container.finished.keep(container.inner); + Ok(()) } /// Insert or replace a caller-authored video rendition in the broadcast's catalog. @@ -452,7 +571,7 @@ impl Publish { /// can't express (an untimed frame). #[cfg(test)] pub(crate) fn track_producer(&mut self, track: Id) -> Option<&mut moq_net::track::Producer> { - self.tracks.get_mut(track) + self.tracks.get_mut(track).map(|track| &mut track.inner) } /// A watch-only handle to a raw track's subscriber demand. @@ -546,8 +665,9 @@ impl Publish { /// Without a live handler an unknown track name is refused, as before. pub fn dynamic(&mut self, broadcast: Id, on_request: OnStatus) -> Result { let dynamic = self.producer(broadcast)?.dynamic(); - let driver = self.broadcast(broadcast)?.driver.clone(); - self.spawn_dynamic(Dynamic::Broadcast(dynamic, broadcast), on_request, driver) + let Broadcast { driver, finished, .. } = self.broadcast(broadcast)?; + let dynamic = Dynamic::Broadcast(dynamic, broadcast, finished.clone()); + self.spawn_dynamic(dynamic, on_request, driver.clone()) } /// Serve fetches of uncached groups on a raw track, delivering each as a group-request @@ -596,9 +716,15 @@ impl Publish { biased; _ = &mut close => return Ok(()), res = kio::wait(|waiter| match &mut dynamic { - Dynamic::Broadcast(dynamic, broadcast) => dynamic - .poll_requested_track(waiter) - .map_ok(|request| Request::Track(Box::new(TrackRequest { broadcast: *broadcast, request }))), + Dynamic::Broadcast(dynamic, broadcast, finished) => { + dynamic.poll_requested_track(waiter).map_ok(|request| { + Request::Track(Box::new(TrackRequest { + broadcast: *broadcast, + finished: finished.clone(), + request, + })) + }) + } Dynamic::Track(dynamic) => dynamic.poll_requested_group(waiter).map_ok(Request::Group), }) => res, }; @@ -639,24 +765,41 @@ impl Publish { /// Accept a track request as a raw track, returning a track handle like [`Self::track`]. pub fn track_request_accept(&mut self, request: Id, info: moq_net::track::Info) -> Result { - let request = self.track_request.remove(request).ok_or(Error::NotFound)?; - self.tracks.insert(request.request.accept(info)) + let TrackRequest { finished, request, .. } = self.track_request.remove(request).ok_or(Error::NotFound)?; + self.tracks.insert(Kept { + inner: request.accept(info), + finished, + }) } /// Accept a track request as an audio track, returning a media handle like [`Self::audio`]. pub fn track_request_audio(&mut self, request: Id, init: import::AudioInit) -> Result { - let TrackRequest { broadcast, request } = self.track_request.remove(request).ok_or(Error::NotFound)?; + let TrackRequest { + broadcast, + finished, + request, + } = self.track_request.remove(request).ok_or(Error::NotFound)?; let catalog = self.catalog(broadcast)?; let track = import::Track::audio(request, catalog.reserve(), init)?; - self.media.insert(Box::new(track)) + self.media.insert(Kept { + inner: Box::new(track), + finished, + }) } /// Accept a track request as a video track, returning a media handle like [`Self::video`]. pub fn track_request_video(&mut self, request: Id, init: import::VideoInit) -> Result { - let TrackRequest { broadcast, request } = self.track_request.remove(request).ok_or(Error::NotFound)?; + let TrackRequest { + broadcast, + finished, + request, + } = self.track_request.remove(request).ok_or(Error::NotFound)?; let catalog = self.catalog(broadcast)?; let track = import::Track::video(request, catalog.reserve(), init)?; - self.media.insert(Box::new(track)) + self.media.insert(Kept { + inner: Box::new(track), + finished, + }) } /// Reject a track request, failing every subscriber waiting on it with `error_code`. @@ -712,9 +855,10 @@ impl Publish { /// for non-media tracks. Pair it with [`Self::video_config`] / [`Self::audio_config`] /// if you want to describe the track in the catalog as well. pub fn track(&mut self, broadcast: Id, name: &str, info: Option) -> Result { + let finished = self.finished(broadcast)?; let broadcast = self.producer(broadcast)?; let track = broadcast.create_track(name, info)?; - self.tracks.insert(track) + self.tracks.insert(Kept { inner: track, finished }) } /// Append a new group to a raw track, returning a group producer. @@ -752,12 +896,13 @@ impl Publish { /// Finish a raw track. No more groups or frames can be written. /// /// [`Self::track_finish_at`] declares the boundary ahead of time, so this keeps that - /// boundary and only releases the handle. + /// boundary and only releases the handle; the broadcast keeps the track. pub fn track_finish(&mut self, track: Id) -> Result<(), Error> { let track = self.tracks.remove(track).ok_or(Error::TrackNotFound)?; if track.end().is_none() { track.finish()?; } + track.keep(); Ok(()) } @@ -771,7 +916,7 @@ impl Publish { /// Abort a raw track with an application error code. pub fn track_abort(&mut self, track: Id, error_code: u16) -> Result<(), Error> { let track = self.tracks.remove(track).ok_or(Error::TrackNotFound)?; - track.abort(moq_net::Error::App(error_code))?; + track.inner.abort(moq_net::Error::App(error_code))?; Ok(()) } @@ -941,4 +1086,23 @@ mod supervision_tests { assert!(matches!(publish.container_cut(container), Err(Error::Panic))); assert!(matches!(publish.container_finish(container), Err(Error::Panic))); } + + #[tokio::test] + async fn a_finish_after_a_driver_panic_closes_the_broadcast() { + let (origin, completion, trigger) = crate::ffi::panicking_origin(); + let mut publish = Publish::default(); + let broadcast = publish + .create((origin.create_broadcast("retained").unwrap(), completion.clone())) + .unwrap(); + let producer = &publish.broadcast(broadcast).unwrap().producer; + // A dynamic handle outlives the consumed broadcast, so only an explicit close ends it. + let _dynamic = producer.dynamic(); + let consumer = producer.consume(); + *trigger + .write() + .unwrap_or_else(|_| unreachable!("test keeps its panic trigger open")) = true; + assert!(matches!(completion.finished().await, Err(Error::Panic))); + assert!(matches!(publish.finish(broadcast), Err(Error::Panic))); + assert!(consumer.is_closed()); + } } diff --git a/rs/moq-c/src/test.rs b/rs/moq-c/src/test.rs index 77ba92d10c6..705a725f1c0 100644 --- a/rs/moq-c/src/test.rs +++ b/rs/moq-c/src/test.rs @@ -659,12 +659,12 @@ fn publish_media_owns_its_rendition_before_the_first_keyframe() { "and the no-op left the media track's rendition alone" ); - // Once the media handle is gone the name is free again. + // The broadcast keeps a finished media track, rendition and all, until it ends. assert_eq!(moq_publish_media_finish(media), 0); assert_eq!( unsafe { moq_publish_video_config(broadcast, &video) }, - 0, - "finishing the media track releases its rendition name" + -18, + "the finished media track keeps its rendition name" ); assert_eq!(moq_publish_close(broadcast), 0); @@ -783,7 +783,7 @@ fn publish_catalog_roundtrip() { assert_eq!(unsafe { moq_publish_video_config(broadcast, &disabled_video) }, 0); { let mut state = State::lock(); - let (_, catalog) = state.publish.pair_mut(Id::try_from(broadcast).unwrap()).unwrap(); + let catalog = state.publish.target(Id::try_from(broadcast).unwrap()).unwrap().catalog; catalog .modify() .unwrap() @@ -2237,6 +2237,98 @@ fn close_invalid_or_zero_ids() { assert!(moq_publish_close(0) < 0); } +/// A finished broadcast serves its finished tracks to a late subscriber, even after their +/// handles were freed, and reports the longest max age among them as its linger. +#[test] +fn publish_finish_serves_finished_tracks_until_closed() { + let origin = id(moq_origin_create()); + let path = b"finish/serve"; + let broadcast = publish_broadcast(origin, path); + + let name = b"data"; + let info = moq_track_info { + priority: 0, + max_age_us: 5_000_000, + max_age_present: true, + timescale: 0, + timescale_present: false, + refresh: 0, + refresh_present: false, + compress: false, + }; + let track = id(unsafe { moq_publish_track(broadcast, name.as_ptr() as *const c_char, name.len(), &info) }); + let payload = b"tail"; + assert_eq!( + unsafe { moq_publish_track_frame(track, payload.as_ptr(), payload.len(), 1_000) }, + 0 + ); + assert_eq!(moq_publish_track_finish(track), 0); + + let media = id(publish_audio( + broadcast, + moq_audio_format::MOQ_AUDIO_FORMAT_OPUS, + &opus_head(), + None, + )); + let frame = b"opus frame"; + assert_eq!( + unsafe { moq_publish_media_frame(media, frame.as_ptr(), frame.len(), 1_000) }, + 0 + ); + assert_eq!(moq_publish_media_finish(media), 0); + + // A NULL out-pointer is refused before the broadcast is consumed. + assert!(unsafe { moq_publish_finish(broadcast, std::ptr::null_mut()) } < 0); + let mut linger_us = 0; + let finish = id(unsafe { moq_publish_finish(broadcast, &mut linger_us) }); + // The media track's default max age outlasts the raw track's. + assert!(linger_us >= 5_000_000, "linger {linger_us}us"); + assert!( + moq_publish_close(broadcast) < 0, + "a finished broadcast handle is released" + ); + + let consume = request_broadcast(origin, path); + let frame_cb = Callback::new(); + let subscription = moq_subscription { + priority: 0, + max_delay_us: 0, + ranges: std::ptr::null(), + ranges_len: 0, + order: 0, + }; + id(unsafe { + moq_consume_track( + consume, + name.as_ptr() as *const c_char, + name.len(), + &subscription, + Some(channel_callback), + frame_cb.ptr, + ) + }); + let frame_id = id(frame_cb.recv()); + let mut frame = moq_frame { + payload: std::ptr::null(), + payload_size: 0, + timestamp_us: 0, + timestamp_present: false, + keyframe: false, + }; + assert_eq!(unsafe { moq_consume_track_frame(frame_id, &mut frame) }, 0); + let received = unsafe { std::slice::from_raw_parts(frame.payload, frame.payload_size) }; + assert_eq!(received, payload); + assert_eq!(moq_consume_track_frame_free(frame_id), 0); + // The track finished, so the subscription ends cleanly on its own, racing any cancel. + assert_eq!(frame_cb.recv_terminal(), 0); + assert_eq!(moq_consume_close(consume), 0); + + assert_eq!(moq_publish_finish_close(finish), 0); + assert!(moq_publish_finish_close(finish) < 0, "a closed finish is released"); + assert!(request_once(origin, path) < 0, "a closed finish is unroutable"); + assert_eq!(moq_origin_close(origin), 0); +} + #[test] fn publish_close_releases_the_handle() { let origin = id(moq_origin_create()); @@ -2736,8 +2828,9 @@ fn track_demand_follows_subscribers() { assert_eq!(late_cb.recv_terminal(), 0); assert!(moq_publish_demand_cancel(late) < 0, "double-close should fail"); - // Finishing the track ends the remaining watcher cleanly. + // The broadcast keeps a finished track until it ends, which ends the remaining watcher cleanly. assert_eq!(moq_publish_track_finish(track), 0); + assert_eq!(moq_publish_close(broadcast), 0); assert_eq!(demand_cb.recv_terminal(), 0); assert!( moq_publish_demand_cancel(watcher) < 0, @@ -2745,7 +2838,6 @@ fn track_demand_follows_subscribers() { ); assert_eq!(moq_consume_close(consume), 0); - assert_eq!(moq_publish_close(broadcast), 0); assert_eq!(moq_origin_close(origin), 0); } @@ -2823,6 +2915,7 @@ fn track_demand_reports_the_wanted_group() { assert_eq!(demand_wanted(watcher), None); assert_eq!(moq_publish_track_finish(track), 0); + assert_eq!(moq_publish_close(broadcast), 0); assert_eq!(demand_cb.recv_terminal(), 0); let (mut group, mut present) = (0, false); assert!( @@ -2831,7 +2924,6 @@ fn track_demand_reports_the_wanted_group() { ); assert_eq!(moq_consume_close(consume), 0); - assert_eq!(moq_publish_close(broadcast), 0); assert_eq!(moq_origin_close(origin), 0); } @@ -2921,10 +3013,9 @@ fn media_demand_refuses_a_container() { let _watcher = id(unsafe { moq_publish_media_demand(media, Some(channel_callback), cb.ptr) }); assert_eq!(cb.recv(), moq_demand::MOQ_DEMAND_UNUSED as i32); assert_eq!(moq_publish_media_finish(media), 0); - assert_eq!(cb.recv_terminal(), 0); - assert_eq!(moq_publish_container_finish(container), 0); assert_eq!(moq_publish_close(broadcast), 0); + assert_eq!(cb.recv_terminal(), 0); assert_eq!(moq_origin_close(origin), 0); } @@ -3026,9 +3117,9 @@ fn dynamic_serves_track_requests() { assert_eq!(frame_cb.recv_terminal(), 0); assert_eq!(demand_cb.recv(), moq_demand::MOQ_DEMAND_UNUSED as i32); assert_eq!(moq_publish_track_finish(track), 0); - assert_eq!(demand_cb.recv_terminal(), 0); assert_eq!(moq_consume_close(consume), 0); assert_eq!(moq_publish_close(broadcast), 0); + assert_eq!(demand_cb.recv_terminal(), 0); assert_eq!(moq_origin_close(origin), 0); } @@ -3071,8 +3162,31 @@ fn dynamic_track_request_publishes_media() { assert_eq!(frame_cb.recv_terminal(), 0); assert_eq!(demand_cb.recv(), moq_demand::MOQ_DEMAND_UNUSED as i32); assert_eq!(moq_publish_media_finish(media), 0); + assert_eq!(moq_publish_close(broadcast), 0); assert_eq!(demand_cb.recv_terminal(), 0); + assert_eq!(request_cb.recv_terminal(), 0); + assert_eq!(moq_consume_close(consume), 0); + assert_eq!(moq_origin_close(origin), 0); +} + +/// A raw track request already delivered stays acceptable after its broadcast handle is closed. +#[test] +fn track_request_accepts_after_the_broadcast_closes() { + let origin = id(moq_origin_create()); + let broadcast = publish_broadcast(origin, b"dynamic-closed"); + let request_cb = Callback::new(); + let _dynamic = id(unsafe { moq_publish_dynamic(broadcast, Some(channel_callback), request_cb.ptr) }); + + let consume = consume_local(broadcast); + let frame_cb = Callback::new(); + consume_track(consume, b"raw", &frame_cb); + + let request = id(request_cb.recv()); assert_eq!(moq_publish_close(broadcast), 0); + let track = id(unsafe { moq_track_request_accept(request, std::ptr::null()) }); + assert_eq!(moq_publish_track_finish(track), 0); + // The subscription ends with the finished track, before its callback's channel is freed. + assert_eq!(frame_cb.recv_terminal(), 0); assert_eq!(request_cb.recv_terminal(), 0); assert_eq!(moq_consume_close(consume), 0); assert_eq!(moq_origin_close(origin), 0); @@ -3407,7 +3521,7 @@ fn consume_audio_follows_a_sibling_broadcast_reference() { // The importer picks the track name, and the catalog rendition must key on the same one. let name = { let mut state = State::lock(); - let (_, catalog) = state.publish.pair_mut(Id::try_from(source).unwrap()).unwrap(); + let catalog = state.publish.target(Id::try_from(source).unwrap()).unwrap().catalog; let catalog = catalog.modify().unwrap(); catalog .audio @@ -3438,7 +3552,7 @@ fn consume_audio_follows_a_sibling_broadcast_reference() { // The C config struct has no broadcast field, so point the rendition at the sibling here. { let mut state = State::lock(); - let (_, catalog) = state.publish.pair_mut(Id::try_from(broadcast).unwrap()).unwrap(); + let catalog = state.publish.target(Id::try_from(broadcast).unwrap()).unwrap().catalog; catalog .modify() .unwrap() diff --git a/rs/moq-c/src/video.rs b/rs/moq-c/src/video.rs index b433bfac278..a9fcd90232b 100644 --- a/rs/moq-c/src/video.rs +++ b/rs/moq-c/src/video.rs @@ -282,6 +282,7 @@ pub(crate) struct VideoEncoder { follow: Option>, followed: Option, ceiling: Option>, + finished: crate::publish::Finished, } /// A delivered frame: the decoded picture, retained until its id is freed, and @@ -355,9 +356,15 @@ pub struct DecoderOutput { fn finalize( mut producer: moq_video::encode::Producer, drained: Result<(), moq_video::Error>, + finished: &crate::publish::Finished, ) -> Result<(), Error> { match drained { - Ok(()) => Ok(producer.finish()?), + Ok(()) => { + producer.finish()?; + // The broadcast keeps the finished track, so its finish still holds it. + finished.keep(producer); + Ok(()) + } Err(err) => { producer.abort(moq_net::Error::Transport(err.to_string())); Err(err.into()) @@ -418,12 +425,13 @@ impl VideoEncoder { encoder, mut producer, followed, + finished, .. } = self; // Drain the codec into the track before ending it, so the last frames land // in it rather than being dropped with the encoder. let drained = block_on(encoder.finish()).and_then(|encoded| producer.publish(&encoded)); - finalize(producer, drained)?; + finalize(producer, drained, &finished)?; // A follower panic only stops rate adaptation, so the track still ends // cleanly before the panic is reported. followed.map_or(Ok(()), |followed| followed.check()) @@ -438,17 +446,18 @@ impl Video { /// a track advertised that will never carry frames. pub fn publish( &mut self, - broadcast: &moq_net::broadcast::Producer, - catalog: moq_mux::catalog::Producer, + target: crate::publish::Target<'_>, format: moq_video_pixel_format, config: &moq_video::encode::Config, rendition: hang::catalog::VideoConfig, encoder: moq_video::encode::Sink, ) -> Result { - let reserved = catalog + let reserved = target + .catalog .reserve() .with_timeline_hint(config.gop.duration(config.framerate)); - let producer = moq_video::encode::Producer::new(broadcast.clone(), reserved, rendition)?; + let producer = moq_video::encode::Producer::new(target.producer.clone(), reserved, rendition)?; + let finished = target.finished.clone(); self.producers.insert(Shared::new(VideoEncoder { encoder, producer, @@ -458,6 +467,7 @@ impl Video { follow: None, followed: None, ceiling: None, + finished, })) } @@ -723,16 +733,7 @@ pub unsafe extern "C" fn moq_encode_video( let mut state = State::lock(); let allocator = bandwidth.map(|id| state.bandwidth.allocator(id)).transpose()?; let State { publish, video, .. } = &mut *state; - let (broadcast_producer, catalog) = publish.pair_mut(broadcast)?; - - let id = video.publish( - broadcast_producer, - catalog.clone(), - format, - &config, - rendition.clone(), - encoder, - )?; + let id = video.publish(publish.target(broadcast)?, format, &config, rendition.clone(), encoder)?; if let Some(allocator) = allocator.as_ref() { video.follow(id, allocator, video_ceiling(&config, &rendition))?; } @@ -862,6 +863,8 @@ pub extern "C" fn moq_encode_video_bitrate(producer: u32, bitrate: u64) -> i32 { /// Flush any frames the codec is still holding and finalize the video track. /// /// The handle is released, so nothing can be published to it afterwards. +/// The broadcast keeps the finished track, catalog rendition included, until it closes or its +/// `moq_publish_finish` linger ends, so a late subscriber can still drain it. #[unsafe(no_mangle)] pub extern "C" fn moq_encode_video_finish(producer: u32) -> i32 { ffi::enter(move || { @@ -1030,7 +1033,7 @@ mod tests { #[tokio::test] async fn a_successful_drain_ends_the_track_cleanly() { let (producer, mut track) = track_under_test().await; - finalize(producer, Ok(())).unwrap(); + finalize(producer, Ok(()), &Default::default()).unwrap(); assert!(matches!(track.recv_group().await, Ok(None)), "expected a clean end"); } @@ -1041,7 +1044,7 @@ mod tests { async fn a_failed_drain_aborts_the_track() { let (producer, mut track) = track_under_test().await; let err = moq_video::Error::Codec(anyhow::anyhow!("the codec lost the tail")); - finalize(producer, Err(err)).unwrap_err(); + finalize(producer, Err(err), &Default::default()).unwrap_err(); let Err(err) = track.recv_group().await else { panic!("expected an abort, not a clean end"); @@ -1071,6 +1074,7 @@ mod tests { follow: None, followed: Some(followed), ceiling: None, + finished: Default::default(), }; let result = tokio::task::spawn_blocking(move || video.publish_finish()) diff --git a/rs/moq-ffi/MIGRATE.md b/rs/moq-ffi/MIGRATE.md index 162c8013022..59e13b01410 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 +### Finished tracks stay until the broadcast ends (#6157) + +A finished track, raw or media, now stays listed, with its catalog rendition and demand, until its broadcast closes or the new `MoqBroadcastProducer::finish` lets go, instead of unlisting when its producer finishes or is released. +Publish a replacement under a new name, and expect a finished track's demand watch to end with the broadcast. + ### A claim answers by publishing (#5678) `MoqOriginProducer::dynamic(prefix)` takes no `MoqRoute`, and `MoqOriginDynamic::update` is gone. diff --git a/rs/moq-ffi/src/audio.rs b/rs/moq-ffi/src/audio.rs index ae9a0dc896f..0cdbc0cf35c 100644 --- a/rs/moq-ffi/src/audio.rs +++ b/rs/moq-ffi/src/audio.rs @@ -366,6 +366,7 @@ pub struct MoqAudioProducer { reservation: std::sync::Mutex>>, /// Held so the reservation's registry outlives extra bandwidth handles. _bandwidth: Option>, + finished: crate::producer::Finished, } impl MoqAudioProducer { @@ -413,11 +414,14 @@ impl MoqAudioProducer { } /// Drain the encoder and finish the audio track. + /// + /// The broadcast keeps the finished track until it ends, so its finish still holds it. pub fn finish(&self) -> Result<(), MoqError> { let _guard = crate::ffi::runtime().enter(); let mut producer = self.inner.lock().unwrap().take().ok_or(MoqError::Closed)?; self.reservation.lock().unwrap().take(); producer.finish()?; + self.finished.keep(producer); Ok(()) } } @@ -471,9 +475,10 @@ impl MoqAudioProducer { options.bandwidth = bandwidth.allocator().clone(); } - let producer = broadcast.with_state(|state| { - moq_audio::encode::Producer::new(&mut state.broadcast, state.catalog.clone(), input, &options) - .map_err(Into::into) + let (producer, finished) = broadcast.with_state(|state| { + let producer = + moq_audio::encode::Producer::new(&mut state.broadcast, state.catalog.clone(), input, &options)?; + Ok((producer, state.finished.clone())) })?; // Producer::new does not reserve today (only capture does), so the @@ -487,6 +492,7 @@ impl MoqAudioProducer { inner: std::sync::Mutex::new(Some(producer)), reservation: std::sync::Mutex::new(reservation), _bandwidth: bandwidth, + finished, })) } } diff --git a/rs/moq-ffi/src/media.rs b/rs/moq-ffi/src/media.rs index 55f03e543d0..a753e094054 100644 --- a/rs/moq-ffi/src/media.rs +++ b/rs/moq-ffi/src/media.rs @@ -386,6 +386,7 @@ fn reserve_container( moq_net::broadcast::Producer, moq_mux::catalog::Reserved, crate::ffi::Background, + crate::producer::Finished, ), MoqError, > { @@ -394,7 +395,12 @@ fn reserve_container( Some(timebase) => timebase.reserve(broadcast, state)?, None => state.catalog.reserve(), }; - Ok((state.broadcast.clone(), reserved, state.driver.clone())) + Ok(( + state.broadcast.clone(), + reserved, + state.driver.clone(), + state.finished.clone(), + )) }) } @@ -765,18 +771,21 @@ struct MediaStreamProducer { pub struct MoqMediaContainerProducer { driver: crate::ffi::Background, inner: std::sync::Mutex>, + finished: crate::producer::Finished, } /// Imports complete encoded frames onto one track. #[derive(uniffi::Object)] pub struct MoqMediaTrackProducer { inner: std::sync::Mutex>, + finished: crate::producer::Finished, } /// Imports a video byte stream onto one track. #[derive(uniffi::Object)] pub struct MoqMediaTrackStreamProducer { inner: std::sync::Mutex>, + finished: crate::producer::Finished, } #[uniffi::export] @@ -800,7 +809,7 @@ impl MoqMediaTrackProducer { reason: format!("init failed: {err}"), } })?; - Ok(MoqMediaTrackProducer::from_import(import)) + Ok(MoqMediaTrackProducer::from_import(import, state.finished.clone())) }) } } @@ -827,7 +836,7 @@ impl MoqMediaTrackProducer { reason: format!("init failed: {err}"), } })?; - Ok(MoqMediaTrackProducer::from_import(import)) + Ok(MoqMediaTrackProducer::from_import(import, state.finished.clone())) }) } } @@ -844,7 +853,7 @@ impl MoqMediaContainerProducer { ) -> Result, MoqError> { let _guard = crate::ffi::enter(); let native = moq_mux::import::ContainerInit::new(init.format.into(), init.data); - let (target, reserved, driver) = reserve_container(broadcast, init.timebase.as_deref())?; + let (target, reserved, driver, finished) = reserve_container(broadcast, init.timebase.as_deref())?; let import = moq_mux::import::Container::new(target, reserved, &native).map_err(|err| MoqError::Codec { reason: format!("init failed: {err}"), })?; @@ -852,6 +861,7 @@ impl MoqMediaContainerProducer { Ok(Arc::new(MoqMediaContainerProducer { driver, inner: std::sync::Mutex::new(Some(ContainerProducer { import })), + finished, })) } } @@ -884,6 +894,7 @@ impl MoqMediaTrackStreamProducer { inner: std::sync::Mutex::new(Some(MediaStreamProducer { import: Box::new(import), })), + finished: state.finished.clone(), })) }) } @@ -891,13 +902,14 @@ impl MoqMediaTrackStreamProducer { impl MoqMediaTrackProducer { /// Wrap a single-codec importer, capturing the demand handle its track exposes. - fn from_import(import: moq_mux::import::Track) -> Arc { + fn from_import(import: moq_mux::import::Track, finished: crate::producer::Finished) -> Arc { let demand = import.demand(); Arc::new(Self { inner: std::sync::Mutex::new(Some(MediaProducer { import: Box::new(import), demand, })), + finished, }) } } @@ -991,6 +1003,8 @@ impl MoqMediaTrackProducer { } /// Finish this track and finalize encoding. + /// + /// The broadcast keeps the finished track until it ends, so its finish still holds it. pub fn finish(&self) -> Result<(), MoqError> { let _guard = crate::ffi::enter(); let mut guard = self.inner.lock().unwrap(); @@ -998,6 +1012,7 @@ impl MoqMediaTrackProducer { media.import.finish().map_err(|err| MoqError::Codec { reason: format!("finish failed: {err}"), })?; + self.finished.keep(media); Ok(()) } } @@ -1060,6 +1075,8 @@ impl MoqMediaContainerProducer { } /// Finish every track this container publishes. + /// + /// The broadcast keeps the finished tracks until it ends, so its finish still holds them. pub fn finish(&self) -> Result<(), MoqError> { let result = (|| { let _guard = crate::ffi::enter(); @@ -1068,6 +1085,7 @@ impl MoqMediaContainerProducer { container.import.finish().map_err(|err| MoqError::Codec { reason: format!("finish failed: {err}"), })?; + self.finished.keep(container); Ok(()) })(); self.driver.check()?; @@ -1099,6 +1117,8 @@ impl MoqMediaTrackStreamProducer { } /// Finalize the track, publishing the last access unit still waiting for a following start code. + /// + /// The broadcast keeps the finished track until it ends, so its finish still holds it. pub fn finish(&self) -> Result<(), MoqError> { let _guard = crate::ffi::enter(); let mut guard = self.inner.lock().unwrap(); @@ -1106,6 +1126,7 @@ impl MoqMediaTrackStreamProducer { media.import.finish().map_err(|err| MoqError::Codec { reason: format!("finish failed: {err}"), })?; + self.finished.keep(media); Ok(()) } } diff --git a/rs/moq-ffi/src/origin.rs b/rs/moq-ffi/src/origin.rs index 252acd3df84..9c27aee52ed 100644 --- a/rs/moq-ffi/src/origin.rs +++ b/rs/moq-ffi/src/origin.rs @@ -698,6 +698,25 @@ mod supervision_tests { .unwrap(); } + #[tokio::test] + async fn a_finish_after_a_driver_panic_closes_the_broadcast() { + let (inner, completion, trigger) = crate::ffi::panicking_origin(); + let origin = MoqOriginProducer::from_inner(Origin { + inner, + driver: completion.clone(), + }); + let broadcast = origin.create_broadcast("retained".into()).unwrap(); + // A dynamic handle outlives the consumed producer, so only an explicit close ends it. + let _dynamic = broadcast.dynamic().unwrap(); + let consumer = broadcast.state.lock().unwrap().as_ref().unwrap().broadcast.consume(); + *trigger + .write() + .unwrap_or_else(|_| unreachable!("test keeps its panic trigger open")) = true; + assert!(matches!(completion.finished().await, Err(MoqError::Task { .. }))); + assert!(matches!(broadcast.finish(), Err(MoqError::Task { .. }))); + assert!(consumer.is_closed()); + } + #[tokio::test] async fn container_importers_keep_the_origin_failure_after_other_owners_are_released() { use crate::media::{MoqContainerFormat, MoqContainerInit, MoqMediaContainerProducer, MoqMediaTimebase}; diff --git a/rs/moq-ffi/src/producer.rs b/rs/moq-ffi/src/producer.rs index 253a6586b9d..401ac753d3d 100644 --- a/rs/moq-ffi/src/producer.rs +++ b/rs/moq-ffi/src/producer.rs @@ -96,6 +96,47 @@ pub(crate) struct BroadcastProducer { // Core timebases own catalog outputs, so the broadcast holds them and binding handles stay weak. pub(crate) timebases: std::collections::HashMap>, pub(crate) driver: Background, + pub(crate) finished: Finished, +} + +impl Drop for BroadcastProducer { + fn drop(&mut self) { + self.finished.release(); + } +} + +/// The finished importers a broadcast keeps, or `None` once it ended. +type Keeping = Option>>; + +/// Finished producers a broadcast keeps until it ends. +/// +/// A track unlists once its last producer drops, and a finish holds only listed tracks. An +/// importer lets go of its producer when it finishes, and a binding may release a raw track's +/// handle whenever its garbage collector runs, so the broadcast keeps them here instead, and +/// [`MoqBroadcastProducer::finish`] still holds the track. +#[derive(Clone)] +pub(crate) struct Finished(Arc>); + +impl Default for Finished { + fn default() -> Self { + Self(Arc::new(std::sync::Mutex::new(Some(Vec::new())))) + } +} + +impl Finished { + /// Keep a finished producer until the broadcast ends, or drop it now if it already has. + pub(crate) fn keep(&self, producer: impl kio::MaybeSend + 'static) { + let producer: Box = Box::new(producer); + let mut kept = self.0.lock().unwrap(); + if let Some(kept) = kept.as_mut() { + kept.push(producer); + } + } + + /// Stop keeping, handing back what was kept so the caller decides when it drops. + fn release(&self) -> Vec> { + self.0.lock().unwrap().take().unwrap_or_default() + } } /// A broadcast in which tracks can be published. @@ -126,6 +167,7 @@ impl MoqTrackDynamic { struct DynamicProducer { inner: moq_net::broadcast::Dynamic, + finished: Finished, } struct TrackDynamicProducer { @@ -138,7 +180,7 @@ impl DynamicProducer { // accepts it (raw, at a chosen timescale) or publishes media onto it (importer accepts). // The subscriber's subscribe stays pending until then. let request = self.inner.requested_track().await?; - Ok(Arc::new(MoqTrackRequest::new(request))) + Ok(Arc::new(MoqTrackRequest::new(request, self.finished.clone()))) } } @@ -165,6 +207,7 @@ impl MoqBroadcastProducer { catalog, timebases: Default::default(), driver, + finished: Default::default(), })), }) } @@ -214,6 +257,7 @@ impl MoqBroadcastProducer { Ok(Arc::new(MoqBroadcastDynamic { task: Task::new(DynamicProducer { inner: state.broadcast.dynamic(), + finished: state.finished.clone(), }) .supervised(state.driver.clone()), })) @@ -274,6 +318,7 @@ impl MoqBroadcastProducer { let producer = broadcast.create_track(name, Some(info))?; Ok(Arc::new(MoqTrackProducer { inner: std::sync::Mutex::new(Some(producer)), + finished: std::sync::Mutex::new(Some(state.finished.clone())), })) }) } @@ -295,6 +340,95 @@ impl MoqBroadcastProducer { state.driver.check()?; result } + + /// End the broadcast cleanly, keeping it servable until its media goes stale. + /// + /// Finish every track first: the returned handle holds the tracks finished by now and keeps + /// the broadcast announced, so a subscriber still catching up can drain them. A track still + /// live is not held and adds nothing to the linger. Await [`MoqBroadcastFinish::wait`], or keep + /// the handle for [`MoqBroadcastFinish::linger_us`] on your own clock and then close it. + /// + /// Every later call on this producer fails with `Closed`, as after [`close`](Self::close). + pub fn finish(&self) -> Result, MoqError> { + let _guard = crate::ffi::enter(); + let mut state = self.state.lock().unwrap().take().ok_or(MoqError::Closed)?; + // Finished before the broadcast is, so the catalog lingers with the media. On failure the + // producer is gone, so close the broadcast rather than leave a dynamic handle holding it. + let ready = state.catalog.finish().map_err(MoqError::from); + if let Err(err) = ready.and_then(|()| state.driver.check()) { + state.broadcast.close(); + return Err(err); + } + let broadcast = state.broadcast.clone(); + // Released only once the finish holds their tracks. + let finished = state.finished.release(); + let finish = state.broadcast.clone().finish(); + drop(finished); + Ok(Arc::new(MoqBroadcastFinish { + linger: finish.linger(), + until: moq_clock::now().checked_add(finish.linger()), + broadcast, + finish: std::sync::Mutex::new(Some(finish)), + })) + } +} + +/// A cleanly ended broadcast, still announced and serving its finished tracks. +/// +/// Returned by [`MoqBroadcastProducer::finish`]. Closing or dropping it closes the broadcast, +/// which is how an interrupt ends the linger early. +#[derive(uniffi::Object)] +pub struct MoqBroadcastFinish { + linger: std::time::Duration, + // The linger counts from the finish, as a C caller's own clock would, not from the first + // poll of a wait; `None` when it overflows the clock. + until: Option, + // Closes the broadcast from any thread, ending a wait that took `finish`. + broadcast: moq_net::broadcast::Producer, + // Taken by `wait` or `close`. + finish: std::sync::Mutex>, +} + +#[uniffi::export] +impl MoqBroadcastFinish { + /// How long to keep the broadcast, in microseconds: the longest max age of the held tracks. + /// + /// Tracks still live at the finish, and tracks without a max age, add nothing. + pub fn linger_us(&self) -> u64 { + u64::try_from(self.linger.as_micros()).unwrap_or(u64::MAX) + } + + /// Keep the broadcast up for its linger, or until [`close`](Self::close), then close it. + /// + /// Cancelling the wait closes the broadcast at once. Errors with `Closed` once another wait + /// or a close took the handle. + pub async fn wait(&self) -> Result<(), MoqError> { + let finish = self.finish.lock().unwrap().take().ok_or(MoqError::Closed)?; + let until = self.until; + crate::ffi::detached(async move { + let closed = kio::wait(|waiter| finish.poll_closed(waiter)); + match until { + Some(until) => { + tokio::select! { + _ = moq_clock::sleep_until(until) => {} + _ = closed => {} + } + } + None => closed.await, + } + // Dropping the finish is what closes the broadcast. + drop(finish); + Ok::<_, MoqError>(()) + }) + .await + } + + /// Close the broadcast now, ending the linger and any wait. Closing again is a no-op. + pub fn close(&self) { + let _guard = crate::ffi::enter(); + self.broadcast.close(); + drop(self.finish.lock().unwrap().take()); + } } // ---- Dynamic Broadcast Producer ---- @@ -415,12 +549,14 @@ impl MoqGroupRequest { #[derive(uniffi::Object)] pub struct MoqTrackRequest { inner: std::sync::Mutex>, + finished: Finished, } impl MoqTrackRequest { - pub(crate) fn new(request: moq_net::track::Request) -> Self { + pub(crate) fn new(request: moq_net::track::Request, finished: Finished) -> Self { Self { inner: std::sync::Mutex::new(Some(request)), + finished, } } @@ -468,6 +604,7 @@ impl MoqTrackRequest { let request = self.take()?; Ok(Arc::new(MoqTrackProducer { inner: std::sync::Mutex::new(Some(request.accept(Some(info)))), + finished: std::sync::Mutex::new(Some(self.finished.clone())), })) } @@ -486,6 +623,8 @@ impl MoqTrackRequest { #[derive(uniffi::Object)] pub struct MoqTrackProducer { inner: std::sync::Mutex>, + // Taken by the first finish, so repeating it keeps the track only once. + finished: std::sync::Mutex>, } impl MoqTrackProducer { @@ -608,7 +747,8 @@ impl MoqTrackProducer { /// End the track at the live edge. /// /// [`finish_at`](Self::finish_at) declares the boundary ahead of time, so this keeps - /// that boundary. The handle remains so a later [`abort`](Self::abort) can still run. + /// that boundary. The handle remains so a later [`abort`](Self::abort) can still run, and + /// the broadcast keeps the finished track until it ends, so its finish still holds it. pub fn finish(&self) -> Result<(), MoqError> { let _guard = crate::ffi::enter(); let mut guard = self.inner.lock().unwrap(); @@ -616,6 +756,9 @@ impl MoqTrackProducer { if track.end().is_none() { track.finish()?; } + if let Some(finished) = self.finished.lock().unwrap().take() { + finished.keep(track.clone()); + } Ok(()) } @@ -720,6 +863,20 @@ mod metadata_tests { )); } + #[test] + fn repeated_finishes_keep_the_track_once() { + let broadcast = MoqBroadcastProducer::new().unwrap(); + let track = broadcast.publish_track("data".into(), None).unwrap(); + for _ in 0..3 { + track.finish().unwrap(); + } + let state = broadcast.state.lock().unwrap(); + let finished = &state.as_ref().unwrap().finished; + let kept = finished.0.lock().unwrap().as_ref().map(Vec::len); + drop(state); + assert_eq!(kept, Some(1)); + } + #[test] fn untimed_info_round_trips_through_the_binding() { let original = moq_net::track::Info::default(); diff --git a/rs/moq-ffi/src/test.rs b/rs/moq-ffi/src/test.rs index 080d34a6054..87240e05c68 100644 --- a/rs/moq-ffi/src/test.rs +++ b/rs/moq-ffi/src/test.rs @@ -1229,7 +1229,8 @@ async fn json_demand() { /// A demand handle waits without the producer, and fails once the track is gone. /// /// A raw track's `finish` keeps its handle open for a later `abort`, so its track ends when the -/// handle is released; a media producer's `finish` releases it. +/// handle is released; a media producer's `finish` hands it to the broadcast, so its track ends +/// when the broadcast does. #[tokio::test] async fn demand_handle_outlives_finish() { let broadcast = MoqBroadcastProducer::new().unwrap(); @@ -1254,6 +1255,7 @@ async fn demand_handle_outlives_finish() { track.finish().unwrap(); drop(track); media.finish().unwrap(); + broadcast.close().unwrap(); let track_err = tokio::time::timeout(TIMEOUT, track_demand.until_wanted()) .await .expect("timed out waiting for the finished raw track"); @@ -3565,6 +3567,162 @@ fn close_twice_is_a_noop() { ); } +/// A raw track with a millisecond max age, which is what a finish lingers for. +fn aged_info(max_age_ms: u64) -> MoqTrackInfo { + MoqTrackInfo { + max_age_us: Some(max_age_ms * 1_000), + ..timed_info() + } +} + +/// Wait for the announcement of `path` to end, failing the test if it doesn't. +async fn await_unannounced(announced: &MoqAnnounceConsumer) { + match next_event(announced).await { + MoqAnnounceEvent::End { .. } => {} + other => panic!("expected the announcement to end, got {other:?}"), + } +} + +/// A finished broadcast stays announced and serves its finished tracks to a late subscriber, +/// lingering for the longest max age among them; a live track adds nothing. +#[tokio::test] +async fn finish_serves_finished_tracks_to_a_late_subscriber() { + let origin = MoqOriginProducer::new(MoqOriginConfig::default()); + let consumer = origin.consume(); + let announced = consumer.announced(MoqAnnounceConfig::default()).unwrap(); + let broadcast = create_announced(&origin, "finish"); + next_announced(&announced).await; + + let video = broadcast.publish_track("video".into(), Some(aged_info(2_000))).unwrap(); + let audio = broadcast.publish_track("audio".into(), Some(aged_info(5_000))).unwrap(); + let live = broadcast.publish_track("live".into(), Some(aged_info(60_000))).unwrap(); + for track in [&video, &audio, &live] { + track + .write_frame(MoqFrame { + payload: b"tail".to_vec(), + timestamp_us: Some(0), + }) + .unwrap(); + } + video.finish().unwrap(); + audio.finish().unwrap(); + // A binding's garbage collector may release a finished handle before the broadcast finishes. + drop((video, audio)); + + let finish = broadcast.finish().unwrap(); + assert_eq!(finish.linger_us(), 5_000_000); + assert!(matches!(broadcast.consume(), Err(MoqError::Closed))); + broadcast.close().unwrap(); + + let late = await_announced(&consumer, "finish").await; + let track = late.subscribe_track("audio".into(), None).await.unwrap(); + let frame = tokio::time::timeout(TIMEOUT, track.read_frame()) + .await + .expect("timed out reading the finished track") + .unwrap() + .expect("expected the finished track's frame"); + assert_eq!(frame.payload, b"tail"); + + finish.close(); + await_unannounced(&announced).await; + finish.close(); + assert!(matches!(finish.wait().await, Err(MoqError::Closed))); + live.finish().unwrap(); +} + +/// Media tracks finish through their importer handles, which a finish must still hold. +#[tokio::test] +async fn finish_holds_finished_media_tracks() { + let broadcast = MoqBroadcastProducer::new().unwrap(); + let media = MoqMediaTrackProducer::audio( + &broadcast, + MoqMediaTarget::Named { name: None }, + audio_init(MoqAudioFormat::Opus, opus_head()), + ) + .unwrap(); + media + .write_frame(MoqFrame { + payload: b"opus frame".to_vec(), + timestamp_us: Some(0), + }) + .unwrap(); + media.finish().unwrap(); + drop(media); + + let finish = broadcast.finish().unwrap(); + assert!(finish.linger_us() > 0, "the finished media track was not held"); + finish.close(); +} + +/// Without a max age nothing lingers: the wait closes the broadcast at once. +#[tokio::test] +async fn finish_without_a_max_age_closes_on_wait() { + let origin = MoqOriginProducer::new(MoqOriginConfig::default()); + let consumer = origin.consume(); + let announced = consumer.announced(MoqAnnounceConfig::default()).unwrap(); + let broadcast = create_announced(&origin, "finish"); + next_announced(&announced).await; + let track = broadcast.publish_track("status".into(), Some(timed_info())).unwrap(); + track.finish().unwrap(); + + let finish = broadcast.finish().unwrap(); + assert_eq!(finish.linger_us(), 0); + tokio::time::timeout(TIMEOUT, finish.wait()) + .await + .expect("the wait outlived a zero linger") + .unwrap(); + await_unannounced(&announced).await; +} + +/// Closing the handle, the interrupt, ends a wait in progress and the broadcast with it. +#[tokio::test] +async fn closing_finish_ends_the_wait() { + let origin = MoqOriginProducer::new(MoqOriginConfig::default()); + let consumer = origin.consume(); + let announced = consumer.announced(MoqAnnounceConfig::default()).unwrap(); + let broadcast = create_announced(&origin, "finish"); + next_announced(&announced).await; + let track = broadcast + .publish_track("status".into(), Some(aged_info(3_600_000))) + .unwrap(); + track.finish().unwrap(); + + let finish = broadcast.finish().unwrap(); + let wait = spawn_parked({ + let finish = finish.clone(); + async move { finish.wait().await } + }) + .await; + finish.close(); + tokio::time::timeout(TIMEOUT, wait) + .await + .expect("the wait outlived the close") + .expect("the wait panicked") + .unwrap(); + await_unannounced(&announced).await; +} + +/// Dropping a wait in progress, as a cancelled foreign future does, closes the broadcast. +#[tokio::test] +async fn cancelling_the_wait_closes_the_broadcast() { + let origin = MoqOriginProducer::new(MoqOriginConfig::default()); + let consumer = origin.consume(); + let announced = consumer.announced(MoqAnnounceConfig::default()).unwrap(); + let broadcast = create_announced(&origin, "finish"); + next_announced(&announced).await; + let track = broadcast + .publish_track("status".into(), Some(aged_info(3_600_000))) + .unwrap(); + track.finish().unwrap(); + + let finish = broadcast.finish().unwrap(); + let mut wait = Box::pin(finish.wait()); + let first = std::future::poll_fn(|cx| std::task::Poll::Ready(wait.as_mut().poll(cx))).await; + assert!(first.is_pending()); + drop(wait); + await_unannounced(&announced).await; +} + #[tokio::test] async fn announced_broadcast() { let origin = MoqOriginProducer::new(MoqOriginConfig::default()); diff --git a/rs/moq-ffi/src/video.rs b/rs/moq-ffi/src/video.rs index 064698febc6..7d58a57d27e 100644 --- a/rs/moq-ffi/src/video.rs +++ b/rs/moq-ffi/src/video.rs @@ -275,9 +275,14 @@ impl MoqVideoEncoder { fn finalize( mut producer: moq_video::encode::Producer, drained: Result<(), moq_video::Error>, + finished: &crate::producer::Finished, ) -> Result<(), MoqError> { match drained { - Ok(()) => Ok(producer.finish()?), + Ok(()) => { + producer.finish()?; + finished.keep(producer); + Ok(()) + } Err(err) => { producer.abort(moq_net::Error::Transport(err.to_string())); Err(err.into()) @@ -370,14 +375,14 @@ impl VideoProducer { Ok(()) } - fn finish(self) -> Result<(), MoqError> { + fn finish(self, finished: &crate::producer::Finished) -> Result<(), MoqError> { let Self { encoder, mut producer, .. } = self; // Drain the codec into the track before ending it, so the last frames land // in it rather than being dropped with the encoder. let drained = block_on(encoder.finish()).and_then(|encoded| producer.publish(&encoded)); - finalize(producer, drained) + finalize(producer, drained, finished) } } @@ -395,6 +400,7 @@ pub struct MoqVideoProducer { applied: Arc, /// Held so the reservation's registry outlives extra bandwidth handles. _bandwidth: Option>, + finished: crate::producer::Finished, } impl MoqVideoProducer { @@ -511,6 +517,8 @@ impl MoqVideoProducer { } /// Flush any frames the codec is still holding and finalize the track. + /// + /// The broadcast keeps the finished track until it ends, so its finish still holds it. pub fn finish(&self) -> Result<(), MoqError> { let _guard = crate::ffi::runtime().enter(); let producer = self @@ -530,7 +538,7 @@ impl MoqVideoProducer { self.reservation.lock().unwrap().take(); // A follower panic only stops rate adaptation, so the encoded frames still // end the track cleanly before the panic is reported. - producer.finish()?; + producer.finish(&self.finished)?; followed } } @@ -577,6 +585,7 @@ impl MoqVideoProducer { let encoder = block_on(moq_video::encode::Sink::open(&config))?; let gop = config.gop.duration(config.framerate); let ceiling = video_ceiling(&config, &rendition); + let finished = broadcast.with_state(|state| Ok(state.finished.clone()))?; let producer = broadcast.with_state(|state| match output.track { Some(name) => { let track = state @@ -622,6 +631,7 @@ impl MoqVideoProducer { follow: std::sync::Mutex::new(follow), applied, _bandwidth: bandwidth, + finished, })) } } diff --git a/rs/moq-ffi/uniffi.toml b/rs/moq-ffi/uniffi.toml index 4dda0865a5a..5d42f15377b 100644 --- a/rs/moq-ffi/uniffi.toml +++ b/rs/moq-ffi/uniffi.toml @@ -1,5 +1,7 @@ # Kotlin objects are AutoCloseable, and `close()` there releases the handle, # which ends the broadcast only once no `dynamic()` handle remains. The -# generated forced end is `end()` so it doesn't collide with it. +# generated forced end is `end()` so it doesn't collide with it. A finish handle's +# `close()` ends the linger even while a wait holds the handle, so it is `end()` too. [bindings.kotlin.rename] "MoqBroadcastProducer.close" = "end" +"MoqBroadcastFinish.close" = "end" diff --git a/swift/MIGRATE.md b/swift/MIGRATE.md index 870cab6bf0b..044aa7fa273 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 +### Finished tracks stay until the broadcast ends (#6157) + +A finished track now stays listed, with its catalog rendition and demand, until its broadcast closes or the new `BroadcastProducer.finish()` lets go. +Publish a replacement under a new name, and expect a finished track's demand watch to end with the broadcast. + ### A claim answers by publishing (#5678) `OriginProducer.dynamic(prefix:)` takes no route, and `OriginDynamic.update(route:)` is gone. diff --git a/swift/Sources/Moq/Broadcast.swift b/swift/Sources/Moq/Broadcast.swift index 103b6b84b85..5c2d9f866c3 100644 --- a/swift/Sources/Moq/Broadcast.swift +++ b/swift/Sources/Moq/Broadcast.swift @@ -97,4 +97,42 @@ public final class BroadcastProducer: Sendable { public func close() throws { try ffi.close() } + + /// End the broadcast cleanly, keeping it servable until its media goes stale. + /// + /// Finish every track first: the returned handle holds the tracks finished by now and + /// keeps the broadcast announced, so a subscriber still catching up can drain them. A + /// track still live is not held. Every later call on this producer throws, as after + /// `close()`. + public func finish() throws -> BroadcastFinish { + BroadcastFinish(try ffi.finish()) + } +} + +/// A cleanly ended broadcast, still announced and serving its finished tracks. +/// +/// Closing it, or cancelling the task in `wait()`, closes the broadcast at once. +public final class BroadcastFinish: Sendable { + let ffi: MoqBroadcastFinish + + init(_ ffi: MoqBroadcastFinish) { + self.ffi = ffi + } + + /// How long to keep the broadcast, in microseconds: the longest max age of the held tracks. + public var lingerUs: UInt64 { ffi.lingerUs() } + + /// Keep the broadcast up for its linger, or until `close()`, then close it. + public func wait() async throws { + try await withTaskCancellationHandler { + try await ffi.wait() + } onCancel: { + ffi.close() + } + } + + /// Close the broadcast now, ending the linger and any wait. Closing again is a no-op. + public func close() { + ffi.close() + } } diff --git a/swift/Tests/MoqTests/SmokeTests.swift b/swift/Tests/MoqTests/SmokeTests.swift index 280dd08ce67..2e9ea4c4b34 100644 --- a/swift/Tests/MoqTests/SmokeTests.swift +++ b/swift/Tests/MoqTests/SmokeTests.swift @@ -263,6 +263,21 @@ final class SmokeTests: XCTestCase { XCTAssertThrowsError(try broadcast.publishTrack(name: "events")) } + func testFinishedBroadcastLingersUntilTheWaitIsCancelled() async throws { + let broadcast = try BroadcastProducer() + let track = try broadcast.publishTrack(name: "status", info: TrackInfo(maxAgeUs: 3_600_000_000)) + try track.finish() + let finish = try broadcast.finish() + XCTAssertEqual(finish.lingerUs, 3_600_000_000) + XCTAssertThrowsError(try broadcast.publishTrack(name: "events")) + // Cancelling the wait is the interrupt: it ends instead of lingering for an hour. + let wait = Task { try await finish.wait() } + await Task.yield() + wait.cancel() + _ = await wait.result + finish.close() + } + func testVideoHintsReachMediaPublishApi() throws { let broadcast = try BroadcastProducer() let hint = Media.VideoHint( diff --git a/swift/ffi/MIGRATE.md b/swift/ffi/MIGRATE.md index d85c40bac2d..3552e06292f 100644 --- a/swift/ffi/MIGRATE.md +++ b/swift/ffi/MIGRATE.md @@ -4,6 +4,12 @@ How to update your code for each breaking change, newest first. ## Unreleased +### Finished tracks stay until the broadcast ends (#6157) + +A finished track, raw or media, now stays listed, with its catalog rendition and demand, until its broadcast closes or the new `MoqBroadcastProducer.finish()` lets go, instead of unlisting when its producer finishes or is released. +Publish a replacement under a new name, and expect a finished track's demand watch to end with the broadcast. +Regenerate the bindings for the new `MoqBroadcastFinish` and the changed checksums. + ### Regenerate the matching bindings Documentation on `MoqAudioProducer::write` and `finish` changes their UniFFI metadata checksums.