diff --git a/doc/bin/relay/cluster.md b/doc/bin/relay/cluster.md index 0478a5eb2f2..2bb8c5cb080 100644 --- a/doc/bin/relay/cluster.md +++ b/doc/bin/relay/cluster.md @@ -100,26 +100,34 @@ For a full mesh, list every other relay, or serve the list from `api.url`. A session carries both directions, so one dial per pair is enough; listing a pair on both sides opens a redundant second session. -`cluster.max_hops` bounds the hop path this relay accepts or forwards, from 1 -to 32, with 32 as the default. Set it near the mesh's diameter after any single -link or node failure, plus a margin, to cut off long detours during withdrawal -path hunting. Count the publisher's hop too. A cap below that diameter can -partition the mesh; a lower cap only drops longer paths and preserves route -selection among the remaining paths. A peer hears the best route with room -for this relay's hop, even when a cheaper route at the cap serves locally. +`cluster.max_hops` is a legacy setting: it bounds the hop path that +moq-lite-03 through moq-lite-06 carry, and moq-transport drafts 18 through 22 +when the MoQ Cluster extension is negotiated, and it leaves with moq-lite-06. +A moq-lite-07-wip route crosses at most 32 nodes whatever this is set to: it +does not hunt for paths, so a lower cap would only hide a short path behind a +cheaper long one. In a mesh that mixes the two, a moq-lite-07-wip route that +crossed in from moq-lite-06 still carries the moq-lite-06 chain: a relay drops +the route when that chain plus the route's publisher is longer than +`max_hops`. + +On those older versions it bounds the hop path this relay accepts or forwards, +from 1 to 32, with 32 as the default. Set it near the mesh's diameter after any +single link or node failure, plus a margin, to cut off long detours during +withdrawal path hunting. Count the publisher's hop too. A cap below that +diameter can partition the mesh; a lower cap only drops longer paths and +preserves route selection among the remaining paths. A peer hears the best +route with room for this relay's hop, even when a cheaper route at the cap +serves locally. ```toml [cluster] max_hops = 6 ``` -The same setting is `--cluster-max-hops` or `MOQ_CLUSTER_MAX_HOPS`. It covers -moq-lite-03 through moq-lite-06 and moq-transport drafts 18 through 22 when -the MoQ Cluster extension is negotiated. A moq-lite-07-wip route crosses at -most 32 nodes whatever this is set to: it does not hunt for paths, so a lower -cap would only hide a short path behind a cheaper long one. A forwarded path counts this relay's -own hop even when its peer appends it on receipt. Older versions and peers -without hop paths hide their depth, which this setting cannot bound. +The same setting is `--cluster-max-hops` or `MOQ_CLUSTER_MAX_HOPS`. A forwarded +path counts this relay's own hop even when its peer appends it on receipt. +Versions before moq-lite-03 and peers without hop paths hide their depth, which +this setting cannot bound. ## Upstream links @@ -277,8 +285,8 @@ url = "https://api.example.com/cluster/peers" HTTPS peer-list fetches present the same client certificate as cluster dials, but authenticate the API with system roots and the hostname in its URL. Mesh roots, fingerprints, insecure mode, and the mesh hostname override do not -apply to the API. For a private API, set `cluster.api.tls.root` to PEM -paths (or repeat `--cluster-api-tls-root`); these replace system trust +apply to the API. For a private API, set `cluster.api.root` to PEM +paths (or repeat `--cluster-api-root`); these replace system trust for API fetches only. Malformed roots fail startup, and files reload for new connections when rotated. @@ -355,7 +363,7 @@ services.moq-relay = { auth.enable = true; tls.certs = [ { chain = "/etc/moq/leaf.pem"; key = "/run/secrets/moq-leaf.key"; } ]; cluster = { - rootUrl = [ "https://root.example.com:4443" ]; + connect = [ "https://root.example.com:4443" ]; certFile = "/run/secrets/moq-cluster.pem"; keyFile = "/run/secrets/moq-cluster.key"; }; diff --git a/doc/bin/relay/config.md b/doc/bin/relay/config.md index c772acd2b20..225dc917488 100644 --- a/doc/bin/relay/config.md +++ b/doc/bin/relay/config.md @@ -86,7 +86,6 @@ A stream-only relay refuses `preferred_v4`, `preferred_v6`, `lb.id`, and The io\_uring runtime refuses `preferred_v4`, `preferred_v6`, and `lb.id`; use the tokio runtime when the listener needs these settings. `[listen.lb] nonce` needs an `id` in the same table; unset nonce uses 8. -The `--listen-quic-lb-id` and `--listen-quic-lb-nonce` flags update that table. `unix.allow` needs `unix.bind`. `[listen.lb.forward]` keeps a connection alive when its packets land on another relay behind @@ -107,8 +106,7 @@ so one file serves the whole cluster: A packet for an unlisted server ID is dropped. A forward is accepted only from a listed address and under the shared `key` (`openssl rand -hex 32 > forward.key`). A changed file replaces the map; an invalid one is logged and the last valid map kept, or stops startup. Forwarding needs -`lb.id` and all three settings, which the `--listen-quic-lb-forward-bind`, `-key`, and `-peers` -flags update. +`lb.id` and all three settings. ## \[quic] @@ -278,11 +276,11 @@ connect = ["https://us-east.example.com/?cost=10"] # Peers to dial. ?cost pric node = "https://us-west.example.com/" # This relay's own URL. token = "cluster.jwt" # JWT for dials without an inline ?jwt=. route_key = "route.key" # Route key; relays sharing the file fail over as one to scoped peers. -max_hops = 32 # Longest accepted/forwarded hop path (1 to 32). +max_hops = 32 # Legacy: longest hop path on moq-lite-03 to 06 (1 to 32). [cluster.api] url = "https://api.example.com/peers" # Live JSON peer list; a local file also works. -# tls.root = ["api-ca.pem"] # API server trust, independent from connect.tls. +# root = ["api-ca.pem"] # API server trust, independent from connect.tls. [cluster.lan] # Find peers on the LAN over mDNS. enabled = true diff --git a/nix/modules/moq-relay.nix b/nix/modules/moq-relay.nix index bc63801388b..c922b367ffc 100644 --- a/nix/modules/moq-relay.nix +++ b/nix/modules/moq-relay.nix @@ -16,6 +16,12 @@ let authUrl = "http://127.0.0.1:${toString cfg.auth.port}/"; in { + imports = [ + (lib.mkRemovedOptionModule [ "services" "moq-relay" "cluster" "rootUrl" ] + "Use services.moq-relay.cluster.connect, a list of full peer URLs such as [ \"https://peer.example.com:4443\" ]." + ) + ]; + options.services.moq-relay = { enable = lib.mkEnableOption "moq-relay"; @@ -107,7 +113,7 @@ in }; cluster = { - rootUrl = lib.mkOption { + connect = lib.mkOption { type = lib.types.nullOr (lib.types.nonEmptyListOf lib.types.str); default = null; example = [ @@ -141,7 +147,7 @@ in default = null; example = "/run/secrets/moq-cluster.pem"; description = '' - Client certificate chain (PEM) this node presents when it dials `rootUrl`, issued + Client certificate chain (PEM) this node presents when it dials `connect`, issued by the peers' `ca`. Reloaded when it changes. Needs `keyFile`. ''; }; @@ -159,7 +165,7 @@ in type = lib.types.nullOr lib.types.path; default = null; description = '' - A JWT this node presents when it dials `rootUrl`, for peers whose auth server + A JWT this node presents when it dials `connect`, for peers whose auth server verifies tokens instead of certificates. Re-read on every dial. Prefer `certFile`. ''; }; @@ -229,12 +235,12 @@ in warnings = lib.optional ( - cfg.cluster.rootUrl != null + cfg.cluster.connect != null && cfg.cluster.certFile == null && cfg.cluster.tokenFile == null - && lib.any (url: builtins.match ".*[?&]jwt=[^&#].*" url == null) (lib.toList cfg.cluster.rootUrl) + && lib.any (url: builtins.match ".*[?&]jwt=[^&#].*" url == null) (lib.toList cfg.cluster.connect) ) - "services.moq-relay: this relay dials cluster.rootUrl with no credential, so its peer refuses it or admits it only as an anonymous client; set cluster.certFile and cluster.keyFile (or cluster.tokenFile). The module no longer signs a cluster token."; + "services.moq-relay: this relay dials cluster.connect with no credential, so its peer refuses it or admits it only as an anonymous client; set cluster.certFile and cluster.keyFile (or cluster.tokenFile). The module no longer signs a cluster token."; # Create user and group users.users.${cfg.user} = { @@ -373,9 +379,9 @@ in // lib.optionalAttrs (!cfg.auth.enable) { MOQ_AUTH_PUBLIC = publicPattern; } - // lib.optionalAttrs (cfg.cluster.rootUrl != null) { + // lib.optionalAttrs (cfg.cluster.connect != null) { # Cluster configuration - MOQ_CLUSTER_CONNECT = lib.concatStringsSep "," cfg.cluster.rootUrl; + MOQ_CLUSTER_CONNECT = lib.concatStringsSep "," cfg.cluster.connect; } // lib.optionalAttrs (cfg.cluster.ca != [ ]) { MOQ_LISTEN_TLS_ROOT = lib.concatMapStringsSep "," toString cfg.cluster.ca; diff --git a/quest/m2/README.md b/quest/m2/README.md index c8cef6bd711..e531fa605c3 100644 --- a/quest/m2/README.md +++ b/quest/m2/README.md @@ -44,7 +44,6 @@ removal, a rename, or a wire, catalog, or format change that is free until item re-checked for a downstream caller first. - **Relay and transports.** [CPU](/quest/m2/relay-cpu.md), which the memory pairing found; [congestion names](/quest/m2/congestion-names.md); - [config names](/quest/m2/relay-config-names.md) and [the 0.14 leftovers](/quest/m2/relay-014-leftovers.md); and [transport names](/quest/m2/transport-names.md). - **Auth and crypto.** [Grants](/quest/m2/auth-grants.md), diff --git a/quest/m2/multicast/switch.md b/quest/m2/multicast/switch.md index 48da7e29074..9465a64e4df 100644 --- a/quest/m2/multicast/switch.md +++ b/quest/m2/multicast/switch.md @@ -132,8 +132,10 @@ Delete with the old rule: discount that formed pull cycles here, and lets a link cost 0 (line 88), which `route::Error::ZeroCost` refuses. The code implements neither, and item 10 of the epic makes a moq-transport session an endpoint, which has - no path to carry. `cluster.max_hops` then bounds lite-03 to lite-06 only - ([config names](/quest/m2/relay-config-names.md)). + no path to carry. `cluster.max_hops` then bounds lite-03 to lite-06 only: + drop the MoQ Cluster extension from its docs (`cluster::Config::max_hops`, + `origin::Config::max_hops`, `doc/bin/relay/cluster.md`, and + `doc/bin/relay/config.md`). - `rs/moq-net/verify/route/` and the `verify-route` skill, or rewrite the skill for the exhaustive search. - [Firefox tabs prove their route key](/quest/m5/routes-browser-proof.md), diff --git a/quest/m2/relay-014-leftovers.md b/quest/m2/relay-014-leftovers.md index 94453109d35..06b7dcd429c 100644 --- a/quest/m2/relay-014-leftovers.md +++ b/quest/m2/relay-014-leftovers.md @@ -74,7 +74,3 @@ For the PR: Public API: none (`Legacy` is crate-private). Config and CLI: ten hidden flags, their variables, and six hidden keys stop parsing; a wildcard-free public or mTLS pattern is accepted. Wire: none. - -## Related - -- [The relay's config names](/quest/m2/relay-config-names.md) - the old spellings this cut does refuse by name diff --git a/quest/m2/relay-config-names.md b/quest/m2/relay-config-names.md deleted file mode 100644 index be3a2722cb8..00000000000 --- a/quest/m2/relay-config-names.md +++ /dev/null @@ -1,95 +0,0 @@ -# [S] The relay's config names agree with each other at the freeze - -## Goal - -Four names in moq-relay's configuration follow the rules the rest of it -already keeps. The QUIC-LB flags join their section and key -(`--listen-lb-*` for `[listen.lb]`). The peer-list endpoint's CA is -`cluster.api.root`, as the auth endpoint's is `auth.root`. The NixOS module's -`cluster.rootUrl` is `cluster.connect`. `cluster.max_hops` says it bounds -only the older wire versions. Each old spelling is refused with the new one -named. - -## Plan - -Decided 2026-11-16 (maintainer, /quest-plan of the pre-cut audit): - -- ✅ `--listen-quic-lb-*` becomes `--listen-lb-*` (rejected: renaming the - table to `[listen.quic_lb]`; documenting a third exception). The docs' - rule is that a flag joins the section and key, and the table is the - shorter name. -- ✅ `cluster.api.tls.root` becomes `cluster.api.root` (rejected: keeping - the nested table). Both are "the CA for an HTTP endpoint the relay - calls", and a one-key `tls` table nests nothing. -- ✅ The nix option `cluster.rootUrl` becomes `cluster.connect` (rejected: - keeping a name from the root and leaf mode, which - [moq-dev/moq#8854](https://github.com/moq-dev/moq/pull/8854) removed). -- ✅ `cluster.max_hops` is marked legacy (rejected: deleting it now, which - leaves lite-03 to lite-06 meshes without their bound while the relay - still negotiates them). - -Facts found by the audit: - -- `doc/bin/relay/config.md:8-11`: "Every key is also a CLI flag and - environment variable that joins the section and key", with `listen.bind` - and the two `extensions` keys as the listed exceptions. `[listen.lb]` - (`rs/moq-tokio/src/listen.rs:204`) is spelled `--listen-quic-lb-id`, - `-nonce`, and `-forward-bind`, `-key`, `-peers` (`:387-462`), an unlisted - third. `release` has `--listen-quic-lb-id` and `-nonce`; the three - `forward` flags are new. `--server-quic-lb-*` is already refused naming - `--listen-quic-lb-*` (`:387-396`, `:664`). -- `auth.root` (`rs/moq-relay/src/auth.rs:46`) is flat; - `cluster.api.tls.root` (`rs/moq-relay/src/cluster/api.rs:38-46`) is new - since release and is the only key in its table. -- `nix/modules/moq-relay.nix:110` declares `cluster.rootUrl`, which sets - `MOQ_CLUSTER_CONNECT` (`:376-378`) and is named in two other options' - docs and an assertion (`:144`, `:162`, `:232-237`). `release` has the - option, setting `MOQ_CLUSTER_ROOT`. -- `cluster.max_hops` (`rs/moq-relay/src/cluster.rs:755`) bounds a hop list - that only lite-03 to lite-06 and the moq-cluster extension carry; a - lite-07 route has no hop list to bound. Nothing in its doc says so. -- `rs/moq-relay/src/cluster.rs:728`: "Hop-based routing on broadcasts - prevents announcement loops regardless of topology." Stale since lite-07. - -For the PR: - -- Flags and environment variables: `--listen-lb-id`, `--listen-lb-nonce`, - `--listen-lb-forward-bind`, `-key`, `-peers`, with `MOQ_LISTEN_LB_*`. - Refuse `--listen-quic-lb-*` and `--server-quic-lb-*` (and their - environment variables) through `moq_tokio::cli::Deprecated`, naming the - new spelling, as `--server-quic-lb-*` is refused today. The TOML keys do - not move. -- `cluster.api.root`, `--cluster-api-root`, `MOQ_CLUSTER_API_ROOT`. The old - key was never released, so it needs no refusal; an unknown key already - stops startup. -- Nix: rename the option and its mentions. Recommended: - `lib.mkRemovedOptionModule` naming `cluster.connect`, since the option is - on `release` and the repository refuses old names rather than aliasing - them. No other module in this repository sets it; downstream NixOS - configs do, so the PR's Impact section names the rename. -- `cluster.max_hops`: its doc, `doc/bin/relay/config.md`, and - `doc/bin/relay/cluster.md` say it applies to moq-lite-03 through 06 (and - moq-transport's cluster extension while - [the switch](/quest/m2/multicast/switch.md) keeps it) and leaves with - lite-06. `origin::Config::max_hops` gets the same sentence. If the switch - retires the cluster extension first, drop that clause. -- Fix the struct doc at `cluster.rs:728`. -- Update `doc/bin/relay/config.md`, `doc/bin/relay/cluster.md`, - the migration notes for moq-relay and moq-tokio, and - `rs/moq-relay/tests/integration/released_cli.rs`, the frozen list of - released spellings that must keep parsing: it gains - `listen-quic-lb-id` and `listen-quic-lb-nonce`. -- Tests: each old flag and variable refuses with the new name in the - message; the new ones parse; `nix flake check` covers the module. - -Not picked up, recorded so the next audit does not reopen them without new -evidence: `web.https.cert` not falling back to `listen.tls.cert` (additive -later), and `listen` against `bind` for socket keys (already on release). - -Public API: `moq_tokio::listen` flag names only. Config and CLI: breaking, -five flags and their variables renamed (two released), one unreleased TOML -key renamed, one nix option renamed. Wire: none. - -## Related - -- [The switch](/quest/m2/multicast/switch.md) - retires what else reads a hop bound diff --git a/quest/m3/release/migrate-audit.md b/quest/m3/release/migrate-audit.md index c13503af9a8..e4e3662d57c 100644 --- a/quest/m3/release/migrate-audit.md +++ b/quest/m3/release/migrate-audit.md @@ -66,8 +66,10 @@ m1 quest on 2026-10-22. - Known break, a Nix option rather than a Rust API (added 2026-10-31, from [moq-dev/moq#7343](https://github.com/moq-dev/moq/pull/7343)): the NixOS module option `services.moq-relay.cluster.rootUrl` takes a non-empty - list instead of a string. Migrate `rootUrl = "https://root:4443";` to - `rootUrl = [ "https://root:4443" ];`; an empty list fails evaluation. + list instead of a string, and is renamed `cluster.connect` + ([moq-dev/moq#8924](https://github.com/moq-dev/moq/pull/8924)). Migrate + `rootUrl = "https://root:4443";` to `connect = [ "https://root:4443" ];`; + an empty list fails evaluation, and `rootUrl` fails it naming `connect`. Write it into `rs/moq-relay/MIGRATE.md`'s transition section (its `## Unreleased` section until the cut names the version). diff --git a/quest/m5/nix-relay-peers-test.md b/quest/m5/nix-relay-peers-test.md index 3c3382ad208..38a36f2418d 100644 --- a/quest/m5/nix-relay-peers-test.md +++ b/quest/m5/nix-relay-peers-test.md @@ -3,7 +3,7 @@ ## Goal `nix flake check` evaluates the moq-relay NixOS module with no, one, and -several `cluster.rootUrl` peers and refuses an empty list, asserting the +several `cluster.connect` peers and refuses an empty list, asserting the `MOQ_CLUSTER_CONNECT` value each produces. Optionally a NixOS VM test runs a root and two leaves from the module and sees them connect. @@ -15,14 +15,14 @@ Decided 2026-10-31 (user, /quest-plan of the follow-ups from the 2026-10-31 Moved to m5 2026-11-12 (maintainer, /quest-audit): no consumer; parked rather than deleted. -[moq-dev/moq#7343](https://github.com/moq-dev/moq/pull/7343) made `services.moq-relay.cluster.rootUrl` a +[moq-dev/moq#7343](https://github.com/moq-dev/moq/pull/7343) made `services.moq-relay.cluster.rootUrl` (now `cluster.connect`) a `nullOr (nonEmptyListOf str)` (`nix/modules/moq-relay.nix:120` at 4bf501b535), joined into `MOQ_CLUSTER_CONNECT` at `:365`, and verified it only by a manual `nix eval`. - Add an eval check beside `nix/runner/config-test.nix`, wired into `flake.nix`'s `checks` (`:750` at 4bf501b535): `null` sets no `MOQ_CLUSTER_CONNECT`, one and two URLs join with commas, `[ ]` fails the type check, and a relay with - `rootUrl` but no `certFile` or `tokenFile` raises the missing-credential warning. + `connect` but no `certFile` or `tokenFile` raises the missing-credential warning. - A VM test (root plus two leaves) only if it stays cheap in CI; otherwise leave it out and say so. diff --git a/rs/moq-cli/src/args.rs b/rs/moq-cli/src/args.rs index 41aab58a0c5..d9227ca85b5 100644 --- a/rs/moq-cli/src/args.rs +++ b/rs/moq-cli/src/args.rs @@ -2771,7 +2771,7 @@ mod tests { &["--listen-version", "moq-lite-02"], &["--listen-tls-generate", "localhost"], &["--listen-preferred-v4", "127.0.0.1:443"], - &["--listen-quic-lb-id", "01"], + &["--listen-lb-id", "01"], &["--listen-tcp-bind", "127.0.0.1:0"], &["--cluster-node", "https://self.example"], &["--auth-public", "**"], diff --git a/rs/moq-net/src/model/origin.rs b/rs/moq-net/src/model/origin.rs index f73b1d4b92f..8b7dde6a09e 100644 --- a/rs/moq-net/src/model/origin.rs +++ b/rs/moq-net/src/model/origin.rs @@ -113,12 +113,14 @@ pub struct Config { /// Longest hop path a session using this origin accepts or forwards (default 32). /// - /// Applies to moq-lite-03+ hop paths and the negotiated MoQ Cluster extension on - /// moq-transport. A forwarded path counts this origin's own hop too, including + /// Legacy: applies to moq-lite-03 through 06 and the negotiated MoQ Cluster extension + /// on moq-transport, and leaves with moq-lite-06. A moq-lite-07 route's own hops stop + /// at 32 whatever this is, but a route that crossed into moq-lite-07 from moq-lite-06 + /// still carries that chain: with its publisher's hop appended it must fit this + /// bound, or the route is dropped (logged at debug). A forwarded path counts this origin's own hop too, including /// when the receiving peer reconstructs that hop from the announce handshake. /// Protocols without a hop path cannot reveal or bound the depth they hide. No wire - /// carries a path longer than 32, so a larger value acts as 32, and a moq-lite-07 - /// route's own hops stop there whatever this is. + /// carries a path longer than 32, so a larger value acts as 32. pub max_hops: NonZeroUsize, /// The cache pool broadcasts under this origin charge their groups into. It flows diff --git a/rs/moq-relay/src/cluster.rs b/rs/moq-relay/src/cluster.rs index 8c3bc6c95fb..e0fbefb3ed2 100644 --- a/rs/moq-relay/src/cluster.rs +++ b/rs/moq-relay/src/cluster.rs @@ -725,7 +725,9 @@ impl Drop for Held { /// configured here or found on the LAN; it never dials a URL learned from an /// announcement. /// -/// Hop-based routing on broadcasts prevents announcement loops regardless of topology. +/// A relay drops any route that names it, so announcements never loop whatever the +/// topology: a moq-lite-07 route names each relay it crossed, and older versions +/// carry that hop list on each broadcast. #[serde_with::serde_as] #[derive(usage_rs::Args, Clone, Debug, serde::Serialize, serde::Deserialize, Default)] #[usage(unknown_flags = "error", args_override_self = false)] @@ -747,7 +749,13 @@ pub struct Config { )] pub route_key: Option, - /// Longest hop path accepted or forwarded, from 1 to 32 (default 32). + /// Legacy: longest hop path accepted or forwarded on moq-lite-03 to 06, from 1 to 32 + /// (default 32). + /// + /// Also bounds moq-transport's MoQ Cluster extension. A moq-lite-07 route stops at + /// 32 nodes whatever this is, so the setting leaves with moq-lite-06. Until then, a + /// moq-lite-07 route that crossed in from moq-lite-06 is dropped when the chain it + /// carries, plus its publisher, is longer than this. #[usage( name = "cluster-max-hops", long = "cluster-max-hops", @@ -780,7 +788,7 @@ pub struct Config { #[serde_as(as = "serde_with::OneOrMany<_>")] pub connect: Vec, - /// Dynamic peer-list source and its independent TLS trust. + /// Dynamic peer-list source and its independent server trust. #[usage(flatten)] pub api: api::Config, @@ -876,14 +884,14 @@ impl Config { found.flag( "--cluster-connect-api-tls-root", Some("MOQ_CLUSTER_CONNECT_API_TLS_ROOT"), - "--cluster-api-tls-root", + "--cluster-api-root", ); } if self.removed_api.is_some() { found.toml("[cluster] connect_api", "[cluster.api] url", None); } if self.removed_api_root.is_some() { - found.toml("[cluster] connect_api_tls_root", "[cluster.api.tls] root", None); + found.toml("[cluster] connect_api_tls_root", "[cluster.api] root", None); } const ID: &str = "the Hop ID is random on every start and nothing pins it"; if self.removed_id.is_some() { @@ -1857,7 +1865,7 @@ impl Cluster { .context("cluster.api.url with an http(s) URL needs a dial template (call Cluster::with_connect)")? .tls .build()?; - Some(crate::http_client::build(&tls, &self.config.api.tls.root)?) + Some(crate::http_client::build(&tls, &self.config.api.root)?) } else { None }; @@ -3948,7 +3956,7 @@ mod tests { #[test] fn cluster_connect_api_survives_toml_merge() { - let toml = "[cluster.api]\nurl = \"https://api.example.com/cluster/connect\"\ntls.root = [\"api.pem\"]\n"; + let toml = "[cluster.api]\nurl = \"https://api.example.com/cluster/connect\"\nroot = [\"api.pem\"]\n"; let dir = tempfile::tempdir().unwrap(); let path = dir.path().join("cluster-connect-api-toml.toml"); std::fs::write(&path, toml).unwrap(); @@ -3959,7 +3967,7 @@ mod tests { config.cluster.api.url.as_deref(), Some("https://api.example.com/cluster/connect") ); - assert_eq!(config.cluster.api.tls.root, vec![PathBuf::from("api.pem")]); + assert_eq!(config.cluster.api.root, vec![PathBuf::from("api.pem")]); } #[tokio::test] diff --git a/rs/moq-relay/src/cluster/api.rs b/rs/moq-relay/src/cluster/api.rs index f11361ca999..89b5f418d8c 100644 --- a/rs/moq-relay/src/cluster/api.rs +++ b/rs/moq-relay/src/cluster/api.rs @@ -4,6 +4,7 @@ use serde::{Deserialize, Serialize}; use std::path::PathBuf; /// Dynamic peer-list source, independent from mesh TLS trust. +#[serde_with::serde_as] #[derive(usage_rs::Args, Clone, Debug, Default, Serialize, Deserialize)] #[serde(default, deny_unknown_fields)] #[non_exhaustive] @@ -21,27 +22,18 @@ pub struct Config { /// `--cluster-node` value, when set, is sent as a `?node=` query param so the /// server can return this node's peers. The relay keeps the last good list if /// a fetch fails. Composes with `--cluster-connect`. - #[usage(long = "cluster-api-url", env = "MOQ_CLUSTER_API_URL", setting = "cluster.api.url")] pub url: Option, - /// TLS trust used only for the peer-list API. - #[usage(flatten)] - pub tls: Tls, -} -/// Server roots for a peer-list API; its client identity comes from the dial template. -#[serde_with::serde_as] -#[derive(usage_rs::Args, Clone, Debug, Default, Serialize, Deserialize)] -#[serde(default, deny_unknown_fields)] -#[non_exhaustive] -pub struct Tls { /// PEM roots to use instead of system roots, verifying the API URL's hostname. + /// The client identity comes from the dial template; mesh trust never applies. #[usage( - long = "cluster-api-tls-root", - env = "MOQ_CLUSTER_API_TLS_ROOT", - setting = "cluster.api.tls.root" + long = "cluster-api-root", + env = "MOQ_CLUSTER_API_ROOT", + setting = "cluster.api.root" )] #[usage(value_hint = usage_rs::ValueHint::FilePath, extensions("pem", "crt", "cer"))] + #[serde(skip_serializing_if = "Vec::is_empty")] #[serde_as(as = "serde_with::OneOrMany<_>")] pub root: Vec, } diff --git a/rs/moq-relay/src/config.rs b/rs/moq-relay/src/config.rs index 6741eecf3c3..82d2091d3dc 100644 --- a/rs/moq-relay/src/config.rs +++ b/rs/moq-relay/src/config.rs @@ -509,7 +509,7 @@ mod tests { "--cluster-connect-api-tls-root", "MOQ_CLUSTER_CONNECT_API_TLS_ROOT", "api.pem", - "--cluster-api-tls-root", + "--cluster-api-root", ), ]; @@ -544,7 +544,7 @@ mod tests { let path = dir.path().join("obsolete.toml"); for (body, replacement) in [ ("[cluster]\nconnect_api = 'peers.json'", "[cluster.api] url"), - ("[cluster]\nconnect_api_tls_root = []", "[cluster.api.tls] root"), + ("[cluster]\nconnect_api_tls_root = []", "[cluster.api] root"), ] { std::fs::write(&path, body).unwrap(); let error = @@ -1792,8 +1792,13 @@ ws = false ); } - /// The variables a QUIC-LB setting could also be read from. - const QUIC_LB_ENV: &[&str] = &["MOQ_LISTEN_QUIC_LB_ID", "MOQ_LISTEN_QUIC_LB_NONCE"]; + /// The variables a QUIC-LB setting could also be read from, current and released. + const QUIC_LB_ENV: &[&str] = &[ + "MOQ_LISTEN_LB_ID", + "MOQ_LISTEN_LB_NONCE", + "MOQ_LISTEN_QUIC_LB_ID", + "MOQ_LISTEN_QUIC_LB_NONCE", + ]; /// Merge `body` as the config file named `name` with `cli`, and require that the /// listener refuses to start with an error containing `needle`. @@ -1813,7 +1818,7 @@ ws = false /// A QUIC-LB nonce with no server id stops startup from TOML, and CLI /// assignments override the same nested fields. /// - /// The CLI flag pair already requires `--listen-quic-lb-id`, so this does not + /// The CLI flag pair already requires `--listen-lb-id`, so this does not /// add a second command-line error for that spelling. #[test] fn quic_lb_nonce_and_conflicts_refuse_to_start() { @@ -1821,16 +1826,11 @@ ws = false return; } - let err = Config::parse_and_merge(["moq-relay", "--listen-quic-lb-nonce", "8"]) + let err = Config::parse_and_merge(["moq-relay", "--listen-lb-nonce", "8"]) .expect_err("the flag pair is already required"); - assert!(err.to_string().contains("--listen-quic-lb-id"), "{err}"); + assert!(err.to_string().contains("--listen-lb-id"), "{err}"); - refuse_quic_lb( - "nonce.toml", - "[listen.lb]\nnonce = 8\n", - &[], - "requires --listen-quic-lb-id", - ); + refuse_quic_lb("nonce.toml", "[listen.lb]\nnonce = 8\n", &[], "requires --listen-lb-id"); { let dir = tempfile::tempdir().unwrap(); @@ -1844,7 +1844,7 @@ ws = false let config = Config::parse_and_merge([ std::ffi::OsString::from("moq-relay"), path.into(), - "--listen-quic-lb-id".into(), + "--listen-lb-id".into(), "ee".into(), ]) .expect("CLI overrides the same nested config field"); @@ -1858,12 +1858,33 @@ ws = false #[test] fn quic_lb_env_nonce_without_an_id_refuses_to_start() { if !test_env::Env::without(QUIC_LB_ENV) - .set("MOQ_LISTEN_QUIC_LB_NONCE", "8") + .set("MOQ_LISTEN_LB_NONCE", "8") .isolate() { return; } let err = Config::parse_and_merge(["moq-relay"]).expect_err("env nonce without id"); - assert!(err.to_string().contains("--listen-quic-lb-id"), "{err}"); + assert!(err.to_string().contains("--listen-lb-id"), "{err}"); + } + + /// The released `--listen-quic-lb-*` spellings stop startup naming their + /// replacement, from the command line and the environment alike. + #[test] + fn released_quic_lb_spellings_name_their_replacement() { + if !test_env::Env::without(QUIC_LB_ENV) + .set("MOQ_LISTEN_QUIC_LB_NONCE", "8") + .isolate() + { + return; + } + let err = Config::parse_and_merge(["moq-relay", "--listen-quic-lb-id", "ab"]) + .expect_err("released spellings are refused") + .to_string(); + for line in [ + "--listen-quic-lb-id / MOQ_LISTEN_QUIC_LB_ID -> --listen-lb-id / MOQ_LISTEN_LB_ID", + "--listen-quic-lb-nonce / MOQ_LISTEN_QUIC_LB_NONCE -> --listen-lb-nonce / MOQ_LISTEN_LB_NONCE", + ] { + assert!(err.contains(line), "missing {line:?} from {err}"); + } } } diff --git a/rs/moq-relay/src/uring.rs b/rs/moq-relay/src/uring.rs index 842f4325c51..174fa78bf85 100644 --- a/rs/moq-relay/src/uring.rs +++ b/rs/moq-relay/src/uring.rs @@ -1002,7 +1002,7 @@ mod tests { &mut crate::handoff::Sockets::disabled(), ) .expect_err("a QUIC-LB nonce without an id is refused"); - assert!(err.to_string().contains("--listen-quic-lb-nonce"), "{err:#}"); + assert!(err.to_string().contains("--listen-lb-nonce"), "{err:#}"); } /// A window the operator set has to reach the worker. Refusing it, or diff --git a/rs/moq-relay/tests/integration/released_cli.rs b/rs/moq-relay/tests/integration/released_cli.rs index 747818f4073..ed55fcaa5e1 100644 --- a/rs/moq-relay/tests/integration/released_cli.rs +++ b/rs/moq-relay/tests/integration/released_cli.rs @@ -54,11 +54,14 @@ const RELEASED: &[(&str, Option<&str>)] = &[ ("client-version", Some("MOQ_CLIENT_VERSION")), ("cluster-connect", Some("MOQ_CLUSTER_CONNECT")), ("cluster-connect-api", Some("MOQ_CLUSTER_CONNECT_API")), + ("cluster-connect-api-tls-root", Some("MOQ_CLUSTER_CONNECT_API_TLS_ROOT")), ("cluster-node", Some("MOQ_CLUSTER_NODE")), ("cluster-tier", Some("MOQ_CLUSTER_TIER")), ("cluster-token", Some("MOQ_CLUSTER_TOKEN")), ("internal-listen", Some("MOQ_INTERNAL_LISTEN")), ("listen", Some("MOQ_SERVER_BIND")), + ("listen-quic-lb-id", Some("MOQ_LISTEN_QUIC_LB_ID")), + ("listen-quic-lb-nonce", Some("MOQ_LISTEN_QUIC_LB_NONCE")), ("log-level", Some("MOQ_LOG_LEVEL")), ("server-bind", Some("MOQ_SERVER_BIND")), ("server-max-streams", Some("MOQ_SERVER_QUIC_MAX_STREAMS")), diff --git a/rs/moq-tokio/src/listen.rs b/rs/moq-tokio/src/listen.rs index 7a2fa1b8ebf..a8da52e995c 100644 --- a/rs/moq-tokio/src/listen.rs +++ b/rs/moq-tokio/src/listen.rs @@ -211,9 +211,9 @@ pub struct Config { #[serde(default)] pub reset: Reset, - /// The released `--server-*` spellings and their env vars, kept parsing but - /// hidden. Never read as settings: [`Config::deprecated`] names what replaced - /// each one so a process can say so and stop. + /// The released `--server-*` and `--listen-quic-lb-*` spellings and their env + /// vars, kept parsing but hidden. Never read as settings: [`Config::deprecated`] + /// names what replaced each one so a process can say so and stop. #[usage(flatten)] #[serde(skip)] pub(crate) legacy: Legacy, @@ -290,7 +290,8 @@ pub struct Resolved { /// forms a group here, and callers do not need its raw serving handles. pub(crate) use moq_sock::shard::Socket; -/// The `--server-*` flags from before the accept side was named `listen`. +/// The released `--server-*` flags from before the accept side was named `listen`, and +/// the `--listen-quic-lb-*` ones from before they joined their `[listen.lb]` table. /// /// They carry their original env vars, which is why these are separate args rather /// than Usage aliases: an alias renames the flag but not the variable, and a relay @@ -352,6 +353,22 @@ pub(crate) struct Legacy { hide = true )] lb_nonce: Option, + + #[usage( + name = "listen-quic-lb-id", + long = "listen-quic-lb-id", + env = "MOQ_LISTEN_QUIC_LB_ID", + hide = true + )] + quic_lb_id: Option, + + #[usage( + name = "listen-quic-lb-nonce", + long = "listen-quic-lb-nonce", + env = "MOQ_LISTEN_QUIC_LB_NONCE", + hide = true + )] + quic_lb_nonce: Option, } impl Legacy { @@ -386,14 +403,28 @@ impl Legacy { found.flag( "--server-quic-lb-id", Some("MOQ_SERVER_QUIC_LB_ID"), - "--listen-quic-lb-id / MOQ_LISTEN_QUIC_LB_ID", + "--listen-lb-id / MOQ_LISTEN_LB_ID", ); } if self.lb_nonce.is_some() { found.flag( "--server-quic-lb-nonce", Some("MOQ_SERVER_QUIC_LB_NONCE"), - "--listen-quic-lb-nonce / MOQ_LISTEN_QUIC_LB_NONCE", + "--listen-lb-nonce / MOQ_LISTEN_LB_NONCE", + ); + } + if self.quic_lb_id.is_some() { + found.flag( + "--listen-quic-lb-id", + Some("MOQ_LISTEN_QUIC_LB_ID"), + "--listen-lb-id / MOQ_LISTEN_LB_ID", + ); + } + if self.quic_lb_nonce.is_some() { + found.flag( + "--listen-quic-lb-nonce", + Some("MOQ_LISTEN_QUIC_LB_NONCE"), + "--listen-lb-nonce / MOQ_LISTEN_LB_NONCE", ); } found @@ -434,32 +465,27 @@ impl Config { )); } if self.lb.nonce.is_some() && self.lb.id.is_none() { - return Err(crate::Error::NoBackend( - "--listen-quic-lb-nonce requires --listen-quic-lb-id", - )); + return Err(crate::Error::NoBackend("--listen-lb-nonce requires --listen-lb-id")); } let forward = &self.lb.forward; if forward.configured() { let refused = [ - ( - self.lb.id.is_none(), - "--listen-quic-lb-forward-* requires --listen-quic-lb-id", - ), + (self.lb.id.is_none(), "--listen-lb-forward-* requires --listen-lb-id"), ( forward.bind.is_none(), - "--listen-quic-lb-forward-* requires --listen-quic-lb-forward-bind", + "--listen-lb-forward-* requires --listen-lb-forward-bind", ), ( forward.key.is_none(), - "--listen-quic-lb-forward-bind requires --listen-quic-lb-forward-key", + "--listen-lb-forward-bind requires --listen-lb-forward-key", ), ( forward.peers.is_none(), - "--listen-quic-lb-forward-bind requires --listen-quic-lb-forward-peers", + "--listen-lb-forward-bind requires --listen-lb-forward-peers", ), ( forward.bind.is_some_and(|bind| bind.ip().is_unspecified()), - "--listen-quic-lb-forward-bind needs a specific IP, which its peers list", + "--listen-lb-forward-bind needs a specific IP, which its peers list", ), ]; if let Some((_, reason)) = refused.into_iter().find(|(set, _)| *set) { @@ -499,10 +525,7 @@ impl Config { self.preferred_v6.is_some(), "--listen-preferred-v6 needs a QUIC listener (--listen)", ), - ( - self.lb.id.is_some(), - "--listen-quic-lb-id needs a QUIC listener (--listen)", - ), + (self.lb.id.is_some(), "--listen-lb-id needs a QUIC listener (--listen)"), ( self.reset.secret.is_some(), "--listen-reset-secret needs a QUIC listener (--listen)", @@ -629,9 +652,9 @@ mod tests { Cli::parse_from(&args).unwrap().config } - /// Every released `--server-*` spelling keeps parsing, so the process can name - /// its replacement rather than leave Usage reporting an unexpected argument. - /// None of them configure anything. + /// Every released `--server-*` and `--listen-quic-lb-*` spelling keeps parsing, + /// so the process can name its replacement rather than leave Usage reporting an + /// unexpected argument. None of them configure anything. #[test] fn released_server_spellings_are_reported_not_applied() { let config = config_from([ @@ -644,6 +667,12 @@ mod tests { "192.0.2.1:443", "--server-quic-lb-id", "ab", + "--server-quic-lb-nonce", + "8", + "--listen-quic-lb-id", + "cd", + "--listen-quic-lb-nonce", + "9", "--server-tls-cert", "/tmp/cert.pem", "--server-tls-root", @@ -653,6 +682,7 @@ mod tests { assert!(config.version.is_empty()); assert_eq!(config.preferred_v4, None); assert!(config.lb.id.is_none()); + assert!(config.lb.nonce.is_none()); assert!(config.tls.cert.is_empty()); assert!(config.tls.root.is_empty()); @@ -661,7 +691,10 @@ mod tests { "--server-bind / MOQ_SERVER_BIND -> --listen / MOQ_LISTEN", "--server-version / MOQ_SERVER_VERSION -> --listen-version / MOQ_LISTEN_VERSION", "--server-preferred-v4 / MOQ_SERVER_PREFERRED_V4 -> --listen-preferred-v4 / MOQ_LISTEN_PREFERRED_V4", - "--server-quic-lb-id / MOQ_SERVER_QUIC_LB_ID -> --listen-quic-lb-id / MOQ_LISTEN_QUIC_LB_ID", + "--server-quic-lb-id / MOQ_SERVER_QUIC_LB_ID -> --listen-lb-id / MOQ_LISTEN_LB_ID", + "--server-quic-lb-nonce / MOQ_SERVER_QUIC_LB_NONCE -> --listen-lb-nonce / MOQ_LISTEN_LB_NONCE", + "--listen-quic-lb-id / MOQ_LISTEN_QUIC_LB_ID -> --listen-lb-id / MOQ_LISTEN_LB_ID", + "--listen-quic-lb-nonce / MOQ_LISTEN_QUIC_LB_NONCE -> --listen-lb-nonce / MOQ_LISTEN_LB_NONCE", "--tls-cert / MOQ_SERVER_TLS_CERT -> --listen-tls-cert / MOQ_LISTEN_TLS_CERT", "--server-tls-root / MOQ_SERVER_TLS_ROOT -> --listen-tls-root / MOQ_LISTEN_TLS_ROOT", ] { @@ -715,7 +748,7 @@ mod tests { #[test] fn cli_load_balancer_survives_the_merge_round_trip() { - let config = config_from(["test", "--listen-quic-lb-id", "ab", "--listen-quic-lb-nonce", "9"]); + let config = config_from(["test", "--listen-lb-id", "ab", "--listen-lb-nonce", "9"]); let encoded = toml::Value::try_from(config).expect("serialize"); let decoded: Config = encoded.try_into().expect("deserialize"); assert_eq!( @@ -732,7 +765,7 @@ mod tests { fn quic_lb_nonce_without_id_refuses_to_start() { let config: Config = toml::from_str("[lb]\nnonce = 8").unwrap(); assert!( - matches!(config.validate(), Err(crate::Error::NoBackend(reason)) if reason.contains("requires --listen-quic-lb-id")) + matches!(config.validate(), Err(crate::Error::NoBackend(reason)) if reason.contains("requires --listen-lb-id")) ); } @@ -788,18 +821,18 @@ peers = "peers.toml" config.validate().expect("complete"); for (body, needle) in [ - (complete.replace("id = \"ab\"\n", ""), "requires --listen-quic-lb-id"), + (complete.replace("id = \"ab\"\n", ""), "requires --listen-lb-id"), ( complete.replace("bind = \"10.0.0.1:4443\"\n", ""), - "requires --listen-quic-lb-forward-bind", + "requires --listen-lb-forward-bind", ), ( complete.replace("key = \"k\"\n", ""), - "requires --listen-quic-lb-forward-key", + "requires --listen-lb-forward-key", ), ( complete.replace("peers = \"p\"\n", ""), - "requires --listen-quic-lb-forward-peers", + "requires --listen-lb-forward-peers", ), (complete.replace("10.0.0.1", "0.0.0.0"), "needs a specific IP"), ] { @@ -846,7 +879,7 @@ peers = "peers.toml" ("--listen-preferred-v6", |c| { c.preferred_v6 = Some("[2001:db8::1]:443".parse().unwrap()) }), - ("--listen-quic-lb-id", |c| c.lb.id = Some("ab".parse().unwrap())), + ("--listen-lb-id", |c| c.lb.id = Some("ab".parse().unwrap())), ("--listen-reset-secret", |c| c.reset.secret = Some("reset.key".into())), ]; for (name, set) in cases { @@ -940,9 +973,9 @@ pub struct LoadBalancer { /// Server ID to embed in connection IDs for QUIC-LB compatibility. /// If set, connection IDs will be derived semi-deterministically. #[usage( - name = "listen-quic-lb-id", - long = "listen-quic-lb-id", - env = "MOQ_LISTEN_QUIC_LB_ID", + name = "listen-lb-id", + long = "listen-lb-id", + env = "MOQ_LISTEN_LB_ID", setting = "listen.lb.id" )] #[serde(default, skip_serializing_if = "Option::is_none")] @@ -951,11 +984,11 @@ pub struct LoadBalancer { /// Number of random nonce bytes in QUIC-LB connection IDs. /// Must be at least 4, and server_id + nonce + 1 must not exceed 20. #[usage( - name = "listen-quic-lb-nonce", - long = "listen-quic-lb-nonce", - env = "MOQ_LISTEN_QUIC_LB_NONCE", + name = "listen-lb-nonce", + long = "listen-lb-nonce", + env = "MOQ_LISTEN_LB_NONCE", setting = "listen.lb.nonce", - requires = "--listen-quic-lb-id" + requires = "--listen-lb-id" )] #[serde(default, skip_serializing_if = "Option::is_none")] pub nonce: Option, @@ -966,7 +999,7 @@ pub struct LoadBalancer { pub forward: Forward, } -/// QUIC-LB forwarding (`[listen.lb.forward]`, `--listen-quic-lb-forward-*`). +/// QUIC-LB forwarding (`[listen.lb.forward]`, `--listen-lb-forward-*`). /// /// Behind an anycast address or a load-balanced VIP, a route change or a rebalance can land an /// established connection's packets on another server. With forwarding, that server hands each @@ -980,9 +1013,9 @@ pub struct Forward { /// The UDP address this server receives forwards on, and the one its peers name it by. /// Needs a specific IP, since a forward is accepted only from a peer's listed address. #[usage( - name = "listen-quic-lb-forward-bind", - long = "listen-quic-lb-forward-bind", - env = "MOQ_LISTEN_QUIC_LB_FORWARD_BIND", + name = "listen-lb-forward-bind", + long = "listen-lb-forward-bind", + env = "MOQ_LISTEN_LB_FORWARD_BIND", setting = "listen.lb.forward.bind" )] #[serde(default, skip_serializing_if = "Option::is_none")] @@ -992,9 +1025,9 @@ pub struct Forward { /// characters (`openssl rand -hex 32`). It authenticates each forward, which carries a /// client address the receiver would otherwise take on trust. #[usage( - name = "listen-quic-lb-forward-key", - long = "listen-quic-lb-forward-key", - env = "MOQ_LISTEN_QUIC_LB_FORWARD_KEY", + name = "listen-lb-forward-key", + long = "listen-lb-forward-key", + env = "MOQ_LISTEN_LB_FORWARD_KEY", setting = "listen.lb.forward.key" )] #[usage(value_hint = usage_rs::ValueHint::FilePath)] @@ -1006,9 +1039,9 @@ pub struct Forward { /// This server's own entry is skipped, so every server can share one file. A packet for /// a server missing from it is dropped. #[usage( - name = "listen-quic-lb-forward-peers", - long = "listen-quic-lb-forward-peers", - env = "MOQ_LISTEN_QUIC_LB_FORWARD_PEERS", + name = "listen-lb-forward-peers", + long = "listen-lb-forward-peers", + env = "MOQ_LISTEN_LB_FORWARD_PEERS", setting = "listen.lb.forward.peers" )] #[usage(value_hint = usage_rs::ValueHint::FilePath)]