Archive the load-balanced replicas and idempotent messages change

Grade 3 of lab 3 is closed: the stand runs two API replicas of one
compose service behind HAProxy as the only published entry point,
one token reaches both replicas by X-Instance-Id, stopping either
replica with scripts/stop-one.sh keeps writes going within 1.2-1.7 s
without errors or duplicates, eight concurrent posts with one key give
one message, and make test, the persistence scenario with
scripts/restart.sh, the failover scenario, lint, own tests, check,
validate and the lab 2 stack fault tests pass. The new
lab3-load-balancing and lab3-idempotent-messages specs are synced, and
the lab 1 history and operability specs and the lab 2 storage spec
carry their deltas.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
This commit is contained in:
Artyom
2026-10-28 11:53:26 +03:00
co-authored by Claude Opus 5.5
parent 957eabdfc3
commit 8d28d45d55
14 changed files with 208 additions and 16 deletions
@@ -1,2 +1,4 @@
schema: spec-driven
created: 2026-10-28
archived: 2026-10-28
lab: 3
@@ -5,14 +5,19 @@
## Requirements
### Requirement: Отправка сообщения
Сервис SHALL принимать `POST /api/v1/chats/{chat_id}/messages` от участника чата с телом `{"text":...}` и возвращать `201` с объектом `Message`. Отправитель SHALL выводиться из предъявленной идентификации; поле `sender_id` в теле запроса SHALL NOT приниматься. `text` SHALL содержать от 1 до 4000 Unicode code points и SHALL NOT состоять только из пробельных символов. `id` и `created_at` SHALL назначаться сервером.
Сервис SHALL принимать `POST /api/v1/chats/{chat_id}/messages` от участника чата с телом `{"text":...}` и обязательным заголовком `Idempotency-Key` и возвращать `201` с объектом `Message`. Отправитель SHALL выводиться из предъявленной идентификации; поле `sender_id` в теле запроса SHALL NOT приниматься. `text` SHALL содержать от 1 до 4000 Unicode code points и SHALL NOT состоять только из пробельных символов. `id` и `created_at` SHALL назначаться сервером. Правила ключа описаны в `lab3-idempotent-messages`.
#### Scenario: Сообщение отправлено
- **WHEN** участник отправляет `{"text":"Привет, мир 👋"}` в свой чат
- **WHEN** участник отправляет `{"text":"Привет, мир 👋"}` в свой чат с новым `Idempotency-Key`
- **THEN** ответ `201`, тело соответствует схеме `Message`
- **AND** `sender_id` равен идентификатору вызывающего, `chat_id` равен чату из пути, `text` побайтово совпадает с отправленным
#### Scenario: Ключ не передан
- **WHEN** участник отправляет корректное тело без заголовка `Idempotency-Key`
- **THEN** ответ `400` с кодом `invalid_request`
#### Scenario: Отправитель не берётся из тела запроса
- **WHEN** тело запроса содержит поле `sender_id`
@@ -31,13 +36,13 @@
#### Scenario: Посторонний пишет в чужой чат
- **WHEN** пользователь, не входящий в состав чата, отправляет корректное сообщение
- **WHEN** пользователь, не входящий в состав чата, отправляет корректное сообщение с ключом
- **THEN** ответ `404` с кодом `not_found`
- **AND** сообщение не сохраняется
#### Scenario: Доступ проверяется раньше содержимого
- **WHEN** посторонний отправляет в чужой чат тело, нарушающее схему
- **WHEN** посторонний отправляет в чужой чат с ключом тело с пустым `text`
- **THEN** ответ `404`, а не `400`
### Requirement: Порядок истории
@@ -34,18 +34,28 @@
### Requirement: Сквозной идентификатор запроса
Каждый ответ сервиса, включая ответы проб и ответы об ошибках, SHALL содержать непустой заголовок `X-Request-Id`. Если запрос принёс собственный `X-Request-Id`, сервис SHALL использовать его значение, иначе SHALL сгенерировать новое.
Каждый ответ сервиса, включая ответы проб, `204` выхода и ответы об ошибках (`404`/`405` неизвестного маршрута, `413`, `500` необработанного исключения), SHALL содержать непустые заголовки `X-Request-Id` и `X-Instance-Id`. Если запрос принёс собственный `X-Request-Id`, сервис SHALL использовать его значение, иначе SHALL сгенерировать новое. `X-Instance-Id` SHALL идентифицировать реплику (контейнер), а не отдельный процесс-воркер: значение SHALL быть одинаковым у всех процессов реплики, стабильным на всё время её жизни и SHALL совпадать с hostname контейнера, чтобы оператор мог сопоставить ответ с `docker ps`.
#### Scenario: Идентификатор присутствует в любом ответе
- **WHEN** выполняется любой запрос к сервису, успешный или ошибочный
- **THEN** ответ содержит непустой `X-Request-Id`
- **THEN** ответ содержит непустые `X-Request-Id` и `X-Instance-Id`
#### Scenario: Клиентский идентификатор сохраняется
- **WHEN** запрос содержит `X-Request-Id` с непустым значением
- **THEN** ответ содержит то же значение
#### Scenario: Один идентификатор на реплику
- **WHEN** реплика с несколькими процессами-воркерами обслуживает серию запросов
- **THEN** все её ответы несут одно и то же значение `X-Instance-Id`, равное hostname контейнера
#### Scenario: Необработанное исключение несёт идентификаторы
- **WHEN** обработка запроса завершается непредвиденным исключением
- **THEN** ответ `500` содержит `X-Request-Id` и `X-Instance-Id`
### Requirement: Единый формат ошибки
Ответ с кодом `4xx` или `5xx` SHALL иметь `Content-Type: application/json` и тело `{"error":{"code":...,"message":...,"request_id":...}}` без каких-либо дополнительных полей. `code` SHALL принимать значение из перечисления контракта, `request_id` SHALL совпадать со значением заголовка `X-Request-Id`. `message` SHALL быть непустым и SHALL NOT содержать stack trace, SQL, учётных данных, внутренних путей и сведений о существовании чужих объектов.
@@ -69,12 +79,12 @@
### Requirement: Корректное завершение по сигналу
По получении `SIGTERM` сервис SHALL перестать принимать новые соединения, дождаться завершения принятых запросов и завершить процесс не более чем за 10 секунд. Процесс сервера SHALL быть основным процессом контейнера и SHALL получать сигналы напрямую.
По получении `SIGTERM` сервис SHALL перестать принимать новые соединения, дождаться завершения принятых запросов и завершить процесс не более чем за 10 секунд; срок мягкой остановки сервера SHALL быть меньше `stop_grace_period` контейнера, чтобы контейнер не убивался по таймауту. Процесс сервера SHALL быть основным процессом контейнера и SHALL получать сигналы напрямую.
#### Scenario: Остановка укладывается в срок
- **WHEN** запущенному контейнеру послан `SIGTERM`
- **THEN** процесс завершается не позднее чем через 10 секунд
- **THEN** процесс завершается не позднее чем через 10 секунд и раньше `stop_grace_period`
- **AND** код завершения соответствует штатной остановке, а не убийству по таймауту
#### Scenario: Принятый запрос дорабатывается
@@ -112,8 +122,8 @@
#### Scenario: API доступен на опубликованном порту
- **WHEN** контейнер запущен с публикацией порта 8080
- **THEN** `GET /health/ready` с хоста отвечает `200`
- **WHEN** стенд поднят командой `make up`
- **THEN** `GET /health/ready` с хоста через опубликованный порт балансировщика отвечает `200`
#### Scenario: Процесс работает не от root
+16 -6
View File
@@ -19,12 +19,12 @@ PostgreSQL SHALL хранить пользователей, сессии, чат
### Requirement: Версионируемые миграции
Схема SHALL создаваться только миграциями: упорядоченными SQL-файлами, каждый из которых применяется в своей транзакции и записывается в журнал применённых версий. Миграции SHALL применяться одноразовым процессом до старта API, одновременный запуск двух процессов SHALL сериализоваться. Повторный запуск SHALL NOT менять схему и данные. Изменение текста уже применённой миграции SHALL останавливать запуск с ошибкой.
Схема SHALL создаваться только миграциями: упорядоченными SQL-файлами, каждый из которых применяется в своей транзакции и записывается в журнал применённых версий. Миграции SHALL применяться одним одноразовым процессом до старта реплик API, а не каждой репликой; одновременный запуск двух процессов SHALL сериализоваться. Повторный запуск SHALL NOT менять схему и данные. Изменение текста уже применённой миграции SHALL останавливать запуск с ошибкой. Новая миграция SHALL быть аддитивной: работающая предыдущая версия API SHALL продолжать работать на схеме после неё.
#### Scenario: Миграции с пустого volume
- **WHEN** стенд поднимается на пустом volume PostgreSQL
- **THEN** процесс миграций применяет все версии по порядку и завершается кодом 0, после чего стартует API
- **THEN** процесс миграций применяет все версии по порядку и завершается кодом 0, после чего стартуют реплики API
#### Scenario: Повторный запуск
@@ -36,6 +36,11 @@ PostgreSQL SHALL хранить пользователей, сессии, чат
- **WHEN** текст применённой миграции изменён и процесс миграций запущен
- **THEN** процесс завершается ненулевым кодом и схему не трогает
#### Scenario: Реплики не мигрируют схему
- **WHEN** стартует или перезапускается реплика API
- **THEN** она не применяет миграции; журнал версий меняет только процесс `migrate`
### Requirement: Атомарное создание чата
Создание чата SHALL записывать чат и всех его участников в одной транзакции. Если хотя бы одна запись нарушает ограничение, транзакция SHALL откатываться целиком: ни строки чата, ни строк участников не остаётся.
@@ -48,12 +53,12 @@ PostgreSQL SHALL хранить пользователей, сессии, чат
### Requirement: Данные и сессии переживают рестарт
Пользователи, чаты, участники, сообщения и ещё действующие сессии SHALL сохраняться при перезапуске API и всех хранилищ с сохранёнными volumes. После рестарта прежний токен SHALL работать до своего прежнего `expires_at`, а подтверждённое сообщение SHALL читаться побайтно тем же.
Пользователи, чаты, участники, сообщения, ключи идемпотентности и ещё действующие сессии SHALL сохраняться при перезапуске балансировщика, всех реплик API и всех хранилищ с сохранёнными volumes. После рестарта прежний токен SHALL работать до своего прежнего `expires_at`, а подтверждённое сообщение SHALL читаться побайтно тем же.
#### Scenario: Полный рестарт стенда
- **WHEN** выполняется `make test-persistence ACTION_SCRIPT=scripts/restart.sh`
- **THEN** hook перезапускает API и хранилища за ≤90 с с кодом 0, а тест печатает `PASS: persistence preserved confirmed data and existing session`
- **THEN** hook перезапускает балансировщик, API и хранилища за ≤90 с с кодом 0, а тест печатает `PASS: persistence preserved confirmed data and existing session`
#### Scenario: Логаут после рестарта
@@ -62,12 +67,17 @@ PostgreSQL SHALL хранить пользователей, сессии, чат
### Requirement: Воспроизводимый стенд из репозитория
Стенд SHALL подниматься из чистого clone командами репозитория: образы сторонних сервисов закреплены версией и digest, API собирается из исходников. Процессы сервисов SHALL работать не от root, у каждого долгоживущего сервиса SHALL быть healthcheck. Наружу SHALL публиковаться только API на `127.0.0.1:8080`. Учётные данные SHALL передаваться файлами compose secrets из каталога, исключённого из Git, и SHALL NOT появляться в Git, образе и журнале.
Стенд SHALL подниматься из чистого clone командами репозитория: образы сторонних сервисов закреплены версией и digest, API собирается из исходников. Процессы сервисов SHALL работать не от root, у каждого долгоживущего сервиса SHALL быть healthcheck и лимиты CPU и памяти. Наружу SHALL публиковаться только балансировщик на `127.0.0.1` (порт HTTP и порт статистики); PostgreSQL, Valkey и реплики API SHALL NOT публиковать порты. Учётные данные SHALL передаваться файлами compose secrets из каталога, исключённого из Git, только тем сервисам, которым они нужны, и SHALL NOT появляться в Git, образе и журнале.
#### Scenario: Подъём из чистого clone
- **WHEN** в чистом clone выполняются `make secrets` и `make up`
- **THEN** все сервисы становятся `healthy` или завершаются кодом 0, а `GET /health/ready` отвечает `200`
- **THEN** все сервисы становятся `healthy` или завершаются кодом 0, а `GET /health/ready` через балансировщик отвечает `200`
#### Scenario: Опубликован только балансировщик
- **WHEN** выполняется `docker compose ps --format '{{.Service}} {{.Ports}}'`
- **THEN** опубликованные порты есть только у сервиса `lb` и все они привязаны к `127.0.0.1`
#### Scenario: Секреты и volumes вне Git
@@ -0,0 +1,81 @@
# lab3-idempotent-messages Specification
## Purpose
Определяет идемпотентную отправку сообщения через `Idempotency-Key`: формат и область ключа, повтор и конфликт, срок хранения результата, атомарность записи и поведение при конкурентном повторе через разные реплики и при неопределённом исходе.
## Requirements
### Requirement: Обязательный ключ идемпотентности
`POST /api/v1/chats/{chat_id}/messages` SHALL требовать заголовок `Idempotency-Key` длиной 1–128 символов из `[A-Za-z0-9._:-]`. Отсутствующий или не соответствующий формату ключ SHALL давать `400` с кодом `invalid_request` в общем формате ошибки; сообщение при этом SHALL NOT сохраняться. Остальные endpoint SHALL NOT требовать ключ.
#### Scenario: Ключ отсутствует
- **WHEN** участник отправляет корректное сообщение без `Idempotency-Key`
- **THEN** ответ `400` с кодом `invalid_request`, история чата не меняется
#### Scenario: Ключ неверного формата
- **WHEN** `Idempotency-Key` пустой, длиннее 128 символов или содержит пробел, `/` или не-ASCII символ
- **THEN** ответ `400` с кодом `invalid_request`
### Requirement: Повтор возвращает исходный результат
Область ключа SHALL составлять пользователь сессии, метод и путь чата и сам ключ. Повтор с тем же ключом и семантически тем же JSON (порядок полей не важен) в течение `IDEMPOTENCY_TTL_SECONDS` (не меньше 86 400 с) SHALL возвращать `201` и тот же объект `Message` — те же `id`, `text` и строку `created_at` — без создания нового сообщения. Тот же ключ с другим JSON SHALL давать `409` с кодом `conflict`. Одинаковый ключ у разных пользователей или в разных чатах SHALL действовать независимо. После истечения срока ключ SHALL приниматься как новый.
#### Scenario: Повтор того же тела
- **WHEN** участник повторяет `POST` с тем же ключом и тем же `{"text":...}`
- **THEN** ответ `201`, тело равно телу первого ответа целиком, в истории одно такое сообщение
#### Scenario: Тот же ключ, другое тело
- **WHEN** участник повторяет `POST` с тем же ключом, но другим `text`
- **THEN** ответ `409` с кодом `conflict`, новое сообщение не создаётся
#### Scenario: Тот же ключ у другого пользователя
- **WHEN** другой участник того же чата отправляет сообщение с тем же значением ключа
- **THEN** ответ `201` с новым сообщением этого участника
#### Scenario: Тот же ключ в другом чате
- **WHEN** участник отправляет в другой свой чат сообщение с уже использованным ключом
- **THEN** ответ `201` с новым сообщением в этом чате
#### Scenario: Срок ключа истёк
- **WHEN** с момента первой отправки прошло больше `IDEMPOTENCY_TTL_SECONDS` и участник отправляет с тем же ключом другой текст
- **THEN** ответ `201` с новым сообщением, а не `409`
### Requirement: Повтор заново проверяет доступ
Повтор с известным ключом SHALL снова проверять сессию и членство в чате до выдачи сохранённого результата: отозванный или истёкший токен SHALL получать `401`, посторонний — `404`. Ответы `4xx` и `5xx` SHALL NOT сохраняться как результат ключа: после такого ответа повтор с тем же ключом обрабатывается как первая попытка.
#### Scenario: Повтор после выхода
- **WHEN** пользователь отправил сообщение, вышел и повторил запрос с тем же ключом и прежним токеном
- **THEN** ответ `401`
#### Scenario: Ошибка не занимает ключ
- **WHEN** участник отправил с ключом `K` пустой текст и получил `400`, затем отправил с ключом `K` корректный текст
- **THEN** второй ответ `201` с новым сообщением
#### Scenario: Посторонний с чужим ключом
- **WHEN** посторонний отправляет в чат запрос с ключом, уже использованным участником
- **THEN** ответ `404`, сохранённое сообщение не раскрывается
### Requirement: Атомарная и общая для реплик идемпотентность
Сообщение и запись ключа SHALL фиксироваться одной транзакцией PostgreSQL: либо сохраняются оба, либо ни одно. Одновременные запросы с одним ключом и одним телом, пришедшие на разные реплики, SHALL создавать ровно одно сообщение, и каждый из них SHALL получать `201` с одинаковым `Message`. Если исход первой попытки неизвестен клиенту (обрыв, таймаут, остановка реплики), повтор с тем же ключом SHALL возвращать уже сохранённое сообщение либо, если транзакция не была зафиксирована, создавать его ровно один раз.
#### Scenario: Конкурентный повтор через разные реплики
- **WHEN** 8 параллельных `POST` с одним ключом и одним телом отправлены через LB
- **THEN** все ответы `201` с одинаковым телом, ответы пришли от ≥2 реплик, в истории чата ровно одно такое сообщение
#### Scenario: Повтор после отказа реплики
- **WHEN** во время `make test-failover` запрос не получил ответа и повторён с тем же ключом и текстом
- **THEN** в истории нет дублей по `id` и `text`, а каждый подтверждённый ответ совпадает с записью истории байт-в-байт
@@ -0,0 +1,84 @@
# lab3-load-balancing Specification
## Purpose
Определяет развёртывание API несколькими взаимозаменяемыми репликами за единственной публичной точкой входа: что видно клиенту, как балансировщик выбирает и исключает реплики, какие запросы он вправе повторить и как оператор останавливает одну реплику и перезапускает стенд.
## Requirements
### Requirement: Единственная точка входа и не менее двух реплик
Стенд SHALL описываться одним `compose.yaml` и запускаться документированной командой. API SHALL работать не менее чем двумя репликами одного compose-service без `container_name`; их число SHALL задаваться `API_REPLICAS` (по умолчанию 2). Наружу SHALL публиковаться только балансировщик на `127.0.0.1`; порты реплик API SHALL NOT публиковаться. Все реплики SHALL использовать одну общую PostgreSQL и одно общее хранилище сессий.
#### Scenario: Стенд поднят
- **WHEN** выполняется `make up`, затем `docker compose ps`
- **THEN** работают ≥2 контейнера сервиса `api` в состоянии `healthy`, у них нет опубликованных портов, а единственные опубликованные порты принадлежат сервису `lb`
#### Scenario: Реплика недоступна в обход балансировщика
- **WHEN** с хоста выполняется запрос на порт 8080 контейнера реплики
- **THEN** соединение не устанавливается: реплика слушает только внутреннюю сеть
### Requirement: Разные реплики на одной сессии
Балансировщик SHALL распределять новые соединения по готовым репликам без привязки клиента (sticky session). Реплика SHALL NOT хранить в памяти процесса сессии, ключи идемпотентности и другое состояние, от которого зависит ответ другой реплики: токен, выданный через одну реплику, SHALL приниматься любой другой, а отзыв сессии SHALL действовать на всех репликах сразу.
#### Scenario: Один токен, несколько реплик
- **WHEN** клиент с одним Bearer-токеном выполняет 40 запросов `GET /api/v1/users/me`, каждый новым соединением через LB
- **THEN** все ответы `200`, а заголовок `X-Instance-Id` принимает не менее двух разных значений
#### Scenario: Выход действует на всех репликах
- **WHEN** пользователь выполнил `DELETE /api/v1/auth/sessions/current` через одну реплику
- **THEN** следующий запрос с этим токеном получает `401` независимо от того, какая реплика его обслужила
### Requirement: Готовность backend и обновление адресов
Балансировщик SHALL активно проверять каждую реплику запросом `GET /health/ready` и SHALL исключать из ротации реплику, которая не отвечает `200`. Адреса реплик SHALL обновляться через DNS без перезапуска балансировщика: остановленная реплика исчезает из ротации, запущенная или пересозданная появляется сама. Ответы, сформированные самим балансировщиком (`502`, `503`, `504`), SHALL иметь тело в общем формате ошибки с `request_id`, равным заголовку `X-Request-Id`.
#### Scenario: Реплика возвращается в ротацию
- **WHEN** остановленная реплика снова запущена
- **THEN** после успешных проверок готовности балансировщик снова направляет на неё запросы без перезапуска `lb`
#### Scenario: Нет ни одной готовой реплики
- **WHEN** все реплики API остановлены
- **THEN** запрос через LB получает `503` с телом `{"error":{"code":"unavailable",...}}`
### Requirement: Повтор запросов балансировщиком
Балансировщик SHALL повторять на другой реплике запрос, который не удалось отправить из-за отказа соединения. Повтор после того, как запрос мог быть обработан, SHALL допускаться только для `GET` и для `POST /api/v1/chats/{chat_id}/messages` с `Idempotency-Key`. Балансировщик SHALL NOT прозрачно повторять `POST /api/v1/users`, `POST /api/v1/chats` и `POST /api/v1/auth/sessions`.
#### Scenario: Создание чата не повторяется
- **WHEN** реплика оборвала соединение во время `POST /api/v1/chats`
- **THEN** клиент получает ошибку балансировщика, а не результат повторной отправки на другую реплику
### Requirement: Остановка одной реплики
Оператор SHALL иметь исполняемый хук `scripts/stop-one.sh`, который по переменной `TARGET_INSTANCE_ID` находит контейнер реплики с этим `X-Instance-Id`, останавливает только его с сохранением остальных сервисов и volumes, оставляет остановленным и завершается кодом 0 быстрее 10 секунд. Неизвестный идентификатор SHALL давать ненулевой код без остановки чего-либо. Не позднее 10 секунд от запуска хука SHALL продолжаться новые чтения и записи через LB, а подтверждённые сообщения SHALL оставаться доступными. Хук `scripts/restore.sh` SHALL возвращать остановленные реплики и ждать, пока балансировщик снова видит их готовыми.
#### Scenario: Отказ реплики под запросами
- **WHEN** выполняется `make test-failover ACTION_SCRIPT=scripts/stop-one.sh`
- **THEN** тест печатает `PASS: failover preserved confirmed data and existing session`, хук завершился быстрее 10 с, первая успешная запись после хука пришла не позже 10 с от его старта, остановленная реплика больше не отвечает, а `docker ps -a` показывает именно её контейнер в состоянии `exited`
#### Scenario: Вторая реплика
- **WHEN** после `scripts/restore.sh` тест повторяется и целью становится другая реплика
- **THEN** тест снова проходит
#### Scenario: Неизвестная реплика
- **WHEN** хук запущен с `TARGET_INSTANCE_ID`, которому не соответствует ни один контейнер `api`
- **THEN** хук завершается ненулевым кодом, и все контейнеры продолжают работать
### Requirement: Рестарт стенда
Хук `scripts/restart.sh` SHALL перезапускать балансировщик, все реплики API, PostgreSQL и Valkey с сохранением volumes, без удаления и повторного заполнения данных, и SHALL завершаться кодом 0 не позднее 90 секунд, когда стенд снова готов.
#### Scenario: Полный рестарт сохраняет сессию
- **WHEN** выполняется `make test-persistence ACTION_SCRIPT=scripts/restart.sh`
- **THEN** тест печатает `PASS: persistence preserved confirmed data and existing session`, а `StartedAt` контейнеров `lb`, `api`, `postgres` и `valkey` после прогона позже, чем до него