From 3bce58ef07308f7ba3ab2070b63e30c212d0273b Mon Sep 17 00:00:00 2001 From: Kegan Dougal Date: Wed, 2 Nov 2016 15:26:35 +0000 Subject: [PATCH 1/6] Remove some docs from README. Point to gh-pages for the docs --- README.md | 66 +++++-------------------------------------------------- 1 file changed, 5 insertions(+), 61 deletions(-) diff --git a/README.md b/README.md index 6b11b44..0f75c59 100644 --- a/README.md +++ b/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. ## 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": "", - "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": "", - "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 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 The simplest service. This will echo back any `!echo` command. To configure one: From 579cf29231018a42c562698119adb962c11cddce Mon Sep 17 00:00:00 2001 From: Kegan Dougal Date: Wed, 2 Nov 2016 15:44:08 +0000 Subject: [PATCH 2/6] Add a gendoc script Dumps output to .godoc --- .gitignore | 2 ++ gendoc.sh | 20 ++++++++++++++++++++ 2 files changed, 22 insertions(+) create mode 100755 gendoc.sh diff --git a/.gitignore b/.gitignore index a11dc93..9e11225 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,5 @@ +.godoc + .*.swp # Compiled Object files, Static and Dynamic libs (Shared Objects) diff --git a/gendoc.sh b/gendoc.sh new file mode 100755 index 0000000..7cba3c1 --- /dev/null +++ b/gendoc.sh @@ -0,0 +1,20 @@ +#!/bin/bash + +# 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 +sleep 1 + +# 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 + +mv localhost\:6060 .godoc +echo "Docs can be found in .godoc" +echo "Replace /lib and /pkg in the gh-pages branch to update gh-pages" From 4dc1adf5e2e711837bd94f131a8a93c298bac8a8 Mon Sep 17 00:00:00 2001 From: Kegan Dougal Date: Wed, 2 Nov 2016 16:01:07 +0000 Subject: [PATCH 3/6] Allow gendoc.sh to be called multiple times --- .gitignore | 2 +- gendoc.sh | 9 +++++++-- 2 files changed, 8 insertions(+), 3 deletions(-) diff --git a/.gitignore b/.gitignore index 9e11225..2410f8a 100644 --- a/.gitignore +++ b/.gitignore @@ -1,4 +1,4 @@ -.godoc +godoc .*.swp diff --git a/gendoc.sh b/gendoc.sh index 7cba3c1..1a5ede7 100755 --- a/gendoc.sh +++ b/gendoc.sh @@ -1,5 +1,7 @@ #!/bin/bash +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 & @@ -15,6 +17,9 @@ wget -r -m -k -E -p --include-directories="/pkg,/lib" --exclude-directories="*" # Stop the godoc server kill -9 $DOC_PID -mv localhost\:6060 .godoc -echo "Docs can be found in .godoc" +# Delete the old directory or else mv will put the localhost dir into .godoc +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" From 89f3776cbd29b5c88f8905cfeec779917cb55a4f Mon Sep 17 00:00:00 2001 From: Kegan Dougal Date: Wed, 2 Nov 2016 16:03:27 +0000 Subject: [PATCH 4/6] Less lying --- gendoc.sh | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/gendoc.sh b/gendoc.sh index 1a5ede7..b61d5e8 100755 --- a/gendoc.sh +++ b/gendoc.sh @@ -17,7 +17,8 @@ wget -r -m -k -E -p --include-directories="/pkg,/lib" --exclude-directories="*" # Stop the godoc server kill -9 $DOC_PID -# Delete the old directory or else mv will put the localhost dir into .godoc +# 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 From 5179caceda52a74c5c2adaa6da0edb9d5450607a Mon Sep 17 00:00:00 2001 From: Kegan Dougal Date: Wed, 2 Nov 2016 16:12:13 +0000 Subject: [PATCH 5/6] Add links to gh-pages in config.sample.yaml --- config.sample.yaml | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/config.sample.yaml b/config.sample.yaml index 5428c6f..24516db 100644 --- a/config.sample.yaml +++ b/config.sample.yaml @@ -16,7 +16,8 @@ # The list of clients which Go-NEB is aware of. # 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: - UserID: "@goneb:localhost" AccessToken: "MDASDASJDIASDJASDAFGFRGER" @@ -34,7 +35,8 @@ clients: # The list of realms which Go-NEB is aware of. # 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: - ID: "github_realm" Type: "github" @@ -44,6 +46,7 @@ realms: # Delete or modify this list as appropriate. # The full list of options are shown below: there is no single HTTP endpoint # which maps to this section. +# https://matrix-org.github.io/go-neb/pkg/github.com/matrix-org/go-neb/api/index.html#Session sessions: - SessionID: "your_github_session" RealmID: "github_realm" @@ -56,7 +59,8 @@ sessions: # The list of services which Go-NEB is aware of. # 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: - ID: "giphy_service" Type: "giphy" From a8336cdeab5e0c26046a71cd60b1e5b62323553e Mon Sep 17 00:00:00 2001 From: Kegan Dougal Date: Wed, 2 Nov 2016 16:52:11 +0000 Subject: [PATCH 6/6] Review comments --- gendoc.sh | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/gendoc.sh b/gendoc.sh index b61d5e8..d088e12 100755 --- a/gendoc.sh +++ b/gendoc.sh @@ -1,4 +1,5 @@ #!/bin/bash +set -u DOC_DIR=godoc @@ -8,7 +9,14 @@ GOPATH=$(pwd):$(pwd)/vendor godoc -http=localhost:6060 & DOC_PID=$! # Wait for the server to init -sleep 1 +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".