garrison 0.9.0

Garrison - 面向 Rust 生态的一站式身份认证鉴权框架
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
// Copyright (c) 2026 Kirky.X🌠
// SPDX-License-Identifier: Apache-2.0

//! X-Request-ID 中间件(warp):warp 的 `wrap_fn` 只能组合 Filter、无法用自有 future 包住内层 filter 执行,
//! handler(错误体渲染)必在 request id task-local scope 之外,故采用后置回填——`and_then` 内生成/校验 id,
//! `scope` 包住后置处理:设置 `X-Request-ID` 头,对 4xx/5xx 的 JSON 体经 [`inject_request_id_into_error_body`]
//! 注入 `request_id` 再重组(axum/actix 为前置渲染,三框架终态形状一致,详见 ADR-0004);
//! 成功与非 JSON 错误响应零缓冲透传(仅补 `X-Request-ID` 头)。
//!
//! # 用法
//!
//! ```ignore
//! let routes = routes.with(warp::wrap_fn(
//!     garrison::web_warp::request_id::with_request_id,
//! ));
//! ```
//!
//! 头名 `X-Request-ID` 为固定常量([`REQUEST_ID_HEADER`]),非配置项。

use crate::context::request_id::{
    inject_request_id_into_error_body, propagate_or_generate, scope, REQUEST_ID_HEADER,
};
use http_body_util::BodyExt;
use std::sync::Arc;
use tracing::Instrument;
use warp::http::header::{HeaderName, HeaderValue, CONTENT_LENGTH, CONTENT_TYPE};
use warp::reply::{Reply as _, Response};
use warp::Filter;

/// `x-request-id` 头名(小写静态形式)。
const X_REQUEST_ID: HeaderName = HeaderName::from_static("x-request-id");

/// request id 包装 Filter:经 `warp::wrap_fn(with_request_id)` 组合到任意 `Extract = (impl Reply,)` 的路由外层。
pub fn with_request_id<T, R>(
    route: T,
) -> impl Filter<Extract = (Response,), Error = warp::Rejection> + Clone
where
    T: Filter<Extract = (R,), Error = warp::Rejection> + Clone + Send + Sync + 'static,
    R: warp::reply::Reply + Send + 'static,
{
    warp::any()
        .and(warp::header::optional::<String>(REQUEST_ID_HEADER))
        .and(route)
        .and_then(|inbound: Option<String>, reply: R| async move {
            let id = propagate_or_generate(inbound.as_deref());
            let span = tracing::info_span!("request_id", request_id = %id);
            let response = scope(id.clone(), async move {
                post_process(id, reply.into_response()).await
            })
            .instrument(span)
            .await;
            Ok::<_, warp::Rejection>(response)
        })
}

/// 后置处理:回传 `X-Request-ID` 头;错误 JSON 体在 scope 内回填 `request_id`。
async fn post_process(id: Arc<str>, mut response: Response) -> Response {
    if let Ok(value) = HeaderValue::from_str(id.as_ref()) {
        response.headers_mut().insert(X_REQUEST_ID, value);
    }
    // 完成事件携带 request_id(scope 内发出);debug 级避免与 audit_log_middleware 的每请求 info 日志重复
    tracing::debug!(
        request_id = %id,
        status = response.status().as_u16(),
        "{}", crate::i18n::translate_detail("logs-request-id-middleware-completed", &[])
    );

    let status = response.status();
    let is_error = status.is_client_error() || status.is_server_error();
    let is_json = response
        .headers()
        .get(CONTENT_TYPE)
        .and_then(|v| v.to_str().ok())
        .is_some_and(|v| v.starts_with("application/json"));
    if !(is_error && is_json) {
        return response;
    }

    let (mut parts, body) = response.into_parts();
    let bytes = match BodyExt::collect(body).await {
        Ok(collected) => collected.to_bytes(),
        Err(e) => {
            // 失败显性化:原 body 已消费不可恢复,替换为统一错误体;原状态码与响应头(含 Retry-After / X-Request-ID)保留透传
            tracing::error!(error = %e, "{}", crate::i18n::translate_detail("logs-warp-request-id-body-collect-failed", &[]));
            let fallback =
                crate::error::GarrisonError::Internal("warp-body-collect-failed::".to_string());
            let mut rebuilt =
                warp::reply::with_status(warp::reply::json(&fallback.to_json_body()), parts.status)
                    .into_response();
            parts.headers.remove(CONTENT_LENGTH);
            *rebuilt.headers_mut() = parts.headers;
            return rebuilt;
        },
    };

    // 防御护栏:超大错误体跳过回填、原样透传(阈值与 axum IntoResponse 4KB 截断一致;统一错误体远小于该值)
    if bytes.len() > MAX_INJECT_BODY_SIZE {
        return pass_through_original(parts, bytes.to_vec());
    }
    let mut json = match serde_json::from_slice::<serde_json::Value>(&bytes) {
        Ok(v) => v,
        Err(_) => {
            // 非 JSON body(防御路径):原样透传,状态码与原始响应头保留
            return pass_through_original(parts, bytes.to_vec());
        },
    };
    inject_request_id_into_error_body(&mut json);

    parts.headers.remove(CONTENT_LENGTH);
    let mut rebuilt = warp::reply::with_status(warp::reply::json(&json), status).into_response();
    for (name, value) in parts.headers.iter() {
        if name != CONTENT_TYPE {
            rebuilt.headers_mut().append(name, value.clone());
        }
    }
    rebuilt
}

/// 统一体回填的 body 大小上限(与 axum IntoResponse 的 4KB 截断阈值一致)。
const MAX_INJECT_BODY_SIZE: usize = 4096;

/// 防御路径透传:body 未改动,状态码与原始响应头整体回填(单一 Content-Type,Retry-After / X-Request-ID 原值保留)。
fn pass_through_original(parts: warp::http::response::Parts, body: Vec<u8>) -> Response {
    let mut rebuilt = warp::reply::Reply::into_response(body);
    *rebuilt.status_mut() = parts.status;
    *rebuilt.headers_mut() = parts.headers;
    rebuilt
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::error::GarrisonError;
    use serial_test::serial;
    use tracing_subscriber::layer::SubscriberExt;
    use tracing_subscriber::util::SubscriberInitExt;
    use warp::test::request;

    /// 统一错误 handler(Reply for GarrisonError 路径,与业务用法一致)。
    fn error_routes() -> impl Filter<Extract = (GarrisonError,), Error = warp::Rejection> + Clone {
        warp::path("boom").map(|| GarrisonError::NotLogin("web-not-login::".to_string()))
    }

    /// 限流错误 handler:RateLimited → 429 + Retry-After。
    fn rate_limited_routes(
    ) -> impl Filter<Extract = (GarrisonError,), Error = warp::Rejection> + Clone {
        warp::path("limited").map(|| GarrisonError::RateLimited {
            retry_after_secs: 30,
        })
    }

    /// 成功 handler:回显自身处理结果。
    fn ok_routes() -> impl Filter<Extract = (&'static str,), Error = warp::Rejection> + Clone {
        warp::path("ping").map(|| "pong")
    }

    /// 入站合法 id 原样回传(成功响应也有头)。
    #[tokio::test]
    async fn valid_inbound_id_echoed_on_success_response() {
        let routes = ok_routes().with(warp::wrap_fn(with_request_id));
        let res = request()
            .path("/ping")
            .header(REQUEST_ID_HEADER, "warp-corr-001")
            .reply(&routes)
            .await;
        assert_eq!(res.status(), 200);
        let value = res
            .headers()
            .get(X_REQUEST_ID.as_str())
            .and_then(|v| v.to_str().ok())
            .unwrap_or_default();
        assert_eq!(value, "warp-corr-001");
    }

    /// 超长入站值(> 128 字节)被丢弃并重生成 UUID;CRLF / 非 ASCII 注入防护由框架头解析与
    /// `context::request_id::propagate_or_generate` 纯函数测试覆盖。
    #[tokio::test]
    async fn invalid_inbound_id_regenerated() {
        let routes = ok_routes().with(warp::wrap_fn(with_request_id));
        for bad in ["a".repeat(129), format!("{}tail", "b".repeat(200))] {
            let res = request()
                .path("/ping")
                .header(REQUEST_ID_HEADER, bad.as_str())
                .reply(&routes)
                .await;
            let value = res
                .headers()
                .get(X_REQUEST_ID.as_str())
                .and_then(|v| v.to_str().ok())
                .unwrap_or_default()
                .to_string();
            assert_ne!(value, bad, "非法入站 id 不应被回传");
            assert!(
                uuid::Uuid::parse_str(&value).is_ok(),
                "重新生成的 id 应为合法 UUID: {value}"
            );
        }
    }

    /// 无头时生成 UUID v4。
    #[tokio::test]
    async fn missing_header_generates_uuid_v4() {
        let routes = ok_routes().with(warp::wrap_fn(with_request_id));
        let res = request().path("/ping").reply(&routes).await;
        let value = res
            .headers()
            .get(X_REQUEST_ID.as_str())
            .and_then(|v| v.to_str().ok())
            .unwrap_or_default()
            .to_string();
        let parsed = uuid::Uuid::parse_str(&value).expect("无头时应生成合法 UUID");
        assert_eq!(parsed.get_version_num(), 4);
    }

    /// 错误体后置回填:body.request_id == X-Request-ID 头(warp 后置回填机制)。
    #[tokio::test]
    async fn error_body_request_id_backfilled_matching_header() {
        let routes = error_routes().with(warp::wrap_fn(with_request_id));
        let res = request()
            .path("/boom")
            .header(REQUEST_ID_HEADER, "warp-err-corr-001")
            .reply(&routes)
            .await;
        assert_eq!(res.status(), 401);
        let header = res
            .headers()
            .get(X_REQUEST_ID.as_str())
            .and_then(|v| v.to_str().ok())
            .unwrap_or_default();
        assert_eq!(header, "warp-err-corr-001");
        let body_json: serde_json::Value = serde_json::from_slice(res.body()).unwrap();
        assert_eq!(body_json["request_id"], "warp-err-corr-001");
        assert_eq!(body_json["error_code"], "NOT_LOGIN");
        assert_eq!(body_json["error_id"], "auth.not_login");
    }

    /// 无头时错误体携带生成的 UUID request_id。
    #[tokio::test]
    async fn error_body_request_id_generated_when_missing() {
        let routes = error_routes().with(warp::wrap_fn(with_request_id));
        let res = request().path("/boom").reply(&routes).await;
        let header = res
            .headers()
            .get(X_REQUEST_ID.as_str())
            .and_then(|v| v.to_str().ok())
            .unwrap_or_default()
            .to_string();
        let body_json: serde_json::Value = serde_json::from_slice(res.body()).unwrap();
        assert_eq!(
            body_json["request_id"].as_str().unwrap(),
            header,
            "错误体 request_id 应与响应头一致"
        );
        assert!(uuid::Uuid::parse_str(&header).is_ok());
    }

    /// Retry-After 头(RateLimited → 30)在 warp 路径正确输出。
    #[tokio::test]
    async fn rate_limited_retry_after_header() {
        let routes = rate_limited_routes().with(warp::wrap_fn(with_request_id));
        let res = request().path("/limited").reply(&routes).await;
        assert_eq!(res.status(), 429);
        let value = res
            .headers()
            .get("retry-after")
            .and_then(|v| v.to_str().ok())
            .unwrap_or_default();
        assert_eq!(value, "30");
        let body_json: serde_json::Value = serde_json::from_slice(res.body()).unwrap();
        assert_eq!(body_json["error_id"], "ratelimit.rate_limited");
    }

    /// 非 JSON 错误响应不被回填(零缓冲透传,仅补头)。
    #[tokio::test]
    async fn non_json_error_response_not_backfilled() {
        let routes = warp::path("raw")
            .map(|| warp::http::StatusCode::FORBIDDEN)
            .with(warp::wrap_fn(with_request_id));
        let res = request()
            .path("/raw")
            .header(REQUEST_ID_HEADER, "warp-nonjson-001")
            .reply(&routes)
            .await;
        assert_eq!(res.status(), 403);
        let value = res
            .headers()
            .get(X_REQUEST_ID.as_str())
            .and_then(|v| v.to_str().ok())
            .unwrap_or_default();
        assert_eq!(value, "warp-nonjson-001");
        // 非 JSON:无 request_id 字段可回填,body 保持空
        assert!(res.body().is_empty());
    }

    /// 进程内 tracing 捕获层:记录 (级别, 事件字段渲染)。
    struct CollectLayer(std::sync::Arc<std::sync::Mutex<Vec<(String, String)>>>);

    impl<S> tracing_subscriber::layer::Layer<S> for CollectLayer
    where
        S: tracing::Subscriber + for<'a> tracing_subscriber::registry::LookupSpan<'a>,
    {
        fn on_event(
            &self,
            event: &tracing::Event<'_>,
            _ctx: tracing_subscriber::layer::Context<'_, S>,
        ) {
            let level = event.metadata().level().to_string();
            let mut rendered = String::new();
            event.record(
                &mut |field: &tracing::field::Field, value: &dyn std::fmt::Debug| {
                    rendered.push_str(&format!("{}={:?} ", field.name(), value));
                },
            );
            self.0
                .lock()
                .expect("日志缓冲锁应可用")
                .push((level, rendered));
        }
    }

    /// 初始化线程局部捕获订阅者并重建 callsite interest 缓存:interest 缓存是进程级全局态,
    /// 并行运行的非订阅者测试可能抢先注册事件并缓存 `Interest::never`(事件被宏剔除),故必须显式重建。
    fn init_capture(
        logs: &std::sync::Arc<std::sync::Mutex<Vec<(String, String)>>>,
    ) -> tracing::subscriber::DefaultGuard {
        let guard = tracing_subscriber::registry()
            .with(CollectLayer(logs.clone()))
            .set_default();
        tracing::callsite::rebuild_interest_cache();
        guard
    }

    /// tracing 捕获断言:完成事件为 debug 级(避免与 audit_log_middleware 的 info 日志重复)且携带 request_id 字段。
    #[tokio::test]
    #[serial]
    async fn tracing_event_carries_request_id_field() {
        let logs: std::sync::Arc<std::sync::Mutex<Vec<(String, String)>>> =
            std::sync::Arc::new(std::sync::Mutex::new(Vec::new()));
        let _guard = init_capture(&logs);

        let routes = ok_routes().with(warp::wrap_fn(with_request_id));
        let mut lines: Vec<(String, String)> = Vec::new();
        for _ in 0..3 {
            let _ = request()
                .path("/ping")
                .header(REQUEST_ID_HEADER, "warp-span-id")
                .reply(&routes)
                .await;
            lines = logs.lock().expect("日志缓冲锁应可用").clone();
            if lines
                .iter()
                .any(|(level, msg)| level == "DEBUG" && msg.contains("warp-span-id"))
            {
                break;
            }
            tracing::callsite::rebuild_interest_cache();
        }
        assert!(
            lines
                .iter()
                .any(|(level, msg)| level == "DEBUG" && msg.contains("warp-span-id")),
            "完成事件应为 debug 级且携带 request_id 字段值 warp-span-id,实际: {lines:?}"
        );
    }

    /// 自建 Reply:application/json 标签 + 任意 body(构造后置回填的防御路径)。
    struct JsonLabeledRaw(Vec<u8>);

    impl warp::reply::Reply for JsonLabeledRaw {
        fn into_response(self) -> Response {
            let mut res = warp::reply::Reply::into_response(self.0);
            res.headers_mut()
                .insert(CONTENT_TYPE, HeaderValue::from_static("application/json"));
            *res.status_mut() = warp::http::StatusCode::FORBIDDEN;
            res
        }
    }

    /// 非 JSON body(防御路径):原样透传——状态码、body 与单一 Content-Type 保持,
    /// 不得出现双 Content-Type,也不得注入 request_id。
    #[tokio::test]
    async fn non_json_body_with_json_label_passthrough_single_content_type() {
        let routes = warp::path("raw")
            .map(|| JsonLabeledRaw(b"not-json-body{".to_vec()))
            .with(warp::wrap_fn(with_request_id));
        let res = request()
            .path("/raw")
            .header(REQUEST_ID_HEADER, "warp-nonjson-002")
            .reply(&routes)
            .await;
        assert_eq!(res.status(), 403);
        assert_eq!(res.body().as_ref(), b"not-json-body{", "body 应原样透传");
        let content_types: Vec<_> = res
            .headers()
            .get_all(CONTENT_TYPE.as_str())
            .iter()
            .collect();
        assert_eq!(
            content_types.len(),
            1,
            "Content-Type 不得重复,实际: {content_types:?}"
        );
        assert!(res.headers().get(X_REQUEST_ID.as_str()).is_some());
        let body_str = String::from_utf8_lossy(res.body());
        assert!(
            !body_str.contains("request_id"),
            "透传体不得被注入 request_id 字段: {body_str}"
        );
    }

    /// 超大错误体(> 4KB,与 axum IntoResponse 截断阈值一致)跳过回填、原样透传。
    #[tokio::test]
    async fn oversized_error_body_skips_injection_and_passthrough() {
        let oversized = serde_json::json!({ "pad": "x".repeat(8 * 1024) }).to_string();
        let expected_len = oversized.len();
        let routes = warp::path("big")
            .map(move || JsonLabeledRaw(oversized.clone().into_bytes()))
            .with(warp::wrap_fn(with_request_id));
        let res = request()
            .path("/big")
            .header(REQUEST_ID_HEADER, "warp-oversize-001")
            .reply(&routes)
            .await;
        assert_eq!(res.status(), 403);
        assert_eq!(
            res.body().len(),
            expected_len,
            "超大 body 应原样透传(长度不变)"
        );
        let body_str = String::from_utf8_lossy(res.body());
        assert!(
            !body_str.contains("request_id"),
            "超大错误体不得被注入 request_id 字段"
        );
        assert!(res.headers().get(X_REQUEST_ID.as_str()).is_some());
        let content_types: Vec<_> = res
            .headers()
            .get_all(CONTENT_TYPE.as_str())
            .iter()
            .collect();
        assert_eq!(
            content_types.len(),
            1,
            "Content-Type 不得重复,实际: {content_types:?}"
        );
    }
}