Cronos — Distributed Job Scheduler

Cronos is a high-availability, fault-tolerant distributed cron and job-scheduling platform built with Node.js (ES Modules), Express, Redis, and PostgreSQL.

It manages and executes background tasks across multiple worker instances, using Redis-based distributed locking to guarantee zero task overlap and prevent duplicate executions during job ticks.

---

Key Features

• Distributed Task Locking: Utilizes Redis atomic lock acquisition (SET key worker_id NX PX ttl) with Lua-scripted lock releases to ensure only one worker executes a task per schedule tick.
• Dynamic Cron Scheduling: Supports sub-minute and standard cron expressions for recurring background tasks.
• Execution Auditing: Maintains full execution history in PostgreSQL, logging run states (running, completed, failed), timestamps, and error traces.
• Node Failover & Resilience: Worker nodes dynamically contend for locks, allowing remaining active nodes to seamlessly handle job ticks if an instance goes down.
• REST Management API: Endpoints to dynamically register, list, pause, resume, and manually trigger scheduled jobs.

---

Tech Stack

Layer	Technology
Runtime / Language	Node.js (ES2022+ ESM native)
Framework	Express.js
Distributed Locking & Cache	Redis 7 (ioredis)
Persistence & Audit Log	PostgreSQL 16 (pg)
Cron Engine	node-cron
Containerization	Docker / Docker Compose

---

Architecture Overview

                               ┌────────────────────────────────┐
                               │       Client / REST API        │
                               └───────────────┬────────────────┘
                                               │
                                               ▼
                                  ┌─────────────────────────┐
                                  │   Cronos API Gateway    │
                                  └────────────┬────────────┘
                                               │ (Register Job)
                                               ▼
                                  ┌─────────────────────────┐
                                  │     PostgreSQL DB       │
                                  │   (Job Definitions)     │
                                  └────────────┬────────────┘
                                               │
               ┌───────────────────────────────┼───────────────────────────────┐
               │ (Tick Event)                  │ (Tick Event)                  │ (Tick Event)
               ▼                               ▼                               ▼
    ┌────────────────────┐          ┌────────────────────┐          ┌────────────────────┐
    │   Worker Node 1    │          │   Worker Node 2    │          │   Worker Node 3    │
    └──────────┬─────────┘          └──────────┬─────────┘          └──────────┬─────────┘
               │                               │                               │
               └───────────────────────────────┼───────────────────────────────┘
                                               │
                                               ▼
                                  ┌─────────────────────────┐
                                  │     Redis Lock Store    │
                                  │ (SET key worker_id NX)  │
                                  └────────────┬────────────┘
                                               │
                     ┌─────────────────────────┴─────────────────────────┐
                     ▼                                                   ▼
          [ Lock Acquired (200 OK) ]                          [ Lock Denied (409) ]
                     │                                                   │
         [ Execute Job Payload ]                             [ Skip Execution / Pass ]
                     │
         [ Log Result to Postgres ]
                     │
         [ Release Lock via Lua ]

---

Quick Start Guide

Prerequisites

• Node.js: >= 18.x
• Docker & Docker Compose

1. Installation

Clone the repository and install dependencies:

git clone https://github.com/your-username/cronos.git
cd cronos
npm install

2. Environment Setup

Create a .env file in the root directory:

PORT=3002
DATABASE_URL=postgresql://cronos_user:cronos_password@localhost:5432/cronos_db
REDIS_URL=redis://localhost:6379

3. Start Infrastructure

Launch PostgreSQL and Redis containers using Docker Compose:

docker-compose up -d

4. Run Development Server

Start the service with live reloading:

npm run dev

---

API Endpoints

1. Health Check

GET /health

Verifies active connections to PostgreSQL and Redis.

Response (200 OK):

{
  "status": "ok",
  "service": "Cronos Distributed Scheduler",
  "database": "PostgreSQL Connected",
  "cache": "Redis Connected"
}

2. Register Job

POST /api/jobs

Body:

{
  "name": "Sync Database Indexes",
  "cron_expression": "*/5 * * * *",
  "payload": { "action": "reindex", "target": "users" }
}

3. Pause / Resume Job

PATCH /api/jobs/:id/toggle

---

License

MIT