1pub mod ops;
24mod ui;
25
26use std::sync::atomic::{AtomicUsize, Ordering};
27use std::sync::{Arc, OnceLock};
28use std::time::{Duration, Instant};
29
30use crate::application::Application;
31use crate::entry_point::Config;
32use crate::header::Header;
33use crate::mcp::json_escape;
34use crate::request::Request;
35use crate::response::{Response, STATUS_CODE_REASON_PHRASE};
36use crate::server::{Address, ConnectionInfo};
37
38pub const DEFAULT_TOKEN_ENV: &str = "RWS_ADMIN_TOKEN";
40pub const MAX_CONNECTIONS: usize = 32;
42pub const API_PREFIX: &str = "/admin/api/v1";
44
45#[derive(Debug, Clone, Default, PartialEq)]
47pub struct AdminConfig {
48 pub listen: String,
50 pub token_env: String,
52 pub allowed_origins: Vec<String>,
54}
55
56impl AdminConfig {
57 pub fn from_env() -> AdminConfig {
58 let read = |name: &str| std::env::var(name).unwrap_or_default().trim().to_string();
59 let token_env = read(Config::RWS_CONFIG_ADMIN_TOKEN_ENV);
60 AdminConfig {
61 listen: read(Config::RWS_CONFIG_ADMIN_LISTEN),
62 token_env: if token_env.is_empty() { DEFAULT_TOKEN_ENV.to_string() } else { token_env },
63 allowed_origins: read(Config::RWS_CONFIG_ADMIN_ALLOWED_ORIGINS)
64 .split(',')
65 .map(|o| o.trim().trim_end_matches('/').to_string())
66 .filter(|o| !o.is_empty())
67 .collect(),
68 }
69 }
70
71 pub fn enabled(&self) -> bool {
72 !self.listen.is_empty()
73 }
74
75 pub fn token(&self) -> Result<String, String> {
77 match std::env::var(&self.token_env) {
78 Ok(t) if !t.trim().is_empty() => Ok(t.trim().to_string()),
79 _ => Err(format!("the admin token variable {} is unset or empty", self.token_env)),
80 }
81 }
82}
83
84fn started() -> Instant {
86 static STARTED: OnceLock<Instant> = OnceLock::new();
87 *STARTED.get_or_init(Instant::now)
88}
89
90#[derive(Clone)]
92pub struct AdminApi {
93 inner: Arc<Inner>,
94}
95
96type Reloader = Arc<dyn Fn() + Send + Sync>;
97
98struct Inner {
99 token: String,
100 allowed_origins: Vec<String>,
101 reloader: Reloader,
102 reload_wait: Duration,
103}
104
105impl AdminApi {
106 pub fn new(token: impl Into<String>) -> AdminApi {
108 started();
109 crate::log::tail::enable();
110 AdminApi {
111 inner: Arc::new(Inner {
112 token: token.into(),
113 allowed_origins: Vec::new(),
114 reloader: Arc::new(crate::config_reload::request_reload),
115 reload_wait: Duration::from_secs(10),
116 }),
117 }
118 }
119
120 fn edit(self, f: impl FnOnce(&mut Inner)) -> AdminApi {
121 let mut inner = Inner {
122 token: self.inner.token.clone(),
123 allowed_origins: self.inner.allowed_origins.clone(),
124 reloader: Arc::clone(&self.inner.reloader),
125 reload_wait: self.inner.reload_wait,
126 };
127 f(&mut inner);
128 AdminApi { inner: Arc::new(inner) }
129 }
130
131 pub fn allowed_origins(self, origins: Vec<String>) -> AdminApi {
133 self.edit(|i| i.allowed_origins = origins)
134 }
135
136 pub fn reloader(self, reload: impl Fn() + Send + Sync + 'static, wait: Duration) -> AdminApi {
140 self.edit(|i| {
141 i.reloader = Arc::new(reload);
142 i.reload_wait = wait;
143 })
144 }
145
146 fn reload(&self) -> Response {
149 if !crate::metrics::SERVER_READY.load(Ordering::SeqCst) {
150 return error(STATUS_CODE_REASON_PHRASE.n503_service_unavailable, "the server is starting or stopping");
152 }
153 let (before, _) = crate::config_reload::last_reload();
154 (self.inner.reloader)();
155 let deadline = Instant::now() + self.inner.reload_wait;
156 loop {
157 let (count, errors) = crate::config_reload::last_reload();
158 if count > before {
159 let errors: Vec<String> = errors.iter().map(|e| format!("\"{}\"", json_escape(e))).collect();
160 let applied = errors.is_empty();
161 return json(STATUS_CODE_REASON_PHRASE.n200_ok, format!(r#"{{"reloaded":true,"applied":{applied},"reloads":{count},"errors":[{}]}}"#, errors.join(",")));
162 }
163 if Instant::now() >= deadline {
164 return error(STATUS_CODE_REASON_PHRASE.n504_gateway_timeout, "the reload didn't finish in time; check the server log");
165 }
166 std::thread::sleep(Duration::from_millis(20));
167 }
168 }
169
170 fn authorized(&self, request: &Request) -> bool {
171 let Some(sent) = request.header("Authorization").and_then(|h| h.value.strip_prefix("Bearer ").map(str::trim)) else {
172 return false;
173 };
174 crate::proxy_config::constant_time_eq(sent.as_bytes(), self.inner.token.as_bytes())
175 }
176
177 fn origin_allowed(&self, request: &Request) -> bool {
179 let Some(origin) = request.header("Origin").map(|h| h.value.trim().trim_end_matches('/').to_string()) else {
180 return true;
181 };
182 let host = request.header("Host").map(|h| h.value.trim().to_string()).unwrap_or_default();
183 let own = [format!("http://{host}"), format!("https://{host}")];
184 own.contains(&origin) || self.inner.allowed_origins.contains(&origin)
185 }
186}
187
188pub(crate) fn json(status: &crate::response::StatusCodeReasonPhrase, body: String) -> Response {
189 let mut response = Response::json(status, body.into_bytes());
190 response.headers.push(Header::new("Cache-Control", "no-store"));
191 response
192}
193
194pub(crate) fn error(status: &crate::response::StatusCodeReasonPhrase, message: &str) -> Response {
195 json(status, format!(r#"{{"error":"{}"}}"#, json_escape(message)))
196}
197
198impl Application for AdminApi {
199 fn execute(&self, request: &Request, connection: &ConnectionInfo) -> Result<Response, String> {
200 if !self.origin_allowed(request) {
201 return Ok(error(STATUS_CODE_REASON_PHRASE.n403_forbidden, "origin not allowed"));
202 }
203 let path = crate::url::URL::request_target_path(&request.request_uri).unwrap_or_default();
204 if request.method == "GET" || request.method == "HEAD" {
205 if path == "/admin" || path == "/" {
206 return Ok(ui::redirect());
207 }
208 if let Some(file) = ui::file(path) {
209 return Ok(file);
210 }
211 }
212 if !self.authorized(request) {
213 let mut response = error(STATUS_CODE_REASON_PHRASE.n401_unauthorized, "missing or wrong bearer token");
214 response.headers.push(Header::new("WWW-Authenticate", r#"Bearer realm="rws admin""#));
215 return Ok(response);
216 }
217 let Some(route) = path.strip_prefix(API_PREFIX) else {
218 return Ok(error(STATUS_CODE_REASON_PHRASE.n404_not_found, "not found"));
219 };
220 Ok(self.route(request, connection, route.trim_end_matches('/')))
221 }
222}
223
224fn ok(body: String) -> Response {
225 json(STATUS_CODE_REASON_PHRASE.n200_ok, body)
226}
227
228fn bad_request(message: &str) -> Response {
229 error(STATUS_CODE_REASON_PHRASE.n400_bad_request, message)
230}
231
232fn body_bool(request: &Request, key: &str) -> Option<bool> {
234 let body = std::str::from_utf8(&request.body).ok()?;
235 let value = crate::mcp::json_rpc::object_members(body)?.into_iter().find(|(k, _)| k == key)?.1;
236 match value.as_str() {
237 "true" => Some(true),
238 "false" => Some(false),
239 _ => None,
240 }
241}
242
243fn body_str(request: &Request, key: &str) -> Option<String> {
245 let body = std::str::from_utf8(&request.body).ok()?;
246 let value = crate::mcp::json_rpc::object_members(body)?.into_iter().find(|(k, _)| k == key)?.1;
247 value.starts_with('"').then(|| crate::mcp::json_rpc::extract_str(&format!(r#"{{"v":{value}}}"#), "v")).flatten()
248}
249
250fn wrong_method(allowed: &str) -> Response {
252 let mut response = error(STATUS_CODE_REASON_PHRASE.n405_method_not_allowed, &format!("use {allowed}"));
253 response.headers.push(Header::new("Allow", allowed.to_string()));
254 response
255}
256
257fn authz_route(method: &str, route: &str, request: &Request) -> Response {
259 let decoded = |key: &str| query(request, key).map(|v| crate::url::URL::percent_decode(&v)).filter(|v| !v.is_empty());
260 let answer = |result: Result<String, String>, missing_is_404: bool| match result {
263 Ok(body) => ok(body),
264 Err(e) if missing_is_404 && e.starts_with("no authorization configured") => error(STATUS_CODE_REASON_PHRASE.n404_not_found, &e),
265 Err(e) => error(STATUS_CODE_REASON_PHRASE.n400_bad_request, &e),
266 };
267 match (method, route) {
268 ("GET", "/authz") => answer(ops::authz_schema_json(), true),
269 (_, "/authz") => wrong_method("GET"),
270 ("GET", "/authz/tuples") => {
271 let limit = decoded("limit").and_then(|n| n.parse().ok()).unwrap_or(100);
272 answer(ops::authz_tuples_json(decoded("object").as_deref(), decoded("relation").as_deref(), decoded("subject").as_deref(), limit), true)
273 }
274 ("POST", "/authz/tuples") => match body_str(request, "tuple") {
275 Some(tuple) => answer(ops::authz_write(&tuple), true),
276 None => bad_request(r#"expected {"tuple":"doc:42#viewer@user:alice"}"#),
277 },
278 ("DELETE", "/authz/tuples") => match decoded("tuple").or_else(|| body_str(request, "tuple")) {
279 Some(tuple) => answer(ops::authz_delete(&tuple), true),
280 None => bad_request(r#"expected ?tuple=… or {"tuple":"doc:42#viewer@user:alice"}"#),
281 },
282 (_, "/authz/tuples") => wrong_method("GET, POST, DELETE"),
283 ("POST", "/authz/check") => match (body_str(request, "subject"), body_str(request, "relation"), body_str(request, "object")) {
284 (Some(subject), Some(relation), Some(object)) => answer(ops::authz_check(&subject, &relation, &object), true),
285 _ => bad_request(r#"expected {"subject":"user:alice","relation":"viewer","object":"doc:42"}"#),
286 },
287 (_, "/authz/check") => wrong_method("POST"),
288 _ => error(STATUS_CODE_REASON_PHRASE.n404_not_found, "unknown /authz endpoint"),
289 }
290}
291
292fn query(request: &Request, key: &str) -> Option<String> {
294 let (_, query) = request.request_uri.split_once('?')?;
295 query.split('&').find_map(|pair| {
296 let (k, v) = pair.split_once('=').unwrap_or((pair, ""));
297 (k == key).then(|| v.to_string())
298 })
299}
300
301fn parse_ip(ip: &str) -> Option<String> {
302 let ip = crate::url::URL::percent_decode(ip.trim());
303 ip.parse::<std::net::IpAddr>().ok().map(|ip| ip.to_string())
304}
305
306impl AdminApi {
307 fn route(&self, request: &Request, connection: &ConnectionInfo, route: &str) -> Response {
308 let method = request.method.as_str();
309 if let Some(ip) = route.strip_prefix("/blocklist/") {
310 return match (method, parse_ip(ip)) {
311 ("DELETE", Some(ip)) => ok(ops::unblock(&ip)),
312 ("DELETE", None) => bad_request("not an IP address"),
313 _ => wrong_method("DELETE"),
314 };
315 }
316 if let Some(name) = route.strip_prefix("/flags/") {
317 let name = crate::url::URL::percent_decode(name);
318 return match method {
319 "PUT" => match body_bool(request, "enabled") {
320 Some(enabled) if !name.is_empty() => ok(ops::set_flag(&name, enabled)),
321 _ => bad_request(r#"expected {"enabled":true|false}"#),
322 },
323 _ => wrong_method("PUT"),
324 };
325 }
326 if let Some(name) = route.strip_prefix("/upstreams/").and_then(|r| r.strip_suffix("/drain")) {
327 let name = crate::url::URL::percent_decode(name);
328 return match (method, body_str(request, "backend"), body_bool(request, "drained")) {
329 ("PUT", Some(backend), Some(drained)) => match ops::set_drained(&name, &backend, drained) {
330 Ok(body) => ok(body),
331 Err(e) => error(STATUS_CODE_REASON_PHRASE.n404_not_found, &e),
332 },
333 ("PUT", _, _) => bad_request(r#"expected {"backend":"<url>","drained":true|false}"#),
334 _ => wrong_method("PUT"),
335 };
336 }
337 if let Some(name) = route.strip_prefix("/caches/") {
338 let name = crate::url::URL::percent_decode(name);
339 let decoded = |key: &str| query(request, key).map(|v| crate::url::URL::percent_decode(&v));
340 return match method {
341 "DELETE" => match ops::purge_cache(&name, decoded("path").as_deref(), decoded("prefix").as_deref()) {
342 Some(body) => ok(body),
343 None => error(STATUS_CODE_REASON_PHRASE.n404_not_found, &format!("no cache named {name:?}")),
344 },
345 _ => wrong_method("DELETE"),
346 };
347 }
348 if route == "/authz" || route.starts_with("/authz/") {
349 return authz_route(method, route, request);
350 }
351 match (method, route) {
352 ("GET", "/caches") => ok(ops::caches_json()),
353 (_, "/caches") => wrong_method("GET"),
354 ("GET", "/logs") => {
355 let n = query(request, "n").and_then(|n| n.parse().ok()).unwrap_or(100);
356 ok(ops::logs_json(n))
357 }
358 (_, "/logs") => wrong_method("GET"),
359 ("GET", "/logs/stream") => {
360 let (sender, mut response) = crate::sse::SseStream::new().buffer(256).start();
361 if !crate::log::tail::follow(sender) {
362 return error(STATUS_CODE_REASON_PHRASE.n503_service_unavailable, "too many log followers");
363 }
364 response.headers.push(Header::new("Cache-Control", "no-store"));
365 response
366 }
367 (_, "/logs/stream") => wrong_method("GET"),
368 ("GET", "/upstreams") => ok(ops::upstreams_json()),
369 (_, "/upstreams") => wrong_method("GET"),
370 ("GET", "/certificates") => ok(ops::certificates_json()),
371 (_, "/certificates") => wrong_method("GET"),
372 ("POST", "/certificates/renew") => match ops::request_renewal() {
373 true => json(STATUS_CODE_REASON_PHRASE.n202_accepted, r#"{"requested":true}"#.to_string()),
374 false => error(STATUS_CODE_REASON_PHRASE.n404_not_found, "ACME isn't configured: nothing to renew"),
375 },
376 (_, "/certificates/renew") => wrong_method("POST"),
377 ("GET", "/status") => ok(status_json(connection)),
378 (_, "/status") => wrong_method("GET"),
379 ("GET", "/config") => ok(ops::config_json()),
380 (_, "/config") => wrong_method("GET"),
381 ("POST", "/reload") => self.reload(),
382 (_, "/reload") => wrong_method("POST"),
383 ("GET", "/metrics") => ok(ops::metrics_json()),
384 (_, "/metrics") => wrong_method("GET"),
385 ("GET", "/build") => ok(ops::build_features_json()),
386 (_, "/build") => wrong_method("GET"),
387 ("GET", "/rate-limit") => ok(ops::rate_limit_json()),
388 (_, "/rate-limit") => wrong_method("GET"),
389 ("GET", "/rate-limit/check") => match query(request, "ip").as_deref().and_then(parse_ip) {
390 Some(ip) => ok(ops::check_rate_limit_json(&ip)),
391 None => bad_request("expected ?ip=<address>"),
392 },
393 (_, "/rate-limit/check") => wrong_method("GET"),
394 ("GET", "/cors") => ok(ops::cors_json()),
395 (_, "/cors") => wrong_method("GET"),
396 ("GET", "/maintenance") => ok(ops::maintenance_json()),
397 ("PUT", "/maintenance") => match body_bool(request, "active") {
398 Some(active) => ok(ops::set_maintenance(active)),
399 None => bad_request(r#"expected {"active":true|false}"#),
400 },
401 (_, "/maintenance") => wrong_method("GET, PUT"),
402 ("GET", "/blocklist") => ok(ops::blocklist_json()),
403 ("POST", "/blocklist") => match body_str(request, "ip").as_deref().and_then(parse_ip) {
404 Some(ip) => ok(ops::block(&ip)),
405 None => bad_request(r#"expected {"ip":"<address>"}"#),
406 },
407 (_, "/blocklist") => wrong_method("GET, POST"),
408 ("GET", "/flags") => ok(ops::flags_json()),
409 (_, "/flags") => wrong_method("GET"),
410 ("GET", "/cache") => match ops::registered_cache_json() {
411 Some(stats) => ok(stats),
412 None => error(STATUS_CODE_REASON_PHRASE.n404_not_found, "no response cache in this server"),
413 },
414 ("DELETE", "/cache") => match ops::clear_registered_cache() {
415 true => ok(r#"{"cleared":true}"#.to_string()),
416 false => error(STATUS_CODE_REASON_PHRASE.n404_not_found, "no response cache in this server"),
417 },
418 (_, "/cache") => wrong_method("GET, DELETE"),
419 ("GET", "/routes") => ok(ops::registered_routes_json()),
420 (_, "/routes") => wrong_method("GET"),
421 ("GET", "/requests" | "/errors") => {
422 let n = query(request, "n").and_then(|n| n.parse().ok()).unwrap_or(20);
423 ok(ops::recent_json(n, route == "/errors"))
424 }
425 (_, "/requests" | "/errors") => wrong_method("GET"),
426 _ => error(STATUS_CODE_REASON_PHRASE.n404_not_found, "not found"),
427 }
428 }
429}
430
431pub fn features() -> Vec<&'static str> {
433 let mut on = Vec::new();
434 macro_rules! feature {
435 ($($name:literal),*) => { $( if cfg!(feature = $name) { on.push($name); } )* };
436 }
437 feature!("http1", "http2", "http3", "acme", "auth", "sso", "sso-saml", "sso-server", "gateway-api", "tower", "openapi", "mimalloc", "brotli", "zstd", "wasm-plugins");
438 on
439}
440
441fn status_json(connection: &ConnectionInfo) -> String {
442 let env = |name: &str| std::env::var(name).unwrap_or_default();
443 let tls = !env(Config::RWS_CONFIG_TLS_CERT_FILE).is_empty() || !env(Config::RWS_CONFIG_ACME_DOMAINS).is_empty();
444 let redirect = env(Config::RWS_CONFIG_HTTP_REDIRECT_PORT);
445 let features: Vec<String> = features().iter().map(|f| format!("\"{f}\"")).collect();
446 format!(
447 r#"{{"version":"{}","pid":{},"uptime_secs":{},"ready":{},"features":[{}],"listeners":{{"main":{{"address":"{}:{}","tls":{tls}}},"redirect":{},"admin":"{}:{}"}}}}"#,
448 env!("CARGO_PKG_VERSION"),
449 std::process::id(),
450 started().elapsed().as_secs(),
451 crate::metrics::SERVER_READY.load(Ordering::SeqCst),
452 features.join(","),
453 json_escape(&env(Config::RWS_CONFIG_IP)),
454 json_escape(&env(Config::RWS_CONFIG_PORT)),
455 if redirect.trim().is_empty() { "null".to_string() } else { format!("\"{}\"", json_escape(redirect.trim())) },
456 json_escape(&connection.server.ip),
457 connection.server.port,
458 )
459}
460
461pub(crate) fn validate(get: &dyn Fn(&str) -> Option<String>, report: &mut crate::config_check::ConfigReport) {
464 let listen = get(Config::RWS_CONFIG_ADMIN_LISTEN).unwrap_or_default();
465 let listen = listen.trim();
466 if listen.is_empty() {
467 for key in [Config::RWS_CONFIG_ADMIN_TOKEN_ENV, Config::RWS_CONFIG_ADMIN_ALLOWED_ORIGINS] {
468 if get(key).is_some_and(|v| !v.trim().is_empty()) {
469 report.warn("[admin] has settings but no listen: the admin API is off");
470 break;
471 }
472 }
473 return;
474 }
475 match listen.parse::<std::net::SocketAddr>() {
476 Err(_) => report.error(format!("[admin] listen = {listen:?}: expected host:port with an IP address, e.g. \"127.0.0.1:9901\"")),
477 Ok(addr) if !addr.ip().is_loopback() => report.warn(format!(
478 "[admin] listen = {listen:?} is reachable from other hosts: firewall it, or listen on 127.0.0.1 and use an SSH tunnel"
479 )),
480 Ok(_) => {}
481 }
482 let token_env = get(Config::RWS_CONFIG_ADMIN_TOKEN_ENV).map(|v| v.trim().to_string()).filter(|v| !v.is_empty());
483 let token_env = token_env.unwrap_or_else(|| DEFAULT_TOKEN_ENV.to_string());
484 if !crate::config_check::offline() && std::env::var(&token_env).unwrap_or_default().trim().is_empty() {
485 report.error(format!("[admin] reads its token from {token_env}, which is unset or empty: the admin API won't start"));
486 }
487 for origin in get(Config::RWS_CONFIG_ADMIN_ALLOWED_ORIGINS).unwrap_or_default().split(',').map(str::trim).filter(|o| !o.is_empty()) {
488 if !(origin.starts_with("http://") || origin.starts_with("https://")) || origin.trim_end_matches('/').matches('/').count() > 2 {
489 report.error(format!("[admin] allowed_origins: {origin:?} is not an origin (scheme://host[:port])"));
490 }
491 }
492}
493
494pub fn start(config: &AdminConfig) -> Result<Option<std::net::SocketAddr>, String> {
497 if !config.enabled() {
498 return Ok(None);
499 }
500 let token = config.token()?;
501 let listener = std::net::TcpListener::bind(&config.listen).map_err(|e| format!("can't listen on {}: {e}", config.listen))?;
502 let local = listener.local_addr().map_err(|e| e.to_string())?;
503 let api = AdminApi::new(token).allowed_origins(config.allowed_origins.clone());
504 std::thread::Builder::new()
505 .name("rws-admin".to_string())
506 .spawn(move || serve(listener, api))
507 .map_err(|e| e.to_string())?;
508 Ok(Some(local))
509}
510
511pub fn start_from_env() {
514 match start(&AdminConfig::from_env()) {
515 Ok(Some(addr)) => println!("admin API at http://{addr}{API_PREFIX}/"),
516 Ok(None) => {}
517 Err(e) => eprintln!("admin API not started: {e}"),
518 }
519}
520
521fn serve(listener: std::net::TcpListener, api: AdminApi) {
522 let open = Arc::new(AtomicUsize::new(0));
523 for stream in listener.incoming() {
524 let Ok(stream) = stream else { continue };
525 if open.fetch_add(1, Ordering::SeqCst) >= MAX_CONNECTIONS {
526 open.fetch_sub(1, Ordering::SeqCst);
527 continue;
528 }
529 let (api, held) = (api.clone(), Arc::clone(&open));
530 let spawned = std::thread::Builder::new().name("rws-admin-conn".to_string()).spawn(move || {
531 let address = |a: Option<std::net::SocketAddr>| match a {
532 Some(a) => Address { ip: a.ip().to_string(), port: a.port() as i32 },
533 None => Address { ip: String::new(), port: 0 },
534 };
535 let mut connection = ConnectionInfo::new(address(stream.peer_addr().ok()), address(stream.local_addr().ok()));
536 connection.request_size = 16 * 1024;
537 let _ = stream.set_read_timeout(Some(Duration::from_secs(30)));
538 let _ = stream.set_nodelay(true);
539 let _ = crate::server::Server::process(stream, connection, api);
540 held.fetch_sub(1, Ordering::SeqCst);
541 });
542 if spawned.is_err() {
543 open.fetch_sub(1, Ordering::SeqCst);
544 }
545 }
546}
547
548#[cfg(test)]
549mod tests;