Livery Documentation

Livery is an Erlang web framework that serves one set of handlers over HTTP/1.1, HTTP/2, and HTTP/3 from a single service. The protocols themselves (h1, h2, quic, ws) live in separate libraries; Livery is the part you write code against: 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, to learn Livery.

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

How-to guides

Recipes. Each guide takes one task and shows how to do it.

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
• Send Early Hints
• Serve a file
• Send an empty or redirect response

Routing & middleware

• Mount a router on a service
• Handle QUERY requests
• 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 A2A agents
• Serve WebTransport

Calling out

• Make outbound HTTP requests
• Load-balance outbound requests
• Use a cookie jar

Operations

• Shut down gracefully

Testing and migration

• Test handlers without a socket
• Migrate from Cowboy

Concepts

Explanations. Read these to understand why Livery works the way it does.

• 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

For looking things up. ex_doc generates the exact API of each module from the source; browse the "Modules" section of the sidebar, 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

Ecosystem

Companion libraries built on Livery, each in its own repo:

• livery_grpc: gRPC server and client on top of Livery's HTTP/2 support. All four call types, deadlines, gRPC-Web, server reflection, and the standard health service.
• livery_s3: S3-compatible object storage client on the Livery HTTP client. AWS SigV4 signing, multipart uploads, presigned URLs; works with AWS S3, Garage, MinIO, Ceph, and Wasabi.
• livery_stripe: Stripe API client on the Livery HTTP client. Customers, subscriptions, Checkout, the Billing Portal, and webhook verification.

Project state

The API, the H1, H2 and H3 adapters, and livery:start_service/1 are all in place and tested end to end (the parity suite runs the same handlers through every adapter and compares what comes back). See design.md for the long-form architecture.