rippled/doc/beast.qbk

[/
    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+]

Most of the library is header-only; however, the HTTP parser used is written
in C. To link an application that uses Beast, it is necessary to add a single
.cpp file from beast into your project's build script.

[endsect]



[section:example Examples]

These usage examples are intended to quickly impress upon readers the
flavor of the library.

[note
    All examples and identifiers mentioned in this document are written as
    if the following statements are in effect:
```
    #include <boost/asio.hpp>
    #include <beast/http.hpp>
    #include <beast/websocket.hpp>
    using namespace beast;
    using namespace boost::asio;
```
]

Use HTTP to request the root page from a website and receive the response:
```
    std::string const host = "boost.org";
    io_service ios;
    ip::tcp::resolver r(ios);
    ip::tcp::socket sock(ios);
    connect(sock, r.resolve(ip::tcp::resolver::query{host, "http"}));

    http::request<http::empty_body> req(http::method_t::http_get, "/", 11);
    req.headers.replace("Host", host + ":" + std::to_string(sock.remote_endpoint().port()));
    req.headers.replace("User-Agent", "Beast");
    write(sock, req);

    http::response<http::streambuf_body> resp;
    read(sock, resp);
    ...
```

Establish a WebSocket connection, send a message and receive the reply:
```
    std::string const host = "boost.org";
    io_service ios;
    tcp::resolver r(ios);
    tcp::socket sock(ios);
    connect(sock, r.resolve(tcp::resolver::query{host, "ws"}));

    websocket::stream<ip::tcp::socket&> ws(sock);
    ws.handshake();
    ws.write(ws, buffer("Hello, world!"));

    streambuf sb;
    websocket::opcode op;
    ws.read(ws, op, sb);

    ws.close(); // WebSocket protocol close
```

[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]