forked from Telodendria/Telodendria
Document Routes
This commit is contained in:
parent
e7030ec57a
commit
e17b64dcb2
4 changed files with 99 additions and 19 deletions
2
TODO.txt
2
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
|
||||
|
|
87
man/man3/Routes.3
Normal file
87
man/man3/Routes.3
Normal 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
|
|
@ -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>
|
||||
|
|
|
@ -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
|
||||
|
|
Loading…
Reference in a new issue