From 38de8782c4f7628b886a983bf1e69163be7e506e Mon Sep 17 00:00:00 2001 From: lenovo Date: Sun, 18 Oct 2026 16:03:35 +0300 Subject: [PATCH] =?UTF-8?q?=D0=97=D0=B0=D0=BF=D0=BE=D0=BB=D0=BD=D0=B8?= =?UTF-8?q?=D1=82=D1=8C=20PR-=D1=88=D0=B0=D0=B1=D0=BB=D0=BE=D0=BD=20=D0=B8?= =?UTF-8?q?=20=D0=B2=D1=8B=D0=B2=D0=BE=D0=B4=20make=20test?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .github/pull_request_template.md | 65 ++++++++++++++++++------ README.md | 24 ++------- REPORT.md | 8 +-- evidence/compose-shutdown.txt | 13 +---- evidence/compose-start.txt | 85 ++++++++++++++++++++++++++++++++ evidence/make-test.txt | 5 ++ 6 files changed, 149 insertions(+), 51 deletions(-) create mode 100644 evidence/compose-start.txt create mode 100644 evidence/make-test.txt diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 8ceefa1..d44ba3d 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -1,18 +1,55 @@ ## Лабораторная 2 -Автор / группа: TODO -Целевая оценка (3/4/5): TODO -Трек 5, если заявлен: TODO +Автор / группа: Федотов Михаил, БВТ2302 +Целевая оценка (3/4/5): **4** +Трек 5: **не заявлен** -Что реализовано и что перенесено: TODO -Команды запуска из чистого clone: TODO -Результаты проверок и ссылка на REPORT.md: TODO -Ограничения / известные ошибки: TODO -Источники и использование ИИ: TODO +### Что реализовано и что перенесено -- [ ] Весь обязательный минимум текущей и предыдущих работ сохранён с объявленными переходами. -- [ ] Контракт и публичные тесты не ослаблены. -- [ ] make check и make test выполнены; приложен реальный вывод. -- [ ] Сценарии отказов/безопасности своего уровня воспроизведены. -- [ ] Все секреты и приватные ключи находятся вне Git; отчёт не содержит tokens. -- [ ] README задания сохранён, REPORT.md содержит инструкцию именно моего решения. +- Реализован HTTP API на FastAPI; PostgreSQL хранит пользователей, чаты, участников и сообщения. Схема создаётся версионируемыми миграциями. +- Создание чата и его участников атомарно. История сообщений читается keyset-пагинацией по индексу `(chat_id, created_at, id)`. +- Redis используется как хранилище сессий: непрозрачный Bearer-токен, фиксированный TTL, logout и AOF persistence. Пароли хешируются Argon2id; SQL-запросы параметризованы. +- Переход аутентификации объявлен: пароль задаётся при регистрации, Basic применяется только для `POST /auth/sessions`, бизнес-запросы используют Bearer. Lab1 в исходном репозитории представлен skeleton; совместимость с прежним `X-User-Id` как механизмом доступа не сохраняется. Миграция 0002 удаляет старые сессии PostgreSQL, поэтому после обновления нужно войти заново. + +### Запуск из чистого clone + +Из корня репозитория в WSL (нужны Docker Compose и Python 3): + +```sh +cp -n .env.example .env +# Установить локальный POSTGRES_PASSWORD в .env. +docker compose --env-file .env config --quiet +docker compose --env-file .env up -d --build +docker compose ps # дождаться healthy у api, postgres и redis +make check +make test +make test-persistence ACTION_SCRIPT=scripts/restart.sh +make test-grade4 +docker compose --env-file .env down # тома сохраняются +``` + +### Результаты проверок + +- `make check` — PASS; `make test` — PASS; `make test-grade4` — PASS, включая smoke и persistence. +- Проверены параллельная регистрация (1 × 201, 7 × 409), неверный пароль (401), rollback создания чата, expiry сессии, отказы Redis/PostgreSQL с ограниченным 503 и восстановление после перезапуска. +- `EXPLAIN (ANALYZE, BUFFERS)` на 10 000 синтетических сообщений выбрал `messages_history_idx`; страница из 50 строк прочитала 6 shared buffers. Это единичный замер плана запроса, не нагрузочный benchmark. +- Реальный stdout сохранён в [`evidence/make-check.txt`](../../evidence/make-check.txt), [`evidence/make-test.txt`](../../evidence/make-test.txt), [`evidence/make-test-grade4.txt`](../../evidence/make-test-grade4.txt), [`evidence/explain-history.txt`](../../evidence/explain-history.txt) и других файлах каталога `evidence/`. +- Подробное описание архитектуры, проверок и ограничений: [`REPORT.md`](../../REPORT.md). + +### Ограничения / известные ошибки + +- Уровень 5 и его экспериментальный трек не заявляются; пропускная способность под длительной нагрузкой и RTO/RPO не измерялись. +- Не проверялись восстановление из отдельной резервной копии и потеря/повреждение файлов Redis AOF при отказе хоста. +- При потере Redis аутентифицированные операции завершаются ограниченной ошибкой; резервного хранилища сессий нет. +- Старые PG-сессии при миграции 0002 отзываются; требуется повторный вход. + +### Источники и использование ИИ + +Использованы материалы из README задания: [PostgreSQL transactions](https://www.postgresql.org/docs/current/tutorial-transactions.html), [PostgreSQL EXPLAIN](https://www.postgresql.org/docs/current/using-explain.html), [Redis persistence](https://redis.io/docs/latest/operate/oss_and_stack/management/persistence/) и [RFC 7617](https://www.rfc-editor.org/info/rfc7617/). При подготовке кода и документации использовался Codex (ИИ-ассистент); результат проверен командами и сценариями, указанными выше. + +- [x] Обязательный минимум текущего задания реализован; переход от lab1 и изменение аутентификации объявлены выше и в `REPORT.md`. +- [x] Контракт и публичные тесты не ослаблялись. +- [x] `make check` и `make test` выполнены; фактический stdout приложен в `evidence/`. +- [x] Проверены сценарии отказов и безопасности уровня 4. +- [x] `.env`, токены и приватные ключи в Git не добавлялись; доказательства обезличены. +- [x] Исходный README задания сохранён; инструкция запуска именно этой реализации находится в `REPORT.md`. diff --git a/README.md b/README.md index dfc20f4..0e073ff 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ Перенести состояние в постоянное хранилище и связать запросы с аутентифицированным пользователем. Подтверждённые сообщения и действующие сессии переживают перезапуск. -Исходный репозиторий — skeleton с заданием, контрактом и публичными проверками. В этой рабочей ветке добавлена реализация минимума на FastAPI и PostgreSQL; дальше её нужно проверять и развивать по критериям лабораторной. Язык и framework свободные; UI не обязателен. +Это **skeleton**, а не готовый сервер. Здесь есть задание, контракт и публичные проверки. Реализацию приложения, Dockerfile и требуемую инфраструктуру пишет студент. Язык и framework свободные; UI не обязателен. [Карта курса](COURSE.md) · [Процесс fork/PR](CONTRIBUTING.md) · [OpenAPI](contracts/openapi.json) · [Семантика API](contracts/README.md) · [Проверки](tests/README.md) · [Отчёт](REPORT.md) · [Примеры JSON](contracts/examples.json) · [Памятка преподавателю](MAINTAINERS.md) @@ -25,7 +25,7 @@ - Минимум lab1 сохранён с объявленным переходом на новую аутентификацию. Все обязательные данные и ещё действующие сессии переживают рестарт API и хранилищ без удаления volumes. - PostgreSQL содержит пользователей, чаты, участников и сообщения. Есть первичные/внешние ключи, уникальность username и миграции с нуля. Составная операция создания чата выполняется атомарно. - Basic применяется только на POST /auth/sessions, остальные endpoint требуют Bearer. Есть срок жизни сессии и отзыв; X-User-Id не даёт доступ. Пароли уже хешируются password KDF. -- `make test`, `make test-persistence ACTION_SCRIPT=scripts/restart.sh` и `make test-grade4` проходят. Миграции повторно запускаются без дублирования данных. Secrets/volumes не попадают в Git. +- make test и make test-persistence ACTION_SCRIPT=scripts/restart.sh проходят. Миграции повторно запускаются без дублирования данных. Secrets/volumes не попадают в Git. ## Оценка «4»: уровень стажёра/джуна @@ -44,25 +44,7 @@ **Трек 2. План запроса и восстановление.** Исследуйте ≥100 000 сообщений с неравномерными размерами чатов, сравните ≥2 индекса/запроса и стоимость записи. Сделайте backup → восстановление в новое хранилище → сверку количества и выбранных сообщений. Обсудите время восстановления и границы потери данных. -### Запуск реализации этой ветки - -В WSL из корня репозитория: - -```sh -cp -n .env.example .env -# Замените POSTGRES_PASSWORD на локальный пароль из букв и цифр. -docker compose --env-file .env config --quiet -docker compose --env-file .env up -d --build -# Дождаться healthy у api, postgres и redis: -docker compose ps -make test -chmod +x scripts/restart.sh -make test-persistence ACTION_SCRIPT=scripts/restart.sh -make test-grade4 -``` - -API применяет новые SQL-миграции при старте. PostgreSQL хранит основные данные в `postgres_data`; Redis хранит сессии в `redis_data` с AOF и `appendfsync always`. Сессия имеет фиксированный абсолютный expiry, logout удаляет её из Redis. Порты API и PostgreSQL публикуются только на `127.0.0.1`, поскольку локальный HTTP не предназначен для удалённого доступа. При переходе с предыдущей версии старые PG-сессии отзываются миграцией 0002; выполните вход заново. `docker compose down` сохраняет тома. Не используйте `docker compose down -v` при проверке сохранности. `make test-grade4` запускает короткий TTL, проверки гонки/отката/отказов, EXPLAIN и затем повторяет smoke и persistence. Запустить только план истории: `docker compose exec -T api python scripts/explain_history.py` (добавляет 10 000 синтетических сообщений). -# Как начать и проверить +## Как начать и проверить ```sh # Работает прямо в skeleton, Python 3.9+; приложение не запускается: diff --git a/REPORT.md b/REPORT.md index 0818ab7..975bfd3 100644 --- a/REPORT.md +++ b/REPORT.md @@ -1,8 +1,8 @@ # Отчёт — лабораторная 2 -- Автор, группа: заполнить перед сдачей +- Автор, группа: Федотов Михаил, БВТ2302 - Целевая оценка: 4 -- Commit/PR: заполнить после публикации +- Commit/PR: `be7a901` (реализация; PR ещё не создан) - Источники и библиотеки: PostgreSQL 16.4, Redis 7.4.2, FastAPI 0.115.6, asyncpg 0.30.0, redis-py 5.2.1, Argon2id через argon2-cffi 23.1.0. При подготовке кода использовалась помощь ИИ. ## Запуск из чистого clone @@ -29,13 +29,13 @@ FastAPI обращается к PostgreSQL через asyncpg и огранич | Отказ Redis | остановка Redis и проверка readiness/создания сессии | PASS: оба пути вернули ограниченный 503 `unavailable`; после запуска readiness восстановилась | `tests/grade4.py`; вывод `make test-grade4` | | Отказ PostgreSQL | остановка PostgreSQL и проверка readiness/регистрации | PASS: оба пути вернули ограниченный 503 `unavailable`; после запуска readiness восстановилась | `tests/grade4.py`; вывод `make test-grade4` | | План keyset-истории на 10 000 сообщениях | `scripts/explain_history.py` внутри контейнера | PASS: выбран `messages_history_idx`, 50 строк, 6 buffer hits; execution time 0.056 ms в этом запуске | `evidence/explain-history.txt` | -| Обезличенные протоколы stdout | `make check`, `make validate`, Compose config, `make test-grade4`, restart hook, shutdown | Вывод каждой команды сохранён отдельно; метаданные запуска и состояние контейнеров записаны отдельно, UUID обезличены | `evidence/make-check.txt`, `evidence/make-validate.txt`, `evidence/compose-config.txt`, `evidence/make-test-grade4.txt`, `evidence/restart-hook.txt`, `evidence/compose-shutdown.txt`, `evidence/verification-metadata-2026-10-18.txt` | +| Обезличенные протоколы stdout | `make check`, `make validate`, Compose config/up/down, `make test`, `make test-grade4`, restart hook | Вывод каждой команды сохранён отдельно; метаданные запуска и состояние контейнеров записаны отдельно, UUID обезличены | `evidence/make-check.txt`, `evidence/make-validate.txt`, `evidence/compose-config.txt`, `evidence/compose-start.txt`, `evidence/make-test.txt`, `evidence/make-test-grade4.txt`, `evidence/restart-hook.txt`, `evidence/compose-shutdown.txt`, `evidence/verification-metadata-2026-10-18.txt` | Все сценарии запускаются командой `make test-grade4`; она собирает образ, задаёт короткий TTL, выполняет дополнительные проверки, восстанавливает штатную конфигурацию, затем запускает smoke и persistence. ## Эксперименты и отказы -Целевой уровень — 4, поэтому сравнительный нагрузочный трек уровня 5 не заявляется. Для критерия плана запроса сценарий создаёт 10 000 синтетических сообщений в отдельном чате, выполняет `ANALYZE`, затем сохраняет фактический `EXPLAIN (ANALYZE, BUFFERS)`. В последнем локальном запуске PostgreSQL выбрал `messages_history_idx`; страница из 50 строк прочитала 6 shared buffers, время выполнения составило 0.056 ms. Это единичный плановый замер в контейнере, не benchmark и не обещание производительности. +Целевой уровень — 4, поэтому сравнительный нагрузочный трек уровня 5 не заявляется. Для критерия плана запроса сценарий создаёт 10 000 синтетических сообщений в отдельном чате, выполняет `ANALYZE`, затем сохраняет фактический `EXPLAIN (ANALYZE, BUFFERS)`. В последнем полном `make test-grade4` запуске PostgreSQL выбрал `messages_history_idx`; страница из 50 строк прочитала 6 shared buffers, время выполнения составило 0.066 ms. Это единичный плановый замер в контейнере, не benchmark и не обещание производительности. | Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных | | --- | --- | --- | --- | diff --git a/evidence/compose-shutdown.txt b/evidence/compose-shutdown.txt index 37f55a0..d63d414 100644 --- a/evidence/compose-shutdown.txt +++ b/evidence/compose-shutdown.txt @@ -1,10 +1,9 @@ -$ docker compose --env-file .env down Container mtusi-lab2-api-1 Stopping Container mtusi-lab2-api-1 Stopped Container mtusi-lab2-api-1 Removing Container mtusi-lab2-api-1 Removed - Container mtusi-lab2-postgres-1 Stopping Container mtusi-lab2-redis-1 Stopping + Container mtusi-lab2-postgres-1 Stopping Container mtusi-lab2-postgres-1 Stopped Container mtusi-lab2-postgres-1 Removing Container mtusi-lab2-postgres-1 Removed @@ -13,13 +12,3 @@ $ docker compose --env-file .env down Container mtusi-lab2-redis-1 Removed Network mtusi-lab2_default Removing Network mtusi-lab2_default Removed - -$ docker compose --env-file .env ps -a -NAME IMAGE COMMAND SERVICE CREATED STATUS PORTS - -$ docker volume ls --filter name=mtusi-lab2 -DRIVER VOLUME NAME -local mtusi-lab2_postgres_data -local mtusi-lab2_redis_data - -PASS: containers stopped; named volumes retained. diff --git a/evidence/compose-start.txt b/evidence/compose-start.txt new file mode 100644 index 0000000..a93815a --- /dev/null +++ b/evidence/compose-start.txt @@ -0,0 +1,85 @@ +$ docker compose --env-file .env up -d --build + Image mtusi-lab2-api Building +#1 [internal] load local bake definitions +#1 reading from stdin 549B 0.1s done +#1 DONE 0.1s + +#2 [internal] load build definition from Dockerfile +#2 transferring dockerfile: 426B 0.0s done +#2 DONE 0.0s + +#3 [internal] load metadata for docker.io/library/python:3.12.8-slim +#3 ... + +#4 [auth] library/python:pull token for registry-1.docker.io +#4 DONE 0.0s + +#3 [internal] load metadata for docker.io/library/python:3.12.8-slim +#3 DONE 1.0s + +#5 [internal] load .dockerignore +#5 transferring context: 196B done +#5 DONE 0.0s + +#6 [1/8] FROM docker.io/library/python:3.12.8-slim@sha256:2199a62885a12290dc9c5be3ca0681d367576ab7bf037da120e564723292a2f0 +#6 resolve docker.io/library/python:3.12.8-slim@sha256:2199a62885a12290dc9c5be3ca0681d367576ab7bf037da120e564723292a2f0 0.0s done +#6 DONE 0.0s + +#7 [internal] load build context +#7 transferring context: 3.70kB 0.0s done +#7 DONE 0.0s + +#8 [2/8] WORKDIR /app +#8 CACHED + +#9 [5/8] COPY app ./app +#9 CACHED + +#10 [6/8] COPY migrations ./migrations +#10 CACHED + +#11 [7/8] COPY scripts ./scripts +#11 CACHED + +#12 [4/8] RUN pip install --no-cache-dir -r requirements-app.txt +#12 CACHED + +#13 [3/8] COPY requirements-app.txt ./ +#13 CACHED + +#14 [8/8] RUN useradd --create-home --uid 10001 appuser +#14 CACHED + +#15 exporting to image +#15 exporting layers done +#15 exporting manifest sha256:9cf6afdb1a8794e290a56671c9efc636477b8be3f83fa4b6774ea411e5b45272 done +#15 exporting config sha256:095cc9895237f2b980d61820984491b10ee450d6ac5b9f7e2679edb1c3ab6b0d done +#15 exporting attestation manifest sha256:8c7e440b0feb1664a307d72756e5455e15eb595b853566d9d4bfe1915fcceeac 0.0s done +#15 exporting manifest list sha256:5a248ac1dbf37d83b7f374038bf4bde0aee37722a351863a5504483291076c29 0.0s done +#15 naming to docker.io/library/mtusi-lab2-api:latest done +#15 unpacking to docker.io/library/mtusi-lab2-api:latest done +#15 DONE 0.1s + +#16 resolving provenance for metadata file +#16 DONE 0.0s + Image mtusi-lab2-api Built + Network mtusi-lab2_default Creating + Network mtusi-lab2_default Creating + Network mtusi-lab2_default Created + Network mtusi-lab2_default Created + Container mtusi-lab2-redis-1 Creating + Container mtusi-lab2-postgres-1 Creating + Container mtusi-lab2-redis-1 Created + Container mtusi-lab2-postgres-1 Created + Container mtusi-lab2-api-1 Creating + Container mtusi-lab2-api-1 Created + Container mtusi-lab2-postgres-1 Starting + Container mtusi-lab2-redis-1 Starting + Container mtusi-lab2-postgres-1 Started + Container mtusi-lab2-redis-1 Started + Container mtusi-lab2-postgres-1 Waiting + Container mtusi-lab2-redis-1 Waiting + Container mtusi-lab2-redis-1 Healthy + Container mtusi-lab2-postgres-1 Healthy + Container mtusi-lab2-api-1 Starting + Container mtusi-lab2-api-1 Started diff --git a/evidence/make-test.txt b/evidence/make-test.txt new file mode 100644 index 0000000..5a5462d --- /dev/null +++ b/evidence/make-test.txt @@ -0,0 +1,5 @@ +$ make test +python3 tests/smoke.py --base-url "http://localhost:8080" +PASS: lab2 public API scenario; infrastructure and grading evidence remain separate. + +exit_code=0