Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 3 additions & 1 deletion doc/bin/cli.md
Original file line number Diff line number Diff line change
Expand Up @@ -53,7 +53,9 @@ sessions a reconnect-to-me GOAWAY and waits up to `--drain-timeout` (default
such as `moq-lite-03`, get none and are closed when the window ends. A second
signal exits immediately; `--drain-timeout 0s` closes sessions immediately.
Pending handshakes and admission requests share the same drain window, and an
open stdin pipe does not keep the process alive afterward.
open stdin pipe does not keep the process alive afterward. Admission is part of
the handshake, so `--listen-timeout` bounds it too; `0s` leaves admission without
a deadline.

Add `--stats-enabled` before the first stage to publish accepted-session and
traffic counters with the relay's `--stats-*` settings. An export-only listener
Expand Down
5 changes: 3 additions & 2 deletions doc/bin/relay/auth.md
Original file line number Diff line number Diff line change
Expand Up @@ -373,8 +373,9 @@ refusal. Pass the shared `moq_auth::Refusal` in `auth::Error::Refused` to
`Admission::refuse`, using the same verified-root rule as an HTTP server.
A fixed lease never changes; a `lease::Producer` the application keeps
re-checks, updates, and revokes on its own clock. The relay still closes the
session at the grant's `expires`, and an admission left unanswered for ten
seconds is refused. `Admission::attached()` marks a token presented
session at the grant's `expires`, and a connection whose admission is still
unanswered at its `listen.timeout` handshake deadline is closed; a token
presented in band is refused after ten seconds. `Admission::attached()` marks a token presented
[in band](#in-band-renewal) for a session already admitted under the same id,
so count sessions only on the others. Gateway accept loops can call `Cluster::admit` for the same
scoped session as a native connection. See
Expand Down
6 changes: 4 additions & 2 deletions doc/bin/relay/config.md
Original file line number Diff line number Diff line change
Expand Up @@ -41,8 +41,10 @@ solicit = false # Decline MoQ Solicit, so peers may announc
epoch = false # Decline MoQ Epoch, so routes over moq-transport carry no epoch (draft 17+).
```

`timeout` bounds the whole handshake, transport through MoQ SETUP, so a peer
that connects and never speaks is closed instead of held open by keep-alives.
`timeout` bounds the whole handshake, transport through MoQ SETUP and auth
admission, so a peer that connects and never speaks, or whose admission never
gets an answer, is closed instead of held open by keep-alives. An HTTP read's
admission is bounded by the same value from the request's arrival.

A setting no configured listener reads stops startup rather than being ignored.
A stream-only relay refuses `preferred_v4`, `preferred_v6`, and `lb_id` (or `load_balancer`), which
Expand Down
1 change: 0 additions & 1 deletion quest/m1/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -88,7 +88,6 @@ lands before the cut.
- [Audio jitter target](/quest/m1/audio-jitter-target/README.md) - the playout target is default in both languages; a manual browser proof and a native trace replay remain
- [A/V clock](/quest/m1/av-clock.md) - the audio playhead drives Sync.reference while audio plays, through per-track sync handles
- [Publish channel count](/quest/m1/publish-audio-channel-count.md) - forcing a channel count on an Audio.Capture stops costing the subscriber gaps of silence, and the media fixture's cold-start audio-tone flake is fixed at its cause
- [Handshake deadline covers admission](/quest/m1/handshake-admission-deadline.md) - `listen.timeout` bounds a connection through auth admission on both listeners, replacing the hardcoded admission timeout
- [Restart reset](/quest/m1/stateless-reset-key.md) - a relay restarted with the same `listen.reset_key` stateless-resets its predecessor's connections, so clients reconnect within an RTT instead of the idle timeout
- [Drain cleanup](/quest/m1/drain-cleanup.md) - sessions force-closed at the drain deadline record their lease end and bytes before the relay or CLI exits, while unfinished handshakes stay bounded
- [GOAWAY coverage](/quest/m1/goaway-coverage.md) - every IETF request stream handles GOAWAY, a closed control stream is a violation, and the draft-18 cutoff is honored
Expand Down
4 changes: 0 additions & 4 deletions quest/m1/drain-cleanup.md
Original file line number Diff line number Diff line change
Expand Up @@ -85,7 +85,3 @@ process exits relative to the deadline.

Public API: possibly a small shared drain helper in `moq_relay::shutdown`.
Wire: none.

## Related

- [Handshake deadline covers admission](/quest/m1/handshake-admission-deadline.md) - bounds pending admissions, which the drain deadline must keep cutting
74 changes: 0 additions & 74 deletions quest/m1/handshake-admission-deadline.md

This file was deleted.

1 change: 1 addition & 0 deletions rs/moq-auth/CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
- [**breaking**] Publish and subscribe roles in claims, grants, and permissions now carry `Access { path, rate }`. Optional positive bitrate caps survive signing, authorization, and grant serialization; key scopes refuse them. Gateway embedders must enforce caps or refuse capped grants before admitting media.

- Auth requests distinguish `webtransport` from native `quic`. Upgrade auth servers before relays: older servers reject the new value. Rust and JavaScript auth parsers now map future transport names to `unknown`.
- `Client::connect` no longer times out on its own: the caller's deadline bounds it, and dropping the future drops the request. `attach`, revalidate, and end keep a ten-second bound, reported as `Error::Unavailable`.

## [0.2.1](https://github.com/moq-dev/moq/compare/moq-auth-v0.2.0...moq-auth-v0.2.1) - 2026-10-03

Expand Down
6 changes: 6 additions & 0 deletions rs/moq-auth/MIGRATE.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,12 @@ How to update your code for each breaking change, newest first.

## Unreleased

### `Client::connect` has no timeout of its own (#5765)

`Client::connect` waits on the auth server for as long as its caller does, and dropping the future drops the request.
A caller without its own deadline, such as a handshake deadline, wraps the call in one, for example `tokio::time::timeout(Duration::from_secs(10), client.connect(request))`.
`attach`, revalidate, and end keep their ten-second bound and still report a stalled server as `Error::Unavailable`.

### Typed admission refusals (#5996)

`Error::Refused` now carries a `Refusal`; construct `Error::Refused(Refusal::default())` for an unattributed refusal and match `Error::Refused(refusal)` to read `reason`, `root`, and `tier`.
Expand Down
74 changes: 70 additions & 4 deletions rs/moq-auth/src/client.rs
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,9 @@ impl Client {
/// caller's client identity and roots; `unix://` speaks HTTP over the socket at
/// the URL's path. Anything else is refused here rather than at the first session.
pub fn new(url: Url, tls: Option<rustls::ClientConfig>) -> crate::Result<Self> {
let builder = reqwest::Client::builder().timeout(TIMEOUT);
// No client-wide timeout: `connect` runs under its caller's deadline, and the
// requests that run after the handshake are bounded one by one.
let builder = reqwest::Client::builder();

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1 Badge Add migration steps for callers losing the timeout

When a downstream directly awaits moq_auth::Client::connect (or moq_relay::Auth::admit / Cluster::admit) and the decider never answers, this change now waits forever instead of returning after ten seconds, so existing retry and shutdown paths can silently wedge unless callers add a deadline. I checked rs/moq-auth/MIGRATE.md and rs/moq-relay/MIGRATE.md; neither ## Unreleased section describes that required migration. Add the deadline-wrapping guidance to both affected packages.

AGENTS.md reference: AGENTS.md:L63-L63

Useful? React with 👍 / 👎.

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in 2425324: ## Unreleased entries in rs/moq-auth/MIGRATE.md (Client::connect has no timeout of its own; wrap it in a deadline) and rs/moq-relay/MIGRATE.md (Auth::admit and Cluster::admit are caller-bounded; use Request::within or tokio::time::timeout, and dropping the future withdraws the admission).

(Written by Claude Opus 5.5)


let (builder, url) = match url.scheme() {
"http" => {
Expand Down Expand Up @@ -71,6 +73,11 @@ impl Client {
/// Admit a session: POST `connect`, validate the reply, and return the lease the
/// session holds. The session reports its end and totals through [`lease::Consumer::close`]
/// or drop; credential expiry alone never reports that the connection ended.
///
/// Waits on the server for as long as the caller does: the connection's handshake
/// deadline is the bound, and dropping the future drops the request. Every later
/// request for the session ([`attach`](Self::attach), revalidate, end) is bounded
/// on its own, since nothing else bounds it.
pub async fn connect(&self, request: Request) -> crate::Result<lease::Consumer> {
let context = Context::new(request.clone(), self.identity.clone());
admit(self.clone(), request, context).await
Expand Down Expand Up @@ -253,11 +260,17 @@ impl Post for Client {
}

/// Admit a session through `server` and spawn the driver behind its lease.
///
/// The connection's own `connect` runs under the caller's deadline; an attached
/// credential arrives after the handshake, so its request is bounded here.
async fn admit<S: Post>(server: S, mut request: Request, context: Context) -> crate::Result<lease::Consumer> {
request.event = Event::Connect;
let admission = context.admitting()?;

let grant = ask(&server, &request).await?;
let grant = match context.owner {
true => ask(&server, &request).await?,
false => bounded(ask(&server, &request)).await?,
};
if context.connection.lifecycle.read().ended.is_some() {
return Err(Error::Refused(Default::default()));
}
Expand Down Expand Up @@ -289,6 +302,16 @@ async fn ask<S: Post>(server: &S, request: &Request) -> crate::Result<Grant> {
Ok(grant)
}

/// Finish a request that nothing else bounds within [`TIMEOUT`], or report the
/// server as unavailable, so a stalled server cannot pile up requests.
async fn bounded<T>(request: impl Future<Output = crate::Result<T>>) -> crate::Result<T> {
moq_clock::timeout(TIMEOUT, request).await.unwrap_or_else(|_| {
Err(Error::Unavailable(format!(
"the auth server did not answer within {TIMEOUT:?}"
)))
})
}

/// `url` without its userinfo, query, or fragment, any of which may carry a credential.
fn redact(url: &Url) -> String {
let mut url = url.clone();
Expand Down Expand Up @@ -324,7 +347,7 @@ impl<S: Post> Driver<S> {
bytes,
};
// The session is already gone; nothing to do with a failure but say so.
if let Err(err) = self.server.post_end(&request).await {
if let Err(err) = bounded(self.server.post_end(&request)).await {
tracing::warn!(id = %request.id, %err, "failed to report the session end");
}
}
Expand Down Expand Up @@ -395,7 +418,7 @@ impl<S: Post> Driver<S> {
let server = self.server.clone();
let mut request = self.request.clone();
request.event = Event::Revalidate;
Box::pin(async move { ask(&server, &request).await })
Box::pin(async move { bounded(ask(&server, &request)).await })
}
}

Expand Down Expand Up @@ -612,6 +635,49 @@ mod tests {
);
}

/// `connect` waits as long as its caller does, so a server answering past the
/// fixed bound still admits the session. An attached credential arrives after the
/// handshake, which nothing else bounds, so it keeps the bound.
#[tokio::test(start_paused = true)]
async fn connect_waits_for_a_slow_server_but_attach_does_not() {
#[derive(Clone)]
struct Slow(Script);
impl Post for Slow {
async fn post(&self, request: &Request) -> crate::Result<Grant> {
tokio::time::sleep(TIMEOUT + Duration::from_secs(1)).await;
self.0.post(request).await
}
async fn post_end(&self, request: &Request) -> crate::Result<()> {
self.0.post_end(request).await
}
}
let script = Script::new(Log::default(), |_| Some(Ok(grant(None, None))));
let server = Slow(script.clone());

let start = tokio::time::Instant::now();
let owner = match admit(
server.clone(),
request(),
Context::new(request(), script.identity.clone()),
)
.await
{
Ok(owner) => owner,
Err(err) => panic!("connect gave up on a slow server: {err}"),
};
assert_eq!(start.elapsed(), TIMEOUT + Duration::from_secs(1));

let mut attached = request();
attached.query = Some("jwt=replacement".into());
let context = owner.context().unwrap().attach(&attached, &script.identity).unwrap();
let start = tokio::time::Instant::now();
let Err(err) = admit(server, attached, context).await else {
panic!("an attached credential waited past its bound");
};
assert!(matches!(err, Error::Unavailable(_)), "{err:?}");
assert_eq!(start.elapsed(), TIMEOUT);
}

#[tokio::test]
async fn a_withdrawn_attachment_lands_its_revalidate_before_end() {
#[derive(Clone)]
Expand Down
4 changes: 4 additions & 0 deletions rs/moq-cli/CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0

## [Unreleased]

### Changed

- `moq --listen` bounds auth admission by the listener's `--listen-timeout` handshake deadline instead of a fixed ten seconds.

## [0.14.2](https://github.com/moq-dev/moq/compare/moq-cli-v0.14.1...moq-cli-v0.14.2) - 2026-10-06

### Other
Expand Down
5 changes: 5 additions & 0 deletions rs/moq-cli/MIGRATE.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,11 @@ How to update your invocation and config for each breaking change, newest first.

## Unreleased

### `--listen-timeout` bounds admission (#5765)

`moq --listen` now finishes auth admission within the `--listen-timeout` handshake deadline (default `10s`, counted from the first packet) instead of a separate fixed ten seconds, so a short timeout now refuses a slow auth server sooner and `0s` waits on it forever.
If your auth server can take longer than the handshake timeout allows, raise `--listen-timeout`.

### `--epoch` is removed (#5967)

Remove `--epoch` and `MOQ_EPOCH`: `--epoch` is now an unknown flag, and `MOQ_EPOCH` is ignored.
Expand Down
9 changes: 6 additions & 3 deletions rs/moq-cli/src/main.rs
Original file line number Diff line number Diff line change
Expand Up @@ -188,9 +188,12 @@ impl Serving {
let origin = &self.cluster.origin;
let directions = self.directions;
let auth_request = moq_relay::auth::request_for(&self.auth, &request);
let lease = match self.auth.admit(auth_request).await {
Ok(lease) => lease,
Err(err) => {
// The listener's handshake deadline covers admission; `within` closes a session
// it gives up on with the timeout code.
let lease = match request.within(self.auth.admit(auth_request)).await {

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1 Badge Add the moq-cli timeout migration

For existing moq --listen deployments that set --listen-timeout, this changes auth admission from the old fixed 10-second cap to that flag, whose help declaration in rs/moq-tokio/src/listen.rs:172-177 defines the handshake timeout and permits 0s; short values can now reject slow auth earlier, while zero can wait forever. rs/moq-cli/MIGRATE.md has no ## Unreleased entry telling operators to review that value, so add package-specific migration guidance.

AGENTS.md reference: AGENTS.md:L63-L63

Useful? React with 👍 / 👎.

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in 69aa5f4: rs/moq-cli/MIGRATE.md now has an ## Unreleased entry telling moq --listen operators that admission runs under the --listen-timeout handshake deadline, with 0s waiting forever, and to raise the timeout for slow auth servers. The changelog line now names the flag too.

(Written by Claude Opus 5.5)

Err(err) => return Err(anyhow::Error::new(err).context("admission timed out")),
Ok(Ok(lease)) => lease,
Ok(Err(err)) => {
Comment thread
coderabbitai[bot] marked this conversation as resolved.
Resolved
let status = axum::http::StatusCode::from(&err);
let reject = match status {
axum::http::StatusCode::UNAUTHORIZED => moq_tokio::server::Reject::Unauthorized,
Expand Down
1 change: 1 addition & 0 deletions rs/moq-relay/CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
- [**breaking**] Auth token roles now carry `moq_auth::Access`. Every capped grant is refused until its transport enforces caps, including in-band additions and revalidation. HTTP fetch and announcement endpoints always refuse per-connection caps. Gateway embedders must enforce caps or refuse them.

- Auth requests distinguish `webtransport` from native `quic`. Upgrade auth servers before relays: older servers reject the new value. Rust and JavaScript auth parsers now map future transport names to `unknown`.
- `listen.timeout` bounds auth admission as part of the handshake, replacing the fixed ten-second admission timeout, so an auth server answering `connect` late is admitted within the deadline and `"0"` waits through admission too. HTTP reads bound admission by the web listener's timeout. `Auth::admit` and `Cluster::admit` no longer time out on their own; the caller owns the deadline. In-band token verification keeps its ten-second bound.

## [0.17.2](https://github.com/moq-dev/moq/compare/moq-relay-v0.17.1...moq-relay-v0.17.2) - 2026-10-06

Expand Down
8 changes: 8 additions & 0 deletions rs/moq-relay/MIGRATE.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,14 @@ Rolling a cluster across a release also follows the [upgrade guide](https://moq.

## Unreleased

### Admission runs under the handshake deadline (#5765)

`listen.timeout` now bounds auth admission as part of the handshake, replacing the fixed ten-second admission timeout, so `"0"` also lets admission wait forever.
HTTP reads bound admission by the web listener's timeout.
`Auth::admit` and `Cluster::admit` no longer time out on their own, so a slow embedded decider no longer refuses after ten seconds: the caller owns the deadline.
Bound them with `moq_tokio::server::Request::within` on an accepted session, or wrap them in `tokio::time::timeout`; dropping the future drops the auth server's in-flight request, but an embedded decider is not told and should bound its own work.
Tokens attached in band keep their ten-second bound and are refused as `auth::Error::Unavailable` past it.

### Usage types come from usage-rs 7 (#6060)

The relay's `Args` and `Config` derives now implement usage-rs 7 traits.
Expand Down
Loading