diff --git a/TODO.txt b/TODO.txt index 1cad971..5e0488f 100644 --- a/TODO.txt +++ b/TODO.txt @@ -35,7 +35,7 @@ Due: January 1, 2023 [x] Log [x] Matrix [x] Queue - [ ] Routes + [x] Routes [x] TelodendriaConfig [x] Util [x] Memory diff --git a/man/man3/Routes.3 b/man/man3/Routes.3 new file mode 100644 index 0000000..3ad3a1c --- /dev/null +++ b/man/man3/Routes.3 @@ -0,0 +1,87 @@ +.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 diff --git a/site/index.html b/site/index.html index ee0cd9c..7a0b4de 100644 --- a/site/index.html +++ b/site/index.html @@ -253,6 +253,12 @@ Parse the configuration file into a structure. Functions for writing Matrix API endpoints. + +Routes(3) + +Matrix API endpoint abstractions. + +

Resources