wordval-web 1.0.13

Wordval web layer: router, middleware, extractors, responses, session-based authentication
Documentation
//! 客户端身份中间件:统一可信 client IP 解析与请求入口打点
//!
//! 只解析一次客户端 IP 并放入 request extensions(`ClientIp`),
//! 访问日志、限流、nonce 等下游层读取同一个值,避免各层
//! 使用不同代理策略导致同一请求出现多个 IP 结论。
//! 同时在请求进入时打点注入 [`RequestStart`],配合
//! [`crate::extract::ClientContext`] 提取器,业务侧无需自行计时。

use axum::extract::ConnectInfo;
use axum::{extract::Request, response::Response};
use std::future::Future;
use std::net::SocketAddr;
use std::pin::Pin;
use std::sync::Arc;
use std::task::{Context, Poll};
use std::time::Instant;
use tower::{Layer, Service};
use wordval_utils::web::{extract_client_ip_trusted, TrustedProxies};

/// 已解析的客户端 IP(request extensions 中读取,String 形态与现有日志/限流一致)
#[derive(Debug, Clone)]
pub struct ClientIp(pub String);

/// 请求入口时刻(本层在请求进入时打点注入 request extensions)
///
/// 是整条中间件链对请求的最早观测时刻(仅 RequestId 层更外),
/// 供 [`crate::extract::ClientContext`] 等下游读取;业务侧审计耗时
/// 直接取该打点,不必自己记 `Instant`。
#[derive(Debug, Clone, Copy)]
pub struct RequestStart(pub Instant);

/// 客户端身份中间件
///
/// - `trusted` 为空:只取直连对端 IP(connect_info),不读取任何代理头;
/// - `trusted` 非空:从 `X-Forwarded-For` / `CF-Connecting-IP` 读取真实 IP
///   (跳过可信跳板网段)。
#[derive(Clone)]
pub struct ClientIdentityLayer {
    /// 可信代理网段(空 = 不信任任何代理头)
    pub trusted: Arc<TrustedProxies>,
}

impl<S> Layer<S> for ClientIdentityLayer {
    type Service = ClientIdentityService<S>;

    fn layer(&self, inner: S) -> Self::Service {
        ClientIdentityService {
            inner,
            trusted: self.trusted.clone(),
        }
    }
}

#[derive(Clone)]
/// 客户端身份服务——解析可信 client IP 并注入 extensions
pub struct ClientIdentityService<S> {
    /// 下游服务
    inner: S,
    /// 可信代理网段
    trusted: Arc<TrustedProxies>,
}

impl<S, ReqBody> Service<Request<ReqBody>> for ClientIdentityService<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, req: Request<ReqBody>) -> Self::Future {
        // 入口打点在最前:RequestStart 记录请求进入本层的时刻
        let started = Instant::now();
        let connect_ip = req
            .extensions()
            .get::<ConnectInfo<SocketAddr>>()
            .map(|c| c.0)
            .unwrap_or(SocketAddr::from(([0, 0, 0, 0], 0)));
        // 安全默认:不配置可信代理时仅取直连对端 IP;
        // 配置了 trusted_proxies 时才从代理头读取真实 IP(跳过可信跳板)。
        let ip = if self.trusted.is_empty() {
            connect_ip.ip().to_string()
        } else {
            extract_client_ip_trusted(req.headers(), &connect_ip, &self.trusted)
        };

        let mut req = req;
        req.extensions_mut().insert(RequestStart(started));
        req.extensions_mut().insert(ClientIp(ip));
        let replacement = self.inner.clone();
        let mut inner = std::mem::replace(&mut self.inner, replacement);
        Box::pin(async move { inner.call(req).await })
    }
}