diff --git a/.github/workflows/application.yml b/.github/workflows/application.yml new file mode 100644 index 00000000..5fcf0cfb --- /dev/null +++ b/.github/workflows/application.yml @@ -0,0 +1,26 @@ +name: Application checks +on: [push, pull_request] +permissions: + contents: read +jobs: + application: + runs-on: ubuntu-24.04 + env: + NO_PROXY: localhost,127.0.0.1 + no_proxy: localhost,127.0.0.1 + steps: + - uses: actions/checkout@v4 + with: + persist-credentials: false + - uses: actions/setup-python@v5 + with: + python-version: '3.14.7' + - run: python -m pip install uv==0.13.7 + - run: uv sync --locked + - run: make bootstrap lint check validate PYTHON=.venv/bin/python + - run: make up + - run: make test test-student + - run: make test-persistence ACTION_SCRIPT=scripts/restart.sh + - run: make verify VERIFY_OUTPUT=.work/ci-lifecycle.json + - if: always() + run: docker compose down --volumes diff --git a/Makefile b/Makefile index e50192c1..c6a8062b 100644 --- a/Makefile +++ b/Makefile @@ -27,6 +27,8 @@ test-persistence: UV ?= uv IMAGE ?= mtusi-messenger:lab2 +VERIFY_OUTPUT ?= evidence/lifecycle-repeat.json +RESEARCH_OUTPUT ?= evidence/query-plan-repeat.json .PHONY: bootstrap up down lint test-student image verify research bootstrap: @@ -43,6 +45,6 @@ lint: test-student: BASE_URL="$(BASE_URL)" $(UV) run --locked pytest student-tests verify: - $(UV) run --locked python -m scripts.verify_lifecycle --output evidence/lifecycle.json + $(UV) run --locked python -m scripts.verify_lifecycle --output "$(VERIFY_OUTPUT)" research: - $(UV) run --locked python -m research.query_plan --output evidence/query-plan.json + $(UV) run --locked python -m research.query_plan --output "$(RESEARCH_OUTPUT)" diff --git a/REPORT.md b/REPORT.md index e42f2b05..402b9607 100644 --- a/REPORT.md +++ b/REPORT.md @@ -1,37 +1,226 @@ -# Отчёт — лабораторная 2 +# Лабораторная 2 — PostgreSQL, сессии и Valkey -- Автор, группа: TODO -- Целевая оценка; выбранный трек 5, если нужен: TODO -- Commit/PR: TODO после публикации -- Использованные источники, библиотеки и помощь ИИ: TODO +Автор: **Маслов, БВТ2301**. Цель: **5**, трек 2 «План запроса и восстановление». +Ветка `solution/bvt2301-maslov`; основа — skeleton ЛР2, ветка master. +Публикации и удалённого CI пока нет. -## Запуск из чистого clone +## Воспроизводимый запуск -TODO: версии runtime/образов, prerequisites, команды создания локальных secrets/.env, build, миграций, запуска, ожидания готовности, тестов и остановки. Указать необходимые действия оператора. Не вставлять секреты. Отдельно указать безопасную остановку и команду намеренного удаления учебных данных. +Нужны 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. +Точные транзитивные версии — `uv.lock`. Базовые образы Python/uv, +PostgreSQL 18.3 и Valkey 8.1.3 закреплены тегами и digest. -## Архитектура и решения +```sh +uv sync --locked +make bootstrap +make check validate PYTHON=.venv/bin/python +make lint +make up +NO_PROXY=localhost,127.0.0.1 no_proxy=localhost,127.0.0.1 make test +make test-student +NO_PROXY=localhost,127.0.0.1 no_proxy=localhost,127.0.0.1 \ + make test-persistence ACTION_SCRIPT=scripts/restart.sh +make verify +uv run --locked python -m scripts.verify_pool --output evidence/pool-repeat.json +``` -TODO: схема процессов/хранилищ, источник истины, транзакционные границы, ограничения. Что перенесено из lab1, что изменено в этой работе. Соответствие переменных из .env.example реальной конфигурации. +API: `http://127.0.0.1:8082`. PostgreSQL/Valkey не публикуют host-порты. +Для другого порта задать PUBLIC_PORT в окружении и передавать BASE_URL +проверкам. Все повторные evidence должны иметь новые имена файлов. -## Доказательства критериев +`make down` останавливает стенд, сохраняя PostgreSQL volume. Его повторный +запуск использует прежние данные и секреты. Намеренное удаление **только +учебных данных данного проекта**: `docker compose down --volumes`. +Не применять к рабочим данным и не запускать глобальный Docker prune. -| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства | -| --- | --- | --- | --- | -| Публичный smoke | make test | TODO | TODO | -| Остальные пункты уровня 3 | TODO | TODO | TODO | -| Все пункты уровня 4, если заявлен | TODO | TODO | TODO | -| Выбранный трек 5, если заявлен | TODO | TODO | TODO | +Bootstrap создаёт только отсутствующие `.env`/secret files. Каталог secrets +имеет 0700, файлы доступны non-root контейнеру через read-only file mounts. +Не пересоздавать пароль при сохранённом PG volume: initdb уже создал роль +со старым паролем. В Git/образ секреты и .env не попадают. -TODO: добавить отдельную строку для каждого заявленного критерия. PASS без команды и наблюдения не является доказательством. Проверка инфраструктурного hook требует подтверждения, какие реальные процессы/хранилища перезапущены. +Конфигурация: APP_HOST/APP_PORT — bind внутри API; PUBLIC_PORT — Compose; +DATABASE_URL_FILE/CACHE_URL_FILE — пути к файловым секретам; +SESSION_TTL_SECONDS — абсолютный срок сессии (default 3600); +DB_POOL_SIZE — 1…32 (default 10). SESSION_STORE=postgres и APP_ENV в example +информационные: реализация не переключает источник истины этими строками. +Compose передаёт приложению только нужные ему настройки и секреты. -## Эксперименты и отказы +## Архитектура и перенос -TODO: гипотеза, hardware/лимиты, версии, объём данных, профиль нагрузки, concurrency/arrival rate, длительность/прогрев, повторы, успешные RPS, ошибки, p50/p95/p99, CPU/RAM. Сохранить raw summary без tokens и объяснить ограничения измерения. +Из своей ЛР1 перенесены HTTP-контракт, строгие схемы, ошибки/request ID, +ACL, UUID/UTC, cursor и собственные HTTP-тесты. Сохранены неизменёнными +README/COURSE/contracts/tests **текущего** skeleton. Git-история ЛР1 +не переносилась; репозиторий ЛР2 независим. -| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных | -| --- | --- | --- | --- | -| TODO | TODO | TODO | TODO | +```mermaid +flowchart LR + C[HTTP клиент] --> API[FastAPI: JSON, auth, request ID] + API --> T[Ограниченный threadpool: сервисные операции] + T --> PG[(PostgreSQL: данные и сессии)] + T --> V[(Valkey: карточка User, TTL 30 s)] + M[Одноразовый migrate] --> PG +``` -## Ограничения и следующие шаги +SQL parameter binding используется для всех данных клиента. Динамические +идентификаторы в research — через psycopg.sql.Identifier и проверенный +UUID-префикс; в рабочем API пользователь не задаёт имена таблиц/SQL. -TODO: какие отказы выдерживаются и какие нет; что не реализовано; где учебное упрощение; какое улучшение подтверждено, а какое пока гипотеза. +Модель и транзакции заданы до SQL в [PLAN.md](PLAN.md): + +| Объект/операция | Ограничения и граница | +|---|---| +| users | UUID PK, UNIQUE username; KDF до получения соединения; INSERT атомарен | +| chats + members | FK, уникальный участник/позиция; чат и все участники в одной транзакции | +| messages | FK(chat_id,sender_id) на members; INSERT подтверждается после COMMIT | +| sessions | PK digest32bytes, FK user, created_at/expires_at; raw token не хранится | +| history | `(chat_id,created_at,id)`, tuple keyset + LIMIT limit+1 | +| migrations | SQL-файлы, checksum и advisory lock; отдельный сервис до API | + +Миграции с нуля и повторное применение не создают пользовательские данные. +Изменение применённого файла отклоняется; добавляется новая миграция. +API сам схему не создаёт. Отказ migrate блокирует запуск API в Compose. + +Пул на процесс: min 1 / max 10, ожидание 1 с; connect_timeout 2 с; +statement_timeout 2.5 с, lock_timeout 1 с, idle transaction timeout 6 с. +Общий клиентский срок операций на выданном соединении — 4 с, включая +замороженный сервер. При таймауте соединение закрывается и не возвращается +в пул как исправное. SQL, KDF и cache I/O не блокируют ASGI event loop. +Liveness не обращается к БД; readiness проверяет PostgreSQL, не Valkey. + +## Пароли, сессии и кэш + +- Argon2id: 64 MiB, t=3, p=4. Одновременно не больше двух KDF на процесс, + ожидание слота ограничено 5 с. UTF-8 пароль 12–128 code points обрабатывается + целиком, без усечения/нормализации. Проверено 127 emoji и двоеточие. +- Basic — только POST auth/sessions; собственный строгий base64/UTF-8 parser, + разделение по первому двоеточию. Неизвестный username проходит dummy KDF, + возвращается тот же 401. Хэш/пароль не входят в UserDTO и HTTP-ошибки. +- Токен — secrets.token_urlsafe(32), 256 бит энтропии; PostgreSQL хранит + только SHA-256 digest случайного токена. Это не password KDF и не JWT. +- Каждый запрос проверяет сессию и абсолютный expires_at **в PostgreSQL**. + Logout удаляет сессию; прежний cache hit не оживляет её. X-User-Id + игнорируется, Basic на бизнес-endpoint даёт 401. WWW-Authenticate + соответствует Basic/Bearer. Restart срок не продлевает. +- Valkey хранит только неизменяемую карточку User, TTL 30 с, maxmemory 64 MiB, + allkeys-lru; persistence выключена, собственного volume нет. Ошибка + cache — miss и чтение PG, backoff 5 с; socket/connect timeout 0.15 с, + скрытые retry отключены. При отказе PG cached User не авторизует запрос. +- API не изменяет карточки пользователей, поэтому инвалидации при записи + не требуется. При восстановлении старого snapshot вне API кэш надо + очистить. История вообще не кэшируется: read-after-write идёт из PG. + +Образы API: non-root UID10001, exec Python PID1, healthcheck, read-only rootfs, +tmpfs и cap_drop=ALL. Лимиты API 1 CPU/512 MiB, PG 1 CPU/512 MiB, cache +0.25 CPU/128 MiB. Логи JSON: request ID/маршрут/код/время; без тел, +Authorization, паролей, токенов, их digest и параметров SQL. + +## Таблица доказательств + +| Критерий README | Команда | Факт / evidence | +|---|---|---| +| 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 в финальной проверке | +| Реальная роль 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` | Результат будет добавлен после фактического завершения | + +Первая проверка не утверждает наличие карточки в cache непосредственно +перед PG fault без дополнительного EXISTS: [границы evidence](evidence/verification-notes.md). +Финальный вариант дополнительно проверяет это и неизменность expires_at. + +## Исследование: методика и результаты + +Гипотеза в PLAN закоммичена до замера. Стенд: Apple M1, 8 CPU, 8 GiB RAM, +Docker Desktop 4.98.0/Engine29.9.2; PostgreSQL в контейнере 1 CPU/512 MiB. +Рабочие таблицы messenger не меняются: создаются research_UUID и restored_UUID +именно данного запуска, затем удаляются вместе с временным dump. + +SQL seed: 5 чатов 90000/10000/1000/100/10, всего101110 сообщений; +уникальные тексты80ASCII. Seed обходит HTTP, это явно исследовательский +набор, а не нагрузка регистрации/Argon2. Схема и migration metadata +соответствуют приложению; исследовательский пользователь не используется +для входа. Данных других людей нет. + +Сравниваются chat_id-only и `(chat_id,created_at,id)`. На каждом варианте +VACUUM ANALYZE и прогрев; head/middle/tail каждой истории, LIMIT51, +EXPLAIN ANALYZE BUFFERS. Три повтора с порядком A/B, B/A, A/B; custom plans, +prepared statements в эксперименте отключены. Подготовительный OFFSET +применяется только для получения контрольной границы вне измеряемого +запроса; рабочая пагинация использует только keyset. + +| Индекс | SQL middle90k, мс | Буферы | Размер, bytes | INSERT+COMMIT1000, мс | WAL, bytes | +|---|---:|---:|---:|---:|---:| +| chat_id | 7.237 | 2209 | 729088 | 37.53 | 347536 | +| keyset | 0.017 | 5 | 5980160 | 11.55 | 427672 | + +Это медианы3; min/max и остальные размеры/позиции — +[query-summary.csv](evidence/query-summary.csv), полные планы — +[query-plan.json](evidence/query-plan.json). График построен из raw и проверен: + +![SQL планы](evidence/query-plans.png) + +Гипотеза чтения подтверждается. Цена — индекс примерно в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, +не измерение потери HTTP-подтверждений и не универсальный RTO сервиса. +Пик PG cgroup с момента старта контейнера266039296bytes (включает подготовку +и прочие проверки); это не RSS отдельного процесса и не пик только SELECT. + +```sh +uv run --locked python -m research.query_plan --output evidence/query-plan-repeat.json +uv run --locked python -m research.analyze evidence/query-plan-repeat.json +``` + +Запускать последовательно с проверками отказов. Сырые результаты не +перезаписываются; dump не публикуется и не содержит рабочих данных. + +## Вопросы защиты и ограничения + +1. **Что подтверждает COMMIT?** Транзакция завершена и видна следующим + запросам согласно isolation. Проверены fsync=on, synchronous_commit=on, + full_page_writes=on. WAL flush защищает штатный durability сценарий, + но не потерю единственного диска/VM/host и не заменяет backup. +2. **Где сессии и что даст flush cache?** Сессии в PG, в cache только User. + Flush/restart cache даёт miss, но токен остаётся действующим; logout + действует через PG независимо от TTL карточки. +3. **Auth против ACL?** Сессия определяет пользователя. Отдельная проверка + membership определяет доступ к чату; посторонний получает такой же404, + как отсутствующий ресурс. Успешный login сам по себе доступ не даёт. +4. **KDF и checksum?** Человеческий пароль имеет ограниченную энтропию, + поэтому нужен дорогой Argon2id с солью. Случайный256битный токен можно + индексировать быстрым SHA-256 digest; checksum backup решает проверку + целостности данных, а не защиту пароля. + +Один PG/cache/API на host — не HA. Нет TLS на внешнем маршруте, стенд +только loopback и синтетические данные. PG init-role владеет учебной БД +и имеет широкие права; production разделение SQL-ролей не заявляется. +Backup snapshot не сохраняет последующие сообщения/отзывы сессий; без +WAL-архива и recovery policy это неизбежное ограничение восстановления. +POST сообщения ЛР2 не идемпотентен: после неизвестного исхода COMMIT +автоматический retry может создать дубль; это задача ЛР3. + +## Источники и помощь + +README/COURSE/contracts/tests преподавателя; справочные методические наборы; +[PostgreSQL](https://www.postgresql.org/docs/18/), +[Psycopg](https://www.psycopg.org/psycopg3/docs/), +[Argon2](https://argon2-cffi.readthedocs.io/), +[Valkey](https://valkey.io/topics/), FastAPI/Pydantic/Uvicorn. +Поведение client timeout дополнительно сверено с установленным кодом +psycopg3.3.6 и реальной паузой PostgreSQL. +Помощь ИИ использована при разборе требований, реализации, тестах и отчёте; +измерения подтверждены сохранёнными запусками. diff --git a/evidence/clean-attempt1.txt b/evidence/clean-attempt1.txt new file mode 100644 index 00000000..36ca0845 --- /dev/null +++ b/evidence/clean-attempt1.txt @@ -0,0 +1,12 @@ +Source commit: 7466a09 +Status: INCOMPLETE, not a successful final clean-clone verification. + +The first isolated clone used PUBLIC_PORT=0 (automatic host port). +Bootstrap/build/static checks, smoke and HTTP tests completed before the +public persistence stage. After restart the public client kept its original +BASE_URL and could not recover within 90 seconds. Temporary project and +its volumes were removed by the cleanup handler. + +Diagnostic reproduction checks whether Docker reassigns an automatic host +port on restart. Final verification selects an available numeric host port +once, so its BASE_URL remains valid through the restart hook. diff --git a/evidence/port-restart.json b/evidence/port-restart.json new file mode 100644 index 00000000..9e981350 --- /dev/null +++ b/evidence/port-restart.json @@ -0,0 +1,10 @@ +{ + "date": "2026-11-07", + "scope": "own temporary API, same container before and after docker restart", + "requested_host_port": "automatic", + "before": 65424, + "after": 65441, + "port_changed": true, + "result": "CONFIRMED", + "fix": "Choose a free numeric host port once for the clean-clone Compose project. Keep BASE_URL stable through the public persistence hook." +} diff --git a/scripts/verify_clean.py b/scripts/verify_clean.py index 85165799..abfdbd44 100644 --- a/scripts/verify_clean.py +++ b/scripts/verify_clean.py @@ -1,6 +1,8 @@ import argparse +import atexit import json import os +import socket import subprocess import tempfile from datetime import UTC, datetime @@ -8,6 +10,31 @@ from pathlib import Path from uuid import uuid4 ROOT = Path(__file__).resolve().parents[1] +PROGRESS = {} + + +def save_incomplete(): + receipt = PROGRESS.get("receipt") + if receipt and receipt.get("result") != "PASS": + target = PROGRESS["output"].with_name( + PROGRESS["output"].stem + "-failed.json" + ) + if target.exists(): + target = target.with_name( + target.stem + "-" + uuid4().hex[:8] + target.suffix + ) + target.parent.mkdir(parents=True, exist_ok=True) + target.write_text( + json.dumps( + {**receipt, "result": "INCOMPLETE"}, + ensure_ascii=False, + indent=2, + ) + + "\n" + ) + + +atexit.register(save_incomplete) def run(args, *, cwd, env, expected=0): @@ -23,6 +50,8 @@ def run(args, *, cwd, env, expected=0): ) if result.returncode != expected: + if "receipt" in PROGRESS: + PROGRESS["receipt"]["failed_action"] = redact(" ".join(args)) raise RuntimeError(redact(result.stdout + result.stderr)) return redact(result.stdout.strip()) @@ -42,11 +71,14 @@ def main(): ).strip() identity = uuid4().hex[:10] project = "mtusi-lab2-clean-" + identity + with socket.socket() as reservation: + reservation.bind(("127.0.0.1", 0)) + public_port = str(reservation.getsockname()[1]) env = { **os.environ, "COMPOSE_PROJECT_NAME": project, "API_IMAGE": "mtusi-messenger:lab2-clean-" + identity, - "PUBLIC_PORT": "0", + "PUBLIC_PORT": public_port, "VCS_REF": sha, "NO_PROXY": "localhost,127.0.0.1", "no_proxy": "localhost,127.0.0.1", @@ -56,7 +88,9 @@ def main(): "source_commit": sha, "fresh_secrets_environment_and_volumes": True, "command": "python scripts/verify_clean.py", + "fixed_host_port_for_restart": int(public_port), } + PROGRESS.update(receipt=receipt, output=output) with tempfile.TemporaryDirectory(prefix="mtusi-lab2-clean-") as temporary: clone = Path(temporary) / "lab2" run( @@ -195,7 +229,7 @@ def main(): receipt["fsck"] = run( ["git", "fsck", "--full"], cwd=clone, env=env ) - receipt["result"] = "PASS" + receipt["checks_completed"] = True finally: assert project.startswith("mtusi-lab2-clean-") run( @@ -203,6 +237,7 @@ def main(): cwd=clone, env=env, ) + receipt["result"] = "PASS" output.parent.mkdir(parents=True, exist_ok=True) output.write_text(json.dumps(receipt, ensure_ascii=False, indent=2) + "\n") print(json.dumps(receipt, ensure_ascii=False, indent=2))