From 849fab7227a2fd1ff5fa4d603ba89037e1c462b4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lo=C3=AFc=20Hoguin?= Date: Tue, 26 May 2020 09:54:54 +0200 Subject: Cowboy 2.8.0 --- docs/en/cowboy/2.8/guide/ws_protocol.asciidoc | 69 +++++++++++++++++++++++++++ 1 file changed, 69 insertions(+) create mode 100644 docs/en/cowboy/2.8/guide/ws_protocol.asciidoc (limited to 'docs/en/cowboy/2.8/guide/ws_protocol.asciidoc') diff --git a/docs/en/cowboy/2.8/guide/ws_protocol.asciidoc b/docs/en/cowboy/2.8/guide/ws_protocol.asciidoc new file mode 100644 index 00000000..8fa0673d --- /dev/null +++ b/docs/en/cowboy/2.8/guide/ws_protocol.asciidoc @@ -0,0 +1,69 @@ +[[ws_protocol]] +== The Websocket protocol + +This chapter explains what Websocket is and why it is +a vital component of soft realtime Web applications. + +=== Description + +Websocket is an extension to HTTP that emulates plain TCP +connections between the client, typically a Web browser, +and the server. It uses the HTTP Upgrade mechanism to +establish the connection. + +Websocket connections are fully asynchronous, unlike +HTTP/1.1 (synchronous) and HTTP/2 (asynchronous, but the +server can only initiate streams in response to requests). +With Websocket, the client and the server can both send +frames at any time without any restriction. It is closer +to TCP than any of the HTTP protocols. + +Websocket is an IETF standard. Cowboy supports the standard +and all drafts that were previously implemented by browsers, +excluding the initial flawed draft sometimes known as +"version 0". + +=== Websocket vs HTTP/2 + +For a few years Websocket was the only way to have a +bidirectional asynchronous connection with the server. +This changed when HTTP/2 was introduced. While HTTP/2 +requires the client to first perform a request before +the server can push data, this is only a minor restriction +as the client can do so just as it connects. + +Websocket was designed as a kind-of-TCP channel to a +server. It only defines the framing and connection +management and lets the developer implement a protocol +on top of it. For example you could implement IRC over +Websocket and use a Javascript IRC client to speak to +the server. + +HTTP/2 on the other hand is just an improvement over +the HTTP/1.1 connection and request/response mechanism. +It has the same semantics as HTTP/1.1. + +If all you need is to access an HTTP API, then HTTP/2 +should be your first choice. On the other hand, if what +you need is a different protocol, then you can use +Websocket to implement it. + +=== Implementation + +Cowboy implements Websocket as a protocol upgrade. Once the +upgrade is performed from the `init/2` callback, Cowboy +switches to Websocket. Please consult the next chapter for +more information on initiating and handling Websocket +connections. + +The implementation of Websocket in Cowboy is validated using +the Autobahn test suite, which is an extensive suite of tests +covering all aspects of the protocol. Cowboy passes the +suite with 100% success, including all optional tests. + +Cowboy's Websocket implementation also includes the +permessage-deflate and x-webkit-deflate-frame compression +extensions. + +Cowboy will automatically use compression when the +`compress` option is returned from the `init/2` function. -- cgit v1.2.3