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]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: b94d9054-71f7-422e-93cc-18181979cf3f

📥 Commits

Reviewing files that changed from the base of the PR and between 8353c2d and 9ffd0a4.

📒 Files selected for processing (1)

• draft-lcurley-moq-lite.md

---

Walkthrough

This draft adds Qmux transport bindings and treats moq-lite as running on ordered, multiplexed, bidirectional stream-capable transports. Groups may be delivered over dedicated streams or as single unreliable datagrams; frames gain per-frame Timestamp and Duration tied to the Track Timescale (Timescale=0 falls back to wall-clock). Expiration uses timestamp deltas when Timescale is non-zero, otherwise uses wall-clock; empty groups always use wall-clock. A Datagrams section defines routing, datagram body encoding, deduplication, and a 1200-byte body limit. ANNOUNCE semantics and SUBSCRIBE_OK gain new fields and encoding rules.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title "moq-lite-05: REANNOUNCE, timestamps, and datagrams" directly summarizes the three main features added in this PR: REANNOUNCE/restart status, timestamp/timescale support, and QUIC datagram delivery.
Description check	✅ Passed	The description is comprehensive and directly related to the changeset, detailing all three major additions (REANNOUNCE, timestamps with timescale, and QUIC datagram delivery) and their implementations.
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