Propose load-balanced replicas and idempotent messages as an openspec change
Plan the grade 3 cycle of lab 3 on top of the carried-over lab 2 solution: run the API as several replicas of one compose service behind HAProxy as the only published entry point, stamp every API response with X-Instance-Id taken from the container hostname, require Idempotency-Key on message posts and keep the key and the message in one PostgreSQL transaction, and add explicit stop-one, restart and restore hooks. The design fixes the balancer settings and retry policy, the idempotency table, the lookup order under the chat row lock, the request fingerprint and the shutdown budget. Delta specs add the lab3-load-balancing and lab3-idempotent-messages capabilities and modify message posting, request identification, shutdown, container delivery, migrations, restart and the reproducible stand. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
This commit is contained in:
co-authored by
Claude Opus 5.5
parent
416ce4f9db
commit
9db7a24362
@@ -0,0 +1,2 @@
|
||||
schema: spec-driven
|
||||
created: 2026-10-28
|
||||
@@ -0,0 +1,102 @@
|
||||
## Context
|
||||
|
||||
Мотивация — в `proposal.md`. Решение лабы 2 уже не держит в процессе ничего, от чего зависит корректность: пользователи, сессии, чаты и сообщения лежат в PostgreSQL, кэш сессий — общий Valkey с отметками отзыва, курсор подписан общим секретом из `secrets/cursor_secret`, порядок истории держит блокировка строки чата, а не часы процесса. Шина событий в памяти обслуживает только журнал аудита. Поэтому несколько реплик — это в основном стенд и два новых правила контракта: `X-Instance-Id` и `Idempotency-Key`. Инфраструктурные заготовки (HAProxy, хуки, зонд) проверены отдельно на заглушке и встраиваются, а не пишутся заново.
|
||||
|
||||
## Goals / Non-Goals
|
||||
|
||||
**Goals:**
|
||||
- Любая реплика взаимозаменяема: ответ не зависит от того, какая реплика обслужила предыдущий запрос клиента.
|
||||
- Остановка реплики видна оператору (`docker ps -a` ↔ `X-Instance-Id`) и не прерывает запись дольше 10 с.
|
||||
- Идемпотентность держит одна транзакция PostgreSQL, без второго хранилища и без маркеров «в обработке».
|
||||
|
||||
**Non-Goals:**
|
||||
- Замер времени обнаружения, поочерёдный отказ под нагрузкой, rolling update — уровень «4».
|
||||
- Очистка истёкших ключей фоновым заданием (см. Risks).
|
||||
|
||||
## Decisions
|
||||
|
||||
### D1. Compose + HAProxy, один сервис `api` с репликами
|
||||
|
||||
Один compose-service `api` с `deploy.replicas: ${API_REPLICAS:-2}`, без `container_name`, `hostname` и `ports`; перед ним `lb` — HAProxy 3.2.26 LTS по digest, единственный сервис с опубликованными портами `127.0.0.1:${LB_HTTP_PORT:-8080}` и `127.0.0.1:${LB_STATS_PORT:-8404}` (статистика только на чтение, `/healthz` для healthcheck LB). Сети: `edge` (LB) и `backend` с `internal: true` (LB, `api`, `migrate`, `postgres`, `valkey`). Каждому сервису — `deploy.resources.limits`; `api` — `read_only` с `tmpfs /tmp` для heartbeat gunicorn.
|
||||
|
||||
Что получаем: масштаб одним параметром (нужен треку «5»), активные проверки готовности с явными `inter/fall/rise`, статистика `qcur/qtime` и DNS-обнаружение без `docker.sock`. Чего стоит: ещё один процесс на пути запроса. Отвергнуто: Nginx OSS (только пассивные проверки, DNS резолвится на старте), Traefik (нужен `docker.sock`), Swarm (вне Out of scope лабы), отдельные сервисы `api-1/api-2` (ломают масштабирование одного сервиса).
|
||||
|
||||
### D2. Конфигурация балансировщика
|
||||
|
||||
- `server-template api 8 api:8080` + `resolvers docker` (`127.0.0.11`, `hold` 2 с), `init-addr none`: остановленный контейнер пропадает из DNS, слот уходит в `MAINT`, запущенный возвращается сам.
|
||||
- `balance roundrobin`, без `stick`: новое соединение — следующая реплика; тест требует ≥2 `X-Instance-Id` на одном токене.
|
||||
- `option httpchk GET /health/ready`, `inter 1s fastinter 500ms fall 2 rise 2`, `timeout check 1s`.
|
||||
- Повторы: `retries 2`, `option redispatch 1`, `retry-on conn-failure empty-response`; `http-request disable-l7-retry` для всего, кроме `GET` и `POST …/messages` с `Idempotency-Key`. Отказ соединения повторяется всегда (запрос не ушёл), обрыв после отправки — только для безопасных к повтору запросов; `POST /users`, `/chats` и вход не повторяются, как требует `contracts/README.md`.
|
||||
- `option http-server-close`: соединение LB→API не переиспользуется, поэтому при остановке реплики нет гонки за простаивающее keep-alive-соединение.
|
||||
- `X-Request-Id`: непустой входящий до 200 символов пробрасывается, иначе LB генерирует uuid4; приложение эхо-возвращает его. Ответы LB `502/503/504` — JSON формата контракта с тем же `request_id`.
|
||||
- Таймауты: `connect 500ms` < `server 10s` > `REQUEST_TIMEOUT_SECONDS=8` приложения > `statement_timeout` 2 с; `queue 3s`, `maxconn` на сервер `API_SERVER_MAXCONN` (64). Мягкая остановка LB — `SIGUSR1` с `hard-stop-after 5s`.
|
||||
|
||||
### D3. `X-Instance-Id` — hostname контейнера, платформа
|
||||
|
||||
`PlatformSettings.instance_id` по умолчанию берётся из `socket.gethostname()` один раз при сборке приложения; в контейнере это короткий ID, совпадающий с `docker ps` и `.Config.Hostname`. Конвейер `RequestPipeline` ставит заголовок рядом с `X-Request-Id` на каждый ответ, который проходит через него (включая `401`, `413`, `503` по таймауту и `404/405` фреймворка); обработчик необработанных исключений ставит его сам, потому что `500` формирует внешний `ServerErrorMiddleware`, минуя конвейер. Это платформа (`shared/entrypoints`), без доменных понятий.
|
||||
|
||||
Отвергнуто: pid или uuid процесса — при `WEB_CONCURRENCY=2` одна реплика выглядела бы двумя, а `stop-one.sh` не нашёл бы контейнер; `INSTANCE_ID` в compose — одинаков у всех реплик сервиса. Непрозрачный alias вместо hostname — лаба 7.
|
||||
|
||||
### D4. Идемпотентность в зоне `messaging`, одна транзакция
|
||||
|
||||
Миграция `0002_idempotency_keys.sql` (аддитивная, код лабы 2 её не замечает):
|
||||
|
||||
```sql
|
||||
CREATE TABLE idempotency_keys (
|
||||
chat_id uuid NOT NULL,
|
||||
user_id uuid NOT NULL,
|
||||
key text NOT NULL CHECK (key ~ '^[A-Za-z0-9._:-]{1,128}$'),
|
||||
fingerprint bytea NOT NULL CHECK (octet_length(fingerprint) = 32),
|
||||
message_id uuid NOT NULL REFERENCES messages (id) ON DELETE CASCADE,
|
||||
created_at timestamptz NOT NULL,
|
||||
PRIMARY KEY (chat_id, user_id, key),
|
||||
FOREIGN KEY (chat_id, user_id) REFERENCES chat_members (chat_id, user_id)
|
||||
);
|
||||
```
|
||||
|
||||
Область «пользователь + метод + путь + ключ» сводится к `(chat_id, user_id, key)`: ключ бывает только у `POST /api/v1/chats/{chat_id}/messages`. Внешний ключ на `chat_members` держит связь внутри таблиц зоны `messaging` — SQL зоны по-прежнему не читает `users`.
|
||||
|
||||
`PostMessageHandler` в одной транзакции UoW:
|
||||
|
||||
1. `SELECT … FROM chats WHERE id = $1 FOR UPDATE` (уже есть ради порядка истории) → `404`, если чата нет;
|
||||
2. `chat.post(...)` — членство (`404`), затем текст (`400`), в памяти, без записи;
|
||||
3. поиск квитанции `SELECT k.fingerprint, m.* FROM idempotency_keys k JOIN messages m ON m.id = k.message_id WHERE (k.chat_id, k.user_id, k.key) = ($1, $2, $3) AND k.created_at > $4` по первичному ключу; `$4 = now − IDEMPOTENCY_TTL_SECONDS`;
|
||||
4. квитанция есть: отпечаток совпал → вернуть сохранённое сообщение (транзакция откатывается, события не публикуются), иначе `409 conflict`;
|
||||
5. квитанции нет → один оператор: `INSERT messages` + `INSERT idempotency_keys … ON CONFLICT (chat_id, user_id, key) DO UPDATE` (перезапись истёкшего ключа) + `UPDATE chats.last_message_at`; затем `COMMIT`.
|
||||
|
||||
Конкурентные повторы с одним ключом всегда идут в один чат, поэтому ждут на блокировке строки чата; после `COMMIT` первого следующий оператор в `READ COMMITTED` видит квитанцию и отдаёт то же сообщение. Перезапись в шаге 5 безопасна: под той же блокировкой уже проверено, что живой квитанции нет. Если транзакция откатилась (обрыв, `SIGTERM`, таймаут), не остаётся ни сообщения, ни ключа — повтор создаёт сообщение один раз. Ответы `4xx` и `5xx` ничего не пишут.
|
||||
|
||||
Отпечаток — SHA-256 канонического JSON распарсенной модели `CreateMessageRequest` (`model_dump_json`: порядок полей задаёт модель, а не клиент); считается на границе HTTP и передаётся в команду `PostMessage` вместе с ключом. Повтор отдаёт сообщение тем же `MessageOut`, а `created_at` хранится с микросекундами, поэтому тело совпадает строкой. Доменный объект `Receipt` (ключ, отпечаток, сообщение) решает «повтор или конфликт» методом `replay`; ошибка `IdempotencyConflict` зоны отображается в `409 conflict`. Ключ валидируется заголовком FastAPI (`pattern`, 1–128) → `400` через существующий обработчик ошибок валидации.
|
||||
|
||||
Что получаем: атомарность без второго хранилища и без «залипших» ключей. Чего стоит: строка ключа на каждое сообщение и чтение по первичному ключу под уже взятой блокировкой. Отвергнуто: `SET NX` в Valkey (не атомарен с `COMMIT` PostgreSQL), отдельно закоммиченный маркер «processing» (после гибели реплики повтор получал бы `409`), `INSERT … ON CONFLICT DO NOTHING` без блокировки чата (её всё равно требует порядок истории).
|
||||
|
||||
`LockNotAvailableError` (`lock_timeout` при очереди на строку чата) добавляется к ошибкам, которые пул превращает в `503 unavailable`: это транзиентный отказ, а не `500`, и он не сохраняется под ключом.
|
||||
|
||||
### D5. Миграции и старт реплик
|
||||
|
||||
`migrate` — одноразовый сервис на образе приложения под `pg_advisory_lock`; реплики зависят от него `service_completed_successfully` и сами схему не трогают. Повторный запуск (`restart.sh`, rolling update) безопасен: журнал версий и контрольные суммы.
|
||||
|
||||
### D6. Остановка, готовность и процессы
|
||||
|
||||
`SHUTDOWN_TIMEOUT_SECONDS=5` (gunicorn `graceful_timeout` и uvicorn `timeout_graceful_shutdown`) < `stop_grace_period: 8s`; хук останавливает с `docker stop -t 6`, худший случай хука ≈7 с < 10 с. По `SIGTERM` gunicorn закрывает listener: LB получает отказ соединения и повторяет запрос на соседней реплике. `WEB_CONCURRENCY=2` на реплику с лимитом `cpus: 1`, `512m`; пул 8 соединений на воркер: 2 реплики × 2 × 8 = 32 < `max_connections=200`.
|
||||
|
||||
### D7. Хуки и зонд
|
||||
|
||||
- `scripts/stop-one.sh`: среди `docker compose ps -q api` ищет контейнер с `.Config.Hostname == TARGET_INSTANCE_ID`, `docker stop -t 6`; неизвестный ID → код 3. Запускается тестом без shell, поэтому shebang и `chmod +x`.
|
||||
- `scripts/restart.sh`: `stop lb api` → `restart postgres valkey` → `up -d --wait` (заодно повторно `migrate`), volumes не трогаются.
|
||||
- `scripts/restore.sh`: `up -d --no-deps --no-recreate --wait api`, затем `scripts/lb-wait.sh` ждёт, пока статистика LB покажет все реплики `UP`; без этого следующий тест увидит одну реплику.
|
||||
- `scripts/probe.py check`: 40 `GET /users/me` одним токеном и 8 параллельных `POST` с одним ключом; stdlib, синтаксис Python 3.9.
|
||||
|
||||
`api-shortttl` лабы 2 публиковал порт API в обход LB и удаляется; истечение сессии проверяется in-process тестом с коротким TTL.
|
||||
|
||||
## Risks / Trade-offs
|
||||
|
||||
- [Таблица ключей растёт вместе с историей] → строка на сообщение (~100 байт против сообщения до 16 КБ), истёкшие ключи перезаписываются при повторном использовании; фоновая очистка — следующий шаг, описан в `REPORT.md`.
|
||||
- [Повтор берёт блокировку строки чата] → повтор так же дёшев, как запись; горячий чат сериализуется и без идемпотентности.
|
||||
- [`X-Instance-Id` раскрывает короткий ID контейнера] → допустимо до лабы 7, где появится alias.
|
||||
- [Цель failover-теста выбирается round robin] → для второй реплики тест повторяется после `restore.sh`; лишний запрос через LB сдвигает очередь.
|
||||
- [LB — единственная точка отказа, как и PostgreSQL] → честно в ограничениях отчёта; HA LB и БД — Out of scope.
|
||||
|
||||
## Migration Plan
|
||||
|
||||
`0002` аддитивна: сначала `migrate`, затем реплики с новым кодом; откат кода не требует отката схемы. Старый API лабы 2 работает на новой схеме, не создавая ключей.
|
||||
@@ -0,0 +1,33 @@
|
||||
## Why
|
||||
|
||||
Решение лабы 2 — один контейнер API с опубликованным портом. Рубрика «3» `README.md` требует ≥2 взаимозаменяемых реплик за одной точкой входа, разные реплики на одном токене, запись ≤10 с после остановки любой реплики и повтор сообщения без дубля; контракт 1.3.0 вводит `X-Instance-Id` и `Idempotency-Key`. Изменение закрывает уровень «3» и строки 3.1–3.5 `REPORT.md`.
|
||||
|
||||
## What Changes
|
||||
|
||||
- Каждый ответ API несёт `X-Instance-Id` — hostname контейнера, один на все воркеры.
|
||||
- `POST /api/v1/chats/{chat_id}/messages` требует `Idempotency-Key` (`^[A-Za-z0-9._:-]{1,128}$`, иначе `400`). Повтор того же JSON тем же пользователем в том же чате в течение `IDEMPOTENCY_TTL_SECONDS` (≥24 ч) возвращает исходный `201` и тот же `Message`, другой JSON — `409`. Ключ и сообщение — одна транзакция PostgreSQL; `4xx` и `5xx` не сохраняются.
|
||||
- Новая аддитивная миграция `0002_idempotency_keys.sql`.
|
||||
- Стенд: HAProxy 3.2 LTS (`lb`) — единственный опубликованный порт; `api` с `deploy.replicas: ${API_REPLICAS:-2}` без портов; проверка `GET /health/ready`, Docker DNS, round robin без sticky; `api-shortttl` с портом в обход LB удаляется.
|
||||
- Хуки `scripts/stop-one.sh`, `scripts/restart.sh`, `scripts/restore.sh`, `scripts/lb-wait.sh` и зонд `scripts/probe.py check`.
|
||||
|
||||
## Capabilities
|
||||
|
||||
### New Capabilities
|
||||
- `lab3-load-balancing`: единственная точка входа, ≥2 реплики без локального состояния, балансировка без sticky, проверка готовности и DNS-обновление backend, политика повторов LB, хуки остановки реплики и рестарта стенда.
|
||||
- `lab3-idempotent-messages`: обязательный ключ, область, replay/`409`/`400`, TTL, атомарность, конкурентный повтор, повтор после неопределённого исхода.
|
||||
|
||||
### Modified Capabilities
|
||||
- `lab1-messenger-history`: «Отправка сообщения» требует `Idempotency-Key`.
|
||||
- `lab1-service-operability`: «Сквозной идентификатор запроса» дополняется `X-Instance-Id`; «Корректное завершение по сигналу» — срок внутри `stop_grace_period`; «Контейнерная поставка» — API доступен через LB.
|
||||
- `lab2-persistent-storage`: «Воспроизводимый стенд» — наружу только LB, реплики без портов; «Версионируемые миграции» — аддитивные и совместимые с работающей версией; «Данные и сессии переживают рестарт» — рестарт включает LB.
|
||||
|
||||
## Impact
|
||||
|
||||
- Код: платформа (`X-Instance-Id`), зона `messaging` (идемпотентная отправка), миграция `0002`.
|
||||
- Стенд: `compose.yaml`, `infra/haproxy/haproxy.cfg`, `scripts/`, `Makefile`, `.env.example`, `pyproject.toml` (ruff для `scripts/*.py`), CI.
|
||||
- Тесты: заголовки, идемпотентность, гонка ключа в реальном PostgreSQL.
|
||||
- Отчёт: строки 3.1–3.5 и переноса lab2 в `REPORT.md`, `evidence/`.
|
||||
|
||||
## Non-goals
|
||||
|
||||
Время обнаружения, поочерёдный отказ под нагрузкой, rolling update и измерения лимитов — уровень «4»; серии 1/2/4 реплик — трек «5»; оба — следующие изменения. Из Out of scope не появляется ничего: Swarm, HA PostgreSQL и LB, непрозрачный alias реплики (лаба 7), вложения (лаба 4).
|
||||
@@ -0,0 +1,43 @@
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: Отправка сообщения
|
||||
|
||||
Сервис 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":"Привет, мир 👋"}` в свой чат с новым `Idempotency-Key`
|
||||
- **THEN** ответ `201`, тело соответствует схеме `Message`
|
||||
- **AND** `sender_id` равен идентификатору вызывающего, `chat_id` равен чату из пути, `text` побайтово совпадает с отправленным
|
||||
|
||||
#### Scenario: Ключ не передан
|
||||
|
||||
- **WHEN** участник отправляет корректное тело без заголовка `Idempotency-Key`
|
||||
- **THEN** ответ `400` с кодом `invalid_request`
|
||||
|
||||
#### Scenario: Отправитель не берётся из тела запроса
|
||||
|
||||
- **WHEN** тело запроса содержит поле `sender_id`
|
||||
- **THEN** ответ `400` с кодом `invalid_request`
|
||||
|
||||
#### Scenario: Пустой или пробельный текст
|
||||
|
||||
- **WHEN** тело содержит `{"text":""}` или `{"text":" "}`
|
||||
- **THEN** ответ `400` с кодом `invalid_request`
|
||||
|
||||
#### Scenario: Текст длиннее предела
|
||||
|
||||
- **WHEN** `text` содержит более 4000 Unicode code points
|
||||
- **THEN** ответ `400` с кодом `invalid_request`
|
||||
- **AND** длина считается в code points, а не в байтах UTF-8
|
||||
|
||||
#### Scenario: Посторонний пишет в чужой чат
|
||||
|
||||
- **WHEN** пользователь, не входящий в состав чата, отправляет корректное сообщение с ключом
|
||||
- **THEN** ответ `404` с кодом `not_found`
|
||||
- **AND** сообщение не сохраняется
|
||||
|
||||
#### Scenario: Доступ проверяется раньше содержимого
|
||||
|
||||
- **WHEN** посторонний отправляет в чужой чат с ключом тело с пустым `text`
|
||||
- **THEN** ответ `404`, а не `400`
|
||||
+64
@@ -0,0 +1,64 @@
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: Сквозной идентификатор запроса
|
||||
|
||||
Каждый ответ сервиса, включая ответы проб, `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` и `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: Корректное завершение по сигналу
|
||||
|
||||
По получении `SIGTERM` сервис SHALL перестать принимать новые соединения, дождаться завершения принятых запросов и завершить процесс не более чем за 10 секунд; срок мягкой остановки сервера SHALL быть меньше `stop_grace_period` контейнера, чтобы контейнер не убивался по таймауту. Процесс сервера SHALL быть основным процессом контейнера и SHALL получать сигналы напрямую.
|
||||
|
||||
#### Scenario: Остановка укладывается в срок
|
||||
|
||||
- **WHEN** запущенному контейнеру послан `SIGTERM`
|
||||
- **THEN** процесс завершается не позднее чем через 10 секунд и раньше `stop_grace_period`
|
||||
- **AND** код завершения соответствует штатной остановке, а не убийству по таймауту
|
||||
|
||||
#### Scenario: Принятый запрос дорабатывается
|
||||
|
||||
- **WHEN** `SIGTERM` приходит во время обработки принятого запроса
|
||||
- **THEN** этот запрос получает ответ до завершения процесса
|
||||
|
||||
### Requirement: Контейнерная поставка
|
||||
|
||||
Сервис SHALL собираться из исходников в образ, слушать `0.0.0.0:8080` и читать конфигурацию из переменных окружения. Контейнер SHALL выполняться от непривилегированного пользователя, SHALL фиксировать версию базового образа и версии зависимостей и SHALL объявлять healthcheck, опирающийся на пробу жизни.
|
||||
|
||||
#### Scenario: Образ собирается из чистого clone
|
||||
|
||||
- **WHEN** выполняется сборка образа в свежей копии репозитория
|
||||
- **THEN** сборка завершается успешно без обращения к артефактам вне репозитория
|
||||
|
||||
#### Scenario: API доступен на опубликованном порту
|
||||
|
||||
- **WHEN** стенд поднят командой `make up`
|
||||
- **THEN** `GET /health/ready` с хоста через опубликованный порт балансировщика отвечает `200`
|
||||
|
||||
#### Scenario: Процесс работает не от root
|
||||
|
||||
- **WHEN** в работающем контейнере проверяется эффективный пользователь процесса сервера
|
||||
- **THEN** это не `root`, и идентификатор пользователя не равен 0
|
||||
|
||||
#### Scenario: Healthcheck отражает состояние сервиса
|
||||
|
||||
- **WHEN** контейнер запущен и сервис готов
|
||||
- **THEN** статус healthcheck контейнера становится `healthy`
|
||||
+58
@@ -0,0 +1,58 @@
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: Версионируемые миграции
|
||||
|
||||
Схема SHALL создаваться только миграциями: упорядоченными SQL-файлами, каждый из которых применяется в своей транзакции и записывается в журнал применённых версий. Миграции SHALL применяться одним одноразовым процессом до старта реплик API, а не каждой репликой; одновременный запуск двух процессов SHALL сериализоваться. Повторный запуск SHALL NOT менять схему и данные. Изменение текста уже применённой миграции SHALL останавливать запуск с ошибкой. Новая миграция SHALL быть аддитивной: работающая предыдущая версия API SHALL продолжать работать на схеме после неё.
|
||||
|
||||
#### Scenario: Миграции с пустого volume
|
||||
|
||||
- **WHEN** стенд поднимается на пустом volume PostgreSQL
|
||||
- **THEN** процесс миграций применяет все версии по порядку и завершается кодом 0, после чего стартуют реплики API
|
||||
|
||||
#### Scenario: Повторный запуск
|
||||
|
||||
- **WHEN** процесс миграций запускается повторно на той же БД
|
||||
- **THEN** он завершается кодом 0, журнал версий и число строк во всех таблицах не меняются
|
||||
|
||||
#### Scenario: Изменённая миграция
|
||||
|
||||
- **WHEN** текст применённой миграции изменён и процесс миграций запущен
|
||||
- **THEN** процесс завершается ненулевым кодом и схему не трогает
|
||||
|
||||
#### Scenario: Реплики не мигрируют схему
|
||||
|
||||
- **WHEN** стартует или перезапускается реплика API
|
||||
- **THEN** она не применяет миграции; журнал версий меняет только процесс `migrate`
|
||||
|
||||
### Requirement: Данные и сессии переживают рестарт
|
||||
|
||||
Пользователи, чаты, участники, сообщения, ключи идемпотентности и ещё действующие сессии 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`
|
||||
|
||||
#### Scenario: Логаут после рестарта
|
||||
|
||||
- **WHEN** после рестарта пользователь отзывает прежний токен
|
||||
- **THEN** ответ `204`, а следующий запрос с этим токеном получает `401`
|
||||
|
||||
### Requirement: Воспроизводимый стенд из репозитория
|
||||
|
||||
Стенд 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`
|
||||
|
||||
#### Scenario: Опубликован только балансировщик
|
||||
|
||||
- **WHEN** выполняется `docker compose ps --format '{{.Service}} {{.Ports}}'`
|
||||
- **THEN** опубликованные порты есть только у сервиса `lb` и все они привязаны к `127.0.0.1`
|
||||
|
||||
#### Scenario: Секреты и volumes вне Git
|
||||
|
||||
- **WHEN** выполняются `git ls-files secrets .env` и `git check-ignore secrets/database_url .env`
|
||||
- **THEN** первая команда ничего не выводит, вторая подтверждает, что пути игнорируются
|
||||
+81
@@ -0,0 +1,81 @@
|
||||
## Purpose
|
||||
|
||||
Определяет идемпотентную отправку сообщения через `Idempotency-Key`: формат и область ключа, повтор и конфликт, срок хранения результата, атомарность записи и поведение при конкурентном повторе через разные реплики и при неопределённом исходе.
|
||||
|
||||
## ADDED 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 @@
|
||||
## Purpose
|
||||
|
||||
Определяет развёртывание API несколькими взаимозаменяемыми репликами за единственной публичной точкой входа: что видно клиенту, как балансировщик выбирает и исключает реплики, какие запросы он вправе повторить и как оператор останавливает одну реплику и перезапускает стенд.
|
||||
|
||||
## ADDED 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` после прогона позже, чем до него
|
||||
@@ -0,0 +1,43 @@
|
||||
## 1. Перенос лабы 2
|
||||
|
||||
- [x] 1.1 Перенести контекст агента и историю openspec, переписать `AGENTS.md` и `openspec/config.yaml` под лабу 3
|
||||
- [x] 1.2 Перенести код, собственные тесты, Dockerfile, тулчейн, compose, миграции, скрипты и CI из коммита `8cddb09` лабы 2; влить цели Makefile
|
||||
- [x] 1.3 Проверка группы: `make lint`, `make student-test`, `make check` зелёные до изменений лабы 3
|
||||
|
||||
## 2. Идентификатор реплики (платформа)
|
||||
|
||||
- [ ] 2.1 `PlatformSettings.instance_id` по умолчанию из `socket.gethostname()`; заголовок `X-Instance-Id` в конвейере и в обработчике `500`
|
||||
- [ ] 2.2 Версия приложения 1.3.0; проверка группы: тесты — `X-Instance-Id` на `200`, `204`, `401`, `404`, `405`, `413`, `500`, одно значение на процесс
|
||||
|
||||
## 3. Схема
|
||||
|
||||
- [ ] 3.1 Миграция `0002_idempotency_keys.sql`: PK `(chat_id, user_id, key)`, FK на `chat_members` и `messages`, `CHECK` формата ключа и длины отпечатка
|
||||
- [ ] 3.2 Проверка группы: тест миграций — версии `0001`, `0002`, повтор без изменений, ключ без участника отклоняется FK
|
||||
|
||||
## 4. Идемпотентная отправка (зона `messaging`)
|
||||
|
||||
- [ ] 4.1 Домен: `Receipt` с `replay`, ошибка `IdempotencyConflict`; команда `PostMessage` с ключом и отпечатком
|
||||
- [ ] 4.2 Порт и адаптер PostgreSQL: поиск квитанции с учётом TTL, запись сообщения и ключа одним оператором; `LockNotAvailableError` → `503`
|
||||
- [ ] 4.3 Обработчик: блокировка чата → `chat.post` → квитанция → повтор, `409` или запись; `IDEMPOTENCY_TTL_SECONDS` в настройках зоны
|
||||
- [ ] 4.4 HTTP: обязательный заголовок `Idempotency-Key` (`400`), отпечаток канонического JSON модели, `409 conflict` в реестре ошибок зоны
|
||||
- [ ] 4.5 Проверка группы: тесты — повтор, другое тело `409`, нет и неверный ключ `400`, `4xx` не занимает ключ, другой пользователь и другой чат независимы, повтор после выхода `401`, посторонний `404`, истёкший ключ, 8 конкурентных повторов в реальном PostgreSQL дают одно сообщение; ключ во всех прежних отправках
|
||||
|
||||
## 5. Стенд
|
||||
|
||||
- [ ] 5.1 `infra/haproxy/haproxy.cfg` из заготовки: round robin, `httpchk /health/ready`, Docker DNS, политика повторов, JSON-ошибки LB, статистика
|
||||
- [ ] 5.2 `compose.yaml`: `lb`, `api` с `deploy.replicas` без портов, сети `edge`/`backend`, лимиты всех сервисов, параметры PostgreSQL, таймауты и `stop_grace_period`; удалить `api-shortttl`
|
||||
- [ ] 5.3 `.env.example`, Dockerfile (умолчания таймаутов и воркеров), Makefile (`up`, `down`, `restore`, `lb-check`, `test-faults` без `api-shortttl`), CI-job под лабу 3
|
||||
- [ ] 5.4 Проверка группы: `docker compose config --quiet`, `haproxy -c`, `make up`, опубликованы только порты `lb`
|
||||
|
||||
## 6. Хуки и зонд
|
||||
|
||||
- [ ] 6.1 `scripts/stop-one.sh`, `scripts/restart.sh` (вместо версии лабы 2), `scripts/restore.sh`, `scripts/lb-wait.sh`
|
||||
- [ ] 6.2 `scripts/probe.py` (`check`), ruff для `scripts/*.py`
|
||||
- [ ] 6.3 Скрипт доказательства отказа: `docker ps -a` до и после, `make test-failover`, какой контейнер остановлен
|
||||
- [ ] 6.4 Проверка группы: `make test`, `make lb-check`, `make test-failover ACTION_SCRIPT=scripts/stop-one.sh` для обеих реплик с `scripts/restore.sh` между ними, `make test-persistence ACTION_SCRIPT=scripts/restart.sh`
|
||||
|
||||
## 7. Отчёт
|
||||
|
||||
- [ ] 7.1 `evidence/`: smoke, stack, lb-check, failover по каждой реплике, persistence со `StartedAt`, схема и повтор миграций, KDF, секреты, собственные тесты, окружение
|
||||
- [ ] 7.2 `REPORT.md`: запуск из чистого clone, архитектура и решения, роли и сервисы, соответствие переменных, строки 3.1–3.5 и переноса lab2, таблица отказов уровня «3»
|
||||
- [ ] 7.3 Проверка группы: `make check`, `make validate`, `make lint`, `make student-test`, `make test`, persistence и failover зелёные
|
||||
Reference in New Issue
Block a user