Files
mtusi2026lab5/openspec/specs/pagination/spec.md
T
ricoromaandClaude Opus 5.5 04f859282d chore: port lab 4 solution into the lab 5 skeleton
Source: mtusi2026lab4-safronov, solution/bvt2301-safronov, 2546deb.
Contracts, public tests and evidence of lab 4 are not carried over.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-31 03:09:12 +03:00

5.0 KiB
Raw Blame History

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.

Курсор, изменённый клиентом, SHALL давать 400 invalid_request, даже если он по-прежнему разбирается: ключ элемента другого типа или не в той записи, в которой его выдал сервер, версия другого значения или типа. Такой курсор MUST NOT давать 500 или страницу списка. Поля, которых сервер не знает, SHALL игнорироваться: новое необязательное поле не делает курсор недействительным для реплик прежней версии.

Scenario: Курсор другого чата

  • WHEN участник двух чатов передаёт в историю чата B курсор, полученный в чате A
  • THEN ответ 400

Scenario: Повреждённый курсор

  • WHEN cursor равен произвольной строке garbage
  • THEN ответ 400

Scenario: Изменённый курсор

  • WHEN клиент раскодирует курсор, выданный историей чата или списком чатов, и меняет в нём только одно: ключ последнего элемента — на [], {}, 123, false или на тот же id без дефисов или в верхнем регистре, либо версию — на true; затем кодирует обратно и передаёт в тот же список
  • THEN ответ 400 с code invalid_request, а тот же курсор, раскодированный и закодированный обратно без изменений или с добавленным незнакомым полем, даёт 200 и ту же страницу