matrix-doc/proposals/4233-remembering-knock-via.md

MSC4233: Remembering which server a user knocked through

Knocking allows users to request an invite into a semi-public room from members already in that room. The use cases for this feature vary, though it is relatively common that the room isn't already known to the user's homeserver. For this reason, the API endpoint for knocking accepts via parameters to assist the homeserver in locating another server to knock through.

Later, when the client wishes to show the user's pending knocks, it may wish to show the user more information, or possibly even detect that the room became public and offer a direct join button. It may do this through an API like the summary endpoint proposed in MSC3266. When trying to call such endpoints, the client may only have a room ID, which is unroutable, leading to errors if the room is unknown to the server.

This proposal requires the server to remember what server(s) were used by a user to knock on a room, making it available to clients to use in subsequent API calls. This proposal doesn't address invites or other membership states because the client can parse the user ID which sent the membership change.

Proposal

Within the GET /_matrix/client/v3/sync response is a knock section to denote which rooms the user has knocked on. This currently contains a single property, knock_state, which is the stripped state for the room. This stripped state can be used for simple rendering of the room, but may be outdated and require a refresh from the server using an API like the one proposed in MSC3266.

A new property next to knock_state is added, denoting the servers specified by the client at the time of the most recent knock. This property is called knock_servers.

Example /sync response (irrelevant details not shown):

{
  "rooms": {
    "knock": {
      "!opaque:example.org": {
        "knock_state": {
          "events": [
            {"type": "m.room.name", "state_key": "", "content": {"name": "My Room"}}
          ]
        },
        "knock_servers": [ // new property
          "a.example.org",
          "b.example.org",
          "c.example.org"
        ]
      }
    }
  }
}

Servers SHOULD put the server name used to complete the federation knock dance first in the array. This is to help speed up API calls on servers which sequentially check via parameters rather than process them in parallel. There's also a small amount of debugging benefit, when troubleshooting knocks.

Servers MUST track the server names specified in via parameters on POST /_matrix/client/v3/knock/{roomIdOrAlias} when called with a room ID. Tracking server names specified as server_names is optional due to the parameter being slated for removal. Servers MUST expose this information through knock_servers, as described above. Only the most recent knock is required to be tracked, though prior knocks may be stored at the server's discretion.

Servers SHOULD impose a maximum limit of not less than 3 server names to track from a client's call. This is to avoid a database disk fill if a malicious client decides to try knocking through a few thousand servers, for example.

Clients MUST be tolerable to knock_servers being empty or missing as the knock may have happened before the server tracked this information. Servers SHOULD use an empty array rather than lack of field to denote this case, indicating that it is tracking server names for future knocks.

Simplified sliding sync considerations

Simplified sliding sync is currently described as MSC4186 and is set to overhaul the sync model for clients. This proposal doesn't change MSC4186, but does suggest that the knock_servers field be similarly kept next to knock_state on a room subscription.

Potential issues

Servers may not have already tracked this, so information will be lacking for already-knocked rooms. Clients should expect errors, per usual, when attempting to call the summary API or any other endpoint.

Alternatives

A client could track this information on its own, however this is not shared to other clients under the user's account. This effectively leaves other clients operated by the user broken.

Security considerations

As mentioned in the above proposal text, servers are encouraged to apply two limits:

1. Only record the most recent knock attempt.
2. Limit to 3 or more server names from that knock attempt.

Both of these limitations are to prevent unbounded data being stored on the server, leading to disk fill or similar availability concerns.

Safety considerations

No significant safety considerations identified.

Unstable prefix

While this proposal is not considered stable, implementations should use org.matrix.msc4233.knock_servers in place of knock_servers.

Simplified sliding sync may wish to include knock_servers's behaviour independent to this MSC, avoiding a complex MSC dependency tree.

Dependencies

This proposal does not have formal dependencies, though clients bitten by the described bug are most likely using MSC3266.