actix-web-request-uuid

A Rust library to add request ID functionality with the actix-web framework.

Japanese

Please refer to README.ja.md .

Installation

Add this to your Cargo.toml:

[dependencies]
actix-web-request-uuid = "0.1.0"

Usage

Add this to your crate root:

use actix_web::{web, App, HttpServer, HttpResponse, Error};
use actix_web_request_uuid::RequestIDMiddleware;

#[actix_rt::main]
async fn main() -> std::io::Result<()> {
    HttpServer::new(|| {
        App::new()
            .wrap(RequestIDMiddleware::new())
            .service(web::resource("/").to(|| HttpResponse::Ok()))
    })
    .bind("127.0.0.1:59880")?
    .run()
    .await
}

Features

Automatic request ID generation for each HTTP request
Easy integration with actix-web middleware
Lightweight and efficient implementation
Compatible with actix-web ecosystem

Changes from the Original Project

This project is based on pastjean/actix-web-requestid with significant feature enhancements:

1. Global Access via Thread-Local Variables

Added request ID management functionality using Thread-Local variables that the original project lacked:

get_current_request_id(): Access request ID from anywhere during request processing
set_current_request_id(): Manually set request ID
clear_current_request_id(): Clear request ID information

// Get request ID from any function
async fn my_service() -> Result<(), Error> {
    if let Some(request_id) = get_current_request_id() {
        log::info!("Processing request: {}", request_id);
    }
    Ok(())
}

2. Rich Customization Options

While the original project only supported UUID v4, this version supports various formats:

Custom ID length: with_id_length() - Specify any length from 1 to 36 characters
Full UUID format: with_full_uuid() - 36 characters with hyphens
Simple UUID format: with_simple_uuid() - 32 characters without hyphens
Custom format: with_custom_uuid_format() - Custom formatters
Custom generator: generator() - Completely custom ID generation logic
Header name customization: header_name() - Change default request-id

// Configuration example
let middleware = RequestIDMiddleware::new()
    .with_simple_uuid()
    .header_name("X-Request-ID")
    .generator(|| format!("req-{}", Uuid::new_v4().simple()));

3. Actix Web Extractor Support

More intuitive API through FromRequest implementation that the original project lacked:

// Get request ID directly in handler functions
async fn show_id(request_id: RequestID) -> impl Responder {
    format!("Your request ID: {}", request_id)
}

4. Extension Traits

Trait for directly getting request ID from HttpMessage:

pub trait RequestIDMessage {
    fn request_id(&self) -> RequestID;
}

// Usage example
fn my_middleware(req: &HttpRequest) {
    let id = req.request_id(); // Direct access
}

5. Error Handling and Robustness

ID length validation: Safe feature that panics on lengths ≤ 0
Existing ID reuse: Reuse IDs stored in extensions
Automatic cleanup: Automatic Thread-Local variable cleanup after request processing

6. Comprehensive Test Suite

More detailed test coverage than the original project:

Custom ID length tests
UUID format-specific tests
Custom header name tests
Thread-Local functionality tests
Error case tests

7. Rich Documentation

Detailed docstrings for all public functions
Practical code samples
Use case-specific explanations
Best practices guide

These enhancements have significantly upgraded the original simple request ID generation middleware into an enterprise-level request tracking system supporting log collection, distributed tracing, and debugging assistance.

Documentation

For detailed documentation and examples, please refer to the docs.rs page.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request. Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

License

This project is licensed under either of

Apache License, Version 2.0, (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

Original Project

This is a fork of pastjean/actix-web-requestid. We thank the original author for their contribution to the Rust community.

actix-web-request-uuid 0.2.0