hexcore 2.4.0__tar.gz → 3.0.0__tar.gz

{hexcore-2.4.0 → hexcore-3.0.0}/PKG-INFO

@@ -1,29 +1,46 @@
 Metadata-Version: 2.4
 Name: hexcore
-Version: 2.4.0
+Version: 3.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
 Requires-Python: >=3.12
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: aiosqlite>=0.21.0
-Requires-Dist: alembic>=1.16.5
-Requires-Dist: asyncpg>=0.30.0
-Requires-Dist: beanie>=2.0.0
-Requires-Dist: fastapi>=0.116.1
-Requires-Dist: pika>=1.3.2
+Requires-Dist: croniter>=2.0.0
 Requires-Dist: pydantic>=2.11.7
-Requires-Dist: redis>=6.4.0
-Requires-Dist: sqlalchemy>=2.0.43
 Requires-Dist: typer>=0.17.3
 Requires-Dist: ruff>=0.12.11
-Provides-Extra: procrastinate
-Requires-Dist: procrastinate>=3.0.0; extra == "procrastinate"
+Provides-Extra: api
+Requires-Dist: fastapi>=0.116.1; extra == "api"
+Provides-Extra: redis
+Requires-Dist: redis>=6.4.0; extra == "redis"
+Provides-Extra: mongo
+Requires-Dist: beanie>=2.0.0; extra == "mongo"
+Provides-Extra: sql
+Requires-Dist: sqlalchemy>=2.0.43; extra == "sql"
+Requires-Dist: alembic>=1.16.5; extra == "sql"
+Requires-Dist: asyncpg>=0.30.0; extra == "sql"
+Requires-Dist: aiosqlite>=0.21.0; extra == "sql"
 Provides-Extra: rabbitmq
 Requires-Dist: aio-pika>=9.4.0; extra == "rabbitmq"
+Requires-Dist: pika>=1.3.2; extra == "rabbitmq"
+Provides-Extra: procrastinate
+Requires-Dist: procrastinate>=3.0.0; extra == "procrastinate"
 Provides-Extra: celery
 Requires-Dist: celery>=5.4.0; extra == "celery"
+Provides-Extra: all
+Requires-Dist: fastapi>=0.116.1; extra == "all"
+Requires-Dist: redis>=6.4.0; extra == "all"
+Requires-Dist: beanie>=2.0.0; extra == "all"
+Requires-Dist: sqlalchemy>=2.0.43; extra == "all"
+Requires-Dist: alembic>=1.16.5; extra == "all"
+Requires-Dist: asyncpg>=0.30.0; extra == "all"
+Requires-Dist: aiosqlite>=0.21.0; extra == "all"
+Requires-Dist: aio-pika>=9.4.0; extra == "all"
+Requires-Dist: pika>=1.3.2; extra == "all"
+Requires-Dist: procrastinate>=3.0.0; extra == "all"
+Requires-Dist: celery>=5.4.0; extra == "all"
 Dynamic: license-file
 
 # HexCore [![PyPI Downloads](https://static.pepy.tech/personalized-badge/hexcore?period=total&units=INTERNATIONAL_SYSTEM&left_color=BLACK&right_color=GREEN&left_text=downloads)](https://pepy.tech/projects/hexcore)
@@ -280,7 +297,7 @@ HexCore v2 integra de forma nativa soporte para el patrón **CQRS (Command Query
 
 El sistema se basa en 3 buses principales, configurables e independientes:
 
-1. **`AbstractCommandBus`**: Despacha inteniones de mutación (`Command`) a un único `AbstractCommandHandler`. Los commands modifican el estado del sistema y se ejecutan (por defecto) dentro de una transacción de base de datos (Unit of Work).
+1. **`AbstractCommandBus`**: Despacha inteniones de mutación (`Command`) a un único `AbstractCommandHandler`. Los commands modifican el estado del sistema. La transacción la gestiona el handler (el patrón que enseñan los ejemplos de use case); si preferís que la gestione el bus, añadí `TransactionMiddleware` explícitamente con su `uow_factory`.
 2. **`AbstractQueryBus`**: Despacha intenciones de lectura (`Query`) a un único `AbstractQueryHandler`. Retornan un resultado sin mutar el estado.
 3. **`EventBus`**: Distribuye eventos de dominio (`DomainEvent`) a múltiples suscriptores asíncronamente (vía `subscribe`/`publish`).
 
@@ -293,8 +310,9 @@ from hexcore.application.cqrs.config import CQRSConfig, BusConfig
 config = ServerConfig(
     cqrs=CQRSConfig(
         command_bus=BusConfig(
-            # Por defecto incluye TransactionMiddleware
-            middlewares=["hexcore.infrastructure.cqrs.middlewares.TransactionMiddleware"]
+            # Sin middlewares por defecto. Los que no necesitan configuración se
+            # pueden declarar por dotted path:
+            middlewares=["hexcore.infrastructure.cqrs.middlewares.LoggingMiddleware"]
         ),
         # Puedes sustituir el backend en memoria por uno distribuido (Ej: Celery, Procrastinate)
         # backend="mi_app.infrastructure.ProcrastinateCommandBus" 
@@ -302,6 +320,15 @@ config = ServerConfig(
 )
 ```
 
+> **`TransactionMiddleware` no es el default.** Comitea después del handler, así que
+> con un handler que ya gestiona su propia transacción comitearías dos veces. Y
+> necesita un `uow_factory` construido con *tu* engine, cosa que no se puede expresar
+> como dotted path: instancialo a mano y pasá el pipeline al bus.
+>
+> ```python
+> TransactionMiddleware(uow_factory=lambda: SqlAlchemyUnitOfWork(session=session_factory()))
+> ```
+
 ---
 
 ### Guía de Migración: De Casos de Uso Clásicos a CQRS
@@ -584,6 +611,96 @@ register_hexcore_celery_tasks(app, consumer)
 
 ---
 
+## Tareas Periódicas Dinámicas (Cronjobs en Caliente)
+
+HexCore incluye un **`DynamicScheduler`** que te permite programar tareas (`@background_task`) para que se ejecuten periódicamente. La ventaja clave es que lee la configuración desde un repositorio (como tu Base de Datos), permitiendo activar, desactivar o cambiar los horarios **sin necesidad de reiniciar tus servidores**.
+
+### 1. Implementa tu Repositorio
+Implementa `ICronJobRepository` para decirle al Scheduler de dónde leer la configuración (ej. usando SQLAlchemy, MongoDB o Redis):
+
+```python
+from hexcore.domain.cqrs.cron import ICronJobRepository, CronJobDefinition
+from datetime import datetime
+
+class MiCronRepository(ICronJobRepository):
+    async def get_active_jobs(self) -> list[CronJobDefinition]:
+        # SELECT * FROM cronjobs WHERE is_active = true
+        return [
+            CronJobDefinition(
+                job_id="1",
+                task_name="hexcore.process_task", # o cualquier @background_task
+                cron_expression="*/5 * * * *",    # cada 5 minutos
+                payload={"task_name": "clean_db", "payload": {}}
+            )
+        ]
+        
+    async def update_last_run(self, job_id: str, run_time: datetime) -> None:
+        # UPDATE cronjobs SET last_run = run_time WHERE id = job_id
+        pass
+```
+
+### 2. Levanta el Scheduler
+En un proceso en background de tu API o en un microservicio separado, arranca el Scheduler inyectándole tu Enqueuer favorito (Celery, Procrastinate):
+
+```python
+from hexcore.application.cqrs.scheduler import DynamicScheduler
+import asyncio
+
+async def run_scheduler():
+    repo = MiCronRepository()
+    scheduler = DynamicScheduler(
+        repository=repo, 
+        enqueuer=enqueuer, 
+        tick_interval_seconds=60
+    )
+    
+    await scheduler.start() # Bucle infinito
+
+# En FastAPI puedes usar lifespan para lanzarlo:
+# asyncio.create_task(run_scheduler())
+```
+
+El Scheduler evaluará las expresiones (gracias a `croniter`) y delegará la carga pesada al enqueuer. ¡Tu Worker no necesita saber de horarios, solo ejecuta las tareas cuando le llegan!
+
+### 3. Distributed Locks (Evitar ejecuciones dobles)
+
+Si corres tu aplicación en múltiples contenedores o réplicas (ej. Kubernetes), podrías tener múltiples instancias del `DynamicScheduler` ejecutándose al mismo tiempo. Para evitar que el mismo cronjob se encole dos veces en el mismo minuto, HexCore soporta **Locks Distribuidos**.
+
+Puedes inyectar un proveedor de locks (`ILockProvider`) usando Redis o PostgreSQL (si lo usas como tu DB). Al inyectarlo, el Scheduler bloqueará atómicamente la tarea a través de toda tu red.
+
+#### Usando Redis
+```python
+from hexcore.infrastructure.cqrs.redis_lock import RedisLockProvider
+import redis.asyncio as redis
+
+redis_client = redis.from_url("redis://localhost:6379/0")
+lock_provider = RedisLockProvider(redis_client)
+
+scheduler = DynamicScheduler(
+    repository=repo, 
+    enqueuer=enqueuer, 
+    lock_provider=lock_provider
+)
+```
+
+#### Usando PostgreSQL (asyncpg)
+Si usas Procrastinate o bases de datos SQL y no quieres levantar Redis:
+
+```python
+from hexcore.infrastructure.cqrs.postgres_lock import PostgresLockProvider
+
+lock_provider = PostgresLockProvider(my_asyncpg_pool)
+await lock_provider.setup() # Crea la tabla de locks si no existe
+
+scheduler = DynamicScheduler(
+    repository=repo, 
+    enqueuer=enqueuer, 
+    lock_provider=lock_provider
+)
+```
+
+---
+
 ## Referencias
 
 - [CONTRIBUTING.md](./CONTRIBUTING.md): Pautas de colaboración.

hexcore-2.4.0/hexcore.egg-info/PKG-INFO → hexcore-3.0.0/README.md

@@ -1,31 +1,3 @@
-Metadata-Version: 2.4
-Name: hexcore
-Version: 2.4.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
-Requires-Python: >=3.12
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: aiosqlite>=0.21.0
-Requires-Dist: alembic>=1.16.5
-Requires-Dist: asyncpg>=0.30.0
-Requires-Dist: beanie>=2.0.0
-Requires-Dist: fastapi>=0.116.1
-Requires-Dist: pika>=1.3.2
-Requires-Dist: pydantic>=2.11.7
-Requires-Dist: redis>=6.4.0
-Requires-Dist: sqlalchemy>=2.0.43
-Requires-Dist: typer>=0.17.3
-Requires-Dist: ruff>=0.12.11
-Provides-Extra: procrastinate
-Requires-Dist: procrastinate>=3.0.0; extra == "procrastinate"
-Provides-Extra: rabbitmq
-Requires-Dist: aio-pika>=9.4.0; extra == "rabbitmq"
-Provides-Extra: celery
-Requires-Dist: celery>=5.4.0; extra == "celery"
-Dynamic: license-file
-
 # HexCore [![PyPI Downloads](https://static.pepy.tech/personalized-badge/hexcore?period=total&units=INTERNATIONAL_SYSTEM&left_color=BLACK&right_color=GREEN&left_text=downloads)](https://pepy.tech/projects/hexcore)
 HexCore es un módulo base reutilizable para proyectos Python que implementan arquitectura hexagonal y event handling.
 
@@ -280,7 +252,7 @@ HexCore v2 integra de forma nativa soporte para el patrón **CQRS (Command Query
 
 El sistema se basa en 3 buses principales, configurables e independientes:
 
-1. **`AbstractCommandBus`**: Despacha inteniones de mutación (`Command`) a un único `AbstractCommandHandler`. Los commands modifican el estado del sistema y se ejecutan (por defecto) dentro de una transacción de base de datos (Unit of Work).
+1. **`AbstractCommandBus`**: Despacha inteniones de mutación (`Command`) a un único `AbstractCommandHandler`. Los commands modifican el estado del sistema. La transacción la gestiona el handler (el patrón que enseñan los ejemplos de use case); si preferís que la gestione el bus, añadí `TransactionMiddleware` explícitamente con su `uow_factory`.
 2. **`AbstractQueryBus`**: Despacha intenciones de lectura (`Query`) a un único `AbstractQueryHandler`. Retornan un resultado sin mutar el estado.
 3. **`EventBus`**: Distribuye eventos de dominio (`DomainEvent`) a múltiples suscriptores asíncronamente (vía `subscribe`/`publish`).
 
@@ -293,8 +265,9 @@ from hexcore.application.cqrs.config import CQRSConfig, BusConfig
 config = ServerConfig(
     cqrs=CQRSConfig(
         command_bus=BusConfig(
-            # Por defecto incluye TransactionMiddleware
-            middlewares=["hexcore.infrastructure.cqrs.middlewares.TransactionMiddleware"]
+            # Sin middlewares por defecto. Los que no necesitan configuración se
+            # pueden declarar por dotted path:
+            middlewares=["hexcore.infrastructure.cqrs.middlewares.LoggingMiddleware"]
         ),
         # Puedes sustituir el backend en memoria por uno distribuido (Ej: Celery, Procrastinate)
         # backend="mi_app.infrastructure.ProcrastinateCommandBus" 
@@ -302,6 +275,15 @@ config = ServerConfig(
 )
 ```
 
+> **`TransactionMiddleware` no es el default.** Comitea después del handler, así que
+> con un handler que ya gestiona su propia transacción comitearías dos veces. Y
+> necesita un `uow_factory` construido con *tu* engine, cosa que no se puede expresar
+> como dotted path: instancialo a mano y pasá el pipeline al bus.
+>
+> ```python
+> TransactionMiddleware(uow_factory=lambda: SqlAlchemyUnitOfWork(session=session_factory()))
+> ```
+
 ---
 
 ### Guía de Migración: De Casos de Uso Clásicos a CQRS
@@ -584,6 +566,96 @@ register_hexcore_celery_tasks(app, consumer)
 
 ---
 
+## Tareas Periódicas Dinámicas (Cronjobs en Caliente)
+
+HexCore incluye un **`DynamicScheduler`** que te permite programar tareas (`@background_task`) para que se ejecuten periódicamente. La ventaja clave es que lee la configuración desde un repositorio (como tu Base de Datos), permitiendo activar, desactivar o cambiar los horarios **sin necesidad de reiniciar tus servidores**.
+
+### 1. Implementa tu Repositorio
+Implementa `ICronJobRepository` para decirle al Scheduler de dónde leer la configuración (ej. usando SQLAlchemy, MongoDB o Redis):
+
+```python
+from hexcore.domain.cqrs.cron import ICronJobRepository, CronJobDefinition
+from datetime import datetime
+
+class MiCronRepository(ICronJobRepository):
+    async def get_active_jobs(self) -> list[CronJobDefinition]:
+        # SELECT * FROM cronjobs WHERE is_active = true
+        return [
+            CronJobDefinition(
+                job_id="1",
+                task_name="hexcore.process_task", # o cualquier @background_task
+                cron_expression="*/5 * * * *",    # cada 5 minutos
+                payload={"task_name": "clean_db", "payload": {}}
+            )
+        ]
+        
+    async def update_last_run(self, job_id: str, run_time: datetime) -> None:
+        # UPDATE cronjobs SET last_run = run_time WHERE id = job_id
+        pass
+```
+
+### 2. Levanta el Scheduler
+En un proceso en background de tu API o en un microservicio separado, arranca el Scheduler inyectándole tu Enqueuer favorito (Celery, Procrastinate):
+
+```python
+from hexcore.application.cqrs.scheduler import DynamicScheduler
+import asyncio
+
+async def run_scheduler():
+    repo = MiCronRepository()
+    scheduler = DynamicScheduler(
+        repository=repo, 
+        enqueuer=enqueuer, 
+        tick_interval_seconds=60
+    )
+    
+    await scheduler.start() # Bucle infinito
+
+# En FastAPI puedes usar lifespan para lanzarlo:
+# asyncio.create_task(run_scheduler())
+```
+
+El Scheduler evaluará las expresiones (gracias a `croniter`) y delegará la carga pesada al enqueuer. ¡Tu Worker no necesita saber de horarios, solo ejecuta las tareas cuando le llegan!
+
+### 3. Distributed Locks (Evitar ejecuciones dobles)
+
+Si corres tu aplicación en múltiples contenedores o réplicas (ej. Kubernetes), podrías tener múltiples instancias del `DynamicScheduler` ejecutándose al mismo tiempo. Para evitar que el mismo cronjob se encole dos veces en el mismo minuto, HexCore soporta **Locks Distribuidos**.
+
+Puedes inyectar un proveedor de locks (`ILockProvider`) usando Redis o PostgreSQL (si lo usas como tu DB). Al inyectarlo, el Scheduler bloqueará atómicamente la tarea a través de toda tu red.
+
+#### Usando Redis
+```python
+from hexcore.infrastructure.cqrs.redis_lock import RedisLockProvider
+import redis.asyncio as redis
+
+redis_client = redis.from_url("redis://localhost:6379/0")
+lock_provider = RedisLockProvider(redis_client)
+
+scheduler = DynamicScheduler(
+    repository=repo, 
+    enqueuer=enqueuer, 
+    lock_provider=lock_provider
+)
+```
+
+#### Usando PostgreSQL (asyncpg)
+Si usas Procrastinate o bases de datos SQL y no quieres levantar Redis:
+
+```python
+from hexcore.infrastructure.cqrs.postgres_lock import PostgresLockProvider
+
+lock_provider = PostgresLockProvider(my_asyncpg_pool)
+await lock_provider.setup() # Crea la tabla de locks si no existe
+
+scheduler = DynamicScheduler(
+    repository=repo, 
+    enqueuer=enqueuer, 
+    lock_provider=lock_provider
+)
+```
+
+---
+
 ## Referencias
 
 - [CONTRIBUTING.md](./CONTRIBUTING.md): Pautas de colaboración.

{hexcore-2.4.0 → hexcore-3.0.0}/hexcore/application/cqrs/__init__.py

@@ -9,6 +9,7 @@ from .pipeline import MiddlewarePipeline
 from .in_memory_buses import InMemoryCommandBus, InMemoryQueryBus, InMemoryEventBus
 from .adapters import UseCaseCommandHandler
 from .factory import CQRSFactory
+from .scheduler import DynamicScheduler
 
 __all__ = [
     "HandlerRegistry",
@@ -21,4 +22,5 @@ __all__ = [
     "InMemoryEventBus",
     "UseCaseCommandHandler",
     "CQRSFactory",
+    "DynamicScheduler",
 ]

{hexcore-2.4.0 → hexcore-3.0.0}/hexcore/application/cqrs/config.py

@@ -55,13 +55,12 @@ class CQRSConfig(BaseModel):
     """
 
     enabled: bool = True
-    command_bus: BusConfig = Field(
-        default_factory=lambda: BusConfig(
-            middlewares=[
-                "hexcore.infrastructure.cqrs.middlewares.TransactionMiddleware"
-            ]
-        )
-    )
+    # Sin middlewares por defecto (P0-6). `TransactionMiddleware` *era* el default,
+    # pero adivinaba la sesión con el session factory interno de HexCore en vez del
+    # engine de la aplicación, y comiteaba por segunda vez sobre los handlers que ya
+    # gestionan su transacción. Si lo querés, declaralo explícitamente con su
+    # `uow_factory`.
+    command_bus: BusConfig = Field(default_factory=BusConfig)
     query_bus: BusConfig = Field(default_factory=BusConfig)
     event_bus: BusConfig = Field(default_factory=BusConfig)
     serializer: t.Optional[str] = None  # None = PydanticSerializer por defecto

hexcore-3.0.0/hexcore/application/cqrs/factory.py

@@ -0,0 +1,215 @@
+"""
+Factory para construir buses CQRS a partir de la configuración.
+Resuelve backends, serializers y middlewares por dotted path.
+"""
+from __future__ import annotations
+
+import importlib
+import typing as t
+
+from hexcore.domain.cqrs.buses import ICommandBus, IQueryBus, IEventBus
+from hexcore.domain.cqrs.middleware import IMiddleware
+from hexcore.domain.cqrs.serializer import ISerializer
+from hexcore.domain.cqrs.task_queues import ITaskEnqueuer
+
+from .config import CQRSConfig, BusConfig
+from .registry import HandlerRegistry
+from .pipeline import MiddlewarePipeline
+from .in_memory_buses import InMemoryCommandBus, InMemoryQueryBus, InMemoryEventBus
+
+
+def _import_class(dotted_path: str) -> type:
+    """Importa una clase a partir de su dotted path."""
+    module_path, class_name = dotted_path.rsplit(".", 1)
+    module = importlib.import_module(module_path)
+    return getattr(module, class_name)
+
+
+def _build_middlewares(dotted_paths: list[str]) -> list[IMiddleware]:
+    """
+    Instancia middlewares a partir de sus dotted paths.
+
+    Sólo sirve para middlewares construibles sin argumentos. Los que necesitan
+    configuración (p. ej. `TransactionMiddleware`, que requiere un `uow_factory`
+    atado al engine de la aplicación) hay que instanciarlos a mano y pasar el
+    `MiddlewarePipeline` al bus.
+    """
+    middlewares: list[IMiddleware] = []
+    for path in dotted_paths:
+        cls = _import_class(path)
+        try:
+            middlewares.append(cls())
+        except TypeError as exc:
+            raise TypeError(
+                f"El middleware '{path}' no se puede construir sin argumentos: {exc}. "
+                "Declararlo por dotted path sólo funciona para middlewares sin "
+                "configuración; instancialo a mano y pasá el MiddlewarePipeline al bus."
+            ) from exc
+        except ValueError as exc:
+            raise ValueError(
+                f"El middleware '{path}' rechazó su construcción por defecto: {exc} "
+                "Declararlo por dotted path sólo funciona para middlewares sin "
+                "configuración; instancialo a mano y pasá el MiddlewarePipeline al bus."
+            ) from exc
+    return middlewares
+
+
+def _build_pipeline(bus_config: BusConfig) -> MiddlewarePipeline:
+    """Construye un MiddlewarePipeline desde la configuración de un bus."""
+    middlewares = _build_middlewares(bus_config.middlewares)
+    return MiddlewarePipeline(middlewares)
+
+
+class CQRSFactory:
+    """
+    Factory que construye las instancias de buses CQRS.
+
+    Usa CQRSConfig para determinar qué implementación de bus instanciar,
+    qué middlewares configurar y qué serializer utilizar.
+
+    Uso::
+
+        config = CQRSConfig(...)
+        registry = HandlerRegistry()
+        # ...registrar handlers...
+
+        factory = CQRSFactory(config, registry, enqueuer=ProcrastinateEnqueuer(app))
+        command_bus = factory.create_command_bus()
+        query_bus = factory.create_query_bus()
+        event_bus = factory.create_event_bus()
+
+    El `enqueuer` es lo que habilita el Smart Routing: sin él, los buses in-memory
+    no pueden enrutar un `@background_command` y la factory lo dice **al construir**,
+    no en el primer dispatch.
+    """
+
+    def __init__(
+        self,
+        config: CQRSConfig,
+        registry: HandlerRegistry,
+        enqueuer: ITaskEnqueuer | None = None,
+    ) -> None:
+        self._config = config
+        self._registry = registry
+        self._enqueuer = enqueuer
+        self._serializer: ISerializer | None = None
+
+    def create_serializer(self) -> ISerializer:
+        """
+        Crea el serializer configurado (PydanticSerializer por defecto).
+
+        La instancia se cachea: los buses y el consumer tienen que compartir el
+        mismo serializer para que el round-trip por la cola sea coherente.
+        """
+        if self._serializer is not None:
+            return self._serializer
+
+        if self._config.serializer:
+            cls = _import_class(self._config.serializer)
+            self._serializer = t.cast(ISerializer, cls())
+        else:
+            from hexcore.infrastructure.cqrs.pydantic_serializer import PydanticSerializer
+
+            self._serializer = PydanticSerializer()
+        return self._serializer
+
+    def create_command_bus(self, **extra_kwargs: t.Any) -> ICommandBus:
+        """
+        Crea el CommandBus configurado.
+        Si no hay backend explícito, retorna InMemoryCommandBus con el enqueuer y el
+        serializer necesarios para el Smart Routing.
+        """
+        bus_config = self._config.command_bus
+        pipeline = _build_pipeline(bus_config)
+
+        if bus_config.backend is None:
+            self._assert_enqueuer_for_background_commands()
+            return InMemoryCommandBus(
+                registry=self._registry,
+                pipeline=pipeline,
+                enqueuer=self._enqueuer,
+                serializer=self.create_serializer(),
+                **extra_kwargs,
+            )
+
+        # Backend personalizado (ej. ProcrastinateCommandBus)
+        cls = _import_class(bus_config.backend)
+        return cls(
+            registry=self._registry,
+            serializer=self.create_serializer(),
+            pipeline=pipeline,
+            **bus_config.options,
+            **extra_kwargs,
+        )
+
+    def create_query_bus(self) -> IQueryBus:
+        """
+        Crea el QueryBus configurado.
+        Nota: Las queries siempre son síncronas en CQRS puro.
+        """
+        bus_config = self._config.query_bus
+        pipeline = _build_pipeline(bus_config)
+
+        if bus_config.backend is None:
+            return InMemoryQueryBus(
+                registry=self._registry,
+                pipeline=pipeline,
+            )
+
+        cls = _import_class(bus_config.backend)
+        return cls(
+            registry=self._registry,
+            pipeline=pipeline,
+            **bus_config.options,
+        )
+
+    def create_event_bus(self, **extra_kwargs: t.Any) -> IEventBus:
+        """
+        Crea el EventBus configurado.
+
+        Al bus in-memory se le pasan enqueuer y serializer para que los suscriptores
+        marcados con `@background_handler` se puedan enrutar.
+        """
+        bus_config = self._config.event_bus
+        pipeline = _build_pipeline(bus_config)
+
+        if bus_config.backend is None:
+            return InMemoryEventBus(
+                pipeline=pipeline,
+                enqueuer=self._enqueuer,
+                serializer=self.create_serializer(),
+                **extra_kwargs,
+            )
+
+        cls = _import_class(bus_config.backend)
+        return cls(
+            pipeline=pipeline,
+            **bus_config.options,
+            **extra_kwargs,
+        )
+
+    # ── Validación ────────────────────────────────────────────────────────────
+
+    def _assert_enqueuer_for_background_commands(self) -> None:
+        """
+        Falla al construir si hay commands de background registrados y no hay
+        enqueuer. El error en el primer dispatch llega demasiado tarde: para
+        entonces la petición del usuario ya está en vuelo.
+        """
+        if self._enqueuer is not None:
+            return
+
+        background = [
+            command_type.__name__
+            for command_type in self._registry.registered_commands
+            if getattr(command_type, "__cqrs_background__", False)
+        ]
+        if not background:
+            return
+
+        raise RuntimeError(
+            "CQRSFactory no tiene 'enqueuer', pero hay commands decorados con "
+            f"@background_command: {', '.join(sorted(background))}. "
+            "Pasá un ITaskEnqueuer al construir la factory, p. ej. "
+            "CQRSFactory(config, registry, enqueuer=ProcrastinateEnqueuer(app))."
+        )

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

@@ -8,6 +8,7 @@ import logging
 
 from hexcore.domain.cqrs.buses import ICommandBus, IQueryBus, IEventBus
 from hexcore.domain.cqrs.commands import Command
+from hexcore.domain.cqrs.context import is_worker_execution, local_execution
 from hexcore.domain.cqrs.queries import Query
 from hexcore.domain.events import DomainEvent
 from hexcore.domain.cqrs.task_queues import ITaskEnqueuer
@@ -28,6 +29,10 @@ class InMemoryCommandBus(ICommandBus):
     Si el comando está decorado con `@background_command` y se provee un `enqueuer`,
     el comando es automáticamente encolado para su ejecución en segundo plano
     sin bloquear el proceso actual (retornando None).
+
+    Cuando el mensaje viene de un worker (``IN_WORKER`` activo, lo pone el
+    ``CQRSConsumer``), el bus lo ejecuta **localmente** en vez de reencolarlo.
+    Esto permite usar el mismo bus en el proceso web y en el worker.
     """
 
     def __init__(
@@ -44,17 +49,19 @@ class InMemoryCommandBus(ICommandBus):
 
     async def dispatch(self, command: Command) -> t.Any:
         cmd_type = type(command)
-        
+
         # 1. Smart Routing: ¿Debe irse a background?
+        # Si ya estamos dentro de un worker, el mensaje viene de la cola: hay que
+        # ejecutarlo, no volver a encolarlo.
         is_background = getattr(cmd_type, "__cqrs_background__", False)
-        
-        if is_background:
+
+        if is_background and not is_worker_execution():
             if not self._enqueuer or not self._serializer:
                 raise RuntimeError(
                     f"El comando '{cmd_type.__name__}' requiere ejecución en background, "
                     "pero el InMemoryCommandBus no tiene configurado un 'enqueuer' o 'serializer'."
                 )
-            
+
             async def background_dispatcher(cmd: Command) -> None:
                 queue_name = getattr(cmd_type, "__cqrs_queue__", "default")
                 payload = self._serializer.serialize(cmd) # type: ignore
@@ -70,7 +77,10 @@ class InMemoryCommandBus(ICommandBus):
         async def final_handler(cmd: t.Any) -> t.Any:
             return await handler.handle(cmd)
 
-        return await self._pipeline.execute(command, final_handler)
+        # `local_execution` consume el flag de worker: si el handler despacha otro
+        # `@background_command`, ese sí debe encolarse.
+        with local_execution():
+            return await self._pipeline.execute(command, final_handler)
 
 
 class InMemoryQueryBus(IQueryBus):
@@ -129,9 +139,15 @@ class InMemoryEventBus(IEventBus):
 
     async def publish(self, event: DomainEvent) -> None:
         handlers = self._handlers.get(type(event), [])
+        # Si el evento viene de un worker, sus handlers de background se ejecutan
+        # aquí; reencolarlos sería un bucle infinito.
+        in_worker = is_worker_execution()
 
         for event_handler in handlers:
-            is_background = getattr(event_handler, "__cqrs_background_handler__", False)
+            is_background = (
+                getattr(event_handler, "__cqrs_background_handler__", False)
+                and not in_worker
+            )
 
             if is_background:
                 # Enrutamiento hacia background
@@ -161,4 +177,5 @@ class InMemoryEventBus(IEventBus):
                 ) -> None:
                     await _h(evt)
 
-                await self._pipeline.execute(event, final_handler)
+                with local_execution():
+                    await self._pipeline.execute(event, final_handler)