Files
mtusi2026lab3/openspec/specs/pagination/spec.md
T
ricoromaandClaude Opus 5.5 af4bca08c9 feat: carry lab 2 over and add X-Instance-Id and idempotency keys
- carry the lab 2 solution over and plan lab 3 (PLAN.md, OpenSpec
  change instance-id-idempotency)
- rename the compose project to mtusi-lab3 and the image to :lab3
- add X-Instance-Id to every response and instance_id to every log
  record ([app] instance_id, hostname by default)
- require Idempotency-Key on POST messages: keys table in Postgres,
  key and message in one transaction, replay returns the same 201,
  another body gets 409, TTL from [idempotency] ttl_seconds
- send the key from student-tests, k6 scenarios and the skill driver;
  add idempotency, X-Instance-Id, key race and fault tests

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-08 19:42:36 +03:00

75 lines
3.5 KiB
Markdown

# 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