View Source WebSock behaviour (WebSock v0.4.1)
Defines a behaviour which defines an interface for web servers to flexibly host WebSocket
applications. Also provides a consistent upgrade facility to upgrade Plug.Conn
requests to
WebSock
connections for supported servers.
WebSocket connections go through a well defined lifecycle mediated by WebSock
:
- This step is outside the scope of the WebSock API. A client will attempt to Upgrade an HTTP connection to a WebSocket connection by passing a specific set of headers in an HTTP request. An application may choose to determine the feasibility of such an upgrade request however it pleases
- An application will then signal an upgrade to be performed by calling
WebSock.upgrade/4
, passing in thePlug.Conn
to upgrade, along with theWebSock
compliant handler module which will handle the connection once it is upgraded - The underlying server will then attempt to upgrade the HTTP connection to a WebSocket connection
- Assuming the WebSocket connection is successfully negotiated, WebSock will
call
WebSock.init/1
on the configured handler to allow the application to perform any necessary tasks now that the WebSocket connection is live - WebSock will call the configued handler's
WebSock.handle_in/2
callback whenever data is received from the client - WebSock will call the configued handler's
WebSock.handle_info/2
callback whenever other processes send messages to the handler process - The
WebSock
implementation can send data to the client by returning a{:push,...}
tuple from any of the abovehandle_*
callback - At any time,
WebSock.terminate/2
may be called to indicate a close, error or timeout condition
Link to this section Summary
Types
Details about why a connection was closed
The type of a supported connection option
Possible control frame types
Possible data frame types
The result as returned from init, handle_in, handle_control & handle_info calls
The type of an implementing module
The structure of a sent or received WebSocket message body
All possible frame types
Callbacks
Called by WebSock when a ping or pong frame has been received from the client. Note that implementations SHOULD NOT send a pong frame in response; this MUST be automatically done by the web server before this callback has been called.
Called by WebSock when a frame is received from the client. WebSock will only call this function once a complete frame has been received (that is, once any continuation frames have been received).
Called by WebSock when the socket process receives a GenServer.handle_info/2
call which was
not otherwise processed by the server implementation.
Called by WebSock after a WebSocket connection has been established (that is, after the server has accepted the connection & the WebSocket handshake has been successfully completed). Implementations can use this callback to perform tasks such as subscribing the client to any relevant subscriptions within the application, or any other task which should be undertaken at the time the connection is established
Called by WebSock when a connection is closed. reason
may be one of the following
Link to this section Types
@type close_reason() :: :normal | :remote | :shutdown | :timeout | {:error, term()}
Details about why a connection was closed
@type connection_opt() :: {:compress, boolean()} | {:timeout, timeout()} | {:max_frame_size, non_neg_integer()} | {:fullsweep_after, non_neg_integer()}
The type of a supported connection option
@type control_opcode() :: :ping | :pong
Possible control frame types
@type data_opcode() :: :text | :binary
Possible data frame types
@type handle_result() :: {:push, {opcode(), message()}, state()} | {:reply, term(), {opcode(), message()}, state()} | {:ok, state()} | {:stop, term(), state()}
The result as returned from init, handle_in, handle_control & handle_info calls
@type impl() :: module()
The type of an implementing module
@type message() :: iodata() | nil
The structure of a sent or received WebSocket message body
@type opcode() :: data_opcode() | control_opcode()
All possible frame types
@type state() :: term()
The type of state passed into / returned from WebSock
callbacks
Link to this section Callbacks
@callback handle_control( {message(), [{:opcode, control_opcode()}]}, state() ) :: handle_result()
Called by WebSock when a ping or pong frame has been received from the client. Note that implementations SHOULD NOT send a pong frame in response; this MUST be automatically done by the web server before this callback has been called.
Despite the name of this callback, it is not called for connection close frames even though they
are technically control frames. WebSock will handle any received connection
close frames and issue calls to terminate/2
as / if appropriate
This callback is optional
The return value from this callback is handled as described in handle_in/2
@callback handle_in( {message(), [{:opcode, data_opcode()}]}, state() ) :: handle_result()
Called by WebSock when a frame is received from the client. WebSock will only call this function once a complete frame has been received (that is, once any continuation frames have been received).
The return value from this callback are processed as follows:
{:push, {opcode(), message()}, state()}
: The indicated message is sent to the client. The indicated state value is used to update the socket's current state{:reply, term(), {opcode(), message()}, state()}
: The indicated message is sent to the client. The indicated state value is used to update the socket's current state. The second element of the tuple has no semantic meaning in this context and is ignored. This return tuple is included here solely for backwards compatiblity with thePhoenix.Socket.Transport
behaviour; it is in all respects semantically identical to the{:push, ...}
return value previously described{:ok, state()}
: The indicated state value is used to update the socket's current state{:stop, reason :: term(), state()}
: The connection will be closed based on the indicated reason. Ifreason
is:normal
,terminate/2
will be called with areason
value of:normal
. In all other cases, it will be called with{:error, reason}
. Server implementations should also use this value when determining how to close the connection with the client
@callback handle_info(term(), state()) :: handle_result()
Called by WebSock when the socket process receives a GenServer.handle_info/2
call which was
not otherwise processed by the server implementation.
The return value from this callback is handled as described in handle_in/2
@callback init(term()) :: handle_result()
Called by WebSock after a WebSocket connection has been established (that is, after the server has accepted the connection & the WebSocket handshake has been successfully completed). Implementations can use this callback to perform tasks such as subscribing the client to any relevant subscriptions within the application, or any other task which should be undertaken at the time the connection is established
The return value from this callback is handled as described in handle_in/2
@callback terminate(reason :: close_reason(), state()) :: any()
Called by WebSock when a connection is closed. reason
may be one of the following:
:normal
: The local end shut down the connection normally, by returning a{:stop, :normal, state()}
tuple from one of theWebSock.handle_*
callbacks:remote
: The remote end shut down the connection:shutdown
: The local server is being shut down:timeout
: No data has been sent or received for more than the configured timeout duration{:error, reason}
: An error ocurred. This may be the result of error handling in the local server, or the result of aWebSock.handle_*
callback returning a{:stop, reason, state}
tuple where reason is any value other than:normal
The return value of this callback is ignored
Link to this section Functions
@spec upgrade(Plug.Conn.t(), impl(), state(), [connection_opt()]) :: Plug.Conn.t()
Upgrades the provided Plug.Conn
connection request to a WebSock
connection using the
provided WebSock
compliant module as a handler.
This function returns the passed conn
set to an :upgraded
state.
The provided state
value will be used as the argument for init/1
once the WebSocket
connection has been successfully negotiated.
The opts
keyword list argument allows a number of options to be set on the WebSocket
connection. Not all options may be supported by the underlying HTTP server. Possible values are
as follows:
timeout
: The number of milliseconds to wait after no client data is received before closing the connection. Defaults to60_000
compress
: Whether or not to accept negotiation of a compression extension with the client. Defaults tofalse
max_frame_size
: The maximum frame size to accept, in octets. If a frame size larger than this is received the connection will be closed. Defaults to:infinity
:fullsweep_after
: The maximum number of garbage collections before forcing a fullsweep of the WebSocket connection process. Setting this option requires OTP 24 or newer