- 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>
7.1 KiB
Spec Delta
ADDED Requirements
Requirement: Хранение в PostgreSQL
Пользователи, чаты, участники чатов и сообщения SHALL храниться в PostgreSQL, он — источник истины. Сервис MUST NOT хранить эти данные в памяти процесса, файлах или SQLite. Подтверждённая запись (ответ 201) SHALL быть зафиксирована в БД до ответа и видна следующему чтению.
Scenario: Созданное видно сразу
- WHEN клиент создал пользователя и следующим запросом использует
его
idвX-User-Id - THEN пользователь найден
Requirement: Данные переживают рестарт
После перезапуска сервиса и PostgreSQL с сохранённым volume все ранее подтверждённые пользователи, чаты, участники и сообщения SHALL быть доступны в прежнем виде.
Scenario: Прежний пользователь после рестарта
- WHEN стенд перезапущен
scripts/restart.sh, и клиент используетX-User-Id, созданный до рестарта - THEN ответ 200, а история чата этого пользователя содержит те же сообщения в том же порядке
Requirement: Целостность данных в БД
Ограничения SHALL проверяться самой БД, а не только сервисом:
уникальность username, существование пользователей и чатов, на
которые ссылаются участники и сообщения, уникальность участника в
чате, членство отправителя в чате сообщения. Порядок member_ids,
заданный при создании чата, SHALL сохраняться.
Scenario: Порядок участников
- WHEN чат создан с
member_idsв порядке[bob, alice] - THEN
GETэтого чата и список чатов возвращаютmember_idsв том же порядке, в том числе после рестарта стенда
Requirement: Составная операция в одной транзакции
Создание чата вместе с участниками SHALL выполняться одной транзакцией: при ошибке на любом шаге в БД MUST NOT остаться ни чата, ни части его участников.
Scenario: Сбой при добавлении участников
- WHEN чат уже записан в транзакции, а запись участников завершается ошибкой
- THEN транзакция откатывается, чата нет ни в
GETпо егоid, ни в списках чатов участников
Requirement: Недоступность PostgreSQL
Если PostgreSQL недоступен или не ответил за отведённое время,
запрос SHALL завершаться ответом 503 с code unavailable в формате
ошибки, а не 500 и не зависанием. Частично выполненная операция MUST
NOT фиксироваться. Когда PostgreSQL снова доступен, сервис SHALL
обслуживать запросы без перезапуска.
Scenario: БД остановлена
- WHEN PostgreSQL остановлен, и клиент отправляет сообщение
- THEN ответ 503
unavailableбез деталей вmessage
Scenario: БД вернулась
- WHEN PostgreSQL остановлен, затем снова запущен, а сервис не перезапускался
- THEN следующие запросы после готовности БД обслуживаются штатно
Requirement: Ограниченный пул соединений и таймауты
Число соединений сервиса с PostgreSQL SHALL быть ограничено настройкой.
Ожидание свободного соединения, подключение и выполнение запроса SHALL
иметь таймауты из настроек. Истёкший таймаут SHALL давать 503
unavailable.
Scenario: Соединения исчерпаны
- WHEN все соединения пула заняты дольше таймаута ожидания
- THEN новый запрос получает 503
unavailableне позже этого таймаута, а не ждёт бесконечно
MODIFIED Requirements
Requirement: Параллельные запросы не повреждают состояние
Параллельные запросы MUST NOT терять, дублировать или повреждать
записи. Уникальность username SHALL обеспечиваться ограничением БД,
а не проверкой перед вставкой, поэтому одновременная регистрация
одного имени создаёт ровно одного пользователя.
Scenario: 100 сообщений от 10 клиентов
- WHEN 10 клиентов одновременно отправляют по 10 сообщений в один чат
- THEN получено 100 ответов 201, а полный обход истории возвращает
ровно 100 сообщений с уникальными
id
Scenario: Гонка за username
- WHEN несколько клиентов одновременно регистрируют одинаковый
username - THEN создан ровно один пользователь
REMOVED Requirements
Requirement: Состояние только в памяти одного процесса
Reason: лаба 2 требует PostgreSQL как источник истины; память процесса больше не хранит данные. Migration: требование «Хранение в PostgreSQL». Сценарий «Созданное видно сразу» перенесён туда без изменений.
Requirement: Потеря состояния при рестарте
Reason: на лабе 2 подтверждённые данные обязаны переживать рестарт; пустое состояние после рестарта теперь дефект. Migration: требование «Данные переживают рестарт», сценарий «Прежний пользователь после рестарта» теперь ждёт 200.