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.

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

MSC2063: Add "server information" public API proposal #2063

Open
wants to merge 7 commits into
base: old_master
Choose a base branch
from
Open

MSC2063: Add "server information" public API proposal #2063

Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
253f289
Add "server information" public API proposal
grinapo May 31, 2019
4b91bff
Tried to guess next PR number, but... okay, renaming.
grinapo May 31, 2019
3f605b8
Reflow the text for 80 chars
grinapo May 31, 2019
3dc8101
Replace fictive rejected error with real M_FORBIDDEN.
grinapo Jun 2, 2019
c59cd3b
Remove Tradeoffs section and merge partly into Intro.
grinapo Jun 2, 2019
0b06f97
Remove from the actual proposal the MSC-1929 stuff.
grinapo Jun 3, 2019
5296824
Add specific endpoint and result data.
grinapo Jun 3, 2019
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
90 changes: 90 additions & 0 deletions proposals/2063-serverinfo.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,90 @@
* **author**: Peter Gervai
* **Created**: 2019-05-32

## Introduction

Matrix network have a general problem of an overloaded _matrix.org_
server and many underused, hard to find servers just waiting for users.
There are -- and probably will be more -- services which help users to
find servers matching their needs. These lists are only as useful as
the data they offer.

The most important data is available: network reachability. Apart from
that, however, there are very few API endpoints available to provide
generic statistical and administrative data about the servers for
future users. This proposal offers ideas of such endpoints, and
welcomes input from seasoned spec authors to actually dream it into
syntax.

Right now the following is available:
* server version (`_matrix/federation/v1/version`)
* supported client specs (`_matrix/client/versions`)
* supported login methods (`_matrix/client/r0/login`)

Technically `_matrix/key/v2/query` can be used as a crude
connectivity-check tool.

The proposed endpoint(s) would provide a standardised **possibility**
for admins to publish the data helping to pick their servers, it is
not compulsory, thus does not guarantee that such data is available.

## Proposal

The following information would be available (for anyone without any
pre-arranged state):
grinapo marked this conversation as resolved.
Show resolved Hide resolved

* whether the HS supports (open) registrations
* number of registered users / active users in the last *week/month*
* server uptime

Apart from the *first one* all endpoints can be "legally" disabled and
grinapo marked this conversation as resolved.
Show resolved Hide resolved
result a `M_FORBIDDEN` error, so the admin can decide not to publish
the data for whatever reason.

### GET /_matrix/federation/v1/server_data

* Rate-limited: Yes
* Requires auth: No

Requires no parameters.

Response:

```json
{
"server_data": {
"m.open_registrations": true,
"m.uptime": 63072000,
Copy link
Member

Choose a reason for hiding this comment

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

I'm wondering what usefulness the uptime actually has? If it is small, it could be "they updated recently == good" or "they're in a crash loop doing constant OOM == bad". If it is big it could be either "it's stable" or "it's not being maintained". I don't know what would be better though, just wondering whether it is good to include numbers that don't really have any particular purpose. This feels more something that should live in the /metrics endpoint for prometheus.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

include numbers that don't really have any particular purpose.

If you do not need it doesn't mean nobody else does. I could describe how it's useful but really, I believe that "it is useful for some people" should be enough to justify.

This feels more something that should live in the /metrics endpoint for prometheus.

This is a public endpoint, in contrast to prometheus. The primary point is to provide data for automated public server lists.

Copy link
Member

Choose a reason for hiding this comment

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

tbh the first thing I'd disable is uptime: there's no metric that can be pulled from it which helps users with anything. How does uptime apply to a worker or multi-process homeserver for instance?

Copy link
Contributor Author

Choose a reason for hiding this comment

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

How does uptime apply to a worker or multi-process homeserver for instance?

From the users viewpoint a service is "UP" when it's working. :-)
(As a user I would not pick a server with a constant less than a few days uptime, since it's either keep restarting or crashing, but that's me.)

But maybe you're right that it should be externally measured [icmp/api calls] instead of relying on the server.

"m.registered_users": 4,
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 almost perfect; but it'd be probably better to further distinguish between statistics/status information (uptime and the number of users) and configuration/settings information (open registrations). I don't know if it's worth it to introduce a separate /server_config endpoint just for a single boolean value - probably overengineering here. It would be great to have other opinions on this.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

How about

{
 "server_data": {
  "settings": {
    "m.open_registrations": true
  },
  "statistics" : {
    "m.uptime": 63072000,
    "m.registered_users": 4
  }
 }
}

Processing a json and ignoring unnecessary fields is probably painless enough that it doesn't justify creating any more complexity.

I guess someone shall come up with a real justification to separate them even this way though, or maybe it's good for "visibility" or "mental separation"?

Copy link
Member

Choose a reason for hiding this comment

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

I'd rather use two separate endpoints. The reason is that open registrations may (I can imagine that in theory at least) be configurable using some administration API. What I mean to say is that generally configuration is, at least in theory, read/write depending on your access credentials, while statistics are produced by the servers and cannot be tweaked even in theory. But probably let's validate it in the Matrix room.

Copy link
Contributor

Choose a reason for hiding this comment

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

Should be pointed out that open_registrations is not something federation should care about. It should be reported by a client API.

Copy link
Member

Choose a reason for hiding this comment

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

tbh I think it's fine to expose health/metadata/metrics at the federation level for this, mostly because there's a discovery function that server lists can use to query the data.

}
}
```
* `open_registrations`: `true` if the server accepts new account registrations
(open server); this response field is **required**.
* `uptime` in *seconds* (possible to see whether there was a recent restart,
upgrade)

### Data acquired by other means

The following data will be (or ought to be) provided by pull#1929
(MSC 1929) through static `.well-known` method:

* server human readable name
* server description / blurb
* country of the server (if applicable)
* server admin contact

There ought to be a way to gather *server connectivity data*, to check
working federation, but it shall be covered by a specific proposal later.

## Security considerations

Since servers are reachable through public methods these don't really
open up attack surfaces; replies are quasi-static data.

## Conclusion

Implementing these endpoints would make it possible to generate
*automated server lists* with data suited to make educated guesses about
server suitability for new users.