A producer client for the JoobQ SDK gateway (/api/v1/sdk) of a self-hosted JoobQUI server.
JoobQUI version 0.8.0; an SDK talks to a server of its own version or later.
Start an instance in the application's supervision tree (options: JoobQ.Config):
children = [{JoobQ, url: "https://joobqui.example.com", token: System.fetch_env!("JOOBQ_SDK_TOKEN")}]Calls answer {:ok, answer} or {:error, %JoobQ.Error{}}; their ! variants answer the answer or raise the error.
A 426 (the gateway refuses this SDK's version) answers {:error, %JoobQ.SdkTooOldError{}} instead, and is never
sent again: an instance whose worker meets it logs the server's message and stops at once (no drain, no
deregistration) with the exit {:shutdown, %JoobQ.SdkTooOldError{}}, which its supervisor gets.
Summary
Functions
The child specification of an instance: {JoobQ, opts} in a supervisor (see JoobQ.Config).
Creates a JoobQ Pro batch of jobs with its callbacks (POST /sdk/batches, see JoobQ.Batches):
{:ok, %{"batch_id", "total", "jobs"}}. Sent once: a :transport error MAY mean the batch was created.
opts: the batch's and :name, the instance.
A workflow run (JoobQ Pro): JoobQ.Workflows.describe/2.
Enqueues a job of job_type on queue with POST /sdk/jobs, answering once the job is stored:
{:ok, %{"jid" => jid, "queue" => queue, "status" => status}}. opts are the job's (JoobQ.Job) and :name,
the instance (JoobQ by default). A :transport or :bad_response error MAY mean the job is stored (see
JoobQ.Error): give it a unique_key before sending it again.
enqueue/4, answering the stored job or raising JoobQ.Error.
enqueue_many/2 under the name Oban users know.
enqueue/4 without waiting: answers a Task whose Task.await/2 gives what enqueue/4 answers. A wrong option,
a payload Jason cannot encode (JoobQ.Error) or an instance that is not started raises here, before the task starts.
Enqueues jobs with POST /sdk/jobs/batch, 500 per call (see JoobQ.Job.batches/2 for a job's shapes), and
answers one %{"jid", "queue", "status"} per job, in order. opts: :name, and :context, the context of every
job without its own. The calls are made one after the other; when one fails its error is the answer, and the jobs
of the calls before it stay stored: they are the error's details.stored (the gateway's own details, if any, are
then details.gateway).
enqueue_many/2, answering the stored jobs or raising JoobQ.Error.
The progress of the batch id (GET /sdk/batches/:id, JoobQ Pro): {:ok, %{"status", "total", "pending", "succeeded", "failed", ...}}. An id that is not a UUID raises ArgumentError; an unknown one answers 404.
opts: :name, the instance.
Answers a workflow run's query (JoobQ Pro): JoobQ.Workflows.query/3.
Reserves a slot of the rate limit key, limit per period_ms (POST /sdk/rate-limit, JoobQ Pro; see
JoobQ.RateLimits): {:ok, %{"allowed" => boolean, "retry_after_ms" => ms}}. opts: :name, the instance.
Registers, or updates, the job schedule name (POST /sdk/schedules): {:ok, %{"id", "name", "kind", "created"}}.
opts are the schedule's (JoobQ.Schedules: :cron or :every, ...) and :name, the instance.
The SDK's version, the JoobQUI release it was generated from.
Sends a signal to a workflow run (JoobQ Pro): JoobQ.Workflows.signal/4.
Starts an instance outside a supervision tree (see JoobQ.Config).
Starts a workflow run (JoobQ Pro): JoobQ.Workflows.start/3.
Sends an update to a workflow run (JoobQ Pro): JoobQ.Workflows.update/4.
Sets and removes a workflow run's search attributes (JoobQ Pro): JoobQ.Workflows.upsert_attributes/2.
A workflow run's events (JoobQ Pro): JoobQ.Workflows.history/2.
A workflow run once closed (JoobQ Pro): JoobQ.Workflows.result/2.
Functions
@spec child_spec(keyword()) :: Supervisor.child_spec()
The child specification of an instance: {JoobQ, opts} in a supervisor (see JoobQ.Config).
@spec create_batch([tuple()], keyword()) :: {:ok, map()} | {:error, JoobQ.Error.t() | JoobQ.SdkTooOldError.t()}
Creates a JoobQ Pro batch of jobs with its callbacks (POST /sdk/batches, see JoobQ.Batches):
{:ok, %{"batch_id", "total", "jobs"}}. Sent once: a :transport error MAY mean the batch was created.
opts: the batch's and :name, the instance.
@spec describe_workflow(String.t(), keyword()) :: {:ok, map()} | {:error, JoobQ.Error.t() | JoobQ.SdkTooOldError.t()}
A workflow run (JoobQ Pro): JoobQ.Workflows.describe/2.
@spec enqueue(String.t(), String.t(), term(), keyword()) :: {:ok, map()} | {:error, JoobQ.Error.t() | JoobQ.SdkTooOldError.t()}
Enqueues a job of job_type on queue with POST /sdk/jobs, answering once the job is stored:
{:ok, %{"jid" => jid, "queue" => queue, "status" => status}}. opts are the job's (JoobQ.Job) and :name,
the instance (JoobQ by default). A :transport or :bad_response error MAY mean the job is stored (see
JoobQ.Error): give it a unique_key before sending it again.
enqueue/4, answering the stored job or raising JoobQ.Error.
@spec enqueue_all([tuple()], keyword()) :: {:ok, [map()]} | {:error, JoobQ.Error.t() | JoobQ.SdkTooOldError.t()}
enqueue_many/2 under the name Oban users know.
enqueue/4 without waiting: answers a Task whose Task.await/2 gives what enqueue/4 answers. A wrong option,
a payload Jason cannot encode (JoobQ.Error) or an instance that is not started raises here, before the task starts.
@spec enqueue_many([tuple()], keyword()) :: {:ok, [map()]} | {:error, JoobQ.Error.t() | JoobQ.SdkTooOldError.t()}
Enqueues jobs with POST /sdk/jobs/batch, 500 per call (see JoobQ.Job.batches/2 for a job's shapes), and
answers one %{"jid", "queue", "status"} per job, in order. opts: :name, and :context, the context of every
job without its own. The calls are made one after the other; when one fails its error is the answer, and the jobs
of the calls before it stay stored: they are the error's details.stored (the gateway's own details, if any, are
then details.gateway).
enqueue_many/2, answering the stored jobs or raising JoobQ.Error.
@spec get_batch(String.t(), keyword()) :: {:ok, map()} | {:error, JoobQ.Error.t() | JoobQ.SdkTooOldError.t()}
The progress of the batch id (GET /sdk/batches/:id, JoobQ Pro): {:ok, %{"status", "total", "pending", "succeeded", "failed", ...}}. An id that is not a UUID raises ArgumentError; an unknown one answers 404.
opts: :name, the instance.
@spec query_workflow(String.t(), String.t(), keyword()) :: {:ok, term()} | {:error, JoobQ.Error.t() | JoobQ.SdkTooOldError.t()}
Answers a workflow run's query (JoobQ Pro): JoobQ.Workflows.query/3.
@spec rate_limit(String.t(), pos_integer(), pos_integer(), keyword()) :: {:ok, map()} | {:error, JoobQ.Error.t() | JoobQ.SdkTooOldError.t()}
Reserves a slot of the rate limit key, limit per period_ms (POST /sdk/rate-limit, JoobQ Pro; see
JoobQ.RateLimits): {:ok, %{"allowed" => boolean, "retry_after_ms" => ms}}. opts: :name, the instance.
@spec register_schedule(String.t(), String.t(), String.t(), keyword()) :: {:ok, map()} | {:error, JoobQ.Error.t() | JoobQ.SdkTooOldError.t()}
Registers, or updates, the job schedule name (POST /sdk/schedules): {:ok, %{"id", "name", "kind", "created"}}.
opts are the schedule's (JoobQ.Schedules: :cron or :every, ...) and :name, the instance.
@spec sdk_version() :: String.t()
The SDK's version, the JoobQUI release it was generated from.
@spec signal_workflow(String.t(), String.t(), term(), keyword()) :: {:ok, map()} | {:error, JoobQ.Error.t() | JoobQ.SdkTooOldError.t()}
Sends a signal to a workflow run (JoobQ Pro): JoobQ.Workflows.signal/4.
@spec start_link(keyword()) :: Supervisor.on_start()
Starts an instance outside a supervision tree (see JoobQ.Config).
@spec start_workflow(String.t(), term(), keyword()) :: {:ok, map()} | {:error, JoobQ.Error.t() | JoobQ.SdkTooOldError.t()}
Starts a workflow run (JoobQ Pro): JoobQ.Workflows.start/3.
@spec update_workflow(String.t(), String.t(), term(), keyword()) :: {:ok, map()} | {:error, JoobQ.Error.t() | JoobQ.SdkTooOldError.t()}
Sends an update to a workflow run (JoobQ Pro): JoobQ.Workflows.update/4.
@spec upsert_workflow_attributes(String.t(), keyword()) :: {:ok, map()} | {:error, JoobQ.Error.t() | JoobQ.SdkTooOldError.t()}
Sets and removes a workflow run's search attributes (JoobQ Pro): JoobQ.Workflows.upsert_attributes/2.
@spec workflow_history(String.t(), keyword()) :: {:ok, [map()]} | {:error, JoobQ.Error.t() | JoobQ.SdkTooOldError.t()}
A workflow run's events (JoobQ Pro): JoobQ.Workflows.history/2.
@spec workflow_result(String.t(), keyword()) :: {:ok, map()} | {:error, JoobQ.Error.t() | JoobQ.SdkTooOldError.t()}
A workflow run once closed (JoobQ Pro): JoobQ.Workflows.result/2.