Modules
A producer client for the JoobQ SDK gateway (/api/v1/sdk) of a self-hosted JoobQUI server.
JoobQ Pro batches: 1 to 1000 jobs created, filled and sealed in one call (JoobQ.create_batch/2,
POST /sdk/batches), with callback jobs the gateway enqueues when the batch gets there: :on_failure at the first
dead member, :on_complete once every member is counted, and :on_success then too when none is dead. A
callback is written by the gateway only, exactly once, with "batch" => %{"id", "kind", "total", "succeeded", "failed"} in its payload. Without a Pro licence the gateway answers 402 (:pro_required).
The options of one JoobQ instance, as given to {JoobQ, opts} in a supervision tree.
The request context of the job a handler runs, carried on to the work it starts. Inside perform/1 (and its
middleware), JoobQ.enqueue/4, enqueue_async/4, enqueue_many/2, create_batch/2 and start_workflow/3 lay
the running job's context (job.context: tenant_id, request_id, traceparent, ...) under the context you
give them, whose keys win, as every SDK's ctx.enqueue, ctx.start and ctx.create_batch do. Keys are strings
(an atom key is turned into its string).
A gateway call that did not succeed: the gateway answered an error status, or it could not be reached.
A job: the %JoobQ.Job{} a worker leased and hands to JoobQ.Worker.perform/1, and the body of
POST /sdk/jobs that JoobQ.enqueue/4 sends.
Code around every job's run, given to an instance as middleware: [MyApp.Timing, {MyApp.Tenant, key: "t"}]
(JoobQ.Config): the first listed is the outermost, the worker's perform/1 the innermost call.
A failure that sends the job to the dead letter queue at once, its retries unused: raise it in
JoobQ.Worker.perform/1 (raise JoobQ.NonRetryable, "the account is closed") or return
{:error, JoobQ.NonRetryable.exception("the account is closed")}.
Sliding-window rate limits kept by the gateway (JoobQ Pro): JoobQ.rate_limit/4 reserves a slot with
POST /sdk/rate-limit, checking and consuming it in one step. It answers {:ok, %{"allowed" => true, ...}} when a
slot was granted, or "allowed" => false with "retry_after_ms", the milliseconds until one frees up. It paces
your own code (an enqueue, a call to a partner); it does not enqueue or wait. Without a Pro licence the gateway
answers 402: {:error, %JoobQ.Error{reason: :pro_required}}.
Cron and interval job schedules, registered from code with POST /sdk/schedules (JoobQ.register_schedule/4).
The gateway refuses this SDK's version: 426 sdk_too_old, when the server's JOOBQUI_SDK_MIN_VERSION is above
it. Every call answers it until the SDK is upgraded, so none is made again: a producer call answers
{:error, %JoobQ.SdkTooOldError{}} (its ! variant raises it), and a worker that meets it stops at once (see
JoobQ.Config, :queues).
The processes of one JoobQ instance: the Finch pool its gateway calls go through and, when :queues is given, the
worker's. Start it in the host application's supervision tree with {JoobQ, url: ..., token: ...} (see
JoobQ.Config for the options).
The :telemetry events of JoobQ. Each is a span: :start (measurements system_time, monotonic_time), then
:stop or :exception (measurements duration, monotonic_time, in native time units).
One gateway call: JSON in, JSON out, through the instance's Finch pool. The worker's processes call again on their
own when a call of theirs fails (JoobQ.Worker); a producer's call is not.
A job handler, run by the worker of an instance that lists it in :workers (JoobQ.Config)
Builds a workflow blueprint: the steps an SDK worker runs and the engine conducts (it retries, waits, compensates
and keeps the run's state). JoobQ.Workflow builds and registers workflows; JoobQ.Workflows starts runs and
talks to them.
A reference to data a workflow node reads, a ${...} path the gateway and the engine know: the run's input
(input/0,1), a step's output (output/1,2), the update being handled (update_input/0,1) or any path
(ref/1, also ${signals...} and ${updates...}). Build them with the functions of JoobQ.Workflow.
Workflow runs from a producer (JoobQ Pro): the joobq-pro engine conducts every run of a registered blueprint; these
calls start a run and talk to it. Each answers {:ok, answer} or {:error, %JoobQ.Error{}} (:pro_required
without a licence, a 404 :gateway error for an unknown run) and takes :name, the instance, in opts.
Calls are sent once: a :transport error MAY mean the gateway acted (give start/3 an :id to make a start
safe to send again).