Lasse

SSE handler for Cowboy.

References

• Cowboy
• SSE
• canillita's handler (as a reference)

Usage

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:

-behaviour(lasse_handler).

Contact Us

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 inaka.github.io

Examples

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

API

notify(Pid, Message) -> ok

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

Types:

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

Callbacks

init(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.

Types:

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

Types:

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

Types:

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

Types:

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

Types:

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

Types

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()}