From 53846b0994139a88e7671770c9b0e8844787b50f Mon Sep 17 00:00:00 2001
From: Jordan Bancino <jordan@bancino.net>
Date: Fri, 16 Dec 2022 22:15:50 +0000
Subject: [PATCH] Document MatrixAuthenticate and MatrixRateLimit

---
 man/man3/Matrix.3 | 26 +++++++++++++++++++++-----
 1 file changed, 21 insertions(+), 5 deletions(-)

diff --git a/man/man3/Matrix.3 b/man/man3/Matrix.3
index 9cdae75..4a7d4d4 100644
--- a/man/man3/Matrix.3
+++ b/man/man3/Matrix.3
@@ -12,6 +12,10 @@
 .Fn MatrixErrorCreate "MatrixError"
 .Ft HashMap *
 .Fn MatrixUserInteractiveAuth "HttpServerContext *" "Db *" "HashMap *"
+.Ft HashMap *
+.Fn MatrixAuthenticate "HttpServerContext *" "Db *"
+.Ft HashMap *
+.Fn MatrixRateLimit "HttpServerContext *" "Db *"
 .Sh DESCRIPTION
 .Nm
 provides some helper functions that bind to the
@@ -87,17 +91,29 @@ 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.
 .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
-returns NULL when the auth is successful. That is, if it returns NULL,
-then the caller can proceed assuming that the client has done all the
-right things to authenticate itself. If this function does not return
-NULL, then the returned JSON object should be passed along to the
+.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.
 .Sh SEE ALSO
 .Xr HttpServer 3 ,