Skip to content

feat(moq-mux): a catalog update can be stamped at the caller's timestamp - #9281

Open
kixelated wants to merge 2 commits into
mainfrom
quest/m1/catalog-timestamp
Open

kixelated wants to merge 2 commits into
mainfrom
quest/m1/catalog-timestamp

Conversation

@kixelated

@kixelated kixelated commented Nov 21, 2026 •

Copy link
Copy Markdown
Collaborator

Lets moq-mux's catalog producer publish an update stamped at a media timestamp its caller gives, so a publisher whose catalog changes at a frame (a composition switching layout) gets hang and MSF output from one producer instead of hand-rolling a hang-only moq_json::snapshot::Producer.

Changes

  • catalog::Guard::set_timestamp(timestamp): the guard's publish stamps both the hang and MSF catalog groups at timestamp instead of the producer's clock reading.
  • A stamped publish whose timestamp does not pass the last published catalog on either track fails with TimestampRewind before either track is written; a commit refusal leaves the tracks open.
  • A stamped change withheld by the reservation gate keeps its timestamp for the initial publish.
  • Unstamped publishes behave as before (clock now, bumped a unit past the last start), so an estimate-driven republish after a stamped one still lands after it.
  • Fixed a misplaced doc comment: lists_track's doc sat on gate_opens.

Public API

Additive: moq_mux::catalog::Guard::set_timestamp. No wire change.

Decisions

Choices made without the maintainer (user away); each is reviewable:

  1. The timestamp is on the producer's clock (Producer::clock, advertised as sync.clock), as the quest recommended. Nothing validates it beyond ordering.
  2. A timestamp equal to or older than the last published catalog is refused (TimestampRewind), not bumped, as the quest recommended for older ones. Equal is refused too because a group start cannot repeat; batch edits at one frame into one guard.
  3. The API is a setter on the Guard (modify() then set_timestamp) rather than a new modify_at/mutate_at, following the no-foo_with_x rule. mutate stays unstamped.
  4. Risk to note: an estimate-driven republish (stamped at clock now) can land after a frame the caller is still about to stamp, making that stamp a rewind. The caller sees the error from commit; dropping the guard instead aborts the catalog, as for any failed publish.

Validation

  • New unit tests in rs/moq-mux/src/catalog/producer.rs: a stamped publish lands at the caller's timestamp on both tracks (ahead of the clock), a later unstamped one lands a unit after it, an equal or older stamp is refused with neither track written and the next stamp still goes out, and a stamp buffered behind a reservation stamps the initial publish.
  • cargo test -p moq-mux: 2139 + 20 passed.
  • just check: lint/fmt/doc and all non-test modules passed; its test rs stage hit 4 timeouts in unrelated codec::h264 tests, each logging mbx: waiting for machine-wide scheduler capacity (load from parallel agents); those tests pass in the cargo test -p moq-mux run above.

Follow-ups

None.

Models

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

Review

Rewritten by quest review after each round.

  • Head: 6311e8b

  • Base: origin/main at 3728b96

  • Risk: medium, The additive timestamp API changes catalog publication timing and rejection behavior for moq-mux callers and their consumers without changing the wire format; a revert fully undoes it.

  • Classified: medium by Codex, gpt-6.1-sol, low effort, session 01a1fc03-f224-79b3-a995-62417b4d3805

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

  • Session: 01a1fc04-06f9-77e2-862e-e70962dd9dd9, round 1

  • Score: 8/10, No actionable defects were found, and timestamp handling appears consistent across both outputs and buffered publication, but builds and tests were not run as instructed.

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

  • Findings: none

kixelated and others added 2 commits November 20, 2026 18:06
Guard::set_timestamp stamps the hang and MSF publish at a media timestamp on
the producer's clock, refusing one that does not pass the last publish.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@kixelated kixelated changed the title The catalog producer publishes at the caller's timestamp feat(moq-mux): a catalog update can be stamped at the caller's timestamp Nov 21, 2026
@kixelated
kixelated marked this pull request as ready for review November 21, 2026 02:52

@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.

Important

When the producer refuses a stamped change with TimestampRewind, the change still stays in the catalog. The next publish, from any caller, sends it at that publish's timestamp. That puts the change at the wrong time, which is exactly what the refusal is meant to prevent.

Approach: Sound. A per-guard setter that sends an optional stamp into Outputs::emit reuses start::after and keeps unstamped behavior the same. The weak spot is what happens to the catalog after a refusal.

Reviewed changes

I reviewed the whole diff: the new stamping API, how it interacts with the reservation gate, and the tests.

  • Guard::set_timestamp: the guard's publish stamps both catalog tracks at the caller's timestamp. A timestamp that does not pass the last group on either track is refused before either track is written.
  • Buffered stamp: Gate::Buffering gains at, which the reservation flush uses for the initial publish.
  • Unstamped path: this path is unchanged. It still stamps at clock now and bumps a unit past the newest start.
  • Tests: stamping both tracks, refusing an equal or older timestamp, and stamping a buffered initial publish.

Pullfrog  | Fix all ➔ | Fix 👍s ➔ | View workflow run | Using claude-opus-5-5 | 𝕏

///
/// The publish fails with [`TimestampRewind`](crate::container::TimestampRewind) unless
/// `timestamp` is past the last published catalog's, rather than reordering it.
pub fn set_timestamp(&mut self, timestamp: moq_net::Timestamp) {

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.

A refused stamp only fails commit. The guard has already written the change into state.catalog (and publish has set the gate to Published), so the next publish sends it anyway. That could be an estimate republish stamped at clock now, or the caller's next stamped change. In a_set_timestamp_that_does_not_advance_is_refused, the c publish at 61s also carries b60000 and b59000, so the change lands at a timestamp nobody picked. The guard holds the state lock, and every emit runs under that lock. So checking the stamp here, before any edits, is race-free and would let the caller find out without having changed the catalog.

Technical details
# A refused stamped change still reaches the wire with a later publish

## Affected sites
- rs/moq-mux/src/catalog/producer.rs:1197: `set_timestamp` can't fail, so the refusal only shows up in `emit`, after the catalog was already changed.
- rs/moq-mux/src/catalog/producer.rs:1231-1238: `publish` sets `gate = Published` and `anchored = true`, then `emit` refuses the stamp. The changed `state.catalog` stays in place.
- rs/moq-mux/src/catalog/producer.rs:2135: the test passes even though the refused renditions go out with `c`.

## Required outcome
- A stamp the producer refuses never puts its change on the wire at another timestamp. Either the caller learns of the refusal before changing anything, or a refused change is rolled back.
- The test asserts that the refused renditions are missing from the next publish.

## Suggested approach
- `pub fn set_timestamp(&mut self, timestamp) -> crate::Result<()>`: when the gate is `Published`, run `start::after` on `outputs.hang_track` and `outputs.msf_track` right away. The guard owns `&mut Outputs` and the lock, so the check still holds when `commit` runs. Keep the check in `emit` as a backstop, or drop it. Document that `set_timestamp` should come before any edits.

if let Gate::Buffering { pending, .. } = &mut self.state.gate {
if let Gate::Buffering { pending, at, .. } = &mut self.state.gate {
*pending = true;
*at = self.at;

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.

This overwrites the stored stamp with every withheld publish. Take a change stamped at 60s, then an unstamped change staged while the reservation is still held: the second one resets at to None. The initial publish then goes out at clock now, which can be before 60s. The layout change then takes effect before its frame. Keeping the stamp when the later change is unstamped (*at = self.at.or(*at)) avoids this. The unstamped edit then lands no earlier than its stamped neighbour, which matches how the published path bumps unstamped publishes past a stamp.

@coderabbitai

coderabbitai Bot commented Nov 21, 2026

Copy link
Copy Markdown
Contributor

Explain Change →

No actionable comments were generated in the recent review.

Walkthrough

Catalog publishing now supports an optional caller-supplied timestamp through Guard::set_timestamp. Explicit timestamps must advance past the latest publish on both catalog tracks. Without an explicit timestamp, publishing selects advancing timestamps for both tracks. The buffering gate retains the timestamp for the initial publish. Tests cover track timestamps, timestamp rewinds, and buffered publication. The proposal document was removed.

Merge Risk: Minimal · up to 6311e

This adds an optional timestamp for catalog publishes and rejects non-advancing timestamps before anything is written. Unstamped publishing behaves as before. No concrete merge-blocking risk was found.

Pre-merge checks: Passed 4

Check name Status Explanation
Title check Passed The title names the main change: a catalog update in moq-mux can be stamped at a caller-supplied timestamp. This matches the added Guard::set_timestamp API and the timestamp-aware emit logic in produc…
Description check Passed The description explains the new caller-supplied timestamp for the catalog producer, the Guard::set_timestamp API, refusal behavior with TimestampRewind, unstamped publish behavior, tests, and a doc c…
Linked Issues check Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check Passed Check skipped because no linked issues were found for this pull request.
Full details: Title check

Explanation

The title names the main change: a catalog update in moq-mux can be stamped at a caller-supplied timestamp. This matches the added Guard::set_timestamp API and the timestamp-aware emit logic in producer.rs.

Full details: Description check

Explanation

The description explains the new caller-supplied timestamp for the catalog producer, the Guard::set_timestamp API, refusal behavior with TimestampRewind, unstamped publish behavior, tests, and a doc comment fix. All of these relate to the changeset.

Finishing Touches

Simplify code

  • Commit to this branch
  • Create a new PR
  • 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

Recent review info

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: dc1925fd-9881-41bd-8496-e20fbb5f196d
Commits

Reviewing files that changed from the base of the PR and between 8f70734 and 6311e8b.

Files selected for processing: 2

  • quest/m1/catalog-timestamp.md
  • rs/moq-mux/src/catalog/producer.rs
Files with no reviewable changes: 1

  • quest/m1/catalog-timestamp.md

Included review availability: This review used your included allowance. Your plan provides up to 4 included reviews per hour; 1 remain after this review.

This branch has not been deployed

No deployments
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