hexcore 2.4.0__tar.gz → 2.5.0__tar.gz

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

@@ -1,29 +1,46 @@
 Metadata-Version: 2.4
 Name: hexcore
-Version: 2.4.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)
@@ -584,6 +601,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-2.5.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.
 
@@ -584,6 +556,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-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.4.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

hexcore-2.5.0/hexcore/infrastructure/cqrs/postgres_lock.py

@@ -0,0 +1,95 @@
+"""
+Proveedor de Locks Distribuidos utilizando PostgreSQL.
+Ideal para garantizar ejecución única de CronJobs cuando usas bases de datos SQL
+sin necesidad de añadir Redis a tu stack.
+"""
+from __future__ import annotations
+
+import logging
+from datetime import datetime, timezone, timedelta
+from typing import TYPE_CHECKING
+
+from hexcore.domain.cqrs.cron import ILockProvider
+
+if TYPE_CHECKING:
+    import asyncpg
+
+logger = logging.getLogger(__name__)
+
+
+class PostgresLockProvider(ILockProvider):
+    """
+    Implementación de ILockProvider basada en PostgreSQL (vía asyncpg).
+    Utiliza una tabla `hexcore_cron_locks` para gestionar la exclusión mutua
+    con soporte para TTL atómico.
+    """
+
+    def __init__(self, pool: asyncpg.Pool | asyncpg.Connection, table_name: str = "hexcore_cron_locks") -> None:
+        """
+        Args:
+            pool: Pool de conexiones o conexión simple de `asyncpg`.
+            table_name: Nombre de la tabla a utilizar para los locks.
+        """
+        self.pool = pool
+        self.table_name = table_name
+
+    async def setup(self) -> None:
+        """
+        Crea la tabla necesaria para los locks si no existe.
+        Debe llamarse al inicio de la aplicación.
+        """
+        query = f"""
+        CREATE TABLE IF NOT EXISTS {self.table_name} (
+            lock_key TEXT PRIMARY KEY,
+            expires_at TIMESTAMP WITH TIME ZONE NOT NULL
+        )
+        """
+        try:
+            if hasattr(self.pool, "execute"):
+                await self.pool.execute(query) # type: ignore
+        except Exception as e:
+            logger.error(f"Error creando tabla de locks en Postgres: {e}")
+            raise
+
+    async def acquire_lock(self, lock_key: str, ttl_seconds: int) -> bool:
+        """
+        Intenta adquirir un lock en Postgres.
+        
+        Args:
+            lock_key: La clave única del lock.
+            ttl_seconds: Tiempo de vida del lock en segundos (evita deadlocks).
+            
+        Returns:
+            True si el lock fue adquirido con éxito.
+            False si el lock ya estaba tomado y aún no ha expirado.
+        """
+        # Usamos UPSERT (ON CONFLICT) condicional
+        # Si no existe, lo inserta.
+        # Si existe pero expiró, lo actualiza y lo toma.
+        # Si existe y NO expiró, no hace nada (y no retorna fila).
+        query = f"""
+        INSERT INTO {self.table_name} (lock_key, expires_at)
+        VALUES ($1, NOW() + ($2 || ' seconds')::interval)
+        ON CONFLICT (lock_key) DO UPDATE
+        SET expires_at = NOW() + ($2 || ' seconds')::interval
+        WHERE {self.table_name}.expires_at < NOW()
+        RETURNING lock_key;
+        """
+        
+        try:
+            # fetchrow returns a record if RETURNING gave something, else None
+            result = await self.pool.fetchrow(query, lock_key, str(ttl_seconds)) # type: ignore
+            return result is not None
+        except Exception as e:
+            logger.error(f"Error intentando adquirir lock de Postgres para {lock_key}: {e}")
+            return False
+
+    async def release_lock(self, lock_key: str) -> None:
+        """
+        Libera el lock explícitamente eliminándolo de la tabla.
+        """
+        query = f"DELETE FROM {self.table_name} WHERE lock_key = $1"
+        try:
+            await self.pool.execute(query, lock_key) # type: ignore
+        except Exception as e:
+            logger.error(f"Error intentando liberar lock de Postgres para {lock_key}: {e}")

hexcore-2.5.0/hexcore/infrastructure/cqrs/redis_lock.py

@@ -0,0 +1,62 @@
+"""
+Proveedor de Locks Distribuidos utilizando Redis.
+Ideal para garantizar ejecución única de CronJobs en múltiples réplicas.
+"""
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING
+
+from hexcore.domain.cqrs.cron import ILockProvider
+
+if TYPE_CHECKING:
+    from redis.asyncio import Redis
+
+logger = logging.getLogger(__name__)
+
+
+class RedisLockProvider(ILockProvider):
+    """
+    Implementación de ILockProvider basada en Redis.
+    Utiliza el comando SET NX EX para asegurar exclusión mutua de manera atómica
+    y evitar "deadlocks" mediante la expiración (TTL).
+    """
+
+    def __init__(self, redis_client: Redis) -> None:
+        """
+        Args:
+            redis_client: Instancia activa de `redis.asyncio.Redis`.
+        """
+        self.redis = redis_client
+
+    async def acquire_lock(self, lock_key: str, ttl_seconds: int) -> bool:
+        """
+        Intenta adquirir un lock en Redis.
+        
+        Args:
+            lock_key: La clave única del lock (ej. "hexcore:cron_lock:job_1:2026-07-28T01:02:00").
+            ttl_seconds: Tiempo de vida del lock en segundos (evita deadlocks).
+            
+        Returns:
+            True si el lock fue adquirido con éxito (nadie lo tenía).
+            False si el lock ya estaba tomado por otro proceso.
+        """
+        try:
+            # SET key "1" NX (solo si no existe) EX ttl_seconds (expira automáticamente)
+            # Retorna True (si lo seteó) o None/False (si ya existía)
+            result = await self.redis.set(lock_key, "locked", nx=True, ex=ttl_seconds)
+            return bool(result)
+        except Exception as e:
+            logger.error(f"Error intentando adquirir lock de Redis para {lock_key}: {e}")
+            # En caso de error de Redis, asumimos False para evitar ejecución duplicada por dudas,
+            # o podríamos dejar que explote. En un scheduler, es más seguro no correr.
+            return False
+
+    async def release_lock(self, lock_key: str) -> None:
+        """
+        Libera el lock explícitamente.
+        """
+        try:
+            await self.redis.delete(lock_key)
+        except Exception as e:
+            logger.error(f"Error intentando liberar lock de Redis para {lock_key}: {e}")

{hexcore-2.4.0 → hexcore-2.5.0}/hexcore/infrastructure/repositories/base.py

@@ -1,7 +1,10 @@
 from __future__ import annotations
 import abc
 import typing as t
-from sqlalchemy.ext.asyncio import AsyncSession
+try:
+    from sqlalchemy.ext.asyncio import AsyncSession
+except ImportError:
+    class AsyncSession: ... # type: ignore
 
 from hexcore.domain.base import BaseEntity
 from hexcore.domain.repositories import IBaseRepository
@@ -12,12 +15,12 @@ T = t.TypeVar("T", bound=BaseEntity)
 
 class BaseSQLAlchemyRepository(IBaseRepository[T], abc.ABC, t.Generic[T]):
     def __init__(self, uow: IUnitOfWork):
-        self._session: t.Optional[AsyncSession] = getattr(uow, "session", None)
+        self._session: t.Optional["AsyncSession"] = getattr(uow, "session", None)
 
         super().__init__(uow)
         
     @property
-    def session(self) -> AsyncSession:
+    def session(self) -> "AsyncSession":
         if self._session is None:
             raise ValueError("El repositorio no está asociado a una sesión de base de datos.")
         return self._session