Skip to content

MSC4383: Client-Server Discovery of Server Version #4383

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.

Sign up for GitHub

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

Open
jevolk wants to merge 2 commits into
base: main
Choose a base branch
from
Open

MSC4383: Client-Server Discovery of Server Version #4383

Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
63cdb4b
MSC4383: Client-Server Discovery of Server Version
jevolk Nov 21, 2025
7904077
Move description of use case from footnotes to introduction.
jevolk Nov 25, 2025
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
92 changes: 92 additions & 0 deletions proposals/4383-client-server-info.md
View file
Open in desktop
Copy link
Member

@turt2live turt2live Nov 24, 2025

Choose a reason for hiding this comment

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

Implementation requirements:

  • Client (ideally multiple)
  • Server

Original file line number Diff line number Diff line change
@@ -0,0 +1,92 @@
# MSC4383: Client-Server Discovery of Server Version

Copy link
Member

@turt2live turt2live Nov 24, 2025

Choose a reason for hiding this comment

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

This proposal appears to be lacking a problem statement and/or introduction, making it difficult to review with an aim to include it in the spec.

Copy link
Contributor Author

@jevolk jevolk Nov 24, 2025

Choose a reason for hiding this comment

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

The problem is stated in the Alternatives section. I didn't feel the need to make a redundant introduction given the status quo alternative is prominent and it's a small proposal otherwise. Should the first paragraph be moved to the top?

Copy link
Member

@turt2live turt2live Nov 24, 2025

Choose a reason for hiding this comment

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

Relevant information and background should always be first. I didn't feel the paragraph in the Alternatives was suited as an introduction because it lacks background and context.

### Motivation

Client applications utilizing the Matrix SDK[^6], a Client-Server[^7] library, have been observed
making requests to `GET /_matrix/federation/v1/version`[^2]. It is the only known example of a
cross-interface request to have any possible[^5] use to any implementation[^3], motivating this
proposal to reestablish a properly clean partition between client and federation interfaces.
Copy link
Contributor

@Johennes Johennes Nov 24, 2025

Choose a reason for hiding this comment

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

Why do these applications query the SS API in the first place? Also, do they query the SS API on their own home server or on remote servers?

Copy link
Contributor Author

@jevolk jevolk Nov 24, 2025

Choose a reason for hiding this comment

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

In the found case, the information is logged and not used to determine application-logic. The logs are then included in rageshakes.

The query is only to the local server, as remote servers would require server name resolution which the client is not capable of—arguably the local server also requires the resolution for the federation interface which is itself another concern for why the status quo is untenable.

Copy link
Contributor

@Johennes Johennes Nov 24, 2025

Choose a reason for hiding this comment

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

Thanks! I think both of these would be good to include in the main text as they help understand the proposed solution. For instance, if querying /versions on a remote server was a use case, you would need a different API shape that allows to pass in the server name.

Copy link
Contributor Author

@jevolk jevolk Nov 24, 2025

Choose a reason for hiding this comment

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

Are you suggesting morphing this proposal into a client API where the homeserver can run version queries on any other server on behalf of the client?

Copy link
Contributor

@Johennes Johennes Nov 24, 2025

Choose a reason for hiding this comment

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

Sorry, no. I just meant to use that as an example to illustrate that without describing the use case it's not clear why the proposed solution is the best one.


Such cross-interface requests are problematic: the partition in the `/_matrix` URL hierarchy is
understood by site-administrators to allow for distinct middleware configurations. Sites commonly
employ WAF rules covering the client and federation hierarchies with source and destination
assumptions. Some sites disable the entire federation portion, rendering the status quo as unreliable.

This proposal reestablishes the partition between client-server and server-server by simply offering
the same version data over both. With the adoption of this proposal, no need for cross-interface
requests will be known to remain.

### Proposal

An object is added to the top-level of `GET /_matrix/client/versions`[^1] named `server` with
parity to the eponymous object returned by `GET /_matrix/federation/v1/version`[^2].

Example of the `server` object:

```
"server": {
"name": "My_Homeserver_Implementation",
"version": "ArbitraryVersionNumber"
}
```

Example of a full response:
```
{
"server": {
"name": "My_Homeserver_Implementation",
"version": "ArbitraryVersionNumber"
},
"unstable_features": {
"org.example.my_feature": true
},
"versions": [
"r0.0.1",
"v1.1"
]
}
```

##### Unstable prefix

| Stable identifier | Purpose | Unstable identifier |
| --- | --- | ---|
| `server` | Server information | `net.zemos.msc4383.server` |

### Alternatives

MSC2301[^4] enriches the discovery information, including some identifying information about the
server, though specific formal vendor and semantic version information appears avoided
(see: potential issues).

### Potential Issues

Server vendor and version information has been considered counter-productive to the motivations
of Matrix as a unifying communication standard. Matrix believes any use of implementation
knowledge as a condition in its applications always represents an accidental failure of its
implementations or the standard binding them; the solution to such problems is thus found in
cooperation, community and conformity, precluding the need for bug-for-bug conditions and
workarounds. This MSC has the option of including a normative statement which inhibits the use
of vendor information to determine functionality.

### Security Concerns

The federation endpoint is the only location which presently reveals this information.
Site-administrators which have taken some measure to hide, or obscure, or modify it (i.e. with a
proxy) will have to note their implementation's new exposure of it when upgrading.


[^1]: https://spec.matrix.org/v1.16/client-server-api/#api-versions

[^2]: https://spec.matrix.org/v1.16/server-server-api/#server-implementation

[^3]: https://github.com/matrix-org/matrix-rust-sdk/blob/d228bde8ef51a98da10a6b7d4b9f3e5b8f49ad3c/crates/matrix-sdk/src/client/mod.rs#L581-L616

[^4]: https://github.com/matrix-org/matrix-spec-proposals/pull/2301

[^5]: Server version information can provide useful context in logs and may be essential for
effective crash reports.

[^6]: https://github.com/matrix-org/matrix-rust-sdk

[^7]: https://spec.matrix.org/v1.16/client-server-api/