hexcore 2.3.0__tar.gz → 2.5.0__tar.gz

{hexcore-2.3.0 → hexcore-2.5.0}/PKG-INFO

@@ -1,27 +1,46 @@
 Metadata-Version: 2.4
 Name: hexcore
-Version: 2.3.0
+Version: 2.5.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)
@@ -516,23 +535,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 +583,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 +595,98 @@ 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)
+# ¡Magia! Registra las tareas 'hexcore.process_command', 'hexcore.process_handler', etc.
+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:
 
-@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)
+```python
+from hexcore.infrastructure.cqrs.postgres_lock import PostgresLockProvider
 
-@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)
+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
+)
 ```
 
 ---

hexcore-2.3.0/hexcore.egg-info/PKG-INFO → hexcore-2.5.0/README.md

@@ -1,29 +1,3 @@
-Metadata-Version: 2.4
-Name: hexcore
-Version: 2.3.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"
-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.
 
@@ -516,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:
@@ -548,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
@@ -559,20 +550,98 @@ 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)
+# ¡Magia! Registra las tareas 'hexcore.process_command', 'hexcore.process_handler', etc.
+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**.
 
-@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)
+### 1. Implementa tu Repositorio
+Implementa `ICronJobRepository` para decirle al Scheduler de dónde leer la configuración (ej. usando SQLAlchemy, MongoDB o Redis):
 
-@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)
+```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
+)
 ```
 
 ---

{hexcore-2.3.0 → hexcore-2.5.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.5.0/hexcore/application/cqrs/scheduler.py

@@ -0,0 +1,99 @@
+"""
+Servicio encargado de evaluar y encolar tareas periódicas.
+"""
+from __future__ import annotations
+
+import asyncio
+import logging
+from datetime import datetime, timezone
+
+from hexcore.domain.cqrs.cron import ICronJobRepository, ILockProvider
+from hexcore.domain.cqrs.task_queues import ITaskEnqueuer
+
+logger = logging.getLogger(__name__)
+
+
+class DynamicScheduler:
+    """
+    Evalúa constantemente un repositorio de tareas periódicas y delega la ejecución
+    al TaskEnqueuer (Celery/Procrastinate). Permite cambiar configuraciones cron en "caliente".
+    """
+
+    def __init__(
+        self,
+        repository: ICronJobRepository,
+        enqueuer: ITaskEnqueuer,
+        lock_provider: ILockProvider | None = None,
+        tick_interval_seconds: int = 30
+    ) -> None:
+        self.repository = repository
+        self.enqueuer = enqueuer
+        self.lock_provider = lock_provider
+        self.tick_interval_seconds = tick_interval_seconds
+        
+        self._stop_event = asyncio.Event()
+
+    async def start(self) -> None:
+        """Inicia el bucle infinito del scheduler."""
+        import croniter
+        
+        logger.info(f"[*] DynamicScheduler started (Tick interval: {self.tick_interval_seconds}s)")
+        self._stop_event.clear()
+
+        # El estado base es el momento en que se levantó el scheduler.
+        last_check_time = datetime.now(timezone.utc)
+
+        while not self._stop_event.is_set():
+            try:
+                # 1. Esperamos el tiempo del tick
+                await asyncio.sleep(self.tick_interval_seconds)
+                
+                current_time = datetime.now(timezone.utc)
+                
+                # 2. Obtenemos la configuración fresca de BD
+                active_jobs = await self.repository.get_active_jobs()
+                
+                for job in active_jobs:
+                    # Determinamos desde cuándo chequear. Si el job tiene `last_run_at`, lo usamos.
+                    # Sino, usamos el `last_check_time` global del bucle.
+                    base_time = job.last_run_at or last_check_time
+                    
+                    try:
+                        # 3. Comprobamos si la expresión cron cayó entre base_time y current_time
+                        if croniter.croniter.match(job.cron_expression, current_time):
+                            # Evitar múltiples encolados en el mismo tick (minuto)
+                            # Intentar adquirir lock si hay proveedor (Distributed Locks)
+                            if self.lock_provider:
+                                # Usamos el minuto actual (truncado) para evitar colisiones distribuidas
+                                minute_key = current_time.replace(second=0, microsecond=0).isoformat()
+                                lock_key = f"hexcore:cron_lock:{job.job_id}:{minute_key}"
+                                
+                                lock_acquired = await self.lock_provider.acquire_lock(lock_key, ttl_seconds=60)
+                                if not lock_acquired:
+                                    logger.debug(f"CronJob '{job.job_id}' ignorado (lock adquirido por otra réplica).")
+                                    continue
+                                    
+                            logger.info(f"Encolando CronJob '{job.job_id}' -> Task: {job.task_name}")
+                            
+                            await self.enqueuer.enqueue_task(
+                                task_name=job.task_name,
+                                payload=job.payload,
+                                queue=job.queue
+                            )
+                            
+                            # Actualizamos el timestamp en el repositorio
+                            await self.repository.update_last_run(job.job_id, current_time)
+                            
+                    except Exception as e:
+                        logger.error(f"Error procesando el cron job {job.job_id}: {e}")
+
+                last_check_time = current_time
+
+            except asyncio.CancelledError:
+                break
+            except Exception as e:
+                logger.error(f"Error crítico en el bucle del scheduler: {e}")
+
+    def stop(self) -> None:
+        """Detiene el bucle del scheduler de forma segura."""
+        self._stop_event.set()

{hexcore-2.3.0 → hexcore-2.5.0}/hexcore/domain/cqrs/__init__.py

@@ -21,6 +21,7 @@ from .handlers import ICommandHandler, IQueryHandler
 from .buses import ICommandBus, IQueryBus, IEventBus
 from .middleware import IMiddleware
 from .serializer import ISerializer
+from .cron import CronJobDefinition, ICronJobRepository, ILockProvider
 
 __all__ = [
     # Nombres canónicos (Abstract*)
@@ -34,6 +35,10 @@ __all__ = [
     "AbstractMiddleware",
     "NextHandler",
     "AbstractSerializer",
+    # Cron
+    "CronJobDefinition",
+    "ICronJobRepository",
+    "ILockProvider",
     # Aliases (I*)
     "ICommandHandler",
     "IQueryHandler",

hexcore-2.5.0/hexcore/domain/cqrs/cron.py

@@ -0,0 +1,69 @@
+"""
+Definiciones de Dominio para el agendamiento dinámico de Tareas Periódicas (Cronjobs).
+"""
+import abc
+import typing as t
+from dataclasses import dataclass, field
+from datetime import datetime
+
+
+@dataclass
+class CronJobDefinition:
+    """
+    Representa la definición de una tarea periódica que debe ejecutarse.
+    Esta configuración normalmente se guarda en una BD para permitir
+    cambios "en caliente" (hot reload).
+    """
+    job_id: str
+    task_name: str
+    cron_expression: str
+    payload: dict[str, t.Any] = field(default_factory=dict)
+    queue: str = "default"
+    is_active: bool = True
+    
+    # Para control de estado si se usa sin locks distribuidos
+    last_run_at: datetime | None = None
+
+
+class ICronJobRepository(abc.ABC):
+    """
+    Repositorio que el usuario debe implementar (ej. usando SQLAlchemy, Beanie, etc.)
+    para proveer al DynamicScheduler la lista actualizada de tareas a ejecutar.
+    """
+
+    @abc.abstractmethod
+    async def get_active_jobs(self) -> list[CronJobDefinition]:
+        """
+        Retorna la lista de trabajos activos.
+        """
+        pass
+
+    @abc.abstractmethod
+    async def update_last_run(self, job_id: str, run_time: datetime) -> None:
+        """
+        Actualiza la fecha de última ejecución de un job para evitar
+        que se ejecute repetidamente en el mismo tick.
+        """
+        pass
+
+
+class ILockProvider(abc.ABC):
+    """
+    Proveedor de Locks Distribuidos (ej. Redis, PostgreSQL Advisory Locks).
+    Utilizado por el DynamicScheduler para garantizar que múltiples réplicas
+    del scheduler no ejecuten el mismo cronjob de manera duplicada.
+    """
+    
+    @abc.abstractmethod
+    async def acquire_lock(self, lock_key: str, ttl_seconds: int) -> bool:
+        """
+        Intenta adquirir un lock. Retorna True si lo consiguió, False si ya estaba tomado.
+        """
+        pass
+        
+    @abc.abstractmethod
+    async def release_lock(self, lock_key: str) -> None:
+        """
+        Libera el lock explícitamente (opcional, ya que el TTL lo hace automáticamente).
+        """
+        pass