Skip to content

Commit 9847f20

Browse files
vinniefalcovinniefalco
committed
doc work
1 parent 0e85b91 commit 9847f20

7 files changed

Lines changed: 262 additions & 80 deletions

File tree

‎doc/modules/ROOT/images/ClassHierarchy.svg‎

Lines changed: 1 addition & 1 deletion
Loading

‎doc/modules/ROOT/nav.adoc‎

Lines changed: 2 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,20 +1,14 @@
1+
* xref:1.primer.adoc[]
2+
* xref:2.messages.adoc[]
13
* xref:sans_io_philosophy.adoc[]
2-
34
* xref:http_protocol_basics.adoc[]
4-
55
* xref:header_containers.adoc[]
6-
76
* xref:message_bodies.adoc[]
8-
97
* Serializing
10-
118
* Parsing
12-
139
* xref:Message.adoc[]
14-
1510
* Design Requirements
1611
** xref:design_requirements/serializer.adoc[Serializer]
1712
** xref:design_requirements/parser.adoc[Parser]
18-
1913
// * xref:reference:boost/http_proto.adoc[Reference]
2014
* xref:reference.adoc[Reference]

‎doc/modules/ROOT/pages/1.primer.adoc‎

Lines changed: 115 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,115 @@
1+
//
2+
// Copyright (c) 2025 Vinnie Falco (vinnie.falco@gmail.com)
3+
//
4+
// Distributed under the Boost Software License, Version 1.0. (See accompanying
5+
// file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
6+
//
7+
// Official repository: https://github.com/cppalliance/buffers
8+
//
9+
10+
= HTTP Primer
11+
12+
HTTP is a stream-oriented protocol between two connected programs: one acting
13+
as the client, the other as the server. While the connection is open, the client
14+
sends an HTTP request, which the server reads and answers with an HTTP response.
15+
These _messages_ are paired in order; each request has exactly one
16+
corresponding response. This exchange of structured messages continues until
17+
either peer closes the connection, whether normally or due to an error.
18+
19+
HTTP messages consist of three parts: the start line, the headers, and the
20+
message body. The start line differs between requests and responses, while
21+
the headers and body share the same structure. Headers are made up of zero
22+
or more fields, each expressed as a name–value pair. Both the start line and
23+
the header fields use a line-oriented text format, with each line terminated
24+
by a CRLF sequence (carriage return followed by line feed, i.e. bytes
25+
`0x0D 0x0A`). The message body is a sequence of bytes of defined length,
26+
with content determined by the semantics of the start line and headers.
27+
28+
This diagram shows an actual HTTP request and HTTP response
29+
30+
[cols="1a,1a"]
31+
|===
32+
|HTTP Request|HTTP Response
33+
34+
|
35+
[source]
36+
----
37+
GET /index.html HTTP/1.1\r\n
38+
User-Agent: Boost\r\n
39+
\r\n
40+
----
41+
|
42+
[source]
43+
----
44+
HTTP/1.1 200 OK\r\n
45+
Server: Boost.Http.Proto\r\n
46+
Content-Length: 13\r\n
47+
\r\n
48+
Hello, world!
49+
----
50+
51+
|===
52+
53+
More formally, the ABNF for HTTP messages is defined as follows:
54+
55+
[cols="1a,4a"]
56+
|===
57+
|Name|ABNF
58+
59+
|message
60+
|[literal]
61+
HTTP-message = request-line / status-line
62+
*( header-field CRLF )
63+
CRLF
64+
[ message-body ]
65+
66+
|request-line
67+
|[literal]
68+
request-line = method SP request-target SP HTTP-version CRLF
69+
70+
|status-line
71+
|[literal]
72+
status-line = HTTP-version SP status-code SP reason-phrase CRLF
73+
74+
|===
75+
76+
77+
Most HTTP header field values are domain-specific or application-defined, while
78+
certain fields commonly recur. The library understands these fields and takes
79+
appropriate action to ensure RFC compliance:
80+
81+
[cols="1a,4a"]
82+
|===
83+
|Field|Description
84+
85+
a|
86+
https://tools.ietf.org/html/rfc7230#section-6.1[*Connection*] +
87+
https://tools.ietf.org/html/rfc7230#appendix-A.1.2[*Proxy-Connection*]
88+
89+
|This field lets the sender specify control options for the current connection.
90+
Typical values include close, keep-alive, and upgrade.
91+
92+
|https://tools.ietf.org/html/rfc7230#section-3.3.2[*Content-Length*]
93+
|When present, this field tells the recipient the exact size of the message
94+
body, measured in bytes, that follows the header.
95+
96+
|https://tools.ietf.org/html/rfc7230#section-3.3.1[*Transfer-Encoding*]
97+
|This optional field specifies the sequence of transfer codings that have been,
98+
or will be, applied to the content payload to produce the message body.
99+
100+
The library supports the
101+
chunked,
102+
gzip,
103+
deflate, and
104+
brotli
105+
encoding schemes,
106+
in any valid combination. Encodings can be automatically applied or removed
107+
as needed by the caller.
108+
109+
|https://tools.ietf.org/html/rfc7230#section-6.7[*Upgrade*]
110+
|The Upgrade header field provides a mechanism to transition from HTTP/1.1 to
111+
another protocol on the same connection. For example, it is the mechanism used
112+
by WebSocket's initial HTTP handshake to establish a WebSocket connection.
113+
114+
|===
115+

‎doc/modules/ROOT/pages/2.messages.adoc‎

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
//
2+
// Copyright (c) 2023 Vinnie Falco (vinnie.falco@gmail.com)
3+
//
4+
// Distributed under the Boost Software License, Version 1.0. (See accompanying
5+
// file LICENSE_1_0.txt or copy at https://www.boost.org/LICENSE_1_0.txt)
6+
//
7+
// Official repository: https://github.com/cppalliance/http_proto
8+
//
9+
10+
= Messages
11+
12+
The library provides both modifiable containers and immutable views for
13+
requests, responses, and standalone field sets such as trailers. These can
14+
be used to store incoming messages or construct outgoing ones. Unlike other
15+
libraries, such as its predecessor Boost.Beast, the message body is kept
16+
separate. In other words, the containers and views offered by this library
17+
do not include the body.
18+
19+
NOTE: By omitting the body from its container and view types, the library avoids
20+
the need for templates—unlike the message container in Boost.Beast. Experience
21+
has shown that templated containers create poor ergonomics, a design flaw this
22+
library corrects.
23+
24+
The following table lists the types used to model containers and views:
25+
26+
[cols="1a,4a"]
27+
|===
28+
|Type|Description
29+
30+
|cpp:fields[]
31+
|
32+
33+
|cpp:fields_base[]
34+
|
35+
36+
|cpp:fields_view[]
37+
|
38+
39+
|cpp:fields_view_base[]
40+
|
41+
42+
|cpp:message_base[]
43+
|
44+
45+
|cpp:message_view_base[]
46+
|
47+
48+
|cpp:request[]
49+
|
50+
51+
|cpp:request_view[]
52+
|
53+
54+
|cpp:response[]
55+
|
56+
57+
|cpp:response_view[]
58+
|
59+
60+
|===
61+
62+
image:ClassHierarchy.svg[Static,1000]

‎doc/modules/ROOT/pages/design_requirements/parser.adoc‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,51 @@
99

1010
= Parser Design Requirements
1111

12+
== Design
13+
14+
=== Comparison to Boost.Beast
15+
16+
This library builds on the experiences learned from Boost.Beast's seven years
17+
of success. Beast brings these unique design strengths:
18+
19+
* Body type named requirements
20+
* First-class message container
21+
* Individual parser and serializer objects
22+
23+
The message container suffers from these problems:
24+
25+
* Templated on the body type.
26+
* Templated on Allocator
27+
* Node-based implementation
28+
* Serialization is too costly
29+
30+
Meanwhile parsers and serializes suffer from these problems:
31+
32+
* Buffer-at-a-time operation is clumsy.
33+
* Objects are not easily re-used
34+
* Parser is a class template because of body types
35+
36+
==== Message Container
37+
38+
In HTTP.Proto the message container implementation always stores the complete
39+
message or fields in its correctly serialized form. Insertions and modifications
40+
are performed in linear time. When the container is reused, the amortized cost
41+
of reallocation becomes zero. A small lookup table is stored past the end of
42+
the serialized message, permitting iteration in constant time.
43+
44+
==== Parser
45+
46+
The HTTP.Proto parser is designed to persist for the lifetime of the connection
47+
or application. It allocates a fixed size memory buffer upon construction and
48+
uses this memory region to perform type-erasure and apply or remove content
49+
encodings to the body. The parser is a regular class instead of a class
50+
template, which greatly improves its ease of use over the Beast parser design.
51+
52+
==== Serializer
53+
54+
As with the parser, the serializer is designed to persist for the lifetime of
55+
the connection or application and also allocates a fixed size buffer.
56+
1257
== Memory Allocation and Memory Utilization
1358

1459
The `parser` must use a single block of memory allocated during construction and

‎doc/modules/ROOT/pages/header_containers.adoc‎

Lines changed: 0 additions & 1 deletion
This file was deleted.

0 commit comments

Comments
 (0)