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

MSC4235: via query param for hierarchy endpoint #4235

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

MSC4235: via query param for hierarchy endpoint #4235

Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
a66750c
add server name query param for hierarchy endpoint proposal
ajbura Dec 2, 2024
0cbd27e
add msc number
ajbura Dec 2, 2024
ac419f8
change param name to via
ajbura Dec 4, 2024
e4822ae
fix typos and add link to space summary msc
ajbura Dec 4, 2024
120f6a2
remove server specific issues and improve benefits
ajbura Dec 4, 2024
9fd3b7c
fix typo
ajbura Dec 5, 2024
a9933d2
fix typo
ajbura Jan 14, 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
36 changes: 36 additions & 0 deletions proposals/4235-via-query-param-for-hierarchy.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,36 @@
# MSC4235: `via` query param for /hierarchy endpoint

To request the hierarchy of a space, clients need to call the
[/hierarchy](https://spec.matrix.org/v1.9/client-server-api/#get_matrixclientv1roomsroomidhierarchy) endpoint introduced
in [MSC2946](https://github.com/matrix-org/matrix-spec-proposals/pull/2946). This endpoint does not require user to join
Copy link
Member

Choose a reason for hiding this comment

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

We should link to the spec if possible?

Copy link
Author

Choose a reason for hiding this comment

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

it already has link to the hierarchy spec or I am missing something?

Copy link
Member

Choose a reason for hiding this comment

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

There's no reason to link to the MSC then, it's confusing.

the room before responding with hierarchy details. It instead check whether the room is potentially joinable (per
[MSC3173](https://github.com/matrix-org/matrix-spec-proposals/pull/3173)) before responding.

Because it does not require a space room to be joined before calling this endpoint, it's possible that the requested
Copy link
Member

Choose a reason for hiding this comment

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

How would this happen? From a room directory response? I'm unsure what user interactions would cause this.

Copy link
Author

Choose a reason for hiding this comment

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

User interactions are implementation specific, this MSC is trying to fix the issue in the hierarchy spec. An example using the via param would be requesting the only part of sub-spaces hierarchy which is unknown the the client. I have listed some more example of how this could be helpful in the MSC itself.

room may not be locally available on the server. The server might need to request information over federation to
respond. In such a case, this endpoint doesn't provide a mechanism for the client to specify the server name from which
the server should request information.

## Proposal

The [/hierarchy](https://spec.matrix.org/v1.9/client-server-api/#get_matrixclientv1roomsroomidhierarchy) endpoint should
include `via` as query parameter which server can use in case requested room in not locally available on the server.

This change will stabilize the endpoint and allows clients to use this endpoint in more efficient manner, like:
1. Requesting the only part of sub-spaces hierarchy which is unknown the the client.
2. Rendering the preview of space and it's children before joining the space.
3. Since depth-first hierarchy responses can be costly, especially when reaching the end of the hierarchy, clients can
optimize the process by loading subspaces independently. This approach can improve efficiency by loading the
hierarchy of individual subspaces only when the user views them.

## Potential issues
Unknown

## Alternative
Unknown

## Security considerations
Unknown

## Unstable prefix
None
Loading