Cowboy — Small Fast HTTP Server for Erlang/OTP

Introduction

Cowboy is a production-grade HTTP server for the Erlang/OTP platform. It provides a small, focused implementation of HTTP/1.1, HTTP/2, HTTP/3, and WebSocket protocols with the concurrency guarantees of the BEAM virtual machine. Cowboy is the default web server behind frameworks like Phoenix (Elixir) and handles millions of concurrent connections in production deployments.

What Cowboy Does

• Handles HTTP/1.1, HTTP/2, and HTTP/3 requests with a unified handler interface across protocol versions
• Supports WebSocket connections with per-connection Erlang processes for natural concurrency modeling
• Implements streaming request and response bodies for handling large payloads without buffering
• Provides a routing DSL that maps URL patterns to handler modules with constraint-based path matching
• Leverages OTP supervision trees for automatic process restart and fault tolerance

Architecture Overview

Cowboy follows the Erlang/OTP architecture where each connection is handled by a dedicated lightweight process. The Ranch library manages TCP/TLS acceptor pools, while Cowboy itself handles HTTP parsing and dispatching. Incoming requests are routed through a dispatch table to handler modules, where each handler runs in its own process with isolated state. This model allows Cowboy to handle hundreds of thousands of simultaneous connections on a single node with predictable latency, since garbage collection is per-process.

Self-Hosting & Configuration

• Add Cowboy as a dependency via rebar3 or mix (for Elixir projects)
• Configure listeners with port, TLS certificates, and connection limits via Erlang terms
• Set up routing dispatch tables that map host and path patterns to handler modules
• Tune acceptor pool size and connection timeouts based on expected load
• Integrates with OTP releases for packaging as a standalone deployable application

Key Features

• Lightweight per-connection processes that enable millions of concurrent connections on the BEAM VM
• Full HTTP/2 support with server push, stream multiplexing, and header compression
• WebTransport support via HTTP/3 for low-latency bidirectional communication
• Middleware pipeline for request/response transformation before reaching handlers
• REST helper module (cowboy_rest) that implements content negotiation and HTTP semantics automatically

Comparison with Similar Tools

• Phoenix/Plug — Higher-level Elixir web framework that uses Cowboy as its HTTP layer; Cowboy is the server underneath
• Mochiweb — Older Erlang HTTP server; Cowboy offers HTTP/2, HTTP/3, and more active development
• Yaws — Feature-rich Erlang web server with built-in templating; Cowboy is more minimal and composable
• Nginx — C-based reverse proxy and server; Cowboy runs on the BEAM for native Erlang integration
• Actix Web — Rust actor-based web framework; Cowboy uses Erlang's native actor model with hot code reloading

FAQ

Q: Is Cowboy only for Erlang projects? A: Cowboy is written in Erlang but is commonly used through Elixir via the Phoenix framework or Plug. Any BEAM language can use it directly.

Q: How many concurrent connections can Cowboy handle? A: Cowboy can handle millions of concurrent connections on the BEAM VM, constrained primarily by available memory since each connection process uses roughly 2-4 KB.

Q: Does Cowboy support TLS? A: Yes. Cowboy supports TLS via Ranch and can be configured with certificate files, client certificate validation, and ALPN for HTTP/2.

Q: How does Cowboy compare to using Nginx in front of a BEAM application? A: For pure Erlang/Elixir stacks, running Cowboy directly often simplifies deployment. Nginx is added when you need static file serving, load balancing across multiple nodes, or termination for non-BEAM services.

Sources

• https://github.com/ninenines/cowboy
• https://ninenines.eu/docs/en/cowboy/2.12/guide/