diff --git a/REPORT1.md b/REPORT1.md index 0be92dc..7a572f3 100644 --- a/REPORT1.md +++ b/REPORT1.md @@ -2,7 +2,7 @@ - Автор, группа: Миронов Алексей, бвт2302 - Целевая оценка: 4; трек 5 не заявлен -- Commit/PR: заполнить после публикации +- Commit/PR: 1b476ee, https://gitea.privcloud.tech/mtusi2026/mtusi2026lab3/pulls/56 - Использованные источники, библиотеки и помощь ИИ: исходный репозиторий лабораторной 3 и его `COURSE.md`, `README.md`, `contracts/README.md`, `contracts/openapi.json`, `tests/`; перенесённая собственная реализация лабораторной 2; FastAPI, Pydantic, psycopg/psycopg-pool, PostgreSQL, Redis, Argon2, HAProxy, Docker Compose; использовалась помощь ИИ. ## Запуск из чистого clone diff --git a/REPORT1_lab3_updated.md b/REPORT1_lab3_updated.md deleted file mode 100644 index 007fc01..0000000 --- a/REPORT1_lab3_updated.md +++ /dev/null @@ -1,121 +0,0 @@ -# Отчёт — лабораторная 3 - -- Автор, группа: Миронов Алексей, бвт2302 -- Целевая оценка: 4; трек 5 не заявлен -- Commit/PR: заполнить после публикации -- Использованные источники, библиотеки и помощь ИИ: исходный репозиторий лабораторной 3 и его `COURSE.md`, `README.md`, `contracts/README.md`, `contracts/openapi.json`, `tests/`; перенесённая собственная реализация лабораторной 2; FastAPI, Pydantic, psycopg/psycopg-pool, PostgreSQL, Redis, Argon2, HAProxy, Docker Compose; использовалась помощь ИИ. - -## Запуск из чистого clone - -Требуются Docker Engine с Compose v2 и GNU Make. Команды выполняются из корня репозитория. Стенд предназначен только для локальных синтетических данных. - -1. Создать `.env` и задать уникальный локальный пароль PostgreSQL: - ```bash - cp .env.example .env - ``` -2. Проверить структуру и конфигурацию: - ```bash - make check - pip install -r requirements-dev.txt - make validate - docker compose --env-file .env config --quiet - ``` -3. Собрать образы и запустить две API-реплики за HAProxy: - ```bash - docker compose --env-file .env up -d --build --scale api=2 - ``` - `migrate` запускается однократно после готовности PostgreSQL и до API. - Проверить `docker compose --env-file .env ps` и `curl -i http://localhost:8080/health/ready`. -4. Проверить контракт и общую идемпотентность: - ```bash - make test - python tests/grade4_checks.py - ``` -5. Проверить сохранность состояния и отказ реплик (только на тестовом стенде): - ```bash - make test-persistence ACTION_SCRIPT=scripts/restart.sh - make test-failover ACTION_SCRIPT=scripts/stop-one.sh - ``` - Failover-тест оставляет одну реплику остановленной. Восстановить желаемые две реплики: `docker compose --env-file .env up -d --scale api=2 api`. Проверить отказ для каждой реплики отдельно, каждый раз восстанавливая предыдущую. -6. Нагрузка и поочерёдная замена: - ```bash - make load - # В отдельном терминале можно запустить `bash scripts/rolling-restart.sh` - (проверка того, что апи-реплики могут перезапускаться по отдельности без изменения, не останавливая всё приложение. Это проверка отказоустойчивости, балансировщик должен перенаправлять запросы на доступную реплику, пока другая перезапускается) - ``` - Сохранить фактические параметры и JSON-нагрузку в `evidence/`. Команды ожидания готовности и остановки: `docker compose --env-file .env down` (volumes сохраняются); для намеренного удаления учебных данных использовать `docker compose --env-file .env down -v` только после явного решения удалить БД и Redis. - -## Архитектура и решения - -Клиент → HAProxy → две и более взаимозаменяемые FastAPI-реплики → общая PostgreSQL и общий Redis. В Compose наружу опубликован только HAProxy на `127.0.0.1:8080`; API-реплики доступны лишь во внутренней сети. HAProxy опрашивает `/health/ready`, исключает backend после неуспешных проверок и повторно включает после восстановления. Период проверки — 1 с; исключение после двух ошибок ожидается примерно за 2 с плюс timeout/расписание проверок, фактическое время необходимо измерить. - -- **Перенос из lab2:** `src/main.py`, базовая SQL-схема пользователей/чатов/участников/сообщений, Redis-сессии, Argon2, пагинация и формат ошибок перенесены. Также перенесены зависимости, `examples/requests.http`, `.gitignore` и `scripts/restart.sh`. В `REPORT1.md` явно фиксируется этот перенос. -- **Изменения lab3:** добавлен `X-Instance-Id` (hostname контейнера, стабильный в пределах его жизни), обязательный `Idempotency-Key` при POST сообщения и таблица `idempotency_records`. Тело запроса нормализуется перед SHA-256; транзакционная advisory lock сериализует одинаковый ключ на всех репликах; запись сообщения и сохранённого ответа выполняется в одной транзакции PostgreSQL. Идентичный повтор в течение 24 часов возвращает исходный `201` и то же сообщение; другой body при том же ключе получает `409`. -- **Миграции:** `scripts/migrate.py` — отдельный одноразовый Compose-сервис, применяющий миграции в порядке имени и записывающий версии в `schema_migrations`. API-реплики не пытаются одновременно менять схему при старте. -- **Сессии:** остаются в Redis, который использует AOF и именованный volume; PostgreSQL — источник истины для бизнес-данных и идемпотентности. -- **Health/shutdown:** `/health/live` проверяет процесс, `/health/ready` проверяет PostgreSQL и Redis. Uvicorn получает SIGTERM, graceful timeout — 10 с, Compose `stop_grace_period` — 15 с. -- **Ресурсы:** Compose задаёт CPU/RAM limits для API, PostgreSQL, Redis и HAProxy. Это ограничения на одном Docker-host, не гарантия доступности при потере хоста. -- **Секреты:** `.env` игнорируется Git и не копируется в образ. - -## Доказательства критериев - -Результаты ниже перенесены из предоставленного `evidence.txt`. Этот файл является единственным источником доказательств для таблицы; результаты, отсутствующие в нём, обозначены как неподтверждённые. `make check` и `make validate` подтверждают статические проверки, но сами по себе не означают, что приложение было запущено и проверено. - -| Критерий | Команда/сценарий | Фактический результат | Источник | -|---|---|---|---| -| Структура проекта и синтаксис | `make check` | **PASS:** проверка офлайн-структуры, локальных ссылок и синтаксиса Python. В выводе отдельно указано, что приложение этим тестом не проверялось. | `evidence.txt` | -| OpenAPI и JSON Schema | `make validate` | **PASS:** полная валидация OpenAPI 3.1 и JSON Schema. В выводе отдельно указано, что приложение этим тестом не проверялось. | `evidence.txt` | -| Конфигурация Docker Compose | `docker compose --env-file .env config --quiet` | Команда завершилась без диагностического вывода. Отдельный код завершения в предоставленном фрагменте не зафиксирован. | `evidence.txt` | -| Сквозной публичный API | `make test` | **PASS:** `lab3 public API scenario`. | `evidence.txt` | -| Две разные API-реплики и конкурентная идемпотентность | `python3 tests/grade4_checks.py` | **PASS:** наблюдались две разные реплики (`21d7ab63f9dc`, `3c995d3af7ef`); 12 параллельных запросов дали один уникальный ID сообщения; изменённое тело с тем же ключом вернуло HTTP 409; отсутствующий и некорректный ключи вернули HTTP 400. | `evidence.txt` | -| Сохранность данных и сессии после перезапуска | `make test-persistence ACTION_SCRIPT=./scripts/restart.sh` | **PASS:** подтверждённые данные и существующая сессия сохранены. Вывод содержит предупреждение: `Hook scope needs operator evidence`; область действия hook требует отдельного подтверждения оператором. | `evidence.txt` | -| Failover одной API-реплики | `make test-failover ACTION_SCRIPT=./scripts/stop-one.sh` | **PASS:** до отказа наблюдались 2 экземпляра; зафиксировано 73 успешные записи, 1 неудачная попытка и 3,223 секунды до первой успешной записи после восстановления. Подтверждена сохранность данных и сессии. В предоставленном результате не указано, что проверка отдельно повторялась для каждой реплики. | `evidence.txt` | -| Нагрузка без перезапуска | `make load` | **PASS:** 30,088 с; concurrency=4; 1528 успешных запросов, 0 неудачных; error ratio 0; 50,785 успешного запроса/с; p50=64,545 мс, p95=192,316 мс, p99=258,186 мс. Процентили рассчитаны только по успешным запросам. | `evidence.txt` | -| Rolling restart | `bash scripts/rolling-restart.sh` | **PASS:** скрипт завершился сообщением `rolling restart completed with 2 healthy API replicas`. | `evidence.txt` | -| Нагрузка во время rolling restart | `make load`, выполнявшийся параллельно с rolling restart | **Выполнено, но не без ошибок:** 30,128 с; concurrency=4; 1839 успешных запросов и 9 неудачных; error ratio=0,00487 (около 0,487%); 61,039 успешного запроса/с; p50=33,306 мс, p95=97,359 мс, p99=163,583 мс. Типы этих 9 ошибок в приведённом JSON не указаны. | `evidence.txt` | -| TTL сессии | Проверка с временным `SESSION_TTL_SECONDS=3` | Результат в предоставленном `evidence.txt` отсутствует; не подтверждено. | Нет подтверждения в `evidence.txt` | -| Отказ Redis / PostgreSQL | Проверки отказа хранилищ | Результаты в предоставленном `evidence.txt` отсутствуют; не подтверждено. | Нет подтверждения в `evidence.txt` | -| CPU/RAM limits и доступность внутренних портов | Проверки конфигурации/контейнеров | Достаточных результатов в предоставленном `evidence.txt` нет; не подтверждено. | Нет подтверждения в `evidence.txt` | - -## Эксперименты и отказы - -В качестве доказательств используются только результаты из `evidence.txt`. Метрики нагрузки получены закрытым циклом POST-запросов к сообщениям, с concurrency=4, длительностью около 30 секунд и без автоматических повторов. В выводе теста отдельно отмечено, что процентили задержки учитывают только успешные запросы, а closed-loop профиль подвержен coordinated omission и накладным расходам клиента. Поэтому значения характеризуют именно этот тестовый профиль и не являются универсальной оценкой пропускной способности сервиса. - -### Сводка нагрузочных прогонов - -| Сценарий | Длительность | Успешные | Ошибки | Error ratio | Успешных запросов/с | p50 | p95 | p99 | -|---|---:|---:|---:|---:|---:|---:|---:|---:| -| Обычная нагрузка | 30,088 с | 1528 | 0 | 0% | 50,785 | 64,545 мс | 192,316 мс | 258,186 мс | -| Нагрузка во время rolling restart | 30,128 с | 1839 | 9 | 0,487% | 61,039 | 33,306 мс | 97,359 мс | 163,583 мс | - -Успешные RPS и задержки различаются между двумя прогонами; на основании только этих двух запусков нельзя заключать, что rolling restart сам по себе повышает производительность. Во время параллельного прогона было 9 ошибок, поэтому результат не подтверждает полностью безошибочную доступность при замене реплик. Предоставленный JSON не содержит классификации ошибок, поэтому их HTTP-коды и причины здесь не приписываются. - -### Проверки идемпотентности и отказоустойчивости - -| Воздействие | Наблюдение из `evidence.txt` | Вывод и ограничение | -|---|---|---| -| 12 параллельных запросов с одинаковым ключом | Обнаружены две разные реплики; все параллельные повторы дали один уникальный ID сообщения. | Подтверждена конкурентная идемпотентность между наблюдавшимися репликами в этом сценарии. | -| Тот же ключ с изменённым телом | HTTP 409. | Конфликт при повторном использовании ключа с другим телом подтверждён. | -| Отсутствующий или некорректный ключ | HTTP 400 в обоих случаях. | Валидация ключа подтверждена для этих случаев. | -| Перезапуск с проверкой сохранности | Подтверждённые данные и существующая сессия сохранились. | Тест завершился PASS; при этом вывод просит дополнительное операторское подтверждение области действия hook. | -| Остановка одной API-реплики | 73 успешные записи, 1 неудачная попытка, первая успешная запись после восстановления через 3,223 с; данные и сессия сохранены. | Failover-сценарий завершился PASS, но переход не был полностью безошибочным. Предоставленный результат не доказывает отдельную проверку каждой реплики. | -| Rolling restart без параллельной нагрузки | Скрипт завершился с двумя здоровыми API-репликами. | Завершение скрипта и конечное состояние подтверждены; это само по себе не означает нулевых ошибок во время замены. | -| Rolling restart под нагрузкой | 1839 успешных запросов, 9 ошибок за 30,128 с. | Нагрузка продолжалась, но были ошибки. Их тип и временное распределение в предоставленном JSON не указаны. | - -### Что не подтверждено предоставленным журналом - -- Отдельный failover-тест для каждой из двух реплик. -- Проверка TTL сессии. -- Отказы Redis и PostgreSQL. -- Фактические значения CPU/RAM во время нагрузки и проверка лимитов контейнеров. -- Типы и причины 9 ошибок во время rolling restart. -- Дополнительные подробности операторского подтверждения для persistence hook. - -## Ограничения и следующие шаги - -- Реализована репликация процесса API на одном Docker-host. Потеря хоста, единственного HAProxy, PostgreSQL или Redis не переживается; автоматическая HA для этих компонентов отсутствует. -- HAProxy health checks и Docker health checks имеют ограниченную периодичность; краткие ошибки во время обнаружения отказа возможны и должны измеряться. -- Идемпотентность ограничена текущим API POST сообщений, scope — пользователь + чат/путь + ключ, срок — 24 часа. Ключи старше 24 часов могут быть использованы повторно. -- Redis AOF `appendfsync everysec` не равен синхронной репликации/резервному копированию. -- `scripts/rolling-restart.sh` выполняет поочерёдную замену контейнеров в Compose как упражнение rolling restart; он не является автоматическим blue/green deployment с гарантированным обновлением версии приложения. Проверить поведение в целевой версии Compose и сохранить журнал. -