diff --git a/TODO.txt b/TODO.txt index 5bf4dbb..1cad971 100644 --- a/TODO.txt +++ b/TODO.txt @@ -33,7 +33,7 @@ Due: January 1, 2023 [ ] HttpServer [x] Json [x] Log - [ ] Matrix + [x] Matrix [x] Queue [ ] Routes [x] TelodendriaConfig diff --git a/man/man3/Matrix.3 b/man/man3/Matrix.3 new file mode 100644 index 0000000..8887b17 --- /dev/null +++ b/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 diff --git a/site/index.html b/site/index.html index 86bf9c4..ee0cd9c 100644 --- a/site/index.html +++ b/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. + +Matrix(3) + +Functions for writing Matrix API endpoints. + +

Resources