# pagination Specification ## Purpose Общие правила постраничных списков (чаты пользователя и история чата): параметр `limit`, непрозрачный keyset-курсор и `next_cursor`. Обход списка по курсору не теряет и не повторяет элементы. ## Requirements ### Requirement: Параметр limit `limit` SHALL быть целым числом от 1 до 100, по умолчанию 50. Другие значения SHALL давать 400 `invalid_request`. #### Scenario: Ноль - **WHEN** клиент запрашивает список с `limit=0` - **THEN** ответ 400 #### Scenario: Больше максимума и не число - **WHEN** `limit=101` или `limit=abc` - **THEN** ответ 400 #### Scenario: По умолчанию - **WHEN** `limit` не передан и в списке 60 элементов - **THEN** страница содержит 50 элементов ### Requirement: Форма страницы и next_cursor Ответ списка SHALL иметь вид `{"items": [...], "next_cursor": ...}`. `next_cursor` SHALL быть непустой строкой, если на момент чтения после последнего элемента страницы есть ещё элементы, и null — если нет, в том числе когда страница содержит ровно `limit` элементов и больше ничего нет. #### Scenario: Последняя полная страница - **WHEN** в списке ровно 2 элемента и клиент запрашивает `limit=2` - **THEN** страница содержит оба элемента и `next_cursor` null ### Requirement: Порядок и продолжение по курсору Элементы SHALL упорядочиваться по `(created_at, id)` по возрастанию, где `id` сравнивается как значение UUID. Запрос с `cursor` SHALL возвращать элементы строго после последнего элемента предыдущей страницы. При обходе неизменного списка элементы MUST NOT теряться и повторяться. `limit` SHALL разрешено менять между страницами. #### Scenario: Полный обход - **WHEN** клиент обходит список из 7 элементов страницами по 3, затем по 2 - **THEN** объединение страниц содержит все 7 элементов ровно по одному разу в правильном порядке ### Requirement: Курсор непрозрачен и привязан к списку Курсор SHALL быть непрозрачной для клиента строкой. Курсор, полученный для другого чата, для списка чатов вместо истории или наоборот, либо повреждённая строка SHALL давать 400 `invalid_request`. #### Scenario: Курсор другого чата - **WHEN** участник двух чатов передаёт в историю чата B курсор, полученный в чате A - **THEN** ответ 400 #### Scenario: Повреждённый курсор - **WHEN** `cursor` равен произвольной строке `garbage` - **THEN** ответ 400