213 lines
8.4 KiB
Plaintext
213 lines
8.4 KiB
Plaintext
[/
|
|
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]
|