Livery Documentation

Livery is a modern Erlang web framework that serves one handler set over HTTP/1.1, HTTP/2, and HTTP/3 from a single service runtime. The wire layer (h1, h2, quic, ws) lives in sibling libraries; Livery owns the developer surface: router, middleware, handlers, extractors, observability.

These docs follow the Diátaxis split: tutorials teach, how-to guides solve a specific task, concepts explain how things fit together, reference is the exact API.

Start here

Tutorials

Step-by-step, learning-oriented.

• Your first service
• Compose a middleware stack
• Stream a response
• Test your handlers
• Call another service
• Build a complete service

How-to guides

Task-oriented recipes. Each guide is a specific problem and its solution.

Reading requests

• Parse a JSON body
• Read query string parameters
• Read headers
• Extract a bearer token
• Verify opaque tokens with introspection
• Use signed session cookies
• Read a streaming request body

Writing responses

• Return a streaming response
• Return Server-Sent Events
• Return trailers
• Serve a file
• Send an empty or redirect response

Routing & middleware

• Mount a router on a service
• Write a custom middleware
• Cap request body size
• Add per-request deadlines
• Log every request
• Propagate request IDs
• Catch handler errors
• Cancel work when the client disconnects
• Generate OpenAPI docs and validate requests
• Serve MCP tools
• Serve WebTransport

Calling out

• Make outbound HTTP requests
• Load-balance outbound requests

Operations

• Shut down gracefully

Testing and migration

• Test handlers without a socket
• Migrate from Cowboy

Concepts

Explanation-oriented. Read these to understand why Livery is shaped the way it is.

• Architecture
• Request and response model
• The middleware pipeline
• Routing
• Request lifecycle
• Adapters
• Streaming and backpressure

For the long-form architecture write-up, see design.md.

Reference

Information-oriented. The exact API for each module is generated from source by ex_doc; browse the sidebar's "Modules" section, grouped as:

• Public API: livery
• Request and response: livery_req, livery_resp, livery_ext
• Routing and middleware: livery_router, livery_middleware
• Built-in middleware: livery_request_id, livery_body_limit, livery_timeout, livery_access_log
• Adapters: livery_adapter, livery_test_adapter
• Body reader: livery_body
• Runtime: livery_app, livery_sup, livery_req_proc, livery_req_sup

Project state

The developer surface, the H1/H2/H3 wire adapters, and livery:start_service/1 are all in place and exercised end-to-end (the parity SUITE diffs the shared handler set across every adapter). See design.md for the long-form architecture.