0cf87b72ab
- authentication-methods: document completeAuth mode param ("redirect"|"json");
clarify add-passkey nudge (no dismiss mechanism, disappears on passkey add)
- journal-auth: session maxAge is 30 days; terms allow-list uses /legal/ prefix
matching (broader than fixed list of paths)
- session-notes: mark awareness isolation and UndoManager isolation as not yet
implemented (shared instances in current code)
- activity-feed: add fan-out scenario for visibility change to public
- explore: note that ?perPage is not yet implemented (hardcoded page size)
- multi-day-routes: add per-day GPX track split scenario (splitByDays option);
document overnight vs isDayBreak naming gap
- osm-poi-overlays: debounce is 800ms + 2000ms min interval (not 500ms);
retry is not automatic (fires on next viewport change)
- brouter-integration: rate limit corrected to 300/hour; add segment-cache
requirement (client caches per-pair segments)
- wahoo-route-push: OAuth state shape uses camelCase (returnTo, pushAfter
object) not snake_case with push_after boolean
- komoot-import: document noop adapter / ConnectedServiceManager bypass;
note four Komoot-specific routes that bypass the generic OAuth framework
- background-jobs: exponential backoff not wired (retryLimit only); add SIGINT
- connected-services: add revoked status; name ConnectionNotActiveError
- infrastructure: add INTEGRATION_SECRET and SENTRY_DSN to env var lists;
split secret decryption scenario by workflow (cd-apps vs cd-infra)
- secret-management: correct CD decryption — cd-apps only decrypts app.env;
cd-infra decrypts both
- transactional-emails: welcome email is async (pg-boss job); magic-link email
includes 6-digit numeric code
- journal-route-detail: websites are https: links (not mailto:); opening_hours
is also displayed
- local-dev-environment: add mobile app (Expo) dev commands
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2.2 KiB
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
pgbossschema if needed, and begins polling for jobs
Scenario: Worker stops on shutdown
- WHEN the server process receives SIGTERM or SIGINT
- 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 limits. The JobDefinition type exposes retryLimit and expireInSeconds; exponential backoff (retryDelay/retryBackoff in pg-boss terms) is not currently wired.
Scenario: Transient failure retry
- WHEN a job handler throws an error
- THEN pg-boss retries the job up to the configured
retryLimit
Scenario: Permanent failure
- WHEN a job exhausts all retries
- THEN the job moves to the
failedstate 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