cowboy_loop man page

cowboy_loop — loop handlers


The cowboy_loop module implements a handler interface for long running HTTP connections. It is the recommended interface for long polling and server-sent events, amongst others.

This module is a sub protocol that defines three callbacks to be implemented by handlers. The init/2 and terminate/3 callbacks are common to all handler types and are documented in the manual for the cowboy_handler module.

The info/3 callback is specific to loop handlers and will be called as many times as necessary until a reply is sent.

It is highly recommended to return a timeout value from the init/2 callback to ensure that the process is terminated when no data has been received during that timespan. The default timeout is infinity, which should only be used if you have alternate means of ending inactive connections.

Terminate Reasons

The following values may be received as the terminate reason in the optional terminate/3 callback.


The connection was closed normally before switching to the loop sub protocol. This typically happens if an ok tuple is returned from the init/2 callback.


The handler requested to close the connection by returning a stop tuple.


The connection has been closed due to inactivity. The timeout value can be configured from init/2. The response sent when this happens is a 204 No Content.

{crash, Class, Reason}

A crash occurred in the handler. Class and Reason can be used to obtain more information about the crash. The function erlang:get_stacktrace/0 can also be called to obtain the stacktrace of the process when the crash occurred.

{error, overflow}

The connection is being closed and the process terminated because the buffer Cowboy uses to keep data sent by the client has reached its maximum. The buffer size can be configured through the environment value loop_max_buffer and defaults to 5000 bytes.

If the long running request comes with a body it is recommended to process this body before switching to the loop sub protocol.

{error, closed}

The socket has been closed brutally without a close frame being received first.

{error, Reason}

A socket error ocurred.


info(Info, Req, State) → {ok, Req, State} | {ok, Req, State, hibernate} | {stop, Req, State}

Info = any()

Message received by the process.

Req = cowboy_req:req()

The Req object.

State = any()

Handler state.

Handle the Erlang message received.

This function will be called every time an Erlang message has been received. The message can be any Erlang term.

The stop return value can be used to stop the receive loop, typically because a response has been sent.

The hibernate option will hibernate the process until it receives another message.