MSC3266: Room summary API #3266

deepbluev7 · 2021-07-04T19:30:53Z

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). The allowed_room_ids part is implemented here: deepbluev7/synapse@37f4253.
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
shields.io: https://shields.io/badges/matrix, Support [Matrix] summary endpoint badges/shields#10782
Matrix Room Search: https://gitlab.com/etke.cc/mrs/api/-/commit/bc4a4a649cfbf98d850ea0248c78afc5d552e1be

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

SCT stuff:

Shepherd: @richvdh
FCP tickyboxes

Checklist: #3266 (comment)

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

proposals/3266-room-summary.md

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

proposals/3266-room-summary.md

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

…est of the path separate Signed-off-by: Nicolas Werner <nicolas.werner@hotmail.de>

That way the requesting server knows, if any user would have access to that room and it can forward the room to the user. Signed-off-by: Nicolas Werner <nicolas.werner@hotmail.de>

proposals/3266-room-summary.md

richvdh · 2025-03-26T09:05:12Z

@KitsuneRal you have an outstanding request for changes (#3266 (review), I think). Could you dismiss your review, unless you still want to see changes here?

richvdh · 2025-03-26T09:05:47Z

🔔 This is now entering its final comment period, as per the review above. 🔔

As far as I can tell, this should have completed FCP weeks ago, but the bot seems to be stuck.

turt2live · 2025-03-26T18:58:48Z

considering FCP completed as-is. If there's edits to be made to the MSC, please put those up as a PR urgently.

* Room summary proposal Signed-off-by: Nicolas Werner <nicolas.werner@hotmail.de> * Remove alias resolution step from the federation API * Reference #688 in the alternatives section Signed-off-by: Nicolas Werner <nicolas.werner@hotmail.de> * Remove `is_direct` from response Signed-off-by: Nicolas Werner <nicolas.werner@hotmail.de> * Fix unstable prefixes for implementations which keep the prefix and rest of the path separate Signed-off-by: Nicolas Werner <nicolas.werner@hotmail.de> * Add allowed_room_ids field That way the requesting server knows, if any user would have access to that room and it can forward the room to the user. Signed-off-by: Nicolas Werner <nicolas.werner@hotmail.de> * Extend rationale for additional fields to reference MSC2946 Also explain that membership is already accessible information. Signed-off-by: Nicolas Werner <nicolas.werner@hotmail.de> * Add bulk API as an alternative Signed-off-by: Nicolas Werner <nicolas.werner@hotmail.de> * Remove federation API and address feedback - Add some additional rationale to some things. - Federation API now reuses MSC 2946 - roomid -> roomId - Move it out of /rooms, because it allows using an alias Signed-off-by: Nicolas Werner <nicolas.werner@hotmail.de> * fix prefixes again * Remove extensions to federation API since that MSC is amended now Signed-off-by: Nicolas Werner <nicolas.werner@hotmail.de> * Fix minor inaccuracy about the spaces sumary api * Add encryption field back * Add room version field Signed-off-by: Nicolas Werner <nicolas.werner@hotmail.de> * Apply suggestions from code review Co-authored-by: Andrew Morgan <1342360+anoadragon453@users.noreply.github.com> Co-authored-by: Alexey Rusakov <Kitsune-Ral@users.sf.net> * Add a bit more reasoning * version -> room_version * Apply suggestions from code review Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> * Try to address review comments Signed-off-by: Nicolas Werner <nicolas.werner@hotmail.de> * Fix incorrect statement about encryption being a bool Signed-off-by: Nicolas Werner <nicolas.werner@hotmail.de> * Apply suggestions from code review Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> * Split up the big alternatives section * Collapse the same descriptions for publicRooms and hierarchy into one * Shorten the 'accessible' section again * Update proposals/3266-room-summary.md Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> * Update proposals/3266-room-summary.md * Update proposals/3266-room-summary.md Co-authored-by: Alexey Rusakov <Kitsune-Ral@users.sf.net> * Support knock_restricted rooms and rename to room_summary As well as a few smaller clarifications. * Be more explicit about authentication * Apply suggestions from code review Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> Co-authored-by: Patrick Cloke <clokep@users.noreply.github.com> * Fix error codes and missing "Optional" * Also add allowed_room_ids to hierarchy API It suffers from the same knock_restricted issue. * Apply suggestions from code review Co-authored-by: Eric Eastwood <madlittlemods@gmail.com> Co-authored-by: Patrick Cloke <clokep@users.noreply.github.com> * Update spec links * Clarify accessibility rules * Update proposals/3266-room-summary.md Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> * Update proposals/3266-room-summary.md Co-authored-by: Johannes Marbach <n0-0ne+github@mailbox.org> * Unauthenticated access is impl-dependent * add to response * Clarify resposnse documentation. * Clarify situation for invited rooms * further clarification about unauth access * Update proposals/3266-room-summary.md Co-authored-by: Johannes Marbach <n0-0ne+github@mailbox.org> --------- Signed-off-by: Nicolas Werner <nicolas.werner@hotmail.de> Co-authored-by: Andrew Morgan <1342360+anoadragon453@users.noreply.github.com> Co-authored-by: Alexey Rusakov <Kitsune-Ral@users.sf.net> Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> Co-authored-by: Patrick Cloke <clokep@users.noreply.github.com> Co-authored-by: Eric Eastwood <madlittlemods@gmail.com> Co-authored-by: Richard van der Hoff <richard@matrix.org> Co-authored-by: Johannes Marbach <n0-0ne+github@mailbox.org>

proposals/3266-room-summary.md

Johennes · 2025-03-28T12:39:02Z

proposals/3266-room-summary.md

+
+For unauthenticated requests a response should only be returned if the room is
+publicly accessible; specifically, that means either:
+ * the room has `join_rule: public` or `join_rule: knock`, or:


I suspect this is meant to include knock_restricted?

If the current implementation does so, yes. Otherwise it'll need a new MSC.

Luckily it does: https://github.com/element-hq/synapse/blob/develop/synapse/handlers/room_summary.py#L611

Johennes · 2025-03-31T12:28:59Z

Spec PR: matrix-org/matrix-spec#2125

Add two new fields to PublicRoom struct for MSC3266 room summary support: - Encryption: The encryption algorithm used in the room - RoomVersion: The room version These fields use unstable prefixes (im.nheko.summary.*) until MSC3266 is merged into the Matrix spec. This enables federation hierarchy responses to include encryption and room version information for room previews. Ref: matrix-org/matrix-spec-proposals#3266

Room summary proposal

642f4e1

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

deepbluev7 changed the title ~~Room summary proposal~~ MSC3266: Room summary proposal Jul 4, 2021

deepbluev7 force-pushed the room-summaries branch from 855306e to 642f4e1 Compare July 4, 2021 19:32

deepbluev7 changed the title ~~MSC3266: Room summary proposal~~ MSC3266: Room summary Jul 4, 2021

Sorunome reviewed Jul 5, 2021

View reviewed changes

proposals/3266-room-summary.md Show resolved Hide resolved

deepbluev7 commented Jul 5, 2021

View reviewed changes

proposals/3266-room-summary.md Outdated Show resolved Hide resolved

tulir reviewed Jul 5, 2021

View reviewed changes

proposals/3266-room-summary.md Outdated Show resolved Hide resolved

tulir reviewed Jul 5, 2021

View reviewed changes

proposals/3266-room-summary.md Outdated Show resolved Hide resolved

Remove alias resolution step from the federation API

188b6e5

haslersn reviewed Jul 9, 2021

View reviewed changes

proposals/3266-room-summary.md Outdated Show resolved Hide resolved

KitsuneRal reviewed Jul 11, 2021

View reviewed changes

proposals/3266-room-summary.md Show resolved Hide resolved

deepbluev7 changed the title ~~MSC3266: Room summary~~ MSC3266: Room summary API Jul 11, 2021

Reference matrix-org#688 in the alternatives section

dc5b372

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

t3chguy reviewed Jul 14, 2021

View reviewed changes

proposals/3266-room-summary.md Outdated Show resolved Hide resolved

t3chguy reviewed Jul 14, 2021

View reviewed changes

proposals/3266-room-summary.md Outdated Show resolved Hide resolved

t3chguy reviewed Jul 14, 2021

View reviewed changes

proposals/3266-room-summary.md Outdated Show resolved Hide resolved

t3chguy reviewed Jul 14, 2021

View reviewed changes

proposals/3266-room-summary.md Outdated Show resolved Hide resolved

t3chguy reviewed Jul 14, 2021

View reviewed changes

proposals/3266-room-summary.md Outdated Show resolved Hide resolved

t3chguy mentioned this pull request Jul 14, 2021

Initial MSC3266 implementation with tweaks for displaying Spaces matrix-org/matrix.to#219

Merged

t3chguy reviewed Jul 14, 2021

View reviewed changes

proposals/3266-room-summary.md Show resolved Hide resolved

deepbluev7 added 3 commits July 14, 2021 20:09

Remove is_direct from response

975ece5

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

Fix unstable prefixes for implementations which keep the prefix and r…

d148acf

…est of the path separate Signed-off-by: Nicolas Werner <nicolas.werner@hotmail.de>

Add allowed_room_ids field

6776863

That way the requesting server knows, if any user would have access to that room and it can forward the room to the user. Signed-off-by: Nicolas Werner <nicolas.werner@hotmail.de>

t3chguy reviewed Jul 14, 2021

View reviewed changes

proposals/3266-room-summary.md Outdated Show resolved Hide resolved

t3chguy reviewed Jul 14, 2021

View reviewed changes

proposals/3266-room-summary.md Outdated Show resolved Hide resolved

mscbot added the final-comment-period This MSC has entered a final comment period in interest to approval, postpone, or delete in 5 days. label Mar 7, 2025

turt2live moved this from Ready for FCP ticks to In FCP in Spec Core Team Workflow Mar 7, 2025

stefanceriu mentioned this pull request Mar 10, 2025

Invites room summary fallback matrix-org/matrix-rust-sdk#4780

Merged

KitsuneRal approved these changes Mar 26, 2025

View reviewed changes

turt2live merged commit 520ba77 into matrix-org:old_master Mar 26, 2025

turt2live moved this from In FCP to Requires spec writing in Spec Core Team Workflow Mar 26, 2025

Johennes reviewed Mar 28, 2025

View reviewed changes

proposals/3266-room-summary.md Show resolved Hide resolved

Johennes reviewed Mar 28, 2025

View reviewed changes

Johennes mentioned this pull request Mar 31, 2025

Spec PR - MSC3266: Room Summary API matrix-org/matrix-spec#2125

Merged

3 tasks

turt2live added spec-pr-in-review A proposal which has been PR'd against the spec and is in review and removed spec-pr-missing Proposal has been implemented and is being used in the wild but hasn't yet been added to the spec labels Apr 1, 2025

turt2live moved this from Requires spec writing to Requires spec PR review in Spec Core Team Workflow Apr 1, 2025

clokep added merged A proposal whose PR has merged into the spec! and removed spec-pr-in-review A proposal which has been PR'd against the spec and is in review labels Jun 4, 2025

This was referenced Jun 7, 2025

client-api,federation-api: Add common RoomSummary type ruma/ruma#2097

Merged

Implement Matrix 1.15 changes ruma/ruma#2082

Closed

turt2live moved this from Requires spec PR review to Done to some definition in Spec Core Team Workflow Jun 10, 2025

Johennes mentioned this pull request Jul 3, 2025

Matrix v1.15 gematik/api-ti-messenger#323

Closed

34 tasks

turt2live mentioned this pull request Jul 24, 2025

Support Matrix 1.15 element-hq/synapse#18731

Open

34 tasks

KitsuneRal mentioned this pull request Aug 25, 2025

Invites need to convey a better summary of the room they describe. matrix-org/matrix-spec#380

Closed

MSC3266: Room summary API #3266

MSC3266: Room summary API #3266

Uh oh!

Conversation

deepbluev7 commented Jul 4, 2021 • edited by richvdh Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

richvdh commented Mar 26, 2025

Uh oh!

richvdh commented Mar 26, 2025

Uh oh!

turt2live commented Mar 26, 2025

Uh oh!

Uh oh!

Johennes Mar 28, 2025

Choose a reason for hiding this comment

Uh oh!

turt2live Mar 28, 2025

Choose a reason for hiding this comment

Uh oh!

Johennes Mar 28, 2025

Choose a reason for hiding this comment

Uh oh!

Johennes commented Mar 31, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

20 participants

deepbluev7 commented Jul 4, 2021 •

edited by richvdh

Loading