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

3.5 KiB

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