router.h File Reference

#include <keel/allocator.h>
#include <keel/request.h>
#include <keel/response.h>
#include <keel/body_reader.h>
#include <stddef.h>

Include dependency graph for router.h:

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

Go to the source code of this file.

Data Structures
struct	KlRoute
struct	KlMiddlewareEntry
struct	KlRouter

Typedefs
typedef void(*	KlHandler) (KlRequest *req, KlResponse *res, void *user_data)
	Route handler function.
typedef int(*	KlMiddleware) (KlRequest *req, KlResponse *res, void *user_data)
	Middleware function signature.
typedef struct KlWsServerConfig	KlWsServerConfig
typedef struct KlRouter	KlRouter

Functions
int	kl_router_init (KlRouter *r, KlAllocator *alloc)
	Initialize a router with an empty route table.
int	kl_router_add (KlRouter *r, const char *method, const char *pattern, KlHandler handler, void *user_data, KlBodyReaderFactory body_reader)
	Register a route. Pattern supports :param segments (e.g. "/users/:id").
int	kl_router_match (KlRouter *r, const char *method, size_t method_len, const char *path, size_t path_len, KlRoute **matched, KlParam *params, int *num_params)
	Match a request against registered routes. HEAD requests automatically fall back to GET routes.
int	kl_router_use (KlRouter *r, const char *method, const char *pattern, KlMiddleware fn, void *user_data)
	Register pre-body middleware that runs before body reading.
int	kl_router_use_post (KlRouter *r, const char *method, const char *pattern, KlMiddleware fn, void *user_data)
	Register post-body middleware that runs after body reading.
int	kl_router_run_middleware (KlRouter *r, KlRequest *req, KlResponse *res)
	Run all matching pre-body middleware in registration order.
int	kl_router_run_post_middleware (KlRouter *r, KlRequest *req, KlResponse *res)
	Run all matching post-body middleware in registration order.
void	kl_router_free (KlRouter *r)
	Free router resources.

Typedef Documentation

KlHandler

typedef void(* KlHandler) (KlRequest *req, KlResponse *res, void *user_data)

Route handler function.

KlMiddleware

typedef int(* KlMiddleware) (KlRequest *req, KlResponse *res, void *user_data)

Middleware function signature.

Returns

0 to continue to next middleware/handler, non-zero to short-circuit (response must already be written by the middleware).

KlWsServerConfig

typedef struct KlWsServerConfig KlWsServerConfig

KlRouter

typedef struct KlRouter KlRouter

Function Documentation

kl_router_init()

int kl_router_init	(	KlRouter *	r,
		KlAllocator *	alloc
	)

Initialize a router with an empty route table.

Parameters

r	Router to initialize.
alloc	Allocator for route table growth.

Returns

0 on success, -1 on allocation failure.

kl_router_add()

int kl_router_add	(	KlRouter *	r,
		const char *	method,
		const char *	pattern,
		KlHandler	handler,
		void *	user_data,
		KlBodyReaderFactory	body_reader
	)

Register a route. Pattern supports :param segments (e.g. "/users/:id").

Parameters

r	Router instance.
method	HTTP method ("GET", "POST", "*" for any).
pattern	URL pattern to match.
handler	Handler function invoked on match.
user_data	Passed to handler and body reader factory.
body_reader	Factory for body reader, or NULL to discard body.

Returns

0 on success, -1 on allocation failure.

kl_router_match()

int kl_router_match	(	KlRouter *	r,
		const char *	method,
		size_t	method_len,
		const char *	path,
		size_t	path_len,
		KlRoute **	matched,
		KlParam *	params,
		int *	num_params
	)

Match a request against registered routes. HEAD requests automatically fall back to GET routes.

Parameters

r	Router instance.
method	Request method string.
method_len	Length of method string.
path	Request path string.
path_len	Length of path string.
matched	Receives the matched route, or NULL.
params	Receives extracted :param values.
num_params	Receives the number of extracted params.

Returns

200 on match, 404 if no path matches, 405 if path matches but method doesn't.

kl_router_use()

int kl_router_use	(	KlRouter *	r,
		const char *	method,
		const char *	pattern,
		KlMiddleware	fn,
		void *	user_data
	)

Register pre-body middleware that runs before body reading.

Parameters

r	Router instance.
method	HTTP method filter ("GET", "POST", "*" for any).
pattern	URL pattern — exact match 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 allocation failure.

kl_router_use_post()

int kl_router_use_post	(	KlRouter *	r,
		const char *	method,
		const char *	pattern,
		KlMiddleware	fn,
		void *	user_data
	)

Register post-body middleware that runs after body reading.

Post-body middleware can access req->body_reader data. Short-circuiting preserves keep_alive since the body has already been consumed.

Parameters

r	Router instance.
method	HTTP method filter ("GET", "POST", "*" for any).
pattern	URL pattern — exact match 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 allocation failure.

kl_router_run_middleware()

int kl_router_run_middleware	(	KlRouter *	r,
		KlRequest *	req,
		KlResponse *	res
	)

Run all matching pre-body middleware in registration order.

Returns

0 if all passed, non-zero if a middleware short-circuited.

kl_router_run_post_middleware()

int kl_router_run_post_middleware	(	KlRouter *	r,
		KlRequest *	req,
		KlResponse *	res
	)

Run all matching post-body middleware in registration order.

Returns

0 if all passed, non-zero if a middleware short-circuited.

kl_router_free()

void kl_router_free

(

KlRouter *

r

)

Free router resources.