Nous.HTTP.Backend behaviour (nous v0.16.2)

View Source

Behaviour for non-streaming HTTP backends.

Implemented by Nous.HTTP.Backend.Req (default) and Nous.HTTP.Backend.Hackney. Selection is per-call via :backend, per-environment via NOUS_HTTP_BACKEND, or per-app via config :nous, :http_backend, MyBackend. See Nous.Providers.HTTP.post/4 for the resolution order and docs/benchmarks/http_backend.md for performance characteristics.

Custom backends just need to implement post/4 and return one of: {:ok, decoded_body} for 2xx, {:error, %{status: status, body: body, headers: headers}} for 4xx/5xx (headers as a list of {name, value} tuples — used by Nous.Errors.RetryInfo to extract Retry-After hints), or {:error, term()} for transport / decode failures.

Streaming requests do NOT go through this behaviour — those always use hackney's :async, :once mode for backpressure (see Nous.Providers.HTTP.stream/4).

Summary

Callbacks

post(url, body, headers, opts)

Issue a POST request with a JSON body and return the decoded JSON response.

Callbacks

post(url, body, headers, opts)

@callback post(
  url :: String.t(),
  body :: map(),
  headers :: [{String.t(), String.t()}],
  opts :: keyword()
) :: {:ok, map() | binary()} | {:error, term()}

Issue a POST request with a JSON body and return the decoded JSON response.

Options

  • :timeout — receive timeout in milliseconds (default: 60_000)

Backends MAY accept additional options; unknown options should be ignored.