Writing Middleware
=================

Middleware sits between the server and your route handlers, processing
every request and response that flows through your application. It's the
right tool for cross-cutting concerns — things that apply to *all*
requests, not just specific routes.

Common middleware use cases:

- Request logging and timing
- Authentication and authorization
- Adding security headers
- Request ID generation
- Rate limiting
- Response compression (built-in)


Hooks vs. Middleware
--------------------

Responder gives you two levels of request processing:

**Hooks** (``before_request`` / ``after_request``) run inside Responder's
routing layer. They receive Responder's ``req`` and ``resp`` objects and
are the simplest way to add behavior::

    @api.route(before_request=True)
    def add_header(req, resp):
        resp.headers["X-Powered-By"] = "Responder"

    @api.after_request()
    def log_request(req, resp):
        print(f"{req.method} {req.url.path} -> {resp.status_code}")

**Middleware** runs at the ASGI level, wrapping the entire application.
It's more powerful but more complex — you work with raw ASGI scopes
instead of Responder objects. Use middleware when you need to process
requests *before* they reach Responder's routing, or when you need to
integrate with Starlette middleware.


Using Starlette Middleware
--------------------------

Responder is built on Starlette, so any Starlette middleware works
out of the box::

    from starlette.middleware.base import BaseHTTPMiddleware

    class TimingMiddleware(BaseHTTPMiddleware):
        async def dispatch(self, request, call_next):
            import time
            start = time.time()
            response = await call_next(request)
            duration = time.time() - start
            response.headers["X-Response-Time"] = f"{duration:.3f}s"
            return response

    api.add_middleware(TimingMiddleware)

The ``dispatch`` method receives a Starlette ``Request`` and a
``call_next`` function. Call ``call_next(request)`` to pass the request
to the next middleware (or to your route handler). The return value is
a Starlette ``Response`` that you can modify before it's sent.


Built-in Middleware
-------------------

Responder configures several middleware components automatically:

- **GZipMiddleware** — compresses responses larger than 500 bytes
- **TrustedHostMiddleware** — validates the ``Host`` header
- **ServerErrorMiddleware** — catches unhandled exceptions
- **ExceptionMiddleware** — routes exceptions to your handlers
- **SessionMiddleware** — manages signed cookie sessions

Optional middleware you can enable:

- **CORSMiddleware** — ``api = responder.API(cors=True)``
- **HTTPSRedirectMiddleware** — ``api = responder.API(enable_hsts=True)``


Adding Third-Party Middleware
-----------------------------

Any ASGI middleware can be added with ``api.add_middleware()``::

    from some_package import SomeMiddleware

    api.add_middleware(SomeMiddleware, option1="value", option2=True)

Keyword arguments are passed to the middleware's constructor.


Middleware Order
----------------

Middleware wraps your application like layers of an onion. The *last*
middleware added is the *outermost* layer — it sees the request first
and the response last.

Responder's built-in middleware stack (from outermost to innermost):

1. SessionMiddleware
2. ServerErrorMiddleware
3. CORSMiddleware (if enabled)
4. TrustedHostMiddleware
5. HTTPSRedirectMiddleware (if enabled)
6. GZipMiddleware
7. ExceptionMiddleware
8. Your routes

When you call ``api.add_middleware()``, your middleware is added *outside*
the existing stack. Keep this in mind for ordering dependencies — if
middleware A depends on middleware B having run first, add B before A.


When to Use What
-----------------

- **Simple header additions, logging, auth checks** → use hooks
- **Response transformation, timing, third-party integrations** → use middleware
- **Rate limiting** → use the built-in ``RateLimiter`` (it uses hooks internally)
- **Request ID** → use ``api = responder.API(request_id=True)``

Start with hooks. They're simpler and cover most cases. Graduate to
middleware when hooks aren't enough.