matrix-org / matrix-org/matrix-spec
What should happen when the homeserver is unable to fetch hierarchy info about a remote room?
Nobody has claimed this yet.
- Dominant language
- HTML
- Stars
- 330
- Forks
- 150
- Avg merge
- 2h 21m
- Merged PRs (30d)
- 3
Description
### Link to problem area
Spaces `/hierarchy` endpoint (client API): https://spec.matrix.org/v1.16/client-server-api/#get_matrixclientv1roomsroomidhierarchy
### Issue
Clarify the server behavior when a someone requests `/hierarchy` for some space but the homeserver is unable to fetch hierarchy info for some unknown remote child room over federation. This could be because the remote `via` servers are unreachable or because the remote homeserver returned a mangled response (doesn't pass validation).
This is a superset of https://github.com/matrix-org/matrix-spec/issues/1467 which describes when the homeserver fails to fetch hierarchy information about a given `m.space.child` because the `via` servers are unreachable.
Currently, the spec doesn't say anything but I guess it's implied that the room is just omitted from the list of `rooms`. This is what happens in Synapse for example.
---
*Spawning from reviewing https://github.com/element-hq/synapse/pull/19021#discussion_r2452562397*
### Potential solutions
#### Status quo
Perhaps the status quo is good enough. The client can find these unknown remote rooms by comparing the `m.space.child` in the `children_state` of a space compared to the other rooms they received. From a client perspective, perhaps this isn't very surprising since you would be iterating over the `children_state` of each space to render it out. From a server implementer perspective not familiar with this API, I had to think hard enough to realize this (spawning this issue).
When the client encounters a `m.space.child` that they don't have a corresponding `SpaceHierarchyRoomsChunk` for, they can still render the room ID from the `m.space.child` and the client can try to join themselves with the `via` servers in the `m.space.child` event.
In this case, we should just document expectations. After writing this issue out, I think this is the correct approach.
#### Include the `room_id` by itself
We could include a `SpaceHierarchyRoomsChunk` in the list of `rooms` that only contains the `room_id` by itself. This isn't that useful unless we also include the `via` servers otherwise clients would have to find this in the `m.space.child` event (not very good ergonomics).
The other problem is that currently, some fields of the `SpaceHierarchyRoomsChunk` are marked as **Required**; so a) omitting them wouldn't validate correctly and b) it would be impossible distinguish stub values from actual values if we included them.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with the Spaces /hierarchy endpoint in the linked Matrix Client-Server API specification and review the related issue #1467 and Synapse discussion. Determine the intended response when remote hierarchy data cannot be fetched or validated, then document that behavior and its interaction with children_state; done means the specification removes the ambiguity for clients and server implementers.
Written by the indexing model from the issue text.
Assessment
- Domain
- api, documentation
- Issue type
- Documentation
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 38/100