WebSock

WebSock is a specification for apps to service WebSocket connections; you can think of it as 'Plug for WebSockets'. Web servers such as Bandit or Cowboy are expected to implement support for hosting WebSock-based applications (possibly by way of an adapter library such as Plug.Cowboy). 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.

The WebSock specification is just that; a specification. There is no actual code in this specification as there is within the Plug specification, largely due to the lower-level nature of WebSockets as compared to HTTP. What you will find here consists of simple interface which dictates conventions about how the lifecycle of a WebSocket connection is managed.

The WebSock behaviour describes the functions that an application must implement in order to be WebSock compliant; it is the equivalent of the Plug interface, but for WebSocket connections. Server implementations are expected to manage the upgrade process to WebSocket connections themselves, based on their specific policy and routing decisions and aided by helper functions within the Plug API (see below for details).

WebSocket Lifecycle

WebSocket connections go through a well defined lifecycle, which is reflected in the shape of the WebSock behaviour:

• 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 the upgrade request however it pleases. Most typically, an application will then signal an upgrade to be performed by calling the Plug.Conn.upgrade_adapter/3 callback with parameters indicating an upgrade to WebSock (note that the structure of these arguments depends on the particular server in use; consult Bandit or Plug.Cowboy documentation for details)
• Assuming the application accepted the WebSocket connection, the underlying server will then upgrade the HTTP connection to a WebSocket connection, and will call c:WebSock.init/1 to allow the application to perform any necessary tasks now that the WebSocket connection is live
• The WebSock implementation will be notified of client data by way of the c:WebSock.handle_in/2 callback
• The WebSock implementation may choose to be notified of control frames by way of the optional c:WebSock.handle_control/2 callback. Note that user implementations DO NOT need to concern themselves with issuing pong frames in response to ping requests; the underlying server implementation MUST handle this
• The WebSock implementation will be notified of any messages sent to it by other processes by way of the c:WebSock.handle_info/2 callback
• The WebSock implementation can send data to the client by returning a {:push,...} tuple from any of the above handle_* callback
• At any time, c:WebSock.terminate/2 may be called to indicate a close, error or timeout condition

For more information, consult the docs.

Installation

The websock package can be installed by adding websock to your list of dependencies in mix.exs:

def deps do
  [
    {:websock, "~> 0.4.0"}
  ]
end

Documentation can be found at https://hexdocs.pm/websock.

License

MIT