HTTP Clients

HTTP Clients

CWIST has three outgoing-request clients:

Client	Header	Protocols	Notes
cwist_http_client	<cwist/net/http/http_client.h>	HTTP/1.1, HTTP/2, HTTP/3 via Alt-Svc	wraps the system libcurl
cwist_http3_client	<cwist/net/http/http3_client.h>	HTTP/3	on lsquic; see HTTP/3 and QUIC
gRPC client and channels	<cwist/net/grpc/grpc_channel.h>	gRPC over HTTP/2	see gRPC Client

cwist_http_client

#include <cwist/net/http/http_client.h>

cwist_http_client *c = cwist_http_client_create();
cwist_http_client_set_timeout_ms(c, 5000);

cwist_http_header_node *headers = NULL;
cwist_http_header_add(&headers, "Accept", "application/json");

cwist_http_response *res = NULL;
cwist_error_t err = cwist_http_client_request(c, "https://api.example.com/items",
                                              CWIST_HTTP_GET, headers, NULL, 0, &res);
if (cwist_error_is_ok(&err)) {
    printf("%d\n%s\n", res->status_code, res->body->data);
    cwist_http_response_destroy(res);
}
cwist_http_header_free_all(headers);
cwist_http_client_destroy(c);

Function	Description
cwist_http_client *cwist_http_client_create(void)	New client. libcurl global state is initialized on first use (reference counted). The client keeps connections for reuse and shares DNS, cookie and TLS-session caches.
void cwist_http_client_destroy(cwist_http_client *c)	Free it.
void cwist_http_client_set_follow_redirects(c, int follow)	Follow redirects (default on).
void cwist_http_client_set_timeout_ms(c, int ms)	Request timeout; 0 disables it (default 30000).
void cwist_http_client_set_ca_bundle(c, const char *path)	PEM CA bundle; NULL uses the system default.
void cwist_http_client_enable_altsvc(c, int enabled)	Cache Alt-Svc and let libcurl upgrade later requests to HTTP/3 when the libcurl build supports it (default off).
void cwist_http_client_set_altsvc_db(c, const char *path)	Persist the Alt-Svc cache in a file.
cwist_error_t cwist_http_client_request(c, url, method, headers, body, body_len, &response)	Synchronous request; HTTP/2 is negotiated when the server supports it. Destroy the response with cwist_http_response_destroy().

The client uses the system libcurl, so -lcurl (and its dependencies) must be linked; pkg-config --libs --static cwist includes it. Calls block, so do not make them on a reactor thread: run them from a scheduler job and complete the request with an async handler.