Quickstart & Sample: Microservicios DLS

Sample Project

Proyecto de microservicios de referencia construido con @caerus-dev/sdk. Demuestra exclusión mutua distribuida, Fencing Tokens monotónicos, adquisición streaming y resolución de deadlocks en tiempo real.

Idea Central del Sample

Comprender cómo interactúan múltiples microservicios concurrentes al solicitar locks puede ser complejo. Este proyecto de referencia provee una arquitectura modular con workers independientes (2 o 3 procesos) que compiten por recursos compartidos (como file:reports_export o network:cloud_uploader).

Cada evento refleja respuestas del motor de Caerus mediante Server-Sent Events (SSE) y grafica el estado de cada worker: IDLE, STARTING_TX, HOLDING, QUEUED o DEADLOCK_ABORTED.

Los 4 Escenarios de Concurrencia

Lectura Concurrente

1. Lectura Compartida (SHARED_READ)

Muestra cómo múltiples workers adquieren locks SHARED_READ sobre el mismo archivo en paralelo sin bloquearse entre sí, hasta que un escritor exclusivo solicita el recurso.

Exclusión Mutua

2. Tarea Simple (EXCLUSIVE)

Ejecuta una transacción exclusiva con generación de Fencing Token monotónico. El worker toma el lock, escribe en el archivo y libera la transacción de forma segura.

Ciclo Cruzado

3. Detección de Deadlock (Cruzado)

Worker A retiene el Recurso 1 y solicita el 2; Worker B retiene el 2 y solicita el 1. El motor detecta el ciclo en el grafo y aborta a la víctima designada para desatorar el sistema.

Alta Concurrencia

4. Estampida (100 Workers)

Lanza una ráfaga masiva de solicitudes simultáneas contra un solo recurso para verificar la estabilidad de la cola distribuida, streaming gRPC y ausencia de condiciones de carrera.

Grafo de Espera y Selección de Víctima

En el escenario de Deadlock, el inspector destaca con color ámbar y rojo las aristas que forman el ciclo cerrado (Worker A ➔ Recurso 2 ➔ Worker B ➔ Recurso 1 ➔ Worker A).

El motor de Caerus selecciona a la víctima con menor prioridad o menor progreso transaccional, emite una señal de aborto para liberar sus recursos retenidos y permite que los workers restantes completen su trabajo de forma transparente.

Repositorio Oficial en GitHub

El código completo de los microservicios, el archivo de variables (.env.example) y la guía detallada de configuración y ejecución local se encuentran disponibles en GitHub:

caerus-dev/demo-dls

Next.js · TypeScript · @caerus-dev/sdk · Server-Sent Events · Fencing Tokens · Deadlocks

Explorar Repositorio en GitHub

💡 ¿Qué encontrarás en el README del repositorio?

Pasos de ejecución rápida con pnpm install y pnpm dev.
Explicación técnica de la intercepción de llamadas al SDK con AsyncLocalStorage.
Configuración de variables de entorno para clúster local gRPC (puerto 9090) o cloud.
Parámetros de la plantilla task_processing requerida en el Dashboard.