forked from boostorg/beast
Documentation work
This commit is contained in:
1 parent
d4ec693a61
commit
9d5d4d56a4
46 files changed
+1264
-153
No files matched your search
@@ -0,0 +1,116 @@
|
||||
[/
|
||||
Copyright (c) 2013-2017 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)
|
||||
]
|
||||
|
||||
[section:server Handshaking (Servers)]
|
||||
|
||||
A
|
||||
[link beast.ref.websocket__stream `stream`]
|
||||
automatically handles receiving and processing the HTTP response to the
|
||||
handshake request. The call to handshake is successful if a HTTP response
|
||||
is received with the 101 "Switching Protocols" status code. On failure,
|
||||
an error is returned or an exception is thrown. Depending on the keep alive
|
||||
setting, the connection may remain open for a subsequent handshake attempt.
|
||||
|
||||
Performing a handshake for an incoming websocket upgrade request operates
|
||||
similarly. If the handshake fails, an error is returned or exception thrown:
|
||||
|
||||
[ws_snippet_11]
|
||||
|
||||
Successful WebSocket Upgrade responses generated by the implementation will
|
||||
typically look like this:
|
||||
|
||||
[table Decorated WebSocket Upgrade HTTP Request
|
||||
[[Serialized Octets][Description]]
|
||||
[[
|
||||
```
|
||||
HTTP/1.1 101 Switching Protocols
|
||||
Upgrade: websocket
|
||||
Connection: upgrade
|
||||
Sec-WebSocket-Accept: s3pPLMBiTxaQ9kYGzzhZRbK+xOo=
|
||||
Server: Beast/40
|
||||
```
|
||||
][
|
||||
The Sec-WebSocket-Accept field value is generated from the
|
||||
request in a fashion specified by the WebSocket protocol.
|
||||
]]]
|
||||
|
||||
[heading Decorators]
|
||||
|
||||
If the caller wishes to add or modify fields, the member functions
|
||||
[link beast.ref.websocket__stream.accept_ex `accept_ex`] and
|
||||
[link beast.ref.websocket__stream.async_accept_ex `async_accept_ex`]
|
||||
are provided which allow an additional function object, called a
|
||||
['decorator], to be passed. The decorator is invoked to modify
|
||||
the HTTP Upgrade request as needed. This example sets the Server
|
||||
field on the response:
|
||||
|
||||
[ws_snippet_12]
|
||||
|
||||
The HTTP Upgrade response produced by the previous call looks like this:
|
||||
|
||||
[table Decorated WebSocket Upgrade HTTP Request
|
||||
[[Serialized Octets][Description]]
|
||||
[[
|
||||
```
|
||||
HTTP/1.1 101 Switching Protocols
|
||||
Upgrade: websocket
|
||||
Connection: upgrade
|
||||
Sec-WebSocket-Accept: s3pPLMBiTxaQ9kYGzzhZRbK+xOo=
|
||||
Server: AcmeServer
|
||||
```
|
||||
][
|
||||
When the Upgrade request fails, the implementation will still invoke
|
||||
the decorator to modify the response. In this case, the response
|
||||
object will have a status code other than 101.
|
||||
|
||||
Undefined behavior results when the upgrade request is successful
|
||||
and the decorator modifies the fields specific to perform the
|
||||
WebSocket Upgrade, such as the Upgrade and Connection fields.
|
||||
]]]
|
||||
|
||||
[heading Passing 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.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.websocket__stream.accept `accept`],
|
||||
[link beast.ref.websocket__stream.accept_ex `accept_ex`],
|
||||
[link beast.ref.websocket__stream.async_accept `async_accept`], and
|
||||
[link beast.ref.websocket__stream.async_accept_ex `async_accept_ex`]
|
||||
are provided which receive the entire HTTP request header as an object
|
||||
to perform the handshake. In this example, the request is first read
|
||||
in using the HTTP algorithms, and then passed to a newly constructed
|
||||
stream:
|
||||
|
||||
[ws_snippet_13]
|
||||
|
||||
[heading Buffered Handshakes]
|
||||
|
||||
Sometimes a server implementation wishes to read octets on the stream
|
||||
in order to route the incoming request. For example, a server may read
|
||||
the first 6 octets after accepting an incoming connection to determine
|
||||
if a TLS protocol is being negotiated, and choose a suitable implementation
|
||||
at run-time. In the case where the server wishes to accept the incoming
|
||||
request as an HTTP WebSocket Upgrade request, additional overloads of
|
||||
[link beast.ref.websocket__stream.accept `accept`],
|
||||
[link beast.ref.websocket__stream.accept_ex `accept_ex`],
|
||||
[link beast.ref.websocket__stream.async_accept `async_accept`], and
|
||||
[link beast.ref.websocket__stream.async_accept_ex `async_accept_ex`]
|
||||
are provided which receive the additional buffered octets and consume
|
||||
them as part of the handshake.
|
||||
|
||||
In this example, the server reads the initial HTTP message into the
|
||||
specified dynamic buffer as an octet sequence in the buffer's output
|
||||
area, and later uses those octets to attempt an HTTP WebSocket Upgrade:
|
||||
|
||||
[ws_snippet_14]
|
||||
|
||||
[endsect]
|
||||
Reference in new issue
Block a user