forked from boostorg/beast
Update documentation:
* http parse functions * Parser concept * More detail on concepts * Better hyperlinking
This commit is contained in:
Vinnie Falco
@@ -0,0 +1,50 @@
|
||||
[/
|
||||
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)
|
||||
]
|
||||
|
||||
[section:Body Body]
|
||||
|
||||
In this table:
|
||||
|
||||
* `X` is a type meeting the requirements of [*`Body`].
|
||||
|
||||
[table Body requirements
|
||||
[[operation] [type] [semantics, pre/post-conditions]]
|
||||
[
|
||||
[`X::value_type`]
|
||||
[]
|
||||
[
|
||||
The type of the `message::body` member.
|
||||
If this is not movable or not copyable, the containing message
|
||||
will be not movable or not copyable.
|
||||
]
|
||||
]
|
||||
[
|
||||
[`X:value_type{}`]
|
||||
[]
|
||||
[`DefaultConstructible`]
|
||||
]
|
||||
[
|
||||
[`Body::reader`]
|
||||
[]
|
||||
[
|
||||
If present, a type meeting the requirements of
|
||||
[link beast.types.Reader [*`Reader`]].
|
||||
Provides an implementation to parse the body.
|
||||
]
|
||||
]
|
||||
[
|
||||
[`Body::writer`]
|
||||
[]
|
||||
[
|
||||
If present, a type meeting the requirements of
|
||||
[link beast.types.Writer [*`Writer`]].
|
||||
Provides an implementation to serialize the body.
|
||||
]
|
||||
]
|
||||
]
|
||||
|
||||
[endsect]
|
||||
@@ -0,0 +1,15 @@
|
||||
[/
|
||||
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)
|
||||
]
|
||||
|
||||
[section:BufferSequence BufferSequence]
|
||||
|
||||
A `BufferSequence` is a type meeting either of the following requirements:
|
||||
|
||||
* [@http://www.boost.org/doc/libs/1_60_0/doc/html/boost_asio/reference/ConstBufferSequence.html [*`ConstBufferSequence`]]
|
||||
* [@http://www.boost.org/doc/libs/1_60_0/doc/html/boost_asio/reference/MutableBufferSequence.html [*`MutableBufferSequence`]]
|
||||
|
||||
[endsect]
|
||||
@@ -0,0 +1,41 @@
|
||||
[/
|
||||
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)
|
||||
]
|
||||
|
||||
[section:Field Field]
|
||||
|
||||
A [*`Field`] represents a single HTTP header field/value pair.
|
||||
|
||||
In this table:
|
||||
|
||||
* `X` denotes a type meeting the requirements of [*`Field`].
|
||||
* `a` denotes a value of type `X`.
|
||||
|
||||
[table Field requirements
|
||||
|
||||
[[operation][type][semantics, pre/post-conditions]]
|
||||
[
|
||||
[`a.name()`]
|
||||
[`boost::string_ref`]
|
||||
[
|
||||
This function returns a value implicitly convertible to
|
||||
`boost::string_ref` containing the case-insensitve field
|
||||
name, without leading or trailing white space.
|
||||
]
|
||||
]
|
||||
[
|
||||
[`a.value()`]
|
||||
[`boost::string_ref`]
|
||||
[
|
||||
This function returns a value implicitly convertible to
|
||||
`boost::string_ref` containing the value for the field. The
|
||||
value is considered canonical if there is no leading or
|
||||
trailing whitespace.
|
||||
]
|
||||
]
|
||||
]
|
||||
|
||||
[endsect]
|
||||
@@ -0,0 +1,51 @@
|
||||
[/
|
||||
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)
|
||||
]
|
||||
|
||||
[section:FieldSequence FieldSequence]
|
||||
|
||||
A [*`FieldSequence`] is an iterable container whose value type meets
|
||||
the requirements of [link beast.types.Field [*`Field`]].
|
||||
|
||||
In this table:
|
||||
|
||||
* `X` denotes a type that meets the requirements of [*`FieldSequence`].
|
||||
|
||||
* `a` is a value of type `X`.
|
||||
|
||||
[table FieldSequence requirements
|
||||
[[operation][type][semantics, pre/post-conditions]]
|
||||
[
|
||||
[`X::value_type`]
|
||||
[]
|
||||
[
|
||||
A type that meets the requirements of `Field`.
|
||||
]
|
||||
]
|
||||
[
|
||||
[`X::const_iterator`]
|
||||
[]
|
||||
[
|
||||
A type that meets the requirements of `ForwardIterator`.
|
||||
]
|
||||
]
|
||||
[
|
||||
[`a.begin()`]
|
||||
[`X::const_iterator`]
|
||||
[
|
||||
Returns an iterator to the beginning of the field sequence.
|
||||
]
|
||||
]
|
||||
[
|
||||
[`a.end()`]
|
||||
[`X::const_iterator`]
|
||||
[
|
||||
Returns an iterator to the end of the field sequence.
|
||||
]
|
||||
]
|
||||
]
|
||||
|
||||
[endsect]
|
||||
@@ -0,0 +1,58 @@
|
||||
[/
|
||||
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)
|
||||
]
|
||||
|
||||
[section:Parser Parser]
|
||||
|
||||
A [*`Parser`] is used to deserialize HTTP/1 messages from [link beast.types.streams streams].
|
||||
Objects of this type are used with [link beast.ref.http__parse http::parse] and
|
||||
[link beast.ref.http__async_parse http::async_parse].
|
||||
|
||||
In this table:
|
||||
|
||||
* `X` denotes a type meeting the requirements of [*`Parser`].
|
||||
|
||||
* `a` denotes a value of type `X`.
|
||||
|
||||
* `b` is a value meeting the requirements of [@http://www.boost.org/doc/libs/1_60_0/doc/html/boost_asio/reference/ConvertibleToConstBuffer.html [*`ConvertibleToConstBuffer`]].
|
||||
|
||||
* `ec` is a value of type [link beast.ref.error_code `error_code&`].
|
||||
|
||||
[table Parser requirements
|
||||
[[operation] [type] [semantics, pre/post-conditions]]
|
||||
[
|
||||
[`a.complete()`]
|
||||
[`bool`]
|
||||
[
|
||||
Returns `true` when a complete HTTP/1 message has been parsed.
|
||||
]
|
||||
]
|
||||
[
|
||||
[`a.write(b, ec)`]
|
||||
[`std::size_t`]
|
||||
[
|
||||
Parses the octets in the specified input buffer sequentially until
|
||||
an error occurs, the end of the buffer is reached, or a complete
|
||||
HTTP/1 message has been parsed. If an error occurs, `ec` is set
|
||||
to the error code and parsing stops. This function returns the
|
||||
number of bytes consumed in the input buffer.
|
||||
]
|
||||
]
|
||||
[
|
||||
[`a.write_eof(ec)`]
|
||||
[`void`]
|
||||
[
|
||||
Indicates to the parser that no more octets will be available.
|
||||
Typically this function is called when the end of stream is reached.
|
||||
For example, if a call to `boost::asio::ip::tcp::socket::read_some`
|
||||
generates a `boost::asio::error::eof` error. Some HTTP/1 messages
|
||||
determine the end of the message body by an end of file marker or
|
||||
closing of the connection.
|
||||
]
|
||||
]
|
||||
]
|
||||
|
||||
[endsect]
|
||||
@@ -0,0 +1,54 @@
|
||||
[/
|
||||
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)
|
||||
]
|
||||
|
||||
[section:Reader Reader]
|
||||
|
||||
Parser implementations will construct the corresponding `reader` object
|
||||
during the parse. This customization point allows the Body to determine
|
||||
the strategy for storing incoming message body data.
|
||||
|
||||
In this table:
|
||||
|
||||
* `X` denotes a type meeting the requirements of [*`Reader`].
|
||||
|
||||
* `a` denotes a value of type `X`.
|
||||
|
||||
* `p` is any pointer.
|
||||
|
||||
* `n` is a value convertible to `std::size_t`.
|
||||
|
||||
* `ec` is a value of type `error_code&`.
|
||||
|
||||
* `m` denotes a value of type `message const&` where
|
||||
`std::is_same<decltype(m.body), Body::value_type>:value == true`
|
||||
|
||||
|
||||
[table Reader requirements
|
||||
[[operation] [type] [semantics, pre/post-conditions]]
|
||||
[
|
||||
[`X a(m);`]
|
||||
[]
|
||||
[
|
||||
`a` is constructible from `m`. The lifetime of `m` is
|
||||
guaranteed to end no earlier than after `a` is destroyed.
|
||||
]
|
||||
]
|
||||
[
|
||||
[`a.write(p, n, ec)`]
|
||||
[`void`]
|
||||
[
|
||||
Deserializes the input sequence into the body.
|
||||
If `ec` is set, the deserialization is aborted and the error
|
||||
is returned to the caller.
|
||||
]
|
||||
]
|
||||
]
|
||||
|
||||
[note Definitions for required `Reader` member functions should be declared
|
||||
inline so the generated code becomes part of the implementation. ]
|
||||
|
||||
[endsect]
|
||||
@@ -0,0 +1,96 @@
|
||||
[/
|
||||
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)
|
||||
]
|
||||
|
||||
[section:Streambuf Streambuf]
|
||||
|
||||
A [*`Streambuf`] represents a logical octet sequence divided in two sections,
|
||||
the input sequence and the output sequence. Octets are written to the output
|
||||
sequence, then moved to the input sequence where they are available for
|
||||
reading. When some or all of the input sequence is no longer needed, it may
|
||||
be consumed.
|
||||
|
||||
The interface to this concept is intended to permit the following
|
||||
implementation strategies:
|
||||
|
||||
* A single contiguous octet array, which is reallocated as necessary to
|
||||
accommodate changes in the size of the octet sequence.
|
||||
|
||||
* A sequence of one or more octet arrays, where each array is of the same
|
||||
size. Additional octet array objects are appended to the sequence to
|
||||
accommodate changes in the size of the octet sequence.
|
||||
|
||||
* A sequence of one or more octet arrays of varying sizes. Additional octet
|
||||
array objects are appended to the sequence to accommodate changes in the
|
||||
size of the character sequence. This is the implementation approached
|
||||
currently offered by [link beast.ref.basic_streambuf `basic_streambuf`].
|
||||
|
||||
In the table below:
|
||||
|
||||
* `X` denotes a class meeting the requirements of [*`Streambuf`]
|
||||
* `a` denotes a value of type `X`
|
||||
* `n` denotes a value convertible to `std::size_t`
|
||||
* `U`, `T` denote unspecified types.
|
||||
|
||||
[table Streambuf requirements
|
||||
[[operation] [type] [semantics, pre/post-conditions]]
|
||||
[
|
||||
[`X::const_buffers_type`]
|
||||
[`T`]
|
||||
[`T` meets the requirements for [@http://www.boost.org/doc/libs/1_60_0/doc/html/boost_asio/reference/ConstBufferSequence.html `ConstBufferSequence`].]
|
||||
]
|
||||
[
|
||||
[`X::mutable_buffers_type`]
|
||||
[`U`]
|
||||
[`U` meets the requirements for [@http://www.boost.org/doc/libs/1_60_0/doc/html/boost_asio/reference/MutableBufferSequence.html `MutableBufferSequence`].]
|
||||
]
|
||||
[
|
||||
[`a.commit(n)`]
|
||||
[`void`]
|
||||
[Moves bytes from the output sequence to the input sequence.]
|
||||
]
|
||||
[
|
||||
[`a.consume(n)`]
|
||||
[`void`]
|
||||
[Removes bytes from the input sequence.]
|
||||
]
|
||||
[
|
||||
[`a.data()`]
|
||||
[`T`]
|
||||
[Returns a list of buffers that represents the input sequence.]
|
||||
]
|
||||
[
|
||||
[`a.prepare(n)`]
|
||||
[`U`]
|
||||
[Returns a list of buffers that represents the output sequence, with
|
||||
the given size.]
|
||||
]
|
||||
[
|
||||
[`a.size()`]
|
||||
[`std::size_t`]
|
||||
[Returns the size of the input sequence.]
|
||||
]
|
||||
[
|
||||
[`a.max_size()`]
|
||||
[`std::size_t`]
|
||||
[Returns the maximum size of the stream buffer.]
|
||||
]
|
||||
[
|
||||
[`read_size_helper(a, n)`]
|
||||
[`std::size_t`]
|
||||
[
|
||||
Returns the suggested number of bytes to read into the output
|
||||
sequence where `n` is an upper limit on this value. One possible
|
||||
implementation is to return the number of bytes that may be prepared
|
||||
without causing a dynamic allocation or `n`, whichever is smaller.
|
||||
Calls to `read_size_helper` will be made without namespace
|
||||
qualification, to allow the rules for argument dependent lookup to
|
||||
take effect.
|
||||
]
|
||||
]
|
||||
]
|
||||
|
||||
[endsect]
|
||||
@@ -0,0 +1,34 @@
|
||||
[/
|
||||
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)
|
||||
]
|
||||
|
||||
[section:streams Streams]
|
||||
|
||||
Stream types represent objects capable of performing synchronous or
|
||||
asynchronous I/O. They are based on concepts from `boost::asio`.
|
||||
|
||||
[heading:Stream Stream]
|
||||
|
||||
A type modeling [*`Stream`] meets either or both of the following requirements:
|
||||
|
||||
* [link beast.types.streams.AsyncStream [*`AsyncStream`]]
|
||||
* [link beast.types.streams.SyncStream [*`SyncStream`]]
|
||||
|
||||
[heading:AsyncStream AsyncStream]
|
||||
|
||||
A type modeling [*`AsyncStream`] meets the following requirements:
|
||||
|
||||
* [@http://www.boost.org/doc/libs/1_60_0/doc/html/boost_asio/reference/AsyncReadStream.html [*`AsyncReadStream`]]
|
||||
* [@http://www.boost.org/doc/libs/1_60_0/doc/html/boost_asio/reference/AsyncWriteStream.html [*`AsyncWriteStream`]]
|
||||
|
||||
[heading:SyncStream SyncStream]
|
||||
|
||||
A type modeling [*`SyncStream`] meets the following requirements:
|
||||
|
||||
* [@http://www.boost.org/doc/libs/1_60_0/doc/html/boost_asio/reference/SyncReadStream.html [*`SyncReadStream`]]
|
||||
* [@http://www.boost.org/doc/libs/1_60_0/doc/html/boost_asio/reference/SyncWriteStream.html [*`SyncWriteStream`]]
|
||||
|
||||
[endsect]
|
||||
@@ -0,0 +1,179 @@
|
||||
[/
|
||||
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)
|
||||
]
|
||||
|
||||
[section:Writer Writer]
|
||||
|
||||
A `Writer` serializes the message body. The implementation creates an instance
|
||||
of this type when serializing a message, and calls into it zero or more times
|
||||
to provide buffers containing the data. The interface of `Writer` is intended
|
||||
to allow serialization in these scenarios:
|
||||
|
||||
* A body that does not entirely fit in memory.
|
||||
* A body produced incrementally from coroutine output.
|
||||
* A body represented by zero or more buffers already in memory.
|
||||
* A body as a series of buffers when the content size is not known ahead of time.
|
||||
* Body data generated on demand from other threads.
|
||||
* Body data computed algorithmically.
|
||||
|
||||
In this table:
|
||||
|
||||
* `X` denotes a type meeting the requirements of `Writer`.
|
||||
|
||||
* `a` denotes a value of type `X`.
|
||||
|
||||
* `m` denotes a value of type `message const&` where
|
||||
`std::is_same<decltype(m.body), Body::value_type>:value == true`.
|
||||
|
||||
* `rc` is an object of type [link beast.ref.http__resume_context resume_context].
|
||||
|
||||
* `ec` is a value of type `error_code&`.
|
||||
|
||||
* `wf` is a [*write function]: a function object of unspecified type provided
|
||||
by the implementation which accepts any value meeting the requirements
|
||||
of `ConstBufferSequence` as its single parameter.
|
||||
|
||||
[table Writer requirements
|
||||
[[operation] [type] [semantics, pre/post-conditions]]
|
||||
[
|
||||
[`X a(m);`]
|
||||
[]
|
||||
[
|
||||
`a` is constructible from `m`. The lifetime of `m` is
|
||||
guaranteed to end no earlier than after `a` is destroyed.
|
||||
]
|
||||
]
|
||||
[
|
||||
[`a.init(ec)`]
|
||||
[`void`]
|
||||
[
|
||||
Called immediately after construction.
|
||||
If `ec` is set, the serialization is aborted and the error
|
||||
is propagated to the caller.
|
||||
]
|
||||
]
|
||||
[
|
||||
[`a.content_length()`]
|
||||
[`std::uint64_t`]
|
||||
[
|
||||
If this member is present, it is called after initialization
|
||||
and before calls to provide buffers. The serialized message will
|
||||
have the Content-Length field set to the value returned from
|
||||
this function. If this member is absent, the serialized message
|
||||
body will be chunk-encoded for HTTP versions 1.1 and later, else
|
||||
the serialized message body will be sent unmodified, with the
|
||||
error `boost::asio::error::eof` returned to the caller, to notify
|
||||
they should close the connection to indicate the end of the message.
|
||||
]
|
||||
]
|
||||
[
|
||||
[`a(rc, ec, wf)`]
|
||||
[`boost::tribool`]
|
||||
[
|
||||
Called repeatedly after `init` succeeds.
|
||||
`wf` is a function object which takes as its single parameter,
|
||||
any value meeting the requirements of `ConstBufferSequence`.
|
||||
Buffers provided by the `writer` to this [*write function] must
|
||||
remain valid until the next member function of `writer` is
|
||||
invoked (which may be the destructor). This function returns `true`
|
||||
to indicate all message body data has been written, or `false`
|
||||
if there is more body data. If the return value is
|
||||
`boost::indeterminate`, the implementation will suspend the operation
|
||||
until the writer invokes `rc`. It is the writers responsibility when
|
||||
returning `boost::indeterminate`, to acquire ownership of the
|
||||
`resume_context` via move construction and eventually call it or else
|
||||
undefined behavior results.
|
||||
]
|
||||
]
|
||||
]
|
||||
|
||||
[note Definitions for required `Writer` member functions should be declared
|
||||
inline so the generated code becomes part of the implementation. ]
|
||||
|
||||
Exemplar:
|
||||
```
|
||||
struct writer
|
||||
{
|
||||
public:
|
||||
/** Construct the writer.
|
||||
|
||||
The msg object is guaranteed to exist for the lifetime of the writer.
|
||||
|
||||
Exceptions:
|
||||
No-throw guarantee.
|
||||
|
||||
@param msg The message whose body is to be written.
|
||||
*/
|
||||
template<bool isRequest, class Body, class Headers>
|
||||
explicit
|
||||
writer(message<isRequest, Body, Headers> const& msg);
|
||||
|
||||
/** Initialize the writer.
|
||||
|
||||
Called once immediately after construction.
|
||||
The writer can perform initialization which may fail.
|
||||
|
||||
@param ec Contains the error code if any errors occur.
|
||||
*/
|
||||
void
|
||||
init(error_code& ec);
|
||||
|
||||
/** Returns the content length.
|
||||
|
||||
If this member is present, the implementation will set the
|
||||
Content-Length field accordingly. If absent, the implementation will
|
||||
use chunk-encoding or terminate the connection to indicate the end
|
||||
of the message.
|
||||
*/
|
||||
std::size_t
|
||||
content_length() const;
|
||||
|
||||
/** Write zero or one buffer representing the message body.
|
||||
|
||||
Postconditions:
|
||||
|
||||
If return value is `true`:
|
||||
* Callee does not take ownership of resume.
|
||||
* Callee made zero or one calls to `write`.
|
||||
* There is no more data remaining to write.
|
||||
|
||||
If return value is `false`:
|
||||
* Callee does not take ownership of resume.
|
||||
* Callee made one call to `write`.
|
||||
|
||||
If return value is boost::indeterminate:
|
||||
* Callee takes ownership of `resume`.
|
||||
* Caller suspends the write operation
|
||||
until `resume` is invoked.
|
||||
|
||||
When the caller takes ownership of resume, the
|
||||
asynchronous operation will not complete until the
|
||||
caller destroys the object.
|
||||
|
||||
@param resume A functor to call to resume the write operation
|
||||
after the writer has returned boost::indeterminate.
|
||||
|
||||
@param ec Set to indicate an error. This will cause an
|
||||
asynchronous write operation to complete with the error.
|
||||
|
||||
@param write A functor the writer will call to provide the next
|
||||
set of buffers. Ownership of the buffers is not transferred,
|
||||
the writer must guarantee that the buffers remain valid until the
|
||||
next member function is invoked, which may be the destructor.
|
||||
|
||||
@return `true` if there is data, `false` when done,
|
||||
boost::indeterminate to suspend.
|
||||
|
||||
@note Undefined behavior if the callee takes ownership
|
||||
of resume but does not return boost::indeterminate.
|
||||
*/
|
||||
template<class WriteFunction>
|
||||
boost::tribool
|
||||
operator()(resume_context&&, error_code&, WriteFunction&& write);
|
||||
};
|
||||
```
|
||||
|
||||
[endsect]
|
||||
Reference in New Issue
Block a user