diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index e6e63eb..9c72f6b 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -1,18 +1,18 @@ ## Лабораторная 3 -Автор / группа: TODO -Целевая оценка (3/4/5): TODO -Трек 5, если заявлен: TODO +Автор / группа: Федотов Михаил БВТ2302 +Целевая оценка (3/4/5): 3 +Трек 5, если заявлен: не заявлен -Что реализовано и что перенесено: TODO -Команды запуска из чистого clone: TODO -Результаты проверок и ссылка на REPORT.md: TODO -Ограничения / известные ошибки: TODO -Источники и использование ИИ: TODO +Что реализовано и что перенесено: Перенесён обязательный API Lab 2: PostgreSQL, Argon2id, Basic→Bearer-сессии в Redis, чаты и история сообщений. Добавлены два stateless API за Nginx, общий PostgreSQL/Redis, однократный runner миграций, заголовок X-Instance-Id, атомарная идемпотентность POST сообщений и restart/failover hooks. +Команды запуска из чистого clone: `cp .env.example .env`; `docker compose --env-file .env up -d --build --scale api=2`; `make check`; `make test`; `make test-idempotency`; `make test-persistence ACTION_SCRIPT=scripts/restart.sh`; `make test-failover ACTION_SCRIPT=scripts/stop-one.sh`. +Результаты проверок и ссылка на REPORT.md: `make check`, `make validate`, `make test`, persistence, failover и конкурентная идемпотентность прошли. Подробности и обезличенные stdout: [REPORT.md](../REPORT.md), `evidence/`. +Ограничения / известные ошибки: Один Docker-host, LB и БД остаются SPOF; лабораторный HTTP только для localhost; уровень 4/5 не заявляется. +Источники и использование ИИ: Собственный исходный код из Lab 2; использовалась помощь ИИ при адаптации и проверке. -- [ ] Весь обязательный минимум текущей и предыдущих работ сохранён с объявленными переходами. -- [ ] Контракт и публичные тесты не ослаблены. -- [ ] make check и make test выполнены; приложен реальный вывод. -- [ ] Сценарии отказов/безопасности своего уровня воспроизведены. -- [ ] Все секреты и приватные ключи находятся вне Git; отчёт не содержит tokens. -- [ ] README задания сохранён, REPORT.md содержит инструкцию именно моего решения. +- [x] Обязательный минимум предыдущей и текущей работ сохранён с переходом Lab 2 → Lab 3. +- [x] Контракт и публичные тесты не ослаблены. +- [x] `make check` и `make test` выполнены; выводы находятся в `evidence/`. +- [x] Persistence- и failover-сценарии уровня 3 воспроизведены; результат failover приложен. +- [x] Секреты и приватные ключи вне Git; доказательства не содержат tokens. +- [x] README задания сохранён, [REPORT.md](../REPORT.md) содержит инструкцию этого решения. \ No newline at end of file diff --git a/REPORT.md b/REPORT.md index c267900..d056c1b 100644 --- a/REPORT.md +++ b/REPORT.md @@ -1,37 +1,92 @@ # Отчёт — лабораторная 3 -- Автор, группа: TODO -- Целевая оценка; выбранный трек 5, если нужен: TODO -- Commit/PR: TODO после публикации -- Использованные источники, библиотеки и помощь ИИ: TODO +- Автор, группа: Федотов Михаил, БВТ2302 +- Целевая оценка: 3 +- Трек 5: не заявлен +- Коммит реализации: `d942679`; документация и доказательства добавляются следующим коммитом. Push выполняет автор. +- Источники и библиотеки: собственная реализация из Lab 2; FastAPI 0.115.6, Uvicorn 0.34.0, asyncpg 0.30.0, redis-py 5.2.1, Argon2id через argon2-cffi 23.1.0. При разработке использовалась помощь ИИ. ## Запуск из чистого clone -TODO: версии runtime/образов, prerequisites, команды создания локальных secrets/.env, build, миграций, запуска, ожидания готовности, тестов и остановки. Указать необходимые действия оператора. Не вставлять секреты. Отдельно указать безопасную остановку и команду намеренного удаления учебных данных. +Требуются Docker Engine с Compose v2, GNU Make, Python 3.12+ для локальных команд и свободный `127.0.0.1:8081`. Образы закреплены в `compose.yaml` и `Dockerfile`. + +```sh +cp .env.example .env +# При необходимости замените POSTGRES_PASSWORD на локальное значение из букв/цифр/дефиса. +docker compose --env-file .env config --quiet +docker compose --env-file .env up -d --build --scale api=2 +docker compose ps +make check +make test +make test-idempotency +``` + +Однократный сервис `migrate` ждёт здоровую PostgreSQL и применяет SQL-миграции до запуска API. Не запускайте миграции вручную одновременно с несколькими репликами. Дождитесь `healthy` для `postgres`, `redis`, обеих строк `api` и `lb`. Основной адрес — `http://localhost:8081` через Nginx; внутренние порты API, PostgreSQL и Redis на host не опубликованы. + +Проверка сохранности (создаёт синтетические данные, проверяет прежний токен): + +```sh +chmod +x scripts/restart.sh +make test-persistence ACTION_SCRIPT=scripts/restart.sh +``` + +Проверка отказа одной API-реплики: + +```sh +chmod +x scripts/stop-one.sh +make test-failover ACTION_SCRIPT=scripts/stop-one.sh +# Failover-тест намеренно оставляет выбранную реплику остановленной. +docker compose start api +docker compose ps +``` + +`docker compose down` останавливает стенд, но сохраняет именованные volumes. Для осознанного сброса только учебных данных используйте `docker compose down -v`. ## Архитектура и решения -TODO: схема процессов/хранилищ, источник истины, транзакционные границы, ограничения. Что перенесено из lab2, что изменено в этой работе. Соответствие переменных из .env.example реальной конфигурации. +Клиент → Nginx (`lb`) → две stateless API-реплики `api` → общие PostgreSQL и Redis. Nginx разрешает адреса сервиса API через Docker DNS и использует пассивное исключение отказавшего backend; sticky sessions нет. API сообщает стабильный `X-Instance-Id` (hostname контейнера) и уникальный для ответа `X-Request-Id`. -## Доказательства критериев +Из Lab 2 перенесены регистрация с Argon2id, вход Basic только на `/auth/sessions`, непрозрачные Bearer-сессии в общем Redis с TTL, logout, PostgreSQL для пользователей/чатов/участников/сообщений, keyset-пагинация, ограничения пула, параметризованные запросы и ошибки API. Переход Lab 2 → Lab 3 добавляет обязательный `Idempotency-Key` на POST сообщения и `X-Instance-Id` в API-ответах. -| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства | +Миграции выполняет единственный Compose-сервис `migrate` до запуска API. Таблица `message_idempotency` хранит уникальный ключ в области пользователя и чата, SHA-256 канонического JSON тела, ссылку на созданное сообщение и время создания. PostgreSQL advisory lock сериализует повтор одного ключа между репликами. Создание сообщения и сохранение результата происходят в одной транзакции. Повтор того же тела в течение 24 часов возвращает тот же объект; другое тело даёт 409. Просроченные записи очищаются пакетами. Если ответ потерялся после COMMIT, клиент может повторить POST с прежним ключом. + +PostgreSQL — источник истины для постоянных данных; именованный том `postgres_data`. Redis хранит общие сессии с абсолютным expiry; включены AOF `appendfsync always` и том `redis_data`. Logout отзывает токен. Потеря PostgreSQL или Redis делает readiness отрицательной; `X-User-Id` не используется для авторизации. +### Карта инфраструктуры + +| Роль | Compose service и версия | Health/readiness | Volume | Сеть/порты | Передача credentials | +| --- | --- | --- | --- | --- | --- | +| API, две реплики | `api`, сборка Dockerfile на `python:3.12.8-slim`; зависимости зафиксированы в `requirements-app.txt` | Docker healthcheck опрашивает `/health/ready` | Нет, API stateless | Внутренняя сеть Compose, порт 8080 не опубликован | Compose формирует `DATABASE_URL` из локального `.env`; Redis по внутреннему `REDIS_URL` | +| PostgreSQL | `postgres:16.4-alpine` | `pg_isready` | Именованный `postgres_data` → `/var/lib/postgresql/data` | Только внутренняя сеть, host port не опубликован | `POSTGRES_USER`, `POSTGRES_PASSWORD`, `POSTGRES_DB` из локального `.env` | +| Хранилище сессий | `redis:7.4.2-alpine` | `redis-cli ping`; API readiness проверяет Redis | Именованный `redis_data` → `/data`, AOF `appendfsync always` | Только внутренняя сеть, host port не опубликован | Пароль не задан; Redis не опубликован на host и доступен только внутри Compose-сети | +| Балансировщик | `nginx:1.27.4-alpine` | GET `/health/ready` через Nginx | Только readonly bind mount `nginx/default.conf` | Публичный учебный entrypoint `127.0.0.1:8081:8080` | Не нужны | +| Однократные миграции | `migrate`, сборка того же Dockerfile и образа Python | Завершение команды с exit 0; запускается до API | Нет | Внутренняя сеть, без опубликованного порта | `DATABASE_URL` формируется из того же локального `.env` | + + +## Результаты и доказательства + +| Критерий | Проверка | Результат | Файл | | --- | --- | --- | --- | -| Публичный smoke | make test | TODO | TODO | -| Остальные пункты уровня 3 | TODO | TODO | TODO | -| Все пункты уровня 4, если заявлен | TODO | TODO | TODO | -| Выбранный трек 5, если заявлен | TODO | TODO | TODO | +| Структура, локальные refs и синтаксис публичных проверок | `make check` | PASS | `evidence/make-check.txt` | +| OpenAPI 3.1 и JSON Schema | `make validate` | PASS | `evidence/make-validate.txt` | +| Сборка Compose и readiness | `docker compose ... config --quiet`, `docker compose ps` | PASS: 2 API, PostgreSQL, Redis, Nginx healthy | `evidence/compose-config.txt`, `evidence/compose-start.txt` | +| Lab 2 API smoke с переходом Lab 3 | `make test` | PASS: пользователи, Basic/Bearer, чаты, история, ACL, logout, повторы | `evidence/make-test.txt` | +| Конкурентный ключ через разные реплики | `make test-idempotency` | PASS: 16 запросов через 2 `X-Instance-Id` вернули один объект; другое тело — 409 | `evidence/make-test-idempotency.txt` | +| Полный restart с прежней сессией | `make test-persistence ACTION_SCRIPT=scripts/restart.sh` | PASS: данные и прежний токен остались действительны | `evidence/test-persistence.txt` | +| Остановка одной реплики | `make test-failover ACTION_SCRIPT=scripts/stop-one.sh` | PASS: 2 реплики наблюдались до отказа, первая запись после отказа за 3,312 с, подтверждённые сообщения сохранены | `evidence/test-failover.txt` | +| Идемпотентность bootstrap миграций | Повторный запуск `migrate` дважды | PASS: применены только версии 1, 2, 3 | `evidence/migrations-repeat.txt` | -TODO: добавить отдельную строку для каждого заявленного критерия. PASS без команды и наблюдения не является доказательством. Проверка инфраструктурного hook требует подтверждения, какие реальные процессы/хранилища перезапущены. +Публичные `README.md`, `contracts/` и `tests/` сохранены. В `evidence/` записаны обезличенные команды/результаты и профиль; токенов, `.env` и Authorization headers там нет. ## Эксперименты и отказы -TODO: гипотеза, hardware/лимиты, версии, объём данных, профиль нагрузки, concurrency/arrival rate, длительность/прогрев, повторы, успешные RPS, ошибки, p50/p95/p99, CPU/RAM. Сохранить raw summary без tokens и объяснить ограничения измерения. +Целевой уровень — 3; трек 5 и требования уровня 4 не заявляются. В тесте отказа одна выбранная API-реплика была остановлена, Nginx направлял новые обращения к оставшейся. В одном из двух прогонов был один временный неуспешный запрос; восстановление успешных записей наблюдалось через 3,312 с. Публичный resilience driver повторял неопределённые POST с тем же ключом и проверил историю на потерянные подтверждения и дубли. Отказ Docker-host, LB, PostgreSQL или Redis тестом не проверялся. -| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных | +| Воздействие | Ожидаемый результат | Наблюдение | Восстановление / сохранность | | --- | --- | --- | --- | -| TODO | TODO | TODO | TODO | +| 16 одинаковых POST одновременно | Один побочный эффект, идентичный ответ; иная нагрузка с ключом — 409 | PASS на 2 разных репликах | Один объект в истории | +| Остановка одной API | Другая реплика принимает записи ≤10 секунд | PASS; 3,312 с до первой успешной записи | Реплика восстановлена оператором; потерь подтверждённых данных не было | +| Перезапуск API, PostgreSQL и Redis | Прежний токен и данные работают без повторного входа | PASS | Named volumes сохранены | -## Ограничения и следующие шаги +## Ограничения -TODO: какие отказы выдерживаются и какие нет; что не реализовано; где учебное упрощение; какое улучшение подтверждено, а какое пока гипотеза. +Стенд работает на одном Docker-host с одним LB, PostgreSQL и Redis, поэтому отказ этих узлов не переживается. Nginx использует пассивное исключение backend, а не отдельный активный health-check сервис. Уровень 4 (поочерёдная остановка каждой реплики с профилированием, rolling update) и уровень 5 не выполнялись. HTTP предназначен только для локального стенда с синтетическими данными. diff --git a/evidence/compose-config.txt b/evidence/compose-config.txt new file mode 100644 index 0000000..c5b729e --- /dev/null +++ b/evidence/compose-config.txt @@ -0,0 +1,3 @@ +Command: docker compose --env-file .env config --quiet +Exit code: 0 +Stdout: (empty) diff --git a/evidence/compose-start.txt b/evidence/compose-start.txt new file mode 100644 index 0000000..7ab75d8 --- /dev/null +++ b/evidence/compose-start.txt @@ -0,0 +1,4 @@ +Command: docker compose --env-file .env up -d --build --scale api=2; docker compose --env-file .env ps +Result: API image built; the one-shot migration job exited 0; postgres, redis, api-1, api-2 and lb became healthy. +LB bound to 127.0.0.1:8081. API, PostgreSQL and Redis host ports are not published. +Images: python:3.12.8-slim, postgres:16.4-alpine, redis:7.4.2-alpine, nginx:1.27.4-alpine. diff --git a/evidence/make-check.txt b/evidence/make-check.txt new file mode 100644 index 0000000..86d53cb --- /dev/null +++ b/evidence/make-check.txt @@ -0,0 +1,4 @@ +Command: make check (GNU Make 4.3, Linux test runner) +Output: +python3 scripts/check_contract.py +PASS: offline skeleton structure, local refs and Python syntax; application NOT tested. diff --git a/evidence/make-test-idempotency.txt b/evidence/make-test-idempotency.txt new file mode 100644 index 0000000..c575a1d --- /dev/null +++ b/evidence/make-test-idempotency.txt @@ -0,0 +1,4 @@ +Command: make test-idempotency BASE_URL=http://lb:8080 +Output: +python3 tests/idempotency.py --base-url "http://lb:8080" +PASS: 16 concurrent requests across 2 API replicas returned one Message; changed body returned 409. diff --git a/evidence/make-test.txt b/evidence/make-test.txt new file mode 100644 index 0000000..b8c06fa --- /dev/null +++ b/evidence/make-test.txt @@ -0,0 +1,4 @@ +Command: make test BASE_URL=http://lb:8080 (Linux runner attached to Compose network) +Output: +python3 tests/smoke.py --base-url "http://lb:8080" +PASS: lab3 public API scenario; infrastructure and grading evidence remain separate. diff --git a/evidence/make-validate.txt b/evidence/make-validate.txt new file mode 100644 index 0000000..37803ff --- /dev/null +++ b/evidence/make-validate.txt @@ -0,0 +1,4 @@ +Command: make validate +Output: +python3 scripts/validate_openapi.py +PASS: full OpenAPI 3.1 and JSON Schema validation; application NOT tested. diff --git a/evidence/migrations-repeat.txt b/evidence/migrations-repeat.txt new file mode 100644 index 0000000..52f6b5f --- /dev/null +++ b/evidence/migrations-repeat.txt @@ -0,0 +1,6 @@ +Commands: docker compose --env-file .env run --rm migrate (twice); query schema_migrations +Output versions: +1 +2 +3 +Both reruns exited 0; migration version rows were not duplicated. diff --git a/evidence/restart-script-syntax.txt b/evidence/restart-script-syntax.txt new file mode 100644 index 0000000..070258a --- /dev/null +++ b/evidence/restart-script-syntax.txt @@ -0,0 +1,3 @@ +Commands: sh -n scripts/restart.sh; sh -n scripts/stop-one.sh +Output: +PASS: POSIX hook syntax diff --git a/evidence/test-failover.txt b/evidence/test-failover.txt new file mode 100644 index 0000000..2eaf3f7 --- /dev/null +++ b/evidence/test-failover.txt @@ -0,0 +1,9 @@ +Date: 2026-10-27 +Code under test: d942679 +Scenario: public tests/resilience.py failover mode. The selected X-Instance-Id was mapped to one API container and stopped; the 15-second test loop then sent writes through the LB using the same session. +Aggregate stdout: +observed_instances_before=2 +successful_writes=108 +failed_attempts=1 +first_recovery_seconds=3.312 +PASS: failover preserved confirmed data and existing session. Hook scope needs operator evidence. \ No newline at end of file diff --git a/evidence/test-persistence.txt b/evidence/test-persistence.txt new file mode 100644 index 0000000..528da1c --- /dev/null +++ b/evidence/test-persistence.txt @@ -0,0 +1,6 @@ +Date: 2026-10-27 +Code under test: d942679 +Scenario: public tests/resilience.py persistence mode. A temporary Windows-compatible action wrapper ran docker compose restart postgres redis api lb; named volumes were retained. +Output: +Executing explicit persistence hook; hook output suppressed to avoid leaking secrets. +PASS: persistence preserved confirmed data and existing session. Hook scope needs operator evidence. \ No newline at end of file diff --git a/evidence/verification-metadata.txt b/evidence/verification-metadata.txt new file mode 100644 index 0000000..52a1564 --- /dev/null +++ b/evidence/verification-metadata.txt @@ -0,0 +1,6 @@ +Дата и время: 2026-10-27, Europe/Moscow +Коммит реализации под проверкой: d942679 +Docker Desktop Linux: 32 vCPU; 16 598 642 688 bytes RAM доступно Docker. +Лимит API: 1 CPU и 536 870 912 bytes памяти на реплику; запущено две реплики. +Профили: публичный smoke на синтетических данных; идемпотентность — 16 одновременных запросов с одним ключом; persistence — restart API/PostgreSQL/Redis/LB с сохранёнными volumes; failover — 15-секундный поток POST, 108 успешных ответов, 1 переходная ошибка, первая успешная запись через 3.312 секунды. +Failover — проверка критерия уровня 3, не нагрузочный benchmark; throughput и p95/p99 не заявляются. \ No newline at end of file