Bandit is an HTTP server for Plug and WebSock apps.
Bandit is written entirely in Elixir and is built atop Thousand Island. It can serve HTTP/1.x, HTTP/2 and WebSocket clients over both HTTP and HTTPS. It is written with correctness, clarity & performance as fundamental goals.
In ongoing automated performance tests, Bandit's HTTP/1.x engine is up to 4x faster than Cowboy depending on the number of concurrent requests. When comparing HTTP/2 performance, Bandit is up to 1.5x faster than Cowboy. This is possible because Bandit has been built from the ground up for use with Plug applications; this focus pays dividends in both performance and also in the approachability of the code base.
Bandit also emphasizes correctness. Its HTTP/2 implementation scores 100% on the h2spec suite in strict mode, and its WebSocket implementation scores 100% on the Autobahn test suite, both of which run as part of Bandit's comprehensive CI suite. Extensive unit test, credo, dialyzer, and performance regression test coverage round out a test suite that ensures that Bandit is and will remain a platform you can count on.
Lastly, Bandit exists to demystify the lower layers of infrastructure code. In a world where The New Thing is nearly always adding abstraction on top of abstraction, it's important to have foundational work that is approachable & understandable by users above it in the stack.
Any Phoenix or Plug app should work with Bandit as a drop-in replacement for Cowboy; exceptions to this are errors (if you find one, please file an issue!).
Bandit fully supports Phoenix. Phoenix applications which use WebSockets for features such as Channels or LiveView require Phoenix 1.7 or later.
Using Bandit to host your Phoenix application couldn't be simpler:
Add Bandit as a dependency in your Phoenix application's mix.exs
:
{:bandit, "~> 1.0"}
Add the following adapter:
line to your endpoint configuration in config/config.exs
, as in the following example:
# config/config.exs
config :your_app, YourAppWeb.Endpoint,
adapter: Bandit.PhoenixAdapter, # <---- ADD THIS LINE
url: [host: "localhost"],
render_errors: ...
Using Bandit to host your own Plug is very straightforward. Assuming you have
a Plug module implemented already, you can host it within Bandit by adding
something similar to the following to your application's Application.start/2
function:
# lib/my_app/application.ex
defmodule MyApp.Application do
use Application
def start(_type, _args) do
children = [
{Bandit, plug: MyApp.MyPlug}
]
opts = [strategy: :one_for_one, name: MyApp.Supervisor]
Supervisor.start_link(children, opts)
end
end
For less formal usage, you can also start Bandit using the same configuration
options via the Bandit.start_link/1
function:
# Start an http server on the default port 4000, serving MyApp.MyPlug
Bandit.start_link(plug: MyPlug)
A number of options are defined when starting a server. The complete list is
defined by the t:Bandit.options/0
type.
By far the most common stumbling block encountered when setting up an HTTPS server involves configuring key and certificate data. Bandit is comparatively easy to set up in this regard, with a working example looking similar to the following:
# lib/my_app/application.ex
defmodule MyApp.Application do
use Application
def start(_type, _args) do
children = [
{Bandit,
plug: MyApp.MyPlug,
scheme: :https,
certfile: "/absolute/path/to/cert.pem",
keyfile: "/absolute/path/to/key.pem"}
]
opts = [strategy: :one_for_one, name: MyApp.Supervisor]
Supervisor.start_link(children, opts)
end
end
If you're using Bandit to run a Phoenix application as suggested above, there is nothing more for you to do; WebSocket support will 'just work'.
If you wish to interact with WebSockets at a more fundamental level, the WebSock and WebSockAdapter libraries provides a generic abstraction for WebSockets (very similar to how Plug is a generic abstraction on top of HTTP). Bandit fully supports all aspects of these libraries.
Bandit primarily consists of three protocol-specific implementations, one each for HTTP/1, HTTP/2 and WebSockets. Each of these implementations is largely distinct from one another, and is described in its own README linked above.
If you're just taking a casual look at Bandit or trying to understand how an HTTP server works, the HTTP/1 implementation is likely the best place to start exploring.
Contributions to Bandit are very much welcome! Before undertaking any substantial work, please open an issue on the project to discuss ideas and planned approaches so we can ensure we keep progress moving in the same direction.
All contributors must agree and adhere to the project's Code of Conduct.
Security disclosures should be handled per Bandit's published security policy.
Bandit is available in Hex. The package can be installed
by adding bandit
to your list of dependencies in mix.exs
:
def deps do
[
{:bandit, "~> 1.0"}
]
end
Documentation can be found at https://hexdocs.pm/bandit.
MIT