http

HTTP request/response types, parsers, and server/client helpers.

Classes

Name	Description
`Authenticator`	Maintains HTTP Basic or Digest authentication state for outbound requests.
`BasicAuthenticator`	Encodes and decodes HTTP Basic authentication credentials.
`ChunkedAdapter`	HTTP chunked transfer encoding adapter for streaming responses.
`Client`	HTTP client for creating and managing outgoing connections.
`ClientConnection`	HTTP client connection for managing request/response lifecycle.
`Connection`	Base HTTP connection managing socket I/O and message lifecycle
`ConnectionAdapter`	Default HTTP socket adapter for reading and writing HTTP messages
`ConnectionPool`	LIFO connection pool for reusing ServerConnection objects. Avoids per-request heap allocation by resetting and reusing connections instead of destroying and recreating them.
`ConnectionStream`	Packet stream wrapper for an HTTP connection.
`Cookie`	HTTP cookie value plus its response/header attributes.
`FilePart`	Form part backed by a file on disk.
`FormPart`	An implementation of FormPart.
`FormWriter`	FormWriter is an HTTP client connection adapter for writing HTML forms.
`Message`	The base class for Request and Response.
`MultipartAdapter`	HTTP multipart encoding adapter for multipart/x-mixed-replace streaming.
`Parser`	HTTP request/response parser using the llhttp library.
`ParserObserver`	Abstract observer interface for HTTP parser events.
`ProgressSignal`	HTTP progress signal for upload and download progress notifications.
`Request`	HTTP request message with method, URI, headers, and optional body.
`Response`	HTTP response message with status, reason phrase, headers, and body metadata.
`Server`	HTTP server implementation.
`ServerConnection`	HTTP server connection.
`ServerConnectionFactory`	Factory for creating per-socket `[ServerConnection](icy-http-ServerConnection.html#serverconnection)` and per-request `[ServerResponder](icy-http-ServerResponder.html#serverresponder)` objects.
`ServerResponder`	Base responder interface for handling one HTTP request on a server connection. Derived classes typically override `[onRequest()](icy-http-ServerResponder.html#onrequest)` and optionally the streaming hooks.
`StringPart`	Form part backed by an in-memory string payload.
`URL`	An RFC 3986 based URL parser. Constructors and assignment operators will throw a SyntaxException if the URL is invalid.
`DateCache`	Caches the formatted Date header, updated once per second. Avoids per-request time formatting and string allocation.
`Method`	HTTP request methods.

Enumerations

Name	Description
`StatusCode`	HTTP Response Status Codes.
`ServerConnectionState`	HTTP server-side lifecycle phases used by the keep-alive state machine.
`ServerConnectionMode`	Transport mode for server connections before and after protocol upgrade.

StatusCode

enum StatusCode

HTTP Response Status Codes.

Value	Description
`Continue`
`SwitchingProtocols`
`OK`
`Created`
`Accepted`
`NonAuthoritative`
`NoContent`
`ResetContent`
`PartialContent`
`MultipleChoices`
`MovedPermanently`
`Found`
`SeeOther`
`NotModified`
`UseProxy`
`TemporaryRedirect`
`BadRequest`
`Unauthorized`
`PaymentRequired`
`Forbidden`
`NotFound`
`MethodNotAllowed`
`NotAcceptable`
`ProxyAuthRequired`
`RequestTimeout`
`Conflict`
`Gone`
`LengthRequired`
`PreconditionFailed`
`EntityTooLarge`
`UriTooLong`
`UnsupportedMediaType`
`RangeNotSatisfiable`
`ExpectationFailed`
`UnprocessableEntity`
`UpgradeRequired`
`InternalServerError`
`NotImplemented`
`BadGateway`
`Unavailable`
`GatewayTimeout`
`VersionNotSupported`

ServerConnectionState

enum ServerConnectionState

HTTP server-side lifecycle phases used by the keep-alive state machine.

Value	Description
`ReceivingHeaders`	Parsing request headers.
`ReceivingBody`	Receiving request body bytes.
`DispatchingOrSending`	Dispatching the responder or sending a normal response.
`Streaming`	Sending a long-lived streaming response.
`Upgraded`	Upgraded to a non-HTTP protocol such as WebSocket.
`Closing`	Close has been requested and teardown is in progress.
`Closed`	Connection has fully closed.

ServerConnectionMode

enum ServerConnectionMode

Transport mode for server connections before and after protocol upgrade.

Value	Description
`Http`	Standard HTTP request/response mode.
`Upgraded`	Upgraded transport mode owned by another protocol adapter.

Typedefs

Return	Name	Description
`std::vector< ClientConnection::Ptr >`	`ClientConnectionPtrVec`	List of owned client connections tracked by an HTTP client.

ClientConnectionPtrVec

std::vector< ClientConnection::Ptr > ClientConnectionPtrVec()

List of owned client connections tracked by an HTTP client.

Functions

Return	Name	Description
`bool`	`isBasicCredentials`	Returns true if the given Authorization header value uses HTTP Basic authentication.
`bool`	`isDigestCredentials`	Returns true if the given Authorization header value uses HTTP Digest authentication.
`bool`	`hasBasicCredentials`	Returns true if the request contains a Basic Authorization header.
`bool`	`hasDigestCredentials`	Returns true if the request contains a Digest Authorization header.
`bool`	`hasProxyBasicCredentials`	Returns true if the request contains a Basic Proxy-Authorization header.
`bool`	`hasProxyDigestCredentials`	Returns true if the request contains a Digest Proxy-Authorization header.
`void`	`extractCredentials`	Splits a "user:password" user-info string into separate username and password strings. If no ':' is present, the entire string is treated as the username and password is empty.
`void`	`extractCredentials`	Extracts username and password from the user-info component of a URL. Does nothing if the URL has no user-info part.
`ClientConnection::Ptr`	`createConnectionT` `inline`	Creates a ClientConnection (or subtype) for the given URL without registering it with a Client instance. The socket and adapter are chosen based on the URL scheme:
`ClientConnection::Ptr`	`createConnection` `inline`	Creates a ClientConnection for the given URL and optionally registers it with a Client. Equivalent to calling Client::createConnection() when `client` is non-null.
`const char *`	`getStatusCodeReason`	Returns the standard reason phrase for the given HTTP status code (e.g. "OK" for StatusCode::OK, "Not Found" for StatusCode::NotFound).
`const char *`	`getStatusCodeString`	Returns a combined "NNN Reason" string for the given HTTP status code (e.g. "200 OK").
`std::string`	`parseURI`	Extracts the URI (path and query) from a raw HTTP request line.
`bool`	`matchURL`	Tests whether a URI matches a glob-style expression.
`std::string`	`parseCookieItem`	Extracts a named attribute from a Cookie header value.
`bool`	`splitURIParameters`	Parses URL query parameters from a URI into key-value pairs. Handles percent-decoding of names and values.
`void`	`splitParameters`	Splits a header-style parameter string into a primary value and named attributes. Attributes are separated by ';'. Enclosing quotes are stripped from values.
`void`	`splitParameters`	Splits a substring (defined by iterators) into named attributes. Attributes are separated by ';'. Enclosing quotes are stripped from values.

isBasicCredentials

bool isBasicCredentials(std::string_view header)

Returns true if the given Authorization header value uses HTTP Basic authentication.

Parameters

header Value of the Authorization or WWW-Authenticate header.

isDigestCredentials

bool isDigestCredentials(std::string_view header)

Returns true if the given Authorization header value uses HTTP Digest authentication.

Parameters

header Value of the Authorization or WWW-Authenticate header.

hasBasicCredentials

bool hasBasicCredentials(const http::Request & request)

Returns true if the request contains a Basic Authorization header.

Parameters

request HTTP request to inspect.

hasDigestCredentials

bool hasDigestCredentials(const http::Request & request)

Returns true if the request contains a Digest Authorization header.

Parameters

request HTTP request to inspect.

hasProxyBasicCredentials

bool hasProxyBasicCredentials(const http::Request & request)

Returns true if the request contains a Basic Proxy-Authorization header.

Parameters

request HTTP request to inspect.

hasProxyDigestCredentials

bool hasProxyDigestCredentials(const http::Request & request)

Returns true if the request contains a Digest Proxy-Authorization header.

Parameters

request HTTP request to inspect.

extractCredentials

void extractCredentials(std::string_view userInfo, std::string & username, std::string & password)

Splits a "user:password" user-info string into separate username and password strings. If no ':' is present, the entire string is treated as the username and password is empty.

Parameters

userInfo Input string in the form "user:password".
username Receives the extracted username.
password Receives the extracted password.

extractCredentials

void extractCredentials(const http::URL & uri, std::string & username, std::string & password)

Extracts username and password from the user-info component of a URL. Does nothing if the URL has no user-info part.

Parameters

uri URL to extract credentials from.
username Receives the extracted username.
password Receives the extracted password.

createConnectionT

inline

template<class ConnectionT> inline ClientConnection::Ptr createConnectionT(const URL & url, uv::Loop * loop)

Creates a ClientConnection (or subtype) for the given URL without registering it with a Client instance. The socket and adapter are chosen based on the URL scheme:

"http" -> TCPSocket
"https" -> SSLSocket
"ws" -> TCPSocket + WebSocket adapter
"wss" -> SSLSocket + WebSocket adapter

Parameters

ConnectionT Concrete connection type derived from ClientConnection.

Parameters

url Target URL. Must have a recognised scheme.
loop Event loop to use. Defaults to the default libuv loop.

Returns

Shared pointer to the created connection.

Exceptions

std::runtime_error if the URL scheme is not recognised.

createConnection

inline

inline ClientConnection::Ptr createConnection(const URL & url, http::Client * client, uv::Loop * loop)

Creates a ClientConnection for the given URL and optionally registers it with a Client. Equivalent to calling Client::createConnection() when client is non-null.

Parameters

url Target URL. The scheme determines the socket and adapter type.
client Optional Client instance to register the connection with.
loop Event loop to use. Defaults to the default libuv loop.

Returns

Shared pointer to the created connection.

getStatusCodeReason

const char * getStatusCodeReason(StatusCode status)

Returns the standard reason phrase for the given HTTP status code (e.g. "OK" for StatusCode::OK, "Not Found" for StatusCode::NotFound).

Parameters

status HTTP status code.

Returns

Null-terminated reason phrase string.

getStatusCodeString

const char * getStatusCodeString(StatusCode status)

Returns a combined "NNN Reason" string for the given HTTP status code (e.g. "200 OK").

Parameters

status HTTP status code.

Returns

Null-terminated status code string.

parseURI

std::string parseURI(std::string_view request)

Extracts the URI (path and query) from a raw HTTP request line.

Parameters

request Raw HTTP request line (e.g. "GET /path?q=1 HTTP/1.1").

Returns

The URI portion (e.g. "/path?q=1").

matchURL

bool matchURL(std::string_view uri, std::string_view expression)

Tests whether a URI matches a glob-style expression.

Parameters

uri The URI to test.
expression Pattern to match against. '*' matches any sequence of characters.

Returns

true if the URI matches the expression.

parseCookieItem

std::string parseCookieItem(std::string_view cookie, std::string_view item)

Extracts a named attribute from a Cookie header value.

Parameters

cookie Full Cookie header value (e.g. "name=value; Path=/; HttpOnly").
item Attribute name to find (e.g. "Path").

Returns

The value of the named attribute, or an empty string if not found.

splitURIParameters

bool splitURIParameters(std::string_view uri, NVCollection & out)

Parses URL query parameters from a URI into key-value pairs. Handles percent-decoding of names and values.

Parameters

uri URI string optionally containing a '?' query component.
out Collection to populate with parsed parameters.

Returns

true if at least one parameter was parsed; false otherwise.

splitParameters

void splitParameters(const std::string & s, std::string & value, NVCollection & parameters)

Splits a header-style parameter string into a primary value and named attributes. Attributes are separated by ';'. Enclosing quotes are stripped from values.

Example input: "multipart/mixed; boundary="boundary-01234567"" Output value: "multipart/mixed", parameters: { "boundary" -> "boundary-01234567" }

Parameters

s Input string to split.
value Receives the primary value before the first ';'.
parameters Receives the parsed attribute key-value pairs.

splitParameters

void splitParameters(const std::string::const_iterator & begin, const std::string::const_iterator & end, NVCollection & parameters)

Splits a substring (defined by iterators) into named attributes. Attributes are separated by ';'. Enclosing quotes are stripped from values.

Parameters

begin Iterator to the start of the string to parse.
end Iterator past the end of the string to parse.
parameters Receives the parsed attribute key-value pairs.