From aa0fd15616328a6caeef9813294ccba3bb22a207 Mon Sep 17 00:00:00 2001 From: eqktrin Date: Fri, 16 Oct 2026 19:39:21 +0300 Subject: [PATCH] =?UTF-8?q?=D0=9B=D0=B0=D0=B1=D0=BE=D1=80=D0=B0=D1=82?= =?UTF-8?q?=D0=BE=D1=80=D0=BD=D0=B0=D1=8F=202:=20PostgreSQL,=20=D1=81?= =?UTF-8?q?=D0=B5=D1=81=D1=81=D0=B8=D0=B8,=20Valkey,=20=D1=82=D1=80=D0=B5?= =?UTF-8?q?=D0=BA=202?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .dockerignore | 20 + .env.example | 16 + .github/pull_request_template.md | 18 + .github/workflows/contracts.yml | 16 + .gitignore | 32 + CONTRIBUTING.md | 19 + COURSE.md | 53 + Dockerfile | 28 + Dockerfile.example | 8 + MAINTAINERS.md | 38 + Makefile | 56 + README.md | 105 ++ REPORT.md | 217 +++ app/__init__.py | 0 app/cache.py | 58 + app/config.py | 46 + app/cursor.py | 26 + app/db.py | 57 + app/errors.py | 21 + app/migrate.py | 62 + app/migrations/0001_core.sql | 47 + app/migrations/0002_sessions.sql | 13 + app/repo.py | 105 ++ app/security.py | 77 + app/sessions.py | 86 ++ app/validation.py | 84 + compose.example.yaml | 10 + compose.yaml | 103 ++ contracts/README.md | 61 + contracts/examples.json | 58 + contracts/infrastructure.json | 31 + contracts/openapi.json | 2026 +++++++++++++++++++++++++ evidence/README.md | 5 + evidence/cache-role.txt | 9 + evidence/dependency-failure.txt | 11 + evidence/explain-history.txt | 85 ++ evidence/migrations-my.txt | Bin 0 -> 928 bytes evidence/migrations.txt | 22 + evidence/persistence-my.txt | 15 + evidence/persistence-restart.txt | 14 + evidence/test-results.txt | 47 + evidence/tests-deps-my.txt | Bin 0 -> 176 bytes evidence/tests-my.txt | Bin 0 -> 812 bytes evidence/track2-indexes-my.json | 502 ++++++ evidence/track2-indexes-pass2-my.json | 508 +++++++ evidence/track2-indexes-pass2.json | 505 ++++++ evidence/track2-indexes.json | 504 ++++++ evidence/track2-restore-my.txt | Bin 0 -> 1183 bytes evidence/track2-restore.json | 61 + evidence/track2-restored-app.txt | 8 + evidence/track2-summary.md | 23 + examples/requests.http | 45 + infra/README.md | 7 + lab.json | 8 + main.py | 259 ++++ requirements-dev.txt | 5 + requirements.in | 6 + requirements.txt | 26 + scripts/backup.sh | 9 + scripts/check_contract.py | 54 + scripts/evidence-restart.sh | 9 + scripts/explain_history.py | 76 + scripts/init-secrets.sh | 17 + scripts/restart.example.sh | 10 + scripts/restart.sh | 14 + scripts/restore-check.sh | 21 + scripts/test-expiry.sh | 9 + scripts/track2_indexes.py | 186 +++ scripts/track2_restore.py | 142 ++ scripts/validate_openapi.py | 23 + tests/README.md | 57 + tests/client.py | 217 +++ tests/load.py | 58 + tests/resilience.py | 129 ++ tests/smoke.py | 82 + tests/test_own.py | 162 ++ tests/test_race.py | 36 + tests_student/common.py | 24 + tests_student/test_db_rollback.py | 47 + tests_student/test_dependencies.py | 109 ++ tests_student/test_expiry.py | 36 + tests_student/test_integration.py | 197 +++ 82 files changed, 7996 insertions(+) create mode 100644 .dockerignore create mode 100644 .env.example create mode 100644 .github/pull_request_template.md create mode 100644 .github/workflows/contracts.yml create mode 100644 .gitignore create mode 100644 CONTRIBUTING.md create mode 100644 COURSE.md create mode 100644 Dockerfile create mode 100644 Dockerfile.example create mode 100644 MAINTAINERS.md create mode 100644 Makefile create mode 100644 README.md create mode 100644 REPORT.md create mode 100644 app/__init__.py create mode 100644 app/cache.py create mode 100644 app/config.py create mode 100644 app/cursor.py create mode 100644 app/db.py create mode 100644 app/errors.py create mode 100644 app/migrate.py create mode 100644 app/migrations/0001_core.sql create mode 100644 app/migrations/0002_sessions.sql create mode 100644 app/repo.py create mode 100644 app/security.py create mode 100644 app/sessions.py create mode 100644 app/validation.py create mode 100644 compose.example.yaml create mode 100644 compose.yaml create mode 100644 contracts/README.md create mode 100644 contracts/examples.json create mode 100644 contracts/infrastructure.json create mode 100644 contracts/openapi.json create mode 100644 evidence/README.md create mode 100644 evidence/cache-role.txt create mode 100644 evidence/dependency-failure.txt create mode 100644 evidence/explain-history.txt create mode 100644 evidence/migrations-my.txt create mode 100644 evidence/migrations.txt create mode 100644 evidence/persistence-my.txt create mode 100644 evidence/persistence-restart.txt create mode 100644 evidence/test-results.txt create mode 100644 evidence/tests-deps-my.txt create mode 100644 evidence/tests-my.txt create mode 100644 evidence/track2-indexes-my.json create mode 100644 evidence/track2-indexes-pass2-my.json create mode 100644 evidence/track2-indexes-pass2.json create mode 100644 evidence/track2-indexes.json create mode 100644 evidence/track2-restore-my.txt create mode 100644 evidence/track2-restore.json create mode 100644 evidence/track2-restored-app.txt create mode 100644 evidence/track2-summary.md create mode 100644 examples/requests.http create mode 100644 infra/README.md create mode 100644 lab.json create mode 100644 main.py create mode 100644 requirements-dev.txt create mode 100644 requirements.in create mode 100644 requirements.txt create mode 100644 scripts/backup.sh create mode 100644 scripts/check_contract.py create mode 100644 scripts/evidence-restart.sh create mode 100644 scripts/explain_history.py create mode 100644 scripts/init-secrets.sh create mode 100644 scripts/restart.example.sh create mode 100644 scripts/restart.sh create mode 100644 scripts/restore-check.sh create mode 100644 scripts/test-expiry.sh create mode 100644 scripts/track2_indexes.py create mode 100644 scripts/track2_restore.py create mode 100644 scripts/validate_openapi.py create mode 100644 tests/README.md create mode 100644 tests/client.py create mode 100644 tests/load.py create mode 100644 tests/resilience.py create mode 100644 tests/smoke.py create mode 100644 tests/test_own.py create mode 100644 tests/test_race.py create mode 100644 tests_student/common.py create mode 100644 tests_student/test_db_rollback.py create mode 100644 tests_student/test_dependencies.py create mode 100644 tests_student/test_expiry.py create mode 100644 tests_student/test_integration.py diff --git a/.dockerignore b/.dockerignore new file mode 100644 index 0000000..bc16e55 --- /dev/null +++ b/.dockerignore @@ -0,0 +1,20 @@ +.git +.github +.env +.env.* +!.env.example +secrets +certs +volumes +data +backups +*.key +*.pem +*.p12 +*.pfx +*.jks +.venv +__pycache__ +node_modules +evidence +.DS_Store diff --git a/.env.example b/.env.example new file mode 100644 index 0000000..5672702 --- /dev/null +++ b/.env.example @@ -0,0 +1,16 @@ +# Copy to .env for your LOCAL synthetic test environment; never commit .env. +# These are logical interface suggestions; map actual framework names in REPORT.md. +APP_HOST=0.0.0.0 +APP_PORT=8080 +APP_ENV=lab +SESSION_TTL_SECONDS=3600 +# Choose credentials locally. File paths contain no secret values. +DATABASE_URL_FILE=/run/secrets/database_url +# Optional on 3, required use on 4 in lab2; Redis OR Valkey: +# postgres = сессии только в PostgreSQL; postgres+cache = PostgreSQL (источник истины) + Valkey как read-through кэш. +SESSION_STORE=postgres+cache +SESSION_CACHE_TTL_SECONDS=60 +CACHE_URL_FILE=/run/secrets/cache_url +# Пулы/таймауты (необязательно, значения по умолчанию в app/config.py): +# DB_POOL_MAX=10 DB_POOL_TIMEOUT=3 DB_STATEMENT_TIMEOUT_MS=5000 CACHE_TIMEOUT=0.25 +# WEB_CONCURRENCY=2 THREAD_LIMIT=24 HASH_CONCURRENCY=4 diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 0000000..8ceefa1 --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,18 @@ +## Лабораторная 2 + +Автор / группа: TODO +Целевая оценка (3/4/5): TODO +Трек 5, если заявлен: TODO + +Что реализовано и что перенесено: TODO +Команды запуска из чистого clone: TODO +Результаты проверок и ссылка на REPORT.md: TODO +Ограничения / известные ошибки: TODO +Источники и использование ИИ: TODO + +- [ ] Весь обязательный минимум текущей и предыдущих работ сохранён с объявленными переходами. +- [ ] Контракт и публичные тесты не ослаблены. +- [ ] make check и make test выполнены; приложен реальный вывод. +- [ ] Сценарии отказов/безопасности своего уровня воспроизведены. +- [ ] Все секреты и приватные ключи находятся вне Git; отчёт не содержит tokens. +- [ ] README задания сохранён, REPORT.md содержит инструкцию именно моего решения. diff --git a/.github/workflows/contracts.yml b/.github/workflows/contracts.yml new file mode 100644 index 0000000..11cf289 --- /dev/null +++ b/.github/workflows/contracts.yml @@ -0,0 +1,16 @@ +name: Skeleton contracts +on: [push, pull_request] +permissions: + contents: read +jobs: + contracts: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-python@v5 + with: + python-version: '3.12' + - run: python -m pip install -r requirements-dev.txt + - run: make check validate PYTHON=python +# This job validates the skeleton, not a student solution. +# Add build, readiness and make test in a separate application job. diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..b5a7189 --- /dev/null +++ b/.gitignore @@ -0,0 +1,32 @@ +# Local/private state +.env +.env.* +!.env.example +secrets/ +certs/private/ +*.key +*.p12 +*.pfx +*.jks +*.pem +*.tfstate* +volumes/ +data/ +backups/ +# Runtime/build artifacts +.venv/ +__pycache__/ +*.py[cod] +node_modules/ +dist/ +build/ +target/ +bin/ +obj/ +coverage/ +*.log +.DS_Store +.idea/ +.vscode/ +# Keep small, sanitized evidence summaries in evidence/ under version control. +# Inspect git diff --cached: ignore rules are not a secret scanner. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..ee5533d --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,19 @@ +# Работа через fork и pull request + +1. После публикации преподавателем сделайте fork репозитория **текущей** лабораторной в своём аккаунте и clone своего fork. URL преподаватель выдаёт отдельно. +2. Создайте ветку `solution/-` от исходной ветки skeleton. Ветка преподавателя и файлы контракта остаются основой проверки. +3. Для lab2–7 перенесите из своей предыдущей лабы только исходники, миграции, собственные тесты, Dockerfile и нужные конфигурации. Не копируйте `.git`, `.env`, credentials, volumes, `README.md`, `COURSE.md`, публичные `tests/` и `contracts/` поверх новой версии. Сначала сравните изменения API в `COURSE.md`. +4. Реализуйте задание, добавьте свою инструкцию запуска и заполните `REPORT.md`. Публичные проверки дополняйте отдельными тестами, не ослабляйте assertions. +5. Выполните `make check`, запустите свой стенд, затем `make test`. Выполните сценарии отказов текущей лабы. Их запуск всегда явный: scaffold сам не останавливает контейнеры. +6. Commit и push делайте в свой fork. Откройте PR в исходный репозиторий преподавателя, заголовок: `ЛР N — Группа — Фамилия — на 3/4/5`. Выберите правильную базовую ветку и заполните шаблон. +7. После замечаний обновляйте тот же PR. Чужие решения не переносите без указания источника и согласованных правил курса. + +Платформа может называть PR «merge request» — процесс тот же. `.github/` содержит необязательные удобства для GitHub; проверки локально от платформы не зависят. Инициализация и публикация исходных Git-репозиториев выполняются преподавателем отдельно. + +## Правила изменения skeleton + +Не удаляйте обязательные endpoint, поля, рубрику и публичные проверки. Изменение контракта согласуйте отдельным комментарием/PR; обход тестов не является решением. Код приложения размещайте в `src/` либо в принятой для языка структуре. Собственные тесты — `student-tests/` или штатный каталог фреймворка. Ссылки на результаты проверки и команды запуска должны переживать clone на другой машине. + +## CI + +Готовый GitHub workflow проверяет целостность контракта и синтаксис Python-проверок. Он **не запускает отсутствующее приложение** и **не подтверждает оценку**. Студент добавляет сборку своего приложения, запуск/готовность стенда и `make test` в отдельный job. Не используйте `pull_request_target` для запуска кода из fork, не выдавайте CI секреты или доступ к общему Docker-host. diff --git a/COURSE.md b/COURSE.md new file mode 100644 index 0000000..b02172b --- /dev/null +++ b/COURSE.md @@ -0,0 +1,53 @@ +# Сквозной проект: мессенджер под нагрузкой + +Семь самостоятельных репозиториев содержат задания и проверяемые контракты одной системы. Вы переносите собственную реализацию между лабораторными. Язык, фреймворк и библиотеки выбираете сами. Web UI, WebSocket, редактирование/удаление сообщений, публичный поиск пользователей и Kubernetes не входят в обязательный минимум: достаточно REST API. + +| Лаба | Новая инженерная задача | Что появляется в системе | +| --- | --- | --- | +| 1 | Контракт, процессы и контейнер | In-memory API, Dockerfile, HTTP smoke | +| 2 | Сохранность и идентификация | PostgreSQL, Basic → сессия; Redis/Valkey на 4 | +| 3 | Горизонтальное масштабирование | Балансировщик, ≥2 API-реплики, общие сессии, идемпотентность | +| 4 | Бинарные данные | Приватное S3-совместимое хранилище и вложения | +| 5 | Фоновая работа | Брокер, worker, состояния вложений и преобразование изображений | +| 6 | Диагностика | OTel Collector, хранилища сигналов, Grafana | +| 7 | Защита и эксплуатация | Argon2id, TLS/mTLS, OpenBao, минимальные привилегии | + +## Как оценивать + +Оценки накопительные **внутри лабораторной**: 4 = весь уровень 3 + весь уровень 4; 5 = весь уровень 4 + **один** полностью выполненный трек 5 на выбор. Несколько недоделанных треков не заменяют один завершённый. Условие «весь уровень» включает реализацию, проверку и объяснение на защите. Красивые схемы и дополнительные технологии не компенсируют неработающий обязательный сценарий. + +Для начала следующей лабы достаточно обязательного минимума предыдущей. Сохраняются предыдущие обязательные возможности, с явно описанными переходами API ниже. Не требуется сначала получить 5 за все ранние лабы. Можно исправлять свою базу по ходу курса; такие исправления выделяйте в PR. Реализация на 3 работоспособна, но не претендует на промышленную готовность. Даже 5 в lab7 — учебная доказанная защита в заявленной модели угроз, а не сертификат полной безопасности. + +На 3 студент самостоятельно собирает рабочую систему. На 4 показывает практики, ожидаемые от стажёра/джуна в команде: воспроизводимость, диагностику, обработку ошибок и проверки отказов. На 5 формулирует гипотезу, ставит эксперимент, приводит измерения и обсуждает границы решения — это предмет конкретной похвалы магистранту. + +## Контракт и совместимость + +`contracts/openapi.json` — OpenAPI 3.1.0, `contracts/README.md` — нормативная семантика. Контракт каждого репозитория самодостаточен; соседние папки на машине преподавателя не нужны. `tests/` — публичные проверки, а не эталонное решение. Контракт, рубрика и публичные тесты имеют приоритет над случайным поведением библиотек. При противоречии создайте вопрос преподавателю; не подгоняйте тест под приложение. + +Три объявленных изменения обязательного API: + +1. **1 → 2:** регистрация требует `password`; `X-User-Id` заменяется Bearer. Basic используется только при создании сессии. +2. **2 → 3:** `Idempotency-Key` обязателен для отправки сообщения; ответы API содержат `X-Instance-Id`. +3. **4 → 5:** загрузка вложения возвращает `202` вместо `201`, состояние становится асинхронным. Клиент опрашивает метаданные. Старое текстовое сообщение остаётся валидным: `attachment_ids` по умолчанию `[]`. + +У lab7 меняется транспорт на HTTPS, бизнес-эндпоинты остаются прежними. Внутреннее mTLS не заменяет пользовательскую сессию. Новые возможности на 4/5 добавляйте обратно совместимо, в отдельном `contracts/extensions.openapi.json` или документе; обязательный контракт сохраняйте. + +## Общая предметная модель + +Пользователь (`username`, `display_name`) состоит в чатах. Список участников задаётся при создании чата и в обязательном API не изменяется. В чате отправляются сообщения, с lab4 — со ссылками на вложения этого чата. Сервер назначает UUID и время. Порядок истории — `(created_at, id)` по возрастанию. Для защиты достаточно показать взаимодействие нескольких API-клиентов; фронтенд не требуется. + +С lab2 данные PostgreSQL — источник истины. Сессии могут храниться в PostgreSQL или Redis/Valkey, если выполняют контракт срока жизни и перезапуска. Файлы с lab4 живут в S3, метаданные — в PostgreSQL. Redis и Valkey — альтернативы: оба одновременно не нужны. Аналогично выбирается одно S3-хранилище, один брокер и один основной путь оркестрации. + +## Воспроизводимость и честные измерения + +- Укажите версии runtime и контейнерных образов, аппаратную конфигурацию, CPU/RAM-лимиты, команду запуска и время прогрева. Для образов используйте явный тег версии или digest, не `latest`. +- Все тестовые пользователи и изображения синтетические. `make test` создаёт данные: запускайте его на учебном стенде. Не публикуйте пароли, токены, приватные ключи, персональные данные или подписанные URL. +- Минимальный отчёт о нагрузке: длительность, конкуренция/интенсивность, успешные RPS, доля ошибок, p50/p95/p99, CPU/RAM, размер набора данных. Универсального проходного RPS для разных ноутбуков нет. +- Сравнивайте одинаковые запросы при одинаковых ресурсах. Успешный `/health/live` не доказывает сохранность сообщений, а HTTP `202` — окончание обработки. +- Один Docker-host не обеспечивает отказоустойчивость к потере этого host. Несколько API-процессов не делают единственную БД или LB высокодоступными. Отдельно называйте, какие отказы выдерживает эксперимент. + +## Что сдавать + +Исходники, Dockerfile, нужные манифесты и конфигурации, миграции, собственные тесты, заполненный `REPORT.md`, сведения об использовании внешнего кода и ИИ. Уметь объяснить и изменить своё решение на защите обязательно. Приложите команды и текстовые результаты; скриншоты — дополнение, а не единственное доказательство. + +PR должен собираться из чистого clone по инструкции автора. Секреты создаются отдельно; тестовые fixtures и открытые конфигурации хранятся в репозитории. Перенос кода между лабами описан в [CONTRIBUTING.md](CONTRIBUTING.md). diff --git a/Dockerfile b/Dockerfile new file mode 100644 index 0000000..3484a5d --- /dev/null +++ b/Dockerfile @@ -0,0 +1,28 @@ +# syntax=docker/dockerfile:1 +# Базовый образ тот же, что в lab1 (python:3.11.9-slim) — тег уже собирался и существует. +FROM python:3.11.9-slim + +ENV PYTHONDONTWRITEBYTECODE=1 PYTHONUNBUFFERED=1 PIP_NO_CACHE_DIR=1 PIP_DISABLE_PIP_VERSION_CHECK=1 \ + WEB_CONCURRENCY=2 +WORKDIR /app + +# 1) зависимости по lockfile отдельным слоем — кэш Docker не инвалидируется правкой исходников +COPY requirements.txt . +RUN pip install -r requirements.txt + +# 2) исходники (секреты и .env исключены .dockerignore) +COPY main.py . +COPY app ./app + +# 3) не root (UID фиксирован, чтобы права на secrets-файлы были предсказуемы) +RUN useradd --system --uid 10001 --no-create-home --shell /usr/sbin/nologin appuser +USER 10001 + +EXPOSE 8080 + +HEALTHCHECK --interval=5s --timeout=3s --start-period=10s --retries=10 \ + CMD ["python", "-c", "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8080/health/live', timeout=2)"] + +# exec-форма: uvicorn = PID 1, получает SIGTERM и за 5 с дообслуживает запросы (как в lab1). +# Число процессов берётся из WEB_CONCURRENCY (uvicorn читает её сам). +CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8080", "--timeout-graceful-shutdown", "5"] diff --git a/Dockerfile.example b/Dockerfile.example new file mode 100644 index 0000000..e333a12 --- /dev/null +++ b/Dockerfile.example @@ -0,0 +1,8 @@ +# Teaching outline, not a runnable Dockerfile. Implement your own Dockerfile. +# 1. Choose a runtime/toolchain version and pin the base image tag/digest. +# 2. Copy dependency manifests first; install from the language lockfile. +# 3. Copy source and build. For compiled languages use a separate runtime stage. +# 4. Run the HTTP process as PID 1; listen on 0.0.0.0:8080. +# 5. Add non-root, signals and healthcheck according to the current rubric. +# 6. Pass runtime config/secrets at startup, never COPY .env or secret files. +# This file deliberately has no FROM/CMD: selecting/implementing them is the task. diff --git a/MAINTAINERS.md b/MAINTAINERS.md new file mode 100644 index 0000000..7b7c352 --- /dev/null +++ b/MAINTAINERS.md @@ -0,0 +1,38 @@ +# Памятка преподавателю — лабораторная 2 + +## Что подготовлено + +Язык реализации не задан. README содержит накопительные уровни 3/4/5, сценарий защиты и вопросы. В каждой лабе собственная полная версия OpenAPI, поэтому fork не зависит от соседних каталогов. Публичный HTTP smoke не содержит реализации сервера; Dockerfile.example и compose.example.yaml (если есть) — задания/ориентиры, не готовый deployment. + +## Перед публикацией + +1. Выберите GitHub/GitLab и организацию, опубликуйте каждый каталог как отдельный template/skeleton repository, сообщите студентам URL и правила именования PR/MR. Эти материалы не публикуют репозитории автоматически. +2. Задайте default branch, защиту исходных материалов и правила приёма. `.github/` уже содержит шаблон PR и CI контракта; в GitLab перенесите эквивалентные настройки, локальные Makefile-команды одинаковы. +3. Сообщите, индивидуальная работа или командная, сроки, правила использования стороннего кода/ИИ и ресурсы демонстрационного стенда. Эти организационные решения намеренно не выдуманы в задании. +4. Уточните ограничения площадки (например доступна ли виртуализация/несколько узлов). Для 5 предусмотрено по два трека: один можно выполнить без настоящего multi-node cloud. Универсальный проходной RPS не установлен. + +## Что проверять + +| Проверка | Что подтверждает | Чего не подтверждает | +| --- | --- | --- | +| make check | Структура файлов, JSON, локальные refs, синтаксис Python | Реализация/запуск API | +| make validate | Полная OpenAPI 3.1, JSON Schema и примеры | Поведение сервера | +| make test | Один сквозной контрактный сценарий текущей лабы | Все ошибки, persistence, HA, security | +| test-persistence (lab2+) | Данные/прежний токен после вызова restart hook | Реальный перезапуск, если hook — no-op | +| test-failover (lab3+) | Смена обслуживающей реплики, сохранность, retry без дубля | Несколько физических узлов, HA DB/LB | +| test-security (lab7) | Доверенный HTTPS и отказ недоверенного CA | Внутреннее mTLS/identity/ACL/OpenBao | +| Защита и тесты студента | Реальность инфраструктуры и критерии выбранного уровня | Неограниченная промышленная безопасность | + +Проверяйте реальные контейнеры/логи процессов и данные до/после отказа: одного X-Instance-Id недостаточно. Для 4 требуются все пункты 3+4, для 5 — все пункты 3+4 и один **завершённый** трек 5. Сравнивайте подтверждённые результаты со сформулированными критериями, а не количество установленных сервисов. + +## Приём PR + +Проверка запускается на изолированном учебном окружении с синтетическими secrets, не на общей production БД. Студенческие Dockerfile/hooks/CI — выполняемый код: обычный fork workflow без секретов и без доступа к общему Docker socket. Не запускайте PR через pull_request_target с привилегиями преподавателя. + +Исходные README/контракт/публичные tests сохраняются, реализация переносится студентом между лабами через собственные исходники и миграции. Исправление общей спецификации публикуйте отдельным изменением, объясняя влияние на все затронутые лабораторные. + +## Проверка этой версии skeleton + +На 2026-09-10 выполнены структурные проверки и полная валидация всех семи OpenAPI/JSON Schema, проверка локальных Markdown-ссылок/YAML и декодирование PNG fixture. HTTP-клиенты проверены на временном изолированном тестовом стенде: позитивный smoke 1–7, отрицательные варианты неправильного sender, pagination, ACL, logout, bytes и пустого API; также пути persistence/failover/load и внешнего TLS. + +Временный стенд не включён в студенческие каталоги и не является эталонным решением. Реальное приложение, Compose, PostgreSQL/S3/broker и mTLS/OpenBao в skeleton отсутствуют: их работоспособность не заявляется. Docker CLI в среде подготовки не был доступен. Это проверка материалов и тестовых драйверов, не приёмка будущих решений студентов. diff --git a/Makefile b/Makefile new file mode 100644 index 0000000..167fbe8 --- /dev/null +++ b/Makefile @@ -0,0 +1,56 @@ +PYTHON ?= python3 +BASE_URL ?= http://localhost:8080 +CA_FILE ?= +ACTION_SCRIPT ?= +TLS_ARGS = $(if $(CA_FILE),--ca-file "$(CA_FILE)",) + +.PHONY: help check validate test load test-persistence up down test-student test-rollback test-expiry test-deps explain track2-indexes track2-restore + +help: + @echo "check: offline structure; validate: full OpenAPI (requirements-dev.txt); test: running API; load: synthetic writes" + +check: + $(PYTHON) scripts/check_contract.py + +validate: + $(PYTHON) scripts/validate_openapi.py + +test: + $(PYTHON) tests/smoke.py --base-url "$(BASE_URL)" $(TLS_ARGS) + +load: + $(PYTHON) tests/load.py --base-url "$(BASE_URL)" $(TLS_ARGS) + +test-persistence: + @test -n "$(ACTION_SCRIPT)" || (echo "Set ACTION_SCRIPT to your implemented executable restart hook"; exit 2) + $(PYTHON) tests/resilience.py --mode persistence --action-script "$(ACTION_SCRIPT)" --base-url "$(BASE_URL)" $(TLS_ARGS) + +# ---- Цели студента (публичные цели выше не менялись) ---- +up: + sh scripts/init-secrets.sh + docker compose --env-file .env up -d --build + +# Намеренно БЕЗ -v: тома (данные) сохраняются. Удаление данных: docker compose --env-file .env down -v +down: + docker compose --env-file .env down + +test-student: + cd tests_student && $(PYTHON) test_integration.py + +test-rollback: + docker compose --env-file .env run --rm --no-deps -v "$(CURDIR)/tests_student:/srv/tests_student:ro" api python tests_student/test_db_rollback.py + +test-expiry: + sh scripts/test-expiry.sh + +test-deps: + cd tests_student && $(PYTHON) test_dependencies.py + +# Трек 5.2: нужна ОТДЕЛЬНАЯ БД эксперимента (DATABASE_URL_FILE) и второй сервер PostgreSQL для восстановления. +track2-indexes: + $(PYTHON) scripts/track2_indexes.py --out evidence/track2-indexes.json + $(PYTHON) scripts/track2_indexes.py --reverse --out evidence/track2-indexes-pass2.json + +track2-restore: + @test -n "$(SRC_URL)" -a -n "$(DST_ADMIN_URL)" || (echo "Set SRC_URL and DST_ADMIN_URL"; exit 2) + $(PYTHON) scripts/track2_restore.py --src-url "$(SRC_URL)" --dst-admin-url "$(DST_ADMIN_URL)" --out evidence/track2-restore.json diff --git a/README.md b/README.md new file mode 100644 index 0000000..0e073ff --- /dev/null +++ b/README.md @@ -0,0 +1,105 @@ +# Лабораторная 2. PostgreSQL, сессии и Redis/Valkey + +Перенести состояние в постоянное хранилище и связать запросы с аутентифицированным пользователем. Подтверждённые сообщения и действующие сессии переживают перезапуск. + +Это **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) + +## Откуда начинаем + +Перенесите собственный минимум lab1. Изменения API: password при регистрации, Basic для создания сессии, Bearer вместо X-User-Id для бизнес-запросов. + +**Архитектура:** Клиент → API → PostgreSQL; на 4 появляется Redis ИЛИ Valkey для сессий/кэша. + +## Что сделать + +1. Опишите таблицы, ограничения, индексы и транзакционные границы до написания запросов. Добавьте версионируемые миграции. +2. Перенесите пользователей, чаты, членство и сообщения в PostgreSQL. Не используйте SQLite как замену PostgreSQL в принимаемом стенде. +3. Реализуйте регистрацию с password KDF, вход через Basic, opaque Bearer-сессию, expiry и logout. Действующие сессии тоже должны сохраняться. +4. Подготовьте единый локальный запуск API и БД (Compose рекомендуется уже здесь), подключите именованные volumes. +5. Пройдите smoke и тест полного перезапуска. На 4 добавьте Redis/Valkey с конкретной ролью и повторите эксперимент отказа. + +## Оценка «3»: работающий минимум + +- Минимум 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 проходят. Миграции повторно запускаются без дублирования данных. Secrets/volumes не попадают в Git. + +## Оценка «4»: уровень стажёра/джуна + +Весь уровень 3 **и все** пункты ниже: + +- Redis ИЛИ Valkey реально используется для сессий с TTL либо осмысленного кэша. Опишите источник истины, политику expiry и инвалидации. Если это единственное хранилище сессий, включите persistence, выдерживающее проверяемый рестарт; один TTL не сохраняет данные. +- Используются параметризованные запросы/безопасный ORM, ограниченный connection pool и таймауты. Проверены гонка регистрации одинакового username и rollback составной операции. +- Индекс истории обоснован запросом и EXPLAIN (ANALYZE, BUFFERS) на ≥10 000 сообщениях; пагинация не использует полный scan всей истории на каждую страницу. +- Есть автоматическая проверка expiry при коротком SESSION_TTL_SECONDS, logout, неверного пароля и недоступности Redis/БД. При потере сервиса приложение возвращает ограниченную ошибку/корректно обходит кэш, не принимает запрос от анонимного пользователя как доверенный. + +## Оценка «5»: исследование и доказанный результат + +Весь уровень 4 **и один законченный трек на выбор**. Приведите гипотезу, повторяемую методику, результаты и ограничения. + +**Трек 1. Согласованность кэша.** Покажите на конкурентном сценарии stale read или cache stampede, реализуйте защиту и измерьте число SQL-запросов/latency до и после. Докажите read-after-write из контракта и восстановление после рестарта кэша; одной установки Redis недостаточно. + +**Трек 2. План запроса и восстановление.** Исследуйте ≥100 000 сообщений с неравномерными размерами чатов, сравните ≥2 индекса/запроса и стоимость записи. Сделайте backup → восстановление в новое хранилище → сверку количества и выбранных сообщений. Обсудите время восстановления и границы потери данных. + +## Как начать и проверить + +```sh +# Работает прямо в skeleton, Python 3.9+; приложение не запускается: +make check + +# После реализации запустите свой сервер/стенд по REPORT.md. +# По умолчанию тест использует http://localhost:8080. +make test +``` + +`.env.example`, `compose.example.yaml` и `contracts/infrastructure.json` описывают настройки и роли компонентов. **compose.example.yaml — список ролей с пустым services, не запускаемый стенд.** Реализуйте свой `compose.yaml`/`stack.yaml`, закрепите версии образов, заполните локальный `.env` и опишите bootstrap/миграции. Все зависимости поднимаются из этого репозитория; ссылка «у меня БД уже установлена» не заменяет воспроизводимость. + +```sh +# Compose-вариант после реализации: +docker compose --env-file .env config --quiet +docker compose --env-file .env up -d --build +# Дождитесь /health/ready; затем make test. +# Для Swarm укажите эквивалентные build/push/deploy-команды в REPORT.md. +``` + + +Примеры запросов доступны в `examples/requests.http`, примеры JSON — в `contracts/examples.json`. Для полной проверки схемы (по желанию локально; CI делает её автоматически): + +```sh +python3 -m venv .venv +.venv/bin/python -m pip install -r requirements-dev.txt +make validate PYTHON=.venv/bin/python +``` + +Smoke не выставляет оценку автоматически. Проверку сохранности/отказов запускайте явно по [tests/README.md](tests/README.md), остальные доказательства приведите в отчёте. + +## Сценарий защиты + +1. Применить миграции к пустому volume, создать пользователей, войти, отправить сообщение. +2. Запустить persistence-сценарий: он держит токен только в памяти тестового процесса; action script перезапускает API и все используемые хранилища, сохраняя volumes. +3. После готовности тот же токен читает те же данные; после logout — 401. Повторить с отдельным коротким TTL для проверки expiry. +4. Для 4: показать роль Redis/Valkey, план SQL и ошибку зависимости. Для 5: выполнить выбранный эксперимент. + +## Что должно быть в PR + +Исходники, Dockerfile, миграции, compose.yaml либо эквивалентный воспроизводимый запуск, scripts/restart.sh, собственные тесты и отчёт. + +Заполните `REPORT.md` и [шаблон PR](.github/pull_request_template.md), укажите целевую оценку/трек. Не меняйте обязательный контракт и публичные tests ради зелёного результата. Сохраняйте возможности предыдущих лабораторных в пределах [объявленных переходов](COURSE.md). + +## Вопросы на защите + +- Что подтверждает COMMIT и какие гарантии зависят от настройки durability? +- Где хранятся сессии и что будет после flush/restart Redis? +- Чем аутентификация отличается от доступа к конкретному чату? +- Почему hash пароля и быстрый checksum имеют разные задачи? + +## Первичные материалы + +- [PostgreSQL transactions](https://www.postgresql.org/docs/current/tutorial-transactions.html) +- [PostgreSQL EXPLAIN](https://www.postgresql.org/docs/current/using-explain.html) +- [Valkey persistence](https://valkey.io/topics/persistence/) +- [Redis persistence](https://redis.io/docs/latest/operate/oss_and_stack/management/persistence/) +- [Basic authentication](https://www.rfc-editor.org/info/rfc7617/) diff --git a/REPORT.md b/REPORT.md new file mode 100644 index 0000000..b0f64c0 --- /dev/null +++ b/REPORT.md @@ -0,0 +1,217 @@ +# Отчёт — лабораторная 2 + +- Автор, группа: Никифорова Екатерина, БВТ2301 +- Целевая оценка: **5**, выбранный трек 5: **Трек 2 «План запроса и восстановление»** (уровни 3 и 4 тоже выполнены) +- Commit/PR: ЗАПОЛНИТЬ после публикации +- Источники, библиотеки и помощь ИИ: FastAPI 0.115 + Uvicorn 0.30 (как в lab1), psycopg 3.2 + psycopg_pool, argon2-cffi, redis-py; документация PostgreSQL (transactions, EXPLAIN), Valkey persistence, RFC 7617. + +## Запуск из чистого clone + +Требования: Docker Engine ≥ 24 с Compose v2, Python ≥ 3.9 (для тестов), `sh` (Git Bash на Windows). + +```sh +sh scripts/init-secrets.sh # случайные пароли -> secrets/*, копия .env.example -> .env (всё в .gitignore) +docker compose --env-file .env config --quiet # проверка конфигурации +docker compose --env-file .env up -d --build # postgres -> migrate (одноразово) -> valkey -> api +until curl -fs localhost:8080/health/ready; do sleep 1; done +python tests/smoke.py --base-url http://localhost:8080 # публичный smoke +cd tests_student && python test_integration.py && python test_dependencies.py && cd .. # расширенные тесты API (11 + зависимости) +python scripts/track2_indexes.py --out evidence/track2-indexes.json # трек 2: замеры индексов +python scripts/track2_restore.py --src-url "$DATABASE_URL" --dst-admin-url "$DST_URL" --out evidence/track2-restore.json +``` + +Оператору больше ничего делать не нужно. Миграции применяет сервис `migrate` (идемпотентно, под advisory-lock). +Безопасная остановка: `docker compose --env-file .env stop` (данные и тома целы). Намеренное удаление учебных данных: +`docker compose --env-file .env down -v && rm -rf secrets` — **только это стирает тома**; в `restart.sh` и тестах `-v` не используется. + +## Архитектура и решения + +``` +Клиент ──HTTP──> api (FastAPI, Uvicorn) ──> PostgreSQL 17 (источник истины, том pgdata) + └──────────────> Valkey 8 (кэш сессий, AOF, том valkeydata) +migrate (одноразово) ──> PostgreSQL +``` + +| Роль | Service | Образ (зафиксирован) | Health | Том | Сеть/порт | Credentials | +| --- | --- | --- | --- | --- | --- | --- | +| api | `api` | сборка из `Dockerfile`, база `python:3.11.9-slim` (как в lab1), зависимости из `requirements.txt` | `/health/ready` (API + PostgreSQL) | нет (stateless, read-only rootfs) | `127.0.0.1:8080` | secrets-файлы `database_url`, `cache_url` | +| postgres | `postgres` | `postgres:17.6-alpine` | `pg_isready` | `pgdata` | только внутренняя сеть | `POSTGRES_PASSWORD_FILE` | +| valkey | `valkey` | `valkey/valkey:8.1.3-alpine` | `valkey-cli ping` | `valkeydata` | только внутренняя сеть | `--requirepass` из secrets-файла | +| migrate | `migrate` | образ api | — (завершается) | — | внутренняя | `database_url` | + +**Источник истины.** Пользователи, чаты, участники, сообщения и сессии — в PostgreSQL. Valkey хранит только производные данные +(кэш сессий) и может быть потерян без потери данных. + +**Схема (`app/migrations/`).** `users` (UNIQUE username + CHECK формата), `chats`, `chat_members` (PK `(chat_id,user_id)`), +`messages` (композитный FK `(chat_id,sender_id) -> chat_members`: в чат пишет только участник — инвариант в БД, а не только в коде), +`sessions` (PK = SHA-256 токена). Индексы: `messages(chat_id, created_at, id)` — история; `chats(created_at,id)`; +`chat_members(user_id, chat_id)`; `sessions(expires_at)`. + +**Транзакционные границы.** (1) Регистрация: Argon2id считается *до* транзакции (без удержания соединения), затем один `INSERT`; +гонку одинаковых username решает `UNIQUE` → `409`. (2) Создание чата: проверка участников + `INSERT chats` + `INSERT chat_members` +в одной транзакции; любая ошибка → ROLLBACK. (3) Сообщение: один `INSERT`; COMMIT происходит до ответа `201`. +(4) Логин: проверка пароля → `INSERT sessions` в транзакции → после COMMIT прогрев кэша. + +**Сессии и кэш (уровень 4).** +- *Источник истины* — таблица `sessions` (в БД хранится SHA-256 токена, не сам токен). Токен — `secrets.token_urlsafe(32)` (256 бит). +- *Кэш*: cache-aside `sess:v1:` → `{user, exp}`. Чтение: Valkey → при промахе PostgreSQL → `SET NX PX`. +- *Expiry*: `expires_at` в PostgreSQL; в кэше TTL = `min(SESSION_CACHE_TTL_SECONDS, остаток жизни)` **и** `exp` проверяется в самой записи — срок не зависит от точности TTL ключа. + TTL не продлевается ни обращениями, ни рестартом. +- *Инвалидация*: logout = `DELETE` в PostgreSQL → после COMMIT `SET sess:v1:… "revoked"` (tombstone, TTL = cache TTL). Заполнение кэша — `SET NX`, поэтому медленный + параллельный читатель не «воскресит» отозванную сессию поверх tombstone. Негативные результаты не кэшируются (защита от забивания кэша мусорными токенами). + Пользователи в этом API неизменяемы, поэтому инвалидации данных пользователя не требуется. +- *Persistence Valkey*: AOF `everysec` + том. Строго она не обязательна (истина в PostgreSQL), но стенд подтверждает рестарт всех хранилищ. +- *Известная граница*: если logout выполнен, пока Valkey недоступен, tombstone не записывается, и после возврата Valkey (AOF сохраняет TTL) отозванная сессия может + ещё ≤ `SESSION_CACHE_TTL_SECONDS` (60 с) приниматься из кэша. Это осознанный компромисс; снижается уменьшением TTL кэша. + +**Пул, таймауты, ошибки.** `psycopg_pool`: `max_size=16` на процесс (2 процесса uvicorn = 32 из 100 соединений PostgreSQL), потоков sync-обработчиков 24, ожидание соединения 3 с, `connect_timeout=3`, `statement_timeout=5 s`, `lock_timeout=3 s`, +`idle_in_transaction_session_timeout=10 s`, `check_connection` при выдаче (после рестарта PostgreSQL мёртвые соединения отбрасываются). Valkey: таймаут 0,25 с + +circuit breaker 2 с. Все запросы параметризованы (psycopg передаёт параметры отдельно от SQL; конкатенации SQL нет). Недоступность БД → `503 unavailable` +без деталей; неожиданное исключение → `500 internal_error`, стек — только в серверный лог. + +**Критичные зависимости readiness.** PostgreSQL — критична (`/health/ready` = 503 без неё). Valkey — нет (`ready` остаётся 200, кэш обходится). + +**Что перенесено из lab1 и что изменено.** Приложение — прямое развитие `main.py` из lab1 (FastAPI/Uvicorn, тот же Dockerfile-подход). +- *Сохранено без изменений по поведению*: маршруты и коды ответов; формат ошибки `{"error":{code,message,request_id}}`; middleware `X-Request-Id` (входящее значение теперь принимается только если оно безопасно: `[A-Za-z0-9._-]{1,64}`, иначе генерируется новое; заголовок есть и в ответах 500/503); keyset-пагинация с курсором, привязанным к ресурсу (`messages`/`chats` + id) и порядком `(created_at, id)`; строгая валидация (лишние поля → 400, неверный Content-Type → 415, пустой/пробельный текст → 400); 404 вместо 403 для чужого чата; `/health/live` и `/health/ready`; `--timeout-graceful-shutdown 5`; тесты lab1 (`tests/test_own.py`, `tests/test_race.py`, 8+1 сценариев) перенесены на Bearer. +- *Изменено (объявленные переходы lab2)*: добавлен `password` при регистрации (Argon2id); `POST /auth/sessions` с Basic; `Authorization: Bearer` вместо `X-User-Id` (заголовок игнорируется); словари под `RLock` заменены PostgreSQL; `threading.RLock` больше не нужен — согласованность обеспечивают транзакции и ограничения БД; `/health/ready` проверяет PostgreSQL. +- *Заменено осознанно*: pydantic-модели lab1 (`extra="forbid"`) заменены строгим разбором JSON (`app/validation.py`): он отвергает дубли ключей, `NaN`, NUL и одиночные суррогаты (после них PostgreSQL возвращал бы 500), а проверка доступа (404) выполняется **до** валидации тела; автодокументация FastAPI (`/docs`) отключена — контракт в `contracts/openapi.json`. +- *Исправлено по сравнению с lab1*: регулярка `^…$` пропускала username с завершающим `\n` (в Python `$` совпадает перед `\n`) — теперь `fullmatch`; `len(display_name)` считался до проверки типов — теперь тип проверяется первым. + +**Переменные `.env.example` → код.** `APP_HOST/APP_PORT` — как в lab1, совпадают с `CMD uvicorn main:app --host 0.0.0.0 --port 8080`; число процессов — `WEB_CONCURRENCY` (читает сам uvicorn); `SESSION_TTL_SECONDS` → `app/config.py` (срок сессии); +`DATABASE_URL_FILE`, `CACHE_URL_FILE` → пути к secrets-файлам; `SESSION_STORE` = `postgres` | `postgres+cache`; `SESSION_CACHE_TTL_SECONDS` — TTL записи кэша. + +## Доказательства критериев + +Основные замеры выполнены в песочнице (без Docker, PostgreSQL 16.15, Redis 7). Дополнительно всё проверено на реальном Docker Compose-стенде +(Windows 11 + Docker Desktop, PostgreSQL 17.6, Valkey 8.1.3): + +- `sh scripts/init-secrets.sh` — 4 секрета в `secrets/`, `.env` +- `docker compose --env-file .env up -d --build` — postgres/migrate/valkey/api, api healthy +- `python tests/smoke.py --base-url http://localhost:8080` → PASS +- Persistence: полный рестарт api+valkey+postgres тем же Bearer-токеном → 200 (`evidence/persistence-my.txt`) +- Миграции идемпотентны: `migrate` повторно → «nothing to do» (`evidence/migrations-my.txt`) +- Свои тесты: 11/11 passed (`evidence/tests-my.txt`) +- Тесты зависимостей (`evidence/tests-deps-my.txt`) +- **Трек 2 — индексы (2 прохода)**: `evidence/track2-indexes-my.json`, `evidence/track2-indexes-pass2-my.json` +- **Трек 2 — backup/restore со сверкой md5**: `evidence/track2-restore-my.txt` + (SRC=DST: users 1, chats 563, messages 102000, sessions 1; md5 совпал) +- Теги `postgres:17.6-alpine` и `valkey/valkey:8.1.3-alpine` проверены через `docker pull` + +| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл | +| --- | --- | --- | --- | +| Тесты lab1 в новой аутентификации + гонка регистрации | `pytest tests/test_own.py tests/test_race.py -v` | 15 passed | `test-results.txt` | +| Публичный smoke | `python tests/smoke.py` | `PASS: lab2 public API scenario` | `test-results.txt`, `smoke_docker.txt` | +| Контракт offline | `python scripts/check_contract.py` | `PASS: offline skeleton structure…` | `test-results.txt` | +| PostgreSQL: таблицы, PK/FK, UNIQUE, миграции с нуля | `python -m app.migrate` ×2 | 1-й запуск: применены 0001, 0002; 2-й: «nothing to do» | `migrations.txt`, `migrations-my.txt` | +| Атомарное создание чата | `tests_student/test_db_rollback.py` | FK-ошибка после `INSERT chats` → 0 строк остаётся | `test-results.txt` | +| Basic только на `/auth/sessions`, Bearer везде, `X-User-Id` игнорируется | smoke + `test_integration.py` | 401 с корректными `WWW-Authenticate` | `test-results.txt` | +| Пароли — KDF | код `app/security.py` | Argon2id (m=19 MiB, t=2, p=1), соль на пароль, rehash при смене параметров | — | +| Рестарт API и хранилищ, сессии живы | `docker compose stop api valkey postgres && up -d` | тот же токен работает после рестарта | `persistence-restart.txt`, `persistence-my.txt` | +| Secrets/volumes не в Git | `.gitignore`, `.dockerignore` | `secrets/`, `.env` исключены; в образ не копируются | — | +| **4:** Valkey реально используется | `evidence/cache-role.txt` | ключи `sess:v1:`, PTTL ≤ 60 000 мс; tombstone после logout; сессия переживает `FLUSHALL` | `cache-role.txt` | +| **4:** параметризованные запросы, пул, таймауты | код `app/db.py`, `app/repo.py` | см. «Пул, таймауты» | — | +| **4:** гонка регистрации | `test_integration.py::registration_race_same_username` | 16 параллельных → ровно один 201, 15×409 | `test-results.txt` | +| **4:** индекс истории, EXPLAIN на ≥10 000 | `scripts/explain_history.py` (100 000 строк) | keyset с индексом: Index Scan, 4 буфера, **0,03–0,04 мс**; без индекса: Seq Scan 1235 буферов, **~8–9 мс** | `explain-history.txt` | +| **4:** expiry (короткий TTL) | `tests_student/test_expiry.py 2` | после 3,5 с: 401 на `users/me`, `chats`, `logout` | `test-results.txt` | +| **4:** logout, неверный пароль | smoke + `logout_revokes_only_that_session` | 204; повтор 401; неверный пароль 401 | `test-results.txt` | +| **5 (трек 2):** ≥100 000 сообщений, ≥2 индекса/запроса, цена записи | `scripts/track2_indexes.py` (2 прохода, Windows + Docker) | см. раздел «Трек 5.2» | `track2-indexes*.json`, `track2-indexes-my.json`, `track2-indexes-pass2-my.json` | +| **5 (трек 2):** backup → восстановление → сверка | `docker exec pg_dump/pg_restore` + md5 | counts SRC=DST (users 1, chats 563, messages 102000, sessions 1), md5 совпал | `track2-restore-my.txt` | +| **4:** недоступность Valkey/БД | `tests_student/test_dependencies.py` | Valkey off/flush → 200; PostgreSQL off → `ready`=503; после старта токен целы | `dependency-failure.txt`, `tests-deps-my.txt` | + +Пагинация: `pagination_walk_and_cursor_binding` — 250 сообщений от 8 параллельных писателей, обход страницами 100/37, нет потерь/дублей/перестановок; курсор чужого чата → 400. + +## Эксперименты и отказы + +| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных | +| --- | --- | --- | --- | +| Полный рестарт API + PostgreSQL + Valkey, тома сохранены | сессии и данные целы, прежний токен работает | PASS (`persistence-restart.txt`, `persistence-my.txt`) | потерь нет | +| Остановка Valkey | API работает через PostgreSQL | все запросы 200, `ready` 200, задержка < 2,5 с (circuit breaker) | мгновенно; потерь нет | +| `FLUSHALL` Valkey | сессии берутся из PostgreSQL, кэш наполняется заново | токены работают | мгновенно | +| Остановка PostgreSQL | 503, никакого доверия анониму | `ready`/бизнес 503 (`unavailable`), без токена 401 | после старта БД API восстановился автоматически; потерь нет | +| Короткий TTL (2 с) | сессия перестаёт действовать | 401 после истечения | — | + +Методика EXPLAIN: PostgreSQL 16.15 (песочница) и 17.6 (Docker Windows), 100 000 строк (1 чат 20 000 + 4 чата-шума по 20 000), `VACUUM ANALYZE`, +сравнение «без индекса» выполнено удалением индекса в откатываемой транзакции. + +## Трек 5.2. План запроса и восстановление + +### Гипотезы +- **H1.** Составной индекс `(chat_id, created_at, id)` даёт страницу истории за O(размер страницы) для чата любого размера и любой глубины; индекс только по `chat_id` и «глобальный» `(created_at, id)` — нет. +- **H2.** Дополнительный индекс удорожает запись; цена растёт с шириной индекса (покрывающий `INCLUDE (sender_id, text)` дороже всех). +- **H3.** Логический backup (`pg_dump -Fc`) восстанавливается в новый сервер без потери данных *на момент снапшота*; всё записанное после начала дампа теряется (RPO = возраст бэкапа). + +### Методика (повторяемая: `scripts/track2_indexes.py`, `scripts/track2_restore.py`) +- **Данные**: 100 000 сообщений в 563 чатах с неравномерными размерами: 1×50 000, 1×20 000, 1×10 000, 10×1 000, 50×100, 500×10; текст 10–400 символов; плюс 2 000 одиночных вставок в процессе замера записи (итого ≈102 000). +- **Конфигурации** (5): C0 только PK · C1 `(chat_id)` · **C2 `(chat_id, created_at, id)`** · C3 то же `INCLUDE (sender_id, text)` · C4 `(created_at, id)`. +- **Запросы**: Q1 первая страница гиганта (50 000) · Q2 keyset на глубине 40 000 · Q3 первая страница чата из 10 сообщений · Q4 keyset в середине чата из 1 000 · Q5 `OFFSET 40000` (антипример). Страница = 50 (+1) строк. +- **Чтение**: 20 прогревочных + 300 замеров на запрос, p50/p95 клиентской латентности, плюс `EXPLAIN (ANALYZE, BUFFERS)`. +- **Запись**: (а) `INSERT … SELECT` 100 000 строк, 3 повтора, медиана; (б) 2 000 одиночных `INSERT` с коммитом. +- **Повторяемость**: два прохода, второй — в **обратном** порядке конфигураций. + +### Результаты — собственные замеры (Windows 11 + Docker Desktop, PostgreSQL 17.6) + +**Проход 1** (`evidence/track2-indexes-my.json`): + +| Конфигурация | bulk 100k, с | single p50, мс | индекс, МиБ | Q1 p50, мс | Q2 p50, мс | Q3 p50, мс | +| --- | --- | --- | --- | --- | --- | --- | +| C0 (PK only) | 3.00 | 1.770 | 0.0 | 20.143 | 14.824 | 14.878 | +| C1 `(chat_id)` | 3.06 | 1.787 | 0.9 | 14.884 | 14.300 | 0.957 | +| **C2 `(chat_id, created_at, id)`** | 3.11 | 1.733 | 6.9 | **1.219** | **1.196** | **0.932** | +| C3 + `INCLUDE` | 3.79 | 1.741 | 35.6 | 1.184 | 1.221 | 1.050 | +| C4 `(created_at, id)` | 3.26 | 1.904 | 5.0 | 3.453 | 1.492 | 32.912 | + +**Проход 2** (`evidence/track2-indexes-pass2-my.json`, обратный порядок): + +| Конфигурация | bulk 100k, с | single p50, мс | индекс, МиБ | Q1 p50, мс | Q2 p50, мс | Q3 p50, мс | +| --- | --- | --- | --- | --- | --- | --- | +| C4 | 3.38 | 1.714 | 5.0 | 3.433 | 1.418 | 15.920 | +| C3 | 5.17 | 2.267 | 35.5 | 2.224 | 1.837 | 1.347 | +| **C2** | 3.62 | 1.847 | 6.9 | 1.327 | 1.861 | 1.095 | +| C1 | 3.86 | 2.258 | 0.9 | 17.321 | 16.562 | 1.417 | +| C0 | 3.65 | 1.822 | 0.0 | 18.452 | 18.306 | 14.635 | + +### Выводы по гипотезам +- **H1 подтверждена для C2**: 1.2–1.9 мс на любой странице любого чата (от 10 до 50 000 сообщений). C1 деградирует на гиганте (14.9–17.3 мс), C0 — везде 14–20 мс. **C4 хуже всего для маленького чата** (15.9–32.9 мс): планировщик не может эффективно отфильтровать крошечный чат по глобальному порядку. +- **Покрывающий C3 не оправдан**: Q1–Q3 того же порядка, что C2, но индекс **в 5 раз больше** (35.6 МиБ против 6.9 МиБ) и bulk-загрузка дороже (3.79 с и 5.17 с против 3.11 с и 3.62 с у C2). +- **Решение**: оставлен C2 (он же в миграции `0001_core.sql`). + +### Backup → восстановление в новое хранилище → сверка (`evidence/track2-restore-my.txt`) +- **Backup**: `docker exec messenger-lab2-postgres-1 pg_dump -U messenger -d messenger -Fc --no-owner -f /tmp/dump.dump` → 3.62 МБ. +- **Новое хранилище**: отдельный контейнер `pg-restore-target` (PostgreSQL 17.6, порт 5434). `docker exec pg_restore --no-owner --exit-on-error` — без ошибок. Затем `ANALYZE`. +- **Сверка** (совпала с источником): + +| Таблица | SRC | DST | +| --- | --- | --- | +| users | 1 | 1 | +| chats | 563 | 563 | +| messages | 102000 | 102000 | +| sessions | 1 | 1 | +| md5 всех сообщений | `440f9224c9a3e355f7fbd551e2a078eb` | `440f9224c9a3e355f7fbd551e2a078eb` | + +- **Работоспособность копии**: публичный smoke и 11 собственных тестов прошли на API, подключённом к восстановленной БД. + +### Время восстановления (RTO) и границы потери данных (RPO) +- **Измерено** (102 тыс. строк, ~65 МиБ): dump ≈0,8 с + restore ≈1,3 с + analyze ≈0,2 с ≈ **2,3 с**. Это **не оценка для продакшена**; на 100× больших данных восстановление займёт минуты. +- **RPO у логического дампа = возраст дампа.** После дампа записано 500 сообщений — в копии их нет (102 000 против 102 500 в источнике). Для сокращения RPO нужны WAL-архивация + `pg_basebackup` (PITR) или синхронная репликация — **в работе не реализованы**. +- **Безопасность при восстановлении**: отозванная после дампа сессия в копии «воскресла». Практика: после восстановления из бэкапа очистить `sessions`. +- **Что не проверялось**: восстановление в другую мажорную версию PostgreSQL, повреждённый дамп, шифрование бэкапа. + +### Ограничения методики +- 1 CPU, клиент на той же машине, 2 прохода (не повторы с доверительными интервалами); p95 одиночных вставок шумит. +- Данные синтетические; реальные распределения могут сместить цифры. +- Горячий кэш: все данные поместились в `shared_buffers`/page cache; на «холодном» диске разрыв между Seq Scan и индексом был бы больше. + +## Ограничения проверки + +- Основные замеры трека 2 сделаны в песочнице Claude (без Docker, PostgreSQL 16.15). **Дополнительно проверено на Windows 11 + Docker Desktop (PostgreSQL 17.6, Valkey 8.1.3)**: init-secrets.sh, docker compose up -d --build, smoke PASS, persistence, миграции, трек 2 (индексы + backup/restore). См. `evidence/*-my.*`. +- Теги образов проверены: `docker pull postgres:17.6-alpine` и `docker pull valkey/valkey:8.1.3-alpine` — оба существуют. +- В evidence использованы PostgreSQL 16 и Redis 7 (песочница) и 17.6/Valkey 8.1.3 (Docker Windows); на проверяемые свойства это не влияет. +- Нагрузочный профиль (`make load`) не снимался — для уровня 4 не требуется. + +## Ограничения и следующие шаги + +- Выдерживается: рестарт API/PostgreSQL/Valkey с томами; потеря/сброс/недоступность Valkey; кратковременная недоступность PostgreSQL (503 → автоматическое восстановление). +- Не выдерживается: потеря тома PostgreSQL без свежего бэкапа (логический backup делается вручную, расписания и PITR нет); отказ единственного хоста. +- Семантика конкурентных вставок: `created_at` ставится `clock_timestamp()` в момент вставки, а не COMMIT. Для точной гарантии нужна монотонная последовательность (`bigserial`/outbox) — следующий шаг. +- Кэш истории сообщений не делался (трек 1 не заявлен): сейчас кэшируются только сессии. +- HTTP без TLS допустим только для локального стенда с синтетическими данными (Basic — кодирование, а не шифрование). \ No newline at end of file diff --git a/app/__init__.py b/app/__init__.py new file mode 100644 index 0000000..e69de29 diff --git a/app/cache.py b/app/cache.py new file mode 100644 index 0000000..4f36e82 --- /dev/null +++ b/app/cache.py @@ -0,0 +1,58 @@ +"""Тонкая обёртка над Redis/Valkey. Кэш — НЕ источник истины: любая ошибка = «кэша нет». + +Circuit breaker: после сбоя кэш обходится CACHE_BACKOFF секунд, чтобы недоступный Valkey +не добавлял таймаут к каждому запросу. +""" +import logging +import threading +import time + +import redis + +from . import config + +log = logging.getLogger("cache") +_client = None +_down_until = 0.0 +_lock = threading.Lock() + + +def _get_client(): + global _client + if not config.CACHE_URL: + return None + if _client is None: + with _lock: + if _client is None: + _client = redis.Redis.from_url( + config.CACHE_URL, socket_timeout=config.CACHE_TIMEOUT, + socket_connect_timeout=config.CACHE_TIMEOUT, max_connections=20, + decode_responses=True, retry_on_timeout=False) + return _client + + +def _call(fn): + """Выполнить операцию; при недоступности вернуть None и включить паузу.""" + global _down_until + client = _get_client() + if client is None or time.monotonic() < _down_until: + return None + try: + return fn(client) + except redis.RedisError as exc: + _down_until = time.monotonic() + config.CACHE_BACKOFF + log.warning("cache unavailable (%s); bypassing for %.0fs", type(exc).__name__, config.CACHE_BACKOFF) + return None + + +def get(key): + return _call(lambda c: c.get(key)) + + +def set_if_absent(key, value, ttl_ms): + """SET NX PX: не перезаписывает tombstone отозванной сессии.""" + return _call(lambda c: c.set(key, value, nx=True, px=ttl_ms)) + + +def set_always(key, value, ttl_ms): + return _call(lambda c: c.set(key, value, px=ttl_ms)) diff --git a/app/config.py b/app/config.py new file mode 100644 index 0000000..9368d8d --- /dev/null +++ b/app/config.py @@ -0,0 +1,46 @@ +"""Конфигурация из переменных окружения. Секреты читаются из файлов (*_FILE), а не из env.""" +import os +from pathlib import Path + + +def _read(name): + """NAME_FILE (путь к секрету) имеет приоритет над NAME (прямое значение для локальной отладки).""" + path = os.environ.get(name + "_FILE") + if path: + return Path(path).read_text(encoding="utf-8").strip() + return os.environ.get(name) or None + + +def _int(name, default, low, high): + value = int(os.environ.get(name, default)) + if not low <= value <= high: + raise ValueError("%s must be in %d..%d" % (name, low, high)) + return value + + +APP_HOST = os.environ.get("APP_HOST", "0.0.0.0") +APP_PORT = _int("APP_PORT", 8080, 1, 65535) +APP_ENV = os.environ.get("APP_ENV", "lab") + +SESSION_TTL_SECONDS = _int("SESSION_TTL_SECONDS", 3600, 1, 30 * 24 * 3600) +# postgres — сессии только в PostgreSQL; +# postgres+cache — PostgreSQL (источник истины) + read-through кэш в Redis/Valkey. +SESSION_STORE = os.environ.get("SESSION_STORE", "postgres+cache") +SESSION_CACHE_TTL_SECONDS = _int("SESSION_CACHE_TTL_SECONDS", 60, 1, 3600) + +DATABASE_URL = _read("DATABASE_URL") +CACHE_URL = _read("CACHE_URL") if SESSION_STORE == "postgres+cache" else None + +DB_POOL_MIN = _int("DB_POOL_MIN", 1, 0, 50) +DB_POOL_MAX = _int("DB_POOL_MAX", 16, 1, 50) +DB_POOL_TIMEOUT = float(os.environ.get("DB_POOL_TIMEOUT", "3")) # ожидание свободного соединения +DB_STATEMENT_TIMEOUT_MS = _int("DB_STATEMENT_TIMEOUT_MS", 5000, 100, 60000) +CACHE_TIMEOUT = float(os.environ.get("CACHE_TIMEOUT", "0.25")) # connect/read timeout кэша, сек +CACHE_BACKOFF = float(os.environ.get("CACHE_BACKOFF", "2")) # пауза после сбоя кэша, сек + +# Параметры Argon2id (OWASP: m=19 MiB, t=2, p=1). +ARGON2_MEMORY_KIB = _int("ARGON2_MEMORY_KIB", 19456, 8, 1048576) +ARGON2_TIME_COST = _int("ARGON2_TIME_COST", 2, 1, 10) +MAX_BODY_BYTES = 64 * 1024 +THREAD_LIMIT = _int("THREAD_LIMIT", 24, 1, 200) # потоков для sync-обработчиков FastAPI на процесс +HASH_CONCURRENCY = _int("HASH_CONCURRENCY", 4, 1, 32) # одновременных Argon2-операций на процесс (память!) diff --git a/app/cursor.py b/app/cursor.py new file mode 100644 index 0000000..ff0c2af --- /dev/null +++ b/app/cursor.py @@ -0,0 +1,26 @@ +"""Непрозрачный keyset-курсор (created_at, id), привязанный к ресурсу.""" +import base64 +import json +from datetime import datetime, timezone + +from .errors import bad_request + + +def encode(kind, scope, created_at, row_id): + payload = {"k": kind, "s": str(scope), "t": created_at.astimezone(timezone.utc).isoformat(), "i": str(row_id)} + return base64.urlsafe_b64encode(json.dumps(payload, separators=(",", ":")).encode()).rstrip(b"=").decode() + + +def decode(value, kind, scope): + """Возвращает (created_at, id_str). Чужой чат/пользователь/вид курсора или мусор -> 400.""" + import uuid + try: + raw = base64.urlsafe_b64decode(value + "=" * (-len(value) % 4)) + payload = json.loads(raw.decode("utf-8")) + created_at = datetime.fromisoformat(payload["t"]) + row_id = uuid.UUID(payload["i"]) + if payload["k"] != kind or payload["s"] != str(scope) or created_at.tzinfo is None: + raise ValueError("scope mismatch") + return created_at, row_id + except (ValueError, KeyError, TypeError, UnicodeDecodeError): + raise bad_request("Некорректный cursor") diff --git a/app/db.py b/app/db.py new file mode 100644 index 0000000..c553c44 --- /dev/null +++ b/app/db.py @@ -0,0 +1,57 @@ +"""Пул соединений PostgreSQL: ограниченный размер, таймауты, проверка соединения при выдаче.""" +import threading + +import psycopg +from psycopg.rows import dict_row +from psycopg_pool import ConnectionPool, PoolClosed, PoolTimeout + +from . import config + +# Ошибки «зависимость недоступна/перегружена» -> 503, а не 500. +TRANSIENT = (psycopg.OperationalError, PoolTimeout, PoolClosed, psycopg.errors.QueryCanceled, + psycopg.errors.LockNotAvailable) + +_pool = None +_lock = threading.Lock() + + +def get_pool(): + """Пул создаётся лениво в каждом worker-процессе (после fork), без ожидания БД при старте.""" + global _pool + if _pool is None: + with _lock: + if _pool is None: + if not config.DATABASE_URL: + raise RuntimeError("DATABASE_URL(_FILE) is not configured") + options = ("-c statement_timeout=%d -c lock_timeout=3000 " + "-c idle_in_transaction_session_timeout=10000" % config.DB_STATEMENT_TIMEOUT_MS) + pool = ConnectionPool( + config.DATABASE_URL, + min_size=config.DB_POOL_MIN, max_size=config.DB_POOL_MAX, + timeout=config.DB_POOL_TIMEOUT, max_lifetime=1800, max_idle=300, + reconnect_timeout=5, + check=ConnectionPool.check_connection, # после рестарта PostgreSQL мёртвые соединения отбрасываются + kwargs={"row_factory": dict_row, "connect_timeout": 3, "options": options, + "application_name": "messenger-api"}, + open=False) + pool.open(wait=False) + _pool = pool + return _pool + + +def connection(timeout=None): + """Транзакция: COMMIT при выходе из with, ROLLBACK при исключении.""" + return get_pool().connection(timeout=timeout) + + +def ping(): + with connection(timeout=1.5) as conn: + conn.execute("SELECT 1") + + +def close(): + """Корректное закрытие пула при остановке процесса (SIGTERM).""" + global _pool + if _pool is not None: + _pool.close(timeout=5) + _pool = None diff --git a/app/errors.py b/app/errors.py new file mode 100644 index 0000000..9473b34 --- /dev/null +++ b/app/errors.py @@ -0,0 +1,21 @@ +class ApiError(Exception): + def __init__(self, status, code, message, headers=None): + super().__init__(message) + self.status, self.code, self.message, self.headers = status, code, message, headers or {} + + +BASIC_CHALLENGE = {"WWW-Authenticate": 'Basic realm="messenger", charset="UTF-8"'} +BEARER_CHALLENGE = {"WWW-Authenticate": 'Bearer realm="messenger"'} + + +def bad_request(message="Некорректный запрос"): + return ApiError(400, "invalid_request", message) + + +def unauthorized(challenge): + # Одно и то же сообщение для всех причин: не раскрываем, что именно не так. + return ApiError(401, "unauthorized", "Требуется аутентификация", challenge) + + +def not_found(): + return ApiError(404, "not_found", "Объект не найден") diff --git a/app/migrate.py b/app/migrate.py new file mode 100644 index 0000000..ccfcd27 --- /dev/null +++ b/app/migrate.py @@ -0,0 +1,62 @@ +"""Версионируемые миграции: python -m app.migrate. Идемпотентно и безопасно при параллельном запуске.""" +import hashlib +import logging +import sys +import time +from pathlib import Path + +import psycopg + +from . import config + +LOCK_ID = 727_002_001 # произвольный константный ключ advisory-lock +log = logging.getLogger("migrate") + + +def migration_files(): + return sorted((Path(__file__).parent / "migrations").glob("[0-9][0-9][0-9][0-9]_*.sql")) + + +def apply_all(conninfo): + files = migration_files() + # Всё выполняется в ОДНОЙ транзакции: либо все новые миграции, либо ни одной. + with psycopg.connect(conninfo, connect_timeout=3) as conn: + conn.execute("SELECT pg_advisory_xact_lock(%s)", (LOCK_ID,)) # параллельные мигрирующие процессы ждут друг друга + conn.execute("""CREATE TABLE IF NOT EXISTS schema_migrations ( + version text PRIMARY KEY, + checksum text NOT NULL, + applied_at timestamptz NOT NULL DEFAULT now())""") + applied = dict(conn.execute("SELECT version, checksum FROM schema_migrations").fetchall()) + done = [] + for path in files: + sql = path.read_text(encoding="utf-8") + checksum = hashlib.sha256(sql.encode()).hexdigest() + if path.stem in applied: + if applied[path.stem] != checksum: + raise RuntimeError("migration %s was modified after being applied" % path.stem) + continue + conn.execute(sql) + conn.execute("INSERT INTO schema_migrations (version, checksum) VALUES (%s, %s)", (path.stem, checksum)) + done.append(path.stem) + return done + + +def main(): + logging.basicConfig(level=logging.INFO, format="%(asctime)s %(name)s %(message)s") + if not config.DATABASE_URL: + sys.exit("DATABASE_URL(_FILE) is not configured") + deadline = time.monotonic() + 60 + while True: + try: + done = apply_all(config.DATABASE_URL) + break + except psycopg.OperationalError as exc: # БД ещё поднимается + if time.monotonic() > deadline: + raise + log.info("database not ready (%s), retrying", type(exc).__name__) + time.sleep(1) + log.info("applied: %s", ", ".join(done) if done else "nothing to do (schema is up to date)") + + +if __name__ == "__main__": + main() diff --git a/app/migrations/0001_core.sql b/app/migrations/0001_core.sql new file mode 100644 index 0000000..b55b392 --- /dev/null +++ b/app/migrations/0001_core.sql @@ -0,0 +1,47 @@ +-- 0001: пользователи, чаты, участники, сообщения. +-- Принципы: ограничения живут в БД (а не только в коде приложения), идентификаторы +-- генерирует приложение (UUIDv4), время ставит сервер БД (clock_timestamp()). + +CREATE TABLE users ( + id uuid PRIMARY KEY, + username text NOT NULL, + display_name text NOT NULL, + password_hash text NOT NULL, -- Argon2id (PHC string), никогда не отдаётся в API + created_at timestamptz NOT NULL DEFAULT clock_timestamp(), + CONSTRAINT users_username_key UNIQUE (username), + CONSTRAINT users_username_format CHECK (username ~ '^[a-z0-9_]{3,32}$'), + CONSTRAINT users_display_name_length CHECK (char_length(display_name) BETWEEN 1 AND 100) +); + +CREATE TABLE chats ( + id uuid PRIMARY KEY, + title text NOT NULL, + created_by uuid NOT NULL REFERENCES users (id), + created_at timestamptz NOT NULL DEFAULT clock_timestamp(), + CONSTRAINT chats_title_length CHECK (char_length(title) BETWEEN 1 AND 100) +); +-- Keyset-пагинация списка чатов по (created_at, id). +CREATE INDEX chats_created_at_id_idx ON chats (created_at, id); + +CREATE TABLE chat_members ( + chat_id uuid NOT NULL REFERENCES chats (id) ON DELETE CASCADE, + user_id uuid NOT NULL REFERENCES users (id), + added_at timestamptz NOT NULL DEFAULT clock_timestamp(), + PRIMARY KEY (chat_id, user_id) +); +-- «Какие чаты у пользователя?» — обратное направление к PK. +CREATE INDEX chat_members_user_chat_idx ON chat_members (user_id, chat_id); + +CREATE TABLE messages ( + id uuid PRIMARY KEY, + chat_id uuid NOT NULL, + sender_id uuid NOT NULL, + text text NOT NULL, + created_at timestamptz NOT NULL DEFAULT clock_timestamp(), + CONSTRAINT messages_text_length CHECK (char_length(text) BETWEEN 1 AND 4000), + -- Инвариант на уровне БД: писать в чат может только его участник. + CONSTRAINT messages_sender_is_member FOREIGN KEY (chat_id, sender_id) + REFERENCES chat_members (chat_id, user_id) +); +-- Индекс истории: равенство по chat_id + порядок (created_at, id) = ровно запрос keyset-страницы. +CREATE INDEX messages_chat_created_id_idx ON messages (chat_id, created_at, id); diff --git a/app/migrations/0002_sessions.sql b/app/migrations/0002_sessions.sql new file mode 100644 index 0000000..0638105 --- /dev/null +++ b/app/migrations/0002_sessions.sql @@ -0,0 +1,13 @@ +-- 0002: серверные сессии. Источник истины — PostgreSQL; Redis/Valkey лишь кэш. +-- В БД лежит SHA-256 от токена, а не сам токен: утечка дампа не даёт готовых Bearer-токенов. +CREATE TABLE sessions ( + token_hash bytea PRIMARY KEY, + user_id uuid NOT NULL REFERENCES users (id), + created_at timestamptz NOT NULL DEFAULT clock_timestamp(), + expires_at timestamptz NOT NULL, + CONSTRAINT sessions_hash_length CHECK (octet_length(token_hash) = 32), + CONSTRAINT sessions_expiry_after_creation CHECK (expires_at > created_at) +); +-- Выборка просроченных сессий при фоновой очистке. +CREATE INDEX sessions_expires_at_idx ON sessions (expires_at); +CREATE INDEX sessions_user_idx ON sessions (user_id); diff --git a/app/repo.py b/app/repo.py new file mode 100644 index 0000000..dd6263e --- /dev/null +++ b/app/repo.py @@ -0,0 +1,105 @@ +"""Доступ к данным. Только параметризованные запросы (psycopg передаёт параметры отдельно от SQL).""" +import uuid + +from . import cursor, security +from .errors import bad_request +from .sessions import fmt_ts + + +def username_exists(conn, username): + return conn.execute("SELECT 1 FROM users WHERE username = %s", (username,)).fetchone() is not None + + +def insert_user(conn, username, display_name, password_hash): + return conn.execute( + """INSERT INTO users (id, username, display_name, password_hash) VALUES (%s, %s, %s, %s) + RETURNING id, username, display_name, created_at""", + (uuid.uuid4(), username, display_name, password_hash)).fetchone() + + +def user_for_login(conn, username): + return conn.execute("SELECT id, username, display_name, password_hash, created_at FROM users WHERE username = %s", + (username,)).fetchone() + + +def update_password_hash(conn, user_id, new_hash): + conn.execute("UPDATE users SET password_hash = %s WHERE id = %s", (new_hash, user_id)) + + +def chat_json(row): + return {"id": str(row["id"]), "title": row["title"], "member_ids": [str(x) for x in row["member_ids"]], + "created_at": fmt_ts(row["created_at"])} + + +def create_chat(conn, creator_id, title, member_ids, check_members=True): + """Составная операция (users -> chats -> chat_members) в транзакции вызывающего. + + Любая ошибка после вставки chats откатывает ВСЁ: чат без участников не появится. + check_members=False нужен только тесту отката: FK на chat_members сработает уже после вставки чата. + """ + if check_members: + found = conn.execute("SELECT count(*) AS n FROM users WHERE id = ANY(%s)", (member_ids,)).fetchone()["n"] + if found != len(member_ids): + raise bad_request("Неизвестный участник чата") + chat = conn.execute( + "INSERT INTO chats (id, title, created_by) VALUES (%s, %s, %s) RETURNING id, title, created_at", + (uuid.uuid4(), title, creator_id)).fetchone() + conn.execute("INSERT INTO chat_members (chat_id, user_id) SELECT %s, unnest(%s::uuid[])", + (chat["id"], member_ids)) + chat["member_ids"] = sorted(member_ids) + return chat + + +def get_chat(conn, chat_id, user_id): + """Чат + список участников, только если user_id — участник (иначе None => 404).""" + return conn.execute( + """SELECT c.id, c.title, c.created_at, + ARRAY(SELECT m.user_id FROM chat_members m WHERE m.chat_id = c.id ORDER BY m.user_id) AS member_ids + FROM chats c + WHERE c.id = %s AND EXISTS (SELECT 1 FROM chat_members me WHERE me.chat_id = c.id AND me.user_id = %s)""", + (chat_id, user_id)).fetchone() + + +def is_member(conn, chat_id, user_id): + return conn.execute("SELECT 1 FROM chat_members WHERE chat_id = %s AND user_id = %s", + (chat_id, user_id)).fetchone() is not None + + +def list_chats(conn, user_id, after, limit): + base = """SELECT c.id, c.title, c.created_at, + ARRAY(SELECT m.user_id FROM chat_members m WHERE m.chat_id = c.id ORDER BY m.user_id) AS member_ids + FROM chat_members me JOIN chats c ON c.id = me.chat_id + WHERE me.user_id = %s""" + params = [user_id] + if after: + base += " AND (c.created_at, c.id) > (%s, %s)" + params += list(after) + rows = conn.execute(base + " ORDER BY c.created_at, c.id LIMIT %s", params + [limit + 1]).fetchall() + page, more = rows[:limit], len(rows) > limit + nxt = cursor.encode("chats", user_id, page[-1]["created_at"], page[-1]["id"]) if more else None + return [chat_json(r) for r in page], nxt + + +def message_json(row): + return {"id": str(row["id"]), "chat_id": str(row["chat_id"]), "sender_id": str(row["sender_id"]), + "text": row["text"], "created_at": fmt_ts(row["created_at"])} + + +def insert_message(conn, chat_id, sender_id, text): + return conn.execute( + """INSERT INTO messages (id, chat_id, sender_id, text) VALUES (%s, %s, %s, %s) + RETURNING id, chat_id, sender_id, text, created_at""", + (uuid.uuid4(), chat_id, sender_id, text)).fetchone() + + +def list_messages(conn, chat_id, after, limit): + """Keyset: WHERE (created_at, id) > курсор ORDER BY created_at, id LIMIT n+1 — идёт по индексу, без OFFSET.""" + sql = "SELECT id, chat_id, sender_id, text, created_at FROM messages WHERE chat_id = %s" + params = [chat_id] + if after: + sql += " AND (created_at, id) > (%s, %s)" + params += list(after) + rows = conn.execute(sql + " ORDER BY created_at, id LIMIT %s", params + [limit + 1]).fetchall() + page, more = rows[:limit], len(rows) > limit + nxt = cursor.encode("messages", chat_id, page[-1]["created_at"], page[-1]["id"]) if more else None + return [message_json(r) for r in page], nxt diff --git a/app/security.py b/app/security.py new file mode 100644 index 0000000..1d0e207 --- /dev/null +++ b/app/security.py @@ -0,0 +1,77 @@ +"""Пароли (Argon2id), токены, разбор заголовка Authorization.""" +import base64 +import binascii +import hashlib +import re +import secrets +import threading + +from argon2 import PasswordHasher, Type +from argon2.exceptions import InvalidHashError, VerificationError + +from . import config + +_hasher = PasswordHasher(time_cost=config.ARGON2_TIME_COST, memory_cost=config.ARGON2_MEMORY_KIB, + parallelism=1, hash_len=32, salt_len=16, type=Type.ID) +# Хеш-заглушка: при неизвестном username всё равно тратим время на verify -> нет timing-оракула «есть ли такой логин». +_DUMMY_HASH = _hasher.hash("dummy-password-for-constant-time") +# Каждая операция Argon2 держит ~19 МиБ: ограничиваем параллелизм, иначе всплеск входов исчерпает память контейнера. +_hash_slots = threading.BoundedSemaphore(config.HASH_CONCURRENCY) +_TOKEN_RE = re.compile(r"[A-Za-z0-9._~+/=-]{16,512}") + + +def hash_password(password): + with _hash_slots: + return _hasher.hash(password) # UTF-8 пароля целиком, без усечения; соль генерируется библиотекой + + +def verify_password(stored_hash, password): + """(ok, new_hash_or_None). new_hash — если параметры KDF устарели и хеш надо обновить.""" + with _hash_slots: + try: + _hasher.verify(stored_hash, password) + except (VerificationError, InvalidHashError): + return False, None + return True, (_hasher.hash(password) if _hasher.check_needs_rehash(stored_hash) else None) + + +def burn_verify(password): + with _hash_slots: + try: + _hasher.verify(_DUMMY_HASH, password) + except VerificationError: + pass + + +def new_token(): + return secrets.token_urlsafe(32) # 32 байта CSPRNG = 256 бит энтропии + + +def token_hash(token): + # Токен уже высокоэнтропийный, поэтому быстрый SHA-256 достаточен (в отличие от паролей, где нужен медленный KDF). + return hashlib.sha256(token.encode("ascii")).digest() + + +def parse_basic(header): + """Возвращает (username, password) или None. Любой дефект -> None (одинаковый 401).""" + if not header: + return None + scheme, _, rest = header.partition(" ") + if scheme.lower() != "basic": + return None + try: + text = base64.b64decode(rest.strip(), validate=True).decode("utf-8") + except (binascii.Error, UnicodeDecodeError, ValueError): + return None + username, sep, password = text.partition(":") # двоеточие допустимо в пароле: делим по ПЕРВОМУ + return (username, password) if sep else None + + +def parse_bearer(header): + if not header: + return None + scheme, _, rest = header.partition(" ") + token = rest.strip() + if scheme.lower() != "bearer" or not _TOKEN_RE.fullmatch(token): + return None + return token diff --git a/app/sessions.py b/app/sessions.py new file mode 100644 index 0000000..df04731 --- /dev/null +++ b/app/sessions.py @@ -0,0 +1,86 @@ +"""Сессии: PostgreSQL — источник истины, Redis/Valkey — read-through кэш (cache-aside). + +Чтение: кэш -> (промах) -> PostgreSQL -> наполнение кэша с TTL = min(SESSION_CACHE_TTL, остаток жизни). +Отзыв: DELETE в PostgreSQL (commit) -> tombstone в кэше (SET), чтобы медленный параллельный reader +не воскресил сессию через SET NX. Потеря/сброс кэша ничего не ломает: данные берутся из PostgreSQL. +""" +import json +import time +from datetime import timezone + +from . import cache, config, db, security + +TOMBSTONE = "revoked" +_KEY = "sess:v1:" + + +def fmt_ts(value): + return value.astimezone(timezone.utc).strftime("%Y-%m-%dT%H:%M:%S.%fZ") + + +def user_json(row): + return {"id": str(row["id"]), "username": row["username"], "display_name": row["display_name"], + "created_at": fmt_ts(row["created_at"])} + + +def _ttl_ms(expires_epoch): + remaining = expires_epoch - time.time() + return int(min(config.SESSION_CACHE_TTL_SECONDS, remaining) * 1000) if remaining > 0 else 0 + + +def create(conn, user_row): + """Выдать токен; запись о сессии коммитится вместе с транзакцией вызывающего.""" + token = security.new_token() + row = conn.execute( + """INSERT INTO sessions (token_hash, user_id, expires_at) + VALUES (%s, %s, clock_timestamp() + make_interval(secs => %s)) + RETURNING expires_at""", + (security.token_hash(token), user_row["id"], config.SESSION_TTL_SECONDS)).fetchone() + # Опортунистическая очистка: старые просроченные строки (не более 100 за вход). + conn.execute("""DELETE FROM sessions WHERE token_hash IN ( + SELECT token_hash FROM sessions WHERE expires_at < now() - interval '1 hour' LIMIT 100)""") + return token, row["expires_at"] + + +def warm(token, user, expires_at): + entry = {"user": user, "exp": expires_at.timestamp()} + ttl = _ttl_ms(entry["exp"]) + if ttl > 0: + cache.set_if_absent(_KEY + security.token_hash(token).hex(), json.dumps(entry), ttl) + + +def lookup(token): + """-> {'user': {...}} либо None (неизвестная/истёкшая/отозванная сессия). Исключения БД -> 503 выше.""" + digest = security.token_hash(token) + key = _KEY + digest.hex() + cached = cache.get(key) + if cached == TOMBSTONE: + return None + if cached: + try: + entry = json.loads(cached) + if entry["exp"] > time.time(): # срок проверяем и по кэшу: expiry не зависит от TTL ключа + return {"user": entry["user"], "digest": digest} + return None + except (ValueError, KeyError, TypeError): + pass # битая запись = промах + with db.connection() as conn: + row = conn.execute( + """SELECT u.id, u.username, u.display_name, u.created_at, + extract(epoch FROM s.expires_at) AS exp + FROM sessions s JOIN users u ON u.id = s.user_id + WHERE s.token_hash = %s AND s.expires_at > clock_timestamp()""", (digest,)).fetchone() + if row is None: + return None # отрицательные результаты не кэшируем (защита от забивания кэша) + user = user_json(row) + ttl = _ttl_ms(float(row["exp"])) + if ttl > 0: + cache.set_if_absent(key, json.dumps({"user": user, "exp": float(row["exp"])}), ttl) + return {"user": user, "digest": digest} + + +def revoke(digest): + with db.connection() as conn: + conn.execute("DELETE FROM sessions WHERE token_hash = %s", (digest,)) + # Только ПОСЛЕ commit: иначе читатель мог бы заново закэшировать ещё живую сессию. + cache.set_always(_KEY + digest.hex(), TOMBSTONE, config.SESSION_CACHE_TTL_SECONDS * 1000) diff --git a/app/validation.py b/app/validation.py new file mode 100644 index 0000000..66dccb8 --- /dev/null +++ b/app/validation.py @@ -0,0 +1,84 @@ +"""Строгая валидация входа: никаких лишних полей, типов-«почти», NUL и суррогатов.""" +import json +import re +import uuid + +from .errors import ApiError, bad_request + +_UUID_RE = re.compile(r"[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}") +_USERNAME_RE = re.compile(r"[a-z0-9_]{3,32}") # fullmatch: «$» в Python пропускает завершающий \n! +_INT_RE = re.compile(r"[0-9]{1,6}") + + +def parse_uuid(value): + if isinstance(value, str) and _UUID_RE.fullmatch(value): + return uuid.UUID(value) + return None + + +def require_uuid(value, name="id"): + parsed = parse_uuid(value) + if parsed is None: + raise bad_request("Некорректный %s" % name) + return parsed + + +def _reject_constant(name): + raise ValueError("non-finite number") + + +def _no_duplicates(pairs): + result = {} + for key, value in pairs: + if key in result: + raise ValueError("duplicate key") + result[key] = value + return result + + +def json_body(content_type, raw, allowed, required): + """content_type — значение заголовка; raw — тело (размер уже ограничен при чтении -> 413).""" + if content_type.split(";")[0].strip().lower() != "application/json": + raise ApiError(415, "unsupported_media_type", "Ожидается Content-Type: application/json") + try: + data = json.loads(raw.decode("utf-8"), parse_constant=_reject_constant, object_pairs_hook=_no_duplicates) + except (ValueError, UnicodeDecodeError, RecursionError): + raise bad_request("Некорректный JSON") + if not isinstance(data, dict) or set(data) - set(allowed) or not set(required) <= set(data): + raise bad_request("Некорректный набор полей") + return data + + +def text_field(value, name, low, high, allow_blank=False): + if not isinstance(value, str): + raise bad_request("Поле %s должно быть строкой" % name) + if "\x00" in value or not _encodable(value): + raise bad_request("Поле %s содержит недопустимые символы" % name) + if not low <= len(value) <= high: # len(str) в Python = число Unicode code points + raise bad_request("Поле %s: длина должна быть %d–%d" % (name, low, high)) + if not allow_blank and not value.strip(): + raise bad_request("Поле %s не должно состоять только из пробелов" % name) + return value + + +def _encodable(value): + try: + value.encode("utf-8") + return True + except UnicodeEncodeError: # одиночные суррогаты из "\ud800" + return False + + +def username_field(value): + if not isinstance(value, str) or not _USERNAME_RE.fullmatch(value): + raise bad_request("username должен соответствовать [a-z0-9_]{3,32}") + return value + + +def limit_param(params): + raw = params.get("limit") + if raw is None: + return 50 + if not _INT_RE.fullmatch(raw) or not 1 <= int(raw) <= 100: + raise bad_request("limit должен быть целым числом 1–100") + return int(raw) diff --git a/compose.example.yaml b/compose.example.yaml new file mode 100644 index 0000000..52524b0 --- /dev/null +++ b/compose.example.yaml @@ -0,0 +1,10 @@ +# Topology worksheet, deliberately NOT a runnable stack (no application supplied). +# Implement compose.yaml or stack.yaml; do not submit this empty file as deployment. +# Service names below are logical roles, not imposed container names. +x-lab-number: 2 +x-required-roles: + - api + - postgres +# TODO: implement real images/builds, network wiring, volumes, healthchecks, +# credentials and bootstrap. Details: contracts/infrastructure.json and README.md. +services: {} diff --git a/compose.yaml b/compose.yaml new file mode 100644 index 0000000..ec17cf4 --- /dev/null +++ b/compose.yaml @@ -0,0 +1,103 @@ +# Локальный стенд лабораторной 2: API + PostgreSQL + Valkey (кэш сессий). +# Порядок запуска: sh scripts/init-secrets.sh && docker compose --env-file .env up -d --build +name: messenger-lab2 + +x-app-env: &app-env + APP_HOST: "0.0.0.0" + APP_PORT: "8080" + APP_ENV: ${APP_ENV:-lab} + SESSION_TTL_SECONDS: ${SESSION_TTL_SECONDS:-3600} + SESSION_STORE: ${SESSION_STORE:-postgres+cache} + SESSION_CACHE_TTL_SECONDS: ${SESSION_CACHE_TTL_SECONDS:-60} + DATABASE_URL_FILE: /run/secrets/database_url # секреты — файлами, не переменными окружения + CACHE_URL_FILE: /run/secrets/cache_url + +services: + postgres: # источник истины: users/chats/members/messages/sessions + image: postgres:17.6-alpine + ports: + - "127.0.0.1:5433:5432" # временно открыт для track2_indexes.py + restart: unless-stopped + environment: + POSTGRES_DB: messenger + POSTGRES_USER: messenger + POSTGRES_PASSWORD_FILE: /run/secrets/postgres_password + secrets: [postgres_password] + command: ["postgres", "-c", "fsync=on", "-c", "synchronous_commit=on", "-c", "full_page_writes=on", + "-c", "max_connections=100"] # durability явно: COMMIT = WAL сброшен на диск + volumes: + - pgdata:/var/lib/postgresql/data + healthcheck: + test: ["CMD-SHELL", "pg_isready -U messenger -d messenger"] + interval: 3s + timeout: 3s + retries: 20 + stop_grace_period: 30s + networks: [backend] + + valkey: # кэш сессий (read-through); истина — PostgreSQL + image: valkey/valkey:8.1.3-alpine + restart: unless-stopped + secrets: [valkey_password] + command: + - sh + - -c + - >- + exec valkey-server --requirepass "$$(cat /run/secrets/valkey_password)" + --appendonly yes --appendfsync everysec --save "" + --maxmemory 64mb --maxmemory-policy volatile-ttl + volumes: + - valkeydata:/data + healthcheck: + test: ["CMD-SHELL", "REDISCLI_AUTH=\"$$(cat /run/secrets/valkey_password)\" valkey-cli ping | grep -q PONG"] + interval: 3s + timeout: 3s + retries: 20 + networks: [backend] + + migrate: # одноразово применяет миграции; идемпотентен + build: . + command: ["python", "-m", "app.migrate"] + environment: *app-env + secrets: [database_url, cache_url] + depends_on: + postgres: {condition: service_healthy} + restart: "no" + networks: [backend] + + api: + build: . + restart: unless-stopped + environment: *app-env + secrets: [database_url, cache_url] + depends_on: + migrate: {condition: service_completed_successfully} + postgres: {condition: service_healthy} + valkey: {condition: service_started} # кэш не критичен: API стартует и без него + ports: + - "127.0.0.1:8080:8080" # единственный опубликованный порт, только localhost + read_only: true + tmpfs: ["/tmp", "/dev/shm"] + cap_drop: [ALL] + security_opt: ["no-new-privileges:true"] + healthcheck: # readiness: API + PostgreSQL + test: ["CMD", "python", "-c", "import urllib.request as u; u.urlopen('http://127.0.0.1:8080/health/ready', timeout=2)"] + interval: 3s + timeout: 3s + retries: 20 + start_period: 5s + stop_grace_period: 25s + networks: [backend] + +networks: + backend: {} + +volumes: # именованные: переживают stop/restart/down (но не down -v) + pgdata: {} + valkeydata: {} + +secrets: + postgres_password: {file: ./secrets/postgres_password} + valkey_password: {file: ./secrets/valkey_password} + database_url: {file: ./secrets/database_url} + cache_url: {file: ./secrets/cache_url} \ No newline at end of file diff --git a/contracts/README.md b/contracts/README.md new file mode 100644 index 0000000..8c58b32 --- /dev/null +++ b/contracts/README.md @@ -0,0 +1,61 @@ +# Семантика API + +Этот текст дополняет [openapi.json](openapi.json). Обязательный API соответствует уровню 3 текущей лабораторной. Факультативный crop или rate limiting не становятся обязательными только из-за наличия допустимого имени варианта или кода ошибки в схеме. + +## Формат и ошибки + +- JSON — UTF-8, `Content-Type: application/json`. UUID — строка; время — RFC 3339 UTC с `Z`, назначается сервером. Часы не считаются уникальным ID. +- Каждый ответ API, включая ошибки и health, содержит непустой `X-Request-Id`. Тело ошибки: `{"error":{"code":"invalid_request","message":"...","request_id":"..."}}`; `request_id` совпадает с заголовком. Сообщение ошибки не раскрывает stack trace, SQL, credentials или наличие чужого объекта. +- Обязательные строки не состоят только из пробельных символов. `username` строго `[a-z0-9_]{3,32}`, уникален; `display_name` — 1–100 Unicode code points. JSON с лишними полями или неверными типами — `400`; malformed JSON также `400`. +- `400 invalid_request` — неверные поля, UUID, cursor, limit; `401 unauthorized` — нет действительной идентификации/сессии; `404 not_found` — объекта нет или он чужой; `409 conflict` — username занят, повторный ключ с другим сообщением, объект ещё не готов; `413 payload_too_large`; `415 unsupported_media_type`; `429 rate_limited`; `503 unavailable`. Неожиданное исключение — `500 internal_error` без внутренних деталей. +- Сначала аутентификация, затем доступ к конкретному ресурсу. Любой аутентифицированный участник чата может читать его историю и вложения и писать в него; посторонний получает `404`. Списки содержат только доступные объекты. Не используйте `403` для раскрытия существования чужого чата. +- `GET /health/live` проверяет только жизнь процесса, возвращает `200 {"status":"ok"}`. `GET /health/ready` возвращает 200, если приложение может безопасно обслуживать обязательный синхронный путь; иначе 503 в общем формате ошибки. Какие зависимости критичны, зафиксируйте в отчёте; недоступность Grafana не должна останавливать API. + +## Пользователи, чаты и сообщения + +- `POST /users` публичен; возвращает `201 User`. Пароль/его hash и сессионные данные никогда не входят в User. +- `POST /chats` принимает title и явный список существующих `member_ids`, включая вызывающего. Дубликаты, неизвестные участники и отсутствие вызывающего — 400. Чат создаётся атомарно. GET списка чатов сортируется по `(created_at, id)` по возрастанию. +- Отправитель сообщения выводится из текущей идентификации, поле `sender_id` в запросе не принимается. Текст — до 4000 Unicode code points. Нельзя отправить пустой/пробельный текст без вложений. +- История использует keyset cursor: `(created_at, id)`, по возрастанию; `limit` — целое 1–100, по умолчанию 50. Ответ `{"items":[...],"next_cursor":null}`. Непустой cursor — непрозрачная для клиента строка; последний элемент предыдущей страницы не повторяется. Cursor привязан к ресурсу/запросу: от другого чата — 400. Изменять `limit` при продолжении можно. +- `next_cursor` равен null, если на момент чтения следующей записи нет. Гарантируется отсутствие повторов при обходе неизменной истории; snapshot изоляция между несколькими HTTP-запросами не требуется. При конкурентных вставках опишите выбранную семантику и ограничения часов. +- Подтверждённое сообщение видно следующему чтению через любую API-реплику. Допускается кэш, но он не должен возвращать устаревшую историю после успешной записи. Удаление и изменение участников в обязательный API не входят. + +## Идентификация и сессии + +**Lab1:** защищённые endpoint требуют `X-User-Id: `; отсутствие/неизвестный ID — 401. Это учебный выбор пользователя: любой клиент может выдать себя за другого. + +**Lab2–7:** `POST /auth/sessions` принимает только `Authorization: Basic `, без JSON body. Username ограничен ASCII; пароль кодируется UTF-8, 12–128 code points, двоеточие в пароле допустимо. Неверные credentials — одинаковый 401 и `WWW-Authenticate: Basic realm="messenger", charset="UTF-8"`. + +Вход возвращает `201 {"token":"...","token_type":"Bearer","expires_at":"...Z","user":{...}}`. Токен — непрозрачное случайное значение, не username/UUID и не обязательный JWT; энтропия не менее 256 бит. Храните серверную сессию с expiry; TTL задаётся `SESSION_TTL_SECONDS`, по умолчанию 3600 (в тесте истечения можно 2). В обычном smoke TTL должен быть не менее 300. + +Все защищённые endpoint принимают только `Authorization: Bearer `. Истёкший/отозванный/неизвестный токен — 401 с `WWW-Authenticate: Bearer realm="messenger"`. Basic на бизнес-endpoint — 401. `X-User-Id` с lab2 игнорируется: он не меняет владельца сессии и сам по себе не даёт доступ. `DELETE /auth/sessions/current` отзывает текущий токен и возвращает 204 без тела; повтор с отозванным токеном — 401. + +Пользователи, чаты, сообщения и ещё действительные сессии переживают перезапуск приложения и используемых хранилищ с сохранёнными volumes. TTL не продлевается из-за рестарта. Пароли уже с lab2 хешируются библиотечным password KDF (Argon2id, scrypt или bcrypt с учётом ограничений библиотеки), не SHA-256 и не plaintext. Если bcrypt не поддерживает весь диапазон UTF-8 паролей без усечения, выберите другую библиотечную схему. В lab7 обязателен Argon2id. + +Basic — это кодирование, не шифрование. HTTP lab1–6 допускается только для локального изолированного стенда с синтетическими данными; для удалённой демонстрации нужен TLS. Lab7 использует HTTPS обязательно. См. [RFC 7617](https://www.rfc-editor.org/info/rfc7617/). + +## Балансировка и повторная отправка (с lab3) + +- Каждый ответ, созданный API, содержит `X-Instance-Id`; значение стабильно для жизни процесса. Ошибки соединения, созданные самим LB, могут не иметь этого заголовка. В lab7 используйте случайный alias реплики без раскрытия hostname/IP. +- Для POST сообщения обязателен `Idempotency-Key` (ASCII `[A-Za-z0-9._:-]{1,128}`). Нет/неверный ключ — 400. Область уникальности: текущий пользователь + HTTP-метод + путь чата + ключ. +- При повторе того же валидного JSON в течение 24 часов сервер возвращает тот же код 201 и то же Message. Порядок ключей JSON и отсутствующий `attachment_ids` вместо `[]` семантически равны. Другой body при том же ключе — 409. Разные пользователи/чаты могут использовать одинаковый ключ независимо. +- Одновременные повторы через разные реплики создают ровно одно сообщение. Повтор снова проверяет действительность сессии и доступ. Транзиентные 5xx не фиксируются как окончательный результат; побочный эффект и запись результата должны быть атомарны. +- Ключ обязателен только для сообщений. Самостоятельный retry загрузки файла или создания чата может создать ещё один объект; не добавляйте прозрачные повторы этих POST без расширения контракта. + +## Вложения (с lab4) + +- `POST /chats/{chat_id}/attachments?filename=photo.png`: сырые bytes одного PNG/JPEG; `Content-Type: image/png` или `image/jpeg`. Не multipart. Максимум **10 MiB = 10 485 760 байт**. MIME проверяется по содержимому; заведомо повреждённые/чужие форматы — 415, превышение bytes — 413. Не более 40 миллионов декодированных пикселей (превышение — 413). Устанавливайте лимит до полной распаковки изображения. +- `filename` — отображаемое имя (1–255 code points). Не используйте его как путь/ключ S3. Имя с `/`, `\`, NUL или управляющими символами — 400. Bucket приватен; object key генерирует сервер. Оригинал возвращается побайтно, его lowercase SHA-256 и размер соответствуют исходному файлу. +- Lab4 возвращает `201 Attachment` со `status=ready`, `variants=[]`, `error_code=null` только после сохранения оригинала и метаданных. Lab5–7 возвращают `202 Attachment` со снимком `status=queued`; готовность определяется последующим GET метаданных. Быстрый worker может закончить до первого GET — это нормально. +- Файл заранее привязан к чату. В POST сообщения добавляется `attachment_ids` (0–10 уникальных ID, по умолчанию []). Можно отправить `text=""` с хотя бы одним вложением. Все вложения должны принадлежать этому чату; чужое/неизвестное — 404. Любой участник может ссылаться на доступное вложение чата. Failed-вложение прикреплять нельзя (409); queued/processing с lab5 можно. +- `GET /attachments/{id}` и `/content` доступны только участникам чата. Download возвращает байты с истинным Content-Type, через авторизованный API, **без redirect** в обязательном контракте. Приватный bucket сам по себе не заменяет эту проверку. `variant` по умолчанию original. Для queued/processing content — 409; для failed — 409. Отсутствующий вариант ready-объекта — 404. +- В ready-метаданных `error_code=null`. В failed — краткий машинный код (например `invalid_image`, `processing_failed`, `retry_exhausted`), без stack trace. `size_bytes`, `sha256`, `content_type` всегда описывают оригинал; у вариантов отдельные поля. Публичный API не раскрывает ключи бакета, внутренние адреса и credentials. +- Прямой upload/download по временной подписи — факультативное расширение. Его дополняют ограничение срока/размера, уникальный ключ и подтверждение реально загруженного объекта; он не заменяет стандартный endpoint. Особенности подписанных URL: [S3](https://docs.aws.amazon.com/AmazonS3/latest/userguide/using-presigned-url.html). + +## Фоновая обработка (с lab5) + +До 202 все байты приняты в **устойчивый staging**, а намерение обработать файл надёжно сохранено. HTTP-передача клиента не исчезает и не становится мгновенной. Staging — приватный S3-prefix либо общий persistent volume, доступный worker; локальная память/API ephemeral disk не подходит. Worker асинхронно переносит/публикует оригинал в конечный S3-prefix и создаёт варианты; если staging уже в S3, опишите эту границу честно. + +Обязательный thumbnail: JPEG, изображение вписано в 256×256 с сохранением пропорций, без увеличения маленьких исходников, EXIF orientation применяется; alpha компонуется на белый. Размеры округляются вниз, минимум 1 px. Fixture 320×200 должен дать 256×160. Статус ready ставится после сохранения оригинала и thumbnail. Crop на 4: JPEG, центрированный квадрат 128×128 (для маленьких исходников допускается увеличение). Optimized на 4: WebP, вписан в 1280×1280 без увеличения, параметры качества и удаления EXIF документируются; не обещайте уменьшение каждого маленького файла. + +Допустимые состояния и события описаны в `jobs.schema.json` и `attachment-states.md`. Доставка — at least once; обработка идемпотентна, повторы не размножают варианты. Финальные ошибки наблюдаемы, бесконечный немой retry недопустим. Обязательный smoke ждёт ready до 60 секунд; это бюджет локального smoke для одного файла при свободном worker, не универсальный production SLA. В очередь идут ссылки/ID, не бинарное содержимое. diff --git a/contracts/examples.json b/contracts/examples.json new file mode 100644 index 0000000..eaa4fcd --- /dev/null +++ b/contracts/examples.json @@ -0,0 +1,58 @@ +{ + "CreateUser": { + "username": "alice", + "display_name": "Алиса", + "password": "Example-only-not-a-real-secret-123" + }, + "User": { + "id": "11111111-1111-4111-8111-111111111111", + "username": "alice", + "display_name": "Алиса", + "created_at": "2026-09-01T12:00:00Z" + }, + "CreateChat": { + "title": "Проект по ВНП", + "member_ids": [ + "11111111-1111-4111-8111-111111111111", + "22222222-2222-4222-8222-222222222222" + ] + }, + "Chat": { + "title": "Проект по ВНП", + "member_ids": [ + "11111111-1111-4111-8111-111111111111", + "22222222-2222-4222-8222-222222222222" + ], + "id": "33333333-3333-4333-8333-333333333333", + "created_at": "2026-09-01T12:00:00Z" + }, + "CreateMessage": { + "text": "Привет, Боб!" + }, + "Message": { + "id": "44444444-4444-4444-8444-444444444444", + "chat_id": "33333333-3333-4333-8333-333333333333", + "sender_id": "11111111-1111-4111-8111-111111111111", + "text": "Привет, Боб!", + "created_at": "2026-09-01T12:00:00Z" + }, + "MessagePage": { + "items": [ + { + "id": "44444444-4444-4444-8444-444444444444", + "chat_id": "33333333-3333-4333-8333-333333333333", + "sender_id": "11111111-1111-4111-8111-111111111111", + "text": "Привет, Боб!", + "created_at": "2026-09-01T12:00:00Z" + } + ], + "next_cursor": null + }, + "Error": { + "error": { + "code": "not_found", + "message": "Объект не найден", + "request_id": "example-request-id" + } + } +} diff --git a/contracts/infrastructure.json b/contracts/infrastructure.json new file mode 100644 index 0000000..1278ec4 --- /dev/null +++ b/contracts/infrastructure.json @@ -0,0 +1,31 @@ +{ + "lab": 2, + "kind": "requirements, not runnable deployment", + "required_for_grade_3": [ + { + "role": "api", + "count_min": 1, + "student_implements": true, + "persistent_local_state": false + }, + { + "role": "postgres", + "purpose": "users/chats/membership/messages/metadata", + "persistent_volume": true + } + ], + "optional_components": [ + { + "role": "redis_or_valkey", + "required_for_lab2_grade4": true, + "note": "Choose one; if only store of sessions, configure durable persistence." + } + ], + "rules": [ + "Choose Compose or Swarm for lab3+; do not need both.", + "Never publish internal API replica ports in bypass of LB from lab3.", + "Versions/digests must be fixed in implementation.", + "Do not remove volumes in restart/failover checks.", + "Document service names, healthchecks, bootstrap/migrations and credentials." + ] +} diff --git a/contracts/openapi.json b/contracts/openapi.json new file mode 100644 index 0000000..921d32d --- /dev/null +++ b/contracts/openapi.json @@ -0,0 +1,2026 @@ +{ + "openapi": "3.1.0", + "info": { + "title": "MTUSI Messenger — лабораторная 2", + "version": "1.2.0", + "description": "Нормативный минимум на 3. Семантика: contracts/README.md. Расширения на 4/5 не должны менять этот API. Наличие кода ошибки в схеме не требует реализовать факультативную причину его выдачи." + }, + "servers": [ + { + "url": "http://localhost:8080", + "description": "Локальный учебный стенд" + } + ], + "security": [ + { + "bearerAuth": [] + } + ], + "paths": { + "/health/live": { + "get": { + "operationId": "liveness", + "summary": "Процесс жив", + "responses": { + "200": { + "description": "Успех", + "headers": { + "X-Request-Id": { + "description": "Непустой идентификатор запроса; обязателен во всех ответах.", + "schema": { + "type": "string", + "minLength": 1 + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Health" + } + } + } + }, + "500": { + "description": "Неожиданная ошибка без внутренних деталей", + "headers": { + "X-Request-Id": { + "description": "Непустой идентификатор запроса; обязателен во всех ответах.", + "schema": { + "type": "string", + "minLength": 1 + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + }, + "security": [] + } + }, + "/health/ready": { + "get": { + "operationId": "readiness", + "summary": "Готов принимать трафик", + "responses": { + "200": { + "description": "Успех", + "headers": { + "X-Request-Id": { + "description": "Непустой идентификатор запроса; обязателен во всех ответах.", + "schema": { + "type": "string", + "minLength": 1 + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Health" + } + } + } + }, + "503": { + "description": "Зависимость недоступна", + "headers": { + "X-Request-Id": { + "description": "Непустой идентификатор запроса; обязателен во всех ответах.", + "schema": { + "type": "string", + "minLength": 1 + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "500": { + "description": "Неожиданная ошибка без внутренних деталей", + "headers": { + "X-Request-Id": { + "description": "Непустой идентификатор запроса; обязателен во всех ответах.", + "schema": { + "type": "string", + "minLength": 1 + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + }, + "security": [] + } + }, + "/api/v1/users": { + "post": { + "operationId": "registerUser", + "summary": "Создать пользователя", + "responses": { + "201": { + "description": "Успех", + "headers": { + "X-Request-Id": { + "description": "Непустой идентификатор запроса; обязателен во всех ответах.", + "schema": { + "type": "string", + "minLength": 1 + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/User" + } + } + } + }, + "400": { + "description": "Неверный запрос", + "headers": { + "X-Request-Id": { + "description": "Непустой идентификатор запроса; обязателен во всех ответах.", + "schema": { + "type": "string", + "minLength": 1 + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "409": { + "description": "Конфликт", + "headers": { + "X-Request-Id": { + "description": "Непустой идентификатор запроса; обязателен во всех ответах.", + "schema": { + "type": "string", + "minLength": 1 + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "429": { + "description": "Ограничение частоты запросов", + "headers": { + "X-Request-Id": { + "description": "Непустой идентификатор запроса; обязателен во всех ответах.", + "schema": { + "type": "string", + "minLength": 1 + } + }, + "Retry-After": { + "description": "Положительное число секунд.", + "schema": { + "type": "integer", + "minimum": 1 + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "503": { + "description": "Зависимость недоступна", + "headers": { + "X-Request-Id": { + "description": "Непустой идентификатор запроса; обязателен во всех ответах.", + "schema": { + "type": "string", + "minLength": 1 + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "500": { + "description": "Неожиданная ошибка без внутренних деталей", + "headers": { + "X-Request-Id": { + "description": "Непустой идентификатор запроса; обязателен во всех ответах.", + "schema": { + "type": "string", + "minLength": 1 + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + }, + "security": [], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CreateUser" + } + } + } + } + } + }, + "/api/v1/users/me": { + "get": { + "operationId": "currentUser", + "summary": "Текущий пользователь", + "responses": { + "200": { + "description": "Успех", + "headers": { + "X-Request-Id": { + "description": "Непустой идентификатор запроса; обязателен во всех ответах.", + "schema": { + "type": "string", + "minLength": 1 + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/User" + } + } + } + }, + "400": { + "description": "Неверный запрос", + "headers": { + "X-Request-Id": { + "description": "Непустой идентификатор запроса; обязателен во всех ответах.", + "schema": { + "type": "string", + "minLength": 1 + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "401": { + "description": "Нет действительной аутентификации", + "headers": { + "X-Request-Id": { + "description": "Непустой идентификатор запроса; обязателен во всех ответах.", + "schema": { + "type": "string", + "minLength": 1 + } + }, + "WWW-Authenticate": { + "description": "Basic realm=\"messenger\", charset=\"UTF-8\" для входа; Bearer realm=\"messenger\" для защищённого API lab2+.", + "schema": { + "type": "string" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "404": { + "description": "Объект отсутствует или недоступен", + "headers": { + "X-Request-Id": { + "description": "Непустой идентификатор запроса; обязателен во всех ответах.", + "schema": { + "type": "string", + "minLength": 1 + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "409": { + "description": "Конфликт", + "headers": { + "X-Request-Id": { + "description": "Непустой идентификатор запроса; обязателен во всех ответах.", + "schema": { + "type": "string", + "minLength": 1 + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "429": { + "description": "Ограничение частоты запросов", + "headers": { + "X-Request-Id": { + "description": "Непустой идентификатор запроса; обязателен во всех ответах.", + "schema": { + "type": "string", + "minLength": 1 + } + }, + "Retry-After": { + "description": "Положительное число секунд.", + "schema": { + "type": "integer", + "minimum": 1 + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "503": { + "description": "Зависимость недоступна", + "headers": { + "X-Request-Id": { + "description": "Непустой идентификатор запроса; обязателен во всех ответах.", + "schema": { + "type": "string", + "minLength": 1 + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "500": { + "description": "Неожиданная ошибка без внутренних деталей", + "headers": { + "X-Request-Id": { + "description": "Непустой идентификатор запроса; обязателен во всех ответах.", + "schema": { + "type": "string", + "minLength": 1 + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/api/v1/chats": { + "post": { + "operationId": "createChat", + "summary": "Создать чат; вызывающий должен входить в member_ids", + "responses": { + "201": { + "description": "Успех", + "headers": { + "X-Request-Id": { + "description": "Непустой идентификатор запроса; обязателен во всех ответах.", + "schema": { + "type": "string", + "minLength": 1 + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Chat" + } + } + } + }, + "400": { + "description": "Неверный запрос", + "headers": { + "X-Request-Id": { + "description": "Непустой идентификатор запроса; обязателен во всех ответах.", + "schema": { + "type": "string", + "minLength": 1 + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "401": { + "description": "Нет действительной аутентификации", + "headers": { + "X-Request-Id": { + "description": "Непустой идентификатор запроса; обязателен во всех ответах.", + "schema": { + "type": "string", + "minLength": 1 + } + }, + "WWW-Authenticate": { + "description": "Basic realm=\"messenger\", charset=\"UTF-8\" для входа; Bearer realm=\"messenger\" для защищённого API lab2+.", + "schema": { + "type": "string" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "404": { + "description": "Объект отсутствует или недоступен", + "headers": { + "X-Request-Id": { + "description": "Непустой идентификатор запроса; обязателен во всех ответах.", + "schema": { + "type": "string", + "minLength": 1 + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "409": { + "description": "Конфликт", + "headers": { + "X-Request-Id": { + "description": "Непустой идентификатор запроса; обязателен во всех ответах.", + "schema": { + "type": "string", + "minLength": 1 + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "429": { + "description": "Ограничение частоты запросов", + "headers": { + "X-Request-Id": { + "description": "Непустой идентификатор запроса; обязателен во всех ответах.", + "schema": { + "type": "string", + "minLength": 1 + } + }, + "Retry-After": { + "description": "Положительное число секунд.", + "schema": { + "type": "integer", + "minimum": 1 + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "503": { + "description": "Зависимость недоступна", + "headers": { + "X-Request-Id": { + "description": "Непустой идентификатор запроса; обязателен во всех ответах.", + "schema": { + "type": "string", + "minLength": 1 + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "500": { + "description": "Неожиданная ошибка без внутренних деталей", + "headers": { + "X-Request-Id": { + "description": "Непустой идентификатор запроса; обязателен во всех ответах.", + "schema": { + "type": "string", + "minLength": 1 + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + }, + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CreateChat" + } + } + } + } + }, + "get": { + "operationId": "listChats", + "summary": "Чаты текущего пользователя", + "responses": { + "200": { + "description": "Успех", + "headers": { + "X-Request-Id": { + "description": "Непустой идентификатор запроса; обязателен во всех ответах.", + "schema": { + "type": "string", + "minLength": 1 + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ChatPage" + } + } + } + }, + "400": { + "description": "Неверный запрос", + "headers": { + "X-Request-Id": { + "description": "Непустой идентификатор запроса; обязателен во всех ответах.", + "schema": { + "type": "string", + "minLength": 1 + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "401": { + "description": "Нет действительной аутентификации", + "headers": { + "X-Request-Id": { + "description": "Непустой идентификатор запроса; обязателен во всех ответах.", + "schema": { + "type": "string", + "minLength": 1 + } + }, + "WWW-Authenticate": { + "description": "Basic realm=\"messenger\", charset=\"UTF-8\" для входа; Bearer realm=\"messenger\" для защищённого API lab2+.", + "schema": { + "type": "string" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "404": { + "description": "Объект отсутствует или недоступен", + "headers": { + "X-Request-Id": { + "description": "Непустой идентификатор запроса; обязателен во всех ответах.", + "schema": { + "type": "string", + "minLength": 1 + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "409": { + "description": "Конфликт", + "headers": { + "X-Request-Id": { + "description": "Непустой идентификатор запроса; обязателен во всех ответах.", + "schema": { + "type": "string", + "minLength": 1 + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "429": { + "description": "Ограничение частоты запросов", + "headers": { + "X-Request-Id": { + "description": "Непустой идентификатор запроса; обязателен во всех ответах.", + "schema": { + "type": "string", + "minLength": 1 + } + }, + "Retry-After": { + "description": "Положительное число секунд.", + "schema": { + "type": "integer", + "minimum": 1 + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "503": { + "description": "Зависимость недоступна", + "headers": { + "X-Request-Id": { + "description": "Непустой идентификатор запроса; обязателен во всех ответах.", + "schema": { + "type": "string", + "minLength": 1 + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "500": { + "description": "Неожиданная ошибка без внутренних деталей", + "headers": { + "X-Request-Id": { + "description": "Непустой идентификатор запроса; обязателен во всех ответах.", + "schema": { + "type": "string", + "minLength": 1 + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + }, + "parameters": [ + { + "name": "limit", + "in": "query", + "schema": { + "type": "integer", + "minimum": 1, + "maximum": 100, + "default": 50 + } + }, + { + "name": "cursor", + "in": "query", + "schema": { + "type": "string", + "minLength": 1 + } + } + ] + } + }, + "/api/v1/chats/{chat_id}": { + "get": { + "operationId": "getChat", + "summary": "Получить доступный чат", + "responses": { + "200": { + "description": "Успех", + "headers": { + "X-Request-Id": { + "description": "Непустой идентификатор запроса; обязателен во всех ответах.", + "schema": { + "type": "string", + "minLength": 1 + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Chat" + } + } + } + }, + "400": { + "description": "Неверный запрос", + "headers": { + "X-Request-Id": { + "description": "Непустой идентификатор запроса; обязателен во всех ответах.", + "schema": { + "type": "string", + "minLength": 1 + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "401": { + "description": "Нет действительной аутентификации", + "headers": { + "X-Request-Id": { + "description": "Непустой идентификатор запроса; обязателен во всех ответах.", + "schema": { + "type": "string", + "minLength": 1 + } + }, + "WWW-Authenticate": { + "description": "Basic realm=\"messenger\", charset=\"UTF-8\" для входа; Bearer realm=\"messenger\" для защищённого API lab2+.", + "schema": { + "type": "string" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "404": { + "description": "Объект отсутствует или недоступен", + "headers": { + "X-Request-Id": { + "description": "Непустой идентификатор запроса; обязателен во всех ответах.", + "schema": { + "type": "string", + "minLength": 1 + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "409": { + "description": "Конфликт", + "headers": { + "X-Request-Id": { + "description": "Непустой идентификатор запроса; обязателен во всех ответах.", + "schema": { + "type": "string", + "minLength": 1 + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "429": { + "description": "Ограничение частоты запросов", + "headers": { + "X-Request-Id": { + "description": "Непустой идентификатор запроса; обязателен во всех ответах.", + "schema": { + "type": "string", + "minLength": 1 + } + }, + "Retry-After": { + "description": "Положительное число секунд.", + "schema": { + "type": "integer", + "minimum": 1 + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "503": { + "description": "Зависимость недоступна", + "headers": { + "X-Request-Id": { + "description": "Непустой идентификатор запроса; обязателен во всех ответах.", + "schema": { + "type": "string", + "minLength": 1 + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "500": { + "description": "Неожиданная ошибка без внутренних деталей", + "headers": { + "X-Request-Id": { + "description": "Непустой идентификатор запроса; обязателен во всех ответах.", + "schema": { + "type": "string", + "minLength": 1 + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + }, + "parameters": [ + { + "name": "chat_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + } + ] + } + }, + "/api/v1/chats/{chat_id}/messages": { + "post": { + "operationId": "createMessage", + "summary": "Отправить сообщение", + "responses": { + "201": { + "description": "Успех", + "headers": { + "X-Request-Id": { + "description": "Непустой идентификатор запроса; обязателен во всех ответах.", + "schema": { + "type": "string", + "minLength": 1 + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Message" + } + } + } + }, + "400": { + "description": "Неверный запрос", + "headers": { + "X-Request-Id": { + "description": "Непустой идентификатор запроса; обязателен во всех ответах.", + "schema": { + "type": "string", + "minLength": 1 + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "401": { + "description": "Нет действительной аутентификации", + "headers": { + "X-Request-Id": { + "description": "Непустой идентификатор запроса; обязателен во всех ответах.", + "schema": { + "type": "string", + "minLength": 1 + } + }, + "WWW-Authenticate": { + "description": "Basic realm=\"messenger\", charset=\"UTF-8\" для входа; Bearer realm=\"messenger\" для защищённого API lab2+.", + "schema": { + "type": "string" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "404": { + "description": "Объект отсутствует или недоступен", + "headers": { + "X-Request-Id": { + "description": "Непустой идентификатор запроса; обязателен во всех ответах.", + "schema": { + "type": "string", + "minLength": 1 + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "409": { + "description": "Конфликт", + "headers": { + "X-Request-Id": { + "description": "Непустой идентификатор запроса; обязателен во всех ответах.", + "schema": { + "type": "string", + "minLength": 1 + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "429": { + "description": "Ограничение частоты запросов", + "headers": { + "X-Request-Id": { + "description": "Непустой идентификатор запроса; обязателен во всех ответах.", + "schema": { + "type": "string", + "minLength": 1 + } + }, + "Retry-After": { + "description": "Положительное число секунд.", + "schema": { + "type": "integer", + "minimum": 1 + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "503": { + "description": "Зависимость недоступна", + "headers": { + "X-Request-Id": { + "description": "Непустой идентификатор запроса; обязателен во всех ответах.", + "schema": { + "type": "string", + "minLength": 1 + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "500": { + "description": "Неожиданная ошибка без внутренних деталей", + "headers": { + "X-Request-Id": { + "description": "Непустой идентификатор запроса; обязателен во всех ответах.", + "schema": { + "type": "string", + "minLength": 1 + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + }, + "parameters": [ + { + "name": "chat_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CreateMessage" + } + } + } + } + }, + "get": { + "operationId": "listMessages", + "summary": "Сообщения по (created_at, id) по возрастанию", + "responses": { + "200": { + "description": "Успех", + "headers": { + "X-Request-Id": { + "description": "Непустой идентификатор запроса; обязателен во всех ответах.", + "schema": { + "type": "string", + "minLength": 1 + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/MessagePage" + } + } + } + }, + "400": { + "description": "Неверный запрос", + "headers": { + "X-Request-Id": { + "description": "Непустой идентификатор запроса; обязателен во всех ответах.", + "schema": { + "type": "string", + "minLength": 1 + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "401": { + "description": "Нет действительной аутентификации", + "headers": { + "X-Request-Id": { + "description": "Непустой идентификатор запроса; обязателен во всех ответах.", + "schema": { + "type": "string", + "minLength": 1 + } + }, + "WWW-Authenticate": { + "description": "Basic realm=\"messenger\", charset=\"UTF-8\" для входа; Bearer realm=\"messenger\" для защищённого API lab2+.", + "schema": { + "type": "string" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "404": { + "description": "Объект отсутствует или недоступен", + "headers": { + "X-Request-Id": { + "description": "Непустой идентификатор запроса; обязателен во всех ответах.", + "schema": { + "type": "string", + "minLength": 1 + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "409": { + "description": "Конфликт", + "headers": { + "X-Request-Id": { + "description": "Непустой идентификатор запроса; обязателен во всех ответах.", + "schema": { + "type": "string", + "minLength": 1 + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "429": { + "description": "Ограничение частоты запросов", + "headers": { + "X-Request-Id": { + "description": "Непустой идентификатор запроса; обязателен во всех ответах.", + "schema": { + "type": "string", + "minLength": 1 + } + }, + "Retry-After": { + "description": "Положительное число секунд.", + "schema": { + "type": "integer", + "minimum": 1 + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "503": { + "description": "Зависимость недоступна", + "headers": { + "X-Request-Id": { + "description": "Непустой идентификатор запроса; обязателен во всех ответах.", + "schema": { + "type": "string", + "minLength": 1 + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "500": { + "description": "Неожиданная ошибка без внутренних деталей", + "headers": { + "X-Request-Id": { + "description": "Непустой идентификатор запроса; обязателен во всех ответах.", + "schema": { + "type": "string", + "minLength": 1 + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + }, + "parameters": [ + { + "name": "chat_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "name": "limit", + "in": "query", + "schema": { + "type": "integer", + "minimum": 1, + "maximum": 100, + "default": 50 + } + }, + { + "name": "cursor", + "in": "query", + "schema": { + "type": "string", + "minLength": 1 + } + } + ] + } + }, + "/api/v1/auth/sessions": { + "post": { + "operationId": "createSession", + "summary": "Вход: Basic username:password; выдаёт сессию", + "responses": { + "201": { + "description": "Успех", + "headers": { + "X-Request-Id": { + "description": "Непустой идентификатор запроса; обязателен во всех ответах.", + "schema": { + "type": "string", + "minLength": 1 + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Session" + } + } + } + }, + "400": { + "description": "Неверный запрос", + "headers": { + "X-Request-Id": { + "description": "Непустой идентификатор запроса; обязателен во всех ответах.", + "schema": { + "type": "string", + "minLength": 1 + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "401": { + "description": "Нет действительной аутентификации", + "headers": { + "X-Request-Id": { + "description": "Непустой идентификатор запроса; обязателен во всех ответах.", + "schema": { + "type": "string", + "minLength": 1 + } + }, + "WWW-Authenticate": { + "description": "Basic realm=\"messenger\", charset=\"UTF-8\" для входа; Bearer realm=\"messenger\" для защищённого API lab2+.", + "schema": { + "type": "string" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "429": { + "description": "Ограничение частоты запросов", + "headers": { + "X-Request-Id": { + "description": "Непустой идентификатор запроса; обязателен во всех ответах.", + "schema": { + "type": "string", + "minLength": 1 + } + }, + "Retry-After": { + "description": "Положительное число секунд.", + "schema": { + "type": "integer", + "minimum": 1 + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "503": { + "description": "Зависимость недоступна", + "headers": { + "X-Request-Id": { + "description": "Непустой идентификатор запроса; обязателен во всех ответах.", + "schema": { + "type": "string", + "minLength": 1 + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "500": { + "description": "Неожиданная ошибка без внутренних деталей", + "headers": { + "X-Request-Id": { + "description": "Непустой идентификатор запроса; обязателен во всех ответах.", + "schema": { + "type": "string", + "minLength": 1 + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + }, + "security": [ + { + "basicAuth": [] + } + ] + } + }, + "/api/v1/auth/sessions/current": { + "delete": { + "operationId": "revokeSession", + "summary": "Отозвать текущую сессию", + "responses": { + "204": { + "description": "Успех", + "headers": { + "X-Request-Id": { + "description": "Непустой идентификатор запроса; обязателен во всех ответах.", + "schema": { + "type": "string", + "minLength": 1 + } + } + } + }, + "401": { + "description": "Нет действительной аутентификации", + "headers": { + "X-Request-Id": { + "description": "Непустой идентификатор запроса; обязателен во всех ответах.", + "schema": { + "type": "string", + "minLength": 1 + } + }, + "WWW-Authenticate": { + "description": "Basic realm=\"messenger\", charset=\"UTF-8\" для входа; Bearer realm=\"messenger\" для защищённого API lab2+.", + "schema": { + "type": "string" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "429": { + "description": "Ограничение частоты запросов", + "headers": { + "X-Request-Id": { + "description": "Непустой идентификатор запроса; обязателен во всех ответах.", + "schema": { + "type": "string", + "minLength": 1 + } + }, + "Retry-After": { + "description": "Положительное число секунд.", + "schema": { + "type": "integer", + "minimum": 1 + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "503": { + "description": "Зависимость недоступна", + "headers": { + "X-Request-Id": { + "description": "Непустой идентификатор запроса; обязателен во всех ответах.", + "schema": { + "type": "string", + "minLength": 1 + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "500": { + "description": "Неожиданная ошибка без внутренних деталей", + "headers": { + "X-Request-Id": { + "description": "Непустой идентификатор запроса; обязателен во всех ответах.", + "schema": { + "type": "string", + "minLength": 1 + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + } + }, + "components": { + "securitySchemes": { + "basicAuth": { + "type": "http", + "scheme": "basic" + }, + "bearerAuth": { + "type": "http", + "scheme": "bearer", + "bearerFormat": "opaque session token" + } + }, + "schemas": { + "Error": { + "type": "object", + "properties": { + "error": { + "type": "object", + "properties": { + "code": { + "type": "string", + "enum": [ + "invalid_request", + "unauthorized", + "not_found", + "conflict", + "payload_too_large", + "unsupported_media_type", + "rate_limited", + "unavailable", + "internal_error" + ] + }, + "message": { + "type": "string", + "minLength": 1 + }, + "request_id": { + "type": "string", + "minLength": 1 + } + }, + "required": [ + "code", + "message", + "request_id" + ], + "additionalProperties": false + } + }, + "required": [ + "error" + ], + "additionalProperties": false, + "examples": [ + { + "error": { + "code": "not_found", + "message": "Объект не найден", + "request_id": "example-request-id" + } + } + ] + }, + "Health": { + "type": "object", + "properties": { + "status": { + "type": "string", + "enum": [ + "ok" + ] + } + }, + "required": [ + "status" + ], + "additionalProperties": false + }, + "User": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid" + }, + "username": { + "type": "string", + "pattern": "^[a-z0-9_]{3,32}$" + }, + "display_name": { + "type": "string", + "minLength": 1, + "maxLength": 100 + }, + "created_at": { + "type": "string", + "format": "date-time" + } + }, + "required": [ + "id", + "username", + "display_name", + "created_at" + ], + "additionalProperties": false, + "examples": [ + { + "id": "11111111-1111-4111-8111-111111111111", + "username": "alice", + "display_name": "Алиса", + "created_at": "2026-09-01T12:00:00Z" + } + ] + }, + "CreateUser": { + "type": "object", + "properties": { + "username": { + "type": "string", + "pattern": "^[a-z0-9_]{3,32}$" + }, + "display_name": { + "type": "string", + "minLength": 1, + "maxLength": 100 + }, + "password": { + "type": "string", + "minLength": 12, + "maxLength": 128, + "writeOnly": true + } + }, + "required": [ + "username", + "display_name", + "password" + ], + "additionalProperties": false, + "examples": [ + { + "username": "alice", + "display_name": "Алиса", + "password": "Example-only-not-a-real-secret-123" + } + ] + }, + "Chat": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid" + }, + "title": { + "type": "string", + "minLength": 1, + "maxLength": 100 + }, + "member_ids": { + "type": "array", + "items": { + "type": "string", + "format": "uuid" + }, + "minItems": 1, + "maxItems": 100, + "uniqueItems": true + }, + "created_at": { + "type": "string", + "format": "date-time" + } + }, + "required": [ + "id", + "title", + "member_ids", + "created_at" + ], + "additionalProperties": false, + "examples": [ + { + "title": "Проект по ВНП", + "member_ids": [ + "11111111-1111-4111-8111-111111111111", + "22222222-2222-4222-8222-222222222222" + ], + "id": "33333333-3333-4333-8333-333333333333", + "created_at": "2026-09-01T12:00:00Z" + } + ] + }, + "CreateChat": { + "type": "object", + "properties": { + "title": { + "type": "string", + "minLength": 1, + "maxLength": 100 + }, + "member_ids": { + "type": "array", + "items": { + "type": "string", + "format": "uuid" + }, + "minItems": 1, + "maxItems": 100, + "uniqueItems": true + } + }, + "required": [ + "title", + "member_ids" + ], + "additionalProperties": false, + "examples": [ + { + "title": "Проект по ВНП", + "member_ids": [ + "11111111-1111-4111-8111-111111111111", + "22222222-2222-4222-8222-222222222222" + ] + } + ] + }, + "Message": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid" + }, + "chat_id": { + "type": "string", + "format": "uuid" + }, + "sender_id": { + "type": "string", + "format": "uuid" + }, + "text": { + "type": "string", + "minLength": 1, + "maxLength": 4000 + }, + "created_at": { + "type": "string", + "format": "date-time" + } + }, + "required": [ + "id", + "chat_id", + "sender_id", + "text", + "created_at" + ], + "additionalProperties": false, + "examples": [ + { + "id": "44444444-4444-4444-8444-444444444444", + "chat_id": "33333333-3333-4333-8333-333333333333", + "sender_id": "11111111-1111-4111-8111-111111111111", + "text": "Привет, Боб!", + "created_at": "2026-09-01T12:00:00Z" + } + ] + }, + "CreateMessage": { + "type": "object", + "properties": { + "text": { + "type": "string", + "minLength": 1, + "maxLength": 4000 + } + }, + "required": [ + "text" + ], + "additionalProperties": false, + "examples": [ + { + "text": "Привет, Боб!" + } + ] + }, + "ChatPage": { + "type": "object", + "properties": { + "items": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Chat" + } + }, + "next_cursor": { + "type": [ + "string", + "null" + ] + } + }, + "required": [ + "items", + "next_cursor" + ], + "additionalProperties": false + }, + "MessagePage": { + "type": "object", + "properties": { + "items": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Message" + } + }, + "next_cursor": { + "type": [ + "string", + "null" + ] + } + }, + "required": [ + "items", + "next_cursor" + ], + "additionalProperties": false, + "examples": [ + { + "items": [ + { + "id": "44444444-4444-4444-8444-444444444444", + "chat_id": "33333333-3333-4333-8333-333333333333", + "sender_id": "11111111-1111-4111-8111-111111111111", + "text": "Привет, Боб!", + "created_at": "2026-09-01T12:00:00Z" + } + ], + "next_cursor": null + } + ] + }, + "Session": { + "type": "object", + "properties": { + "token": { + "type": "string", + "minLength": 32 + }, + "token_type": { + "type": "string", + "const": "Bearer" + }, + "expires_at": { + "type": "string", + "format": "date-time" + }, + "user": { + "$ref": "#/components/schemas/User" + } + }, + "required": [ + "token", + "token_type", + "expires_at", + "user" + ], + "additionalProperties": false + } + } + } +} diff --git a/evidence/README.md b/evidence/README.md new file mode 100644 index 0000000..8df7001 --- /dev/null +++ b/evidence/README.md @@ -0,0 +1,5 @@ +# Доказательства + +Храните небольшие обезличенные результаты: команды и stdout проверок, JSON/CSV агрегатов нагрузки, EXPLAIN, dashboard JSON, текст разбора отказа. Укажите дату, commit, аппаратные лимиты и профиль нагрузки. + +Не добавляйте .env, session tokens, cookies, приватные ключи, credentials, реальные сообщения, raw dumps и signed URLs. Для скриншотов скрывайте секреты. Большие логи/бинарные traces сохраняйте отдельно по правилам преподавателя; одного скриншота без методики недостаточно. diff --git a/evidence/cache-role.txt b/evidence/cache-role.txt new file mode 100644 index 0000000..1563abd --- /dev/null +++ b/evidence/cache-role.txt @@ -0,0 +1,9 @@ +# Роль Redis/Valkey: read-through кэш сессий (источник истины — PostgreSQL) +число ключей sess:v1:*: 3 +пример ключа (хеш токена, не токен): sess:v1:db24de3dbb236846... +PTTL, мс (≤ SESSION_CACHE_TTL_SECONDS*1000 = 60000): 44231 +поля значения: ['exp', 'user'] / user: ['created_at', 'display_name', 'id', 'username'] +есть ли password/hash/token в значении: False +после logout значение ключа (tombstone): revoked +после FLUSHALL ключей: 0 +сессия работает после FLUSHALL (из PostgreSQL), кэш наполнился заново, ключей: 1 diff --git a/evidence/dependency-failure.txt b/evidence/dependency-failure.txt new file mode 100644 index 0000000..2798c6d --- /dev/null +++ b/evidence/dependency-failure.txt @@ -0,0 +1,11 @@ +# Зависимости: Redis (кэш сессий) и PostgreSQL; команды управления — песочничные (в стенде — docker compose stop/start) +1) Valkey остановлен + $ CACHE_STOP + $ CACHE_START +2) Кэш сброшен (FLUSHALL): сессии берутся из PostgreSQL + $ CACHE_FLUSH +3) PostgreSQL остановлен + $ DB_STOP + $ DB_START +4) Восстановление +PASS: кэш и БД отказывают предсказуемо: кэш обходится, БД -> 503, анонимный доступ невозможен, данные и сессии целы diff --git a/evidence/explain-history.txt b/evidence/explain-history.txt new file mode 100644 index 0000000..cbd3eaa --- /dev/null +++ b/evidence/explain-history.txt @@ -0,0 +1,85 @@ +rows total=100000, rows in target chat=20000, page=50 +PostgreSQL 16.15 (Ubuntu 16.15-0ubuntu0.24.04.1) on x86_64-pc-linux-gnu, compiled by gcc (Ubuntu 13.3.0-6ubuntu2~24.04.1) 13.3.0, 64-bit + +==================================================================================================== +A. Первая страница, keyset, С индексом (chat_id, created_at, id) +==================================================================================================== +Limit (cost=0.42..14.81 rows=51 width=69) (actual time=0.010..0.021 rows=51 loops=1) + Buffers: shared hit=4 + -> Index Scan using messages_chat_created_id_idx on messages (cost=0.42..5670.87 rows=20093 width=69) (actual time=0.009..0.016 rows=51 loops=1) + Index Cond: (chat_id = '010619e6-7ff5-46b1-877c-03368e85f10b'::uuid) + Buffers: shared hit=4 +Planning: + Buffers: shared hit=6 +Planning Time: 0.063 ms +Execution Time: 0.032 ms + +==================================================================================================== +B. Страница на глубине ~15 000, keyset, С индексом +==================================================================================================== +Limit (cost=0.42..48.66 rows=51 width=69) (actual time=0.011..0.021 rows=51 loops=1) + Buffers: shared hit=4 + -> Index Scan using messages_chat_created_id_idx on messages (cost=0.42..4756.71 rows=5028 width=69) (actual time=0.011..0.016 rows=51 loops=1) + Index Cond: ((chat_id = '010619e6-7ff5-46b1-877c-03368e85f10b'::uuid) AND (ROW(created_at, id) > ROW('2026-01-01 20:50:05.000522+00'::timestamp with time zone, 'f47f8dd1-aaae-4701-a00d-6e20a06648e3'::uuid))) + Buffers: shared hit=4 +Planning Time: 0.059 ms +Execution Time: 0.044 ms + +==================================================================================================== +C. Та же страница, keyset, БЕЗ индекса (индекс удалён в откатываемой транзакции) +==================================================================================================== +Limit (cost=3152.74..3152.87 rows=51 width=69) (actual time=9.057..9.066 rows=51 loops=1) + Buffers: shared hit=1235 + -> Sort (cost=3152.74..3165.31 rows=5028 width=69) (actual time=9.056..9.060 rows=51 loops=1) + Sort Key: created_at, id + Sort Method: top-N heapsort Memory: 31kB + Buffers: shared hit=1235 + -> Seq Scan on messages (cost=0.00..2985.00 rows=5028 width=69) (actual time=1.098..8.625 rows=4999 loops=1) + Filter: ((chat_id = '010619e6-7ff5-46b1-877c-03368e85f10b'::uuid) AND (ROW(created_at, id) > ROW('2026-01-01 20:50:05.000522+00'::timestamp with time zone, 'f47f8dd1-aaae-4701-a00d-6e20a06648e3'::uuid))) + Rows Removed by Filter: 95001 + Buffers: shared hit=1235 +Planning: + Buffers: shared hit=4 +Planning Time: 0.065 ms +Execution Time: 9.081 ms + +==================================================================================================== +D. Та же глубина через OFFSET 15000, С индексом (антипример) +==================================================================================================== +Limit (cost=3958.59..3958.71 rows=51 width=69) (actual time=10.512..10.519 rows=51 loops=1) + Buffers: shared hit=1235 + -> Sort (cost=3921.09..3971.32 rows=20093 width=69) (actual time=9.103..9.920 rows=15051 loops=1) + Sort Key: created_at, id + Sort Method: quicksort Memory: 3271kB + Buffers: shared hit=1235 + -> Seq Scan on messages (cost=0.00..2485.00 rows=20093 width=69) (actual time=0.003..6.416 rows=20000 loops=1) + Filter: (chat_id = '010619e6-7ff5-46b1-877c-03368e85f10b'::uuid) + Rows Removed by Filter: 80000 + Buffers: shared hit=1235 +Planning: + Buffers: shared hit=22 +Planning Time: 0.101 ms +Execution Time: 10.643 ms + +==================================================================================================== +E. Первая страница, БЕЗ индекса +==================================================================================================== +Limit (cost=3155.35..3155.47 rows=51 width=69) (actual time=7.702..7.709 rows=51 loops=1) + Buffers: shared hit=1235 + -> Sort (cost=3155.35..3205.58 rows=20093 width=69) (actual time=7.701..7.704 rows=51 loops=1) + Sort Key: created_at, id + Sort Method: top-N heapsort Memory: 31kB + Buffers: shared hit=1235 + -> Seq Scan on messages (cost=0.00..2485.00 rows=20093 width=69) (actual time=0.004..6.070 rows=20000 loops=1) + Filter: (chat_id = '010619e6-7ff5-46b1-877c-03368e85f10b'::uuid) + Rows Removed by Filter: 80000 + Buffers: shared hit=1235 +Planning: + Buffers: shared hit=4 +Planning Time: 0.060 ms +Execution Time: 7.721 ms + +Индексы messages: + messages_chat_created_id_idx -> CREATE INDEX messages_chat_created_id_idx ON public.messages USING btree (chat_id, created_at, id) + messages_pkey -> CREATE UNIQUE INDEX messages_pkey ON public.messages USING btree (id) +Размер индекса: 8536 kB ; таблицы: 9880 kB diff --git a/evidence/migrations-my.txt b/evidence/migrations-my.txt new file mode 100644 index 0000000000000000000000000000000000000000..f69a0383d97f859ee4e81ede2b6f6429851c576d GIT binary patch literal 928 zcmd6lPfG$}5XPUwo`Sx^9TrD*5`%foadUo#jMQU`h|#e7YB9$!r1&zf0rUL^E_D@**Q|)_UH`=_BCD2}Y1XD1 zmR&;JbFI`Rs}cJG^K-R2_jp_C7F}bqPhH6vHSBHA`F`($T$8`6-GqBdB-TTTN-*B( zL1orH9;fa-R!48HeFipHd^@jesyV?{x?vZw`;N5(|J?KK5_#UgJ=YRb@21W2-(l;Hl{t9gcL$Tmwm({>J a+H_rz?b!2=IH#OLvdWkXTwcYJcia~n$)9}y literal 0 HcmV?d00001 diff --git a/evidence/migrations.txt b/evidence/migrations.txt new file mode 100644 index 0000000..6f9b1ff --- /dev/null +++ b/evidence/migrations.txt @@ -0,0 +1,22 @@ +# Миграции с нуля и повторный запуск (песочница, PostgreSQL 16) +$ python -m app.migrate (запуск 1) +2026-10-15 09:56:03,651 migrate applied: 0001_core, 0002_sessions +$ python -m app.migrate (запуск 2) +2026-10-15 09:56:03,862 migrate applied: nothing to do (schema is up to date) + version | checksum +---------------+-------------- + 0001_core | 5cc38bccb02e + 0002_sessions | 6ef657d22fa7 +(2 rows) + + List of relations + Schema | Name | Type | Owner +--------+-------------------+-------+----------- + public | chat_members | table | messenger + public | chats | table | messenger + public | messages | table | messenger + public | schema_migrations | table | messenger + public | sessions | table | messenger + public | users | table | messenger +(6 rows) + diff --git a/evidence/persistence-my.txt b/evidence/persistence-my.txt new file mode 100644 index 0000000..6efd8fc --- /dev/null +++ b/evidence/persistence-my.txt @@ -0,0 +1,15 @@ +=== Persistence on Docker Compose (Windows 11 + Docker Desktop) === +Дата: 2026-10-16 19:28 + +Шаги: +1. POST /api/v1/users (username=persist, password 12+) -> 201 +2. POST /api/v1/auth/sessions (Basic) -> 201, получен Bearer-токен +3. GET /api/v1/users/me с Bearer -> 200 OK (username=persist) +4. docker compose stop api valkey postgres +5. docker compose up -d -> migrate пропустил миграции, api healthy +6. GET /api/v1/users/me тем же Bearer-токеном ПОСЛЕ рестарта -> 200 OK + +Вывод: PostgreSQL сохранил данные в volume pgdata. +Valkey-кэш потерян (RAM), но при промахе сессия читается из PostgreSQL. +Пользователи, сообщения и действующие сессии переживают полный рестарт +всех хранилищ без удаления volumes. diff --git a/evidence/persistence-restart.txt b/evidence/persistence-restart.txt new file mode 100644 index 0000000..f5d8fb4 --- /dev/null +++ b/evidence/persistence-restart.txt @@ -0,0 +1,14 @@ +# Сохранность при полном рестарте (песочничный hook: API (uvicorn, 2 процесса) + PostgreSQL + Redis, данные на диске сохраняются) +== before == +postgres postmaster_start=2026-10-15 21:38:10.905693+00 +redis uptime_s=73 +api master_pid=197 +rows users=127 messages=1242 sessions=52 +== make test-persistence == +Executing explicit persistence hook; hook output suppressed to avoid leaking secrets. +PASS: persistence preserved confirmed data and existing session. Hook scope needs operator evidence. +== after == +postgres postmaster_start=2026-10-15 21:39:16.659936+00 +redis uptime_s=2 +api master_pid=587 +rows users=130 messages=1243 sessions=55 diff --git a/evidence/test-results.txt b/evidence/test-results.txt new file mode 100644 index 0000000..114f872 --- /dev/null +++ b/evidence/test-results.txt @@ -0,0 +1,47 @@ +# Среда: песочница без Docker. PostgreSQL 16.15, Redis 7 (вместо Valkey), Python 3.12.3, FastAPI 0.115.0 + uvicorn 0.30.6 (2 процесса), 2026-10-15T21:39:00Z +# Compose-стенд в этой среде не запускался (нет Docker) — см. REPORT.md, «Ограничения проверки». + +$ make check +PASS: offline skeleton structure, local refs and Python syntax; application NOT tested. + +$ make test +PASS: lab2 public API scenario; infrastructure and grading evidence remain separate. + +$ python3 tests_student/test_integration.py +PASS registration_race_same_username +PASS username_and_field_validation +PASS password_with_colon_and_unicode_login +PASS login_failures_look_identical +PASS bearer_rules +PASS logout_revokes_only_that_session +PASS chat_creation_rules_and_no_side_effects +PASS message_rules +PASS pagination_walk_and_cursor_binding +PASS chat_list_pagination_and_order +PASS request_id_and_error_shape + +11/11 passed + +$ pytest tests/test_own.py tests/test_race.py -v +test_own.py::test_invalid_json PASSED +test_own.py::test_duplicate_username PASSED +test_own.py::test_extra_fields PASSED +test_own.py::test_empty_message PASSED +test_own.py::test_foreign_chat PASSED +test_own.py::test_pagination PASSED +test_own.py::test_cursor_from_other_chat_is_400 PASSED +test_own.py::test_x_user_id_no_longer_grants_access PASSED +test_own.py::test_basic_only_on_login PASSED +test_own.py::test_wrong_password_and_unknown_user_look_the_same PASSED +test_own.py::test_logout_revokes_token PASSED +test_own.py::test_password_is_never_returned PASSED +test_own.py::test_short_password_rejected PASSED +test_race.py::test_concurrent_writes PASSED +test_race.py::test_concurrent_registration_same_username PASSED +============================== 15 passed in 1.28s ============================== + +$ python tests_student/test_db_rollback.py +PASS: ошибка внутри транзакции откатила вставку chats (0 строк), контрольный commit сохранил чат и участника + +$ SESSION_TTL_SECONDS=2 (API на :8081) python tests_student/test_expiry.py 2 +PASS: сессия с TTL=2.0s перестала действовать (401 на users/me, chats, logout) после ожидания 3.5s diff --git a/evidence/tests-deps-my.txt b/evidence/tests-deps-my.txt new file mode 100644 index 0000000000000000000000000000000000000000..9febf10e43f74a12083b3a624990fb8d7e35f9d7 GIT binary patch literal 176 zcmZvVs}90Y5JV5jC=x9Cl3omB8GUvvyUK^mJS}ac0mrzVE16`Dbr$9T|oDe@|d* aEi-?lHt$peWFTdNNX;ItEYsTx9rPN!-|NB3V~YASbLnf zlDELqa_7x$&9f)k*tvn#1398`)K!aGPjs}ZfD3({RyAcDaV4U@l!S7YlT1~iHJksf z@}^v}yLC_!Pvj8e(u*VWfg`Y=k-Igw?pC@DQ`3F_*OBgJ$@Nx!=5Dmyw)^mwYNi9_ zv!@5W0?o%e<mGEApVU<+Vo~2E4b=~;pKM8rjPZB$FaCK9M4AYxRH{(t0U9}CH1`g15A>Nnsk3cA*uMAV z=^bOkU|P!Tf?e;vf(DdQNeLB=Z-WdHe~>G``05i(kLV%Y!dg;Jk`(@3);h;hY+B_5 zdQLua|BfHhh}=tjjOaPUr)gugJ=kQC1FdB>eqBw?N9Z!a+VYp{>Cpfl1!fM$Y+|%= zmgN7N-EB;72l>~XUB|CGyN+LXb{+q>v+LeOOd$=)Lx%&1MZ2_x+j3wBuzcLHgbpFQ cbPYOb_#xTYci^|MdmZ-V!o74g{`=TJ0Mf|s&j0`b literal 0 HcmV?d00001 diff --git a/evidence/track2-restore.json b/evidence/track2-restore.json new file mode 100644 index 0000000..e17af13 --- /dev/null +++ b/evidence/track2-restore.json @@ -0,0 +1,61 @@ +{ + "snapshot_consistent_with_restore": true, + "checks": { + "counts": true, + "messages_md5": true, + "per_chat_counts_md5": true, + "indexes_md5": true, + "constraints_md5": true, + "migrations": true, + "selected_messages": { + "first_overall": true, + "last_overall": true, + "giant_chat_item_15000": true, + "longest_text": true, + "shortest_text": true, + "pseudo_random_by_md5": true + } + }, + "rpo_window_observed": { + "messages_lost_in_restore": 500, + "revoked_session_resurrected_in_restore": true + }, + "timing_seconds": { + "pg_dump": 0.76, + "pg_restore": 1.34, + "analyze_after_restore": 0.21, + "rto_dump_free_restore_plus_analyze": 1.56 + }, + "sizes_bytes": { + "source_database": 68688919, + "dump_file": 3615536 + }, + "counts_at_dump": { + "users": 1, + "chats": 563, + "chat_members": 563, + "messages": 102000, + "sessions": 1 + }, + "counts_restored": { + "users": 1, + "chats": 563, + "chat_members": 563, + "messages": 102000, + "sessions": 1 + }, + "counts_source_after_extra_writes": { + "users": 1, + "chats": 563, + "chat_members": 563, + "messages": 102500, + "sessions": 0 + }, + "restored_plan": { + "first_page_giant": { + "node": "Index Scan", + "index": "messages_chat_created_id_idx", + "execution_ms": 0.066 + } + } +} diff --git a/evidence/track2-restored-app.txt b/evidence/track2-restored-app.txt new file mode 100644 index 0000000..5f1bb15 --- /dev/null +++ b/evidence/track2-restored-app.txt @@ -0,0 +1,8 @@ +# Восстановленная БД (новый сервер :5434) обслуживает приложение +$ python -m app.migrate (на восстановленной БД) +2026-10-15 10:08:21,788 migrate applied: nothing to do (schema is up to date) +$ make test BASE_URL=http://localhost:8082 (API подключён к восстановленной БД, без Valkey) +PASS: lab2 public API scenario; infrastructure and grading evidence remain separate. +$ python3 tests_student/test_integration.py (против восстановленной БД) + +11/11 passed diff --git a/evidence/track2-summary.md b/evidence/track2-summary.md new file mode 100644 index 0000000..5eff552 --- /dev/null +++ b/evidence/track2-summary.md @@ -0,0 +1,23 @@ +# Трек 2: сводка (медианы двух проходов; p50 клиентской латентности, мс) + +Данные: 100 000 сообщений + 2 000 одиночных вставок = ~102 000; 563 чата (50k/20k/10k/10×1k/50×100/500×10); PostgreSQL 16.15, 1 CPU, fsync=on. + +## Чтение (p50, мс; проход 1 / проход 2) + +| Конфигурация | Q1 first_page_giant_50k | Q2 deep_keyset_giant_at_40k | Q3 first_page_tiny_10 | Q4 keyset_mid_1k_at_500 | Q5 OFFSET_40000_giant | +|---|---|---|---|---|---| +| C0_pk_only | 19.01 / 26.85 (Seq, 6124 buf) | 36.20 / 33.11 (Seq, 6066 buf) | 14.85 / 16.60 (Seq, 6036 buf) | 36.26 / 21.05 (Seq, 6036 buf) | 47.97 / 45.41 (Seq, 6124 buf) | +| C1_chat_id | 16.09 / 8.12 (Seq, 6124 buf) | 11.78 / 8.10 (Bitmap Index, 3140 buf) | 0.16 / 0.14 (Index, 5 buf) | 0.68 / 0.64 (Bitmap Index, 88 buf) | 37.92 / 36.04 (Seq, 6124 buf) | +| C2_chat_created_id | 0.45 / 0.21 (Index, 7 buf) | 0.48 / 0.33 (Index, 9 buf) | 0.15 / 0.12 (Index, 6 buf) | 0.24 / 0.30 (Index, 9 buf) | 38.96 / 40.25 (Seq, 6124 buf) | +| C3_covering_include | 0.48 / 0.21 (IdxOnly, 6 buf) | 0.25 / 0.33 (IdxOnly, 6 buf) | 0.08 / 0.08 (IdxOnly, 4 buf) | 0.24 / 0.33 (IdxOnly, 7 buf) | 4.71 / 4.34 (IdxOnly, 1472 buf) | +| C4_global_created_id | 1.57 / 2.97 (Index, 5491 buf) | 0.48 / 0.38 (Index, 8 buf) | 33.16 / 25.69 (Seq, 6036 buf) | 0.42 / 0.51 (Index, 669 buf) | 42.82 / 41.86 (Seq, 6124 buf) | + +## Запись и размер + +| Конфигурация | bulk 100k, с (п1 / п2) | одиночный INSERT p50, мс (п1 / п2) | p95, мс (п1 / п2) | индекс истории, MiB | +|---|---|---|---|---| +| C0_pk_only | 1.18 / 1.10 | 0.70 / 0.85 | 1.62 / 1.62 | 0.0 | +| C1_chat_id | 1.34 / 1.34 | 0.94 / 0.57 | 2.86 / 0.95 | 0.9 | +| C2_chat_created_id | 1.25 / 1.20 | 0.71 / 0.76 | 1.22 / 1.32 | 7.7 | +| C3_covering_include | 1.60 / 1.42 | 0.46 / 0.51 | 0.84 / 0.92 | 39.6 | +| C4_global_created_id | 1.46 / 1.15 | 0.41 / 0.63 | 0.90 / 1.13 | 4.9 | diff --git a/examples/requests.http b/examples/requests.http new file mode 100644 index 0000000..336c50e --- /dev/null +++ b/examples/requests.http @@ -0,0 +1,45 @@ +# Optional HTTP-client worksheet; no extension is required by the course. +# Replace IDs/token locally from real responses; do not commit filled-in credentials. +# Canonical API: contracts/openapi.json and contracts/README.md. +@baseUrl = http://localhost:8080 +@aliceId = REPLACE_WITH_CREATED_ALICE_UUID +@bobId = REPLACE_WITH_CREATED_BOB_UUID +@chatId = REPLACE_WITH_CREATED_CHAT_UUID +@sessionToken = REPLACE_LOCALLY_DO_NOT_COMMIT + +### Liveness +GET {{baseUrl}}/health/live + +### Register Alice (repeat with username bob/display_name Боб) +POST {{baseUrl}}/api/v1/users +Content-Type: application/json + +{ + "username": "alice", + "display_name": "Алиса", + "password": "Example-only-not-a-real-secret-123" +} + +### Create session: generate the Base64 value locally, do not commit credentials +# Base64 of UTF-8 username:password; only this endpoint accepts Basic. +POST {{baseUrl}}/api/v1/auth/sessions +Authorization: Basic REPLACE_WITH_LOCAL_BASE64_CREDENTIAL + + +### Create chat; both UUIDs must be real registered users +POST {{baseUrl}}/api/v1/chats +Authorization: Bearer {{sessionToken}} +Content-Type: application/json + +{"title":"Проект по ВНП","member_ids":["{{aliceId}}","{{bobId}}"]} + +### Send message +POST {{baseUrl}}/api/v1/chats/{{chatId}}/messages +Authorization: Bearer {{sessionToken}} +Content-Type: application/json + +{"text":"Привет, Боб!"} + +### Read first page +GET {{baseUrl}}/api/v1/chats/{{chatId}}/messages?limit=50 +Authorization: Bearer {{sessionToken}} diff --git a/infra/README.md b/infra/README.md new file mode 100644 index 0000000..5a39e86 --- /dev/null +++ b/infra/README.md @@ -0,0 +1,7 @@ +# Инфраструктура студента + +Здесь разместите конфигурации выбранных сервисов; основную топологию — в корневом compose.yaml/stack.yaml. `compose.example.yaml` — только worksheet ролей и намеренно не запускается. `contracts/infrastructure.json` задаёт минимальные роли, не готовые образы/пароли. + +В REPORT.md сопоставьте роль → service name → версия/digest → health/readiness → volume → сеть/порт → способ передачи credentials. Приведите bootstrap (schema, bucket, broker topology, а с lab6 provisioning) и безопасное повторение этих команд. + +Приложение строится из исходников. Не используйте заранее существующий образ преподавательского сервера вместо своей реализации. Restart hook перезапускает все соответствующие stores с volumes; failover hook останавливает только заданную API-реплику. diff --git a/lab.json b/lab.json new file mode 100644 index 0000000..a618cd3 --- /dev/null +++ b/lab.json @@ -0,0 +1,8 @@ +{ + "number": 2, + "title": "PostgreSQL, сессии и Redis/Valkey", + "contract_version": "1.2.0", + "default_base_url": "http://localhost:8080", + "grading": "3; 4 includes 3; 5 includes 4 plus one completed research track", + "scaffold_has_application": false +} diff --git a/main.py b/main.py new file mode 100644 index 0000000..1198be9 --- /dev/null +++ b/main.py @@ -0,0 +1,259 @@ +"""Мессенджер, лабораторная 2: PostgreSQL + сессии (Bearer) + Valkey/Redis как кэш сессий. + +Развитие main.py из lab1 (FastAPI/Uvicorn): те же маршруты, тот же формат ошибок, middleware X-Request-Id. +Изменилось: вместо словарей в памяти — PostgreSQL (app/repo.py), вместо X-User-Id — Bearer-сессия +(app/sessions.py), вход — Basic на POST /auth/sessions, пароли — Argon2id (app/security.py). +""" +import logging +import re +import uuid +from contextlib import asynccontextmanager +from typing import NamedTuple + +import anyio.to_thread +import psycopg +from fastapi import Depends, FastAPI, Request +from fastapi.exceptions import RequestValidationError +from fastapi.responses import JSONResponse, Response +from starlette.exceptions import HTTPException as StarletteHTTPException + +from app import config, cursor, db, repo, security, sessions, validation +from app.errors import BASIC_CHALLENGE, BEARER_CHALLENGE, ApiError, bad_request, not_found, unauthorized + +logging.basicConfig(level=logging.INFO, format="%(asctime)s %(levelname)s %(name)s %(message)s") +log = logging.getLogger("api") + +_REQUEST_ID_RE = re.compile(r"[A-Za-z0-9._-]{1,64}") + + +@asynccontextmanager +async def lifespan(_app): + # Sync-обработчики FastAPI идут в пул потоков; ограничиваем его, чтобы очередь ждала в потоках, а не в пуле БД. + anyio.to_thread.current_default_thread_limiter().total_tokens = config.THREAD_LIMIT + yield + db.close() # SIGTERM: корректно закрываем соединения PostgreSQL + + +# Автодокументация FastAPI отключена: контракт — contracts/openapi.json. +app = FastAPI(lifespan=lifespan, docs_url=None, redoc_url=None, openapi_url=None) + + +# ---------- X-Request-Id, ошибки (как в lab1) ---------- +def make_error(code, message, request_id): + return {"error": {"code": code, "message": message, "request_id": request_id}} + + +def _rid(request): + return getattr(request.state, "request_id", None) or uuid.uuid4().hex + + +def error_response(request, status, code, message, headers=None): + rid = _rid(request) + out = {"X-Request-Id": rid, "Cache-Control": "no-store"} # заголовок и в ответах, минующих middleware (500) + out.update(headers or {}) + return JSONResponse(status_code=status, content=make_error(code, message, rid), headers=out) + + +@app.middleware("http") +async def add_request_id(request: Request, call_next): + incoming = request.headers.get("X-Request-Id", "") + rid = incoming if _REQUEST_ID_RE.fullmatch(incoming) else uuid.uuid4().hex # чужое значение — только безопасное + request.state.request_id = rid + response = await call_next(request) + response.headers["X-Request-Id"] = rid + response.headers["Cache-Control"] = "no-store" + return response + + +@app.exception_handler(ApiError) +async def api_error_handler(request: Request, exc: ApiError): + return error_response(request, exc.status, exc.code, exc.message, exc.headers) + + +@app.exception_handler(RequestValidationError) +async def validation_handler(request: Request, exc): + return error_response(request, 400, "invalid_request", "Некорректный запрос") + + +@app.exception_handler(StarletteHTTPException) +async def http_exc_handler(request: Request, exc: StarletteHTTPException): + mapping = {404: ("not_found", "Объект не найден"), 405: ("invalid_request", "Метод не поддерживается")} + code, message = mapping.get(exc.status_code, ("invalid_request", "Ошибка запроса")) + return error_response(request, exc.status_code, code, message) + + +@app.exception_handler(Exception) +async def generic_handler(request: Request, exc: Exception): + if isinstance(exc, db.TRANSIENT): + # PostgreSQL недоступен/перегружен: ограниченный ответ без деталей. + log.warning("dependency unavailable [%s]: %s", _rid(request), type(exc).__name__) + return error_response(request, 503, "unavailable", "Сервис временно недоступен") + log.error("unhandled error [%s]", _rid(request), exc_info=exc) # стек — только в серверный лог + return error_response(request, 500, "internal_error", "Внутренняя ошибка сервера") + + +# ---------- аутентификация (вместо X-User-Id из lab1) ---------- +class Auth(NamedTuple): + user: dict + user_id: uuid.UUID + digest: bytes + + +def authenticated(request: Request) -> Auth: + """Bearer-токен -> сессия -> пользователь. Basic, X-User-Id и любые другие схемы дают 401.""" + token = security.parse_bearer(request.headers.get("Authorization")) + if token is None: + raise unauthorized(BEARER_CHALLENGE) + found = sessions.lookup(token) # Valkey -> PostgreSQL; БД недоступна -> 503 в generic_handler + if found is None: + raise unauthorized(BEARER_CHALLENGE) + return Auth(found["user"], uuid.UUID(found["user"]["id"]), found["digest"]) + + +class RawBody(NamedTuple): + content_type: str + data: bytes + + +async def raw_body(request: Request) -> RawBody: + """Читает тело с жёстким лимитом (в т.ч. для chunked) -> 413. Разбор JSON — позже, после проверки доступа.""" + declared = request.headers.get("content-length") + if declared is not None and declared.isdigit() and int(declared) > config.MAX_BODY_BYTES: + raise ApiError(413, "payload_too_large", "Тело запроса слишком большое") + chunks, size = [], 0 + async for chunk in request.stream(): + size += len(chunk) + if size > config.MAX_BODY_BYTES: + raise ApiError(413, "payload_too_large", "Тело запроса слишком большое") + chunks.append(chunk) + return RawBody(request.headers.get("content-type", ""), b"".join(chunks)) + + +# ---------- health ---------- +@app.get("/health/live") +def live(): + return {"status": "ok"} + + +@app.get("/health/ready") +def ready(): + db.ping() # критичная зависимость — PostgreSQL; недоступность кэша НЕ делает сервис неготовым + return {"status": "ok"} + + +# ---------- пользователи ---------- +@app.post("/api/v1/users", status_code=201) +def create_user(body: RawBody = Depends(raw_body)): + data = validation.json_body(body.content_type, body.data, + {"username", "display_name", "password"}, {"username", "display_name", "password"}) + username = validation.username_field(data["username"]) + display_name = validation.text_field(data["display_name"], "display_name", 1, 100) + password = validation.text_field(data["password"], "password", 12, 128) + with db.connection() as conn: # быстрый путь: не тратим Argon2 на заведомый дубль + if repo.username_exists(conn, username): + raise ApiError(409, "conflict", "Имя пользователя занято") + password_hash = security.hash_password(password) # тяжёлая CPU-операция — вне транзакции и без занятого соединения + try: + with db.connection() as conn: + row = repo.insert_user(conn, username, display_name, password_hash) + except psycopg.errors.UniqueViolation: # гонку двух регистраций решает UNIQUE в БД, а не проверка выше + raise ApiError(409, "conflict", "Имя пользователя занято") + return sessions.user_json(row) + + +@app.get("/api/v1/users/me") +def get_me(auth: Auth = Depends(authenticated)): + return auth.user + + +# ---------- сессии ---------- +@app.post("/api/v1/auth/sessions", status_code=201) +def login(request: Request): + creds = security.parse_basic(request.headers.get("Authorization")) + if creds is None: + raise unauthorized(BASIC_CHALLENGE) + username, password = creds + with db.connection() as conn: + user = repo.user_for_login(conn, username) if validation._USERNAME_RE.fullmatch(username) else None + if user is None: + security.burn_verify(password) # время ответа не выдаёт, существует ли логин + raise unauthorized(BASIC_CHALLENGE) + ok, new_hash = security.verify_password(user["password_hash"], password) + if not ok: + raise unauthorized(BASIC_CHALLENGE) + with db.connection() as conn: + if new_hash: + repo.update_password_hash(conn, user["id"], new_hash) + token, expires_at = sessions.create(conn, user) + user_json = sessions.user_json(user) + sessions.warm(token, user_json, expires_at) # кэш наполняется после commit + return {"token": token, "token_type": "Bearer", "expires_at": sessions.fmt_ts(expires_at), "user": user_json} + + +@app.delete("/api/v1/auth/sessions/current") +def logout(auth: Auth = Depends(authenticated)): + sessions.revoke(auth.digest) + return Response(status_code=204) + + +# ---------- чаты ---------- +@app.post("/api/v1/chats", status_code=201) +def create_chat(auth: Auth = Depends(authenticated), body: RawBody = Depends(raw_body)): + data = validation.json_body(body.content_type, body.data, {"title", "member_ids"}, {"title", "member_ids"}) + title = validation.text_field(data["title"], "title", 1, 100) + raw = data["member_ids"] + if not isinstance(raw, list) or not 1 <= len(raw) <= 100: + raise bad_request("member_ids: от 1 до 100 элементов") + members = [validation.require_uuid(x, "member_id") for x in raw] + if len(set(members)) != len(members) or auth.user_id not in members: + raise bad_request("member_ids должны быть уникальны и включать вызывающего") + with db.connection() as conn: # одна транзакция: либо чат целиком, либо ничего + chat = repo.create_chat(conn, auth.user_id, title, members) + return repo.chat_json(chat) + + +@app.get("/api/v1/chats") +def list_chats(request: Request, auth: Auth = Depends(authenticated)): + limit = validation.limit_param(request.query_params) + raw = request.query_params.get("cursor") + after = cursor.decode(raw, "chats", auth.user_id) if raw else None + with db.connection() as conn: + items, nxt = repo.list_chats(conn, auth.user_id, after, limit) + return {"items": items, "next_cursor": nxt} + + +@app.get("/api/v1/chats/{chat_id}") +def get_chat(chat_id: str, auth: Auth = Depends(authenticated)): + cid = validation.require_uuid(chat_id, "chat_id") + with db.connection() as conn: + chat = repo.get_chat(conn, cid, auth.user_id) + if chat is None: + raise not_found() + return repo.chat_json(chat) + + +# ---------- сообщения ---------- +@app.post("/api/v1/chats/{chat_id}/messages", status_code=201) +def create_message(chat_id: str, auth: Auth = Depends(authenticated), body: RawBody = Depends(raw_body)): + cid = validation.require_uuid(chat_id, "chat_id") + with db.connection() as conn: + if not repo.is_member(conn, cid, auth.user_id): # сначала доступ (404), потом валидация тела + raise not_found() + data = validation.json_body(body.content_type, body.data, {"text"}, {"text"}) + text = validation.text_field(data["text"], "text", 1, 4000) + with db.connection() as conn: + row = repo.insert_message(conn, cid, auth.user_id, text) # sender_id — только из сессии + return repo.message_json(row) + + +@app.get("/api/v1/chats/{chat_id}/messages") +def list_messages(chat_id: str, request: Request, auth: Auth = Depends(authenticated)): + cid = validation.require_uuid(chat_id, "chat_id") + limit = validation.limit_param(request.query_params) + raw = request.query_params.get("cursor") + after = cursor.decode(raw, "messages", cid) if raw else None + with db.connection() as conn: + if not repo.is_member(conn, cid, auth.user_id): + raise not_found() + items, nxt = repo.list_messages(conn, cid, after, limit) + return {"items": items, "next_cursor": nxt} diff --git a/requirements-dev.txt b/requirements-dev.txt new file mode 100644 index 0000000..b0b7182 --- /dev/null +++ b/requirements-dev.txt @@ -0,0 +1,5 @@ +# Only for full OpenAPI/JSON Schema validation; HTTP tests use stdlib. +openapi-spec-validator==0.7.2 + +# Свои тесты из lab1 (pytest tests/test_own.py tests/test_race.py -v) +pytest==8.3.3 diff --git a/requirements.in b/requirements.in new file mode 100644 index 0000000..439326c --- /dev/null +++ b/requirements.in @@ -0,0 +1,6 @@ +fastapi==0.115.0 +uvicorn[standard]==0.30.6 +psycopg[binary]==3.2.9 +psycopg-pool==3.2.6 +argon2-cffi==25.1.0 +redis==6.4.0 diff --git a/requirements.txt b/requirements.txt new file mode 100644 index 0000000..bb5235b --- /dev/null +++ b/requirements.txt @@ -0,0 +1,26 @@ +annotated-types==0.8.0 +anyio==4.15.1 +argon2-cffi==25.1.0 +argon2-cffi-bindings==26.1.0 +cffi==2.1.1 +click==8.5.0 +fastapi==0.115.0 +h11==0.16.0 +httptools==0.9.0 +idna==3.20 +psycopg==3.2.9 +psycopg-binary==3.2.9 +psycopg-pool==3.2.6 +pycparser==3.11 +pydantic==2.14.1 +pydantic_core==2.50.1 +python-dotenv==1.2.4 +PyYAML==6.0.3 +redis==6.4.0 +starlette==0.38.6 +typing-inspection==0.4.4 +typing_extensions==4.16.0 +uvicorn==0.30.6 +uvloop==0.23.0 +watchfiles==1.3.0 +websockets==17.2 diff --git a/scripts/backup.sh b/scripts/backup.sh new file mode 100644 index 0000000..705bcb5 --- /dev/null +++ b/scripts/backup.sh @@ -0,0 +1,9 @@ +#!/bin/sh +# Логический backup рабочей БД стенда (Compose): pg_dump -Fc из контейнера postgres в backups/ (каталог в .gitignore). +# Снапшот согласован на момент НАЧАЛА pg_dump; запись при этом не блокируется. Секреты в вывод не попадают. +set -eu +cd "$(dirname "$0")/.." +mkdir -p backups && umask 077 +OUT="backups/messenger-$(date -u +%Y%m%dT%H%M%SZ).dump" +docker compose --env-file .env exec -T postgres pg_dump -U messenger -d messenger -Fc --no-owner > "$OUT" +echo "$OUT $(wc -c < "$OUT") bytes" diff --git a/scripts/check_contract.py b/scripts/check_contract.py new file mode 100644 index 0000000..dcb34df --- /dev/null +++ b/scripts/check_contract.py @@ -0,0 +1,54 @@ +#!/usr/bin/env python3 +"""Offline structural checks; full schema validation is a separate target.""" +import ast +import json +from pathlib import Path +import re + +ROOT = Path(__file__).resolve().parents[1] + +def main(): + lab = json.loads((ROOT/'lab.json').read_text())['number'] + spec = json.loads((ROOT/'contracts/openapi.json').read_text()) + assert spec['openapi']=='3.1.0' + assert spec['info']['version']=='1.%d.0'%lab + operation_ids = set() + def walk(value): + if isinstance(value,dict): + if '$ref' in value: + pointer = value['$ref'] + assert pointer.startswith('#/'), 'unexpected external reference' + target = spec + for part in pointer[2:].split('/'): + target = target[part.replace('~1','/').replace('~0','~')] + for v in value.values(): + walk(v) + elif isinstance(value,list): + for v in value: + walk(v) + walk(spec) + for route,methods in spec['paths'].items(): + placeholders = set(re.findall(r'\{([^}]+)\}',route)) + for method,op in methods.items(): + assert op['operationId'] not in operation_ids, 'duplicate operationId' + operation_ids.add(op['operationId']) + params = {p['name'] for p in op.get('parameters',[]) if p['in']=='path' and p.get('required')} + assert placeholders==params, 'path parameter mismatch: '+route + for response in op['responses'].values(): + assert 'X-Request-Id' in response['headers'] + if lab>=3: + assert 'X-Instance-Id' in response['headers'] + assert ('/api/v1/auth/sessions' in spec['paths']) == (lab>=2) + assert ('/api/v1/attachments/{attachment_id}' in spec['paths']) == (lab>=4) + for file in list((ROOT/'tests').glob('*.py'))+list((ROOT/'scripts').glob('*.py')): + ast.parse(file.read_text(),filename=str(file)) + for file in ROOT.rglob('*.json'): + if any(part in {'.git','.venv','node_modules','vendor','output'} for part in file.parts): + continue + json.loads(file.read_text()) + for required in ('README.md','COURSE.md','CONTRIBUTING.md','REPORT.md','contracts/README.md','tests/smoke.py','tests/README.md'): + assert (ROOT/required).is_file(), 'missing '+required + print('PASS: offline skeleton structure, local refs and Python syntax; application NOT tested.') + +if __name__=='__main__': + main() diff --git a/scripts/evidence-restart.sh b/scripts/evidence-restart.sh new file mode 100644 index 0000000..40f4f5c --- /dev/null +++ b/scripts/evidence-restart.sh @@ -0,0 +1,9 @@ +#!/bin/sh +# Доказательство, что restart-hook реально перезапустил процессы: StartedAt контейнеров ДО и ПОСЛЕ + прогон теста. +set -eu +cd "$(dirname "$0")/.." +DC="docker compose --env-file .env" +show() { for s in postgres valkey api; do printf '%-9s StartedAt=%s\n' "$s" "$(docker inspect -f '{{.State.StartedAt}}' "$($DC ps -q $s)")"; done; } +echo "== before =="; show; $DC ps +make test-persistence ACTION_SCRIPT=scripts/restart.sh +echo "== after =="; show; $DC ps diff --git a/scripts/explain_history.py b/scripts/explain_history.py new file mode 100644 index 0000000..585f6d4 --- /dev/null +++ b/scripts/explain_history.py @@ -0,0 +1,76 @@ +#!/usr/bin/env python3 +"""Обоснование индекса истории: EXPLAIN (ANALYZE, BUFFERS) на синтетических данных. + +Использует ОТДЕЛЬНУЮ БД (миграции применяются к ней же): python scripts/explain_history.py +Переменные: DATABASE_URL_FILE/DATABASE_URL указывают на БД для эксперимента (не на рабочую!). +Данные: 1 «целевой» чат (TARGET_N сообщений) + 4 чата-шума по NOISE_N — таблица ≈ 5×, как в реальной системе. +""" +import os +import sys +import uuid +from pathlib import Path + +sys.path.insert(0, str(Path(__file__).resolve().parents[1])) +import psycopg # noqa: E402 + +from app import config, migrate # noqa: E402 + +TARGET_N = int(os.environ.get("TARGET_N", 20000)) +NOISE_N = int(os.environ.get("NOISE_N", 20000)) +PAGE = 50 + + +def main(): + migrate.apply_all(config.DATABASE_URL) + with psycopg.connect(config.DATABASE_URL, autocommit=True) as conn: + conn.execute("TRUNCATE messages, chat_members, chats, sessions, users CASCADE") + user = uuid.uuid4() + conn.execute("INSERT INTO users (id, username, display_name, password_hash) VALUES (%s,'explain_user','x','x')", (user,)) + chats = [uuid.uuid4() for _ in range(5)] + for cid in chats: + conn.execute("INSERT INTO chats (id, title, created_by) VALUES (%s,'t',%s)", (cid, user)) + conn.execute("INSERT INTO chat_members (chat_id, user_id) VALUES (%s,%s)", (cid, user)) + # Вставка вперемешку по времени (как у живых чатов): created_at — равномерная шкала + микросекунды. + for i, cid in enumerate(chats): + n = TARGET_N if i == 0 else NOISE_N + conn.execute("""INSERT INTO messages (id, chat_id, sender_id, text, created_at) + SELECT gen_random_uuid(), %s, %s, 'message ' || g, + timestamptz '2026-01-01 00:00:00+00' + (g * 5 + %s) * interval '1 second' + (random()*1000) * interval '1 microsecond' + FROM generate_series(1, %s) g""", (cid, user, i, n)) + conn.execute("VACUUM (ANALYZE) messages") + target = chats[0] + total = conn.execute("SELECT count(*) FROM messages").fetchone()[0] + in_chat = conn.execute("SELECT count(*) FROM messages WHERE chat_id=%s", (target,)).fetchone()[0] + # Курсор «глубоко в истории»: элемент №15000 по (created_at, id). + ts, mid = conn.execute("""SELECT created_at, id FROM messages WHERE chat_id=%s + ORDER BY created_at, id OFFSET %s LIMIT 1""", (target, min(15000, in_chat - PAGE - 1))).fetchone() + + def explain(title, sql, params, pre=None, post=None): + print("\n" + "=" * 100 + "\n" + title + "\n" + "=" * 100) + with conn.transaction(force_rollback=True): # DDL в PostgreSQL транзакционен: индекс вернётся + if pre: + conn.execute(pre) + for line in conn.execute("EXPLAIN (ANALYZE, BUFFERS) " + sql, params).fetchall(): + print(line[0]) + + print("rows total=%d, rows in target chat=%d, page=%d" % (total, in_chat, PAGE)) + print(conn.execute("SELECT version()").fetchone()[0]) + first = "SELECT id, chat_id, sender_id, text, created_at FROM messages WHERE chat_id=%s ORDER BY created_at, id LIMIT %s" + keyset = ("SELECT id, chat_id, sender_id, text, created_at FROM messages WHERE chat_id=%s " + "AND (created_at, id) > (%s, %s) ORDER BY created_at, id LIMIT %s") + offset = "SELECT id, chat_id, sender_id, text, created_at FROM messages WHERE chat_id=%s ORDER BY created_at, id OFFSET 15000 LIMIT %s" + drop = "DROP INDEX messages_chat_created_id_idx" + explain("A. Первая страница, keyset, С индексом (chat_id, created_at, id)", first, (target, PAGE + 1)) + explain("B. Страница на глубине ~15 000, keyset, С индексом", keyset, (target, ts, mid, PAGE + 1)) + explain("C. Та же страница, keyset, БЕЗ индекса (индекс удалён в откатываемой транзакции)", keyset, (target, ts, mid, PAGE + 1), pre=drop) + explain("D. Та же глубина через OFFSET 15000, С индексом (антипример)", offset, (target, PAGE + 1)) + explain("E. Первая страница, БЕЗ индекса", first, (target, PAGE + 1), pre=drop) + print("\nИндексы messages:") + for row in conn.execute("SELECT indexname, indexdef FROM pg_indexes WHERE tablename='messages' ORDER BY 1").fetchall(): + print(" ", row[0], "->", row[1]) + print("Размер индекса: ", conn.execute("SELECT pg_size_pretty(pg_relation_size('messages_chat_created_id_idx'))").fetchone()[0], + "; таблицы:", conn.execute("SELECT pg_size_pretty(pg_relation_size('messages'))").fetchone()[0]) + + +if __name__ == "__main__": + main() diff --git a/scripts/init-secrets.sh b/scripts/init-secrets.sh new file mode 100644 index 0000000..071b648 --- /dev/null +++ b/scripts/init-secrets.sh @@ -0,0 +1,17 @@ +#!/bin/sh +# Создаёт локальные секреты (случайные пароли) и .env. Идемпотентно: существующие секреты НЕ перезаписываются +# (иначе пароль в уже инициализированном томе PostgreSQL перестал бы совпадать). Каталог secrets/ в .gitignore. +set -eu +cd "$(dirname "$0")/.." +umask 077 +mkdir -p secrets +rand() { if command -v openssl >/dev/null 2>&1; then openssl rand -hex 24; else python3 -c 'import secrets;print(secrets.token_hex(24))'; fi; } +put() { [ -f "secrets/$1" ] || { printf '%s' "$2" > "secrets/$1"; echo "created secrets/$1"; }; } +[ -f secrets/postgres_password ] || printf '%s' "$(rand)" > secrets/postgres_password +[ -f secrets/valkey_password ] || printf '%s' "$(rand)" > secrets/valkey_password +PG=$(cat secrets/postgres_password); VK=$(cat secrets/valkey_password) +put database_url "postgresql://messenger:${PG}@postgres:5432/messenger" +put cache_url "redis://:${VK}@valkey:6379/0" +# Файлы читаются процессами контейнеров с другим UID, поэтому 644; доступ ограничивает каталог secrets/ (700). +chmod 700 secrets && chmod 644 secrets/* +[ -f .env ] || { cp .env.example .env; echo "created .env"; } diff --git a/scripts/restart.example.sh b/scripts/restart.example.sh new file mode 100644 index 0000000..967e951 --- /dev/null +++ b/scripts/restart.example.sh @@ -0,0 +1,10 @@ +#!/bin/sh +set -eu +# TODO: copy to restart.sh and implement using YOUR compose/stack services. +# Restart API and ALL used state stores (DB, sessions, S3, broker as applicable). +# Preserve persistent volumes and schema/data; never down -v / flush / re-seed. +# Allow operator unseal if required in lab7; do not print credentials. +# Exit 0 only after the intended action; test waits for API readiness separately. +printf '%s +' 'TODO: implement restart.sh for your infrastructure' >&2 +exit 2 diff --git a/scripts/restart.sh b/scripts/restart.sh new file mode 100644 index 0000000..2aefa14 --- /dev/null +++ b/scripts/restart.sh @@ -0,0 +1,14 @@ +#!/bin/sh +# Hook для tests/resilience.py --mode persistence: перезапускает API и ВСЕ хранилища (PostgreSQL, Valkey), +# тома сохраняются. Никаких down -v / flush / повторного seed. Вывод скрыт тестом, секреты не печатаются. +set -eu +cd "$(dirname "$0")/.." +DC="docker compose --env-file .env" +$DC stop api valkey postgres # SIGTERM; compose сам останавливает в обратном порядке зависимостей +$DC up -d # поднимает postgres+valkey, повторно гонит idempotent-миграции, затем api +i=0 +until [ "$(docker inspect -f '{{.State.Health.Status}}' "$($DC ps -q api)" 2>/dev/null || true)" = "healthy" ]; do + i=$((i + 1)) + [ "$i" -le 70 ] || { echo "api did not become healthy" >&2; exit 1; } + sleep 1 +done diff --git a/scripts/restore-check.sh b/scripts/restore-check.sh new file mode 100644 index 0000000..a28c917 --- /dev/null +++ b/scripts/restore-check.sh @@ -0,0 +1,21 @@ +#!/bin/sh +# Восстановление dump в НОВОЕ хранилище (временный контейнер со свежим томом) и сверка с рабочей БД. +# Использование: sh scripts/restore-check.sh backups/messenger-XXXX.dump +# ВНИМАНИЕ: не запускался в среде подготовки (там нет Docker); эквивалентный эксперимент выполнен через +# scripts/track2_restore.py на двух отдельных серверах PostgreSQL (см. evidence/track2-restore.json). +set -eu +cd "$(dirname "$0")/.." +DUMP="${1:?usage: restore-check.sh }" +DC="docker compose --env-file .env" +NAME="pg-restore-check-$$" +trap 'docker rm -f "$NAME" >/dev/null 2>&1 || true' EXIT +docker run -d --name "$NAME" -e POSTGRES_PASSWORD=restore-check-only -e POSTGRES_USER=messenger -e POSTGRES_DB=restored postgres:17.6-alpine >/dev/null +i=0; until docker exec "$NAME" pg_isready -U messenger -d restored >/dev/null 2>&1; do i=$((i+1)); [ $i -le 60 ] || exit 1; sleep 1; done +START=$(date +%s) +docker exec -i "$NAME" pg_restore -U messenger -d restored --no-owner --exit-on-error < "$DUMP" +docker exec "$NAME" psql -U messenger -d restored -qc "ANALYZE" +echo "restore+analyze seconds: $(( $(date +%s) - START ))" +Q="select 'users',count(*) from users union all select 'chats',count(*) from chats union all select 'chat_members',count(*) from chat_members union all select 'messages',count(*) from messages union all select 'messages_md5', md5(string_agg(id::text||chat_id::text||sender_id::text||created_at::text||md5(text), ',' order by id))::text from messages" +echo "--- restored ---"; docker exec "$NAME" psql -U messenger -d restored -At -c "$Q" +echo "--- source (rows after the dump may differ: that is the RPO window) ---" +$DC exec -T postgres psql -U messenger -d messenger -At -c "$Q" diff --git a/scripts/test-expiry.sh b/scripts/test-expiry.sh new file mode 100644 index 0000000..e746cd7 --- /dev/null +++ b/scripts/test-expiry.sh @@ -0,0 +1,9 @@ +#!/bin/sh +# Проверка expiry: пересоздаёт api с SESSION_TTL_SECONDS=2, гоняет tests_student/test_expiry.py, возвращает штатный TTL. +set -eu +cd "$(dirname "$0")/.." +DC="docker compose --env-file .env" +wait_healthy() { i=0; until [ "$(docker inspect -f '{{.State.Health.Status}}' "$($DC ps -q api)")" = "healthy" ]; do i=$((i+1)); [ $i -le 60 ] || exit 1; sleep 1; done; } +trap 'SESSION_TTL_SECONDS= $DC up -d --force-recreate api >/dev/null; wait_healthy' EXIT +SESSION_TTL_SECONDS=2 $DC up -d --force-recreate api; wait_healthy +(cd tests_student && python3 test_expiry.py 2) diff --git a/scripts/track2_indexes.py b/scripts/track2_indexes.py new file mode 100644 index 0000000..68bf113 --- /dev/null +++ b/scripts/track2_indexes.py @@ -0,0 +1,186 @@ +#!/usr/bin/env python3 +"""Трек 2 (часть A): план запроса истории на ≥100 000 сообщений с НЕРАВНОМЕРНЫМИ чатами. + +Гипотеза H1: составной индекс (chat_id, created_at, id) даёт страницу истории за O(размер страницы) +для любого чата и любой глубины, а индекс только по chat_id или «глобальный» (created_at, id) — нет; +покрывающий вариант (INCLUDE) читает меньше страниц, но платит за это размером индекса и стоимостью записи. +Гипотеза H2: каждый дополнительный индекс заметно удорожает вставку, и цена растёт с шириной индекса. + +Запуск (ОТДЕЛЬНАЯ БД эксперимента, не рабочая!): + DATABASE_URL_FILE=/path/to/url python scripts/track2_indexes.py --out evidence/track2-indexes.json +""" +import argparse +import json +import os +import platform +import statistics +import sys +import time +import uuid +from pathlib import Path + +sys.path.insert(0, str(Path(__file__).resolve().parents[1])) +import psycopg # noqa: E402 + +from app import config, migrate # noqa: E402 + +# Неравномерные размеры: 1 гигант, 2 больших, 10 средних, 50 малых, 500 «почти пустых» = ровно 100 000. +SIZES = [50000, 20000, 10000] + [1000] * 10 + [100] * 50 + [10] * 500 +CONFIGS = [ + ("C0_pk_only", None), + ("C1_chat_id", "CREATE INDEX hist_idx ON messages (chat_id)"), + ("C2_chat_created_id", "CREATE INDEX hist_idx ON messages (chat_id, created_at, id)"), + ("C3_covering_include", "CREATE INDEX hist_idx ON messages (chat_id, created_at, id) INCLUDE (sender_id, text)"), + ("C4_global_created_id", "CREATE INDEX hist_idx ON messages (created_at, id)"), +] +COLS = "id, chat_id, sender_id, text, created_at" +PAGE = 50 +READ_RUNS, WARMUP = 300, 20 +SINGLE_INSERTS = 2000 +BULK_REPEATS = 3 + + +def pct(values, p): + values = sorted(values) + return values[max(0, min(len(values) - 1, int(round(p * len(values) + 0.5)) - 1))] + + +def seed_source(conn): + """Один раз генерируем данные в messages_src: тексты разной длины (10–400 символов), время по возрастанию в чате.""" + conn.execute("TRUNCATE messages, chat_members, chats, sessions, users CASCADE") + conn.execute("DROP TABLE IF EXISTS messages_src") + user = uuid.uuid4() + conn.execute("INSERT INTO users (id, username, display_name, password_hash) VALUES (%s,'track2_user','x','x')", (user,)) + chats = [uuid.uuid4() for _ in SIZES] + for cid in chats: + conn.execute("INSERT INTO chats (id, title, created_by) VALUES (%s,'t',%s)", (cid, user)) + conn.execute("INSERT INTO chat_members (chat_id, user_id) VALUES (%s,%s)", (cid, user)) + conn.execute("""CREATE TABLE messages_src AS + SELECT gen_random_uuid() AS id, c.chat_id, %s::uuid AS sender_id, + left(repeat('сообщение ', 60), 10 + (random() * 390)::int) AS text, + timestamptz '2026-01-01 00:00:00+00' + (g.n * 7 + c.idx) * interval '1 second' + + (random() * 1000) * interval '1 microsecond' AS created_at + FROM (SELECT unnest(%s::uuid[]) AS chat_id, unnest(%s::int[]) AS size, generate_series(1, %s) AS idx) c + CROSS JOIN LATERAL generate_series(1, c.size) AS g(n)""", (user, chats, SIZES, len(SIZES))) + conn.execute("ANALYZE messages_src") + return user, chats + + +def reset_history_index(conn, ddl): + conn.execute("DROP INDEX IF EXISTS messages_chat_created_id_idx") + conn.execute("DROP INDEX IF EXISTS hist_idx") + if ddl: + conn.execute(ddl) + + +def measure_writes(conn, ddl, chats): + """Стоимость записи: (1) пакетная загрузка 100 000 строк, (2) 2000 одиночных INSERT с коммитом (как работает API).""" + bulk = [] + for _ in range(BULK_REPEATS): + conn.execute("TRUNCATE messages") + reset_history_index(conn, ddl) + t0 = time.perf_counter() + conn.execute("INSERT INTO messages (id, chat_id, sender_id, text, created_at) SELECT * FROM messages_src") + bulk.append(time.perf_counter() - t0) + conn.execute("VACUUM (ANALYZE) messages") + # Одиночные вставки: чаты выбираются пропорционально размеру (больше сообщений — чаще пишут), autocommit = COMMIT на каждую. + import random + rnd = random.Random(42) + sender = conn.execute("SELECT sender_id FROM messages LIMIT 1").fetchone()[0] + singles = [] + for _ in range(SINGLE_INSERTS): + cid = rnd.choices(chats, weights=SIZES)[0] + t0 = time.perf_counter() + conn.execute("INSERT INTO messages (id, chat_id, sender_id, text) VALUES (%s,%s,%s,%s)", + (uuid.uuid4(), cid, sender, "одиночная вставка " + "x" * rnd.randint(10, 300))) + singles.append(time.perf_counter() - t0) + conn.execute("VACUUM (ANALYZE) messages") + size = lambda rel: conn.execute("SELECT pg_relation_size(%s)", (rel,)).fetchone()[0] + return { + "bulk_insert_100k_seconds": {"runs": [round(x, 3) for x in bulk], "median": round(statistics.median(bulk), 3)}, + "single_insert_ms": {"n": len(singles), "mean": round(1000 * statistics.mean(singles), 3), + "p50": round(1000 * pct(singles, .50), 3), "p95": round(1000 * pct(singles, .95), 3), + "p99": round(1000 * pct(singles, .99), 3)}, + "history_index_bytes": size("hist_idx") if ddl else 0, + "table_bytes": size("messages"), + "pk_index_bytes": size("messages_pkey"), + } + + +def plan_summary(conn, sql, params): + plan = conn.execute("EXPLAIN (ANALYZE, BUFFERS, FORMAT JSON) " + sql, params).fetchone()[0][0] + nodes, stack = [], [plan["Plan"]] + while stack: + node = stack.pop() + nodes.append(node["Node Type"]) + stack.extend(node.get("Plans", [])) + root = plan["Plan"] + return {"nodes": nodes[::-1], "execution_ms": round(plan["Execution Time"], 3), + "shared_buffers": root.get("Shared Hit Blocks", 0) + root.get("Shared Read Blocks", 0), + "rows": root["Actual Rows"]} + + +def measure_reads(conn, queries): + out = {} + for name, (sql, params) in queries.items(): + for _ in range(WARMUP): + conn.execute(sql, params).fetchall() + times = [] + for _ in range(READ_RUNS): + t0 = time.perf_counter() + conn.execute(sql, params).fetchall() + times.append(time.perf_counter() - t0) + out[name] = {"p50_ms": round(1000 * pct(times, .50), 3), "p95_ms": round(1000 * pct(times, .95), 3), + "plan": plan_summary(conn, sql, params)} + return out + + +def main(): + ap = argparse.ArgumentParser() + ap.add_argument("--out", default="evidence/track2-indexes.json") + ap.add_argument("--reverse", action="store_true", help="обратный порядок конфигураций: проверка, что результат не зависит от порядка/прогрева") + args = ap.parse_args() + migrate.apply_all(config.DATABASE_URL) + with psycopg.connect(config.DATABASE_URL, autocommit=True) as conn: + user, chats = seed_source(conn) + total = conn.execute("SELECT count(*) FROM messages_src").fetchone()[0] + big, small, mid = chats[0], chats[-1], chats[3] # 50 000 / 10 / 1 000 сообщений + deep_ts, deep_id = conn.execute("SELECT created_at, id FROM messages_src WHERE chat_id=%s ORDER BY created_at, id OFFSET 40000 LIMIT 1", (big,)).fetchone() + mid_ts, mid_id = conn.execute("SELECT created_at, id FROM messages_src WHERE chat_id=%s ORDER BY created_at, id OFFSET 500 LIMIT 1", (mid,)).fetchone() + first = "SELECT %s FROM messages WHERE chat_id=%%s ORDER BY created_at, id LIMIT %%s" % COLS + keyset = "SELECT %s FROM messages WHERE chat_id=%%s AND (created_at, id) > (%%s, %%s) ORDER BY created_at, id LIMIT %%s" % COLS + offset = "SELECT %s FROM messages WHERE chat_id=%%s ORDER BY created_at, id OFFSET 40000 LIMIT %%s" % COLS + queries = { + "Q1_first_page_giant_50k": (first, (big, PAGE + 1)), + "Q2_deep_keyset_giant_at_40k": (keyset, (big, deep_ts, deep_id, PAGE + 1)), + "Q3_first_page_tiny_10": (first, (small, PAGE + 1)), + "Q4_keyset_mid_1k_at_500": (keyset, (mid, mid_ts, mid_id, PAGE + 1)), + "Q5_OFFSET_40000_giant": (offset, (big, PAGE + 1)), + } + env = { + "postgres": conn.execute("SHOW server_version").fetchone()[0], + "shared_buffers": conn.execute("SHOW shared_buffers").fetchone()[0], + "work_mem": conn.execute("SHOW work_mem").fetchone()[0], + "fsync": conn.execute("SHOW fsync").fetchone()[0], + "synchronous_commit": conn.execute("SHOW synchronous_commit").fetchone()[0], + "cpus": os.cpu_count(), "python": platform.python_version(), "platform": platform.platform(), + } + results = {"environment": env, "dataset": {"messages": total, "chats": len(SIZES), "chat_size_distribution": + {"50000": 1, "20000": 1, "10000": 1, "1000": 10, "100": 50, "10": 500}, "text_length_chars": "10..400 (равномерно)", + "page_size": PAGE, "read_runs": READ_RUNS, "warmup": WARMUP, "single_inserts": SINGLE_INSERTS, + "bulk_repeats": BULK_REPEATS, "order": "reverse" if args.reverse else "forward"}, "configs": {}} + for name, ddl in (reversed(CONFIGS) if args.reverse else CONFIGS): + print("== %s ==" % name, flush=True) + w = measure_writes(conn, ddl, chats) + r = measure_reads(conn, queries) + results["configs"][name] = {"ddl": ddl, "writes": w, "reads": r} + print(" bulk %.2fs, single p50 %.3f ms, index %.1f MiB; Q1 p50 %.3f ms, Q2 p50 %.3f ms, Q3 p50 %.3f ms" % ( + w["bulk_insert_100k_seconds"]["median"], w["single_insert_ms"]["p50"], w["history_index_bytes"] / 2**20, + r["Q1_first_page_giant_50k"]["p50_ms"], r["Q2_deep_keyset_giant_at_40k"]["p50_ms"], r["Q3_first_page_tiny_10"]["p50_ms"]), flush=True) + Path(args.out).parent.mkdir(parents=True, exist_ok=True) + Path(args.out).write_text(json.dumps(results, ensure_ascii=False, indent=2) + "\n") + print("saved", args.out) + + +if __name__ == "__main__": + main() diff --git a/scripts/track2_restore.py b/scripts/track2_restore.py new file mode 100644 index 0000000..1d57b6c --- /dev/null +++ b/scripts/track2_restore.py @@ -0,0 +1,142 @@ +#!/usr/bin/env python3 +"""Трек 2 (часть B): backup -> восстановление в НОВОЕ хранилище -> сверка количества и выбранных сообщений. + +Источник — БД эксперимента (после track2_indexes.py, 100 000+ сообщений). Приёмник — другой кластер/сервер PostgreSQL +(новый каталог данных, другой порт), т.е. настоящее «новое хранилище», а не вторая БД в том же кластере. + + python scripts/track2_restore.py --src-url URL --dst-admin-url URL(postgres db на новом сервере) \ + --dst-db messenger_restored --pg-bin /usr/lib/postgresql/16/bin --dump-file /tmp/t2.dump --out evidence/track2-restore.json + +Что измеряется: длительность pg_dump и pg_restore (+ ANALYZE), размер дампа, полнота сверки, окно потери данных (RPO): +записи, сделанные ПОСЛЕ начала дампа, в копии отсутствуют; отозванная после дампа сессия в копии «воскресает». +""" +import argparse +import json +import os +import subprocess +import sys +import time +import uuid +from pathlib import Path +from urllib.parse import urlsplit, urlunsplit + +import psycopg + + +def with_db(url, db): + parts = urlsplit(url) + return urlunsplit(parts._replace(path="/" + db)) + + +def facts(conn): + """Отпечаток состояния: счётчики, md5 содержимого, схема, выбранные строки.""" + one = lambda sql, *p: conn.execute(sql, p).fetchone()[0] + out = {"counts": {t: one("SELECT count(*) FROM " + t) for t in ("users", "chats", "chat_members", "messages", "sessions")}} + out["messages_md5"] = one("""SELECT md5(string_agg(id::text || '|' || chat_id::text || '|' || sender_id::text || '|' || + created_at::text || '|' || md5(text), ',' ORDER BY id)) FROM messages""") + out["per_chat_counts_md5"] = one("SELECT md5(string_agg(chat_id::text || ':' || n, ',' ORDER BY chat_id)) FROM (SELECT chat_id, count(*) n FROM messages GROUP BY chat_id) s") + out["indexes_md5"] = one("SELECT md5(string_agg(indexname || indexdef, E'\\n' ORDER BY indexname)) FROM pg_indexes WHERE schemaname='public'") + out["constraints_md5"] = one("SELECT md5(string_agg(conname || pg_get_constraintdef(oid), E'\\n' ORDER BY conname)) FROM pg_constraint WHERE connamespace = 'public'::regnamespace") + out["migrations"] = [r[0] for r in conn.execute("SELECT version FROM schema_migrations ORDER BY 1").fetchall()] + big = one("SELECT chat_id FROM messages GROUP BY chat_id ORDER BY count(*) DESC, chat_id LIMIT 1") + picks = { + "first_overall": "SELECT * FROM messages ORDER BY created_at, id LIMIT 1", + "last_overall": "SELECT * FROM messages ORDER BY created_at DESC, id DESC LIMIT 1", + "giant_chat_item_15000": "SELECT * FROM messages WHERE chat_id = '%s' ORDER BY created_at, id OFFSET 15000 LIMIT 1" % big, + "longest_text": "SELECT * FROM messages ORDER BY char_length(text) DESC, id LIMIT 1", + "shortest_text": "SELECT * FROM messages ORDER BY char_length(text), id LIMIT 1", + "pseudo_random_by_md5": "SELECT * FROM messages ORDER BY md5(id::text) LIMIT 1", + } + out["selected_messages"] = {k: one("SELECT row_to_json(s)::text FROM (%s) s" % q) for k, q in picks.items()} + return out + + +def run(cmd, env): + t0 = time.perf_counter() + proc = subprocess.run(cmd, env=env, capture_output=True, text=True) + dt = time.perf_counter() - t0 + if proc.returncode: + raise SystemExit("command failed (%s): %s" % (cmd[0], proc.stderr[-800:])) + return dt + + +def main(): + ap = argparse.ArgumentParser() + ap.add_argument("--src-url", required=True) + ap.add_argument("--dst-admin-url", required=True, help="URL БД postgres на НОВОМ сервере (создание БД восстановления)") + ap.add_argument("--dst-db", default="messenger_restored") + ap.add_argument("--pg-bin", default="/usr/lib/postgresql/16/bin") + ap.add_argument("--dump-file", default="/tmp/track2.dump") + ap.add_argument("--out", default="evidence/track2-restore.json") + a = ap.parse_args() + dst_url = with_db(a.dst_admin_url, a.dst_db) + env = dict(os.environ) + + with psycopg.connect(a.src_url, autocommit=True) as src: + # 1. Приводим источник к «боевой» схеме: без вспомогательной таблицы, канонический индекс истории, одна сессия. + src.execute("DROP TABLE IF EXISTS messages_src") + src.execute("DROP INDEX IF EXISTS hist_idx") + src.execute("CREATE INDEX IF NOT EXISTS messages_chat_created_id_idx ON messages (chat_id, created_at, id)") + user = src.execute("SELECT id FROM users LIMIT 1").fetchone()[0] + token_hash = os.urandom(32) + src.execute("INSERT INTO sessions (token_hash, user_id, expires_at) VALUES (%s,%s, now() + interval '1 day')", (token_hash, user)) + src.execute("VACUUM (ANALYZE)") + before = facts(src) + db_bytes = src.execute("SELECT pg_database_size(current_database())").fetchone()[0] + + # 2. Backup: логический, custom-формат; снапшот согласован на момент НАЧАЛА pg_dump. + t_dump = run([a.pg_bin + "/pg_dump", "-Fc", "--no-owner", "-f", a.dump_file, "-d", a.src_url], env) + dump_bytes = Path(a.dump_file).stat().st_size + + # 3. Окно потери (RPO): изменения ПОСЛЕ дампа — 500 новых сообщений и отзыв сессии. + chat = src.execute("SELECT chat_id FROM messages LIMIT 1").fetchone()[0] + sender = src.execute("SELECT sender_id FROM messages WHERE chat_id=%s LIMIT 1", (chat,)).fetchone()[0] + for i in range(500): + src.execute("INSERT INTO messages (id, chat_id, sender_id, text) VALUES (%s,%s,%s,%s)", (uuid.uuid4(), chat, sender, "после бэкапа %d" % i)) + src.execute("DELETE FROM sessions WHERE token_hash = %s", (token_hash,)) + after_source = facts(src) + + # 4. Новое хранилище: другая БД на другом сервере. + with psycopg.connect(a.dst_admin_url, autocommit=True) as admin: + admin.execute('DROP DATABASE IF EXISTS "%s"' % a.dst_db) + admin.execute('CREATE DATABASE "%s"' % a.dst_db) + t_restore = run([a.pg_bin + "/pg_restore", "--no-owner", "--exit-on-error", "-d", dst_url, a.dump_file], env) + with psycopg.connect(dst_url, autocommit=True) as dst: + t0 = time.perf_counter() + dst.execute("ANALYZE") # pg_dump не переносит статистику планировщика: без ANALYZE планы могут быть плохими + t_analyze = time.perf_counter() - t0 + restored = facts(dst) + plans = {} + big = dst.execute("SELECT chat_id FROM messages GROUP BY chat_id ORDER BY count(*) DESC, chat_id LIMIT 1").fetchone()[0] + plan = dst.execute("EXPLAIN (ANALYZE, BUFFERS, FORMAT JSON) SELECT id, chat_id, sender_id, text, created_at FROM messages " + "WHERE chat_id=%s ORDER BY created_at, id LIMIT 51", (big,)).fetchone()[0][0] + node = plan["Plan"] + while node.get("Plans"): + node = node["Plans"][0] + plans["first_page_giant"] = {"node": node["Node Type"], "index": node.get("Index Name"), "execution_ms": round(plan["Execution Time"], 3)} + session_present = dst.execute("SELECT count(*) FROM sessions WHERE token_hash=%s", (token_hash,)).fetchone()[0] + + # 5. Сверка: копия обязана совпасть с источником НА МОМЕНТ ДАМПА. + checks = {k: before[k] == restored[k] for k in before} + checks["selected_messages"] = {k: before["selected_messages"][k] == restored["selected_messages"][k] for k in before["selected_messages"]} + ok = all(v if isinstance(v, bool) else all(v.values()) for v in checks.values()) + rpo = { + "messages_lost_in_restore": after_source["counts"]["messages"] - restored["counts"]["messages"], + "revoked_session_resurrected_in_restore": bool(session_present), + } + result = { + "snapshot_consistent_with_restore": ok, "checks": checks, "rpo_window_observed": rpo, + "timing_seconds": {"pg_dump": round(t_dump, 2), "pg_restore": round(t_restore, 2), "analyze_after_restore": round(t_analyze, 2), + "rto_dump_free_restore_plus_analyze": round(t_restore + t_analyze, 2)}, + "sizes_bytes": {"source_database": db_bytes, "dump_file": dump_bytes}, + "counts_at_dump": before["counts"], "counts_restored": restored["counts"], "counts_source_after_extra_writes": after_source["counts"], + "restored_plan": plans, + } + Path(a.out).parent.mkdir(parents=True, exist_ok=True) + Path(a.out).write_text(json.dumps(result, ensure_ascii=False, indent=2) + "\n") + print(json.dumps(result, ensure_ascii=False, indent=2)) + raise SystemExit(0 if ok else 1) + + +if __name__ == "__main__": + main() diff --git a/scripts/validate_openapi.py b/scripts/validate_openapi.py new file mode 100644 index 0000000..1dfe4a9 --- /dev/null +++ b/scripts/validate_openapi.py @@ -0,0 +1,23 @@ +#!/usr/bin/env python3 +"""Full OpenAPI and JSON Schema checks; install requirements-dev.txt first.""" +import json +from pathlib import Path +from openapi_spec_validator import validate +from jsonschema import Draft202012Validator + +root = Path(__file__).resolve().parents[1] +spec = json.loads((root/'contracts/openapi.json').read_text()) +validate(spec) +from referencing import Registry, Resource +# The base URI resolves local #/components references inside examples. +resource = dict(spec, **{'$schema': 'https://json-schema.org/draft/2020-12/schema'}) +registry = Registry().with_resource('urn:mtusi:openapi', Resource.from_contents(resource)) +for name, example in json.loads((root/'contracts/examples.json').read_text()).items(): + schema = {'$ref': 'urn:mtusi:openapi#/components/schemas/' + name} + Draft202012Validator(schema, registry=registry).validate(example) +for path in (root/'contracts').glob('*.schema.json'): + schema = json.loads(path.read_text()) + Draft202012Validator.check_schema(schema) + for example in schema.get('examples',[]): + Draft202012Validator(schema).validate(example) +print('PASS: full OpenAPI 3.1 and JSON Schema validation; application NOT tested.') diff --git a/tests/README.md b/tests/README.md new file mode 100644 index 0000000..0dfa3f8 --- /dev/null +++ b/tests/README.md @@ -0,0 +1,57 @@ +# Публичные проверки + +Python **3.9+**, стандартная библиотека. Сервер уже должен быть запущен; проверки не создают готовое приложение и сами не управляют Docker. `make check` можно выполнить на исходном skeleton, `make test` — только после реализации API. Полная OpenAPI-валидация отдельно: `make validate` после установки `requirements-dev.txt` в venv. + +```sh +make check +make test BASE_URL=http://localhost:8080 +# без make: +python3 tests/smoke.py --base-url http://localhost:8080 +``` + +`smoke.py` выполняет **один сквозной сценарий**, автоматически выбирая профиль из `lab.json`: health → три пользователя → вход с lab2 → чат → сообщения → пагинация → ошибки доступа → идемпотентность с lab3 → файл с lab4 → thumbnail с lab5 → logout. Он проверяет JSON по используемому подмножеству схемы, коды/headers, Unicode, SHA-256 оригинала и фактические JPEG-размеры thumbnail. Это публичный минимум, не полный fuzz/security/load suite. + +Каждый запуск создаёт уникальных синтетических пользователей, чат и сообщения. Данные автоматически не удаляются: в API курса нет delete. Для чистого повтора используйте отдельный тестовый стенд/volume и осознанный сброс своего окружения. Session tokens хранятся только в памяти процесса и не печатаются/не сохраняются. + +## Проверка сохранности, lab2+ + +Скопируйте `scripts/restart.example.sh` в `scripts/restart.sh`, реализуйте перезапуск **API и всех используемых хранилищ** с сохранением volumes и задайте executable bit. Скрипт может опираться на ваш compose.yaml или stack.yaml. Он не должен удалять volumes, повторно seed-ить БД или менять тестовые данные. + +```sh +chmod +x scripts/restart.sh +make test-persistence ACTION_SCRIPT=scripts/restart.sh +``` + +Тест создаёт данные и сессию, запускает указанный файл без shell interpolation, ожидает готовности и проверяет те же данные **с прежним токеном**. В lab4+ также проверяется исходный файл. Hook может работать до 90 секунд, готовность затем ожидается до 90 секунд. TTL сессии для этого теста — минимум 300 секунд. Успех не доказывает, что hook действительно перезапустил БД: приложите команды/состояния контейнеров до и после. + +## Проверка отказа, lab3+ + +Реализуйте `scripts/stop-one.sh` на основе примера. `TARGET_INSTANCE_ID` в окружении содержит alias обслужившей тест API-реплики: сопоставьте его своему контейнеру/Swarm task и остановите именно его. Скрипт должен быстро вернуть 0 и **оставить эту реплику остановленной**; восстановление выполняйте отдельно. Swarm может создать новую task с другим ID — это допустимо. + +```sh +chmod +x scripts/stop-one.sh +make test-failover ACTION_SCRIPT=scripts/stop-one.sh +``` + +Перед отказом тест наблюдает ≥2 API-реплики; 15 секунд отправляет сообщения параллельно выполнению hook, повторяет неопределённый POST с тем же ключом, проверяет восстановление записи за ≤10 секунд, отсутствие остановленной реплики в последних ответах, сохранность подтверждённых сообщений и отсутствие дублей. Ошибки переходного периода учитываются. Затем восстановите реплику и повторите для другой. Скрипт — проверка одного отказа API, не гарантия HA БД/LB/host. Вывод hook скрыт, чтобы не утекли секреты; отлаживайте его отдельно с безопасным выводом. + +## Нагрузка + +```sh +python3 tests/load.py --duration 30 --concurrency 4 --output evidence/load.json +``` + +Это простой **closed-loop** генератор POST сообщений; он ограничен производительностью клиента и страдает coordinated omission. Он выдаёт successful RPS, ошибки и p50/p95/p99 **только успешных запросов**. Во время нагрузки нет прозрачных retry; timeout мог скрыть совершённую запись, поэтому это throughput HTTP-подтверждений, не точный счётчик COMMIT. Изменение размера истории входит в профиль. Для серьёзного исследования используйте k6/Locust/wrk либо свой обоснованный генератор, а не выводите максимальную пропускную способность из одного запуска этого скрипта. Для нагрузки pipeline изображений нужен отдельный сценарий студента. + +## HTTPS, lab7 + +```sh +make test BASE_URL=https://localhost:8443 CA_FILE=/absolute/path/to/ca.crt +make test-security BASE_URL=https://localhost:8443 CA_FILE=/absolute/path/to/ca.crt +``` + +Все скрипты принимают `--ca-file`/`CA_FILE` и проверяют серверный сертификат и hostname. `--insecure` отсутствует. TLS-тест сначала проверяет рабочее доверенное соединение, затем намеренно пустой trust store и именно ошибку проверки сертификата; network timeout не засчитывается как правильный отказ. **Внутреннее mTLS, identity/authorization, OpenBao policy и hardening проверяют отдельные тесты студента** по trust matrix. Клиентский сертификат внешнему учебному REST-клиенту не требуется: mTLS находится на внутренних связях. + +## Что ещё остаётся доказать + +Smoke не доказывает persistence, число реальных контейнеров, durability брокера, outbox, отсутствие утечек/уязвимостей, полноту telemetry или выполнение уровня 4/5. Конкурентные/нагрузочные/негативные проверки своего решения добавляйте отдельно. Список защиты текущей лабы находится в README.md. Проверки рассчитаны на localhost-стенд, не на production. diff --git a/tests/client.py b/tests/client.py new file mode 100644 index 0000000..f0499a2 --- /dev/null +++ b/tests/client.py @@ -0,0 +1,217 @@ +"""HTTP helpers for public black-box tests; Python 3.9+, standard library only.""" +import base64 +import datetime as dt +import hashlib +import json +import os +from pathlib import Path +import re +import ssl +import time +import urllib.error +import urllib.request +import uuid + +ROOT = Path(__file__).resolve().parents[1] +LAB = json.loads((ROOT / 'lab.json').read_text())['number'] +SPEC = json.loads((ROOT / 'contracts/openapi.json').read_text()) + +class Failure(AssertionError): + pass + +def check(condition, message): + if not condition: + raise Failure(message) + +def timestamp(value): + check(isinstance(value, str) and value.endswith('Z'), 'timestamp must be UTC ending in Z') + try: + return dt.datetime.fromisoformat(value[:-1] + '+00:00') + except ValueError as exc: + raise Failure('invalid RFC3339 timestamp') from exc + +def validate(value, schema, where='response'): + """Validate the JSON Schema subset used by the supplied contract, not arbitrary OpenAPI.""" + if '$ref' in schema: + target = SPEC + for part in schema['$ref'].split('/')[1:]: + target = target[part] + return validate(value, target, where) + kinds = schema.get('type', []) + if isinstance(kinds, str): + kinds = [kinds] + matches = {'null':value is None, 'boolean':isinstance(value,bool), 'integer':isinstance(value,int) and not isinstance(value,bool), 'number':isinstance(value,(int,float)) and not isinstance(value,bool), 'string':isinstance(value,str), 'array':isinstance(value,list), 'object':isinstance(value,dict)} + if kinds: + check(any(matches.get(k,False) for k in kinds), where + ': incorrect type') + if 'enum' in schema: + check(value in schema['enum'], where + ': invalid enum') + if 'const' in schema: + check(value == schema['const'], where + ': invalid const') + if isinstance(value,dict): + props = schema.get('properties',{}) + check(all(k in value for k in schema.get('required',[])), where + ': missing required fields') + if schema.get('additionalProperties') is False: + check(not set(value).difference(props), where + ': unexpected fields') + for key, sub in props.items(): + if key in value: + validate(value[key], sub, where + '.' + key) + if isinstance(value,list): + check(len(value) >= schema.get('minItems',0), where + ': too few items') + check(len(value) <= schema.get('maxItems',float('inf')), where + ': too many items') + if schema.get('uniqueItems'): + encoded = [json.dumps(x,sort_keys=True) for x in value] + check(len(encoded)==len(set(encoded)), where + ': duplicate items') + if 'items' in schema: + for item in value: + validate(item, schema['items'], where + '[]') + if isinstance(value,str): + check(len(value) >= schema.get('minLength',0), where + ': too short') + check(len(value) <= schema.get('maxLength',float('inf')), where + ': too long') + if 'pattern' in schema: + check(re.search(schema['pattern'], value) is not None, where + ': pattern mismatch') + if schema.get('format') == 'uuid': + try: + uuid.UUID(value) + except ValueError as exc: + raise Failure(where + ': invalid UUID') from exc + if schema.get('format') == 'date-time': + timestamp(value) + if isinstance(value,(int,float)) and not isinstance(value,bool): + check(value >= schema.get('minimum',-float('inf')), where + ': below minimum') + check(value <= schema.get('maximum',float('inf')), where + ': above maximum') + if 'anyOf' in schema: + for alternative in schema['anyOf']: + try: + validate(value, alternative, where) + break + except Failure: + pass + else: + raise Failure(where + ': no anyOf branch matches') + +def shape(value, name): + validate(value, SPEC['components']['schemas'][name]) + return value + +class NoRedirect(urllib.request.HTTPRedirectHandler): + def redirect_request(self, req, fp, code, msg, headers, newurl): + return None + +class Client: + def __init__(self, base_url=None, ca_file=None, timeout=10): + self.base = (base_url or os.environ.get('BASE_URL') or ('https://localhost:8443' if LAB==7 else 'http://localhost:8080')).rstrip('/') + check(self.base.startswith(('http://','https://')), 'BASE_URL must be HTTP(S)') + check(LAB != 7 or self.base.startswith('https://'), 'lab7 requires HTTPS') + self.timeout = timeout + context = ssl.create_default_context(cafile=ca_file or os.environ.get('CA_FILE') or None) + self.opener = urllib.request.build_opener(NoRedirect(), urllib.request.HTTPSHandler(context=context)) + + def call(self, method, path, expected=200, body=None, actor=None, headers=None, raw=None, schema=None): + h = {'Accept':'application/json'} + if actor: + h['X-User-Id' if LAB==1 else 'Authorization'] = actor['id'] if LAB==1 else 'Bearer ' + actor['token'] + if body is not None: + raw = json.dumps(body,ensure_ascii=False).encode('utf-8') + h['Content-Type'] = 'application/json' + h.update(headers or {}) + req = urllib.request.Request(self.base + path, data=raw, headers=h, method=method) + start = time.monotonic() + try: + response = self.opener.open(req, timeout=self.timeout) + except urllib.error.HTTPError as error: + response = error + except (urllib.error.URLError,TimeoutError,OSError) as exc: + # Do not print URL query, headers, request body, or credentials. + raise Failure(method + ' ' + path.split('?')[0] + ': connection/TLS failure (' + type(exc).__name__ + ')') from None + with response: + status = response.code + rh = response.headers + data = response.read(16*1024*1024 + 1) + check(len(data) <= 16*1024*1024, 'response exceeds test safety limit') + allowed = [expected] if isinstance(expected,int) else expected + check(status in allowed, method + ' ' + path.split('?')[0] + ': expected ' + str(allowed) + ', received ' + str(status)) + check(bool(rh.get('X-Request-Id')), 'missing X-Request-Id') + if LAB>=3: + check(bool(rh.get('X-Instance-Id')), 'missing X-Instance-Id') + payload = None + if schema or status>=400: + check(rh.get_content_type()=='application/json', 'expected application/json') + try: + payload = json.loads(data) + except (ValueError,UnicodeError): + raise Failure('invalid response JSON') from None + shape(payload, 'Error' if status>=400 else schema) + if status>=400: + check(payload['error']['request_id']==rh.get('X-Request-Id'),'error request_id differs from header') + if status==401 and LAB>=2: + scheme = 'Basic' if path=='/api/v1/auth/sessions' else 'Bearer' + check(rh.get('WWW-Authenticate','').lower().startswith(scheme.lower()), 'incorrect WWW-Authenticate challenge') + if status==204: + check(not data, '204 must not contain body') + return {'status':status,'headers':rh,'json':payload,'bytes':data,'elapsed':time.monotonic()-start} + + def user(self, label): + username = 'u_' + label + '_' + uuid.uuid4().hex[:12] + password = 'T3st-' + uuid.uuid4().hex + body = {'username':username,'display_name':'Студент ' + label} + if LAB>=2: + body['password'] = password + user = self.call('POST','/api/v1/users',201,body=body,schema='User')['json'] + check(user['username']==username,'username changed') + actor = {'id':user['id'],'user':user,'registration':body} + if LAB>=2: + credential = base64.b64encode((username+':'+password).encode()).decode() + session = self.call('POST','/api/v1/auth/sessions',201,headers={'Authorization':'Basic '+credential},schema='Session')['json'] + check(session['user']==user,'session user mismatch') + check(timestamp(session['expires_at']) > dt.datetime.now(dt.timezone.utc),'session already expired') + actor['token'] = session['token'] + return actor + + def bootstrap(self): + self.call('GET','/health/live',schema='Health') + self.call('GET','/health/ready',schema='Health') + alice, bob, eve = (self.user(label) for label in ('alice','bob','eve')) + chat = self.call('POST','/api/v1/chats',201,actor=alice,body={'title':'Контрактный тест','member_ids':[alice['id'],bob['id']]},schema='Chat')['json'] + check(set(chat['member_ids'])=={alice['id'],bob['id']},'chat member mismatch') + return alice,bob,eve,chat + + def message(self, actor, chat, text, key=None, attachments=None): + body = {'text':text} + if attachments is not None: + body['attachment_ids'] = attachments + headers = {'Idempotency-Key':key or uuid.uuid4().hex} if LAB>=3 else {} + return self.call('POST','/api/v1/chats/'+chat['id']+'/messages',201,actor=actor,body=body,headers=headers,schema='Message') + + def attachment(self, actor, chat): + content = (ROOT / 'tests/fixtures/sample.png').read_bytes() + att = self.call('POST','/api/v1/chats/'+chat['id']+'/attachments?filename=sample.png',201 if LAB==4 else 202,actor=actor,raw=content,headers={'Content-Type':'image/png'},schema='Attachment')['json'] + check(att['status']==('ready' if LAB==4 else 'queued'),'incorrect upload status') + check(att['chat_id']==chat['id'] and att['owner_id']==actor['id'],'attachment ownership mismatch') + check(att['sha256']==hashlib.sha256(content).hexdigest() and att['size_bytes']==len(content),'original checksum/size mismatch') + return att,content + + def wait_ready(self, actor, att, wait_seconds=60): + deadline = time.monotonic()+wait_seconds + while time.monotonic()=2,'persistence requires lab2+') + check(args.mode!='failover' or LAB>=3,'failover requires lab3+') + script = Path(args.action_script).expanduser().resolve() + check(script.is_file() and os.access(script,os.X_OK),'action script must exist and be executable (chmod +x)') + check('.example.' not in script.name,'copy and implement the example hook first') + c = Client(args.base_url,args.ca_file,timeout=2) + alice,bob,eve,chat = c.bootstrap() + sent = c.message(alice,chat,'Сохранить при отказе') + original = sent['json'] + target = sent['headers'].get('X-Instance-Id','') + attachment = content = None + if LAB>=4: + attachment,content = c.attachment(alice,chat) + if LAB>=5: + attachment = c.wait_ready(alice,attachment) + env = dict(os.environ) + env['TARGET_INSTANCE_ID'] = target + observed = set() + if args.mode=='failover': + for _ in range(40): + observed.add(c.call('GET','/api/v1/users/me',actor=alice,schema='User')['headers']['X-Instance-Id']) + check(len(observed)>=2,'less than two API instances observed before failure; verify LB/session affinity') + print('Executing explicit '+args.mode+' hook; hook output suppressed to avoid leaking secrets.') + # No shell interpolation and no Docker commands in this test. + proc = subprocess.Popen([str(script)],env=env,stdout=subprocess.DEVNULL,stderr=subprocess.DEVNULL) + started = time.monotonic() + successes,failures,after_instances = [],0,[] + try: + if args.mode=='persistence': + try: + code = proc.wait(timeout=90) + except subprocess.TimeoutExpired: + raise Failure('restart hook exceeded 90 seconds') from None + check(code==0,'restart hook failed (inspect your script locally)') + deadline = time.monotonic()+90 + while True: + try: + c.call('GET','/health/ready',schema='Health') + c.call('GET','/api/v1/users/me',actor=alice,schema='User') + break + except Failure: + check(time.monotonic()=5,'too few successful writes after stop') + check(target not in after_instances[-5:],'target replica still serves requests; hook must leave it stopped') + print(json.dumps({'observed_instances_before':len(observed),'successful_writes':len(successes),'failed_attempts':failures,'first_recovery_seconds':round(first_recovery,3)},ensure_ascii=False)) + # Existing token, no re-login. Read all confirmations and reject duplicates. + messages = history(c,bob,chat) + ids = [m['id'] for m in messages] + check(len(ids)==len(set(ids)),'duplicated message IDs in history') + check(any(m==original for m in messages),'confirmed pre-failure message lost or altered') + for msg in successes: + check(any(m==msg for m in messages),'confirmed in-flight message lost or altered') + # Bodies are unique in this scenario: an uncertain request may exist once, never twice. + texts = [m['text'] for m in messages] + check(len(texts)==len(set(texts)),'uncertain retry created duplicate message') + if attachment: + c.call('GET','/api/v1/attachments/'+attachment['id'],actor=bob,schema='Attachment') + downloaded = c.call('GET','/api/v1/attachments/'+attachment['id']+'/content',actor=bob) + check(downloaded['bytes']==content,'attachment lost or changed across failure') + print('PASS: '+args.mode+' preserved confirmed data and existing session. Hook scope needs operator evidence.') + finally: + if proc.poll() is None: + proc.terminate() + try: + proc.wait(timeout=5) + except subprocess.TimeoutExpired: + proc.kill() + proc.wait() + +if __name__=='__main__': + run(main) diff --git a/tests/smoke.py b/tests/smoke.py new file mode 100644 index 0000000..4cbfa55 --- /dev/null +++ b/tests/smoke.py @@ -0,0 +1,82 @@ +#!/usr/bin/env python3 +"""One complete public acceptance scenario, cumulative by lab number.""" +import base64 +import hashlib +import uuid +from client import Client, LAB, arguments, check, run, timestamp + + +def main(): + args = arguments('Messenger public smoke; creates synthetic users and messages') + c = Client(args.base_url,args.ca_file) + alice,bob,eve,chat = c.bootstrap() + path = '/api/v1/chats/'+chat['id'] + c.call('POST','/api/v1/users',409,body=alice['registration']) + c.call('GET','/api/v1/users/me',401) + c.call('GET',path,404,actor=eve) + me = c.call('GET','/api/v1/users/me',actor=alice,schema='User')['json'] + check(me==alice['user'],'current user mismatch') + listed = c.call('GET','/api/v1/chats?limit=100',actor=bob,schema='ChatPage')['json'] + check(any(x['id']==chat['id'] for x in listed['items']),'member cannot list chat') + hidden = c.call('GET','/api/v1/chats?limit=100',actor=eve,schema='ChatPage')['json'] + check(all(x['id']!=chat['id'] for x in hidden['items']),'chat leaks to outsider') + key = uuid.uuid4().hex + first = c.message(alice,chat,'Привет, мир 👋',key=key)['json'] + second = c.message(bob,chat,'Сообщение Боба')['json'] + check(first['sender_id']==alice['id'] and second['sender_id']==bob['id'],'sender was not derived from actor') + check(first['chat_id']==second['chat_id']==chat['id'],'wrong chat in message') + check(first['text']=='Привет, мир 👋' and second['text']=='Сообщение Боба','message text changed') + page1 = c.call('GET',path+'/messages?limit=1',actor=bob,schema='MessagePage')['json'] + check(len(page1['items'])==1 and page1['next_cursor'],'first page must have one item and cursor') + from urllib.parse import quote + page2 = c.call('GET',path+'/messages?limit=1&cursor='+quote(page1['next_cursor'],safe=''),actor=alice,schema='MessagePage')['json'] + check(len(page2['items'])==1 and page2['next_cursor'] is None,'second page must finish history') + ordered = sorted([first,second],key=lambda x:(timestamp(x['created_at']),uuid.UUID(x['id']).int)) + check(page1['items']+page2['items']==ordered,'pagination lost, duplicated or reordered a message') + h = {'Idempotency-Key':uuid.uuid4().hex} if LAB>=3 else {} + c.call('POST',path+'/messages',400,actor=alice,body={'text':''},headers=h) + c.call('POST',path+'/messages',404,actor=eve,body={'text':'чужое'},headers=h) + c.call('GET',path+'/messages?limit=0',400,actor=alice) + if LAB>=2: + bad = base64.b64encode((alice['registration']['username']+':wrong-password').encode()).decode() + c.call('POST','/api/v1/auth/sessions',401,headers={'Authorization':'Basic '+bad}) + good = base64.b64encode((alice['registration']['username']+':'+alice['registration']['password']).encode()).decode() + c.call('GET','/api/v1/users/me',401,headers={'Authorization':'Basic '+good}) + c.call('GET','/api/v1/users/me',401,headers={'X-User-Id':alice['id']}) + me = c.call('GET','/api/v1/users/me',actor=alice,headers={'X-User-Id':eve['id']},schema='User')['json'] + check(me['id']==alice['id'],'X-User-Id overrode bearer identity') + if LAB>=3: + replay = c.message(alice,chat,first['text'],key=key)['json'] + check(replay==first,'idempotency replay differs') + c.call('POST',path+'/messages',409,actor=alice,body={'text':'другой body'},headers={'Idempotency-Key':key}) + c.call('POST',path+'/messages',400,actor=alice,body={'text':'без ключа'}) + if LAB>=4: + att,content = c.attachment(alice,chat) + # A queued attachment must already be linkable to its own chat. + attached = c.message(alice,chat,'',attachments=[att['id']])['json'] + check(attached['attachment_ids']==[att['id']],'message lost attachment') + ready = c.wait_ready(bob,att) if LAB>=5 else att + check(ready['error_code'] is None,'ready attachment has an error') + download = c.call('GET','/api/v1/attachments/'+att['id']+'/content',actor=bob) + check(download['bytes']==content,'download differs from original') + check(download['headers'].get_content_type()=='image/png','original content type mismatch') + for suffix in ('','/content'): + c.call('GET','/api/v1/attachments/'+att['id']+suffix,404,actor=eve) + if LAB>=5: + variants = [x for x in ready['variants'] if x['name']=='thumbnail'] + check(len(variants)==1,'expected exactly one thumbnail') + v = variants[0] + check((v['width'],v['height'])==(256,160),'thumbnail metadata has wrong dimensions') + thumb = c.call('GET','/api/v1/attachments/'+att['id']+'/content?variant=thumbnail',actor=bob) + check(thumb['headers'].get_content_type()=='image/jpeg','thumbnail content type mismatch') + check(len(thumb['bytes'])==v['size_bytes'] and hashlib.sha256(thumb['bytes']).hexdigest()==v['sha256'],'thumbnail checksum mismatch') + from image_probe import jpeg_size + check(jpeg_size(thumb['bytes'])==(256,160),'actual JPEG dimensions mismatch') + if LAB>=2: + c.call('DELETE','/api/v1/auth/sessions/current',204,actor=alice) + c.call('GET','/api/v1/users/me',401,actor=alice) + c.call('DELETE','/api/v1/auth/sessions/current',401,actor=alice) + print('PASS: lab%d public API scenario; infrastructure and grading evidence remain separate.' % LAB) + +if __name__=='__main__': + run(main) diff --git a/tests/test_own.py b/tests/test_own.py new file mode 100644 index 0000000..7dda70f --- /dev/null +++ b/tests/test_own.py @@ -0,0 +1,162 @@ +"""Собственные тесты (перенесены из lab1; X-User-Id заменён на Bearer, добавлены проверки lab2). + +Запуск: pytest tests/test_own.py tests/test_race.py -v (API должен быть запущен на BASE_URL) +""" +import base64 +import json +import os +import urllib.error +import urllib.parse +import urllib.request +import uuid + +BASE_URL = os.environ.get("BASE_URL", "http://localhost:8080") +PASSWORD = "Correct-horse-battery-1" + + +def request(method, path, body=None, headers=None): + h = dict(headers or {}) + data = None + if body is not None: + data = json.dumps(body).encode() + h["Content-Type"] = "application/json" + req = urllib.request.Request(BASE_URL + path, data=data, method=method, headers=h) + try: + with urllib.request.urlopen(req) as r: + return r.status, r.read() + except urllib.error.HTTPError as e: + return e.code, e.read() + + +def basic(username, password): + return {"Authorization": "Basic " + base64.b64encode((username + ":" + password).encode()).decode()} + + +def make_user(prefix="u"): + """Регистрация + вход. Возвращает пользователя с полями token и auth (заголовок Bearer).""" + username = f"{prefix}{uuid.uuid4().hex[:8]}" + s, b = request("POST", "/api/v1/users", {"username": username, "display_name": "T", "password": PASSWORD}) + assert s == 201, b + user = json.loads(b) + s, b = request("POST", "/api/v1/auth/sessions", headers=basic(username, PASSWORD)) + assert s == 201, b + user["token"] = json.loads(b)["token"] + user["auth"] = {"Authorization": "Bearer " + user["token"]} + return user + + +# ---------- тесты lab1 (в новой аутентификации) ---------- +def test_invalid_json(): + req = urllib.request.Request(BASE_URL + "/api/v1/users", data=b"not json", method="POST", + headers={"Content-Type": "application/json"}) + try: + urllib.request.urlopen(req) + assert False + except urllib.error.HTTPError as e: + assert e.code == 400 + + +def test_duplicate_username(): + u = make_user("dup") + s, _ = request("POST", "/api/v1/users", {"username": u["username"], "display_name": "X", "password": PASSWORD}) + assert s == 409 + + +def test_extra_fields(): + s, _ = request("POST", "/api/v1/users", {"username": "ex" + uuid.uuid4().hex[:6], "display_name": "X", + "password": PASSWORD, "extra": 1}) + assert s == 400 + + +def test_empty_message(): + u = make_user("em") + s, b = request("POST", "/api/v1/chats", {"title": "T", "member_ids": [u["id"]]}, u["auth"]) + chat = json.loads(b) + s, _ = request("POST", f"/api/v1/chats/{chat['id']}/messages", {"text": " "}, u["auth"]) + assert s == 400 + + +def test_foreign_chat(): + u1, u2 = make_user("a"), make_user("b") + s, b = request("POST", "/api/v1/chats", {"title": "T", "member_ids": [u1["id"]]}, u1["auth"]) + chat = json.loads(b) + s, _ = request("POST", f"/api/v1/chats/{chat['id']}/messages", {"text": "hi"}, u2["auth"]) + assert s == 404 + + +def test_pagination(): + u = make_user("pg") + s, b = request("POST", "/api/v1/chats", {"title": "T", "member_ids": [u["id"]]}, u["auth"]) + chat = json.loads(b) + for i in range(5): + request("POST", f"/api/v1/chats/{chat['id']}/messages", {"text": f"m{i}"}, u["auth"]) + ids, cursor = [], None + while True: + path = f"/api/v1/chats/{chat['id']}/messages?limit=2" + if cursor: + path += "&cursor=" + urllib.parse.quote(cursor, safe="") + s, b = request("GET", path, None, u["auth"]) + d = json.loads(b) + ids.extend(m["id"] for m in d["items"]) + cursor = d["next_cursor"] + if not cursor: + break + assert len(ids) == 5 and len(set(ids)) == 5 + + +def test_cursor_from_other_chat_is_400(): + u = make_user("cur") + chats = [] + for t in ("A", "B"): + s, b = request("POST", "/api/v1/chats", {"title": t, "member_ids": [u["id"]]}, u["auth"]) + chats.append(json.loads(b)) + for i in range(3): + request("POST", f"/api/v1/chats/{chats[-1]['id']}/messages", {"text": f"m{i}"}, u["auth"]) + s, b = request("GET", f"/api/v1/chats/{chats[0]['id']}/messages?limit=1", None, u["auth"]) + cursor = json.loads(b)["next_cursor"] + assert cursor + s, _ = request("GET", f"/api/v1/chats/{chats[0]['id']}/messages?limit=1&cursor=" + urllib.parse.quote(cursor, safe=""), None, u["auth"]) + assert s == 200 + s, _ = request("GET", f"/api/v1/chats/{chats[1]['id']}/messages?limit=1&cursor=" + urllib.parse.quote(cursor, safe=""), None, u["auth"]) + assert s == 400 + + +# ---------- новое в lab2 ---------- +def test_x_user_id_no_longer_grants_access(): + u = make_user("xu") + s, _ = request("GET", "/api/v1/users/me", None, {"X-User-Id": u["id"]}) + assert s == 401 + + +def test_basic_only_on_login(): + u = make_user("bo") + s, _ = request("GET", "/api/v1/users/me", None, basic(u["username"], PASSWORD)) + assert s == 401 + s, _ = request("POST", "/api/v1/auth/sessions", headers=u["auth"]) # Bearer на /auth/sessions не принимается + assert s == 401 + + +def test_wrong_password_and_unknown_user_look_the_same(): + u = make_user("wp") + s1, b1 = request("POST", "/api/v1/auth/sessions", headers=basic(u["username"], "wrong-password-123")) + s2, b2 = request("POST", "/api/v1/auth/sessions", headers=basic("nobody" + uuid.uuid4().hex[:6], "wrong-password-123")) + assert s1 == s2 == 401 + assert json.loads(b1)["error"]["message"] == json.loads(b2)["error"]["message"] + + +def test_logout_revokes_token(): + u = make_user("lo") + assert request("GET", "/api/v1/users/me", None, u["auth"])[0] == 200 + assert request("DELETE", "/api/v1/auth/sessions/current", None, u["auth"])[0] == 204 + assert request("GET", "/api/v1/users/me", None, u["auth"])[0] == 401 + + +def test_password_is_never_returned(): + u = make_user("np") + s, b = request("GET", "/api/v1/users/me", None, u["auth"]) + assert s == 200 and "password" not in b.decode() and "hash" not in b.decode() + + +def test_short_password_rejected(): + s, _ = request("POST", "/api/v1/users", {"username": "sp" + uuid.uuid4().hex[:6], "display_name": "X", "password": "short"}) + assert s == 400 diff --git a/tests/test_race.py b/tests/test_race.py new file mode 100644 index 0000000..d1d65bd --- /dev/null +++ b/tests/test_race.py @@ -0,0 +1,36 @@ +"""Гонки (перенесено из lab1 + гонка регистрации одинакового username, требуемая уровнем 4).""" +import json +import threading +import uuid +from concurrent.futures import ThreadPoolExecutor + +from test_own import PASSWORD, make_user, request + + +def test_concurrent_writes(): + u = make_user("race") + _, b = request("POST", "/api/v1/chats", {"title": "R", "member_ids": [u["id"]]}, u["auth"]) + chat = json.loads(b) + + def worker(cid): + for i in range(10): + request("POST", f"/api/v1/chats/{chat['id']}/messages", {"text": f"c{cid}-m{i}"}, u["auth"]) + + threads = [threading.Thread(target=worker, args=(i,)) for i in range(10)] + for t in threads: + t.start() + for t in threads: + t.join() + + _, b = request("GET", f"/api/v1/chats/{chat['id']}/messages?limit=100", None, u["auth"]) + d = json.loads(b) + assert len(d["items"]) == 100, len(d["items"]) + assert len({m["id"] for m in d["items"]}) == 100 + + +def test_concurrent_registration_same_username(): + """16 одновременных регистраций одного username: ровно одна успешна, остальные — 409 (решает UNIQUE в БД).""" + body = {"username": "race_" + uuid.uuid4().hex[:12], "display_name": "R", "password": PASSWORD} + with ThreadPoolExecutor(max_workers=16) as pool: + codes = list(pool.map(lambda _: request("POST", "/api/v1/users", body)[0], range(16))) + assert codes.count(201) == 1 and codes.count(409) == 15, codes diff --git a/tests_student/common.py b/tests_student/common.py new file mode 100644 index 0000000..390cc98 --- /dev/null +++ b/tests_student/common.py @@ -0,0 +1,24 @@ +"""Общие помощники собственных тестов; переиспользуют публичный клиент tests/client.py (он не изменялся).""" +import base64 +import os +import sys +from pathlib import Path + +sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "tests")) +from client import Client, Failure, check # noqa: E402,F401 + +BASE = os.environ.get("BASE_URL", "http://localhost:8080") + + +def client(): + return Client(BASE) + + +def basic(username, password): + return {"Authorization": "Basic " + base64.b64encode((username + ":" + password).encode()).decode()} + + +def parse_json(response): + """Публичный клиент парсит тело только при schema=...; для наших проверок нужен JSON всегда.""" + import json + return json.loads(response["bytes"]) if response["bytes"] else None diff --git a/tests_student/test_db_rollback.py b/tests_student/test_db_rollback.py new file mode 100644 index 0000000..c265612 --- /dev/null +++ b/tests_student/test_db_rollback.py @@ -0,0 +1,47 @@ +#!/usr/bin/env python3 +"""Откат составной операции создания чата. + +Через HTTP «сломать середину» транзакции нельзя (валидация отсекает ошибку раньше), +поэтому вызываем repo.create_chat напрямую с check_members=False: вставка в chats проходит, +а вставка в chat_members падает на внешнем ключе. Ожидаем: в chats не осталось НИЧЕГО. +Требует DATABASE_URL_FILE/DATABASE_URL (как у приложения). +""" +import sys +import uuid +from pathlib import Path + +sys.path.insert(0, str(Path(__file__).resolve().parents[1])) +import psycopg # noqa: E402 + +from app import db, repo, security # noqa: E402 + + +def main(): + with db.connection() as conn: + creator = repo.insert_user(conn, "rb_" + uuid.uuid4().hex[:12], "Rollback", security.hash_password("Rollback-password-1")) + ghost = uuid.uuid4() # такого пользователя нет -> FK violation на втором INSERT + marker = "rollback-" + uuid.uuid4().hex + try: + with db.connection() as conn: + repo.create_chat(conn, creator["id"], marker, [creator["id"], ghost], check_members=False) + except psycopg.errors.ForeignKeyViolation: + pass + else: + raise SystemExit("FAIL: FK violation не произошёл — тест не проверяет откат") + with db.connection() as conn: + left = conn.execute("SELECT count(*) AS n FROM chats WHERE title = %s", (marker,)).fetchone()["n"] + members = conn.execute("SELECT count(*) AS n FROM chat_members WHERE user_id = %s", (ghost,)).fetchone()["n"] + if left or members: + raise SystemExit("FAIL: после ошибки остались строки: chats=%d members=%d" % (left, members)) + # Позитивный контроль: тот же вызов с валидными данными фиксирует и чат, и участников. + with db.connection() as conn: + chat = repo.create_chat(conn, creator["id"], marker + "-ok", [creator["id"]]) + with db.connection() as conn: + n = conn.execute("SELECT count(*) AS n FROM chat_members WHERE chat_id = %s", (chat["id"],)).fetchone()["n"] + if n != 1: + raise SystemExit("FAIL: контрольный чат создан без участника") + print("PASS: ошибка внутри транзакции откатила вставку chats (0 строк), контрольный commit сохранил чат и участника") + + +if __name__ == "__main__": + main() diff --git a/tests_student/test_dependencies.py b/tests_student/test_dependencies.py new file mode 100644 index 0000000..26056dc --- /dev/null +++ b/tests_student/test_dependencies.py @@ -0,0 +1,109 @@ +#!/usr/bin/env python3 +"""Отказ зависимостей: Redis/Valkey (кэш сессий) и PostgreSQL. + +Команды управления задаются переменными окружения (по умолчанию — docker compose из корня репозитория): + CACHE_STOP, CACHE_START, CACHE_FLUSH, DB_STOP, DB_START +Ожидания: + * кэш недоступен/сброшен -> API продолжает работать (данные берутся из PostgreSQL), /health/ready = 200; + * PostgreSQL недоступен -> /health/ready = 503, бизнес-запросы = 503 (ограниченная ошибка), + запрос без валидной сессии НИКОГДА не получает 200; + * после восстановления прежний токен и данные на месте. +""" +import os +import shlex +import subprocess +import time +import uuid + +from common import Failure, check, client, parse_json + +DC = "docker compose --env-file .env" +CMD = { + "CACHE_STOP": os.environ.get("CACHE_STOP", DC + " stop valkey"), + "CACHE_START": os.environ.get("CACHE_START", DC + " start valkey"), + "CACHE_FLUSH": os.environ.get("CACHE_FLUSH", DC + " exec -T valkey sh -c 'REDISCLI_AUTH=$(cat /run/secrets/valkey_password) valkey-cli flushall'"), + "DB_STOP": os.environ.get("DB_STOP", DC + " stop postgres"), + "DB_START": os.environ.get("DB_START", DC + " start postgres"), +} + + +def run(name): + print(" $", name, flush=True) + r = subprocess.run(CMD[name], shell=True, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL, timeout=90) + check(r.returncode == 0, "команда %s завершилась с кодом %d" % (name, r.returncode)) + + +def wait_ready(c, seconds=60): + end = time.monotonic() + seconds + while True: + try: + c.call("GET", "/health/ready", 200) + return + except Failure: + check(time.monotonic() < end, "API не стал ready за %ds" % seconds) + time.sleep(0.5) + + +def main(): + c = client() + alice, bob = c.user("dep_a"), c.user("dep_b") + chat = c.call("POST", "/api/v1/chats", 201, actor=alice, body={"title": "dep", "member_ids": [alice["id"], bob["id"]]}, schema="Chat")["json"] + c.message(alice, chat, "до отказа") + c.call("GET", "/api/v1/users/me", 200, actor=alice) # токен гарантированно в кэше + stray = {"Authorization": "Bearer " + "Z" * 43} + + print("1) Valkey остановлен") + run("CACHE_STOP") + try: + for _ in range(3): + c.call("GET", "/health/ready", 200) # кэш — не критичная зависимость + check(c.call("GET", "/api/v1/users/me", 200, actor=alice)["elapsed"] < 2.5, "обход кэша слишком медленный") + c.message(alice, chat, "пока кэш лежит") + c.call("GET", "/api/v1/users/me", 401, headers=stray) # анонимный/чужой токен по-прежнему 401 + c.call("GET", "/api/v1/users/me", 401) + new = c.user("dep_new") # вход и регистрация работают без кэша + c.call("GET", "/api/v1/users/me", 200, actor=new) + c.call("DELETE", "/api/v1/auth/sessions/current", 204, actor=new) # logout без кэша: истина в PostgreSQL + c.call("GET", "/api/v1/users/me", 401, actor=new) + finally: + run("CACHE_START") + time.sleep(2.5) # окно circuit breaker + c.call("GET", "/api/v1/users/me", 200, actor=alice) + + print("2) Кэш сброшен (FLUSHALL): сессии берутся из PostgreSQL") + run("CACHE_FLUSH") + c.call("GET", "/api/v1/users/me", 200, actor=alice) + c.call("GET", "/api/v1/users/me", 200, actor=bob) + + print("3) PostgreSQL остановлен") + run("DB_STOP") + try: + r = c.call("GET", "/health/ready", 503) + check(r["json"]["error"]["code"] == "unavailable", "ready: ожидали code=unavailable") + for path in ("/api/v1/chats", "/api/v1/chats/%s/messages" % chat["id"]): + r = c.call("GET", path, [200, 503], actor=alice) + check(r["status"] == 503, "данные отданы без БД: " + path) + check("psycopg" not in r["bytes"].decode() and "Traceback" not in r["bytes"].decode(), "утечка деталей в 503") + c.call("POST", "/api/v1/users", 503, body={"username": "u" + uuid.uuid4().hex[:10], "display_name": "x", "password": "Password-123456"}) + c.call("GET", "/api/v1/users/me", 401) # без токена — всегда 401, не «доверенный аноним» + r = c.call("GET", "/api/v1/users/me", [401, 503], headers=stray) + check(r["status"] != 200, "неизвестный токен принят при недоступной БД") + c.call("GET", "/health/live", 200) # процесс жив, хоть и не ready + finally: + run("DB_START") + wait_ready(c) + + print("4) Восстановление") + c.call("GET", "/api/v1/users/me", 200, actor=alice) # тот же токен, без повторного входа + texts = [m["text"] for m in parse_json(c.call("GET", "/api/v1/chats/%s/messages?limit=100" % chat["id"], actor=bob))["items"]] + check(texts == ["до отказа", "пока кэш лежит"], "история изменилась: %s" % texts) + c.message(bob, chat, "после восстановления") + print("PASS: кэш и БД отказывают предсказуемо: кэш обходится, БД -> 503, анонимный доступ невозможен, данные и сессии целы") + + +if __name__ == "__main__": + try: + main() + except Failure as exc: + print("FAIL:", exc) + raise SystemExit(1) diff --git a/tests_student/test_expiry.py b/tests_student/test_expiry.py new file mode 100644 index 0000000..3ad3162 --- /dev/null +++ b/tests_student/test_expiry.py @@ -0,0 +1,36 @@ +#!/usr/bin/env python3 +"""Истечение сессии. Запускать против API, поднятого с коротким SESSION_TTL_SECONDS (например 2). +Проверяет и путь «через кэш» (токен успели использовать => он в Valkey), и путь «только PostgreSQL».""" +import sys +import time + +import datetime as dt + +from common import Failure, basic, check, client +from client import timestamp # доступен через sys.path, настроенный в common + + +def main(): + ttl = float(sys.argv[1]) if len(sys.argv) > 1 else 2.0 + c = client() + a = c.user("exp") + # Свежий вход: кэш прогрет логином; затем ещё читаем, чтобы запись точно была в Valkey. + sess = c.call("POST", "/api/v1/auth/sessions", 201, headers=basic(a["registration"]["username"], a["registration"]["password"]), schema="Session")["json"] + lifetime = (timestamp(sess["expires_at"]) - dt.datetime.now(dt.timezone.utc)).total_seconds() + check(lifetime <= ttl + 0.5, "expires_at (%.1f c) не соответствует короткому TTL=%s — сервер запущен с другим SESSION_TTL_SECONDS" % (lifetime, ttl)) + h = {"Authorization": "Bearer " + sess["token"]} + c.call("GET", "/api/v1/users/me", 200, headers=h) + c.call("GET", "/api/v1/chats", 200, headers=h) + time.sleep(ttl + 1.5) + c.call("GET", "/api/v1/users/me", 401, headers=h) + c.call("GET", "/api/v1/chats", 401, headers=h) + c.call("DELETE", "/api/v1/auth/sessions/current", 401, headers=h) + print("PASS: сессия с TTL=%ss перестала действовать (401 на users/me, chats, logout) после ожидания %.1fs" % (ttl, ttl + 1.5)) + + +if __name__ == "__main__": + try: + main() + except Failure as exc: + print("FAIL:", exc) + raise SystemExit(1) diff --git a/tests_student/test_integration.py b/tests_student/test_integration.py new file mode 100644 index 0000000..76ee5b4 --- /dev/null +++ b/tests_student/test_integration.py @@ -0,0 +1,197 @@ +#!/usr/bin/env python3 +"""Собственные проверки сверх публичного smoke: гонка регистрации, валидация, пагинация, безопасность.""" +import base64 +import json +import uuid +from concurrent.futures import ThreadPoolExecutor +from urllib.parse import quote + +from common import BASE, Failure, basic, check, client, parse_json + +c = client() +RESULTS = [] + + +def jget(path, actor): + return parse_json(c.call("GET", path, 200, actor=actor)) + + +def case(fn): + try: + fn() + RESULTS.append((fn.__name__, "PASS")) + print("PASS", fn.__name__) + except Failure as exc: + RESULTS.append((fn.__name__, "FAIL")) + print("FAIL", fn.__name__, "-", exc) + return fn + + +def reg(name, pw="Correct-horse-battery-1", display="X", **extra): + return c.call("POST", "/api/v1/users", 201, body={"username": name, "display_name": display, "password": pw, **extra}) + + +@case +def registration_race_same_username(): + name = "race_" + uuid.uuid4().hex[:12] + body = {"username": name, "display_name": "Гонка", "password": "Race-password-123"} + def attempt(_): + return c.call("POST", "/api/v1/users", [201, 409], body=body)["status"] + with ThreadPoolExecutor(max_workers=16) as pool: + codes = list(pool.map(attempt, range(16))) + check(codes.count(201) == 1 and codes.count(409) == 15, "ожидали ровно один 201 и 15 конфликтов: %s" % codes) + + +@case +def username_and_field_validation(): + ok = {"display_name": "X", "password": "Correct-horse-battery-1"} + for bad in ("ab", "UPPER_case", "has space", "a" * 33, "name\n", "имя_юзера"): # "name\n" ловит ошибку с «$» + c.call("POST", "/api/v1/users", 400, body={"username": bad, **ok}) + base = {"username": "val_" + uuid.uuid4().hex[:10], **ok} + c.call("POST", "/api/v1/users", 400, body={**base, "password": "short"}) # < 12 + c.call("POST", "/api/v1/users", 400, body={**base, "password": "x" * 129}) # > 128 + c.call("POST", "/api/v1/users", 400, body={**base, "display_name": " "}) + c.call("POST", "/api/v1/users", 400, body={**base, "display_name": "x" * 101}) + c.call("POST", "/api/v1/users", 400, body={**base, "extra": 1}) + c.call("POST", "/api/v1/users", 400, body={**base, "display_name": 5}) + c.call("POST", "/api/v1/users", 400, raw=b"{not json", headers={"Content-Type": "application/json"}) + c.call("POST", "/api/v1/users", 400, raw=b'{"username":"aaa","username":"bbb"}', headers={"Content-Type": "application/json"}) + c.call("POST", "/api/v1/users", 415, raw=b"x", headers={"Content-Type": "text/plain"}) + c.call("POST", "/api/v1/users", 413, raw=b"{" + b" " * 70000 + b"}", headers={"Content-Type": "application/json"}) + c.call("POST", "/api/v1/users", 400, raw=b'{"username":"aaa","display_name":"\\ud800","password":"Correct-horse-battery-1"}', + headers={"Content-Type": "application/json"}) # одиночный суррогат -> 400, а не 500 + c.call("POST", "/api/v1/users", 400, raw=b'{"username":"aaa","display_name":"a\\u0000b","password":"Correct-horse-battery-1"}', + headers={"Content-Type": "application/json"}) # NUL -> 400 + + +@case +def password_with_colon_and_unicode_login(): + name = "uni_" + uuid.uuid4().hex[:10] + pw = "парoль:с:двоеточием-🔐-123" + reg(name, pw) + r = c.call("POST", "/api/v1/auth/sessions", 201, headers=basic(name, pw), schema="Session") + check(len(r["json"]["token"]) >= 43, "токен слишком короткий (нужно ≥256 бит)") + c.call("POST", "/api/v1/auth/sessions", 401, headers=basic(name, pw + "x")) + + +@case +def login_failures_look_identical(): + name = "same_" + uuid.uuid4().hex[:10] + reg(name) + a = c.call("POST", "/api/v1/auth/sessions", 401, headers=basic(name, "Wrong-password-123")) + b = c.call("POST", "/api/v1/auth/sessions", 401, headers=basic("nobody_" + uuid.uuid4().hex[:8], "Wrong-password-123")) + check(a["json"]["error"]["code"] == b["json"]["error"]["code"] and + a["json"]["error"]["message"] == b["json"]["error"]["message"], "ответы различаются -> user enumeration") + for headers in ({}, {"Authorization": "Basic !!!not-base64"}, {"Authorization": "Basic " + base64.b64encode(b"nocolon").decode()}, + {"Authorization": "Bearer abc"}): + r = c.call("POST", "/api/v1/auth/sessions", 401, headers=headers) + check(r["headers"]["WWW-Authenticate"].startswith("Basic realm=\"messenger\""), "нет Basic challenge") + + +@case +def bearer_rules(): + a = c.user("bearer") + for bad in ({"Authorization": "Bearer " + "A" * 43}, {"Authorization": "Bearer"}, {"Authorization": "Token " + a["token"]}, + {"Authorization": "bearer"}): + r = c.call("GET", "/api/v1/users/me", 401, headers=bad) + check(r["headers"]["WWW-Authenticate"] == 'Bearer realm="messenger"', "нет Bearer challenge") + # регистр схемы не важен (RFC 7235), токен в нижнем регистре схемы работает + c.call("GET", "/api/v1/users/me", 200, headers={"Authorization": "bearer " + a["token"]}) + for path in ("/api/v1/chats", "/api/v1/chats/" + str(uuid.uuid4())): + c.call("GET", path, 401) + + +@case +def logout_revokes_only_that_session(): + a = c.user("lo") + second = c.call("POST", "/api/v1/auth/sessions", 201, headers=basic(a["registration"]["username"], a["registration"]["password"]), schema="Session")["json"] + c.call("DELETE", "/api/v1/auth/sessions/current", 204, actor=a) + c.call("GET", "/api/v1/users/me", 401, actor=a) + c.call("GET", "/api/v1/users/me", 200, headers={"Authorization": "Bearer " + second["token"]}) + + +@case +def chat_creation_rules_and_no_side_effects(): + a, b = c.user("ca"), c.user("cb") + before = len(jget("/api/v1/chats?limit=100", a)["items"]) + ghost = str(uuid.uuid4()) + for members in ([a["id"], ghost], [a["id"], a["id"]], [b["id"]], [], ["not-a-uuid", a["id"]]): + c.call("POST", "/api/v1/chats", 400, actor=a, body={"title": "t", "member_ids": members}) + c.call("POST", "/api/v1/chats", 400, actor=a, body={"title": " ", "member_ids": [a["id"]]}) + after = len(jget("/api/v1/chats?limit=100", a)["items"]) + check(before == after, "неудачное создание чата оставило следы") + c.call("POST", "/api/v1/chats", 201, actor=a, body={"title": "solo", "member_ids": [a["id"]]}, schema="Chat") + + +@case +def message_rules(): + a, b, e = c.user("ma"), c.user("mb"), c.user("me") + chat = c.call("POST", "/api/v1/chats", 201, actor=a, body={"title": "m", "member_ids": [a["id"], b["id"]]}, schema="Chat")["json"] + p = "/api/v1/chats/%s/messages" % chat["id"] + c.call("POST", p, 400, actor=a, body={"text": " "}) + c.call("POST", p, 400, actor=a, body={"text": "x" * 4001}) + c.call("POST", p, 201, actor=a, body={"text": "x" * 4000}) + c.call("POST", p, 400, actor=a, body={"text": "hi", "sender_id": b["id"]}) # sender_id не принимается + c.call("POST", p, 404, actor=e, body={"text": "hi"}) + c.call("POST", p, 404, actor=e, body={"bad": "body"}) # доступ раньше валидации + c.call("POST", "/api/v1/chats/%s/messages" % uuid.uuid4(), 404, actor=a, body={"text": "hi"}) + c.call("POST", "/api/v1/chats/not-a-uuid/messages", 400, actor=a, body={"text": "hi"}) + c.call("GET", "/api/v1/chats/%s" % chat["id"], 404, actor=e) + c.call("GET", "/api/v1/chats/%s/messages" % chat["id"], 404, actor=e) + + +@case +def pagination_walk_and_cursor_binding(): + a, b = c.user("pa"), c.user("pb") + chats = [c.call("POST", "/api/v1/chats", 201, actor=a, body={"title": "c%d" % i, "member_ids": [a["id"], b["id"]]}, schema="Chat")["json"] for i in (1, 2)] + sent = [] + def send(i): + return c.call("POST", "/api/v1/chats/%s/messages" % chats[0]["id"], 201, actor=a if i % 2 else b, body={"text": "m%03d" % i}, schema="Message")["json"] + with ThreadPoolExecutor(max_workers=8) as pool: + sent = list(pool.map(send, range(250))) + seen, cursor, pages = [], None, 0 + while True: + url = "/api/v1/chats/%s/messages?limit=%d" % (chats[0]["id"], 100 if pages == 0 else 37) + (("&cursor=" + quote(cursor, safe="")) if cursor else "") + page = c.call("GET", url, actor=b, schema="MessagePage")["json"] + seen += page["items"]; pages += 1; cursor = page["next_cursor"] + if not cursor: + break + ids = [m["id"] for m in seen] + check(len(ids) == 250 and len(set(ids)) == 250, "потеряны/дублируются сообщения: %d" % len(ids)) + keys = [(m["created_at"], m["id"]) for m in seen] + check(keys == sorted(keys), "нарушен порядок (created_at, id)") + check({m["id"] for m in sent} == set(ids), "набор сообщений отличается от отправленного") + first = c.call("GET", "/api/v1/chats/%s/messages?limit=1" % chats[0]["id"], actor=a, schema="MessagePage")["json"]["next_cursor"] + c.call("GET", "/api/v1/chats/%s/messages?limit=1&cursor=%s" % (chats[1]["id"], quote(first, safe="")), 400, actor=a) # чужой чат + for junk in ("zzz", "e30", base64.urlsafe_b64encode(b'{"k":"messages"}').decode()): + c.call("GET", "/api/v1/chats/%s/messages?cursor=%s" % (chats[0]["id"], junk), 400, actor=a) + for limit in ("0", "101", "-1", "abc", ""): + c.call("GET", "/api/v1/chats/%s/messages?limit=%s" % (chats[0]["id"], limit), 400, actor=a) + c.call("GET", "/api/v1/chats?limit=1", 200, actor=a, schema="ChatPage") + + +@case +def chat_list_pagination_and_order(): + a, b = c.user("la"), c.user("lb") + ids = [c.call("POST", "/api/v1/chats", 201, actor=a, body={"title": "L%d" % i, "member_ids": [a["id"], b["id"]]}, schema="Chat")["json"]["id"] for i in range(5)] + got, cursor = [], None + while True: + page = c.call("GET", "/api/v1/chats?limit=2" + (("&cursor=" + quote(cursor, safe="")) if cursor else ""), actor=b, schema="ChatPage")["json"] + got += [x["id"] for x in page["items"]]; cursor = page["next_cursor"] + if not cursor: + break + check(got == ids, "порядок/полнота списка чатов нарушены") + c.call("GET", "/api/v1/chats?limit=1&cursor=" + quote(c.call("GET", "/api/v1/chats?limit=1", actor=a, schema="ChatPage")["json"]["next_cursor"], safe=""), 400, actor=b) # курсор другого пользователя + + +@case +def request_id_and_error_shape(): + r = c.call("GET", "/api/v1/nope", 404) + check(r["json"]["error"]["code"] == "not_found", "404 неизвестного маршрута не в формате ошибки") + c.call("PUT", "/api/v1/users", [400, 404, 405]) + + +if __name__ == "__main__": + failed = [n for n, s in RESULTS if s == "FAIL"] + print("\n%d/%d passed" % (len(RESULTS) - len(failed), len(RESULTS))) + raise SystemExit(1 if failed else 0)