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

93 lines
5.0 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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 и ту же страницу