An implementation of HTTP-protocol parsing, formatting, and validation primitives per RFC 9110. More...
Enumerations | |
| enum class | sourcemeta::core::HTTPContentEncoding : std::uint8_t { HTTPContentEncoding::Identity , HTTPContentEncoding::GZIP } |
| enum class | sourcemeta::core::HTTPCacheVisibility : std::uint8_t { HTTPCacheVisibility::Public , HTTPCacheVisibility::Private } |
| enum class | sourcemeta::core::HTTPCookieSameSite : std::uint8_t { HTTPCookieSameSite::Strict , HTTPCookieSameSite::Lax , HTTPCookieSameSite::None } |
| enum class | sourcemeta::core::HTTPMethod : std::uint8_t { HTTPMethod::GET , HTTPMethod::HEAD , HTTPMethod::POST , HTTPMethod::PUT , HTTPMethod::DELETE , HTTPMethod::CONNECT , HTTPMethod::OPTIONS , HTTPMethod::TRACE , HTTPMethod::PATCH } |
Functions | |
| SOURCEMETA_CORE_HTTP_EXPORT auto | sourcemeta::core::http_match_accept (const std::string_view accept_header, std::initializer_list< std::string_view > candidates) -> std::string_view |
| SOURCEMETA_CORE_HTTP_EXPORT auto | sourcemeta::core::http_accept_includes_all (const std::string_view accept_header, std::initializer_list< std::string_view > media_types) noexcept -> bool |
| SOURCEMETA_CORE_HTTP_EXPORT auto | sourcemeta::core::http_content_type_matches (const std::string_view content_type_header, const std::string_view media_type) noexcept -> bool |
| SOURCEMETA_CORE_HTTP_EXPORT auto | sourcemeta::core::http_parse_media_type (const std::string_view media_type) -> std::optional< HTTPMediaType > |
| SOURCEMETA_CORE_HTTP_EXPORT auto | sourcemeta::core::http_match_media_range (const std::string_view media_type, std::span< const std::string_view > ranges) noexcept -> std::string_view |
| SOURCEMETA_CORE_HTTP_EXPORT auto | sourcemeta::core::http_match_accept_language (const std::string_view accept_language_header, std::initializer_list< std::string_view > candidates) -> std::string_view |
| SOURCEMETA_CORE_HTTP_EXPORT auto | sourcemeta::core::http_negotiate_encoding (const std::string_view accept_encoding_header, const HTTPContentEncoding server_preference) noexcept -> std::optional< HTTPContentEncoding > |
| SOURCEMETA_CORE_HTTP_EXPORT auto | sourcemeta::core::http_from_date (const std::string_view value) -> std::optional< std::chrono::system_clock::time_point > |
| SOURCEMETA_CORE_HTTP_EXPORT auto | sourcemeta::core::http_cache_control_max_age (const std::string_view cache_control) noexcept -> std::optional< std::chrono::seconds > |
| SOURCEMETA_CORE_HTTP_EXPORT auto | sourcemeta::core::http_format_link (const HTTPLink &link, std::string &out) -> void |
| SOURCEMETA_CORE_HTTP_EXPORT auto | sourcemeta::core::http_format_link (const HTTPLink &link) -> std::string |
| SOURCEMETA_CORE_HTTP_EXPORT auto | sourcemeta::core::http_format_links (std::span< const HTTPLink > links, std::string &out) -> void |
| SOURCEMETA_CORE_HTTP_EXPORT auto | sourcemeta::core::http_format_links (std::span< const HTTPLink > links) -> std::string |
| SOURCEMETA_CORE_HTTP_EXPORT auto | sourcemeta::core::http_cache_control_valid (const HTTPCacheControl &directives) -> bool |
| SOURCEMETA_CORE_HTTP_EXPORT auto | sourcemeta::core::http_serialize_cache_control (const HTTPCacheControl &directives, std::string &out) -> bool |
| SOURCEMETA_CORE_HTTP_EXPORT auto | sourcemeta::core::http_serialize_cache_control (const HTTPCacheControl &directives) -> std::optional< std::string > |
| SOURCEMETA_CORE_HTTP_EXPORT auto | sourcemeta::core::http_challenge_valid (const HTTPChallenge &challenge) -> bool |
| SOURCEMETA_CORE_HTTP_EXPORT auto | sourcemeta::core::http_serialize_challenge (const HTTPChallenge &challenge, std::string &out) -> bool |
| SOURCEMETA_CORE_HTTP_EXPORT auto | sourcemeta::core::http_serialize_challenge (const HTTPChallenge &challenge) -> std::optional< std::string > |
| SOURCEMETA_CORE_HTTP_EXPORT auto | sourcemeta::core::http_serialize_challenges (std::span< const HTTPChallenge > challenges, std::string &out) -> bool |
| SOURCEMETA_CORE_HTTP_EXPORT auto | sourcemeta::core::http_serialize_challenges (std::span< const HTTPChallenge > challenges) -> std::optional< std::string > |
| SOURCEMETA_CORE_HTTP_EXPORT auto | sourcemeta::core::http_parse_challenges (const std::string_view input, std::vector< HTTPParsedChallenge > &challenges) -> bool |
| SOURCEMETA_CORE_HTTP_EXPORT auto | sourcemeta::core::http_cookie_valid (const HTTPCookie &cookie) -> bool |
| SOURCEMETA_CORE_HTTP_EXPORT auto | sourcemeta::core::http_serialize_cookie (const HTTPCookie &cookie, std::string &out) -> bool |
| SOURCEMETA_CORE_HTTP_EXPORT auto | sourcemeta::core::http_serialize_cookie (const HTTPCookie &cookie) -> std::optional< std::string > |
| SOURCEMETA_CORE_HTTP_EXPORT auto | sourcemeta::core::http_expire_cookie (const HTTPCookie &cookie) -> HTTPCookie |
| SOURCEMETA_CORE_HTTP_EXPORT auto | sourcemeta::core::http_field_list_contains_any (const std::string_view header_value, std::initializer_list< std::string_view > tokens) noexcept -> bool |
| SOURCEMETA_CORE_HTTP_EXPORT auto | sourcemeta::core::http_format_vary (std::span< const std::string_view > field_names, std::string &out) -> bool |
| SOURCEMETA_CORE_HTTP_EXPORT auto | sourcemeta::core::http_format_vary (std::span< const std::string_view > field_names) -> std::optional< std::string > |
| SOURCEMETA_CORE_HTTP_EXPORT auto | sourcemeta::core::http_parse_bearer (const std::string_view authorization) noexcept -> std::string_view |
| auto SOURCEMETA_CORE_HTTP_EXPORT | sourcemeta::core::http_aws_sigv4_canonical_request (const std::string_view method, const std::string_view path, const std::string_view query, const std::span< const std::pair< std::string_view, std::string_view > > headers, const std::string_view payload_hash, const bool normalize=true) -> std::string |
| auto SOURCEMETA_CORE_HTTP_EXPORT | sourcemeta::core::http_aws_sigv4_signed_headers (const std::span< const std::pair< std::string_view, std::string_view > > headers) -> std::string |
| auto SOURCEMETA_CORE_HTTP_EXPORT | sourcemeta::core::http_aws_sigv4_credential_scope (const std::string_view date, const std::string_view region, const std::string_view service) -> std::string |
| auto SOURCEMETA_CORE_HTTP_EXPORT | sourcemeta::core::http_aws_sigv4_string_to_sign (const std::string_view amz_date, const std::string_view scope, const std::string_view canonical_request) -> std::string |
| auto SOURCEMETA_CORE_HTTP_EXPORT | sourcemeta::core::http_aws_sigv4_signing_key (const std::string_view secret, const std::string_view date, const std::string_view region, const std::string_view service) -> std::array< std::uint8_t, 32 > |
| auto SOURCEMETA_CORE_HTTP_EXPORT | sourcemeta::core::http_aws_sigv4_signature (const std::array< std::uint8_t, 32 > &signing_key, const std::string_view string_to_sign) -> std::string |
| auto SOURCEMETA_CORE_HTTP_EXPORT | sourcemeta::core::http_aws_sigv4_authorization (const std::string_view access_key_id, const std::string_view scope, const std::string_view signed_headers, const std::string_view signature) -> std::string |
| SOURCEMETA_CORE_HTTP_EXPORT auto | sourcemeta::core::http_is_baggage_value (const std::string_view value) noexcept -> bool |
| SOURCEMETA_CORE_HTTP_EXPORT auto | sourcemeta::core::http_is_baggage (const std::string_view value) noexcept -> bool |
| template<typename Callback> requires std::invocable<Callback, std::string_view, std::string_view, std::string_view> | |
| auto | sourcemeta::core::http_parse_baggage (const std::string_view value, Callback callback) -> bool |
| template<typename Callback> requires std::invocable<Callback, std::string_view, std::optional<std::string_view>> | |
| auto | sourcemeta::core::http_parse_baggage_properties (const std::string_view properties, Callback callback) -> bool |
| constexpr auto | sourcemeta::core::http_is_status_line (const std::string_view line) noexcept -> bool |
| template<typename Buffer> requires requires(Buffer buffer, std::string_view line) { buffer.clear(); buffer.append(line); } | |
| auto | sourcemeta::core::http_accumulate_header_line (Buffer &buffer, const std::string_view line) -> void |
| template<typename Callback> requires std::invocable<Callback, std::string_view, std::string_view> | |
| auto | sourcemeta::core::http_parse_headers (const std::string_view input, Callback callback) -> void |
| template<typename Callback> requires std::invocable<Callback, std::string_view, std::string_view> | |
| auto | sourcemeta::core::http_parse_cookies (const std::string_view input, Callback callback) -> void |
| template<typename Container> requires requires(Container container, std::string_view entry) { container.emplace_back(entry, entry); } | |
| auto | sourcemeta::core::http_parse_cookies (const std::string_view input, Container &cookies) -> void |
| template<typename Container> requires requires(Container container, std::string_view entry) { container.emplace_back(entry); } | |
| auto | sourcemeta::core::http_cookie_values (const std::string_view input, const std::string_view name, Container &values) -> void |
| template<typename Container> requires requires(Container container, std::string name, std::string value, const char character) { container.emplace_back(std::move(name), std::move(value)); { container.empty() } -> std::convertible_to<bool>; container.back().second += character; } | |
| auto | sourcemeta::core::http_parse_headers (const std::string_view input, Container &headers) -> void |
| template<typename Headers> | |
| auto | sourcemeta::core::http_serialize_headers (const Headers &headers) -> std::string |
| template<typename Headers> | |
| auto | sourcemeta::core::http_header_find (const Headers &headers, const std::string_view name) -> std::optional< std::string_view > |
| constexpr auto | sourcemeta::core::http_method_string (const HTTPMethod method) noexcept -> std::string_view |
| SOURCEMETA_CORE_HTTP_EXPORT auto | sourcemeta::core::http_make_problem_details (const HTTPProblemDetails &problem) -> sourcemeta::core::JSON |
| constexpr auto | sourcemeta::core::http_is_status_code (const std::string_view value) noexcept -> bool |
| constexpr auto | sourcemeta::core::http_status_from_code (const std::uint16_t code) noexcept -> HTTPStatus |
| auto | sourcemeta::core::http_is_ows (const char character) noexcept -> bool |
| auto | sourcemeta::core::http_is_tchar (const char character) noexcept -> bool |
| auto | sourcemeta::core::http_is_field_octet (const char character) noexcept -> bool |
| auto | sourcemeta::core::http_is_b64token_char (const char character) noexcept -> bool |
| auto | sourcemeta::core::http_is_b64token (const std::string_view value) noexcept -> bool |
| auto | sourcemeta::core::http_is_token (const std::string_view value) noexcept -> bool |
| auto | sourcemeta::core::http_encode_quoted_string (const std::string_view value, std::string &sink) -> bool |
| auto | sourcemeta::core::http_field_line_has_forbidden_byte (const std::string_view value) noexcept -> bool |
| auto | sourcemeta::core::http_trim_leading_ows (std::string_view value) noexcept -> std::string_view |
| auto | sourcemeta::core::http_trim_trailing_ows (std::string_view value) noexcept -> std::string_view |
| SOURCEMETA_CORE_HTTP_EXPORT auto | sourcemeta::core::http_scan_quoted_string (const std::string_view input, const std::size_t position, std::string &storage, std::string_view &value) -> std::optional< std::size_t > |
| constexpr auto | sourcemeta::core::http_traceparent_sampled (const std::uint8_t flags) noexcept -> bool |
| SOURCEMETA_CORE_HTTP_EXPORT auto | sourcemeta::core::http_is_traceparent (const std::string_view value) noexcept -> bool |
| SOURCEMETA_CORE_HTTP_EXPORT auto | sourcemeta::core::http_parse_traceparent (const std::string_view value) noexcept -> std::optional< HTTPTraceParent > |
| SOURCEMETA_CORE_HTTP_EXPORT auto | sourcemeta::core::http_make_traceparent (const bool sampled) -> std::array< char, 55 > |
| SOURCEMETA_CORE_HTTP_EXPORT auto | sourcemeta::core::http_continue_traceparent (const std::string_view value, const bool sampled) -> std::optional< std::array< char, 55 > > |
| SOURCEMETA_CORE_HTTP_EXPORT auto | sourcemeta::core::http_is_tracestate (const std::string_view value) noexcept -> bool |
| template<typename Callback> requires std::invocable<Callback, std::string_view, std::string_view> | |
| auto | sourcemeta::core::http_parse_tracestate (const std::string_view value, Callback callback) -> bool |
| template<typename Container> requires requires(Container container, std::string_view entry) { container.emplace_back(entry, entry); } | |
| auto | sourcemeta::core::http_parse_tracestate (const std::string_view value, Container &members) -> bool |
An implementation of HTTP-protocol parsing, formatting, and validation primitives per RFC 9110.
Media types live in this module rather than in a MIME one because HTTP defines its own grammar for them. RFC 9110 §8.3.1 builds a media type from the HTTP token of §5.6.2, while the MIME grammar of RFC 2045 §5.1 admits curly braces, and a MIME header field further admits the comments and folding whitespace that HTTP has no equivalent of. RFC 9112 Appendix B.1 states that "HTTP is not a MIME-compliant protocol". Only the registration vocabulary of RFC 6838, the structured syntax suffix among it, is common to both.
This functionality is included as follows:
| struct sourcemeta::core::HTTPMediaType |
The parts of a media type per RFC 9110 §8.3.1, as views borrowed from the input.
Public Attributes | |
|---|---|
| std::string_view | type {} |
| The type, such as application. | |
| std::string_view | subtype {} |
| The subtype, such as geo+json. | |
| std::string_view | suffix {} |
| std::string_view | parameters {} |
| The parameters that follow the type, starting at the first ;. | |
| std::string_view sourcemeta::core::HTTPMediaType::suffix {} |
The structured syntax suffix per RFC 6838 §4.2, carrying the leading + that the IANA registry names it by, such as +JSON. Empty when the subtype has none
| struct sourcemeta::core::HTTPLink |
A typed RFC 8288 §3 link-value. The caller owns the backing storage for every field, must URI-escape target, and must ensure parameter values are valid quoted-string content.
| struct sourcemeta::core::HTTPCacheControl |
The response directives to serialise into an RFC 9111 §5.2 Cache-Control header value. The caller owns the backing storage for every field.
Whether a response may be stored by a shared cache is an access decision as much as a performance one, so it is carried as one alternative rather than as two independent flags that could both be set.
Public Attributes | |
|---|---|
| std::optional< HTTPCacheVisibility > | visibility {} |
| Which caches may store the response. | |
| std::optional< std::chrono::seconds > | max_age {} |
| How long the response stays fresh (RFC 9111 §5.2.2.1). | |
| std::optional< std::chrono::seconds > | shared_max_age {} |
| bool | no_store {false} |
| Whether no cache may store any part of the exchange (RFC 9111 §5.2.2.5). | |
| bool | no_cache {false} |
| bool | must_revalidate {false} |
| bool | proxy_revalidate {false} |
| The same for a shared cache alone (RFC 9111 §5.2.2.8). | |
| bool | must_understand {false} |
| bool | no_transform {false} |
| Whether the payload must not be transformed (RFC 9111 §5.2.2.6). | |
| bool | immutable {false} |
| Whether the response will not be updated while fresh (RFC 8246). | |
| std::span< const std::string_view > | private_fields {} |
| std::span< const std::string_view > | no_cache_fields {} |
| bool sourcemeta::core::HTTPCacheControl::must_revalidate {false} |
Whether a stale response must be validated before reuse (RFC 9111 §5.2.2.2)
| bool sourcemeta::core::HTTPCacheControl::must_understand {false} |
Whether storing is limited to a cache that implements the status code's caching requirements (RFC 9111 §5.2.2.3)
| bool sourcemeta::core::HTTPCacheControl::no_cache {false} |
Whether the response must be validated before every reuse (RFC 9111 §5.2.2.4), ignored when a field list qualifies it below
| std::span<const std::string_view> sourcemeta::core::HTTPCacheControl::no_cache_fields {} |
The fields that must be revalidated before reuse, which qualifies the no-cache directive (RFC 9111 §5.2.2.4)
| std::span<const std::string_view> sourcemeta::core::HTTPCacheControl::private_fields {} |
The fields a shared cache must not store, which qualifies the private directive and so requires it (RFC 9111 §5.2.2.7)
| std::optional<std::chrono::seconds> sourcemeta::core::HTTPCacheControl::shared_max_age {} |
How long the response stays fresh for a shared cache, overriding the above for one (RFC 9111 §5.2.2.10)
| struct sourcemeta::core::HTTPChallenge |
A challenge to serialise into an RFC 9110 §11.6.1 WWW-Authenticate response header value. The caller owns the backing storage for every field.
RFC 9110 §11.3 gives challenge = auth-scheme [ 1*SP ( token68 / #auth-param ) ], so a challenge carries either a credential or a parameter list and never both.
| struct sourcemeta::core::HTTPParsedChallenge |
A challenge read out of an RFC 9110 §11.6.1 WWW-Authenticate header value. Unlike the challenge a caller hands to the serialiser, this one owns its strings, since a quoted-pair means a value does not always appear verbatim in the field it was read from.
| struct sourcemeta::core::HTTPCookie |
A cookie to serialise into an RFC 6265 §4.1 Set-Cookie response header value. The caller owns the backing storage for every field. A valid cookie has a name that is an RFC 9110 §5.6.2 token and a value made of RFC 6265 §4.1.1 cookie-octets. RFC 6265bis §5.7 requires a cookie with a same-site mode of none to also be secure.
Public Attributes | |
|---|---|
| std::string_view | name {} |
| The cookie name. | |
| std::string_view | value {} |
| The cookie value. | |
| std::optional< std::string_view > | path {} |
| The path the cookie is scoped to. | |
| std::optional< std::string_view > | domain {} |
| The host the cookie is scoped to. | |
| std::optional< std::chrono::seconds > | max_age {} |
| The cookie lifetime. | |
| bool | http_only {false} |
| Whether the cookie is withheld from scripts. | |
| bool | secure {false} |
| Whether the cookie is only sent over secure channels. | |
| std::optional< HTTPCookieSameSite > | same_site {} |
| The cross-site request policy for the cookie. | |
| struct sourcemeta::core::HTTPAWSCredentials |
The credentials used to sign a request with AWS Signature Version 4. The session token is left empty when using long-term credentials.
| class sourcemeta::core::HTTPError |
An error that prevented obtaining a response, such as a connection failure, a name resolution failure, or a TLS failure. For example:
Public Member Functions | |
|---|---|
| HTTPError (const StaticString message, const HTTPMethod method, std::string url) | |
| Construct an error from a message, the request method, and the URL. | |
| HTTPError (const StaticString message, const HTTPMethod method, std::string url, std::string detail) | |
| auto | method () const noexcept -> HTTPMethod |
| Get the request method that triggered the failure. | |
| auto | url () const noexcept -> const std::string & |
| Get the request URL that triggered the failure. | |
| auto | detail () const noexcept -> std::string_view |
| Get what the backend reported, empty when it reported nothing. | |
| Public Member Functions inherited from sourcemeta::core::Error | |
| auto | message () const noexcept -> StaticString |
Additional Inherited Members | |
| Protected Member Functions inherited from sourcemeta::core::Error | |
| Error (const StaticString message) noexcept | |
| Construct the error given its message. | |
|
inline |
Construct an error that also carries what the backend reported, which is the only account of the failure that names the condition the system hit
| class sourcemeta::core::HTTPTimeoutError |
An error for a request that did not complete within its configured timeout. For example:
Public Member Functions | |
|---|---|
| HTTPTimeoutError (const HTTPMethod method, std::string url, const std::chrono::milliseconds timeout) | |
| auto | timeout () const noexcept -> std::chrono::milliseconds |
| Public Member Functions inherited from sourcemeta::core::HTTPError | |
| HTTPError (const StaticString message, const HTTPMethod method, std::string url) | |
| Construct an error from a message, the request method, and the URL. | |
| HTTPError (const StaticString message, const HTTPMethod method, std::string url, std::string detail) | |
| auto | method () const noexcept -> HTTPMethod |
| Get the request method that triggered the failure. | |
| auto | url () const noexcept -> const std::string & |
| Get the request URL that triggered the failure. | |
| auto | detail () const noexcept -> std::string_view |
| Get what the backend reported, empty when it reported nothing. | |
| Public Member Functions inherited from sourcemeta::core::Error | |
| auto | message () const noexcept -> StaticString |
Additional Inherited Members | |
| Protected Member Functions inherited from sourcemeta::core::Error | |
| Error (const StaticString message) noexcept | |
| Construct the error given its message. | |
|
inline |
Construct an error from the request method, URL, and the total timeout that was configured for the request
|
inlinenodiscardnoexcept |
Get the total timeout that was configured for the request. A backend does not report which of the configured bounds elapsed, so this is the total timeout even when a narrower connection timeout was the one hit
| class sourcemeta::core::HTTPStatusError |
An error for a response with an unsuccessful status code, owning a copy of the status data. For example:
Public Member Functions | |
|---|---|
| HTTPStatusError (const HTTPMethod method, std::string url, const HTTPStatus &status) | |
| auto | status () const noexcept -> HTTPStatus |
| Public Member Functions inherited from sourcemeta::core::HTTPError | |
| HTTPError (const StaticString message, const HTTPMethod method, std::string url) | |
| Construct an error from a message, the request method, and the URL. | |
| HTTPError (const StaticString message, const HTTPMethod method, std::string url, std::string detail) | |
| auto | method () const noexcept -> HTTPMethod |
| Get the request method that triggered the failure. | |
| auto | url () const noexcept -> const std::string & |
| Get the request URL that triggered the failure. | |
| auto | detail () const noexcept -> std::string_view |
| Get what the backend reported, empty when it reported nothing. | |
| Public Member Functions inherited from sourcemeta::core::Error | |
| auto | message () const noexcept -> StaticString |
Additional Inherited Members | |
| Protected Member Functions inherited from sourcemeta::core::Error | |
| Error (const StaticString message) noexcept | |
| Construct the error given its message. | |
|
inline |
Construct an error from the request method, URL, and the unsuccessful response status
|
inlinenodiscardnoexcept |
Get the response status that triggered the failure. The contained views borrow from this error and stay valid for its lifetime
| class sourcemeta::core::HTTPEntropyError |
An error raised when no non-zero trace context identifier could be drawn.
Additional Inherited Members | |
| Public Member Functions inherited from sourcemeta::core::Error | |
| auto | message () const noexcept -> StaticString |
| Protected Member Functions inherited from sourcemeta::core::Error | |
| Error (const StaticString message) noexcept | |
| Construct the error given its message. | |
| struct sourcemeta::core::HTTPProblemDetails |
Fields of an RFC 9457 §3.1 Problem Details object.
Public Attributes | |
|---|---|
| HTTPStatus | status |
| The HTTP status code for this occurrence of the problem. | |
| JSON::StringView | type {"about:blank"} |
| The identifier for the problem type. | |
| JSON::StringView | title {} |
| The short human-readable summary of the problem type. | |
| JSON::StringView | detail {} |
| The human-readable explanation specific to this occurrence. | |
| JSON::StringView | instance {} |
| The identifier for this specific occurrence of the problem. | |
| struct sourcemeta::core::HTTPStatus |
A typed HTTP status code per RFC 9110 §15. For example:
Public Attributes | |
|---|---|
| std::uint16_t | code |
| The numeric status code. | |
| std::string_view | phrase |
| The reason phrase. | |
| std::string_view | wire |
| The status code and reason phrase in their wire form. | |
| struct sourcemeta::core::HTTPResponse |
The result of performing a request against a system HTTP backend. For example:
Public Attributes | |
|---|---|
| HTTPStatus | status {} |
| The response status code. | |
| std::vector< std::pair< std::string, std::string > > | headers |
| std::string | body |
| The response body, owned by this result. | |
| std::string | url |
| The effective URL after any followed redirects. | |
| std::vector<std::pair<std::string, std::string> > sourcemeta::core::HTTPResponse::headers |
The response headers, with names normalised to lowercase. Repeated headers are preserved as separate entries, though some backends fold them into a single comma-separated entry, which is lossy and incorrect for a Set-Cookie header that "cannot be combined into a single field value" (RFC 9110 §5.3)
| class sourcemeta::core::HTTPSystemBackendError |
An error that prevented loading the underlying system HTTP backend, such as a missing dynamically loaded library. For example:
Public Member Functions | |
|---|---|
| HTTPSystemBackendError (const std::string &message, std::string variable, std::vector< std::string > paths) | |
| auto | variable () const noexcept -> const std::string & |
| Get the name of the environment variable that overrides the backend path. | |
| auto | paths () const noexcept -> const std::vector< std::string > & |
| Get the paths that were searched while looking for the backend. | |
|
inline |
Construct an error from a message, the environment variable that overrides the backend path, and the paths that were searched
| class sourcemeta::core::HTTPSystemRequest |
A simple cross-platform HTTP request that delegates to the system HTTP stack, NSURLSession on Apple platforms, WinHTTP on Windows, and cURL everywhere else. The request owns its data, configure it with the builder methods and perform it with send. For example:
Public Member Functions | |
|---|---|
| HTTPSystemRequest (std::string url, const HTTPMethod method=HTTPMethod::GET) | |
| Construct a request for the given URL and method. | |
| auto | method (const HTTPMethod method) -> HTTPSystemRequest & |
| Set the request method. | |
| auto | header (std::string name, std::string value) -> HTTPSystemRequest & |
| auto | header (std::string name, SecureString value) -> HTTPSystemRequest & |
| auto | header (const std::string_view name) const -> std::optional< std::string_view > |
| auto | headers () const noexcept -> const auto & |
| Get the request headers configured so far, in the order they were added. | |
| auto | body (std::string data, std::string content_type) -> HTTPSystemRequest & |
| auto | body (SecureString data, std::string content_type) -> HTTPSystemRequest & |
| auto | follow_redirects (const bool value) -> HTTPSystemRequest & |
| Set whether to follow redirects, on by default. | |
| auto | maximum_redirects (const std::size_t value) -> HTTPSystemRequest & |
| Set the maximum number of redirects to follow, 20 by default. | |
| auto | timeout (const std::chrono::milliseconds value) -> HTTPSystemRequest & |
| Set the total request timeout, 30 seconds by default. | |
| auto | connect_timeout (const std::chrono::milliseconds value) -> HTTPSystemRequest & |
| auto | maximum_response_size (const std::size_t value) -> HTTPSystemRequest & |
| Abort with an error if the response body exceeds this number of bytes. | |
| auto | sign_aws_sigv4 (const HTTPAWSCredentials &credentials, const std::string_view region, const std::string_view service, const std::chrono::system_clock::time_point moment=std::chrono::system_clock::now()) -> HTTPSystemRequest & |
| auto | send () const -> HTTPResponse |
|
inline |
Set the request body from wiping storage, sent along with the given Content-Type header. The body is held in the wiping storage so a secret it carries, such as a client secret or PKCE code verifier, is never copied into an ordinary string. A content type carrying a carriage return, line feed, or NUL is refused, leaving the request unchanged
|
inline |
Set the request body, sent along with the given Content-Type header. A content type carrying a carriage return, line feed, or NUL is refused, leaving the request unchanged
|
inline |
Set a best-effort timeout for establishing the connection, applied as each backend allows and falling back to the backend default when unset
|
inlinenodiscard |
Get the value of the first header with the given name, compared case insensitively, or no value when no such header was added. For example:
|
inline |
Add a request header from wiping storage. The value is held in the wiping storage so a secret it carries, such as a client credential, is never retained in an ordinary string, and the transient serialisation a backend builds at send time is wiped
|
inline |
Add a request header. Repeated names are permitted. A name or value carrying a carriage return, line feed, or NUL is refused, leaving the request unchanged
|
nodiscard |
Perform the request. A failure to obtain a response is reported as an error, while unsuccessful status codes are returned on the result. This blocks the calling thread until the response arrives or a timeout elapses, so it must not run on an event loop or any other thread serving unrelated work.
| auto sourcemeta::core::HTTPSystemRequest::sign_aws_sigv4 | ( | const HTTPAWSCredentials & | credentials, |
| const std::string_view | region, | ||
| const std::string_view | service, | ||
| const std::chrono::system_clock::time_point | moment = std::chrono::system_clock::now() ) -> HTTPSystemRequest & |
Sign this request with AWS Signature Version 4, stamping the x-amz-date, x-amz-content-sha256, and Authorization headers, plus x-amz-security-token when the credentials carry a session token. The path is normalised for every service except Amazon S3. The timestamp defaults to the current time. For example:
| struct sourcemeta::core::HTTPTraceParent |
The fields of a traceparent field value. Every view borrows the input, so the value these came from must outlive them.
Public Attributes | |
|---|---|
| std::uint8_t | version {0} |
| std::string_view | trace_id |
| std::string_view | parent_id |
| std::uint8_t | flags {0} |
| An eight bit field of which one bit is currently defined. | |
| std::string_view sourcemeta::core::HTTPTraceParent::parent_id |
Identifies the operation that made this request, as 16 lowercase hexadecimal characters
| std::string_view sourcemeta::core::HTTPTraceParent::trace_id |
Identifies the trace this request belongs to, as 32 lowercase hexadecimal characters
| std::uint8_t sourcemeta::core::HTTPTraceParent::version {0} |
The revision of the field format this value was written to. Note that a value being forwarded is not sent on under this revision but under "the highest version of the specification known to the implementation", so a higher one read here is reported rather than endorsed.
|
strong |
Whether a cached response may be stored by a shared cache or only by a private one (RFC 9111 §5.2.2.7 and §5.2.2.9). The two are alternatives rather than flags, so a response cannot be marked both.
|
strong |
|
strong |
|
strong |
A request method per RFC 9110 §9.3 and RFC 5789 §2.
|
noexcept |
Test whether every media type is individually acceptable under an Accept header per RFC 9110 §12.5.1. For example:
|
inline |
Accumulate raw header lines into a buffer, retaining only the block of the most recent message, given that transparently following redirects or receiving interim responses produces one header block per message. For example:
| auto SOURCEMETA_CORE_HTTP_EXPORT sourcemeta::core::http_aws_sigv4_authorization | ( | const std::string_view | access_key_id, |
| const std::string_view | scope, | ||
| const std::string_view | signed_headers, | ||
| const std::string_view | signature ) -> std::string |
Assemble the AWS Signature Version 4 Authorization header value from an access key, credential scope, signed headers, and signature. For example:
| auto SOURCEMETA_CORE_HTTP_EXPORT sourcemeta::core::http_aws_sigv4_canonical_request | ( | const std::string_view | method, |
| const std::string_view | path, | ||
| const std::string_view | query, | ||
| const std::span< const std::pair< std::string_view, std::string_view > > | headers, | ||
| const std::string_view | payload_hash, | ||
| const bool | normalize = true ) -> std::string |
Compute the AWS Signature Version 4 canonical request from a request method, path, query, headers, and payload hash. Each path segment and query parameter is decoded and re-encoded into canonical form, so the path and query may be passed exactly as they appear in the request target. The path is optionally normalised by collapsing sequential slashes and removing dot segments, which every service except Amazon S3 requires. For example:
| auto SOURCEMETA_CORE_HTTP_EXPORT sourcemeta::core::http_aws_sigv4_credential_scope | ( | const std::string_view | date, |
| const std::string_view | region, | ||
| const std::string_view | service ) -> std::string |
Compute the AWS Signature Version 4 credential scope from a date, region, and service. For example:
| auto SOURCEMETA_CORE_HTTP_EXPORT sourcemeta::core::http_aws_sigv4_signature | ( | const std::array< std::uint8_t, 32 > & | signing_key, |
| const std::string_view | string_to_sign ) -> std::string |
Compute the AWS Signature Version 4 hex signature from a signing key and a string to sign. For example:
| auto SOURCEMETA_CORE_HTTP_EXPORT sourcemeta::core::http_aws_sigv4_signed_headers | ( | const std::span< const std::pair< std::string_view, std::string_view > > | headers | ) | -> std::string |
Compute the AWS Signature Version 4 signed headers list, the lowercased header names sorted and joined with a semicolon. For example:
| auto SOURCEMETA_CORE_HTTP_EXPORT sourcemeta::core::http_aws_sigv4_signing_key | ( | const std::string_view | secret, |
| const std::string_view | date, | ||
| const std::string_view | region, | ||
| const std::string_view | service ) -> std::array< std::uint8_t, 32 > |
Derive the AWS Signature Version 4 signing key from a secret access key, date, region, and service. For example:
| auto SOURCEMETA_CORE_HTTP_EXPORT sourcemeta::core::http_aws_sigv4_string_to_sign | ( | const std::string_view | amz_date, |
| const std::string_view | scope, | ||
| const std::string_view | canonical_request ) -> std::string |
Compute the AWS Signature Version 4 string to sign from a timestamp, a credential scope, and a canonical request. For example:
|
noexcept |
Read the max-age response directive from a Cache-Control header value per RFC 9111 §5.2.2.1. Returns an empty value when the directive is absent or malformed. A value larger than the cache can represent saturates to 2147483648 seconds as mandated by RFC 9111 §1.2.2. For example:
| SOURCEMETA_CORE_HTTP_EXPORT auto sourcemeta::core::http_cache_control_valid | ( | const HTTPCacheControl & | directives | ) | -> bool |
Test whether a set of directives can be serialised into a valid RFC 9111 §5.2 Cache-Control header value: every duration is the non-negative integer §1.2.2 defines, every qualifying field name is an RFC 9110 §5.6.2 token, a private field list is accompanied by the directive it qualifies, and at least one directive is named, since §5.2 lists them and RFC 9110 §5.6.1.1 forbids a sender from generating an empty list element.
| SOURCEMETA_CORE_HTTP_EXPORT auto sourcemeta::core::http_challenge_valid | ( | const HTTPChallenge & | challenge | ) | -> bool |
Test whether a challenge can be serialised into a valid RFC 9110 §11.6.1 WWW-Authenticate header value: the scheme is a non-empty RFC 9110 §5.6.2 token, a present credential is a §11.2 token68 and stands alone, every parameter name is a token, no parameter name repeats under the case-insensitive matching §11.2 mandates, and every value is encodable as a §5.6.4 quoted-string.
A challenge naming the Bearer scheme is held to RFC 6750 §3 as well, which requires at least one parameter and bounds the octets scope, Error, error_description and error_uri may carry. For example:
|
noexcept |
Test whether a Content-Type header denotes the given media type per RFC 9110 §8.3.1. For example:
| SOURCEMETA_CORE_HTTP_EXPORT auto sourcemeta::core::http_continue_traceparent | ( | const std::string_view | value, |
| const bool | sampled ) -> std::optional< std::array< char, 55 > > |
Generate the traceparent field value to send onward for a request that arrived carrying one. The trace continues, so its identifier is kept, while the operation is this one rather than the caller's, which is the mutation the specification calls "the most typical" and says "should be considered a default".
The input is the field value that arrived rather than its parsed fields, so that what is carried over is known to be well formed, and nothing comes back for one that does not parse.
The sampling decision is the one being made here rather than the one that arrived, since the flag "reflects the caller's recording behavior" and the caller is now this service. Read the arriving decision off the parsed flags to pass it on unchanged. A value read at a later revision is written back at the revision this library implements, which is the downgrade a reader of one owes, and whatever that value appended is dropped with it. For example:
| SOURCEMETA_CORE_HTTP_EXPORT auto sourcemeta::core::http_cookie_valid | ( | const HTTPCookie & | cookie | ) | -> bool |
Test whether a cookie can be serialised into a valid RFC 6265 §4.1 Set-Cookie header value: the name is a non-empty RFC 9110 §5.6.2 token, the value is made of RFC 6265 §4.1.1 cookie-octets, any path is made of RFC 6265bis av-octets, any domain is a valid RFC 1123 host name allowing an ignorable leading dot, a present max_age is not negative, per RFC 6265bis §5.7 a HTTPCookieSameSite::None cookie is also secure, and the RFC 6265bis §4.1.3 __Secure- and __Host- name prefixes carry their required attributes. The RFC 6265bis §5.6 and §5.7 length ceilings are enforced too, since a cookie past either is ignored in whole or in part by the user agent. For example:
|
inline |
Collect every value carried under the given cookie name, in the order the header presents them. A request may carry several cookies with one name, since a parent domain and the host itself can each set one and RFC 6265 §4.2.2 notes the server "cannot determine from the Cookie header alone [...] for which hosts the cookie is valid". That section also warns that servers "SHOULD NOT rely upon the order in which these cookies appear", so a caller verifying a signed cookie tries every value rather than any single one. Naming a cookie with the RFC 6265bis §4.1.3.2 __Host- prefix prevents the collision at the source.
The values are borrowed from input rather than copied, so a container of views must not outlive it, while an owning container may. For example:
|
inline |
Append a string to the sink as a quoted-string (RFC 9110 Section 5.6.4), wrapping it in double quotes and escaping any double quote or backslash, returning whether it was encodable. Nothing is appended when the string carries a byte no quoted-string admits, such as a control character, which keeps a value from injecting into a header. For example:
| SOURCEMETA_CORE_HTTP_EXPORT auto sourcemeta::core::http_expire_cookie | ( | const HTTPCookie & | cookie | ) | -> HTTPCookie |
Derive the cookie that removes a cookie, carrying its name and every attribute across so that the RFC 6265 §3.1 requirement to match the path and the domain of the original is met by construction. The value is dropped, and the lifetime is set to zero, which RFC 6265bis §5.6.2 maps to "the earliest representable date and time". For example:
|
inlinenoexcept |
Whether a field name or value carries a byte that must never appear on a field line, a carriage return, a line feed, or a NUL (RFC 9110 Section 5.5). For example:
|
noexcept |
Test whether a comma-separated header value per RFC 9110 §5.6.1 lists any of the given tokens. For example:
| SOURCEMETA_CORE_HTTP_EXPORT auto sourcemeta::core::http_format_link | ( | const HTTPLink & | link | ) | -> std::string |
Format an RFC 8288 §3 link-value. For example:
| SOURCEMETA_CORE_HTTP_EXPORT auto sourcemeta::core::http_format_link | ( | const HTTPLink & | link, |
| std::string & | out ) -> void |
Append an RFC 8288 §3 link-value to out. For example:
| SOURCEMETA_CORE_HTTP_EXPORT auto sourcemeta::core::http_format_links | ( | std::span< const HTTPLink > | links | ) | -> std::string |
Format an RFC 8288 §3.5 comma-separated multi-link value. For example:
| SOURCEMETA_CORE_HTTP_EXPORT auto sourcemeta::core::http_format_links | ( | std::span< const HTTPLink > | links, |
| std::string & | out ) -> void |
Append an RFC 8288 §3.5 comma-separated multi-link value to out. For example:
| SOURCEMETA_CORE_HTTP_EXPORT auto sourcemeta::core::http_format_vary | ( | std::span< const std::string_view > | field_names | ) | -> std::optional< std::string > |
Compose an RFC 9110 §12.5.5 Vary header value, returning no value when any member is not an RFC 9110 §5.6.2 token or when there are none.
Note that RFC 9110 §12.5.5 forbids a proxy from generating the wildcard member, so only an origin server may compose one. For example:
| SOURCEMETA_CORE_HTTP_EXPORT auto sourcemeta::core::http_format_vary | ( | std::span< const std::string_view > | field_names, |
| std::string & | out ) -> bool |
Append an RFC 9110 §12.5.5 Vary header value to out, returning true on success. Every member must be a non-empty RFC 9110 §5.6.2 token, which the wildcard also is, since §5.1 defines a field name as one and §5.6.1.1 forbids a sender from generating an empty list element. An empty list has nothing to send, so the header is left to be omitted rather than emitted blank. The spelling of each name is kept as given, as §5.1 makes field names case-insensitive. Nothing is appended and this returns false when any member is refused, which keeps a name from injecting a further field. For example:
| SOURCEMETA_CORE_HTTP_EXPORT auto sourcemeta::core::http_from_date | ( | const std::string_view | value | ) | -> std::optional< std::chrono::system_clock::time_point > |
Parse an HTTP-date string per RFC 9110 §5.6.7. For example:
|
inline |
Find the value of the first header with the given lowercase name in any range of name and value pairs, returning no result when absent. For example:
|
inlinenoexcept |
Whether a string is a well-formed token68 (RFC 7235 Section 2.1) or b64token (RFC 6750 Section 2.1), at least one alphabet character followed by any "=" padding. For example:
|
inlinenoexcept |
Whether a character may appear in the alphabet of a token68 (RFC 7235 Section 2.1) or b64token (RFC 6750 Section 2.1) credential, before its padding. For example:
|
noexcept |
Whether the input is a well-formed baggage field value. The grammar is in W3C Baggage Section 3.3.1, and whitespace at the two outer ends of the input is accepted although the list production does not place any there, since a field value does not carry such whitespace to begin with.
A member is a key and a value, optionally trailed by a semicolon-delimited property set whose own entries may be a bare key. Whitespace around a key or a value is allowed and is not part of it. A repeated key is allowed, since "Uniqueness of keys between multiple list-members in a baggage-string is not guaranteed", where tracestate holds that "Only one entry per key is allowed".
The grammar caps the list at 180 members. The separate figures of 64 members and 8192 bytes are the point past which a platform "MAY drop list-members" rather than a bound on what is well formed, so they are not checked here. For example:
|
noexcept |
Whether the input is a well-formed baggage value, which is the part of a member after its equals sign. The grammar is in W3C Baggage Section 3.3.1, and this is stricter than it on one point, noted below.
The permitted octets leave out the control characters, whitespace, the double quote, the comma, the semicolon and the backslash, so a value carrying any of those has to percent-encode it. This also requires that a percent introduces an encoded octet, which is stricter than the grammar, where the percent is an octet like any other. The prose is what forbids a bare one. An empty value is well formed, where a tracestate value has to end in a mandatory non-blank character and so cannot be empty. For example:
|
inlinenoexcept |
Whether the character is one a field value may carry. RFC 9110 Section 5.5 admits the visible characters and obsolete text, along with the spaces and horizontal tabs between them, and nothing else: "field-vchar = VCHAR / obs-text" Every other control character is excluded, and a recipient of one of those "MUST either reject the message or replace each of those characters with SP before further processing". For example:
|
inlinenoexcept |
Whether a character is optional whitespace, a space or a horizontal tab (RFC 9110 Section 5.6.3). For example:
|
constexprnoexcept |
Check whether a string is a three digit HTTP status code, which RFC 9110 Section 15 gives as three digits whose first is 1 through 5. This asks about the form alone, as a code may be well formed without the registry naming it. For example:
|
constexprnoexcept |
Test whether a raw line opens a message header block per RFC 9112 §4. For example:
|
inlinenoexcept |
Whether a character is a token character (RFC 9110 Section 5.6.2), the set a bare header token draws from. For example:
|
inlinenoexcept |
Whether a string is a well-formed token (RFC 9110 Section 5.6.2), at least one token character and nothing else. For example:
|
noexcept |
Whether the input is a well-formed traceparent field value. The grammar in W3C Trace Context Section 3.2.2 is written for version 00, and a higher version is admitted under the rules for reading one in Section 3.2.4.
Version 00 is exactly 55 characters and admits nothing further. A later version may append, since a reader is told to "check that the 2 characters are either the end of the string or a dash", so a longer value must carry a dash where the flags end. Whatever follows that dash is left uninterpreted, because "Vendors MUST NOT parse or assume anything about unknown fields for this version", but it is still held to the octets a field value may carry, so a carriage return or a line feed there is refused. Version ff is invalid, and an identifier of all zeroes is "considered an invalid value". For example:
|
noexcept |
Whether the input is a well-formed tracestate field value (RFC 5234 ABNF in W3C Trace Context Section 3.3.1).
The grammar is permissive in ways that surprise: at most 32 members, and "Empty and whitespace-only list members are allowed. Vendors MUST accept empty tracestate headers". Since "Spaces and horizontal tabs surrounding list-members are ignored", a member padded on either side is accepted and so is one made only of padding. Padding at the two outer ends of the whole value is a little more than the list production writes down, and is accepted on that same sentence. A member's value, in contrast, cannot be empty. Note that baggage differs on every one of those points.
This rejects a repeated key, which the grammar alone does not forbid, on the rule that "Only one entry per key is allowed because the entry represents that last position in the trace". A reader is offered the alternative of dropping just the repeated entry, but only in a section marked non-normative. For example:
| SOURCEMETA_CORE_HTTP_EXPORT auto sourcemeta::core::http_make_problem_details | ( | const HTTPProblemDetails & | problem | ) | -> sourcemeta::core::JSON |
Build an RFC 9457 §3.1 Problem Details JSON object. For example:
| SOURCEMETA_CORE_HTTP_EXPORT auto sourcemeta::core::http_make_traceparent | ( | const bool | sampled | ) | -> std::array< char, 55 > |
Generate a traceparent field value that starts a new trace, drawing both identifiers from the random provider of the crypto module. This is what a request that arrived without one needs, and it is also the mutation that regenerates every property, which a service acting as "a front gate into secure networks" performs to shed what it was handed.
Note that the identifiers are only unguessable to the degree that provider is, which varies with how the library was built, and that the requirement on a generator is strict: "Random number generators MUST NOT rely on any information that can potentially be user-identifiable". For example:
| SOURCEMETA_CORE_HTTP_EXPORT auto sourcemeta::core::http_match_accept | ( | const std::string_view | accept_header, |
| std::initializer_list< std::string_view > | candidates ) -> std::string_view |
Pick the best media-type candidate against an Accept header per RFC 9110 §12.5.1. Returns an empty value when no candidate is acceptable. The returned view borrows from candidates. For example:
| SOURCEMETA_CORE_HTTP_EXPORT auto sourcemeta::core::http_match_accept_language | ( | const std::string_view | accept_language_header, |
| std::initializer_list< std::string_view > | candidates ) -> std::string_view |
Pick the best language-tag candidate against an Accept-Language header per RFC 9110 §12.5.4, which lets an implementation choose its matching scheme. This uses a q-aware Basic-Filtering-style scheme (RFC 4647 §3.3.1, the scheme RFC 9110 §12.5.4 points to) that also honors q=0 exclusions. Returns an empty value when no candidate is acceptable. The returned view borrows from candidates. For example:
|
noexcept |
Pick the most specific media range that a media type matches per RFC 9110 §12.5.1, where an exact type beats a subtype wildcard, which in turn beats a full wildcard, and a range that pins a parameter the media type also carries is more specific still. A weight on a range is not a media type parameter and takes no part in matching. Selection looks only at the type and the parameters it is given, so neither side has to be well-formed beyond its type. Returns an empty value when none match. The returned view borrows from ranges. For example:
|
constexprnoexcept |
Convert a request method into its case-sensitive token per RFC 9110 §9.1. For example:
|
noexcept |
Resolve a content coding against an Accept-Encoding header per RFC 9110 §12.5.3. For example:
|
inline |
Visit each baggage member in order as a key, a value, and the property set trailing it, which is empty when the member carries none. The value is handed over still encoded, since decoding it is a separate concern with a rule of its own: "percent-encoded octet sequences that do not match the UTF-8 encoding scheme MUST be replaced with the replacement code point (U+FFFD)". The whole input is checked before anything is visited, so a caller never acts on part of a malformed value, which for baggage means never propagating a pair out of a value it then discards.
A key may repeat and the order of members is significant, so a caller collecting these wants a sequence rather than a map. Every view borrows the input, so the value they came from must outlive them. For example:
|
inline |
Visit each entry of a baggage property set in order, as a key and a value that is absent when the entry is a bare key. That distinction is why the value is optional rather than empty: the grammar admits an entry with no value at all and an entry whose value is the empty string, and they are not the same thing.
The input is the property set handed over when visiting a member, which is what follows the first semicolon and so does not include it. An empty set is a set of no entries and parses. Note that the specification writes a set with that leading semicolon still attached, where this does not take one.
The input is checked before anything is visited, and nothing is visited when it does not parse. Every view borrows the input. For example:
|
noexcept |
Extract the credential from an Authorization header that uses the Bearer scheme per RFC 6750 §2.1, matching the scheme case-insensitively per RFC 9110 §11.1 and tolerating optional whitespace around the token. Returns an empty view when the header is absent, uses another scheme, or does not carry a well-formed b64token credential. For example:
| SOURCEMETA_CORE_HTTP_EXPORT auto sourcemeta::core::http_parse_challenges | ( | const std::string_view | input, |
| std::vector< HTTPParsedChallenge > & | challenges ) -> bool |
Parse an RFC 9110 §11.6.1 WWW-Authenticate header value, given without the field name, into its challenges, returning false and leaving the container empty when the value is malformed or carries no challenge at all.
The field is a list of challenges whose parameters are themselves comma-separated, so §11.6.1 warns recipients to take special care. A token followed by an equals sign continues the challenge being read, while one that is not opens the next, and a run of token characters closed by equals padding and nothing else is a §11.2 token68 rather than a parameter without a value. Empty list elements are ignored as §5.6.1.2 requires.
This applies the RFC 9110 grammar alone. A recipient judges nothing beyond it, so a challenge that http_challenge_valid would refuse a sender, such as a bare Bearer, still parses. For example:
|
inline |
Parse the value of an RFC 6265 §4.2 Cookie request header, given without the field name, into its cookie-pairs, invoking the callback once per pair with the name and value. A request cookie header carries only names and values, never attributes. Surrounding whitespace is trimmed, values are otherwise reported verbatim, and pairs that lack a = or have an empty name are skipped. Neither argument allocates, as both are borrowed from the input, so anything the callback keeps must not outlive it. For example:
A header may carry several cookies under one name, so a callback that assigns to a single variable keeps whichever happens to come last. Use http_cookie_values to look one up by name.
|
inline |
Parse the value of an RFC 6265 §4.2 Cookie request header, given without the field name, into any container of name and value pairs. The names and values are borrowed from input rather than copied, so a container of views must not outlive it, while an owning container may. For example:
|
inline |
Parse the field lines of a raw message header block per RFC 9112 §5, skipping the start line and invoking the callback with each raw field name and its value with optional whitespace excluded. A continuation of the previous value through deprecated line folding is reported with an empty name. Malformed field lines are discarded. Neither argument allocates, as both are views into the input. For example:
|
inline |
Parse the field lines of a raw message header block, skipping the start line, into any container of name and value pairs, normalising names to lowercase given that RFC 9110 §5.1 mandates that "field names are case-insensitive", preserving repeated fields as separate entries, and joining deprecated line folding per RFC 9112 §5.2. For example:
| SOURCEMETA_CORE_HTTP_EXPORT auto sourcemeta::core::http_parse_media_type | ( | const std::string_view | media_type | ) | -> std::optional< HTTPMediaType > |
Parse a media type into its parts per RFC 9110 §8.3.1, splitting off any structured syntax suffix per RFC 6838 §4.2. Returns no value when the input is not well-formed, including when its parameters do not follow RFC 9110 §5.6.6. A media range such as text/* parses the same way. For example:
|
noexcept |
Parse a traceparent field value into its fields, or nothing when it is not well formed. The identifiers borrow the input. For example:
|
inline |
Visit each tracestate member in order as a key and a value, skipping the empty members the grammar allows. The whole value is checked before anything is visited, so a caller never acts on part of a malformed value, and nothing is visited when it does not parse. Every key and value borrows the input, so the value they came from must outlive them. For example:
|
inline |
Collect each tracestate member in order into a container of pairs. Every key and value borrows the input, so the value they came from must outlive the container. For example:
| SOURCEMETA_CORE_HTTP_EXPORT auto sourcemeta::core::http_scan_quoted_string | ( | const std::string_view | input, |
| const std::size_t | position, | ||
| std::string & | storage, | ||
| std::string_view & | value ) -> std::optional< std::size_t > |
Scan a quoted-string (RFC 9110 Section 5.6.4) whose opening double quote is at position in input, returning the position just past the closing quote, or no value when it is malformed. The unescaped content is written to value, borrowing from input when it carries no quoted-pair and appending to storage otherwise, whose capacity should be reserved up front so that earlier views into it stay valid. Control characters other than horizontal tab are rejected as a header-injection defense. For example:
| SOURCEMETA_CORE_HTTP_EXPORT auto sourcemeta::core::http_serialize_cache_control | ( | const HTTPCacheControl & | directives | ) | -> std::optional< std::string > |
Serialise an RFC 9111 §5.2 Cache-Control header value, returning no value when the directives are not http_cache_control_valid. For example:
| SOURCEMETA_CORE_HTTP_EXPORT auto sourcemeta::core::http_serialize_cache_control | ( | const HTTPCacheControl & | directives, |
| std::string & | out ) -> bool |
Append an RFC 9111 §5.2 Cache-Control header value to out, returning true on success. When the directives are not http_cache_control_valid, out is left unchanged and this returns false.
A duration is written in the token form §5.2.2.1 requires, never quoted, while a field list is written in the quoted-string form §5.2.2.4 and §5.2.2.7 ask a sender to use even for a single entry. A qualifying field list replaces the bare directive rather than joining it. For example:
| SOURCEMETA_CORE_HTTP_EXPORT auto sourcemeta::core::http_serialize_challenge | ( | const HTTPChallenge & | challenge | ) | -> std::optional< std::string > |
Serialise an RFC 9110 §11.6.1 WWW-Authenticate challenge, returning no value when the challenge is not http_challenge_valid.
| SOURCEMETA_CORE_HTTP_EXPORT auto sourcemeta::core::http_serialize_challenge | ( | const HTTPChallenge & | challenge, |
| std::string & | out ) -> bool |
Append an RFC 9110 §11.6.1 WWW-Authenticate challenge to out, returning true on success. When the challenge is not http_challenge_valid, out is left unchanged and this returns false.
Every parameter value is spelled as a §5.6.4 quoted-string, since §11.5 leaves a sender no other choice for a realm, and the encoding escapes a quote or a backslash rather than letting either close the value early. For example:
| SOURCEMETA_CORE_HTTP_EXPORT auto sourcemeta::core::http_serialize_challenges | ( | std::span< const HTTPChallenge > | challenges | ) | -> std::optional< std::string > |
Serialise a whole RFC 9110 §11.6.1 WWW-Authenticate header value, returning no value when the list is empty or carries an invalid challenge. For example:
| SOURCEMETA_CORE_HTTP_EXPORT auto sourcemeta::core::http_serialize_challenges | ( | std::span< const HTTPChallenge > | challenges, |
| std::string & | out ) -> bool |
Append a whole RFC 9110 §11.6.1 WWW-Authenticate header value to out, which is a list of challenges. Returns false without touching out when the list is empty, since §11.6.1 requires a 401 to carry at least one challenge, or when any challenge is not http_challenge_valid.
| SOURCEMETA_CORE_HTTP_EXPORT auto sourcemeta::core::http_serialize_cookie | ( | const HTTPCookie & | cookie | ) | -> std::optional< std::string > |
Serialise an RFC 6265 §4.1 Set-Cookie header value, returning no value when the cookie is not http_cookie_valid. For example:
| SOURCEMETA_CORE_HTTP_EXPORT auto sourcemeta::core::http_serialize_cookie | ( | const HTTPCookie & | cookie, |
| std::string & | out ) -> bool |
Append an RFC 6265 §4.1 Set-Cookie header value to out, returning true on success. When the cookie is not http_cookie_valid, out is left unchanged and this returns false. For example:
|
inline |
Serialise headers, given as any range of name and value pairs, into CRLF-delimited field lines per RFC 9112 §5. For example:
|
constexprnoexcept |
Resolve a numeric status code into its registered status, with unknown codes resolving to an empty reason phrase. For example:
|
constexprnoexcept |
Whether the sampled bit is set, which records that the caller may have recorded trace data rather than that it did. The remaining bits are reserved and a reader is told to mask rather than compare: "As this is a bit field, you cannot interpret flags by decoding the hex value and looking at the resulting number". For example:
|
inlinenoexcept |
The view with any leading optional whitespace removed (RFC 9110 Section 5.6.3). For example:
|
inlinenoexcept |
The view with any trailing optional whitespace removed (RFC 9110 Section 5.6.3). For example:
|
inlineconstexpr |
The RFC 6265bis §5.6 ceiling on the length of a single cookie attribute value, past which a user agent ignores that attribute while keeping the cookie, silently widening or narrowing the scope the server asked for.
|
inlineconstexpr |
The RFC 6265bis §5.7 ceiling on the sum of the lengths of a cookie name and its value, past which a user agent ignores the cookie entirely. Note that the RFC 6265 §6.1 minimum capability names the same number but measures the attributes into it as well, so a cookie sized against this one is not necessarily within that older bound.
|
inlineconstexpr |
RFC 9110 §15.3.3 (Successful).
|
inlineconstexpr |
RFC 5842 §7.1 (WebDAV).
|
inlineconstexpr |
RFC 9110 §15.6.3 (Server Error).
|
inlineconstexpr |
RFC 9110 §15.5.1 (Client Error).
|
inlineconstexpr |
RFC 9110 §15.5.10 (Client Error).
|
inlineconstexpr |
RFC 9110 §15.5.14 (Client Error). RFC 9110 renamed this from "Payload Too Large" (RFC 7231) to "Content Too Large".
|
inlineconstexpr |
RFC 9110 §15.2.1 (Informational).
|
inlineconstexpr |
RFC 9110 §15.3.2 (Successful).
|
inlineconstexpr |
RFC 8297 §2.
|
inlineconstexpr |
RFC 9110 §15.5.18 (Client Error).
|
inlineconstexpr |
RFC 4918 §11.4 (WebDAV).
|
inlineconstexpr |
RFC 9110 §15.5.4 (Client Error).
|
inlineconstexpr |
RFC 9110 §15.4.3 (Redirection).
|
inlineconstexpr |
RFC 9110 §15.6.5 (Server Error).
|
inlineconstexpr |
RFC 9110 §15.5.11 (Client Error).
|
inlineconstexpr |
RFC 9110 §15.6.6 (Server Error).
|
inlineconstexpr |
RFC 2324 §2.3.2 (HTCPCP).
|
inlineconstexpr |
RFC 3229 §10.4.1 (HTTP Delta Encoding).
|
inlineconstexpr |
RFC 4918 §11.5 (WebDAV).
|
inlineconstexpr |
RFC 9110 §15.6.1 (Server Error).
|
inlineconstexpr |
RFC 9110 §15.5.12 (Client Error).
|
inlineconstexpr |
RFC 4918 §11.3 (WebDAV).
|
inlineconstexpr |
RFC 5842 §7.2 (WebDAV).
|
inlineconstexpr |
RFC 9110 §15.5.6 (Client Error).
|
inlineconstexpr |
RFC 9110 §15.5.20 (Client Error).
|
inlineconstexpr |
RFC 9110 §15.4.2 (Redirection).
|
inlineconstexpr |
RFC 4918 §11.1 (WebDAV).
|
inlineconstexpr |
RFC 9110 §15.4.1 (Redirection).
|
inlineconstexpr |
RFC 6585 §6.
|
inlineconstexpr |
RFC 9110 §15.3.5 (Successful).
|
inlineconstexpr |
RFC 9110 §15.3.4 (Successful).
|
inlineconstexpr |
RFC 9110 §15.5.7 (Client Error).
|
inlineconstexpr |
RFC 2774 §7.
|
inlineconstexpr |
RFC 9110 §15.5.5 (Client Error).
|
inlineconstexpr |
RFC 9110 §15.6.2 (Server Error).
|
inlineconstexpr |
RFC 9110 §15.4.5 (Redirection).
|
inlineconstexpr |
RFC 9110 §15.3.1 (Successful).
|
inlineconstexpr |
RFC 9110 §15.3.7 (Successful).
|
inlineconstexpr |
RFC 9110 §15.5.3 (Client Error).
|
inlineconstexpr |
RFC 9110 §15.4.9 (Redirection).
|
inlineconstexpr |
RFC 9110 §15.5.13 (Client Error).
|
inlineconstexpr |
RFC 6585 §3.
|
inlineconstexpr |
RFC 2518 §10.1 (WebDAV).
|
inlineconstexpr |
RFC 9110 §15.5.8 (Client Error).
|
inlineconstexpr |
RFC 9110 §15.5.17 (Client Error).
|
inlineconstexpr |
RFC 6585 §5.
|
inlineconstexpr |
RFC 9110 §15.5.9 (Client Error).
|
inlineconstexpr |
RFC 9110 §15.3.6 (Successful).
|
inlineconstexpr |
RFC 9110 §15.4.4 (Redirection).
|
inlineconstexpr |
RFC 9110 §15.6.4 (Server Error).
|
inlineconstexpr |
RFC 9110 §15.2.2 (Informational).
|
inlineconstexpr |
RFC 9110 §15.4.8 (Redirection).
|
inlineconstexpr |
RFC 8470 §5.2.
|
inlineconstexpr |
RFC 6585 §4.
|
inlineconstexpr |
RFC 9110 §15.5.2 (Client Error).
|
inlineconstexpr |
RFC 7725 §3.
|
inlineconstexpr |
RFC 9110 §15.5.21 (Client Error).
|
inlineconstexpr |
RFC 9110 §15.5.16 (Client Error).
|
inlineconstexpr |
RFC 9110 §15.5.22 (Client Error).
|
inlineconstexpr |
RFC 9110 §15.5.15 (Client Error).
|
inlineconstexpr |
RFC 9110 §15.4.6 (Redirection).
|
inlineconstexpr |
RFC 2295 §8.1 (Transparent Content Negotiation).