123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155 |
- [/
- Copyright (c) 2016-2019 Vinnie Falco (vinnie dot falco at gmail dot com)
- Distributed under the Boost Software License, Version 1.0. (See accompanying
- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
- Official repository: https://github.com/boostorg/beast
- ]
- [section Handshaking]
- [/-----------------------------------------------------------------------------]
- [heading Client Role]
- A WebSocket session begins when a client sends the HTTP/1.1
- [@https://tools.ietf.org/html/rfc7230#section-6.7 Upgrade]
- request for
- [@https://tools.ietf.org/html/rfc6455#section-1.3 WebSocket]
- on an established connection, and the server sends an appropriate response
- indicating that the request was accepted and that the connection has been
- upgraded. The Upgrade request must include the
- [@https://tools.ietf.org/html/rfc7230#section-5.4 Host]
- field, and the
- [@https://tools.ietf.org/html/rfc7230#section-5.3 target]
- of the resource to request.
- A typical HTTP Upgrade request created and sent by the implementation
- will look like this:
- [table WebSocket HTTP Upgrade Request
- [[Wire Format][Description]]
- [[
- ```
- GET / HTTP/1.1
- Host: www.example.com
- Upgrade: websocket
- Connection: upgrade
- Sec-WebSocket-Key: 2pGeTR0DsE4dfZs2pH+8MA==
- Sec-WebSocket-Version: 13
- User-Agent: Boost.Beast/216
- ```
- ][
- The host and target parameters become part of the Host field
- and request-target in the resulting HTTP request. The key is
- generated by the implementation. Callers who wish to add,
- modify, or inspect fields may set the ['decorator] option
- on the stream (described later).
- ]]]
- The
- [link beast.ref.boost__beast__websocket__stream `websocket::stream`]
- member functions
- [link beast.ref.boost__beast__websocket__stream.handshake `handshake`] and
- [link beast.ref.boost__beast__websocket__stream.async_handshake `async_handshake`]
- are used to send the request with the required host and target strings. This
- code connects to the IP address returned from a hostname lookup, then performs
- the WebSocket handshake in the client role.
- [code_websocket_2_1]
- When a client receives an HTTP Upgrade response from the server indicating
- a successful upgrade, the caller may wish to perform additional validation
- on the received HTTP response message. For example, to check that the
- response to a basic authentication challenge is valid. To achieve this,
- overloads of the handshake member function allow the caller to store the
- received HTTP message in an output reference argument of type
- [link beast.ref.boost__beast__websocket__response_type `response_type`]
- as follows:
- [code_websocket_2_2]
- [/-----------------------------------------------------------------------------]
- [heading Server Role]
- For servers accepting incoming connections, the
- [link beast.ref.boost__beast__websocket__stream `websocket::stream`]
- can read the incoming upgrade request and automatically reply. If the handshake
- meets the requirements, the stream sends back the upgrade response with a
- [@https://tools.ietf.org/html/rfc6455#section-4.2.2 ['101 Switching Protocols]]
- status code. If the handshake does not meet the requirements, or falls outside
- the range of allowed parameters specified by stream options set previously by
- the caller, the stream sends back an HTTP response with a status code indicating
- an error. Depending on the keep alive setting, the connection may remain open
- for a subsequent handshake attempt. A typical HTTP Upgrade response created and
- sent by the implementation upon receiving an upgrade request handshake will
- look like this:
- [table WebSocket Upgrade HTTP Response
- [[Wire Format][Description]]
- [[
- ```
- HTTP/1.1 101 Switching Protocols
- Upgrade: websocket
- Connection: upgrade
- Sec-WebSocket-Accept: s3pPLMBiTxaQ9kYGzzhZRbK+xOo=
- Server: Boost.Beast
- ```
- ][
- The
- [@https://tools.ietf.org/html/rfc6455#section-11.3.3 ['Sec-WebSocket-Accept]]
- field value is generated from the request in a fashion specified by
- the WebSocket protocol.
- ]]]
- The
- [link beast.ref.boost__beast__websocket__stream `stream`]
- member functions
- [link beast.ref.boost__beast__websocket__stream.accept `accept`] and
- [link beast.ref.boost__beast__websocket__stream.async_accept `async_accept`]
- are used to read the WebSocket HTTP Upgrade request handshake from a stream
- already connected to an incoming peer, and then send the WebSocket HTTP
- Upgrade response, as shown:
- [code_websocket_2_3]
- [heading Handshake Buffering]
- It is possible for servers to read data from the stream and decide later
- that the buffered bytes should be interpreted as a WebSocket upgrade
- request. To address this usage, overloads of
- [link beast.ref.boost__beast__websocket__stream.accept `accept`] and
- [link beast.ref.boost__beast__websocket__stream.async_accept `async_accept`]
- which accept an additional buffer sequence parameter are provided.
- In this example, the server reads the initial HTTP request header into a
- dynamic buffer, then later uses the buffered data to attempt a websocket
- upgrade.
- [code_websocket_2_4]
- [heading Inspecting HTTP Requests]
- When implementing an HTTP server that also supports WebSocket, the
- server usually reads the HTTP request from the client. To detect when
- the incoming HTTP request is a WebSocket Upgrade request, the function
- [link beast.ref.boost__beast__websocket__is_upgrade `is_upgrade`] may be used.
- Once the caller determines that the HTTP request is a WebSocket Upgrade,
- additional overloads of
- [link beast.ref.boost__beast__websocket__stream.accept `accept`] and
- [link beast.ref.boost__beast__websocket__stream.async_accept `async_accept`]
- are provided which receive the entire HTTP request header as an object
- to perform the handshake. By reading the request manually, the program
- can handle normal HTTP requests as well as upgrades. The program may
- also enforce policies based on the HTTP fields, such as Basic
- Authentication. In this example, the request is first read in
- using the HTTP algorithms, and then passed to a newly constructed
- stream:
- [code_websocket_2_5]
- [/-----------------------------------------------------------------------------]
- [endsect]
|