[/
    Copyright (c) 2016-2019 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)

    Official repository: https://github.com/boostorg/beast
]

[section:using_http HTTP]

[warning
    Higher level functions such as Basic
    Authentication,  mime/multipart encoding, cookies, automatic handling
    of redirects, gzipped transfer encodings, caching, or proxying (to name
    a few) are not directly provided, but nothing stops users from creating
    these features using Beast's HTTP message types.
]

This library offers programmers simple and performant models of HTTP messages
and their associated operations including synchronous, asynchronous, and
buffer-oriented parsing and serialization of messages in the HTTP/1 wire
format using __Asio__. Specifically, the library provides:

[variablelist
[
    [Message Containers]
    [
        Complete HTTP messages are modeled using the __message__ class,
        with possible user customizations.
    ]
][
    [Stream Reading]
    [
        The functions
        [link beast.ref.boost__beast__http__read `read`],
        [link beast.ref.boost__beast__http__read_header `read_header`],
        [link beast.ref.boost__beast__http__read_some `read_some`],
        [link beast.ref.boost__beast__http__async_read `async_read`],
        [link beast.ref.boost__beast__http__async_read_header `async_read_header`], and
        [link beast.ref.boost__beast__http__async_read_some `async_read_some`]
        read HTTP/1 message data from a
        [link beast.concepts.streams stream].
]
][
    [Stream Writing]
    [
        The functions
        [link beast.ref.boost__beast__http__write `write`],
        [link beast.ref.boost__beast__http__write_header `write_header`],
        [link beast.ref.boost__beast__http__write_some `write_some`],
        [link beast.ref.boost__beast__http__async_write `async_write`],
        [link beast.ref.boost__beast__http__async_write_header `async_write_header`], and
        [link beast.ref.boost__beast__http__async_write_some `async_write_some`]
        write HTTP/1 message data to a
        [link beast.concepts.streams stream].
    ]
][
    [Serialization]
    [
        The __serializer__ produces a series of octet buffers
        conforming to the __rfc7230__ wire representation of
        a __message__.
    ]
][
    [Parsing]
    [
        The __parser__ attempts to convert a series of octet
        buffers into a __message__.
    ]
]
]

Interfaces for operating on HTTP messages are structured into several
layers. The highest level provides ease of use, while lower levels provide
progressively more control, options, and flexibility. At the lowest level
customization points are provided, where user defined types can replace
parts of the implementation. The layers are arranged thusly:

[table
[[Level][Read/Write What][Description]]
[
    [[*6]]
    [
        __message__
    ][
        At the highest level, these free functions send or receive
        a complete HTTP message in one call. They are designed for
        ease of use:
        [link beast.ref.boost__beast__http__read.overload4 `read`],
        [link beast.ref.boost__beast__http__write.overload4 `write`],
        [link beast.ref.boost__beast__http__async_read.overload2 `async_read`], and
        [link beast.ref.boost__beast__http__async_write.overload2 `async_write`].
    ]
][
    [[*5]]
    [
        __parser__, __serializer__
    ][
        For more control, callers may take responsibility for managing the
        required __parser__ or __serializer__ transient state objects.
        This allows additional configuration such as limiting the number
        of bytes for message components during parsing, or regulating the
        size of buffers emitted during output. These functions send or
        receive complete messages using a serializer or parser:
        [link beast.ref.boost__beast__http__read.overload2 `read`],
        [link beast.ref.boost__beast__http__write.overload2 `write`],
        [link beast.ref.boost__beast__http__async_read.overload1 `async_read`], and
        [link beast.ref.boost__beast__http__async_write.overload1 `async_write`].

    ]
][
    [[*4]]
    [
        __header__
    ][
        Sometimes it is necessary to first send or receive the HTTP
        header. For example, to read the header and take action before
        continuing to read the body. These functions use a __parser__
        or __serializer__ to read or write the header:
        [link beast.ref.boost__beast__http__read_header.overload2 `read_header`],
        [link beast.ref.boost__beast__http__write_header.overload2 `write_header`],
        [link beast.ref.boost__beast__http__async_read_header `async_read_header`], and
        [link beast.ref.boost__beast__http__async_write_header `async_write_header`].
    ]
][
    [[*3]]
    [
        partial __message__
    ][
        All of the stream operations at higher levels thus far have operated
        on a complete header or message. At this level it is possible to
        send and receive messages incrementally. This allows resource
        constrained implementations to perform work bounded on storage,
        or allows better control when setting timeouts for example.
        These functions read or write bounded amounts of data and return
        the number of bytes transacted:
        [link beast.ref.boost__beast__http__read_some.overload2 `read_some`],
        [link beast.ref.boost__beast__http__write_some.overload2 `write_some`],
        [link beast.ref.boost__beast__http__async_read_some `async_read_some`], and
        [link beast.ref.boost__beast__http__async_write_some `async_write_some`].
    ]
][
    [[*2]]
    [
        [@https://tools.ietf.org/html/rfc7230#section-4.1 ['chunked-body]]
    ][
        Until now parse and serialize operations apply or remove the chunked
        transfer coding as needed for message payloads whose size is not known
        ahead of time. For some domain specific niches, it is necessary
        to assume direct control over incoming or outgoing chunks in a chunk
        encoded message payload.
        For parsing this is achieved by setting hooks using the functions
        [link beast.ref.boost__beast__http__parser.on_chunk_header `on_chunk_header`] and/or
        [link beast.ref.boost__beast__http__parser.on_chunk_body `on_chunk_body`].
        For serializing callers may first emit the header, and then use
        these buffer sequence adapters to control the contents of each chunk
        including
        [@https://tools.ietf.org/html/rfc7230#section-4.1.1 ['chunk extensions]]
        and the
        [@https://tools.ietf.org/html/rfc7230#section-4.1.2 ['trailer-part]]:
        [link beast.ref.boost__beast__http__chunk_body `chunk_body`],
        [link beast.ref.boost__beast__http__chunk_crlf `chunk_crlf`],
        [link beast.ref.boost__beast__http__chunk_header `chunk_header`], and
        [link beast.ref.boost__beast__http__chunk_last `chunk_last`].
    ]
][
    [[*1]]
    [
        buffers
    ][
        For ultimate control, the use of library stream algorithms may
        be bypassed entirely and instead work directly with buffers by
        calling members of __parser__ or __serializer__.
    ]
][
    [[*0]]
    [
        ['user-defined]
    ][
        In addition to the typical customization points of __Stream__
        and __DynamicBuffer__, user-defined types may replace parts of
        the library implementation at the lowest level. The customization
        points include __Fields__ for creating a container to store HTTP
        fields, __Body__ for defining containers and algorithms used for
        HTTP message payloads, and user-defined subclasses of
        __basic_parser__ for implementing custom message representation
        strategies.
    ]
]]

[note
    This documentation assumes some familiarity with __Asio__ and
    the HTTP protocol specification described in __rfc7230__. Sample
    code and identifiers mentioned in this section is written as if
    these declarations are in effect:

    [http_snippet_1]
]

[include 01_primer.qbk]
[include 02_message.qbk]
[include 03_streams.qbk]
[include 04_serializer_streams.qbk]
[include 05_parser_streams.qbk]
[include 06_serializer_buffers.qbk]
[include 07_parser_buffers.qbk]
[include 08_chunked_encoding.qbk]
[include 09_custom_body.qbk]
[include 10_custom_parsers.qbk]

[endsect]