Allow knocking rooms

spec/integ/matrix-client-methods.spec.ts

@@ -19,7 +19,7 @@ import { Mocked } from "jest-mock";
 import * as utils from "../test-utils/test-utils";
 import { CRYPTO_ENABLED, IStoredClientOpts, MatrixClient } from "../../src/client";
 import { MatrixEvent } from "../../src/models/event";
-import { Filter, MemoryStore, Method, Room, SERVICE_TYPES } from "../../src/matrix";
+import { Filter, KnockRoomOpts, MemoryStore, Method, Room, SERVICE_TYPES } from "../../src/matrix";
 import { TestClient } from "../TestClient";
 import { THREAD_RELATION_TYPE } from "../../src/models/thread";
 import { IFilterDefinition } from "../../src/filter";
@@ -205,6 +205,84 @@ describe("MatrixClient", function () {
         });
     });
 
+    describe("knockRoom", function () {
+        const roomId = "!some-room-id:example.org";
+        const reason = "some reason";
+        const viaServers = "example.com";
+
+        type TestCase = [string, KnockRoomOpts];
+        const testCases: TestCase[] = [
+            ["should knock a room", {}],
+            ["should knock a room for a reason", { reason }],
+            ["should knock a room via given servers", { viaServers }],
+            ["should knock a room for a reason via given servers", { reason, viaServers }],
+        ];
+
+        it.each(testCases)("%s", async (_, opts) => {
+            httpBackend
+                .when("POST", "/knock/" + encodeURIComponent(roomId))
+                .check((request) => {
+                    expect(request.data).toEqual({ reason: opts.reason });
+                    expect(request.queryParams).toEqual({ server_name: opts.viaServers });
+                })
+                .respond(200, { room_id: roomId });
+
+            const prom = client.knockRoom(roomId, opts);
+            await httpBackend.flushAllExpected();
+            expect((await prom).room_id).toBe(roomId);
+        });
+
+        it("should no-op if you've already knocked a room", function () {
+            const room = new Room(roomId, client, userId);
+
+            client.fetchRoomEvent = () =>
+                Promise.resolve({
+                    type: "test",
+                    content: {},
+                });
+
+            room.addLiveEvents([
+                utils.mkMembership({
+                    user: userId,
+                    room: roomId,
+                    mship: "knock",
+                    event: true,
+                }),
+            ]);
+
+            httpBackend.verifyNoOutstandingRequests();
+            store.storeRoom(room);
+            client.knockRoom(roomId);
+            httpBackend.verifyNoOutstandingRequests();
+        });
+
+        describe("errors", function () {
+            type TestCase = [number, { errcode: string; error?: string }, string];
+            const testCases: TestCase[] = [
+                [
+                    403,
+                    { errcode: "M_FORBIDDEN", error: "You don't have permission to knock" },
+                    "[M_FORBIDDEN: MatrixError: [403] You don't have permission to knock]",
+                ],
+                [
+                    500,
+                    { errcode: "INTERNAL_SERVER_ERROR" },
+                    "[INTERNAL_SERVER_ERROR: MatrixError: [500] Unknown message]",
+                ],
+            ];
+
+            it.each(testCases)("should handle %s error", async (code, { errcode, error }, snapshot) => {
+                httpBackend.when("POST", "/knock/" + encodeURIComponent(roomId)).respond(code, { errcode, error });
+
+                const prom = client.knockRoom(roomId);
+                await Promise.all([
+                    httpBackend.flushAllExpected(),
+                    expect(prom).rejects.toMatchInlineSnapshot(snapshot),
+                ]);
+            });
+        });
+    });
+
     describe("getFilter", function () {
         const filterId = "f1lt3r1d";
 

src/@types/requests.ts

@@ -45,6 +45,18 @@ export interface IJoinRoomOpts {
     viaServers?: string[];
 }
 
+export interface KnockRoomOpts {
+    /**
+     * The reason for the knock.
+     */
+    reason?: string;
+
+    /**
+     * The server names to try and knock through in addition to those that are automatically chosen.
+     */
+    viaServers?: string | string[];
+}
+
 export interface IRedactOpts {
     reason?: string;
     /**

src/client.ts

@@ -134,6 +134,7 @@ import {
     ITagsResponse,
     IStatusResponse,
     IAddThreePidBody,
+    KnockRoomOpts,
 } from "./@types/requests";
 import {
     EventType,
@@ -4158,6 +4159,34 @@ export class MatrixClient extends TypedEventEmitter<EmittedEvents, ClientEventHa
         return syncRoom;
     }
 
+    /**
+     * Knock a room. If you have already knocked the room, this will no-op.
+     * @param roomIdOrAlias - The room ID or room alias to knock.
+     * @param opts - Options when knocking the room.
+     * @returns Promise which resolves: `{room_id: {string}}`
+     * @returns Rejects: with an error response.
+     */
+    public knockRoom(roomIdOrAlias: string, opts: KnockRoomOpts = {}): Promise<{ room_id: string }> {
+        const room = this.getRoom(roomIdOrAlias);
+        if (room?.hasMembershipState(this.credentials.userId!, "knock")) {
+            return Promise.resolve({ room_id: room.roomId });
+        }
+
+        const path = utils.encodeUri("/knock/$roomIdOrAlias", { $roomIdOrAlias: roomIdOrAlias });
+
+        const queryParams: Record<string, string | string[]> = {};
+        if (opts.viaServers) {
+            queryParams.server_name = opts.viaServers;
+        }
+
+        const body: Record<string, string> = {};
+        if (opts.reason) {
+            body.reason = opts.reason;
+        }
+
+        return this.http.authedRequest(Method.Post, path, queryParams, body);
+    }
+
     /**
      * Resend an event. Will also retry any to-device messages waiting to be sent.
      * @param event - The event to resend.