Files
mtusi2026lab4/openspec/specs/pagination/spec.md
T
ricoromaandClaude Opus 5.5 5d5d8f9d2a chore: carry lab 3 over
- carry the lab 3 solution over from mtusi2026lab3-safronov
  (solution/bvt2301-safronov, ce89eba): src, migrations, student-tests,
  bench, openspec, .claude, infra/haproxy and infra/valkey, own scripts,
  Dockerfile, compose, pyproject and uv lock
- merge Makefile, .gitignore and .dockerignore (the lab 3 versions only
  add lines to the skeleton, which is the same in lab 4) and
  .env.example (lab 4 skeleton names listed in the header)
- rename the compose project to mtusi-lab4 and the image to :lab4 so
  the stand does not reuse the lab 3 containers and volumes
- update AGENTS.md for lab 4: current lab, origin commit, contract and
  test files of the new skeleton

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-20 17:32:33 +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 и ту же страницу