Skip to content

Commit

Permalink
Merge pull request #1794 from matrix-org/erikj/fed_invite_v2
Browse files Browse the repository at this point in the history
MSC 1794 - Federation v2 Invite API
  • Loading branch information
turt2live authored Jan 21, 2019
2 parents ecca4a0 + ebf3717 commit f308871
Showing 1 changed file with 78 additions and 0 deletions.
78 changes: 78 additions & 0 deletions proposals/1794-federation-v2-invites.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,78 @@
# MSC 1794 - Federation v2 Invite API

This proposal adds a new `/invite` API to federation that supports different
room versions.

## Motivation

It is planned for future room versions to be able to change the format of events
in various ways. To support this, all servers must know the room version
whenever they need to parse an event. Currently the `/invite` API does not
include the room version, so the target server would be unable to parse the event included in the payload.

## Proposal

Add a new version of the invite API under the prefix `/_matrix/federation/v2`,
which has a payload of:

```
PUT /_matrix/federation/v2/invite/<room_id>/<event_id>
{
"room_version": <room_version>,
"event": { ... },
"invite_room_state": [ ... ]
}
```

The differences between this and `v1` are:

1. The payload in `v1` is the event, while in `v2` the event is instead placed
under an `"event"` key. This is for consistency with other APIs, and to allow
extra data to be added to the request payload separately from the event.
2. A required field called `"room_version"` is added that specifies the room
version.
3. The `"invite_room_state"` is moved from the `unsigned` section of the event
to a top level key. The key `invite_room_state` being in the `event.unsigned`
was a hack due to point 1. above.


The response is identical to `v1`, except that:

1. If the receiving server does not support the given room version the
appropriate incompatible-room-version error is returned, in the same way
as e.g. for `/make_join` APIs.
2. The response payload is no longer in the format of `[200, { ... }]`, and is
instead simply the `{ ... }` portion. This fixes a historical accident to
bring the invite API into line with the rest of the federation API.


If a call to `v2` `/invite` results in an unrecognised request exception **AND**
the room version is `1` or `2` then the sending server should retry the request
with the `v1` API.


## Alternatives


### Reusing V1 API

One alternative is to add a `room_version` query string parameter to the `v1`
`/invite` API in a similar way as for the `/make_join` APIs. However, older
servers would ignore the query string parameter while processing an incoming
`/invite` request, resulting in the server attempting to parse the event in the
old `v1` format. This would likely result in either a `400` or `500` response,
which the sending server could interpret as the receiving server not supporting
the room version.

This method, however, is fragile and could easily mask legitimate `400` and
`500` errors that are not due to not supporting the room version.


### Using V1 API for V1 room versions

Instead of all servers attempting to use the new API and falling back if the API
is not found, servers could instead always use the current API for V1 and V2
rooms.

However, this would not allow us to deprecate the `v1` API.

0 comments on commit f308871

Please sign in to comment.