Request Pipeline

The request lifecycle

For HTTP applications, the effective pipeline is:

1. request enters the Axum router created by NestForgeFactory
2. framework request context is created
3. a request ID is generated and attached
4. a scoped container is created for request-level dependencies
5. auth resolution runs if the app configured one
6. middleware bindings run
7. guards run
8. interceptors wrap the handler
9. the handler executes
10. exception filters can rewrite HttpException values

Scoped container behavior

Each request receives its own scoped container derived from the app container. This is why request-scoped providers and request metadata extraction work cleanly without turning the whole application into mutable shared state.

Request ID handling

The HTTP factory generates request IDs and adds them both:

• to request extensions and the scoped container
• to the response header x-request-id

This makes request tracing available to handlers, middleware, filters, and external clients.

Auth resolution

If with_auth_resolver(...) is configured, the factory extracts the bearer token and asks your resolver to map it into an AuthIdentity. On success, the identity becomes available to:

• AuthUser
• OptionalAuthUser
• role-based guards
• other code that resolves identity from the request container

Middleware vs guards vs interceptors

Use the stages deliberately:

• middleware for raw HTTP concerns such as request logging or header normalization
• guards for access rules and preconditions
• interceptors for wrapping execution and responses

That separation is one of the clearest architectural choices in the framework, and it is worth preserving in application code.

Exception filters

Global and route-level exception filters can rewrite HttpException values before the response is finalized. This is useful when you want:

• consistent public error messages
• translation from internal errors to public API errors
• route-specific error rewriting

Testing the pipeline

The workspace test suites under crates/nestforge/tests/ exercise many of these behaviors directly, including:

• auth extraction
• request decorators
• response envelopes and serializers
• cache interceptor behavior
• route-level metadata and filters