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