HTTP Client

Session and Requests

HttpClientSession is an active, event-loop-owned HTTP/1.1 and HTTPS client created by Network::createHttpClientSession(). It captures limits, TLS policy, default fields, and fallback callbacks when a prepared HttpClientRequest is submitted. Convenience operations create, submit, and return retained GET, HEAD, or fixed-body POST requests.

The session bounds concurrent and pending operations and retained fixed request bodies. close() stops admission and drains submitted requests before emitting onClosed and onFinal. abort() cancels queued and active requests and emits onFinal.

Redirects

HttpClientRedirectOptions defaults to following at most ten redirects on any host while rejecting HTTPS-to-HTTP downgrades. The session policy is captured when a request is submitted; a prepared request can override it. onRedirect receives the response head, source URL, optional resolved target, followed count, and a machine-readable hard constraint. A request callback overrides the captured session fallback and returns Follow, ReturnResponse, or Reject.

The client follows 301, 302, 303, 307, and 308 responses. POST changes to GET for 301 and 302; 303 changes every method except HEAD to GET; and 307 and 308 preserve the method and body. Empty and fixed bodies are replayable. A streamed body can only follow when the status rewrite discards it. Loop, limit, malformed-target, downgrade, host-policy, and body-replay guards cannot be bypassed by a callback. ReturnResponse exposes the retained 3xx response through the ordinary response policy, while a blocked follow or explicit rejection reports HttpRedirectFailure.

Relative targets resolve against the current hop and inherit a source fragment when Location has none. Cross-origin hops permanently discard authorization, proxy authorization, caller cookies, origin, and referrer fields. Host, framing, and automatic cookies are regenerated for every hop. HttpClientRequest::url() remains the submitted URL; the final response exposes effectiveUrl() and redirectCount().

Cookie Handling

Every session owns one stable HttpCookieJar. Automatic cookie handling is enabled by default: valid Set-Cookie fields are stored before redirect policy runs, and matching cookies generate the request Cookie field. A caller Cookie field therefore fails submission while automation is enabled. Disable automation explicitly when an application must own that field.

The jar supports exact inspection, insertion, replacement, removal, and clearing. It implements bounded domain and path matching, default paths, host-only and Secure cookies, HttpOnly inspection, Max-Age precedence, expiry, __Secure- and __Host- prefix rules, and deterministic sending and LRU eviction. SameSite is retained for inspection but browser navigation semantics are not enforced. Defaults are 4 KiB per cookie, 180 cookies per registrable domain, and 3,000 globally. Registrable-domain policy uses the bundled complete ICANN and private Public Suffix List; IP-address cookies remain exact-host-only.

Connection Reuse

Sequential HTTP/1.1 reuse is enabled by default. The session retains at most one idle connection per origin, eight idle connections globally, for 30 seconds and at most 1,000 transactions per physical connection. Concurrent logical requests remain independent and may create additional same-origin connections; only one completed idle connection is kept.

Origin and captured transport/TLS configuration generations isolate reusable connections. Unsolicited input, closure, errors, retained bytes, expiry, or a transaction cap evicts a connection. A stale reused connection is retried at most once only for GET, HEAD, OPTIONS, or TRACE with an empty or fixed body and before any informational or final response was observed. Session close() drains leased requests without accepting their returned connections; abort() terminates both active work and idle connections.

Response Handling

onResponse, onTextResponse, and onJsonResponse select one bounded automatic aggregate. Text is decoded as strict UTF-8 and JSON is parsed before its callback runs. HttpClientResponseOptions controls the aggregate limit and optional media-type patterns.

onResponseHead is the low-level alternative. Its retained HttpClientResponse must select streamed delivery, bounded byte, text, or JSON aggregation, body rejection, or pumping into a ByteOutputStream. Streaming supports pause and resume, while output-stream pumping pauses input around each bounded worker write. The Path overload creates a collision-safe temporary file in the destination directory on a bounded worker, reports committed progress, flushes and closes it, and atomically replaces a regular-file destination only after the complete response succeeds. Cancellation, deadlines, write failures, and commit failures remove the temporary file and preserve an existing destination.

HTTPS Policy

HttpClientTlsOptions selects the http/client configuration label by default. HTTPS requests resolve the corresponding immutable TLS configuration, validate the server through its explicit trust anchors, and offer only http/1.1 through ALPN.

See Using HTTP Clients for request preparation, response policies, streaming, errors, and lifecycle examples.

Interface

class HttpClientBodyProgress

Successfully committed response-body progress for an output sink.

Public Functions

inline HttpClientBodyProgress(unit::ByteLength committedLength, std::optional<unit::ByteLength> expectedLength) noexcept

Create one progress value.

inline constexpr unit::ByteLength committedLength() const noexcept

Get the number of bytes successfully written to the sink.

inline constexpr std::optional<unit::ByteLength> expectedLength() const noexcept

Get the expected decoded body length when known from Content-Length.

enum class erbsland::network::HttpClientRedirectAction : std::uint8_t

The action selected for an HTTP client redirect response.

Values:

enumerator Follow

Follow the redirect when every hard guard permits it.

enumerator ReturnResponse

Deliver the redirect response through the ordinary response policy.

enumerator Reject

Fail the logical request with a redirect-policy error.

enum class erbsland::network::HttpClientRedirectConstraint : std::uint8_t

A machine-readable hard guard that prevents following a redirect.

Values:

enumerator None

The redirect is eligible to be followed.

enumerator InvalidTarget

Location is absent, malformed, or not HTTP(S).

enumerator RedirectLimit

The captured redirect limit would be exceeded.

enumerator Loop

The canonical fragment-free target was already requested.

enumerator HttpsDowngrade

HTTPS-to-HTTP downgrade is disabled.

enumerator HostPolicy

The target violates the captured host policy.

enumerator BodyNotReplayable

The redirect must preserve a streamed request body.

class HttpClientRedirectContext

Context presented at a redirect-policy checkpoint.

Public Functions

inline HttpClientRedirectContext(HttpResponseHead responseHead, Url sourceUrl, std::optional<Url> targetUrl, unit::ItemCount followedCount, HttpClientRedirectConstraint constraint) noexcept

Create one redirect context.

inline const HttpResponseHead &responseHead() const noexcept

Get the retained redirect response head.

inline const Url &sourceUrl() const noexcept

Get the URL used for the completed hop.

inline const std::optional<Url> &targetUrl() const noexcept

Get the resolved target URL, if Location was valid.

inline constexpr unit::ItemCount followedCount() const noexcept

Get the number of redirects already followed.

inline constexpr bool canFollow() const noexcept

Test whether all non-overridable follow guards permit this hop.

inline constexpr HttpClientRedirectConstraint constraint() const noexcept

Get the first hard constraint preventing a follow action.

inline const HttpClientRequestPtr &requestOverride() const noexcept

Get the optional prepared request override supplied by the callback.

inline void setRequestOverride(HttpClientRequestPtr request) noexcept

Use a prepared request from the same session for the next eligible hop.

enum class erbsland::network::HttpClientRedirectHostPolicy : std::uint8_t

The host boundary applied to every redirect relative to the original request URL.

Values:

enumerator Any

Permit any HTTP or HTTPS host.

enumerator SameHost

Require the exact canonical original host.

enumerator SameRegistrableDomain

Require the same registrable domain under the bundled Public Suffix List.

class HttpClientRedirectOptions

Redirect policy captured when an HTTP client request is submitted.

Public Functions

inline constexpr HttpClientRedirectAction action() const noexcept

Get the action used when no redirect callback is installed.

inline constexpr HttpClientRedirectOptions &setAction(const HttpClientRedirectAction value) noexcept

Set the action used when no redirect callback is installed.

inline constexpr unit::ItemCount maximumRedirects() const noexcept

Get the maximum number of followed redirects.

inline constexpr HttpClientRedirectOptions &setMaximumRedirects(const unit::ItemCount value) noexcept

Set the finite maximum number of followed redirects.

inline constexpr HttpClientRedirectHostPolicy hostPolicy() const noexcept

Get the redirect host policy.

inline constexpr HttpClientRedirectOptions &setHostPolicy(const HttpClientRedirectHostPolicy value) noexcept

Set the redirect host policy.

inline constexpr bool allowsHttpsDowngrade() const noexcept

Test whether HTTPS-to-HTTP redirects may be followed.

inline constexpr HttpClientRedirectOptions &setAllowHttpsDowngrade(const bool value) noexcept

Permit or reject HTTPS-to-HTTP redirects.

Public Static Attributes

static constexpr auto cDefaultMaximumRedirects = unit::ItemCount{10U}

Default followed-hop limit.

class HttpClientRequest : public erbsland::event::EventSource

One prepared or submitted HTTP client request.

See: HTTP Client

Subclassed by erbsland::network::impl::HttpClientRequest

Public Functions

virtual const HttpMethod &method() const noexcept = 0

Get the request method.

virtual const Url &url() const noexcept = 0

Get the absolute request URL.

virtual const HttpHeaders &headers() const noexcept = 0

Get the request-specific fields.

virtual void setHeaders(HttpHeaders headers) = 0

Replace request-specific fields while prepared.

virtual void setBody(mem::ByteBlock body) = 0

Select a fixed request body while prepared.

virtual void streamBody() = 0

Select streamed request-body framing while prepared.

virtual void setRedirectOptions(HttpClientRedirectOptions options) = 0

Override the captured session redirect policy while prepared.

virtual NetworkSendStatus sendBody(const mem::ByteBlock &data) = 0

Atomically submit one streamed request-body block.

virtual NetworkSendStatus finishBody(HttpHeaders trailers = {}) = 0

Finish a streamed request body with optional trailers.

virtual NetworkSourceState state() const noexcept = 0

Get the request lifecycle state.

virtual void cancel() noexcept = 0

Cancel this request without affecting sibling requests.

virtual HttpClientRequestEventEditor &events() override = 0

Access the stable request callback and response-policy editor.

class HttpClientRequestEventEditor : public erbsland::event::impl::CommonEventEditor

Callback and response-policy editor for one HTTP client request.

Subclassed by erbsland::network::impl::HttpClientRequestEventEditor

Public Functions

virtual HttpClientRequestEventEditor &onResponse(HttpClientResponseFn callback, HttpClientResponseOptions options = {}) = 0

Select and replace bounded byte-response handling for this request.

virtual HttpClientRequestEventEditor &onTextResponse(HttpClientTextResponseFn callback, HttpClientResponseOptions options = {}) = 0

Select and replace bounded strict UTF-8 response handling for this request.

virtual HttpClientRequestEventEditor &onJsonResponse(HttpClientJsonResponseFn callback, HttpClientResponseOptions options = {}) = 0

Select and replace bounded JSON response handling for this request.

virtual HttpClientRequestEventEditor &onResponseHead(HttpClientResponseHeadFn callback) = 0

Select and replace low-level final-response-head handling for this request.

virtual HttpClientRequestEventEditor &onInformationalResponse(HttpClientInformationalResponseFn callback) = 0

Replace the informational-response handler.

virtual HttpClientRequestEventEditor &onRedirect(HttpClientRedirectFn callback) = 0

Replace the redirect-policy handler.

virtual HttpClientRequestEventEditor &onWritable(NetworkEventFn callback) = 0

Replace the initial and renewed upload-writable handler.

virtual HttpClientRequestEventEditor &onError(HttpClientErrorFn callback) = 0

Replace the operational-error handler.

virtual HttpClientRequestEventEditor &onFinal(NetworkEventFn callback) = 0

Replace the exactly-once request final handler.

using erbsland::network::HttpClientResponseFn = std::function<void(HttpClientRequestPtr, HttpClientResponsePtr, mem::ByteBlock)>

A completed bounded byte-response handler.

using erbsland::network::HttpClientTextResponseFn = std::function<void(HttpClientRequestPtr, HttpClientResponsePtr, text::String)>

A completed bounded strict UTF-8 response handler.

using erbsland::network::HttpClientJsonResponseFn = std::function<void(HttpClientRequestPtr, HttpClientResponsePtr, text::json::JsonValue)>

A completed bounded JSON response handler.

using erbsland::network::HttpClientResponseHeadFn = std::function<void(HttpClientRequestPtr, HttpClientResponsePtr)>

A low-level final-response-head handler.

using erbsland::network::HttpClientInformationalResponseFn = std::function<void(HttpClientRequestPtr, const HttpResponseHead&)>

An informational response handler.

using erbsland::network::HttpClientRedirectFn = std::function<HttpClientRedirectAction(HttpClientRequestPtr, HttpClientRedirectContext&)>

A redirect-policy checkpoint handler.

using erbsland::network::HttpClientBodyProgressFn = std::function<void(const HttpClientBodyProgress&)>

A successfully committed output-sink progress handler.

using erbsland::network::HttpClientErrorFn = std::function<void(HttpClientRequestPtr, const NetworkErrorContext&)>

A request-associated operational-error handler.

class HttpClientResponse : public erbsland::event::EventSource

One retained final HTTP client response and its incoming body policy.

See: HTTP Client

Subclassed by erbsland::network::impl::HttpClientResponse

Public Functions

virtual const HttpResponseHead &head() const noexcept = 0

Get the immutable final response head.

virtual const HttpHeaders &trailers() const noexcept = 0

Get completed trailer fields, or an empty collection before completion.

virtual const Url &effectiveUrl() const noexcept = 0

Get the final effective URL after all followed redirects.

virtual unit::ItemCount redirectCount() const noexcept = 0

Get the number of redirects followed before this response.

virtual void streamBody() = 0

Select incremental body delivery through onBodyData.

virtual void aggregateBody(unit::ByteLength maximumLength) = 0

Select bounded byte aggregation through onBody.

virtual void aggregateText(unit::ByteLength maximumLength) = 0

Select bounded strict UTF-8 aggregation through onText.

virtual void aggregateJson(unit::ByteLength maximumLength) = 0

Select bounded JSON aggregation through onJson.

virtual void writeBodyTo(stream::ByteOutputStreamPtr output) = 0

Pump body blocks into a byte output stream away from the event loop.

virtual void writeBodyTo(path::Path destination) = 0

Atomically replace a destination path only after the complete response succeeds.

virtual void rejectBody() = 0

Reject the unread body and make the connection non-reusable.

virtual void pauseBody() = 0

Pause an active streamed body.

virtual void resumeBody() = 0

Resume an explicitly paused streamed body.

virtual bool isFinal() const noexcept = 0

Test whether this response can no longer emit body events.

virtual HttpClientResponseEventEditor &events() override = 0

Access the stable body callback editor.

class HttpClientResponseEventEditor : public erbsland::event::impl::CommonEventEditor

Callback editor for a low-level HTTP client response body.

Subclassed by erbsland::network::impl::HttpClientResponseEventEditor

Public Functions

virtual HttpClientResponseEventEditor &onBodyData(NetworkDataFn callback) = 0

Replace the streamed-body block handler.

virtual HttpClientResponseEventEditor &onBody(NetworkDataFn callback) = 0

Replace the manually aggregated byte-body handler.

virtual HttpClientResponseEventEditor &onText(std::function<void(text::String)> callback) = 0

Replace the manually aggregated strict UTF-8 body handler.

virtual HttpClientResponseEventEditor &onJson(std::function<void(text::json::JsonValue)> callback) = 0

Replace the manually aggregated JSON body handler.

virtual HttpClientResponseEventEditor &onTrailers(std::function<void(const HttpHeaders&)> callback) = 0

Replace the trailer handler.

virtual HttpClientResponseEventEditor &onBodyProgress(HttpClientBodyProgressFn callback) = 0

Replace the output-sink progress handler.

virtual HttpClientResponseEventEditor &onBodyCompleted(NetworkEventFn callback) = 0

Replace the response-body completion handler.

virtual HttpClientResponseEventEditor &onFinal(NetworkEventFn callback) = 0

Replace the exactly-once response final handler.

class HttpClientResponseOptions

Automatic HTTP client response aggregation and media policy.

Public Functions

inline unit::ByteLength maximumBodyLength() const noexcept

Get the automatic response-body aggregation limit.

inline HttpClientResponseOptions &setMaximumBodyLength(unit::ByteLength value) noexcept

Set the positive finite automatic response-body aggregation limit.

inline const std::optional<std::vector<text::String>> &acceptedContentTypes() const noexcept

Get explicitly configured accepted media-type patterns.

No value selects the handler-family defaults; an empty list disables filtering.

inline HttpClientResponseOptions &setAcceptedContentTypes(std::vector<text::String> value) noexcept

Replace accepted media-type patterns; an empty list disables filtering.

Public Static Attributes

static constexpr auto cDefaultMaximumBodyLength = unit::ByteLength{1024U * 1024U}

Default automatic response-body aggregation limit.

class HttpClientSession : public erbsland::event::EventSource

A session-first HTTP/1.1 and HTTPS client.

See: HTTP Client

Subclassed by erbsland::network::impl::HttpClientSession

Public Functions

virtual void setOptions(HttpClientSessionOptions options) = 0

Replace limits and deadlines used by subsequently submitted requests.

virtual void setTlsOptions(HttpClientTlsOptions options) = 0

Replace curated HTTPS options used by subsequently submitted requests.

virtual void setRedirectOptions(HttpClientRedirectOptions options) = 0

Replace the redirect policy captured by subsequently submitted requests.

virtual void setDefaultHeaders(HttpHeaders headers) = 0

Replace default fields used by subsequently submitted requests.

virtual HttpCookieJar &cookieJar() noexcept = 0

Access the stable session-owned cookie jar.

virtual HttpClientRequestPtr createRequest(Url url) = 0

Create one prepared GET request.

virtual HttpClientRequestPtr createRequest(HttpMethod method, Url url) = 0

Create one prepared request.

virtual void sendRequest(HttpClientRequestPtr request) = 0

Submit a prepared request created by this session.

virtual HttpClientRequestPtr sendGet(Url url) = 0

Create and submit a GET request.

virtual HttpClientRequestPtr sendHead(Url url) = 0

Create and submit a HEAD request.

virtual HttpClientRequestPtr sendPost(Url url, mem::ByteBlock body, HttpHeaders headers = {}) = 0

Create and submit a fixed-body POST request.

virtual NetworkSourceState state() const noexcept = 0

Get the session lifecycle state.

virtual void close() = 0

Stop admission and drain every submitted request.

virtual void abort() noexcept = 0

Cancel every queued or active request immediately.

virtual HttpClientSessionEventEditor &events() override = 0

Access the stable callback and default response-policy editor.

class HttpClientSessionEventEditor : public erbsland::event::impl::CommonEventEditor

Callback and default response-policy editor for an HTTP client session.

Subclassed by erbsland::network::impl::HttpClientSessionEventEditor

Public Functions

virtual HttpClientSessionEventEditor &onResponse(HttpClientResponseFn callback, HttpClientResponseOptions options = {}) = 0

Replace the default bounded byte-response handler.

virtual HttpClientSessionEventEditor &onTextResponse(HttpClientTextResponseFn callback, HttpClientResponseOptions options = {}) = 0

Replace the default bounded strict UTF-8 response handler.

virtual HttpClientSessionEventEditor &onJsonResponse(HttpClientJsonResponseFn callback, HttpClientResponseOptions options = {}) = 0

Replace the default bounded JSON response handler.

virtual HttpClientSessionEventEditor &onResponseHead(HttpClientResponseHeadFn callback) = 0

Replace the default low-level final-response-head handler.

virtual HttpClientSessionEventEditor &onInformationalResponse(HttpClientInformationalResponseFn callback) = 0

Replace the informational-response handler.

virtual HttpClientSessionEventEditor &onRedirect(HttpClientRedirectFn callback) = 0

Replace the redirect-policy fallback handler.

virtual HttpClientSessionEventEditor &onError(HttpClientErrorFn callback) = 0

Replace the request-error fallback handler.

virtual HttpClientSessionEventEditor &onClosed(NetworkEventFn callback) = 0

Replace the graceful session-closure handler.

virtual HttpClientSessionEventEditor &onFinal(NetworkEventFn callback) = 0

Replace the exactly-once session final handler.

class HttpClientSessionOptions

Limits and deadlines captured for submitted HTTP client requests.

Public Functions

inline unit::ItemCount maximumConcurrentRequests() const noexcept

Get the maximum concurrent request count.

inline HttpClientSessionOptions &setMaximumConcurrentRequests(unit::ItemCount value) noexcept

Set the maximum concurrent request count.

inline unit::ItemCount maximumPendingRequests() const noexcept

Get the maximum pending request count.

inline HttpClientSessionOptions &setMaximumPendingRequests(unit::ItemCount value) noexcept

Set the maximum pending request count.

inline unit::ByteLength maximumRetainedRequestBodyLength() const noexcept

Get the aggregate retained fixed-body quota.

inline HttpClientSessionOptions &setMaximumRetainedRequestBodyLength(unit::ByteLength value) noexcept

Set the aggregate retained fixed-body quota.

inline unit::ByteLength maximumBodyLength() const noexcept

Get the decoded response hard maximum.

inline HttpClientSessionOptions &setMaximumBodyLength(unit::ByteLength value) noexcept

Set the decoded response hard maximum.

inline unit::ByteLength maximumQueueLength() const noexcept

Get the transaction queue maximum.

inline HttpClientSessionOptions &setMaximumQueueLength(unit::ByteLength value) noexcept

Set the transaction queue maximum.

inline unit::ByteLength maximumStartLineLength() const noexcept

Get the response status-line maximum.

inline HttpClientSessionOptions &setMaximumStartLineLength(unit::ByteLength value) noexcept

Set the response status-line maximum.

inline HttpHeaderLimits headerLimits() const noexcept

Get the request/response header limits.

inline HttpClientSessionOptions &setHeaderLimits(HttpHeaderLimits value) noexcept

Set the request/response header limits.

inline SocketBufferLimits socketBufferLimits() const noexcept

Get connected socket buffer limits.

inline HttpClientSessionOptions &setSocketBufferLimits(SocketBufferLimits value) noexcept

Set connected socket buffer limits.

inline bool automaticCookiesEnabled() const noexcept

Test whether automatic cookie storage and generation are enabled.

inline HttpClientSessionOptions &setAutomaticCookiesEnabled(const bool value) noexcept

Enable or disable automatic cookie storage and generation.

inline HttpCookieJarOptions cookieJarOptions() const noexcept

Get cookie-jar limits captured for subsequently submitted requests.

inline HttpClientSessionOptions &setCookieJarOptions(HttpCookieJarOptions value) noexcept

Set cookie-jar limits.

inline bool connectionReuseEnabled() const noexcept

Test whether completed HTTP/1.1 connections may be reused sequentially.

inline HttpClientSessionOptions &setConnectionReuseEnabled(const bool value) noexcept

Enable or disable sequential connection reuse.

inline unit::ItemCount maximumIdleConnections() const noexcept

Get the global idle-connection cap. At most one idle connection is retained per origin.

inline HttpClientSessionOptions &setMaximumIdleConnections(const unit::ItemCount value) noexcept

Set the global idle-connection cap.

inline time::TimeDelta idleConnectionTimeout() const noexcept

Get the idle connection deadline.

inline HttpClientSessionOptions &setIdleConnectionTimeout(const time::TimeDelta value) noexcept

Set the idle connection deadline.

inline unit::ItemCount maximumTransactionsPerConnection() const noexcept

Get the transaction cap for one physical connection.

inline HttpClientSessionOptions &setMaximumTransactionsPerConnection(const unit::ItemCount value) noexcept

Set the transaction cap for one physical connection.

inline time::TimeDelta dnsTimeout() const noexcept

Get the DNS deadline.

inline HttpClientSessionOptions &setDnsTimeout(time::TimeDelta value) noexcept

Set the DNS deadline.

inline time::TimeDelta connectTimeout() const noexcept

Get the TCP connection deadline after resolution.

inline HttpClientSessionOptions &setConnectTimeout(time::TimeDelta value) noexcept

Set the TCP connection deadline after resolution.

inline time::TimeDelta headerTimeout() const noexcept

Get the response-head deadline.

inline HttpClientSessionOptions &setHeaderTimeout(time::TimeDelta value) noexcept

Set the response-head deadline.

inline time::TimeDelta bodyIdleTimeout() const noexcept

Get the response-body idle deadline.

inline HttpClientSessionOptions &setBodyIdleTimeout(time::TimeDelta value) noexcept

Set the response-body idle deadline.

inline time::TimeDelta overallTimeout() const noexcept

Get the overall request deadline starting at submission.

inline HttpClientSessionOptions &setOverallTimeout(time::TimeDelta value) noexcept

Set the overall request deadline starting at submission.

inline time::TimeDelta closeTimeout() const noexcept

Get the graceful connection-close deadline.

inline HttpClientSessionOptions &setCloseTimeout(time::TimeDelta value) noexcept

Set the graceful connection-close deadline.

Public Static Attributes

static constexpr auto cDefaultMaximumConcurrentRequests = unit::ItemCount{8U}

Active requests.

static constexpr auto cDefaultMaximumPendingRequests = unit::ItemCount{256U}

Queued requests.

static constexpr auto cDefaultMaximumRetainedRequestBodyLength = unit::ByteLength{64U * 1024U * 1024U}

Session fixed-body quota.

static constexpr auto cDefaultMaximumBodyLength = unit::ByteLength{16U * 1024U * 1024U}

Decoded response bound.

static constexpr auto cDefaultMaximumQueueLength = unit::ByteLength{1024U * 1024U}

Per-transaction queue bound.

static constexpr auto cDefaultMaximumStartLineLength = unit::ByteLength{8U * 1024U}

Status-line bound.

static constexpr auto cDefaultMaximumIdleConnections = unit::ItemCount{8U}

Global idle cap.

static constexpr auto cDefaultMaximumTransactionsPerConnection = unit::ItemCount{1000U}

Reuse cap.

static const auto cDefaultDnsTimeout = time::TimeDelta::seconds(10)

DNS deadline.

static const auto cDefaultConnectTimeout = time::TimeDelta::seconds(30)

TCP deadline.

static const auto cDefaultHeaderTimeout = time::TimeDelta::seconds(30)

Response-head deadline.

static const auto cDefaultBodyIdleTimeout = time::TimeDelta::minutes(5)

Body idle deadline.

static const auto cDefaultOverallTimeout = time::TimeDelta::minutes(30)

Overall deadline.

static const auto cDefaultCloseTimeout = time::TimeDelta::seconds(10)

Close deadline.

static const auto cDefaultIdleConnectionTimeout = time::TimeDelta::seconds(30)

Idle reuse deadline.

class HttpClientTlsOptions

Curated TLS policy for HTTPS client requests.

Public Functions

inline const text::String &configurationLabel() const noexcept

Get the TLS configuration label.

inline HttpClientTlsOptions &setConfigurationLabel(text::String value) noexcept

Set the TLS configuration label.

inline SocketBufferLimits bufferLimits() const noexcept

Get the TLS protocol buffer limits.

inline HttpClientTlsOptions &setBufferLimits(SocketBufferLimits value) noexcept

Set the TLS protocol buffer limits.

inline time::TimeDelta handshakeTimeout() const noexcept

Get the TLS handshake deadline.

inline HttpClientTlsOptions &setHandshakeTimeout(time::TimeDelta value) noexcept

Set the TLS handshake deadline.

inline time::TimeDelta idleTimeout() const noexcept

Get the authenticated transport idle deadline.

inline HttpClientTlsOptions &setIdleTimeout(time::TimeDelta value) noexcept

Set the authenticated transport idle deadline.

Public Static Attributes

static const auto cDefaultConfigurationLabel = text::String{"http/client"}

Default client TLS configuration label.

static const auto cDefaultHandshakeTimeout = time::TimeDelta::seconds(30)

Default TLS handshake deadline.

static const auto cDefaultIdleTimeout = time::TimeDelta::minutes(5)

Default authenticated transport idle deadline.

class HttpCookie

An immutable snapshot of one stored HTTP client cookie.

Public Functions

inline HttpCookie(text::String name, text::String value, text::String domain, text::String path, std::optional<time::DateTime> expires, std::optional<HttpCookieSameSite> sameSite, bool hostOnly, bool secure, bool httpOnly) noexcept

Create one cookie snapshot.

inline const text::String &name() const noexcept

Get the cookie name.

inline const text::String &value() const noexcept

Get the cookie value.

inline const text::String &domain() const noexcept

Get the canonical IDNA ASCII domain.

inline const text::String &path() const noexcept

Get the cookie path.

inline const std::optional<time::DateTime> &expires() const noexcept

Get the absolute expiry, if persistent.

inline std::optional<HttpCookieSameSite> sameSite() const noexcept

Get the retained SameSite attribute.

inline constexpr bool isHostOnly() const noexcept

Test whether this is a host-only cookie.

inline constexpr bool isSecure() const noexcept

Test whether the Secure attribute is enabled.

inline constexpr bool isHttpOnly() const noexcept

Test whether the HttpOnly attribute is enabled.

class HttpCookieInsertionOptions

Attributes for synchronously inserting one cookie into a client jar.

Public Functions

inline const std::optional<text::String> &domain() const noexcept

Get the optional Domain attribute.

inline HttpCookieInsertionOptions &setDomain(text::String value) noexcept

Set the Domain attribute.

inline const std::optional<text::String> &path() const noexcept

Get the optional Path attribute.

inline HttpCookieInsertionOptions &setPath(text::String value) noexcept

Set the Path attribute.

inline const std::optional<time::DateTime> &expires() const noexcept

Get the optional absolute expiry.

inline HttpCookieInsertionOptions &setExpires(time::DateTime value) noexcept

Set the absolute expiry.

inline std::optional<HttpCookieSameSite> sameSite() const noexcept

Get the optional retained SameSite attribute.

inline HttpCookieInsertionOptions &setSameSite(const HttpCookieSameSite value) noexcept

Set the retained SameSite attribute.

inline constexpr bool isSecure() const noexcept

Test whether the Secure attribute is enabled.

inline constexpr HttpCookieInsertionOptions &setSecure(const bool value) noexcept

Enable or disable the Secure attribute.

inline constexpr bool isHttpOnly() const noexcept

Test whether the HttpOnly attribute is enabled.

inline constexpr HttpCookieInsertionOptions &setHttpOnly(const bool value) noexcept

Enable or disable the HttpOnly attribute.

class HttpCookieJar

A stable session-owned HTTP cookie jar.

See: HTTP Client

Subclassed by erbsland::network::impl::HttpCookieJar

Public Functions

virtual HttpCookieJarOptions options() const noexcept = 0

Get the current finite storage limits.

virtual void setOptions(HttpCookieJarOptions options) = 0

Replace finite limits and immediately evict excess least-recently-used entries.

virtual std::vector<HttpCookie> cookies() = 0

Return immutable snapshots in deterministic creation order.

virtual void setCookie(const Url &url, text::String name, text::String value, HttpCookieInsertionOptions options = {}) = 0

Insert or replace one cookie as if it was received for the given URL.

Throws:

err::ParameterError – If the cookie or its attributes are invalid.

virtual bool removeCookie(const text::String &name, const text::String &domain, const text::String &path) = 0

Remove the exact name/domain/path tuple and report whether it existed.

virtual void clear() noexcept = 0

Remove all cookies.

class HttpCookieJarOptions

Finite storage limits for an HTTP client cookie jar.

Public Functions

inline constexpr unit::ByteLength maximumCookieLength() const noexcept

Get the maximum serialized length of one cookie.

inline constexpr HttpCookieJarOptions &setMaximumCookieLength(const unit::ByteLength value) noexcept

Set the maximum serialized length of one cookie.

inline constexpr unit::ItemCount maximumCookiesPerRegistrableDomain() const noexcept

Get the maximum number of cookies retained per registrable domain.

inline constexpr HttpCookieJarOptions &setMaximumCookiesPerRegistrableDomain(const unit::ItemCount value) noexcept

Set the maximum number of cookies retained per registrable domain.

inline constexpr unit::ItemCount maximumCookies() const noexcept

Get the global maximum number of cookies.

inline constexpr HttpCookieJarOptions &setMaximumCookies(const unit::ItemCount value) noexcept

Set the global maximum number of cookies.