Nombaone.Transport behaviour (Nomba One v0.1.0)

View Source

The pluggable HTTP back-end.

The SDK owns the retry, idempotency, and envelope logic; a transport only performs one HTTP round-trip. The default is Nombaone.Transport.HTTPC (Erlang's :httpc, zero extra dependencies). Swap in your own — a Finch or Req adapter, or a recording double for tests — by implementing this behaviour and passing it to Nombaone.new/2:

Nombaone.new(key, transport: MyTransport, transport_options: opts)

Your request/2 receives the fully-built request (absolute URL, all headers, encoded body, per-attempt timeout) and the transport_options term from the client. Return {:ok, response} for any completed HTTP exchange (including 4xx/5xx — the engine interprets the status), or {:error, failure} when the request never completed.

Summary

Types

failure()

A request that never completed. :timeout means the attempt exceeded its budget (retryable); :connection is any other transport failure (retryable).

method()

The HTTP method, lowercased.

request()

A fully-built request. body is nil for methods without one.

response()

A completed HTTP response. status may be any code, including 4xx/5xx.

Callbacks

request(request, transport_options)

Perform one HTTP round-trip.

Types

failure()

@type failure() :: {:timeout, term()} | {:connection, term()}

A request that never completed. :timeout means the attempt exceeded its budget (retryable); :connection is any other transport failure (retryable).

method()

@type method() :: :get | :post | :patch | :put | :delete

The HTTP method, lowercased.

request()

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

A fully-built request. body is nil for methods without one.

response()

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

A completed HTTP response. status may be any code, including 4xx/5xx.

Callbacks

request(request, transport_options)

@callback request(request(), transport_options :: term()) ::
  {:ok, response()} | {:error, failure()}

Perform one HTTP round-trip.