csilk_ctx_t Struct Reference

Main Request Context — holds all state for the current HTTP request/response cycle. More...

#include <context_internal.h>

Collaboration diagram for csilk_ctx_t:

Data Fields
int	handler_index
csilk_handler_t *	handlers
int	aborted
jmp_buf	jump_buffer
int	has_jump_buffer
csilk_arena_t *	arena
csilk_request_t	request
csilk_response_t	response
csilk_param_t	params [CSILK_MAX_PARAMS]
int	params_count
int	is_websocket
int	is_sse
void(*	on_ws_message )(csilk_ctx_t *c, const uint8_t *payload, size_t len, int opcode)
void(*	on_ws_send )(csilk_ctx_t *c, const uint8_t *payload, size_t len, int opcode)
csilk_storage_driver_t *	storage_driver
csilk_crypto_driver_t *	crypto_driver
csilk_cipher_driver_t *	cipher_driver
csilk_storage_item_t *	storage_head
struct csilk_server_s *	server
int32_t	stream_id
struct csilk_ctx_s *	next_stream
void *	_internal_client
uv_work_t	work_req
int	is_async
int	response_started
int	file_fd
size_t	file_offset
size_t	file_size
csilk_method_handler_t *	current_handler
char	request_id [37]

Detailed Description

Main Request Context — holds all state for the current HTTP request/response cycle.

Forward declaration of the request context (defined in csilk.h).

Opaque request context type. Created per-request by the server and passed to every handler and middleware. Carries the request, response, path parameters, arena allocator, storage, and connection state (WebSocket/SSE). Not thread-safe — access only from the libuv loop thread that owns the connection.

Lifecycle

1. Allocation: Created once per TCP connection in on_connection().
2. Reset: csilk_ctx_cleanup() is called after each request completes, which resets arena memory, clears headers/params/body, and resets flags. The underlying TCP connection and SSL session are preserved.
3. Reuse: For keep-alive connections, the same context handles multiple requests sequentially.
4. Free: When the connection closes, the arena is freed and the client struct (containing the context) is returned to the server's free pool.

Thread Safety

A single context is NEVER accessed from multiple threads simultaneously. The libuv event loop ensures serialized access per connection. Async operations (uv_queue_work) run on the thread pool but access to the context is synchronized via the libuv main-loop callback pattern.

Field Documentation

_internal_client

void* csilk_ctx_t::_internal_client

Opaque pointer to the internal csilk_client_t. MUST NOT be used directly by handlers. Used internally by _csilk_send_data() to route data through TLS or raw TCP.

aborted

int csilk_ctx_t::aborted

Non-zero if handler execution was aborted via csilk_abort(). Subsequent csilk_next() calls are no-ops.

arena

csilk_arena_t* csilk_ctx_t::arena

Request-scoped arena allocator. Memory is reset between requests. All short-lived allocations (headers, param values, storage items) are served from this arena.

cipher_driver

csilk_cipher_driver_t* csilk_ctx_t::cipher_driver

Optional pluggable cipher backend for AES-256-GCM encrypt/decrypt, RSA-OAEP encrypt/decrypt, RSA-PSS sign/verify, and RSA-2048 key generation.

crypto_driver

csilk_crypto_driver_t* csilk_ctx_t::crypto_driver

Optional pluggable crypto backend for HMAC, UUID generation, SHA256. Defaults to OpenSSL-based software implementation.

current_handler

csilk_method_handler_t* csilk_ctx_t::current_handler

OpenAPI spec generation — tracks the current method handler's metadata Pointer to the method handler entry for the matched route (NULL if unmatched). Used by csilk_bind_reflect() and csilk_json_reflect() to infer input/output type names from route metadata.

file_fd

int csilk_ctx_t::file_fd

File descriptor of the file being sent via sendfile(). -1 if not in use. Set by static file middleware for large file responses.

file_offset

size_t csilk_ctx_t::file_offset

Byte offset into the file where sendfile should start reading (for partial/range requests).

file_size

size_t csilk_ctx_t::file_size

Total number of bytes to send from the file.

handler_index

int csilk_ctx_t::handler_index

Index of the current handler in the chain; starts at -1 (before first handler).

handlers

csilk_handler_t* csilk_ctx_t::handlers

NULL-terminated array of handler function pointers for the matched route.

has_jump_buffer

int csilk_ctx_t::has_jump_buffer

Non-zero if jump_buffer has been initialized and is safe to longjmp to. Guards against longjmp on uninitialized context.

is_async

int csilk_ctx_t::is_async

Non-zero if the response will be sent asynchronously (framework skips auto-send after handler chain returns). Set by csilk_response_write() for streaming responses or explicitly by csilk_set_async().

is_sse

int csilk_ctx_t::is_sse

Non-zero if the connection is being used for Server-Sent Events streaming. When set, the framework does not auto-send the response after the handler returns.

is_websocket

int csilk_ctx_t::is_websocket

Non-zero if the connection has been upgraded to WebSocket (set by csilk_ws_handshake). When set, data frames are dispatched to on_ws_message instead of being parsed as HTTP.

jump_buffer

jmp_buf csilk_ctx_t::jump_buffer

setjmp buffer for error recovery (used by panic/recovery middleware via longjmp).

next_stream

struct csilk_ctx_s* csilk_ctx_t::next_stream

Linked list of active multiplexed contexts for a single client.

on_ws_message

void(* csilk_ctx_t::on_ws_message) (csilk_ctx_t *c, const uint8_t *payload, size_t len, int opcode)

Callback invoked for each incoming WebSocket data frame. Set via csilk_set_on_ws_message(). Receives the context, unmasked payload, payload length, and opcode (0x1=text, 0x2=binary).

on_ws_send

void(* csilk_ctx_t::on_ws_send) (csilk_ctx_t *c, const uint8_t *payload, size_t len, int opcode)

Callback invoked for each outgoing WebSocket data frame (for testing).

params

csilk_param_t csilk_ctx_t::params[CSILK_MAX_PARAMS]

URL path parameters captured during routing (key/value pairs). Populated by the router when matching parameterized routes like "/users/:id".

params_count

int csilk_ctx_t::params_count

Number of path parameters currently in params[] array.

request

csilk_request_t csilk_ctx_t::request

Parsed HTTP request data (method, path, headers, body, query params, form params). Populated by the llhttp-based HTTP parser.

request_id

char csilk_ctx_t::request_id[37]

Per-request unique identifier (UUID v4 string, 36 chars + null).

response

csilk_response_t csilk_ctx_t::response

HTTP response data (status, headers, body) to be sent to the client. Set by handler functions like csilk_string(), csilk_json(), etc.

response_started

int csilk_ctx_t::response_started

Non-zero if chunked response headers have already been sent to the client. Used by csilk_response_write() to avoid sending headers multiple times in streaming mode.

server

struct csilk_server_s* csilk_ctx_t::server

Pointer to the owning server instance.

storage_driver

csilk_storage_driver_t* csilk_ctx_t::storage_driver

Optional pluggable storage backend for csilk_set()/csilk_get(). When set, takes precedence over the internal linked-list storage. Set per-server and propagated to all contexts.

storage_head

csilk_storage_item_t* csilk_ctx_t::storage_head

Head of the linked list for simple arena-backed key-value storage. Managed by csilk_set()/csilk_get() when no storage_driver is set.

stream_id

int32_t csilk_ctx_t::stream_id

HTTP/2 Stream ID. 0 for HTTP/1.1 connections.

work_req

uv_work_t csilk_ctx_t::work_req

libuv work request structure for offloading async operations to the thread pool. Used by csilk_ai_chat_async() and other async handlers.

---

The documentation for this struct was generated from the following file:

• src/core/context_internal.h