The limited flag in Timeline in /sync response needs clarification

[erikjohnston]

Link to /sync spec.

It currently says:

True if the number of events returned was limited by the limit on the filter.

However, there are also the following cases:

• When newly joining a room. Though this arguably is covered by the above, we should explicitly state it.
• When there is a gap in the timeline. See /sync doesn't inform clients when there is a gap in the timeline synapse#16463

Generally, limited means that there is more events the client can request with /messages

[olivia-fl]

Conduit/grapevine/conduwuit currently set limited: true when returning a response with a gap. I interpret a gapped sync response as a consequence of this text from the filter spec:

The maximum number of events to return, must be an integer greater than 0.

Servers should apply a default value, and impose a maximum value to avoid resource exhaustion.

In this interpretation, a gap in the timeline occurs because the server has imposed a maximum or default value on the filter limit that is lower than the total number of events in the request's sync window. This is just a special case of the response being limited by the limit field in the filter, and so we set limited: true.