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
Request options passed through the low-level request API.
Build with options() and with_initial_flow for finite response credit.
Pass request headers directly to request or start_stream.
pub opaque type RequestOptionsValues
pub fn cancel(
connection: connection.Connection,
stream: Stream,
) -> Result(Nil, error.GluegunError)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.
Exception: Gun can leave HTTP/1.1 reads paused after finite flow credit is exhausted. Terminate and replace that connection after cancellation; do not reuse it. This also discards its other requests. See issue #78.
pub fn data(
connection: connection.Connection,
stream: Stream,
fin: fin.Fin,
data: BitArray,
) -> Result(Nil, error.GluegunError)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 flush(
connection: connection.Connection,
) -> Result(Nil, error.GluegunError)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 request(
connection: connection.Connection,
method: http.Method,
path: String,
headers: List(#(String, String)),
body: BitArray,
options: RequestOptions,
) -> Result(Stream, error.GluegunError)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); original header names must be valid ASCII
HTTP tokens before they are lowercased;
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 start_stream(
connection: connection.Connection,
method: http.Method,
path: String,
headers: List(#(String, String)),
options: RequestOptions,
) -> Result(Stream, error.GluegunError)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.
Content-Length is not supported on streamed uploads. It is rejected
before sending headers because supported Gun versions can crash on
fixed-length chunk sequences. Use chunked uploads or request instead.
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 update_flow(
connection: connection.Connection,
stream: Stream,
increment: Int,
) -> Result(Nil, error.GluegunError)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 with_initial_flow(
options: RequestOptions,
credit credit: Int,
) -> Result(RequestOptions, error.GluegunError)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.