wordval-web 1.0.13

Wordval web layer: router, middleware, extractors, responses, session-based authentication
Documentation
//! 请求 ID 中间件
//!
//! 为每个请求生成或复用 request-id:
//! - 入站 `x-request-id` 需通过长度/字符集校验,非法值生成新的服务端 ID
//!   (不信任客户端伪造的内部链路 ID);
//! - ID 同时注入 request extensions(`RequestId`)与响应头 `x-request-id`;
//! - 建立以 request ID、method、path 为字段的 tracing span,串联全链路日志。

use axum::http::{HeaderName, HeaderValue};
use axum::{extract::Request, response::Response};
use std::future::Future;
use std::pin::Pin;
use std::task::{Context, Poll};
use tower::{Layer, Service};
use tracing::Instrument;

/// 入站 request-id 长度上限(超长视为非法,重新生成)
const MAX_INBOUND_ID_LEN: usize = 128;

/// 入站 request-id 允许的字符集:字母数字与 `-` `_` `.`
fn is_valid_request_id(s: &str) -> bool {
    !s.is_empty()
        && s.len() <= MAX_INBOUND_ID_LEN
        && s.bytes()
            .all(|b| b.is_ascii_alphanumeric() || b == b'-' || b == b'_' || b == b'.')
}

/// 已解析的请求 ID(request extensions 中读取)
#[derive(Debug, Clone)]
pub struct RequestId(pub String);

/// 请求 ID 中间件
///
/// 为每个请求分配一个 UUID v7(时间有序),写入 `x-request-id` 响应头和 tracing span,
/// 便于日志串联和全链路追踪。客户端携带的合法 `x-request-id` 会被复用,
/// 非法值(超长/非法字符)视为伪造,替换为服务端生成的新 ID。
#[derive(Clone)]
pub struct RequestIdLayer;

impl<S> Layer<S> for RequestIdLayer {
    type Service = RequestIdService<S>;

    fn layer(&self, inner: S) -> Self::Service {
        RequestIdService { inner }
    }
}

#[derive(Clone)]
/// 请求 ID 服务——为每个请求分配 UUID 并注入到响应头
pub struct RequestIdService<S> {
    /// 下游服务
    inner: S,
}

impl<S, ReqBody> Service<Request<ReqBody>> for RequestIdService<S>
where
    S: Service<Request<ReqBody>, Response = Response> + Clone + Send + 'static,
    S::Future: Send + 'static,
    ReqBody: Send + 'static,
{
    type Response = S::Response;
    type Error = S::Error;
    type Future = Pin<Box<dyn Future<Output = Result<Self::Response, Self::Error>> + Send>>;

    fn poll_ready(&mut self, cx: &mut Context<'_>) -> Poll<Result<(), Self::Error>> {
        self.inner.poll_ready(cx)
    }

    fn call(&mut self, mut req: Request<ReqBody>) -> Self::Future {
        // HeaderMap 名称大小写不敏感,直接按名称取;非法值视为伪造并生成新 ID
        let request_id = req
            .headers()
            .get("x-request-id")
            .and_then(|v| v.to_str().ok())
            .filter(|s| is_valid_request_id(s))
            .map(|s| s.to_string())
            .unwrap_or_else(wordval_utils::Sid::short);

        // request_id 已通过 is_valid_request_id 字符集校验(字母数字 - _ .),
        // 必然为合法 header 值,解析一次复用,避免重复解析
        let header_val = HeaderValue::from_str(&request_id)
            .unwrap_or_else(|_| HeaderValue::from_static(""));
        req.headers_mut()
            .insert(HeaderName::from_static("x-request-id"), header_val.clone());
        req.extensions_mut().insert(RequestId(request_id.clone()));

        let span = tracing::info_span!(
            "http_request",
            request_id = %request_id,
            method = %req.method(),
            path = %req.uri().path()
        );
        let replacement = self.inner.clone();
        let mut inner = std::mem::replace(&mut self.inner, replacement);

        Box::pin(async move {
            // span 必须包裹整个请求处理过程(含内层全部中间件与 handler),
            // 否则链路日志无法关联到该请求
            let mut result = inner.call(req).instrument(span).await;
            // 即使内层短路(401/403/404/429/预检)也补写响应头
            if let Ok(resp) = &mut result {
                resp.headers_mut().insert(
                    HeaderName::from_static("x-request-id"),
                    header_val,
                );
            }
            result
        })
    }
}