Current Status

Updated Jul 20, 2026

The following functionality is now implemented:

  • Middleware configuration options (header name, generator, validator, etc.).
  • Header retrieval and whitespace normalization.
  • Trusted source IP/CIDR matching.
  • Default UUIDv7 generator implementation.
  • Automatic correlation ID generation for requests without valid incoming IDs.
  • Custom generator injection support.
  • Default UUID validator for incoming ID format validation.
  • Validation integration into request processing: incoming IDs from trusted sources are validated (when a validator is configured) before acceptance, with DEBUG-level logging of failures.
  • Context variables (correlation_id_var and user_id_var) for request-scoped storage via contextvars.
  • Correlation ID context variable lifecycle management: correlation_id_var is set during request processing and reset during response cleanup.
  • Dual access to the correlation ID via req.context.correlation_id and correlation_id_var.get(), both always in sync during request handling.
  • ContextualLogFilter for injecting correlation ID and user ID into standard library log records, with "-" placeholder when context is not set. Pre-existing record attributes (e.g. from extra=) are preserved.
  • RECOMMENDED_LOG_FORMAT constant providing a ready-made format string for use with logging.Formatter or dictConfig.
  • Structlog integration documentation with custom processor and bind_contextvars bridging approaches (task 3.2).
  • httpx propagation wrapper functions (request_with_correlation_id and async_request_with_correlation_id) for injecting the correlation ID into outgoing HTTP requests (task 4.1.1).
  • httpx transport classes (CorrelationIDTransport and AsyncCorrelationIDTransport) for shared client configuration that injects the correlation ID into outgoing HTTP requests (task 4.1.2).
  • Celery publish propagation via propagate_correlation_id_to_celery, which injects the ambient request correlation ID into outgoing task message properties (task 4.2.1).

See the roadmap for the full implementation plan.