hexcore 2.3.0__tar.gz → 2.4.0__tar.gz

{hexcore-2.3.0/hexcore.egg-info → hexcore-2.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hexcore
-Version: 2.3.0
+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
@@ -22,6 +22,8 @@ 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)
@@ -516,23 +518,39 @@ class ProcrastinateEnqueuer(ITaskEnqueuer):
         await process_generic_task.defer_async(task_name=task_name, payload=payload)
 ```
 
-#### 3. Configurar tus Buses (Enrutamiento Automático)
+#### 2. Configurar tus Buses con un Adaptador Oficial
 
-Al inyectar tu enqueuer en los buses estándar de memoria en tu API, estos adquieren la habilidad de enrutamiento inteligente. (Si usas un comando decorado pero no inyectas un enqueuer, HexCore levantará una excepción tempranamente).
+HexCore provee adaptadores *plug & play* para **Celery** y **Procrastinate**. Simplemente importa el enqueuer, pásale tu app y configúralo en los buses de memoria.
 
-```python
-from hexcore.application.cqrs.in_memory_buses import InMemoryCommandBus, InMemoryEventBus
+Si además deseas persistencia o distribución de Eventos entre múltiples workers/servidores (Pub/Sub), puedes cambiar el `InMemoryEventBus` por `RedisEventBus`, `PostgresEventBus` o `RabbitMQEventBus`:
 
-enqueuer = ProcrastinateEnqueuer()
+```python
+from hexcore.application.cqrs.in_memory_buses import InMemoryCommandBus
+from hexcore.infrastructure.task_queues.celery_adapter import CeleryEnqueuer
+from hexcore.infrastructure.cqrs.redis_bus import RedisEventBus
+from celery import Celery
+import redis.asyncio as redis
+
+# 1. Adaptador de Task Queue (Para Comandos asíncronos y Event Handlers asíncronos)
+app = Celery("my_app", broker="redis://localhost:6379/0")
+enqueuer = CeleryEnqueuer(app)
 serializer = PydanticSerializer()
 
-# El bus evalúa: ¿Tiene el comando @background_command? Si es así, usa el enqueuer.
 command_bus = InMemoryCommandBus(registry=registry, enqueuer=enqueuer, serializer=serializer)
 
-# El bus evalúa suscriptores: ¿Tienen @background_handler? Si es así, usa el enqueuer.
-event_bus = InMemoryEventBus(enqueuer=enqueuer, serializer=serializer)
+# 2. Event Bus (Para enviar los Eventos por la red)
+redis_client = redis.from_url("redis://localhost:6379/0")
+event_bus = RedisEventBus(
+    redis_client=redis_client,
+    serializer=serializer,
+    stream_name="hexcore:events",
+    group_name="api_workers",
+    enqueuer=enqueuer  # <-- Importante para inyectarle la habilidad de Smart Routing
+)
 ```
 
+> **Tip:** También dispones de `PostgresEventBus(pool, serializer, channel_name)` que usa `LISTEN/NOTIFY` nativo si quieres 0 dependencias externas aparte de tu BD de siempre.
+
 #### 4. Ejecutar tareas genéricas
 
 Para encolar la tarea genérica (`@background_task`), la llamas indirectamente pasándola por el enqueuer:
@@ -548,10 +566,11 @@ await enqueuer.enqueue_task(
 
 #### 5. Levantar el Worker (Consumidor Universal)
 
-En el entrypoint de tu worker (ej. Celery o Procrastinate), usa el `CQRSConsumer` de HexCore para deserializar y ejecutar los payloads interceptados. El consumidor usa resolución dinámica para invocar la función correcta automáticamente.
+En el entrypoint de tu worker, usa la función utilitaria `register_hexcore_celery_tasks` para autoconfigurar las rutas en una sola línea:
 
 ```python
 from hexcore.infrastructure.workers.consumer import CQRSConsumer
+from hexcore.infrastructure.task_queues.celery_adapter import register_hexcore_celery_tasks
 
 consumer = CQRSConsumer(
     command_bus=command_bus, # Tu CommandBus configurado
@@ -559,20 +578,8 @@ consumer = CQRSConsumer(
     serializer=serializer
 )
 
-@app.task(name="process_cqrs_command")
-async def process_cqrs_command(payload: dict):
-    # HexCore deserializa y ejecuta el Command usando el CommandBus local
-    await consumer.process_command(payload)
-
-@app.task(name="process_cqrs_handler")
-async def process_cqrs_handler(handler_name: str, payload: dict):
-    # HexCore resuelve y ejecuta exclusivamente el Event Handler asíncrono
-    await consumer.process_handler(handler_name, payload)
-
-@app.task(name="process_generic_task")
-async def process_generic_task(task_name: str, payload: dict):
-    # HexCore resuelve e inyecta los kwargs a la función pura
-    await consumer.process_task(task_name, payload)
+# ¡Magia! Registra las tareas 'hexcore.process_command', 'hexcore.process_handler', etc.
+register_hexcore_celery_tasks(app, consumer)
 ```
 
 ---

{hexcore-2.3.0 → hexcore-2.4.0}/README.md

@@ -490,23 +490,39 @@ class ProcrastinateEnqueuer(ITaskEnqueuer):
         await process_generic_task.defer_async(task_name=task_name, payload=payload)
 ```
 
-#### 3. Configurar tus Buses (Enrutamiento Automático)
+#### 2. Configurar tus Buses con un Adaptador Oficial
 
-Al inyectar tu enqueuer en los buses estándar de memoria en tu API, estos adquieren la habilidad de enrutamiento inteligente. (Si usas un comando decorado pero no inyectas un enqueuer, HexCore levantará una excepción tempranamente).
+HexCore provee adaptadores *plug & play* para **Celery** y **Procrastinate**. Simplemente importa el enqueuer, pásale tu app y configúralo en los buses de memoria.
 
-```python
-from hexcore.application.cqrs.in_memory_buses import InMemoryCommandBus, InMemoryEventBus
+Si además deseas persistencia o distribución de Eventos entre múltiples workers/servidores (Pub/Sub), puedes cambiar el `InMemoryEventBus` por `RedisEventBus`, `PostgresEventBus` o `RabbitMQEventBus`:
 
-enqueuer = ProcrastinateEnqueuer()
+```python
+from hexcore.application.cqrs.in_memory_buses import InMemoryCommandBus
+from hexcore.infrastructure.task_queues.celery_adapter import CeleryEnqueuer
+from hexcore.infrastructure.cqrs.redis_bus import RedisEventBus
+from celery import Celery
+import redis.asyncio as redis
+
+# 1. Adaptador de Task Queue (Para Comandos asíncronos y Event Handlers asíncronos)
+app = Celery("my_app", broker="redis://localhost:6379/0")
+enqueuer = CeleryEnqueuer(app)
 serializer = PydanticSerializer()
 
-# El bus evalúa: ¿Tiene el comando @background_command? Si es así, usa el enqueuer.
 command_bus = InMemoryCommandBus(registry=registry, enqueuer=enqueuer, serializer=serializer)
 
-# El bus evalúa suscriptores: ¿Tienen @background_handler? Si es así, usa el enqueuer.
-event_bus = InMemoryEventBus(enqueuer=enqueuer, serializer=serializer)
+# 2. Event Bus (Para enviar los Eventos por la red)
+redis_client = redis.from_url("redis://localhost:6379/0")
+event_bus = RedisEventBus(
+    redis_client=redis_client,
+    serializer=serializer,
+    stream_name="hexcore:events",
+    group_name="api_workers",
+    enqueuer=enqueuer  # <-- Importante para inyectarle la habilidad de Smart Routing
+)
 ```
 
+> **Tip:** También dispones de `PostgresEventBus(pool, serializer, channel_name)` que usa `LISTEN/NOTIFY` nativo si quieres 0 dependencias externas aparte de tu BD de siempre.
+
 #### 4. Ejecutar tareas genéricas
 
 Para encolar la tarea genérica (`@background_task`), la llamas indirectamente pasándola por el enqueuer:
@@ -522,10 +538,11 @@ await enqueuer.enqueue_task(
 
 #### 5. Levantar el Worker (Consumidor Universal)
 
-En el entrypoint de tu worker (ej. Celery o Procrastinate), usa el `CQRSConsumer` de HexCore para deserializar y ejecutar los payloads interceptados. El consumidor usa resolución dinámica para invocar la función correcta automáticamente.
+En el entrypoint de tu worker, usa la función utilitaria `register_hexcore_celery_tasks` para autoconfigurar las rutas en una sola línea:
 
 ```python
 from hexcore.infrastructure.workers.consumer import CQRSConsumer
+from hexcore.infrastructure.task_queues.celery_adapter import register_hexcore_celery_tasks
 
 consumer = CQRSConsumer(
     command_bus=command_bus, # Tu CommandBus configurado
@@ -533,20 +550,8 @@ consumer = CQRSConsumer(
     serializer=serializer
 )
 
-@app.task(name="process_cqrs_command")
-async def process_cqrs_command(payload: dict):
-    # HexCore deserializa y ejecuta el Command usando el CommandBus local
-    await consumer.process_command(payload)
-
-@app.task(name="process_cqrs_handler")
-async def process_cqrs_handler(handler_name: str, payload: dict):
-    # HexCore resuelve y ejecuta exclusivamente el Event Handler asíncrono
-    await consumer.process_handler(handler_name, payload)
-
-@app.task(name="process_generic_task")
-async def process_generic_task(task_name: str, payload: dict):
-    # HexCore resuelve e inyecta los kwargs a la función pura
-    await consumer.process_task(task_name, payload)
+# ¡Magia! Registra las tareas 'hexcore.process_command', 'hexcore.process_handler', etc.
+register_hexcore_celery_tasks(app, consumer)
 ```
 
 ---

hexcore-2.4.0/hexcore/infrastructure/cqrs/postgres_bus.py

@@ -0,0 +1,126 @@
+"""
+Event Bus basado en PostgreSQL LISTEN / NOTIFY.
+Ligero, rápido y no requiere infraestructura adicional si ya usas PostgreSQL.
+"""
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import typing as t
+
+from hexcore.domain.cqrs.buses import IEventBus
+from hexcore.domain.cqrs.task_queues import ITaskEnqueuer
+from hexcore.domain.events import DomainEvent
+
+if t.TYPE_CHECKING:
+    from asyncpg import Pool, Connection
+    from hexcore.infrastructure.cqrs.pydantic_serializer import PydanticSerializer
+
+
+logger = logging.getLogger(__name__)
+
+
+class PostgresEventBus(IEventBus):
+    """
+    Implementación de IEventBus utilizando PostgreSQL LISTEN/NOTIFY.
+    Nota: LISTEN/NOTIFY no persiste los eventos una vez entregados. 
+    Ideal para eventos efímeros o arquitecturas más simples.
+    """
+
+    def __init__(
+        self,
+        pool: "Pool",
+        serializer: "PydanticSerializer",
+        channel_name: str,
+        enqueuer: ITaskEnqueuer | None = None,
+    ) -> None:
+        self.pool = pool
+        self._serializer = serializer
+        self.channel_name = channel_name
+        self.enqueuer = enqueuer
+        
+        self._handlers: dict[type[DomainEvent], list[t.Callable[..., t.Any]]] = {}
+        self._event_types_by_name: dict[str, type[DomainEvent]] = {}
+        self._stop_event = asyncio.Event()
+        self._listener_connection: "Connection | None" = None
+
+    def subscribe(self, event_type: type[DomainEvent], handler: t.Callable[..., t.Any]) -> None:
+        if event_type not in self._handlers:
+            self._handlers[event_type] = []
+        self._handlers[event_type].append(handler)
+        
+        fqn = f"{event_type.__module__}.{event_type.__qualname__}"
+        self._event_types_by_name[fqn] = event_type
+
+    async def publish(self, event: DomainEvent) -> None:
+        payload = self._serializer.serialize(event)
+        json_payload = json.dumps(payload)
+        
+        async with self.pool.acquire() as conn:
+            # En PostgreSQL, pg_notify recibe el canal y el payload en texto.
+            await conn.execute("SELECT pg_notify($1, $2)", self.channel_name, json_payload)
+
+    async def start_consuming(self) -> None:
+        """
+        Inicia el consumo adquiriendo una conexión dedicada y escuchando el canal.
+        """
+        self._stop_event.clear()
+        
+        # Adquirir una conexión persistente para el listener
+        self._listener_connection = await self.pool.acquire()
+        try:
+            await self._listener_connection.add_listener(self.channel_name, self._handle_notify)
+            logger.info(f"[*] PostgresEventBus listening on channel '{self.channel_name}'")
+            
+            # Bloquear hasta que alguien llame a stop()
+            await self._stop_event.wait()
+            
+        except asyncio.CancelledError:
+            pass
+        finally:
+            if self._listener_connection:
+                try:
+                    await self._listener_connection.remove_listener(self.channel_name, self._handle_notify)
+                except Exception as e:
+                    logger.warning(f"Error removing postgres listener: {e}")
+                await self.pool.release(self._listener_connection)
+                self._listener_connection = None
+
+    def _handle_notify(self, connection: "Connection", pid: int, channel: str, payload: str) -> None:
+        """
+        Callback invocada por asyncpg cuando recibe un NOTIFY.
+        Dado que es síncrona/concurrente desde el driver, delegamos la carga real
+        a un asyncio.create_task para evitar bloquear la conexión.
+        """
+        asyncio.create_task(self._process_message(payload))
+
+    async def _process_message(self, json_payload: str) -> None:
+        try:
+            payload_dict = json.loads(json_payload)
+            event_name = payload_dict.get("__type__")
+            
+            event_type = self._event_types_by_name.get(event_name)
+            if not event_type:
+                return
+
+            event = self._serializer.deserialize(payload_dict)
+            handlers = self._handlers.get(event_type, [])
+            
+            for handler in handlers:
+                is_background = getattr(handler, "__cqrs_background_handler__", False)
+                if is_background:
+                    queue_name = getattr(handler, "__cqrs_queue__", "default")
+                    if not self.enqueuer:
+                        raise RuntimeError(f"El handler asíncrono {handler.__name__} requiere un enqueuer.")
+                    
+                    handler_ref = getattr(handler, "__cqrs_handler_name__", f"{handler.__module__}.{handler.__name__}")
+                    await self.enqueuer.enqueue_handler(handler_ref, payload_dict, queue_name)
+                else:
+                    await handler(event)
+                    
+        except Exception as e:
+            logger.error(f"Error parseando o ejecutando evento de PostgreSQL NOTIFY: {e}")
+
+    async def stop(self) -> None:
+        self._stop_event.set()

hexcore-2.4.0/hexcore/infrastructure/cqrs/redis_bus.py

@@ -0,0 +1,143 @@
+"""
+Event Bus basado en Redis Streams.
+Soporta alta concurrencia mediante Consumer Groups.
+"""
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import typing as t
+import uuid
+
+from hexcore.domain.cqrs.buses import IEventBus
+from hexcore.domain.cqrs.task_queues import ITaskEnqueuer
+from hexcore.domain.events import DomainEvent
+
+if t.TYPE_CHECKING:
+    from redis.asyncio import Redis
+    from hexcore.infrastructure.cqrs.pydantic_serializer import PydanticSerializer
+
+
+logger = logging.getLogger(__name__)
+
+
+class RedisEventBus(IEventBus):
+    """
+    Implementación de IEventBus usando Redis Streams.
+    """
+
+    def __init__(
+        self,
+        redis_client: "Redis",
+        serializer: "PydanticSerializer",
+        stream_name: str,
+        group_name: str,
+        consumer_name: str | None = None,
+        enqueuer: ITaskEnqueuer | None = None,
+    ) -> None:
+        self.redis = redis_client
+        self._serializer = serializer
+        self.stream_name = stream_name
+        self.group_name = group_name
+        self.consumer_name = consumer_name or f"consumer-{uuid.uuid4()}"
+        self.enqueuer = enqueuer
+        
+        self._handlers: dict[type[DomainEvent], list[t.Callable[..., t.Any]]] = {}
+        self._event_types_by_name: dict[str, type[DomainEvent]] = {}
+        self._stop_event = asyncio.Event()
+
+    def subscribe(self, event_type: type[DomainEvent], handler: t.Callable[..., t.Any]) -> None:
+        if event_type not in self._handlers:
+            self._handlers[event_type] = []
+        self._handlers[event_type].append(handler)
+        
+        fqn = f"{event_type.__module__}.{event_type.__qualname__}"
+        self._event_types_by_name[fqn] = event_type
+
+    async def publish(self, event: DomainEvent) -> None:
+        payload = self._serializer.serialize(event)
+        # Redis streams accepts dicts with string keys and string values
+        json_payload = json.dumps(payload)
+        await self.redis.xadd(self.stream_name, {"payload": json_payload})
+
+    async def start_consuming(self) -> None:
+        """
+        Inicia el consumo utilizando Grupos de Consumidores de Redis.
+        """
+        import redis.exceptions
+
+        # Asegurar que el grupo existe, creándolo si no existe (con MKSTREAM)
+        try:
+            await self.redis.xgroup_create(self.stream_name, self.group_name, id="$", mkstream=True)
+        except redis.exceptions.ResponseError as e:
+            if "BUSYGROUP Consumer Group name already exists" not in str(e):
+                raise e
+
+        logger.info(f"[*] RedisEventBus consuming from stream '{self.stream_name}' (group: {self.group_name}, consumer: {self.consumer_name})")
+        self._stop_event.clear()
+
+        while not self._stop_event.is_set():
+            try:
+                # Bloquea hasta 1000ms esperando mensajes no leídos ('>')
+                messages = await self.redis.xreadgroup(
+                    groupname=self.group_name,
+                    consumername=self.consumer_name,
+                    streams={self.stream_name: ">"},
+                    count=10,
+                    block=1000,
+                )
+                
+                if not messages:
+                    continue
+                
+                # messages: [[b'stream_name', [(b'message_id', {b'payload': b'...'}), ...]]]
+                for stream, stream_messages in messages:
+                    for message_id, message_data in stream_messages:
+                        await self._handle_message(message_id, message_data)
+                        
+            except asyncio.CancelledError:
+                break
+            except Exception as e:
+                logger.error(f"Error procesando mensaje de Redis: {e}")
+                await asyncio.sleep(1)
+
+    async def _handle_message(self, message_id: bytes, message_data: dict[bytes, bytes]) -> None:
+        try:
+            payload_bytes = message_data.get(b"payload")
+            if not payload_bytes:
+                return
+
+            payload_dict = json.loads(payload_bytes)
+            event_name = payload_dict.get("__type__")
+            
+            event_type = self._event_types_by_name.get(event_name)
+            if not event_type:
+                # Evento no registrado localmente, lo saltamos y confirmamos
+                await self.redis.xack(self.stream_name, self.group_name, message_id)
+                return
+
+            event = self._serializer.deserialize(payload_dict)
+            handlers = self._handlers.get(event_type, [])
+            
+            # Ejecutar handlers (respetando Smart Routing)
+            for handler in handlers:
+                is_background = getattr(handler, "__cqrs_background_handler__", False)
+                if is_background:
+                    queue_name = getattr(handler, "__cqrs_queue__", "default")
+                    if not self.enqueuer:
+                        raise RuntimeError(f"El handler asíncrono {handler.__name__} requiere un enqueuer.")
+                    
+                    handler_ref = getattr(handler, "__cqrs_handler_name__", f"{handler.__module__}.{handler.__name__}")
+                    await self.enqueuer.enqueue_handler(handler_ref, payload_dict, queue_name)
+                else:
+                    await handler(event)
+
+            # Confirmar mensaje
+            await self.redis.xack(self.stream_name, self.group_name, message_id)
+            
+        except Exception as e:
+            logger.error(f"Error parseando o ejecutando evento de Redis (ID {message_id}): {e}")
+
+    async def stop(self) -> None:
+        self._stop_event.set()

hexcore-2.4.0/hexcore/infrastructure/task_queues/__init__.py

@@ -0,0 +1,3 @@
+"""
+Adaptadores opcionales para Task Queues (Celery, Procrastinate).
+"""

hexcore-2.4.0/hexcore/infrastructure/task_queues/celery_adapter.py

@@ -0,0 +1,83 @@
+"""
+Adaptador para Celery.
+Permite encolar comandos y tareas usando Celery, y proporciona 
+utilidades para auto-registrar las tareas asíncronas en el Worker.
+"""
+from __future__ import annotations
+
+import asyncio
+import typing as t
+
+from hexcore.domain.cqrs.task_queues import ITaskEnqueuer
+
+if t.TYPE_CHECKING:
+    try:
+        from celery import Celery
+    except ImportError:
+        Celery = t.Any
+        
+    from hexcore.infrastructure.workers.consumer import CQRSConsumer
+
+
+class CeleryEnqueuer(ITaskEnqueuer):
+    """
+    Adaptador que utiliza Celery para encolar comandos, eventos y tareas.
+    Dado que `ITaskEnqueuer` tiene métodos asíncronos y Celery `.send_task` 
+    es síncrono (bloqueante), utiliza `asyncio.to_thread` para no congelar
+    el Event Loop principal (ej. FastAPI).
+    """
+
+    def __init__(self, app: "Celery") -> None:
+        self.app = app
+
+    async def enqueue_command(self, command_name: str, payload: dict[str, t.Any], queue: str) -> None:
+        await asyncio.to_thread(
+            self.app.send_task,
+            "hexcore.process_command",
+            kwargs={"payload": payload},
+            queue=queue,
+        )
+
+    async def enqueue_event(self, event_name: str, payload: dict[str, t.Any], queue: str) -> None:
+        # Los eventos genéricos (publish a todos los workers) rara vez se envían a Celery
+        # de esta forma. Normalmente se usa enqueue_handler. Se provee para completitud.
+        pass
+
+    async def enqueue_handler(self, handler_name: str, payload: dict[str, t.Any], queue: str) -> None:
+        await asyncio.to_thread(
+            self.app.send_task,
+            "hexcore.process_handler",
+            kwargs={"handler_name": handler_name, "payload": payload},
+            queue=queue,
+        )
+
+    async def enqueue_task(self, task_name: str, payload: dict[str, t.Any], queue: str) -> None:
+        await asyncio.to_thread(
+            self.app.send_task,
+            "hexcore.process_task",
+            kwargs={"task_name": task_name, "payload": payload},
+            queue=queue,
+        )
+
+
+def register_hexcore_celery_tasks(app: "Celery", consumer: "CQRSConsumer") -> None:
+    """
+    Auto-registra las tareas base de HexCore en una aplicación Celery.
+    Esto permite que un worker de Celery esté listo para recibir mensajes
+    generados por el Smart Routing de HexCore.
+    
+    Dado que las tareas de Celery son síncronas y el Consumer de HexCore es 
+    asíncrono, se envuelven en `asyncio.run()`.
+    """
+
+    @app.task(name="hexcore.process_command", bind=True)
+    def process_command(self: t.Any, payload: dict[str, t.Any]) -> None:
+        asyncio.run(consumer.process_command(payload))
+
+    @app.task(name="hexcore.process_handler", bind=True)
+    def process_handler(self: t.Any, handler_name: str, payload: dict[str, t.Any]) -> None:
+        asyncio.run(consumer.process_handler(handler_name, payload))
+
+    @app.task(name="hexcore.process_task", bind=True)
+    def process_task(self: t.Any, task_name: str, payload: dict[str, t.Any]) -> None:
+        asyncio.run(consumer.process_task(task_name, payload))

hexcore-2.4.0/hexcore/infrastructure/task_queues/procrastinate_adapter.py

@@ -0,0 +1,61 @@
+"""
+Adaptador para Procrastinate.
+Permite encolar comandos y tareas usando Procrastinate, y proporciona 
+utilidades para auto-registrar las tareas asíncronas en el Worker.
+"""
+from __future__ import annotations
+
+import typing as t
+
+from hexcore.domain.cqrs.task_queues import ITaskEnqueuer
+
+if t.TYPE_CHECKING:
+    try:
+        import procrastinate
+    except ImportError:
+        procrastinate = t.Any
+        
+    from hexcore.infrastructure.workers.consumer import CQRSConsumer
+
+
+class ProcrastinateEnqueuer(ITaskEnqueuer):
+    """
+    Adaptador que utiliza Procrastinate (PostgreSQL) para encolar comandos y tareas.
+    Totalmente asíncrono y nativo.
+    """
+
+    def __init__(self, app: "procrastinate.App") -> None:
+        self.app = app
+
+    async def enqueue_command(self, command_name: str, payload: dict[str, t.Any], queue: str) -> None:
+        task = self.app.configure_task(name="hexcore.process_command", queue=queue)
+        await task.defer_async(payload=payload)
+
+    async def enqueue_event(self, event_name: str, payload: dict[str, t.Any], queue: str) -> None:
+        pass
+
+    async def enqueue_handler(self, handler_name: str, payload: dict[str, t.Any], queue: str) -> None:
+        task = self.app.configure_task(name="hexcore.process_handler", queue=queue)
+        await task.defer_async(handler_name=handler_name, payload=payload)
+
+    async def enqueue_task(self, task_name: str, payload: dict[str, t.Any], queue: str) -> None:
+        task = self.app.configure_task(name="hexcore.process_task", queue=queue)
+        await task.defer_async(task_name=task_name, payload=payload)
+
+
+def register_hexcore_procrastinate_tasks(app: "procrastinate.App", consumer: "CQRSConsumer") -> None:
+    """
+    Auto-registra las tareas base de HexCore en una aplicación Procrastinate.
+    """
+
+    @app.task(name="hexcore.process_command")
+    async def process_command(payload: dict[str, t.Any]) -> None:
+        await consumer.process_command(payload)
+
+    @app.task(name="hexcore.process_handler")
+    async def process_handler(handler_name: str, payload: dict[str, t.Any]) -> None:
+        await consumer.process_handler(handler_name, payload)
+
+    @app.task(name="hexcore.process_task")
+    async def process_task(task_name: str, payload: dict[str, t.Any]) -> None:
+        await consumer.process_task(task_name, payload)