blt / elli

Simple, robust and performant Erlang web server

elli - Erlang web server for HTTP APIs

Elli is a webserver you can run inside your Erlang application to expose an HTTP API. Elli is a aimed exclusively at building high-throughput, low-latency HTTP APIs. If robustness and performance is more important than general purpose features, then elli might be for you. If you find yourself digging into the implementation of a webserver, elli might be for you. If you're building web services, not web sites, then elli might be for you.

Elli is used in production at Wooga and Game Analytics. Elli requires R15 or newer.

Features

Here's the features Elli does have:

• Rack-style request-response. Your handler function gets a complete request and returns a complete response. There's no messaging, no receiving data directly from the socket, no writing responses directly to the socket. It's a very simple and straightforward API. Have a look at src/elli_example_callback.erl for examples.

• Middlewares allows you to add useful features like compression, encoding, stats, but only have it used when needed. No features you don't use on the critical path.

• Short-circuiting of responses using exceptions, allows you to use "assertions" that return for example 403 permission denied. is_allowed(Req) orelse throw({403, [], <<"Permission denied">>}).

• Every client connection gets its own process, isolating the failure of a request from another. For the duration of the connection, only one process is involved, resulting in very robust and efficient code.

• Binaries everywhere for strings.

• Instrumentation inside the core of the webserver, triggering user callbacks. For example when a request completes, the user callback gets the request_complete event which contains timings of all the different parts of handling a request. There's also events for clients unexpectedly closing a connection, crashes in the user callback, etc.

• Keep alive, using one Erlang process per connection only active when there is a request from the client. Number of connections is only limited by RAM and CPU.

• Chunked transfer in responses for real-time push to clients

• Basic pipelining. HTTP verbs that does not have side-effects(GET and HEAD) can be pipelined, ie. a client supporting pipelining can send multiple requests down the line and expect the responses to appear in the same order as requests. Elli processes the requests one at a time in order, future work could make it possible to process them in parallel.

• SSL using built-in Erlang/OTP ssl, nice for low volume admin interfaces, etc. For high volume, you should probably go with nginx, stunnel or ELB if you're on AWS.

• Implement your own connection handling, for WebSockets, streaming uploads, etc. See src/elli_example_callback_handover.erl

Extensions

• WebSockets: https://github.com/mmzeeman/elli_websocket
• Access log: https://github.com/wooga/elli_access_log
• Basic auth: https://github.com/martinrehfeld/elli_basicauth
• Static content: https://github.com/chrisavl/elli_fileserve
• "Date" header: https://github.com/knutin/elli_date
• Cookies: https://github.com/drfloob/elli_cookie
• Real-time statistics dashboard: https://github.com/knutin/elli_stats

About

From operating and debugging high-volume, low-latency apps we have gained some valuable insight into what we want from a webserver. We want simplicity, robustness, performance, ease of debugging, visibility into strange client behaviour, really good instrumentation and good tests. We are willing to sacrifice almost everything, even basic features to achieve this.

With this in mind we looked at the big names in the Erlang community: Yaws, Mochiweb, Misultin and Cowboy. We found Mochiweb to be the best match. However, we also wanted to see if we could take the architecture of Mochiweb and improve on it. elli takes the acceptor-turns-into-request-handler idea found in Mochiweb, the binaries-only idea from Cowboy and the request-response idea from WSGI/Rack (with chunked transfer being an exception).

On top of this we built a handler that allows us to write HTTP middleware modules to add practical features, like compression of responses, HTTP access log with timings, a real-time statistics dashboard and chaining multiple request handlers.

Aren't there enough webservers in the Erlang community already?

There are a few very mature and robust projects with steady development, one recently ceased development and one new kid on the block with lots of interest. As elli is not a general purpose webserver, but more of a specialized tool, we believe it has a very different target audience and would not attract effort or users away from the big names.

Why another webserver? Isn't this just the NIH syndrome?

Yaws, Mochiweb, Misultin and Cowboy are great projects, hardened over time and full of very useful features for web development. If you value developer productivity, Yaws is an excellent choice. If you want a fast and lightweight server, Mochiweb and Cowboy are excellent choices.

Having used and studied all of these projects, we believed that if we merged some of the existing ideas and added some ideas from other communities, we could create a core that was better for our use cases.

It started out as an experiment to see if it is at all possible to significantly improve and it turns out that for our particular use cases, there is enough improvement to warrant a new project.

What makes Elli different?

Elli has a very simple architecture. It avoids using more processes and messages than absolutely necessary. It uses binaries for strings. The request-response programming model allows middlewares to do much heavy lifting, so the core can stay very simple. It has been instrumented so as a user you can understand where time is spent. When things go wrong, like the client closed the connection before you could send a response, you are notified about these things so you can better understand your client behaviour.

Performance

"Hello World!" micro-benchmarks are really useful when measuring the performance of the webserver itself, but the numbers usually do more harm than good when released. I encourage you to run your own benchmarks, on your own hardware. Mark Nottingham has some very good pointers about benchmarking HTTP servers.

Installation

To use elli you will need a working installation of Erlang R15BXX (or later).

Add elli to your application by adding it as a dependency to your rebar config.

% rebar.config:
{deps, [
    {elli, "", {git, "git://github.com/knutin/elli.git"}},
    % ...
]}.

Afterwards you can run:

$: ./rebar get-deps
$: ./rebar compile

Usage

$: erl -pa deps/*/ebin ebin

% starting elli
1>: {ok, Pid} = elli:start_link([{callback, elli_example_callback}, {port, 3000}]).

Callback module

The best source of documentation for how to write a callback module is src/elli_example_callback.erl. It has a bunch of examples used in the tests.

A minimal callback module could look like this:

-module(elli_minimal_callback).
-export([handle/2, handle_event/3]).

-include_lib("elli/include/elli.hrl").
-behaviour(elli_handler).

handle(Req, _Args) ->
    %% Delegate to our handler function
    handle(Req#req.method, elli_request:path(Req), Req).

handle('GET',[<<"hello">>, <<"world">>], _Req) ->
    %% Reply with a normal response. 'ok' can be used instead of '200'
    %% to signal success.
    {ok, [], <<"Hello World!">>};

handle(_, _, _Req) ->
    {404, [], <<"Not Found">>}.

%% @doc: Handle request events, like request completed, exception
%% thrown, client timeout, etc. Must return 'ok'.
handle_event(_Event, _Data, _Args) ->
    ok.

Supervisor Childspec example

To add elli to a supervisor you can use the following example and adapt it to your needs.

-module(fancyapi_sup).
-behaviour(supervisor).
-export([start_link/0]).
-export([init/1]).

start_link() ->
    supervisor:start_link({local, ?MODULE}, ?MODULE, []).

init([]) ->
    ElliOpts = [{callback, fancyapi_callback}, {port, 3000}],
    ElliSpec = {
        fancy_http,
        {elli, start_link, [ElliOpts]},
        permanent,
        5000,
        worker,
        [elli]},

    {ok, { {one_for_one, 5, 10}, [ElliSpec]} }.