From 78ca383e3c079875ea01c6941f6fc00789a77ecf Mon Sep 17 00:00:00 2001 From: Cory McWilliams Date: Sun, 3 Mar 2024 12:35:10 -0500 Subject: [PATCH] http.h docs. --- src/http.h | 154 +++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 151 insertions(+), 3 deletions(-) diff --git a/src/http.h b/src/http.h index 5de5a6a9..fbfb204f 100644 --- a/src/http.h +++ b/src/http.h @@ -14,38 +14,88 @@ #include #include +/** An HTTP connection. */ typedef struct _tf_http_connection_t tf_http_connection_t; + +/** An HTTP request. */ typedef struct _tf_http_request_t tf_http_request_t; + +/** An HTTP instance. */ typedef struct _tf_http_t tf_http_t; + +/** A TLS context. */ typedef struct _tf_tls_context_t tf_tls_context_t; + +/** A trace instance. */ typedef struct _tf_trace_t tf_trace_t; + +/** An event loop. */ typedef struct uv_loop_s uv_loop_t; +/** +** A callback called when receiving a websocket message. +** @param request The HTTP request. +** @param op_code The type of websocket message. +** @param data The payload. +** @param size The size of the payload in bytes. +*/ typedef void(tf_http_message_callback)(tf_http_request_t* request, int op_code, const void* data, size_t size); + +/** +** A callback called when a request closes. +** @param request The HTTP request. +*/ typedef void(tf_http_close_callback)(tf_http_request_t* request); +/** +** A callback called when an HTTP request is received. +** @param request The HTTP request. +*/ +typedef void(tf_http_callback_t)(tf_http_request_t* request); + +/** +** A callback called when the HTTP instance is destroyed. +** @param user_data User data provided with the callback. +*/ +typedef void(tf_http_cleanup_t)(void* user_data); + +/** +** An HTTP request. +*/ typedef struct _tf_http_request_t { + /** The HTTP instance this request belongs to. */ tf_http_t* http; + /** The HTTP connection associated with this request. */ tf_http_connection_t* connection; + /** True if this is an HTTPS session. */ bool is_tls; + /** The HTTP method of the request (GET/POST/...). */ const char* method; + /** The HTTP request path. */ const char* path; + /** The raw HTTP query string. */ const char* query; + /** The HTTP request body. */ void* body; + /** The length of the HTTP request body. */ size_t content_length; + /** Header storage. Can also be accessed with tf_http_request_get_header(). */ struct phr_header* headers; + /** The number of headers stored. */ int headers_count; + /** A callback to be called when receiving a websocket message. */ tf_http_message_callback* on_message; + /** A callback to be called when the connection is closed. */ tf_http_close_callback* on_close; + /** Extra storage for user data. */ void* context; + /** User data available to callbacks. */ void* user_data; + /** The number of times tf_http_request_ref() has been called without tf_http_request_unref(). */ int ref_count; } tf_http_request_t; -typedef void(tf_http_callback_t)(tf_http_request_t* request); -typedef void(tf_http_cleanup_t)(void* user_data); - /** ** Create an HTTP server using the given libuv loop. ** @param loop A libuv loop to use. @@ -53,22 +103,120 @@ typedef void(tf_http_cleanup_t)(void* user_data); */ tf_http_t* tf_http_create(uv_loop_t* loop); +/** +** Register a trace instance with the HTTP instance to record the begin and end +** time of request handlers. +** @param http The HTTP instance to trace. +** @param trace The trace instance to use, or NULL to disable. +*/ void tf_http_set_trace(tf_http_t* http, tf_trace_t* trace); + +/** +** Begin listening for HTTP requests on a new port. May be called multiple +** times to listen on multiple ports. +** @param http The HTTP instance. +** @param port The port on which to listen, or 0 to assign a free port. +** @param tls An optional TLS context to use for HTTPS requests. +** @param cleanup A function called when the HTTP instance is being cleaned up. +** @param user_data User data passed to the cleanup callback. +** @return The port number on which the HTTP instance is now listening. +*/ int tf_http_listen(tf_http_t* http, int port, tf_tls_context_t* tls, tf_http_cleanup_t* cleanup, void* user_data); + +/** +** Add an HTTP request handler. +** @param http The HTTP instance. +** @param pattern The prefix that the path of incoming requests must match to use this handler. +** @param callback The function to be called to handle the request. +** @param cleanup A function to be called when the request is complete. +** @param user_data User data to pass to the callbacks. +*/ void tf_http_add_handler(tf_http_t* http, const char* pattern, tf_http_callback_t* callback, tf_http_cleanup_t* cleanup, void* user_data); + +/** +** Respond to an HTTP request. +** @param request The request. +** @param status The HTTP status with which to respond. +** @param headers Headers to include in the response. Content-Length will be added internally. +** @param headers_count The number of headers. The headers array must have +** twice as many entries as this value, since it is both keys and values. +** @param body The response body or NULL. +** @param content_length The length of the response body. +*/ void tf_http_respond(tf_http_request_t* request, int status, const char** headers, int headers_count, const void* body, size_t content_length); + +/** +** Get the request body content. +** @param request An incoming request. +** @param out_data The request body content. Valid until the request is completed. +** @return The size of the request body content. +*/ size_t tf_http_get_body(const tf_http_request_t* request, const void** out_data); + +/** +** Destroy an HTTP instance. +** @param http The HTTP instance. +*/ void tf_http_destroy(tf_http_t* http); +/** +** Set instance-wide HTTP user data and a callback to clean it up. +** @param http The HTTP instance. +** @param user_data The user data. +** @param cleanup The cleanup callback. +*/ void tf_http_set_user_data(tf_http_t* http, void* user_data, tf_http_cleanup_t* cleanup); + +/** +** Get HTTP instance user data previous set with tf_http_set_user_data(). +** @param http The HTTP instance. +** @return The user data. +*/ void* tf_http_get_user_data(tf_http_t* http); +/** +** Increment a requests refcount to keep it around after its callback. +** tf_http_respond() may be called at a later time, and tf_http_request_unref() +** must eventually be called in order to not leak the request. +** @param request The request to retain. +*/ void tf_http_request_ref(tf_http_request_t* request); + +/** +** Decrement a requests refcount. tf_http_request_ref() must have been previously called. +** @param request The request. +*/ void tf_http_request_unref(tf_http_request_t* request); + +/** +** Get the value of a header from an HTTP request. +** @param request The request. +** @param name The header key. Matched case insensitively. +** @return The value or NULL. +*/ const char* tf_http_request_get_header(tf_http_request_t* request, const char* name); + +/** +** Send a websocket message. +** @param request The HTTP request which was previously updated to a websocket +** session with tf_http_request_websocket_upgrade(). +** @param data The message data. +** @param size The size of data. +*/ void tf_http_request_send(tf_http_request_t* request, const void* data, size_t size); + +/** +** Upgrade an HTTP request to a websocket session. +** @param request The HTTP request. +*/ void tf_http_request_websocket_upgrade(tf_http_request_t* request); +/** +** Get standard HTTP status text for common HTTP statuses. 200 = "OK", 404 = +** "File not found", etc. +** @param status The HTTP status. +** @return The status text or NULL. +*/ const char* tf_http_status_text(int status); /** @} */