moq-relay: add /health load-shedding endpoint (#1604)

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: kixelated

Cargo.lock

@@ -96,6 +96,22 @@ cert = "cert.pem"
 key = "key.pem"
 ```
 
+### \[web.health]
+
+Thresholds for the `/health` load-shedding probe (CPU, RAM, network, load
+average), or an external `api` to defer the decision to. All keys are optional;
+an unset threshold is not enforced, and with none set `/health` is a pure
+liveness probe. See [HTTP Endpoints](/bin/relay/http) for the full reference and
+value syntax.
+
+```toml
+[web.health]
+cpu = 75       # percent; `75` or `75%`
+ram = "80%"    # percent of total, or absolute (`32GB`)
+tx = "500MB"   # bytes/s; `b` = bits, `B` = bytes (`4Gb`)
+load5 = "80%"  # load average; raw (`6.0`) or percent of cores; Unix only
+```
+
 ### \[auth]
 
 Authentication configuration.

doc/bin/relay/config.md

@@ -77,6 +77,67 @@ curl http://localhost:4443/certificate.sha256
 # f4:a3:b2:... (hex-encoded fingerprint)
 ```
 
+### GET /health
+
+A liveness and load-shedding probe for upstream load balancers.
+
+- Returns `200` with the body `ok` when every configured threshold passes.
+- Returns `503` with the body `overloaded`, followed by one line per breached threshold, otherwise.
+
+With no thresholds configured it's a pure liveness probe (always `200`).
+Each threshold is independent and only enforced when set, so you can mix and match.
+It's unauthenticated so probes don't need a token.
+
+```bash
+curl -i http://localhost:4443/health
+# HTTP/1.1 503 Service Unavailable
+# overloaded
+# cpu 82.1% exceeds 75%
+# tx 612.0MB/s exceeds 500.0MB/s
+```
+
+Thresholds are read from the host via the cross-platform [`sysinfo`](https://crates.io/crates/sysinfo) crate.
+Metrics are sampled in the background every `interval` seconds (default 2).
+
+```toml
+[web.health]
+# Return 503 when global CPU usage exceeds this percentage. Accepts `75` or `75%`.
+cpu = 75
+
+# Return 503 when memory usage exceeds a percentage of total RAM (`80%`)
+# or an absolute used-bytes amount (`32GB`, `32GiB`).
+ram = "80%"
+
+# Return 503 when aggregate received/transmitted throughput exceeds this rate.
+# A unit is required; lowercase `b` is bits, uppercase `B` is bytes (`4Gb`, `500MB`).
+# `/s` is always implied. Useful for shedding before you saturate the NIC.
+rx = "4Gb"
+tx = "500MB"
+
+# Return 503 when the load average exceeds these limits. Each accepts a raw
+# value (`6.0`) or a percentage of CPU cores (`80%`, i.e. a load of
+# `0.8 * cores` — so `100%` is one runnable task per core). Unix only;
+# these keys are rejected on Windows (which has no load average).
+load1 = "8.0"
+load5 = "80%"
+load15 = "4.0"
+
+# Seconds between metric samples. Defaults to 2, floored at 1.
+interval = 2
+
+# Defer the decision to another service. On each request the relay GETs this
+# URL (5s timeout); a non-2xx response or an unreachable service counts as a
+# breach (fail closed). Merges with the local thresholds above, so you can use
+# it alone to simply proxy the verdict.
+api = "http://localhost:9876/health"
+```
+
+Every key also has a CLI flag (`--web-health-cpu 75`, `--web-health-ram 80%`,
+`--web-health-rx 4Gb`, `--web-health-tx 500MB`, `--web-health-load1 8.0`,
+`--web-health-load5 80%`, `--web-health-load15 4.0`, `--web-health-interval 2`,
+`--web-health-api http://localhost:9876/health`) and a matching
+`MOQ_WEB_HEALTH_*` environment variable.
+
 ## See Also
 
 - [Relay Configuration](/bin/relay/config) - Full config reference

doc/bin/relay/http.md

@@ -7,7 +7,9 @@ license = "MIT OR Apache-2.0"
 
 version = "0.12.6"
 edition = "2024"
-rust-version.workspace = true
+# Higher than the workspace MSRV: sysinfo 0.39 uses std's `cfg_select!`, stabilized in Rust 1.95.
+# Fine here because moq-relay is a binary, not a published library.
+rust-version = "1.95"
 
 keywords = ["quic", "http3", "webtransport", "media", "live"]
 categories = ["multimedia", "network-programming", "web-programming"]
@@ -50,6 +52,7 @@ rustls = { version = "0.23", features = ["aws-lc-rs"], default-features = false
 serde = { version = "1", features = ["derive"] }
 serde_json = "1"
 serde_with = { version = "3", features = ["json", "base64"] }
+sysinfo = { version = "0.39", default-features = false, features = ["system", "network"] }
 thiserror = "2"
 tokio = { workspace = true, features = ["full"] }
 tokio-rustls = { version = "0.26", default-features = false }

rs/moq-relay/Cargo.toml

@@ -161,10 +161,10 @@ impl DialMap {
 	/// unannounce while a timestamp is pending doesn't reset the clock.
 	fn mark_unannounced(&self, peer: &str, now: Instant) {
 		let mut map = self.inner.lock().expect("dial map poisoned");
-		if let Some(entry) = map.get_mut(peer) {
-			if entry.sources.gossip {
-				entry.unannounced_at.get_or_insert(now);
-			}
+		if let Some(entry) = map.get_mut(peer)
+			&& entry.sources.gossip
+		{
+			entry.unannounced_at.get_or_insert(now);
 		}
 	}
 

rs/moq-relay/src/cluster.rs

@@ -256,4 +256,44 @@ auth_api = "https://api.moq.dev/cluster/auth"
 			"TOML's auth.auth_api must not be clobbered by the CLI re-parse",
 		);
 	}
+
+	/// Same clap+TOML clobber guard for the `[web.health]` thresholds. Each is
+	/// `Option<T>`, so an absent `--web-health-*` CLI flag must leave the
+	/// TOML-configured value untouched during the `update_from` re-parse.
+	static HEALTH_ENV_LOCK: Mutex<()> = Mutex::new(());
+
+	#[test]
+	fn cli_does_not_clobber_toml_health() {
+		let _guard = HEALTH_ENV_LOCK.lock().unwrap_or_else(|e| e.into_inner());
+		// SAFETY: HEALTH_ENV_LOCK serializes this with any sibling test touching
+		// the same env vars.
+		unsafe {
+			std::env::remove_var("MOQ_WEB_HEALTH_CPU");
+			std::env::remove_var("MOQ_WEB_HEALTH_RAM");
+		}
+
+		let toml = r#"
+[web.health]
+cpu = 75.0
+ram = "80%"
+"#;
+		let dir = std::env::temp_dir().join("moq-relay-config-test");
+		std::fs::create_dir_all(&dir).unwrap();
+		let path = dir.join("health-toml-wins.toml");
+		std::fs::write(&path, toml).unwrap();
+
+		let args = vec![std::ffi::OsString::from("moq-relay"), std::ffi::OsString::from(&path)];
+		let config = Config::parse_and_merge(args).expect("config load");
+
+		assert_eq!(
+			config.web.health.cpu,
+			Some(75.0),
+			"TOML's web.health.cpu must not be clobbered by the CLI re-parse"
+		);
+		assert_eq!(
+			config.web.health.ram,
+			Some(crate::MemLimit::Percent(80.0)),
+			"TOML's web.health.ram must not be clobbered by the CLI re-parse"
+		);
+	}
 }