JoobQ (joobq_ex v0.8.0)

Copy Markdown View Source

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.

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

Starts an instance outside a supervision tree (see JoobQ.Config).

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

child_spec(opts)

@spec child_spec(keyword()) :: Supervisor.child_spec()

The child specification of an instance: {JoobQ, opts} in a supervisor (see JoobQ.Config).

create_batch(jobs, opts \\ [])

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

describe_workflow(id, opts \\ [])

@spec describe_workflow(String.t(), keyword()) ::
  {:ok, map()} | {:error, JoobQ.Error.t() | JoobQ.SdkTooOldError.t()}

A workflow run (JoobQ Pro): JoobQ.Workflows.describe/2.

enqueue(queue, job_type, payload \\ %{}, opts \\ [])

@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!(queue, job_type, payload \\ %{}, opts \\ [])

@spec enqueue!(String.t(), String.t(), term(), keyword()) :: map()

enqueue/4, answering the stored job or raising JoobQ.Error.

enqueue_all(jobs, opts \\ [])

@spec enqueue_all([tuple()], keyword()) ::
  {:ok, [map()]} | {:error, JoobQ.Error.t() | JoobQ.SdkTooOldError.t()}

enqueue_many/2 under the name Oban users know.

enqueue_async(queue, job_type, payload \\ %{}, opts \\ [])

@spec enqueue_async(String.t(), String.t(), term(), keyword()) :: Task.t()

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.

enqueue_many(jobs, opts \\ [])

@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!(jobs, opts \\ [])

@spec enqueue_many!([tuple()], keyword()) :: [map()]

enqueue_many/2, answering the stored jobs or raising JoobQ.Error.

get_batch(id, opts \\ [])

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

query_workflow(id, query, opts \\ [])

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

rate_limit(key, limit, period_ms, opts \\ [])

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

register_schedule(name, queue, job_type, opts \\ [])

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

sdk_version()

@spec sdk_version() :: String.t()

The SDK's version, the JoobQUI release it was generated from.

signal_workflow(id, signal, payload \\ nil, opts \\ [])

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

start_link(opts)

@spec start_link(keyword()) :: Supervisor.on_start()

Starts an instance outside a supervision tree (see JoobQ.Config).

start_workflow(name, input, opts \\ [])

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

update_workflow(id, update, input \\ nil, opts \\ [])

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

upsert_workflow_attributes(id, opts)

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

workflow_history(id, opts \\ [])

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

workflow_result(id, opts \\ [])

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