matrix-org / matrix-org/matrix-spec

What should happen when the homeserver is unable to fetch hierarchy info about a remote room?

Open
#2,237 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

clarification
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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.