Browse Source

Merge pull request #109 from matrix-org/kegan/readme-to-docs

Delete API info from README and point to gh-page. Add gendoc script
kegan/docs-services
Kegsay 8 years ago
committed by GitHub
parent
commit
5153857926
  1. 2
      .gitignore
  2. 66
      README.md
  3. 10
      config.sample.yaml
  4. 34
      gendoc.sh

2
.gitignore

@ -1,3 +1,5 @@
godoc
.*.swp .*.swp
# Compiled Object files, Static and Dynamic libs (Shared Objects) # Compiled Object files, Static and Dynamic libs (Shared Objects)

66
README.md

@ -108,72 +108,16 @@ Go-NEB needs to be "configured" with clients and services before it will do anyt
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](config.sample.yaml) which explains all the options. In most cases, these are *direct mappings* to the corresponding 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](config.sample.yaml) which explains all the options. In most cases, these are *direct mappings* to the corresponding HTTP API.
## Configuring Clients ## Configuring Clients
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. To create a user:
```bash
curl -X POST localhost:4050/admin/configureClient --data-binary '{
"UserID": "@goneb:localhost:8448",
"HomeserverURL": "http://localhost:8008",
"AccessToken": "<access_token>",
"Sync": true,
"AutoJoinRooms": true,
"DisplayName": "My Bot"
}'
```
- `UserID` is the complete user ID of the client to connect as. The user MUST already exist.
- `HomeserverURL` is the complete Homeserver URL for the given user ID.
- `AccessToken` is the user's access token.
- `Sync`, if `true`, will start a `/sync` stream so this client will receive incoming messages. This is required for services which need a live stream to the server (e.g. to respond to `!commands` and expand issues). It is not required for services which do not respond to Matrix users (e.g. webhook notifications).
- `AutoJoinRooms`, if `true`, will automatically join rooms when an invite is received. This option is only valid when `Sync: true`.
- `DisplayName`, if set, will set the given user's profile display name to the string given.
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.
Go-NEB will respond with the previous configuration for this client, if one exists, as well as echo back the complete configuration for the client:
```json
{
"OldClient": {},
"NewClient": {
"UserID": "@goneb:localhost:8448",
"HomeserverURL": "http://localhost:8008",
"AccessToken": "<access_token>",
"Sync": true,
"AutoJoinRooms": true,
"DisplayName": "My Bot"
}
}
```
- [HTTP API Docs](https://matrix-org.github.io/go-neb/pkg/github.com/matrix-org/go-neb/api/handlers/index.html#ConfigureClient.OnIncomingRequest)
- [JSON Request Body Docs](https://matrix-org.github.io/go-neb/pkg/github.com/matrix-org/go-neb/api/index.html#ClientConfig)
## Configuring Services ## Configuring Services
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. 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 MUST have the following fields:
- `Type` : The type of service. This determines which code is executed.
- `Id` : An arbitrary string which you can use to identify this service.
- `UserID` : A user ID of a client which has been previously configured on Go-NEB. If this user does not exist, an error will be returned.
- `Config` : A JSON object. The contents of this object depends on the service.
The information about a Service can be retrieved based on their `Id` like so:
```bash
curl -X POST localhost:4050/admin/getService --data-binary '{
"Id": "myserviceid"
}'
```
This will return:
```yaml
# HTTP 200 OK
{
"Type": "echo",
"Id": "myserviceid",
"UserID": "@goneb:localhost:8448",
"Config": {}
}
```
If the service is not found, this will return:
```yaml
# HTTP 404 Not Found
{ "message": "Service not found" }
```
If you configure an existing Service (based on ID), the entire service will be replaced with the new information.
- [HTTP API Docs](https://matrix-org.github.io/go-neb/pkg/github.com/matrix-org/go-neb/api/handlers/index.html#ConfigureService.OnIncomingRequest)
- [JSON Request Body Docs](https://matrix-org.github.io/go-neb/pkg/github.com/matrix-org/go-neb/api/index.html#ConfigureServiceRequest)
### Echo Service ### Echo Service
The simplest service. This will echo back any `!echo` command. To configure one: The simplest service. This will echo back any `!echo` command. To configure one:

10
config.sample.yaml

@ -16,7 +16,8 @@
# The list of clients which Go-NEB is aware of. # The list of clients which Go-NEB is aware of.
# Delete or modify this list as appropriate. # Delete or modify this list as appropriate.
# See the docs for /configureClient for the full list of options.
# See the docs for /configureClient for the full list of options:
# https://matrix-org.github.io/go-neb/pkg/github.com/matrix-org/go-neb/api/index.html#ClientConfig
clients: clients:
- UserID: "@goneb:localhost" - UserID: "@goneb:localhost"
AccessToken: "MDASDASJDIASDJASDAFGFRGER" AccessToken: "MDASDASJDIASDJASDAFGFRGER"
@ -34,7 +35,8 @@ clients:
# The list of realms which Go-NEB is aware of. # The list of realms which Go-NEB is aware of.
# Delete or modify this list as appropriate. # Delete or modify this list as appropriate.
# See the docs for /configureAuthRealm for the full list of options.
# See the docs for /configureAuthRealm for the full list of options:
# https://matrix-org.github.io/go-neb/pkg/github.com/matrix-org/go-neb/api/index.html#ConfigureAuthRealmRequest
realms: realms:
- ID: "github_realm" - ID: "github_realm"
Type: "github" Type: "github"
@ -44,6 +46,7 @@ realms:
# Delete or modify this list as appropriate. # Delete or modify this list as appropriate.
# The full list of options are shown below: there is no single HTTP endpoint # The full list of options are shown below: there is no single HTTP endpoint
# which maps to this section. # which maps to this section.
# https://matrix-org.github.io/go-neb/pkg/github.com/matrix-org/go-neb/api/index.html#Session
sessions: sessions:
- SessionID: "your_github_session" - SessionID: "your_github_session"
RealmID: "github_realm" RealmID: "github_realm"
@ -56,7 +59,8 @@ sessions:
# The list of services which Go-NEB is aware of. # The list of services which Go-NEB is aware of.
# Delete or modify this list as appropriate. # Delete or modify this list as appropriate.
# See the docs for /configureService for the full list of options.
# See the docs for /configureService for the full list of options:
# https://matrix-org.github.io/go-neb/pkg/github.com/matrix-org/go-neb/api/index.html#ConfigureServiceRequest
services: services:
- ID: "giphy_service" - ID: "giphy_service"
Type: "giphy" Type: "giphy"

34
gendoc.sh

@ -0,0 +1,34 @@
#!/bin/bash
set -u
DOC_DIR=godoc
# Run a godoc server which we will scrape. Clobber the GOPATH to include
# only our dependencies.
GOPATH=$(pwd):$(pwd)/vendor godoc -http=localhost:6060 &
DOC_PID=$!
# Wait for the server to init
while :
do
curl -s "http://localhost:6060" > /dev/null
if [ $? -eq 0 ] # exit code is 0 if we connected
then
break
fi
done
# Scrape the pkg directory for the API docs. Scrap lib for the CSS/JS. Ignore everything else.
# The output is dumped to the directory "localhost:6060".
wget -r -m -k -E -p --include-directories="/pkg,/lib" --exclude-directories="*" http://localhost:6060/pkg/github.com/matrix-org/go-neb/
# Stop the godoc server
kill -9 $DOC_PID
# Delete the old directory or else mv will put the localhost dir into
# the DOC_DIR if it already exists.
rm -rf $DOC_DIR
mv localhost\:6060 $DOC_DIR
echo "Docs can be found in $DOC_DIR"
echo "Replace /lib and /pkg in the gh-pages branch to update gh-pages"
Loading…
Cancel
Save