Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions cpp/obs/src/moq-output.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -391,9 +391,9 @@ void MoQOutput::Reset()
broadcast.reset();
origin.reset();

// Drain once the tracks are finished, so the session delivers their tails instead
// of cutting them off. The future holds the session until the drain settles, and
// dropping it would abort the drain, so keep it past this attempt.
// Drain once tracks finish. Default lite-06 waits for transport ACKs, not
// confirmation that the peer received the tail. Keep the future past this
// attempt because dropping it aborts the drain.
if (retired) {
draining.erase(std::remove_if(draining.begin(), draining.end(),
[](const moq::Future<void> &drain) {
Expand Down
6 changes: 5 additions & 1 deletion dart/moq/lib/src/client.dart
Original file line number Diff line number Diff line change
Expand Up @@ -189,7 +189,11 @@ final class Moq {
/// the room back.
Bandwidth bandwidth() => session.bandwidth();

/// Gracefully close the session and stop the client.
/// Drain within one second, then stop the client.
///
/// Explicit `moq-lite-07-wip` waits for the peer to receive finished tails; older
/// Lite versions, including the default lite-06, wait only for transport ACKs.
/// IETF also waits for transport ACKs.
Future<void> close() async {
try {
await session.shutdown();
Expand Down
2 changes: 1 addition & 1 deletion dart/moq_ffi/lib/src/moq.dart
Original file line number Diff line number Diff line change
Expand Up @@ -13678,7 +13678,7 @@ void _checkApiChecksums() {
if (uniffi_moq_ffi_checksum_method_moqsession_publish() != 15240) {
throw UniffiInternalError.panicked("UniFFI API checksum mismatch");
}
if (uniffi_moq_ffi_checksum_method_moqsession_shutdown() != 64390) {
if (uniffi_moq_ffi_checksum_method_moqsession_shutdown() != 1301) {
throw UniffiInternalError.panicked("UniFFI API checksum mismatch");
}
if (uniffi_moq_ffi_checksum_method_moqsession_stats() != 44305) {
Expand Down
4 changes: 3 additions & 1 deletion doc/bin/obs.md
Original file line number Diff line number Diff line change
Expand Up @@ -67,7 +67,9 @@ stream limit, and the WebSocket fallback race. A rejected value stops the
stream with the reason in the log rather than silently using a default.

The plugin is C++ over the [generated C++ bindings](/lib/cpp/) and ships with
every moq-cpp release.
every moq-cpp release. Stopping finishes the tracks and drains for up to one
second. The default lite-06 waits for transport ACKs, which do not confirm that
the peer received the tail.

If the relay closes the session for too many requests, reduce the broadcasts
or subscribed tracks, or have the operator adjust its
Expand Down
5 changes: 5 additions & 0 deletions doc/lib/cpp/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -191,6 +191,11 @@ Obtain a dynamic track request’s `demand()` before accepting it to watch subsc

## Shutdown

`session->shutdown().get()` drains for up to one second and reports any error.
Application delivery requires explicitly selecting `moq-lite-07-wip` on both
peers; older Lite versions (including default lite-06) and IETF wait only for
transport ACKs. Finish or abort live tracks first.

`moq::shutdown()` stops the `moq-ffi` runtime workers, then the executor.
Pending calls resolve `Cancelled`, and every object stays safe to drop. Call
it once before a plugin or engine module unloads, from a thread that is not
Expand Down
2 changes: 1 addition & 1 deletion doc/lib/dart/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -76,7 +76,7 @@ one to one; the API reference has the names.
- **Names.** Types drop the `Moq` prefix (`Session`, `BroadcastProducer`) as aliases, so the generated names still work. `Container`, `Route`, and the exceptions keep it, since Flutter owns those names. `dynamic` is reserved, so the origin method is `dynamic_`.
- **Audio needs cuts.** Video groups at its keyframes, but audio forms a group only where you call `cut()`: after every frame, or at a segment cadence to align with video.
- **Live encoder timing.** After writing a frame you encoded yourself, call `flush(timestampUs: ...)` with the same timestamp so the catalog advertises your jitter. Skip it for file and network imports. On a seek or pause, call `discontinuity()`, then keep timestamps moving forward and resume video on a keyframe.
- **Closing.** `await moq.close()` or `session.shutdown()` gives finished tracks up to one second to deliver and fails if they did not. `session.cancel(code: 0)` closes at once. Finish or abort live tracks first. Cancelling a stream subscription releases its native cursor.
- **Closing.** `await moq.close()` or `session.shutdown()` drains for up to one second and reports any error. `session.cancel(code: 0)` closes at once. Finish or abort live tracks first. Cancelling a stream subscription releases its native cursor. Application delivery requires explicitly selecting `moq-lite-07-wip` on both peers; older Lite versions (including default lite-06) and IETF wait only for transport ACKs.
- **Stats.** `session.stats()` reports `rttUs`, `estimatedSendRateBps`, `estimatedRecvRateBps`, and the byte and packet counters (`bytesSent`, `bytesReceived`, `bytesLost`, `packetsSent`, `packetsReceived`, `packetsLost`). A field is `null` when the transport does not report it, which is not the same as zero.
- **Errors.** Read diagnostic payloads from `reason` and structured protocol failures from `details`.
- **Disabled renditions.** Audio and video convenience decoders reject a catalog configuration with `enabled: false`. Select an enabled rendition from the latest catalog before opening a decoder.
Expand Down
2 changes: 1 addition & 1 deletion doc/lib/go/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -106,7 +106,7 @@ one to one; the API reference has the names.
- **Audio needs cuts.** Video groups at its keyframes, but audio forms a group only where you call `Cut()`: after every frame, or at a segment cadence to align with video.
- **Live encoder timing.** After writing a frame you encoded yourself, call `Flush(timestamp)` with the same timestamp so the catalog advertises your jitter. Skip it for file and network imports. On a seek or pause, call `Discontinuity()`, then keep timestamps moving forward and resume video on a keyframe.
- **Decoded frames hold decoder buffers.** `Close` each `VideoDecodedFrame` promptly, or the decoder stalls. `Resize` is best effort, so read each frame's `Width()` and `Height()`.
- **Closing.** `client.Close()` gives finished tracks up to one second to deliver and returns an error if they did not. `session.Shutdown(ctx)` does the same, and `session.Cancel(code)` closes at once. Finish or abort live tracks first.
- **Closing.** `client.Close()` drains for up to one second and returns an error on failure. `session.Shutdown(ctx)` does the same, and `session.Cancel(code)` closes at once. Finish or abort live tracks first. Application delivery requires explicitly selecting `moq-lite-07-wip` on both peers; older Lite versions (including default lite-06) and IETF wait only for transport ACKs.
- **Stats.** `Session().Stats()` reports `RTT`, `EstimatedSendRateBps`, `EstimatedRecvRateBps`, and the byte and packet counters (`BytesSent`, `BytesReceived`, `BytesLost`, `PacketsSent`, `PacketsReceived`, `PacketsLost`). A field is nil when the transport does not report it, which is not the same as zero.
- **Errors.** Read diagnostic payloads from `Reason` and structured protocol failures from `Details`.
- **Disabled renditions.** Audio and video convenience decoders reject a catalog configuration with `enabled: false`. Select an enabled rendition from the latest catalog before opening a decoder.
Expand Down
2 changes: 1 addition & 1 deletion doc/lib/js/net.md
Original file line number Diff line number Diff line change
Expand Up @@ -46,7 +46,7 @@ broadcast.announce();
- **Subscriber staleness is `maxDelay`.** It is media time. Passing the old `maxAge` key throws a `TypeError` naming `maxDelay`. Publisher retention is the separate `Track.Info.maxAge`.
- **Hidden paths** stay out of discovery unless the announce request opts in. See [hidden broadcasts](/concept/moq-lite#hidden-broadcasts).
- **Authorization is in band.** On moq-lite 07 (offered only when `moq-lite-07-wip` is listed in `webtransport.protocols`; the WebSocket fallback cannot offer it) and on moq-transport draft-17+ with the [MoQ Auth extension](/draft/moq-auth), `auth.grant` watches what the relay lets this side publish and subscribe to, and `auth.add(token)` presents another token without reconnecting. Publishing outside the grant closes the connection with `SessionCode.Unauthorized`, naming the path. On moq-lite, a subscription the grant stops covering resets with `StreamCode.Unauthorized` and the session stays up.
- **A graceful close waits.** `await connection.close()` withdraws announcements and gives finished tracks up to one second. `abort()` ends immediately.
- **A graceful close waits.** `await connection.close()` withdraws announcements and drains for up to one second. Application delivery requires explicit `moq-lite-07-wip`; older Lite versions wait only for transport ACKs. IETF media streams are not drained. `abort()` ends immediately.

Examples:
[`js/net/examples/`](https://github.com/moq-dev/moq/tree/main/js/net/examples).
Expand Down
2 changes: 1 addition & 1 deletion doc/lib/kt/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -81,7 +81,7 @@ one to one; the API reference has the names.
- **Audio needs cuts.** Video groups at its keyframes, but audio forms a group only where you call `cut()`: after every frame, or at a segment cadence to align with video.
- **Live encoder timing.** After writing a frame you encoded yourself, call `flush(timestampUs)` with the same timestamp so the catalog advertises your jitter. Skip it for file and network imports. On a seek or pause, call `discontinuity()`, then keep timestamps moving forward and resume video on a keyframe.
- **Decoded frames hold decoder buffers.** `close()` each frame from `decodeVideo` promptly (or `use { }` it), or the decoder stalls. `resize` is best effort, so read each frame's `width()` and `height()`.
- **Closing.** Suspending `moq.shutdown()` gives finished tracks up to one second to deliver and throws if they did not. `Moq.close()`, and so `use { }`, cancels at once. Finish or abort live tracks first.
- **Closing.** Suspending `moq.shutdown()` drains for up to one second and throws on failure. `Moq.close()`, and so `use { }`, cancels at once. Finish or abort live tracks first. Application delivery requires explicitly selecting `moq-lite-07-wip` on both peers; older Lite versions (including default lite-06) and IETF wait only for transport ACKs.
- **Stats.** `session.stats()` reports `rttUs`, `estimatedSendRateBps`, `estimatedRecvRateBps`, and the byte and packet counters (`bytesSent`, `bytesReceived`, `bytesLost`, `packetsSent`, `packetsReceived`, `packetsLost`). A field is `null` when the transport does not report it, which is not the same as zero.
- **Errors.** Read diagnostic payloads from `reason` and structured protocol failures from `details`.
- **Disabled renditions.** Audio and video convenience decoders reject a catalog configuration with `enabled: false`. Select an enabled rendition from the latest catalog before opening a decoder.
Expand Down
2 changes: 1 addition & 1 deletion doc/lib/py/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -97,7 +97,7 @@ one to one; the API reference has the names.
- **Audio needs cuts.** Video groups at its keyframes, but audio forms a group only where you call `cut()`: after every frame, or at a segment cadence to align with video.
- **Live encoder timing.** After writing a frame you encoded yourself, call `flush(timestamp)` with the same timestamp so the catalog advertises your jitter. Skip it for file and network imports. On a seek or pause, call `discontinuity()`, then keep timestamps moving forward and resume video on a keyframe.
- **Decoded frames hold decoder buffers.** Drop each frame from `decode_video` promptly, or the decoder stalls. `resize` is best effort, so read each frame's `width()` and `height()`.
- **Closing.** `await session.shutdown()` gives finished tracks up to one second to deliver and raises if they did not. `cancel(code)` closes at once. Finish or abort live tracks first.
- **Closing.** `await session.shutdown()` drains for up to one second and raises on failure. `cancel(code)` closes at once. Finish or abort live tracks first. Application delivery requires explicitly selecting `moq-lite-07-wip` on both peers; older Lite versions (including default lite-06) and IETF wait only for transport ACKs.
- **Stats.** `session.stats()` reports `rtt`, `estimated_send_rate_bps`, `estimated_recv_rate_bps`, and the byte and packet counters (`bytes_sent`, `bytes_received`, `bytes_lost`, `packets_sent`, `packets_received`, `packets_lost`). A field is `None` when the transport does not report it, which is not the same as zero.
- **Errors.** Read diagnostic payloads from `reason` and structured protocol failures from `details`.
- **Disabled renditions.** Audio and video convenience decoders reject a catalog configuration with `enabled: false`. Select an enabled rendition from the latest catalog before opening a decoder.
Expand Down
2 changes: 1 addition & 1 deletion doc/lib/rs/moq-net.md
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,7 @@ What you use it for, beyond what the concept page already describes:
- **You drive the session, or `moq-tokio` does.** `connect` and `accept` return a session plus a driver that never reads the clock itself. `moq_net::time::run` polls it on tokio or in the browser. `moq-tokio` and `moq-wasm` hide that. A custom transport implements `moq_net::transport::poll`.
- **A session caps what its peer can hold.** `session::Limits` (via `Client::with_limits` and `Server::with_limits`) bounds announces and subscriptions per session; the defaults suit a relay mesh, so lower them for untrusted peers. Past either, the session closes with `TOO_MANY_REQUESTS`. On moq-transport drafts 14 to 16 they also size the request-ID window, which every request counts against, so very low limits can starve it. Peer-declared lengths are capped before they are buffered.
- **Authorization is in band.** On moq-lite 07 (`moq-lite-07-wip`, opt-in) and on moq-transport draft-17+ with the [MoQ Auth extension](/draft/moq-auth), `session.auth()` presents tokens without reconnecting and watches the grant the peer sent back. A server verifies tokens itself by taking `handshake.auth().requests()` before `ok()`. `authorize(&grant)` narrows or widens a live session on any version: what falls outside resets with `Unauthorized` and the session stays up. A client that publishes outside its grant closes the session, naming the path.
- **A graceful close waits.** `session.close().await` withdraws announcements and gives finished tracks up to one second to deliver. `abort` ends immediately. IETF drafts 14 through 16 send withdrawals without waiting.
- **A graceful close waits.** `session.close().await` withdraws announcements and drains for up to one second. Application delivery requires explicit `moq-lite-07-wip`; older Lite versions (including default lite-06) and IETF wait only for transport ACKs. `abort` ends immediately. IETF drafts 14 through 16 send withdrawals without waiting.

```bash
cargo add moq-net moq-tokio
Expand Down
2 changes: 1 addition & 1 deletion doc/lib/swift/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -81,7 +81,7 @@ one to one; the API reference has the names.
- **Audio needs cuts.** Video groups at its keyframes, but audio forms a group only where you call `cut()`: after every frame, or at a segment cadence to align with video.
- **Live encoder timing.** After writing a frame you encoded yourself, call `flush(timestampUs:)` with the same timestamp so the catalog advertises your jitter. Skip it for file and network imports. On a seek or pause, call `discontinuity()`, then keep timestamps moving forward and resume video on a keyframe.
- **Decoded frames hold decoder buffers.** Release each frame from `decodeVideo` promptly, or the decoder stalls. `resize` is best effort, so read each frame's `width()` and `height()`.
- **Closing.** `try await session.shutdown()` gives finished tracks up to one second to deliver and throws if they did not. `session.cancel(code:)` closes at once. Finish or abort live tracks first.
- **Closing.** `try await session.shutdown()` drains for up to one second and throws on failure. `session.cancel(code:)` closes at once. Finish or abort live tracks first. Application delivery requires explicitly selecting `moq-lite-07-wip` on both peers; older Lite versions (including default lite-06) and IETF wait only for transport ACKs.
- **Stats.** `session.stats()` reports `rttUs`, `estimatedSendRateBps`, `estimatedRecvRateBps`, and the byte and packet counters (`bytesSent`, `bytesReceived`, `bytesLost`, `packetsSent`, `packetsReceived`, `packetsLost`). A field is `nil` when the transport does not report it, which is not the same as zero.
- **Errors.** Diagnostic cases use the `reason:` argument label; match their associated value to inspect it. Protocol errors carry `details`.
- **Disabled renditions.** Audio and video convenience decoders reject a catalog configuration with `enabled: false`. Select an enabled rendition from the latest catalog before opening a decoder.
Expand Down
5 changes: 4 additions & 1 deletion go/wrapper/session.go
Original file line number Diff line number Diff line change
Expand Up @@ -104,7 +104,10 @@ func (s *Session) Consume() *OriginConsumer {
return &OriginConsumer{inner: s.inner.Consume()}
}

// Shutdown drains finished tracks within one second, returning any delivery error.
// Shutdown drains finished tracks within one second, returning any drain error.
// Explicit moq-lite-07-wip waits for the peer to receive finished tails; older Lite
// versions, including the default lite-06, wait only for transport ACKs.
// IETF also waits for transport ACKs.
// Cancelling ctx aborts the session immediately.
func (s *Session) Shutdown(ctx context.Context) error {
return bridge.CallErr(ctx, s.abort, s.inner.Shutdown)
Expand Down
7 changes: 6 additions & 1 deletion js/net/src/connection/established.ts
Original file line number Diff line number Diff line change
Expand Up @@ -52,7 +52,12 @@ export interface Established {
*/
stats(): Promise<Stats>;

/** Withdraw announcements and wait up to one second for delivery, then close the session. */
/**
* Withdraw announcements and drain for up to one second, then close the session.
*
* Explicit lite-07-wip waits for the subscriber to receive finished tails; older
* Lite versions wait only for transport ACKs. IETF media streams are not drained.
*/
close(): Promise<void>;

/** End the session immediately without waiting for delivery. */
Expand Down
7 changes: 6 additions & 1 deletion kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/Moq.kt
Original file line number Diff line number Diff line change
Expand Up @@ -67,7 +67,12 @@ class Moq internal constructor(
*/
fun bandwidth(): Bandwidth = session.bandwidth()

/** Drain finished tracks within one second, throwing if delivery times out. */
/**
* Drain finished tracks within one second, throwing on failure.
* Explicit `moq-lite-07-wip` waits for the peer to receive finished tails; older
* Lite versions, including the default lite-06, wait only for transport ACKs.
* IETF also waits for transport ACKs.
*/
suspend fun shutdown() {
try {
session.shutdown()
Expand Down
2 changes: 1 addition & 1 deletion py/moq-rs/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -150,7 +150,7 @@ client = moq.Client(
- `.cancel()`. Cancel an in-flight `accept()`/`reject()` call.
- **`Session`**. An established connection. Holding it keeps the connection alive; it is also an `async with` context manager that drains on a clean exit and cancels on an error.
- `await .closed()`. Wait until the session closes.
- `.cancel(code)`, `await session.shutdown()`. Cancel immediately, or drain finished tracks within one second, raising on failure.
- `.cancel(code)`, `await session.shutdown()`. Cancel immediately, or drain within one second, raising on failure. Explicit `moq-lite-07-wip` waits for the peer to receive finished tails; older Lite versions, including default lite-06, wait only for transport ACKs. IETF also waits for transport ACKs.
- `.publish() → OriginProducer`, `.consume() → OriginConsumer`. The wired origin sides.
- `.stats() → ConnectionStats`. Snapshot RTT, bandwidth estimates, and byte/packet counters.
- `await .status() → ConnectionStatus`, `.connects()`. Watch reconnects; `connects()` counts connections, 1 on the first.
Expand Down
7 changes: 6 additions & 1 deletion py/moq-rs/moq/session.py
Original file line number Diff line number Diff line change
Expand Up @@ -72,7 +72,12 @@ def cancel(self, code: int) -> None:
self._inner.cancel(code)

async def shutdown(self) -> None:
"""Drain finished tracks within one second, raising if delivery times out."""
"""Drain within one second, raising on failure.

Explicit ``moq-lite-07-wip`` waits for the peer to receive finished tails;
older Lite versions, including the default lite-06, wait only for transport
ACKs. IETF also waits for transport ACKs.
"""
await self._inner.shutdown()

def publish(self) -> OriginProducer:
Expand Down
1 change: 0 additions & 1 deletion quest/m1/test-flakes-2/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -40,7 +40,6 @@ Public API: none. Wire: none.
- [uring teardown close](/quest/m1/test-flakes-2/uring-teardown-close.md) - moq-uring's published-close teardown test holds under load, fixed at its cause
- [Auth serve signals](/quest/m1/test-flakes-2/auth-serve-signals.md) - moq-cli's auth serve signal tests hold under load
- [Export exit tests](/quest/m1/test-flakes-2/export-failure-exit.md) - moq-cli's failed-export and interrupted-publisher exit tests hold under load
- [FFI shutdown](/quest/m1/test-flakes-2/ffi-shutdown.md) - moq-ffi's graceful shutdown tests hold under load

## Related

Expand Down
Loading
Loading