Unified HTTP/1.1 and HTTP/2 client using libcurl. More...

#include <cwist/net/http/http.h>
#include <cwist/sys/err/cwist_err.h>
#include <stddef.h>

Include dependency graph for http_client.h:

This graph shows which files directly or indirectly include this file:

Typedefs
typedef struct cwist_http_client	cwist_http_client
	Opaque HTTP client handle.

Functions
Lifecycle
cwist_http_client *	cwist_http_client_create (void)
	Create a new HTTP client.

void	cwist_http_client_destroy (cwist_http_client *client)
	Destroy an HTTP client and release all associated resources.

Configuration
void	cwist_http_client_set_follow_redirects (cwist_http_client *client, int follow)
	Enable or disable automatic redirect following.

void	cwist_http_client_set_timeout_ms (cwist_http_client *client, int timeout_ms)
	Set request timeout in milliseconds.

void	cwist_http_client_set_ca_bundle (cwist_http_client client, const char path)
	Set path to CA bundle for TLS verification.

void	cwist_http_client_enable_altsvc (cwist_http_client *client, int enabled)
	Enable or disable Alt-Svc caching for HTTP/3 upgrade.

void	cwist_http_client_set_altsvc_db (cwist_http_client client, const char path)
	Set Alt-Svc cache database file path.

Request Execution
cwist_error_t	cwist_http_client_request (cwist_http_client client, const char url, cwist_http_method_t method, cwist_http_header_node headers, const char body, size_t body_len, cwist_http_response **out_response)
	Perform a synchronous HTTP request.

Detailed Description

Unified HTTP/1.1 and HTTP/2 client using libcurl.

Provides a CWIST-native wrapper around libcurl for synchronous HTTP requests. Supports connection reuse, Alt-Svc upgrade to HTTP/3, redirects, cookies, and TLS via the system libcurl (linked against BoringSSL + nghttp2).

Definition in file http_client.h.

Typedef Documentation

◆ cwist_http_client

typedef struct cwist_http_client cwist_http_client

Opaque HTTP client handle.

Internally holds a libcurl multi handle for connection reuse and a share handle for DNS/cookie/SSL session caching.

Definition at line 28 of file http_client.h.

Function Documentation

◆ cwist_http_client_create()

cwist_http_client * cwist_http_client_create ( void )

Create a new HTTP client.

Initializes libcurl global state on first call (ref-counted).

Create a new HTTP client.

Acquires the shared curl global state, then initializes an easy handle with defaults: redirect following (max 10 hops), 30 s timeout, TCP keepalive, automatic content decoding, and a CWIST user agent.

Returns: new client handle, or NULL on allocation/curl init failure (the curl global reference is released in that case).

Definition at line 185 of file http_client.c.

References cap, cwist_alloc(), cwist_curl_global_acquire(), cwist_curl_global_release(), and cwist_free().

◆ cwist_http_client_destroy()

void cwist_http_client_destroy ( cwist_http_client * client )

Destroy an HTTP client and release all associated resources.

Cleans up the curl easy handle, frees the CA bundle and alt-svc paths, frees the handle, and releases the shared curl global reference. Safe to call with NULL.

Parameters

client client handle to destroy, or NULL.

Definition at line 226 of file http_client.c.

References cap, cwist_curl_global_release(), and cwist_free().

◆ cwist_http_client_enable_altsvc()

void cwist_http_client_enable_altsvc	(	cwist_http_client *	client,
		int	enabled
	)

Enable or disable Alt-Svc caching for HTTP/3 upgrade.

When enabled, libcurl caches Alt-Svc responses and may transparently upgrade HTTP/2 connections to HTTP/3 on subsequent requests.

Parameters

client	Client handle.
enabled	Non-zero to enable (default: 0).

Enable or disable Alt-Svc caching for HTTP/3 upgrade.

When enabled, libcurl may advertise and switch to alternative services for subsequent requests; requires a database path set via cwist_http_client_set_altsvc_db.

Parameters

client	client handle.
enabled	non-zero to enable alt-svc, 0 to disable.

Definition at line 287 of file http_client.c.

References cap.

◆ cwist_http_client_request()

cwist_error_t cwist_http_client_request	(	cwist_http_client *	client,
		const char *	url,
		cwist_http_method_t	method,
		cwist_http_header_node *	headers,
		const char *	body,
		size_t	body_len,
		cwist_http_response **	out_response
	)

Perform a synchronous HTTP request.

The request is executed using libcurl's easy interface. HTTP/2 multiplexing is used automatically when the server supports it. If Alt-Svc is enabled and the server previously advertised h3, libcurl may upgrade to HTTP/3 transparently.

Parameters

client	Client handle.
url	Fully-qualified URL (e.g. "https://example.com/path").
method	HTTP method enum.
headers	Optional request headers linked list (may be NULL).
body	Optional request body (may be NULL).
body_len	Length of `body` in bytes.
out_response	Output pointer for the parsed response. Caller must destroy with cwist_http_response_destroy().

Returns: CWIST error, err_i16 == 0 on success.

Perform a synchronous HTTP request.

The handle is reset and re-configured from the client settings before each call, so a client may be reused for multiple requests. The response body is capped at CWIST_HTTP_MAX_BODY_SIZE and headers at 200 entries; exceeding either cap fails the transfer. HTTP/2 is preferred with downgrade to HTTP/1.1. On success a cwist_http_response is allocated and stored in *out_response (caller must free it with cwist_http_response_free); *out_response is always set to NULL before the transfer starts. The client is not thread-safe; concurrent requests require separate handles.

Parameters

client	client handle.
url	request URL.
method	HTTP method.
headers	linked list of request headers, or NULL.
body	request body, or NULL for no body.
body_len	length of body in bytes.
out_response	output for the allocated response object.

Returns: cwist_error_t with err_i16 set to 0 on success, -1 on failure (invalid arguments, curl transfer error, or allocation failure).

Definition at line 336 of file http_client.c.

References cap, CWIST_ERR_INT16, CWIST_HTTP_BAD_REQUEST, CWIST_HTTP_CREATED, CWIST_HTTP_FORBIDDEN, cwist_http_header_free_all(), CWIST_HTTP_INTERNAL_ERROR, cwist_http_method_to_string(), CWIST_HTTP_NO_CONTENT, CWIST_HTTP_NOT_FOUND, CWIST_HTTP_NOT_IMPLEMENTED, CWIST_HTTP_OK, cwist_http_response_create(), CWIST_HTTP_SERVICE_UNAVAILABLE, CWIST_HTTP_UNAUTHORIZED, cwist_sstring_assign(), cwist_sstring_assign_len(), cwist_sstring::data, cwist_http_header_node::key, make_error(), cwist_http_header_node::next, and cwist_http_header_node::value.

◆ cwist_http_client_set_altsvc_db()

void cwist_http_client_set_altsvc_db	(	cwist_http_client *	client,
		const char *	path
	)

Set Alt-Svc cache database file path.

If set, Alt-Svc entries are persisted across process restarts.

Parameters

client	Client handle.
path	Filesystem path, or NULL for in-memory only.

Set Alt-Svc cache database file path.

Replaces any previously set path. Pass NULL to clear it.

Parameters

client	client handle.
path	path to the alt-svc cache file, or NULL.

Definition at line 302 of file http_client.c.

References cap, and cwist_free().

◆ cwist_http_client_set_ca_bundle()

void cwist_http_client_set_ca_bundle	(	cwist_http_client *	client,
		const char *	path
	)

Set path to CA bundle for TLS verification.

Parameters

client	Client handle.
path	Filesystem path to PEM CA bundle, or NULL for system default.

Set path to CA bundle for TLS verification.

Replaces any previously set path. Pass NULL to fall back to libcurl's default trust store.

Parameters

client	client handle.
path	filesystem path to the CA bundle, or NULL.

Definition at line 270 of file http_client.c.

References cap, and cwist_free().

◆ cwist_http_client_set_follow_redirects()

void cwist_http_client_set_follow_redirects	(	cwist_http_client *	client,
		int	follow
	)

Enable or disable automatic redirect following.

Parameters

client	Client handle.
follow	Non-zero to follow redirects (default: 1).
client	client handle.
follow	non-zero to follow redirects, 0 to disable.

Definition at line 243 of file http_client.c.

References cap.

◆ cwist_http_client_set_timeout_ms()

void cwist_http_client_set_timeout_ms	(	cwist_http_client *	client,
		int	timeout_ms
	)

Set request timeout in milliseconds.

Parameters

client	Client handle.
timeout_ms	Timeout value, 0 for no timeout (default: 30000).

Set request timeout in milliseconds.

Parameters

client	client handle.
timeout_ms	timeout in milliseconds (applied to the whole transfer).

Definition at line 255 of file http_client.c.

References cap.

Typedefs

Functions

Detailed Description

Typedef Documentation

◆ cwist_http_client

Function Documentation

◆ cwist_http_client_create()

◆ cwist_http_client_destroy()

◆ cwist_http_client_enable_altsvc()

◆ cwist_http_client_request()

◆ cwist_http_client_set_altsvc_db()

◆ cwist_http_client_set_ca_bundle()

◆ cwist_http_client_set_follow_redirects()

◆ cwist_http_client_set_timeout_ms()