plate/telodendria
1
0
Fork 0
forked from lda/telodendria
Code Pull requests Activity Actions

Update Matrix documentation.

Browse source
This commit is contained in:
Jordan Bancino 2023-03-06 22:49:21 +00:00
parent f2c2888c87
commit eae8fc5c79
1 changed files with 36 additions and 17 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

53
man/man3/Matrix.3
View file

@ -1,4 +1,4 @@
.Dd $Mdocdate: February 15 2023 $ .Dd $Mdocdate: March 6 2023 $
.Dt MATRIX 3 .Dt MATRIX 3
.Os Telodendria Project .Os Telodendria Project
.Sh NAME .Sh NAME
@ -11,11 +11,11 @@
.Ft void .Ft void
.Fn MatrixErrorCreate "MatrixError" .Fn MatrixErrorCreate "MatrixError"
.Ft HashMap * .Ft HashMap *
.Fn MatrixUserInteractiveAuth "HttpServerContext *" "Db *" "HashMap *"
.Ft HashMap *
.Fn MatrixAuthenticate "HttpServerContext *" "Db *"
.Ft HashMap *
.Fn MatrixRateLimit "HttpServerContext *" "Db *" .Fn MatrixRateLimit "HttpServerContext *" "Db *"
.Ft HashMap *
.Fn MatrixGetAccessToken "HttpServerContext *" "char **"
.Ft HashMap *
.Fn MatrixClientWellKnown "char *" "char *"
.Sh DESCRIPTION .Sh DESCRIPTION
.Nm .Nm
provides some helper functions that bind to the provides some helper functions that bind to the
@ -84,22 +84,30 @@ typedef enum MatrixError
} MatrixError; } MatrixError;
.Ed .Ed
.Pp .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 .Fn MatrixRateLimit
determines whether or not the request should be rate limited. It is 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 expected that this will occur before most, if not all of the caller's
logic. 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 .Sh RETURN VALUES
.Pp .Pp
.Fn MatrixErrorCreate .Fn MatrixErrorCreate
@ -115,6 +123,17 @@ 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 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 return NULL, then the returned JSON object should be passed along to the
client immediately without continuing. 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 .Sh SEE ALSO
.Xr HttpServer 3 , .Xr HttpServer 3 ,
.Xr Log 3 , .Xr Log 3 ,