matrix-org / matrix-org/matrix-spec
Expiration of pagination tokens on `/hierarchy` not specified
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**: https://spec.matrix.org/v1.2/client-server-api/#get_matrixclientv1roomsroomidhierarchy
**Issue**
MSC2946 ([MD](https://github.com/matrix-org/matrix-spec-proposals/blob/main/proposals/2946-spaces-summary.md#server-behaviour)) states:
> When the current response page is full, the current state should be persisted and a pagination token should be generated (if there is more data to return). To prevent resource exhaustion, the server may expire persisted data that it deems to be stale.
however, this note about expiration is not included in the spec for clients to rely on.
**Expected behaviour**
The spec should clearly state the expiration requirements to avoid confusion such as https://github.com/matrix-org/synapse/issues/12697 / https://github.com/vector-im/element-web/issues/22138
**Historical proof**
> This was implemented in https://github.com/matrix-org/synapse/pull/10574 as part of maintenance work for https://github.com/matrix-org/synapse/issues/10495 which appeared shortly after MSC2946 was updated.
— https://github.com/matrix-org/synapse/issues/12697#issuecomment-1122947619
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 linked `/hierarchy` section in the Matrix Client-Server API specification, then compare its pagination wording with MSC2946's “Server behaviour” section. Review the linked Synapse and Element issues for the ambiguity this change should address. Done means the specification clearly states the expiration requirements for persisted pagination data and tokens.
Written by the indexing model from the issue text.
Assessment
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100