mux.h File Reference

HTTP request multiplexer (router). More...

#include <cwist/net/http/http.h>
#include <cwist/sys/app/app.h>
#include <cwist/core/sstring/sstring.h>
#include <stdint.h>

Include dependency graph for mux.h:

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

Go to the source code of this file.

Classes
struct	cwist_mux_middleware_node
struct	cwist_mux_route
struct	cwist_mux_router
struct	cwist_mux_group

Typedefs
typedef void(*	cwist_http_handler_func) (cwist_http_request *req, cwist_http_response *res)
typedef struct cwist_mux_middleware_node	cwist_mux_middleware_node
typedef struct cwist_mux_route	cwist_mux_route
typedef struct cwist_mux_router	cwist_mux_router
typedef struct cwist_mux_group	cwist_mux_group

Functions
Lifecycle
cwist_mux_router *	cwist_mux_router_create (void)
	Create a new router.
void	cwist_mux_router_destroy (cwist_mux_router *router)
	Destroy a router and all its routes.
Route Management
void	cwist_mux_handle (cwist_mux_router *router, cwist_http_method_t method, const char *path, cwist_http_handler_func handler)
	Register a route handler.
cwist_mux_route *	cwist_mux_find_route (cwist_mux_router *router, cwist_http_method_t method, const char *path)
	Find a matching route.
Route Groups
cwist_mux_group *	cwist_mux_group_create (cwist_mux_router *router, const char *prefix)
	Create a route group with a path prefix.
void	cwist_mux_group_destroy (cwist_mux_group *group)
	Destroy a route group.
void	cwist_mux_group_handle (cwist_mux_group *group, cwist_http_method_t method, const char *path, cwist_http_handler_func handler)
	Register a handler inside a group.
Per-Route Middleware
void	cwist_mux_route_use (cwist_mux_route *route, cwist_middleware_func mw)
	Attach middleware to a specific route.
Dispatch
bool	cwist_mux_serve (cwist_mux_router *router, cwist_http_request *req, cwist_http_response *res)
	Dispatches an HTTP request through the router.

Detailed Description

HTTP request multiplexer (router).

Definition in file mux.h.

Typedef Documentation

cwist_http_handler_func

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

— Mux Router —

Definition at line 16 of file mux.h.

cwist_mux_group

typedef struct cwist_mux_group cwist_mux_group

cwist_mux_middleware_node

typedef struct cwist_mux_middleware_node cwist_mux_middleware_node

cwist_mux_route

typedef struct cwist_mux_route cwist_mux_route

cwist_mux_router

typedef struct cwist_mux_router cwist_mux_router

Function Documentation

cwist_mux_find_route()

cwist_mux_route * cwist_mux_find_route	(	cwist_mux_router *	router,
		cwist_http_method_t	method,
		const char *	path
	)

Find a matching route.

Find a matching route.

Parameters

router	Router whose exact and parametric routes are searched.
method	HTTP method to match.
path	Request path to resolve; NULL is treated as the root.

Returns

Matching route record, or NULL when no exact or parametric route matches.

Note

Wildcard routes are not considered by this lookup.

Definition at line 325 of file mux.c.

References cwist_mux_route::bucket_next, cwist_mux_router::buckets, cap, cwist_query_map_destroy(), and cwist_mux_router::param_routes.

cwist_mux_group_create()

cwist_mux_group * cwist_mux_group_create	(	cwist_mux_router *	router,
		const char *	prefix
	)

Create a route group with a path prefix.

Create a route group with a path prefix.

Parameters

router	Router that will own the routes registered through the group.
prefix	Path prefix prepended to every route path registered on the group.

Returns

Newly allocated group, or NULL when an argument is NULL or allocation fails.

Definition at line 361 of file mux.c.

References cap, cwist_alloc(), cwist_free(), and cwist_mux_group::router.

cwist_mux_group_destroy()

void cwist_mux_group_destroy

(

cwist_mux_group *

group

)

Destroy a route group.

Destroy a route group.

Parameters

group

Group to destroy. NULL is ignored.

Note

Only the group record is freed; routes registered through the group remain owned by the router and are released by cwist_mux_router_destroy().

Definition at line 381 of file mux.c.

References cap, and cwist_free().

cwist_mux_group_handle()

void cwist_mux_group_handle	(	cwist_mux_group *	group,
		cwist_http_method_t	method,
		const char *	path,
		cwist_http_handler_func	handler
	)

Register a handler inside a group.

Register a handler inside a group.

Parameters

group	Group supplying the path prefix and target router.
method	HTTP method to match.
path	Route path relative to the group prefix; the two are concatenated verbatim.
handler	Callback to invoke for a matching request.

Note

Invalid arguments (NULL group, router, path, or handler) are silently ignored, as is an allocation failure while building the full path.

Definition at line 396 of file mux.c.

References cap, cwist_alloc(), CWIST_DEFER_FREE, and cwist_mux_handle().

cwist_mux_handle()

void cwist_mux_handle	(	cwist_mux_router *	router,
		cwist_http_method_t	method,
		const char *	path,
		cwist_http_handler_func	handler
	)

Register a route handler.

Register a route handler.

Parameters

router	Router that will own the route metadata.
method	HTTP method to match.
path	Exact request path to dispatch.
handler	Callback to invoke for a matching request.

Definition at line 160 of file mux.c.

Referenced by cwist_mux_group_handle().

cwist_mux_route_use()

void cwist_mux_route_use	(	cwist_mux_route *	route,
		cwist_middleware_func	mw
	)

Attach middleware to a specific route.

Attach middleware to a specific route.

Parameters

route	Route to attach the middleware to. NULL is ignored.
mw	Middleware function to prepend to the route's chain. NULL is ignored.

Note

Middleware runs in most-recently-added-first order because each node is prepended to the head of the list. An allocation failure is silently ignored.

Definition at line 418 of file mux.c.

References cap, cwist_alloc(), cwist_mux_middleware_node::func, and cwist_mux_middleware_node::next.

cwist_mux_router_create()

cwist_mux_router * cwist_mux_router_create

(

void

)

Create a new router.

Create a new router.

Returns

Newly allocated router, or NULL when allocation fails.

Definition at line 113 of file mux.c.

cwist_mux_router_destroy()

void cwist_mux_router_destroy

(

cwist_mux_router *

router

)

Destroy a router and all its routes.

Destroy a router and all its routes.

Destroy a router.

Parameters

router

Router to destroy. NULL is ignored.

Definition at line 134 of file mux.c.

cwist_mux_serve()

bool cwist_mux_serve	(	cwist_mux_router *	router,
		cwist_http_request *	req,
		cwist_http_response *	res
	)

Dispatches an HTTP request through the router.

Returns

True if a route was found and executed, false otherwise (404).

Dispatches an HTTP request through the router.

Dispatch a request.

Parameters

router	Router containing registered exact-match handlers.
req	Parsed HTTP request with method and path information.
res	HTTP response object passed through to the matched handler.

Returns

true when a route was found and its handler was executed, otherwise false.

Definition at line 435 of file mux.c.