From b0adfc67d8e07ec031762601dac4c84be36ac01b Mon Sep 17 00:00:00 2001 From: Erik Johnston Date: Thu, 10 Jan 2019 12:17:48 +0000 Subject: [PATCH 1/5] MSC 1794 - Federation v2 Invite API --- proposals/1794-federation-v2-invites.md | 79 +++++++++++++++++++++++++ 1 file changed, 79 insertions(+) create mode 100644 proposals/1794-federation-v2-invites.md diff --git a/proposals/1794-federation-v2-invites.md b/proposals/1794-federation-v2-invites.md new file mode 100644 index 00000000..3879683b --- /dev/null +++ b/proposals/1794-federation-v2-invites.md @@ -0,0 +1,79 @@ +# 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, and so 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, and so the event included in the payload would not be +able to be parsed. + +## 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_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 exception 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 a 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. From 2109314c524fbc63952f96452e4989cd2786a863 Mon Sep 17 00:00:00 2001 From: Erik Johnston Date: Fri, 11 Jan 2019 14:34:31 +0000 Subject: [PATCH 2/5] Apply suggestions from code review Co-Authored-By: erikjohnston --- proposals/1794-federation-v2-invites.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/proposals/1794-federation-v2-invites.md b/proposals/1794-federation-v2-invites.md index 3879683b..8402c447 100644 --- a/proposals/1794-federation-v2-invites.md +++ b/proposals/1794-federation-v2-invites.md @@ -6,9 +6,9 @@ room versions. ## Motivation It is planned for future room versions to be able to change the format of events -in various ways, and so to support this all servers must know the room version +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, and so the event included in the payload would not be +include the room version, so the target server would be unable to parse the event included in the payload. able to be parsed. ## Proposal @@ -41,7 +41,7 @@ The differences between this and `v1` are: 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 exception is returned, in the same way + 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 From c88c9c29413c2da12b2d0b9fc9a1b698ddd7cdba Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Mon, 14 Jan 2019 14:19:58 +0000 Subject: [PATCH 3/5] Update proposals/1794-federation-v2-invites.md Co-Authored-By: erikjohnston --- proposals/1794-federation-v2-invites.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/1794-federation-v2-invites.md b/proposals/1794-federation-v2-invites.md index 8402c447..de5c70f6 100644 --- a/proposals/1794-federation-v2-invites.md +++ b/proposals/1794-federation-v2-invites.md @@ -48,7 +48,7 @@ The response is identical to `v1`, except that: bring the invite API into line with the rest of the federation API. -If a call to `v2` `/invite` results in a unrecognised request exception **AND** +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. From b90ee6baaba293681e24ce503465626363d87c30 Mon Sep 17 00:00:00 2001 From: Erik Johnston Date: Mon, 14 Jan 2019 14:20:57 +0000 Subject: [PATCH 4/5] 'invite_room_state' should be an array --- proposals/1794-federation-v2-invites.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/1794-federation-v2-invites.md b/proposals/1794-federation-v2-invites.md index de5c70f6..65e63825 100644 --- a/proposals/1794-federation-v2-invites.md +++ b/proposals/1794-federation-v2-invites.md @@ -22,7 +22,7 @@ PUT /_matrix/federation/v2/invite// { "room_version": , "event": { ... }, - "invite_room_state": { ... } + "invite_room_state": [ ... ] } ``` From ebf37178b5acb9f3ba376fa429fb56263a87e4a3 Mon Sep 17 00:00:00 2001 From: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> Date: Mon, 14 Jan 2019 15:53:23 +0000 Subject: [PATCH 5/5] Update proposals/1794-federation-v2-invites.md Co-Authored-By: erikjohnston --- proposals/1794-federation-v2-invites.md | 1 - 1 file changed, 1 deletion(-) diff --git a/proposals/1794-federation-v2-invites.md b/proposals/1794-federation-v2-invites.md index 65e63825..a2f2bb35 100644 --- a/proposals/1794-federation-v2-invites.md +++ b/proposals/1794-federation-v2-invites.md @@ -9,7 +9,6 @@ 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. -able to be parsed. ## Proposal