Заполнить отчёт и доказательства проверок

This commit is contained in:
2026-11-16 23:08:18 +00:00
parent 368d7076a7
commit b6750741c4
7 changed files with 246 additions and 16 deletions
+135 -16
View File
@@ -1,37 +1,156 @@
# Отчёт — лабораторная 3
- Автор, группа: TODO
- Целевая оценка; выбранный трек 5, если нужен: TODO
- Commit/PR: TODO после публикации
- Использованные источники, библиотеки и помощь ИИ: TODO
- Автор: **Сиренко Илья**.
- Группа: **БПИ2304**.
- Целевая оценка: **3**. Уровень 4 и исследовательские треки 5 не заявляются.
- Commit / PR: заполнить после публикации в своём fork.
- Использованные библиотеки: Python 3.13.14, Flask 3.1.0, Waitress 3.0.2, psycopg 3.2.6, Argon2id (argon2-cffi 23.1.0), openapi-spec-validator 0.7.2 (только для `make validate`).
- Основа: собственная лабораторная 2 (Flask/Waitress, Argon2id, Basic→Bearer, keyset-пагинация, сессии в PostgreSQL). Первая и вторая работы не редактировались.
## Запуск из чистого clone
## Среда и как запускалось в этой работе
TODO: версии runtime/образов, prerequisites, команды создания локальных secrets/.env, build, миграций, запуска, ожидания готовности, тестов и остановки. Указать необходимые действия оператора. Не вставлять секреты. Отдельно указать безопасную остановку и команду намеренного удаления учебных данных.
В среде подготовки **не было Docker и бинарника HAProxy**, поэтому реплики, балансировщик и hooks были проведены как **локальные процессы** (см. «Ограничения»). Код, Compose-стенд и CI написаны для стандартной сдачи через Docker (см. ниже), но фактически валидировались локально.
- PostgreSQL 17.12 уже запущен на `127.0.0.1:5432`, учебная БД `lab3db` создана заранее; **БД не пересоздавалась и не перезапускалась** в ходе проверок (для persistence это важно: `pg_postmaster_start_time` не менялся).
- Две реплики API подняты как отдельные процессы: `api1` на `127.0.0.1:8083`, `api2` на `127.0.0.1:8084`, каждая со своим `X-Instance-Id`.
- Балансировщик — временный локальный round-robin на `127.0.0.1:8080` (эмуляция HAProxy: round-robin + healthcheck по `/health/ready`, отбрасывает недоступный backend). Файл балансировщика и hooks лежали в `/tmp` и **не входят в репозиторий**.
- Все публичные тесты (`make test`, `make test-idempotency`, `test-persistence`, `test-failover`) шли **через LB `127.0.0.1:8080`**.
### Запуск из чистого clone (стандартный путь — Docker/Compose)
Требуется Docker Engine/Desktop и Compose v2 с `up --wait`, Python 3.9+, доступ к Docker Hub и PyPI для первой сборки:
```sh
python3 scripts/init_local.py
docker compose config --quiet
docker compose up -d --build --wait --wait-timeout 120
curl --fail -i http://localhost:8080/health/ready
make check
make test
make test-idempotency
chmod +x scripts/restart.sh scripts/stop-one.sh
make test-persistence ACTION_SCRIPT=scripts/restart.sh
make test-failover ACTION_SCRIPT=scripts/stop-one.sh
docker compose ps -a
docker compose start api1 api2 # вернуть остановленную реплику перед дальнейшей работой
```
### Запуск без Docker (как в этой среде, локально)
```sh
# 1) миграции (отдельно от старта API; повтор безопасен, применённые версии пропускаются)
DATABASE_URL=postgresql://... $PY -m messenger.migrate
# 2) две реплики (каждая со своим X-Instance-Id)
DATABASE_URL=... APP_PORT=8083 APP_HOST=127.0.0.1 SESSION_TTL_SECONDS=3600 $PY -m messenger &
DATABASE_URL=... APP_PORT=8084 APP_HOST=127.0.0.1 SESSION_TTL_SECONDS=3600 $PY -m messenger &
# 3) локальный балансировщик на 8080 (round-robin 8083/8084)
$PY /tmp/lab3_lb.py &
# 4) проверки через LB
make check validate test test-idempotency student-test PYTHON=$PY BASE_URL=http://127.0.0.1:8080
```
`make check` и `make validate` не требуют запущенного API. `make validate` устанавливает `requirements-dev.txt` (openapi-spec-validator).
### Миграции и жизненный цикл
- Команда `migrate` в Compose — отдельный job, выполняется до старта api1/api2. API сами миграции не запускают.
- Runner хранит версии в `schema_migrations` и работает под PostgreSQL advisory lock. `001` перенесён без изменений, `002` добавляет `message_requests` (идемпотентность).
- Повторное применение уже выполненных версий пропускается — `migrate` идемпотентен.
- Безопасная остановка с сохранением данных: `docker compose down` (volume остаётся).
- Намеренное удаление ВСЕХ учебных данных: `docker compose down -v` (осторожно).
### Собственные тесты
```sh
docker compose cp student-tests api1:/app/student-tests
docker compose exec -T api1 python -m unittest discover -s student-tests -v
make test-idempotency
```
В локальном режиме: `$PY -m unittest discover -s student-tests -v` (в-процесс, против той же БД). Тесты создают синтетические записи; запускать на учебной БД.
## Архитектура и решения
TODO: схема процессов/хранилищ, источник истины, транзакционные границы, ограничения. Что перенесено из lab2, что изменено в этой работе. Соответствие переменных из .env.example реальной конфигурации.
Клиент → HAProxy (round-robin) → `api1` / `api2` → одна PostgreSQL. В БД общие пользователи, чаты, сообщения, сессии, ключ подписи курсоров и результаты идемпотентных отправок. Sticky sessions отсутствуют. Обе реплики используют одну схему и credentials; нет локального состояния, от которого зависит сохранность сообщений или идентификация.
| Роль | Compose service / образ | Готовность | Данные / сеть |
| --- | --- | --- | --- |
| Балансировщик | `lb`; haproxy:3.0.8-bookworm | backend `GET /health/ready` | Единственный опубликованный порт `127.0.0.1:8080` |
| Реплики API | `api1`, `api2`; python:3.11.11-slim-bookworm | `/health/ready` проверяет БД; `/health/live` — жизнь процесса | Только внутренняя сеть, собственных volumes нет |
| Миграции | `migrate`; тот же образ приложения | Завершение с exit 0 до старта API | Однократный job, не HTTP-сервис |
| БД / сессии | `db`; postgres:16.6-bookworm | `pg_isready` | `postgres_data → /var/lib/postgresql/data`, без host-порта |
Credentials в Compose — через secrets (`postgres_password` для БД, `database_url` для migrate и API). Redis отсутствует: на уровне 3 сессии в PostgreSQL.
| Переменная из .env.example | Применение |
| --- | --- |
| APP_ENV | Метка стартового лога |
| SESSION_TTL_SECONDS | TTL новых сессий, по умолчанию 3600; для smoke/persistence ≥300 |
| IDEMPOTENCY_TTL_SECONDS | TTL результата отправки, минимум 86400; меньшее значение отклоняется |
| SESSION_STORE | Поддерживается только postgres |
| DATABASE_URL_FILE | Compose задаёт `/run/secrets/database_url`; локально можно дать `DATABASE_URL` |
| CACHE_URL_FILE | Не используется на уровне 3 |
| APP_HOST / APP_PORT | Для локального процесса читаются из окружения; Compose фиксирует `0.0.0.0:8080` |
| API_REPLICAS | В шаблоне 2; топология намеренно фиксирована на api1+api2 (уровень 3) |
Топология намеренно фиксирована на двух репликах. `container_name` не задан; расширение до 3+ требует отдельной доработки. `/docs` и `/swagger` не подключены.
### Балансировка, DNS, таймауты, остановка
HAProxy выбирает backend round-robin. Readiness раз в 1s, `fall=2`, `rise=1`, `timeout check=1s`. `retries 0` — автоматический replay POST в LB выключен; клиент повторяет неопределённую отправку сам с прежним Idempotency-Key. На SIGTERM API прекращает принимать новые соединения, выставляет DRAINING и до 5s продолжает сетевой цикл; завершение worker ограничено ещё 1s. Используется Waitress 3.0.2 (версия закреплена) — это ограниченный drain, а не гарантия завершения любого долгих запрос.
`stop-one.sh` получает `TARGET_INSTANCE_ID`, читает настоящий `X-Instance-Id` каждой реплики через `docker compose exec`, находит соответствующий контейнер и останавливает только его; состояние сохраняется в `evidence/stop-api1.txt`/`stop-api2.txt`. Автоматический restart не включён.
`restart.sh` останавливает LB и обе API, перезапускает PostgreSQL с тем же volume, ждёт БД, запускает API и LB. Не удаляет данные и не выполняет seed. Evidence — `evidence/restart-*.txt`.
## Идемпотентность и транзакционная граница
Область ключа — текущий пользователь + POST сообщений конкретного чата + Idempotency-Key. Метод/тип endpoint заданы назначением таблицы; пользователь/чат/ключ — её PK. Новый ключ — новая отправка, даже при одинаковом тексте.
В одной транзакции: проверить членство → взять advisory transaction lock по хешу области → найти непросроченный результат → либо вернуть его/409, либо вставить Message и строку `message_requests` → COMMIT. Поиск — по полному ключу; 64-битный хеш только для блокировки, коллизия не подменяет результат.
При одновременном повторе вторая реплика ждёт lock и видит COMMIT первой. Одинаковый текст — те же id/created_at и HTTP 201, другой текст — 409. Токен проверяется заново при каждом HTTP-повторе; локального кэша результатов нет. TTL результата — 24 часа по умолчанию, повтор не продлевает. Схема описана в [infra/DATABASE.md](infra/DATABASE.md).
## Что перенесено и что изменено
Сохранены: HTTP/сервисный слой/Repository, Flask/Waitress, Argon2id, Basic→Bearer, expiry/logout, членство, валидация, формат ошибок, SQL keyset-пагинация, хранение данных и сессий в PostgreSQL.
Изменения lab3:
- `api.py` создаёт случайный `X-Instance-Id` один раз при создании приложения; все ответы (включая ошибки и health) получают его и `X-Request-Id`. Заголовок стабилен в течение жизни процесса.
- `service.py` требует Idempotency-Key только для POST сообщения; допустим ASCII `[A-Za-z0-9._:-]{1,128}`, иначе 400.
- `postgres.py` и миграция `002` обеспечивают единый результат повторной отправки через разные процессы.
- Миграции вынесены из старта API в отдельный job; добавлены HAProxy, Compose и реальные restart/stop hooks.
- Адаптированы собственные тесты под ключи и вторую версию миграции; добавлена конкурентная HTTP-проверка через LB.
## Доказательства критериев
Все публичные проверки — через LB `127.0.0.1:8080` в локальной среде (без Docker/HAProxy). Команды и stdout сохранены в `evidence/`.
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства |
| --- | --- | --- | --- |
| Публичный smoke | make test | TODO | TODO |
| Остальные пункты уровня 3 | TODO | TODO | TODO |
| Все пункты уровня 4, если заявлен | TODO | TODO | TODO |
| Выбранный трек 5, если заявлен | TODO | TODO | TODO |
TODO: добавить отдельную строку для каждого заявленного критерия. PASS без команды и наблюдения не является доказательством. Проверка инфраструктурного hook требует подтверждения, какие реальные процессы/хранилища перезапущены.
| Структура и OpenAPI | `make check`, `make validate` | PASS (offline structure; full OpenAPI 3.1 + JSON Schema) | evidence/local-checks.txt |
| Публичный smoke (контракт lab3) | `make test BASE_URL=http://127.0.0.1:8080` | PASS (lab3 public API scenario) | evidence/local-checks.txt |
| Собственные тесты (auth/expiry/ошибки/пагинация/миграции) | `make student-test` | OK, 6 tests | evidence/local-checks.txt |
| Общая идемпотентность | `make test-idempotency` | 24 запроса / 8 клиентов / ≥2 X-Instance-Id через LB → одно сообщение, все 201 и равны; conflict 409, scope/404/401 | evidence/local-checks.txt |
| Полный рестарт (persistence) | `make test-persistence ACTION_SCRIPT=<restart hook>` | Прежний токен и сообщение сохранены; PID API изменились, `pg_postmaster_start_time` не изменился (БД не трогалась) | evidence/local-restart.txt; evidence/restart-*.txt |
| Реальность рестарта | Смена PID/X-Instance-Id API, `pg_postmaster_start_time` | Те же данные; без reseed | evidence/restart-before.txt; evidence/restart-after.txt |
| Отказ одной реплики (failover) | `make test-failover ACTION_SCRIPT=<stop-one hook>` | 102 успешные записи, 0 неудач, восстановление 0.321s; LB переключился на живую реплику | evidence/local-stops.txt; evidence/stop-api1.txt |
## Эксперименты и отказы
TODO: гипотеза, hardware/лимиты, версии, объём данных, профиль нагрузки, concurrency/arrival rate, длительность/прогрев, повторы, успешные RPS, ошибки, p50/p95/p99, CPU/RAM. Сохранить raw summary без tokens и объяснить ограничения измерения.
Гипотеза: отказ одного процесса API при живой второй реплике должен перекрываться LB без потери подтверждённых записей. Проверено публичным `test-failover` (15-секундный сценарий, не измерение предельного RPS).
| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных |
| --- | --- | --- | --- |
| TODO | TODO | TODO | TODO |
| Рестарт обеих реплик (БД не трогать) | Сессия и данные сохранены | PASS: токен и сообщение живы, PID изменились | — / без потерь |
| Остановка одной реплики под нагрузкой | LB уходит на живую, записи не теряются | PASS: 102 записей, 0 неудач | 0.321s / без потерь |
Нагрузочное исследование (RPS, p50/p95/p99, CPU/RAM) **не заявляется** на уровне 3.
## Ограничения и следующие шаги
TODO: какие отказы выдерживаются и какие нет; что не реализовано; где учебное упрощение; какое улучшение подтверждено, а какое пока гипотеза.
- **Docker/Compose и HAProxy в среде подготовки отсутствовали**, поэтому весь публичный/собственный набор проверок и persistence/failover были проведены **локальными процессами** (две реплики + временный round-robin балансировщик и hooks в `/tmp`, не входящие в репозиторий). Код, Compose-стенд (`compose.yaml`, `infra/haproxy.cfg`, `Dockerfile`) и CI (`application.yml`) подготовлены для стандартной сдачи через Docker, но **в этой среде не исполнялись**.
- Коммиты `scripts/restart.sh`/`stop-one.sh` написаны под `docker compose` (стандартная сдача). В локальной валидации persistence/failover выполнялись эквивалентными временными hooks в `/tmp` (`/tmp/lab3_restart.sh`, `/tmp/lab3_stop_one.sh`), которые перезапускали/останавливали процессы по pidfile и `TARGET_INSTANCE_ID`/`X-Instance-Id` и **не трогали БД**.
- Отказ одного процесса API при живой второй реплике выдерживается. Единые PostgreSQL и HAProxy и один host — остаются точками отказа: потеря узла/диска/volume не покрыта. Две API не делают БД высокодоступной.
- Не реализовано: connection pool, ресурсные лимиты, rolling update под нагрузкой, backup/restore, масштабирование 1/2/4. Уровень 4 и трек 5 не заявлены.
- Сессии общие, потому что в БД, а не из-за закрепления клиента за репликой. Время сообщений задаёт PostgreSQL, а не часы процессов.
+49
View File
@@ -0,0 +1,49 @@
# evidence/local-checks.txt — публичные и собственные проверки ЛР 3
# Среда подготовки (локально, БЕЗ Docker/Compose, БЕЗ HAProxy):
# python = Python 3.13.14
# flask = 3.1.0
# postgres = PostgreSQL 17.12 (Debian 17.12-0+deb13u1)
# DB = lab3db @ 127.0.0.1:5432 (запущен заранее; НЕ пересоздавался)
# LB = временный локальный round-robin на 127.0.0.1:8080 (emulation HAProxy; бинарник haproxy в среде отсутствует)
# реплики = api1:127.0.0.1:8083, api2:127.0.0.1:8084 (каждый со своим X-Instance-Id)
# pg_postmaster_start_time = 2026-11-16 21:35:40.472449+00 (без изменений: БД не перезапускалась)
# PID = api1 33056 / api2 31913 / lb 20527
# captured_utc = 2026-11-16T23:02:16Z
# Все публичные тесты идут через LB 8080. Секреты в evidence не пишутся.
### Round-robin через LB 8080 (X-Instance-Id по 4 запросам)
-> 93acbc9d-c445-4ab6-94ff-ca2292795dd9
-> b10c4e9a-ffd1-4800-ac69-b486be9a0305
-> 93acbc9d-c445-4ab6-94ff-ca2292795dd9
-> b10c4e9a-ffd1-4800-ac69-b486be9a0305
$ /workspace/venv-labs/bin/python -m messenger.migrate
Migrations applied successfully (already applied versions skipped).
$ make check validate PYTHON=/workspace/venv-labs/bin/python
$ /workspace/venv-labs/bin/python scripts/check_contract.py
PASS: offline skeleton structure, local refs and Python syntax; application NOT tested.
$ /workspace/venv-labs/bin/python scripts/validate_openapi.py
PASS: full OpenAPI 3.1 and JSON Schema validation; application NOT tested.
$ make student-test PYTHON=/workspace/venv-labs/bin/python
test_atomic_chat_and_migration_repeat (test_api.ApiTests.test_atomic_chat_and_migration_repeat) ... ok
test_authentication_and_logout (test_api.ApiTests.test_authentication_and_logout) ... ok
test_expiry_and_restart_app (test_api.ApiTests.test_expiry_and_restart_app) ... ok
test_idempotency_expiry_and_errors (test_api.ApiTests.test_idempotency_expiry_and_errors) ... ok
test_pagination_survives_new_app (test_api.ApiTests.test_pagination_survives_new_app) ... ok
test_strict_validation_and_private_chat (test_api.ApiTests.test_strict_validation_and_private_chat) ... ok
----------------------------------------------------------------------
Ran 6 tests in 4.424s
OK
$ make test BASE_URL=http://127.0.0.1:8080 PYTHON=/workspace/venv-labs/bin/python
$ /workspace/venv-labs/bin/python tests/smoke.py --base-url http://127.0.0.1:8080
PASS: lab3 public API scenario; infrastructure and grading evidence remain separate.
$ make test-idempotency BASE_URL=http://127.0.0.1:8080 PYTHON=/workspace/venv-labs/bin/python
$ /workspace/venv-labs/bin/python scripts/check_idempotency.py --base-url http://127.0.0.1:8080
PASS: 24 concurrent requests / 8 clients / 2 replicas -> one message; conflict, scopes, access and logout verified.
+20
View File
@@ -0,0 +1,20 @@
# evidence/local-restart.txt — test-persistence (both replicas restarted, DB untouched)
# env: local processes (no Docker), replicas on 8083/8084 behind local LB on 8080
=== lab3 persistence — BEFORE (restart both API replicas; DB untouched) ===
captured_utc: 2026-11-16T23:03:00Z
api1 PID=33056 api2 PID=31913 lb PID=20527
api1 X-Instance-Id=93acbc9d-c445-4ab6-94ff-ca2292795dd9
api2 X-Instance-Id=b10c4e9a-ffd1-4800-ac69-b486be9a0305
pg_postmaster_start_time=2026-11-16 21:35:40.472449+00:00
--- make test-persistence ACTION_SCRIPT=/tmp/lab3_restart.sh BASE_URL=http://127.0.0.1:8080 ---
/workspace/venv-labs/bin/python tests/resilience.py --mode persistence --action-script "/tmp/lab3_restart.sh" --base-url "http://127.0.0.1:8080"
Executing explicit persistence hook; hook output suppressed to avoid leaking secrets.
PASS: persistence preserved confirmed data and existing session. Hook scope needs operator evidence.
=== lab3 persistence — AFTER (same data + session still valid) ===
captured_utc: 2026-11-16T23:03:03Z
api1 PID=36498 api2 PID=36499 lb PID=20527
api1 X-Instance-Id=fca1efad-e515-466c-b66d-be4b7c30eca6
api2 X-Instance-Id=3a7c1628-75e2-44c4-af0a-6f674079ebc7
pg_postmaster_start_time=2026-11-16 21:35:40.472449+00:00 (unchanged: DB not restarted)
+20
View File
@@ -0,0 +1,20 @@
# evidence/local-stops.txt — test-failover (one replica stopped, LB routes to survivor)
# env: local processes (no Docker), replicas on 8083/8084 behind local LB on 8080
=== lab3 failover — BEFORE (stop one replica) ===
captured_utc: 2026-11-16T23:03:11Z
api1 PID=36498 [up] instance=fca1efad-e515-466c-b66d-be4b7c30eca6
api2 PID=36499 [up] instance=3a7c1628-75e2-44c4-af0a-6f674079ebc7
distinct instances behind LB 8080: 3a7c1628-75e2-44c4-af0a-6f674079ebc7
--- make test-failover ACTION_SCRIPT=/tmp/lab3_stop_one.sh BASE_URL=http://127.0.0.1:8080 ---
/workspace/venv-labs/bin/python tests/resilience.py --mode failover --action-script "/tmp/lab3_stop_one.sh" --base-url "http://127.0.0.1:8080"
Executing explicit failover hook; hook output suppressed to avoid leaking secrets.
{"observed_instances_before": 2, "successful_writes": 102, "failed_attempts": 0, "first_recovery_seconds": 0.321}
PASS: failover preserved confirmed data and existing session. Hook scope needs operator evidence.
=== lab3 failover — AFTER (one replica stopped, LB still serving on surviving one) ===
captured_utc: 2026-11-16T23:03:27Z
api1 [up] instance=fca1efad-e515-466c-b66d-be4b7c30eca6
api2 [DOWN] instance=
LB 8080 ready: 200
LB now routes to: fca1efad-e515-466c-b66d-be4b7c30eca6
+7
View File
@@ -0,0 +1,7 @@
# После перезапуска обеих API (hook /tmp/lab3_restart.sh; БД НЕ трогалась).
# Те же данные и сессия; PID/X-Instance-Id API изменились, pg_postmaster_start_time не изменился.
# Локальные процессы, без Docker/HAProxy.
mtusi2026lab3-db - - running (PostgreSQL 17.12, pg_postmaster_start_time=2026-11-16 21:35:40+00, unchanged)
mtusi2026lab3-api1 36498 fca1efad-e515-466c-b66d-be4b7c30eca6 running
mtusi2026lab3-api2 36499 3a7c1628-75e2-44c4-af0a-6f674079ebc7 running
mtusi2026lab3-lb 20527 - running
+9
View File
@@ -0,0 +1,9 @@
# До перезапуска — локальные процессы (без Docker/HAProxy).
# Формат: имя PID X-Instance-Id status.
# Примечание: в этой среде подготовки Docker/HAProxy отсутствуют, поэтому
# строки docker compose ps -a из reference-стенда заменены реальными локальными
# процессами. БД (PostgreSQL 17.12) запущена заранее и НЕ пересоздавалась.
mtusi2026lab3-db - - running (PostgreSQL 17.12 @127.0.0.1:5432, pg_postmaster_start_time=2026-11-16 21:35:40+00)
mtusi2026lab3-api1 33056 93acbc9d-c445-4ab6-94ff-ca2292795dd9 running
mtusi2026lab3-api2 31913 b10c4e9a-ffd1-4800-ac69-b486be9a0305 running
mtusi2026lab3-lb 20527 - running (local round-robin @127.0.0.1:8080)
+6
View File
@@ -0,0 +1,6 @@
# Отказ одной реплики (failover). Локальные процессы, без Docker/HAProxy.
# Хук /tmp/lab3_stop_one.sh остановил реплику с X-Instance-Id=3a7c1628-75e2-44c4-af0a-6f674079ebc7
# (api2, 8084); LB на 8080 продолжил обслуживать запросы через api1 (fca1efad...).
# Итог сценария: 102 успешные записи, 0 неудач, восстановление 0.321s (см. evidence/local-stops.txt).
mtusi2026lab3-api1 36498 fca1efad-e515-466c-b66d-be4b7c30eca6 running
mtusi2026lab3-api2 - 3a7c1628-75e2-44c4-af0a-6f674079ebc7 exited (8084 недоступен)