Document Routes

This commit is contained in:
Jordan Bancino 2022-12-12 17:34:59 +00:00
parent e7030ec57a
commit e17b64dcb2
4 changed files with 99 additions and 19 deletions

View file

@ -35,7 +35,7 @@ Due: January 1, 2023
[x] Log
[x] Matrix
[x] Queue
[ ] Routes
[x] Routes
[x] TelodendriaConfig
[x] Util
[x] Memory

87
man/man3/Routes.3 Normal file
View file

@ -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

View file

@ -253,6 +253,12 @@ Parse the configuration file into a structure.
Functions for writing Matrix API endpoints.
</td>
</tr>
<tr>
<td><a href="man/man3/Routes.3.html">Routes(3)</a></td>
<td>
Matrix API endpoint abstractions.
</td>
</tr>
</table>
<h2 id="resources">Resources</h2>
<ul>

View file

@ -31,21 +31,6 @@
#include <HttpServer.h>
#include <Matrix.h>
/*
* Abstract away the underlying data structure of the path so that
* routes don't have to care what it is.
*
* This will be helpful, for instance, if we decide to switch to a
* queue (which can easily be done with the current implementation if
* we just add a function that computes how many elements are in a
* queue.) An array isn't the most efficient data structure for this
* purpose; a queue would be much better. This allows us to change that
* down the road without having to rewrite all the routes.
*
* One tricky thing about the current Queue implementation is that it
* is a fixed-size queue, so we'd either need to make it large enough
* to accomodate large paths, or rewrite it to be dynamically-sized.
*/
#define MATRIX_PATH Array
#define MATRIX_PATH_CREATE() ArrayCreate()
#define MATRIX_PATH_APPEND(path, part) ArrayAdd(path, part)
@ -72,8 +57,10 @@ typedef struct RouteArgs
HashMap * \
name(RouteArgs * argsName)
ROUTE(RouteWellKnown);
ROUTE(RouteMatrix);
ROUTE(RouteLogin);
ROUTE(RouteWellKnown); /* /.well-known */
ROUTE(RouteMatrix); /* /_matrix */
ROUTE(RouteLogin); /* /_matrix/client/(r0|v3)/login */
#undef ROUTE
#endif