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: 2 additions & 4 deletions dart/moq_ffi/lib/src/moq.dart
Original file line number Diff line number Diff line change
Expand Up @@ -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";

Expand Down Expand Up @@ -24694,7 +24692,7 @@ void _checkApiChecksums() {
55377) {
throw UniffiInternalError.panicked("UniFFI API checksum mismatch");
}
if (uniffi_moq_ffi_checksum_method_moqrequest_accept() != 55136) {
if (uniffi_moq_ffi_checksum_method_moqrequest_accept() != 30910) {
throw UniffiInternalError.panicked("UniFFI API checksum mismatch");
}
if (uniffi_moq_ffi_checksum_method_moqrequest_cancel() != 25859) {
Expand All @@ -24710,7 +24708,7 @@ void _checkApiChecksums() {
if (uniffi_moq_ffi_checksum_method_moqrequest_query() != 23842) {
throw UniffiInternalError.panicked("UniFFI API checksum mismatch");
}
if (uniffi_moq_ffi_checksum_method_moqrequest_reject() != 2829) {
if (uniffi_moq_ffi_checksum_method_moqrequest_reject() != 53566) {
throw UniffiInternalError.panicked("UniFFI API checksum mismatch");
}
if (uniffi_moq_ffi_checksum_method_moqrequest_transport() != 57171) {
Expand Down
2 changes: 1 addition & 1 deletion go/wrapper/errors.go
Original file line number Diff line number Diff line change
Expand Up @@ -61,7 +61,7 @@ var (
ErrBind = ffi.ErrMoqErrorBind
// ErrReject is returned when a session is refused during the handshake.
ErrReject = ffi.ErrMoqErrorReject
// ErrAlreadyResponded is returned when a Request is accepted or rejected more than once.
// ErrAlreadyResponded is returned when a request is used after it was accepted or rejected.
ErrAlreadyResponded = ffi.ErrMoqErrorAlreadyResponded
// ErrCodec is returned when codec configuration or bitstream parsing fails.
ErrCodec = ffi.ErrMoqErrorCodec
Expand Down
4 changes: 2 additions & 2 deletions go/wrapper/moq_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -1202,8 +1202,8 @@ func TestDynamicTrackRequestCanPublishAudio(t *testing.T) {
if mediaName != "requested-audio" {
t.Fatalf("media name = %q, want requested-audio", mediaName)
}
if _, err := request.Name(); !errors.Is(err, moq.ErrClosed) {
t.Fatalf("request name after accept error = %v, want ErrClosed", err)
if _, err := request.Name(); !errors.Is(err, moq.ErrAlreadyResponded) {
t.Fatalf("request name after accept error = %v, want ErrAlreadyResponded", err)
}

var mediaConsumer *moqmedia.TrackConsumer
Expand Down
2 changes: 1 addition & 1 deletion py/moq-rs/tests/test_socket.py
Original file line number Diff line number Diff line change
Expand Up @@ -74,7 +74,7 @@ async def test_refusal_and_cancelled_wait_leave_endpoint_usable():
incoming.reject()
with pytest.raises(moq.Error.NotFound):
await dial
with pytest.raises(moq.Error.Closed):
with pytest.raises(moq.Error.AlreadyResponded):
incoming.reject()
client, server = await tcp(a, b)
assert client.session == server.session
Expand Down
2 changes: 1 addition & 1 deletion quest/m1/explicit-state/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -70,7 +70,7 @@ which collapses that state and waits on [Drop set](/quest/m1/drop-set.md).
## Required

- [js/qmux close](/quest/m1/explicit-state/qmux-close.md) - a graceful remote close ends qmux streams cleanly
- [FFI handle state](/quest/m1/explicit-state/ffi-state.md) - FFI handles hold one state each: video follow under one lock, requests answered once, drivers Cancelled after shutdown
- [FFI handle state](/quest/m1/explicit-state/ffi-state.md) - moq-ffi's tasks and server, moq-c's ids, and the language wrappers hold one state each
- [moq-net phase data](/quest/m1/explicit-state/net-phases.md) - moq-net's session and subscription state machines keep each phase's data in its variant
- [TS and fMP4 export lifecycles](/quest/m1/explicit-state/mux-gst.md) - the TS export program and tracks and the fMP4 export track are explicit state

Expand Down
80 changes: 25 additions & 55 deletions quest/m1/explicit-state/ffi-state.md
Original file line number Diff line number Diff line change
@@ -1,66 +1,35 @@
# [L] FFI handle state
# [M] FFI handle state

## Goal

Each moq-ffi and moq-c handle holds its lifecycle in one value under one lock:

- A video producer's track, its bandwidth reservation, and its follower
change together. A finish or abort can't leave a reservation behind.
- A one-shot request handle (track, broadcast, datagram, socket, and server
requests) is pending, answered, or failed. A failed answer leaves the
request pending, or reports why it failed.
- A background driver that never ran reports `Cancelled`, never `Ok`.
Synchronous calls after `moq_ffi_shutdown` fail the same way the
asynchronous ones do.

The language wrappers stop mirroring Rust state in their own flags.
The moq-ffi and moq-c handles that still spread one lifecycle over several
fields hold it in one value under one lock, and the language wrappers stop
mirroring Rust state in their own flags.

## Plan

The shared decisions are in the [epic](/quest/m1/explicit-state/README.md).

Bugs to reproduce and fix:

- **Video follow across locks** (`rs/moq-ffi/src/video.rs`):
- `inner`, `reservation`, and `follow` are three mutexes.
- `write()` releases `inner` and only then calls `follow_track`, so a
`finish()` on another thread can run in between.
- `follow_track` then stores a new reservation for a finished track.
- `abort()` returns early once `inner` is `None` and never clears it.
- Recommended: `Mutex<enum { Open { producer, follow: Option<(Reservation,
Follow)> }, Closed }>`.
- The same bug exists in `rs/moq-c/src/video.rs` (`follow_grant` spreads
`reservation`, `follow`, and `followed` across three lock acquisitions).
It also exists in the encoder `apply` of both crates: the encoder is taken
before a fallible `discontinuity()`, so a failure leaves the catalog
saying enabled while frames are dropped.
- **`Background` after shutdown** (`rs/moq-ffi/src/ffi.rs`; `rs/moq-c/src/ffi.rs`
maps the same case to `Panic`):
- `Option<Consumer<Option<Result>>>` encodes five states.
- `check()` reads "dropped without a result" as `Ok`, while `finished()`
reads it as `Cancel`.
- Recommended: `enum Completion { Detached, Running, Done(Result), Dropped }`.

Also sweep:

- The `Mutex<Option<Request>>` handles: `producer.rs`, `origin.rs`,
`datagram.rs`, `socket.rs`, `server.rs`, and `media.rs`'s `Requested`
target. Each is taken before validation or before an await, and they return
inconsistent errors (`Closed` vs `AlreadyResponded`).
- `Task<T>` (`ffi.rs`): a cancel flag, an `Option` state, and the cleanup.
- `MoqServer` (`server.rs`): its lifecycle is spread over four places.
[moq-dev/moq#8264](https://github.com/moq-dev/moq/pull/8264) fixed the
reproduced bugs: the video producer's track, reservation, and follower
under one lock in both crates; the encoder disable that left the catalog
enabled; `Background` reading a dropped driver as `Cancelled` everywhere;
and the one-shot request handles (`OneShot` in `rs/moq-ffi/src/ffi.rs`),
which now answer once and report `AlreadyResponded` or the first answer's
error. What remains has no known bug, so it needs no test beyond what each
redesign changes.

Sweep in moq-ffi and moq-c:

- `Task<T>` (`rs/moq-ffi/src/ffi.rs`): a cancel flag, an `Option` state, and
the cleanup.
- `MoqServer` (`rs/moq-ffi/src/server.rs`): its lifecycle is spread over
four places (`task`, `driver`, `listening`, and the task's state).
- `MoqTrackProducer.keep: None`, which means both "finished" and "has no
family".
- `MoqConnectionState` (`session.rs`) is a flat snapshot (`revision`,
`phase`, `connects`, `failure`, `version`), so `failure` and `version` are
readable in phases where they mean nothing. It carries each phase's data
with that phase, mirroring whatever shape Rust's connection state takes,
and moq-c's `moq_connection_state` follows (renaming its `protocol` to
`version`). It breaks every binding, so under the epic's milestone rule
this item splits into its own m2 quest when this quest starts (added
2026-11-07, maintainer, /quest-plan from the API shape audit).
- moq-c's global id counter, whose wrap lets a stale route id name a newer
broadcast. Use generation-tagged ids or clear ids on close.
- moq-c's global id counter (`rs/moq-c/src/id.rs`), whose wrap lets a stale
route id name a newer broadcast. Use generation-tagged ids or clear ids on
close.

Then sweep the hand-written wrappers:

Expand All @@ -69,5 +38,6 @@ Then sweep the hand-written wrappers:
- the OBS output's mirrored `connected`/`live`;
- the Dart stream.

[moq-dev/moq#8060](https://github.com/moq-dev/moq/pull/8060) (moq-c parity)
edits `rs/moq-c/src/video.rs` and `ffi.rs`, so expect merge conflicts.
`MoqConnectionState` split into
[Connection state carries each phase's data](/quest/m2/connection-state-phases.md),
since it breaks every binding.
1 change: 1 addition & 0 deletions quest/m2/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -197,6 +197,7 @@ quests that require them.
- [Unbounded groups](/quest/m2/unbounded-groups/README.md) - groups and frames lose their size caps; a group keeps a 32 MB tail, and readers behind it replay through paced flights or refresh
- [moq-quic drops inherited surfaces with no consumer](/quest/m2/moq-quic-unused-surface.md) - unused accept, connection, and stream-id surfaces leave moq-quic's public API before the cut
- [No sentinel values in public API](/quest/m2/no-sentinels.md) - receive windows, cache durations, reconnect timeouts, and the FFI test clock use `Option` instead of a huge value or zero
- [Connection state carries each phase's data](/quest/m2/connection-state-phases.md) - moq-tokio's `Observation`, moq-ffi's `MoqConnectionState`, and moq-c's `moq_connection_state` each hold one phase per value, so no field is readable in a phase where it means nothing
- [moq-video takes devices, not environment variables](/quest/m2/video-devices.md) - VA-API and V4L2 device paths are config fields, and `moq_video::ENV` never ships
- [Gateways share one ingest config and one rate cap](/quest/m2/gateway-ingest.md) - `moq_mux::Ingest` replaces 18 per-gateway setters, and the live rate cap moves to `moq_net::bandwidth`
- [JS time values are types, not numbers](/quest/m2/js-time-types.md) - every public JS duration and instant is a `Clock.Duration` or `Clock.Instant` object, so a unit mistake fails to compile
Expand Down
38 changes: 38 additions & 0 deletions quest/m2/connection-state-phases.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,38 @@
# [L] Connection state carries each phase's data

## Goal

A connection state snapshot carries each phase's data inside that phase, so
a field that means nothing in the current phase can't be read:

- moq-ffi's `MoqConnectionState` (`rs/moq-ffi/src/session.rs`) is a flat
record (`revision`, `phase`, `connects`, `failure`, `version`), so
`failure` and `version` are readable in phases where they mean nothing.
It becomes a phase enum whose variants carry their own data, mirroring
Rust's `moq_tokio::connection::Observation`, which takes the same shape,
and every hand-written wrapper follows.
- moq-c's `moq_connection_state` follows the same shape and renames its
`protocol` to `version`.

## Plan

Split from [FFI handle state](/quest/m1/explicit-state/ffi-state.md) when it
Comment thread
kixelated marked this conversation as resolved.
Resolved
started (2026-11-08), as that item recorded: it breaks every binding, so
under the [explicit-state epic](/quest/m1/explicit-state/README.md)'s
milestone rule it is its own m2 quest. Its PR marks its title `!` and says
how to migrate.

Rust's `moq_tokio::connection::Observation` (`rs/moq-tokio/src/connection.rs`)
is flat too: `failure`, `version`, `transport`, and `last_connected` sit
beside `phase`, while the private `Lifecycle` enum it is built from already
carries them per phase.

- ✅ Decided 2026-11-08 (maintainer): reshape `Observation` together with
`MoqConnectionState`, one phase per value in both, so each binding converts
one enum to another (rejected: reshape only the binding records and keep
Rust's snapshot flat).

## Related

- [Lifecycles are explicit state](/quest/m1/explicit-state/README.md) - the epic this item split from
- [Bindings' small surface fixes](/quest/m2/api-shape/bindings.md) - other breaking binding fixes before the cut
71 changes: 59 additions & 12 deletions rs/moq-c/src/ffi.rs
Original file line number Diff line number Diff line change
Expand Up @@ -124,26 +124,34 @@ impl Background {
Self { result: Some(receiver) }
}

/// Read the operation's completion, arming `waiter` while it runs. Every reader goes through
/// here, so a synchronous check and an awaited one agree on each state.
fn completion(&self, waiter: &kio::Waiter) -> Completion {
let Some(result) = &self.result else {
return Completion::Detached;
};
let completed = result.poll(waiter, |state| match &**state {
Some(result) => std::task::Poll::Ready(result.clone()),
None => std::task::Poll::Pending,
});
match completed {
std::task::Poll::Pending => Completion::Running,
std::task::Poll::Ready(Ok(result)) => Completion::Done(result),
std::task::Poll::Ready(Err(_)) => Completion::Dropped,
}
}

/// Return a completed background failure, if any.
pub fn check(&self) -> Result<(), Error> {
self.result
.as_ref()
.map(|result| result.read().clone().unwrap_or(Ok(())))
.unwrap_or(Ok(()))
self.completion(&kio::Waiter::noop()).result().unwrap_or(Ok(()))
}

/// The background operation's result, once it finishes.
#[kio::wrapper]
pub fn poll_finished(&self, waiter: &kio::Waiter) -> std::task::Poll<Result<(), Error>> {
let Some(result) = &self.result else {
return std::task::Poll::Ready(Ok(()));
};
match std::task::ready!(result.poll(waiter, |state| match &**state {
Some(result) => std::task::Poll::Ready(result.clone()),
match self.completion(waiter).result() {
Some(result) => std::task::Poll::Ready(result),
None => std::task::Poll::Pending,
})) {
Ok(result) => std::task::Poll::Ready(result),
Err(_) => std::task::Poll::Ready(Err(Error::Panic)),
}
}

Expand All @@ -164,6 +172,28 @@ impl Background {
}
}

/// Where an owned operation stands, as its handle's calls report it.
enum Completion {
/// The handle owns no operation, so nothing can fail it.
Detached,
Running,
Done(Result<(), Error>),
/// Released without a result, which only the runtime's teardown does.
Dropped,
}

impl Completion {
/// What the handle's calls report, or `None` while the operation runs.
fn result(self) -> Option<Result<(), Error>> {
match self {
Self::Detached => Some(Ok(())),
Self::Running => None,
Self::Done(result) => Some(result),
Self::Dropped => Some(Err(moq_net::Error::Cancel.into())),
}
}
}

#[cfg(test)]
pub(crate) fn panicking_origin() -> (moq_net::origin::Producer, Background, kio::Producer<bool>) {
struct Driver {
Expand Down Expand Up @@ -617,6 +647,23 @@ mod tests {
));
}

/// A background dropped before it reported reads as cancelled to a check and an await alike.
#[tokio::test]
async fn a_dropped_background_reads_cancelled_everywhere() {
let result = kio::Producer::new(None);
let background = Background {
result: Some(result.consume()),
};
drop(result);
let checked = background.check();
let finished = background.finished().await;
assert!(
matches!(checked, Err(Error::Moq(moq_net::Error::Cancel)))
&& matches!(finished, Err(Error::Moq(moq_net::Error::Cancel))),
"{checked:?} {finished:?}"
);
}

struct PanickingDriver {
dropped: Option<tokio::sync::oneshot::Sender<()>>,
observed: std::sync::mpsc::Receiver<()>,
Expand Down
Loading
Loading