http.h File Reference

http.h interface. More...

#include <cwist/sstring.h>
#include <cwist/err/cwist_err.h>
#include <cwist/query.h>
#include <stdint.h>
#include <netinet/in.h>
#include <sys/socket.h>

Include dependency graph for http.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes
struct	cwist_http_header_node
	Linked list for headers to handle multiple headers easily. More...
struct	cwist_http_request
struct	cwist_http_response
	HTTP Response Object. Supports standard string body or Zero-Copy pointer body. More...
struct	cwist_server_config

Macros
#define	CWIST_HTTP_MAX_HEADER_SIZE   (8 * 1024)
#define	CWIST_HTTP_MAX_BODY_SIZE   (10 * 1024 * 1024)
#define	CWIST_HTTP_READ_BUFFER_SIZE   (16 * 1024)
#define	CWIST_HTTP_TIMEOUT_MS   30000

Typedefs
typedef enum cwist_http_method_t	cwist_http_method_t
typedef enum cwist_http_status_t	cwist_http_status_t
typedef enum cwist_http_parse_error_t	cwist_http_parse_error_t
	Failure reason reported by the request receive APIs.
typedef struct cwist_http_header_node	cwist_http_header_node
	Linked list for headers to handle multiple headers easily.
typedef struct cwist_http_request	cwist_http_request
typedef struct cwist_http_response	cwist_http_response

Enumerations
enum	cwist_http_method_t {   CWIST_HTTP_GET , CWIST_HTTP_POST , CWIST_HTTP_PUT , CWIST_HTTP_DELETE ,   CWIST_HTTP_PATCH , CWIST_HTTP_HEAD , CWIST_HTTP_OPTIONS , CWIST_HTTP_UNKNOWN }
enum	cwist_http_status_t {   CWIST_HTTP_OK = 200 , CWIST_HTTP_CREATED = 201 , CWIST_HTTP_NO_CONTENT = 204 , CWIST_HTTP_BAD_REQUEST = 400 ,   CWIST_HTTP_UNAUTHORIZED = 401 , CWIST_HTTP_FORBIDDEN = 403 , CWIST_HTTP_NOT_FOUND = 404 , CWIST_HTTP_INTERNAL_ERROR = 500 ,   CWIST_HTTP_NOT_IMPLEMENTED = 501 }
enum	cwist_http_parse_error_t {   CWIST_HTTP_PARSE_OK = 0 , CWIST_HTTP_PARSE_EOF , CWIST_HTTP_PARSE_MALFORMED , CWIST_HTTP_PARSE_HEADER_OVERFLOW ,   CWIST_HTTP_PARSE_BODY_TOO_LARGE , CWIST_HTTP_PARSE_TE_UNSUPPORTED , CWIST_HTTP_PARSE_EXPECT_FAILED }
	Failure reason reported by the request receive APIs. More...

Functions
Request Lifecycle
— API Functions —
cwist_http_request *	cwist_http_request_create (void)
	Create a new HTTP request object.
void	cwist_http_request_destroy (cwist_http_request *req)
	Destroy an HTTP request object.
cwist_http_request *	cwist_http_parse_request (const char *raw_request)
	Parse a raw HTTP request string.
cwist_http_request *	cwist_http_receive_request (int client_fd, char *read_buf, size_t buf_size, size_t *buf_len, cwist_http_parse_error_t *err_out)
	Receive and parse an HTTP request from a socket.
void	cwist_http_send_error_response (int fd, int status, const char *msg)
	Send a minimal error response (Connection: close) for a failed request.
Response Lifecycle
cwist_http_response *	cwist_http_response_create (void)
	Create a new HTTP response object.
void	cwist_http_response_destroy (cwist_http_response *res)
	Destroy an HTTP response object.
cwist_sstring *	cwist_http_stringify_response (cwist_http_response *res)
	Serialize a response to a string.
cwist_error_t	cwist_http_send_response (int client_fd, cwist_http_response *res)
	Send a response over a socket.
cwist_error_t	cwist_http_send_response_head (int client_fd, cwist_http_response *res)
	Send only the status line and headers (HEAD replies).
size_t	cwist_http_serialize_headers (cwist_http_response *res, char *buf, size_t buf_size)
	Serialize only the status line and headers into a caller buffer.
Header Manipulation
cwist_error_t	cwist_http_header_add (cwist_http_header_node **head, const char *key, const char *value)
	Add a header to the list.
char *	cwist_http_header_get (cwist_http_header_node *head, const char *key)
	Find a header value by key.
void	cwist_http_response_add_security_headers (cwist_http_response *res)
	Add default security headers (CSP, X-Frame-Options, etc.) if missing.
void	cwist_http_header_free_all (cwist_http_header_node *head)
	Free all headers.
Helpers
const char *	cwist_http_method_to_string (cwist_http_method_t method)
	Convert method enum to string.
cwist_http_method_t	cwist_http_string_to_method (const char *method_str)
	Convert method string to enum.

TCP Socket Helpers
typedef struct cwist_server_config	cwist_server_config
const int	CWIST_CREATE_SOCKET_FAILED
const int	CWIST_HTTP_UNAVAILABLE_ADDRESS
const int	CWIST_HTTP_BIND_FAILED
const int	CWIST_HTTP_SETSOCKOPT_FAILED
const int	CWIST_HTTP_LISTEN_FAILED
int	cwist_make_socket_ipv4 (struct sockaddr_in *sockv4, const char *address, uint16_t port, uint16_t backlog)
	Create an IPv4 socket and bind/listen.
cwist_error_t	cwist_accept_socket (int server_fd, struct sockaddr *sockv4, void(*handler_func)(int client_fd, void *ctx), void *ctx)
	Accept sockets and invoke a handler callback.
cwist_error_t	cwist_http_server_loop (int server_fd, cwist_server_config *config, void(*handler)(int, void *), void *ctx)
	Run the main HTTP accept loop using the configured concurrency strategy.
int	headers_have_content_length (cwist_http_header_node *headers)
	Detect whether a header list already defines Content-Length.

Detailed Description

http.h interface.

Definition in file http.h.

Macro Definition Documentation

CWIST_HTTP_MAX_BODY_SIZE

#define CWIST_HTTP_MAX_BODY_SIZE   (10 * 1024 * 1024)

Definition at line 41 of file http.h.

CWIST_HTTP_MAX_HEADER_SIZE

#define CWIST_HTTP_MAX_HEADER_SIZE   (8 * 1024)

— Constants and Limits —

Definition at line 40 of file http.h.

CWIST_HTTP_READ_BUFFER_SIZE

#define CWIST_HTTP_READ_BUFFER_SIZE   (16 * 1024)

Definition at line 42 of file http.h.

CWIST_HTTP_TIMEOUT_MS

#define CWIST_HTTP_TIMEOUT_MS   30000

Definition at line 43 of file http.h.

Typedef Documentation

cwist_http_header_node

typedef struct cwist_http_header_node cwist_http_header_node

Linked list for headers to handle multiple headers easily.

— Structures —

cwist_http_method_t

typedef enum cwist_http_method_t cwist_http_method_t

— Enums —

cwist_http_parse_error_t

typedef enum cwist_http_parse_error_t cwist_http_parse_error_t

Failure reason reported by the request receive APIs.

cwist_http_request

typedef struct cwist_http_request cwist_http_request

cwist_http_response

typedef struct cwist_http_response cwist_http_response

cwist_http_status_t

typedef enum cwist_http_status_t cwist_http_status_t

cwist_server_config

typedef struct cwist_server_config cwist_server_config

Enumeration Type Documentation

cwist_http_method_t

enum cwist_http_method_t

— Enums —

Enumerator
CWIST_HTTP_GET
CWIST_HTTP_POST
CWIST_HTTP_PUT
CWIST_HTTP_DELETE
CWIST_HTTP_PATCH
CWIST_HTTP_HEAD
CWIST_HTTP_OPTIONS
CWIST_HTTP_UNKNOWN

Definition at line 16 of file http.h.

cwist_http_parse_error_t

enum cwist_http_parse_error_t

Failure reason reported by the request receive APIs.

Enumerator
CWIST_HTTP_PARSE_OK
CWIST_HTTP_PARSE_EOF
CWIST_HTTP_PARSE_MALFORMED
CWIST_HTTP_PARSE_HEADER_OVERFLOW
CWIST_HTTP_PARSE_BODY_TOO_LARGE
CWIST_HTTP_PARSE_TE_UNSUPPORTED
CWIST_HTTP_PARSE_EXPECT_FAILED

Definition at line 46 of file http.h.

cwist_http_status_t

enum cwist_http_status_t

Enumerator
CWIST_HTTP_OK
CWIST_HTTP_CREATED
CWIST_HTTP_NO_CONTENT
CWIST_HTTP_BAD_REQUEST
CWIST_HTTP_UNAUTHORIZED
CWIST_HTTP_FORBIDDEN
CWIST_HTTP_NOT_FOUND
CWIST_HTTP_INTERNAL_ERROR
CWIST_HTTP_NOT_IMPLEMENTED

Definition at line 27 of file http.h.

Function Documentation

cwist_accept_socket()

cwist_error_t cwist_accept_socket	(	int	server_fd,
		struct sockaddr *	sockv4,
		void(*)(int client_fd, void *ctx)	handler_func,
		void *	ctx
	)

Accept sockets and invoke a handler callback.

cwist_http_header_add()

cwist_error_t cwist_http_header_add	(	cwist_http_header_node **	head,
		const char *	key,
		const char *	value
	)

Add a header to the list.

Returns

INT16 0 on success; INT16 -1 when head is NULL or key/value contains CR or LF (nothing is added); a JSON error on allocation failure.

Add a header to the list.

Parameters

head	Header-list head pointer to update.
key	Header name to store.
value	Header value to store.

Returns

Tagged CWIST error: INT16 0 on success, INT16 -1 when head is NULL or key/value contains CR or LF (nothing is added), or a JSON error on allocation failure.

Definition at line 1861 of file http.c.

References cap, CWIST_ERR_INT16, head, and make_error().

Referenced by cwist_app_healthz(), cwist_async_abort(), cwist_async_respond(), cwist_bind_write_error_response(), cwist_graphql_serve(), cwist_grpc_set_response(), cwist_grpc_stream_close(), cwist_grpc_stream_set_retry_pushback(), cwist_http2_push_resource(), cwist_https_send_response(), cwist_https_send_response_head(), cwist_metrics_serve_http(), cwist_mw_cors_handler(), cwist_mw_request_id_handler(), cwist_sse_response_init(), and cwist_websocket_upgrade_response().

cwist_http_header_free_all()

void cwist_http_header_free_all

(

cwist_http_header_node *

head

)

Free all headers.

Free all headers.

Parameters

head	Head of the header linked list.

Definition at line 2006 of file http.c.

References cap, cwist_free(), cwist_sstring_destroy(), head, and cwist_http_header_node::next.

Referenced by cwist_http_client_request().

cwist_http_header_get()

char * cwist_http_header_get	(	cwist_http_header_node *	head,
		const char *	key
	)

Find a header value by key.

Returns

Raw char* for convenience, NULL if not found.

Find a header value by key.

Parameters

head	Head of the header linked list.
key	Header name to search for.

Returns

Raw header value string, or NULL when absent.

Definition at line 1880 of file http.c.

References cap, cwist_sstring::data, head, and cwist_http_header_node::value.

Referenced by cwist_assets_respond(), cwist_http3_push_resource(), cwist_https_send_response(), cwist_https_send_response_head(), cwist_mw_request_id_handler(), cwist_session_start(), and cwist_websocket_upgrade_response().

cwist_http_method_to_string()

const char * cwist_http_method_to_string

(

cwist_http_method_t

method

)

Convert method enum to string.

Convert method enum to string.

Parameters

method

HTTP method enum value.

Returns

Static string name for the method.

Definition at line 1554 of file http.c.

References CWIST_HTTP_CONNECT, CWIST_HTTP_DELETE, CWIST_HTTP_GET, CWIST_HTTP_HEAD, CWIST_HTTP_OPTIONS, CWIST_HTTP_PATCH, CWIST_HTTP_POST, and CWIST_HTTP_PUT.

Referenced by cwist_http_client_request().

cwist_http_parse_request()

cwist_http_request * cwist_http_parse_request

(

const char *

raw_request

)

Parse a raw HTTP request string.

Parse a raw HTTP request string.

Returns

Parsed request, or NULL when no header terminator exists.

Definition at line 4412 of file http.c.

References cap.

Referenced by cwist_https_receive_request().

cwist_http_receive_request()

cwist_http_request * cwist_http_receive_request	(	int	client_fd,
		char *	read_buf,
		size_t	buf_size,
		size_t *	buf_len,
		cwist_http_parse_error_t *	err_out
	)

Receive and parse an HTTP request from a socket.

Receive and parse an HTTP request from a socket.

Bounds the header read by CWIST_HTTP_HEADERS_TIMEOUT_MS, answers a validated Expect: 100-continue, then completes the body per Content-Length or chunked framing. Leftover pipelined bytes are compacted into read_buf and *buf_len is updated.

Returns

Parsed request, or NULL with *err_out set (defaults to CWIST_HTTP_PARSE_EOF).

Definition at line 4722 of file http.c.

References cwist_http_request::body, cap, cwist_http_request::content_length, cwist_alloc(), cwist_free(), CWIST_HTTP_HEADERS_TIMEOUT_MS, cwist_http_live_idle_enter(), cwist_http_live_idle_leave(), CWIST_HTTP_MAX_BODY_SIZE, CWIST_HTTP_PARSE_BODY_TOO_LARGE, CWIST_HTTP_PARSE_EOF, CWIST_HTTP_PARSE_HEADER_OVERFLOW, CWIST_HTTP_PARSE_MALFORMED, CWIST_HTTP_PARSE_OK, cwist_http_request_destroy(), CWIST_HTTP_TIMEOUT_MS, CWIST_LOG_WARN, CWIST_METRIC_HTTP_HEADER_OVERFLOW, cwist_metric_inc(), cwist_metrics_registry(), cwist_sstring_adopt_len(), cwist_sstring_create(), cwist_sstring_destroy(), cwist_http_request::expect_100_seen, and cwist_http_request::te_chunked_seen.

Referenced by cwist_app_http_handler().

cwist_http_request_create()

cwist_http_request * cwist_http_request_create

(

void

)

Create a new HTTP request object.

Create a new HTTP request object.

Returns

Newly allocated request, or NULL on allocation failure.

Definition at line 2056 of file http.c.

References cwist_http_request::app, cwist_http_request::arena, cwist_http_request::async_conn, cwist_http_request::body, cap, cwist_http_request::client_fd, cwist_http_request::content_length, cwist_arena_create(), cwist_arena_destroy(), CWIST_ENDPOINT_DEFAULT, CWIST_HTTP_GET, cwist_sstring_borrow(), cwist_http_request::db, cwist_http_request::endpoint_opts, cwist_http_request::flash, cwist_http_request::h2_queue, cwist_http_request::headers, cwist_http_request::https_conn, cwist_http_request::keep_alive, cwist_http_request::method, cwist_http_request::path, cwist_http_request::path_params, cwist_http_request::private_data, cwist_http_request::query, cwist_http_request::query_params, cwist_http_request::stream_id, cwist_http_request::upgraded, and cwist_http_request::version.

cwist_http_request_destroy()

void cwist_http_request_destroy

(

cwist_http_request *

req

)

Destroy an HTTP request object.

Destroy an HTTP request object.

Parameters

req	Request object to destroy.

Definition at line 2180 of file http.c.

References cwist_http_request::arena, cwist_http_request::body, cwist_http_request::csrf_token, cwist_arena_destroy(), cwist_arena_owns(), cwist_free(), cwist_http_header_free_all(), cwist_query_map_destroy(), cwist_session_destroy(), cwist_sstring_destroy(), cwist_http_request::flash, cwist_http_request::headers, cwist_http_request::path, cwist_http_request::path_params, cwist_http_request::query, cwist_http_request::query_params, cwist_http_request::session, and cwist_http_request::version.

Referenced by cwist_app_dispatch_memory(), cwist_app_dispatch_stream(), cwist_h2_async_queue_enqueue(), and cwist_https_receive_request().

cwist_http_response_add_security_headers()

void cwist_http_response_add_security_headers

(

cwist_http_response *

res

)

Add default security headers (CSP, X-Frame-Options, etc.) if missing.

Add default security headers (CSP, X-Frame-Options, etc.) if missing.

Safe to call for both HTTP and HTTPS responses. HSTS is intentionally omitted here because RFC 6797 section 7.2 forbids sending it over plain HTTP; browsers ignore it on non-TLS connections anyway. Use cwist_http_response_add_hsts() from your HTTPS handler to add it there.

Parameters

res	Response object to populate.

Definition at line 1935 of file http.c.

References cwist_http_response::arena, cwist_http_header_get(), and cwist_http_response::headers.

cwist_http_response_create()

cwist_http_response * cwist_http_response_create

(

void

)

Create a new HTTP response object.

Create a new HTTP response object.

Returns

Newly allocated response, or NULL on failure.

Definition at line 2291 of file http.c.

References cap, cwist_arena_create(), and cwist_arena_destroy().

Referenced by cwist_app_dispatch_memory(), cwist_app_dispatch_stream(), cwist_http_client_request(), and cwist_websocket_upgrade().

cwist_http_response_destroy()

void cwist_http_response_destroy

(

cwist_http_response *

res

)

Destroy an HTTP response object.

Destroy an HTTP response object.

Parameters

res	Response object to destroy.

Definition at line 2315 of file http.c.

References cwist_http_response::alt_svc, cwist_http_response::arena, cwist_http_response::arena_borrowed, cwist_http_response::body, cap, cwist_arena_destroy(), cwist_arena_owns(), cwist_async_forget_response(), cwist_free(), cwist_http_header_free_all(), cwist_sstring_destroy(), cwist_http_response::headers, cwist_http_response::status_text, cwist_http_response::stream_buf, and cwist_http_response::version.

Referenced by cwist_app_dispatch_memory(), cwist_app_dispatch_stream(), cwist_h2_async_queue_enqueue(), cwist_http2_push_resource(), cwist_http2_serve_connection_ex(), cwist_http3_client_request(), and cwist_websocket_upgrade().

cwist_http_send_error_response()

void cwist_http_send_error_response	(	int	fd,
		int	status,
		const char *	msg
	)

Send a minimal error response (Connection: close) for a failed request.

Send a minimal error response (Connection: close) for a failed request.

Parameters

fd	Connected client socket descriptor.
status	HTTP status code (reason phrase is derived from it).
msg	Plain-text body; NULL falls back to the reason phrase.

Definition at line 4046 of file http.c.

References cap, cwist_http_status_reason(), and MSG_DONTWAIT.

cwist_http_send_response()

cwist_error_t cwist_http_send_response	(	int	client_fd,
		cwist_http_response *	res
	)

Send a response over a socket.

Send a response over a socket.

Parameters

client_fd	Connected client socket descriptor.
res	Response object to send.

Returns

Tagged CWIST error describing success or transmission failure.

Definition at line 2878 of file http.c.

References cwist_http_response::body, cap, CWIST_ERR_INT16, CWIST_HTTP_MAX_HEADER_SIZE, cwist_tcp_cork_enabled(), cwist_sstring::data, cwist_http_response::is_ptr_body, make_error(), MSG_DONTWAIT, cwist_http_response::ptr_body, cwist_http_response::ptr_body_len, cwist_sstring::size, and cwist_http_response::use_file_stream.

Referenced by cwist_websocket_upgrade().

cwist_http_send_response_head()

cwist_error_t cwist_http_send_response_head	(	int	client_fd,
		cwist_http_response *	res
	)

Send only the status line and headers (HEAD replies).

Send only the status line and headers (HEAD replies).

Definition at line 2961 of file http.c.

References cap, CWIST_ERR_INT16, CWIST_HTTP_MAX_HEADER_SIZE, make_error(), and MSG_DONTWAIT.

cwist_http_serialize_headers()

size_t cwist_http_serialize_headers	(	cwist_http_response *	res,
		char *	buf,
		size_t	buf_size
	)

Serialize only the status line and headers into a caller buffer.

Returns

Number of bytes written.

Serialize only the status line and headers into a caller buffer.

Non-static wrapper around serialize_headers() so the TLS send path can stream headers and body separately instead of materializing one blob.

Parameters

res	Response object to serialize.
buf	Destination buffer for the header block.
buf_size	Total capacity of buf in bytes.

Returns

Number of bytes written into the buffer.

Definition at line 2609 of file http.c.

References cap.

Referenced by cwist_app_dispatch_stream(), cwist_https_send_response(), and cwist_https_send_response_head().

cwist_http_server_loop()

cwist_error_t cwist_http_server_loop	(	int	server_fd,
		cwist_server_config *	config,
		void(*)(int, void *)	handler,
		void *	ctx
	)

Run the main HTTP accept loop using the configured concurrency strategy.

Parameters

server_fd	Listening server socket.
config	Server concurrency configuration flags.
handler	Callback that handles one accepted client.
ctx	Opaque callback context.

Returns

Tagged CWIST error describing success or failure.

Definition at line 5590 of file http.c.

References cap, count, cwist_accept_socket(), CWIST_ERR_INT16, cwist_http_pool_destroy(), cwist_http_pool_init_mode(), cwist_http_pool_submit(), g_cwist_running, HTTP_ACCEPT_WAIT_MS, make_error(), cwist_server_config::use_epoll, cwist_server_config::use_forking, and cwist_server_config::use_threading.

cwist_http_string_to_method()

cwist_http_method_t cwist_http_string_to_method

(

const char *

method_str

)

Convert method string to enum.

Convert method string to enum.

Returns

Matching method, or CWIST_HTTP_UNKNOWN for NULL/unrecognized input.

Definition at line 1629 of file http.c.

References cap, cwist_http_string_to_method_len(), and CWIST_HTTP_UNKNOWN.

Referenced by cwist_http3_method_is_idempotent().

cwist_http_stringify_response()

cwist_sstring * cwist_http_stringify_response

(

cwist_http_response *

res

)

Serialize a response to a string.

Serialize a response to a string.

Parameters

res	Response object to stringify.

Returns

Heap-allocated response string, or NULL on invalid input.

Definition at line 4099 of file http.c.

References cwist_http_response::body, cap, CWIST_HTTP_MAX_HEADER_SIZE, cwist_sstring_append_len(), cwist_sstring_assign_len(), cwist_sstring_create(), cwist_sstring::data, cwist_http_response::is_ptr_body, cwist_http_response::ptr_body, cwist_http_response::ptr_body_len, and cwist_sstring::size.

cwist_make_socket_ipv4()

int cwist_make_socket_ipv4	(	struct sockaddr_in *	sockv4,
		const char *	address,
		uint16_t	port,
		uint16_t	backlog
	)

Create an IPv4 socket and bind/listen.

Create an IPv4 socket and bind/listen.

Parameters

sockv4	Output sockaddr structure populated for the bind call.
address	IPv4 address string to bind.
port	TCP port to listen on.
backlog	Listen backlog passed to listen(2).

Returns

Listening socket fd on success, or a negative CWIST socket error code.

Definition at line 5361 of file http.c.

References cap, CWIST_CREATE_SOCKET_FAILED, cwist_free(), CWIST_HTTP_BIND_FAILED, CWIST_HTTP_LISTEN_FAILED, CWIST_HTTP_SETSOCKOPT_FAILED, CWIST_HTTP_UNAVAILABLE_ADDRESS, and cwist_reuseport_enabled().

headers_have_content_length()

int headers_have_content_length

(

cwist_http_header_node *

headers

)

Detect whether a header list already defines Content-Length.

Parameters

headers

Header linked list to scan.

Returns

1 when a Content-Length header is present, otherwise 0.

Definition at line 2394 of file http.c.

References cap, and cwist_http_header_node::next.

Variable Documentation

CWIST_CREATE_SOCKET_FAILED

const int CWIST_CREATE_SOCKET_FAILED

extern

Definition at line 1541 of file http.c.

CWIST_HTTP_BIND_FAILED

const int CWIST_HTTP_BIND_FAILED

extern

Definition at line 1543 of file http.c.

CWIST_HTTP_LISTEN_FAILED

const int CWIST_HTTP_LISTEN_FAILED

extern

Definition at line 1545 of file http.c.

CWIST_HTTP_SETSOCKOPT_FAILED

const int CWIST_HTTP_SETSOCKOPT_FAILED

extern

Definition at line 1544 of file http.c.

CWIST_HTTP_UNAVAILABLE_ADDRESS

const int CWIST_HTTP_UNAVAILABLE_ADDRESS

extern

Definition at line 1542 of file http.c.