Split oversized runtime modules + Async tests hardened

Co-Authored-By: brekotis <93345790+brekotis@users.noreply.github.com>

src/api/handler.rs

@@ -0,0 +1,187 @@
+use super::*;
+
+// Read-only fixed API endpoints.
+mod read_routes;
+// Fixed configuration and lifecycle mutations.
+mod fixed_routes;
+// Dynamic reload and user-resource routes.
+mod user_routes;
+
+pub(super) async fn handle(
+    req: Request<Incoming>,
+    peer: SocketAddr,
+    shared: Arc<ApiShared>,
+) -> Result<Response<Full<Bytes>>, IoError> {
+    let runtime = shared.active_runtime.load_full();
+    let previous_cache_generation = shared.cache_generation.swap(runtime.id, Ordering::AcqRel);
+    if previous_cache_generation != runtime.id {
+        *shared.minimal_cache.lock().await = None;
+        *shared.runtime_edge_connections_cache.lock().await = None;
+    }
+    let shared = Arc::new(shared.for_runtime(runtime.as_ref()));
+    let config_rx = runtime.config_rx.clone();
+    shared
+        .runtime_state
+        .admission_open
+        .store(*runtime.admission_rx.borrow(), Ordering::Relaxed);
+    let request_id = shared.next_request_id();
+    let cfg = config_rx.borrow().clone();
+    let api_cfg = &cfg.server.api;
+
+    if !api_cfg.enabled {
+        return Ok(error_response(
+            request_id,
+            ApiFailure::new(
+                StatusCode::SERVICE_UNAVAILABLE,
+                "api_disabled",
+                "API is disabled",
+            ),
+        ));
+    }
+
+    if !api_cfg.whitelist.is_empty() && !api_cfg.whitelist.iter().any(|net| net.contains(peer.ip()))
+    {
+        return match api_cfg.gray_action {
+            ApiGrayAction::Api => Ok(error_response(
+                request_id,
+                ApiFailure::new(
+                    StatusCode::FORBIDDEN,
+                    "forbidden",
+                    "Source IP is not allowed",
+                ),
+            )),
+            ApiGrayAction::Ok200 => Ok(Response::builder()
+                .status(StatusCode::OK)
+                .header("content-type", "text/html; charset=utf-8")
+                .body(Full::new(Bytes::new()))
+                .unwrap()),
+            ApiGrayAction::Drop => Err(IoError::new(
+                ErrorKind::ConnectionAborted,
+                "api request dropped by gray_action=drop",
+            )),
+        };
+    }
+
+    if !api_cfg.auth_header.is_empty() {
+        let auth_ok = req
+            .headers()
+            .get(AUTHORIZATION)
+            .and_then(|v| v.to_str().ok())
+            .map(|v| auth_header_matches(v, &api_cfg.auth_header))
+            .unwrap_or(false);
+        if !auth_ok {
+            return Ok(error_response(
+                request_id,
+                ApiFailure::new(
+                    StatusCode::UNAUTHORIZED,
+                    "unauthorized",
+                    "Missing or invalid Authorization header",
+                ),
+            ));
+        }
+    }
+
+    let method = req.method().clone();
+    let path = req.uri().path().to_string();
+    let normalized_path = if path.len() > 1 {
+        path.trim_end_matches('/')
+    } else {
+        path.as_str()
+    };
+    let query = req.uri().query().map(str::to_string);
+    let body_limit = api_cfg.request_body_limit_bytes;
+
+    let result = dispatch(
+        req,
+        method,
+        &path,
+        normalized_path,
+        query.as_deref(),
+        body_limit,
+        &shared,
+        cfg.as_ref(),
+        &config_rx,
+        request_id,
+    )
+    .await;
+    match result {
+        Ok(resp) => Ok(resp),
+        Err(error) => Ok(error_response(request_id, error)),
+    }
+}
+
+async fn dispatch(
+    req: Request<Incoming>,
+    method: Method,
+    path: &str,
+    normalized_path: &str,
+    query: Option<&str>,
+    body_limit: usize,
+    shared: &Arc<ApiShared>,
+    cfg: &ProxyConfig,
+    config_rx: &watch::Receiver<Arc<ProxyConfig>>,
+    request_id: u64,
+) -> Result<Response<Full<Bytes>>, ApiFailure> {
+    if web_runtime::is_route(normalized_path) {
+        let web_mutation = method == Method::POST;
+        let result = web_runtime::handle(
+            method,
+            normalized_path,
+            query,
+            req,
+            shared.as_ref(),
+            cfg,
+            request_id,
+            body_limit,
+        )
+        .await;
+        if web_mutation && let Err(error) = &result {
+            shared.runtime_events.record(
+                "api.web.control.failed",
+                format!("path={} code={}", normalized_path, error.code),
+            );
+        }
+        return result;
+    }
+
+    if let Some(response) = read_routes::handle(
+        &method,
+        normalized_path,
+        query,
+        shared.as_ref(),
+        cfg,
+        config_rx,
+    )
+    .await?
+    {
+        return Ok(response);
+    }
+
+    match (method.as_str(), normalized_path) {
+        ("POST", "/v1/users") => {
+            fixed_routes::create_user_route(req, shared, cfg, config_rx, request_id, body_limit)
+                .await
+        }
+        ("GET", "/v1/config") => fixed_routes::get_config_route(shared).await,
+        ("POST", "/v1/system/reload") => {
+            fixed_routes::reload_route(req, shared, cfg, request_id, body_limit).await
+        }
+        ("PATCH", "/v1/config") => {
+            fixed_routes::patch_config_route(req, shared, cfg, query, request_id, body_limit).await
+        }
+        _ => {
+            user_routes::handle(
+                req,
+                &method,
+                path,
+                normalized_path,
+                shared,
+                cfg,
+                config_rx,
+                request_id,
+                body_limit,
+            )
+            .await
+        }
+    }
+}

src/api/handler/fixed_routes.rs

@@ -0,0 +1,149 @@
+use super::*;
+
+pub(super) async fn create_user_route(
+    req: Request<Incoming>,
+    shared: &Arc<ApiShared>,
+    cfg: &ProxyConfig,
+    config_rx: &watch::Receiver<Arc<ProxyConfig>>,
+    request_id: u64,
+    body_limit: usize,
+) -> Result<Response<Full<Bytes>>, ApiFailure> {
+    let api_cfg = &cfg.server.api;
+    if api_cfg.read_only {
+        return Ok(error_response(
+            request_id,
+            ApiFailure::new(
+                StatusCode::FORBIDDEN,
+                "read_only",
+                "API runs in read-only mode",
+            ),
+        ));
+    }
+    let expected_revision = parse_if_match(req.headers());
+    let body = read_json::<CreateUserRequest>(req.into_body(), body_limit).await?;
+    let requested_enabled = body.enabled;
+    let result = create_user(body, expected_revision, shared).await;
+    let (mut data, revision) = match result {
+        Ok(ok) => ok,
+        Err(error) => {
+            shared
+                .runtime_events
+                .record("api.user.create.failed", error.code);
+            return Err(error);
+        }
+    };
+    let runtime_cfg = config_rx.borrow().clone();
+    data.user.in_runtime = runtime_cfg.access.users.contains_key(&data.user.username);
+    if let Some(enabled) = requested_enabled {
+        shared
+            .proxy_shared
+            .set_user_enabled(&data.user.username, enabled);
+        if !enabled {
+            let cancelled = shared
+                .proxy_shared
+                .cancel_user_sessions(&data.user.username);
+            if cancelled > 0 {
+                shared.runtime_events.record(
+                    "api.user.disable.runtime",
+                    format!(
+                        "username={} cancelled_sessions={}",
+                        data.user.username, cancelled
+                    ),
+                );
+            }
+        }
+    }
+    shared.runtime_events.record(
+        "api.user.create.ok",
+        format!("username={}", data.user.username),
+    );
+    let status = if data.user.in_runtime {
+        StatusCode::CREATED
+    } else {
+        StatusCode::ACCEPTED
+    };
+    Ok(success_response(status, data, revision))
+}
+
+pub(super) async fn get_config_route(
+    shared: &Arc<ApiShared>,
+) -> Result<Response<Full<Bytes>>, ApiFailure> {
+    let (value, revision) = config_edit::read_managed_config(&shared.config_path).await?;
+    Ok(success_response(StatusCode::OK, value, revision))
+}
+
+pub(super) async fn reload_route(
+    req: Request<Incoming>,
+    shared: &Arc<ApiShared>,
+    cfg: &ProxyConfig,
+    request_id: u64,
+    body_limit: usize,
+) -> Result<Response<Full<Bytes>>, ApiFailure> {
+    let api_cfg = &cfg.server.api;
+    if api_cfg.read_only {
+        return Ok(error_response(
+            request_id,
+            ApiFailure::new(
+                StatusCode::FORBIDDEN,
+                "read_only",
+                "API runs in read-only mode",
+            ),
+        ));
+    }
+    let expected_revision = parse_if_match(req.headers());
+    let request = read_optional_json::<ReloadRequest>(req.into_body(), body_limit)
+        .await?
+        .unwrap_or_default();
+    request.validate().map_err(ApiFailure::bad_request)?;
+
+    let (accepted, revision) = submit_reload_from_disk(
+        &shared.config_path,
+        shared.mutation_lock.as_ref(),
+        &shared.reload_control,
+        expected_revision.as_deref(),
+        request,
+    )
+    .await?;
+    Ok(success_response(StatusCode::ACCEPTED, accepted, revision))
+}
+
+pub(super) async fn patch_config_route(
+    req: Request<Incoming>,
+    shared: &Arc<ApiShared>,
+    cfg: &ProxyConfig,
+    query: Option<&str>,
+    request_id: u64,
+    body_limit: usize,
+) -> Result<Response<Full<Bytes>>, ApiFailure> {
+    let api_cfg = &cfg.server.api;
+    if api_cfg.read_only {
+        return Ok(error_response(
+            request_id,
+            ApiFailure::new(
+                StatusCode::FORBIDDEN,
+                "read_only",
+                "API runs in read-only mode",
+            ),
+        ));
+    }
+    let expected_revision = parse_if_match(req.headers());
+    let reload_request = ReloadRequest::from_query(query).map_err(ApiFailure::bad_request)?;
+    let body = read_json::<serde_json::Value>(req.into_body(), body_limit).await?;
+    match config_edit::patch_config(body, expected_revision, reload_request, shared).await {
+        Ok(resp) => {
+            let revision = resp.revision.clone();
+            let status = if resp.reload.is_some() {
+                StatusCode::ACCEPTED
+            } else {
+                StatusCode::OK
+            };
+            Ok(success_response(status, resp, revision))
+        }
+        Err(error) => {
+            shared
+                .runtime_events
+                .record("api.config.patch.failed", error.code);
+            Err(error)
+        }
+    }
+}

src/api/handler/read_routes.rs

@@ -0,0 +1,210 @@
+use super::*;
+
+pub(super) async fn handle(
+    method: &Method,
+    normalized_path: &str,
+    query: Option<&str>,
+    shared: &ApiShared,
+    cfg: &ProxyConfig,
+    config_rx: &watch::Receiver<Arc<ProxyConfig>>,
+) -> Result<Option<Response<Full<Bytes>>>, ApiFailure> {
+    let api_cfg = &cfg.server.api;
+    match (method.as_str(), normalized_path) {
+        ("GET", "/web-status") => Ok(web_status::render(query, &shared.web_trace).await),
+        ("GET", "/v1/health") => {
+            let revision = current_revision(&shared.config_path).await?;
+            let data = HealthData {
+                status: "ok",
+                read_only: api_cfg.read_only,
+            };
+            Ok(success_response(StatusCode::OK, data, revision))
+        }
+        ("GET", "/v1/health/ready") => {
+            let revision = current_revision(&shared.config_path).await?;
+            let admission_open = shared.runtime_state.admission_open.load(Ordering::Relaxed);
+            let upstream_health = shared.upstream_manager.api_health_summary().await;
+            let ready = admission_open && upstream_health.healthy_total > 0;
+            let reason = if ready {
+                None
+            } else if !admission_open {
+                Some("admission_closed")
+            } else {
+                Some("no_healthy_upstreams")
+            };
+            let data = HealthReadyData {
+                ready,
+                status: if ready { "ready" } else { "not_ready" },
+                reason,
+                admission_open,
+                healthy_upstreams: upstream_health.healthy_total,
+                total_upstreams: upstream_health.configured_total,
+            };
+            let status_code = if ready {
+                StatusCode::OK
+            } else {
+                StatusCode::SERVICE_UNAVAILABLE
+            };
+            Ok(success_response(status_code, data, revision))
+        }
+        ("GET", "/v1/system/info") => {
+            let revision = current_revision(&shared.config_path).await?;
+            let data = build_system_info_data(shared, cfg, &revision);
+            Ok(success_response(StatusCode::OK, data, revision))
+        }
+        ("GET", "/v1/runtime/gates") => {
+            let revision = current_revision(&shared.config_path).await?;
+            let data = build_runtime_gates_data(shared, cfg).await;
+            Ok(success_response(StatusCode::OK, data, revision))
+        }
+        ("GET", "/v1/runtime/initialization") => {
+            let revision = current_revision(&shared.config_path).await?;
+            let data = build_runtime_initialization_data(shared).await;
+            Ok(success_response(StatusCode::OK, data, revision))
+        }
+        ("GET", "/v1/limits/effective") => {
+            let revision = current_revision(&shared.config_path).await?;
+            let data = build_limits_effective_data(cfg);
+            Ok(success_response(StatusCode::OK, data, revision))
+        }
+        ("GET", "/v1/security/posture") => {
+            let revision = current_revision(&shared.config_path).await?;
+            let data = build_security_posture_data(cfg);
+            Ok(success_response(StatusCode::OK, data, revision))
+        }
+        ("GET", "/v1/security/whitelist") => {
+            let revision = current_revision(&shared.config_path).await?;
+            let data = build_security_whitelist_data(cfg);
+            Ok(success_response(StatusCode::OK, data, revision))
+        }
+        ("GET", "/v1/stats/summary") => {
+            let revision = current_revision(&shared.config_path).await?;
+            let connections_bad_by_class = shared
+                .stats
+                .get_connects_bad_class_counts()
+                .into_iter()
+                .map(|(class, total)| ClassCount { class, total })
+                .collect();
+            let handshake_failures_by_class = shared
+                .stats
+                .get_handshake_failure_class_counts()
+                .into_iter()
+                .map(|(class, total)| ClassCount { class, total })
+                .collect();
+            let data = SummaryData {
+                uptime_seconds: shared.stats.uptime_secs(),
+                connections_total: shared.stats.get_connects_all(),
+                connections_bad_total: shared.stats.get_connects_bad(),
+                connections_bad_by_class,
+                handshake_failures_by_class,
+                handshake_timeouts_total: shared.stats.get_handshake_timeouts(),
+                configured_users: cfg.access.users.len(),
+            };
+            Ok(success_response(StatusCode::OK, data, revision))
+        }
+        ("GET", "/v1/stats/zero/all") => {
+            let revision = current_revision(&shared.config_path).await?;
+            let data = build_zero_all_data(&shared.stats, cfg.access.users.len());
+            Ok(success_response(StatusCode::OK, data, revision))
+        }
+        ("GET", "/v1/stats/upstreams") => {
+            let revision = current_revision(&shared.config_path).await?;
+            let data = build_upstreams_data(shared, api_cfg);
+            Ok(success_response(StatusCode::OK, data, revision))
+        }
+        ("GET", "/v1/stats/minimal/all") => {
+            let revision = current_revision(&shared.config_path).await?;
+            let data = build_minimal_all_data(shared, api_cfg).await;
+            Ok(success_response(StatusCode::OK, data, revision))
+        }
+        ("GET", "/v1/stats/me-writers") => {
+            let revision = current_revision(&shared.config_path).await?;
+            let data = build_me_writers_data(shared, api_cfg).await;
+            Ok(success_response(StatusCode::OK, data, revision))
+        }
+        ("GET", "/v1/stats/dcs") => {
+            let revision = current_revision(&shared.config_path).await?;
+            let data = build_dcs_data(shared, api_cfg).await;
+            Ok(success_response(StatusCode::OK, data, revision))
+        }
+        ("GET", "/v1/runtime/me-pool-state") | ("GET", "/v1/runtime/me_pool_state") => {
+            let revision = current_revision(&shared.config_path).await?;
+            let data = build_runtime_me_pool_state_data(shared).await;
+            Ok(success_response(StatusCode::OK, data, revision))
+        }
+        ("GET", "/v1/runtime/me-quality") | ("GET", "/v1/runtime/me_quality") => {
+            let revision = current_revision(&shared.config_path).await?;
+            let data = build_runtime_me_quality_data(shared).await;
+            Ok(success_response(StatusCode::OK, data, revision))
+        }
+        ("GET", "/v1/runtime/upstream-quality") | ("GET", "/v1/runtime/upstream_quality") => {
+            let revision = current_revision(&shared.config_path).await?;
+            let data = build_runtime_upstream_quality_data(shared).await;
+            Ok(success_response(StatusCode::OK, data, revision))
+        }
+        ("GET", "/v1/runtime/nat-stun") | ("GET", "/v1/runtime/nat_stun") => {
+            let revision = current_revision(&shared.config_path).await?;
+            let data = build_runtime_nat_stun_data(shared).await;
+            Ok(success_response(StatusCode::OK, data, revision))
+        }
+        ("GET", "/v1/runtime/me-selftest") => {
+            let revision = current_revision(&shared.config_path).await?;
+            let data = build_runtime_me_selftest_data(shared, cfg).await;
+            Ok(success_response(StatusCode::OK, data, revision))
+        }
+        ("GET", "/v1/runtime/connections/summary") => {
+            let revision = current_revision(&shared.config_path).await?;
+            let data = build_runtime_connections_summary_data(shared, cfg).await;
+            Ok(success_response(StatusCode::OK, data, revision))
+        }
+        ("GET", "/v1/runtime/events/recent") => {
+            let revision = current_revision(&shared.config_path).await?;
+            let data = build_runtime_events_recent_data(shared, cfg, query);
+            Ok(success_response(StatusCode::OK, data, revision))
+        }
+        ("GET", "/v1/runtime/tls-fingerprints") => {
+            let revision = current_revision(&shared.config_path).await?;
+            let data = build_runtime_tls_fingerprints_data(shared, cfg, query);
+            Ok(success_response(StatusCode::OK, data, revision))
+        }
+        ("GET", "/v1/stats/users/active-ips") => {
+            let revision = current_revision(&shared.config_path).await?;
+            let usernames: Vec<_> = cfg.access.users.keys().cloned().collect();
+            let active_ips_map = shared.ip_tracker.get_active_ips_for_users(&usernames).await;
+            let mut data: Vec<UserActiveIps> = active_ips_map
+                .into_iter()
+                .filter(|(_, ips)| !ips.is_empty())
+                .map(|(username, active_ips)| UserActiveIps {
+                    username,
+                    active_ips,
+                })
+                .collect();
+            data.sort_by(|a, b| a.username.cmp(&b.username));
+            Ok(success_response(StatusCode::OK, data, revision))
+        }
+        ("GET", "/v1/stats/users") | ("GET", "/v1/users") => {
+            let revision = current_revision(&shared.config_path).await?;
+            let disk_cfg = load_config_from_disk(&shared.config_path).await?;
+            let runtime_cfg = config_rx.borrow().clone();
+            let (detected_ip_v4, detected_ip_v6) = shared.detected_link_ips();
+            let users = users_from_config(
+                &disk_cfg,
+                &shared.stats,
+                &shared.ip_tracker,
+                detected_ip_v4,
+                detected_ip_v6,
+                Some(runtime_cfg.as_ref()),
+            )
+            .await;
+            Ok(success_response(StatusCode::OK, users, revision))
+        }
+        ("GET", "/v1/stats/users/quota") => {
+            let revision = current_revision(&shared.config_path).await?;
+            let disk_cfg = load_config_from_disk(&shared.config_path).await?;
+            let data = build_user_quota_list(&disk_cfg, shared.stats.as_ref());
+            Ok(success_response(StatusCode::OK, data, revision))
+        }
+
+        _ => return Ok(None),
+    }
+    .map(Some)
+}

src/api/handler/user_routes.rs

@@ -0,0 +1,386 @@
+use super::*;
+
+pub(super) async fn handle(
+    req: Request<Incoming>,
+    method: &Method,
+    path: &str,
+    normalized_path: &str,
+    shared: &Arc<ApiShared>,
+    cfg: &ProxyConfig,
+    config_rx: &watch::Receiver<Arc<ProxyConfig>>,
+    request_id: u64,
+    body_limit: usize,
+) -> Result<Response<Full<Bytes>>, ApiFailure> {
+    let api_cfg = &cfg.server.api;
+    if method == Method::GET
+        && let Some(reload_id) = reload_status_route_id(normalized_path)
+    {
+        let revision = current_revision(&shared.config_path).await?;
+        let status = shared
+            .reload_control
+            .status(reload_id)
+            .await
+            .ok_or_else(|| {
+                ApiFailure::new(
+                    StatusCode::NOT_FOUND,
+                    "reload_not_found",
+                    format!("Reload {} was not found", reload_id),
+                )
+            })?;
+        return Ok(success_response(StatusCode::OK, status, revision));
+    }
+    if method == Method::POST
+        && let Some(base_user) = normalized_path
+            .strip_prefix("/v1/users/")
+            .and_then(|path| path.strip_suffix("/enable"))
+        && !base_user.is_empty()
+        && !base_user.contains('/')
+    {
+        let base_user = parse_route_username(base_user)?;
+        if api_cfg.read_only {
+            return Ok(error_response(
+                request_id,
+                ApiFailure::new(
+                    StatusCode::FORBIDDEN,
+                    "read_only",
+                    "API runs in read-only mode",
+                ),
+            ));
+        }
+        let expected_revision = parse_if_match(req.headers());
+        let result = set_user_enabled(base_user, true, expected_revision, shared).await;
+        let (mut data, revision) = match result {
+            Ok(ok) => ok,
+            Err(error) => {
+                shared.runtime_events.record(
+                    "api.user.enable.failed",
+                    format!("username={} code={}", base_user, error.code),
+                );
+                return Err(error);
+            }
+        };
+        let runtime_cfg = config_rx.borrow().clone();
+        data.in_runtime = runtime_cfg.access.users.contains_key(&data.username);
+        shared.proxy_shared.set_user_enabled(base_user, true);
+        shared
+            .runtime_events
+            .record("api.user.enable.ok", format!("username={}", base_user));
+        let status = if data.in_runtime {
+            StatusCode::OK
+        } else {
+            StatusCode::ACCEPTED
+        };
+        return Ok(success_response(status, data, revision));
+    }
+    if method == Method::POST
+        && let Some(base_user) = normalized_path
+            .strip_prefix("/v1/users/")
+            .and_then(|path| path.strip_suffix("/disable"))
+        && !base_user.is_empty()
+        && !base_user.contains('/')
+    {
+        let base_user = parse_route_username(base_user)?;
+        if api_cfg.read_only {
+            return Ok(error_response(
+                request_id,
+                ApiFailure::new(
+                    StatusCode::FORBIDDEN,
+                    "read_only",
+                    "API runs in read-only mode",
+                ),
+            ));
+        }
+        let expected_revision = parse_if_match(req.headers());
+        let result = set_user_enabled(base_user, false, expected_revision, shared).await;
+        let (mut data, revision) = match result {
+            Ok(ok) => ok,
+            Err(error) => {
+                shared.runtime_events.record(
+                    "api.user.disable.failed",
+                    format!("username={} code={}", base_user, error.code),
+                );
+                return Err(error);
+            }
+        };
+        let runtime_cfg = config_rx.borrow().clone();
+        data.in_runtime = runtime_cfg.access.users.contains_key(&data.username);
+        let newly_disabled = shared.proxy_shared.set_user_enabled(base_user, false);
+        let cancelled = shared.proxy_shared.cancel_user_sessions(base_user);
+        shared.runtime_events.record(
+            "api.user.disable.ok",
+            format!(
+                "username={} newly_disabled={} cancelled_sessions={}",
+                base_user, newly_disabled, cancelled
+            ),
+        );
+        let status = if data.in_runtime {
+            StatusCode::OK
+        } else {
+            StatusCode::ACCEPTED
+        };
+        return Ok(success_response(status, data, revision));
+    }
+    if method == Method::POST
+        && let Some(user) = normalized_path
+            .strip_prefix("/v1/users/")
+            .and_then(|path| path.strip_suffix("/reset-quota"))
+        && !user.is_empty()
+        && !user.contains('/')
+    {
+        let user = parse_route_username(user)?;
+        if api_cfg.read_only {
+            return Ok(error_response(
+                request_id,
+                ApiFailure::new(
+                    StatusCode::FORBIDDEN,
+                    "read_only",
+                    "API runs in read-only mode",
+                ),
+            ));
+        }
+        let expected_revision = parse_if_match(req.headers());
+        let _mutation_guard = shared.mutation_lock.lock().await;
+        let disk_cfg = load_config_from_disk(&shared.config_path).await?;
+        ensure_expected_revision(&shared.config_path, expected_revision.as_deref()).await?;
+        if !disk_cfg.access.users.contains_key(user) {
+            return Ok(error_response(
+                request_id,
+                ApiFailure::new(StatusCode::NOT_FOUND, "not_found", "User not found"),
+            ));
+        }
+        let configured_users = disk_cfg
+            .access
+            .users
+            .keys()
+            .cloned()
+            .collect::<BTreeSet<_>>();
+        let snapshot = match shared.quota_state.reset_user(&configured_users, user).await {
+            Ok(snapshot) => snapshot,
+            Err(error) => {
+                shared.runtime_events.record(
+                    "api.user.reset_quota.failed",
+                    format!("username={} error={}", user, error),
+                );
+                return Err(ApiFailure::internal(format!(
+                    "Failed to reset user quota: {}",
+                    error
+                )));
+            }
+        };
+        shared
+            .runtime_events
+            .record("api.user.reset_quota.ok", format!("username={}", user));
+        let revision = current_revision(&shared.config_path).await?;
+        return Ok(success_response(
+            StatusCode::OK,
+            ResetUserQuotaResponse {
+                username: user.to_string(),
+                used_bytes: snapshot.used_bytes,
+                last_reset_epoch_secs: snapshot.last_reset_epoch_secs,
+            },
+            revision,
+        ));
+    }
+    if method == Method::POST
+        && let Some(base_user) = normalized_path
+            .strip_prefix("/v1/users/")
+            .and_then(|path| path.strip_suffix("/rotate-secret"))
+        && !base_user.is_empty()
+        && !base_user.contains('/')
+    {
+        let base_user = parse_route_username(base_user)?;
+        if api_cfg.read_only {
+            return Ok(error_response(
+                request_id,
+                ApiFailure::new(
+                    StatusCode::FORBIDDEN,
+                    "read_only",
+                    "API runs in read-only mode",
+                ),
+            ));
+        }
+        let expected_revision = parse_if_match(req.headers());
+        let body = read_optional_json::<RotateSecretRequest>(req.into_body(), body_limit).await?;
+        let result = rotate_secret(
+            base_user,
+            body.unwrap_or_default(),
+            expected_revision,
+            shared,
+        )
+        .await;
+        let (mut data, revision) = match result {
+            Ok(ok) => ok,
+            Err(error) => {
+                shared.runtime_events.record(
+                    "api.user.rotate_secret.failed",
+                    format!("username={} code={}", base_user, error.code),
+                );
+                return Err(error);
+            }
+        };
+        let runtime_cfg = config_rx.borrow().clone();
+        data.user.in_runtime = runtime_cfg.access.users.contains_key(&data.user.username);
+        shared.runtime_events.record(
+            "api.user.rotate_secret.ok",
+            format!("username={}", base_user),
+        );
+        let status = if data.user.in_runtime {
+            StatusCode::OK
+        } else {
+            StatusCode::ACCEPTED
+        };
+        return Ok(success_response(status, data, revision));
+    }
+    if let Some(user) = normalized_path.strip_prefix("/v1/users/")
+        && !user.is_empty()
+        && !user.contains('/')
+    {
+        let user = parse_route_username(user)?;
+        if method == Method::GET {
+            let revision = current_revision(&shared.config_path).await?;
+            let disk_cfg = load_config_from_disk(&shared.config_path).await?;
+            let runtime_cfg = config_rx.borrow().clone();
+            let (detected_ip_v4, detected_ip_v6) = shared.detected_link_ips();
+            let users = users_from_config(
+                &disk_cfg,
+                &shared.stats,
+                &shared.ip_tracker,
+                detected_ip_v4,
+                detected_ip_v6,
+                Some(runtime_cfg.as_ref()),
+            )
+            .await;
+            if let Some(user_info) = users.into_iter().find(|entry| entry.username == user) {
+                return Ok(success_response(StatusCode::OK, user_info, revision));
+            }
+            return Ok(error_response(
+                request_id,
+                ApiFailure::new(StatusCode::NOT_FOUND, "not_found", "User not found"),
+            ));
+        }
+        if method == Method::PATCH {
+            if api_cfg.read_only {
+                return Ok(error_response(
+                    request_id,
+                    ApiFailure::new(
+                        StatusCode::FORBIDDEN,
+                        "read_only",
+                        "API runs in read-only mode",
+                    ),
+                ));
+            }
+            let expected_revision = parse_if_match(req.headers());
+            let body = read_json::<PatchUserRequest>(req.into_body(), body_limit).await?;
+            let enabled_update = match &body.enabled {
+                Patch::Unchanged => None,
+                Patch::Remove => Some(true),
+                Patch::Set(enabled) => Some(*enabled),
+            };
+            let result = patch_user(user, body, expected_revision, shared).await;
+            let (mut data, revision) = match result {
+                Ok(ok) => ok,
+                Err(error) => {
+                    shared.runtime_events.record(
+                        "api.user.patch.failed",
+                        format!("username={} code={}", user, error.code),
+                    );
+                    return Err(error);
+                }
+            };
+            let runtime_cfg = config_rx.borrow().clone();
+            data.in_runtime = runtime_cfg.access.users.contains_key(&data.username);
+            if let Some(enabled) = enabled_update {
+                shared
+                    .proxy_shared
+                    .set_user_enabled(&data.username, enabled);
+                if !enabled {
+                    let cancelled = shared.proxy_shared.cancel_user_sessions(&data.username);
+                    shared.runtime_events.record(
+                        "api.user.disable.runtime",
+                        format!(
+                            "username={} cancelled_sessions={}",
+                            data.username, cancelled
+                        ),
+                    );
+                }
+            }
+            shared
+                .runtime_events
+                .record("api.user.patch.ok", format!("username={}", data.username));
+            let status = if data.in_runtime {
+                StatusCode::OK
+            } else {
+                StatusCode::ACCEPTED
+            };
+            return Ok(success_response(status, data, revision));
+        }
+        if method == Method::DELETE {
+            if api_cfg.read_only {
+                return Ok(error_response(
+                    request_id,
+                    ApiFailure::new(
+                        StatusCode::FORBIDDEN,
+                        "read_only",
+                        "API runs in read-only mode",
+                    ),
+                ));
+            }
+            let expected_revision = parse_if_match(req.headers());
+            let result = delete_user(user, expected_revision, shared).await;
+            let (deleted_user, revision) = match result {
+                Ok(ok) => ok,
+                Err(error) => {
+                    shared.runtime_events.record(
+                        "api.user.delete.failed",
+                        format!("username={} code={}", user, error.code),
+                    );
+                    return Err(error);
+                }
+            };
+            shared.proxy_shared.set_user_enabled(&deleted_user, true);
+            let cancelled = shared.proxy_shared.cancel_user_sessions(&deleted_user);
+            shared.runtime_events.record(
+                "api.user.delete.ok",
+                format!("username={} cancelled_sessions={}", deleted_user, cancelled),
+            );
+            let runtime_cfg = config_rx.borrow().clone();
+            let in_runtime = runtime_cfg.access.users.contains_key(&deleted_user);
+            let response = DeleteUserResponse {
+                username: deleted_user,
+                in_runtime,
+            };
+            let status = if response.in_runtime {
+                StatusCode::ACCEPTED
+            } else {
+                StatusCode::OK
+            };
+            return Ok(success_response(status, response, revision));
+        }
+        if method == Method::POST {
+            return Ok(error_response(
+                request_id,
+                ApiFailure::method_not_allowed(ALLOW_GET_PATCH_DELETE),
+            ));
+        }
+        return Ok(error_response(
+            request_id,
+            ApiFailure::method_not_allowed(ALLOW_GET_PATCH_DELETE),
+        ));
+    }
+    if let Some(allow) = allowed_methods_for_path(normalized_path) {
+        return Ok(error_response(
+            request_id,
+            ApiFailure::method_not_allowed(allow),
+        ));
+    }
+    debug!(
+        method = method.as_str(),
+        path = %path,
+        normalized_path = %normalized_path,
+        "API route not found"
+    );
+    Ok(error_response(
+        request_id,
+        ApiFailure::new(StatusCode::NOT_FOUND, "not_found", "Route not found"),
+    ))
+}

src/api/mod.rs

@@ -21,7 +21,7 @@ use tokio::sync::{Mutex, RwLock, Semaphore, watch};
 use tokio::time::timeout;
 use tracing::{debug, info, warn};
 
-use crate::config::ApiGrayAction;
+use crate::config::{ApiGrayAction, ProxyConfig};
 use crate::ip_tracker::UserIpTracker;
 use crate::maestro::control_plane::ProcessControlPlane;
 use crate::maestro::generation::{RuntimeGeneration, RuntimeWatchState};
@@ -40,6 +40,8 @@ mod config_edit;
 pub(crate) mod config_store;
 mod events;
 mod http_utils;
+// Authenticated request admission and route dispatch.
+mod handler;
 mod model;
 mod patch;
 #[cfg(test)]
@@ -61,6 +63,7 @@ use config_store::{
     parse_if_match,
 };
 use events::ApiEventStore;
+use handler::handle;
 use http_utils::{error_response, read_json, read_optional_json, success_response};
 use model::{
     ApiFailure, ClassCount, CreateUserRequest, DeleteUserResponse, HealthData, HealthReadyData,
@@ -424,835 +427,3 @@ pub(crate) async fn serve(
         });
     }
 }
-
-async fn handle(
-    req: Request<Incoming>,
-    peer: SocketAddr,
-    shared: Arc<ApiShared>,
-) -> Result<Response<Full<Bytes>>, IoError> {
-    let runtime = shared.active_runtime.load_full();
-    let previous_cache_generation = shared.cache_generation.swap(runtime.id, Ordering::AcqRel);
-    if previous_cache_generation != runtime.id {
-        *shared.minimal_cache.lock().await = None;
-        *shared.runtime_edge_connections_cache.lock().await = None;
-    }
-    let shared = Arc::new(shared.for_runtime(runtime.as_ref()));
-    let config_rx = runtime.config_rx.clone();
-    shared
-        .runtime_state
-        .admission_open
-        .store(*runtime.admission_rx.borrow(), Ordering::Relaxed);
-    let request_id = shared.next_request_id();
-    let cfg = config_rx.borrow().clone();
-    let api_cfg = &cfg.server.api;
-
-    if !api_cfg.enabled {
-        return Ok(error_response(
-            request_id,
-            ApiFailure::new(
-                StatusCode::SERVICE_UNAVAILABLE,
-                "api_disabled",
-                "API is disabled",
-            ),
-        ));
-    }
-
-    if !api_cfg.whitelist.is_empty() && !api_cfg.whitelist.iter().any(|net| net.contains(peer.ip()))
-    {
-        return match api_cfg.gray_action {
-            ApiGrayAction::Api => Ok(error_response(
-                request_id,
-                ApiFailure::new(
-                    StatusCode::FORBIDDEN,
-                    "forbidden",
-                    "Source IP is not allowed",
-                ),
-            )),
-            ApiGrayAction::Ok200 => Ok(Response::builder()
-                .status(StatusCode::OK)
-                .header("content-type", "text/html; charset=utf-8")
-                .body(Full::new(Bytes::new()))
-                .unwrap()),
-            ApiGrayAction::Drop => Err(IoError::new(
-                ErrorKind::ConnectionAborted,
-                "api request dropped by gray_action=drop",
-            )),
-        };
-    }
-
-    if !api_cfg.auth_header.is_empty() {
-        let auth_ok = req
-            .headers()
-            .get(AUTHORIZATION)
-            .and_then(|v| v.to_str().ok())
-            .map(|v| auth_header_matches(v, &api_cfg.auth_header))
-            .unwrap_or(false);
-        if !auth_ok {
-            return Ok(error_response(
-                request_id,
-                ApiFailure::new(
-                    StatusCode::UNAUTHORIZED,
-                    "unauthorized",
-                    "Missing or invalid Authorization header",
-                ),
-            ));
-        }
-    }
-
-    let method = req.method().clone();
-    let path = req.uri().path().to_string();
-    let normalized_path = if path.len() > 1 {
-        path.trim_end_matches('/')
-    } else {
-        path.as_str()
-    };
-    let query = req.uri().query().map(str::to_string);
-    let body_limit = api_cfg.request_body_limit_bytes;
-
-    let result: Result<Response<Full<Bytes>>, ApiFailure> = async {
-        if web_runtime::is_route(normalized_path) {
-            let web_mutation = method == Method::POST;
-            let result = web_runtime::handle(
-                method,
-                normalized_path,
-                query.as_deref(),
-                req,
-                shared.as_ref(),
-                cfg.as_ref(),
-                request_id,
-                body_limit,
-            )
-            .await;
-            if web_mutation && let Err(error) = &result {
-                shared.runtime_events.record(
-                    "api.web.control.failed",
-                    format!("path={} code={}", normalized_path, error.code),
-                );
-            }
-            return result;
-        }
-        match (method.as_str(), normalized_path) {
-            ("GET", "/web-status") => {
-                Ok(web_status::render(query.as_deref(), &shared.web_trace).await)
-            }
-            ("GET", "/v1/health") => {
-                let revision = current_revision(&shared.config_path).await?;
-                let data = HealthData {
-                    status: "ok",
-                    read_only: api_cfg.read_only,
-                };
-                Ok(success_response(StatusCode::OK, data, revision))
-            }
-            ("GET", "/v1/health/ready") => {
-                let revision = current_revision(&shared.config_path).await?;
-                let admission_open = shared.runtime_state.admission_open.load(Ordering::Relaxed);
-                let upstream_health = shared.upstream_manager.api_health_summary().await;
-                let ready = admission_open && upstream_health.healthy_total > 0;
-                let reason = if ready {
-                    None
-                } else if !admission_open {
-                    Some("admission_closed")
-                } else {
-                    Some("no_healthy_upstreams")
-                };
-                let data = HealthReadyData {
-                    ready,
-                    status: if ready { "ready" } else { "not_ready" },
-                    reason,
-                    admission_open,
-                    healthy_upstreams: upstream_health.healthy_total,
-                    total_upstreams: upstream_health.configured_total,
-                };
-                let status_code = if ready {
-                    StatusCode::OK
-                } else {
-                    StatusCode::SERVICE_UNAVAILABLE
-                };
-                Ok(success_response(status_code, data, revision))
-            }
-            ("GET", "/v1/system/info") => {
-                let revision = current_revision(&shared.config_path).await?;
-                let data = build_system_info_data(shared.as_ref(), cfg.as_ref(), &revision);
-                Ok(success_response(StatusCode::OK, data, revision))
-            }
-            ("GET", "/v1/runtime/gates") => {
-                let revision = current_revision(&shared.config_path).await?;
-                let data = build_runtime_gates_data(shared.as_ref(), cfg.as_ref()).await;
-                Ok(success_response(StatusCode::OK, data, revision))
-            }
-            ("GET", "/v1/runtime/initialization") => {
-                let revision = current_revision(&shared.config_path).await?;
-                let data = build_runtime_initialization_data(shared.as_ref()).await;
-                Ok(success_response(StatusCode::OK, data, revision))
-            }
-            ("GET", "/v1/limits/effective") => {
-                let revision = current_revision(&shared.config_path).await?;
-                let data = build_limits_effective_data(cfg.as_ref());
-                Ok(success_response(StatusCode::OK, data, revision))
-            }
-            ("GET", "/v1/security/posture") => {
-                let revision = current_revision(&shared.config_path).await?;
-                let data = build_security_posture_data(cfg.as_ref());
-                Ok(success_response(StatusCode::OK, data, revision))
-            }
-            ("GET", "/v1/security/whitelist") => {
-                let revision = current_revision(&shared.config_path).await?;
-                let data = build_security_whitelist_data(cfg.as_ref());
-                Ok(success_response(StatusCode::OK, data, revision))
-            }
-            ("GET", "/v1/stats/summary") => {
-                let revision = current_revision(&shared.config_path).await?;
-                let connections_bad_by_class = shared
-                    .stats
-                    .get_connects_bad_class_counts()
-                    .into_iter()
-                    .map(|(class, total)| ClassCount { class, total })
-                    .collect();
-                let handshake_failures_by_class = shared
-                    .stats
-                    .get_handshake_failure_class_counts()
-                    .into_iter()
-                    .map(|(class, total)| ClassCount { class, total })
-                    .collect();
-                let data = SummaryData {
-                    uptime_seconds: shared.stats.uptime_secs(),
-                    connections_total: shared.stats.get_connects_all(),
-                    connections_bad_total: shared.stats.get_connects_bad(),
-                    connections_bad_by_class,
-                    handshake_failures_by_class,
-                    handshake_timeouts_total: shared.stats.get_handshake_timeouts(),
-                    configured_users: cfg.access.users.len(),
-                };
-                Ok(success_response(StatusCode::OK, data, revision))
-            }
-            ("GET", "/v1/stats/zero/all") => {
-                let revision = current_revision(&shared.config_path).await?;
-                let data = build_zero_all_data(&shared.stats, cfg.access.users.len());
-                Ok(success_response(StatusCode::OK, data, revision))
-            }
-            ("GET", "/v1/stats/upstreams") => {
-                let revision = current_revision(&shared.config_path).await?;
-                let data = build_upstreams_data(shared.as_ref(), api_cfg);
-                Ok(success_response(StatusCode::OK, data, revision))
-            }
-            ("GET", "/v1/stats/minimal/all") => {
-                let revision = current_revision(&shared.config_path).await?;
-                let data = build_minimal_all_data(shared.as_ref(), api_cfg).await;
-                Ok(success_response(StatusCode::OK, data, revision))
-            }
-            ("GET", "/v1/stats/me-writers") => {
-                let revision = current_revision(&shared.config_path).await?;
-                let data = build_me_writers_data(shared.as_ref(), api_cfg).await;
-                Ok(success_response(StatusCode::OK, data, revision))
-            }
-            ("GET", "/v1/stats/dcs") => {
-                let revision = current_revision(&shared.config_path).await?;
-                let data = build_dcs_data(shared.as_ref(), api_cfg).await;
-                Ok(success_response(StatusCode::OK, data, revision))
-            }
-            ("GET", "/v1/runtime/me-pool-state") | ("GET", "/v1/runtime/me_pool_state") => {
-                let revision = current_revision(&shared.config_path).await?;
-                let data = build_runtime_me_pool_state_data(shared.as_ref()).await;
-                Ok(success_response(StatusCode::OK, data, revision))
-            }
-            ("GET", "/v1/runtime/me-quality") | ("GET", "/v1/runtime/me_quality") => {
-                let revision = current_revision(&shared.config_path).await?;
-                let data = build_runtime_me_quality_data(shared.as_ref()).await;
-                Ok(success_response(StatusCode::OK, data, revision))
-            }
-            ("GET", "/v1/runtime/upstream-quality") | ("GET", "/v1/runtime/upstream_quality") => {
-                let revision = current_revision(&shared.config_path).await?;
-                let data = build_runtime_upstream_quality_data(shared.as_ref()).await;
-                Ok(success_response(StatusCode::OK, data, revision))
-            }
-            ("GET", "/v1/runtime/nat-stun") | ("GET", "/v1/runtime/nat_stun") => {
-                let revision = current_revision(&shared.config_path).await?;
-                let data = build_runtime_nat_stun_data(shared.as_ref()).await;
-                Ok(success_response(StatusCode::OK, data, revision))
-            }
-            ("GET", "/v1/runtime/me-selftest") => {
-                let revision = current_revision(&shared.config_path).await?;
-                let data = build_runtime_me_selftest_data(shared.as_ref(), cfg.as_ref()).await;
-                Ok(success_response(StatusCode::OK, data, revision))
-            }
-            ("GET", "/v1/runtime/connections/summary") => {
-                let revision = current_revision(&shared.config_path).await?;
-                let data =
-                    build_runtime_connections_summary_data(shared.as_ref(), cfg.as_ref()).await;
-                Ok(success_response(StatusCode::OK, data, revision))
-            }
-            ("GET", "/v1/runtime/events/recent") => {
-                let revision = current_revision(&shared.config_path).await?;
-                let data = build_runtime_events_recent_data(
-                    shared.as_ref(),
-                    cfg.as_ref(),
-                    query.as_deref(),
-                );
-                Ok(success_response(StatusCode::OK, data, revision))
-            }
-            ("GET", "/v1/runtime/tls-fingerprints") => {
-                let revision = current_revision(&shared.config_path).await?;
-                let data = build_runtime_tls_fingerprints_data(
-                    shared.as_ref(),
-                    cfg.as_ref(),
-                    query.as_deref(),
-                );
-                Ok(success_response(StatusCode::OK, data, revision))
-            }
-            ("GET", "/v1/stats/users/active-ips") => {
-                let revision = current_revision(&shared.config_path).await?;
-                let usernames: Vec<_> = cfg.access.users.keys().cloned().collect();
-                let active_ips_map = shared.ip_tracker.get_active_ips_for_users(&usernames).await;
-                let mut data: Vec<UserActiveIps> = active_ips_map
-                    .into_iter()
-                    .filter(|(_, ips)| !ips.is_empty())
-                    .map(|(username, active_ips)| UserActiveIps {
-                        username,
-                        active_ips,
-                    })
-                    .collect();
-                data.sort_by(|a, b| a.username.cmp(&b.username));
-                Ok(success_response(StatusCode::OK, data, revision))
-            }
-            ("GET", "/v1/stats/users") | ("GET", "/v1/users") => {
-                let revision = current_revision(&shared.config_path).await?;
-                let disk_cfg = load_config_from_disk(&shared.config_path).await?;
-                let runtime_cfg = config_rx.borrow().clone();
-                let (detected_ip_v4, detected_ip_v6) = shared.detected_link_ips();
-                let users = users_from_config(
-                    &disk_cfg,
-                    &shared.stats,
-                    &shared.ip_tracker,
-                    detected_ip_v4,
-                    detected_ip_v6,
-                    Some(runtime_cfg.as_ref()),
-                )
-                .await;
-                Ok(success_response(StatusCode::OK, users, revision))
-            }
-            ("GET", "/v1/stats/users/quota") => {
-                let revision = current_revision(&shared.config_path).await?;
-                let disk_cfg = load_config_from_disk(&shared.config_path).await?;
-                let data = build_user_quota_list(&disk_cfg, shared.stats.as_ref());
-                Ok(success_response(StatusCode::OK, data, revision))
-            }
-            ("POST", "/v1/users") => {
-                if api_cfg.read_only {
-                    return Ok(error_response(
-                        request_id,
-                        ApiFailure::new(
-                            StatusCode::FORBIDDEN,
-                            "read_only",
-                            "API runs in read-only mode",
-                        ),
-                    ));
-                }
-                let expected_revision = parse_if_match(req.headers());
-                let body = read_json::<CreateUserRequest>(req.into_body(), body_limit).await?;
-                let requested_enabled = body.enabled;
-                let result = create_user(body, expected_revision, &shared).await;
-                let (mut data, revision) = match result {
-                    Ok(ok) => ok,
-                    Err(error) => {
-                        shared
-                            .runtime_events
-                            .record("api.user.create.failed", error.code);
-                        return Err(error);
-                    }
-                };
-                let runtime_cfg = config_rx.borrow().clone();
-                data.user.in_runtime = runtime_cfg.access.users.contains_key(&data.user.username);
-                if let Some(enabled) = requested_enabled {
-                    shared
-                        .proxy_shared
-                        .set_user_enabled(&data.user.username, enabled);
-                    if !enabled {
-                        let cancelled = shared
-                            .proxy_shared
-                            .cancel_user_sessions(&data.user.username);
-                        if cancelled > 0 {
-                            shared.runtime_events.record(
-                                "api.user.disable.runtime",
-                                format!(
-                                    "username={} cancelled_sessions={}",
-                                    data.user.username, cancelled
-                                ),
-                            );
-                        }
-                    }
-                }
-                shared.runtime_events.record(
-                    "api.user.create.ok",
-                    format!("username={}", data.user.username),
-                );
-                let status = if data.user.in_runtime {
-                    StatusCode::CREATED
-                } else {
-                    StatusCode::ACCEPTED
-                };
-                Ok(success_response(status, data, revision))
-            }
-            ("GET", "/v1/config") => {
-                let (value, revision) =
-                    config_edit::read_managed_config(&shared.config_path).await?;
-                Ok(success_response(StatusCode::OK, value, revision))
-            }
-            ("POST", "/v1/system/reload") => {
-                if api_cfg.read_only {
-                    return Ok(error_response(
-                        request_id,
-                        ApiFailure::new(
-                            StatusCode::FORBIDDEN,
-                            "read_only",
-                            "API runs in read-only mode",
-                        ),
-                    ));
-                }
-                let expected_revision = parse_if_match(req.headers());
-                let request = read_optional_json::<ReloadRequest>(req.into_body(), body_limit)
-                    .await?
-                    .unwrap_or_default();
-                request.validate().map_err(ApiFailure::bad_request)?;
-
-                let (accepted, revision) = submit_reload_from_disk(
-                    &shared.config_path,
-                    shared.mutation_lock.as_ref(),
-                    &shared.reload_control,
-                    expected_revision.as_deref(),
-                    request,
-                )
-                .await?;
-                Ok(success_response(StatusCode::ACCEPTED, accepted, revision))
-            }
-            ("PATCH", "/v1/config") => {
-                if api_cfg.read_only {
-                    return Ok(error_response(
-                        request_id,
-                        ApiFailure::new(
-                            StatusCode::FORBIDDEN,
-                            "read_only",
-                            "API runs in read-only mode",
-                        ),
-                    ));
-                }
-                let expected_revision = parse_if_match(req.headers());
-                let reload_request =
-                    ReloadRequest::from_query(query.as_deref()).map_err(ApiFailure::bad_request)?;
-                let body = read_json::<serde_json::Value>(req.into_body(), body_limit).await?;
-                match config_edit::patch_config(body, expected_revision, reload_request, &shared)
-                    .await
-                {
-                    Ok(resp) => {
-                        let revision = resp.revision.clone();
-                        let status = if resp.reload.is_some() {
-                            StatusCode::ACCEPTED
-                        } else {
-                            StatusCode::OK
-                        };
-                        Ok(success_response(status, resp, revision))
-                    }
-                    Err(error) => {
-                        shared
-                            .runtime_events
-                            .record("api.config.patch.failed", error.code);
-                        Err(error)
-                    }
-                }
-            }
-            _ => {
-                if method == Method::GET
-                    && let Some(reload_id) = reload_status_route_id(normalized_path)
-                {
-                    let revision = current_revision(&shared.config_path).await?;
-                    let status =
-                        shared
-                            .reload_control
-                            .status(reload_id)
-                            .await
-                            .ok_or_else(|| {
-                                ApiFailure::new(
-                                    StatusCode::NOT_FOUND,
-                                    "reload_not_found",
-                                    format!("Reload {} was not found", reload_id),
-                                )
-                            })?;
-                    return Ok(success_response(StatusCode::OK, status, revision));
-                }
-                if method == Method::POST
-                    && let Some(base_user) = normalized_path
-                        .strip_prefix("/v1/users/")
-                        .and_then(|path| path.strip_suffix("/enable"))
-                    && !base_user.is_empty()
-                    && !base_user.contains('/')
-                {
-                    let base_user = parse_route_username(base_user)?;
-                    if api_cfg.read_only {
-                        return Ok(error_response(
-                            request_id,
-                            ApiFailure::new(
-                                StatusCode::FORBIDDEN,
-                                "read_only",
-                                "API runs in read-only mode",
-                            ),
-                        ));
-                    }
-                    let expected_revision = parse_if_match(req.headers());
-                    let result =
-                        set_user_enabled(base_user, true, expected_revision, &shared).await;
-                    let (mut data, revision) = match result {
-                        Ok(ok) => ok,
-                        Err(error) => {
-                            shared.runtime_events.record(
-                                "api.user.enable.failed",
-                                format!("username={} code={}", base_user, error.code),
-                            );
-                            return Err(error);
-                        }
-                    };
-                    let runtime_cfg = config_rx.borrow().clone();
-                    data.in_runtime = runtime_cfg.access.users.contains_key(&data.username);
-                    shared.proxy_shared.set_user_enabled(base_user, true);
-                    shared
-                        .runtime_events
-                        .record("api.user.enable.ok", format!("username={}", base_user));
-                    let status = if data.in_runtime {
-                        StatusCode::OK
-                    } else {
-                        StatusCode::ACCEPTED
-                    };
-                    return Ok(success_response(status, data, revision));
-                }
-                if method == Method::POST
-                    && let Some(base_user) = normalized_path
-                        .strip_prefix("/v1/users/")
-                        .and_then(|path| path.strip_suffix("/disable"))
-                    && !base_user.is_empty()
-                    && !base_user.contains('/')
-                {
-                    let base_user = parse_route_username(base_user)?;
-                    if api_cfg.read_only {
-                        return Ok(error_response(
-                            request_id,
-                            ApiFailure::new(
-                                StatusCode::FORBIDDEN,
-                                "read_only",
-                                "API runs in read-only mode",
-                            ),
-                        ));
-                    }
-                    let expected_revision = parse_if_match(req.headers());
-                    let result =
-                        set_user_enabled(base_user, false, expected_revision, &shared).await;
-                    let (mut data, revision) = match result {
-                        Ok(ok) => ok,
-                        Err(error) => {
-                            shared.runtime_events.record(
-                                "api.user.disable.failed",
-                                format!("username={} code={}", base_user, error.code),
-                            );
-                            return Err(error);
-                        }
-                    };
-                    let runtime_cfg = config_rx.borrow().clone();
-                    data.in_runtime = runtime_cfg.access.users.contains_key(&data.username);
-                    let newly_disabled = shared.proxy_shared.set_user_enabled(base_user, false);
-                    let cancelled = shared.proxy_shared.cancel_user_sessions(base_user);
-                    shared.runtime_events.record(
-                        "api.user.disable.ok",
-                        format!(
-                            "username={} newly_disabled={} cancelled_sessions={}",
-                            base_user, newly_disabled, cancelled
-                        ),
-                    );
-                    let status = if data.in_runtime {
-                        StatusCode::OK
-                    } else {
-                        StatusCode::ACCEPTED
-                    };
-                    return Ok(success_response(status, data, revision));
-                }
-                if method == Method::POST
-                    && let Some(user) = normalized_path
-                        .strip_prefix("/v1/users/")
-                        .and_then(|path| path.strip_suffix("/reset-quota"))
-                    && !user.is_empty()
-                    && !user.contains('/')
-                {
-                    let user = parse_route_username(user)?;
-                    if api_cfg.read_only {
-                        return Ok(error_response(
-                            request_id,
-                            ApiFailure::new(
-                                StatusCode::FORBIDDEN,
-                                "read_only",
-                                "API runs in read-only mode",
-                            ),
-                        ));
-                    }
-                    let expected_revision = parse_if_match(req.headers());
-                    let _mutation_guard = shared.mutation_lock.lock().await;
-                    let disk_cfg = load_config_from_disk(&shared.config_path).await?;
-                    ensure_expected_revision(&shared.config_path, expected_revision.as_deref())
-                        .await?;
-                    if !disk_cfg.access.users.contains_key(user) {
-                        return Ok(error_response(
-                            request_id,
-                            ApiFailure::new(StatusCode::NOT_FOUND, "not_found", "User not found"),
-                        ));
-                    }
-                    let configured_users = disk_cfg
-                        .access
-                        .users
-                        .keys()
-                        .cloned()
-                        .collect::<BTreeSet<_>>();
-                    let snapshot = match shared
-                        .quota_state
-                        .reset_user(&configured_users, user)
-                        .await
-                    {
-                        Ok(snapshot) => snapshot,
-                        Err(error) => {
-                            shared.runtime_events.record(
-                                "api.user.reset_quota.failed",
-                                format!("username={} error={}", user, error),
-                            );
-                            return Err(ApiFailure::internal(format!(
-                                "Failed to reset user quota: {}",
-                                error
-                            )));
-                        }
-                    };
-                    shared
-                        .runtime_events
-                        .record("api.user.reset_quota.ok", format!("username={}", user));
-                    let revision = current_revision(&shared.config_path).await?;
-                    return Ok(success_response(
-                        StatusCode::OK,
-                        ResetUserQuotaResponse {
-                            username: user.to_string(),
-                            used_bytes: snapshot.used_bytes,
-                            last_reset_epoch_secs: snapshot.last_reset_epoch_secs,
-                        },
-                        revision,
-                    ));
-                }
-                if method == Method::POST
-                    && let Some(base_user) = normalized_path
-                        .strip_prefix("/v1/users/")
-                        .and_then(|path| path.strip_suffix("/rotate-secret"))
-                    && !base_user.is_empty()
-                    && !base_user.contains('/')
-                {
-                    let base_user = parse_route_username(base_user)?;
-                    if api_cfg.read_only {
-                        return Ok(error_response(
-                            request_id,
-                            ApiFailure::new(
-                                StatusCode::FORBIDDEN,
-                                "read_only",
-                                "API runs in read-only mode",
-                            ),
-                        ));
-                    }
-                    let expected_revision = parse_if_match(req.headers());
-                    let body =
-                        read_optional_json::<RotateSecretRequest>(req.into_body(), body_limit)
-                            .await?;
-                    let result = rotate_secret(
-                        base_user,
-                        body.unwrap_or_default(),
-                        expected_revision,
-                        &shared,
-                    )
-                    .await;
-                    let (mut data, revision) = match result {
-                        Ok(ok) => ok,
-                        Err(error) => {
-                            shared.runtime_events.record(
-                                "api.user.rotate_secret.failed",
-                                format!("username={} code={}", base_user, error.code),
-                            );
-                            return Err(error);
-                        }
-                    };
-                    let runtime_cfg = config_rx.borrow().clone();
-                    data.user.in_runtime =
-                        runtime_cfg.access.users.contains_key(&data.user.username);
-                    shared.runtime_events.record(
-                        "api.user.rotate_secret.ok",
-                        format!("username={}", base_user),
-                    );
-                    let status = if data.user.in_runtime {
-                        StatusCode::OK
-                    } else {
-                        StatusCode::ACCEPTED
-                    };
-                    return Ok(success_response(status, data, revision));
-                }
-                if let Some(user) = normalized_path.strip_prefix("/v1/users/")
-                    && !user.is_empty()
-                    && !user.contains('/')
-                {
-                    let user = parse_route_username(user)?;
-                    if method == Method::GET {
-                        let revision = current_revision(&shared.config_path).await?;
-                        let disk_cfg = load_config_from_disk(&shared.config_path).await?;
-                        let runtime_cfg = config_rx.borrow().clone();
-                        let (detected_ip_v4, detected_ip_v6) = shared.detected_link_ips();
-                        let users = users_from_config(
-                            &disk_cfg,
-                            &shared.stats,
-                            &shared.ip_tracker,
-                            detected_ip_v4,
-                            detected_ip_v6,
-                            Some(runtime_cfg.as_ref()),
-                        )
-                        .await;
-                        if let Some(user_info) =
-                            users.into_iter().find(|entry| entry.username == user)
-                        {
-                            return Ok(success_response(StatusCode::OK, user_info, revision));
-                        }
-                        return Ok(error_response(
-                            request_id,
-                            ApiFailure::new(StatusCode::NOT_FOUND, "not_found", "User not found"),
-                        ));
-                    }
-                    if method == Method::PATCH {
-                        if api_cfg.read_only {
-                            return Ok(error_response(
-                                request_id,
-                                ApiFailure::new(
-                                    StatusCode::FORBIDDEN,
-                                    "read_only",
-                                    "API runs in read-only mode",
-                                ),
-                            ));
-                        }
-                        let expected_revision = parse_if_match(req.headers());
-                        let body =
-                            read_json::<PatchUserRequest>(req.into_body(), body_limit).await?;
-                        let enabled_update = match &body.enabled {
-                            Patch::Unchanged => None,
-                            Patch::Remove => Some(true),
-                            Patch::Set(enabled) => Some(*enabled),
-                        };
-                        let result = patch_user(user, body, expected_revision, &shared).await;
-                        let (mut data, revision) = match result {
-                            Ok(ok) => ok,
-                            Err(error) => {
-                                shared.runtime_events.record(
-                                    "api.user.patch.failed",
-                                    format!("username={} code={}", user, error.code),
-                                );
-                                return Err(error);
-                            }
-                        };
-                        let runtime_cfg = config_rx.borrow().clone();
-                        data.in_runtime = runtime_cfg.access.users.contains_key(&data.username);
-                        if let Some(enabled) = enabled_update {
-                            shared
-                                .proxy_shared
-                                .set_user_enabled(&data.username, enabled);
-                            if !enabled {
-                                let cancelled =
-                                    shared.proxy_shared.cancel_user_sessions(&data.username);
-                                shared.runtime_events.record(
-                                    "api.user.disable.runtime",
-                                    format!(
-                                        "username={} cancelled_sessions={}",
-                                        data.username, cancelled
-                                    ),
-                                );
-                            }
-                        }
-                        shared
-                            .runtime_events
-                            .record("api.user.patch.ok", format!("username={}", data.username));
-                        let status = if data.in_runtime {
-                            StatusCode::OK
-                        } else {
-                            StatusCode::ACCEPTED
-                        };
-                        return Ok(success_response(status, data, revision));
-                    }
-                    if method == Method::DELETE {
-                        if api_cfg.read_only {
-                            return Ok(error_response(
-                                request_id,
-                                ApiFailure::new(
-                                    StatusCode::FORBIDDEN,
-                                    "read_only",
-                                    "API runs in read-only mode",
-                                ),
-                            ));
-                        }
-                        let expected_revision = parse_if_match(req.headers());
-                        let result = delete_user(user, expected_revision, &shared).await;
-                        let (deleted_user, revision) = match result {
-                            Ok(ok) => ok,
-                            Err(error) => {
-                                shared.runtime_events.record(
-                                    "api.user.delete.failed",
-                                    format!("username={} code={}", user, error.code),
-                                );
-                                return Err(error);
-                            }
-                        };
-                        shared.proxy_shared.set_user_enabled(&deleted_user, true);
-                        let cancelled = shared.proxy_shared.cancel_user_sessions(&deleted_user);
-                        shared.runtime_events.record(
-                            "api.user.delete.ok",
-                            format!("username={} cancelled_sessions={}", deleted_user, cancelled),
-                        );
-                        let runtime_cfg = config_rx.borrow().clone();
-                        let in_runtime = runtime_cfg.access.users.contains_key(&deleted_user);
-                        let response = DeleteUserResponse {
-                            username: deleted_user,
-                            in_runtime,
-                        };
-                        let status = if response.in_runtime {
-                            StatusCode::ACCEPTED
-                        } else {
-                            StatusCode::OK
-                        };
-                        return Ok(success_response(status, response, revision));
-                    }
-                    if method == Method::POST {
-                        return Ok(error_response(
-                            request_id,
-                            ApiFailure::method_not_allowed(ALLOW_GET_PATCH_DELETE),
-                        ));
-                    }
-                    return Ok(error_response(
-                        request_id,
-                        ApiFailure::method_not_allowed(ALLOW_GET_PATCH_DELETE),
-                    ));
-                }
-                if let Some(allow) = allowed_methods_for_path(normalized_path) {
-                    return Ok(error_response(
-                        request_id,
-                        ApiFailure::method_not_allowed(allow),
-                    ));
-                }
-                debug!(
-                    method = method.as_str(),
-                    path = %path,
-                    normalized_path = %normalized_path,
-                    "API route not found"
-                );
-                Ok(error_response(
-                    request_id,
-                    ApiFailure::new(StatusCode::NOT_FOUND, "not_found", "Route not found"),
-                ))
-            }
-        }
-    }
-    .await;
-
-    match result {
-        Ok(resp) => Ok(resp),
-        Err(error) => Ok(error_response(request_id, error)),
-    }
-}

src/api/model.rs

@@ -466,164 +466,6 @@ pub(super) struct MinimalAllData {
     pub(super) data: Option<MinimalAllPayload>,
 }
 
-#[derive(Serialize)]
-pub(super) struct UserLinks {
-    pub(super) classic: Vec<String>,
-    pub(super) secure: Vec<String>,
-    pub(super) tls: Vec<String>,
-    pub(super) tls_domains: Vec<TlsDomainLink>,
-}
-
-#[derive(Serialize)]
-pub(super) struct TlsDomainLink {
-    pub(super) domain: String,
-    pub(super) link: String,
-}
-
-#[derive(Serialize)]
-pub(super) struct UserInfo {
-    pub(super) username: String,
-    pub(super) enabled: bool,
-    pub(super) in_runtime: bool,
-    pub(super) user_ad_tag: Option<String>,
-    pub(super) max_tcp_conns: Option<usize>,
-    pub(super) expiration_rfc3339: Option<String>,
-    pub(super) data_quota_bytes: Option<u64>,
-    pub(super) rate_limit_up_bps: Option<u64>,
-    pub(super) rate_limit_down_bps: Option<u64>,
-    pub(super) max_unique_ips: Option<usize>,
-    pub(super) current_connections: u64,
-    pub(super) active_unique_ips: usize,
-    pub(super) active_unique_ips_list: Vec<IpAddr>,
-    pub(super) recent_unique_ips: usize,
-    pub(super) recent_unique_ips_list: Vec<IpAddr>,
-    pub(super) total_octets: u64,
-    pub(super) links: UserLinks,
-}
-
-#[derive(Serialize)]
-pub(super) struct UserActiveIps {
-    pub(super) username: String,
-    pub(super) active_ips: Vec<IpAddr>,
-}
-
-#[derive(Serialize)]
-pub(super) struct CreateUserResponse {
-    pub(super) user: UserInfo,
-    pub(super) secret: String,
-}
-
-#[derive(Serialize)]
-pub(super) struct DeleteUserResponse {
-    pub(super) username: String,
-    pub(super) in_runtime: bool,
-}
-
-#[derive(Serialize)]
-pub(super) struct ResetUserQuotaResponse {
-    pub(super) username: String,
-    pub(super) used_bytes: u64,
-    pub(super) last_reset_epoch_secs: u64,
-}
-
-#[derive(Serialize)]
-pub(super) struct UserQuotaListData {
-    pub(super) users: Vec<UserQuotaEntry>,
-}
-
-#[derive(Serialize)]
-pub(super) struct UserQuotaEntry {
-    pub(super) username: String,
-    pub(super) data_quota_bytes: u64,
-    pub(super) used_bytes: u64,
-    pub(super) last_reset_epoch_secs: u64,
-}
-
-#[derive(Deserialize)]
-pub(super) struct CreateUserRequest {
-    pub(super) username: String,
-    pub(super) secret: Option<String>,
-    pub(super) user_ad_tag: Option<String>,
-    pub(super) max_tcp_conns: Option<usize>,
-    pub(super) expiration_rfc3339: Option<String>,
-    pub(super) data_quota_bytes: Option<u64>,
-    pub(super) rate_limit_up_bps: Option<u64>,
-    pub(super) rate_limit_down_bps: Option<u64>,
-    pub(super) max_unique_ips: Option<usize>,
-    pub(super) enabled: Option<bool>,
-}
-
-#[derive(Deserialize)]
-pub(super) struct PatchUserRequest {
-    pub(super) secret: Option<String>,
-    #[serde(default, deserialize_with = "patch_field")]
-    pub(super) user_ad_tag: Patch<String>,
-    #[serde(default, deserialize_with = "patch_field")]
-    pub(super) max_tcp_conns: Patch<usize>,
-    #[serde(default, deserialize_with = "patch_field")]
-    pub(super) expiration_rfc3339: Patch<String>,
-    #[serde(default, deserialize_with = "patch_field")]
-    pub(super) data_quota_bytes: Patch<u64>,
-    #[serde(default, deserialize_with = "patch_field")]
-    pub(super) rate_limit_up_bps: Patch<u64>,
-    #[serde(default, deserialize_with = "patch_field")]
-    pub(super) rate_limit_down_bps: Patch<u64>,
-    #[serde(default, deserialize_with = "patch_field")]
-    pub(super) max_unique_ips: Patch<usize>,
-    #[serde(default, deserialize_with = "patch_field")]
-    pub(super) enabled: Patch<bool>,
-}
-
-#[derive(Default, Deserialize)]
-pub(super) struct RotateSecretRequest {
-    pub(super) secret: Option<String>,
-}
-
-pub(super) fn parse_optional_expiration(
-    value: Option<&str>,
-) -> Result<Option<DateTime<Utc>>, ApiFailure> {
-    let Some(raw) = value else {
-        return Ok(None);
-    };
-    let parsed = DateTime::parse_from_rfc3339(raw)
-        .map_err(|_| ApiFailure::bad_request("expiration_rfc3339 must be valid RFC3339"))?;
-    Ok(Some(parsed.with_timezone(&Utc)))
-}
-
-pub(super) fn parse_patch_expiration(
-    value: &Patch<String>,
-) -> Result<Patch<DateTime<Utc>>, ApiFailure> {
-    match value {
-        Patch::Unchanged => Ok(Patch::Unchanged),
-        Patch::Remove => Ok(Patch::Remove),
-        Patch::Set(raw) => {
-            let parsed = DateTime::parse_from_rfc3339(raw)
-                .map_err(|_| ApiFailure::bad_request("expiration_rfc3339 must be valid RFC3339"))?;
-            Ok(Patch::Set(parsed.with_timezone(&Utc)))
-        }
-    }
-}
-
-pub(super) fn is_valid_user_secret(secret: &str) -> bool {
-    secret.len() == 32 && secret.chars().all(|c| c.is_ascii_hexdigit())
-}
-
-pub(super) fn is_valid_ad_tag(tag: &str) -> bool {
-    tag.len() == 32 && tag.chars().all(|c| c.is_ascii_hexdigit())
-}
-
-pub(super) fn is_valid_username(user: &str) -> bool {
-    !user.is_empty()
-        && user.len() <= MAX_USERNAME_LEN
-        && user
-            .chars()
-            .all(|ch| ch.is_ascii_alphanumeric() || matches!(ch, '_' | '-' | '.'))
-}
-
-pub(super) fn random_user_secret() -> String {
-    static API_SECRET_RNG: OnceLock<SecureRandom> = OnceLock::new();
-    let rng = API_SECRET_RNG.get_or_init(SecureRandom::new);
-    let mut bytes = [0u8; 16];
-    rng.fill(&mut bytes);
-    hex::encode(bytes)
-}
+// User-management request, response, and validation models.
+mod users;
+pub(super) use users::*;

src/api/model/users.rs

@@ -0,0 +1,163 @@
+use super::*;
+
+#[derive(Serialize)]
+pub(in crate::api) struct UserLinks {
+    pub(in crate::api) classic: Vec<String>,
+    pub(in crate::api) secure: Vec<String>,
+    pub(in crate::api) tls: Vec<String>,
+    pub(in crate::api) tls_domains: Vec<TlsDomainLink>,
+}
+
+#[derive(Serialize)]
+pub(in crate::api) struct TlsDomainLink {
+    pub(in crate::api) domain: String,
+    pub(in crate::api) link: String,
+}
+
+#[derive(Serialize)]
+pub(in crate::api) struct UserInfo {
+    pub(in crate::api) username: String,
+    pub(in crate::api) enabled: bool,
+    pub(in crate::api) in_runtime: bool,
+    pub(in crate::api) user_ad_tag: Option<String>,
+    pub(in crate::api) max_tcp_conns: Option<usize>,
+    pub(in crate::api) expiration_rfc3339: Option<String>,
+    pub(in crate::api) data_quota_bytes: Option<u64>,
+    pub(in crate::api) rate_limit_up_bps: Option<u64>,
+    pub(in crate::api) rate_limit_down_bps: Option<u64>,
+    pub(in crate::api) max_unique_ips: Option<usize>,
+    pub(in crate::api) current_connections: u64,
+    pub(in crate::api) active_unique_ips: usize,
+    pub(in crate::api) active_unique_ips_list: Vec<IpAddr>,
+    pub(in crate::api) recent_unique_ips: usize,
+    pub(in crate::api) recent_unique_ips_list: Vec<IpAddr>,
+    pub(in crate::api) total_octets: u64,
+    pub(in crate::api) links: UserLinks,
+}
+
+#[derive(Serialize)]
+pub(in crate::api) struct UserActiveIps {
+    pub(in crate::api) username: String,
+    pub(in crate::api) active_ips: Vec<IpAddr>,
+}
+
+#[derive(Serialize)]
+pub(in crate::api) struct CreateUserResponse {
+    pub(in crate::api) user: UserInfo,
+    pub(in crate::api) secret: String,
+}
+
+#[derive(Serialize)]
+pub(in crate::api) struct DeleteUserResponse {
+    pub(in crate::api) username: String,
+    pub(in crate::api) in_runtime: bool,
+}
+
+#[derive(Serialize)]
+pub(in crate::api) struct ResetUserQuotaResponse {
+    pub(in crate::api) username: String,
+    pub(in crate::api) used_bytes: u64,
+    pub(in crate::api) last_reset_epoch_secs: u64,
+}
+
+#[derive(Serialize)]
+pub(in crate::api) struct UserQuotaListData {
+    pub(in crate::api) users: Vec<UserQuotaEntry>,
+}
+
+#[derive(Serialize)]
+pub(in crate::api) struct UserQuotaEntry {
+    pub(in crate::api) username: String,
+    pub(in crate::api) data_quota_bytes: u64,
+    pub(in crate::api) used_bytes: u64,
+    pub(in crate::api) last_reset_epoch_secs: u64,
+}
+
+#[derive(Deserialize)]
+pub(in crate::api) struct CreateUserRequest {
+    pub(in crate::api) username: String,
+    pub(in crate::api) secret: Option<String>,
+    pub(in crate::api) user_ad_tag: Option<String>,
+    pub(in crate::api) max_tcp_conns: Option<usize>,
+    pub(in crate::api) expiration_rfc3339: Option<String>,
+    pub(in crate::api) data_quota_bytes: Option<u64>,
+    pub(in crate::api) rate_limit_up_bps: Option<u64>,
+    pub(in crate::api) rate_limit_down_bps: Option<u64>,
+    pub(in crate::api) max_unique_ips: Option<usize>,
+    pub(in crate::api) enabled: Option<bool>,
+}
+
+#[derive(Deserialize)]
+pub(in crate::api) struct PatchUserRequest {
+    pub(in crate::api) secret: Option<String>,
+    #[serde(default, deserialize_with = "patch_field")]
+    pub(in crate::api) user_ad_tag: Patch<String>,
+    #[serde(default, deserialize_with = "patch_field")]
+    pub(in crate::api) max_tcp_conns: Patch<usize>,
+    #[serde(default, deserialize_with = "patch_field")]
+    pub(in crate::api) expiration_rfc3339: Patch<String>,
+    #[serde(default, deserialize_with = "patch_field")]
+    pub(in crate::api) data_quota_bytes: Patch<u64>,
+    #[serde(default, deserialize_with = "patch_field")]
+    pub(in crate::api) rate_limit_up_bps: Patch<u64>,
+    #[serde(default, deserialize_with = "patch_field")]
+    pub(in crate::api) rate_limit_down_bps: Patch<u64>,
+    #[serde(default, deserialize_with = "patch_field")]
+    pub(in crate::api) max_unique_ips: Patch<usize>,
+    #[serde(default, deserialize_with = "patch_field")]
+    pub(in crate::api) enabled: Patch<bool>,
+}
+
+#[derive(Default, Deserialize)]
+pub(in crate::api) struct RotateSecretRequest {
+    pub(in crate::api) secret: Option<String>,
+}
+
+pub(in crate::api) fn parse_optional_expiration(
+    value: Option<&str>,
+) -> Result<Option<DateTime<Utc>>, ApiFailure> {
+    let Some(raw) = value else {
+        return Ok(None);
+    };
+    let parsed = DateTime::parse_from_rfc3339(raw)
+        .map_err(|_| ApiFailure::bad_request("expiration_rfc3339 must be valid RFC3339"))?;
+    Ok(Some(parsed.with_timezone(&Utc)))
+}
+
+pub(in crate::api) fn parse_patch_expiration(
+    value: &Patch<String>,
+) -> Result<Patch<DateTime<Utc>>, ApiFailure> {
+    match value {
+        Patch::Unchanged => Ok(Patch::Unchanged),
+        Patch::Remove => Ok(Patch::Remove),
+        Patch::Set(raw) => {
+            let parsed = DateTime::parse_from_rfc3339(raw)
+                .map_err(|_| ApiFailure::bad_request("expiration_rfc3339 must be valid RFC3339"))?;
+            Ok(Patch::Set(parsed.with_timezone(&Utc)))
+        }
+    }
+}
+
+pub(in crate::api) fn is_valid_user_secret(secret: &str) -> bool {
+    secret.len() == 32 && secret.chars().all(|c| c.is_ascii_hexdigit())
+}
+
+pub(in crate::api) fn is_valid_ad_tag(tag: &str) -> bool {
+    tag.len() == 32 && tag.chars().all(|c| c.is_ascii_hexdigit())
+}
+
+pub(in crate::api) fn is_valid_username(user: &str) -> bool {
+    !user.is_empty()
+        && user.len() <= MAX_USERNAME_LEN
+        && user
+            .chars()
+            .all(|ch| ch.is_ascii_alphanumeric() || matches!(ch, '_' | '-' | '.'))
+}
+
+pub(in crate::api) fn random_user_secret() -> String {
+    static API_SECRET_RNG: OnceLock<SecureRandom> = OnceLock::new();
+    let rng = API_SECRET_RNG.get_or_init(SecureRandom::new);
+    let mut bytes = [0u8; 16];
+    rng.fill(&mut bytes);
+    hex::encode(bytes)
+}

src/api/runtime_min.rs

@@ -541,55 +541,7 @@ pub(super) async fn build_runtime_upstream_quality_data(
     }
 }
 
-pub(super) async fn build_runtime_nat_stun_data(shared: &ApiShared) -> RuntimeNatStunData {
-    let now_epoch_secs = now_epoch_secs();
-    let Some(pool) = shared.me_pool.read().await.clone() else {
-        return RuntimeNatStunData {
-            enabled: false,
-            reason: Some(SOURCE_UNAVAILABLE_REASON),
-            generated_at_epoch_secs: now_epoch_secs,
-            data: None,
-        };
-    };
-
-    let snapshot = pool.api_nat_stun_snapshot().await;
-    RuntimeNatStunData {
-        enabled: true,
-        reason: None,
-        generated_at_epoch_secs: now_epoch_secs,
-        data: Some(RuntimeNatStunPayload {
-            flags: RuntimeNatStunFlagsData {
-                nat_probe_enabled: snapshot.nat_probe_enabled,
-                nat_probe_disabled_runtime: snapshot.nat_probe_disabled_runtime,
-                nat_probe_attempts: snapshot.nat_probe_attempts,
-            },
-            servers: RuntimeNatStunServersData {
-                configured: snapshot.configured_servers,
-                live: snapshot.live_servers.clone(),
-                live_total: snapshot.live_servers.len(),
-            },
-            reflection: RuntimeNatStunReflectionBlockData {
-                v4: snapshot
-                    .reflection_v4
-                    .map(|entry| RuntimeNatStunReflectionData {
-                        addr: entry.addr.to_string(),
-                        age_secs: entry.age_secs,
-                    }),
-                v6: snapshot
-                    .reflection_v6
-                    .map(|entry| RuntimeNatStunReflectionData {
-                        addr: entry.addr.to_string(),
-                        age_secs: entry.age_secs,
-                    }),
-            },
-            stun_backoff_remaining_ms: snapshot.stun_backoff_remaining_ms,
-        }),
-    }
-}
-
-fn now_epoch_secs() -> u64 {
-    SystemTime::now()
-        .duration_since(UNIX_EPOCH)
-        .unwrap_or_default()
-        .as_secs()
-}
+// NAT/STUN runtime projection and timestamping.
+mod nat;
+pub(super) use nat::build_runtime_nat_stun_data;
+use nat::now_epoch_secs;

src/api/runtime_min/nat.rs

@@ -0,0 +1,54 @@
+use super::*;
+
+pub(in crate::api) async fn build_runtime_nat_stun_data(shared: &ApiShared) -> RuntimeNatStunData {
+    let now_epoch_secs = now_epoch_secs();
+    let Some(pool) = shared.me_pool.read().await.clone() else {
+        return RuntimeNatStunData {
+            enabled: false,
+            reason: Some(SOURCE_UNAVAILABLE_REASON),
+            generated_at_epoch_secs: now_epoch_secs,
+            data: None,
+        };
+    };
+
+    let snapshot = pool.api_nat_stun_snapshot().await;
+    RuntimeNatStunData {
+        enabled: true,
+        reason: None,
+        generated_at_epoch_secs: now_epoch_secs,
+        data: Some(RuntimeNatStunPayload {
+            flags: RuntimeNatStunFlagsData {
+                nat_probe_enabled: snapshot.nat_probe_enabled,
+                nat_probe_disabled_runtime: snapshot.nat_probe_disabled_runtime,
+                nat_probe_attempts: snapshot.nat_probe_attempts,
+            },
+            servers: RuntimeNatStunServersData {
+                configured: snapshot.configured_servers,
+                live: snapshot.live_servers.clone(),
+                live_total: snapshot.live_servers.len(),
+            },
+            reflection: RuntimeNatStunReflectionBlockData {
+                v4: snapshot
+                    .reflection_v4
+                    .map(|entry| RuntimeNatStunReflectionData {
+                        addr: entry.addr.to_string(),
+                        age_secs: entry.age_secs,
+                    }),
+                v6: snapshot
+                    .reflection_v6
+                    .map(|entry| RuntimeNatStunReflectionData {
+                        addr: entry.addr.to_string(),
+                        age_secs: entry.age_secs,
+                    }),
+            },
+            stun_backoff_remaining_ms: snapshot.stun_backoff_remaining_ms,
+        }),
+    }
+}
+
+pub(super) fn now_epoch_secs() -> u64 {
+    SystemTime::now()
+        .duration_since(UNIX_EPOCH)
+        .unwrap_or_default()
+        .as_secs()
+}

src/api/runtime_stats.rs

@@ -84,8 +84,7 @@ pub(super) fn build_zero_all_data(stats: &Stats, configured_users: usize) -> Zer
             reconnect_success_total: stats.get_me_reconnect_success(),
             handshake_reject_total: stats.get_me_handshake_reject_total(),
             handshake_error_codes,
-            handshake_error_code_overflow_total: stats
-                .get_me_handshake_error_code_overflow_total(),
+            handshake_error_code_overflow_total: stats.get_me_handshake_error_code_overflow_total(),
             reader_eof_total: stats.get_me_reader_eof_total(),
             idle_close_by_peer_total: stats.get_me_idle_close_by_peer_total(),
             route_drop_no_conn_total: stats.get_me_route_drop_no_conn(),
@@ -527,57 +526,6 @@ async fn get_minimal_payload_cached(
     Some((generated_at_epoch_secs, payload))
 }
 
-fn disabled_me_writers(now_epoch_secs: u64, reason: &'static str) -> MeWritersData {
-    MeWritersData {
-        middle_proxy_enabled: false,
-        reason: Some(reason),
-        generated_at_epoch_secs: now_epoch_secs,
-        summary: MeWritersSummary {
-            configured_dc_groups: 0,
-            configured_endpoints: 0,
-            available_endpoints: 0,
-            available_pct: 0.0,
-            required_writers: 0,
-            alive_writers: 0,
-            coverage_pct: 0.0,
-            fresh_alive_writers: 0,
-            fresh_coverage_pct: 0.0,
-        },
-        writers: Vec::new(),
-    }
-}
-
-fn disabled_dcs(now_epoch_secs: u64, reason: &'static str) -> DcStatusData {
-    DcStatusData {
-        middle_proxy_enabled: false,
-        reason: Some(reason),
-        generated_at_epoch_secs: now_epoch_secs,
-        dcs: Vec::new(),
-    }
-}
-
-fn map_route_kind(value: UpstreamRouteKind) -> &'static str {
-    match value {
-        UpstreamRouteKind::Direct => "direct",
-        UpstreamRouteKind::Socks4 => "socks4",
-        UpstreamRouteKind::Socks5 => "socks5",
-        UpstreamRouteKind::Shadowsocks => "shadowsocks",
-    }
-}
-
-fn map_ip_preference(value: IpPreference) -> &'static str {
-    match value {
-        IpPreference::Unknown => "unknown",
-        IpPreference::PreferV6 => "prefer_v6",
-        IpPreference::PreferV4 => "prefer_v4",
-        IpPreference::BothWork => "both_work",
-        IpPreference::Unavailable => "unavailable",
-    }
-}
-
-fn now_epoch_secs() -> u64 {
-    SystemTime::now()
-        .duration_since(UNIX_EPOCH)
-        .unwrap_or_default()
-        .as_secs()
-}
+// Disabled-state builders and stable upstream enum mappings.
+mod helpers;
+use helpers::*;

src/api/runtime_stats/helpers.rs

@@ -0,0 +1,56 @@
+use super::*;
+
+pub(super) fn disabled_me_writers(now_epoch_secs: u64, reason: &'static str) -> MeWritersData {
+    MeWritersData {
+        middle_proxy_enabled: false,
+        reason: Some(reason),
+        generated_at_epoch_secs: now_epoch_secs,
+        summary: MeWritersSummary {
+            configured_dc_groups: 0,
+            configured_endpoints: 0,
+            available_endpoints: 0,
+            available_pct: 0.0,
+            required_writers: 0,
+            alive_writers: 0,
+            coverage_pct: 0.0,
+            fresh_alive_writers: 0,
+            fresh_coverage_pct: 0.0,
+        },
+        writers: Vec::new(),
+    }
+}
+
+pub(super) fn disabled_dcs(now_epoch_secs: u64, reason: &'static str) -> DcStatusData {
+    DcStatusData {
+        middle_proxy_enabled: false,
+        reason: Some(reason),
+        generated_at_epoch_secs: now_epoch_secs,
+        dcs: Vec::new(),
+    }
+}
+
+pub(super) fn map_route_kind(value: UpstreamRouteKind) -> &'static str {
+    match value {
+        UpstreamRouteKind::Direct => "direct",
+        UpstreamRouteKind::Socks4 => "socks4",
+        UpstreamRouteKind::Socks5 => "socks5",
+        UpstreamRouteKind::Shadowsocks => "shadowsocks",
+    }
+}
+
+pub(super) fn map_ip_preference(value: IpPreference) -> &'static str {
+    match value {
+        IpPreference::Unknown => "unknown",
+        IpPreference::PreferV6 => "prefer_v6",
+        IpPreference::PreferV4 => "prefer_v4",
+        IpPreference::BothWork => "both_work",
+        IpPreference::Unavailable => "unavailable",
+    }
+}
+
+pub(super) fn now_epoch_secs() -> u64 {
+    SystemTime::now()
+        .duration_since(UNIX_EPOCH)
+        .unwrap_or_default()
+        .as_secs()
+}

src/api/runtime_watch.rs

@@ -4,8 +4,8 @@ use std::time::{SystemTime, UNIX_EPOCH};
 
 use tokio::sync::watch;
 
-use crate::maestro::generation::RuntimeWatchState;
 use crate::maestro::control_plane::ProcessControlPlane;
+use crate::maestro::generation::RuntimeWatchState;
 
 use super::ApiRuntimeState;
 use super::events::ApiEventStore;