MSC4156: Migrate server_name to via

proposals/4156-server-name-to-via.md

@@ -0,0 +1,64 @@
+# 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. 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,
+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 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 (with identical values).
+
+Homeservers MUST ignore all `server_name` parameters if any `via` 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
+
+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
+
+Until this proposal is accepted into the spec, implementations SHOULD refer to `via` as `org.matrix.msc4156.via`.
+
+
+## Dependencies
+
+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
+[`/_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