This is an automated email from the ASF dual-hosted git repository.
JosiahWI pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/trafficserver.git
The following commit(s) were added to refs/heads/master by this push:
new e241265286 Document `HTTPHdr` methods for #13420 review (#13422)
e241265286 is described below
commit e24126528683cc2514ae9681c3893c2822b5d7cb
Author: JosiahWI <[email protected]>
AuthorDate: Thu Jul 23 13:43:07 2026 -0500
Document `HTTPHdr` methods for #13420 review (#13422)
* Document HTTP methods for #13420 review
* Make changes requested by Brian Neradt
Put brief sentence on opening line
Use in/out/in,out parameter markers
Clarify that `@` headers are also included in length
---
include/proxy/hdrs/HTTP.h | 77 +++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 77 insertions(+)
diff --git a/include/proxy/hdrs/HTTP.h b/include/proxy/hdrs/HTTP.h
index 571bd0fdc5..eb73b68eb3 100644
--- a/include/proxy/hdrs/HTTP.h
+++ b/include/proxy/hdrs/HTTP.h
@@ -496,6 +496,23 @@ public:
int print(char *buf, int bufsize, int *bufindex, int *dumpoffset) const;
+ /** Returns the serialized byte length of the HTTP header.
+ *
+ * The count includes the request-line (for requests) or status-line (for
+ * responses), all header fields, and the terminating blank line. The message
+ * body is not included.
+ *
+ * @note Internal fields whose names begin with @c '@' are counted here even
+ * though @c print() omits them from its output, so this length may
+ * exceed the number of bytes @c print() actually writes.
+ *
+ * @return Serialized byte length of the header.
+ *
+ * @pre The header must be initialized.
+ *
+ * @par Thread Safety
+ * Not thread-safe.
+ */
int length_get() const;
HTTPType type_get() const;
@@ -616,10 +633,70 @@ public:
void mark_early_data(bool flag = true) const;
bool is_early_data() const;
+ /** Parse an HTTP/1.x request header incrementally from a raw buffer.
+ *
+ * Parses input data into the header's request fields. Call repeatedly with
the same @p parser
+ * until a result other than @c ParseResult::CONT is returned. When @c
ParseResult::DONE is
+ * returned, the request method, URL, version, and header fields are set on
this header.
+ *
+ * @param[in,out] parser Parser state. Must be the same
object on each call for a given message.
+ * @param[in,out] start On entry, points to the first
unparsed byte; on return,
+ * advanced past all consumed bytes.
+ * @param[in] end One past the last available byte of
input.
+ * @param[in] eof @c true if no more data will follow
@p end.
+ * @param[in] strict_uri_parsing URI compliance level: @c 0 performs
no compliance check; @c 1 rejects
+ * the URI unless every character is a
valid RFC 3986 URI character; @c 2
+ * is more permissive, rejecting the
URI only if it contains whitespace or
+ * non-printable characters. Other
values behave like @c 0.
+ * @param[in] max_request_line_size Maximum byte length of the request
line; exceeding it returns
+ * @c ParseResult::ERROR.
+ * @param[in] max_hdr_field_size Maximum byte length of a single
header field; exceeding it
+ * returns @c ParseResult::ERROR.
+ *
+ * @return @c ParseResult::DONE if a complete valid request header has been
parsed;
+ * @c ParseResult::CONT if more data is required;
+ * @c ParseResult::ERROR on a protocol error or exceeded limit.
+ *
+ * @pre The header must be initialized with @c HTTPType::REQUEST polarity.
+ *
+ * @par Thread Safety
+ * Not thread-safe.
+ */
ParseResult parse_req(HTTPParser *parser, const char **start, const char
*end, bool eof, int strict_uri_parsing = 0,
size_t max_request_line_size = UINT16_MAX, size_t
max_hdr_field_size = 131070);
ParseResult parse_resp(HTTPParser *parser, const char **start, const char
*end, bool eof);
+ /** Parse an HTTP/1.x request header incrementally from an @c IOBufferReader.
+ *
+ * Reads and consumes data from @p r, parsing it into the header's request
fields. Call
+ * repeatedly with the same @p parser until a result other than @c
ParseResult::CONT is
+ * returned. When @c ParseResult::DONE is returned, the request method, URL,
version, and
+ * header fields are set on this header.
+ *
+ * @param[in,out] parser Parser state. Must be the same
object on each call for a given message.
+ * @param[in,out] r Source of input data; bytes consumed
by the parser are removed from
+ * the reader.
+ * @param[out] bytes_used Must be non-null; set to the number
of bytes consumed from @p r.
+ * @param[in] eof @c true if no more data will be
provided after what is currently
+ * available on @p r.
+ * @param[in] strict_uri_parsing URI compliance level: @c 0 performs
no compliance check; @c 1 rejects
+ * the URI unless every character is a
valid RFC 3986 URI character; @c 2
+ * is more permissive, rejecting the
URI only if it contains whitespace or
+ * non-printable characters. Other
values behave like @c 0.
+ * @param[in] max_request_line_size Maximum byte length of the request
line; exceeding it returns
+ * @c ParseResult::ERROR.
+ * @param[in] max_hdr_field_size Maximum byte length of a single
header field; exceeding it
+ * returns @c ParseResult::ERROR.
+ *
+ * @return @c ParseResult::DONE if a complete valid request header has been
parsed;
+ * @c ParseResult::CONT if more data is required;
+ * @c ParseResult::ERROR on a protocol error or exceeded limit.
+ *
+ * @pre The header must be initialized with @c HTTPType::REQUEST polarity.
+ *
+ * @par Thread Safety
+ * Not thread-safe.
+ */
ParseResult parse_req(HTTPParser *parser, IOBufferReader *r, int
*bytes_used, bool eof, int strict_uri_parsing = 0,
size_t max_request_line_size = UINT16_MAX, size_t
max_hdr_field_size = UINT16_MAX);
ParseResult parse_resp(HTTPParser *parser, IOBufferReader *r, int
*bytes_used, bool eof);
