.Dd $Mdocdate: December 12 2022 $
.Dt ROUTES 3
.Os Telodendria Project
.Sh NAME
.Nm Routes
.Nd Matrix API endpoint abstractions.
.Sh SYNOPSIS
.In Routes.h
.Ft char *
.Fn MATRIX_PATH_POP "MATRIX_PATH"
.Ft size_t
.Fn MATRIX_PATH_PARTS "MATRIX_PATH"
.Ft int
.Fn MATRIX_PATH_EQUALS "char *" "char *"
.Sh DESCRIPTION
.Pp
.Nm
provides all of the Matrix API route functions, as well as a few
helpful macros to be used to declare those route functions, and some
macros that are intended to be used inside them.
.Pp
The route macros are intended to increase the readability of the header,
so the individual routes are not documented here; only the helper
macros and structures are documented here. Consult the
.Pa Routes.h
file for a list of the registered route functions.
.Pp
.Fn MATRIX_PATH_POP
and
.Fn MATRIX_PATH_PARTS
are macros that abstract away the underlying data structure of the
path so that that routes don't have to care what it is. The reason
this design choice was made was so that the data structure can be
switched out without breaking all the routes. These macros should
be preferred to the actual underlying data structure functions,
because the data structure may change in the future.
.Pp
At the moment, the path data structure is just an array, but it would
be much more efficient to switch to a queue (which can be easily done
with the current Queue implementation if we just add a function that
computes how many elements are in the queue.) 
.Pp
.Fn MATRIX_PATH_POP
returns the next available part of the path, and removes it from
the path such that the next call to
.Fn MATRIX_PATH_POP
returns the part after.
.Fn MATRIX_PATH_PARTS
returns the number of path parts remaining.
.Pp
.Fn MATRIX_PATH_EQUALS
is just a simple string comparison macro. It takes two strings and
returns a boolean value indicating whether or not they're equal.
.Pp
.Nm
also defines
.Fn ROUTE
and
.Fn ROUTE_IMPL .
.Fn ROUTE
is intended to be used only inside the route header, and should be
invoked to declare a new route function prototype. It takes the
route function name, which by convention starts with "Route".
.Fn ROUTE_IMPL
may be used to actually implement a route function. It takes the
route function name, and the name of the variable to put the
RouteArgs in.
.Pp
Every route function takes a RouteArgs structure, which is defined
as follows:
.Bd -literal -offset indent
typedef struct RouteArgs
{
	MatrixHttpHandlerArgs *matrixArgs;
	HttpServerContext *context;
	MATRIX_PATH *path;
} RouteArgs;
.Ed
.Sh RETURN VALUES
.Pp
Each route returns a JSON hash map that contains the response it
intends to return to the client making the request. Routes
should NOT return NULL, because then no body will be returned to
the client, and that is almost always a bug. The Matrix specification
usually mandates that at least an empty JSON object is returned.
.Sh SEE ALSO
.Xr Matrix 3