HTTP/2 Protocol Definitions for CWIST. More...

#include <cwist/net/http/http.h>
#include <cwist/net/http/https.h>

Include dependency graph for http2.h:

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

Classes
struct	cwist_http2_header

struct	cwist_http2_stream_hooks

struct	cwist_http2_static_header
	HPACK static table entry (RFC 7541 Appendix A). More...

Typedefs
typedef void(*	cwist_http2_request_handler_func) (void user_ctx, cwist_http_request req, cwist_http_response *res)
	Callback function type for handling HTTP/2 requests.

typedef struct cwist_h2_stream	cwist_h2_stream

typedef struct cwist_http2_header	cwist_http2_header

typedef struct cwist_http2_stream_hooks	cwist_http2_stream_hooks

typedef struct cwist_h2_async_queue	cwist_h2_async_queue

typedef struct cwist_http2_static_header	cwist_http2_static_header
	HPACK static table entry (RFC 7541 Appendix A).

Functions
cwist_error_t	cwist_http2_serve_connection_ex (cwist_https_connection conn, void user_ctx, cwist_http2_request_handler_func handler, const cwist_http2_stream_hooks *hooks)
	Serve one HTTP/2 connection until it closes. Verifies the preface, sends our SETTINGS, then runs the frame dispatcher: HEADERS/CONTINUATION, DATA, SETTINGS, PING, WINDOW_UPDATE, RST_STREAM, and GOAWAY, with per-connection DoS budgets and flow control. A session may be parked off its thread (cwist_https_park) and resumed via conn->proto_state; on exit the session is torn down and proto_state cleared.

cwist_error_t	cwist_http2_serve_connection (cwist_https_connection conn, void user_ctx, cwist_http2_request_handler_func handler)
	Starts serving an HTTP/2 connection over an established HTTPS session.

int	cwist_http2_push_resource (cwist_http_request req, const char path, const char content_type, const unsigned char data, size_t data_len)
	Push a resource to the client over HTTP/2 Server Push.

int	cwist_http2_stream_send_headers (cwist_h2_stream stream, int status, const cwist_http2_header headers, size_t header_count, int end_stream)

int	cwist_http2_stream_send_data (cwist_h2_stream stream, const unsigned char data, size_t len)
	Send DATA on a hook-taken stream, honoring flow-control credit. Splits `data` into peer_max_frame_size chunks. When the send window is exhausted the batch buffer is flushed and the calling handler thread parks on the connection's fc_cond until the dispatcher applies WINDOW_UPDATE credit or the stream goes away; credit is re-checked under out_mu before each frame is written.

int	cwist_http2_stream_send_trailers (cwist_h2_stream stream, const cwist_http2_header trailers, size_t trailer_count)

cwist_h2_async_queue *	cwist_h2_async_queue_acquire (cwist_h2_async_queue *q)
	Take an additional reference on the queue (for an in-flight cwist_async handle).

void	cwist_h2_async_queue_release (cwist_h2_async_queue *q)
	Drop a reference on the queue. On the last reference: closes the wake descriptors, destroys the mutex, and frees the queue. Callers must not enqueue after close().

int	cwist_h2_async_queue_enqueue (cwist_h2_async_queue q, uint32_t stream_id, cwist_http_request req, cwist_http_response send, cwist_http_response res, bool send_owned)

int	h2_decode_integer (const unsigned char buf, size_t len, size_t pos, uint8_t prefix_bits, uint32_t *value)
	Decode an HPACK integer.

char *	h2_huffman_decode (const unsigned char src, size_t src_len, size_t out_len)
	Decode an HPACK huffman-encoded string.

char *	h2_decode_string (const unsigned char buf, size_t len, size_t pos)
	Decode an HPACK string (literal or huffman).

const cwist_http2_static_header *	h2_static_header (uint32_t index)
	Resolve an HPACK static table index (1-based); NULL when out of range.

size_t	h2_encode_integer (unsigned char *dst, size_t dst_cap, uint32_t value, uint8_t prefix_bits)
	Encode an HPACK integer; returns bytes written, 0 when dst is too small.

size_t	h2_encode_string (unsigned char dst, size_t dst_cap, const char str)
	Encode an HPACK string (literal, non-huffman); 0 when dst is too small.

Detailed Description

HTTP/2 Protocol Definitions for CWIST.

Definition in file http2.h.

Typedef Documentation

◆ cwist_h2_async_queue

typedef struct cwist_h2_async_queue cwist_h2_async_queue

Definition at line 123 of file http2.h.

◆ cwist_h2_stream

typedef struct cwist_h2_stream cwist_h2_stream

Opaque per-stream handle for hook-driven (e.g. gRPC streaming) I/O.

Definition at line 23 of file http2.h.

◆ cwist_http2_header

typedef struct cwist_http2_header cwist_http2_header

A literal header name/value pair for cwist_http2_stream_send_headers().

◆ cwist_http2_request_handler_func

typedef void(* cwist_http2_request_handler_func) (void *user_ctx, cwist_http_request *req, cwist_http_response *res)

Callback function type for handling HTTP/2 requests.

Parameters

user_ctx	Opaque pointer for user context.
req	Parsed HTTP request object.
res	HTTP response object to be populated by the handler.

Definition at line 19 of file http2.h.

◆ cwist_http2_static_header

typedef struct cwist_http2_static_header cwist_http2_static_header

HPACK static table entry (RFC 7541 Appendix A).

◆ cwist_http2_stream_hooks

typedef struct cwist_http2_stream_hooks cwist_http2_stream_hooks

Optional per-connection hooks that let a higher layer (gRPC) take over individual streams: inbound DATA is delivered incrementally instead of being buffered, and the stream emits its own response frames.

Function Documentation

◆ cwist_h2_async_queue_acquire()

cwist_h2_async_queue * cwist_h2_async_queue_acquire ( cwist_h2_async_queue * q )

Take an additional reference on the queue (for an in-flight cwist_async handle).

Parameters

q	Queue to retain; NULL is tolerated.

Returns: q.

Definition at line 316 of file http2.c.

References cap.

Referenced by cwist_async_defer().

◆ cwist_h2_async_queue_enqueue()

int cwist_h2_async_queue_enqueue	(	cwist_h2_async_queue *	q,
		uint32_t	stream_id,
		cwist_http_request *	req,
		cwist_http_response *	send,
		cwist_http_response *	res,
		bool	send_owned
	)

Definition at line 339 of file http2.c.

References cap, cwist_alloc(), cwist_full_gc_enabled(), cwist_gc_scope_disown(), cwist_http_request_destroy(), and cwist_http_response_destroy().

◆ cwist_h2_async_queue_release()

void cwist_h2_async_queue_release ( cwist_h2_async_queue * q )

Drop a reference on the queue. On the last reference: closes the wake descriptors, destroys the mutex, and frees the queue. Callers must not enqueue after close().

Parameters

q	Queue to release; NULL is tolerated.

Definition at line 327 of file http2.c.

References cap, and cwist_free().

◆ cwist_http2_push_resource()

int cwist_http2_push_resource	(	cwist_http_request *	req,
		const char *	path,
		const char *	content_type,
		const unsigned char *	data,
		size_t	data_len
	)

Push a resource to the client over HTTP/2 Server Push.

Sends a PUSH_PROMISE frame on the original request stream, then delivers the pushed response headers and body on a newly allocated server-initiated stream. The caller should ensure HTTP/2 Server Push is enabled on the connection (via SETTINGS_ENABLE_PUSH).

Parameters

req	The current HTTP/2 request (must have stream_id and private_data populated by the HTTP/2 layer).
path	The resource path to push (e.g., "/style.css").
content_type	Optional Content-Type header value (may be NULL).
data	Response body bytes (may be NULL).
data_len	Length of `data`.

Returns: 0 on success, -1 on failure.

Push a resource to the client over HTTP/2 Server Push.

Parameters

req	Request of the stream that triggered the push; its private_data must be the cwist_https_connection.
path	:path for the promised request.
content_type	Optional content-type header value.
data	Body bytes (may be NULL when `data_len` is 0).
data_len	Body length.

Return values

0	Response queued/written successfully.
-1	Invalid arguments, missing Host header, or send failure.

Definition at line 4210 of file http2.c.

References cwist_http_request::arena, cwist_http_response::body, cap, CWIST_HTTP2_FLAG_END_HEADERS, CWIST_HTTP2_MAX_FRAME_SIZE, cwist_http_header_add(), CWIST_HTTP_OK, cwist_http_response_create_in_arena(), cwist_http_response_destroy(), cwist_sstring_assign_len(), cwist_sstring::data, h2_encode_integer(), h2_encode_string(), cwist_http_request::headers, cwist_http_response::headers, cwist_http_header_node::key, cwist_http_header_node::next, cwist_http_request::private_data, cwist_http_response::status_code, cwist_http_request::stream_id, and cwist_http_header_node::value.

◆ cwist_http2_serve_connection()

cwist_error_t cwist_http2_serve_connection	(	cwist_https_connection *	conn,
		void *	user_ctx,
		cwist_http2_request_handler_func	handler
	)

Starts serving an HTTP/2 connection over an established HTTPS session.

Parameters

conn	Pointer to the HTTPS connection that negotiated HTTP/2.
user_ctx	Opaque user context passed to the handler callback.
handler	Function to call when an HTTP/2 stream issues a request.

Returns: cwist_error_t Indicates success or connection error.

Starts serving an HTTP/2 connection over an established HTTPS session.

Parameters

conn	HTTPS connection with a completed TLS (or h2c) handshake.
user_ctx	Opaque context passed to `handler`.
handler	Request handler invoked per stream.

Returns: CWIST_ERR_INT16 with err_i16 0 on orderly close, -1 on setup or preface failure.

Definition at line 3493 of file http2.c.

References cap, and cwist_http2_serve_connection_ex().

◆ cwist_http2_serve_connection_ex()

cwist_error_t cwist_http2_serve_connection_ex	(	cwist_https_connection *	conn,
		void *	user_ctx,
		cwist_http2_request_handler_func	handler,
		const cwist_http2_stream_hooks *	hooks
	)

Serve one HTTP/2 connection until it closes. Verifies the preface, sends our SETTINGS, then runs the frame dispatcher: HEADERS/CONTINUATION, DATA, SETTINGS, PING, WINDOW_UPDATE, RST_STREAM, and GOAWAY, with per-connection DoS budgets and flow control. A session may be parked off its thread (cwist_https_park) and resumed via conn->proto_state; on exit the session is torn down and proto_state cleared.

Parameters

conn	HTTPS connection with a completed TLS (or h2c) handshake.
user_ctx	Opaque context passed to `handler` and the hooks.
handler	Request handler invoked per stream.
hooks	Optional stream-lifetime hooks (may be NULL).

Returns: CWIST_ERR_INT16 with err_i16 0 on orderly close, -1 on argument, allocation, or preface failure.

Definition at line 3573 of file http2.c.

References cap, cwist_alloc(), cwist_async_dispatch_ack(), cwist_async_dispatch_take(), CWIST_DEFER_FREE, CWIST_ERR_INT16, cwist_free(), CWIST_HTTP2_FLAG_ACK, CWIST_HTTP2_FLAG_END_HEADERS, CWIST_HTTP2_FLAG_END_STREAM, CWIST_HTTP2_FLAG_PADDED, CWIST_HTTP2_FLAG_PRIORITY, cwist_http2_flow_control_consume(), cwist_http2_flow_control_receive(), cwist_http2_flow_control_update_rtt(), CWIST_HTTP2_FRAME_CONTINUATION, CWIST_HTTP2_FRAME_DATA, CWIST_HTTP2_FRAME_GOAWAY, CWIST_HTTP2_FRAME_HEADERS, CWIST_HTTP2_FRAME_PING, CWIST_HTTP2_FRAME_PUSH_PROMISE, CWIST_HTTP2_FRAME_RST_STREAM, CWIST_HTTP2_FRAME_SETTINGS, CWIST_HTTP2_FRAME_WINDOW_UPDATE, CWIST_HTTP2_MAX_FRAME_SIZE, CWIST_HTTP2_MAX_WINDOW, cwist_http2_stream_flow_control_consume(), cwist_http2_stream_flow_control_receive(), CWIST_HTTP_MAX_BODY_SIZE, cwist_http_response_create_in_arena(), cwist_http_response_destroy(), cwist_https_conn_idle(), cwist_https_park(), CWIST_HTTPS_PARK_HTTP2, CWIST_LOG_WARN, cwist_seq_assembler_create_limited(), cwist_seq_assembler_feed(), cwist_seq_assembler_get_data(), cwist_seq_chunk_parse(), CWIST_SEQ_HEADER_SIZE, cwist_sstring_append_len(), __prim_cwist_error_t::err_i16, cwist_error_t::error, g_cwist_running, H2_ERR_ENHANCE_YOUR_CALM, H2_ERR_FLOW_CONTROL_ERROR, H2_ERR_FRAME_SIZE_ERROR, H2_ERR_NO_ERROR, H2_ERR_PROTOCOL_ERROR, H2_ERR_REFUSED_STREAM, make_error(), cwist_http2_stream_hooks::next_deadline_ms, cwist_http2_stream_hooks::on_cancel, cwist_http2_stream_hooks::on_conn_open, cwist_http2_stream_hooks::on_data, cwist_http2_stream_hooks::on_poll, cwist_https_connection::park_expired, cwist_https_connection::proto_state, and cwist_https_connection::proto_state_free.

Referenced by cwist_app_http_handler(), cwist_app_http_handler_async(), and cwist_http2_serve_connection().

◆ cwist_http2_stream_send_data()

int cwist_http2_stream_send_data	(	cwist_h2_stream *	stream,
		const unsigned char *	data,
		size_t	len
	)

Send DATA on a hook-taken stream, honoring flow-control credit. Splits data into peer_max_frame_size chunks. When the send window is exhausted the batch buffer is flushed and the calling handler thread parks on the connection's fc_cond until the dispatcher applies WINDOW_UPDATE credit or the stream goes away; credit is re-checked under out_mu before each frame is written.

Parameters

stream	Stream to send on; must belong to a live connection.
data	Payload bytes.
len	Payload length.

Returns: 0 when the whole payload was queued/written, -1 on send failure or stream/connection teardown.

Definition at line 2642 of file http2.c.

References cap, CWIST_HTTP2_FRAME_DATA, and CWIST_HTTP2_MAX_FRAME_SIZE.

◆ cwist_http2_stream_send_headers()

int cwist_http2_stream_send_headers	(	cwist_h2_stream *	stream,
		int	status,
		const cwist_http2_header *	headers,
		size_t	header_count,
		int	end_stream
	)

Immediate outbound writes for hook-taken streams. Safe to call from the stream handler's own thread; frames bypass the batching delay and are flushed to the socket before returning.

cwist_http2_stream_send_headers emits a response HEADERS frame (status is taken from status, the pairs carry the remaining fields). cwist_http2_stream_send_data emits DATA frames (chunked to the peer's frame/window limits). cwist_http2_stream_send_trailers emits a trailer HEADERS frame with END_STREAM. All return 0 on success, -1 on failure.

Definition at line 2608 of file http2.c.

References cap, cwist_free(), CWIST_HTTP2_FLAG_END_HEADERS, CWIST_HTTP2_FLAG_END_STREAM, and CWIST_HTTP2_FRAME_HEADERS.

◆ cwist_http2_stream_send_trailers()

int cwist_http2_stream_send_trailers	(	cwist_h2_stream *	stream,
		const cwist_http2_header *	trailers,
		size_t	trailer_count
	)

Definition at line 2688 of file http2.c.

References cap, cwist_free(), CWIST_HTTP2_FLAG_END_HEADERS, CWIST_HTTP2_FLAG_END_STREAM, CWIST_HTTP2_FRAME_HEADERS, and cwist_realloc().

◆ h2_decode_integer()

int h2_decode_integer	(	const unsigned char *	buf,
		size_t	len,
		size_t *	pos,
		uint8_t	prefix_bits,
		uint32_t *	value
	)

Decode an HPACK integer.

Definition at line 1267 of file http2.c.

References cap.

Referenced by h2_decode_string().

◆ h2_decode_string()

char * h2_decode_string	(	const unsigned char *	buf,
		size_t	len,
		size_t *	pos
	)

Decode an HPACK string (literal or huffman).

Parameters

buf	Buffer holding the encoded header block.
len	Total length of `buf`.
pos	In/out: offset of the string; advanced past it on success.

Returns: Newly allocated string (caller frees), or NULL on malformed input.

Definition at line 1543 of file http2.c.

References cap, cwist_alloc(), h2_decode_integer(), and h2_huffman_decode().

◆ h2_encode_integer()

size_t h2_encode_integer	(	unsigned char *	dst,
		size_t	dst_cap,
		uint32_t	value,
		uint8_t	prefix_bits
	)

Encode an HPACK integer; returns bytes written, 0 when dst is too small.

Parameters

dst	Destination buffer; dst[0] must already hold any flag bits.
dst_cap	Capacity of `dst` in bytes.
value	Integer to encode.
prefix_bits	Number of prefix bits (1..8).

Returns: Bytes written, or 0 when dst_cap is too small.

Definition at line 1875 of file http2.c.

References cap.

Referenced by cwist_http2_push_resource(), and h2_encode_string().

◆ h2_encode_string()

size_t h2_encode_string	(	unsigned char *	dst,
		size_t	dst_cap,
		const char *	str
	)

Encode an HPACK string (literal, non-huffman); 0 when dst is too small.

Parameters

dst	Destination buffer.
dst_cap	Capacity of `dst` in bytes.
str	NUL-terminated string to encode.

Returns: Bytes written, or 0 when dst_cap is too small.

Definition at line 1903 of file http2.c.

References cap, and h2_encode_integer().

Referenced by cwist_http2_push_resource().

◆ h2_huffman_decode()

char * h2_huffman_decode	(	const unsigned char *	src,
		size_t	src_len,
		size_t *	out_len
	)

Decode an HPACK huffman-encoded string.

Parameters

src	Encoded bytes.
src_len	Number of encoded bytes.
out_len	Out: decoded length in bytes.

Returns: Newly allocated NUL-terminated decoded string (caller frees), or NULL on initialization, allocation, or coding errors.

Definition at line 1442 of file http2.c.

References cap, cwist_alloc(), cwist_free(), and cwist_realloc().

Referenced by h2_decode_string().

◆ h2_static_header()

const cwist_http2_static_header * h2_static_header ( uint32_t index )

Resolve an HPACK static table index (1-based); NULL when out of range.

Parameters

index Static table index (1..61).

Returns: Pointer to the static entry, or NULL for index 0 or out of range.

Definition at line 1570 of file http2.c.

References cap, and count.

Classes

Typedefs

Functions

Detailed Description

Typedef Documentation

◆ cwist_h2_async_queue

◆ cwist_h2_stream

◆ cwist_http2_header

◆ cwist_http2_request_handler_func

◆ cwist_http2_static_header

◆ cwist_http2_stream_hooks

Function Documentation

◆ cwist_h2_async_queue_acquire()

◆ cwist_h2_async_queue_enqueue()

◆ cwist_h2_async_queue_release()

◆ cwist_http2_push_resource()

◆ cwist_http2_serve_connection()

◆ cwist_http2_serve_connection_ex()

◆ cwist_http2_stream_send_data()

◆ cwist_http2_stream_send_headers()

◆ cwist_http2_stream_send_trailers()

◆ h2_decode_integer()

◆ h2_decode_string()

◆ h2_encode_integer()

◆ h2_encode_string()

◆ h2_huffman_decode()

◆ h2_static_header()