NAME

Matrix — Functions for writing Matrix API endpoints.

SYNOPSIS

#include <Matrix.h>

void
MatrixHttpHandler(HttpServerContext *, void *);

void
MatrixErrorCreate(MatrixError);

HashMap *
MatrixRateLimit(HttpServerContext *, Db *);

HashMap *
MatrixGetAccessToken(HttpServerContext *, char **);

HashMap *
MatrixClientWellKnown(char *, char *);

DESCRIPTION

Matrix provides some helper functions that bind to the HttpServer(3) interface and add basic Matrix functionality, turning an HTTP server into a Matrix homeserver.

MatrixHttpHandler is the HTTP handler function that handles all Matrix homeserver functionality. It should be passed into 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:

typedef struct MatrixHttpHandlerArgs
{
	LogConfig *lc;
	TelodendriaConfig *config;
	Db *db;
} MatrixHttpHandlerArgs;

This structure should be populated once and then never modified again for the duration of the HTTP server.

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:

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;

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.

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 Authorization header, or in a access_token GET paramter. This function checks both, and stores the access token it finds in the passed character pointer.

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 /.well-known/matrix/client endpoint, or it can be added as a key in a response, as is the case with a few endpoints.

RETURN VALUES

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.

MatrixUserInteractiveAuth(), MatrixAuthenticate(), and 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.

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.

MatrixClientWellKnown() returns a JSON object, or NULL if something went wrong.

SEE ALSO

HttpServer(3), Log(3), TelodendriaConfig(3), Db(3)