JoobQ.Transport (joobq_ex v0.8.0)

Copy Markdown View Source

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 call is made once and never retried, not on a 5xx and not on a kept-alive connection found closed: the gateway can have stored the job before the connection broke, and it does not deduplicate by jid. So a :transport or :bad_response error MAY mean the job is stored; a job with a unique_key can be sent again safely. The pool closes connections idle for 5 seconds (JoobQ.Supervisor), below the usual proxy keep-alive limits, so a call rarely meets a stale one. :request_timeout (JoobQ.Config) bounds the whole answer.

Every call is a :telemetry span [:joobq, :request] (:start, :stop, :exception) with the metadata %{name: name, method: method, path: path}, and :status on :stop (nil when there was no answer); an :exception adds kind and error_class only (JoobQ.Telemetry).

Summary

Functions

body as JSON (nil stays nil), or an :invalid error when Jason cannot encode it (a tuple, a pid, ...).

The status (nil without an answer) and the result of what Finch answered; nothing here sends again.

Sends body (a term Jason encodes, or nil for no body) and answers the decoded JSON answer. opts: :timeout, the milliseconds this call may take (:request_timeout of JoobQ.Config by default), and :route, the path the telemetry metadata names (path by default; a path that holds a lease token passes its pattern).

The result for an answer with status and the raw body the gateway sent; a 426 is a JoobQ.SdkTooOldError, whatever its body.

Sends a body encode/1 gave; raises ArgumentError when the instance name is not started.

Types

result()

@type result() :: {:ok, term()} | {:error, JoobQ.Error.t() | JoobQ.SdkTooOldError.t()}

Functions

encode(body)

@spec encode(term()) :: {:ok, iodata() | nil} | {:error, JoobQ.Error.t()}

body as JSON (nil stays nil), or an :invalid error when Jason cannot encode it (a tuple, a pid, ...).

outcome(arg)

@spec outcome({:ok, Finch.Response.t()} | {:error, term()}) ::
  {pos_integer() | nil, result()}

The status (nil without an answer) and the result of what Finch answered; nothing here sends again.

request(name, method, path, body \\ nil, opts \\ [])

@spec request(atom(), :get | :post, String.t(), term(), keyword()) :: result()

Sends body (a term Jason encodes, or nil for no body) and answers the decoded JSON answer. opts: :timeout, the milliseconds this call may take (:request_timeout of JoobQ.Config by default), and :route, the path the telemetry metadata names (path by default; a path that holds a lease token passes its pattern).

result(status, body)

@spec result(pos_integer(), binary()) :: result()

The result for an answer with status and the raw body the gateway sent; a 426 is a JoobQ.SdkTooOldError, whatever its body.

send_encoded(name, method, path, encoded, opts \\ [])

@spec send_encoded(atom(), :get | :post, String.t(), iodata() | nil, keyword()) ::
  result()

Sends a body encode/1 gave; raises ArgumentError when the instance name is not started.