# `LlmCall.HTTP`
[🔗](https://github.com/gilbertwong96/llm_call/blob/main/lib/llm_call/http.ex#L1)

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.

# `event`

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

# `response`

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

# `build_url`

```elixir
@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`

```elixir
@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`

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

Performs one request and returns the whole response.

# `retry_after_ms`

```elixir
@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`

```elixir
@spec stream(
  LlmCall.HTTP.Request.t(),
  acc,
  (event(), acc -&gt; {: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?`

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

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

---

*Consult [api-reference.md](api-reference.md) for complete listing*
