# Copyright 2021 The Matrix.org Foundation C.I.C.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

swagger: '2.0'
info:
  title: "Matrix Federation Knock Room API"
  version: "1.0.0"
host: localhost:8448
schemes:
  - https
basePath: /_matrix/federation/v1
consumes:
  - application/json
produces:
  - application/json
securityDefinitions:
  $ref: definitions/security.yaml
paths:
  "/make_knock/{roomId}/{userId}":
    get:
      summary: Get information required to make a knock event for a room.
      description: |-
        Asks the receiving server to return information that the sending
        server will need to prepare a knock event for the room.
      operationId: makeKnock
      security:
        - signedRequest: []
      parameters:
        - in: path
          name: roomId
          type: string
          description: The room ID that is about to be knocked.
          required: true
          x-example: "!abc123:example.org"
        - in: path
          name: userId
          type: string
          description: The user ID the knock event will be for.
          required: true
          x-example: "@someone:example.org"
        - in: query
          type: array
          items:
            type: string
          name: ver
          description: |-
            The room versions the sending server has support for.
          required: true  # knocking was supported in v7
          x-example: ["1", "7"]
      responses:
        200:
          description: |-
            A template to be used for the rest of the [Knocking Rooms](/server-server-api/#knocking-rooms)
            handshake. Note that events have a different format depending on room version - check the
            [room version specification](/#room-versions) for precise event formats. **The response body
            here describes the common event fields in more detail and may be missing other
            required fields for a PDU.**
          schema:
            type: object
            properties:
              room_version:
                type: string
                description: |-
                  The version of the room where the server is trying to knock.
                example: "7"
              event:
                description: |-
                  An unsigned template event. Note that events have a different format
                  depending on the room version - check the [room version specification](/#room-versions)
                  for precise event formats.
                type: object
                title: Event Template
                properties:
                  sender:
                    type: string
                    description: The user ID of the knocking member.
                    example: "@someone:example.org"
                  origin:
                    type: string
                    description: The name of the resident homeserver.
                    example: "matrix.org"
                  origin_server_ts:
                    type: integer
                    format: int64
                    description: A timestamp added by the resident homeserver.
                    example: 1234567890
                  type:
                    type: string
                    description: The value `m.room.member`.
                    example: "m.room.member"
                  state_key:
                    type: string
                    description: The user ID of the knocking member.
                    example: "@someone:example.org"
                  content:
                    type: object
                    title: Membership Event Content
                    description: The content of the event.
                    example: {"membership": "knock"}
                    properties:
                      membership:
                        type: string
                        description: The value `knock`.
                        example: "knock"
                    required: ['membership']
                required:
                  - state_key
                  - origin
                  - origin_server_ts
                  - type
                  - content
                  - sender
            required:
              - room_version  # knocking was added in v7
              - event
          examples:
            application/json: {
              "room_version": "7",
              "event": {
                "$ref": "examples/minimal_pdu.json",
                "type": "m.room.member",
                "state_key": "@someone:example.org",
                "origin": "example.org",
                "origin_server_ts": 1549041175876,
                "sender": "@someone:example.org",
                "content": {
                  "membership": "knock"
                }
              }
            }
        400:
          description: |-
            The request is invalid or the room the server is attempting
            to knock upon has a version that is not listed in the `ver`
            parameters.

            The error should be passed through to clients so that they
            may give better feedback to users.
          schema:
            allOf:
              - $ref: "../client-server/definitions/errors/error.yaml"
              - type: object
                properties:
                  room_version:
                    type: string
                    description: |-
                      The version of the room. Required if the `errcode`
                      is `M_INCOMPATIBLE_ROOM_VERSION`.
          examples:
            application/json: {
              "errcode": "M_INCOMPATIBLE_ROOM_VERSION",
              "error": "Your homeserver does not support the features required to knock on this room",
              "room_version": "7"
            }
        404:
          description: |-
            The room that the knocking server is attempting to knock upon is unknown
            to the receiving server.
          schema:
            allOf:
              - $ref: "../client-server/definitions/errors/error.yaml"
          examples:
            application/json: {
              "errcode": "M_NOT_FOUND",
              "error": "Unknown room",
            }
        403:
          description: |-
            The knocking server or user is not permitted to knock on the room, such as when the
            server/user is banned or the room is not set up for receiving knocks.
          schema:
            allOf:
              - $ref: "../client-server/definitions/errors/error.yaml"
          examples:
            application/json: {
              "errcode": "M_FORBIDDEN",
              "error": "You are not permitted to knock on this room",
            }

  "/send_knock/{roomId}/{eventId}":
    put:
      summary: Submit a signed knock event to a resident server.
      description: |-
        Submits a signed knock event to the resident server for it to
        accept into the room's graph. Note that events have
        a different format depending on the room version - check
        the [room version specification](/#room-versions) for precise event formats.
        **The request and response body here describe the common
        event fields in more detail and may be missing other required
        fields for a PDU.**
      operationId: sendKnock
      security:
        - signedRequest: []
      parameters:
        - in: path
          name: roomId
          type: string
          description: The room ID that is about to be knocked upon.
          required: true
          x-example: "!abc123:example.org"
        - in: path
          name: eventId
          type: string
          description: The event ID for the knock event.
          required: true
          x-example: "$abc123:example.org"
        - in: body
          name: body
          type: object
          required: true
          schema:
            type: object
            properties:
              sender:
                type: string
                description: The user ID of the knocking member.
                example: "@someone:example.org"
              origin:
                type: string
                description: The name of the knocking homeserver.
                example: "matrix.org"
              origin_server_ts:
                type: integer
                format: int64
                description: A timestamp added by the knocking homeserver.
                example: 1234567890
              type:
                type: string
                description: The value `m.room.member`.
                example: "m.room.member"
              state_key:
                type: string
                description: The user ID of the knocking member.
                example: "@someone:example.org"
              content:
                type: object
                title: Membership Event Content
                description: The content of the event.
                example: {"membership": "knock"}
                properties:
                  membership:
                    type: string
                    description: The value `knock`.
                    example: "knock"
                required: ['membership']
            required:
              - state_key
              - sender
              - origin
              - origin_server_ts
              - type
              - content
          example: {
            "$ref": "examples/minimal_pdu.json",
            "type": "m.room.member",
            "state_key": "@someone:example.org",
            "origin": "example.org",
            "origin_server_ts": 1549041175876,
            "sender": "@someone:example.org",
            "content": {
                "membership": "knock"
            }
          }
      responses:
        200:
          description: |-
            Information about the room to pass along to clients regarding the
            knock.
          schema:
            type: object
            properties:
              knock_room_state:
                type: array
                items:
                  $ref: "../../event-schemas/schema/stripped_state.yaml"
                description: |-
                  A list of simplified events to help the initiator of the knock identify
                  the room. The recommended events to include are the join rules, canonical
                  alias, avatar, name, and encryption state of the room.
                example:
                  $ref: "../../event-schemas/examples/knock_room_state.json"
            required: ['knock_room_state']
          examples:
            application/json: {
              "knock_room_state": {"$ref": "../../event-schemas/examples/knock_room_state.json"}
            }
        404:
          description: |-
            The room that the knocking server is attempting to knock upon is unknown
            to the receiving server.
          schema:
            allOf:
              - $ref: "../client-server/definitions/errors/error.yaml"
          examples:
            application/json: {
              "errcode": "M_NOT_FOUND",
              "error": "Unknown room",
            }
        403:
          description: |-
            The knocking server or user is not permitted to knock on the room, such as when the
            server/user is banned or the room is not set up for receiving knocks.
          schema:
            allOf:
              - $ref: "../client-server/definitions/errors/error.yaml"
          examples:
            application/json: {
              "errcode": "M_FORBIDDEN",
              "error": "You are not permitted to knock on this room",
            }