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_route_streaming (KlServer *s, const char *method, const char *pattern, KlHandler handler, void *user_data, KlBodyReaderFactory body_reader)
	Register a streaming-handler route. The handler runs after the body reader is set up but BEFORE the body is fully received, so it can pull bytes incrementally (e.g. via the streaming multipart iterator) and yield mid-stream. The body reader's on_data callback is responsible for resuming the yielded handler.
int	kl_server_route_streaming_async (KlServer *s, const char *method, const char *pattern, KlHandler handler, void *user_data, KlBodyReaderFactory body_reader)
	Register an async-streaming-handler route (v2.2.0+).
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_route_streaming()

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

Register a streaming-handler route. The handler runs after the body reader is set up but BEFORE the body is fully received, so it can pull bytes incrementally (e.g. via the streaming multipart iterator) and yield mid-stream. The body reader's on_data callback is responsible for resuming the yielded handler.

Post-body middleware does NOT run for streaming routes. A non-NULL body_reader factory is required.

Returns

0 on success, -1 on failure.

kl_server_route_streaming_async()

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

Register an async-streaming-handler route (v2.2.0+).

   Like kl_server_route_streaming, plus the handler is invoked
   BEFORE any leftover body bytes are fed via on_data. The
   handler MUST yield on NEED_DATA — the body reader's on_data
   callback resumes it for the leftover and subsequent reads.

   Enables the full error-path mid-stream early-exit: caps
   that fire during leftover processing now resume the parked
   handler via on_error so it can write a structured response,
   instead of clobbering with the hardcoded 413.

   Synchronous C handlers that need the body fully buffered
   before they run should keep using kl_server_route_streaming.

   See router.h::kl_router_add_streaming_async for the full
   contract.

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).