forked from Telodendria/Telodendria
144 lines
4.2 KiB
Groff
144 lines
4.2 KiB
Groff
.Dd $Mdocdate: December 18 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"
|
|
.Ft HashMap *
|
|
.Fn MatrixUserInteractiveAuth "HttpServerContext *" "Db *" "HashMap *"
|
|
.Ft HashMap *
|
|
.Fn MatrixAuthenticate "HttpServerContext *" "Db *"
|
|
.Ft HashMap *
|
|
.Fn MatrixRateLimit "HttpServerContext *" "Db *"
|
|
.Ft int
|
|
.Fn MatrixUserValidate "char *" "char *"
|
|
.Ft int
|
|
.Fn MatrixHistoricalUserValidate "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 MatrixUserInteractiveAuth
|
|
executes the user interactive authentication flow. A number of Matrix
|
|
client API requests require this flow, so this function provides a
|
|
convenient abstraction. Currently, it only implements a single-stage
|
|
"m.login.dummy" auth, so it's more of a formality than anything else,
|
|
but in the future, this function may support more authentication
|
|
flows.
|
|
.Pp
|
|
.Fn MatrixAuthenticate
|
|
checks the request for a valid access token, which indicates that a
|
|
user is authenticated.
|
|
.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 MatrixUserValidate
|
|
and
|
|
.Fn MatrixHistoricalUserValidate
|
|
take a Matrix ID local part and a domain name, in that order, and
|
|
check to see if it is valid according to the specification.
|
|
.Fn MatrixUserValidate
|
|
checks for a strictly spec-compliant user ID, but the specification
|
|
also requires historical usernames which do not meet the requirements
|
|
of the latest speck to also be supported, so
|
|
.Fn MatrixHistoricalUserValidate
|
|
can be used in cases where historical usernames may be dealt with.
|
|
.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 MatrixUserValidate
|
|
and
|
|
.Fn MatrixHistoricalUserValidate
|
|
return a boolean value, where 0 indicates the provided ID is
|
|
not valid, and non-zero values indicate the provided ID is valid.
|
|
.Sh SEE ALSO
|
|
.Xr HttpServer 3 ,
|
|
.Xr Log 3 ,
|
|
.Xr TelodendriaConfig 3 ,
|
|
.Xr Db 3
|