- 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>
75 lines
3.5 KiB
Markdown
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
|