roadrunner_gleam

Run Gleam web apps on Roadrunner, the pure-Erlang HTTP/1.1, HTTP/2, HTTP/3 and WebSocket server.

Requirements

Requires OTP 27+ and Gleam 1.19+, with rebar3 installed to build Roadrunner.

🚧 Status

roadrunner_gleam is in 0.x. The core is functional and covered by tests, but the API may change between minor versions. Pin an exact version in your deps if you need stability across upgrades.

Installation

gleam add roadrunner_gleam

Usage

import gleam/erlang/process
import roadrunner_gleam
import roadrunner_gleam/request.{type Request}
import roadrunner_gleam/response.{type Response}

pub fn main() {
  let assert Ok(_) =
    roadrunner_gleam.new(handle)
    |> roadrunner_gleam.port(8080)
    |> roadrunner_gleam.start
  process.sleep_forever()
}

fn handle(request: Request) -> Response {
  case request.path_segments(request) {
    [] -> response.text("hello, roadrunner!")
    ["hello", name] -> response.text("hello, " <> name <> "!")
    _ -> response.new(404)
  }
}

$ curl localhost:8080/hello/gleam
hello, gleam!

To run the listener under a gleam/otp supervisor, add roadrunner_gleam.supervised(builder) as a child.

TLS, HTTP/2 and HTTP/3

roadrunner_gleam.new(handle)
|> roadrunner_gleam.port(8443)
|> roadrunner_gleam.tls(certfile: "cert.pem", keyfile: "key.pem")
|> roadrunner_gleam.http3
|> roadrunner_gleam.start

A TLS listener serves HTTP/1.1 and HTTP/2 on the TCP port. http3 also serves HTTP/3 over QUIC on the UDP port with the same number, or, with port 0, on a UDP port of its own that listener_quic_port returns.

Any other Roadrunner listener option, such as max_content_length or keep_alive_timeout, can be set with roadrunner_gleam.option.

What works

• Handlers are plain Gleam functions, the same on HTTP/1.1, HTTP/2 and HTTP/3
• Requests are read in place, at the same cost as an Erlang handler
• Request bodies read before the handler, or on demand in pieces so large uploads never sit in memory whole
• Responses: complete, chunked and files sent by the kernel
• content-length set for you on complete and file responses
• Response compression with gzip or deflate (roadrunner_gleam.compress)
• A heap floor, on by default: a connection keeps the heap its last request needed, so handlers that build sizeable responses, such as JSON, collect far less, and a WebSocket session does the same for the pushes it builds (roadrunner_gleam.heap_floor, websocket.heap_floor)
• Cookies, the client's address, the connection's peer and local address, and the client's TLS certificate
• request.from_http to test handlers without starting a listener
• WebSocket sessions over HTTP/1.1, with typed state, a Subject other processes can push through, and a Selector for anything else, such as monitors
• Responses that stay open and push data as messages arrive, such as server-sent events with a builder for them, on HTTP/1.1, HTTP/2 and HTTP/3
• Responses are gleam_http responses, so gleam/http/response's set_header, set_cookie, redirect and the rest work on them, and request.to_http gives a gleam_http request
• Start, stop and drain listeners, or run them under a gleam/otp supervisor

Sponsors

roadrunner_gleam is open source and maintained on personal time. If you or your company find it useful, consider sponsoring.

I also accept coffees ☕

License

Copyright (c) 2026 William Fank Thomé

roadrunner_gleam is open-source under the Apache 2.0 License on GitHub.

See LICENSE.md for more information.