Bandit (Bandit v1.6.11)

Bandit is an HTTP server for Plug and WebSock apps.

As an HTTP server, Bandit's primary goal is to act as 'glue' between client connections managed by Thousand Island and application code defined via the Plug and/or WebSock APIs. As such there really isn't a whole lot of user-visible surface area to Bandit, and as a consequence the API documentation presented here is somewhat sparse. This is by design! Bandit is intended to 'just work' in almost all cases; the only thought users typically have to put into Bandit comes in the choice of which options (if any) they would like to change when starting a Bandit server. The sparseness of the Bandit API should not be taken as an indicator of the comprehensiveness or robustness of the project.

Using Bandit With Phoenix

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: ...

That's it! You should now see messages at startup indicating that Phoenix is using Bandit to serve your endpoint, and everything should 'just work'. Note that if you have set any exotic configuration options within your endpoint, you may need to update that configuration to work with Bandit; see the Bandit.PhoenixAdapter documentation for more information.

Using Bandit With Plug Applications

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)

Configuration

A number of options are defined when starting a server. The complete list is defined by the t:Bandit.options/0 type.

Setting up an HTTPS Server

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

WebSocket Support

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.

Receiving messages in your Plug process: A word of warning

The Plug specification is concerned only with the shape of the Plug.init/1 and Plug.call/2 functions; it says nothing about the process model that underlies the call, nor about how the Plug function should respond to any messages it may receive. Although it is occasionally necessary to receive messages from within your Plug call, this must be done with caution as Bandit makes extensive use of messaging internally, especially with HTTP/2 based requests.

In particular, you must ensure that your code never receives messages that match the patterns {:bandit, _} or {:plug_conn, :sent}. Any receive calls you make should be appropriately guarded to ensure that these messages remain in the process' mailbox for Bandit to process them when required.

Summary

Types

deflate_options()

Options to configure the deflate library used for HTTP compression

http_1_options()

Options to configure the HTTP/1 stack in Bandit

http_2_options()

Options to configure the HTTP/2 stack in Bandit

http_options()

Options to configure shared aspects of the HTTP stack in Bandit

options()

Possible top-level options to configure a Bandit server

websocket_options()

Options to configure the WebSocket stack in Bandit

Functions

start_link(arg)

Starts a Bandit server using the provided arguments. See options/0 for specific options to pass to this function.