Lucerna.HTTP behaviour (Lucerna v0.0.1-alpha.0)

The transport seam. Any module implementing this behaviour can replace the bundled Finch adapter via the :http option — that is how tests inject a scripted fake and how exotic runtimes bring their own client.

Summary

Types

request()
response()

Callbacks

request(request, timeout_ms, adapter_opts)

Performs one HTTP request. adapter_opts is the second element of the configured {adapter, adapter_opts} tuple. Network-level failures return {:error, exception} — never raise.

Functions

header(map, key)

Case-insensitive response-header lookup.

with_retry(fun, opts \\ [])

Runs fun (which must return {:ok, response} | {:error, error}) up to :attempts times with jittered exponential backoff. Only network failures and 5xx are retried; any 4xx is a stable answer and returns immediately — Lucerna.AuthError for 401/403. Exhausted attempts return the last error. Mirrors the Ruby gem's HTTP.with_retry.

Types

request()

@type request() :: %{
  method: :get | :post,
  url: String.t(),
  headers: [{String.t(), String.t()}],
  body: iodata() | nil
}

response()

@type response() :: %{
  status: non_neg_integer(),
  headers: [{String.t(), String.t()}],
  body: binary()
}

Callbacks

request(request, timeout_ms, adapter_opts)

@callback request(request(), timeout_ms :: pos_integer(), adapter_opts :: term()) ::
  {:ok, response()} | {:error, Exception.t()}

Performs one HTTP request. adapter_opts is the second element of the configured {adapter, adapter_opts} tuple. Network-level failures return {:error, exception} — never raise.

Functions

header(map, key)

@spec header(response(), String.t()) :: String.t() | nil

Case-insensitive response-header lookup.

with_retry(fun, opts \\ [])

@spec with_retry(
  (-> {:ok, response()} | {:error, Exception.t()}),
  keyword()
) :: {:ok, response()} | {:error, Exception.t()}

Runs fun (which must return {:ok, response} | {:error, error}) up to :attempts times with jittered exponential backoff. Only network failures and 5xx are retried; any 4xx is a stable answer and returns immediately — Lucerna.AuthError for 401/403. Exhausted attempts return the last error. Mirrors the Ruby gem's HTTP.with_retry.