matrix-org / matrix-org/matrix-spec

lazy-loading behaviour for `/sync` is incorrectly specified

Open
#942 9 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

clarification spec-bug
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.1/client-server-api/#get_matrixclientv3sync

I'm having a hard time following the description of `/sync`'s behaviour. In particular, the third paragraph:

> Further, like other members, the user's own membership event is eligible
> for being considered redundant by the server. When a sync is `limited`,
> the server MUST return membership events for events in the gap
> (between `since` and the start of the returned timeline), regardless
> as to whether or not they are redundant. This ensures that joins/leaves
> and profile changes which occur during the gap are not lost.
>
> Note that the default behaviour of `state` is to include all membership
> events, alongside other state, when lazy-loading is not enabled.

Points of confusion:
- I'm not sure what "being considered redundant by the server" refers to.
- Is this in the context of lazy-loading? I thought that involved a specific user-defined filter, rather than the server's discretion.
- The events which live the in the "gap" aren't redundant---they're just omitted---so I don't think it's talking about that.

- "membership events for events in the gap" sounds like "all membership events which are in the gap" to me; it wasn't obvious to me that events "have" or "own" a membership event.
- It apparently means "the most recent membership event for each sender of an event in the gap".
- Must we only return such membership events in the `gap`, or can they predate the gap? Put differently, can the server assume the client has a complete understanding of memberships at the `since` token, if it given? (Is this the meaning of redundant in the ~~final~~ penultimate sentence?)

- "Note that the default behaviour of `state` is to include all membership events".
- All historical events back to the beginning of time?
- What about events after the `since` token?
- Or just the most recent such event prior to the `since` token?
- For each currently joined member? For members who have left/been kicked or banned?

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 GET /_matrix/client/v3/sync section in the linked Matrix Client-Server API specification, especially the third paragraph and its explanation of lazy-loading and state. Resolve what “redundant” and “membership events for events in the gap” mean, then revise the wording so the relevant event history and default state behavior are unambiguous.

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
Needs clarification
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.