feat(observability): add request id middleware and access logs

Author: zubeyralmaho

docs/API_HTTP.md

@@ -9,6 +9,11 @@ Authentication notes:
   - `x-spatiad-dispatcher-token: <token>`
 - Dispatch endpoints are rate-limited per actor and may return `429 Too Many Requests`.
 
+Request tracing notes:
+
+- Every HTTP response includes `x-request-id`.
+- If client sends `x-request-id`, server echoes it back; otherwise server generates one.
+
 ## GET /health
 
 Response:

rust/crates/spatiad-api/Cargo.toml

@@ -18,5 +18,6 @@ spatiad-types = { path = "../spatiad-types" }
 spatiad-ws = { path = "../spatiad-ws" }
 spatiad-core = { path = "../spatiad-core" }
 tokio.workspace = true
+tracing.workspace = true
 tower = { version = "0.5", features = ["util"] }
 uuid.workspace = true

rust/crates/spatiad-api/src/lib.rs

@@ -2,9 +2,11 @@ use std::{collections::{HashMap, VecDeque}, sync::Arc};
 
 use axum::{
     extract::ws::Message,
+    extract::Request,
     extract::{Path, Query, State, WebSocketUpgrade},
-    http::{HeaderMap, StatusCode},
-    response::IntoResponse,
+    http::{HeaderMap, HeaderValue, StatusCode},
+    middleware::{self, Next},
+    response::{IntoResponse, Response},
     routing::{get, post},
     Json, Router,
 };
@@ -19,6 +21,7 @@ use spatiad_types::{Coordinates, DriverStatus, JobRequest, MatchResult, OfferSta
 use spatiad_ws::{DriverInbound, DriverOutbound};
 use tokio::sync::{mpsc, Mutex};
 use tokio::time::{interval, sleep, Duration};
+use tracing::info;
 use uuid::Uuid;
 
 mod validation;
@@ -205,9 +208,50 @@ pub fn router(state: ApiState) -> Router {
         .route("/api/v1/dispatch/job/:job_id", get(dispatch_job_status))
         .route("/api/v1/dispatch/job/:job_id/events", get(dispatch_job_events))
         .route("/api/v1/stream/driver/:driver_id", get(driver_ws))
+        .layer(middleware::from_fn(request_context_middleware))
         .with_state(state)
 }
 
+async fn request_context_middleware(mut request: Request, next: Next) -> Response {
+    let started = std::time::Instant::now();
+    let method = request.method().clone();
+    let path = request.uri().path().to_string();
+
+    let request_id = request
+        .headers()
+        .get("x-request-id")
+        .and_then(|value| value.to_str().ok())
+        .map(|value| value.to_string())
+        .unwrap_or_else(|| Uuid::new_v4().to_string());
+
+    if let Ok(header) = HeaderValue::from_str(&request_id) {
+        request
+            .headers_mut()
+            .insert("x-request-id", header);
+    }
+
+    let mut response = next.run(request).await;
+    let status = response.status();
+    let elapsed_ms = started.elapsed().as_millis();
+
+    if let Ok(header) = HeaderValue::from_str(&request_id) {
+        response
+            .headers_mut()
+            .insert("x-request-id", header);
+    }
+
+    info!(
+        request_id = %request_id,
+        method = %method,
+        path = %path,
+        status = status.as_u16(),
+        duration_ms = elapsed_ms,
+        "http request",
+    );
+
+    response
+}
+
 async fn health() -> Json<HealthResponse> {
     Json(HealthResponse {
         status: "ok",

rust/crates/spatiad-api/tests/integration_tests.rs

@@ -95,6 +95,51 @@ mod tests {
         assert_eq!(body["active_sessions"], 0);
     }
 
+    #[tokio::test]
+    async fn test_health_response_includes_generated_request_id() {
+        let state = setup_test_state();
+        let app = router(state);
+
+        let request = Request::builder()
+            .method("GET")
+            .uri("/health")
+            .body(Body::empty())
+            .unwrap();
+
+        let response = app.oneshot(request).await.unwrap();
+        let header = response.headers().get("x-request-id").cloned();
+
+        assert!(header.is_some());
+        let header_value = header.unwrap();
+        let request_id = header_value
+            .to_str()
+            .expect("request id header should be valid utf8");
+        assert!(!request_id.is_empty());
+    }
+
+    #[tokio::test]
+    async fn test_health_preserves_incoming_request_id() {
+        let state = setup_test_state();
+        let app = router(state);
+
+        let request = Request::builder()
+            .method("GET")
+            .uri("/health")
+            .header("x-request-id", "req-123")
+            .body(Body::empty())
+            .unwrap();
+
+        let response = app.oneshot(request).await.unwrap();
+        let request_id = response
+            .headers()
+            .get("x-request-id")
+            .expect("request id should be present")
+            .to_str()
+            .expect("request id header should be valid utf8");
+
+        assert_eq!(request_id, "req-123");
+    }
+
     #[tokio::test]
     async fn test_driver_upsert() {
         let state = setup_test_state();