diff --git a/openspec/changes/add-lab3-load-balanced-replicas/.openspec.yaml b/openspec/changes/add-lab3-load-balanced-replicas/.openspec.yaml new file mode 100644 index 00000000..1bb6456d --- /dev/null +++ b/openspec/changes/add-lab3-load-balanced-replicas/.openspec.yaml @@ -0,0 +1,2 @@ +schema: spec-driven +created: 2026-10-28 diff --git a/openspec/changes/add-lab3-load-balanced-replicas/design.md b/openspec/changes/add-lab3-load-balanced-replicas/design.md new file mode 100644 index 00000000..59101327 --- /dev/null +++ b/openspec/changes/add-lab3-load-balanced-replicas/design.md @@ -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 работает на новой схеме, не создавая ключей. diff --git a/openspec/changes/add-lab3-load-balanced-replicas/proposal.md b/openspec/changes/add-lab3-load-balanced-replicas/proposal.md new file mode 100644 index 00000000..eff0837a --- /dev/null +++ b/openspec/changes/add-lab3-load-balanced-replicas/proposal.md @@ -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). diff --git a/openspec/changes/add-lab3-load-balanced-replicas/specs/lab1-messenger-history/spec.md b/openspec/changes/add-lab3-load-balanced-replicas/specs/lab1-messenger-history/spec.md new file mode 100644 index 00000000..ec1599cd --- /dev/null +++ b/openspec/changes/add-lab3-load-balanced-replicas/specs/lab1-messenger-history/spec.md @@ -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` diff --git a/openspec/changes/add-lab3-load-balanced-replicas/specs/lab1-service-operability/spec.md b/openspec/changes/add-lab3-load-balanced-replicas/specs/lab1-service-operability/spec.md new file mode 100644 index 00000000..1172fbfa --- /dev/null +++ b/openspec/changes/add-lab3-load-balanced-replicas/specs/lab1-service-operability/spec.md @@ -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` diff --git a/openspec/changes/add-lab3-load-balanced-replicas/specs/lab2-persistent-storage/spec.md b/openspec/changes/add-lab3-load-balanced-replicas/specs/lab2-persistent-storage/spec.md new file mode 100644 index 00000000..61a22242 --- /dev/null +++ b/openspec/changes/add-lab3-load-balanced-replicas/specs/lab2-persistent-storage/spec.md @@ -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** первая команда ничего не выводит, вторая подтверждает, что пути игнорируются diff --git a/openspec/changes/add-lab3-load-balanced-replicas/specs/lab3-idempotent-messages/spec.md b/openspec/changes/add-lab3-load-balanced-replicas/specs/lab3-idempotent-messages/spec.md new file mode 100644 index 00000000..894bfdf3 --- /dev/null +++ b/openspec/changes/add-lab3-load-balanced-replicas/specs/lab3-idempotent-messages/spec.md @@ -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`, а каждый подтверждённый ответ совпадает с записью истории байт-в-байт diff --git a/openspec/changes/add-lab3-load-balanced-replicas/specs/lab3-load-balancing/spec.md b/openspec/changes/add-lab3-load-balanced-replicas/specs/lab3-load-balancing/spec.md new file mode 100644 index 00000000..6b15d9ac --- /dev/null +++ b/openspec/changes/add-lab3-load-balanced-replicas/specs/lab3-load-balancing/spec.md @@ -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` после прогона позже, чем до него diff --git a/openspec/changes/add-lab3-load-balanced-replicas/tasks.md b/openspec/changes/add-lab3-load-balanced-replicas/tasks.md new file mode 100644 index 00000000..934576d0 --- /dev/null +++ b/openspec/changes/add-lab3-load-balanced-replicas/tasks.md @@ -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 зелёные