feat(relay): add --cluster-id to set a fixed origin id

[kixelated]

Summary

A relay previously always generated a random origin id on startup (Origin::random()), so it looked like a brand-new node to the cluster after every restart. There was no way for an operator to assign a stable identity.

This adds a cluster.id config field (--cluster-id / MOQ_CLUSTER_ID) to pin the relay's origin/hop id across restarts. The origin id is the value a relay adds to a broadcast's hop list for loop detection and shortest-path routing.

[cluster]
id = 12345

Behavior

• Unset (default): unchanged — a fresh random id per start.
• Set to a valid value (1 .. 2^62): used verbatim as the origin id.
• Reserved (0) or out of range (>= 2^62, the wire varint limit): errors at startup (Cluster::new returns Err), rather than producing an unencodable hop id.

Keep an explicit id below 2^53 if older @moq/lite browser clients connect, since they decode hop ids as a u53; this is documented but not enforced.

Typed as Option<u64> per the repo's config-flag convention so an absent CLI flag doesn't clobber a TOML-configured value during the merge re-parse.

Public API changes

• ClusterConfig gains a pub id: Option<u64> field. ClusterConfig is #[non_exhaustive] with a Default, so additive.
• Cluster::new signature changes from -> Self to -> anyhow::Result<Self> so an invalid id fails loudly. Technically breaking for the (in-repo only) callers; all call sites updated.

Files

• rs/moq-relay/src/cluster.rs: new id field; Cluster::new validates it and returns Result.
• rs/moq-relay/src/main.rs: propagate the new Result.
• rs/moq-relay/src/config.rs: regression tests for the clap+TOML clobber and CLI-override paths.
• rs/moq-relay/tests/smoke.rs: updated for the new Result.
• doc/bin/relay/cluster.md: new "Origin id" section (Cross-Package Sync).

Test plan

• cargo test -p moq-relay — all pass, including new tests (cluster_id_sets_origin, cluster_id_out_of_range_errors, cli_does_not_clobber_toml_cluster_id, cli_flag_overrides_toml_cluster_id)
• cargo clippy -p moq-relay clean (via nix)
• cargo fmt --check clean (via nix)

Notes

Related to (but independent of) #1785, which caps the randomly generated id at 53 bits for the same @moq/lite u53 compatibility reason. This PR lets operators set an explicit id.

(Written by Claude)

[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: 60ea8ca4-7457-4d68-b35f-ee6c3af41cf0

📥 Commits

Reviewing files that changed from the base of the PR and between 99ad693 and 9c6633f.

📒 Files selected for processing (4)

• doc/bin/relay/cluster.md
• rs/moq-relay/src/cluster.rs
• rs/moq-relay/src/main.rs
• rs/moq-relay/tests/smoke.rs

✅ Files skipped from review due to trivial changes (1)

• doc/bin/relay/cluster.md

---

Walkthrough

ClusterConfig.id gains a --cluster-id CLI flag with MOQ_CLUSTER_ID environment variable support and documented validity constraints. Cluster::new now returns anyhow::Result<Self> and derives the relay's origin hop id from config.id instead of always generating a random one: it returns an error for reserved (0) or out-of-range (>= 2^62) ids, and uses Origin::from(id) for valid ids. Unit tests cover both valid and invalid id paths. Regression tests in config.rs verify that TOML-configured cluster.id is not overwritten by the clap re-parse, and that an explicit --cluster-id flag correctly overrides TOML. Error propagation updates in main.rs and test initialization sites adapt to the new Result return type. Documentation describes the new cluster.id semantics for loop detection and routing.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately summarizes the main feature: adding a --cluster-id flag to allow operators to set a fixed origin id, which is the primary change across all modified files.
Description check	✅ Passed	The description comprehensively explains the motivation (random id on every restart), the new feature (--cluster-id flag), configuration options, validation rules, behavior, API changes, files modified, and testing performed.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.
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/relay-cluster-id

---

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