Browse Source

Merge pull request #114 from matrix-org/kegan/remove-docs-from-readme

Remove docs from the README and link to the godoc instead
kegan/realm-docs
Kegsay 8 years ago
committed by GitHub
parent
commit
40d482f7bb
  1. 166
      README.md
  2. 7
      src/github.com/matrix-org/go-neb/services/giphy/giphy.go
  3. 32
      src/github.com/matrix-org/go-neb/services/github/github.go
  4. 33
      src/github.com/matrix-org/go-neb/services/github/github_webhook.go
  5. 7
      src/github.com/matrix-org/go-neb/services/guggy/guggy.go
  6. 20
      src/github.com/matrix-org/go-neb/services/jira/jira.go
  7. 15
      src/github.com/matrix-org/go-neb/services/rssbot/rssbot.go

166
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 &

7
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 request:
// {
// "api_key": "dc6zaTOxFJmzC"
// }
type Service struct {
types.DefaultService
// The Giphy API key to use when making HTTP requests to Giphy.

32
src/github.com/matrix-org/go-neb/services/github/github.go

@ -28,7 +28,26 @@ 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.
//
// Example request:
// {
// "RealmID": "github-realm-id"
// }
type Service struct {
types.DefaultService
// The ID of an existing "github" realm. This realm will be used to obtain
@ -201,16 +220,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")

33
src/github.com/matrix-org/go-neb/services/github/github_webhook.go

@ -19,7 +19,29 @@ 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.
//
// Example request:
// {
// 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
@ -33,12 +55,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
}

7
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 request:
// {
// "api_key": "fkweugfyuwegfweyg"
// }
type Service struct {
types.DefaultService
// The Guggy API key to use when making HTTP requests to Guggy.

20
src/github.com/matrix-org/go-neb/services/jira/jira.go

@ -29,7 +29,25 @@ 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.
//
// Example request:
// {
// Rooms: {
// "!qmElAGdFYCHoCJuaNt:localhost": {
// Realms: {
// "jira-realm-id": {
// Projects: {
// "SYN": { Expand: true },
// "BOTS": { Expand: true, Track: true }
// }
// }
// }
// }
// }
// }
type Service struct {
types.DefaultService
webhookEndpointURL string

15
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 request:
// {
// 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"`

Loading…
Cancel
Save