# handleRequestAthenaAuth

## Summary
Dispatch one `AuthRequest` through middleware, core routing, and plugin routing, returning either a handled `AuthResponse` or a middleware-level error.

## Symbol
- Name: `handle_request`
- Original Symbol: `AthenaAuth::handle_request`
- Kind: `method`
- Owner: `AthenaAuth`

## Signature
```rust
pub async fn handle_request(&self, req: AuthRequest) -> AuthResult<AuthResponse>
```

## Location
- `src/core/auth.rs`
- Used by the Axum integration in `src/handlers/axum.rs`

## Inputs
- `req`: required; consumed by value
- Path handling: callers may pass a route already stripped to internal form like `"/sign-in/email"` or mounted under the configured `base_path`
- Route-specific headers, cookies, query parameters, and JSON body requirements are enforced by the matched core handler, plugin, and middleware

## Returns
- Usually `Ok(AuthResponse)`, including normal success responses and standardized error responses produced from core or plugin `AuthError` values
- `Err(AuthError)` only when middleware `before_request` or `after_request` processing itself fails

## Errors
- Middleware failures from `run_before(...)` or `run_after(...)` bubble out as `Err(AuthError)`
- Core-handler and plugin `AuthError` values are converted into JSON error responses instead of being returned as `Err`

## Preconditions
- The request must satisfy whichever auth, body, query, and header requirements the matched route expects
- If the route depends on bearer auth or a session cookie, the caller must supply those using the request headers expected by the selected plugins and middleware

## Side Effects
- Runs middleware `before_request` and `after_request`
- May read or mutate database state depending on the matched route
- May emit `Set-Cookie` headers, including cookie-clearing headers for invalid or revoked session-cookie requests
- Logs request outcome with a generated or forwarded trace id
- Adds `x-request-id` and `x-athena-trace-id` headers on standardized auth error responses so the same identifier can be searched in logs or Loki

## Guarantees
- Any caller-supplied virtual session state on `AuthRequest` is discarded at the public entry point and rebuilt from the plain request parts
- The configured `base_path` is stripped before disabled-path checks, plugin `before_request` hooks, and internal route matching
- `disabled_paths` are enforced before plugin `before_request` short-circuits such as API-key session emulation
- When a request matches both a core route and a plugin route, plugin dispatch gets the first handling opportunity
- Unmatched requests become a standardized 404 JSON response with a `message` field
- Core/plugin auth errors become standardized JSON error bodies with `message`, `version`, and `traceId`, and the same trace id is echoed in response headers and warning/error logs
- On `Unauthenticated` or `SessionNotFound`, if the incoming request carried the configured session cookie, the response includes a clearing `Set-Cookie` header
- `after_request` middleware runs for both success responses and standardized core/plugin error responses, in reverse middleware order

## Examples
```rust
let response = auth
    .handle_request(AuthRequest::new(HttpMethod::Get, "/ok"))
    .await?;
assert_eq!(response.status, 200);
```

## Source of Truth
- Implementation: `src/core/auth.rs`
- Middleware contract: `crates/core/src/middleware/mod.rs`
- Error body contract: `crates/core/src/error.rs`, `crates/core/src/types.rs`
- Tests: `src/tests/response_shape_tests.rs`, `src/tests/route_collision_precedence_tests.rs`, `tests/compatibility_tests.rs`
- Call sites: `examples/auth_builder_minimal.rs`, `examples/auth_core_ok.rs`, `src/handlers/axum.rs`
