Skip to content

feat!: finishing an importer or the video producer returns a Finished handle - #8946

Merged
kixelated merged 5 commits into
mainfrom
quest/m2/finish-sweep
Nov 17, 2026
Merged

kixelated merged 5 commits into
mainfrom
quest/m2/finish-sweep

Conversation

@kixelated

@kixelated kixelated commented Nov 16, 2026 •

Copy link
Copy Markdown
Collaborator

Problem

moq-dev/moq#8395 made finishing a media producer return a Finished handle, but the sweep stopped short. The ten moq_mux::codec importers, moq_mux::import::{Track, TrackStream}, and moq_video::encode::Producer still took finish(&mut self). After finish a caller could still publish, and the bindings kept the whole importer (its splitter included) alive just to keep the track published. This finishes quest/m2/finish-sweep.md.

Approach

  • Codec importers: finish(self) returns the container::Finished of the producer each one wraps: Finished<hang::Container, VideoConfig> for video, AudioConfig for audio. All ten have the same shape, with no per-codec handle. The TS importer keeps its codec importers inside its own ts::Finished, so it ends them through a crate-private finish_in_place, the same pattern as container::Producer::end_with.
  • import::Track / TrackStream: finish(self) returns import::track::Finished, one type over the video or audio track. It exposes name and abort. import::track is now a public module, like import::container. A failed flush of the last access unit now aborts the track with its cause inside the library. moq-ffi and moq-c used to do that themselves, so their cause helpers are gone.
  • moq_video::encode::Producer: finish(self) -> Result<Finished, Error>. The new encode::Finished has demand and abort, matching the audio producer. The splitter is released with the producer.
  • Callers: moq-ffi (media.rs, video.rs) and moq-c (publish.rs, video.rs) now keep the Finished instead of the importer. moq-cli, moq-gst, moq-rtsp, moq-webrtc, the Rust interop client, and the moq-mux bench follow. moq-webrtc's internal Bridge::finish now consumes the bridge and hands back what keeps the track served. The bindings' own API is unchanged.
  • Doctests: two new compile_fail doctests, on import::track::Finished and moq_video::encode::Finished, check that writing after finish does not compile. The codec importers return container::Finished, which already has one.
  • Audit fix: moq-c's video finalize now forgets the child when its finish fails, as media_finish already did.

Impact

  • moq_mux::codec::{aac, av1, flac, h264, h265, mp3, opus, vp8, vp9}::Import::finish and moq_mux::codec::legacy::Import::finish (breaking): these now take self and return Result<container::Finished<catalog::hang::Container, hang::catalog::{VideoConfig | AudioConfig}>>. To migrate, hold the returned handle for as long as the track should stay published (dropping it releases the track and its rendition), and call abort on it instead of on the importer.
  • moq_mux::import::{Track, TrackStream}::finish (breaking): these now take self and return Result<moq_mux::import::track::Finished>. Migrate the same way. A failed finish now ends the track with its cause, so callers no longer abort the importer after an error.
  • moq_mux::import::track (new public module) holds Finished. Track, TrackStream, AudioInit, and VideoInit are still exported at moq_mux::import.
  • moq_video::encode::Producer::finish (breaking): now finish(self) -> Result<encode::Finished, Error>. Call abort on the returned Finished instead of on the producer.
  • moq_video::encode::Finished (new).
  • Bindings (moq-ffi, moq-c, and every language): no API change. Wire: none.

Decisions

The maintainer confirmed these decisions on 2026-11-16 (/quest-run). A review can still undo any of them:

  • Codec importers return container::Finished directly, not a handle of their own. It already carries name, demand, info, consume, estimate, and abort.
  • import::track::Finished is one type for both Track and TrackStream, with only name and abort. It has no public From impls, so the only way to get one is from a finish.
  • The TS importer uses a crate-private finish_in_place on the five codec importers it holds (h264, h265, aac, opus, legacy). The alternative was restructuring ts::Import to store finished handles, which would mean much more churn for no behavior change.
  • The video Finished has demand and abort but no name accessor, because the video Producer has none.

Alternatives

  • A small Finished per codec importer, wrapping the container one. Rejected: the quest asks for one shape, and the container type already says everything.
  • Keeping finish(&mut self) on the importers that only the TS importer calls in place. Rejected: the public API would be split between borrowing and consuming finishes.

Validation

  • just check: every module passed except py's test_socket.py::test_abort_and_endpoint_close_are_errors (an unroutable vs closed race on endpoint close). That is the flake moq-dev/moq#8900 fixes; it is unrelated to finish.
  • just test interop --all: all 210 lanes pass. These include finish rust -> {rust, python, go, cpp, js, js-native-node}, which drives the Rust client through TrackStream::finish and the linger, and every rust -> * lane, which runs moq import avc3 (the CLI's FinishedDecoder::Avc3) through the relay.
  • New moq-mux test import::track::tests::a_failed_finish_aborts_the_track. I mutation-checked it: with the in-library abort removed, it fails.
  • Second check: the memory tests finished_track_releases_its_splitter, finished_track_stream_releases_its_splitter, and moq-video's finished_producer_releases_its_splitter measure that a kept Finished no longer holds splitter storage. They pass against the new handles. moq-ffi's a_failed_finish_ends_the_track_with_its_cause still passes now that the abort lives in moq-mux.
  • just rs test -p moq-video --features openh264,capture encode::producer: 22 passed, including abort_after_finish (finish then abort through the handle) and the capture fixtures.
  • just rs doctest -p moq-mux -p moq-video: passes, including both new compile_fail doctests.

Follow-ups

None.

Models

Size: M
Implementer: Claude Code, claude-opus-5-5, medium effort (arm A)

🤖 Generated with Claude Code

(Written by Claude Opus 5.5 with medium)

Review

Rewritten by quest review after each round.

  • Head: 288e6e4

  • Base: origin/main at 0051c3d

  • Risk: high, Consuming finish APIs change public ownership requirements and can break downstream callers, which must update their code or revert the dependency upgrade.

  • Classified: medium by default

  • Reviewer: Codex, gpt-6.1-sol, high effort

  • Session: 01a1e8e6-f238-7a90-b7a2-cff55dfb5989, round 2

  • Score: 9/10, No actionable regressions were found in the incremental changes; the merged finish paths remain consistent, but builds and tests were not run as instructed.

  • Raised the risk to high: Consuming finish APIs change public ownership requirements and can break downstream callers, which must update their code or revert the dependency upgrade.

  • Rounds: 3; first round 0; findings 0: fixed 0, refuted 0, open 0

  • Findings: none

kixelated and others added 3 commits November 16, 2026 06:25
Quest-Claim: 643c164d506d880b
… handle

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@kixelated kixelated changed the title Finishing an importer or the video producer returns a Finished handle feat!: finishing an importer or the video producer returns a Finished handle Nov 16, 2026
@kixelated
kixelated marked this pull request as ready for review November 16, 2026 15:36
@coderabbitai

coderabbitai Bot commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

Warning

Review limit reached

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

Next included review available in 1 minute.

Check out review usage here.

View limit details

Limit details: You’ve used all 4 included reviews currently available.

Learn how review limits work.

Review configuration:

Run configuration

  • Source mode: Auto
  • Repository: Unavailable
  • Branch: Unavailable
  • File: No configuration file from this repository applied
  • Commit: Unavailable
  • Layers: Organization UI
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: 9236f3df-253f-4afb-bb50-dc2da917a3f1
Commits

Reviewing files that changed from the base of the PR and between c82de37 and 288e6e4.

Files selected for processing: 35

  • quest/m2/README.md
  • quest/m2/finish-sweep.md
  • quest/m2/video-producer.md
  • rs/moq-c/src/publish.rs
  • rs/moq-c/src/video.rs
  • rs/moq-cli/src/publish.rs
  • rs/moq-ffi/src/media.rs
  • rs/moq-ffi/src/video.rs
  • rs/moq-gst/src/sink/pad.rs
  • rs/moq-mux/benches/containers.rs
  • rs/moq-mux/src/codec/aac/import.rs
  • rs/moq-mux/src/codec/av1/import.rs
  • rs/moq-mux/src/codec/flac/import.rs
  • rs/moq-mux/src/codec/h264/import.rs
  • rs/moq-mux/src/codec/h265/import.rs
  • rs/moq-mux/src/codec/legacy.rs
  • rs/moq-mux/src/codec/mp3.rs
  • rs/moq-mux/src/codec/opus/import.rs
  • rs/moq-mux/src/codec/vp8/import.rs
  • rs/moq-mux/src/codec/vp9/import.rs
  • rs/moq-mux/src/container/ts/import.rs
  • rs/moq-mux/src/import/mod.rs
  • rs/moq-mux/src/import/track.rs
  • rs/moq-rtsp/src/client.rs
  • rs/moq-video/src/encode/mod.rs
  • rs/moq-video/src/encode/producer.rs
  • rs/moq-webrtc/src/codec/av1.rs
  • rs/moq-webrtc/src/codec/h264.rs
  • rs/moq-webrtc/src/codec/h265.rs
  • rs/moq-webrtc/src/codec/mod.rs
  • rs/moq-webrtc/src/codec/opus.rs
  • rs/moq-webrtc/src/codec/vp8.rs
  • rs/moq-webrtc/src/codec/vp9.rs
  • rs/moq-webrtc/src/session.rs
  • test/interop/clients/rust/finish.rs
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

Share

pullfrog[bot]
pullfrog Bot previously approved these changes Nov 16, 2026

@pullfrog pullfrog Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

✅ No new issues found.

Reviewed changes

Reviewed the full sweep that makes every remaining media producer's finish consume self and return a Finished handle, along with each caller.

  • Codec importers: all ten moq_mux::codec importers' finish(self) now delegates to container::Producer::finish. The five the TS importer keeps get a crate-private finish_in_place. A failed cut still aborts the track with its cause through end_with.
  • import::Track / TrackStream: these return import::track::Finished, which exposes name and abort. A failed flush of the last access unit now aborts the track inside moq-mux, so the duplicated cause() helpers in moq-ffi and moq-c are gone.
  • moq_video::encode::Producer: finish(self) returns encode::Finished, which exposes demand and abort. The splitter is released with the producer.
  • Callers: moq-c, moq-ffi, moq-cli, moq-gst, moq-rtsp, moq-webrtc, the bench, and the interop client keep the handle instead of the importer. moq-c's video finalize now forgets the child on a failed finish, as media_finish already did. moq-webrtc's Bridge::finish consumes the bridge, and that module is private, so the Box<dyn Send> alias stays internal.
  • Tests: there are two new compile_fail doctests. A new test, a_failed_finish_aborts_the_track, covers the abort that moved into moq-mux.

Pullfrog  | View workflow run | Using claude-opus-5-5 | 𝕏

@kixelated kixelated left a comment

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Automated review by review (OpenAI)

Reviewed 9c3a152d89aeb85ee1702e8f2c39abd4709e9b47. No blocker found. The new handles retain the track and catalog rendition where callers linger (bindings, GStreamer, and WebRTC), without retaining the input splitter. The flush-error path now aborts at the importer, so callers no longer need the consumed producer to report the cause.

For the migration note, distinguish a caller that still serves completed media (keep the returned handle) from teardown (drop it deliberately). Also call out the old “abort after a failed finish” pattern: abort directly on a drain failure; once finish(self) is called, it owns reporting a finalize failure. Static review only; I did not rerun interop or doctests.

pullfrog[bot]
pullfrog Bot previously approved these changes Nov 17, 2026

@pullfrog pullfrog Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

✅ No new issues found.

Reviewed changes

The only change since the prior review is a merge from origin/main. The PR's own code is unchanged.

  • Merged main: the merge brought in quest doc edits and a doc comment on an upstream test in rs/moq-mux/src/import/track.rs. It resolved cleanly against the consuming finish(self) API.

Pullfrog  | View workflow run | Using claude-opus-5-5 | 𝕏

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

@pullfrog pullfrog Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

✅ No new issues found.

Reviewed changes

The only change since the prior review is another merge from origin/main. Its conflict resolution keeps the consuming finish(self) API intact.

  • Resolved the TS opus stream against typed TS errors: in rs/moq-mux/src/container/ts/import.rs, the opus stream's finish now returns main's TS Result<()> and calls this PR's crate-private finish_in_place. The ? converts the error through From<crate::Error>. cargo check -p moq-mux --tests passes on the merged head.
  • Updated the quest index: quest/m2/README.md no longer links the completed finish-sweep quest. The ts-typed-outcomes link was already removed upstream.

Pullfrog  | View workflow run | Using claude-opus-5-5 | 𝕏

@kixelated
kixelated added this pull request to the merge queue Nov 17, 2026
Merged via the queue into main with commit 8c27c2c Nov 17, 2026
6 checks passed
@kixelated
kixelated deleted the quest/m2/finish-sweep branch November 17, 2026 11:39
kixelated added a commit that referenced this pull request Nov 17, 2026
Adopts #8946's Finished (Publisher::finish consumes and wraps
moq_mux::container::Finished), ports #8940's Capture::device and #8977's
sync.clock into the split capture.rs, and drops quests main or this PR finished.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant