From 5d549f457099a283cda8f645be67e05ee4b0ed89 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Mon, 2 Nov 2026 22:05:56 -0800 Subject: [PATCH 01/10] chore(quest): claim quest/m1/poll-first/no-spawn/admissions.md Quest-Claim: 551e90837399e966 From 3721ac0a4e2569f76345e67eb2027058e94c48d8 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Mon, 2 Nov 2026 22:17:10 -0800 Subject: [PATCH 02/10] refactor(relay): poll admissions and stats through their owners Co-Authored-By: GPT-6.1 Sol --- doc/bin/relay/index.md | 4 +- quest/m1/poll-first/no-spawn/README.md | 1 - quest/m1/poll-first/no-spawn/admissions.md | 39 ------ quest/m1/poll-first/no-spawn/sim-tests.md | 4 - rs/moq-relay/MIGRATE.md | 4 + rs/moq-relay/benches/http_auth.rs | 108 ++++++++++------ rs/moq-relay/src/auth.rs | 136 +++++++++++++-------- rs/moq-relay/src/cluster.rs | 95 +++++++++++--- rs/moq-relay/src/relay.rs | 4 +- rs/moq-relay/src/stats.rs | 4 +- 10 files changed, 243 insertions(+), 156 deletions(-) delete mode 100644 quest/m1/poll-first/no-spawn/admissions.md diff --git a/doc/bin/relay/index.md b/doc/bin/relay/index.md index 624ea816578..4c068a813c3 100644 --- a/doc/bin/relay/index.md +++ b/doc/bin/relay/index.md @@ -77,7 +77,9 @@ relay.with_web(web).run().await?; - `Relay::load` binds every socket, so a taken port fails there, and the accessors report the bound addresses, including ports assigned for `:0`. -- `run` consumes the relay, so clone the handles your tasks need first. +- `run` consumes the relay, so clone the handles your tasks need first. Stats + publishing starts when `run` drives the cluster; an application building a + `Cluster` itself must keep polling its returned driver while serving. - Build on `web().routes()`: `with_web` replaces the router, so `Router::new()` drops the built-in routes. - A route reads the connection's peer address with axum's diff --git a/quest/m1/poll-first/no-spawn/README.md b/quest/m1/poll-first/no-spawn/README.md index ad8a5a53c05..827b8bd270d 100644 --- a/quest/m1/poll-first/no-spawn/README.md +++ b/quest/m1/poll-first/no-spawn/README.md @@ -49,7 +49,6 @@ binding boundary. ## Required -- [Admissions and stats are polled](/quest/m1/poll-first/no-spawn/admissions.md) - HTTP admissions run inside their waiter, and the stats publisher runs in the cluster's driver - [moq-ffi spawns only its root](/quest/m1/poll-first/no-spawn/ffi.md) - one runtime-owned driver task holds every `Background` as `kio::Tasks` children - [The relay's in-memory tests run on kio's simulator](/quest/m1/poll-first/no-spawn/sim-tests.md) - `rs/moq-relay/tests/integration/connection.rs` runs on the simulator instead of paused tokio diff --git a/quest/m1/poll-first/no-spawn/admissions.md b/quest/m1/poll-first/no-spawn/admissions.md deleted file mode 100644 index 4ada3dda796..00000000000 --- a/quest/m1/poll-first/no-spawn/admissions.md +++ /dev/null @@ -1,39 +0,0 @@ -# [S] Admissions and stats are polled - -## Goal - -moq-relay spawns no task per HTTP admission, and `Cluster::with_stats` spawns -no stats publisher. The `Server` decider's request runs inside the caller that -waits on its answer, and the publisher runs as a child of the cluster's -`Driver`. - -## Plan - -Spawns in scope on `main` (2026-11-01): - -- `rs/moq-relay/src/auth.rs`, `Decider::Server`: one - `tokio::spawn(moq_tokio::panic::isolate(..))` per admission HTTP request. - [moq-dev/moq#7360](https://github.com/moq-dev/moq/pull/7360) (merged - 2026-11-01) already removed the decider loop around it. -- `rs/moq-relay/src/cluster.rs`, `Cluster::with_stats`: the stats publisher, - through `Critical`. Since #7360, `moq_stats::Producer::new` returns - `(Producer, Publisher)`, so moq-stats itself spawns nothing. - -✅ **The waiter polls the admission** (maintainer, 2026-11-01, D3 on -[moq-dev/moq#7519](https://github.com/moq-dev/moq/pull/7519)): the caller -waiting on `Answer` polls the `moq_auth::Client` request inline, and dropping -the wait cancels the request, which replaces the `reply.closed()` select. A -panic then ends the session being admitted, the same scope the per-admission -`isolate` gives today. Rejected: one long-lived `kio::Tasks` of admissions -polled by `Relay::run`, which brings back the long-lived decider task that -#7360 removed. - -The publisher joins the cluster's `Driver` (`rs/moq-relay/src/cluster.rs`, -from [moq-dev/moq#7626](https://github.com/moq-dev/moq/pull/7626)), so a -publisher panic still ends the relay. `Cluster::new` has already handed the -driver out by the time `Cluster::with_stats` runs, so the publisher either -reaches it through a queue the driver polls or moves into `Options` for -`Cluster::new` to add. `Publisher::run` is an `async fn`; giving `Publisher` a -`poll` is optional and only worth it if `Driver` needs it. - -Public API: `Cluster::with_stats` no longer needs a tokio runtime. Wire: none. diff --git a/quest/m1/poll-first/no-spawn/sim-tests.md b/quest/m1/poll-first/no-spawn/sim-tests.md index e317ad695f5..065e5927f99 100644 --- a/quest/m1/poll-first/no-spawn/sim-tests.md +++ b/quest/m1/poll-first/no-spawn/sim-tests.md @@ -16,7 +16,3 @@ m2, or require the part of the spawn audit that converts those two helpers. Decide that when it starts. Public API: none. Wire: none. - -## Required - -- [Admissions and stats are polled](/quest/m1/poll-first/no-spawn/admissions.md) - admissions stop spawning on tokio diff --git a/rs/moq-relay/MIGRATE.md b/rs/moq-relay/MIGRATE.md index 226b006254e..46c29a9b4d5 100644 --- a/rs/moq-relay/MIGRATE.md +++ b/rs/moq-relay/MIGRATE.md @@ -5,6 +5,10 @@ Rolling a cluster across a release also follows the [upgrade guide](https://moq. ## Unreleased +### Stats publishing runs in the cluster driver ([#7673](https://github.com/moq-dev/moq/pull/7673)) + +`Cluster::with_stats` queues its publisher for the `Driver` returned by `Cluster::new` instead of spawning it. Keep polling that driver while serving; `Relay::run` does this for you. Attaching stats needs no Tokio runtime, and dropping the driver cancels publishing too. + ### Smaller default receive windows ([#7624](https://github.com/moq-dev/moq/pull/7624)) `[quic]` defaults to a 4 MiB `receive_window`, a 1 MiB `stream_receive_window`, and a 4 MiB `send_window`, down from 128 MiB, 4 MiB, and 16 MiB, and the smallest `receive_window` accepted here or in `[limits.peer.quic]` is 1 MiB instead of about 64 MiB. diff --git a/rs/moq-relay/benches/http_auth.rs b/rs/moq-relay/benches/http_auth.rs index 21d0f8bbe8c..eacb17591ab 100644 --- a/rs/moq-relay/benches/http_auth.rs +++ b/rs/moq-relay/benches/http_auth.rs @@ -7,10 +7,7 @@ use criterion::{BenchmarkId, Criterion, criterion_group, criterion_main}; use moq_auth::{Grant, lease}; use moq_relay::{auth, cluster, web}; -use std::sync::{ - Arc, - atomic::{AtomicUsize, Ordering}, -}; +use std::task::Poll; use std::time::Duration; type Send = h2::client::SendRequest; @@ -30,25 +27,35 @@ impl Drop for Fixture { } impl Fixture { - async fn new(connections: usize, streams: usize) -> Self { + async fn new(connections: usize, streams: usize, server: bool) -> Self { let _ = rustls::crypto::aws_lc_rs::default_provider().install_default(); - let (auth, mut admissions) = auth::Auth::embedded("bench"); - let waiting = Arc::new(AtomicUsize::new(0)); - let decider = tokio::spawn({ + let waiting = kio::Shared::new(0usize); + let (auth, decider) = if server { + let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap(); + let mut config = auth::Config::default(); + config.url = Some(format!("http://{}/", listener.local_addr().unwrap()).parse().unwrap()); + let auth = config.init("bench", &Default::default(), false).unwrap(); + let app = axum::Router::new() + .route("/", axum::routing::post(decide)) + .with_state(waiting.clone()); + let decider = tokio::spawn(async move { axum::serve(listener, app).await.unwrap() }); + (auth, decider) + } else { + let (auth, mut admissions) = auth::Auth::embedded("bench"); let waiting = waiting.clone(); - async move { + let decider = tokio::spawn(async move { let mut held = Vec::new(); while let Some(admission) = admissions.next().await { if admission.request.path.starts_with("/held") { held.push(admission); - waiting.store(held.len(), Ordering::Release); + *waiting.lock() = held.len(); continue; } - let grant = Grant::new(moq_auth::Patterns::new(), moq_auth::Pattern::all()); - admission.grant(lease::Consumer::fixed(grant)); + admission.grant(lease::Consumer::fixed(grant())); } - } - }); + }); + (auth, decider) + }; let pem = rcgen::generate_simple_self_signed(vec!["localhost".into()]) .unwrap() @@ -58,7 +65,7 @@ impl Fixture { let mut config = web::Config::default(); config.http.listen = Some("127.0.0.1:0".parse().unwrap()); let (cluster, driver) = cluster::Cluster::new(Default::default()).unwrap(); - tokio::spawn(driver.run()); + let driver = tokio::spawn(async move { driver.run().await.unwrap() }); // No admission timeout, so held requests stay waiting however long setup and the // measurement take. let web = web::Web::new(auth, cluster, certificates, config) @@ -71,7 +78,7 @@ impl Fixture { let _ = web.serve(routes).await; }); - let mut tasks = vec![decider, server]; + let mut tasks = vec![decider, server, driver]; let mut held = Vec::new(); for connection in 0..connections { let mut send = connect(addr, &mut tasks).await; @@ -84,9 +91,17 @@ impl Fixture { held.push((send, responses)); } let measured = connect(addr, &mut tasks).await; - while waiting.load(Ordering::Acquire) < connections * streams { - tokio::time::sleep(Duration::from_millis(1)).await; - } + drop( + waiting + .wait(|count| { + if **count == connections * streams { + Poll::Ready(()) + } else { + Poll::Pending + } + }) + .await, + ); Self { measured, @@ -106,6 +121,22 @@ impl Fixture { } } +fn grant() -> Grant { + Grant::new(moq_auth::Patterns::new(), moq_auth::Pattern::all()) +} + +async fn decide( + axum::extract::State(waiting): axum::extract::State>, + axum::Json(request): axum::Json, +) -> axum::Json { + if request.path.starts_with("/held") { + *waiting.lock() += 1; + std::future::pending().await + } else { + axum::Json(grant()) + } +} + async fn connect(addr: std::net::SocketAddr, tasks: &mut Vec>) -> Send { let tcp = tokio::net::TcpStream::connect(addr).await.unwrap(); let (send, connection) = h2::client::handshake(tcp).await.unwrap(); @@ -126,24 +157,31 @@ fn admission(c: &mut Criterion) { .enable_all() .build() .unwrap(); - let mut group = c.benchmark_group("relay_http_admission"); - group.sample_size(10); - group.warm_up_time(Duration::from_millis(100)); - group.measurement_time(Duration::from_millis(300)); - // Each connection may hold up to the verification budget (128 by default) at once. - for connections in [1, 16, 64] { - for streams in [0, 16, 64] { - let mut fixture = runtime.block_on(Fixture::new(connections, streams)); - group.bench_with_input( - BenchmarkId::new(format!("connections={connections}"), streams), - &(connections, streams), - |b, _| { - b.iter(|| runtime.block_on(fixture.round())); - }, - ); + for server in [false, true] { + let name = if server { + "relay_http_auth_server" + } else { + "relay_http_admission" + }; + let mut group = c.benchmark_group(name); + group.sample_size(10); + group.warm_up_time(Duration::from_millis(100)); + group.measurement_time(Duration::from_millis(300)); + // Each connection may hold up to the verification budget (128 by default) at once. + for connections in [1, 16, 64] { + for streams in [0, 16, 64] { + let mut fixture = runtime.block_on(Fixture::new(connections, streams, server)); + group.bench_with_input( + BenchmarkId::new(format!("connections={connections}"), streams), + &(connections, streams), + |b, _| { + b.iter(|| runtime.block_on(fixture.round())); + }, + ); + } } + group.finish(); } - group.finish(); } criterion_group!(benches, admission); diff --git a/rs/moq-relay/src/auth.rs b/rs/moq-relay/src/auth.rs index 032b37c1b32..868fe2db820 100644 --- a/rs/moq-relay/src/auth.rs +++ b/rs/moq-relay/src/auth.rs @@ -820,55 +820,54 @@ enum Decider { } impl Decider { - fn decide(&self, mut admission: Admission) -> Result<(), Error> { + fn decide(&self, request: Request, connection: Option) -> Result { match self { - Self::Embedded(admissions) => admissions - .send(admission) - .map_err(|_| Error::Unavailable("nobody is answering admissions".into()))?, + Self::Embedded(admissions) => { + let (reply, answer) = oneshot::channel(); + admissions + .send(Admission { + request, + connection, + reply, + }) + .map_err(|_| Error::Unavailable("nobody is answering admissions".into()))?; + Ok(Box::pin(async move { + answer + .await + .map_err(|_| Error::Unavailable("the admission went unanswered".into()))? + })) + } Self::Server(client) => { let client = client.clone(); - // A panic drops the admission, which answers it as unavailable. - tokio::spawn(moq_tokio::panic::isolate(async move { - let ask = async { - match &admission.connection { - Some(connection) => client.attach(connection, admission.request.clone()).await, - None => client.connect(admission.request.clone()).await, - } - }; - // The relay stopped waiting (its handshake deadline passed): drop the - // request to the server, so an expired admission leaves nothing in flight. - let lease = tokio::select! { - biased; - () = admission.reply.closed() => return, - lease = ask => lease, - }; - match lease { - Ok(lease) => admission.grant(lease), - Err(err) => admission.refuse(err.into()), - } - })); + // The waiter owns the request, so dropping its answer cancels the HTTP + // exchange and a panic unwinds only the session being admitted. + Ok(Box::pin(async move { + Ok(match connection { + Some(connection) => client.attach(&connection, request).await?, + None => client.connect(request).await?, + }) + })) } // Nothing here can verify a token, so one is refused rather than ignored: // its holder expects it to count, and the public grant is not what it says. - Self::Public(_) if presents_token(&admission.request) => { - tracing::debug!(path = ?admission.request.path, "a token was presented to public rules"); - admission.refuse(Error::Refused(Default::default())); + Self::Public(_) if presents_token(&request) => { + tracing::debug!(path = ?request.path, "a token was presented to public rules"); + Ok(Box::pin(std::future::ready(Err(Error::Refused(Default::default()))))) } - Self::Public(rules) => match rules.authorize(&admission.request.path) { - Ok(access) => { - let grant = Grant::new(access.publish, access.subscribe); - admission.grant(lease::Consumer::fixed(grant)); - } - // A path the rules don't reach is a refusal, never an outage a - // client would retry. - Err(err) => { - tracing::debug!(path = ?admission.request.path, ?err, "public rules refused"); - admission.refuse(Error::Refused(Default::default())); - } - }, - Self::Refuse => admission.refuse(Error::Refused(Default::default())), + Self::Public(rules) => { + let result = match rules.authorize(&request.path) { + Ok(access) => Ok(lease::Consumer::fixed(Grant::new(access.publish, access.subscribe))), + // A path the rules don't reach is a refusal, never an outage a + // client would retry. + Err(err) => { + tracing::debug!(path = ?request.path, ?err, "public rules refused"); + Err(Error::Refused(Default::default())) + } + }; + Ok(Box::pin(std::future::ready(result))) + } + Self::Refuse => Ok(Box::pin(std::future::ready(Err(Error::Refused(Default::default()))))), } - Ok(()) } } @@ -984,13 +983,7 @@ impl Auth { /// Hand one admission to the decider, returning its pending answer. fn submit(&self, request: Request, connection: Option) -> Result { - let (reply, answer) = oneshot::channel(); - self.decider.decide(Admission { - request, - connection, - reply, - })?; - Ok(answer) + self.decider.decide(request, connection) } /// Admit a session on a grant decided locally, bypassing the server: the LAN @@ -1007,7 +1000,7 @@ fn navigates(path: &str) -> bool { } /// A decider's pending answer to one [`Admission`]. -type Answer = oneshot::Receiver>; +type Answer = futures::future::BoxFuture<'static, Result>; fn timed_out() -> Error { Error::Unavailable("the admission timed out".into()) @@ -1016,10 +1009,8 @@ fn timed_out() -> Error { /// Check a decider's answer against the contract every decider is held to: a /// grant that admits nothing or asks for a re-check without a bound is a bug, not /// a refusal. Returns the grant snapshot it checked. -fn answered_with( - answered: Result, oneshot::error::RecvError>, -) -> Result<(lease::Consumer, Grant), Error> { - let consumer = answered.map_err(|_| Error::Unavailable("the admission went unanswered".into()))??; +fn answered_with(answered: Result) -> Result<(lease::Consumer, Grant), Error> { + let consumer = answered?; let grant = consumer.grant(); grant.validate()?; Ok((consumer, grant)) @@ -1184,6 +1175,45 @@ pub(crate) fn peer(identity: &moq_tokio::tls::PeerIdentity) -> Option accepted.unwrap(), + result = &mut answer => panic!("answered before the server accepted: {result:?}"), + }; + let mut buffer = [0; 1024]; + let received = tokio::select! { + received = socket.read(&mut buffer) => received.unwrap(), + result = &mut answer => panic!("answered before the server replied: {result:?}"), + }; + assert_ne!(received, 0, "the caller drove an HTTP request"); + drop(answer); + // A request awaiting its response cannot return its connection to the pool. + // Cancelling it closes that connection even while the auth server is stalled. + loop { + match socket.read(&mut buffer).await { + Ok(0) => break, + Ok(_) => {} + Err(err) if err.kind() == std::io::ErrorKind::ConnectionReset => break, + Err(err) => panic!("reading the cancelled request: {err}"), + } + } + } + fn patterns(texts: &[&str]) -> moq_auth::Patterns { texts.iter().map(|text| text.parse().unwrap()).collect() } diff --git a/rs/moq-relay/src/cluster.rs b/rs/moq-relay/src/cluster.rs index 69212a577eb..a7a4847cff5 100644 --- a/rs/moq-relay/src/cluster.rs +++ b/rs/moq-relay/src/cluster.rs @@ -1019,14 +1019,16 @@ impl Options { } } -/// The work a [`Cluster`] needs to serve at all: its origin's lifecycle driver and, -/// when the cache has one, the headroom governor. Returned by [`Cluster::new`]. +/// The work a [`Cluster`] needs to serve: its origin's lifecycle driver, cache +/// governor, and stats publisher. Returned by [`Cluster::new`]. /// /// Nothing runs on its own: poll it, or await [`run`](Self::run), for as long as the /// cluster serves. Dropping it tears the origin down, failing every later mutation. #[must_use = "the origin makes no progress unless its driver is polled"] pub struct Driver { work: kio::Tasks>, + /// Owns queued work too, so dropping the driver cancels it before its first poll. + pending: kio::Producer>>, } impl Driver { @@ -1037,6 +1039,9 @@ impl Driver { /// `" panicked: "`, the error [`Relay::run`](crate::Relay::run) /// exits with. Polling on after that keeps driving the rest. pub fn poll(&mut self, waiter: &kio::Waiter) -> Poll> { + while let Poll::Ready(child) = self.pending.read().poll_pop(waiter) { + self.work.push(child.expect("only the driver owns the queue")); + } let mut failed = None; let poll = self.work.poll_each(waiter, |_, res| { if let Err(err) = res { @@ -1085,9 +1090,9 @@ impl Started { } /// Run the cluster's dials and peer sources on this task until they stop, or - /// until one of them or a task the relay cannot serve without (its stats - /// publisher, ACME renewal, or certificate reload) panics. The origin's own work - /// is the [`Driver`]'s. + /// until one of them or a task the relay cannot serve without (its + /// ACME renewal or certificate reload) panics. The origin, cache governor, and + /// stats publisher are the [`Driver`]'s work. /// /// Standalone, this only waits for such a panic. Returning, a failure /// included, closes every dial as [`Cluster::close`] does. A cancelled `run` @@ -1261,10 +1266,13 @@ pub struct Cluster { /// view always points at the same session in the logs. connection_ids: Arc, - /// The stats publisher, ACME renewal, and certificate reload: a panic in any - /// of them stops [`Relay::run`](crate::Relay::run). + /// ACME renewal and certificate reload: a panic in either stops + /// [`Relay::run`](crate::Relay::run). pub(crate) critical: crate::critical::Critical, + /// Attach work after construction without keeping the driver's queue alive. + pending: kio::Weak>>, + /// All broadcasts, local and remote. Downstream sessions read from here /// (filtered by their auth token) and remote dials both read and write here. pub origin: origin::Producer, @@ -1276,8 +1284,8 @@ pub struct Cluster { /// to a disabled (no-op) registry until [`with_stats`](Self::with_stats) is called. pub stats: moq_net::stats::Registry, - /// Keeps the stats publish task running for as long as any handle on this - /// cluster lives. The task holds only a `Weak` to its producer, so it stops + /// Keeps the stats publisher alive while any cluster handle lives and its + /// driver runs. The task holds only a `Weak` to its producer, so it stops /// when the last [`moq_stats::Producer`] clone drops; parking one here means /// serving and publishing end together, instead of publishing ending early /// because a caller dropped a producer it never asked for. @@ -1335,10 +1343,10 @@ impl Cluster { /// builders do not rebuild the origin. /// /// Returns the cluster with its [`Driver`]: the origin's lifecycle work and the - /// cache governor, which run only while the owner polls it. Poll it for as long - /// as the cluster serves, whether or not [`start`](Self::start) (the mesh half) - /// is ever called; [`Relay::run`](crate::Relay::run) does. Dropping it tears the - /// origin down. + /// cache governor, plus any attached stats publisher. They run only while the + /// owner polls it. Poll it for as long as the cluster serves, whether or not + /// [`start`](Self::start) (the mesh half) is ever called; + /// [`Relay::run`](crate::Relay::run) does. Dropping it tears the origin down. /// /// Errors if `config.id` is set to 0. An unset id picks a fresh random origin. /// Errors too if the `peer.quic` receive window does not fit a QUIC varint, or @@ -1366,6 +1374,7 @@ impl Cluster { crate::configured_tier(config.tier.clone()).context("invalid --cluster-tier")?; peer.quic.validate()?; let mut work = kio::Tasks::new(); + let pending = kio::Producer::new(kio::Queue::new()); let mut origin_config = origin::Config::new(id); if let Some(max) = config.max_hops { origin_config.max_hops = origin::HopLimit::new(max).context("--cluster-max-hops must be from 1 to 32")?; @@ -1401,11 +1410,12 @@ impl Cluster { refusals: Default::default(), connection_ids: Arc::default(), critical: Default::default(), + pending: pending.downgrade(), origin, stats: moq_net::stats::Registry::disabled(), _stats_publisher: None, }; - Ok((cluster, Driver { work })) + Ok((cluster, Driver { work, pending })) } /// Admit a gateway session and scope both origin directions from its grant. @@ -1554,16 +1564,22 @@ impl Cluster { } /// Attach a stats producer, replacing the default disabled registry with its - /// registry, and run its publisher. + /// registry, and queue its publisher for the cluster's [`Driver`]. /// /// Build both with [`stats::Config::build`](crate::stats::Config::build), passing /// [`Self::origin`] so it publishes through the same origin cluster peers read /// from. The cluster holds the producer from here on, so the caller may drop - /// its own handle: publishing lasts exactly as long as the cluster does. A - /// panic in the publisher ends [`Relay::run`](crate::Relay::run), like the - /// cluster's other critical tasks. Must be called within a Tokio runtime. + /// its own handle. Publishing runs only while the driver is polled; dropping + /// the driver cancels it even if producer clones remain. A publisher panic ends + /// [`Relay::run`](crate::Relay::run), like the cluster's other critical tasks. + /// Needs no Tokio runtime; panics if the driver has already been dropped. pub fn with_stats(mut self, stats: moq_stats::Producer, publisher: moq_stats::Publisher) -> Self { - self.critical.spawn("stats publisher", publisher.run()); + self.pending + .upgrade() + .expect("the cluster driver was dropped") + .read() + .try_push(Child::new("stats publisher", publisher.run())) + .expect("only the driver owns the queue"); self.stats = stats.registry().clone(); self.refusals = crate::refusals::Refusals::new(&self.stats); self._stats_publisher = Some(stats); @@ -2596,6 +2612,47 @@ mod tests { } } + #[test] + fn stats_can_be_attached_without_a_runtime() { + let (cluster, driver) = Cluster::new(Options::default()).unwrap(); + let (stats, publisher) = crate::stats::Config { + enabled: true, + ..Default::default() + } + .build(cluster.origin.clone()) + .unwrap(); + let cluster = cluster.with_stats(stats, publisher); + drop((cluster, driver)); + } + + #[kio::test] + async fn stats_wake_and_end_with_the_driver() { + let (cluster, driver) = Cluster::new(Options::default()).unwrap(); + let (stats, publisher) = crate::stats::Config { + enabled: true, + ..Default::default() + } + .build(cluster.origin.clone()) + .unwrap(); + let attach = async move { + let cluster = cluster.with_stats(stats, publisher); + let consumer = cluster.origin.consume(); + let path = Path::from_static(".stats/node"); + let broadcast = consumer.follow(&path, None).unwrap().available().await.unwrap(); + (cluster, broadcast) + }; + // Poll the driver before attaching, so a queued publisher must wake it. + let futures::future::Either::Right(((cluster, broadcast), driver)) = + futures::future::select(Box::pin(driver.run()), Box::pin(attach)).await + else { + panic!("the driver stopped before publishing stats"); + }; + assert!(!broadcast.is_closed()); + drop(driver); + assert!(broadcast.is_closed(), "dropping the driver stopped the publisher"); + drop(cluster); + } + /// The publish task holds only a `Weak` to its producer, so it stops when the /// last `moq_stats::Producer` clone drops. Attaching one must therefore hand /// its lifetime to the cluster: an embedder clones handles off a `Relay` and diff --git a/rs/moq-relay/src/relay.rs b/rs/moq-relay/src/relay.rs index ebdb2be1f36..9619a7c8c4d 100644 --- a/rs/moq-relay/src/relay.rs +++ b/rs/moq-relay/src/relay.rs @@ -89,7 +89,7 @@ pub struct Relay { /// config named a source; `run` refuses to start while this is still held. admissions: Option, cluster: cluster::Cluster, - /// The cluster's origin and cache work, polled for as long as [`Self::run`] + /// The cluster's origin, cache, and stats work, polled for as long as [`Self::run`] /// runs. `None` only once `run` took it. driver: Option, stats: moq_stats::Producer, @@ -137,7 +137,7 @@ impl Relay { /// reading key material), so a returned `Relay` reports its ephemeral ports and /// a taken port fails here. Nothing runs yet: the cluster's /// [`Driver`](crate::cluster::Driver), which holds the origin's lifecycle work and - /// the cache governor, is only stored, and no session is admitted until + /// the cache governor and stats publisher, is only stored, and no session is admitted until /// [`Self::run`] drives both. pub async fn load(config: Config) -> anyhow::Result { // Keep the large debug state machine off the embedder's main-thread stack. diff --git a/rs/moq-relay/src/stats.rs b/rs/moq-relay/src/stats.rs index 2d5fc208a80..1a3be4a2152 100644 --- a/rs/moq-relay/src/stats.rs +++ b/rs/moq-relay/src/stats.rs @@ -117,8 +117,8 @@ impl Config { /// Returns a no-op producer when [`Self::enabled`] is false, so the relay can /// attach the result unconditionally. Hand both to /// [`Cluster::with_stats`](crate::cluster::Cluster::with_stats), which takes over - /// the registry, running the publisher, and keeping it alive (it stops when the - /// last clone of the producer drops). Fails on a zero interval. + /// the registry and keeps the producer alive while its driver runs the publisher. + /// Fails on a zero interval. pub fn build(&self, origin: origin::Producer) -> anyhow::Result<(moq_stats::Producer, moq_stats::Publisher)> { if !self.enabled { return Ok(moq_stats::Producer::new(moq_stats::produce::Config::new())); From c25d48ac80a83a465ac1f97626ba48252599dcfe Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Mon, 2 Nov 2026 22:40:06 -0800 Subject: [PATCH 03/10] fix(relay): bound admission benchmark socket usage and record API decision Co-Authored-By: GPT-6.1 Sol --- quest/m1/poll-first/no-spawn/README.md | 1 + quest/m1/poll-first/no-spawn/admissions.md | 34 ++++++++++++++++++++++ quest/m1/poll-first/no-spawn/sim-tests.md | 4 +++ rs/moq-relay/benches/http_auth.rs | 30 ++++++++++++++----- 4 files changed, 62 insertions(+), 7 deletions(-) create mode 100644 quest/m1/poll-first/no-spawn/admissions.md diff --git a/quest/m1/poll-first/no-spawn/README.md b/quest/m1/poll-first/no-spawn/README.md index 827b8bd270d..ad8a5a53c05 100644 --- a/quest/m1/poll-first/no-spawn/README.md +++ b/quest/m1/poll-first/no-spawn/README.md @@ -49,6 +49,7 @@ binding boundary. ## Required +- [Admissions and stats are polled](/quest/m1/poll-first/no-spawn/admissions.md) - HTTP admissions run inside their waiter, and the stats publisher runs in the cluster's driver - [moq-ffi spawns only its root](/quest/m1/poll-first/no-spawn/ffi.md) - one runtime-owned driver task holds every `Background` as `kio::Tasks` children - [The relay's in-memory tests run on kio's simulator](/quest/m1/poll-first/no-spawn/sim-tests.md) - `rs/moq-relay/tests/integration/connection.rs` runs on the simulator instead of paused tokio diff --git a/quest/m1/poll-first/no-spawn/admissions.md b/quest/m1/poll-first/no-spawn/admissions.md new file mode 100644 index 00000000000..5b31e0814cb --- /dev/null +++ b/quest/m1/poll-first/no-spawn/admissions.md @@ -0,0 +1,34 @@ +# [S] Admissions and stats are polled + +## Goal + +moq-relay spawns no task per HTTP admission, and the stats publisher runs as a +child of the cluster's `Driver`. The caller waiting on an admission answer +owns and polls its HTTP request, so dropping the wait cancels the exchange. + +## Plan + +[moq-dev/moq#7673](https://github.com/moq-dev/moq/pull/7673) implements the +caller-owned admission future and queues stats publishers for the existing +cluster driver. The initial implementation passed `just ci`, including the +runtime-free setup, HTTP cancellation, and stats driver-lifetime tests. + +The caller-owned admission request is settled by the maintainer's D3 on +[moq-dev/moq#7519](https://github.com/moq-dev/moq/pull/7519). Keep it; do not +reintroduce a long-lived decider supervisor. In-band verification slots and +end-event ordering remain unchanged. + +The first local review found a construction tradeoff: the queue keeps +`Cluster::with_stats`, but adds two locks to each driver poll and panics if +stats are attached after its driver drops. Moving stats configuration into +`cluster::Options` lets `Cluster::new` build it against its origin and add the +publisher to the driver directly, removing the handoff entirely. That changes +the public construction API, so it needs the maintainer's pick. + +The review also found that the HTTP/1.1 admission benchmark could exhaust a +1024-fd process limit and wait forever during setup. Its fix keeps the server +sweep within that budget and fails when a held admission completes early. + +## Waiting + +- Maintainer: choose the stats construction API on [moq-dev/moq#7673](https://github.com/moq-dev/moq/pull/7673): keep `Cluster::with_stats` and its queue, or move stats configuration into `cluster::Options` and remove the builder. Recommend `Options`, which removes the queue, its per-poll locks, and the post-driver-drop panic. Check the recorded decision, implement it if needed, and finish local review before marking the PR ready. diff --git a/quest/m1/poll-first/no-spawn/sim-tests.md b/quest/m1/poll-first/no-spawn/sim-tests.md index 065e5927f99..e317ad695f5 100644 --- a/quest/m1/poll-first/no-spawn/sim-tests.md +++ b/quest/m1/poll-first/no-spawn/sim-tests.md @@ -16,3 +16,7 @@ m2, or require the part of the spawn audit that converts those two helpers. Decide that when it starts. Public API: none. Wire: none. + +## Required + +- [Admissions and stats are polled](/quest/m1/poll-first/no-spawn/admissions.md) - admissions stop spawning on tokio diff --git a/rs/moq-relay/benches/http_auth.rs b/rs/moq-relay/benches/http_auth.rs index eacb17591ab..58dc7a2b9f1 100644 --- a/rs/moq-relay/benches/http_auth.rs +++ b/rs/moq-relay/benches/http_auth.rs @@ -5,6 +5,7 @@ #![expect(clippy::disallowed_methods, reason = "host time measures benchmark throughput")] use criterion::{BenchmarkId, Criterion, criterion_group, criterion_main}; +use futures::{StreamExt, stream::FuturesUnordered}; use moq_auth::{Grant, lease}; use moq_relay::{auth, cluster, web}; use std::task::Poll; @@ -91,17 +92,25 @@ impl Fixture { held.push((send, responses)); } let measured = connect(addr, &mut tasks).await; - drop( - waiting + let mut responses: FuturesUnordered<_> = held + .iter_mut() + .flat_map(|(_, responses)| responses.iter_mut()) + .collect(); + tokio::select! { + biased; + result = responses.next(), if !responses.is_empty() => { + panic!("a held admission completed during setup: {result:?}"); + } + _ = waiting .wait(|count| { if **count == connections * streams { Poll::Ready(()) } else { Poll::Pending } - }) - .await, - ); + }) => {} + } + drop(responses); Self { measured, @@ -167,9 +176,16 @@ fn admission(c: &mut Criterion) { group.sample_size(10); group.warm_up_time(Duration::from_millis(100)); group.measurement_time(Duration::from_millis(300)); + // A held HTTP/1.1 auth POST takes two sockets, unlike a multiplexed web + // stream. Keep its full sweep below a process's standard 1024-fd budget. + let (connections, streams) = if server { + ([1, 4, 16], [0, 4, 16]) + } else { + ([1, 16, 64], [0, 16, 64]) + }; // Each connection may hold up to the verification budget (128 by default) at once. - for connections in [1, 16, 64] { - for streams in [0, 16, 64] { + for connections in connections { + for streams in streams { let mut fixture = runtime.block_on(Fixture::new(connections, streams, server)); group.bench_with_input( BenchmarkId::new(format!("connections={connections}"), streams), From f1f490a02a095851094cc4311b09cf2f85915e81 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Mon, 2 Nov 2026 22:46:02 -0800 Subject: [PATCH 04/10] docs(relay): clarify the stats accessor publisher lifetime Co-Authored-By: GPT-6.1 Sol --- rs/moq-relay/src/relay.rs | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/rs/moq-relay/src/relay.rs b/rs/moq-relay/src/relay.rs index 9619a7c8c4d..012b17edd81 100644 --- a/rs/moq-relay/src/relay.rs +++ b/rs/moq-relay/src/relay.rs @@ -518,9 +518,8 @@ impl Relay { &self.cluster } - /// The stats producer, for publishing extra counters through the same - /// registry. [`Self::cluster`] holds a clone, so the publish task lives as - /// long as the cluster whether or not this handle is kept. + /// The stats producer, for publishing extra counters through the same registry. + /// The cluster retains a clone; its driver must keep running to publish. pub fn stats(&self) -> &moq_stats::Producer { &self.stats } From 987f37fa09c9a46bdb2431ffa715eef7e7b9b1dd Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 3 Nov 2026 12:57:56 -0800 Subject: [PATCH 05/10] quest: record the stats construction decision Co-Authored-By: Claude Opus 5.5 --- quest/m1/poll-first/no-spawn/admissions.md | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/quest/m1/poll-first/no-spawn/admissions.md b/quest/m1/poll-first/no-spawn/admissions.md index 5b31e0814cb..b44197c2221 100644 --- a/quest/m1/poll-first/no-spawn/admissions.md +++ b/quest/m1/poll-first/no-spawn/admissions.md @@ -29,6 +29,10 @@ The review also found that the HTTP/1.1 admission benchmark could exhaust a 1024-fd process limit and wait forever during setup. Its fix keeps the server sweep within that budget and fails when a held admission completes early. -## Waiting - -- Maintainer: choose the stats construction API on [moq-dev/moq#7673](https://github.com/moq-dev/moq/pull/7673): keep `Cluster::with_stats` and its queue, or move stats configuration into `cluster::Options` and remove the builder. Recommend `Options`, which removes the queue, its per-poll locks, and the post-driver-drop panic. Check the recorded decision, implement it if needed, and finish local review before marking the PR ready. +Decided 2026-11-03 (maintainer, /quest-unblock): ✅ **Move cluster stats +configuration into `cluster::Options` and remove `Cluster::with_stats`.** +Construction adds the stats publisher directly to the driver, removing the +handoff queue, the two locks per driver poll, and the panic after the driver +drops. Not chosen: keep `with_stats` and its queue. Update every in-tree +caller (moq-relay) and write migration notes in the PR's Impact section and +`rs/moq-relay/MIGRATE.md`. From a52ef10c3698de512162bc66ee7673e2a51a282c Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 3 Nov 2026 12:58:13 -0800 Subject: [PATCH 06/10] refactor(relay)!: configure cluster stats in Options Move stats configuration into cluster::Options and remove Cluster::with_stats. Cluster::new builds the producer on its origin and adds the publisher straight to the driver, dropping the handoff queue, its two locks per driver poll, and the panic after the driver drops. stats::Config::build becomes crate-private. Finishes the admissions quest, so it is deleted with its links. Co-Authored-By: Claude Opus 5.5 --- doc/bin/relay/index.md | 3 +- quest/m1/poll-first/no-spawn/README.md | 1 - quest/m1/poll-first/no-spawn/admissions.md | 38 ---- quest/m1/poll-first/no-spawn/sim-tests.md | 4 - rs/moq-relay/MIGRATE.md | 16 +- rs/moq-relay/benches/http_auth.rs | 1 - rs/moq-relay/benches/session.rs | 6 +- rs/moq-relay/src/auth/admission_tests.rs | 21 +-- rs/moq-relay/src/cluster.rs | 188 ++++++++----------- rs/moq-relay/src/config.rs | 3 +- rs/moq-relay/src/relay.rs | 15 +- rs/moq-relay/src/stats.rs | 14 +- rs/moq-relay/tests/integration/connection.rs | 9 +- 13 files changed, 127 insertions(+), 192 deletions(-) delete mode 100644 quest/m1/poll-first/no-spawn/admissions.md diff --git a/doc/bin/relay/index.md b/doc/bin/relay/index.md index 42cacf28976..ed6344349e5 100644 --- a/doc/bin/relay/index.md +++ b/doc/bin/relay/index.md @@ -79,7 +79,8 @@ relay.with_web(web).run().await?; accessors report the bound addresses, including ports assigned for `:0`. - `run` consumes the relay, so clone the handles your tasks need first. Stats publishing starts when `run` drives the cluster; an application building a - `Cluster` itself must keep polling its returned driver while serving. + `Cluster` itself sets stats in `cluster::Options` and must keep polling the + returned driver while serving. - Build on `web().routes()`: `with_web` replaces the router, so `Router::new()` drops the built-in routes. - A route reads the connection's peer address with axum's diff --git a/quest/m1/poll-first/no-spawn/README.md b/quest/m1/poll-first/no-spawn/README.md index 07487d518da..f6df9f8e797 100644 --- a/quest/m1/poll-first/no-spawn/README.md +++ b/quest/m1/poll-first/no-spawn/README.md @@ -49,7 +49,6 @@ binding boundary. ## Required -- [Admissions and stats are polled](/quest/m1/poll-first/no-spawn/admissions.md) - HTTP admissions run inside their waiter, and the stats publisher runs in the cluster's driver - [moq-ffi spawns only its root](/quest/m1/poll-first/no-spawn/ffi.md) - one runtime-owned driver task holds every `Background` as `kio::Tasks` children - [The relay's in-memory tests run on kio's simulator](/quest/m1/poll-first/no-spawn/sim-tests.md) - `rs/moq-relay/tests/integration/connection.rs` runs on the simulator instead of paused tokio diff --git a/quest/m1/poll-first/no-spawn/admissions.md b/quest/m1/poll-first/no-spawn/admissions.md deleted file mode 100644 index b44197c2221..00000000000 --- a/quest/m1/poll-first/no-spawn/admissions.md +++ /dev/null @@ -1,38 +0,0 @@ -# [S] Admissions and stats are polled - -## Goal - -moq-relay spawns no task per HTTP admission, and the stats publisher runs as a -child of the cluster's `Driver`. The caller waiting on an admission answer -owns and polls its HTTP request, so dropping the wait cancels the exchange. - -## Plan - -[moq-dev/moq#7673](https://github.com/moq-dev/moq/pull/7673) implements the -caller-owned admission future and queues stats publishers for the existing -cluster driver. The initial implementation passed `just ci`, including the -runtime-free setup, HTTP cancellation, and stats driver-lifetime tests. - -The caller-owned admission request is settled by the maintainer's D3 on -[moq-dev/moq#7519](https://github.com/moq-dev/moq/pull/7519). Keep it; do not -reintroduce a long-lived decider supervisor. In-band verification slots and -end-event ordering remain unchanged. - -The first local review found a construction tradeoff: the queue keeps -`Cluster::with_stats`, but adds two locks to each driver poll and panics if -stats are attached after its driver drops. Moving stats configuration into -`cluster::Options` lets `Cluster::new` build it against its origin and add the -publisher to the driver directly, removing the handoff entirely. That changes -the public construction API, so it needs the maintainer's pick. - -The review also found that the HTTP/1.1 admission benchmark could exhaust a -1024-fd process limit and wait forever during setup. Its fix keeps the server -sweep within that budget and fails when a held admission completes early. - -Decided 2026-11-03 (maintainer, /quest-unblock): ✅ **Move cluster stats -configuration into `cluster::Options` and remove `Cluster::with_stats`.** -Construction adds the stats publisher directly to the driver, removing the -handoff queue, the two locks per driver poll, and the panic after the driver -drops. Not chosen: keep `with_stats` and its queue. Update every in-tree -caller (moq-relay) and write migration notes in the PR's Impact section and -`rs/moq-relay/MIGRATE.md`. diff --git a/quest/m1/poll-first/no-spawn/sim-tests.md b/quest/m1/poll-first/no-spawn/sim-tests.md index e317ad695f5..065e5927f99 100644 --- a/quest/m1/poll-first/no-spawn/sim-tests.md +++ b/quest/m1/poll-first/no-spawn/sim-tests.md @@ -16,7 +16,3 @@ m2, or require the part of the spawn audit that converts those two helpers. Decide that when it starts. Public API: none. Wire: none. - -## Required - -- [Admissions and stats are polled](/quest/m1/poll-first/no-spawn/admissions.md) - admissions stop spawning on tokio diff --git a/rs/moq-relay/MIGRATE.md b/rs/moq-relay/MIGRATE.md index 3ba11123696..045e9acf92e 100644 --- a/rs/moq-relay/MIGRATE.md +++ b/rs/moq-relay/MIGRATE.md @@ -5,9 +5,21 @@ Rolling a cluster across a release also follows the [upgrade guide](https://moq. ## Unreleased -### Stats publishing runs in the cluster driver ([#7673](https://github.com/moq-dev/moq/pull/7673)) +### Stats are configured in `cluster::Options` ([#7673](https://github.com/moq-dev/moq/pull/7673)) -`Cluster::with_stats` queues its publisher for the `Driver` returned by `Cluster::new` instead of spawning it. Keep polling that driver while serving; `Relay::run` does this for you. Attaching stats needs no Tokio runtime, and dropping the driver cancels publishing too. +`Cluster::with_stats` is removed, and `stats::Config::build` is no longer public. Pass the stats config to `Cluster::new` instead, which builds the producer on the cluster's origin and runs its publisher in the returned `Driver`: + +```rust +// Before +let (cluster, driver) = Cluster::new(options)?; +let (stats, publisher) = stats_config.build(cluster.origin.clone())?; +let cluster = cluster.with_stats(stats, publisher); + +// After +let (cluster, driver) = Cluster::new(options.with_stats(stats_config))?; +``` + +Read the registry from `cluster.stats`; `Relay::stats` still returns the producer. Publishing runs only while the driver is polled, which `Relay::run` does, and stops when the driver drops. Building stats needs no Tokio runtime, and an invalid stats config now fails `Cluster::new`. ### The iroh transport is removed ([#7345](https://github.com/moq-dev/moq/pull/7345)) diff --git a/rs/moq-relay/benches/http_auth.rs b/rs/moq-relay/benches/http_auth.rs index 58dc7a2b9f1..910b7b1182f 100644 --- a/rs/moq-relay/benches/http_auth.rs +++ b/rs/moq-relay/benches/http_auth.rs @@ -2,7 +2,6 @@ //! holds waiting on the decider. A slope means admitting one request costs more as others //! wait, rather than what the request itself touches. //! The real web listener runs over loopback TCP; timings include one request round trip. -#![expect(clippy::disallowed_methods, reason = "host time measures benchmark throughput")] use criterion::{BenchmarkId, Criterion, criterion_group, criterion_main}; use futures::{StreamExt, stream::FuturesUnordered}; diff --git a/rs/moq-relay/benches/session.rs b/rs/moq-relay/benches/session.rs index 7e3a9ed4220..730adc32264 100644 --- a/rs/moq-relay/benches/session.rs +++ b/rs/moq-relay/benches/session.rs @@ -43,13 +43,11 @@ impl Backend for Relay { options.config.id = Some(id); // The shared sweeps include more announcements than a default ordinary client. options.session.announces = options.peer.announces; - let (cluster, driver) = cluster::Cluster::new(options.with_cache(cache)).unwrap(); - tokio::spawn(driver.run()); let mut stats = stats::Config::default(); stats.enabled = true; stats.node = Some(id.to_string()); - let (producer, publisher) = stats.build(cluster.origin.clone()).unwrap(); - let cluster = cluster.with_stats(producer, publisher); + let (cluster, driver) = cluster::Cluster::new(options.with_cache(cache).with_stats(stats)).unwrap(); + tokio::spawn(driver.run()); let (auth, mut admissions) = auth::Auth::embedded(format!("bench-{id}")); let decider = tokio::spawn(async move { diff --git a/rs/moq-relay/src/auth/admission_tests.rs b/rs/moq-relay/src/auth/admission_tests.rs index 4d1b08a96f1..c010b7281b7 100644 --- a/rs/moq-relay/src/auth/admission_tests.rs +++ b/rs/moq-relay/src/auth/admission_tests.rs @@ -150,11 +150,12 @@ async fn a_moved_gateway_tier_retags_its_stats() { #[tokio::test(start_paused = true)] async fn gateway_admission_refuses_once_in_the_shared_stats_registry() { - let cluster = cluster::Cluster::spawn(cluster::Options::default()).unwrap(); - let (producer, publisher) = - moq_stats::Producer::new(moq_stats::produce::Config::new().with_origin(cluster.origin.clone())); - let registry = producer.registry().clone(); - let cluster = cluster.with_stats(producer, publisher); + let cluster = cluster::Cluster::spawn(cluster::Options::default().with_stats(crate::stats::Config { + enabled: true, + ..Default::default() + })) + .unwrap(); + let registry = cluster.stats.clone(); let (auth, mut admissions) = auth::Auth::embedded("edge"); let (result, ()) = tokio::join!( cluster.admit(&auth, auth.request(Transport::Srt, "/unattributed")), @@ -184,14 +185,12 @@ async fn gateway_admission_refuses_once_in_the_shared_stats_registry() { #[tokio::test] async fn embedded_expired_refusals_keep_verified_root_and_tier() { tokio::time::pause(); - let cluster = cluster::Cluster::spawn(cluster::Options::default()).unwrap(); - let config = crate::stats::Config { + let cluster = cluster::Cluster::spawn(cluster::Options::default().with_stats(crate::stats::Config { enabled: true, ..Default::default() - }; - let (producer, publisher) = config.build(cluster.origin.clone()).unwrap(); - let registry = producer.registry().clone(); - let cluster = cluster.with_stats(producer, publisher); + })) + .unwrap(); + let registry = cluster.stats.clone(); let (auth, mut admissions) = auth::Auth::embedded("edge"); for tier in [None, Some("edge")] { let mut refusal = moq_auth::Refusal::default(); diff --git a/rs/moq-relay/src/cluster.rs b/rs/moq-relay/src/cluster.rs index 2f1dc8e7087..981ae3972f5 100644 --- a/rs/moq-relay/src/cluster.rs +++ b/rs/moq-relay/src/cluster.rs @@ -981,11 +981,13 @@ struct LanAuth { credential: String, } -/// Construction settings for a [`Cluster`]: identity, discovery, and the origin cache. +/// Construction settings for a [`Cluster`]: identity, discovery, the origin cache, +/// and stats publishing. /// /// The origin is built once from these, so cache settings cannot detach a handle -/// taken after construction. Independent services ([`Cluster::with_connect`], -/// [`Cluster::with_stats`]) attach afterwards without rebuilding it. +/// taken after construction, and the stats publisher joins the [`Driver`] from the +/// start. Independent services ([`Cluster::with_connect`]) attach afterwards +/// without rebuilding it. #[derive(Default)] #[non_exhaustive] pub struct Options { @@ -1001,6 +1003,9 @@ pub struct Options { /// `None` uses an unbounded pool with the standard LRU window and no /// media-timestamp ceiling. pub cache: Option, + + /// Stats publishing on the cluster's origin. Disabled by default. + pub stats: crate::stats::Config, } impl Options { @@ -1017,6 +1022,12 @@ impl Options { self.cache = Some(cache); self } + + /// Publish stats on the cluster's origin with this config. + pub fn with_stats(mut self, stats: crate::stats::Config) -> Self { + self.stats = stats; + self + } } /// The work a [`Cluster`] needs to serve: its origin's lifecycle driver, cache @@ -1027,8 +1038,6 @@ impl Options { #[must_use = "the origin makes no progress unless its driver is polled"] pub struct Driver { work: kio::Tasks>, - /// Owns queued work too, so dropping the driver cancels it before its first poll. - pending: kio::Producer>>, } impl Driver { @@ -1039,9 +1048,6 @@ impl Driver { /// `" panicked: "`, the error [`Relay::run`](crate::Relay::run) /// exits with. Polling on after that keeps driving the rest. pub fn poll(&mut self, waiter: &kio::Waiter) -> Poll> { - while let Poll::Ready(child) = self.pending.read().poll_pop(waiter) { - self.work.push(child.expect("only the driver owns the queue")); - } let mut failed = None; let poll = self.work.poll_each(waiter, |_, res| { if let Err(err) = res { @@ -1268,9 +1274,6 @@ pub struct Cluster { /// [`Relay::run`](crate::Relay::run). pub(crate) critical: crate::critical::Critical, - /// Attach work after construction without keeping the driver's queue alive. - pending: kio::Weak>>, - /// All broadcasts, local and remote. Downstream sessions read from here /// (filtered by their auth token) and remote dials both read and write here. pub origin: origin::Producer, @@ -1278,16 +1281,15 @@ pub struct Cluster { /// Stats registry. One instance per relay; sessions pick a billing tier via /// [`stats::Registry::tier`](moq_net::stats::Registry::tier) at acceptance time /// (the default tier unless configured otherwise, or any label the auth API - /// returns) so traffic classes land in separate counter sets. Defaults - /// to a disabled (no-op) registry until [`with_stats`](Self::with_stats) is called. + /// returns) so traffic classes land in separate counter sets. A disabled + /// (no-op) registry unless [`Options::stats`] enabled publishing. pub stats: moq_net::stats::Registry, /// Keeps the stats publisher alive while any cluster handle lives and its - /// driver runs. The task holds only a `Weak` to its producer, so it stops + /// driver runs. The publisher holds only a `Weak` to its producer, so it stops /// when the last [`moq_stats::Producer`] clone drops; parking one here means - /// serving and publishing end together, instead of publishing ending early - /// because a caller dropped a producer it never asked for. - _stats_publisher: Option, + /// serving and publishing end together. + pub(crate) stats_producer: moq_stats::Producer, } /// A gateway or network session admitted with its lease, scoped origins, and stats. @@ -1332,29 +1334,31 @@ impl Cluster { self.origin.hop().id() } - /// Creates a cluster with one origin, using [`Options`] for identity - /// and cache. + /// Creates a cluster with one origin, using [`Options`] for identity, cache, + /// and stats publishing. /// /// Use [`with_connect`](Self::with_connect) to enable dialing remote peers - /// (required when `config.connect` is non-empty), and - /// [`with_stats`](Self::with_stats) to enable metrics publishing. Those - /// builders do not rebuild the origin. + /// (required when `config.connect` is non-empty). That builder does not + /// rebuild the origin. /// - /// Returns the cluster with its [`Driver`]: the origin's lifecycle work and the - /// cache governor, plus any attached stats publisher. They run only while the - /// owner polls it. Poll it for as long as the cluster serves, whether or not + /// Returns the cluster with its [`Driver`]: the origin's lifecycle work, the + /// cache governor, and the stats publisher. They run only while the owner polls + /// it. Poll it for as long as the cluster serves, whether or not /// [`start`](Self::start) (the mesh half) is ever called; - /// [`Relay::run`](crate::Relay::run) does. Dropping it tears the origin down. + /// [`Relay::run`](crate::Relay::run) does. Dropping it tears the origin down + /// and stops publishing stats. A stats publisher panic ends the driver like + /// its other work. Needs no Tokio runtime. /// /// Errors if `config.id` is set to 0. An unset id picks a fresh random origin. - /// Errors too if the `peer.quic` receive window does not fit a QUIC varint, or - /// `config.tier` is not a valid stats tier. + /// Errors too if the `peer.quic` receive window does not fit a QUIC varint, + /// `config.tier` is not a valid stats tier, or the stats config is invalid. pub fn new(options: Options) -> anyhow::Result<(Self, Driver)> { let Options { config, cache, session, peer, + stats, } = options; let id = match config.id { Some(id) => Hop::new(id).context("--cluster-id must be non-zero")?, @@ -1372,7 +1376,6 @@ impl Cluster { crate::configured_tier(config.tier.clone()).context("invalid --cluster-tier")?; peer.quic.validate()?; let mut work = kio::Tasks::new(); - let pending = kio::Producer::new(kio::Queue::new()); let mut origin_config = origin::Config::new(id); if let Some(max) = config.max_hops { origin_config.max_hops = origin::HopLimit::new(max).context("--cluster-max-hops must be from 1 to 32")?; @@ -1388,6 +1391,10 @@ impl Cluster { work.push(Child::new("origin driver", async move { moq_net::time::run(driver).await; })); + // Publish through the same origin cluster peers read from. + let (stats_producer, publisher) = stats.build(origin.clone())?; + work.push(Child::new("stats publisher", publisher.run())); + let stats = stats_producer.registry().clone(); let nodes = crate::nodes::Nodes::default(); tracing::info!(hop_id = %origin.hop(), configured = config.id.is_some(), "cluster initialized"); let cluster = Cluster { @@ -1403,15 +1410,14 @@ impl Cluster { #[cfg(feature = "cluster-lan")] lan_auth: Arc::new(std::sync::OnceLock::new()), nodes, - refusals: Default::default(), + refusals: crate::refusals::Refusals::new(&stats), connection_ids: Arc::default(), critical: Default::default(), - pending: pending.downgrade(), origin, - stats: moq_net::stats::Registry::disabled(), - _stats_publisher: None, + stats, + stats_producer, }; - Ok((cluster, Driver { work, pending })) + Ok((cluster, Driver { work })) } /// Admit a gateway session and scope both origin directions from its grant. @@ -1552,29 +1558,6 @@ impl Cluster { self.connection_ids.fetch_add(1, Ordering::Relaxed) } - /// Attach a stats producer, replacing the default disabled registry with its - /// registry, and queue its publisher for the cluster's [`Driver`]. - /// - /// Build both with [`stats::Config::build`](crate::stats::Config::build), passing - /// [`Self::origin`] so it publishes through the same origin cluster peers read - /// from. The cluster holds the producer from here on, so the caller may drop - /// its own handle. Publishing runs only while the driver is polled; dropping - /// the driver cancels it even if producer clones remain. A publisher panic ends - /// [`Relay::run`](crate::Relay::run), like the cluster's other critical tasks. - /// Needs no Tokio runtime; panics if the driver has already been dropped. - pub fn with_stats(mut self, stats: moq_stats::Producer, publisher: moq_stats::Publisher) -> Self { - self.pending - .upgrade() - .expect("the cluster driver was dropped") - .read() - .try_push(Child::new("stats publisher", publisher.run())) - .expect("only the driver owns the queue"); - self.stats = stats.registry().clone(); - self.refusals = crate::refusals::Refusals::new(&self.stats); - self._stats_publisher = Some(stats); - self - } - /// Billing tier cluster-peer traffic records under (`--cluster-tier`). /// An absent or empty label selects the default unprefixed tier. fn cluster_tier(&self) -> Tier { @@ -2595,38 +2578,39 @@ mod tests { } } - #[test] - fn stats_can_be_attached_without_a_runtime() { - let (cluster, driver) = Cluster::new(Options::default()).unwrap(); - let (stats, publisher) = crate::stats::Config { + fn with_stats() -> Options { + Options::default().with_stats(crate::stats::Config { enabled: true, ..Default::default() - } - .build(cluster.origin.clone()) - .unwrap(); - let cluster = cluster.with_stats(stats, publisher); + }) + } + + #[test] + fn stats_build_without_a_runtime() { + let (cluster, driver) = Cluster::new(with_stats()).unwrap(); + assert!(cluster.stats.is_enabled()); drop((cluster, driver)); } - #[kio::test] - async fn stats_wake_and_end_with_the_driver() { - let (cluster, driver) = Cluster::new(Options::default()).unwrap(); - let (stats, publisher) = crate::stats::Config { + #[test] + fn invalid_stats_config_errors() { + let options = Options::default().with_stats(crate::stats::Config { enabled: true, + interval: Some(Duration::ZERO.into()), ..Default::default() - } - .build(cluster.origin.clone()) - .unwrap(); - let attach = async move { - let cluster = cluster.with_stats(stats, publisher); - let consumer = cluster.origin.consume(); - let path = Path::from_static(".stats/node"); - let broadcast = consumer.follow(&path, None).unwrap().available().await.unwrap(); - (cluster, broadcast) - }; - // Poll the driver before attaching, so a queued publisher must wake it. - let futures::future::Either::Right(((cluster, broadcast), driver)) = - futures::future::select(Box::pin(driver.run()), Box::pin(attach)).await + }); + let err = Cluster::new(options).err().expect("a zero interval is refused"); + assert!(format!("{err}").contains("stats.interval"), "got: {err}"); + } + + #[kio::test] + async fn stats_end_with_the_driver() { + let (cluster, driver) = Cluster::new(with_stats()).unwrap(); + let consumer = cluster.origin.consume(); + let path = Path::from_static(".stats/node"); + let announced = async { consumer.follow(&path, None).unwrap().available().await.unwrap() }; + let futures::future::Either::Right((broadcast, driver)) = + futures::future::select(Box::pin(driver.run()), Box::pin(announced)).await else { panic!("the driver stopped before publishing stats"); }; @@ -2637,27 +2621,23 @@ mod tests { } /// The publish task holds only a `Weak` to its producer, so it stops when the - /// last `moq_stats::Producer` clone drops. Attaching one must therefore hand - /// its lifetime to the cluster: an embedder clones handles off a `Relay` and - /// does not have to keep the producer, and a relay that keeps serving while - /// silently publishing nothing is exactly the class of failure this API - /// exists to rule out. Moving the ONLY handle in must keep it alive. + /// last `moq_stats::Producer` clone drops. The cluster must therefore hold the + /// producer itself: a relay that keeps serving while silently publishing + /// nothing is exactly the class of failure this rules out. /// /// Asserts the broadcast is still live AFTER a few publish intervals, not /// merely that one appeared: the task publishes once before it can notice its /// producer is gone, so a first announcement races through either way and /// proves nothing. #[tokio::test(start_paused = true)] - async fn stats_publishing_outlives_the_producer_handle() { + async fn stats_publishing_lasts_with_the_cluster() { let config = crate::stats::Config { enabled: true, node: Some("test".to_string()), ..Default::default() }; - let cluster = new_cluster(Config::default()).expect("cluster"); - let (stats, publisher) = config.build(cluster.origin.clone()).expect("stats"); - let cluster = cluster.with_stats(stats, publisher); + let cluster = Cluster::spawn(Options::default().with_stats(config)).expect("cluster"); let path = moq_net::Path::from_static(".stats/node/test"); let consumer = cluster.origin.consume(); @@ -2670,9 +2650,9 @@ mod tests { .expect("stats broadcast resolves"); assert!(broadcast.info().instance.is_some(), "stats announce under an instance"); - // Several publish intervals (1s each by default) after the handle went out - // of scope, the task is still running and its broadcast still announced: a - // request refuses a front whose route retracted. + // Several publish intervals (1s each by default) later, the task is still + // running and its broadcast still announced: a request refuses a front whose + // route retracted. kio::clock::sleep(std::time::Duration::from_millis(2500)).await; let still_live = consumer.request(&path, None).await; assert!( @@ -3281,7 +3261,12 @@ mod tests { id: Some(42), ..Default::default() }) - .with_cache(cache), + .with_cache(cache) + .with_stats(crate::stats::Config { + enabled: true, + node: Some("test".to_string()), + ..Default::default() + }), ) .expect("cluster"); @@ -3290,19 +3275,6 @@ mod tests { assert_eq!(origin.config().cache_duration, duration); assert_eq!(origin.config().pool.expiry(), Some(duration)); - let (stats, publisher) = crate::stats::Config { - enabled: true, - node: Some("test".to_string()), - ..Default::default() - } - .build(origin.clone()) - .expect("stats"); - let cluster = cluster.with_stats(stats, publisher); - - assert_eq!(cluster.origin.hop().id(), origin.hop().id()); - assert_eq!(cluster.origin.config().cache_duration, duration); - assert_eq!(cluster.origin.config().pool.expiry(), Some(duration)); - let broadcast = origin.create_broadcast("cam").expect("create"); broadcast.announce(Default::default()).expect("announce"); let mut track = broadcast.create_track("data", timed()).expect("track"); diff --git a/rs/moq-relay/src/config.rs b/rs/moq-relay/src/config.rs index d2468acb045..1ee853cfac8 100644 --- a/rs/moq-relay/src/config.rs +++ b/rs/moq-relay/src/config.rs @@ -902,8 +902,7 @@ root = ["ca.pem"] ]; let config = Config::parse_and_merge(args).expect("config load"); assert!(config.stats.enabled); - let cluster = cluster::Cluster::spawn(cluster::Options::default()).expect("cluster"); - let _ = config.stats.build(cluster.origin.clone()).expect("stats build"); + let _ = cluster::Cluster::new(cluster::Options::default().with_stats(config.stats)).expect("stats build"); } /// Bare defaults loaded from TOML survive when the CLI does not mention them. diff --git a/rs/moq-relay/src/relay.rs b/rs/moq-relay/src/relay.rs index 309f7d48d42..e63f59b41e5 100644 --- a/rs/moq-relay/src/relay.rs +++ b/rs/moq-relay/src/relay.rs @@ -92,7 +92,6 @@ pub struct Relay { /// The cluster's origin, cache, and stats work, polled for as long as [`Self::run`] /// runs. `None` only once `run` took it. driver: Option, - stats: moq_stats::Producer, internal: internal::Internal, web: web::Web, /// The ACME client, issuing before [`Self::run`] serves and renewing after. @@ -336,17 +335,15 @@ impl Relay { if generated && let Some(fingerprint) = certificates.fingerprints().into_iter().next() { advertise = advertise.with_fingerprint(fingerprint); } - let mut cluster_options = cluster::Options::new(config.cluster).with_cache(cache); + let mut cluster_options = cluster::Options::new(config.cluster) + .with_cache(cache) + .with_stats(config.stats); cluster_options.session = config.limits.client; cluster_options.peer = config.limits.peer; let (cluster, driver) = cluster::Cluster::new(cluster_options)?; let cluster = cluster .with_connect(config.connect.clone(), config.quic.clone()) .with_advertise(advertise); - let (stats, publisher) = config.stats.build(cluster.origin.clone())?; - // The cluster takes over keeping the publish task alive, so an embedder that - // drops the producer keeps publishing for as long as it serves. - let cluster = cluster.with_stats(stats.clone(), publisher); let sessions = crate::session::Registry::new(); let (ready, _) = tokio::sync::watch::channel(Startup::Starting); @@ -411,7 +408,6 @@ impl Relay { admissions, cluster, driver: Some(driver), - stats, internal, web, #[cfg(feature = "acme")] @@ -507,9 +503,10 @@ impl Relay { } /// The stats producer, for publishing extra counters through the same registry. - /// The cluster retains a clone; its driver must keep running to publish. + /// The cluster holds it, so publishing lasts as long as the cluster and its + /// driver do, whether or not this handle is cloned. pub fn stats(&self) -> &moq_stats::Producer { - &self.stats + &self.cluster.stats_producer } /// Graceful-shutdown signal shared by every accepted session and web handler. diff --git a/rs/moq-relay/src/stats.rs b/rs/moq-relay/src/stats.rs index 1a3be4a2152..a51ec2bf361 100644 --- a/rs/moq-relay/src/stats.rs +++ b/rs/moq-relay/src/stats.rs @@ -114,12 +114,14 @@ impl Config { /// Build a [`moq_stats::Producer`] and its [`moq_stats::Publisher`] from this /// config, publishing on `origin`. /// - /// Returns a no-op producer when [`Self::enabled`] is false, so the relay can - /// attach the result unconditionally. Hand both to - /// [`Cluster::with_stats`](crate::cluster::Cluster::with_stats), which takes over - /// the registry and keeps the producer alive while its driver runs the publisher. - /// Fails on a zero interval. - pub fn build(&self, origin: origin::Producer) -> anyhow::Result<(moq_stats::Producer, moq_stats::Publisher)> { + /// Returns a no-op producer when [`Self::enabled`] is false, so + /// [`Cluster::new`](crate::cluster::Cluster::new) can build one unconditionally, + /// keep the producer, and run the publisher on its driver. Fails on a zero + /// interval. + pub(crate) fn build( + &self, + origin: origin::Producer, + ) -> anyhow::Result<(moq_stats::Producer, moq_stats::Publisher)> { if !self.enabled { return Ok(moq_stats::Producer::new(moq_stats::produce::Config::new())); } diff --git a/rs/moq-relay/tests/integration/connection.rs b/rs/moq-relay/tests/integration/connection.rs index 77973741ec9..1131818bf43 100644 --- a/rs/moq-relay/tests/integration/connection.rs +++ b/rs/moq-relay/tests/integration/connection.rs @@ -269,11 +269,10 @@ async fn the_setup_path_reaches_the_decider_and_roots_the_grant() { /// by its reason, under the default tier. #[tokio::test(start_paused = true)] async fn stats_count_admitted_and_refused_sessions() { - let cluster = memory::cluster(); - let (producer, publisher) = - moq_stats::Producer::new(moq_stats::produce::Config::new().with_origin(cluster.origin.clone())); - let registry = producer.registry().clone(); - let cluster = cluster.with_stats(producer, publisher); + let mut config = moq_relay::stats::Config::default(); + config.enabled = true; + let cluster = crate::spawn_cluster(moq_relay::cluster::Options::default().with_stats(config)); + let registry = cluster.stats.clone(); let presence = || { registry .snapshot() From a2a5d1d571f793d7078fe938a878ede4cde7efe5 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 3 Nov 2026 14:27:52 -0800 Subject: [PATCH 07/10] fix(relay): prune abandoned embedded admissions and refresh Cluster docs Embedded admissions queued on an unbounded channel, so every session that gave up stayed queued until the embedder reached it. A shared queue now skips abandoned admissions in Admissions::next and prunes them as it doubles, holding memory for the sessions still waiting. The Cluster type doc now points at Options::with_stats, and the HTTP cancellation test drives Auth::admit. Co-Authored-By: Claude Opus 5.5 --- rs/moq-relay/src/auth.rs | 216 ++++++++++++++++++++++++++++++++---- rs/moq-relay/src/cluster.rs | 10 +- 2 files changed, 203 insertions(+), 23 deletions(-) diff --git a/rs/moq-relay/src/auth.rs b/rs/moq-relay/src/auth.rs index af0a23348da..9e528a515fe 100644 --- a/rs/moq-relay/src/auth.rs +++ b/rs/moq-relay/src/auth.rs @@ -8,7 +8,8 @@ mod refresh; pub(crate) use caps::{Caps, Pacer}; -use std::sync::Arc; +use std::collections::VecDeque; +use std::sync::{Arc, Mutex, MutexGuard, PoisonError}; use axum::http; use moq_auth::{Bytes, Grant, Request, lease}; @@ -16,7 +17,7 @@ use moq_auth::{Pattern, Patterns}; use moq_net::{Path, stats::Tier}; use serde::{Deserialize, Serialize}; use serde_with::{OneOrMany, serde_as}; -use tokio::sync::{mpsc, oneshot}; +use tokio::sync::{Notify, oneshot}; use url::Url; /// The longest a decider may take to verify a token presented in band. A @@ -812,7 +813,7 @@ pub(crate) async fn hold(mut lease: Lease, work: impl std::future::Future), + Embedded(Arc), Server(moq_auth::Client), /// The public rules, as a token with an empty root. Public(Arc), @@ -824,13 +825,11 @@ impl Decider { match self { Self::Embedded(admissions) => { let (reply, answer) = oneshot::channel(); - admissions - .send(Admission { - request, - connection, - reply, - }) - .map_err(|_| Error::Unavailable("nobody is answering admissions".into()))?; + admissions.0.push(Admission { + request, + connection, + reply, + })?; Ok(Box::pin(async move { answer .await @@ -899,8 +898,17 @@ impl Auth { /// returned [`Admissions`] and waits for its [`Admission`] to be granted or /// refused. Dropping the `Admissions` fails every later session as unavailable. pub fn embedded(node: impl Into) -> (Self, Admissions) { - let (sender, receiver) = mpsc::unbounded_channel(); - (Self::new(node, Decider::Embedded(sender)), Admissions(receiver)) + let queue = Arc::new(Queue { + queued: Mutex::new(Queued { + pending: VecDeque::new(), + prune_at: PRUNE_MIN, + closed: false, + dropped: false, + }), + ready: Notify::new(), + }); + let submitter = Arc::new(Submitter(queue.clone())); + (Self::new(node, Decider::Embedded(submitter)), Admissions(queue)) } fn new(node: impl Into, decider: Decider) -> Self { @@ -1038,12 +1046,109 @@ fn still_valid(grant: &Grant) -> Result<(), lease::Reason> { /// slot before they reach the decider. /// Answer in place or hand each [`Admission`] to its own task; nothing here /// serializes them. -pub struct Admissions(mpsc::UnboundedReceiver); +/// +/// An admission whose session stopped waiting is skipped, never handed out, and +/// the queue prunes them as it grows, so a slow decider holds memory for the +/// sessions still waiting rather than every one that gave up. +pub struct Admissions(Arc); impl Admissions { /// The next session to decide, or `None` once every clone of the [`Auth`] is gone. pub async fn next(&mut self) -> Option { - self.0.recv().await + loop { + // A push before this waits stores a permit, so it is never missed. + let ready = self.0.ready.notified(); + { + let mut queued = self.0.lock(); + while let Some(admission) = queued.pending.pop_front() { + if !admission.reply.is_closed() { + return Some(admission); + } + } + if queued.closed { + return None; + } + } + ready.await; + } + } +} + +impl Drop for Admissions { + fn drop(&mut self) { + // Fail every waiting session as unanswered, and every later one as unavailable. + let pending = { + let mut queued = self.0.lock(); + queued.dropped = true; + std::mem::take(&mut queued.pending) + }; + drop(pending); + } +} + +/// The admissions an embedded [`Auth`] has submitted and its [`Admissions`] has +/// yet to take. +struct Queue { + queued: Mutex, + /// Wakes [`Admissions::next`] for a new admission or the last [`Auth`] dropping. + ready: Notify, +} + +struct Queued { + pending: VecDeque, + /// The length at which a push first drops the admissions nobody waits on. + prune_at: usize, + /// Every clone of the [`Auth`] is gone, so no admission arrives again. + closed: bool, + /// The [`Admissions`] is gone, so no admission is answered again. + dropped: bool, +} + +/// The fewest queued admissions that make a push prune the abandoned ones. +/// +/// Each prune sets the next threshold to twice the admissions still waiting, so the +/// queue holds at most twice the sessions waiting at the last prune, and pruning +/// costs a constant amortized time per push. +const PRUNE_MIN: usize = 64; + +impl Queue { + fn lock(&self) -> MutexGuard<'_, Queued> { + self.queued.lock().unwrap_or_else(PoisonError::into_inner) + } + + /// Queue `admission`, failing when nothing will answer it. + fn push(&self, admission: Admission) -> Result<(), Error> { + let abandoned = { + let mut queued = self.lock(); + if queued.dropped { + return Err(Error::Unavailable("nobody is answering admissions".into())); + } + let mut abandoned = VecDeque::new(); + if queued.pending.len() >= queued.prune_at { + let (waiting, gone): (VecDeque<_>, _) = std::mem::take(&mut queued.pending) + .into_iter() + .partition(|admission| !admission.reply.is_closed()); + queued.pending = waiting; + queued.prune_at = (queued.pending.len() * 2).max(PRUNE_MIN); + abandoned = gone; + } + queued.pending.push_back(admission); + abandoned + }; + drop(abandoned); + self.ready.notify_one(); + Ok(()) + } +} + +/// The handle every clone of an embedded [`Auth`] shares: the last one dropping +/// ends [`Admissions::next`]. +struct Submitter(Arc); + +impl Drop for Submitter { + fn drop(&mut self) { + self.0.lock().closed = true; + self.0.ready.notify_one(); } } @@ -1183,24 +1288,25 @@ mod tests { } #[tokio::test] - async fn dropping_a_server_answer_cancels_the_http_exchange() { + async fn dropping_an_admission_cancels_the_http_exchange() { use tokio::io::AsyncReadExt; let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap(); let url = format!("http://{}/", listener.local_addr().unwrap()).parse().unwrap(); let auth = Auth::new("test", Decider::Server(moq_auth::Client::new(url, None).unwrap())); - let mut answer = auth.submit(auth.request(moq_auth::Transport::Http, "/"), None).unwrap(); + // Through `Auth::admit`, so detaching the answer anywhere on that path fails here. + let mut admission = Box::pin(auth.admit(auth.request(moq_auth::Transport::Http, "/"))); let (mut socket, _) = tokio::select! { accepted = listener.accept() => accepted.unwrap(), - result = &mut answer => panic!("answered before the server accepted: {result:?}"), + result = &mut admission => panic!("admitted before the server accepted: {:?}", result.err()), }; let mut buffer = [0; 1024]; let received = tokio::select! { received = socket.read(&mut buffer) => received.unwrap(), - result = &mut answer => panic!("answered before the server replied: {result:?}"), + result = &mut admission => panic!("admitted before the server replied: {:?}", result.err()), }; assert_ne!(received, 0, "the caller drove an HTTP request"); - drop(answer); + drop(admission); // A request awaiting its response cannot return its connection to the pool. // Cancelling it closes that connection even while the auth server is stalled. loop { @@ -1213,6 +1319,78 @@ mod tests { } } + fn submit_embedded(auth: &Auth, path: &str) -> Answer { + auth.submit(auth.request(moq_auth::Transport::Http, path), None) + .unwrap() + } + + #[tokio::test] + async fn an_abandoned_embedded_admission_is_skipped() { + let (auth, mut admissions) = Auth::embedded("test"); + drop(submit_embedded(&auth, "/gone")); + let waiting = submit_embedded(&auth, "/waiting"); + let admission = admissions.next().await.unwrap(); + assert_eq!( + admission.request.path, "/waiting", + "the decider never sees a session that gave up" + ); + admission.refuse(Error::Refused(Default::default())); + assert!(matches!(waiting.await, Err(Error::Refused(_)))); + } + + #[tokio::test] + async fn abandoned_embedded_admissions_are_pruned_without_a_decider() { + let (auth, mut admissions) = Auth::embedded("test"); + let waiting: Vec<_> = (0..PRUNE_MIN / 2) + .map(|i| submit_embedded(&auth, &format!("/waiting/{i}"))) + .collect(); + for i in 0..PRUNE_MIN * 20 { + drop(submit_embedded(&auth, &format!("/gone/{i}"))); + let queued = admissions.0.lock().pending.len(); + assert!(queued <= PRUNE_MIN.max(2 * waiting.len()), "{queued} admissions queued"); + } + for i in 0..waiting.len() { + let admission = admissions.next().await.unwrap(); + assert_eq!( + admission.request.path, + format!("/waiting/{i}"), + "waiting sessions keep their order" + ); + } + drop(waiting); + assert!( + admissions + .0 + .lock() + .pending + .iter() + .all(|admission| admission.reply.is_closed()) + ); + } + + #[tokio::test] + async fn dropping_embedded_admissions_fails_waiting_and_later_sessions() { + let (auth, admissions) = Auth::embedded("test"); + let waiting = submit_embedded(&auth, "/waiting"); + drop(admissions); + assert!(matches!(waiting.await, Err(Error::Unavailable(_)))); + let later = auth.submit(auth.request(moq_auth::Transport::Http, "/later"), None); + assert!(matches!(later.err(), Some(Error::Unavailable(_)))); + } + + #[tokio::test] + async fn embedded_admissions_end_once_every_auth_is_gone() { + let (auth, mut admissions) = Auth::embedded("test"); + let clone = auth.clone(); + let next = tokio::spawn(async move { admissions.next().await.is_none() }); + tokio::task::yield_now().await; + drop(auth); + tokio::task::yield_now().await; + assert!(!next.is_finished(), "a clone can still submit"); + drop(clone); + assert!(next.await.unwrap(), "no admission arrives once every clone is gone"); + } + fn patterns(texts: &[&str]) -> moq_auth::Patterns { texts.iter().map(|text| text.parse().unwrap()).collect() } diff --git a/rs/moq-relay/src/cluster.rs b/rs/moq-relay/src/cluster.rs index 981ae3972f5..0f2eb3208c4 100644 --- a/rs/moq-relay/src/cluster.rs +++ b/rs/moq-relay/src/cluster.rs @@ -1234,10 +1234,12 @@ fn dialer<'a>(cluster: &'a Cluster, token: &'a str) -> impl FnMut(DialTarget) -> /// origin. Loop prevention and route preference come from the hop list carried /// on each announced route (see [`moq_net::origin::Route`]). /// -/// Construct with [`Cluster::new`], then attach a dial template and (optionally) -/// a [`stats::Registry`](moq_net::stats::Registry) with the `with_*` builder -/// methods. Those builders do not rebuild the origin. A cluster without a -/// dial template can serve local sessions but cannot dial remote peers. +/// Construct with [`Cluster::new`]: its [`Options`] carry the limits, cache, and +/// stats ([`Options::with_stats`]), and [`Cluster::stats`] is the resulting +/// registry. Then attach a dial template with [`Cluster::with_connect`] and a LAN +/// advertisement with [`Cluster::with_advertise`]; neither rebuilds the origin. A +/// cluster without a dial template can serve local sessions but cannot dial +/// remote peers. #[derive(Clone)] pub struct Cluster { session_limits: moq_net::session::Limits, From fe70b51db20f82f60950a4c3854493531e7ff537 Mon Sep 17 00:00:00 2001 From: "pullfrog[bot]" <226033991+pullfrog[bot]@users.noreply.github.com> Date: Tue, 3 Nov 2026 23:04:15 +0000 Subject: [PATCH 08/10] fix(relay): reclaim abandoned admissions when waiters drop --- rs/moq-relay/src/auth.rs | 84 ++++++++++++++++++++++++++++++++++++++-- 1 file changed, 80 insertions(+), 4 deletions(-) diff --git a/rs/moq-relay/src/auth.rs b/rs/moq-relay/src/auth.rs index 9e528a515fe..aa4a7f762db 100644 --- a/rs/moq-relay/src/auth.rs +++ b/rs/moq-relay/src/auth.rs @@ -9,6 +9,7 @@ mod refresh; pub(crate) use caps::{Caps, Pacer}; use std::collections::VecDeque; +use std::sync::atomic::{AtomicBool, Ordering}; use std::sync::{Arc, Mutex, MutexGuard, PoisonError}; use axum::http; @@ -825,12 +826,19 @@ impl Decider { match self { Self::Embedded(admissions) => { let (reply, answer) = oneshot::channel(); + let waiting = Arc::new(AtomicBool::new(true)); admissions.0.push(Admission { request, connection, reply, + waiting: waiting.clone(), })?; + let cancel = Cancel { + queue: admissions.0.clone(), + waiting, + }; Ok(Box::pin(async move { + let _cancel = cancel; answer .await .map_err(|_| Error::Unavailable("the admission went unanswered".into()))? @@ -902,6 +910,7 @@ impl Auth { queued: Mutex::new(Queued { pending: VecDeque::new(), prune_at: PRUNE_MIN, + cancelled: 0, closed: false, dropped: false, }), @@ -1048,8 +1057,8 @@ fn still_valid(grant: &Grant) -> Result<(), lease::Reason> { /// serializes them. /// /// An admission whose session stopped waiting is skipped, never handed out, and -/// the queue prunes them as it grows, so a slow decider holds memory for the -/// sessions still waiting rather than every one that gave up. +/// the queue prunes them as it grows or as more waiters give up, so a slow decider +/// holds memory for the sessions still waiting rather than every one that gave up. pub struct Admissions(Arc); impl Admissions { @@ -1061,7 +1070,9 @@ impl Admissions { { let mut queued = self.0.lock(); while let Some(admission) = queued.pending.pop_front() { - if !admission.reply.is_closed() { + // A waiter that gave up already cleared the flag, and its own drop + // reclaimed the entry. Hand out only the ones still waiting. + if admission.waiting.swap(false, Ordering::AcqRel) { return Some(admission); } } @@ -1098,6 +1109,8 @@ struct Queued { pending: VecDeque, /// The length at which a push first drops the admissions nobody waits on. prune_at: usize, + /// Waiters that gave up since the last prune. + cancelled: usize, /// Every clone of the [`Auth`] is gone, so no admission arrives again. closed: bool, /// The [`Admissions`] is gone, so no admission is answered again. @@ -1127,9 +1140,10 @@ impl Queue { if queued.pending.len() >= queued.prune_at { let (waiting, gone): (VecDeque<_>, _) = std::mem::take(&mut queued.pending) .into_iter() - .partition(|admission| !admission.reply.is_closed()); + .partition(|admission| admission.waiting.load(Ordering::Acquire)); queued.pending = waiting; queued.prune_at = (queued.pending.len() * 2).max(PRUNE_MIN); + queued.cancelled = 0; abandoned = gone; } queued.pending.push_back(admission); @@ -1139,6 +1153,50 @@ impl Queue { self.ready.notify_one(); Ok(()) } + + /// Reclaim the admissions whose waiters gave up, without waiting for a push. + /// + /// A burst raises the push threshold while every session still waits; if they + /// all time out afterwards, nothing would cross that threshold again. Scanning + /// once cancellations reach half the queue keeps each reclaim amortized. + fn cancel(&self) { + let abandoned = { + let mut queued = self.lock(); + if queued.dropped || queued.pending.is_empty() { + return; + } + queued.cancelled += 1; + if queued.cancelled < queued.pending.len().div_ceil(2) { + return; + } + let (waiting, gone): (VecDeque<_>, _) = std::mem::take(&mut queued.pending) + .into_iter() + .partition(|admission| admission.waiting.load(Ordering::Acquire)); + queued.pending = waiting; + queued.prune_at = (queued.pending.len() * 2).max(PRUNE_MIN); + queued.cancelled = 0; + gone + }; + drop(abandoned); + } +} + +/// Reclaims the queued admission of a waiter that stopped waiting. +/// +/// The guard rides in the answer future, so dropping it, even before that future +/// is first polled, marks the admission abandoned without needing a later push. +struct Cancel { + queue: Arc, + waiting: Arc, +} + +impl Drop for Cancel { + fn drop(&mut self) { + // A handed-out admission is no longer the queue's to reclaim. + if self.waiting.swap(false, Ordering::AcqRel) { + self.queue.cancel(); + } + } } /// The handle every clone of an embedded [`Auth`] shares: the last one dropping @@ -1160,6 +1218,8 @@ pub struct Admission { pub request: Request, connection: Option, reply: oneshot::Sender>, + /// Whether its waiter still wants it: cleared when handed out or abandoned. + waiting: Arc, } #[cfg(test)] @@ -1368,6 +1428,22 @@ mod tests { ); } + #[tokio::test] + async fn a_cancelled_burst_is_reclaimed_without_a_later_push() { + let (auth, admissions) = Auth::embedded("test"); + let burst: Vec<_> = (0..PRUNE_MIN * 16) + .map(|i| submit_embedded(&auth, &format!("/burst/{i}"))) + .collect(); + // The burst raised the push threshold well above what a small follow-up + // would cross. Nothing is pushed after the sessions give up. + assert!(admissions.0.lock().prune_at > PRUNE_MIN); + drop(burst); + assert!( + admissions.0.lock().pending.is_empty(), + "a burst whose sessions all gave up is reclaimed" + ); + } + #[tokio::test] async fn dropping_embedded_admissions_fails_waiting_and_later_sessions() { let (auth, admissions) = Auth::embedded("test"); From 333631b8e747664d2ec69c0c251c747c321f90e5 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 3 Nov 2026 15:21:09 -0800 Subject: [PATCH 09/10] refactor(relay): sweep abandoned admissions only on give-up pullfrog's guard already counts every waiter that gives up, so the push-time threshold is redundant. Sweep the queue once give-ups since the last sweep reach half of it. Abandoned admissions then stay at most half the queue after each give-up, independent of any past burst, and a sweep stays amortized against the give-ups it reclaims. Co-Authored-By: Claude Opus 5.5 --- rs/moq-relay/src/auth.rs | 98 ++++++++++++++++------------------------ 1 file changed, 39 insertions(+), 59 deletions(-) diff --git a/rs/moq-relay/src/auth.rs b/rs/moq-relay/src/auth.rs index aa4a7f762db..237bb4aedcc 100644 --- a/rs/moq-relay/src/auth.rs +++ b/rs/moq-relay/src/auth.rs @@ -833,12 +833,12 @@ impl Decider { reply, waiting: waiting.clone(), })?; - let cancel = Cancel { + let abandon = Abandon { queue: admissions.0.clone(), waiting, }; Ok(Box::pin(async move { - let _cancel = cancel; + let _abandon = abandon; answer .await .map_err(|_| Error::Unavailable("the admission went unanswered".into()))? @@ -909,8 +909,7 @@ impl Auth { let queue = Arc::new(Queue { queued: Mutex::new(Queued { pending: VecDeque::new(), - prune_at: PRUNE_MIN, - cancelled: 0, + abandoned: 0, closed: false, dropped: false, }), @@ -1057,8 +1056,8 @@ fn still_valid(grant: &Grant) -> Result<(), lease::Reason> { /// serializes them. /// /// An admission whose session stopped waiting is skipped, never handed out, and -/// the queue prunes them as it grows or as more waiters give up, so a slow decider -/// holds memory for the sessions still waiting rather than every one that gave up. +/// the queue sweeps them out as waiters give up, so a slow or stalled decider holds +/// memory for the sessions still waiting rather than every one that gave up. pub struct Admissions(Arc); impl Admissions { @@ -1070,8 +1069,8 @@ impl Admissions { { let mut queued = self.0.lock(); while let Some(admission) = queued.pending.pop_front() { - // A waiter that gave up already cleared the flag, and its own drop - // reclaimed the entry. Hand out only the ones still waiting. + // A waiter that gave up already cleared the flag. Claiming the flag + // here stops its drop from counting it as abandoned. if admission.waiting.swap(false, Ordering::AcqRel) { return Some(admission); } @@ -1107,23 +1106,15 @@ struct Queue { struct Queued { pending: VecDeque, - /// The length at which a push first drops the admissions nobody waits on. - prune_at: usize, - /// Waiters that gave up since the last prune. - cancelled: usize, + /// Waiters that gave up since the last sweep: at least as many as the abandoned + /// admissions left in `pending`. + abandoned: usize, /// Every clone of the [`Auth`] is gone, so no admission arrives again. closed: bool, /// The [`Admissions`] is gone, so no admission is answered again. dropped: bool, } -/// The fewest queued admissions that make a push prune the abandoned ones. -/// -/// Each prune sets the next threshold to twice the admissions still waiting, so the -/// queue holds at most twice the sessions waiting at the last prune, and pruning -/// costs a constant amortized time per push. -const PRUNE_MIN: usize = 64; - impl Queue { fn lock(&self) -> MutexGuard<'_, Queued> { self.queued.lock().unwrap_or_else(PoisonError::into_inner) @@ -1131,70 +1122,59 @@ impl Queue { /// Queue `admission`, failing when nothing will answer it. fn push(&self, admission: Admission) -> Result<(), Error> { - let abandoned = { + { let mut queued = self.lock(); if queued.dropped { return Err(Error::Unavailable("nobody is answering admissions".into())); } - let mut abandoned = VecDeque::new(); - if queued.pending.len() >= queued.prune_at { - let (waiting, gone): (VecDeque<_>, _) = std::mem::take(&mut queued.pending) - .into_iter() - .partition(|admission| admission.waiting.load(Ordering::Acquire)); - queued.pending = waiting; - queued.prune_at = (queued.pending.len() * 2).max(PRUNE_MIN); - queued.cancelled = 0; - abandoned = gone; - } queued.pending.push_back(admission); - abandoned - }; - drop(abandoned); + } self.ready.notify_one(); Ok(()) } - /// Reclaim the admissions whose waiters gave up, without waiting for a push. + /// Count one waiter giving up, sweeping out the abandoned admissions once they + /// may be half the queue. /// - /// A burst raises the push threshold while every session still waits; if they - /// all time out afterwards, nothing would cross that threshold again. Scanning - /// once cancellations reach half the queue keeps each reclaim amortized. - fn cancel(&self) { + /// Abandoned admissions so stay at most half the queue after each give-up, + /// however large a past burst was and whether or not anything is pushed later. + /// A sweep costs the queue's length, paid for by the give-ups counted before it. + fn abandon(&self) { let abandoned = { let mut queued = self.lock(); - if queued.dropped || queued.pending.is_empty() { + if queued.pending.is_empty() { return; } - queued.cancelled += 1; - if queued.cancelled < queued.pending.len().div_ceil(2) { + queued.abandoned += 1; + if queued.abandoned < queued.pending.len().div_ceil(2) { return; } - let (waiting, gone): (VecDeque<_>, _) = std::mem::take(&mut queued.pending) + queued.abandoned = 0; + let (waiting, abandoned): (VecDeque<_>, _) = std::mem::take(&mut queued.pending) .into_iter() .partition(|admission| admission.waiting.load(Ordering::Acquire)); queued.pending = waiting; - queued.prune_at = (queued.pending.len() * 2).max(PRUNE_MIN); - queued.cancelled = 0; - gone + abandoned }; + // Dropped outside the lock, like every other admission the queue releases. drop(abandoned); } } -/// Reclaims the queued admission of a waiter that stopped waiting. +/// Marks a queued admission abandoned once its waiter stops waiting. /// -/// The guard rides in the answer future, so dropping it, even before that future -/// is first polled, marks the admission abandoned without needing a later push. -struct Cancel { +/// The guard rides in the answer future, so dropping that future, even before its +/// first poll, reports the give-up without waiting on a later push. +struct Abandon { queue: Arc, waiting: Arc, } -impl Drop for Cancel { +impl Drop for Abandon { fn drop(&mut self) { - // A handed-out admission is no longer the queue's to reclaim. + // An admission already handed out is no longer the queue's to sweep. if self.waiting.swap(false, Ordering::AcqRel) { - self.queue.cancel(); + self.queue.abandon(); } } } @@ -1401,13 +1381,13 @@ mod tests { #[tokio::test] async fn abandoned_embedded_admissions_are_pruned_without_a_decider() { let (auth, mut admissions) = Auth::embedded("test"); - let waiting: Vec<_> = (0..PRUNE_MIN / 2) + let waiting: Vec<_> = (0..32) .map(|i| submit_embedded(&auth, &format!("/waiting/{i}"))) .collect(); - for i in 0..PRUNE_MIN * 20 { + for i in 0..1024 { drop(submit_embedded(&auth, &format!("/gone/{i}"))); let queued = admissions.0.lock().pending.len(); - assert!(queued <= PRUNE_MIN.max(2 * waiting.len()), "{queued} admissions queued"); + assert!(queued <= 2 * waiting.len(), "{queued} admissions queued"); } for i in 0..waiting.len() { let admission = admissions.next().await.unwrap(); @@ -1431,12 +1411,12 @@ mod tests { #[tokio::test] async fn a_cancelled_burst_is_reclaimed_without_a_later_push() { let (auth, admissions) = Auth::embedded("test"); - let burst: Vec<_> = (0..PRUNE_MIN * 16) + // A stalled decider takes none of the burst, then every session times out + // and nothing is pushed afterwards. + let burst: Vec<_> = (0..1024) .map(|i| submit_embedded(&auth, &format!("/burst/{i}"))) .collect(); - // The burst raised the push threshold well above what a small follow-up - // would cross. Nothing is pushed after the sessions give up. - assert!(admissions.0.lock().prune_at > PRUNE_MIN); + assert_eq!(admissions.0.lock().pending.len(), 1024); drop(burst); assert!( admissions.0.lock().pending.is_empty(), From 9f9b26f14a31c6ef95c6f791f2b1abcb519b94c7 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 3 Nov 2026 15:22:59 -0800 Subject: [PATCH 10/10] test(relay): queued embedded admissions survive the last Auth Co-Authored-By: Claude Opus 5.5 --- rs/moq-relay/src/auth.rs | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/rs/moq-relay/src/auth.rs b/rs/moq-relay/src/auth.rs index 237bb4aedcc..34f40c64cc9 100644 --- a/rs/moq-relay/src/auth.rs +++ b/rs/moq-relay/src/auth.rs @@ -1447,6 +1447,21 @@ mod tests { assert!(next.await.unwrap(), "no admission arrives once every clone is gone"); } + #[tokio::test] + async fn queued_embedded_admissions_survive_the_last_auth() { + let (auth, mut admissions) = Auth::embedded("test"); + let waiting = submit_embedded(&auth, "/waiting"); + drop(auth); + let admission = admissions + .next() + .await + .expect("a queued admission outlives the last Auth"); + assert_eq!(admission.request.path, "/waiting"); + admission.refuse(Error::Refused(Default::default())); + assert!(matches!(waiting.await, Err(Error::Refused(_)))); + assert!(admissions.next().await.is_none()); + } + fn patterns(texts: &[&str]) -> moq_auth::Patterns { texts.iter().map(|text| text.parse().unwrap()).collect() }