Jobs

Jobs provide background processing for events in Snaapi. Define jobs that match event patterns and execute registered processor functions, with automatic retry, concurrency locking, and full execution tracking.

Job Definitions

A job connects an event pattern to a processor function:

Processors

A job processor is a function that handles matched events. Processors are registered by name and invoked when a matching event occurs.

Processor Signature

type JobProcessor = (
  event: Event,
  execution: JobExecution,
) => Promise<Record<string, unknown> | void>;

Processor Definition

interface JobProcessorDefinition {
  name: string;
  description: string;
  processor: JobProcessor;
}

Built-in Processors

Execution Tracking

When an event matches a job's event pattern, a JobExecution record is created to track processing:

Execution Status Transitions

pending → running → completed
                  → failed → pending (retry)

Retry Configuration

Jobs use exponential backoff for failed executions. Defaults are used when no custom retryConfig is provided:

The delay between retries is calculated as:

delay = min(initialDelayMs * backoffMultiplier ^ (attempt - 1), maxDelayMs)

On failure, the execution remains in pending status with a calculated nextRetryAt timestamp until all retry attempts are exhausted, at which point it transitions to failed.

Concurrency Locking

Job executions use timestamp-based locking to prevent concurrent processing of the same execution:

• The locked field stores a timestamp when an execution is being processed
• Only one worker can acquire the lock at a time
• KV store uses atomic versionstamp checks for lock acquisition
• Locks prevent duplicate processing in distributed environments

Invocation Records

Each individual attempt of a job execution is tracked as an ExecutionInvocation:

Database Tables