# `JoobQ.Transport`
[🔗](https://github.com/azutoolkit/joobqui/tree/master/sdks/elixir/blob/main/lib/joobq/transport.ex#L2)

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

# `result`

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

# `encode`

```elixir
@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`

```elixir
@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`

```elixir
@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`

```elixir
@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`

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

---

*Consult [api-reference.md](api-reference.md) for complete listing*
