roadrunner_gleam/request

The request a handler receives.

A Request is roadrunner’s own request, so reading it costs the same as in an Erlang handler: nothing is copied or converted until you ask for a value. Use to_http when you need a gleam/http request, for example to hand it to a library built on gleam_http.

Types

Chunk

</>

A piece of the body. Read the next one from next.

pub type Chunk {
  More(data: BitArray, next: Request)
  Last(data: BitArray, next: Request)
}

Constructors

```
More(data: BitArray, next: Request)
```
More of the body follows.
```
Last(data: BitArray, next: Request)
```
The last piece: the body has been read.

ConnectionInfo

</>

An address and port at one end of the connection.

pub type ConnectionInfo {
  ConnectionInfo(ip_address: IpAddress, port: Int)
}

Constructors

ConnectionInfo(ip_address: IpAddress, port: Int)

HttpVersion

</>

The HTTP version the request came over.

pub type HttpVersion {
  Http10
  Http11
  Http2
  Http3
}

Constructors

```
Http10
```
```
Http11
```
```
Http2
```
```
Http3
```

IpAddress

</>

An IP address.

pub type IpAddress {
  IpV4(Int, Int, Int, Int)
  IpV6(Int, Int, Int, Int, Int, Int, Int, Int)
}

Constructors

```
IpV4(Int, Int, Int, Int)
```

IpV6(Int, Int, Int, Int, Int, Int, Int, Int)

ReadError

</>

Why reading the body failed.

pub type ReadError {
  BodyTooLarge
  ReadFailed(String)
}

Constructors

```
BodyTooLarge
```
The body is larger than the listener’s max_content_length.
```
ReadFailed(String)
```
The client went away or sent a malformed body.

Request

</>

An HTTP request served by roadrunner, over HTTP/1.1, HTTP/2 or HTTP/3.

pub type Request

Values

body

</>

pub fn body(request: Request) -> BitArray

The request body. Roadrunner reads it before calling the handler, up to the listener’s max_content_length. On a listener that reads bodies on demand (roadrunner_gleam.read_body_on_demand) it is empty: read the body with read_body or read_chunk instead.

client_ip

</>

pub fn client_ip(request: Request) -> Result(IpAddress, Nil)

The client’s IP address. Behind trusted proxies configured with the listener’s real_ip option, this is the address they forwarded; otherwise it is the peer’s.

cookies

</>

pub fn cookies(request: Request) -> List(#(String, String))

The cookies the client sent, in order. A cookie whose name or value is not valid UTF-8 is left out. Set cookies with gleam/http/response.set_cookie.

from_http

</>

pub fn from_http(request: request.Request(BitArray)) -> Request

Build a request from a gleam/http request, to test a handler without starting a listener. The request comes over HTTP/1.1, with the body already read. It has no peer, client address or request id.

</>

pub fn header(
  request: Request,
  name: String,
) -> Result(String, Nil)

The first value of a header. The name is matched without regard to case. Fails when the header is missing, or when its value is not valid UTF-8: read that one with header_bits.

header_bits

</>

pub fn header_bits(
  request: Request,
  name: String,
) -> Result(BitArray, Nil)

The first value of a header as raw bytes, whatever they are. The name is matched without regard to case.

headers

</>

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

All request headers, in order, with lowercase names. HTTP lets a value hold bytes that are not UTF-8; such a header is left out here. Read it with header_bits.

http_version

</>

pub fn http_version(request: Request) -> HttpVersion

The HTTP version the request came over.

ip_address_to_string

</>

pub fn ip_address_to_string(ip_address: IpAddress) -> String

The address in its usual text form, such as 127.0.0.1 or ::1.

local_address

</>

pub fn local_address(
  request: Request,
) -> Result(ConnectionInfo, Nil)

The address and port of this server that the connection reached.

method

</>

pub fn method(request: Request) -> http.Method

The request method.

path

</>

pub fn path(request: Request) -> String

The request path, without the query string.

path_segments

</>

pub fn path_segments(request: Request) -> List(String)

The path split into its segments, handy for routing with pattern matching: /users/42 gives ["users", "42"]. The segments are not percent-decoded: decode one with uri.percent_decode when it may hold escapes, such as caf%C3%A9.

peer

</>

pub fn peer(request: Request) -> Result(ConnectionInfo, Nil)

The address and port the connection comes from: the client, or the last proxy in front of it.

peer_certificate

</>

pub fn peer_certificate(
  request: Request,
) -> Result(BitArray, Nil)

The certificate the client sent over TLS, DER-encoded. Fails on plain connections and when the client sent none.

query

</>

pub fn query(request: Request) -> String

The raw query string, without the ?. Empty when there is none.

query_params

</>

pub fn query_params(
  request: Request,
) -> Result(List(#(String, String)), Nil)

The decoded query parameters, in order. A key with no = gets an empty value. Fails when a decoded key or value is not valid UTF-8, as gleam/http/request.get_query does.

read_body

</>

pub fn read_body(
  request: Request,
) -> Result(#(BitArray, Request), ReadError)

Read the rest of the body. Returns the request to use after the read. On a listener that reads bodies before the handler, this is the body already read.

read_chunk

</>

pub fn read_chunk(
  request: Request,
  max_bytes: Int,
) -> Result(Chunk, ReadError)

Read the next piece of the body, at most max_bytes long, so a large upload never sits in memory whole. Bodies sent with chunked encoding are read across chunk boundaries the same way, and a body roadrunner already read is cut into pieces of the same size. A max_bytes below 1 reads 1 byte. After Last, reading again gives an empty Last. Read only in the process that runs the handler.

request_id

</>

pub fn request_id(request: Request) -> Result(String, Nil)

The id roadrunner gives each request, also set in the logger metadata.

scheme

</>

pub fn scheme(request: Request) -> http.Scheme

Http on a plain listener, Https on a TLS one.

to_http

</>

pub fn to_http(request: Request) -> request.Request(BitArray)

Build a gleam/http request with the body as a BitArray. On a listener that reads bodies on demand, the body is what has been read so far: read it first with read_body and convert the request it returns.