Document Matrix.h

TODO.txt

@@ -33,7 +33,7 @@ Due: January 1, 2023
 		[ ] HttpServer
 		[x] Json
 		[x] Log
-		[ ] Matrix
+		[x] Matrix
 		[x] Queue
 		[ ] Routes
 		[x] TelodendriaConfig

man/man3/Matrix.3

@@ -0,0 +1,89 @@
+.Dd $Mdocdate: December 12 2022 $
+.Dt MATRIX 3
+.Os Telodendria Project
+.Sh NAME
+.Nm Matrix
+.Nd Functions for writing Matrix API endpoints.
+.Sh SYNOPSIS
+.In Matrix.h
+.Ft void
+.Fn MatrixHttpHandler "HttpServerContext *" "void *"
+.Ft void
+.Fn MatrixErrorCreate "MatrixError"
+.Sh DESCRIPTION
+.Nm
+provides some helper functions that bind to the
+.Xr HttpServer 3
+interface and add basic Matrix functionality, turning an
+HTTP server into a Matrix homeserver.
+.Pp
+.Xr MatrixHttpHandler
+is the HTTP handler function that handles all Matrix homeserver
+functionality. It should be passed into
+.Fn HttpServerCreate ,
+and it expects that an instance of MatrixHttpHandlerArgs will also
+be provided, because that's what the void pointer is cast to.
+That structure is defined as follows:
+.Bd -literal -offset indent
+typedef struct MatrixHttpHandlerArgs
+{
+	LogConfig *lc;
+	TelodendriaConfig *config;
+	Db *db;
+} MatrixHttpHandlerArgs;
+.Ed
+.Pp
+This structure should be populated once and then never modified again
+for the duration of the HTTP server.
+.Pp
+.Fn MatrixErrorCreate
+is a convenience function that constructs an error payload, including
+the error code and message, given just a MatrixError. MatrixErrors
+exactly follow the errors in the Matrix specification, and are
+defined as follows:
+.Bd -literal -offset indent
+typedef enum MatrixError
+{
+	M_FORBIDDEN,
+	M_UNKNOWN_TOKEN,
+	M_MISSING_TOKEN,
+	M_BAD_JSON,
+	M_NOT_JSON,
+	M_NOT_FOUND,
+	M_LIMIT_EXCEEDED,
+	M_UNKNOWN,
+	M_UNRECOGNIZED,
+	M_UNAUTHORIZED,
+	M_USER_DEACTIVATED,
+	M_USER_IN_USE,
+	M_INVALID_USERNAME,
+	M_ROOM_IN_USE,
+	M_IVALID_ROOM_STATE,
+	M_THREEPID_IN_USE,
+	M_THREEPID_NOT_FOUND,
+	M_THREEPID_AUTH_FAILED,
+	M_THREEPID_DENIED,
+	M_SERVER_NOT_TRUSTED,
+	M_UNSUPPORTED_ROOM_VERSION,
+	M_BAD_STATE,
+	M_GUEST_ACCESS_FORBIDDEN,
+	M_CAPTCHA_NEEDED,
+	M_CAPTCHA_INVALID,
+	M_MISSING_PARAM,
+	M_INVALID_PARAM,
+	M_TOO_LARGE,
+	M_EXCLUSIVE,
+	M_RESOURCE_LIMIT_EXCEEDED,
+	M_CANNOT_LEAVE_SERVER_NOTICE_ROOM
+} MatrixError;
+.Ed
+.Sh RETURN VALUES
+.Pp
+.Fn MatrixErrorCreate
+returns a JSON object that represents the given error code. It can be
+immediately returned as the HTTP response body, or modified as needed.
+.Sh SEE ALSO
+.Xr HttpServer 3 ,
+.Xr Log 3 ,
+.Xr TelodendriaConfig 3 ,
+.Xr Db 3

site/index.html

@@ -247,6 +247,12 @@ An extension to the Json API that implements Matrix's canonical JSON.
 Parse the configuration file into a structure.
 </td>
 </tr>
+<tr>
+<td><a href="man/man3/Matrix.3.html">Matrix(3)</a></td>
+<td>
+Functions for writing Matrix API endpoints.
+</td>
+</tr>
 </table>
 <h2 id="resources">Resources</h2>
 <ul>

src/include/Matrix.h

@@ -41,7 +41,6 @@ typedef enum MatrixError
     M_NOT_FOUND,
     M_LIMIT_EXCEEDED,
     M_UNKNOWN,
-
     M_UNRECOGNIZED,
     M_UNAUTHORIZED,
     M_USER_DEACTIVATED,
@@ -49,12 +48,10 @@ typedef enum MatrixError
     M_INVALID_USERNAME,
     M_ROOM_IN_USE,
     M_INVALID_ROOM_STATE,
-
     M_THREEPID_IN_USE,
     M_THREEPID_NOT_FOUND,
     M_THREEPID_AUTH_FAILED,
     M_THREEPID_DENIED,
-
     M_SERVER_NOT_TRUSTED,
     M_UNSUPPORTED_ROOM_VERSION,
     M_INCOMPATIBLE_ROOM_VERSION,
@@ -62,10 +59,8 @@ typedef enum MatrixError
     M_GUEST_ACCESS_FORBIDDEN,
     M_CAPTCHA_NEEDED,
     M_CAPTCHA_INVALID,
-
     M_MISSING_PARAM,
     M_INVALID_PARAM,
-
     M_TOO_LARGE,
     M_EXCLUSIVE,
     M_RESOURCE_LIMIT_EXCEEDED,