moq-lite-05: REANNOUNCE, timestamps, and datagrams

[kixelated]

Summary

Three additions for moq-lite-05:

1. REANNOUNCE (atomic re-announcement)

A new restart (2) value for Announce Status on the existing ANNOUNCE message. Semantically equivalent to ended immediately followed by active for the same path, but signals that the broadcast was never actually unavailable — useful when only the origin or hop path changes (relay failover, upstream restart). The Hop ID list may differ from the prior announcement.

Alternation rules updated: a broadcast cycles ended ↔ (active|restart). A restart without a prior active is a protocol violation.

2. Timestamps and per-track timescale

Based on moq-dev/moq#1439.

• Publisher Timescale (i) added to SUBSCRIBE_OK. Units per second; 0 means unspecified. Fixed for the lifetime of the subscription.
• Timestamp Delta (i) prepended to every FRAME — zigzag-encoded signed delta from the previous frame's timestamp (first frame deltas from 0).
• Expiration is now timestamp-based when timescale is non-zero, falling back to wall-clock arrival time otherwise. This keeps expiration consistent across relays and unaffected by buffering/jitter.

3. QUIC datagram delivery

Based on moq-dev/moq#1374, but with a different shape per discussion: no separate DATAGRAMS control stream. A publisher MAY send any group as one QUIC datagram routed via the existing Subscribe ID, so datagrams and streams coexist on a single subscription.

Datagram body: Subscribe ID (i) | Group Sequence (i) | Timestamp (i) | Payload (b). Each datagram is a complete group with exactly one frame; not cached, not retransmitted. Total body capped at 1200 bytes to fit within the minimum QUIC path MTU without IP fragmentation — oversize payloads must be sent as a Group Stream instead. Subscribers must deduplicate by group sequence when receiving both delivery paths.

Open design choices worth a second look

• Status name restart vs reannounce — happy to rename.
• Datagram includes an absolute Timestamp (PR 1374 omits it) so timestamp-based expiration also works for datagram-only groups.
• No separate DATAGRAMS control stream / no per-subscription opt-out. Could add a SUBSCRIBE flag if subscribers need to refuse datagrams.

Test plan

• make draft-lcurley-moq-lite.txt builds cleanly.
• Cross-check wire formats against the moq-dev Rust implementation once Lite05 lands there.
• Working group review of the restart naming and the datagram-MTU cap.

🤖 Generated with Claude Code

[coderabbitai]

Warning

Review limit reached

@kixelated, we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 55 minutes and 26 seconds. Learn how PR review limits work.

Your organization has run out of usage credits. Purchase more in the billing tab.

⌛ How to resolve this issue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans include higher PR review limits than trial, open-source, and free plans. In all cases, reviews become available again over time. During sustained high-volume PR review activity, CodeRabbit may temporarily slow when the next review becomes available.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 75806512-1a6d-4836-be16-9e45f9a6158a

📥 Commits

Reviewing files that changed from the base of the PR and between 8353c2d and 3c92e4b.

📒 Files selected for processing (1)

• draft-lcurley-moq-lite.md

Walkthrough

This draft updates moq-lite's protocol semantics and wire format by introducing explicit per-frame timestamp support with Timescale-based expiration, adding datagram delivery as an alternative to stream-based group transport, and extending ANNOUNCE messaging with an atomic restart status. The Group and Frame model now allows groups to be delivered either over dedicated QUIC streams or as single unreliable QUIC datagrams with subscriber-side deduplication. Frames carry Timestamp Delta fields (zigzag varint relative to prior frame timestamp); when Timescale is 0 (unspecified), timestamps are treated as opaque and wall-clock timing is used for expiration instead. The SUBSCRIBE_OK message gains a Publisher Timescale field that remains fixed for the subscription lifetime. Appendix entries are updated to reflect these new features.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and specifically identifies the three main changes: REANNOUNCE (renamed from RESTART), timestamps, and datagrams support for moq-lite-05.
Description check	✅ Passed	The description is directly related to the changeset, providing clear explanations of the three protocol additions and their rationale.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
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.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

✨ Simplify code

• Create PR with simplified code
• Commit simplified code in branch claude/adoring-dijkstra-6a20e0

---

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

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 4

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@draft-lcurley-moq-lite.md`:
- Line 730: Replace the phrase "An application specific payload." with the
hyphenated compound adjective "An application-specific payload." — locate the
exact sentence in draft-lcurley-moq-lite.md (the line containing "An application
specific payload.") and update it to use the hyphenated form for consistency and
readability.
- Around line 390-393: The spec currently treats datagram field Timestamp=0 as
“unspecified,” which prevents representing a true absolute timestamp of value 0
for Tracks with non‑zero Timescale; update the Timestamp definition (the
datagram/field named "Timestamp" in the Track description) so that “unspecified”
is not conflated with the numeric zero—either make unspecified conditional on
Timescale=0 (i.e., if Timescale==0 then Timestamp MUST be 0 to mean unspecified)
or add an explicit validity flag/parameter (e.g., a TimestampValid bit)
alongside Timestamp to indicate whether the numeric value is meaningful; change
the prose and any examples to reflect the new rule and ensure all references to
Timestamp and Timescale in the document use the new semantics.
- Around line 472-476: Update the ANNOUNCE state-machine alternation rule so it
explicitly allows the `restart` status alongside `active` and `ended`: modify
the sentence that currently requires publishers to “MUST ONLY alternate ...
active to ended or vice versa” to mention `restart` (e.g., allow transitions
between `active`, `ended`, and `restart` or state that `restart` may replace an
`active` announcement atomically). Ensure references to `restart`, `active`, and
`ended` in the ANNOUNCE section and any normative MUST language are updated so
the rules are consistent with the `restart` definition in the `restart` (2)
paragraph.
- Around line 332-336: The expiration definition is ambiguous for Groups that
contain zero FRAME messages; update the text around the Group/Frame/Max Latency
explanation so that when a Group has no FRAMEs its “first frame” timestamp is
treated as the group arrival/queue time (subscriber arrival or publisher queue
time) for the purpose of computing the delta used by Track (respecting Track
negotiation of Timescale), i.e., if Timescale is non-zero but the group is
empty, fall back to arrival/queue time; ensure the new normative sentence
references Group, Frame, Max Latency, Track and Timescale and clarifies this
fallback rather than leaving it undefined or exempting empty groups.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 15a5e7d0-a2bf-456f-9add-608867a569c8

📥 Commits

Reviewing files that changed from the base of the PR and between 6cedca9 and 8353c2d.

📒 Files selected for processing (1)

• draft-lcurley-moq-lite.md