dream_http_client

Type-safe HTTP client for Gleam with streaming support.

A standalone HTTP/HTTPS client built on Erlang’s battle-tested httpc. Supports blocking requests, yielder streaming, and message-based streaming. Built with the same quality standards as Dream, but completely independent—use it in any Gleam project.

Why dream_http_client?
Installation
Quick Start
Execution Modes
Recording & Playback
API Reference
Examples

Why dream_http_client?

Feature	What you get
Three execution modes	Blocking, yielder streaming, message-based—choose what fits
OTP-first design	Message-based streams integrate with actors and selectors
Recording/playback	Record HTTP calls for tests, debug production, work offline
Type-safe	`Result` types force error handling—no silent failures
Battle-tested	Built on Erlang’s `httpc`—proven in production for decades
Framework-independent	Zero dependencies on Dream or other frameworks
Concurrent streams	Handle multiple HTTP streams in a single actor
Stream cancellation	Cancel in-flight requests cleanly
Builder pattern	Consistent, composable request configuration

Installation

gleam add dream_http_client

Quick Start

Make a simple HTTP request:

import dream_http_client/client
import gleam/http

pub fn fetch_data() {
  client.new
  |> client.method(http.Get)
  |> client.scheme(http.Https)
  |> client.host("api.example.com")
  |> client.path("/users/123")
  |> client.add_header("Authorization", "Bearer " <> token)
  |> client.send()
}

_{🧪 Tested source}

Execution Modes

dream_http_client provides three execution modes. Choose based on your use case:

1. Blocking - `send()`

Best for: JSON APIs, small responses

let result = client.new
  |> client.host("api.example.com")
  |> client.path("/users")
  |> client.send()

case result {
  Ok(body) -> decode_json(body)
  Error(msg) -> handle_error(msg)
}

_{🧪 Tested source}

2. Yielder Streaming - `stream_yielder()`

Best for: AI/LLM streaming, file downloads, sequential processing

import gleam/yielder

client.new
  |> client.host("api.openai.com")
  |> client.path("/v1/chat/completions")
  |> client.stream_yielder()
  |> yielder.each(fn(chunk_result) {
    case chunk_result {
      Ok(chunk) -> process_chunk(chunk)
      Error(reason) -> log_error(reason)
    }
  })

_{🧪 Tested source}

⚠️ Note: This blocks while waiting for chunks. Not suitable for OTP actors handling concurrent operations.

3. Process-Based Streaming - `start_stream()`

Best for: Background tasks, concurrent operations, cancellable streams

// Start stream with callbacks - returns immediately
let assert Ok(stream) = client.new
  |> client.host("api.openai.com")
  |> client.path("/v1/chat/completions")
  |> client.on_stream_chunk(fn(data) {
    case bit_array.to_string(data) {
      Ok(text) -> io.print(text)
      Error(_) -> Nil
    }
  })
  |> client.start_stream()

// Wait for completion if needed
client.await_stream(stream)

// Or cancel early
client.cancel_stream_handle(stream)

_{🧪 Tested source}

Choosing a Mode

Use Case	Mode	Why
JSON API calls	`send()`	Simple, complete response at once
Small file downloads	`send()`	Load entire file into memory
AI/LLM streaming (single request)	`stream_yielder()`	Sequential token processing
File downloads	`stream_yielder()`	Memory-efficient chunked processing
Background processing	`start_stream()`	Non-blocking, concurrent, cancellable
Long-lived connections	`start_stream()`	Can cancel mid-stream
Cancellable operations	`start_stream()`	Cancel via handle

Recording & Playback

Record HTTP requests/responses for testing, debugging, and offline development.

Quick Example

import dream_http_client/recorder
import dream_http_client/matching

// Record real requests
let assert Ok(rec) = recorder.start(
  recorder.Record(directory: "mocks/api"),
  matching.match_url_only(),
)

client.new
  |> client.host("api.example.com")
  |> client.recorder(rec)
  |> client.send()  // Saved immediately to disk

// Playback later (no network)
let assert Ok(playback) = recorder.start(
  recorder.Playback(directory: "mocks/api"),
  matching.match_url_only(),
)

client.new
  |> client.host("api.example.com")
  |> client.recorder(playback)
  |> client.send()  // Returns recorded response

_{🧪 Tested source}

Recording Modes

Record(directory) - Records real requests to disk immediately
Playback(directory) - Returns recorded responses (no network)
Passthrough - No recording/playback

Important: Recordings are saved immediately when captured. recorder.stop() is optional and only performs cleanup. This ensures recordings are never lost even if the process crashes.

Use Cases

Testing:

// test/api_test.gleam
let assert Ok(rec) = recorder.start(
  recorder.Playback(directory: "test/fixtures/api"),
  matching.match_url_only(),
)
// Tests run without external dependencies

_{🧪 Tested source}

Offline Development: Record API responses once, then work offline using recorded responses.

Debugging Production: Record problematic request/response pairs for investigation.

Request Matching

import dream_http_client/matching

// Default: Match on method + URL only
let config = matching.match_url_only()

// Custom matching
let config = matching.MatchingConfig(
  match_method: True,
  match_url: True,
  match_headers: False,  // Ignore auth tokens, timestamps
  match_body: False,     // Ignore request IDs in body
)

_{🧪 Tested source}

Recording Storage

Recordings are stored as individual files (one per request) with human-readable filenames:

mocks/api/GET_api.example.com_users_a3f5b2.json
mocks/api/POST_api.example.com_users_c7d8e9.json

Benefits:

O(1) write performance - No read-modify-write cycles
Concurrent tests work - No file contention between parallel tests
Easy inspection - Each recording is a separate, readable file
Version control friendly - Individual files show clear diffs

API Reference

Builder Pattern

client.new
|> client.method(http.Post)         // HTTP method
|> client.scheme(http.Https)        // HTTP or HTTPS
|> client.host("api.example.com")   // Hostname (required)
|> client.port(443)                 // Port (optional, defaults 80/443)
|> client.path("/api/users")        // Request path
|> client.query("page=1&limit=10")  // Query string
|> client.add_header("Content-Type", "application/json")
|> client.body(json_body)           // Request body
|> client.timeout(60_000)           // Timeout in ms (default: 30s)

_{🧪 Tested source}

Execution

Blocking:

send(req) -> Result(String, String) - Returns complete response body

Yielder Streaming:

stream_yielder(req) -> Yielder(Result(BytesTree, String)) - Returns yielder producing chunks

Message-Based Streaming:

stream_messages(req) -> Result(RequestId, String) - Starts stream, returns ID
select_stream_messages(selector, mapper) -> Selector(msg) - Integrates with OTP selectors
cancel_stream(request_id) - Cancels active stream

Types

RequestId - Opaque identifier for message-based streams

StreamMessage:

StreamStart(request_id, headers) - Stream started
Chunk(request_id, data) - Data chunk received
StreamEnd(request_id, headers) - Stream completed
StreamError(request_id, reason) - Stream failed
DecodeError(reason) - FFI corruption (report as bug)

Error Handling

All modes use Result types for explicit error handling:

case client.send(request) {
  Ok(body) -> process_response(body)
  Error(msg) -> {
    // Common errors:
    // - Connection refused
    // - DNS resolution failed
    // - Timeout
    log_error(msg)
  }
}

_{🧪 Tested source}

Examples

All examples are tested and verified. See test/snippets/ for complete, runnable code.

Basic requests:

Blocking request - Simple GET
POST with JSON - JSON body
Request builder - Full configuration
Timeout configuration - Custom timeouts

Streaming:

Yielder streaming - Sequential processing

Recording:

Record and playback - Testing without network

Design Principles

This module follows the same quality standards as Dream:

No nested cases - Clear, flat control flow throughout
No anonymous functions - All functions are named for clarity
Builder pattern - Consistent, composable request configuration
Type safety - Result types force error handling at compile time
OTP-first design - Message-based API designed for supervision trees
Comprehensive testing - Unit tests (no network) + integration tests (real HTTP)
Battle-tested foundation - Built on Erlang’s production-proven httpc

About Dream

This module was originally built for the Dream web toolkit, but it’s completely standalone and can be used in any Gleam project. It follows Dream’s design principles and will be maintained as part of the Dream ecosystem.

License

MIT — see LICENSE.md

_{Built in Gleam, on the BEAM, by the Dream Team ❤️}