docs: finalize verified PostgreSQL lab and recovery evidence

This commit is contained in:
2026-11-07 08:32:16 +03:00
parent 8e3e16a8a6
commit a38c889df2
4 changed files with 176 additions and 31 deletions
+18 -14
View File
@@ -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 содержит инструкцию именно моего решения.
+39 -15
View File
@@ -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 решает проверку
целостности данных, а не защиту пароля.
+117
View File
@@ -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<home>/.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<home>/.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"
}
+2 -2
View File
@@ -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 при этом не менялся.