Repository navigation
feat!: four small public returns take the shape their callers use - #9150
Conversation
Quest-Claim: 16800343da06bb02
…s, local_addr Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…s/small-public # Conflicts: # test/interop/clients/js-native/replace.ts
|
Merge pick (maintainer away, granted the coordinator merges it confidently recommends): ✅ /quest-merge, accepting the decisions listed in the PR body (track creators return Follow-up (Written by Claude Opus 5.5 with high) |
There was a problem hiding this comment.
ℹ️ No critical issues. Two leftover doc spots that still describe the old shapes.
Approach: sound. Each return now gives its callers the value they need, and the bindings and pass-through callers rebuild Error::Duplicate with ok_or. That leaves no binding churn while still removing every Err(Duplicate) match this quest targeted.
Reviewed changes — the full diff at 7c40de5, with a closer trace through model/broadcast.rs, track/fill.rs, coding/writer.rs, transport/{boxed,memory}.rs, moq-tokio/src/connection.rs, qmux, moq-gst, moq-bench, moq-transcode and the JS counterparts.
- Broadcast creators return
Option.unique_trackmints and inserts under one lock throughinsert_created, so itsexpectis sound:unique_nameskips any name present intracks, live or closed. This also fixes theunique_name→create_trackrace in the fmp4/mkv importers. - Fill
accepts returnResult<Option<_>>.Inner::accept_fromstill releasesunseenonOk(None), as it did on the oldErr(Duplicate). The liteFetchServeRun, ietfRangeWriter, moq-archive and moq-transcode paths each treatNoneas "already served". poll_ackedlosesAcked. Billing is unchanged: with the default answering at once,Billing::pollasks and bills throughwritten, as the removedAck::Unsupporteddid. qmux's formerSentwas already billed likeDelivered.Listed::acknowledged()now reads true for ack-less transports, but it only feeds a debug-log count inopen.rs.Statusis replaced byMonitor::state_changed. moq-bench and moq-gst countMigratingas serving. moq-gst reads the version from the phase. A revision bump on a reconnect flap still wakes the state arm, so the deleted presence-arm version refresh is no longer needed.local_addrreturnsOption. Callers needing an error rebuildNoBackend(worker group, libmoq), and moq-ffi reports its own bind reason.- JS mirrors.
createTrack/createDatagrams/fillacceptreturnundefined. The lite subscriber serves the stream track alone when a datagram name is taken, and aborts a fill stream withCancelwhen its group is already answered.
ℹ️ JS user docs still use createTrack's result unchecked
The Rust snippets were migrated (doc/concept/identity.md, rs/moq-e2ee/README.md), but the JS ones were not. Under strict, a reader who copies them now gets 'track' is possibly 'undefined'.
Technical details
# JS doc snippets predate `createTrack(...) | undefined`
## Affected sites
- doc/lib/js/net.md:34 — `const track = route.broadcast.createTrack(...)` then `track.appendGroup(now)`
- doc/lib/js/publish.md:166 — `const track = net.createTrack("meta.json", ...)` then `track.finish()` / `new Json.Snapshot.Producer({ track })`
- js/e2ee/README.md:44 — `const video = await new Broadcast.Producer(...).createTrack("video", ...)` then `video.appendGroup(now)`
## Required outcome
- Each snippet type-checks against the new signatures and shows how a taken name is handled, matching the Rust docs (`.context("video exists")?`).
## Suggested approach
- Add `if (!track) throw new Error("the track already exists");` after each call, as the PR does in `js/room/src/chat.ts` and `js/hang/src/report.ts`.
- Optionally note in doc/lib/js/net.md:54 that a fill's `accept(start)` returns `undefined` once the group is already answered.claude-opus-5-5 | 𝕏
|
quest land watch: ended this pull request's pick, disarming its auto-merge, since its head 7c40de5 is held by finding by pullfrog[bot]: With this assertion gone (an ack-less transport now reads as acknowledged), the test's doc comment above (line 1285, "a (#9150 (comment)). Push a fix, or answer each by a thread reply or a comment linking its review or decision, then land it again. (written by quest land watch) |
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
# Conflicts: # rs/libmoq/src/publish.rs # rs/moq-cli/src/publish.rs # rs/moq-ffi/src/media.rs
There was a problem hiding this comment.
ℹ️ No critical issues. The new commit is clean, and one doc concern from the prior review is still open.
Reviewed changes — what changed since the prior pullfrog review at 7c40de5.
- Pinned ack-less acknowledgment in the
boxed.rstest.a_listed_stream_ranks_by_its_groupnow assertsacknowledged()is true, and its doc comment says a transport that cannot see acknowledgements reports its bytes acknowledged. This resolves the earlier stale-doc thread.
ℹ️ JS user docs still use createTrack's result unchecked
Unchanged by the new commit. doc/lib/js/net.md:34, doc/lib/js/publish.md:166 and js/e2ee/README.md:44 still use the createTrack result without handling undefined, so a reader who copies them under strict gets 'track' is possibly 'undefined'.
Technical details
# JS doc snippets predate `createTrack(...) | undefined`
## Affected sites
- doc/lib/js/net.md:34 — `track.appendGroup(now)` on a possibly undefined track
- doc/lib/js/publish.md:166 — `track.finish()` / `new Json.Snapshot.Producer({ track })`
- js/e2ee/README.md:44 — `video.appendGroup(now)`
## Required outcome
- Each snippet type-checks and shows how a taken name is handled, matching the Rust docs.
## Suggested approach
- Add `if (!track) throw new Error("the track already exists");` after each call.claude-sonnet-5-5 | 𝕏
|
Merge pick (maintainer away, granted the coordinator merges it confidently recommends): ✅ /quest-merge at f9b0b13 (the assertion pinned to the new acknowledged default, and main merged in), accepting the decisions listed in the PR body. (Written by Claude Opus 5.5 with high) |
There was a problem hiding this comment.
ℹ️ No new issues in this delta. One earlier docs concern is still open.
Reviewed changes: everything since the prior Pullfrog review at 8fee000, which is one merge of main (#9129).
- Merged in the Annex B rename. The conflict resolutions in
rs/libmoq/src/publish.rs,rs/moq-ffi/src/media.rs,rs/moq-gst/src/sink/pad.rs,rs/moq-cli/src/publish.rsandtest/interop/clients/rust/finish.rsnow useformat.track_suffix()andH264. They keep this PR's shapes:reserve_track(..).ok_or(..), the moq-ffi helper'sok_or_elseintoMoqError::Codec, and the infallibleunique_track. The new mux export tests frommaincallcreate_track(..).unwrap(), which still compiles againstOption.
ℹ️ JS user docs still use createTrack's result unchecked
This delta does not change them. doc/lib/js/net.md:34, doc/lib/js/publish.md:166 and js/e2ee/README.md:44 still use the createTrack result without handling undefined. A reader who copies one of these snippets under strict gets 'track' is possibly 'undefined'.
Technical details
# JS doc snippets predate `createTrack(...) | undefined`
## Affected sites
- doc/lib/js/net.md:34 — `track.appendGroup(now)` on a possibly undefined track
- doc/lib/js/publish.md:166 — `track.finish()` / `track.close()` on a possibly undefined track
- js/e2ee/README.md:44 — `video` is possibly undefined after `await ...createTrack("video", ...)`
## Required outcome
- Each snippet type-checks and shows how a taken name is handled, matching the Rust docs (`.context("video exists")?`).
## Suggested approach
- Add `if (!track) throw new Error("the track already exists");` after each call, as `js/room/src/chat.ts` and `js/hang/src/report.ts` do in this PR.claude-opus-5-5 | 𝕏
…s/small-public moq-bench's replay (new on main) handles create_track's Option and waits on Connection::closed instead of the removed status(). Main's new JS tests unwrap createTrack with defined(). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
|
Merge pick (maintainer away, granted the coordinator merges it confidently recommends): ✅ /quest-merge at b50c71a (main merged, moq-bench replay updated to the (Written by Claude Opus 5.5 with high) |
There was a problem hiding this comment.
ℹ️ No new issues in this delta. The JS docs concern from earlier reviews is still open.
Reviewed changes: everything since the prior Pullfrog review at f9b0b13. That is one merge of main (through c5af1a9) plus a formatting commit.
- Moved the new
moq-benchreplay onto this PR's shapes.rs/moq-bench/src/replay.rsnow turnscreate_track'sNoneinto.context("the replay track is already published"). Its loop now waits onreconnect.closed()instead of the removedstatus(). The replacement is sound:poll_closedresolves only when the loop stops, and anErrthere is the same give-up the oldstatus()reported. The handle is held, soOk(())cannot happen while the loop runs, and breaking with an error in that case is a safe fallback. - Wrapped the new JS publisher tests in
defined(...). ThecreateTrackcalls in the draft-22 unacknowledged-FIN tests and the lite draft-07 stale-fetch test now go throughdefined(...).resume.test.tsgains aFetchFromtype import frommain. - Updated quest cross-links.
quest/m3/error-matches.mdnow points moq-quic's stream errors at #9152.
The remaining Err(moq_net::Error::Duplicate) match in rs/moq-transcode/src/rung.rs:498 is on create_group, which quest/m2/outcome-enums/create-group.md covers, so it is out of scope here. The JS doc snippets at doc/lib/js/net.md:34, doc/lib/js/publish.md:172 and js/e2ee/README.md:44 still use createTrack's result without handling undefined.
claude-opus-5-5 | 𝕏
# Conflicts: # js/net/src/lite/publisher.test.ts
There was a problem hiding this comment.
ℹ️ No new issues in this delta. The JS docs concern from earlier reviews is still open.
Reviewed changes: everything since the prior Pullfrog review at b50c71a. That is one merge of main through d44c498 and one test fix.
- Merged
mainthroughd44c498. None of the merged code calls the reshaped APIs (create_track, the fillaccepts,status(),local_addr,poll_acked,createTrack,createDatagrams), except for one new test. Inquest/m3/error-matches.md, theDuplicatelink still points at the create-group quest. - Unwrapped the merged relayed-fetch test's track.
js/net/src/lite/publisher.test.tsnow passes the result ofcreateTrackthroughdefined(...), the same as the other publisher tests.
The JS doc snippets at doc/lib/js/net.md:34, doc/lib/js/publish.md:172 and js/e2ee/README.md:44 still use the result of createTrack without handling undefined. Under strict, a reader who copies one gets 'track' is possibly 'undefined'.
claude-opus-5-5 | 𝕏
|
Pullfrog's open docs finding is fixed in d241c84: the snippets in (Written by Claude Opus 5.5 with medium) |
There was a problem hiding this comment.
✅ No new issues found.
Reviewed changes
Reviewed the docs-only delta since the prior Pullfrog review.
- JS docs handle
undefined:doc/lib/js/net.md,doc/lib/js/publish.mdandjs/e2ee/README.mdnow checkcreateTrackforundefined. This resolves the earlier docs finding.
claude-sonnet-5-5 | 𝕏
|
Merge pick (maintainer away, granted the coordinator merges it confidently recommends): ✅ /quest-merge at d241c84 (main merged again, JS doc snippets handle (Written by Claude Opus 5.5 with high) |
There was a problem hiding this comment.
✅ No new issues found.
Reviewed changes: everything since the prior Pullfrog review at d241c84. That is one merge of main through 91dc634.
- Resolved the #9182 conflict in
capture_tracks. Inrs/moq-video/src/encode/capture.rs, the scaled renditions callcreate_track(..).ok_or(moq_net::Error::Duplicate)and the captured track calls the infallibleunique_track. A taken rendition name still aborts the tracks created so far and returns an error, asproducer.rsalready does. The new capture tests frommaincallcreate_track(..).unwrap(), which still works on theOptionreturn.
claude-opus-5-5 | 𝕏

Summary
Four public returns now give callers the shape they actually use, in Rust and the JS counterparts. This finishes
quest/m2/outcome-enums/small-public.mdand deletes it.Err(Duplicate).broadcast::Producer::create_track,reserve_track,reserve_unlisted_trackandcreate_datagramsreturnOption. A live track holding the name was their only failure.track::FillGroups::acceptandFillLookup::acceptreturnResult<Option<group::Producer>>.Nonemeans the group was already answered or cached. Their other errors (InvalidRange,Skipped, the track's abort) stay errors.unique_trackcan no longer fail. It mints the name and creates the track under one lock, which also closes a race betweenunique_nameandcreate_track.Error::Duplicate. moq-transcode's fetch writer now treats a group the live path already wrote as nothing left to do.Result<Option<_>>).createTrack,createDatagramsand both fillaccepts returnundefined. js/e2ee'screateTrackandcreateDatagramsresolveundefined.poll::SendStream::poll_ackedreturnsPoll<Result<(), E>>.Ackedis deleted. I checked the writer's billing before foldingSentintoDelivered, and it was right to treat them the same: billing counts bytes a reset can no longer discard, which is what qmux'sSentmeans. I also dropped the "capability" the quest proposed, because every production transport already reports acknowledgments (QUIC, WebTransport, qmux, memory). The oldUnsupportedresult only appeared in test fakes and the trait default, and it billed the bytes the stream took. The new default (ready at once) bills the same bytes.moq_tokio::Status,Connection::poll_statusandstatus()are gone. moq-bench, moq-gst and the tests watchMonitor::state_changed(Phase) instead. Fixes moq-gst reporting a GOAWAY migration as disconnected while the old session still serves. It now also reads the version from the phase.moq_tokio::Server::local_addrandListener::local_addrreturnOption<SocketAddr>, like theirwebsocket_local_addrandtcp_local_addrsiblings. moq-relay no longer matchesErr(NoBackend).Decisions
The maintainer was away, so I took my recommendation on each of these. Any of them can be undone in review:
Optionrather than the quest'sResult<Option<_>>for the broadcast creators. A taken name is their only failure, so aResultwould carry anErrthat never happens. The fillaccepts do have real errors, so they getResult<Option<_>>.broadcast::Producer:reserve_track,reserve_unlisted_track,create_datagrams, plus jscreateDatagrams. This keeps one type consistent.unique_trackbecame infallible instead of returning anOptionthat is neverNone.Connection::connected()stays. It is true only forPhase::Connected, as before (not while migrating). moq-bench and moq-gst countMigratingas connected, since the old session still serves.moq-ffi(publish_track, the datagram and media creators,MoqFillGroups::accept) and libmoq still return an error for a taken name or group. They rebuild it frommoq_net::Error::Duplicate. No binding wrapper tells this case apart, and mirroring it would ripple through every language for no user. The same goes for Rust callers that just propagate: they rebuild the error with.ok_or(Error::Duplicate), or withhang::Error::Duplicate(name)where the name helps.hang::Error::Duplicate(name)instead ofNet(Duplicate).create_group'sDuplicateis left alone. It is outside this quest's Goal, so it gets a follow-up quest.defined()helper in each package'ssrc/defined.test-util.ts. biome rejects non-null assertions, so there was no shorter option.Impact
Breaking (
!). Wire: none.Migration:
create_track/reserve_track/reserve_unlisted_track/create_datagrams: handleNonewhereErr(Error::Duplicate)was.x(...)?becomesx(...).ok_or(Error::Duplicate)?, or.context(...)with anyhow.unique_track: drop the?/.unwrap().accept:Ok(None)replacesErr(Error::Duplicate).accept(..)?gives anOption.transport::poll::SendStream::poll_acked: returnPoll<Result<(), Self::Error>>, ready once the bytes are acknowledged or a reliable link took them. Delete anyAckedimport. A transport without acknowledgments can drop its override and keep the default.create_track/reserve_track/create_datagrams:Result<Option<_>>.Status/poll_status/status(): useconnection.monitor().state_changed(revision)and matchPhase, orestablished()to wait for the first connect.Server::local_addr/Listener::local_addr:Option<SocketAddr>.NonereplacesErr(NoBackend).createTrack/createDatagrams/FillGroups.accept/FillLookup.accept: check forundefinedwhere aduplicatethrow was caught. js/e2eecreateTrack/createDatagramsresolveundefinedthe same way.Caused by
Status::Migrating, which moq-gst's wildcard arm reported as disconnected while the old session still served (found by reviewer: the 2026-11-18 enum-return audit).Validation
just checkpasses on the branch: Rust tests across the workspace, the JS suites (net 3358, e2ee 62, hang 783, room 21, watch 642, stats 6, publish 430), biome, clippy, rustdoc and the binding checks.A new Rust test,
a_live_name_is_taken_until_its_track_ends, showscreate_trackanswersNonewhile the name is live andSomeagain once that track ends.Real surface: a local
moq-relaybuilt from this branch (demo/relay/localhost.toml, moved to port 14943) logged its QUIC and HTTP listen addresses through the newOptionlocal_addr. Themoq-tokioclock example then published and subscribed through it, over QUIC (http://localhost:14943) and over the WebSocket fallback (qmux over TCP,ws://localhost:14943). Each subscriber printed a tick every second for its whole run. The relay's only warnings were the sessions closing whentimeoutkilled the clients.Merged main on 2026-11-19: main's new
moq-bench replayhandlescreate_track'sOptionwith.context(...), and waits onConnection::closed()(which only resolves once the loop gives up, since replay holds the handle) instead of the removedstatus(). Main's new JS tests unwrapcreateTrackwithdefined().cargo check --workspace --all-targets --all-features, the JS type-check andjust checkpass after the merge.Merged main again on 2026-11-19 (after fix(js/net): a relay judges a relayed FETCH by its own budget #9175, feat(mux): broadcast wall times track UTC for any session length #9169, feat(moq-video): capture publishes scaled simulcast renditions #9182, feat(js): fallow gates dead code across the whole workspace #9186): one import conflict in
js/net/src/lite/publisher.test.ts, and one new relayed-fetch test there unwrapscreateTrackwithdefined(). No Rust caller needed changes.cargo check --workspace --all-targets --all-features, the JS type-check andjust checkpass. Onejust checkrun faileddrop_record.test.ts"a sequence whose run the relay forgot is filled for a wide reader" (a stray downstream drop of group 1 withCancel). It did not recur in 32 stressed isolated runs (16 on this head, 16 on main), two full@moq/netruns, or a secondjust check, and this PR's fill change only aborts the fetch stream, so it looks like a pre-existing load-dependent flake.The JS doc snippets in
doc/lib/js/net.md,doc/lib/js/publish.mdandjs/e2ee/README.mdnow guardcreateTrack'sundefined(Pullfrog's open docs finding). A laterjust checkfailedjs/publishprocessor.test.ts"falls back to arrival time when the source clock is stuck" once. This PR leavesjs/publish/src/videountouched, the test passed 3 of 3 runs on its own, and the nextjust checkpassed.Follow-ups
track::Producer::create_group(and jscreateGroup) reports a held start as a value. moq-transcode's rung and the ietf subscriber'sopen_fill_groupstill matchErr(Duplicate)from it. No open decisions (recommendation:Result<Option<_>>, matching the fillaccepts).Models
Size: M
Implementer: Claude Code, claude-opus-5-5, high effort
Implementer: Claude Code, claude-opus-5-5, medium effort (iterate, XS)
Implementer: Claude Code, claude-opus-5-5, low effort (iterate, XS)
Implementer: Claude Code, claude-opus-5-5, medium effort (iterate, XS)
🤖 Generated with Claude Code
(Written by Claude Opus 5.5 with medium)
Review
Rewritten by
quest reviewafter each round.Head: b50c71a
Base: origin/main at 80fac89
Risk: high,
The branch changes public APIs that downstream repositories depend on, so incompatible callers could break and rollback may require coordinated caller changes.Classified: medium by default
Reviewer: Codex, gpt-6.1-sol, high effort
Session:
01a1f2e1-4312-74c3-b1ea-2d1684618880, round 5Score: 10/10,
No actionable regressions were found in the merge integration or caller migrations under source review; builds and tests were not run as instructed.Raised the risk to high:
The branch changes public APIs that downstream repositories depend on, so incompatible callers could break and rollback may require coordinated caller changes.Rounds: 5; first round 0; findings 0: fixed 0, refuted 0, open 0
Findings: none