Background Jobs (Queue/Worker/Scheduler) Server Manager

Tech Stack

• Runtime: Node.js
• Framework: Express.js
• Language: TypeScript
• Scheduling: Internal cron ticker and scheduled job promoter
• Storage: In-memory (no external dependencies)
• Port: 9026 (configurable via PORT environment variable)

Setup/Usage

Installation & Running

npm install
npm run build
npm start

Development Mode

npm run dev

Runs with hot-reload enabled.

Environment Variables

API Endpoints

All endpoints are prefixed with /api and return responses in the format { "data": ... } for success or { "error": "..." } for errors.

Health Check

GET /health

• Returns server health status with timestamp

Jobs

POST /api/jobs

• Create a new job
• Body: name (required), queue, payload, priority, max_retries, scheduled_at

GET /api/jobs

• List all jobs with filtering
• Query params: status, queue, name, limit, offset

GET /api/jobs/:id

• Retrieve a single job by ID

POST /api/jobs/:id/complete

• Mark job as completed

POST /api/jobs/:id/fail

• Mark job as failed with optional error message

POST /api/jobs/:id/retry

• Retry a failed job

POST /api/jobs/:id/cancel

• Cancel a pending or running job

POST /api/jobs/bulk/cancel

• Cancel multiple jobs by IDs
• Body: ids (array of UUIDs)

POST /api/jobs/bulk/retry

• Retry multiple failed jobs by IDs
• Body: ids (array of UUIDs)

DELETE /api/jobs/:id

• Permanently delete a job

Queues

POST /api/queues/:name/pause

• Pause a queue to prevent job claiming

POST /api/queues/:name/resume

• Resume a paused queue

GET /api/queues/:name/status

• Get queue statistics (pending, running, failed, completed counts)

Workers

POST /api/workers

• Register a new worker
• Body: name (required), queues (array)

GET /api/workers

• List all registered workers

GET /api/workers/:id

• Retrieve a single worker by ID

POST /api/workers/:id/heartbeat

• Send worker heartbeat to maintain active status

POST /api/workers/:id/claim

• Claim a job from assigned queues

DELETE /api/workers/:id

• Unregister a worker

Cron Jobs

POST /api/cron

• Create a new cron job
• Body: name, schedule (cron expression), job_name, queue, payload

GET /api/cron

• List all cron jobs

GET /api/cron/:id

• Retrieve a single cron job

PATCH /api/cron/:id/toggle

• Enable/disable a cron job

POST /api/cron/tick

• Manually trigger cron job evaluation

DELETE /api/cron/:id

• Delete a cron job

Metrics

GET /api/metrics

• Get overall system metrics

GET /api/metrics/throughput

• Get job throughput statistics

GET /api/metrics/queues/:name

• Get metrics for a specific queue

POST /api/metrics/reset

• Reset all metrics

Rate Limiting

GET /api/rate-limit

• Get current rate limit status

GET /api/rate-limit/config

• Get rate limit configuration

PATCH /api/rate-limit/config or PUT /api/rate-limit/config

• Update rate limit configuration

POST /api/rate-limit/reset

• Reset rate limit counters

Testing

All 38 API endpoints have been tested and verified (38/38 PASS). The test suite covers job creation, worker registration, queue operations, cron scheduling, metrics, and rate limiting functionality.