diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index e6e63eb..5237dab 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -1,18 +1,23 @@ ## Лабораторная 3 -Автор / группа: TODO -Целевая оценка (3/4/5): TODO -Трек 5, если заявлен: TODO +Автор / группа: Ромашко Владимир, БВТ2301 +Целевая оценка: **4**, Compose + nginx. Трек 5 не заявлен. -Что реализовано и что перенесено: TODO -Команды запуска из чистого clone: TODO -Результаты проверок и ссылка на REPORT.md: TODO -Ограничения / известные ошибки: TODO -Источники и использование ИИ: TODO +Реализованы две API-реплики за nginx, общие сессии и идемпотентность сообщений, +отдельные миграции, остановка каждой реплики и поочерёдная замена под нагрузкой. +Основа lab2 перенесена отдельным коммитом; изменены только необходимые для lab3 части. -- [ ] Весь обязательный минимум текущей и предыдущих работ сохранён с объявленными переходами. -- [ ] Контракт и публичные тесты не ослаблены. -- [ ] make check и make test выполнены; приложен реальный вывод. -- [ ] Сценарии отказов/безопасности своего уровня воспроизведены. -- [ ] Все секреты и приватные ключи находятся вне Git; отчёт не содержит tokens. -- [ ] README задания сохранён, REPORT.md содержит инструкцию именно моего решения. +Запуск: скопировать `.env.example` в `.env`, задать POSTGRES_PASSWORD, +выполнить `docker compose up -d --build --wait --wait-timeout 120`. +Проверки: `python -X utf8 scripts/verify_lab3.py` и +`docker compose exec -T api python -m unittest discover -s student-tests -v`. + +Результаты, ограничения и источники: [REPORT.md](../REPORT.md). +Использован Codex. PostgreSQL, Redis, nginx и host остаются единичными точками отказа. + +- [x] Возможности предыдущих работ сохранены с объявленными переходами. +- [x] Контракт и публичные тесты не ослаблены. +- [x] Эквиваленты make check/test выполнены; вывод приложен. +- [x] Отказ каждой реплики и поочерёдная замена воспроизведены. +- [x] Секреты вне Git, tokens в отчёте отсутствуют. +- [x] README задания сохранён, REPORT.md описывает решение. diff --git a/REPORT.md b/REPORT.md index c267900..12dc637 100644 --- a/REPORT.md +++ b/REPORT.md @@ -1,37 +1,191 @@ # Отчёт — лабораторная 3 -- Автор, группа: TODO -- Целевая оценка; выбранный трек 5, если нужен: TODO -- Commit/PR: TODO после публикации -- Использованные источники, библиотеки и помощь ИИ: TODO +- Автор, группа: Ромашко Владимир, БВТ2301. +- Целевая оценка: **4**, Docker Compose + nginx. +- Проверка: 23 октября 2026 года. +- Основа lab2 зафиксирована отдельным коммитом `cd9c340`. +- Использован Codex для реализации и проверок. Треки оценки 5 не заявлены. -## Запуск из чистого clone +## Запуск -TODO: версии runtime/образов, prerequisites, команды создания локальных secrets/.env, build, миграций, запуска, ожидания готовности, тестов и остановки. Указать необходимые действия оператора. Не вставлять секреты. Отдельно указать безопасную остановку и команду намеренного удаления учебных данных. +Нужны Docker Engine/Desktop с Compose v2 и Python 3.9+ на хосте. +Приложение работает на Python 3.12.8 в контейнере. -## Архитектура и решения +```powershell +Copy-Item .env.example .env +# Задать в .env случайный локальный POSTGRES_PASSWORD. +docker compose --env-file .env config --quiet +docker compose --env-file .env up -d --build --wait --wait-timeout 120 +python -X utf8 scripts/verify_lab3.py +docker compose exec -T api python -m unittest discover -s student-tests -v +``` -TODO: схема процессов/хранилищ, источник истины, транзакционные границы, ограничения. Что перенесено из lab2, что изменено в этой работе. Соответствие переменных из .env.example реальной конфигурации. +`verify_lab3.py` проверяет контракт, smoke, конкурентные повторы, полный restart, +отказ каждой API и поочерёдную замену под нагрузкой. Скрипт останавливает контейнеры +только этого проекта и восстанавливает реплики; volumes сохраняются. Запускать +без одновременного ручного управления стендом. Результаты пишутся в `evidence/`. -## Доказательства критериев +На Linux: `cp .env.example .env`, задать пароль, затем те же Docker-команды и +`python3 scripts/verify_lab3.py`. Перед тестами: -| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства | -| --- | --- | --- | --- | -| Публичный smoke | make test | TODO | TODO | -| Остальные пункты уровня 3 | TODO | TODO | TODO | -| Все пункты уровня 4, если заявлен | TODO | TODO | TODO | -| Выбранный трек 5, если заявлен | TODO | TODO | TODO | +```sh +chmod +x scripts/restart.sh scripts/stop-one.sh +make check +make test +make test-persistence ACTION_SCRIPT=scripts/restart.sh +make test-failover ACTION_SCRIPT=scripts/stop-one.sh +# Восстановить реплику после отдельного failover: +docker compose up -d --no-deps --no-recreate api +``` -TODO: добавить отдельную строку для каждого заявленного критерия. PASS без команды и наблюдения не является доказательством. Проверка инфраструктурного hook требует подтверждения, какие реальные процессы/хранилища перезапущены. +Windows-варианты отдельных проверок: -## Эксперименты и отказы +```powershell +python -X utf8 scripts/check_contract.py +python -X utf8 tests/smoke.py +python -X utf8 tests/resilience.py --mode persistence --action-script scripts/restart.cmd +python -X utf8 tests/resilience.py --mode failover --action-script scripts/stop-one.cmd +docker compose up -d --no-deps --no-recreate api +``` -TODO: гипотеза, hardware/лимиты, версии, объём данных, профиль нагрузки, concurrency/arrival rate, длительность/прогрев, повторы, успешные RPS, ошибки, p50/p95/p99, CPU/RAM. Сохранить raw summary без tokens и объяснить ограничения измерения. +На Windows make отсутствует: выполнены те же Python-команды, которые вызывают +цели Makefile. `-X utf8` нужен публичным скриптам для чтения файлов с русским текстом. +Контракт, публичные tests, Makefile и README задания не менялись. -| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных | -| --- | --- | --- | --- | -| TODO | TODO | TODO | TODO | +Остановка с сохранением данных: `docker compose down`. +Намеренное удаление всех учебных данных проекта: `docker compose down -v`. +При проверках volumes не удалялись. Исходный проект lab2 не изменялся. -## Ограничения и следующие шаги +## Архитектура -TODO: какие отказы выдерживаются и какие нет; что не реализовано; где учебное упрощение; какое улучшение подтверждено, а какое пока гипотеза. +Клиент → `127.0.0.1:8080` nginx → один Compose-service `api` с двумя репликами +→ общие PostgreSQL и Redis. У API нет опубликованных портов и `container_name`. +Sticky sessions нет. `X-Instance-Id` — hostname контейнера; его соответствие +реальному процессу проверяется через Docker. В каждом контейнере один Uvicorn worker. + +Из lab2 сохранены пользователи, чаты, сообщения, Argon2id, Redis-сессии с TTL, +миграции и кэш страниц истории. PostgreSQL — источник истины данных и ключей +идемпотентности. Redis хранит сессии с абсолютным expiry и AOF `appendfsync always`. +Кэш истории использует версию из PostgreSQL: после записи другая реплика не читает +старую версию страницы. Локального состояния сессий в API нет. + +Пароль хранится в игнорируемом `.env`. Он передаётся PostgreSQL, API и migrator. +Nginx не получает пароль. Volumes монтируются только соответствующему хранилищу. +API и хранилища находятся во внутренней сети backend, nginx также подключён к edge. + +| Сервис | Образ | CPU | RAM | +| --- | --- | ---: | ---: | +| API, каждая реплика | python:3.12.8-slim-bookworm + requirements.txt | 1 | 512 MiB | +| migrate, одноразовый | тот же образ приложения | 1 | 512 MiB | +| nginx | nginx:1.28.0-alpine | 0,5 | 128 MiB | +| PostgreSQL | postgres:17.4-bookworm | 1 | 512 MiB | +| Redis | redis:7.4.2-bookworm | 0,5 | 256 MiB | + +`.env.example` сохранён из lab2. `APP_PORT` меняет внешний порт nginx (тестам тогда +нужен `--base-url`); остальные используемые настройки — БД, TTL и лимиты запросов. +API внутри контейнера слушает 0.0.0.0:8080 независимо от APP_HOST в локальном .env. +В Compose заданы две реплики и образ `mtusi2026lab3-api:local`. + +## Идемпотентность + +POST сообщения требует ключ `[A-Za-z0-9._:-]{1,128}`. Область ключа: +пользователь + POST messages конкретного чата + ключ. Сначала проверяются сессия +и доступ. `SELECT FOR UPDATE` блокирует строку чата до поиска сохранённого результата. +Записи в один чат выполняются последовательно; разные чаты не блокируют друг друга. +Та же строка уже обновляется для инвалидации кэша, отдельный механизм блокировок не нужен. + +Сообщение, увеличение версии истории и запись ключа сохраняются одной транзакцией. +После COMMIT возвращается 201. Повтор возвращает тот же Message и 201, другое тело — +409. Сбой до COMMIT откатывает всё; неопределённый ответ после COMMIT можно повторить. +5xx не сохраняется как результат. Сравнивается значение `text`, а не JSON-байты. + +Ключи хранятся бессрочно, что обеспечивает обязательные 24 часа повторов. +Очистка не реализована: таблица растёт, использовать старый ключ для нового тела нельзя. + +## Health, DNS и остановка + +- `/health/live` проверяет процесс; `/health/ready` — PostgreSQL SELECT 1 и Redis PING. + Обе зависимости критичны для защищённых запросов. +- Docker healthcheck API: каждые 2 с, timeout 2 с, 2 неудачи, стартовый период 5 с. + После стартового периода верхняя оценка отметки unhealthy — 8 с. + Эта отметка сама по себе не управляет nginx. +- Nginx исключает backend пассивно: `max_fails=1`, `fail_timeout=2s`. + Учитываются сетевые ошибки, timeout, 502/503/504. При запросах connect-отказ + обнаруживается за ≤1 с, отсутствие ответа — за ≤6 с. Без трафика пассивная + проверка не имеет предельного времени обнаружения. Ошибки переходного периода допустимы. +- Nginx использует Docker DNS `127.0.0.11`, `valid=2s`, resolver timeout 1 с, + `server api:8080 resolve`. Новые адреса появляются без reload nginx. +- GET может перейти на второй backend: до 2 попыток. Бюджет выбора следующей + попытки — 8 с, это не абсолютный deadline всего запроса. Уже отправленный POST + автоматически не повторяется; клиент повторяет сообщение с прежним ключом. +- PostgreSQL: connect 2 с, pool wait 2 с, statement 3 с, lock 2 с; pool до 10/API. + Redis: connect/read по 1 с. Это таймауты отдельных операций. +- Uvicorn получает SIGTERM как PID 1, прекращает приём соединений и даёт активным + запросам до 5 с. Compose ждёт 10 с, action script — 8 с до SIGKILL. + +## Миграции и поочерёдная замена + +Отдельный сервис `migrate` применяет SQL перед запуском API. Startup API миграций +не выполняет. Реестр версий и перенесённая из lab2 блокировка миграций позволяют +безопасно повторять запуск. Миграция 003 только добавляет таблицу ключей. + +`python -X utf8 scripts/rolling.py` собирает образ, один раз запускает migrator, +затем заменяет API по одной: stop выбранного контейнера, удаление только этого +остановленного контейнера, `compose up --no-recreate --scale api=2`, ожидание health +и 3 с на DNS. Соседняя реплика продолжает работать; volumes не удаляются. + +Проверена замена контейнеров текущей версии под нагрузкой. Смешанный переход +lab2→lab3 не поддерживается: lab2 ещё не обеспечивает ключи и X-Instance-Id. +Несовместимые будущие изменения схемы потребуют отдельного порядка обновления. + +## Результаты + +Среда: Docker Desktop Linux x86_64, Engine 28.5.1, Compose 2.40.0; +Docker VM — 8 CPU и 8 328 015 872 байт RAM. Данные синтетические, токены не сохраняются. + +Нагрузка: 2 клиента, каждый пишет сообщение, читает чат, ждёт 20 мс. До воздействия +3 с, весь сценарий минимум 20 с и минимум 5 с после завершения воздействия. +После него сверяется вся история, подтверждения и отсутствие дублей; повторяется +прежний ключ. RPS — успешные HTTP-ответы, latency — только успешные запросы. +Один прогон на воздействие, closed-loop нагрузка: это не предел производительности. +Время восстановления считается от начала action до первого успешного read/write +после его завершения, включая время Docker CLI. + +| Проверка | Результат | Доказательство | +| --- | --- | --- | +| Контракт и smoke через nginx | PASS | [check.txt](evidence/check.txt), [final-smoke.txt](evidence/final-smoke.txt) | +| Регрессия lab2, миграции, rollback и гонка разных тел | 15 тестов OK | [unit-tests.txt](evidence/unit-tests.txt) | +| Один ключ через разные API | 24 запроса, concurrency 8, 2 реплики, 1 сообщение | [idempotency.json](evidence/idempotency.json) | +| Restart API, LB, PostgreSQL и Redis | Прежняя сессия, сообщения и результат ключа сохранены | [persistence.txt](evidence/persistence.txt), [restart.txt](evidence/restart.txt), [idempotency-restart.json](evidence/idempotency-restart.json) | +| Публичный failover, два запуска с восстановлением | PASS, по 124 записи, 0 ошибок; 2,204 / 2,233 с | [Первый](evidence/public-failover-1.txt), [второй](evidence/public-failover-2.txt) | +| Отдельно остановлена каждая API | PASS, прежняя сессия, потерь и дублей нет | [failover-1.json](evidence/failover-1.json), [failover-2.json](evidence/failover-2.json) | +| Поочерёдная замена под нагрузкой | Обе исходные API заменены, 0 ошибок, данные сохранены | [rolling-load.json](evidence/rolling-load.json), включая снимки контейнеров | +| Nginx, health, DNS, SIGTERM, лимиты и порты | Nginx config OK; остановленные ID исчезают, новые появляются; обе API healthy, порт только у LB | [nginx-check.txt](evidence/nginx-check.txt), [final-containers.json](evidence/final-containers.json) | +| Отдельные миграции | 001/002/003 применяются повторно без дублирования; чистая схема проверена | [unit-tests.txt](evidence/unit-tests.txt), [compose.yaml](compose.yaml) | + +| Воздействие | HTTP/с | Записей/с | Ошибок | p50 / p95 / p99, мс | Первые read / write после stop, с | +| --- | ---: | ---: | ---: | --- | --- | +| Stop 6fc32ef53bc9 | 61.9 | 30.95 | 0 | 18.0 / 52.71 / 71.25 | 2.466 / 2.458 | +| Stop a6ee3d7e3779 | 65.84 | 32.92 | 0 | 16.38 / 48.29 / 70.66 | 2.409 / 2.397 | +| Замена обеих API | 62.91 | 31.45 | 0 | 16.51 / 48.68 / 75.14 | Запросы продолжались всю замену | + +Замена заняла 29.127 с, включая ожидание health и DNS. +Это длительность операции, не простой API. Максимальный интервал между успешными +ответами: read 0.216 с, write 0.231 с. +Полная сводка: [grade4-summary.json](evidence/grade4-summary.json). + +Сохраняются сводки измерений, ошибки и снимки реальных контейнеров, без тысяч +отдельных сообщений. Доказательство исходного переноса: [baseline-lab2.txt](evidence/baseline-lab2.txt). + +## Ограничения и источники + +Выдерживается отказ одной API при работающей соседней и общих зависимостях. +Nginx, PostgreSQL, Redis и Docker-host остаются единичными точками отказа. +HTTP предназначен для локального учебного стенда. Создание пользователей/чатов +не имеет гарантии идемпотентного повтора. Уровень 5 и отказ узла не заявлены. + +- [Compose services](https://docs.docker.com/reference/compose-file/services/). +- [Nginx upstream](https://nginx.org/en/docs/http/ngx_http_upstream_module.html). +- [Nginx proxy](https://nginx.org/en/docs/http/ngx_http_proxy_module.html). +- [Uvicorn shutdown](https://uvicorn.dev/server-behavior/). +- Контракт и публичные тесты репозитория, собственная реализация lab2. diff --git a/compose.yaml b/compose.yaml index e895236..a9d141a 100644 --- a/compose.yaml +++ b/compose.yaml @@ -1,30 +1,71 @@ +x-api: &api + image: mtusi2026lab3-api:local + build: . + dns_opt: + - timeout:1 + - attempts:1 + environment: + APP_HOST: 0.0.0.0 + APP_PORT: 8080 + POSTGRES_HOST: postgres + POSTGRES_DB: ${POSTGRES_DB:-messenger} + POSTGRES_USER: ${POSTGRES_USER:-messenger} + POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?Set POSTGRES_PASSWORD in .env} + REDIS_URL: redis://redis:6379/0 + SESSION_TTL_SECONDS: ${SESSION_TTL_SECONDS:-3600} + CACHE_TTL_SECONDS: ${CACHE_TTL_SECONDS:-30} + MAX_REQUEST_BYTES: ${MAX_REQUEST_BYTES:-65536} + MAX_INFLIGHT: ${MAX_INFLIGHT:-32} + networks: [backend] + cpus: 1.0 + mem_limit: 512m + stop_grace_period: 10s + services: api: - build: . - dns_opt: - - timeout:1 - - attempts:1 - ports: - - "127.0.0.1:${APP_PORT:-8080}:8080" - environment: - APP_HOST: 0.0.0.0 - APP_PORT: 8080 - POSTGRES_HOST: postgres - POSTGRES_DB: ${POSTGRES_DB:-messenger} - POSTGRES_USER: ${POSTGRES_USER:-messenger} - POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?Set POSTGRES_PASSWORD in .env} - REDIS_URL: redis://redis:6379/0 - SESSION_TTL_SECONDS: ${SESSION_TTL_SECONDS:-3600} - CACHE_TTL_SECONDS: ${CACHE_TTL_SECONDS:-30} - MAX_REQUEST_BYTES: ${MAX_REQUEST_BYTES:-65536} - MAX_INFLIGHT: ${MAX_INFLIGHT:-32} + <<: *api + deploy: + replicas: 2 + depends_on: + migrate: + condition: service_completed_successfully + redis: + condition: service_healthy + healthcheck: + test: [CMD, python, -c, "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8080/health/ready', timeout=1).read()"] + interval: 2s + timeout: 2s + start_period: 5s + retries: 2 + + migrate: + <<: *api + command: [python, -m, src.database] + healthcheck: + disable: true + restart: 'no' depends_on: postgres: condition: service_healthy - redis: + + nginx: + image: nginx:1.28.0-alpine + ports: + - '127.0.0.1:${APP_PORT:-8080}:8080' + volumes: + - ./infra/nginx.conf:/etc/nginx/nginx.conf:ro + networks: [edge, backend] + depends_on: + api: condition: service_healthy - cpus: 1.0 - mem_limit: 512m + healthcheck: + test: [CMD-SHELL, 'wget -q -O /dev/null http://127.0.0.1:8080/health/ready'] + interval: 2s + timeout: 2s + retries: 3 + cpus: 0.5 + mem_limit: 128m + stop_grace_period: 10s postgres: image: postgres:17.4-bookworm @@ -34,6 +75,7 @@ services: POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?Set POSTGRES_PASSWORD in .env} volumes: - postgres_data:/var/lib/postgresql/data + networks: [backend] healthcheck: test: ["CMD-SHELL", "pg_isready -U $$POSTGRES_USER -d $$POSTGRES_DB"] interval: 2s @@ -47,6 +89,7 @@ services: command: ["redis-server", "--appendonly", "yes", "--appendfsync", "always", "--maxmemory", "128mb", "--maxmemory-policy", "noeviction"] volumes: - redis_data:/data + networks: [backend] healthcheck: test: ["CMD", "redis-cli", "ping"] interval: 2s @@ -55,6 +98,10 @@ services: cpus: 0.5 mem_limit: 256m +networks: + edge: + backend: + internal: true volumes: postgres_data: redis_data: diff --git a/evidence/check.txt b/evidence/check.txt new file mode 100644 index 0000000..b62af9c --- /dev/null +++ b/evidence/check.txt @@ -0,0 +1 @@ +PASS: offline skeleton structure, local refs and Python syntax; application NOT tested. diff --git a/evidence/failover-1.json b/evidence/failover-1.json new file mode 100644 index 0000000..95dfab2 --- /dev/null +++ b/evidence/failover-1.json @@ -0,0 +1,88 @@ +{ + "summary": { + "duration_seconds": 20.032, + "concurrency": 2, + "successful_http_rps": 61.9, + "successful_write_rps": 30.95, + "successful_requests": 1240, + "errors": 0, + "action_started_seconds": 3.001, + "action_finished_seconds": 5.454, + "first_read_write_after_action_seconds_from_start": { + "read": 2.466, + "write": 2.458 + }, + "max_success_gap_seconds": { + "read": 0.12, + "write": 0.116 + }, + "latency_ms": { + "50": 18.0, + "95": 52.71, + "99": 71.25 + }, + "confirmed_messages_preserved": true, + "duplicate_messages": 0, + "instances": [ + "6fc32ef53bc9", + "a6ee3d7e3779" + ], + "target": "6fc32ef53bc9" + }, + "containers": { + "target": "6fc32ef53bc9", + "before": [ + { + "id": "6fc32ef53bc923ae2b9300d22d99d833c1b59a0689e6cbbb78ca3dab0a1654d6", + "name": "/mtusi2026lab3-api-3", + "instance": "6fc32ef53bc9", + "image": "sha256:cc3df05d4a5e2283a9dd616442a821fa2a8a4a81a67e4d407a7395c3fcb9f082", + "state": "running", + "started": "2026-10-23T12:19:29.450305334Z", + "health": "healthy", + "cpu": 1000000000, + "memory": 536870912, + "ports": {} + }, + { + "id": "a6ee3d7e3779d847efe497f22021f9942f805202ade85495734e1f93418aeb5a", + "name": "/mtusi2026lab3-api-4", + "instance": "a6ee3d7e3779", + "image": "sha256:cc3df05d4a5e2283a9dd616442a821fa2a8a4a81a67e4d407a7395c3fcb9f082", + "state": "running", + "started": "2026-10-23T12:20:24.84845663Z", + "health": "healthy", + "cpu": 1000000000, + "memory": 536870912, + "ports": {} + } + ], + "after": [ + { + "id": "6fc32ef53bc923ae2b9300d22d99d833c1b59a0689e6cbbb78ca3dab0a1654d6", + "name": "/mtusi2026lab3-api-3", + "instance": "6fc32ef53bc9", + "image": "sha256:cc3df05d4a5e2283a9dd616442a821fa2a8a4a81a67e4d407a7395c3fcb9f082", + "state": "exited", + "started": "2026-10-23T12:19:29.450305334Z", + "health": "unhealthy", + "cpu": 1000000000, + "memory": 536870912, + "ports": {} + }, + { + "id": "a6ee3d7e3779d847efe497f22021f9942f805202ade85495734e1f93418aeb5a", + "name": "/mtusi2026lab3-api-4", + "instance": "a6ee3d7e3779", + "image": "sha256:cc3df05d4a5e2283a9dd616442a821fa2a8a4a81a67e4d407a7395c3fcb9f082", + "state": "running", + "started": "2026-10-23T12:20:24.84845663Z", + "health": "healthy", + "cpu": 1000000000, + "memory": 536870912, + "ports": {} + } + ] + }, + "errors": [] +} diff --git a/evidence/failover-2.json b/evidence/failover-2.json new file mode 100644 index 0000000..34fbcc6 --- /dev/null +++ b/evidence/failover-2.json @@ -0,0 +1,88 @@ +{ + "summary": { + "duration_seconds": 20.05, + "concurrency": 2, + "successful_http_rps": 65.84, + "successful_write_rps": 32.92, + "successful_requests": 1320, + "errors": 0, + "action_started_seconds": 3.001, + "action_finished_seconds": 5.363, + "first_read_write_after_action_seconds_from_start": { + "read": 2.409, + "write": 2.397 + }, + "max_success_gap_seconds": { + "read": 0.114, + "write": 0.102 + }, + "latency_ms": { + "50": 16.38, + "95": 48.29, + "99": 70.66 + }, + "confirmed_messages_preserved": true, + "duplicate_messages": 0, + "instances": [ + "6fc32ef53bc9", + "a6ee3d7e3779" + ], + "target": "a6ee3d7e3779" + }, + "containers": { + "target": "a6ee3d7e3779", + "before": [ + { + "id": "6fc32ef53bc923ae2b9300d22d99d833c1b59a0689e6cbbb78ca3dab0a1654d6", + "name": "/mtusi2026lab3-api-3", + "instance": "6fc32ef53bc9", + "image": "sha256:cc3df05d4a5e2283a9dd616442a821fa2a8a4a81a67e4d407a7395c3fcb9f082", + "state": "running", + "started": "2026-10-23T12:20:57.481834724Z", + "health": "healthy", + "cpu": 1000000000, + "memory": 536870912, + "ports": {} + }, + { + "id": "a6ee3d7e3779d847efe497f22021f9942f805202ade85495734e1f93418aeb5a", + "name": "/mtusi2026lab3-api-4", + "instance": "a6ee3d7e3779", + "image": "sha256:cc3df05d4a5e2283a9dd616442a821fa2a8a4a81a67e4d407a7395c3fcb9f082", + "state": "running", + "started": "2026-10-23T12:20:24.84845663Z", + "health": "healthy", + "cpu": 1000000000, + "memory": 536870912, + "ports": {} + } + ], + "after": [ + { + "id": "6fc32ef53bc923ae2b9300d22d99d833c1b59a0689e6cbbb78ca3dab0a1654d6", + "name": "/mtusi2026lab3-api-3", + "instance": "6fc32ef53bc9", + "image": "sha256:cc3df05d4a5e2283a9dd616442a821fa2a8a4a81a67e4d407a7395c3fcb9f082", + "state": "running", + "started": "2026-10-23T12:20:57.481834724Z", + "health": "healthy", + "cpu": 1000000000, + "memory": 536870912, + "ports": {} + }, + { + "id": "a6ee3d7e3779d847efe497f22021f9942f805202ade85495734e1f93418aeb5a", + "name": "/mtusi2026lab3-api-4", + "instance": "a6ee3d7e3779", + "image": "sha256:cc3df05d4a5e2283a9dd616442a821fa2a8a4a81a67e4d407a7395c3fcb9f082", + "state": "exited", + "started": "2026-10-23T12:20:24.84845663Z", + "health": "unhealthy", + "cpu": 1000000000, + "memory": 536870912, + "ports": {} + } + ] + }, + "errors": [] +} diff --git a/evidence/final-containers.json b/evidence/final-containers.json new file mode 100644 index 0000000..a9d568b --- /dev/null +++ b/evidence/final-containers.json @@ -0,0 +1,81 @@ +[ + { + "id": "52a2db0bf074fa8d0c8ac02253549dabd0fb214d4c2ab35eaa64174c43687f52", + "name": "/mtusi2026lab3-api-5", + "instance": "52a2db0bf074", + "image": "sha256:24f3d4879fd558d1741b8c68e8d6dd7ad1c3c2622d344e21d1f261c44ad6a168", + "state": "running", + "started": "2026-10-23T12:34:15.338654375Z", + "health": "healthy", + "cpu": 1000000000, + "memory": 536870912, + "ports": {} + }, + { + "id": "c5211dc7b5256fc33563384f55525ce3f39839ad27c16205aad0a6f33364ae4a", + "name": "/mtusi2026lab3-api-6", + "instance": "c5211dc7b525", + "image": "sha256:24f3d4879fd558d1741b8c68e8d6dd7ad1c3c2622d344e21d1f261c44ad6a168", + "state": "running", + "started": "2026-10-23T12:34:15.606253965Z", + "health": "healthy", + "cpu": 1000000000, + "memory": 536870912, + "ports": {} + }, + { + "id": "0fec18666f11eaf3b139f22852b71383ec3cf06b9cf171053950ca887a15119a", + "name": "/mtusi2026lab3-migrate-1", + "instance": "0fec18666f11", + "image": "sha256:24f3d4879fd558d1741b8c68e8d6dd7ad1c3c2622d344e21d1f261c44ad6a168", + "state": "exited", + "started": "2026-10-23T12:34:13.577380317Z", + "health": null, + "cpu": 1000000000, + "memory": 536870912, + "ports": {} + }, + { + "id": "cb856359deb9d61c5130f7d9374aa7cecbe39999902e8f87560f4d5fc1a62f79", + "name": "/mtusi2026lab3-nginx-1", + "instance": "cb856359deb9", + "image": "sha256:30f1c0d78e0ad60901648be663a710bdadf19e4c10ac6782c235200619158284", + "state": "running", + "started": "2026-10-23T12:19:29.173913476Z", + "health": "healthy", + "cpu": 500000000, + "memory": 134217728, + "ports": { + "8080/tcp": [ + { + "HostIp": "127.0.0.1", + "HostPort": "8080" + } + ] + } + }, + { + "id": "a1b2b187e907fcf6ce3b44fbc7c9a5fa807de2b5350d9633656dceab841a658e", + "name": "/mtusi2026lab3-postgres-1", + "instance": "a1b2b187e907", + "image": "sha256:304ab813518754228f9f792f79d6da36359b82d8ecf418096c636725f8c930ad", + "state": "running", + "started": "2026-10-23T12:19:28.899601583Z", + "health": "healthy", + "cpu": 1000000000, + "memory": 536870912, + "ports": {} + }, + { + "id": "57f3df8ca10975f9a4375878acc2ef8f668b0436abce7ef374e6f9193ccf0500", + "name": "/mtusi2026lab3-redis-1", + "instance": "57f3df8ca109", + "image": "sha256:fbdbaea47b9ae4ecc2082ecdb4e1cea81e32176ffb1dcf643d422ad07427e5d9", + "state": "running", + "started": "2026-10-23T12:19:28.754756013Z", + "health": "healthy", + "cpu": 500000000, + "memory": 268435456, + "ports": {} + } +] diff --git a/evidence/final-smoke.txt b/evidence/final-smoke.txt new file mode 100644 index 0000000..fc20f9d --- /dev/null +++ b/evidence/final-smoke.txt @@ -0,0 +1 @@ +PASS: lab3 public API scenario; infrastructure and grading evidence remain separate. diff --git a/evidence/grade4-summary.json b/evidence/grade4-summary.json new file mode 100644 index 0000000..d6f8410 --- /dev/null +++ b/evidence/grade4-summary.json @@ -0,0 +1,94 @@ +{ + "failover-1": { + "duration_seconds": 20.032, + "concurrency": 2, + "successful_http_rps": 61.9, + "successful_write_rps": 30.95, + "successful_requests": 1240, + "errors": 0, + "action_started_seconds": 3.001, + "action_finished_seconds": 5.454, + "first_read_write_after_action_seconds_from_start": { + "read": 2.466, + "write": 2.458 + }, + "max_success_gap_seconds": { + "read": 0.12, + "write": 0.116 + }, + "latency_ms": { + "50": 18.0, + "95": 52.71, + "99": 71.25 + }, + "confirmed_messages_preserved": true, + "duplicate_messages": 0, + "instances": [ + "6fc32ef53bc9", + "a6ee3d7e3779" + ], + "target": "6fc32ef53bc9" + }, + "failover-2": { + "duration_seconds": 20.05, + "concurrency": 2, + "successful_http_rps": 65.84, + "successful_write_rps": 32.92, + "successful_requests": 1320, + "errors": 0, + "action_started_seconds": 3.001, + "action_finished_seconds": 5.363, + "first_read_write_after_action_seconds_from_start": { + "read": 2.409, + "write": 2.397 + }, + "max_success_gap_seconds": { + "read": 0.114, + "write": 0.102 + }, + "latency_ms": { + "50": 16.38, + "95": 48.29, + "99": 70.66 + }, + "confirmed_messages_preserved": true, + "duplicate_messages": 0, + "instances": [ + "6fc32ef53bc9", + "a6ee3d7e3779" + ], + "target": "a6ee3d7e3779" + }, + "rolling": { + "duration_seconds": 37.166, + "concurrency": 2, + "successful_http_rps": 62.91, + "successful_write_rps": 31.45, + "successful_requests": 2338, + "errors": 0, + "action_started_seconds": 3.001, + "action_finished_seconds": 32.128, + "first_read_write_after_action_seconds_from_start": { + "read": 29.135, + "write": 29.137 + }, + "max_success_gap_seconds": { + "read": 0.216, + "write": 0.231 + }, + "latency_ms": { + "50": 16.51, + "95": 48.68, + "99": 75.14 + }, + "confirmed_messages_preserved": true, + "duplicate_messages": 0, + "instances": [ + "6fc32ef53bc9", + "8c864b1beb6a", + "a6ee3d7e3779", + "bb8669ea27d1" + ], + "target": null + } +} diff --git a/evidence/idempotency-restart.json b/evidence/idempotency-restart.json new file mode 100644 index 0000000..69e0c87 --- /dev/null +++ b/evidence/idempotency-restart.json @@ -0,0 +1,4 @@ +{ + "same_token": true, + "same_201_message": true +} diff --git a/evidence/idempotency.json b/evidence/idempotency.json new file mode 100644 index 0000000..12a3216 --- /dev/null +++ b/evidence/idempotency.json @@ -0,0 +1,11 @@ +{ + "requests": 24, + "concurrency": 8, + "instances": [ + "6fc32ef53bc9", + "a6ee3d7e3779" + ], + "unique_messages": 1, + "same_response": true, + "conflict_auth_access_key_scope": "PASS" +} diff --git a/evidence/nginx-check.txt b/evidence/nginx-check.txt new file mode 100644 index 0000000..159c3ad --- /dev/null +++ b/evidence/nginx-check.txt @@ -0,0 +1,2 @@ +nginx: the configuration file /etc/nginx/nginx.conf syntax is ok +nginx: configuration file /etc/nginx/nginx.conf test is successful diff --git a/evidence/persistence.txt b/evidence/persistence.txt new file mode 100644 index 0000000..749fd29 --- /dev/null +++ b/evidence/persistence.txt @@ -0,0 +1,2 @@ +Executing explicit persistence hook; hook output suppressed to avoid leaking secrets. +PASS: persistence preserved confirmed data and existing session. Hook scope needs operator evidence. diff --git a/evidence/public-failover-1.txt b/evidence/public-failover-1.txt new file mode 100644 index 0000000..51c081c --- /dev/null +++ b/evidence/public-failover-1.txt @@ -0,0 +1,3 @@ +Executing explicit failover hook; hook output suppressed to avoid leaking secrets. +{"observed_instances_before": 2, "successful_writes": 124, "failed_attempts": 0, "first_recovery_seconds": 2.204} +PASS: failover preserved confirmed data and existing session. Hook scope needs operator evidence. diff --git a/evidence/public-failover-2.txt b/evidence/public-failover-2.txt new file mode 100644 index 0000000..9c90634 --- /dev/null +++ b/evidence/public-failover-2.txt @@ -0,0 +1,3 @@ +Executing explicit failover hook; hook output suppressed to avoid leaking secrets. +{"observed_instances_before": 2, "successful_writes": 124, "failed_attempts": 0, "first_recovery_seconds": 2.233} +PASS: failover preserved confirmed data and existing session. Hook scope needs operator evidence. diff --git a/evidence/restart.txt b/evidence/restart.txt new file mode 100644 index 0000000..c840750 --- /dev/null +++ b/evidence/restart.txt @@ -0,0 +1,13 @@ +Command: docker compose restart api postgres redis nginx +Before (UTC): +/mtusi2026lab3-api-3 2026-10-23T12:18:00.276504145Z +/mtusi2026lab3-api-4 2026-10-23T12:18:00.50467995Z +/mtusi2026lab3-nginx-1 2026-10-23T12:18:06.464884093Z +/mtusi2026lab3-postgres-1 2026-10-23T12:17:55.596165683Z +/mtusi2026lab3-redis-1 2026-10-23T12:17:55.593753417Z +After (UTC): +/mtusi2026lab3-api-3 2026-10-23T12:19:29.450305334Z +/mtusi2026lab3-api-4 2026-10-23T12:19:29.302397436Z +/mtusi2026lab3-nginx-1 2026-10-23T12:19:29.173913476Z +/mtusi2026lab3-postgres-1 2026-10-23T12:19:28.899601583Z +/mtusi2026lab3-redis-1 2026-10-23T12:19:28.754756013Z diff --git a/evidence/rolling-load.json b/evidence/rolling-load.json new file mode 100644 index 0000000..ac5fdf0 --- /dev/null +++ b/evidence/rolling-load.json @@ -0,0 +1,149 @@ +{ + "summary": { + "duration_seconds": 37.166, + "concurrency": 2, + "successful_http_rps": 62.91, + "successful_write_rps": 31.45, + "successful_requests": 2338, + "errors": 0, + "action_started_seconds": 3.001, + "action_finished_seconds": 32.128, + "first_read_write_after_action_seconds_from_start": { + "read": 29.135, + "write": 29.137 + }, + "max_success_gap_seconds": { + "read": 0.216, + "write": 0.231 + }, + "latency_ms": { + "50": 16.51, + "95": 48.68, + "99": 75.14 + }, + "confirmed_messages_preserved": true, + "duplicate_messages": 0, + "instances": [ + "6fc32ef53bc9", + "8c864b1beb6a", + "a6ee3d7e3779", + "bb8669ea27d1" + ], + "target": null + }, + "containers": { + "before": [ + { + "id": "6fc32ef53bc923ae2b9300d22d99d833c1b59a0689e6cbbb78ca3dab0a1654d6", + "name": "/mtusi2026lab3-api-3", + "instance": "6fc32ef53bc9", + "image": "sha256:cc3df05d4a5e2283a9dd616442a821fa2a8a4a81a67e4d407a7395c3fcb9f082", + "state": "running", + "started": "2026-10-23T12:20:57.481834724Z", + "health": "healthy", + "cpu": 1000000000, + "memory": 536870912, + "ports": {} + }, + { + "id": "a6ee3d7e3779d847efe497f22021f9942f805202ade85495734e1f93418aeb5a", + "name": "/mtusi2026lab3-api-4", + "instance": "a6ee3d7e3779", + "image": "sha256:cc3df05d4a5e2283a9dd616442a821fa2a8a4a81a67e4d407a7395c3fcb9f082", + "state": "running", + "started": "2026-10-23T12:21:29.455170279Z", + "health": "healthy", + "cpu": 1000000000, + "memory": 536870912, + "ports": {} + } + ], + "steps": [ + { + "replaced": "6fc32ef53bc923ae2b9300d22d99d833c1b59a0689e6cbbb78ca3dab0a1654d6", + "ready": [ + { + "id": "a6ee3d7e3779d847efe497f22021f9942f805202ade85495734e1f93418aeb5a", + "name": "/mtusi2026lab3-api-4", + "instance": "a6ee3d7e3779", + "image": "sha256:cc3df05d4a5e2283a9dd616442a821fa2a8a4a81a67e4d407a7395c3fcb9f082", + "state": "running", + "started": "2026-10-23T12:21:29.455170279Z", + "health": "healthy", + "cpu": 1000000000, + "memory": 536870912, + "ports": {} + }, + { + "id": "8c864b1beb6a090a0eff2397fe989ab21ebd0190291f164e6df7dacf7285e82a", + "name": "/mtusi2026lab3-api-5", + "instance": "8c864b1beb6a", + "image": "sha256:7eed22c328d1b387371156ba7c4a30a8017bd48be3acb0b94b63c561925b43ea", + "state": "running", + "started": "2026-10-23T12:21:55.548004137Z", + "health": "healthy", + "cpu": 1000000000, + "memory": 536870912, + "ports": {} + } + ] + }, + { + "replaced": "a6ee3d7e3779d847efe497f22021f9942f805202ade85495734e1f93418aeb5a", + "ready": [ + { + "id": "8c864b1beb6a090a0eff2397fe989ab21ebd0190291f164e6df7dacf7285e82a", + "name": "/mtusi2026lab3-api-5", + "instance": "8c864b1beb6a", + "image": "sha256:7eed22c328d1b387371156ba7c4a30a8017bd48be3acb0b94b63c561925b43ea", + "state": "running", + "started": "2026-10-23T12:21:55.548004137Z", + "health": "healthy", + "cpu": 1000000000, + "memory": 536870912, + "ports": {} + }, + { + "id": "bb8669ea27d1bd1fa5b6442a1d1ebcc689aa0ec3991dffdfaa5cb96fb61fe5da", + "name": "/mtusi2026lab3-api-6", + "instance": "bb8669ea27d1", + "image": "sha256:7eed22c328d1b387371156ba7c4a30a8017bd48be3acb0b94b63c561925b43ea", + "state": "running", + "started": "2026-10-23T12:22:08.293929923Z", + "health": "healthy", + "cpu": 1000000000, + "memory": 536870912, + "ports": {} + } + ] + } + ], + "after": [ + { + "id": "8c864b1beb6a090a0eff2397fe989ab21ebd0190291f164e6df7dacf7285e82a", + "name": "/mtusi2026lab3-api-5", + "instance": "8c864b1beb6a", + "image": "sha256:7eed22c328d1b387371156ba7c4a30a8017bd48be3acb0b94b63c561925b43ea", + "state": "running", + "started": "2026-10-23T12:21:55.548004137Z", + "health": "healthy", + "cpu": 1000000000, + "memory": 536870912, + "ports": {} + }, + { + "id": "bb8669ea27d1bd1fa5b6442a1d1ebcc689aa0ec3991dffdfaa5cb96fb61fe5da", + "name": "/mtusi2026lab3-api-6", + "instance": "bb8669ea27d1", + "image": "sha256:7eed22c328d1b387371156ba7c4a30a8017bd48be3acb0b94b63c561925b43ea", + "state": "running", + "started": "2026-10-23T12:22:08.293929923Z", + "health": "healthy", + "cpu": 1000000000, + "memory": 536870912, + "ports": {} + } + ] + }, + "errors": [] +} diff --git a/evidence/unit-tests.txt b/evidence/unit-tests.txt new file mode 100644 index 0000000..0af7205 --- /dev/null +++ b/evidence/unit-tests.txt @@ -0,0 +1,20 @@ +test_concurrent_writers_do_not_lose_version_increments (test_cache.CacheTests.test_concurrent_writers_do_not_lose_version_increments) ... ok +test_hit_still_checks_membership_and_cache_failure_falls_back (test_cache.CacheTests.test_hit_still_checks_membership_and_cache_failure_falls_back) ... ok +test_http_read_after_write_and_cursor_pages (test_cache.CacheTests.test_http_read_after_write_and_cursor_pages) ... ok +test_late_fill_cannot_restore_old_page (test_cache.CacheTests.test_late_fill_cannot_restore_old_page) ... ok +test_read_after_write_through_another_api_process (test_cache.CacheTests.test_read_after_write_through_another_api_process) ... ok +test_version_rolls_back_with_failed_message (test_cache.CacheTests.test_version_rolls_back_with_failed_message) ... ok +test_migrate_empty_schema_and_preserve_orm_data_on_repeat (test_database.MigrationTests.test_migrate_empty_schema_and_preserve_orm_data_on_repeat) ... ok +test_concurrent_different_payloads_have_one_winner (test_idempotency.IdempotencyTests.test_concurrent_different_payloads_have_one_winner) ... ok +test_record_and_message_rollback_together (test_idempotency.IdempotencyTests.test_record_and_message_rollback_together) ... ok +test_chat_rollback (test_lab2.Lab2Tests.test_chat_rollback) ... ok +test_expiry_short_ttl (test_lab2.Lab2Tests.test_expiry_short_ttl) ... ok +test_migrations_repeat (test_lab2.Lab2Tests.test_migrations_repeat) ... ok +test_password_logout_and_identity (test_lab2.Lab2Tests.test_password_logout_and_identity) ... ok +test_registration_race (test_lab2.Lab2Tests.test_registration_race) ... ok +test_unicode_password (test_lab2.Lab2Tests.test_unicode_password) ... ok + +---------------------------------------------------------------------- +Ran 15 tests in 19.204s + +OK diff --git a/infra/nginx.conf b/infra/nginx.conf new file mode 100644 index 0000000..fc7ecdb --- /dev/null +++ b/infra/nginx.conf @@ -0,0 +1,35 @@ +worker_processes 1; +worker_shutdown_timeout 8s; +events { worker_connections 1024; } +http { + resolver 127.0.0.11 valid=2s ipv6=off; + resolver_timeout 1s; + upstream messenger { + zone messenger 64k; + server api:8080 resolve max_fails=1 fail_timeout=2s; + } + log_format upstream '$request_method $uri $status upstream=$upstream_addr ' + 'upstream_status=$upstream_status time=$request_time'; + access_log /var/log/nginx/access.log upstream; + server { + listen 8080; + client_max_body_size 64k; + client_body_timeout 5s; + client_header_timeout 5s; + keepalive_timeout 5s; + location / { + proxy_pass http://messenger; + proxy_http_version 1.1; + proxy_set_header Host $host; + proxy_set_header Connection close; + proxy_connect_timeout 1s; + proxy_send_timeout 6s; + proxy_read_timeout 6s; + proxy_next_upstream error timeout http_502 http_503 http_504; + proxy_next_upstream_tries 2; + proxy_next_upstream_timeout 8s; + # Never transparently retry a POST already sent to an API. + # A client retries messages using the original Idempotency-Key. + } + } +} diff --git a/migrations/003_message_idempotency.sql b/migrations/003_message_idempotency.sql new file mode 100644 index 0000000..434b1e2 --- /dev/null +++ b/migrations/003_message_idempotency.sql @@ -0,0 +1,9 @@ +-- Additive migration: no rewrite of existing lab2 tables or messages. +CREATE TABLE message_idempotency ( + actor_id uuid NOT NULL REFERENCES users(id), + chat_id uuid NOT NULL REFERENCES chats(id) ON DELETE CASCADE, + key text NOT NULL CHECK (key ~ '^[A-Za-z0-9._:-]{1,128}$'), + message_id uuid NOT NULL REFERENCES messages(id) ON DELETE CASCADE, + created_at timestamptz NOT NULL DEFAULT clock_timestamp(), + PRIMARY KEY (actor_id, chat_id, key) +); diff --git a/scripts/ops.py b/scripts/ops.py new file mode 100644 index 0000000..9e86362 --- /dev/null +++ b/scripts/ops.py @@ -0,0 +1,79 @@ +"""Project-scoped Docker operations; never read/export container environments.""" +import json +import subprocess +import time +from pathlib import Path + +ROOT = Path(__file__).resolve().parents[1] + + +def docker(*args): + return subprocess.check_output(['docker', *args], cwd=ROOT, text=True, timeout=120).strip() + + +def compose(*args): + return docker('compose', *args) + + +def snapshot(service=None): + ids = compose('ps', '-a', '-q', *([service] if service else [])).split() + if not ids: + return [] + # Select fields before returning; no secrets in evidence. + template = ('{"id":{{json .Id}},"name":{{json .Name}},"instance":{{json .Config.Hostname}},' + '"image":{{json .Image}},"state":{{json .State.Status}},' + '"started":{{json .State.StartedAt}},' + '"health":{{with index .State "Health"}}{{json .Status}}{{else}}null{{end}},' + '"cpu":{{.HostConfig.NanoCpus}},"memory":{{.HostConfig.Memory}},' + '"ports":{{json .HostConfig.PortBindings}}}') + return [json.loads(line) for line in docker('inspect', '--format', template, *ids).splitlines()] + + +def wait_api(count=2, timeout=60): + deadline = time.monotonic() + timeout + while time.monotonic() < deadline: + rows = snapshot('api') + if len(rows) == count and all(r['health'] == 'healthy' and r['state'] == 'running' for r in rows): + time.sleep(3) # Docker DNS validity 2s, plus resolver budget 1s. + return rows + time.sleep(0.5) + raise RuntimeError('API replicas did not become healthy') + + +def save(name, value): + (ROOT / 'evidence').mkdir(exist_ok=True) + (ROOT / 'evidence' / name).write_text(json.dumps(value, indent=2) + '\n', encoding='utf-8') + + +def stop_instance(instance): + before = snapshot('api') + matches = [r for r in before if r['instance'] == instance and r['state'] == 'running'] + if len(matches) != 1 or sum(r['state'] == 'running' for r in before) < 2: + raise RuntimeError('Target must identify one running API with a running peer') + docker('stop', '--time', '8', matches[0]['id']) + result = {'target': instance, 'before': before, 'after': snapshot('api')} + if next(r for r in result['after'] if r['instance'] == instance)['state'] != 'exited': + raise RuntimeError('Target was not stopped') + return result + + +def restore(): + compose('up', '-d', '--no-deps', '--no-recreate', 'api') + return wait_api() + + +def rolling(): + before = wait_api() + if len(before) != 2: + raise RuntimeError('This rolling scenario requires exactly two replicas') + steps = [] + for old in before: + stop_instance(old['instance']) + # Only remove the selected, already stopped API; never remove a volume. + docker('rm', old['id']) + compose('up', '-d', '--no-deps', '--no-recreate', '--scale', 'api=2', 'api') + steps.append({'replaced': old['id'], 'ready': wait_api()}) + result = {'before': before, 'steps': steps, 'after': snapshot('api')} + if {r['id'] for r in before} & {r['id'] for r in result['after']}: + raise RuntimeError('Not all original API containers were replaced') + return result diff --git a/scripts/restart.py b/scripts/restart.py index c797090..8933193 100644 --- a/scripts/restart.py +++ b/scripts/restart.py @@ -15,12 +15,12 @@ def snapshot(): def main(): before = snapshot() - subprocess.run(['docker', 'compose', 'restart', 'api', 'postgres', 'redis'], + subprocess.run(['docker', 'compose', 'restart', 'api', 'postgres', 'redis', 'nginx'], cwd=ROOT, check=True, timeout=60) after = snapshot() (ROOT / 'evidence').mkdir(exist_ok=True) (ROOT / 'evidence' / 'restart.txt').write_text( - 'Command: docker compose restart api postgres redis\nBefore (UTC):\n' + before + 'Command: docker compose restart api postgres redis nginx\nBefore (UTC):\n' + before + 'After (UTC):\n' + after, encoding='utf-8') diff --git a/scripts/rolling.py b/scripts/rolling.py new file mode 100644 index 0000000..9658a7d --- /dev/null +++ b/scripts/rolling.py @@ -0,0 +1,6 @@ +from ops import compose, rolling + +if __name__ == '__main__': + compose('build', 'api') + compose('run', '--rm', '--no-deps', 'migrate') + rolling() diff --git a/scripts/stop-one.cmd b/scripts/stop-one.cmd new file mode 100644 index 0000000..063197a --- /dev/null +++ b/scripts/stop-one.cmd @@ -0,0 +1,3 @@ +@echo off +cd /d "%~dp0.." +python scripts\stop-one.py diff --git a/scripts/stop-one.py b/scripts/stop-one.py new file mode 100644 index 0000000..839d543 --- /dev/null +++ b/scripts/stop-one.py @@ -0,0 +1,5 @@ +import os +from ops import stop_instance + +if __name__ == '__main__': + stop_instance(os.environ['TARGET_INSTANCE_ID']) diff --git a/scripts/stop-one.sh b/scripts/stop-one.sh new file mode 100755 index 0000000..911fbd6 --- /dev/null +++ b/scripts/stop-one.sh @@ -0,0 +1,4 @@ +#!/bin/sh +set -eu +cd "$(dirname "$0")/.." +exec python3 scripts/stop-one.py diff --git a/scripts/verify_lab3.py b/scripts/verify_lab3.py new file mode 100644 index 0000000..94ea439 --- /dev/null +++ b/scripts/verify_lab3.py @@ -0,0 +1,199 @@ +"""Repeatable grade-4 experiments. Run on host with Docker access and UTF-8 mode.""" +import argparse +import json +import os +import subprocess +import sys +import threading +import time +from concurrent.futures import ThreadPoolExecutor +from uuid import uuid4 + +from ops import ROOT, compose, restore, rolling, save, snapshot, stop_instance, wait_api + +sys.path.insert(0, str(ROOT / 'tests')) +from client import Client, Failure, check +from resilience import history + + +def command(name, args): + result = subprocess.run(args, cwd=ROOT, text=True, encoding='utf-8', + stdout=subprocess.PIPE, stderr=subprocess.STDOUT, timeout=180) + (ROOT / 'evidence' / name).write_text(result.stdout, encoding='utf-8') + print(result.stdout, flush=True) + check(result.returncode == 0, 'Command failed: ' + name) + + +def concurrency(base): + c = Client(base) + alice, bob, eve, chat = c.bootstrap() + path = '/api/v1/chats/' + chat['id'] + '/messages' + key = uuid4().hex + barrier = threading.Barrier(8) + + def send(_): + client = Client(base) + barrier.wait(timeout=10) + return client.message(alice, chat, 'one concurrent message', key=key) + + responses = [] + with ThreadPoolExecutor(max_workers=8) as executor: + for _ in range(3): + responses.extend(executor.map(send, range(8))) + first = responses[0]['json'] + check(all(r['json'] == first and r['status'] == 201 for r in responses), 'Concurrent replies differ') + instances = sorted({r['headers']['X-Instance-Id'] for r in responses}) + check(len(instances) >= 2, 'Concurrent test did not reach both replicas') + check(history(c, alice, chat) == [first], 'Concurrent retry duplicated message') + c.call('POST', path, 409, actor=alice, body={'text': 'different'}, headers={'Idempotency-Key': key}) + c.call('POST', path, 401, body={'text': 'one concurrent message'}, headers={'Idempotency-Key': key}) + c.call('POST', path, 404, actor=eve, body={'text': 'one concurrent message'}, headers={'Idempotency-Key': key}) + for invalid in (None, '', 'bad key', 'x' * 129): + c.call('POST', path, 400, actor=alice, body={'text': 'invalid key'}, + headers={} if invalid is None else {'Idempotency-Key': invalid}) + other = c.message(bob, chat, 'independent user', key=key)['json'] + check(other['id'] != first['id'], 'Key scope must include actor') + chat2 = c.call('POST', '/api/v1/chats', 201, actor=alice, + body={'title': 'Scope', 'member_ids': [alice['id']]}, schema='Chat')['json'] + other = c.message(alice, chat2, 'independent chat', key=key)['json'] + check(other['id'] != first['id'], 'Key scope must include chat') + save('idempotency.json', {'requests': 24, 'concurrency': 8, 'instances': instances, + 'unique_messages': 1, 'same_response': True, + 'conflict_auth_access_key_scope': 'PASS'}) + return c, alice, chat, key, first + + +def experiment(base, name, action, target=None): + c = Client(base, timeout=9) + alice, bob, _, chat = c.bootstrap() + confirmed_before = c.message(alice, chat, 'before ' + name)['json'] + events = [] + stop = threading.Event() + started = time.monotonic() + + def worker(): + client = Client(base, timeout=9) + key = uuid4().hex + while not stop.is_set(): + begin = time.monotonic() + try: + response = client.message(alice, chat, key, key=key) + msg = response['json'] + events.append({'kind': 'write', 'time': time.monotonic() - started, + 'latency': response['elapsed'], 'instance': response['headers']['X-Instance-Id'], + 'message': msg}) + key = uuid4().hex + except Failure as exc: + events.append({'kind': 'error', 'operation': 'write', 'time': time.monotonic() - started, + 'latency': time.monotonic() - begin, 'error': str(exc)}) + continue # Keep original key/body after an uncertain write. + begin = time.monotonic() + try: + response = client.call('GET', '/api/v1/chats/' + chat['id'], actor=bob, schema='Chat') + events.append({'kind': 'read', 'time': time.monotonic() - started, + 'latency': response['elapsed'], 'instance': response['headers']['X-Instance-Id']}) + except Failure as exc: + events.append({'kind': 'error', 'operation': 'read', 'time': time.monotonic() - started, + 'latency': time.monotonic() - begin, 'error': str(exc)}) + time.sleep(0.02) + + with ThreadPoolExecutor(max_workers=2) as executor: + futures = [executor.submit(worker) for _ in range(2)] + try: + time.sleep(3) + action_started = time.monotonic() - started + effect = action() + action_finished = time.monotonic() - started + time.sleep(max(5, 20 - (time.monotonic() - started))) + finally: + stop.set() + for future in futures: + future.result() + duration = time.monotonic() - started + successes = [e for e in events if e['kind'] != 'error'] + errors = [e for e in events if e['kind'] == 'error'] + writes = [e for e in successes if e['kind'] == 'write'] + recovery = {} + for kind in ('read', 'write'): + after = [e for e in successes if e['kind'] == kind and e['time'] >= action_finished] + check(bool(after), 'No ' + kind + ' after action') + recovery[kind] = round(min(e['time'] for e in after) - action_started, 3) + if target: + check(all(e['instance'] != target for e in after), 'Stopped target still serves') + check(recovery[kind] <= 10, 'Recovery exceeded 10 seconds') + messages = history(c, bob, chat) + by_id = {m['id']: m for m in messages} + check(by_id.get(confirmed_before['id']) == confirmed_before, 'Pre-failure message lost') + check(all(by_id.get(e['message']['id']) == e['message'] for e in writes), 'Confirmed write lost') + check(len({m['text'] for m in messages}) == len(messages), 'Retry duplicated a message') + # Retry a pre-failure key through the surviving/new processes. + if writes: + item = writes[0]['message'] + check(c.message(alice, chat, item['text'], key=item['text'])['json'] == item, 'Replay changed after action') + latencies = sorted(e['latency'] for e in successes) + gaps = {} + for kind in ('read', 'write'): + times = sorted(e['time'] for e in successes if e['kind'] == kind) + gaps[kind] = round(max((b - a for a, b in zip(times, times[1:])), default=0), 3) + summary = {'duration_seconds': round(duration, 3), 'concurrency': 2, + 'successful_http_rps': round(len(successes) / duration, 2), + 'successful_write_rps': round(len(writes) / duration, 2), + 'successful_requests': len(successes), 'errors': len(errors), + 'action_started_seconds': round(action_started, 3), + 'action_finished_seconds': round(action_finished, 3), + 'first_read_write_after_action_seconds_from_start': recovery, + 'max_success_gap_seconds': gaps, + 'latency_ms': {str(p): round(latencies[min(int(len(latencies)*p/100), len(latencies)-1)]*1000, 2) + for p in (50, 95, 99)}, + 'confirmed_messages_preserved': True, 'duplicate_messages': 0, + 'instances': sorted({e['instance'] for e in successes}), 'target': target} + save(name + '.json', {'summary': summary, 'containers': effect, 'errors': errors}) + print(name + ': ' + json.dumps(summary), flush=True) + return summary + + +def main(): + parser = argparse.ArgumentParser() + parser.add_argument('--base-url', default='http://127.0.0.1:8080') + args = parser.parse_args() + os.environ['PYTHONUTF8'] = '1' + base = args.base_url + wait_api() + command('check.txt', [sys.executable, '-X', 'utf8', 'scripts/check_contract.py']) + command('final-smoke.txt', [sys.executable, '-X', 'utf8', 'tests/smoke.py', '--base-url', base]) + c, actor, chat, key, original = concurrency(base) + hook = 'scripts/restart.cmd' if os.name == 'nt' else 'scripts/restart.sh' + command('persistence.txt', [sys.executable, '-X', 'utf8', 'tests/resilience.py', '--mode', 'persistence', + '--base-url', base, '--action-script', hook]) + wait_api() + check(c.message(actor, chat, original['text'], key=key)['json'] == original, + 'Idempotency/session not preserved across full restart') + save('idempotency-restart.json', {'same_token': True, 'same_201_message': True}) + hook = 'scripts/stop-one.cmd' if os.name == 'nt' else 'scripts/stop-one.sh' + for index in range(2): + try: + command('public-failover-' + str(index+1) + '.txt', + [sys.executable, '-X', 'utf8', 'tests/resilience.py', '--mode', 'failover', + '--base-url', base, '--action-script', hook]) + finally: + restore() + results = {} + for index, row in enumerate(snapshot('api'), start=1): + target = row['instance'] + try: + results['failover-' + str(index)] = experiment(base, 'failover-' + str(index), + lambda: stop_instance(target), target) + finally: + restore() + # Build one image first; apply compatible migrations once before replacing replicas. + compose('build', 'api') + compose('run', '--rm', '--no-deps', 'migrate') + results['rolling'] = experiment(base, 'rolling-load', rolling) + save('grade4-summary.json', results) + save('final-containers.json', snapshot()) + command('final-smoke.txt', [sys.executable, '-X', 'utf8', 'tests/smoke.py', '--base-url', base]) + print('PASS: all grade-4 scenarios', flush=True) + + +if __name__ == '__main__': + main() diff --git a/src/errors.py b/src/errors.py index de05211..d02425b 100644 --- a/src/errors.py +++ b/src/errors.py @@ -2,6 +2,7 @@ from fastapi import Request from fastapi.exceptions import RequestValidationError from fastapi.responses import JSONResponse from starlette.exceptions import HTTPException as StarletteHTTPException +from .middleware import INSTANCE_ID class APIError(Exception): @@ -15,7 +16,7 @@ def error_response(request: Request, status_code: int, code: str, message: str) request_id = getattr(request.state, "request_id", "") return JSONResponse( status_code=status_code, - headers={"X-Request-Id": request_id}, + headers={"X-Request-Id": request_id, "X-Instance-Id": INSTANCE_ID}, content={ "error": { "code": code, diff --git a/src/main.py b/src/main.py index a0a7d18..298c7cc 100644 --- a/src/main.py +++ b/src/main.py @@ -5,10 +5,9 @@ from contextlib import asynccontextmanager from sqlalchemy.exc import OperationalError, InterfaceError, TimeoutError as PoolTimeout from sqlalchemy.orm import sessionmaker from redis.exceptions import RedisError -from starlette.concurrency import run_in_threadpool from .errors import APIError, api_error_handler, validation_error_handler, http_error_handler, internal_error_handler, dependency_error_handler -from .database import create_db_engine, migrate +from .database import create_db_engine from .store import store from .auth import sessions from .middleware import RequestIdMiddleware @@ -23,7 +22,6 @@ from .routers.auth import router as auth_router async def lifespan(app): engine = create_db_engine() try: - await run_in_threadpool(migrate, engine) store.sessions = sessionmaker(engine, expire_on_commit=False) yield finally: diff --git a/src/middleware.py b/src/middleware.py index f19a3df..530eeb9 100644 --- a/src/middleware.py +++ b/src/middleware.py @@ -1,8 +1,11 @@ from uuid import uuid4 +from socket import gethostname from starlette.responses import JSONResponse from starlette.middleware.base import BaseHTTPMiddleware from starlette.requests import Request +INSTANCE_ID = gethostname() + class RequestIdMiddleware(BaseHTTPMiddleware): async def dispatch(self, request: Request, call_next): @@ -25,8 +28,10 @@ class RequestIdMiddleware(BaseHTTPMiddleware): }, ) response.headers["X-Request-Id"] = request_id + response.headers["X-Instance-Id"] = INSTANCE_ID return response response = await call_next(request) response.headers["X-Request-Id"] = request_id + response.headers["X-Instance-Id"] = INSTANCE_ID return response diff --git a/src/models.py b/src/models.py index 418dc30..45b3266 100644 --- a/src/models.py +++ b/src/models.py @@ -58,3 +58,12 @@ class SchemaMigration(Base): __tablename__ = 'schema_migrations' version: Mapped[str] = mapped_column(Text, primary_key=True) applied_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), server_default=func.now(), nullable=True) + + +class IdempotencyRecord(Base): + __tablename__ = 'message_idempotency' + actor_id: Mapped[str] = mapped_column(Uuid(as_uuid=False), ForeignKey('users.id'), primary_key=True) + chat_id: Mapped[str] = mapped_column(Uuid(as_uuid=False), ForeignKey('chats.id', ondelete='CASCADE'), primary_key=True) + key: Mapped[str] = mapped_column(Text, primary_key=True) + message_id: Mapped[str] = mapped_column(Uuid(as_uuid=False), ForeignKey('messages.id', ondelete='CASCADE')) + created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), server_default=func.clock_timestamp()) diff --git a/src/routers/chats.py b/src/routers/chats.py index 8708506..9604e94 100644 --- a/src/routers/chats.py +++ b/src/routers/chats.py @@ -1,6 +1,8 @@ from typing import Optional +import re -from fastapi import APIRouter, Depends, Query, status +from fastapi import APIRouter, Depends, Header, Query, status +from ..errors import APIError from ..dependencies import current_user, page_limit from ..schemas.chat import Chat, ChatPage, CreateChat @@ -30,8 +32,11 @@ def get_chat(chat_id: str, user: dict = Depends(current_user)): @router.post("/{chat_id}/messages", response_model=Message, status_code=status.HTTP_201_CREATED) -def create_message(chat_id: str, payload: CreateMessage, user: dict = Depends(current_user)): - return store.create_message(chat_id, user["id"], payload.text) +def create_message(chat_id: str, payload: CreateMessage, user: dict = Depends(current_user), + idempotency_key: Optional[str] = Header(default=None)): + if not idempotency_key or not re.fullmatch(r'[A-Za-z0-9._:-]{1,128}', idempotency_key): + raise APIError(400, 'invalid_request', 'Требуется корректный Idempotency-Key') + return store.create_message(chat_id, user["id"], payload.text, idempotency_key) @router.get("/{chat_id}/messages", response_model=MessagePage) diff --git a/src/store.py b/src/store.py index 3f82ac2..01a7e33 100644 --- a/src/store.py +++ b/src/store.py @@ -10,7 +10,7 @@ from sqlalchemy.exc import IntegrityError from .auth import password_hasher, verify_password, unauthorized from .errors import APIError from .cache import history_cache -from .models import User, Chat, ChatMember, Message +from .models import User, Chat, ChatMember, Message, IdempotencyRecord def ensure_uuid(value): @@ -130,15 +130,28 @@ class PostgresStore: items = [self._members(session, chat) for chat in chats[:limit]] return self._page(items, len(chats) > limit, 'chats', actor_id) - def create_message(self, chat_id, actor_id, text): + def create_message(self, chat_id, actor_id, text, idempotency_key=None): chat_id = ensure_uuid(chat_id) with self.sessions.begin() as session: self._chat(session, chat_id, actor_id) + if idempotency_key is not None: + # Serialize writers to this chat before looking up the key. + # The same row is updated below for history cache invalidation. + session.execute(select(Chat.id).where(Chat.id == chat_id).with_for_update()) + record = session.get(IdempotencyRecord, (actor_id, chat_id, idempotency_key)) + if record is not None: + previous = session.get(Message, record.message_id) + if previous.text != text: + raise APIError(409, 'conflict', 'Ключ уже использован для другого сообщения') + return serialize(previous, *MESSAGE_FIELDS) session.execute(update(Chat).where(Chat.id == chat_id).values( history_version=Chat.history_version + 1)) message = Message(chat_id=chat_id, sender_id=actor_id, text=text) session.add(message) session.flush() + if idempotency_key is not None: + session.add(IdempotencyRecord(actor_id=actor_id, chat_id=chat_id, + key=idempotency_key, message_id=message.id)) result = serialize(message, *MESSAGE_FIELDS) return result diff --git a/student-tests/test_database.py b/student-tests/test_database.py index 1359535..d570537 100644 --- a/student-tests/test_database.py +++ b/student-tests/test_database.py @@ -27,7 +27,7 @@ class MigrationTests(unittest.TestCase): self.assertEqual(store.list_messages(chat['id'], user['id'], 100, None)['items'], [message]) with isolated.connect() as conn: self.assertEqual(set(conn.scalars(select(SchemaMigration.version))), - {'001_initial.sql', '002_history_version.sql'}) + {'001_initial.sql', '002_history_version.sql', '003_message_idempotency.sql'}) indexes = {index['name'] for index in inspect(isolated).get_indexes('messages')} self.assertIn('messages_history_idx', indexes) self.assertEqual(len(inspect(isolated).get_foreign_keys('messages')), 2) diff --git a/student-tests/test_idempotency.py b/student-tests/test_idempotency.py new file mode 100644 index 0000000..59362b4 --- /dev/null +++ b/student-tests/test_idempotency.py @@ -0,0 +1,55 @@ +"""Database atomicity and concurrent conflict checks, using isolated synthetic data.""" +import unittest +from concurrent.futures import ThreadPoolExecutor +from unittest.mock import patch +from uuid import uuid4 + +from sqlalchemy import func, select +from sqlalchemy.orm import Session, sessionmaker + +from src.database import create_db_engine +from src.errors import APIError +from src.models import Chat, IdempotencyRecord, Message +from src.store import PostgresStore + + +class IdempotencyTests(unittest.TestCase): + def setUp(self): + self.engine = create_db_engine() + self.store = PostgresStore() + self.store.sessions = sessionmaker(self.engine, expire_on_commit=False) + self.user = self.store.create_user('idem_' + uuid4().hex[:16], 'Idempotency', 'Synthetic-password-123') + self.chat = self.store.create_chat(self.user['id'], 'Atomic', [self.user['id']]) + + def tearDown(self): + self.engine.dispose() + + def test_record_and_message_rollback_together(self): + real_add = Session.add + def fail_record(session, instance, *args, **kwargs): + if isinstance(instance, IdempotencyRecord): + raise RuntimeError('Simulate failure after message INSERT, before COMMIT') + return real_add(session, instance, *args, **kwargs) + args = (self.chat['id'], self.user['id'], 'atomic', 'same-key') + with patch.object(Session, 'add', fail_record): + with self.assertRaises(RuntimeError): + self.store.create_message(*args) + with Session(self.engine) as session: + self.assertEqual(session.scalar(select(func.count()).select_from(Message).where(Message.chat_id == self.chat['id'])), 0) + self.assertIsNone(session.get(IdempotencyRecord, (self.user['id'], self.chat['id'], 'same-key'))) + self.assertEqual(session.get(Chat, self.chat['id']).history_version, 0) + first = self.store.create_message(*args) + self.assertEqual(self.store.create_message(*args), first) + + def test_concurrent_different_payloads_have_one_winner(self): + def send(index): + try: + return self.store.create_message(self.chat['id'], self.user['id'], str(index), 'conflict'), 201 + except APIError as exc: + return None, exc.status_code + with ThreadPoolExecutor(max_workers=8) as executor: + results = list(executor.map(send, range(8))) + self.assertEqual(sorted(code for _, code in results), [201] + [409] * 7) + with Session(self.engine) as session: + self.assertEqual(session.scalar(select(func.count()).select_from(Message).where(Message.chat_id == self.chat['id'])), 1) + self.assertEqual(session.get(Chat, self.chat['id']).history_version, 1)