Documentation work

This commit is contained in:
Vinnie Falco committed 2017-06-09 18:07:20 -07:00
1 parent d4ec693a61
commit 9d5d4d56a4
46 files changed
+1264 -153

No files matched your search

+8 -5
View File
@@ -71,9 +71,11 @@
[def __static_buffer__ [link beast.ref.static_buffer `static_buffer`]]
[def __static_buffer_n__ [link beast.ref.static_buffer_n `static_buffer_n`]]
[import ../examples/file_body.hpp]
[import ../examples/http_example.cpp]
[import ../examples/websocket_example.cpp]
[import ../examples/echo_op.cpp]
[import ../examples/doc_core_samples.hpp]
[import ../examples/doc_http_samples.hpp]
[import ../test/core/doc_snippets.cpp]
[import ../test/http/doc_snippets.cpp]
@@ -83,11 +85,12 @@
[include 1_overview.qbk]
[include 2_examples.qbk]
[include 3_0_core.qbk]
[include 4_00_http.qbk]
[include 5_http_examples.qbk]
[include 6_0_websocket.qbk]
[include 7_concepts.qbk]
[include 8_0_design.qbk]
[include 4_0_network.qbk]
[include 5_00_http.qbk]
[include 6_0_http_examples.qbk]
[include 7_0_websocket.qbk]
[include 8_concepts.qbk]
[include 9_0_design.qbk]
[section:quickref Reference]
[xinclude quickref.xml]
+7 -7
View File
@@ -8,13 +8,13 @@
[section:overview Introduction]
[important
Beast is a cross-platform, header-only C++11 library for low-level
[*HTTP/1 and WebSocket protocol] programming
using the consistent asynchronous networking model of __Asio__.
Beast is not an HTTP client or HTTP server, but it can be used to
build those things. It is intended to be a foundation for writing
other interoperable libraries by providing HTTP vocabulary types
and algorithms. The provided examples show how clients and servers
Beast is a cross-platform, header-only C++11 library for
[*low-level HTTP/1, WebSocket, and network protocol] programming
using the consistent asynchronous model of __Asio__. Beast is
not an HTTP client or HTTP server, but it can be used to build
those things. It is intended to be a foundation for writing other
interoperable libraries by providing HTTP vocabulary types and
algorithms. The provided examples show how clients and servers
might be built.
]
+1 -2
View File
@@ -5,7 +5,7 @@
file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
]
[section:core Library Basics]
[section:core Using Networking]
A goal of the library is expose implementation primitives in order that
users may build their own library-like components. These primitives include
@@ -26,6 +26,5 @@ lists these facilities by group, with descriptions.
[include 3_2_streams.qbk]
[include 3_3_buffers.qbk]
[include 3_4_async.qbk]
[include 3_5_op_tutorial.qbk]
[endsect]
+1 -1
View File
@@ -15,7 +15,7 @@ customization of how the result of the asynchronous operation is conveyed to
callers. __Asio__ allows the special completion tokens __use_future__ and
objects of type __yield_context__ to allow callers to specify the use of futures
and coroutines respectively. This system, where the return value and method of
indicating completion may be customize at the call site of the asynchronous
indicating completion may be customized at the call site of the asynchronous
initiation function, is known as the ['Extensible Asynchronous Model] described
in __N3747__, and built-in to __N4588__.
+17
View File
@@ -0,0 +1,17 @@
[/
Copyright (c) 2013-2017 Vinnie Falco (vinnie dot falco at gmail dot com)
Distributed under the Boost Software License, Version 1.0. (See accompanying
file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
]
[section:network Network Examples]
These examples in this section are working functions that may be found
in the examples directory. They demonstrate the usage of the library
for a variety of scenarios.
[include 4_1_detect_tls.qbk]
[include 4_2_echo.qbk]
[endsect]
+64
View File
@@ -0,0 +1,64 @@
[/
Copyright (c) 2013-2017 Vinnie Falco (vinnie dot falco at gmail dot com)
Distributed under the Boost Software License, Version 1.0. (See accompanying
file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
]
[section:detect_tls TLS/SSL Detector Composed Operation]
In this example we will build a simple function to detect the presence
of the TLS handshake given an input buffer sequence. Then we build on
the example by adding synchronous stream algorithms. Finally, we
implemement an asynchronous detection function using a composed operation.
This SSL detector may be used to allow a server to accept both TLS and
unencrypted connections at the same port.
Here is the declaration for a function to detect the SSL client handshake.
The input to the function is simply a buffer sequence, no stream. This
allows the detection algorithm to be used elsewhere.
[core_sample_detect_tls_1]
The implementation checks the buffer for the presence of the SSL
Handshake message octet sequence and returns an apporopriate value:
[core_sample_detect_tls_2]
Now we define a stream operation. We start with the simple,
synchronous version which takes the stream and buffer as input:
[core_sample_detect_tls_3]
The synchronous algorithm is the model for building the asynchronous
operation which has more boilerplate. First, we declare the asynchronous
initiation function:
[core_sample_detect_tls_4]
The implementation of the initiation function is straightforward
and contains mostly boilerplate. It is to construct the return
type customization helper to obtain the actual handler, and
then create the composed operation and launch it. The actual
code for interacting with the stream is in the composed operation,
which is written as a separate class.
[core_sample_detect_tls_5]
Now we will declare our composed operation. There is a considerable
amount of necessary boilerplate to get this right, but the result
is worth the effort.
[core_sample_detect_tls_6]
The boilerplate is all done, and now we need to implemnt the function
call operator that turns this composed operation a completion handler
with the signature `void(error_code, std::size_t)` which is exactly
the signature needed when performing asynchronous reads. This function
is a transformation of the synchronous version of `detect_ssl` above,
but with the inversion of flow that characterizes code written in the
callback style:
[core_sample_detect_tls_7]
[endsect]
+5 -4
View File
@@ -5,12 +5,13 @@
file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
]
[section:op_tutorial Writing a Composed Operation]
[section:echo Echo Composed Operation]
To illustrate the usage of the asynchronous helpers in the core section of
this library, we will develop a simple asynchronous composed operation called
Here we developed a more advanced asynchronous composed operation called
[*echo]. This operation will read up to the first newline on a stream, and
then write the same line including the newline back on the stream.
then write the same line including the newline back on the stream. The
implementation performs both reading and writing, and has a
non-trivially-copyable state.
First we define the input parameters and results, then declare our initiation
function. For our echo operation the only inputs are the stream and the
+9 -9
View File
@@ -78,14 +78,14 @@ format using __Asio__. Specifically, the library provides:
[http_snippet_1]
]
[include 4_01_primer.qbk]
[include 4_02_message.qbk]
[include 4_03_streams.qbk]
[include 4_04_serializer_streams.qbk]
[include 4_05_parser_streams.qbk]
[include 4_06_serializer_buffers.qbk]
[include 4_07_parser_buffers.qbk]
[include 4_08_custom_parsers.qbk]
[include 4_09_custom_body.qbk]
[include 5_01_primer.qbk]
[include 5_02_message.qbk]
[include 5_03_streams.qbk]
[include 5_04_serializer_streams.qbk]
[include 5_05_parser_streams.qbk]
[include 5_06_serializer_buffers.qbk]
[include 5_07_parser_buffers.qbk]
[include 5_08_custom_parsers.qbk]
[include 5_09_custom_body.qbk]
[endsect]
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
@@ -11,6 +11,28 @@ These examples in this section are working functions that may be found
in the examples directory. They demonstrate the usage of the library for
a variety of scenarios.
[section Change Body Type]
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
depending on the header contents. For example, depending on the verb,
target path, or target query parameters. To accomplish this, a parser
is declared to read in the header only, using a trivial body type such as
[link beast.ref.http__empty_body `empty_body`]. Then, a new parser is constructed
from this existing parser where the body type is conditionally determined
by information from the header or elsewhere.
This example illustrates how a server may make the commitment of a body
type depending on the method verb:
[http_sample_defer_body]
[endsect]
[section Expect 100-continue (Client)]
The Expect field with the value "100-continue" in a request is special. It
@@ -48,6 +70,10 @@ synchronous version of this server action looks like this:
[include 6_1_file_body.qbk]
[section HEAD request (Client)]
The
@@ -75,21 +101,21 @@ if the method was GET, except that the body is omitted.
[section Write To std::ostream]
[section HTTP Relay]
The standard library provides the type `std::ostream` for performing high
level write operations on character streams. The variable `std::cout` is
based on this output stream. In this example, we build a stream operation
which serializes an HTTP message to a `std::ostream`:
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
of the headers and representation of the body along the way. Then, the
proxy reads a response from the server and sends it back to the client,
also with the possibility of changing the headers and body representation.
[http_sample_write_ostream]
The example that follows implements a synchronous HTTP relay. It uses a
fixed size buffer, to avoid reading in the entire body so that the upstream
connection sees a header without unnecessary latency. This example brings
together all of the concepts discussed so far, it uses both a __serializer__
and a __parser__ to achieve its goal:
[tip
Serializing to a `std::ostream` could be implemented using an alternate
strategy: adapt the `std::ostream` interface to a __SyncWriteStream__.
This lets all the library's existing algorithms work on `std::ostream`.
We leave this as an exercise for the reader.
]
[http_sample_relay]
[endsect]
@@ -138,43 +164,21 @@ HTTP response. The output of the process is sent as it becomes available:
[section Defer Body Type]
[section Write To std::ostream]
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
depending on the header contents. For example, depending on the verb,
target path, or target query parameters. To accomplish this, a parser
is declared to read in the header only, using a trivial body type such as
[link beast.ref.http__empty_body `empty_body`]. Then, a new parser is constructed
from this existing parser where the body type is conditionally determined
by information from the header or elsewhere.
The standard library provides the type `std::ostream` for performing high
level write operations on character streams. The variable `std::cout` is
based on this output stream. In this example, we build a stream operation
which serializes an HTTP message to a `std::ostream`:
This example illustrates how a server may make the commitment of a body
type depending on the method verb:
[http_sample_write_ostream]
[http_sample_defer_body]
[endsect]
[section HTTP Relay]
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
of the headers and representation of the body along the way. Then, the
proxy reads a response from the server and sends it back to the client,
also with the possibility of changing the headers and body representation.
The example that follows implements a synchronous HTTP relay. It uses a
fixed size buffer, to avoid reading in the entire body so that the upstream
connection sees a header without unnecessary latency. This example brings
together all of the concepts discussed so far, it uses both a __serializer__
and a __parser__ to achieve its goal:
[http_sample_relay]
[tip
Serializing to a `std::ostream` could be implemented using an alternate
strategy: adapt the `std::ostream` interface to a __SyncWriteStream__.
This lets all the library's existing algorithms work on `std::ostream`.
We leave this as an exercise for the reader.
]
[endsect]
+52
View File
@@ -0,0 +1,52 @@
[/
Copyright (c) 2013-2017 Vinnie Falco (vinnie dot falco at gmail dot com)
Distributed under the Boost Software License, Version 1.0. (See accompanying
file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
]
[section File Body Type]
Use of the flexible __Body__ concept customization point enables authors to
preserve the self-contained nature of the __message__ object while allowing
domain specific behaviors. Common operations for HTTP servers include sending
responses which deliver file contents, and allowing for file uploads. In this
example we build the `file_body` type which supports both reading and writing
to a file on the file system.
First we declare the type itself, along with the required members:
[http_sample_file_body_1]
The `size` function is a simple call to retrieve the file size:
[http_sample_file_body_2]
Our implementation of __BodyReader__ will contain a small buffer
from which the file contents are read. The buffer is provided to
the implementation on each call until everything has been read in.
[http_sample_file_body_3]
And here are the definitions for the functions we have declared:
[http_sample_file_body_4]
Files can be read now, and the next step is to allow writing to files
by implementing the __BodyWriter__. The style is similar to the reader,
except that buffers are incoming instead of outgoing. Here's the
declaration:
[http_sample_file_body_5]
Finally, here is the implementation of the writer member functions:
[http_sample_file_body_6]
We have created a full featured body type capable of reading and
writing files on the filesystem, integrating seamlessly with the
HTTP algorithms and message container. Source code for this body
type, and HTTP servers that use it, are available in the examples
directory.
[endsect]
@@ -27,12 +27,12 @@ Boost.Asio with a consistent asynchronous model using a modern C++ approach.
[ws_snippet_1]
]
[include 6_1_streams.qbk]
[include 6_2_connect.qbk]
[include 6_3_client.qbk]
[include 6_4_server.qbk]
[include 6_5_messages.qbk]
[include 6_6_control.qbk]
[include 6_7_notes.qbk]
[include 7_1_streams.qbk]
[include 7_2_connect.qbk]
[include 7_3_client.qbk]
[include 7_4_server.qbk]
[include 7_5_messages.qbk]
[include 7_6_control.qbk]
[include 7_7_notes.qbk]
[endsect]
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
@@ -7,8 +7,6 @@
[section:concept Concepts]
[include concept/Body.qbk]
[include concept/BodyReader.qbk]
[include concept/BodyWriter.qbk]
+4 -4
View File
@@ -50,9 +50,9 @@ start. Other design goals:
* Allow for customizations, if the user needs it.
[include 8_1_http_message.qbk]
[include 8_2_http_comparison.qbk]
[include 8_3_websocket_zaphoyd.qbk]
[include 8_4_faq.qbk]
[include 9_1_http_message.qbk]
[include 9_2_http_comparison.qbk]
[include 9_3_websocket_zaphoyd.qbk]
[include 9_4_faq.qbk]
[endsect]
File renamed without changes.
File renamed without changes.
File renamed without changes.
View File
File renamed without changes.