Packages

bandit

1.1.2
1.12.0 1.11.1 1.11.0 1.10.4 1.10.3 1.10.2 1.10.1 1.10.0 retired 1.9.0 1.8.0 1.7.0 1.6.11 1.6.10 1.6.9 1.6.8 1.6.7 1.6.6 1.6.5 1.6.4 1.6.3 1.6.2 1.6.1 1.6.0 1.5.7 1.5.6 1.5.5 1.5.4 1.5.3 1.5.2 1.5.1 1.5.0 1.4.2 1.4.1 1.4.0 1.3.0 1.2.3 1.2.2 1.2.1 1.2.0 1.1.3 1.1.2 1.1.1 1.1.0 1.0.0 1.0.0-pre.18 1.0.0-pre.17 1.0.0-pre.16 1.0.0-pre.15 1.0.0-pre.14 1.0.0-pre.13 1.0.0-pre.12 1.0.0-pre.11 1.0.0-pre.10 1.0.0-pre.9 1.0.0-pre.8 1.0.0-pre.7 1.0.0-pre.6 1.0.0-pre.5 1.0.0-pre.4 1.0.0-pre.3 1.0.0-pre.2 1.0.0-pre.1 0.7.7 0.7.6 0.7.5 0.7.4 0.7.3 0.7.2 0.7.1 0.7.0 0.6.11 0.6.10 0.6.9 0.6.8 0.6.7 0.6.6 0.6.5 0.6.4 0.6.3 0.6.2 0.6.1 0.6.0 0.5.11 0.5.10 0.5.9 0.5.8 0.5.7 0.5.6 0.5.5 0.5.4 0.5.3 0.5.2 0.5.1 0.5.0 0.4.10 0.4.9 0.4.8 0.4.7 0.4.6 0.4.5 0.4.4 0.4.3 0.4.2 0.4.1 0.4.0 0.3.9 0.3.8 0.3.7 0.3.6 0.3.5 0.3.4 0.3.3 0.3.2 0.2.3 0.2.2 0.2.1 0.2.0 0.1.1 0.1.0

A pure-Elixir HTTP server built for Plug & WebSock apps

Security advisory: This version has known vulnerabilities. View advisories
HexDocs

Current section

Files

Jump to
Readme
119 Versions
5 Dependencies
Dependants
7 Advisories
Files
Activity
bandit lib bandit websocket README.md
Raw

lib/bandit/websocket/README.md 

# WebSocket Handler



Included in this folder is a complete `ThousandIsland.Handler` based implementation of WebSockets

as defined in [RFC 6455](https://datatracker.ietf.org/doc/rfc6455). 



## Upgrade mechanism



A good overview of this process is contained in this [ElixirConf EU

talk](https://www.youtube.com/watch?v=usKLrYl4zlY).



Upgrading an HTTP connection to a WebSocket connection is coordinated by code

contained within several libraries, including Bandit,

[WebSockAdapter](https://github.com/phoenixframework/websock_adapter), and

[Plug](https://github.com/elixir-plug/plug). 



The HTTP request containing the upgrade request is first passed to the user's

application as a standard Plug call. After inspecting the request and deeming it

a suitable upgrade candidate (via whatever policy the application dictates), the

user indicates a desire to upgrade the connection to a WebSocket by calling

`WebSockAdapter.upgrade/4`, which checks that the request is a valid WebSocket

upgrade request, and then calls `Plug.Conn.upgrade_adapter/3` to signal to

Bandit that the connection should be upgraded at the conclusion of the request.

At the conclusion of the `Plug.call/2` callback, `Bandit.Pipeline` will then

attempt to upgrade the underlying connection. As part of this upgrade process,

`Bandit.DelegatingHandler` will switch the Handler for the connection to be

`Bandit.WebSocket.Handler`. This will cause any future communication after the

upgrade process to be handled directly by Bandit's WebSocket stack.



## Process model



Within a Bandit server, a WebSocket connection is modeled as a single process.

This process is directly tied to the lifecycle of the underlying WebSocket

connection; when upgrading from HTTP/1, the existing HTTP/1 handler process

'magically' becomes a WebSocket process by changing which Handler the

`Bandit.DelegatingHandler` delegates to. 



The execution model to handle a given request is quite straightforward: at

upgrade time, the `Bandit.DelegatingHandler` will call `handle_connection/2` to

allow the WebSocket handler to initialize any startup state. Connection state is

modeled by the `Bandit.WebSocket.Connection` struct and module.



All data subsequently received by the underlying [Thousand

Island](https://github.com/mtrudel/thousand_island) library will result in

a call to `Bandit.WebSocket.Handler.handle_data/3`, which will then attempt to

parse the data into one or more WebSocket frames. Once a frame has been

constructed, it is them passed through to the configured `WebSock` handler by

way of the underlying `Bandit.WebSocket.Connection`.



# Testing



All of this is exhaustively tested. Tests are broken up primarily into `protocol_test.exs`, which

is concerned with aspects of the implementation relating to protocol conformance and

client-facing concerns, while `sock_test.exs` is concerned with aspects of the implementation

having to do with the WebSock API and application-facing concerns. There are also more

unit-style tests covering frame serialization and deserialization.



In addition, the `autobahn` conformance suite is run via a `System` wrapper & executes the entirety

of the suite against a running Bandit server.