mirror of
https://github.com/turt2live/matrix-dimension.git
synced 2024-10-01 01:05:53 -04:00
Update documentation and remove extra files
This commit is contained in:
Travis Ralston
parent
9a8041ea38
commit
a73fb53dcb
@ -22,30 +22,32 @@ npm run start:web
|
||||
npm run build:app && node build/app/index.js
|
||||
```
|
||||
|
||||
## General architecture
|
||||
## Backend Architecture
|
||||
|
||||
Integrations are defined in the database for administrators to enable, disable, and configure as they please. They are added using migrations (or in some cases, manually by the administrators) and should always be added as "disabled" by default.
|
||||
Integrations are defined into one of four categories:
|
||||
* Simple bots - Bots that can be invited to the room and left alone (Imgur, Giphy, etc)
|
||||
* Complex bots - Bots that require some sort of per-room configuration (RSS, Github, etc)
|
||||
* Bridges - Application services that bridge the room in some way to an external network (IRC, Webhooks, etc)
|
||||
* Widgets - Added functionality through iframes for rooms/users
|
||||
|
||||
The frontend has two sections: the admin and non-admin sections. The admin section is used by authorized users to configure the various integrations, or parts of integrations. The non-admin section is used by everyone else to add the integrations to their rooms.
|
||||
The backend further breaks these categories out to redirect traffic to the correct place. For instance, the admin backend
|
||||
breaks out go-neb specifically as it's configuration is fairly involved.
|
||||
|
||||
The frontend automatically routes edit pages in both the admin and non-admin sections to the appropriate routes. It does this by using a combination of the `category` and `type` of the integrations. For example, a `widget` with the type `jitsi` will be redirected to the `/riot-app/widget/jitsi` route for editing. Both the admin and non-admin routes need to be declared in the `app.routing.ts` class. After that, it is best to copy/paste a similar widget component and edit it to your needs.
|
||||
The backend has 3 major layers:
|
||||
* The webserver (where all the requests come from)
|
||||
* The data stores (where requests normally get routed to)
|
||||
* The proxy (where we flip between using upstream configurations and self-hosted)
|
||||
|
||||
The backend is slightly more complicated, where particular integrations may have their own API defined depending on the complexity involved. For example, all bridges have their own admin and non-admin API to configure the various parts. The required changes to the backend are described in the later sections of this document.
|
||||
Many of the API routes are generic, however many of the integrations require additional structure that the routes cannot
|
||||
provide. For example, the IRC bridge is complicated in that it needs a dedicated API in order to be configured, however
|
||||
the bots can work well within their constraints.
|
||||
|
||||
## Adding new widgets
|
||||
## Frontend Architecture
|
||||
|
||||
TODO
|
||||
The frontend app is split into two major parts: The Riot frontend and the admin section. The components are nested under
|
||||
their respective categories and route. For example, the edit page for the Jitsi widget is under the Widgets directory.
|
||||
|
||||
## Adding new go-neb services
|
||||
|
||||
TODO
|
||||
|
||||
## Adding new bridges
|
||||
|
||||
TODO
|
||||
|
||||
## Adding new bots
|
||||
|
||||
TODO
|
||||
|
||||
*note to self: are simple bots even a thing anymore?*
|
||||
The frontend is otherwise a fairly basic Angular 5 application: there's components, services, etc. The services should be
|
||||
kept small and generic where possible (almost always matching the Service classes in the backend). Components are more of
|
||||
a judgement call and should be split out where it makes sense. For example, it doesn't make sense to create a component
|
||||
for every instance where an `ngFor` is used because the number of components would be astronomical.
|
||||
|
||||
@ -1,8 +0,0 @@
|
||||
type: "complex-bot"
|
||||
integrationType: "circleci"
|
||||
enabled: false # disabled because the API is considered unstable/inoperable. Use at your own risk!
|
||||
name: "CircleCI"
|
||||
about: "Sends CircleCI build results into the room"
|
||||
avatar: "img/avatars/circleci.png"
|
||||
upstream:
|
||||
type: "vector"
|
||||
@ -1,7 +0,0 @@
|
||||
# All this configuration does is make "Custom Widget" available in the UI
|
||||
type: "widget"
|
||||
integrationType: "customwidget"
|
||||
enabled: true
|
||||
name: "Custom Widgets"
|
||||
about: "A webpage embedded in the room."
|
||||
avatar: "img/avatars/customwidget.png"
|
||||
@ -1,11 +0,0 @@
|
||||
# All this configuration does is make "Etherpad Widget" available in the UI
|
||||
type: "widget"
|
||||
integrationType: "etherpad"
|
||||
enabled: true
|
||||
name: "Etherpad"
|
||||
about: "Collaborate on documents with members of your room."
|
||||
avatar: "img/avatars/etherpad.png"
|
||||
|
||||
# This is the URL people will be provided when adding a new Etherpad widget. The supported variables
|
||||
# are $roomId and $padName. Both will end up being URL encoded.
|
||||
defaultUrl: "https://demo.riot.im/etherpad/p/$roomId_$padName"
|
||||
@ -1,19 +0,0 @@
|
||||
type: "bot"
|
||||
integrationType: "giphy"
|
||||
enabled: true
|
||||
userId: "@neb_giphy:matrix.org"
|
||||
name: "Giphy"
|
||||
about: "Use `!giphy query` to find an animated GIF on demand"
|
||||
avatar: "img/avatars/giphy.png"
|
||||
|
||||
# This integration can be hosted in one of two ways: self-hosted or using vector.im's version.
|
||||
# By default, vector.im's version is used, but you can host your own by uncommenting the `hosted`
|
||||
# section below. Be sure to comment out or remove the `upstream` section below if you're self-hosting.
|
||||
# Self-hosted bots are expected to auto-respond to invites.
|
||||
|
||||
upstream:
|
||||
type: "vector"
|
||||
id: "giphy"
|
||||
#hosted:
|
||||
# homeserverUrl: "https://t2bot.io"
|
||||
# accessToken: "your_matrix_access_token_here"
|
||||
@ -1,8 +0,0 @@
|
||||
type: "complex-bot"
|
||||
integrationType: "github"
|
||||
enabled: true
|
||||
name: "Github"
|
||||
about: "Track changes to your projects and create new issues using `!github create`"
|
||||
avatar: "img/avatars/github.png"
|
||||
upstream:
|
||||
type: "vector"
|
||||
@ -1,19 +0,0 @@
|
||||
type: "bot"
|
||||
integrationType: "google"
|
||||
enabled: true
|
||||
userId: "@_neb_google:matrix.org"
|
||||
name: "Google"
|
||||
about: "Use `!google image query` to find an image from Google"
|
||||
avatar: "img/avatars/google.png"
|
||||
|
||||
# This integration can be hosted in one of two ways: self-hosted or using vector.im's version.
|
||||
# By default, vector.im's version is used, but you can host your own by uncommenting the `hosted`
|
||||
# section below. Be sure to comment out or remove the `upstream` section below if you're self-hosting.
|
||||
# Self-hosted bots are expected to auto-respond to invites.
|
||||
|
||||
upstream:
|
||||
type: "vector"
|
||||
id: "google"
|
||||
#hosted:
|
||||
# homeserverUrl: "https://t2bot.io"
|
||||
# accessToken: "your_matrix_access_token_here"
|
||||
@ -1,7 +0,0 @@
|
||||
# All this configuration does is make "Google Calendar Widget" available in the UI
|
||||
type: "widget"
|
||||
integrationType: "googlecalendar"
|
||||
enabled: true
|
||||
name: "Google Calendar"
|
||||
about: "Share upcoming events in your room with a Google Calendar"
|
||||
avatar: "img/avatars/googlecalendar.png"
|
||||
@ -1,7 +0,0 @@
|
||||
# All this configuration does is make "Google Docs Widget" available in the UI
|
||||
type: "widget"
|
||||
integrationType: "googledocs"
|
||||
enabled: true
|
||||
name: "Google Docs"
|
||||
about: "Collaborate on and share documents using Google Docs"
|
||||
avatar: "img/avatars/googledocs.png"
|
||||
@ -1,19 +0,0 @@
|
||||
type: "bot"
|
||||
integrationType: "guggy"
|
||||
enabled: true
|
||||
userId: "@_neb_guggy:matrix.org"
|
||||
name: "Guggy"
|
||||
about: "Use `!guggy sentence` to create an animated GIF from a sentence"
|
||||
avatar: "img/avatars/guggy.png"
|
||||
|
||||
# This integration can be hosted in one of two ways: self-hosted or using vector.im's version.
|
||||
# By default, vector.im's version is used, but you can host your own by uncommenting the `hosted`
|
||||
# section below. Be sure to comment out or remove the `upstream` section below if you're self-hosting.
|
||||
# Self-hosted bots are expected to auto-respond to invites.
|
||||
|
||||
upstream:
|
||||
type: "vector"
|
||||
id: "guggy"
|
||||
#hosted:
|
||||
# homeserverUrl: "https://t2bot.io"
|
||||
# accessToken: "your_matrix_access_token_here"
|
||||
@ -1,19 +0,0 @@
|
||||
type: "bot"
|
||||
integrationType: "imgur"
|
||||
enabled: true
|
||||
userId: "@_neb_imgur:matrix.org"
|
||||
name: "Imgur"
|
||||
about: "Use `!imgur query` to find an image from Imgur"
|
||||
avatar: "img/avatars/imgur.png"
|
||||
|
||||
# This integration can be hosted in one of two ways: self-hosted or using vector.im's version.
|
||||
# By default, vector.im's version is used, but you can host your own by uncommenting the `hosted`
|
||||
# section below. Be sure to comment out or remove the `upstream` section below if you're self-hosting.
|
||||
# Self-hosted bots are expected to auto-respond to invites.
|
||||
|
||||
upstream:
|
||||
type: "vector"
|
||||
id: "imgur"
|
||||
#hosted:
|
||||
# homeserverUrl: "https://t2bot.io"
|
||||
# accessToken: "your_matrix_access_token_here"
|
||||
@ -1,10 +0,0 @@
|
||||
type: "bridge"
|
||||
integrationType: "irc"
|
||||
enabled: true
|
||||
name: "IRC"
|
||||
about: "Bridges IRC channels to the room"
|
||||
avatar: "img/avatars/irc.png"
|
||||
requirements:
|
||||
joinRule: 'public'
|
||||
upstream:
|
||||
type: "vector"
|
||||
@ -1,15 +0,0 @@
|
||||
# All this configuration does is make "Jitsi Widget" available in the UI
|
||||
type: "widget"
|
||||
integrationType: "jitsi"
|
||||
enabled: true
|
||||
name: "Jitsi"
|
||||
about: "Add video conferencing to your room with Jitsi"
|
||||
avatar: "img/avatars/jitsi.png"
|
||||
|
||||
# This is the domain that will be used to construct the Jitsi widget. It must be just the domain.
|
||||
# The default is meet.jit.si The Riot.IM instance is at jitsi.riot.im
|
||||
jitsiDomain: "jitsi.riot.im"
|
||||
|
||||
# This is the path to the external API script. Usually the domain can be replaced with your custom
|
||||
# domain above without any other modifications.
|
||||
scriptUrl: "https://jitsi.riot.im/libs/external_api.min.js"
|
||||
@ -1,8 +0,0 @@
|
||||
type: "complex-bot"
|
||||
integrationType: "rss"
|
||||
enabled: true
|
||||
name: "RSS Bot"
|
||||
about: "Tracks any Atom/RSS feed and sends new items into this room"
|
||||
avatar: "img/avatars/rssbot.png"
|
||||
upstream:
|
||||
type: "vector"
|
||||
@ -1,10 +0,0 @@
|
||||
type: "bot"
|
||||
integrationType: "demo"
|
||||
enabled: false
|
||||
userId: "@dimension:t2bot.io"
|
||||
name: "Demo Bot"
|
||||
about: "A bot that has no functionality. This is just a demonstration on the config."
|
||||
avatar: "img/avatars/demobot.png"
|
||||
hosted:
|
||||
homeserverUrl: "https://t2bot.io"
|
||||
accessToken: "your_matrix_access_token_here"
|
||||
@ -1,10 +0,0 @@
|
||||
type: "bot"
|
||||
integrationType: "pollbot"
|
||||
enabled: false
|
||||
userId: "@pollbot:t2bot.io"
|
||||
name: "Poll Bot"
|
||||
about: "A bot to poll users in a room. Use `!pollhelp` for more information"
|
||||
avatar: "img/avatars/pollbot.png"
|
||||
hosted:
|
||||
homeserverUrl: "https://t2bot.io"
|
||||
accessToken: "your_matrix_access_token_here"
|
||||
@ -1,8 +0,0 @@
|
||||
type: "complex-bot"
|
||||
integrationType: "travisci"
|
||||
enabled: true
|
||||
name: "Travis CI"
|
||||
about: "Sends Travis CI build results into the room"
|
||||
avatar: "img/avatars/travisci.png"
|
||||
upstream:
|
||||
type: "vector"
|
||||
@ -1,7 +0,0 @@
|
||||
# All this configuration does is make "Twitch Widget" available in the UI
|
||||
type: "widget"
|
||||
integrationType: "twitch"
|
||||
enabled: true
|
||||
name: "Twitch Livestream"
|
||||
about: "Embed a Twitch Livestream"
|
||||
avatar: "img/avatars/twitch.png"
|
||||
@ -1,19 +0,0 @@
|
||||
type: "bot"
|
||||
integrationType: "wikipedia"
|
||||
enabled: true
|
||||
userId: "@_neb_wikipedia:matrix.org"
|
||||
name: "Wikipedia"
|
||||
about: "Use `!wikipedia query` to find something from Wikipedia"
|
||||
avatar: "img/avatars/wikipedia.png"
|
||||
|
||||
# This integration can be hosted in one of two ways: self-hosted or using vector.im's version.
|
||||
# By default, vector.im's version is used, but you can host your own by uncommenting the `hosted`
|
||||
# section below. Be sure to comment out or remove the `upstream` section below if you're self-hosting.
|
||||
# Self-hosted bots are expected to auto-respond to invites.
|
||||
|
||||
upstream:
|
||||
type: "vector"
|
||||
id: "wikipedia"
|
||||
#hosted:
|
||||
# homeserverUrl: "https://t2bot.io"
|
||||
# accessToken: "your_matrix_access_token_here"
|
||||
@ -1,7 +0,0 @@
|
||||
# All this configuration does is make "Youtube Widget" available in the UI
|
||||
type: "widget"
|
||||
integrationType: "youtube"
|
||||
enabled: true
|
||||
name: "YouTube Video"
|
||||
about: "Embed a YouTube, Vimeo, or DailyMotion video"
|
||||
avatar: "img/avatars/youtube.png"
|
||||
@ -1,174 +0,0 @@
|
||||
# Dimension API
|
||||
|
||||
Dimension has its own API that allows for management of integrations in Riot/Matrix.
|
||||
|
||||
## Types of integrations
|
||||
|
||||
### Simple Bots
|
||||
|
||||
* Can only be in a room or not
|
||||
* No state information held
|
||||
|
||||
### Complex Bots
|
||||
|
||||
* Simple Bots that hold state information
|
||||
|
||||
### Bridges
|
||||
|
||||
* Manage their own state through dedicated API endpoints
|
||||
|
||||
## Endpoints
|
||||
|
||||
### `GET /api/v1/dimension/integrations/{roomId}?scalar_token=your_token_here`
|
||||
|
||||
**Parameters**
|
||||
* `{roomId}` - The room ID to get integrations for
|
||||
* `scalar_token` - The scalar (dimension) token to authenticate with
|
||||
|
||||
**Example Response**
|
||||
```
|
||||
TODO
|
||||
```
|
||||
|
||||
### `DELETE /api/v1/dimension/integrations/{roomId}/{type}/{integrationType}?scalar_token=your_token_here`
|
||||
|
||||
**Parameters**
|
||||
* `{roomId}` - The room ID to remove the integration from
|
||||
* `{type}` - The integration type (eg: `bot`, `complex-bot`, `bridge`, etc)
|
||||
* `{integrationType}` - The integration subtype (eg: `irc`, `rssbot`, `giphy`, etc)
|
||||
* `scalar_token` - The scalar (dimension) token to authenticate with
|
||||
|
||||
**Example Response**
|
||||
```
|
||||
TODO
|
||||
```
|
||||
|
||||
### `PUT /api/v1/dimension/integrations/{roomId}/{type}/{integrationType}/state`
|
||||
|
||||
**Parameters**
|
||||
* `{roomId}` - The room ID to update the integration state in
|
||||
* `{type}` - The integration type (eg: `bot`, `complex-bot`, `bridge`, etc)
|
||||
* `{integrationType}` - The integration subtype (eg: `irc`, `rssbot`, `giphy`, etc)
|
||||
|
||||
**Example Body**
|
||||
```
|
||||
{
|
||||
"scalar_token": "your_token_here",
|
||||
"state": {
|
||||
// integration specific state goes here
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### `GET /api/v1/dimension/integrations/{roomId}/{type}/{integrationType}/state?scalar_token=your_token_here`
|
||||
|
||||
**Parameters**
|
||||
* `{roomId}` - The room ID to get the integration state in
|
||||
* `{type}` - The integration type (eg: `bot`, `complex-bot`, `bridge`, etc)
|
||||
* `{integrationType}` - The integration subtype (eg: `irc`, `rssbot`, `giphy`, etc)
|
||||
* `scalar_token` - The scalar (dimension) token to authenticate with
|
||||
|
||||
**Response**
|
||||
|
||||
An object representing the integration-specific state. See the documentation for the desired integration for more information.
|
||||
|
||||
### `GET /api/v1/dimension/{type}/{integrationType}/oauth/url?redirect=your_url_here&scalar_token=your_token_here`
|
||||
|
||||
**Parameters**
|
||||
* `{type}` - The integration type (eg: `bot`, `complex-bot`, `bridge`, etc)
|
||||
* `{integrationType}` - The integration subtype (eg: `irc`, `rssbot`, `giphy`, etc)
|
||||
* `redirect` - The URL to redirect to when complete
|
||||
* `scalar_token` - The scalar (dimension) token to authenticate with
|
||||
|
||||
**Example Response**
|
||||
```
|
||||
{
|
||||
"url": "https://github.com/somewhere?with=params"
|
||||
}
|
||||
```
|
||||
|
||||
### `DELETE /api/v1/dimension/{type}/{integrationType}/oauth?scalar_token=your_token_here`
|
||||
|
||||
**Parameters**
|
||||
* `{type}` - The integration type (eg: `bot`, `complex-bot`, `bridge`, etc)
|
||||
* `{integrationType}` - The integration subtype (eg: `irc`, `rssbot`, `giphy`, etc)
|
||||
* `scalar_token` - The scalar (dimension) token to authenticate with
|
||||
|
||||
**Example Response**
|
||||
```
|
||||
{}
|
||||
```
|
||||
|
||||
## Integration State Information
|
||||
|
||||
### Simple Bots
|
||||
|
||||
Do not hold state.
|
||||
|
||||
### Complex Bots
|
||||
|
||||
#### RSS Bot
|
||||
```
|
||||
{
|
||||
// Mutable using state API
|
||||
"feeds": [
|
||||
"https://some.domain.com/feed.rss",
|
||||
"https://some.domain.com/another_feed.rss"
|
||||
],
|
||||
|
||||
// Read only. Controlled by other users.
|
||||
"immutableFeeds": [
|
||||
"https://some.domain.com/third_feed.rss",
|
||||
"https://some.domain.com/fourth_feed.rss"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
#### Github
|
||||
```
|
||||
{
|
||||
// Mutable using state API
|
||||
"repositories": {
|
||||
"turt2live/matrix-dimension": ["push", "pull_request", "issues", "issue_comment", "pull_request_review_comment", "labels", "milestones", "assignments"],
|
||||
"turt2live/matrix-voyager-bot": []
|
||||
},
|
||||
|
||||
// Read only.
|
||||
"authenticated": true
|
||||
}
|
||||
```
|
||||
|
||||
*Unauthenticated response*
|
||||
```
|
||||
{
|
||||
// Read only.
|
||||
"repositories": {},
|
||||
|
||||
// Read only.
|
||||
"authenticated": false
|
||||
}
|
||||
```
|
||||
|
||||
### Bridges
|
||||
|
||||
#### IRC
|
||||
```
|
||||
{
|
||||
// Read only
|
||||
"availableNetworks": [
|
||||
{"name": "Freenode", "id": "freenode"},
|
||||
{"name": "EsperNet", "id": "espernet"},
|
||||
{"name": "OFTC", "id": "oftc"}
|
||||
],
|
||||
|
||||
// Read only. Use IRC API to mutate
|
||||
"channels": {
|
||||
"freenode": [
|
||||
"#dimensiontesting",
|
||||
"#dimensiontest"
|
||||
],
|
||||
"espernet": [],
|
||||
"oftc": []
|
||||
}
|
||||
}
|
||||
```
|
||||
@ -1,47 +0,0 @@
|
||||
# Dimension IRC Bridge API
|
||||
|
||||
As with most bridges, the IRC bridge uses a dedicated set of API endpoints to manage the state of the bridge. The IRC bridge still uses the state API provided by Dimension to report basic state information, but does not allow edits through the regular API. Instead, it is expected that the IRC API be used to mutate the state.
|
||||
|
||||
## Getting available networks/bridged channels
|
||||
|
||||
Make a call to the Dimension state API: `GET /api/v1/dimension/integrations/{roomId}/bridge/irc/state?scalar_token=...`.
|
||||
|
||||
*Example state*
|
||||
```
|
||||
{
|
||||
"availableNetworks": [
|
||||
{"name": "Freenode", "id": "freenode"},
|
||||
{"name": "Espernet", "id": "espernet"},
|
||||
{"name": "OFTC", "id": "oftc"}
|
||||
],
|
||||
"channels": {
|
||||
"freenode": [
|
||||
"#dimensiontesting",
|
||||
"#dimensiontest"
|
||||
],
|
||||
"espernet": [],
|
||||
"oftc": []
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Getting the OPs in a channel
|
||||
|
||||
IRC API Endpoint: `GET /api/v1/irc/{roomId}/ops/{network}/{channel}?scalar_token=...`. The channel should not include the prefix (`#test` becomes `test`).
|
||||
|
||||
*Example response*
|
||||
```
|
||||
["turt2live", "johndoe"]
|
||||
```
|
||||
|
||||
## Linking a new channel
|
||||
|
||||
IRC API Endpoint: `PUT /api/v1/irc/{roomId}/channels/{network}/{channel}?op=turt2live&scalar_token=...`. The channel should not include the prefix (`#test` becomes `test`).
|
||||
|
||||
A 200 OK is returned if the request to add the channel was sent. The channel will not appear in the state information until the op has approved the bridge.
|
||||
|
||||
## Unlinking a channel
|
||||
|
||||
IRC API Endpoint: `DELETE /api/v1/irc/{roomId}/channels/{network}/{channel}?scalar_token=...`. The channel should not include the prefix (`#test` becomes `test`).
|
||||
|
||||
A 200 OK is returned if the delete was successful.
|
||||
@ -1,7 +0,0 @@
|
||||
#!/bin/bash
|
||||
npm --version
|
||||
node --version
|
||||
npm install
|
||||
npm run build
|
||||
rm -f web.zip
|
||||
zip -r web.zip web-dist/*
|
||||
@ -1,10 +0,0 @@
|
||||
Release checklist:
|
||||
* Update documentation
|
||||
* Configuration migration (if possible)
|
||||
* Final testing (widgets, bots, etc)
|
||||
|
||||
After release:
|
||||
* Manage custom bots
|
||||
* Github
|
||||
* Circle CI
|
||||
* Avatars/display names for managed go-neb bots
|
||||
Loading…
Reference in New Issue
Block a user