WebSock is a specification for apps to service WebSocket connections; you can
think of it as 'Plug for WebSockets'. WebSock abstracts WebSocket support from
servers such as Bandit or Cowboy and exposes a generic WebSocket API to
applications. WebSocket-aware applications such as Phoenix can then be hosted
within a supported web server simply by defining conformance to the WebSock
behaviour, in the same manner as how Plug conformance allows their HTTP aspects
to be hosted within an arbitrary web server.
Defines the WebSock
behaviour which describes the functions that
an application such as Phoenix must implement in order to be WebSock compliant;
it is roughly the equivalent of the Plug
interface, but for WebSocket
connections. It is commonly used in conjunction with the websock_adapter
package which defines concrete adapters on top of Bandit and Cowboy;
the two packages are separate to allow for servers which directly expose
WebSock
support to depend on just the behaviour. Users will almost always
want to depend on websock_adapter instead of this package.
WebSocket connections go through a well defined lifecycle mediated by WebSock
and WebSock.Adapters
:
WebSockAdapter.upgrade/4
, passing in the Plug.Conn
to upgrade, along with
the WebSock
compliant handler module which will handle the connection once
it is upgradedc:WebSock.init/1
on the configured handler to allow the application to perform any necessary
tasks now that the WebSocket connection is livec:WebSock.handle_in/2
callback
whenever data is received from the clientc:WebSock.handle_info/2
callback
whenever other processes send messages to the handler processWebSock
implementation can send data to the client by returning
a {:push,...}
tuple from any of the above handle_*
callbacksc:WebSock.terminate/2
(if implemented) may be called to indicate a close, error or
timeout conditionFor more information, consult the docs.
The websock package can be installed by adding websock
to your list of dependencies in mix.exs
:
def deps do
[
{:websock, "~> 0.5"}
]
end
Documentation can be found at https://hexdocs.pm/websock.
MIT