MSC3266: Room summary API

[deepbluev7]

Rendered.

Somewhat related to MSC2946 this provides an API to get a summary for a specific room either from the local server or over federation.

Useful for a few cases, where you need to show a summary for a room like matrix.to, traveler bots, showing spaces, lightweight clients, etc.

Open design questions looking for feedback: see this comment chain: #3266 (comment) resolved as of 2021/10/06

Implementations:

• matrix.to: matrix-org/matrix.to#219
• Synapse: matrix-org/synapse#10394 (Only CS API) and matrix-org/synapse#11507 (for the federation bits)
• Element Android: Better room preview, use room Summary API if available element-hq/element-android#3986
• Element Web (for member counts on space invites): For space invite previews, use room summary API to get the right member count matrix-react-sdk#6982 and Add method to fetch the MSC3266 Room Summary of a Room matrix-js-sdk#1988
• Nheko (to have a prettier join room preview): Nheko-Reborn/nheko@9d8d6b4
• matrix-rust-sdk: room preview: use the room summary MSC3266 endpoint matrix-rust-sdk#3339

Signed-off-by: Nicolas Werner nicolas.werner@hotmail.de

---

SCT stuff:

Checklist: #3266 (comment)

[t3chguy]

Also the /state API also doesn't return stripped state events so would not have access to said data based on the Stripped State MSC https://matrix.org/docs/spec/client_server/r0.6.1#get-matrix-client-r0-rooms-roomid-state

The specific state API does return stripped state (because consistency, what's that) https://matrix.org/docs/spec/client_server/r0.6.1#get-matrix-client-r0-rooms-roomid-state-eventtype-statekey

But would require MANY API hits and not be able to reach all the data (e.g num_joined_members would not be possible)

[t3chguy]

An interesting future consumer of this work could be shields.io - https://github.com/badges/shields/blob/master/services/matrix/matrix.service.js currently registers a bunch of guests and uses the /state/ API so a dedicated API which doesn't require auth would be ideal.

[richvdh]

Still lots of outstanding questions from previous reviews here. @deepbluev7 are you still interested in pursuing this?

[deepbluev7]

Yeah, I am still pursuing this, but I need to update it to work with the new room join rule, since there knocking and restricted joins are not distinguishable, so the allowed roomids need to be exposed, possibly prefiltered. But since my clients now need the unstable endpoint anyway in a few released versions, I am not as much in a hurry anymore.

[turt2live]

I'm going to take this off the SCT's priority list in that case. There is a bit of a problem if clients are relying on the unstable endpoint existing (as we're seeing happen outside of just your clients) - ideally, the MSC moves forward at a more hurried pace to avoid problems related to defacto spec.

For reference, how we'd likely avoid defacto spec being an issue here is recommend the feature for removal from Synapse, forcing clients to treat the functionality as unstable.

[deepbluev7]

Well, the spec team told me to prioritize #3664, so that's what I did. Now that is stuck again. Before that, this MSC was stuck because there weren't enough implementations and half of the comments are nitpicking about wording or names, instead of actually being helpful to the content of the MSC, so it simply takes a bit of time to work on things. I changed some sentences 3 or more times. It simply takes a bit of time to please everyone with the wording, since if you react quickly, you end up just changing it back again on the next comment.

I think the 2 open points, that are actually important for the functionality of the MSC are:

• error codes
• No information about if you can join a restricted_knock room

The rest, in my opinion, is arguing about how specific things are worded or if a specific sentence "is important".

[melroy89]

Also still not merged? We have a lot of users now complaining they can't see the rooms in the Matrix space. Most likely people are using Dendrite. Please consider making it out of beta this year...

[deepbluev7]

@melroy89 Previewing rooms in a space is already part of the spec. This is for rooms outside the space hierarchy.

[melroy89]

@melroy89 Previewing rooms in a space is already part of the spec. This is for rooms outside the space hierarchy.

Ah I see, since that still needs to be enabled manually in Dendrite?
https://github.com/matrix-org/dendrite/blob/main/docs/FAQ.md#does-dendrite-support-space-summaries

[deepbluev7]

That's because the devs didn't get around to stabilizing it and has little to do with the spec.

[aine-etke]

@deepbluev7 could you update the implementations list with MRS, please?

• issue: https://gitlab.com/etke.cc/mrs/api/-/issues/27
• commit: https://gitlab.com/etke.cc/mrs/api/-/commit/bc4a4a649cfbf98d850ea0248c78afc5d552e1be

[deepbluev7]

With the introduction of knock_restricted, knowing the join rule isn't sufficient to know which method the room can be joined via. As such the response should also include the allowedRoomIds, that the user is joined to or so.

[deepbluev7]

It's not clear if this includes invites. It probably should, but that should be explicitly mentioned in the MSC.

[AndrewFerr]

This should also define a new unstable_features flag for GET /_matrix/client/versions.

For example, adapting from MSC3026:

servers implementing this MSC must expose a flag in GET /_matrix/client/versions responses, under unstable_features, named im.nheko.msc3266, which is set to true.

Other MSCs that define an unstable_features are MSC2432, MSC2666, MSC2285, MSC3827, and MSC3440.

[turt2live]

The SCT is aiming to ensure MSCs actually pass the checklist before FCP is proposed. This comment is that checklist tracking.

• Are appropriate implementation(s) specified in the MSC’s PR description?
• Are all MSCs that this MSC depends on already accepted?
• For each new endpoint that is introduced:
  • Have authentication requirements been specified?
  • Have rate-limiting requirements been specified?
  • Have guest access requirements been specified?
  • Are error responses specified?
    • Does each error case have a specified errcode (e.g. M_FORBIDDEN) and HTTP status code?
      • If a new errcode is introduced, is it clear that it is new?
• Will the MSC require a new room version, and if so, has that been made clear?
  • Is the reason for a new room version clearly stated? For example, modifying the set of redacted fields changes how event IDs are calculated, thus requiring a new room version.
• Are backwards-compatibility concerns appropriately addressed?
• Are the endpoint conventions honoured?
  • Do HTTP endpoints use_underscores_like_this?
  • Will the endpoint return unbounded data? If so, has pagination been considered?
  • If the endpoint utilises pagination, is it consistent with the appendices?
• An introduction exists and clearly outlines the problem being solved. Ideally, the first paragraph should be understandable by a non-technical audience.
• All outstanding threads are resolved
  • All feedback is incorporated into the proposal text itself, either as a fix or noted as an alternative
• While the exact sections do not need to be present, the details implied by the proposal template are covered. Namely:
  • Introduction
  • Proposal text
  • Potential issues
  • Alternatives
  • Dependencies
• Stable identifiers are used throughout the proposal, except for the unstable prefix section
  • Unstable prefixes consider the awkward accepted-but-not-merged state
  • Chosen unstable prefixes do not pollute any global namespace (use “org.matrix.mscXXXX”, not “org.matrix”).
• Changes have applicable Sign Off from all authors/editors/contributors
• There is a dedicated "Security Considerations" section which detail any possible attacks/vulnerabilities this proposal may introduce, even if this is "None.". See RFC3552 for things to think about, but in particular pay attention to the OWASP Top Ten.