gluegun - v1.0.0-rc.1

gluegun/client

High-level HTTP helpers for existing Gun connections.

These helpers collect a full HTTP/1.1 or HTTP/2 response — status, headers, body, trailers, and any informational 1xx responses — into a response.Response(BitArray). Its response field is a standard gleam/http/response.Response(BitArray). The body is held fully in memory; use the lower-level gluegun/request and gluegun/message APIs for streaming or very large responses.

Protocol messages for server push, upgrades, and WebSockets are rejected with InvalidMessage. Use the lower-level gluegun/message API for those flows.

If collection fails, these helpers attempt to cancel the failed stream and drain its queued messages, then return the original error. They also cancel and drain each promised stream found in a rejected or queued push. They keep other streams and the connection open. Cancellation is asynchronous: messages in transit can arrive after the drain. For strict mailbox isolation, use the low-level API in a separate receiving process.

Types

Request

opaque </>

A connection-bound request: method, path, headers, body, and total timeout.

The connection supplied to send determines the scheme, host, and port. Supply a request target such as /items?page=2, not a full URL. Gluegun sends the path and query as supplied; it does not percent-encode them. The body must contain whole bytes and need not be UTF-8.

This custom type avoids duplicating the connection’s destination fields. It does not accept or convert standard gleam/http/request.Request values.

pub opaque type Request

Values

add_headers

</> 
pub fn add_headers(
  request: Request,
  headers headers: List(#(String, String)),
) -> Request

Append request headers.

delete

</> 
pub fn delete(
  connection: connection.Connection,
  path path: String,
  headers headers: List(#(String, String)),
  timeout timeout: connection.Timeout,
) -> Result(response.Response(BitArray), error.GluegunError)

Send DELETE on an open connection and collect the full response.

get

</> 
pub fn get(
  connection: connection.Connection,
  path path: String,
  headers headers: List(#(String, String)),
  timeout timeout: connection.Timeout,
) -> Result(response.Response(BitArray), error.GluegunError)

Send GET on an open connection and collect the full response.

</> 
pub fn head(
  connection: connection.Connection,
  path path: String,
  headers headers: List(#(String, String)),
  timeout timeout: connection.Timeout,
) -> Result(response.Response(BitArray), error.GluegunError)

Send HEAD on an open connection and collect the full response.

new

</> 
pub fn new(method: http.Method, path: String) -> Request

Start a new Request builder with the given method and path.

options

</> 
pub fn options(
  connection: connection.Connection,
  path path: String,
  headers headers: List(#(String, String)),
  timeout timeout: connection.Timeout,
) -> Result(response.Response(BitArray), error.GluegunError)

Send OPTIONS on an open connection and collect the full response.

patch

</> 
pub fn patch(
  connection: connection.Connection,
  path path: String,
  headers headers: List(#(String, String)),
  body body: BitArray,
  timeout timeout: connection.Timeout,
) -> Result(response.Response(BitArray), error.GluegunError)

Send PATCH on an open connection and collect the full response.

post

</> 
pub fn post(
  connection: connection.Connection,
  path path: String,
  headers headers: List(#(String, String)),
  body body: BitArray,
  timeout timeout: connection.Timeout,
) -> Result(response.Response(BitArray), error.GluegunError)

Send POST on an open connection and collect the full response.

put

</> 
pub fn put(
  connection: connection.Connection,
  path path: String,
  headers headers: List(#(String, String)),
  body body: BitArray,
  timeout timeout: connection.Timeout,
) -> Result(response.Response(BitArray), error.GluegunError)

Send PUT on an open connection and collect the full response.

send

</> 
pub fn send(
  request: Request,
  connection connection: connection.Connection,
) -> Result(response.Response(BitArray), error.GluegunError)

Send a built Request on an open connection and collect the response.

with_body

</> 
pub fn with_body(
  request: Request,
  body body: BitArray,
) -> Request

Replace the request body.

with_header

</> 
pub fn with_header(
  request: Request,
  name name: String,
  value value: String,
) -> Request

Append a single request header.

with_headers

</> 
pub fn with_headers(
  request: Request,
  headers headers: List(#(String, String)),
) -> Request

Replace request headers.

with_timeout

</> 
pub fn with_timeout(
  request: Request,
  timeout timeout: connection.Timeout,
) -> Request

Set the total request budget, including dispatch and all response messages.

Informational responses and body chunks do not restart the budget. Infinity has no limit. Collection still keeps the complete body in memory.

✨ Search Document