diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 8ceefa1..bcfb285 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -1,18 +1,22 @@ ## Лабораторная 2 -Автор / группа: TODO -Целевая оценка (3/4/5): TODO -Трек 5, если заявлен: TODO +Автор / группа: Маслов / БВТ2301 +Целевая оценка (3/4/5): 5 +Трек 5: трек 2, планы запросов и восстановление -Что реализовано и что перенесено: TODO -Команды запуска из чистого clone: TODO -Результаты проверок и ссылка на REPORT.md: TODO -Ограничения / известные ошибки: TODO -Источники и использование ИИ: TODO +Перенесён собственный HTTP API ЛР1; добавлены PostgreSQL/SQL-миграции, +Argon2id, постоянные Bearer-сессии, Valkey cache, bounded pool/timeouts. +Запуск: uv sync --locked; make bootstrap; make up; make test test-student. +Проверки: [REPORT.md](../REPORT.md), evidence/clean-clone.json; +77 HTTP-тестов, реальные отказы/rollback, 101110 сообщений и backup/restore. +Ограничения: один host, без HA/TLS; snapshot не хранит поздние COMMIT. +Источники: контракт, PostgreSQL/Psycopg/Argon2/Valkey documentation. +Помощь ИИ использована при разборе требований, реализации и проверках; +результаты подтверждаются сохранёнными запусками. -- [ ] Весь обязательный минимум текущей и предыдущих работ сохранён с объявленными переходами. -- [ ] Контракт и публичные тесты не ослаблены. -- [ ] make check и make test выполнены; приложен реальный вывод. -- [ ] Сценарии отказов/безопасности своего уровня воспроизведены. -- [ ] Все секреты и приватные ключи находятся вне Git; отчёт не содержит tokens. -- [ ] README задания сохранён, REPORT.md содержит инструкцию именно моего решения. +- [x] Весь обязательный минимум текущей и предыдущих работ сохранён с объявленными переходами. +- [x] Контракт и публичные тесты не ослаблены. +- [x] make check и make test выполнены; приложен реальный вывод. +- [x] Сценарии отказов/безопасности своего уровня воспроизведены. +- [x] Все секреты и приватные ключи находятся вне Git; отчёт не содержит tokens. +- [x] README задания сохранён, REPORT.md содержит инструкцию именно моего решения. diff --git a/REPORT.md b/REPORT.md index 402b960..7b5ee28 100644 --- a/REPORT.md +++ b/REPORT.md @@ -8,7 +8,7 @@ Нужны Docker 25+ с BuildKit/Compose v2+, make, Git и uv 0.13.7. Python 3.14.7; FastAPI 0.143.3, Pydantic 2.14.1, Uvicorn 0.54.0, -psycopg 3.3.6, psycopg-pool 3.3.3, Argon2 25.1.0, redis client 8.1.0. +psycopg 3.3.6, psycopg-pool 3.3.3, argon2-cffi 25.1.0, redis client 8.1.0. Точные транзитивные версии — `uv.lock`. Базовые образы Python/uv, PostgreSQL 18.3 и Valkey 8.1.3 закреплены тегами и digest. @@ -28,7 +28,8 @@ uv run --locked python -m scripts.verify_pool --output evidence/pool-repeat.json API: `http://127.0.0.1:8082`. PostgreSQL/Valkey не публикуют host-порты. Для другого порта задать PUBLIC_PORT в окружении и передавать BASE_URL -проверкам. Все повторные evidence должны иметь новые имена файлов. +проверкам. Все повторные evidence должны иметь новые имена файлов; +для make доступны VERIFY_OUTPUT и RESEARCH_OUTPUT. `make down` останавливает стенд, сохраняя PostgreSQL volume. Его повторный запуск использует прежние данные и секреты. Намеренное удаление **только @@ -123,17 +124,40 @@ Authorization, паролей, токенов, их digest и параметро | API ЛР1 + новый auth | `make test`, `make test-student` | Smoke PASS, 77 passed; [http-tests.json](evidence/http-tests.json) | | Данные и прежний токен после restart всех stores | `make test-persistence`, `make verify` | [public-persistence.txt](evidence/public-persistence.txt), [lifecycle.json](evidence/lifecycle.json); CID/PID/StartedAt до/после | | PK/FK/UNIQUE и атомарный чат | migrations, регистрационная гонка, injected rollback | [001_core.sql](migrations/001_core.sql), [lifecycle.json](evidence/lifecycle.json); после сбоя строка чата отсутствует | -| Версионируемые миграции и bootstrap | `make verify`, clean clone | Повтор без изменений; секреты сохранены; checksum guard в финальной проверке | +| Версионируемые миграции и bootstrap | `make verify`, clean clone | Повтор без изменений, секреты сохранены, checksum mismatch отклонён; [clean-clone.json](evidence/clean-clone.json) | | Реальная роль Valkey | `make verify` | 20 cache hits, stop/flush не теряют данные/сессию | | Parameter binding, bounded pool и timeouts | `python -m scripts.verify_pool`, `make verify` | [pool.json](evidence/pool.json): pool1, ожидание 1.005 с →503; pause PG4.011 с →503 | | Индекс, EXPLAIN ≥10k | `make research` | 90 планов для 5 размеров чата; [query-plan.json](evidence/query-plan.json) | | Expiry, logout, неверный пароль, отказы | HTTP-тесты, lifecycle | TTL2s →401; stop cache →200; stop PG →503; logout →401 | | Трек2: ≥100k, индексы/запись/backup | research | 101110 сообщений, 2 индекса, 3 повтора, восстановление и сверка | -| Независимый clean clone | `python scripts/verify_clean.py` | Результат будет добавлен после фактического завершения | +| Независимый clean clone | `python scripts/verify_clean.py` | Полный PASS с новыми секретами/volumes, 77 passed; [clean-clone.json](evidence/clean-clone.json) | Первая проверка не утверждает наличие карточки в cache непосредственно перед PG fault без дополнительного EXISTS: [границы evidence](evidence/verification-notes.md). -Финальный вариант дополнительно проверяет это и неизменность expires_at. +Финальный вариант проверил это и неизменность expires_at. + +## Финальный чистый clone + +Проверен source commit `8e3e16a8a6ea07f6a2b8615045735f812299e3d1`. +Новые `.env`, секреты и volumes; pinned image build; check/validate/lint; +публичный smoke; **77 passed за 86 с**; public persistence; lifecycle, +pool и checksum guard — PASS. Повторно выполнено исследование: 101110 +сообщений, 90 EXPLAIN-планов, backup/restore snapshot совпал. +Хэши runtime-модулей совпали; image revision соответствует source commit. +Все временные containers/volumes этого clone удалены, рабочий volume сохранён. + +Первая попытка clean-clone проверки остановилась на persistence: Docker +сменил автоматически назначенный host-порт при restart, а тест сохранил +прежний BASE_URL. Смена подтверждена на том же контейнере (65424 → 65441). +Проверка исправлена выбирать свободный **фиксированный** номер порта один +раз; код API/сессий не менялся. Первая попытка не выдана за успешную: +[описание](evidence/clean-attempt1.txt), [диагностика](evidence/port-restart.json). +Итоговый полный повтор — [clean-clone.json](evidence/clean-clone.json). + +После проверенного source commit менялись только отчёт, шаблон и evidence; +runtime src, зависимости, Dockerfile и Compose остались теми же. +Добавлен отдельный application workflow для CI; наличие файла не означает +его запуска на Gitea. Публикация, fork/MR и удалённый CI пока не выполнялись. ## Исследование: методика и результаты @@ -149,7 +173,7 @@ SQL seed: 5 чатов 90000/10000/1000/100/10, всего101110 сообщен для входа. Данных других людей нет. Сравниваются chat_id-only и `(chat_id,created_at,id)`. На каждом варианте -VACUUM ANALYZE и прогрев; head/middle/tail каждой истории, LIMIT51, +VACUUM ANALYZE и прогрев; head/middle/tail каждой истории, LIMIT 51, EXPLAIN ANALYZE BUFFERS. Три повтора с порядком A/B, B/A, A/B; custom plans, prepared statements в эксперименте отключены. Подготовительный OFFSET применяется только для получения контрольной границы вне измеряемого @@ -160,24 +184,24 @@ prepared statements в эксперименте отключены. Подгот | chat_id | 7.237 | 2209 | 729088 | 37.53 | 347536 | | keyset | 0.017 | 5 | 5980160 | 11.55 | 427672 | -Это медианы3; min/max и остальные размеры/позиции — +Это медианы трёх повторов; min/max и остальные размеры/позиции — [query-summary.csv](evidence/query-summary.csv), полные планы — [query-plan.json](evidence/query-plan.json). График построен из raw и проверен: ![SQL планы](evidence/query-plans.png) -Гипотеза чтения подтверждается. Цена — индекс примерно в8.2 раза больше +Гипотеза чтения подтверждается. Цена — индекс примерно в 8.2 раза больше и больший WAL на запись. Рост именно времени INSERT **не подтвердился**: в этом опыте keyset быстрее и на записи. Причину этого различия отдельный профиль не устанавливал. WAL — глобальный PG-счётчик; фон и cache state могут влиять. EXPLAIN execution time не называется HTTP latency или CPU time. -Backup pg_dump -Fc: 3026259bytes,0.480с; pg_restore в новую БД:0.664с. -Сверены count всех6таблиц, SHA-256 всей истории и15полных сообщений. -После snapshot специально сделан ещё один SQL COMMIT: в источнике101111, -в восстановленной копии101110. Это демонстрация границы snapshot/RPO, +Backup pg_dump -Fc: 3026259 bytes, 0.480 с; restore в новую БД: 0.664 с. +Сверены count всех 6 таблиц, SHA-256 всей истории и 15 полных сообщений. +После snapshot специально сделан ещё один SQL COMMIT: в источнике 101111, +в восстановленной копии 101110. Это демонстрация границы snapshot/RPO, не измерение потери HTTP-подтверждений и не универсальный RTO сервиса. -Пик PG cgroup с момента старта контейнера266039296bytes (включает подготовку +Пик PG cgroup с момента старта контейнера 266039296 bytes (включает подготовку и прочие проверки); это не RSS отдельного процесса и не пик только SELECT. ```sh @@ -198,10 +222,10 @@ uv run --locked python -m research.analyze evidence/query-plan-repeat.json Flush/restart cache даёт miss, но токен остаётся действующим; logout действует через PG независимо от TTL карточки. 3. **Auth против ACL?** Сессия определяет пользователя. Отдельная проверка - membership определяет доступ к чату; посторонний получает такой же404, + membership определяет доступ к чату; посторонний получает такой же 404, как отсутствующий ресурс. Успешный login сам по себе доступ не даёт. 4. **KDF и checksum?** Человеческий пароль имеет ограниченную энтропию, - поэтому нужен дорогой Argon2id с солью. Случайный256битный токен можно + поэтому нужен дорогой Argon2id с солью. Случайный 256-битный токен можно индексировать быстрым SHA-256 digest; checksum backup решает проверку целостности данных, а не защиту пароля. diff --git a/evidence/clean-clone.json b/evidence/clean-clone.json new file mode 100644 index 0000000..4fd43f5 --- /dev/null +++ b/evidence/clean-clone.json @@ -0,0 +1,117 @@ +{ + "date": "2026-11-07T05:26:38.162144+00:00", + "source_commit": "8e3e16a8a6ea07f6a2b8615045735f812299e3d1", + "fresh_secrets_environment_and_volumes": true, + "command": "python scripts/verify_clean.py", + "fixed_host_port_for_restart": 49287, + "static_checks": ".venv/bin/python scripts/check_contract.py\nPASS: offline skeleton structure, local refs and Python syntax; application NOT tested.\n.venv/bin/python scripts/validate_openapi.py\nPASS: full OpenAPI 3.1 and JSON Schema validation; application NOT tested.\n/.local/bin/uv run --locked ruff format src student-tests research scripts/bootstrap.py scripts/stand.py scripts/verify_*.py\n26 files left unchanged\n/.local/bin/uv run --locked ruff check src student-tests research scripts/bootstrap.py scripts/stand.py scripts/verify_*.py\nAll checks passed!", + "internal_store_ports_not_published": true, + "smoke": "python3 tests/smoke.py --base-url \"http://127.0.0.1:49287\" \nPASS: lab2 public API scenario; infrastructure and grading evidence remain separate.", + "http_tests": "........................................................................ [ 93%]\n..... [100%]\n77 passed in 86.00s (0:01:25)", + "public_persistence": "python3 tests/resilience.py --mode persistence --action-script \"scripts/restart.sh\" --base-url \"http://127.0.0.1:49287\" \nExecuting explicit persistence hook; hook output suppressed to avoid leaking secrets.\nPASS: persistence preserved confirmed data and existing session. Hook scope needs operator evidence.", + "verify_lifecycle": { + "date": "2026-11-07T05:28:29.159541+00:00", + "commit": "8e3e16a8a6ea07f6a2b8615045735f812299e3d1", + "command": "python -m scripts.verify_lifecycle", + "runtime_source_hashes_match": true, + "image_revision": "8e3e16a8a6ea07f6a2b8615045735f812299e3d1", + "persistence": { + "absolute_expiry_unchanged": true, + "same_token": true, + "same_message": true, + "before": { + "api": { + "container": "4cc53c6190ac", + "pid": 89123, + "started_at": "2026-11-07T05:28:24.620912381Z" + }, + "postgres": { + "container": "910b02e40597", + "pid": 88965, + "started_at": "2026-11-07T05:28:24.260037964Z" + }, + "cache": { + "container": "d47529714a4a", + "pid": 88983, + "started_at": "2026-11-07T05:28:24.279300006Z" + } + }, + "after": { + "api": { + "container": "4cc53c6190ac", + "pid": 89990, + "started_at": "2026-11-07T05:28:30.971012968Z" + }, + "postgres": { + "container": "910b02e40597", + "pid": 89812, + "started_at": "2026-11-07T05:28:30.640581301Z" + }, + "cache": { + "container": "d47529714a4a", + "pid": 89865, + "started_at": "2026-11-07T05:28:30.700865926Z" + } + }, + "seconds": 5.304535000002943 + }, + "migration_repeat": "PASS", + "bootstrap_preserves_secrets": true, + "credential_storage": { + "argon2id": true, + "digest_bytes": 32, + "raw_password_and_token_absent_in_dump": true + }, + "cache_hits": 20, + "cache_stopped": { + "status": 200, + "seconds": 0.013735125001403503 + }, + "cache_flush_preserves_truth": true, + "postgres_pause": { + "cache_card_present_before_failure": true, + "status": 503, + "seconds": 4.019069417001447, + "cached_identity_not_trusted": true + }, + "postgres_stop": { + "cache_card_present_before_failure": true, + "status": 503, + "seconds": 0.005429041993920691, + "cached_identity_not_trusted": true + }, + "chat_transaction_rollback": { + "injected_failure_status": 500, + "remaining_chat_rows": 0 + }, + "expiry": { + "ttl_seconds": 2, + "status_after_expiry": 401 + }, + "logout_after_cache_hit": "PASS", + "result": "PASS" + }, + "verify_pool": { + "date": "2026-11-07T05:29:04.541663+00:00", + "commit": "8e3e16a8a6ea07f6a2b8615045735f812299e3d1", + "command": "python -m scripts.verify_pool", + "pool_size": 1, + "blocked_insert_observed_in_pg_stat_activity": true, + "pool_wait_seconds": 1.0053121249948163, + "pool_timeout_status": 503, + "statement_timeout_status": 503, + "failed_write_rolled_back": true, + "write_after_recovery": 201, + "result": "PASS" + }, + "applied_migration_checksum_guard": "PASS", + "research_repeated": { + "result": "PASS", + "messages": 101110, + "plans": 90, + "restored_snapshot_equal": true + }, + "fsck": "", + "checks_completed": true, + "result": "PASS" +} diff --git a/evidence/verification-notes.md b/evidence/verification-notes.md index f69db34..ae75266 100644 --- a/evidence/verification-notes.md +++ b/evidence/verification-notes.md @@ -9,5 +9,5 @@ expiry/logout, cache hits и bounded 503 при остановке/паузе Po Финальный скрипт усилен: ждёт окончания backoff, проверяет EXISTS карточки перед каждым воздействием на PG и сравнивает абсолютный expires_at до/после -restart. Этот вариант повторяется в финальном чистом clone; результат -будет в clean-clone.json. Runtime API при этом не менялся. +restart. Этот вариант успешно повторён в финальном чистом clone; результат +в clean-clone.json. Runtime API при этом не менялся.