Job

Layeron Job is the task execution product for a Layeron backend. It runs named backend tasks, records every run and attempt, retries failed work, supports delayed execution, and gives you a status surface for operational task flows.

Job is designed for work that should happen outside the original request: webhook delivery, email sending, image processing, report generation, imports, cleanup tasks, provider synchronization, and other work that benefits from durable status and retry history.

import { backend } from "@layeron/core"
import { job } from "@layeron/modules"

const app = backend({
  project: "acme-api",
})

const jobs = job({
  name: "background",
  namespace: "app",
})

app.use(jobs)

jobs.task("deliver-webhook", {
  retry: {
    attempts: 8,
    backoff: {
      type: "custom",
      delaysSeconds: [10, 30, 120, 300, 900],
    },
  },
}, async (payload, ctx) => {
  await deliverWebhook(payload, ctx)
})

Supported features

Job covers the core task execution surface that backend apps need:

• Named task definitions.
• JSON payloads with stable run IDs.
• Immediate enqueue.
• Delayed execution with delaySeconds.
• Run-at execution with runAt.
• Per-task retry policies.
• Fixed, exponential, and custom retry delays.
• Run status and attempt history.
• Idempotency keys for duplicate-safe enqueue.
• Cancellation for queued, delayed, retrying, or running work.
• Replay from a previous run payload.
• Queue-backed execution through the Job Product Worker.
• Product logs and observability metrics.

Core concepts

Job has four central records:

• Task: A named handler registered in application code. A task owns the execution function and retry defaults.
• Run: One requested execution of a task with a payload. Runs move through states such as queued, running, succeeded, retrying, and dead_lettered.
• Attempt: One try at executing a run. A run can have several attempts when failures are retryable.
• Queue message: The delivery envelope that wakes the Job Product Worker to execute a run.

Execution model

jobs.enqueue(...)
  -> Job Product RPC
  -> Job run state
  -> Queue Product delivery message
  -> Job queue handler
  -> task handler
  -> attempt and run state

Job uses the Layeron Queue Product for delivery and the Layeron Database Product for run history. The Job Product Worker owns retry decisions and status records. Queue owns the delivery message and Cloudflare Queue binding.

Job patterns

Job has several usage patterns. Each one creates runs and attempts through the same execution model.

Pattern	When to use	How runs are created or managed
One-off job	Send one email, call one provider, process one upload	jobs.enqueue(...)
Delayed job	Run once after a delay or at a known time	jobs.enqueue(..., { delaySeconds }) or runAt
Retrying job	Retry a task after failures	jobs.task(..., { retry })
Managed run	Read, cancel, or replay task runs	jobs.runs.get(...), jobs.runs.list(...), jobs.runs.cancel(...), or jobs.runs.replay(...)
Webhook delivery job	Deliver events with retry, status, and replay	jobs.enqueue("deliver-webhook", ...)

Read Job types for code for each pattern.

Common use cases

Use Job when you need a durable execution boundary:

• Webhook delivery: Store the inbound event, enqueue a delivery run, retry delivery with provider-aware delays, and replay failed runs from the dashboard or admin API.
• Email and notifications: Return from a user request quickly and send the email in the background.
• Media processing: Enqueue thumbnail generation, metadata extraction, or format conversion after upload.
• Data imports: Split imports into task runs with retryable steps and visible failure records.
• Provider sync: Pull data from an external API and retry on rate limits.

Integration with Layeron

Job compiles through the same Layeron product pipeline as other backend products:

• Queue delivers work to the Job Product Worker.
• Database state stores runs, attempts, transitions, and idempotency.
• Storage can be used by your task handler for files, artifacts, or large payload snapshots.
• Policy can guard enqueue, read, cancel, and replay operations when your app declares a Policy module.
• Log and Observability record product execution, failures, retries, and run latency.

Policy is optional. App-internal tasks can use Job without configuring Policy.

Next Steps

• Get started: Configure Job, define a task, enqueue work, inspect runs, cancel, and replay.
• Job types: Choose one-off, delayed, retrying, managed run, or webhook delivery jobs.
• Execution model: Understand tasks, runs, attempts, delivery, and idempotency.
• Retries and failures: Configure retry defaults, task overrides, failure behavior, replay, and cancellation.
• Delays and scheduling: Use immediate runs, delaySeconds, runAt, delayed replay, and cancellation.
• Examples: Adapt common task patterns for signups, uploads, search rebuilds, and failed runs.
• API reference: Review Job options, retry settings, queue settings, and result contracts.