client: add wrapper for /knock endpoint (#359)

client.go

@@ -974,6 +974,28 @@ func (cli *Client) JoinRoom(ctx context.Context, roomIDorAlias string, req *ReqJ
 	return
 }
 
+// KnockRoom requests to join a room ID or alias. See https://spec.matrix.org/v1.13/client-server-api/#post_matrixclientv3knockroomidoralias
+//
+// The last parameter contains optional extra fields and can be left nil.
+func (cli *Client) KnockRoom(ctx context.Context, roomIDorAlias string, req *ReqKnockRoom) (resp *RespKnockRoom, err error) {
+	if req == nil {
+		req = &ReqKnockRoom{}
+	}
+	urlPath := cli.BuildURLWithFullQuery(ClientURLPath{"v3", "knock", roomIDorAlias}, func(q url.Values) {
+		if len(req.Via) > 0 {
+			q["via"] = req.Via
+		}
+	})
+	_, err = cli.MakeRequest(ctx, http.MethodPost, urlPath, req, &resp)
+	if err == nil && cli.StateStore != nil {
+		err = cli.StateStore.SetMembership(ctx, resp.RoomID, cli.UserID, event.MembershipKnock)
+		if err != nil {
+			err = fmt.Errorf("failed to update state store: %w", err)
+		}
+	}
+	return
+}
+
 // JoinRoomByID joins the client to a room ID. See https://spec.matrix.org/v1.2/client-server-api/#post_matrixclientv3roomsroomidjoin
 //
 // Unlike JoinRoom, this method can only be used to join rooms that the server already knows about.

requests.go

@@ -156,6 +156,11 @@ type ReqJoinRoom struct {
 	ThirdPartySigned any      `json:"third_party_signed,omitempty"`
 }
 
+type ReqKnockRoom struct {
+	Via    []string `json:"-"`
+	Reason string   `json:"reason,omitempty"`
+}
+
 type ReqMutualRooms struct {
 	From string `json:"-"`
 }

responses.go

@@ -33,6 +33,11 @@ type RespJoinRoom struct {
 	RoomID id.RoomID `json:"room_id"`
 }
 
+// RespKnockRoom is the JSON response for https://spec.matrix.org/v1.13/client-server-api/#post_matrixclientv3knockroomidoralias
+type RespKnockRoom struct {
+	RoomID id.RoomID `json:"room_id"`
+}
+
 // RespLeaveRoom is the JSON response for https://spec.matrix.org/v1.2/client-server-api/#post_matrixclientv3roomsroomidleave
 type RespLeaveRoom struct{}