HTTP Server

Server Lifecycle

HttpServer is an event-loop-owned HTTP/1.1 server created by Network::createHttpServer(). Configure transport, HTTP, TLS, and session options while it is inactive, register routes through its event editor, and then bind it to an IpEndpoint. Without enableTls() it accepts plaintext HTTP. Calling enableTls() selects the http/server identity through the normal configuration fallback chain and forces the single ALPN protocol http/1.1. HttpServerTlsOptions exposes only the identity label, exact SNI mappings, handshake capacity, and handshake deadline; transport, cipher, buffer, and closure details remain safe server-owned defaults.

The effective endpoint becomes available after onListening. close() stops accepting, disables keep-alive reuse, drains committed responses, and then reports onClosed and onFinal. abort() terminates listener and connections immediately.

Routing and Requests

Routes are additive across onRequest, onTextRequest, onJsonRequest, and onRequestHead and are searched in registration order. Session routes are searched before server routes. Patterns match the decoded NFC path while ignoring the exact query. {name} captures one complete nonempty segment and a final {*name} captures the remaining segments. An explicit HEAD route wins; otherwise a matching GET route handles HEAD while response body bytes are suppressed.

HttpServerRequest retains the immutable request head, decoded path, exact query, route parameters, endpoints, concrete connection, and selected logical session. Ordinary byte, text, and JSON routes aggregate automatically under a one-MiB default and optional route-specific Content-Type policy. Text routes require strict UTF-8 and JSON routes parse one complete value before invoking application code. onRequestHead is the low-level family for selecting streaming, bounded aggregation, or rejection manually. Fixed response helpers, response start, and response finish are queued by the framework; only streamed sendBody reports atomic back-pressure. A request retained beyond its transaction remains safe: void response operations do nothing and sendBody reports closed.

Static Content

HttpStaticContentHandler is the extensible source interface. Its hasPath() probe and getContent() factory receive validated, decoded-NFC relative Path values and run on bounded workers, potentially concurrently. A positive probe is authoritative: failures while creating or opening that content do not fall through to another overlay. The returned HttpStaticContent reports its exact length and retained-memory cost before its one-shot open() creates a byte input stream.

HttpStaticFileHandler exposes one filesystem tree, while HttpStaticResourceHandler exposes exact paths below one compiled-resource identifier. Their public classes are abstract interfaces and their factories create built-in final implementations. Handlers are added with HttpServer::addStaticContentHandler() while the server is inactive. At start(), the server freezes and retains the original handler pointers, then stable-sorts a copied pointer vector by descending priority. Configuration and shared media mappings reject mutation while any server using them is starting or active; the freeze is reference-counted and released after terminal shutdown and outstanding worker use.

Session and server routes always take precedence. A dynamic path match also suppresses static content when its method does not match or it is a fallback. Static handlers accept GET and HEAD; another method for existing content returns 405 with Allow: GET, HEAD. Prefixes match complete decoded NFC segments. Only a negative probe continues to the next matching handler, which permits deterministic built-in or custom overlays.

Paths without a trailing slash are probed exactly and never infer a directory or redirect. For a path ending in /, the server appends each configured index filename and probes it in order; the defaults are index.html and index.htm. Filesystem traversal rejects links, non-regular files, unsafe decoded segments, Windows device and alternate-stream spellings, and containment changes. Candidates are resolved with Path below the resolved root and opened through Path::content() with restrictive input-stream symlink handling. Filesystem roots are validated and canonicalized synchronously by HttpStaticFileHandler::create(). Probes, content creation, one-shot opening, and stream reads run on the blocking worker bridge; completions return to the owning event loop and output retains at most one back-pressured block.

HttpMediaTypeMapping::defaultMapping() supplies common web suffixes and an application/octet-stream fallback. Use create() for an empty mapping or defaultMapping()->copy() for an editable built-in clone. Matching is ASCII-case-insensitive and longest-suffix-first. Resource handlers retain an explicit ResourcesConstPtr or borrow the application-lifetime manager, and enforce a one-MiB per-resource logical-size default before loading data. They expose resource bytes through ByteBlockInputStream without another content copy.

Sessions

Without a manager, each connection receives one anonymous HttpServerSession reused by its sequential requests. Session data is an application-defined HttpSessionData pointer. A synchronous HttpServerSessionManager can select identified sessions shared by multiple connections and attach bounded fields to the eventual response.

HttpCookieSessionManager provides opaque 256-bit identifiers in a host-only, HttpOnly cookie. Its bounded server-side registry defaults to a 30-minute idle lifetime, a 24-hour absolute lifetime, and 10,000 sessions. Unknown identifiers never become session identities. Expiry and least-recently-used eviction use ordered structures, and invalidation emits a deletion cookie.

See Using HTTP Servers for configuration, routing, body handling, streamed responses, TLS, and cookie-session examples.

Interface

class HttpConnectionInfo

An immutable transport-independent snapshot of an HTTP connection.

The snapshot deliberately exposes no transport object or mutable event interface and can be extended for future HTTP transports without changing the request ownership model.

Public Functions

inline HttpConnectionInfo(std::optional<IpEndpoint> localEndpoint, std::optional<IpEndpoint> remoteEndpoint, std::optional<HttpTlsConnectionInfo> tls = {}): Create a connection information snapshot.

inline const std::optional<IpEndpoint> &localEndpoint() const noexcept: Get the local endpoint captured for this connection.

inline const std::optional<IpEndpoint> &remoteEndpoint() const noexcept: Get the remote endpoint captured for this connection.

inline bool isSecure() const noexcept: Test whether this connection has authenticated TLS information.

inline const std::optional<HttpTlsConnectionInfo> &tls() const noexcept: Get the negotiated TLS information, if this is a secure connection.

using erbsland::network::HttpConnectionInfoFn = std::function<void(const HttpConnectionInfo&)>

A callback receiving an immutable HTTP connection snapshot.

using erbsland::network::HttpConnectionErrorFn = std::function<void(const HttpConnectionInfo&, const NetworkErrorContext&)>

A callback receiving a connection-local error and its immutable HTTP connection snapshot.

enum class erbsland::network::HttpCookieSecurePolicy : uint8_t

Secure-attribute policy for the built-in HTTP session cookie.

Values:

enumerator Automatic: Add Secure for HTTPS requests.

enumerator Always: Always add Secure.

enumerator Never: Never add Secure.

class HttpCookieSessionManager : public erbsland::network::HttpServerSessionManager 

A bounded server-side session registry selected through one opaque cookie.

Public Functions

virtual HttpServerSessionSelection selectSession(const HttpServerSessionContext &context) override: Select an existing registered identifier or create a fresh session and cookie.

virtual HttpHeaders sessionInvalidated(const HttpServerSessionPtr &session) override: Remove an invalidated session and create its deletion-cookie fields.

virtual HttpServerSessionRenewal renewSession(const HttpServerSessionPtr &session) override: Replace the identifier of an existing valid session.

Public Static Functions

static HttpCookieSessionManagerPtr create(HttpCookieSessionManagerOptions options = {})

Create a manager with validated cookie, lifetime, and capacity options.

Throws:: err::ParameterError – If an option is invalid.

using erbsland::network::HttpCookieSessionManagerPtr = std::shared_ptr<HttpCookieSessionManager>: A shared cookie-backed HTTP server session manager.

class HttpCookieSessionManagerOptions

Configuration for the bounded cookie-backed server session manager.

Public Functions

inline const text::String &cookieName() const noexcept: Get the manager-reserved cookie name.

inline HttpCookieSessionManagerOptions &setCookieName(text::String value) noexcept: Set the manager-reserved cookie name.

inline const text::String &cookiePath() const noexcept: Get the cookie Path attribute.

inline HttpCookieSessionManagerOptions &setCookiePath(text::String value) noexcept: Set the cookie Path attribute.

inline HttpCookieSameSite sameSite() const noexcept: Get the SameSite policy.

inline HttpCookieSessionManagerOptions &setSameSite(HttpCookieSameSite value) noexcept: Set the SameSite policy.

inline HttpCookieSecurePolicy securePolicy() const noexcept: Get the Secure-attribute policy.

inline HttpCookieSessionManagerOptions &setSecurePolicy(HttpCookieSecurePolicy value) noexcept: Set the Secure-attribute policy.

inline time::TimeDelta idleTimeout() const noexcept: Get the sliding inactivity lifetime.

inline HttpCookieSessionManagerOptions &setIdleTimeout(time::TimeDelta value) noexcept: Set the positive sliding inactivity lifetime.

inline time::TimeDelta absoluteTimeout() const noexcept: Get the total session lifetime.

inline HttpCookieSessionManagerOptions &setAbsoluteTimeout(time::TimeDelta value) noexcept: Set the positive total session lifetime.

inline unit::ItemCount maximumSessions() const noexcept: Get the finite server-side registry capacity.

inline HttpCookieSessionManagerOptions &setMaximumSessions(unit::ItemCount value) noexcept: Set the finite server-side registry capacity.

Public Static Attributes

static const auto cDefaultIdleTimeout = time::TimeDelta::minutes(30): Default sliding inactivity lifetime.

static const auto cDefaultAbsoluteTimeout = time::TimeDelta::hours(24): Default total session lifetime.

static constexpr auto cDefaultMaximumSessions = unit::ItemCount{10'000U}: Default bounded registry capacity.

class HttpMediaTypeMapping

A bounded suffix-to-media-type mapping for static HTTP content.

Suffix matching is ASCII-case-insensitive, and the longest matching suffix wins.

See: HTTP Server

Public Functions

HttpMediaType fallbackMediaType() const: Get the fallback used when no suffix matches.

HttpMediaTypeMapping &setFallbackMediaType(HttpMediaType mediaType): Replace the fallback media type.

HttpMediaTypeMapping &setFallbackMediaType(text::String mediaType): Replace the fallback from validated media-type text.

HttpMediaTypeMapping &setSuffix(text::String suffix, HttpMediaType mediaType): Add or replace one suffix mapping.

HttpMediaTypeMapping &setSuffix(text::String suffix, text::String mediaType): Add or replace one suffix mapping from validated media-type text.

HttpMediaTypeMapping &removeSuffix(const text::String &suffix): Remove one suffix mapping.

HttpMediaTypeMapping &clear(): Remove every suffix mapping while preserving the fallback.

HttpMediaType mediaType(const text::String &path) const: Resolve a filename or relative path to its configured media type.

HttpMediaTypeMappingPtr copy() const: Create a mutable independent copy.

Public Static Functions

static HttpMediaTypeMappingPtr create(): Create an empty mapping with an application/octet-stream fallback.

static HttpMediaTypeMappingConstPtr defaultMapping(): Access the immutable built-in mapping.

Public Static Attributes

static constexpr auto cMaximumSuffixCount = unit::ItemCount{256U}: Maximum number of custom suffix mappings.

static constexpr auto cMaximumSuffixLength = unit::ByteLength{64U}: Maximum length of one suffix.

class HttpServer : public erbsland::event::EventSource 

A configurable session-first HTTP/1.1 or HTTPS server.

Subclassed by erbsland::network::impl::HttpServer

Public Functions

virtual void setOptions(HttpServerOptions options) = 0: Replace HTTP limits and deadlines while inactive.

virtual void setListenerOptions(TcpListenerOptions options) = 0: Replace listener admission and socket options while inactive.

virtual void setTcpAcceptOptions(TcpAcceptOptions options) = 0: Replace accepted TCP stream options for plaintext and HTTPS while inactive.

virtual void enableTls() = 0: Enable HTTPS with secure HTTP defaults while inactive.

virtual void enableTls(HttpServerTlsOptions options) = 0: Enable HTTPS with curated server options while inactive.

virtual void setSessionManager(HttpServerSessionManagerPtr manager) = 0: Replace the synchronous logical-session manager while inactive.

virtual void addStaticContentHandler(HttpStaticContentHandlerPtr handler) = 0: Add one server-level static-content handler while inactive.

virtual std::optional<IpEndpoint> localEndpoint() const = 0: Get the effective local endpoint after the listener binds.

virtual NetworkSourceState state() const noexcept = 0: Get the server lifecycle state.

virtual void start(IpEndpoint localEndpoint) = 0: Bind and start after capturing configuration and routes.

virtual void pauseAccepting() = 0: Temporarily stop native acceptance without closing active sessions.

virtual void resumeAccepting() = 0: Resume native acceptance while active.

virtual void close() = 0: Stop accepting, disable reuse, and drain committed responses.

virtual void abort() noexcept = 0: Terminate listener and connections immediately.

virtual HttpServerEventEditor &events() override = 0: Access the stable callback and route editor on the owner loop.

using erbsland::network::HttpServerPtr = std::shared_ptr<HttpServer>: A shared HTTP server.

class HttpServerEventEditor : public erbsland::event::impl::CommonEventEditor

Callback and route editor for an HTTP server.

Subclassed by erbsland::network::impl::HttpServerEventEditor

Public Functions

virtual HttpServerEventEditor &onListening(NetworkEventFn callback) = 0: Replace the callback emitted after binding completes.

virtual HttpServerEventEditor &onConnectionActive(HttpConnectionInfoFn callback) = 0: Replace the callback emitted after an accepted connection completes its transport setup.

virtual HttpServerEventEditor &onConnectionFinal(HttpConnectionInfoFn callback) = 0: Replace the callback emitted before an accepted connection is discarded.

virtual HttpServerEventEditor &onConnectionError(HttpConnectionErrorFn callback) = 0: Replace the callback emitted for an accepted-connection error that does not fail the listener.

virtual HttpServerEventEditor &onNewSession(HttpServerSessionFn callback) = 0: Replace the callback emitted before a newly created session is routed.

virtual HttpServerEventEditor &onRequest(text::String pattern, HttpServerRequestFn callback, HttpServerRouteOptions options = {}) = 0: Add an aggregated byte route for every valid method.

virtual auto onRequest(HttpMethod method, text::String pattern, HttpServerRequestFn callback, HttpServerRouteOptions options = {}) -> HttpServerEventEditor& = 0: Add an aggregated byte route for one method.

virtual auto onRequest(HttpMethodTypes methods, text::String pattern, HttpServerRequestFn callback, HttpServerRouteOptions options = {}) -> HttpServerEventEditor& = 0: Add an aggregated byte route for standard method flags.

virtual auto onTextRequest(text::String pattern, HttpServerTextRequestFn callback, HttpServerRouteOptions options = {}) -> HttpServerEventEditor& = 0: Add an aggregated strict UTF-8 route for every valid method.

virtual auto onTextRequest(HttpMethod method, text::String pattern, HttpServerTextRequestFn callback, HttpServerRouteOptions options = {}) -> HttpServerEventEditor& = 0: Add an aggregated strict UTF-8 route for one method.

virtual auto onTextRequest(HttpMethodTypes methods, text::String pattern, HttpServerTextRequestFn callback, HttpServerRouteOptions options = {}) -> HttpServerEventEditor& = 0: Add an aggregated strict UTF-8 route for standard method flags.

virtual auto onJsonRequest(text::String pattern, HttpServerJsonRequestFn callback, HttpServerRouteOptions options = {}) -> HttpServerEventEditor& = 0: Add an aggregated JSON route for every valid method.

virtual auto onJsonRequest(HttpMethod method, text::String pattern, HttpServerJsonRequestFn callback, HttpServerRouteOptions options = {}) -> HttpServerEventEditor& = 0: Add an aggregated JSON route for one method.

virtual auto onJsonRequest(HttpMethodTypes methods, text::String pattern, HttpServerJsonRequestFn callback, HttpServerRouteOptions options = {}) -> HttpServerEventEditor& = 0: Add an aggregated JSON route for standard method flags.

virtual HttpServerEventEditor &onRequestHead(text::String pattern, HttpServerRequestHeadFn callback) = 0: Add a low-level request-head route for every valid method.

virtual HttpServerEventEditor &onRequestHead(HttpMethod method, text::String pattern, HttpServerRequestHeadFn callback) = 0: Add a low-level request-head route for one method.

virtual HttpServerEventEditor &onRequestHead(HttpMethodTypes methods, text::String pattern, HttpServerRequestHeadFn callback) = 0: Add a low-level request-head route for standard method flags.

virtual HttpServerEventEditor &onRequestHead(HttpServerRequestHeadFn callback) = 0: Add the only patternless fallback route family.

virtual HttpServerEventEditor &onClosed(NetworkEventFn callback) = 0: Replace the graceful-closure callback.

virtual HttpServerEventEditor &onError(NetworkErrorFn callback) = 0: Replace the operational-error callback.

virtual HttpServerEventEditor &onFinal(NetworkEventFn callback) = 0: Replace the exactly-once final callback.

class HttpServerOptions

Limits and deadlines captured when an HTTP server starts.

Public Functions

inline HttpHeaderLimits headerLimits() const noexcept: Get the request and response header limits.

inline HttpServerOptions &setHeaderLimits(HttpHeaderLimits value) noexcept: Set the request and response header limits.

inline unit::ByteLength maximumStartLineLength() const noexcept: Get the maximum request-line length.

inline HttpServerOptions &setMaximumStartLineLength(unit::ByteLength value) noexcept: Set the maximum request-line length.

inline unit::ByteLength maximumBodyLength() const noexcept: Get the decoded request-body hard maximum.

inline HttpServerOptions &setMaximumBodyLength(unit::ByteLength value) noexcept: Set the decoded request-body hard maximum.

inline unit::ByteLength maximumQueueLength() const noexcept: Get the transaction queue maximum.

inline HttpServerOptions &setMaximumQueueLength(unit::ByteLength value) noexcept: Set the transaction queue maximum.

inline unit::ByteLength maximumFixedResponseLength() const noexcept: Get the request-bound fixed-response body maximum.

inline HttpServerOptions &setMaximumFixedResponseLength(unit::ByteLength value) noexcept: Set the request-bound fixed-response body maximum.

inline unit::ItemCount maximumRequestsPerConnection() const noexcept: Get the finite number of transactions accepted per connection.

inline HttpServerOptions &setMaximumRequestsPerConnection(unit::ItemCount value) noexcept: Set the finite number of transactions accepted per connection.

inline unit::ItemCount maximumStaticContentResponses() const noexcept: Get the maximum number of active static-content responses.

inline HttpServerOptions &setMaximumStaticContentResponses(unit::ItemCount value) noexcept: Set the maximum number of active static-content responses.

inline unit::ItemCount maximumStaticContentOperations() const noexcept: Get the maximum number of queued blocking static-content operations.

inline HttpServerOptions &setMaximumStaticContentOperations(unit::ItemCount value) noexcept: Set the maximum number of queued blocking static-content operations.

inline unit::ByteLength maximumStaticContentQueueLength() const noexcept: Get the maximum completed static-content bytes awaiting HTTP output.

inline HttpServerOptions &setMaximumStaticContentQueueLength(unit::ByteLength value) noexcept: Set the maximum completed static-content bytes awaiting HTTP output.

inline unit::ByteLength maximumRetainedStaticContentMemoryLength() const noexcept: Get the maximum aggregate static-content memory retained by active responses.

inline HttpServerOptions &setMaximumRetainedStaticContentMemoryLength(unit::ByteLength value) noexcept: Set the maximum aggregate static-content memory retained by active responses.

inline unit::ByteLength staticContentChunkLength() const noexcept: Get the static-content output chunk length.

inline HttpServerOptions &setStaticContentChunkLength(unit::ByteLength value) noexcept: Set the positive static-content output chunk length up to 16 KiB.

inline time::TimeDelta headerTimeout() const noexcept: Get the request-head deadline.

inline HttpServerOptions &setHeaderTimeout(time::TimeDelta value) noexcept: Set the request-head deadline.

inline time::TimeDelta bodyIdleTimeout() const noexcept: Get the rolling request-body idle deadline.

inline HttpServerOptions &setBodyIdleTimeout(time::TimeDelta value) noexcept: Set the rolling request-body idle deadline.

inline time::TimeDelta totalTimeout() const noexcept: Get the absolute transaction deadline.

inline HttpServerOptions &setTotalTimeout(time::TimeDelta value) noexcept: Set the absolute transaction deadline.

inline time::TimeDelta closeTimeout() const noexcept: Get the graceful connection-close deadline.

inline HttpServerOptions &setCloseTimeout(time::TimeDelta value) noexcept: Set the graceful connection-close deadline.

Public Static Attributes

static const auto cDefaultHeaderTimeout = time::TimeDelta::seconds(30): Default deadline for a complete request head.

static const auto cDefaultBodyIdleTimeout = time::TimeDelta::minutes(5): Default rolling deadline while receiving a body.

static const auto cDefaultTotalTimeout = time::TimeDelta::minutes(30): Default absolute transaction deadline.

static const auto cDefaultCloseTimeout = time::TimeDelta::seconds(10): Default graceful connection-close deadline.

static constexpr auto cDefaultMaximumStartLineLength = unit::ByteLength{8U * 1024U}: Default maximum request-line length.

static constexpr auto cDefaultMaximumBodyLength = unit::ByteLength{16U * 1024U * 1024U}: Default decoded request-body maximum.

static constexpr auto cDefaultMaximumQueueLength = unit::ByteLength{1024U * 1024U}: Default transaction input and output queue maximum.

static constexpr auto cDefaultMaximumFixedResponseLength = unit::ByteLength{256U * 1024U}: Default fixed-response body maximum.

static constexpr auto cDefaultMaximumRequestsPerConnection = unit::ItemCount{1000U}: Default finite keep-alive transaction count.

static constexpr auto cDefaultMaximumStaticContentResponses = unit::ItemCount{128U}: Default maximum number of active static-content responses and open files.

static constexpr auto cDefaultMaximumStaticContentOperations = unit::ItemCount{256U}: Default maximum number of queued blocking content operations.

static constexpr auto cDefaultMaximumStaticContentQueueLength = unit::ByteLength{2U * 1024U * 1024U}: Default maximum bytes retained between content workers and HTTP output.

static constexpr auto cDefaultMaximumRetainedStaticContentMemoryLength = unit::ByteLength{16U * 1024U * 1024U}: Default maximum aggregate static-content memory retained by active responses.

static constexpr auto cDefaultStaticContentChunkLength = unit::ByteLength{16U * 1024U}: Default and hard maximum for one static-content output block.

class HttpServerRequest : public erbsland::event::EventSource 

One retained request and response transaction on an HTTP server.

Subclassed by erbsland::network::impl::HttpServerRequest

Public Functions

virtual const HttpRequestHead &head() const noexcept = 0: Get the immutable exact request head.

virtual const text::String &path() const noexcept = 0: Get the decoded NFC path without its query.

virtual const text::String &query() const noexcept = 0: Get the exact query text without the question mark.

virtual std::optional<text::String> parameter(const text::String &name) const = 0: Get a captured complete-segment or catch-all route parameter.

virtual const HttpConnectionInfo &connectionInfo() const noexcept = 0: Get the immutable snapshot of the underlying HTTP connection.

virtual HttpServerSessionPtr session() const = 0: Get the selected logical session.

virtual void streamBody() = 0: Select incremental body delivery through onBodyData.

virtual void aggregateBody(unit::ByteLength maximumLength) = 0: Select atomic aggregation under a finite request-specific maximum.

virtual void rejectBody() = 0: Reject unread body bytes 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 void sendResponse(HttpResponseHead response, mem::ByteBlock body = {}) = 0: Commit one fixed response and optional body atomically.

virtual void sendText(text::String body, HttpStatus status = HttpStatus::Ok, HttpHeaders headers = {}) = 0: Commit one UTF-8 plain-text response.

virtual void sendJson(text::String body, HttpStatus status = HttpStatus::Ok, HttpHeaders headers = {}) = 0: Commit one UTF-8 JSON response.

virtual void sendJson(const text::json::JsonValue &body, HttpStatus status = HttpStatus::Ok, HttpHeaders headers = {}) = 0: Serialize and commit one compact JSON response.

virtual void sendError(HttpStatus status, text::String message = {}) = 0: Commit one plain-text error response.

virtual void sendRedirect(text::String location, HttpStatus status = HttpStatus::Found, HttpHeaders headers = {}) = 0: Commit one redirect with a Location field.

virtual void startResponse(HttpResponseHead response) = 0: Commit the head of one streamed response.

virtual NetworkSendStatus sendBody(const mem::ByteBlock &data) = 0: Atomically submit one streamed response-body block.

virtual void finishBody(HttpHeaders trailers = {}) = 0: Finish a streamed response with optional trailers.

virtual bool isResponseStarted() const noexcept = 0: Test whether the final response head is committed.

virtual bool isFinal() const noexcept = 0: Test whether this retained request can no longer affect its connection.

virtual HttpServerRequestEventEditor &events() override = 0: Access the stable body, writable, and final callback editor.

using erbsland::network::HttpServerRequestPtr = std::shared_ptr<HttpServerRequest>: A shared HTTP server request.

class HttpServerRequestEventEditor : public erbsland::event::impl::CommonEventEditor

Callback editor for one HTTP server request.

Subclassed by erbsland::network::impl::HttpServerRequestEventEditor

Public Functions

virtual HttpServerRequestEventEditor &onResponseCommitted(HttpServerResponseFn callback) = 0: Replace the callback emitted after the final response head is committed.

virtual HttpServerRequestEventEditor &onError(NetworkErrorFn callback) = 0: Replace the callback emitted for an error affecting this request.

virtual HttpServerRequestEventEditor &onBodyData(NetworkDataFn callback) = 0: Replace the streamed-body block callback.

virtual HttpServerRequestEventEditor &onBody(NetworkDataFn callback) = 0: Replace the bounded aggregated-body callback.

virtual HttpServerRequestEventEditor &onTrailers(std::function<void(const HttpHeaders&)> callback) = 0: Replace the decoded-trailer callback.

virtual HttpServerRequestEventEditor &onBodyCompleted(NetworkEventFn callback) = 0: Replace the incoming-body completion callback.

virtual HttpServerRequestEventEditor &onWritable(NetworkEventFn callback) = 0: Replace the semantic response-writable callback.

virtual HttpServerRequestEventEditor &onFinal(NetworkEventFn callback) = 0: Replace the exactly-once request final callback.

using erbsland::network::HttpServerRequestFn = std::function<void(HttpServerSessionPtr, HttpServerRequestPtr, mem::ByteBlock)>

An aggregated byte-request handler.

using erbsland::network::HttpServerTextRequestFn = std::function<void(HttpServerSessionPtr, HttpServerRequestPtr, text::String)>

An aggregated strict UTF-8 request handler.

using erbsland::network::HttpServerJsonRequestFn = std::function<void(HttpServerSessionPtr, HttpServerRequestPtr, text::json::JsonValue)>

An aggregated JSON request handler.

using erbsland::network::HttpServerRequestHeadFn = std::function<void(HttpServerSessionPtr, HttpServerRequestPtr)>

A low-level request-head handler selecting its body policy manually.

using erbsland::network::HttpServerSessionFn = std::function<void(HttpServerSessionPtr)>

A new-session handler.

using erbsland::network::HttpServerRequestEventFn = std::function<void(HttpServerRequestPtr)>

A callback receiving a request selected for one logical session.

using erbsland::network::HttpServerResponseFn = std::function<void(const HttpResponseHead&)>

A callback receiving the final committed response head for one request.

class HttpServerRouteOptions

Body limits and media filters for an automatic HTTP server route.

Public Functions

inline unit::ByteLength maximumBodyLength() const noexcept: Get the automatic request-body aggregation limit.

inline HttpServerRouteOptions &setMaximumBodyLength(unit::ByteLength value) noexcept: Set the positive finite automatic request-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 route-kind defaults; an empty list disables filtering.

inline HttpServerRouteOptions &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 request-body aggregation limit.

class HttpServerSession : public erbsland::event::EventSource 

A logical HTTP server session that can span multiple connections.

Subclassed by erbsland::network::impl::HttpServerSession

Public Functions

virtual std::optional<text::String> identifier() const = 0: Get the optional manager-assigned identifier.

virtual const HttpSessionDataPtr &data() const noexcept = 0: Get the application-defined session data pointer.

virtual void setData(HttpSessionDataPtr data) = 0: Replace application-defined session data on the owner loop.

virtual bool isValid() const noexcept = 0: Test whether this session can be selected for new requests.

virtual void invalidate() = 0: Prevent new selection and notify the session manager.

virtual bool renewIdentifier() = 0

Replace the manager-owned identifier while preserving session data.

Returns:: true if the active session manager renewed the identifier.

virtual HttpServerSessionEventEditor &events() override = 0: Access session-specific routes and lifecycle callbacks.

using erbsland::network::HttpServerSessionPtr = std::shared_ptr<HttpServerSession>: A shared HTTP server session.

using erbsland::network::HttpServerSessionWeakPtr = std::weak_ptr<HttpServerSession>: A weak HTTP server session.

using erbsland::network::HttpSessionDataPtr = std::shared_ptr<HttpSessionData>: Shared application-defined session data.

class HttpServerSessionContext

Session-resolution context for one request.

Public Types

using CreateFn = std::function<HttpServerSessionPtr(std::optional<text::String>, HttpSessionDataPtr)>: Server-owned session factory used by synchronous managers.

Public Functions

inline HttpServerSessionContext(HttpServerRequestPtr request, bool secure, CreateFn createFn): Create one request-specific manager context.

inline const HttpServerRequestPtr &request() const noexcept: Get the complete retained request and its connection context.

inline bool isSecure() const noexcept: Test whether the request uses an authenticated TLS connection.

inline HttpServerSessionPtr createSession(std::optional<text::String> identifier = {}, HttpSessionDataPtr data = {}) const: Create a server-owned logical session with optional identity and data.

class HttpServerSessionEventEditor : public erbsland::event::impl::CommonEventEditor

Callback and route editor for one HTTP server session.

Subclassed by erbsland::network::impl::HttpServerSessionEventEditor

Public Functions

virtual HttpServerSessionEventEditor &onRequestReceived(HttpServerRequestEventFn callback) = 0: Replace the callback emitted when a request is selected for this session.

virtual HttpServerSessionEventEditor &onRequest(text::String pattern, HttpServerRequestFn callback, HttpServerRouteOptions options = {}) = 0: Add an aggregated byte route for every method.

virtual auto onRequest(HttpMethod method, text::String pattern, HttpServerRequestFn callback, HttpServerRouteOptions options = {}) -> HttpServerSessionEventEditor& = 0: Add an aggregated byte route for one method.

virtual auto onRequest(HttpMethodTypes methods, text::String pattern, HttpServerRequestFn callback, HttpServerRouteOptions options = {}) -> HttpServerSessionEventEditor& = 0: Add an aggregated byte route for standard method flags.

virtual auto onTextRequest(text::String pattern, HttpServerTextRequestFn callback, HttpServerRouteOptions options = {}) -> HttpServerSessionEventEditor& = 0: Add an aggregated strict UTF-8 text route for every method.

virtual auto onTextRequest(HttpMethod method, text::String pattern, HttpServerTextRequestFn callback, HttpServerRouteOptions options = {}) -> HttpServerSessionEventEditor& = 0: Add an aggregated strict UTF-8 text route for one method.

virtual auto onTextRequest(HttpMethodTypes methods, text::String pattern, HttpServerTextRequestFn callback, HttpServerRouteOptions options = {}) -> HttpServerSessionEventEditor& = 0: Add an aggregated strict UTF-8 text route for standard method flags.

virtual auto onJsonRequest(text::String pattern, HttpServerJsonRequestFn callback, HttpServerRouteOptions options = {}) -> HttpServerSessionEventEditor& = 0: Add an aggregated JSON route for every method.

virtual auto onJsonRequest(HttpMethod method, text::String pattern, HttpServerJsonRequestFn callback, HttpServerRouteOptions options = {}) -> HttpServerSessionEventEditor& = 0: Add an aggregated JSON route for one method.

virtual auto onJsonRequest(HttpMethodTypes methods, text::String pattern, HttpServerJsonRequestFn callback, HttpServerRouteOptions options = {}) -> HttpServerSessionEventEditor& = 0: Add an aggregated JSON route for standard method flags.

virtual HttpServerSessionEventEditor &onRequestHead(text::String pattern, HttpServerRequestHeadFn callback) = 0: Add a low-level request-head route for every method.

virtual HttpServerSessionEventEditor &onRequestHead(HttpMethod method, text::String pattern, HttpServerRequestHeadFn callback) = 0: Add a low-level request-head route for one method.

virtual HttpServerSessionEventEditor &onRequestHead(HttpMethodTypes methods, text::String pattern, HttpServerRequestHeadFn callback) = 0: Add a low-level request-head route for standard method flags.

virtual HttpServerSessionEventEditor &onRequestHead(HttpServerRequestHeadFn callback) = 0: Add the low-level fallback invoked after all patterned routes fail.

virtual HttpServerSessionEventEditor &onInvalidated(NetworkEventFn callback) = 0: Replace the invalidation callback.

virtual HttpServerSessionEventEditor &onFinal(NetworkEventFn callback) = 0: Replace the exactly-once session final callback.

class HttpServerSessionManager

Synchronously selects a logical session for each HTTP server request.

Implementations run on the server owner loop and must not block.

Subclassed by erbsland::network::HttpCookieSessionManager

Public Functions

virtual HttpServerSessionSelection selectSession(const HttpServerSessionContext &context) = 0: Select or create one logical session and bounded eventual-response fields.

virtual HttpHeaders sessionInvalidated(const HttpServerSessionPtr &session) = 0: Remove manager state and return fields for the current invalidation response.

virtual HttpServerSessionRenewal renewSession(const HttpServerSessionPtr &session) = 0: Replace the identifier of an existing valid session.

using erbsland::network::HttpServerSessionManagerPtr = std::shared_ptr<HttpServerSessionManager>: A shared HTTP server session manager.

class HttpServerSessionRenewal

The result of renewing a manager-owned HTTP session identifier.

Public Functions

HttpServerSessionRenewal() = default: Create an invalid renewal result.

inline HttpServerSessionRenewal(std::optional<text::String> identifier, HttpHeaders responseFields): Create a successful renewal result.

inline bool isValid() const noexcept: Test whether the session identifier was renewed.

inline const std::optional<text::String> &identifier() const noexcept: Get the replacement identifier.

inline const HttpHeaders &responseFields() const noexcept: Get fields to append to the next response for this session.

class HttpServerSessionSelection

The session and response fields selected for one request.

Public Functions

HttpServerSessionSelection() = default: Create an invalid selection.

inline HttpServerSessionSelection(HttpServerSessionPtr session, HttpHeaders responseFields = {}, std::optional<text::String> reservedCookieName = {}): Create a valid selection.

inline bool isValid() const noexcept: Test whether a non-null session was selected.

inline const HttpServerSessionPtr &session() const noexcept: Get the selected logical session.

inline const HttpHeaders &responseFields() const noexcept: Get manager-owned fields appended to the eventual response.

inline const std::optional<text::String> &reservedCookieName() const noexcept: Get a cookie name that application responses must not set.

class HttpServerTlsOptions

Curated HTTPS configuration captured when an HTTP server starts.

Public Functions

inline const text::String &configurationLabel() const noexcept: Get the default server-identity configuration label.

inline HttpServerTlsOptions &setConfigurationLabel(text::String value) noexcept: Set the default server-identity configuration label.

inline const std::vector<TlsServerIdentityMapping> &identityMappings() const noexcept: Get exact canonical SNI identity mappings.

inline HttpServerTlsOptions &setIdentityMappings(std::vector<TlsServerIdentityMapping> value) noexcept: Replace exact canonical SNI identity mappings.

inline unit::ItemCount maximumConcurrentHandshakes() const noexcept: Get the maximum number of concurrent incomplete handshakes.

inline HttpServerTlsOptions &setMaximumConcurrentHandshakes(unit::ItemCount value) noexcept: Set the positive finite number of concurrent incomplete handshakes.

inline time::TimeDelta handshakeTimeout() const noexcept: Get the TLS handshake deadline.

inline HttpServerTlsOptions &setHandshakeTimeout(time::TimeDelta value) noexcept: Set the positive TLS handshake deadline.

Public Static Attributes

static const auto cDefaultConfigurationLabel = text::String{"http/server"}: Default server-identity configuration label.

static constexpr auto cDefaultMaximumConcurrentHandshakes = unit::ItemCount{128U}: Default incomplete-handshake capacity.

static const auto cDefaultHandshakeTimeout = time::TimeDelta::seconds(30): Default TLS handshake deadline.

class HttpSessionData

Application-defined data associated with an HTTP server session.

class HttpStaticContent

One static HTTP response body with a known length.

Implementations may prepare content lazily. open() is called at most once and must return a non-null stream positioned at byte zero. Implementations are invoked on server workers and must be thread-safe.

See: HTTP Server

Subclassed by erbsland::network::impl::HttpStaticFileContent, erbsland::network::impl::HttpStaticResourceContent

Public Functions

virtual unit::ByteLength length() const noexcept = 0: Get the exact finite logical content length.

virtual unit::ByteLength retainedMemoryLength() const noexcept

Get the memory retained while this content is active.

The conservative default assumes the complete logical content is retained.

virtual stream::ByteInputStreamPtr open() = 0: Open the one-shot content stream at byte zero.

class HttpStaticContentHandler

Extensible server-level static-content source.

Methods may block, are invoked concurrently on server workers, and therefore must be thread-safe. Paths supplied to hasPath() and getContent() are validated decoded-NFC relative paths and must be matched case-sensitively.

See: HTTP Server

Subclassed by erbsland::network::HttpStaticFileHandler, erbsland::network::HttpStaticResourceHandler

Public Functions

virtual ~HttpStaticContentHandler() = default: Release the handler configuration.

virtual bool hasPath(const path::Path &relativePath) const = 0

Probe whether this handler owns an exact relative path.

Return false only for normal absence or ineligibility. A positive result is authoritative.

virtual HttpStaticContentPtr getContent(const path::Path &relativePath) const = 0: Create content for a path previously accepted by hasPath().

text::String urlPrefix() const: Get the decoded URL prefix matched on complete path segments.

HttpStaticContentHandler &setUrlPrefix(text::String value): Replace the decoded URL prefix matched on complete path segments.

std::int32_t priority() const noexcept: Get the ordering priority; higher values are searched first.

HttpStaticContentHandler &setPriority(std::int32_t value): Set the ordering priority.

text::StringList indexFileNames() const: Get the ordered index filenames.

HttpStaticContentHandler &setIndexFileNames(text::StringList value): Replace the ordered index filenames.

HttpMediaTypeMappingConstPtr mediaTypeMapping() const: Get the shared media-type mapping.

HttpStaticContentHandler &setMediaTypeMapping(HttpMediaTypeMappingConstPtr value): Replace the shared media-type mapping.

class HttpStaticFileHandler : public erbsland::network::HttpStaticContentHandler 

A static-content handler backed by one securely contained filesystem root.

See: HTTP Server

Subclassed by erbsland::network::impl::HttpStaticFileHandler

Public Functions

inline const path::Path &rootPath() const noexcept: Get the configured filesystem root.

Public Static Functions

static HttpStaticFileHandlerPtr create(path::Path rootPath, text::String urlPrefix = text::String{"/"}): Create a handler for one filesystem root and URL prefix.

class HttpStaticResourceHandler : public erbsland::network::HttpStaticContentHandler 

A static-content handler backed by one compiled or custom resource identifier.

See: HTTP Server

Subclassed by erbsland::network::impl::HttpStaticResourceHandler

Public Functions

inline const resource::Resources &resources() const noexcept: Get the resource provider.

inline const text::String &identifier() const noexcept: Get the exact portable resource identifier.

unit::ByteLength maximumContentLength() const noexcept: Get the per-resource logical-content maximum.

HttpStaticResourceHandler &setMaximumContentLength(unit::ByteLength value): Set the positive finite per-resource logical-content maximum.

Public Static Functions

static auto create(resource::ResourcesConstPtr resources, text::String identifier, text::String urlPrefix = text::String{"/"}) -> HttpStaticResourceHandlerPtr: Create a handler retaining an explicit resource provider.

static HttpStaticResourceHandlerPtr create(text::String identifier, text::String urlPrefix = text::String{"/"}): Create a handler borrowing the application-lifetime resource provider.

Public Static Attributes

static constexpr auto cDefaultMaximumContentLength = unit::ByteLength{1024U * 1024U}: Default per-resource logical-content limit matching the resource compiler.

class HttpTlsConnectionInfo

An immutable snapshot of negotiated TLS information for an HTTP connection.

Public Functions

inline HttpTlsConnectionInfo(std::optional<text::String> requestedConfigurationLabel, std::optional<text::String> matchedConfigurationLabel, std::optional<HostName> serverName, std::vector<text::String> offeredAlpn, text::String negotiatedAlpn, std::optional<cryptology::TlsCipherSuite> cipherSuite, std::optional<cryptology::TlsSignatureScheme> signatureScheme): Create a TLS information snapshot.

inline const std::optional<text::String> &requestedConfigurationLabel() const noexcept: Get the requested application TLS configuration label.

inline const std::optional<text::String> &matchedConfigurationLabel() const noexcept: Get the matched exact TLS configuration label.

inline const std::optional<HostName> &serverName() const noexcept: Get the canonical SNI server name, if offered.

inline const std::vector<text::String> &offeredAlpn() const noexcept: Get the bounded ALPN offer in wire order.

inline const text::String &negotiatedAlpn() const noexcept: Get the negotiated ALPN identifier, or an empty string.

inline const std::optional<cryptology::TlsCipherSuite> &cipherSuite() const noexcept: Get the negotiated TLS cipher suite.

inline const std::optional<cryptology::TlsSignatureScheme> &signatureScheme() const noexcept: Get the selected CertificateVerify signature scheme.