rn-forge-fastapi 0.4.0__tar.gz → 0.4.1__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (30) hide show
  1. {rn_forge_fastapi-0.4.0 → rn_forge_fastapi-0.4.1}/PKG-INFO +6 -2
  2. {rn_forge_fastapi-0.4.0 → rn_forge_fastapi-0.4.1}/README.md +1 -0
  3. {rn_forge_fastapi-0.4.0 → rn_forge_fastapi-0.4.1}/pyproject.toml +17 -6
  4. rn_forge_fastapi-0.4.1/pyproject.toml.orig +115 -0
  5. {rn_forge_fastapi-0.4.0 → rn_forge_fastapi-0.4.1}/src/rn_forge/fastapi/__init__.py +2 -1
  6. {rn_forge_fastapi-0.4.0 → rn_forge_fastapi-0.4.1}/src/rn_forge/fastapi/problem.py +35 -1
  7. rn_forge_fastapi-0.4.1/src/rn_forge/fastapi/sse.py +133 -0
  8. rn_forge_fastapi-0.4.0/pyproject.toml.orig +0 -113
  9. {rn_forge_fastapi-0.4.0 → rn_forge_fastapi-0.4.1}/LICENSE +0 -0
  10. {rn_forge_fastapi-0.4.0 → rn_forge_fastapi-0.4.1}/src/rn_forge/fastapi/app.py +0 -0
  11. {rn_forge_fastapi-0.4.0 → rn_forge_fastapi-0.4.1}/src/rn_forge/fastapi/auth/__init__.py +0 -0
  12. {rn_forge_fastapi-0.4.0 → rn_forge_fastapi-0.4.1}/src/rn_forge/fastapi/auth/authorization.py +0 -0
  13. {rn_forge_fastapi-0.4.0 → rn_forge_fastapi-0.4.1}/src/rn_forge/fastapi/auth/csrf.py +0 -0
  14. {rn_forge_fastapi-0.4.0 → rn_forge_fastapi-0.4.1}/src/rn_forge/fastapi/auth/dependencies.py +0 -0
  15. {rn_forge_fastapi-0.4.0 → rn_forge_fastapi-0.4.1}/src/rn_forge/fastapi/auth/proxies.py +0 -0
  16. {rn_forge_fastapi-0.4.0 → rn_forge_fastapi-0.4.1}/src/rn_forge/fastapi/auth/rate_limit.py +0 -0
  17. {rn_forge_fastapi-0.4.0 → rn_forge_fastapi-0.4.1}/src/rn_forge/fastapi/auth/redis.py +0 -0
  18. {rn_forge_fastapi-0.4.0 → rn_forge_fastapi-0.4.1}/src/rn_forge/fastapi/auth/routes.py +0 -0
  19. {rn_forge_fastapi-0.4.0 → rn_forge_fastapi-0.4.1}/src/rn_forge/fastapi/auth/sessions.py +0 -0
  20. {rn_forge_fastapi-0.4.0 → rn_forge_fastapi-0.4.1}/src/rn_forge/fastapi/cors.py +0 -0
  21. {rn_forge_fastapi-0.4.0 → rn_forge_fastapi-0.4.1}/src/rn_forge/fastapi/dependencies.py +0 -0
  22. {rn_forge_fastapi-0.4.0 → rn_forge_fastapi-0.4.1}/src/rn_forge/fastapi/deprecation.py +0 -0
  23. {rn_forge_fastapi-0.4.0 → rn_forge_fastapi-0.4.1}/src/rn_forge/fastapi/health.py +0 -0
  24. {rn_forge_fastapi-0.4.0 → rn_forge_fastapi-0.4.1}/src/rn_forge/fastapi/idempotency.py +0 -0
  25. {rn_forge_fastapi-0.4.0 → rn_forge_fastapi-0.4.1}/src/rn_forge/fastapi/merge_patch.py +0 -0
  26. {rn_forge_fastapi-0.4.0 → rn_forge_fastapi-0.4.1}/src/rn_forge/fastapi/openapi.py +0 -0
  27. {rn_forge_fastapi-0.4.0 → rn_forge_fastapi-0.4.1}/src/rn_forge/fastapi/py.typed +0 -0
  28. {rn_forge_fastapi-0.4.0 → rn_forge_fastapi-0.4.1}/src/rn_forge/fastapi/read_mask.py +0 -0
  29. {rn_forge_fastapi-0.4.0 → rn_forge_fastapi-0.4.1}/src/rn_forge/fastapi/soft_delete.py +0 -0
  30. {rn_forge_fastapi-0.4.0 → rn_forge_fastapi-0.4.1}/src/rn_forge/fastapi/transfer.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: rn-forge-fastapi
3
- Version: 0.4.0
3
+ Version: 0.4.1
4
4
  Summary: FastAPI adapters over rn-forge-web
5
5
  Author: Rohit Narayanan
6
6
  Author-email: Rohit Narayanan <rohit.nn@gmail.com>
@@ -15,12 +15,14 @@ Classifier: Programming Language :: Python :: 3 :: Only
15
15
  Classifier: Programming Language :: Python :: 3.14
16
16
  Classifier: Typing :: Typed
17
17
  Requires-Dist: rn-forge-auth>=0.1.0,<0.2
18
+ Requires-Dist: rn-forge-commons>=0.8.0,<0.10
18
19
  Requires-Dist: rn-forge-web[security]>=0.3.0,<0.4
19
20
  Requires-Dist: fastapi>=0.141.1
20
21
  Requires-Dist: opentelemetry-instrumentation-fastapi>=0.65b0
21
22
  Requires-Dist: rn-forge-auth[oidc]>=0.1.0,<0.2 ; extra == 'oidc'
22
23
  Requires-Dist: rn-forge-auth[redis]>=0.1.0,<0.2 ; extra == 'redis'
23
- Requires-Dist: assertpy>=1.1 ; extra == 'testing'
24
+ Requires-Dist: sse-starlette>=3.4.11 ; extra == 'sse'
25
+ Requires-Dist: assertpy>=2.35 ; extra == 'testing'
24
26
  Requires-Dist: httpx>=0.28.1 ; extra == 'testing'
25
27
  Requires-Dist: pytest>=9.1.1 ; extra == 'testing'
26
28
  Requires-Dist: rn-forge-data>=0.1.1,<0.2 ; extra == 'transfer'
@@ -32,6 +34,7 @@ Project-URL: Changelog, https://github.com/rn-forge/pykit/blob/main/packages/rn-
32
34
  Project-URL: Issues, https://github.com/rn-forge/pykit/issues
33
35
  Provides-Extra: oidc
34
36
  Provides-Extra: redis
37
+ Provides-Extra: sse
35
38
  Provides-Extra: testing
36
39
  Provides-Extra: transfer
37
40
  Description-Content-Type: text/markdown
@@ -60,6 +63,7 @@ router factory and an OpenAPI repair. **It makes no wire decision of its own.**
60
63
  | `dependencies` | `page_params`, `require_idempotency_key`, `require_if_match` |
61
64
  | `health` | `health_router(checks=...)` — `/healthz` and `/readyz` |
62
65
  | `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) |
66
+ | `sse` | `sse_response(events)` — an `EventSourceResponse` that rejects forged frame fields, sends a `retry` frame first and ends a failed stream with one problem frame (`sse` extra) |
63
67
  | `app` | `FastApiApp(config)` — a `FastAPI` subclass with the standard adapters installed |
64
68
 
65
69
  ## Where it sits
@@ -22,6 +22,7 @@ router factory and an OpenAPI repair. **It makes no wire decision of its own.**
22
22
  | `dependencies` | `page_params`, `require_idempotency_key`, `require_if_match` |
23
23
  | `health` | `health_router(checks=...)` — `/healthz` and `/readyz` |
24
24
  | `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) |
25
+ | `sse` | `sse_response(events)` — an `EventSourceResponse` that rejects forged frame fields, sends a `retry` frame first and ends a failed stream with one problem frame (`sse` extra) |
25
26
  | `app` | `FastApiApp(config)` — a `FastAPI` subclass with the standard adapters installed |
26
27
 
27
28
  ## Where it sits
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "rn-forge-fastapi"
3
- version = "0.4.0"
3
+ version = "0.4.1"
4
4
  description = "FastAPI adapters over rn-forge-web"
5
5
  readme = "README.md"
6
6
  license = "MIT"
@@ -18,6 +18,7 @@ classifiers = [
18
18
  requires-python = ">=3.14"
19
19
  dependencies = [
20
20
  "rn-forge-auth>=0.1.0,<0.2",
21
+ "rn-forge-commons>=0.8.0,<0.10",
21
22
  "rn-forge-web[security]>=0.3.0,<0.4",
22
23
  "fastapi>=0.141.1",
23
24
  "opentelemetry-instrumentation-fastapi>=0.65b0",
@@ -29,7 +30,7 @@ email = "rohit.nn@gmail.com"
29
30
 
30
31
  [project.optional-dependencies]
31
32
  testing = [
32
- "assertpy>=1.1",
33
+ "assertpy>=2.35",
33
34
  "httpx>=0.28.1",
34
35
  "pytest>=9.1.1",
35
36
  ]
@@ -39,6 +40,7 @@ transfer = [
39
40
  "rn-forge-data>=0.1.1,<0.2",
40
41
  "python-multipart>=0.0.20",
41
42
  ]
43
+ sse = ["sse-starlette>=3.4.11"]
42
44
 
43
45
  [project.urls]
44
46
  Documentation = "https://rn-forge.github.io/pykit/packages/rn-forge-fastapi/latest/"
@@ -47,11 +49,19 @@ Changelog = "https://github.com/rn-forge/pykit/blob/main/packages/rn-forge-fasta
47
49
  Issues = "https://github.com/rn-forge/pykit/issues"
48
50
 
49
51
  [build-system]
50
- requires = ["uv_build>=0.11.28,<0.12.0"]
52
+ requires = ["uv_build>=0.13.7,<0.14.0"]
51
53
  build-backend = "uv_build"
52
54
 
55
+ [tool.pyright]
56
+ typeCheckingMode = "strict"
57
+ reportMissingTypeStubs = false
58
+ reportUnnecessaryTypeIgnoreComment = "error"
59
+ venv = ".venv"
60
+ venvPath = "../.."
61
+
53
62
  [tool.uv.build-backend]
54
63
  module-name = "rn_forge.fastapi"
64
+ source-exclude = ["**/.DS_Store"]
55
65
 
56
66
  [tool.uv.sources.rn-forge-auth]
57
67
  workspace = true
@@ -77,6 +87,7 @@ redis = [
77
87
  "rn_forge.auth.redis",
78
88
  "rn_forge.fastapi.auth.redis",
79
89
  ]
90
+ sse = ["rn_forge.fastapi.sse"]
80
91
  transfer = ["rn_forge.fastapi.transfer"]
81
92
 
82
93
  [tool.pytest.ini_options]
@@ -89,14 +100,14 @@ markers = [
89
100
 
90
101
  [dependency-groups]
91
102
  dev = [
92
- "assertpy>=1.1",
103
+ "assertpy>=2.35",
93
104
  "httpx>=0.28.1",
94
105
  "opentelemetry-sdk>=1.44",
95
106
  "pyright>=1.1.411",
96
107
  "pytest>=9.1.1",
97
108
  "pytest-cov>=7.1.0",
98
109
  "pytest-randomly>=4.1.0",
99
- "rn-forge-fastapi[oidc,redis,transfer]",
110
+ "rn-forge-fastapi[oidc,redis,sse,transfer]",
100
111
  "ruff>=0.15.21",
101
112
  "sqlalchemy>=2.0",
102
113
  ]
@@ -104,5 +115,5 @@ docs = [
104
115
  "mkdocs>=1.6.1",
105
116
  "mkdocs-material>=9.7.6",
106
117
  "mkdocstrings[python]>=1.0.6",
107
- "rn-forge-fastapi",
118
+ "rn-forge-fastapi[sse]",
108
119
  ]
@@ -0,0 +1,115 @@
1
+ [project]
2
+ name = "rn-forge-fastapi"
3
+ version = "0.4.1"
4
+ description = "FastAPI adapters over rn-forge-web"
5
+ readme = "README.md"
6
+ authors = [{ name = "Rohit Narayanan", email = "rohit.nn@gmail.com" }]
7
+ license = "MIT"
8
+ license-files = ["LICENSE"]
9
+ classifiers = [
10
+ "Development Status :: 3 - Alpha",
11
+ "Intended Audience :: Developers",
12
+ "Framework :: FastAPI",
13
+ "Operating System :: OS Independent",
14
+ "Programming Language :: Python :: 3",
15
+ "Programming Language :: Python :: 3 :: Only",
16
+ "Programming Language :: Python :: 3.14",
17
+ "Typing :: Typed",
18
+ ]
19
+ requires-python = ">=3.14"
20
+ # Internal requirements are version ranges (ADR-0004).
21
+ dependencies = [
22
+ "rn-forge-auth>=0.1.0,<0.2",
23
+ "rn-forge-commons>=0.8.0,<0.10",
24
+ # `[security]` is a hard requirement, not an extra: `FastApiApp` installs
25
+ # `SecurityHeadersMiddleware` by default (`AppConfig.security_headers`).
26
+ "rn-forge-web[security]>=0.3.0,<0.4",
27
+ # A hard dependency, not an extra: every module in this package is a FastAPI
28
+ # adapter. The floor is what resolved on 2026-09-12. pydantic arrives with it.
29
+ "fastapi>=0.141.1",
30
+ # `FastApiApp` instruments itself by default (`AppConfig.tracing`). Brings
31
+ # `opentelemetry-instrumentation`, which holds `TraceResponsePropagator`.
32
+ "opentelemetry-instrumentation-fastapi>=0.65b0",
33
+ ]
34
+
35
+ [project.optional-dependencies]
36
+ # httpx is what FastAPI's TestClient drives requests through.
37
+ testing = ["assertpy>=2.35", "httpx>=0.28.1", "pytest>=9.1.1"]
38
+ # JWKS bearer auth: `rn_forge.auth.oidc.OidcAuthenticator` passed to
39
+ # `bearer_auth()`. Nothing in this package imports it; the extra exists so a
40
+ # consumer asks for it by name rather than reaching into auth's extras.
41
+ oidc = ["rn-forge-auth[oidc]>=0.1.0,<0.2"]
42
+ # Redis-backed login sessions and transactions for `rn_forge.fastapi.auth`:
43
+ # `rn_forge.auth.redis`, and the CSRF token store `rn_forge.fastapi.auth.redis`.
44
+ redis = ["rn-forge-auth[redis]>=0.1.0,<0.2"]
45
+ # Tabular export and import: `rn_forge.fastapi.transfer`. Not imported by the
46
+ # package facade. `python-multipart` is what FastAPI's `UploadFile` needs.
47
+ transfer = ["rn-forge-data>=0.1.1,<0.2", "python-multipart>=0.0.20"]
48
+ # Server-sent events: `rn_forge.fastapi.sse`. Not imported by the package facade.
49
+ sse = ["sse-starlette>=3.4.11"]
50
+
51
+ [project.urls]
52
+ Documentation = "https://rn-forge.github.io/pykit/packages/rn-forge-fastapi/latest/"
53
+ Source = "https://github.com/rn-forge/pykit/tree/main/packages/rn-forge-fastapi"
54
+ Changelog = "https://github.com/rn-forge/pykit/blob/main/packages/rn-forge-fastapi/CHANGELOG.md"
55
+ Issues = "https://github.com/rn-forge/pykit/issues"
56
+
57
+ [build-system]
58
+ requires = ["uv_build>=0.13.7,<0.14.0"]
59
+ build-backend = "uv_build"
60
+
61
+ [tool.pyright]
62
+ typeCheckingMode = "strict"
63
+ reportMissingTypeStubs = false
64
+ reportUnnecessaryTypeIgnoreComment = "error"
65
+ venv = ".venv"
66
+ venvPath = "../.."
67
+
68
+ [tool.uv.build-backend]
69
+ module-name = "rn_forge.fastapi"
70
+ source-exclude = ["**/.DS_Store"]
71
+
72
+ [tool.uv.sources]
73
+ rn-forge-auth = { workspace = true }
74
+ rn-forge-commons = { workspace = true }
75
+ rn-forge-data = { workspace = true }
76
+ rn-forge-web = { workspace = true }
77
+ rn-forge-fastapi = { workspace = true }
78
+
79
+ [tool.workspace-ci.smoke]
80
+ modules = ["rn_forge.fastapi"]
81
+
82
+ [tool.workspace-ci.smoke.extras]
83
+ oidc = ["rn_forge.auth.oidc"]
84
+ redis = ["rn_forge.auth.redis", "rn_forge.fastapi.auth.redis"]
85
+ sse = ["rn_forge.fastapi.sse"]
86
+ transfer = ["rn_forge.fastapi.transfer"]
87
+
88
+ [tool.pytest.ini_options]
89
+ addopts = "-ra --import-mode=importlib -m 'not scaffold'"
90
+ markers = [
91
+ "unit: fast isolated tests",
92
+ "scaffold: installs built wheels into a scaffolded application (slow)",
93
+ "security_control: demonstrates the security control with the given rn_forge.auth.conformance case ID",
94
+ ]
95
+
96
+ [dependency-groups]
97
+ dev = [
98
+ "assertpy>=2.35",
99
+ "httpx>=0.28.1",
100
+ "opentelemetry-sdk>=1.44",
101
+ "pyright>=1.1.411",
102
+ "pytest>=9.1.1",
103
+ "pytest-cov>=7.1.0",
104
+ "pytest-randomly>=4.1.0",
105
+ "rn-forge-fastapi[oidc,redis,sse,transfer]",
106
+ "ruff>=0.15.21",
107
+ # Test-only: the ResourcePolicy tests scope real `select()` queries.
108
+ "sqlalchemy>=2.0",
109
+ ]
110
+ docs = [
111
+ "mkdocs>=1.6.1",
112
+ "mkdocs-material>=9.7.6",
113
+ "mkdocstrings[python]>=1.0.6",
114
+ "rn-forge-fastapi[sse]",
115
+ ]
@@ -47,7 +47,7 @@ from rn_forge.fastapi.merge_patch import (
47
47
  merge_patch_openapi,
48
48
  )
49
49
  from rn_forge.fastapi.openapi import operation_id
50
- from rn_forge.fastapi.problem import Log, register_problem_handlers
50
+ from rn_forge.fastapi.problem import Log, log_server_errors, register_problem_handlers
51
51
  from rn_forge.fastapi.read_mask import masked, read_mask_param
52
52
  from rn_forge.fastapi.soft_delete import (
53
53
  SoftDeleteState,
@@ -91,6 +91,7 @@ __all__ = [
91
91
  "deprecated",
92
92
  "health_router",
93
93
  "idempotent",
94
+ "log_server_errors",
94
95
  "masked",
95
96
  "merge_into",
96
97
  "merge_patch_body",
@@ -13,6 +13,7 @@ from typing import Any, cast
13
13
  from fastapi import FastAPI, Request
14
14
  from fastapi.exceptions import RequestValidationError
15
15
  from fastapi.responses import JSONResponse
16
+ from rn_forge.commons.logging import AppLogger
16
17
  from rn_forge.web import (
17
18
  NULL_FIELD_DETAIL,
18
19
  PROBLEM_MEDIA_TYPE,
@@ -27,12 +28,45 @@ from rn_forge.web import (
27
28
  )
28
29
  from starlette.exceptions import HTTPException as StarletteHTTPException
29
30
 
30
- __all__ = ["Log", "register_problem_handlers"]
31
+ __all__ = ["Log", "log_server_errors", "register_problem_handlers"]
31
32
 
32
33
  type Log = Callable[[str, Mapping[str, Any]], None]
33
34
  """The injected logging sink, called as ``log(event, context)``."""
34
35
 
35
36
 
37
+ def log_server_errors(logger: AppLogger | None = None) -> Log:
38
+ """Return a :data:`Log` that logs each 5xx problem at ``ERROR``, with its traceback.
39
+
40
+ The record carries the event, status, instance and trace id in its message
41
+ and the exception's traceback as ``exc_info``. Events other than
42
+ ``problem.server_error`` are ignored.
43
+
44
+ Args:
45
+ logger: Where to log. Defaults to
46
+ ``AppLogger.get_logger("rn_forge.fastapi.problem")``.
47
+
48
+ Example::
49
+
50
+ AppConfig(log=log_server_errors())
51
+ """
52
+ sink = logger or AppLogger.get_logger("rn_forge.fastapi.problem")
53
+
54
+ def log(event: str, context: Mapping[str, Any]) -> None:
55
+ if event != "problem.server_error":
56
+ return
57
+ exc = cast("BaseException", context["exc"])
58
+ sink.error(
59
+ "{} | status={} | instance={} | trace_id={}",
60
+ event,
61
+ context["status"],
62
+ context["instance"],
63
+ context["trace_id"],
64
+ exc_info=(type(exc), exc, exc.__traceback__),
65
+ )
66
+
67
+ return log
68
+
69
+
36
70
  def register_problem_handlers(
37
71
  app: FastAPI,
38
72
  *,
@@ -0,0 +1,133 @@
1
+ """Server-sent events over FastAPI.
2
+
3
+ Requires the ``sse`` extra. Not imported by :mod:`rn_forge.fastapi`.
4
+
5
+ Importing this module imports ``sse_starlette``, which replaces
6
+ ``uvicorn.Server.handle_exit`` for the whole process so that open streams are
7
+ drained on shutdown (``sse_starlette.sse.AppStatus``).
8
+
9
+ :func:`sse_response` returns an ``EventSourceResponse``; the media type, the
10
+ ``cache-control`` and ``x-accel-buffering`` headers, the heartbeat, disconnect
11
+ handling and graceful shutdown are its. This module adds validation of frame
12
+ fields, a terminal ``error`` frame, and a ``retry`` frame. It does not read
13
+ ``Last-Event-ID``: the route does, and passes it to the event source.
14
+ """
15
+
16
+ import json
17
+ from collections.abc import AsyncIterable, AsyncIterator, Mapping
18
+ from typing import Final
19
+
20
+ from rn_forge.fastapi.problem import Log
21
+ from rn_forge.web import (
22
+ ProblemRegistry,
23
+ WebError,
24
+ current_trace_id,
25
+ default_registry,
26
+ render_problem,
27
+ )
28
+ from sse_starlette import EventSourceResponse, ServerSentEvent
29
+
30
+ __all__ = ["DEFAULT_PING_SECONDS", "DEFAULT_RETRY_MS", "sse_response"]
31
+
32
+ DEFAULT_PING_SECONDS: Final = 15.0
33
+ """Seconds between heartbeat comments on an idle stream."""
34
+
35
+ DEFAULT_RETRY_MS: Final = 5_000
36
+ """Milliseconds a client waits before reconnecting a dropped stream."""
37
+
38
+ _ERROR_EVENT: Final = "error"
39
+ _FORBIDDEN: Final = "\r\n\x00"
40
+
41
+ # No `rn_forge.web.conformance` case: both framework drivers run every case with
42
+ # no skips, and `rn-forge-django` has no SSE adapter.
43
+
44
+
45
+ def sse_response(
46
+ events: AsyncIterable[ServerSentEvent],
47
+ *,
48
+ ping: float | None = DEFAULT_PING_SECONDS,
49
+ retry: int | None = DEFAULT_RETRY_MS,
50
+ registry: ProblemRegistry | None = None,
51
+ instance: str = "",
52
+ headers: Mapping[str, str] | None = None,
53
+ log: Log | None = None,
54
+ ) -> EventSourceResponse:
55
+ """Stream *events* as ``text/event-stream``.
56
+
57
+ Args:
58
+ events: The frames to send, in order.
59
+ ping: Seconds between heartbeat comments while the stream is idle.
60
+ ``None`` or ``0`` disables the heartbeat.
61
+ retry: Milliseconds a browser ``EventSource`` waits before reconnecting.
62
+ Sent as the first frame; ``None`` sends no such frame.
63
+ registry: Maps an exception escaping *events* to its problem. Defaults
64
+ to :func:`~rn_forge.web.default_registry`.
65
+ instance: The problem's ``instance`` member.
66
+ headers: Response headers. They are applied last, so each replaces a
67
+ default of the same name.
68
+ log: Called as ``log("problem.server_error", context)`` for a 5xx
69
+ problem, with the exception under ``"exc"``, as
70
+ :func:`~rn_forge.fastapi.problem.register_problem_handlers` does.
71
+
72
+ Returns:
73
+ The response. Each frame of *events* is sent as given, except that an
74
+ ``id`` or ``event`` containing ``\\r``, ``\\n`` or ``\\x00`` is rejected
75
+ with :class:`~rn_forge.web.WebError`. An exception escaping *events*,
76
+ that one included, ends the stream with a single frame whose ``event``
77
+ is ``error`` and whose ``data`` is the problem as JSON, as
78
+ ``registry`` renders it. Cancellation and client disconnect are not
79
+ errors and send nothing.
80
+
81
+ Raises:
82
+ ValueError: *retry* is not a non-negative integer, or *ping* is negative.
83
+ """
84
+ if retry is not None and (type(retry) is not int or retry < 0):
85
+ raise ValueError(f"retry must be a non-negative integer, got {retry!r}")
86
+ response = EventSourceResponse(
87
+ _frames(events, retry, registry or default_registry(), instance, log),
88
+ ping=0 if ping is None else ping,
89
+ )
90
+ # Applied after construction: the response overwrites some defaults itself.
91
+ for name, value in (headers or {}).items():
92
+ response.headers[name] = value
93
+ return response
94
+
95
+
96
+ async def _frames(
97
+ events: AsyncIterable[ServerSentEvent],
98
+ retry: int | None,
99
+ registry: ProblemRegistry,
100
+ instance: str,
101
+ log: Log | None,
102
+ ) -> AsyncIterator[ServerSentEvent]:
103
+ if retry is not None:
104
+ yield ServerSentEvent(retry=retry)
105
+ source = aiter(events)
106
+ try:
107
+ async for event in source:
108
+ _check(event.id, "id")
109
+ _check(event.event, "event")
110
+ yield event
111
+ except Exception as exc: # noqa: BLE001 # CancelledError is not an Exception
112
+ rendered = render_problem(registry, exc, instance=instance)
113
+ if rendered.status >= 500 and log is not None:
114
+ log(
115
+ "problem.server_error",
116
+ {
117
+ "exc": exc,
118
+ "status": rendered.status,
119
+ "instance": rendered.problem.instance,
120
+ "trace_id": current_trace_id(),
121
+ },
122
+ )
123
+ yield ServerSentEvent(event=_ERROR_EVENT, data=json.dumps(rendered.body))
124
+ finally:
125
+ # Closing this generator does not close the source it is iterating.
126
+ aclose = getattr(source, "aclose", None)
127
+ if aclose is not None:
128
+ await aclose()
129
+
130
+
131
+ def _check(value: str | None, field: str) -> None:
132
+ if value is not None and any(char in value for char in _FORBIDDEN):
133
+ raise WebError(f"SSE {field} contains a line break or NUL")
@@ -1,113 +0,0 @@
1
- [project]
2
- name = "rn-forge-fastapi"
3
- version = "0.4.0"
4
- description = "FastAPI adapters over rn-forge-web"
5
- readme = "README.md"
6
- authors = [{ name = "Rohit Narayanan", email = "rohit.nn@gmail.com" }]
7
- license = "MIT"
8
- license-files = ["LICENSE"]
9
- classifiers = [
10
- "Development Status :: 3 - Alpha",
11
- "Intended Audience :: Developers",
12
- "Framework :: FastAPI",
13
- "Operating System :: OS Independent",
14
- "Programming Language :: Python :: 3",
15
- "Programming Language :: Python :: 3 :: Only",
16
- "Programming Language :: Python :: 3.14",
17
- "Typing :: Typed",
18
- ]
19
- requires-python = ">=3.14"
20
- # Internal requirements are version ranges (ADR-0004).
21
- #
22
- # `rn-forge-commons` is not declared: nothing here imports it directly, and it
23
- # arrives through `rn-forge-web`.
24
- dependencies = [
25
- "rn-forge-auth>=0.1.0,<0.2",
26
- # `[security]` is a hard requirement, not an extra: `FastApiApp` installs
27
- # `SecurityHeadersMiddleware` by default (`AppConfig.security_headers`).
28
- "rn-forge-web[security]>=0.3.0,<0.4",
29
- # A hard dependency, not an extra: every module in this package is a FastAPI
30
- # adapter. The floor is what resolved on 2026-09-12. pydantic arrives with it.
31
- "fastapi>=0.141.1",
32
- # `FastApiApp` instruments itself by default (`AppConfig.tracing`). Brings
33
- # `opentelemetry-instrumentation`, which holds `TraceResponsePropagator`.
34
- "opentelemetry-instrumentation-fastapi>=0.65b0",
35
- ]
36
-
37
- [project.optional-dependencies]
38
- # httpx is what FastAPI's TestClient drives requests through.
39
- testing = ["assertpy>=1.1", "httpx>=0.28.1", "pytest>=9.1.1"]
40
- # JWKS bearer auth: `rn_forge.auth.oidc.OidcAuthenticator` passed to
41
- # `bearer_auth()`. Nothing in this package imports it; the extra exists so a
42
- # consumer asks for it by name rather than reaching into auth's extras.
43
- oidc = [
44
- "rn-forge-auth[oidc]>=0.1.0,<0.2",
45
- ]
46
- # Redis-backed login sessions and transactions for `rn_forge.fastapi.auth`:
47
- # `rn_forge.auth.redis`, and the CSRF token store `rn_forge.fastapi.auth.redis`.
48
- redis = [
49
- "rn-forge-auth[redis]>=0.1.0,<0.2",
50
- ]
51
- # Tabular export and import: `rn_forge.fastapi.transfer`. Not imported by the
52
- # package facade. `python-multipart` is what FastAPI's `UploadFile` needs.
53
- transfer = [
54
- "rn-forge-data>=0.1.1,<0.2",
55
- "python-multipart>=0.0.20",
56
- ]
57
-
58
- [project.urls]
59
- Documentation = "https://rn-forge.github.io/pykit/packages/rn-forge-fastapi/latest/"
60
- Source = "https://github.com/rn-forge/pykit/tree/main/packages/rn-forge-fastapi"
61
- Changelog = "https://github.com/rn-forge/pykit/blob/main/packages/rn-forge-fastapi/CHANGELOG.md"
62
- Issues = "https://github.com/rn-forge/pykit/issues"
63
-
64
- [build-system]
65
- requires = ["uv_build>=0.11.28,<0.12.0"]
66
- build-backend = "uv_build"
67
-
68
- [tool.uv.build-backend]
69
- module-name = "rn_forge.fastapi"
70
-
71
- [tool.uv.sources]
72
- rn-forge-auth = { workspace = true }
73
- rn-forge-commons = { workspace = true }
74
- rn-forge-data = { workspace = true }
75
- rn-forge-web = { workspace = true }
76
- rn-forge-fastapi = { workspace = true }
77
-
78
- [tool.workspace-ci.smoke]
79
- modules = ["rn_forge.fastapi"]
80
-
81
- [tool.workspace-ci.smoke.extras]
82
- oidc = ["rn_forge.auth.oidc"]
83
- redis = ["rn_forge.auth.redis", "rn_forge.fastapi.auth.redis"]
84
- transfer = ["rn_forge.fastapi.transfer"]
85
-
86
- [tool.pytest.ini_options]
87
- addopts = "-ra --import-mode=importlib -m 'not scaffold'"
88
- markers = [
89
- "unit: fast isolated tests",
90
- "scaffold: installs built wheels into a scaffolded application (slow)",
91
- "security_control: demonstrates the security control with the given rn_forge.auth.conformance case ID",
92
- ]
93
-
94
- [dependency-groups]
95
- dev = [
96
- "assertpy>=1.1",
97
- "httpx>=0.28.1",
98
- "opentelemetry-sdk>=1.44",
99
- "pyright>=1.1.411",
100
- "pytest>=9.1.1",
101
- "pytest-cov>=7.1.0",
102
- "pytest-randomly>=4.1.0",
103
- "rn-forge-fastapi[oidc,redis,transfer]",
104
- "ruff>=0.15.21",
105
- # Test-only: the ResourcePolicy tests scope real `select()` queries.
106
- "sqlalchemy>=2.0",
107
- ]
108
- docs = [
109
- "mkdocs>=1.6.1",
110
- "mkdocs-material>=9.7.6",
111
- "mkdocstrings[python]>=1.0.6",
112
- "rn-forge-fastapi",
113
- ]