diff --git a/.taplo.toml b/.taplo.toml index 205a07900b8..a1834cfa308 100644 --- a/.taplo.toml +++ b/.taplo.toml @@ -1,5 +1,5 @@ -# Skip vendored, build, and scratch trees so `taplo format` doesn't recurse into them. -exclude = ["**/node_modules/**", "**/target/**", "**/dist/**", "**/.venv/**", "**/.direnv/**", "**/.tmp/**"] +# Skip vendored, build, and scratch trees (c/moq/build links into target/) so `taplo format` doesn't recurse into them. +exclude = ["**/node_modules/**", "**/target/**", "c/moq/build/**", "**/dist/**", "**/.venv/**", "**/.direnv/**", "**/.tmp/**"] # Match the existing repo style (4-space indent on Cargo.toml, lines up # to ~120 chars) so the initial format pass stays minimal. diff --git a/dart/moq/lib/src/aliases.dart b/dart/moq/lib/src/aliases.dart index 58085dabb41..f470fcd4938 100644 --- a/dart/moq/lib/src/aliases.dart +++ b/dart/moq/lib/src/aliases.dart @@ -144,6 +144,9 @@ typedef Anchor = MoqAnchor; /// Which pending group the publisher sends first. typedef Order = MoqOrder; +/// A location within a track: a group sequence and a frame index in it. +typedef Position = MoqPosition; + /// Options for fetching one past group by sequence. typedef FetchGroupOptions = MoqFetchGroupOptions; diff --git a/dart/moq_ffi/lib/src/moq.dart b/dart/moq_ffi/lib/src/moq.dart index 4c0bd31cb45..9e35b5dfde4 100644 --- a/dart/moq_ffi/lib/src/moq.dart +++ b/dart/moq_ffi/lib/src/moq.dart @@ -8,7 +8,9 @@ import "dart:ffi"; import "dart:io" show Platform, File, Directory; import "dart:isolate"; import "dart:typed_data"; + import "package:ffi/ffi.dart"; + import "uniffi_runtime.dart"; export "uniffi_runtime.dart"; @@ -2860,6 +2862,65 @@ class FfiConverterMoqRoute { } } +class MoqPosition { + final int group; + final int frame; + MoqPosition({required this.group, required this.frame}); +} + +class FfiConverterMoqPosition { + static MoqPosition lift(RustBuffer buf) { + return FfiConverterMoqPosition.read(buf.asUint8List()).value; + } + + static LiftRetVal read(Uint8List buf) { + int new_offset = buf.offsetInBytes; + final group_lifted = FfiConverterUInt64.read( + Uint8List.view(buf.buffer, new_offset), + ); + final group = group_lifted.value; + new_offset += group_lifted.bytesRead; + final frame_lifted = FfiConverterUInt64.read( + Uint8List.view(buf.buffer, new_offset), + ); + final frame = frame_lifted.value; + new_offset += frame_lifted.bytesRead; + return LiftRetVal( + MoqPosition(group: group, frame: frame), + new_offset - buf.offsetInBytes, + ); + } + + static RustBuffer lower(MoqPosition value) { + final total_length = + FfiConverterUInt64.allocationSize(value.group) + + FfiConverterUInt64.allocationSize(value.frame) + + 0; + final buf = Uint8List(total_length); + write(value, buf); + return toRustBuffer(buf); + } + + static int write(MoqPosition value, Uint8List buf) { + int new_offset = buf.offsetInBytes; + new_offset += FfiConverterUInt64.write( + value.group, + Uint8List.view(buf.buffer, new_offset), + ); + new_offset += FfiConverterUInt64.write( + value.frame, + Uint8List.view(buf.buffer, new_offset), + ); + return new_offset - buf.offsetInBytes; + } + + static int allocationSize(MoqPosition value) { + return FfiConverterUInt64.allocationSize(value.group) + + FfiConverterUInt64.allocationSize(value.frame) + + 0; + } +} + class MoqTrackInfo { final int priority; final Duration? maxAge; @@ -9379,6 +9440,7 @@ class FfiConverterMoqReservation { } abstract class MoqBroadcastConsumerInterface { + UniffiRustFuture closed(); UniffiRustFuture fetchGroup({ required String name, required int sequence, @@ -9428,6 +9490,20 @@ class MoqBroadcastConsumer implements MoqBroadcastConsumerInterface { ); } + UniffiRustFuture closed() { + return uniffiRustCallAsync( + () => uniffi_moq_ffi_fn_method_moqbroadcastconsumer_closed( + uniffiClonePointer(), + ), + ffi_moq_ffi_rust_future_poll_void, + ffi_moq_ffi_rust_future_complete_void, + ffi_moq_ffi_rust_future_cancel_void, + ffi_moq_ffi_rust_future_free_void, + (_) {}, + moqExceptionErrorHandler, + ); + } + UniffiRustFuture fetchGroup({ required String name, required int sequence, @@ -12823,6 +12899,8 @@ abstract class MoqTrackProducerInterface { MoqTrackDemand demand(); void finish(); void finishAt({required int finalSequence}); + void insertDatagram({required int sequence, required MoqFrame frame}); + MoqPosition? largest(); MoqTrackRequests requests(); void writeFrame({required MoqFrame frame}); } @@ -12945,6 +13023,28 @@ class MoqTrackProducer implements MoqTrackProducerInterface { }, moqExceptionErrorHandler); } + void insertDatagram({required int sequence, required MoqFrame frame}) { + return rustCall((status) { + uniffi_moq_ffi_fn_method_moqtrackproducer_insert_datagram( + uniffiClonePointer(), + FfiConverterUInt64.lower(sequence), + FfiConverterMoqFrame.lower(frame), + status, + ); + }, moqExceptionErrorHandler); + } + + MoqPosition? largest() { + return rustCallWithLifter( + (status) => uniffi_moq_ffi_fn_method_moqtrackproducer_largest( + uniffiClonePointer(), + status, + ), + FfiConverterOptionalMoqPosition.lift, + moqExceptionErrorHandler, + ); + } + MoqTrackRequests requests() { return rustCallWithLifter( (status) => uniffi_moq_ffi_fn_method_moqtrackproducer_requests( @@ -15806,6 +15906,53 @@ class FfiConverterOptionalMoqOriginProducer { } } +class FfiConverterOptionalMoqPosition { + static MoqPosition? lift(RustBuffer buf) { + return FfiConverterOptionalMoqPosition.read(buf.asUint8List()).value; + } + + static LiftRetVal read(Uint8List buf) { + if (ByteData.view(buf.buffer, buf.offsetInBytes).getInt8(0) == 0) { + return LiftRetVal(null, 1); + } + final result = FfiConverterMoqPosition.read( + Uint8List.view(buf.buffer, buf.offsetInBytes + 1), + ); + return LiftRetVal(result.value, result.bytesRead + 1); + } + + static int allocationSize([MoqPosition? value]) { + if (value == null) { + return 1; + } + return FfiConverterMoqPosition.allocationSize(value) + 1; + } + + static RustBuffer lower(MoqPosition? value) { + if (value == null) { + return toRustBuffer(Uint8List.fromList([0])); + } + final buf = Uint8List( + FfiConverterOptionalMoqPosition.allocationSize(value), + ); + FfiConverterOptionalMoqPosition.write(value, buf); + return toRustBuffer(buf); + } + + static int write(MoqPosition? value, Uint8List buf) { + if (value == null) { + buf[0] = 0; + return 1; + } + buf[0] = 1; + return FfiConverterMoqPosition.write( + value, + Uint8List.view(buf.buffer, buf.offsetInBytes + 1), + ) + + 1; + } +} + class FfiConverterOptionalMoqRequest { static MoqRequest? lift(RustBuffer buf) { return FfiConverterOptionalMoqRequest.read(buf.asUint8List()).value; @@ -17321,6 +17468,11 @@ external void uniffi_moq_ffi_fn_free_moqbroadcastconsumer( Pointer uniffiStatus, ); +@Native Function(Pointer)>(assetId: _uniffiAssetId) +external Pointer uniffi_moq_ffi_fn_method_moqbroadcastconsumer_closed( + Pointer ptr, +); + @Native Function(Pointer, RustBuffer, Uint64, RustBuffer)>( assetId: _uniffiAssetId, ) @@ -18876,6 +19028,24 @@ external void uniffi_moq_ffi_fn_method_moqtrackproducer_finish_at( Pointer uniffiStatus, ); +@Native< + Void Function(Pointer, Uint64, RustBuffer, Pointer) +>(assetId: _uniffiAssetId) +external void uniffi_moq_ffi_fn_method_moqtrackproducer_insert_datagram( + Pointer ptr, + int sequence, + RustBuffer frame, + Pointer uniffiStatus, +); + +@Native, Pointer)>( + assetId: _uniffiAssetId, +) +external RustBuffer uniffi_moq_ffi_fn_method_moqtrackproducer_largest( + Pointer ptr, + Pointer uniffiStatus, +); + @Native Function(Pointer, Pointer)>( assetId: _uniffiAssetId, ) @@ -19974,6 +20144,9 @@ external int uniffi_moq_ffi_checksum_method_moqreservation_rate(); @Native(assetId: _uniffiAssetId) external int uniffi_moq_ffi_checksum_method_moqreservation_update(); +@Native(assetId: _uniffiAssetId) +external int uniffi_moq_ffi_checksum_method_moqbroadcastconsumer_closed(); + @Native(assetId: _uniffiAssetId) external int uniffi_moq_ffi_checksum_method_moqbroadcastconsumer_fetch_group(); @@ -20318,6 +20491,12 @@ external int uniffi_moq_ffi_checksum_method_moqtrackproducer_finish(); @Native(assetId: _uniffiAssetId) external int uniffi_moq_ffi_checksum_method_moqtrackproducer_finish_at(); +@Native(assetId: _uniffiAssetId) +external int uniffi_moq_ffi_checksum_method_moqtrackproducer_insert_datagram(); + +@Native(assetId: _uniffiAssetId) +external int uniffi_moq_ffi_checksum_method_moqtrackproducer_largest(); + @Native(assetId: _uniffiAssetId) external int uniffi_moq_ffi_checksum_method_moqtrackproducer_requests(); @@ -20670,6 +20849,9 @@ void _checkApiChecksums() { if (uniffi_moq_ffi_checksum_method_moqreservation_update() != 9626) { throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); } + if (uniffi_moq_ffi_checksum_method_moqbroadcastconsumer_closed() != 12232) { + throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); + } if (uniffi_moq_ffi_checksum_method_moqbroadcastconsumer_fetch_group() != 18633) { throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); @@ -21030,6 +21212,13 @@ void _checkApiChecksums() { if (uniffi_moq_ffi_checksum_method_moqtrackproducer_finish_at() != 24581) { throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); } + if (uniffi_moq_ffi_checksum_method_moqtrackproducer_insert_datagram() != + 29400) { + throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); + } + if (uniffi_moq_ffi_checksum_method_moqtrackproducer_largest() != 3968) { + throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); + } if (uniffi_moq_ffi_checksum_method_moqtrackproducer_requests() != 60252) { throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); } diff --git a/go/wrapper/README.md b/go/wrapper/README.md index 2cd23e980d3..c2a801b9171 100644 --- a/go/wrapper/README.md +++ b/go/wrapper/README.md @@ -150,7 +150,8 @@ See the package doc for details. ## Raw datagrams Raw tracks support best-effort datagrams alongside groups: `TrackProducer.AppendDatagram` -sends one `Frame` and returns its sequence number, while `TrackConsumer.RecvDatagram` +sends one `Frame` and returns its sequence number (`InsertDatagram` takes the caller's +own sequence instead), while `TrackConsumer.RecvDatagram` and `TrackConsumer.Datagrams` receive them in arrival order. Payloads are capped at 1200 bytes. Datagram delivery requires a datagram-capable transport and lite-05 or newer moq-lite, or moq-transport; pre-lite-05, WebSocket, and TCP paths do not diff --git a/go/wrapper/moq_test.go b/go/wrapper/moq_test.go index 27b57c91a92..ee4328d9ff2 100644 --- a/go/wrapper/moq_test.go +++ b/go/wrapper/moq_test.go @@ -530,6 +530,70 @@ func testDecodeVideoFrame(t *testing.T, surface bool) { } } +func TestInsertDatagramAndLargest(t *testing.T) { + ctx, cancel := context.WithTimeout(context.Background(), testTimeout) + defer cancel() + + broadcast, err := moq.NewBroadcastProducer() + if err != nil { + t.Fatal(err) + } + track, err := broadcast.PublishTrack("events", timedInfo()) + if err != nil { + t.Fatal(err) + } + consumer, err := track.Consume(nil) + if err != nil { + t.Fatal(err) + } + if largest, err := track.Largest(); err != nil || largest != nil { + t.Fatalf("empty track: largest %v, err %v", largest, err) + } + + if err := track.InsertDatagram(7, moq.Frame{Payload: []byte("seven"), Timestamp: ts(0)}); err != nil { + t.Fatal(err) + } + datagram, err := consumer.RecvDatagram(ctx) + if err != nil { + t.Fatal(err) + } + if datagram == nil || datagram.Sequence != 7 || string(datagram.Payload) != "seven" { + t.Fatalf("got datagram %+v", datagram) + } + largest, err := track.Largest() + if err != nil { + t.Fatal(err) + } + if largest == nil || *largest != (moq.Position{Group: 7, Frame: 0}) { + t.Fatalf("largest %+v", largest) + } + if next, err := track.AppendDatagram(moq.Frame{Payload: []byte("next"), Timestamp: ts(0)}); err != nil || next != 8 { + t.Fatalf("appended at %d, err %v", next, err) + } +} + +func TestBroadcastConsumerClosed(t *testing.T) { + ctx, cancel := context.WithTimeout(context.Background(), testTimeout) + defer cancel() + + broadcast, err := moq.NewBroadcastProducer() + if err != nil { + t.Fatal(err) + } + consumer, err := broadcast.Consume() + if err != nil { + t.Fatal(err) + } + closed := make(chan error, 1) + go func() { closed <- consumer.Closed(ctx) }() + if err := broadcast.Close(); err != nil { + t.Fatal(err) + } + if err := <-closed; err != nil { + t.Fatal(err) + } +} + func TestFetchGroupAndServeDynamicMiss(t *testing.T) { ctx, cancel := context.WithTimeout(context.Background(), testTimeout) defer cancel() diff --git a/go/wrapper/publish.go b/go/wrapper/publish.go index d8d6ea6c078..8ff686eb816 100644 --- a/go/wrapper/publish.go +++ b/go/wrapper/publish.go @@ -223,6 +223,22 @@ func (t *TrackProducer) AppendDatagram(frame Frame) (uint64, error) { return t.inner.AppendDatagram(f) } +// InsertDatagram sends frame as a best-effort datagram at an explicit sequence, for a +// caller that allocates its own. AppendDatagram continues after the largest one. +func (t *TrackProducer) InsertDatagram(sequence uint64, frame Frame) error { + f, err := frame.ffi() + if err != nil { + return err + } + return t.inner.InsertDatagram(sequence, f) +} + +// Largest reports the newest group or datagram written, at its newest frame, or nil +// before any. +func (t *TrackProducer) Largest() (*Position, error) { + return t.inner.Largest() +} + // Abort closes the track with an application error code. func (t *TrackProducer) Abort(errorCode uint16) error { return t.inner.Abort(errorCode) diff --git a/go/wrapper/subscribe.go b/go/wrapper/subscribe.go index e0f661387c9..1b4ed49485b 100644 --- a/go/wrapper/subscribe.go +++ b/go/wrapper/subscribe.go @@ -13,6 +13,12 @@ type BroadcastConsumer struct { inner *ffi.MoqBroadcastConsumer } +// Closed blocks until the broadcast ends: its publisher closed it, or every producer +// left. Cancelling ctx stops waiting. +func (b *BroadcastConsumer) Closed(ctx context.Context) error { + return b.inner.Closed(ctx) +} + // SubscribeTrack subscribes to a track, receiving arbitrary byte payloads. // subscription tunes delivery priority, group range, and staleness; pass nil for defaults. func (b *BroadcastConsumer) SubscribeTrack( diff --git a/go/wrapper/types.go b/go/wrapper/types.go index 0676727a044..c1ac1622af5 100644 --- a/go/wrapper/types.go +++ b/go/wrapper/types.go @@ -67,6 +67,8 @@ type ( AnchorTime = ffi.MoqAnchorTime // Order is which of a subscription's pending groups the publisher sends first. Order = ffi.MoqOrder + // Position is a location within a track: a group sequence and a frame index in it. + Position = ffi.MoqPosition // VideoDecoderOutput configures what a video.Consumer delivers: an optional resize, a max delay, and whether frames keep the decoder's surface (macOS only; refused elsewhere). VideoDecoderOutput = ffi.MoqVideoDecoderOutput // VideoSurface is a decoded frame's platform surface, from VideoDecodedFrame.Surface: VideoSurfacePixelBuffer on macOS and iOS. diff --git a/kt/README.md b/kt/README.md index f01efff502b..c43edd84660 100644 --- a/kt/README.md +++ b/kt/README.md @@ -60,7 +60,7 @@ The `dev.moq` package is intentionally thin: Kotlin has extension functions, so - **Fetched media**: `dev.moq.media.GroupConsumer.fetch(...).frames()` streams the decoded frames of one retained group, then completes. `dev.moq.media.GroupConsumer(group, container)` decodes a raw group instead, such as one from `recvGroup()` for arrival-order reads. - **Timestamp extensions** (`Durations.kt`): the FFI carries media timestamps as microsecond integers, so `frame.timestamp` and its siblings read back as a `kotlin.time.Duration`. Durations such as `stats.rtt` are already `java.time.Duration`. - **`logLevel(...)`**: configures native Rust tracing without importing the raw bindings package. -- **Raw datagrams**: `TrackProducer.appendDatagram(Frame(payload, timestampUs))` sends one best-effort frame and returns its sequence; `TrackConsumer.recvDatagram()` and `datagrams()` receive them. Payloads are capped at 1200 bytes, require a datagram-capable transport plus lite-05 or newer moq-lite or moq-transport, and have no stream fallback. +- **Raw datagrams**: `TrackProducer.appendDatagram(Frame(payload, timestampUs))` sends one best-effort frame and returns its sequence, and `insertDatagram(sequence, frame)` takes the caller's own; `TrackConsumer.recvDatagram()` and `datagrams()` receive them. Payloads are capped at 1200 bytes, require a datagram-capable transport plus lite-05 or newer moq-lite or moq-transport, and have no stream fallback. - **`MoqException.isShutdown`** (`Errors.kt`): true for the graceful `Cancelled`/`Closed` cases. ## Versioning diff --git a/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/Aliases.kt b/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/Aliases.kt index 65a254f477a..c0a820e6beb 100644 --- a/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/Aliases.kt +++ b/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/Aliases.kt @@ -127,6 +127,8 @@ typealias AnchorRelative = uniffi.moq.MoqAnchor.Relative typealias AnchorTime = uniffi.moq.MoqAnchor.Time /** Which pending group the publisher sends first: `ASCENDING` or `DESCENDING`. */ typealias Order = uniffi.moq.MoqOrder +/** A location within a track: a group sequence and a frame index in it. */ +typealias Position = uniffi.moq.MoqPosition /** Options for fetching one past group by sequence. */ typealias FetchGroupOptions = uniffi.moq.MoqFetchGroupOptions /** Delivery settings for a raw track: priority, ordering, latency budget, and timescale. */ diff --git a/py/moq-rs/README.md b/py/moq-rs/README.md index f2e5aa39b7c..dfe833427ae 100644 --- a/py/moq-rs/README.md +++ b/py/moq-rs/README.md @@ -183,6 +183,8 @@ client = moq.Client( - `.finish_at(final_sequence)` declares the first group that will never be produced while leaving lower groups writable. - `.abort(error_code)` terminates the track or group with an application error. - `.append_datagram(payload, timestamp=None) -> sequence` (`TrackProducer`) sends a best-effort datagram. Payloads are capped at 1200 bytes and there is no stream fallback. + - `.insert_datagram(sequence, payload, timestamp=None)` (`TrackProducer`) sends one at the caller's own sequence. + - `.largest() -> Position | None` (`TrackProducer`) reports the newest group or datagram written, at its newest frame. ### Media diff --git a/py/moq-rs/moq/__init__.py b/py/moq-rs/moq/__init__.py index 8f5a72b486e..48a9e580845 100644 --- a/py/moq-rs/moq/__init__.py +++ b/py/moq-rs/moq/__init__.py @@ -64,6 +64,7 @@ Frame, Grant, Order, + Position, ProtocolError, ProtocolKind, QuicConfig, @@ -125,6 +126,7 @@ "OriginRequests", "OriginProducer", "Order", + "Position", "Publication", "Range", "Request", diff --git a/py/moq-rs/moq/publish.py b/py/moq-rs/moq/publish.py index 46dd8809f42..cf7bb38c218 100644 --- a/py/moq-rs/moq/publish.py +++ b/py/moq-rs/moq/publish.py @@ -21,6 +21,7 @@ from ._stream import _Stream from .types import ( Frame, + Position, Subscription, TrackInfo, ) @@ -128,6 +129,18 @@ def append_datagram(self, payload: bytes, timestamp: timedelta | None = None) -> """ return self._inner.append_datagram(Frame(payload, timestamp)._ffi()) + def insert_datagram(self, sequence: int, payload: bytes, timestamp: timedelta | None = None) -> None: + """Send a best-effort datagram at an explicit sequence number. + + For a caller that allocates its own sequences; :meth:`append_datagram` + continues after the largest one. + """ + self._inner.insert_datagram(sequence, Frame(payload, timestamp)._ffi()) + + def largest(self) -> Position | None: + """The newest group or datagram written, at its newest frame; ``None`` before any.""" + return self._inner.largest() + def consume(self, subscription: Subscription | None = None) -> TrackConsumer: """Create a consumer that reads directly from this producer's track. diff --git a/py/moq-rs/moq/subscribe.py b/py/moq-rs/moq/subscribe.py index b13089cad24..9736b9083ff 100644 --- a/py/moq-rs/moq/subscribe.py +++ b/py/moq-rs/moq/subscribe.py @@ -151,6 +151,10 @@ class BroadcastConsumer: def __init__(self, inner: MoqBroadcastConsumer) -> None: self._inner = inner + async def closed(self) -> None: + """Wait until the broadcast ends: its publisher closed it, or every producer left.""" + await self._inner.closed() + async def subscribe_track(self, name: str, subscription: Subscription | None = None) -> TrackConsumer: """Subscribe to a track and receive arbitrary byte payloads. diff --git a/py/moq-rs/moq/types.py b/py/moq-rs/moq/types.py index d65eaa159cf..2615ec6453a 100644 --- a/py/moq-rs/moq/types.py +++ b/py/moq-rs/moq/types.py @@ -33,6 +33,9 @@ from moq_ffi import ( MoqOrder as Order, ) +from moq_ffi import ( + MoqPosition as Position, +) from moq_ffi import ( MoqProtocolError as ProtocolError, ) @@ -97,6 +100,7 @@ "FetchGroupOptions", "Grant", "Order", + "Position", "ProtocolError", "ProtocolKind", "QuicConfig", diff --git a/py/moq-rs/tests/test_local.py b/py/moq-rs/tests/test_local.py index 1308772d810..aa28400a17c 100644 --- a/py/moq-rs/tests/test_local.py +++ b/py/moq-rs/tests/test_local.py @@ -118,6 +118,29 @@ async def reject(): await task +async def test_insert_datagram_keeps_its_sequence_and_largest_follows(): + broadcast = moq.BroadcastProducer() + track = broadcast.publish_track("events") + consumer = track.consume() + assert track.largest() is None + + track.insert_datagram(7, b"seven") + datagram = await asyncio.wait_for(consumer.recv_datagram(), 5) + assert datagram is not None + assert (datagram.sequence, datagram.payload) == (7, b"seven") + assert track.largest() == moq.Position(group=7, frame=0) + assert track.append_datagram(b"next") == 8 + + +async def test_broadcast_consumer_closed_resolves_on_close(): + broadcast = moq.BroadcastProducer() + closed = asyncio.create_task(broadcast.consume().closed()) + await asyncio.sleep(0.01) + assert not closed.done() + broadcast.close() + await asyncio.wait_for(closed, 5) + + def test_protocol_error_helper_covers_known_app_and_unknown(): cases = [ (moq.ErrorScope.SESSION, 0x2, moq.ProtocolKind.UNAUTHORIZED, True), diff --git a/quest/m2/rs2ts/wasm-bindings.md b/quest/m2/rs2ts/wasm-bindings.md index d56a8b766a9..76d1f53ad00 100644 --- a/quest/m2/rs2ts/wasm-bindings.md +++ b/quest/m2/rs2ts/wasm-bindings.md @@ -10,8 +10,12 @@ this quest does not switch the public package's default implementation. ## Plan Decided 2026-10-12: reuse the existing Rust implementation, including async. -Inventory `@moq/net` and its in-tree consumers against the bindings first. -Preserve frame metadata as well as bytes, exact sequence/id values, ownership, +The inventory of `@moq/net`'s in-tree consumers against the bindings is in +[`test/wasm/README.md`](/test/wasm/README.md#parity-with-moqnet); close its rows, +updating the table as each lands. The connection rows (reconnect with backoff, +WebSocket fallback, `probe`) are the largest; the WebSocket fallback needs qmux to +build on wasm32 (its `Transport` traits require `Send` and it spawns on tokio) and a +browser `WebSocket` transport beneath it. Preserve frame metadata as well as bytes, exact sequence/id values, ownership, close/error behavior, cancellation, and backpressure. Validate supported versions and transports with the browser fixtures and `just test interop --all`. Wire new tests into CI, at least nightly. diff --git a/rs/moq-ffi/CHANGELOG.md b/rs/moq-ffi/CHANGELOG.md index 89a1c5367a4..309ba71dcad 100644 --- a/rs/moq-ffi/CHANGELOG.md +++ b/rs/moq-ffi/CHANGELOG.md @@ -15,6 +15,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 `MoqAudioConsumer::delay_us()` reports it, fixed or estimated from arrivals. - `MoqAudio::jitter_us` carries the catalog's advertised jitter, which floors the estimated audio playout delay. +- `MoqTrackProducer::insert_datagram` sends a datagram at the caller's sequence, + and `MoqTrackProducer::largest` reports the newest `MoqPosition` written. +- `MoqBroadcastConsumer::closed` resolves once the broadcast ends. ### Changed diff --git a/rs/moq-ffi/README.md b/rs/moq-ffi/README.md index cfb759e7af5..3e42822d473 100644 --- a/rs/moq-ffi/README.md +++ b/rs/moq-ffi/README.md @@ -39,6 +39,29 @@ uniffi_bindgen_dart --library target/release/libmoq_ffi.{dylib,so} --out-dir out The Dart generator is pinned in `flake.nix`; run `nix develop --command just dart generate` to regenerate the committed package bindings. +## Browser + +moq-ffi also builds for `wasm32-unknown-unknown`, where +[ubrn](https://github.com/jhugman/uniffi-bindgen-react-native)'s `wasm2` player binds it +to TypeScript. It is the candidate Rust backend for `@moq/net`, not a published package. +Publishing and consumption over WebTransport work for every moq-lite and moq-transport +version; the codecs, the server, and logging are native-only. + +The browser owns the socket and the trust store, so `MoqClientConfig` honors only +`versions`, `tls.fingerprints`, and the origins there, and `MoqClient::new` fails with +`Unsupported` when anything else is set. A session dials once: there is no reconnect and +no WebSocket fallback yet. + +ubrn 0.31 reads UniFFI 0.31 metadata, so for now the TypeScript is generated from a +scratch checkout pinned back to UniFFI 0.31: + +```bash +just test wasm --uniffi # build, then run the browser parity cases against real relays +``` + +[`test/wasm`](../../test/wasm/README.md#generated-bindings) covers the build, the +browser cases, and what `@moq/net` still needs from this surface. + ## Architecture ```text diff --git a/rs/moq-ffi/src/consumer.rs b/rs/moq-ffi/src/consumer.rs index d400a2f86dc..acef58d88a1 100644 --- a/rs/moq-ffi/src/consumer.rs +++ b/rs/moq-ffi/src/consumer.rs @@ -310,6 +310,19 @@ impl MoqBroadcastConsumer { })) } + /// Wait until the broadcast ends: its publisher closed it, or every producer of it left. + /// + /// Resolves rather than erroring when it ends, since an ended broadcast is not a failure. + /// Errors only when the session driving it fails first. Cancel the call to stop waiting. + pub async fn closed(&self) -> Result<(), MoqError> { + self.driver + .watch(async { + self.inner.closed().await; + Ok(()) + }) + .await + } + /// Subscribe to a track by name, the same pattern as moq-boy's command/status tracks. /// /// Frames are returned as plain byte payloads with no codec or container parsing. diff --git a/rs/moq-ffi/src/producer.rs b/rs/moq-ffi/src/producer.rs index b23af0b35c2..1c3e53f8ece 100644 --- a/rs/moq-ffi/src/producer.rs +++ b/rs/moq-ffi/src/producer.rs @@ -10,6 +10,24 @@ use crate::error::MoqError; use crate::ffi::{Background, Task}; use crate::media::MoqFrame; +/// A location within a track, mirroring [`moq_net::track::Position`]. +#[derive(Clone, Copy, Debug, PartialEq, Eq, uniffi::Record)] +pub struct MoqPosition { + /// The group sequence. + pub group: u64, + /// The frame index within the group, numbered from 0 in write order. + pub frame: u64, +} + +impl From for MoqPosition { + fn from(position: moq_net::track::Position) -> Self { + Self { + group: position.group, + frame: position.frame, + } + } +} + /// Publisher-side track properties, mirroring [`moq_net::track::Info`]. /// /// Construct with the fields you care about; the rest use raw-track defaults @@ -781,6 +799,32 @@ impl MoqTrackProducer { Ok(track.append_datagram(timestamp, frame.payload)?) } + /// Send `frame` as a best-effort datagram at an explicit `sequence`. + /// + /// [`append_datagram`](Self::append_datagram) assigns the next sequence; this is for a + /// caller that allocates its own, such as an encryption layer binding the sequence into + /// its nonce. The same payload, transport, and timedness rules apply, and a sequence at or + /// past a [`finish_at`](Self::finish_at) boundary is refused with `Closed`. + pub fn insert_datagram(&self, sequence: u64, frame: MoqFrame) -> Result<(), MoqError> { + let _guard = crate::ffi::enter(); + let timestamp = frame.timestamp_us.map(moq_net::Timestamp::from_micros).transpose()?; + let mut guard = self.inner.lock().unwrap(); + let track = guard.as_mut().ok_or(MoqError::Closed)?; + Ok(track.insert_datagram(sequence, timestamp, frame.payload)?) + } + + /// The newest content this track holds: its newest group or datagram, at that group's + /// newest frame (0 while it is empty), or null before anything was written. + /// + /// A publisher compares it with [`MoqTrackDemand`]'s wanted group to tell whether a join + /// is already served by a group it wrote. + pub fn largest(&self) -> Result, MoqError> { + let _guard = crate::ffi::enter(); + let guard = self.inner.lock().unwrap(); + let track = guard.as_ref().ok_or(MoqError::Closed)?; + Ok(track.largest().map(MoqPosition::from)) + } + /// Abort this track with an application error code. pub fn abort(&self, error_code: u16) -> Result<(), MoqError> { let _guard = crate::ffi::enter(); diff --git a/rs/moq-ffi/src/test.rs b/rs/moq-ffi/src/test.rs index 61c68657000..8aa1d457e7e 100644 --- a/rs/moq-ffi/src/test.rs +++ b/rs/moq-ffi/src/test.rs @@ -4932,6 +4932,61 @@ where assert_eq!(datagram.payload, b"beep".to_vec()); } +/// `insert_datagram` sends at the caller's sequence, and later appends continue past it. +#[tokio::test] +async fn raw_track_insert_datagram_keeps_its_sequence() { + let (_broadcast, track, consumer) = raw_track(); + + track.insert_datagram(7, datagram_frame(b"seven")).unwrap(); + let datagram = tokio::time::timeout(TIMEOUT, consumer.recv_datagram()) + .await + .expect("timed out waiting for the inserted datagram") + .unwrap() + .expect("expected a datagram"); + assert_eq!(datagram.sequence, 7); + assert_eq!(datagram.payload, b"seven".to_vec()); + assert_eq!(datagram.timestamp_us, Some(1)); + + assert_eq!(track.append_datagram(datagram_frame(b"next")).unwrap(), 8); +} + +/// `largest` follows the newest group and its newest frame. +#[test] +fn raw_track_largest_follows_writes() { + let (_broadcast, track, _consumer) = raw_track(); + assert_eq!(track.largest().unwrap(), None); + + let group = track.create_group(3).unwrap(); + assert_eq!(track.largest().unwrap(), Some(MoqPosition { group: 3, frame: 0 })); + group.write_frame(group_frame(b"one")).unwrap(); + group.write_frame(group_frame(b"two")).unwrap(); + assert_eq!(track.largest().unwrap(), Some(MoqPosition { group: 3, frame: 1 })); + + // An older group never moves it back. + track.create_group(1).unwrap(); + assert_eq!(track.largest().unwrap(), Some(MoqPosition { group: 3, frame: 1 })); +} + +/// A broadcast consumer's `closed` resolves once its producer closes. +#[tokio::test] +async fn broadcast_consumer_closed_resolves_on_close() { + let broadcast = MoqBroadcastProducer::new().unwrap(); + let consumer = broadcast.consume().unwrap(); + + let closed = { + let consumer = consumer.clone(); + spawn_parked(async move { consumer.closed().await }).await + }; + assert!(!closed.is_finished(), "closed resolved while the broadcast is live"); + + broadcast.close().unwrap(); + tokio::time::timeout(TIMEOUT, closed) + .await + .expect("timed out waiting for closed") + .expect("closed panicked") + .unwrap(); +} + #[tokio::test] async fn raw_track_pending_next_group_does_not_block_datagram() { pending_group_does_not_block_datagram(|consumer| async move { consumer.next_group().await }).await; diff --git a/swift/README.md b/swift/README.md index e08de344375..9381f550cc7 100644 --- a/swift/README.md +++ b/swift/README.md @@ -78,7 +78,8 @@ Every consumer conforms to `AsyncSequence`, so `for try await x in consumer` wor Incoming server `Request` values expose the query-free `path` before acceptance. It is consistent across transports and is empty for the root or missing path. The encoded `query` may contain credentials. Raw tracks also expose best-effort datagrams: `TrackProducer.appendDatagram(_:timestampUs:)` -returns the assigned sequence number, `TrackConsumer.recvDatagram()` receives one datagram, +returns the assigned sequence number (`insertDatagram(_:sequence:timestampUs:)` takes the +caller's own), `TrackConsumer.recvDatagram()` receives one datagram, and `TrackConsumer.datagrams` streams them in arrival order. Payloads are capped at 1200 bytes. Datagrams require a datagram-capable transport and lite-05 or newer moq-lite, or moq-transport; pre-lite-05, WebSocket, and TCP paths do not deliver them, and there is no stream fallback. diff --git a/swift/Sources/Moq/Aliases.swift b/swift/Sources/Moq/Aliases.swift index f885be1d20c..9787186ca16 100644 --- a/swift/Sources/Moq/Aliases.swift +++ b/swift/Sources/Moq/Aliases.swift @@ -115,6 +115,9 @@ public typealias ProtocolKind = MoqFFI.MoqProtocolKind /// A protocol failure: scope, verbatim wire code, kind, and a diagnostic message. public typealias ProtocolError = MoqFFI.MoqProtocolError +/// A location within a track: a group sequence and a frame index in it. +public typealias Position = MoqFFI.MoqPosition + // Nested rather than top-level: a module-level `Range` would shadow `Swift.Range` // in every file that imports Moq. extension Subscription { diff --git a/swift/Sources/Moq/Broadcast.swift b/swift/Sources/Moq/Broadcast.swift index f9e949f1796..49dcd773699 100644 --- a/swift/Sources/Moq/Broadcast.swift +++ b/swift/Sources/Moq/Broadcast.swift @@ -9,6 +9,11 @@ public final class BroadcastConsumer: Sendable { self.ffi = ffi } + /// Wait until the broadcast ends: its publisher closed it, or every producer left. + public func closed() async throws { + try await ffi.closed() + } + /// Subscribe to a track by name, delivering raw frame payloads with no codec /// or container parsing. `subscription` tunes delivery priority, group range, and /// staleness; omit for defaults. diff --git a/swift/Sources/Moq/Track.swift b/swift/Sources/Moq/Track.swift index 7a3f1d23c1f..6f2426ecc49 100644 --- a/swift/Sources/Moq/Track.swift +++ b/swift/Sources/Moq/Track.swift @@ -189,6 +189,17 @@ public final class TrackProducer: Sendable { try ffi.appendDatagram(frame: Frame(payload: payload, timestampUs: timestampUs)) } + /// Send a best-effort datagram at an explicit sequence number, for a caller that + /// allocates its own. `appendDatagram` continues after the largest one. + public func insertDatagram(_ payload: Data, sequence: UInt64, timestampUs: UInt64? = nil) throws { + try ffi.insertDatagram(sequence: sequence, frame: Frame(payload: payload, timestampUs: timestampUs)) + } + + /// The newest group or datagram written, at its newest frame, or `nil` before any. + public func largest() throws -> Position? { + try ffi.largest() + } + /// Abort the track with an application error code, failing active consumers. public func abort(errorCode: UInt16) throws { try ffi.abort(errorCode: errorCode) diff --git a/test/wasm/README.md b/test/wasm/README.md index ebf38eff7bf..28eb2d44d0d 100644 --- a/test/wasm/README.md +++ b/test/wasm/README.md @@ -183,3 +183,28 @@ baseline backend. It also runs parity cases and per-call timings in `uniffi/` ag every relay, once normally and once under a strict CSP. It builds from a scratch checkout, since ubrn needs a UniFFI pin that does not land. [generator.md](generator.md) is the report that chose this binding. + +### Parity with `@moq/net` + +What `@moq/net`'s in-tree consumers (`js/hang`, `watch`, `publish`, `json`, `msf`, +`e2ee`, `room`, `moq-boy`) use, against moq-ffi on wasm32. The model is largely there: +announcements and `follow`, broadcasts, tracks and their demand, subscriptions and their +updates, ordered groups, timed frames, datagrams, the bandwidth allocator, and +cancellation. `uniffi/cases.ts` exercises the parts listed in its cases. + +Still missing or partial, by what the consumer does: + +| `@moq/net` | used by | moq-ffi on wasm32 | +| --- | --- | --- | +| `Connection` reconnects with backoff, and re-dials on a new `url` or `versions` | watch, publish, moq-boy | dials once; `backoff` is `Unsupported` | +| WebSocket fallback when WebTransport is missing | watch, publish | WebTransport only; `websocket` is `Unsupported` | +| `connection.probe` round trip and receive rate | watch, room | `stats()` reports little in the browser | +| `group.closed`, `group.arrived`, `group.expired` | hang | none on `MoqGroupConsumer` | +| frame `arrived` time | hang | `MoqFrame` carries no arrival time | +| `group.tryReadFrame()` | hang | async `read_frame` only | +| `abort(err: Error)` on a track or group | hang | `abort(code)` only | +| `Time.Timestamp` in a track's timescale | hang, publish | microseconds only | +| `Group.MAX_GROUP_CACHE_BYTES` and `_FRAMES` | json | not exported | + +Arrival times need the Rust and JS clocks to agree on origin and units first. Tokens and +in-band AUTH are native-only too, but no consumer uses `Auth` today. diff --git a/test/wasm/baseline/consumer.ts b/test/wasm/baseline/consumer.ts index 002ae022290..63be2211a2b 100644 --- a/test/wasm/baseline/consumer.ts +++ b/test/wasm/baseline/consumer.ts @@ -160,7 +160,10 @@ async function run(config: Sample) { disposers.push(() => session.cancel(0)); await Promise.all( Array.from({ length: config.publishers }, async (_, publisher) => { - const broadcast = await session.consume().follow(`${config.id}/${publisher}`).available(); + const broadcast = await session + .consume() + .follow(`${config.id}/${publisher}`, undefined) + .available(); const track = await broadcast.subscribeTrack("data", undefined); disposers.push(() => track.cancel()); const group = await track.recvGroup(); diff --git a/test/wasm/baseline/uniffi.ts b/test/wasm/baseline/uniffi.ts index 323ae1c06fa..b06b1eb0b21 100644 --- a/test/wasm/baseline/uniffi.ts +++ b/test/wasm/baseline/uniffi.ts @@ -12,7 +12,7 @@ export interface Uniffi { } interface Session { - consume(): { follow(path: string): { available(): Promise } }; + consume(): { follow(path: string, epoch: string | undefined): { available(): Promise } }; cancel(code: number): void; } diff --git a/test/wasm/uniffi/cases.ts b/test/wasm/uniffi/cases.ts index aa6c36e78d2..a3f36fc9813 100644 --- a/test/wasm/uniffi/cases.ts +++ b/test/wasm/uniffi/cases.ts @@ -281,6 +281,46 @@ const local: Record Promise> = { return `${first.message}; then ${later.message}`; }, + "largest follows the newest group and frame": async () => { + using fixture = localTrack(); + const { track } = fixture; + const position = () => { + const largest = track.largest(); + return largest && `${largest.group}/${largest.frame}`; + }; + if (position() !== undefined) throw new Error(`empty track at ${position()}`); + const group = track.createGroup(HIGH[0]); + group.writeFrame({ payload: payload(1), timestampUs: 0n }); + group.writeFrame({ payload: payload(1), timestampUs: 0n }); + track.createGroup(3n); + if (position() !== `${HIGH[0]}/1`) throw new Error(`largest ${position()} != ${HIGH[0]}/1`); + return undefined; + }, + + "insertDatagram keeps the caller's sequence": async () => { + using fixture = localTrack(); + const { track } = fixture; + const consumer = track.consume(undefined); + track.insertDatagram(HIGH[0], { payload: payload(5), timestampUs: 7n }); + const datagram = await within(consumer.recvDatagram(), 1000, "recvDatagram"); + if (datagram?.sequence !== HIGH[0]) throw new Error(`sequence ${datagram?.sequence} != ${HIGH[0]}`); + if (datagram.timestampUs !== 7n) throw new Error(`timestamp ${datagram.timestampUs}`); + if (datagram.payload.byteLength !== 5) throw new Error(`payload ${datagram.payload.byteLength} bytes`); + const next = track.appendDatagram({ payload: payload(1), timestampUs: 8n }); + if (next !== HIGH[0] + 1n) throw new Error(`appended at ${next}`); + return undefined; + }, + + "broadcast closed resolves once its producer closes": async () => { + using fixture = localTrack(); + const { broadcast } = fixture; + const closed = broadcast.consume().closed(); + if (!(await pending(closed))) throw new Error("closed settled while live"); + broadcast.close(); + await within(closed, 1000, "closed"); + return undefined; + }, + "closing the producer ends a pending read": async () => { using fixture = localGroup(); const { group, consumer } = fixture; @@ -339,7 +379,7 @@ const remote: Record Promise> = { const broadcast = publication.broadcast(); const track = broadcast.publishTrack("data", TIMED); publication.announce(MoqAnnounceRoute.create({})); - const consumer = await within(subscriber.consume().follow(path).available(), 5000, "announce"); + const consumer = await within(subscriber.consume().follow(path, undefined).available(), 5000, "announce"); const sub = await consumer.subscribeTrack("data", undefined); const seen: string[] = []; for (const sequence of [5n, 2n ** 32n, 2n ** 53n - 1n, ...HIGH]) { @@ -372,7 +412,7 @@ const remote: Record Promise> = { const broadcast = publication.broadcast(); broadcast.publishTrack("data", TIMED); publication.announce(MoqAnnounceRoute.create({})); - const consumer = await within(subscriber.consume().follow(path).available(), 5000, "announce"); + const consumer = await within(subscriber.consume().follow(path, undefined).available(), 5000, "announce"); const outcome = await settle( consumer.subscribeTrack("missing", undefined).then((track) => track.recvGroup()), 5000, @@ -388,6 +428,26 @@ const remote: Record Promise> = { } }, + "broadcast closed resolves when the publisher ends it": async (relay) => { + const publisher = await connect(relay); + const subscriber = await connect(relay); + try { + const path = `uniffi/closed/${crypto.randomUUID()}`; + const publication = publisher.publish().createBroadcast(path); + publication.broadcast().publishTrack("data", TIMED); + publication.announce(MoqAnnounceRoute.create({})); + const consumer = await within(subscriber.consume().follow(path, undefined).available(), 5000, "announce"); + const closed = consumer.closed(); + if (!(await pending(closed))) throw new Error("closed settled while announced"); + publication.broadcast().close(); + await within(closed, 5000, "closed after the publisher closed"); + return undefined; + } finally { + publisher.cancel(0); + subscriber.cancel(0); + } + }, + "session cancel rejects a pending remote read": async (relay) => { const publisher = await connect(relay); const subscriber = await connect(relay); @@ -397,7 +457,7 @@ const remote: Record Promise> = { const broadcast = publication.broadcast(); const track = broadcast.publishTrack("data", TIMED); publication.announce(MoqAnnounceRoute.create({})); - const consumer = await within(subscriber.consume().follow(path).available(), 5000, "announce"); + const consumer = await within(subscriber.consume().follow(path, undefined).available(), 5000, "announce"); const sub = await consumer.subscribeTrack("data", undefined); const group = track.appendGroup(); group.writeFrame({ payload: payload(4), timestampUs: 0n });