http.h

#include <modkit/http.h>23 functions · 12 structs · 4 enums · 19 typedefs · 3 macros

Asynchronous HTTP client and native REST/static server.

Client event data and server request views are non-owning and valid only for the duration of their callback unless a field explicitly says it is copied.

Functions

mk_http_cancelfunction

mk_result mk_http_cancel(mk_http_request_t request)

Cancel a request; completion is still reported asynchronously.

Parameter	Type	Description
request	mk_http_request_t	Value for request.

Returns MK_SUCCESS or an error result.

mk_http_pausefunction

mk_result mk_http_pause(mk_http_request_t request)

Pause body reading and delivery for a streamed response.

Parameter	Type	Description
request	mk_http_request_t	Value for request.

Returns MK_SUCCESS or an error result.

mk_http_reply_sendfunction

mk_result mk_http_reply_send(mk_http_reply_t reply, const mk_http_response_desc *response)

Complete a deferred reply on the networking owner thread.

Parameter	Type	Description
reply	mk_http_reply_t	Value for reply.
response	const mk_http_response_desc *	Value for response.

Returns MK_SUCCESS or an error result.

mk_http_reply_validfunction

bool mk_http_reply_valid(mk_http_reply_t handle)

Return whether an HTTP reply handle is nonzero.

Parameter	Type	Description
handle	mk_http_reply_t	Value for handle.

Returns True when the operation succeeds.

mk_http_requestfunction

mk_result mk_http_request(const mk_http_request_desc *desc, mk_http_request_t *out_request)

Start an asynchronous request.

Descriptor strings, headers, TLS data, and body bytes are copied before return. Exactly one MK_HTTP_EVENT_COMPLETE is delivered after acceptance.

Parameter	Type	Description
desc	const mk_http_request_desc *	Request configuration.
out_request	mk_http_request_t *	Receives the request handle.

Returns MK_SUCCESS when accepted, otherwise an immediate error.

mk_http_request_desc_initfunction

mk_http_request_desc mk_http_request_desc_init(void)

Return GET/buffered defaults with 10-second connect and 60-second total timeouts.

Returns The resulting value.

mk_http_request_headerfunction

const char * mk_http_request_header(const mk_http_request_view *request, const char *name)

Find a request header case-insensitively, or return NULL.

Parameter	Type	Description
request	const mk_http_request_view *	Value for request.
name	const char *	Stable name.

Returns A borrowed pointer, or NULL when unavailable.

mk_http_request_paramfunction

const char * mk_http_request_param(const mk_http_request_view *request, const char *name)

Find a matched route parameter by name, or return NULL.

Parameter	Type	Description
request	const mk_http_request_view *	Value for request.
name	const char *	Stable name.

Returns A borrowed pointer, or NULL when unavailable.

mk_http_request_queryfunction

const char * mk_http_request_query(const mk_http_request_view *request, const char *name)

Find a decoded query parameter by name, or return NULL.

Parameter	Type	Description
request	const mk_http_request_view *	Value for request.
name	const char *	Stable name.

Returns A borrowed pointer, or NULL when unavailable.

mk_http_request_validfunction

bool mk_http_request_valid(mk_http_request_t handle)

Return whether an HTTP request handle is nonzero.

Parameter	Type	Description
handle	mk_http_request_t	Value for handle.

Returns True when the operation succeeds.

mk_http_response_bodyfunction

mk_result mk_http_response_body(mk_http_response_writer *response, const void *body, size_t size)

Set and copy the response body during a handler callback.

Parameter	Type	Description
response	mk_http_response_writer *	Value for response.
body	const void *	Value for body.
size	size_t	Size in bytes.

Returns MK_SUCCESS or an error result.

mk_http_response_headerfunction

mk_result mk_http_response_header(mk_http_response_writer *response, const char *name, const char *value)

Add or replace a response header during a handler callback.

Parameter	Type	Description
response	mk_http_response_writer *	Value for response.
name	const char *	Stable name.
value	const char *	Value to use.

Returns MK_SUCCESS or an error result.

mk_http_response_statusfunction

void mk_http_response_status(mk_http_response_writer *response, int status_code)

Set the response status code; a new response writer initially uses 200.

Parameter	Type	Description
response	mk_http_response_writer *	Value for response.
status_code	int	Value for status code.

mk_http_resumefunction

mk_result mk_http_resume(mk_http_request_t request)

Resume a previously paused streamed response.

Parameter	Type	Description
request	mk_http_request_t	Value for request.

Returns MK_SUCCESS or an error result.

mk_http_server_closefunction

mk_result mk_http_server_close(mk_http_server_t server)

Stop a server, close WebSockets, and complete deferred replies with 503.

Parameter	Type	Description
server	mk_http_server_t	Value for server.

Returns MK_SUCCESS or an error result.

mk_http_server_createfunction

mk_result mk_http_server_create(const mk_http_server_desc *desc, mk_http_server_t *out_server)

Create a native server; routes may be registered before it is started.

Parameter	Type	Description
desc	const mk_http_server_desc *	Configuration descriptor.
out_server	mk_http_server_t *	Receives the server.

Returns MK_SUCCESS or an error result.

mk_http_server_desc_initfunction

mk_http_server_desc mk_http_server_desc_init(void)

Return all-interface defaults for 1024 clients, 64-KiB headers, and 16-MiB bodies.

Returns The resulting value.

mk_http_server_portfunction

uint16_t mk_http_server_port(mk_http_server_t server)

Return the server's bound port, including an automatically selected port.

Parameter	Type	Description
server	mk_http_server_t	Value for server.

Returns The resulting value.

mk_http_server_routefunction

mk_result mk_http_server_route(mk_http_server_t server, const mk_http_route_desc *route)

Register a method/path route before the server starts.

Parameter	Type	Description
server	mk_http_server_t	Value for server.
route	const mk_http_route_desc *	Value for route.

Returns MK_SUCCESS or an error result.

mk_http_server_startfunction

mk_result mk_http_server_start(mk_http_server_t server)

Start accepting requests after all middleware and routes are registered.

Parameter	Type	Description
server	mk_http_server_t	Value for server.

Returns MK_SUCCESS or an error result.

mk_http_server_staticfunction

mk_result mk_http_server_static(mk_http_server_t server, const mk_http_static_desc *mount)

Mount a native directory for static HTTP serving.

Parameter	Type	Description
server	mk_http_server_t	Value for server.
mount	const mk_http_static_desc *	Value for mount.

Returns MK_SUCCESS or an error result.

mk_http_server_usefunction

mk_result mk_http_server_use(mk_http_server_t server, mk_http_handler_fn middleware, void *user_data)

Append ordered middleware to a server before it starts.

Parameter	Type	Description
server	mk_http_server_t	Value for server.
middleware	mk_http_handler_fn	Value for middleware.
user_data	void *	Caller-provided context.

Returns MK_SUCCESS or an error result.

mk_http_server_validfunction

bool mk_http_server_valid(mk_http_server_t handle)

Return whether an HTTP server handle is nonzero.

Parameter	Type	Description
handle	mk_http_server_t	Value for handle.

Returns True when the operation succeeds.

Structs

mk_http_eventstruct

HTTP client event delivered by mk_net_poll().

Field	Type	Description
type	mk_http_event_type	Event kind.
request	mk_http_request_t	Request that produced the event.
status_code	int	HTTP status, or zero before a response.
final_url	const char *	URL after redirects.
headers	const mk_http_header *	Response headers for HEADERS/COMPLETE.
header_count	uint32_t	Number of entries in headers.
data	const void *	Body chunk or buffered complete body.
size	size_t	Number of bytes in data.
bytes_received	uint64_t	Decoded response bytes received so far.
content_length	uint64_t	Expected decoded length, or zero if unknown.
result	mk_result	Terminal result for COMPLETE.
error	mk_net_error	Detailed failure for COMPLETE.

mk_http_headerstruct

Non-owning HTTP header name/value view.

Field	Type	Description
name	const char *	Null-terminated header name.
value	const char *	Null-terminated header value.

mk_http_named_valuestruct

Non-owning decoded name/value view used for query and route parameters.

Field	Type	Description
name	const char *	Decoded parameter name.
value	const char *	Decoded parameter value.

mk_http_reply_handlestruct

Generational handle for a server response, including deferred responses.

Field	Type	Description
id	uint32_t	Opaque identifier; zero is invalid.

mk_http_request_descstruct

Descriptor for one asynchronous HTTP or HTTPS request.

Field	Type	Description
method	mk_http_method	Request method; ANY is invalid here.
custom_method	const char *	HTTP token used when method is CUSTOM.
url	const char *	Required absolute http:// or https:// URL.
headers	const mk_http_header *	Optional request headers, copied on submit.
header_count	uint32_t	Number of request headers.
body	const void *	Optional request body, copied on submit.
body_size	size_t	Request body size in bytes.
response_mode	mk_http_response_mode	Buffered or streamed response delivery.
connect_timeout_ms	uint32_t	Native connect timeout; zero uses 10 seconds.
total_timeout_ms	uint32_t	Whole-request timeout; zero disables it.
max_redirects	uint32_t	Native redirect limit; browsers use UA policy.
max_buffered_body_bytes	size_t	Decoded-body limit; zero uses 64 MiB.
allow_https_downgrade	bool	Permit redirects from HTTPS to HTTP.
automatic_decompression	bool	Decode gzip/deflate; required on web.
has_range	bool	Add a single HTTP byte Range header.
range_first	uint64_t	Inclusive first requested byte.
range_last	uint64_t	Inclusive last byte, or UINT64_MAX for open end.
tls	const mk_tls_client_config *	Optional native TLS trust configuration.
callback	mk_http_event_fn	Required response callback.
user_data	void *	Opaque value passed to callback.

mk_http_request_handlestruct

Generational handle for an asynchronous HTTP client request.

Field	Type	Description
id	uint32_t	Opaque identifier; zero is invalid.

mk_http_request_viewstruct

Read-only server request view valid only during its handler callback.

Field	Type	Description
server	mk_http_server_t	Receiving server.
reply	mk_http_reply_t	Reply handle retained by DEFER.
method	mk_http_method	Parsed request method.
custom_method	const char *	Method token when method is CUSTOM.
path	const char *	URL path without the query string.
query	const char *	Raw query string without '?
headers	const mk_http_header *	Request headers.
header_count	uint32_t	Number of request headers.
query_params	const mk_http_named_value *	Percent-decoded query parameters.
query_param_count	uint32_t	Number of query parameters.
params	const mk_http_named_value *	Matched :parameter and *wildcard values.
param_count	uint32_t	Number of matched route parameters.
body	const void *	Complete request body.
body_size	size_t	Request body size in bytes.
remote	mk_net_address	Remote numeric address.

mk_http_response_descstruct

Complete response used by mk_http_reply_send().

Field	Type	Description
status_code	int	HTTP status; zero selects 200.
headers	const mk_http_header *	Response headers copied by the call.
header_count	uint32_t	Number of response headers.
body	const void *	Response body copied by the call.
body_size	size_t	Response body size in bytes.

mk_http_route_descstruct

Method/path route registered before an HTTP server starts.

Field	Type	Description
method	mk_http_method	Method to match, including ANY or CUSTOM.
custom_method	const char *	Token matched when method is CUSTOM.
path	const char *	Absolute pattern with :params or trailing *wildcard.
handler	mk_http_handler_fn	Required route callback.
user_data	void *	Opaque value passed to handler.

mk_http_server_descstruct

Descriptor for a native HTTP or HTTPS server.

Field	Type	Description
bind_address	const char *	Local address; NULL means all IPv4 interfaces.
port	uint16_t	Local port; zero selects an available port.
max_connections	uint32_t	Connection limit; zero uses 1024.
max_header_bytes	size_t	Header limit; zero uses 64 KiB.
max_body_bytes	size_t	Body limit; zero uses 16 MiB.
request_timeout_ms	uint32_t	Deferred-reply deadline; zero uses default.
tls	const mk_tls_server_config *	NULL for HTTP, credentials for HTTPS.

mk_http_server_handlestruct

Generational handle for a native HTTP server.

Field	Type	Description
id	uint32_t	Opaque identifier; zero is invalid.

mk_http_static_descstruct

Static-file mount registered before an HTTP server starts.

Field	Type	Description
url_prefix	const char *	URL prefix such as "/assets".
root_path	const char *	Native filesystem directory served by the mount.
index_file	const char *	Optional file served for directory requests.

Enums

mk_http_event_typeenum

HTTP client event kind.

Value	Description
MK_HTTP_EVENT_HEADERS	Status and response headers are available.
MK_HTTP_EVENT_DATA	A streamed response-body chunk is available.
MK_HTTP_EVENT_COMPLETE	Request finished, failed, or was cancelled.

mk_http_handler_resultenum

Control value returned by HTTP middleware and route handlers.

Value	Description
MK_HTTP_HANDLER_NEXT	Continue middleware/routing.
MK_HTTP_HANDLER_RESPOND	Send the response writer immediately.
MK_HTTP_HANDLER_DEFER	Retain request->reply for a later response.

mk_http_methodenum

HTTP request method used by clients and server routes.

Value	Description
MK_HTTP_METHOD_ANY	Match any method in a server route; not valid for clients.
MK_HTTP_METHOD_GET	GET.
MK_HTTP_METHOD_HEAD	HEAD.
MK_HTTP_METHOD_POST	POST.
MK_HTTP_METHOD_PUT	PUT.
MK_HTTP_METHOD_PATCH	PATCH.
MK_HTTP_METHOD_DELETE	DELETE.
MK_HTTP_METHOD_OPTIONS	OPTIONS.
MK_HTTP_METHOD_CUSTOM	Token supplied through custom_method.

mk_http_response_modeenum

HTTP client response delivery mode.

Value	Description
MK_HTTP_RESPONSE_BUFFERED	Deliver the complete body with COMPLETE.
MK_HTTP_RESPONSE_STREAM	Deliver body chunks as DATA events.

Typedefs

mk_http_eventtypedef

typedef struct mk_http_event mk_http_event

HTTP client event delivered by mk_net_poll().

mk_http_event_fntypedef

typedef void(*) mk_http_event_fn(const mk_http_event *event, void *user_data)

HTTP client callback invoked by mk_net_poll() on the owner thread.

mk_http_event_typetypedef

typedef enum mk_http_event_type mk_http_event_type

HTTP client event kind.

mk_http_handler_fntypedef

typedef mk_http_handler_result(*) mk_http_handler_fn(const mk_http_request_view *request, mk_http_response_writer *response, void *user_data)

Native HTTP middleware or route callback.

mk_http_handler_resulttypedef

typedef enum mk_http_handler_result mk_http_handler_result

Control value returned by HTTP middleware and route handlers.

mk_http_headertypedef

typedef struct mk_http_header mk_http_header

Non-owning HTTP header name/value view.

mk_http_methodtypedef

typedef enum mk_http_method mk_http_method

HTTP request method used by clients and server routes.

mk_http_named_valuetypedef

typedef struct mk_http_named_value mk_http_named_value

Non-owning decoded name/value view used for query and route parameters.

mk_http_reply_ttypedef

typedef struct mk_http_reply_handle mk_http_reply_t

Generational handle for a server response, including deferred responses.

mk_http_request_desctypedef

typedef struct mk_http_request_desc mk_http_request_desc

Descriptor for one asynchronous HTTP or HTTPS request.

mk_http_request_ttypedef

typedef struct mk_http_request_handle mk_http_request_t

Generational handle for an asynchronous HTTP client request.

mk_http_request_viewtypedef

typedef struct mk_http_request_view mk_http_request_view

Read-only server request view valid only during its handler callback.

mk_http_response_desctypedef

typedef struct mk_http_response_desc mk_http_response_desc

Complete response used by mk_http_reply_send().

mk_http_response_modetypedef

typedef enum mk_http_response_mode mk_http_response_mode

HTTP client response delivery mode.

mk_http_response_writertypedef

typedef struct mk_http_response_writer mk_http_response_writer

Opaque response builder valid only during a server handler callback.

mk_http_route_desctypedef

typedef struct mk_http_route_desc mk_http_route_desc

Method/path route registered before an HTTP server starts.

mk_http_server_desctypedef

typedef struct mk_http_server_desc mk_http_server_desc

Descriptor for a native HTTP or HTTPS server.

mk_http_server_ttypedef

typedef struct mk_http_server_handle mk_http_server_t

Generational handle for a native HTTP server.

mk_http_static_desctypedef

typedef struct mk_http_static_desc mk_http_static_desc

Static-file mount registered before an HTTP server starts.

Macros

MK_HTTP_REPLY_INVALIDdefine

MK_HTTP_REPLY_INVALID

Invalid HTTP reply handle.

MK_HTTP_REQUEST_INVALIDdefine

MK_HTTP_REQUEST_INVALID

Invalid HTTP client request handle.

MK_HTTP_SERVER_INVALIDdefine

MK_HTTP_SERVER_INVALID

Invalid HTTP server handle.