Merge pull request #1420 from matrix-org/hs/debug-api

Document the Debug API in mdbook

changelog.d/1420.doc

@@ -0,0 +1 @@
+The Debug API is now documented in the hosted documentation, replacing the wiki page.

docs/SUMMARY.md

@@ -7,6 +7,7 @@
   - [Room Configuration](./room_configuration.md)
   - [IRC Modes](./irc_modes.md)
 - [Bridged Networks](./bridged_networks.md)
-- [Setup](./bridge_setup.md)
-- [Administrators Guide](./administrators_guide.md)
+- [Bridge Administrators](./administrators_guide.md)
+  - [Setting up the bridge](./bridge_setup.md)
+  - [Debug API](./debug_api.md)
 - [IRC Operators](./irc_operators.md)

docs/administrators_guide.md

@@ -1,6 +1,7 @@
 # Administrators Guide
 
-This document describes useful information when administering a bridge.
+This document describes useful information when administering a bridge. If you are looking for information
+on how to set up the bridge, please see [Bridge Setup](./bridge_setup.md).
 
 ## Advanced Configuration
 
@@ -86,7 +87,5 @@ can be found in [GRAFANA.md](https://github.com/matrix-org/matrix-appservice-irc
 ## The Debug API
 
 The Debug API allows you to perform administrative actions on the bridge such as killing a IRC
-connection, inspecting connected users or unbridging a room. The API is currently loosely documented
-over in [the GitHub wiki]([https://github.com/matrix-org/matrix-appservice-irc/wiki/Debug-API).
-
-This is not enabled by default.
+connection, inspecting connected users or unbridging a room. You can learn more by reading
+the [Debug API](./debug_api.md) documentation.

docs/debug_api.md

@@ -0,0 +1,178 @@
+Debug API
+=========
+
+
+The Debug API is a powerful HTTP API to make adjustments to the bridge at runtime, and is typically useful
+when administrating large bridges. Some functionality has moved to the [Admin Room](admin_room)
+interface as sending commands over Matrix is preferred, however, many powerful commands are exposed here.
+
+You can enable this feature in the config file:
+
+```yaml
+ircService:
+  # ...
+  debugApi:
+    enabled: true
+    port: 11100
+```
+
+**Note: The Debug API listens on `0.0.0.0` by default, so be careful to lock down access to this port.**
+
+To access the API over `curl`:
+
+```sh
+curl http://127.0.0.1:11100/inspectUsers?access_token=AS_TOKEN_FROM_REGISTRATION_FILE
+```
+
+## Endpoints
+
+<!-- no toc -->
+- [`GET /inspectUsers?regex={userRegex}`](#get-inspectusersregexuserregex)
+- [`POST /killRoom`](#post-killroom)
+- [`POST /killUser`](#post-killuser)
+- [`POST /reapUsers`](#post-reapusers)
+- [`GET /irc/$domain/user/$user_id`](#get-ircdomainuseruser_id)
+- [`POST /irc/$domain/user/$user_id`](#post-ircdomainuseruser_id)
+
+
+### `GET /inspectUsers?regex={userRegex}`
+
+#### Request Parameters
+
+- `userRegex` A JS regex string which should match against MXIDs. E.g. `@foobar_.*:matrix.org`
+
+#### Example Response
+
+```js
+{
+  "users": {
+    "@Half-Shot:half-shot.uk": [
+      {
+        "channels": [
+          "#matrix"
+        ],
+        "dead": false,
+        "server": "chat.freenode.net",
+        "nick": "Half-Shot"
+      }
+    ]
+  }
+}
+```
+
+### `POST /killRoom`
+
+Stop a room from being bridged. This will remove IRC ghost users from the room
+and disconnect Matrix users from the channel.
+
+The [Admin Room](admin_room#unlink) features a less
+powerful version of this command.
+
+#### Request Body
+
+```json5
+{
+  "room_id": "!foo:bar", // The Matrix Room ID. Required.
+  "domain": "irc.foo.bar", // The IRC domain. Required.
+  "channel": "#evilcave", // The IRC channel. Required.
+  "leave_notice": true, // Should a notice be sent on unbridge. Default: true.
+  "remove_alias": true, // Should the room alias for the room be removed. Default: true.
+}
+```
+
+#### Response Body
+
+The response body will contain a JSON array of stages that were successful and failed as
+it's possible for this command to only be partially successful.
+
+Typical successful response:
+
+```json5
+{
+  error: [],
+  stages: ["Removed room from store", "Left notice in room", "Deleted alias for room", "Parted clients where applicable."],
+}
+```
+
+Typical error response:
+
+```json5
+{
+  error: ["Room not found"],
+  stages: [],
+}
+```
+
+### `POST /killUser`
+
+This will kill a connection to IRC for a given user on all networks they are connected to.
+
+#### Request Body
+
+```js
+{
+  "user_id": "@foo:bar",
+  "reason": "Trust nobody"
+}
+```
+
+#### Response Body
+
+If a disconnection was successful, the bridge will emit "null". Otherwise, it may emit an error
+message in plaintext.
+
+### `POST /reapUsers`
+
+This will kill multiple connections for users considered "idle". This is a powerful and 
+expensive operation and should be taken with care.
+
+Idleness is calculated by how long it has been since a user has sent a message/joined/left a room.
+This is calulated by whether the appservice bot or it's users have seen the user perform any actions 
+(i.e. left a IRC bridged room or sent a message). Due to limitations of Matrix, it is not possible to 
+discover "lurkers".
+
+#### Request Parameters
+
+- `server` is the servername you wish to disconnect users from. This is the key of 
+  your server configuration object in the config section.
+- `since` is the number of hours a user has been idle for to be considered `idle`. This must be an integer.
+- `reason` is the reason string to disconnect users with. E.g. "You have been idle for too long".
+- `dryrun` is whether to actually disconnect users, or just calculate which users 
+  should be disconnected and output it to the response.
+
+#### Response Body
+
+The bridge will "stream" logs to the client in plaintext format. Do not close the
+connection before the operation has finished.
+
+### `GET /irc/$domain/user/$user_id`
+
+Return the state of a user's `BridgedClient`. Typically this is only useful for deep debugging
+of connection issues.
+
+#### Request Parameters
+
+- `$domain` The domain of the IRC network you are requesting information on.
+- `$user_id` The user_id of the user you are requesting information for.
+
+#### Response Body
+
+A plaintext dump of the object via the [inspect](https://nodejs.org/dist/latest-v16.x/docs/api/util.html#util_util_inspect_object_options)
+API.
+
+### `POST /irc/$domain/user/$user_id`
+
+Send raw IRC command(s) as the given user.
+
+#### Request Parameters
+
+- `$domain` The domain of the IRC network you are requesting information on.
+- `$user_id` The user_id of the user you are requesting information for.
+- 
+#### Request Body
+
+The body should be a newline delimited list of commands to send to IRC.
+
+### Response format
+The bridge will wait 3 seconds to buffer up any responses from the IRCD and return
+them in a newline delimited JSON format.

docs/irc_modes.md

@@ -54,7 +54,7 @@ directory. The room will still be joinable however.
 ## Key protected (+k)
 
 If a channel is protected by a key, it cannot be entered by joining via an alias. Instead you may join by using
-the [`!join`](admin_room.md#join) command. Be aware that the bridge purposefully does not store channel keys in
+the [`!join`](admin_room#join) command. Be aware that the bridge purposefully does not store channel keys in
 the database as a security precaution so you should be expected to do this again on bridge restart.
 
 ## Channel Forwarding (+f)