Metadata-Version: 2.4
Name: rn-forge-fastapi
Version: 0.4.0
Summary: FastAPI adapters over rn-forge-web
Author: Rohit Narayanan
Author-email: Rohit Narayanan <rohit.nn@gmail.com>
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Framework :: FastAPI
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.14
Classifier: Typing :: Typed
Requires-Dist: rn-forge-auth>=0.1.0,<0.2
Requires-Dist: rn-forge-web[security]>=0.3.0,<0.4
Requires-Dist: fastapi>=0.141.1
Requires-Dist: opentelemetry-instrumentation-fastapi>=0.65b0
Requires-Dist: rn-forge-auth[oidc]>=0.1.0,<0.2 ; extra == 'oidc'
Requires-Dist: rn-forge-auth[redis]>=0.1.0,<0.2 ; extra == 'redis'
Requires-Dist: assertpy>=1.1 ; extra == 'testing'
Requires-Dist: httpx>=0.28.1 ; extra == 'testing'
Requires-Dist: pytest>=9.1.1 ; extra == 'testing'
Requires-Dist: rn-forge-data>=0.1.1,<0.2 ; extra == 'transfer'
Requires-Dist: python-multipart>=0.0.20 ; extra == 'transfer'
Requires-Python: >=3.14
Project-URL: Documentation, https://rn-forge.github.io/pykit/packages/rn-forge-fastapi/latest/
Project-URL: Source, https://github.com/rn-forge/pykit/tree/main/packages/rn-forge-fastapi
Project-URL: Changelog, https://github.com/rn-forge/pykit/blob/main/packages/rn-forge-fastapi/CHANGELOG.md
Project-URL: Issues, https://github.com/rn-forge/pykit/issues
Provides-Extra: oidc
Provides-Extra: redis
Provides-Extra: testing
Provides-Extra: transfer
Description-Content-Type: text/markdown

# rn-forge-fastapi

[Documentation](https://rn-forge.github.io/pykit/packages/rn-forge-fastapi/latest/)
·
[Changelog](https://github.com/rn-forge/pykit/blob/main/packages/rn-forge-fastapi/CHANGELOG.md)
·
[Source](https://github.com/rn-forge/pykit/tree/main/packages/rn-forge-fastapi)
· [All pykit packages](https://rn-forge.github.io/pykit/)

FastAPI adapters over `rn-forge-web`.

`rn-forge-web` settles the wire — the problem body, the cursor codec, the ETag
semantics, the idempotency reuse rule, the readiness aggregate, the 401/403
boundary. This package is the FastAPI-shaped plumbing that puts those decisions
into an application: exception-handler registration, `Depends` factories, a
router factory and an OpenAPI repair. **It makes no wire decision of its own.**

| Module | What it adapts |
| -- | -- |
| `problem` | `register_problem_handlers(app)` — every error the app produces, including FastAPI's own 404/405/422, as `application/problem+json` |
| `openapi` | `FastApiApp.openapi()` repairs the cached document — adds `ProblemDetail` and the problem responses it can actually produce, accuracy only; `operation_id` — the shared `operationId` convention |
| `dependencies` | `page_params`, `require_idempotency_key`, `require_if_match` |
| `health` | `health_router(checks=...)` — `/healthz` and `/readyz` |
| `auth` | `auth_router` and `SessionMiddleware` — the `/auth` routes, login sessions and CSRF protection over `rn-forge-auth`; `bearer_auth`, `basic_auth`, `current_principal`, `requires`, `requires_permission`, `PolicyGuard` — `Security` dependencies; rate limiting; `auth.redis` — the Redis CSRF store and rate limiter (`redis` extra) |
| `app` | `FastApiApp(config)` — a `FastAPI` subclass with the standard adapters installed |

## Where it sits

```text
commons ──► web ──► auth ──► django
                          └───► fastapi      (this package)
```

`rn-forge-fastapi` depends on `rn-forge-web`, `rn-forge-auth` and FastAPI. It
never imports `rn_forge.django` — the two framework packages are independent
siblings — nor `rn_forge.cli` or `rn_forge.tooling`. `.importlinter` carries the
`fastapi-runtime-has-no-tooling` and `web-layers` contracts, and
`uv run lint-imports` proves them.

## The import path

This package is `rn_forge.fastapi`; the framework is `fastapi`. The two do not
collide: `from fastapi import APIRouter` always resolves to the framework,
unless a process puts `src/rn_forge/` itself on `sys.path`.

## Installation

Require the packages by version range:

```toml
dependencies = [
  "rn-forge-fastapi>=0.4,<0.5",
  "rn-forge-web>=0.3,<0.4",
]
```

Application code imports `rn_forge.web` directly (wire models, pagination,
problem types, the auth contract), and this package does not re-export it.
Declare `rn-forge-web` as well, so the import is not an undeclared transitive
dependency.

Inside this workspace, `[tool.uv.sources]` overrides the requirement with the
local checkout, for local development only.

## What this package deliberately does not ship

- **Settings, infrastructure, or application policy.** `FastApiApp` wires the
  standard adapters from an explicit `AppConfig`; applications still construct
  their settings, clients, authenticators, stores and product routes.
- **A dependency-injection container, a settings facade, any store.** FastAPI's
  `Depends` is the DI framework; configuration arrives as function arguments;
  an `AsyncIdempotencyStore` is SQL- or Redis-backed and belongs to the
  application.
- **A tracing middleware.** Tracing is W3C Trace Context through OpenTelemetry's
  own `FastAPIInstrumentor`, not a house middleware — `FastApiApp` calls it by
  default (`AppConfig.tracing`). The current trace id reaches a 500 the same
  way it reaches any other response: `render_problem` reads it from the active
  span, and `ServerErrorMiddleware` sits inside the instrumentation's span,
  not outside it.
- **A token verifier.** The auth binding takes any
  `rn_forge.auth.Authenticator`; verifying a JWT against a JWKS is that
  authenticator's job. For OIDC that authenticator already exists —
  `rn_forge.auth.oidc.OidcAuthenticator`, via this package's `oidc` extra —
  and is shared with `rn-forge-django` so both stacks accept the same tokens.
  Nothing here wraps it; pass it to `bearer_auth`.

## Dependencies

**`rn-forge-web`** — every module adapts one of its primitives.
`rn-forge-commons` is not declared: nothing here imports it directly, and it
arrives through `rn-forge-web`.

**`rn-forge-auth`** — a base dependency: the `auth` package is built on its
login flows, `Principal`, `Requirement` and authenticator contracts. Its OIDC
adapter comes with this package's `oidc` extra, and its Redis stores with the
`redis` extra, which also installs the client for `auth.redis`.

**`fastapi`** (`>=0.141.1`) — a hard dependency, not an extra. It is used as
documented, not abstracted away — an application keeps `APIRouter`, `Depends`,
`Header` and `response_model` exactly as FastAPI defines them. `pydantic` (2.13
resolved) and `starlette` arrive with it; the `rn_forge.web.WireModel`
configuration uses `validate_by_name`/`serialize_by_alias`, which need pydantic
≥ 2.11.

**Not wrapped:** FastAPI's `HTTPBearer`/`HTTPBasic` are used with
`auto_error=False` — kept for the `securitySchemes` entry they put in the
schema, stripped of their own 401 body and non-RFC-6750 challenge.

## OpenAPI across stacks

Wire behaviour and `operationId` are identical to the Django stack; the rest of
the document text is not. `Page[T]` keeps pydantic's own name, `Page_UserOut_`.

An operation outside the six CRUD verbs is a custom method, spelled
`POST /orders/{orderId}:cancel` and named `ordersCancel` (see `rn-forge-web`'s
`api-conventions.md` §9). Spelled as a plain path segment it still gets a
mechanical name and wants an explicit `operation_id=`.

`operationId` must be unique across the document. drf-spectacular warns and
appends a numeral on a collision; FastAPI does neither, so two routes ending in
the same literal segment collide silently here.

## Documentation

`uv run --directory packages/rn-forge-fastapi --group docs mkdocs build --strict`,
or the combined site from the repo root. The wiring guide is the page an
application is written from.
