Mirror
/
go-neb
mirror of https://github.com/matrix-org/go-neb.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity
Browse Source

Remove docs from the README and link to the godoc instead

kegan/remove-docs-from-readme
Kegan Dougal 8 years ago
parent
7095e234e0
commit
f0cd6be741
4 changed files with 50 additions and 165 deletions
Whitespace
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Unified View
Diff Options
Show Stats Download Patch File Download Diff File
  1. 166
      README.md
  2. 27
      src/github.com/matrix-org/go-neb/services/github/github.go
  3. 18
      src/github.com/matrix-org/go-neb/services/github/github_webhook.go
  4. 4
      src/github.com/matrix-org/go-neb/services/jira/jira.go

166
README.md
View File

@ -116,163 +116,27 @@ Go-NEB needs to connect as a matrix user to receive messages. Go-NEB can listen
## 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 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) - [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) - [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 ## 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 ### Github Realm
This has the `Type` of `github`. To set up this 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 ## 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 # Start a documentation server listening on :6060
GOPATH=$GOPATH:$(pwd) godoc -v -http=localhost:6060 & GOPATH=$GOPATH:$(pwd) godoc -v -http=localhost:6060 &

27
src/github.com/matrix-org/go-neb/services/github/github.go
View File

@ -28,7 +28,21 @@ const ServiceType = "github"
var ownerRepoIssueRegex = regexp.MustCompile(`(([A-z0-9-_]+)/([A-z0-9-_]+))?#([0-9]+)`) var ownerRepoIssueRegex = regexp.MustCompile(`(([A-z0-9-_]+)/([A-z0-9-_]+))?#([0-9]+)`)
var ownerRepoRegex = regexp.MustCompile(`^([A-z0-9-_]+)/([A-z0-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 { type Service struct {
types.DefaultService types.DefaultService
// The ID of an existing "github" realm. This realm will be used to obtain // 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 { func (s *Service) Register(oldService types.Service, client *matrix.Client) error {
if s.RealmID == "" { if s.RealmID == "" {
return fmt.Errorf("RealmID is required") return fmt.Errorf("RealmID is required")

18
src/github.com/matrix-org/go-neb/services/github/github_webhook.go
View File

@ -19,7 +19,14 @@ import (
// WebhookServiceType of the Github Webhook service. // WebhookServiceType of the Github Webhook service.
const WebhookServiceType = "github-webhook" 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 { type WebhookService struct {
types.DefaultService types.DefaultService
webhookEndpointURL string webhookEndpointURL string
@ -33,12 +40,17 @@ type WebhookService struct {
// A map of "owner/repo"-style repositories to the events to listen for. // A map of "owner/repo"-style repositories to the events to listen for.
Repos map[string]struct { // owner/repo => { events: ["push","issue","pull_request"] } Repos map[string]struct { // owner/repo => { events: ["push","issue","pull_request"] }
// The webhook events to listen for. Currently supported: // 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 // Full list: https://developer.github.com/webhooks/#events
Events []string 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 SecretToken string
} }

4
src/github.com/matrix-org/go-neb/services/jira/jira.go
View File

@ -29,7 +29,9 @@ const ServiceType = "jira"
var issueKeyRegex = regexp.MustCompile("([A-z]+)-([0-9]+)") var issueKeyRegex = regexp.MustCompile("([A-z]+)-([0-9]+)")
var projectKeyRegex = regexp.MustCompile("^[A-z]+$") 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 { type Service struct {
types.DefaultService types.DefaultService
webhookEndpointURL string webhookEndpointURL string

Write Preview
Loading…
Cancel
Save