147 - Scheduling and Queueing Jobs

[jjohngrey]

Summary

• Integrate pg-boss using existing Postgres (DATABASE_URL) and add a central job runtime service at src/server/services/jobService.ts.
• Add a typed jobs module under src/server/jobs:
  • definitions/cleanup-orphaned-images.job.ts
  • definitions/scheduled-test.job.ts
  • registry.ts
  • types.ts
• Register jobService in DI (src/server/api/di-container.ts) and bootstrap it at server startup.
• Add test support via src/test/mocks/mock-job-service.ts and wire it into src/test/test-container.ts.

Key Design Changes

• Introduced a single-source job registry with:
  • known job-name typing (KnownJobName)
  • payload inference by job name (JobPayload<TJobName>)
  • duplicate-name guard at startup
• Unified scheduling API into run(jobName, data?, options?):
  • one-off immediate
  • one-off delayed (runAt / startAfter)
  • recurring (cron, optional startAt, endAt, tz)
• Startup scheduling simplified:
  • each job has optional startup
  • startup.cron present => recurring startup schedule
  • startup.cron absent => one-off startup enqueue
• Added correlation-id concept for recurring schedules:
  • run(..., { cron, correlationId }) creates correlation-specific recurring streams
  • unschedule(jobName, { correlationId }) cancels only that stream
  • unschedule(jobName) remains supported to cancel all schedules for a job

Test Plan

• Start backend and verify jobService boots without errors.
• Confirm recurring startup registration for jobs.cleanup-orphaned-images.
• Confirm one-off startup enqueue for jobs.scheduled-test.
• Call run() for:
  • immediate one-off
  • delayed one-off (runAt)
  • recurring (cron)
• Call unschedule(jobName, { correlationId }) and verify only targeted recurring stream is removed.
• Call unschedule(jobName) and verify all recurring schedules for that job are removed.
• Run unit/integration tests that use MockJobService.