gluegun/request

Low-level HTTP request and stream operations.

Use this module when you need Gun stream references, chunked request bodies, flow-control updates, cancellation, or direct access to asynchronous Gun messages. For simple full-body responses, prefer gluegun/client.

Types

Method

HTTP request method constructors.

Use canonical constructors such as Get, Post, and Put, or Custom for extension methods.

pub type Method {
  Get
  Head
  Post
  Put
  Patch
  Delete
  Options
  Trace
  Connect
  Custom(String)
}

Constructors

Get

HTTP GET. Safe and idempotent.

Head

HTTP HEAD. Same as Get but the response has no body.

Post

HTTP POST. Create or submit data; not idempotent.

Put

HTTP PUT. Replace the target resource; idempotent.

Patch

HTTP PATCH. Apply a partial modification.

Delete

HTTP DELETE. Remove the target resource; idempotent.

Options

HTTP OPTIONS. Describe communication options for the target.

Trace

HTTP TRACE. Loop-back diagnostics; rarely used.

Connect

HTTP CONNECT. Establish a tunnel through a proxy.

Custom(String)

An extension or non-standard method. The wrapped string is sent verbatim.

RequestOptions

Request options passed through the low-level request API.

Build with options() then chain with_headers or add_headers for option-level headers. Use with_initial_flow for finite response credit.

pub type RequestOptions

Type aliases

Header

HTTP header represented as #(name, value).

pub type Header = #(String, String)

Stream

Opaque handle for a Gun request stream.

pub type Stream = internal.Stream

Functions

add_headers

Add option-level headers that are appended to per-call headers.

pub fn add_headers(
  RequestOptions,
  headers: List(#(String, String))
) -> RequestOptions

cancel

Cancel an in-flight request stream.

Sends a reset/cancel to Gun. The connection remains usable for new streams. Pending response messages for the cancelled stream may still arrive briefly and should be drained.

pub fn cancel(
  internal.Connection,
  internal.Stream
) -> Result(Nil, error.GluegunError)

data

Send a chunk of request body data on an open stream.

Pass fin.NoFin for intermediate chunks and fin.Fin for the last chunk. After sending the final chunk the request body is closed, but the stream remains open for response messages.

Chunks must contain whole bytes; empty chunks are valid. A non-byte-aligned BitArray returns InvalidOptions without sending data or closing the request body, even when fin.Fin is supplied.

pub fn data(
  internal.Connection,
  internal.Stream,
  fin.Fin,
  BitArray
) -> Result(Nil, error.GluegunError)

flush

Discard buffered Gun messages currently queued for the calling process.

Useful after cancel or when recovering from an aborted flow. Returns Ok(Nil) even when no messages were buffered. It does not prevent late arrivals. Use connection.terminate to stop the sender, wait for exit, and flush this caller's connection messages.

pub fn flush(internal.Connection) -> Result(Nil, error.GluegunError)

method_to_string

Convert a method constructor to its HTTP method string.

pub fn method_to_string(Method) -> String

options

Construct default request options.

pub fn options() -> RequestOptions

request

Send a low-level HTTP request on an open Gun connection.

Returns a stream reference; response messages are delivered asynchronously to the calling process (unless Gun options redirect replies). Use gluegun/message.await / await_body to consume them, or use gluegun/client helpers to collect a regular response.

The method, path, and headers are validated before crossing to Gun: the method and path must be non-empty and must not contain a control byte, space, or DEL (including CR/LF); header names must be valid HTTP tokens; header values must not contain a control byte (other than HTAB) or DEL; and headers cannot include a caller-supplied Transfer-Encoding or a duplicate/malformed Content-Length. Invalid input returns InvalidOptions instead of reaching Gun.

The body must contain whole bytes. A non-byte-aligned BitArray returns InvalidOptions before Gun receives the request. Empty bodies are valid.

Errors: ConnectionDown, StreamError, InvalidOptions.

pub fn request(
  internal.Connection,
  Method,
  String,
  List(#(String, String)),
  BitArray,
  RequestOptions
) -> Result(internal.Stream, error.GluegunError)

start_stream

Start a low-level HTTP request whose body will be streamed in chunks.

Send zero or more body chunks with data(..., fin.NoFin, ...), then terminate the request with a final data(..., fin.Fin, ...) (which may carry an empty BitArray if there is no trailing payload). The stream remains open for response messages either way.

Gun response messages go to the calling process. with_initial_flow sets response credit before Gun starts the stream.

The method, path, and headers are validated the same way as request; see its documentation for the rejected shapes.

Errors: ConnectionDown, StreamError, InvalidOptions.

pub fn start_stream(
  internal.Connection,
  Method,
  String,
  List(#(String, String)),
  RequestOptions
) -> Result(internal.Stream, error.GluegunError)

update_flow

Update HTTP/1.1 or HTTP/2 stream flow control by the given increment.

The increment must be positive. Gun rejects non-positive flow-control increments, so this function validates the value before crossing the FFI boundary and returns InvalidOptions for zero or negative increments. The unit is data messages for both HTTP/1.1 and HTTP/2, not bytes. Finite credit pauses socket reads in HTTP/1.1 and stream window updates in HTTP/2. It does not bound bytes in a message or data already buffered.

pub fn update_flow(
  internal.Connection,
  internal.Stream,
  Int
) -> Result(Nil, error.GluegunError)

with_headers

Replace option-level headers.

pub fn with_headers(
  RequestOptions,
  headers: List(#(String, String))
) -> RequestOptions

with_initial_flow

Set finite initial response credit in data messages, not bytes.

Credit must be positive. One permits a data message before update_flow. Headers do not consume credit. Gun can parse several HTTP chunks or HTTP/2 frames from one socket read before it pauses, so credit is not a strict mailbox-message or allocation limit. Check each chunk's byte size before retaining it. With no setting, Gun keeps its unlimited default. Use message.await and replenish credit yourself. Full-body collectors such as message.await_body and client.send do not replenish it.

pub fn with_initial_flow(
  RequestOptions,
  credit: Int
) -> Result(RequestOptions, error.GluegunError)