diff --git a/doc/qbk/01_intro/1_quick_look.qbk b/doc/qbk/01_intro/1_quick_look.qbk new file mode 100644 index 00000000..9db70b0b --- /dev/null +++ b/doc/qbk/01_intro/1_quick_look.qbk @@ -0,0 +1,45 @@ +[/ + 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 Quick Look] +[/block''''''] + +These complete programs are intended to quickly impress upon readers +the flavor of the library. Source code and build scripts for them are +located in the [source_file example] directory. + + + +[section:http_client Simple HTTP Client __example__] + +Use HTTP to make a GET request to a website and print the response: + +File: [source_file example/http/client/sync/http_client_sync.cpp] + +[example_http_client] + +[endsect] + + + +[section:websocket_client Simple WebSocket Client __example__] + +Establish a WebSocket connection, send a message and receive the reply: + +File: [source_file example/websocket/client/sync/websocket_client_sync.cpp] + +[example_websocket_client] + +[endsect] + +[include 1a_bishop_fox.qbk] + +[include 1b_autobahn.qbk] + +[endsect] diff --git a/doc/qbk/01_intro/1_reports.qbk b/doc/qbk/01_intro/1a_bishop_fox.qbk similarity index 65% rename from doc/qbk/01_intro/1_reports.qbk rename to doc/qbk/01_intro/1a_bishop_fox.qbk index a3b37c05..f9888a5f 100644 --- a/doc/qbk/01_intro/1_reports.qbk +++ b/doc/qbk/01_intro/1a_bishop_fox.qbk @@ -1,5 +1,5 @@ [/ - Copyright (c) 2016-2017 Vinnie Falco (vinnie dot falco at gmail dot com) + 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) @@ -7,12 +7,7 @@ Official repository: https://github.com/boostorg/beast ] -[section Reports] -[block''''''] - - - -[section Security Review (Bishop Fox)] +[section:security_review_bishop_fox Security Review (Bishop Fox) __video__] Since 2005, [@https://www.bishopfox.com/ Bishop Fox] has provided security consulting services to the Fortune 1000, high-tech startups, @@ -35,36 +30,14 @@ manual exploitation and review of these issues to validate the findings. [@https://vinniefalco.github.io/BeastAssets/Beast%20-%20Hybrid%20Application%20Assessment%202017%20-%20Assessment%20Report%20-%2020171114.pdf [*Beast - Hybrid Application Assessment 2017]] -[block''' +[/ "Securing Boost.Beast: A Non-Traditional Source Code Review"] +''' + align="center" contentwidth="560" contentdepth="315"/> -'''] - -[endsect] - - - -[section WebSocket (Autobahn|Testsuite)] - -The -[@https://github.com/crossbario/autobahn-testsuite Autobahn WebSockets Testsuite] -provides a fully automated test suite to -verify client and server implementations of The WebSocket Protocol -for specification conformance and implementation robustness. -The test suite will check an implementation by doing basic -WebSocket conversations, extensive protocol compliance -verification and performance and limits testing. -Autobahn|Testsuite is used across the industry and -contains over 500 test cases. - -[@https://vinniefalco.github.io/BeastAssets/reports/autobahn/index.html [*Autobahn|Testsuite WebSocket Results]] - -[endsect] - - +''' [endsect] diff --git a/doc/qbk/01_intro/1b_autobahn.qbk b/doc/qbk/01_intro/1b_autobahn.qbk new file mode 100644 index 00000000..87fb29f2 --- /dev/null +++ b/doc/qbk/01_intro/1b_autobahn.qbk @@ -0,0 +1,25 @@ +[/ + 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:websocket_autobahn_testsuite WebSocket (Autobahn|Testsuite)] + +The +[@https://github.com/crossbario/autobahn-testsuite Autobahn WebSockets Testsuite] +provides a fully automated test suite to +verify client and server implementations of The WebSocket Protocol +for specification conformance and implementation robustness. +The test suite will check an implementation by doing basic +WebSocket conversations, extensive protocol compliance +verification and performance and limits testing. +Autobahn|Testsuite is used across the industry and +contains over 500 test cases. + +[@https://vinniefalco.github.io/BeastAssets/reports/autobahn/index.html [*Autobahn|Testsuite WebSocket Results]] + +[endsect] diff --git a/doc/qbk/01_intro/0_intro.qbk b/doc/qbk/01_intro/_intro.qbk similarity index 95% rename from doc/qbk/01_intro/0_intro.qbk rename to doc/qbk/01_intro/_intro.qbk index 70ac6bfe..a48f99ea 100644 --- a/doc/qbk/01_intro/0_intro.qbk +++ b/doc/qbk/01_intro/_intro.qbk @@ -1,5 +1,5 @@ [/ - Copyright (c) 2016-2017 Vinnie Falco (vinnie dot falco at gmail dot com) + 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) @@ -58,7 +58,7 @@ Beast requires: * [*C++11:] Robust support for most language features. * [*Boost:] Beast only works with Boost, not stand-alone Asio -* [*OpenSSL:] Optional, for using TLS/Secure sockets. +* [*OpenSSL:] Required to build the tests, examples, and to use TLS/Secure sockets. Tested with these compilers: msvc-14+, gcc 4.8.4+, clang 3.6+. @@ -99,7 +99,7 @@ prefer to keep your issue or question confidential please email the author at -[heading Credits] +[section Credits] Boost.Asio is the inspiration behind which all of the interfaces and implementation strategies are built. Some parts of the documentation are @@ -137,4 +137,6 @@ for his generous participation and source code contributions. -[include 1_reports.qbk] +[endsect] + +[include 1_quick_look.qbk] diff --git a/doc/qbk/02_examples/0_examples.qbk b/doc/qbk/02_examples/_examples.qbk similarity index 69% rename from doc/qbk/02_examples/0_examples.qbk rename to doc/qbk/02_examples/_examples.qbk index 8e25bca6..9fae3278 100644 --- a/doc/qbk/02_examples/0_examples.qbk +++ b/doc/qbk/02_examples/_examples.qbk @@ -1,5 +1,5 @@ [/ - Copyright (c) 2016-2017 Vinnie Falco (vinnie dot falco at gmail dot com) + 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) @@ -7,46 +7,13 @@ Official repository: https://github.com/boostorg/beast ] -[section Quick Start] -[block''''''] - -These complete programs are intended to quickly impress upon readers -the flavor of the library. Source code and build scripts for them are -located in the [source_file example] directory. - -[section HTTP Client] - -Use HTTP to make a GET request to a website and print the response: - -File: [source_file example/http/client/sync/http_client_sync.cpp] - -[example_http_client] - -[endsect] - -[section WebSocket Client] - -Establish a WebSocket connection, send a message and receive the reply: - -File: [source_file example/websocket/client/sync/websocket_client_sync.cpp] - -[example_websocket_client] - -[endsect] - -[endsect] - - - [section Examples] [block''''''] Source code and build scripts for these programs are located in the [source_file example] directory. - - -[template example_src[path name] ''''''[name]''''''] +[/-----------------------------------------------------------------------------] [section Clients] @@ -97,7 +64,7 @@ before disconnecting. All asynchronous clients support timeouts. [endsect] - +[/-----------------------------------------------------------------------------] [section Servers] @@ -166,7 +133,7 @@ support timeouts. [endsect] - +[/-----------------------------------------------------------------------------] [section Servers (Advanced)] @@ -211,93 +178,56 @@ and illustrate the implementation of advanced features. [endsect] +[/-----------------------------------------------------------------------------] +[section:chat_server Chat Server __video__ __new__] -[section CppCon 2018] +This example demonstrates a websocket chat server, allowing multiple +users to connect and participate in live, group messaging. It comes +with a tiny front end implemented in JavaScript and HTML5 which runs +in any browser. The example is accompanied by a one hour presentation +which provides a discussion of networking concepts, followed by in-depth +explanation of how the client and server are constructed. This talk +was delivered at [@https://cppcon.org CppCon 2018]. The source code +in the Beast example contains improvements to the original program. -This talk was given at [@https://cppcon.org CppCon 2018]. In this -presentation, we develop a multi-user chat server written in C++ using -Beast WebSocket, which uses a provided chat client written in HTML and -JavaScript. An improved, multi-threaded version of this program is -included here -[source_file example/websocket/server/chat-multi]. +[table Chat WebSocket Server and JavaScript Client +[[Component] [Features] [Sources]] +[ + [Server] + [[itemized_list + [C++] + [Timeouts] + [Multi-threaded] + [Broadcast to multiple peers] + [Dual protocols: HTTP and WebSocket] + [Clean exit via SIGINT (CTRL+C) or SIGTERM (kill)] + ]] + [[source_file example/websocket/server/chat-multi]] +][ + [Client] + [[itemized_list + [JavaScript / HTML5] + [Runs in the browser] + [Delivered by the server] + [Only 60 lines total including UI] + [Completely portable graphics] + ]] + [[source_file example/websocket/server/chat-multi/chat_client.html]] +]] -[block''' +[/ "Get rich quick! Using Boost.Beast WebSockets and Networking TS"] +''' -'''] +''' [endsect] - - -[section Common Files] - -Some of the examples use one or more shared header files, they are -listed here along with a description of their use: - -[table -[[Source File] [Description]] -[ - [[source_file example/common/detect_ssl.hpp]] - [ - This contains the detect SSL algorithm including the - synchronous and asynchronous initiating functions, described - in the documentation. It is used by the "flex" servers which - support both plain and SSL sessions on the same port. - ] -][ - [[source_file example/common/root_certificates.hpp]] - [ - This contains the root SSL certificates used in the SSL client - examples. These certificates are used to verify the signatures - of SSL certificates presented by remote servers. They represent - a subset of the public keys usually installed as part of the - operating system or browser, so they may not identify every - possible server. - ] -][ - [[source_file example/common/server_certificate.hpp]] - [ - This file contains a self-signed SSL certificate used by the - SSL server examples. It has not been validated by a Certificate - Authority ("CA") so connecting to an example HTTP server using - a browser may generate security warnings. - ] -]] - -[endsect] - - - -[section Documentation Samples] - -Here are all of the example functions and classes presented -throughout the documentation, they can be included and used -in your program without modification - -* [source_file example/doc/http_examples.hpp] - -[endsect] - - - -[section Composed Operations] - -This program shows how to use Beast's network foundations to build a -composable asynchronous initiation function with associated composed -operation implementation. This is a complete, runnable version of -the example described in -[link beast.using_io.writing_composed_operations.echo Writing Composed Operations: Echo]. - -* [source_file example/echo-op/echo_op.cpp] - -[endsect] - - +[/-----------------------------------------------------------------------------] [endsect] diff --git a/doc/qbk/03_core/1_refresher.qbk b/doc/qbk/03_core/1_refresher.qbk index 348b5786..1b14f365 100644 --- a/doc/qbk/03_core/1_refresher.qbk +++ b/doc/qbk/03_core/1_refresher.qbk @@ -1,5 +1,5 @@ [/ - Copyright (c) 2016-2017 Vinnie Falco (vinnie dot falco at gmail dot com) + 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) @@ -7,7 +7,7 @@ Official repository: https://github.com/boostorg/beast ] -[section:asio_refresher Refresher] +[section:asio_refresher Refresher __new__] To use Beast effectively, a prior understanding of Networking is required. This section reviews these concepts as a reminder and guide for further @@ -22,7 +22,11 @@ Data may be reliably transferred across a connection in both directions ([@https://en.wikipedia.org/wiki/Duplex_(telecommunications) ['full-duplex]]) with bytes arriving in the same order they were sent. These connections, along with the objects and types used to represent them, are collectively termed -[link beast.concepts.streams ['streams]]. +[link beast.concepts.streams ['streams]]. The computer or device attached +to the network is called a +[@https://en.wikipedia.org/wiki/Host_(network) ['host]], and the +program on the other end of an established connection is called a +[@https://en.wikipedia.org/wiki/Peer-to-peer ['peer]]. The [@https://en.wikipedia.org/wiki/Internet ['internet]] @@ -33,7 +37,13 @@ popular protocol is which this library relies on exclusively. The protocol takes care of the low level details so that applications see a ['stream], which is the reliable, full-duplex connection carrying the ordered -set of bytes described above. +set of bytes described above. A +[@https://en.wikipedia.org/wiki/Server_(computing) ['server]] +is a powerful, always-on host at a well-known network name or network address +which provides data services. A +[@https://en.wikipedia.org/wiki/Client_(computing) ['client]] +is a transient peer which connects to a server to exchange data, and goes +offline. A vendor supplies a program called a [@https://en.wikipedia.org/wiki/Device_driver ['device driver]], @@ -121,8 +131,9 @@ Beast provides a well-rounded collection of dynamic buffer types such as [link beast.ref.boost__beast__flat_buffer `flat_buffer`], [link beast.ref.boost__beast__multi_buffer `multi_buffer`], and [link beast.ref.boost__beast__static_buffer `static_buffer`]. -In the following function, the contents of a stream are read into a dynamic -buffer until it contains a newline character, using +The following function reads data from a +[link beast.ref.boost__beast__tcp_stream `tcp_stream`] +into a dynamic buffer until it encountering a newline character, using [@boost:/doc/html/boost_asio/reference/buffers_iterator.html `net::buffers_iterator`] to treat the contents of the buffer as a range of characters: @@ -177,9 +188,7 @@ results, which may include the error code and other specific information. An asynchronous operation is said to be ['completed] after the completion handler is queued. The code that follows shows how some -text may be written to a -[@boost:/doc/html/boost_asio/reference/ip__tcp/socket.html `net::socket`] -asynchronously, invoking a lambda when the +text may be written to a socket asynchronously, invoking a lambda when the operation is complete: [code_core_1_refresher_3s] @@ -202,7 +211,10 @@ Or these associations may be specified non-intrusively, by specializing the class templates [@boost:/doc/html/boost_asio/reference/associated_allocator.html `net::associated_allocator`] and -[@boost:/doc/html/boost_asio/reference/associated_executor.html `net::associated_executor`]. +[@boost:/doc/html/boost_asio/reference/associated_executor.html `net::associated_executor`]: + +[code_core_1_refresher_7] + The function [@boost:/doc/html/boost_asio/reference/bind_executor.html `net::bind_executor`] may be used when the caller wants to change the executor of a completion @@ -233,7 +245,7 @@ object meeting the named requirements for asynchronous reading, writing, or both. This example shows an algorithm which writes some text to an asynchronous stream: -[code_core_1_refresher_7] +[code_core_1_refresher_8] [/-----------------------------------------------------------------------------] @@ -285,42 +297,43 @@ launched with In both of these cases, an object with a specific type is used in place of the completion handler, and the return value of the initiating function is transformed from `void` to `std::future` or `std::size_t`. -The return type transformation is supported by customization points in the -initiating function signature. Here is the signature for `net::async_write`: +The handler is sometimes called a +[@boost:/doc/html/boost_asio/reference/asynchronous_operations#boost_asio.reference.asynchronous_operations.completion_tokens_and_handlers ['CompletionToken]] +when used in this context. The return type transformation is supported by +customization points in the initiating function signature. Here is the +signature for +[@boost:/doc/html/boost_asio/reference/async_write/overload1.html `net::async_write`]: -[code_core_1_refresher_8] +[code_core_1_refresher_9] The type of the function's return value is determined by the [@boost:/doc/html/boost_asio/reference/async_result.html `net::async_result`] customization point, which comes with specializations for common library types such as `std::future` and may also be specialized for user-defined -types. The universal model also provides the -[@boost:/doc/html/boost_asio/reference/async_completion.html `net::async_completion`] -customization point for transforming -the `handler` argument (called a -[@boost:/doc/html/boost_asio/reference/asynchronous_operations/completion_token.html ['CompletionToken]] -in this context) into an underlying completion handler to be invoked when the -operation is complete. This transformed, internal handler is responsible for -the finalizing step that delivers the result of the operation to the caller. -For example, when using `net::use_future` the internal handler will deliver -the result by calling `std::promise::set_value` on the promise object -returned by the initiating function. +types. The body of the initiating function calls the +[@boost:/doc/html/boost_asio/reference/async_inititate.html `net::async_initiate`] +helper to capture the arguments and forward them to the specialization of +`async_result`. An additional "initiation function" object is provided which +`async_result` may use to immediately launch the operation, or defer the launch +of the operation until some point in the future (this is called "lazy +execution"). The initiation function object receives the internal completion +handler which matches the signature expected by the initiating function: + +[code_core_1_refresher_10] + +This transformed, internal handler is responsible for the finalizing step that +delivers the result of the operation to the caller. For example, when using +`net::use_future` the internal handler will deliver the result by calling +[@https://en.cppreference.com/w/cpp/thread/promise/set_value `std::promise::set_value`] +on the promise object returned by the initiating function. [/-----------------------------------------------------------------------------] [heading Using Networking] -[warning - Beast does not manage sockets, make outgoing connections, - accept incoming connections, handle timeouts, close endpoints, - do name lookups, deal with TLS certificates, perform authentication, - or otherwise handle any aspect of connection management. This is - left to the interfaces already existing on the underlying streams. -] - -Library stream algorithms require a __socket__, __ssl_stream__, or other -__Stream__ object that has already established communication with a remote -peer. This example is provided as a reminder of how to work with +Most library stream algorithms require a __socket__, __ssl_stream__, or +other __Stream__ object that has already established communication with +a remote peer. This example is provided as a reminder of how to work with sockets: [snippet_core_2] diff --git a/doc/qbk/03_core/2_streams.qbk b/doc/qbk/03_core/2_streams.qbk index fc489178..f3129a3a 100644 --- a/doc/qbk/03_core/2_streams.qbk +++ b/doc/qbk/03_core/2_streams.qbk @@ -1,5 +1,5 @@ [/ - Copyright (c) 2016-2017 Vinnie Falco (vinnie dot falco at gmail dot com) + 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) @@ -9,7 +9,7 @@ -[section Stream Types] +[section:stream_types Streams] A __Stream__ is a communication channel where data is reliably transferred as an ordered sequence of bytes. Streams are either synchronous or asynchronous, diff --git a/doc/qbk/03_core/3_timeouts.qbk b/doc/qbk/03_core/3_timeouts.qbk new file mode 100644 index 00000000..ee55e005 --- /dev/null +++ b/doc/qbk/03_core/3_timeouts.qbk @@ -0,0 +1,217 @@ +[/ + 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:timeouts Timeouts __example__ __new__] + +Network programs must handle adverse connection conditions; the most common +is that a connected peer goes offline unexpectedly. Protocols have no way of +identifying this reliably: the peer is offline after all, and unable to send +a message announcing the absence. A peer can go offline for various reasons: + +[itemized_list + [The peer experiences a power loss] + [The peer becomes disconnected from the network] + [The local host becomes disconnected from the network] + [The network itself becomes unavailable] +] + +To determine when a peer is offline or idle, a program will implement a +[@https://en.wikipedia.org/wiki/Timeout_(computing) timeout] +algorithm, which closes the connection after a specified amount of time if +some condition is met. For example, if no data is received for the duration. +A timeout may be used to: + +[itemized_list + [Drop malicious or poorly performing hosts] + [Close idle connections to free up resources] + [Determine if a peer is offline or no longer available] +] + +Traditionally, programs use a +[@boost:/doc/html/boost_asio/reference/steady_timer.html `net::steady_timer`] +to determine when a timeout occurs, and then call +[@boost:/doc/html/boost_asio/reference/basic_socket/close/overload2.html `close`] +on the socket to release the resources. The complexity of managing a separate +timer is often a source of +[@http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2018/p1269r0.html#timers frustration] +for non-experts. + +[note + For portability reasons, networking does not provide timeouts + or cancellation features for synchronous stream operations. +] + +To simplify the handling of timeouts, these provided types wrap a +[@boost:/doc/html/boost_asio/reference/basic_stream_socket.html `net::basic_stream_socket`] +to provide additional features: + +[table +[[Name][Features]] +[ + [[link beast.ref.boost__beast__tcp_stream `tcp_stream`]] + [[itemized_list + [Timeouts for logical operations] + [[@boost:/doc/html/boost_asio/reference/ip__tcp.html `net::ip::tcp`] protocol] + [[@boost:/doc/html/boost_asio/reference/executor.html `net::executor`] executor] + [[link beast.ref.boost__beast__unlimited_rate_policy `unlimited_rate_policy`] rate limits] + ]] +][ + [[link beast.ref.boost__beast__basic_stream `basic_stream`]] + [[itemized_list + [Timeouts for logical operations] + [Configurable __Protocol__ type] + [Configurable __Executor__ type] + [Configurable __RatePolicy__ type] + ]] +]] + +[/-----------------------------------------------------------------------------] + +[heading Construction] + +The `tcp_stream` is designed as a replacement for +[@boost:/doc/html/boost_asio/reference/ip__tcp/socket.html `net::ip::tcp::socket`]. +Any program which currently uses a socket, can switch to a `tcp_stream` and achieve +the features above (although some interfaces are different, see below). +Networking now allows I/O objects to construct with any instance of +__ExecutionContext__ or __Executor__ objects. Here we construct a stream which +uses a particular I/O context to dispatch completion handlers: + +[code_core_3_timeouts_1] + +Alternatively, we can construct the stream from an executor: + +[code_core_3_timeouts_2] + +The function +[link beast.ref.boost__beast__make_strand `make_strand`] returns a strand +constructed from an execution context or executor. When a +[@boost:/doc/html/boost_asio/reference/strand.html `net::strand`] +is chosen for the stream's executor, all completion handlers which do not +already have an associated executor will use the strand. This is both a +notational convenience (no need for `strand::wrap` or `bind_executor` at +call sites) and a measure of safety, as it is no longer possible to forget +to use the strand. + +[code_core_3_timeouts_3] + +[/-----------------------------------------------------------------------------] + +[heading Connecting] + +Before data can be exchanged, the stream needs to be connected to a peer. +The following code sets a timeout for an asynchronous connect operation. +In Beast, functions to connect to a range of endpoints (such as the range +returned by +[@boost:/doc/html/boost_asio/reference/ip__basic_resolver/resolve/overload3.html `net::ip::tcp::resolver::resolve`]) +are members of the class rather than free functions such as +[@boost:/doc/html/boost_asio/reference/async_connect.html `net::async_connect`]. + +[code_core_3_timeouts_4] + +A server will use an acceptor bound to a particular IP address and port to +listen to and receive incoming connection requests. The acceptor returns +an ordinary socket. A `tcp_stream` can be move-constructed from the +underlying `basic_stream_socket` thusly: + +[code_core_3_timeouts_5] + +[/-----------------------------------------------------------------------------] + +[heading Reading and Writing] + +Timeouts apply to the logical operation, expressed as a series of asynchronous +calls, rather than just the next call. This code reads a line from the stream +and writes it back. Both the read and the write must complete within 30 seconds +from when the timeout was set; the timer is not reset between operations. + +[code_core_3_timeouts_6] + +Since reads and writes can take place concurrently, it is possible to have +two simultaneous logical operations where each operation either only reads, +or only writes. The beginning of a new read or write operation will use +the most recently set timeout. This will not affect operations that are +already outstanding. + +[code_core_3_timeouts_7] + +When a timeout is set, it cancels any previous read or write timeout for which +no outstanding operation is in progress. Algorithms which loop over logical +operations simply need to set the timeout once before the logical operation, +it is not necessary to call `expires_never` in this case. Here we implement +an algorithm which continuously echoes lines back, with a timeout. This example +is implemented as a complete function. + +[code_core_3_timeouts_1f] + +[/-----------------------------------------------------------------------------] + +[heading https_get] + +It is important to note that all of the examples thus far which perform +reads and writes with a timeout, make use of the existing networking stream +algorithms. As these algorithms are written generically to work with any +object meeting the stream requirements, they transparently support timeouts +when used with `tcp_stream`. This can be used to enable timeouts for stream +wrappers that do not currently support timeouts. + +The following code establishes an encrypted connection, writes an HTTP +request, reads the HTTP response, and closes the connection gracefully. +If these operations take longer than 30 seconds total, a timeout occurs. +This code is intended to show how `tcp_stream` can be used to enable +timeouts across unmodified stream algorithms which were not originally +written to support timing out, and how a blocking algorithm may be written +from asynchronous intermediate operations. + +[code_core_3_timeouts_2f] + +[/-----------------------------------------------------------------------------] + +[heading Rate Limiting] + +The +[link beast.ref.boost__beast__basic_stream `basic_stream`] +class template supports an additional `RatePolicy` template parameter. Objects +of this type must meet the requirements of __RatePolicy__. They are used to +implement rate limiting or bandwidth management. The default policy for +`basic_stream` and `tcp_stream` is +[link beast.ref.boost__beast__unlimited_rate_policy `unlimited_rate_policy`], +which places no limits on reading and writing. The library comes with the +[link beast.ref.boost__beast__simple_rate_policy `simple_rate_policy`], +allowing for independent control of read and write limits expressed in terms +of bytes per second. The follow code creates an instance of the basic stream +with a simple rate policy, and sets the read and write limits: + +[code_core_3_timeouts_8] + +More sophisticated rate policies can be implemented as user-defined types which +meet the requirements of __RatePolicy__. Here, we develop a rate policy that +measures the instantaneous throughput of reads and writes. First we write a +small utility class that applies an exponential smoothing function to a series +of discrete rate samples, to calculate instantaneous throughput. + +[code_core_3_timeouts_3f] + +Then we define our rate policy object. We friend the type +[link beast.ref.boost__beast__rate_policy_access `rate_policy_access`] to +allow our implementation to be private, but still allow the `basic_stream` +access to call the required functions. This lets us avoid having to write +a cumbersome friend declaration for the `basic_stream` class template. +Public members of rate policy objects become part of the stream object's +interface, through a call to `rate_policy`. + +[code_core_3_timeouts_4f] + +To use our new policy we declare an instance of the stream, and then use it +with stream algorithms as usual. At any time, we can determine the current +read or write rates by calling into the policy. + +[code_core_3_timeouts_9] + +[endsect] diff --git a/doc/qbk/03_core/3_layers.qbk b/doc/qbk/03_core/4__layers.qbk similarity index 94% rename from doc/qbk/03_core/3_layers.qbk rename to doc/qbk/03_core/4__layers.qbk index 67922c01..c76b95c1 100644 --- a/doc/qbk/03_core/3_layers.qbk +++ b/doc/qbk/03_core/4__layers.qbk @@ -1,5 +1,5 @@ [/ - Copyright (c) 2016-2017 Vinnie Falco (vinnie dot falco at gmail dot com) + 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) @@ -7,7 +7,7 @@ Official repository: https://github.com/boostorg/beast ] -[section Layered Streams] +[section Layered Streams __new__] Networking's __ssl_stream__ is a class template meeting the requirements of both synchronous and asynchronous read and write streams, implemented @@ -17,7 +17,7 @@ layer object internally, while allowing external access through the observer `net::ssl::stream::next_layer()`. This declares an SSL stream which uses a regular TCP/IP socket as the next layer: -[code_core_3_layers_1] +[code_core_4_layers_1] Objects using this design pattern are referred to in networking as "a stack of stream layers". In Beast we use the term ['layered stream], @@ -26,13 +26,13 @@ As with the SSL stream, __websocket_stream__ is a class template parameterized on a next layer object. This declares a websocket stream which uses a regular TCP/IP socket as the next layer: -[code_core_3_layers_2] +[code_core_4_layers_2] If a Secure WebSockets stream is desired, this is accomplished simply by changing the type of the next layer and adjusting the constructor arguments to match: -[code_core_3_layers_3] +[code_core_4_layers_3] Higher level abstractions can be developed in this fashion by nesting stream layers to arbitrary degree. The stack of stream layers effectively @@ -88,7 +88,7 @@ facilities for authoring and working with layered streams: puts a layered stream into non-blocking mode by retrieving the TCP/IP socket in the lowest layer and changing the socket option: - [code_core_3_layers_4] + [code_core_4_layers_4] ]] [[ [link beast.ref.boost__beast__http__icy_stream `http::icy_stream`] @@ -114,13 +114,15 @@ facilities for authoring and working with layered streams: ]] ] -[heading Example] +[section Counted Stream __example__ __new__] This example shows the definition of a layered stream which keeps individual counts of the total number of bytes read from and written to the next layer. It meets the requirements for synchronous and asynchronous read and write streams: -[code_core_3_layers_5] +[code_core_4_layers_5] + +[endsect] [endsect] diff --git a/doc/qbk/03_core/4_buffers.qbk b/doc/qbk/03_core/5_buffers.qbk similarity index 99% rename from doc/qbk/03_core/4_buffers.qbk rename to doc/qbk/03_core/5_buffers.qbk index be6cbd7b..3bf76b62 100644 --- a/doc/qbk/03_core/4_buffers.qbk +++ b/doc/qbk/03_core/5_buffers.qbk @@ -1,5 +1,5 @@ [/ - Copyright (c) 2016-2017 Vinnie Falco (vinnie dot falco at gmail dot com) + 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) diff --git a/doc/qbk/03_core/5_files.qbk b/doc/qbk/03_core/6_files.qbk similarity index 95% rename from doc/qbk/03_core/5_files.qbk rename to doc/qbk/03_core/6_files.qbk index 71c95618..2d9ff2aa 100644 --- a/doc/qbk/03_core/5_files.qbk +++ b/doc/qbk/03_core/6_files.qbk @@ -1,5 +1,5 @@ [/ - Copyright (c) 2016-2017 Vinnie Falco (vinnie dot falco at gmail dot com) + 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) diff --git a/doc/qbk/03_core/6_composed.qbk b/doc/qbk/03_core/7_composed.qbk similarity index 97% rename from doc/qbk/03_core/6_composed.qbk rename to doc/qbk/03_core/7_composed.qbk index f419f0a6..b250878a 100644 --- a/doc/qbk/03_core/6_composed.qbk +++ b/doc/qbk/03_core/7_composed.qbk @@ -1,5 +1,5 @@ [/ - Copyright (c) 2016-2017 Vinnie Falco (vinnie dot falco at gmail dot com) + 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) @@ -110,7 +110,7 @@ composed operations: ]] ] -[include 6a_echo.qbk] -[include 6b_detect_ssl.qbk] +[include 7a_echo.qbk] +[include 7b_detect_ssl.qbk] [endsect] diff --git a/doc/qbk/03_core/6a_echo.qbk b/doc/qbk/03_core/7a_echo.qbk similarity index 94% rename from doc/qbk/03_core/6a_echo.qbk rename to doc/qbk/03_core/7a_echo.qbk index e95be58b..1f4f2bbf 100644 --- a/doc/qbk/03_core/6a_echo.qbk +++ b/doc/qbk/03_core/7a_echo.qbk @@ -1,5 +1,5 @@ [/ - Copyright (c) 2016-2017 Vinnie Falco (vinnie dot falco at gmail dot com) + 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) @@ -7,7 +7,7 @@ Official repository: https://github.com/boostorg/beast ] -[section:echo Echo] +[section:echo Echo __example__ __new__] This example develops an initiating function called [*echo]. The operation will read up to the first newline on a stream, and @@ -17,6 +17,10 @@ initiation function. For our echo operation the only inputs are the stream and the completion token. The output is the error code which is usually included in all completion handler signatures. +[tip + The source for for this example is [source_file example/echo-op/echo_op.cpp]. +] + [example_core_echo_op_2] Now that we have a declaration, we will define the body of the function. diff --git a/doc/qbk/03_core/6b_detect_ssl.qbk b/doc/qbk/03_core/7b_detect_ssl.qbk similarity index 97% rename from doc/qbk/03_core/6b_detect_ssl.qbk rename to doc/qbk/03_core/7b_detect_ssl.qbk index ddf47693..b373606c 100644 --- a/doc/qbk/03_core/6b_detect_ssl.qbk +++ b/doc/qbk/03_core/7b_detect_ssl.qbk @@ -1,5 +1,5 @@ [/ - Copyright (c) 2016-2017 Vinnie Falco (vinnie dot falco at gmail dot com) + 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) @@ -7,7 +7,7 @@ Official repository: https://github.com/boostorg/beast ] -[section:detect_ssl Detect SSL] +[section:detect_ssl Detect SSL __example__ __new__] In this example we will build a simple function to detect the presence of the [@https://tools.ietf.org/html/rfc2246#section-7.4 TLS client handshake] diff --git a/doc/qbk/03_core/0_core.qbk b/doc/qbk/03_core/_core.qbk similarity index 90% rename from doc/qbk/03_core/0_core.qbk rename to doc/qbk/03_core/_core.qbk index b52f0e7a..2a55c7d2 100644 --- a/doc/qbk/03_core/0_core.qbk +++ b/doc/qbk/03_core/_core.qbk @@ -1,5 +1,5 @@ [/ - Copyright (c) 2016-2017 Vinnie Falco (vinnie dot falco at gmail dot com) + 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) @@ -7,7 +7,7 @@ Official repository: https://github.com/boostorg/beast ] -[section:using_io Using Networking] +[section:using_io Networking __new__] This library uses the [@http://cplusplus.github.io/networking-ts/draft.pdf Networking Technical Specification], @@ -75,9 +75,9 @@ namespace is used to qualify Networking identifiers. For Boost.Beast, `net` will be an alias for the `boost::asio` namespace. To further ease of use, this library provides an extensive collection -of types and algorithms. This section of the documentation explains these types and algorithms, provides examples -of usage, and also provides refreshers and tutorials for working with -networking. +of types and algorithms. This section of the documentation explains these +types and algorithms, provides examples of usage, and also provides +refreshers and tutorials for working with networking. [heading Abbreviations] @@ -91,9 +91,10 @@ effect: [include 1_refresher.qbk] [include 2_streams.qbk] -[include 3_layers.qbk] -[include 4_buffers.qbk] -[include 5_files.qbk] -[include 6_composed.qbk] +[include 3_timeouts.qbk] +[include 4__layers.qbk] +[include 5_buffers.qbk] +[include 6_files.qbk] +[include 7_composed.qbk] [endsect] diff --git a/doc/qbk/04_http/01_primer.qbk b/doc/qbk/04_http/01_primer.qbk index d2710b27..3aa24dbb 100644 --- a/doc/qbk/04_http/01_primer.qbk +++ b/doc/qbk/04_http/01_primer.qbk @@ -1,5 +1,5 @@ [/ - Copyright (c) 2016-2017 Vinnie Falco (vinnie dot falco at gmail dot com) + 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) diff --git a/doc/qbk/04_http/02_message.qbk b/doc/qbk/04_http/02_message.qbk index b4e5574a..724f2c49 100644 --- a/doc/qbk/04_http/02_message.qbk +++ b/doc/qbk/04_http/02_message.qbk @@ -1,5 +1,5 @@ [/ - Copyright (c) 2016-2017 Vinnie Falco (vinnie dot falco at gmail dot com) + 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) diff --git a/doc/qbk/04_http/03_streams.qbk b/doc/qbk/04_http/03_streams.qbk index 91c84fdd..ba7e565e 100644 --- a/doc/qbk/04_http/03_streams.qbk +++ b/doc/qbk/04_http/03_streams.qbk @@ -1,5 +1,5 @@ [/ - Copyright (c) 2016-2017 Vinnie Falco (vinnie dot falco at gmail dot com) + 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) diff --git a/doc/qbk/04_http/04_serializer_streams.qbk b/doc/qbk/04_http/04_serializer_streams.qbk index 020b1bbb..f37aae43 100644 --- a/doc/qbk/04_http/04_serializer_streams.qbk +++ b/doc/qbk/04_http/04_serializer_streams.qbk @@ -1,5 +1,5 @@ [/ - Copyright (c) 2016-2017 Vinnie Falco (vinnie dot falco at gmail dot com) + 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) diff --git a/doc/qbk/04_http/05_parser_streams.qbk b/doc/qbk/04_http/05_parser_streams.qbk index 85d7f2eb..e316a38f 100644 --- a/doc/qbk/04_http/05_parser_streams.qbk +++ b/doc/qbk/04_http/05_parser_streams.qbk @@ -1,5 +1,5 @@ [/ - Copyright (c) 2016-2017 Vinnie Falco (vinnie dot falco at gmail dot com) + 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) @@ -125,7 +125,7 @@ the response: -[section Incremental Read] +[section:incremental_read Incremental Read __example__] This function uses [link beast.ref.boost__beast__http__buffer_body `buffer_body`] diff --git a/doc/qbk/04_http/06_serializer_buffers.qbk b/doc/qbk/04_http/06_serializer_buffers.qbk index 3074b9d6..f5379be6 100644 --- a/doc/qbk/04_http/06_serializer_buffers.qbk +++ b/doc/qbk/04_http/06_serializer_buffers.qbk @@ -1,5 +1,5 @@ [/ - Copyright (c) 2016-2017 Vinnie Falco (vinnie dot falco at gmail dot com) + 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) @@ -58,7 +58,7 @@ C++14 example we print the header first, followed by the body: -[section Write To std::ostream] +[section:write_to_std_ostream Write To std::ostream __example__] The standard library provides the type `std::ostream` for performing high level write operations on character streams. The variable `std::cout` is diff --git a/doc/qbk/04_http/07_parser_buffers.qbk b/doc/qbk/04_http/07_parser_buffers.qbk index 6bf63a7e..560c5363 100644 --- a/doc/qbk/04_http/07_parser_buffers.qbk +++ b/doc/qbk/04_http/07_parser_buffers.qbk @@ -1,5 +1,5 @@ [/ - Copyright (c) 2016-2017 Vinnie Falco (vinnie dot falco at gmail dot com) + 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) @@ -85,7 +85,7 @@ The parser provides a few options which may be set before parsing begins: -[section Read From std::istream] +[section:read_from_std_istream Read From std::istream __example__] The standard library provides the type `std::istream` for performing high level read operations on character streams. The variable `std::cin` is based diff --git a/doc/qbk/04_http/08_chunked_encoding.qbk b/doc/qbk/04_http/08_chunked_encoding.qbk index 9fcd1ae4..e0d01a05 100644 --- a/doc/qbk/04_http/08_chunked_encoding.qbk +++ b/doc/qbk/04_http/08_chunked_encoding.qbk @@ -1,5 +1,5 @@ [/ - Copyright (c) 2016-2017 Vinnie Falco (vinnie dot falco at gmail dot com) + 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) diff --git a/doc/qbk/04_http/09_custom_body.qbk b/doc/qbk/04_http/09_custom_body.qbk index 495416df..ec5ff6fb 100644 --- a/doc/qbk/04_http/09_custom_body.qbk +++ b/doc/qbk/04_http/09_custom_body.qbk @@ -1,5 +1,5 @@ [/ - Copyright (c) 2016-2017 Vinnie Falco (vinnie dot falco at gmail dot com) + 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) @@ -93,7 +93,7 @@ those bodies may be parsed or serialized. -[section File Body] +[section:file_body File Body __example__] Use of the flexible __Body__ concept customization point enables authors to preserve the self-contained nature of the __message__ object while allowing diff --git a/doc/qbk/04_http/0_http.qbk b/doc/qbk/04_http/0_http.qbk index bf976c65..00795c3a 100644 --- a/doc/qbk/04_http/0_http.qbk +++ b/doc/qbk/04_http/0_http.qbk @@ -1,5 +1,5 @@ [/ - Copyright (c) 2016-2017 Vinnie Falco (vinnie dot falco at gmail dot com) + 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) diff --git a/doc/qbk/04_http/10_custom_parsers.qbk b/doc/qbk/04_http/10_custom_parsers.qbk index 86b430f2..facc5204 100644 --- a/doc/qbk/04_http/10_custom_parsers.qbk +++ b/doc/qbk/04_http/10_custom_parsers.qbk @@ -1,5 +1,5 @@ [/ - Copyright (c) 2016-2017 Vinnie Falco (vinnie dot falco at gmail dot com) + 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) diff --git a/doc/qbk/05_http_examples/0_http_examples.qbk b/doc/qbk/05_http_examples/0_http_examples.qbk index 3620cf27..c056fde8 100644 --- a/doc/qbk/05_http_examples/0_http_examples.qbk +++ b/doc/qbk/05_http_examples/0_http_examples.qbk @@ -1,5 +1,5 @@ [/ - Copyright (c) 2016-2017 Vinnie Falco (vinnie dot falco at gmail dot com) + 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) @@ -15,7 +15,7 @@ a variety of scenarios. -[section Change Body Type] +[section:change_body_type Change Body Type __example__] Sophisticated servers may wish to defer the choice of the Body template type until after the header is available. Then, a body type may be chosen @@ -35,7 +35,7 @@ type depending on the method verb: -[section Expect 100-continue (Client)] +[section:expect_100_continue_client Expect 100-continue (Client) __example__] The Expect field with the value "100-continue" in a request is special. It indicates that the after sending the message header, a client desires an @@ -54,7 +54,7 @@ this client action looks like this: -[section Expect 100-continue (Server)] +[section:expect_100_continue_server Expect 100-continue (Server) __example__] The Expect field with the value "100-continue" in a request is special. It indicates that the after sending the message header, a client desires an @@ -72,7 +72,7 @@ synchronous version of this server action looks like this: -[section HEAD request (Client)] +[section:head_request_client HEAD request (Client) __example__] The [@https://tools.ietf.org/html/rfc7231#section-4.3.2 HEAD request] @@ -90,7 +90,7 @@ with the value `true`, as shown in this example: -[section HEAD response (Server)] +[section:head_response_server HEAD response (Server) __example__] When a server receives a [@https://tools.ietf.org/html/rfc7231#section-4.3.2 HEAD request], @@ -103,7 +103,7 @@ if the method was GET, except that the body is omitted. -[section HTTP Relay] +[section:http_relay HTTP Relay __example__] An HTTP proxy acts as a relay between client and server. The proxy reads a request from the client and sends it to the server, possibly adjusting some @@ -123,7 +123,7 @@ and a __parser__ to achieve its goal: -[section Send Child Process Output] +[section:send_child_process_output Send Child Process Output __example__] Sometimes it is necessary to send a message whose body is not conveniently described by a single container. For example, when implementing an HTTP relay diff --git a/doc/qbk/06_websocket/01_streams.qbk b/doc/qbk/06_websocket/01_streams.qbk index 379dfc8a..0ca5e8e8 100644 --- a/doc/qbk/06_websocket/01_streams.qbk +++ b/doc/qbk/06_websocket/01_streams.qbk @@ -1,5 +1,5 @@ [/ - Copyright (c) 2016-2017 Vinnie Falco (vinnie dot falco at gmail dot com) + 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) diff --git a/doc/qbk/06_websocket/02_connect.qbk b/doc/qbk/06_websocket/02_connect.qbk index cc7e8301..beaf7a40 100644 --- a/doc/qbk/06_websocket/02_connect.qbk +++ b/doc/qbk/06_websocket/02_connect.qbk @@ -1,5 +1,5 @@ [/ - Copyright (c) 2016-2017 Vinnie Falco (vinnie dot falco at gmail dot com) + 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) diff --git a/doc/qbk/06_websocket/03_client.qbk b/doc/qbk/06_websocket/03_client.qbk index 1f2038ea..3a829f30 100644 --- a/doc/qbk/06_websocket/03_client.qbk +++ b/doc/qbk/06_websocket/03_client.qbk @@ -1,5 +1,5 @@ [/ - Copyright (c) 2016-2017 Vinnie Falco (vinnie dot falco at gmail dot com) + 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) diff --git a/doc/qbk/06_websocket/04_server.qbk b/doc/qbk/06_websocket/04_server.qbk index fe232ee2..dc2a1607 100644 --- a/doc/qbk/06_websocket/04_server.qbk +++ b/doc/qbk/06_websocket/04_server.qbk @@ -1,5 +1,5 @@ [/ - Copyright (c) 2016-2017 Vinnie Falco (vinnie dot falco at gmail dot com) + 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) diff --git a/doc/qbk/06_websocket/05_decorator.qbk b/doc/qbk/06_websocket/05_decorator.qbk index d0dd8217..1fbe258f 100644 --- a/doc/qbk/06_websocket/05_decorator.qbk +++ b/doc/qbk/06_websocket/05_decorator.qbk @@ -1,5 +1,5 @@ [/ - Copyright (c) 2016-2017 Vinnie Falco (vinnie dot falco at gmail dot com) + 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) @@ -7,7 +7,7 @@ Official repository: https://github.com/boostorg/beast ] -[section:decorator Custom HTTP Fields] +[section:decorator Custom HTTP Fields __new__] For programs which need to modify either the outgoing WebSocket HTTP Upgrade request, the outgoing WebSocket HTTP Upgrade response, or both, the stream diff --git a/doc/qbk/06_websocket/06_messages.qbk b/doc/qbk/06_websocket/06_messages.qbk index 149c3b65..c4b4be13 100644 --- a/doc/qbk/06_websocket/06_messages.qbk +++ b/doc/qbk/06_websocket/06_messages.qbk @@ -1,5 +1,5 @@ [/ - Copyright (c) 2016-2017 Vinnie Falco (vinnie dot falco at gmail dot com) + 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) diff --git a/doc/qbk/06_websocket/07_control.qbk b/doc/qbk/06_websocket/07_control.qbk index b38fe6b4..82864305 100644 --- a/doc/qbk/06_websocket/07_control.qbk +++ b/doc/qbk/06_websocket/07_control.qbk @@ -1,5 +1,5 @@ [/ - Copyright (c) 2016-2017 Vinnie Falco (vinnie dot falco at gmail dot com) + 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) diff --git a/doc/qbk/06_websocket/08_teardown.qbk b/doc/qbk/06_websocket/08_teardown.qbk index 7492d201..5a889f8a 100644 --- a/doc/qbk/06_websocket/08_teardown.qbk +++ b/doc/qbk/06_websocket/08_teardown.qbk @@ -1,5 +1,5 @@ [/ - Copyright (c) 2016-2017 Vinnie Falco (vinnie dot falco at gmail dot com) + 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) diff --git a/doc/qbk/06_websocket/09_notes.qbk b/doc/qbk/06_websocket/09_notes.qbk index ac04d46f..40332394 100644 --- a/doc/qbk/06_websocket/09_notes.qbk +++ b/doc/qbk/06_websocket/09_notes.qbk @@ -1,5 +1,5 @@ [/ - Copyright (c) 2016-2017 Vinnie Falco (vinnie dot falco at gmail dot com) + 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) diff --git a/doc/qbk/06_websocket/0_websocket.qbk b/doc/qbk/06_websocket/0_websocket.qbk index 87deb65e..5107dc20 100644 --- a/doc/qbk/06_websocket/0_websocket.qbk +++ b/doc/qbk/06_websocket/0_websocket.qbk @@ -1,5 +1,5 @@ [/ - Copyright (c) 2016-2017 Vinnie Falco (vinnie dot falco at gmail dot com) + 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) diff --git a/doc/qbk/07_concepts/0_concepts.qbk b/doc/qbk/07_concepts/0_concepts.qbk index f70b5565..4856312f 100644 --- a/doc/qbk/07_concepts/0_concepts.qbk +++ b/doc/qbk/07_concepts/0_concepts.qbk @@ -1,5 +1,5 @@ [/ - Copyright (c) 2016-2017 Vinnie Falco (vinnie dot falco at gmail dot com) + 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) diff --git a/doc/qbk/07_concepts/Body.qbk b/doc/qbk/07_concepts/Body.qbk index b3eb06c8..56c8397e 100644 --- a/doc/qbk/07_concepts/Body.qbk +++ b/doc/qbk/07_concepts/Body.qbk @@ -1,5 +1,5 @@ [/ - Copyright (c) 2016-2017 Vinnie Falco (vinnie dot falco at gmail dot com) + 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) diff --git a/doc/qbk/07_concepts/BodyReader.qbk b/doc/qbk/07_concepts/BodyReader.qbk index f6a267b3..974156cf 100644 --- a/doc/qbk/07_concepts/BodyReader.qbk +++ b/doc/qbk/07_concepts/BodyReader.qbk @@ -1,5 +1,5 @@ [/ - Copyright (c) 2016-2017 Vinnie Falco (vinnie dot falco at gmail dot com) + 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) diff --git a/doc/qbk/07_concepts/BodyWriter.qbk b/doc/qbk/07_concepts/BodyWriter.qbk index 3ca52cf9..8962aa00 100644 --- a/doc/qbk/07_concepts/BodyWriter.qbk +++ b/doc/qbk/07_concepts/BodyWriter.qbk @@ -1,5 +1,5 @@ [/ - Copyright (c) 2016-2017 Vinnie Falco (vinnie dot falco at gmail dot com) + 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) diff --git a/doc/qbk/07_concepts/BufferSequence.qbk b/doc/qbk/07_concepts/BufferSequence.qbk index a3f8dc64..86612ddb 100644 --- a/doc/qbk/07_concepts/BufferSequence.qbk +++ b/doc/qbk/07_concepts/BufferSequence.qbk @@ -1,5 +1,5 @@ [/ - Copyright (c) 2016-2017 Vinnie Falco (vinnie dot falco at gmail dot com) + 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) diff --git a/doc/qbk/07_concepts/DynamicBuffer.qbk b/doc/qbk/07_concepts/DynamicBuffer.qbk index 4b2d6a5f..3ea5b7aa 100644 --- a/doc/qbk/07_concepts/DynamicBuffer.qbk +++ b/doc/qbk/07_concepts/DynamicBuffer.qbk @@ -1,5 +1,5 @@ [/ - Copyright (c) 2016-2017 Vinnie Falco (vinnie dot falco at gmail dot com) + 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) diff --git a/doc/qbk/07_concepts/Fields.qbk b/doc/qbk/07_concepts/Fields.qbk index f0c06dd2..29d54805 100644 --- a/doc/qbk/07_concepts/Fields.qbk +++ b/doc/qbk/07_concepts/Fields.qbk @@ -1,5 +1,5 @@ [/ - Copyright (c) 2016-2017 Vinnie Falco (vinnie dot falco at gmail dot com) + 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) diff --git a/doc/qbk/07_concepts/FieldsWriter.qbk b/doc/qbk/07_concepts/FieldsWriter.qbk index d0a1a85a..f8d0af60 100644 --- a/doc/qbk/07_concepts/FieldsWriter.qbk +++ b/doc/qbk/07_concepts/FieldsWriter.qbk @@ -1,5 +1,5 @@ [/ - Copyright (c) 2016-2017 Vinnie Falco (vinnie dot falco at gmail dot com) + 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) diff --git a/doc/qbk/07_concepts/RatePolicy.qbk b/doc/qbk/07_concepts/RatePolicy.qbk index 80a4cef8..1f19ad98 100644 --- a/doc/qbk/07_concepts/RatePolicy.qbk +++ b/doc/qbk/07_concepts/RatePolicy.qbk @@ -7,7 +7,7 @@ Official repository: https://github.com/boostorg/beast ] -[section:RatePolicy RatePolicy] +[section:RatePolicy RatePolicy __new__] An instance of [*RatePolicy] is associated with a [link beast.ref.boost__beast__basic_stream `basic_stream`], diff --git a/doc/qbk/07_concepts/Streams.qbk b/doc/qbk/07_concepts/Streams.qbk index 63ddd8d9..54b2538d 100644 --- a/doc/qbk/07_concepts/Streams.qbk +++ b/doc/qbk/07_concepts/Streams.qbk @@ -1,5 +1,5 @@ [/ - Copyright (c) 2016-2017 Vinnie Falco (vinnie dot falco at gmail dot com) + 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) diff --git a/doc/qbk/08_design/0_design.qbk b/doc/qbk/08_design/0_design.qbk index 4586e101..19d434ce 100644 --- a/doc/qbk/08_design/0_design.qbk +++ b/doc/qbk/08_design/0_design.qbk @@ -1,5 +1,5 @@ [/ - Copyright (c) 2016-2017 Vinnie Falco (vinnie dot falco at gmail dot com) + 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) @@ -57,6 +57,7 @@ The following video presentation was delivered at in 2016. It provides a light introduction to some of the earliest interfaces of Beast (which have since changed). +[/ "Introducing Beast..."] [block''' diff --git a/doc/qbk/08_design/1_http_message.qbk b/doc/qbk/08_design/1_http_message.qbk index 06bab360..cd3154c3 100644 --- a/doc/qbk/08_design/1_http_message.qbk +++ b/doc/qbk/08_design/1_http_message.qbk @@ -1,5 +1,5 @@ [/ - Copyright (c) 2016-2017 Vinnie Falco (vinnie dot falco at gmail dot com) + 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) @@ -9,7 +9,7 @@ ] -[section HTTP Message Container] +[section:http_message_container HTTP Message Container __video__] The following video presentation was delivered at [@https://cppcon.org/ CppCon] @@ -18,6 +18,7 @@ process for the HTTP message container used in Beast. The slides and code used are available in the [@https://github.com/vinniefalco/CppCon2017 GitHub repository]. +[/ "Make Classes Great Again! (Using Concepts for Customization Points)"] [block''' diff --git a/doc/qbk/08_design/2_http_comparison.qbk b/doc/qbk/08_design/2_http_comparison.qbk index adb859fa..4909d9d1 100644 --- a/doc/qbk/08_design/2_http_comparison.qbk +++ b/doc/qbk/08_design/2_http_comparison.qbk @@ -1,5 +1,5 @@ [/ - Copyright (c) 2016-2017 Vinnie Falco (vinnie dot falco at gmail dot com) + 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) diff --git a/doc/qbk/08_design/3_websocket_zaphoyd.qbk b/doc/qbk/08_design/3_websocket_zaphoyd.qbk index bfa1119a..2f5d1f37 100644 --- a/doc/qbk/08_design/3_websocket_zaphoyd.qbk +++ b/doc/qbk/08_design/3_websocket_zaphoyd.qbk @@ -1,5 +1,5 @@ [/ - Copyright (c) 2016-2017 Vinnie Falco (vinnie dot falco at gmail dot com) + 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) diff --git a/doc/qbk/08_design/4_faq.qbk b/doc/qbk/08_design/4_faq.qbk index 6e965733..511a14c2 100644 --- a/doc/qbk/08_design/4_faq.qbk +++ b/doc/qbk/08_design/4_faq.qbk @@ -1,5 +1,5 @@ [/ - Copyright (c) 2016-2017 Vinnie Falco (vinnie dot falco at gmail dot com) + 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) diff --git a/doc/qbk/index.xml b/doc/qbk/index.xml index 0aa7e91d..5cf4cbf7 100644 --- a/doc/qbk/index.xml +++ b/doc/qbk/index.xml @@ -1,7 +1,7 @@