bedrock-fastapi 0.1.0__tar.gz

bedrock_fastapi-0.1.0/PKG-INFO

@@ -0,0 +1,47 @@
+Metadata-Version: 2.4
+Name: bedrock-fastapi
+Version: 0.1.0
+Summary: FastAPI integration for Bedrock: request DI scopes, request-bound database sessions, and BedrockExc responses.
+Keywords: bedrock,fastapi,starlette,asgi,middleware
+Author: maacck
+Author-email: maacck <c.mai@madainchina.com>
+License-Expression: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Dist: anyio>=3.4.0
+Requires-Dist: bedrock-core>=0.3.1
+Requires-Dist: starlette>=0.40.0
+Requires-Python: >=3.12
+Project-URL: Bug Tracker, https://github.com/maacck/bedrock-py/issues
+Project-URL: Documentation, https://bedrock-py.com
+Project-URL: Homepage, https://bedrock-py.com
+Project-URL: Repository, https://github.com/maacck/bedrock-py
+Description-Content-Type: text/markdown
+
+# bedrock-fastapi
+
+FastAPI integration for [Bedrock](https://bedrock-py.com). Your application creates and owns the FastAPI app;
+this package supplies pieces you add as needed:
+
+- `RequestScopeMiddleware`: one Bedrock DI scope per request.
+- `DbSessionMiddleware` / `AsyncDbSessionMiddleware`: each request runs inside `db.session_scope()` /
+  `db.asession_scope()`. Services commit; uncommitted work is rolled back when the request ends.
+- `bedrock_exception_handler(status_codes)`: answers mapped `BedrockExc` subclasses with `{"detail": ...}`.
+
+```python
+from bedrock.exc import BedrockExc
+from bedrock_fastapi import AsyncDbSessionMiddleware, RequestScopeMiddleware, bedrock_exception_handler
+
+app.add_middleware(AsyncDbSessionMiddleware)
+app.add_middleware(RequestScopeMiddleware)
+app.add_exception_handler(BedrockExc, bedrock_exception_handler({ItemNotFound: 404}))
+```
+
+See the FastAPI integration docs at https://bedrock-py.com/docs/integrations/fastapi for installation, the
+transaction convention, and a complete example.

bedrock_fastapi-0.1.0/README.md

@@ -0,0 +1,21 @@
+# bedrock-fastapi
+
+FastAPI integration for [Bedrock](https://bedrock-py.com). Your application creates and owns the FastAPI app;
+this package supplies pieces you add as needed:
+
+- `RequestScopeMiddleware`: one Bedrock DI scope per request.
+- `DbSessionMiddleware` / `AsyncDbSessionMiddleware`: each request runs inside `db.session_scope()` /
+  `db.asession_scope()`. Services commit; uncommitted work is rolled back when the request ends.
+- `bedrock_exception_handler(status_codes)`: answers mapped `BedrockExc` subclasses with `{"detail": ...}`.
+
+```python
+from bedrock.exc import BedrockExc
+from bedrock_fastapi import AsyncDbSessionMiddleware, RequestScopeMiddleware, bedrock_exception_handler
+
+app.add_middleware(AsyncDbSessionMiddleware)
+app.add_middleware(RequestScopeMiddleware)
+app.add_exception_handler(BedrockExc, bedrock_exception_handler({ItemNotFound: 404}))
+```
+
+See the FastAPI integration docs at https://bedrock-py.com/docs/integrations/fastapi for installation, the
+transaction convention, and a complete example.

bedrock_fastapi-0.1.0/pyproject.toml

@@ -0,0 +1,48 @@
+[project]
+name = "bedrock-fastapi"
+version = "0.1.0"
+description = "FastAPI integration for Bedrock: request DI scopes, request-bound database sessions, and BedrockExc responses."
+readme = "README.md"
+license = "MIT"
+authors = [
+    { name = "maacck", email = "c.mai@madainchina.com" }
+]
+keywords = ["bedrock", "fastapi", "starlette", "asgi", "middleware"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Framework :: FastAPI",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Typing :: Typed",
+]
+requires-python = ">=3.12"
+dependencies = [
+    "anyio>=3.4.0",
+    "bedrock-core>=0.3.1",
+    "starlette>=0.40.0",
+]
+
+[project.urls]
+Homepage = "https://bedrock-py.com"
+Repository = "https://github.com/maacck/bedrock-py"
+Documentation = "https://bedrock-py.com"
+"Bug Tracker" = "https://github.com/maacck/bedrock-py/issues"
+
+[build-system]
+requires = ["uv_build>=0.8.15,<0.9.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-root = "src"
+module-name = "bedrock_fastapi"
+
+[dependency-groups]
+dev = [
+    "pytest>=8.4.2",
+    "fastapi>=0.115.0",
+    "httpx2>=0.1.0",
+    "aiosqlite>=0.20.0",
+]

bedrock_fastapi-0.1.0/src/bedrock_fastapi/__init__.py

@@ -0,0 +1,14 @@
+"""FastAPI integration for Bedrock.
+
+The host application creates and owns its FastAPI app. Add only the pieces it needs.
+"""
+
+from .exceptions import bedrock_exception_handler
+from .middleware import AsyncDbSessionMiddleware, DbSessionMiddleware, RequestScopeMiddleware
+
+__all__ = [
+    "AsyncDbSessionMiddleware",
+    "DbSessionMiddleware",
+    "RequestScopeMiddleware",
+    "bedrock_exception_handler",
+]

bedrock_fastapi-0.1.0/src/bedrock_fastapi/exceptions.py

@@ -0,0 +1,45 @@
+"""Translate Bedrock exceptions into HTTP responses."""
+
+from collections.abc import Awaitable, Callable, Mapping
+
+from bedrock.exc import BedrockExc
+from starlette.requests import Request
+from starlette.responses import JSONResponse, Response
+
+
+def bedrock_exception_handler(
+    status_codes: Mapping[type[BedrockExc], int],
+) -> Callable[[Request, Exception], Awaitable[Response]]:
+    """Build an exception handler that answers mapped Bedrock exceptions with ``{"detail": exc.detail}``.
+
+    The lookup walks the raised exception's MRO, so mapping a module's base exception covers its subclasses
+    and the most specific mapping wins. An unmapped exception is re-raised: the server-error middleware logs
+    it and returns a generic 500 without exposing ``detail``, because ``BedrockExc`` is also the base of
+    runtime errors such as ``ImproperlyConfigured``. WebSocket connections are never answered: an exception there
+    is re-raised, because an HTTP response cannot be sent once the socket is accepted.
+
+    Example::
+
+        app.add_exception_handler(
+            BedrockExc,
+            bedrock_exception_handler(
+                {ItemNotFound: 404, ItemConflict: 409}
+            ),
+        )
+
+    Args:
+        status_codes: HTTP status code per exception class.
+
+    Returns:
+        An async exception handler for ``app.add_exception_handler``.
+    """
+
+    async def handle(request: Request, exc: Exception) -> Response:
+        if request.scope["type"] == "http" and isinstance(exc, BedrockExc):
+            matches = [cls for cls in status_codes if isinstance(exc, cls)]
+            if matches:
+                most_specific = min(matches, key=type(exc).__mro__.index)
+                return JSONResponse({"detail": exc.detail}, status_code=status_codes[most_specific])
+        raise exc
+
+    return handle

bedrock_fastapi-0.1.0/src/bedrock_fastapi/middleware.py

@@ -0,0 +1,126 @@
+"""Pure ASGI middleware that give each request its own Bedrock DI scope and database sessions.
+
+The middleware enter and leave request state in the request's own context. FastAPI runs sync (``def``)
+dependencies and endpoints in worker threads with copied contexts, so state entered there cannot be reset
+or cleaned up reliably at the end of the request.
+"""
+
+from anyio import CancelScope
+from bedrock.database import db
+from bedrock.di import container
+from starlette.concurrency import run_in_threadpool
+from starlette.types import ASGIApp, Receive, Scope, Send
+
+_REQUEST_TYPES = frozenset({"http", "websocket"})
+
+
+class RequestScopeMiddleware:
+    """Run each HTTP or WebSocket connection inside ``container.scope("request")``.
+
+    ``SCOPED`` services resolved while the connection is handled share one instance, and their ``close()``
+    runs when it ends. Lifespan events pass through.
+    """
+
+    def __init__(self, app: ASGIApp) -> None:
+        """Wrap the downstream application.
+
+        Args:
+            app: The downstream ASGI application.
+        """
+        self.app = app
+
+    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
+        """Handle one ASGI connection.
+
+        Args:
+            scope: The ASGI connection scope.
+            receive: The ASGI receive channel.
+            send: The ASGI send channel.
+        """
+        if scope["type"] not in _REQUEST_TYPES:
+            await self.app(scope, receive, send)
+            return
+        with container.scope("request"):
+            await self.app(scope, receive, send)
+
+
+class DbSessionMiddleware:
+    """Run each HTTP request inside ``db.session_scope()`` without committing on its behalf.
+
+    Services work in ``db.session`` and commit, as they do outside HTTP. Whatever is still uncommitted when the
+    request ends, including work done by background tasks, is rolled back, so a write nobody commits is lost
+    while the response may still be a success.
+
+    Because a session is already bound, ``db.session_scope()`` raises ``RuntimeError`` inside a request; use
+    ``db.independent_session()`` for side transactions. WebSocket and lifespan events pass through.
+    """
+
+    def __init__(self, app: ASGIApp) -> None:
+        """Wrap the downstream application.
+
+        Args:
+            app: The downstream ASGI application.
+        """
+        self.app = app
+
+    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
+        """Handle one ASGI connection.
+
+        Args:
+            scope: The ASGI connection scope.
+            receive: The ASGI receive channel.
+            send: The ASGI send channel.
+
+        Raises:
+            DatabaseNotConfiguredError: When ``db.init()`` has not been called.
+        """
+        if scope["type"] != "http":
+            await self.app(scope, receive, send)
+            return
+        with db.session_scope() as session:
+            try:
+                await self.app(scope, receive, send)
+            finally:
+                # Discard uncommitted work so the scope's own commit has nothing left. Shielded so a cancelled
+                # request still returns its connection, and in a worker thread because the rollback is blocking I/O.
+                with CancelScope(shield=True):
+                    await run_in_threadpool(session.rollback)
+
+
+class AsyncDbSessionMiddleware:
+    """Run each HTTP request inside ``db.asession_scope()`` without committing on its behalf.
+
+    Same contract as :class:`DbSessionMiddleware`: services commit with ``await db.asession.commit()``,
+    uncommitted work is rolled back when the request ends, and ``db.asession_scope()`` raises ``RuntimeError``
+    inside a request (use ``db.aindependent_session()``). The sync and async sessions use separate context
+    variables, so both middleware can be installed together; each has its own transaction.
+    """
+
+    def __init__(self, app: ASGIApp) -> None:
+        """Wrap the downstream application.
+
+        Args:
+            app: The downstream ASGI application.
+        """
+        self.app = app
+
+    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
+        """Handle one ASGI connection.
+
+        Args:
+            scope: The ASGI connection scope.
+            receive: The ASGI receive channel.
+            send: The ASGI send channel.
+
+        Raises:
+            DatabaseNotConfiguredError: When ``db.init()`` has not been called.
+        """
+        if scope["type"] != "http":
+            await self.app(scope, receive, send)
+            return
+        async with db.asession_scope() as session:
+            try:
+                await self.app(scope, receive, send)
+            finally:
+                with CancelScope(shield=True):
+                    await session.rollback()