WebSocket.protocol.txt

             
   WEBSOCKET  
             


WebSocket:
  - Gives server possibility to initiate communication with client
  - Is over TCP (ws://) or TSL (wss://)
  - Can debug in Chrome develper tools (see Upgrade request and message payloads|type), or using wscat

HTTP handshake:
  - client:
     - Connection: Upgrade [C]
     - Upgrade: websocket [C]
     - Origin: HOST [C]
     - Sec-WebSocket-Key: TOKEN [C]: random-generated then Base64
     - Sec-WebSocket-Protocol: SUBPROTOCOL;... [C]
        - can be signified with ws[s][.SUBPROTOCOL]://
        - SUBPROTOCOL is either:
           - the protocol on top of Websocket (the one of the messages)
           - extensions on the Websocket protocol
           - The request ask for one or severals subprotocols, and the server respond with the one it chooses.
     - Sec-WebSocket-Version: NUM [C]
        - server send Sec-WebSocket-Version: NUM [S] if server's version is lower
  - (success) server sends 101:
     - Connection: Upgrade [C]
     - Upgrade: websocket [S]
     - Sec-WebSocket-Accept: TOKEN2 [S]: SHA1(TOKEN + STR), where STR is fixed magic string
     - Sec-WebSocket-Protocol: SUBPROTOCOL [S]
  - (failure) server sends 426
  - Then following TCP exchanges should be interpreted as Websocket protocol, not HTTP

Websocket protocol:
  - client|server, but each end communicate to other the same way
  - bits:
     - 0x00: FIN bit: 1 if final frame of a single message (to allow big messages)
     - 0x01-0x03: reserved RSV1-3
     - 0x04-0x07: opcode:
        - message: 1|2 (text|binary) for first frame then 0 for next frames
        - ping|pong: 9|10
     - 0x08: MASK bit: usually set 1 by browsers
     - 0x09-0xdf: payload length
     - 0xe0-0xff: MASK: XOR key applied on payload, to introduce randomness (not for confidentiality but prevent cache
       poisoning)
     - 0xg0-...: payload
  - closing:
     - single packet
     - error codes:
        - 0-999 : reserved
        - 1000, CLOSE_NORMAL
        - 1001, CLOSE_GOING_AWAY : server failure or browser changing page
        - 1002, CLOSE_PROTOCOL_ERROR
        - 1003, CLOSE_UNSUPPORTED : received data in a format not supported
        - 1004, CLOSE_TOO_LARGE : received too big data
        - 3000-3999 : for libraries
        - 4000-4999 : for applications
     - payload: error message (123 octets max).

Security:
  - Should use wss://
  - CSWSH (CSRF for WebSockets)
     - Send 403 if Origin [C] not good
     - Use CSRF tokens
  - Should also secure AJAX fallback when fallback is used

Extensions (Sec-Websocket-Protocol):
  - permessage-deflate:
     - compress payloads
     - only if RSV1 bit set (so can choose not to compress if too small payload)
     - if not supported, can always compress data yourself and send as binary
  - client|server_max_window_bits[=UINT]:
     - choose compression buffer size: the higher, the most compressed but the longer|more resource needed
     - is UINT -> 2^UINT (def: 15)
     - client_max_window_bits; server_max_window_bits=UINT must be set by client, and inverse
  - client|server_no_context_takeover:
     - disallow keeping memory of previous messages: decrease compression, but required less memory
     - to do if messages are very diffrent, meaning it will not benefit the context takeover

Comparison with HTTP2:
  - advantages:
     - main one: realtime server push
     - least one: smaller header throughput
  - disadvantages:
     - no multiplexing: only one request at a time
     - no builtin semantics:
        - using method, headers, status codes, etc.
        - so cannot use (unless built): caching, redirections, user agent identity, content negotiation, proxies, tracking

Debugging:
  - about:networking#websockets (Firefox)