featherbit/admin/

debug.rs

//! Admin API for debug mode: trace listing/retrieval and the plugin sandbox.
//!
//! Every route except `GET /api/debug/config` responds `404` while
//! `debug.enabled` is false. A `403` would confirm the surface exists, and
//! these endpoints dump request contexts and execute plugins — the highest
//! value target on the box. The `404` is defence in depth behind the Basic Auth
//! layer, not a replacement for it.
//!
//! Discoverability is preserved two ways: each gated rejection logs a warning
//! naming the exact config key, and `GET /api/debug/config` always answers so
//! the web UI can render an explanatory empty state instead of a mystery.

use std::sync::Arc;

use axum::extract::{Path, Query, State};
use axum::http::StatusCode;
use axum::response::IntoResponse;
use axum::routing::{get, post};
use axum::{Json, Router};

use crate::debug::render::{apply_filter, render_trace, TraceFilter};
use crate::debug::sandbox::SandboxRequest;
use crate::state::SharedState;

/// Builds the router for the `/api/debug/*` endpoints.
pub fn router() -> Router<Arc<SharedState>> {
    Router::new()
        .route("/api/debug/config", get(get_config))
        .route("/api/debug/traces", get(list_traces).delete(clear_traces))
        .route("/api/debug/traces/{id}", get(get_trace))
        .route("/api/debug/sandbox", post(run_sandbox))
}

/// The `404` returned when debug mode is off, matching the shape the rest of
/// the Admin API uses for a missing resource.
fn disabled(what: &str) -> axum::response::Response {
    tracing::warn!(
        "{} was requested but debug mode is off; set `debug.enabled: true` in \
         system.yaml (or FEATHERBIT_DEBUG=true) and restart",
        what
    );
    (
        StatusCode::NOT_FOUND,
        Json(serde_json::json!({"error": "not_found"})),
    )
        .into_response()
}

/// `GET /api/debug/config` — the effective debug settings.
///
/// Deliberately **not** gated: it returns only booleans the UI needs to explain
/// itself, and answering it is what turns "the button does nothing" into "debug
/// mode is off, here is the key to set".
async fn get_config(State(state): State<Arc<SharedState>>) -> impl IntoResponse {
    let d = &state.debug;
    Json(serde_json::json!({
        "enabled": d.enabled,
        "sandbox": d.sandbox_enabled,
        "trigger_header": d.trigger_header,
        "trace_all": d.trace_all,
        "capture_bodies": d.capture_bodies,
        "max_traces": d.max_traces,
        "max_steps": d.max_steps,
        "max_body_bytes": d.max_body_bytes,
        "traces_stored": d.len(),
    }))
}

/// `GET /api/debug/traces` — summaries, newest first.
///
/// Optional query filters (`route`, `policy`, `status`, `source`, `limit`) let
/// you narrow the buffer to the recent requests on one policy or route, then
/// select one to inspect via `GET /api/debug/traces/{id}`.
async fn list_traces(
    State(state): State<Arc<SharedState>>,
    Query(filter): Query<TraceFilter>,
) -> impl IntoResponse {
    if !state.debug.enabled {
        return disabled("trace listing");
    }
    let traces = apply_filter(state.debug.list(), &filter);
    // `retention` travels with every listing: an empty `traces` is ambiguous
    // on its own, since a rotated-out match and a match that never happened
    // look identical.
    Json(serde_json::json!({
        "traces": traces,
        "retention": state.debug.retention(),
    }))
    .into_response()
}

/// `GET /api/debug/traces/{id}` — one trace with computed changes.
///
/// Errors: `404` if the id is unknown or has been evicted from the ring buffer.
async fn get_trace(
    State(state): State<Arc<SharedState>>,
    Path(id): Path<String>,
) -> impl IntoResponse {
    if !state.debug.enabled {
        return disabled("trace retrieval");
    }
    match state.debug.get(&id) {
        Some(trace) => Json(render_trace(&trace)).into_response(),
        None => (
            StatusCode::NOT_FOUND,
            Json(serde_json::json!({"error": "not_found"})),
        )
            .into_response(),
    }
}

/// `DELETE /api/debug/traces` — empties the buffer.
async fn clear_traces(State(state): State<Arc<SharedState>>) -> impl IntoResponse {
    if !state.debug.enabled {
        return disabled("trace clearing");
    }
    let removed = state.debug.clear();
    Json(serde_json::json!({ "status": "cleared", "removed": removed })).into_response()
}

fn bad_request(msg: impl Into<String>) -> axum::response::Response {
    (
        StatusCode::BAD_REQUEST,
        Json(serde_json::json!({"error": msg.into()})),
    )
        .into_response()
}

/// `POST /api/debug/sandbox` — run ad-hoc nodes or a named policy against a
/// synthetic context.
///
/// Plugins execute **for real**: outbound callouts are made, rate-limit
/// counters decrement, breakers trip, loggers fire. That is the point (a
/// `key-auth` node that did not resolve real consumers would be a lie), but it
/// is why the endpoint is gated behind `debug.enabled` + `debug.sandbox` on top
/// of admin auth, and why every response carries a `warning`.
///
/// Errors: `400` for a malformed request or a plugin config the compiler
/// rejects; `404` for an unknown policy; `504` if the run exceeds
/// `debug.sandbox_timeout_seconds`.
async fn run_sandbox(
    State(state): State<Arc<SharedState>>,
    Json(req): Json<SandboxRequest>,
) -> impl IntoResponse {
    use crate::debug::sandbox::{run_sandbox as run, SandboxError};
    match run(&state, req).await {
        Ok(r) => Json(serde_json::json!({
            "mode": r.mode,
            "policy": r.policy,
            "warning": "plugins executed for real: outbound calls were made and shared \
                        rate-limit/breaker state was mutated",
            "stored_trace_id": r.stored_trace_id,
            "trace": r.trace,
        }))
        .into_response(),
        Err(SandboxError::Disabled) => disabled("sandbox"),
        Err(SandboxError::SandboxDisabled) => disabled("sandbox (debug.sandbox is false)"),
        Err(SandboxError::BadRequest(e)) => bad_request(e),
        Err(SandboxError::UnknownPolicy(name)) => (
            StatusCode::NOT_FOUND,
            Json(serde_json::json!({"error": format!("unknown policy '{name}'")})),
        )
            .into_response(),
        Err(SandboxError::Timeout(secs)) => (
            StatusCode::GATEWAY_TIMEOUT,
            Json(serde_json::json!({
                "error": "sandbox_timeout",
                "message": format!("run exceeded debug.sandbox_timeout_seconds ({}s)", secs),
            })),
        )
            .into_response(),
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::config::{DebugConfig, GatewayConfig, SystemConfig};
    use crate::config_store::FileConfigStore;
    use crate::debug::store::TraceSummary;
    use crate::debug::TraceSource;

    fn state_with(debug: DebugConfig) -> Arc<SharedState> {
        // Every section of both configs has a serde default, so an empty
        // document is the cheapest way to get a valid baseline.
        let system = SystemConfig {
            debug,
            ..serde_yaml::from_str::<SystemConfig>("{}").unwrap()
        };
        let gateway: GatewayConfig = serde_yaml::from_str("{}").unwrap();
        Arc::new(
            SharedState::new(
                system,
                gateway,
                None,
                Arc::new(FileConfigStore::new(std::path::PathBuf::from(
                    "gateway.yaml",
                ))),
            )
            .unwrap(),
        )
    }

    /// The gate must not depend on the handler being reached — assert the
    /// predicate the handlers share.
    #[test]
    fn test_disabled_by_default() {
        let s = state_with(DebugConfig::default());
        assert!(!s.debug.enabled);
    }

    #[tokio::test]
    async fn test_config_endpoint_answers_even_when_disabled() {
        let s = state_with(DebugConfig::default());
        let resp = get_config(State(s)).await.into_response();
        // This is the one endpoint that must not 404: the UI reads it to
        // explain *why* debugging is unavailable.
        assert_eq!(resp.status(), StatusCode::OK);
    }

    #[tokio::test]
    async fn test_trace_routes_404_when_disabled() {
        let s = state_with(DebugConfig::default());
        assert_eq!(
            list_traces(State(s.clone()), Query(TraceFilter::default()))
                .await
                .into_response()
                .status(),
            StatusCode::NOT_FOUND
        );
        assert_eq!(
            get_trace(State(s.clone()), Path("any".to_string()))
                .await
                .into_response()
                .status(),
            StatusCode::NOT_FOUND
        );
        assert_eq!(
            clear_traces(State(s.clone()))
                .await
                .into_response()
                .status(),
            StatusCode::NOT_FOUND
        );
        assert_eq!(
            run_sandbox(State(s), Json(SandboxRequest::default()))
                .await
                .into_response()
                .status(),
            StatusCode::NOT_FOUND
        );
    }

    #[tokio::test]
    async fn test_sandbox_404s_when_only_sandbox_is_off() {
        let s = state_with(DebugConfig {
            enabled: true,
            sandbox: false,
            ..Default::default()
        });
        // Tracing still works...
        assert_eq!(
            list_traces(State(s.clone()), Query(TraceFilter::default()))
                .await
                .into_response()
                .status(),
            StatusCode::OK
        );
        // ...but plugin execution is separately withheld.
        assert_eq!(
            run_sandbox(State(s), Json(SandboxRequest::default()))
                .await
                .into_response()
                .status(),
            StatusCode::NOT_FOUND
        );
    }

    #[tokio::test]
    async fn test_sandbox_requires_exactly_one_mode() {
        let s = state_with(DebugConfig {
            enabled: true,
            ..Default::default()
        });
        // Neither.
        assert_eq!(
            run_sandbox(State(s.clone()), Json(SandboxRequest::default()))
                .await
                .into_response()
                .status(),
            StatusCode::BAD_REQUEST
        );
        // Both.
        let both = SandboxRequest {
            nodes: Some(Vec::new()),
            policy: Some("p".to_string()),
            ..Default::default()
        };
        assert_eq!(
            run_sandbox(State(s), Json(both))
                .await
                .into_response()
                .status(),
            StatusCode::BAD_REQUEST
        );
    }

    #[tokio::test]
    async fn test_sandbox_unknown_policy_404s() {
        let s = state_with(DebugConfig {
            enabled: true,
            ..Default::default()
        });
        let req = SandboxRequest {
            policy: Some("nope".to_string()),
            ..Default::default()
        };
        assert_eq!(
            run_sandbox(State(s), Json(req))
                .await
                .into_response()
                .status(),
            StatusCode::NOT_FOUND
        );
    }

    fn summary(route: &str, policy: &str, status: u16, source: TraceSource) -> TraceSummary {
        TraceSummary {
            id: format!("{route}-{status}"),
            seq: 0,
            source,
            started_ms: 0,
            route: Some(route.to_string()),
            policy: policy.to_string(),
            method: "GET".to_string(),
            path: "/x".to_string(),
            status,
            duration_us: 1,
            step_count: 1,
            error_count: 0,
            captured_bodies: false,
        }
    }

    fn sample() -> Vec<TraceSummary> {
        vec![
            summary("echo-api", "echo-policy", 200, TraceSource::Request),
            summary("secure-api", "secure-policy", 401, TraceSource::Request),
            summary("echo-api", "echo-policy", 502, TraceSource::Request),
            summary("s", "echo-policy", 200, TraceSource::Sandbox),
        ]
    }

    fn ids(traces: Vec<TraceSummary>) -> Vec<String> {
        traces.into_iter().map(|t| t.id).collect()
    }

    #[test]
    fn test_no_filter_returns_all() {
        assert_eq!(apply_filter(sample(), &TraceFilter::default()).len(), 4);
    }

    #[test]
    fn test_filter_by_route() {
        let f = TraceFilter {
            route: Some("echo-api".to_string()),
            ..Default::default()
        };
        assert_eq!(apply_filter(sample(), &f).len(), 2);
    }

    #[test]
    fn test_filter_by_policy_spans_routes() {
        // echo-policy appears on a route and a sandbox run.
        let f = TraceFilter {
            policy: Some("echo-policy".to_string()),
            ..Default::default()
        };
        assert_eq!(apply_filter(sample(), &f).len(), 3);
    }

    #[test]
    fn test_filters_are_anded() {
        let f = TraceFilter {
            policy: Some("echo-policy".to_string()),
            status: Some(200),
            source: Some("request".to_string()),
            ..Default::default()
        };
        assert_eq!(ids(apply_filter(sample(), &f)), vec!["echo-api-200"]);
    }

    #[test]
    fn test_empty_filter_string_is_ignored() {
        // A bare `?route=` must not filter everything out.
        let f = TraceFilter {
            route: Some("  ".to_string()),
            ..Default::default()
        };
        assert_eq!(apply_filter(sample(), &f).len(), 4);
    }

    #[test]
    fn test_limit_applies_after_filtering() {
        let f = TraceFilter {
            policy: Some("echo-policy".to_string()),
            limit: Some(2),
            ..Default::default()
        };
        assert_eq!(apply_filter(sample(), &f).len(), 2);
    }

    #[test]
    fn test_filter_by_source() {
        let f = TraceFilter {
            source: Some("sandbox".to_string()),
            ..Default::default()
        };
        assert_eq!(ids(apply_filter(sample(), &f)), vec!["s-200"]);
    }

    #[tokio::test]
    async fn test_sandbox_rejects_unknown_plugin_type() {
        let s = state_with(DebugConfig {
            enabled: true,
            ..Default::default()
        });
        let req = SandboxRequest {
            nodes: Some(vec![crate::config::NodeConfig {
                id: "x".to_string(),
                node_type: "no-such-plugin".to_string(),
                config: Default::default(),
                config_ref: None,
                position: None,
            }]),
            ..Default::default()
        };
        assert_eq!(
            run_sandbox(State(s), Json(req))
                .await
                .into_response()
                .status(),
            StatusCode::BAD_REQUEST
        );
    }

    /// A sandbox run of a policy that uses a supernode must expand it the
    /// same way the data plane does — namespaced inner steps in the trace.
    #[tokio::test]
    async fn test_sandbox_expands_supernodes() {
        let system = SystemConfig {
            debug: DebugConfig {
                enabled: true,
                ..Default::default()
            },
            ..serde_yaml::from_str::<SystemConfig>("{}").unwrap()
        };
        let gateway: GatewayConfig = serde_yaml::from_str(
            r#"
supernodes:
  - name: secured-call
    nodes:
      - { id: input,  type: input }
      - { id: output, type: output }
      - { id: error,  type: error }
      - { id: c, type: cors }
    edges:
      - { from: input.out, to: c.in }
      - { from: c.success, to: output.in }
      - { from: c.preflight, to: output.in }
policies:
  - name: p
    nodes:
      - { id: listener, type: listener }
      - { id: sec, type: supernode, config: { name: secured-call } }
      - { id: client, type: client }
    edges:
      - { from: listener.out, to: sec.in }
      - { from: sec.success, to: client.in }
"#,
        )
        .unwrap();
        let s = Arc::new(
            SharedState::new(
                system,
                gateway,
                None,
                Arc::new(FileConfigStore::new(std::path::PathBuf::from(
                    "gateway.yaml",
                ))),
            )
            .unwrap(),
        );

        let req = SandboxRequest {
            policy: Some("p".to_string()),
            ..Default::default()
        };
        let resp = run_sandbox(State(s), Json(req)).await.into_response();
        assert_eq!(resp.status(), StatusCode::OK);

        let bytes = axum::body::to_bytes(resp.into_body(), usize::MAX)
            .await
            .unwrap();
        let v: serde_json::Value = serde_json::from_slice(&bytes).unwrap();
        let steps = v["trace"]["steps"].as_array().unwrap();
        assert!(
            steps
                .iter()
                .any(|s| s["node_id"].as_str().unwrap_or("").starts_with("sec/")),
            "expected a namespaced sec/* step, got: {v}"
        );
    }

    /// A sandbox run resolves config_ref exactly like the data plane: the
    /// mocking node inherits the shared config and answers with its body.
    #[tokio::test]
    async fn test_sandbox_resolves_plugin_configs() {
        let system = SystemConfig {
            debug: DebugConfig {
                enabled: true,
                ..Default::default()
            },
            ..serde_yaml::from_str::<SystemConfig>("{}").unwrap()
        };
        let gateway: GatewayConfig = serde_yaml::from_str(
            r#"
plugin_configs:
  - name: m
    type: mocking
    config: { response_status: 200, response_example: "from-shared", content_type: "text/plain" }
policies:
  - name: p
    nodes:
      - { id: listener, type: listener }
      - { id: mock, type: mocking, config_ref: m }
      - { id: client, type: client }
    edges:
      - { from: listener.out, to: mock.in }
      - { from: mock.success, to: client.in }
"#,
        )
        .unwrap();
        let s = Arc::new(
            SharedState::new(
                system,
                gateway,
                None,
                Arc::new(FileConfigStore::new(std::path::PathBuf::from(
                    "gateway.yaml",
                ))),
            )
            .unwrap(),
        );

        let req = SandboxRequest {
            policy: Some("p".to_string()),
            ..Default::default()
        };
        let resp = run_sandbox(State(s), Json(req)).await.into_response();
        assert_eq!(resp.status(), StatusCode::OK);
        let bytes = axum::body::to_bytes(resp.into_body(), usize::MAX)
            .await
            .unwrap();
        let v: serde_json::Value = serde_json::from_slice(&bytes).unwrap();
        let steps = v["trace"]["steps"].as_array().unwrap();
        // The mocking node ran with the shared body -> response body captured
        // in the final snapshot contains it (bodies off => assert via status).
        assert!(
            steps
                .iter()
                .any(|s| s["node_id"] == "mock" && s["outcome"]["kind"] == "success"),
            "{v}"
        );
    }
}