From d860b9acd1094f354657d2947744252098273b44 Mon Sep 17 00:00:00 2001 From: Will Hunt Date: Tue, 4 Jan 2022 17:49:59 +0000 Subject: [PATCH] Docs and config improvements (#124) * Don't suggest to bind widgets in config * Don't support 'appservice' just yet for the listener service. * Add config validator * Clarify listener configuration * Improve text of webhooks docs * Update config sample * Revert "Add config validator" This reverts commit b422b3da3d246f9eb1a6b47641ea4c1315252c2c. * changelog --- changelog.d/124.doc | 1 + config.sample.yml | 5 +++-- docs/_site/style.css | 1 + docs/setup.md | 35 ++++++++++++++++++++++++++++++++--- docs/setup/webhooks.md | 24 ++++++++++-------------- src/Config/Config.ts | 2 ++ src/Config/Defaults.ts | 2 +- src/ListenerService.ts | 5 +++-- 8 files changed, 53 insertions(+), 22 deletions(-) create mode 100644 changelog.d/124.doc diff --git a/changelog.d/124.doc b/changelog.d/124.doc new file mode 100644 index 00000000..f9273120 --- /dev/null +++ b/changelog.d/124.doc @@ -0,0 +1 @@ +Improve docs around listener and generic webhook configuration \ No newline at end of file diff --git a/config.sample.yml b/config.sample.yml index 832856db..54a6da35 100644 --- a/config.sample.yml +++ b/config.sample.yml @@ -85,13 +85,14 @@ logging: listeners: # (Optional) HTTP Listener configuration. # Bind resource endpoints to ports and addresses. - # 'resources' may be any of webhooks, widgets, metrics, provisioning, appservice + # 'port' must be specified. Each listener must listen on a unique port. + # 'bindAddress' will default to '127.0.0.1' if not specified, which may not be suited to Docker environments. + # 'resources' may be any of webhooks, widgets, metrics, provisioning # - port: 9000 bindAddress: 0.0.0.0 resources: - webhooks - - widgets - port: 9001 bindAddress: 127.0.0.1 resources: diff --git a/docs/_site/style.css b/docs/_site/style.css index 7971d15b..bc9dbe3d 100644 --- a/docs/_site/style.css +++ b/docs/_site/style.css @@ -1,4 +1,5 @@ .notice { + color: black; border: 2px solid #0098d4; border-left-width: 2px; border-left-width: 5px; diff --git a/docs/setup.md b/docs/setup.md index fe7921bb..9dd155cf 100644 --- a/docs/setup.md +++ b/docs/setup.md @@ -63,15 +63,15 @@ on how to add appservices. [Synapse documents the process here](https://matrix-o You will need to configure some listeners to make the bridge functional. ```yaml +listeners: # (Optional) HTTP Listener configuration. # Bind resource endpoints to ports and addresses. - # 'resources' may be any of webhooks, widgets, metrics, provisioning, appservice + # 'resources' may be any of webhooks, widgets, metrics, provisioning # - port: 9000 bindAddress: 0.0.0.0 resources: - webhooks - - widgets - port: 9001 bindAddress: 127.0.0.1 resources: @@ -80,12 +80,41 @@ You will need to configure some listeners to make the bridge functional. ``` At a minimum, you should bind the `webhooks` resource to a port and address. You can have multiple resources on the same -port, or one on each. +port, or one on each. Each listener MUST listen on a unique port. You will also need to make this port accessible to the internet so services like GitHub can reach the bridge. It is recommended to factor hookshot into your load balancer configuration, but currrently this process is left as an excercise to the user. +In terms of API endpoints: + +- The `webhooks` resource handles resources under `/`, so it should be on it's own listener. +- The `metrics` resource handles resources under `/metrics`. +- The `provisioning` resource handles resources under `/v1/...`. + +#### Appservice listener + +
+Please note that the appservice HTTP listener is configured seperately from the rest of the bridge due to lack of support +in the upstream library. See this issue for details. +
+ + +```yaml +bridge: + # Basic homeserver configuration + # + domain: example.com + url: http://localhost:8008 + mediaUrl: http://example.com + port: 9993 + bindAddress: 127.0.0.1 +``` + +The `port` and `bindAddress` must not conflict with the other listeners in the bridge config. This listeners should **not** be reachable +over the internet to users, as it's intended to be used by the homeserver exclusively. This service listens on `/_matrix/app/`. + + ### Services configuration You will need to configure some services. Each service has it's own documentation file inside the the setup subdirectory. diff --git a/docs/setup/webhooks.md b/docs/setup/webhooks.md index 55f743f6..88a5448a 100644 --- a/docs/setup/webhooks.md +++ b/docs/setup/webhooks.md @@ -1,10 +1,7 @@ # Webhooks -Hookshot supports generic webhook support so that services can send messages into Matrix rooms without being aware of the Matrix protocol. - -## Features - -The webhook connection supports sending messages into a single Matrix room, by hitting an API endpoint. +Hookshot supports generic webhook support so that services can send messages into Matrix rooms without being aware of the Matrix protocol. This works +by having services hit a unique URL that then transforms a HTTP payload into a Matrix message. ## Configuration @@ -17,11 +14,10 @@ generic: allowJsTransformationFunctions: false ``` -The bridge listens for incoming webhooks on the host and port provided in the `webhook` configuration section. For example, -a internal hook URL (using the default port) would look like `http://0.0.0.0:9000/abcdef`. +The bridge listens for incoming webhooks requests on the host and port provided in the [`listeners` config](../setup.md#listeners-configuration). `urlPrefix` describes the public facing URL of your webhook handler. For instance, if your load balancer redirected -webhook requests from `https://example.com/mywebhookspath` to the bridge, an example webhook URL would look like: +webhook requests from `https://example.com/mywebhookspath` to the bridge an example webhook URL would look like: `https://example.com/mywebhookspath/abcdef`. ## Adding a webhook @@ -32,17 +28,17 @@ To add a webhook to your room: - Say `!setup webhook` - The bot will respond with the webhook URL to be sent to services. -## Endpoint options +## Webhook Handling -The webhook endpoint can handle a `GET`,`POST` or `PUT` request. +Hookshot handles HTTP requests with a method of `GET`, `POST` or `PUT`. -If the request is a `GET` request, the query parameters are assumed to be the body. -otherwise, the body of the request should be a JSON payload. +If the request is a `GET` request, the query parameters are assumed to be the body. Otherwise, the body of the request should be a JSON payload. + +If the body contains a `text` key, then that key will be used as a message body in Matrix. This text will be automatically converted from Markdown to HTML. -If the body contains a `text` key, then that key will be used as a message body in Matrix. If the body *also* contains a `username` key, then the message will be prepended by the given username. -Otherwise, the full JSON payload will be sent to the room. This can be adapted into a message by creating a **JavaScript transformation function**. +If the body does NOT contain a `text` field, the full JSON payload will be sent to the room. This can be adapted into a message by creating a **JavaScript transformation function**. ## JavaScript Transformations diff --git a/src/Config/Config.ts b/src/Config/Config.ts index 571fcc33..b18fbf6b 100644 --- a/src/Config/Config.ts +++ b/src/Config/Config.ts @@ -190,6 +190,8 @@ export class BridgeConfig { @configKey(`HTTP Listener configuration. Bind resource endpoints to ports and addresses. + 'port' must be specified. Each listener must listen on a unique port. + 'bindAddress' will default to '127.0.0.1' if not specified, which may not be suited to Docker environments. 'resources' may be any of ${ResourceTypeArray.join(', ')}`, true) public readonly listeners: BridgeConfigListener[]; diff --git a/src/Config/Defaults.ts b/src/Config/Defaults.ts index 52577cf4..1b3c0c7c 100644 --- a/src/Config/Defaults.ts +++ b/src/Config/Defaults.ts @@ -82,7 +82,7 @@ export const DefaultConfig = new BridgeConfig({ { port: 9000, bindAddress: '0.0.0.0', - resources: ['webhooks', 'widgets'], + resources: ['webhooks'], }, { port: 9001, diff --git a/src/ListenerService.ts b/src/ListenerService.ts index 20f0b5d2..84c51df2 100644 --- a/src/ListenerService.ts +++ b/src/ListenerService.ts @@ -3,8 +3,9 @@ import { Application, default as expressApp, Router } from "express"; import LogWrapper from "./LogWrapper"; // Appserices can't be handled yet because the bot-sdk maintains control of it. -export type ResourceName = "webhooks"|"widgets"|"metrics"|"provisioning"|"appservice"; -export const ResourceTypeArray: ResourceName[] = ["webhooks","widgets","metrics","provisioning","appservice"]; +// See https://github.com/turt2live/matrix-bot-sdk/issues/191 +export type ResourceName = "webhooks"|"widgets"|"metrics"|"provisioning"; +export const ResourceTypeArray: ResourceName[] = ["webhooks","widgets","metrics","provisioning"]; export interface BridgeConfigListener { bindAddress?: string;