elli - Erlang web server for HTTP APIs

Hex.pm Documentation Erlang Travis CI Coverage Status MIT License

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 OTP 18.0 or newer.


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

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

{deps, [elli]}.

Afterwards you can run:

$ rebar3 compile


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


Callback Module

The best source to learn how to write a callback module is src/elli_example_callback.erl and its generated documentation. There are a bunch of examples used in the tests as well as descriptions of all the events.

A minimal callback module could look like this:

  -export([handle/2, handle_event/3]).
  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) ->

Supervisor Childspec

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

  start_link() ->
      supervisor:start_link({local, ?MODULE}, ?MODULE, []).
  init([]) ->
      ElliOpts = [{callback, fancyapi_callback}, {port, 3000}],
      ElliSpec = {
          {elli, start_link, [ElliOpts]},
      {ok, { {one_for_one, 5, 10}, [ElliSpec]} }.


Here's the features Elli does have:



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.


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




Elli is licensed under The MIT License.

Copyright (c) 2012-2016 Knut Nesheim, 2016-2018 elli-lib team