Bài 39: Extension Extractor — Request-Scoped Data

Sau bài học, bạn sẽ:

• Hiểu Extension<T> extractor cho request-scoped data set qua middleware, extract trong handler downstream.
• Phân biệt Extension<T> (per-request, set runtime mỗi request) vs State<T> (persistent app-wide, set 1 lần lúc startup) — quyết định khi nào dùng cái nào.
• Implement X-Request-Id middleware trong crates/shop-api/src/middleware/request_id.rs — generate UUID v4 hoặc echo header client gửi, set Extension cho handler downstream, echo response header để client trace.
• Implement error envelope enrich middleware đọc Extension RequestId rồi inject vào response JSON — refactor placeholder request_id: null lock B16 sang giá trị thật.
• Wire 2 middleware vào router.rs qua axum::middleware::from_fn(...), hiểu ordering bottom-up lock B29.
• Nắm pattern CurrentUser injection qua middleware (preview B112 JWT verify) — tách concern auth khỏi handler.
• Foundation observability G15: trace context propagation OpenTelemetry cùng pattern Extension cho structured log correlation cross-service.

axum cung cấp Extension<T> extractor cho per-request data — dữ liệu sống đúng 1 vòng đời request, sinh ra ở middleware, tiêu thụ ở handler. Mỗi http::Request trong hyper có 1 type-map http::Extensions (HashMap key theo TypeId): middleware set qua request.extensions_mut().insert(value), handler downstream extract qua Extension(value): Extension<T>. Yêu cầu trên T: Clone + Send + Sync + 'static — Clone vì Extension extractor clone giá trị từ map sang handler arg, Send + Sync + 'static vì axum chạy multi-thread + handler có thể giữ giá trị qua await point.

// Pattern cơ bản handler dùng Extension<T>
use axum::Extension;
use axum::http::StatusCode;

#[derive(Debug, Clone)]
pub struct RequestId(pub String);

async fn handler(Extension(req_id): Extension<RequestId>) -> StatusCode {
    tracing::info!(request_id = %req_id.0, "handling request");
    StatusCode::OK
}

Điểm chú ý:

• Newtype RequestId(pub String) wrap String thay vì insert thẳng String — vì http::Extensions key theo TypeId, nếu 2 middleware cùng insert String thì middleware sau override trước. Newtype tạo type riêng biệt theo TypeId nên co-exist nhiều extension cùng inner type được.
• Extension(req_id): Extension<RequestId> destructure ngay trên signature handler — pattern lock cho mọi extractor wrapper Shop API (giống Json(payload), Path(slug), Query(pagination)).
• Nếu handler khai báo Extension<RequestId> mà middleware chưa insert trước đó → axum reject với ExtensionRejection 500 Internal Server Error (lỗi server-side config sai, không phải client lỗi).
• Extension<T> implement FromRequestParts (không consume body) — đặt ĐẦU arg list trước body extractor (Json, Form, Multipart) theo lock B31.

Hai extractor nhìn giống nhau (cùng share data vào handler) nhưng khác biệt căn bản về lifecycle và thời điểm set. State<T> lock B28 dùng cho dữ liệu persistent share toàn app — DB pool, Redis pool, AppConfig, metrics handle — set 1 lần lúc startup qua Router::with_state(state). Extension<T> dùng cho dữ liệu per-request sinh runtime mỗi request — request_id (mỗi request 1 UUID khác nhau), trace context, current_user (sau auth verify).

Aspect             | State<T>                  | Extension<T>
-------------------+---------------------------+--------------------------------
Lifecycle          | App startup → shutdown    | Per-request (sinh + drop mỗi req)
Set by             | with_state(state) startup | request.extensions_mut().insert()
Read by            | State<T> extractor        | Extension<T> extractor
Use case           | DB pool, Redis, config    | request_id, trace, current_user
Clone-cheap        | Required (Arc internal)   | Required (Arc/Clone trên T)
Failure mode       | Compile error router  ()  | Runtime 500 nếu middleware quên set
Storage            | Router's S type param     | http::Extensions type-map per req

Quyết định khi nào dùng cái nào — quy tắc đơn giản:

• Dữ liệu giống nhau cho mọi request (cấu hình, connection pool) → State<T>.
• Dữ liệu khác nhau mỗi request (request_id unique, user khác nhau sau auth) → Extension<T> set qua middleware.
• Hybrid pattern: State<AppState> chứa user_repo + jwt_secret persistent, middleware require_auth dùng State đọc config rồi set Extension<CurrentUser> per-request — pattern lock B112.

Sai lầm phổ biến: dùng State<T> cho per-request data (vd nhồi Mutex<HashMap<Uuid, RequestContext>> vào State) → contention lock + memory leak khi quên dọn entry. Pattern Shop API lock vĩnh viễn: chỉ giữ infrastructure persistent trong AppState, dùng Extension cho mọi giá trị thay đổi per-request.

Tạo file mới crates/shop-api/src/middleware/request_id.rs chứa middleware function + newtype RequestId. Pattern 4 bước MANDATORY lock vĩnh viễn cho mọi middleware tương tự sau này:

// File: crates/shop-api/src/middleware/request_id.rs
use axum::{
    extract::Request,
    http::HeaderValue,
    middleware::Next,
    response::Response,
};
use shop_common::headers::X_REQUEST_ID;
use uuid::Uuid;

/// Request-scoped identifier — newtype wrap UUID v4 hoặc giá trị client gửi.
/// Set bởi `request_id_middleware`, extract trong handler downstream qua
/// `Extension<RequestId>` (B39).
#[derive(Debug, Clone)]
pub struct RequestId(pub String);

/// Middleware đảm bảo mọi request có X-Request-Id ổn định cross-service:
/// - Echo header client gửi nếu hợp lệ (trace từ frontend qua API gateway).
/// - Generate UUID v4 mới nếu missing (server-initiated request).
/// - Set Extension cho handler downstream + error_enrich middleware (B39).
/// - Echo response header X-Request-Id để client correlation log.
pub async fn request_id_middleware(mut request: Request, next: Next) -> Response {
    // Bước 1: đọc X-Request-Id từ header hoặc generate mới
    let request_id = request
        .headers()
        .get(X_REQUEST_ID)
        .and_then(|v| v.to_str().ok())
        .filter(|s| !s.is_empty())
        .map(String::from)
        .unwrap_or_else(|| Uuid::new_v4().to_string());

    // Bước 2: set Extension cho handler downstream extract qua Extension<RequestId>
    request
        .extensions_mut()
        .insert(RequestId(request_id.clone()));

    // Bước 3: chạy middleware/handler downstream
    let mut response = next.run(request).await;

    // Bước 4: echo X-Request-Id lên response để client correlation
    if let Ok(header_value) = HeaderValue::from_str(&request_id) {
        response.headers_mut().insert(X_REQUEST_ID, header_value);
    }

    response
}

Phân tích từng bước:

• Bước 1: request.headers().get(X_REQUEST_ID) dùng constant shop_common::headers::X_REQUEST_ID lock B4/B10 (header name lowercase chuẩn hyper). Chain and_then(|v| v.to_str().ok()) convert HeaderValue sang &str (fail nếu chứa non-ASCII), filter loại empty string (header gửi rỗng coi như không hợp lệ), map(String::from) own giá trị. Fallback Uuid::new_v4().to_string() generate UUID v4 random 122 bit entropy đủ unique cross-instance.
• Bước 2: request.extensions_mut().insert(RequestId(...)) — clone string trước vì bước 4 cần dùng lại set response header. RequestId wrap String thay vì insert thẳng String tránh xung đột TypeId với extension khác cùng inner type.
• Bước 3: next.run(request).await chạy phần còn lại của chain (middleware INNER hơn + handler) — trả Response ownership.
• Bước 4: HeaderValue::from_str có thể fail nếu chứa control char — defensive if let Ok(...) bỏ qua silent thay vì panic. Echo header cho client log correlation với backend log cùng request_id.

2 kịch bản client lock vĩnh viễn: nếu client gửi X-Request-Id: abc-123 server tôn trọng (trace từ frontend qua backend), nếu không gửi server tự generate (internal call, monitoring probe).

Folder crates/shop-api/src/middleware/ đã pre-allocate placeholder từ B17, file mod.rs hiện chỉ có comment. Refactor thành module aggregator + re-export top-level cho handler import 1 dòng:

// File: crates/shop-api/src/middleware/mod.rs
pub mod error_enrich;
pub mod request_id;

pub use error_enrich::enrich_error_response;
pub use request_id::{request_id_middleware, RequestId};

Add workspace dep cho UUID v4 generation. Edit shop/Cargo.toml workspace root:

# File: shop/Cargo.toml — section [workspace.dependencies]
# ... các dep cũ ...
uuid = { version = "1", features = ["v4"] }

Member crate shop-api consume qua .workspace = true. Edit crates/shop-api/Cargo.toml:

# File: crates/shop-api/Cargo.toml — section [dependencies]
# ... các dep cũ ...
uuid = { workspace = true }

Feature v4 đủ cho random UUID v4 (4-bit version + 122-bit random). Không cần feature v7 (time-ordered, dùng cho DB primary key G7 B68) hay serde (chỉ cần khi serialize UUID trong DTO — request_id ở đây luôn là String). uuid = "1" version stable từ 2022, no breaking change cho v4.

Wire 2 middleware vào build_router() qua axum::middleware::from_fn(fn) — adapter wrap async function thành Layer compatibility với Router::layer(). Edit crates/shop-api/src/router.rs:

// File: crates/shop-api/src/router.rs
use axum::{
    middleware as axum_middleware,
    routing::get,
    Router,
};
use http::StatusCode;

use crate::{handlers, middleware, routes, state::AppState};

pub fn build_router(state: AppState) -> Router {
    let api_v1 = Router::new().merge(routes::products::routes());

    Router::new()
        .route("/", get(root))
        .merge(routes::health::routes())
        .merge(routes::version::routes())
        .merge(routes::demo_error::routes())
        .merge(routes::demo_async::routes())
        .nest("/api/v1", api_v1)
        .fallback(handlers::fallback::not_found)
        .method_not_allowed_fallback(handlers::fallback::method_not_allowed)
        // Layer apply bottom-up — outer layer ở DƯỚI chạy ĐẦU request (lock B29).
        // error_enrich INNER hơn: cần Extension đã set bởi request_id.
        .layer(axum_middleware::from_fn(middleware::enrich_error_response))
        // request_id OUTER nhất: set Extension trước, echo header response cuối.
        .layer(axum_middleware::from_fn(middleware::request_id_middleware))
        .with_state(state)
}

async fn root() -> (StatusCode, &'static str) {
    (StatusCode::OK, "shop-api v0.1.0")
}

Điểm chú ý ordering:

• Layer apply bottom-up (lock B29): layer ở dòng DƯỚI gần with_state là outer nhất — chạy đầu khi request đến, chạy cuối khi response trả về. request_id_middleware đặt CUỐI trong code → outer nhất → set Extension trước → echo response header cuối cùng.
• enrich_error_response đặt TRƯỚC request_id_middleware trong code → inner hơn → chạy SAU khi request_id_middleware đã set Extension → đọc được RequestId từ Extension.
• Nếu đảo ngược ordering (request_id INNER, enrich OUTER) → enrich chạy trước khi Extension được set → request.extensions().get::<RequestId>() trả None → request_id field trong envelope vẫn null. Pitfall ordering kinh điển khi compose middleware Shop API.
• middleware::from_fn(fn) giải đắc lực function async đơn giản — không cần impl tower::Layer + tower::Service verbose. Đủ cho 90% middleware Shop API; chỉ cần impl Layer raw khi cần state riêng cho middleware (vd rate-limit counter G17).

Vấn đề kỹ thuật: impl IntoResponse for AppError lock B16 build envelope { error, code, request_id: null } với placeholder null — vì handler trả AppError, axum gọi error.into_response() với chỉ self: AppError KHÔNG có access tới Request::extensions để đọc RequestId. Đẩy Extension<RequestId> vào mọi handler arg list để tự embed request_id vào error là anti-pattern: handler signature bloat 1 arg dù 90% case không cần, lặp boilerplate 60+ endpoint, vi phạm separation of concerns.

Solution lock B16 approach (a): middleware wrap response đọc Extension, parse JSON body, inject request_id field, rebuild response. Tạo file mới crates/shop-api/src/middleware/error_enrich.rs:

// File: crates/shop-api/src/middleware/error_enrich.rs
use axum::{
    body::{to_bytes, Body},
    extract::Request,
    http::header,
    middleware::Next,
    response::Response,
};

use crate::middleware::request_id::RequestId;

/// Max body size cho enrich — 1MB đủ cho mọi envelope error JSON.
/// Body lớn hơn (download stream B38) sẽ skip enrich (status không phải 4xx/5xx).
const MAX_ENRICH_BODY: usize = 1024 * 1024;

/// Middleware đọc Extension<RequestId> (set bởi request_id_middleware OUTER),
/// chạy handler, nếu response là error (4xx/5xx) + Content-Type application/json
/// thì parse body, inject field "request_id" thay placeholder null của
/// AppError::into_response (lock B16 approach (a) middleware enrich-error-body).
pub async fn enrich_error_response(request: Request, next: Next) -> Response {
    // Đọc Extension trước khi consume request bởi next.run
    let request_id = request
        .extensions()
        .get::<RequestId>()
        .map(|r| r.0.clone());

    let response = next.run(request).await;

    let status = response.status();
    let should_enrich = status.is_client_error() || status.is_server_error();
    if !should_enrich {
        return response;
    }

    let is_json = response
        .headers()
        .get(header::CONTENT_TYPE)
        .and_then(|v| v.to_str().ok())
        .map(|ct| ct.starts_with("application/json"))
        .unwrap_or(false);
    if !is_json {
        return response;
    }

    let Some(request_id) = request_id else {
        return response;
    };

    enrich_json_body(response, &request_id).await
}

async fn enrich_json_body(response: Response, request_id: &str) -> Response {
    let (parts, body) = response.into_parts();
    let bytes = match to_bytes(body, MAX_ENRICH_BODY).await {
        Ok(b) => b,
        Err(_) => return Response::from_parts(parts, Body::empty()),
    };

    let Ok(mut json) = serde_json::from_slice::<serde_json::Value>(&bytes) else {
        return Response::from_parts(parts, Body::from(bytes));
    };

    if let Some(obj) = json.as_object_mut() {
        obj.insert(
            "request_id".to_string(),
            serde_json::Value::String(request_id.to_string()),
        );
    }

    let new_body = match serde_json::to_vec(&json) {
        Ok(v) => v,
        Err(_) => return Response::from_parts(parts, Body::from(bytes)),
    };

    Response::from_parts(parts, Body::from(new_body))
}

Phân tích pattern:

• Đọc Extension TRƯỚC next.run — vì next.run(request) consume ownership Request sau đó không truy cập extensions() nữa. Clone RequestId.0 String sang local var.
• Filter 3 điều kiện để chỉ enrich error JSON: (i) status 4xx/5xx, (ii) Content-Type bắt đầu với application/json (tránh enrich text/plain webhook hoặc HTML), (iii) Extension RequestId tồn tại (nếu middleware ordering sai thì silent fallback không panic).
• axum::body::to_bytes(body, MAX_ENRICH_BODY) consume body stream thành bytes::Bytes với cap 1MB — đủ cho envelope error JSON (typical ~100 bytes), tránh OOM nếu accidentally body lớn. Body size lớn hơn (stream download B38) status không phải 4xx/5xx nên không vào branch enrich.
• Parse JSON qua serde_json::Value generic — không cần biết schema cụ thể (AppError envelope có thể thêm field tương lai như details: [...] validator B41 không phải sửa middleware). let Some(obj) = json.as_object_mut() chỉ inject khi root là object, array hay primitive bỏ qua silent.
• Response::from_parts(parts, Body::from(new_body)) rebuild response giữ nguyên status + headers, chỉ thay body. Header Content-Length cũ có thể sai sau khi inject field — hyper sẽ tự re-compute khi serialize response (axum + hyper handle auto).
• Overhead: chỉ apply cho error path 4xx/5xx (typical < 1% traffic), happy path 200 OK skip toàn bộ enrich logic. Parse + inject JSON typical 10-50μs, negligible so với DB query 1-10ms.

Chạy server qua cargo run -p shop-api, expect log shop-api listening addr=0.0.0.0:3000. Verify 3 kịch bản lock vĩnh viễn:

Case 1 — normal request: response phải có header x-request-id với UUID v4 generate server-side.

curl -i http://localhost:3000/health
# HTTP/1.1 200 OK
# content-type: application/json
# x-request-id: 550e8400-e29b-41d4-a716-446655440000
# content-length: 15
#
# {"status":"ok"}

Case 2 — error request: envelope phải có field request_id giá trị thật không còn null placeholder lock B16.

curl -i http://localhost:3000/api/v1/unknown
# HTTP/1.1 404 Not Found
# content-type: application/json
# x-request-id: 7b9c1234-5678-90ab-cdef-1234567890ab
#
# {"error":"not found: route not found","code":"NOT_FOUND","request_id":"7b9c1234-5678-90ab-cdef-1234567890ab"}

Case 3 — client gửi X-Request-Id custom: server tôn trọng giá trị client (trace cross-service từ frontend).

curl -i http://localhost:3000/health \
    -H 'X-Request-Id: my-custom-trace-id'
# HTTP/1.1 200 OK
# x-request-id: my-custom-trace-id
#
# {"status":"ok"}

# Verify cùng custom ID flow qua error envelope:
curl -i http://localhost:3000/error/not-found \
    -H 'X-Request-Id: client-trace-abc'
# HTTP/1.1 404 Not Found
# x-request-id: client-trace-abc
#
# {"error":"not found: demo not found","code":"NOT_FOUND","request_id":"client-trace-abc"}

Suggested commit khi verify pass: B39: implement request_id middleware + error envelope enrich + refactor AppError request_id từ placeholder sang Extension.

Pattern Extension áp dụng cho authentication ở B112: middleware verify JWT một lần ở edge, set CurrentUser vào Extension, handler downstream extract qua Extension<CurrentUser> KHÔNG re-verify token + KHÔNG fetch user lại trong mọi handler. Preview code (chi tiết B112 implement đầy đủ với jsonwebtoken crate):

// File: crates/shop-api/src/middleware/auth.rs (B112 implement)
use axum::{
    extract::{Request, State},
    middleware::Next,
    response::Response,
};
use shop_common::error::{AppError, AppResult};

use crate::state::AppState;

#[derive(Debug, Clone)]
pub struct CurrentUser {
    pub id: i64,
    pub role: String,
}

pub async fn require_auth(
    State(state): State<AppState>,
    mut request: Request,
    next: Next,
) -> AppResult<Response> {
    // 1. Extract Bearer token từ Authorization header (typed header B33)
    let token = extract_bearer_token(request.headers())?;

    // 2. Verify JWT signature + claims qua jwt_secret từ AppState
    let claims = verify_jwt(&token, &state.config.jwt_secret)?;

    // 3. Fetch user từ DB (hoặc cache) — đảm bảo user chưa bị disable
    let user = state.user_repo.find(claims.sub).await?;

    // 4. Set CurrentUser vào Extension cho handler downstream
    request.extensions_mut().insert(CurrentUser {
        id: user.id,
        role: user.role,
    });

    Ok(next.run(request).await)
}

// Handler tận dụng Extension không cần biết logic auth:
async fn me(
    axum::Extension(user): axum::Extension<CurrentUser>,
) -> AppResult<axum::Json<serde_json::Value>> {
    Ok(axum::Json(serde_json::json!({
        "id": user.id,
        "role": user.role,
    })))
}

Pattern này lock vĩnh viễn cho Shop API:

• Tách concern clean: middleware lo authentication (parse token, verify signature, fetch user, check disabled), handler lo business logic (CRUD, validate input, query DB). Handler signature chỉ thêm 1 arg Extension<CurrentUser> khi cần biết user.
• Apply selective qua route_layer (lock B29): endpoint public không cần auth (vd GET /api/v1/products) không wire middleware, endpoint protected (vd GET /api/v1/me) wire qua .route_layer(middleware::from_fn_with_state(state.clone(), require_auth)) chỉ cho subset route.
• Mở rộng cho RBAC B135: RequireRole<"admin"> extractor đọc Extension<CurrentUser> đã set bởi require_auth outer, check user.role == "admin", reject 403 nếu không match. Chain middleware: require_auth → require_role::<"admin"> → handler.
• Mở rộng cho A/B test variant: middleware đọc feature flag service set Extension<Variant("control" | "treatment")>, handler render UI khác nhau theo variant — same pattern.

• Extension<T> request-scoped data, set qua middleware request.extensions_mut().insert(value), extract qua Extension(value): Extension<T> với T: Clone + Send + Sync + 'static.
• State<T> vs Extension<T>: State persistent app-wide (set 1 lần startup qua with_state, dùng cho pool/config/metrics), Extension per-request (set runtime mỗi request qua middleware, dùng cho request_id/trace/current_user).
• Implement X-Request-Id middleware 4 bước MANDATORY: đọc header client hoặc generate UUID v4 → wrap newtype RequestId(String) insert Extension → next.run(request).await → echo response header X-Request-Id.
• Server tôn trọng client X-Request-Id nếu hợp lệ (trace cross-service từ frontend), generate UUID v4 mới nếu missing (server-initiated request).
• Error envelope enrich pattern: middleware đọc Extension<RequestId>, sau khi next.run nếu response 4xx/5xx + JSON → consume body qua to_bytes → parse serde_json::Value → inject field request_id thay placeholder null lock B16 → rebuild Response qua from_parts.
• Vì sao KHÔNG impl trực tiếp trong AppError::into_response(): handler trả AppError chỉ có self không có Request → không đọc được Extension. Solution middleware wrap response approach (a) lock B16 tránh bloat handler arg list.
• Middleware ordering MANDATORY: request_id OUTER (đăng ký SAU trong code, gần with_state), error_enrich INNER (đăng ký TRƯỚC) — vì layer apply bottom-up lock B29, outer chạy đầu set Extension trước, inner đọc Extension sau.
• CurrentUser pattern B112: middleware require_auth extract Bearer → verify JWT → fetch user → set Extension<CurrentUser>; handler extract qua Extension(user) tách concern auth khỏi business logic.
• Shop API có 2 middleware mới đầu tiên: request_id_middleware, enrich_error_response — file path lock vĩnh viễn crates/shop-api/src/middleware/{request_id,error_enrich}.rs.
• Constant shop_common::headers::X_REQUEST_ID đã lock B4/B10 — reuse cross-middleware, không hard-code string literal.
• Workspace dep thêm uuid = { version = "1", features = ["v4"] } — generate UUID v4 random 122-bit entropy đủ unique cross-instance không cần coordinate.
• Foundation observability G15: trace context propagation OpenTelemetry tương lai cùng pattern Extension; request_id attach vào tracing span cho structured log correlation cross-service (frontend log + API log + downstream microservice log cùng correlation ID).

Tự trả lời, đáp án ở cuối:

1. Phân biệt State<T> và Extension<T>. Lifecycle mỗi loại bằng gì? Use case cụ thể Shop API mỗi loại?
2. X-Request-Id middleware làm 4 việc gì? Liệt kê step theo thứ tự và giải thích vì sao mỗi step cần thiết.
3. Server tôn trọng X-Request-Id từ client hay generate UUID v4 mới? Tại sao tách 2 case? Cho ví dụ thực tế mỗi case.
4. Pattern enrich error envelope: tại sao KHÔNG impl trực tiếp trong AppError::into_response()? Solution mechanism dùng cái gì thay thế? Trade-off có gì?
5. CurrentUser extractor B112 set ở đâu trong request lifecycle? Handler extract qua trait nào? Lợi ích so với pattern handler tự verify JWT mỗi endpoint?

Bài 40: Response Builder — Custom IntoResponse — bài CUỐI Group 4 Extractors Và Response Sâu: đi sâu impl IntoResponse cho tuple (StatusCode, HeaderMap, Json<T>) 3-element pattern lock B14 cho 201 Created + Location header, builder pattern wrap response qua Response::builder() hyper, optional ApiResponse<T> wrapper envelope đã preview B14 cho data endpoint consistent { data, meta, links } JSON:API style hoặc { items, total, page } ListResponse style lock B23, decision matrix per endpoint pattern Shop API response envelope đầy đủ kết thúc Group 4 sẵn sàng vào Group 5 JSON Body Streaming chuyển sang validator crate B41 + body size limit B47 + compression B48.