mirror of
https://github.com/XRPLF/rippled.git
synced 2025-11-20 11:05:54 +00:00
beast doc/test work
This commit is contained in:
3
TODO.txt
3
TODO.txt
@@ -19,4 +19,5 @@
|
||||
* trim public interface of rfc2616.h to essentials only
|
||||
* Use new http routines in JSONRPCClient
|
||||
* Remove or change http::headers alias
|
||||
|
||||
* Do something about the methods.hpp and fields.hpp type headers
|
||||
* Fix index in docs
|
||||
|
||||
@@ -103,43 +103,51 @@ WARN_LOGFILE =
|
||||
# Configuration options related to the input files
|
||||
#---------------------------------------------------------------------------
|
||||
INPUT = \
|
||||
../beast/asio/append_buffers.h \
|
||||
../beast/asio/async_completion.h \
|
||||
../beast/asio/basic_streambuf.h \
|
||||
../beast/asio/bind_handler.h \
|
||||
../beast/asio/buffers_adapter.h \
|
||||
../beast/asio/consuming_buffers.h \
|
||||
../beast/asio/handler_alloc.h \
|
||||
../beast/asio/prepare_buffers.h \
|
||||
../beast/asio/static_streambuf.h \
|
||||
../beast/asio/streambuf.h \
|
||||
../beast/asio/streambuf_readstream.h \
|
||||
../beast/asio/type_check.h \
|
||||
../beast/http/basic_headers.h \
|
||||
../beast/http/basic_parser.h \
|
||||
../beast/http/chunk_encode.h \
|
||||
../beast/http/empty_body.h \
|
||||
../beast/http/error.h \
|
||||
../beast/http/message.h \
|
||||
../beast/http/parser.h \
|
||||
../beast/http/read.h \
|
||||
../beast/http/resume_context.h \
|
||||
../beast/http/stream.h \
|
||||
../beast/http/streambuf_body.h \
|
||||
../beast/http/string_body.h \
|
||||
../beast/http/type_check.h \
|
||||
../beast/http/write.h \
|
||||
../beast/wsproto/error.h \
|
||||
../beast/wsproto/option.h \
|
||||
../beast/wsproto/rfc6455.h \
|
||||
../beast/wsproto/socket.h \
|
||||
../beast/wsproto/static_string.h \
|
||||
../beast/wsproto/teardown.h \
|
||||
../include/beast/async_completion.hpp \
|
||||
../include/beast/basic_streambuf.hpp \
|
||||
../include/beast/bind_handler.hpp \
|
||||
../include/beast/buffer_cat.hpp \
|
||||
../include/beast/buffers_adapter.hpp \
|
||||
../include/beast/buffers_debug.hpp \
|
||||
../include/beast/consuming_buffers.hpp \
|
||||
../include/beast/handler_alloc.hpp \
|
||||
../include/beast/http.hpp \
|
||||
../include/beast/placeholders.hpp \
|
||||
../include/beast/prepare_buffers.hpp \
|
||||
../include/beast/static_streambuf.hpp \
|
||||
../include/beast/streambuf.hpp \
|
||||
../include/beast/streambuf_readstream.hpp \
|
||||
../include/beast/type_check.hpp \
|
||||
../include/beast/websocket.hpp \
|
||||
../include/beast/http/basic_headers.hpp \
|
||||
../include/beast/http/basic_parser.hpp \
|
||||
../include/beast/http/chunk_encode.hpp \
|
||||
../include/beast/http/empty_body.hpp \
|
||||
../include/beast/http/error.hpp \
|
||||
../include/beast/http/fields.hpp \
|
||||
../include/beast/http/headers.hpp \
|
||||
../include/beast/http/message.hpp \
|
||||
../include/beast/http/method.hpp \
|
||||
../include/beast/http/parser.hpp \
|
||||
../include/beast/http/read.hpp \
|
||||
../include/beast/http/resume_context.hpp \
|
||||
../include/beast/http/rfc2616.hpp \
|
||||
../include/beast/http/streambuf_body.hpp \
|
||||
../include/beast/http/string_body.hpp \
|
||||
../include/beast/http/type_check.hpp \
|
||||
../include/beast/http/write.hpp \
|
||||
../include/beast/websocket/error.hpp \
|
||||
../include/beast/websocket/option.hpp \
|
||||
../include/beast/websocket/rfc6455.hpp \
|
||||
../include/beast/websocket/ssl.hpp \
|
||||
../include/beast/websocket/static_string.hpp \
|
||||
../include/beast/websocket/stream.hpp \
|
||||
../include/beast/websocket/teardown.hpp \
|
||||
|
||||
INPUT_ENCODING = UTF-8
|
||||
FILE_PATTERNS =
|
||||
RECURSIVE = NO
|
||||
EXCLUDE = ../beast/http/URL.h
|
||||
EXCLUDE =
|
||||
EXCLUDE_SYMLINKS = NO
|
||||
EXCLUDE_PATTERNS =
|
||||
EXCLUDE_SYMBOLS =
|
||||
|
||||
@@ -42,7 +42,7 @@
|
||||
|
||||
Beast is a cross-platform C++ library built on Boost, containing two modules
|
||||
implementing widely used network protocols. Beast.HTTP offers a universal
|
||||
model for describing, sending, and receiving HTTP messages while Beast.WSProto
|
||||
model for describing, sending, and receiving HTTP messages while Beast.WebSocket
|
||||
provides a complete implementation of the WebSocket protocol. Their design
|
||||
achieves these goals:
|
||||
|
||||
@@ -97,12 +97,11 @@ flavor of the library.
|
||||
All examples and identifiers mentioned in this document are written as
|
||||
if the following statements are in effect:
|
||||
```
|
||||
#include <beast/http.h>
|
||||
#include <beast/wsproto.h>
|
||||
#include <boost/asio.hpp>
|
||||
#include <beast/http.hpp>
|
||||
#include <beast/websocket.hpp>
|
||||
using namespace beast;
|
||||
using namespace beast::http;
|
||||
using namespace boost::asio;
|
||||
using namespace boost::asio::ip;
|
||||
```
|
||||
]
|
||||
|
||||
@@ -110,16 +109,16 @@ Use HTTP to request the root page from a website and receive the response:
|
||||
```
|
||||
std::string const host = "boost.org";
|
||||
io_service ios;
|
||||
tcp::resolver r(ios);
|
||||
tcp::socket sock(ios);
|
||||
connect(sock, r.resolve(tcp::resolver::query{host, "http"}));
|
||||
ip::tcp::resolver r(ios);
|
||||
ip::tcp::socket sock(ios);
|
||||
connect(sock, r.resolve(ip::tcp::resolver::query{host, "http"}));
|
||||
|
||||
request<empty_body> req(method_t::http_get, "/", 11);
|
||||
http::request<http::empty_body> req(http::method_t::http_get, "/", 11);
|
||||
req.headers.replace("Host", host + ":" + std::to_string(sock.remote_endpoint().port()));
|
||||
req.headers.replace("User-Agent", "Beast");
|
||||
write(sock, prepare(req, connection(close)));
|
||||
write(sock, req);
|
||||
|
||||
parsed_response<streambuf_body> resp;
|
||||
http::response<http::streambuf_body> resp;
|
||||
read(sock, resp);
|
||||
...
|
||||
```
|
||||
@@ -132,12 +131,12 @@ Establish a WebSocket connection, send a message and receive the reply:
|
||||
tcp::socket sock(ios);
|
||||
connect(sock, r.resolve(tcp::resolver::query{host, "ws"}));
|
||||
|
||||
wsproto::socket<tcp::socket&> ws(sock);
|
||||
websocket::stream<ip::tcp::socket&> ws(sock);
|
||||
ws.handshake();
|
||||
ws.write(ws, buffer("Hello, world!"));
|
||||
|
||||
streambuf sb;
|
||||
wsproto::opcode op;
|
||||
websocket::opcode op;
|
||||
ws.read(ws, op, sb);
|
||||
|
||||
ws.close(); // WebSocket protocol close
|
||||
@@ -165,7 +164,7 @@ documentation is based.
|
||||
|
||||
|
||||
[include http.qbk]
|
||||
[include wsproto.qbk]
|
||||
[include websocket.qbk]
|
||||
[include types.qbk]
|
||||
[include design.qbk]
|
||||
[section:quickref Quick Reference]
|
||||
|
||||
39
doc/http.qbk
39
doc/http.qbk
@@ -46,48 +46,45 @@ both Boost.Asio and the HTTP protocol specification described in
|
||||
All examples and identifiers mentioned in this document are written as
|
||||
if the following declarations are in effect:
|
||||
```
|
||||
#include <beast/http.h>
|
||||
using namespace beast::http;
|
||||
#include <boost/asio.hpp>
|
||||
#include <beast/http.hpp>
|
||||
using namespace beast;
|
||||
using namespace boost::asio;
|
||||
```
|
||||
|
||||
Create a HTTP request:
|
||||
```
|
||||
request<string_body> req({method_t::http_get, "/", 11});
|
||||
http::request<http::empty_body> req({http::method_t::http_get, "/", 11});
|
||||
req.headers.insert("Host", "127.0.0.1:80");
|
||||
req.headers.insert("User-Agent", "Beast.HTTP");
|
||||
|
||||
```
|
||||
|
||||
To send a message it must first be prepared through a call to `prepare`. This
|
||||
customization point transforms the `message` into a `prepared_message`,
|
||||
filling in some standard HTTP behavior and allowing the Body associated with
|
||||
the message to perform preparatory steps. For example, a string body may set
|
||||
the Content-Length and Content-Type appropriately.
|
||||
When sending a message, the Content-Length and Transfer-Encoding are set
|
||||
automatically based on the properties of the body. Depending on the HTTP
|
||||
version of the message and properties of the message body, the implementation
|
||||
will automaticaly chunk-encode the data sent on the wire:
|
||||
```
|
||||
void send_request(ip::tcp::socket& sock,
|
||||
request<string_body>&& req)
|
||||
{
|
||||
// Send the request on the socket
|
||||
write(sock, prepare(req, connection(keep_alive));
|
||||
ip::tcp::socket sock(ios);
|
||||
...
|
||||
http::response<http::string_body> resp({200, "OK", 11});
|
||||
resp.headers.insert("Server", "Beast.HTTP");
|
||||
resp.body = "The command was successful";
|
||||
|
||||
write(sock, resp);
|
||||
}
|
||||
```
|
||||
|
||||
Messages can be read from the network and parsed into a `parsed_message` object,
|
||||
which extends the `message` by adding parse-specific metadata such as the
|
||||
keep-alive which is context sensitive (depending on the HTTP version for
|
||||
example). When preparing a response for sending, `prepare` must be called with
|
||||
an additional parameter, the corresponding parsed request. The implementation
|
||||
inspects the contents of the request to set dependent fields of the response.
|
||||
Receiving a message is simple, declare a value of type message and call `read`.
|
||||
This example reads a message, builds a response, and sends it.
|
||||
```
|
||||
void handle_connection(ip::tcp::socket& sock)
|
||||
{
|
||||
parsed_request<string_body> req;
|
||||
request<string_body> req;
|
||||
read(sock, req);
|
||||
response<string_body> resp;
|
||||
...
|
||||
write(sock, prepare(resp, req));
|
||||
write(sock, resp);
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
@@ -36,7 +36,6 @@
|
||||
<member><link linkend="beast.ref.http__error_code">error_code</link></member>
|
||||
<member><link linkend="beast.ref.http__message">message</link></member>
|
||||
<member><link linkend="beast.ref.http__resume_context">resume_context</link></member>
|
||||
<member><link linkend="beast.ref.http__stream">stream</link></member>
|
||||
<member><link linkend="beast.ref.http__streambuf_body">streambuf_body</link></member>
|
||||
<member><link linkend="beast.ref.http__string_body">string_body</link></member>
|
||||
</simplelist>
|
||||
@@ -67,30 +66,30 @@
|
||||
<entry valign="top">
|
||||
<bridgehead renderas="sect3">Classes</bridgehead>
|
||||
<simplelist type="vert" columns="1">
|
||||
<member><link linkend="beast.ref.wsproto__close_reason">close_reason</link></member>
|
||||
<member><link linkend="beast.ref.wsproto__socket">socket</link></member>
|
||||
<member><link linkend="beast.ref.wsproto__static_string">static_string</link></member>
|
||||
<member><link linkend="beast.ref.websocket__close_reason">close_reason</link></member>
|
||||
<member><link linkend="beast.ref.websocket__static_string">static_string</link></member>
|
||||
<member><link linkend="beast.ref.websocket__stream">stream</link></member>
|
||||
</simplelist>
|
||||
<bridgehead renderas="sect3">Options</bridgehead>
|
||||
<simplelist type="vert" columns="1">
|
||||
<member><link linkend="beast.ref.wsproto__auto_fragment_size">auto_fragment_size</link></member>
|
||||
<member><link linkend="beast.ref.wsproto__decorate">decorate</link></member>
|
||||
<member><link linkend="beast.ref.wsproto__keep_alive">keep_alive</link></member>
|
||||
<member><link linkend="beast.ref.wsproto__read_buffer_size">read_buffer_size</link></member>
|
||||
<member><link linkend="beast.ref.wsproto__read_message_max">read_message_max</link></member>
|
||||
<member><link linkend="beast.ref.wsproto__write_buffer_size">write_buffer_size</link></member>
|
||||
<member><link linkend="beast.ref.websocket__auto_fragment_size">auto_fragment_size</link></member>
|
||||
<member><link linkend="beast.ref.websocket__decorate">decorate</link></member>
|
||||
<member><link linkend="beast.ref.websocket__keep_alive">keep_alive</link></member>
|
||||
<member><link linkend="beast.ref.websocket__read_buffer_size">read_buffer_size</link></member>
|
||||
<member><link linkend="beast.ref.websocket__read_message_max">read_message_max</link></member>
|
||||
<member><link linkend="beast.ref.websocket__write_buffer_size">write_buffer_size</link></member>
|
||||
</simplelist>
|
||||
</entry>
|
||||
<entry valign="top">
|
||||
<bridgehead renderas="sect3">Functions</bridgehead>
|
||||
<simplelist type="vert" columns="1">
|
||||
<member><link linkend="beast.ref.wsproto__async_teardown">async_teardown</link></member>
|
||||
<member><link linkend="beast.ref.wsproto__teardown">teardown</link></member>
|
||||
<member><link linkend="beast.ref.websocket__async_teardown">async_teardown</link></member>
|
||||
<member><link linkend="beast.ref.websocket__teardown">teardown</link></member>
|
||||
</simplelist>
|
||||
<bridgehead renderas="sect3">Constants</bridgehead>
|
||||
<simplelist type="vert" columns="1">
|
||||
<member><link linkend="beast.ref.wsproto__close_code">close_code</link></member>
|
||||
<member><link linkend="beast.ref.wsproto__opcode">opcode</link></member>
|
||||
<member><link linkend="beast.ref.websocket__close_code">close_code</link></member>
|
||||
<member><link linkend="beast.ref.websocket__opcode">opcode</link></member>
|
||||
</simplelist>
|
||||
</entry>
|
||||
</row>
|
||||
@@ -128,8 +127,8 @@
|
||||
<entry valign="top">
|
||||
<bridgehead renderas="sect3">Functions</bridgehead>
|
||||
<simplelist type="vert" columns="1">
|
||||
<member><link linkend="beast.ref.append_buffers">append_buffers</link></member>
|
||||
<member><link linkend="beast.ref.bind_handler">bind_handler</link></member>
|
||||
<member><link linkend="beast.ref.buffer_cat">buffer_cat</link></member>
|
||||
<member><link linkend="beast.ref.prepare_buffer">prepare_buffer</link></member>
|
||||
<member><link linkend="beast.ref.prepare_buffers">prepare_buffers</link></member>
|
||||
</simplelist>
|
||||
|
||||
@@ -5,7 +5,7 @@
|
||||
file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
|
||||
]
|
||||
|
||||
[section:wsproto WSProto]
|
||||
[section:websocket WebSocket]
|
||||
|
||||
The WebSocket Protocol enables two-way communication between a client
|
||||
running untrusted code in a controlled environment to a remote host that has
|
||||
@@ -15,7 +15,7 @@ this technology is to provide a mechanism for browser-based applications that
|
||||
need two-way communication with servers that does not rely on opening multiple
|
||||
HTTP connections.
|
||||
|
||||
Beast.WSProto provides developers with a robust WebSocket implementation
|
||||
Beast.WebSocket provides developers with a robust WebSocket implementation
|
||||
built on Boost.Asio with a consistent asynchronous model using a modern
|
||||
C++ approach.
|
||||
|
||||
@@ -33,17 +33,17 @@ good implementations in C++ are scarce. A survey of existing C++ WebSocket
|
||||
solutions reveals interfaces which lack symmetry, impose performance penalties,
|
||||
and needlessly restrict implementation strategies.
|
||||
|
||||
Beast.WSProto is built on Boost.Asio, a robust cross platform networking
|
||||
Beast.WebSocket is built on Boost.Asio, a robust cross platform networking
|
||||
framework that is part of Boost and also offered as a standalone library.
|
||||
A proposal to add networking functionality to the C++ standard library,
|
||||
based on Boost.Asio, is under consideration by the standards committee.
|
||||
Since the final approved networking interface for the C++ standard library
|
||||
will likely closely resemble the current interface of Boost.Asio, it is
|
||||
logical for Beast.WSProto to use Boost.Asio as its network transport.
|
||||
logical for Beast.WebSocket to use Boost.Asio as its network transport.
|
||||
|
||||
Beast.WSProto takes advantage of Boost.Asio's extensible asynchronous
|
||||
Beast.WebSocket takes advantage of Boost.Asio's extensible asynchronous
|
||||
model, handler allocation, and handler invocation hooks. Calls to
|
||||
Beast.WSProto asynchronous initiation functions allow callers the choice
|
||||
Beast.WebSocket asynchronous initiation functions allow callers the choice
|
||||
of using a completion handler, stackful or stackless coroutines, futures,
|
||||
or user defined customizations (for example, Boost.Fiber). The
|
||||
implementation uses handler invocation hooks (`asio_handler_invoke`),
|
||||
@@ -52,7 +52,7 @@ identical to Boost.Asio. The implementation also uses handler allocation
|
||||
hooks (`asio_handler_allocate`) when allocating memory internally for
|
||||
composed operations.
|
||||
|
||||
There is no need for inheritance or virtual members in `wsproto::socket`.
|
||||
There is no need for inheritance or virtual members in `websocket::stream`.
|
||||
All operations are templated and transparent to the compiler, allowing for
|
||||
maximum inlining and optimization.
|
||||
|
||||
@@ -67,25 +67,27 @@ both Boost.Asio and the WebSocket protocol specification described in
|
||||
[section:creating Creating the socket]
|
||||
|
||||
The interface to Beast's WebSocket implementation is a single template
|
||||
class which wraps an object meeting the requirements of `SyncStream` if
|
||||
synchronous operations are performed, `AsyncStream` if asynchronous
|
||||
operations are performed, or both. Arguments supplied during construction
|
||||
are passed to the `Stream` constructor. Here we declare two websockets
|
||||
which contain the underlying stream:
|
||||
class [link beast.ref.websocket__stream `websocket::stream`] which wraps a
|
||||
"next layer" object. The next layer object must meet the requirements of
|
||||
`SyncReadStream` and `SyncWriteStream` if synchronous operations are performed,
|
||||
`AsyncReadStream` and `AsyncWriteStream` is asynchronous operations are
|
||||
performed, or both. Arguments supplied during construction are passed to
|
||||
next layer's constructor. Here we declare two websockets which have ownership
|
||||
of the next layer:
|
||||
```
|
||||
io_service ios;
|
||||
wsproto::socket<tcp::socket> ws(ios);
|
||||
websocket::stream<ip::tcp::socket> ws(ios);
|
||||
|
||||
ssl::context ctx(ssl::context::sslv23);
|
||||
wsproto::socket<ssl::stream<tcp::socket>> wss(ios, ctx);
|
||||
websocket::stream<ssl::stream<ip::tcp::socket>> wss(ios, ctx);
|
||||
```
|
||||
|
||||
For servers that can handshake in multiple protocols, it may be desired
|
||||
to wrap a socket that already exists. The socket can be moved in:
|
||||
to wrap an object that already exists. This socket can be moved in:
|
||||
```
|
||||
tcp::socket&& sock;
|
||||
...
|
||||
wsproto::socket<tcp::socket> ws(std::move(sock));
|
||||
websocket::stream<ip::tcp::socket> ws(std::move(sock));
|
||||
```
|
||||
|
||||
Or, the wrapper can be constructed with a non-owning reference. In
|
||||
@@ -94,14 +96,14 @@ underlying socket being wrapped:
|
||||
```
|
||||
tcp::socket sock;
|
||||
...
|
||||
wsproto::socket<tcp::socket&> ws(sock);
|
||||
websocket::stream<ip::tcp::socket&> ws(sock);
|
||||
```
|
||||
|
||||
The stream being wrapped can be accessed through the websocket's "next layer",
|
||||
The layer being wrapped can be accessed through the websocket's "next layer",
|
||||
permitting callers to interact directly with its interface.
|
||||
```
|
||||
ssl::context ctx(ssl::context::sslv23);
|
||||
wsproto::socket<ssl::stream<tcp::socket>> ws(ios, ctx);
|
||||
websocket::stream<ssl::stream<ip::tcp::socket>> ws(ios, ctx);
|
||||
...
|
||||
ws.next_layer().shutdown(); // ssl::stream shutdown
|
||||
```
|
||||
@@ -116,13 +118,13 @@ result in undefined behavior. ]
|
||||
|
||||
[section:connecting Making connections]
|
||||
|
||||
Connections are established by using the interfaces which already exist for
|
||||
the wrapped stream. For example, making an outgoing connection:
|
||||
Connections are established by using the interfaces which already exist
|
||||
for the next layer. For example, making an outgoing connection:
|
||||
```
|
||||
std::string const host = "mywebapp.com";
|
||||
io_service ios;
|
||||
tcp::resolver r(ios);
|
||||
wsproto::socket<tcp::socket> ws(ios);
|
||||
websocket::stream<ip::tcp::socket> ws(ios);
|
||||
connect(ws.next_layer(), r.resolve(tcp::resolver::query{host, "ws"}));
|
||||
```
|
||||
|
||||
@@ -130,7 +132,7 @@ Accepting an incoming connection:
|
||||
```
|
||||
void do_accept(tcp::acceptor& acceptor)
|
||||
{
|
||||
wsproto::socket<tcp::socket> ws(acceptor.get_io_service());
|
||||
websocket::stream<ip::tcp::socket> ws(acceptor.get_io_service());
|
||||
acceptor.accept(ws.next_layer());
|
||||
}
|
||||
```
|
||||
@@ -147,16 +149,16 @@ A WebSocket session begins when one side sends the HTTP Upgrade request
|
||||
for websocket, and the other side sends an appropriate HTTP response
|
||||
indicating that the request was accepted and that the connection has
|
||||
been upgraded. The HTTP Upgrade request must include the Host HTTP field,
|
||||
and the URI of the resource to request. `wsproto::socket::hanshake` is
|
||||
used to send the request with the required host and resource strings.
|
||||
and the URI of the resource to request. `hanshake` is used to send the
|
||||
request with the required host and resource strings.
|
||||
```
|
||||
wsproto::socket<tcp::socket> ws(ios);
|
||||
websocket::stream<ip::tcp::socket> ws(ios);
|
||||
...
|
||||
ws.set_option(wsproto::keep_alive(true));
|
||||
ws.set_option(websocket::keep_alive(true));
|
||||
ws.handshake("ws.mywebapp.com:80", "/cgi-bin/bitcoin-prices");
|
||||
```
|
||||
|
||||
The `wsproto::socket` automatically handles receiving and processing
|
||||
The `websocket::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.
|
||||
@@ -166,7 +168,7 @@ 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:
|
||||
```
|
||||
wsproto::socket<tcp::socket> ws(ios);
|
||||
websocket::stream<ip::tcp::socket> ws(ios);
|
||||
...
|
||||
ws.accept();
|
||||
```
|
||||
@@ -181,7 +183,7 @@ void do_accept(tcp::socket& sock)
|
||||
boost::asio::streambuf sb;
|
||||
read_until(sock, sb, "\r\n\r\n");
|
||||
...
|
||||
wsproto::socket<tcp::socket&> ws(sock);
|
||||
websocket::stream<ip::tcp::socket&> ws(sock);
|
||||
ws.accept(sb.data());
|
||||
...
|
||||
}
|
||||
@@ -193,13 +195,15 @@ obtained elsewhere:
|
||||
void do_accept(tcp::socket& sock)
|
||||
{
|
||||
boost::asio::streambuf sb;
|
||||
http::parsed_request<http::empty_body> request;
|
||||
http::request<http::empty_body> request;
|
||||
http::read(sock, request);
|
||||
...
|
||||
wsproto::socket<tcp::socket&> ws(sock);
|
||||
if(http::is_upgrade(request))
|
||||
{
|
||||
websocket::stream<ip::tcp::socket&> ws(sock);
|
||||
ws.accept(request);
|
||||
...
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
[note Identifiers in the `http` namespace are part of Beast.HTTP. ]
|
||||
@@ -214,20 +218,20 @@ After the WebSocket handshake is accomplished, callers may send and receive
|
||||
messages using the message oriented interface. This interface requires that
|
||||
all of the buffers representing the message are known ahead of time:
|
||||
```
|
||||
void echo(wsproto::socket<ip::tcp::socket>& ws)
|
||||
void echo(websocket::stream<ip::tcp::socket>& ws)
|
||||
{
|
||||
streambuf sb;
|
||||
wsproto::opcode::value op;
|
||||
websocket::opcode::value op;
|
||||
ws.read(sb);
|
||||
|
||||
ws.set_option(wsproto::message_type(op));
|
||||
wsproto::write(ws, sb.data());
|
||||
ws.set_option(websocket::message_type(op));
|
||||
websocket::write(ws, sb.data());
|
||||
sb.consume(sb.size());
|
||||
}
|
||||
```
|
||||
|
||||
[important Calls to `wsproto::socket::set_option` must be made from the same
|
||||
implicit or explicit strand as that used to perform other operations. ]
|
||||
[important Calls to `set_option` must be made from the same implicit
|
||||
or explicit strand as that used to perform other operations. ]
|
||||
|
||||
[endsect]
|
||||
|
||||
@@ -245,18 +249,18 @@ message ahead of time:
|
||||
For these cases, the frame oriented interface may be used. This
|
||||
example reads and echoes a complete message using this interface:
|
||||
```
|
||||
void echo(wsproto::socket<ip::tcp::socket>& ws)
|
||||
void echo(websocket::stream<ip::tcp::socket>& ws)
|
||||
{
|
||||
beast::streambuf sb;
|
||||
wsproto::frame_info fi;
|
||||
streambuf sb;
|
||||
websocket::frame_info fi;
|
||||
for(;;)
|
||||
{
|
||||
ws.read_frame(fi, sb);
|
||||
if(fi.fin)
|
||||
break;
|
||||
}
|
||||
ws.set_option(wsproto::message_type(fi.op));
|
||||
beast::consuming_buffers<streambuf::const_buffers_type> cb(sb.data());
|
||||
ws.set_option(websocket::message_type(fi.op));
|
||||
consuming_buffers<streambuf::const_buffers_type> cb(sb.data());
|
||||
for(;;)
|
||||
{
|
||||
using boost::asio::buffer_size;
|
||||
@@ -285,7 +289,7 @@ During read operations, the implementation automatically reads and processes
|
||||
WebSocket control frames such as ping, pong, and close. Pings are replied
|
||||
to as soon as possible, pongs are noted. The receipt of a close frame
|
||||
initiates the WebSocket close procedure, eventually resulting in the
|
||||
error code `wsproto::error::closed` being delivered to the caller in
|
||||
error code `websocket::error::closed` being delivered to the caller in
|
||||
a subsequent read operation, assuming no other error takes place.
|
||||
|
||||
To ensure timely delivery of control frames, large messages are broken up
|
||||
@@ -294,18 +298,18 @@ of the frames making up the message. The automatic fragment size option
|
||||
gives callers control over the size of these frames:
|
||||
```
|
||||
...
|
||||
ws.set_option(wsproto::auto_fragment_size(8192));
|
||||
ws.set_option(websocket::auto_fragment_size(8192));
|
||||
```
|
||||
|
||||
The WebSocket protocol defines a procedure and control message for initiating
|
||||
a close of the session. Handling of close initiated by the remote end of the
|
||||
connection is performed automatically. To manually initiate a close, use
|
||||
`wsproto::socket::close`:
|
||||
`websocket::stream::close`:
|
||||
```
|
||||
ws.close();
|
||||
```
|
||||
|
||||
[note To receive the `wsproto::error::closed` error, a read operation
|
||||
[note To receive the `websocket::error::closed` error, a read operation
|
||||
is required. ]
|
||||
|
||||
[endsect]
|
||||
@@ -331,7 +335,7 @@ of the underlying TCP/IP connection.
|
||||
|
||||
Asynchronous versions are available for all functions:
|
||||
```
|
||||
wsproto::opcode op;
|
||||
websocket::opcode op;
|
||||
ws.async_read(op, sb,
|
||||
[](boost::system::error_code const& ec)
|
||||
{
|
||||
@@ -343,11 +347,11 @@ Calls to asynchronous initiation functions support the extensible asynchronous
|
||||
model developed by the Boost.Asio author, allowing for traditional completion
|
||||
handlers, stackful or stackless coroutines, and even futures:
|
||||
```
|
||||
void echo(wsproto::socket<ip::tcp::socket>& ws,
|
||||
void echo(websocket::stream<ip::tcp::socket>& ws,
|
||||
boost::asio::yield_context yield)
|
||||
{
|
||||
ws.async_read(sb, yield);
|
||||
std::future<wsproto::error_code> fut =
|
||||
std::future<websocket::error_code> fut =
|
||||
ws.async_write, sb.data(), boost::use_future);
|
||||
...
|
||||
}
|
||||
@@ -370,7 +374,7 @@ threads are unavailable. Beast.WSProto itself does not use or require threads.
|
||||
|
||||
[section:safety Thread Safety]
|
||||
|
||||
Like a regular asio socket, a `wsproto::socket` is not thread safe. Callers
|
||||
Like a regular asio socket, a `websocket::stream` is not thread safe. Callers
|
||||
are responsible for synchronizing operations on the socket using an implicit
|
||||
or explicit strand, as per the Asio documentation. The asynchronous interface
|
||||
supports one active read and one active write simultaneously. Undefined
|
||||
34
test/Jamfile
34
test/Jamfile
@@ -7,27 +7,45 @@
|
||||
|
||||
import os ;
|
||||
|
||||
unit-test all :
|
||||
unit-test http_tests :
|
||||
main.cpp
|
||||
../src/beast_http_nodejs_parser.cpp
|
||||
http/basic_headers.cpp
|
||||
http/basic_parser.cpp
|
||||
http/chunk_encode.cpp
|
||||
http/empty_body.cpp
|
||||
http/error.cpp
|
||||
http/fields.cpp
|
||||
http/headers.cpp
|
||||
http/message.cpp
|
||||
http/method.cpp
|
||||
http/parser.cpp
|
||||
http/read.cpp
|
||||
http/reason.cpp
|
||||
http/resume_context.cpp
|
||||
http/rfc2616.cpp
|
||||
http/streambuf_body.cpp
|
||||
http/string_body.cpp
|
||||
http/type_check.cpp
|
||||
http/write.cpp
|
||||
;
|
||||
|
||||
unit-test core_tests :
|
||||
main.cpp
|
||||
async_completion.cpp
|
||||
base64.cpp
|
||||
basic_streambuf.cpp
|
||||
basic_headers.cpp
|
||||
bind_handler.cpp
|
||||
buffer_cat.cpp
|
||||
buffers_adapter.cpp
|
||||
buffers_debug.cpp
|
||||
chunk_encode.cpp
|
||||
consuming_buffers.cpp
|
||||
empty_base_optimization.cpp
|
||||
handler_alloc.cpp
|
||||
message.cpp
|
||||
placeholders.cpp
|
||||
prepare_buffers.cpp
|
||||
rfc2616.cpp
|
||||
static_streambuf.cpp
|
||||
streambuf.cpp
|
||||
streambuf_readstream.cpp
|
||||
type_check.cpp
|
||||
main.cpp
|
||||
detail/base64.cpp
|
||||
detail/empty_base_optimization.cpp
|
||||
;
|
||||
|
||||
9
test/http/basic_parser.cpp
Normal file
9
test/http/basic_parser.cpp
Normal file
@@ -0,0 +1,9 @@
|
||||
//
|
||||
// Copyright (c) 2013-2016 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)
|
||||
//
|
||||
|
||||
// Test that header file is self-contained.
|
||||
#include <beast/http/basic_parser.hpp>
|
||||
9
test/http/empty_body.cpp
Normal file
9
test/http/empty_body.cpp
Normal file
@@ -0,0 +1,9 @@
|
||||
//
|
||||
// Copyright (c) 2013-2016 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)
|
||||
//
|
||||
|
||||
// Test that header file is self-contained.
|
||||
#include <beast/http/empty_body.hpp>
|
||||
9
test/http/error.cpp
Normal file
9
test/http/error.cpp
Normal file
@@ -0,0 +1,9 @@
|
||||
//
|
||||
// Copyright (c) 2013-2016 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)
|
||||
//
|
||||
|
||||
// Test that header file is self-contained.
|
||||
#include <beast/http/error.hpp>
|
||||
9
test/http/fields.cpp
Normal file
9
test/http/fields.cpp
Normal file
@@ -0,0 +1,9 @@
|
||||
//
|
||||
// Copyright (c) 2013-2016 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)
|
||||
//
|
||||
|
||||
// Test that header file is self-contained.
|
||||
#include <beast/http/fields.hpp>
|
||||
9
test/http/headers.cpp
Normal file
9
test/http/headers.cpp
Normal file
@@ -0,0 +1,9 @@
|
||||
//
|
||||
// Copyright (c) 2013-2016 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)
|
||||
//
|
||||
|
||||
// Test that header file is self-contained.
|
||||
#include <beast/http/headers.hpp>
|
||||
9
test/http/method.cpp
Normal file
9
test/http/method.cpp
Normal file
@@ -0,0 +1,9 @@
|
||||
//
|
||||
// Copyright (c) 2013-2016 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)
|
||||
//
|
||||
|
||||
// Test that header file is self-contained.
|
||||
#include <beast/http/method.hpp>
|
||||
9
test/http/parser.cpp
Normal file
9
test/http/parser.cpp
Normal file
@@ -0,0 +1,9 @@
|
||||
//
|
||||
// Copyright (c) 2013-2016 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)
|
||||
//
|
||||
|
||||
// Test that header file is self-contained.
|
||||
#include <beast/http/parser.hpp>
|
||||
9
test/http/read.cpp
Normal file
9
test/http/read.cpp
Normal file
@@ -0,0 +1,9 @@
|
||||
//
|
||||
// Copyright (c) 2013-2016 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)
|
||||
//
|
||||
|
||||
// Test that header file is self-contained.
|
||||
#include <beast/http/read.hpp>
|
||||
9
test/http/reason.cpp
Normal file
9
test/http/reason.cpp
Normal file
@@ -0,0 +1,9 @@
|
||||
//
|
||||
// Copyright (c) 2013-2016 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)
|
||||
//
|
||||
|
||||
// Test that header file is self-contained.
|
||||
#include <beast/http/reason.hpp>
|
||||
9
test/http/resume_context.cpp
Normal file
9
test/http/resume_context.cpp
Normal file
@@ -0,0 +1,9 @@
|
||||
//
|
||||
// Copyright (c) 2013-2016 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)
|
||||
//
|
||||
|
||||
// Test that header file is self-contained.
|
||||
#include <beast/http/resume_context.hpp>
|
||||
@@ -1,23 +1,13 @@
|
||||
//------------------------------------------------------------------------------
|
||||
/*
|
||||
This file is part of Beast: https://github.com/vinniefalco/Beast
|
||||
Copyright 2013, Vinnie Falco <vinnie.falco@gmail.com>
|
||||
|
||||
Permission to use, copy, modify, and/or distribute this software for any
|
||||
purpose with or without fee is hereby granted, provided that the above
|
||||
copyright notice and this permission notice appear in all copies.
|
||||
|
||||
THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
|
||||
WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
|
||||
MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
|
||||
ANY SPECIAL , DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
|
||||
WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
|
||||
ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
|
||||
OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
|
||||
*/
|
||||
//==============================================================================
|
||||
//
|
||||
// Copyright (c) 2013-2016 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)
|
||||
//
|
||||
|
||||
// Test that header file is self-contained.
|
||||
#include <beast/http/rfc2616.hpp>
|
||||
|
||||
#include <beast/detail/unit_test/suite.hpp>
|
||||
#include <string>
|
||||
#include <vector>
|
||||
9
test/http/streambuf_body.cpp
Normal file
9
test/http/streambuf_body.cpp
Normal file
@@ -0,0 +1,9 @@
|
||||
//
|
||||
// Copyright (c) 2013-2016 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)
|
||||
//
|
||||
|
||||
// Test that header file is self-contained.
|
||||
#include <beast/http/streambuf_body.hpp>
|
||||
9
test/http/string_body.cpp
Normal file
9
test/http/string_body.cpp
Normal file
@@ -0,0 +1,9 @@
|
||||
//
|
||||
// Copyright (c) 2013-2016 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)
|
||||
//
|
||||
|
||||
// Test that header file is self-contained.
|
||||
#include <beast/http/string_body.hpp>
|
||||
9
test/http/type_check.cpp
Normal file
9
test/http/type_check.cpp
Normal file
@@ -0,0 +1,9 @@
|
||||
//
|
||||
// Copyright (c) 2013-2016 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)
|
||||
//
|
||||
|
||||
// Test that header file is self-contained.
|
||||
#include <beast/http/type_check.hpp>
|
||||
9
test/http/write.cpp
Normal file
9
test/http/write.cpp
Normal file
@@ -0,0 +1,9 @@
|
||||
//
|
||||
// Copyright (c) 2013-2016 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)
|
||||
//
|
||||
|
||||
// Test that header file is self-contained.
|
||||
#include <beast/http/write.hpp>
|
||||
Reference in New Issue
Block a user