SSE handler for Cowboy
Erlang Makefile HTML
Latest commit 692eaec Mar 11, 2016 @igaray igaray Merge pull request #41 from inaka/harenson.40.update-repo-and-make-it…

[Fix #40] Update dependencies; Update; Add ruleset to elvis config; Add rebar.config file
Failed to load latest commit information.
examples/ping_pong [#37] Fix elvis warnings, remove unneeded env vars and other goodies Jan 11, 2016
.gitignore [#37] Version bump to 1.0.1 Jan 11, 2016
elvis.config [Fix #40] Update dependencies; Update; Add ruleset to elvis… Mar 11, 2016

Stories in Ready


SSE handler for Cowboy.



lasse provides a cowboy loop handler called lasse_handler that describes a behaviour. To include it in your server routes, just add the following tuple to your dispatch routes:

{<<"/your/[:route]">>, lasse_handler, [your_module]}
% or
{<<"/your/[:route]">>, lasse_handler, [{module, your_module}, {init_args, Args}]}

Specifying the module (e.g your_module) is mandatory while providing a value for init_args is optional.

Additionally, in your module, you have to implement the lasse_handler behaviour and its callbacks:


Contact Us

For questions or general comments regarding the use of this library, please use our public hipchat room.

If you find any bugs or have a problem while using this library, please open an issue in this repo (or a pull request :)).

And you can check all of our open-source projects at


You can find some example applications that implement the lasse_handler in the examples folder.

Running the examples is as simple as executing make run, given you have the make tool, git and erlang installed in your environment.


notify(Pid, Message) -> ok

Used to send in-band messages to the handler given its Pid.


  • Pid = pid()
  • Message = any()


init(InitArgs, LastEventId, Req) -> {ok, NewReq, State}

| {ok, NewReq, InitialEvents, State}
| {no_content, NewReq, State}
| {shutdown, StatusCode, Headers, Body, NewReq, State}

Will be called upon initialization of the handler, receiving the value of the "last-event-id" header if there is one or undefined otherwise. If everything goes well it should return {ok, NewReq, State} to leave the connection open or {ok, NewReq, InitialEvents, State} if there are any InitialEvents that need to ben sent before the handler enters its loop.

In case the handler has no content to deliver it should return {no_content, NewReq, State} and the client will receive a response with a status code 204 No Content. A custom response can be provided for other scenarios by returning {shutdown, StatusCode, Headers, Body, NewReq, State}, which will cause the handler to reply to the client with the information supplied and then terminate.


  • InitArgs = any()
  • LastEventId = binary() | undefined
  • Req = cowboy_req:req()
  • NewReq = cowboy_req:req()
  • State = any()
  • StatusCode = cowboy:http_status()
  • Headers = cowboy:http_headers()
  • Body = iodata()

handle_notify(Msg, State) -> Result

Receives and processes in-band messages sent through the lasse_handler:notify/2 function.


  • Msg = any()
  • State = any()
  • Result = result()

handle_info(Msg, State) -> Result

Receives and processes out-of-band messages sent directly to the handler's process.


  • Msg = any()
  • State = any()
  • Result = result()

handle_error(Msg, Reason, State) -> NewState

If there's a problem while sending a chunk to the client, this function will be called after which the handler will terminate.


  • Msg = any()
  • Reason = atom()
  • State = any()
  • NewState = any()

terminate(Reason, Req, State) -> ok

This function will be called before terminating the handler, its return value is ignored.


  • Reason = atom()
  • Req = cowboy:http_headers()
  • State = any()


result() = {'send', Event :: event(), NewState :: any()}

| {'nosend', NewState :: any()}
| {'stop', NewState :: any()}

event() = [event_value(), ...]

The field data is required for every event returned by handle_notify() and hanfle_info(), if none is supplied data_required will be thrown.

event_value() = {'id', binary()}

| {'event', binary()}
| {'data', binary()}
| {'retry', binary()}
| {'comment', binary()}