Debug API

Documentation for the Debug API

(This section is a work in progress)

The Debug API allows administrators of a bridge to control the IRC bridge without having to restart the bridge, as well as perform maintenance functions such as cleaning up idle users or inspecting connected users.

All these endpoints presume you have access to the bridge and it's as_token.

This document assumes you are running 0.14.0 or greater. Behavior is documented from that version onwards.

Endpoints

• GET inspectUsers
• POST /killPortal
• POST /killUser
• POST /reapUsers
• GET /irc/$domain/user/$user_id
• POST /irc/$domain/user/$user_id

GET /inspectUsers?regex={userRegex}

Request Parameters

• userRegex A JS regex string which should match against MXIDs. E.g. @foobar_.*:matrix.org

Response Body

{
  "users": {
    "@Half-Shot:half-shot.uk": [
      {
        "channels": [
          "#matrix"
        ],
        "dead": false,
        "server": "chat.freenode.net",
        "nick": "Half-Shot"
      }
    ]
  }
}

POST /killPortal

(TODO: This)

POST /killUser

This will kill a connection to IRC for a given user on all networks they are connected to.

Request Body

{
  "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.
• 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

(TODO: This)

POST /irc/$domain/user/$user_id

(TODO: This)