HTTP Server

Classes
struct	_tf_http_request_t

Typedefs
typedef struct _tf_http_connection_t	tf_http_connection_t
typedef struct _tf_http_request_t	tf_http_request_t
typedef struct _tf_http_t	tf_http_t
typedef struct _tf_tls_context_t	tf_tls_context_t
typedef struct _tf_trace_t	tf_trace_t
typedef struct uv_loop_s	uv_loop_t
typedef void()	tf_http_message_callback(tf_http_request_t *request, int op_code, const void *data, size_t size)
typedef void()	tf_http_close_callback(tf_http_request_t *request)
typedef void()	tf_http_callback_t(tf_http_request_t *request)
typedef void()	tf_http_cleanup_t(void *user_data)

Functions
tf_http_t *	tf_http_create (uv_loop_t *loop)
void	tf_http_set_trace (tf_http_t *http, tf_trace_t *trace)
int	tf_http_listen (tf_http_t *http, int port, bool local_only, tf_tls_context_t *tls, tf_http_cleanup_t *cleanup, void *user_data)
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)
void	tf_http_respond (tf_http_request_t *request, int status, const char **headers, int headers_count, const void *body, size_t content_length)
size_t	tf_http_get_body (const tf_http_request_t *request, const void **out_data)
void	tf_http_destroy (tf_http_t *http)
void	tf_http_set_user_data (tf_http_t *http, void *user_data, tf_http_cleanup_t *cleanup)
void *	tf_http_get_user_data (tf_http_t *http)
void	tf_http_request_ref (tf_http_request_t *request)
void	tf_http_request_unref (tf_http_request_t *request)
const char *	tf_http_request_get_header (tf_http_request_t *request, const char *name)
const char *	tf_http_get_cookie (const char *cookie_header, const char *name)
void	tf_http_request_websocket_send (tf_http_request_t *request, int op_code, const void *data, size_t size)
void	tf_http_request_websocket_upgrade (tf_http_request_t *request)
const char *	tf_http_status_text (int status)
bool	tf_http_pattern_matches (const char *pattern, const char *path)

Detailed Description

This is a HTTP server.

It can listen on multiple ports. It supports IPv4 and IPv6. It handles websocket connections. Requests can be handled immediately or at a later time. It is very bare bones, and that is a feature.

Typedef Documentation

tf_http_callback_t

typedef void() tf_http_callback_t(tf_http_request_t *request)

A callback called when an HTTP request is received.

Parameters

request

The HTTP request.

tf_http_cleanup_t

typedef void() tf_http_cleanup_t(void *user_data)

A callback called when the HTTP instance is destroyed.

Parameters

user_data

User data provided with the callback.

tf_http_close_callback

typedef void() tf_http_close_callback(tf_http_request_t *request)

A callback called when a request closes.

Parameters

request

The HTTP request.

tf_http_connection_t

typedef struct _tf_http_connection_t tf_http_connection_t

An HTTP connection.

tf_http_message_callback

typedef void() tf_http_message_callback(tf_http_request_t *request, int op_code, const void *data, size_t size)

A callback called when receiving a websocket message.

Parameters

request	The HTTP request.
op_code	The type of websocket message.
data	The payload.
size	The size of the payload in bytes.

tf_http_request_t

typedef struct _tf_http_request_t tf_http_request_t

An HTTP request.

tf_http_t

typedef struct _tf_http_t tf_http_t

An HTTP instance.

tf_tls_context_t

typedef struct _tf_tls_context_t tf_tls_context_t

A TLS context.

tf_trace_t

typedef struct _tf_trace_t tf_trace_t

A trace instance.

uv_loop_t

typedef struct uv_loop_s uv_loop_t

An event loop.

Function Documentation

tf_http_add_handler()

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
	)

Add an HTTP request handler.

Parameters

http	The HTTP instance.
pattern	The prefix that the path of incoming requests must match to use this handler.
callback	The function to be called to handle the request.
cleanup	A function to be called when the request is complete.
user_data	User data to pass to the callbacks.

tf_http_create()

tf_http_t * tf_http_create

(

uv_loop_t *

loop

)

Create an HTTP server using the given libuv loop.

Parameters

loop	A libuv loop to use.

Returns

An HTTP server instance.

tf_http_destroy()

void tf_http_destroy

(

tf_http_t *

http

)

Destroy an HTTP instance.

Parameters

http	The HTTP instance.

tf_http_get_body()

size_t tf_http_get_body	(	const tf_http_request_t *	request,
		const void **	out_data
	)

Get the request body content.

Parameters

request	An incoming request.
out_data	The request body content. Valid until the request is completed.

Returns

The size of the request body content.

tf_http_get_cookie()

const char * tf_http_get_cookie	(	const char *	cookie_header,
		const char *	name
	)

Get a cookie value from request headers.

Parameters

cookie_header	The value of the "Cookie" header of the form "name1=value1; name2=value2".
name	The cookie name.

Returns

The cookie value, if found, or NULL. Must be freed with tf_free().

tf_http_get_user_data()

void * tf_http_get_user_data

(

tf_http_t *

http

)

Get HTTP instance user data previous set with tf_http_set_user_data().

Parameters

http	The HTTP instance.

Returns

The user data.

tf_http_listen()

int tf_http_listen	(	tf_http_t *	http,
		int	port,
		bool	local_only,
		tf_tls_context_t *	tls,
		tf_http_cleanup_t *	cleanup,
		void *	user_data
	)

Begin listening for HTTP requests on a new port. May be called multiple times to listen on multiple ports.

Parameters

http	The HTTP instance.
port	The port on which to listen, or 0 to assign a free port.
local_only	Only access connections on localhost, otherwise any address.
tls	An optional TLS context to use for HTTPS requests.
cleanup	A function called when the HTTP instance is being cleaned up.
user_data	User data passed to the cleanup callback.

Returns

The port number on which the HTTP instance is now listening.

tf_http_pattern_matches()

bool tf_http_pattern_matches	(	const char *	pattern,
		const char *	path
	)

Match URL patterns. "*" matches anything, and "{word}" matches [a-zA-Z][a-zA-Z0-9]*".

Parameters

pattern	The pattern to match.
path	The path to test.

Returns

true if the path matches the pattern.

tf_http_request_get_header()

const char * tf_http_request_get_header	(	tf_http_request_t *	request,
		const char *	name
	)

Get the value of a header from an HTTP request.

Parameters

request	The request.
name	The header key. Matched case insensitively.

Returns

The value or NULL.

tf_http_request_ref()

void tf_http_request_ref

(

tf_http_request_t *

request

)

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.

Parameters

request

The request to retain.

tf_http_request_unref()

void tf_http_request_unref

(

tf_http_request_t *

request

)

Decrement a requests refcount. tf_http_request_ref() must have been previously called.

Parameters

request

The request.

tf_http_request_websocket_send()

void tf_http_request_websocket_send	(	tf_http_request_t *	request,
		int	op_code,
		const void *	data,
		size_t	size
	)

Send a websocket message.

Parameters

request	The HTTP request which was previously updated to a websocket session with tf_http_request_websocket_upgrade().
op_code	Websocket op code.
data	The message data.
size	The size of data.

tf_http_request_websocket_upgrade()

void tf_http_request_websocket_upgrade

(

tf_http_request_t *

request

)

Upgrade an HTTP request to a websocket session.

Parameters

request

The HTTP request.

tf_http_respond()

void tf_http_respond	(	tf_http_request_t *	request,
		int	status,
		const char **	headers,
		int	headers_count,
		const void *	body,
		size_t	content_length
	)

Respond to an HTTP request.

Parameters

request	The request.
status	The HTTP status with which to respond.
headers	Headers to include in the response. Content-Length will be added internally.
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.
body	The response body or NULL.
content_length	The length of the response body.

tf_http_set_trace()

void tf_http_set_trace	(	tf_http_t *	http,
		tf_trace_t *	trace
	)

Register a trace instance with the HTTP instance to record the begin and end time of request handlers.

Parameters

http	The HTTP instance to trace.
trace	The trace instance to use, or NULL to disable.

tf_http_set_user_data()

void tf_http_set_user_data	(	tf_http_t *	http,
		void *	user_data,
		tf_http_cleanup_t *	cleanup
	)

Set instance-wide HTTP user data and a callback to clean it up.

Parameters

http	The HTTP instance.
user_data	The user data.
cleanup	The cleanup callback.

tf_http_status_text()

const char * tf_http_status_text

(

int

status

)

Get standard HTTP status text for common HTTP statuses. 200 = "OK", 404 = "File not found", etc.

Parameters

status

The HTTP status.

Returns

The status text or NULL.