sp2-verify-1770324794/.sdlc/features/async-jobs/tasks.md

Implementation Tasks: Async Jobs

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

Task List

Task 1: Create Redis Queue Package

ID: task-1-redis-queue-pkg Status: pending Blocked By: none

Create the shared pkg/redisqueue package with job queue abstractions.

Files to create:

• pkg/redisqueue/job.go - Job struct and JobStatus constants
• pkg/redisqueue/queue.go - RedisQueue implementation

Acceptance Criteria:

• Job struct with ID, Type, Payload, Status, timestamps
• JobStatus constants: pending, running, completed, failed
• Enqueue: store job data + push ID to queue
• Dequeue: BLPOP queue + fetch job data + set running
• GetJob: fetch job by ID
• UpdateStatus: update job status fields

---

Task 2: Add Redis Configuration to API Service

ID: task-2-api-redis-config Status: pending Blocked By: task-1-redis-queue-pkg

Add Redis URL configuration and client initialization to the API service.

Files to modify:

• services/api/internal/config/config.go - Add RedisURL field
• services/api/cmd/server/main.go - Initialize Redis client

Acceptance Criteria:

• Config loads REDIS_URL from environment
• Redis client created in main.go
• Graceful handling of connection errors

---

Task 3: Implement Job Port and Service

ID: task-3-job-service Status: pending Blocked By: task-2-api-redis-config

Create the job port interface and service layer for job operations.

Files to create:

• services/api/internal/port/job.go - JobQueue interface
• services/api/internal/service/job.go - JobService implementation

Acceptance Criteria:

• JobQueue interface defines Create and Get operations
• JobService implements business logic
• Service validates input before queue operations

---

Task 4: Implement Job HTTP Handlers

ID: task-4-job-handlers Status: pending Blocked By: task-3-job-service

Create HTTP handlers for POST /jobs and GET /jobs/{id}.

Files to create:

• services/api/internal/api/handlers/job.go - Job handlers
• services/api/internal/api/handlers/job_test.go - Handler tests

Files to modify:

• services/api/internal/api/routes.go - Register routes

Acceptance Criteria:

• POST /api/api/jobs creates job, returns 201
• GET /api/api/jobs/{id} returns job status
• GET /api/api/jobs/{id} returns 404 for unknown
• Request validation with proper error messages
• Tests cover success and error cases

---

Task 5: Add Redis Configuration to Worker

ID: task-5-worker-redis-config Status: pending Blocked By: task-1-redis-queue-pkg

Add Redis URL and job simulation configuration to the worker.

Files to modify:

• workers/background-processor/internal/config/config.go - Add Redis and simulation config

Acceptance Criteria:

• Config loads REDIS_URL from environment
• Config loads JOB_SIMULATION_DURATION with default (2s)

---

Task 6: Implement Worker Job Processing

ID: task-6-worker-job-processing Status: pending Blocked By: task-5-worker-redis-config

Implement the async job handler in the background worker.

Files to create:

• workers/background-processor/internal/handlers/jobs.go - Job processor

Files to modify:

• workers/background-processor/cmd/worker/main.go - Register job handler

Acceptance Criteria:

• Worker dequeues jobs from Redis
• Worker simulates work with configurable delay
• Worker updates job status to completed
• Worker handles errors and marks jobs failed
• Graceful shutdown waits for in-flight jobs

---

Dependency Graph

task-1-redis-queue-pkg
       │
       ├───────────────────┐
       ▼                   ▼
task-2-api-redis-config   task-5-worker-redis-config
       │                   │
       ▼                   ▼
task-3-job-service        task-6-worker-job-processing
       │
       ▼
task-4-job-handlers

Implementation Order

1. task-1-redis-queue-pkg (no dependencies)
2. task-2-api-redis-config (depends on 1)
3. task-5-worker-redis-config (depends on 1, can run in parallel with 2)
4. task-3-job-service (depends on 2)
5. task-4-job-handlers (depends on 3)
6. task-6-worker-job-processing (depends on 5)