[boost] Boost.HTTPKit, a new library from the makers of Beast!

Subject: [boost] Boost.HTTPKit, a new library from the makers of Beast!
From: Vinnie Falco (vinnie.falco_at_[hidden])
Date: 2017-10-04 15:22:28

During the formal review of Beast the desire was expressed to have
parsing and serialization available independently of Asio.
Unfortunately the obstacles to this are the concrete functions and
types required for interoperability with the buffer sequence concepts
defined in Asio.

I have drawn up a solution to this problem which involves creating two
brand new libraries.

The first new library is called Boost.Buffers, and I described it
partially in an earlier list posting. This library will contain copies
of just the header files from Asio needed to implement the buffer
sequence concepts. A preprocessor switch will allow users of
Boost.Buffers to decide whether to use the copies of the headers, or
to just include the Asio headers directly:

<https://github.com/vinniefalco/buffers/blob/30ef7031ec0909972a720c0cdd8d6c6e1cc9e37b/include/boost/buffers/asio.hpp#L13>

If an author wants to develop a library which uses just the buffer
sequence concepts from Asio, then instead of writing:

    #include <boost/asio/buffer.hpp>

they will instead write:

    #include <boost/buffers/asio.hpp>

in header files, and in their build scripts set:

    #define BOOST_NET_BUFFER_NO_ASIO 1

This way, their tests and example programs will use the copies of the
asio headers found in the Boost.Buffers libraries and everything will
work. Boost.Asio will not be a dependency.

However, if a consumer of that library wants to also use Boost.Asio,
they can do so by just not setting the macro in their build scripts
(or explicitly setting it to 0).

Now that we have a way to write a library that uses Asio buffer
concepts without depending on all of Asio, we can move the Beast
dynamic buffer implementations and buffer adapters into the
Boost.Buffers library.

Boost.Buffers will contain these public includes:

Boost.Buffers
    <boost/buffers.hpp>
    <boost/buffers/asio.hpp>
        boost::asio::const_buffer
        boost::asio::const_buffers_1
        boost::asio::mutable_buffer
        boost::asio::mutable_buffers_1
        boost::asio::buffer_copy
        boost::asio::buffer_size
        boost::asio::buffer_cast
        boost::asio:is_const_buffer_sequence
        boost::asio:is_mutable_buffer_sequence
    <boost/buffers/buffers_adapter.hpp>
    <boost/buffers/buffers_cat.hpp>
    <boost/buffers/buffers_prefix.hpp>
    <boost/buffers/buffers_suffix.hpp>
    <boost/buffers/buffers_to_string.hpp>
    <boost/buffers/flat_buffer.hpp>
    <boost/buffers/flat_static_buffer.hpp>
    <boost/buffers/multi_buffer.hpp>
    <boost/buffers/ostream.hpp>
    <boost/buffers/read_size.hpp>
    <boost/buffers/static_buffer.hpp>

Boost.Buffers would have dependencies on these Boost libraries:

    Array
    Assert
    Config
    Core
    Exception
    Intrusive
    StaticAssert
    ThrowException
    TypeTraits

Beast will then be modified to take a dependency on Boost.Buffers to
have access to all the buffer adapters and dynamic buffer
implementations.

Now that we have a new library which offers Asio buffer concepts and
Beast's collection of useful dynamic buffers and buffer adapters, we
can extract the HTTP parsing and serialization algorithms from Beast
to form a new library:

Boost.HTTPKit will contain these public includes:

Boost.HTTPKit
    <boost/http/basic_file_body.hpp>
    <boost/http/basic_dynamic_body.hpp>
    <boost/http/basic_parser.hpp>
    <boost/http/buffer_body.hpp>
    <boost/http/chunk_encode.hpp>
    <boost/http/dynamic_body.hpp>
    <boost/http/empty_body.hpp>
    <boost/http/parse_error.hpp>
    <boost/http/field.hpp>
    <boost/http/fields.hpp>
    <boost/http/message.hpp>
    <boost/http/parser.hpp>
    <boost/http/rfc7230.hpp>
    <boost/http/serializer.hpp>
    <boost/http/span_body.hpp>
    <boost/http/status.hpp>
    <boost/http/string_body.hpp>
    <boost/http/string_param.hpp>
    <boost/http/type_traits.hpp>
    <boost/http/vector_body.hpp>
    <boost/http/verb.hpp>

Boost.HTTPKit would have dependencies on these Boost libraries:

    Array
    Assert
    Config
    Core
    Exception
    Intrusive
    StaticAssert
    ThrowException
    TypeTraits

This new library provides serialization and parsing of HTTP/1 messages
to and from Asio buffer sequences, without requiring the full
Boost.Asio dependency. The library also provides Beast's universal
HTTP message container.

Beast will be modified to take an additional dependency on Boost.HTTPKit.

This solution satisfies long-stated needs of users to have HTTP
parsing and serialization without Boost.Asio.

However, there is one problem and that is the documentation. All of
Beast's documentation related to buffer-oriented parsing and
serialization, message containers, Body types, Fields concept, buffer
sequences, and dynamic buffers will now be moved into two other
libraries. This leaves the Beast documentation objectively worse off
for users, as it is impossible to cross-link to other library
documentation from inside a Javadoc comment extracted by Doxygen. I
would like to hear ideas for how to smooth this out.

Questions:

How does the community feel about:

* Boost.Buffers as a solution to accessing buffer concepts without Asio?

* Boost.Buffers offering Beast's buffer sequence adapters and dynamic buffers?

* Boost.HTTPKit depending on Boost.Buffers?

* Boost.HTTPKit offering serialization and parsing without Asio?

Any feedback is appreciated

Thanks