msgid "" msgstr "" "Project-Id-Version: English (Boost Beast Translation (zh_Hans))\n" "Report-Msgid-Bugs-To: \n" "POT-Creation-Date: 2026-06-06 17:47+0000\n" "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" "Last-Translator: FULL NAME \n" "Language-Team: English \n" "Language: en\n" "MIME-Version: 1.0\n" "Content-Type: text/plain; charset=UTF-8\n" "Content-Transfer-Encoding: 8bit\n" "Plural-Forms: nplurals=2; plural=n != 1;\n" "X-Generator: Weblate 2026.5\n" #. type: section title #: 12 #, read-only msgid "HTTP Message Container __video__" msgstr "HTTP Message Container __video__" #. type: paragraph #: 14 #, read-only msgid "" "The following video presentation was delivered at [@https://cppcon.org/ " "CppCon] in 2017. The presentation provides a simplified explanation of the " "design process for the HTTP message container used in Beast. The slides and " "code used are available in the [@https://github.com/vinniefalco/CppCon2017 " "GitHub repository]." msgstr "" "The following video presentation was delivered at [@https://cppcon.org/ " "CppCon] in 2017. The presentation provides a simplified explanation of the " "design process for the HTTP message container used in Beast. The slides and " "code used are available in the [@https://github.com/vinniefalco/CppCon2017 " "GitHub repository]." #. type: paragraph #: 31 #, read-only msgid "" "In this section we describe the problem of modeling HTTP messages and " "explain how the library arrived at its solution, with a discussion of the " "benefits and drawbacks of the design choices. The goal for creating a " "message model is to create a container with value semantics, possibly " "movable and/or copyable, that contains all the information needed to " "serialize, or all of the information captured during parsing. More formally, " "given:" msgstr "" "In this section we describe the problem of modeling HTTP messages and " "explain how the library arrived at its solution, with a discussion of the " "benefits and drawbacks of the design choices. The goal for creating a " "message model is to create a container with value semantics, possibly " "movable and/or copyable, that contains all the information needed to " "serialize, or all of the information captured during parsing. More formally, " "given:" #. type: list #: 38 #, read-only msgid "* `m` is an instance of an HTTP message container" msgstr "* `m` is an instance of an HTTP message container" #. type: list #: 40 #, read-only msgid "* `x` is a series of octets describing a valid HTTP message in" msgstr "* `x` is a series of octets describing a valid HTTP message in" #. type: list #: 43 #, read-only msgid "* `S(m)` is a serialization function which produces a series of octets" msgstr "* `S(m)` is a serialization function which produces a series of octets" #. type: list #: 46 #, read-only msgid "* `P(x)` is a parsing function which produces a message container from" msgstr "* `P(x)` is a parsing function which produces a message container from" #. type: paragraph #: 49 #, read-only msgid "These relations are true:" msgstr "These relations are true:" #. type: list #: 51 #, read-only msgid "* `S(m) == x`" msgstr "* `S(m) == x`" #. type: list #: 53 #, read-only msgid "* `P(S(m)) == m`" msgstr "* `P(S(m)) == m`" #. type: paragraph #: 55 #, read-only msgid "" "We would also like our message container to have customization points " "permitting the following: allocator awareness, user-defined containers to " "represent header fields, and user-defined types and algorithms to represent " "the body. And finally, because requests and responses have different fields " "in the ['start-line], we would like the containers for requests and " "responses to be represented by different types for function overloading." msgstr "" "We would also like our message container to have customization points " "permitting the following: allocator awareness, user-defined containers to " "represent header fields, and user-defined types and algorithms to represent " "the body. And finally, because requests and responses have different fields " "in the ['start-line], we would like the containers for requests and " "responses to be represented by different types for function overloading." #. type: paragraph #: 63 #, read-only msgid "Here is our first attempt at declaring some message containers:" msgstr "Here is our first attempt at declaring some message containers:" #. type: paragraph #: 97 #, read-only msgid "" "These containers are capable of representing everything in the model of HTTP " "requests and responses described in __rfc7230__. Request and response " "objects are different types. The user can choose the container used to " "represent the fields. And the user can choose the [*Body] type, which is a " "concept defining not only the type of `body` member but also the algorithms " "used to transfer information in and out of that member when performing " "serialization and parsing." msgstr "" "These containers are capable of representing everything in the model of HTTP " "requests and responses described in __rfc7230__. Request and response " "objects are different types. The user can choose the container used to " "represent the fields. And the user can choose the [*Body] type, which is a " "concept defining not only the type of `body` member but also the algorithms " "used to transfer information in and out of that member when performing " "serialization and parsing." #. type: paragraph #: 105 #, read-only msgid "" "However, a problem arises. How do we write a function which can accept an " "object that is either a request or a response? As written, the only obvious " "solution is to make the message a template type. Additional traits classes " "would then be needed to make sure that the passed object has a valid type " "which meets the requirements. These unnecessary complexities are bypassed by " "making each container a partial specialization: ``` /// An HTTP message " "template struct message;" msgstr "" "However, a problem arises. How do we write a function which can accept an " "object that is either a request or a response? As written, the only obvious " "solution is to make the message a template type. Additional traits classes " "would then be needed to make sure that the passed object has a valid type " "which meets the requirements. These unnecessary complexities are bypassed by " "making each container a partial specialization: ``` /// An HTTP message " "template struct message;" #. type: paragraph #: 116 #, read-only msgid "" "/// An HTTP request template struct message {" msgstr "" "/// An HTTP request template struct message {" #. type: paragraph #: 126 #, read-only msgctxt "126" msgid "};" msgstr "};" #. type: paragraph #: 128 #, read-only msgid "" "/// An HTTP response template " "struct message {" msgstr "" "/// An HTTP response template " "struct message {" #. type: paragraph #: 138 #, read-only msgctxt "138" msgid "}; ```" msgstr "}; ```" #. type: paragraph #: 141 #, read-only msgid "" "Now we can declare a function which takes any message as a parameter: ``` " "template void f(message& msg); ```" msgstr "" "Now we can declare a function which takes any message as a parameter: ``` " "template void f(message& msg); ```" #. type: paragraph #: 147 #, read-only msgid "" "This function can manipulate the fields common to requests and responses. If " "it needs to access the other fields, it can use overloads with partial " "specialization, or in C++17 a `constexpr` expression: ``` template void f(message" "& msg) {" msgstr "" "This function can manipulate the fields common to requests and responses. If " "it needs to access the other fields, it can use overloads with partial " "specialization, or in C++17 a `constexpr` expression: ``` template void f(message" "& msg) {" #. type: paragraph #: 162 #, read-only msgid "} ```" msgstr "} ```" #. type: paragraph #: 165 #, read-only msgid "" "Often, in non-trivial HTTP applications, we want to read the HTTP header and " "examine its contents before choosing a type for [*Body]. To accomplish this, " "there needs to be a way to model the header portion of a message. And we'd " "like to do this in a way that allows functions which take the header as a " "parameter, to also accept a type representing the whole message (the " "function will see just the header part). This suggests inheritance, by " "splitting a new base class off of the message: ``` /// An HTTP message " "header template struct header; ```" msgstr "" "Often, in non-trivial HTTP applications, we want to read the HTTP header and " "examine its contents before choosing a type for [*Body]. To accomplish this, " "there needs to be a way to model the header portion of a message. And we'd " "like to do this in a way that allows functions which take the header as a " "parameter, to also accept a type representing the whole message (the " "function will see just the header part). This suggests inheritance, by " "splitting a new base class off of the message: ``` /// An HTTP message " "header template struct header; ```" #. type: paragraph #: 178 #, read-only msgid "" "Code which accesses the fields has to laboriously mention the `fields` " "member, so we'll not only make `header` a base class but we'll make a " "quality of life improvement and derive the header from the fields for " "notational convenience. In order to properly support all forms of " "construction of [*Fields] there will need to be a set of suitable " "constructor overloads (not shown): ``` /// An HTTP request header " "template struct header : Fields {" msgstr "" "Code which accesses the fields has to laboriously mention the `fields` " "member, so we'll not only make `header` a base class but we'll make a " "quality of life improvement and derive the header from the fields for " "notational convenience. In order to properly support all forms of " "construction of [*Fields] there will need to be a set of suitable " "constructor overloads (not shown): ``` /// An HTTP request header " "template struct header : Fields {" #. type: paragraph #: 192 #, read-only msgctxt "192" msgid "};" msgstr "};" #. type: paragraph #: 194 #, read-only msgctxt "194" msgid "" "/// An HTTP response header template struct header : Fields {" msgstr "" "/// An HTTP response header template struct header : Fields {" #. type: paragraph #: 201 #, read-only msgctxt "201" msgid "};" msgstr "};" #. type: paragraph #: 203 #, read-only msgid "" "/// An HTTP message template " "struct message : header {" msgstr "" "/// An HTTP message template " "struct message : header {" #. type: paragraph #: 211 #, read-only msgctxt "211" msgid "};" msgstr "};" #. type: paragraph #: 213 #, read-only msgid "```" msgstr "```" #. type: paragraph #: 215 #, read-only msgid "" "Note that the `message` class now has a constructor allowing messages to be " "constructed from a similarly typed `header`. This handles the case where the " "user already has the header and wants to make a commitment to the type for " "[*Body]. A function can be declared which accepts any header: ``` " "template void f(header& msg)" "; ```" msgstr "" "Note that the `message` class now has a constructor allowing messages to be " "constructed from a similarly typed `header`. This handles the case where the " "user already has the header and wants to make a commitment to the type for " "[*Body]. A function can be declared which accepts any header: ``` " "template void f(header& msg)" "; ```" #. type: paragraph #: 224 #, read-only msgid "" "Until now we have not given significant consideration to the constructors of " "the `message` class. But to achieve all our goals we will need to make sure " "that there are enough constructor overloads to not only provide for the " "special copy and move members if the instantiated types support it, but also " "allow the fields container and body container to be constructed with " "arbitrary variadic lists of parameters. This allows the container to fully " "support allocators." msgstr "" "Until now we have not given significant consideration to the constructors of " "the `message` class. But to achieve all our goals we will need to make sure " "that there are enough constructor overloads to not only provide for the " "special copy and move members if the instantiated types support it, but also " "allow the fields container and body container to be constructed with " "arbitrary variadic lists of parameters. This allows the container to fully " "support allocators." #. type: paragraph #: 232 #, read-only msgid "" "The solution used in the library is to treat the message like a `std::pair` " "for the purposes of construction, except that instead of `first` and " "`second` we have the `Fields` base class and `message::body` member. This " "means that single-argument constructors for those fields should be " "accessible as they are with `std::pair`, and that a mechanism identical to " "the pair's use of `std::piecewise_construct` should be provided. Those " "constructors are too complex to repeat here, but interested readers can view " "the declarations in the corresponding header file." msgstr "" "The solution used in the library is to treat the message like a `std::pair` " "for the purposes of construction, except that instead of `first` and " "`second` we have the `Fields` base class and `message::body` member. This " "means that single-argument constructors for those fields should be " "accessible as they are with `std::pair`, and that a mechanism identical to " "the pair's use of `std::piecewise_construct` should be provided. Those " "constructors are too complex to repeat here, but interested readers can view " "the declarations in the corresponding header file." #. type: paragraph #: 241 #, read-only msgid "" "There is now significant progress with our message container but a stumbling " "block remains. There is no way to control the allocator for the " "`std::string` members. We could add an allocator to the template parameter " "list of the header and message classes, use it for those strings. This is " "unsatisfying because of the combinatorial explosion of constructor " "variations needed to support the scheme. It also means that request messages " "could have [*four] different allocators: two for the fields and body, and " "two for the method and target strings. A better solution is needed." msgstr "" "There is now significant progress with our message container but a stumbling " "block remains. There is no way to control the allocator for the " "`std::string` members. We could add an allocator to the template parameter " "list of the header and message classes, use it for those strings. This is " "unsatisfying because of the combinatorial explosion of constructor " "variations needed to support the scheme. It also means that request messages " "could have [*four] different allocators: two for the fields and body, and " "two for the method and target strings. A better solution is needed." #. type: paragraph #: 250 #, read-only msgid "" "To get around this we make an interface modification and then add a " "requirement to the [*Fields] type. First, the interface change: ``` /// An " "HTTP request header template struct header : " "Fields {" msgstr "" "To get around this we make an interface modification and then add a " "requirement to the [*Fields] type. First, the interface change: ``` /// An " "HTTP request header template struct header : " "Fields {" #. type: paragraph #: 267 #, read-only msgid "private:" msgstr "private:" #. type: paragraph #: 269 #, read-only msgctxt "269" msgid "};" msgstr "};" #. type: paragraph #: 271 #, read-only msgctxt "271" msgid "" "/// An HTTP response header template struct header : Fields {" msgstr "" "/// An HTTP response header template struct header : Fields {" #. type: paragraph #: 279 #, read-only msgctxt "279" msgid "}; ```" msgstr "}; ```" #. type: paragraph #: 282 #, read-only msgid "" "The start-line data members are replaced by traditional accessors using non-" "owning references to string buffers. The method is stored using a simple " "integer instead of the entire string, for the case where the method is " "recognized from the set of known verb strings." msgstr "" "The start-line data members are replaced by traditional accessors using non-" "owning references to string buffers. The method is stored using a simple " "integer instead of the entire string, for the case where the method is " "recognized from the set of known verb strings." #. type: paragraph #: 287 #, read-only msgid "" "Now we add a requirement to the fields type: management of the corresponding " "string is delegated to the [*Fields] container, which can already be " "allocator aware and constructed with the necessary allocator parameter via " "the provided constructor overloads for `message`. The delegation " "implementation looks like this (only the response header specialization is " "shown): ``` /// An HTTP response header template struct " "header : Fields {" msgstr "" "Now we add a requirement to the fields type: management of the corresponding " "string is delegated to the [*Fields] container, which can already be " "allocator aware and constructed with the necessary allocator parameter via " "the provided constructor overloads for `message`. The delegation " "implementation looks like this (only the response header specialization is " "shown): ``` /// An HTTP response header template struct " "header : Fields {" #. type: paragraph #: 312 #, read-only msgctxt "312" msgid "}; ```" msgstr "}; ```" #. type: paragraph #: 315 #, read-only msgid "" "Now that we've accomplished our initial goals and more, there are a few more " "quality of life improvements to make. Users will choose different types for " "`Body` far more often than they will for `Fields`. Thus, we swap the order " "of these types and provide a default. Then, we provide type aliases for " "requests and responses to soften the impact of using `bool` to choose the " "specialization:" msgstr "" "Now that we've accomplished our initial goals and more, there are a few more " "quality of life improvements to make. Users will choose different types for " "`Body` far more often than they will for `Fields`. Thus, we swap the order " "of these types and provide a default. Then, we provide type aliases for " "requests and responses to soften the impact of using `bool` to choose the " "specialization:" #. type: paragraph #: 322 #, read-only msgid "" "``` /// An HTTP header template struct header;" msgstr "" "``` /// An HTTP header template struct header;" #. type: paragraph #: 327 #, read-only msgid "" "/// An HTTP message template struct message;" msgstr "" "/// An HTTP message template struct message;" #. type: paragraph #: 331 #, read-only msgid "" "/// An HTTP request template using " "request = message;" msgstr "" "/// An HTTP request template using " "request = message;" #. type: paragraph #: 335 #, read-only msgid "" "/// An HTTP response template using " "response = message; ```" msgstr "" "/// An HTTP response template using " "response = message; ```" #. type: paragraph #: 340 #, read-only msgid "" "This allows concise specification for the common cases, while allowing for " "maximum customization for edge cases: ``` request req;" msgstr "" "This allows concise specification for the common cases, while allowing for " "maximum customization for edge cases: ``` request req;" #. type: paragraph #: 345 #, read-only msgid "response res; ```" msgstr "response res; ```" #. type: paragraph #: 348 #, read-only msgid "" "This container is also capable of representing complete HTTP/2 messages. Not " "because it was explicitly designed for, but because the IETF wanted to " "preserve message compatibility with HTTP/1. Aside from version specific " "fields such as Connection, the contents of HTTP/1 and HTTP/2 messages are " "identical even though their serialized representation is considerably " "different. The message model presented in this library is ready for HTTP/2." msgstr "" "This container is also capable of representing complete HTTP/2 messages. Not " "because it was explicitly designed for, but because the IETF wanted to " "preserve message compatibility with HTTP/1. Aside from version specific " "fields such as Connection, the contents of HTTP/1 and HTTP/2 messages are " "identical even though their serialized representation is considerably " "different. The message model presented in this library is ready for HTTP/2." #. type: paragraph #: 355 #, read-only msgid "" "In conclusion, this representation for the message container is well thought " "out, provides comprehensive flexibility, and avoids the necessity of " "defining additional traits classes. User declarations of functions that " "accept headers or messages as parameters are easy to write in a variety of " "ways to accomplish different results, without forcing cumbersome SFINAE " "declarations everywhere." msgstr "" "In conclusion, this representation for the message container is well thought " "out, provides comprehensive flexibility, and avoids the necessity of " "defining additional traits classes. User declarations of functions that " "accept headers or messages as parameters are easy to write in a variety of " "ways to accomplish different results, without forcing cumbersome SFINAE " "declarations everywhere."