eWSrv/README.md

eWSrv
=====

An erlang web server

Build
-----

    $ rebar3 compile

## Usage

```sh
$ rebar3 shell
```

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

## Examples

### Callback Module

The best source to learn how to write a callback module
is [src/elli_example_callback.erl](src/elli_example_callback.erl) and
its [generated documentation](doc/elli_example_callback.md). 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:

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

-include_lib("elli/include/eWSrv.hrl").
-behaviour(wsHer).

handle(Req, _Args) ->
   %% Delegate to our handler function
   handle(Req#req.method, wsReq: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

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

```erlang
-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]}}.
```

## Further Reading

For more information about the features and design philosophy of `elli` check out the [overview](doc/README.md).