diff --git a/01.md b/01.md index 6f26a3a8f7..1915a7d704 100644 --- a/01.md +++ b/01.md @@ -148,6 +148,12 @@ A `REQ` message may contain multiple filters. In this case, events that match an The `limit` property of a filter is only valid for the initial query and MUST be ignored afterwards. When `limit: n` is present it is assumed that the events returned in the initial query will be the last `n` events ordered by the `created_at`. Newer events should appear first, and in the case of ties the event with the lowest id (first in lexical order) should be first. Relays SHOULD use the `limit` value to guide how many events are returned in the initial response. Returning fewer events is acceptable, but returning (much) more should be avoided to prevent overwhelming clients. +### Pagination & limits + +Relays that impose a maximum `limit` MUST set it greater than the largest number of events sharing a single `created_at`, so no second can fill a page and stall pagination. A relay that violates this leaves clients no fix but to stall or drop events. + +To page backwards, clients MUST repeat requests with `until = oldest` (inclusive), deduplicating by `id` since the oldest second is re-fetched each round; paging is complete when a round yields no new events. Clients MUST detect a full page whose oldest and newest events share one `created_at`, and MUST then either advance with `until = oldest - 1`, dropping the unretrieved events, or abort. For paging, clients MUST NOT set `limit`; they MUST accept the relay maximum, since a smaller value reintroduces the stall. + ### From relay to client: sending events and notices Relays can send 5 types of messages, which must also be JSON arrays, according to the following patterns: