tempest-fastapi-sdk 0.61.0__tar.gz → 0.63.0__tar.gz

{tempest_fastapi_sdk-0.61.0 → tempest_fastapi_sdk-0.63.0}/CHANGELOG.md

@@ -5,6 +5,64 @@ All notable changes to **tempest-fastapi-sdk** are listed below.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.63.0] — 2026-06-21
+
+### Changed
+
+- **`UserAuthService.current_user_dependency()` now loads the authenticated
+  user on the request-scoped session** (`db.session_dependency` by default)
+  instead of opening its own short-lived session through `load_user`.
+  Previously the returned `UserModel` was **detached** — mutating it and
+  committing/refreshing on the request's repository session raised
+  `InvalidRequestError: Instance is not persistent within this Session`,
+  and lazy-relationship access raised `DetachedInstanceError`. The user is
+  now attached to the same session repositories use. **Breaking** only for
+  apps whose repositories do not share the auth service's session callable;
+  pass `session_dependency=` to point both at the same provider. See the
+  **Migration guide** (`docs/migration.md`). The single-argument `user_loader` path
+  of `make_jwt_user_dependency` is unchanged; the new behavior is opt-in via
+  the new `session_dependency=` parameter (which `current_user_dependency`
+  now passes by default).
+- **`BaseRepository.resolve()` re-attaches detached instances** via
+  `session.merge()` instead of returning them as-is. A detached model passed
+  to a mutating service is brought back into the active session, so the
+  subsequent `update()` commits instead of raising. `merge` issues a
+  `SELECT` only when the row is not already in the session's identity map.
+
+### Added
+
+- **`make_jwt_user_dependency(..., session_dependency=...)`** — when given a
+  request-scoped session provider, the dependency injects it and calls the
+  two-argument loader `user_loader(subject, session)`, sharing the session
+  with the request's repositories.
+- **`UserAuthService.current_user_dependency(session_dependency=...)`** —
+  override the session provider shared with repositories (defaults to
+  `self.db.session_dependency`). Now raises `RuntimeError` eagerly when the
+  service was built without `db=`.
+
+## [0.62.0] — 2026-06-20
+
+### Added
+
+- **`BasePaginationFilterSchema.get_pagination_conditions()`** and
+  **`CursorPaginationFilterSchema.get_pagination_conditions()`** — the
+  counterpart to `get_conditions()`. Where `get_conditions()` strips the
+  pagination keys to expose the domain filters, this returns **only** the
+  pagination/sort keys (`page`/`page_size`/`order_by`/`ascending` for
+  offset, `cursor`/`limit`/`order_by`/`ascending` for cursor). A service
+  can now forward a filter schema to `paginate` / `cursor_paginate`
+  without manually unpacking the model:
+
+    ```python
+    data = await repo.paginate(
+        filters=f.get_conditions(),
+        **f.get_pagination_conditions(),
+    )
+    ```
+
+  This replaces the `**filter_schema` idiom, which leaked domain filters
+  (e.g. `is_active`) into keyword arguments the repository does not accept.
+
 ## [0.61.0] — 2026-06-15
 
 ### Added

{tempest_fastapi_sdk-0.61.0 → tempest_fastapi_sdk-0.63.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tempest-fastapi-sdk
-Version: 0.61.0
+Version: 0.63.0
 Summary: Shared FastAPI building blocks: base schemas, ORM model, async repository, exceptions, pagination and settings — the conventions used across Tempest projects.
 Project-URL: Homepage, https://github.com/mauriciobenjamin700/tempest-fastapi-sdk
 Project-URL: Repository, https://github.com/mauriciobenjamin700/tempest-fastapi-sdk
@@ -1167,6 +1167,15 @@ async def me(current: UserModel = Depends(get_current_user)) -> UserResponseSche
 > get_current_user = auth_service.current_user_dependency()
 > get_current_user_or_none = auth_service.current_user_dependency(soft=True)
 > ```
+>
+> The authenticated user is loaded on the **request-scoped session**
+> (`db.session_dependency`), so it is attached to the same session your
+> repositories use — you can mutate it and `commit`/`refresh` without an
+> `InvalidRequestError: Instance is not persistent within this Session`.
+> Keep one shared session callable (`get_session = db.session_dependency`)
+> for FastAPI to deduplicate them; if your repositories depend on a
+> different `get_session` wrapper, pass it as
+> `current_user_dependency(session_dependency=get_session)`.
 
 #### Soft auth (optional user)
 

{tempest_fastapi_sdk-0.61.0 → tempest_fastapi_sdk-0.63.0}/README.md

@@ -1064,6 +1064,15 @@ async def me(current: UserModel = Depends(get_current_user)) -> UserResponseSche
 > get_current_user = auth_service.current_user_dependency()
 > get_current_user_or_none = auth_service.current_user_dependency(soft=True)
 > ```
+>
+> The authenticated user is loaded on the **request-scoped session**
+> (`db.session_dependency`), so it is attached to the same session your
+> repositories use — you can mutate it and `commit`/`refresh` without an
+> `InvalidRequestError: Instance is not persistent within this Session`.
+> Keep one shared session callable (`get_session = db.session_dependency`)
+> for FastAPI to deduplicate them; if your repositories depend on a
+> different `get_session` wrapper, pass it as
+> `current_user_dependency(session_dependency=get_session)`.
 
 #### Soft auth (optional user)
 

{tempest_fastapi_sdk-0.61.0 → tempest_fastapi_sdk-0.63.0}/docs/migration.en.md

@@ -2,6 +2,36 @@
 
 Breaking-change walkthroughs grouped by minor release. Stick to the version that matches what you're upgrading **from**.
 
+## 0.63.0 — authenticated user loaded on the request session
+
+Before 0.63.0, `UserAuthService.current_user_dependency()` loaded the authenticated user through `load_user`, which opened its **own** session (via `db.get_session_context()`) and closed it on exit. The `UserModel` handed to the route was therefore **detached**: mutating it and calling `commit`/`refresh` on the request session (the one your repositories use) raised
+`InvalidRequestError: Instance is not persistent within this Session`.
+
+From 0.63.0 the dependency loads the user on the **request session** (`db.session_dependency` by default) via `get_user(subject, session)`. The user is attached to the same session repositories use, so lazy-relationship reads and writes work without re-attaching anything.
+
+!!! warning "Compatibility"
+    The auth dependency and your repositories must share the **same** session callable for FastAPI's sub-dependency cache to deduplicate them. The recommended pattern is already covered:
+
+    ```python
+    # resources.py
+    get_session = db.session_dependency          # one object, reused
+    ```
+
+    If you wrap the session in your own provider (`async def get_session(): ...`), pass it explicitly, otherwise the dependency opens a second session and the user is detached again:
+
+    ```python
+    get_current_user = auth.current_user_dependency(session_dependency=get_session)
+    ```
+
+!!! info "Extra safety net"
+    `BaseRepository.resolve()` now re-attaches detached instances via `session.merge()`. Even if some flow still hands in a detached user, `resolve` brings it back into the active session instead of breaking — so services that worked around this (re-fetch by id before mutating) can drop the workaround.
+
+### Verify
+
+- Drop any "re-fetch by id before mutating the authenticated user" workaround — it's no longer needed.
+- A single-argument `user_loader` passed to `make_jwt_user_dependency` keeps working. To share the request session, pass `session_dependency=` and use a two-argument loader `(subject, session)`.
+
+## 0.8.0 — `ServerSettings` rename
 
 0.8.0 renames every field on `ServerSettings`, extracts log fields to a new `LogSettings` mixin, and adds eleven other primitives. The renames are the only **breaking** changes — every new primitive is opt-in.
 

{tempest_fastapi_sdk-0.61.0 → tempest_fastapi_sdk-0.63.0}/docs/migration.md

@@ -2,6 +2,36 @@
 
 Passo a passo das mudanças que quebram compatibilidade, agrupadas por release minor. Siga a versão que casa com aquela **de onde** você está atualizando.
 
+## 0.63.0 — usuário autenticado carregado na sessão de request
+
+Antes da 0.63.0, `UserAuthService.current_user_dependency()` carregava o usuário autenticado chamando `load_user`, que abria a **própria** sessão (via `db.get_session_context()`) e a fechava ao terminar. O `UserModel` entregue à rota ficava **detached**: mutá-lo e dar `commit`/`refresh` na sessão de request (a dos seus repositories) levantava
+`InvalidRequestError: Instance is not persistent within this Session`.
+
+A partir da 0.63.0 a dependência carrega o usuário na **sessão de request** (`db.session_dependency` por padrão), via `get_user(subject, session)`. O usuário fica anexado à mesma sessão que os repositories usam, então leituras de relacionamentos lazy e escritas funcionam sem reanexar nada.
+
+!!! warning "Compatibilidade"
+    A dependência de auth e seus repositories precisam compartilhar o **mesmo callable** de sessão para o cache de sub-dependências do FastAPI casar. Quem segue o padrão recomendado já está coberto:
+
+    ```python
+    # resources.py
+    get_session = db.session_dependency          # um único objeto, reutilizado
+    ```
+
+    Se você embrulha a sessão num provider próprio (`async def get_session(): ...`), passe-o explicitamente para a dependência, senão ela abre uma segunda sessão e o usuário volta a ficar detached:
+
+    ```python
+    get_current_user = auth.current_user_dependency(session_dependency=get_session)
+    ```
+
+!!! info "Defesa adicional"
+    `BaseRepository.resolve()` agora reanexa instâncias detached via `session.merge()`. Mesmo que algum fluxo ainda receba um usuário detached, o `resolve` o traz de volta à sessão ativa em vez de quebrar — então serviços que faziam workarounds manuais (re-fetch por id antes de mutar) podem removê-los.
+
+### Verifique
+
+- Remova qualquer workaround do tipo "re-fetch por id antes de mutar o usuário autenticado" — não é mais necessário.
+- Se você passava um `user_loader` de um argumento para `make_jwt_user_dependency`, ele continua funcionando. Para compartilhar a sessão de request, passe `session_dependency=` e use um loader de dois argumentos `(subject, session)`.
+
+## 0.8.0 — renomeação de `ServerSettings`
 
 A 0.8.0 renomeia todos os campos de `ServerSettings`, extrai os campos de log para um novo mixin `LogSettings` e adiciona onze outros primitivos. As renomeações são as únicas mudanças **que quebram** — todo primitivo novo é opt-in.
 

{tempest_fastapi_sdk-0.61.0 → tempest_fastapi_sdk-0.63.0}/docs/recipes/database.en.md

@@ -650,6 +650,24 @@ class UserRepository(BaseRepository[UserModel]):
 query, so custom joins still report a correct total. When `order_by` is
 `None`, it orders by `created_at desc`.
 
+!!! tip "Forward the schema without unpacking it by hand"
+    The `get_conditions()` / `get_pagination_conditions()` pair covers both
+    sides of the filter: the former returns only the domain filters, the
+    latter only the pagination keys (`page`, `page_size`, `order_by`,
+    `ascending`). The service forwards the filter straight through, no
+    `**f` — which would leak domain filters (`is_active`, etc.) as kwargs
+    the repository does not accept:
+
+    ```python
+    data = await repo.paginate(
+        filters=f.get_conditions(),
+        **f.get_pagination_conditions(),
+    )
+    ```
+
+    `CursorPaginationFilterSchema` exposes the same pair (with `cursor` /
+    `limit` instead of `page` / `page_size`).
+
 ### Cursor — when the table is large
 
 Cursor pagination scales better than offset on large tables (no

{tempest_fastapi_sdk-0.61.0 → tempest_fastapi_sdk-0.63.0}/docs/recipes/database.md

@@ -651,6 +651,24 @@ class UserRepository(BaseRepository[UserModel]):
 filtrada, então joins custom ainda reportam total correto. Quando
 `order_by` é `None`, ordena por `created_at desc`.
 
+!!! tip "Encaminhe o schema sem desempacotar à mão"
+    O par `get_conditions()` / `get_pagination_conditions()` cobre os dois
+    lados do filtro: o primeiro devolve só os filtros de domínio, o segundo
+    só as chaves de paginação (`page`, `page_size`, `order_by`,
+    `ascending`). Assim o service repassa o filtro direto, sem `**f` — que
+    vazaria filtros de domínio (`is_active`, etc.) como kwargs que o
+    repository não aceita:
+
+    ```python
+    data = await repo.paginate(
+        filters=f.get_conditions(),
+        **f.get_pagination_conditions(),
+    )
+    ```
+
+    `CursorPaginationFilterSchema` tem o mesmo par (com `cursor` / `limit`
+    no lugar de `page` / `page_size`).
+
 ### Cursor — quando a tabela é grande
 
 A paginação por cursor escala melhor que offset em tabelas grandes (sem

{tempest_fastapi_sdk-0.61.0 → tempest_fastapi_sdk-0.63.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "tempest-fastapi-sdk"
-version = "0.61.0"
+version = "0.63.0"
 description = "Shared FastAPI building blocks: base schemas, ORM model, async repository, exceptions, pagination and settings — the conventions used across Tempest projects."
 readme = "README.md"
 requires-python = ">=3.11"

{tempest_fastapi_sdk-0.61.0 → tempest_fastapi_sdk-0.63.0}/tempest_fastapi_sdk/__init__.py

@@ -301,7 +301,7 @@ from tempest_fastapi_sdk.websockets import (
     make_websocket_router,
 )
 
-__version__: str = "0.61.0"
+__version__: str = "0.63.0"
 
 __all__: list[str] = [
     "BASE_COLUMN_ORDER",

{tempest_fastapi_sdk-0.61.0 → tempest_fastapi_sdk-0.63.0}/tempest_fastapi_sdk/api/dependencies/auth.py

@@ -139,6 +139,7 @@ def make_jwt_user_dependency(
     bearer_scheme: HTTPBearer | None = None,
     subject_claim: str = "sub",
     error_message: str = "Authorization token is missing or invalid",
+    session_dependency: Callable[..., Any] | None = None,
 ) -> Callable[..., Coroutine[Any, Any, Any]]:
     """Build a FastAPI dependency that returns the authenticated user.
 
@@ -150,15 +151,33 @@ def make_jwt_user_dependency(
     4. Awaits ``user_loader(<id>)`` and returns whatever it yields.
 
     ``user_loader`` is the single seam where the service maps
-    ``payload[subject_claim]`` to an actual user. It's an async
-    callable (so it can open / close its own DB session) — the SDK
-    doesn't impose a session shape.
+    ``payload[subject_claim]`` to an actual user.
+
+    **Session sharing.** When ``session_dependency`` is given, the
+    returned dependency declares it as a sub-dependency and calls the
+    two-argument ``user_loader(subject, session)`` with the
+    **request-scoped** session. Because FastAPI caches a sub-dependency
+    by its callable within a single request, the authenticated user is
+    loaded on the *same* session the request's repositories use — so the
+    instance stays attached and can be mutated / refreshed without the
+    ``InvalidRequestError: Instance is not persistent within this
+    Session`` that a per-loader private session would cause. Pass the
+    **exact** callable your repositories depend on (e.g.
+    ``db.session_dependency``); a different wrapper would resolve to a
+    second, distinct session and defeat the sharing.
+
+    When ``session_dependency`` is ``None`` the loader is called with a
+    single argument (``user_loader(subject)``) and owns its own session
+    lifecycle — useful outside a request scope, but it yields a
+    **detached** instance.
 
     Args:
         tokens (JWTUtils): The JWT helper used to verify the token.
         user_loader (Callable[..., Coroutine[Any, Any, Any]]): Async
             callable that receives the subject (typically the user id
-            as a string) and returns the loaded user. Raise
+            as a string) and returns the loaded user. When
+            ``session_dependency`` is set it is called as
+            ``user_loader(subject, session)``. Raise
             :class:`UnauthorizedException` or
             :class:`NotFoundException` from inside the loader when the
             user no longer exists.
@@ -169,6 +188,10 @@ def make_jwt_user_dependency(
             Defaults to ``"sub"``.
         error_message (str): Message attached to the raised
             :class:`UnauthorizedException` when ``soft`` is ``False``.
+        session_dependency (Callable[..., Any] | None): The
+            request-scoped session provider to share with repositories.
+            When set, ``user_loader`` is called with ``(subject,
+            session)``.
 
     Returns:
         Callable[..., Coroutine[Any, Any, Any]]: An async FastAPI
@@ -181,20 +204,41 @@ def make_jwt_user_dependency(
         error_message=error_message,
     )
 
-    async def _current_user(
-        payload: dict[str, Any] | None = Depends(decode_bearer),
-    ) -> Any:
-        if payload is None:
-            return None
-        subject = payload.get(subject_claim)
-        if subject is None:
-            if soft:
+    if session_dependency is None:
+
+        async def _current_user_owns_session(
+            payload: dict[str, Any] | None = Depends(decode_bearer),
+        ) -> Any:
+            if payload is None:
                 return None
-            raise UnauthorizedException(message=error_message)
-        return await user_loader(subject)
+            subject = payload.get(subject_claim)
+            if subject is None:
+                if soft:
+                    return None
+                raise UnauthorizedException(message=error_message)
+            return await user_loader(subject)
+
+        dependency = _current_user_owns_session
+
+    else:
+
+        async def _current_user_shared_session(
+            payload: dict[str, Any] | None = Depends(decode_bearer),
+            session: Any = Depends(session_dependency),
+        ) -> Any:
+            if payload is None:
+                return None
+            subject = payload.get(subject_claim)
+            if subject is None:
+                if soft:
+                    return None
+                raise UnauthorizedException(message=error_message)
+            return await user_loader(subject, session)
+
+        dependency = _current_user_shared_session
 
-    _current_user.__doc__ = "Decode the bearer JWT and resolve the authenticated user."
-    return _current_user
+    dependency.__doc__ = "Decode the bearer JWT and resolve the authenticated user."
+    return dependency
 
 
 def make_role_dependency(

{tempest_fastapi_sdk-0.61.0 → tempest_fastapi_sdk-0.63.0}/tempest_fastapi_sdk/auth/service.py

@@ -528,11 +528,12 @@ class UserAuthService:
         self,
         *,
         soft: bool = False,
+        session_dependency: Callable[..., Any] | None = None,
     ) -> Callable[..., Coroutine[Any, Any, Any]]:
         """Build a FastAPI dependency that returns the authenticated user.
 
         Wraps :func:`tempest_fastapi_sdk.make_jwt_user_dependency` with
-        this service's own :class:`JWTUtils` and :meth:`load_user`, so
+        this service's own :class:`JWTUtils` and :meth:`get_user`, so
         the bearer token is verified with the **same** secret the
         service signs with — there is no second ``JWTUtils`` to keep in
         sync. Mount it on any of your routes:
@@ -542,23 +543,49 @@ class UserAuthService:
             ...     soft=True
             ... )
 
-        Requires the service to have been built with ``db=`` (consumed
-        lazily by :meth:`load_user` on the first authenticated request).
+        The authenticated user is loaded on the **request-scoped**
+        session (``self.db.session_dependency`` by default), so it is
+        attached to the same session the request's repositories use and
+        can be mutated / refreshed without an
+        ``InvalidRequestError: Instance is not persistent within this
+        Session``. If your repositories depend on a different session
+        callable (e.g. a project-local ``get_session`` wrapper), pass it
+        as ``session_dependency`` so both resolve to the *same* request
+        session — FastAPI caches a sub-dependency by its callable, so a
+        distinct wrapper would open a second session and detach the user.
+
+        Requires the service to have been built with ``db=``.
 
         Args:
             soft (bool): When ``True``, the dependency returns ``None``
                 instead of raising on a missing / invalid token — for
                 endpoints that work both authenticated and anonymous.
+            session_dependency (Callable[..., Any] | None): The
+                request-scoped session provider to share with
+                repositories. Defaults to ``self.db.session_dependency``.
 
         Returns:
             Callable[..., Coroutine[Any, Any, Any]]: An async FastAPI
             dependency yielding the user (or ``None`` in soft mode).
+
+        Raises:
+            RuntimeError: When the service was created without ``db=``.
         """
+        if self.db is None:
+            raise RuntimeError(
+                "UserAuthService was created without `db=`; pass an "
+                "AsyncDatabaseManager to use current_user_dependency."
+            )
         from tempest_fastapi_sdk.api.dependencies.auth import (
             make_jwt_user_dependency,
         )
 
-        return make_jwt_user_dependency(self.jwt, self.load_user, soft=soft)
+        return make_jwt_user_dependency(
+            self.jwt,
+            self.get_user,
+            soft=soft,
+            session_dependency=session_dependency or self.db.session_dependency,
+        )
 
     # ------------------------------------------------------------------
     # Authorization guards (imperative, on an already-loaded user)

{tempest_fastapi_sdk-0.61.0 → tempest_fastapi_sdk-0.63.0}/tempest_fastapi_sdk/db/repository.py

@@ -9,7 +9,16 @@ from datetime import date, datetime
 from typing import Any, Generic, List, TypeVar, cast
 from uuid import UUID
 
-from sqlalchemy import CursorResult, Select, delete, func, insert, select, update
+from sqlalchemy import (
+    CursorResult,
+    Select,
+    delete,
+    func,
+    insert,
+    inspect,
+    select,
+    update,
+)
 from sqlalchemy.exc import IntegrityError
 from sqlalchemy.ext.asyncio import AsyncSession
 
@@ -337,14 +346,23 @@ class BaseRepository(Generic[ModelType]):
         ``if isinstance(x, UUID): ... else: ...`` boilerplate services
         reimplement whenever a method takes ``UUID | Model``.
 
+        When given a **detached** instance (one whose session has been
+        closed — e.g. a user loaded by an auth dependency on its own
+        short-lived session) it is re-attached to this repository's
+        session via :meth:`AsyncSession.merge`. Returning it as-is would
+        later raise ``InvalidRequestError: Instance is not persistent
+        within this Session`` on the first ``commit`` / ``refresh``.
+        ``merge`` issues a ``SELECT`` only when the row is not already in
+        this session's identity map.
+
         Args:
             ref (UUID | ModelType): The primary key to look up, or an
-                already-loaded instance to return as-is.
+                already-loaded instance to attach and return.
             for_update (bool): Whether to acquire a row-level lock when
                 ``ref`` is a ``UUID`` (ignored when an instance is given).
 
         Returns:
-            ModelType: The resolved instance.
+            ModelType: The resolved instance, attached to this session.
 
         Raises:
             AppException: ``self.not_found_exception`` when ``ref`` is a
@@ -352,6 +370,8 @@ class BaseRepository(Generic[ModelType]):
         """
         if isinstance(ref, UUID):
             return await self.get_by_id(ref, for_update=for_update)
+        if inspect(ref).detached:
+            return await self.session.merge(ref)
         return ref
 
     async def exists(self, filters: dict[str, Any]) -> bool:

{tempest_fastapi_sdk-0.61.0 → tempest_fastapi_sdk-0.63.0}/tempest_fastapi_sdk/schemas/pagination.py

@@ -94,6 +94,34 @@ class BasePaginationFilterSchema(BaseSchema):
             exclude=["page", "page_size", "order_by", "ascending"],
         )
 
+    def get_pagination_conditions(self) -> dict[str, Any]:
+        """Return only the pagination and sort keyword arguments.
+
+        Complements :meth:`get_conditions`: where that method strips the
+        pagination keys to expose the domain filters, this one keeps only
+        the pagination keys (``page``, ``page_size``, ``order_by``,
+        ``ascending``). Together they let a service forward a filter
+        schema to :meth:`BaseRepository.paginate` without manually
+        unpacking the model, which would also leak domain filters such as
+        ``is_active`` into kwargs the repository does not accept:
+
+        .. code-block:: python
+
+            data = await repo.paginate(
+                filters=f.get_conditions(),
+                **f.get_pagination_conditions(),
+            )
+
+        Returns:
+            dict[str, Any]: The pagination/sort keyword arguments.
+        """
+        return {
+            "page": self.page,
+            "page_size": self.page_size,
+            "order_by": self.order_by,
+            "ascending": self.ascending,
+        }
+
 
 T = TypeVar("T", bound=BaseSchema)
 
@@ -210,6 +238,34 @@ class CursorPaginationFilterSchema(BaseSchema):
             exclude=["cursor", "limit", "order_by", "ascending"],
         )
 
+    def get_pagination_conditions(self) -> dict[str, Any]:
+        """Return only the cursor pagination and sort keyword arguments.
+
+        Complements :meth:`get_conditions`: where that method strips the
+        pagination keys to expose the domain filters, this one keeps only
+        the pagination keys (``cursor``, ``limit``, ``order_by``,
+        ``ascending``). Together they let a service forward a filter
+        schema to :meth:`BaseRepository.cursor_paginate` without manually
+        unpacking the model, which would also leak domain filters into
+        kwargs the repository does not accept:
+
+        .. code-block:: python
+
+            data = await repo.cursor_paginate(
+                filters=f.get_conditions(),
+                **f.get_pagination_conditions(),
+            )
+
+        Returns:
+            dict[str, Any]: The cursor pagination/sort keyword arguments.
+        """
+        return {
+            "cursor": self.cursor,
+            "limit": self.limit,
+            "order_by": self.order_by,
+            "ascending": self.ascending,
+        }
+
 
 class CursorPaginationSchema(BaseSchema, Generic[T]):
     """Generic envelope returned by cursor-paginated endpoints.

{tempest_fastapi_sdk-0.61.0 → tempest_fastapi_sdk-0.63.0}/tests/auth/test_service.py

@@ -9,7 +9,7 @@ from typing import Any
 import pytest
 from fastapi import Depends, FastAPI
 from httpx import ASGITransport, AsyncClient
-from sqlalchemy import select
+from sqlalchemy import inspect, select
 from sqlalchemy.ext.asyncio import (
     AsyncSession,
     async_sessionmaker,
@@ -1507,6 +1507,68 @@ class TestCurrentUserResolution:
         finally:
             await db.disconnect()
 
+    async def test_current_user_attached_to_request_session(self) -> None:
+        """The authenticated user is attached to the request-scoped session.
+
+        Regression for ``InvalidRequestError: Instance is not persistent
+        within this Session``: loading the user on a private auth session
+        yielded a *detached* instance, so mutating it on the request's
+        repository session never persisted (and ``refresh`` raised). The
+        dependency now shares ``db.session_dependency`` with the route, so
+        the user is live and a mutation commits.
+        """
+        db, service = await _db_service()
+        try:
+            async with db.get_session_context() as s:
+                user, _ = await service.signup(
+                    s,
+                    email="attached@a.com",
+                    password="strong-pass-12-chars",
+                )
+                user.is_active = True
+                await s.commit()
+                await s.refresh(user)
+            user_id = user.id
+            access, _ = service.issue_jwt_pair(user)
+
+            get_current_user = service.current_user_dependency()
+            app = FastAPI()
+
+            @app.post("/deactivate")
+            async def deactivate(
+                current: Any = Depends(get_current_user),
+                session: AsyncSession = Depends(db.session_dependency),
+            ) -> dict[str, bool]:
+                # The user is attached to this very request session: its
+                # underlying sync Session is the dependency's shared one.
+                same_session = inspect(current).session is session.sync_session
+                current.is_active = False
+                await session.commit()
+                await session.refresh(current)  # would raise if detached
+                return {"same_session": same_session}
+
+            async with AsyncClient(
+                transport=ASGITransport(app=app), base_url="http://t"
+            ) as client:
+                resp = await client.post(
+                    "/deactivate", headers={"Authorization": f"Bearer {access}"}
+                )
+                assert resp.status_code == 200
+                assert resp.json() == {"same_session": True}
+
+            # The mutation actually hit the database.
+            async with db.get_session_context() as verify:
+                reloaded = await service.get_user(user_id, verify)
+                assert reloaded.is_active is False
+        finally:
+            await db.disconnect()
+
+    async def test_current_user_without_db_raises(self) -> None:
+        """``current_user_dependency`` needs ``db=`` to share its session."""
+        service = _service()  # built without db=
+        with pytest.raises(RuntimeError):
+            service.current_user_dependency()
+
     async def test_current_user_dependency_soft_returns_none(self) -> None:
         db, service = await _db_service()
         try: