From f0cd6be741219a9fd85609b5206f6f04b6f171b0 Mon Sep 17 00:00:00 2001 From: Kegan Dougal Date: Fri, 4 Nov 2016 11:01:50 +0000 Subject: [PATCH 1/3] Remove docs from the README and link to the godoc instead --- README.md | 166 ++---------------- .../go-neb/services/github/github.go | 27 +-- .../go-neb/services/github/github_webhook.go | 18 +- .../matrix-org/go-neb/services/jira/jira.go | 4 +- 4 files changed, 50 insertions(+), 165 deletions(-) diff --git a/README.md b/README.md index 0f75c59..63a0ef7 100644 --- a/README.md +++ b/README.md @@ -116,163 +116,27 @@ Go-NEB needs to connect as a matrix user to receive messages. Go-NEB can listen ## 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 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. + - [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: -```bash -curl -X POST localhost:4050/admin/configureService --data-binary '{ - "Type": "echo", - "Id": "myserviceid", - "UserID": "@goneb:localhost:8448", - "Config": { - } -}' -``` - -Then invite `@goneb:localhost:8448` to any Matrix room and it will automatically join (if the client was configured to do so). Then try typing `!echo hello world` and the bot will respond with `hello world`. - -### Github Service -*Before you can set up a Github Service, you need to set up a [Github Realm](#github-realm).* - -*This service [requires a client](#configuring-clients) which has `Sync: true`.* - -This service will add the following command for [users who have associated their account with Github](#github-authentication): -``` -!github create owner/repo "Some title" "Some description" -``` - -This service will also expand the following string into a short summary of the Github issue: -``` -owner/repo#1234 -``` - -You can create this service like so: - -```bash -curl -X POST localhost:4050/admin/configureService --data-binary '{ - "Type": "github", - "Id": "githubcommands", - "UserID": "@goneb:localhost", - "Config": { - "RealmID": "mygithubrealm" - } -}' -``` - - `RealmID`: The ID of the Github Realm you created earlier. - -You can set a "default repository" for a Matrix room by sending a `m.room.bot.options` state event which has the following `content`: -```json -{ - "github": { - "default_repo": "owner/repo" - } -} -``` -This will allow you to omit the `owner/repo` from both commands and expansions e.g `#12` will be treated as `owner/repo#12`. - -### Github Webhook Service -*Before you can set up a Github Webhook Service, you need to set up a [Github Realm](#github-realm).* - -This service will send notices into a Matrix room when Github sends webhook events to it. It requires a public domain which Github can reach. This service does not require a syncing client. Notices will be sent as the given `UserID`. To create this service: +List of services: + - [Echo](https://matrix-org.github.io/go-neb/pkg/github.com/matrix-org/go-neb/services/echo/) - An example service + - [Giphy](https://matrix-org.github.io/go-neb/pkg/github.com/matrix-org/go-neb/services/giphy/) - A GIF bot + - [Github](https://matrix-org.github.io/go-neb/pkg/github.com/matrix-org/go-neb/services/github/) - A Github bot + - [Github Webhook](https://matrix-org.github.io/go-neb/pkg/github.com/matrix-org/go-neb/services/github/index.html#WebhookService) - A Github notification bot + - [Guggy](https://matrix-org.github.io/go-neb/pkg/github.com/matrix-org/go-neb/services/guggy/) - A GIF bot + - [JIRA](https://matrix-org.github.io/go-neb/pkg/github.com/matrix-org/go-neb/services/jira/) - Integration with JIRA + - [RSS Bot](https://matrix-org.github.io/go-neb/pkg/github.com/matrix-org/go-neb/services/rssbot/) - An Atom/RSS feed reader -```bash -curl -X POST localhost:4050/admin/configureService --data-binary '{ - "Type": "github-webhook", - "Id": "ghwebhooks", - "UserID": "@goneb:localhost", - "Config": { - "RealmID": "mygithubrealm", - "SecretToken": "a random string", - "ClientUserID": "@a_real_user:localhost", - "Rooms": { - "!wefiuwegfiuwhe:localhost": { - "Repos": { - "owner/repo": { - "Events": ["push"] - }, - "owner/another-repo": { - "Events": ["issues"] - } - } - } - } - } -}' -``` - - `RealmID`: The ID of the Github realm you created earlier. - - `SecretToken`: Optional. If supplied, Go-NEB will perform security checks on incoming webhook requests using this token. - - `ClientUserID`: The user ID of the Github user to setup webhooks as. This user MUST have [associated their user ID with a Github account](#github-authentication). Webhooks will be created using their OAuth token. - - `Rooms`: A map of room IDs to room info. - - `Repos`: A map of repositories to repo info. - - `Events`: A list of webhook events to send into this room. Can be any of: - - `push`: When users push to this repository. - - `pull_request`: When a pull request is made to this repository. - - `issues`: When an issue is opened/closed. - - `issue_comment`: When an issue or pull request is commented on. - - `pull_request_review_comment`: When a line comment is made on a pull request. - -### JIRA Service -*Before you can set up a JIRA Service, you need to set up a [JIRA Realm](#jira-realm).* - -TODO: Expand this section. - -``` -curl -X POST localhost:4050/admin/configureService --data-binary '{ - "Type": "jira", - "Id": "jid", - "UserID": "@goneb:localhost", - "Config": { - "ClientUserID": "@example:localhost", - "Rooms": { - "!EmwxeXCVubhskuWvaw:localhost": { - "Realms": { - "jira_realm_id": { - "Projects": { - "BOTS": { - "Expand": true, - "Track": true - } - } - } - } - } - } - } -}' -``` - -### Giphy Service -A simple service that adds the ability to use the `!giphy` command. To configure one: -```bash -curl -X POST localhost:4050/admin/configureService --data-binary '{ - "Type": "giphy", - "Id": "giphyid", - "UserID": "@goneb:localhost", - "Config": { - "APIKey": "YOUR_API_KEY" - } -}' -``` -Then invite the user into a room and type `!giphy food` and it will respond with a GIF. ## Configuring Realms -Realms are how Go-NEB authenticates users on third-party websites. Every realm MUST have the following fields: - - `ID` : An arbitrary string you can use to remember what the realm is. - - `Type`: The type of realm. This determines what code gets executed. - - `Config`: A JSON object. The contents depends on the realm `Type`. +Realms are how Go-NEB authenticates users on third-party websites. -They are configured like so: -```bash -curl -X POST localhost:4050/admin/configureAuthRealm --data-binary '{ - "ID": "some_arbitrary_string", - "Type": "some_realm_type", - "Config": { - ... - } -}' -``` + - [HTTP API Docs](https://matrix-org.github.io/go-neb/pkg/github.com/matrix-org/go-neb/api/handlers/index.html#ConfigureAuthRealm.OnIncomingRequest) + - [JSON Request Body Docs](https://matrix-org.github.io/go-neb/pkg/github.com/matrix-org/go-neb/api/index.html#ConfigureAuthRealmRequest) ### Github Realm This has the `Type` of `github`. To set up this realm: @@ -421,6 +285,8 @@ Auth Session = An individual authentication session /requestAuthSession makes th ## Viewing the API docs +The full docs can be found on [Github Pages](https://matrix-org.github.io/go-neb/pkg/github.com/matrix-org/go-neb). Alternatively, you can locally host the API docs: + ``` # Start a documentation server listening on :6060 GOPATH=$GOPATH:$(pwd) godoc -v -http=localhost:6060 & diff --git a/src/github.com/matrix-org/go-neb/services/github/github.go b/src/github.com/matrix-org/go-neb/services/github/github.go index e10ac14..228b0b6 100644 --- a/src/github.com/matrix-org/go-neb/services/github/github.go +++ b/src/github.com/matrix-org/go-neb/services/github/github.go @@ -28,7 +28,21 @@ const ServiceType = "github" var ownerRepoIssueRegex = regexp.MustCompile(`(([A-z0-9-_]+)/([A-z0-9-_]+))?#([0-9]+)`) var ownerRepoRegex = regexp.MustCompile(`^([A-z0-9-_]+)/([A-z0-9-_]+)$`) -// Service contains the Config fields for this service. +// Service contains the Config fields for the Github service. +// +// Before you can set up a Github Service, you need to set up a Github Realm. This +// service requires a syncing client. +// +// You can set a "default repository" for a Matrix room by sending a `m.room.bot.options` state event +// which has the following `content`: +// +// { +// "github": { +// "default_repo": "owner/repo" +// } +// } +// +// This will allow the "owner/repo" to be omitted when creating/expanding issues. type Service struct { types.DefaultService // The ID of an existing "github" realm. This realm will be used to obtain @@ -201,16 +215,7 @@ func (s *Service) Expansions(cli *matrix.Client, roomID string) []types.Expansio } } -// Register will create webhooks for the repos specified in Rooms -// -// The hooks made are a delta between the old service and the current configuration. If all webhooks are made, -// Register() succeeds. If any webhook fails to be created, Register() fails. A delta is used to allow clients to incrementally -// build up the service config without recreating the hooks every time a change is made. -// -// Hooks are deleted when this service receives a webhook event from Github for a repo which has no user configurations. -// -// Hooks can get out of sync if a user manually deletes a hook in the Github UI. In this case, toggling the repo configuration will -// force NEB to recreate the hook. +// Register makes sure that the given realm ID maps to a github realm. func (s *Service) Register(oldService types.Service, client *matrix.Client) error { if s.RealmID == "" { return fmt.Errorf("RealmID is required") diff --git a/src/github.com/matrix-org/go-neb/services/github/github_webhook.go b/src/github.com/matrix-org/go-neb/services/github/github_webhook.go index b2393b0..6c126d7 100644 --- a/src/github.com/matrix-org/go-neb/services/github/github_webhook.go +++ b/src/github.com/matrix-org/go-neb/services/github/github_webhook.go @@ -19,7 +19,14 @@ import ( // WebhookServiceType of the Github Webhook service. const WebhookServiceType = "github-webhook" -// WebhookService contains the Config fields for this service. +// WebhookService contains the Config fields for the Github Webhook Service. +// +// Before you can set up a Github Service, you need to set up a Github Realm. This +// service does not require a syncing client. +// +// This service will send notices into a Matrix room when Github sends webhook events +// to it. It requires a public domain which Github can reach. Notices will be sent +// as the service user ID, not the ClientUserID. type WebhookService struct { types.DefaultService webhookEndpointURL string @@ -33,12 +40,17 @@ type WebhookService struct { // A map of "owner/repo"-style repositories to the events to listen for. Repos map[string]struct { // owner/repo => { events: ["push","issue","pull_request"] } // The webhook events to listen for. Currently supported: - // push, pull_request, issues, issue_comment, pull_request_review_comment + // push : When users push to this repository. + // pull_request : When a pull request is made to this repository. + // issues : When an issue is opened/closed. + // issue_comment : When an issue or pull request is commented on. + // pull_request_review_comment : When a line comment is made on a pull request. // Full list: https://developer.github.com/webhooks/#events Events []string } } - // Optional. The secret token to supply when creating the webhook. + // Optional. The secret token to supply when creating the webhook. If supplied, + // Go-NEB will perform security checks on incoming webhook requests using this token. SecretToken string } diff --git a/src/github.com/matrix-org/go-neb/services/jira/jira.go b/src/github.com/matrix-org/go-neb/services/jira/jira.go index 718455a..713ccd4 100644 --- a/src/github.com/matrix-org/go-neb/services/jira/jira.go +++ b/src/github.com/matrix-org/go-neb/services/jira/jira.go @@ -29,7 +29,9 @@ const ServiceType = "jira" var issueKeyRegex = regexp.MustCompile("([A-z]+)-([0-9]+)") var projectKeyRegex = regexp.MustCompile("^[A-z]+$") -// Service contains the Config fields for this service. +// Service contains the Config fields for the JIRA service. +// +// Before you can set up a JIRA Service, you need to set up a JIRA Realm. type Service struct { types.DefaultService webhookEndpointURL string From 209af79efeeab1793a986ebedf44f0632ca48680 Mon Sep 17 00:00:00 2001 From: Kegan Dougal Date: Fri, 4 Nov 2016 11:15:01 +0000 Subject: [PATCH 2/3] Add example configs for each service --- .../matrix-org/go-neb/services/giphy/giphy.go | 7 ++++++- .../matrix-org/go-neb/services/github/github.go | 5 +++++ .../go-neb/services/github/github_webhook.go | 15 +++++++++++++++ .../matrix-org/go-neb/services/guggy/guggy.go | 7 ++++++- .../matrix-org/go-neb/services/jira/jira.go | 16 ++++++++++++++++ .../matrix-org/go-neb/services/rssbot/rssbot.go | 15 ++++++++++++++- 6 files changed, 62 insertions(+), 3 deletions(-) diff --git a/src/github.com/matrix-org/go-neb/services/giphy/giphy.go b/src/github.com/matrix-org/go-neb/services/giphy/giphy.go index 53a4697..ff5ae84 100644 --- a/src/github.com/matrix-org/go-neb/services/giphy/giphy.go +++ b/src/github.com/matrix-org/go-neb/services/giphy/giphy.go @@ -34,7 +34,12 @@ type giphySearch struct { Data []result } -// Service contains the Config fields for this service. +// Service contains the Config fields for the Giphy Service. +// +// Example: +// { +// "api_key": "dc6zaTOxFJmzC" +// } type Service struct { types.DefaultService // The Giphy API key to use when making HTTP requests to Giphy. diff --git a/src/github.com/matrix-org/go-neb/services/github/github.go b/src/github.com/matrix-org/go-neb/services/github/github.go index 228b0b6..e0d19f5 100644 --- a/src/github.com/matrix-org/go-neb/services/github/github.go +++ b/src/github.com/matrix-org/go-neb/services/github/github.go @@ -43,6 +43,11 @@ var ownerRepoRegex = regexp.MustCompile(`^([A-z0-9-_]+)/([A-z0-9-_]+)$`) // } // // This will allow the "owner/repo" to be omitted when creating/expanding issues. +// +// Example: +// { +// "RealmID": "github-realm-id" +// } type Service struct { types.DefaultService // The ID of an existing "github" realm. This realm will be used to obtain diff --git a/src/github.com/matrix-org/go-neb/services/github/github_webhook.go b/src/github.com/matrix-org/go-neb/services/github/github_webhook.go index 6c126d7..9e4135d 100644 --- a/src/github.com/matrix-org/go-neb/services/github/github_webhook.go +++ b/src/github.com/matrix-org/go-neb/services/github/github_webhook.go @@ -27,6 +27,21 @@ const WebhookServiceType = "github-webhook" // This service will send notices into a Matrix room when Github sends webhook events // to it. It requires a public domain which Github can reach. Notices will be sent // as the service user ID, not the ClientUserID. +// +// Example: +// { +// ClientUserID: "@alice:localhost", +// RealmID: "github-realm-id", +// Rooms: { +// "!qmElAGdFYCHoCJuaNt:localhost": { +// Repos: { +// "matrix-org/go-neb": { +// Events: ["push", "issues", "pull_request"] +// } +// } +// } +// } +// } type WebhookService struct { types.DefaultService webhookEndpointURL string diff --git a/src/github.com/matrix-org/go-neb/services/guggy/guggy.go b/src/github.com/matrix-org/go-neb/services/guggy/guggy.go index d4b50dd..e1a3fda 100644 --- a/src/github.com/matrix-org/go-neb/services/guggy/guggy.go +++ b/src/github.com/matrix-org/go-neb/services/guggy/guggy.go @@ -32,7 +32,12 @@ type guggyGifResult struct { Height float64 `json:"height"` } -// Service contains the Config fields for this service. +// Service contains the Config fields for the Guggy service. +// +// Example: +// { +// "api_key": "fkweugfyuwegfweyg" +// } type Service struct { types.DefaultService // The Guggy API key to use when making HTTP requests to Guggy. diff --git a/src/github.com/matrix-org/go-neb/services/jira/jira.go b/src/github.com/matrix-org/go-neb/services/jira/jira.go index 713ccd4..6959ad5 100644 --- a/src/github.com/matrix-org/go-neb/services/jira/jira.go +++ b/src/github.com/matrix-org/go-neb/services/jira/jira.go @@ -32,6 +32,22 @@ var projectKeyRegex = regexp.MustCompile("^[A-z]+$") // Service contains the Config fields for the JIRA service. // // Before you can set up a JIRA Service, you need to set up a JIRA Realm. +// +// Example: +// { +// Rooms: { +// "!qmElAGdFYCHoCJuaNt:localhost": { +// Realms: { +// "jira-realm-id": { +// Projects: { +// "SYN": { Expand: true }, +// "BOTS": { Expand: true, Track: true } +// } +// } +// } +// } +// } +// } type Service struct { types.DefaultService webhookEndpointURL string diff --git a/src/github.com/matrix-org/go-neb/services/rssbot/rssbot.go b/src/github.com/matrix-org/go-neb/services/rssbot/rssbot.go index f3833ab..0dc7e38 100644 --- a/src/github.com/matrix-org/go-neb/services/rssbot/rssbot.go +++ b/src/github.com/matrix-org/go-neb/services/rssbot/rssbot.go @@ -36,11 +36,24 @@ var ( const minPollingIntervalSeconds = 60 * 5 // 5 min (News feeds can be genuinely spammy) // Service contains the Config fields for this service. +// +// Example: +// { +// feeds: { +// "http://rss.cnn.com/rss/edition.rss": { +// poll_interval_mins: 60, +// rooms: ["!cBrPbzWazCtlkMNQSF:localhost"] +// }, +// "https://www.wired.com/feed/": { +// rooms: ["!qmElAGdFYCHoCJuaNt:localhost"] +// } +// } +// } type Service struct { types.DefaultService // Feeds is a map of feed URL to configuration options for this feed. Feeds map[string]struct { - // The time to wait between polls. If this is less than minPollingIntervalSeconds, it is ignored. + // Optional. The time to wait between polls. If this is less than minPollingIntervalSeconds, it is ignored. PollIntervalMins int `json:"poll_interval_mins"` // The list of rooms to send feed updates into. This cannot be empty. Rooms []string `json:"rooms"` From a06ac2d3bed9da8c131cb3c359f9151b5c99dbd5 Mon Sep 17 00:00:00 2001 From: Kegan Dougal Date: Fri, 4 Nov 2016 11:23:28 +0000 Subject: [PATCH 3/3] Make it clear that these are example requests --- src/github.com/matrix-org/go-neb/services/giphy/giphy.go | 2 +- src/github.com/matrix-org/go-neb/services/github/github.go | 2 +- .../matrix-org/go-neb/services/github/github_webhook.go | 2 +- src/github.com/matrix-org/go-neb/services/guggy/guggy.go | 2 +- src/github.com/matrix-org/go-neb/services/jira/jira.go | 2 +- src/github.com/matrix-org/go-neb/services/rssbot/rssbot.go | 2 +- 6 files changed, 6 insertions(+), 6 deletions(-) diff --git a/src/github.com/matrix-org/go-neb/services/giphy/giphy.go b/src/github.com/matrix-org/go-neb/services/giphy/giphy.go index ff5ae84..c82333d 100644 --- a/src/github.com/matrix-org/go-neb/services/giphy/giphy.go +++ b/src/github.com/matrix-org/go-neb/services/giphy/giphy.go @@ -36,7 +36,7 @@ type giphySearch struct { // Service contains the Config fields for the Giphy Service. // -// Example: +// Example request: // { // "api_key": "dc6zaTOxFJmzC" // } diff --git a/src/github.com/matrix-org/go-neb/services/github/github.go b/src/github.com/matrix-org/go-neb/services/github/github.go index e0d19f5..7945dd7 100644 --- a/src/github.com/matrix-org/go-neb/services/github/github.go +++ b/src/github.com/matrix-org/go-neb/services/github/github.go @@ -44,7 +44,7 @@ var ownerRepoRegex = regexp.MustCompile(`^([A-z0-9-_]+)/([A-z0-9-_]+)$`) // // This will allow the "owner/repo" to be omitted when creating/expanding issues. // -// Example: +// Example request: // { // "RealmID": "github-realm-id" // } diff --git a/src/github.com/matrix-org/go-neb/services/github/github_webhook.go b/src/github.com/matrix-org/go-neb/services/github/github_webhook.go index 9e4135d..eca1a3e 100644 --- a/src/github.com/matrix-org/go-neb/services/github/github_webhook.go +++ b/src/github.com/matrix-org/go-neb/services/github/github_webhook.go @@ -28,7 +28,7 @@ const WebhookServiceType = "github-webhook" // to it. It requires a public domain which Github can reach. Notices will be sent // as the service user ID, not the ClientUserID. // -// Example: +// Example request: // { // ClientUserID: "@alice:localhost", // RealmID: "github-realm-id", diff --git a/src/github.com/matrix-org/go-neb/services/guggy/guggy.go b/src/github.com/matrix-org/go-neb/services/guggy/guggy.go index e1a3fda..fa4b5a4 100644 --- a/src/github.com/matrix-org/go-neb/services/guggy/guggy.go +++ b/src/github.com/matrix-org/go-neb/services/guggy/guggy.go @@ -34,7 +34,7 @@ type guggyGifResult struct { // Service contains the Config fields for the Guggy service. // -// Example: +// Example request: // { // "api_key": "fkweugfyuwegfweyg" // } diff --git a/src/github.com/matrix-org/go-neb/services/jira/jira.go b/src/github.com/matrix-org/go-neb/services/jira/jira.go index 6959ad5..ea59805 100644 --- a/src/github.com/matrix-org/go-neb/services/jira/jira.go +++ b/src/github.com/matrix-org/go-neb/services/jira/jira.go @@ -33,7 +33,7 @@ var projectKeyRegex = regexp.MustCompile("^[A-z]+$") // // Before you can set up a JIRA Service, you need to set up a JIRA Realm. // -// Example: +// Example request: // { // Rooms: { // "!qmElAGdFYCHoCJuaNt:localhost": { diff --git a/src/github.com/matrix-org/go-neb/services/rssbot/rssbot.go b/src/github.com/matrix-org/go-neb/services/rssbot/rssbot.go index 0dc7e38..21c9b1d 100644 --- a/src/github.com/matrix-org/go-neb/services/rssbot/rssbot.go +++ b/src/github.com/matrix-org/go-neb/services/rssbot/rssbot.go @@ -37,7 +37,7 @@ const minPollingIntervalSeconds = 60 * 5 // 5 min (News feeds can be genuinely s // Service contains the Config fields for this service. // -// Example: +// Example request: // { // feeds: { // "http://rss.cnn.com/rss/edition.rss": {