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