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