Core Application Structure and Lifecycle Management. More...

#include <cwist/net/http/http.h>
#include <cwist/net/http/https.h>
#include <cwist/core/db/sql.h>
#include <cwist/core/db/pool.h>
#include <cwist/net/redis/cwist_redis.h>
#include <cwist/net/grpc/grpc.h>
#include <cwist/sys/job/scheduler.h>
#include <cwist/sys/err/cwist_err.h>
#include <cwist/core/macros.h>
#include <cwist/sys/app/big_dumb_reply.h>
#include <ttak/mem_tree/mem_tree.h>
#include <cwist/net/websocket/websocket.h>
#include <cwist/net/websocket/websocket_async.h>

Include dependency graph for app.h:

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

Go to the source code of this file.

Classes
struct	cwist_error_handler_entry

struct	cwist_rdbms_runtime
	Mounted RDBMS runtime state. More...

struct	cwist_middleware_node
	Linked list node for middleware chain. More...

struct	cwist_app
	Main Application Context. More...

struct	cwist_file_t
	Represents a file loaded into the fixed memory pool. More...

struct	cwist_fix_server_mem
	Fixed Server Memory Manager. More...

struct	cwist_multiport_t
	Counted multiport descriptor created from a normal C array. More...

Macros
#define	cwist_use_https2(enabled) cwist_app_use_https2((app), (enabled))

#define	cwist_use_https3(enabled) cwist_app_use_https3((app), (enabled))

#define	cwist_use_http2(enabled) cwist_app_use_http2((app), (enabled))

#define	cwist_use_http3(enabled) cwist_app_use_http3((app), (enabled))

#define	CWIST_STREAM_CHUNK (64 * 1024)

Typedefs
typedef void(*	cwist_handler_func) (cwist_http_request req, cwist_http_response res)
	Function pointer type for HTTP route handlers.

typedef void(*	cwist_handler_ex_func) (void user_ctx, cwist_http_request req, cwist_http_response *res)
	Route handler that also receives the context it was registered with.

typedef void(*	cwist_handler_ctx_destroy_func) (void *user_ctx)
	Releases a route's user context once the route no longer needs it.

typedef void(*	cwist_ws_handler_func) (cwist_websocket *ws)
	Function pointer type for WebSocket handlers.

typedef void(*	cwist_error_handler_func) (cwist_http_request req, cwist_http_response res, cwist_http_status_t status)
	Function pointer type for error handlers.

typedef void(*	cwist_webtransport_handler_func) (cwist_http_request req, cwist_http_response res, void *stream)
	Callback function type for handling WebTransport sessions over HTTP/3.

typedef struct cwist_error_handler_entry	cwist_error_handler_entry

typedef enum cwist_rdbms_provider	cwist_rdbms_provider_t
	RDBMS provider auto-detection result.

typedef struct cwist_rdbms_runtime	cwist_rdbms_runtime
	Mounted RDBMS runtime state.

typedef void(*	cwist_middleware_func) (cwist_http_request req, cwist_http_response res, cwist_handler_func next)
	Middleware type that receives req/res pair and the next stage in the chain.

typedef void(*	cwist_middleware_func_ex) (cwist_http_request req, cwist_http_response res, cwist_handler_func next, void *user_ctx)
	Extended middleware type that also receives a user context.

typedef void(*	cwist_middleware_ctx_destroy_func) (void *user_ctx)
	Destructor for a middleware user context.

typedef void(*	cwist_https_request_handler_func) (cwist_https_connection conn, void ctx)

typedef struct cwist_middleware_node	cwist_middleware_node
	Linked list node for middleware chain.

typedef struct cwist_route_table	cwist_route_table

typedef struct cwist_static_dir	cwist_static_dir

typedef struct cwist_config	cwist_config

typedef struct cwist_logger	cwist_logger

typedef struct cwist_app	cwist_app
	Main Application Context.

typedef struct cwist_file_t	cwist_file_t
	Represents a file loaded into the fixed memory pool.

typedef struct cwist_fix_server_mem	cwist_fix_server_mem
	Fixed Server Memory Manager.

typedef int(*	cwist_stream_write_fn) (void ctx, const char data, size_t len)

typedef struct cwist_stream_req	cwist_stream_req_t

Enumerations
enum	cwist_rdbms_provider { CWIST_RDBMS_NONE = 0 , CWIST_RDBMS_POSTGRES , CWIST_RDBMS_MYSQL , CWIST_RDBMS_MARIADB }
	RDBMS provider auto-detection result. More...

Functions
cwist_rdbms_provider_t	cwist_rdbms_probe_port (int port)
	Probe a TCP port for an RDBMS wire protocol.

bool	cwist_rdbms_mount_runtime (cwist_app *app, cwist_rdbms_provider_t provider, int port)
	Mount an RDBMS runtime for the given provider and port.

cwist_app *	cwist_app_create (void)
	Creates a new CWIST application instance.

void	cwist_app_enable_swagger (cwist_app app, const char mount_path, const char *openapi_json_path)
	Enables embedded Swagger UI interactive documentation page.

void	cwist_app_destroy (cwist_app *app)
	Destroys the application and frees all resources.

void	cwist_app_set_max_memspace (cwist_app *app, size_t size)
	Sets the maximum memory space for the static file pool.

void	cwist_app_configure_bdr (cwist_app *app, size_t max_bytes, time_t max_entry_age_sec, uint64_t revalidate_hits)
	Configures the Big Dumb Reply guardrails.

cwist_error_t	cwist_app_use_https (cwist_app app, const char cert_path, const char *key_path)
	Enable TLS for the application using the supplied certificate pair.

cwist_error_t	cwist_app_reload_tls (cwist_app app, const char cert_path, const char *key_path)
	Hot-reload the TLS certificate chain and key without restarting the listener.

cwist_error_t	cwist_app_use_https2 (cwist_app *app, bool enabled)

cwist_error_t	cwist_app_use_https3 (cwist_app *app, bool enabled)

cwist_error_t	cwist_app_use_http2 (cwist_app *app, bool enabled)
	Enable HTTP/2 cleartext (h2c) over standard TCP.

cwist_error_t	cwist_app_use_http3 (cwist_app *app, bool enabled)
	Enable HTTP/3 (QUIC) without manual SSL configuration. Auto-generates an ephemeral self-signed certificate internally.

void	cwist_app_use_webtransport (cwist_app *app, cwist_webtransport_handler_func handler)
	Enable WebTransport over HTTP/3 on the application.

void	cwist_app_use_pqc_layer (cwist_app *app, bool enabled)
	Enable Post-Quantum Cryptography (PQC) hybrid key exchange layer.

void	cwist_app_set_tls_groups (cwist_app app, const char groups)
	Override TLS groups explicitly.

cwist_error_t	cwist_app_use_db (cwist_app app, const char db_path)
	Open a SQLite database and attach it as the shared application handle.

cwist_error_t	cwist_app_use_nuke_db (cwist_app app, const char db_path, int sync_interval_ms)
	Enable NUKE DB and fall back to standard SQLite when RAM bootstrap fails.

cwist_db *	cwist_app_get_db (cwist_app *app)
	Return the active shared database wrapper for the application.

cwist_error_t	cwist_app_use_db_pool (cwist_app app, const char db_path, size_t max_conns)
	Open a SQLite connection pool and attach it to the application.

cwist_db_pool_t *	cwist_app_get_db_pool (cwist_app *app)
	Return the application's database connection pool.

cwist_error_t	cwist_app_use_redis (cwist_app app, const char host, int port, size_t max_conns)
	Configure a Redis connection pool for the application.

cwist_redis_pool_t *	cwist_app_get_redis_pool (cwist_app *app)
	Return the application's Redis connection pool.

cwist_error_t	cwist_app_use_scheduler (cwist_app *app, size_t worker_count, size_t queue_capacity)
	Configure a background job scheduler for the application.

cwist_scheduler_t *	cwist_app_get_scheduler (cwist_app *app)
	Return the application's background job scheduler.

bool	cwist_app_auto_rdbms (cwist_app *app, int port)
	Auto-detect and mount an RDBMS runtime by probing a TCP port.

void	cwist_app_dispatch (cwist_app app, cwist_http_request req, cwist_http_response *res)
	Dispatch a request internally through the app's router and middleware. Used by the test client and advanced integrations.

int	cwist_app_dispatch_memory (cwist_app app, const char req_buf, size_t req_len, char *res_buf, size_t res_len)
	Run the full router/middleware/handler pipeline on a raw HTTP/1.x request held in a memory buffer, with no socket or event loop involved.

int	cwist_app_dispatch_stream (cwist_app app, const char req_buf, size_t req_len, cwist_stream_write_fn write_fn, void *write_ctx)
	Like cwist_app_dispatch_memory(), but streams the serialized response through `write_fn` instead of returning one buffer.

cwist_stream_req_t *	cwist_stream_req_begin (const char *head, size_t head_len)
	Begin an incremental request: `head` is the serialized request line plus headers (everything up to and including the terminating CRLF of the header block). The body length is taken from Content-Length (required for fed bodies; Transfer-Encoding: chunked is not reassembled).

int	cwist_stream_req_feed (cwist_stream_req_t req, const char chunk, size_t len)
	Feed one body chunk. Chunks may be any size and may split anywhere; reassembly is the implementation's job. Feeding more bytes than the declared Content-Length is an error.

int	cwist_stream_req_end (cwist_stream_req_t *req)
	Declare the body complete. The fed byte count must equal the declared Content-Length (or both be zero for a bodyless request).

int	cwist_stream_req_dispatch (cwist_stream_req_t req, cwist_app app, cwist_stream_write_fn write_fn, void *write_ctx)
	Dispatch a completed incremental request with a streaming response. Takes ownership of `req` regardless of outcome.

Middleware
void	cwist_app_use (cwist_app *app, cwist_middleware_func mw)
	Append a middleware callback to the application's execution chain.

cwist_error_t	cwist_app_use_ex (cwist_app app, cwist_middleware_func mw, cwist_middleware_func_ex mw_ex, void user_ctx, cwist_middleware_ctx_destroy_func destroy)
	Append an extended middleware to the application chain.

Error Handling Configuration
void	cwist_app_set_error_handler (cwist_app *app, cwist_error_handler_func handler)
	Install a custom HTTP error callback.

void	cwist_app_register_error_handler (cwist_app *app, cwist_http_status_t status, cwist_error_handler_func handler)

Routing
void	cwist_app_get (cwist_app app, const char path, cwist_handler_func handler)
	Registers a GET route handler.

void	cwist_app_post (cwist_app app, const char path, cwist_handler_func handler)
	Register a POST handler with default endpoint options.

void	cwist_app_put (cwist_app app, const char path, cwist_handler_func handler)

void	cwist_app_delete (cwist_app app, const char path, cwist_handler_func handler)

void	cwist_app_patch (cwist_app app, const char path, cwist_handler_func handler)

void	cwist_app_ws (cwist_app app, const char path, cwist_ws_handler_func handler)
	Register a WebSocket upgrade endpoint with default options.

cwist_error_t	cwist_app_get_ex (cwist_app app, const char path, cwist_handler_ex_func handler, void *user_ctx, cwist_handler_ctx_destroy_func destroy)
	Registers a GET route whose handler receives a user context.

cwist_error_t	cwist_app_post_ex (cwist_app app, const char path, cwist_handler_ex_func handler, void *user_ctx, cwist_handler_ctx_destroy_func destroy)
	POST counterpart of cwist_app_get_ex().

cwist_error_t	cwist_app_put_ex (cwist_app app, const char path, cwist_handler_ex_func handler, void *user_ctx, cwist_handler_ctx_destroy_func destroy)
	PUT counterpart of cwist_app_get_ex().

cwist_error_t	cwist_app_delete_ex (cwist_app app, const char path, cwist_handler_ex_func handler, void *user_ctx, cwist_handler_ctx_destroy_func destroy)
	DELETE counterpart of cwist_app_get_ex().

cwist_error_t	cwist_app_patch_ex (cwist_app app, const char path, cwist_handler_ex_func handler, void *user_ctx, cwist_handler_ctx_destroy_func destroy)
	PATCH counterpart of cwist_app_get_ex().

void	cwist_app_ws_async (cwist_app app, const char path, cwist_ws_on_message_t on_message, void *user_data)
	Register a callback-shaped non-blocking WebSocket endpoint (C1M mode).

void	cwist_app_get_opt (cwist_app app, const char path, cwist_handler_func handler, cwist_endpoint_opt_t opts)
	Register a GET handler with explicit endpoint options.

void	cwist_app_post_opt (cwist_app app, const char path, cwist_handler_func handler, cwist_endpoint_opt_t opts)
	Register a POST handler with explicit endpoint options.

void	cwist_app_put_opt (cwist_app app, const char path, cwist_handler_func handler, cwist_endpoint_opt_t opts)

void	cwist_app_delete_opt (cwist_app app, const char path, cwist_handler_func handler, cwist_endpoint_opt_t opts)

void	cwist_app_patch_opt (cwist_app app, const char path, cwist_handler_func handler, cwist_endpoint_opt_t opts)

void	cwist_app_ws_opt (cwist_app app, const char path, cwist_ws_handler_func handler, cwist_endpoint_opt_t opts)
	Register a WebSocket route with explicit endpoint options.

void	cwist_app_enable_metrics (cwist_app *app)

void	cwist_app_enable_healthz (cwist_app *app)

void	cwist_app_get_named (cwist_app app, const char path, const char *name, cwist_handler_func handler)

void	cwist_app_post_named (cwist_app app, const char path, const char *name, cwist_handler_func handler)

void	cwist_app_put_named (cwist_app app, const char path, const char *name, cwist_handler_func handler)

void	cwist_app_delete_named (cwist_app app, const char path, const char *name, cwist_handler_func handler)

void	cwist_app_patch_named (cwist_app app, const char path, const char *name, cwist_handler_func handler)

char *	cwist_url_for (cwist_app app, const char name, cwist_query_map *params)

cwist_error_t	cwist_app_static (cwist_app app, const char url_prefix, const char *directory)
	Serves a directory of static files at a URL prefix. Files are loaded into the fixed memory pool for Zero-Copy serving.

cwist_error_t	cwist_app_static_with_cache (cwist_app app, const char url_prefix, const char directory, const char cache_control)
	Serves a directory of static files at a URL prefix with custom Cache-Control. Files are loaded into the fixed memory pool for Zero-Copy serving.

Startup
#define	CWIST_MULTIPORT_MAX_PORTS 64

#define	cwist_create_multiport(ports) cwist_create_multiport_from_array((ports), sizeof(ports) / sizeof((ports)[0]))
	Create a counted multiport descriptor from a real C array.

typedef struct cwist_multiport_t	cwist_multiport_t
	Counted multiport descriptor created from a normal C array.

cwist_multiport_t	cwist_create_multiport_from_array (const unsigned short *ports, size_t count)
	Create a counted multiport descriptor from an explicit pointer and length.

void	cwist_app_http_handler (int client_fd, void *ctx)

cwist_async_action_t	cwist_app_http_handler_async (int client_fd, cwist_http_async_conn_t *conn)

void	cwist_apply_profile (void)
	Apply CWIST_PROFILE preset env-var defaults.

int	cwist_app_listen (cwist_app *app, int port)
	Serve `app` on `port` until SIGTERM, SIGINT or cwist_shutdown_request(); blocks the calling thread.

int	cwist_app_listen_ex (cwist_app *app, int port, int workers_override, int c1m_override)
	cwist_app_listen() with the worker count and server mode given explicitly.

int	cwist_app_multiport (cwist_app **app_ref, unsigned short public_port, cwist_multiport_t ports)
	Start one app facade across a public port and counted backend port list.

cwist_app *	cwist_multiport_get_app (cwist_app **app_ref, unsigned short port)
	Detach one additional multiport port into its own tunable application.

Detailed Description

Core Application Structure and Lifecycle Management.

Definition in file app.h.

Macro Definition Documentation

◆ cwist_create_multiport

#define cwist_create_multiport ( ports ) cwist_create_multiport_from_array((ports), sizeof(ports) / sizeof((ports)[0]))

Create a counted multiport descriptor from a real C array.

Parameters

ports Real C array, not a decayed pointer.

Definition at line 611 of file app.h.

◆ CWIST_MULTIPORT_MAX_PORTS

#define CWIST_MULTIPORT_MAX_PORTS 64

Definition at line 587 of file app.h.

◆ CWIST_STREAM_CHUNK

#define CWIST_STREAM_CHUNK (64 * 1024)

Maximum slice size passed to cwist_stream_write_fn() for the body.

Definition at line 711 of file app.h.

◆ cwist_use_http2

#define cwist_use_http2 ( enabled ) cwist_app_use_http2((app), (enabled))

Definition at line 466 of file app.h.

◆ cwist_use_http3

#define cwist_use_http3 ( enabled ) cwist_app_use_http3((app), (enabled))

Definition at line 467 of file app.h.

◆ cwist_use_https2

#define cwist_use_https2 ( enabled ) cwist_app_use_https2((app), (enabled))

Definition at line 464 of file app.h.

◆ cwist_use_https3

#define cwist_use_https3 ( enabled ) cwist_app_use_https3((app), (enabled))

Definition at line 465 of file app.h.

Typedef Documentation

◆ cwist_app

typedef struct cwist_app cwist_app

Main Application Context.

Manages routing, middleware, database connections, memory pools, and caching strategies (BDR).

◆ cwist_config

typedef struct cwist_config cwist_config

Definition at line 146 of file app.h.

◆ cwist_error_handler_entry

typedef struct cwist_error_handler_entry cwist_error_handler_entry

◆ cwist_error_handler_func

typedef void(* cwist_error_handler_func) (cwist_http_request *req, cwist_http_response *res, cwist_http_status_t status)

Function pointer type for error handlers.

Definition at line 61 of file app.h.

◆ cwist_file_t

typedef struct cwist_file_t cwist_file_t

Represents a file loaded into the fixed memory pool.

— Memory Management —

◆ cwist_fix_server_mem

typedef struct cwist_fix_server_mem cwist_fix_server_mem

Fixed Server Memory Manager.

Pre-allocates a large contiguous block of memory to serve static files via Zero-Copy pointer passing. Supports hot-reloading on file change.

◆ cwist_handler_ctx_destroy_func

typedef void(* cwist_handler_ctx_destroy_func) (void *user_ctx)

Releases a route's user context once the route no longer needs it.

Parameters

user_ctx The pointer passed at registration.

Definition at line 50 of file app.h.

◆ cwist_handler_ex_func

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

Route handler that also receives the context it was registered with.

Registered through the _ex routing functions (cwist_app_get_ex() and friends). user_ctx comes first, matching cwist_http2_request_handler_func.

Parameters

user_ctx	The pointer passed at registration.
req	Pointer to the HTTP request object.
res	Pointer to the HTTP response object.

Definition at line 43 of file app.h.

◆ cwist_handler_func

typedef void(* cwist_handler_func) (cwist_http_request *req, cwist_http_response *res)

Function pointer type for HTTP route handlers.

Parameters

req	Pointer to the HTTP request object.
res	Pointer to the HTTP response object.

Definition at line 32 of file app.h.

◆ cwist_https_request_handler_func

typedef void(* cwist_https_request_handler_func) (cwist_https_connection *conn, void *ctx)

Definition at line 130 of file app.h.

◆ cwist_logger

typedef struct cwist_logger cwist_logger

Definition at line 147 of file app.h.

◆ cwist_middleware_ctx_destroy_func

typedef void(* cwist_middleware_ctx_destroy_func) (void *user_ctx)

Destructor for a middleware user context.

Definition at line 128 of file app.h.

◆ cwist_middleware_func

typedef void(* cwist_middleware_func) (cwist_http_request *req, cwist_http_response *res, cwist_handler_func next)

Middleware type that receives req/res pair and the next stage in the chain.

Definition at line 115 of file app.h.

◆ cwist_middleware_func_ex

typedef void(* cwist_middleware_func_ex) (cwist_http_request *req, cwist_http_response *res, cwist_handler_func next, void *user_ctx)

Extended middleware type that also receives a user context.

This is the target type for language bindings that need to pass a closure and its destructor through the C middleware chain.

Definition at line 124 of file app.h.

◆ cwist_middleware_node

typedef struct cwist_middleware_node cwist_middleware_node

Linked list node for middleware chain.

◆ cwist_multiport_t

typedef struct cwist_multiport_t cwist_multiport_t

Counted multiport descriptor created from a normal C array.

◆ cwist_rdbms_provider_t

typedef enum cwist_rdbms_provider cwist_rdbms_provider_t

RDBMS provider auto-detection result.

◆ cwist_rdbms_runtime

typedef struct cwist_rdbms_runtime cwist_rdbms_runtime

Mounted RDBMS runtime state.

◆ cwist_route_table

typedef struct cwist_route_table cwist_route_table

Definition at line 144 of file app.h.

◆ cwist_static_dir

typedef struct cwist_static_dir cwist_static_dir

Definition at line 145 of file app.h.

◆ cwist_stream_req_t

typedef struct cwist_stream_req cwist_stream_req_t

Opaque incremental request assembly handle. Feeding a body chunk by chunk lets hosts avoid materializing one contiguous buffer for large uploads; chunks are copied once into the internally assembled wire buffer, which dispatch sends without a further reassembly copy.

Definition at line 731 of file app.h.

◆ cwist_stream_write_fn

typedef int(* cwist_stream_write_fn) (void *ctx, const char *data, size_t len)

— WASM boundary streaming (issue #93 Phase 3) ----------------------—

Streaming here means the boundary, not a streaming handler API: the request body may be fed incrementally (large uploads without one giant contiguous host buffer) and the serialized response is delivered through a caller-supplied chunk callback instead of one returned buffer, so hosts can consume it incrementally (e.g. pipe it into a JS ReadableStream). The handler itself still builds the response body in memory; a true chunked producer API inside handlers is a separate, larger change. Chunk sink for cwist_app_dispatch_stream(). Receives the serialized response bytes in order: the head (status line + headers) first, then the body in slices of at most CWIST_STREAM_CHUNK bytes. Return 0 to continue, nonzero to abort the dispatch (the remaining bytes are dropped and the dispatch returns -2).

Definition at line 708 of file app.h.

◆ cwist_webtransport_handler_func

typedef void(* cwist_webtransport_handler_func) (cwist_http_request *req, cwist_http_response *res, void *stream)

Callback function type for handling WebTransport sessions over HTTP/3.

Parameters

req	Parsed HTTP request object (CONNECT with :protocol=webtransport).
res	HTTP response object to be populated (e.g., 200 OK to accept).
stream	Opaque CWIST WebTransport session handle.

Definition at line 71 of file app.h.

◆ cwist_ws_handler_func

typedef void(* cwist_ws_handler_func) (cwist_websocket *ws)

Function pointer type for WebSocket handlers.

Parameters

ws	Pointer to the WebSocket context.

Definition at line 56 of file app.h.

Enumeration Type Documentation

◆ cwist_rdbms_provider

enum cwist_rdbms_provider

RDBMS provider auto-detection result.

Enumerator
CWIST_RDBMS_NONE
CWIST_RDBMS_POSTGRES
CWIST_RDBMS_MYSQL
CWIST_RDBMS_MARIADB

Definition at line 81 of file app.h.

Function Documentation

◆ cwist_app_auto_rdbms()

bool cwist_app_auto_rdbms	(	cwist_app *	app,
		int	port
	)

Auto-detect and mount an RDBMS runtime by probing a TCP port.

Connects to 127.0.0.1:port, probes the wire protocol, detects the provider (PostgreSQL, MySQL, or MariaDB), and mounts a data runtime.

Parameters

app	Application context.
port	Target TCP port for RDBMS probe.

Returns: true when provider detected and runtime mounted; false otherwise.

Auto-detect and mount an RDBMS runtime by probing a TCP port.

Probes port via cwist_rdbms_probe_port(); on success the detected provider's runtime is mounted with cwist_rdbms_mount_runtime().

Parameters

app	App to attach the runtime to; must not be NULL.
port	TCP port on localhost to probe.

Returns: true if detection and mounting succeed, false otherwise.

Definition at line 189 of file rdbms_auto_mount.c.

References CWIST_LOG_ERROR, cwist_rdbms_mount_runtime(), CWIST_RDBMS_NONE, cwist_rdbms_probe_port(), cwist_rdbms_runtime::port, and cwist_rdbms_runtime::provider.

◆ cwist_app_configure_bdr()

void cwist_app_configure_bdr	(	cwist_app *	app,
		size_t	max_bytes,
		time_t	max_entry_age_sec,
		uint64_t	revalidate_hits
	)

Configures the Big Dumb Reply guardrails.

Parameters

app	Target app.
max_bytes	Maximum bytes to keep in RAM (0 = keep default).
max_entry_age_sec	Retire cached replies older than this (<=0 keeps default).
revalidate_hits	Force refresh after this many hits (0 = keep default).

Configures the Big Dumb Reply guardrails.

Parameters

app	Application whose BDR context should be tuned.
max_bytes	Maximum total cache footprint.
max_entry_age_sec	Maximum age for cached entries.
revalidate_hits	Hit count that forces revalidation.

Definition at line 1454 of file app.c.

References cwist_app::bdr_ctx, and cwist_bdr_set_limits().

◆ cwist_app_create()

cwist_app * cwist_app_create ( void )

Creates a new CWIST application instance.

— API —

Returns: Pointer to the allocated app, or NULL on failure.

Definition at line 1292 of file app.c.

References cwist_app::bdr_ctx, cap, cwist_app::cert_path, cwist_app::config, cwist_alloc(), cwist_bdr_create(), cwist_config_create(), cwist_free(), cwist_logger_create(), cwist_app::db, cwist_app::db_path, cwist_app::db_pool, cwist_app::error_handler, cwist_app::error_handlers, cwist_app::grpc_routes, cwist_app::h3_ctx, cwist_app::https_request_handler, cwist_app::key_path, cwist_app::logger, cwist_app::max_mem_space, cwist_app::mem_manager, cwist_app::middlewares, cwist_app::nuke_enabled, cwist_app::port, cwist_app::pqc_layer_enabled, cwist_app::redis_pool, cwist_app::router, cwist_app::scheduler, cwist_app::session_max_age, cwist_app::session_name, cwist_app::session_secret, cwist_app::ssl_ctx, cwist_app::static_dirs, cwist_app::tls_groups, cwist_app::use_http2, cwist_app::use_http3, cwist_app::use_https2, cwist_app::use_https3, cwist_app::use_ssl, and cwist_app::wt_handler.

◆ cwist_app_delete()

void cwist_app_delete	(	cwist_app *	app,
		const char *	path,
		cwist_handler_func	handler
	)

Definition at line 2275 of file app.c.

References CWIST_ENDPOINT_DEFAULT, and CWIST_HTTP_DELETE.

◆ cwist_app_delete_ex()

cwist_error_t cwist_app_delete_ex	(	cwist_app *	app,
		const char *	path,
		cwist_handler_ex_func	handler,
		void *	user_ctx,
		cwist_handler_ctx_destroy_func	destroy
	)

DELETE counterpart of cwist_app_get_ex().

Definition at line 2195 of file app.c.

References CWIST_HTTP_DELETE.

◆ cwist_app_delete_named()

void cwist_app_delete_named	(	cwist_app *	app,
		const char *	path,
		const char *	name,
		cwist_handler_func	handler
	)

Definition at line 2293 of file app.c.

References CWIST_ENDPOINT_DEFAULT, and CWIST_HTTP_DELETE.

◆ cwist_app_delete_opt()

void cwist_app_delete_opt	(	cwist_app *	app,
		const char *	path,
		cwist_handler_func	handler,
		cwist_endpoint_opt_t	opts
	)

Definition at line 2385 of file app.c.

References CWIST_HTTP_DELETE.

◆ cwist_app_destroy()

void cwist_app_destroy ( cwist_app * app )

Destroys the application and frees all resources.

Parameters

app	Pointer to the app to destroy.

Destroys the application and frees all resources.

Parameters

app	Application instance to destroy.

Definition at line 1464 of file app.c.

References cwist_app::assets, cwist_app::bdr_ctx, cap, cwist_app::cert_path, cwist_app::config, cwist_assets_destroy(), cwist_bdr_destroy(), cwist_config_destroy(), cwist_db_close(), cwist_db_pool_destroy(), cwist_free(), cwist_grpc_routes_destroy(), cwist_http3_destroy_context(), cwist_https_destroy_context(), cwist_logger_destroy(), cwist_nuke_close(), cwist_redis_pool_destroy(), cwist_scheduler_destroy(), cwist_app::db, cwist_app::db_path, cwist_app::db_pool, cwist_middleware_node::destroy, cwist_app::error_handlers, cwist_fix_server_mem::file_count, cwist_fix_server_mem::file_tree, cwist_fix_server_mem::files, cwist_file_t::fs_path, cwist_app::h3_ctx, cwist_app::key_path, cwist_fix_server_mem::lock, cwist_app::logger, cwist_app::mem_manager, cwist_app::middlewares, cwist_error_handler_entry::next, cwist_middleware_node::next, cwist_file_t::node, cwist_app::nuke_enabled, cwist_file_t::path, cwist_app::rdbms, cwist_app::redis_pool, cwist_app::router, cwist_app::scheduler, cwist_app::session_name, cwist_app::session_secret, cwist_app::ssl_ctx, cwist_app::static_dirs, cwist_app::tls_groups, cwist_fix_server_mem::watcher_running, and cwist_fix_server_mem::watcher_thread.

◆ cwist_app_dispatch()

void cwist_app_dispatch	(	cwist_app *	app,
		cwist_http_request *	req,
		cwist_http_response *	res
	)

Dispatch a request internally through the app's router and middleware. Used by the test client and advanced integrations.

Definition at line 2516 of file app.c.

References cwist_http_request::app, cwist_http_request::db, and cwist_app::db.

Referenced by cwist_app_dispatch_memory(), and cwist_app_dispatch_stream().

◆ cwist_app_dispatch_memory()

int cwist_app_dispatch_memory	(	cwist_app *	app,
		const char *	req_buf,
		size_t	req_len,
		char **	res_buf,
		size_t *	res_len
	)

Run the full router/middleware/handler pipeline on a raw HTTP/1.x request held in a memory buffer, with no socket or event loop involved.

The response is serialized (status line + headers + body) into a freshly allocated buffer; the caller frees res_buf with cwist_free(). The exchange uses Connection: close semantics. This is the in-memory entry point for embedded transports (e.g. WASM / Service Worker hosts).

Returns: 0 on success; -1 when the request is malformed or the response cannot be serialized (e.g. a file-streaming body).

Definition at line 2523 of file app.c.

References cap, cwist_app_dispatch(), cwist_http_parse_request_len(), cwist_http_request_destroy(), cwist_http_response_create(), cwist_http_response_destroy(), cwist_http_response_serialize(), cwist_http_response_stream_end(), cwist_http_response::keep_alive, cwist_http_response::stream_ended, and cwist_http_response::stream_mode.

◆ cwist_app_dispatch_stream()

int cwist_app_dispatch_stream	(	cwist_app *	app,
		const char *	req_buf,
		size_t	req_len,
		cwist_stream_write_fn	write_fn,
		void *	write_ctx
	)

Like cwist_app_dispatch_memory(), but streams the serialized response through write_fn instead of returning one buffer.

Parameters

app	Application to dispatch against.
req_buf	Serialized HTTP/1.1 request (head + body, as the wire form).
req_len	Length of `req_buf`.
write_fn	Chunk sink; must not be NULL.
write_ctx	Opaque argument passed to every write_fn call.

Returns: 0 when the full response was delivered; -1 on dispatch/serialize failure; -2 when the sink aborted.

Definition at line 2668 of file app.c.

Referenced by cwist_stream_req_dispatch().

◆ cwist_app_enable_healthz()

void cwist_app_enable_healthz ( cwist_app * app )

Definition at line 2249 of file app.c.

References cwist_app_get().

◆ cwist_app_enable_metrics()

void cwist_app_enable_metrics ( cwist_app * app )

Definition at line 2227 of file app.c.

References cwist_app_get().

◆ cwist_app_enable_swagger()

void cwist_app_enable_swagger	(	cwist_app *	app,
		const char *	mount_path,
		const char *	openapi_json_path
	)

Enables embedded Swagger UI interactive documentation page.

Parameters

app	Pointer to the app.
mount_path	URL route path to serve Swagger UI (e.g. "/swagger" or "/docs").
openapi_json_path	Path to the generated openapi.json file on disk.

Definition at line 5051 of file app.c.

References cap, and cwist_app_get().

◆ cwist_app_get()

void cwist_app_get	(	cwist_app *	app,
		const char *	path,
		cwist_handler_func	handler
	)

Registers a GET route handler.

Parameters

app	Application being configured.
path	Exact route path.
handler	HTTP handler invoked for matching requests.

Definition at line 2216 of file app.c.

References CWIST_ENDPOINT_DEFAULT, and CWIST_HTTP_GET.

Referenced by cwist_app_enable_healthz(), cwist_app_enable_metrics(), and cwist_app_enable_swagger().

◆ cwist_app_get_db()

cwist_db * cwist_app_get_db ( cwist_app * app )

Return the active shared database wrapper for the application.

Parameters

app	Application whose database handle should be queried.

Returns: Database wrapper, or NULL when no database is configured.

Definition at line 1948 of file app.c.

References cap, cwist_db::conn, cwist_nuke_get_db(), cwist_app::db, and cwist_app::nuke_enabled.

◆ cwist_app_get_db_pool()

cwist_db_pool_t * cwist_app_get_db_pool ( cwist_app * app )

Return the application's database connection pool.

Definition at line 1984 of file app.c.

References cap, and cwist_app::db_pool.

◆ cwist_app_get_ex()

cwist_error_t cwist_app_get_ex	(	cwist_app *	app,
		const char *	path,
		cwist_handler_ex_func	handler,
		void *	user_ctx,
		cwist_handler_ctx_destroy_func	destroy
	)

Registers a GET route whose handler receives a user context.

Behaves like cwist_app_get() (exact and :param paths, middleware, every transport), but the handler is called as handler(user_ctx, req, res). This lets a caller bind state to a route without globals, for example a closure from a language binding.

Ownership of user_ctx passes to the app on every call. When destroy is not NULL it is called exactly once with user_ctx:

when the app is destroyed;
when the same method and path (one without :param segments) is registered again, by any routing function, before the new registration takes over (unless it passes the same non-NULL user_ctx);
immediately, if the registration fails. Multiport sub-apps share the context without owning it. Pass NULL for destroy to keep ownership with the caller.

Parameters

app	Application being configured.
path	Route path; may contain `:param` segments.
handler	Handler invoked for matching requests.
user_ctx	Opaque pointer passed to `handler` (may be NULL).
destroy	Optional destructor for `user_ctx`.

Returns: INT16 0 on success; INT16 -1 when app, path or handler is NULL or the route could not be allocated.

Definition at line 2180 of file app.c.

References CWIST_HTTP_GET.

Referenced by cwist_app_enable_openapi().

◆ cwist_app_get_named()

void cwist_app_get_named	(	cwist_app *	app,
		const char *	path,
		const char *	name,
		cwist_handler_func	handler
	)

Definition at line 2256 of file app.c.

References CWIST_ENDPOINT_DEFAULT, and CWIST_HTTP_GET.

◆ cwist_app_get_opt()

void cwist_app_get_opt	(	cwist_app *	app,
		const char *	path,
		cwist_handler_func	handler,
		cwist_endpoint_opt_t	opts
	)

Register a GET handler with explicit endpoint options.

Parameters

app	Application being configured.
path	Exact route path.
handler	HTTP handler invoked for matching requests.
opts	Endpoint flags controlling cache and transport behavior.

Definition at line 2363 of file app.c.

References CWIST_HTTP_GET.

◆ cwist_app_get_redis_pool()

cwist_redis_pool_t * cwist_app_get_redis_pool ( cwist_app * app )

Return the application's Redis connection pool.

Definition at line 2015 of file app.c.

References cap, and cwist_app::redis_pool.

◆ cwist_app_get_scheduler()

cwist_scheduler_t * cwist_app_get_scheduler ( cwist_app * app )

Return the application's background job scheduler.

Definition at line 2045 of file app.c.

References cap, and cwist_app::scheduler.

◆ cwist_app_http_handler()

void cwist_app_http_handler	(	int	client_fd,
		void *	ctx
	)

◆ cwist_app_http_handler_async()

cwist_async_action_t cwist_app_http_handler_async	(	int	client_fd,
		cwist_http_async_conn_t *	conn
	)

Definition at line 3343 of file app.c.

References cwist_http_request::app, APP_SERVE_CLOSE, APP_SERVE_DEFERRED, APP_SERVE_DETACH, cwist_http_request::async_conn, cap, cwist_http_request::client_fd, cwist_alloc(), CWIST_ASYNC_CLOSE, CWIST_ASYNC_DEFER, CWIST_ASYNC_DETACH, CWIST_ASYNC_REARM, CWIST_COALESCE_FLUSH_ERROR, CWIST_COALESCE_FLUSH_PARKED, cwist_free(), cwist_grpc_http2_hooks(), CWIST_H2C_THREAD_STACK_SIZE, cwist_http2_serve_connection_ex(), cwist_http_async_conn_fill(), cwist_http_async_rearm(), cwist_http_coalesce_flush(), CWIST_HTTP_PARSE_OK, cwist_http_receive_request_nb(), CWIST_HTTPS_PROTOCOL_HTTP2, CWIST_RECV_FATAL, CWIST_RECV_NEED_MORE, cwist_http_request::db, cwist_app::db, cwist_https_connection::fd, cwist_http_async_conn::len, cwist_http_async_conn::peer_eof, cwist_http_async_conn::rbuf, cwist_http_async_conn::reactor, cwist_app::use_http2, and cwist_http_async_conn::user_ctx.

◆ cwist_app_listen()

int cwist_app_listen	(	cwist_app *	app,
		int	port
	)

Serve app on port until SIGTERM, SIGINT or cwist_shutdown_request(); blocks the calling thread.

CWIST_WORKERS (default: one per online core) and CWIST_C1M_MODE select the worker count and server mode; with more than one worker it forks and returns in each worker. Same as cwist_app_listen_ex(app, port, 0, -1).

Serve app on port until SIGTERM, SIGINT or cwist_shutdown_request(); blocks the calling thread.

Parameters

app	Application instance to run.
port	TCP port to bind.

Returns: 0 on success, or -1 when initialization, bind, or worker shutdown fails.

Definition at line 4628 of file app.c.

References cwist_app_listen_ex().

◆ cwist_app_listen_ex()

int cwist_app_listen_ex	(	cwist_app *	app,
		int	port,
		int	workers_override,
		int	c1m_override
	)

cwist_app_listen() with the worker count and server mode given explicitly.

Parameters

workers_override	Worker processes (1 serves without forking); 0 or less reads CWIST_WORKERS.
c1m_override	1 for the reactor server, which joins its handler threads before returning; 0 for the classic pool; negative reads CWIST_C1M_MODE. Ignored on WASI.

Returns: 0 after a graceful shutdown, -1 if the server could not start.

Definition at line 4636 of file app.c.

References cap, cwist_shutdown_install_handlers(), cwist_shutdown_restore_handlers(), and cwist_app::port.

Referenced by cwist_app_listen().

◆ cwist_app_multiport()

int cwist_app_multiport	(	cwist_app **	app_ref,
		unsigned short	public_port,
		cwist_multiport_t	ports
	)

Start one app facade across a public port and counted backend port list.

Parameters

app_ref	Address of the cwist_app pointer (use: cwist_app_multiport(&app, 443, ports)).
public_port	Primary public TCP port.
ports	Additional TCP ports created by cwist_create_multiport().

Returns: 0 after graceful shutdown, or -1 on validation/bind failure.

◆ cwist_app_patch()

void cwist_app_patch	(	cwist_app *	app,
		const char *	path,
		cwist_handler_func	handler
	)

Definition at line 2279 of file app.c.

References CWIST_ENDPOINT_DEFAULT, and CWIST_HTTP_PATCH.

◆ cwist_app_patch_ex()

cwist_error_t cwist_app_patch_ex	(	cwist_app *	app,
		const char *	path,
		cwist_handler_ex_func	handler,
		void *	user_ctx,
		cwist_handler_ctx_destroy_func	destroy
	)

PATCH counterpart of cwist_app_get_ex().

Definition at line 2200 of file app.c.

References CWIST_HTTP_PATCH.

◆ cwist_app_patch_named()

void cwist_app_patch_named	(	cwist_app *	app,
		const char *	path,
		const char *	name,
		cwist_handler_func	handler
	)

Definition at line 2298 of file app.c.

References CWIST_ENDPOINT_DEFAULT, and CWIST_HTTP_PATCH.

◆ cwist_app_patch_opt()

void cwist_app_patch_opt	(	cwist_app *	app,
		const char *	path,
		cwist_handler_func	handler,
		cwist_endpoint_opt_t	opts
	)

Definition at line 2390 of file app.c.

References CWIST_HTTP_PATCH.

◆ cwist_app_post()

void cwist_app_post	(	cwist_app *	app,
		const char *	path,
		cwist_handler_func	handler
	)

Register a POST handler with default endpoint options.

Parameters

app	Application being configured.
path	Exact route path.
handler	HTTP handler invoked for matching requests.

Definition at line 2267 of file app.c.

References CWIST_ENDPOINT_DEFAULT, and CWIST_HTTP_POST.

◆ cwist_app_post_ex()

cwist_error_t cwist_app_post_ex	(	cwist_app *	app,
		const char *	path,
		cwist_handler_ex_func	handler,
		void *	user_ctx,
		cwist_handler_ctx_destroy_func	destroy
	)

POST counterpart of cwist_app_get_ex().

Definition at line 2185 of file app.c.

References CWIST_HTTP_POST.

◆ cwist_app_post_named()

void cwist_app_post_named	(	cwist_app *	app,
		const char *	path,
		const char *	name,
		cwist_handler_func	handler
	)

Definition at line 2283 of file app.c.

References CWIST_ENDPOINT_DEFAULT, and CWIST_HTTP_POST.

◆ cwist_app_post_opt()

void cwist_app_post_opt	(	cwist_app *	app,
		const char *	path,
		cwist_handler_func	handler,
		cwist_endpoint_opt_t	opts
	)

Register a POST handler with explicit endpoint options.

Parameters

app	Application being configured.
path	Exact route path.
handler	HTTP handler invoked for matching requests.
opts	Endpoint flags controlling cache and transport behavior.

Definition at line 2375 of file app.c.

References CWIST_HTTP_POST.

◆ cwist_app_put()

void cwist_app_put	(	cwist_app *	app,
		const char *	path,
		cwist_handler_func	handler
	)

Definition at line 2271 of file app.c.

References CWIST_ENDPOINT_DEFAULT, and CWIST_HTTP_PUT.

◆ cwist_app_put_ex()

cwist_error_t cwist_app_put_ex	(	cwist_app *	app,
		const char *	path,
		cwist_handler_ex_func	handler,
		void *	user_ctx,
		cwist_handler_ctx_destroy_func	destroy
	)

PUT counterpart of cwist_app_get_ex().

Definition at line 2190 of file app.c.

References CWIST_HTTP_PUT.

◆ cwist_app_put_named()

void cwist_app_put_named	(	cwist_app *	app,
		const char *	path,
		const char *	name,
		cwist_handler_func	handler
	)

Definition at line 2288 of file app.c.

References CWIST_ENDPOINT_DEFAULT, and CWIST_HTTP_PUT.

◆ cwist_app_put_opt()

void cwist_app_put_opt	(	cwist_app *	app,
		const char *	path,
		cwist_handler_func	handler,
		cwist_endpoint_opt_t	opts
	)

Definition at line 2380 of file app.c.

References CWIST_HTTP_PUT.

◆ cwist_app_register_error_handler()

void cwist_app_register_error_handler	(	cwist_app *	app,
		cwist_http_status_t	status,
		cwist_error_handler_func	handler
	)

Definition at line 1415 of file app.c.

References cap, cwist_alloc(), cwist_app::error_handlers, cwist_error_handler_entry::handler, cwist_error_handler_entry::next, and cwist_error_handler_entry::status_code.

◆ cwist_app_reload_tls()

cwist_error_t cwist_app_reload_tls	(	cwist_app *	app,
		const char *	cert_path,
		const char *	key_path
	)

Hot-reload the TLS certificate chain and key without restarting the listener.

Builds and validates a new SSL_CTX from cert_path/key_path and swaps it into the application's live HTTPS context (and the HTTP/3 context when HTTPS/3 is enabled): established connections and in-progress handshakes finish on the old certificate, new handshakes present the new one. The shared session-ticket key (STEK) is carried over, so session resumption survives the reload; see docs/decisions/0002-tls-hot-reload.md.

Safe to call from any thread while the app is serving. In the pre-fork multi-worker model (CWIST_WORKERS > 1) each worker process holds its own copy of the context, so call it in every worker (e.g. from a SIGHUP handler installed in each process).

Parameters

app	Application configured with cwist_app_use_https().
cert_path	Path to the new PEM certificate chain.
key_path	Path to the new PEM private key.

Returns: err.error.err_i16 == 0 on success; on failure the previous certificate keeps serving and the stored paths stay unchanged.

Hot-reload the TLS certificate chain and key without restarting the listener.

Definition at line 1691 of file app.c.

References cap, cwist_app::cert_path, CWIST_ERR_INT16, cwist_free(), cwist_http3_reload_context(), cwist_https_reload_context(), cwist_strdup(), cwist_app::h3_ctx, cwist_app::key_path, make_error(), cwist_app::ssl_ctx, cwist_app::use_https3, and cwist_app::use_ssl.

◆ cwist_app_set_error_handler()

void cwist_app_set_error_handler	(	cwist_app *	app,
		cwist_error_handler_func	handler
	)

Install a custom HTTP error callback.

Parameters

app	Application being configured.
handler	Handler invoked for framework-generated errors such as 404 responses.

Definition at line 1411 of file app.c.

References cwist_app::error_handler.

◆ cwist_app_set_max_memspace()

void cwist_app_set_max_memspace	(	cwist_app *	app,
		size_t	size
	)

Sets the maximum memory space for the static file pool.

Parameters

app	Pointer to the app.
size	Size in bytes (Use macros like CWIST_MIB(64)).

Sets the maximum memory space for the static file pool.

Parameters

app	Application being configured.
size	Maximum bytes reserved for static payload caching.

Definition at line 1402 of file app.c.

References cwist_app::max_mem_space.

◆ cwist_app_set_tls_groups()

void cwist_app_set_tls_groups	(	cwist_app *	app,
		const char *	groups
	)

Override TLS groups explicitly.

Parameters

app	Application context.
groups	Colon-separated group list (e.g., "X25519MLKEM768:X25519:P-256"). Pass NULL to reset to automatic selection.

Definition at line 1749 of file app.c.

References cap, cwist_free(), cwist_strdup(), and cwist_app::tls_groups.

◆ cwist_app_static()

cwist_error_t cwist_app_static	(	cwist_app *	app,
		const char *	url_prefix,
		const char *	directory
	)

Serves a directory of static files at a URL prefix. Files are loaded into the fixed memory pool for Zero-Copy serving.

Parameters

app	Pointer to the app.
url_prefix	URL prefix (e.g., "/static").
directory	Local filesystem path.

Note: Additional method helpers can be added as needed.

Serves a directory of static files at a URL prefix. Files are loaded into the fixed memory pool for Zero-Copy serving.

Parameters

app	Application being configured.
url_prefix	Request-path prefix such as "/static".
directory	Filesystem directory that backs the mapping.

Returns: Tagged CWIST error describing success or failure.

Definition at line 2057 of file app.c.

References cap, cwist_alloc(), CWIST_ERR_INT16, cwist_free(), make_error(), and cwist_app::static_dirs.

◆ cwist_app_static_with_cache()

cwist_error_t cwist_app_static_with_cache	(	cwist_app *	app,
		const char *	url_prefix,
		const char *	directory,
		const char *	cache_control
	)

Serves a directory of static files at a URL prefix with custom Cache-Control. Files are loaded into the fixed memory pool for Zero-Copy serving.

Parameters

app	Pointer to the app.
url_prefix	URL prefix (e.g., "/static").
directory	Local filesystem path.
cache_control	Cache-Control directive string (e.g., "public, max-age=31536000, immutable"). Pass NULL to use the default "public, max-age=3600".

Serves a directory of static files at a URL prefix with custom Cache-Control. Files are loaded into the fixed memory pool for Zero-Copy serving.

Parameters

app	Application being configured.
url_prefix	Request-path prefix such as "/static".
directory	Filesystem directory that backs the mapping.
cache_control	Value for the Cache-Control header (e.g. "public, max-age=86400").

Returns: Tagged CWIST error describing success or failure.

Definition at line 2103 of file app.c.

References cap, cwist_alloc(), CWIST_ERR_INT16, cwist_free(), cwist_strdup(), make_error(), and cwist_app::static_dirs.

◆ cwist_app_use()

void cwist_app_use	(	cwist_app *	app,
		cwist_middleware_func	mw
	)

Append a middleware callback to the application's execution chain.

Parameters

app	Application being configured.
mw	Middleware callback to append.

Definition at line 1376 of file app.c.

References cap.

◆ cwist_app_use_db()

cwist_error_t cwist_app_use_db	(	cwist_app *	app,
		const char *	db_path
	)

Open a SQLite database and attach it as the shared application handle.

Parameters

app	Application being configured.
db_path	Filesystem path or SQLite URI to open.

Returns: Tagged CWIST error describing success or failure.

Definition at line 1851 of file app.c.

References cap, cwist_db_close(), cwist_db_open(), CWIST_ERR_INT16, cwist_free(), cwist_strdup(), cwist_app::db, cwist_app::db_path, make_error(), and cwist_app::nuke_enabled.

Referenced by cwist_app_use_nuke_db().

◆ cwist_app_use_db_pool()

cwist_error_t cwist_app_use_db_pool	(	cwist_app *	app,
		const char *	db_path,
		size_t	max_conns
	)

Open a SQLite connection pool and attach it to the application.

Parameters

app	Application context.
db_path	SQLite database path (or ":memory:").
max_conns	Maximum number of connections in the pool (>= 1).

Definition at line 1958 of file app.c.

References cap, cwist_db_pool_create(), cwist_db_pool_destroy(), CWIST_ERR_INT16, cwist_app::db_pool, and make_error().

◆ cwist_app_use_ex()

cwist_error_t cwist_app_use_ex	(	cwist_app *	app,
		cwist_middleware_func	mw,
		cwist_middleware_func_ex	mw_ex,
		void *	user_ctx,
		cwist_middleware_ctx_destroy_func	destroy
	)

Append an extended middleware to the application chain.

Exactly one of mw or mw_ex must be non-NULL. The user context is passed to mw_ex on every invocation; destroy is called once when the application is destroyed or, if registration fails, before this returns. Multiport sub-apps share the context without owning it.

Parameters

app	Application context.
mw	Legacy middleware function (may be NULL if `mw_ex` is set).
mw_ex	Extended middleware function with user context (may be NULL if `mw` is set).
user_ctx	Opaque context for `mw_ex`.
destroy	Destructor for `user_ctx`.

Returns: INT16 0 on success; INT16 -1 when app is NULL, not exactly one of mw and mw_ex is set, or the node could not be allocated.

Append an extended middleware to the application chain.

Parameters

app	Application being configured.
mw	Legacy middleware function (may be NULL if `mw_ex` is set).
mw_ex	Extended middleware function with user context (may be NULL if `mw` is set).
user_ctx	Opaque context for `mw_ex`.
destroy	Destructor for `user_ctx`.

Returns: INT16 0 on success, -1 on failure (the context is already released).

Definition at line 1389 of file app.c.

References cap, CWIST_ERR_INT16, and make_error().

◆ cwist_app_use_http2()

cwist_error_t cwist_app_use_http2	(	cwist_app *	app,
		bool	enabled
	)

Enable HTTP/2 cleartext (h2c) over standard TCP.

Parameters

app	Application context.
enabled	True to enable h2c.

Returns: cwist_error_t Status.

Definition at line 1806 of file app.c.

References cap, CWIST_ERR_INT16, make_error(), and cwist_app::use_http2.

◆ cwist_app_use_http3()

cwist_error_t cwist_app_use_http3	(	cwist_app *	app,
		bool	enabled
	)

Enable HTTP/3 (QUIC) without manual SSL configuration. Auto-generates an ephemeral self-signed certificate internally.

Parameters

app	Application context.
enabled	True to enable zero-config HTTP/3.

Returns: cwist_error_t Status.

Definition at line 1818 of file app.c.

References cap, CWIST_ERR_INT16, make_error(), and cwist_app::use_http3.

◆ cwist_app_use_https()

cwist_error_t cwist_app_use_https	(	cwist_app *	app,
		const char *	cert_path,
		const char *	key_path
	)

Enable TLS for the application using the supplied certificate pair.

Parameters

app	Application being configured.
cert_path	PEM certificate chain path.
key_path	PEM private key path.

Returns: Tagged CWIST error describing success or failure.

Definition at line 1646 of file app.c.

References cap, cwist_app::cert_path, CWIST_ERR_INT16, cwist_free(), cwist_strdup(), cwist_app::key_path, make_error(), cwist_app::use_http3, cwist_app::use_https3, and cwist_app::use_ssl.

◆ cwist_app_use_https2()

cwist_error_t cwist_app_use_https2	(	cwist_app *	app,
		bool	enabled
	)

Definition at line 1760 of file app.c.

References cap, cwist_app::cert_path, CWIST_ERR_INT16, cwist_app::key_path, make_error(), cwist_app::use_https2, and cwist_app::use_ssl.

◆ cwist_app_use_https3()

cwist_error_t cwist_app_use_https3	(	cwist_app *	app,
		bool	enabled
	)

Definition at line 1783 of file app.c.

References cap, cwist_app::cert_path, CWIST_ERR_INT16, cwist_app::key_path, make_error(), cwist_app::use_https3, and cwist_app::use_ssl.

◆ cwist_app_use_nuke_db()

cwist_error_t cwist_app_use_nuke_db	(	cwist_app *	app,
		const char *	db_path,
		int	sync_interval_ms
	)

Enable NUKE DB and fall back to standard SQLite when RAM bootstrap fails.

Parameters

app	Application being configured.
db_path	On-disk database file to mirror into memory.
sync_interval_ms	Synchronization interval forwarded to NUKE DB.

Returns: Tagged CWIST error describing success or failure.

Definition at line 1890 of file app.c.

References cap, cwist_db::conn, cwist_app_use_db(), cwist_db_close(), CWIST_ERR_INT16, cwist_free(), cwist_nuke_close(), CWIST_NUKE_ERR_LOW_MEMORY, cwist_nuke_get_db(), cwist_nuke_init(), CWIST_NUKE_OK, cwist_strdup(), cwist_app::db, cwist_app::db_path, make_error(), and cwist_app::nuke_enabled.

◆ cwist_app_use_pqc_layer()

void cwist_app_use_pqc_layer	(	cwist_app *	app,
		bool	enabled
	)

Enable Post-Quantum Cryptography (PQC) hybrid key exchange layer.

Parameters

app	Application context.
enabled	True to enable PQC hybrid TLS groups and force TLS 1.3.

Definition at line 1744 of file app.c.

References cwist_app::pqc_layer_enabled.

◆ cwist_app_use_redis()

cwist_error_t cwist_app_use_redis	(	cwist_app *	app,
		const char *	host,
		int	port,
		size_t	max_conns
	)

Configure a Redis connection pool for the application.

Parameters

app	Application context.
host	Redis server host.
port	Redis server port.
max_conns	Maximum number of pooled connections (>= 1).

Definition at line 1989 of file app.c.

References cap, CWIST_ERR_INT16, cwist_redis_pool_create(), cwist_redis_pool_destroy(), make_error(), and cwist_app::redis_pool.

◆ cwist_app_use_scheduler()

cwist_error_t cwist_app_use_scheduler	(	cwist_app *	app,
		size_t	worker_count,
		size_t	queue_capacity
	)

Configure a background job scheduler for the application.

Parameters

app	Application context.
worker_count	Number of background worker threads (>= 1).
queue_capacity	Capacity hint for the underlying job queue.

Definition at line 2020 of file app.c.

References cap, CWIST_ERR_INT16, cwist_scheduler_create(), cwist_scheduler_destroy(), make_error(), and cwist_app::scheduler.

◆ cwist_app_use_webtransport()

void cwist_app_use_webtransport	(	cwist_app *	app,
		cwist_webtransport_handler_func	handler
	)

Enable WebTransport over HTTP/3 on the application.

This registers a WebTransport session handler. The application must also enable HTTP/3 (via cwist_app_use_http3 or cwist_app_use_https3) for WebTransport to function.

Parameters

app	Application context.
handler	WebTransport session handler.

Definition at line 1835 of file app.c.

References cwist_http3_set_webtransport_handler(), cwist_app::h3_ctx, and cwist_app::wt_handler.

◆ cwist_app_ws()

void cwist_app_ws	(	cwist_app *	app,
		const char *	path,
		cwist_ws_handler_func	handler
	)

Register a WebSocket upgrade endpoint with default options.

Parameters

app	Application being configured.
path	Exact GET route that should upgrade to WebSocket.
handler	WebSocket handler invoked after a successful upgrade.

Definition at line 2309 of file app.c.

References cap, CWIST_ENDPOINT_DEFAULT, CWIST_HTTP_GET, and cwist_app::router.

◆ cwist_app_ws_async()

void cwist_app_ws_async	(	cwist_app *	app,
		const char *	path,
		cwist_ws_on_message_t	on_message,
		void *	user_data
	)

Register a callback-shaped non-blocking WebSocket endpoint (C1M mode).

On the C1M reactor path each complete message is delivered through on_message without blocking the worker. In classic mode (thread pool) a route registered only through this function answers 501 Not Implemented; use cwist_app_ws() for the blocking handler API there.

Parameters

app	Application being configured.
path	Exact GET route that should upgrade to WebSocket.
on_message	Callback invoked per complete message on the reactor path.
user_data	Opaque pointer forwarded to the callback.

Definition at line 2330 of file app.c.

References cap, CWIST_ENDPOINT_DEFAULT, CWIST_HTTP_GET, and cwist_app::router.

◆ cwist_app_ws_opt()

void cwist_app_ws_opt	(	cwist_app *	app,
		const char *	path,
		cwist_ws_handler_func	handler,
		cwist_endpoint_opt_t	opts
	)

Register a WebSocket route with explicit endpoint options.

Parameters

app	Application being configured.
path	Exact GET route that should upgrade to WebSocket.
handler	WebSocket handler invoked after a successful upgrade.
opts	Endpoint flags associated with the route.

Definition at line 2402 of file app.c.

References cap, CWIST_ENDPOINT_DEFAULT, CWIST_HTTP_GET, and cwist_app::router.

◆ cwist_apply_profile()

void cwist_apply_profile ( void )

Apply CWIST_PROFILE preset env-var defaults.

Reads CWIST_PROFILE and uses setenv(overwrite=0) to fill in defaults for the relevant tuning variables before cwist_app_listen() reads them. Recognized values: "performance", "lowmem", "lowlat", "default". An unset (or empty) CWIST_PROFILE is treated as "default": C1M mode on and reactor drain chunk 8. Called automatically by cwist_app_listen(); exposed here so tests and tools can invoke it directly before any env-var caches are populated.

Apply CWIST_PROFILE preset env-var defaults.

Profiles: performance - maximize request throughput: C1M enabled, glibc arena cap, tighter reactor drain chunk (8 events between post drains), larger per-turn HTTP batch so a hot connection yields less. lowmem - minimize resident memory: C1M enabled, glibc arena capped, worker count capped at 2 so total RSS scales with fewer processes (throughput trades off against memory). lowlat - minimize per-request latency: classic thread-pool mode, sub-millisecond median at moderate concurrency. default - C1M enabled with reactor drain chunk 8; also applied when CWIST_PROFILE is unset, so the built-in app baseline uses the tighter drain chunk instead of the reactor's 64-event fallback. Explicit env vars still win (overwrite=0).

Definition at line 4593 of file app.c.

References cap.

◆ cwist_create_multiport_from_array()

cwist_multiport_t cwist_create_multiport_from_array	(	const unsigned short *	ports,
		size_t	count
	)

Create a counted multiport descriptor from an explicit pointer and length.

Parameters

ports	Source port array.
count	Number of elements in ports.

Returns: Counted descriptor accepted by cwist_app_multiport().

◆ cwist_multiport_get_app()

cwist_app * cwist_multiport_get_app	(	cwist_app **	app_ref,
		unsigned short	port
	)

Detach one additional multiport port into its own tunable application.

Parameters

app_ref	Address of the root cwist_app pointer.
port	Additional port to detach. The public/default port is rejected by cwist_app_multiport().

Returns: Detached sub-application for per-port tuning, or NULL on allocation failure.

◆ cwist_rdbms_mount_runtime()

bool cwist_rdbms_mount_runtime	(	cwist_app *	app,
		cwist_rdbms_provider_t	provider,
		int	port
	)

Mount an RDBMS runtime for the given provider and port.

Parameters

app	Application context.
provider	Detected provider.
port	Target port.

Returns: true on success, false on failure.

Mount an RDBMS runtime for the given provider and port.

Idempotent: if app already has an RDBMS runtime mounted, this returns true without allocating. On success the new runtime is stored in app->rdbms with ready set to true.

Parameters

app	App to attach the runtime to; must not be NULL.
provider	Detected provider stored in the runtime.
port	Port the provider was detected on.

Returns: true if a runtime is mounted, false on NULL app or allocation failure.

Definition at line 155 of file rdbms_auto_mount.c.

References cap, cwist_alloc_array(), CWIST_LOG_ERROR, CWIST_LOG_INFO, cwist_rdbms_runtime::port, cwist_rdbms_runtime::provider, and cwist_app::rdbms.

Referenced by cwist_app_auto_rdbms().

◆ cwist_rdbms_probe_port()

cwist_rdbms_provider_t cwist_rdbms_probe_port ( int port )

Probe a TCP port for an RDBMS wire protocol.

Parameters

port	TCP port to probe.

Returns: Detected provider, or CWIST_RDBMS_UNKNOWN.

Probe a TCP port for an RDBMS wire protocol.

Connects to the given port with a 2-second send/recv timeout, inspects any unsolicited handshake bytes as a MySQL/MariaDB handshake, and if that does not match, sends a PostgreSQL StartupMessage and waits for an AuthenticationRequest response.

Parameters

port	TCP port on localhost to probe.

Returns: Detected provider (CWIST_RDBMS_MYSQL, CWIST_RDBMS_MARIADB, or CWIST_RDBMS_POSTGRES) or CWIST_RDBMS_NONE if detection fails. The socket is always closed before returning.

Definition at line 83 of file rdbms_auto_mount.c.

References cap, CWIST_LOG_ERROR, CWIST_RDBMS_NONE, and CWIST_RDBMS_POSTGRES.

Referenced by cwist_app_auto_rdbms().

◆ cwist_stream_req_begin()

cwist_stream_req_t * cwist_stream_req_begin	(	const char *	head,
		size_t	head_len
	)

Begin an incremental request: head is the serialized request line plus headers (everything up to and including the terminating CRLF of the header block). The body length is taken from Content-Length (required for fed bodies; Transfer-Encoding: chunked is not reassembled).

Returns: Handle on success, NULL on allocation failure.

Definition at line 2600 of file app.c.

References cap, cwist_alloc(), cwist_free(), CWIST_STREAM_REQ_EAGER_MAX, and head.

◆ cwist_stream_req_dispatch()

int cwist_stream_req_dispatch	(	cwist_stream_req_t *	req,
		cwist_app *	app,
		cwist_stream_write_fn	write_fn,
		void *	write_ctx
	)

Dispatch a completed incremental request with a streaming response. Takes ownership of req regardless of outcome.

Returns: As cwist_app_dispatch_stream(); -1 also when cwist_stream_req_end() has not succeeded (the fed body is incomplete).

Definition at line 2653 of file app.c.

References cap, cwist_app_dispatch_stream(), and cwist_free().

◆ cwist_stream_req_end()

int cwist_stream_req_end ( cwist_stream_req_t * req )

Declare the body complete. The fed byte count must equal the declared Content-Length (or both be zero for a bodyless request).

Returns: 0 on success, -1 on a short body.

Definition at line 2646 of file app.c.

◆ cwist_stream_req_feed()

int cwist_stream_req_feed	(	cwist_stream_req_t *	req,
		const char *	chunk,
		size_t	len
	)

Feed one body chunk. Chunks may be any size and may split anywhere; reassembly is the implementation's job. Feeding more bytes than the declared Content-Length is an error.

Returns: 0 on success, -1 on overflow/malformed state.

Definition at line 2626 of file app.c.

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

◆ cwist_url_for()

char * cwist_url_for	(	cwist_app *	app,
		const char *	name,
		cwist_query_map *	params
	)

Definition at line 2475 of file app.c.

References cap, cwist_query_map_get(), cwist_sstring_append(), cwist_sstring_create(), cwist_sstring_destroy(), cwist_strdup(), cwist_sstring::data, and cwist_app::router.

Classes

Macros

Typedefs

Enumerations

Functions

Startup

Detailed Description

Macro Definition Documentation

◆ cwist_create_multiport

◆ CWIST_MULTIPORT_MAX_PORTS

◆ CWIST_STREAM_CHUNK

◆ cwist_use_http2

◆ cwist_use_http3

◆ cwist_use_https2

◆ cwist_use_https3

Typedef Documentation

◆ cwist_app

◆ cwist_config

◆ cwist_error_handler_entry

◆ cwist_error_handler_func

◆ cwist_file_t

◆ cwist_fix_server_mem

◆ cwist_handler_ctx_destroy_func

◆ cwist_handler_ex_func

◆ cwist_handler_func

◆ cwist_https_request_handler_func

◆ cwist_logger

◆ cwist_middleware_ctx_destroy_func

◆ cwist_middleware_func

◆ cwist_middleware_func_ex

◆ cwist_middleware_node

◆ cwist_multiport_t

◆ cwist_rdbms_provider_t

◆ cwist_rdbms_runtime

◆ cwist_route_table

◆ cwist_static_dir

◆ cwist_stream_req_t

◆ cwist_stream_write_fn

◆ cwist_webtransport_handler_func

◆ cwist_ws_handler_func

Enumeration Type Documentation

◆ cwist_rdbms_provider

Function Documentation

◆ cwist_app_auto_rdbms()

◆ cwist_app_configure_bdr()

◆ cwist_app_create()

◆ cwist_app_delete()

◆ cwist_app_delete_ex()

◆ cwist_app_delete_named()

◆ cwist_app_delete_opt()

◆ cwist_app_destroy()

◆ cwist_app_dispatch()

◆ cwist_app_dispatch_memory()

◆ cwist_app_dispatch_stream()

◆ cwist_app_enable_healthz()

◆ cwist_app_enable_metrics()

◆ cwist_app_enable_swagger()

◆ cwist_app_get()

◆ cwist_app_get_db()

◆ cwist_app_get_db_pool()

◆ cwist_app_get_ex()

◆ cwist_app_get_named()

◆ cwist_app_get_opt()

◆ cwist_app_get_redis_pool()

◆ cwist_app_get_scheduler()

◆ cwist_app_http_handler()

◆ cwist_app_http_handler_async()

◆ cwist_app_listen()

◆ cwist_app_listen_ex()

◆ cwist_app_multiport()

◆ cwist_app_patch()

◆ cwist_app_patch_ex()

◆ cwist_app_patch_named()

◆ cwist_app_patch_opt()

◆ cwist_app_post()

◆ cwist_app_post_ex()

◆ cwist_app_post_named()

◆ cwist_app_post_opt()

◆ cwist_app_put()

◆ cwist_app_put_ex()