voltwire-fastapi-db-txs 0.0.1__tar.gz

voltwire_fastapi_db_txs-0.0.1/.gitignore

@@ -0,0 +1,221 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#   Usually these files are written by a python script from a template
+#   before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+# Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+# uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+# poetry.lock
+# poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+# pdm.lock
+# pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+# pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# Redis
+*.rdb
+*.aof
+*.pid
+
+# RabbitMQ
+mnesia/
+rabbitmq/
+rabbitmq-data/
+
+# ActiveMQ
+activemq-data/
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#   JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#   be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#   and can be added to the global gitignore or merged into this file.  For a more nuclear
+#   option (not recommended) you can uncomment the following to ignore the entire idea folder.
+.idea/
+
+# Abstra
+#   Abstra is an AI-powered process automation framework.
+#   Ignore directories containing user credentials, local state, and settings.
+#   Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#   Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#   that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#   and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#   you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+# Temporary file for partial code execution
+tempCodeRunnerFile.py
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# Streamlit
+.streamlit/secrets.toml
+
+# Local tool state
+.omc/

voltwire_fastapi_db_txs-0.0.1/PKG-INFO

@@ -0,0 +1,169 @@
+Metadata-Version: 2.5
+Name: voltwire-fastapi-db-txs
+Version: 0.0.1
+Summary: FastAPI middleware and dependencies for request-scoped DB transaction management
+Author-email: Hermann Steidel <hsteidel.software@gmail.com>
+License-Expression: MIT
+Requires-Python: <4.0,>=3.13
+Requires-Dist: fastapi>=0.100.0
+Requires-Dist: starlette>=0.27.0
+Requires-Dist: voltwire-db-session>=0.0.0
+Description-Content-Type: text/markdown
+
+<img src="https://raw.githubusercontent.com/hsteidel/voltwire/main/assets/icons/fastapi-db-txs.svg" alt="" width="56" height="56" align="left">
+
+# voltwire-fastapi-db-txs
+
+FastAPI integration for `voltwire.db.session.TransactionContext` (from
+[voltwire-db-session](https://pypi.org/project/voltwire-db-session/)): request-scoped read-write and
+read-only database sessions with automatic commit/rollback, so route handlers never manage
+session lifecycle themselves.
+
+**No hidden global state, no DI framework coupling.** Every component here depends on
+*resolvers* — anything callable as `(request: Request) -> T` — for `TransactionContext`
+and the relevant session factory, rather than plain instances. This lets apps defer
+resolution to `request.app.state`, a DI container, or anywhere else, which matters for
+apps whose DB config isn't finalized until after this middleware/dependency is
+constructed (e.g. test harnesses that substitute a test database after module import
+time). Apps with one fixed instance for the process's lifetime just pass
+`lambda request: my_instance`.
+
+## Installation
+
+```bash
+pip install voltwire-fastapi-db-txs
+# or with Poetry:
+poetry add voltwire-fastapi-db-txs
+```
+
+## Wiring it into your app
+
+Your app should hold exactly one `TransactionContext` instance for the life of the process.
+The easiest way to get one — along with its matching `DatabaseSessionFactory`/
+`RODatabaseSessionFactory` — is `auto_configure_database`, from voltwire-db-session. If your DB
+config is ready before any route module gets imported, resolve it once and close over it:
+
+```python
+from voltwire.db.session import auto_configure_database, DatabaseAutoConfigurationProperties
+from voltwire.fastapi.db_txs import TransactionMiddleware, make_read_only_transaction
+
+db = auto_configure_database(db_settings, DatabaseAutoConfigurationProperties(build_read_replica=True))
+
+app.add_middleware(
+    TransactionMiddleware,
+    transaction_context=lambda request: db.transaction_context,
+    session_factory=lambda request: db.session_factory,
+)
+
+ReadOnlyTransaction = make_read_only_transaction(
+    lambda request: db.ro_session_factory,
+    lambda request: db.transaction_context,
+)
+```
+
+If your app defers DB config until later (e.g. it's set on `request.app.state` during
+startup, or substituted for a test database after these components are constructed),
+resolve from the request instead. If your app uses voltwire-di-core's
+`request.app.state.provide(cls)` convention, `AppStateResolver` implements the resolver
+protocol for you — pass the class you want resolved:
+
+```python
+from voltwire.fastapi.db_txs import AppStateResolver
+
+app.add_middleware(
+    TransactionMiddleware,
+    transaction_context=AppStateResolver(TransactionContext),
+    session_factory=AppStateResolver(DatabaseSessionFactory),
+)
+
+ReadOnlyTransaction = make_read_only_transaction(
+    AppStateResolver(RODatabaseSessionFactory),
+    AppStateResolver(TransactionContext),
+)
+```
+
+Apps not using that convention can pass any other callable of the same shape —
+`lambda request: request.app.state.my_custom_lookup(TransactionContext)`, a bound
+method, or a small resolver class of their own.
+
+If you'd rather assemble the session factories yourself (e.g. a custom
+`DatabaseSessionFactory` subclass) instead of using `auto_configure_database`, build each
+one directly — `TransactionMiddleware` and `make_read_only_transaction` only need
+resolvers returning a `TransactionContext` and the relevant factory, however you got them:
+
+```python
+from voltwire.db.session import TransactionContext, build_session_factory, build_ro_session_factory
+
+transaction_context = TransactionContext()
+session_factory = build_session_factory(db_settings)
+ro_session_factory = build_ro_session_factory(db_settings)
+```
+
+## Using it in routes
+
+Write routes (RW by default — the middleware opens a session for every request):
+
+```python
+@router.post("/users")
+def create_user(user_repo: UserRepositoryDI):
+    return user_repo.save(user)  # commits automatically on a 2xx/3xx response
+```
+
+Read-only routes (route or router-level, targets your read replica instead):
+
+```python
+@router.get("/users", dependencies=[ReadOnlyTransaction])
+def search_users(user_repo: UserRepositoryDI) -> list[UserResponse]:
+    ...
+```
+
+Wherever your app resolves a `Session` for its repositories, call
+`transaction_context.get_session()` — it returns the RO session if one is active for the
+current request, otherwise the RW session opened by the middleware, otherwise `None`.
+
+## Scripts and background tasks
+
+For code outside a FastAPI request (management scripts, workers), use the context managers
+directly instead of the middleware/dependency — either via the `db` object from
+`auto_configure_database`:
+
+```python
+with db.transaction():
+    user_repo = UserRepository(db.transaction_context.get_session())
+    user_repo.save(user)
+    # commits on success, rolls back on exception
+
+with db.read_transaction():
+    result = repo.find(...)
+```
+
+or, if you built the pieces yourself, the same methods on `TransactionContext` directly:
+
+```python
+with transaction_context.transaction(session_factory):
+    user_repo = UserRepository(transaction_context.get_session())
+    user_repo.save(user)
+
+with transaction_context.read_transaction(ro_session_factory):
+    result = repo.find(...)
+```
+
+If a single `DatabaseAutoConfiguration` is truly the only one in the process (no multiple
+databases, no multiple apps sharing the interpreter — e.g. in a pytest session), voltwire-db-session
+also has an opt-in `voltwire.db.session.default` module for a bare `with transaction():` — see
+voltwire-db-session's docs for when that tradeoff is worth it.
+
+## Why resolvers instead of instances?
+
+This library has no knowledge of any dependency-injection framework — `TransactionMiddleware`
+and `make_read_only_transaction` never construct or own a `TransactionContext`/session
+factory themselves. Depending on a resolver *protocol* instead of a plain instance means
+your app decides *when* resolution happens: eagerly (a lambda that just returns a value
+captured at wiring time) or lazily per request (e.g. `request.app.state.provide(...)`),
+without this library needing to know which. `AppStateResolver` is the one piece that
+assumes anything about `request.app.state` beyond FastAPI itself — it exists purely as a
+convenience for voltwire-di-core's convention; everything else in this library only ever calls
+the resolver, never reaches into `request.app.state` directly. The one thing that
+matters regardless of which resolver you use: share the *same* `TransactionContext`
+instance across the middleware, any read-only dependencies, and your app's own
+session-resolution code — its ContextVars are what tie a request's session together.

voltwire_fastapi_db_txs-0.0.1/README.md

@@ -0,0 +1,157 @@
+<img src="https://raw.githubusercontent.com/hsteidel/voltwire/main/assets/icons/fastapi-db-txs.svg" alt="" width="56" height="56" align="left">
+
+# voltwire-fastapi-db-txs
+
+FastAPI integration for `voltwire.db.session.TransactionContext` (from
+[voltwire-db-session](https://pypi.org/project/voltwire-db-session/)): request-scoped read-write and
+read-only database sessions with automatic commit/rollback, so route handlers never manage
+session lifecycle themselves.
+
+**No hidden global state, no DI framework coupling.** Every component here depends on
+*resolvers* — anything callable as `(request: Request) -> T` — for `TransactionContext`
+and the relevant session factory, rather than plain instances. This lets apps defer
+resolution to `request.app.state`, a DI container, or anywhere else, which matters for
+apps whose DB config isn't finalized until after this middleware/dependency is
+constructed (e.g. test harnesses that substitute a test database after module import
+time). Apps with one fixed instance for the process's lifetime just pass
+`lambda request: my_instance`.
+
+## Installation
+
+```bash
+pip install voltwire-fastapi-db-txs
+# or with Poetry:
+poetry add voltwire-fastapi-db-txs
+```
+
+## Wiring it into your app
+
+Your app should hold exactly one `TransactionContext` instance for the life of the process.
+The easiest way to get one — along with its matching `DatabaseSessionFactory`/
+`RODatabaseSessionFactory` — is `auto_configure_database`, from voltwire-db-session. If your DB
+config is ready before any route module gets imported, resolve it once and close over it:
+
+```python
+from voltwire.db.session import auto_configure_database, DatabaseAutoConfigurationProperties
+from voltwire.fastapi.db_txs import TransactionMiddleware, make_read_only_transaction
+
+db = auto_configure_database(db_settings, DatabaseAutoConfigurationProperties(build_read_replica=True))
+
+app.add_middleware(
+    TransactionMiddleware,
+    transaction_context=lambda request: db.transaction_context,
+    session_factory=lambda request: db.session_factory,
+)
+
+ReadOnlyTransaction = make_read_only_transaction(
+    lambda request: db.ro_session_factory,
+    lambda request: db.transaction_context,
+)
+```
+
+If your app defers DB config until later (e.g. it's set on `request.app.state` during
+startup, or substituted for a test database after these components are constructed),
+resolve from the request instead. If your app uses voltwire-di-core's
+`request.app.state.provide(cls)` convention, `AppStateResolver` implements the resolver
+protocol for you — pass the class you want resolved:
+
+```python
+from voltwire.fastapi.db_txs import AppStateResolver
+
+app.add_middleware(
+    TransactionMiddleware,
+    transaction_context=AppStateResolver(TransactionContext),
+    session_factory=AppStateResolver(DatabaseSessionFactory),
+)
+
+ReadOnlyTransaction = make_read_only_transaction(
+    AppStateResolver(RODatabaseSessionFactory),
+    AppStateResolver(TransactionContext),
+)
+```
+
+Apps not using that convention can pass any other callable of the same shape —
+`lambda request: request.app.state.my_custom_lookup(TransactionContext)`, a bound
+method, or a small resolver class of their own.
+
+If you'd rather assemble the session factories yourself (e.g. a custom
+`DatabaseSessionFactory` subclass) instead of using `auto_configure_database`, build each
+one directly — `TransactionMiddleware` and `make_read_only_transaction` only need
+resolvers returning a `TransactionContext` and the relevant factory, however you got them:
+
+```python
+from voltwire.db.session import TransactionContext, build_session_factory, build_ro_session_factory
+
+transaction_context = TransactionContext()
+session_factory = build_session_factory(db_settings)
+ro_session_factory = build_ro_session_factory(db_settings)
+```
+
+## Using it in routes
+
+Write routes (RW by default — the middleware opens a session for every request):
+
+```python
+@router.post("/users")
+def create_user(user_repo: UserRepositoryDI):
+    return user_repo.save(user)  # commits automatically on a 2xx/3xx response
+```
+
+Read-only routes (route or router-level, targets your read replica instead):
+
+```python
+@router.get("/users", dependencies=[ReadOnlyTransaction])
+def search_users(user_repo: UserRepositoryDI) -> list[UserResponse]:
+    ...
+```
+
+Wherever your app resolves a `Session` for its repositories, call
+`transaction_context.get_session()` — it returns the RO session if one is active for the
+current request, otherwise the RW session opened by the middleware, otherwise `None`.
+
+## Scripts and background tasks
+
+For code outside a FastAPI request (management scripts, workers), use the context managers
+directly instead of the middleware/dependency — either via the `db` object from
+`auto_configure_database`:
+
+```python
+with db.transaction():
+    user_repo = UserRepository(db.transaction_context.get_session())
+    user_repo.save(user)
+    # commits on success, rolls back on exception
+
+with db.read_transaction():
+    result = repo.find(...)
+```
+
+or, if you built the pieces yourself, the same methods on `TransactionContext` directly:
+
+```python
+with transaction_context.transaction(session_factory):
+    user_repo = UserRepository(transaction_context.get_session())
+    user_repo.save(user)
+
+with transaction_context.read_transaction(ro_session_factory):
+    result = repo.find(...)
+```
+
+If a single `DatabaseAutoConfiguration` is truly the only one in the process (no multiple
+databases, no multiple apps sharing the interpreter — e.g. in a pytest session), voltwire-db-session
+also has an opt-in `voltwire.db.session.default` module for a bare `with transaction():` — see
+voltwire-db-session's docs for when that tradeoff is worth it.
+
+## Why resolvers instead of instances?
+
+This library has no knowledge of any dependency-injection framework — `TransactionMiddleware`
+and `make_read_only_transaction` never construct or own a `TransactionContext`/session
+factory themselves. Depending on a resolver *protocol* instead of a plain instance means
+your app decides *when* resolution happens: eagerly (a lambda that just returns a value
+captured at wiring time) or lazily per request (e.g. `request.app.state.provide(...)`),
+without this library needing to know which. `AppStateResolver` is the one piece that
+assumes anything about `request.app.state` beyond FastAPI itself — it exists purely as a
+convenience for voltwire-di-core's convention; everything else in this library only ever calls
+the resolver, never reaches into `request.app.state` directly. The one thing that
+matters regardless of which resolver you use: share the *same* `TransactionContext`
+instance across the middleware, any read-only dependencies, and your app's own
+session-resolution code — its ContextVars are what tie a request's session together.

voltwire_fastapi_db_txs-0.0.1/pyproject.toml

@@ -0,0 +1,26 @@
+[project]
+name = "voltwire-fastapi-db-txs"
+version = "0.0.1"
+description = "FastAPI middleware and dependencies for request-scoped DB transaction management"
+authors = [{name = "Hermann Steidel", email = "hsteidel.software@gmail.com"}]
+license = "MIT"
+readme = "README.md"
+requires-python = ">=3.13,<4.0"
+dependencies = [
+    "fastapi>=0.100.0",
+    "starlette>=0.27.0",
+    "voltwire-db-session>=0.0.0",
+]
+
+[dependency-groups]
+dev = ["pytest>=8.0"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/voltwire"]
+
+[tool.uv.sources]
+voltwire-db-session = {workspace = true}

voltwire_fastapi_db_txs-0.0.1/src/voltwire/fastapi/db_txs/__init__.py

@@ -0,0 +1,19 @@
+from voltwire.fastapi.db_txs.dependencies import make_read_only_transaction
+from voltwire.fastapi.db_txs.middleware import TransactionMiddleware
+from voltwire.fastapi.db_txs.resolvers import (
+    AppStateResolver,
+    RODatabaseSessionFactoryResolver,
+    SessionFactoryResolver,
+    TransactionContextResolver,
+)
+
+__version__ = "0.0.0"
+
+__all__ = [
+    "TransactionMiddleware",
+    "make_read_only_transaction",
+    "AppStateResolver",
+    "RODatabaseSessionFactoryResolver",
+    "SessionFactoryResolver",
+    "TransactionContextResolver",
+]

voltwire_fastapi_db_txs-0.0.1/src/voltwire/fastapi/db_txs/dependencies.py

@@ -0,0 +1,66 @@
+"""
+Read-Replica FastAPI Dependency Builder
+
+FastAPI's ``Depends()`` callables can't take extra constructor arguments, so the
+read-only dependency is produced by a builder function instead: call
+``make_read_only_transaction`` once at app-wiring time with resolver callables for
+your ``RODatabaseSessionFactory`` and the same ``TransactionContext`` instance used by
+``TransactionMiddleware``, then bind the result to a name in your app::
+
+    ReadOnlyTransaction = make_read_only_transaction(
+        lambda request: my_ro_session_factory,
+        lambda request: my_transaction_context,
+    )
+
+    @router.get("", dependencies=[ReadOnlyTransaction])
+    def search_items(service: MyServiceDI) -> MySearchResponse:
+        ...
+
+Both resolvers are invoked per request with the ``Request`` rather than passed as
+plain instances — this lets apps defer resolution to whatever they've stashed on
+``request.app.state`` (or a DI container), which matters for apps whose settings/
+session factories aren't finalized until after this dependency is built (e.g. test
+harnesses that substitute a test database via ``request.app.state`` after module
+import time). Apps with a single fixed instance for the lifetime of the process can
+pass ``lambda request: my_instance``.
+"""
+
+from collections.abc import AsyncGenerator
+
+from fastapi import Depends, Request
+from fastapi.params import Depends as DependsType
+
+from voltwire.fastapi.db_txs.resolvers import RODatabaseSessionFactoryResolver, TransactionContextResolver
+
+
+def make_read_only_transaction(
+    ro_session_factory: RODatabaseSessionFactoryResolver,
+    transaction_context: TransactionContextResolver,
+) -> DependsType:
+    """
+    Build a FastAPI dependency that opens a read-only replica session for the
+    duration of a request.
+
+    Keeps the RO session open for the full duration of the request so that all
+    downstream session resolution within the route uses the replica.
+
+    Must be async so the ContextVar is set and reset within the async event-loop
+    context — mirroring ``TransactionMiddleware``. Sync generator dependencies run in
+    a thread pool where anyio snapshots the context, causing ContextVar tokens to be
+    bound to the thread's copied Context; the token would then be invalid when FastAPI
+    runs generator cleanup in a different context snapshot. As an async generator,
+    ``set()``/``reset()`` both execute in the same async Context, and the sync route
+    thread inherits the session via the context copy.
+    """
+
+    async def build_read_replica_context(request: Request) -> AsyncGenerator[None, None]:
+        session = ro_session_factory(request).get_session()
+        context = transaction_context(request)
+        token = context.set_ro_session(session)
+        try:
+            yield
+        finally:
+            context.reset_ro_session(token)
+            session.close()
+
+    return Depends(build_read_replica_context)

voltwire_fastapi_db_txs-0.0.1/src/voltwire/fastapi/db_txs/middleware.py

@@ -0,0 +1,98 @@
+"""
+FastAPI Transaction Middleware
+
+Provides transparent transaction management for web requests with automatic
+commit/rollback behavior, built on top of ``voltwire.db.session.TransactionContext``.
+
+This middleware:
+- Opens a read-write session for each HTTP request
+- Commits the transaction on successful response (2xx/3xx status codes)
+- Rolls back the transaction on exceptions or error status codes
+- Always closes the session for proper cleanup
+- Works across FastAPI's thread boundaries via the injected ``TransactionContext``
+
+Usage::
+
+    app.add_middleware(
+        TransactionMiddleware,
+        transaction_context=lambda request: my_transaction_context,
+        session_factory=lambda request: my_session_factory,
+    )
+
+Both ``transaction_context`` and ``session_factory`` are resolver callables invoked
+per request with the ``Request``, not plain instances — this lets apps defer
+resolution to whatever they've stashed on ``request.app.state`` (or a DI container),
+which matters for apps whose settings/session factories aren't finalized until after
+this middleware is constructed (e.g. test harnesses that substitute a test database
+via ``request.app.state`` after module import time). Apps with a single fixed
+instance for the lifetime of the process can pass ``lambda request: my_instance``.
+"""
+
+from collections.abc import Callable
+
+from starlette.middleware.base import BaseHTTPMiddleware
+from starlette.requests import Request
+from starlette.responses import Response
+
+from voltwire.fastapi.db_txs.resolvers import SessionFactoryResolver, TransactionContextResolver
+
+
+class TransactionMiddleware(BaseHTTPMiddleware):
+    """
+    Middleware that provides transparent transaction management for HTTP requests.
+
+    Automatically manages database session lifecycle:
+    - Opens a session before request processing
+    - Commits on successful completion (2xx/3xx status codes)
+    - Rolls back on exceptions or error status codes
+    - Always cleans up resources
+
+    ``transaction_context`` and ``session_factory`` are resolver callables — invoked
+    with the current ``Request`` on every request — supplied by the caller. This
+    middleware has no knowledge of any DI framework or app-level session registry.
+    The resolved ``TransactionContext`` should be the same instance used by any
+    read-only dependency built with ``make_read_only_transaction`` and by the app's
+    own session-resolution code, since the ContextVars it owns are what tie a
+    request's session together across dependencies and route handlers.
+    """
+
+    def __init__(
+        self,
+        app,
+        transaction_context: TransactionContextResolver,
+        session_factory: SessionFactoryResolver,
+    ):
+        super().__init__(app)
+        self._resolve_transaction_context = transaction_context
+        self._resolve_session_factory = session_factory
+
+    async def dispatch(self, request: Request, call_next: Callable) -> Response:
+        """
+        Handle HTTP request with automatic transaction management.
+
+        Opens the RW session eagerly in the async context so that all thread-pool
+        workers dispatched by ``call_next`` inherit the same session via context copy.
+        Read-only routes shadow it via a dependency built from the same
+        ``transaction_context``.
+        """
+        transaction_context = self._resolve_transaction_context(request)
+        session_factory = self._resolve_session_factory(request)
+
+        session = session_factory.get_session()
+        transaction_context.set_rw_session(session)
+        try:
+            response = await call_next(request)
+
+            if 200 <= response.status_code < 399:
+                transaction_context.commit()
+            else:
+                transaction_context.rollback()
+
+            return response
+
+        except Exception:
+            transaction_context.rollback()
+            raise
+
+        finally:
+            transaction_context.close()

voltwire_fastapi_db_txs-0.0.1/src/voltwire/fastapi/db_txs/resolvers.py

@@ -0,0 +1,64 @@
+"""
+Resolvers
+
+``TransactionMiddleware`` and ``make_read_only_transaction`` depend on resolver
+*protocols* — anything callable with ``(request: Request) -> T`` — rather than plain
+instances, so resolution can be deferred to whatever the app has stashed on
+``request.app.state`` (or elsewhere), instead of requiring a value fixed at wiring
+time. A plain function or lambda satisfies the protocol structurally; no subclassing
+required::
+
+    TransactionMiddleware(
+        app,
+        transaction_context=lambda request: my_transaction_context,
+        session_factory=lambda request: my_session_factory,
+    )
+
+For apps using voltwire-di-core's ``request.app.state.provide(cls)`` convention,
+``AppStateResolver`` implements the protocol for you — pass the class you want
+resolved::
+
+    TransactionMiddleware(
+        app,
+        transaction_context=AppStateResolver(TransactionContext),
+        session_factory=AppStateResolver(DatabaseSessionFactory),
+    )
+
+``AppStateResolver`` is the only piece of this library that assumes anything about
+``request.app.state`` beyond FastAPI itself — apps not using that convention should
+pass a plain callable instead.
+"""
+
+from typing import Generic, Protocol, TypeVar
+
+from voltwire.db.session import DatabaseSessionFactory, RODatabaseSessionFactory, TransactionContext
+from starlette.requests import Request
+
+T = TypeVar("T")
+
+
+class TransactionContextResolver(Protocol):
+    def __call__(self, request: Request) -> TransactionContext: ...
+
+
+class SessionFactoryResolver(Protocol):
+    def __call__(self, request: Request) -> DatabaseSessionFactory: ...
+
+
+class RODatabaseSessionFactoryResolver(Protocol):
+    def __call__(self, request: Request) -> RODatabaseSessionFactory: ...
+
+
+class AppStateResolver(Generic[T]):
+    """
+    Resolves ``cls`` via ``request.app.state.provide(cls)`` — the voltwire-di-core
+    convention for reaching a request's DI container. Satisfies
+    ``TransactionContextResolver``/``SessionFactoryResolver``/
+    ``RODatabaseSessionFactoryResolver`` for whichever ``cls`` is passed.
+    """
+
+    def __init__(self, cls: type[T]) -> None:
+        self._cls = cls
+
+    def __call__(self, request: Request) -> T:
+        return request.app.state.provide(self._cls)

voltwire_fastapi_db_txs-0.0.1/tests/test_dependencies.py

@@ -0,0 +1,76 @@
+import asyncio
+from unittest.mock import MagicMock
+
+from voltwire.db.session import RODatabaseSessionFactory, TransactionContext
+from voltwire.fastapi.db_txs import make_read_only_transaction
+
+
+def _ro_factory(session: MagicMock) -> MagicMock:
+    factory = MagicMock(spec=RODatabaseSessionFactory)
+    factory.get_session.return_value = session
+    return factory
+
+
+async def _drain(dependency) -> None:
+    """Fully exercise a FastAPI Depends()-wrapped async generator, like FastAPI would."""
+    agen = dependency.dependency(MagicMock())
+    await agen.__anext__()
+    try:
+        await agen.__anext__()
+    except StopAsyncIteration:
+        pass
+
+
+def test_ro_session_active_during_yield():
+    context = TransactionContext()
+    session = MagicMock()
+    ro_transaction = make_read_only_transaction(lambda _request: _ro_factory(session), lambda _request: context)
+
+    seen = {}
+
+    async def run():
+        agen = ro_transaction.dependency(MagicMock())
+        await agen.__anext__()
+        seen["session"] = context.get_session()
+        try:
+            await agen.__anext__()
+        except StopAsyncIteration:
+            pass
+
+    asyncio.run(run())
+
+    assert seen["session"] is session
+
+
+def test_session_closed_and_context_cleared_after():
+    context = TransactionContext()
+    session = MagicMock()
+    ro_transaction = make_read_only_transaction(lambda _request: _ro_factory(session), lambda _request: context)
+
+    asyncio.run(_drain(ro_transaction))
+
+    session.close.assert_called_once()
+    assert context.get_ro_session() is None
+
+
+def test_never_commits():
+    context = TransactionContext()
+    session = MagicMock()
+    ro_transaction = make_read_only_transaction(lambda _request: _ro_factory(session), lambda _request: context)
+
+    asyncio.run(_drain(ro_transaction))
+
+    session.commit.assert_not_called()
+
+
+def test_restores_previous_ro_session_after_completion():
+    context = TransactionContext()
+    outer_session = MagicMock()
+    context.set_ro_session(outer_session)
+
+    inner_session = MagicMock()
+    ro_transaction = make_read_only_transaction(lambda _request: _ro_factory(inner_session), lambda _request: context)
+
+    asyncio.run(_drain(ro_transaction))
+
+    assert context.get_ro_session() is outer_session

voltwire_fastapi_db_txs-0.0.1/tests/test_middleware.py

@@ -0,0 +1,92 @@
+import asyncio
+from unittest.mock import AsyncMock, MagicMock
+
+import pytest
+
+from voltwire.db.session import DatabaseSessionFactory, TransactionContext
+from voltwire.fastapi.db_txs import TransactionMiddleware
+
+
+def _build_middleware(transaction_context: TransactionContext, session: MagicMock) -> TransactionMiddleware:
+    session_factory = MagicMock(spec=DatabaseSessionFactory)
+    session_factory.get_session.return_value = session
+    app = MagicMock()
+    return TransactionMiddleware(
+        app,
+        transaction_context=lambda _request: transaction_context,
+        session_factory=lambda _request: session_factory,
+    )
+
+
+def _response(status_code: int) -> MagicMock:
+    response = MagicMock()
+    response.status_code = status_code
+    return response
+
+
+def test_commits_on_success_status():
+    context = TransactionContext()
+    session = MagicMock()
+    middleware = _build_middleware(context, session)
+    call_next = AsyncMock(return_value=_response(200))
+
+    result = asyncio.run(middleware.dispatch(MagicMock(), call_next))
+
+    assert result.status_code == 200
+    session.commit.assert_called_once()
+    session.rollback.assert_not_called()
+    session.close.assert_called_once()
+
+
+def test_rolls_back_on_error_status():
+    context = TransactionContext()
+    session = MagicMock()
+    middleware = _build_middleware(context, session)
+    call_next = AsyncMock(return_value=_response(500))
+
+    asyncio.run(middleware.dispatch(MagicMock(), call_next))
+
+    session.rollback.assert_called_once()
+    session.commit.assert_not_called()
+    session.close.assert_called_once()
+
+
+def test_rolls_back_and_reraises_on_exception():
+    context = TransactionContext()
+    session = MagicMock()
+    middleware = _build_middleware(context, session)
+    call_next = AsyncMock(side_effect=ValueError("boom"))
+
+    with pytest.raises(ValueError, match="boom"):
+        asyncio.run(middleware.dispatch(MagicMock(), call_next))
+
+    session.rollback.assert_called_once()
+    session.commit.assert_not_called()
+    session.close.assert_called_once()
+
+
+def test_session_visible_via_transaction_context_during_request():
+    context = TransactionContext()
+    session = MagicMock()
+    middleware = _build_middleware(context, session)
+
+    seen = {}
+
+    async def call_next(_request):
+        seen["session"] = context.get_session()
+        return _response(200)
+
+    asyncio.run(middleware.dispatch(MagicMock(), call_next))
+
+    assert seen["session"] is session
+
+
+def test_session_cleared_after_request():
+    context = TransactionContext()
+    session = MagicMock()
+    middleware = _build_middleware(context, session)
+    call_next = AsyncMock(return_value=_response(200))
+
+    asyncio.run(middleware.dispatch(MagicMock(), call_next))
+
+    assert context.get_session() is None

voltwire_fastapi_db_txs-0.0.1/tests/test_resolvers.py

@@ -0,0 +1,26 @@
+from unittest.mock import MagicMock
+
+from voltwire.db.session import TransactionContext
+from voltwire.fastapi.db_txs import AppStateResolver
+
+
+class TestAppStateResolver:
+    def test_calls_provide_with_the_given_class(self):
+        resolved = TransactionContext()
+        request = MagicMock()
+        request.app.state.provide.return_value = resolved
+
+        resolver = AppStateResolver(TransactionContext)
+        result = resolver(request)
+
+        request.app.state.provide.assert_called_once_with(TransactionContext)
+        assert result is resolved
+
+    def test_re_resolves_on_every_call(self):
+        request = MagicMock()
+        resolver = AppStateResolver(TransactionContext)
+
+        resolver(request)
+        resolver(request)
+
+        assert request.app.state.provide.call_count == 2