.Dd $Mdocdate: March 6 2023 $
.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"
.Ft HashMap *
.Fn MatrixRateLimit "HttpServerContext *" "Db *"
.Ft HashMap *
.Fn MatrixGetAccessToken "HttpServerContext *" "char **"
.Ft HashMap *
.Fn MatrixClientWellKnown "char *" "char *"
.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
.Pp
.Fn MatrixRateLimit
determines whether or not the request should be rate limited. It is
expected that this will occur before most, if not all of the caller's
logic.
.Pp
.Fn MatrixGetAccessToken
reads the request headers and parameters, and attempts to obtain
the access token it found. The matrix specification says that an
access token can either be in an
.Dv Authorization
header, or in a
.Dv access_token
.Sy GET
paramter. This function checks both, and stores the access token
it finds in the passed character pointer.
.Pp
.Fn MatrixClientWellKnown
builds a client ``well-known'' JSON object, which contains
information about the homeserver base URL and identity server,
both of which should be provided by the caller in that order. This
object can be sent to a client as-is, as is the case with the
.Pa /.well-known/matrix/client
endpoint, or it can be added as a key in a response, as is the
case with a few endpoints.
.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.
.Pp
.Fn MatrixUserInteractiveAuth ,
.Fn MatrixAuthenticate ,
and
.Fn MatrixRateLimit
all return NULL when they are successful. That is, if these functions
return NULL, then the caller can proceed assuming that all is well
and no further action needs to be taken. If these functions do not
return NULL, then the returned JSON object should be passed along to the
client immediately without continuing.
.Pp
.Fn MatrixGetAccessToken
returns a JSON object that should be immediately passed to the client
if it is not NULL. This JSON object holds an error message, indicating
that something went wrong. If this function does return NULL, then
the access token can be checked for validity. Otherwise, the access
token is either not valid or not provided so it should not be
checked.
.Pp
.Fn MatrixClientWellKnown
returns a JSON object, or NULL if something went wrong.
.Sh SEE ALSO
.Xr HttpServer 3 ,
.Xr Log 3 ,
.Xr TelodendriaConfig 3 ,
.Xr Db 3