pig_transport

Cancellable HTTP transport primitives for the pig agent ecosystem.

pig_transport provides a small transport boundary shared by pig and pig_proxy. It supports buffered requests and incremental response streaming without tying callers to a provider protocol.

Installation

Add the package to a Gleam project:

gleam add pig_transport

pig_transport targets Erlang and includes a production adapter backed by Hackney.

Buffered requests

import pig_transport
import pig_transport/hackney

pub fn fetch() {
  let request =
    pig_transport.Request(
      method: "GET",
      url: "https://example.com",
      headers: [],
      body: "",
      timeout_ms: 30_000,
    )

  pig_transport.sync(hackney.transport(), request)
}

A buffered request returns either a complete Response or a TransportError.

Streaming lifecycle

Streaming uses an opaque StreamHandle and ordered lifecycle events:

1. open returns immediately without performing upstream I/O on the caller.
2. Committed, Rejected, or Failed reports the response-head decision.
3. After Committed, call start with a sink to receive body chunks.
4. The sink receives ordered Chunk events followed by exactly one terminal event: Done, StreamError, or Cancelled.

Non-2xx responses are buffered and delivered as Rejected, so callers never observe a partially committed error response.

Call cancel at any point to stop upstream work. Cancellation is idempotent, and the relay monitors its owner and sink so abandoned streams do not leave the underlying connection running.

Custom adapters

A transport contains two functions:

pub type Transport {
  Transport(
    sync: fn(Request) -> Response,
    stream: fn(Request, process.Subject(SourceEvent)) -> Nil,
  )
}

Custom streaming adapters send SourceHead, SourceChunk, and one source terminal event to the relay. Adapters that can close their connection cleanly can first send SourceReady with a cancellation subject.

Development

From this package directory:

gleam build --warnings-as-errors
gleam test

License

Apache-2.0