diff --git a/cpp/moq/MIGRATE.md b/cpp/moq/MIGRATE.md index 986d21b524f..bc35c440677 100644 --- a/cpp/moq/MIGRATE.md +++ b/cpp/moq/MIGRATE.md @@ -4,6 +4,11 @@ How to update your code for each breaking change, newest first. ## Unreleased +### A claim answers by publishing (#5678) + +`OriginProducer::dynamic(prefix)` takes no route, and `OriginDynamic::update` is gone. +Replace `request->accept(broadcast)` with `request->prepare(epoch)`, which returns a `BroadcastPrepared`: fill its `broadcast()`, then `publish()` announces it at the exact path under that epoch and returns its producer. + ### Anchors can name a time (#6074) `Anchor` gains a `Time` case holding `timestamp_us`, the group containing that presentation time, so exhaustive visits need a case for it. diff --git a/dart/moq/MIGRATE.md b/dart/moq/MIGRATE.md index b280596e611..ca684d6754f 100644 --- a/dart/moq/MIGRATE.md +++ b/dart/moq/MIGRATE.md @@ -4,6 +4,11 @@ How to update your code for each breaking change, newest first. ## Unreleased +### A claim answers by publishing (#5678) + +`origin.dynamic_(prefix:)` takes no route, and `update` is gone. +Replace `request.accept(broadcast:)` with `request.prepare(epoch: mintEpoch())`, which returns a `BroadcastPrepared`: fill its `broadcast()`, then `publish()` announces it at the exact path under that epoch and returns its producer. + ### Anchors can name a time (#6074) `Anchor` gains a time variant, so exhaustive switches need a case for it. diff --git a/dart/moq/lib/src/aliases.dart b/dart/moq/lib/src/aliases.dart index ee9d97750c1..7d353f783cb 100644 --- a/dart/moq/lib/src/aliases.dart +++ b/dart/moq/lib/src/aliases.dart @@ -43,6 +43,9 @@ typedef OriginDynamic = MoqOriginDynamic; /// A requested broadcast not yet accepted: fulfill it with a producer or reject it. typedef BroadcastRequest = MoqBroadcastRequest; +/// A claim answer being filled before its exact route is announced. +typedef BroadcastPrepared = MoqBroadcastPrepared; + /// A stream of announce events under a prefix. typedef AnnounceConsumer = MoqAnnounceConsumer; diff --git a/dart/moq/test/moq_test.dart b/dart/moq/test/moq_test.dart index 3bcdcfa02fb..e8ec7946f64 100644 --- a/dart/moq/test/moq_test.dart +++ b/dart/moq/test/moq_test.dart @@ -428,12 +428,11 @@ void main() { test('dynamic serves a request under a prefix', () async { final origin = MoqOriginProducer(config: MoqOriginConfig()); - final dynamic = origin.dynamic_(prefix: 'live', route: MoqRoute()); + final dynamic = origin.dynamic_(prefix: 'live'); final pending = origin.consume().requestBroadcast(path: 'live/cam'); final request = await dynamic.requestedBroadcast().timeout(timeout); expect(request.path(), 'live/cam'); - final served = MoqBroadcastProducer(); - request.accept(broadcast: served); + final served = request.prepare(epoch: mintEpoch()).publish(); await pending.timeout(timeout); dynamic.cancel(); dynamic.dispose(); diff --git a/dart/moq_ffi/lib/src/moq.dart b/dart/moq_ffi/lib/src/moq.dart index f21651d2045..1a442e663c2 100644 --- a/dart/moq_ffi/lib/src/moq.dart +++ b/dart/moq_ffi/lib/src/moq.dart @@ -8,9 +8,7 @@ import "dart:ffi"; import "dart:io" show Platform, File, Directory; import "dart:isolate"; import "dart:typed_data"; - import "package:ffi/ffi.dart"; - import "uniffi_runtime.dart"; export "uniffi_runtime.dart"; @@ -10424,9 +10422,98 @@ class FfiConverterMoqAnnouncedBroadcast { } } +abstract class MoqBroadcastPreparedInterface { + MoqBroadcastProducer broadcast(); + MoqBroadcastProducer publish(); +} + +final _MoqBroadcastPreparedFinalizer = Finalizer>((ptr) { + rustCall( + (status) => uniffi_moq_ffi_fn_free_moqbroadcastprepared(ptr, status), + ); +}); + +class MoqBroadcastPrepared implements MoqBroadcastPreparedInterface { + late final Pointer _ptr; + bool _isDisposed = false; + MoqBroadcastPrepared._(this._ptr) { + _MoqBroadcastPreparedFinalizer.attach(this, _ptr, detach: this); + } + factory MoqBroadcastPrepared.lift(Pointer ptr) { + return MoqBroadcastPrepared._(ptr); + } + Pointer uniffiClonePointer() { + if (_isDisposed) { + throw StateError("Object has already been disposed"); + } + return rustCall( + (status) => uniffi_moq_ffi_fn_clone_moqbroadcastprepared(_ptr, status), + ); + } + + void dispose() { + if (_isDisposed) { + return; + } + _isDisposed = true; + _MoqBroadcastPreparedFinalizer.detach(this); + rustCall( + (status) => uniffi_moq_ffi_fn_free_moqbroadcastprepared(_ptr, status), + ); + } + + MoqBroadcastProducer broadcast() { + return rustCallWithLifter( + (status) => uniffi_moq_ffi_fn_method_moqbroadcastprepared_broadcast( + uniffiClonePointer(), + status, + ), + FfiConverterMoqBroadcastProducer.lift, + null, + ); + } + + MoqBroadcastProducer publish() { + return rustCallWithLifter( + (status) => uniffi_moq_ffi_fn_method_moqbroadcastprepared_publish( + uniffiClonePointer(), + status, + ), + FfiConverterMoqBroadcastProducer.lift, + moqExceptionErrorHandler, + ); + } +} + +class FfiConverterMoqBroadcastPrepared { + static MoqBroadcastPrepared lift(Pointer ptr) { + return MoqBroadcastPrepared.lift(ptr); + } + + static Pointer lower(MoqBroadcastPrepared value) { + return value.uniffiClonePointer(); + } + + static int allocationSize(MoqBroadcastPrepared value) { + return 8; + } + + static LiftRetVal read(Uint8List buf) { + final handle = buf.buffer.asByteData(buf.offsetInBytes).getInt64(0); + final pointer = Pointer.fromAddress(handle); + return LiftRetVal(MoqBroadcastPrepared.lift(pointer), 8); + } + + static int write(MoqBroadcastPrepared value, Uint8List buf) { + final handle = lower(value); + buf.buffer.asByteData(buf.offsetInBytes).setInt64(0, handle.address); + return 8; + } +} + abstract class MoqBroadcastRequestInterface { - void accept({required MoqBroadcastProducer broadcast}); String path(); + MoqBroadcastPrepared prepare({required String epoch}); void reject({required int errorCode}); } @@ -10463,23 +10550,25 @@ class MoqBroadcastRequest implements MoqBroadcastRequestInterface { ); } - void accept({required MoqBroadcastProducer broadcast}) { - return rustCall((status) { - uniffi_moq_ffi_fn_method_moqbroadcastrequest_accept( + String path() { + return rustCallWithLifter( + (status) => uniffi_moq_ffi_fn_method_moqbroadcastrequest_path( uniffiClonePointer(), - FfiConverterMoqBroadcastProducer.lower(broadcast), status, - ); - }, moqExceptionErrorHandler); + ), + FfiConverterString.lift, + moqExceptionErrorHandler, + ); } - String path() { + MoqBroadcastPrepared prepare({required String epoch}) { return rustCallWithLifter( - (status) => uniffi_moq_ffi_fn_method_moqbroadcastrequest_path( + (status) => uniffi_moq_ffi_fn_method_moqbroadcastrequest_prepare( uniffiClonePointer(), + FfiConverterString.lower(epoch), status, ), - FfiConverterString.lift, + FfiConverterMoqBroadcastPrepared.lift, moqExceptionErrorHandler, ); } @@ -10630,7 +10719,6 @@ class FfiConverterMoqOriginConsumer { abstract class MoqOriginDynamicInterface { void cancel(); Future requestedBroadcast(); - void update({required MoqRoute route}); } final _MoqOriginDynamicFinalizer = Finalizer>((ptr) { @@ -10686,16 +10774,6 @@ class MoqOriginDynamic implements MoqOriginDynamicInterface { moqExceptionErrorHandler, ); } - - void update({required MoqRoute route}) { - return rustCall((status) { - uniffi_moq_ffi_fn_method_moqorigindynamic_update( - uniffiClonePointer(), - FfiConverterMoqRoute.lower(route), - status, - ); - }, moqExceptionErrorHandler); - } } class FfiConverterMoqOriginDynamic { @@ -10727,7 +10805,7 @@ class FfiConverterMoqOriginDynamic { abstract class MoqOriginProducerInterface { MoqOriginConsumer consume(); MoqBroadcastProducer createBroadcast({required String path}); - MoqOriginDynamic dynamic_({required String prefix, required MoqRoute route}); + MoqOriginDynamic dynamic_({required String prefix}); } final _MoqOriginProducerFinalizer = Finalizer>((ptr) { @@ -10796,12 +10874,11 @@ class MoqOriginProducer implements MoqOriginProducerInterface { ); } - MoqOriginDynamic dynamic_({required String prefix, required MoqRoute route}) { + MoqOriginDynamic dynamic_({required String prefix}) { return rustCallWithLifter( (status) => uniffi_moq_ffi_fn_method_moqoriginproducer_dynamic( uniffiClonePointer(), FfiConverterString.lower(prefix), - FfiConverterMoqRoute.lower(route), status, ), FfiConverterMoqOriginDynamic.lift, @@ -16403,7 +16480,7 @@ external void uniffi_moq_ffi_fn_method_moqannouncedbroadcast_cancel( @Native Function(Pointer, Pointer)>( assetId: _uniffiAssetId, ) -external Pointer uniffi_moq_ffi_fn_clone_moqbroadcastrequest( +external Pointer uniffi_moq_ffi_fn_clone_moqbroadcastprepared( Pointer handle, Pointer uniffiStatus, ); @@ -16411,17 +16488,40 @@ external Pointer uniffi_moq_ffi_fn_clone_moqbroadcastrequest( @Native, Pointer)>( assetId: _uniffiAssetId, ) -external void uniffi_moq_ffi_fn_free_moqbroadcastrequest( +external void uniffi_moq_ffi_fn_free_moqbroadcastprepared( Pointer handle, Pointer uniffiStatus, ); -@Native, Pointer, Pointer)>( +@Native Function(Pointer, Pointer)>( assetId: _uniffiAssetId, ) -external void uniffi_moq_ffi_fn_method_moqbroadcastrequest_accept( +external Pointer uniffi_moq_ffi_fn_method_moqbroadcastprepared_broadcast( + Pointer ptr, + Pointer uniffiStatus, +); + +@Native Function(Pointer, Pointer)>( + assetId: _uniffiAssetId, +) +external Pointer uniffi_moq_ffi_fn_method_moqbroadcastprepared_publish( Pointer ptr, - Pointer broadcast, + Pointer uniffiStatus, +); + +@Native Function(Pointer, Pointer)>( + assetId: _uniffiAssetId, +) +external Pointer uniffi_moq_ffi_fn_clone_moqbroadcastrequest( + Pointer handle, + Pointer uniffiStatus, +); + +@Native, Pointer)>( + assetId: _uniffiAssetId, +) +external void uniffi_moq_ffi_fn_free_moqbroadcastrequest( + Pointer handle, Pointer uniffiStatus, ); @@ -16433,6 +16533,15 @@ external RustBuffer uniffi_moq_ffi_fn_method_moqbroadcastrequest_path( Pointer uniffiStatus, ); +@Native< + Pointer Function(Pointer, RustBuffer, Pointer) +>(assetId: _uniffiAssetId) +external Pointer uniffi_moq_ffi_fn_method_moqbroadcastrequest_prepare( + Pointer ptr, + RustBuffer epoch, + Pointer uniffiStatus, +); + @Native, Uint16, Pointer)>( assetId: _uniffiAssetId, ) @@ -16516,15 +16625,6 @@ uniffi_moq_ffi_fn_method_moqorigindynamic_requested_broadcast( Pointer ptr, ); -@Native, RustBuffer, Pointer)>( - assetId: _uniffiAssetId, -) -external void uniffi_moq_ffi_fn_method_moqorigindynamic_update( - Pointer ptr, - RustBuffer route, - Pointer uniffiStatus, -); - @Native Function(Pointer, Pointer)>( assetId: _uniffiAssetId, ) @@ -16568,17 +16668,11 @@ uniffi_moq_ffi_fn_method_moqoriginproducer_create_broadcast( ); @Native< - Pointer Function( - Pointer, - RustBuffer, - RustBuffer, - Pointer, - ) + Pointer Function(Pointer, RustBuffer, Pointer) >(assetId: _uniffiAssetId) external Pointer uniffi_moq_ffi_fn_method_moqoriginproducer_dynamic( Pointer ptr, RustBuffer prefix, - RustBuffer route, Pointer uniffiStatus, ); @@ -18148,11 +18242,17 @@ external int uniffi_moq_ffi_checksum_method_moqannouncedbroadcast_available(); external int uniffi_moq_ffi_checksum_method_moqannouncedbroadcast_cancel(); @Native(assetId: _uniffiAssetId) -external int uniffi_moq_ffi_checksum_method_moqbroadcastrequest_accept(); +external int uniffi_moq_ffi_checksum_method_moqbroadcastprepared_broadcast(); + +@Native(assetId: _uniffiAssetId) +external int uniffi_moq_ffi_checksum_method_moqbroadcastprepared_publish(); @Native(assetId: _uniffiAssetId) external int uniffi_moq_ffi_checksum_method_moqbroadcastrequest_path(); +@Native(assetId: _uniffiAssetId) +external int uniffi_moq_ffi_checksum_method_moqbroadcastrequest_prepare(); + @Native(assetId: _uniffiAssetId) external int uniffi_moq_ffi_checksum_method_moqbroadcastrequest_reject(); @@ -18174,9 +18274,6 @@ external int uniffi_moq_ffi_checksum_method_moqorigindynamic_cancel(); external int uniffi_moq_ffi_checksum_method_moqorigindynamic_requested_broadcast(); -@Native(assetId: _uniffiAssetId) -external int uniffi_moq_ffi_checksum_method_moqorigindynamic_update(); - @Native(assetId: _uniffiAssetId) external int uniffi_moq_ffi_checksum_method_moqoriginproducer_consume(); @@ -18815,12 +18912,19 @@ void _checkApiChecksums() { if (uniffi_moq_ffi_checksum_method_moqannouncedbroadcast_cancel() != 63175) { throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); } - if (uniffi_moq_ffi_checksum_method_moqbroadcastrequest_accept() != 36946) { + if (uniffi_moq_ffi_checksum_method_moqbroadcastprepared_broadcast() != + 42363) { + throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); + } + if (uniffi_moq_ffi_checksum_method_moqbroadcastprepared_publish() != 65442) { throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); } if (uniffi_moq_ffi_checksum_method_moqbroadcastrequest_path() != 6534) { throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); } + if (uniffi_moq_ffi_checksum_method_moqbroadcastrequest_prepare() != 14120) { + throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); + } if (uniffi_moq_ffi_checksum_method_moqbroadcastrequest_reject() != 9727) { throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); } @@ -18842,9 +18946,6 @@ void _checkApiChecksums() { 54021) { throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); } - if (uniffi_moq_ffi_checksum_method_moqorigindynamic_update() != 15163) { - throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); - } if (uniffi_moq_ffi_checksum_method_moqoriginproducer_consume() != 52357) { throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); } @@ -18852,7 +18953,7 @@ void _checkApiChecksums() { 45756) { throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); } - if (uniffi_moq_ffi_checksum_method_moqoriginproducer_dynamic() != 56233) { + if (uniffi_moq_ffi_checksum_method_moqoriginproducer_dynamic() != 3545) { throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); } if (uniffi_moq_ffi_checksum_method_moqbroadcastdynamic_cancel() != 25875) { @@ -19176,7 +19277,7 @@ void _checkApiChecksums() { if (uniffi_moq_ffi_checksum_constructor_moqoriginproducer_new() != 48126) { throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); } - if (uniffi_moq_ffi_checksum_constructor_moqbroadcastproducer_new() != 37572) { + if (uniffi_moq_ffi_checksum_constructor_moqbroadcastproducer_new() != 12099) { throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); } if (uniffi_moq_ffi_checksum_constructor_moqserver_new() != 49910) { diff --git a/doc/concept/moq-lite.md b/doc/concept/moq-lite.md index 8a75ddf05c5..3eb126e31cf 100644 --- a/doc/concept/moq-lite.md +++ b/doc/concept/moq-lite.md @@ -87,21 +87,19 @@ A path and an epoch name one broadcast. The path never changes, so authorization and hidden names work exactly as without one. - **One instance, one epoch.** A publisher mints an epoch per run. Replicas of - the same content announce that same epoch. A prefix claim, and any route - without an epoch, names no instance, so a relay cannot tell that a claim's - worker closed a path and serves it again. Such a worker keeps the path's group - sequence going, even when its own input starts over at 0. Otherwise a viewer - returning within a relay's cache window gets the old output's latest group, - then nothing until the new sequence passes it. + the same content announce that same epoch. A prefix claim names no instance: + its worker answers each requested path by announcing that exact path under + the output's own epoch. Restarting one output is then a new epoch every hop + sees, so a viewer returning within a relay's cache window never gets the old + output's groups. - **Newest wins.** Among routes at the same prefix, the newest epoch ranks first, ahead of cost, and a route without an epoch ranks last. Newest means the latest UUIDv7 timestamp, so hosts with skewed clocks can lose a restart until the old instance retracts. - **Same epoch resumes.** A subscription moves between routes with the same epoch without a seam, continuing from the first frame it lacks. A route - without an epoch keeps its subscriptions until that route goes, which is how - a transcoder claim stays on the worker that first served it, and a track that - fails ends instead of resuming, so request the path again. + without an epoch keeps its subscriptions until that route goes, and a track + that fails ends instead of resuming, so request the path again. - **Another instance restarts.** A newer epoch, or, without one, another route winning the path, is announced as a restart. Subscriptions already open stay on the old instance until dropped or none of its routes remain, which ends diff --git a/doc/lib/js/net.md b/doc/lib/js/net.md index b0c833901ec..f413e9cb5a8 100644 --- a/doc/lib/js/net.md +++ b/doc/lib/js/net.md @@ -33,7 +33,7 @@ group.close(); broadcast.announce(); ``` -- **The origin holds the broadcasts, not the connection.** Closing a session unannounces them and leaves them created for the next one. A broadcast is invisible, locally and remotely, until `announce()`. `dynamic(prefix, route)` claims a prefix and yields each requested path to accept or reject. `accept` throws on a broadcast a session delivered, since JS apps do not proxy; copy its tracks into a broadcast you produce instead. +- **The origin holds the broadcasts, not the connection.** Closing a session unannounces them and leaves them created for the next one. A broadcast is invisible, locally and remotely, until `announce()`. `dynamic(prefix)` claims a prefix and yields each requested path. Call `prepare(epoch)`, fill its broadcast, then `publish()` to answer with a new publisher instance, or `reject(err)` either one. - **Requests can pin an epoch.** `consumer.request(path, { epoch })` resolves only through a route announcing that [publisher epoch](/concept/moq-lite#publisher-epochs) and reports `unroutable` otherwise. The resolved broadcast's `epoch` names the route it came through, pinned or not. - **Rank several CDNs.** Connect to each with its own `consume: origin.withPreference(Origin.Preference(rank))` (higher wins; 0 is neutral and a negative rank demotes), all on one origin. Requests use the preferred link that has a route and fail over to the next; see [multiple CDNs](/concept/moq-lite#multiple-cdns). - **Follow restarts.** `origin.request(path, { announced: true })` follows whichever publisher instance serves the path: its `active` changes to a fresh broadcast on a restart, clears on an end, and resolves again on the next start, so read it reactively and close the request when done. Instances are never stitched, so subscribe again to each new broadcast. Another route of the same epoch taking over (epochs travel only on `moq-lite-07-wip`) keeps `active` as is, and each track subscription resumes there from the first group it lacks. A refusal ends the request. Add `epoch` to pin one instance; a plain `request(path)` keeps its accepted instance, can resolve blindly, and ends once that instance stops serving. To list what is live, iterate `announced(scope)`. diff --git a/doc/lib/rs/index.md b/doc/lib/rs/index.md index 08059e24cea..37d812758ed 100644 --- a/doc/lib/rs/index.md +++ b/doc/lib/rs/index.md @@ -73,8 +73,8 @@ while let Some(event) = announced.next().await { let mut broadcast = origin.publish("my-stream.hang", Default::default())?; // moq-mux (from a container) or moq-video / moq-audio (from a device) fill it. // The route retracts on `unannounce()` or when the broadcast ends. To serve a whole -// subtree on demand instead, `origin.dynamic("room", Default::default())?` yields -// each requested path for the application to accept or reject. +// subtree on demand instead, `origin.dynamic("room")?` yields each requested path: +// `prepare(Epoch::mint())`, fill its broadcast, then `publish()`, or reject it. ``` The connection and origin helpers spawn their drivers. Watch diff --git a/go/wrapper/MIGRATE.md b/go/wrapper/MIGRATE.md index 0331ac824cd..3ff535ff662 100644 --- a/go/wrapper/MIGRATE.md +++ b/go/wrapper/MIGRATE.md @@ -4,6 +4,12 @@ How to update your code for each breaking change, newest first. ## Unreleased +### A claim answers by publishing (#5678) + +`OriginProducer.Dynamic(prefix)` takes no route, and `OriginDynamic.Update` is gone. +Replace `request.Accept(broadcast)` with `request.Prepare(epoch)`, which returns a `*BroadcastPrepared`: fill its `Broadcast()`, then `Publish()` announces it at the exact path under that epoch and returns its producer. +Where you rejected a request after a failed setup, `Close()` the prepared answer instead. + ### `TrackInfo` gains `Compress` (#5928) A positional `TrackInfo{...}` literal adds a trailing `false`; keyed literals need no change. diff --git a/go/wrapper/moq_test.go b/go/wrapper/moq_test.go index 02858ed518e..60843a0c634 100644 --- a/go/wrapper/moq_test.go +++ b/go/wrapper/moq_test.go @@ -44,7 +44,7 @@ func opusHead() []byte { func TestOriginLifecycle(t *testing.T) { origin := newOrigin(t) _ = origin.Consume() - dynamic, err := origin.Dynamic("", moq.Route{}) + dynamic, err := origin.Dynamic("") if err != nil { t.Fatal(err) } @@ -56,7 +56,7 @@ func TestDynamicBroadcastRequest(t *testing.T) { defer cancel() origin := newOrigin(t) - dynamic, err := origin.Dynamic("", moq.Route{}) + dynamic, err := origin.Dynamic("") if err != nil { t.Fatal(err) } @@ -84,15 +84,16 @@ func TestDynamicBroadcastRequest(t *testing.T) { t.Fatalf("path = %q, want %q", path, "dynamic/broadcast") } - served, err := moq.NewBroadcastProducer() + prepared, err := request.Prepare(moq.MintEpoch()) if err != nil { t.Fatal(err) } - track, err := served.PublishTrack("status", timedInfo()) + track, err := prepared.Broadcast().PublishTrack("status", timedInfo()) if err != nil { t.Fatal(err) } - if err := request.Accept(served); err != nil { + served, err := prepared.Publish() + if err != nil { t.Fatal(err) } @@ -1105,7 +1106,7 @@ func TestConsumerCancelConcurrent(t *testing.T) { // that one request rather than the consumer it was made on. func TestRequestBroadcastCancelKeepsTheOrigin(t *testing.T) { origin := newOrigin(t) - dynamic, err := origin.Dynamic("", moq.Route{}) + dynamic, err := origin.Dynamic("") if err != nil { t.Fatal(err) } @@ -1142,12 +1143,6 @@ func TestRequestBroadcastCancelKeepsTheOrigin(t *testing.T) { // The same consumer resolves the next path, which it could not do if the // cancel had torn the origin down. - served, err := moq.NewBroadcastProducer() - if err != nil { - t.Fatal(err) - } - defer served.Close() - resolved := make(chan error, 1) go func() { _, err := consumer.RequestBroadcast(waitCtx, "later/served") @@ -1158,9 +1153,15 @@ func TestRequestBroadcastCancelKeepsTheOrigin(t *testing.T) { if err != nil { t.Fatal(err) } - if err := next.Accept(served); err != nil { + prepared, err := next.Prepare(moq.MintEpoch()) + if err != nil { + t.Fatal(err) + } + served, err := prepared.Publish() + if err != nil { t.Fatal(err) } + defer served.Close() select { case err := <-resolved: if err != nil { @@ -1553,7 +1554,7 @@ func TestDynamicServesARequestUnderAPrefix(t *testing.T) { defer cancel() origin := newOrigin(t) - dynamic, err := origin.Dynamic("live", moq.Route{}) + dynamic, err := origin.Dynamic("live") if err != nil { t.Fatal(err) } @@ -1574,18 +1575,61 @@ func TestDynamicServesARequestUnderAPrefix(t *testing.T) { if err != nil || path != "live/cam" { t.Fatalf("path = %q err=%v", path, err) } - served, err := moq.NewBroadcastProducer() + prepared, err := request.Prepare(moq.MintEpoch()) if err != nil { t.Fatal(err) } - if err := request.Accept(served); err != nil { + served, err := prepared.Publish() + if err != nil { t.Fatal(err) } + defer served.Close() if err := <-done; err != nil { t.Fatal(err) } } +func TestClosingAPreparedAnswerRefusesTheRequest(t *testing.T) { + ctx, cancel := context.WithTimeout(context.Background(), testTimeout) + defer cancel() + + origin := newOrigin(t) + dynamic, err := origin.Dynamic("live") + if err != nil { + t.Fatal(err) + } + defer dynamic.Cancel() + + consumer := origin.Consume() + done := make(chan error, 1) + go func() { + _, err := consumer.RequestBroadcast(ctx, "live/cam") + done <- err + }() + + request, err := dynamic.RequestedBroadcast(ctx) + if err != nil { + t.Fatal(err) + } + prepared, err := request.Prepare(moq.MintEpoch()) + if err != nil { + t.Fatal(err) + } + prepared.Close() + + select { + case err := <-done: + if err == nil { + t.Fatal("RequestBroadcast succeeded, want the abandoned answer refused") + } + if ctx.Err() != nil { + t.Fatalf("RequestBroadcast err = %v, want a refusal before the deadline", err) + } + case <-ctx.Done(): + t.Fatal(ctx.Err()) + } +} + // us is a raw frame's optional timestamp in microseconds. func us(v uint64) *uint64 { return &v } diff --git a/go/wrapper/origin.go b/go/wrapper/origin.go index 088e539b6be..d0a60966b63 100644 --- a/go/wrapper/origin.go +++ b/go/wrapper/origin.go @@ -2,7 +2,6 @@ package moq import ( "context" - "errors" "iter" ffi "moq.dev/moq-ffi/moq" @@ -42,8 +41,8 @@ func (o *OriginProducer) Consume() *OriginConsumer { // service that only serves some of them rejects the rest as they are requested. // Create, Dynamic if tracks are served on demand, populate, then // [BroadcastProducer.Announce]. -func (o *OriginProducer) Dynamic(prefix string, route Route) (*OriginDynamic, error) { - inner, err := o.inner.Dynamic(prefix, route) +func (o *OriginProducer) Dynamic(prefix string) (*OriginDynamic, error) { + inner, err := o.inner.Dynamic(prefix) if err != nil { return nil, err } @@ -86,11 +85,6 @@ func (d *OriginDynamic) All(ctx context.Context) iter.Seq2[*BroadcastRequest, er return bridge.Seq(ctx, d.RequestedBroadcast) } -// Update re-prices the route in place: replaces its hops and costs. -func (d *OriginDynamic) Update(route Route) error { - return d.inner.Update(route) -} - // Cancel stops serving requested broadcasts and retracts the route. func (d *OriginDynamic) Cancel() { d.inner.Cancel() @@ -106,12 +100,13 @@ func (r *BroadcastRequest) Path() (string, error) { return r.inner.Path() } -// Accept serves the request with an unannounced broadcast. -func (r *BroadcastRequest) Accept(broadcast *BroadcastProducer) error { - if broadcast == nil { - return errors.New("moq: nil broadcast producer") +// Prepare starts an answer under a new epoch, hidden until published. +func (r *BroadcastRequest) Prepare(epoch string) (*BroadcastPrepared, error) { + inner, err := r.inner.Prepare(epoch) + if err != nil { + return nil, err } - return r.inner.Accept(broadcast.inner) + return &BroadcastPrepared{inner: inner}, nil } // Reject fails the request with an application error code. @@ -119,6 +114,30 @@ func (r *BroadcastRequest) Reject(errorCode uint16) error { return r.inner.Reject(errorCode) } +// BroadcastPrepared is a claim answer being filled before announcement. +type BroadcastPrepared struct { + inner *ffi.MoqBroadcastPrepared +} + +// Broadcast returns the unannounced broadcast to fill before publishing; only Publish announces it. +func (p *BroadcastPrepared) Broadcast() *BroadcastProducer { + return &BroadcastProducer{inner: p.inner.Broadcast()} +} + +// Publish announces the answer and resolves every waiting requester. +func (p *BroadcastPrepared) Publish() (*BroadcastProducer, error) { + inner, err := p.inner.Publish() + if err != nil { + return nil, err + } + return &BroadcastProducer{inner: inner}, nil +} + +// Close abandons the answer if it was not published, refusing every waiting requester. +func (p *BroadcastPrepared) Close() { + p.inner.Destroy() +} + // OriginConsumer discovers and requests broadcasts published to an origin. type OriginConsumer struct { inner *ffi.MoqOriginConsumer diff --git a/go/wrapper/origin_internal_test.go b/go/wrapper/origin_internal_test.go index f1c61919182..467d0d018ea 100644 --- a/go/wrapper/origin_internal_test.go +++ b/go/wrapper/origin_internal_test.go @@ -43,7 +43,7 @@ func TestDynamicKeepsTheOrigin(t *testing.T) { defer cancel() origin := NewOriginProducer() - dynamic, err := origin.Dynamic("", Route{}) + dynamic, err := origin.Dynamic("") if err != nil { t.Fatal(err) } @@ -66,14 +66,15 @@ func TestDynamicKeepsTheOrigin(t *testing.T) { if err != nil { t.Fatalf("RequestedBroadcast err = %v, want a request", err) } - served, err := NewBroadcastProducer() + prepared, err := request.Prepare(MintEpoch()) if err != nil { t.Fatal(err) } - defer func() { _ = served.Close() }() - if err := request.Accept(served); err != nil { + served, err := prepared.Publish() + if err != nil { t.Fatal(err) } + defer func() { _ = served.Close() }() var res result select { diff --git a/js/net/MIGRATE.md b/js/net/MIGRATE.md index 4d7076305f6..3b071ad6145 100644 --- a/js/net/MIGRATE.md +++ b/js/net/MIGRATE.md @@ -4,6 +4,15 @@ How to update your code for each breaking change, newest first. ## Unreleased +### A claim answers by publishing (#5678) + +`Origin.Producer.dynamic(prefix)` takes no route: an application claim has no epoch, cost, or hops. +Answer each `Origin.Request` with `request.prepare(epoch)` (a fresh `Epoch.mint()` per output run), fill `prepared.broadcast`, then `prepared.publish()`, which announces the broadcast at the exact path under that epoch and returns its producer. +Only `publish` announces it: `prepared.broadcast.announce()` throws. +Call `prepared.reject(err)` to refuse instead; JS has no destructor, so an abandoned `Prepared` holds its request open. +`Dynamic.update` and `Request.accept` are no longer part of the public API, and `accept` throws on a request from `dynamic`. +Close the claim and claim again to change it, and close an answer's producer to end that output. + ### `largest()` reports within a reader's `setGroups` bounds `Track.Subscriber.largest()` and `Track.Ordered.largest()` report the track's largest only while it is within the bounds set with `setGroups` or `withGroups`, where they used to ignore the bounds. diff --git a/js/net/bench/broadcasts.ts b/js/net/bench/broadcasts.ts index 39d1b154c0c..2a3730bbeac 100644 --- a/js/net/bench/broadcasts.ts +++ b/js/net/bench/broadcasts.ts @@ -51,7 +51,7 @@ for (const scope of ["unscoped", "distinct-scopes", "producer-scopes", "rooted-p const start = performance.now(); for (let index = 0; index < updates; index++) { - handles[0].update({ cost: BigInt(index + 1) }); + handles[0].updateRoute({ cost: BigInt(index + 1) }); await new Promise((resolve) => setImmediate(resolve)); } const elapsed = performance.now() - start; @@ -213,7 +213,7 @@ const nextEpoch = Epoch.parse("01900000-0000-7000-8000-000000000002"); for (const pathCount of routeCounts) { for (const readerCount of observerCounts) { const origin = new Producer(); - const dynamic = origin.dynamic(Path.from("room"), { epoch }); + const dynamic = origin.dynamicRoute(Path.from("room"), { epoch }); const pending = dynamic.requested(); const requests = Array.from({ length: pathCount }, (_, index) => Array.from({ length: readerCount }, () => origin.consume().request(Path.from(`room/${index}`))), @@ -223,7 +223,7 @@ for (const pathCount of routeCounts) { await Promise.resolve(); const before = requests.map((request) => request.active.peek()); const start = performance.now(); - dynamic.update({ epoch: nextEpoch }); + dynamic.updateRoute({ epoch: nextEpoch }); await Promise.resolve(); const elapsed = performance.now() - start; for (const [index, request] of requests.entries()) { diff --git a/js/net/bench/requests.ts b/js/net/bench/requests.ts index 2f16119e7ec..31ad90e65a6 100644 --- a/js/net/bench/requests.ts +++ b/js/net/bench/requests.ts @@ -70,7 +70,7 @@ console.log("unrelated,waiters,cancel_us"); for (const unrelated of [8, 128, 2048]) for (const waiters of [1, 8, 32]) { const origin = new Producer(); - origin.dynamic(Path.from("pending")); + origin.dynamicRoute(Path.from("pending")); const held = Array.from({ length: unrelated }, (_, i) => origin.request(Path.from(`pending/${i}`))); const wire = wireOf(origin.consume()); const samples: number[] = []; @@ -104,9 +104,9 @@ for (const failovers of [0, 1, 16, 128]) const sources: Broadcast[] = []; for (let i = 0; i < failovers; i++) { const epoch = Epoch.mint(); - const primary = origin.dynamic(prefix, { epoch, cost: 0n }); + const primary = origin.dynamicRoute(prefix, { epoch, cost: 0n }); const ar = primary.requested(); - const br = origin.dynamic(prefix, { epoch, cost: 1n }).requested(); + const br = origin.dynamicRoute(prefix, { epoch, cost: 1n }).requested(); const held = origin.request(path); const source = new Broadcast(); sources.push(source); @@ -115,8 +115,8 @@ for (const failovers of [0, 1, 16, 128]) entries.push({ primary, ar, br, held }); } const epoch = Epoch.mint(); - origin.dynamic(prefix, { epoch }); - for (let i = 0; i < extraRoutes; i++) origin.dynamic(prefix, { epoch, cost: BigInt(i + 1) }); + origin.dynamicRoute(prefix, { epoch }); + for (let i = 0; i < extraRoutes; i++) origin.dynamicRoute(prefix, { epoch, cost: BigInt(i + 1) }); const pending = []; for (const entry of entries) { entry.primary.close(); @@ -178,7 +178,7 @@ for (const operation of ["cancel-forward", "cancel-reverse", "drain-local"]) const settled: number[] = []; for (let round = 0; round < 4; round++) { const origin = new Producer(); - const dynamic = origin.dynamic(Path.from("pending")); + const dynamic = origin.dynamicRoute(Path.from("pending")); const requests = dynamic.requested(); const wire = wireOf(origin.consume()); const names = Array.from({ length: paths }, (_, i) => Path.from(`pending/${i}`)); @@ -236,7 +236,7 @@ for (const survivor of [false, true]) const origin = new Producer(); const prefix = Path.from("competing"); const path = Path.from("competing/touched"); - for (let i = 0; i < routes; i++) origin.dynamic(prefix, { cost: BigInt(i) }); + for (let i = 0; i < routes; i++) origin.dynamicRoute(prefix, { cost: BigInt(i) }); const wire = wireOf(origin.consume()); const kept = survivor ? new AbortController() : undefined; const remaining = kept ? wire.demand(path, undefined, kept.signal).catch(() => {}) : undefined; diff --git a/js/net/src/broadcast.ts b/js/net/src/broadcast.ts index 3dab4121a7b..affaf75c828 100644 --- a/js/net/src/broadcast.ts +++ b/js/net/src/broadcast.ts @@ -367,6 +367,11 @@ export class Producer { producer.#announcer = announcer; }; hooks.attachAnnouncer = attachAnnouncer; + hooks.withholdAnnouncer = (producer) => { + const announcer = producer.#announcer; + producer.#announcer = undefined; + return announcer; + }; stampProducer = (producer, path) => { producer.#path = path; }; @@ -456,7 +461,7 @@ export class Producer { * Call it once the tracks a subscriber needs first (a catalog) exist. Until then the * broadcast exists for nobody, on its own origin or at a peer. Retracts on * {@link unannounce} or {@link close}. Throws if this producer was not created through an - * origin, or if the broadcast is already closed. + * origin, is a claim answer still being prepared, or if the broadcast is already closed. */ announce( route: diff --git a/js/net/src/connection/forward.ts b/js/net/src/connection/forward.ts index 932533666da..684482c7977 100644 --- a/js/net/src/connection/forward.ts +++ b/js/net/src/connection/forward.ts @@ -121,7 +121,7 @@ export function forwardAnnounced(conn: Established, origin: OriginProducer): voi existing.handle = handle; void drive(handle, conn); } else if (!routesEqual(existing.handle.route, route)) { - existing.handle.update(route); + existing.handle.updateRoute(route); } }; diff --git a/js/net/src/connection/pool.test.ts b/js/net/src/connection/pool.test.ts index fe1c3f20bc9..977f699a094 100644 --- a/js/net/src/connection/pool.test.ts +++ b/js/net/src/connection/pool.test.ts @@ -257,7 +257,7 @@ test("a borrowed connection origin exposes live routes and dynamic serving", asy announcement = event; }); const prefix = Path.from("on-demand"); - const route = table.dynamic(prefix); + const route = table.dynamicRoute(prefix); await advance(); expect(announcement).toMatchObject({ kind: "start", prefix }); let withdrawal: unknown; diff --git a/js/net/src/ietf/publisher.test.ts b/js/net/src/ietf/publisher.test.ts index 8c7d801b580..7a02e8aea9a 100644 --- a/js/net/src/ietf/publisher.test.ts +++ b/js/net/src/ietf/publisher.test.ts @@ -300,7 +300,7 @@ test("TRACK_STATUS outside the grant is refused on every draft", async () => { const session = new NativeSession(pair.server, version, true); const grant = new Signal(nothing()); const { pub, origin } = publisher(pair.server, { session, grant }); - const requests = origin.dynamic(Path.from("room")).requested(); + const requests = origin.dynamicRoute(Path.from("room")).requested(); const outside = requestStream(version); await pub.runTrackStatusRequest(trackStatus("room"), outside.stream); @@ -383,7 +383,7 @@ test("a cancelled TRACK_STATUS releases its demand on every draft", async () => const pair = createMockTransportPair(ALPNS[version]); const session = new NativeSession(pair.server, version, true); const { pub, origin } = publisher(pair.server, { session }); - const requests = origin.dynamic(Path.from("room")).requested(); + const requests = origin.dynamicRoute(Path.from("room")).requested(); // The broadcast is still resolving: its handler never answers. const early = requestStream(version); @@ -924,7 +924,7 @@ test("a subscription outside a covering route's claim does not hear it", async ( const pair = createMockTransportPair(ALPN.DRAFT_19); const { pub, origin } = publisher(pair.server, { requiresSolicitation: true }); const chat = origin.scope(Path.empty(), new Path.Patterns([Path.Pattern.subtree(Path.from("room/chat"))])); - const dynamic = chat.dynamic(Path.from("room")); + const dynamic = chat.dynamicRoute(Path.from("room")); const subscription = await Stream.open(pair.client, { version: VERSION }); const accepted = await Stream.accept(pair.server, VERSION); @@ -956,8 +956,8 @@ test("a subscription hears the best covering route its claim allows", async () = const { pub, origin } = publisher(pair.server, { requiresSolicitation: true }); const scoped = (path: string) => origin.scope(Path.empty(), new Path.Patterns([Path.Pattern.subtree(Path.from(path))])); - const chat = scoped("room/chat").dynamic(Path.from("room"), { cost: 1n }); - const video = scoped("room/video").dynamic(Path.from("room"), { cost: 5n }); + const chat = scoped("room/chat").dynamicRoute(Path.from("room"), { cost: 1n }); + const video = scoped("room/video").dynamicRoute(Path.from("room"), { cost: 5n }); const subscription = await Stream.open(pair.client, { version: VERSION }); const accepted = await Stream.accept(pair.server, VERSION); @@ -997,8 +997,8 @@ test("a subscription hears a broader covering route when the narrowest cannot se }); const chat = origin .scope(Path.empty(), new Path.Patterns([Path.Pattern.subtree(Path.from("tenant/chat"))])) - .dynamic(Path.from("tenant")); - const broad = origin.dynamic(Path.empty(), { cost: 5n }); + .dynamicRoute(Path.from("tenant")); + const broad = origin.dynamicRoute(Path.empty(), { cost: 5n }); const subscription = await Stream.open(pair.client, { version: VERSION }); const accepted = await Stream.accept(pair.server, VERSION); @@ -1035,7 +1035,7 @@ test("a covering route's claim is compared relative to the served root", async ( requiresSolicitation: true, }); const chat = origin.scope(Path.empty(), new Path.Patterns([Path.Pattern.subtree(Path.from("tenant/room/chat"))])); - const dynamic = chat.dynamic(Path.from("tenant/room")); + const dynamic = chat.dynamicRoute(Path.from("tenant/room")); const subscription = await Stream.open(pair.client, { version: VERSION }); const accepted = await Stream.accept(pair.server, VERSION); diff --git a/js/net/src/integration.test.ts b/js/net/src/integration.test.ts index 213c5667df9..3da09eddb31 100644 --- a/js/net/src/integration.test.ts +++ b/js/net/src/integration.test.ts @@ -959,7 +959,7 @@ test("integration: a peer is served the cheaper route it was offered, not the lo const epoch = Epoch.mint(); const local = origin.createBroadcast(path); local.announce({ epoch, cost: 5n }); - const dynamic = origin.dynamic(path, { epoch, cost: 1n }); + const dynamic = origin.dynamicRoute(path, { epoch, cost: 1n }); const [client, server] = await Promise.all([ connect(url, { transport: pair.client }), @@ -2732,7 +2732,7 @@ test("create then announce is discoverable on the wire", async () => { test("a handle serves a request under live/** over the wire", async () => { const pair = createMockTransportPair(Lite.ALPN_06); const origin = new OriginProducer(); - const handle = origin.dynamic(Path.from("live")); + const handle = origin.dynamicRoute(Path.from("live")); const serving = (async () => { for await (const request of handle.requested()) { diff --git a/js/net/src/internal.ts b/js/net/src/internal.ts index c342ed8218a..bb963f18556 100644 --- a/js/net/src/internal.ts +++ b/js/net/src/internal.ts @@ -492,6 +492,10 @@ export const hooks: { producer: BroadcastProducer, announcer: { announce(route: Route): void; unannounce(): void; route(): Route | undefined }, ) => void; + /** Take a created broadcast's advertisement away, so it cannot announce until attached again. */ + withholdAnnouncer: ( + producer: BroadcastProducer, + ) => { announce(route: Route): void; unannounce(): void; route(): Route | undefined } | undefined; /** Name a broadcast handle by the path an origin created or resolved it at. */ stampPath: (target: BroadcastProducer | BroadcastConsumer, path: Path.Valid) => void; /** Name the epoch of the route an origin resolved a broadcast handle through. */ @@ -641,6 +645,9 @@ export const hooks: { attachAnnouncer: () => { throw new Error("broadcast.ts not loaded"); }, + withholdAnnouncer: () => { + throw new Error("broadcast.ts not loaded"); + }, stampPath: () => { throw new Error("broadcast.ts not loaded"); }, diff --git a/js/net/src/lite/publisher.test.ts b/js/net/src/lite/publisher.test.ts index c4f7d66c1c2..4761f43e242 100644 --- a/js/net/src/lite/publisher.test.ts +++ b/js/net/src/lite/publisher.test.ts @@ -2163,7 +2163,7 @@ test("lite draft-06: closing while announces wait for the setup grant does not h test("lite draft-06: a grant that shrinks while a TRACK resolves refuses it", async () => { const pair = createMockTransportPair(ALPN_06); const origin = new OriginProducer(); - const handle = origin.dynamic(Path.from("live")); + const handle = origin.dynamicRoute(Path.from("live")); const requests = handle.requested(); const grant = new Signal(grantOf("live")); const publisher = new Publisher(pair.server, Version.DRAFT_06, randomHop(), origin.consume(), { @@ -2204,7 +2204,7 @@ test("lite draft-06: a grant that shrinks while a TRACK resolves refuses it", as test("lite draft-06: a grant that shrinks while TRACK_INFO is blocked resets it", async () => { const pair = createMockTransportPair(ALPN_06); const origin = new OriginProducer(); - const handle = origin.dynamic(Path.from("live")); + const handle = origin.dynamicRoute(Path.from("live")); const requests = handle.requested(); const grant = new Signal(grantOf("live")); const publisher = new Publisher(pair.server, Version.DRAFT_06, randomHop(), origin.consume(), { @@ -2267,7 +2267,7 @@ test("lite draft-06: a grant that shrinks while TRACK_INFO is blocked resets it" test("lite draft-06: a grant that shrinks while the broadcast resolves resets the subscription", async () => { const pair = createMockTransportPair(ALPN_06); const origin = new OriginProducer(); - const handle = origin.dynamic(Path.from("live")); + const handle = origin.dynamicRoute(Path.from("live")); const requests = handle.requested(); const grant = new Signal(grantOf("live")); const publisher = new Publisher(pair.server, Version.DRAFT_06, randomHop(), origin.consume(), { diff --git a/js/net/src/origin-demand.test.ts b/js/net/src/origin-demand.test.ts index 79236cf59e7..887af3e9288 100644 --- a/js/net/src/origin-demand.test.ts +++ b/js/net/src/origin-demand.test.ts @@ -27,7 +27,7 @@ test.each(["lite", "ietf", "fetch", "track"] as const)( async (kind) => { const pair = createMockTransportPair(); const origin = new Producer(); - const dynamic = origin.dynamic(Path.from("room")); + const dynamic = origin.dynamicRoute(Path.from("room")); const publisher = kind === "ietf" ? new IetfPublisher({ @@ -106,7 +106,7 @@ test.each(["lite", "ietf", "fetch", "track"] as const)( test("last cancellation finishes the internal wait and discards a late consumer", async () => { const origin = new Producer(); - const dynamic = origin.dynamic(Path.from("room")); + const dynamic = origin.dynamicRoute(Path.from("room")); const requests = dynamic.requested(); const hold = new AbortController(); const wait = wireOf(origin.consume()).demand(path, undefined, hold.signal); @@ -149,7 +149,7 @@ test.each([true, false])( "shared local/remote demand is withdrawn whichever leaves last (local first: %s)", async (localFirst) => { const origin = new Producer(); - const dynamic = origin.dynamic(Path.from("room")); + const dynamic = origin.dynamicRoute(Path.from("room")); const requests = dynamic.requested(); const hold = new AbortController(); const wait = wireOf(origin.consume()) @@ -194,13 +194,13 @@ test.each([ ] as const)("cancelling one waiter preserves a second %s requester across %i routes", async (other, routes) => { const origin = new Producer(); const prefix = Path.from("room"); - const dynamics = Array.from({ length: routes }, (_, i) => origin.dynamic(prefix, { cost: BigInt(i) })); + const dynamics = Array.from({ length: routes }, (_, i) => origin.dynamicRoute(prefix, { cost: BigInt(i) })); const hold = new AbortController(); const wire = wireOf(origin.consume()); const first = wire.demand(path, undefined, hold.signal).catch(() => undefined); // With competing routes, re-price the cancelled waiter's route so the survivor pends on another. const cancelled = dynamics[0]; - if (routes > 1) cancelled.update({ ...cancelled.route, cost: BigInt(routes) }); + if (routes > 1) cancelled.updateRoute({ ...cancelled.route, cost: BigInt(routes) }); const requests = dynamics[routes > 1 ? 1 : 0].requested(); const second = other === "peer" ? wire.demand(path) : undefined; const local = other === "local" ? origin.request(path) : undefined; @@ -223,7 +223,7 @@ test.each([ test("an already cancelled signal never enqueues or subscribes to abort", async () => { const origin = new Producer(); - const dynamic = origin.dynamic(Path.from("room")); + const dynamic = origin.dynamicRoute(Path.from("room")); const requests = dynamic.requested(); const hold = new AbortController(); hold.abort(); @@ -245,7 +245,7 @@ test.each(["accept", "reject", "cancel"] as const)( "%s releases the abort listener without closing a shared producer", async (action) => { const origin = new Producer(); - const dynamic = origin.dynamic(Path.from("room")); + const dynamic = origin.dynamicRoute(Path.from("room")); const requests = dynamic.requested(); const source = new Broadcast(); const keeper = source.consume(); @@ -281,12 +281,12 @@ test.each(["accept", "reject", "cancel"] as const)( test("a pending local request changing routes withdraws the old route's work", async () => { const origin = new Producer(); - const first = origin.dynamic(Path.from("room"), { cost: 5n }); + const first = origin.dynamicRoute(Path.from("room"), { cost: 5n }); const a = first.requested(); const local = origin.request(path); const old = (await a.next()).value; if (!old) throw new Error("expected a pending request"); - const second = origin.dynamic(Path.from("room"), { cost: 1n }); + const second = origin.dynamicRoute(Path.from("room"), { cost: 1n }); const b = second.requested(); const fresh = (await b.next()).value; if (!fresh) throw new Error("expected a pending request"); @@ -314,7 +314,7 @@ test("a pending local request changing routes withdraws the old route's work", a test("cancelling an old epoch waiter does not decrement a new epoch's demand", async () => { const origin = new Producer(); const epoch = Epoch.mint(); - const dynamic = origin.dynamic(Path.from("room"), { epoch }); + const dynamic = origin.dynamicRoute(Path.from("room"), { epoch }); const requests = dynamic.requested(); const wire = wireOf(origin.consume()); const hold = new AbortController(); @@ -322,7 +322,7 @@ test("cancelling an old epoch waiter does not decrement a new epoch's demand", a const old = (await requests.next()).value; if (!old) throw new Error("expected old request"); const nextEpoch = Epoch.mint(); - dynamic.update({ epoch: nextEpoch }); + dynamic.updateRoute({ epoch: nextEpoch }); const after = wire.demand(path, nextEpoch); hold.abort(); await before; @@ -346,8 +346,8 @@ test.each(["answer", "release"] as const)( const origin = new Producer(); const epoch = Epoch.mint(); const prefix = Path.from("room"); - const a = origin.dynamic(prefix, { epoch, cost: 1n }); - const b = origin.dynamic(prefix, { epoch, cost: 5n }); + const a = origin.dynamicRoute(prefix, { epoch, cost: 1n }); + const b = origin.dynamicRoute(prefix, { epoch, cost: 5n }); const ar = a.requested(); const br = b.requested(); const held = origin.request(path); @@ -355,7 +355,7 @@ test.each(["answer", "release"] as const)( (await ar.next()).value?.accept(source); await settle(); // Another instance wins new requests. The old handle stays on its own epoch. - const c = origin.dynamic(prefix, { epoch: Epoch.mint(), cost: 0n }); + const c = origin.dynamicRoute(prefix, { epoch: Epoch.mint(), cost: 0n }); a.close(); await settle(); const pending = (await br.next()).value; @@ -405,8 +405,8 @@ test.each([0, 1])( const sources: Broadcast[] = []; for (let i = 0; i < 2; i++) { const epoch = Epoch.parse(`00000000-0000-7000-8000-00000000000${i + 1}`); - const primary = origin.dynamic(prefix, { epoch, cost: 0n }); - const standby = origin.dynamic(prefix, { epoch, cost: 1n }); + const primary = origin.dynamicRoute(prefix, { epoch, cost: 0n }); + const standby = origin.dynamicRoute(prefix, { epoch, cost: 1n }); const ar = primary.requested(); const br = standby.requested(); const held = origin.request(path); @@ -416,7 +416,7 @@ test.each([0, 1])( await settle(); entries.push({ primary, ar, br, held }); } - origin.dynamic(prefix, { epoch: Epoch.parse("00000000-0000-7000-8000-000000000003") }); + origin.dynamicRoute(prefix, { epoch: Epoch.parse("00000000-0000-7000-8000-000000000003") }); const pending = []; for (const entry of entries) { entry.primary.close(); @@ -457,7 +457,7 @@ test.each([0, 1])( test("a normal FETCH request FIN keeps unanswered origin demand alive", async () => { const pair = createMockTransportPair(); const origin = new Producer(); - const dynamic = origin.dynamic(Path.from("room")); + const dynamic = origin.dynamicRoute(Path.from("room")); const requests = dynamic.requested(); const publisher = new LitePublisher(pair.server, LiteVersion.DRAFT_06, randomHop(), origin.consume()); let input!: ReadableStreamDefaultController; @@ -498,7 +498,7 @@ test.each(["accept", "reject"] as const)( "cancellation racing %s releases only the cancelled waiter", async (answer) => { const origin = new Producer(); - const dynamic = origin.dynamic(Path.from("room")); + const dynamic = origin.dynamicRoute(Path.from("room")); const requests = dynamic.requested(); const wire = wireOf(origin.consume()); const hold = new AbortController(); @@ -527,7 +527,7 @@ test.each(["accept", "reject"] as const)( test.each([true, false])("last waiter cancellation and accept in one turn (cancel first: %s)", async (cancelFirst) => { const origin = new Producer(); - const dynamic = origin.dynamic(Path.from("room")); + const dynamic = origin.dynamicRoute(Path.from("room")); const requests = dynamic.requested(); const wire = wireOf(origin.consume()); const hold = new AbortController(); @@ -568,7 +568,7 @@ test.each([true, false])("last waiter cancellation and accept in one turn (cance test.each([true, false])("local demand survives same-turn cancellation only when rejoined: %s", async (rejoin) => { const origin = new Producer(); - const dynamic = origin.dynamic(Path.from("room")); + const dynamic = origin.dynamicRoute(Path.from("room")); const requests = dynamic.requested(); const local = origin.request(path); const hold = new AbortController(); @@ -614,7 +614,7 @@ test.each([true, false])("local demand survives same-turn cancellation only when test("queued cancellation preserves order, replacement identity, and empty-queue wakeup", async () => { const origin = new Producer(); - const dynamic = origin.dynamic(Path.from("room")); + const dynamic = origin.dynamicRoute(Path.from("room")); const requests = dynamic.requested(); const wire = wireOf(origin.consume()); const holds = Array.from({ length: 4 }, () => new AbortController()); @@ -640,7 +640,7 @@ test("queued cancellation preserves order, replacement identity, and empty-queue test("reset clears queued work while a handler is suspended and admits the new epoch", async () => { const origin = new Producer(); const epoch = Epoch.mint(); - const dynamic = origin.dynamic(Path.from("room"), { epoch }); + const dynamic = origin.dynamicRoute(Path.from("room"), { epoch }); const requests = dynamic.requested(); const wire = wireOf(origin.consume()); const waits = [path, Path.from("room/obsolete")].map((name) => wire.demand(name, epoch).catch(() => {})); @@ -648,7 +648,7 @@ test("reset clears queued work while a handler is suspended and admits the new e const old = (await requests.next()).value; expect(old?.path).toBe(path); const nextEpoch = Epoch.mint(); - dynamic.update({ epoch: nextEpoch }); + dynamic.updateRoute({ epoch: nextEpoch }); waits.push(wire.demand(path, nextEpoch).catch(() => {})); const fresh = (await requests.next()).value; expect(fresh?.path).toBe(path); @@ -664,7 +664,7 @@ test("reset clears queued work while a handler is suspended and admits the new e test("concurrent handlers consume queued requests once across empty batches", async () => { const origin = new Producer(); - const dynamic = origin.dynamic(Path.from("room")); + const dynamic = origin.dynamicRoute(Path.from("room")); const handlers = [dynamic.requested(), dynamic.requested()]; const wire = wireOf(origin.consume()); const waits: Promise[] = []; diff --git a/js/net/src/origin-request.test.ts b/js/net/src/origin-request.test.ts index 18b4ec663b2..4a92d9b7113 100644 --- a/js/net/src/origin-request.test.ts +++ b/js/net/src/origin-request.test.ts @@ -140,7 +140,7 @@ test("announced requests follow the serving prefix, ignoring descendants and re- const origin = new Producer(); const source = new BroadcastProducer(); const keeper = source.consume(); - const prefix = origin.dynamic(Path.from("pool")); + const prefix = origin.dynamicRoute(Path.from("pool")); const serving = (async () => { for await (const request of prefix.requested()) request.accept(source.consume()); })(); @@ -155,7 +155,7 @@ test("announced requests follow the serving prefix, ignoring descendants and re- exact.announce(); await settle(); expect(request.active.peek()?.closed).toBe(exact.closed); - prefix.update({ cost: 5n }); + prefix.updateRoute({ cost: 5n }); await settle(); expect(request.active.peek()?.closed).toBe(exact.closed); exact.close(); @@ -176,7 +176,7 @@ test("announced requests follow the serving prefix, ignoring descendants and re- test("an announced request ignores a covering route whose scope excludes its path", async () => { const origin = new Producer(); const scoped = origin.scope(Path.empty(), new Path.Patterns([Path.Pattern.parse("room/*/chat")])); - const prefix = scoped.dynamic(Path.from("room/alice")); + const prefix = scoped.dynamicRoute(Path.from("room/alice")); const exact = origin.createBroadcast(Path.from("room/alice")); exact.announce({ cost: 5n }); const request = origin.request(Path.from("room/alice"), { announced: true }); @@ -193,7 +193,7 @@ test("an announced request follows an epochless route replaced by an identical o const origin = new Producer(); const path = Path.from("room"); const serve = (source: BroadcastProducer) => { - const route = origin.dynamic(path); + const route = origin.dynamicRoute(path); void (async () => { for await (const request of route.requested()) request.accept(source.consume()); })(); @@ -224,7 +224,7 @@ test("an origin closing settles an announced request a served route resolved", a const origin = new Producer(); const path = Path.from("room"); const source = new BroadcastProducer(); - const route = origin.dynamic(path); + const route = origin.dynamicRoute(path); void (async () => { for await (const request of route.requested()) request.accept(source.consume()); })(); @@ -243,14 +243,14 @@ test("an origin closing settles an announced request a served route resolved", a test("an announced request keeps a refusal that lands with a re-price", async () => { const origin = new Producer(); const path = Path.from("room"); - const route = origin.dynamic(path); + const route = origin.dynamicRoute(path); const requested = route.requested(); const request = origin.request(path, { announced: true }); const pending = (await requested.next()).value; if (!pending) throw new Error("expected a request"); // Both land in one turn: the watch notification must not retry the refused request. - route.update({ cost: 5n }); + route.updateRoute({ cost: 5n }); const denied = new Error("denied"); pending.reject(denied); await settle(); @@ -274,7 +274,7 @@ for (const received of [false, true]) { const events: string[] = []; const stop = wireOf(origin).interests((prefix, wanted) => events.push(`${prefix} ${wanted}`)); const source = new BroadcastProducer(); - const route = received ? wireOf(origin).receive(path, Route.default) : origin.dynamic(path); + const route = received ? wireOf(origin).receive(path, Route.default) : origin.dynamicRoute(path); void (async () => { for await (const request of route.requested()) request.accept(source.consume()); })(); @@ -294,3 +294,113 @@ for (const received of [false, true]) { origin.close(); }); } + +test("a claim answer is hidden until published under its own epoch", async () => { + const origin = new Producer(); + const path = Path.from("room/alice"); + const claim = origin.dynamic(Path.from("room")); + const requests = claim.requested(); + const request = origin.request(path); + const pending = (await requests.next()).value; + if (!pending) throw new Error("expected a request"); + const epoch = Epoch.mint(); + const prepared = pending.prepare(epoch); + prepared.broadcast.createTrack("video"); + await settle(); + expect(request.active.peek()).toBeUndefined(); + const published = prepared.publish(); + await settle(); + expect(request.active.peek()?.epoch).toBe(epoch); + request.close(); + published.close(); + claim.close(); + origin.close(); +}); + +test("a prepared answer cannot announce itself before publish", async () => { + const origin = new Producer(); + const path = Path.from("room/alice"); + const claim = origin.dynamic(Path.from("room")); + const requests = claim.requested(); + const request = origin.request(path); + const pending = (await requests.next()).value; + if (!pending) throw new Error("expected a request"); + const epoch = Epoch.mint(); + const prepared = pending.prepare(epoch); + expect(() => prepared.broadcast.announce({ epoch: Epoch.mint() })).toThrow("not attached to an origin"); + expect(prepared.broadcast.route).toBeUndefined(); + await settle(); + expect(request.active.peek()).toBeUndefined(); + const published = prepared.publish(); + expect(published.route?.epoch).toBe(epoch); + await settle(); + expect(request.active.peek()?.epoch).toBe(epoch); + request.close(); + published.close(); + claim.close(); + origin.close(); +}); + +test("an application claim refuses an arbitrary broadcast", async () => { + const origin = new Producer(); + const claim = origin.dynamic(Path.from("room")); + const requests = claim.requested(); + const request = origin.request(Path.from("room/alice")); + const pending = (await requests.next()).value; + if (!pending) throw new Error("expected a request"); + expect(() => pending.accept(new BroadcastProducer())).toThrow("prepared and published"); + request.close(); + claim.close(); + origin.close(); +}); + +test("rejecting a prepared answer refuses the request and closes its broadcast", async () => { + const origin = new Producer(); + const claim = origin.dynamic(Path.from("room")); + const requests = claim.requested(); + const request = origin.request(Path.from("room/alice")); + const pending = (await requests.next()).value; + if (!pending) throw new Error("expected a request"); + const prepared = pending.prepare(Epoch.mint()); + prepared.reject(new Error("no output")); + await settle(); + expect(request.closed.peek()).toBeInstanceOf(Error); + expect(prepared.broadcast.closed.peek()).toBeDefined(); + claim.close(); + origin.close(); +}); + +test("a prepared answer that fails to publish refuses the request", async () => { + const origin = new Producer(); + const claim = origin.dynamic(Path.from("room")); + const requests = claim.requested(); + const request = origin.request(Path.from("room/alice")); + const pending = (await requests.next()).value; + if (!pending) throw new Error("expected a request"); + const prepared = pending.prepare(Epoch.mint()); + prepared.broadcast.close(); + expect(() => prepared.publish()).toThrow("broadcast is closed"); + await settle(); + expect(request.closed.peek()).toBeInstanceOf(Error); + claim.close(); + origin.close(); +}); + +test("an answer prepared for an abandoned claim is never announced", async () => { + const origin = new Producer(); + const path = Path.from("room/alice"); + const claim = origin.dynamic(Path.from("room")); + const requests = claim.requested(); + const request = origin.request(path); + const pending = (await requests.next()).value; + if (!pending) throw new Error("expected a request"); + const prepared = pending.prepare(Epoch.mint()); + claim.close(); + expect(() => prepared.publish()).toThrow("request is closed"); + const announced = origin.request(path, { announced: true }); + await settle(); + expect(announced.active.peek()).toBeUndefined(); + announced.close(); + request.close(); + origin.close(); +}); diff --git a/js/net/src/origin.test.ts b/js/net/src/origin.test.ts index 132044695d0..23ffd232ab3 100644 --- a/js/net/src/origin.test.ts +++ b/js/net/src/origin.test.ts @@ -91,10 +91,10 @@ test("a borrowed table exposes dynamic serving and a live scoped broadcast map", expect(changes.some((value) => value.get(localPath)?.cost === 4n)).toBe(true); const prefix = Path.from("room"); - const dynamic = table.dynamic(prefix, { cost: 2n }); + const dynamic = table.dynamicRoute(prefix, { cost: 2n }); await new Promise((resolve) => setImmediate(resolve)); expect(live.peek().get(prefix)).toEqual(Route.normalize({ cost: 2n })); - dynamic.update({ cost: 3n }); + dynamic.updateRoute({ cost: 3n }); await settle(); await new Promise((resolve) => setImmediate(resolve)); expect(live.peek().get(prefix)).toEqual(Route.normalize({ cost: 3n })); @@ -668,7 +668,7 @@ test("an identical reconnect restarts without an epoch and is quiet with one", a // Retracting the stale twin is quiet, and a re-price of the winner is an update. old.close(); - fresh.update({ ...route, cost: 5n }); + fresh.updateRoute({ ...route, cost: 5n }); expect(await announced.next()).toMatchObject({ prefix: path, kind: "update", route: { cost: 5n } }); fresh.close(); @@ -1256,7 +1256,7 @@ test("a preference outside a signed byte is refused", () => { test("a handle serves a request under live", async () => { const origin = new Producer(); const consumer = origin.consume(); - const handle = origin.dynamic(Path.from("live")); + const handle = origin.dynamicRoute(Path.from("live")); expect(await consumer.announced().next()).toMatchObject({ prefix: Path.from("live"), kind: "start" }); @@ -1283,7 +1283,7 @@ test("a handle serves a request under live", async () => { test("an originated route refuses a broadcast a session delivered", async () => { const origin = new Producer(); - const handle = origin.dynamic(Path.from("live")); + const handle = origin.dynamicRoute(Path.from("live")); const it = handle.requested(); const pending = wireOf(origin.consume()).demand(Path.from("live/cam")); const { value: req } = await it.next(); @@ -1326,10 +1326,10 @@ test("a received route still serves a broadcast a session delivered", async () = test("a re-priced route is delivered as an update", async () => { const origin = new Producer(); - const handle = origin.dynamic(Path.from("live")); + const handle = origin.dynamicRoute(Path.from("live")); const announced = origin.consume().announced(); expect(await announced.next()).toMatchObject({ prefix: Path.from("live"), kind: "start" }); - handle.update({ cost: 5n }); + handle.updateRoute({ cost: 5n }); expect(await announced.next()).toMatchObject({ prefix: Path.from("live"), kind: "update" }); handle.close(); expect(await announced.next()).toMatchObject({ prefix: Path.from("live"), kind: "end" }); @@ -1339,7 +1339,7 @@ test("a re-priced route is delivered as an update", async () => { test("an accepted dynamic broadcast is retired when it closes", async () => { const origin = new Producer(); - const handle = origin.dynamic(Path.from("live")); + const handle = origin.dynamicRoute(Path.from("live")); const path = Path.from("live/cam"); const request = origin.request(path); const it = handle.requested(); @@ -1371,7 +1371,7 @@ test("an accepted dynamic broadcast is retired when it closes", async () => { test("reject surfaces the error from demand", async () => { const origin = new Producer(); - const handle = origin.dynamic(Path.from("live")); + const handle = origin.dynamicRoute(Path.from("live")); const consumer = origin.consume(); const it = handle.requested(); const pending = wireOf(consumer).demand(Path.from("live/cam")); @@ -1388,8 +1388,8 @@ test("a peer is offered and served the cheapest originated route", async () => { const origin = new Producer(); const consumer = origin.consume(); const prefix = Path.from("live"); - const cheap = origin.dynamic(prefix, { epoch: EPOCH, cost: 1n }); - const pricey = origin.dynamic(prefix, { epoch: EPOCH, cost: 10n }); + const cheap = origin.dynamicRoute(prefix, { epoch: EPOCH, cost: 1n }); + const pricey = origin.dynamicRoute(prefix, { epoch: EPOCH, cost: 10n }); expect(wireOf(consumer).advertised.peek()?.get(prefix)?.[0]?.route).toEqual( Route.normalize({ epoch: EPOCH, cost: 1n }), @@ -1420,7 +1420,7 @@ test("a peer is offered and served the cheapest originated route", async () => { test("a shared reject still surfaces from demand", async () => { const origin = new Producer(); - const handle = origin.dynamic(Path.from("live")); + const handle = origin.dynamicRoute(Path.from("live")); const consumer = origin.consume(); const it = handle.requested(); @@ -1442,7 +1442,7 @@ test("a shared reject still surfaces from demand", async () => { test("a request refusal does not keep demand from asking again", async () => { const origin = new Producer(); - const handle = origin.dynamic(Path.from("live")); + const handle = origin.dynamicRoute(Path.from("live")); const consumer = origin.consume(); const it = handle.requested(); @@ -1466,7 +1466,7 @@ test("a request refusal does not keep demand from asking again", async () => { test("advancing requested without settling rejects the previous request", async () => { const origin = new Producer(); - const handle = origin.dynamic(Path.from("live")); + const handle = origin.dynamicRoute(Path.from("live")); const consumer = origin.consume(); const it = handle.requested(); @@ -1490,7 +1490,7 @@ test("advancing requested without settling rejects the previous request", async test("a rejected request is not asked of the same route again", async () => { const origin = new Producer(); - const handle = origin.dynamic(Path.from("live")); + const handle = origin.dynamicRoute(Path.from("live")); const it = handle.requested(); const request = origin.request(Path.from("live/cam")); @@ -1805,8 +1805,8 @@ test("a request ends when its winning source goes, even with a standby", async ( test("a refusal is terminal, never falling through to a broader route", async () => { const origin = new Producer(); const consumer = origin.consume(); - const narrow = origin.dynamic(Path.from("live")); - const wide = origin.dynamic(Path.from("")); + const narrow = origin.dynamicRoute(Path.from("live")); + const wide = origin.dynamicRoute(Path.from("")); const wideRequests = wide.requested(); const wideAsked = wideRequests.next(); @@ -1843,8 +1843,8 @@ test("a better route's refusal ends a served request", async () => { // The narrower route is asked while the broad one keeps serving, then says no. A // costlier sibling at the same prefix could serve, but is never asked. - const narrow = origin.dynamic(Path.from("live"), { epoch: EPOCH, cost: 1n }); - const sibling = origin.dynamic(Path.from("live"), { epoch: EPOCH, cost: 2n }); + const narrow = origin.dynamicRoute(Path.from("live"), { epoch: EPOCH, cost: 1n }); + const sibling = origin.dynamicRoute(Path.from("live"), { epoch: EPOCH, cost: 2n }); const siblingRequests = sibling.requested(); const siblingAsked = siblingRequests.next(); const { value: req } = await narrow.requested().next(); @@ -1869,14 +1869,14 @@ test("a better route's refusal ends a served request", async () => { test("a refusal from a superseded route does not end the request", async () => { const origin = new Producer(); const consumer = origin.consume(); - const wide = origin.dynamic(Path.from("")); + const wide = origin.dynamicRoute(Path.from("")); const wideRequests = wide.requested(); const request = consumer.request(Path.from("live/cam")); const { value: stale } = await wideRequests.next(); // A narrower route takes over the pending request before the broad one answers. - const narrow = origin.dynamic(Path.from("live")); + const narrow = origin.dynamicRoute(Path.from("live")); const { value: req } = await narrow.requested().next(); stale?.reject(new Error("unserved")); await settle(); @@ -1898,7 +1898,7 @@ test("a refusal from a superseded route does not end the request", async () => { test("a refusal from a route a local broadcast superseded does not end the request", async () => { const origin = new Producer(); const consumer = origin.consume(); - const wide = origin.dynamic(Path.from("live")); + const wide = origin.dynamicRoute(Path.from("live")); const wideRequests = wide.requested(); const request = consumer.request(Path.from("live/cam")); @@ -1924,7 +1924,7 @@ test("a refusal from a route a local broadcast superseded does not end the reque test("close rejects queued requests as unroutable", async () => { const origin = new Producer(); - const handle = origin.dynamic(Path.from("live")); + const handle = origin.dynamicRoute(Path.from("live")); const waiting = handle.requested().next(); const request = origin.request(Path.from("live/cam")); const { value: req } = await waiting; @@ -2067,7 +2067,7 @@ test("a rooted producer shares the table and enforces its pattern union", async await new Promise((resolve) => setImmediate(resolve)); expect(() => scoped.request(Path.from("room/alice/deep"))).toThrow("outside the origin scope"); await new Promise((resolve) => setImmediate(resolve)); - expect(() => scoped.dynamic(Path.from("other"))).toThrow("outside the origin scope"); + expect(() => scoped.dynamicRoute(Path.from("other"))).toThrow("outside the origin scope"); await new Promise((resolve) => setImmediate(resolve)); expect(() => scoped.scope(Path.empty(), new Path.Patterns([Path.Pattern.parse("other/**")]))).toThrow( "do not overlap", @@ -2092,7 +2092,7 @@ test("a rooted producer shares the table and enforces its pattern union", async test("a scoped dynamic only serves allowed paths and presents relative requests", async () => { const origin = new Producer(); const scoped = origin.scope(Path.from("tenant"), new Path.Patterns([Path.Pattern.parse("room/*/chat")])); - const dynamic = scoped.dynamic(Path.from("room")); + const dynamic = scoped.dynamicRoute(Path.from("room")); await new Promise((resolve) => setImmediate(resolve)); expect(dynamic.prefix).toBe(Path.from("room")); const denied = origin.request(Path.from("tenant/room/alice/video")); @@ -2107,7 +2107,7 @@ test("a scoped dynamic only serves allowed paths and presents relative requests" pending.value?.accept(broadcast); await new Promise((resolve) => setImmediate(resolve)); expect(request.active.peek()).toBeDefined(); - dynamic.update({ cost: 2n }); + dynamic.updateRoute({ cost: 2n }); await new Promise((resolve) => setImmediate(resolve)); expect((await announcedView(origin)).peek().get(Path.from("tenant/room"))?.cost).toBe(2n); await requests.return?.(); @@ -2138,7 +2138,9 @@ test("scoped wire views filter and rebase advertisements and blind requests", () test("a scoped dynamic is announced only to readers its scope can serve", async () => { const origin = new Producer(); - const dynamic = origin.scope(Path.empty(), new Path.Patterns([Path.Pattern.parse("*/chat")])).dynamic(Path.empty()); + const dynamic = origin + .scope(Path.empty(), new Path.Patterns([Path.Pattern.parse("*/chat")])) + .dynamicRoute(Path.empty()); const chat = origin.scope(Path.empty(), new Path.Patterns([Path.Pattern.parse("room/chat")])); const video = origin.scope(Path.empty(), new Path.Patterns([Path.Pattern.parse("room/video")])); await new Promise((resolve) => setImmediate(resolve)); @@ -2155,8 +2157,8 @@ test("a scoped dynamic is announced only to readers its scope can serve", async test("a rooted reader presents the most specific covering route", async () => { const origin = new Producer(); - const narrow = origin.dynamic(Path.from("room/alice"), { cost: 9n }); - const broad = origin.dynamic(Path.from("room"), { cost: 1n }); + const narrow = origin.dynamicRoute(Path.from("room/alice"), { cost: 9n }); + const broad = origin.dynamicRoute(Path.from("room"), { cost: 1n }); const rooted = origin.scope(Path.from("room/alice"), new Path.Patterns([Path.Pattern.all()])); await new Promise((resolve) => setImmediate(resolve)); expect((await announcedView(rooted)).peek().get(Path.empty())?.cost).toBe(9n); @@ -2170,8 +2172,8 @@ test("a rooted reader presents the most specific covering route", async () => { test("a scoped reader picks the best route its scope can see at a prefix", async () => { const origin = new Producer(); const scoped = (pattern: string) => origin.scope(Path.empty(), new Path.Patterns([Path.Pattern.parse(pattern)])); - const chat = scoped("*/chat").dynamic(Path.empty(), { cost: 1n }); - const video = scoped("*/video").dynamic(Path.empty(), { cost: 5n }); + const chat = scoped("*/chat").dynamicRoute(Path.empty(), { cost: 1n }); + const video = scoped("*/video").dynamicRoute(Path.empty(), { cost: 5n }); const reader = scoped("room/video"); await new Promise((resolve) => setImmediate(resolve)); @@ -2198,7 +2200,7 @@ test("a scoped reader sees a local broadcast that only loses to a route outside const origin = new Producer(); const chat = origin .scope(Path.empty(), new Path.Patterns([Path.Pattern.parse("room/*/chat")])) - .dynamic(Path.from("room/alice"), { epoch: EPOCH, cost: 0n }); + .dynamicRoute(Path.from("room/alice"), { epoch: EPOCH, cost: 0n }); const local = origin.createBroadcast(Path.from("room/alice")); local.announce({ epoch: EPOCH, cost: 5n }); const reader = origin.scope(Path.empty(), new Path.Patterns([Path.Pattern.parse("room/*")])); @@ -2232,7 +2234,7 @@ test("broadcast handles carry the path they were created or requested at", async expect(clone?.path).toBe(Path.from("room/alice")); // A dynamic handler's standalone broadcast is named by the request, too. - const dynamic = origin.dynamic(Path.from("live")); + const dynamic = origin.dynamicRoute(Path.from("live")); const request = origin.request(Path.from("live/bob")); const pending = await dynamic.requested().next(); const served = new BroadcastProducer(); @@ -2275,14 +2277,14 @@ test("demand held across an epoch change asks again, unless it named the old epo const origin = new Producer(); const consumer = origin.consume(); const path = Path.from("live/cam"); - const handle = origin.dynamic(Path.from("live"), { epoch: EPOCH }); + const handle = origin.dynamicRoute(Path.from("live"), { epoch: EPOCH }); const it = handle.requested(); const pinned = wireOf(consumer).demand(path, EPOCH); const unpinned = wireOf(consumer).demand(path); const { value: req } = await it.next(); // Another instance now serves the route: the old handler's answer is for the old one. - handle.update({ ...handle.route, epoch: NEWER }); + handle.updateRoute({ ...handle.route, epoch: NEWER }); req?.accept(new BroadcastProducer().consume()); await expect(pinned).rejects.toThrow("unroutable"); @@ -2304,13 +2306,13 @@ test("a demand refused across an epoch change does not lose the carried demand's const origin = new Producer(); const consumer = origin.consume(); const path = Path.from("live/cam"); - const handle = origin.dynamic(Path.from("live"), { epoch: EPOCH }); + const handle = origin.dynamicRoute(Path.from("live"), { epoch: EPOCH }); const it = handle.requested(); const unpinned = wireOf(consumer).demand(path); const pinned = wireOf(consumer).demand(path, EPOCH); await it.next(); - handle.update({ ...handle.route, epoch: NEWER }); + handle.updateRoute({ ...handle.route, epoch: NEWER }); await expect(pinned).rejects.toThrow("unroutable"); // The replacement's refusal reaches the demand that carried over. (await it.next()).value?.reject(new Error("gone")); @@ -2324,14 +2326,14 @@ test("a demand refused across an epoch change does not lose the carried demand's test("demand held across an epoch round trip still asks again", async () => { const origin = new Producer(); const path = Path.from("live/cam"); - const handle = origin.dynamic(Path.from("live"), { epoch: EPOCH }); + const handle = origin.dynamicRoute(Path.from("live"), { epoch: EPOCH }); const it = handle.requested(); const demanded = wireOf(origin.consume()).demand(path); const { value: req } = await it.next(); // Released by the first change; the epoch coming back does not undo that. - handle.update({ ...handle.route, epoch: NEWER }); - handle.update({ ...handle.route, epoch: EPOCH }); + handle.updateRoute({ ...handle.route, epoch: NEWER }); + handle.updateRoute({ ...handle.route, epoch: EPOCH }); req?.accept(new BroadcastProducer().consume()); const next = new BroadcastProducer(); @@ -2350,8 +2352,8 @@ test("demand held across an epoch round trip still asks again", async () => { test("re-pricing from the current route keeps the epoch", () => { const origin = new Producer(); - const handle = origin.dynamic(Path.from("live"), { epoch: EPOCH, cost: 5n }); - handle.update({ ...handle.route, cost: 1n }); + const handle = origin.dynamicRoute(Path.from("live"), { epoch: EPOCH, cost: 5n }); + handle.updateRoute({ ...handle.route, cost: 1n }); expect(handle.route).toEqual(Route.normalize({ epoch: EPOCH, cost: 1n })); const broadcast = origin.createBroadcast(Path.from("room")); @@ -2418,12 +2420,12 @@ test("a request held across an epoch change asks again and never takes the old h const origin = new Producer(); const prefix = Path.from("room"); const path = Path.from("room/cam"); - const dynamic = origin.dynamic(prefix, { epoch: EPOCH }); + const dynamic = origin.dynamicRoute(prefix, { epoch: EPOCH }); const unpinned = origin.consume().request(path); const pinned = origin.consume().request(path, { epoch: EPOCH }); const requests = dynamic.requested(); const old = (await requests.next()).value; - dynamic.update({ ...dynamic.route, epoch: NEWER }); + dynamic.updateRoute({ ...dynamic.route, epoch: NEWER }); const current = origin.consume().request(path, { epoch: NEWER }); old?.accept(new BroadcastProducer().consume()); await settle(); @@ -2453,7 +2455,7 @@ test.each([ const origin = new Producer(); const prefix = Path.from("live"); const path = Path.from("live/cam"); - const dynamic = origin.dynamic(prefix, { epoch: from }); + const dynamic = origin.dynamicRoute(prefix, { epoch: from }); const requests = dynamic.requested(); const announced = origin.consume().announced(); expect(await announced.next()).toMatchObject({ prefix, kind: "start" }); @@ -2471,7 +2473,7 @@ test.each([ expect((await sticky?.recvGroup())?.sequence).toBe(0); // A re-price at the same epoch keeps every handle, and the handler is not asked again. - dynamic.update({ ...dynamic.route, cost: 5n }); + dynamic.updateRoute({ ...dynamic.route, cost: 5n }); expect(await announced.next()).toMatchObject({ prefix, kind: "update" }); expect(held.active.peek()).toBe(resolved); const same = origin.consume().request(path); @@ -2480,7 +2482,7 @@ test.each([ const pinned = origin.consume().request(path, { epoch: from }); // Another epoch, or none, is another instance: resolved requests keep the old one. - dynamic.update({ ...dynamic.route, epoch: to }); + dynamic.updateRoute({ ...dynamic.route, epoch: to }); expect(await announced.next()).toMatchObject({ prefix, kind: "restart" }); await settle(); expect(held.active.peek()).toBe(resolved); @@ -2537,14 +2539,14 @@ test.each([ test("an epoch update does not retain an answer that already closed", async () => { const origin = new Producer(); const path = Path.from("live/cam"); - const dynamic = origin.dynamic(Path.from("live"), { epoch: EPOCH }); + const dynamic = origin.dynamicRoute(Path.from("live"), { epoch: EPOCH }); const requests = dynamic.requested(); const held = origin.consume().request(path); const old = new BroadcastProducer(); (await requests.next()).value?.accept(old); old.close(); // The server's closure callback has not removed the answer yet. - dynamic.update({ epoch: NEWER }); + dynamic.updateRoute({ epoch: NEWER }); try { expect(held.closed.peek()).toBeInstanceOf(Error); expect(held.active.peek()).toBeUndefined(); @@ -2565,13 +2567,13 @@ test("an epoch update does not retain an answer that already closed", async () = test("an unread resolved request retains its broadcast until its last handle closes", async () => { const origin = new Producer(); const path = Path.from("live/cam"); - const dynamic = origin.dynamic(Path.from("live"), { epoch: EPOCH }); + const dynamic = origin.dynamicRoute(Path.from("live"), { epoch: EPOCH }); const requests = dynamic.requested(); const held = origin.consume().request(path); const old = new BroadcastProducer(); (await requests.next()).value?.accept(old); // Change epochs before the active getter or its subscription can clone the answer. - dynamic.update({ epoch: NEWER }); + dynamic.updateRoute({ epoch: NEWER }); expect(old.closed.peek()).toBeUndefined(); expect(held.active.peek()?.epoch).toBe(EPOCH); held.close(); @@ -2586,7 +2588,7 @@ test("an unread resolved request retains its broadcast until its last handle clo test("a session's re-request after an epoch update asks the handler again", async () => { const origin = new Producer(); const path = Path.from("live/cam"); - const dynamic = origin.dynamic(Path.from("live"), { epoch: EPOCH }); + const dynamic = origin.dynamicRoute(Path.from("live"), { epoch: EPOCH }); const requests = dynamic.requested(); const wire = wireOf(origin.consume()); @@ -2595,7 +2597,7 @@ test("a session's re-request after an epoch update asks the handler again", asyn (await requests.next()).value?.accept(old); expect(await before).toBeDefined(); - dynamic.update({ ...dynamic.route, epoch: NEWER }); + dynamic.updateRoute({ ...dynamic.route, epoch: NEWER }); const after = wire.demand(path); const next = new BroadcastProducer(); const track = next.createTrack("video"); @@ -2616,8 +2618,8 @@ test("an update does not override route selection: another claim at the epoch ke const origin = new Producer(); const prefix = Path.from("live"); const path = Path.from("live/cam"); - const first = origin.dynamic(prefix, { epoch: EPOCH, cost: 1n }); - const second = origin.dynamic(prefix, { epoch: EPOCH, cost: 5n }); + const first = origin.dynamicRoute(prefix, { epoch: EPOCH, cost: 1n }); + const second = origin.dynamicRoute(prefix, { epoch: EPOCH, cost: 5n }); const firstRequests = first.requested(); const secondRequests = second.requested(); @@ -2629,7 +2631,7 @@ test("an update does not override route selection: another claim at the epoch ke // The first claim drops the epoch, so the second, still at it, outranks it: the // resolved request keeps its answer, and new requests go through the second claim. - first.update({ ...first.route, epoch: undefined }); + first.updateRoute({ ...first.route, epoch: undefined }); const fresh = origin.consume().request(path); const replacement = new BroadcastProducer(); const track = replacement.createTrack("video"); diff --git a/js/net/src/origin.ts b/js/net/src/origin.ts index 36046dacdb1..5ebfaa20587 100644 --- a/js/net/src/origin.ts +++ b/js/net/src/origin.ts @@ -447,6 +447,10 @@ class ServeState { this.settled.update((n) => n + 1); } + has(request: Request): boolean { + return this.closed.peek() === undefined && this.pending.get(Path.join(this.root, request.path)) === request; + } + reject(request: Request, err: Error): void { const path = Path.join(this.root, request.path); if (this.pending.get(path) !== request) return; @@ -1096,7 +1100,10 @@ export interface Table { announced(scope?: Path.Pattern, options?: announce.Options): announce.Consumer; /** Advertise a prefix and serve requests under it; see {@link Producer.dynamic}. */ - dynamic( + dynamic(prefix: Path.Valid): Dynamic; + + /** Insert a route with protocol metadata. @internal */ + dynamicRoute( prefix: Path.Valid, route?: Route | { epoch?: Route["epoch"]; hops?: Route["hops"]; cost?: Route["cost"]; auth?: Route["auth"] }, ): Dynamic; @@ -1290,7 +1297,12 @@ export class Producer implements Table { * the returned {@link Dynamic} lives. A consumer resolving a path under it that * no announced local broadcast wins is handed to the handle as a {@link Request}. */ - dynamic( + dynamic(prefix: Path.Valid): Dynamic { + return this.#insertRoute(prefix, Route.default, true, true); + } + + /** Insert an originated claim with route metadata that answers through `accept`, for tests and benches. @internal */ + dynamicRoute( prefix: Path.Valid, route: | Route @@ -1301,7 +1313,7 @@ export class Producer implements Table { auth?: Route["auth"]; } = Route.default, ): Dynamic { - return this.#insertRoute(prefix, Route.normalize(route), true); + return this.#insertRoute(prefix, Route.normalize(route), true, false); } /** @@ -1321,10 +1333,10 @@ export class Producer implements Table { auth?: Route["auth"]; } = Route.default, ): Dynamic { - return this.#insertRoute(prefix, Route.normalize(route), false); + return this.#insertRoute(prefix, Route.normalize(route), false, false); } - #insertRoute(prefix: Path.Valid, route: Route, originated: boolean): Dynamic { + #insertRoute(prefix: Path.Valid, route: Route, originated: boolean, publishes: boolean): Dynamic { prefix = this.#scope.prefix(prefix); const server = new ServeState(this.#scope.root, originated); server.onChange = (path) => this.#state.refresh(path); @@ -1351,7 +1363,7 @@ export class Producer implements Table { }); if (closed) { server.close(); - return makeDynamic(prefix, entry, this.#state, () => {}); + return makeDynamic(prefix, entry, this.#state, () => {}, publishes ? this : undefined); } this.#state.rebuildOriginated(); this.#state.refreshPrefix(prefix); @@ -1370,7 +1382,7 @@ export class Producer implements Table { this.#state.refreshPrefix(prefix); }; - return makeDynamic(prefix, entry, this.#state, retract); + return makeDynamic(prefix, entry, this.#state, retract, publishes ? this : undefined); } /** @@ -1554,7 +1566,13 @@ let makeRequesting: ( dispose: Dispose, ) => Requesting; -let makeDynamic: (prefix: Path.Valid, entry: RouteEntry, state: OriginState, retract: Dispose) => Dynamic; +let makeDynamic: ( + prefix: Path.Valid, + entry: RouteEntry, + state: OriginState, + retract: Dispose, + publisher?: Producer, +) => Dynamic; let makeRequest: (path: Path.Valid, server: ServeState) => Request; let finishRequest: (request: Request, err: Error) => void; @@ -2230,17 +2248,26 @@ export class Dynamic { #entry: RouteEntry; #state: OriginState; #retract: Dispose; + #publisher?: Producer; #closed = false; - private constructor(prefix: Path.Valid, entry: RouteEntry, state: OriginState, retract: Dispose) { + private constructor( + prefix: Path.Valid, + entry: RouteEntry, + state: OriginState, + retract: Dispose, + publisher?: Producer, + ) { this.prefix = Path.stripPrefix(entry.scope.root, prefix) ?? Path.empty(); this.#entry = entry; this.#state = state; this.#retract = retract; + this.#publisher = publisher; } static { - makeDynamic = (prefix, entry, state, retract) => new Dynamic(prefix, entry, state, retract); + makeDynamic = (prefix, entry, state, retract, publisher) => + new Dynamic(prefix, entry, state, retract, publisher); } /** The route this handle advertises. */ @@ -2261,9 +2288,12 @@ export class Dynamic { * request for one of those paths asks the handler again too. The broadcasts it served keep * running for the subscriptions already on them; close them to end those too. * Route selection still applies: another route still at the old epoch outranks one - * without. To re-price, start from the current route, `update({ ...dynamic.route, cost })`. + * without. To re-price, start from the current route, `updateRoute({ ...dynamic.route, cost })`. + * + * @internal */ - update( + // pending: /quest/m1/public-model/answer.md + updateRoute( route: Route | { epoch?: Route["epoch"]; hops?: Route["hops"]; cost?: Route["cost"]; auth?: Route["auth"] }, ): void { if (this.#closed) throw new Error("dynamic is closed"); @@ -2284,7 +2314,7 @@ export class Dynamic { this.#retract(); } - /** Requests under this prefix, as they arrive, each to {@link Request.accept} or reject. */ + /** Requests under this prefix, as they arrive, each to {@link Request.prepare} or reject. */ async *requested(): AsyncIterableIterator { const server = this.#entry.server; if (!server) return; @@ -2304,6 +2334,7 @@ export class Dynamic { queue.delete(next.value); }); current = next.value; + current.publisher = this.#publisher; yield next.value; continue; } @@ -2333,6 +2364,8 @@ export class Request { #server: ServeState; #done = false; #withdrawn = false; + /** @internal Set only by an application claim. */ + publisher?: Producer; private constructor(path: Path.Valid, server: ServeState) { this.path = path; @@ -2348,18 +2381,54 @@ export class Request { }; } + /** Start answering as a new publisher instance, hidden until published. */ + prepare(epoch: Epoch.Valid): Prepared { + if (this.#done) throw new Error("request is closed"); + if (!this.publisher) throw new Error("forwarded requests cannot be prepared"); + this.#done = true; + const answer = this.publisher.createBroadcast(this.path); + // Withheld until publish, so the answer cannot announce itself under another + // epoch or skip the request's admission. + const announcer = hooks.withholdAnnouncer(answer); + if (!announcer) throw new Error("origin is closed"); + return new Prepared(this, answer, announcer, epoch); + } + + /** @internal Publish a prepared answer after its tracks have been filled. */ + publishPrepared( + answer: broadcast.Producer, + announcer: broadcast.Announcer, + epoch: Epoch.Valid, + ): broadcast.Producer { + if (!this.#server.has(this)) throw new Error("request is closed"); + if (answer.closed.peek() !== undefined) throw new Error("broadcast is closed"); + hooks.attachAnnouncer(answer, announcer); + // The exact route usually settles the request on its own, resolving its waiters + // through the new epoch; answer it directly if it is still pending. + answer.announce({ epoch }); + if (this.#server.has(this)) this.#server.accept(this, answer.consume()); + return answer; + } + + /** @internal Refuse the request a prepared answer abandoned. */ + rejectPrepared(err: Error): void { + this.#server.reject(this, err); + } + /** - * Accept the request, resolving every awaiting requester with `broadcast`. + * Resolve a session-forwarded request with its peer's routed broadcast. * * The caller keeps producing into `broadcast`; repeat requests for the path share * it for as long as it stays live. * * A JS app does not proxy: a broadcast a session delivered would go out labeled with - * this origin's hop. To serve upstream content, copy its tracks into a broadcast you - * produce and accept that. + * this origin's hop. To serve upstream content, copy its tracks into a prepared answer + * and publish it. * * @throws Error when handed a broadcast a session delivered. The request stays open. + * @internal */ + // pending: /quest/m1/public-model/answer.md accept(source: broadcast.Producer | broadcast.Consumer): void { if (this.#done) { // A withdrawn request takes no answer. Only the handed-off consumer is ours; @@ -2367,6 +2436,7 @@ export class Request { if (this.#withdrawn && source instanceof broadcast.Consumer) source.close(); return; } + if (this.publisher) throw new Error("claim answers must be prepared and published"); if (this.#server.originated && !(source instanceof broadcast.Producer) && wireOf(source).fromSession) { throw new Error("origin cannot serve a broadcast it did not produce"); } @@ -2382,3 +2452,42 @@ export class Request { this.#server.reject(this, err); } } + +/** A claim answer being filled before its exact route is announced. */ +export class Prepared { + /** The unannounced broadcast to fill before publishing; only {@link publish} announces it. */ + readonly broadcast: broadcast.Producer; + readonly #request: Request; + readonly #announcer: broadcast.Announcer; + readonly #epoch: Epoch.Valid; + #done = false; + + /** @internal */ + constructor(request: Request, answer: broadcast.Producer, announcer: broadcast.Announcer, epoch: Epoch.Valid) { + this.#request = request; + this.broadcast = answer; + this.#announcer = announcer; + this.#epoch = epoch; + } + + /** Announce the filled broadcast and resolve every waiting requester, refusing them if it cannot be announced. */ + publish(): broadcast.Producer { + if (this.#done) throw new Error("prepared answer is closed"); + this.#done = true; + try { + return this.#request.publishPrepared(this.broadcast, this.#announcer, this.#epoch); + } catch (err) { + this.broadcast.close(); + this.#request.rejectPrepared(err instanceof Error ? err : new Error(String(err))); + throw err; + } + } + + /** Abandon the answer unpublished, closing its broadcast and resolving every waiting requester with `err`. */ + reject(err: Error): void { + if (this.#done) return; + this.#done = true; + this.broadcast.close(); + this.#request.rejectPrepared(err); + } +} diff --git a/js/net/src/untimed.test.ts b/js/net/src/untimed.test.ts index e839f281006..146a85c52c6 100644 --- a/js/net/src/untimed.test.ts +++ b/js/net/src/untimed.test.ts @@ -129,7 +129,7 @@ test("a forwarded untimed track stays untimed", async () => { // Serve the downstream session from the upstream one. A JS origin refuses to serve a // broadcast a session delivered, so the forwarding node republishes a copy it produced. - const dynamic = relay.dynamic(Path.from("test")); + const dynamic = relay.dynamicRoute(Path.from("test")); const inputs: BroadcastConsumer[] = []; const forwarding = (async () => { for await (const request of dynamic.requested()) { diff --git a/js/watch/src/broadcast.test.ts b/js/watch/src/broadcast.test.ts index bef9431ea36..1077c92a6e9 100644 --- a/js/watch/src/broadcast.test.ts +++ b/js/watch/src/broadcast.test.ts @@ -307,7 +307,7 @@ describe("blind resolution", () => { // Stand in for a dynamic route answering the request. const upstream = new Moq.Broadcast.Producer(); - const route = owner.dynamic(Path.from("blind.hang")); + const route = owner.dynamicRoute(Path.from("blind.hang")); const requests = route.requested(); const next = await requests.next(); expect(next.done).toBe(false); @@ -419,7 +419,7 @@ describe("restart", () => { it("moves to a more specific announcement of another instance", async () => { const owner = new Origin.Producer(); const name = Path.from("pool/job.hang"); - const pool = owner.dynamic(Path.from("pool"), { epoch: Moq.Epoch.mint() }); + const pool = owner.dynamicRoute(Path.from("pool"), { epoch: Moq.Epoch.mint() }); const requests = pool.requested(); const upstream = new Moq.Broadcast.Producer(); void (async () => { @@ -465,7 +465,7 @@ describe("restart", () => { // The exact route goes, which ends the request on it, and the prefix arrives under the same // epoch before the table is read again. The player still has to ask again. exact.close(); - const pool = owner.dynamic(Path.from("pool"), { epoch }); + const pool = owner.dynamicRoute(Path.from("pool"), { epoch }); const requests = pool.requested(); const upstream = new Moq.Broadcast.Producer(); void (async () => { @@ -487,7 +487,7 @@ describe("restart", () => { it("falls back to a covering prefix when the exact route ends", async () => { const owner = new Origin.Producer(); const name = Path.from("pool/job.hang"); - const pool = owner.dynamic(Path.from("pool")); + const pool = owner.dynamicRoute(Path.from("pool")); const requests = pool.requested(); const upstream = new Moq.Broadcast.Producer(); void (async () => { @@ -525,7 +525,7 @@ describe("refusal", () => { const owner = new Origin.Producer(); const name = Path.from("room/live.hang"); const upstream = new Moq.Broadcast.Producer(); - const first = owner.dynamic(Path.from("room"), { epoch: Moq.Epoch.mint() }); + const first = owner.dynamicRoute(Path.from("room"), { epoch: Moq.Epoch.mint() }); const firstRequests = first.requested(); void (async () => { for await (const request of firstRequests) request.accept(upstream); @@ -535,7 +535,7 @@ describe("refusal", () => { expect(source.out.active.peek()).toBeDefined(); // The restarted publisher refuses with the same code an ended instance reports. - const second = owner.dynamic(Path.from("room"), { epoch: Moq.Epoch.mint() }); + const second = owner.dynamicRoute(Path.from("room"), { epoch: Moq.Epoch.mint() }); const refused = await second.requested().next(); refused.value?.reject(new Moq.Error.Stream(Moq.StreamCode.Unroutable, { message: "refused" })); await settle(); @@ -573,7 +573,7 @@ describe("refusal", () => { for (const announced of [true, false]) { it(`reports a refusal until a fresh request (announced: ${announced})`, async () => { const owner = new Origin.Producer(); - const route = owner.dynamic(Path.from("room")); + const route = owner.dynamicRoute(Path.from("room")); const requests = route.requested(); const name = new Signal(Path.from("room/refused.hang")); const enabled = new Signal(true); @@ -855,7 +855,7 @@ describe("wildcard renditions", () => { await settle(); expect(videoRenditions(source)).toEqual(["source"]); - const worker = owner.dynamic(Path.from(".pro/transcode")); + const worker = owner.dynamicRoute(Path.from(".pro/transcode")); const requests = worker.requested(); await settle(); expect(videoRenditions(source)).toEqual(["source", "transcode"]); @@ -904,8 +904,8 @@ describe("wildcard renditions", () => { try { // A catch-all (an archive) and a narrower pool both cover the derived path. - const archive = owner.dynamic(Path.empty()); - const worker = owner.dynamic(Path.from(".pro/transcode")); + const archive = owner.dynamicRoute(Path.empty()); + const worker = owner.dynamicRoute(Path.from(".pro/transcode")); await settle(); expect(videoRenditions(source)).toEqual(["source", "transcode"]); diff --git a/kt/moq/MIGRATE.md b/kt/moq/MIGRATE.md index 9a3ad22f29e..2518129a1a8 100644 --- a/kt/moq/MIGRATE.md +++ b/kt/moq/MIGRATE.md @@ -4,6 +4,11 @@ How to update your code for each breaking change, newest first. ## Unreleased +### A claim answers by publishing (#5678) + +`OriginProducer.dynamic(prefix)` takes no route, and `OriginDynamic.update` is gone. +Replace `request.accept(broadcast)` with `request.prepare(mintEpoch())`, which returns a `BroadcastPrepared`: fill its `broadcast()`, then `publish()` announces it at the exact path under that epoch and returns its producer. + ### Anchors can name a time (#6074) `Anchor` gains `AnchorTime`, so exhaustive `when` expressions need a branch for it. diff --git a/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/Aliases.kt b/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/Aliases.kt index 6430cf04fc7..340fc592348 100644 --- a/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/Aliases.kt +++ b/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/Aliases.kt @@ -43,6 +43,8 @@ typealias OriginConsumer = uniffi.moq.MoqOriginConsumer typealias OriginDynamic = uniffi.moq.MoqOriginDynamic /** A requested broadcast not yet accepted: fulfill it with a producer or reject it. */ typealias BroadcastRequest = uniffi.moq.MoqBroadcastRequest +/** A claim answer being filled before its exact route is announced. */ +typealias BroadcastPrepared = uniffi.moq.MoqBroadcastPrepared /** A stream of announce events under a prefix. */ typealias AnnounceConsumer = uniffi.moq.MoqAnnounceConsumer /** A literal prefix, an optional relative pattern, and the hidden-path opt-in for announcement discovery. */ diff --git a/kt/moq/src/jvmAndAndroidTest/kotlin/dev/moq/SmokeTest.kt b/kt/moq/src/jvmAndAndroidTest/kotlin/dev/moq/SmokeTest.kt index 691a8799972..5ff3aa1c585 100644 --- a/kt/moq/src/jvmAndAndroidTest/kotlin/dev/moq/SmokeTest.kt +++ b/kt/moq/src/jvmAndAndroidTest/kotlin/dev/moq/SmokeTest.kt @@ -165,7 +165,7 @@ class SmokeTest { fun `origin alias constructs and consumes`() = runTest { OriginProducer(OriginConfig()).use { origin -> origin.consume().use { /* lifecycle smoke */ } - origin.dynamic("", Route()).use { /* dynamic origin smoke */ } + origin.dynamic("").use { /* dynamic origin smoke */ } } } @@ -563,15 +563,14 @@ class SmokeTest { @Test fun `dynamic serves a request under a prefix`() = runTest { OriginProducer(OriginConfig()).use { origin -> - origin.dynamic("live", Route()).use { dynamic -> + origin.dynamic("live").use { dynamic -> val pending = async { origin.consume().requestBroadcast("live/cam") } val request = dynamic.requestedBroadcast() assertEquals("live/cam", request.path()) - BroadcastProducer().use { served -> - request.accept(served) - pending.await() + request.prepare(mintEpoch()).use { prepared -> + prepared.publish().use { pending.await() } } } } diff --git a/py/moq-rs/MIGRATE.md b/py/moq-rs/MIGRATE.md index 59f06c9963e..26f7bf2456e 100644 --- a/py/moq-rs/MIGRATE.md +++ b/py/moq-rs/MIGRATE.md @@ -4,6 +4,11 @@ How to update your code for each breaking change, newest first. ## Unreleased +### A claim answers by publishing (#5678) + +`OriginProducer.dynamic(prefix)` takes no route, and `OriginDynamic.update` is gone. +Replace `request.accept(broadcast)` with `prepared = request.prepare(moq.mint_epoch())`, fill `prepared.broadcast`, then `prepared.publish()`, which announces it at the exact path under that epoch and returns its producer. + ### Anchors can name a time (#6074) `Anchor` gains a `TIME` variant, the group containing a presentation time. diff --git a/py/moq-rs/README.md b/py/moq-rs/README.md index 1b7e3caf71f..349216e4252 100644 --- a/py/moq-rs/README.md +++ b/py/moq-rs/README.md @@ -238,10 +238,10 @@ Every handle whose cleanup is `cancel()` is an async context manager, so exiting - **`OriginProducer(*, cache_capacity_bytes=None)`**. Manage broadcast announcements. Set `cache_capacity_bytes` to bound cached groups under this origin. - `.consume() → OriginConsumer` - - `.dynamic(prefix, route=Route()) → OriginDynamic` + - `.dynamic(prefix) → OriginDynamic` - `.create_broadcast(path) → BroadcastProducer` - **`OriginDynamic`**. Async source of broadcasts requested by consumers. - - `await .requested_broadcast() → BroadcastRequest`. Call `.accept(broadcast)` to serve it, or `.reject(code)` to fail the requester. + - `await .requested_broadcast() → BroadcastRequest`. Call `.prepare(mint_epoch())`, fill its `.broadcast`, then `.publish()` to serve it under a new epoch, or `.reject(code)` to fail the requester. - Async iterator yielding `BroadcastRequest` - **`OriginConsumer`**. Discover broadcasts. - `.announced(prefix, filter=None) → AnnounceConsumer` (async iterator of `AnnounceEvent`: `AnnounceEventStart`, `AnnounceEventUpdate`, `AnnounceEventEnd`, or `AnnounceEventRestart`, each carrying an `Announce` whose `.route.epoch` names the publisher run; on a restart, request the path again); `filter` is a pattern relative to the literal prefix, while each `Announce.prefix` stays origin-relative and `.captures` reports wildcard matches diff --git a/py/moq-rs/moq/__init__.py b/py/moq-rs/moq/__init__.py index f564c37f84c..9bb50633df5 100644 --- a/py/moq-rs/moq/__init__.py +++ b/py/moq-rs/moq/__init__.py @@ -24,6 +24,7 @@ AnnounceEventRestart, AnnounceEventStart, AnnounceEventUpdate, + BroadcastPrepared, BroadcastRequest, OriginConsumer, OriginDynamic, @@ -91,6 +92,7 @@ "Bandwidth", "BroadcastConsumer", "BroadcastDynamic", + "BroadcastPrepared", "BroadcastProducer", "BroadcastRequest", "Client", diff --git a/py/moq-rs/moq/origin.py b/py/moq-rs/moq/origin.py index b08c1c8c2d7..df807b6f019 100644 --- a/py/moq-rs/moq/origin.py +++ b/py/moq-rs/moq/origin.py @@ -8,15 +8,13 @@ MoqAnnounceConsumer, MoqAnnouncedBroadcast, MoqAnnounceEvent, + MoqBroadcastPrepared, MoqBroadcastRequest, MoqOriginConfig, MoqOriginConsumer, MoqOriginDynamic, MoqOriginProducer, ) -from moq_ffi import ( - MoqRoute as Route, -) from ._stream import _Stream from .publish import BroadcastProducer @@ -115,15 +113,31 @@ def path(self) -> str: """The requested broadcast path.""" return self._inner.path() - def accept(self, broadcast: BroadcastProducer) -> None: - """Serve the request with an unannounced broadcast.""" - self._inner.accept(broadcast._inner) + def prepare(self, epoch: str) -> BroadcastPrepared: + """Start an answer under a new epoch, hidden until published.""" + return BroadcastPrepared(self._inner.prepare(epoch)) def reject(self, error_code: int) -> None: """Reject the request with an application error code.""" self._inner.reject(error_code) +class BroadcastPrepared: + """A claim answer being filled before its exact route is announced.""" + + def __init__(self, inner: MoqBroadcastPrepared) -> None: + self._inner = inner + + @property + def broadcast(self) -> BroadcastProducer: + """The unannounced broadcast to fill before publishing; only `publish` announces it.""" + return BroadcastProducer._from_inner(self._inner.broadcast()) + + def publish(self) -> BroadcastProducer: + """Announce the filled broadcast and resolve waiting requesters.""" + return BroadcastProducer._from_inner(self._inner.publish()) + + class OriginDynamic(_Stream[BroadcastRequest]): """A served route: advertises a prefix and yields requests beneath it. @@ -140,10 +154,6 @@ async def requested_broadcast(self) -> BroadcastRequest: """Await the next broadcast a consumer requested but that isn't published yet.""" return BroadcastRequest(await self._inner.requested_broadcast()) - def update(self, route: Route) -> None: - """Re-price the route in place: replace its hops and costs.""" - self._inner.update(route) - def cancel(self) -> None: """Stop serving and retract the route.""" self._inner.cancel() @@ -211,7 +221,7 @@ def consume(self) -> OriginConsumer: """Create a consumer that discovers the broadcasts this origin publishes.""" return OriginConsumer(self._inner.consume()) - def dynamic(self, prefix: str, route: Route | None = None) -> OriginDynamic: + def dynamic(self, prefix: str) -> OriginDynamic: """Advertise ``prefix`` and serve the requests beneath it. A route claims ``prefix`` and every path beneath it (``""`` claims every @@ -219,7 +229,7 @@ def dynamic(self, prefix: str, route: Route | None = None) -> OriginDynamic: are requested. Hold the returned handle while the route should stay advertised. """ - return OriginDynamic(self._inner.dynamic(prefix, route if route is not None else Route())) + return OriginDynamic(self._inner.dynamic(prefix)) def create_broadcast(self, path: str) -> BroadcastProducer: """Create a broadcast at ``path``, returning the producer that feeds it. diff --git a/py/moq-rs/tests/test_local.py b/py/moq-rs/tests/test_local.py index 38621566fa3..6b754cc3700 100644 --- a/py/moq-rs/tests/test_local.py +++ b/py/moq-rs/tests/test_local.py @@ -649,9 +649,9 @@ async def test_dynamic_broadcast_request(): request = await asyncio.wait_for(dynamic.requested_broadcast(), timeout=5.0) assert request.path == "dynamic/broadcast" - served = moq.BroadcastProducer() - track = served.publish_track("status", moq.TrackInfo(timescale=1_000_000)) - request.accept(served) + prepared = request.prepare(moq.mint_epoch()) + track = prepared.broadcast.publish_track("status", moq.TrackInfo(timescale=1_000_000)) + served = prepared.publish() with pytest.raises(Exception): _ = request.path @@ -1527,8 +1527,7 @@ async def test_dynamic_serves_a_request_under_a_prefix(): pending = asyncio.create_task(consumer.request_broadcast("live/cam")) request = await asyncio.wait_for(dynamic.requested_broadcast(), timeout=5.0) assert request.path == "live/cam" - served = moq.BroadcastProducer() - request.accept(served) + served = request.prepare(moq.mint_epoch()).publish() await asyncio.wait_for(pending, timeout=5.0) dynamic.cancel() served.close() diff --git a/py/moq-rs/tests/test_server.py b/py/moq-rs/tests/test_server.py index ee8aee91821..bf96e4be0d9 100644 --- a/py/moq-rs/tests/test_server.py +++ b/py/moq-rs/tests/test_server.py @@ -443,11 +443,12 @@ async def test_route_update_observes_restart(): """A route metadata update arrives as an AnnounceEventUpdate. The publisher re-prices its announced route; the subscriber observes the new - hop chain in place (no retraction), and cancelling retracts it. + hop chain in place (no retraction), and unannouncing retracts it. """ origin = moq.OriginProducer() async with moq.Server("127.0.0.1:0", tls_generate=["localhost"], publish=origin) as server: - announce = origin.dynamic("routed", moq.Route(hops=[42])) + announce = origin.create_broadcast("routed") + announce.announce(moq.Route(hops=[42])) serve_task = asyncio.create_task(server.serve()) try: @@ -464,14 +465,14 @@ async def test_route_update_observes_restart(): assert 77 not in first.announce.route.hops # The publisher advertises a longer chain: an in-place update. - announce.update(moq.Route(hops=[42, 77])) + announce.announce(moq.Route(hops=[42, 77])) updated = await next_route(announced) assert isinstance(updated, moq.AnnounceEventUpdate) assert updated.announce.prefix == "routed" assert 77 in updated.announce.route.hops - # Cancelling retracts the route. - announce.cancel() + # Unannouncing retracts the route. + announce.unannounce() ended = await next_route(announced) assert isinstance(ended, moq.AnnounceEventEnd) assert ended.announce.prefix == "routed" diff --git a/quest/m1/README.md b/quest/m1/README.md index 0cec85655e8..084221e12a8 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -62,7 +62,6 @@ lands before the cut. - [Refresh](/quest/m1/refresh/README.md) - a join asks for a fresh group once the current group's deltas exceed a publisher-advertised byte ratio, at every hop; replaces `Demand::used`/`unused` and moq-json's `delta_ratio` - [Compressed tracks](/quest/m1/compress/README.md) - a track flagged `compress` is DEFLATEd per group by moq-net, forwarded compressed, and inflated once on the relay for peers that cannot signal it; `catalog.json.z` and moq-flate go away - [Moxygen minimal interop](/quest/m1/smoke-moxygen.md) - waiting on Moxygen to send a registered filter type, then the smoke lane stops hiding its failure -- [Claim answer epochs](/quest/m1/claim-answer-epochs.md) - a claim answers each output by publishing it at its exact path under its own epoch, so a restarted output never reaches a returning reader as the old one's cache - [Readers see SUBSCRIBE_DROP](/quest/m1/subscribe-drop-errors.md) - a dropped or cut group ends its reader with an error, never a clean end, across cache reclaim, cap changes, and recovery - [Subscribe ranges](/quest/m1/subscribe-ranges/README.md) - a lite-07 SUBSCRIBE asks for past and live ranges with absolute or relative ends, in either order, and replaces FETCH; merged ranges never starve a subscriber; relays fill misses by range, including over moq-transport - [More tests under load](/quest/m1/test-flakes-2/README.md) - the second round of load-only failures, one quest per flake, fixed at the cause diff --git a/quest/m1/announce-takeover.md b/quest/m1/announce-takeover.md index 490c6e911ac..df845df6c34 100644 --- a/quest/m1/announce-takeover.md +++ b/quest/m1/announce-takeover.md @@ -88,11 +88,11 @@ ANNOUNCE_TAKEOVER; published versions retain their framing. ## Required -- [Claim answer epochs](/quest/m1/claim-answer-epochs.md) - `Request::prepare` then `publish` answers a claim at the exact path under a fresh epoch, the operation TAKEOVER continues - [Routes and announces](/quest/m1/cluster-routing/routes.md) - shared routing layer and per-stream identity ## Related +- [Claim answer epochs](https://github.com/moq-dev/moq/pull/5678) - `Request::prepare` then `publish` answers a claim at the exact path under a fresh epoch, the operation TAKEOVER continues - [IETF takeover](/quest/m1/ietf-takeover.md) - negotiated IETF counterpart - [Catalog references](/quest/m0/broadcast-epoch/catalog-references.md) - a proven continuation preserves the same pin - [Retired requests](https://github.com/moq-dev/moq/pull/5294) - replacements never substitute content into held handles diff --git a/quest/m1/c/README.md b/quest/m1/c/README.md index ed703acd670..cdaa9b38596 100644 --- a/quest/m1/c/README.md +++ b/quest/m1/c/README.md @@ -45,7 +45,7 @@ its final notice release and is not a prerequisite of this preparation. The hand-written crate gets no more feature work: its shutdown, CMake library, and fetch quests were abandoned for this line, and hidden is done. -Decided in the quest audit: [claim epochs](/quest/m1/claim-answer-epochs.md) +Decided in the quest audit: [claim epochs](https://github.com/moq-dev/moq/pull/5678) is a narrow correctness exception. Its existing claim API migrates with Rust and JS so C cannot retain the unsafe accept path while this line waits. That change owns its C tests and `MIGRATE.md` entries; other API reshaping stays here. diff --git a/quest/m1/claim-answer-epochs.md b/quest/m1/claim-answer-epochs.md deleted file mode 100644 index 955cc00bf00..00000000000 --- a/quest/m1/claim-answer-epochs.md +++ /dev/null @@ -1,109 +0,0 @@ -# [L] A claim answers each output as its own epoch - -## Goal - -A worker behind a prefix claim that restarts a path's output does so under a -new epoch, so every hop sees the change and drops its copy: a returning reader -never gets the old output's groups. The public claim API cannot serve two -outputs at one path under the same instance. Replaces the relay-side -regression check proposed in #5057. - -## Plan - -Facts as of main 90500867d: - -- A claim (`origin::Producer::dynamic`, JS `Producer.dynamic`, moq-ffi, moq-c - and the binding wrappers) answers with any broadcast via `Request::accept`. - Every answer resolves under the claim route's instance (its epoch, or the - entry's generation), shared by every path and every answer for the claim's - lifetime. Once an answer closes, the handler is asked again and the new - broadcast, restarting at group 0, resolves under the same instance; nothing - on any wire changes, so a lingering downstream copy splices old onto new. -- `Dynamic::update` to a new epoch, or a renewal, restarts the whole prefix, - resetting every sibling path's readers. Too coarse for a pool. -- Tracks already avoid this: a broadcast keeps each track name's sequence - across replacement producers. Claims have no equivalent. -- In repo, the production claim handlers are moq-net sessions forwarding a - peer's claim; they relay upstream numbering and keep working as is. - -Decided 2026-10-12: a request is answered by publishing, not by handing over -content. The answer has two steps, so the broadcast holds its tracks (or a -`broadcast::Dynamic`) before anyone resolves through it, and the caller names -the epoch. Roughly: - - impl Request { - /// Start answering the path as a new publisher instance under `epoch`, unannounced until published. - pub fn prepare(self, epoch: Epoch) -> Result; - } - - impl Prepared { - /// Announce the filled broadcast at exactly the requested path and resolve every waiting requester. - pub fn publish(self) -> Result; - } - -`Prepared` (name open) gives access to the broadcast to fill and is the only -way to answer, so an announced empty answer can't be expressed. Dropping it -unpublished rejects the request, as dropping a `Request` does. The broadcast -is announced with the claim's route metadata and that epoch, and requesters -resolve through that route, never the claim's instance. Closing it ends the -route; the next request prepares under a new epoch (`Epoch::mint()` per run, -or a replica set's shared one). Session forwarding keeps a crate-private -accept. Rejected: a single `publish` that announces an empty broadcast, -renewing the prefix on each restart (resets every sibling), and carrying -sequences over to the next answer (relabels a different job as a -continuation). - -Decided 2026-10-12: public claims carry no epoch. A claim is a capability, -as announce takeover already treats it, so `Producer::dynamic` (JS and the -bindings alike) cannot take one; prefer a shape where the route has none over -a runtime refusal. A request pinned to an epoch resolves only through an -exact-path route with that epoch. Sessions keep epochs on the peer routes -they land internally. Migrate the in-repo callers and tests that claim with -an epoch. - -Required: validity and route insertion are atomic. A request the claim -released (an `update` to another instance) or abandoned (the claim dropped) -before `publish` is refused, never announced, as `accept` drops it today. -Regression tests cover both, and a pinned request. - -Look out for: - -- A downstream relay that resolved the path through its copy of the claim - before the exact announcement arrived holds a front under the claim's - instance. Check it can't be rejoined once another route won the path and - then ended; if it can, retire it per path, not by renewing the prefix. The - cold-start reset it implies is accepted until announce takeover lands. -- One exact announcement per live output: benchmark outputs against downstream - cursors. -- No producer-side refusal of a backwards sequence: a fresh broadcast has no - memory of the last run, and backfill below the newest group is legitimate. - -Verification: mocked time, reusing #5057's worker harness -(`tests/largest_regression.rs` on its branch, with Dryvnt credited as -co-author). A worker restarts `pool/p` within the linger, behind one relay -and behind an edge relay of ours, on lite-05, 06, 07 and moq-transport 14, -16, 22: the returning reader gets the new output from group 0, never the old -group, and sibling paths keep their readers. On the wires without an epoch -that rests on our relays retiring a copy on End then Start, as -`tests/integration/restart.rs` shows; arbitrary older caching relays are out of scope, as -in [MoQ Epoch](/drafts/draft-lcurley-moq-epoch.md), since base IETF object identity -survives a withdrawal. A same-epoch lagging replica still resumes, checked on -lite-07 only, the one wire here that carries the epoch. JS mirrors the tests. -`just test interop --all`. - -Public API: breaking. A claim request is answered through `prepare` and -`publish`, and a public claim takes no epoch, in Rust, JS, moq-ffi, moq-c and -every binding wrapper, plus the claim docs. Wire: none. - -Decided in the quest audit: migrate the hand-written C claim API in this -change as a narrow correctness exception to the -[C freeze](/quest/m1/c/README.md). Leaving its existing accept path would -preserve the identity bug, so claim safety does not wait for generated C. -This permits only the claim migration and its tests and upgrade notes; -the broader C API still waits for the generated replacement. - -## Related - -- [Announcement takeover](/quest/m1/announce-takeover.md) - its claim-to-route operation is `Request::prepare` then `publish`; TAKEOVER then removes the cold-start reset -- [MoQ Epoch](/drafts/draft-lcurley-moq-epoch.md) - carries the answer epoch over moq-transport, so same-epoch resume and replacement can be told apart there -- [#5057](https://github.com/moq-dev/moq/pull/5057) - the relay-side check this replaces diff --git a/quest/m1/public-model/answer.md b/quest/m1/public-model/answer.md index 75c059888cd..13f1adaab4b 100644 --- a/quest/m1/public-model/answer.md +++ b/quest/m1/public-model/answer.md @@ -62,6 +62,18 @@ Rust items (`rs/moq-net/src/model/`), as they stood at b4eab0db1: - Keep them private. - `origin::Dynamic::withdrawn` (lite subscriber): public, as the explicit peer withdrawal that differs from a session simply dropping its handle. +- **Peer-route escape hatches** (`origin::Producer::dynamic_route`, + `origin::Dynamic::update_route`, `origin::Request::accept`; JS + `Origin.Producer.dynamicRoute`, `Dynamic.updateRoute`, `Request.accept`). + Settled as the interim in [#5678](https://github.com/moq-dev/moq/pull/5678): + an application claim (`dynamic(prefix)`) carries no route and answers + through `Request::prepare` then `Prepared::publish`, and these stay + `#[doc(hidden)] pub` / `@internal` for the sessions, tests, and benches that + model a peer's route (a covering claim with hops, cost, or an epoch, + answered with a broadcast the session already routes). Make them private + (`pub(crate)`, and private in JS) once the identity handle above and the + answer source give a peer's route a public shape, and move the + out-of-crate tests and benches onto it. - `origin::interest_prefixes` (both subscribers): remove the need through [Rust lazy discovery](/quest/m1/lazy-discovery/rust.md), which gives Rust the origin's watched interests the way JS has them; make that public in diff --git a/rs/moq-c/MIGRATE.md b/rs/moq-c/MIGRATE.md index 16e3b1374b1..a6765ccfdcf 100644 --- a/rs/moq-c/MIGRATE.md +++ b/rs/moq-c/MIGRATE.md @@ -4,6 +4,12 @@ How to update your code for each breaking change, newest first. ## Unreleased +### A claim answers by publishing (#5678) + +`moq_origin_dynamic` takes no route, and `moq_origin_dynamic_update` is gone. +`moq_broadcast_request_accept` is replaced by `moq_broadcast_request_prepare`, which returns a prepared answer under the epoch you pass: fill its broadcast, then `moq_broadcast_prepared_publish` announces it at the exact path under that epoch. +`moq_broadcast_prepared_free` refuses an answer you will not publish. + ### `moq_track_info` gains `compress` (#5928) The new trailing field changes its ABI. A zero-initialized struct leaves it false, as before. diff --git a/rs/moq-c/src/api.rs b/rs/moq-c/src/api.rs index c0004025181..0ae309ac25d 100644 --- a/rs/moq-c/src/api.rs +++ b/rs/moq-c/src/api.rs @@ -1740,7 +1740,6 @@ pub unsafe extern "C" fn moq_origin_create_broadcast(origin: u32, path: *const c /// /// # Safety /// - The caller must ensure that prefix is a valid pointer to prefix_len bytes of data. -/// - `route` may be NULL, or must point at a readable [moq_route]. /// - `on_request` must be non-NULL; a missing callback is refused before the route is advertised. /// - The caller must keep `user_data` valid until the terminal (`<= 0`) `on_request` callback. #[unsafe(no_mangle)] @@ -1748,31 +1747,14 @@ pub unsafe extern "C" fn moq_origin_dynamic( origin: u32, prefix: *const c_char, prefix_len: usize, - route: *const moq_route, on_request: ffi::moq_status_callback, user_data: *mut c_void, ) -> i32 { ffi::enter(move || { let origin = ffi::parse_id(origin)?; let prefix = unsafe { ffi::parse_str(prefix, prefix_len)? }; - let route = unsafe { parse_route(route)? }; let on_request = unsafe { ffi::OnStatus::new(user_data, on_request)? }; - State::lock().origin.dynamic(origin, prefix, route, on_request) - }) -} - -/// Re-price a served route in place. The prefix cannot change. -/// -/// Returns a zero on success, or a negative code on failure. -/// -/// # Safety -/// - `route` may be NULL, or must point at a readable [moq_route]. -#[unsafe(no_mangle)] -pub unsafe extern "C" fn moq_origin_dynamic_update(dynamic: u32, route: *const moq_route) -> i32 { - ffi::enter(move || { - let dynamic = ffi::parse_id(dynamic)?; - let route = unsafe { parse_route(route)? }; - State::lock().origin.dynamic_update(dynamic, route) + State::lock().origin.dynamic(origin, prefix, on_request) }) } @@ -1808,19 +1790,61 @@ pub unsafe extern "C" fn moq_broadcast_request_path(request: u32, dst: *mut moq_ }) } -/// Accept a broadcast request with an unannounced broadcast producer. +/// Start a broadcast request answer under `epoch`, hidden until published. /// -/// Consumes the request handle. Returns a zero on success, or a negative code -/// on failure. +/// Consumes the request handle, writes the new broadcast handle to `broadcast` +/// (which cannot announce itself; only [moq_broadcast_prepared_publish] does), +/// and returns a positive prepared-answer handle or a negative error. +/// +/// # Safety +/// - `epoch` must point at `epoch_len` readable bytes containing a UUIDv7 epoch. +/// - `broadcast` must point at writable storage for one handle. #[unsafe(no_mangle)] -pub extern "C" fn moq_broadcast_request_accept(request: u32, broadcast: u32) -> i32 { +pub unsafe extern "C" fn moq_broadcast_request_prepare( + request: u32, + epoch: *const c_char, + epoch_len: usize, + broadcast: *mut u32, +) -> i32 { ffi::enter(move || { let request = ffi::parse_id(request)?; - let broadcast = ffi::parse_id(broadcast)?; + let epoch = unsafe { ffi::parse_str(epoch, epoch_len)? } + .parse() + .map_err(|_| Error::InvalidCode)?; + let broadcast_out = unsafe { broadcast.as_mut() }.ok_or(Error::InvalidPointer)?; let mut state = State::lock(); - let pending = state.origin.broadcast_request_take(request)?; - let consumer = state.publish.producer(broadcast)?.consume(); - pending.accept(&consumer); + let (pending, driver) = state.origin.broadcast_request_take(request)?; + let prepared = pending.prepare(epoch)?; + let broadcast = state.publish.create((prepared.broadcast().clone(), driver.clone()))?; + let id = state.origin.prepared_insert(prepared, driver)?; + *broadcast_out = broadcast.into(); + Ok(id) + }) +} + +/// Publish a prepared claim answer and resolve every waiting requester. +/// +/// Consumes the prepared handle. The broadcast handle returned by +/// [moq_broadcast_request_prepare] remains owned by the caller. +#[unsafe(no_mangle)] +pub extern "C" fn moq_broadcast_prepared_publish(prepared: u32) -> i32 { + ffi::enter(move || { + let prepared = ffi::parse_id(prepared)?; + let (prepared, driver) = State::lock().origin.prepared_take(prepared)?; + driver.check()?; + let result = prepared.publish(); + driver.check()?; + result?; + Ok(()) + }) +} + +/// Free a prepared claim answer without publishing it. +#[unsafe(no_mangle)] +pub extern "C" fn moq_broadcast_prepared_free(prepared: u32) -> i32 { + ffi::enter(move || { + let prepared = ffi::parse_id(prepared)?; + State::lock().origin.prepared_take(prepared)?; Ok(()) }) } @@ -1833,8 +1857,10 @@ pub extern "C" fn moq_broadcast_request_accept(request: u32, broadcast: u32) -> pub extern "C" fn moq_broadcast_request_reject(request: u32, error_code: u16) -> i32 { ffi::enter(move || { let request = ffi::parse_id(request)?; - let pending = State::lock().origin.broadcast_request_take(request)?; + let (pending, driver) = State::lock().origin.broadcast_request_take(request)?; + driver.check()?; pending.reject(moq_net::Error::App(error_code)); + driver.check()?; Ok(()) }) } diff --git a/rs/moq-c/src/origin.rs b/rs/moq-c/src/origin.rs index ffadd5d6439..069ada23da8 100644 --- a/rs/moq-c/src/origin.rs +++ b/rs/moq-c/src/origin.rs @@ -29,7 +29,10 @@ pub struct Origin { dynamic: NonZeroSlab>, /// Broadcast requests delivered to a dynamic handler, freed after accept/reject. - broadcast_request: NonZeroSlab>, + broadcast_request: NonZeroSlab>, + + /// Claim answers being filled before their exact route is announced. + prepared: NonZeroSlab>, } #[derive(Clone)] @@ -332,17 +335,11 @@ impl Origin { /// Advertise `prefix` and serve requests beneath it, delivering each as a /// broadcast-request handle via `on_request`. - pub fn dynamic( - &mut self, - origin: Id, - prefix: &str, - route: moq_net::origin::Route, - on_request: OnStatus, - ) -> Result { + pub fn dynamic(&mut self, origin: Id, prefix: &str, on_request: OnStatus) -> Result { let origin = self.active.get(origin).ok_or(Error::OriginNotFound)?; origin.driver.check()?; let driver = origin.driver.clone(); - let result = origin.producer.dynamic(prefix, route); + let result = origin.producer.dynamic(prefix); origin.driver.check()?; let inner = result?; let channel = oneshot::channel(); @@ -352,8 +349,9 @@ impl Origin { callback: on_request, }))?; + let request_driver = driver.clone(); tokio::spawn(async move { - let res = crate::ffi::run(driver.watch(Self::run_dynamic(id, channel.1))).await; + let res = crate::ffi::run(driver.watch(Self::run_dynamic(id, channel.1, request_driver))).await; let entry = State::lock().origin.dynamic.remove(id).flatten(); if let Some(entry) = entry { entry.callback.call(res); @@ -363,7 +361,11 @@ impl Origin { Ok(id) } - async fn run_dynamic(id: Id, mut close: oneshot::Receiver<()>) -> Result<(), Error> { + async fn run_dynamic( + id: Id, + mut close: oneshot::Receiver<()>, + driver: crate::ffi::Background, + ) -> Result<(), Error> { loop { let request = tokio::select! { biased; @@ -381,7 +383,10 @@ impl Origin { }, }; - let request_id = State::lock().origin.broadcast_request.insert(Some(request))?; + let request_id = State::lock() + .origin + .broadcast_request + .insert(Some((request, driver.clone())))?; let callback = State::lock() .origin .dynamic @@ -395,16 +400,6 @@ impl Origin { } } - pub fn dynamic_update(&self, dynamic: Id, route: moq_net::origin::Route) -> Result<(), Error> { - let dynamic = self - .dynamic - .get(dynamic) - .and_then(|entry| entry.as_ref()) - .and_then(|entry| entry.inner.as_ref()) - .ok_or(Error::NotFound)?; - Ok(dynamic.update(route)?) - } - pub fn dynamic_close(&mut self, dynamic: Id) -> Result<(), Error> { let entry = self .dynamic @@ -423,7 +418,7 @@ impl Origin { .get(request) .and_then(|slot| slot.as_ref()) .ok_or(Error::NotFound)?; - let path = request.path(); + let path = request.0.path(); *dst = crate::moq_string { data: path.as_str().as_ptr().cast::(), len: path.as_str().len(), @@ -431,10 +426,28 @@ impl Origin { Ok(()) } - pub fn broadcast_request_take(&mut self, request: Id) -> Result { + pub fn broadcast_request_take( + &mut self, + request: Id, + ) -> Result<(moq_net::origin::Request, crate::ffi::Background), Error> { self.broadcast_request.remove(request).flatten().ok_or(Error::NotFound) } + pub fn prepared_insert( + &mut self, + prepared: moq_net::origin::Prepared, + driver: crate::ffi::Background, + ) -> Result { + self.prepared.insert(Some((prepared, driver))) + } + + pub fn prepared_take( + &mut self, + prepared: Id, + ) -> Result<(moq_net::origin::Prepared, crate::ffi::Background), Error> { + self.prepared.remove(prepared).flatten().ok_or(Error::NotFound) + } + pub fn close(&mut self, origin: Id) -> Result<(), Error> { self.active.remove(origin).ok_or(Error::OriginNotFound)?; Ok(()) diff --git a/rs/moq-c/src/test.rs b/rs/moq-c/src/test.rs index a05be7a1db8..77ba92d10c6 100644 --- a/rs/moq-c/src/test.rs +++ b/rs/moq-c/src/test.rs @@ -2579,7 +2579,6 @@ fn dynamic_serves_a_request_under_a_prefix() { origin, prefix.as_ptr() as *const c_char, prefix.len(), - std::ptr::null(), Some(channel_callback), cb.ptr, ) @@ -2606,8 +2605,11 @@ fn dynamic_serves_a_request_under_a_prefix() { let got = unsafe { std::str::from_utf8(std::slice::from_raw_parts(info.data.cast::(), info.len)).unwrap() }; assert_eq!(got, "live/cam"); - let served = id(unsafe { moq_origin_create_broadcast(origin, b"unused".as_ptr() as *const c_char, 6) }); - assert_eq!(moq_broadcast_request_accept(request, served), 0); + let epoch = moq_net::Epoch::mint().to_string(); + let mut served = 0; + let prepared = + id(unsafe { moq_broadcast_request_prepare(request, epoch.as_ptr().cast(), epoch.len(), &mut served) }); + assert_eq!(moq_broadcast_prepared_publish(prepared), 0); assert!(req_cb.recv() > 0); req_cb.recv_terminal(); @@ -2627,7 +2629,6 @@ fn dynamic_refuses_a_missing_callback() { origin, prefix.as_ptr() as *const c_char, prefix.len(), - std::ptr::null(), None, std::ptr::null_mut(), ) @@ -3577,7 +3578,7 @@ fn consume_announced_delivers_a_takeover_once(dynamic_at: &str) { .origin .get(origin) .unwrap() - .dynamic(dynamic_at, route) + .dynamic_route(dynamic_at, route) .unwrap() }; let cb = Callback::new(); @@ -3626,7 +3627,7 @@ fn serve_dynamic(origin: u32, prefix: &str, route: moq_net::origin::Route) -> mo .origin .get(origin) .unwrap() - .dynamic(prefix, route) + .dynamic_route(prefix, route) .unwrap() } diff --git a/rs/moq-cli/src/play/media.rs b/rs/moq-cli/src/play/media.rs index 7aa884a844d..f83c1e195ea 100644 --- a/rs/moq-cli/src/play/media.rs +++ b/rs/moq-cli/src/play/media.rs @@ -1618,7 +1618,7 @@ mod tests { let mut served = moq_net::broadcast::Info::new().produce(); let served_catalog = catalog::Producer::new(&mut served, Default::default()).unwrap(); let mut new = rendition(&served, &served_catalog, "audio"); - let pool = origin.dynamic("", route).unwrap(); + let pool = origin.dynamic_route("", route).unwrap(); drop(exact); let consumer = served.consume(); tokio::spawn(async move { @@ -1664,7 +1664,7 @@ mod tests { } exact.unannounce(); - let pool = origin.dynamic("", route).unwrap(); + let pool = origin.dynamic_route("", route).unwrap(); let consumer = mirror.consume(); tokio::spawn(async move { while let Ok(request) = pool.requested_broadcast().await { diff --git a/rs/moq-ffi/MIGRATE.md b/rs/moq-ffi/MIGRATE.md index d12b0488b5f..4316e7d0106 100644 --- a/rs/moq-ffi/MIGRATE.md +++ b/rs/moq-ffi/MIGRATE.md @@ -5,6 +5,12 @@ These are the UniFFI names; each language wrapper has its own `MIGRATE.md` in it ## Unreleased +### A claim answers by publishing (#5678) + +`MoqOriginProducer::dynamic(prefix)` takes no `MoqRoute`, and `MoqOriginDynamic::update` is gone. +`MoqBroadcastRequest::accept` is replaced by `prepare(epoch)`, which returns a `MoqBroadcastPrepared`: fill its `broadcast()`, then `publish()` announces it at the exact path under that epoch and returns its producer. +Mint a fresh epoch per output run with `moq_mint_epoch()`. Dropping a prepared answer unpublished refuses the request. + ### `MoqTrackInfo` gains `compress` (#5928) It defaults to `false` in every generated binding; a Rust struct literal adds `compress: false`. diff --git a/rs/moq-ffi/src/origin.rs b/rs/moq-ffi/src/origin.rs index 161d46be428..2de64aa110b 100644 --- a/rs/moq-ffi/src/origin.rs +++ b/rs/moq-ffi/src/origin.rs @@ -149,7 +149,6 @@ pub struct MoqAnnounceConsumer { /// `MoqOriginProducer` is gone. pub struct MoqOriginDynamic { slot: Slot, - driver: Background, task: std::sync::Mutex>>>, } @@ -157,6 +156,15 @@ pub struct MoqOriginDynamic { /// A pending dynamic broadcast request that must be accepted or rejected. pub struct MoqBroadcastRequest { inner: std::sync::Mutex>, + driver: Background, +} + +#[derive(uniffi::Object)] +/// A claim answer being filled before its exact route is announced. +pub struct MoqBroadcastPrepared { + inner: std::sync::Mutex>, + broadcast: Arc, + driver: Background, } struct Announced { @@ -190,7 +198,7 @@ impl OriginDynamic { }) }) .await?; - Ok(Arc::new(MoqBroadcastRequest::new(request))) + Ok(Arc::new(MoqBroadcastRequest::new(request, self.driver.clone()))) } } @@ -377,17 +385,15 @@ impl MoqOriginProducer { /// the returned handle while the route should stay advertised and missing /// broadcasts should be served. Create, attach this for tracks served on /// demand, populate, then announce. - pub fn dynamic(&self, prefix: String, route: MoqRoute) -> Result, MoqError> { + pub fn dynamic(&self, prefix: String) -> Result, MoqError> { let _guard = crate::ffi::enter(); self.inner.driver.check()?; - let route: moq_net::origin::Route = route.try_into()?; - let result = self.inner.dynamic(prefix, route); + let result = self.inner.dynamic(prefix); self.inner.driver.check()?; let dynamic = result?; let slot = Arc::new(std::sync::Mutex::new(Some(dynamic))); Ok(Arc::new(MoqOriginDynamic { slot: slot.clone(), - driver: self.inner.driver.clone(), task: std::sync::Mutex::new(Some(Arc::new(Task::new(OriginDynamic { slot, driver: self.inner.driver.clone(), @@ -502,19 +508,6 @@ impl MoqOriginDynamic { .await } - /// Replace the route in place: its epoch, hops, and a static cost. The prefix cannot - /// change; call `dynamic` again instead. - pub fn update(&self, route: MoqRoute) -> Result<(), MoqError> { - self.driver.check()?; - let _guard = crate::ffi::enter(); - let route: moq_net::origin::Route = route.try_into()?; - let slot = self.slot.lock().unwrap(); - let dynamic = slot.as_ref().ok_or(MoqError::Closed)?; - let result = dynamic.update(route); - self.driver.check()?; - Ok(result?) - } - /// Stop serving and retract the route. Terminal: this handler is released /// here, not when the handle is, so pending requests are rejected before /// this returns. @@ -531,9 +524,10 @@ impl MoqOriginDynamic { // ---- MoqBroadcastRequest ---- impl MoqBroadcastRequest { - fn new(request: moq_net::origin::Request) -> Self { + fn new(request: moq_net::origin::Request, driver: Background) -> Self { Self { inner: std::sync::Mutex::new(Some(request)), + driver, } } @@ -551,13 +545,23 @@ impl MoqBroadcastRequest { Ok(request.path().to_string()) } - /// Accept the request with an unannounced broadcast. - pub fn accept(&self, broadcast: &MoqBroadcastProducer) -> Result<(), MoqError> { + /// Start answering as a new publisher instance, hidden until published. + pub fn prepare(&self, epoch: String) -> Result, MoqError> { let _guard = crate::ffi::enter(); - let consumer = broadcast.consume_inner()?; + self.driver.check()?; let request = self.take()?; - request.accept(&consumer); - Ok(()) + let result = request.prepare(epoch.parse()?); + self.driver.check()?; + let prepared = result?; + let broadcast = Arc::new(MoqBroadcastProducer::from_inner( + prepared.broadcast().clone(), + self.driver.clone(), + )?); + Ok(Arc::new(MoqBroadcastPrepared { + inner: std::sync::Mutex::new(Some(prepared)), + broadcast, + driver: self.driver.clone(), + })) } /// Reject the request with an application error code. @@ -569,6 +573,25 @@ impl MoqBroadcastRequest { } } +#[uniffi::export] +impl MoqBroadcastPrepared { + /// The unannounced broadcast to fill before publishing; only `publish` announces it. + pub fn broadcast(&self) -> Arc { + self.broadcast.clone() + } + + /// Announce the filled broadcast and resolve every waiting requester. + pub fn publish(&self) -> Result, MoqError> { + let _guard = crate::ffi::enter(); + self.driver.check()?; + let prepared = self.inner.lock().unwrap().take().ok_or(MoqError::Closed)?; + let result = prepared.publish(); + self.driver.check()?; + result?; + Ok(self.broadcast.clone()) + } +} + // ---- MoqAnnounceConsumer ---- #[uniffi::export] diff --git a/rs/moq-ffi/src/producer.rs b/rs/moq-ffi/src/producer.rs index 97b2c3ec24e..9f3f5585eaa 100644 --- a/rs/moq-ffi/src/producer.rs +++ b/rs/moq-ffi/src/producer.rs @@ -165,6 +165,7 @@ impl MoqBroadcastProducer { }) } + #[cfg(test)] pub(crate) fn consume_inner(&self) -> Result { self.with_state(|state| Ok(state.broadcast.consume())) } @@ -217,8 +218,7 @@ impl MoqBroadcastProducer { /// Create a standalone broadcast, not attached to any origin. /// - /// Use it to serve a dynamic broadcast request ([`MoqBroadcastRequest::accept`](crate::origin::MoqBroadcastRequest::accept)) - /// or for local pub/sub via [`consume`](Self::consume). To publish at a path, use + /// Use it for local pub/sub via [`consume`](Self::consume). To publish at a path, use /// [`MoqOriginProducer::create_broadcast`](crate::origin::MoqOriginProducer::create_broadcast) instead. #[uniffi::constructor] pub fn new() -> Result, MoqError> { diff --git a/rs/moq-ffi/src/test.rs b/rs/moq-ffi/src/test.rs index f64b91adc8e..5de35642e56 100644 --- a/rs/moq-ffi/src/test.rs +++ b/rs/moq-ffi/src/test.rs @@ -2678,7 +2678,7 @@ async fn announced_filters_patterns_and_reports_captures() { }) .unwrap(); - let _broad = origin.dynamic("room".into(), MoqRoute::default()).unwrap(); + let _broad = origin.dynamic("room".into()).unwrap(); let overlap = next_announced(&announced).await; assert_eq!(overlap.prefix, "room"); assert_eq!(overlap.captures, None, "an overlap does not pin the wildcard"); @@ -3552,7 +3552,7 @@ async fn announced_broadcast() { } fn serve(origin: &MoqOriginProducer, prefix: &str) -> Arc { - origin.dynamic(prefix.into(), MoqRoute::default()).unwrap() + origin.dynamic(prefix.into()).unwrap() } #[tokio::test] @@ -3572,9 +3572,12 @@ async fn dynamic_broadcast_request() { .unwrap(); assert_eq!(request.path().unwrap(), "dynamic/broadcast"); - let served = MoqBroadcastProducer::new().unwrap(); + let prepared = request.prepare(moq_net::Epoch::mint().to_string()).unwrap(); + let served = prepared.broadcast(); let track = served.publish_track("status".into(), Some(timed_info())).unwrap(); - request.accept(&served).unwrap(); + // Only publish announces the answer, under its epoch and after admission. + assert!(matches!(served.announce(MoqRoute::default()), Err(MoqError::Closed))); + prepared.publish().unwrap(); assert!(matches!(request.path(), Err(MoqError::Closed))); let broadcast = tokio::time::timeout(TIMEOUT, request_broadcast) @@ -3621,8 +3624,9 @@ async fn dynamic_serves_a_request_under_a_prefix() { .expect("timed out waiting for the prefix request") .unwrap(); assert_eq!(request.path().unwrap(), "live/cam"); - let served = MoqBroadcastProducer::new().unwrap(); - request.accept(&served).unwrap(); + let prepared = request.prepare(moq_net::Epoch::mint().to_string()).unwrap(); + let served = prepared.broadcast(); + prepared.publish().unwrap(); tokio::time::timeout(TIMEOUT, request_broadcast) .await .expect("timed out waiting for the request to resolve") @@ -3662,8 +3666,9 @@ async fn dynamic_keeps_the_origin_alive() { .await .expect("the handler must still receive requests") .unwrap(); - let served = MoqBroadcastProducer::new().unwrap(); - request.accept(&served).unwrap(); + let prepared = request.prepare(moq_net::Epoch::mint().to_string()).unwrap(); + let served = prepared.broadcast(); + prepared.publish().unwrap(); tokio::time::timeout(TIMEOUT, request_broadcast) .await .expect("timed out waiting for the request to resolve") @@ -4727,8 +4732,7 @@ async fn announced_broadcast_retries_a_dropped_wait() { assert!(matches!(dropped.await, Err(err) if err.is_cancelled())); let retry = tokio::spawn(async move { followed.available().await }); - let served = MoqBroadcastProducer::new().unwrap(); - request.accept(&served).unwrap(); + let served = request.prepare(moq_mint_epoch()).unwrap().publish().unwrap(); tokio::time::timeout(TIMEOUT, retry) .await .expect("the retry waited for another instance") @@ -4796,15 +4800,20 @@ async fn announced_broadcast_hands_out_the_instance_again_after_an_end() { .expect("timed out waiting for the broadcast") .unwrap(); - let dynamic = origin.dynamic("".into(), route).unwrap(); + // A peer's covering route under the same epoch, which the public claim cannot express. + let dynamic = origin + .inner() + .inner + .dynamic_route("", route.clone().try_into().unwrap()) + .unwrap(); broadcast.unannounce().unwrap(); let again = tokio::spawn(async move { followed.available().await }); let request = tokio::time::timeout(TIMEOUT, dynamic.requested_broadcast()) .await .expect("the instance never asked the route above the path") .unwrap(); - let served = MoqBroadcastProducer::new().unwrap(); - request.accept(&served).unwrap(); + let served = moq_net::broadcast::Info::new().produce(); + request.accept(served.consume()); let again = tokio::time::timeout(TIMEOUT, again) .await @@ -4815,7 +4824,7 @@ async fn announced_broadcast_hands_out_the_instance_again_after_an_end() { again.inner().is_clone(first.inner()), "the route above did not carry the instance on" ); - served.close().unwrap(); + drop((served, dynamic)); broadcast.close().unwrap(); } diff --git a/rs/moq-gst/src/source/imp.rs b/rs/moq-gst/src/source/imp.rs index 8057ebf97a5..122f7e051fd 100644 --- a/rs/moq-gst/src/source/imp.rs +++ b/rs/moq-gst/src/source/imp.rs @@ -2956,7 +2956,7 @@ mod session_tests { let mut old = Publisher::standalone(video_rendition()); let serving = std::sync::Arc::new(Mutex::new(old.broadcast.consume())); - let pool = std::sync::Arc::new(origin.dynamic("", epoch()).unwrap()); + let pool = std::sync::Arc::new(origin.dynamic_route("", epoch()).unwrap()); let (handler, answer) = (pool.clone(), serving.clone()); let handler = super::RUNTIME.spawn(async move { while let Ok(request) = handler.requested_broadcast().await { @@ -2969,7 +2969,7 @@ mod session_tests { let mut new = Publisher::standalone(video_rendition()); *serving.lock().unwrap() = new.broadcast.consume(); - pool.update(epoch()).unwrap(); + pool.update_route(epoch()).unwrap(); assert_eq!(recorder.written(&mut new, 2), pad, "the restart moved to another pad"); stop(session); diff --git a/rs/moq-hls/src/export/mod.rs b/rs/moq-hls/src/export/mod.rs index 5af0c533bae..1c436a815bb 100644 --- a/rs/moq-hls/src/export/mod.rs +++ b/rs/moq-hls/src/export/mod.rs @@ -3496,7 +3496,7 @@ mod tests { let mut old_media = moq_net::broadcast::Info::new().produce(); let _old_track = write_routed_media(&mut old_media, OLD, recorder, 0); - let old_server = origin.dynamic("media", sibling_route(10)).unwrap(); + let old_server = origin.dynamic_route("media", sibling_route(10)).unwrap(); settle().await; let upstream = crate::resolved(&origin, "live").await; @@ -3547,7 +3547,7 @@ mod tests { } // A publisher serving the path afterwards, with rows recorded for it, is never bound. - let new_server = origin.dynamic("media", sibling_route(11)).unwrap(); + let new_server = origin.dynamic_route("media", sibling_route(11)).unwrap(); let _ = rendition.snapshot(); assert!( tokio::time::timeout(Duration::from_secs(1), new_server.requested_broadcast()) @@ -3583,7 +3583,7 @@ mod tests { let mut media = moq_net::broadcast::Info::new().produce(); let _track = write_routed_media(&mut media, KEYFRAME, recorder, 0); - let server = origin.dynamic("media", sibling_route(10)).unwrap(); + let server = origin.dynamic_route("media", sibling_route(10)).unwrap(); settle().await; let upstream = crate::resolved(&origin, "live").await; @@ -3646,7 +3646,7 @@ mod tests { let mut media = moq_net::broadcast::Info::new().produce(); let _track = write_routed_media(&mut media, NEW, recorder, 0); - let server = origin.dynamic("media", sibling_route(11)).unwrap(); + let server = origin.dynamic_route("media", sibling_route(11)).unwrap(); settle().await; let upstream = crate::resolved(&origin, "live").await; @@ -3685,7 +3685,7 @@ mod tests { let mut old_media = moq_net::broadcast::Info::new().produce(); let _old_track = write_routed_media(&mut old_media, OLD, recorder, 0); - let old_server = origin.dynamic("media", sibling_route(10)).unwrap(); + let old_server = origin.dynamic_route("media", sibling_route(10)).unwrap(); settle().await; let upstream = crate::resolved(&origin, "live").await; @@ -3710,7 +3710,7 @@ mod tests { .expect("the old retained segment drains"); assert!(contains(&served, OLD)); - let new_server = origin.dynamic("media", sibling_route(11)).unwrap(); + let new_server = origin.dynamic_route("media", sibling_route(11)).unwrap(); let mut new_media = moq_net::broadcast::Info::new().produce(); let recorder = catalog.enroll_test("video0").unwrap(); let _new_track = write_routed_media(&mut new_media, NEW, recorder, 6_000_000); @@ -3749,7 +3749,7 @@ mod tests { let recorder = catalog.enroll_test("video0").unwrap(); let mut media = moq_net::broadcast::Info::new().produce(); let track = write_routed_media(&mut media, OLD, recorder, 0); - let server = origin.dynamic("media", sibling_route(10)).unwrap(); + let server = origin.dynamic_route("media", sibling_route(10)).unwrap(); settle().await; let upstream = crate::resolved(&origin, "live").await; @@ -3809,7 +3809,7 @@ mod tests { .await .expect("the catalog's rows are listed before the sibling resolves"); - let server = origin.dynamic("media", sibling_route(10)).unwrap(); + let server = origin.dynamic_route("media", sibling_route(10)).unwrap(); let _ = rendition.snapshot(); accept_sibling(&server, &media).await; let served = rendition diff --git a/rs/moq-mux/benches/containers.rs b/rs/moq-mux/benches/containers.rs index 2a2aea35289..48fe61619b8 100644 --- a/rs/moq-mux/benches/containers.rs +++ b/rs/moq-mux/benches/containers.rs @@ -76,7 +76,7 @@ async fn prepare(tracks: usize, frames: usize, payload: &Bytes) -> (moq_mux::Sou catalog.finish().unwrap(); let (origin, driver) = moq_net::origin::Producer::new(Default::default()); let driver = tokio::spawn(moq_net::time::run(driver)); - let dynamic = origin.dynamic("", Default::default()).unwrap(); + let dynamic = origin.dynamic_route("", Default::default()).unwrap(); let requests = tokio::spawn(async move { while let Ok(request) = dynamic.requested_broadcast().await { request.accept(consumer.clone()); diff --git a/rs/moq-mux/benches/export.rs b/rs/moq-mux/benches/export.rs index 7ffec0491e4..da97d3bb42d 100644 --- a/rs/moq-mux/benches/export.rs +++ b/rs/moq-mux/benches/export.rs @@ -58,7 +58,7 @@ async fn prepare(tracks: usize, frames: usize) -> (moq_mux::Source, moq_mux::cat catalog.finish().unwrap(); let (origin, driver) = moq_net::origin::Producer::new(Default::default()); let driver = tokio::spawn(moq_net::time::run(driver)); - let dynamic = origin.dynamic("", Default::default()).unwrap(); + let dynamic = origin.dynamic_route("", Default::default()).unwrap(); let requests = tokio::spawn(async move { while let Ok(request) = dynamic.requested_broadcast().await { request.accept(consumer.clone()); diff --git a/rs/moq-mux/src/catalog/hang/consumer.rs b/rs/moq-mux/src/catalog/hang/consumer.rs index c90055b8e02..f7c9ec2f178 100644 --- a/rs/moq-mux/src/catalog/hang/consumer.rs +++ b/rs/moq-mux/src/catalog/hang/consumer.rs @@ -169,7 +169,7 @@ mod test { .expect("catalog track should create"); let origin = crate::source::produce_origin(); - let dynamic = origin.dynamic("", Default::default()).unwrap(); + let dynamic = origin.dynamic_route("", Default::default()).unwrap(); let requesting = origin.consume().request_broadcast("a/pub", None); let served = broadcast.consume(); // The handler hands its route back: dropping it would retract the route and end diff --git a/rs/moq-mux/src/container/consumer.rs b/rs/moq-mux/src/container/consumer.rs index 150766f8345..9b7c547e9df 100644 --- a/rs/moq-mux/src/container/consumer.rs +++ b/rs/moq-mux/src/container/consumer.rs @@ -2341,7 +2341,7 @@ mod tests { let origin = crate::source::produce_origin(); let hops = moq_net::Hops::try_from(vec![moq_net::Hop::new(10).unwrap()]).unwrap(); let first_route = origin - .dynamic( + .dynamic_route( "live", moq_net::origin::Route::default() .with_epoch(epoch.clone()) @@ -2385,7 +2385,7 @@ mod tests { let mut sources = Vec::new(); for sequence in 1..=4 { let route = origin - .dynamic( + .dynamic_route( "live", moq_net::origin::Route::default() .with_epoch(epoch.clone()) diff --git a/rs/moq-mux/src/container/ts/export_test.rs b/rs/moq-mux/src/container/ts/export_test.rs index a8e9470edd3..1fc80f4b3fe 100644 --- a/rs/moq-mux/src/container/ts/export_test.rs +++ b/rs/moq-mux/src/container/ts/export_test.rs @@ -9033,7 +9033,7 @@ async fn a_follower_takes_its_own_instance_winning_back_for_no_replacement() { info.epoch = Some(epoch.clone()); let mut served = info.produce(); let mut catalog = crate::catalog::Producer::<()>::new(&mut served, Default::default()).unwrap(); - let pool = origin.dynamic("pool", route(epoch)).unwrap(); + let pool = origin.dynamic_route("pool", route(epoch)).unwrap(); let consumer = served.consume(); tokio::spawn(async move { while let Ok(request) = pool.requested_broadcast().await { @@ -9179,7 +9179,7 @@ async fn a_follower_continues_through_a_same_epoch_handoff_after_a_gap() { let mut served = info.produce(); let mut catalog = crate::catalog::Producer::<()>::new(&mut served, Default::default()).unwrap(); let mut track = aac_rendition(&mut served, &mut catalog, "a.aac"); - let pool = origin.dynamic("pool", route).unwrap(); + let pool = origin.dynamic_route("pool", route).unwrap(); let consumer = served.consume(); tokio::spawn(async move { while let Ok(request) = pool.requested_broadcast().await { @@ -9225,10 +9225,10 @@ async fn a_follower_ignores_a_covering_prefix_while_the_exact_route_serves() { let mut follower = super::Follower::new(open_export(source).await.unwrap()).unwrap(); let quiet = Duration::from_secs(1); - let pool = origin.dynamic("pool", route(moq_net::Epoch::mint())).unwrap(); + let pool = origin.dynamic_route("pool", route(moq_net::Epoch::mint())).unwrap(); assert!(tokio::time::timeout(quiet, follower.next()).await.is_err(), "a start"); drop(pool); - let pool = origin.dynamic("pool", route(moq_net::Epoch::mint())).unwrap(); + let pool = origin.dynamic_route("pool", route(moq_net::Epoch::mint())).unwrap(); assert!(tokio::time::timeout(quiet, follower.next()).await.is_err(), "a restart"); drop(pool); assert!(tokio::time::timeout(quiet, follower.next()).await.is_err(), "an end"); diff --git a/rs/moq-mux/src/source.rs b/rs/moq-mux/src/source.rs index c619162c924..5325f93b6e2 100644 --- a/rs/moq-mux/src/source.rs +++ b/rs/moq-mux/src/source.rs @@ -348,7 +348,7 @@ pub(crate) async fn resolved(origin: &moq_net::origin::Producer, path: &str) -> #[cfg(test)] pub(crate) async fn announced(broadcast: &moq_net::broadcast::Consumer) -> Source { let origin = produce_origin(); - let dynamic = origin.dynamic("", Default::default()).unwrap(); + let dynamic = origin.dynamic_route("", Default::default()).unwrap(); let served = broadcast.clone(); tokio::spawn(async move { while let Ok(request) = dynamic.requested_broadcast().await { @@ -380,7 +380,7 @@ mod tests { let _catalog = origin.publish("pub", Default::default()).unwrap(); settle().await; let source = resolved(&origin, "pub").await; - let dynamic = origin.dynamic("media", Default::default()).unwrap(); + let dynamic = origin.dynamic_route("media", Default::default()).unwrap(); let binding = source.bind(Some(&Relative::new("media"))).unwrap(); let request = dynamic.requested_broadcast().await.unwrap(); diff --git a/rs/moq-net/MIGRATE.md b/rs/moq-net/MIGRATE.md index 8009db2c319..2a313140d69 100644 --- a/rs/moq-net/MIGRATE.md +++ b/rs/moq-net/MIGRATE.md @@ -4,6 +4,15 @@ How to update your code for each breaking change, newest first. ## Unreleased +### A claim answers by publishing (#5678) + +`origin::Producer::dynamic(prefix)` takes no route: an application claim has no epoch, cost, or hops. +Answer each `origin::Request` with `request.prepare(epoch)?` (a fresh `Epoch::mint()` per output run), fill `prepared.broadcast()`, then `prepared.publish()?`, which announces the broadcast at the exact path under that epoch and returns its producer. +Only `publish` announces it: `prepared.broadcast().announce(..)` fails with `Error::Closed`. +`Dynamic::update` is gone: drop the claim and claim again to change it, and close an answer's producer to end that output. +`Request::accept` is no longer part of the public API and panics on a request from `dynamic`. +Dropping a `Prepared` unpublished refuses the request, as dropping a `Request` does, and `publish` fails with `Error::Unroutable` once the claim went away. + ### Anchors can name a time (#6074) `track::Anchor` gains `Time(Timestamp)`, the group containing a presentation time, so exhaustive matches need an arm for it. diff --git a/rs/moq-net/benches/origin.rs b/rs/moq-net/benches/origin.rs index 4cd654e56cb..e27d5f695a0 100644 --- a/rs/moq-net/benches/origin.rs +++ b/rs/moq-net/benches/origin.rs @@ -156,7 +156,7 @@ fn bench_withdraw(c: &mut Criterion) { .poll(moq_net::time::Instant::now(), &kio::Waiter::noop()) .unwrap(); let routes: Vec<_> = (0..publishers) - .map(|i| producer.dynamic(format!("room/{i}"), peer_route(9, 1)).unwrap()) + .map(|i| producer.dynamic_route(format!("room/{i}"), peer_route(9, 1)).unwrap()) .collect(); let mut cursors: Vec<_> = (0..subscribers).map(|_| producer.consume().announced()).collect(); for cursor in &mut cursors { @@ -294,7 +294,11 @@ fn bench_announce_duplicate(c: &mut Criterion) { // Every peer announces the one path, each under its own hop chain so // the entries are distinct routes rather than one re-priced in place. let _routes: Vec<_> = (1..=duplicates) - .map(|peer| producer.dynamic(PATH, peer_route(peer as u64, INCUMBENT_COST)).unwrap()) + .map(|peer| { + producer + .dynamic_route(PATH, peer_route(peer as u64, INCUMBENT_COST)) + .unwrap() + }) .collect(); let mut cursors: Vec = (0..subscribers) .map(|_| consumer.clone().with_hidden(true).announced()) @@ -305,7 +309,7 @@ fn bench_announce_duplicate(c: &mut Criterion) { b.iter(|| { let handle = producer - .dynamic(PATH, peer_route(duplicates as u64 + 1, INCUMBENT_COST - 1)) + .dynamic_route(PATH, peer_route(duplicates as u64 + 1, INCUMBENT_COST - 1)) .unwrap(); for cursor in &mut cursors { cursor.next().now_or_never().flatten().expect("announce delivered"); @@ -341,13 +345,13 @@ fn bench_reprice_duplicate(c: &mut Criterion) { &Patterns::from(Pattern::subtree(&format!("{PATH}/p{}", (peer - 1) % 2)).unwrap()), ) .unwrap() - .dynamic(PATH, peer_route(peer as u64, incumbent_cost)) + .dynamic_route(PATH, peer_route(peer as u64, incumbent_cost)) .unwrap() }) .collect(); let challenger = duplicates as u64 + 1; let route = producer - .dynamic(PATH, peer_route(challenger, incumbent_cost + 1)) + .dynamic_route(PATH, peer_route(challenger, incumbent_cost + 1)) .unwrap(); let mut cursors: Vec = (0..subscribers) .map(|peer| { @@ -367,7 +371,7 @@ fn bench_reprice_duplicate(c: &mut Criterion) { } b.iter(|| { for cost in [incumbent_cost - 1, incumbent_cost + 1] { - route.update(peer_route(challenger, cost)).unwrap(); + route.update_route(peer_route(challenger, cost)).unwrap(); for cursor in &mut cursors { // The winner switches between epochless routes, which is another instance. let event = cursor.next().now_or_never().flatten().expect("winner changed"); @@ -409,7 +413,7 @@ fn bench_announce_fronts(c: &mut Criterion) { let (producer, mut driver) = origin::Producer::new(origin::Config::default()); let consumer = producer.consume(); // Served but never answered: every request under it parks a front. - let _served = producer.dynamic("room", origin::Route::default()).unwrap(); + let _served = producer.dynamic_route("room", origin::Route::default()).unwrap(); let _requests: Vec<_> = (0..fronts) .map(|i| consumer.request_broadcast(format!("room/{i}"), None)) .collect(); @@ -451,7 +455,7 @@ fn bench_serve_idle(c: &mut Criterion) { let dynamics: Vec<_> = (0..routes) .map(|i| { producer - .dynamic(format!(".stats/p{}/node/edge{i}", i % 8), origin::Route::default()) + .dynamic_route(format!(".stats/p{}/node/edge{i}", i % 8), origin::Route::default()) .unwrap() }) .collect(); @@ -608,8 +612,8 @@ fn bench_unroutable_churn(c: &mut Criterion) { group.bench_function(id, |b| { let (producer, mut driver) = origin::Producer::new(origin::Config::default()); let consumer = producer.consume(); - let server = producer.dynamic("room", origin::Route::default()).unwrap(); - let unrelated = producer.dynamic("other", origin::Route::default()).unwrap(); + let server = producer.dynamic_route("room", origin::Route::default()).unwrap(); + let unrelated = producer.dynamic_route("other", origin::Route::default()).unwrap(); let mut waiting = Waiting::new( (0..requesters) .map(|i| { @@ -641,7 +645,7 @@ fn bench_unroutable_churn(c: &mut Criterion) { b.iter(|| { for _ in 0..changes { cost = 3 - cost; - changed.update(origin::Route::default().with_cost(cost)).unwrap(); + changed.update_route(origin::Route::default().with_cost(cost)).unwrap(); assert!(covering || !waiting.is_woken(), "unrelated churn wakes no request"); waiting.drain(); driver.poll(now, &waiter).unwrap(); @@ -733,7 +737,7 @@ fn pool(members: usize, paths: usize, cursors: usize) -> Pool { let consumer = producer.consume(); let cursors = (0..cursors).map(|_| consumer.announced()).collect(); let members: Vec<_> = (0..members) - .map(|i| producer.dynamic("pool", pool_route(POOL_HOP + i as u64)).unwrap()) + .map(|i| producer.dynamic_route("pool", pool_route(POOL_HOP + i as u64)).unwrap()) .collect(); let waiter = kio::Waiter::noop(); @@ -792,7 +796,7 @@ fn bench_pool_churn(c: &mut Criterion) { let waiter = kio::Waiter::noop(); let hop = POOL_HOP + members as u64; b.iter(|| { - let joined = pool.producer.dynamic("pool", pool_route(hop)).unwrap(); + let joined = pool.producer.dynamic_route("pool", pool_route(hop)).unwrap(); pool.driver.poll(moq_net::time::Instant::now(), &waiter).unwrap(); drop(joined); pool.driver.poll(moq_net::time::Instant::now(), &waiter).unwrap(); @@ -820,7 +824,7 @@ fn bench_pool_cursors(c: &mut Criterion) { let waiter = kio::Waiter::noop(); let hop = POOL_HOP + members as u64; b.iter(|| { - let joined = pool.producer.dynamic("pool", pool_route(hop)).unwrap(); + let joined = pool.producer.dynamic_route("pool", pool_route(hop)).unwrap(); pool.driver.poll(moq_net::time::Instant::now(), &waiter).unwrap(); drop(joined); pool.driver.poll(moq_net::time::Instant::now(), &waiter).unwrap(); diff --git a/rs/moq-net/benches/retirement.rs b/rs/moq-net/benches/retirement.rs index 5ff1db672e2..fdc5281f03a 100644 --- a/rs/moq-net/benches/retirement.rs +++ b/rs/moq-net/benches/retirement.rs @@ -22,7 +22,7 @@ fn retirement(c: &mut Criterion) { || { let (origin, driver) = origin::Producer::new(origin::Config::default()); let routes: Vec<_> = (0..routes) - .map(|i| origin.dynamic(format!("route/{i}"), origin::Route::default()).unwrap()) + .map(|i| origin.dynamic(format!("route/{i}")).unwrap()) .collect(); let mut watches = Vec::new(); let mut controls = Vec::new(); @@ -46,7 +46,7 @@ fn retirement(c: &mut Criterion) { (origin, driver, routes, watches, controls, pending) }, |fixture| { - let replacement = fixture.0.dynamic("route/0/jobs", origin::Route::default()).unwrap(); + let replacement = fixture.0.dynamic("route/0/jobs").unwrap(); let refused = fixture .5 .iter() diff --git a/rs/moq-net/benches/viewers.rs b/rs/moq-net/benches/viewers.rs index d98864db034..fcd617a9646 100644 --- a/rs/moq-net/benches/viewers.rs +++ b/rs/moq-net/benches/viewers.rs @@ -181,7 +181,7 @@ fn bench_churn(c: &mut Criterion) { room.leave(subscription); } b.iter(|| { - let covering = room.producer.dynamic("room", origin::Route::default()).unwrap(); + let covering = room.producer.dynamic("room").unwrap(); room.poll(); drop(covering); room.poll(); diff --git a/rs/moq-net/src/ietf/publisher.rs b/rs/moq-net/src/ietf/publisher.rs index 8d8220f4973..1bae4a9e6e8 100644 --- a/rs/moq-net/src/ietf/publisher.rs +++ b/rs/moq-net/src/ietf/publisher.rs @@ -8106,7 +8106,10 @@ mod serve_tests { for version in ALL_VERSIONS { let mut h = serve(version); - let claim = h._origin.dynamic("live", crate::origin::Route::default()).unwrap(); + let claim = h + ._origin + .dynamic_route("live", crate::origin::Route::default()) + .unwrap(); let auth = crate::auth::Handle::new(false); auth.authorize(¬hing()); h.publisher = h.publisher.clone().with_auth(auth); @@ -8126,7 +8129,10 @@ mod serve_tests { for version in ALL_VERSIONS { let mut h = serve(version); - let claim = h._origin.dynamic("live", crate::origin::Route::default()).unwrap(); + let claim = h + ._origin + .dynamic_route("live", crate::origin::Route::default()) + .unwrap(); let auth = crate::auth::Handle::new(false); h.publisher = h.publisher.clone().with_auth(auth.clone()); @@ -8450,7 +8456,7 @@ mod serve_tests { for version in [Version::Draft21, Version::Draft22] { for path in [".", "./child", ".session", ".session/extension"] { let h = serve(version); - let claim = h._origin.dynamic("", crate::origin::Route::default()).unwrap(); + let claim = h._origin.dynamic_route("", crate::origin::Route::default()).unwrap(); settle().await; let stream = Stream::open(&mut h.session.clone(), version).await.unwrap(); let mark = h.log.writes.lock().unwrap().len(); @@ -10717,7 +10723,7 @@ mod serve_tests { let origin = crate::origin::Config::new(crate::Hop::new(1).unwrap()).produce(); let (claim, published) = match parked { Parked::Resolving => ( - Some(origin.dynamic("room", crate::origin::Route::default()).unwrap()), + Some(origin.dynamic_route("room", crate::origin::Route::default()).unwrap()), None, ), Parked::Acking | Parked::Ending => { diff --git a/rs/moq-net/src/ietf/subscriber.rs b/rs/moq-net/src/ietf/subscriber.rs index 6bec992b6f9..9b02c47dac3 100644 --- a/rs/moq-net/src/ietf/subscriber.rs +++ b/rs/moq-net/src/ietf/subscriber.rs @@ -2206,7 +2206,7 @@ where if self.going_away.is_set() { route.cost = crate::origin::Cost::DRAIN; } - entry.dynamic = Some(self.origin.dynamic(path, route)?); + entry.dynamic = Some(self.origin.dynamic_route(path, route)?); entry.generation += 1; tracing::info!(route = %self.origin.absolute(path), "namespace authorized again"); Ok(Some(entry.generation)) @@ -2271,7 +2271,7 @@ where if *newest == id { entry.route = route.clone(); if let Some(dynamic) = &entry.dynamic { - dynamic.update(entry.route.clone())?; + dynamic.update_route(entry.route.clone())?; } } Ok(()) @@ -2298,7 +2298,7 @@ where return Ok(()); } // Propagates Error::Unauthorized if the namespace is out of scope. - let dynamic = self.origin.dynamic(&path, route.clone())?; + let dynamic = self.origin.dynamic_route(&path, route.clone())?; entry.insert(BroadcastState { route: route.clone(), @@ -2353,7 +2353,7 @@ where if *newest != state.route { state.route = newest.clone(); if let Some(dynamic) = &state.dynamic { - dynamic.update(state.route.clone())?; + dynamic.update_route(state.route.clone())?; } } if state.tokens == 0 @@ -2522,7 +2522,7 @@ where route.cost = crate::origin::Cost::DRAIN; } if let Some(dynamic) = &entry.dynamic { - let _ = dynamic.update(entry.route.clone()); + let _ = dynamic.update_route(entry.route.clone()); } } diff --git a/rs/moq-net/src/lite/publisher.rs b/rs/moq-net/src/lite/publisher.rs index 1200012429b..547b5afe430 100644 --- a/rs/moq-net/src/lite/publisher.rs +++ b/rs/moq-net/src/lite/publisher.rs @@ -6593,7 +6593,7 @@ mod tests { let mut echoed_hops = Hops::new(); echoed_hops.push(crate::Hop::UNKNOWN).unwrap(); let _echoed = origin - .dynamic( + .dynamic_route( "echoed", crate::origin::Route::default() .with_hops(echoed_hops) @@ -6604,7 +6604,7 @@ mod tests { let mut local_hops = Hops::new(); local_hops.push(upstream).unwrap(); let _local = origin - .dynamic("local", crate::origin::Route::default().with_hops(local_hops)) + .dynamic_route("local", crate::origin::Route::default().with_hops(local_hops)) .unwrap(); // A SETUP that declares no origin of its own, so only the assigned one applies. @@ -7071,7 +7071,7 @@ mod tests { let mut _route = None; let mut held = None; match wait { - Wait::Broadcast => _route = Some(origin.dynamic("room", crate::origin::Route::default()).unwrap()), + Wait::Broadcast => _route = Some(origin.dynamic_route("room", crate::origin::Route::default()).unwrap()), Wait::Track => { let broadcast = origin.create_broadcast("room").unwrap(); let dynamic = broadcast.dynamic(); diff --git a/rs/moq-net/src/lite/subscriber.rs b/rs/moq-net/src/lite/subscriber.rs index 4b882f0f2fa..93fed76d213 100644 --- a/rs/moq-net/src/lite/subscriber.rs +++ b/rs/moq-net/src/lite/subscriber.rs @@ -5478,7 +5478,7 @@ impl Announced { return false; } // An error means the prefix is outside our origin's scope, so don't serve it. - match subscriber.origin.dynamic(&path, route.clone()) { + match subscriber.origin.dynamic_route(&path, route.clone()) { Ok(dynamic) => { self.attach(path, route, dynamic); true @@ -5674,7 +5674,7 @@ impl AnnouncedRoute { fn update(&mut self, route: crate::origin::Route) { self.route = route.clone(); self.drained = false; - let _ = self.dynamic.update(route); + let _ = self.dynamic.update_route(route); } /// Re-price the route to [`crate::origin::Cost::DRAIN`] (the peer sent a @@ -5687,7 +5687,7 @@ impl AnnouncedRoute { self.drained = true; let mut route = self.route.clone(); route.cost = crate::origin::Cost::DRAIN; - let _ = self.dynamic.update(route); + let _ = self.dynamic.update_route(route); } } diff --git a/rs/moq-net/src/model/broadcast.rs b/rs/moq-net/src/model/broadcast.rs index c84c445b631..fcb125db503 100644 --- a/rs/moq-net/src/model/broadcast.rs +++ b/rs/moq-net/src/model/broadcast.rs @@ -277,7 +277,8 @@ impl Producer { /// [`close`](Self::close), or the last producer dropping. /// /// Fails with [`Error::Closed`] on a standalone broadcast (one not created - /// through an origin, so there is nothing to announce into), once the broadcast + /// through an origin, so there is nothing to announce into), on a claim answer + /// still being [prepared](super::origin::Request::prepare), once the broadcast /// has closed, or once the origin's driver has been dropped. pub fn announce(&self, route: Route) -> Result<(), Error> { let mut announcer = self.alive.announcer.lock(); @@ -285,6 +286,37 @@ impl Producer { announcer.announce(route) } + /// Hand back an announcer withheld at creation and announce `route` once `admit` + /// agrees, decided under the origin's table lock. The announcer is installed only + /// when admitted; otherwise it drops, so this broadcast can never announce. + pub(super) fn announce_withheld( + &self, + mut announcer: Announcer, + route: Route, + admit: impl FnOnce() -> bool, + ) -> Result { + let refused = { + let mut slot = self.alive.announcer.lock(); + debug_assert!(slot.is_none(), "an announcer was already installed"); + // A close already retracted the slot, so an announcer installed now would + // outlive the broadcast. + if self.alive.state.lock().closing { + Err(Error::Closed) + } else { + match announcer.announce_if(route, admit) { + Ok(true) => { + *slot = Some(announcer); + return Ok(true); + } + refused => refused, + } + } + }; + // Dropped outside the announcer lock, as in `Alive::retract`. + drop(announcer); + refused + } + /// Retract this broadcast's advertisement, if any, from local consumers and /// peers alike. New requests for the path fail with [`Error::Unroutable`] and /// the broadcast the origin served from it ends, while tracks already in diff --git a/rs/moq-net/src/model/follow.rs b/rs/moq-net/src/model/follow.rs index 4623bcf359a..cb68c9e3c52 100644 --- a/rs/moq-net/src/model/follow.rs +++ b/rs/moq-net/src/model/follow.rs @@ -322,7 +322,7 @@ mod tests { let epoch = Epoch::mint(); // A prefix above the path covers it. - let pool = origin.dynamic("pool", route(&epoch)).unwrap(); + let pool = origin.dynamic_route("pool", route(&epoch)).unwrap(); assert_eq!(followed(&mut follow).await, ("start", "pool".into())); // A route beneath the path serves another broadcast. @@ -334,7 +334,7 @@ mod tests { assert_eq!(followed(&mut follow).await, ("update", "pool/job".into())); // The covering prefix no longer serves the path, so its changes are not seen. - pool.update(pool.route().with_cost(5)).unwrap(); + pool.update_route(pool.route().with_cost(5)).unwrap(); quiet(&mut follow).await; // Another instance at the path. @@ -345,7 +345,7 @@ mod tests { drop(exact); assert_eq!(followed(&mut follow).await, ("restart", "pool".into())); - pool.update(pool.route().with_cost(9)).unwrap(); + pool.update_route(pool.route().with_cost(9)).unwrap(); assert_eq!(followed(&mut follow).await, ("update", "pool".into())); drop(pool); @@ -357,7 +357,7 @@ mod tests { #[moq_clock::test] async fn follow_starts_on_the_serving_route_when_joining_late() { let origin = Hop::new(1).unwrap().produce(); - let _pool = origin.dynamic("pool", Route::default()).unwrap(); + let _pool = origin.dynamic_route("pool", Route::default()).unwrap(); let _exact = origin.publish("pool/job", Route::default()).unwrap(); let mut follow = origin.consume().follow("pool/job").unwrap(); @@ -378,7 +378,7 @@ mod tests { // Both land before the follower reads again, and the cursor delivers the prefix's start // ahead of the path's end, but the path went unserved in between. drop(exact); - let _pool = origin.dynamic("pool", route(&epoch)).unwrap(); + let _pool = origin.dynamic_route("pool", route(&epoch)).unwrap(); assert_eq!(followed(&mut follow).await, ("end", "pool/job".into())); assert_eq!(followed(&mut follow).await, ("start", "pool".into())); @@ -399,7 +399,7 @@ mod tests { assert_eq!(followed(&mut follow).await, ("start", "pool/job".into())); let epoch = Epoch::mint(); - let _pool = origin.dynamic("pool", route(&epoch)).unwrap(); + let _pool = origin.dynamic_route("pool", route(&epoch)).unwrap(); exact.announce(route(&epoch)).unwrap(); assert_eq!(followed(&mut follow).await, ("restart", "pool/job".into())); @@ -413,7 +413,7 @@ mod tests { let origin = Hop::new(1).unwrap().produce(); let mut follow = origin.consume().follow("pool/job").unwrap(); - let _pool = origin.dynamic("pool", Route::default()).unwrap(); + let _pool = origin.dynamic_route("pool", Route::default()).unwrap(); assert_eq!(followed(&mut follow).await, ("start", "pool".into())); let _exact = origin.publish("pool/job", Route::default()).unwrap(); @@ -429,7 +429,7 @@ mod tests { let _chat = origin .scope("", &chat) .unwrap() - .dynamic("room/alice", Route::default()) + .dynamic_route("room/alice", Route::default()) .unwrap(); let mut follow = origin.consume().follow("room/alice").unwrap(); @@ -488,7 +488,7 @@ mod tests { #[moq_clock::test] async fn announced_hands_out_a_held_takeover_once() { let origin = Hop::new(1).unwrap().produce(); - let dynamic = origin.dynamic("live", Route::default()).unwrap(); + let dynamic = origin.dynamic("live").unwrap(); let mut announced = origin.consume().announced_broadcast("live", None).unwrap(); // The wait is on the dynamic route's answer when the exact path takes over without an epoch. @@ -504,7 +504,7 @@ mod tests { #[moq_clock::test] async fn announced_hands_out_a_dropped_takeover_again() { let origin = Hop::new(1).unwrap().produce(); - let dynamic = origin.dynamic("live", Route::default()).unwrap(); + let dynamic = origin.dynamic("live").unwrap(); let mut announced = origin.consume().announced_broadcast("live", None).unwrap(); let (dropped, _publish) = futures::join!(available(&mut announced), async { @@ -524,7 +524,7 @@ mod tests { #[moq_clock::test] async fn announced_hands_out_a_gap_while_resolving_once() { let origin = Hop::new(1).unwrap().produce(); - let dynamic = origin.dynamic("", Route::default()).unwrap(); + let dynamic = origin.dynamic("").unwrap(); let mut announced = origin.consume().announced_broadcast("live", None).unwrap(); let (_arrival, _publish) = futures::join!(available(&mut announced), async { @@ -547,7 +547,7 @@ mod tests { let exact = origin.publish("live", route(&epoch)).unwrap(); let first = available(&mut announced).await; - let dynamic = origin.dynamic("", route(&epoch)).unwrap(); + let dynamic = origin.dynamic_route("", route(&epoch)).unwrap(); exact.unannounce(); let served = broadcast::Info::new().produce(); let (again, ()) = futures::join!(available(&mut announced), async { diff --git a/rs/moq-net/src/model/mod.rs b/rs/moq-net/src/model/mod.rs index d78f67cfc1e..63e3891e27d 100644 --- a/rs/moq-net/src/model/mod.rs +++ b/rs/moq-net/src/model/mod.rs @@ -55,8 +55,8 @@ pub use timed::Timed; pub mod origin { pub use super::follow::AnnouncedBroadcast; pub use super::origin_impl::{ - Config, Consumer, Cost, DEFAULT_UPDATE_HOLD, Driver, Dynamic, Preference, Producer, Request, Requesting, Route, - Routing, Source, + Config, Consumer, Cost, DEFAULT_UPDATE_HOLD, Driver, Dynamic, Preference, Prepared, Producer, Request, + Requesting, Route, Routing, Source, }; } diff --git a/rs/moq-net/src/model/origin.rs b/rs/moq-net/src/model/origin.rs index dcea246547d..edff1690e81 100644 --- a/rs/moq-net/src/model/origin.rs +++ b/rs/moq-net/src/model/origin.rs @@ -19,7 +19,7 @@ use super::{ front::{Action, Candidate, Event, Front, Refusal}, }; use crate::{ - AsPath, Error, InvalidPattern, Path, PathOwned, Pattern, Patterns, + AsPath, Epoch, Error, InvalidPattern, Path, PathOwned, Pattern, Patterns, coding::{BoundsExceeded, Decode, DecodeError, Decoder, Encode, EncodeError, Encoder}, path::Segment, time::{Deadlines, Instant}, @@ -1944,9 +1944,14 @@ impl Producer { /// pattern can spell (`*` or `**`), or [`Error::Closed`] once the origin's /// [`Driver`] has been dropped. pub fn create_broadcast(&self, path: impl AsPath) -> Result { - let path = path.as_path(); + let full = self.root.join(path.as_path()).to_owned(); + let (broadcast, announcer) = self.create_withheld(full)?; + Ok(broadcast.with_announcer(announcer)) + } - let full = self.root.join(&path).to_owned(); + /// A new broadcast at `full` with its announcer withheld, so it cannot announce + /// until the announcer is handed back. + fn create_withheld(&self, full: PathOwned) -> Result<(broadcast::Producer, Announcer), Error> { if !self.scope.permits(&full) || !self.scope.publishes(&full) { return Err(Error::Unauthorized); } @@ -1993,11 +1998,12 @@ impl Producer { advertised: false, }, )?; - Ok(source.with_announcer(Announcer { + let announcer = Announcer { entry, ingress, _keepalive: self.tasks.keepalive(), - })) + }; + Ok((source, announcer)) } /// Create and advertise a broadcast in one call. @@ -2094,16 +2100,28 @@ impl Producer { /// The advertisement is visible to [`Consumer::announced`] and forwarded by /// sessions for as long as the returned [`Dynamic`] (and every clone) lives. /// A consumer resolving a path under it through this route is handed to the - /// handler as a [`Request`] to materialize on demand. This is how a service - /// answers a whole subtree without publishing each path, and how sessions - /// land the routes a peer announces to them; a publisher that + /// handler as a [`Request`] to materialize on demand: [`Request::prepare`] + /// under a new epoch, fill, then [`Prepared::publish`] the exact path. Each + /// answer is its own publisher instance, so restarting one output never + /// splices into a copy of the last. This is how a service answers a whole + /// subtree without publishing each path ahead of time; a publisher that /// knows its broadcasts advertises each one's exact path with /// [`broadcast::Producer::announce`] instead, so subscribers can enumerate /// them. /// /// The prefix must overlap this producer's pattern scope. Individual requests /// remain authoritative and are refused when they do not match the scope. - pub fn dynamic(&self, prefix: impl AsPath, route: Route) -> Result { + pub fn dynamic(&self, prefix: impl AsPath) -> Result { + self.dynamic_inner(prefix, Route::default(), true) + } + + /// Land a peer's claim with its wire route metadata. + #[doc(hidden)] + pub fn dynamic_route(&self, prefix: impl AsPath, route: Route) -> Result { + self.dynamic_inner(prefix, route, false) + } + + fn dynamic_inner(&self, prefix: impl AsPath, route: Route, publishes: bool) -> Result { let announcing = Announcing::new(self, prefix)?; let serve = kio::Shared::::default(); serve.lock().requests.add_handler(); @@ -2118,6 +2136,7 @@ impl Producer { Ok(Dynamic { announcement, state: serve, + publisher: publishes.then(|| self.clone()), _keepalive: self.tasks.keepalive(), }) } @@ -2366,11 +2385,18 @@ pub(super) struct Announcer { impl Announcer { /// Advertise the broadcast's path with `route`, or re-price it in place. pub(super) fn announce(&mut self, route: Route) -> Result<(), Error> { - self.entry.update(route)?; + self.announce_if(route, || true).map(|_| ()) + } + + /// [`Self::announce`] once `admit` agrees; see [`AnnounceProducer::update_if`]. + pub(super) fn announce_if(&mut self, route: Route, admit: impl FnOnce() -> bool) -> Result { + if !self.entry.update_if(route, admit)? { + return Ok(false); + } if self.entry.guard.is_none() { self.entry.guard = Some(self.ingress.announce()); } - Ok(()) + Ok(true) } /// Withdraw the advertisement from local and remote consumers alike. @@ -2403,16 +2429,33 @@ pub(crate) struct AnnounceProducer { } impl AnnounceProducer { - /// Replace the route in place, epoch included; see [`Dynamic::update`]. + /// Replace the route in place, epoch included; see [`Dynamic::update_route`]. /// /// The prefix is fixed at announce time and a [`Route`] cannot name one: to /// move an advertisement, drop this and announce again. Fails with /// [`Error::Closed`] once the origin's [`Driver`] has been dropped. pub fn update(&self, route: Route) -> Result<(), Error> { + self.update_if(route, || true).map(|_| ()) + } + + /// [`Self::update`] once `admit` agrees, returning whether it did. `admit` runs + /// under the table lock, so nothing ordered after that lock (a release, a + /// retraction, the teardown) can change its answer before the route lands. + pub(super) fn update_if(&self, route: Route, admit: impl FnOnce() -> bool) -> Result { let mut shared = self.shared.lock(); if shared.closed { return Err(Error::Closed); } + if !self + .entries + .iter() + .all(|(prefix, id)| shared.routes.entry(prefix, *id).is_some()) + { + return Err(Error::Closed); + } + if !admit() { + return Ok(false); + } // The requests an epoch change released, refused once the table lock is gone: the // refusal wakes their fronts, which read the table. let mut released = Vec::new(); @@ -2456,7 +2499,7 @@ impl AnnounceProducer { request.resolved.get_or_insert(Err(Error::Unroutable)); } } - Ok(()) + Ok(true) } /// The route as last given, while advertised: every entry carries the same one. @@ -4742,7 +4785,7 @@ impl Resolution { /// subtree it never publishes ahead of time. /// /// Drop it to retract the route and reject the requests still waiting to be -/// served; [`update`](Self::update) re-prices it in place. +/// served. /// /// It keeps the origin's [`Driver`] running, like a published broadcast: a /// handler can drop every [`Producer`] and keep serving. @@ -4751,6 +4794,8 @@ pub struct Dynamic { /// The advertisement, retracted on drop. announcement: AnnounceProducer, state: kio::Shared, + /// Present for application claims, which publish each answer as an exact route. + publisher: Option, /// Producer-side children pin their parent where no cycle exists. The /// origin's state holds only the [`ServeState`], never this handle, so the /// driver cannot keep itself alive. @@ -4850,12 +4895,13 @@ impl Dynamic { /// those too. Route selection still applies: another route still at the old epoch /// outranks one without. /// To re-price, start from the current route: - /// `dynamic.update(dynamic.route().with_cost(cost))`. + /// `dynamic.update_route(dynamic.route().with_cost(cost))`. /// /// The prefix is fixed at announce time: to move a route, drop this and call /// [`Producer::dynamic`] again. Fails with [`Error::Closed`] once the origin's /// [`Driver`] has been dropped. - pub fn update(&self, route: Route) -> Result<(), Error> { + #[doc(hidden)] + pub fn update_route(&self, route: Route) -> Result<(), Error> { self.announcement.update(route) } @@ -4888,6 +4934,7 @@ impl Dynamic { path, producer, home: self.state.clone(), + publisher: self.publisher.clone(), })) } @@ -4918,16 +4965,33 @@ impl ServeState { path: &PathOwned, producer: &kio::Producer, result: Result, - ) { + ) -> bool { let mut state = shared.lock(); - if state.closed { - return; + let Some(resolved) = state.answer(path, producer, result) else { + return false; + }; + if let Ok(mut pending) = producer.write() { + pending.resolved.get_or_insert(resolved); + drop(state); + } + true + } + + /// Take the request off the queue and cache an accepted broadcast, returning what + /// its requesters resolve with, or `None` once it is no longer ours to answer. + fn answer( + &mut self, + path: &PathOwned, + producer: &kio::Producer, + result: Result, + ) -> Option> { + if self.closed { + return None; } // Released already (the route changed instance): the answer was for the old one, // so nothing resolves or caches it. - if state.requests.remove_if(path, |p| p.same_channel(producer)).is_none() { - return; - } + self.requests.remove_if(path, |p| p.same_channel(producer))?; + let state = self; let resolved = match result { Ok(broadcast) => { // If a live broadcast was already served for this path while we were @@ -4949,10 +5013,7 @@ impl ServeState { } Err(err) => Err(err), }; - if let Ok(mut pending) = producer.write() { - pending.resolved.get_or_insert(resolved); - drop(state); - } + Some(resolved) } /// Release every request, queued or handed to a handler, and forget the answers served, @@ -4977,9 +5038,9 @@ impl ServeState { /// A pending request for a broadcast to be served on demand. /// /// Yielded by [`Dynamic::poll_requested_broadcast`]. The requester is awaiting inside -/// [`Consumer::request_broadcast`]; [`accept`](Self::accept) resolves it with a live -/// broadcast (which the handler keeps producing into) and [`reject`](Self::reject) resolves -/// it with an error. Dropping the request without either rejects it. +/// [`Consumer::request_broadcast`]; [`prepare`](Self::prepare) then [`Prepared::publish`] +/// resolves it with a new exact-path broadcast, and [`reject`](Self::reject) resolves it +/// with an error. Dropping the request without either rejects it. pub struct Request { // Absolute path that was requested. path: PathOwned, @@ -4991,6 +5052,10 @@ pub struct Request { // The queue this request came from, so `accept` can cache the served // broadcast for repeat requests. home: kio::Shared, + + // Applications publish answers into this origin; session-forwarded claims accept + // their peer's already-routed broadcast directly instead. + publisher: Option, } impl Request { @@ -4999,20 +5064,89 @@ impl Request { &self.path } - /// Accept the request, resolving every awaiting requester with `broadcast`. + /// Start an answer under a new publisher `epoch`, hidden until it is published. + pub fn prepare(self, epoch: Epoch) -> Result { + let publisher = self.publisher.clone().ok_or(Error::Unroutable)?; + let (broadcast, announcer) = publisher.create_withheld(self.path.clone())?; + Ok(Prepared { + request: self, + broadcast, + announcer, + epoch, + }) + } + + /// Resolve a session-forwarded claim with its peer's already-routed broadcast. /// - /// The caller keeps producing into `broadcast` (e.g. a relay proxying tracks from - /// upstream); the requesters receive a consumer for it. Repeat requests for the - /// path share the served broadcast for as long as it stays live. + /// # Panics + /// + /// On a request from [`Producer::dynamic`], which answers only through [`Self::prepare`]. + #[doc(hidden)] pub fn accept(self, broadcast: impl Consume) { + assert!( + self.publisher.is_none(), + "an application claim answers through prepare and publish" + ); let broadcast = broadcast.consume(); - ServeState::resolve(&self.home, &self.path, &self.producer, Ok(broadcast)); + let _ = ServeState::resolve(&self.home, &self.path, &self.producer, Ok(broadcast)); // `self.producer` drops here, closing the channel; the value is still observable. } /// Reject the request, resolving every awaiting requester with `err`. pub fn reject(self, err: Error) { - ServeState::resolve(&self.home, &self.path, &self.producer, Err(err)); + let _ = ServeState::resolve(&self.home, &self.path, &self.producer, Err(err)); + } +} + +/// A claim answer being filled before its exact route is announced. +/// +/// Dropping it unpublished refuses the request, as dropping a [`Request`] does. +pub struct Prepared { + request: Request, + broadcast: broadcast::Producer, + // Withheld from the broadcast until `publish`, so the answer cannot announce + // itself under another epoch or skip the request's admission. + announcer: Announcer, + epoch: Epoch, +} + +impl Prepared { + /// The unannounced broadcast to fill before publishing. Its own + /// [`announce`](broadcast::Producer::announce) fails with [`Error::Closed`]: only + /// [`Self::publish`] announces it. + pub fn broadcast(&self) -> &broadcast::Producer { + &self.broadcast + } + + /// Announce the filled broadcast and resolve every requester waiting for it. + /// + /// Fails with [`Error::Unroutable`], announcing nothing, once the request was + /// released or its claim retracted, or with [`Error::Closed`] once the broadcast + /// closed. A failed answer can never announce. + pub fn publish(self) -> Result { + let Self { + request, + broadcast, + announcer, + epoch, + } = self; + let route = Route::default().with_epoch(epoch); + let answer = broadcast.consume(); + let mut resolved = None; + // Answered under the table lock that every release takes first, so the route + // lands only for a request still pending and no release can slip in between. + let admitted = broadcast.announce_withheld(announcer, route, || { + resolved = request.home.lock().answer(&request.path, &request.producer, Ok(answer)); + resolved.is_some() + })?; + let Some(resolved) = resolved.filter(|_| admitted) else { + return Err(Error::Unroutable); + }; + // Woken outside every lock: a front re-entering the table must not find it held. + if let Ok(mut pending) = request.producer.write() { + pending.resolved.get_or_insert(resolved); + } + Ok(broadcast) } } @@ -6893,7 +7027,7 @@ mod tests { #[cfg(feature = "async")] async fn mount_resolves_on_the_target_front() { let producer = origin(1).produce(); - let server = producer.dynamic(".svc", Route::default()).unwrap(); + let server = producer.dynamic_route(".svc", Route::default()).unwrap(); let project = mounted(&producer, "p1", &["**"]); let through = project.request_broadcast(".svc/foo", None); @@ -7076,11 +7210,11 @@ mod tests { .unwrap(); assert!(matches!(project.create_broadcast(".svc/foo"), Err(Error::Unauthorized))); assert!(matches!( - project.dynamic(".svc", Route::default()), + project.dynamic_route(".svc", Route::default()), Err(Error::Unauthorized) )); assert!(matches!( - project.dynamic(".svc/foo", Route::default()), + project.dynamic_route(".svc/foo", Route::default()), Err(Error::Unauthorized) )); project.publish("cam", Route::default()).unwrap(); @@ -7358,7 +7492,7 @@ mod tests { let _pool: Vec = order .map(|id| { producer - .dynamic("pool", Route::default().with_hops(hops(&[id])).with_cost(3)) + .dynamic_route("pool", Route::default().with_hops(hops(&[id])).with_cost(3)) .unwrap() }) .collect(); @@ -7428,10 +7562,10 @@ mod tests { async fn a_reprice_is_an_update() { let producer = origin(1).produce(); let mut announced = producer.consume().announced(); - let route = producer.dynamic("room", Route::default().with_cost(3)).unwrap(); + let route = producer.dynamic_route("room", Route::default().with_cost(3)).unwrap(); announced.expect_next_active("room").await; - route.update(Route::default().with_cost(5)).unwrap(); + route.update_route(Route::default().with_cost(5)).unwrap(); match announced.next().await.expect("no next") { AnnounceEvent::Update(update) => assert_eq!(update.route.cost, Cost::new(5)), other => panic!("should be an update: got {other:?}"), @@ -7449,11 +7583,11 @@ mod tests { let producer = origin(1).produce(); let mut announced = producer.consume().announced(); let route = producer - .dynamic("room", Route::default().with_auth(first.clone())) + .dynamic_route("room", Route::default().with_auth(first.clone())) .unwrap(); assert_eq!(announced.expect_next_active("room").await.auth, Some(first)); - route.update(Route::default().with_auth(second.clone())).unwrap(); + route.update_route(Route::default().with_auth(second.clone())).unwrap(); match announced.next().await.expect("no next") { AnnounceEvent::Update(update) => assert_eq!(update.route.auth, Some(second)), other => panic!("should be an update: got {other:?}"), @@ -7477,12 +7611,12 @@ mod tests { let consumer = producer.consume(); let mut announced = consumer.announced(); let old = producer - .dynamic("pool/job-0", Route::default().with_hops(hops(&[11]))) + .dynamic_route("pool/job-0", Route::default().with_hops(hops(&[11]))) .unwrap(); announced.expect_next_active("pool/job-0").await; let new = producer - .dynamic("pool/job-0", Route::default().with_hops(hops(&[10]))) + .dynamic_route("pool/job-0", Route::default().with_hops(hops(&[10]))) .unwrap(); announced.assert_next_wait(); @@ -7518,7 +7652,7 @@ mod tests { claims .scope("", &scopes(&[scope])) .unwrap() - .dynamic(prefix, Route::default().with_hops(hops(&[hop])).with_cost(cost)) + .dynamic_route(prefix, Route::default().with_hops(hops(&[hop])).with_cost(cost)) .unwrap() }; (producer, claim) @@ -7616,12 +7750,13 @@ mod tests { let _sticky = hold(&consumer, "room/job", &a).await; let c = producer - .dynamic("room", Route::default().with_hops(hops(&[12])).with_cost(1)) + .dynamic_route("room", Route::default().with_hops(hops(&[12])).with_cost(1)) .unwrap(); assert_eq!(announced.expect_next_restarted("room").await.cost, Cost::new(1)); quiet(&mut announced).await; - c.update(Route::default().with_hops(hops(&[12])).with_cost(3)).unwrap(); + c.update_route(Route::default().with_hops(hops(&[12])).with_cost(3)) + .unwrap(); assert_eq!(announced.expect_next_restarted("room").await.cost, Cost::new(2)); quiet(&mut announced).await; } @@ -7639,7 +7774,8 @@ mod tests { assert_eq!(announced.expect_next_active("room").await.cost, Cost::new(5)); let _sticky = hold(&consumer, "room/job", &a).await; - b.update(Route::default().with_hops(hops(&[11])).with_cost(3)).unwrap(); + b.update_route(Route::default().with_hops(hops(&[11])).with_cost(3)) + .unwrap(); assert_eq!(announced.expect_next_restarted("room").await.cost, Cost::new(3)); quiet(&mut announced).await; } @@ -7747,10 +7883,10 @@ mod tests { let consumer = producer.consume(); let anonymous = producer - .dynamic("room", Route::default().with_hops(hops(&[0])).with_cost(1)) + .dynamic_route("room", Route::default().with_hops(hops(&[0])).with_cost(1)) .unwrap(); let identified = producer - .dynamic("room", Route::default().with_hops(hops(&[10])).with_cost(5)) + .dynamic_route("room", Route::default().with_hops(hops(&[10])).with_cost(5)) .unwrap(); let _pending = consumer.request_broadcast("room/alice", None); @@ -7771,10 +7907,10 @@ mod tests { let demoted = producer .clone() .with_preference(Preference::new(-1)) - .dynamic("room", Route::default().with_hops(hops(&[10])).with_cost(1)) + .dynamic_route("room", Route::default().with_hops(hops(&[10])).with_cost(1)) .unwrap(); let unranked = producer - .dynamic("room", Route::default().with_hops(hops(&[11])).with_cost(5)) + .dynamic_route("room", Route::default().with_hops(hops(&[11])).with_cost(5)) .unwrap(); let _pending = consumer.request_broadcast("room/alice", None); @@ -7806,10 +7942,10 @@ mod tests { let mut announced = producer.consume().announced(); let dynamic = producer - .dynamic("room", Route::default().with_epoch(epoch()).with_cost(5)) + .dynamic_route("room", Route::default().with_epoch(epoch()).with_cost(5)) .unwrap(); announced.expect_next_active("room").await; - dynamic.update(dynamic.route().with_cost(1)).unwrap(); + dynamic.update_route(dynamic.route().with_cost(1)).unwrap(); let route = announced.expect_next_active("room").await; assert_eq!((route.epoch, route.cost), (Some(epoch()), Cost::new(1))); assert_eq!(dynamic.route().cost, Cost::new(1)); @@ -7933,7 +8069,7 @@ mod tests { assert_eq!(announced.expect_next_active("room/alice").await.cost, Cost::new(5)); let server = producer - .dynamic( + .dynamic_route( "room/alice", Route::default().with_epoch(epoch()).with_hops(hops(&[10])).with_cost(1), ) @@ -7986,7 +8122,7 @@ mod tests { .expect("resolves locally"); let server = producer - .dynamic( + .dynamic_route( "room/alice", Route::default().with_epoch(epoch()).with_hops(hops(&[10])).with_cost(1), ) @@ -8075,7 +8211,7 @@ mod tests { assert_eq!(listed(&mut tracks).await, "synced"); let server = producer - .dynamic( + .dynamic_route( "room/alice", Route::default().with_epoch(epoch()).with_hops(hops(&[10])).with_cost(1), ) @@ -8096,7 +8232,7 @@ mod tests { async fn a_front_through_a_covering_prefix_lists_nothing() { let producer = origin(1).produce(); let consumer = producer.consume(); - let server = producer.dynamic("room", Route::default()).unwrap(); + let server = producer.dynamic_route("room", Route::default()).unwrap(); let pending = consumer.request_broadcast("room/alice", None); let upstream = broadcast::Info::new().produce(); let _video = upstream.create_track("video", None).unwrap(); @@ -8117,7 +8253,7 @@ mod tests { let consumer = producer.consume(); let _local = producer.publish("room/alice", Route::default()).unwrap(); - let server = producer.dynamic("room/alice", Route::default()).unwrap(); + let server = producer.dynamic_route("room/alice", Route::default()).unwrap(); // Were the claim to win, the request would park on its handler forever. let resolved = moq_clock::timeout(Duration::from_secs(1), consumer.request_broadcast("room/alice", None)) @@ -8172,7 +8308,7 @@ mod tests { let mut announced = consumer.announced(); let server = producer - .dynamic( + .dynamic_route( "room/alice", Route::default().with_epoch(epoch()).with_hops(hops(&[10])).with_cost(2), ) @@ -8258,7 +8394,7 @@ mod tests { let producer = origin(1).produce(); let consumer = producer.consume(); let server = producer - .dynamic("room/alice", Route::default().with_hops(hops(&[10]))) + .dynamic_route("room/alice", Route::default().with_hops(hops(&[10]))) .unwrap(); let pending = consumer.request_broadcast("room/alice", None); let upstream = broadcast::Info::new().produce(); @@ -8339,7 +8475,7 @@ mod tests { let producer = origin(1).produce(); // A prefix route, which resolves any path beneath it optimistically. let server = producer - .dynamic("room", Route::default().with_hops(hops(&[10]))) + .dynamic_route("room", Route::default().with_hops(hops(&[10]))) .unwrap(); let upstream = broadcast::Info::new().produce(); let source = upstream.create_track("video", crate::track::Info::timed()).unwrap(); @@ -8391,7 +8527,7 @@ mod tests { async fn a_hop_in_a_chain_gets_its_own_front() { let producer = origin(1).produce(); let _incumbent = producer - .dynamic("room", Route::default().with_hops(hops(&[10]))) + .dynamic_route("room", Route::default().with_hops(hops(&[10]))) .unwrap(); let fronts = || producer.shared.lock().fronts.len(); @@ -8402,7 +8538,7 @@ mod tests { // The same publisher, now also reached through the peer. let _echo = producer - .dynamic("room", Route::default().with_hops(hops(&[10, 7]))) + .dynamic_route("room", Route::default().with_hops(hops(&[10, 7]))) .unwrap(); let _filtered = peer.request_broadcast("room/alice", None); assert_eq!(fronts(), 2, "the peer still shares the plain front"); @@ -8421,7 +8557,7 @@ mod tests { let producer = origin(1).produce(); let consumer = producer.consume(); let server = producer - .dynamic("room", Route::default().with_hops(hops(&[10]))) + .dynamic_route("room", Route::default().with_hops(hops(&[10]))) .unwrap(); let upstream = broadcast::Info::new().produce(); let source = upstream.create_track("video", crate::track::Info::timed()).unwrap(); @@ -8488,7 +8624,7 @@ mod tests { let producer = origin(1).produce(); let consumer = producer.consume(); let server = producer - .dynamic("room", Route::default().with_hops(hops(&[10]))) + .dynamic_route("room", Route::default().with_hops(hops(&[10]))) .unwrap(); let upstream = broadcast::Info::new().produce(); let source = upstream.create_track("video", None).unwrap(); @@ -8551,11 +8687,11 @@ mod tests { async fn a_peers_filtered_front_ends_once_unread() { let producer = origin(1).produce(); let server = producer - .dynamic("room", Route::default().with_hops(hops(&[10]))) + .dynamic_route("room", Route::default().with_hops(hops(&[10]))) .unwrap(); // The same publisher, also reached through the peer, at a price the plain front skips. let _echo = producer - .dynamic("room", Route::default().with_hops(hops(&[10, 7])).with_cost(100)) + .dynamic_route("room", Route::default().with_hops(hops(&[10, 7])).with_cost(100)) .unwrap(); let upstream = broadcast::Info::new().produce(); let source = upstream.create_track("video", crate::track::Info::timed()).unwrap(); @@ -8591,7 +8727,7 @@ mod tests { let peer = producer.consume().excluding(origin(7)); let mut view = peer.announced(); let incumbent = producer - .dynamic("room", Route::default().with_epoch(epoch()).with_hops(hops(&[10]))) + .dynamic_route("room", Route::default().with_epoch(epoch()).with_hops(hops(&[10]))) .unwrap(); view.expect_next_active("room").await; @@ -8602,7 +8738,7 @@ mod tests { // The same publisher, now also reached through the peer, outlives the incumbent. let echo = producer - .dynamic("room", Route::default().with_epoch(epoch()).with_hops(hops(&[10, 7]))) + .dynamic_route("room", Route::default().with_epoch(epoch()).with_hops(hops(&[10, 7]))) .unwrap(); drop(incumbent); drop(source); @@ -8631,7 +8767,7 @@ mod tests { async fn takeover_keeps_the_open_group_head(dies_first: bool) { let producer = origin(1).produce(); let first_server = producer - .dynamic( + .dynamic_route( "room/alice", Route::default().with_epoch(epoch()).with_hops(hops(&[10])).with_cost(5), ) @@ -8686,7 +8822,7 @@ mod tests { } let cost = if dies_first { 5 } else { 0 }; let replacement_server = producer - .dynamic( + .dynamic_route( "room/alice", Route::default() .with_epoch(epoch()) @@ -8916,8 +9052,8 @@ mod tests { #[cfg(feature = "async")] async fn duplicate_routes_aggregate_until_the_last_leaves() { let producer = origin(1).produce(); - let first = producer.dynamic("live", Route::default().with_cost(3)).unwrap(); - let second = producer.dynamic("live", Route::default().with_cost(1)).unwrap(); + let first = producer.dynamic_route("live", Route::default().with_cost(3)).unwrap(); + let second = producer.dynamic_route("live", Route::default().with_cost(1)).unwrap(); let mut announced = producer.consume().announced(); let Some(Some(AnnounceEvent::Start(update))) = announced.next().now_or_never() else { @@ -8941,14 +9077,14 @@ mod tests { let producer = origin(1).produce(); let scoped = producer.scope("", &scopes(&["room"])).unwrap(); let _broad = scoped - .dynamic("", Route::default()) + .dynamic_route("", Route::default()) .expect("an overlapping prefix is accepted"); let _ok = scoped - .dynamic("room/alice", Route::default()) + .dynamic_route("room/alice", Route::default()) .expect("a contained prefix is accepted"); assert!(matches!( - scoped.dynamic("other", Route::default()), + scoped.dynamic_route("other", Route::default()), Err(Error::Unauthorized) )); } @@ -8959,7 +9095,7 @@ mod tests { let producer = origin(1).produce(); let scope = Patterns::from("*/chat".parse::().unwrap()); let scoped = producer.scope("", &scope).unwrap(); - let dynamic = scoped.dynamic("", Route::default()).unwrap(); + let dynamic = scoped.dynamic_route("", Route::default()).unwrap(); let mut matching = producer .consume() @@ -8995,8 +9131,12 @@ mod tests { .scope("", &Patterns::from(pattern.parse::().unwrap())) .unwrap() }; - let _chat = scoped("*/chat").dynamic("", Route::default().with_cost(1)).unwrap(); - let _video = scoped("*/video").dynamic("", Route::default().with_cost(5)).unwrap(); + let _chat = scoped("*/chat") + .dynamic_route("", Route::default().with_cost(1)) + .unwrap(); + let _video = scoped("*/video") + .dynamic_route("", Route::default().with_cost(5)) + .unwrap(); let mut video = producer .consume() @@ -9026,7 +9166,7 @@ mod tests { let chat = producer .scope("", &scopes(&["room/live/chat"])) .unwrap() - .dynamic("room/live", Route::default().with_hops(hops(&[7])).with_cost(1)) + .dynamic_route("room/live", Route::default().with_hops(hops(&[7])).with_cost(1)) .unwrap(); assert_eq!(all.expect_next_active("room/live").await.cost, Cost::new(1)); assert_eq!(rooted.expect_next_active("").await.cost, Cost::new(1)); @@ -9036,14 +9176,14 @@ mod tests { let video_route = producer .scope("", &scopes(&["room/live/video"])) .unwrap() - .dynamic("room/live", Route::default().with_hops(hops(&[8])).with_cost(5)) + .dynamic_route("room/live", Route::default().with_hops(hops(&[8])).with_cost(5)) .unwrap(); all.assert_next_wait(); rooted.assert_next_wait(); assert_eq!(excluded.expect_next_active("room/live").await.cost, Cost::new(5)); assert_eq!(video.expect_next_active("room/live").await.cost, Cost::new(5)); - chat.update(Route::default().with_hops(hops(&[7])).with_cost(9)) + chat.update_route(Route::default().with_hops(hops(&[7])).with_cost(9)) .unwrap(); assert_eq!(all.expect_next_active("room/live").await.cost, Cost::new(5)); assert_eq!(rooted.expect_next_active("").await.cost, Cost::new(5)); @@ -9061,8 +9201,10 @@ mod tests { #[cfg(feature = "async")] async fn root_cursor_keeps_the_more_specific_covering_route() { let producer = origin(1).produce(); - let broad = producer.dynamic("room", Route::default().with_cost(1)).unwrap(); - let narrow = producer.dynamic("room/live", Route::default().with_cost(9)).unwrap(); + let broad = producer.dynamic_route("room", Route::default().with_cost(1)).unwrap(); + let narrow = producer + .dynamic_route("room/live", Route::default().with_cost(9)) + .unwrap(); let mut announced = producer .consume() .scope("room/live/video", &Patterns::from(Pattern::all())) @@ -9070,9 +9212,9 @@ mod tests { .announced(); assert_eq!(announced.expect_next_active("").await.cost, Cost::new(9)); - broad.update(Route::default().with_cost(0)).unwrap(); + broad.update_route(Route::default().with_cost(0)).unwrap(); announced.assert_next_wait(); - narrow.update(Route::default().with_cost(8)).unwrap(); + narrow.update_route(Route::default().with_cost(8)).unwrap(); assert_eq!(announced.expect_next_active("").await.cost, Cost::new(8)); drop(narrow); assert_eq!(announced.expect_next_active("").await.cost, Cost::new(0)); @@ -9088,7 +9230,9 @@ mod tests { .join("/"); let mut announced = producer.consume().announced(); - let dynamic = producer.dynamic(&path, Route::default()).expect("max depth is allowed"); + let dynamic = producer + .dynamic_route(&path, Route::default()) + .expect("max depth is allowed"); announced.expect_next_active(&path).await; let _pending = producer.consume().request_broadcast(&path, None); @@ -9100,7 +9244,7 @@ mod tests { async fn dynamic_exclusion_skips_routes_through_the_subscriber() { let producer = origin(1).produce(); let _server = producer - .dynamic("live", Route::default().with_hops(hops(&[7]))) + .dynamic_route("live", Route::default().with_hops(hops(&[7]))) .unwrap(); let mut excluded = producer.consume().excluding(origin(7)).announced(); @@ -9116,7 +9260,7 @@ mod tests { async fn announce_consumer_is_a_stream() { use futures::StreamExt; let producer = origin(1).produce(); - let server = producer.dynamic("live", Route::default()).unwrap(); + let server = producer.dynamic_route("live", Route::default()).unwrap(); let mut announced = producer.consume().announced(); let mut next = || StreamExt::next(&mut announced).now_or_never(); let Some(Some(AnnounceEvent::Start(update))) = next() else { @@ -9131,7 +9275,7 @@ mod tests { #[moq_clock::test] async fn dynamic_retracts() { let producer = origin(1).produce(); - let server = producer.dynamic("live", Route::default()).unwrap(); + let server = producer.dynamic_route("live", Route::default()).unwrap(); let mut announced = producer.consume().announced(); announced.expect_next_active("live").await; @@ -9170,7 +9314,7 @@ mod tests { let producer = origin(1).produce(); let consumer = producer.consume(); - let server = producer.dynamic("room", Route::default()).unwrap(); + let server = producer.dynamic_route("room", Route::default()).unwrap(); let pending = consumer.request_broadcast("room/alice", None); let request = queued(&server).await; @@ -9193,7 +9337,7 @@ mod tests { async fn served_requests_coalesce() { let producer = origin(1).produce(); let consumer = producer.consume(); - let server = producer.dynamic("room", Route::default()).unwrap(); + let server = producer.dynamic_route("room", Route::default()).unwrap(); let first = consumer.request_broadcast("room/alice", None); let second = consumer.request_broadcast("room/alice", None); @@ -9215,7 +9359,7 @@ mod tests { async fn retract_rejects_pending_requests() { let producer = origin(1).produce(); let consumer = producer.consume(); - let server = producer.dynamic("room", Route::default()).unwrap(); + let server = producer.dynamic_route("room", Route::default()).unwrap(); let pending = consumer.request_broadcast("room/alice", None); drop(server); @@ -9241,9 +9385,9 @@ mod tests { // Three identical routes, oldest first: the newest identical route wins // requests, and swapping between them emits no announce update. - let standby_server = producer.dynamic("room", Route::default()).unwrap(); - let second_server = producer.dynamic("room", Route::default()).unwrap(); - let incumbent_server = producer.dynamic("room", Route::default()).unwrap(); + let standby_server = producer.dynamic_route("room", Route::default()).unwrap(); + let second_server = producer.dynamic_route("room", Route::default()).unwrap(); + let incumbent_server = producer.dynamic_route("room", Route::default()).unwrap(); let mut resolving = Box::pin(consumer.routed_broadcast("room/alice")); assert!((&mut resolving).now_or_never().is_none()); @@ -9270,7 +9414,7 @@ mod tests { async fn split_horizon_skips_routes_through_the_requester() { let producer = origin(1).produce(); let _server = producer - .dynamic("room", Route::default().with_hops(hops(&[7]))) + .dynamic_route("room", Route::default().with_hops(hops(&[7]))) .unwrap(); // The requester's own bytes must not be served back to it. @@ -9296,11 +9440,11 @@ mod tests { let mut announced = producer.consume().announced(); let _ingest = producer - .dynamic("client", Route::default().with_hops(hops(&[5])).with_via(origin(5))) + .dynamic_route("client", Route::default().with_hops(hops(&[5])).with_via(origin(5))) .unwrap(); let _gateway = producer.publish("gateway", Route::default()).unwrap(); let _forwarded = peer - .dynamic( + .dynamic_route( "forwarded", Route::default().with_hops(hops(&[5, 7])).with_via(origin(7)), ) @@ -9315,7 +9459,7 @@ mod tests { // The mark survives narrowing the handle. let scoped = peer.scope("room", &Patterns::from(Pattern::all())).unwrap(); - let _nested = scoped.dynamic("x", Route::default().with_via(origin(8))).unwrap(); + let _nested = scoped.dynamic_route("x", Route::default().with_via(origin(8))).unwrap(); assert_eq!( announced.expect_next_active("room/x").await.source(), Source::Peer(origin(8)) @@ -9349,10 +9493,10 @@ mod tests { .with_hops(hops(chain)) .with_via(origin(via)) }; - let near = peer.dynamic("room", route(&[9, 2], 2)).unwrap(); + let near = peer.dynamic_route("room", route(&[9, 2], 2)).unwrap(); announced.assert_try_next_active("room"); - let _far = peer.dynamic("room", route(&[9, 3, 4], 4)).unwrap(); + let _far = peer.dynamic_route("room", route(&[9, 3, 4], 4)).unwrap(); drop(near); assert!(announced.try_next().is_none(), "the update is held"); step(Duration::from_millis(1)).await; @@ -9383,12 +9527,12 @@ mod tests { .with_hops(hops(chain)) .with_via(origin(via)) }; - let near = peer.dynamic("room", route(&[9, 2], 2)).unwrap(); + let near = peer.dynamic_route("room", route(&[9, 2], 2)).unwrap(); announced.expect_next_active("room").await; // The best route changes twice; the consumer sees only the last, once. - let far = peer.dynamic("room", route(&[9, 3, 4], 4)).unwrap(); - let farther = peer.dynamic("room", route(&[9, 5, 6, 7], 7)).unwrap(); + let far = peer.dynamic_route("room", route(&[9, 3, 4], 4)).unwrap(); + let farther = peer.dynamic_route("room", route(&[9, 5, 6, 7], 7)).unwrap(); let start = moq_clock::now(); drop(near); drop(far); @@ -9416,30 +9560,30 @@ mod tests { let route = |chain: &[u64], via| Route::default().with_hops(hops(chain)).with_via(origin(via)); - let near = peer.dynamic("named", route(&[9, 2], 2)).unwrap(); + let near = peer.dynamic_route("named", route(&[9, 2], 2)).unwrap(); announced.expect_next_active("named").await; drop(near); announced.expect_next_ended("named").await; let start = moq_clock::now(); - let _stale = peer.dynamic("named", route(&[9, 3, 4], 4)).unwrap(); + let _stale = peer.dynamic_route("named", route(&[9, 3, 4], 4)).unwrap(); match announced.next().await.unwrap() { AnnounceEvent::Start(announce) => assert_eq!(announce.route.hops, hops(&[9, 3, 4])), other => panic!("should be a start: got {other:?}"), } assert!(moq_clock::now() - start >= RETRACT_QUARANTINE); - let near = peer.dynamic("anonymous", route(&[0, 2], 2)).unwrap(); + let near = peer.dynamic_route("anonymous", route(&[0, 2], 2)).unwrap(); announced.expect_next_active("anonymous").await; drop(near); announced.expect_next_ended("anonymous").await; - let _other = peer.dynamic("anonymous", route(&[0, 3, 4], 4)).unwrap(); + let _other = peer.dynamic_route("anonymous", route(&[0, 3, 4], 4)).unwrap(); announced.expect_next_active("anonymous").await; // Retract and announce cycles at one clock reading queue the prefix once, // whether or not the route names its publisher. let queued = announced.anchoring.len(); for chain in [[9, 2], [0, 2], [9, 2], [0, 2]] { - let churn = peer.dynamic("churn", route(&chain, 2)).unwrap(); + let churn = peer.dynamic_route("churn", route(&chain, 2)).unwrap(); announced.expect_next_active("churn").await; drop(churn); announced.expect_next_ended("churn").await; @@ -9448,7 +9592,7 @@ mod tests { // A quarantine is forgotten once it ends: the cursor wakes to anchor it, // then again to drop it. - let gone = peer.dynamic("gone", route(&[9, 2], 2)).unwrap(); + let gone = peer.dynamic_route("gone", route(&[9, 2], 2)).unwrap(); announced.expect_next_active("gone").await; drop(gone); announced.expect_next_ended("gone").await; @@ -9472,9 +9616,9 @@ mod tests { // Publisher 9 ingests at relay 2; relay 3 relays 2's route. let direct = || Route::default().with_hops(hops(&[9, 2])).with_via(origin(2)); - let first = peer.dynamic("room", direct()).unwrap(); + let first = peer.dynamic_route("room", direct()).unwrap(); let relayed = peer - .dynamic("room", Route::default().with_hops(hops(&[9, 2, 3])).with_via(origin(3))) + .dynamic_route("room", Route::default().with_hops(hops(&[9, 2, 3])).with_via(origin(3))) .unwrap(); announced.expect_next_active("room").await; announced.assert_next_wait(); @@ -9485,7 +9629,7 @@ mod tests { announced.assert_next_wait(); // Relay 2 announces again, and the relayed copy is live with it. - let second = peer.dynamic("room", direct()).unwrap(); + let second = peer.dynamic_route("room", direct()).unwrap(); announced.expect_next_active("room").await; assert!(producer.shared.lock().withdrawn.is_empty()); @@ -9505,13 +9649,13 @@ mod tests { let peer = producer.clone().peer(); let mut announced = producer.consume().announced(); let route = Route::default().with_hops(hops(&[9, 2])); - let first = peer.dynamic("room", route.clone()).unwrap(); - let second = peer.dynamic("room", route.clone()).unwrap(); + let first = peer.dynamic_route("room", route.clone()).unwrap(); + let second = peer.dynamic_route("room", route.clone()).unwrap(); announced.expect_next_active("room").await; announced.assert_next_wait(); let remaining = if restart { // The older table entry has the newest advertisement after a restart. - first.update(route).unwrap(); + first.update_route(route).unwrap(); second.withdrawn(); announced.expect_next_restarted("room").await; first @@ -9531,9 +9675,11 @@ mod tests { async fn withdrawn_route_no_longer_covers_requests() { let producer = origin(1).produce(); let peer = producer.clone().peer(); - let direct = peer.dynamic("room", Route::default().with_hops(hops(&[9, 2]))).unwrap(); + let direct = peer + .dynamic_route("room", Route::default().with_hops(hops(&[9, 2]))) + .unwrap(); let _relayed = peer - .dynamic("room", Route::default().with_hops(hops(&[9, 2, 3]))) + .dynamic_route("room", Route::default().with_hops(hops(&[9, 2, 3]))) .unwrap(); let path = Path::new("room/video"); let id = producer @@ -9563,14 +9709,14 @@ mod tests { .with_epoch(epoch()) .with_hops(hops(&[7])) .with_via(origin(7)); - let _forwarded = peer.dynamic("room", route.clone()).unwrap(); + let _forwarded = peer.dynamic_route("room", route.clone()).unwrap(); assert_eq!( announced.expect_next_active("room").await.source(), Source::Peer(origin(7)) ); // The newest identical route wins, so the local twin takes over. - let local = producer.dynamic("room", route).unwrap(); + let local = producer.dynamic_route("room", route).unwrap(); match announced.next().await.expect("no next") { AnnounceEvent::Update(announce) => assert_eq!(announce.route.source(), Source::Local), other => panic!("should be an update: got {other:?}"), @@ -9590,7 +9736,7 @@ mod tests { let mut local = producer.consume().local().announced(); let _forwarded = peer - .dynamic("remote", Route::default().with_hops(hops(&[7])).with_via(origin(7))) + .dynamic_route("remote", Route::default().with_hops(hops(&[7])).with_via(origin(7))) .unwrap(); local.assert_next_wait(); @@ -9598,10 +9744,10 @@ mod tests { // and retracts from the local view when the local route goes, even though // the peer's still covers it. let _shadow = peer - .dynamic("both", Route::default().with_hops(hops(&[7])).with_via(origin(7))) + .dynamic_route("both", Route::default().with_hops(hops(&[7])).with_via(origin(7))) .unwrap(); let ingest = producer - .dynamic( + .dynamic_route( "both", Route::default().with_hops(hops(&[5])).with_via(origin(5)).with_cost(9), ) @@ -9642,7 +9788,7 @@ mod tests { let mut everyone = producer.consume().announced(); let _core = core - .dynamic("core", Route::default().with_hops(hops(&[7])).with_via(origin(7))) + .dynamic_route("core", Route::default().with_hops(hops(&[7])).with_via(origin(7))) .unwrap(); assert_eq!( everyone.expect_next_active("core").await.source(), @@ -9651,7 +9797,7 @@ mod tests { toward_core.assert_next_wait(); let _mesh = peer - .dynamic("mesh", Route::default().with_hops(hops(&[8])).with_via(origin(8))) + .dynamic_route("mesh", Route::default().with_hops(hops(&[8])).with_via(origin(8))) .unwrap(); assert_eq!( toward_core.expect_next_active("mesh").await.source(), @@ -9661,10 +9807,10 @@ mod tests { // A path both an upstream and a mesh peer reach: the upstream route is // cheaper, yet the upstream view selects the mesh peer's. let _cheap = core - .dynamic("both", Route::default().with_hops(hops(&[7])).with_via(origin(7))) + .dynamic_route("both", Route::default().with_hops(hops(&[7])).with_via(origin(7))) .unwrap(); let mesh = peer - .dynamic( + .dynamic_route( "both", Route::default().with_hops(hops(&[8])).with_via(origin(8)).with_cost(9), ) @@ -9680,7 +9826,7 @@ mod tests { let _still = core .clone() .peer() - .dynamic("again", Route::default().with_hops(hops(&[7])).with_via(origin(7))) + .dynamic_route("again", Route::default().with_hops(hops(&[7])).with_via(origin(7))) .unwrap(); toward_core.assert_next_wait(); @@ -9711,7 +9857,7 @@ mod tests { async fn handler_rejection_is_final() { let producer = origin(1).produce(); let consumer = producer.consume(); - let server = producer.dynamic("room", Route::default()).unwrap(); + let server = producer.dynamic_route("room", Route::default()).unwrap(); let pending = consumer.request_broadcast("room/alice", None); let request = queued(&server).await; @@ -9732,6 +9878,147 @@ mod tests { pending.await.expect("resolves"); } + #[moq_clock::test] + #[cfg(feature = "async")] + async fn claim_answer_is_hidden_until_published_with_its_epoch() { + let producer = origin(1).produce(); + let consumer = producer.consume(); + let claim = producer.dynamic("room").unwrap(); + let epoch = crate::Epoch::mint(); + let mut pending = Box::pin(consumer.request_broadcast("room/alice", None)); + assert!((&mut pending).now_or_never().is_none()); + + let prepared = queued(&claim).await.prepare(epoch.clone()).unwrap(); + let _track = prepared + .broadcast() + .create_track("video", crate::track::Info::timed()) + .unwrap(); + assert!((&mut pending).now_or_never().is_none()); + + let _published = prepared.publish().unwrap(); + let resolved = pending.await.unwrap(); + assert_eq!(resolved.info().epoch.as_ref(), Some(&epoch)); + assert!(resolved.track("video").is_ok()); + } + + /// Only `publish` announces a prepared answer, under its epoch and after admission. + #[moq_clock::test] + #[cfg(feature = "async")] + async fn a_prepared_answer_cannot_announce_itself() { + let producer = origin(1).produce(); + let mut announced = producer.consume().announced(); + let claim = producer.dynamic("room").unwrap(); + announced.assert_next_active("room"); + let pending = producer.consume().request_broadcast("room/alice", None); + let epoch = crate::Epoch::mint(); + let prepared = queued(&claim).await.prepare(epoch.clone()).unwrap(); + let answer = prepared.broadcast().clone(); + + let other = Route::default().with_epoch(crate::Epoch::mint()); + assert!(matches!(answer.announce(other), Err(Error::Closed))); + assert!(answer.route().is_none()); + announced.assert_next_wait(); + + let published = prepared.publish().unwrap(); + assert_eq!(published.route().and_then(|route| route.epoch), Some(epoch.clone())); + assert_eq!(pending.await.unwrap().info().epoch.as_ref(), Some(&epoch)); + } + + /// A refused answer keeps its announcer withheld, so a clone cannot announce it later. + #[moq_clock::test] + #[cfg(feature = "async")] + async fn a_refused_prepared_answer_cannot_announce_later() { + let producer = origin(1).produce(); + let claim = producer.dynamic("room").unwrap(); + let _pending = producer.consume().request_broadcast("room/alice", None); + let prepared = queued(&claim).await.prepare(crate::Epoch::mint()).unwrap(); + let answer = prepared.broadcast().clone(); + + drop(claim); + assert!(matches!(prepared.publish(), Err(Error::Unroutable))); + assert!(matches!(answer.announce(Route::default()), Err(Error::Closed))); + } + + #[moq_clock::test] + #[cfg(feature = "async")] + async fn dropping_a_prepared_claim_answer_refuses_the_request() { + let producer = origin(1).produce(); + let consumer = producer.consume(); + let claim = producer.dynamic("room").unwrap(); + let pending = consumer.request_broadcast("room/alice", None); + let prepared = queued(&claim).await.prepare(crate::Epoch::mint()).unwrap(); + drop(prepared); + assert!(matches!(pending.await, Err(Error::Unroutable))); + } + + /// An answer prepared for a claim that went away is refused, never announced. + #[moq_clock::test] + #[cfg(feature = "async")] + async fn a_prepared_answer_for_an_abandoned_claim_is_never_announced() { + let producer = origin(1).produce(); + let mut announced = producer.consume().announced(); + let claim = producer.dynamic("room").unwrap(); + announced.assert_next_active("room"); + let _pending = producer.consume().request_broadcast("room/alice", None); + let prepared = queued(&claim).await.prepare(crate::Epoch::mint()).unwrap(); + + drop(claim); + announced.assert_next_ended("room"); + assert!(matches!(prepared.publish(), Err(Error::Unroutable))); + announced.assert_next_wait(); + } + + /// An answer prepared before the claim changed instance is refused, never announced. + #[moq_clock::test] + #[cfg(feature = "async")] + async fn a_prepared_answer_for_a_released_request_is_never_announced() { + let producer = origin(1).produce(); + let mut announced = producer.consume().announced(); + let claim = producer.dynamic("room").unwrap(); + announced.assert_next_active("room"); + let _pending = producer.consume().request_broadcast("room/alice", None); + let prepared = queued(&claim).await.prepare(crate::Epoch::mint()).unwrap(); + + claim + .update_route(Route::default().with_epoch(crate::Epoch::mint())) + .unwrap(); + announced.assert_next_restarted("room"); + assert!(matches!(prepared.publish(), Err(Error::Unroutable))); + announced.assert_next_wait(); + } + + /// A request pinned to an epoch resolves only through the answer published under it, + /// never by asking the claim, which has no epoch of its own. + #[moq_clock::test] + #[cfg(feature = "async")] + async fn a_pinned_request_resolves_only_through_the_published_epoch() { + let producer = origin(1).produce(); + let consumer = producer.consume(); + let claim = producer.dynamic("room").unwrap(); + let epoch = crate::Epoch::mint(); + let unknown = consumer.request_broadcast("room/alice", crate::Epoch::mint()); + assert!(matches!(unknown.await, Err(Error::Unroutable))); + + let pending = consumer.request_broadcast("room/alice", None); + let _published = queued(&claim).await.prepare(epoch.clone()).unwrap().publish().unwrap(); + pending.await.expect("resolves"); + + let pinned = consumer.request_broadcast("room/alice", epoch.clone()).await; + assert_eq!(pinned.expect("resolves").info().epoch.as_ref(), Some(&epoch)); + let stale = consumer.request_broadcast("room/alice", crate::Epoch::mint()); + assert!(matches!(stale.await, Err(Error::Unroutable))); + } + + #[moq_clock::test] + #[cfg(feature = "async")] + #[should_panic(expected = "prepare and publish")] + async fn an_application_claim_cannot_accept_an_arbitrary_broadcast() { + let producer = origin(1).produce(); + let claim = producer.dynamic("room").unwrap(); + let _pending = producer.consume().request_broadcast("room/alice", None); + queued(&claim).await.accept(broadcast::Info::new().produce()); + } + /// A refusal from the longest prefix is the answer: neither a costlier advertiser of /// that prefix nor a catch-all is asked instead. #[moq_clock::test] @@ -9739,9 +10026,9 @@ mod tests { async fn refusal_never_falls_through() { let producer = origin(1).produce(); let consumer = producer.consume(); - let catch_all = producer.dynamic("", Route::default()).unwrap(); - let winner = producer.dynamic("room", Route::default()).unwrap(); - let sibling = producer.dynamic("room", Route::default().with_cost(2)).unwrap(); + let catch_all = producer.dynamic_route("", Route::default()).unwrap(); + let winner = producer.dynamic_route("room", Route::default()).unwrap(); + let sibling = producer.dynamic_route("room", Route::default().with_cost(2)).unwrap(); let mut pending = Box::pin(consumer.request_broadcast("room/alice", None)); assert!((&mut pending).now_or_never().is_none()); @@ -9767,7 +10054,7 @@ mod tests { async fn superseded_refusal_does_not_end_the_request() { let producer = origin(1).produce(); let consumer = producer.consume(); - let stale = producer.dynamic("room", Route::default()).unwrap(); + let stale = producer.dynamic_route("room", Route::default()).unwrap(); let mut pending = Box::pin(consumer.request_broadcast("room/alice", None)); assert!((&mut pending).now_or_never().is_none()); @@ -9794,13 +10081,13 @@ mod tests { async fn refusal_from_a_beaten_route_asks_the_new_winner() { let producer = origin(1).produce(); let consumer = producer.consume(); - let stale = producer.dynamic("room", Route::default()).unwrap(); + let stale = producer.dynamic_route("room", Route::default()).unwrap(); let mut pending = Box::pin(consumer.request_broadcast("room/alice", None)); assert!((&mut pending).now_or_never().is_none()); let request = queued(&stale).await; - let winner = producer.dynamic("room/alice", Route::default()).unwrap(); + let winner = producer.dynamic_route("room/alice", Route::default()).unwrap(); request.reject(Error::NotFound); let source = broadcast::Info::new().produce(); queued(&winner).await.accept(&source); @@ -9821,7 +10108,7 @@ mod tests { async fn routed_broadcast_waits_out_a_rejection() { let producer = origin(1).produce(); let consumer = producer.consume(); - let server = producer.dynamic("room", Route::default()).unwrap(); + let server = producer.dynamic_route("room", Route::default()).unwrap(); let mut resolving = Box::pin(consumer.routed_broadcast("room/alice")); assert!((&mut resolving).now_or_never().is_none()); @@ -9836,7 +10123,7 @@ mod tests { assert!(server.poll_requested_broadcast(&kio::Waiter::noop()).is_pending()); // A re-price moves the table: the retry reaches the handler, which serves it. - server.update(Route::default().with_cost(2)).unwrap(); + server.update_route(Route::default().with_cost(2)).unwrap(); assert!((&mut resolving).now_or_never().is_none()); let request = queued(&server).await; let served = broadcast::Info::new().produce(); @@ -9850,7 +10137,7 @@ mod tests { async fn routed_broadcast_reports_teardown_as_closed() { let (producer, driver) = Producer::new(Config::new(origin(1))); let consumer = producer.consume(); - let _server = producer.dynamic("room", Route::default()).unwrap(); + let _server = producer.dynamic_route("room", Route::default()).unwrap(); // Park on the covering route, past the loop's closed check. let mut resolving = Box::pin(consumer.routed_broadcast("room/alice")); @@ -9873,7 +10160,7 @@ mod tests { async fn routed_broadcast_wakes_for_a_local_broadcast() { let producer = origin(1).produce(); let consumer = producer.consume(); - let server = producer.dynamic("room", Route::default()).unwrap(); + let server = producer.dynamic_route("room", Route::default()).unwrap(); let mut resolving = Box::pin(consumer.routed_broadcast("room/alice")); assert!((&mut resolving).now_or_never().is_none()); @@ -9897,7 +10184,7 @@ mod tests { async fn late_track_on_a_served_front_replays() { let producer = origin(1).produce(); let consumer = producer.consume(); - let server = producer.dynamic("room", Route::default()).unwrap(); + let server = producer.dynamic_route("room", Route::default()).unwrap(); let source = broadcast::Info::new().produce(); for name in ["a", "b"] { @@ -9937,7 +10224,7 @@ mod tests { let producer = origin(1).produce(); let consumer = producer.consume(); - let broad_server = producer.dynamic("", Route::default()).unwrap(); + let broad_server = producer.dynamic_route("", Route::default()).unwrap(); // A narrow advertise-only claim: requests under it must NOT route to the // broad server; they fall through to the (absent) fallback handler. let _narrow = producer.announce(".dash", Route::default()).unwrap(); @@ -9962,7 +10249,7 @@ mod tests { let producer = origin(1).produce(); let consumer = producer.consume(); let mut announced = consumer.announced(); - let dynamic = producer.dynamic("", Route::default()).unwrap(); + let dynamic = producer.dynamic_route("", Route::default()).unwrap(); // The root claim is advertised like any other prefix. announced.expect_next_active("").await; @@ -9996,7 +10283,7 @@ mod tests { #[cfg(feature = "async")] async fn out_of_scope_request_never_reaches_the_dynamic_handler() { let producer = origin(1).produce(); - let dynamic = producer.dynamic("", Route::default()).unwrap(); + let dynamic = producer.dynamic_route("", Route::default()).unwrap(); let scoped = producer.consume().scope("", &scopes(&["tenant-a"])).unwrap(); // `tenant-a-other` shares a character prefix but not a segment, so this @@ -10081,7 +10368,7 @@ mod tests { let mut announced = consumer.announced(); announced.expect_next_active("room").await; - let _server = producer.dynamic("served", Route::default()).unwrap(); + let _server = producer.dynamic_route("served", Route::default()).unwrap(); let pending = consumer.request_broadcast("served/path", None); drop(driver); @@ -10126,7 +10413,7 @@ mod tests { #[test] fn internal_route_requests_are_closed_on_teardown() { let (producer, mut driver) = Producer::new(Config::new(origin(1))); - let server = producer.dynamic("room", Route::default()).unwrap(); + let server = producer.dynamic_route("room", Route::default()).unwrap(); let _pending = producer.consume().request_broadcast("room/alice", None); driver.poll(Instant::now(), &kio::Waiter::noop()).unwrap(); let Poll::Ready(Ok(request)) = server.poll_requested_broadcast(&kio::Waiter::noop()) else { @@ -10158,7 +10445,7 @@ mod tests { let consumer = producer.consume(); let server = producer - .dynamic("room", Route::default().with_epoch(epoch()).with_hops(hops(first))) + .dynamic_route("room", Route::default().with_epoch(epoch()).with_hops(hops(first))) .unwrap(); let pending = consumer.request_broadcast("room/alice", None); @@ -10201,7 +10488,7 @@ mod tests { /// back its handle, ready to answer the front's re-request. fn standby(&self, first: &[u64]) -> Dynamic { self.producer - .dynamic("room", Route::default().with_epoch(epoch()).with_hops(hops(first))) + .dynamic_route("room", Route::default().with_epoch(epoch()).with_hops(hops(first))) .unwrap() } } @@ -10255,7 +10542,7 @@ mod tests { let producer = origin(1).produce(); let consumer = producer.consume(); let first = producer - .dynamic("room", Route::default().with_hops(hops(&[10])).with_cost(5)) + .dynamic_route("room", Route::default().with_hops(hops(&[10])).with_cost(5)) .unwrap(); let pending = consumer.request_broadcast("room/alice", None); let source = broadcast::Info::new().produce(); @@ -10266,7 +10553,7 @@ mod tests { deliver(&track, &mut subscription, b"first").await; let second = producer - .dynamic("room", Route::default().with_hops(hops(&[11])).with_cost(1)) + .dynamic_route("room", Route::default().with_hops(hops(&[11])).with_cost(1)) .unwrap(); deliver(&track, &mut subscription, b"pinned").await; @@ -10380,7 +10667,7 @@ mod tests { let producer = origin(1).produce(); let consumer = producer.consume(); let old = producer - .dynamic("room", Route::default().with_epoch(crate::Epoch::mint())) + .dynamic_route("room", Route::default().with_epoch(crate::Epoch::mint())) .unwrap(); let pending = consumer.request_broadcast("room/alice", None); let request = queued(&old).await; @@ -10410,7 +10697,7 @@ mod tests { let consumer = producer.consume(); let old = crate::Epoch::mint(); let dynamic = producer - .dynamic("room", Route::default().with_epoch(old.clone())) + .dynamic_route("room", Route::default().with_epoch(old.clone())) .unwrap(); let pending = consumer.request_broadcast("room/alice", None); let pinned = consumer.request_broadcast("room/alice", old); @@ -10421,9 +10708,9 @@ mod tests { let epoch = crate::Epoch::mint(); if answer_first { request.accept(&stale); - dynamic.update(dynamic.route().with_epoch(epoch.clone())).unwrap(); + dynamic.update_route(dynamic.route().with_epoch(epoch.clone())).unwrap(); } else { - dynamic.update(dynamic.route().with_epoch(epoch.clone())).unwrap(); + dynamic.update_route(dynamic.route().with_epoch(epoch.clone())).unwrap(); request.accept(&stale); } @@ -10466,12 +10753,12 @@ mod tests { let producer = origin(1).produce(); let consumer = producer.consume(); let dynamic = producer - .dynamic("room", Route::default().with_epoch(crate::Epoch::mint())) + .dynamic_route("room", Route::default().with_epoch(crate::Epoch::mint())) .unwrap(); let pending = consumer.request_broadcast("room/alice", None); queued(&dynamic).await.reject(Error::NotFound); let epoch = crate::Epoch::mint(); - dynamic.update(dynamic.route().with_epoch(epoch.clone())).unwrap(); + dynamic.update_route(dynamic.route().with_epoch(epoch.clone())).unwrap(); let fresh = broadcast::Info::new().produce(); let fresh_track = fresh.create_track("video", crate::track::Info::timed()).unwrap(); @@ -10491,15 +10778,15 @@ mod tests { let consumer = producer.consume(); let old = crate::Epoch::mint(); let dynamic = producer - .dynamic("room", Route::default().with_epoch(old.clone())) + .dynamic_route("room", Route::default().with_epoch(old.clone())) .unwrap(); let pending = consumer.request_broadcast("room/alice", None); let request = queued(&dynamic).await; dynamic - .update(dynamic.route().with_epoch(crate::Epoch::mint())) + .update_route(dynamic.route().with_epoch(crate::Epoch::mint())) .unwrap(); - dynamic.update(dynamic.route().with_epoch(old.clone())).unwrap(); + dynamic.update_route(dynamic.route().with_epoch(old.clone())).unwrap(); let stale = broadcast::Info::new().produce(); let _stale_track = stale.create_track("video", crate::track::Info::timed()).unwrap(); request.accept(&stale); @@ -10521,7 +10808,7 @@ mod tests { async fn losing_an_epoch_is_another_instance() { let producer = origin(1).produce(); let consumer = producer.consume(); - let dynamic = producer.dynamic("room", Route::default()).unwrap(); + let dynamic = producer.dynamic_route("room", Route::default()).unwrap(); let pending = consumer.request_broadcast("room/alice", None); let old = broadcast::Info::new().produce(); let _old_track = old.create_track("video", crate::track::Info::timed()).unwrap(); @@ -10529,11 +10816,11 @@ mod tests { let resolved = pending.await.expect("resolves"); dynamic - .update(dynamic.route().with_epoch(crate::Epoch::mint())) + .update_route(dynamic.route().with_epoch(crate::Epoch::mint())) .unwrap(); let mut route = dynamic.route(); route.epoch = None; - dynamic.update(route).unwrap(); + dynamic.update_route(route).unwrap(); let retry = consumer.request_broadcast("room/alice", None); let fresh = broadcast::Info::new().produce(); @@ -10701,7 +10988,7 @@ mod tests { for first in [&[][..], &[0][..], &[10][..]] { let (mut rig, server, _source) = ResumeRig::new(first).await; let standby = rig.standby(&[10, 20]); - server.update(Route::default().with_hops(hops(&[11]))).unwrap(); + server.update_route(Route::default().with_hops(hops(&[11]))).unwrap(); let mut group = rig.incumbent_track.append_group().unwrap(); group.write_frame(crate::Timestamp::ZERO, b"after".as_ref()).unwrap(); @@ -10740,11 +11027,11 @@ mod tests { None => producer.consume(), }; let incumbent = producer - .dynamic("room", Route::default().with_epoch(epoch()).with_hops(hops(&[10]))) + .dynamic_route("room", Route::default().with_epoch(epoch()).with_hops(hops(&[10]))) .unwrap(); // The same publisher, reached through the requesting peer. let echo = producer - .dynamic("room", Route::default().with_epoch(epoch()).with_hops(hops(&[10, 7]))) + .dynamic_route("room", Route::default().with_epoch(epoch()).with_hops(hops(&[10, 7]))) .unwrap(); let pending = consumer.request_broadcast("room/alice", None); @@ -10807,7 +11094,7 @@ mod tests { // Session A: an assigned anonymous hop serving the path. let server_a = producer - .dynamic("room", Route::default().with_hops(hops(&[10]))) + .dynamic_route("room", Route::default().with_hops(hops(&[10]))) .unwrap(); // Session C: a third anonymous session, excluding the hop the server @@ -10863,7 +11150,7 @@ mod tests { // Session B attaches at the same path. Its front is served immediately. let server_b = producer - .dynamic("room", Route::default().with_hops(hops(&[20]))) + .dynamic_route("room", Route::default().with_hops(hops(&[20]))) .unwrap(); let pending = consumer.request_broadcast("room/alice", None); let request = queued(&server_b).await; @@ -10905,7 +11192,7 @@ mod tests { // A metadata-only reprice of the only route: nothing re-requests and the // subscription keeps flowing from the same source. incumbent - .update(Route::default().with_hops(hops(&[10])).with_cost(9)) + .update_route(Route::default().with_hops(hops(&[10])).with_cost(9)) .unwrap(); let track = source.create_track("audio", crate::track::Info::timed()).unwrap(); @@ -10939,7 +11226,7 @@ mod tests { // keeps serving. The front migrates to the standby without waiting for // the death. incumbent - .update( + .update_route( Route::default() .with_epoch(epoch()) .with_hops(hops(&[10])) @@ -11036,7 +11323,7 @@ mod tests { let producer = origin(1).produce(); let consumer = producer.consume(); let server = producer - .dynamic("room", Route::default().with_hops(hops(&[10]))) + .dynamic_route("room", Route::default().with_hops(hops(&[10]))) .unwrap(); let pending = consumer.request_broadcast("room/alice", None); @@ -11084,7 +11371,7 @@ mod tests { async fn a_closed_source_is_not_requested_again_from_its_standing_route() { let producer = origin(1).produce(); let server = producer - .dynamic("room", Route::default().with_hops(hops(&[10]))) + .dynamic_route("room", Route::default().with_hops(hops(&[10]))) .unwrap(); let pending = producer.consume().request_broadcast("room/alice", None); let source = broadcast::Info::new().produce(); @@ -11171,7 +11458,7 @@ mod tests { async fn a_held_group_continues_after_its_track_goes_unread() { let producer = origin(1).produce(); let server = producer - .dynamic("live", Route::default().with_hops(hops(&[10]))) + .dynamic_route("live", Route::default().with_hops(hops(&[10]))) .unwrap(); let pending = producer.consume().request_broadcast("live", None); let source = broadcast::Info::new().produce(); @@ -11259,13 +11546,17 @@ mod tests { .expect("resolves"); let mid = origin(2).produce(); - let mid_server = mid.dynamic("room", Route::default().with_hops(hops(&[10]))).unwrap(); + let mid_server = mid + .dynamic_route("room", Route::default().with_hops(hops(&[10]))) + .unwrap(); let mid_pending = mid.consume().request_broadcast("room/alice", None); queued(&mid_server).await.accept(&leaf_front); let mid_resolved = mid_pending.await.expect("mid resolves"); let edge = origin(3).produce(); - let edge_server = edge.dynamic("room", Route::default().with_hops(hops(&[20]))).unwrap(); + let edge_server = edge + .dynamic_route("room", Route::default().with_hops(hops(&[20]))) + .unwrap(); let edge_pending = edge.consume().request_broadcast("room/alice", None); queued(&edge_server).await.accept(&mid_resolved); let edge_resolved = edge_pending.await.expect("edge resolves"); @@ -11394,7 +11685,7 @@ mod tests { ) { let producer = origin(1).produce(); let server = producer - .dynamic("room", Route::default().with_epoch(epoch()).with_hops(hops(&[10]))) + .dynamic_route("room", Route::default().with_epoch(epoch()).with_hops(hops(&[10]))) .unwrap(); let pending = producer.consume().request_broadcast("room/alice", None); let upstream = broadcast::Info::new().produce(); @@ -11727,7 +12018,7 @@ mod tests { let (producer, driver) = Producer::new(Config::new(origin(1))); let run = moq_clock::sim::spawn(crate::time::run(driver)); let consumer = producer.consume(); - let server = producer.dynamic("room", Route::default()).unwrap(); + let server = producer.dynamic_route("room", Route::default()).unwrap(); drop(producer); let pending = consumer.request_broadcast("room/alice", None); @@ -11831,19 +12122,21 @@ mod tests { #[moq_clock::test] async fn source_selection_leases_survive_reprices_but_never_revive_pending_work() { let producer = origin(1).produce(); - let broad = producer.dynamic("room", Route::default().with_via(origin(2))).unwrap(); + let broad = producer + .dynamic_route("room", Route::default().with_via(origin(2))) + .unwrap(); let selected = broad.request_validity(&Path::new("room/a")).unwrap(); let pending = selected.current(); assert!(!pending.is_closed()); - broad.update(broad.route().with_cost(Cost::from(7))).unwrap(); + broad.update_route(broad.route().with_cost(Cost::from(7))).unwrap(); assert!(!pending.is_closed()); // Another peer's winning route cannot change what a request on peer 2 names. let other = producer - .dynamic("room/a", Route::default().with_via(origin(3))) + .dynamic_route("room/a", Route::default().with_via(origin(3))) .unwrap(); assert!(!pending.is_closed()); let replacement = producer - .dynamic("room/a", Route::default().with_via(origin(2))) + .dynamic_route("room/a", Route::default().with_via(origin(2))) .unwrap(); assert!(pending.is_closed()); assert!(selected.current().is_closed()); @@ -11861,7 +12154,9 @@ mod tests { #[moq_clock::test] async fn source_selection_unregisters_without_retaining_the_source() { let producer = origin(1).produce(); - let route = producer.dynamic("room", Route::default().with_via(origin(2))).unwrap(); + let route = producer + .dynamic_route("room", Route::default().with_via(origin(2))) + .unwrap(); let path = Path::new("room/a"); let selected = route.request_validity(&path).unwrap(); let lease = selected.current(); @@ -11916,7 +12211,7 @@ mod tests { ..Default::default() }); let consumer = producer.consume(); - let _served = producer.dynamic("room", Route::default()).unwrap(); + let _served = producer.dynamic_route("room", Route::default()).unwrap(); // A consumer outlives its producer by design, so the task set can refuse // submissions while the origin is still open. The front's task is then // dropped on the spot, taking its `Watch` with it: the request must not diff --git a/rs/moq-net/tests/integration/drained_claim.rs b/rs/moq-net/tests/integration/drained_claim.rs index 938bf01c632..84ac5f0ad17 100644 --- a/rs/moq-net/tests/integration/drained_claim.rs +++ b/rs/moq-net/tests/integration/drained_claim.rs @@ -56,7 +56,7 @@ impl Worker { let origin = produce_origin(hop); let claim = Rc::new( origin - .dynamic("pool", origin::Route::default().with_cost(cost)) + .dynamic_route("pool", origin::Route::default().with_cost(cost)) .unwrap(), ); let outputs = Rc::new(RefCell::new(Vec::new())); @@ -103,7 +103,9 @@ async fn drained_claim(version: &str) { // A closes its output and drains its claim, so B wins the path from here on. a.outputs.borrow().iter().for_each(|(output, _)| output.close()); - a.claim.update(a.claim.route().with_cost(origin::Cost::DRAIN)).unwrap(); + a.claim + .update_route(a.claim.route().with_cost(origin::Cost::DRAIN)) + .unwrap(); // Past the linger, which is as long as the cache window, nothing reads the relay's // front for the path. moq_clock::sleep(moq_net::cache::DEFAULT_EXPIRY * 2).await; diff --git a/rs/moq-net/tests/integration/restart.rs b/rs/moq-net/tests/integration/restart.rs index 0392f722779..c5b24d1d1a2 100644 --- a/rs/moq-net/tests/integration/restart.rs +++ b/rs/moq-net/tests/integration/restart.rs @@ -182,7 +182,7 @@ struct Worker { impl Worker { fn new(hop: u64) -> Self { let origin = produce_origin(hop); - let claim = Rc::new(origin.dynamic("pool", origin::Route::default()).unwrap()); + let claim = Rc::new(origin.dynamic_route("pool", origin::Route::default()).unwrap()); let outputs = Rc::new(RefCell::new(Vec::new())); let (handler, served) = (claim.clone(), outputs.clone()); drop(moq_clock::sim::spawn(async move { @@ -265,7 +265,7 @@ impl Claim { fn new(origin: &origin::Producer, epoch: Option) -> Self { let mut route = origin::Route::default(); route.epoch = epoch; - let dynamic = Rc::new(origin.dynamic("live", route).unwrap()); + let dynamic = Rc::new(origin.dynamic_route("live", route).unwrap()); let outputs = Rc::new(RefCell::new(Vec::new())); let (handler, served) = (dynamic.clone(), outputs.clone()); drop(moq_clock::sim::spawn(async move { @@ -292,7 +292,7 @@ impl Claim { fn update_epoch(&self, epoch: Option) { let mut route = self.dynamic.route(); route.epoch = epoch; - self.dynamic.update(route).unwrap(); + self.dynamic.update_route(route).unwrap(); } } @@ -320,7 +320,7 @@ async fn dynamic_epoch(version: &str, from: Option, to: Option) { assert_eq!(read(&mut sticky).await, "old:0", "{version}"); // A re-price at the same epoch is an update at most: every handle survives. - claim.dynamic.update(claim.dynamic.route().with_cost(5)).unwrap(); + claim.dynamic.update_route(claim.dynamic.route().with_cost(5)).unwrap(); while let Ok(event) = moq_clock::timeout(Duration::from_secs(1), announced.next()).await { assert!( matches!(event, Some(announce::Event::Update(_))), @@ -401,9 +401,12 @@ async fn dynamic_epoch_second_route_keeps_winning() { let (a, _) = epochs(); let origin = produce_origin(1); let first = Claim::new(&origin, Some(a.clone())); - first.dynamic.update(first.dynamic.route().with_cost(1)).unwrap(); + first.dynamic.update_route(first.dynamic.route().with_cost(1)).unwrap(); let second = Claim::new(&origin, Some(a.clone())); - second.dynamic.update(second.dynamic.route().with_cost(5)).unwrap(); + second + .dynamic + .update_route(second.dynamic.route().with_cost(5)) + .unwrap(); let mut announced = origin.consume().announced(); match next_event(&mut announced).await { announce::Event::Start(announce) => assert_eq!(announce.route.epoch.as_ref(), Some(&a)), @@ -593,3 +596,121 @@ async fn a_more_specific_source_cannot_fill_a_held_covering_track() { assert_eq!(read(&mut subscription).await, "old:1"); } } + +/// A worker claiming `pool` through the public API: each request is prepared under a +/// fresh epoch and published at its exact path, and `outputs[path]` holds the latest. +struct Pool { + _claim: Rc, + outputs: Rc>>, + answered: Rc>, +} + +impl Pool { + fn new(origin: &origin::Producer) -> Self { + let claim = Rc::new(origin.dynamic("pool").unwrap()); + let outputs = Rc::new(RefCell::new(std::collections::HashMap::new())); + let answered = Rc::new(RefCell::new(0)); + let (handler, served, count) = (claim.clone(), outputs.clone(), answered.clone()); + drop(moq_clock::sim::spawn(async move { + while let Ok(request) = handler.requested_broadcast().await { + let path = request.path().to_string(); + let prepared = request.prepare(Epoch::mint()).unwrap(); + let track = prepared.broadcast().create_track("video", timed()).unwrap(); + let output = prepared.publish().unwrap(); + served.borrow_mut().insert(path, (output, track)); + *count.borrow_mut() += 1; + } + })); + Self { + _claim: claim, + outputs, + answered, + } + } + + fn write(&self, path: &str, tag: &str) { + write(&self.outputs.borrow()[path].1, tag); + } + + /// End the output at `path`, as a worker does when it restarts that job. + fn close(&self, path: &str) { + self.outputs.borrow()[path].0.close(); + } +} + +/// Wake the worker for `path` through the claim, then subscribe through the exact route +/// it published. A relay resolves a path under the claim optimistically, and the first +/// subscription through it is reset once the exact route arrives: the cold-start reset +/// accepted until announce takeover lands. +async fn claimed(origin: &origin::Producer, path: &str) -> (broadcast::Consumer, track::Subscriber) { + let cold = origin.consume().request_broadcast(path, None).await.unwrap(); + drop(cold.track("video").unwrap().subscribe(None).await); + settle().await; + subscribe(origin, path).await +} + +/// `W -> R -> E`, where worker `W` claims `pool` and restarts the output at `pool/p` +/// within the cache window. A returning reader at the edge gets the new output from its +/// first group, never a group cached from the old one, while `pool/q` keeps its reader. +async fn claim_restart(version: &str) { + let version: Version = version.parse().unwrap(); + let worker = produce_origin(1); + let relay = produce_origin(2); + let edge = produce_origin(3); + let _upstream = link(version, &worker, &relay).await; + let _downstream = link(version, &relay, &edge).await; + let pool = Pool::new(&worker); + settle().await; + + let (_sibling, mut sibling) = claimed(&edge, "pool/q").await; + pool.write("pool/q", "q:0"); + assert_eq!(read(&mut sibling).await, "q:0", "{version}"); + + let (old, mut first) = claimed(&edge, "pool/p").await; + for group in 0..3 { + pool.write("pool/p", &format!("old:{group}")); + assert_eq!(read(&mut first).await, format!("old:{group}"), "{version}"); + } + drop(first); + pool.close("pool/p"); + settle().await; + + let (fresh, mut returning) = claimed(&edge, "pool/p").await; + assert!(!fresh.is_clone(&old), "{version}: joined the old output"); + if version == "moq-lite-07-wip".parse().unwrap() { + assert!(fresh.info().epoch.is_some(), "{version}: resolved through the claim"); + assert_ne!(fresh.info().epoch, old.info().epoch, "{version}: reused the old epoch"); + } + assert_eq!(*pool.answered.borrow(), 3, "{version}: the worker was not asked again"); + pool.write("pool/p", "new:0"); + assert_eq!(read(&mut returning).await, "new:0", "{version}"); + + pool.write("pool/q", "q:1"); + assert_eq!( + read(&mut sibling).await, + "q:1", + "{version}: the sibling lost its reader" + ); +} + +macro_rules! claim_restart_tests { + ($($name:ident: $version:literal,)*) => { + $( + #[moq_clock::test] + async fn $name() { + moq_clock::timeout(TEST_TIMEOUT, claim_restart($version)) + .await + .expect("timed out"); + } + )* + }; +} + +claim_restart_tests! { + claim_restart_lite05: "moq-lite-05", + claim_restart_lite06: "moq-lite-06", + claim_restart_lite07: "moq-lite-07-wip", + claim_restart_ietf14: "moq-transport-14", + claim_restart_ietf16: "moq-transport-16", + claim_restart_ietf22: "moq-transport-22", +} diff --git a/rs/moq-net/tests/loom.rs b/rs/moq-net/tests/loom.rs index 5623ac5b4f6..df661303c7f 100644 --- a/rs/moq-net/tests/loom.rs +++ b/rs/moq-net/tests/loom.rs @@ -511,6 +511,43 @@ fn a_request_never_joins_a_retiring_front() { }); } +/// A claim answer published while its claim retracts on another thread. The answer +/// either lands before the retraction, and stays announced, or is refused without +/// ever being announced. Announcing it and withdrawing it again shows up here as a +/// route seen mid-race on an answer that was refused. +#[test] +fn a_refused_answer_is_never_announced() { + model(|| { + let (producer, mut driver) = origin::Producer::new(origin::Config::new(Hop::new(1).unwrap())); + let claim = producer.dynamic("room").unwrap(); + let pending = producer.consume().request_broadcast("room/alice", None); + driver + .poll(moq_net::time::Instant::now(), &kio::Waiter::noop()) + .unwrap(); + let prepared = block_on(claim.requested_broadcast()) + .expect("requested") + .prepare(moq_net::Epoch::mint()) + .expect("prepare"); + let answer = prepared.broadcast().clone(); + + let watch = answer.clone(); + let releaser = thread::spawn(move || { + drop(claim); + watch.route().is_some() + }); + let published = prepared.publish(); + let seen = releaser.join().unwrap(); + + assert_eq!( + published.is_ok(), + answer.route().is_some(), + "the route outlived its answer" + ); + assert!(!seen || published.is_ok(), "a refused answer was announced"); + drop(pending); + }); +} + /// Read a track whose source already aborted with `read`, racing the front ending it. /// A reader that saw no end, then found one set when it went to park, parked on nothing /// and never woke, which shows up here as a deadlock. `read` says whether the refusal diff --git a/rs/moq-rtc/src/egress.rs b/rs/moq-rtc/src/egress.rs index 83f455f1d4b..80ab1130953 100644 --- a/rs/moq-rtc/src/egress.rs +++ b/rs/moq-rtc/src/egress.rs @@ -1126,7 +1126,7 @@ mod tests { assert_eq!(written(&mut writes).await.as_ref(), b"low-0"); // The better rendition lives in a broadcast whose request is never answered. - let _handler = origin.dynamic("missing", Default::default()).unwrap(); + let _handler = origin.dynamic("missing").unwrap(); let mut config = VideoConfig::new(VideoCodec::VP8); config.container = hang::catalog::Container::Legacy; config.coded_width = Some(1920); diff --git a/swift/MIGRATE.md b/swift/MIGRATE.md index 2f6ffc91e7d..c7b9604ed0d 100644 --- a/swift/MIGRATE.md +++ b/swift/MIGRATE.md @@ -4,6 +4,11 @@ How to update your code for each breaking change, newest first. ## Unreleased +### A claim answers by publishing (#5678) + +`OriginProducer.dynamic(prefix:)` takes no route, and `OriginDynamic.update(route:)` is gone. +Replace `request.accept(broadcast:)` with `let prepared = try request.prepare(epoch: mintEpoch())`, fill `prepared.broadcast`, then `try prepared.publish()`, which announces it at the exact path under that epoch and returns its producer. + ### Anchors can name a time (#6074) `Subscription.Anchor` gains `.time(timestampUs:)`, so exhaustive switches need a case for it. diff --git a/swift/Sources/Moq/Origin.swift b/swift/Sources/Moq/Origin.swift index 081e2406f67..4b5c0f0cda3 100644 --- a/swift/Sources/Moq/Origin.swift +++ b/swift/Sources/Moq/Origin.swift @@ -26,8 +26,8 @@ public final class OriginProducer: Sendable { /// A service that only serves some of them rejects the rest as they are /// requested. Create, `dynamic` if tracks are served on demand, populate, /// then `BroadcastProducer.announce`. - public func dynamic(prefix: String, route: Route = Route()) throws -> OriginDynamic { - OriginDynamic(try ffi.dynamic(prefix: prefix, route: route)) + public func dynamic(prefix: String) throws -> OriginDynamic { + OriginDynamic(try ffi.dynamic(prefix: prefix)) } /// Create a broadcast at `path`, returning the producer that feeds it. @@ -54,9 +54,9 @@ public final class BroadcastRequest: Sendable { get throws { try ffi.path() } } - /// Serve the request with an unannounced broadcast. - public func accept(broadcast: BroadcastProducer) throws { - try ffi.accept(broadcast: broadcast.ffi) + /// Start an answer under a new epoch, hidden until published. + public func prepare(epoch: String) throws -> BroadcastPrepared { + BroadcastPrepared(try ffi.prepare(epoch: epoch)) } /// Reject the request with an application error code. @@ -65,6 +65,25 @@ public final class BroadcastRequest: Sendable { } } +/// A claim answer being filled before its exact route is announced. +public final class BroadcastPrepared: Sendable { + let ffi: MoqBroadcastPrepared + + init(_ ffi: MoqBroadcastPrepared) { + self.ffi = ffi + } + + /// The unannounced broadcast to fill before publishing; only `publish` announces it. + public var broadcast: BroadcastProducer { + BroadcastProducer(ffi.broadcast()) + } + + /// Announce the filled broadcast and resolve every waiting requester. + public func publish() throws -> BroadcastProducer { + BroadcastProducer(try ffi.publish()) + } +} + /// A stream of broadcasts requested by consumers. Iterate directly: /// `for try await request in dynamic { ... }`. Hold this while missing /// broadcasts should be served; cancelling the consuming task stops serving. @@ -83,11 +102,6 @@ public final class OriginDynamic: AsyncSequence, Sendable { BroadcastRequest(try await ffi.requestedBroadcast()) } - /// Re-price the route in place: replace its hops and costs. - public func update(route: Route) throws { - try ffi.update(route: route) - } - /// Cancel all current and future `requestedBroadcast()` calls and retract /// the route. public func cancel() { diff --git a/swift/Tests/MoqTests/SmokeTests.swift b/swift/Tests/MoqTests/SmokeTests.swift index d34f06f0f51..fcf8aaddf8d 100644 --- a/swift/Tests/MoqTests/SmokeTests.swift +++ b/swift/Tests/MoqTests/SmokeTests.swift @@ -199,9 +199,9 @@ final class SmokeTests: XCTestCase { } let request = try await dynamic.requestedBroadcast() XCTAssertEqual(try request.path, "live/cam") - let served = try BroadcastProducer() - try request.accept(broadcast: served) + let served = try request.prepare(epoch: mintEpoch()).publish() _ = try await pending.value + try served.close() dynamic.cancel() }