Skip to content

Commit dcf7962

Browse files
vinniefalcovinniefalco
committed
doc work
1 parent f025f8d commit dcf7962

4 files changed

Lines changed: 89 additions & 74 deletions

File tree

‎doc/modules/ROOT/nav.adoc‎

Lines changed: 1 addition & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,20 +1,13 @@
1+
* xref:1.intro.adoc[]
12
* xref:sans_io_philosophy.adoc[]
2-
33
* xref:http_protocol_basics.adoc[]
4-
54
* xref:header_containers.adoc[]
6-
75
* xref:message_bodies.adoc[]
8-
96
* Serializing
10-
117
* Parsing
12-
138
* xref:Message.adoc[]
14-
159
* Design Requirements
1610
** xref:design_requirements/serializer.adoc[Serializer]
1711
** xref:design_requirements/parser.adoc[Parser]
18-
1912
// * xref:reference:boost/http_proto.adoc[Reference]
2013
* xref:reference.adoc[Reference]

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

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
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+
= Introduction

‎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/index.adoc‎

Lines changed: 33 additions & 66 deletions
Original file line numberDiff line numberDiff line change
@@ -9,41 +9,53 @@
99

1010
= Boost.HTTP.Proto
1111

12-
Boost.HTTP.Proto is a portable C++ library which provides containers and
13-
algorithms which implement the HTTP/1.1 protocol, widely used to deliver content
14-
on the Internet. It adheres strictly to the HTTP/1.1 RFC specification
15-
(henceforth referred to as https://datatracker.ietf.org/doc/html/rfc9110[rfc9110,window=blank_]).
16-
17-
This library understands the grammars related to HTTP nessages and provides
18-
functionality to validate, parse, examine, and modify messages.
19-
20-
== Features
12+
This is a portable C++ library offering containers and algorithms for implementing
13+
the HTTP/1.1 protocol. The format is widely used to deliver content on the Internet,
14+
and this implementation adheres strictly to the
15+
https://datatracker.ietf.org/doc/html/rfc9110[HTTP/1.1 RFC specification],
16+
henceform referred to as the RFC. The library is distinguished by these
17+
provided features:
18+
19+
* Sans-I/O approach
20+
* Requires only C++11
21+
* Works without exceptions
22+
* Fast compilation, few templates
23+
* Advanced handling of memory (RAM)
24+
25+
== Sans-I/O
26+
27+
While this library implements the HTTP protocol, it does so without performing
28+
any actual network activity as the logic is completely isolated from the
29+
underlying I/O operations. The implementation manages state, ensures RFC
30+
compliance, and provides the application-level interface for building and
31+
inspecting HTTP messages and their payloads, and it is necessary to use or
32+
write the interfacing network implementation on top of HTTP.Proto.
33+
34+
The companion library Boost.HTTP.IO uses Boost.HTTP.Proto to implement network
35+
I/O using Boost.Asio. The
36+
https://sans-io.readthedocs.io/[sans-I/O] website goes into more depth regarding
37+
this innovative approach to designing protocol libraries.
2138

2239
== Requirements
2340

24-
The library requires a compiler supporting at least C++11.
25-
26-
Standard types such as `error_code` or `string_view` use their Boost equivalents.
41+
* Requires Boost and a compiler supporting at least C++11
42+
* Link to a static or dynamically linked version of this library
43+
* Supports `-fno-exceptions`, detected automatically
2744

2845
== Tested Compilers
2946

30-
Boost.HTTP.Proto has been tested with the following compilers:
31-
32-
* clang:
33-
* gcc:
34-
* msvc:
35-
36-
and these architectures: x86, x64
47+
Boost.HTTP.Proto is tested with the following compiler versions:
3748

38-
We do not test and support gcc 8.0.1.
49+
gcc: 5 to 14 (except 8.0.1)
50+
clang: 3.9, 4 to 18
51+
msvc: 14.1 to 14.42
3952

4053
== Quality Assurance
4154

4255
The development infrastructure for the library includes these per-commit analyses:
4356

4457
* Coverage reports
4558
* Compilation and tests on Drone.io and GitHub Actions
46-
* Regular code audits for security
4759

4860
== ABNF
4961

@@ -62,48 +74,3 @@ using the combinators provided by the library.
6274
This library wouldn't be where it is today without the help of
6375
https://github.com/pdimov[Peter Dimov,window=blank_]
6476
for design advice and general assistance.
65-
66-
== Design
67-
68-
=== Comparison to Boost.Beast
69-
70-
This library builds on the experiences learned from Boost.Beast's seven years
71-
of success. Beast brings these unique design strengths:
72-
73-
* Body type named requirements
74-
* First-class message container
75-
* Individual parser and serializer objects
76-
77-
The message container suffers from these problems:
78-
79-
* Templated on the body type.
80-
* Templated on Allocator
81-
* Node-based implementation
82-
* Serialization is too costly
83-
84-
Meanwhile parsers and serializes suffer from these problems:
85-
86-
* Buffer-at-a-time operation is clumsy.
87-
* Objects are not easily re-used
88-
* Parser is a class template because of body types
89-
90-
==== Message Container
91-
92-
In HTTP.Proto the message container implementation always stores the complete
93-
message or fields in its correctly serialized form. Insertions and modifications
94-
are performed in linear time. When the container is reused, the amortized cost
95-
of reallocation becomes zero. A small lookup table is stored past the end of
96-
the serialized message, permitting iteration in constant time.
97-
98-
==== Parser
99-
100-
The HTTP.Proto parser is designed to persist for the lifetime of the connection
101-
or application. It allocates a fixed size memory buffer upon construction and
102-
uses this memory region to perform type-erasure and apply or remove content
103-
encodings to the body. The parser is a regular class instead of a class
104-
template, which greatly improves its ease of use over the Beast parser design.
105-
106-
==== Serializer
107-
108-
As with the parser, the serializer is designed to persist for the lifetime of
109-
the connection or application and also allocates a fixed size buffer.

0 commit comments

Comments
 (0)