hexcore 3.0.0__tar.gz → 4.0.0__tar.gz

{hexcore-3.0.0/hexcore.egg-info → hexcore-4.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hexcore
-Version: 3.0.0
+Version: 4.0.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

{hexcore-3.0.0 → hexcore-4.0.0}/hexcore/application/cqrs/in_memory_buses.py

@@ -56,7 +56,10 @@ class InMemoryCommandBus(ICommandBus):
         is_background = getattr(cmd_type, "__cqrs_background__", False)
 
         if is_background and not is_worker_execution():
-            if not self._enqueuer or not self._serializer:
+            # `is None` y no truthiness: un enqueuer que implemente `__len__` o
+            # `__bool__` (un doble de test que cuenta lo encolado, p. ej.) es falsy
+            # cuando está vacío, y con `not self._enqueuer` se descartaría.
+            if self._enqueuer is None or self._serializer is None:
                 raise RuntimeError(
                     f"El comando '{cmd_type.__name__}' requiere ejecución en background, "
                     "pero el InMemoryCommandBus no tiene configurado un 'enqueuer' o 'serializer'."
@@ -150,8 +153,9 @@ class InMemoryEventBus(IEventBus):
             )
 
             if is_background:
-                # Enrutamiento hacia background
-                if not self._enqueuer or not self._serializer:
+                # Enrutamiento hacia background. `is None` por el mismo motivo que en
+                # `InMemoryCommandBus.dispatch`.
+                if self._enqueuer is None or self._serializer is None:
                     raise RuntimeError(
                         f"El handler de eventos '{event_handler.__name__}' requiere ejecución en background, "
                         "pero el InMemoryEventBus no tiene configurado un 'enqueuer' o 'serializer'."

hexcore-4.0.0/hexcore/application/dtos/cursor.py

@@ -0,0 +1,110 @@
+"""
+Paginación por cursor.
+
+`limit`/`offset` degrada en tablas grandes: un `OFFSET 100000` obliga a la base a
+escanear y descartar 100.000 filas antes de devolver la primera. Para los listados
+grandes (tickets, líneas, movimientos) hace falta la variante por cursor, que salta
+directo con un `WHERE (sort_key, id) > (...)`.
+
+Se **añade**, no sustituye a `QueryResponseDTO`.
+
+El cursor es opaco a propósito: codifica `(sort_key, id)` en base64url. Si fuera legible,
+los clientes empezarían a construirlo a mano y quedaría congelado como API pública.
+"""
+from __future__ import annotations
+
+import base64
+import binascii
+import json
+import typing as t
+
+from pydantic import Field
+
+from .base import DTO
+from .query import FilterConditionDTO, SortDirection
+
+T = t.TypeVar("T")
+
+__all__ = [
+    "CursorPageDTO",
+    "CursorRequestDTO",
+    "encode_cursor",
+    "decode_cursor",
+    "InvalidCursorError",
+]
+
+
+class InvalidCursorError(ValueError):
+    """El cursor recibido no se puede decodificar."""
+
+
+class CursorPageDTO(DTO, t.Generic[T]):
+    """
+    Una página por cursor.
+
+    `next_cursor` es None cuando no hay más resultados, que es la única señal de fin que
+    necesita el cliente: no hay `total`, porque contar es justamente lo que esta
+    paginación evita.
+    """
+
+    items: list[T] = Field(default_factory=list)
+    next_cursor: str | None = None
+
+
+class CursorRequestDTO(DTO):
+    """Petición de una página por cursor."""
+
+    limit: int = Field(default=50, ge=1, le=500)
+    cursor: str | None = None
+    sort_field: str = "created_at"
+    direction: SortDirection = SortDirection.DESC
+    search: str | None = None
+    search_fields: list[str] = Field(default_factory=list)
+    filters: list[FilterConditionDTO] = Field(default_factory=list)
+
+
+def encode_cursor(sort_value: t.Any, entity_id: t.Any) -> str:
+    """
+    Codifica la posición de la última fila de la página.
+
+    Se incluye el `id` además del campo de orden para desempatar: con sólo el `sort_key`,
+    varias filas con el mismo `created_at` se saltarían o se repetirían.
+    """
+    payload = json.dumps(
+        {"k": _jsonable(sort_value), "i": _jsonable(entity_id)},
+        separators=(",", ":"),
+    )
+    return base64.urlsafe_b64encode(payload.encode()).decode().rstrip("=")
+
+
+def decode_cursor(cursor: str) -> tuple[t.Any, t.Any]:
+    """
+    Decodifica un cursor a `(sort_value, entity_id)`.
+
+    Raises:
+        InvalidCursorError: Si el cursor está corrupto o no tiene la forma esperada. Es
+            un `ValueError`, así que los handlers de F5 lo traducen a 422.
+    """
+    try:
+        padding = "=" * (-len(cursor) % 4)
+        payload = base64.urlsafe_b64decode(cursor + padding).decode()
+        data = json.loads(payload)
+    except (binascii.Error, UnicodeDecodeError, json.JSONDecodeError, ValueError) as exc:
+        raise InvalidCursorError(f"Cursor inválido: {cursor!r}") from exc
+
+    if not isinstance(data, dict) or "k" not in data or "i" not in data:
+        raise InvalidCursorError(f"Cursor inválido: {cursor!r}")
+
+    return data["k"], data["i"]
+
+
+def _jsonable(value: t.Any) -> t.Any:
+    """Normaliza a algo serializable en JSON conservando el orden lexicográfico."""
+    if value is None or isinstance(value, (str, int, float, bool)):
+        return value
+    isoformat = getattr(value, "isoformat", None)
+    if callable(isoformat):
+        # ISO-8601 ordena lexicográficamente igual que cronológicamente, que es lo que
+        # necesita la comparación del WHERE.
+        return isoformat()
+    return str(value)

hexcore-4.0.0/hexcore/application/dtos/errors.py

@@ -0,0 +1,30 @@
+"""
+Errores de validación de campos de query, con datos estructurados.
+
+`ValueError("Campo de orden no soportado: nope")` sólo se puede mostrar; el cliente no
+puede señalar el input concreto ni ofrecer las alternativas. Esta subclase lleva `field` y
+`allowed`, y sigue siendo un `ValueError`, así que todo el código que ya lo capturaba
+—incluidos los handlers de F5— sigue funcionando.
+"""
+from __future__ import annotations
+
+import typing as t
+
+__all__ = ["UnsupportedQueryFieldError"]
+
+
+class UnsupportedQueryFieldError(ValueError):
+    """Un campo de filtro, orden o búsqueda que el modelo no expone."""
+
+    def __init__(
+        self,
+        field: str,
+        context: str,
+        allowed: t.Iterable[str] | None = None,
+    ) -> None:
+        self.field = field
+        self.context = context
+        self.allowed: list[str] = sorted(allowed) if allowed is not None else []
+        # Se conserva el mensaje anterior palabra por palabra: hay tests y logs que lo
+        # buscan, y cambiarlo no aporta nada.
+        super().__init__(f"Campo de {context} no soportado: {field}")

{hexcore-3.0.0 → hexcore-4.0.0}/hexcore/config.py

@@ -21,6 +21,11 @@ class ServerConfig(BaseModel):
     port: int = 8000
     debug: bool = True
 
+    # Identidad de la app. La usa `create_app()` para el título y la versión de FastAPI,
+    # de modo que el camino feliz no necesite pasarlos.
+    app_title: str = "HexCore API"
+    app_version: str = "0.1.0"
+
     # DB CONFIG
     sql_database_url: str = "sqlite:///./db.sqlite3"
     async_sql_database_url: str = "sqlite+aiosqlite:///./db.sqlite3"

hexcore-4.0.0/hexcore/infrastructure/api/__init__.py

@@ -0,0 +1,76 @@
+from .cqrs import (
+    CQRSContainer,
+    configure_cqrs,
+    get_cqrs_container,
+    provide_command_bus,
+    provide_event_bus,
+    provide_query_bus,
+    provide_registry,
+    reset_cqrs,
+)
+from .exception_handlers import (
+    DEFAULT_EXCEPTION_STATUS_MAP,
+    register_exception_handlers,
+)
+from .health import (
+    DependencyReport,
+    HealthReport,
+    Probe,
+    check_health,
+    default_probes,
+    register_health_routes,
+)
+from .middlewares import (
+    REQUEST_ID,
+    RequestIDLogFilter,
+    RequestIDMiddleware,
+    TimingMiddleware,
+    get_request_id,
+    install_request_id_logging,
+)
+from .rate_limit import client_ip_key, rate_limit
+from .routing import build_root_router, mount_routers
+from .streaming import connection_slot, format_sse_event, sse_stream, ws_heartbeat
+from .utils import build_query_endpoint, register_query_endpoint
+
+__all__ = [
+    "build_query_endpoint",
+    "register_query_endpoint",
+    # Middlewares (F11)
+    "REQUEST_ID",
+    "RequestIDMiddleware",
+    "TimingMiddleware",
+    "RequestIDLogFilter",
+    "get_request_id",
+    "install_request_id_logging",
+    # Routing (F13)
+    "build_root_router",
+    "mount_routers",
+    # Handlers de excepción (F5)
+    "DEFAULT_EXCEPTION_STATUS_MAP",
+    "register_exception_handlers",
+    # Providers CQRS (F6)
+    "CQRSContainer",
+    "configure_cqrs",
+    "get_cqrs_container",
+    "reset_cqrs",
+    "provide_command_bus",
+    "provide_query_bus",
+    "provide_event_bus",
+    "provide_registry",
+    # Rate limiting (F12)
+    "rate_limit",
+    "client_ip_key",
+    # Streaming (F14)
+    "sse_stream",
+    "format_sse_event",
+    "ws_heartbeat",
+    "connection_slot",
+    # Health checks (F16)
+    "check_health",
+    "register_health_routes",
+    "default_probes",
+    "HealthReport",
+    "DependencyReport",
+    "Probe",
+]

hexcore-4.0.0/hexcore/infrastructure/api/app.py

@@ -0,0 +1,131 @@
+"""
+Factory de la aplicación FastAPI.
+
+Cada app repite CORS, middleware de request-id, handlers de excepción y health checks.
+Aplicando las reglas de simplicidad del plan: el camino feliz es cero configuración
+(`create_app()` a secas produce una app usable), y los interruptores van agrupados en un
+solo objeto en vez de ocho keywords.
+"""
+from __future__ import annotations
+
+import typing as t
+
+from fastapi import FastAPI
+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 .middlewares import RequestIDMiddleware, TimingMiddleware
+from .routing import MountableRouter, mount_routers
+
+__all__ = ["AppFeatures", "create_app"]
+
+
+class AppFeatures(BaseModel):
+    """
+    Qué cablea `create_app()`. Todo activado por defecto.
+
+    Desactivar es explícito y localizado: ``create_app(features=AppFeatures(cors=False))``.
+    """
+
+    cors: bool = True
+    """CORS con `config.allow_origins` / `allow_methods` / `allow_headers`."""
+
+    request_id: bool = True
+    """Middleware `X-Request-ID` (F11)."""
+
+    timing: bool = True
+    """Middleware `X-Response-Time-ms` (F11)."""
+
+    exception_handlers: bool = True
+    """Mapeo de excepciones de dominio a HTTP (F5)."""
+
+    health: bool = True
+    """Rutas `/health` y `/health/ready` (F16)."""
+
+
+def create_app(
+    lifespan: t.Any | None = None,
+    *,
+    features: AppFeatures | None = None,
+    routers: t.Sequence[MountableRouter] | None = None,
+    health_probes: t.Sequence[Probe] | None = None,
+    exception_mapping: dict[type[Exception], int] | None = None,
+    **fastapi_kwargs: t.Any,
+) -> FastAPI:
+    """
+    Construye una `FastAPI` con lo que toda app necesita ya cableado.
+
+    `create_app()` sin argumentos ya da una app usable: `title` y `version` salen de
+    `ServerConfig`, CORS de `config.allow_origins`, y `/health` existe.
+
+    Args:
+        lifespan: El lifespan. Típicamente de `build_lifespan(...)` (F4).
+        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).
+        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
+            de la configuración.
+
+    Returns:
+        La aplicación, lista para servir.
+    """
+    resolved_features = features or AppFeatures()
+    config = _config()
+
+    app = FastAPI(lifespan=lifespan, **{**_fastapi_defaults(config), **fastapi_kwargs})
+
+    # Los middlewares de Starlette se ejecutan en orden inverso al de registro, así que
+    # el request-id se añade último para que envuelva a todo lo demás y su ContextVar
+    # esté disponible en el resto de la pila.
+    if resolved_features.cors:
+        app.add_middleware(
+            CORSMiddleware,
+            allow_origins=list(getattr(config, "allow_origins", ["*"])),
+            allow_credentials=bool(getattr(config, "allow_credentials", True)),
+            allow_methods=list(getattr(config, "allow_methods", ["*"])),
+            allow_headers=list(getattr(config, "allow_headers", ["*"])),
+        )
+    if resolved_features.timing:
+        app.add_middleware(TimingMiddleware)
+    if resolved_features.request_id:
+        app.add_middleware(RequestIDMiddleware)
+
+    if resolved_features.exception_handlers:
+        register_exception_handlers(app, mapping=exception_mapping)
+
+    if resolved_features.health:
+        register_health_routes(app, probes=health_probes)
+
+    if routers:
+        mount_routers(app, list(routers))
+
+    return app
+
+
+def _fastapi_defaults(config: t.Any) -> dict[str, t.Any]:
+    """
+    Defaults derivados de `ServerConfig`.
+
+    `debug` gobierna la documentación interactiva: en producción, `/docs` abierto es una
+    decisión que hay que tomar a propósito, no heredar.
+    """
+    debug = bool(getattr(config, "debug", False))
+    return {
+        "title": getattr(config, "app_title", None) or "HexCore API",
+        "version": getattr(config, "app_version", None) or "0.1.0",
+        "debug": debug,
+        "docs_url": "/docs" if debug else None,
+        "redoc_url": "/redoc" if debug else None,
+        "openapi_url": "/openapi.json" if debug else None,
+    }
+
+
+def _config() -> t.Any:
+    from hexcore.config import LazyConfig
+
+    return LazyConfig.get_config()

hexcore-4.0.0/hexcore/infrastructure/api/cqrs.py

@@ -0,0 +1,195 @@
+"""
+Providers FastAPI para los buses CQRS.
+
+Existen como funciones —y no como accesos directos al contenedor— por una única razón:
+`app.dependency_overrides[provide_command_bus] = ...` en los tests. Si el endpoint
+tocara el singleton, no habría nada que sobreescribir.
+
+**Una sola fuente de verdad.** El contenedor que leen estos providers es el mismo que
+usa el worker: se configura una vez con `configure_cqrs(...)` y tanto la app web como el
+entrypoint del worker lo consumen. Duplicar la construcción es cómo se acaba con un
+registry en el web que no tiene los handlers del worker.
+"""
+from __future__ import annotations
+
+import threading
+import typing as t
+
+from hexcore.domain.cqrs.buses import (
+    AbstractCommandBus,
+    AbstractEventBus,
+    AbstractQueryBus,
+)
+
+if t.TYPE_CHECKING:
+    from hexcore.application.cqrs.factory import CQRSFactory
+    from hexcore.application.cqrs.registry import HandlerRegistry
+    from hexcore.domain.cqrs.serializer import ISerializer
+    from hexcore.domain.cqrs.task_queues import ITaskEnqueuer
+    from hexcore.infrastructure.workers.consumer import CQRSConsumer
+
+__all__ = [
+    "CQRSContainer",
+    "configure_cqrs",
+    "get_cqrs_container",
+    "reset_cqrs",
+    "provide_command_bus",
+    "provide_query_bus",
+    "provide_event_bus",
+    "provide_registry",
+]
+
+
+class CQRSContainer:
+    """
+    Contenedor perezoso de los buses CQRS.
+
+    Construye los buses la primera vez que se piden y los cachea. Perezoso a propósito:
+    `configure_cqrs()` se puede llamar en import time sin tocar la BD ni el broker.
+    """
+
+    def __init__(
+        self,
+        factory: "CQRSFactory",
+    ) -> None:
+        self._factory = factory
+        self._command_bus: AbstractCommandBus | None = None
+        self._query_bus: AbstractQueryBus | None = None
+        self._event_bus: AbstractEventBus | None = None
+        self._lock = threading.RLock()
+
+    @property
+    def registry(self) -> "HandlerRegistry":
+        return self._factory._registry  # noqa: SLF001 - misma capa lógica
+
+    @property
+    def serializer(self) -> "ISerializer":
+        return self._factory.create_serializer()
+
+    def command_bus(self) -> AbstractCommandBus:
+        with self._lock:
+            if self._command_bus is None:
+                self._command_bus = t.cast(
+                    AbstractCommandBus, self._factory.create_command_bus()
+                )
+            return self._command_bus
+
+    def query_bus(self) -> AbstractQueryBus:
+        with self._lock:
+            if self._query_bus is None:
+                self._query_bus = t.cast(
+                    AbstractQueryBus, self._factory.create_query_bus()
+                )
+            return self._query_bus
+
+    def event_bus(self) -> AbstractEventBus:
+        with self._lock:
+            if self._event_bus is None:
+                self._event_bus = t.cast(
+                    AbstractEventBus, self._factory.create_event_bus()
+                )
+            return self._event_bus
+
+    def build_consumer(self) -> "CQRSConsumer":
+        """
+        Construye el `CQRSConsumer` del worker sobre **estos mismos** buses.
+
+        Es lo que garantiza que el worker y la app web comparten registry y serializer.
+        """
+        from hexcore.infrastructure.workers.consumer import CQRSConsumer
+
+        return CQRSConsumer(
+            command_bus=self.command_bus(),
+            event_bus=self.event_bus(),
+            serializer=self.serializer,
+        )
+
+
+_container: CQRSContainer | None = None
+_container_lock = threading.RLock()
+
+
+def configure_cqrs(
+    registry: "HandlerRegistry",
+    *,
+    config: t.Any = None,
+    enqueuer: "ITaskEnqueuer | None" = None,
+) -> CQRSContainer:
+    """
+    Configura el contenedor CQRS del proceso. Llamalo una vez, al arrancar.
+
+    Args:
+        registry: El registry con los handlers ya registrados.
+        config: Un `CQRSConfig`. Por defecto, el de `ServerConfig.cqrs` si está, o
+            `CQRSConfig()`.
+        enqueuer: El `ITaskEnqueuer` para el Smart Routing. Sin él, un
+            `@background_command` registrado hace fallar la construcción del bus (P0-5).
+
+    Returns:
+        El contenedor, por si querés usarlo directamente (p. ej. `build_consumer()`).
+    """
+    from hexcore.application.cqrs.config import CQRSConfig
+    from hexcore.application.cqrs.factory import CQRSFactory
+
+    global _container
+
+    if config is None:
+        from hexcore.config import LazyConfig
+
+        config = getattr(LazyConfig.get_config(), "cqrs", None) or CQRSConfig()
+
+    with _container_lock:
+        _container = CQRSContainer(
+            CQRSFactory(config, registry, enqueuer=enqueuer)
+        )
+        return _container
+
+
+def get_cqrs_container() -> CQRSContainer:
+    """
+    El contenedor configurado.
+
+    Raises:
+        RuntimeError: Si nadie llamó a `configure_cqrs()`.
+    """
+    with _container_lock:
+        if _container is None:
+            raise RuntimeError(
+                "El CQRS no está configurado. Llamá a "
+                "hexcore.infrastructure.api.cqrs.configure_cqrs(registry, enqueuer=...) "
+                "al arrancar la aplicación (o el worker), antes de resolver cualquier bus."
+            )
+        return _container
+
+
+def reset_cqrs() -> None:
+    """Descarta el contenedor. Para tests y para reconfigurar en un worker."""
+    global _container
+
+    with _container_lock:
+        _container = None
+
+
+# ── Dependencias FastAPI ──────────────────────────────────────────────────────
+# Deliberadamente triviales: su valor está en ser un objeto sobre el que hacer
+# `app.dependency_overrides[...] = ...`.
+
+
+def provide_command_bus() -> AbstractCommandBus:
+    """Dependencia FastAPI: el CommandBus del proceso."""
+    return get_cqrs_container().command_bus()
+
+
+def provide_query_bus() -> AbstractQueryBus:
+    """Dependencia FastAPI: el QueryBus del proceso."""
+    return get_cqrs_container().query_bus()
+
+
+def provide_event_bus() -> AbstractEventBus:
+    """Dependencia FastAPI: el EventBus del proceso."""
+    return get_cqrs_container().event_bus()
+
+
+def provide_registry() -> "HandlerRegistry":
+    """Dependencia FastAPI: el `HandlerRegistry` del proceso."""
+    return get_cqrs_container().registry