From d4c58a935ca4da56f28772e68a8ba329ce89f7c1 Mon Sep 17 00:00:00 2001 From: Johannes Marbach Date: Mon, 17 Jun 2024 13:20:15 +0200 Subject: [PATCH 1/7] MSC4156: Migrate server_name to via Signed-off-by: Johannes Marbach --- proposals/4156-server-name-to-via.md | 57 ++++++++++++++++++++++++++++ 1 file changed, 57 insertions(+) create mode 100644 proposals/4156-server-name-to-via.md diff --git a/proposals/4156-server-name-to-via.md b/proposals/4156-server-name-to-via.md new file mode 100644 index 00000000000..b5d9c7d83c4 --- /dev/null +++ b/proposals/4156-server-name-to-via.md @@ -0,0 +1,57 @@ +# MSC4156: Migrate `server_name` to `via` + +Room IDs in Matrix are generally not routable on their own. In the [room ID grammar] `!opaque_id:domain`, +the `domain` is the server that created the room. There is, however, no guarantee that this server is +still joined to the room at a later time. Therefore, room IDs don't provide a reliable resident server +to send requests to. + +The spec partially addresses this issue by defining a [`via`] query parameter on room URIs that can be +used to list servers that have a high probability of being in the room in the distant future. Additionally, +some APIs such as [`/_matrix/client/v3/join/{roomIdOrAlias}`] can take a `server_name` query parameter +that has the same effect as `via`. + +The terminology difference between `server_name` and `via` can be slightly confusing which is why this +proposal attempts to standardize on `via`. + + +## Proposal + +The `server_name` query parameter on [`/_matrix/client/v3/join/{roomIdOrAlias}`] and +[`/_matrix/client/v3/knock/{roomIdOrAlias}`] is deprecated and a new parameter `via: [string]` is +introduced. Clients MUST use `via` when the homeserver they're talking to supports it. To do this, they +MAY either detect server support through [`/_matrix/client/versions`] or always include both parameters. +Homeservers MUST prefer `via` if both parameters are supplied. + + +## Potential issues + +As with any migration, some effort will be required to update client and server implementations. Additionally, +while the transitions isn't completed, the concurrent existence of both query parameters might lead to further +confusion. + + +## Alternatives + +None other than accepting status quo. + + +## Security considerations + +None. + + +## Unstable prefix + +Until this proposal is accepted into the spec, implementations SHOULD refer to `via` as `org.matrix.msc4156.via`. + + +## Dependencies + +None. + + +[room ID grammar]: https://spec.matrix.org/v1.10/appendices/#room-ids +[`via`]: https://spec.matrix.org/v1.10/appendices/#routing +[`/_matrix/client/v3/join/{roomIdOrAlias}`]: https://spec.matrix.org/v1.10/client-server-api/#post_matrixclientv3joinroomidoralias +[`/_matrix/client/v3/knock/{roomIdOrAlias}`]: https://spec.matrix.org/v1.10/client-server-api/#post_matrixclientv3knockroomidoralias +[`/_matrix/client/versions`]: https://spec.matrix.org/v1.10/client-server-api/#get_matrixclientversions From 5a97bc2248dd5ba36c07470f9f032cc43be1619c Mon Sep 17 00:00:00 2001 From: Johannes Marbach Date: Mon, 17 Jun 2024 22:10:34 +0200 Subject: [PATCH 2/7] Ignore server_name when via is present --- proposals/4156-server-name-to-via.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/4156-server-name-to-via.md b/proposals/4156-server-name-to-via.md index b5d9c7d83c4..3c1733bf06a 100644 --- a/proposals/4156-server-name-to-via.md +++ b/proposals/4156-server-name-to-via.md @@ -20,7 +20,7 @@ The `server_name` query parameter on [`/_matrix/client/v3/join/{roomIdOrAlias}`] [`/_matrix/client/v3/knock/{roomIdOrAlias}`] is deprecated and a new parameter `via: [string]` is introduced. Clients MUST use `via` when the homeserver they're talking to supports it. To do this, they MAY either detect server support through [`/_matrix/client/versions`] or always include both parameters. -Homeservers MUST prefer `via` if both parameters are supplied. +Homeservers MUST ignore `server_name` if both parameters are supplied. ## Potential issues From fe3e01e5a35c1f529bf59fe7e0f241816d715f13 Mon Sep 17 00:00:00 2001 From: Johannes Marbach Date: Fri, 9 Aug 2024 08:08:39 +0200 Subject: [PATCH 3/7] Update proposals/4156-server-name-to-via.md Co-authored-by: Travis Ralston --- proposals/4156-server-name-to-via.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/4156-server-name-to-via.md b/proposals/4156-server-name-to-via.md index 3c1733bf06a..d5966b28c5f 100644 --- a/proposals/4156-server-name-to-via.md +++ b/proposals/4156-server-name-to-via.md @@ -20,7 +20,7 @@ The `server_name` query parameter on [`/_matrix/client/v3/join/{roomIdOrAlias}`] [`/_matrix/client/v3/knock/{roomIdOrAlias}`] is deprecated and a new parameter `via: [string]` is introduced. Clients MUST use `via` when the homeserver they're talking to supports it. To do this, they MAY either detect server support through [`/_matrix/client/versions`] or always include both parameters. -Homeservers MUST ignore `server_name` if both parameters are supplied. +Homeservers MUST ignore all `server_name` parameters if any `via` parameters are supplied. ## Potential issues From ae3677cfdf384f1761e6b79296dc56041ac4c0d4 Mon Sep 17 00:00:00 2001 From: Johannes Marbach Date: Fri, 9 Aug 2024 08:12:58 +0200 Subject: [PATCH 4/7] Stress that the domain part is merely a namespace and not a routing server --- proposals/4156-server-name-to-via.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/4156-server-name-to-via.md b/proposals/4156-server-name-to-via.md index d5966b28c5f..01bbd401f2c 100644 --- a/proposals/4156-server-name-to-via.md +++ b/proposals/4156-server-name-to-via.md @@ -3,7 +3,7 @@ Room IDs in Matrix are generally not routable on their own. In the [room ID grammar] `!opaque_id:domain`, the `domain` is the server that created the room. There is, however, no guarantee that this server is still joined to the room at a later time. Therefore, room IDs don't provide a reliable resident server -to send requests to. +to send requests to. Critically, the `domain` is not to be used as a routing server. It is purely a namespace. The spec partially addresses this issue by defining a [`via`] query parameter on room URIs that can be used to list servers that have a high probability of being in the room in the distant future. Additionally, From 0a8e6e1098978107857d139edee357682c705308 Mon Sep 17 00:00:00 2001 From: Johannes Marbach Date: Fri, 9 Aug 2024 08:16:12 +0200 Subject: [PATCH 5/7] Downgrade clients use of `via` to SHOULD --- proposals/4156-server-name-to-via.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/4156-server-name-to-via.md b/proposals/4156-server-name-to-via.md index 01bbd401f2c..efd32745f4b 100644 --- a/proposals/4156-server-name-to-via.md +++ b/proposals/4156-server-name-to-via.md @@ -18,7 +18,7 @@ proposal attempts to standardize on `via`. The `server_name` query parameter on [`/_matrix/client/v3/join/{roomIdOrAlias}`] and [`/_matrix/client/v3/knock/{roomIdOrAlias}`] is deprecated and a new parameter `via: [string]` is -introduced. Clients MUST use `via` when the homeserver they're talking to supports it. To do this, they +introduced. Clients SHOULD use `via` when the homeserver they're talking to supports it. To do this, they MAY either detect server support through [`/_matrix/client/versions`] or always include both parameters. Homeservers MUST ignore all `server_name` parameters if any `via` parameters are supplied. From ae4e79cc9314928e60374b5be5fbcc320ededc90 Mon Sep 17 00:00:00 2001 From: Johannes Marbach Date: Fri, 9 Aug 2024 08:19:47 +0200 Subject: [PATCH 6/7] Clarify that server support can be detected through the supported spec versions in /versions --- proposals/4156-server-name-to-via.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/proposals/4156-server-name-to-via.md b/proposals/4156-server-name-to-via.md index efd32745f4b..3a3705e4829 100644 --- a/proposals/4156-server-name-to-via.md +++ b/proposals/4156-server-name-to-via.md @@ -18,8 +18,12 @@ proposal attempts to standardize on `via`. The `server_name` query parameter on [`/_matrix/client/v3/join/{roomIdOrAlias}`] and [`/_matrix/client/v3/knock/{roomIdOrAlias}`] is deprecated and a new parameter `via: [string]` is -introduced. Clients SHOULD use `via` when the homeserver they're talking to supports it. To do this, they -MAY either detect server support through [`/_matrix/client/versions`] or always include both parameters. +introduced. + +Clients SHOULD use `via` when the homeserver they're talking to supports it. To do this, they MAY either +detect server support through the supported spec versions in [`/_matrix/client/versions`] or always include +both parameters. + Homeservers MUST ignore all `server_name` parameters if any `via` parameters are supplied. From 7b3a7b35d398d7e888460fad5673c67dce10a9b7 Mon Sep 17 00:00:00 2001 From: Johannes Marbach Date: Fri, 9 Aug 2024 09:13:00 +0200 Subject: [PATCH 7/7] Add security consideration --- proposals/4156-server-name-to-via.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/proposals/4156-server-name-to-via.md b/proposals/4156-server-name-to-via.md index 3a3705e4829..d8719de33de 100644 --- a/proposals/4156-server-name-to-via.md +++ b/proposals/4156-server-name-to-via.md @@ -22,7 +22,7 @@ introduced. Clients SHOULD use `via` when the homeserver they're talking to supports it. To do this, they MAY either detect server support through the supported spec versions in [`/_matrix/client/versions`] or always include -both parameters. +both parameters (with identical values). Homeservers MUST ignore all `server_name` parameters if any `via` parameters are supplied. @@ -41,7 +41,9 @@ None other than accepting status quo. ## Security considerations -None. +A client that supplies different `via` and `server_name` parameters could be served a different room depending +on which set of parameters the server uses to resolve the room ID. Tricking a client into doing this seems very +difficult though because [Matrix URIs], for instance, only have a single documented `via` parameter. ## Unstable prefix @@ -54,6 +56,7 @@ Until this proposal is accepted into the spec, implementations SHOULD refer to ` None. +[Matrix URIs]: https://spec.matrix.org/v1.11/appendices/#matrix-uri-scheme [room ID grammar]: https://spec.matrix.org/v1.10/appendices/#room-ids [`via`]: https://spec.matrix.org/v1.10/appendices/#routing [`/_matrix/client/v3/join/{roomIdOrAlias}`]: https://spec.matrix.org/v1.10/client-server-api/#post_matrixclientv3joinroomidoralias