Document Routes

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

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

site/index.html

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

src/include/Routes.h

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