feedc0de/boost_beast
1
0 Fork 0
forked from boostorg/beast
Code Pull Requests Activity

Refactor all examples:

Browse Source 
fix #575, fix #604, fix #608, fix #634, fix #712

All examples are rewritten:

* Using Best Practices
* Mostly self-contained
* New examples to complete the feature matrix
* The server-framework example is removed
This commit is contained in:
Vinnie Falco committed 2017-08-07 20:53:11 -07:00
1 parent 20a8f7d75b
commit dd71b0f94d
187 files changed
+11759 -7098
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

doc/images/server.png
BIN
View File
Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 19 KiB

doc/qbk/00_main.qbk
+2 -2
View File
@@ -85,8 +85,8 @@
[import ../../example/common/detect_ssl.hpp]
[import ../../example/doc/http_examples.hpp]
[import ../../example/echo-op/echo_op.cpp]
[import ../../example/http-client/http_client.cpp]
[import ../../example/websocket-client/websocket_client.cpp]
[import ../../example/http/client/sync/http_client_sync.cpp]
[import ../../example/websocket/client/sync/websocket_client_sync.cpp]
[import ../../include/boost/beast/http/basic_file_body.hpp]
doc/qbk/02_examples.qbk
+175 -107
View File
@@ -14,13 +14,11 @@ 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 example/ directory.
[section HTTP Client]
Use HTTP to make a GET request to a website and print the response:
File: [repo_file example/http-client/http_client.cpp]
File: [repo_file example/http/client/sync/http_client_sync.cpp]
[example_http_client]
@@ -30,7 +28,7 @@ File: [repo_file example/http-client/http_client.cpp]
Establish a WebSocket connection, send a message and receive the reply:
File: [repo_file example/websocket-client/websocket_client.cpp]
File: [repo_file example/websocket/client/sync/websocket_client_sync.cpp]
[example_websocket_client]
@@ -44,85 +42,196 @@ File: [repo_file example/websocket-client/websocket_client.cpp]
[block'''<?dbhtml stop-chunking?>''']
Source code and build scripts for these programs are located
in the example/ directory.
in the [repo_file example] directory.
[section HTTP Crawl]
[template example_src[path name] '''<ulink url="../../'''[path]'''">'''[name]'''</ulink>''']
This example retrieves the page at each of the most popular domains
as measured by Alexa.
[heading Clients]
* [repo_file example/http-crawl/http_crawl.cpp]
These HTTP clients submit a GET request to a server specified on the command
line, and prints the resulting response. The crawl client asynchronously
fetches the document root of the 10,000 top ranked domains, this may be
used to evaluate robustness.
[endsect]
[table
[[Description] [Source File] [Source File (using SSL)]]
[
[HTTP, synchronous]
[[example_src example/http/client/sync/http_client_sync.cpp http_client_sync.cpp]]
[[example_src example/http/client/sync-ssl/http_client_sync_ssl.cpp http_client_sync_ssl.cpp]]
][
[HTTP, asynchronous]
[[example_src example/http/client/async/http_client_async.cpp http_client_async.cpp]]
[[example_src example/http/client/async-ssl/http_client_async_ssl.cpp http_client_async_ssl.cpp]]
][
[HTTP, coroutine]
[[example_src example/http/client/coro/http_client_coro.cpp http_client_coro.cpp]]
[[example_src example/http/client/coro-ssl/http_client_coro_ssl.cpp http_client_coro_ssl.cpp]]
][
[HTTP crawl (asynchronous)]
[[example_src example/http/client/crawl/http_crawl.cpp http_crawl.cpp]]
[]
]]
These WebSocket clients connect to a
server and send a message, then receive a message and print the response
before disconnecting.
[table
[[Description] [Source File] [Source File (using SSL)]]
[
[WebSocket, synchronous]
[[example_src example/websocket/client/sync/websocket_client_sync.cpp websocket_client_sync.cpp]]
[[example_src example/websocket/client/sync-ssl/websocket_client_sync_ssl.cpp websocket_client_sync_ssl.cpp]]
][
[WebSocket, asynchronous]
[[example_src example/websocket/client/async/websocket_client_async.cpp websocket_client_async.cpp]]
[[example_src example/websocket/client/async-ssl/websocket_client_async_ssl.cpp websocket_client_async_ssl.cpp]]
][
[WebSocket, coroutine]
[[example_src example/websocket/client/coro/websocket_client_coro.cpp websocket_client_coro.cpp]]
[[example_src example/websocket/client/coro-ssl/websocket_client_coro_ssl.cpp websocket_client_coro_ssl.cpp]]
]]
[section HTTP Client (with SSL)]
[heading Servers]
This example demonstrates sending and receiving HTTP messages
over a TLS connection. Requires OpenSSL to build.
These HTTP servers deliver files from a root directory specified on the
command line.
* [repo_file example/http-client-ssl/http_client_ssl.cpp]
[table
[[Description] [Source File] [Source File (using SSL)]]
[
[HTTP, synchronous]
[[example_src example/http/server/sync/http_server_sync.cpp http_server_sync.cpp]]
[[example_src example/http/server/sync-ssl/http_server_sync_ssl.cpp http_server_sync_ssl.cpp]]
][
[HTTP, asynchronous]
[[example_src example/http/server/async/http_server_async.cpp http_server_async.cpp]]
[[example_src example/http/server/async-ssl/http_server_async_ssl.cpp http_server_async_ssl.cpp]]
][
[HTTP, coroutine]
[[example_src example/http/server/coro/http_server_coro.cpp http_server_coro.cpp]]
[[example_src example/http/server/coro-ssl/http_server_coro_ssl.cpp http_server_coro_ssl.cpp]]
][
[HTTP, stackless coroutine]
[[example_src example/http/server/stackless/http_server_stackless.cpp http_server_stackless.cpp]]
[[example_src example/http/server/stackless-ssl/http_server_stackless_ssl.cpp http_server_stackless_ssl.cpp]]
][
[HTTP, fast (optimized for speed)]
[[example_src example/http/server/fast/http_server_fast.cpp http_server_fast.cpp]]
[]
][
[HTTP, small (optimized for space)]
[[example_src example/http/server/small/http_server_small.cpp http_server_small.cpp]]
[]
][
[HTTP, flex (plain + SSL)]
[]
[[example_src example/http/server/flex/http_server_flex.cpp http_server_flex.cpp]]
]]
[endsect]
These WebSocket servers echo back any message received, keeping the
session open until the client disconnects.
[table
[[Description] [Source File] [Source File (using SSL)]]
[
[WebSocket, synchronous]
[[example_src example/websocket/server/sync/websocket_server_sync.cpp websocket_server_sync.cpp]]
[[example_src example/websocket/server/sync-ssl/websocket_server_sync_ssl.cpp websocket_server_sync_ssl.cpp]]
][
[WebSocket, asynchronous]
[[example_src example/websocket/server/async/websocket_server_async.cpp websocket_server_async.cpp]]
[[example_src example/websocket/server/async-ssl/websocket_server_async_ssl.cpp websocket_server_async_ssl.cpp]]
][
[WebSocket, coroutine]
[[example_src example/websocket/server/coro/websocket_server_coro.cpp websocket_server_coro.cpp]]
[[example_src example/websocket/server/coro-ssl/websocket_server_coro_ssl.cpp websocket_server_coro_ssl.cpp]]
][
[WebSocket, stackless coroutine]
[[example_src example/websocket/server/stackless/websocket_server_stackless.cpp websocket_server_stackless.cpp]]
[[example_src example/websocket/server/stackless-ssl/websocket_server_stackless_ssl.cpp websocket_server_stackless_ssl.cpp]]
][
[WebSocket, fast (suited for benchmarks)]
[[example_src example/websocket/server/fast/websocket_server_fast.cpp websocket_server_fast.cpp]]
[]
]]
[heading Advanced Servers]
[section HTTP Server (Fast)]
These servers offer both HTTP and WebSocket services on the same port,
and illustrate the implementation of advanced features.
This example implements a very simple HTTP server with
some optimizations suitable for calculating benchmarks.
[table
[[Description] [Features] [Source File]]
[
[Advanced]
[[itemized_list
[HTTP pipelining]
[Asynchronous timeouts]
[Dual protocols: HTTP and WebSocket]]]
[[example_src example/advanced/server/advanced_server.cpp advanced_server.cpp]]
][
[Advanced, flex (plain + SSL)]
[[itemized_list
[HTTP pipelining]
[Asynchronous timeouts]
[Dual protocols: HTTP and WebSocket]
[Flexible ports; plain and SSL on the same port]]]
[[example_src example/advanced/server-flex/advanced_server_flex.cpp advanced_server_flex.cpp]]
]]
* [repo_file example/http-server-fast/fields_alloc.hpp]
* [repo_file example/http-server-fast/http_server_fast.cpp]
[heading Common Files]
[endsect]
Some of the examples use one or more shared header files, they are
listed here along with a description of their use:
[section HTTP Server (Small)]
This example implements a very simple HTTP server
suitable as a starting point on an embedded device.
* [repo_file example/http-server-small/http_server_small.cpp]
[endsect]
[section HTTP Server (Threaded)]
This example implements a very simple HTTP server using
synchronous interfaces and using one thread per connection:
* [repo_file example/http-server-threaded/http_server_threaded.cpp]
[endsect]
[section WebSocket Client (with SSL)]
Establish a WebSocket connection over an encrypted TLS connection,
send a message and receive the reply. Requires OpenSSL to build.
* [repo_file example/websocket-client-ssl/websocket_client_ssl.cpp]
[endsect]
[section WebSocket Server (Asynchronous)]
This program implements a WebSocket echo server using asynchronous
interfaces and a configurable number of threads.
* [repo_file example/websocket-server-async/websocket_server_async.cpp]
[endsect]
[table
[[Source File] [Description]]
[
[[repo_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.
]
][
[[repo_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.
]
][
[[repo_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.
]
][
[[repo_file example/common/ssl_stream.hpp]]
[
The `ssl_stream` is a replacement for `boost::asio::ssl::stream`
which supports construction from a moved-froms ocket and is also
itself move constructible.
]
][
[[repo_file example/common/write_msg.hpp]]
[
The function `async_write_msg` takes ownership of an HTTP message
using the move constructor, and sends it asynchronously. It is
used as a convenience for managing the lifetime of temporary
objects, as well as for implementing HTTP pipelining.
]
]]
@@ -143,7 +252,8 @@ in your program without modification
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 the Core Foundations document section.
the example described in
[link beast.using_io.writing_composed_operations.echo Writing Composed Operations: Echo].
* [repo_file example/echo-op/echo_op.cpp]
@@ -151,46 +261,4 @@ the example described in the Core Foundations document section.
[section Common Code]
This code is reused between some of the examples. The header files
stand alone can be directly included in your projects.
* [repo_file example/common/detect_ssl.hpp]
* [repo_file example/common/helpers.hpp]
* [repo_file example/common/mime_types.hpp]
* [repo_file example/common/rfc7231.hpp]
* [repo_file example/common/ssl_stream.hpp]
* [repo_file example/common/write_msg.hpp]
[endsect]
[section Server Framework]
This is a complete program and framework of classes implementing
a general purpose server that users may copy to use as the basis
for writing their own servers. It serves both HTTP and WebSocket.
* [repo_file example/server-framework/file_service.hpp]
* [repo_file example/server-framework/framework.hpp]
* [repo_file example/server-framework/http_async_port.hpp]
* [repo_file example/server-framework/http_base.hpp]
* [repo_file example/server-framework/http_sync_port.hpp]
* [repo_file example/server-framework/https_ports.hpp]
* [repo_file example/server-framework/main.cpp]
* [repo_file example/server-framework/multi_port.hpp]
* [repo_file example/server-framework/server.hpp]
* [repo_file example/server-framework/service_list.hpp]
* [repo_file example/server-framework/ssl_certificate.hpp]
* [repo_file example/server-framework/ws_async_port.hpp]
* [repo_file example/server-framework/ws_sync_port.hpp]
* [repo_file example/server-framework/ws_upgrade_service.hpp]
* [repo_file example/server-framework/wss_ports.hpp]
[endsect]
[endsect]