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

@@ -0,0 +1 @@
+Improve docs around listener and generic webhook configuration

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:

docs/_site/style.css

@@ -1,4 +1,5 @@
 .notice {
+    color: black;
     border: 2px solid #0098d4;
     border-left-width: 2px;
     border-left-width: 5px;

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
+
+<section class="notice">
+Please note that the appservice HTTP listener is configured <strong>seperately</strong> from the rest of the bridge due to lack of support
+in the upstream library. See <a href="https://github.com/turt2live/matrix-bot-sdk/issues/191">this issue</a> for details.
+</section>
+
+
+```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.

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
 

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[];
 

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,

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;