Repository navigation
docs(quest): plan the LAN app id, one LAN mesh, and the relay verb #3590
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Changes from all commits
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
This file was deleted.
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,57 @@ | ||
| # [S] LAN discovery app id | ||
|
|
||
| ## Goal | ||
|
|
||
| Two unrelated MoQ applications on one network never discover each other. Every | ||
| LAN advertisement names an application; a peer from another application is | ||
| never resolved or reported, and the membership proofs are bound to the | ||
| application, so one secret reused across two applications still yields two | ||
| meshes. moq-cli and moq-relay share one default, so they find each other with | ||
| no configuration. | ||
|
|
||
| Non-goals: hiding the record (mDNS is multicast in the clear either way) and | ||
| any change to how a discovered peer is dialed. | ||
|
|
||
| ## Plan | ||
|
|
||
| `rs/moq-tokio/src/mdns.rs` registers every process under one DNS-SD type, | ||
| `_moq._udp.local.`, and tells groups apart only after resolving, by whether the | ||
| HMAC proof verifies. Two applications with no secret therefore mesh with each | ||
| other, and two with different secrets still resolve and log every foreign | ||
| record. | ||
|
|
||
| - `mdns::App`: a newtype over 1..=62 lowercase ASCII letters, digits, and | ||
| hyphens, with `FromStr` and `Display`, refusing anything else at parse time. | ||
| 62, not 63: the subtype label is `_<app>`, and a DNS label holds 63 octets, | ||
| so the boundary test refuses a 63-character app rather than letting | ||
| registration fail later. | ||
| `impl Default` returns `default`, the name both binaries advertise under. | ||
| `Config::new(app, port)` replaces `Config::new(port)`; moq-tokio is | ||
| unpublished, so no shim. | ||
| - Partition: register the service under the DNS-SD subtype | ||
| `_<app>._sub._moq._udp.local.` (RFC 6763 section 7.1) and browse that | ||
| subtype, so the daemon only ever resolves this application's records. | ||
| mdns-sd 0.20 supports it: the subtype rides `ServiceInfo::new`'s type | ||
| argument and `browse` takes the same string. `_moq._udp` stays the parent | ||
| type, so `dns-sd -B _moq._udp` still lists every MoQ process on the network. | ||
| - Bind: `Identity` gains the app and both proofs cover it, so a record cannot | ||
| be replayed under another application's subtype and the same secret under | ||
| two apps never verifies. Extend `proofs_are_bound_to_one_listener`. | ||
| - Surfaces: moq-cli gains `--cluster-lan-app` (`MOQ_CLUSTER_LAN_APP`) beside | ||
| `--cluster-lan-secret` in `rs/moq-cli/src/cluster.rs`; moq-relay gains | ||
| `[cluster.lan] app` (`--cluster-lan-app`) in `LanConfig`. Both default to | ||
| `default` and document that an application built on the library picks its | ||
| own name. Update `doc/bin/relay/cluster.md` and `doc/bin/relay/config.md`; | ||
| `doc/bin/cli.md` does not mention `--cluster-lan` at all, so add the flags | ||
| there while reconciling against `--help`. | ||
| - Test: there is no mDNS test today. Add one that runs two `Discovery` | ||
| instances on the host under different apps and asserts neither reports the | ||
| other, then two under the same app and secret that do. Skip cleanly when no | ||
| interface can announce, the way `ANNOUNCE_TIMEOUT` already fails, so CI | ||
| without multicast stays green rather than silently passing. | ||
|
|
||
| Branch from `dev`; mDNS exists only there. | ||
|
|
||
| ## Related | ||
|
|
||
| - [One LAN mesh](/quest/m1/lan-mesh.md) - consolidates the flag surface this adds into the relay's `ClusterConfig` |
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,67 @@ | ||
| # [L] One LAN mesh | ||
|
|
||
| ## Goal | ||
|
|
||
| A `moq --cluster-lan` process and a `moq-relay` with `[cluster.lan]` on the | ||
| same network mesh with each other, in both directions, through one | ||
| implementation. A LAN peer authenticates with its mDNS credential and is never | ||
| handed `cluster.token`; the secret is optional for both, and without one the | ||
| mesh is open and documented as such. | ||
|
|
||
| ## Plan | ||
|
|
||
| Two meshes share the `_moq._udp` service today and cannot connect. The CLI | ||
| (`rs/moq-cli/src/cluster.rs`) advertises a fingerprint and no node, dials | ||
| `/.cluster/<credential>` with the fingerprint pinned, and attaches one | ||
| unauthenticated origin. The relay (`rs/moq-relay/src/cluster.rs`) always | ||
| advertises a node, skips any peer without one, dials the node URL with | ||
| `?jwt=<cluster.token>` under ordinary TLS trust, and never reads | ||
| `Peer::credential` or `Peer::fingerprint`. A CLI dialing a relay lands as an | ||
| anonymous client at the node URL and is refused unless `--auth-public` happens | ||
| to cover it. | ||
|
|
||
| One implementation: the relay's `Cluster`. | ||
|
|
||
| - moq-cli depends on the moq-relay library; its `cluster-lan` feature becomes | ||
| `moq-relay/cluster-lan`. `MoqSide.cluster` nests `moq_relay::ClusterConfig`, | ||
| so the CLI's `--cluster-*` flags are the relay's, LAN and WAN alike, and the | ||
| stages publish and subscribe on the cluster's origin (the one | ||
| [cluster construction](/quest/m1/cluster-construction.md) builds once). | ||
| Delete `rs/moq-cli/src/cluster.rs`. | ||
| - Advertise: the listener's fingerprint whenever its certificate was | ||
| generated, the node URL when one is configured, and at least one of them | ||
| (the `UnboundSecret` rule). A relay without `--cluster-node` advertises its | ||
| listen port, the way the CLI does, so the `--cluster-lan` needs | ||
| `--cluster-node` start-up check goes away. | ||
| - Dial: `Peer::urls()` in order, node first, on the path | ||
| `/.cluster/<credential>`, with the advertised fingerprint pinned. The lower | ||
| id dials. Never `?jwt=`; `cluster.token` is for static and gossip peers only. | ||
| The request path needs moq-lite-05 or any moq-transport version, so the | ||
| CLI's `validate_versions` moves with the dial. | ||
| - Accept: `Connection::authenticate` recognizes `/.cluster/<credential>`, | ||
| verifies it with `Discovery::verify_credential` (constant time), and grants | ||
| the cluster-peer scope a `cluster.token` would, recording the hop. Every | ||
| other path stays on the JWT, mTLS, and public-prefix path. A `/.cluster` | ||
| request on a relay without LAN discovery is refused, not routed. | ||
| - Secret: optional for the relay too, since a LAN dial no longer carries the | ||
| token; `doc/bin/relay/cluster.md` inherits the CLI's warning that an open | ||
| mesh admits anyone who can reach the listener. Drop the relay's | ||
| secret-required start-up check and reconcile | ||
| [cluster flags](/quest/m2/cluster-flags.md), which lists both removed checks. | ||
| - Docs: `doc/bin/relay/cluster.md`, `doc/bin/relay/config.md`, and the CLI | ||
| page describe one mesh; the CLI page names the WAN flags it gains. | ||
| - Test: an in-process test meshes a node-advertising cluster with a | ||
| fingerprint-advertising one and asserts a broadcast crosses in each | ||
| direction. A smoke recipe runs `moq import --cluster-lan` beside `moq-relay` | ||
| with `[cluster.lan]` and watches from the relay. | ||
|
|
||
| Branch from `dev`. | ||
|
|
||
| ## Required | ||
|
|
||
| - [LAN discovery app id](/quest/m1/lan-app.md) - the flag surface this consolidates includes `app` | ||
|
|
||
| ## Related | ||
|
|
||
| - [Cluster construction](/quest/m1/cluster-construction.md) - the origin the CLI's stages attach to | ||
| - [`moq relay`](/quest/m2/moq-relay-subcommand.md) - the second place the CLI hosts the relay library |
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,46 @@ | ||
| # [L] The CLI serves like a relay | ||
|
|
||
| ## Goal | ||
|
|
||
| The only difference between `moq` and `moq-relay` is that the relay listens by | ||
| default. A `moq --listen` session is authenticated (JWT, mTLS, or public | ||
| prefixes), scoped by its token, recorded as a hop, counted in stats, and | ||
| drained on shutdown, exactly as on a relay. The CLI's stages are a local | ||
| publisher and subscriber on that same origin. | ||
|
|
||
| ## Plan | ||
|
|
||
| Today `spawn_server`, `route_server`, and `spawn_serve` | ||
| (`rs/moq-cli/src/main.rs`) accept every request with `request.ok()`, attach | ||
| the process's single origin in whichever directions the stages use, and never | ||
| look at a path or token. The relay's `serve` and `Connection::run` | ||
| (`rs/moq-relay/src/relay.rs`, `connection.rs`) do everything listed in the | ||
| goal. Once [one LAN mesh](/quest/m1/lan-mesh.md) lands the CLI's origin is the | ||
| cluster's, so the relay's `serve` can take over the listener directly. | ||
|
|
||
| - Replace the CLI's three server helpers with `moq_relay::serve` over the | ||
| cluster, the auth, and the shutdown handle. `MoqSide` nests | ||
| `moq_relay::AuthConfig` and `StatsConfig`, so `--auth-*` and `--stats-*` | ||
| read the same on both binaries. | ||
| - Default grant: with no auth configured the CLI keeps what it gives today, an | ||
| open listener over the whole origin, spelled as the relay's public prefixes | ||
| covering the root. The relay's own default stays a refusal, since that is | ||
| its `no auth-key, auth-key-dir, auth-api, or public path configured` check; | ||
| the difference is the listening default this quest is about, and both defaults | ||
| are documented side by side. | ||
| - The Unix peer-credential gate on `--listen-unix-bind` and the certificate | ||
| endpoint `web::run_web` spawns for an explicit `--listen` survive, rehomed | ||
| on the relay's web server or kept as the CLI's, whichever leaves one copy. | ||
| - Drain: `moq import --listen` on SIGTERM sends GOAWAY and waits | ||
| `drain_timeout` like the relay, instead of dropping sessions. | ||
| - Docs: `doc/bin/cli.md` describes serving in the relay's terms and links the | ||
| relay's auth page rather than restating it. | ||
| - Test: an authenticated viewer with a scoped token sees only its root on a | ||
| `moq import --listen`, and an unscoped one is refused when a key is | ||
| configured; the existing unauthenticated import-to-export smoke keeps | ||
| passing with the default grant. | ||
|
|
||
| ## Required | ||
|
|
||
| - [One LAN mesh](/quest/m1/lan-mesh.md) - the CLI's origin becomes the cluster's | ||
| - [`moq relay`](/quest/m2/moq-relay-subcommand.md) - the CLI hosts the whole relay library |
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,49 @@ | ||
| # [S] Relay verb | ||
|
|
||
| ## Goal | ||
|
|
||
| `moq relay` runs the relay with exactly the flags, environment, and TOML | ||
| `moq-relay` accepts, and `moq-relay` stays published as its own minimal | ||
| binary: someone who only wants a relay does not download the capture, encode, | ||
| decode, and render stack. | ||
|
|
||
| ## Plan | ||
|
|
||
| The same shape `moq token` already uses: `moq-token-cli` is lib+bin, its | ||
| `Args` nested by moq-cli (`rs/moq-cli/src/main.rs`), its binary untouched. | ||
| `moq-relay` is lib+bin as well (`rs/moq-relay/Cargo.toml`), with a 15-line | ||
| `main.rs` that installs the aws-lc-rs provider, optionally jemalloc, and calls | ||
| `Relay::load(Config::load()?).await?.run()`. | ||
|
|
||
| - moq-cli gains a default-on `relay` feature depending on the moq-relay | ||
| library and a `Command::Relay(moq_relay::Config)` verb, answered before any | ||
|
Comment on lines
+18
to
+19
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Making Useful? React with 👍 / 👎. |
||
| transport binds like `token` and `completion`, with `MoqSide::reject` | ||
|
Comment on lines
+19
to
+20
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
When a user runs Useful? React with 👍 / 👎.
Collaborator
Author
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Fixed in e9b9dcd: the plan splits the TOML read and precedence merge out of (written by Claude Opus 5) |
||
| covering it. The relay's own features (`iroh`, `cluster-lan`, backends, | ||
| `websocket`) forward from the CLI's features of the same name. | ||
| - `Config::load` parses argv, reads the TOML `file` names, and merges the | ||
| layers in one step (`rs/moq-relay/src/config.rs`, `parse_and_merge`), so a | ||
| nested `Config` would carry only the flags and ignore its TOML. Split the | ||
| file read and precedence merge into a step that takes an already-parsed | ||
| `Config`, used by both `Config::load` and the verb, and test the same TOML | ||
|
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
The composable step must also settle logger ownership, not only merge TOML. AGENTS.md reference: AGENTS.md:L59-L59 Useful? React with 👍 / 👎. |
||
| invocation through both binaries. | ||
| - Move the provider install out of both mains into `Relay::load`, so an | ||
| embedder and the two binaries share one startup. jemalloc stays a | ||
| binary-level global allocator. | ||
| - `moq relay --help` renders the relay's whole tree under the verb; check the | ||
| spec dumps both binaries produce agree. | ||
| - Docs: `doc/bin/relay/` names both spellings once, `doc/bin/cli.md` gains the | ||
| verb, and the demo recipes keep using `moq-relay`. | ||
| - Test: `rs/moq-relay/tests/released_cli.rs` drives the binary; add a case | ||
| that runs the same smoke through `moq relay`. | ||
|
|
||
| Starts on `main` after the merge: the CLI's verbs live on `usage`, which only | ||
| `dev` has. | ||
|
|
||
| ## Required | ||
|
|
||
| - [Merge dev](/quest/m1/merge-dev.md) - builds on dev-only code that reaches `main` with the merge | ||
|
|
||
| ## Related | ||
|
|
||
| - [One LAN mesh](/quest/m1/lan-mesh.md) - the CLI already hosts the relay library for its cluster | ||
| - [`moq` serves like a relay](/quest/m2/cli-serve.md) - the end state where the relay is `moq` with listening on by default | ||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
These quests rely on code that exists only on
dev, but their described API break is explicitly unpublished and their remaining changes are additive or wire-only. They therefore fit m2's documented rule for work that starts onmainafter the merge, rather than m1 work that must gate the merge. Keeping both ready entries ahead ofMerge devmakes quest priority order delay that merge unnecessarily; move them to m2 and make the first one requireMerge dev.AGENTS.md reference: AGENTS.md:L86-L88
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Declined, the maintainer placed these in m1 deliberately. The merge is what publishes
moq_tokio::mdnsand the peer contract (/.cluster/<credential>, the advert fields); breaking either afterwards costs a dev cycle plus a relay/CLI compatibility cycle, which is exactly the cost the m1 rule exists to avoid. They rank below the merge gates in the list, so they do not delay the merge.(written by Claude Opus 5)