Add Sarlette/FastAPI support

AGENTS.md

@@ -16,18 +16,20 @@ Haiway is a Python framework helping to build high-quality codebases. It focuses
   - `attributes/`: Attribute annotations, state objects, and validation helpers.
   - `context/`: Structured-concurrency context management, scopes, and lifecycle utilities.
   - `helpers/`: Cross-cutting helpers for configuration, async orchestration, retries, throttling, HTTP adapters, file access, and message queues.
+  - `fastapi/`: FastAPI application factory reusing the Starlette integration pieces, built on top of `fastapi`.
   - `httpx/`: Thin wrappers around `httpx2.AsyncClient` aligned with haiway abstractions.
   - `opentelemetry/`: OpenTelemetry integration and observability backend wiring.
   - `postgres/`: Async Postgres client, configuration, and typed row/state helpers built on top of `asyncpg` patterns.
   - `rabbitmq/`: Async RabbitMQ client/state helpers and typed queue/message abstractions built on top of `pika`.
+  - `starlette/`: Starlette integration plugging the context into ASGI request handling - application context, middleware, and application factory built on top of `starlette`.
   - `types/`: Fundamental typed primitives (e.g., `Missing`, immutable containers) shared across modules.
   - `utils/`: Generic async utilities (queues, streams, env helpers, logging bootstrap, metadata helpers).
 - `tests/`: Pytest suite mirroring package structure; keep new tests alongside the code they cover.
 - `docs/`: MkDocs content, author guides, and API references; update navigation in `mkdocs.yml` when adding pages.
 - `Makefile`: Entry point for common dev tasks (`format`, `lint`, `test`, `docs`, `docs-format`, `docs-lint`, `sync`, `update`).
 - `pyproject.toml`: Project metadata, dependencies, and configuration.
 
-Core public exports are centralized in `src/haiway/__init__.py`. Optional integration packages also expose public APIs from their own subpackages such as `haiway.postgres`, `haiway.rabbitmq`, and `haiway.opentelemetry`.
+Core public exports are centralized in `src/haiway/__init__.py`. Optional integration packages also expose public APIs from their own subpackages such as `haiway.postgres`, `haiway.rabbitmq`, `haiway.starlette`, `haiway.fastapi`, and `haiway.opentelemetry`.
 
 ## Style & Patterns
 

docs/features/context-presets.md

@@ -250,7 +250,9 @@ with ctx.presets(dev_preset, prod_preset, staging_preset):
 
 Direct presets passed to `ctx.scope(preset)` take precedence over registry lookup. Registry lookup
 is scoped through `ctx.presets(...)`, and a nested registry shadows the outer registry for the
-duration of that nested `with` block.
+duration of that nested `with` block - a name is resolved against the innermost registry only,
+without falling back to the outer one. Entering `ctx.presets()` with no presets is a no-op, leaving
+whatever registry is already active in place.
 
 ## Best Practices
 

docs/features/fastapi.md

@@ -0,0 +1,225 @@
+# FastAPI
+
+Haiway provides a FastAPI variant of the [Starlette](starlette.md) integration. It is the same
+integration with a FastAPI base: the request context is declared through the same `ServerContext`,
+requests are handled within scopes by the same `ContextMiddleware`, and `haiway.fastapi.application`
+wires both into a `FastAPI` application instead of a plain Starlette one.
+
+## Overview
+
+- **FastAPI Base**: returns a regular `FastAPI` application - routers, dependencies, OpenAPI docs
+  and everything else work as they always do
+- **Shared Context**: `ServerContext` and `ContextMiddleware` are the Starlette ones, re-exported
+  from `haiway.fastapi` so a single import is enough
+- **Scope per Request**: state declared by the server context is available to endpoints,
+  dependencies, background tasks and nested middlewares
+
+## Installation
+
+Install the FastAPI extra, which brings Starlette along with it:
+
+```bash
+pip install "haiway[fastapi]"
+```
+
+## Quick Start
+
+Declare the application context, then build the application from it:
+
+```python
+from fastapi import APIRouter
+from haiway import State, ctx
+from haiway.fastapi import ServerContext, application
+from haiway.httpx import HTTPXClient
+
+
+class ServiceConfig(State):
+    upstream: str = "https://example.com"
+
+
+router = APIRouter(prefix="/api/v1", tags=["example"])
+
+
+@router.get("/status")
+async def status() -> dict[str, str]:
+    # state declared by the server context, resolved from the request scope
+    config: ServiceConfig = ctx.state(ServiceConfig)
+    ctx.log_info("Checking %s", config.upstream)
+
+    return {"upstream": config.upstream}
+
+
+app = application(
+    ServerContext(
+        ServiceConfig(),
+        disposables=(HTTPXClient(),),
+    ),
+    routers=(router,),
+    title="Example API",
+    version="1.0.0",
+    openapi_url="/openapi.json" if __debug__ else None,
+    docs_url="/swagger" if __debug__ else None,
+)
+```
+
+Serve it with any ASGI server:
+
+```bash
+uvicorn example:app
+```
+
+## Differences from the Starlette Factory
+
+Everything about the request context - state, disposables, presets, observability, scope names and
+trace headers - is described on the [Starlette](starlette.md) page and applies here unchanged. Only
+the application factory differs:
+
+- `routers` takes `APIRouter` instances, included in order, instead of `routes` taking Starlette
+  routes. A router serving under a path prefix carries it itself, as `APIRouter(prefix="/api/v1")`,
+  and further routers can be added afterwards through `app.include_router(...)`
+- everything FastAPI accepts and Starlette does not - `title`, `version`, `description`,
+  `openapi_url`, `docs_url`, global `dependencies`, `root_path` - is passed through as keyword
+  arguments
+- `exception_handlers` accepts async and sync handlers alike - a sync one is called in a worker
+  thread - and the type `ExceptionHandling` names their signature. A handler nested below the
+  middleware - the validation error handler of FastAPI included - answers within the scope of its
+  request, so its response carries the trace headers, while the `Exception` and `500` slots run
+  above it and carry none
+
+`middleware`, `lifespan` and `debug` work exactly as in the Starlette factory, and
+`ContextMiddleware` is installed as the outermost application middleware. There is no
+`max_body_size` here - FastAPI does not accept one, so passing it through would fail; a body limit
+takes a middleware of its own.
+
+## Distributed Traces
+
+Requests continue the trace they arrive with, which takes passing the OpenTelemetry backend factory
+to the context - the W3C trace context of each request is read from its headers and handed to it:
+
+```python
+from haiway.opentelemetry import OpenTelemetry
+
+context = ServerContext(observability=OpenTelemetry.observability)
+```
+
+Responses then report which trace handled them, through the `trace-id`, `traceparent` and
+`tracestate` headers, and an outgoing request carries it onwards when it asks to:
+
+```python
+context = ServerContext(
+    observability=OpenTelemetry.observability,
+    disposables=(HTTPXClient(base_url=INTERNAL_URL),),
+)
+
+# within an endpoint - the trace continues into the service you own
+response = await HTTPClient.get(url="/users", trace_propagation=True)
+```
+
+See [Observability](starlette.md#observability) for what is resolved before the backend sees it, and
+for configuring the OpenTelemetry integration itself.
+
+## Dependencies and Endpoints
+
+The context scope is entered before routing, so everything FastAPI runs while handling a request
+runs within it:
+
+```python
+from typing import Annotated
+
+from fastapi import Depends, Header
+
+
+class Caller(State):
+    identifier: str
+
+
+async def caller(authorization: Annotated[str, Header()]) -> Caller:
+    # state resolved from the scope of the request being handled
+    return await Authorization.verify(authorization)
+
+
+@router.get("/profile")
+async def profile(caller: Annotated[Caller, Depends(caller)]) -> dict[str, str]:
+    return {"identifier": caller.identifier}
+```
+
+That covers dependencies, endpoints, background tasks added through `BackgroundTasks`, and the
+generator of a streaming response. Synchronous endpoints are included as well - FastAPI runs them in
+a worker thread with the context of the request copied into it, so `ctx.state(...)` resolves there
+too. Long blocking work still belongs off the event loop path: prefer async endpoints and Haiway's
+`@asynchronous` helper for the calls which cannot be.
+
+## Streaming Responses
+
+`StreamResponse` is re-exported here and returned from an endpoint like any other response. The
+scope of the request stays entered until the last chunk was sent, so the producer resolves state and
+reports the trace of the request it belongs to:
+
+```python
+from collections.abc import AsyncGenerator
+
+from haiway.fastapi import StreamResponse
+
+
+@router.get("/updates")
+async def updates() -> StreamResponse:
+    async def content() -> AsyncGenerator[bytes]:
+        async for update in Updates.subscribe():  # state of the request
+            yield update.payload.encode()
+
+    return StreamResponse(content(), media_type="application/x-ndjson")
+```
+
+Returning a `Response` from a FastAPI endpoint skips its serialization, so annotate the return type
+with the response itself - or with `Response` - rather than with the model of a chunk. See
+[Streaming Responses](starlette.md#streaming-responses) for what closes a stream and for the scope a
+producer of its own needs.
+
+## Existing Applications
+
+An application which is already built is plugged in by installing the same two pieces by hand:
+
+```python
+from fastapi import FastAPI
+from haiway.fastapi import ContextMiddleware, ServerContext
+
+context = ServerContext(disposables=(HTTPXClient(),))
+
+app = FastAPI(lifespan=context.lifespan)
+app.add_middleware(ContextMiddleware, context=context)
+```
+
+`add_middleware` puts the middleware in front of the ones added before it, so adding it last keeps
+it outermost - which is what makes the context available to the other middlewares as well. When the
+application already has a lifespan of its own, compose the two:
+
+```python
+app = FastAPI(lifespan=context.composed_lifespan(existing_lifespan))
+```
+
+## Testing
+
+An application built this way is tested like any other FastAPI application, entering its lifespan
+first so the context is prepared. A context backs a single run, so build the application within the
+test - through a factory - rather than entering the lifespan of a shared one more than once.
+`TestClient` requires `httpx2`, installed with the `httpx` extra:
+
+```python
+from fastapi import FastAPI
+from fastapi.testclient import TestClient
+
+
+def build_application() -> FastAPI:  # a context per run, so an application per test
+    return application(
+        ServerContext(ServiceConfig(), disposables=(HTTPXClient(),)),
+        routers=(router,),
+    )
+
+
+def test_status() -> None:
+    with TestClient(build_application()) as client:  # enters the lifespan
+        response = client.get("/api/v1/status")
+
+    assert response.status_code == 200
+    assert response.headers["trace-id"]
+```

docs/features/http-client.md

@@ -350,11 +350,23 @@ a `Content-Length`. It can be consumed only once, which means it cannot be repla
 preserving the method (307, 308) or a retry fails with `HTTPClientError`. Pass `bytes` instead when
 the request has to survive either.
 
+A streamed payload stays owned by whoever passed it. The request reads it while it is in flight and
+never closes it, so a request that fails before the upload finished - or a server that answers early
+\- leaves the generator open. Close it at the call site when the generator holds anything worth
+releasing:
+
+```python
+from contextlib import aclosing
+
+async with aclosing(encoded_rows(pending_events())) as body:
+    response = await HTTPClient.put(url="/uploads/events", body=body)
+```
+
 Buffered payloads are `bytes`, not `str` - `HTTPBody` is `AsyncGenerator[bytes] | bytes`, so text is
 encoded at the call site and the charset is never guessed for you. It has to be a full async
-generator rather than any async iterable, because a streamed body is closed once it is read or
-abandoned and only a generator has `aclose`. Wrap a bare async iterator in an `async def` generator
-that yields from it.
+generator rather than any async iterable, because a streamed response body is closed once it is read
+or abandoned and only a generator has `aclose`. Wrap a bare async iterator in an `async def`
+generator that yields from it.
 
 ### Connection Pooling and Reuse
 
@@ -427,26 +439,30 @@ A few properties worth knowing:
 ### Trace Propagation
 
 A request can carry the current trace position, so the called service continues this trace instead
-of starting its own. It is asked for per request, and off by default:
+of starting its own. It is asked for per request:
 
 ```python
 async with ctx.scope(
     "api",
     observability=OpenTelemetry.observability(),
-    disposables=(HTTPXClient(base_url="https://internal.example.com"),),
+    disposables=(HTTPXClient(),),
 ):
-    # this request carries `traceparent`, and `tracestate` when present
-    response = await HTTPClient.get(url="/users", trace_propagation=True)
+    # carries `traceparent`, and `tracestate` when present
+    internal = await HTTPClient.get(
+        url="https://internal.example.com/users",
+        trace_propagation=True,
+    )
 
-    # this one does not
-    other = await HTTPClient.get(url="/public")
+    # left off by default, so a third party sees no trace identifiers
+    external = await HTTPClient.get(url="https://api.vendor.com/rates")
 ```
 
-`trace_propagation` is per request, and defaults to `False`, because it exposes internal trace
-identifiers to whoever is called - ask for it towards services you own, not towards third party
-APIs. Since it is decided at the request site, one client can be used for both. Headers passed to
-the request are never overridden, so a caller managing trace context itself keeps control, and a
-backend with no trace position to hand out - the default logger among them - propagates nothing.
+The decision belongs to the request site and defaults to `False` - propagating exposes internal
+trace identifiers to whoever is called, which is a choice per callee rather than per client.
+
+Headers passed to the request are never overridden, so a caller managing trace context itself keeps
+control, and a backend with no trace position to hand out - the default logger among them -
+propagates nothing, so the same code works whether or not the service is traced.
 
 ## Testing
 
@@ -515,8 +531,9 @@ async def test_user_fetching():
 1. **Send replayable bodies where redirects or retries are expected**: A streamed request body is
    consumed once and cannot be sent again.
 1. **Mock the `requesting` callable in tests**: Most unit tests do not need a real transport.
-1. **Ask for `trace_propagation` only on requests towards services you own**: It hands internal
-   trace identifiers to whoever is called.
+1. **Propagate the trace only towards services you own**: Ask for `trace_propagation` on requests
+   towards your own services, and leave it off for third-party APIs. It hands internal trace
+   identifiers to whoever is called.
 
 ## Custom Implementations
 

docs/features/opentelemetry.md

@@ -304,6 +304,20 @@ trace instead. The value is decoded once, when the adapter is created.
 The remote parent applies to root scopes only. A nested scope entered within a spawned task stays
 under the span its task inherited, instead of being re-rooted at the remote parent.
 
+Reading the headers and preparing a backend per request is what the Starlette and FastAPI
+integrations do, so an ASGI application needs none of the wiring above - `observability` there takes
+the callable itself:
+
+```python
+from haiway.starlette import ServerContext
+
+context = ServerContext(observability=OpenTelemetry.observability)
+```
+
+See [Starlette](starlette.md#distributed-traces) for what it resolves from a request, and for the
+cases a backend handed a single value cannot see - several `traceparent` headers, or a `tracestate`
+split across a few.
+
 To propagate the current active span to another system, use:
 
 ```python