footing 0.6.6

Feature-gated foundations for Rust backend services
Documentation
//! Run with `cargo run --example request_correlation --features http`.
//!
//! Starts an application and a mock downstream on temporary loopback ports,
//! prints the headers observed downstream, then stops both servers.
//! The repository's Reqx development dependency selects ring for example clients.
//! Applications can use their own reqx dependency; correlation propagation only
//! needs Footing's `http` context, and this loopback example uses plain HTTP.
//!
//! Correlation is explicitly allowed only for the configured downstream origin
//! and the fixed `/inspect` endpoint. The request cannot supply a destination,
//! and redirects are disabled. In an application, select permitted downstreams
//! from trusted configuration before adding correlation headers.
//!
//! Only `x-request-id` and a validated `traceparent` are copied. Incoming cookies,
//! authorization, and other headers are not forwarded. These identifiers provide
//! correlation, not authentication. This is passive traceparent propagation: it
//! does not create a child span or establish a complete OpenTelemetry trace.
//! The downstream call has a total deadline covering retries and body reads,
//! and a response size limit. Choose these budgets for the downstream contract.

use std::{io, net::Ipv4Addr, time::Duration};

use axum::{
    Json, Router,
    extract::State,
    http::{HeaderMap, HeaderName, StatusCode, header},
    middleware,
    routing::get,
};
use footing::http::{
    REQUEST_ID_HEADER_NAME, RequestContext, TRACEPARENT_HEADER_NAME, request_context_middleware,
};
use reqx::prelude::RedirectPolicy;
use serde::{Deserialize, Serialize};
use tokio::{net::TcpListener, sync::oneshot, task::JoinHandle};

type BoxError = Box<dyn std::error::Error + Send + Sync>;

const DEMO_TRACEPARENT: &str = "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01";
const DOWNSTREAM_TIMEOUT: Duration = Duration::from_secs(5);
const MAX_DOWNSTREAM_RESPONSE_BYTES: usize = 16 * 1024;

#[derive(Debug, Deserialize, Serialize)]
struct ReceivedHeaders {
    request_id: Option<String>,
    traceparent: Option<String>,
    has_authorization: bool,
    has_cookie: bool,
}

async fn inspect(headers: HeaderMap) -> Json<ReceivedHeaders> {
    Json(ReceivedHeaders {
        request_id: headers
            .get(REQUEST_ID_HEADER_NAME)
            .and_then(|value| value.to_str().ok())
            .map(str::to_owned),
        traceparent: headers
            .get(TRACEPARENT_HEADER_NAME)
            .and_then(|value| value.to_str().ok())
            .map(str::to_owned),
        has_authorization: headers.contains_key(header::AUTHORIZATION),
        has_cookie: headers.contains_key(header::COOKIE),
    })
}

async fn forward(
    State(client): State<reqx::Client>,
    context: RequestContext,
) -> Result<Json<ReceivedHeaders>, StatusCode> {
    // Keep correlation on the request builder. A shared client's default headers
    // or a mutable global context would mix concurrent incoming requests.
    let mut request = client.get("/inspect").header(
        HeaderName::from_static(REQUEST_ID_HEADER_NAME),
        context.request_id().into(),
    );
    if let Some(traceparent) = context.traceparent_value() {
        request = request.header(
            HeaderName::from_static(TRACEPARENT_HEADER_NAME),
            traceparent.into(),
        );
    }
    request
        .send_json()
        .await
        .map(Json)
        .map_err(|error| match error.code() {
            reqx::ErrorCode::Timeout | reqx::ErrorCode::DeadlineExceeded => {
                StatusCode::GATEWAY_TIMEOUT
            }
            _ => StatusCode::BAD_GATEWAY,
        })
}

fn application(downstream_origin: &str, downstream_timeout: Duration) -> reqx::Result<Router> {
    let client = reqx::Client::builder(downstream_origin)
        .redirect_policy(RedirectPolicy::none())
        .total_timeout(Some(downstream_timeout))
        .max_response_body_bytes(MAX_DOWNSTREAM_RESPONSE_BYTES)
        .build()?;
    Ok(Router::new()
        .route("/forward", get(forward))
        .layer(middleware::from_fn(request_context_middleware))
        .with_state(client))
}

// Local demo/test servers; no external service or fixed port is required.
struct LocalServer {
    origin: String,
    shutdown: oneshot::Sender<()>,
    task: JoinHandle<io::Result<()>>,
}

impl LocalServer {
    async fn start(router: Router) -> io::Result<Self> {
        let listener = TcpListener::bind((Ipv4Addr::LOCALHOST, 0)).await?;
        let origin = format!("http://{}", listener.local_addr()?);
        let (shutdown, receiver) = oneshot::channel();
        let task = tokio::spawn(async move {
            axum::serve(listener, router)
                .with_graceful_shutdown(async move {
                    let _ = receiver.await;
                })
                .await
        });
        Ok(Self {
            origin,
            shutdown,
            task,
        })
    }

    async fn stop(self) -> Result<(), BoxError> {
        let _ = self.shutdown.send(());
        self.task.await??;
        Ok(())
    }
}

#[tokio::main(flavor = "current_thread")]
async fn main() -> Result<(), BoxError> {
    let downstream = LocalServer::start(Router::new().route("/inspect", get(inspect))).await?;
    let app = LocalServer::start(application(&downstream.origin, DOWNSTREAM_TIMEOUT)?).await?;
    let caller = reqx::Client::builder(app.origin.as_str()).build()?;
    let received: ReceivedHeaders = caller
        .get("/forward")
        .try_header(REQUEST_ID_HEADER_NAME, "demo-request")?
        .try_header(TRACEPARENT_HEADER_NAME, DEMO_TRACEPARENT)?
        .try_header("authorization", "Bearer demo-only")?
        .try_header("cookie", "session=demo-only")?
        .send_json()
        .await?;
    println!("{}", serde_json::to_string_pretty(&received)?);
    app.stop().await?;
    downstream.stop().await?;
    Ok(())
}

#[cfg(test)]
mod tests {
    use std::{
        sync::{
            Arc,
            atomic::{AtomicBool, AtomicUsize, Ordering},
        },
        time::Duration,
    };

    use axum::{body::Body, http::Request, response::Redirect};
    use footing::http::RequestId;
    use tokio::{sync::Barrier, time::timeout};
    use tower::ServiceExt;

    use super::*;

    #[tokio::test]
    async fn concurrent_requests_keep_their_own_correlation() -> Result<(), BoxError> {
        // Both requests must reach the downstream before either can complete.
        let barrier = Arc::new(Barrier::new(2));
        let downstream = LocalServer::start(Router::new().route(
            "/inspect",
            get(move |headers: HeaderMap| {
                let barrier = barrier.clone();
                async move {
                    barrier.wait().await;
                    inspect(headers).await
                }
            }),
        ))
        .await?;
        let app = LocalServer::start(application(&downstream.origin, DOWNSTREAM_TIMEOUT)?).await?;
        let caller = reqx::Client::builder(app.origin.as_str()).build()?;
        let second_traceparent = "00-11111111111111111111111111111111-2222222222222222-00";
        let first = caller
            .get("/forward")
            .try_header(REQUEST_ID_HEADER_NAME, "request-first")?
            .try_header(TRACEPARENT_HEADER_NAME, DEMO_TRACEPARENT)?;
        let second = caller
            .get("/forward")
            .try_header(REQUEST_ID_HEADER_NAME, "request-second")?
            .try_header(TRACEPARENT_HEADER_NAME, second_traceparent)?;
        let (first, second) = timeout(Duration::from_secs(5), async {
            tokio::try_join!(
                first.send_json::<ReceivedHeaders>(),
                second.send_json::<ReceivedHeaders>()
            )
        })
        .await??;
        assert_eq!(first.request_id.as_deref(), Some("request-first"));
        assert_eq!(first.traceparent.as_deref(), Some(DEMO_TRACEPARENT));
        assert_eq!(second.request_id.as_deref(), Some("request-second"));
        assert_eq!(second.traceparent.as_deref(), Some(second_traceparent));
        app.stop().await?;
        downstream.stop().await?;
        Ok(())
    }

    #[tokio::test]
    async fn missing_or_invalid_traceparent_and_credentials_are_not_forwarded()
    -> Result<(), BoxError> {
        let downstream = LocalServer::start(Router::new().route("/inspect", get(inspect))).await?;
        let app = LocalServer::start(application(&downstream.origin, DOWNSTREAM_TIMEOUT)?).await?;
        let caller = reqx::Client::builder(app.origin.as_str()).build()?;
        for traceparent in [Some("not-a-traceparent"), None] {
            let mut request = caller
                .get("/forward")
                .try_header("authorization", "Bearer incoming-secret")?
                .try_header("cookie", "session=incoming-secret")?;
            if let Some(traceparent) = traceparent {
                request = request.try_header(TRACEPARENT_HEADER_NAME, traceparent)?;
            }
            let response = timeout(Duration::from_secs(5), request.send()).await??;
            let received: ReceivedHeaders = response.json()?;
            let generated_id = response.headers()[REQUEST_ID_HEADER_NAME].to_str()?;
            assert!(RequestId::new(generated_id).is_ok());
            assert_eq!(received.request_id.as_deref(), Some(generated_id));
            assert_eq!(received.traceparent, None);
            assert!(!received.has_authorization);
            assert!(!received.has_cookie);
        }
        app.stop().await?;
        downstream.stop().await?;
        Ok(())
    }

    #[tokio::test]
    async fn oversized_downstream_json_is_rejected_before_deserialization() -> Result<(), BoxError>
    {
        let downstream = LocalServer::start(Router::new().route(
            "/inspect",
            get(|| async {
                // Valid JSON that ReceivedHeaders would otherwise accept:
                // unknown fields must still count toward the response limit.
                Json(serde_json::json!({
                    "has_authorization": false,
                    "has_cookie": false,
                    "padding": "x".repeat(MAX_DOWNSTREAM_RESPONSE_BYTES),
                }))
            }),
        ))
        .await?;
        let response = application(&downstream.origin, DOWNSTREAM_TIMEOUT)?
            .oneshot(Request::get("/forward").body(Body::empty())?)
            .await?;
        assert_eq!(response.status(), StatusCode::BAD_GATEWAY);
        downstream.stop().await?;
        Ok(())
    }

    #[tokio::test]
    async fn stalled_downstream_returns_gateway_timeout_within_the_total_budget()
    -> Result<(), BoxError> {
        let timeout_budget = Duration::from_millis(250);
        let reached_downstream = Arc::new(AtomicBool::new(false));
        let release = Arc::new(tokio::sync::Notify::new());
        let downstream = LocalServer::start(Router::new().route(
            "/inspect",
            get({
                let reached_downstream = reached_downstream.clone();
                let release = release.clone();
                move || {
                    let reached_downstream = reached_downstream.clone();
                    let release = release.clone();
                    async move {
                        reached_downstream.store(true, Ordering::Relaxed);
                        release.notified().await;
                        StatusCode::NO_CONTENT
                    }
                }
            }),
        ))
        .await?;
        let response = timeout(
            timeout_budget + Duration::from_secs(1),
            application(&downstream.origin, timeout_budget)?
                .oneshot(Request::get("/forward").body(Body::empty())?),
        )
        .await??;
        release.notify_one();
        assert_eq!(response.status(), StatusCode::GATEWAY_TIMEOUT);
        assert!(
            reached_downstream.load(Ordering::Relaxed),
            "the request must reach the stalled handler before timing out"
        );
        downstream.stop().await?;
        Ok(())
    }

    #[tokio::test]
    async fn redirect_cannot_send_correlation_to_another_origin() -> Result<(), BoxError> {
        let unexpected_requests = Arc::new(AtomicUsize::new(0));
        let observed_requests = unexpected_requests.clone();
        let other = LocalServer::start(Router::new().route(
            "/inspect",
            get(move |headers: HeaderMap| {
                observed_requests.fetch_add(1, Ordering::SeqCst);
                inspect(headers)
            }),
        ))
        .await?;
        let location = format!("{}/inspect", other.origin);
        let downstream = LocalServer::start(Router::new().route(
            "/inspect",
            get(move || {
                let location = location.clone();
                async move { Redirect::temporary(&location) }
            }),
        ))
        .await?;
        let incoming = Request::builder()
            .uri("/forward")
            .header(REQUEST_ID_HEADER_NAME, "redirect-request")
            .header(TRACEPARENT_HEADER_NAME, DEMO_TRACEPARENT)
            .body(Body::empty())?;
        let response = timeout(
            Duration::from_secs(5),
            application(&downstream.origin, DOWNSTREAM_TIMEOUT)?.oneshot(incoming),
        )
        .await??;
        assert_eq!(response.status(), StatusCode::BAD_GATEWAY);
        assert_eq!(unexpected_requests.load(Ordering::SeqCst), 0);
        downstream.stop().await?;
        other.stop().await?;
        Ok(())
    }
}