Background Jobs & Cron

Soli owns the whole lifecycle — storage, claiming, execution, retries, and cron:

• Enqueue writes a row to the _jobs collection on your default connection (works on SolidB, PostgreSQL, MySQL, and SQLite). On a SQL connection the queue indexes itself on first enqueue (state, run_at, priority), so the claim query does not scan the table every poll tick.
• Claim is atomic — Postgres FOR UPDATE SKIP LOCKED, MySQL a token claim, SQLite the database write lock (BEGIN IMMEDIATE), SolidB an If-Match compare-and-swap — so several app processes can share one queue without double-running a job.
• Execute happens on a worker pool thread with its own loaded interpreter, never on a web worker, so a slow job can't delay requests.
• Retry is exponential backoff with a lease; a job whose process dies is reclaimed once its lease expires.

Nothing calls back into your app over HTTP: there is no callback URL, no inbound route, and no shared secret to configure. Webhook.* jobs are delivered by the engine itself, with the same retry policy.

Job classes get a set of static helpers automatically — no inheritance needed.

The trailing queue_or_opts argument is either a queue-name string or an options hash { queue, priority, max_retries } — priority is an Int and higher runs first.

WelcomeEmailJob.perform_later({ "user_id": 42 })        # Default queue
WelcomeEmailJob.perform_in("5 minutes", { "user_id": 42 })
WelcomeEmailJob.perform_at("2026-05-01T08:00:00Z", { "user_id": 42 })
WelcomeEmailJob.perform_now({ "user_id": 42 })                  # Inline, no queue
WelcomeEmailJob.perform_later({ "user_id": 42 }, "mailers")     # Pick a queue
WelcomeEmailJob.perform_later({ "user_id": 42 }, { "queue": "mailers", "priority": 10 })

For work that targets a URL rather than a Soli handler class. The engine fires the HTTP request itself when the job is due, so it works on every database adapter.

Soli POSTs the payload as JSON with X-Webhook-Event: job, X-Webhook-Delivery: <job-id>, and (when a secret is configured — per-job secret, else SOLI_WEBHOOK_SECRET) X-Webhook-Signature, the lowercase hex HMAC-SHA256 of the body. Non-2xx responses count as failure and are retried with the same exponential backoff as class-target jobs.

Pure string builders — they produce six-field cron strings (sec min hour day-of-month month day-of-week). That leading seconds field is what distinguishes them from five-field Unix crontab lines, which are rejected rather than silently never firing. Calling a builder has no side effect; only Cron.schedule writes a schedule.

You can always pass a raw cron string instead.

Cron.every refuses an interval cron cannot express, rather than emitting one that never runs: "90 seconds" (no sub-minute field), "90 minutes" (the minute field reaches 59 and 90 is not a whole number of hours), "25 hours" (the hour field reaches 23) and "40 days" (day-of-month reaches 31) are each an error naming what to use instead. Every in-range value is accepted — but note */N means “every value of this field divisible by N”, and each field restarts on its own cycle, so Cron.every("45 minutes") fires at :00 and :45 and the gap across the hour is 15 minutes. That is how cron works everywhere; pick a divisor of 60 (or of 24 for hours) for even spacing.

• Backoff is exponential from 5 seconds, doubling per attempt, capped at 1 hour, with a small per-job spread so a burst of sibling failures doesn't retry in lockstep.
• Attempts increment at claim time, not at completion — so a worker that dies mid-job counts the lost attempt.
• Leases recover crashes. A running row whose locked_until has passed becomes claimable again, so a killed process's work is picked up rather than stranded. The poller heartbeats in-flight leases each tick.
• Exhausted budgets are buried. Once attempts passes max_retries the row becomes dead with its last error, and is kept for inspection.
• Completed rows are pruned after SOLI_JOBS_RETENTION_SECS; failed and dead rows are not.

Send an email asynchronously

class WelcomeEmailJob
  static def perform(args: Hash)
    user = User.find(args["user_id"])
    Mailer.send(user.email, "Welcome!")
  end
end

def create
  user = User.create(req["json"])
  WelcomeEmailJob.perform_later({ "user_id": user.id })
  return redirect("/users/" + str(user.id))
end

Recurring report (declarative)

class NightlyReportJob
  static cron: String = Cron.daily_at("03:00")

  static def perform(args: Hash)
    Report.generate()
    AdminMailer.send_summary()
  end
end

Fire-and-forget webhook to a third party

No handler class needed — the engine POSTs the payload to the URL when the job is due. Retries on non-2xx with exponential backoff.

def create
  order = Order.create(req["json"])
  Webhook.enqueue(
    "https://hooks.slack.com/services/T00/B00/abc",
    { "text": "Order #" + str(order.id) + " placed" },
    { "queue": "external", "max_retries": 5 }
  )
  return redirect("/orders/" + str(order.id))
end