Background Jobs & Cron

SolidB owns the queue, scheduling, and retries. Soli provides:

• A file-based handler convention (app/jobs/email_job.sl ↔ EmailJob).
• A small language-side API (Job, Webhook, Cron) plus per-class facade methods.
• A built-in callback route (POST /_jobs/run/:name) that SolidB hits when a class-target job fires.

When you enqueue a class-target job, Soli sends it to SolidB along with a callback URL. When SolidB is ready to run it, it POSTs back into your app with an HMAC-signed payload, which dispatches to XJob.perform(args). When you enqueue via Webhook, SolidB POSTs straight to the URL you supplied — no Soli-side dispatcher in the loop.

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_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. SolidB itself fires the HTTP request when the job runs — no Soli-side dispatcher involved.

When the job fires, SolidB POSTs the payload as JSON with X-Webhook-Event: job, X-Webhook-Delivery: <job-id>, and (when a secret is set) X-Webhook-Signature (lowercase hex HMAC-SHA256 of the body). Non-2xx responses count as failure and are retried with the same exponential backoff as script jobs.

Pure string builders — they produce standard 5-token cron strings. Calling them has no side effect; only Cron.schedule writes to SolidB.

You can always pass a raw cron string instead.

The POST /_jobs/run/:name route dispatches to XJob.perform(args) on whichever class the URL names — it can call any loaded class with a static perform. To stop a passing client from invoking arbitrary code, every callback must carry a valid signature.

• A webhook secret is required. If neither SOLI_WEBHOOK_SECRET nor SOLI_JOBS_SECRET is set, Soli does not register /_jobs/run/:name at all — workers log a warning at boot and SolidB callbacks will get 404s until a secret is configured.
• SolidB sends X-Webhook-Signature (canonical) whose value is the lowercase hex HMAC-SHA256 of the raw request body, keyed with the configured secret. The legacy X-Job-Signature header is also accepted by the dispatcher.
• Soli verifies the signature with secure_compare() (constant-time), so callers can't probe the secret by timing 401 responses.
• Bad signature → 401, missing class → 503, handler error → 500. Only a valid signature lets the request reach cls.perform(args).

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 = 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 — SolidB POSTs the payload directly 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