goplt/docs/content/stories/epic5/5.5-scheduler-jobs.md

Story 5.5: Scheduler and Background Jobs System

Metadata

• Story ID: 5.5
• Title: Scheduler and Background Jobs System
• Epic: 5 - Infrastructure Adapters
• Status: Pending
• Priority: High
• Estimated Time: 6-8 hours
• Dependencies: 1.1, 5.1

Goal

Implement a complete scheduler and background job system with cron jobs, job queues, retries, and job status tracking.

Description

This story implements a scheduler system using Asynq (Redis-backed) that supports cron jobs for periodic tasks and job queues for background processing. Jobs can be registered from modules and tracked.

Deliverables

1. Scheduler Interface (pkg/scheduler/scheduler.go)

• Scheduler interface with:
  • Cron(spec string, job JobFunc) error - Schedule cron job
  • Enqueue(queue string, payload any) error - Enqueue job
  • RegisterJob(name string, handler JobHandler) error - Register job handler

2. Asynq Implementation (internal/infra/scheduler/asynq_scheduler.go)

• Redis-backed job queue
• Cron jobs for periodic tasks
• Job retries and backoff
• Job status tracking
• Job result storage

3. Job Registry (internal/infra/scheduler/job_registry.go)

• Register jobs from modules
• Start job processor on app startup
• Job lifecycle management

4. Example Jobs

• Cleanup expired tokens (daily)
• Send digest emails (weekly)
• Database cleanup tasks

5. Job Monitoring API

• GET /api/v1/jobs/status - Job status endpoint
• Job history and statistics

6. Configuration

• Scheduler config in config/default.yaml:
  • Redis connection (shared with cache)
  • Concurrency settings
  • Retry settings

7. DI Integration

• Provider function for Scheduler
• Register in DI container

Acceptance Criteria

• Scheduler interface is defined
• Cron jobs can be scheduled
• Jobs can be enqueued
• Jobs are processed correctly
• Job retries work
• Job status is tracked
• Example jobs run on schedule
• Job monitoring API works

Files to Create/Modify

• pkg/scheduler/scheduler.go - Scheduler interface
• internal/infra/scheduler/asynq_scheduler.go - Asynq implementation
• internal/infra/scheduler/job_registry.go - Job registry
• internal/infra/scheduler/jobs.go - Example jobs
• internal/di/providers.go - Add scheduler provider
• config/default.yaml - Add scheduler config