hexcore 6.0.2__tar.gz → 6.2.0__tar.gz

{hexcore-6.0.2/hexcore.egg-info → hexcore-6.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hexcore
-Version: 6.0.2
+Version: 6.2.0
 Summary: Núcleo reutilizable para proyectos Python con arquitectura hexagonal y event handling. Provee abstracciones, utilidades y contratos para DDD, eventos y desacoplamiento de infraestructura.
 Author-email: "David Latosefki (Indroic)" <indroic@outlook.com>
 License-Expression: MIT
@@ -155,7 +155,7 @@ pero están deprecados — ver [Versiones y soporte](#versiones-y-soporte).
 | Sesión o UoW fuera de un request | `sql.session_scope()`, `sql.uow_scope()` | `sql` |
 | Request-id correlacionado en los logs | `hx.RequestIDMiddleware`, `hx.install_request_id_logging()` | `api` |
 | Excepciones de dominio → HTTP | `hx.register_exception_handlers()` | `api` |
-| Health checks que sondean de verdad | `hx.register_health_routes()`, `hx.check_health()` | `api` |
+| Health checks que sondean de verdad | `hx.register_health_routes()`, `hx.check_health()`, `hx.HealthRoutes` | `api` |
 | Rate limiting | `hx.rate_limit()` | `api` |
 | SSE / WebSocket / límite de conexiones | `hx.sse_stream()`, `hx.ws_heartbeat()`, `hx.connection_slot()` | `api` |
 | Composición de routers | `hx.build_root_router()`, `hx.mount_routers()` | `api` |
@@ -308,6 +308,36 @@ register_health_routes(app, probes=[
 ])
 ```
 
+#### Si tu app ya publica su propio `/health`
+
+Las dos rutas se registran por separado, así que una app **ya en producción** —con su forma de
+respuesta y un cliente tipado generado desde su OpenAPI— puede quedarse con la readiness, que es
+la parte que no se escribe a mano, sin tocar el contrato que ya publicó:
+
+```python
+register_health_routes(app, liveness=False)          # sólo /health/ready
+register_health_routes(app, liveness=False, readiness_path="/_ready")
+```
+
+Y si lo que hay que conservar es la **forma del cuerpo**, `response_factory` la adapta sin
+renunciar a las sondas. El status code lo sigue decidiendo el informe, que es lo que lee el
+orquestador:
+
+```python
+register_health_routes(
+    app,
+    response_factory=lambda r: {"ok": r.status != "down", "checks": r.dependencies},
+)
+```
+
+Lo mismo desde `create_app`, sin apagar la feature entera:
+
+```python
+from hexcore.fastapi import AppFeatures, HealthRoutes, create_app
+
+app = create_app(features=AppFeatures(health=HealthRoutes(liveness=False)))
+```
+
 ### Rate limiting
 
 ```python
@@ -331,8 +361,11 @@ rate_limit(10, 60, on_backend_error="deny")
 ### Request-id correlacionado
 
 ```python
+import logging
+
 from hexcore.fastapi import get_request_id, install_request_id_logging
 
+logging.basicConfig(level=logging.INFO)          # primero: configurá el logging
 install_request_id_logging(fmt="%(asctime)s [%(request_id)s] %(message)s")
 ```
 
@@ -341,6 +374,10 @@ la traza) y lo publica en un `ContextVar` y en `request.state`. `install_request
 lo inyecta en **cada línea de log**, que es la mitad del valor: sin eso, tener el header no
 correlaciona nada.
 
+> **El orden importa.** `install_request_id_logging()` instrumenta los handlers que **ya
+> existen**. En un proceso donde nadie configuró el logging todavía no hay ninguno, así que la
+> llamada no tiene nada que hacer — y avisa con un `RuntimeWarning` en vez de quedarse callada.
+
 ### Streaming: SSE, WebSocket y límite de conexiones
 
 ```python

{hexcore-6.0.2 → hexcore-6.2.0}/README.md

@@ -110,7 +110,7 @@ pero están deprecados — ver [Versiones y soporte](#versiones-y-soporte).
 | Sesión o UoW fuera de un request | `sql.session_scope()`, `sql.uow_scope()` | `sql` |
 | Request-id correlacionado en los logs | `hx.RequestIDMiddleware`, `hx.install_request_id_logging()` | `api` |
 | Excepciones de dominio → HTTP | `hx.register_exception_handlers()` | `api` |
-| Health checks que sondean de verdad | `hx.register_health_routes()`, `hx.check_health()` | `api` |
+| Health checks que sondean de verdad | `hx.register_health_routes()`, `hx.check_health()`, `hx.HealthRoutes` | `api` |
 | Rate limiting | `hx.rate_limit()` | `api` |
 | SSE / WebSocket / límite de conexiones | `hx.sse_stream()`, `hx.ws_heartbeat()`, `hx.connection_slot()` | `api` |
 | Composición de routers | `hx.build_root_router()`, `hx.mount_routers()` | `api` |
@@ -263,6 +263,36 @@ register_health_routes(app, probes=[
 ])
 ```
 
+#### Si tu app ya publica su propio `/health`
+
+Las dos rutas se registran por separado, así que una app **ya en producción** —con su forma de
+respuesta y un cliente tipado generado desde su OpenAPI— puede quedarse con la readiness, que es
+la parte que no se escribe a mano, sin tocar el contrato que ya publicó:
+
+```python
+register_health_routes(app, liveness=False)          # sólo /health/ready
+register_health_routes(app, liveness=False, readiness_path="/_ready")
+```
+
+Y si lo que hay que conservar es la **forma del cuerpo**, `response_factory` la adapta sin
+renunciar a las sondas. El status code lo sigue decidiendo el informe, que es lo que lee el
+orquestador:
+
+```python
+register_health_routes(
+    app,
+    response_factory=lambda r: {"ok": r.status != "down", "checks": r.dependencies},
+)
+```
+
+Lo mismo desde `create_app`, sin apagar la feature entera:
+
+```python
+from hexcore.fastapi import AppFeatures, HealthRoutes, create_app
+
+app = create_app(features=AppFeatures(health=HealthRoutes(liveness=False)))
+```
+
 ### Rate limiting
 
 ```python
@@ -286,8 +316,11 @@ rate_limit(10, 60, on_backend_error="deny")
 ### Request-id correlacionado
 
 ```python
+import logging
+
 from hexcore.fastapi import get_request_id, install_request_id_logging
 
+logging.basicConfig(level=logging.INFO)          # primero: configurá el logging
 install_request_id_logging(fmt="%(asctime)s [%(request_id)s] %(message)s")
 ```
 
@@ -296,6 +329,10 @@ la traza) y lo publica en un `ContextVar` y en `request.state`. `install_request
 lo inyecta en **cada línea de log**, que es la mitad del valor: sin eso, tener el header no
 correlaciona nada.
 
+> **El orden importa.** `install_request_id_logging()` instrumenta los handlers que **ya
+> existen**. En un proceso donde nadie configuró el logging todavía no hay ninguno, así que la
+> llamada no tiene nada que hacer — y avisa con un `RuntimeWarning` en vez de quedarse callada.
+
 ### Streaming: SSE, WebSocket y límite de conexiones
 
 ```python

{hexcore-6.0.2 → hexcore-6.2.0}/hexcore/fastapi.py

@@ -21,6 +21,7 @@ _EXPORTS: dict[str, tuple[str, str]] = {
     # ── App y lifespan ────────────────────────────────────────────────────────
     "create_app": ("hexcore.infrastructure.api.app", "create_app"),
     "AppFeatures": ("hexcore.infrastructure.api.app", "AppFeatures"),
+    "HealthRoutes": ("hexcore.infrastructure.api.app", "HealthRoutes"),
     "build_lifespan": ("hexcore.infrastructure.api.lifespan", "build_lifespan"),
     "StartupStep": ("hexcore.infrastructure.api.lifespan", "StartupStep"),
     "CallableStep": ("hexcore.infrastructure.api.lifespan", "CallableStep"),
@@ -98,6 +99,7 @@ _EXPORTS: dict[str, tuple[str, str]] = {
     "HealthReport": ("hexcore.infrastructure.api.health", "HealthReport"),
     "DependencyReport": ("hexcore.infrastructure.api.health", "DependencyReport"),
     "Probe": ("hexcore.infrastructure.api.health", "Probe"),
+    "ResponseFactory": ("hexcore.infrastructure.api.health", "ResponseFactory"),
 }
 
 __all__ = sorted(_EXPORTS)

{hexcore-6.0.2 → hexcore-6.2.0}/hexcore/infrastructure/api/app.py

@@ -15,11 +15,29 @@ from fastapi.middleware.cors import CORSMiddleware
 from pydantic import BaseModel
 
 from .exception_handlers import register_exception_handlers
-from .health import Probe, register_health_routes
+from .health import Probe, ResponseFactory, register_health_routes
 from .middlewares import RequestIDMiddleware, TimingMiddleware
 from .routing import MountableRouter, mount_routers
 
-__all__ = ["AppFeatures", "create_app"]
+__all__ = ["AppFeatures", "HealthRoutes", "create_app"]
+
+
+class HealthRoutes(BaseModel):
+    """
+    Qué rutas de health cablea `create_app()`, y con qué forma.
+
+    Existe para que una app **ya publicada** pueda adoptar la readiness sin renunciar a
+    su `/health` ni al cliente tipado generado desde su OpenAPI. Los argumentos son los
+    de `register_health_routes`, agrupados para no engordar la firma de `create_app`.
+    """
+
+    model_config = {"arbitrary_types_allowed": True}
+
+    path: str = "/health"
+    liveness: bool = True
+    readiness: bool = True
+    readiness_path: str | None = None
+    response_factory: ResponseFactory | None = None
 
 
 class AppFeatures(BaseModel):
@@ -41,8 +59,16 @@ class AppFeatures(BaseModel):
     exception_handlers: bool = True
     """Mapeo de excepciones de dominio a HTTP (F5)."""
 
-    health: bool = True
-    """Rutas `/health` y `/health/ready` (F16)."""
+    health: bool | HealthRoutes = True
+    """
+    Rutas `/health` y `/health/ready` (F16).
+
+    Acepta también un `HealthRoutes` para adoptarlas **por partes**: una app que ya
+    publica su propio `/health` puede quedarse con la readiness, que es la que no se
+    escribe a mano, sin apagar la feature entera::
+
+        AppFeatures(health=HealthRoutes(liveness=False))
+    """
 
 
 def create_app(
@@ -65,7 +91,8 @@ def create_app(
         features: Qué cablear. Ver `AppFeatures`.
         routers: Routers a montar. Acepta `APIRouter` o `(APIRouter, kwargs)` (F13).
         health_probes: Sondas para `/health/ready`. Por defecto, las deducidas de la
-            configuración (F16).
+            configuración (F16). Qué rutas se registran y con qué forma se controla con
+            `AppFeatures(health=HealthRoutes(...))`.
         exception_mapping: Excepciones extra a mapear, fusionadas con el default (F5).
         **fastapi_kwargs: Se pasan tal cual a `FastAPI` (`title`, `version`,
             `docs_url`, `openapi_tags`…). Lo que pases gana sobre los defaults derivados
@@ -99,7 +126,20 @@ def create_app(
         register_exception_handlers(app, mapping=exception_mapping)
 
     if resolved_features.health:
-        register_health_routes(app, probes=health_probes)
+        health_routes = (
+            resolved_features.health
+            if isinstance(resolved_features.health, HealthRoutes)
+            else HealthRoutes()
+        )
+        register_health_routes(
+            app,
+            probes=health_probes,
+            path=health_routes.path,
+            liveness=health_routes.liveness,
+            readiness=health_routes.readiness,
+            readiness_path=health_routes.readiness_path,
+            response_factory=health_routes.response_factory,
+        )
 
     if routers:
         mount_routers(app, list(routers))

{hexcore-6.0.2 → hexcore-6.2.0}/hexcore/infrastructure/api/health.py

@@ -26,6 +26,7 @@ __all__ = [
     "DependencyReport",
     "HealthReport",
     "Probe",
+    "ResponseFactory",
     "check_health",
     "register_health_routes",
     "default_probes",
@@ -56,6 +57,11 @@ class HealthReport(BaseModel):
         return 503 if self.status == "down" else 200
 
 
+#: Adapta el cuerpo de las rutas de health a la forma que ya publica una app. Recibe el
+#: informe y devuelve lo que haya que serializar.
+ResponseFactory = t.Callable[[HealthReport], t.Any]
+
+
 class Probe(t.NamedTuple):
     """Una sonda con nombre y timeout propio."""
 
@@ -231,6 +237,10 @@ def register_health_routes(
     *,
     path: str = "/health",
     probes: t.Sequence[Probe] | None = None,
+    liveness: bool = True,
+    readiness: bool = True,
+    readiness_path: str | None = None,
+    response_factory: ResponseFactory | None = None,
 ) -> None:
     """
     Registra `GET {path}` (liveness) y `GET {path}/ready` (readiness).
@@ -238,18 +248,71 @@ def register_health_routes(
     - `{path}` responde 200 sin I/O. Apuntá aquí el liveness probe.
     - `{path}/ready` sondea las dependencias y responde **503** si algo crítico falla,
       con el detalle y la latencia por dependencia. Apuntá aquí el readiness probe.
+
+    Las dos rutas se registran por separado a propósito. Una app que **ya publica**
+    `/health` con su propia forma —y con un cliente tipado generado desde su OpenAPI— no
+    puede aceptar la forma de `HealthReport` sin romper el contrato, pero sí quiere la
+    readiness, que es la parte que no se puede escribir a mano en cinco minutos::
+
+        register_health_routes(app, liveness=False)   # sólo /health/ready
+
+    Y si lo que hace falta es conservar la forma del cuerpo, `response_factory` la
+    adapta sin renunciar a las sondas::
+
+        register_health_routes(
+            app,
+            response_factory=lambda r: {"ok": r.status != "down", "checks": r.dependencies},
+        )
+
+    Args:
+        app: La app donde registrar.
+        path: Ruta del liveness. También la base del readiness, salvo que se dé
+            `readiness_path`.
+        probes: Sondas del readiness. Por defecto, las de `default_probes()`.
+        liveness: Registrar `GET {path}`. Poné `False` si ya publicás el tuyo.
+        readiness: Registrar el readiness.
+        readiness_path: Ruta del readiness. Por defecto ``f"{path}/ready"``.
+        response_factory: Si se da, se le pasa el `HealthReport` y lo que devuelva es el
+            cuerpo de la respuesta. El **status code** lo sigue decidiendo el informe
+            (503 si algo crítico está caído), salvo que devuelvas una `Response` propia,
+            en cuyo caso el status es cosa tuya.
+
+    Raises:
+        ValueError: Si se desactivan las dos rutas. Una llamada que no registra nada es
+            un error de configuración, y descubrirlo por silencio cuesta un incidente.
     """
-    @app.get(path, tags=["health"], summary="Liveness: el proceso responde")
-    async def health() -> HealthReport:
-        return await check_health(deep=False)
-
-    @app.get(
-        f"{path}/ready",
-        tags=["health"],
-        summary="Readiness: las dependencias responden",
-        responses={503: {"description": "Alguna dependencia crítica no responde"}},
-    )
-    async def health_ready(response: Response) -> HealthReport:
-        report = await check_health(deep=True, probes=probes)
-        response.status_code = report.http_status
-        return report
+    if not liveness and not readiness:
+        raise ValueError(
+            "register_health_routes(liveness=False, readiness=False) no registra nada. "
+            "Si no querés ninguna de las dos rutas, no llames a la función."
+        )
+
+    # Sin factory se declara `HealthReport` para que el OpenAPI documente la forma; con
+    # factory el cuerpo es lo que devuelva el usuario y no hay modelo que prometer.
+    response_model = None if response_factory is not None else HealthReport
+
+    def render(report: HealthReport) -> t.Any:
+        return report if response_factory is None else response_factory(report)
+
+    if liveness:
+        @app.get(
+            path,
+            tags=["health"],
+            summary="Liveness: el proceso responde",
+            response_model=response_model,
+        )
+        async def health() -> t.Any:
+            return render(await check_health(deep=False))
+
+    if readiness:
+        @app.get(
+            readiness_path or f"{path}/ready",
+            tags=["health"],
+            summary="Readiness: las dependencias responden",
+            response_model=response_model,
+            responses={503: {"description": "Alguna dependencia crítica no responde"}},
+        )
+        async def health_ready(response: Response) -> t.Any:
+            report = await check_health(deep=True, probes=probes)
+            response.status_code = report.http_status
+            return render(report)

{hexcore-6.0.2 → hexcore-6.2.0}/hexcore/infrastructure/api/middlewares.py

@@ -12,6 +12,7 @@ import logging
 import time
 import typing as t
 import uuid
+import warnings
 from contextvars import ContextVar
 
 from starlette.middleware.base import BaseHTTPMiddleware, RequestResponseEndpoint
@@ -123,11 +124,25 @@ def install_request_id_logging(
     """
     Instala el filtro de request-id en los handlers de un logger.
 
+    **Configurá el logging primero.** Esta función instrumenta los handlers que
+    **ya existen**; si no hay ninguno, no hay nada que instrumentar y no hace nada::
+
+        logging.basicConfig(level=logging.INFO)          # primero
+        install_request_id_logging(fmt="%(asctime)s [%(request_id)s] %(message)s")
+
+    Al revés no falla, pero deja el logging sin configurar y el request-id sin
+    aparecer. Por eso el caso "sin handlers" emite un `RuntimeWarning` en vez de
+    devolver en silencio: el síntoma sería "no veo el request-id en los logs", que no
+    apunta a ninguna causa.
+
     Args:
         logger: El logger a instrumentar. Por defecto, el root logger.
         fmt: Si se da, se aplica como formato a los handlers del logger. Usá
             ``%(request_id)s`` en él. Si es None, no se toca el formato: el filtro
             deja el atributo disponible para el formato que ya tengas.
+
+    Warns:
+        RuntimeWarning: Si el logger de destino no tiene ningún handler.
     """
     target = logger or logging.getLogger()
     log_filter = RequestIDLogFilter()
@@ -135,6 +150,19 @@ def install_request_id_logging(
     # El filtro va en los handlers, no en el logger: un filtro de logger no se aplica
     # a los registros que suben por propagación desde loggers hijos.
     handlers = target.handlers or logging.getLogger().handlers
+    if not handlers:
+        # Un no-op silencioso en una utilidad de *observabilidad* es especialmente malo:
+        # el usuario descubre que no funcionó cuando necesita correlacionar un incidente.
+        warnings.warn(
+            f"install_request_id_logging: el logger {target.name!r} no tiene handlers, "
+            "así que no hay nada que instrumentar y esta llamada no hizo nada. "
+            "Configurá el logging primero (p. ej. logging.basicConfig(...)) y llamá "
+            "después.",
+            RuntimeWarning,
+            stacklevel=2,
+        )
+        return
+
     for handler in handlers:
         if not any(isinstance(f, RequestIDLogFilter) for f in handler.filters):
             handler.addFilter(log_filter)

{hexcore-6.0.2 → hexcore-6.2.0/hexcore.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hexcore
-Version: 6.0.2
+Version: 6.2.0
 Summary: Núcleo reutilizable para proyectos Python con arquitectura hexagonal y event handling. Provee abstracciones, utilidades y contratos para DDD, eventos y desacoplamiento de infraestructura.
 Author-email: "David Latosefki (Indroic)" <indroic@outlook.com>
 License-Expression: MIT
@@ -155,7 +155,7 @@ pero están deprecados — ver [Versiones y soporte](#versiones-y-soporte).
 | Sesión o UoW fuera de un request | `sql.session_scope()`, `sql.uow_scope()` | `sql` |
 | Request-id correlacionado en los logs | `hx.RequestIDMiddleware`, `hx.install_request_id_logging()` | `api` |
 | Excepciones de dominio → HTTP | `hx.register_exception_handlers()` | `api` |
-| Health checks que sondean de verdad | `hx.register_health_routes()`, `hx.check_health()` | `api` |
+| Health checks que sondean de verdad | `hx.register_health_routes()`, `hx.check_health()`, `hx.HealthRoutes` | `api` |
 | Rate limiting | `hx.rate_limit()` | `api` |
 | SSE / WebSocket / límite de conexiones | `hx.sse_stream()`, `hx.ws_heartbeat()`, `hx.connection_slot()` | `api` |
 | Composición de routers | `hx.build_root_router()`, `hx.mount_routers()` | `api` |
@@ -308,6 +308,36 @@ register_health_routes(app, probes=[
 ])
 ```
 
+#### Si tu app ya publica su propio `/health`
+
+Las dos rutas se registran por separado, así que una app **ya en producción** —con su forma de
+respuesta y un cliente tipado generado desde su OpenAPI— puede quedarse con la readiness, que es
+la parte que no se escribe a mano, sin tocar el contrato que ya publicó:
+
+```python
+register_health_routes(app, liveness=False)          # sólo /health/ready
+register_health_routes(app, liveness=False, readiness_path="/_ready")
+```
+
+Y si lo que hay que conservar es la **forma del cuerpo**, `response_factory` la adapta sin
+renunciar a las sondas. El status code lo sigue decidiendo el informe, que es lo que lee el
+orquestador:
+
+```python
+register_health_routes(
+    app,
+    response_factory=lambda r: {"ok": r.status != "down", "checks": r.dependencies},
+)
+```
+
+Lo mismo desde `create_app`, sin apagar la feature entera:
+
+```python
+from hexcore.fastapi import AppFeatures, HealthRoutes, create_app
+
+app = create_app(features=AppFeatures(health=HealthRoutes(liveness=False)))
+```
+
 ### Rate limiting
 
 ```python
@@ -331,8 +361,11 @@ rate_limit(10, 60, on_backend_error="deny")
 ### Request-id correlacionado
 
 ```python
+import logging
+
 from hexcore.fastapi import get_request_id, install_request_id_logging
 
+logging.basicConfig(level=logging.INFO)          # primero: configurá el logging
 install_request_id_logging(fmt="%(asctime)s [%(request_id)s] %(message)s")
 ```
 
@@ -341,6 +374,10 @@ la traza) y lo publica en un `ContextVar` y en `request.state`. `install_request
 lo inyecta en **cada línea de log**, que es la mitad del valor: sin eso, tener el header no
 correlaciona nada.
 
+> **El orden importa.** `install_request_id_logging()` instrumenta los handlers que **ya
+> existen**. En un proceso donde nadie configuró el logging todavía no hay ninguno, así que la
+> llamada no tiene nada que hacer — y avisa con un `RuntimeWarning` en vez de quedarse callada.
+
 ### Streaming: SSE, WebSocket y límite de conexiones
 
 ```python

{hexcore-6.0.2 → hexcore-6.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "hexcore"
-version = "6.0.2"
+version = "6.2.0"
 authors = [
   { name="David Latosefki (Indroic)", email="indroic@outlook.com" },
 ]

{hexcore-6.0.2 → hexcore-6.2.0}/tests/test_api_health.py

@@ -218,3 +218,114 @@ def test_health_report_is_serializable():
     report = HealthReport(status="ok")
 
     assert report.model_dump()["status"] == "ok"
+
+
+# ── R5: adopción por partes en una app que ya publica su /health ───────────────
+
+
+def test_readiness_can_be_registered_without_touching_the_published_liveness():
+    """
+    El caso que dejó F16 sin adoptar: la app ya publica `/health` con su propia forma y
+    un cliente tipado generado desde el OpenAPI. Antes había que apagar la feature
+    entera, y con ella se perdía la readiness, que es la parte valiosa.
+    """
+    app = FastAPI()
+
+    @app.get("/health")
+    async def mi_health() -> dict[str, str]:
+        return {"estado": "vivo"}          # el contrato ya publicado, intacto
+
+    register_health_routes(app, liveness=False, probes=[Probe("sql", _boom)])
+
+    with TestClient(app) as client:
+        assert client.get("/health").json() == {"estado": "vivo"}
+        assert client.get("/health/ready").status_code == 503
+
+
+def test_liveness_can_be_registered_alone():
+    app = FastAPI()
+    register_health_routes(app, readiness=False, probes=[Probe("sql", _boom)])
+
+    with TestClient(app) as client:
+        assert client.get("/health").status_code == 200
+        assert client.get("/health/ready").status_code == 404
+
+
+def test_disabling_both_routes_is_an_error_not_a_silent_noop():
+    app = FastAPI()
+
+    with pytest.raises(ValueError, match="no registra nada"):
+        register_health_routes(app, liveness=False, readiness=False)
+
+
+def test_readiness_path_can_be_set_independently():
+    app = FastAPI()
+    register_health_routes(
+        app, liveness=False, readiness_path="/_ready", probes=[Probe("sql", _ok)]
+    )
+
+    with TestClient(app) as client:
+        assert client.get("/_ready").status_code == 200
+        assert client.get("/health/ready").status_code == 404
+
+
+def test_response_factory_adapts_the_body_but_not_the_status():
+    """
+    La otra mitad de la adopción: conservar la forma del cuerpo sin renunciar a que un
+    503 siga siendo un 503, que es lo que lee el orquestador.
+    """
+    app = FastAPI()
+    register_health_routes(
+        app,
+        probes=[Probe("sql", _boom)],
+        response_factory=lambda report: {
+            "ok": report.status != "down",
+            "checks": [dep.name for dep in report.dependencies],
+        },
+    )
+
+    with TestClient(app) as client:
+        live = client.get("/health")
+        ready = client.get("/health/ready")
+
+    assert live.status_code == 200
+    assert live.json() == {"ok": True, "checks": []}
+
+    assert ready.status_code == 503
+    assert ready.json() == {"ok": False, "checks": ["sql"]}
+
+
+def test_response_factory_body_is_not_forced_into_the_health_report_schema():
+    """
+    Con `response_model=HealthReport`, FastAPI filtraría el cuerpo del factory a los
+    campos del informe y devolvería `{}`: adaptarlo sería inútil.
+    """
+    app = FastAPI()
+    register_health_routes(app, response_factory=lambda report: {"forma": "propia"})
+
+    with TestClient(app) as client:
+        assert client.get("/health").json() == {"forma": "propia"}
+
+
+def test_create_app_can_register_only_the_readiness():
+    from hexcore.infrastructure.api.app import AppFeatures, HealthRoutes, create_app
+
+    app = create_app(features=AppFeatures(health=HealthRoutes(liveness=False)))
+
+    @app.get("/health")
+    async def mi_health() -> dict[str, str]:
+        return {"estado": "vivo"}
+
+    with TestClient(app) as client:
+        assert client.get("/health").json() == {"estado": "vivo"}
+        assert client.get("/health/ready").status_code in (200, 503)
+
+
+def test_create_app_health_true_still_registers_both():
+    from hexcore.infrastructure.api.app import create_app
+
+    app = create_app()
+
+    paths = {route.path for route in app.routes if hasattr(route, "path")}
+
+    assert {"/health", "/health/ready"} <= paths