Finish moving over current Administrator API documentation.

docs/user/admin/config.md

@@ -0,0 +1,42 @@
+# Administrator API: Configuration
+
+As mentioned in [Setup](../setup.md), Telodendria's configuration is
+intended to be managed via the configuration API. Consult the
+[Configuration](../config.md) document for a complete list of supported
+configuration options. This document simply describes the API used to
+update the configuration.
+
+## API Endpoints
+
+### **GET** `/_telodendria/admin/config`
+
+Retrieve the current configuration.
+
+| Requires Token | Rate Limited |
+|----------------|--------------|
+| Yes            | Yes          |
+
+| Response Code | Description |
+|---------------|-------------|
+| 200           | The current configuration was successfully retrieved.|
+
+### **POST** `/_telodendria/admin/config`
+
+Installs a new configuration. This endpoint validates the request body,
+ensuring it is a proper configuration, then it replaces the existing
+configuration with the new one.
+
+| Requires Token | Rate Limited |
+|----------------|--------------|
+| Yes            | Yes          |
+
+| Response Code | Description |
+|---------------|-------------|
+| 200           | The new configuration was successfully installed.|
+
+#### 200 Response Format
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `restart_required` | `Boolean` | Whether or not the process needs to be restarted to finish applying the configuration. If this is `true`, then the restart endpoint should be used at a convenient time to apply the configuration.
+

docs/user/admin/privileges.md

@@ -89,7 +89,7 @@ owns the access token.
 |-------|------|-------------|
 | `privileges` | `Array` | An array of privileges, as described above. The privileges are encoded as JSON strings.|
 
-### **PUT** `/_telodendria/admin/privileges/[localpart]
+### **PUT** `/_telodendria/admin/privileges/[localpart]`
 
 Update the privileges of a local user by adding the privileges
 specified in the request to the users existing privileges.

docs/user/admin/proc.md

@@ -0,0 +1,49 @@
+# Administrator API: Process Control
+
+This document describes the administrator APIs that allow a server
+administrator to manage the Telodendria process itself.
+
+## API Endpoints
+
+### **POST** `/_telodendria/admin/restart`
+
+Restart the Telodendria daemon cleanly. This endpoint will respond
+immediately after signaling to the daemon that it should be restarted
+as soon as possible. Note that the restart wmay not happen
+instantaneously, as Telodendria will finish processing all current
+requests before restarting. Also note that this is not a true restart;
+the process does not exit and restart, rather, Telodendria simply tears
+down all its state and then jumps back to the beginning of its code and
+starts over.
+
+| Requires Token | Rate Limited |
+|----------------|--------------|
+| Yes            | Yes          |
+
+| Response Code | Description |
+|---------------|-------------|
+| 200           | The restart request was successfully sent.|
+
+On success, this endpoint simply returns an empty JSON object.
+
+### **POST** `/_telodendria/admin/shutdown`
+
+Shut down the Telodendria process cleanly. This endpoint will respond
+immediately after signalling to the daemon that it should be shut
+down as soon as possible. Note that the shutdown may not happen
+instantaneously, as Telodendria will finish processing all current
+requests before shutting down. Also note that once shut down, Telodendria
+may be automatically restarted by the system's service manager.
+Otherwise, it will have to be manually restarted. This is a true
+shutdown; the Telodendria process exits as soon as possible.
+
+| Requires Token | Rate Limited |
+|----------------|--------------|
+| Yes            | Yes          |
+
+| Response Code | Description |
+|---------------|-------------|
+| 200           | The shutdown request was successfully sent.|
+
+On success, this endpoint simply returns an empty JSON object.
+

docs/user/admin/stats.md

@@ -0,0 +1,24 @@
+# Administrator API: Server Statistics
+
+The administrator API allows users with the proper privileges to get
+information about how the server process is performing.
+
+## API Endpoints
+
+### **GET** `/_telodendria/admin/stats`
+
+Retrieve basic statistics about the currently running Telodendria
+process.
+
+| Requires Token | Rate Limited |
+|----------------|--------------|
+| Yes            | Yes          |
+
+| Response Code | Description |
+| 200           | The server statistics were successfully retrieved.|
+
+#### 200 Response Format
+
+| Field | Type | Description |
+| `memory_allocated` | `Integer` | The total amount of memory allocated, measured in bytes.|
+| `version` | `String` | The current version of Telodendria.|

man/man7/telodendria-admin.7

@@ -1,421 +0,0 @@
-.Dd $Mdocdate: August 9 2023 $
-.Dt TELODENDRIA-ADMIN 7
-.Os Telodendria Project
-.Sh NAME
-.Nm telodendria-admin
-.Nd Administrator API documention.
-.Sh DESCRIPTION
-.Pp
-Telodendria provides an administrator API that allows for administrator control
-over the homeserver. This includes profiling and examining the state of Telodendria,
-as well as managing users and media.
-.Pp
-Like Synapse, Telodendria supports designating specific users as administrators.
-However, unlike Synapse, it uses a more finely-grained privilege model that allows
-a server administrator to designate specific administration tasks to other users
-while not compromising and granting them full administrative access to the server.
-.Pp
-To authenticate with the administrator API, simply use a regular
-access token.
-.Ss Privileges
-.Pp
-Here are all of the privileges a local user can have. Unless otherwise specified,
-these privileges only grant access to certain parts of the administrator API; the
-regular Matrix API is unaffected.
-.Bl -tag -width -Ds
-.It Dv DEACTIVATE
-Allows a user to deactivate any other local users.
-.It Dv ISSUE_TOKENS
-Allows a user to create, modify, and delete registration tokens.
-.It Dv CONFIG
-Allows a user to modify the Telodendria server daemon's configuration.
-.It Dv GRANT_PRIVILEGES
-Allows a user to modify his or her own privileges or the privileges of other
-local users.
-.It Dv ALIAS
-Allows a user to modify room aliases created by other users. By default, users
-can only manage their own room aliases, but an administrator may wish to take
-over an alias or remove an offensive alias.
-.It Dv PROC_CONTROL
-Allows a user to get statistics on the running process, as well as shutdown and
-restart the Telodendria daemon itself. Typically this will pair well with
-.Dv CONFIG ,
-because there are certain configuration options that require the process to be
-restarted.
-.El
-.Pp
-There is also a special ``pseudo-privilege'':
-.Bl -tag -width Ds
-.It Dv ALL
-Grants a user all of the aforementioned privileges, as well as privileges that
-do not yet exist. That is, if an update to Telodendria adds more privileges,
-users with this privilege will automatically gain those new privileges in
-addition to having all of the existing privileges.
-.Pp
-This privilege should only be used with fully-trusted users. It is typical for
-a server administrator to not fully trust anyone else, and be the only one that
-holds an account with this privilege level.
-.El
-.Sh API ENDPOINTS
-.Pp
-The following API endpoints are implemented for the installed version of
-Telodendria.
-.Pp
-Unless otherwise indicated, HTTP response codes that are not 200 Ok
-will be accompanied by a standard Matrix API error. Consult the Matrix specification
-for the format of these errors. The following error conditions are assumed to be
-possible for all of the endpoints listed here:
-.Pp
-.TS
-tab(;) allbox expand;
-lfB lfB
-l l.
-Response Code;Description
-400;T{
-The user is not authenticated, did not provide a valid JSON object,
-or provided a JSON object with invalid parameters. 
-T}
-403;T{
-The user does not have the privileges necessary to carry out the
-specified action.
-T}
-500;T{
-A fatal server error occured. Check the logs for more information.
-T}
-.TE
-.Ss Sy GET No /_telodendria/admin/privileges/[localpart]
-.Pp
-Retrieve the permissions for a user. If the localpart is
-omitted, then retrieve the privileges for the user that owns
-the access token being used. Note that the owner of the
-access token must have the
-.Dv GRANT_PRIVILEGES
-privilege.
-.Pp
-.TS
-tab(;) allbox expand;
-lfB lfB
-l l.
-Requires Token;Rate Limited
-Yes;Yes
-.TE
-.TS
-tab(;) allbox expand;
-lfB lfB
-l l.
-Response Code;Description
-200;T{
-The privileges were successfully retrieved.
-T}
-.TE
-.Pp
-200 Response Format:
-.TS
-tab(;) allbox expand;
-lfB lfB lfB
-l l l.
-Field;Type;Description
-privileges;Array;T{
-An array of privileges, as described above. The
-privileges are represented as strings in JSON.
-T}
-.TE
-.Ss Sy POST No /_telodendria/admin/privileges/[localpart]
-.Pp
-Update the privileges of a local user by replacing the
-privileges array with the one specified in the request.
-Like the
-.Sy GET
-version of this endpoint, the localpart can be omitted to
-operate on the user that owns the access token.
-.Pp
-.TS
-tab(;) allbox expand;
-lfB lfB
-l l.
-Requires Token;Rate Limited
-Yes;Yes
-.TE
-.TS
-tab(;) allbox expand;
-lfB lfB
-l l.
-Response Code;Description
-200;T{
-The privileges were successfully replaced.
-T}
-.TE
-.Pp
-Request Format:
-.TS
-tab(;) allbox expand;
-lfB lfB lfB
-l l l.
-Field;Type;Description
-privileges;Array;T{
-An array of privileges, as described above. The
-privileges are represented as strings in JSON.
-T}
-.TE
-.Pp
-200 Response Format:
-.TS
-tab(;) allbox expand;
-lfB lfB lfB
-l l l.
-Field;Type;Description
-privileges;Array;T{
-An array of privileges, as described above. The
-privileges are represented as strings in JSON.
-T}
-.TE
-.Ss Sy PUT No /_telodendria/admin/privileges/[localpart]
-.Pp
-Update the privileges of a local user by adding the privileges
-specified in the request to the user's existing privileges.
-.Pp
-.TS
-tab(;) allbox expand;
-lfB lfB
-l l.
-Requires Token;Rate Limited
-Yes;Yes
-.TE
-.TS
-tab(;) allbox expand;
-lfB lfB
-l l.
-Response Code;Description
-200;T{
-The requested privileges were successfully added.
-T}
-.TE
-.Pp
-Request Format:
-.TS
-tab(;) allbox expand;
-lfB lfB lfB
-l l l.
-Field;Type;Description
-privileges;Array;T{
-An array of privileges, as described above. The
-privileges are represented as strings in JSON.
-T}
-.TE
-.Pp
-200 Response Format:
-.TS
-tab(;) allbox expand;
-lfB lfB lfB
-l l l.
-Field;Type;Description
-privileges;Array;T{
-An array of privileges, as described above. The
-privileges are represented as strings in JSON.
-T}
-.TE
-.Ss Sy DELETE No /_telodendria/admin/privileges/[localpart]
-.Pp
-Update the privileges of a local user by removing the privileges
-specified in the request from the user's existing privileges.
-.Pp
-.TS
-tab(;) allbox expand;
-lfB lfB
-l l.
-Requires Token;Rate Limited
-Yes;Yes
-.TE
-.TS
-tab(;) allbox expand;
-lfB lfB
-l l.
-Response Code;Description
-200;T{
-The requested privileges were successfully removed.
-T}
-.TE
-.Pp
-Request Format:
-.TS
-tab(;) allbox expand;
-lfB lfB lfB
-l l l.
-Field;Type;Description
-privileges;Array;T{
-An array of privileges, as described above. The
-privileges are represented as strings in JSON.
-T}
-.TE
-.Pp
-200 Response Format:
-.TS
-tab(;) allbox expand;
-lfB lfB lfB
-l l l.
-Field;Type;Description
-privileges;Array;T{
-An array of privileges, as described above. The
-privileges are represented as strings in JSON.
-T}
-.TE
-.Ss Sy POST No /_telodendria/admin/config
-.Pp
-Installs a new configuration. It validates the request body, ensuring it is a
-proper configuration, then replaces the existing configuration with the new one.
-.Pp
-.TS
-tab(;) allbox expand;
-lfB lfB
-l l.
-Requires Token; Rate Limited
-Yes;Yes
-.TE
-.TS
-tab(;) allbox expand;
-lfB lfB
-l l.
-Response Code;Description
-200;T{
-The new configuration was successfully installed.
-T}
-.TE
-.Pp
-Consult the
-.Xr telodendria-config 7
-manual page for a full description of the configuration object that should
-be submitted. That page lists all the fields, and notes which ones are
-required.
-.Pp
-200 Response Format:
-.TS
-tab(;) allbox expand;
-lfB lfB lfB
-l l l.
-Field;Type;Description
-restart_required;Boolean;T{
-Whether or not the process needs to be restarted to finish applying the
-configuration. If this is true, the restart endpoint may be used.
-T}
-.TE
-.Ss Sy GET No /_telodendria/admin/config
-.Pp
-Retrieve the current configuration.
-.Pp
-.TS
-tab(;) allbox expand;
-lfB lfB
-l l.
-Requires Token;Rate Limited
-Yes;Yes
-.TE
-.TS
-tab(;) allbox expand;
-lfB lfB
-l l.
-Response Code;Description
-200;T{
-The current configuration was successfully retrieved.
-T}
-.TE
-.Pp
-Consult the
-.Xr telodendria-config 7
-manual page for a full description of the configuration object that
-is returned. Note that this is the same object that was submitted
-using the
-.Sy POST
-version of this endpoint, otherwise it is the default configuration.
-.Ss Sy GET No /_telodendria/admin/stats
-.Pp
-Retrieve statistics about the currently running Telodendria process.
-.Pp
-.TS
-tab(;) allbox expand;
-lfB lfB
-l l.
-Requires Token;Rate Limited
-Yes;Yes
-.TE
-.TS
-tab(;) allbox expand;
-lfB lfB
-l l.
-Response Code;Description
-200;T{
-The server statistics were successfully retrieved.
-T}
-.TE
-.Pp
-200 Response Format:
-.TS
-tab(;) allbox expand;
-lfB lfB lfB
-l l l.
-Field;Type;Description
-memory_allocated;Integer;T{
-The total amount of memory allocated, measured in bytes.
-T}
-version;String;T{
-The current version of Telodendria.
-T}
-.TE
-.Ss Sy POST No /_telodendria/admin/restart
-.Pp
-Restart the Telodendria daemon cleanly. This endpoint will respond immediately
-after signaling to the daemon that it should be restarted as soon as possible.
-Note that the restart may not happen instantaneously, as Telodendria will finish
-processing all current requests before restarting. Also note that this is not a
-``true'' restart; the process does not exit and restart, rather, Telodendria
-simply tears down its state, and then jumps back to the beginning of its code
-and starts over.
-.Pp
-.TS
-tab(;) allbox expand;
-lfB lfB
-l l.
-Requires Token;Rate Limited
-Yes;Yes
-.TE
-.TS
-tab(;) allbox expand;
-lfB lfB
-l l.
-Response Code;Description
-200;T{
-The restart request was successfully sent.
-T}
-.TE
-.Pp
-On success, this endpoint simply returns an empty JSON object.
-.Ss Sy POST No /_telodendria/admin/shutdown
-.Pp
-Shut down the Telodendria process cleanly. This endpoint will respond immediately
-after signaling to the daemon that it should be shut down as soon as possible.
-Note that the shutdown may not happen instantaneously, as Telodnedria will
-finish processing all current requests before shutting down. Also note that once
-shut down, Telodendria may be automatically restarted by the system's service
-manager, otherwise, it will have to be manually restarted. This is a ``true''
-shutdown, the Telodendria process exits as soon as possible.
-.Pp
-.TS
-tab(;) allbox expand;
-lfB lfB
-l l.
-Requires Token;Rate Limited
-Yes;Yes
-.TE
-.TS
-tab(;) allbox expand;
-lfB lfB
-l l.
-Response Code;Description
-200;T{
-The shutdown request was successfully sent.
-T}
-.TE
-.Pp
-On success, this endpoint simply returns an empty JSON object.
-.Sh SEE ALSO
-.Xr telodendria-config 7 ,
-.Xr telodendria-setup 7