sig_http_client.h

SIG_HTTP_CLIENT_MAX_BODY

#define SIG_HTTP_CLIENT_MAX_BODY 65536

Maximum response body accepted by sig_http_client_get, in bytes.

sig_http_get_fn

typedef sig_status_t (*sig_http_get_fn)(const char *url, int timeout_ms, char **out_body, size_t *out_len);

Signature of sig_http_client_get, so callers can inject a stub in tests.

sig_http_client_get

sig_status_t sig_http_client_get(const char * url, int timeout_ms, char ** out_body, size_t * out_len)

Performs a blocking HTTP GET of url (redirects are not followed). On SIG_OK, *out_body is a NUL-terminated buffer from sig_alloc that the caller releases with sig_free, and *out_len is its length excluding the NUL. On any error *out_body and *out_len are left untouched. Returns SIG_ERR_INVALID_ARG for a NULL argument or a timeout_ms that is not positive (there is no "no timeout" mode), SIG_ERR_TIMEOUT when the transfer exceeds timeout_ms, and SIG_ERR_PLATFORM for connect/TLS/transfer failures, an HTTP status other than 200, or a body over 64 KiB.

sig_http_done_fn

typedef void (*sig_http_done_fn)(sig_status_t status, char *body, size_t len, void *ctx);

Asynchronous HTTP GET: the form capsules use, so a platform with no libcurl (or no threads) can supply its own transport. A port implements sig_http_get_async() and nothing else about the capsule changes. sig_http_get_async() starts a GET of url (redirects are not followed) and returns at once. On SIG_OK, done(status, body, len, ctx) is called exactly once, later, with the result of sig_http_client_get(): on SIG_OK body is a NUL-terminated sig_alloc buffer of len bytes that done now owns and must sig_free; otherwise body is NULL. done may run on ANY thread -- a worker, or the port's own event loop -- and never runs before sig_http_get_async() returns, so the caller may hold a lock across the call. It should do very little: hand the result to the owning service (see sig_service_schedule_job()) rather than act on it there. If sig_http_get_async() fails (SIG_ERR_INVALID_ARG for a NULL url/done or a timeout_ms that is not positive, SIG_ERR_ALLOC, or SIG_ERR_PLATFORM when the transfer cannot be started) done is NOT called. There is no cancel: the request runs to completion or timeout_ms, so ctx must stay valid until done has run.

sig_http_get_async_fn

typedef sig_status_t (*sig_http_get_async_fn)(const char *url, int timeout_ms, sig_http_done_fn done,
                                              void *ctx);

shared with sig_http_done_fn

Asynchronous HTTP GET: the form capsules use, so a platform with no libcurl (or no threads) can supply its own transport. A port implements sig_http_get_async() and nothing else about the capsule changes. sig_http_get_async() starts a GET of url (redirects are not followed) and returns at once. On SIG_OK, done(status, body, len, ctx) is called exactly once, later, with the result of sig_http_client_get(): on SIG_OK body is a NUL-terminated sig_alloc buffer of len bytes that done now owns and must sig_free; otherwise body is NULL. done may run on ANY thread -- a worker, or the port's own event loop -- and never runs before sig_http_get_async() returns, so the caller may hold a lock across the call. It should do very little: hand the result to the owning service (see sig_service_schedule_job()) rather than act on it there. If sig_http_get_async() fails (SIG_ERR_INVALID_ARG for a NULL url/done or a timeout_ms that is not positive, SIG_ERR_ALLOC, or SIG_ERR_PLATFORM when the transfer cannot be started) done is NOT called. There is no cancel: the request runs to completion or timeout_ms, so ctx must stay valid until done has run.

sig_http_get_async

sig_status_t sig_http_get_async(const char * url, int timeout_ms, sig_http_done_fn done, void * ctx)

shared with sig_http_done_fn

Asynchronous HTTP GET: the form capsules use, so a platform with no libcurl (or no threads) can supply its own transport. A port implements sig_http_get_async() and nothing else about the capsule changes. sig_http_get_async() starts a GET of url (redirects are not followed) and returns at once. On SIG_OK, done(status, body, len, ctx) is called exactly once, later, with the result of sig_http_client_get(): on SIG_OK body is a NUL-terminated sig_alloc buffer of len bytes that done now owns and must sig_free; otherwise body is NULL. done may run on ANY thread -- a worker, or the port's own event loop -- and never runs before sig_http_get_async() returns, so the caller may hold a lock across the call. It should do very little: hand the result to the owning service (see sig_service_schedule_job()) rather than act on it there. If sig_http_get_async() fails (SIG_ERR_INVALID_ARG for a NULL url/done or a timeout_ms that is not positive, SIG_ERR_ALLOC, or SIG_ERR_PLATFORM when the transfer cannot be started) done is NOT called. There is no cancel: the request runs to completion or timeout_ms, so ctx must stay valid until done has run.