fastapi-basekit 0.5.0__tar.gz → 0.5.3__tar.gz

{fastapi_basekit-0.5.0 → fastapi_basekit-0.5.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: fastapi-basekit
-Version: 0.5.0
+Version: 0.5.3
 Summary: Utilities and base classes for FastAPI async projects (Beanie, SQLAlchemy or SQLModel)
 Author-email: Jerson Moreno <jerson.ml820@hotmail.com>
 License: MIT

{fastapi_basekit-0.5.0 → fastapi_basekit-0.5.3}/fastapi_basekit/aio/beanie/repository/base.py

@@ -215,6 +215,19 @@ class BaseRepository(Generic[ModelT]):
                     exprs.append(field_attr.id == _coerce_objectid(v))
                     continue
 
+            # Clave no resoluble (typo, campo inexistente, nesting mal escrito).
+            # Se descarta — pero se AVISA: si la clave venía de `get_filters`
+            # (scoping por tenant/owner), su desaparición silenciosa deja el
+            # listado sin filtrar → fuga cross-tenant (IDOR). El warning hace
+            # visible la pérdida en logs/Sentry en vez de fallar en silencio.
+            logger.warning(
+                "build_filter_query: filtro '%s' descartado (no resuelve a "
+                "ningún campo de %s). Si era un filtro de scoping, el listado "
+                "queda SIN ese filtro.",
+                k,
+                getattr(self.model, "__name__", self.model),
+            )
+
         # Raw MongoDB filters go first so Beanie processes them as a dict condition
         query_args: list = ([raw_filters] if raw_filters else []) + exprs
         query = self.model.find(*query_args, **self._get_query_kwargs(**kwargs))

{fastapi_basekit-0.5.0 → fastapi_basekit-0.5.3}/fastapi_basekit/aio/controller/base.py

@@ -79,12 +79,41 @@ class BaseController:
     # DRF Style: Permisos globales por defecto
     permission_classes: ClassVar[List[Type[BasePermission]]] = []
 
-    # ClassVar so cbv (fastapi-restful) does NOT promote it to a query param.
-    # A plain `Optional[str]` annotation here leaks a spurious `action` query
-    # parameter onto every mounted endpoint. `prepare_action` still assigns
-    # `self.action` (instance attr) at runtime, which works fine.
-    action: ClassVar[Optional[str]] = None
     request: Request
+
+    @property
+    def action(self) -> Optional[str]:
+        """Acción canónica del request actual.
+
+        Preferencia: la que fijó ``prepare_action`` (``list``/``retrieve``/…).
+        Fallback: el nombre de la función de endpoint que FastAPI está
+        ejecutando (``create``/``update``/``retrieve``/…), leído de
+        ``request.scope["endpoint"]``. Así un endpoint CUSTOM que llama
+        ``format_response`` sin ``prepare_action`` igual obtiene su acción para
+        ``get_schema_class``/``get_filters`` — antes caía a ``None`` y devolvía
+        el schema por defecto (de lista), rompiendo la validación del
+        ``response_model`` de detalle.
+
+        Es una ``property`` (no un campo anotado) a propósito: cbv
+        (fastapi-restful) NO la promueve a query param, así que no reaparece el
+        ``action`` espurio en la firma de cada endpoint.
+
+        OJO: NO reemplaza a ``prepare_action`` para permisos. El fallback solo
+        informa el schema/scoping; ``check_permissions`` sigue corriendo solo si
+        el endpoint llamó ``prepare_action`` (o delega en un CRUD base)."""
+        prepared = getattr(self, "_basekit_prepared_action", None)
+        if prepared is not None:
+            return prepared
+        request = getattr(self, "request", None)
+        scope = getattr(request, "scope", None) if request is not None else None
+        endpoint = scope.get("endpoint") if isinstance(scope, dict) else None
+        return getattr(endpoint, "__name__", None)
+
+    @action.setter
+    def action(self, value: Optional[str]) -> None:
+        """Permite fijar la acción a mano (``self.action = "list"``) — compat
+        con código pre-property. Escribe el backing attr que lee el getter."""
+        self._basekit_prepared_action = value
     _params_excluded_fields: ClassVar[Set[str]] = {
         "self",
         "page",
@@ -135,7 +164,9 @@ class BaseController:
         """
         if getattr(self, "_basekit_prepared_action", None) == action_name:
             return
-        self.action = action_name
+        # `action` es una property de solo-lectura que expone
+        # `_basekit_prepared_action` (con fallback al nombre del endpoint), así
+        # que fijamos el backing attr, no `self.action` directamente.
         self._basekit_prepared_action = action_name
         # Propagate the canonical CRUD action ("list"/"retrieve"/...) to the
         # service so `get_kwargs_query` / `get_filters` can branch on it. The
@@ -233,13 +264,33 @@ class BaseController:
         # raw value when the schema doesn't fit (custom-action endpoints
         # often return ad-hoc dicts that don't match the controller's
         # default schema_class — those should pass through untouched).
-        if isinstance(data, list):
-            data_dicts = [self.to_dict(item) for item in data]
-            try:
-                adapter = TypeAdapter(List[schema])
-                data_parsed = adapter.validate_python(data_dicts)
-            except Exception:
-                data_parsed = data_dicts
+        #
+        # Cuando un endpoint custom ya devuelve un modelo Pydantic específico
+        # (distinto a ``schema``), no lo re-casteeamos al schema por defecto:
+        # eso rompe el ``response_model`` declarado en la ruta y provoca
+        # ResponseValidationError. Se convierte a dict limpio y FastAPI se
+        # encarga de validar/serializar contra el response_model del endpoint.
+        if isinstance(data, BaseModel):
+            if isinstance(data, schema):
+                data_parsed = data
+            else:
+                data_parsed = self.to_dict(data)
+
+        elif isinstance(data, list):
+            # Si la lista contiene modelos Pydantic distintos al schema por
+            # defecto, respetarlos; de lo contrario validar normalmente.
+            if data and all(
+                isinstance(item, BaseModel) and not isinstance(item, schema)
+                for item in data
+            ):
+                data_parsed = [self.to_dict(item) for item in data]
+            else:
+                data_dicts = [self.to_dict(item) for item in data]
+                try:
+                    adapter = TypeAdapter(List[schema])
+                    data_parsed = adapter.validate_python(data_dicts)
+                except Exception:
+                    data_parsed = data_dicts
 
         elif isinstance(data, dict):
             try:

{fastapi_basekit-0.5.0 → fastapi_basekit-0.5.3}/fastapi_basekit/aio/sqlalchemy/repository/base.py

@@ -11,6 +11,7 @@ from typing import (
     Union,
 )
 from uuid import UUID
+import logging
 
 from sqlalchemy import Select, and_, or_, select, func
 from sqlalchemy.ext.asyncio import AsyncSession
@@ -18,6 +19,8 @@ from sqlalchemy.orm import Relationship, joinedload, selectinload
 
 from ....exceptions.api_exceptions import NotFoundException
 
+logger = logging.getLogger(__name__)
+
 #: Tipo del modelo ORM que gestiona el repositorio. Parametrízalo al declarar
 #: la subclase — ``class UserRepository(BaseRepository[User])`` — para que
 #: ``get``/``create``/``update``/``list_paginated`` devuelvan ``User`` tipado
@@ -165,6 +168,17 @@ class BaseRepository(Generic[ModelT]):
             attr, field_joins = self._resolve_field_path(resolve_path)
 
             if attr is None:
+                # Filtro no resoluble (typo, columna/relación inexistente). Se
+                # descarta — pero se AVISA: si venía de `get_filters` (scoping
+                # por tenant/owner), su desaparición silenciosa deja el listado
+                # sin filtrar → fuga cross-tenant (IDOR). El warning hace
+                # visible la pérdida en logs en vez de fallar en silencio.
+                logger.warning(
+                    "filtro '%s' descartado (no resuelve a ningún campo de %s). "
+                    "Si era un filtro de scoping, el listado queda SIN ese filtro.",
+                    filter_path,
+                    getattr(self.model, "__name__", self.model),
+                )
                 continue
 
             joins_to_apply.update(field_joins)

{fastapi_basekit-0.5.0 → fastapi_basekit-0.5.3}/fastapi_basekit/aio/sqlmodel/repository/base.py

@@ -12,6 +12,8 @@ from typing import (
 )
 from uuid import UUID
 
+import logging
+
 from sqlmodel import select
 from sqlmodel.ext.asyncio.session import AsyncSession
 from sqlalchemy import and_, or_, func, Select
@@ -19,6 +21,8 @@ from sqlalchemy.orm import Relationship, joinedload, selectinload
 
 from ....exceptions.api_exceptions import NotFoundException
 
+logger = logging.getLogger(__name__)
+
 #: Tipo del modelo SQLModel que gestiona el repositorio. Parametrízalo al
 #: declarar la subclase — ``class UserRepository(BaseRepository[User])``.
 ModelT = TypeVar("ModelT")
@@ -140,6 +144,17 @@ class BaseRepository(Generic[ModelT]):
             attr, field_joins = self._resolve_field_path(resolve_path)
 
             if attr is None:
+                # Filtro no resoluble (typo, columna/relación inexistente). Se
+                # descarta — pero se AVISA: si venía de `get_filters` (scoping
+                # por tenant/owner), su desaparición silenciosa deja el listado
+                # sin filtrar → fuga cross-tenant (IDOR). El warning hace
+                # visible la pérdida en logs en vez de fallar en silencio.
+                logger.warning(
+                    "filtro '%s' descartado (no resuelve a ningún campo de %s). "
+                    "Si era un filtro de scoping, el listado queda SIN ese filtro.",
+                    filter_path,
+                    getattr(self.model, "__name__", self.model),
+                )
                 continue
 
             joins_to_apply.update(field_joins)

{fastapi_basekit-0.5.0 → fastapi_basekit-0.5.3}/fastapi_basekit/exceptions/handler.py

@@ -5,6 +5,34 @@ from fastapi.exceptions import RequestValidationError
 from fastapi.responses import JSONResponse
 from pydantic import ValidationError
 
+
+def _get_cors_headers(request: Request) -> Dict[str, str]:
+    """Extrae headers CORS del ``Origin`` del request para respuestas de error.
+
+    Cuando una respuesta se genera desde un handler que corre debajo del
+    CORSMiddleware los headers CORS se agregan automáticamente.  Pero si la
+    respuesta se genera desde ServerErrorMiddleware (por encima de CORS) o
+    desde cualquier otro camino que no pase por el middleware, los headers
+    faltan y el browser reporta un falso error CORS.  Esta función permite
+    agregarlos defensivamente desde cualquier handler.
+    """
+    origin = request.headers.get("origin")
+    if not origin:
+        return {}
+    return {
+        "Access-Control-Allow-Origin": origin,
+        "Access-Control-Allow-Credentials": "true",
+        "Vary": "Origin",
+    }
+
+
+def _apply_cors(request: Request, response: JSONResponse) -> JSONResponse:
+    """Agrega headers CORS defensivos a una ``JSONResponse``."""
+    headers = _get_cors_headers(request)
+    if headers:
+        response.headers.update(headers)
+    return response
+
 try:  # pragma: no cover - dependencia opcional
     from pymongo.errors import DuplicateKeyError  # type: ignore
 except ImportError:  # pragma: no cover
@@ -35,7 +63,10 @@ async def api_exception_handler(request: Request, exc: APIException):
     response = BaseResponse(
         status=exc.status_code, message=exc.message, data=exc.data
     )
-    return JSONResponse(status_code=exc.status, content=response.model_dump())
+    return _apply_cors(
+        request,
+        JSONResponse(status_code=exc.status, content=response.model_dump()),
+    )
 
 
 async def domain_error_handler(request: Request, exc: DomainError):
@@ -46,8 +77,11 @@ async def domain_error_handler(request: Request, exc: DomainError):
     a `exc.http_status()` con el mismo envelope `BaseResponse` que el resto.
     """
     response = BaseResponse(status=exc.code, message=exc.message, data=None)
-    return JSONResponse(
-        status_code=exc.http_status(), content=response.model_dump()
+    return _apply_cors(
+        request,
+        JSONResponse(
+            status_code=exc.http_status(), content=response.model_dump()
+        ),
     )
 
 
@@ -81,9 +115,12 @@ async def document_not_found_handler(request: Request, exc: DocumentNotFound):
         message="Documento no encontrado",
         data={"detail": str(exc)},
     )
-    return JSONResponse(
-        status_code=status.HTTP_404_NOT_FOUND,
-        content=response.model_dump(),
+    return _apply_cors(
+        request,
+        JSONResponse(
+            status_code=status.HTTP_404_NOT_FOUND,
+            content=response.model_dump(),
+        ),
     )
 
 
@@ -96,9 +133,12 @@ async def global_exception_handler(request: Request, exc: Exception):
         message="Ocurrió un error desconocido",
         data={"detail": str(exc)},
     )
-    return JSONResponse(
-        status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
-        content=response.model_dump(),
+    return _apply_cors(
+        request,
+        JSONResponse(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            content=response.model_dump(),
+        ),
     )
 
 
@@ -119,9 +159,12 @@ async def value_exception_handler(
         data=str(error_details),
     )
 
-    return JSONResponse(
-        status_code=status.HTTP_400_BAD_REQUEST,
-        content=response.model_dump(mode="json"),
+    return _apply_cors(
+        request,
+        JSONResponse(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            content=response.model_dump(mode="json"),
+        ),
     )
 
 
@@ -139,9 +182,12 @@ async def request_validation_handler(
         message="Error de validación",
         data=exc.errors(),
     )
-    return JSONResponse(
-        status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
-        content=response.model_dump(mode="json"),
+    return _apply_cors(
+        request,
+        JSONResponse(
+            status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
+            content=response.model_dump(mode="json"),
+        ),
     )
 
 
@@ -153,9 +199,12 @@ async def integrity_error_handler(request: Request, exc: Exception):
         message="Registro ya existe o viola una restricción de integridad",
         data={"detail": str(detail) if detail is not None else str(exc)},
     )
-    return JSONResponse(
-        status_code=status.HTTP_400_BAD_REQUEST,
-        content=response.model_dump(mode="json"),
+    return _apply_cors(
+        request,
+        JSONResponse(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            content=response.model_dump(mode="json"),
+        ),
     )
 
 

{fastapi_basekit-0.5.0 → fastapi_basekit-0.5.3}/fastapi_basekit/templates/project/{{cookiecutter.project_slug}}/app/utils/exception_handlers.py

@@ -10,6 +10,7 @@ from fastapi_basekit.exceptions.api_exceptions import (
     DatabaseIntegrityException,
     ValidationException,
 )
+from fastapi_basekit.exceptions.handler import _apply_cors  # noqa: F401
 from fastapi_basekit.schema.base import BaseResponse
 from pydantic import ValidationError
 {% if cookiecutter.orm == "sqlalchemy" -%}
@@ -19,7 +20,10 @@ from sqlalchemy.exc import IntegrityError
 
 async def api_exception_handler(request: Request, exc: APIException):
     response = BaseResponse(status=exc.status_code, message=exc.message, data=exc.data)
-    return JSONResponse(status_code=exc.status, content=response.model_dump())
+    return _apply_cors(
+        request,
+        JSONResponse(status_code=exc.status, content=response.model_dump()),
+    )
 
 
 async def validation_exception_handler(request: Request, exc: RequestValidationError):
@@ -28,7 +32,10 @@ async def validation_exception_handler(request: Request, exc: RequestValidationE
 
 async def database_exception_handler(request: Request, exc: DatabaseIntegrityException):
     response = BaseResponse(status=exc.status_code, message=exc.message, data=exc.data)
-    return JSONResponse(status_code=exc.status, content=response.model_dump())
+    return _apply_cors(
+        request,
+        JSONResponse(status_code=exc.status, content=response.model_dump()),
+    )
 
 
 async def value_exception_handler(request: Request, exc: Union[ValidationError, ValueError]):
@@ -42,9 +49,12 @@ async def value_exception_handler(request: Request, exc: Union[ValidationError,
         message="Field validation error",
         data=str(error_details),
     )
-    return JSONResponse(
-        status_code=status.HTTP_400_BAD_REQUEST,
-        content=response.model_dump(mode="json"),
+    return _apply_cors(
+        request,
+        JSONResponse(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            content=response.model_dump(mode="json"),
+        ),
     )
 
 
@@ -65,9 +75,12 @@ async def integrity_error_handler(request: Request, exc: IntegrityError):
         message = "Database integrity error"
 
     response = BaseResponse(status="DATABASE_INTEGRITY_ERROR", message=message, data=None)
-    return JSONResponse(
-        status_code=status.HTTP_400_BAD_REQUEST,
-        content=response.model_dump(),
+    return _apply_cors(
+        request,
+        JSONResponse(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            content=response.model_dump(),
+        ),
     )
 {% endif %}
 
@@ -78,7 +91,10 @@ async def global_exception_handler(request: Request, exc: Exception):
         message="Unknown error",
         data={"detail": str(exc)},
     )
-    return JSONResponse(
-        status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
-        content=response.model_dump(),
+    return _apply_cors(
+        request,
+        JSONResponse(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            content=response.model_dump(),
+        ),
     )

{fastapi_basekit-0.5.0 → fastapi_basekit-0.5.3}/fastapi_basekit.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: fastapi-basekit
-Version: 0.5.0
+Version: 0.5.3
 Summary: Utilities and base classes for FastAPI async projects (Beanie, SQLAlchemy or SQLModel)
 Author-email: Jerson Moreno <jerson.ml820@hotmail.com>
 License: MIT

{fastapi_basekit-0.5.0 → fastapi_basekit-0.5.3}/fastapi_basekit.egg-info/SOURCES.txt

@@ -121,6 +121,7 @@ tests/test_crud_controller.py
 tests/test_crud_sqlmodel_repository_service.py
 tests/test_exception_handlers.py
 tests/test_filter_operators.py
+tests/test_format_response_schema_override.py
 tests/test_generics_optional_and_cache.py
 tests/test_generics_wiring.py
 tests/test_jwt_config_robustness.py

{fastapi_basekit-0.5.0 → fastapi_basekit-0.5.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "fastapi-basekit"
-version = "0.5.0"
+version = "0.5.3"
 description = "Utilities and base classes for FastAPI async projects (Beanie, SQLAlchemy or SQLModel)"
 readme = "README.md"
 requires-python = ">=3.11"

{fastapi_basekit-0.5.0 → fastapi_basekit-0.5.3}/tests/test_action_param_leak.py

@@ -1,7 +1,7 @@
 """Regresión: cbv NO debe exponer `action` como query param.
 
-`BaseController.action` se declara `ClassVar` precisamente para que
-fastapi-restful (cbv) no lo promueva a parámetro de query en cada ruta
+`BaseController.action` es una `@property` (no un campo anotado) precisamente
+para que fastapi-restful (cbv) no lo promueva a parámetro de query en cada ruta
 montada. Antes de 0.4.0 aparecía un `?action=` espurio en toda mutación.
 """
 
@@ -49,3 +49,42 @@ def test_action_is_filterable_not_excluded():
 
     assert "action" not in SQLAlchemyBaseController._params_excluded_fields
     assert "action" not in BaseController._params_excluded_fields
+
+
+def test_action_falls_back_to_endpoint_name():
+    """`action` resuelve al nombre de la función de endpoint cuando el endpoint
+    custom NO llamó `prepare_action`.
+
+    Antes `action` era un ClassVar que quedaba en None → `get_schema_class`
+    devolvía el schema por defecto (de lista) y la validación del `response_model`
+    de detalle fallaba. Ahora es una property con fallback a
+    `request.scope["endpoint"].__name__`. Sigue sin filtrarse como query param
+    (test de arriba) porque una property no es un campo anotado.
+    """
+    from fastapi_basekit.aio.controller.base import BaseController
+
+    class C(BaseController):
+        pass
+
+    # Sin request ni prepare_action → None (no rompe).
+    assert C().action is None
+
+    # `prepare_action` (vía backing attr) gana sobre el fallback.
+    c = C()
+    c._basekit_prepared_action = "list"
+    assert c.action == "list"
+
+    # Fallback: lee el nombre de la función de endpoint activa.
+    def create():  # nombre = acción canónica
+        ...
+
+    class _Req:
+        scope = {"endpoint": create}
+
+    c2 = C()
+    c2.request = _Req()
+    assert c2.action == "create"
+
+    # Setter de compat: `self.action = "x"` sigue funcionando.
+    c2.action = "update"
+    assert c2.action == "update"

{fastapi_basekit-0.5.0 → fastapi_basekit-0.5.3}/tests/test_beanie_repository_regression.py

@@ -163,6 +163,40 @@ async def test_filter_scalar_field(data):
     assert {e.name for e in rows} == {"Ana", "Ciro"}
 
 
+@pytest.mark.asyncio
+async def test_mongo_style_scoping_keys_pass_through(data):
+    """`user.$id` / `$or` (patrón de scoping en get_filters) NO se descartan:
+    se aplican como filtro Mongo crudo. Su pérdida silenciosa sería un IDOR."""
+    repo = EmployeeRepo()
+    query = repo.build_filter_query(
+        search=None,
+        search_fields=[],
+        filters={"company.$id": data["acme"].id},
+    )
+    assert query.get_filter_query() == {"company.$id": data["acme"].id}
+
+
+@pytest.mark.asyncio
+async def test_unresolvable_filter_key_warns_before_drop(data, caplog):
+    """Una clave que no resuelve a ningún campo se descarta PERO avisa: si era
+    un filtro de scoping, su desaparición silenciosa dejaría el listado sin
+    filtrar (fuga cross-tenant). El warning hace visible la pérdida."""
+    import logging
+
+    repo = EmployeeRepo()
+    with caplog.at_level(logging.WARNING):
+        query = repo.build_filter_query(
+            search=None,
+            search_fields=[],
+            filters={"nonexistent_scope": "x"},
+        )
+    assert query.get_filter_query() in ({}, {"$and": []})
+    assert any(
+        "nonexistent_scope" in r.message and "descartado" in r.message
+        for r in caplog.records
+    )
+
+
 # ---------------------------------------------------------------------------
 # get_by_field / get_by_fields
 # ---------------------------------------------------------------------------

{fastapi_basekit-0.5.0 → fastapi_basekit-0.5.3}/tests/test_exception_handlers.py

@@ -39,6 +39,10 @@ def client():
         # code sin mapeo → DEFAULT_STATUS (400)
         raise DomainError("SOMETHING", "algo pasó")
 
+    @app.get("/boom-generic")
+    async def boom_generic():
+        raise RuntimeError("error inesperado")
+
     @app.post("/echo")
     async def echo(body: Body):
         return {"n": body.n}
@@ -83,3 +87,16 @@ def test_domain_error_default_status(client):
     r = client.get("/boom-domain-default")
     assert r.status_code == 400  # DEFAULT_STATUS
     assert r.json()["status"] == "SOMETHING"
+
+
+def test_cors_headers_injected_on_error(client):
+    """Todas las respuestas de error incluyen headers CORS cuando el request
+    tiene un header ``Origin`` (defensa en profundidad)."""
+    r = client.get(
+        "/boom-generic",
+        headers={"Origin": "https://app.example.com"},
+    )
+    assert r.status_code == 500
+    assert r.headers.get("Access-Control-Allow-Origin") == "https://app.example.com"
+    assert r.headers.get("Access-Control-Allow-Credentials") == "true"
+    assert r.headers.get("Vary") == "Origin"

fastapi_basekit-0.5.3/tests/test_format_response_schema_override.py

@@ -0,0 +1,79 @@
+"""Regresión: format_response no debe re-castear modelos Pydantic específicos
+a ``schema_class`` cuando un endpoint custom devuelve otro schema."""
+
+import pytest
+from pydantic import BaseModel
+
+from fastapi_basekit.aio.controller.base import BaseController
+
+
+class _DefaultSchema(BaseModel):
+    id: int
+    name: str
+
+
+class _OtherSchema(BaseModel):
+    ok: bool
+    status: str
+
+
+class _Controller(BaseController):
+    schema_class = _DefaultSchema
+
+
+@pytest.fixture
+def controller():
+    return _Controller()
+
+
+def test_format_response_respects_other_pydantic_model(controller):
+    """Un endpoint custom que devuelve otro schema no debe romperse al forzar
+    ``schema_class`` (GatewayCheckoutResponseSchema vs GatewayChargeResponseSchema)."""
+    other = _OtherSchema(ok=True, status="paid")
+    resp = controller.format_response(other, message="OK")
+
+    # Se convierte a dict limpio y se deja pasar; FastAPI validará contra
+    # el response_model declarado en la ruta.
+    assert resp.data == {"ok": True, "status": "paid"}
+    assert isinstance(resp.data, dict)
+    assert resp.message == "OK"
+
+
+def test_format_response_keeps_default_model_instance(controller):
+    """Si ``data`` ya es instancia de ``schema_class``, se usa tal cual."""
+    item = _DefaultSchema(id=1, name="foo")
+    resp = controller.format_response(item)
+
+    assert resp.data is item
+
+
+def test_format_response_validates_plain_dict(controller):
+    """Los dicts planos siguen validándose contra ``schema_class``."""
+    resp = controller.format_response({"id": 2, "name": "bar"})
+
+    assert isinstance(resp.data, _DefaultSchema)
+    assert resp.data.id == 2
+    assert resp.data.name == "bar"
+
+
+def test_format_response_list_of_other_models(controller):
+    """Una lista de modelos Pydantic distintos a ``schema_class`` se respeta."""
+    items = [
+        _OtherSchema(ok=True, status="paid"),
+        _OtherSchema(ok=False, status="failed"),
+    ]
+    resp = controller.format_response(items)
+
+    assert resp.data == [
+        {"ok": True, "status": "paid"},
+        {"ok": False, "status": "failed"},
+    ]
+
+
+def test_format_response_list_of_dicts_still_validates(controller):
+    """Una lista de dicts sigue validándose contra ``List[schema_class]``."""
+    resp = controller.format_response([{"id": 3, "name": "baz"}])
+
+    assert isinstance(resp.data, list)
+    assert isinstance(resp.data[0], _DefaultSchema)
+    assert resp.data[0].id == 3