Messages

The library provides both modifiable containers and immutable views for requests, responses, and standalone field sets such as trailers. These can be used to store incoming messages or construct outgoing ones. Unlike other libraries, such as its predecessor Boost.Beast, the message body is kept separate. In other words, the containers and views offered by this library do not include the body.

By omitting the body from its container and view types, the library avoids the need for templates—unlike the message container in Boost.Beast. Experience has shown that templated containers create poor ergonomics, a design flaw this library corrects.

The following table lists the types used to model containers and views:

Type Description

fields

A modifiable container of header fields.

fields_view

A read-only view to a fields

message

A modifiable container holding a start-line and header fields, with accompanying metadata.

message_view

A read-only view to a message

request

A modifiable container holding a request-line and header fields, with accompanying metadata.

request_view

A read-only view to a request

response

A modifiable container holding a status-line and header fields, with accompanying metadata.

response_view

A read-only view to a response

Construction

All containers maintain the following invariants:

  • The container’s contents are always stored in serialized form that is syntactically valid.

  • Any modification that would produce a malformed field or start line throws an exception, with strong exception safety guaranteed.

To satisfy these invariants, default-constructed containers initially consist of a start line:

request req;
response res;

assert(req->buffer() == "GET / HTTP/1.1\r\n\r\n");
assert(res->buffer() == "HTTP/1.1 200 OK\r\n\r\n");

The buffer function runs in constant time, never throws exceptions, and returns a boost::core::string_view representing the complete serialized object.

Each header field consists of a name and a value, both stored as strings, with prescribed ABNF format:

field-name     = token
field-value    = *( field-content / obs-fold )
field-content  = field-vchar [ 1*( SP / HTAB ) field-vchar ]
field-vchar    = VCHAR / obs-text

obs-fold       = CRLF 1*( SP / HTAB )
               ; obsolete line folding

Operations that create or modify fields throw an exception if the name or value violates the syntactic requirements of the protocol.

Although fields may be identified by comparing their names, the library provides the field enumeration, which defines a wide set of constants for well-known field names. Internally, containers maintain a lookup table so that specifying fields by enumeration replaces costly string comparisons with efficient integer comparisons.

The following example builds an HTTP GET request:

Code Serialized Result 
request req( method::get, "/index.htm", version::http_1_1 );
req.append( field::accept, "text/html" );
req.append( "User-Agent", "Boost" );
 
GET /index.htm HTTP/1.1\r\n
Accept: text/html\r\n
User-Agent: Boost\r\n
\r\n
Field-specific syntax (e.g., for date values) is not fully validated by this library. It is the application’s responsibility to follow the relevant specifications to ensure correct behavior.
Edit this Page