mirror of
https://github.com/XRPLF/rippled.git
synced 2025-12-06 17:27:55 +00:00
47dc31d8c2
* Fix warnings * Port cmake scripts to linux * Add command line options for running test suites * Add examples to CMakeLists * Return std::uint64_t from writer::content_length * basic_parser::write takes asio::const_buffer instead of pointer and size * Turn message test back on now that it passes * Rename to http::headers, use std::allocator, remove http_headers * http::message::method is now a string * Refactor to_string for ConstBufferSequence * Remove chunk_encode from the public interface * Initialize members for default constructed iterators * Disallow default construction for dependent buffer sequences Refactor http::message serialization: * Serialization no longer creates a copy of the headers and modifies them * New function prepare(), sets Connection, Transfer-Encoding, Content-Length based on the body attributes and caller options. Callers can use prepare() to have the fields set automatically, or they can set the fields manually. * Use write for operator<< * Tests for serialization
198 lines
6.7 KiB
Plaintext
198 lines
6.7 KiB
Plaintext
[/
|
|
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)
|
|
]
|
|
|
|
[library Beast
|
|
[quickbook 1.6]
|
|
[copyright 2013 - 2016 Vinnie Falco]
|
|
[purpose C++ Library]
|
|
[license
|
|
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])
|
|
]
|
|
[authors [Falco, Vinnie]]
|
|
[category template]
|
|
[category generic]
|
|
]
|
|
|
|
[template mdash[] '''— ''']
|
|
[template indexterm1[term1] '''<indexterm><primary>'''[term1]'''</primary></indexterm>''']
|
|
[template indexterm2[term1 term2] '''<indexterm><primary>'''[term1]'''</primary><secondary>'''[term2]'''</secondary></indexterm>''']
|
|
[template ticket[number]'''<ulink url="https://svn.boost.org/trac/boost/ticket/'''[number]'''">'''#[number]'''</ulink>''']
|
|
[def __POSIX__ /POSIX/]
|
|
[def __Windows__ /Windows/]
|
|
[def __accept__ [@http://www.opengroup.org/onlinepubs/000095399/functions/accept.html `accept()`]]
|
|
[def __connect__ [@http://www.opengroup.org/onlinepubs/000095399/functions/connect.html `connect()`]]
|
|
[def __getpeername__ [@http://www.opengroup.org/onlinepubs/000095399/functions/getpeername.html `getpeername()`]]
|
|
[def __getsockname__ [@http://www.opengroup.org/onlinepubs/000095399/functions/getsockname.html `getsockname()`]]
|
|
[def __getsockopt__ [@http://www.opengroup.org/onlinepubs/000095399/functions/getsockopt.html `getsockopt()`]]
|
|
[def __ioctl__ [@http://www.opengroup.org/onlinepubs/000095399/functions/ioctl.html `ioctl()`]]
|
|
[def __recvfrom__ [@http://www.opengroup.org/onlinepubs/000095399/functions/recvfrom.html `recvfrom()`]]
|
|
[def __sendto__ [@http://www.opengroup.org/onlinepubs/000095399/functions/sendto.html `sendto()`]]
|
|
[def __setsockopt__ [@http://www.opengroup.org/onlinepubs/000095399/functions/setsockopt.html `setsockopt()`]]
|
|
[def __socket__ [@http://www.opengroup.org/onlinepubs/000095399/functions/socket.html `socket()`]]
|
|
|
|
|
|
|
|
[section:intro Introduction]
|
|
|
|
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.WebSocket
|
|
provides a complete implementation of the WebSocket protocol. Their design
|
|
achieves these goals:
|
|
|
|
* [*Symmetry.] Interfaces are role-agnostic; the same interfaces can be
|
|
used to build clients, servers, or both.
|
|
|
|
* [*Ease of Use.] HTTP messages are modeled using simple, readily
|
|
accessible objects. Functions and classes used to send and receive HTTP
|
|
or WebSocket messages are designed to resemble Boost.Asio as closely as
|
|
possible. Users familiar with Boost.Asio will be immediately comfortable
|
|
using this library.
|
|
|
|
* [*Flexibility.] Interfaces do not mandate specific implementation
|
|
strategies; important decisions such as buffer or thread management are
|
|
left to users of the library.
|
|
|
|
* [*Performance.] The implementation performs competitively, making it a
|
|
realistic choice for building a high performance network server.
|
|
|
|
* [*Scalability.] Development of network applications that scale to thousands
|
|
of concurrent connections is possible with the implementation.
|
|
|
|
* [*Basis for further abstraction.] The interfaces facilitate the
|
|
development of other libraries that provide higher levels of abstraction.
|
|
|
|
|
|
|
|
[section:requirements Requirements]
|
|
|
|
Beast requires:
|
|
|
|
* [*C++11.] A minimum of C++11 is needed.
|
|
* [*Boost.] Beast is built on Boost, especially Boost.Asio.
|
|
* [*OpenSSL.] If using TLS/Secure sockets (optional).
|
|
|
|
[note Tested compilers: msvc-14+, gcc 5+, clang 3.6+]
|
|
|
|
The library is [*header-only]. It is not necessary to add any .cpp files,
|
|
or to edit your existing build script or project file except to provide
|
|
that the include/ directory for beast is searched for include files.
|
|
|
|
[endsect]
|
|
|
|
|
|
|
|
[section:example Examples]
|
|
|
|
These usage examples are intended to quickly impress upon readers the
|
|
flavor of the library. They are complete programs which may be built
|
|
and run. Source code and build scripts for these programs may be found
|
|
in the examples directory.
|
|
|
|
Use HTTP to request the root page from a website and print the response:
|
|
```
|
|
#include <beast/http.hpp>
|
|
#include <boost/asio.hpp>
|
|
#include <iostream>
|
|
#include <string>
|
|
|
|
int main()
|
|
{
|
|
// Normal boost::asio setup
|
|
std::string const host = "boost.org";
|
|
boost::asio::io_service ios;
|
|
boost::asio::ip::tcp::resolver r(ios);
|
|
boost::asio::ip::tcp::socket sock(ios);
|
|
boost::asio::connect(sock,
|
|
r.resolve(boost::asio::ip::tcp::resolver::query{host, "http"}));
|
|
|
|
using namespace beast::http;
|
|
|
|
// Send HTTP request using beast
|
|
request<empty_body> req({"GET", "/", 11});
|
|
req.headers.replace("Host", host + ":" + std::to_string(sock.remote_endpoint().port()));
|
|
req.headers.replace("User-Agent", "Beast");
|
|
prepare(req);
|
|
write(sock, req);
|
|
|
|
// Receive and print HTTP response using beast
|
|
beast::streambuf sb;
|
|
response<streambuf_body> resp;
|
|
read(sock, sb, resp);
|
|
std::cout << resp;
|
|
}
|
|
```
|
|
|
|
Establish a WebSocket connection, send a message and receive the reply:
|
|
```
|
|
#include <beast/to_string.hpp>
|
|
#include <beast/websocket.hpp>
|
|
#include <boost/asio.hpp>
|
|
#include <iostream>
|
|
#include <string>
|
|
|
|
int main()
|
|
{
|
|
// Normal boost::asio setup
|
|
std::string const host = "echo.websocket.org";
|
|
boost::asio::io_service ios;
|
|
boost::asio::ip::tcp::resolver r(ios);
|
|
boost::asio::ip::tcp::socket sock(ios);
|
|
boost::asio::connect(sock,
|
|
r.resolve(boost::asio::ip::tcp::resolver::query{host, "80"}));
|
|
|
|
using namespace beast::websocket;
|
|
|
|
// WebSocket connect and send message using beast
|
|
stream<boost::asio::ip::tcp::socket&> ws(sock);
|
|
ws.handshake(host, "/");
|
|
ws.write(boost::asio::buffer("Hello, world!"));
|
|
|
|
// Receive WebSocket message, print and close using beast
|
|
beast::streambuf sb;
|
|
opcode op;
|
|
ws.read(op, sb);
|
|
ws.close(close_code::normal);
|
|
std::cout << to_string(sb.data()) << "\n";
|
|
}
|
|
```
|
|
|
|
[endsect]
|
|
|
|
|
|
|
|
[section:credits Credits]
|
|
|
|
Beast would not be possible without the considerable time and patience
|
|
contributed by David Schwartz, Edward Hennis, Howard Hinnant, Miguel Portilla,
|
|
Nikolaos Bougalis, Scott Determan, Scott Schurr, and Ripple Labs for
|
|
supporting its development. Thanks also to Christopher Kohloff, whose Asio
|
|
C++ library is the inspiration behind which much of the design and
|
|
documentation is based.
|
|
|
|
[endsect]
|
|
|
|
|
|
|
|
[endsect]
|
|
|
|
|
|
|
|
[include http.qbk]
|
|
[include websocket.qbk]
|
|
[include types.qbk]
|
|
[include design.qbk]
|
|
[section:quickref Quick Reference]
|
|
[xinclude quickref.xml]
|
|
[endsect]
|
|
[include reference.qbk]
|
|
[section:idx Index]
|
|
[xinclude index.xml]
|
|
[endsect]
|