HTTP Gun

CI http_gun on Hex Gleam

HTTP Gun is a Gleam HTTP client for Erlang/OTP applications. One client gives you a reusable connection pool, collected or streamed byte responses, explicit resource limits, and offline playback. Your application decides what a status or response body means.

Capabilities

When to use it

Use HTTP Gun for API calls in supervised Erlang applications, streamed reads of large responses, or tests with deterministic offline responses and recorded exchanges. It is a transport client: provider adapters still own authentication, status and content interpretation, retries, protocol framing such as SSE, and reconciliation of external effects.

Install

HTTP Gun requires Gleam 1.18 or newer on the Erlang target. Add it from Hex:

gleam add http_gun

Commit the application’s gleam.toml and manifest.toml to retain the resolved versions.

Send a request

This excerpt uses server, local_request, and local_config from the complete ordinary consumer. That consumer starts a local fixture and explicitly permits loopback access.

let req = local_request(server())
// The common path: start a client, send, read the collected response, stop.
let assert Ok(client) = http_gun.start(local_config())
let assert Ok(reply) = http_gun.send(client, req)
let assert 200 = reply.response.status
let assert <<"abc":utf8>> = reply.response.body
http_gun.stop(client)

send collects the response body up to its configured limit. Statuses such as 404 and 500 are still response data. For a streaming response, scope body cleanup with with_response and read chunks using body.next:

let assert Ok(3) = {
  use response <- http_gun.with_response(stream, req, fn(failure) { failure })
  count(response.body, 0)
}

The consumer source includes the count helper and runs this example against a local server.

Test with playback

A playback client answers from a script or a loaded cassette and never opens a connection. A request that does not match fails with PlaybackMismatch, and one after the last exchange with PlaybackExhausted. When the code under test handles those failures itself, ask the client before stopping it. This excerpt comes from the offline usage example.

// The code under test swallows the mismatch.
let _ = http_gun.send(client, stale)
let _ = http_gun.send(client, expected)

let assert Ok(testing.Verdict(
  mismatched: [testing.Mismatch(position: 0, expected: _, actual: missed)],
  exhausted: [],
  unused: [_second],
  dropped: 0,
)) = testing.verify(client)
let assert "/v2/orders" = missed.path
http_gun.stop(client)

A test that normalises volatile request values (a time, an id) can rewrite request bodies only, so a recorded answer is never edited, and can store only the request headers it names, plus content-type. cassette.redact applies a grown policy to a loaded cassette without recording again; the caller encodes the result and writes the file.

let policy =
  redaction.default()
  |> redaction.keeping_request_headers(["accept"])
  |> redaction.with_request_body(fn(body) {
    case body {
      <<"asked at ":utf8, _:bytes>> -> <<"asked at <time>":utf8>>
      other -> other
    }
  })
// The stored form a recording under `policy` writes. Encode it to clean
// an old cassette without recording again.
let assert [stored] = testing.exchanges(cassette.redact(old, policy))
let assert [#("accept", "application/json")] = testing.request(stored).headers
let assert <<"asked at <time>":utf8>> = testing.request(stored).body
// The answer is never rewritten.
let assert testing.Respond(reply, _) = testing.reply(stored)
let assert [<<"due 20/11 14:30":utf8>>] = reply.body
let cleaned = cassette.encode(cassette.redact(old, policy))

Runtime ownership

Each client has a pool process that admits requests and assigns connection capacity. Each response has a body owner that coordinates the HTTP exchange; only the process that opened a body may read it. Gun handles HTTP wire protocols. An optional recorder captures exchanges, and lifecycle events go to Sinal handlers.

flowchart LR
  caller[Calling process] -->|send / open / batch| pool[Client pool process]
  pool -->|admit and lease| body[Body owner]
  body -->|requests and cancellation| gun[Gun connections]
  gun -->|response events| body
  caller -->|next / close| body
  pool -. lifecycle events .-> sinal[Sinal handlers]
  body -. lifecycle events .-> sinal
  body -. optional capture .-> recorder[Recorder]

Operational limits

Examples and reference

The ordinary consumer runs the public API examples. See the async feed recipe for application owned jobs and sinks, and the mTLS consumer for client identity setup and rotation. The public API, design, and coverage map describe the package contracts. Benchmark notes report retained local workload measurements; they predate this checkout and make no performance promise.

The changelog records releases and additions to public error variants.

✨ Search Document