Files
mtusi2026lab2/REPORT.md
T
ArtyomandClaude Opus 5.5 a9aab2727f Record level 4 evidence and extend the report
Evidence from a freshly recreated stand at the current code: the four
detection cases with their declared maxima, failover-each for both
replicas under k6 at 100 rps (no errors, no balancer retries, the
stopped replica never served during its outage), the 20 round
same-key race, the limits and isolation check with a run against
deliberate violations, and two rolling updates under load: from the
level 3 image, where the old replicas without a drain window caused
54 redispatches and 2 response errors that the balancer retried, and
between two current builds with all counters at zero. Level 3 runs
are refreshed on the new code: smoke, stack view, both failovers with
the drain sequence in the replica log, hooks with the longer stop,
persistence, stack fault tests and own tests with the shutdown and
timeout chain output.

The report gains the shutdown order, the check period and worst
detection per failure with measurements, the timeout chain, rows 4.1
to 4.4, level 4 rows of the failure table, the k6 role, the new
variables and the updated limitations; AGENTS.md lists the commands.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
2026-10-28 20:07:51 +03:00

307 lines
44 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Отчёт — лабораторная 3
- Автор, группа: Костылев Артём, БПИ2303
- Целевая оценка: **5**; трек «5» — **трек 1 «Цена масштабирования»**
- Commit/PR: ветка `solution/bpi2303-kostylev`, PR в репозиторий преподавателя
- Использованные источники, библиотеки и помощь ИИ: FastAPI, gunicorn + uvicorn-worker, dishka, pydantic,
structlog, asyncpg, argon2-cffi, redis-py, pytest, ruff, ty (версии — `evidence/environment.txt` и `uv.lock`);
HAProxy 3.2 Configuration Manual (health checks, resolvers, `retry-on`, `http-error`, `init-state`), Grafana k6
(`constant-arrival-rate`, `handleSummary`), uvicorn и gunicorn (порядок graceful shutdown), документация Docker
Compose (`deploy.replicas`, `depends_on`, secrets), PostgreSQL (`SELECT … FOR UPDATE`, `INSERT … ON CONFLICT`,
уровни изоляции), IETF draft «The Idempotency-Key HTTP Header Field». Решение перенесено из моей лабы 2 и
выполнено с помощью Claude Code; код, стенд и отказы проверены прогонами, перечисленными ниже.
## Запуск из чистого clone
Требуются Docker с Compose v2 и `make`; системный Python 3.9+ — только для публичных проверок и
`scripts/probe.py`. Образы сторонних сервисов закреплены версией и digest, API собирается из исходников.
```sh
git clone <repo> && cd mtusi2026lab3 && git checkout solution/bpi2303-kostylev
make secrets # secrets/* (пароли PostgreSQL и Valkey, DATABASE_URL, CACHE_URL, ключ курсора) и .env из .env.example
docker compose --env-file .env config --quiet
make up # docker compose up -d --build --wait: postgres, valkey → migrate → api ×2 → lb, ждёт healthy
make test # публичный smoke через балансировщик, http://localhost:8080
make lb-check # ≥2 X-Instance-Id на одном токене и 8 параллельных POST с одним ключом → evidence/lb-check.json
make test-failover ACTION_SCRIPT=scripts/stop-one.sh
make restore # вернуть остановленную реплику и дождаться её в ротации LB
make test-persistence ACTION_SCRIPT=scripts/restart.sh
make down # безопасная остановка: контейнеры удаляются, volumes с данными остаются
make reset-data # НАМЕРЕННОЕ удаление учебных данных: docker compose down -v
```
`make up` ждёт не только `healthy` реплик, но и `healthy` балансировщика, а он здоров, только когда в ротации
есть реплика (`/healthz` на порту статистики). Миграции применяет одноразовый `migrate` до старта реплик.
Публикуются только порты `lb` на `127.0.0.1`: `LB_HTTP_PORT` (по умолчанию 8080) и `LB_STATS_PORT` (8404,
статистика только для чтения). На машине, где выполнялась работа, параллельно работали стенды других лаб,
поэтому в локальном `.env` стояли `LB_HTTP_PORT=18083`, `LB_STATS_PORT=23083`, а проверки запускались с
`BASE_URL=http://localhost:18083`. Прогон из свежего clone — `evidence/clean-clone.txt`.
Собственные проверки и тулчейн:
```sh
make install # uv sync --group dev (Python 3.14 и зависимости из uv.lock)
make lint # ruff check + ruff format --check (src, student-tests, scripts/probe.py, scripts/limits.py) + ty check
make student-test # собственные тесты; поднимают одноразовые PostgreSQL и Valkey того же образа в Docker
make check # офлайн-проверка skeleton
make validate PYTHON=.venv/bin/python # полная валидация OpenAPI
make test-faults # тесты стенда лабы 2 (Valkey, PostgreSQL, гонки) через балансировщик
make failover-evidence # docker inspect реплик до/после, make test-failover, логи остановленной, restore
make persistence-evidence # persistence-тест + StartedAt всех контейнеров до и после
make stack-evidence # сервисы, порты, hostname ↔ X-Instance-Id, лимиты, сети, взгляд LB
make storage-evidence # \d+ схемы, повтор миграций, префикс KDF, правила ignore
```
Проверки уровня «4» — по одной команде на пункт рубрики, каждая пишет файл в `evidence/` и завершается
ненулевым кодом при нарушении (`make level4` — все подряд, ≈8 минут):
```sh
make limits # лимиты, порты, секреты, volumes, сети по политике → evidence/limits.txt
make lb-check # 40 GET одним токеном + 20 раундов × 8 параллельных POST с одним ключом
make detection # время обнаружения: SIGTERM, kill, pause, остановка PostgreSQL → evidence/detection/
make failover-each # каждая реплика: остановка, 10 с без неё, возврат — под k6 100 rps
make rolling-update FROM_REV=8d28d45 # стенд на версии уровня «3», затем замена на текущую под нагрузкой
make rolling-update # замена текущей сборкой (эквивалентная поочерёдная замена)
```
Генератор нагрузки — сервис `k6` под профилем `bench` (с `make up` не стартует); `RATE` задаёт интенсивность.
**Версии и стенд:** Python 3.14.7 в образе `python:3.14-slim-trixie@sha256:51dafde8…`,
`haproxy:3.2.26-alpine@sha256:58938405…`, `postgres:17.11-alpine@sha256:266d3c25…`,
`valkey/valkey:8.1.11-alpine@sha256:2602ace2…`, uv 0.9.7 по digest, Docker 28.3.2, Compose 2.38.2. Машина —
Apple M4 Max, 16 CPU, 48 ГБ RAM, macOS 15.1; VM Docker Desktop — 16 CPU, 7.65 ГиБ (`evidence/environment.txt`).
## Архитектура и решения
```
┌── api (gunicorn, 2 × UvicornWorker) ──┐ asyncpg pool, 1–2 с
клиент ──HTTP──▶ lb (HAProxy 3.2) ───┤ X-Instance-Id = hostname ├──▶ postgres (источник истины, pgdata)
127.0.0.1:8080 round robin, └── api (gunicorn, 2 × UvicornWorker) ──┘──▶ valkey (кэш сессий, AOF, valkeydata)
httpchk /health/ready migrate (тот же образ, один раз до реплик) ──▶ postgres
сеть edge ─────── lb ─────── сеть backend (internal): lb, api, migrate, postgres, valkey
```
**Перенесено из лабы 2 без изменения поведения:** зоны `identity` и `messaging`, порты и адаптеры, UoW, шина
событий с журналом аудита, ASGI-конвейер, Basic → Bearer, Argon2id, сессии в PostgreSQL с read-through кэшем
в Valkey и отметками отзыва, подписанный курсор, порядок истории под блокировкой строки чата, миграции под
advisory lock, тесты стенда (`make test-faults`). Уже в лабе 2 реплика не держала в памяти ничего, от чего
зависит корректность: кэш и отметки отзыва общие (Valkey), курсор подписан общим секретом, отметка
`created_at` назначается под блокировкой строки чата, а не часами процесса. **Изменено:** один контейнер с
портом → сервис `api` с `deploy.replicas` за HAProxy; `X-Instance-Id`; обязательный `Idempotency-Key`;
миграция `0002`; `restart.sh` перезапускает и LB; таймауты и воркеры под реплики; удалён `api-shortttl`
(публиковал порт API в обход LB, проверка истечения TTL осталась in-process тестом).
**`X-Instance-Id`.** `PlatformSettings.instance_id` по умолчанию — `socket.gethostname()`; Docker даёт
контейнеру hostname, равный короткому ID, поэтому значение одно на все воркеры реплики, стабильно на жизнь
контейнера и совпадает с `docker ps` (`evidence/stack.txt`). Конвейер ставит заголовок рядом с
`X-Request-Id` на каждый ответ, проходящий через него; ответ `500` формирует внешний `ServerErrorMiddleware`,
поэтому обработчик необработанных исключений ставит оба заголовка сам. `INSTANCE_ID` в compose не задаётся:
он был бы одинаков у всех реплик.
**Идемпотентная отправка (зона `messaging`).** Таблица `idempotency_keys (chat_id, user_id, key, fingerprint,
message_id, created_at)`, PK `(chat_id, user_id, key)` — область «пользователь + метод + путь чата + ключ»
(ключ бывает только у `POST …/messages`), FK `(chat_id, user_id) → chat_members` и `message_id → messages`,
`CHECK` формата ключа и длины отпечатка. Обработчик в одной транзакции:
1. `SELECT … FROM chats WHERE id = $1 FOR UPDATE` → `404`, если чата нет;
2. членство (`404`), затем текст (`400`) — в памяти;
3. квитанция по PK, моложе `IDEMPOTENCY_TTL_SECONDS`: тот же отпечаток → сохранённое сообщение (`201`, тот же
`MessageOut`, `created_at` хранится с микросекундами); другой → `409 conflict`;
4. квитанции нет → один оператор: `INSERT messages` + `INSERT idempotency_keys … ON CONFLICT DO UPDATE`
(перезапись истёкшего ключа) + `UPDATE chats.last_message_at`; `COMMIT`.
Сообщение и ключ фиксируются вместе или не фиксируются вовсе; маркера «в обработке» нет, поэтому после
гибели реплики посреди запроса повтор с тем же ключом создаёт сообщение один раз. Одновременные повторы
одного ключа всегда идут в один чат и ждут на блокировке его строки; следующий оператор в `READ COMMITTED`
видит зафиксированную квитанцию. Отпечаток — SHA-256 канонического JSON распарсенной модели, поэтому
порядок полей и пробелы не важны. Ответы `4xx`/`5xx` ничего не пишут; `lock_timeout` теперь `503`, а не `500`.
Отвергнуто: `SET NX` в Valkey (не атомарен с `COMMIT`), отдельный маркер «processing» (залипает после отказа).
**Балансировщик** (`infra/haproxy/haproxy.cfg`):
| Параметр | Значение | Зачем |
| --- | --- | --- |
| Обнаружение | `server-template api 8 api:8080`, `resolvers docker` (127.0.0.11), `init-addr none` | остановленная реплика пропадает из DNS, новая появляется без перезапуска LB и без `docker.sock` |
| Алгоритм | `balance roundrobin`, без `stick` | каждое новое соединение — следующая реплика; сессия общая, привязка не нужна |
| Проверка | `GET /health/ready`, `inter 1s fastinter 500ms downinter 2s fall 2 rise 2`, `timeout check 1s`, `init-state fully-down` | реплика без БД или в остановке выходит из ротации; вернувшаяся получает трафик только после проверок |
| Повторы | `retries 2`, `redispatch 1`, `retry-on conn-failure empty-response`; `disable-l7-retry` всем, кроме `GET` и `POST …/messages` с ключом | отказ соединения повторяется всегда (запрос не ушёл); после отправки — только безопасное к повтору; `POST /users`, `/chats`, вход не повторяются (`contracts/README.md`) |
| Соединения к API | `option http-server-close` | нет простаивающих keep-alive, за которые гонится остановка реплики |
| Таймауты | `connect 500ms`, `server 10s` > `REQUEST_TIMEOUT_SECONDS=8` > `statement_timeout` 2 с; `queue 3s`, `maxconn 64` на сервер | цепочка клиент > LB > приложение > БД |
| Ошибки LB | `502/503/504` — JSON `{"error":{…,"request_id"}}` с тем же `X-Request-Id` | формат контракта даже без реплик (`evidence/hooks.txt`) |
| `X-Request-Id` | непустой входящий до 200 символов пробрасывается, иначе uuid4 | приложение эхо-возвращает его |
| Остановка | `SIGUSR1`, `hard-stop-after 5s` | мягкий стоп внутри `stop_grace_period` |
**Остановка и процессы (уровень «4»).** По `SIGTERM` реплика сначала выходит из ротации и только потом
перестаёт принимать соединения. Каждый воркер запускает `DrainingServer` (наследник `uvicorn.Server`,
`src/messenger/gunicorn_conf.py`): после сигнала он поднимает флаг, `/health/ready` отвечает `503`, `/health/live`
— `200`, запросы обслуживаются как обычно, и так `DRAIN_SECONDS=2` — дольше худшего обнаружения `503`
балансировщиком (1,5 с). Затем uvicorn закрывает listener и дообрабатывает принятые запросы ещё
`SHUTDOWN_TIMEOUT_SECONDS − DRAIN_SECONDS` = 3 с; весь срок — gunicorn `graceful_timeout` 5 с < `docker stop -t 6`
хука < `stop_grace_period: 8s` < 10 с. Без окна (уровень «3») gunicorn закрывал listener сразу, и запрос, уже
стоявший в очереди `accept`, LB видел как обрыв после отправки: для `GET` и сообщений с ключом это повтор, для
`POST /users`, `/chats` и входа — `502`. Разница видна в счётчиках LB: rolling update со старой версии —
`wredis` 54, `eresp` 2, с новой — 0 (`evidence/rolling*/result.json`). Хук `stop-one.sh` теперь идёт ≈2,7 с.
На реплику `cpus: 1`, `512m`, 2 воркера, пул 8: 2 × 2 × 8 = 32 соединения < `max_connections=200`. API
работает `read_only` с `tmpfs /tmp`.
**Проверки, период и максимум обнаружения.** `GET /health/ready` раз в `inter 1s`; после первого провала —
`fastinter 500ms`; `fall 2` провала — реплика исключена; `rise 2` успеха — возвращена; `timeout check 1s`;
у `DOWN`-реплики — `downinter 2s`. Readiness пингует PostgreSQL за ≤0,8 с (0,4 с на соединение из пула и 0,4 с
на `SELECT 1`), то есть отвечает явным `503` раньше таймаута проверки. `init-state fully-down`: сервер, который
стартовал, появился через DNS или вернулся из `MAINT (resolution)`, получает трафик только после `rise 2`
проверок (без этого HAProxy делал его `UP/READY` сразу по DNS-ответу, и запросы уходили в ещё не слушающий
gunicorn — первый прогон `failover-each` показал `wredis` 19 и 49 без ошибок).
| Отказ | Как замечает LB | Максимум обнаружения | Замер (`make detection`) |
| --- | --- | --- | --- |
| `SIGTERM` (`docker stop`, `stop-one.sh`) | readiness `503` в окне вывода | `inter + (fall−1)·fastinter` = 1,5 с, и раньше закрытия порта (2 с) | 0,71 с; процесс вышел через 2,49 с |
| процесс убит (`docker kill`) | отказ соединения, DNS | 1,5 с | 0,67 с |
| процесс завис (`docker pause`) | таймаут проверки | `inter + (fall−1)·fastinter + fall·timeout check` = 3,5 с | 2,76 с |
| PostgreSQL остановлен | readiness всех реплик `503` | 1,5 с до 0 `UP`; LB сам отвечает `503` | 1,23 с; `/health/live` через LB → `503 unavailable` без `X-Instance-Id` |
Допуск замера — 0,25 с (задержка docker CLI до сигнала и опрос статистики LB раз в 50 мс); время считается
от запуска команды отказа. Возврат в ротацию после `restore` — 2,0–3,1 с.
**Цепочка таймаутов** (проверяется тестом `student-tests/unit/test_timeouts.py` по `compose.yaml`,
`haproxy.cfg` и `scripts/stop-one.sh`, а не только таблицей):
| Звено | Значение | Условие |
| --- | --- | --- |
| LB `timeout server` | 10 с | > `REQUEST_TIMEOUT_SECONDS` |
| `REQUEST_TIMEOUT_SECONDS` | 8 с | > ожидание соединения + оператор БД |
| `DB_ACQUIRE_TIMEOUT_SECONDS` + `DB_COMMAND_TIMEOUT_SECONDS` (`statement_timeout` = `lock_timeout`) | 1 + 2 с | ≤ дообработки 3 с после окна |
| LB `timeout check` | 1 с | > readiness 0,8 с |
| `DRAIN_SECONDS` | 2 с | > обнаружения 1,5 с |
| `SHUTDOWN_TIMEOUT_SECONDS` (gunicorn `graceful_timeout`) | 5 с | > окна; < `STOP_TIMEOUT` хука |
| `STOP_TIMEOUT` хука `stop-one.sh` | 6 с | < `stop_grace_period` 8 с < 10 с |
| LB `timeout connect` / `queue` | 0,5 с / 3 с | отказ соединения повторяется на соседа сразу |
| LB `hard-stop-after` | 5 с | < `stop_grace_period` LB 8 с |
| клиенты: resilience / smoke / k6 | 2 / 10 / 10 с | — |
**Хуки.** `scripts/stop-one.sh` — контейнер `api` с `.Config.Hostname == TARGET_INSTANCE_ID` → `docker stop -t 6`,
реплика остаётся остановленной, неизвестный ID → код 3 без изменений. `scripts/restart.sh` — `stop lb api`,
`restart postgres valkey`, `up -d --no-recreate --wait` (те же контейнеры, повторный `migrate`), volumes не
трогаются. `scripts/restore.sh` — `up --no-deps --no-recreate --wait api`, затем `scripts/lb-wait.sh` ждёт, пока
статистика LB покажет все реплики `UP`.
**Роли и сервисы** (`compose.yaml`; сети `edge` и `backend` с `internal: true`):
| Роль | Сервис | Версия / digest | Health / readiness | Volume | Сеть / порт | Credentials |
| --- | --- | --- | --- | --- | --- | --- |
| load_balancer | `lb` | `haproxy:3.2.26-alpine@sha256:58938405…`, uid 99, `read_only`, `cap_drop: ALL` | `/healthz` :8404 (`nbsrv(api) ≥ 1`); проверяет реплики `GET /health/ready` | нет | `edge` + `backend`; `127.0.0.1:${LB_HTTP_PORT:-8080}`, `127.0.0.1:${LB_STATS_PORT:-8404}` | нет |
| api ×`API_REPLICAS` | `api` | сборка из `Dockerfile`, python по digest, uid 10001, `read_only` | `GET /health/ready` (пингует PostgreSQL) | нет | `backend`, порт не публикуется | secrets `database_url`, `cache_url`, `cursor_secret` через `*_FILE` |
| postgres | `postgres` | `postgres:17.11-alpine@sha256:266d3c25…`, uid 70, `pg_stat_statements` | `pg_isready` | `pgdata:/var/lib/postgresql/data` | `backend` | secret `postgres_password` через `POSTGRES_PASSWORD_FILE` |
| сессии (кэш) | `valkey` | `valkey/valkey:8.1.11-alpine@sha256:2602ace2…`, uid 999 | `valkey-cli ping` с паролем | `valkeydata:/data` (AOF) | `backend` | secret `valkey.conf` (`requirepass`) |
| bootstrap | `migrate` | образ api, `restart: "no"` | код выхода 0 | нет | `backend` | secret `database_url` |
| генератор нагрузки (профиль `bench`) | `k6` | `grafana/k6:2.3.0@sha256:2dd4756e…`, uid хоста | нет | нет (скрипт `infra/k6` только для чтения) | только `edge`, порт не публикуется | нет |
Готовность реплики зависит только от PostgreSQL: Valkey — кэш, при его отказе проверка идёт в БД. Общее
хранилище сессий — PostgreSQL (источник истины) плюс общий Valkey. Bootstrap: `make secrets` (идемпотентен,
не перезаписывает существующие файлы), `make up` (миграции — `migrate` под advisory lock); повтор безопасен.
Лимиты: lb 1 CPU/128m, api 1 CPU/512m на реплику, migrate 0.5/256m, postgres 2/1g, valkey 0.5/128m,
k6 2/512m (`make limits` сверяет их и изоляцию с политикой).
**Соответствие `.env.example` реальной конфигурации:**
| `.env.example` | В решении | Комментарий |
| --- | --- | --- |
| `APP_HOST`, `APP_PORT` | `HOST`, `PORT` | заданы в образе (`0.0.0.0:8080`); снаружи — порт LB `LB_HTTP_PORT` |
| `APP_ENV` | не используется | режимов окружения нет |
| `SESSION_TTL_SECONDS` | `SESSION_TTL_SECONDS` | по умолчанию 3600 |
| `DATABASE_URL_FILE` | `DATABASE_URL_FILE` | любой параметр читается из `<ИМЯ>_FILE` |
| `SESSION_STORE=postgres` | фиксировано | PostgreSQL — источник истины сессий, Valkey — кэш поверх него |
| `CACHE_URL_FILE` | `CACHE_URL_FILE` | без него кэш выключен |
| `API_REPLICAS` | `deploy.replicas: ${API_REPLICAS:-2}` | число реплик сервиса `api` |
| `IDEMPOTENCY_TTL_SECONDS` | `IDEMPOTENCY_TTL_SECONDS` | 86 400; квитанция старше срока перезаписывается новым запросом |
| — | `LB_HTTP_PORT`, `LB_STATS_PORT` | опубликованные порты LB на `127.0.0.1` |
| — | `API_CPUS`, `API_MEMORY`, `WEB_CONCURRENCY`, `DB_POOL_MAX_SIZE`, `API_SERVER_MAXCONN` | размер реплики, воркеры, пул на воркер, очередь LB на сервер |
| — | `PG_MAX_CONNECTIONS`, `PG_CPUS`, `PG_MEMORY`, `LB_CPUS` | лимиты PostgreSQL и LB |
| — | `REQUEST_TIMEOUT_SECONDS`, `DRAIN_SECONDS`, `SHUTDOWN_TIMEOUT_SECONDS` | 8 с, 2 с и 5 с (заданы в compose и образе) |
| — | `DB_ACQUIRE_TIMEOUT_SECONDS`, `DB_COMMAND_TIMEOUT_SECONDS` | 1 с и 2 с: ожидание соединения из пула и `statement_timeout` = `lock_timeout` |
| — | `K6_CPUS`, `K6_MEMORY` | лимиты генератора нагрузки (профиль `bench`) |
| — | `CURSOR_SECRET_FILE` | общий ключ подписи курсора для всех реплик |
## Доказательства критериев
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства |
| --- | --- | --- | --- |
| Публичный smoke | `make test BASE_URL=http://localhost:18083` | `PASS: lab3 public API scenario` (включая replay == first, `409` на другой body, `400` без ключа, `X-Instance-Id` на каждом ответе) | `evidence/smoke.txt` |
| Запуск из чистого clone | `git clone`, `make secrets`, `config --quiet`, `make up`, `make test` | `valid`; все сервисы `Healthy`, `migrate` `Exited` (0) за 15 с; smoke `PASS` | `evidence/clean-clone.txt` |
| **3.1** Весь стенд в `compose.yaml`, ≥2 API, одна точка входа, общая БД и общее хранилище сессий | `make stack-evidence` (`config --quiet`, `ps`, `docker port` реплик, `docker inspect`, статистика LB) | 2 контейнера `api` без портов (`docker port` пуст), порты только у `lb` на `127.0.0.1`; `container_name` 0; LB видит `api1 UP L7OK 200`, `api2 UP L7OK 200`; один `postgres`, один `valkey` | `evidence/stack.txt` |
| **3.2** Разные запросы одного пользователя — разные реплики без повторного входа, видно по `X-Instance-Id` | `make lb-check` (40 × `GET /users/me` одним токеном, новые соединения) + `docker inspect` | `{"27de23496b0f": 20, "a3536e394b3f": 20}` — ровно hostname двух контейнеров `api` | `evidence/lb-check.json`, `evidence/stack.txt` |
| **3.3** Остановка любой одной реплики: ≤10 с, данные доступны, ошибки измерены | `make failover-evidence` → `make test-failover ACTION_SCRIPT=scripts/stop-one.sh`, `docker inspect` до/после, `restore`; второй прогон после сдвига round robin | реплика `27de23496b0f`: первая запись после хука через 2.64 с от его старта, 133 записи после, 0 ошибок; реплика `a3536e394b3f`: 2.69 с, 130, 0; именно target в `exited` с кодом 0, в его логе — сигнал, окно вывода из ротации с readiness `503`, закрытие и выход; `PASS: failover …` | `evidence/failover-27de23496b0f.txt`, `evidence/failover-a3536e394b3f.txt` |
| **3.3** Хук останавливает только заданную реплику | `scripts/stop-one.sh` с hostname, с неизвестным ID и без него | хук 2.72 с (окно вывода 2 с + остановка), код 0, target `exited` с кодом 0; неизвестный ID → код 3, всё работает; без переменной → код 1 | `evidence/hooks.txt` |
| **3.4** Повтор с тем же ключом не создаёт дубль; конкурентный повтор и смена реплики | `make lb-check` (20 раундов × 8 параллельных POST с одним ключом через LB); `make student-test -k idempotency`; failover-тест (после ошибки — тот же ключ и текст) | 160 × `201` от обеих реплик (80 + 80); в каждом из 20 раундов тела равны, в истории 1 копия, другой body → `409`; in-process: 8 повторов через два экземпляра приложения → одна строка ключа | `evidence/lb-check.json`, `evidence/student-tests.txt`, `evidence/failover-*.txt` |
| **3.4** Неподтверждённую запись можно безопасно повторить | `make student-test -k "rejected_attempt or expired or concurrent"`; failover-тест сверяет историю байт-в-байт | `4xx` не занимает ключ; истёкший ключ начинает заново; в истории после отказа нет дублей `id`/`text` | `evidence/student-tests.txt`, `evidence/failover-*.txt` |
| **3.5** `make test`, persistence и failover проходят; ≥2 наблюдаемых реплики | `make test`, `make persistence-evidence`, `make test-failover …` | smoke `PASS`; persistence `PASS`, `StartedAt` у `lb`, обеих `api`, `postgres`, `valkey`, `migrate` после теста новее, контейнеры те же; failover `observed_instances_before: 2` | `evidence/smoke.txt`, `evidence/persistence.txt`, `evidence/failover-*.txt` |
| Перенос lab2: схема PK/FK/UNIQUE и миграции с нуля, повтор без дублей | `make reset-data && make up`; `make storage-evidence` | `0001_init`, `0002_idempotency_keys` применены; повтор `up to date`, счётчики строк равны (сообщений столько же, сколько ключей) | `evidence/schema.txt`, `evidence/migrations.txt` |
| Перенос lab2: Basic только на `/auth/sessions`, Bearer, logout, `X-User-Id` игнорируется | `make test`; `make student-test`; `make test-faults` | smoke `PASS`; logout `204` → `401` → `401` через LB | `evidence/smoke.txt`, `evidence/student-tests.txt`, `evidence/faults.txt` |
| Перенос lab2: password KDF | `make storage-evidence` | `$argon2id$v=19$m=19456,t=2,p=1$` у всех пользователей; в `sessions` только 32-байтовые SHA-256 | `evidence/kdf.txt` |
| Перенос lab2: секреты и volumes вне Git | `git ls-files secrets .env`; `git check-ignore -v …` | пусто; пути игнорируются | `evidence/secrets.txt` |
| Перенос lab2: отказы Valkey и PostgreSQL через LB | `make test-faults BASE_URL=http://localhost:18083` | 10 passed: гонка регистрации 201×1/409×49, rollback чата, остановка Valkey и PostgreSQL (`503` ≤ 0.02 с; live внутри реплики `200`; LB исключил обе реплики через 0.61 с и сам отвечает `503`; готовность через 2.1 с), рестарт API | `evidence/faults.txt` |
| `X-Instance-Id` на каждом ответе приложения | `make student-test -k instance` | `200`, `204`, `400`, `401`, `404`, скрытый `405`, `413`, `500` несут один ID реплики и `X-Request-Id` | `evidence/student-tests.txt` |
| Непривилегированные процессы | `make stack-evidence` | api — uid 10001, lb — 99, postgres — 70, valkey — 999 | `evidence/environment.txt` |
**Уровень «4».** Нагрузка — k6 open model из сети `edge` в `lb:8080`: 100 запросов/с постоянной
интенсивности (80 % `POST` сообщения с уникальным ключом, 20 % чтения первой страницы истории), 20
пользователей и 10 чатов, прогрев 10 с, замер 60–90 с; параллельно зонд шлёт сообщение каждые 0,1 с и после
ошибки повторяет тот же ключ, а опрос статистики LB 10 раз в секунду пишет число `UP`. Счётчики LB —
дельта за прогон по backend `api`: `wretr` (повторы), `wredis` (перенаправления), `econ`, `eresp`, `hrsp_5xx`.
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства |
| --- | --- | --- | --- |
| **4.1** Health/readiness, таймауты и прекращение приёма при `SIGTERM` согласованы | `make student-test` (`test_timeouts.py`, `test_drain.py`) | цепочка: LB server 10 с > запрос 8 с > БД 3 с; readiness 0,8 с < check 1 с; окно 2 с > обнаружение 1,5 с; остановка 5 с < хук 6 с < `stop_grace_period` 8 с; настоящий gunicorn по `SIGTERM`: ready/live `(503, 200)` в окне, порт закрыт через 1.69 с, запрос, принятый до сигнала и дописанный после закрытия порта, получил `201`, выход с кодом 0 через 2.11 с | `evidence/student-tests.txt`, `compose.yaml`, `infra/haproxy/haproxy.cfg`, `src/messenger/gunicorn_conf.py` |
| **4.1** LB исключает недоступный backend; период проверок и максимум обнаружения | `make detection` | период 1 с (0,5 с после провала), `fall 2`/`rise 2`; заявлено ≤1,5 с (`503`/отказ соединения) и ≤3,5 с (зависание); измерено: `SIGTERM` 0.71 с — раньше выхода процесса (2.49 с), `kill` 0.67 с, `pause` 2.76 с, PostgreSQL 1.23 с до 0 `UP` и `503 unavailable` от LB; возврат 2.0–3.1 с; все `pass: true` | `evidence/detection/{sigterm,kill,pause,postgres}.json` |
| **4.2** Последовательно остановить каждую реплику (с восстановлением предыдущей); RPS, ошибки, время восстановления | `make failover-each` (на реплику: `stop-one.sh`, 10 с без неё, `restore.sh` — всё внутри окна нагрузки) | `a3536e394b3f`: 100.02 rps, 6001 запрос k6, ошибок 0, p50/p95/p99 2.4/3.41/5.1 мс, обнаружение 1.52 с, возврат в ротацию через 14.11 с от начала действия (хук ≈2,5 с + 10 с + restore), зонд 635 записей / 0 ошибок, пока реплика исключена, её `X-Instance-Id` не встречался; `27de23496b0f`: 100.02 rps, 0 ошибок, 2.44/3.42/5.08 мс, 0.89 с, 14.39 с, 635/0; счётчики LB `wretr`/`wredis`/`econ`/`eresp`/`hrsp_5xx` — 0 | `evidence/failover-each/summary.json`, `evidence/failover-each/<hostname>/` |
| **4.2** Общая идемпотентность — параллельными запросами с одним ключом | `make lb-check` | 20 раундов × 8: 160 × `201` от двух реплик, 20/20 раундов с одинаковыми телами, одной копией и `409` на другой body | `evidence/lb-check.json` |
| **4.3** CPU/RAM-лимиты, API без портов в обход LB, секреты и хранилища только где нужно, нет `container_name` | `make limits` (`docker compose --profile bench config` + `docker inspect` против политики в `scripts/limits.py`) | лимиты у всех 6 сервисов (api 1/512MiB, lb 1/128MiB, postgres 2/1024MiB, valkey 0.5/128MiB, migrate 0.5/256MiB, k6 2/512MiB) и применены у запущенных; порты только у `lb` на `127.0.0.1`; секреты: api — 3, migrate — `database_url`, postgres — пароль, valkey — конфиг, lb и k6 — нет; volumes `pgdata`/`valkeydata` только у своих хранилищ; `backend` internal, k6 только в `edge`; api `read_only`; `PASS`. Подмешанные нарушения (порт и лишний секрет у api, `container_name`, снятый лимит) → 5 нарушений, код 1 | `evidence/limits.txt`, `evidence/limits-violations.txt` |
| **4.4** Rolling update под нагрузкой | `make rolling-update FROM_REV=8d28d45` (стенд на образе уровня «3», затем замена на текущую версию с запасом +1) | `lb_up_min` 2 из 2, k6 100 rps, 9000 запросов, ошибок 0, зонд 897/0; после замены отвечают только новые контейнеры (`7a4c320f9b13`, `00548d9b229e` → `28af1eaa77c8`, `f3f2f7801b56`; образ `cbd83541c3e5` → `13e52dc26774`); старые реплики без окна дали `wredis` 54, `eresp` 2 — запросы, повторённые LB на соседа | `evidence/rolling-from-8d28d45/result.json`, `action.txt` |
| **4.4** То же на текущей версии | `make rolling-update` | `lb_up_min` 2, 9001 запрос, ошибок 0, зонд 904/0, все реплики новые; все счётчики LB 0. Слои образа те же, ID отличается только provenance-аттестацией BuildKit — это эквивалентная поочерёдная замена | `evidence/rolling/result.json`, `action.txt` |
| **4.4** Миграции однократно и совместимы с работающей версией | `scripts/rolling-update.sh`; `make storage-evidence` | `migrate` запускается один раз до замены первой реплики (`migration.completed up to date`), реплики схему не трогают, `migrate` под `pg_advisory_lock`; между уровнями «3» и «4» схема не менялась; `0002_idempotency_keys` только добавляет таблицу, код лабы 2 её не замечает | `evidence/rolling*/action.txt`, `evidence/migrations.txt` |
## Эксперименты и отказы
Стенд: 2 реплики × (1 CPU, 512 MiB, 2 воркера), PostgreSQL 2 CPU / 1 GiB, HAProxy 1 CPU / 128 MiB, Valkey
0.5 CPU / 128 MiB, k6 2 CPU / 512 MiB; Docker Desktop на Apple M4 Max. Нагрузка в failover-тесте — один клиент,
`POST` каждые 0.1 с в течение 15 с, таймаут 2 с, повтор после ошибки с тем же ключом; в строках уровня «4» —
k6 100 rps плюс зонд (см. выше).
| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных |
| --- | --- | --- | --- |
| stop api#1 (`stop-one.sh`, `27de23496b0f`) | запись продолжается ≤10 с, target больше не отвечает | 0 неудачных попыток, 133 записи после хука, последние 5 ответов — от `a3536e394b3f` | первая запись после хука через 2.64 с от его старта (хук ≈2,7 с из-за окна вывода; запись не прерывалась); потерь и дублей нет |
| stop api#2 (после `restore`, `a3536e394b3f`) | то же для второй реплики | 0 неудачных попыток, 130 записей после хука | 2.69 с; потерь и дублей нет |
| Полный restart (`restart.sh`: lb, api ×2, postgres, valkey) | прежний токен работает, история побайтно та же | persistence `PASS`, `StartedAt` всех контейнеров обновился, ID контейнеров прежние | стенд `healthy` ≈12 с; потерь нет |
| Конкурентный одинаковый ключ (20 раундов × 8 POST через LB) | в каждом раунде одно сообщение, все ответы равны | 160 × `201`, 80 + 80 по репликам, 20/20 раундов с 1 копией, другой body → `409` | — |
| Все реплики остановлены | LB отвечает `503` в формате контракта | `503 {"error":{"code":"unavailable",…,"request_id":"no-replica-1"}}` | после `make restore` — `200` |
| `docker compose stop postgres` | реплики выходят из ротации, ответы `503`, а не `500` | `503` за ≤0.02 с на ready, me, login, register; live внутри реплики `200`; LB исключил обе реплики за 0.61–1.23 с и отвечает `503` сам | после `start` готовность через 2.1–2.5 с без рестарта API |
| `docker compose stop valkey` | проверка сессий через PostgreSQL, без анонимного доступа | действующий токен `200`, неизвестный `401`, выход `503` | после `start` выход `204` |
| Повторный `migrate` | схема и данные не меняются | `up to date`, счётчики равны | — |
| `SIGTERM` реплике (`docker stop -t 6`) | LB исключает её раньше, чем она закроет порт | исключена через 0.71 с, процесс вышел через 2.49 с с кодом 0; в логе — окно 2 с, readiness `503` | возврат после `restore` 1.96 с |
| Процесс реплики убит (`docker kill`) | исключение ≤1,5 с | 0.67 с | `restore` 3.08 с |
| Процесс реплики завис (`docker pause`) | исключение ≤3,5 с по таймауту проверки | 2.76 с; через LB — `200` от соседа | после `unpause` 2.38 с |
| Поочерёдная остановка каждой реплики под 100 rps | 0 ошибок, запись не прерывается, реплика возвращается | обе реплики: k6 0 ошибок из 6001, зонд 0 из 635, p99 ≈5 мс, повторов LB 0 | обнаружение 0.89–1.52 с; снова в ротации через 14.1–14.4 с от начала действия (хук ≈2,5 с + 10 с без реплики + `restore`) |
| Rolling update с уровня «3» под 100 rps | ёмкость не ниже 2, 0 ошибок, после — только новые реплики | `lb_up_min` 2, 0 ошибок из 9000, зонд 0 из 897; старые реплики без окна: `wredis` 54, `eresp` 2 | замена двух реплик за 7.7 с |
| Rolling update текущей версии под 100 rps | то же, и без повторов LB | `lb_up_min` 2, 0 ошибок из 9001, зонд 0 из 904, все счётчики LB 0 | 11.8 с |
## Ограничения и следующие шаги
- Один Docker-host: потеря host, LB или PostgreSQL — отказ всего стенда. LB и БД — единственные точки отказа;
их резервирование вне рамок лабы.
- Цель failover-теста выбирает round robin (кто обслужил первое сообщение); для второй реплики тест
повторяется после `make restore`, при необходимости с одним лишним запросом через LB.
- `X-Instance-Id` раскрывает короткий ID контейнера — допустимо до лабы 7, где появится непрозрачный alias.
- Таблица ключей растёт вместе с историей (строка на сообщение); истёкшие ключи только перезаписываются при
повторном использовании, фоновой очистки нет.
- Запись в один горячий чат сериализуется блокировкой строки чата; повтор с ключом берёт ту же блокировку.
- Окно вывода из ротации удлиняет каждую остановку реплики на 2 с; оно рассчитано на проверки LB раз в
секунду: при большем `inter` окно нужно увеличить (это ловит `test_timeouts.py`).
- Время обнаружения измерено одним прогоном на сценарий; верхняя граница — формула по параметрам проверки, а
замер её подтверждает. Время считается от запуска команды отказа, с допуском 0,25 с на docker CLI и опрос.
- Rolling update проверен со сменой кода без смены схемы. Миграция, несовместимая с работающей версией
(удаление или переименование столбца), потребовала бы двух выпусков expand/contract; в лабе таких нет.
- `scripts/rolling-update.sh` и `restore.sh` используют `--no-recreate`: после замены с другим `API_IMAGE`
обычный `make up` пересоздаст реплики под текущий конфиг — это ожидаемо.
- Серии 1/2/4 реплик и поиск насыщения — трек «5», следующее изменение.