Allow manual configuration of connections from the config (#1102)

* Cleanup config a bit.

* Add support for defining static connections

* Allow generic hooks to be static.

* Add test for static configs

* Lots of config import cleanup

* Fixup hooks

* remove console statement

* Passing tests

* Add changelog

* Add default config

* Fix test

* Add documentation for static configs

* Validate configuration too

* Update 1102.feature

Signed-off-by: Will Hunt <[email protected]>

---------

Signed-off-by: Will Hunt <[email protected]>

Author: Half-Shot

changelog.d/1102.feature

@@ -0,0 +1 @@
+Static connections may now be configured in the config file.

config.sample.yml

@@ -108,7 +108,7 @@ listeners:
 #  # (Optional) Support for generic webhook events.
 #  #'allowJsTransformationFunctions' will allow users to write short transformation snippets in code, and thus is unsafe in untrusted environments
 
-#  enabled: false
+#  enabled: true
 #  outbound: false
 #  urlPrefix: https://example.com/webhook/
 #  userIdPrefix: _webhooks_
@@ -200,5 +200,13 @@ listeners:
 #  dsn: https://[email protected]/0
 #  environment: production
 
+#connections:
+#  # (Optional) Static connections that may be configured by an admin
+#  - connectionType: uk.half-shot.matrix-hookshot.generic.hook
+#    stateKey: any-unique-id
+#    roomId: "!any-room-id:example.org"
+#    state:
+#      name: My static hook
+
 
 

docs/SUMMARY.md

@@ -13,6 +13,7 @@
   - [OpenProject](./setup/openproject.md)
 - [👤 Usage](./usage.md)
   - [Dynamic Rooms](./usage/dynamic_rooms.md)
+  - [Static Connections](./usage/static_connections.md)
   - [Authenticating](./usage/auth.md)
   - [Room Configuration](./usage/room_configuration.md)
     - [GitHub Repo](./usage/room_configuration/github_repo.md)

docs/setup/webhooks.md

@@ -19,6 +19,8 @@ generic:
   # userIdPrefix: webhook_
 ```
 
+Inbound webhooks may also be specified [statically](../usage/static_connections.html#generic-hook-ukhalf-shotmatrix-hookshotgenerichook)
+
 ## Inbound Webhooks
 
 Hookshot supports generic webhook support so that services can send messages into Matrix rooms without being aware of the Matrix protocol. This works

docs/usage/static_connections.md

@@ -0,0 +1,35 @@
+# Static Connections
+
+Hookshot can also now be configured with "static connections". These allow system administrators to
+configure Hookshot with pre-specified set of connections which cannot be altered at runtime, but will
+have predictable configuration without any interactions with Matrix.
+
+Not all connection types are currently suitable for static configuration, the supported types are listed below.
+
+### Generic Hook `uk.half-shot.matrix-hookshot.generic.hook`
+
+Generic (inbound) webhooks can be configured, an example configuration is below:
+
+```yaml
+connections:
+ - connectionType: uk.half-shot.matrix-hookshot.generic.hook
+   stateKey: id-used-by-webhook
+   roomId: "!any-room-id:example.org"
+   state:
+     name: My static hook
+     waitForComplete: true
+     includeHookBody: true
+     expirationDate: 2025-11-03T16:44:59.533Z
+     # All below are optional
+     transformationFunction: |
+        result = {
+            plain: "*Everything is fine*",
+            version: "v2",
+        };
+}
+```
+
+You may then send requests to `http(s)://example.org/webhooks/id-used-by-webhook` to activate the webhook.
+
+See [the webhook documentation](../setup/webhooks) for more help on
+configuring hooks.

spec/static-connection-config.spec.ts

@@ -0,0 +1,93 @@
+import { E2ESetupTestTimeout, E2ETestEnv } from "./util/e2e-test";
+import {
+  describe,
+  test,
+  beforeAll,
+  afterAll,
+  afterEach,
+  expect,
+  vitest,
+} from "vitest";
+import {
+  GenericHookConnection,
+  GenericHookConnectionState,
+} from "../src/Connections";
+
+describe("Statically configured connection", () => {
+  let testEnv: E2ETestEnv;
+
+  beforeAll(async () => {
+    const webhooksPort = 9500 + E2ETestEnv.workerId;
+    testEnv = await E2ETestEnv.createTestEnv({
+      matrixLocalparts: ["user"],
+      staticConnectionRooms: {
+        "my-room": { members: ["user"] },
+      },
+      config: {
+        generic: {
+          enabled: true,
+          // Prefer to wait for complete as it reduces the concurrency of the test.
+          waitForComplete: true,
+          urlPrefix: `http://localhost:${webhooksPort}`,
+          payloadSizeLimit: "10mb",
+        },
+        connections: [
+          {
+            roomId: "my-room",
+            stateKey: "foo",
+            connectionType: GenericHookConnection.CanonicalEventType,
+            state: {
+              name: "My hook",
+            } satisfies GenericHookConnectionState,
+          },
+        ],
+        listeners: [
+          {
+            port: webhooksPort,
+            bindAddress: "0.0.0.0",
+            // Bind to the SAME listener to ensure we don't have conflicts.
+            resources: ["webhooks"],
+          },
+        ],
+      },
+    });
+    await testEnv.setUp();
+  }, E2ESetupTestTimeout);
+
+  afterAll(() => {
+    return testEnv?.tearDown();
+  });
+
+  afterEach(() => {
+    vitest.useRealTimers();
+  });
+
+  test("should be able to handle an incoming request.", async () => {
+    const user = testEnv.getUser("user");
+    const roomId = testEnv.connectionRooms["my-room"];
+    await user.joinRoom(roomId);
+    const url = new URL(
+      testEnv.opts.config?.generic?.urlPrefix! + "/webhook/foo",
+    );
+
+    const expectedMsg = user.waitForRoomEvent({
+      eventType: "m.room.message",
+      sender: testEnv.botMxid,
+      roomId,
+    });
+
+    const req = await fetch(url, {
+      method: "PUT",
+      body: "Hello world",
+    });
+    expect(req.status).toEqual(200);
+    expect(await req.json()).toEqual({ ok: true });
+    expect((await expectedMsg).data.content).toEqual({
+      msgtype: "m.notice",
+      body: "Received webhook data: Hello world",
+      formatted_body: "<p>Received webhook data: Hello world</p>",
+      format: "org.matrix.custom.html",
+      "uk.half-shot.hookshot.webhook_data": "Hello world",
+    });
+  });
+});

spec/util/e2e-test.ts

@@ -1,6 +1,5 @@
 import { TestHomeServer, createHS, destroyHS } from "./homerunner";
 import {
-  Appservice,
   IAppserviceRegistration,
   MatrixClient,
   Membership,
@@ -12,7 +11,6 @@ import { BridgeConfig, BridgeConfigRoot } from "../../src/config/Config";
 import { start } from "../../src/App/BridgeApp";
 import { RSAKeyPairOptions, generateKeyPair } from "node:crypto";
 import path from "node:path";
-import Redis from "ioredis";
 import {
   BridgeConfigActorPermission,
   BridgeConfigServicePermission,
@@ -21,11 +19,15 @@ import { TestContainers } from "testcontainers";
 
 const WAIT_EVENT_TIMEOUT = 20000;
 export const E2ESetupTestTimeout = 60000;
-const REDIS_DATABASE_URI =
-  process.env.HOOKSHOT_E2E_REDIS_DB_URI ?? "redis://localhost:6379";
 
 interface Opts<ML extends string> {
   matrixLocalparts?: ML[];
+  staticConnectionRooms?: Record<
+    string,
+    {
+      members: string[];
+    }
+  >;
   permissionsRoom?: {
     members: string[];
     permissions: Array<BridgeConfigServicePermission>;
@@ -378,6 +380,7 @@ export class E2ETestEnv<ML extends string = string> {
 
     const registration: IAppserviceRegistration = {
       id: "hookshot",
+      url: null,
       as_token: homeserver.asToken,
       hs_token: homeserver.hsToken,
       sender_localpart: "hookshot",
@@ -394,9 +397,22 @@ export class E2ETestEnv<ML extends string = string> {
       "de.sorunome.msc2409.push_ephemeral": true,
     };
 
+    const connectionRooms: Record<string, string> = {};
+
+    const botClient = new MatrixClient(homeserver.url, homeserver.asToken);
+    for (const [roomIdMapper, roomOpts] of Object.entries(
+      opts.staticConnectionRooms ?? {},
+    )) {
+      connectionRooms[roomIdMapper] = await botClient.createRoom({
+        name: `${roomIdMapper}`,
+        invite: roomOpts.members.map(
+          (localpart) => `@${localpart}:${homeserver.domain}`,
+        ),
+      });
+    }
+
     let permissions: BridgeConfigActorPermission[] = [];
     if (opts.permissionsRoom) {
-      const botClient = new MatrixClient(homeserver.url, homeserver.asToken);
       const permsRoom = await botClient.createRoom({
         name: "Permissions room",
         invite: opts.permissionsRoom.members.map(
@@ -448,11 +464,15 @@ export class E2ETestEnv<ML extends string = string> {
       cache: cacheConfig,
       permissions,
       ...providedConfig,
+      connections: opts.config?.connections?.map((c) => ({
+        ...c,
+        roomId: connectionRooms[c.roomId],
+      })),
     });
     const app = await start(config, registration);
     app.listener.finaliseListeners();
 
-    return new E2ETestEnv(homeserver, app, opts, config, dir);
+    return new E2ETestEnv(homeserver, app, opts, config, dir, connectionRooms);
   }
 
   private constructor(
@@ -461,6 +481,7 @@ export class E2ETestEnv<ML extends string = string> {
     public readonly opts: Opts<ML>,
     private readonly config: BridgeConfig,
     private readonly dir: string,
+    public readonly connectionRooms: Record<string, string>,
   ) {
     const appService = app.appservice;
 

src/Bridge.ts

@@ -16,11 +16,7 @@ import {
   PLManager,
 } from "matrix-bot-sdk";
 import BotUsersManager from "./managers/BotUsersManager";
-import {
-  BridgeConfig,
-  BridgePermissionLevel,
-  GitLabInstance,
-} from "./config/Config";
+import { BridgeConfig, BridgePermissionLevel } from "./config/Config";
 import { BridgeWidgetApi } from "./widgets/BridgeWidgetApi";
 import { CommentProcessor } from "./CommentProcessor";
 import { ConnectionManager } from "./ConnectionManager";
@@ -111,6 +107,7 @@ import { OpenProjectWebhookPayloadWorkPackage } from "./openproject/Types";
 import { OpenProjectConnection } from "./Connections/OpenProjectConnection";
 import { OAuthRequest, OAuthRequestResult } from "./tokens/Oauth";
 import { IJsonType } from "matrix-bot-sdk/lib/helpers/Types";
+import { GitLabInstance } from "./config/sections";
 
 const log = new Logger("Bridge");