75 lines
3.4 KiB
Markdown
75 lines
3.4 KiB
Markdown
# WebSock
|
|
|
|
[](https://github.com/phoenixframework/websock/actions)
|
|
[](https://hexdocs.pm/websock)
|
|
[](https://hex.pm/packages/websock)
|
|
|
|
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.
|
|
|
|
<!-- MDOC -->
|
|
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 Lifecycle
|
|
|
|
WebSocket connections go through a well defined lifecycle mediated by `WebSock`
|
|
and `WebSock.Adapters`:
|
|
|
|
* **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
|
|
`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 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 `c: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 configured handler's `c:WebSock.handle_in/2` callback
|
|
whenever data is received from the client
|
|
* WebSock will call the configured handler's `c: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 above `handle_*` callbacks
|
|
* At any time, `c:WebSock.terminate/2` (if implemented) may be called to indicate a close, error or
|
|
timeout condition
|
|
|
|
[Cowboy]: https://github.com/ninenines/cowboy
|
|
[Bandit]: https://github.com/mtrudel/bandit/
|
|
[websock_adapter]: https://hex.pm/packages/websock_adapter
|
|
<!-- MDOC -->
|
|
|
|
For more information, consult the [docs](https://hexdocs.pm/websock).
|
|
|
|
## Installation
|
|
|
|
The websock package can be installed by adding `websock` to your list of dependencies in `mix.exs`:
|
|
|
|
```elixir
|
|
def deps do
|
|
[
|
|
{:websock, "~> 0.5"}
|
|
]
|
|
end
|
|
```
|
|
|
|
Documentation can be found at <https://hexdocs.pm/websock>.
|
|
|
|
## License
|
|
|
|
MIT
|