Name: go-neb
Owner: matrix.org
Description: Extensible matrix bot written in Go
Created: 2016-07-29 09:39:03.0
Updated: 2017-12-12 19:12:06.0
Pushed: 2017-12-15 08:01:41.0
Homepage: null
Size: 11116
Language: Go
GitHub Committers
| User | Most Recent Commit | # Commits |
|---|
Other Committers
| User | Most Recent Commit | # Commits |
|---|
Go-NEB is a Matrix bot written in Go. It is the successor to Matrix-NEB, the original Matrix bot written in Python.
Clone and run (Requires Go 1.7+ and GB):
uild github.com/matrix-org/go-neb
_ADDRESS=:4050 DATABASE_TYPE=sqlite3 DATABASE_URL=go-neb.db?_busy_timeout=5000 BASE_URL=http://localhost:4050 bin/go-neb
Get a Matrix user ID and access token and give it to Go-NEB:
-X POST localhost:4050/admin/configureClient --data-binary '{
"UserID": "@goneb:localhost",
"HomeserverURL": "http://localhost:8008",
"AccessToken": "<access_token>",
"Sync": true,
"AutoJoinRooms": true,
"DisplayName": "My Bot"
Tell it what service to run:
-X POST localhost:4050/admin/configureService --data-binary '{
"Type": "echo",
"Id": "myserviceid",
"UserID": "@goneb:localhost",
"Config": {}
Invite the bot user into a Matrix room and type !echo hello world. It will reply with hello world.
foo/bar#1234.#1234 to automatically expand, as well as shorter issue creation command syntax.FOO-1234.Go-NEB is built using Go 1.7+ and GB. Once you have installed Go, run the following commands:
stall gb
et github.com/constabulary/gb/...
one the go-neb repository
clone https://github.com/matrix-org/go-neb
o-neb
ild go-neb
uild github.com/matrix-org/go-neb
Go-NEB uses environment variables to configure its SQLite database and bind address. To run Go-NEB, run the following command:
_ADDRESS=:4050 DATABASE_TYPE=sqlite3 DATABASE_URL=go-neb.db?_busy_timeout=5000 BASE_URL=https://public.facing.endpoint bin/go-neb
BIND_ADDRESS is the port to listen on.DATABASE_TYPE MUST be “sqlite3”. No other type is supported.DATABASE_URL is where to find the database file. One will be created if it does not exist. It is a URL so parameters can be passed to it. We recommend setting _busy_timeout=5000 to prevent sqlite3 “database is locked” errors.BASE_URL should be the public-facing endpoint that sites like Github can send webhooks to.CONFIG_FILE is the path to the configuration file to read from. This isn't included in the example above, so Go-NEB will operate in HTTP mode.Go-NEB needs to be “configured” with clients and services before it will do anything useful. It can be configured via a configuration file OR by an HTTP API.
If you run Go-NEB with a CONFIG_FILE environment variable, it will load that file and use it for services, clients, etc. There is a sample configuration file which explains all the options. In most cases, these are direct mappings to the corresponding HTTP API.
The API is documented in sections using godoc. The sections consists of:
To form the complete API, you need to combine the HTTP API with the JSON request body, and the “Configuration” information (which is always under a JSON key called Config). In addition, most APIs have a Type which determines which piece of code to load. To find out what the right type is for the thing you're creating, check the constants defined in godoc.
Go-NEB needs to connect as a matrix user to receive messages. Go-NEB can listen for messages as multiple matrix users. The users are configured using an HTTP API and the config is stored in the database.
Services contain all the useful functionality in Go-NEB. They require a client to operate. Services are configured using an HTTP API and the config is stored in the database. Services use one of the matrix users configured on Go-NEB to send/receive matrix messages.
Every service has an “ID”, “type” and “user ID”. Services may specify additional “config” keys: see the specific service you're interested in for the additional keys, if any.
List of Services:
Realms are how Go-NEB authenticates users on third-party websites.
List of Realms:
Authentication via HTTP:
Authentication via the config file:
There's a bunch more tools this project uses when developing in order to do things like linting. Some of them are bundled with go (fmt and vet) but some are not. You should install the ones which are not:
et github.com/golang/lint/golint
et github.com/fzipp/gocyclo
You can then install the pre-commit hook:
oks/install.sh
OMESERVER
|
==========================================================+
| Go-NEB |
--------+ |
Clients | |
--------+ |
| |
--------+ +------------+ +--------------+ |
Service |-------| Auth Realm |------| Auth Session |-+ |
--------+ +------------+ +--------------+ | |
^ ^ +---------------+ |
| | |
==========================================================+
| |
WEBHOOK REDIRECT
REQUEST REQUEST
nts = A thing which can talk to homeservers and listen for events. /configureClient makes these.
ice = An individual bot, configured by a user. /configureService makes these.
Realm = A place where a user can authenticate with. /configureAuthRealm makes these.
Session = An individual authentication session /requestAuthSession makes these.
The full docs can be found on Github Pages. Alternatively, you can locally host the API docs:
art a documentation server listening on :6060
TH=$GOPATH:$(pwd) godoc -v -http=localhost:6060 &
en up the documentation for go-neb in a browser.
ible-browser http://localhost:6060/pkg/github.com/matrix-org/go-neb
There is a Dockerfile in the root of the repository and a build-docker-image.sh script that uses an alpine-based golang container to build go-neb (note that this will overwrite host-built binaries in pkg/ and bin/) and then builds the docker image using that binary.
The image sets the following environment variables:
_ADDRESS=:4050
BASE_TYPE=sqlite3
BASE_URL=/data/go-neb.db?_busy_timeout=5000
The image exposes port 4050 and a volume at /data. The BASE_URL environment variable needs to be set, a volume should be mounted at /data and port 4050 should be appropriately mapped as desired.