Defining payload jobs

A payload job is a plain Ruby class that includes Zeridion::Flare::Job, declares its defaults with flare_options, and implements #perform(payload, ctx):

require "zeridion_flare/worker"

class SendWelcomeEmail
  include Zeridion::Flare::Job
  flare_options queue: "email", max_attempts: 5, timeout: 120

  def perform(payload, ctx)
    Mailer.welcome(payload["email"]).deliver_now
  end
end

Including the mixin registers the class with the worker automatically — no scan, no manual list. Construct a Worker and it picks up every job class that has been required.

`flare_options`

Option	Default	Meaning
`job_type:`	the class's fully-qualified name	The routing key on the wire.
`queue:`	`"default"`	Which queue this job is served on.
`max_attempts:`	`3`	Advisory attempt ceiling announced to the server.
`timeout:`	`1800`	Per-execution timeout, in seconds.
`payload_struct:`	none	Optional typed payload class (see below).

`job_type` is the routing key

By default job_type is the class's fully-qualified name (e.g. "SendWelcomeEmail", or "Mailers::SendWelcomeEmail" if namespaced). The worker only runs jobs whose job_type matches a registered class, so whoever enqueues the job must use the same string. On a shared queue with workers in other languages, set an explicit job_type: so every language agrees on the routing key:

flare_options job_type: "send_welcome_email", queue: "email"

Two classes claiming the same job_type raise an error at startup — a routing collision is caught immediately, not at dispatch time.

The payload

By default payload is the decoded JSON as a Hash with string keys:

def perform(payload, ctx)
  email = payload["email"]
  user_id = payload["user_id"]
end

A null/absent payload is passed through as nil.

Typed payloads

Opt into a typed payload with payload_struct: — any keyword-initializable class (a Struct, a Data, or your own):

WelcomePayload = Struct.new(:user_id, :email, keyword_init: true)

class SendWelcomeEmail
  include Zeridion::Flare::Job
  flare_options queue: "email", payload_struct: WelcomePayload

  def perform(payload, ctx)
    Mailer.welcome(payload.email).deliver_now   # payload is a WelcomePayload
  end
end

The worker hydrates the decoded JSON into the struct by keyword.

Outcome

A normal return acks the job succeeded. Any raised exception acks it failed, carrying the exception's class name and message back for diagnostics. The server then decides — based on the attempt count — whether to retry the job or park it; the worker never makes that call itself.

Enqueue a job

Jobs are enqueued with the thin client (or any SDK, or a raw HTTP call) — the worker does not enqueue its own work:

client = Zeridion::Flare::Client.new
client.create_job(
  "job_type" => "SendWelcomeEmail",
  "queue"    => "email",
  "payload"  => { "user_id" => "u_123", "email" => "alice@example.com" },
)

flare_options​

job_type is the routing key​

The payload​

Typed payloads​

Outcome​

Enqueue a job​

See also​