diff --git a/c/moq/MIGRATE.md b/c/moq/MIGRATE.md index 568c8ec1267..48c82e836c2 100644 --- a/c/moq/MIGRATE.md +++ b/c/moq/MIGRATE.md @@ -4,6 +4,10 @@ How to update your code for each breaking change, newest first. ## Unreleased +### Viewer targets are bounded ([#7090](https://github.com/moq-dev/moq/pull/7090)) + +Viewer ceilings and PROBE target overrides are refused with the new `MOQ_ERROR_OUT_OF_RANGE` once they would sum above 2^53 - 1 bps, the most a PROBE target carries; nothing changes on a refusal. `moq_viewers_watch`, `moq_viewers_set_target`, and `moq_viewer_update` return it. Handle the new variant wherever you match the error exhaustively. Regenerate bindings and rebuild the matching native library together. + ### Media setup refusals are typed Audio and video subscribe setup now reports `MOQ_ERROR_UNSUPPORTED_CONFIG` when the decoder refuses a codec, layout, or description. Handle this variant to try another rendition instead of inspecting an audio/video error message or `Unsupported`. Decoder faults, such as a backend that fails to open, and later peer and decode failures keep their existing errors. Regenerate bindings and rebuild the matching native library together. diff --git a/cpp/moq/MIGRATE.md b/cpp/moq/MIGRATE.md index 5d21f4f59c0..07314ea0fd7 100644 --- a/cpp/moq/MIGRATE.md +++ b/cpp/moq/MIGRATE.md @@ -2,6 +2,10 @@ ## Unreleased +### Viewer targets are bounded ([#7090](https://github.com/moq-dev/moq/pull/7090)) + +Viewer ceilings and PROBE target overrides are refused with the new `moq::Error::kOutOfRange` once they would sum above 2^53 - 1 bps, the most a PROBE target carries; nothing changes on a refusal. `Viewers::watch` and `set_target` and `Viewer::update` return a `moq::expected` carrying it. Handle the new variant wherever you match the error exhaustively. Regenerate bindings and rebuild the matching native library together. + ### `moq::VideoInit::lower` takes either producer kind ([#7699](https://github.com/moq-dev/moq/pull/7699)) `lower` is `std::optional` instead of a `std::shared_ptr`. Assign `moq::MediaProducer(moq::MediaProducer::kTrack{producer})`, or `kStream` for a `moq::MediaTrackStreamProducer`. diff --git a/dart/moq/MIGRATE.md b/dart/moq/MIGRATE.md index 455dd1ca3a3..3b8b4f43267 100644 --- a/dart/moq/MIGRATE.md +++ b/dart/moq/MIGRATE.md @@ -4,6 +4,10 @@ How to update your code for each breaking change, newest first. ## Unreleased +### Viewer targets are bounded ([#7090](https://github.com/moq-dev/moq/pull/7090)) + +Viewer ceilings and PROBE target overrides are refused with the new `OutOfRangeMoqException` once they would sum above 2^53 - 1 bps, the most a PROBE target carries; nothing changes on a refusal. `Viewers.watch` and `setTarget` and `Viewer.update` throw it. Handle the new variant wherever you match the error exhaustively. Regenerate bindings and rebuild the matching native library together. + ### `VideoInit.lower` takes either producer kind ([#7699](https://github.com/moq-dev/moq/pull/7699)) `VideoInit.lower` is a `Producer` (`MoqMediaProducer`) instead of a `TrackProducer`. Pass `TrackMoqMediaProducer(producer: ...)`, or `StreamMoqMediaProducer(producer: ...)` for a byte-stream rendition. diff --git a/dart/moq/lib/src/aliases.dart b/dart/moq/lib/src/aliases.dart index f97c5c56074..fde53ff777c 100644 --- a/dart/moq/lib/src/aliases.dart +++ b/dart/moq/lib/src/aliases.dart @@ -198,6 +198,13 @@ typedef BandwidthConsumer = MoqBandwidthConsumer; /// One track's standing claim on an [Allocator]. typedef Reservation = MoqReservation; +/// Divides one connection's receive estimate among the broadcasts watched over it. +typedef Viewers = MoqViewers; + +/// One watched broadcast's standing claim on [Viewers]; holding it requests +/// PROBE, disposing it releases the claim. +typedef Viewer = MoqViewer; + /// Turns a [Reservation]'s grant into a sender's [RateTarget]; call `update` on every frame. typedef RateControl = MoqRateControl; diff --git a/dart/moq/lib/src/client.dart b/dart/moq/lib/src/client.dart index 267834ddf62..0ab5c3c40af 100644 --- a/dart/moq/lib/src/client.dart +++ b/dart/moq/lib/src/client.dart @@ -247,6 +247,16 @@ final class Moq { /// the room back. Allocator allocator() => session.allocator(); + /// The session's viewers, dividing the connection's receive estimate among + /// the broadcasts watched over it. + /// + /// Every call returns a handle to the same registry, and the session sends + /// what its viewers' ceilings add up to as its PROBE target. [Viewers.watch] + /// a broadcast with the ceiling of the largest rendition the player would + /// switch to, read its slice with [Viewer.rate], and dispose the [Viewer] + /// once the broadcast stops being watched. + Viewers viewers() => session.viewers(); + /// Follow the grant the peer gave this session. /// /// Listen to [GrantConsumerUpdates.updates] for the current grant and each diff --git a/dart/moq/test/moq_test.dart b/dart/moq/test/moq_test.dart index 0098a57d29c..1124c71e377 100644 --- a/dart/moq/test/moq_test.dart +++ b/dart/moq/test/moq_test.dart @@ -221,6 +221,22 @@ void main() { final serverSession = await accepted; expect(client.allocator(), isA()); + final viewers = client.viewers(); + expect(viewers, isA()); + final viewer = viewers.watch(maxBps: 4000000); + expect(viewer, isA()); + // A slice never exceeds its ceiling, whether or not QUIC has an estimate yet. + viewer.update(maxBps: 1000000); + expect(viewer.rate() ?? 0, lessThanOrEqualTo(1000000)); + viewers.setTarget(targetBps: 0); + viewers.setTarget(targetBps: null); + // Past what a PROBE target carries: refused. + expect( + () => viewers.watch(maxBps: 1 << 53), + throwsA(isA()), + ); + viewer.dispose(); + final announcement = client.announced().updates().firstWhere( (event) => event is AnnounceEventStart, ); diff --git a/dart/moq_ffi/MIGRATE.md b/dart/moq_ffi/MIGRATE.md index 1f0d514839c..df3475adb81 100644 --- a/dart/moq_ffi/MIGRATE.md +++ b/dart/moq_ffi/MIGRATE.md @@ -2,6 +2,10 @@ ## Unreleased +### Viewer targets are bounded ([#7090](https://github.com/moq-dev/moq/pull/7090)) + +Viewer ceilings and PROBE target overrides are refused with the new `OutOfRangeMoqException` once they would sum above 2^53 - 1 bps, the most a PROBE target carries; nothing changes on a refusal. `MoqViewers.watch` and `setTarget` and `MoqViewer.update` throw it. Handle the new variant wherever you match the error exhaustively. Regenerate bindings and rebuild the matching native library together. + ### Media setup refusals are typed Audio and video subscribe setup now reports `UnsupportedConfigMoqException` when the decoder refuses a codec, layout, or description. Handle this variant to try another rendition instead of inspecting an audio/video error message or `Unsupported`. Decoder faults, such as a backend that fails to open, and later peer and decode failures keep their existing errors. Regenerate bindings and rebuild the matching native library together. diff --git a/dart/moq_ffi/lib/src/moq.dart b/dart/moq_ffi/lib/src/moq.dart index 6060ab1678d..27fe6eac5d0 100644 --- a/dart/moq_ffi/lib/src/moq.dart +++ b/dart/moq_ffi/lib/src/moq.dart @@ -5769,6 +5769,12 @@ class FfiConverterMoqException { lifted.value, lifted.bytesRead - subview.offsetInBytes + 4, ); + case 35: + final lifted = OutOfRangeMoqException.read(subview); + return LiftRetVal( + lifted.value, + lifted.bytesRead - subview.offsetInBytes + 4, + ); default: throw UniffiInternalError( UniffiInternalError.unexpectedEnumCase, @@ -6972,6 +6978,44 @@ class UnsupportedConfigMoqException extends MoqException { } } +class OutOfRangeMoqException extends MoqException { + final String reason; + OutOfRangeMoqException(String this.reason); + OutOfRangeMoqException._(String this.reason); + static LiftRetVal read(Uint8List buf) { + int new_offset = buf.offsetInBytes; + final reason_lifted = FfiConverterString.read( + Uint8List.view(buf.buffer, new_offset), + ); + final reason = reason_lifted.value; + new_offset += reason_lifted.bytesRead; + return LiftRetVal(OutOfRangeMoqException._(reason), new_offset); + } + + @override + RustBuffer lower() { + final buf = Uint8List(allocationSize()); + write(buf); + return toRustBuffer(buf); + } + + @override + int allocationSize() { + return FfiConverterString.allocationSize(reason) + 4; + } + + @override + int write(Uint8List buf) { + buf.buffer.asByteData(buf.offsetInBytes).setInt32(0, 35); + int new_offset = buf.offsetInBytes + 4; + new_offset += FfiConverterString.write( + reason, + Uint8List.view(buf.buffer, new_offset), + ); + return new_offset; + } +} + class MoqExceptionErrorHandler extends UniffiRustCallStatusErrorHandler { @override Exception lift(RustBuffer errorBuf) { @@ -10203,6 +10247,185 @@ class FfiConverterMoqReservation { } } +abstract class MoqViewerInterface { + int? rate(); + void update({required int maxBps}); +} + +final _MoqViewerFinalizer = Finalizer>((ptr) { + rustCall((status) => uniffi_moq_ffi_fn_free_moqviewer(ptr, status)); +}); + +class MoqViewer implements MoqViewerInterface { + late final Pointer _ptr; + bool _isDisposed = false; + MoqViewer._(this._ptr) { + _MoqViewerFinalizer.attach(this, _ptr, detach: this); + } + factory MoqViewer.lift(Pointer ptr) { + return MoqViewer._(ptr); + } + Pointer uniffiClonePointer() { + if (_isDisposed) { + throw StateError("Object has already been disposed"); + } + return rustCall( + (status) => uniffi_moq_ffi_fn_clone_moqviewer(_ptr, status), + ); + } + + void dispose() { + if (_isDisposed) { + return; + } + final status = calloc(); + _isDisposed = true; + _MoqViewerFinalizer.detach(this); + try { + uniffi_moq_ffi_fn_free_moqviewer(_ptr, status); + checkCallStatus(NullRustCallStatusErrorHandler(), status); + } finally { + calloc.free(status); + } + } + + int? rate() { + return rustCallWithLifter( + (status) => + uniffi_moq_ffi_fn_method_moqviewer_rate(uniffiClonePointer(), status), + FfiConverterOptionalUInt64.lift, + null, + ); + } + + void update({required int maxBps}) { + return rustCall((status) { + uniffi_moq_ffi_fn_method_moqviewer_update( + uniffiClonePointer(), + FfiConverterUInt64.lower(maxBps), + status, + ); + }, moqExceptionErrorHandler); + } +} + +class FfiConverterMoqViewer { + static MoqViewer lift(Pointer ptr) { + return MoqViewer.lift(ptr); + } + + static Pointer lower(MoqViewer value) { + return value.uniffiClonePointer(); + } + + static int allocationSize(MoqViewer value) { + return 8; + } + + static LiftRetVal read(Uint8List buf) { + final handle = buf.buffer.asByteData(buf.offsetInBytes).getInt64(0); + final pointer = Pointer.fromAddress(handle); + return LiftRetVal(MoqViewer.lift(pointer), 8); + } + + static int write(MoqViewer value, Uint8List buf) { + final handle = lower(value); + buf.buffer.asByteData(buf.offsetInBytes).setInt64(0, handle.address); + return 8; + } +} + +abstract class MoqViewersInterface { + void setTarget({required int? targetBps}); + MoqViewer watch({required int maxBps}); +} + +final _MoqViewersFinalizer = Finalizer>((ptr) { + rustCall((status) => uniffi_moq_ffi_fn_free_moqviewers(ptr, status)); +}); + +class MoqViewers implements MoqViewersInterface { + late final Pointer _ptr; + bool _isDisposed = false; + MoqViewers._(this._ptr) { + _MoqViewersFinalizer.attach(this, _ptr, detach: this); + } + factory MoqViewers.lift(Pointer ptr) { + return MoqViewers._(ptr); + } + Pointer uniffiClonePointer() { + if (_isDisposed) { + throw StateError("Object has already been disposed"); + } + return rustCall( + (status) => uniffi_moq_ffi_fn_clone_moqviewers(_ptr, status), + ); + } + + void dispose() { + if (_isDisposed) { + return; + } + final status = calloc(); + _isDisposed = true; + _MoqViewersFinalizer.detach(this); + try { + uniffi_moq_ffi_fn_free_moqviewers(_ptr, status); + checkCallStatus(NullRustCallStatusErrorHandler(), status); + } finally { + calloc.free(status); + } + } + + void setTarget({required int? targetBps}) { + return rustCall((status) { + uniffi_moq_ffi_fn_method_moqviewers_set_target( + uniffiClonePointer(), + FfiConverterOptionalUInt64.lower(targetBps), + status, + ); + }, moqExceptionErrorHandler); + } + + MoqViewer watch({required int maxBps}) { + return rustCallWithLifter( + (status) => uniffi_moq_ffi_fn_method_moqviewers_watch( + uniffiClonePointer(), + FfiConverterUInt64.lower(maxBps), + status, + ), + FfiConverterMoqViewer.lift, + moqExceptionErrorHandler, + ); + } +} + +class FfiConverterMoqViewers { + static MoqViewers lift(Pointer ptr) { + return MoqViewers.lift(ptr); + } + + static Pointer lower(MoqViewers value) { + return value.uniffiClonePointer(); + } + + static int allocationSize(MoqViewers value) { + return 8; + } + + static LiftRetVal read(Uint8List buf) { + final handle = buf.buffer.asByteData(buf.offsetInBytes).getInt64(0); + final pointer = Pointer.fromAddress(handle); + return LiftRetVal(MoqViewers.lift(pointer), 8); + } + + static int write(MoqViewers value, Uint8List buf) { + final handle = lower(value); + buf.buffer.asByteData(buf.offsetInBytes).setInt64(0, handle.address); + return 8; + } +} + abstract class MoqBroadcastConsumerInterface { UniffiRustFuture closed(); UniffiRustFuture fetchGroup({ @@ -14643,6 +14866,7 @@ abstract class MoqSessionInterface { UniffiRustFuture stateChanged({required int after}); MoqConnectionStats stats(); MoqTokens? tokens(); + MoqViewers viewers(); } final _MoqSessionFinalizer = Finalizer>((ptr) { @@ -14815,6 +15039,17 @@ class MoqSession implements MoqSessionInterface { null, ); } + + MoqViewers viewers() { + return rustCallWithLifter( + (status) => uniffi_moq_ffi_fn_method_moqsession_viewers( + uniffiClonePointer(), + status, + ), + FfiConverterMoqViewers.lift, + null, + ); + } } class FfiConverterMoqSession { @@ -18660,6 +18895,73 @@ external void uniffi_moq_ffi_fn_method_moqreservation_update( Pointer uniffiStatus, ); +@Native Function(Pointer, Pointer)>( + assetId: _uniffiAssetId, +) +external Pointer uniffi_moq_ffi_fn_clone_moqviewer( + Pointer handle, + Pointer uniffiStatus, +); + +@Native, Pointer)>( + assetId: _uniffiAssetId, +) +external void uniffi_moq_ffi_fn_free_moqviewer( + Pointer handle, + Pointer uniffiStatus, +); + +@Native, Pointer)>( + assetId: _uniffiAssetId, +) +external RustBuffer uniffi_moq_ffi_fn_method_moqviewer_rate( + Pointer ptr, + Pointer uniffiStatus, +); + +@Native, Uint64, Pointer)>( + assetId: _uniffiAssetId, +) +external void uniffi_moq_ffi_fn_method_moqviewer_update( + Pointer ptr, + int max_bps, + Pointer uniffiStatus, +); + +@Native Function(Pointer, Pointer)>( + assetId: _uniffiAssetId, +) +external Pointer uniffi_moq_ffi_fn_clone_moqviewers( + Pointer handle, + Pointer uniffiStatus, +); + +@Native, Pointer)>( + assetId: _uniffiAssetId, +) +external void uniffi_moq_ffi_fn_free_moqviewers( + Pointer handle, + Pointer uniffiStatus, +); + +@Native, RustBuffer, Pointer)>( + assetId: _uniffiAssetId, +) +external void uniffi_moq_ffi_fn_method_moqviewers_set_target( + Pointer ptr, + RustBuffer target_bps, + Pointer uniffiStatus, +); + +@Native Function(Pointer, Uint64, Pointer)>( + assetId: _uniffiAssetId, +) +external Pointer uniffi_moq_ffi_fn_method_moqviewers_watch( + Pointer ptr, + int max_bps, + Pointer uniffiStatus, +); + @Native Function(Pointer, Pointer)>( assetId: _uniffiAssetId, ) @@ -20653,6 +20955,14 @@ external RustBuffer uniffi_moq_ffi_fn_method_moqsession_tokens( Pointer uniffiStatus, ); +@Native Function(Pointer, Pointer)>( + assetId: _uniffiAssetId, +) +external Pointer uniffi_moq_ffi_fn_method_moqsession_viewers( + Pointer ptr, + Pointer uniffiStatus, +); + @Native Function(Pointer, Pointer)>( assetId: _uniffiAssetId, ) @@ -21368,6 +21678,18 @@ external int uniffi_moq_ffi_checksum_method_moqreservation_rate(); @Native(assetId: _uniffiAssetId) external int uniffi_moq_ffi_checksum_method_moqreservation_update(); +@Native(assetId: _uniffiAssetId) +external int uniffi_moq_ffi_checksum_method_moqviewer_rate(); + +@Native(assetId: _uniffiAssetId) +external int uniffi_moq_ffi_checksum_method_moqviewer_update(); + +@Native(assetId: _uniffiAssetId) +external int uniffi_moq_ffi_checksum_method_moqviewers_set_target(); + +@Native(assetId: _uniffiAssetId) +external int uniffi_moq_ffi_checksum_method_moqviewers_watch(); + @Native(assetId: _uniffiAssetId) external int uniffi_moq_ffi_checksum_method_moqbroadcastconsumer_closed(); @@ -21833,6 +22155,9 @@ external int uniffi_moq_ffi_checksum_method_moqsession_stats(); @Native(assetId: _uniffiAssetId) external int uniffi_moq_ffi_checksum_method_moqsession_tokens(); +@Native(assetId: _uniffiAssetId) +external int uniffi_moq_ffi_checksum_method_moqsession_viewers(); + @Native(assetId: _uniffiAssetId) external int uniffi_moq_ffi_checksum_method_moqtokens_answered(); @@ -22086,6 +22411,18 @@ void _checkApiChecksums() { if (uniffi_moq_ffi_checksum_method_moqreservation_update() != 9626) { throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); } + if (uniffi_moq_ffi_checksum_method_moqviewer_rate() != 64505) { + throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); + } + if (uniffi_moq_ffi_checksum_method_moqviewer_update() != 27767) { + throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); + } + if (uniffi_moq_ffi_checksum_method_moqviewers_set_target() != 46661) { + throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); + } + if (uniffi_moq_ffi_checksum_method_moqviewers_watch() != 18224) { + throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); + } if (uniffi_moq_ffi_checksum_method_moqbroadcastconsumer_closed() != 12232) { throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); } @@ -22570,6 +22907,9 @@ void _checkApiChecksums() { if (uniffi_moq_ffi_checksum_method_moqsession_tokens() != 44247) { throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); } + if (uniffi_moq_ffi_checksum_method_moqsession_viewers() != 51586) { + throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); + } if (uniffi_moq_ffi_checksum_method_moqtokens_answered() != 11571) { throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); } diff --git a/doc/concept/standard.md b/doc/concept/standard.md index 805f6d2a5d9..bd28c41bad4 100644 --- a/doc/concept/standard.md +++ b/doc/concept/standard.md @@ -49,8 +49,11 @@ ignores unknown parameters: [cluster](/draft/moq-cluster) routing hop lists, [active-count](/draft/moq-active-count) to count the `NAMESPACE` messages before a `SUBSCRIBE_NAMESPACE` is synced, and [probe](/draft/moq-probe) for bandwidth estimation. Rust sessions request PROBE -only while an owned `recv_bandwidth()` consumer is held. Read estimates through -its `peek()` or `changed()` methods; session statistics do not request PROBE. +only while an owned `recv_bandwidth()` consumer or a `viewers()` viewer is held. +The consumer reads the estimate, and a viewer reads its share of it; session +statistics do not request PROBE. The viewers' ceilings, summed, are the PROBE target, sent only +to a peer advertising `Increase`, which a native session over moq-quic with BBR3 +does and a browser session does not yet. Both libraries offer solicit and auth unless a side's `extensions` setting declines one, which connects it as a peer that does not speak that extension. The pooled JavaScript `Connection` has no such setting yet. diff --git a/doc/lib/c/index.md b/doc/lib/c/index.md index 1e3acb31c0b..64763727acd 100644 --- a/doc/lib/c/index.md +++ b/doc/lib/c/index.md @@ -115,6 +115,7 @@ inside. The header is the reference: each function carries a doc comment. - **JSON windows.** `moq_publish_json_window` publishes a sliding run of records: `moq_publish_json_window_push` appends at the back, `moq_publish_json_window_pop` drops from the front, and `moq_publish_json_window_cut` closes the open group at a natural boundary. The catalog has no window mode, so a reader names the track. `moq_consume_json_window_event` fills `moq_json_window_event` with a push (the record at `start`, in `json`), a pop of `[start, end)`, or a skip of `[start, end)` that this reader joined too late to receive. Set `checkpoint_records` to bound what each new group restates for a window you never pop. - **Decoded reads.** `moq_decode_audio` and `moq_decode_video` deliver read ids in order: a frame, a gap where media was lost, or an end where the publisher stopped its encoder. Check `kind` on what `moq_decode_audio_read` or `moq_decode_video_read` writes. Free each id with `moq_decode_audio_read_free` or `moq_decode_video_read_free` promptly: a held video frame holds a decoder buffer, and the decoder stalls. A decoder reads everything the track still holds unless a live player sets `start` to `MOQ_DECODE_START_LATEST`, which joins at the newest group and skips the cached backlog. A decoder setup refusal reports `MOQ_ERROR_UNSUPPORTED_CONFIG` on its terminal callback, so the caller can try another rendition; later peer or decode failures retain their own error codes. - **Stats.** `moq_session_stats()` fills `moq_connection_stats` with `rtt_us`, `estimated_send_rate_bps`, and the byte and packet counters (`bytes_sent`, `bytes_received`, `bytes_lost`, `packets_sent`, `packets_received`, `packets_lost`). Each has a `_valid` flag, false when the transport does not report it, which is not the same as zero. `moq_session_snapshot()` adds the negotiated `protocol`. A failed dial or dropped connection reaches the session's `on_state` with its `failure` code, and `moq_error()` gives the reason during that callback. Hold the handle returned by `moq_session_recv_bandwidth()` to request receive estimates. `moq_bandwidth_consumer_peek()` reads the estimate and `moq_bandwidth_consumer_changed()` waits for a change. `moq_bandwidth_consumer_close()` releases demand; the last consumer stops PROBE. Stats snapshots do not request it. +- **Viewers.** `moq_session_viewers()` returns a handle that divides the receive estimate among the broadcasts you watch, max-min fair by each one's ceiling. `moq_viewers_watch()` returns a viewer claiming up to `max_bps`, the bitrate of the largest rendition you would switch to; `moq_viewer_rate()` reads its share in bits per second, with `present` false while there is no estimate (keep the current rendition), and `moq_viewer_update()` changes the ceiling. Holding a viewer requests the estimate like a `moq_session_recv_bandwidth()` consumer, and `moq_viewer_close()` releases the claim. The session sends the summed ceilings as its PROBE target; `moq_viewers_set_target()` with `present` true overrides that, a `0` target sends none, and `present` false follows the viewers again. `moq_viewers_watch()`, `moq_viewer_update()`, and `moq_viewers_set_target()` return `MOQ_ERROR_OUT_OF_RANGE`, changing nothing, when the ceilings or the target would pass 2^53 - 1 bps, the most a PROBE target carries. `moq_viewers_close()` releases the registry handle; viewers watched through it stay until each is closed. - **Demand.** A watcher from `moq_publish_track_demand()` (or the media, video, and audio variants) calls back `MOQ_DEMAND_WANTED` or `MOQ_DEMAND_UNWANTED`, again whenever the wanted group moves. `moq_publish_demand_wanted()` reads that group: start a new one once it passes your largest. Set `refresh` in `moq_track_info` to have a joining subscriber ask for a new group once the newest has grown past `refresh` times its first frame. A producer publishes everything you write, subscribed or not, so a late subscriber can fetch the recent past. Capturing only while the watcher reports `MOQ_DEMAND_WANTED` is an opt-in that saves the encode but leaves nothing from before the first subscriber. - **Disabled renditions.** A rendition with `enabled: false` has no frames coming until its publisher re-enables it. Query the latest catalog with `moq_consume_audio_enabled` or `moq_consume_video_enabled` before selecting a rendition and opening a decoder. Keep one already playing while every rendition of its kind is disabled: the convenience decoders accept a disabled configuration, and a re-enable, such as an unmute, then plays without a resubscribe. Among the video renditions you can decode, prefer the highest `preference`; `0` is the default and `-1` marks a compatibility transcode. diff --git a/doc/lib/cpp/index.md b/doc/lib/cpp/index.md index 7ca3caf14e1..7db92026a2c 100644 --- a/doc/lib/cpp/index.md +++ b/doc/lib/cpp/index.md @@ -213,6 +213,21 @@ A rendition with `enabled: false` has no frames coming until its publisher re-en Hold the owned `BandwidthConsumer` returned by `session->recv_bandwidth()` to receive bandwidth estimates. `rate()` reads the current estimate in bits per second and `rate_changed()` waits for a new one. 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. +## Viewers + +`session->viewers()` divides the receive estimate among the broadcasts you watch, max-min fair by each one's ceiling. `watch(max_bps)` returns a `Viewer` claiming up to a ceiling, the bitrate of the largest rendition you would switch to; its `rate()` reads that viewer's share in bits per second, `std::nullopt` while there is no estimate (keep the current rendition), and `update(max_bps)` changes the ceiling. Holding a viewer requests the estimate like `recv_bandwidth()`, and releasing it releases the claim. The session sends the summed ceilings as its PROBE target; `set_target(bps)` overrides that, `0` sends none, and `std::nullopt` follows the viewers again. `watch`, `update`, and `set_target` return `moq::Error::kOutOfRange` when the ceilings or the target would pass 2^53 - 1 bps, the most a PROBE target carries. Client viewers survive reconnects and read `std::nullopt` while disconnected. + +```cpp +auto viewers = session->viewers(); +auto camera = ok(viewers->watch(4'000'000)); // what its largest rendition needs +auto screen = ok(viewers->watch(1'000'000)); +if (auto bps = camera->rate()) { + // Switch to the largest rendition that fits in *bps. +} +ok(camera->update(2'500'000)); // the catalog disabled the top rendition +screen.reset(); // stopped watching: its share returns to camera +``` + ## Compressed tracks `moq::TrackInfo::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. diff --git a/doc/lib/dart/index.md b/doc/lib/dart/index.md index 6b99bb4d3f5..e6139f97676 100644 --- a/doc/lib/dart/index.md +++ b/doc/lib/dart/index.md @@ -156,6 +156,7 @@ shows which module holds each. - **Closing.** `await moq.close()` drains for up to one second and reports its result. `session.shutdown()` requests the drain synchronously; `await session.closed()` waits for its result. `session.cancel(code: 0)` closes at once. Finish or abort live tracks first. Awaiting cancellation of an announcement, grant, or request subscription releases its pending native read. Announcements and grants also release their consumer; server listeners leave their shared server usable. moq-lite-05 and newer wait for the peer to receive finished tails; older Lite versions and IETF wait only for transport ACKs. - **Ending cleanly.** When the input ends, finish every track, then call `finish()` on its `CatalogProducer` to finish the catalog, which ends the content. The broadcast stays announced and keeps serving the finished tracks, so a subscriber still catching up can drain them, until `broadcast.close()` takes it offline; disposing its `Publication` does not. How long to keep it up is yours to decide. A track still open at the close, or released without a finish, ends with `Unroutable` (`Internal` over moq-transport, which has no such code). Readers follow a publisher's runs by announcement, not by that error: see [identity and recovery](/concept/identity). - **Stats.** `session.stats()` reports `rtt`, `estimatedSendRateBps`, and the byte and packet counters (`bytesSent`, `bytesReceived`, `bytesLost`, `packetsSent`, `packetsReceived`, `packetsLost`). A field is `null` when the transport does not report it, which is not the same as zero. `version` names the negotiated protocol. Connect returns a connecting session; read its coherent `state()` snapshot and wait with that snapshot's revision to observe first-dial failures and reconnects. Each watcher keeps its own revision. Hold the owned `BandwidthConsumer` returned by `session.recvBandwidth()` to receive bandwidth estimates. `rate()` reads the current estimate in bits per second and `rateChanged()` waits for a new one. Release the consumer or call `cancel()` when finished; releasing the last consumer stops PROBE; the session and stats snapshots do not request it. Client consumers survive reconnects and report no estimate while disconnected. +- **Viewers.** `client.viewers()` divides the connection's receive estimate among the broadcasts you watch, max-min fair by each one's ceiling. `watch(maxBps: ...)` returns a `Viewer` claiming up to what the largest rendition the player would switch to needs; `rate()` reads its slice in bits per second, `null` while there is no estimate, so hold the current selection. `update(maxBps: ...)` changes the ceiling, such as when the catalog enables or disables a rendition. Holding a viewer requests PROBE, and the session sends the viewers' summed ceilings as the PROBE target; `dispose()` it once the broadcast stops being watched. `setTarget(targetBps: ...)` sends another target, `0` sends none, and `null` follows the viewers again. Ceilings or a target past 2^53 - 1 bps, the most a PROBE target carries, throw `OutOfRangeMoqException`. Client viewers survive reconnects and read `null` while disconnected. - **Authorization.** On `moq-lite-07-wip` (opt in with `ConnectOptions(versions: ...)`) and on moq-transport draft-18+ with the [MoQ Auth extension](/draft/moq-auth), listen to `moq.grants().updates()` for the `Grant` the relay sent back and each change, `null` until it answers and while a client session reconnects. - **Tokens.** Pass `ConnectOptions(tokens: [...])` instead of putting the credential in the URL. The first is the connection credential, sent in SETUP and, while an offered version can't carry it there (lite before 07), as the URL's `?jwt=`; each other token widens the grant over AUTH. `moq.tokens().set_(tokens: [...])` replaces them before they expire: the next dial presents them, a live AUTH session at once, and after an authorization refusal the session redials only if they changed. `await tokens().answered()` returns once the relay accepts them and throws its refusal with the relay's code. A `?jwt=` already in the URL stays the connection credential, which is how to reach a relay older than this release. - **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 35f5ddaa146..76ae948235e 100644 --- a/doc/lib/go/index.md +++ b/doc/lib/go/index.md @@ -137,6 +137,7 @@ shows which module holds each. - **Closing.** `client.Close()` drains for up to one second and returns an error on failure. `session.Shutdown()` requests that drain immediately; `session.Closed(ctx)` waits for its result, and `session.Cancel(code)` closes at once. Finish or abort live tracks first. moq-lite-05 and newer wait for the peer to receive finished tails; older Lite versions and IETF wait only for transport ACKs. - **Ending cleanly.** When the input ends, finish every track, then call `Finish()` on its `media.CatalogProducer` to finish the catalog, which ends the content. The broadcast stays announced and keeps serving the finished tracks, so a subscriber still catching up can drain them, until `broadcast.Close()` takes it offline. How long to keep it up is yours to decide. A track still open at the close, or released without a finish, ends with `Unroutable` (`Internal` over moq-transport, which has no such code). Readers follow a publisher's runs by announcement, not by that error: see [identity and recovery](/concept/identity). - **Stats.** `Session().Stats()` reports `RTT`, `EstimatedSendRateBps`, and the byte and packet counters (`BytesSent`, `BytesReceived`, `BytesLost`, `PacketsSent`, `PacketsReceived`, `PacketsLost`). A field is nil when the transport does not report it, which is not the same as zero. `Version` names the negotiated protocol. `Dial` returns a connecting session; read `Session().State()` and wait with `StateChanged(ctx, state.Revision)` to observe first-dial failures and reconnects. Hold the owned `BandwidthConsumer` returned by `Session().RecvBandwidth()` to receive bandwidth estimates. `Rate()` reads the current estimate in bits per second and `RateChanged(ctx)` waits for a new one. Calling `Close()` on the last consumer stops PROBE; the session and stats snapshots do not request it. Client consumers survive reconnects and report no estimate while disconnected. +- **Viewers.** `Session().Viewers()` divides the connection's receive estimate among the broadcasts you watch, max-min fair by each one's ceiling. `Watch(maxBps)` returns a `Viewer` claiming up to what the largest rendition the player would switch to needs; `Rate()` reads its slice in bits per second, nil while there is no estimate, so hold the current selection. `Update(maxBps)` changes the ceiling, such as when the catalog enables or disables a rendition. Holding a viewer requests PROBE, and the session sends the viewers' summed ceilings as the PROBE target; `Close()` it once the broadcast stops being watched, from the goroutine that last used it. `SetTarget(&bps)` sends another target, zero sends none, and nil follows the viewers again. `Watch`, `Update`, and `SetTarget` return `moq.ErrOutOfRange` when the ceilings or the target would pass 2^53 - 1 bps, the most a PROBE target carries. Client viewers survive reconnects and read nil while disconnected. - **Authorization.** On `moq-lite-07-wip` (opt in with `ClientConfig.Versions`) and on moq-transport draft-18+ with the [MoQ Auth extension](/draft/moq-auth), `Session().Grants()` returns a `GrantConsumer`: `Grant()` is the `Grant` the relay sent back, nil until it answers and while a client session reconnects, and `Changed(ctx)` waits for the next one. `Close()` it when done. - **Tokens.** Set `ClientConfig.Tokens` instead of putting the credential in the URL. The first is the connection credential, sent in SETUP and, while an offered version can't carry it there (lite before 07), as the URL's `?jwt=`; each other token widens the grant over AUTH. `Session().Tokens().Set(...)` replaces a client session's tokens before they expire: the next dial presents them, a live AUTH session at once, and after an authorization refusal the session redials only if they changed. `Answered(ctx)` returns nil once the relay accepts them, or its refusal with the relay's code. A `?jwt=` already in the URL stays the connection credential, which is how to reach a relay older than this release. - **Errors.** Read diagnostic payloads from `Reason` and structured protocol failures from `Details`. diff --git a/doc/lib/js/net.md b/doc/lib/js/net.md index 0b10f7e8b08..60b99b4fee1 100644 --- a/doc/lib/js/net.md +++ b/doc/lib/js/net.md @@ -47,6 +47,7 @@ publication.announce(); - **Connections share by URL and versions.** `new Connection({ url })` pools and reconnects with backoff, which the elements use. An ordered `versions` list, spelled like `moq-lite-06` as in Rust, applies to both WebTransport and WebSocket; equivalent lists share, while a different order or an omitted list gets its own pool entry. Supplying your own transport options or origin selects a private loop. Receive estimates are on demand: observe `connection.probe` reactively or subscribe while you need them; `peek()` alone opens no PROBE stream. - **GOAWAY moves the session.** The connection dials the replacement at once while the old session keeps serving its groups, up to `goaway.handover` (default 10s, or the relay's deadline when that is sooner). New requests keep opening on the old session until the replacement's route outranks it, which is a restart when the instance did not cross: an unpinned announced request follows the replacement, while a blind or instance-pinned request stays on its accepted stream. When `moq-lite-07-wip` is offered the instance crosses, the replacement serves the same stream, and open subscriptions move across without missing a group. An empty GOAWAY redials the same URL. A redirect stays on the same host unless `goaway.redirect` is `"follow"`, which also presents the tokens on the connection's `auth` handle to the new host. A one-shot session from `Connection.connect` never moves on its own; its `draining` settles with the GOAWAY, so you can connect again and close it. Its URI is the peer's to choose and `goaway.redirect` does not apply, so validate it before dialing it or presenting tokens to it. - **One send estimate per connection.** `Bandwidth.Allocator` divides it by track priority, max-min fair within a tier. An idle track claims nothing, though its reservation still reads the share it would get. Publishers reserve against it so their targets sum to the estimate. A connection samples the estimate from its transport only while a reservation reads it, so receive-only and lingering connections do no stats work, and the first reservation after none reads `undefined` until one fresh snapshot lands. A transport that cannot report one is never sampled and reads `undefined`: the WebSocket fallback, WebRTC, and WebTransport without `getStats()` (shipping Chromium and Safari). +- **One receive estimate per connection.** `connection.viewers` divides it among watched broadcasts, max-min fair by each viewer's ceiling, so several players on one pooled connection don't each select against the whole downlink. Holding a viewer requests PROBE, and the viewers' ceilings, summed, are the PROBE target a relay advertising `Increase` probes the downlink up to. `setTarget(0)` opts out. `watch`, `update`, and `setTarget` throw a `RangeError` when the ceilings or the target would pass `Viewers.MAX_TARGET` (`Number.MAX_SAFE_INTEGER`), the most a PROBE target carries. - **List a broadcast's tracks.** `for await (const event of broadcast.tracks())` reports each track the broadcast lists (`added`, with its `Track.Info`), one `synced`, then `added` and `removed` as tracks come and go, until the broadcast ends; leaving the loop stops listing. Over a session it needs `moq-lite-07-wip`, syncs at once with what this side holds, and the peer's tracks follow as `added`. A track served only on request is never listed. See [discovery](/concept/moq-lite#discovery). - **One track per name.** Concurrent subscriptions share one request and producer. `createTrack` on a name with a request still queued answers it. The application owns sequence numbers: the broadcast keeps nothing of an ended track, so a track that replaces it, created or requested, starts at 0. A name always means the same content, so the replacement continues past its predecessor's groups by writing its first group with an explicit sequence. Sequences are `bigint`, so every ID the wire carries fits, past 2^53 included: `track.createGroup(5n)`, `{ absolute: 10n }`. Frame indices and relative anchors stay `number`. - **Serve history on request.** `track.requests()` opens a handle that serves the groups readers miss: ones their ranges name below the newest group written that the cache no longer holds, or never did. Each run of misses arrives as a `Track.Fill` from `await requests.requestedFill()`, shared by every reader missing it. `accept(sequence)` it into the cache and write the group's frames as first published, `dropGroups(start, end)` what the source lacks (sequences are `bigint`), and serve `wanted()` until it is `undefined`: a reader that leaves or narrows stops wanting its groups. `close()` the fill when done; whatever is still wanted is named dropped. A `fetchGroup` of an uncached group asks the handle at once, even for a group not written yet, which a live write then answers; with no handle open it fails with `NotFound`, as in Rust, and a reader's miss is given up. A reader only asks for what its `delay.max` still wants, so a reader at the live edge never asks. This serves lite FETCH and lite-07 ranged subscriptions from the same track, as Rust's `requests()` does. diff --git a/doc/lib/kt/index.md b/doc/lib/kt/index.md index b2446076cdf..6f611203685 100644 --- a/doc/lib/kt/index.md +++ b/doc/lib/kt/index.md @@ -111,6 +111,7 @@ shows which module holds each. - **Closing.** `moq.shutdown()` requests a drain immediately; suspending `moq.session.closed()` waits up to one second and reports its result. `Moq.close()`, and so `use { }`, cancels at once. Finish or abort live tracks first. moq-lite-05 and newer wait for the peer to receive finished tails; older Lite versions and IETF wait only for transport ACKs. - **Ending cleanly.** When the input ends, finish every track, then call `finish()` on its `CatalogProducer` to finish the catalog, which ends the content. The broadcast stays announced and keeps serving the finished tracks, so a subscriber still catching up can drain them, until `broadcast.end()` takes it offline. How long to keep it up is yours to decide. A track still open at the end, or released without a finish, ends with `Unroutable` (`Internal` over moq-transport, which has no such code). Readers follow a publisher's runs by announcement, not by that error: see [identity and recovery](/concept/identity). - **Stats.** `session.stats()` reports `rtt`, `estimatedSendRateBps`, and the byte and packet counters (`bytesSent`, `bytesReceived`, `bytesLost`, `packetsSent`, `packetsReceived`, `packetsLost`). A field is `null` when the transport does not report it, which is not the same as zero. `version` names the negotiated protocol. Connect returns a connecting session; read its coherent `state()` snapshot and wait with that snapshot's revision to observe first-dial failures and reconnects. Each watcher keeps its own revision. Hold the owned `BandwidthConsumer` returned by `session.recvBandwidth()` to receive bandwidth estimates. `rate()` reads the current estimate in bits per second and `rateChanged()` waits for a new one. Release the consumer or call `cancel()` when finished; releasing the last consumer stops PROBE; the session and stats snapshots do not request it. Client consumers survive reconnects and report no estimate while disconnected. +- **Viewers.** `moq.viewers()` divides the connection's receive estimate among the broadcasts you watch, max-min fair by each one's ceiling. `watch(maxBps)` returns a `Viewer` claiming up to what the largest rendition the player would switch to needs; `rate()` reads its slice in bits per second, `null` while there is no estimate, so hold the current selection. `update(maxBps)` changes the ceiling, such as when the catalog enables or disables a rendition. Holding a viewer requests PROBE, and the session sends the viewers' summed ceilings as the PROBE target; `close()` it, or leave `use { }`, once the broadcast stops being watched. `setTarget(bps)` sends another target, `0` sends none, and `null` follows the viewers again. Ceilings or a target past 2^53 - 1 bps, the most a PROBE target carries, throw `MoqException.OutOfRange`. Client viewers survive reconnects and read `null` while disconnected. - **Authorization.** On `moq-lite-07-wip` (opt in with `ClientConfig(versions = ...)`) and on moq-transport draft-18+ with the [MoQ Auth extension](/draft/moq-auth), collect `moq.grants().updates()` for the `Grant` the relay sent back and each change, `null` until it answers and while a client session reconnects. Ending the collection cancels the consumer. - **Tokens.** Pass `ClientConfig(tokens = listOf(...))` instead of putting the credential in the URL. The first is the connection credential, sent in SETUP and, while an offered version can't carry it there (lite before 07), as the URL's `?jwt=`; each other token widens the grant over AUTH. `moq.tokens().set(listOf(...))` replaces them before they expire: the next dial presents them, a live AUTH session at once, and after an authorization refusal the session redials only if they changed. Suspending `tokens().answered()` returns once the relay accepts them and throws its refusal with the relay's code. A `?jwt=` already in the URL stays the connection credential, which is how to reach a relay older than this release. - **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 f4cc705f22d..1064174de64 100644 --- a/doc/lib/py/index.md +++ b/doc/lib/py/index.md @@ -125,6 +125,7 @@ shows which module holds each. - **Closing.** `session.shutdown()` requests a drain immediately; `await session.closed()` waits up to one second and reports its result. `cancel(code)` closes at once. Finish or abort live tracks first. moq-lite-05 and newer wait for the peer to receive finished tails; older Lite versions and IETF wait only for transport ACKs. - **Ending cleanly.** When the input ends, finish every track, then call `finish()` on its `moq.media.CatalogProducer` to finish the catalog, which ends the content. The broadcast stays announced and keeps serving the finished tracks, so a subscriber still catching up can drain them, until `broadcast.close()` takes it offline. How long to keep it up is yours to decide. A track still open at the close, or released without a finish, ends with `Unroutable` (`Internal` over moq-transport, which has no such code). Readers follow a publisher's runs by announcement, not by that error: see [identity and recovery](/concept/identity). - **Stats.** `session.stats()` reports `rtt`, `estimated_send_rate_bps`, and the byte and packet counters (`bytes_sent`, `bytes_received`, `bytes_lost`, `packets_sent`, `packets_received`, `packets_lost`). A field is `None` when the transport does not report it, which is not the same as zero. `version` names the negotiated protocol. Connect returns a connecting session; read its coherent `state()` snapshot and wait with that snapshot's revision to observe first-dial failures and reconnects. Each watcher keeps its own revision. Hold the owned `BandwidthConsumer` returned by `session.recv_bandwidth()` to receive bandwidth estimates. `rate()` reads the current estimate in bits per second and `rate_changed()` waits for a new one. Release the consumer or call `cancel()` when finished; releasing the last consumer stops PROBE; the session and stats snapshots do not request it. Client consumers survive reconnects and report no estimate while disconnected. +- **Viewers.** `session.viewers()` divides the receive estimate among the broadcasts you watch. `watch(max_bps)` returns a `Viewer` claiming up to a ceiling, the bitrate of the largest rendition you would switch to; its `rate()` reads that viewer's fair share in bits per second, `None` while there is no estimate (keep the current rendition), and `update(max_bps)` changes the ceiling. Holding a viewer requests the estimate like `recv_bandwidth()`, and dropping it releases the claim. The session sends the summed ceilings as its PROBE target; `set_target(bps)` overrides that, `0` sends none, and `None` follows the viewers again. Ceilings or a target past 2^53 - 1 bps, the most a PROBE target carries, raise `moq.Error.OutOfRange`. - **Authorization.** On `moq-lite-07-wip` (opt in with `versions=`) and on moq-transport draft-18+ with the [MoQ Auth extension](/draft/moq-auth), `async for grant in session.grants()` yields the `Grant` the relay sent back and each change, `None` until it answers and while a client session reconnects. `grants().grant()` reads it once; cancelling or leaving an `async with` releases the wait. - **Tokens.** Pass `tokens=[...]` instead of putting the credential in the URL. The first is the connection credential, sent in SETUP and, while an offered version can't carry it there (lite before 07), as the URL's `?jwt=`; each other token widens the grant over AUTH. `session.tokens().set([...])` replaces a client session's tokens before they expire: the next dial presents them, a live AUTH session at once, and after an authorization refusal the session redials only if they changed. `await tokens.answered()` returns once the relay accepts them and raises its refusal with the relay's code. A `?jwt=` already in the URL stays the connection credential, which is how to reach a relay older than this release. - **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 14167f2d129..35895c71e49 100644 --- a/doc/lib/swift/index.md +++ b/doc/lib/swift/index.md @@ -111,6 +111,7 @@ shows which module holds each. - **Closing.** `session.shutdown()` requests a drain immediately; `try await session.closed()` waits up to one second and reports its result. `session.cancel(code:)` closes at once. Finish or abort live tracks first. moq-lite-05 and newer wait for the peer to receive finished tails; older Lite versions and IETF wait only for transport ACKs. - **Ending cleanly.** When the input ends, finish every track, then call `try finish()` on its `Media.CatalogProducer` to finish the catalog, which ends the content. The broadcast stays announced and keeps serving the finished tracks, so a subscriber still catching up can drain them, until `broadcast.close()` takes it offline. How long to keep it up is yours to decide. A track still open at the close, or released without a finish, ends with `Unroutable` (`Internal` over moq-transport, which has no such code). Readers follow a publisher's runs by announcement, not by that error: see [identity and recovery](/concept/identity). - **Stats.** `session.stats()` reports `rtt`, `estimatedSendRateBps`, and the byte and packet counters (`bytesSent`, `bytesReceived`, `bytesLost`, `packetsSent`, `packetsReceived`, `packetsLost`). A field is `nil` when the transport does not report it, which is not the same as zero. `version` names the negotiated protocol. Connect returns a connecting session; read its coherent `state()` snapshot and wait with that snapshot's revision to observe first-dial failures and reconnects. Each watcher keeps its own revision. Hold the owned `BandwidthConsumer` returned by `session.recvBandwidth()` to receive bandwidth estimates. `rate()` reads the current estimate in bits per second and `rateChanged()` waits for a new one. Release the consumer or call `cancel()` when finished; releasing the last consumer stops PROBE; the session and stats snapshots do not request it. Client consumers survive reconnects and report no estimate while disconnected. +- **Viewers.** `session.viewers()` divides the receive estimate among the broadcasts you watch. `watch(maxBps:)` returns a `Viewer` claiming up to a ceiling, the bitrate of the largest rendition you would switch to; its `rate()` reads that viewer's fair share in bits per second, `nil` while there is no estimate (keep the current rendition), and `update(maxBps:)` changes the ceiling. Holding a viewer requests the estimate like `recvBandwidth()`, and releasing it releases the claim. The session sends the summed ceilings as its PROBE target; `setTarget(targetBps:)` overrides that, `0` sends none, and `nil` follows the viewers again. `watch`, `update`, and `setTarget` throw `MoqError.OutOfRange` when the ceilings or the target would pass 2^53 - 1 bps, the most a PROBE target carries. - **Authorization.** On `moq-lite-07-wip` (opt in with `Client(versions:)`) and on moq-transport draft-18+ with the [MoQ Auth extension](/draft/moq-auth), `for try await grant in session.grants()` yields the `Grant` the relay sent back and each change, `nil` until it answers and while a client session reconnects. Cancelling the iterating task cancels the native wait. - **Tokens.** Pass `Client(tokens: [...])` instead of putting the credential in the URL. The first is the connection credential, sent in SETUP and, while an offered version can't carry it there (lite before 07), as the URL's `?jwt=`; each other token widens the grant over AUTH. `try session.tokens()?.set([...])` replaces them before they expire: the next dial presents them, a live AUTH session at once, and after an authorization refusal the session redials only if they changed. `try await tokens.answered()` returns once the relay accepts them and throws its refusal with the relay's code. A `?jwt=` already in the URL stays the connection credential, which is how to reach a relay older than this release. - **Errors.** Diagnostic cases use the `reason:` argument label; match their associated value to inspect it. Protocol errors carry `details`. diff --git a/go/wrapper/MIGRATE.md b/go/wrapper/MIGRATE.md index 86416d17b97..08d483234ed 100644 --- a/go/wrapper/MIGRATE.md +++ b/go/wrapper/MIGRATE.md @@ -4,6 +4,10 @@ How to update your code for each breaking change, newest first. ## Unreleased +### Viewer targets are bounded ([#7090](https://github.com/moq-dev/moq/pull/7090)) + +Viewer ceilings and PROBE target overrides are refused with the new `ErrOutOfRange` once they would sum above 2^53 - 1 bps, the most a PROBE target carries; nothing changes on a refusal. `Viewers.Watch` returns `(*Viewer, error)`, and `Viewers.SetTarget` and `Viewer.Update` return an `error`. Handle the new variant wherever you match the error exhaustively. Regenerate bindings and rebuild the matching native library together. + ### `media.VideoInit.Lower` is a `media.Producer` ([#7699](https://github.com/moq-dev/moq/pull/7699)) `Lower` is the `media.Producer` interface instead of `*media.TrackProducer`, so a `*media.TrackStreamProducer` fits too. Assigning a `*media.TrackProducer`, nil included, compiles unchanged; code that reads `Lower` back type-asserts it. diff --git a/go/wrapper/README.md b/go/wrapper/README.md index a36c8f5725a..27feead3fa3 100644 --- a/go/wrapper/README.md +++ b/go/wrapper/README.md @@ -80,6 +80,15 @@ return its share and automatic probe ceiling immediately, even while the track stays subscribed. A later update can resume the same claim. While the track stays open, dropping the Go reference alone leaves release to garbage collection. +A player divides the receive estimate among the broadcasts it watches with +`Client.Session().Viewers()`. `Watch(maxBps)` claims up to what the largest +rendition it would switch to needs; the viewer's `Rate()` is its slice, nil +while there is no estimate, and `Update(maxBps)` changes the ceiling. The +session sends the viewers' summed ceilings as its PROBE target, which +`SetTarget` overrides. Ceilings or a target summing above 2^53 - 1 fail with +`moq.ErrOutOfRange`. Holding a viewer requests PROBE, so `Close()` it once +the broadcast stops being watched. + Incoming server requests expose the query-free `Path()` before `Accept()`. It is consistent across transports and returns an empty string for the root or missing path. `Query()` returns the encoded query and may contain credentials. diff --git a/go/wrapper/bandwidth_test.go b/go/wrapper/bandwidth_test.go index 5783bed2e4c..5475fc39850 100644 --- a/go/wrapper/bandwidth_test.go +++ b/go/wrapper/bandwidth_test.go @@ -2,6 +2,7 @@ package moq_test import ( "context" + "errors" "math" "runtime" "testing" @@ -86,3 +87,68 @@ func TestReservationUpdateReleasesSubscribedTrack(t *testing.T) { } runtime.KeepAlive(retired) } + +// Viewers are wired through the session: watch, update, override the target, +// and release a viewer without disturbing the registry. The moq-ffi tests +// cover how the estimate divides. +func TestViewersWatchUpdateAndClose(t *testing.T) { + ctx, cancel := context.WithTimeout(context.Background(), testTimeout) + defer cancel() + relay := startRelay(t, ctx, "127.0.0.1:0") + defer relay.server.Close() + client, err := moq.Dial(ctx, "https://"+relay.addr, moq.ClientConfig{ + TLS: moq.ClientTLS{Insecure: true}, + Once: true, + }) + if err != nil { + t.Fatal(err) + } + defer client.Close() + waitConnects(t, ctx, client.Session(), 1) + + viewers := client.Session().Viewers() + first, err := viewers.Watch(4_000_000) + if err != nil { + t.Fatal(err) + } + second, err := viewers.Watch(1_000_000) + if err != nil { + t.Fatal(err) + } + // Whether QUIC has a receive estimate yet varies, but a slice never exceeds its ceiling. + if rate := second.Rate(); rate != nil && *rate > 1_000_000 { + t.Fatalf("rate = %d, above its 1000000 ceiling", *rate) + } + if err := second.Update(500_000); err != nil { + t.Fatal(err) + } + if rate := second.Rate(); rate != nil && *rate > 500_000 { + t.Fatalf("rate = %d, above its 500000 ceiling", *rate) + } + zero := uint64(0) + if err := viewers.SetTarget(&zero); err != nil { + t.Fatal(err) + } + if err := viewers.SetTarget(nil); err != nil { + t.Fatal(err) + } + // Past what a PROBE target carries: refused. + if _, err := viewers.Watch(1 << 53); !errors.Is(err, moq.ErrOutOfRange) { + t.Fatalf("Watch(2^53) = %v, want ErrOutOfRange", err) + } + + // Closing one viewer leaves the others and the registry usable. + second.Close() + if err := first.Update(2_000_000); err != nil { + t.Fatal(err) + } + if rate := first.Rate(); rate != nil && *rate > 2_000_000 { + t.Fatalf("rate = %d, above its 2000000 ceiling", *rate) + } + first.Close() + last, err := client.Session().Viewers().Watch(1) + if err != nil { + t.Fatal(err) + } + last.Close() +} diff --git a/go/wrapper/errors.go b/go/wrapper/errors.go index 022bd5d3d98..73057fa29c9 100644 --- a/go/wrapper/errors.go +++ b/go/wrapper/errors.go @@ -91,6 +91,8 @@ var ( ErrLog = ffi.ErrMoqErrorLog // ErrConfig is returned when Dial or Listen is given a value the native side cannot use. ErrConfig = ffi.ErrMoqErrorConfig + // ErrOutOfRange is returned when a number is outside the range the call accepts, such as viewer ceilings summing above 2^53 - 1. + ErrOutOfRange = ffi.ErrMoqErrorOutOfRange ) // IsShutdown reports whether err is the expected result of a graceful shutdown diff --git a/go/wrapper/errors_test.go b/go/wrapper/errors_test.go index 4cb2e38cd22..80c84dfd720 100644 --- a/go/wrapper/errors_test.go +++ b/go/wrapper/errors_test.go @@ -96,6 +96,7 @@ func TestErrorSentinels(t *testing.T) { {"NotFound", ffi.NewMoqErrorNotFound(), moq.ErrNotFound}, {"Unsupported", ffi.NewMoqErrorUnsupported(), moq.ErrUnsupported}, {"UnsupportedConfig", ffi.NewMoqErrorUnsupportedConfig("description"), moq.ErrUnsupportedConfig}, + {"OutOfRange", ffi.NewMoqErrorOutOfRange("viewer"), moq.ErrOutOfRange}, {"InvalidPattern", ffi.NewMoqErrorInvalidPattern(""), moq.ErrInvalidPattern}, {"InvalidInstance", ffi.NewMoqErrorInvalidInstance(""), moq.ErrInvalidInstance}, {"UnresolvableBroadcast", ffi.NewMoqErrorUnresolvableBroadcast(""), moq.ErrUnresolvableBroadcast}, diff --git a/go/wrapper/session.go b/go/wrapper/session.go index 06f910f851b..a266e194b01 100644 --- a/go/wrapper/session.go +++ b/go/wrapper/session.go @@ -176,6 +176,71 @@ func (r *Reservation) Update(maxBps uint64) { r.inner.Update(maxBps) } +// Viewers returns the session's viewers, dividing the connection's receive +// estimate among the broadcasts watched over it. Every call returns a handle to +// the same registry, and the session sends what its viewers' ceilings add up to +// as its PROBE target. A client handle survives reconnects: a viewer reads nil +// while disconnected and resumes on the next connection. +func (s *Session) Viewers() *Viewers { + return &Viewers{inner: s.inner.Viewers()} +} + +// Viewers divides one connection's receive estimate among the broadcasts +// watched over it, max-min fair by each viewer's ceiling. +type Viewers struct { + inner *ffi.MoqViewers +} + +// Watch claims up to maxBps for a broadcast, returning its viewer. maxBps is a +// ceiling: what the largest rendition the player would switch to needs, not what +// it is receiving. Holding the viewer requests the receive estimate, like +// Session.RecvBandwidth; Close it once the broadcast stops being watched. +// Errors with ErrOutOfRange, watching nothing, when the ceilings would sum +// above 2^53 - 1. +func (v *Viewers) Watch(maxBps uint64) (*Viewer, error) { + inner, err := v.inner.Watch(maxBps) + if err != nil { + return nil, err + } + return &Viewer{inner: inner}, nil +} + +// SetTarget sends targetBps as the PROBE target instead of the viewers' sum, or +// nil to follow them again. Zero sends no target. Errors with ErrOutOfRange, +// keeping the previous override, above 2^53 - 1. +func (v *Viewers) SetTarget(targetBps *uint64) error { + return v.inner.SetTarget(targetBps) +} + +// Viewer is one watched broadcast's standing claim on Viewers. +// +// Rate is a snapshot: nil means no receive estimate, so hold the current +// selection, and 0 is a real zero rate. +type Viewer struct { + inner *ffi.MoqViewer +} + +// Rate returns this viewer's slice of the receive estimate right now, in bits +// per second. +func (v *Viewer) Rate() *uint64 { + return v.inner.Rate() +} + +// Update changes the ceiling, keeping the same claim, as when a catalog enables +// or disables a rendition. Errors with ErrOutOfRange, keeping the previous +// ceiling, when the ceilings would sum above 2^53 - 1. +func (v *Viewer) Update(maxBps uint64) error { + return v.inner.Update(maxBps) +} + +// Close releases the claim, handing its share to the other viewers, lowering +// the PROBE target, and ending its receive-estimate demand without waiting for +// garbage collection. Call it from the goroutine that last used the viewer; +// the viewer is unusable afterwards. +func (v *Viewer) Close() { + v.inner.Destroy() +} + // RatePolicy maps a reservation's grant onto a sender's bitrate: MaxBps caps it, // and LowerBps, the next lower rendition's MaxBps, disables this rendition while // the grant is below (MaxBps + 2*LowerBps) / 3 and a session probes for it. diff --git a/js/net/api/index.api.md b/js/net/api/index.api.md index 1f88caaaaa9..68203040da6 100644 --- a/js/net/api/index.api.md +++ b/js/net/api/index.api.md @@ -72,6 +72,21 @@ export namespace Bandwidth { get rate(): Signals.Getter; update(max: number): void; } + export class Viewer implements Disposable { + [Symbol.dispose](): void; + close(): void; + peek(): number | undefined; + get rate(): Signals.Getter; + update(max: number): void; + } + export class Viewers { + constructor(estimate?: Signals.Getter); + static readonly MAX_TARGET: number; + close(): void; + setTarget(target: number | undefined): void; + readonly target: Signals.Getter; + watch(max: number): Bandwidth.Viewer; + } } export namespace Broadcast { @@ -148,6 +163,7 @@ export namespace Connection { transport?: WebTransport; url: URL; versions?: readonly string[]; + viewers?: Bandwidth.Viewers; websocket?: Connection.WebSocketProps; webtransport?: Connection.WebTransportProps; } @@ -242,6 +258,7 @@ export class Connection { readonly transport: Signals.Getter; url: Signals.Signal; versions: Signals.Signal; + readonly viewers: Signals.Getter | undefined>; } export namespace Error { diff --git a/js/net/src/bandwidth.test.ts b/js/net/src/bandwidth.test.ts index 31eecc49f2c..df068984ac2 100644 --- a/js/net/src/bandwidth.test.ts +++ b/js/net/src/bandwidth.test.ts @@ -1,7 +1,8 @@ import { expect, test } from "bun:test"; import { Signal } from "@moq/signals"; -import { Allocator, allocate, Plan, type Want } from "./bandwidth.ts"; +import { Allocator, allocate, Plan, Viewers, type Want } from "./bandwidth.ts"; import { Producer as TrackProducer } from "./track.ts"; +import { Observed } from "./util/observed.ts"; /** Priorities matching hang's, which is what the allocator sees in practice. */ const AUDIO = 80; @@ -364,3 +365,130 @@ test("reserve and update reject a non-finite or negative ceiling", () => { allocator.close(); }); + +// Several players on one connection must not each select against the whole downlink: +// the receive estimate splits max-min fair by each viewer's ceiling, and never sums above it. +test("viewers split the receive estimate max-min fair", () => { + const estimate = new Signal(6_000_000); + const viewers = new Viewers(estimate); + + const small = viewers.watch(1_000_000); + const large = viewers.watch(8_000_000); + expect(small.peek()).toBe(1_000_000); + expect(large.peek()).toBe(5_000_000); + + // Three even claims on a link too small for any of them: an even cut each, never above it. + estimate.set(2_000_000); + small.update(4_000_000); + large.update(4_000_000); + const third = viewers.watch(4_000_000); + const grants = [small.peek() ?? 0, large.peek() ?? 0, third.peek() ?? 0]; + for (const grant of grants) expect(Math.abs(grant - 666_666)).toBeLessThanOrEqual(1); + expect(grants.reduce((sum, grant) => sum + grant, 0)).toBe(2_000_000); + + // No estimate is "hold your selection", not zero. + estimate.set(undefined); + expect(small.peek()).toBeUndefined(); + + viewers.close(); +}); + +// The PROBE stream encodes at most MAX_TARGET, so a viewer, update, or override past it is +// refused and leaves the target as it was. +test("viewer targets stay encodable", () => { + const viewers = new Viewers(); + const max = Viewers.MAX_TARGET; + + expect(() => viewers.watch(max + 1)).toThrow(RangeError); + const first = viewers.watch(max - 1); + expect(() => viewers.watch(2)).toThrow(RangeError); + const second = viewers.watch(1); + expect(viewers.target.peek()).toBe(max); + + expect(() => second.update(2)).toThrow(RangeError); + expect(viewers.target.peek()).toBe(max); + first.update(1); + second.update(max - 1); + expect(viewers.target.peek()).toBe(max); + + viewers.setTarget(1_000_000); + expect(() => viewers.setTarget(max + 1)).toThrow(RangeError); + expect(viewers.target.peek()).toBe(1_000_000); + + first.close(); + second.close(); + viewers.close(); +}); + +test("the viewers' target sums their ceilings until overridden", () => { + const viewers = new Viewers(new Signal(1_000_000)); + expect(viewers.target.peek()).toBe(0); + + const first = viewers.watch(1_000_000); + const second = viewers.watch(2_000_000); + expect(viewers.target.peek()).toBe(3_000_000); + + second.update(4_000_000); + expect(viewers.target.peek()).toBe(5_000_000); + + // Zero sends no target; clearing the override follows the viewers again. + viewers.setTarget(0); + expect(viewers.target.peek()).toBe(0); + viewers.setTarget(10_000_000); + expect(viewers.target.peek()).toBe(10_000_000); + viewers.setTarget(undefined); + expect(viewers.target.peek()).toBe(5_000_000); + + first.close(); + expect(viewers.target.peek()).toBe(4_000_000); + second.close(); + expect(viewers.target.peek()).toBe(0); + + viewers.close(); +}); + +test("a closed viewers registry claims nothing", () => { + const viewers = new Viewers(new Signal(1_000_000)); + // Closing retracts an override too, and a later one is ignored. + viewers.setTarget(1_000_000); + viewers.close(); + expect(viewers.target.peek()).toBe(0); + viewers.setTarget(1_000_000); + expect(viewers.target.peek()).toBe(0); + + const viewer = viewers.watch(2_000_000); + expect(viewers.target.peek()).toBe(0); + expect(viewer.peek()).toBeUndefined(); + viewer.close(); +}); + +// Observing a connection's receive estimate is what requests PROBE, so a registry with +// nobody watching must not hold that demand. +test("an idle viewers registry does not observe the estimate", async () => { + const estimate = new Observed(1_000_000); + const viewers = new Viewers(estimate); + expect(estimate.wanted.peek()).toBe(false); + + const viewer = viewers.watch(1_000_000); + await settled(); + expect(estimate.wanted.peek()).toBe(true); + + viewer.close(); + await settled(); + expect(estimate.wanted.peek()).toBe(false); + + viewers.close(); +}); + +// Let queued signal reactions run without relying on host timers. +function settled(): Promise { + return new Promise((resolve) => { + const channel = new MessageChannel(); + channel.port1.onmessage = () => { + channel.port1.close(); + channel.port2.close(); + resolve(); + }; + channel.port2.postMessage(null); + }); +} diff --git a/js/net/src/bandwidth.ts b/js/net/src/bandwidth.ts index c679196b875..27811ff8682 100644 --- a/js/net/src/bandwidth.ts +++ b/js/net/src/bandwidth.ts @@ -5,9 +5,13 @@ * an {@link Allocator} rather than each targeting the whole thing. How a sender * then follows its share is policy and lives with the sender. * + * The receive direction mirrors it: {@link Viewers} divides the receive estimate + * among the broadcasts watched over one connection, and their ceilings summed are + * the PROBE target the connection asks its peer to probe up to. + * * @module */ -import { Effect, type Getter, Signal } from "@moq/signals"; +import { Derived, Effect, type Getter, Signal } from "@moq/signals"; import { hooks } from "./internal.ts"; import type { Demand } from "./track.ts"; @@ -135,7 +139,8 @@ export function allocate(estimate: number, wants: readonly Want[], id: number): interface Entry { id: number; - demand: Demand; + /** The track whose demand gates the claim, or undefined for a claim that is always active. */ + demand?: Demand; priority: number; max: number; rate: Signal; @@ -147,9 +152,11 @@ interface Registry { release(id: number): void; } -/** Whether `entry` claims its share from the others: its track is demanded and not released. */ function demanded(entry: Entry): boolean { - return hooks.demandReleased(entry.demand).peek() === undefined && entry.demand.wanted.peek() !== undefined; + return ( + !entry.demand || + (hooks.demandReleased(entry.demand).peek() === undefined && entry.demand.wanted.peek() !== undefined) + ); } /** A division and what it divided, so a read that finds them unchanged reuses it. */ @@ -170,8 +177,10 @@ interface Division { * needs that to know when to resume. */ function shareOf(plan: Plan, entry: Entry): number | undefined { - if (entry.demand.closed.peek() !== undefined) return undefined; - if (entry.demand.wanted.peek() === undefined) return plan.rejoin(entry); + if (entry.demand) { + if (entry.demand.closed.peek() !== undefined) return undefined; + if (entry.demand.wanted.peek() === undefined) return plan.rejoin(entry); + } return plan.grant(entry.id); } @@ -182,53 +191,25 @@ function ceiling(max: number): number { return max; } -/** - * A non-owning handle on an allocator: reserve a slice, without its lifecycle. - * - * What a shared connection lends out. {@link Allocator} implements it, so code - * that is handed an allocator rather than owning one should accept this type: - * closing the registry stays the owner's alone, and a borrower cannot express it. - * - * @public - */ -export interface Handle { - /** Reserve up to `max` for `track`; see {@link Allocator.reserve}. */ - reserve(track: Demand, max: number): Reservation; +/** The ceilings summed in order, the way {@link Viewers.target} sums them. */ +function total(entries: readonly { max: number }[]): number { + let sum = 0; + for (const entry of entries) sum += entry.max; + return sum; } -// Assigned by Allocator's static block, which runs before any instance exists. -let reservedOf: (allocator: Allocator) => Getter; - /** - * Whether `allocator` holds a reservation that reads the estimate. - * - * The estimate's source can stop sampling while this is false: nothing reads it. - * - * @internal + * The registry behind {@link Allocator} and {@link Viewers}: divides one estimate + * among its claims, publishing each claim's slice. */ -export function reserved(allocator: Allocator): Getter { - return reservedOf(allocator); -} - -/** - * Divides one connection's bandwidth estimate among the tracks sharing it. - * - * Every sender on a connection reads the same estimate, so N senders each - * targeting all of it oversubscribe the uplink N times over. Register a track - * here and it gets a {@link Reservation} reporting only its own slice, so the - * slices sum to the estimate instead of each matching it. - * - * Advisory, not enforced. A track that ignores its slice, or can't follow it at - * all (PCM audio has a fixed bitrate), still sends what it sends; the transport - * sheds the excess by dropping groups. - * - * Hand the same instance to every sender on the connection. - */ -export class Allocator implements Handle { +class Divider { #estimate: Getter | undefined; - #entries = new Signal([]); + /** The most the ceilings may sum to, or `undefined` for no limit. */ + #limit: number | undefined; + readonly entries = new Signal([]); + /** Whether a live claim reads the estimate; see {@link reserved}. */ + readonly reserved = new Signal(false); #alive = new Signal(true); - #reserved = new Signal(false); #nextId = 0; #signals = new Effect(); #registry: Registry; @@ -236,14 +217,9 @@ export class Allocator implements Handle { #version = 0; #division: Division | undefined; - /** - * Divide `estimate`, normally a connection's sampled send rate. - * - * Omit it (or call {@link unlimited}) for nothing to divide: every reservation - * reports `undefined`, which already means "no opinion, hold your rate". - */ - constructor(estimate?: Getter) { + constructor(estimate?: Getter, limit?: number) { this.#estimate = estimate; + this.#limit = limit; this.#registry = { peek: (id) => this.#peek(id), @@ -253,106 +229,75 @@ export class Allocator implements Handle { this.#signals.run((effect) => { if (!effect.get(this.#alive)) return; - if (this.#estimate) effect.get(this.#estimate); - const entries = effect.get(this.#entries); + const entries = effect.get(this.entries); let reserved = false; for (const entry of entries) { + // A claim without a demand always reads its slice. + if (!entry.demand) { + reserved = true; + continue; + } effect.get(entry.demand.wanted); effect.get(hooks.demandReleased(entry.demand)); // The same test shareOf applies: a closed demand reads no slice. if (effect.get(entry.demand.closed) === undefined) reserved = true; } - this.#reserved.set(reserved); + this.reserved.set(reserved); + // Observe the estimate only while something claims it: reading a session's + // receive estimate is what requests PROBE, so an empty registry asks for nothing. + if (entries.length === 0) return; + if (this.#estimate) effect.get(this.#estimate); this.#publish(); }); } - static { - reservedOf = (allocator) => allocator.#reserved; - } - - /** - * An allocator with nothing to divide, so every reservation reports `undefined`. - * - * `undefined` already means "no opinion, hold your rate" to a sender, so this is - * what a transport with no congestion estimate, a local file, or a test harness - * wants. - */ - static unlimited(): Allocator { - return new Allocator(); - } - - /** - * Reserve up to `max` for `track`, returning the reservation. - * - * `max` is a ceiling, not a measurement: reserve the most the track can ever - * send, not what it happens to be sending. A VBR encoder sitting on a black - * screen at 1 Mbps can jump to 6 Mbps between one frame and the next, and a - * reservation that had followed it down would have already handed that room - * to somebody else. - * - * Priority comes from the track's `Info.priority` (higher served first). A tier is filled to - * its reservations before the next one sees a bit; within a tier the split is - * max-min fair. - * - * The reservation lasts until {@link Reservation.close}: hold it for as long - * as the sender is publishing, change the ceiling with - * {@link Reservation.update}, and close it to hand the room back. - * - * {@link Reservation.peek} / {@link Reservation.rate} report `undefined` - * while the connection has no estimate, telling a sender to hold its current - * rate rather than encode at zero. While nothing is subscribed to the track they - * report the slice the track would get back, without claiming it from the others. - */ - reserve(track: Demand, max: number): Reservation { + /** Claim up to `max`, active whenever `demand` is, or always without one. */ + claim(demand: Demand | undefined, priority: number, max: number): Reservation { max = ceiling(max); this.#prune(); + if (this.#limit !== undefined && this.#alive.peek()) this.#fits([...this.entries.peek(), { max }]); + const id = this.#nextId++; const rate = new Signal(undefined); - this.#mutate((entries) => { - entries.push({ - id, - demand: track, - priority: hooks.demandPriority(track), - max, - rate, + // A closed registry hands back an inert reservation, so its target stays zero. + if (this.#alive.peek()) { + this.#mutate((entries) => { + entries.push({ id, demand, priority, max, rate }); }); - }); + } const reservation = makeReservation(this.#registry, id, rate); this.#publish(); return reservation; } - /** - * Stop dividing. Existing reservations report `undefined` and further - * {@link reserve} calls still return a handle that never claims. - */ close(): void { if (!this.#alive.peek()) return; this.#alive.set(false); - this.#reserved.set(false); - for (const entry of this.#entries.peek()) { + this.reserved.set(false); + for (const entry of this.entries.peek()) { entry.rate.set(undefined); } - this.#entries.set([]); + this.entries.set([]); this.#division = undefined; this.#signals.close(); } #prune(): void { - const entries = this.#entries.peek(); - const live = entries.filter((entry) => hooks.demandReleased(entry.demand).peek() === undefined); + const entries = this.entries.peek(); + const live = entries.filter( + (entry) => !entry.demand || hooks.demandReleased(entry.demand).peek() === undefined, + ); if (live.length !== entries.length) { this.#version++; - this.#entries.set(live); + this.entries.set(live); } } #mutate(fn: (entries: Entry[]) => void): void { this.#version++; - this.#entries.mutate(fn); + this.entries.mutate(fn); } /** The division of `estimate` among `entries`, divided again only when either moved. */ @@ -377,8 +322,7 @@ export class Allocator implements Handle { #publish(): void { if (!this.#alive.peek()) return; const estimate = this.#estimate?.peek(); - const entries = this.#entries.peek(); - // Divided once for every reservation rather than once per reservation. + const entries = this.entries.peek(); const plan = estimate == null ? undefined : this.#plan(estimate, entries); for (const entry of entries) { entry.rate.set(plan && shareOf(plan, entry)); @@ -389,15 +333,26 @@ export class Allocator implements Handle { if (!this.#alive.peek()) return undefined; const estimate = this.#estimate?.peek(); if (estimate == null) return undefined; - const entries = this.#entries.peek(); + const entries = this.entries.peek(); const entry = entries.find((candidate) => candidate.id === id); if (!entry) return undefined; return shareOf(this.#plan(estimate, entries), entry); } + /** Throw when `entries`' ceilings sum above the limit. */ + #fits(entries: readonly { max: number }[]): void { + const sum = total(entries); + if (sum > (this.#limit ?? Number.POSITIVE_INFINITY)) { + throw new RangeError(`ceilings sum to ${sum}, above the limit of ${this.#limit}`); + } + } + #update(id: number, max: number): void { if (!this.#alive.peek()) return; max = ceiling(max); + if (this.#limit !== undefined) { + this.#fits(this.entries.peek().map((entry) => (entry.id === id ? { max } : entry))); + } this.#mutate((entries) => { const entry = entries.find((candidate) => candidate.id === id); if (entry) entry.max = max; @@ -415,6 +370,248 @@ export class Allocator implements Handle { } } +/** + * A non-owning handle on an allocator: reserve a slice, without its lifecycle. + * + * What a shared connection lends out. {@link Allocator} implements it, so code + * that is handed an allocator rather than owning one should accept this type: + * closing the registry stays the owner's alone, and a borrower cannot express it. + * + * @public + */ +export interface Handle { + /** Reserve up to `max` for `track`; see {@link Allocator.reserve}. */ + reserve(track: Demand, max: number): Reservation; +} + +// Assigned by Allocator's static block, which runs before any instance exists. +let reservedOf: (allocator: Allocator) => Getter; + +/** + * Whether `allocator` holds a reservation that reads the estimate. + * + * The estimate's source can stop sampling while this is false: nothing reads it. + * + * @internal + */ +export function reserved(allocator: Allocator): Getter { + return reservedOf(allocator); +} + +/** + * Divides one connection's bandwidth estimate among the tracks sharing it. + * + * Every sender on a connection reads the same estimate, so N senders each + * targeting all of it oversubscribe the uplink N times over. Register a track + * here and it gets a {@link Reservation} reporting only its own slice, so the + * slices sum to the estimate instead of each matching it. + * + * Advisory, not enforced. A track that ignores its slice, or can't follow it at + * all (PCM audio has a fixed bitrate), still sends what it sends; the transport + * sheds the excess by dropping groups. + * + * Hand the same instance to every sender on the connection. + */ +export class Allocator implements Handle { + #divider: Divider; + + /** + * Divide `estimate`, normally a connection's sampled send rate. + * + * Omit it (or call {@link unlimited}) for nothing to divide: every reservation + * reports `undefined`, which already means "no opinion, hold your rate". + */ + constructor(estimate?: Getter) { + this.#divider = new Divider(estimate); + } + + static { + reservedOf = (allocator) => allocator.#divider.reserved; + } + + /** + * An allocator with nothing to divide, so every reservation reports `undefined`. + * + * `undefined` already means "no opinion, hold your rate" to a sender, so this is + * what a transport with no congestion estimate, a local file, or a test harness + * wants. + */ + static unlimited(): Allocator { + return new Allocator(); + } + + /** + * Reserve up to `max` for `track`, returning the reservation. + * + * `max` is a ceiling, not a measurement: reserve the most the track can ever + * send, not what it happens to be sending. A VBR encoder sitting on a black + * screen at 1 Mbps can jump to 6 Mbps between one frame and the next, and a + * reservation that had followed it down would have already handed that room + * to somebody else. + * + * Priority comes from the track's `Info.priority` (higher served first). A tier is filled to + * its reservations before the next one sees a bit; within a tier the split is + * max-min fair. + * + * The reservation lasts until {@link Reservation.close}: hold it for as long + * as the sender is publishing, change the ceiling with + * {@link Reservation.update}, and close it to hand the room back. + * + * {@link Reservation.peek} / {@link Reservation.rate} report `undefined` + * while the connection has no estimate, telling a sender to hold its current + * rate rather than encode at zero. While nothing is subscribed to the track they + * report the slice the track would get back, without claiming it from the others. + */ + reserve(track: Demand, max: number): Reservation { + return this.#divider.claim(track, hooks.demandPriority(track), max); + } + + /** + * Stop dividing. Existing reservations report `undefined` and further + * {@link reserve} calls still return a handle that never claims. + */ + close(): void { + this.#divider.close(); + } +} + +/** + * Divides one connection's receive estimate among the broadcasts watched over it. + * + * The receive-side mirror of {@link Allocator}. Every player on a connection reads the + * same receive estimate, so N players each selecting against all of it oversubscribe + * the downlink N times over. {@link watch} a broadcast here and its {@link Viewer} + * reports only its own slice, split max-min fair by each viewer's ceiling, so the + * slices sum to the estimate instead of each matching it. Viewers carry no priority: + * a viewer asking for less than an even cut takes all it asked for and leaves the + * rest to the others. + * + * The viewers' ceilings summed are also the PROBE target the connection sends its + * peer, which probes up to it when it advertised `Increase`, so the estimate can rise + * to fund a larger rendition. The target never leaves this hop. + * + * The estimate is observed only while a viewer is live, since observing a + * connection's receive estimate is what requests PROBE. + */ +export class Viewers { + /** + * The largest PROBE target: the most the viewers' ceilings, summed, or an override may be. + * + * `Number.MAX_SAFE_INTEGER` bits per second, the largest integer the PROBE stream encodes. + */ + static readonly MAX_TARGET = Number.MAX_SAFE_INTEGER; + + #divider: Divider; + #override = new Signal(undefined); + #closed = false; + + /** + * The PROBE target: the live viewers' ceilings summed, or the {@link setTarget} override. + * Zero sends no target. + */ + readonly target: Getter; + + /** Divide `estimate`, normally a connection's receive estimate from PROBE. */ + constructor(estimate?: Getter) { + this.#divider = new Divider(estimate, Viewers.MAX_TARGET); + this.target = new Derived([this.#divider.entries, this.#override], (entries, override) => + override !== undefined ? override : total(entries), + ); + } + + /** + * Watch a broadcast receiving at most `max` bits per second, returning its viewer. + * + * `max` is a ceiling: what the largest rendition the player would switch to needs, + * not what it happens to be receiving. The claim lasts until {@link Viewer.close}: + * change the ceiling with {@link Viewer.update}, and close it once the broadcast + * stops being watched. + * + * @throws {RangeError} watching nothing, when the ceilings would sum above {@link Viewers.MAX_TARGET}. + */ + watch(max: number): Viewer { + return makeViewer(this.#divider.claim(undefined, 0, max)); + } + + /** + * Send `target` as the PROBE target instead of the viewers' sum, or `undefined` to follow them again. + * + * `0` sends no target, so the peer stops probing for these viewers. + * + * @throws {RangeError} keeping the previous override, for a target above {@link Viewers.MAX_TARGET}. + */ + setTarget(target: number | undefined): void { + if (this.#closed) return; + if (target !== undefined && ceiling(target) > Viewers.MAX_TARGET) { + throw new RangeError(`PROBE target ${target} is above the limit of ${Viewers.MAX_TARGET}`); + } + this.#override.set(target); + } + + /** + * Stop dividing. Existing viewers report `undefined` and release their claims, and the + * target drops to zero for good, override included. + */ + close(): void { + this.#closed = true; + this.#override.set(undefined); + this.#divider.close(); + } +} + +let makeViewer: (reservation: Reservation) => Viewer; + +/** + * One watched broadcast's standing claim on {@link Viewers}, held for as long as it is watched. + * + * Close it to release the claim and lower the PROBE target. + */ +export class Viewer implements Disposable { + readonly #reservation: Reservation; + + private constructor(reservation: Reservation) { + this.#reservation = reservation; + } + + static { + makeViewer = (reservation) => new Viewer(reservation); + } + + /** This viewer's slice of the receive estimate right now; see {@link Reservation.peek}. */ + peek(): number | undefined { + return this.#reservation.peek(); + } + + /** + * This viewer's current slice of the receive estimate. + * + * `undefined` while the connection has no receive estimate or this viewer has been + * closed, telling a player to hold its current selection. + */ + get rate(): Getter { + return this.#reservation.rate; + } + + /** + * Change the ceiling, keeping the same claim, as when a catalog enables or disables a rendition. + * + * @throws {RangeError} keeping the previous ceiling, when the ceilings would sum above {@link Viewers.MAX_TARGET}. + */ + update(max: number): void { + this.#reservation.update(max); + } + + /** Release the claim so other viewers take the room. Idempotent. */ + close(): void { + this.#reservation.close(); + } + + /** Calls {@link close}, so `using` releases the claim. */ + [Symbol.dispose](): void { + this.close(); + } +} + let makeReservation: (registry: Registry, id: number, rate: Signal) => Reservation; /** diff --git a/js/net/src/bandwidth_api.ts b/js/net/src/bandwidth_api.ts index 7fc5892eab9..76e3316d3d0 100644 --- a/js/net/src/bandwidth_api.ts +++ b/js/net/src/bandwidth_api.ts @@ -3,4 +3,4 @@ * * @module */ -export { Allocator, type Handle, Reservation } from "./bandwidth.ts"; +export { Allocator, type Handle, Reservation, Viewer, Viewers } from "./bandwidth.ts"; diff --git a/js/net/src/connection/connect.ts b/js/net/src/connection/connect.ts index 824c0140e4d..92a7ea881c6 100644 --- a/js/net/src/connection/connect.ts +++ b/js/net/src/connection/connect.ts @@ -1,8 +1,9 @@ import { Elapsed, Milli, Nano, sleep, timeout } from "@moq/clock"; import Session, { type Version as QmuxVersion } from "@moq/qmux"; -import { race } from "@moq/signals"; +import { type Getter, race } from "@moq/signals"; import type * as Auth from "../auth.ts"; import { vacant } from "../auth_session.ts"; +import type { Viewers } from "../bandwidth.ts"; import { ConnectTimeout, error, fromClose, ProtocolViolation, sessionCause } from "../error.ts"; import * as Ietf from "../ietf/index.ts"; import { IMPLEMENTATION } from "../implementation.ts"; @@ -253,6 +254,13 @@ export interface ConnectProps { */ implementation?: string; + /** + * The viewers whose ceilings summed the session sends as its PROBE target, so a peer + * that advertised `Increase` probes the connection up to it (moq-lite-05+). Omit to send + * no target. The registry is borrowed, so the same one can span reconnects. + */ + viewers?: Viewers; + /** * Maximum time for one connect, covering the dial and the MoQ handshake, which has no * deadline of its own (default: 30000ms). `0` waits forever. Past it, the connect rejects @@ -281,6 +289,8 @@ type SessionProps = { token?: Uint8Array; /** The implementation this side advertises in SETUP; empty sends nothing. */ implementation: string; + /** The PROBE target to send a peer that advertised `Increase`. */ + probeTarget?: Getter; }; /** @@ -383,6 +393,7 @@ async function connectInner( extensions: Extensions.offered(props.extensions), token: presented.setup === undefined ? undefined : new TextEncoder().encode(presented.setup), implementation: props.implementation ?? IMPLEMENTATION, + probeTarget: props.viewers?.target, }); if (props.transport) { diff --git a/js/net/src/connection/pool.ts b/js/net/src/connection/pool.ts index 6e0d499a16d..795af807a51 100644 --- a/js/net/src/connection/pool.ts +++ b/js/net/src/connection/pool.ts @@ -9,7 +9,7 @@ import { Effect, type GetPromise, type Getter, Once, Signal } from "@moq/signals import type * as Announce from "../announce.ts"; import { Producer as AnnounceProducer } from "../announced.ts"; import type * as Auth from "../auth.ts"; -import type { Handle } from "../bandwidth.ts"; +import type { Handle, Viewers } from "../bandwidth.ts"; import * as Origin from "../origin.ts"; import * as Path from "../path.ts"; import { closeUnwanted } from "../util/announce.ts"; @@ -186,6 +186,15 @@ export class Connection { */ readonly allocator: Getter; + /** + * The receive-side registry for the current URL, or undefined while disabled or URL-less. + * + * Every handle on this URL shares the same instance, so players watching over one + * connection split its receive estimate instead of each selecting against all of it, + * and their ceilings summed are the PROBE target. Borrowed, not owned: it has no close. + */ + readonly viewers: Getter | undefined>; + /** * The origin for the current URL, or undefined while disabled or URL-less. * @@ -222,6 +231,7 @@ export class Connection { readonly #probe = new Signal | undefined>(undefined); readonly #origin = new Signal(undefined); readonly #allocator = new Signal(undefined); + readonly #viewers = new Signal | undefined>(undefined); readonly #auth = new Signal(undefined); readonly #error = new Signal(undefined); #signals: Effect; @@ -252,6 +262,7 @@ export class Connection { this.probe = new Follow(this.#probe); this.origin = this.#origin; this.allocator = this.#allocator; + this.viewers = this.#viewers; this.auth = this.#auth; this.transport = this.#signals.computed((effect) => effect.get(this.#established)?.transport); @@ -279,6 +290,7 @@ export class Connection { effect.set(this.#origin, lease.origin, undefined); effect.set(this.#allocator, lease.connection.allocator, undefined); + effect.set(this.#viewers, lease.connection.viewers, undefined); effect.set(this.#auth, lease.connection.auth, undefined); // Proxy the shared loop's outputs, so this handle reads like its own connection. @@ -330,6 +342,7 @@ export class Connection { if (!effect.get(this.enabled) || !effect.get(href)) return; effect.set(this.#origin, origin, undefined); effect.set(this.#allocator, loop.allocator, undefined); + effect.set(this.#viewers, loop.viewers, undefined); effect.set(this.#auth, loop.auth, undefined); }); signals.run((effect) => effect.set(this.#status, effect.get(loop.status), "disconnected")); diff --git a/js/net/src/connection/reload.test.ts b/js/net/src/connection/reload.test.ts index 5adcd6e91c8..5d79d593eec 100644 --- a/js/net/src/connection/reload.test.ts +++ b/js/net/src/connection/reload.test.ts @@ -2,6 +2,7 @@ import { expect, spyOn, test } from "bun:test"; import { Instant, Manual, Milli, Nano, now, sleep, yieldNow } from "@moq/clock"; import { Effect, Signal } from "@moq/signals"; import * as Announce from "../announced.ts"; +import { Viewers } from "../bandwidth.ts"; import type { Producer as BroadcastProducer } from "../broadcast.ts"; import { ConnectTimeout, SessionCode, SessionError, StreamCode, toTransport } from "../error.ts"; import { Route } from "../hop.ts"; @@ -87,6 +88,14 @@ test("ReloadProps excludes transport", () => { expect(props.enabled).toBeUndefined(); }); +test("ReloadProps excludes viewers", () => { + const withViewers = { viewers: new Viewers() }; + // @ts-expect-error a reload owns its viewers registry + const props: ReloadProps = withViewers; + expect(props.enabled).toBeUndefined(); + withViewers.viewers.close(); +}); + test("closing mid-connect aborts the pending attempt", async () => { const original = globalThis.WebTransport; let closes = 0; diff --git a/js/net/src/connection/reload.ts b/js/net/src/connection/reload.ts index 5f54d89f33c..db9ed20d714 100644 --- a/js/net/src/connection/reload.ts +++ b/js/net/src/connection/reload.ts @@ -1,9 +1,9 @@ import { Instant, Milli, Nano, now, sleep } from "@moq/clock"; -import { Effect, type GetPromise, type Getter, Once, Signal } from "@moq/signals"; +import { Derived, Effect, type GetPromise, type Getter, Once, Signal } from "@moq/signals"; import type * as Announce from "../announced.ts"; import { Handle as AuthHandle } from "../auth.ts"; import { ended } from "../auth_session.ts"; -import { Allocator, reserved } from "../bandwidth.ts"; +import { Allocator, reserved, Viewers } from "../bandwidth.ts"; import { error, reason, SessionCode, SessionError } from "../error.ts"; import type { Consumer as OriginConsumer, Producer as OriginProducer } from "../origin.ts"; import * as Path from "../path.ts"; @@ -83,7 +83,7 @@ export type ReloadDelay = { */ export type ReloadProps = Omit< ConnectProps, - "url" | "signal" | "transport" | "implementation" | "extensions" | "tokens" + "url" | "signal" | "transport" | "implementation" | "extensions" | "tokens" | "viewers" > & { /** See {@link ConnectProps.tokens}; pass a `Signal` to replace them before they expire. */ tokens?: readonly string[] | Signal; @@ -94,6 +94,9 @@ export type ReloadProps = Omit< /** A one-shot transport cannot be reused by the reconnect loop. */ transport?: never; + /** A reload owns its {@link Reload.viewers}, fed by its own sessions' estimates. */ + viewers?: never; + /** Whether to reload the connection when it disconnects (default: true). */ enabled?: boolean | Signal; @@ -227,6 +230,15 @@ export class Reload { */ readonly allocator: Allocator; + /** + * Divides this connection's receive estimate among the broadcasts watched over it. + * + * The same instance across reconnects, so viewers survive a drop, and every session + * the loop dials sends their ceilings summed as its PROBE target. A live viewer + * requests PROBE; viewers report `undefined` while disconnected. + */ + readonly viewers: Viewers; + /** * The auth handle every session of the loop is built on, spanning reconnects. * @@ -412,6 +424,11 @@ export class Reload { this.allocator = new Allocator(this.#estimate); this.#signals.cleanup(() => this.allocator.close()); + // Lazy: the registry observes the estimate only while a viewer is live, and only + // that observation requests PROBE from the current session. + this.viewers = new Viewers(new Derived([this.probe], (probe) => probe?.estimatedRecvRate)); + this.#signals.cleanup(() => this.viewers.close()); + // The transport has no event for the send-rate estimate, so sample on our // own schedule and skip a tick while the previous snapshot is outstanding. // Only while a reservation reads it: a receive-only or lingering connection @@ -551,6 +568,7 @@ export class Reload { publish: this.publish, consume: this.consume, auth: this.auth, + viewers: this.viewers, signal, }); } finally { diff --git a/js/net/src/lite/connection.ts b/js/net/src/lite/connection.ts index cde3e63081c..a1ca4405692 100644 --- a/js/net/src/lite/connection.ts +++ b/js/net/src/lite/connection.ts @@ -71,6 +71,8 @@ export interface ConnectionProps { token?: Uint8Array; /** The implementation our SETUP advertises (lite-05+). Defaults to {@link IMPLEMENTATION}; empty sends nothing. */ implementation?: string; + /** The PROBE target to send a peer that advertised `Increase`, in bits per second; zero sends none. */ + probeTarget?: Getter; } /** @@ -136,6 +138,8 @@ export class Connection implements Established { #token?: Uint8Array; // What our SETUP advertises; see {@link ConnectionProps.implementation}. #implementation: string; + // See {@link ConnectionProps.probeTarget}. + #probeTarget?: Getter; #peerImplementation = Promise.withResolvers(); /** The implementation the peer advertised; see {@link Established.peerImplementation}. */ @@ -172,6 +176,7 @@ export class Connection implements Established { client = true, token, implementation = IMPLEMENTATION, + probeTarget, }: ConnectionProps) { this.url = url; // Older versions carry the credential in the URL instead. @@ -229,6 +234,7 @@ export class Connection implements Established { ); this.#client = client; this.#implementation = implementation; + this.#probeTarget = probeTarget; // Only the lite-05+ Setup Stream carries it. if (!hasSetupStream(version)) this.#peerImplementation.resolve(undefined); registerWire(this, { @@ -295,7 +301,7 @@ export class Connection implements Established { const probes = new Effect((effect) => { if (!effect.get(this.#probe.wanted)) return; - effect.spawn(() => this.#subscriber.runProbe(effect.abort)); + effect.spawn(() => this.#subscriber.runProbe(effect.abort, this.#probeTarget)); }); // Fail loud on a publication our grant never covers, once the peer has answered the diff --git a/js/net/src/lite/subscriber.test.ts b/js/net/src/lite/subscriber.test.ts index 962e19cdb55..839354147c8 100644 --- a/js/net/src/lite/subscriber.test.ts +++ b/js/net/src/lite/subscriber.test.ts @@ -3,6 +3,7 @@ import { Elapsed, Manual, Milli, Nano, timeout, yieldNow } from "@moq/clock"; import { type Getter, Signal } from "@moq/signals"; import type { Grant } from "../auth.ts"; import type { AuthSession } from "../auth_session.ts"; +import { Viewers } from "../bandwidth.ts"; import type { Probe as ProbeStats } from "../connection/stats.ts"; import { error, @@ -31,6 +32,7 @@ import { type AnnounceBroadcast, AnnounceInit, AnnounceOk, encodeAnnounceBroadca import { Datagram as DatagramMessage } from "./datagram.ts"; import { Group } from "./group.ts"; import { Probe } from "./probe.ts"; +import { ProbeLevel, Setup } from "./setup.ts"; import { StreamId } from "./stream.ts"; import { encodeSubscribeResponse, @@ -3014,6 +3016,142 @@ test.each(["answer", "credit"] as const)("FETCH shares the TRACK deadline while } }); +/** + * A PROBE stream to a peer whose SETUP advertised `level`: `sent` reads back what the + * subscriber wrote, and `finish` plays the peer's FIN. + */ +function probeTargetHarness(level: ProbeLevel, options?: { failTarget?: boolean; stallTarget?: boolean }) { + const version = Version.DRAFT_06; + let written!: ReadableStreamDefaultController; + const sent = new Reader( + new ReadableStream({ start: (controller) => (written = controller) }), + undefined, + version, + ); + let inbound!: ReadableStreamDefaultController; + let writes = 0; + let stall!: () => void; + const stalled = new Promise((resolve) => (stall = resolve)); + let reset!: (reason: unknown) => void; + const aborted = new Promise((resolve) => (reset = resolve)); + const quic = { + createBidirectionalStream: async () => ({ + readable: new ReadableStream({ start: (controller) => (inbound = controller) }), + writable: new WritableStream({ + write: async (chunk, controller) => { + // Only the stream type precedes the first target. + if (writes++ > 0) { + if (options?.failTarget) throw new Error("write failed"); + // A peer that never drains the stream: only a reset ends the write. + if (options?.stallTarget) { + stall(); + await new Promise((_, reject) => { + controller.signal.addEventListener("abort", () => { + reset(controller.signal.reason); + reject(controller.signal.reason); + }); + }); + } + } + written.enqueue(new Uint8Array(chunk)); + }, + close: () => written.close(), + }), + }), + } as unknown as WebTransport; + const peerSetup = new Signal(new Setup({ probe: level })); + const subscriber = new Subscriber(quic, version, HopSchema.parse(1n), new Signal({}), peerSetup); + return { + subscriber, + sent, + version, + stalled, + aborted, + finish: () => inbound.close(), + }; +} + +// The viewers' sum reaches the peer as its PROBE target: only once nonzero, on every change, +// and retracted with a zero, while an opt-out sends nothing at all. +test("the PROBE stream sends the viewers' target to an Increase peer", async () => { + const { subscriber, sent, version, finish } = probeTargetHarness(ProbeLevel.Increase); + const viewers = new Viewers(); + viewers.setTarget(0); + const running = subscriber.runProbe(undefined, viewers.target); + expect(await sent.u53()).toBe(StreamId.Probe); + + // Opted out: a viewer moves nothing onto the wire until the override clears. + const first = viewers.watch(1_000_000); + viewers.setTarget(undefined); + expect((await Probe.decode(sent, version)).bitrate).toBe(1_000_000); + + const second = viewers.watch(2_000_000); + expect((await Probe.decode(sent, version)).bitrate).toBe(3_000_000); + + first.close(); + expect((await Probe.decode(sent, version)).bitrate).toBe(2_000_000); + + // Dropping to zero retracts the target as unknown on the wire. + second.close(); + expect((await Probe.decode(sent, version)).bitrate).toBeUndefined(); + + finish(); + await running; + expect(await sent.done()).toBe(true); + subscriber.close(); + viewers.close(); +}); + +// The writer and reader are independent: a failed target write ends the probe even while +// the peer keeps its side open. +test("a failed PROBE target write ends the probe", async () => { + const { subscriber, sent } = probeTargetHarness(ProbeLevel.Increase, { failTarget: true }); + const viewers = new Viewers(); + const viewer = viewers.watch(1_000_000); + const running = subscriber.runProbe(undefined, viewers.target); + expect(await sent.u53()).toBe(StreamId.Probe); + + await running; + viewer.close(); + subscriber.close(); + viewers.close(); +}); + +// Ending the probe resets a stream whose target write the peer never drained, rather than +// queueing a close behind that write and holding the stream open. +test("ending the probe resets a stalled PROBE target write", async () => { + const { subscriber, sent, stalled, aborted } = probeTargetHarness(ProbeLevel.Increase, { stallTarget: true }); + const viewers = new Viewers(); + const viewer = viewers.watch(1_000_000); + const stop = new AbortController(); + const running = subscriber.runProbe(stop.signal, viewers.target); + expect(await sent.u53()).toBe(StreamId.Probe); + await stalled; + + stop.abort(); + await running; + expect(await aborted).toBeDefined(); + viewer.close(); + subscriber.close(); + viewers.close(); +}); + +// A Report-level peer only measures, so it is never sent a target to ignore. +test("the PROBE stream sends no target to a Report peer", async () => { + const { subscriber, sent, finish } = probeTargetHarness(ProbeLevel.Report); + const viewers = new Viewers(); + const viewer = viewers.watch(1_000_000); + const running = subscriber.runProbe(undefined, viewers.target); + expect(await sent.u53()).toBe(StreamId.Probe); + + finish(); + await running; + expect(await sent.done()).toBe(true); + viewer.close(); + subscriber.close(); + viewers.close(); +}); + // Announce streams overlapping at a path share the instance minted for it, but a replacement // delivered on both, interleaved, is a new stream on each: holder counts alone would hand it // the old instance, splicing the two. diff --git a/js/net/src/lite/subscriber.ts b/js/net/src/lite/subscriber.ts index 60df226dece..15658cc6f19 100644 --- a/js/net/src/lite/subscriber.ts +++ b/js/net/src/lite/subscriber.ts @@ -2164,7 +2164,7 @@ export class Subscriber { return setup.probe; } - async runProbe(signal?: AbortSignal): Promise { + async runProbe(signal?: AbortSignal, target?: Getter): Promise { if (!this.#probe) return; if (this.version === Version.DRAFT_01 || this.version === Version.DRAFT_02) return; const scope = new Effect(); @@ -2177,9 +2177,12 @@ export class Subscriber { // input ends the session. Drop the estimates so consumers know they're stale. try { // Lite-05+ gates PROBE on the peer advertising Probe >= Report in its SETUP. + // Only a peer that probes up to a target is sent one; a Report-level peer ignores it. + let increase = false; if (hasSetupStream(this.version) && this.#peerSetup) { const level = await this.#peerProbeLevel(this.#peerSetup, scope); if (level === undefined || level < ProbeLevel.Report) return; + increase = level >= ProbeLevel.Increase; } if (this.#goingAway() || abort.aborted) return; const opening = Stream.open(this.#quic, { version: this.version }); @@ -2191,6 +2194,7 @@ export class Subscriber { } scope.cleanup(() => stream.close()); await scope.race(stream.writer.u53(StreamId.Probe)); + if (target && increase) this.#sendTarget(stream, target, scope); for (;;) { const probe = await scope.race(Probe.decodeMaybe(stream.reader, this.version)); if (!probe) break; @@ -2215,6 +2219,43 @@ export class Subscriber { } } + // Send `target` on the PROBE stream whenever it changes, in order, while `scope` lives. + // Nothing is sent while it is zero, until it retracts a target already sent. One write is + // in flight at a time, and the next sends the latest target, so a peer that stops reading + // holds one target however often it changes. + #sendTarget(stream: Stream, target: Getter, scope: Effect): void { + let sent = 0; + let writing = false; + const write = async () => { + writing = true; + try { + for (;;) { + // The wire carries whole bits per second. + const next = Math.floor(target.peek()); + if (next === sent) return; + sent = next; + // Zero reads as unknown on the wire, which retracts the last target. + await new Probe({ bitrate: next > 0 ? next : undefined }).encode(stream.writer, this.version); + } + } catch { + // The writer and reader are independent, so a failed write does not end the + // reads: end the probe here, which also closes the stream. + scope.close(); + } finally { + writing = false; + } + }; + scope.run((effect) => { + effect.get(target); + if (!writing) void write(); + }); + // A close queues behind a write the peer is not reading, which would hold the stream + // open past the probe; a reset rejects that write and frees the stream. + scope.cleanup(() => { + if (writing) stream.abort(new StreamError(StreamCode.Cancel, { message: "probe ended" })); + }); + } + /** * Wait until every subscribe stream's responses are read to its FIN or reset. Bounded only * once the transport is closed, so that its reads end. diff --git a/js/net/src/util/observed.test.ts b/js/net/src/util/observed.test.ts index 8dcad772018..71cce5837dd 100644 --- a/js/net/src/util/observed.test.ts +++ b/js/net/src/util/observed.test.ts @@ -1,5 +1,5 @@ import { expect, test } from "bun:test"; -import { Effect, type Getter, Signal } from "@moq/signals"; +import { Derived, Effect, type Getter, Signal } from "@moq/signals"; import { Follow, Observed } from "./observed"; const flush = async () => { @@ -36,6 +36,28 @@ test("reactive one-shot observers preserve demand across a value update", async stop(); }); +// A reload's viewers read the session's PROBE estimate through a Follow and a Derived; a +// gap in demand there would close and reopen the PROBE stream on every report. +test("a reactive reader through a Derived preserves demand across a value update", async () => { + const value = new Observed(1); + const demand: boolean[] = []; + const stop = value.wanted.subscribe((wanted) => demand.push(wanted)); + const derived = new Derived([new Follow(new Signal | undefined>(value))], (value) => + value === undefined ? undefined : value * 2, + ); + const effect = new Effect((effect) => { + effect.get(derived); + }); + await flush(); + value.set(2); + await flush(); + expect(demand).toEqual([true]); + effect.close(); + await flush(); + expect(demand).toEqual([true, false]); + stop(); +}); + test("forwarded demand switches sources and releases its old source", async () => { const first = new Observed(1); const second = new Observed(2); diff --git a/js/signals/src/index.ts b/js/signals/src/index.ts index dce31400c80..1eb72ecacf6 100644 --- a/js/signals/src/index.ts +++ b/js/signals/src/index.ts @@ -1271,11 +1271,23 @@ export class Derived[], T> implements G // Calls `fn` with the derived value the first time it changes, then unsubscribes. #once(fn: Subscriber): Dispose { + let active = true; const dispose = this.subscribe((value) => { - dispose(); - fn(value); + if (!active) return; + active = false; + // Call `fn` before letting go of the sources: a reactive reader schedules its next + // run there, so its replacement subscription coalesces away the gap a source that + // counts its listeners (such as demand for an estimate) would otherwise see. + try { + fn(value); + } finally { + dispose(); + } }); - return dispose; + return () => { + active = false; + dispose(); + }; } // Subscribes to every source, recomputing on any notification. diff --git a/kt/moq-ffi/MIGRATE.md b/kt/moq-ffi/MIGRATE.md index 9525d9ce6a6..2f15dab034f 100644 --- a/kt/moq-ffi/MIGRATE.md +++ b/kt/moq-ffi/MIGRATE.md @@ -2,6 +2,10 @@ ## Unreleased +### Viewer targets are bounded ([#7090](https://github.com/moq-dev/moq/pull/7090)) + +Viewer ceilings and PROBE target overrides are refused with the new `MoqException.OutOfRange` once they would sum above 2^53 - 1 bps, the most a PROBE target carries; nothing changes on a refusal. `MoqViewers.watch` and `setTarget` and `MoqViewer.update` throw it. Handle the new variant wherever you match the error exhaustively. Regenerate bindings and rebuild the matching native library together. + ### Media setup refusals are typed Audio and video subscribe setup now reports `MoqException.UnsupportedConfig` when the decoder refuses a codec, layout, or description. Handle this variant to try another rendition instead of inspecting an audio/video error message or `Unsupported`. Decoder faults, such as a backend that fails to open, and later peer and decode failures keep their existing errors. Regenerate bindings and rebuild the matching native library together. diff --git a/kt/moq/MIGRATE.md b/kt/moq/MIGRATE.md index 4eda798883f..1085c33056d 100644 --- a/kt/moq/MIGRATE.md +++ b/kt/moq/MIGRATE.md @@ -4,6 +4,10 @@ How to update your code for each breaking change, newest first. ## Unreleased +### Viewer targets are bounded ([#7090](https://github.com/moq-dev/moq/pull/7090)) + +Viewer ceilings and PROBE target overrides are refused with the new `MoqException.OutOfRange` once they would sum above 2^53 - 1 bps, the most a PROBE target carries; nothing changes on a refusal. `Viewers.watch` and `setTarget` and `Viewer.update` throw it. Handle the new variant wherever you match the error exhaustively. Regenerate bindings and rebuild the matching native library together. + ### `VideoInit.lower` takes either producer kind ([#7699](https://github.com/moq-dev/moq/pull/7699)) `VideoInit.lower` is a `dev.moq.media.Producer` (`uniffi.moq.MoqMediaProducer`) instead of a `TrackProducer`. Pass `MoqMediaProducer.Track(producer)`, or `MoqMediaProducer.Stream(producer)` for a byte-stream rendition. diff --git a/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/Aliases.kt b/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/Aliases.kt index 2789356ded4..e9c10ada02d 100644 --- a/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/Aliases.kt +++ b/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/Aliases.kt @@ -288,6 +288,15 @@ typealias BandwidthConsumer = uniffi.moq.MoqBandwidthConsumer /** One track's standing claim on an [Allocator]. */ typealias Reservation = uniffi.moq.MoqReservation +/** Divides one connection's receive estimate among the broadcasts watched over it. */ +typealias Viewers = uniffi.moq.MoqViewers + +/** + * One watched broadcast's standing claim on [Viewers]; holding it requests PROBE, closing it + * releases the claim. + */ +typealias Viewer = uniffi.moq.MoqViewer + /** Turns a [Reservation]'s grant into a sender's [RateTarget]; call `update` on every frame. */ typealias RateControl = uniffi.moq.MoqRateControl diff --git a/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/Moq.kt b/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/Moq.kt index 46dc101fff8..fc1fbb9d6a4 100644 --- a/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/Moq.kt +++ b/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/Moq.kt @@ -61,6 +61,17 @@ internal constructor( */ fun allocator(): Allocator = session.allocator() + /** + * The session's viewers, dividing the connection's receive estimate among the broadcasts + * watched over it. + * + * Every call returns a handle to the same registry, and the session sends what its viewers' + * ceilings add up to as its PROBE target. [Viewers.watch] a broadcast with the ceiling of the + * largest rendition the player would switch to, read its slice with [Viewer.rate], and + * [Viewer.close] it once the broadcast stops being watched. + */ + fun viewers(): Viewers = session.viewers() + /** * Follow the grant the peer gave this session. * diff --git a/kt/moq/src/jvmAndAndroidTest/kotlin/dev/moq/SmokeTest.kt b/kt/moq/src/jvmAndAndroidTest/kotlin/dev/moq/SmokeTest.kt index 4bf978bed2d..31b6c21613a 100644 --- a/kt/moq/src/jvmAndAndroidTest/kotlin/dev/moq/SmokeTest.kt +++ b/kt/moq/src/jvmAndAndroidTest/kotlin/dev/moq/SmokeTest.kt @@ -681,6 +681,33 @@ class SmokeTest { } } + @Test + fun `viewers watch, update, and release before the session connects`() = runTest { + Server.listen( + ServerConfig(bind = "127.0.0.1:0", tls = ServerTls(generate = listOf("localhost"))) + ) + .use { server -> + Moq.connect( + "https://${server.localAddr}", + ClientConfig(tls = ClientTls(insecure = true)), + ) + .use { moq -> + val viewers: Viewers = moq.viewers() + // The server never accepts, so there is no receive estimate to divide. + val viewer: Viewer = viewers.watch(4_000_000uL) + viewer.use { + assertNull(it.rate()) + it.update(1_000_000uL) + assertNull(it.rate()) + } + viewers.setTarget(0uL) + viewers.setTarget(null) + // Past what a PROBE target carries: refused. + assertFailsWith { viewers.watch(1uL shl 53) } + } + } + } + @Test fun `closing a server releases its port`() = runTest { val first = diff --git a/py/moq-ffi/MIGRATE.md b/py/moq-ffi/MIGRATE.md index 042afc06407..ab1806ded62 100644 --- a/py/moq-ffi/MIGRATE.md +++ b/py/moq-ffi/MIGRATE.md @@ -2,6 +2,10 @@ ## Unreleased +### Viewer targets are bounded ([#7090](https://github.com/moq-dev/moq/pull/7090)) + +Viewer ceilings and PROBE target overrides are refused with the new `MoqError.OutOfRange` once they would sum above 2^53 - 1 bps, the most a PROBE target carries; nothing changes on a refusal. `MoqViewers.watch` and `set_target` and `MoqViewer.update` raise it. Handle the new variant wherever you match the error exhaustively. Regenerate bindings and rebuild the matching native library together. + ### Media setup refusals are typed Audio and video subscribe setup now reports `UnsupportedConfig` when the decoder refuses a codec, layout, or description. Handle this variant to try another rendition instead of inspecting an audio/video error message or `Unsupported`. Decoder faults, such as a backend that fails to open, and later peer and decode failures keep their existing errors. Regenerate bindings and rebuild the matching native library together. diff --git a/py/moq-rs/MIGRATE.md b/py/moq-rs/MIGRATE.md index dbcce1fe979..27249eeaf44 100644 --- a/py/moq-rs/MIGRATE.md +++ b/py/moq-rs/MIGRATE.md @@ -4,6 +4,10 @@ How to update your code for each breaking change, newest first. ## Unreleased +### Viewer targets are bounded ([#7090](https://github.com/moq-dev/moq/pull/7090)) + +Viewer ceilings and PROBE target overrides are refused with the new `moq.Error.OutOfRange` once they would sum above 2^53 - 1 bps, the most a PROBE target carries; nothing changes on a refusal. `Viewers.watch` and `set_target` and `Viewer.update` raise it. Handle the new variant wherever you match the error exhaustively. Regenerate bindings and rebuild the matching native library together. + ### `VideoInit.lower` takes either producer kind ([#7699](https://github.com/moq-dev/moq/pull/7699)) The `lower=` argument of `TrackProducer.video` and `TrackStreamProducer.video` accepts either producer and needs no change. Code that sets the raw `VideoInit.lower` field wraps the handle as `MoqMediaProducer.TRACK(producer=...)` or `MoqMediaProducer.STREAM(producer=...)`. diff --git a/py/moq-rs/README.md b/py/moq-rs/README.md index 4630a685467..06a0a24f11f 100644 --- a/py/moq-rs/README.md +++ b/py/moq-rs/README.md @@ -163,6 +163,7 @@ client = moq.Client( - `.stats() → ConnectionStats`. Snapshot RTT, bandwidth estimates, and byte/packet counters. - `.state()` and `await .state_changed(after)`. Read one lifecycle snapshot and wait with its revision; first-dial failures and reconnects share the same session. - `.allocator() → Allocator`. Divide the send estimate between encoders and app-owned tracks. + - `.viewers() → Viewers`. Divide the receive estimate between watched broadcasts: `.watch(max_bps) → Viewer` claims up to a ceiling, `Viewer.rate()` reads its slice (`None` while there is no estimate), and dropping the viewer releases it. The summed ceilings are the PROBE target; `.set_target(bps)` overrides it (`0` sends none, `None` follows the viewers again). - `.grants() → GrantConsumer`. On `moq-lite-07-wip` and on moq-transport draft-18+ with the MoQ Auth extension, `.grant()` reads the peer's `Grant` and `async for grant in session.grants()` follows it. - `.tokens() → Tokens | None`. A client session's credentials: `.set([...])` replaces them without reconnecting and `await .answered()` raises the relay's refusal. diff --git a/py/moq-rs/moq/__init__.py b/py/moq-rs/moq/__init__.py index 6ab6dbb7630..016bb64095d 100644 --- a/py/moq-rs/moq/__init__.py +++ b/py/moq-rs/moq/__init__.py @@ -49,6 +49,8 @@ Reservation, Session, Tokens, + Viewer, + Viewers, ) from .subscribe import ( BroadcastConsumer, @@ -165,6 +167,8 @@ "VideoEncoderOutput", "VideoDecodedFrame", "VideoPixelFormat", + "Viewer", + "Viewers", "WebSocketConfig", "connect", "is_auth", diff --git a/py/moq-rs/moq/session.py b/py/moq-rs/moq/session.py index 6c1670223ea..67f1b7ee2ab 100644 --- a/py/moq-rs/moq/session.py +++ b/py/moq-rs/moq/session.py @@ -13,6 +13,8 @@ MoqReservation, MoqSession, MoqTokens, + MoqViewer, + MoqViewers, ) from ._records import _strs @@ -132,6 +134,16 @@ def allocator(self) -> Allocator: """ return Allocator(self._inner.allocator()) + def viewers(self) -> Viewers: + """The session's viewers, dividing the receive estimate among watched broadcasts. + + Every call returns a handle to the same registry, and the session sends + what its viewers' ceilings add up to as its PROBE target. A client handle + survives reconnects: a viewer reads ``None`` while disconnected and + resumes on the next connection. + """ + return Viewers(self._inner.viewers()) + class GrantConsumer: """Follows the grant a session's peer gave it, returned by :meth:`Session.grants`. @@ -272,6 +284,59 @@ def update(self, max_bps: int) -> None: self._inner.update(max_bps) +class Viewers: + """Divides one connection's receive estimate among the broadcasts watched over it. + + Minted by :meth:`Session.viewers`. Handles from one session share a registry. + """ + + def __init__(self, inner: MoqViewers) -> None: + self._inner = inner + + def watch(self, max_bps: int) -> Viewer: + """Watch a broadcast receiving at most ``max_bps``, returning its viewer. + + ``max_bps`` is a ceiling: what the largest rendition the player would + switch to needs, not what it is receiving. Drop the viewer once the + broadcast stops being watched. Holding one requests the receive + estimate, like :meth:`Session.recv_bandwidth`. Raises + ``moq.Error.OutOfRange``, watching nothing, when the ceilings would sum + above ``2**53 - 1``. + """ + return Viewer(self._inner.watch(max_bps)) + + def set_target(self, target_bps: int | None) -> None: + """Send ``target_bps`` as the PROBE target instead of the viewers' sum. + + ``None`` follows the viewers again, and ``0`` sends no target. Raises + ``moq.Error.OutOfRange``, keeping the previous override, above ``2**53 - 1``. + """ + self._inner.set_target(target_bps) + + +class Viewer: + """One watched broadcast's standing claim on :class:`Viewers`. + + :meth:`rate` is a snapshot: ``None`` means no receive estimate, so hold the + current selection, and ``0`` is a real zero rate. + """ + + def __init__(self, inner: MoqViewer) -> None: + self._inner = inner + + def rate(self) -> int | None: + """This viewer's slice of the receive estimate right now, in bits per second.""" + return self._inner.rate() + + def update(self, max_bps: int) -> None: + """Change the ceiling, keeping the same claim. + + Raises ``moq.Error.OutOfRange``, keeping the previous ceiling, when the + ceilings would sum above ``2**53 - 1``. + """ + self._inner.update(max_bps) + + class RateControl: """Turns a :class:`Reservation`'s grant into a sender's :data:`RateTarget`. diff --git a/py/moq-rs/tests/test_server.py b/py/moq-rs/tests/test_server.py index 11297357e69..1deab09e91d 100644 --- a/py/moq-rs/tests/test_server.py +++ b/py/moq-rs/tests/test_server.py @@ -212,6 +212,36 @@ async def test_session_state_names_a_failing_first_dial(): session.cancel(0) +async def test_viewer_holds_without_an_estimate(): + """A viewer on a session that has not connected reads no estimate.""" + import socket + + with socket.socket(socket.AF_INET, socket.SOCK_DGRAM) as silent: + silent.bind(("127.0.0.1", 0)) + host, port = silent.getsockname() + client = moq.Client( + f"https://{host}:{port}", + tls=moq.ClientTls(insecure=True), + bind="127.0.0.1:0", + websocket=moq.WebSocketConfig(enabled=False), + ) + async with client: + session = client.session + assert session is not None + viewers = session.viewers() + viewer = viewers.watch(1_000_000) + viewer.update(2_000_000) + viewers.set_target(0) + viewers.set_target(None) + assert viewer.rate() is None + # Past what a PROBE target carries: refused. + with pytest.raises(moq.Error.OutOfRange): + viewers.watch(2**53) + with pytest.raises(moq.Error.OutOfRange): + viewers.set_target(2**53) + session.cancel(0) + + async def test_server_close_releases_port(): """Exiting the context manager releases the listening socket before it returns, so the same address binds again with no retry.""" diff --git a/quest/m2/probe/README.md b/quest/m2/probe/README.md index 6ca5266317a..0fae738bad5 100644 --- a/quest/m2/probe/README.md +++ b/quest/m2/probe/README.md @@ -30,7 +30,7 @@ publisher-local padding handle: target and the peer's PROBE target. PROBE `Increase` is the wire signal; retransmission or padding is the mechanism. The send target (`bandwidth::Allocator`'s reservations) owns the local half and - [viewer targets](/quest/m2/probe/viewer-target.md) the peer's. + viewer targets (`bandwidth::Viewers`, [moq-dev/moq#7090](https://github.com/moq-dev/moq/pull/7090)) the peer's. - **Viewers are in scope.** The viewer up-switch joined the epic, since a viewer's target is the same session target sent the other way. - **moq-net stays catalog-agnostic, and each hop is independent.** A relay @@ -64,11 +64,24 @@ Decided with the maintainer on 2026-10-20: probes with padding. - The target then split: m1 keeps the send target native rung recovery needs, and viewer handles, viewer grants, the peer's - PROBE target, and `Increase` came back here as - [viewer targets](/quest/m2/probe/viewer-target.md), beside their consumers. + PROBE target, and `Increase` came back here as viewer targets, beside their + consumers, and landed in [moq-dev/moq#7090](https://github.com/moq-dev/moq/pull/7090). The `js/net` send target moved to [padding](/quest/m2/probe/padding.md), its only sender. +Decided with the maintainer on 2026-11-03, in review of +[moq-dev/moq#7090](https://github.com/moq-dev/moq/pull/7090): + +- **A local override covers local reservations only.** ✅ Keep the larger of + the two targets: `Allocator::set_target(Some(0))` stops probing for this + side's reservations, and the peer's PROBE target still sets how high to + probe. Rejected: a local zero that also disables peer-driven probing. +- **Unencodable viewer targets are refused at the public API.** ✅ Viewer + ceilings and overrides that would sum above 2^53 - 1 bps fail + (`Error::BoundsExceeded` in Rust, `MoqError::OutOfRange` through moq-ffi, a + `RangeError` in JS) and change nothing. Rejected: saturating the advertised + target, which silently changes what an oversized target means. + This README's own work, once the children land: - An end-to-end shaped-uplink test, at least nightly: a Chrome publisher @@ -87,7 +100,6 @@ This README's own work, once the children land: - [Browser send estimate](/quest/m2/probe/browser-send-estimate.md) - shipping Chrome and Safari publishers adapt to the relay's PROBE estimate, since they have no `getStats()` - [Padding probes](/quest/m2/probe/padding.md) - a browser probes with a lowest-priority padding stream on an ALR schedule - [JS rung disable](/quest/m2/probe/rung-disable-js.md) - `@moq/publish` applies the native rung rule, recovering through padding -- [Viewer targets](/quest/m2/probe/viewer-target.md) - a session sends its viewer handles as its PROBE target, probes to the peer's, splits the receive estimate into viewer grants, and advertises `Increase` where a sender exists - [Players set viewer targets](/quest/m2/probe/players.md) - players hold a viewer handle per watched broadcast at its highest enabled rendition's bitrate - [Viewer up-switch](/quest/m2/probe/viewer-upswitch.md) - a viewer capped by its small rendition finds headroom through PROBE and moves up - [Viewer targets are tested end to end and documented in Python](/quest/m2/probe/viewer-followups.md) - three gaps moq-dev/moq#7090 left are closed diff --git a/quest/m2/probe/padding.md b/quest/m2/probe/padding.md index 01880688332..f19f7a120d1 100644 --- a/quest/m2/probe/padding.md +++ b/quest/m2/probe/padding.md @@ -9,9 +9,8 @@ sends a short probe cluster at about twice the estimate, capped at the target, about every five seconds, with a follow-up probe when one validates. When the path has room the estimate rises; when it doesn't, padding stays within its overhead and media frame-delay budgets. Such sessions on lite-07 or IETF -draft-18 and later then have a sender, so -[viewer targets](/quest/m2/probe/viewer-target.md) can advertise PROBE -`Increase` for them. +draft-18 and later then have a sender, so they advertise PROBE `Increase` and +probe to the larger of their send target and the peer's PROBE target. ## Plan @@ -33,6 +32,14 @@ Decided with the maintainer on 2026-10-17 (see the (`js/net/src/connection/reload.ts`). Moved here in review of [#6102](https://github.com/moq-dev/moq/pull/6102), so m1 ships no browser target without a sender. +- **The peer's target.** Viewer targets landed first ([moq-dev/moq#7090](https://github.com/moq-dev/moq/pull/7090)), so + `js/net` still advertises `Report` and its publisher's `runProbe` reads and + drops a peer's PROBE target. With padding, keep the latest target from each + PROBE stream (zero once the stream ends), pad to the larger of it and the send + target, and advertise `Increase` from `probeLevel` only where padding runs, + mirroring Rust's `ProbeLevel::detect` and the session's `Probing` in + `rs/moq-net/src/session.rs`. The two directions never mix: a viewer's own + target goes to its peer, never into what it pads. - **WebRTC's schedule.** Model it on GoogCC's `ProbeController` ALR probing. Rejected: [#5863](https://github.com/moq-dev/moq/pull/5863)'s exponential backoff to 60 s, which leaves a rendition waiting up to a minute after the @@ -63,6 +70,9 @@ Tests, on `@moq/clock`'s `Manual`: - The padding writer over a fake WebTransport: padding goes out at the lowest priority on lite-07 and IETF draft-18, while lite-05, lite-06, and drafts 14 to 17 pad nothing and negotiate `Report`. +- A peer's PROBE target raises what padding probes to, a session that also + watches never pads for its own viewers, and the target lapses when the + PROBE stream ends. - In Chrome through a shaped link: with padding the estimate rises past the media, without it it stays frozen. On a path held below the target, report media frame delay and deadline misses against budgets set before tuning: diff --git a/quest/m2/probe/players.md b/quest/m2/probe/players.md index eadf39e9eef..ade697532c7 100644 --- a/quest/m2/probe/players.md +++ b/quest/m2/probe/players.md @@ -16,8 +16,11 @@ Decided with the maintainer on 2026-10-17 (see the already reads the catalog, which keeps moq-net catalog-agnostic, and only an enabled rendition is one it could switch to. Targets are on by default. -- The handle comes from the [viewer targets](/quest/m2/probe/viewer-target.md) quest; this - quest only decides its `max`. +- The handle is a `Bandwidth.Viewer` from `connection.viewers` in `@moq/net` + (`Session::viewers` or `moq_tokio::Connection::viewers` in Rust, and + `MoqSession::viewers` through moq-ffi and every binding, decided with the + maintainer on 2026-10-31), landed in + [moq-dev/moq#7090](https://github.com/moq-dev/moq/pull/7090); this quest only decides its `max`. - Settle what a rendition without a catalog bitrate contributes. - A probe that reaches the target must make the rendition selectable. Selection discounts the estimate (0.8x in `js/watch/src/video/source.ts`) @@ -28,7 +31,3 @@ enabled rendition is one it could switch to. Targets are on by default. Tests with mocked catalogs: the target tracks the highest enabled rendition through enable and disable flips, ignores disabled ones, drops when unwatched, and yields to an application override. - -## Required - -- [Viewer targets](/quest/m2/probe/viewer-target.md) - the per-broadcast viewer handle diff --git a/quest/m2/probe/viewer-followups.md b/quest/m2/probe/viewer-followups.md index fd94679b999..7b3812a2d15 100644 --- a/quest/m2/probe/viewer-followups.md +++ b/quest/m2/probe/viewer-followups.md @@ -16,7 +16,7 @@ left are closed: ## Plan Decided 2026-10-31 (user, /quest-plan of the follow-ups from the 2026-10-31 /quest-complete run), from [moq-dev/moq#7090](https://github.com/moq-dev/moq/pull/7090), -which finishes [viewer targets](/quest/m2/probe/viewer-target.md). +which finishes viewer targets. - Pooled reconnect: the `Reload`/pool `viewers` wiring (`js/net/src/connection/reload.ts`) is covered only by type checks and @@ -37,7 +37,3 @@ viewer once they adapt renditions is [players](/quest/m2/probe/players.md)' work, not this quest's. Public API: none (tests and docs). Wire: none. - -## Required - -- [Viewer probe targets and grants](/quest/m2/probe/viewer-target.md) - its PR, [moq-dev/moq#7090](https://github.com/moq-dev/moq/pull/7090), adds the handles and PROBE wiring these test diff --git a/quest/m2/probe/viewer-target.md b/quest/m2/probe/viewer-target.md deleted file mode 100644 index 695490903f1..00000000000 --- a/quest/m2/probe/viewer-target.md +++ /dev/null @@ -1,87 +0,0 @@ -# [M] Viewer probe targets and grants - -## Goal - -A moq-net session and a `js/net` connection each keep a receive target: the -sum of their viewer handles, sent to the peer as the PROBE target. A sending -session probes to the larger of its own send target -(`bandwidth::Allocator`'s; in `js/net`, the one [padding](/quest/m2/probe/padding.md) adds) and the -peer's PROBE target, and advertises PROBE `Increase` where it has a -sender. The two directions never mix: a session that publishes and watches -doesn't probe its uplink for what it watches. - -Each viewer handle also reads a grant: its share of the session's receive -estimate, so several broadcasts watched over one connection each select -against their own share instead of the whole downlink. - -## Plan - -Split from the send target by the maintainer on -2026-10-20: m1 native rung recovery needs only the send target, while these -handles' consumers ([players](/quest/m2/probe/players.md) and the -[viewer up-switch](/quest/m2/probe/viewer-upswitch.md)) are in m2. - -Decided with the maintainer on 2026-10-17 (see the -[epic](/quest/m2/probe/README.md)): - -- **A viewer handle per broadcast.** The subscriber session hands out a - reservation-like handle carrying a `max`, one per watched broadcast; the - session sums the live handles and sends the sum as its PROBE target. - Updating or dropping a handle changes the sum. Rejected: one target the - application sums, which pushes the multi-broadcast case onto every app. - Players hold these handles. -- **Viewer grants.** Decided with the maintainer on 2026-10-19: a viewer - handle carries a grant the way a publisher `Reservation` does, splitting the - receive estimate across live handles max-min fair by `max`, the split the - send `Allocator` applies within one priority tier - (`rs/moq-net/src/model/bandwidth.rs`). A handle asking for less than an even - cut takes all of it and leaves the rest to the others. Today every - `` on a pooled connection selects against 0.8x the whole - `estimatedRecvRate`, so N watchers over-select about N times. Rejected: each - watcher measuring its own subscription's rate, which stays app-limited and - can't see headroom, and dividing the estimate by the watcher count, which - ignores each handle's `max`. - Handles carry no priority: subscription priorities are per track and fixed - by kind, so no per-broadcast priority exists to divide by. Add one when a - player needs to favor one broadcast over another. -- **Peer target.** A sending session probes to the larger of its own target - and the peer's PROBE target. Each hop is independent: a relay never forwards - a viewer's target upstream, and the PROBE target stays per connection, with - no per-track wire field. moq-net reads no catalog. A peer's target is - untrusted, but it only sets how high to probe: each probe scales the - current estimate (BBR's 1.25x phase, padding's 2x cluster) and stays under - congestion control. Repeated cycles can still walk the estimate up to the - path's capacity, so a huge target costs the redundant bytes of probing that - far, held to native probing's overhead budget (redundant bytes at most - 10% of unique bytes, [moq-dev/moq#6635](https://github.com/moq-dev/moq/pull/6635)); a peer that subscribes to more media can already cost the - sender that much. Clamp it to the session's rate cap where one exists - ([rate grant](/quest/m2/rate-grant.md)) rather than adding a constant. -- **`Increase` only with a sender.** SETUP advertises `Increase` only when - the session has a sender behind the seam the send target defines: native - probing on moq-quic, padding in the browser. A browser session on a version - [padding](/quest/m2/probe/padding.md) refuses (lite-05, lite-06) has none, so it keeps `Report`. -- **Automatic, opt-out.** Targets are on by default; an application can - override them or disable probing. - -Notes for the implementer: - -- Rust sessions request PROBE today only while an owned `recv_bandwidth()` - consumer is held (`doc/concept/standard.md`). If the viewer handle subsumes - that, migrate those callers in the same change; a held consumer never - silently stops requesting PROBE. -- Wire: none. PROBE already carries a target and SETUP the `Increase` level - (`drafts/draft-lcurley-moq-lite.md`, `drafts/draft-lcurley-moq-probe.md`). - Report the public API in the PR, mirrored across Rust and JS, and carry it - through moq-ffi and the bindings per the cross-package sync table. - -Tests with mocked time, Rust and JS: viewer handles sum into the PROBE target -sent to the peer; the session probes to the larger of its reservations and -the peer's target; a session that publishes and watches keeps the two -directions apart; viewer grants split the receive estimate max-min fair by -`max` and never sum above it; `Increase` is advertised only with a sender, and never by a browser session -on a version padding refuses; -opting out sends no target. - -The sum fans out over viewer handles, so add a benchmark sweeping their count, -wired into the benchmark CI, so an update that rescans every handle shows up -as a slope. diff --git a/quest/m2/probe/viewer-upswitch.md b/quest/m2/probe/viewer-upswitch.md index 7d84f3a3129..3a6ef603302 100644 --- a/quest/m2/probe/viewer-upswitch.md +++ b/quest/m2/probe/viewer-upswitch.md @@ -19,14 +19,14 @@ estimate. Decided with the maintainer on 2026-10-17: this joined the [probe epic](/quest/m2/probe/README.md). [Players](/quest/m2/probe/players.md) -set the viewer target, the [session](/quest/m2/probe/viewer-target.md) sends it as -its PROBE target, and the relay's sender probes the downlink up to it; this +set the viewer target, the session sends it as its PROBE target +([moq-dev/moq#7090](https://github.com/moq-dev/moq/pull/7090)), and the relay's sender probes the downlink up to it; this quest makes selection act on the estimate that rises. The relay runs moq-quic, whose native probing ([moq-dev/moq#6635](https://github.com/moq-dev/moq/pull/6635)) is that sender. -Selection reads its broadcast's viewer grant from the -[viewer targets](/quest/m2/probe/viewer-target.md) quest, not the connection's whole +Selection reads its broadcast's viewer grant (`Bandwidth.Viewer.rate`), not +the connection's whole `estimatedRecvRate`, so several watchers on one pooled connection don't each select against the full downlink (decided with the maintainer on 2026-10-19). @@ -37,7 +37,6 @@ and audio, or selection stops discounting a probed estimate. ## Required -- [Viewer targets](/quest/m2/probe/viewer-target.md) - the viewer handle the session sends as its PROBE target, and the relay probing up to it - [Players set viewer targets](/quest/m2/probe/players.md) - `@moq/watch` asks for its highest enabled rendition ## Closes diff --git a/quest/m2/rate-grant.md b/quest/m2/rate-grant.md index 6a60eef9c3f..971748bf55d 100644 --- a/quest/m2/rate-grant.md +++ b/quest/m2/rate-grant.md @@ -32,6 +32,12 @@ negotiated IETF AUTH extension and `drafts/draft-lcurley-moq-auth.md` unchanged: extending cap reporting to IETF is outside this quest. Keeping that boundary avoids expanding the agreed lite-only wire change. +A sending session also clamps the peer's PROBE target to the cap it enforces +on that peer, as viewer targets decided rather than adding a constant: a target +past the cap only buys probing overhead the peer can never receive. The session +takes the larger of its own and the peer's target in `Probing` +(`rs/moq-net/src/session.rs`, [moq-dev/moq#7090](https://github.com/moq-dev/moq/pull/7090)); clamp the peer's half there. + Tests: a capped session's grant carries the rates; the publisher's video target never exceeds the cap minus overhead; a raised cap lets it climb back. diff --git a/rs/moq-c/README.md b/rs/moq-c/README.md index 16835118d7e..377774df99f 100644 --- a/rs/moq-c/README.md +++ b/rs/moq-c/README.md @@ -39,6 +39,13 @@ int32_t moq_allocator_close(uint32_t allocator); int32_t moq_reservation_rate(uint32_t reservation, uint64_t *bps, bool *present); int32_t moq_reservation_update(uint32_t reservation, uint64_t max_bps); int32_t moq_reservation_close(uint32_t reservation); +int32_t moq_session_viewers(uint32_t session); +int32_t moq_viewers_watch(uint32_t viewers, uint64_t max_bps); +int32_t moq_viewers_set_target(uint32_t viewers, uint64_t target_bps, bool present); +int32_t moq_viewers_close(uint32_t viewers); +int32_t moq_viewer_rate(uint32_t viewer, uint64_t *bps, bool *present); +int32_t moq_viewer_update(uint32_t viewer, uint64_t max_bps); +int32_t moq_viewer_close(uint32_t viewer); // Server int32_t moq_server_listen(const moq_server_config *config, moq_status_callback on_request, void *user_data); diff --git a/rs/moq-c/src/bandwidth.rs b/rs/moq-c/src/bandwidth.rs index 8d559d7bd8c..19a1d2170ca 100644 --- a/rs/moq-c/src/bandwidth.rs +++ b/rs/moq-c/src/bandwidth.rs @@ -1,16 +1,19 @@ -//! Session bandwidth allocator and per-track reservation, mirroring -//! [`moq_net::bandwidth`]. +//! Session bandwidth allocator and per-track reservation, and the receive-side +//! viewers, mirroring [`moq_net::bandwidth`]. use std::sync::Arc; use crate::{Error, Id, NonZeroSlab, State, ffi}; -/// Allocators minted from a session, plus the reservations taken against them. +/// Allocators minted from a session, plus the reservations taken against them, and +/// the same for the receive side's viewers. #[derive(Default)] pub(crate) struct Bandwidth { allocators: NonZeroSlab, reservations: NonZeroSlab>, consumers: NonZeroSlab>, + viewers: NonZeroSlab, + viewer: NonZeroSlab, } impl Bandwidth { @@ -45,6 +48,10 @@ impl Bandwidth { self.reservations.remove(id).ok_or(Error::NotFound)?; Ok(()) } + + pub fn insert_viewers(&mut self, viewers: moq_net::bandwidth::Viewers) -> Result { + self.viewers.insert(viewers) + } } /// The session's bandwidth allocator. Clones share one reservation registry. @@ -139,6 +146,136 @@ pub extern "C" fn moq_reservation_close(reservation: u32) -> i32 { }) } +/// The session's viewers, dividing the receive estimate among watched broadcasts. +/// +/// Clones share one registry, and the session sends the viewers' ceilings summed as its +/// PROBE target. Returns a non-zero handle, or a negative error if the session is unknown. +#[unsafe(no_mangle)] +pub extern "C" fn moq_session_viewers(session: u32) -> i32 { + ffi::enter(move || { + let session = ffi::parse_id(session)?; + let mut state = State::lock(); + let viewers = state.session.viewers(session)?; + state.bandwidth.insert_viewers(viewers) + }) +} + +/// Release a viewers handle. Viewers watched through it stay until each is closed (or +/// the session's viewers are gone). +#[unsafe(no_mangle)] +pub extern "C" fn moq_viewers_close(viewers: u32) -> i32 { + ffi::enter(move || { + let viewers = ffi::parse_id(viewers)?; + State::lock().bandwidth.viewers.remove(viewers).ok_or(Error::NotFound)?; + Ok(()) + }) +} + +/// Watch a broadcast receiving at most `max_bps`, returning a viewer handle. +/// +/// `max_bps` is a ceiling: what the largest rendition you would switch to needs, not +/// what you are receiving. Holding the viewer requests the receive estimate, like a +/// [`moq_session_recv_bandwidth`] consumer. Close it with [`moq_viewer_close`] once the +/// broadcast stops being watched. Returns [`MOQ_ERROR_OUT_OF_RANGE`](crate::MOQ_ERROR_OUT_OF_RANGE), +/// watching nothing, when the ceilings would sum above `2^53 - 1`. +#[unsafe(no_mangle)] +pub extern "C" fn moq_viewers_watch(viewers: u32, max_bps: u64) -> i32 { + ffi::enter(move || { + let viewers = ffi::parse_id(viewers)?; + let mut state = State::lock(); + let viewer = state + .bandwidth + .viewers + .get(viewers) + .ok_or(Error::NotFound)? + .watch(moq_net::bandwidth::Rate::from_bps(max_bps)) + .map_err(out_of_range)?; + state.bandwidth.viewer.insert(viewer) + }) +} + +/// Send `target_bps` as the PROBE target instead of the viewers' sum. +/// +/// `present` false follows the viewers again. `present` true and `target_bps` 0 sends +/// no target. Returns [`MOQ_ERROR_OUT_OF_RANGE`](crate::MOQ_ERROR_OUT_OF_RANGE), keeping the +/// previous override, for a target above `2^53 - 1`. +#[unsafe(no_mangle)] +pub extern "C" fn moq_viewers_set_target(viewers: u32, target_bps: u64, present: bool) -> i32 { + ffi::enter(move || { + let viewers = ffi::parse_id(viewers)?; + State::lock() + .bandwidth + .viewers + .get(viewers) + .ok_or(Error::NotFound)? + .set_target(present.then(|| moq_net::bandwidth::Rate::from_bps(target_bps))) + .map_err(out_of_range) + }) +} + +/// This viewer's slice of the receive estimate right now, in bits per second. +/// +/// `present` is false when there is no estimate: keep the current rendition. `present` +/// true and `bps` 0 is a real zero rate. +/// +/// # Safety +/// - `bps` and `present` must be valid pointers. +#[unsafe(no_mangle)] +pub unsafe extern "C" fn moq_viewer_rate(viewer: u32, bps: *mut u64, present: *mut bool) -> i32 { + ffi::enter(move || { + let viewer = ffi::parse_id(viewer)?; + let bps = unsafe { bps.as_mut() }.ok_or(Error::InvalidPointer)?; + let present = unsafe { present.as_mut() }.ok_or(Error::InvalidPointer)?; + let rate = State::lock() + .bandwidth + .viewer + .get(viewer) + .ok_or(Error::NotFound)? + .rate(); + *bps = rate.map_or(0, moq_net::bandwidth::Rate::as_bps); + *present = rate.is_some(); + Ok(()) + }) +} + +/// Change the viewer's ceiling, keeping the same claim. +/// +/// Returns [`MOQ_ERROR_OUT_OF_RANGE`](crate::MOQ_ERROR_OUT_OF_RANGE), keeping the previous +/// ceiling, when the ceilings would sum above `2^53 - 1`. +#[unsafe(no_mangle)] +pub extern "C" fn moq_viewer_update(viewer: u32, max_bps: u64) -> i32 { + ffi::enter(move || { + let viewer = ffi::parse_id(viewer)?; + State::lock() + .bandwidth + .viewer + .get(viewer) + .ok_or(Error::NotFound)? + .update(moq_net::bandwidth::Rate::from_bps(max_bps)) + .map_err(out_of_range) + }) +} + +/// A viewer ceiling or target refused for passing the PROBE target's limit. +fn out_of_range(err: moq_net::Error) -> Error { + Error::OutOfRange(format!( + "{err}: viewer targets sum to at most {} bps", + moq_net::bandwidth::Viewers::MAX_TARGET.as_bps() + )) +} + +/// Release a viewer, handing its share back to the others and lowering the PROBE target. +#[unsafe(no_mangle)] +pub extern "C" fn moq_viewer_close(viewer: u32) -> i32 { + ffi::enter(move || { + let viewer = ffi::parse_id(viewer)?; + // Released outside the lock. + let viewer = State::lock().bandwidth.viewer.remove(viewer).ok_or(Error::NotFound)?; + drop(viewer); + Ok(()) + }) +} + /// One owned estimate and, optionally, its single outstanding changed call. struct Consumer { inner: std::sync::Mutex>, diff --git a/rs/moq-c/src/error.rs b/rs/moq-c/src/error.rs index 8e08a9109c7..d37182a862d 100644 --- a/rs/moq-c/src/error.rs +++ b/rs/moq-c/src/error.rs @@ -84,6 +84,8 @@ pub const MOQ_ERROR_EXPIRED: i32 = -42; pub const MOQ_ERROR_UNSUPPORTED_CATALOG: i32 = -43; /// The rendition's codec, layout, or description was refused during setup; another rendition may work. pub const MOQ_ERROR_UNSUPPORTED_CONFIG: i32 = -44; +/// A number is outside the range the call accepts. +pub const MOQ_ERROR_OUT_OF_RANGE: i32 = -45; /// Whether a protocol code is from the session or stream registry. #[repr(C)] @@ -347,6 +349,11 @@ pub enum Error { /// resolved through an origin, so there is nothing to resolve the reference against. #[error("unresolvable broadcast reference: {0}")] UnresolvableBroadcast(String), + + /// A number was outside the range the call accepts, such as viewer ceilings summing + /// above what a PROBE target carries. + #[error("out of range: {0}")] + OutOfRange(String), } impl From for Error { @@ -537,6 +544,7 @@ impl ffi::ReturnCode for Error { Error::JsonTrack(_) => MOQ_ERROR_JSON_TRACK, Error::InvalidConfig(_) => MOQ_ERROR_INVALID_CONFIG, Error::UnresolvableBroadcast(_) => MOQ_ERROR_UNRESOLVABLE_BROADCAST, + Error::OutOfRange(_) => MOQ_ERROR_OUT_OF_RANGE, } } } diff --git a/rs/moq-c/src/session.rs b/rs/moq-c/src/session.rs index 7841b8552e7..1b7d744e7d5 100644 --- a/rs/moq-c/src/session.rs +++ b/rs/moq-c/src/session.rs @@ -157,14 +157,16 @@ impl Session { let _publish = publish; let _consume = consume; - // A panic ends only this session, reported through the terminal callback. - let res = ffi::run(publish_driver.watch(consume_driver.watch(async move { + // A panic ends only this session, reported through the terminal callback. Boxed so + // each wrapper holds a pointer: unoptimized builds otherwise copy the future into + // every layer's frame, overflowing the runtime thread's stack. + let res = ffi::run(publish_driver.watch(consume_driver.watch(Box::pin(async move { tokio::select! { // close() requested: drain what the session queued, then close it. _ = closed => reconnect.clone().close().await.map_err(map_connect_error), res = Self::report(callback, &reconnect, &monitor) => res, } - }))) + })))) .await; // The terminal callback waits for the close to reach the peer, so a caller that exits // on it doesn't leave the peer to time the connection out. @@ -221,13 +223,14 @@ impl Session { let _publish = publish; let _consume = consume; - // A panic ends only this session, reported through the terminal callback. - let mut res = ffi::run(publish_driver.watch(consume_driver.watch(async move { + // A panic ends only this session, reported through the terminal callback. Boxed + // like the dialed session's. + let mut res = ffi::run(publish_driver.watch(consume_driver.watch(Box::pin(async move { tokio::select! { _ = closed => Ok(()), res = Self::serve(id, callback, request) => res, } - }))) + })))) .await; let entry = State::lock().session.task.remove(id); @@ -294,6 +297,17 @@ impl Session { } } + /// The session's viewers, whose summed ceilings it sends as its PROBE target. A dialed + /// session's survive reconnects, reading no estimate while offline. + /// + /// Errors with [`Error::Offline`] for an accepted session still in SETUP. + pub fn viewers(&self, id: Id) -> Result { + match self.link(id)? { + Link::Dialed { connection, .. } => Ok(connection.viewers()), + Link::Accepted(accepted) => Ok(accepted.as_ref().ok_or(Error::Offline)?.session.viewers()), + } + } + /// Mint receive-estimate demand only when the caller asks for a consumer. pub fn recv_bandwidth(&self, id: Id) -> Result, Error> { match self.link(id)? { diff --git a/rs/moq-c/src/test.rs b/rs/moq-c/src/test.rs index ac3b25fad83..788cd996a4d 100644 --- a/rs/moq-c/src/test.rs +++ b/rs/moq-c/src/test.rs @@ -7144,6 +7144,55 @@ fn bandwidth_reservations_split_the_estimate() { assert_eq!(moq_origin_close(origin), 0); } +/// Two viewers split a 3 Mbps receive estimate max-min fair by ceiling, and closing +/// one hands its share back. +#[test] +fn viewers_split_the_receive_estimate() { + let estimate = moq_net::bandwidth::Producer::new(); + let viewers = { + let mut state = State::lock(); + let viewers = moq_net::bandwidth::Viewers::new(estimate.weak()); + id(i32::from(state.bandwidth.insert_viewers(viewers).unwrap())) + }; + let viewer_rate = |viewer: u32| { + let mut bps = 0; + let mut present = false; + assert_eq!(unsafe { moq_viewer_rate(viewer, &mut bps, &mut present) }, 0); + present.then_some(bps) + }; + + let first = id(moq_viewers_watch(viewers, 4_000_000)); + let second = id(moq_viewers_watch(viewers, 1_000_000)); + assert_eq!(viewer_rate(first), None); + + estimate + .set(Some(moq_net::bandwidth::Rate::from_bps(3_000_000))) + .unwrap(); + assert_eq!(viewer_rate(first), Some(2_000_000)); + assert_eq!(viewer_rate(second), Some(1_000_000)); + + assert_eq!(moq_viewer_update(second, 4_000_000), 0); + assert_eq!(viewer_rate(first), Some(1_500_000)); + assert_eq!(moq_viewers_set_target(viewers, 0, true), 0); + assert_eq!(moq_viewers_set_target(viewers, 0, false), 0); + + // Past what a PROBE target carries: refused, and nothing changes. + let max = moq_net::bandwidth::Viewers::MAX_TARGET.as_bps(); + assert_eq!(moq_viewers_watch(viewers, max), crate::MOQ_ERROR_OUT_OF_RANGE); + assert_eq!(moq_viewer_update(second, max), crate::MOQ_ERROR_OUT_OF_RANGE); + assert_eq!( + moq_viewers_set_target(viewers, max + 1, true), + crate::MOQ_ERROR_OUT_OF_RANGE + ); + assert_eq!(viewer_rate(first), Some(1_500_000)); + + assert_eq!(moq_viewer_close(second), 0); + assert_eq!(viewer_rate(first), Some(3_000_000)); + assert_eq!(moq_viewer_close(first), 0); + assert!(moq_viewer_close(first) < 0); + assert_eq!(moq_viewers_close(viewers), 0); +} + /// Two allocator handles share one registry. #[test] fn bandwidth_handles_share_the_registry() { diff --git a/rs/moq-ffi/CHANGELOG.md b/rs/moq-ffi/CHANGELOG.md index b19af36d87c..0c1744c8117 100644 --- a/rs/moq-ffi/CHANGELOG.md +++ b/rs/moq-ffi/CHANGELOG.md @@ -9,6 +9,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Added +- `MoqSession::viewers` returns a `MoqViewers` that divides the receive estimate + among watched broadcasts: `MoqViewers::watch` returns a `MoqViewer` reading its + slice, and the viewers' ceilings summed are the PROBE target sent to the peer. + Ceilings or a target past 2^53 - 1 bps are refused with the new + `MoqError::OutOfRange`. - `MoqAudioEncoder::track_init` returns the init that publishes its packets, and `MoqAudioEncoder::set_bitrate` retunes it live. - `MoqAudioDecoderOutput::delay_us` fixes the audio playout delay, and diff --git a/rs/moq-ffi/MIGRATE.md b/rs/moq-ffi/MIGRATE.md index 125bc6c280b..5260084c9d4 100644 --- a/rs/moq-ffi/MIGRATE.md +++ b/rs/moq-ffi/MIGRATE.md @@ -5,6 +5,10 @@ These are the UniFFI names; each language wrapper has its own `MIGRATE.md` in it ## Unreleased +### Viewer targets are bounded ([#7090](https://github.com/moq-dev/moq/pull/7090)) + +Viewer ceilings and PROBE target overrides are refused with the new `MoqError::OutOfRange` once they would sum above 2^53 - 1 bps, the most a PROBE target carries; nothing changes on a refusal. `MoqViewers::watch` and `set_target` and `MoqViewer::update` return a `Result`. Handle the new variant wherever you match the error exhaustively. Regenerate bindings and rebuild the matching native library together. + ### Datagrams are a track of their own A raw track's datagrams travel on a separate datagram track of the same name, so the API is unchanged but some results differ: diff --git a/rs/moq-ffi/src/bandwidth.rs b/rs/moq-ffi/src/bandwidth.rs index 36c9a89063a..4e35614e33e 100644 --- a/rs/moq-ffi/src/bandwidth.rs +++ b/rs/moq-ffi/src/bandwidth.rs @@ -88,6 +88,97 @@ impl MoqReservation { } } +/// Divides one connection's receive estimate among the broadcasts watched over it, +/// mirroring [`moq_net::bandwidth::Viewers`]. +/// +/// Minted by [`MoqSession::viewers`](crate::session::MoqSession::viewers). Handles from +/// one session share a registry, and the session sends what its viewers' ceilings add +/// up to as its PROBE target, so a peer that probes raises the estimate toward it. +#[derive(uniffi::Object)] +pub struct MoqViewers { + inner: moq_net::bandwidth::Viewers, +} + +impl MoqViewers { + pub(crate) fn new(inner: moq_net::bandwidth::Viewers) -> Self { + Self { inner } + } +} + +#[uniffi::export] +impl MoqViewers { + /// Watch a broadcast receiving at most `max_bps`, returning its viewer. + /// + /// `max_bps` is a ceiling: what the largest rendition the player would switch to + /// needs, not what it is receiving. The claim lasts as long as the returned handle; + /// drop it once the broadcast stops being watched. Holding one requests the receive + /// estimate, like [`MoqSession::recv_bandwidth`](crate::session::MoqSession::recv_bandwidth). + /// + /// Errors with [`MoqError::OutOfRange`], watching nothing, when the ceilings would sum + /// above [`moq_net::bandwidth::Viewers::MAX_TARGET`] (`2^53 - 1`). + pub fn watch(&self, max_bps: u64) -> Result, MoqError> { + let _guard = crate::ffi::enter(); + let inner = self + .inner + .watch(moq_net::bandwidth::Rate::from_bps(max_bps)) + .map_err(out_of_range)?; + Ok(Arc::new(MoqViewer { inner })) + } + + /// Send `target_bps` as the PROBE target instead of the viewers' sum, or `None` to + /// follow them again. `Some(0)` sends no target. + /// + /// Errors with [`MoqError::OutOfRange`], keeping the previous override, for a target + /// above `2^53 - 1`. + pub fn set_target(&self, target_bps: Option) -> Result<(), MoqError> { + let _guard = crate::ffi::enter(); + self.inner + .set_target(target_bps.map(moq_net::bandwidth::Rate::from_bps)) + .map_err(out_of_range) + } +} + +/// A viewer ceiling or target refused for passing the PROBE target's limit. +fn out_of_range(err: moq_net::Error) -> MoqError { + MoqError::OutOfRange { + reason: format!( + "{err}: viewer targets sum to at most {} bps", + moq_net::bandwidth::Viewers::MAX_TARGET.as_bps() + ), + } +} + +/// One watched broadcast's standing claim on a [`MoqViewers`]. +/// +/// [`rate`](Self::rate) is [`moq_net::bandwidth::Viewer::rate`]: `None` means no +/// receive estimate, so hold the current selection. +#[derive(uniffi::Object)] +pub struct MoqViewer { + inner: moq_net::bandwidth::Viewer, +} + +#[uniffi::export] +impl MoqViewer { + /// This viewer's slice of the receive estimate right now, in bits per second. + /// + /// `None` means no estimate: hold the current selection. `Some(0)` is a real zero rate. + pub fn rate(&self) -> Option { + let _guard = crate::ffi::enter(); + self.inner.rate().map(moq_net::bandwidth::Rate::as_bps) + } + + /// Change the ceiling, keeping the same claim. + /// + /// Errors with [`MoqError::OutOfRange`], keeping the previous ceiling, when the + /// ceilings would sum above `2^53 - 1`. + pub fn update(&self, max_bps: u64) -> Result<(), MoqError> { + let _guard = crate::ffi::enter(); + self.inner + .update(moq_net::bandwidth::Rate::from_bps(max_bps)) + .map_err(out_of_range) + } +} + /// How a [`MoqRateControl`] maps a reservation's grant onto the bitrate a sender produces. #[derive(Clone, Debug, uniffi::Record)] pub struct MoqRatePolicy { @@ -281,6 +372,44 @@ mod tests { assert_eq!(reserved.rate(), Some(1_000_000)); } + /// Two viewers split a 3 Mbps receive estimate max-min fair by ceiling. + #[test] + fn viewers_split_the_receive_estimate() { + let estimate = moq_net::bandwidth::Producer::new(); + let viewers = MoqViewers::new(moq_net::bandwidth::Viewers::new(estimate.weak())); + + let first = viewers.watch(4_000_000).unwrap(); + let second = viewers.watch(1_000_000).unwrap(); + assert_eq!(first.rate(), None); + + estimate + .set(Some(moq_net::bandwidth::Rate::from_bps(3_000_000))) + .unwrap(); + assert_eq!(first.rate(), Some(2_000_000)); + assert_eq!(second.rate(), Some(1_000_000)); + + second.update(4_000_000).unwrap(); + assert_eq!(first.rate(), Some(1_500_000)); + + drop(second); + assert_eq!(first.rate(), Some(3_000_000)); + } + + /// Ceilings and overrides past what a PROBE target carries are refused as out of range. + #[test] + fn viewer_targets_past_the_limit_are_out_of_range() { + let viewers = MoqViewers::new(moq_net::bandwidth::Viewers::default()); + let max = moq_net::bandwidth::Viewers::MAX_TARGET.as_bps(); + let refused = |res: Result<(), MoqError>| matches!(res, Err(MoqError::OutOfRange { .. })); + + assert!(refused(viewers.watch(u64::MAX).map(drop))); + let viewer = viewers.watch(max).unwrap(); + assert!(refused(viewers.watch(1).map(drop))); + assert!(refused(viewer.update(max + 1))); + assert!(refused(viewers.set_target(Some(max + 1)))); + viewers.set_target(Some(max)).unwrap(); + } + /// A rung follows its reservation's grant down, but never disables while no session /// probes for it, since nothing could then raise the grant to resume it. A missing /// grant holds the target. diff --git a/rs/moq-ffi/src/error.rs b/rs/moq-ffi/src/error.rs index 77f64f97005..febab5c2ce9 100644 --- a/rs/moq-ffi/src/error.rs +++ b/rs/moq-ffi/src/error.rs @@ -407,6 +407,13 @@ pub enum MoqError { /// A diagnostic message describing the refusal. reason: String, }, + /// A number was outside the range the call accepts, such as viewer ceilings summing + /// above what a PROBE target carries. + #[error("out of range: {reason}")] + OutOfRange { + /// A diagnostic message describing the refusal. + reason: String, + }, } impl From for MoqError { diff --git a/rs/moq-ffi/src/session.rs b/rs/moq-ffi/src/session.rs index 8d76459e449..035747bfe7a 100644 --- a/rs/moq-ffi/src/session.rs +++ b/rs/moq-ffi/src/session.rs @@ -1050,6 +1050,19 @@ impl MoqSession { self.allocator.clone() } + /// The session's viewers, used to divide the connection's receive estimate among + /// the broadcasts watched over it. + /// + /// Every call returns a handle to the same registry, and the session sends what its + /// viewers add up to as its PROBE target. A client handle survives reconnects: a + /// viewer reads `None` while disconnected and resumes on the next connection. + pub fn viewers(&self) -> Arc { + Arc::new(crate::bandwidth::MoqViewers::new(match &self.inner { + Inner::Connection(connection) => connection.viewers(), + Inner::Session(session) => session.viewers(), + })) + } + /// Follow the grant the peer gave this session. /// /// Every call returns an independent consumer. A client session's grant follows each diff --git a/rs/moq-net/MIGRATE.md b/rs/moq-net/MIGRATE.md index 3ece960bddd..85a6caf0965 100644 --- a/rs/moq-net/MIGRATE.md +++ b/rs/moq-net/MIGRATE.md @@ -4,6 +4,11 @@ How to update your code for each breaking change, newest first. ## Unreleased +### A zero `Allocator::set_target` leaves the peer's PROBE target ([#7090](https://github.com/moq-dev/moq/pull/7090)) + +A session with a sender now probes to the larger of its allocator's target and the PROBE target its peer sends, so `Allocator::set_target(Some(Rate::ZERO))` stops probing for this side's reservations only. A peer that advertises a target still raises the probe; a reservation's `Consumer::probed` stays `false`, since nothing probes for it. +The new `Viewers::watch`, `Viewers::set_target`, and `Viewer::update` return `Result` and refuse ceilings summing above `Viewers::MAX_TARGET` with `Error::BoundsExceeded`. + ### Datagrams are their own track kind ([#7752](https://github.com/moq-dev/moq/pull/7752)) A stream track no longer carries datagrams. `track::Producer::{append_datagram, insert_datagram}` and `track::Subscriber/Ordered::{poll_recv_datagram, recv_datagram}` are removed; a datagram track is created and read through the broadcast, in a namespace apart from stream tracks, with its own sequence counter. diff --git a/rs/moq-net/benches/bandwidth.rs b/rs/moq-net/benches/bandwidth.rs index fa25f610c60..7440f750bf0 100644 --- a/rs/moq-net/benches/bandwidth.rs +++ b/rs/moq-net/benches/bandwidth.rs @@ -3,6 +3,8 @@ //! - update: one reservation's ceiling moves and the session reads the new target. //! Swept over the reservations sharing the allocator, so an update that rescans //! every reservation shows up as a slope. +//! - viewers: one viewer's ceiling moves and the session reads the new PROBE target. +//! Swept over the viewers sharing the connection, for the same slope. //! - grants/estimate, grants/demand, grants/ceiling: one change (every connection's //! estimate, one track's demand on each connection, one ceiling on each connection), //! then every observer drains its parked [`Consumer`], as each sender's task does. @@ -26,7 +28,7 @@ use std::task::{Context, Poll, RawWaker, RawWakerVTable, Waker}; use std::time::Duration; use criterion::{BenchmarkId, Criterion, criterion_group}; -use moq_net::bandwidth::{Allocator, Consumer, Producer, Rate, Reservation}; +use moq_net::bandwidth::{Allocator, Consumer, Producer, Rate, Reservation, Viewers}; use moq_net::{broadcast, fuzz, kio, track}; /// Reservations sharing the allocator. @@ -65,6 +67,30 @@ fn bench_update(c: &mut Criterion) { group.finish(); } +fn bench_viewers(c: &mut Criterion) { + let mut group = c.benchmark_group("bandwidth/viewers"); + for count in RESERVATIONS { + group.bench_function(BenchmarkId::from_parameter(count), |b| { + let viewers = Viewers::default(); + let watched: Vec<_> = (0..count) + .map(|_| viewers.watch(Rate::from_kbps(1_000)).expect("within the limit")) + .collect(); + let mut target = fuzz::ProbeTarget::viewers(&viewers); + target.poll().expect("the first poll reports the target"); + let touched = &watched[count / 2]; + let mut raised = false; + b.iter(|| { + raised = !raised; + touched + .update(Rate::from_kbps(if raised { 2_000 } else { 1_000 })) + .expect("within the limit"); + std::hint::black_box(target.poll().expect("the target moved")); + }); + }); + } + group.finish(); +} + // ── counting ─────────────────────────────────────────────────────────────── struct Counter; @@ -499,7 +525,7 @@ fn counts(iterations: usize, case: Option<&str>) { } } -criterion_group!(benches, bench_update, bench_grants); +criterion_group!(benches, bench_update, bench_viewers, bench_grants); // Let each harness initialize and finalize its own Criterion implementation. mod harness { diff --git a/rs/moq-net/src/client.rs b/rs/moq-net/src/client.rs index 86716eeadeb..bbaea6605d0 100644 --- a/rs/moq-net/src/client.rs +++ b/rs/moq-net/src/client.rs @@ -24,6 +24,7 @@ pub struct Client { extensions: setup::Extensions, auth: Option, allocator: Option, + viewers: Option, implementation: Option, } @@ -88,6 +89,22 @@ impl Client { self.allocator.clone().unwrap_or_default() } + /// Share `viewers` with every session this client dials. + /// + /// Each session sends what they add up to as its PROBE target, and its + /// [`Session::viewers`](crate::Session::viewers) watches into the same registry, so + /// a viewer taken on one session still counts after a reconnect. Without one, each + /// session starts an empty registry of its own. + pub fn with_viewers(mut self, viewers: crate::bandwidth::Viewers) -> Self { + self.viewers = Some(viewers); + self + } + + /// The registry the next session sends the target of. + fn viewers(&self) -> crate::bandwidth::Viewers { + self.viewers.clone().unwrap_or_default() + } + /// Restrict which protocol versions to offer, in preference order. /// Defaults to every version this crate supports. pub fn with_versions(mut self, versions: Versions) -> Self { @@ -294,11 +311,12 @@ impl Client { ) -> Result<(Session, crate::Driver), Error> { let (publish, subscribe) = self.origins(peer_hop); - // Advertise our capabilities (we report what the transport measures; we - // don't pad) plus the request path on URI-less transports, and the - // direction we intend to use so the server can reject a token that lacks - // the matching scope during the handshake instead of silently carrying - // no media. Versions without a Setup Stream have nothing to advertise. + // Advertise our capabilities (we report what the transport measures, and + // probe to the peer's target only with a sender) plus the request path on + // URI-less transports, and the direction we intend to use so the server + // can reject a token that lacks the matching scope during the handshake + // instead of silently carrying no media. Versions without a Setup Stream + // have nothing to advertise. let our_setup = if version.has_setup_stream() { lite::Setup { probe: lite::ProbeLevel::detect(&session), @@ -316,11 +334,14 @@ impl Client { lite::Setup::default() }; + // One registry, which the subscriber sends and the session hands out. + let viewers = self.viewers(); let start = lite::start(lite::Config { runtime: runtime.clone(), stats: self.stats.clone(), client: true, limits: self.limits, + viewers: viewers.clone(), session: session.clone(), setup_stream: None, publish, @@ -344,7 +365,9 @@ impl Client { auth: start.auth, credential: start.credential, estimate: Some(start.estimate), + peer_target: Some(start.peer_target), bandwidth: self.allocator(), + viewers, peer_implementation: start.peer_implementation, }, )) @@ -419,7 +442,9 @@ impl Client { auth, credential, estimate: None, + peer_target: None, bandwidth: self.allocator(), + viewers: self.viewers(), peer_implementation, }, )); @@ -482,11 +507,14 @@ impl Client { } let stream = stream.with_version(v); + // One registry, which the subscriber sends and the session hands out. + let viewers = self.viewers(); let start = lite::start(lite::Config { runtime: runtime.clone(), stats: self.stats.clone(), client: true, limits: self.limits, + viewers: viewers.clone(), session: session.clone(), setup_stream: Some(stream), publish: publish.clone(), @@ -512,7 +540,9 @@ impl Client { auth: start.auth, credential: start.credential, estimate: Some(start.estimate), + peer_target: Some(start.peer_target), bandwidth: self.allocator(), + viewers, peer_implementation: start.peer_implementation, }, )) diff --git a/rs/moq-net/src/fuzz.rs b/rs/moq-net/src/fuzz.rs index 23c74b81e5a..07c43d80fa1 100644 --- a/rs/moq-net/src/fuzz.rs +++ b/rs/moq-net/src/fuzz.rs @@ -451,7 +451,7 @@ pub fn bump_publisher_bytes( registry.bump_publisher_bytes(path, tier, n); } -/// An allocator's probe target as its session follows it, for the bandwidth bench. +/// A probe target as its session follows it, for the bandwidth bench. pub struct ProbeTarget(crate::bandwidth::Target); impl ProbeTarget { @@ -460,6 +460,11 @@ impl ProbeTarget { Self(allocator.target()) } + /// Follow `viewers`' target, as the session sending it as PROBE does. + pub fn viewers(viewers: &crate::bandwidth::Viewers) -> Self { + Self(viewers.target()) + } + /// The target in bits per second once it moved, without parking. pub fn poll(&mut self) -> Option { match self.0.poll_changed(&kio::Waiter::noop()) { diff --git a/rs/moq-net/src/lite/publisher.rs b/rs/moq-net/src/lite/publisher.rs index ab24ead9dbd..a175559e2bc 100644 --- a/rs/moq-net/src/lite/publisher.rs +++ b/rs/moq-net/src/lite/publisher.rs @@ -1,7 +1,5 @@ use crate::driver::Transport; use crate::transport::poll::Session as _; -#[cfg(test)] -use std::sync::atomic::AtomicU64; use crate::{SessionError, announce, datagram, frame, group, origin, track}; use rangemap::{RangeMap, RangeSet}; @@ -11,7 +9,7 @@ use std::{ ops::{Bound, ControlFlow, Range}, sync::{ Arc, Mutex, - atomic::{AtomicUsize, Ordering}, + atomic::{AtomicU64, AtomicUsize, Ordering}, }, task::{Poll, ready}, time::Duration, @@ -92,6 +90,23 @@ struct Shared { // untimed (see `wire_timestamp`). runtime: crate::time::Deadlines, estimate: kio::ProducerWeak, + /// The peer's latest PROBE target, which the session's sender probes up to. + peer_target: kio::Producer, + /// Each open PROBE stream's latest target, which `peer_target` follows. + peer_targets: Mutex, + /// Numbers each PROBE stream for `peer_targets`. + probe_streams: AtomicU64, +} + +/// The latest target each open PROBE stream sent, so the peer's target is the newest +/// one written by a stream still open. A superseded stream's late targets and end then +/// settle on its replacement's target whatever order they arrive in, with no need to +/// know which stream the peer opened first. +#[derive(Default)] +struct PeerTargets { + /// By stream: when its target was written, counted by `writes`, and the target. + streams: HashMap, + writes: u64, } /// Largest millisecond duration every implementation can carry losslessly. @@ -132,6 +147,40 @@ fn cursor_floor(version: Version, start_group: Option, latest: Option) } impl Shared { + /// Record the PROBE target stream `stream` sent, which only a session with a sender + /// acts on. The latest write wins while several streams are open. + fn set_peer_target(&self, stream: u64, target: crate::bandwidth::Rate) { + let mut targets = self.peer_targets.lock().unwrap(); + targets.writes += 1; + let order = targets.writes; + targets.streams.insert(stream, (order, target)); + self.write_peer_target(target); + } + + /// Lapse the target stream `stream` sent as it ends, falling back to the newest one + /// another open stream sent, or zero. + fn clear_peer_target(&self, stream: u64) { + let mut targets = self.peer_targets.lock().unwrap(); + if targets.streams.remove(&stream).is_none() { + return; + } + let newest = targets + .streams + .values() + .max_by_key(|(order, _)| *order) + .map_or(crate::bandwidth::Rate::ZERO, |(_, target)| *target); + self.write_peer_target(newest); + } + + fn write_peer_target(&self, target: crate::bandwidth::Rate) { + // An error means nothing follows the target, which is then moot. + if let Ok(mut current) = self.peer_target.write() + && *current != target + { + *current = target; + } + } + /// Watches whether the session still lets us serve `broadcast` to the peer: our /// grant, and the ceiling on what the peer may subscribe to. fn gate(&self, broadcast: &crate::Path) -> crate::auth::Gate { @@ -209,6 +258,9 @@ impl Publisher { lister: crate::broadcast::Owner::new(), runtime: config.runtime.clone(), estimate: config.estimate, + peer_target: kio::Producer::new(crate::bandwidth::Rate::ZERO), + peer_targets: Default::default(), + probe_streams: AtomicU64::new(0), }), runtime: config.runtime, accept, @@ -218,6 +270,11 @@ impl Publisher { } impl Publisher { + /// The peer's latest PROBE target, or zero while it asks for none. + pub fn peer_target(&self) -> kio::Consumer { + self.shared.peer_target.consume() + } + pub fn poll(&mut self, waiter: &kio::Waiter) -> Poll> { if let Some(enforce) = &mut self.enforce && let Poll::Ready(res) = enforce.poll(&self.shared, waiter) @@ -662,6 +719,8 @@ struct ProbeServe { due: crate::time::Deadline, /// A peer streaming targets still lets the session's other tasks run. budget: kio::coop::Budget, + /// This stream's key in the session's `peer_targets`. + id: u64, } impl ProbeServe { @@ -713,6 +772,7 @@ impl ProbeServe { fn new(shared: Arc, runtime: crate::time::Deadlines, stream: Stream) -> Self { Self { + id: shared.probe_streams.fetch_add(1, Ordering::Relaxed) + 1, estimate: shared.estimate.consume(), seen: None, shared, @@ -725,7 +785,11 @@ impl ProbeServe { } fn poll(&mut self, waiter: &kio::Waiter) -> Poll> { - match ready!(self.poll_probe(waiter)) { + let res = ready!(self.poll_probe(waiter)); + // The stream carried the target, so it lapses with it, back to another open + // stream's target if a replacement already sent one. + self.shared.clear_peer_target(self.id); + match res { Ok(()) => tracing::debug!("probe stream closed"), Err(err) => { self.stream.take().expect("stream present").writer.abort(&err); @@ -751,11 +815,18 @@ impl ProbeServe { // Deliver the previous estimate before weighing the next one. ready!(stream.writer.poll_flush(waiter))?; - // Report ignores target values, but consumes them so buffered bytes - // cannot hide the peer's FIN or a malformed complete message. + // The peer's target, recorded for the session's sender. Without one the + // session ignores it, as a Report-level publisher must, but it is still + // consumed so buffered bytes cannot hide the peer's FIN or a malformed + // complete message. loop { match stream.reader.poll_decode_maybe::(waiter) { - Poll::Ready(Ok(Some(_))) => ready!(self.budget.poll_yield(waiter)), + Poll::Ready(Ok(Some(probe))) => { + let target = probe.bitrate.map(crate::bandwidth::Rate::from_bps); + self.shared + .set_peer_target(self.id, target.unwrap_or(crate::bandwidth::Rate::ZERO)); + ready!(self.budget.poll_yield(waiter)) + } Poll::Ready(Ok(None)) => return Poll::Ready(Ok(())), Poll::Ready(Err(err)) => return Poll::Ready(Err(err)), Poll::Pending => break, @@ -8272,6 +8343,38 @@ mod tests { ProbeServe::new(publisher.shared.clone(), publisher.runtime.clone(), stream) } + /// A subscriber that drops its PROBE stream and opens another can see the new + /// stream's target land before the old stream's buffered targets and end, in any + /// order: once the old stream ends, the new stream's target stands. + #[kio::test] + async fn a_superseded_probe_stream_keeps_its_successors_target() { + use crate::bandwidth::Rate; + let version = Version::Lite06; + let session = ScriptedSession::new(Vec::new()); + let mut transport = crate::driver::Transport::new(session.clone()); + let stream = Stream::open(&mut transport, version).await.unwrap(); + let estimate = kio::Producer::default(); + let old = probe_server(crate::driver::Transport::new(session), stream, version, &estimate); + let stream = Stream::open(&mut transport, version).await.unwrap(); + let new = ProbeServe::new(old.shared.clone(), crate::time::sim(), stream); + let shared = old.shared.clone(); + let target = shared.peer_target.consume(); + + shared.set_peer_target(old.id, Rate::from_bps(1_000_000)); + shared.set_peer_target(new.id, Rate::from_bps(2_000_000)); + // The old stream's buffered target lands late, winning while it is open. + shared.set_peer_target(old.id, Rate::from_bps(3_000_000)); + assert_eq!(*target.read(), Rate::from_bps(3_000_000)); + shared.clear_peer_target(old.id); + assert_eq!(*target.read(), Rate::from_bps(2_000_000)); + // A stream that never sent a target ends without touching the others'. + shared.clear_peer_target(old.id + new.id + 1); + assert_eq!(*target.read(), Rate::from_bps(2_000_000)); + + shared.clear_peer_target(new.id); + assert_eq!(*target.read(), Rate::ZERO); + } + #[kio::test] async fn malformed_complete_goaway_closes_the_session() { use kio::Task; diff --git a/rs/moq-net/src/lite/session.rs b/rs/moq-net/src/lite/session.rs index 88cce513670..3f63276c0f5 100644 --- a/rs/moq-net/src/lite/session.rs +++ b/rs/moq-net/src/lite/session.rs @@ -15,6 +15,8 @@ use super::{ pub(crate) struct SessionStart { pub recv_bandwidth: Option, + /// The peer's PROBE target, which the session's sender probes up to. + pub peer_target: kio::Consumer, /// The estimate PROBE reports, published by the session's supervisor. pub estimate: kio::Producer, /// The session's protocol machine over the boxed transport. @@ -202,6 +204,8 @@ pub struct Config { pub auth: crate::auth::Link, /// What the peer may make this session hold. pub limits: crate::session::Limits, + /// The viewers whose sum the session sends as its PROBE target. + pub viewers: bandwidth::Viewers, } /// Start a lite session. @@ -222,6 +226,7 @@ pub fn start(config: Config) -> Result { peer_setup, auth, limits, + viewers, } = config; let recv_bw = bandwidth::Producer::new(); @@ -334,6 +339,7 @@ pub fn start(config: Config) -> Result { client, subscriptions, }); + let peer_target = publisher.peer_target(); let mut subscriber = Subscriber::new(SubscriberConfig { runtime: runtime.clone(), session: session.clone(), @@ -350,6 +356,7 @@ pub fn start(config: Config) -> Result { auth: auth.clone(), }); subscriber.announces = announces; + subscriber.viewers = viewers; // SendSetup only logs a failure, so refuse a SETUP that cannot encode (one past the // size bound, such as a long implementation or path) here rather than leave the peer waiting. @@ -386,6 +393,7 @@ pub fn start(config: Config) -> Result { Ok(SessionStart { recv_bandwidth: recv_bw_consumer, + peer_target, estimate, driver, goaway: goaway_handle, @@ -944,6 +952,7 @@ mod tests { stats: Default::default(), client: true, limits: Default::default(), + viewers: Default::default(), session: crate::driver::Transport::new(transport.clone()), setup_stream: None, publish: None, @@ -989,6 +998,7 @@ mod tests { stats: Default::default(), client: true, limits: Default::default(), + viewers: Default::default(), session: crate::driver::Transport::new(transport), setup_stream: None, publish: None, @@ -1069,6 +1079,7 @@ mod tests { stats: Default::default(), client: false, limits: Default::default(), + viewers: Default::default(), session: crate::driver::Transport::new(transport.clone()), setup_stream: None, publish: None, @@ -1156,6 +1167,7 @@ mod tests { stats: Default::default(), client: true, limits: Default::default(), + viewers: Default::default(), session: crate::driver::Transport::new(transport.clone()), setup_stream: None, publish: None, @@ -1237,6 +1249,7 @@ mod tests { client: false, auth: crate::auth::Link::new(version.has_auth()), limits: Default::default(), + viewers: Default::default(), }) .unwrap(); let _ = started.driver.poll(&kio::Waiter::noop()); @@ -1292,6 +1305,7 @@ mod tests { client: false, auth: crate::auth::Link::new(version.has_auth()), limits: Default::default(), + viewers: Default::default(), }) .unwrap(); let _ = started.driver.poll(&kio::Waiter::noop()); @@ -1325,6 +1339,7 @@ mod tests { peer_setup, auth: crate::auth::Link::new(version.has_auth()), limits: Default::default(), + viewers: Default::default(), }) .unwrap() } diff --git a/rs/moq-net/src/lite/setup.rs b/rs/moq-net/src/lite/setup.rs index 259e9e8086e..6cdd9965762 100644 --- a/rs/moq-net/src/lite/setup.rs +++ b/rs/moq-net/src/lite/setup.rs @@ -60,14 +60,21 @@ impl ProbeLevel { /// Both metrics are sampled rather than declared, so this only works for a /// transport whose figures exist by the time the session starts. QUIC and TCP /// both qualify: their RTT comes from the handshake, which has already happened. + /// + /// [`Increase`](Self::Increase) additionally needs a sender, a transport + /// [`Probe`](crate::transport::Probe), since the session probes to the peer's + /// target through it. Without one a peer's target could never be honored. #[cfg(feature = "async")] pub fn detect(session: &crate::driver::Transport) -> Self { use crate::transport::Metrics as _; use crate::transport::poll::Session as _; let metrics = session.metrics(); - match metrics.estimated_send_rate().is_some() || metrics.rtt().is_some() { - true => Self::Report, - false => Self::None, + if metrics.estimated_send_rate().is_none() && metrics.rtt().is_none() { + return Self::None; + } + match session.probe().is_some() { + true => Self::Increase, + false => Self::Report, } } @@ -555,18 +562,18 @@ mod tests { ); } - /// Probing to a local target never reaches the wire, so a sender alone promises the - /// peer nothing more than a report. + /// A sender probes to the peer's target as well as its own, so it promises the peer + /// `Increase`. Without one, `detect_reports_with_either_metric` stays at `Report`. #[test] #[cfg(feature = "async")] - fn a_sender_still_reports() { + fn a_sender_advertises_increase() { use crate::lite::test_transport::{SinkSession, SinkStats}; let stats = SinkStats::default().with_send_rate(1_000_000); let session = SinkSession::new(Default::default()).with_stats(stats).with_probe(); assert_eq!( ProbeLevel::detect(&crate::driver::Transport::new(session.clone())), - ProbeLevel::Report + ProbeLevel::Increase ); } diff --git a/rs/moq-net/src/lite/subscriber.rs b/rs/moq-net/src/lite/subscriber.rs index 3998766d58e..688df73ad00 100644 --- a/rs/moq-net/src/lite/subscriber.rs +++ b/rs/moq-net/src/lite/subscriber.rs @@ -98,6 +98,8 @@ pub(super) struct Subscriber { auth: crate::auth::Link, /// Broadcasts the peer may have announced at once (`session::Limits::announces`). pub(super) announces: crate::session::Slots, + /// The viewers whose sum the PROBE stream sends as its target. + pub(super) viewers: bandwidth::Viewers, /// The instances minted for the paths the peer advertises without one, shared by the /// announce streams. minted: Minted, @@ -420,6 +422,7 @@ impl Subscriber { going_away: config.going_away, auth: config.auth, announces: Default::default(), + viewers: Default::default(), minted: Default::default(), } } @@ -1754,7 +1757,8 @@ impl DatagramRecv { } } -/// Opens a PROBE stream on demand while a consumer is interested. +/// Opens a PROBE stream on demand while a consumer is interested, and sends it the +/// viewers' target when the peer probes up to one. /// /// Loops forever: wait for a consumer, race the probe stream against the /// consumer leaving, then loop back. Transport errors stay per-stream; malformed @@ -1762,6 +1766,10 @@ impl DatagramRecv { struct RecvBandwidth { subscriber: Subscriber, state: BandwidthState, + /// The viewers' target, followed only once the peer advertised `Increase`. + target: Option, + /// The target last read from it. + wanted: bandwidth::Rate, } #[expect( @@ -1784,6 +1792,8 @@ impl RecvBandwidth { Self { subscriber, state: BandwidthState::Gate, + target: None, + wanted: bandwidth::Rate::ZERO, } } @@ -1794,11 +1804,16 @@ impl RecvBandwidth { if self.subscriber.recv_bandwidth.is_none() { return Poll::Ready(Ok(())); } - if self.subscriber.version.has_setup_stream() - && ready!(self.subscriber.peer_setup.poll_probe_level(waiter)) < lite::ProbeLevel::Report - { - tracing::debug!("peer does not support probing; skipping probe stream"); - return Poll::Ready(Ok(())); + if self.subscriber.version.has_setup_stream() { + let level = ready!(self.subscriber.peer_setup.poll_probe_level(waiter)); + if level < lite::ProbeLevel::Report { + tracing::debug!("peer does not support probing; skipping probe stream"); + return Poll::Ready(Ok(())); + } + // A Report-level peer ignores a target, so only a peer that probes is sent one. + if level >= lite::ProbeLevel::Increase { + self.target = Some(self.subscriber.viewers.target()); + } } self.state = BandwidthState::WaitUsed; } @@ -1824,7 +1839,12 @@ impl RecvBandwidth { Poll::Ready(Err(_)) => return Poll::Ready(Ok(())), Poll::Pending => {} } - match ready!(probe.poll(waiter)) { + if let Some(target) = &mut self.target { + while let Poll::Ready(rate) = target.poll_changed(waiter) { + self.wanted = rate; + } + } + match ready!(probe.poll(waiter, self.wanted)) { Ok(()) => tracing::debug!("probe stream closed"), Err(err) => { let err = lite::error::control(&mut self.subscriber.session.clone(), err); @@ -1852,11 +1872,13 @@ impl RecvBandwidth { } /// One PROBE stream: send the type, then feed the peer's estimates into the -/// bandwidth producer until it FINs. +/// bandwidth producer until it FINs, sending each new target along the way. struct ProbeStream { subscriber: Subscriber, session: Transport, state: ProbeState, + /// The target last sent; zero sends none. + sent: bandwidth::Rate, } #[kio::machine(self.state: ProbeState)] @@ -1866,10 +1888,12 @@ impl ProbeStream { subscriber: subscriber.clone(), session: subscriber.session.clone(), state: ProbeState::Start, + sent: bandwidth::Rate::ZERO, } } - fn poll(&mut self, waiter: &kio::Waiter) -> Poll> { + /// Run the stream, sending `target` whenever it differs from the last one sent. + fn poll(&mut self, waiter: &kio::Waiter, target: bandwidth::Rate) -> Poll> { let mut stream: Stream = wait!(Open => { // Probe is best-effort telemetry; a session that is going away // has no use for a new estimate, so skip it rather than erroring. @@ -1882,6 +1906,21 @@ impl ProbeStream { stream.writer.buffer(&lite::ControlType::Probe)?; wait!(Send => stream.writer.poll_flush(waiter))?; Poll::Ready(wait!(Read => { + // Deliver the target without holding up the estimates behind it. Only a flushed + // writer takes the next one, so a peer that stops reading holds one target, and + // the latest is sent once it drains. + if let Poll::Ready(res) = stream.writer.poll_flush(waiter) { + res?; + if target != self.sent { + // Zero reads as unknown on the wire, which retracts the last target. + let bitrate = (target > bandwidth::Rate::ZERO).then_some(target.as_bps()); + stream.writer.buffer(&lite::Probe { bitrate, rtt: None })?; + self.sent = target; + if let Poll::Ready(res) = stream.writer.poll_flush(waiter) { + res?; + } + } + } let bandwidth = self.subscriber.recv_bandwidth.as_ref().expect("gated by RecvBandwidth"); // Each estimate wakes every reader, so a peer streaming them must not hold // the session's other tasks. diff --git a/rs/moq-net/src/model/bandwidth.rs b/rs/moq-net/src/model/bandwidth.rs index 211b8c06e1c..46017b658ad 100644 --- a/rs/moq-net/src/model/bandwidth.rs +++ b/rs/moq-net/src/model/bandwidth.rs @@ -11,6 +11,10 @@ //! The same reservations set the connection's probe target: their ceilings summed, //! which the session hands to its transport's [`Probe`](crate::transport::Probe) so //! the estimate can rise to fund them. +//! +//! The receive direction mirrors it: [Viewers] divides the receive estimate among the +//! broadcasts watched over one connection, and their ceilings summed are the PROBE +//! target the session asks its peer to probe up to. use std::{ collections::BTreeMap, @@ -21,7 +25,7 @@ use std::{ task::{Poll, Wake, Waker}, }; -use crate::{Error, Result, track}; +use crate::{BoundsExceeded, Error, Result, track}; /// A rate, in bits per second. /// @@ -117,7 +121,6 @@ impl Producer { } /// A handle that mints consumers without being one, so holding it is not demand. - #[cfg_attr(not(feature = "async"), allow(dead_code, reason = "async-only"))] pub fn weak(&self) -> Weak { Weak(self.state.weak()) } @@ -196,12 +199,10 @@ impl Default for Producer { /// Mints [`Consumer`]s on demand without counting as one, nor keeping the channel open. #[derive(Clone)] -#[cfg_attr(not(feature = "async"), allow(dead_code, reason = "async-only"))] pub struct Weak(kio::ProducerWeak); impl Weak { /// A new consumer, which reports the closure once the producer is gone. - #[cfg_attr(not(feature = "async"), allow(dead_code, reason = "async-only"))] pub fn consume(&self) -> Consumer { Consumer { inner: Inner::Whole(self.0.consume()), @@ -266,15 +267,26 @@ impl Allocator { /// Probe up to `target` instead of the sum of the reservations, or `None` to follow them again. /// - /// `Some(Rate::ZERO)` turns probing off. The override is the registry's, so it holds - /// for every clone and across the reconnects a persistent allocator spans. + /// The override covers these reservations only: `Some(Rate::ZERO)` stops probing for + /// them, but a session still probes up to the PROBE target its peer sends, since it + /// probes to the larger of the two. The override is the registry's, so it holds for + /// every clone and across the reconnects a persistent allocator spans. pub fn set_target(&self, target: Option) { + if self.retarget(target).is_err() { + unreachable!("an allocator's registry has no limit") + } + } + + /// Override the target, refusing one above the registry's limit. + fn retarget(&self, target: Option) -> Result<()> { let Ok(mut registry) = self.registry.write() else { unreachable!("the allocator holds its own registry producer") }; + registry.fits(target.map_or(0, |target| u128::from(target.as_bps())))?; if registry.target != target { registry.target = target; } + Ok(()) } /// Follow the probe target, for the session that probes on the reservations' behalf. @@ -351,9 +363,17 @@ impl Allocator { pub fn reserve(&self, track: &track::Demand, max: Rate) -> Reservation { // Read the track before taking the registry lock, so the two are never held // at once and there's no order to get wrong. - let priority = track.priority(); - let demand = track.clone(); + let claimed = self.claim(self.estimate.clone(), Some(track.clone()), track.priority(), max); + let Ok(reservation) = claimed else { + unreachable!("an allocator's registry has no limit") + }; + reservation + } + /// Claim up to `max` of `estimate`, active whenever `demand` is, or always without one. + /// + /// Errors without claiming when the ceilings would sum above the registry's limit. + fn claim(&self, estimate: Consumer, demand: Option, priority: i8, max: Rate) -> Result { let (id, grants) = { // Nothing ever closes this channel: the allocator holds the only producer // and never aborts it, so it's open for as long as `self` is. @@ -365,12 +385,13 @@ impl Allocator { let closed: Vec = registry .entries .iter() - .filter(|(_, entry)| entry.demand.is_closed()) + .filter(|(_, entry)| entry.demand.as_ref().is_some_and(track::Demand::is_closed)) .map(|(id, _)| *id) .collect(); for id in closed { registry.remove(id); } + registry.fits(registry.reserved + u128::from(max.as_bps()))?; let id = registry.next_id; registry.next_id += 1; @@ -380,15 +401,15 @@ impl Allocator { (id, registry.grants.clone()) }; - Reservation { + Ok(Reservation { share: Share { - estimate: self.estimate.clone(), + estimate, registry: self.registry.consume(), grants, id, }, registry: self.registry.downgrade(), - } + }) } } @@ -438,18 +459,28 @@ impl Reservation { /// Does nothing once every [`Allocator`] is gone, since there is then nothing left /// dividing anything; a reader learns that from its [`consumer`](Self::consume). pub fn update(&self, max: Rate) { + if self.resize(max).is_err() { + unreachable!("an allocator's registry has no limit") + } + } + + /// Change the ceiling, refusing one that would sum above the registry's limit. + fn resize(&self, max: Rate) -> Result<()> { let Some(registry) = self.registry.upgrade() else { - return; + return Ok(()); }; let Ok(mut registry) = registry.write() else { - return; + return Ok(()); }; let registry = &mut *registry; if let Some(entry) = registry.entries.get_mut(&self.share.id) { - registry.reserved = registry.reserved - u128::from(entry.max.as_bps()) + u128::from(max.as_bps()); + let reserved = registry.reserved - u128::from(entry.max.as_bps()) + u128::from(max.as_bps()); + within(registry.limit, reserved)?; + registry.reserved = reserved; registry.generation += 1; entry.max = max; } + Ok(()) } } @@ -483,6 +514,169 @@ impl std::fmt::Debug for Allocator { } } +/// Divides one connection's receive estimate among the broadcasts watched over it. +/// +/// The receive-side mirror of [`Allocator`]. Every player on a connection reads the +/// same receive estimate, so N players each selecting against all of it oversubscribe +/// the downlink N times over. [`watch`](Self::watch) a broadcast here and its +/// [`Viewer`] reports only its own slice, split max-min fair by each viewer's ceiling, +/// so the slices sum to the estimate instead of each matching it. Viewers carry no +/// priority: a viewer asking for less than an even cut takes all it asked for and +/// leaves the rest to the others. +/// +/// The viewers' ceilings summed are also the PROBE target the session sends its +/// peer, which probes the connection up to it when it advertised `Increase`, so the +/// estimate can rise to fund a larger rendition. The target never leaves this hop: +/// a relay probes its own downlink for its viewers, and never forwards them upstream. +/// +/// The ceilings may sum to at most [`MAX_TARGET`](Self::MAX_TARGET), which every PROBE +/// encoding carries: a viewer or override that would pass it is refused with +/// [`Error::BoundsExceeded`]. +/// +/// Holding a [`Viewer`] (or a [`Consumer`] read from one) requests PROBE, like +/// holding `Session::recv_bandwidth`. Take it from `Session::viewers` (with the +/// `async` feature) rather than building one, since only a session sends the target. +/// Clones share one registry. +#[derive(Clone)] +pub struct Viewers { + /// The registry, whose own estimate is unused: each viewer reads one minted from + /// `estimate`, so holding the registry is not demand. + registry: Allocator, + /// Mints the receive estimate each viewer reads, or `None` when there is none. + estimate: Option, +} + +impl Viewers { + /// The largest PROBE target: the most the viewers' ceilings, summed, or an override may be. + /// + /// `2^53 - 1` bits per second, the largest integer a JavaScript peer decodes exactly, + /// and well inside the wire's varint. + pub const MAX_TARGET: Rate = Rate::from_bps((1 << 53) - 1); + + /// Divide the receive estimate `estimate` mints, with no session sending the target. + /// + /// For an estimate that outlives a session, such as one a reconnect loop feeds + /// from each session it dials. Hand the same registry to `Client::with_viewers` + /// (with the `async` feature) so every session it dials sends the target. + pub fn new(estimate: Weak) -> Self { + Self { + estimate: Some(estimate), + ..Self::default() + } + } + + /// The same registry dividing the estimate `estimate` mints instead, or nothing when it is `None`. + #[cfg(feature = "async")] + pub(crate) fn with_estimate(&self, estimate: Option) -> Self { + Self { + registry: self.registry.clone(), + estimate, + } + } + + /// Watch a broadcast receiving at most `max`, returning its viewer. + /// + /// `max` is a ceiling: what the largest rendition the player would switch to + /// needs, not what it happens to be receiving. The claim lasts as long as the + /// returned [`Viewer`]: change the ceiling with [`update`](Viewer::update), and drop + /// it once the broadcast stops being watched. + /// + /// # Errors + /// + /// [`Error::BoundsExceeded`], watching nothing, when the ceilings would sum above + /// [`MAX_TARGET`](Self::MAX_TARGET). + pub fn watch(&self, max: Rate) -> Result { + let estimate = match &self.estimate { + Some(estimate) => estimate.consume(), + None => Consumer { + inner: Inner::Unavailable, + last: None, + probed: false, + }, + }; + Ok(Viewer(self.registry.claim(estimate, None, 0, max)?)) + } + + /// Send `target` as the PROBE target instead of the viewers' sum, or `None` to follow them again. + /// + /// `Some(Rate::ZERO)` sends no target, so the peer stops probing for these viewers. The + /// override is the registry's, so it holds for every clone and across the reconnects a + /// persistent registry spans. + /// + /// # Errors + /// + /// [`Error::BoundsExceeded`], keeping the previous override, for a target above + /// [`MAX_TARGET`](Self::MAX_TARGET). + pub fn set_target(&self, target: Option) -> Result<()> { + self.registry.retarget(target) + } + + /// Follow the PROBE target, for the session that sends it to a peer that probes up to it. + /// + /// Holding it is what marks the viewers [`probed`](Consumer::probed). + #[cfg(any(feature = "async", test))] + pub(crate) fn target(&self) -> Target { + self.registry.target() + } +} + +/// No receive estimate to divide, with the PROBE target's limit. +impl Default for Viewers { + fn default() -> Self { + let registry = Allocator::unlimited(); + if let Ok(mut state) = registry.registry.write() { + state.limit = Some(Self::MAX_TARGET); + } + Self { + registry, + estimate: None, + } + } +} + +// Hand-written so the config structs that carry a registry can still derive `Debug`. +impl std::fmt::Debug for Viewers { + fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { + f.debug_struct("Viewers") + .field("watched", &self.registry.registry.read().entries.len()) + .finish() + } +} + +/// One watched broadcast's standing claim on [`Viewers`], held for as long as it is watched. +/// +/// Holding it requests PROBE. Dropping it releases the claim and lowers the PROBE target. +#[must_use = "a dropped Viewer is released, so the broadcast claims nothing and the PROBE target drops"] +pub struct Viewer(Reservation); + +impl Viewer { + /// This viewer's slice of the receive estimate right now. + /// + /// `None` while the connection has no receive estimate, telling a player to hold its + /// current selection. + pub fn rate(&self) -> Option { + self.0.rate() + } + + /// A handle reading this viewer's current slice of the receive estimate. + /// + /// Cloneable and independent of the viewer: once the viewer is dropped these report + /// `None`. [`Consumer::probed`] reports whether the peer is asked to probe for it. + pub fn consume(&self) -> Consumer { + self.0.consume() + } + + /// Change the ceiling, keeping the same claim, as when a catalog enables or disables a rendition. + /// + /// # Errors + /// + /// [`Error::BoundsExceeded`], keeping the previous ceiling, when the ceilings would + /// sum above [`Viewers::MAX_TARGET`]. + pub fn update(&self, max: Rate) -> Result<()> { + self.0.resize(max) + } +} + /// Every track registered with one [`Allocator`]. #[derive(Default)] struct Registry { @@ -494,6 +688,8 @@ struct Registry { reserved: u128, /// The application's override of `reserved` as the probe target. target: Option, + /// The most `reserved` and `target` may each be, or `None` for no limit. + limit: Option, /// How many sessions probe for these reservations, each through its [`Target`]. probes: usize, /// Bumped whenever an entry is added, moved or removed, so a [`Plan`] knows the @@ -511,6 +707,11 @@ impl Registry { } } + /// Refuse `total` when it is above the registry's limit. + fn fits(&self, total: u128) -> Result<()> { + within(self.limit, total) + } + /// What the session probes up to. fn target(&self) -> Rate { self.target @@ -518,9 +719,18 @@ impl Registry { } } +/// Refuse `total` when it is above `limit`. +fn within(limit: Option, total: u128) -> Result<()> { + match limit { + Some(limit) if total > u128::from(limit.as_bps()) => Err(Error::BoundsExceeded(BoundsExceeded)), + _ => Ok(()), + } +} + /// One registered track's standing reservation. struct Entry { - demand: track::Demand, + /// The track whose demand gates the claim, or `None` for a claim that is always active. + demand: Option, priority: i8, max: Rate, } @@ -600,8 +810,9 @@ impl Share { self.grants.grant(&self.registry, estimate, self.id) } - /// Whether a session probes for this share's registry, toward a target above zero, - /// which turns probing off. + /// Whether a session probes for this share's registry, toward a target above zero. + /// A zero target stops probing for these claims, though the session may still probe + /// for its peer's target. fn probed(&self) -> bool { let registry = self.registry.read(); registry.probes > 0 && registry.target() > Rate::ZERO @@ -778,7 +989,7 @@ impl Plan { /// divide `estimate` among them. fn new(registry: &kio::Consumer, watch: &Arc, estimate: Rate, epoch: u64) -> Self { // Snapshot the registry so the tracks can be read without holding its lock. - let (generation, claims): (u64, Vec<(Want, track::Demand)>) = { + let (generation, claims): (u64, Vec<(Want, Option)>) = { let registry = registry.read(); let claims = registry .entries @@ -800,7 +1011,7 @@ impl Plan { .into_iter() .map(|(want, demand)| Planned { want, - state: demand.poll_state(&waiter), + state: demand.map_or(track::DemandState::Active, |demand| demand.poll_state(&waiter)), grant: 0, }) .collect(); @@ -930,8 +1141,10 @@ impl Consumer { /// Whether a session probes the connection for this slice's reservation, so the /// estimate can rise to fund it even while its sender is stopped. /// - /// Only a session whose transport has a sender probes, and none does while - /// [`Allocator::set_target`] turns probing off. Without one the estimate + /// Only a session whose transport has a sender probes, and none does for it while + /// [`Allocator::set_target`] overrides the target to zero. For a [`Viewer`]'s slice, + /// whether the session asks a peer that advertised `Increase` to probe for it, which + /// [`Viewers::set_target`] can turn off the same way. Without one the estimate /// stops learning once the connection is app-limited, so a sender that stops for /// lack of bandwidth could never see enough to resume. Always `false` for a whole /// estimate, which no reservation backs. [`poll_changed`](Self::poll_changed) @@ -1688,4 +1901,102 @@ mod tests { allocator.set_target(None); assert_eq!(target.poll_changed(&waiter), Poll::Ready(bps(4_000_000))); } + + /// Several broadcasts on one connection each read their own slice of the receive + /// estimate, max-min fair by ceiling, so together they never claim more than it. + #[test] + fn viewers_split_the_estimate_max_min_fair() { + let estimate = Producer::new(); + let viewers = Viewers::new(estimate.weak()); + let small = viewers.watch(bps(1_000_000)).unwrap(); + let large = viewers.watch(bps(8_000_000)).unwrap(); + assert_eq!(small.rate(), None, "no estimate yet: hold the selection"); + + estimate.set(Some(bps(6_000_000))).unwrap(); + assert_eq!(small.rate(), Some(bps(1_000_000))); + assert_eq!(large.rate(), Some(bps(5_000_000))); + + let third = viewers.watch(bps(4_000_000)).unwrap(); + let grants = [&small, &large, &third].map(|viewer| viewer.rate().unwrap()); + assert_eq!(grants, [bps(1_000_000), bps(2_500_000), bps(2_500_000)]); + assert!(grants.iter().map(|rate| rate.as_bps()).sum::() <= 6_000_000); + + // A viewer that leaves hands its slice back. + drop(third); + assert_eq!(large.rate(), Some(bps(5_000_000))); + } + + /// The PROBE target sums every live viewer's ceiling until overridden. + #[test] + fn the_viewers_target_sums_their_ceilings() { + let viewers = Viewers::default(); + let mut target = viewers.target(); + let waiter = kio::Waiter::noop(); + assert_eq!(target.poll_changed(&waiter), Poll::Ready(Rate::ZERO)); + + let first = viewers.watch(bps(3_000_000)).unwrap(); + let second = viewers.clone().watch(bps(2_000_000)).unwrap(); + assert_eq!(target.poll_changed(&waiter), Poll::Ready(bps(5_000_000))); + first.update(bps(1_000_000)).unwrap(); + assert_eq!(target.poll_changed(&waiter), Poll::Ready(bps(3_000_000))); + + viewers.set_target(Some(Rate::ZERO)).unwrap(); + assert_eq!(target.poll_changed(&waiter), Poll::Ready(Rate::ZERO)); + viewers.set_target(None).unwrap(); + assert_eq!(target.poll_changed(&waiter), Poll::Ready(bps(3_000_000))); + + drop(second); + assert_eq!(target.poll_changed(&waiter), Poll::Ready(bps(1_000_000))); + drop(first); + assert_eq!(target.poll_changed(&waiter), Poll::Ready(Rate::ZERO)); + } + + /// The viewers' ceilings sum to at most what every PROBE encoding carries: a viewer, + /// update, or override past it is refused and leaves the target as it was. + #[test] + fn viewer_targets_stay_encodable() { + let viewers = Viewers::default(); + let mut target = viewers.target(); + let waiter = kio::Waiter::noop(); + let max = Viewers::MAX_TARGET.as_bps(); + let bounds = |res: Result<()>| matches!(res, Err(Error::BoundsExceeded(_))); + + assert!(bounds(viewers.watch(bps(max + 1)).map(drop))); + let first = viewers.watch(bps(max - 1)).unwrap(); + assert!(bounds(viewers.watch(bps(2)).map(drop)), "the sum would pass the limit"); + let second = viewers.watch(bps(1)).unwrap(); + assert_eq!(target.poll_changed(&waiter), Poll::Ready(Viewers::MAX_TARGET)); + + assert!(bounds(second.update(bps(2)))); + first.update(bps(1)).unwrap(); + assert_eq!(target.poll_changed(&waiter), Poll::Ready(bps(2))); + second.update(bps(max - 1)).unwrap(); + assert_eq!(target.poll_changed(&waiter), Poll::Ready(Viewers::MAX_TARGET)); + + viewers.set_target(Some(bps(1_000_000))).unwrap(); + assert!(bounds(viewers.set_target(Some(bps(max + 1))))); + assert_eq!(target.poll_changed(&waiter), Poll::Ready(bps(1_000_000))); + viewers.set_target(Some(Viewers::MAX_TARGET)).unwrap(); + assert_eq!(target.poll_changed(&waiter), Poll::Ready(Viewers::MAX_TARGET)); + } + + /// A held viewer is what requests the receive estimate (and so PROBE); the registry + /// alone is not, so a session holding one opens no PROBE stream. + #[test] + fn a_viewer_requests_the_estimate() { + let estimate = Producer::new(); + let viewers = Viewers::new(estimate.weak()); + assert!(!estimate.demand().wanted()); + + let viewer = viewers.watch(bps(1_000_000)).unwrap(); + assert!(estimate.demand().wanted()); + let grant = viewer.consume(); + drop(viewer); + assert!( + estimate.demand().wanted(), + "a grant read from the viewer still wants it" + ); + drop(grant); + assert!(!estimate.demand().wanted()); + } } diff --git a/rs/moq-net/src/server.rs b/rs/moq-net/src/server.rs index 9c7dfe52320..869b79a2021 100644 --- a/rs/moq-net/src/server.rs +++ b/rs/moq-net/src/server.rs @@ -184,11 +184,14 @@ impl Server { lite::Setup::default() }; + // One registry, which the subscriber sends and the session hands out. + let viewers = crate::bandwidth::Viewers::default(); let start = lite::start(lite::Config { runtime: runtime.clone(), stats: self.stats.clone(), client: false, limits: self.limits, + viewers: viewers.clone(), session: session.clone(), setup_stream: None, publish, @@ -212,7 +215,9 @@ impl Server { auth: start.auth, credential: start.credential, estimate: Some(start.estimate), + peer_target: Some(start.peer_target), bandwidth: crate::bandwidth::Allocator::default(), + viewers, peer_implementation: start.peer_implementation, }, )) @@ -552,7 +557,9 @@ impl PausedIetf { auth, credential, estimate: None, + peer_target: None, bandwidth: crate::bandwidth::Allocator::default(), + viewers: Default::default(), peer_implementation, }, )) @@ -596,11 +603,14 @@ impl PausedNegotiated { let stream = stream.with_version(version); // Pre-lite-05: no Setup Stream, so nothing to advertise or seed. + // One registry, which the subscriber sends and the session hands out. + let viewers = crate::bandwidth::Viewers::default(); let start = lite::start(lite::Config { runtime: runtime.clone(), stats: server.stats.clone(), client: false, limits: server.limits, + viewers: viewers.clone(), session: session.clone(), setup_stream: Some(stream), publish, @@ -624,7 +634,9 @@ impl PausedNegotiated { auth: start.auth, credential: start.credential, estimate: Some(start.estimate), + peer_target: Some(start.peer_target), bandwidth: crate::bandwidth::Allocator::default(), + viewers, peer_implementation: start.peer_implementation, }, )) diff --git a/rs/moq-net/src/session.rs b/rs/moq-net/src/session.rs index 51091a09971..2ed971dfe3c 100644 --- a/rs/moq-net/src/session.rs +++ b/rs/moq-net/src/session.rs @@ -169,6 +169,8 @@ pub struct Session { /// unused: [`bandwidth`](Self::bandwidth) mints one per call, so holding the /// session doesn't keep the sampler running. bandwidth: bandwidth::Allocator, + /// The registry whose viewers this session sends its peer as the PROBE target. + viewers: bandwidth::Viewers, goaway: Arc, auth: auth::Handle, credential: Option, @@ -238,6 +240,21 @@ impl Session { self.recv_bandwidth.as_ref().map(bandwidth::Weak::consume) } + /// Divides [`recv_bandwidth`](Self::recv_bandwidth) among the broadcasts watched over this session. + /// + /// The session sends what the viewers add up to as its PROBE target, so a peer that + /// advertised `Increase` probes the connection up to it. Holding a viewer requests + /// PROBE. Clones share one registry: a + /// [`Client::with_viewers`](crate::Client::with_viewers) registry's when the session + /// was dialed with one, so their claims outlive a reconnect, like + /// [`allocator`](Self::allocator)'s. Viewers taken here read this session's + /// estimate, and report `None` once it ends or when the version has no PROBE; take + /// them from the reconnecting handle (`moq_tokio::Connection::viewers`) to read + /// each new session's. + pub fn viewers(&self) -> bandwidth::Viewers { + self.viewers.with_estimate(self.recv_bandwidth.clone()) + } + /// Returns a snapshot of the current connection statistics. /// /// Cheap and non-blocking: this reads the latest sample the session's @@ -410,6 +427,10 @@ pub(super) struct Handles { pub estimate: Option>, /// The reservations the session probes for. pub bandwidth: bandwidth::Allocator, + /// The viewers whose sum the session sends as its PROBE target. + pub viewers: bandwidth::Viewers, + /// The peer's PROBE target, for a protocol that carries one (moq-lite PROBE). + pub peer_target: Option>, /// What the peer's SETUP advertised as its implementation. pub peer_implementation: crate::setup::PeerImplementation, } @@ -430,6 +451,8 @@ impl Session { estimate, stats: context, bandwidth, + viewers, + peer_target, peer_implementation, } = handles; let goaway = Arc::new(goaway); @@ -454,7 +477,12 @@ impl Session { }; // Without a sender there is nothing to hand the target to, so don't follow it. - let probe = session.probe().map(|probe| (probe, bandwidth.target())); + let probe = session.probe().map(|sender| Probing { + sender, + local: bandwidth.target(), + peer: peer_target, + targets: (bandwidth::Rate::ZERO, bandwidth::Rate::ZERO), + }); let close = kio::Producer::new(None); let closed = kio::Producer::new(None); @@ -494,6 +522,7 @@ impl Session { send_bandwidth, recv_bandwidth, bandwidth, + viewers, goaway, auth: auth.handle().clone(), credential, @@ -540,8 +569,8 @@ pub(crate) struct Supervisor { send_bandwidth: Option, /// Published on change while a consumer exists; see [`Self::poll_sampler`]. estimate: Option>, - /// The transport's sender and the target it is handed, when it has one. - probe: Option<(crate::transport::Probe, bandwidth::Target)>, + /// The transport's sender and the targets it probes up to, when it has one. + probe: Option, /// When the last sample was taken. sampled: Option, mode: SamplerMode, @@ -553,6 +582,52 @@ pub(crate) struct Supervisor { auth: auth::Link, } +/// A transport's sender and the two targets it probes up to, whichever is larger. +/// +/// The directions never mix: these are both rates this side sends at, its own +/// reservations' and what the peer asks to receive. What this side wants to receive +/// goes to the peer instead, as its PROBE target. +struct Probing { + sender: crate::transport::Probe, + /// This side's reservations. + local: bandwidth::Target, + /// The peer's PROBE target, when the protocol carries one. `None` once it is gone. + peer: Option>, + /// The last local and peer targets read. + targets: (bandwidth::Rate, bandwidth::Rate), +} + +impl Probing { + fn poll(&mut self, waiter: &kio::Waiter) { + while let Poll::Ready(local) = self.local.poll_changed(waiter) { + self.targets.0 = local; + } + // Loop until pending, so the waiter stays armed for the next change. + while let Some(peer) = &self.peer { + let last = self.targets.1; + let polled = peer.poll(waiter, |rate| match **rate != last { + true => Poll::Ready(**rate), + false => Poll::Pending, + }); + match polled.map(|res| res.ok()) { + Poll::Ready(Some(rate)) => self.targets.1 = rate, + // The protocol stopped reading the peer; nothing it asked for still holds. + Poll::Ready(None) => { + self.targets.1 = bandwidth::Rate::ZERO; + self.peer = None; + } + Poll::Pending => break, + } + } + // The peer's target is untrusted, but only sets how high to probe: each probe + // scales the current estimate and stays under congestion control. + let target = self.targets.0.max(self.targets.1); + if self.sender.target() != target { + self.sender.set_target(target); + } + } +} + /// A [`Session::close`] waiting for the protocol to deliver what it queued. enum Drain { /// Nobody asked for one. @@ -679,10 +754,8 @@ impl Supervisor { self.poll_sampler(waiter); - if let Some((probe, target)) = &mut self.probe { - while let Poll::Ready(target) = target.poll_changed(waiter) { - probe.set_target(target); - } + if let Some(probe) = &mut self.probe { + probe.poll(waiter); } Poll::Pending diff --git a/rs/moq-net/tests/integration/main.rs b/rs/moq-net/tests/integration/main.rs index 43d70c43bf5..21a710fc538 100644 --- a/rs/moq-net/tests/integration/main.rs +++ b/rs/moq-net/tests/integration/main.rs @@ -81,6 +81,7 @@ mod tracks; mod tracks_ietf; mod unannounce_release; mod untimed; +mod viewer_target; mod warm_backfill; mod wide_hop; mod wide_sequence; diff --git a/rs/moq-net/tests/integration/support/harness.rs b/rs/moq-net/tests/integration/support/harness.rs index bcfb15d6d45..5941243f948 100644 --- a/rs/moq-net/tests/integration/support/harness.rs +++ b/rs/moq-net/tests/integration/support/harness.rs @@ -92,6 +92,8 @@ pub struct MockConnectOptions { pub cost: Option, /// What both transports report as their connection statistics. pub stats: MockStats, + /// Whether both transports have a sender that probes up to a target. + pub probe: bool, /// The context the server records under. pub server_stats: moq_net::stats::Session, /// Count server driver polls into this counter when supplied. @@ -125,6 +127,7 @@ impl MockConnectOptions { server_extensions: Default::default(), cost: None, stats: MockStats::default(), + probe: false, server_stats: Default::default(), server_polls: None, client_discovers_all: true, @@ -165,6 +168,8 @@ pub async fn connect_mock(opts: MockConnectOptions) -> MockPair { client_transport.set_latency(opts.latency); client_transport.set_stats(opts.stats); server_transport.set_stats(opts.stats); + client_transport.set_probe(opts.probe); + server_transport.set_probe(opts.probe); let transports = (client_transport.clone(), server_transport.clone()); let mut client = Client::new() diff --git a/rs/moq-net/tests/integration/support/mock.rs b/rs/moq-net/tests/integration/support/mock.rs index 5de67580b38..7f3351e0855 100644 --- a/rs/moq-net/tests/integration/support/mock.rs +++ b/rs/moq-net/tests/integration/support/mock.rs @@ -462,6 +462,10 @@ struct Side { panic_on_stats: AtomicBool, /// The wire counters [`poll::Session::wire`] exposes, which a test updates as a transport would. wire: moq_net::transport::Wire, + /// Whether [`poll::Session::probe`] reports a sender; see [`MockSession::set_probe`]. + probing: AtomicBool, + /// The sender's target, which the session sets. + probe: moq_net::transport::Probe, /// What [`poll::Session::receive_window`] reports instead of the memory transport's, if set. receive_window: Mutex>>, } @@ -657,6 +661,13 @@ impl poll::Session for MockSession { Some(self.side.wire.clone()) } + fn probe(&self) -> Option { + self.side + .probing + .load(Ordering::Relaxed) + .then(|| self.side.probe.clone()) + } + fn receive_window(&self) -> Option { match *self.side.receive_window.lock().unwrap() { Some(window) => window, @@ -696,6 +707,16 @@ impl MockSession { *self.side.stats.lock().unwrap() = stats; } + /// Report a sender from now on, which a session reads once as it starts. + pub fn set_probe(&self, probing: bool) { + self.side.probing.store(probing, Ordering::Relaxed); + } + + /// The target the session hands this side's sender, or zero without one. + pub fn probe_target(&self) -> moq_net::bandwidth::Rate { + self.side.probe.target() + } + /// Report `window` as the receive windows in force, as a transport whose limits changed. pub fn set_receive_window(&self, window: Option) { *self.side.receive_window.lock().unwrap() = Some(window); @@ -940,6 +961,8 @@ pub fn create_mock_session_pair(config: memory::Config) -> (MockSession, MockSes panic_on_stats: Default::default(), receive_window: Default::default(), wire: Default::default(), + probing: Default::default(), + probe: Default::default(), }), }; diff --git a/rs/moq-net/tests/integration/viewer_target.rs b/rs/moq-net/tests/integration/viewer_target.rs new file mode 100644 index 00000000000..583fcb5b934 --- /dev/null +++ b/rs/moq-net/tests/integration/viewer_target.rs @@ -0,0 +1,156 @@ +#![cfg(feature = "async")] + +//! A session sends its viewers' sum to the peer as the PROBE target, and a sending +//! session probes to the larger of its own reservations and the peer's target. + +use crate::support; + +use std::time::Duration; + +use moq_net::{Version, bandwidth::Rate, broadcast, track}; +use support::harness::{MockConnectOptions, MockPair, connect_mock}; +use support::mock::{MockSession, MockStats}; + +/// The versions whose SETUP carries the probe level a target is gated on. +const VERSIONS: [&str; 2] = ["moq-lite-06", "moq-lite-07-wip"]; + +const STATS: MockStats = MockStats { + estimated_send_rate: Some(10_000_000), + rtt: Some(Duration::from_millis(40)), +}; + +/// A connected pair, each side with a sender when `probe`. +async fn pair(version: &str, probe: bool) -> MockPair { + let mut options = MockConnectOptions::new(version.parse::().unwrap()); + options.stats = STATS; + options.probe = probe; + connect_mock(options).await +} + +fn mbps(n: u64) -> Rate { + Rate::from_mbps(n) +} + +/// Run until `transport`'s sender is handed `target`. +async fn probes_to(transport: &MockSession, target: Rate) { + while transport.probe_target() != target { + moq_net::kio::clock::sleep(Duration::from_millis(1)).await; + } +} + +/// A track to reserve for, plus the broadcast keeping it alive. +fn reservable() -> (broadcast::Producer, track::Producer) { + let broadcast = broadcast::Info::default().produce(); + let track = broadcast.create_track("t", None).unwrap(); + (broadcast, track) +} + +#[moq_net::kio::test] +async fn viewers_sum_into_the_peers_target() { + for version in VERSIONS { + let pair = pair(version, true).await; + let viewers = pair.client.viewers(); + + let first = viewers.watch(mbps(3)).unwrap(); + probes_to(&pair.server_transport, mbps(3)).await; + let second = viewers.watch(mbps(2)).unwrap(); + probes_to(&pair.server_transport, mbps(5)).await; + first.update(mbps(1)).unwrap(); + probes_to(&pair.server_transport, mbps(3)).await; + + drop(second); + probes_to(&pair.server_transport, mbps(1)).await; + // The last viewer releases the PROBE stream, and the target lapses with it. + drop(first); + probes_to(&pair.server_transport, Rate::ZERO).await; + } +} + +#[moq_net::kio::test] +async fn the_sender_probes_to_the_larger_target() { + for version in VERSIONS { + let pair = pair(version, true).await; + let (_broadcast, track) = reservable(); + let reserved = pair.server.allocator().reserve(&track.demand(), mbps(4)); + probes_to(&pair.server_transport, mbps(4)).await; + + let viewer = pair.client.viewers().watch(mbps(6)).unwrap(); + probes_to(&pair.server_transport, mbps(6)).await; + viewer.update(mbps(2)).unwrap(); + probes_to(&pair.server_transport, mbps(4)).await; + drop(reserved); + probes_to(&pair.server_transport, mbps(2)).await; + } +} + +/// The sender's override covers its own reservations only: zeroing it stops probing +/// for them, while the peer's target still sets how high to probe. +#[moq_net::kio::test] +async fn a_local_override_leaves_the_peers_target() { + for version in VERSIONS { + let pair = pair(version, true).await; + let (_broadcast, track) = reservable(); + let allocator = pair.server.allocator(); + let reserved = allocator.reserve(&track.demand(), mbps(4)); + allocator.set_target(Some(Rate::ZERO)); + + let viewer = pair.client.viewers().watch(mbps(2)).unwrap(); + probes_to(&pair.server_transport, mbps(2)).await; + assert!( + !reserved.consume().probed(), + "{version}: nothing probes for the reservation" + ); + drop(viewer); + probes_to(&pair.server_transport, Rate::ZERO).await; + } +} + +/// A session that publishes and watches probes its uplink for what it sends, never +/// for what it watches, and its peer the other way around. +#[moq_net::kio::test] +async fn the_directions_stay_apart() { + for version in VERSIONS { + let pair = pair(version, true).await; + let (_broadcast, track) = reservable(); + let _sent = pair.client.allocator().reserve(&track.demand(), mbps(1)); + let _watched = pair.client.viewers().watch(mbps(6)).unwrap(); + + probes_to(&pair.client_transport, mbps(1)).await; + probes_to(&pair.server_transport, mbps(6)).await; + moq_net::kio::clock::sleep(Duration::from_secs(1)).await; + assert_eq!(pair.client_transport.probe_target(), mbps(1), "{version}"); + assert_eq!(pair.server_transport.probe_target(), mbps(6), "{version}"); + } +} + +#[moq_net::kio::test] +async fn opting_out_sends_no_target() { + for version in VERSIONS { + let pair = pair(version, true).await; + let viewers = pair.client.viewers(); + viewers.set_target(Some(Rate::ZERO)).unwrap(); + let viewer = viewers.watch(mbps(6)).unwrap(); + let mut grant = viewer.consume(); + // The estimate arrives, so the PROBE stream is up and the target would have too. + assert_eq!(grant.changed().await.unwrap(), Some(mbps(6)), "{version}"); + moq_net::kio::clock::sleep(Duration::from_secs(1)).await; + assert_eq!(pair.server_transport.probe_target(), Rate::ZERO, "{version}"); + assert!(!grant.probed(), "{version}: opted out, nothing probes for it"); + + viewers.set_target(None).unwrap(); + probes_to(&pair.server_transport, mbps(6)).await; + assert!(grant.probed(), "{version}"); + } +} + +/// A peer without a sender advertises `Report`, so its viewers are never probed for. +#[moq_net::kio::test] +async fn a_peer_without_a_sender_is_sent_no_target() { + for version in VERSIONS { + let pair = pair(version, false).await; + let viewer = pair.client.viewers().watch(mbps(6)).unwrap(); + let mut grant = viewer.consume(); + assert_eq!(grant.changed().await.unwrap(), Some(mbps(6)), "{version}"); + assert!(!grant.probed(), "{version}"); + } +} diff --git a/rs/moq-tokio/src/client.rs b/rs/moq-tokio/src/client.rs index ff542619839..c6a45b49098 100644 --- a/rs/moq-tokio/src/client.rs +++ b/rs/moq-tokio/src/client.rs @@ -224,6 +224,12 @@ impl Client { self } + /// Share `viewers` with every session this client dials. + pub(crate) fn with_viewers(mut self, viewers: moq_net::bandwidth::Viewers) -> Self { + self.moq = self.moq.with_viewers(viewers); + self + } + /// Price the links this client dials; see [`moq_net::Client::with_cost`]. pub fn with_cost(mut self, cost: u64) -> Self { self.moq = self.moq.with_cost(cost); diff --git a/rs/moq-tokio/src/connection.rs b/rs/moq-tokio/src/connection.rs index 4cf3ea1d8ec..ec6d9d1f98d 100644 --- a/rs/moq-tokio/src/connection.rs +++ b/rs/moq-tokio/src/connection.rs @@ -945,6 +945,8 @@ pub struct Connection { bandwidth: moq_net::bandwidth::Allocator, /// Persistent recv-bitrate estimate, fed by the loop from each live session. recv_bandwidth: moq_net::bandwidth::Weak, + /// Divides `recv_bandwidth`, and every session the loop dials sends its viewers' target. + viewers: moq_net::bandwidth::Viewers, /// The last status returned by [`status`](Self::status), for change detection. /// Per-clone: a clone starts from its parent's cursor and diverges from there. last_reported: Option, @@ -989,7 +991,8 @@ impl Connection { let send_bandwidth = send_bw.consume(); let recv_bandwidth = recv_bw.weak(); let bandwidth = moq_net::bandwidth::Allocator::new(send_bandwidth.clone()); - let client = client.with_allocator(bandwidth.clone()); + let viewers = moq_net::bandwidth::Viewers::new(recv_bandwidth.clone()); + let client = client.with_allocator(bandwidth.clone()).with_viewers(viewers.clone()); let closed: CloseGuard = Default::default(); let task_closed = closed.clone(); @@ -1037,6 +1040,7 @@ impl Connection { send_bandwidth, recv_bandwidth, bandwidth, + viewers, last_reported: None, } } @@ -1571,6 +1575,15 @@ impl Connection { self.recv_bandwidth.consume() } + /// Divides [`recv_bandwidth`](Self::recv_bandwidth) among the broadcasts watched over + /// this connection, mirroring [`moq_net::Session::viewers`]. + /// + /// Persistent like the estimate: every session the loop dials sends these viewers' + /// target, so they survive reconnects. Viewers report `None` while disconnected. + pub fn viewers(&self) -> moq_net::bandwidth::Viewers { + self.viewers.clone() + } + /// Poll whether the connection loop has stopped. /// /// `Ready(Err)` if it permanently gave up (reconnect timeout exceeded, an auth diff --git a/swift/MIGRATE.md b/swift/MIGRATE.md index 6e98d5c51a3..86895a6576a 100644 --- a/swift/MIGRATE.md +++ b/swift/MIGRATE.md @@ -4,6 +4,10 @@ How to update your code for each breaking change, newest first. ## Unreleased +### Viewer targets are bounded ([#7090](https://github.com/moq-dev/moq/pull/7090)) + +Viewer ceilings and PROBE target overrides are refused with the new `MoqError.OutOfRange` once they would sum above 2^53 - 1 bps, the most a PROBE target carries; nothing changes on a refusal. `Viewers.watch(maxBps:)` and `setTarget(targetBps:)` and `Viewer.update(maxBps:)` throw it, so call them with `try`. Handle the new variant wherever you match the error exhaustively. Regenerate bindings and rebuild the matching native library together. + ### `lower` is a `Media.Producer` ([#7699](https://github.com/moq-dev/moq/pull/7699)) `Media.TrackProducer.video` and `Media.TrackStreamProducer.video` take `lower: Media.Producer?` instead of `TrackProducer?`. Pass `lower: .track(producer)`, or `.stream(producer)` for a byte-stream rendition. diff --git a/swift/Sources/Moq/Bandwidth.swift b/swift/Sources/Moq/Bandwidth.swift index 71abf536bee..69b1313d297 100644 --- a/swift/Sources/Moq/Bandwidth.swift +++ b/swift/Sources/Moq/Bandwidth.swift @@ -59,6 +59,58 @@ public final class Reservation: Sendable { } } +/// Divides one connection's receive estimate among the broadcasts watched over it. +/// +/// Minted by `Session.viewers`. Handles from the same session share one registry. +public final class Viewers: Sendable { + let ffi: MoqViewers + + init(_ ffi: MoqViewers) { + self.ffi = ffi + } + + /// Watch a broadcast receiving at most `maxBps`, returning its viewer. + /// + /// `maxBps` is a ceiling: what the largest rendition the player would switch to + /// needs, not what it is receiving. Drop the viewer once the broadcast stops being + /// watched. Holding one requests the receive estimate, like `Session.recvBandwidth()`. + /// Throws `MoqError.OutOfRange`, watching nothing, when the ceilings would sum above + /// `2^53 - 1`. + public func watch(maxBps: UInt64) throws -> Viewer { + Viewer(try ffi.watch(maxBps: maxBps)) + } + + /// Send `targetBps` as the PROBE target instead of the viewers' sum, or `nil` to + /// follow them again. `0` sends no target. Throws `MoqError.OutOfRange`, keeping the + /// previous override, above `2^53 - 1`. + public func setTarget(targetBps: UInt64?) throws { + try ffi.setTarget(targetBps: targetBps) + } +} + +/// One watched broadcast's standing claim on `Viewers`. +/// +/// `rate()` is a snapshot: `nil` means no receive estimate, so hold the current +/// selection, and `0` is a real zero rate. +public final class Viewer: Sendable { + let ffi: MoqViewer + + init(_ ffi: MoqViewer) { + self.ffi = ffi + } + + /// This viewer's slice of the receive estimate right now, in bits per second. + public func rate() -> UInt64? { + ffi.rate() + } + + /// Change the ceiling, keeping the same claim. Throws `MoqError.OutOfRange`, keeping + /// the previous ceiling, when the ceilings would sum above `2^53 - 1`. + public func update(maxBps: UInt64) throws { + try ffi.update(maxBps: maxBps) + } +} + /// What a sender following a ``RateControl`` should be doing. public typealias RateTarget = MoqRateTarget diff --git a/swift/Sources/Moq/Client.swift b/swift/Sources/Moq/Client.swift index 5f02f204266..218e49d3645 100644 --- a/swift/Sources/Moq/Client.swift +++ b/swift/Sources/Moq/Client.swift @@ -173,4 +173,14 @@ public final class Session: Sendable { public func allocator() -> Allocator { Allocator(ffi.allocator()) } + + /// The session's viewers, dividing the receive estimate among watched broadcasts. + /// + /// Every call returns a handle to the same registry, and the session sends what + /// its viewers' ceilings add up to as its PROBE target. A client handle survives + /// reconnects: a viewer reads `nil` while disconnected and resumes on the next + /// connection. + public func viewers() -> Viewers { + Viewers(ffi.viewers()) + } } diff --git a/swift/Tests/MoqTests/SmokeTests.swift b/swift/Tests/MoqTests/SmokeTests.swift index d64681acc35..0d9131a52a8 100644 --- a/swift/Tests/MoqTests/SmokeTests.swift +++ b/swift/Tests/MoqTests/SmokeTests.swift @@ -112,6 +112,27 @@ final class SmokeTests: XCTestCase { } } + /// A viewer on a session that has not connected reads no estimate. + func testViewerHoldsWithoutAnEstimate() async throws { + let client = try Client(bind: "127.0.0.1:0", tls: ClientTls(insecure: true), once: true) + defer { client.cancel() } + let session = try await client.connect(to: "https://127.0.0.1:1") + defer { session.cancel(code: 0) } + + let viewers = session.viewers() + let viewer = try viewers.watch(maxBps: 1_000_000) + try viewer.update(maxBps: 2_000_000) + try viewers.setTarget(targetBps: 0) + try viewers.setTarget(targetBps: nil) + XCTAssertNil(viewer.rate()) + // Past what a PROBE target carries: refused. + XCTAssertThrowsError(try viewers.watch(maxBps: 1 << 53)) { error in + guard case MoqError.OutOfRange = error else { + return XCTFail("expected OutOfRange, got \(error)") + } + } + } + /// A value the native side cannot use throws from the constructor, not the dial. func testInvalidConfigThrowsConfig() { XCTAssertThrowsError(try Client(versions: ["moq-lite-99"])) { error in