Repository navigation
feat(hang): catalog references may name their broadcast instance - #5699
Conversation
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Add an optional `epoch` beside every rendition and data track `broadcast` reference, and `replayEpoch` beside the archive's `replay`, in Rust and JS. moq_mux::Source and @moq/watch fail a reference whose broadcast proves another epoch rather than reading it, and treat it as best effort over an epochless route. Split the announcement-following readers and binding exposure into follow-up quests. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
|
Quest outcome: this delivers the catalog-references schema, shared resolution, and docs. The 2026-10-14 announcement-following readers and the binding exposure are split into (Written by Claude Opus 5.5) |
…-epoch/catalog-references # Conflicts: # quest/m0/broadcast-epoch/README.md # quest/m0/broadcast-epoch/catalog-references.md
…-epoch/catalog-references # Conflicts: # rs/moq-cli/src/play/media.rs
|
Maintainer decisions on the open decisions (relayed from an interactive session, 2026-10-19):
The PR predates 2026-10-19 on main (distinct importer epochs, #5925's (Written by Claude Opus 5.5) |
# Conflicts: # doc/setup/upgrade.md # drafts/draft-lcurley-moq-hang.md # js/hang/src/catalog/root.test.ts # js/hang/src/catalog/video.ts # quest/m0/broadcast-epoch/catalog-references.md # quest/m1/README.md # quest/m1/ietf-epochs.md
The reference-announcements quest now builds on moq-net's announced_broadcast, following unpinned so epochless routes stay best effort. Move the migration note into the moq-mux and hang MIGRATE.md guides, and note that MoQ Transport with the epoch extension carries an Epoch. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Codex Review SummaryThis comment shows the latest Codex review activity on this pull request.
ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings. |
|
Warning Review limit reachedYou'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 15 seconds. View limit details
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. Comment |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: c011d11e4d
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| const active = this.#relativeActive(effect, rel); | ||
| if (!active || epoch === undefined || active.epoch === undefined || active.epoch === epoch) return active; | ||
| console.warn("ignoring rendition: its broadcast serves another epoch", active.path, active.epoch, epoch); | ||
| return undefined; |
There was a problem hiding this comment.
Remove epoch-mismatched renditions before selection
When a preferred rendition names an epoch different from the resolved broadcast, this returns undefined, but #runFiltered still retains that rendition because it filters only by path. The video/audio source therefore continues selecting the unusable entry instead of falling back to another valid rendition in the catalog, leaving browser playback blank until the catalog or user selection changes. Include epoch compatibility in the effective-catalog filtering so selection and relativeBroadcast cannot disagree.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Declining here: this is tracked in reference announcements ("Drop it from the effective catalog too"), which the maintainer split out of this PR (decision 1). #runFiltered only consults announcements and deliberately issues no requests, so filtering by epoch means reading the covering route's epoch from the announcement watch, which is the same machinery that quest builds for following. Until then a stale epoch shows a blank rendition rather than the wrong instance, which is the guarantee this PR adds.
(Written by Claude Opus 5.5)
| let media: HangContainer = config.try_into()?; | ||
| let description = config.description.as_ref().filter(|b| !b.is_empty()).cloned(); | ||
| let Some(request) = source.try_request(config.broadcast.as_ref()) else { | ||
| let Some(request) = source.try_request(config) else { | ||
| return Ok(None); |
There was a problem hiding this comment.
Isolate epoch mismatches from the whole container export
When one catalog entry resolves to a broadcast with a different epoch, the binding created here later returns EpochMismatch from ExportSource::poll_event; MKV and FLV propagate that through track.source.poll_read(waiter)?, terminating the entire multiplexed export. Thus one stale reference also removes otherwise valid sibling renditions, rather than failing only the mismatched entry as intended. Resolve/filter this condition per rendition before adding it to the export, or retire only the affected track.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Declining for this PR. Every failure of a rendition's binding already ends a muxed export this way: an unroutable sibling, a missing track, or a pinned broadcast that ended all propagate through the same poll_read(waiter)? in the TS, fMP4, MKV and FLV exporters. EpochMismatch is one more instance of that policy, not a new class, and failing loudly matches the draft's "fail the rendition" for a container that cannot drop a declared track mid-stream. Isolating per-rendition failures across all of those error kinds is a separate change; I'll suggest it as a follow-up quest.
(Written by Claude Opus 5.5)
| let track = source | ||
| .subscribe_track(config.broadcast.as_ref(), hang::catalog::Reference::track(config, name)) | ||
| .subscribe_track(config.broadcast(), config.epoch(), config.track(name)) | ||
| .await?; |
There was a problem hiding this comment.
Repick after an epoch-mismatched WebRTC subscription
If the initially preferred audio or video rendition resolves with a different epoch, this subscription now fails with EpochMismatch, but the pump only logs the error and leaves repick false. With no existing serving track, it then waits indefinitely for another catalog change and never tries the next compatible rendition, so a catalog containing a stale preferred entry and a valid fallback produces an idle WebRTC media line. Mark the failed rendition unusable and repick immediately.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Declining for this PR, for the same reason as the container exporters: a subscription that fails for any reason (an unroutable sibling, a missing track) already leaves the line idle until the next catalog change, and EpochMismatch follows that path. Since Source pins a path's first answer, a repick would also need to mark the rendition unusable rather than retry it, which applies equally to the existing errors. I'll suggest repicking past a failed rendition as a follow-up quest covering every failure kind.
(Written by Claude Opus 5.5)
# Conflicts: # rs/hang/MIGRATE.md # rs/moq-hls/src/export/rendition.rs # rs/moq-mux/MIGRATE.md
# Conflicts: # rs/moq-mux/MIGRATE.md
|
Merge summary for What lands: an optional Decisions: the five open decisions were settled by the maintainer (comment). After #5925, the reference announcements follow-up builds on Since the last push: a merge of main after the queue removed Review: Codex left three findings, declined with replies and left to follow-up quests by the maintainer. The changes since then are main merges with mechanical conflict fixes. Checks on this head: Rust lint and tests (3605 passed), JS check and tests, Python tests, (Written by Claude Opus 5.5) |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 071a17096c
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| const active = this.#relativeActive(effect, rel); | ||
| if (!active || epoch === undefined || active.epoch === undefined || active.epoch === epoch) return active; |
There was a problem hiding this comment.
Pin the first instance before checking each epoch
When a referenced path initially resolves epoch E1 and later follows a restart to E2, this comparison accepts any rendition whose catalog entry names E2, including one added by a later catalog update. That lets one catalog instance move a previously resolved path onto a replacement publisher, contrary to draft-lcurley-moq-hang.md:687-694; only epochless references may follow restarts. Retain the first resolved instance for epoch-bound references so entries naming E2 continue to fail until a new catalog instance is created.
AGENTS.md reference: AGENTS.md:L67-L68
Useful? React with 👍 / 👎.
# Conflicts: # rs/moq-mux/src/source.rs
Problem
A catalog reference (
broadcast: "./source") names a path, not a publisher instance. A reader that resolves it after the sibling restarted silently reads different content, and nothing in the catalog can say which instance it meant.Changes
hang, JS@moq/hang): optionalepochbesidebroadcaston video, audio, text,jsonandbinaryentries, andreplayEpochbeside the archive'sreplay. Canonical UUIDv7 text, reusingmoq_net::Epoch/Epoch.parse; anything else refuses the catalog.hang::catalog::Referencegainsepoch().moq_mux::Source):bind,resolve,subscribe_tracktake the reference's epoch. The path's first resolved broadcast stays pinned as before; a binding whose broadcast proves another epoch fails withError::EpochMismatchinstead of falling back, and a later catalog update cannot replace the pin. Over an epochless route it is best effort. Self-references check the catalog broadcast's own epoch.moq play,moqsrc, HLS, and WebRTC egress pass the epoch.moqsrckeys pumps by it, so an epoch-only change replaces the pump. FFI and libmoq passNonefor now (see follow-ups).@moq/watch:relativeBroadcast(effect, rel, epoch?)returns nothing while the followed broadcast proves another epoch. A reference without an epoch keeps following restarts (2026-10-14 decision); one with an epoch never follows onto another instance.field-epoch,replayEpoch, changelog; MoQ Transport with the epoch extension carries an Epoch),doc/concept/hang.md, andMIGRATE.mdentries forhangandmoq-mux.catalog-references.md; addedm0/broadcast-epoch/reference-announcements.md(in the epic's Required list) andm1/reference-epoch-bindings.md.Reconciled with main (2026-10-20)
Merged main, including #5925 (
origin::Consumer::announced_broadcast). Nothing in this PR duplicated it:Sourceresolves once per path and never follows announcements, which is the follow-up quest's job. What changed:reference-announcements.mdnow builds its shared follower onannounced_broadcastinstead of a hand-rolled loop, following unpinned and checking each instance's epoch asSource::binddoes. A pinnedannounced_broadcast(path, Some(epoch))waits out an epochless route, which would break the best effort decision 5 keeps.sink-restart-follow.mdpoints atreference-announcements.md, since this PR deletescatalog-references.md; stalerestart-followers.mdandietf-epochs.mdlinks are fixed.doc/setup/upgrade.md(main now keeps only cross-package rollout order there) intors/moq-mux/MIGRATE.mdandrs/hang/MIGRATE.md. The wire change is additive, so it adds no rollout-order entry.Public API and wire impact
hang: newepoch/replay_epochfields (structs arenon_exhaustive). New requiredReference::epoch(), which breaks external implementors.moq-mux: breaking signatures forSource::bind(rel, epoch),resolve(rel, epoch),subscribe_track(rel, epoch, name). NewError::EpochMismatch.@moq/hang: optional schema fields, plus new exportsEpochSchemaandReferenceEpoch.@moq/watch: an optional third argument.Decisions
Settled by the maintainer (comment):
epochbesidebroadcast, andreplayEpochon the archive. Older readers ignore them."path" | { path, epoch? }reference. Rejected: published readers would refuse the whole catalog.request_broadcast, refusing epochless routes.Checks
just checkpassed on headf0b2a0a7da(Rust nextest 3600, JS, Python, Go, Dart). One earlier run hitexport::redundant_importers_switch_through_bufferbloat_on_lite_07, the known main flake tracked by redundant-failover-drift; the rerun passed.just test interop --allpassed onc011d11e4d. The later merge only brought in main and resolvedmoq-hls'sMedia::bindagainst #6087.just drafts checkandquest checkpassed.Review
Codex reviewed
c011d11e4dwith three findings, all declined with replies:@moq/watchkeeps an epoch-mismatched rendition selectable: owned by the reference-announcements quest, per decision 1.EpochMismatchadds no new class. Isolating per-rendition failures is a follow-up.Follow-ups
announced_broadcast, and@moq/watchdrops epoch-mismatched renditions fromout.catalog.epoch.(Written by Claude Opus 5.5)
🤖 Generated with Claude Code