Files
mtusi2026lab6/openspec/specs/pagination/spec.md
T
ricoromaandClaude Opus 5.5 9cc6c0c7a6 chore: port lab 5 solution into the lab 6 skeleton
Source: mtusi2026lab5-safronov, solution/bvt2301-safronov, 046ec9e.
Contracts, public tests and evidence of lab 5 are not carried over.
The compose project, image and CI prefix are renamed to lab6; the first
broker start defect is recorded in KNOWN_ISSUES.md; PLAN.md outlines the
OpenSpec changes of lab 6.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-11 04:46:56 +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 и ту же страницу