LlmCall.HTTP (llm_call v0.1.0)

Copy Markdown View Source

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-2xx response 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

event()

@type event() ::
  {:status, non_neg_integer()}
  | {:headers, [{String.t(), String.t()}]}
  | {:data, binary()}

response()

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

Functions

build_url(base_url, path, query \\ nil)

@spec build_url(String.t() | URI.t(), String.t(), String.t() | nil) :: String.t()

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.

merge_headers(header_lists)

@spec merge_headers([[{String.t(), String.t()}]]) :: [{String.t(), String.t()}]

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.

request(request, opts \\ [])

@spec request(LlmCall.HTTP.Request.t(), keyword()) ::
  {:ok, response()} | {:error, term()}

Performs one request and returns the whole response.

retry_after_ms(headers)

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

stream(request, acc, fun, opts)

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

valid_headers?(headers)

@spec valid_headers?(term()) :: boolean()

Whether headers is a list of string {name, value} pairs (nil is allowed).