HTTP transport, backed by Finch.
There is one transport. The pool is named LlmCall.Finch; the application
starts it unless that name is already taken, so a host can own it by starting
its pool first. Pass http_opts: [name: MyPool] to a provider or client to use
a pool from your own supervision tree.
request/2 and stream/4 forward exactly four transport options: :name
(the pool), plus Finch's :pool_timeout, :request_timeout, and
:pool_strategy. LlmCall.Provider rejects any other key, so a typo cannot be
dropped silently. The per-request read timeout is not one of them: it comes
from the request itself, which the client fills from its timeout: option.
Streaming events
stream/4 delivers, in order:
{:status, status}— before any body bytes, so a caller can stop on a non-2xxresponse instead of treating an error body as an empty stream;{:headers, headers};{:data, binary}— zero or more body chunks.
Returning {:halt, acc} from the callback stops the request and closes the
connection.
Summary
Functions
Joins a base URL, a request path, and an already-encoded query.
Merges header lists, keeping one value per name (case-insensitive).
Performs one request and returns the whole response.
Parses a Retry-After header into milliseconds.
Performs one request, delivering event()s to fun.
Whether headers is a list of string {name, value} pairs (nil is allowed).
Types
@type event() :: {:status, non_neg_integer()} | {:headers, [{String.t(), String.t()}]} | {:data, binary()}
@type response() :: %{ status: non_neg_integer(), headers: [{String.t(), String.t()}], body: binary() }
Functions
Joins a base URL, a request path, and an already-encoded query.
The base URL's path is kept, so a vendor prefix (https://…/openai) survives
and the path is appended to it; a trailing slash on either side never doubles.
The query is set on the URI struct rather than glued onto the string, which is
what keeps a ? in the base URL from ending up inside the path.
base_url may be a string or an already parsed %URI{}, which lets the
WebSocket handshake reuse it after changing the scheme.
Merges header lists, keeping one value per name (case-insensitive).
Later entries win, so a codec's protocol header overrides a caller's, and a caller's header overrides a provider default.
@spec request(LlmCall.HTTP.Request.t(), keyword()) :: {:ok, response()} | {:error, term()}
Performs one request and returns the whole response.
@spec retry_after_ms([{String.t(), String.t()}]) :: non_neg_integer() | nil
Parses a Retry-After header into milliseconds.
Accepts delta-seconds or an IMF-fixdate HTTP-date; returns nil when the
header is missing or malformed. Header names are matched case-insensitively.
@spec stream( LlmCall.HTTP.Request.t(), acc, (event(), acc -> {:cont, acc} | {:halt, acc}), keyword() ) :: {:ok, acc} | {:error, term()} when acc: term()
Performs one request, delivering event()s to fun.
acc is threaded through the callback; {:halt, acc} stops the request and
closes the connection. The last argument carries the transport options
described in the module documentation: :name, :pool_timeout,
:request_timeout, and :pool_strategy.
Whether headers is a list of string {name, value} pairs (nil is allowed).