feat: use async_lru for caching

docs/examples/pagination-search.md

@@ -130,7 +130,7 @@ Pass `next_cursor` as the `cursor` query parameter on the next request to advanc
 
 !!! info "Added in `v2.3.0`"
 
-[`paginate()`](../module/crud.md#unified-endpoint-both-strategies) lets a single endpoint support both strategies via a `pagination_type` query parameter. The `pagination_type` field in the response acts as a discriminator for frontend tooling.
+[`paginate()`](../module/crud.md#unified-paginate--both-strategies-on-one-endpoint) lets a single endpoint support both strategies via a `pagination_type` query parameter. The `pagination_type` field in the response acts as a discriminator for frontend tooling.
 
 ```python title="routes.py:61:79"
 --8<-- "docs_src/examples/pagination_search/routes.py:61:79"

docs/migration/v4.md

@@ -1,40 +0,0 @@
-# Migrating to v4.0
-
-This page covers every breaking change introduced in **v4.0** and the steps required to update your code.
-
----
-
-## Database
-
-### `lock_tables` now takes a `session_maker` instead of a `session`
-
-The first argument of `lock_tables` changed from an `AsyncSession` instance to an `async_sessionmaker`.
-The function creates and manages its own **dedicated session** internally, yielding it to the caller.
-
-=== "Before (`v3`)"
-
-    ```python
-    from fastapi_toolsets.db import lock_tables, LockMode
-
-    async with lock_tables(session=session, tables=[User, Account]):
-        user = await UserCrud.get(session, [User.id == 1])
-        user.balance += 100
-
-    # With a custom lock mode
-    async with lock_tables(session, [Order], mode=LockMode.EXCLUSIVE):
-        await process_order(session, order_id)
-    ```
-
-=== "Now (`v4`)"
-
-    ```python
-    from fastapi_toolsets.db import lock_tables, LockMode
-
-    async with lock_tables(session_maker=session_maker, tables=[User, Account]) as session:
-        user = await UserCrud.get(session, [User.id == 1])
-        user.balance += 100
-
-    # With a custom lock mode
-    async with lock_tables(session_maker, [Order], mode=LockMode.EXCLUSIVE) as session:
-        await process_order(session, order_id)
-    ```

docs/module/db.md

@@ -57,12 +57,12 @@ async def create_user_with_role(session=session):
 
 ## Table locking
 
-[`lock_tables`](../reference/db.md#fastapi_toolsets.db.lock_tables) acquires PostgreSQL table-level locks before executing critical sections. It opens a **dedicated session** internally and yields it to the caller, so the lock is guaranteed to be released when the context exits:
+[`lock_tables`](../reference/db.md#fastapi_toolsets.db.lock_tables) acquires PostgreSQL table-level locks before executing critical sections:
 
 ```python
-from fastapi_toolsets.db import lock_tables, LockMode
+from fastapi_toolsets.db import lock_tables
 
-async with lock_tables(session_maker=session_maker, tables=[User], mode=LockMode.EXCLUSIVE) as session:
+async with lock_tables(session=session, tables=[User], mode="EXCLUSIVE"):
     # No other transaction can modify User until this block exits
     ...
 ```
@@ -129,7 +129,7 @@ SQLAlchemy's ORM collection API triggers lazy-loads when you append to a relatio
 ```python
 from fastapi_toolsets.db import lock_tables, m2m_add
 
-async with lock_tables(session_maker, [Tag]) as session:
+async with lock_tables(session, [Tag]):
     tag = await TagCrud.create(session, TagCreate(name="python"))
     await m2m_add(session, post, Post.tags, tag)
 ```

docs/module/schemas.md

@@ -102,7 +102,7 @@ async def list_events(
 
 #### [`PaginatedResponse[T]`](../reference/schemas.md#fastapi_toolsets.schemas.PaginatedResponse)
 
-Return type for endpoints that support **both** pagination strategies via a `pagination_type` query parameter (using [`paginate()`](crud.md#unified-endpoint-both-strategies)).
+Return type for endpoints that support **both** pagination strategies via a `pagination_type` query parameter (using [`paginate()`](crud.md#unified-paginate--both-strategies-on-one-endpoint)).
 
 When used as a return annotation, `PaginatedResponse[T]` automatically expands to `Annotated[Union[CursorPaginatedResponse[T], OffsetPaginatedResponse[T]], Field(discriminator="pagination_type")]`, so FastAPI emits a proper `oneOf` + discriminator in the OpenAPI schema with no extra boilerplate:
 
@@ -129,7 +129,7 @@ async def list_users(
 
 #### Pagination metadata models
 
-The optional `filter_attributes` field is populated when `facet_fields` are configured on the CRUD class (see [Filter attributes](crud.md#faceted-search)). It is `None` by default and can be hidden from API responses with `response_model_exclude_none=True`.
+The optional `filter_attributes` field is populated when `facet_fields` are configured on the CRUD class (see [Filter attributes](crud.md#filter-attributes-facets)). It is `None` by default and can be hidden from API responses with `response_model_exclude_none=True`.
 
 ### [`ErrorResponse`](../reference/schemas.md#fastapi_toolsets.schemas.ErrorResponse)
 

docs/module/security.md

@@ -174,6 +174,15 @@ async def profile(user: User = Security(bearer.require(role=Role.USER))):
 The `prefix` (for `BearerTokenAuth`), cookie name and `secret_key` (for
 `CookieAuth`), and header name (for `APIKeyHeaderAuth`) are always preserved.
 
+`.require()` instances work transparently inside `MultiAuth`:
+
+```python
+multi = MultiAuth(
+    user_bearer.require(role=Role.USER),
+    org_bearer.require(role=Role.ADMIN),
+)
+```
+
 ## MultiAuth
 
 [`MultiAuth`](../reference/security.md#fastapi_toolsets.security.MultiAuth) combines multiple auth sources into a single callable. Sources are tried in order; the first one that finds a credential wins.
@@ -276,24 +285,24 @@ Returns a `(authorization_url, token_url, userinfo_url)` tuple. `userinfo_url` i
 
 ### Authorization redirect
 
-[`oauth_build_authorization_redirect()`](../reference/security.md#fastapi_toolsets.security.oauth_build_authorization_redirect) constructs the redirect to the provider's authorization page.  It requires a `state_token` — a random CSRF token generated by [`oauth_generate_state_token()`](../reference/security.md#fastapi_toolsets.security.oauth_generate_state_token) — that must be stored server-side (e.g. in the session) and verified on the callback to prevent login-CSRF attacks ([RFC 6749 §10.12](https://datatracker.ietf.org/doc/html/rfc6749#section-10.12)):
+[`oauth_build_authorization_redirect()`](../reference/security.md#fastapi_toolsets.security.oauth_build_authorization_redirect) constructs the redirect to the provider's authorization page.  It requires a `nonce` — a random CSRF token generated by [`oauth_generate_nonce()`](../reference/security.md#fastapi_toolsets.security.oauth_generate_nonce) — that must be stored server-side (e.g. in the session) and verified on the callback to prevent login-CSRF attacks (RFC 6749 §10.12):
 
 ```python
 from fastapi import Request
-from fastapi_toolsets.security import oauth_build_authorization_redirect, oauth_generate_state_token
+from fastapi_toolsets.security import oauth_build_authorization_redirect, oauth_generate_nonce
 
 @app.get("/auth/google/login")
 async def google_login(request: Request):
     auth_url, _, _ = await oauth_resolve_provider_urls(GOOGLE_DISCOVERY_URL)
-    state_token = oauth_generate_state_token()
-    request.session["oauth_state"] = state_token  # requires SessionMiddleware
+    nonce = oauth_generate_nonce()
+    request.session["oauth_nonce"] = nonce  # requires SessionMiddleware
     return oauth_build_authorization_redirect(
         auth_url,
         client_id=GOOGLE_CLIENT_ID,
         scopes="openid email profile",
         redirect_uri="https://myapp.com/auth/google/callback",
         destination="/dashboard",
-        state_token=state_token,
+        nonce=nonce,
     )
 ```
 
@@ -301,7 +310,7 @@ async def google_login(request: Request):
 
 [`oauth_fetch_userinfo()`](../reference/security.md#fastapi_toolsets.security.oauth_fetch_userinfo) performs the two-step exchange: it POSTs the authorization code to the token endpoint, then GETs the userinfo endpoint with the resulting access token.
 
-On the callback, retrieve the stored token and pass it to [`oauth_decode_state()`](../reference/security.md#fastapi_toolsets.security.oauth_decode_state) to verify the CSRF token before processing the code:
+On the callback, retrieve the stored nonce and pass it to [`oauth_decode_state()`](../reference/security.md#fastapi_toolsets.security.oauth_decode_state) to verify the CSRF token before processing the code:
 
 ```python
 from fastapi import HTTPException, Request
@@ -309,11 +318,11 @@ from fastapi_toolsets.security import oauth_decode_state, oauth_fetch_userinfo
 
 @app.get("/auth/google/callback")
 async def google_callback(request: Request, code: str, state: str):
-    # Pop token first — single-use, regardless of whether verification succeeds
-    state_token = request.session.pop("oauth_state", None)
-    if state_token is None:
+    # Pop nonce first — single-use, regardless of whether verification succeeds
+    nonce = request.session.pop("oauth_nonce", None)
+    if nonce is None:
         raise HTTPException(status_code=400, detail="missing OAuth state")
-    destination = oauth_decode_state(state, expected_state_token=state_token, fallback="/")
+    destination = oauth_decode_state(state, expected_nonce=nonce, fallback="/")
     if not destination.startswith("/"):  # reject absolute URLs to prevent open-redirect
         destination = "/"
 
@@ -337,16 +346,16 @@ Pass `required_scopes` to guard against providers silently granting fewer scopes
 
 ### State encoding
 
-[`oauth_encode_state()`](../reference/security.md#fastapi_toolsets.security.oauth_encode_state) and [`oauth_decode_state()`](../reference/security.md#fastapi_toolsets.security.oauth_decode_state) encode and decode the destination URL together with the CSRF token embedded in the OAuth `state` parameter.  `oauth_decode_state` returns `fallback` if `state` is absent, malformed, or the token does not match:
+[`oauth_encode_state()`](../reference/security.md#fastapi_toolsets.security.oauth_encode_state) and [`oauth_decode_state()`](../reference/security.md#fastapi_toolsets.security.oauth_decode_state) encode and decode the destination URL together with the CSRF nonce embedded in the OAuth `state` parameter.  `oauth_decode_state` returns `fallback` if `state` is absent, malformed, or the nonce does not match:
 
 ```python
 from fastapi_toolsets.security import oauth_encode_state, oauth_decode_state
 
-state_token = oauth_generate_state_token()
-encoded = oauth_encode_state("/dashboard", state_token)
-decoded = oauth_decode_state(encoded, expected_state_token=state_token, fallback="/")  # "/dashboard"
-decoded = oauth_decode_state(encoded, expected_state_token="wrong", fallback="/")  # "/"
-decoded = oauth_decode_state(None, expected_state_token=state_token, fallback="/")       # "/"
+nonce = "my-random-nonce"
+encoded = oauth_encode_state("/dashboard", nonce)
+decoded = oauth_decode_state(encoded, expected_nonce=nonce, fallback="/")  # "/dashboard"
+decoded = oauth_decode_state(encoded, expected_nonce="wrong", fallback="/")  # "/"
+decoded = oauth_decode_state(None, expected_nonce=nonce, fallback="/")       # "/"
 ```
 
 ---

docs/reference/exceptions.md

@@ -12,7 +12,6 @@ from fastapi_toolsets.exceptions import (
     NotFoundError,
     ConflictError,
     NoSearchableFieldsError,
-    InvalidSearchColumnError,
     InvalidFacetFilterError,
     InvalidOrderFieldError,
     generate_error_responses,
@@ -32,8 +31,6 @@ from fastapi_toolsets.exceptions import (
 
 ## ::: fastapi_toolsets.exceptions.exceptions.NoSearchableFieldsError
 
-## ::: fastapi_toolsets.exceptions.exceptions.InvalidSearchColumnError
-
 ## ::: fastapi_toolsets.exceptions.exceptions.InvalidFacetFilterError
 
 ## ::: fastapi_toolsets.exceptions.exceptions.InvalidOrderFieldError

docs/reference/security.md

@@ -15,7 +15,7 @@ from fastapi_toolsets.security import (
     oauth_decode_state,
     oauth_encode_state,
     oauth_fetch_userinfo,
-    oauth_generate_state_token,
+    oauth_generate_nonce,
     oauth_resolve_provider_urls,
 )
 ```
@@ -34,7 +34,7 @@ from fastapi_toolsets.security import (
 
 ## ::: fastapi_toolsets.security.oauth_fetch_userinfo
 
-## ::: fastapi_toolsets.security.oauth_generate_state_token
+## ::: fastapi_toolsets.security.oauth_generate_nonce
 
 ## ::: fastapi_toolsets.security.oauth_build_authorization_redirect
 

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "fastapi-toolsets"
-version = "4.0.0"
+version = "3.1.1"
 description = "Production-ready utilities for FastAPI applications"
 readme = "README.md"
 license = "MIT"

src/fastapi_toolsets/__init__.py

@@ -21,4 +21,4 @@ Example usage:
         return Response(data={"user": user.username}, message="Success")
 """
 
-__version__ = "4.0.0"
+__version__ = "3.1.1"

src/fastapi_toolsets/db.py

@@ -151,57 +151,52 @@ class LockMode(str, Enum):
     ACCESS_EXCLUSIVE = "ACCESS EXCLUSIVE"
 
 
-def lock_tables(
-    session_maker: async_sessionmaker[_SessionT],
+@asynccontextmanager
+async def lock_tables(
+    session: AsyncSession,
     tables: list[type[DeclarativeBase]],
     *,
     mode: LockMode = LockMode.SHARE_UPDATE_EXCLUSIVE,
     timeout: str = "5s",
-) -> AbstractAsyncContextManager[_SessionT]:
+) -> AsyncGenerator[AsyncSession, None]:
     """Lock PostgreSQL tables for the duration of a transaction.
 
+    Acquires table-level locks that are held until the transaction ends.
+    Useful for preventing concurrent modifications during critical operations.
+
     Args:
-        session_maker: Async session factory used to create the dedicated
-            session.
-        tables: List of SQLAlchemy model classes to lock.
-        mode: Lock mode (default: SHARE UPDATE EXCLUSIVE).
-        timeout: Lock timeout (default: "5s").
+        session: AsyncSession instance
+        tables: List of SQLAlchemy model classes to lock
+        mode: Lock mode (default: SHARE UPDATE EXCLUSIVE)
+        timeout: Lock timeout (default: "5s")
 
     Yields:
-        The dedicated session, open within the locked transaction.
+        The session with locked tables
 
     Raises:
-        SQLAlchemyError: If the lock cannot be acquired within *timeout*.
+        SQLAlchemyError: If lock cannot be acquired within timeout
 
     Example:
         ```python
         from fastapi_toolsets.db import lock_tables, LockMode
 
-        async with lock_tables(session_maker, [User, Account]) as session:
-            # Tables are locked; changes are committed when the context exits.
+        async with lock_tables(session, [User, Account]):
+            # Tables are locked with SHARE UPDATE EXCLUSIVE mode
             user = await UserCrud.get(session, [User.id == 1])
             user.balance += 100
 
         # With custom lock mode
-        async with lock_tables(session_maker, [Order], mode=LockMode.EXCLUSIVE) as session:
+        async with lock_tables(session, [Order], mode=LockMode.EXCLUSIVE):
+            # Exclusive lock - no other transactions can access
             await process_order(session, order_id)
         ```
     """
     table_names = ",".join(table.__tablename__ for table in tables)
 
-    @asynccontextmanager
-    async def _lock() -> AsyncGenerator[_SessionT, None]:
-        async with session_maker() as session:
-            try:
-                await session.execute(text(f"SET LOCAL lock_timeout='{timeout}'"))
-                await session.execute(text(f"LOCK {table_names} IN {mode.value} MODE"))
-                yield session
-                await session.commit()
-            except BaseException:
-                await session.rollback()
-                raise
-
-    return _lock()
+    async with get_transaction(session):
+        await session.execute(text(f"SET LOCAL lock_timeout='{timeout}'"))
+        await session.execute(text(f"LOCK {table_names} IN {mode.value} MODE"))
+        yield session
 
 
 async def create_database(

src/fastapi_toolsets/security/__init__.py

@@ -6,7 +6,7 @@ from .oauth import (
     oauth_decode_state,
     oauth_encode_state,
     oauth_fetch_userinfo,
-    oauth_generate_state_token,
+    oauth_generate_nonce,
     oauth_resolve_provider_urls,
 )
 from .sources import APIKeyHeaderAuth, BearerTokenAuth, CookieAuth, MultiAuth
@@ -21,6 +21,6 @@ __all__ = [
     "oauth_decode_state",
     "oauth_encode_state",
     "oauth_fetch_userinfo",
-    "oauth_generate_state_token",
+    "oauth_generate_nonce",
     "oauth_resolve_provider_urls",
 ]

src/fastapi_toolsets/security/oauth.py

@@ -103,8 +103,13 @@ async def oauth_fetch_userinfo(
         return userinfo_resp.json()
 
 
-def oauth_generate_state_token() -> str:
-    """Generate a cryptographically random CSRF token for the OAuth ``state`` parameter."""
+def oauth_generate_nonce() -> str:
+    """Generate a cryptographically random nonce for use as an OAuth CSRF token.
+
+    Call this before :func:`oauth_build_authorization_redirect`, persist the
+    returned value in the user's session or a ``Secure; HttpOnly; SameSite=Lax``
+    cookie, then verify it with :func:`oauth_decode_state` on the callback.
+    """
     return secrets.token_urlsafe(32)
 
 
@@ -115,7 +120,7 @@ def oauth_build_authorization_redirect(
     scopes: str,
     redirect_uri: str,
     destination: str,
-    state_token: str,
+    nonce: str,
 ) -> RedirectResponse:
     """Return an OAuth 2.0 authorization ``RedirectResponse``.
 
@@ -126,9 +131,9 @@ def oauth_build_authorization_redirect(
         redirect_uri: URI the provider should redirect back to after authorization.
         destination: URL the user should be sent to after the full OAuth flow
             completes (embedded in ``state``).
-        state_token: CSRF token generated by :func:`oauth_generate_state_token`.
-            Must be stored server-side (session or signed cookie) and verified via
-            :func:`oauth_decode_state` on the callback endpoint (RFC 6749 §10.12).
+        nonce: CSRF token generated by :func:`oauth_generate_nonce`.  Must be
+            stored server-side (session or signed cookie) and verified via
+            :func:`oauth_decode_state` on the callback endpoint.
 
     Returns:
         A :class:`~fastapi.responses.RedirectResponse` to the provider's
@@ -140,34 +145,32 @@ def oauth_build_authorization_redirect(
             "response_type": "code",
             "scope": scopes,
             "redirect_uri": redirect_uri,
-            "state": oauth_encode_state(destination, state_token),
+            "state": oauth_encode_state(destination, nonce),
         }
     )
     return RedirectResponse(f"{authorization_url}?{params}")
 
 
-def oauth_encode_state(url: str, state_token: str) -> str:
-    """Encode a destination URL and CSRF token into an OAuth ``state`` parameter.
+def oauth_encode_state(url: str, nonce: str) -> str:
+    """Encode a destination URL and CSRF nonce into an OAuth ``state`` parameter.
 
     Args:
         url: Post-login destination URL.
-        state_token: CSRF token from :func:`oauth_generate_state_token`.
+        nonce: CSRF token from :func:`oauth_generate_nonce`.
     """
-    payload = json.dumps({"n": state_token, "d": url}, separators=(",", ":"))
+    payload = json.dumps({"n": nonce, "d": url}, separators=(",", ":"))
     return base64.urlsafe_b64encode(payload.encode()).decode()
 
 
-def oauth_decode_state(
-    state: str | None, *, expected_state_token: str, fallback: str
-) -> str:
+def oauth_decode_state(state: str | None, *, expected_nonce: str, fallback: str) -> str:
     """Decode and CSRF-verify an OAuth ``state`` parameter.
 
-    Uses a constant-time comparison for the CSRF token to prevent timing attacks.
+    Uses a constant-time comparison for the nonce to prevent timing attacks.
 
     Args:
         state: Raw ``state`` query parameter from the provider's callback.
-        expected_state_token: The token stored before the authorization redirect.
-            If it does not match the decoded value, ``fallback`` is returned.
+        expected_nonce: The nonce stored before the authorization redirect.
+            If the decoded nonce does not match, ``fallback`` is returned.
         fallback: URL to return when ``state`` is absent, malformed, or fails
             CSRF verification.
 
@@ -175,7 +178,7 @@ def oauth_decode_state(
         The destination URL embedded in ``state``, or ``fallback``.
 
     Important:
-        **Single-use**: delete the stored token from the session immediately
+        **Single-use**: delete the stored nonce from the session immediately
         after calling this function — whether it matched or not — so that a
         captured callback URL cannot be replayed.
 
@@ -189,7 +192,7 @@ def oauth_decode_state(
         padded = state + "=" * (-len(state) % 4)
         payload = json.loads(base64.urlsafe_b64decode(padded).decode("utf-8"))
         if not isinstance(payload, dict) or not hmac.compare_digest(
-            payload.get("n", "").encode(), expected_state_token.encode()
+            payload.get("n", "").encode(), expected_nonce.encode()
         ):
             return fallback
         return str(payload["d"])

tests/conftest.py

@@ -439,21 +439,6 @@ async def engine():
     await engine.dispose()
 
 
-@pytest.fixture(scope="function")
-async def session_maker(engine):
-    """Provide a session factory with tables created and dropped around the test."""
-    async with engine.begin() as conn:
-        await conn.run_sync(Base.metadata.create_all)
-
-    factory = async_sessionmaker(engine, expire_on_commit=False)
-
-    try:
-        yield factory
-    finally:
-        async with engine.begin() as conn:
-            await conn.run_sync(Base.metadata.drop_all)
-
-
 @pytest.fixture(scope="function")
 async def db_session(engine):
     """Create a test database session with tables.

tests/test_db.py

@@ -116,8 +116,13 @@ class TestCreateDbDependency:
         await engine.dispose()
 
     @pytest.mark.anyio
-    async def test_data_inside_lock_is_committed(self):
-        """Changes made inside lock_tables are committed when the context exits."""
+    async def test_update_after_lock_tables_is_persisted(self):
+        """Changes made after lock_tables exits (before endpoint returns) are committed.
+
+        Regression: without the auto-begin fix, lock_tables would start and commit a
+        real outer transaction, leaving the session idle. Any modifications after that
+        point were silently dropped.
+        """
         engine = create_async_engine(DATABASE_URL, echo=False)
         session_factory = async_sessionmaker(engine, expire_on_commit=False)
 
@@ -125,12 +130,21 @@ class TestCreateDbDependency:
             await conn.run_sync(Base.metadata.create_all)
 
         try:
-            async with lock_tables(session_factory, [Role]) as session:
-                role = Role(name="lock_committed")
-                session.add(role)
+            get_db = create_db_dependency(session_factory)
+
+            async for session in get_db():
+                async with lock_tables(session, [Role]):
+                    role = Role(name="lock_then_update")
+                    session.add(role)
+                    await session.flush()
+                # lock_tables has exited — outer transaction must still be open
+                assert session.in_transaction()
+                role.name = "updated_after_lock"
 
             async with session_factory() as verify:
-                result = await RoleCrud.first(verify, [Role.name == "lock_committed"])
+                result = await RoleCrud.first(
+                    verify, [Role.name == "updated_after_lock"]
+                )
                 assert result is not None
         finally:
             async with engine.begin() as conn:
@@ -273,55 +287,54 @@ class TestLockTables:
     """Tests for lock_tables context manager (PostgreSQL-specific)."""
 
     @pytest.mark.anyio
-    async def test_lock_single_table(self, session_maker):
-        """Lock a single table; changes inside are committed on context exit."""
-        async with lock_tables(session_maker, [Role]) as session:
+    async def test_lock_single_table(self, db_session: AsyncSession):
+        """Lock a single table."""
+        async with lock_tables(db_session, [Role]):
+            # Inside the lock, we can still perform operations
             role = Role(name="locked_role")
-            session.add(role)
+            db_session.add(role)
+            await db_session.flush()
 
-        async with session_maker() as verify:
-            result = await RoleCrud.first(verify, [Role.name == "locked_role"])
-            assert result is not None
+        # After lock is released, verify the data was committed
+        result = await RoleCrud.first(db_session, [Role.name == "locked_role"])
+        assert result is not None
 
     @pytest.mark.anyio
-    async def test_lock_multiple_tables(self, session_maker):
+    async def test_lock_multiple_tables(self, db_session: AsyncSession):
         """Lock multiple tables."""
-        async with lock_tables(session_maker, [Role, User]) as session:
+        async with lock_tables(db_session, [Role, User]):
             role = Role(name="multi_lock_role")
-            session.add(role)
+            db_session.add(role)
+            await db_session.flush()
 
-        async with session_maker() as verify:
-            result = await RoleCrud.first(verify, [Role.name == "multi_lock_role"])
-            assert result is not None
+        result = await RoleCrud.first(db_session, [Role.name == "multi_lock_role"])
+        assert result is not None
 
     @pytest.mark.anyio
-    async def test_lock_with_custom_mode(self, session_maker):
+    async def test_lock_with_custom_mode(self, db_session: AsyncSession):
         """Lock with custom lock mode."""
-        async with lock_tables(
-            session_maker, [Role], mode=LockMode.EXCLUSIVE
-        ) as session:
+        async with lock_tables(db_session, [Role], mode=LockMode.EXCLUSIVE):
             role = Role(name="exclusive_lock_role")
-            session.add(role)
+            db_session.add(role)
+            await db_session.flush()
 
-        async with session_maker() as verify:
-            result = await RoleCrud.first(verify, [Role.name == "exclusive_lock_role"])
-            assert result is not None
+        result = await RoleCrud.first(db_session, [Role.name == "exclusive_lock_role"])
+        assert result is not None
 
     @pytest.mark.anyio
-    async def test_lock_rollback_on_exception(self, session_maker):
+    async def test_lock_rollback_on_exception(self, db_session: AsyncSession):
         """Lock context rolls back on exception."""
         try:
-            async with lock_tables(session_maker, [Role]) as session:
+            async with lock_tables(db_session, [Role]):
                 role = Role(name="lock_rollback_role")
-                session.add(role)
-                await session.flush()
+                db_session.add(role)
+                await db_session.flush()
                 raise ValueError("Simulated error")
         except ValueError:
             pass
 
-        async with session_maker() as verify:
-            result = await RoleCrud.first(verify, [Role.name == "lock_rollback_role"])
-            assert result is None
+        result = await RoleCrud.first(db_session, [Role.name == "lock_rollback_role"])
+        assert result is None
 
 
 class TestWaitForRowChange:
@@ -630,30 +643,29 @@ class TestM2MAdd:
             await m2m_add(db_session, user, User.role, role)
 
     @pytest.mark.anyio
-    async def test_works_inside_lock_tables(self, session_maker):
-        """m2m_add works correctly inside a lock_tables context."""
-        async with lock_tables(session_maker, [Tag]) as session:
-            user = User(username="m2m_lock_author", email="m2m_lock@test.com")
-            session.add(user)
-            await session.flush()
+    async def test_works_inside_lock_tables(self, db_session: AsyncSession):
+        """m2m_add works correctly inside a lock_tables nested transaction."""
+        user = User(username="m2m_lock_author", email="m2m_lock@test.com")
+        db_session.add(user)
+        await db_session.flush()
 
+        async with lock_tables(db_session, [Tag]):
             tag = Tag(name="locked_tag")
-            session.add(tag)
-            await session.flush()
+            db_session.add(tag)
+            await db_session.flush()
 
             post = Post(title="Post Lock", author_id=user.id)
-            session.add(post)
-            await session.flush()
+            db_session.add(post)
+            await db_session.flush()
 
-            await m2m_add(session, post, Post.tags, tag)
+            await m2m_add(db_session, post, Post.tags, tag)
 
-        async with session_maker() as verify:
-            result = await verify.execute(
-                select(Post).where(Post.id == post.id).options(selectinload(Post.tags))
-            )
-            loaded = result.scalar_one()
-            assert len(loaded.tags) == 1
-            assert loaded.tags[0].name == "locked_tag"
+        result = await db_session.execute(
+            select(Post).where(Post.id == post.id).options(selectinload(Post.tags))
+        )
+        loaded = result.scalar_one()
+        assert len(loaded.tags) == 1
+        assert loaded.tags[0].name == "locked_tag"
 
 
 class _LocalBase(DeclarativeBase):

tests/test_models.py

@@ -7,7 +7,6 @@ from unittest.mock import patch
 
 import pytest
 from sqlalchemy import String
-from sqlalchemy.ext.asyncio import async_sessionmaker, create_async_engine
 from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column
 
 import fastapi_toolsets.models.watched as _watched_module
@@ -21,7 +20,6 @@ from fastapi_toolsets.models import (
     listens_for,
 )
 from fastapi_toolsets.models.watched import (
-    EventSession,
     _EVENT_HANDLERS,
     _SESSION_CREATES,
     _SESSION_DELETES,
@@ -340,23 +338,6 @@ async def mixin_session_expire():
         yield session
 
 
-@pytest.fixture(scope="function")
-async def mixin_session_maker():
-    """Provide an EventSession-backed session factory with MixinBase tables."""
-    engine = create_async_engine(DATABASE_URL, echo=False)
-    async with engine.begin() as conn:
-        await conn.run_sync(MixinBase.metadata.create_all)
-
-    factory = async_sessionmaker(engine, expire_on_commit=False, class_=EventSession)
-
-    try:
-        yield factory
-    finally:
-        async with engine.begin() as conn:
-            await conn.run_sync(MixinBase.metadata.drop_all)
-        await engine.dispose()
-
-
 class TestUUIDMixin:
     @pytest.mark.anyio
     async def test_uuid_generated_by_db(self, mixin_session):
@@ -1578,13 +1559,15 @@ class TestEventSessionWithGetTransaction:
         assert creates[0]["obj_id"] == survivor.id
 
     @pytest.mark.anyio
-    async def test_lock_tables_with_events(self, mixin_session_maker):
-        """Events fire correctly when lock_tables commits on context exit."""
+    async def test_lock_tables_with_events(self, mixin_session):
+        """Events fire correctly after lock_tables context."""
         from fastapi_toolsets.db import lock_tables
 
-        async with lock_tables(mixin_session_maker, [WatchedModel]) as session:
+        async with lock_tables(mixin_session, [WatchedModel]):
             obj = WatchedModel(status="locked", other="x")
-            session.add(obj)
+            mixin_session.add(obj)
+
+        await mixin_session.commit()
 
         creates = [e for e in _test_events if e["event"] == "create"]
         assert len(creates) == 1

tests/test_security.py

@@ -18,7 +18,7 @@ from fastapi_toolsets.security import (
     oauth_decode_state,
     oauth_encode_state,
     oauth_fetch_userinfo,
-    oauth_generate_state_token,
+    oauth_generate_nonce,
     oauth_resolve_provider_urls,
 )
 
@@ -1013,64 +1013,56 @@ def _make_async_client_mock(get_return=None, post_return=None):
 
 class TestEncodeDecodeOAuthState:
     def test_encode_returns_base64url_string(self):
-        result = oauth_encode_state("https://example.com/dashboard", "test-state-token")
+        result = oauth_encode_state("https://example.com/dashboard", "test-nonce")
         assert isinstance(result, str)
         assert "+" not in result
         assert "/" not in result
 
     def test_round_trip(self):
         url = "https://example.com/after-login?next=/home"
-        state_token = "test-state-token"
+        nonce = "test-nonce"
         assert (
             oauth_decode_state(
-                oauth_encode_state(url, state_token),
-                expected_state_token=state_token,
-                fallback="/",
+                oauth_encode_state(url, nonce), expected_nonce=nonce, fallback="/"
             )
             == url
         )
 
     def test_decode_none_returns_fallback(self):
         assert (
-            oauth_decode_state(None, expected_state_token="any", fallback="/home")
-            == "/home"
+            oauth_decode_state(None, expected_nonce="any", fallback="/home") == "/home"
         )
 
     def test_decode_null_string_returns_fallback(self):
         assert (
-            oauth_decode_state("null", expected_state_token="any", fallback="/home")
+            oauth_decode_state("null", expected_nonce="any", fallback="/home")
             == "/home"
         )
 
     def test_decode_invalid_base64_returns_fallback(self):
         assert (
             oauth_decode_state(
-                "!!!notbase64!!!", expected_state_token="any", fallback="/home"
+                "!!!notbase64!!!", expected_nonce="any", fallback="/home"
             )
             == "/home"
         )
 
     def test_decode_handles_missing_padding(self):
         url = "https://example.com/x"
-        state_token = "test-state-token"
-        encoded = oauth_encode_state(url, state_token).rstrip("=")
-        assert (
-            oauth_decode_state(encoded, expected_state_token=state_token, fallback="/")
-            == url
-        )
+        nonce = "test-nonce"
+        encoded = oauth_encode_state(url, nonce).rstrip("=")
+        assert oauth_decode_state(encoded, expected_nonce=nonce, fallback="/") == url
 
-    def test_decode_wrong_state_token_returns_fallback(self):
+    def test_decode_wrong_nonce_returns_fallback(self):
         url = "https://example.com/dashboard"
-        encoded = oauth_encode_state(url, "correct-token")
+        encoded = oauth_encode_state(url, "correct-nonce")
         assert (
-            oauth_decode_state(
-                encoded, expected_state_token="wrong-token", fallback="/"
-            )
+            oauth_decode_state(encoded, expected_nonce="wrong-nonce", fallback="/")
             == "/"
         )
 
-    def test_generate_state_token_is_random(self):
-        assert oauth_generate_state_token() != oauth_generate_state_token()
+    def test_generate_nonce_is_random(self):
+        assert oauth_generate_nonce() != oauth_generate_nonce()
 
 
 class TestBuildAuthorizationRedirect:
@@ -1083,19 +1075,19 @@ class TestBuildAuthorizationRedirect:
             scopes="openid email",
             redirect_uri="https://app.example.com/callback",
             destination="https://app.example.com/dashboard",
-            state_token="test-state-token",
+            nonce="test-nonce",
         )
         assert isinstance(response, RedirectResponse)
 
     def test_redirect_location_contains_all_params(self):
-        state_token = "test-state-token"
+        nonce = "test-nonce"
         response = oauth_build_authorization_redirect(
             "https://auth.example.com/authorize",
             client_id="my-client",
             scopes="openid email",
             redirect_uri="https://app.example.com/callback",
             destination="https://app.example.com/dashboard",
-            state_token=state_token,
+            nonce=nonce,
         )
         location = response.headers["location"]
         parsed = urlparse(location)
@@ -1109,9 +1101,7 @@ class TestBuildAuthorizationRedirect:
         assert params["scope"] == ["openid email"]
         assert params["redirect_uri"] == ["https://app.example.com/callback"]
         assert (
-            oauth_decode_state(
-                params["state"][0], expected_state_token=state_token, fallback=""
-            )
+            oauth_decode_state(params["state"][0], expected_nonce=nonce, fallback="")
             == "https://app.example.com/dashboard"
         )
 

uv.lock

@@ -330,7 +330,7 @@ wheels = [
 
 [[package]]
 name = "fastapi-toolsets"
-version = "4.0.0"
+version = "3.1.1"
 source = { editable = "." }
 dependencies = [
     { name = "asyncpg" },

zensical.toml

@@ -147,7 +147,6 @@ Examples = [
 
 [[project.nav]]
 Migration = [
-    {"v4.0" = "migration/v4.md"},
     {"v3.0" = "migration/v3.md"},
     {"v2.0" = "migration/v2.md"},
 ]