Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

MSC4156: Migrate server_name to via #4156

Merged
merged 7 commits into from
Aug 19, 2024
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
64 changes: 64 additions & 0 deletions proposals/4156-server-name-to-via.md
turt2live marked this conversation as resolved.
Show resolved Hide resolved
Original file line number Diff line number Diff line change
@@ -0,0 +1,64 @@
# MSC4156: Migrate `server_name` to `via`
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Just wanted to say that this sounds to me like a sensible idea to try to standardise terminology in this case to make everyones lives easier.

Thanks for this very sensible proposal.


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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is nice but honestly, for next time, I think it's unnecessary. I think it's fair to assume the audience is already familiar with the problem.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

having the detail in the introduction I think is important, but agreed the phrasing is slightly off here. Not all readers will have context on the problem, particularly when it's a bit of obscure spec.


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