feat(net)!: simplify origin scoping

[kixelated]

Problem

Origin construction and scoping require repetitive setup, expose the hop through deref, and collapse authorization and routing failures into ambiguous Option/Unroutable results. Broadcast metadata also carries an origin identity it does not use.

Approach

• make the origin hop, cache policy, scope root, and scope patterns explicit
• combine rooting and narrowing into one fallible scope(root, patterns) operation
• separate broadcast cache metadata from origin identity
• migrate every in-repository Rust consumer and the native-JavaScript smoke client
• add regressions for scoped wildcard authorization, default hop generation, publishing, and the cross-language client matrix

Impact

Public Rust API in moq-net:

• Breaking: origin::Config::id is hop; Config::default() now mints a nonzero random hop; origin Producer/Consumer expose hop() instead of dereferencing to Hop.
• Breaking: origin::{Producer,Consumer}::scope(root, patterns) -> Result<_, Error> replaces scope(patterns) -> Option<_> plus with_root. Empty/disjoint grants return Unauthorized; excessive rooting returns BoundsExceeded.
• Breaking behavior: requesting a path outside the consumer's own scope returns Unauthorized. A path allowed by that scope but excluded by the available server route remains Unroutable.
• Breaking: origin::Pending is origin::Requesting.
• Breaking: broadcast::Info no longer contains origin::Config; it directly exposes pool, cache_duration, and path.
• Additive: origin::Producer::publish(path, route) creates and advertises a broadcast together.

Public Rust API in moq-tokio:

• Breaking: origin::spawn(config_or_hop) becomes zero-argument origin::spawn(); explicit configuration uses origin::spawn_config(config).
• Additive: Client::with_origin and Server::with_origin use one shared origin for publishing and subscribing.

The FFI ABI is unchanged; its Rust implementation is migrated to the new origin API. The native-JavaScript smoke-client edit only migrates an in-repository consumer to the already-released @moq/net object-style connection/origin API.

Wire encoding and message schemas are unchanged. Random Rust hop IDs now use the full legal 62-bit wire range. Current supported @moq/net clients decode hops as bigint/u62 and interoperate. Retired u53-only @moq/lite clients can reject a hop above Number.MAX_SAFE_INTEGER and close the session; those clients must upgrade.

This final prerelease pass intentionally lands the breaking API cleanup on main per maintainer direction.

Validation

• focused four-version wildcard scope regression: 4 passed
• nix develop --command just check: passed
• nix develop --command just test: JavaScript passed; Rust 4,211 passed; Python 64 passed
• SMOKE_PORT=4590 nix develop --command just test smoke-full: all 32 Rust/Python/Go/JavaScript/C/GStreamer publisher-subscriber combinations passed
• nix develop --command bunx biome check test/smoke/clients/js-native/subscribe.ts: passed

Alternatives

Compatibility shims would preserve two construction and scoping idioms immediately before the release. The old shapes are removed directly so authorization failures and rooted scopes have one representation.

Follow-ups

• downstream Rust consumers must migrate to the new signatures
• deployments still using u53-only @moq/lite must upgrade before consuming full-width random Rust hops

(written by GPT-5)

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Advanced

Run ID: 0bd11678-a5a5-44e9-82e4-977392f86d27

📥 Commits

Reviewing files that changed from the base of the PR and between 84545f7 and 15f6a22.

📒 Files selected for processing (2)

• quest/m1/api-review-gate.md
• rs/moq-ffi/src/origin.rs

💤 Files with no reviewable changes (1)

• quest/m1/api-review-gate.md

Included review availability: Your plan provides up to 4 included reviews per hour; 1 remains after this review.

---

Walkthrough

The pull request refactors the origin API. Default origin creation now mints a hop, explicit configurations use spawn_config, and origin handles expose hop(). Scoping accepts a root and patterns and returns Result. Publishing can create and announce a broadcast in one call. Broadcast cache metadata and request types move to new fields and names. Callers, tests, examples, changelogs, and quest documentation are updated.

Priority: ➖ Normal

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly identifies the main change: simplifying origin scoping. It is concise and relevant to the breaking API cleanup.
Description check	✅ Passed	The description accurately explains the origin API, scoping, authorization, metadata, migration, and validation changes. It is directly related to the changeset.
Docstring Coverage	✅ Passed	Docstring coverage is 84.88% which is sufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 172 functions across 50 files.
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.

✨ Finishing Touches

✨ Simplify code

• Commit to this branch
• Create a new PR

---

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

[moq-bot]

1. Breaking API in published crates targets main; retarget to dev (rs/moq-net/CHANGELOG.md:20, rs/moq-tokio/CHANGELOG.md:13, AGENTS.md#Development). Retarget PR to dev and rebase; moq-net 0.2.22 and moq-tokio 0.19.11 are not 0.0.x exempt.
2. Duplicate changelog section splits new API (rs/moq-tokio/CHANGELOG.md:15, AGENTS.md#Required). Merge the two ### Added blocks into one.
3. Breaking renames lack markers while neighbors have them (rs/moq-net/CHANGELOG.md:24, AGENTS.md#Public API). Add [**breaking**] to origin::Info to Config, write_datagram to insert_datagram, and Timescale From removal lines.

Verdict: request changes
(Written by Muse Spark)

opencode session  |  github run

[kixelated]

Addressed the prior review findings on the rebased head:

• merged the duplicate moq-tokio changelog section
• marked the identified breaking changes
• corrected scoped wildcard expectations to distinguish Unauthorized from Unroutable and verified all four protocol cases
• documented full-width hop compatibility: current @moq/net is u62/bigint; legacy u53-only @moq/lite must upgrade
• migrated the native-JavaScript smoke client missed by feat(net): simplify JavaScript API #3815; all 32 smoke-full combinations now pass

The PR remains on main under the explicit maintainer direction for this final prerelease pass.

(written by GPT-5)

[moq-bot]

1. Breaking moq-net/moq-tokio API targets main; retarget to dev (rs/moq-net/CHANGELOG.md:25, AGENTS.md#Development). Retarget PR to dev and rebase onto origin/dev.
2. README references removed with_root / scope split (rs/moq-rtmp/README.md:66, AGENTS.md#Required). Update comment to scope(root, patterns).
3. Rust mints full 62-bit hops while JS caps generation at 53 bits (js/net/src/hop.ts:63, AGENTS.md#Cross-Package Sync). Lift randomHop to 62 bits or gate Rust Hop::random; confirm legacy client plan.

Verdict: request changes
(Written by Muse Spark)

opencode session  |  github run

[moq-bot]

1. Comment still names removed with_root / scope split (rs/moq-rtmp/README.md:66, AGENTS.md#Required). Change to scope(root, patterns).
   Verdict: request changes
   (Written by Muse Spark)

opencode session  |  github run

[moq-bot]

1. Published breaking API targets main; retarget to dev (rs/moq-net/CHANGELOG.md:25, AGENTS.md#Development). Retarget PR to dev and rebase onto origin/dev.
2. Comment names removed with_root / scope split (rs/moq-rtmp/README.md:66, AGENTS.md#Required). Change to scope(root, patterns).

Verdict: request changes
(Written by Muse Spark)

opencode session  |  github run

[kixelated]

Merged after rebasing onto #3819 and validating the release interaction.

Changes completed:

• fixed the four wildcard-scope authorization regressions so paths outside the client grant are Unauthorized, while server-excluded paths remain Unroutable
• added deterministic regression coverage for those cases
• corrected duplicate and missing breaking-change markers in the Rust changelogs
• preserved refactor(net): expose route cost fields #3802 route-cost fields and feat(libmoq)!: finalize release API #3819 lifecycle cleanup through the rebases
• documented the exact public API migration and the hop-width compatibility boundary: current @moq/net clients decode full u62 values, while retired u53-only @moq/lite clients may reject hops above Number.MAX_SAFE_INTEGER

Validation on head 15f6a22b6:

• just check
• just test (4,212 Rust tests, 64 Python tests, affected JavaScript suites)
• just test smoke-full (32/32 cross-language combinations)
• just test smoke-media (media lifecycle and control cases)
• fresh GitHub Check, Test, OBS, Swift, WASM, and review gates

Squash merge: 14be99999b7ab0a10aab32d3da6f7ac6c889fe17

(written by GPT-5)