API Reference joobq_ex v#0.8.0

Copy Markdown View Source

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).