View Source Bandit (Bandit v0.6.3)

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

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:

  1. Add Bandit as a dependency in your Phoenix application's mix.exs:

      {:bandit, ">= 0.5.10"}
  2. Add the following to your endpoint configuration in config/config.exs:

      config :your_app, YourAppWeb.Endpoint,
        adapter: Bandit.PhoenixAdapter
  3. That's it! You should now see messages at startup indicating that Phoenix is using Bandit to serve your endpoint.

For more details about how to configure Bandit within Phoenix, consult the Bandit.PhoenixAdapter documentation.

using-bandit-with-plug-applications

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:

def start(_type, _args) do
  children = [
    {Bandit, plug: MyApp.MyPlug, scheme: :http, options: [port: 4000]}
  ]

  opts = [strategy: :one_for_one, name: MyApp.Supervisor]
  Supervisor.start_link(children, opts)
end

For details about writing Plug based applications, consult the excellent Plug documentation for plenty of examples & tips to get started. Bandit supports the complete Plug API & should work correctly with any Plug-based application. If you encounter errors using Bandit your Plug app, please do get in touch by filing an issue on the Bandit GitHub project (especially if the error does not occur with another HTTP server such as Cowboy).

config-options

Config Options

Bandit takes a number of options at startup:

  • plug: The plug to handle connections. Can be specified as MyPlug or {MyPlug, plug_opts}
  • display_plug: The plug to use when describing the connection in logs. Useful for situations such as Phoenix code reloading where you have a 'wrapper' plug but wish to refer to the connection by the endpoint name
  • scheme: One of :http or :https. If :https is specified, you will need to specify certfile and keyfile in the transport_options subsection of options.
  • options: Options to pass to ThousandIsland. For an exhaustive list of options see the ThousandIsland documentation, however some common options are:
    • port: The port to bind to. Defaults to 4000
    • num_acceptors: The number of acceptor processes to run. This is mostly a performance tuning knob and can usually be left at the default value of 10
    • read_timeout: How long to wait for data from the client before timing out and closing the connection, specified in milliseconds. Defaults to 15_000 milliseconds
    • transport_module: The name of the module which provides basic socket functions. This overrides any value set for scheme and is intended for cases where control over the socket at a fundamental level is needed.
    • transport_options: A keyword list of options to be passed into the transport socket's listen function

setting-up-an-https-server

Setting up an HTTPS Server

By far the most common stumbling block encountered with configuration involves setting up an HTTPS server. Bandit is comparatively easy to set up in this regard, with a working example looking similar to the following:

def start(_type, _args) do
  bandit_options = [
    port: 4000,
    transport_options: [
      certfile: Path.join(__DIR__, "path/to/cert.pem"),
      keyfile: Path.join(__DIR__, "path/to/key.pem")
    ]
  ]

  children = [
    {Bandit, plug: MyApp.MyPlug, scheme: :https, options: bandit_options}
  ]

  opts = [strategy: :one_for_one, name: MyApp.Supervisor]
  Supervisor.start_link(children, opts)
end

websocket-support

WebSocket Support

Bandit supports upgrading HTTP requests to WebSocket connections via the use of the Plug.Conn.upgrade_adapter/3 function, called with :websocket as the second argument. Applications should validate that the connection represents a valid WebSocket request before calling this function (Bandit will validate the connection as part of the upgrade process, but does not provide any capacity for an application to be notified if the upgrade is not successful). If an application wishes to negotiate WebSocket subprotocols or otherwise set any response headers, it should do so before calling Plug.Conn.upgrade_adapter/3.

The third argument to Plug.Conn.upgrade_adapter/3 defines the details of how Bandit should handle the WebSocket connection, and must take the form {handler, handler_opts, connection_opts}, where values are as follows:

  • handler is a module which implements the WebSock API
  • handler_opts is an arbitrary term which will be passed as the argument to WebSock.init/1
  • connection_opts is a keyword list which consists of zero or more of the following options:
    • timeout: The number of milliseconds to wait after no client data is received before closing the connection. Defaults to 60_000
    • compress: Whether or not to accept negotiation of a compression extension with the client. Defaults to false
    • :fullsweep_after - the maximum number of garbage collections before forcing a fullsweep of the socket process. You can set it to 0 to force more frequent cleanups of your websocket transport processes. Setting this option requires Erlang/OTP 24

Link to this section Summary

Types

A Plug definition

Functions

Starts a Bandit server using the provided arguments. See "Config Options' above for specific options to pass to this function.

Link to this section Types

@type plug() :: {module(), keyword()}

A Plug definition

Link to this section Functions

@spec child_spec(keyword()) :: Supervisor.child_spec()

Starts a Bandit server using the provided arguments. See "Config Options' above for specific options to pass to this function.