Feature Specification: Async Jobs

Feature: async-jobs Status: approved Author: Claude Created: 2026-02-05

Overview

Implement an async job processing system using Redis as the job queue backend. The API service exposes endpoints to create and query jobs, while the background worker processes jobs from the Redis queue.

Requirements

Functional Requirements

POST /api/api/jobs - Create a new async job
- Accepts JSON payload with job type and data
- Pushes job to Redis queue
- Returns job ID and initial status ("pending")
GET /api/api/jobs/{id} - Get job status
- Returns current job status and metadata
- Statuses: pending, running, completed, failed
Worker Processing
- Worker pops jobs from Redis queue (blocking pop)
- Simulates work (configurable delay)
- Updates job status in Redis upon completion/failure

Non-Functional Requirements

Jobs must survive API restarts (persisted in Redis)
Multiple workers can process jobs concurrently
Job status queries must be fast (O(1) lookup)

API Design

Create Job

POST /api/api/jobs
Content-Type: application/json

{
  "type": "process_data",
  "payload": {
    "key": "value"
  }
}

Response (201 Created):

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "type": "process_data",
    "status": "pending",
    "created_at": "2026-02-05T10:00:00Z"
  }
}

Get Job Status

GET /api/api/jobs/{id}

Response (200 OK):

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "type": "process_data",
    "status": "completed",
    "payload": {"key": "value"},
    "created_at": "2026-02-05T10:00:00Z",
    "started_at": "2026-02-05T10:00:01Z",
    "completed_at": "2026-02-05T10:00:03Z"
  }
}

Data Model

Job Structure (stored in Redis)

type Job struct {
    ID          string         `json:"id"`
    Type        string         `json:"type"`
    Payload     map[string]any `json:"payload"`
    Status      string         `json:"status"`  // pending, running, completed, failed
    CreatedAt   time.Time      `json:"created_at"`
    StartedAt   *time.Time     `json:"started_at,omitempty"`
    CompletedAt *time.Time     `json:"completed_at,omitempty"`
    Error       string         `json:"error,omitempty"`
}

Redis Keys

jobs:queue - List for pending jobs (RPUSH/BLPOP)
jobs:data:{id} - Hash for job metadata

Acceptance Criteria

POST /api/api/jobs creates a job and returns 201 with job ID
GET /api/api/jobs/{id} returns job status
GET /api/api/jobs/{id} returns 404 for unknown jobs
Worker processes jobs from queue
Job status updates are visible via GET endpoint
Simulated work delay is configurable

2.7 KiB Raw Permalink Blame History