Bài 76: Middleware Overview — Tower Layer Architecture

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

• Hiểu tower::Service trait và tower::Layer trait — foundation cross-framework Rust.
• Phân biệt axum::middleware::from_fn vs custom Layer — khi nào dùng nào.
• Hiểu middleware ordering bottom-up trong axum và pitfall thường gặp.
• Áp dụng pattern 3 loại scope middleware: per-request global, per-route, per-state.
• Hiểu Shop API middleware stack hiện tại 4 layer đã wire trong router.rs.
• Nắm roadmap Group 8 (B76-B85) — 10 bài middleware production-grade phía trước.

axum xây dựng trên 2 trait nền tảng của crate tower: Service mô tả "đơn vị xử lý" 1 request thành 1 response, Layer mô tả "factory" wrap 1 service thành 1 service mới (middleware). Hiểu 2 trait này là điều kiện tiên quyết để đọc code axum sâu cũng như reuse middleware từ ecosystem (tower-http, tower-governor, axum-extra).

tower::Service<Request> là trait core:

// Trait core từ crate tower
pub trait Service<Request> {
    type Response;
    type Error;
    type Future: Future<Output = Result<Self::Response, Self::Error>>;

    // poll_ready: hỏi service đã sẵn sàng nhận request chưa
    // (backpressure, capacity limit, circuit breaker)
    fn poll_ready(
        &mut self,
        cx: &mut Context<'_>,
    ) -> Poll<Result<(), Self::Error>>;

    // call: xử lý request, trả Future tạo Response
    fn call(&mut self, req: Request) -> Self::Future;
}

Mỗi handler axum thực chất là 1 Service ngầm: function async fn handler(...) -> impl IntoResponse được axum bọc thành struct impl Service<Request> tự động. Middleware là 1 service khác wrap quanh service handler để thêm hành vi (log, validate, transform).

tower::Layer<S> là "constructor" tạo wrapper service từ inner service:

// Layer trait: factory tạo wrapper service
pub trait Layer<S> {
    type Service;
    fn layer(&self, service: S) -> Self::Service;
}

Composition: layer.layer(handler) trả 1 service mới wrap handler bên trong. Wrap nhiều lần tạo chain: layer_a.layer(layer_b.layer(layer_c.layer(handler))) → request đi qua a → b → c → handler → c → b → a → response. Đây là kiến trúc "hành tây" (onion model) chuẩn middleware.

Điểm mạnh của tower là cross-framework Rust: cùng 1 layer (vd TraceLayer, TimeoutLayer, RateLimitLayer) chạy được trên axum (HTTP), tonic (gRPC), hyper trực tiếp. Pattern viết middleware 1 lần dùng nhiều stack là lợi thế lớn so với hệ sinh thái Express/Koa Node.js hoặc Rails Rack.

Mỗi request đi qua middleware stack theo workflow đối xứng — bước xuống (pre-process) rồi bước lên (post-process):

Client request →
  Layer 1 (outermost) — pre-process
    Layer 2 — pre-process
      Layer 3 (innermost) — pre-process
        Handler — business logic
      Layer 3 — post-process
    Layer 2 — post-process
  Layer 1 — post-process
→ Client response

Pre-process diễn ra trước khi gọi next.run(req): đọc header để extract context (auth token, request id), modify request (inject extension, decode body), validate sớm và reject (rate limit, body size). Post-process diễn ra sau khi handler chạy xong và trả response: modify response (set header, compress body, wrap envelope), log + metric (status code, latency), enrich error theo format thống nhất.

Ordering CRITICAL: layer outer bao quanh layer inner. Vd compression đặt outermost nghĩa là compression chỉ thấy response cuối cùng sau khi tất cả layer khác đã hoàn tất modify → compress đúng nội dung cuối. Đặt sai thứ tự dẫn đến bug subtle: compression chạy trước khi enrich_error wrap envelope → response client nhận thiếu field request_id.

Pattern lock Shop API tiếp tục từ B50:

Shop API request lifecycle (target Group 8 hoàn thành):

  Layer 1: compression           ← outermost (wrap response cuối)
  Layer 2: decompression         ← decompress request body
  Layer 3: request_id            ← inject Extension<RequestId>
  Layer 4: enrich_error          ← đọc RequestId từ Extension
  Layer 5: rate_limit (B78)      ← reject trước khi đến handler
  Layer 6: cors (B77)            ← header check
  Handler (innermost)            ← business logic

Mỗi layer có trách nhiệm đơn lẻ rõ ràng (Single Responsibility Principle) và độc lập, có thể thay thế hoặc bỏ ra mà không ảnh hưởng layer còn lại.

axum::middleware::from_fn là cách đơn giản nhất viết middleware — convert 1 async function thành Layer + Service đầy đủ qua macro magic. Đây là pattern chiếm 90% case Shop API (request_id B39, enrich_error B39, Idempotency B66 đều dùng from_fn).

// Pattern from_fn: async function trả Response
use axum::{
    extract::Request,
    middleware::{self, Next},
    response::Response,
    routing::get,
    Router,
};

async fn timing_middleware(req: Request, next: Next) -> Response {
    // Pre-process
    let start = std::time::Instant::now();
    let path = req.uri().path().to_string();

    // Gọi handler (hoặc layer inner kế tiếp)
    let response = next.run(req).await;

    // Post-process
    tracing::info!(
        path = %path,
        elapsed_ms = start.elapsed().as_millis(),
        status = response.status().as_u16(),
        "request handled"
    );
    response
}

// Wire vào router
let app: Router = Router::new()
    .route("/health", get(|| async { "ok" }))
    .layer(middleware::from_fn(timing_middleware));

Pros:

• Quick + readable — 1 async function thay vì 2 struct + 3 impl block.
• Stateless — không cần định nghĩa struct giữ field, chỉ logic thuần.
• Common pattern Shop API — 90% middleware nhỏ vừa fit đủ.

Cons:

• Khó share state — phải đổi sang from_fn_with_state để pass AppState.
• Generic constraint phức tạp khi nested middleware bọc nhau nhiều tầng.

Biến thể quan trọng:

// Variant 1: from_fn_with_state — pass AppState vào middleware
use axum::extract::State;

async fn auth_middleware(
    State(state): State<AppState>,
    req: Request,
    next: Next,
) -> Result<Response, StatusCode> {
    let token = req
        .headers()
        .get("authorization")
        .and_then(|v| v.to_str().ok())
        .ok_or(StatusCode::UNAUTHORIZED)?;
    let _claims = verify_jwt(token, &state.jwt_secret)?;
    Ok(next.run(req).await)
}

let app = Router::new()
    .route("/me", get(get_me_handler))
    .layer(middleware::from_fn_with_state(
        state.clone(),
        auth_middleware,
    ))
    .with_state(state);

// Variant 2: from_extractor — chỉ extract, KHÔNG process response
let app = Router::new()
    .route("/admin", get(admin_handler))
    .layer(middleware::from_extractor::<RequireAdmin>());

Lock decision Shop API: dùng from_fn cho 90% case middleware đơn giản; nâng cấp lên from_fn_with_state khi cần access AppState (DB pool, Redis, config).

Khi middleware cần reusable cross-project (publish crate), stateful phức tạp hơn (config field, internal cache), hoặc tương thích đầy đủ với hệ sinh thái tower (hyper, tonic), pattern custom Layer là lựa chọn chuẩn. Phải define struct riêng + impl Layer + impl Service.

// Skeleton custom Layer + Service
use std::{
    future::Future,
    pin::Pin,
    task::{Context, Poll},
};
use tower::{Layer, Service};
use axum::{
    extract::Request,
    response::Response,
};

// 1. Layer struct — config field nếu có
#[derive(Clone)]
pub struct LoggingLayer {
    pub component: &'static str,
}

// 2. Impl Layer — tạo wrapper service khi axum wire
impl<S> Layer<S> for LoggingLayer {
    type Service = LoggingMiddleware<S>;

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

// 3. Wrapper service struct
#[derive(Clone)]
pub struct LoggingMiddleware<S> {
    inner: S,
    component: &'static str,
}

// 4. Impl Service cho wrapper
impl<S> Service<Request> for LoggingMiddleware<S>
where
    S: Service<Request, Response = Response> + Clone + Send + 'static,
    S::Future: 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) -> Self::Future {
        // Clone inner trước khi async block — pattern lock cho tower service
        let mut inner = self.inner.clone();
        let component = self.component;
        let start = std::time::Instant::now();
        let path = req.uri().path().to_string();

        Box::pin(async move {
            let response = inner.call(req).await?;
            tracing::info!(
                component,
                path = %path,
                elapsed_ms = start.elapsed().as_millis(),
                "request completed"
            );
            Ok(response)
        })
    }
}

Pros:

• Reusable cross-project — publish thành crate (tower-http, tower-governor là ví dụ).
• Stateful dễ — struct field giữ config + internal state (cache, counter, channel).
• Generic constraint kiểm soát tốt hơn from_fn trong case phức tạp.
• Tower ecosystem compatible — chạy được trên hyper, tonic không sửa code.

Cons:

• Boilerplate nhiều — 4 phần (Layer struct, impl Layer, Service struct, impl Service).
• Bound generic phức tạp — phải nắm trait Send + Sync + 'static + Future bound.

Lock decision Shop API: custom Layer chỉ áp dụng khi cần reusable hoặc stateful phức tạp; 90% còn lại vẫn ưu tiên from_fn cho tốc độ phát triển. Hầu hết middleware Shop API đến B85 sẽ wrap built-in từ tower-http (đã sẵn pattern custom Layer chuẩn) thay vì viết tay.

Quy tắc quan trọng nhất: trong axum, thứ tự gọi .layer() đảo ngược thứ tự execution. Layer thêm SAU cùng wrap layer thêm TRƯỚC.

// Đọc code dưới này:
Router::new()
    .route("/", handler)
    .layer(layer_inner)    // chạy thứ 3 (innermost, gần handler)
    .layer(layer_middle)   // chạy thứ 2
    .layer(layer_outer);   // chạy thứ 1 (outermost, gần network)

// Execution order:
//   request → layer_outer (pre) → layer_middle (pre) → layer_inner (pre)
//           → handler
//           → layer_inner (post) → layer_middle (post) → layer_outer (post)
//           → response

Pitfall thường gặp: developer đến từ Express.js (Node) hoặc Koa nghĩ middleware chạy theo thứ tự khai báo top-down (layer 1 đầu file chạy trước layer 2 sau file). Trong axum thì ngược lại — đọc code từ dưới lên. Hệ quả: developer wire auth trước cors nghĩ rằng auth chạy trước, thực tế cors chạy trước → preflight OPTIONS request bị reject vì chưa qua cors handler.

Shop API stack hiện tại trong crates/shop-api/src/router.rs (sau B50):

// File: crates/shop-api/src/router.rs (snippet sau B50)
use axum::{middleware, Router};
use tower_http::{
    compression::{CompressionLayer, CompressionLevel},
    decompression::DecompressionLayer,
};

use crate::{
    middleware::{enrich_error_response, request_id_middleware},
    state::AppState,
};

pub fn build_router(state: AppState) -> Router {
    Router::new()
        // ... routes merge từ products, orders, cart, users, brands, categories
        .merge(crate::routes::products::routes())
        .merge(crate::routes::orders::routes())
        .merge(crate::routes::cart::routes())
        // ... 26+ endpoint khác
        //
        // Middleware stack — đọc TỪ DƯỚI LÊN để hiểu execution order:
        .layer(middleware::from_fn(enrich_error_response))  // INNER 4 — wrap error envelope
        .layer(middleware::from_fn(request_id_middleware))  // INNER 3 — inject Extension<RequestId>
        .layer(DecompressionLayer::new().gzip(true).br(true)) // INNER 2 — decompress body
        .layer(                                              // OUTERMOST 1 — compress response
            CompressionLayer::new()
                .gzip(true)
                .br(true)
                .quality(CompressionLevel::Default),
        )
        .with_state(state)
}

Pattern lock vĩnh viễn: comment thứ tự execution INNER/OUTERMOST trên mỗi .layer() để team đọc code không phải tự suy luận. Comment dạng "INNER 3", "INNER 4", "OUTERMOST 1" rõ ràng hơn comment "auth layer" thuần (không nói rõ vị trí trong stack).

axum cho phép áp middleware ở 3 scope khác nhau tùy use case:

Decision matrix — chọn scope middleware

  Scope         | Áp dụng cho       | API axum                       | Vd Shop API
  --------------+-------------------+--------------------------------+--------------------------
  Per-request   | Mọi route         | Router::new()...layer(L)       | request_id, compression,
   (global)     |                   |                                | trace, cors
  --------------+-------------------+--------------------------------+--------------------------
  Per-route     | 1-vài route       | route().layer(L) hoặc          | idempotency (B66),
                |                   | route_layer(L) cho path con    | body_limit /import (B47)
  --------------+-------------------+--------------------------------+--------------------------
  Per-state     | Mọi route cần     | from_fn_with_state(state, fn)  | rate_limit (B78),
                | access AppState   |                                | auth (B112)

Per-request (global): áp dụng mọi request đi qua router. Wire ở router root sau khi merge tất cả route con.

// Pattern global — wire ở router root
Router::new()
    .merge(routes::products::routes())
    .merge(routes::orders::routes())
    .layer(middleware::from_fn(request_id_middleware));
    // Mọi route products + orders đều có request_id

Per-route: áp dụng 1 vài route cụ thể (không phải toàn bộ stack). Dùng cho middleware nặng/không phù hợp mọi endpoint: Idempotency-Key chỉ POST /orders, body limit 10MB chỉ /import NDJSON.

// Pattern per-route — wire ở route cụ thể (B66 Idempotency)
use axum::extract::DefaultBodyLimit;

let import_route = post(import_products_ndjson)
    .layer(DefaultBodyLimit::max(10 * 1024 * 1024)); // 10MB cho NDJSON import

let orders_routes = Router::new()
    .route(
        "/orders",
        post(create_order).layer(middleware::from_fn_with_state(
            state.clone(),
            idempotency_middleware, // B66 chỉ POST /orders
        )),
    )
    .route("/products/import.ndjson", import_route);

Per-state: middleware cần access AppState (DB pool cho rate limit query Redis, JWT secret cho auth). Dùng from_fn_with_state truyền state qua signature.

// Pattern per-state — rate_limit query Redis qua AppState (B78 preview)
async fn rate_limit_middleware(
    State(state): State<AppState>,
    req: Request,
    next: Next,
) -> Result<Response, StatusCode> {
    let ip = req.headers().get("x-forwarded-for")
        .and_then(|v| v.to_str().ok())
        .unwrap_or("unknown");
    let key = format!("rate:{ip}");
    let count: i64 = state.redis.incr(&key, 1).await.unwrap_or(0);
    if count == 1 { state.redis.expire(&key, 60).await.ok(); }
    if count > 100 { return Err(StatusCode::TOO_MANY_REQUESTS); }
    Ok(next.run(req).await)
}

Lock pattern Shop API:

• Global: tracing, request_id, compression — mọi request đều cần.
• Per-route: Idempotency (B66 POST mutation), body limit (B47 /import).
• Per-state: rate limit (B78 Redis pool), auth (B112 JWT secret).

Sau Group 4 + Group 5 + Group 7, Shop API đã có 4 layer global + 1 layer per-route:

• request_id (B39) — inject Extension<RequestId> mọi request, log + trả header X-Request-Id.
• enrich_error_response (B39) — đọc RequestId từ Extension, inject vào envelope error JSON.
• CompressionLayer (B50) — gzip + brotli response > 512 byte (skip image/zip/gzip content type).
• DecompressionLayer (B50) — gzip + brotli decompress request body.
• Idempotency middleware (B66, per-route POST /orders) — cache replay theo header Idempotency-Key.

Group 8 (B76-B85) sẽ thêm 10 layer mới phủ hết các nhu cầu middleware production-grade:

• B77 cors_layer — tower-http CorsLayer (allow_origin, allow_methods, allow_headers, max_age).
• B77 security_headers_layer — X-Frame-Options, X-Content-Type-Options, Content-Security-Policy, Referrer-Policy.
• B78 rate_limit_layer — per-IP token bucket với crate governor (in-memory) hoặc Redis distributed.
• B79 body_limit_per_route — refactor B47 thành pattern reusable (mỗi route khai báo limit riêng).
• B80 trace_layer — tower-http TraceLayer + structured log span (method, uri, status, latency).
• B81 metrics_layer — Prometheus middleware mở rộng /metrics endpoint từ B57 (histogram latency per-endpoint, counter status code).
• B82 timeout_layer — per-route request timeout (vd checkout 30s, NDJSON export 300s).
• B83 request_validation — input sanitize (strip HTML, normalize unicode) trước khi handler nhận.
• B84 fallback handler middleware — 404 customization (envelope chuẩn, log unknown path).
• B85 middleware testing — integration test middleware stack qua tower::ServiceExt::oneshot (pattern B75 mở rộng).

Lock stack thứ tự sau Group 8 hoàn thành:

Final stack — 11 layer production-grade (sau Group 8 B85):

  1. compression                  ← outermost (compress response cuối)
  2. decompression                ← decompress request body
  3. trace_layer (B80)            ← log span đầu vào (catch nhiều thông tin nhất)
  4. metrics_layer (B81)          ← đếm + đo latency tất cả request
  5. rate_limit (B78)             ← reject sớm trước khi tốn CPU layer khác
  6. cors (B77)                   ← preflight OPTIONS handle
  7. security_headers (B77)       ← inject header phòng thủ vào response
  8. request_id (B39)             ← inject Extension trace request
  9. enrich_error (B39)           ← wrap error envelope với request_id
  10. timeout per-route (B82)     ← timeout business-logic level
  11. idempotency per-route (B66) ← cache replay POST mutation
  Handler (innermost)             ← business logic + DB

File path lock vĩnh viễn: extend thư mục crates/shop-api/src/middleware/ cho mỗi layer mới — 1 file riêng (cors.rs, security_headers.rs, rate_limit.rs, trace.rs, metrics.rs, timeout.rs, validation.rs, fallback.rs) thay vì gộp 1 file middleware/mod.rs phình to khó maintain.

• tower::Service + tower::Layer trait foundation cross-framework Rust (axum + hyper + tonic).
• Middleware lifecycle: pre-process → handler → post-process — mô hình hành tây bao quanh handler.
• Ordering bottom-up axum: layer thêm SAU = wrap layer thêm TRƯỚC; đọc code từ dưới lên.
• from_fn vs custom Layer: function quick (90% case), Layer reusable + stateful (10% case).
• 3 loại scope middleware: per-request global, per-route, per-state.
• Pattern lock Shop API: from_fn cho đơn giản, custom Layer cho reusable cross-project.
• Shop API stack hiện tại 4 layer: request_id + enrich_error + compression + decompression (+ 1 per-route Idempotency).
• Roadmap Group 8 10 layer mới: cors + security + rate-limit + body-limit + trace + metrics + timeout + validation + fallback + test.
• Final stack 11 layer production-grade sau Group 8 hoàn thành.
• Comment thứ tự execution INNER/OUTERMOST trên mỗi .layer() tránh confuse cho team.
• File path lock: extend crates/shop-api/src/middleware/ cho mỗi layer mới — 1 file riêng (cors.rs, security_headers.rs, rate_limit.rs, …).

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

1. tower::Service vs tower::Layer — phân biệt vai trò mỗi trait. Layer là gì so với Service?
2. Middleware ordering bottom-up axum — pitfall thường gặp khi developer nghĩ top-down. Cho ví dụ scenario reverse order ảnh hưởng behavior.
3. axum::middleware::from_fn vs custom Layer — khi nào chọn cái nào? 90/10 rule Shop API.
4. 3 loại scope middleware — per-request global, per-route, per-state. Cho ví dụ Shop API mỗi loại.
5. 11 layer stack production — sequence từ outermost → innermost ra sao? Tại sao compression OUTERMOST?

Bài 77: CORS + Security Headers — chi tiết tower-http CorsLayer (allow_origin, allow_methods, allow_headers, max_age), security headers (X-Frame-Options, Content-Security-Policy, X-Content-Type-Options, Referrer-Policy), pattern same-site cookie SameSite=Strict, áp Shop API global stack.