trails-cool/trails
1
1
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
trails/openspec/specs/background-jobs/spec.md
Ullrich Schäfer 91e80ace36
Archive demo-activity-bot, pg-boss-background-jobs, configurable-demo-persona 
Fold completed deltas into main specs (activity-feed, route-management,
infrastructure, planner-session), add new background-jobs and
demo-activity-bot capability specs, and move the three change dirs to
openspec/changes/archive/.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-05-03 21:17:39 +02:00

2.1 KiB
Raw Blame History

Purpose

Shared background job infrastructure for trails.cool apps, built on pg-boss. Provides a single PostgreSQL-backed queue used by both the planner and journal for one-shot, retried, and cron-scheduled work (e.g., session expiry, periodic maintenance), with worker lifecycle tied to the server process and observability via the existing Grafana stack.

Requirements

Requirement: Job queue initialization

The @trails-cool/jobs package SHALL initialize a pg-boss instance using the app's DATABASE_URL and export a function to start the worker.

Scenario: Worker starts with server

  • WHEN the planner or journal server starts
  • THEN pg-boss connects to PostgreSQL, creates/migrates the pgboss schema if needed, and begins polling for jobs

Scenario: Worker stops on shutdown

  • WHEN the server process receives SIGTERM
  • THEN pg-boss completes any in-progress jobs and stops gracefully before the process exits

Requirement: Cron job scheduling

The system SHALL support registering recurring jobs with cron expressions.

Scenario: Register a cron job

  • WHEN a job is registered with a cron expression (e.g., 0 * * * * for hourly)
  • THEN pg-boss creates a schedule that enqueues the job at the specified interval

Scenario: Cron job survives restart

  • WHEN the server process restarts
  • THEN existing cron schedules persist and continue firing without re-registration conflicts

Requirement: Job retry policy

Jobs SHALL support configurable retry policies with exponential backoff.

Scenario: Transient failure retry

  • WHEN a job handler throws an error
  • THEN pg-boss retries the job up to the configured retry limit with exponential backoff

Scenario: Permanent failure

  • WHEN a job exhausts all retries
  • THEN the job moves to the failed state and remains queryable for debugging

Requirement: Job handler timeout

Each job handler SHALL have a configurable execution timeout.

Scenario: Job exceeds timeout

  • WHEN a job handler does not complete within its timeout
  • THEN pg-boss marks the job as failed with a timeout error