server.h File Reference

#include <keel/allocator.h>
#include <keel/compress.h>
#include <keel/error.h>
#include <keel/parser.h>
#include <keel/router.h>
#include <keel/tls.h>
#include <keel/h2_server.h>
#include <keel/connection.h>
#include <keel/event_ctx.h>
#include <stdarg.h>
#include <stdatomic.h>
#include <stdint.h>

Include dependency graph for server.h:

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

Go to the source code of this file.

Data Structures
struct	KlConfig
struct	KlServer
struct	KlServerStats
	Server load statistics — read-only snapshot for load-shedding decisions. More...

Macros
#define	KL_DEFAULT_MAX_CONNS   256
	Default max connections.
#define	KL_DEFAULT_READ_TIMEOUT   30000
	Default read timeout (ms).
#define	KL_DEFAULT_MAX_BODY_SIZE   (1024 * 1024)
	Default max body size.
#define	KL_LOG_TRACE   0
	Log levels (values match rxi/log.c for zero-cost bridging).
#define	KL_LOG_DEBUG   1
#define	KL_LOG_INFO   2
#define	KL_LOG_WARN   3
#define	KL_LOG_ERROR   4
#define	KL_LOG_FATAL   5

Typedefs
typedef struct KlWsServerConfig	KlWsServerConfig
typedef KlParser *(*	KlParserFactory) (KlAllocator *alloc)
	Factory function for creating request parsers.
typedef void(*	KlAccessLogFn) (const KlRequest *req, int status, size_t body_bytes, double duration_ms, void *user_data)
	Access log callback — called after each response is fully sent. NULL = disabled.
typedef void(*	KlLogFn) (int level, const char *fmt, va_list ap, void *user_data)
	Diagnostic log callback. NULL = fprintf(stderr) fallback.
typedef struct KlConfig	KlConfig
typedef struct KlAsyncOp	KlAsyncOp
typedef struct KlServer	KlServer

Functions
int	kl_server_init (KlServer *s, const KlConfig *config)
	Initialize server with the given configuration.
int	kl_server_route (KlServer *s, const char *method, const char *pattern, KlHandler handler, void *user_data, KlBodyReaderFactory body_reader)
	Register a route on the server.
int	kl_server_use (KlServer *s, const char *method, const char *pattern, KlMiddleware fn, void *user_data)
	Register pre-body middleware on the server.
int	kl_server_use_post (KlServer *s, const char *method, const char *pattern, KlMiddleware fn, void *user_data)
	Register post-body middleware on the server.
int	kl_server_ws (KlServer *s, const char *pattern, KlWsServerConfig *config)
	Register a WebSocket endpoint. Matches GET with Upgrade: websocket.
int	kl_server_run (KlServer *s)
	Start the event loop (blocks until stopped).
void	kl_server_stop (KlServer *s)
	Request server shutdown. If drain_timeout_ms is configured, enters drain mode first (stops accepting, waits for in-flight).
void	kl_server_free (KlServer *s)
	Free all server resources (pool, router, event loop).
void	kl_server_stats (const KlServer *s, KlServerStats *out)
	Populate a stats snapshot from current server state.

Macro Definition Documentation

KL_LOG_TRACE

#define KL_LOG_TRACE   0

Log levels (values match rxi/log.c for zero-cost bridging).

Trace

KL_LOG_DEBUG

#define KL_LOG_DEBUG   1

Debug

KL_LOG_INFO

#define KL_LOG_INFO   2

Info

KL_LOG_WARN

#define KL_LOG_WARN   3

Warning

KL_LOG_ERROR

#define KL_LOG_ERROR   4

Error

KL_LOG_FATAL

#define KL_LOG_FATAL   5

Fatal

KL_DEFAULT_MAX_CONNS

#define KL_DEFAULT_MAX_CONNS   256

Default max connections.

KL_DEFAULT_READ_TIMEOUT

#define KL_DEFAULT_READ_TIMEOUT   30000

Default read timeout (ms).

ms

KL_DEFAULT_MAX_BODY_SIZE

#define KL_DEFAULT_MAX_BODY_SIZE   (1024 * 1024)

Default max body size.

1 MB

Typedef Documentation

KlWsServerConfig

typedef struct KlWsServerConfig KlWsServerConfig

KlParserFactory

typedef KlParser *(* KlParserFactory) (KlAllocator *alloc)

Factory function for creating request parsers.

KlAccessLogFn

typedef void(* KlAccessLogFn) (const KlRequest *req, int status, size_t body_bytes, double duration_ms, void *user_data)

Access log callback — called after each response is fully sent. NULL = disabled.

KlLogFn

typedef void(* KlLogFn) (int level, const char *fmt, va_list ap, void *user_data)

Diagnostic log callback. NULL = fprintf(stderr) fallback.

KlConfig

typedef struct KlConfig KlConfig

KlAsyncOp

typedef struct KlAsyncOp KlAsyncOp

KlServer

typedef struct KlServer KlServer

Function Documentation

kl_server_init()

int kl_server_init	(	KlServer *	s,
		const KlConfig *	config
	)

Initialize server with the given configuration.

Parameters

s	Server instance.
config	Configuration (defaults applied for zero fields).

Returns

0 on success, -1 on failure.

kl_server_route()

int kl_server_route	(	KlServer *	s,
		const char *	method,
		const char *	pattern,
		KlHandler	handler,
		void *	user_data,
		KlBodyReaderFactory	body_reader
	)

Register a route on the server.

Returns

0 on success, -1 on failure.

kl_server_use()

int kl_server_use	(	KlServer *	s,
		const char *	method,
		const char *	pattern,
		KlMiddleware	fn,
		void *	user_data
	)

Register pre-body middleware on the server.

Parameters

s	Server instance.
method	HTTP method filter ("GET", "POST", "*" for any).
pattern	URL pattern — exact or prefix with trailing slash-star.
fn	Middleware function. Return 0 to continue, non-zero to short-circuit.
user_data	Passed to fn on each invocation.

Returns

0 on success, -1 on failure.

kl_server_use_post()

int kl_server_use_post	(	KlServer *	s,
		const char *	method,
		const char *	pattern,
		KlMiddleware	fn,
		void *	user_data
	)

Register post-body middleware on the server.

Runs after body reading completes. Can access req->body_reader data. Short-circuiting preserves keep_alive (body already consumed).

Parameters

s	Server instance.
method	HTTP method filter ("GET", "POST", "*" for any).
pattern	URL pattern — exact or prefix with trailing slash-star.
fn	Middleware function. Return 0 to continue, non-zero to short-circuit.
user_data	Passed to fn on each invocation.

Returns

0 on success, -1 on failure.

kl_server_ws()

int kl_server_ws	(	KlServer *	s,
		const char *	pattern,
		KlWsServerConfig *	config
	)

Register a WebSocket endpoint. Matches GET with Upgrade: websocket.

Parameters

s	Server instance.
pattern	URL pattern to match.
config	WebSocket configuration (callbacks, limits). Must remain valid.

Returns

0 on success, -1 on failure.

kl_server_run()

int kl_server_run

(

KlServer *

s

)

Start the event loop (blocks until stopped).

Returns

0 on clean shutdown, -1 on fatal error.

kl_server_stop()

void kl_server_stop

(

KlServer *

s

)

Request server shutdown. If drain_timeout_ms is configured, enters drain mode first (stops accepting, waits for in-flight).

kl_server_free()

void kl_server_free

(

KlServer *

s

)

Free all server resources (pool, router, event loop).

kl_server_stats()

void kl_server_stats	(	const KlServer *	s,
		KlServerStats *	out
	)

Populate a stats snapshot from current server state.

Parameters

s	Server instance (may be NULL — zeroes out).
out	Output struct (may be NULL — no-op).