Document Matrix.h

This commit is contained in:
Jordan Bancino 2022-12-12 16:59:13 +00:00
parent fe2c4de1b6
commit e7030ec57a
4 changed files with 96 additions and 6 deletions

View file

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

89
man/man3/Matrix.3 Normal file
View file

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

View file

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

View file

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