Begin documenting User API

man/man3/User.3

@@ -0,0 +1,71 @@
+.Dd $Mdocdate: February 12 2023 $
+.Dt USER 3
+.Os Telodendria Project
+.Sh NAME
+.Nm User
+.Nd Convenience functions for working with local users.
+.Sh SYNOPSIS
+.In User.h
+.Ft int
+.Fn UserValidate "char *" "char *"
+.Ft int
+.Fn UserHistoricalValidate "char *" "char *"
+.Ft int
+.Fn UserExists "Db *" "char *"
+.Ft User *
+.Fn UserCreate "Db *" "char *" "char *"
+.Ft User *
+.Fn UserLock "Db *" "char *"
+.Ft User *
+.Fn UserAuthenticate "Db *" "char *"
+.Ft int
+.Fn UserUnlock "User *"
+.Ft UserLoginInfo *
+.Fn UserLogin "User *" "char *" "char *" "char *" "int"
+.Ft char *
+.Fn UserGetName "User *"
+.Ft int
+.Fn UserCheckPassword "User *" "char *"
+.Sh DESCRIPTION
+.Pp
+The
+.Nm
+API provides a wrapper over the database and offers an easy way for managing
+local users. It supports all of the locking mechanisms that the database does,
+and provides features for authenticating local users, among other tasks.
+.Pp
+.Fn UserValidate
+takes a localpart and domain as separate parameters and validates it against the
+rules of the Matrix specification. The reason the domain is required is because
+the spec imposes limitations on the length of the user name, and the longer the
+domain name is, the shorter the local part can be. This function is used to
+ensure that client-provided localparts are valid on this server.
+.Fn UserHistoricalValidate
+is called the exact same way, except it is a little more lenient. It is used to
+validate user parts on other servers, since some usernames might exist that are
+not fully spec compliant, but remain in use due to historical reasons.
+.Pp
+.Fn UserExists
+takes a localpart and checks whether or not it exists in the database.
+.Pp
+.Fn UserCreate
+creates a new user. It takes a localpart, which is assumed to be valid, and
+a password.
+.Pp
+.Fn UserLock
+takes a localpart and obtains a database reference to the user represented by that
+localpart. It behaves analogously to
+.Fn DbLock ,
+and in fact uses it under the hood to ensure that the user can only be modified
+by the thread that has locked the user.
+.Fn UserUnlock
+returns the user reference back to the database. It uses
+.Fn DbUnlock
+under the hood.
+.Pp
+.Fn UserAuthenticate
+takes an access token, figures out what user it belongs to, and returns the
+reference to that user.
+.Sh RETURN VALUES
+.Sh SEE ALSO
+.Xr Db 3

src/include/User.h

@@ -43,10 +43,10 @@ extern int
  UserHistoricalValidate(char *, char *);
 
 extern int
- UserExists(Db *, char *name);
+ UserExists(Db *, char *);
 
 extern User *
- UserCreate(Db *, char *name, char *password);
+ UserCreate(Db *, char *, char *);
 
 extern User *
  UserLock(Db *, char *name);