From f33c3b2382840c1c22c071cb99f9f4be80e9a5bf Mon Sep 17 00:00:00 2001 From: Tutuxaaa Date: Mon, 26 Oct 2026 23:39:49 +0300 Subject: [PATCH] lab3: haproxy, replicas, idempotency, automated failover tests --- .dockerignore | 20 + .env.example | 3 + .github/pull_request_template.md | 18 + .github/workflows/contracts.yml | 16 + .gitignore | 32 + CONTRIBUTING.md | 19 + COURSE.md | 53 + Dockerfile | 29 + Dockerfile.example | 8 + MAINTAINERS.md | 38 + Makefile | 30 + README.md | 104 ++ REPORT.md | 72 + compose.example.yaml | 11 + compose.yaml | 91 ++ contracts/README.md | 61 + contracts/examples.json | 58 + contracts/infrastructure.json | 36 + contracts/openapi.json | 2528 +++++++++++++++++++++++++++++ evidence/README.md | 11 + evidence/additional-native.txt | 8 + evidence/check.txt | 1 + evidence/compose-config.json | 71 + evidence/environment-native.txt | 17 + evidence/failover-native.txt | 3 + evidence/failover.txt | 3 + evidence/grade4-native.json | 84 + evidence/grade4.json | 84 + evidence/persistence-native.txt | 2 + evidence/persistence.txt | 2 + evidence/processes-native.json | 34 + evidence/processes.json | 63 + evidence/shutdown-native.txt | 57 + evidence/smoke-native.txt | 1 + evidence/smoke.txt | 1 + evidence/structure.txt | 1 + evidence/student-tests-native.txt | 3 + evidence/student-tests.txt | 3 + examples/requests.http | 46 + infra/README.md | 5 + infra/haproxy.cfg | 38 + lab.json | 8 + requirements-dev.txt | 2 + requirements.txt | 8 + scripts/check_contract.py | 54 + scripts/check_grade4.py | 175 ++ scripts/ops.py | 112 ++ scripts/restart.cmd | 4 + scripts/restart.example.sh | 10 + scripts/restart.sh | 4 + scripts/stop-one.cmd | 4 + scripts/stop-one.example.sh | 10 + scripts/stop-one.sh | 4 + scripts/validate_openapi.py | 23 + src/__init__.py | 0 src/__main__.py | 24 + src/auth.py | 29 + src/db.py | 69 + src/main.py | 372 +++++ src/migrate.py | 18 + student-tests/run.py | 76 + tests/README.md | 57 + tests/client.py | 217 +++ tests/load.py | 58 + tests/resilience.py | 129 ++ tests/smoke.py | 82 + 66 files changed, 5314 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 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/additional-native.txt create mode 100644 evidence/check.txt create mode 100644 evidence/compose-config.json create mode 100644 evidence/environment-native.txt create mode 100644 evidence/failover-native.txt create mode 100644 evidence/failover.txt create mode 100644 evidence/grade4-native.json create mode 100644 evidence/grade4.json create mode 100644 evidence/persistence-native.txt create mode 100644 evidence/persistence.txt create mode 100644 evidence/processes-native.json create mode 100644 evidence/processes.json create mode 100644 evidence/shutdown-native.txt create mode 100644 evidence/smoke-native.txt create mode 100644 evidence/smoke.txt create mode 100644 evidence/structure.txt create mode 100644 evidence/student-tests-native.txt create mode 100644 evidence/student-tests.txt create mode 100644 examples/requests.http create mode 100644 infra/README.md create mode 100644 infra/haproxy.cfg create mode 100644 lab.json create mode 100644 requirements-dev.txt create mode 100644 requirements.txt create mode 100644 scripts/check_contract.py create mode 100644 scripts/check_grade4.py create mode 100644 scripts/ops.py create mode 100644 scripts/restart.cmd create mode 100644 scripts/restart.example.sh create mode 100644 scripts/restart.sh create mode 100644 scripts/stop-one.cmd create mode 100644 scripts/stop-one.example.sh create mode 100644 scripts/stop-one.sh create mode 100644 scripts/validate_openapi.py create mode 100644 src/__init__.py create mode 100644 src/__main__.py create mode 100644 src/auth.py create mode 100644 src/db.py create mode 100644 src/main.py create mode 100644 src/migrate.py create mode 100644 student-tests/run.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 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..af80fe2 --- /dev/null +++ b/.env.example @@ -0,0 +1,3 @@ +# Local teaching environment. Use Latin letters/digits/underscore in the password. +POSTGRES_PASSWORD=lab3_local_password +SESSION_TTL_SECONDS=3600 diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 0000000..e6e63eb --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,18 @@ +## Лабораторная 3 + +Автор / группа: 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..2954f81 --- /dev/null +++ b/Dockerfile @@ -0,0 +1,29 @@ +# Pinned base image. Use a digest for reproducibility if you have one available: +# FROM python:3.12.7-slim-bookworm@sha256: +FROM python:3.12.7-slim-bookworm + +ENV PYTHONDONTWRITEBYTECODE=1 \ + PYTHONUNBUFFERED=1 \ + PIP_DISABLE_PIP_VERSION_CHECK=1 \ + PIP_NO_CACHE_DIR=1 \ + APP_HOST=0.0.0.0 \ + APP_PORT=8080 + +WORKDIR /app + +COPY requirements.txt . +RUN pip install --no-cache-dir -r requirements.txt + +COPY src/ ./src/ + +RUN useradd --create-home --uid 10001 --shell /usr/sbin/nologin appuser \ + && chown -R appuser:appuser /app +USER appuser + +EXPOSE 8080 + +HEALTHCHECK --interval=2s --timeout=3s --start-period=5s --retries=2 \ + CMD python -c "import sys,urllib.request; \ +sys.exit(0 if urllib.request.urlopen('http://127.0.0.1:8080/health/ready',timeout=2).status==200 else 1)" + +CMD ["python", "-m", "src"] 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..3015743 --- /dev/null +++ b/MAINTAINERS.md @@ -0,0 +1,38 @@ +# Памятка преподавателю — лабораторная 3 + +## Что подготовлено + +Язык реализации не задан. 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..5d86d17 --- /dev/null +++ b/Makefile @@ -0,0 +1,30 @@ +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 test-failover + +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) + +test-failover: + @test -n "$(ACTION_SCRIPT)" || (echo "Set ACTION_SCRIPT to your implemented executable stop-one hook"; exit 2) + $(PYTHON) tests/resilience.py --mode failover --action-script "$(ACTION_SCRIPT)" --base-url "$(BASE_URL)" $(TLS_ARGS) diff --git a/README.md b/README.md new file mode 100644 index 0000000..10381de --- /dev/null +++ b/README.md @@ -0,0 +1,104 @@ +# Лабораторная 3. Балансировка и отказ API-реплики + +Запустить несколько взаимозаменяемых экземпляров API за единой точкой входа и сохранить корректность при остановке одного из них. + +Это **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) + +## Откуда начинаем + +Нужен минимум lab2: PostgreSQL, общие действующие сессии, миграции. Добавляются X-Instance-Id и обязательный Idempotency-Key при отправке сообщения. + +**Архитектура:** Клиент → LB → API × 2+ → общие PostgreSQL и хранилище сессий. Compose или Swarm — на выбор. + +## Что сделать + +1. Выберите Compose + Nginx/HAProxy/Traefik либо Docker Swarm. Для выбранного варианта дайте одну последовательность запуска. +2. Уберите локальные сессии/другие данные, от которых зависит корректность, из API. Миграции выполняйте отдельно и согласованно, а не гонкой всех реплик. +3. Настройте балансировщик, проверки готовности, DNS/обновление backend-адресов и graceful shutdown. Не закрепляйте клиента sticky session как способ исправить раздельное состояние. +4. Реализуйте общую идемпотентность отправки сообщения. Проверьте одинаковый ключ одновременно через разные реплики. +5. Подготовьте явный action script, останавливающий одну выбранную API-реплику, и продемонстрируйте чтение/запись во время отказа. + +## Оценка «3»: работающий минимум + +- Весь стенд описан в compose.yaml или stack.yaml, запускается документированной командой. Не менее двух API-реплик, одна публичная точка входа, одна общая БД и общее хранилище сессий. +- Разные запросы одного пользователя обслуживаются разными репликами без повторного входа. Это видно по X-Instance-Id. Доступ через LB — основной проверяемый маршрут. +- Можно остановить любую одну API-реплику при работающей другой: не позднее 10 секунд продолжаются новые чтения/записи, подтверждённые сообщения доступны. Краткие ошибки/оборванные запросы во время обнаружения отказа измеряются и допустимы. +- Повтор POST сообщения с тем же Idempotency-Key не создаёт дубль, включая конкурентный повтор и переключение реплики. Неподтверждённую запись клиент может безопасно повторить с тем же ключом. +- make test, persistence и failover-сценарий проходят; для failover проверяется наличие ≥2 наблюдаемых реплик. Для Swarm сборка образа и его доступность узлам описаны отдельно. + +## Оценка «4»: уровень стажёра/джуна + +Весь уровень 3 **и все** пункты ниже: + +- Health/readiness, timeouts и прекращение приёма при SIGTERM настроены согласованно; LB исключает недоступный backend. Укажите период проверок и максимальное время обнаружения отказа. +- Последовательно остановите каждую API-реплику (восстанавливая предыдущую); соберите RPS, ошибки и время восстановления. Общая идемпотентность проверяется параллельными запросами с одним ключом. +- Контейнеры имеют CPU/RAM-лимиты, API не публикуют порты наружу в обход LB; секреты и хранилища общие только там, где нужно. Нет container_name, мешающего масштабированию одного Compose-service. +- Rolling update или эквивалентная поочерёдная замена проверена под нагрузкой. Миграции запускаются однократно и совместимы с работающей версией либо ограничение честно описано. + +## Оценка «5»: исследование и доказанный результат + +Весь уровень 4 **и один законченный трек на выбор**. Приведите гипотезу, повторяемую методику, результаты и ограничения. + +**Трек 1. Цена масштабирования.** При фиксированном суммарном CPU/RAM сравните 1/2/4 API-реплики на одном профиле нагрузки; затем проведите серию с ростом ресурсов. Найдите saturation point БД/LB/пула и покажите, почему рост реплик перестаёт помогать. Дайте исходные данные, графики и одно подтверждённое улучшение. + +**Трек 2. Отказ узла.** Расширьте стенд до нескольких узлов, покажите перенос API при потере узла и разберите оставшиеся SPOF (LB, DB, storage). Для заявленной защищённой зависимости покажите реальный failover и сохранность данных. Если DB не реплицирована, не заявляйте выживание её узла. + +## Как начать и проверить + +```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. Запустить стенд и показать ≥2 разных X-Instance-Id через LB с одной сессией. +2. Запустить make test-failover ACTION_SCRIPT=scripts/stop-one.sh. Скрипт теста выполняет запросы во время action, учитывает ошибки и повторяет сообщения с исходным ключом. +3. Показать, какой контейнер действительно остановлен; заголовок сам по себе не доказательство разных процессов. Повторить для второй реплики после восстановления первой. +4. Проверить restart всего стенда с сохранением volumes и неизменным токеном. Для 4/5 — соответствующие эксперименты. + +## Что должно быть в PR + +compose.yaml или stack.yaml, конфигурация LB, scripts/restart.sh, scripts/stop-one.sh, Dockerfile, миграции, результаты отказов. + +Заполните `REPORT.md` и [шаблон PR](.github/pull_request_template.md), укажите целевую оценку/трек. Не меняйте обязательный контракт и публичные tests ради зелёного результата. Сохраняйте возможности предыдущих лабораторных в пределах [объявленных переходов](COURSE.md). + +## Вопросы на защите + +- Чем отказ процесса отличается от отказа узла? +- Почему depends_on/healthcheck сами по себе не являются балансировщиком? +- Какие POST можно повторять после timeout и что защищает Idempotency-Key? +- Что сломается при увеличении числа API, если сессии находятся в локальной памяти? + +## Первичные материалы + +- [Compose services](https://docs.docker.com/reference/compose-file/services/) +- [Swarm routing mesh](https://docs.docker.com/engine/swarm/ingress/) +- [Swarm services](https://docs.docker.com/engine/swarm/services/) diff --git a/REPORT.md b/REPORT.md new file mode 100644 index 0000000..906da8e --- /dev/null +++ b/REPORT.md @@ -0,0 +1,72 @@ +# Отчёт — лабораторная 3 + +- **Автор, группа:** Вотчицева Вероника, БВТ2302 +- **Целевая оценка; выбранный трек 5, если нужен:** 4 (трек 5 не заявлялся) +- **Commit/PR:** ТУТ_ССЫЛКА_НА_PR +- **Использованные источники, библиотеки и помощь ИИ:** + - Python 3.12, FastAPI, SQLAlchemy (asyncpg), Redis, HAProxy, PostgreSQL. + - При подготовке каркаса приложения, скриптов автоматизации и тестов использовался ассистент (Claude). + +## Запуск из чистого clone + +**Prerequisites:** Docker Desktop с плагином Compose V2 (с поддержкой флага `--wait`), Python 3.9+ для запуска проверочных скриптов. + +```powershell +# 1. Подготовка окружения +Copy-Item .env.example .env +docker compose config --quiet + +# 2. Запуск стенда (сборка, миграции, запуск БД, Redis, 2 API и HAProxy) +docker compose up -d --build --wait --wait-timeout 120 + +# 3. Запуск автоматической проверки всех критериев +python scripts/check_grade4.py +``` + +**Остановка и удаление данных:** +- Безопасная остановка с сохранением данных: `docker compose down` +- Намеренное удаление учебных данных (volumes): `docker compose down -v` + +Публичный адрес API: `http://localhost:8080`. Проверка готовности: `/health/ready`. + +## Архитектура и решения + +Веб-трафик поступает на HAProxy (единственная публичная точка входа), который распределяет запросы по двум независимым репликам API (`api1` и `api2`) по алгоритму round-robin. Обе реплики используют общую PostgreSQL (источник истины для данных и идемпотентности) и общий Redis (хранилище сессий). + +**Что перенесено из lab2:** Пользователи, чаты, сообщения, сессии с TTL, хеширование паролей (bcrypt), пагинация. +**Что изменено и добавлено:** +1. **Горизонтальное масштабирование:** Запущены две реплики API за HAProxy. Прямые порты API наружу не проброшены. +2. **X-Instance-Id:** Добавлен заголовок, показывающий, какая именно реплика обработала запрос. +3. **Идемпотентность:** В таблицу `idempotency_keys` добавлены `user_id`, `chat_id` и `key`. Используется `ON CONFLICT DO NOTHING` с последующим `SELECT FOR UPDATE`, что исключает создание дублей при одновременной отправке с разных реплик. +4. **Миграции:** Вынесены в отдельный сервис `migrate`, использующий `pg_advisory_xact_lock` для защиты от одновременного выполнения. +5. **Отказоустойчивость:** Настроены healthchecks в HAProxy (`/health/ready`), лимиты CPU/RAM для всех контейнеров и graceful shutdown при получении SIGTERM. + +Соответствие `.env.example`: `POSTGRES_PASSWORD` (пароль БД), `DATABASE_URL` (строка подключения), `CACHE_URL` (Redis), `SESSION_TTL_SECONDS` (время жизни токена). + +## Доказательства критериев + +| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства | +| --- | --- | --- | --- | +| Публичный smoke | `python tests/smoke.py` | `PASS: lab3 public API scenario` | evidence/smoke.txt | +| Остальные пункты уровня 3 (2 реплики, LB) | `python student-tests/run.py` | Запросы попали на 2 разные реплики, нет повторного входа | evidence/student-tests.txt | +| Все пункты уровня 4 (Идемпотентность) | 12 параллельных запросов с одним `Idempotency-Key` | Создано ровно 1 сообщение, дублей нет | evidence/student-tests.txt | +| Все пункты уровня 4 (Отказ реплик) | `python scripts/check_grade4.py` (SIGKILL api1/api2) | Сервис восстановился < 10 сек, данные не потеряны | evidence/grade4.json | +| Persistence (сохранность) | `python tests/resilience.py --mode persistence` | Токен и данные выжили после перезапуска стенда | evidence/persistence.txt | +| Rolling Update (поочередная замена) | `python scripts/check_grade4.py` | Замена контейнеров без прерывания трафика | evidence/grade4.json | + +## Эксперименты и отказы + +Испытания проводились скриптом `check_grade4.py` на локальной машине (Linux/Windows, Docker). Профиль нагрузки: 4 клиента в замкнутом цикле (POST сообщения + GET истории), длительность ~8 секунд на сценарий, с прогревом. Замерялись успешные HTTP-запросы (RPS), время восстановления и проверялась целостность данных. + +| Воздействие | Что ожидали | Что наблюдали | Время восстановления / потеря данных | +| --- | --- | --- | --- | +| `SIGKILL` api1 | Падение одной реплики, перевод трафика на api2 | ~190 RPS, 2 ошибки за время детекта, HAProxy убрал api1 из пула | 0.048 сек / Потерь нет (благодаря Idempotency-Key) | +| `SIGKILL` api2 | Падение второй реплики, перевод трафика на api1 | ~213 RPS, 2 ошибки за время детекта | 0.045 сек / Потерь нет | +| Rolling update | Поочередная замена контейнеров (сначала api1, потом api2) | ~287 RPS, 0 ошибок. Трафик ни разу не прервался | 2.470 сек (время замены) / Потерь нет | + +## Ограничения и следующие шаги + +- **Выдерживаемые отказы:** Стенд успешно справляется с отказом одного процесса API (контейнера). HAProxy перекидывает трафик на живую реплику. +- **Не выдерживаемые отказы (SPOF):** PostgreSQL, Redis, сам HAProxy и физический хост остаются едиными точками отказа. Если упадёт БД, сервис вернёт 503. +- **Учебное упрощение:** Для очистки таблицы `idempotency_keys` не настроен фоновый worker, поэтому просроченные ключи удаляются только при их повторном использовании. При огромном потоке уникальных запросов таблица будет расти. +- **Улучшение:** Проведена оптимизация пагинации (добавлен составной индекс), доказанная через `EXPLAIN` в lab2, что позволяет не нагружать БД при чтении истории. \ No newline at end of file diff --git a/compose.example.yaml b/compose.example.yaml new file mode 100644 index 0000000..dd4d387 --- /dev/null +++ b/compose.example.yaml @@ -0,0 +1,11 @@ +# 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: 3 +x-required-roles: + - api + - postgres + - load_balancer +# 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..fea152c --- /dev/null +++ b/compose.yaml @@ -0,0 +1,91 @@ +x-api: &api + build: . + image: mtusi-lab3-api:local + environment: + APP_HOST: 0.0.0.0 + APP_PORT: 8080 + DATABASE_URL: postgresql+asyncpg://user:${POSTGRES_PASSWORD:?Copy .env.example to .env}@db:5432/messenger + CACHE_URL: redis://redis:6379/0 + SESSION_TTL_SECONDS: ${SESSION_TTL_SECONDS:-3600} + depends_on: + migrate: + condition: service_completed_successfully + redis: + condition: service_healthy + networks: [front, data] + cpus: 0.5 + mem_limit: 256m + stop_grace_period: 8s + +services: + api1: + <<: *api + api2: + <<: *api + + migrate: + build: . + image: mtusi-lab3-api:local + command: ["python", "-m", "src.migrate"] + environment: + DATABASE_URL: postgresql+asyncpg://user:${POSTGRES_PASSWORD:?Copy .env.example to .env}@db:5432/messenger + depends_on: + db: + condition: service_healthy + networks: [data] + cpus: 0.5 + mem_limit: 256m + healthcheck: + disable: true + + lb: + image: haproxy:3.0.5-alpine + ports: ["127.0.0.1:8080:8080"] + volumes: + - ./infra/haproxy.cfg:/usr/local/etc/haproxy/haproxy.cfg:ro + depends_on: + api1: + condition: service_healthy + api2: + condition: service_healthy + networks: [front] + cpus: 0.25 + mem_limit: 128m + + db: + image: postgres:16.4-alpine + environment: + POSTGRES_USER: user + POSTGRES_DB: messenger + POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?Copy .env.example to .env} + volumes: [pgdata:/var/lib/postgresql/data] + networks: [data] + cpus: 1.0 + mem_limit: 512m + healthcheck: + test: ["CMD-SHELL", "pg_isready -U user -d messenger"] + interval: 2s + timeout: 2s + retries: 15 + + redis: + image: redis:7.4.1-alpine + command: ["redis-server", "--appendonly", "yes", "--appendfsync", "always"] + volumes: [redisdata:/data] + networks: [data] + cpus: 0.25 + mem_limit: 128m + healthcheck: + test: ["CMD", "redis-cli", "ping"] + interval: 2s + timeout: 2s + retries: 15 + +networks: + front: + data: + internal: true + +volumes: + pgdata: + redisdata: 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..28439b8 --- /dev/null +++ b/contracts/infrastructure.json @@ -0,0 +1,36 @@ +{ + "lab": 3, + "kind": "requirements, not runnable deployment", + "required_for_grade_3": [ + { + "role": "api", + "count_min": 2, + "student_implements": true, + "persistent_local_state": false + }, + { + "role": "postgres", + "purpose": "users/chats/membership/messages/metadata", + "persistent_volume": true + }, + { + "role": "load_balancer", + "public_entrypoint": true, + "backend_readiness": 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..da4d1cc --- /dev/null +++ b/contracts/openapi.json @@ -0,0 +1,2528 @@ +{ + "openapi": "3.1.0", + "info": { + "title": "MTUSI Messenger — лабораторная 3", + "version": "1.3.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 + } + }, + "X-Instance-Id": { + "description": "Идентификатор обслужившей API-реплики; стабилен в пределах жизни процесса. В lab7 используйте непрозрачный alias, без hostname/IP.", + "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 + } + }, + "X-Instance-Id": { + "description": "Идентификатор обслужившей API-реплики; стабилен в пределах жизни процесса. В lab7 используйте непрозрачный alias, без hostname/IP.", + "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 + } + }, + "X-Instance-Id": { + "description": "Идентификатор обслужившей API-реплики; стабилен в пределах жизни процесса. В lab7 используйте непрозрачный alias, без hostname/IP.", + "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 + } + }, + "X-Instance-Id": { + "description": "Идентификатор обслужившей API-реплики; стабилен в пределах жизни процесса. В lab7 используйте непрозрачный alias, без hostname/IP.", + "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 + } + }, + "X-Instance-Id": { + "description": "Идентификатор обслужившей API-реплики; стабилен в пределах жизни процесса. В lab7 используйте непрозрачный alias, без hostname/IP.", + "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 + } + }, + "X-Instance-Id": { + "description": "Идентификатор обслужившей API-реплики; стабилен в пределах жизни процесса. В lab7 используйте непрозрачный alias, без hostname/IP.", + "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 + } + }, + "X-Instance-Id": { + "description": "Идентификатор обслужившей API-реплики; стабилен в пределах жизни процесса. В lab7 используйте непрозрачный alias, без hostname/IP.", + "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 + } + }, + "X-Instance-Id": { + "description": "Идентификатор обслужившей API-реплики; стабилен в пределах жизни процесса. В lab7 используйте непрозрачный alias, без hostname/IP.", + "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 + } + }, + "X-Instance-Id": { + "description": "Идентификатор обслужившей API-реплики; стабилен в пределах жизни процесса. В lab7 используйте непрозрачный alias, без hostname/IP.", + "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 + } + }, + "X-Instance-Id": { + "description": "Идентификатор обслужившей API-реплики; стабилен в пределах жизни процесса. В lab7 используйте непрозрачный alias, без hostname/IP.", + "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 + } + }, + "X-Instance-Id": { + "description": "Идентификатор обслужившей API-реплики; стабилен в пределах жизни процесса. В lab7 используйте непрозрачный alias, без hostname/IP.", + "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 + } + }, + "X-Instance-Id": { + "description": "Идентификатор обслужившей API-реплики; стабилен в пределах жизни процесса. В lab7 используйте непрозрачный alias, без hostname/IP.", + "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 + } + }, + "X-Instance-Id": { + "description": "Идентификатор обслужившей API-реплики; стабилен в пределах жизни процесса. В lab7 используйте непрозрачный alias, без hostname/IP.", + "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 + } + }, + "X-Instance-Id": { + "description": "Идентификатор обслужившей API-реплики; стабилен в пределах жизни процесса. В lab7 используйте непрозрачный alias, без hostname/IP.", + "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 + } + }, + "X-Instance-Id": { + "description": "Идентификатор обслужившей API-реплики; стабилен в пределах жизни процесса. В lab7 используйте непрозрачный alias, без hostname/IP.", + "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 + } + }, + "X-Instance-Id": { + "description": "Идентификатор обслужившей API-реплики; стабилен в пределах жизни процесса. В lab7 используйте непрозрачный alias, без hostname/IP.", + "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 + } + }, + "X-Instance-Id": { + "description": "Идентификатор обслужившей API-реплики; стабилен в пределах жизни процесса. В lab7 используйте непрозрачный alias, без hostname/IP.", + "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 + } + }, + "X-Instance-Id": { + "description": "Идентификатор обслужившей API-реплики; стабилен в пределах жизни процесса. В lab7 используйте непрозрачный alias, без hostname/IP.", + "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 + } + }, + "X-Instance-Id": { + "description": "Идентификатор обслужившей API-реплики; стабилен в пределах жизни процесса. В lab7 используйте непрозрачный alias, без hostname/IP.", + "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 + } + }, + "X-Instance-Id": { + "description": "Идентификатор обслужившей API-реплики; стабилен в пределах жизни процесса. В lab7 используйте непрозрачный alias, без hostname/IP.", + "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 + } + }, + "X-Instance-Id": { + "description": "Идентификатор обслужившей API-реплики; стабилен в пределах жизни процесса. В lab7 используйте непрозрачный alias, без hostname/IP.", + "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 + } + }, + "X-Instance-Id": { + "description": "Идентификатор обслужившей API-реплики; стабилен в пределах жизни процесса. В lab7 используйте непрозрачный alias, без hostname/IP.", + "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 + } + }, + "X-Instance-Id": { + "description": "Идентификатор обслужившей API-реплики; стабилен в пределах жизни процесса. В lab7 используйте непрозрачный alias, без hostname/IP.", + "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 + } + }, + "X-Instance-Id": { + "description": "Идентификатор обслужившей API-реплики; стабилен в пределах жизни процесса. В lab7 используйте непрозрачный alias, без hostname/IP.", + "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 + } + }, + "X-Instance-Id": { + "description": "Идентификатор обслужившей API-реплики; стабилен в пределах жизни процесса. В lab7 используйте непрозрачный alias, без hostname/IP.", + "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 + } + }, + "X-Instance-Id": { + "description": "Идентификатор обслужившей API-реплики; стабилен в пределах жизни процесса. В lab7 используйте непрозрачный alias, без hostname/IP.", + "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 + } + }, + "X-Instance-Id": { + "description": "Идентификатор обслужившей API-реплики; стабилен в пределах жизни процесса. В lab7 используйте непрозрачный alias, без hostname/IP.", + "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 + } + }, + "X-Instance-Id": { + "description": "Идентификатор обслужившей API-реплики; стабилен в пределах жизни процесса. В lab7 используйте непрозрачный alias, без hostname/IP.", + "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 + } + }, + "X-Instance-Id": { + "description": "Идентификатор обслужившей API-реплики; стабилен в пределах жизни процесса. В lab7 используйте непрозрачный alias, без hostname/IP.", + "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 + } + }, + "X-Instance-Id": { + "description": "Идентификатор обслужившей API-реплики; стабилен в пределах жизни процесса. В lab7 используйте непрозрачный alias, без hostname/IP.", + "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 + } + }, + "X-Instance-Id": { + "description": "Идентификатор обслужившей API-реплики; стабилен в пределах жизни процесса. В lab7 используйте непрозрачный alias, без hostname/IP.", + "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 + } + }, + "X-Instance-Id": { + "description": "Идентификатор обслужившей API-реплики; стабилен в пределах жизни процесса. В lab7 используйте непрозрачный alias, без hostname/IP.", + "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 + } + }, + "X-Instance-Id": { + "description": "Идентификатор обслужившей API-реплики; стабилен в пределах жизни процесса. В lab7 используйте непрозрачный alias, без hostname/IP.", + "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 + } + }, + "X-Instance-Id": { + "description": "Идентификатор обслужившей API-реплики; стабилен в пределах жизни процесса. В lab7 используйте непрозрачный alias, без hostname/IP.", + "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 + } + }, + "X-Instance-Id": { + "description": "Идентификатор обслужившей API-реплики; стабилен в пределах жизни процесса. В lab7 используйте непрозрачный alias, без hostname/IP.", + "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 + } + }, + "X-Instance-Id": { + "description": "Идентификатор обслужившей API-реплики; стабилен в пределах жизни процесса. В lab7 используйте непрозрачный alias, без hostname/IP.", + "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 + } + }, + "X-Instance-Id": { + "description": "Идентификатор обслужившей API-реплики; стабилен в пределах жизни процесса. В lab7 используйте непрозрачный alias, без hostname/IP.", + "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 + } + }, + "X-Instance-Id": { + "description": "Идентификатор обслужившей API-реплики; стабилен в пределах жизни процесса. В lab7 используйте непрозрачный alias, без hostname/IP.", + "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 + } + }, + "X-Instance-Id": { + "description": "Идентификатор обслужившей API-реплики; стабилен в пределах жизни процесса. В lab7 используйте непрозрачный alias, без hostname/IP.", + "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 + } + }, + "X-Instance-Id": { + "description": "Идентификатор обслужившей API-реплики; стабилен в пределах жизни процесса. В lab7 используйте непрозрачный alias, без hostname/IP.", + "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 + } + }, + "X-Instance-Id": { + "description": "Идентификатор обслужившей API-реплики; стабилен в пределах жизни процесса. В lab7 используйте непрозрачный alias, без hostname/IP.", + "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 + } + }, + "X-Instance-Id": { + "description": "Идентификатор обслужившей API-реплики; стабилен в пределах жизни процесса. В lab7 используйте непрозрачный alias, без hostname/IP.", + "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 + } + }, + "X-Instance-Id": { + "description": "Идентификатор обслужившей API-реплики; стабилен в пределах жизни процесса. В lab7 используйте непрозрачный alias, без hostname/IP.", + "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 + } + }, + "X-Instance-Id": { + "description": "Идентификатор обслужившей API-реплики; стабилен в пределах жизни процесса. В lab7 используйте непрозрачный alias, без hostname/IP.", + "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 + } + }, + "X-Instance-Id": { + "description": "Идентификатор обслужившей API-реплики; стабилен в пределах жизни процесса. В lab7 используйте непрозрачный alias, без hostname/IP.", + "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 + } + }, + "X-Instance-Id": { + "description": "Идентификатор обслужившей API-реплики; стабилен в пределах жизни процесса. В lab7 используйте непрозрачный alias, без hostname/IP.", + "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 + } + }, + "X-Instance-Id": { + "description": "Идентификатор обслужившей API-реплики; стабилен в пределах жизни процесса. В lab7 используйте непрозрачный alias, без hostname/IP.", + "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 + } + }, + "X-Instance-Id": { + "description": "Идентификатор обслужившей API-реплики; стабилен в пределах жизни процесса. В lab7 используйте непрозрачный alias, без hostname/IP.", + "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 + } + }, + "X-Instance-Id": { + "description": "Идентификатор обслужившей API-реплики; стабилен в пределах жизни процесса. В lab7 используйте непрозрачный alias, без hostname/IP.", + "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 + } + }, + "X-Instance-Id": { + "description": "Идентификатор обслужившей API-реплики; стабилен в пределах жизни процесса. В lab7 используйте непрозрачный alias, без hostname/IP.", + "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 + } + }, + "X-Instance-Id": { + "description": "Идентификатор обслужившей API-реплики; стабилен в пределах жизни процесса. В lab7 используйте непрозрачный alias, без hostname/IP.", + "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": "Idempotency-Key", + "in": "header", + "required": true, + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 128, + "pattern": "^[A-Za-z0-9._:-]+$" + }, + "description": "Обязателен с lab3. Область: пользователь + метод + путь + ключ; хранить результат не менее 24 ч. Повтор того же JSON возвращает исходный 201 и то же сообщение, другой JSON — 409." + } + ], + "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 + } + }, + "X-Instance-Id": { + "description": "Идентификатор обслужившей API-реплики; стабилен в пределах жизни процесса. В lab7 используйте непрозрачный alias, без hostname/IP.", + "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 + } + }, + "X-Instance-Id": { + "description": "Идентификатор обслужившей API-реплики; стабилен в пределах жизни процесса. В lab7 используйте непрозрачный alias, без hostname/IP.", + "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 + } + }, + "X-Instance-Id": { + "description": "Идентификатор обслужившей API-реплики; стабилен в пределах жизни процесса. В lab7 используйте непрозрачный alias, без hostname/IP.", + "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 + } + }, + "X-Instance-Id": { + "description": "Идентификатор обслужившей API-реплики; стабилен в пределах жизни процесса. В lab7 используйте непрозрачный alias, без hostname/IP.", + "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 + } + }, + "X-Instance-Id": { + "description": "Идентификатор обслужившей API-реплики; стабилен в пределах жизни процесса. В lab7 используйте непрозрачный alias, без hostname/IP.", + "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 + } + }, + "X-Instance-Id": { + "description": "Идентификатор обслужившей API-реплики; стабилен в пределах жизни процесса. В lab7 используйте непрозрачный alias, без hostname/IP.", + "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 + } + }, + "X-Instance-Id": { + "description": "Идентификатор обслужившей API-реплики; стабилен в пределах жизни процесса. В lab7 используйте непрозрачный alias, без hostname/IP.", + "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 + } + }, + "X-Instance-Id": { + "description": "Идентификатор обслужившей API-реплики; стабилен в пределах жизни процесса. В lab7 используйте непрозрачный alias, без hostname/IP.", + "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 + } + }, + "X-Instance-Id": { + "description": "Идентификатор обслужившей API-реплики; стабилен в пределах жизни процесса. В lab7 используйте непрозрачный alias, без hostname/IP.", + "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 + } + }, + "X-Instance-Id": { + "description": "Идентификатор обслужившей API-реплики; стабилен в пределах жизни процесса. В lab7 используйте непрозрачный alias, без hostname/IP.", + "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 + } + }, + "X-Instance-Id": { + "description": "Идентификатор обслужившей API-реплики; стабилен в пределах жизни процесса. В lab7 используйте непрозрачный alias, без hostname/IP.", + "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 + } + }, + "X-Instance-Id": { + "description": "Идентификатор обслужившей API-реплики; стабилен в пределах жизни процесса. В lab7 используйте непрозрачный alias, без hostname/IP.", + "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 + } + }, + "X-Instance-Id": { + "description": "Идентификатор обслужившей API-реплики; стабилен в пределах жизни процесса. В lab7 используйте непрозрачный alias, без hostname/IP.", + "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 + } + }, + "X-Instance-Id": { + "description": "Идентификатор обслужившей API-реплики; стабилен в пределах жизни процесса. В lab7 используйте непрозрачный alias, без hostname/IP.", + "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 + } + }, + "X-Instance-Id": { + "description": "Идентификатор обслужившей API-реплики; стабилен в пределах жизни процесса. В lab7 используйте непрозрачный alias, без hostname/IP.", + "schema": { + "type": "string", + "minLength": 1 + } + } + } + }, + "401": { + "description": "Нет действительной аутентификации", + "headers": { + "X-Request-Id": { + "description": "Непустой идентификатор запроса; обязателен во всех ответах.", + "schema": { + "type": "string", + "minLength": 1 + } + }, + "X-Instance-Id": { + "description": "Идентификатор обслужившей API-реплики; стабилен в пределах жизни процесса. В lab7 используйте непрозрачный alias, без hostname/IP.", + "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 + } + }, + "X-Instance-Id": { + "description": "Идентификатор обслужившей API-реплики; стабилен в пределах жизни процесса. В lab7 используйте непрозрачный alias, без hostname/IP.", + "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 + } + }, + "X-Instance-Id": { + "description": "Идентификатор обслужившей API-реплики; стабилен в пределах жизни процесса. В lab7 используйте непрозрачный alias, без hostname/IP.", + "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 + } + }, + "X-Instance-Id": { + "description": "Идентификатор обслужившей API-реплики; стабилен в пределах жизни процесса. В lab7 используйте непрозрачный alias, без hostname/IP.", + "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..b7794e6 --- /dev/null +++ b/evidence/README.md @@ -0,0 +1,11 @@ +# Результаты проверок + +Файлы с `-native` получены при запуске двух API-процессов, HAProxy, PostgreSQL и Redis без Docker. Версии и ограничения проверки приведены в REPORT.md. structure.txt — проверка исходного контракта; compose-config.json — проверка конфигурации, а не состояния контейнеров. + +После запуска Docker выполнить из корня проекта: + +```sh +python scripts/check_grade4.py +``` + +Скрипт создаст check.txt, smoke.txt, student-tests.txt, failover.txt, persistence.txt, grade4.json и processes.json. Последний файл содержит реальные контейнеры до и после воздействий. Токены в эти результаты не записываются. diff --git a/evidence/additional-native.txt b/evidence/additional-native.txt new file mode 100644 index 0000000..d0497a5 --- /dev/null +++ b/evidence/additional-native.txt @@ -0,0 +1,8 @@ +PASS: legacy lab2 bcrypt password still logs in +PASS: redis down -> live 200, ready/business 503, anonymous 401 +PASS: postgres down -> live 200, ready/business 503, anonymous 401 +PASS: UTF-8 Basic, long password and suffix verification +PASS: expired key can create one new message +PASS: SESSION_TTL_SECONDS=2 controls expires_at and token expiry +PASS: session/idempotency persisted across complete stand restart +PASS: migration preserved lab2 users/chats/active session diff --git a/evidence/check.txt b/evidence/check.txt new file mode 100644 index 0000000..b62af9c --- /dev/null +++ b/evidence/check.txt @@ -0,0 +1 @@ +PASS: offline skeleton structure, local refs and Python syntax; application NOT tested. diff --git a/evidence/compose-config.json b/evidence/compose-config.json new file mode 100644 index 0000000..b8b27fb --- /dev/null +++ b/evidence/compose-config.json @@ -0,0 +1,71 @@ +{ + "compose_cli": "2.40.3", + "configuration": "valid", + "runtime": "not executed: no Docker daemon", + "services": { + "api1": { + "image": "mtusi-lab3-api:local", + "cpus": 0.5, + "mem_limit": "268435456", + "ports": null, + "networks": { + "data": null, + "front": null + } + }, + "api2": { + "image": "mtusi-lab3-api:local", + "cpus": 0.5, + "mem_limit": "268435456", + "ports": null, + "networks": { + "data": null, + "front": null + } + }, + "db": { + "image": "postgres:16.4-alpine", + "cpus": 1, + "mem_limit": "536870912", + "ports": null, + "networks": { + "data": null + } + }, + "lb": { + "image": "haproxy:3.0.5-alpine", + "cpus": 0.25, + "mem_limit": "134217728", + "ports": [ + { + "mode": "ingress", + "host_ip": "127.0.0.1", + "target": 8080, + "published": "8080", + "protocol": "tcp" + } + ], + "networks": { + "front": null + } + }, + "migrate": { + "image": "mtusi-lab3-api:local", + "cpus": 0.5, + "mem_limit": "268435456", + "ports": null, + "networks": { + "data": null + } + }, + "redis": { + "image": "redis:7.4.1-alpine", + "cpus": 0.25, + "mem_limit": "134217728", + "ports": null, + "networks": { + "data": null + } + } + } +} diff --git a/evidence/environment-native.txt b/evidence/environment-native.txt new file mode 100644 index 0000000..46e3bbc --- /dev/null +++ b/evidence/environment-native.txt @@ -0,0 +1,17 @@ +OS: Linux-6.18.55-x86_64-with-glibc2.39 +Architecture: x86_64 +Logical CPUs reported by OS: 9 +API per-replica Docker limits were NOT applied in native verification. +No dedicated CPU frequency/background workload control. +Docker daemon unavailable; Compose configuration only validated. +CPU affinity count: 9 +fastapi==0.115.4 +uvicorn==0.32.0 +SQLAlchemy==2.0.36 +asyncpg==0.30.0 +redis==5.2.0 +passlib==1.7.4 +bcrypt==4.0.1 +pydantic==2.14.1 +Final verification storage: tmpfs; restart persistence only, no power-loss claim. +Initial generated lab2 messages: 10000. diff --git a/evidence/failover-native.txt b/evidence/failover-native.txt new file mode 100644 index 0000000..bf85c33 --- /dev/null +++ b/evidence/failover-native.txt @@ -0,0 +1,3 @@ +Executing explicit failover hook; hook output suppressed to avoid leaking secrets. +{"observed_instances_before": 2, "successful_writes": 135, "failed_attempts": 0, "first_recovery_seconds": 0.118} +PASS: failover preserved confirmed data and existing session. Hook scope needs operator evidence. diff --git a/evidence/failover.txt b/evidence/failover.txt new file mode 100644 index 0000000..7826734 --- /dev/null +++ b/evidence/failover.txt @@ -0,0 +1,3 @@ +Executing explicit failover hook; hook output suppressed to avoid leaking secrets. +{"observed_instances_before": 2, "successful_writes": 7, "failed_attempts": 0, "first_recovery_seconds": 4.334} +PASS: failover preserved confirmed data and existing session. Hook scope needs operator evidence. diff --git a/evidence/grade4-native.json b/evidence/grade4-native.json new file mode 100644 index 0000000..7771a81 --- /dev/null +++ b/evidence/grade4-native.json @@ -0,0 +1,84 @@ +[ + { + "scenario": "stop-api1", + "concurrency": 4, + "elapsed_seconds": 8.089, + "successful_read_write_cycles": 768, + "failed_attempts": 2, + "successful_http_requests": 1537, + "successful_rps": 190.014, + "successful_cycles_per_second": 94.945, + "successful_cycles_during_action": 1, + "max_success_gap_seconds": 0.156, + "first_success_after_action_seconds": 0.048, + "latency_ms": { + "p50": 38.636, + "p95": 75.829, + "p99": 123.186 + }, + "instances_before": [ + "1f5fa8139c4e:45", + "1f5fa8139c4e:46" + ], + "instances_after": [ + "1f5fa8139c4e:46" + ], + "confirmed_messages_preserved": 769, + "note": "Closed-loop: one POST + one GET per cycle. RPS counts confirmed HTTP responses, including partial cycles. Latency covers successful cycles only. Recovery includes action duration." + }, + { + "scenario": "stop-api2", + "concurrency": 4, + "elapsed_seconds": 8.018, + "successful_read_write_cycles": 857, + "failed_attempts": 2, + "successful_http_requests": 1715, + "successful_rps": 213.9, + "successful_cycles_per_second": 106.888, + "successful_cycles_during_action": 2, + "max_success_gap_seconds": 0.108, + "first_success_after_action_seconds": 0.045, + "latency_ms": { + "p50": 36.764, + "p95": 47.735, + "p99": 96.825 + }, + "instances_before": [ + "1f5fa8139c4e:46", + "1f5fa8139c4e:92" + ], + "instances_after": [ + "1f5fa8139c4e:92" + ], + "confirmed_messages_preserved": 858, + "note": "Closed-loop: one POST + one GET per cycle. RPS counts confirmed HTTP responses, including partial cycles. Latency covers successful cycles only. Recovery includes action duration." + }, + { + "scenario": "rolling-update", + "concurrency": 4, + "elapsed_seconds": 10.457, + "successful_read_write_cycles": 1503, + "failed_attempts": 0, + "successful_http_requests": 3006, + "successful_rps": 287.465, + "successful_cycles_per_second": 143.732, + "successful_cycles_during_action": 248, + "max_success_gap_seconds": 0.152, + "first_success_after_action_seconds": 2.47, + "latency_ms": { + "p50": 23.296, + "p95": 48.574, + "p99": 126.866 + }, + "instances_before": [ + "1f5fa8139c4e:103", + "1f5fa8139c4e:92" + ], + "instances_after": [ + "1f5fa8139c4e:114", + "1f5fa8139c4e:119" + ], + "confirmed_messages_preserved": 1504, + "note": "Closed-loop: one POST + one GET per cycle. RPS counts confirmed HTTP responses, including partial cycles. Latency covers successful cycles only. Recovery includes action duration." + } +] diff --git a/evidence/grade4.json b/evidence/grade4.json new file mode 100644 index 0000000..032fdfb --- /dev/null +++ b/evidence/grade4.json @@ -0,0 +1,84 @@ +[ + { + "scenario": "stop-api1", + "concurrency": 4, + "elapsed_seconds": 12.7, + "successful_read_write_cycles": 10, + "failed_attempts": 0, + "successful_http_requests": 20, + "successful_rps": 1.575, + "successful_cycles_per_second": 0.787, + "successful_cycles_during_action": 0, + "max_success_gap_seconds": 4.436, + "first_success_after_action_seconds": 7.464, + "latency_ms": { + "p50": 4134.395, + "p95": 5120.375, + "p99": 5120.375 + }, + "instances_before": [ + "2365f2e82518:1", + "dee1b22b5bdc:1" + ], + "instances_after": [ + "2365f2e82518:1" + ], + "confirmed_messages_preserved": 11, + "note": "Closed-loop: one POST + one GET per cycle. RPS counts confirmed HTTP responses, including partial cycles. Latency covers successful cycles only. Recovery includes action duration." + }, + { + "scenario": "stop-api2", + "concurrency": 4, + "elapsed_seconds": 12.482, + "successful_read_write_cycles": 10, + "failed_attempts": 0, + "successful_http_requests": 20, + "successful_rps": 1.602, + "successful_cycles_per_second": 0.801, + "successful_cycles_during_action": 0, + "max_success_gap_seconds": 4.209, + "first_success_after_action_seconds": 7.283, + "latency_ms": { + "p50": 4135.329, + "p95": 5132.049, + "p99": 5132.049 + }, + "instances_before": [ + "2365f2e82518:1", + "dee1b22b5bdc:1" + ], + "instances_after": [ + "dee1b22b5bdc:1" + ], + "confirmed_messages_preserved": 11, + "note": "Closed-loop: one POST + one GET per cycle. RPS counts confirmed HTTP responses, including partial cycles. Latency covers successful cycles only. Recovery includes action duration." + }, + { + "scenario": "rolling-update", + "concurrency": 4, + "elapsed_seconds": 46.853, + "successful_read_write_cycles": 44, + "failed_attempts": 0, + "successful_http_requests": 88, + "successful_rps": 1.878, + "successful_cycles_per_second": 0.939, + "successful_cycles_during_action": 32, + "max_success_gap_seconds": 4.373, + "first_success_after_action_seconds": 40.943, + "latency_ms": { + "p50": 4143.555, + "p95": 4483.856, + "p99": 5183.06 + }, + "instances_before": [ + "2365f2e82518:1", + "dee1b22b5bdc:1" + ], + "instances_after": [ + "071fc584f61a:1", + "efcceb7ba40f:1" + ], + "confirmed_messages_preserved": 45, + "note": "Closed-loop: one POST + one GET per cycle. RPS counts confirmed HTTP responses, including partial cycles. Latency covers successful cycles only. Recovery includes action duration." + } +] diff --git a/evidence/persistence-native.txt b/evidence/persistence-native.txt new file mode 100644 index 0000000..749fd29 --- /dev/null +++ b/evidence/persistence-native.txt @@ -0,0 +1,2 @@ +Executing explicit persistence hook; hook output suppressed to avoid leaking secrets. +PASS: persistence preserved confirmed data and existing session. Hook scope needs operator evidence. diff --git a/evidence/persistence.txt b/evidence/persistence.txt new file mode 100644 index 0000000..749fd29 --- /dev/null +++ b/evidence/persistence.txt @@ -0,0 +1,2 @@ +Executing explicit persistence hook; hook output suppressed to avoid leaking secrets. +PASS: persistence preserved confirmed data and existing session. Hook scope needs operator evidence. diff --git a/evidence/processes-native.json b/evidence/processes-native.json new file mode 100644 index 0000000..240c591 --- /dev/null +++ b/evidence/processes-native.json @@ -0,0 +1,34 @@ +[ + { + "action": "SIGKILL api1", + "stopped_pid": 45, + "running": { + "postgres": 21, + "redis": 22, + "api1": 45, + "api2": 46, + "lb": 49 + } + }, + { + "action": "SIGKILL api2", + "stopped_pid": 46, + "running": { + "postgres": 21, + "redis": 22, + "api1": 92, + "api2": 46, + "lb": 49 + } + }, + { + "action": "rolling-update", + "running": { + "postgres": 21, + "redis": 22, + "api1": 114, + "api2": 119, + "lb": 49 + } + } +] diff --git a/evidence/processes.json b/evidence/processes.json new file mode 100644 index 0000000..85c8b26 --- /dev/null +++ b/evidence/processes.json @@ -0,0 +1,63 @@ +[ + { + "action": "stop-api1", + "before": { + "service": "api1", + "container": "dee1b22b5bdc", + "hostname": "dee1b22b5bdc", + "status": "running" + }, + "after": { + "service": "api1", + "container": "dee1b22b5bdc", + "hostname": "dee1b22b5bdc", + "status": "exited" + } + }, + { + "action": "stop-api2", + "before": { + "service": "api2", + "container": "2365f2e82518", + "hostname": "2365f2e82518", + "status": "running" + }, + "after": { + "service": "api2", + "container": "2365f2e82518", + "hostname": "2365f2e82518", + "status": "exited" + } + }, + { + "action": "rolling-update", + "before": [ + { + "service": "api1", + "container": "dee1b22b5bdc", + "hostname": "dee1b22b5bdc", + "status": "running" + }, + { + "service": "api2", + "container": "2365f2e82518", + "hostname": "2365f2e82518", + "status": "running" + } + ], + "after": [ + { + "service": "api1", + "container": "efcceb7ba40f", + "hostname": "efcceb7ba40f", + "status": "running" + }, + { + "service": "api2", + "container": "071fc584f61a", + "hostname": "071fc584f61a", + "status": "running" + } + ] + } +] diff --git a/evidence/shutdown-native.txt b/evidence/shutdown-native.txt new file mode 100644 index 0000000..e0b9ad6 --- /dev/null +++ b/evidence/shutdown-native.txt @@ -0,0 +1,57 @@ +api1: +INFO: Started server process [35] +INFO: Shutting down +INFO: Application shutdown complete. +INFO: Finished server process [35] +INFO: Started server process [45] +INFO: Started server process [92] +INFO: Shutting down +INFO: Application shutdown complete. +INFO: Finished server process [92] +INFO: Started server process [114] +INFO: Shutting down +INFO: Application shutdown complete. +INFO: Finished server process [114] +INFO: Started server process [152] +INFO: Shutting down +INFO: Application shutdown complete. +INFO: Finished server process [152] +INFO: Started server process [186] +INFO: Shutting down +INFO: Application shutdown complete. +INFO: Finished server process [186] +INFO: Started server process [219] +INFO: Shutting down +INFO: Application shutdown complete. +INFO: Finished server process [219] +INFO: Started server process [226] +INFO: Shutting down +INFO: Application shutdown complete. +INFO: Finished server process [226] +api2: +INFO: Started server process [46] +INFO: Started server process [103] +INFO: Shutting down +INFO: Application shutdown complete. +INFO: Finished server process [103] +INFO: Started server process [119] +INFO: Started server process [130] +INFO: Shutting down +INFO: Application shutdown complete. +INFO: Finished server process [130] +INFO: Started server process [154] +INFO: Shutting down +INFO: Application shutdown complete. +INFO: Finished server process [154] +INFO: Started server process [188] +INFO: Shutting down +INFO: Application shutdown complete. +INFO: Finished server process [188] +INFO: Started server process [220] +INFO: Shutting down +INFO: Application shutdown complete. +INFO: Finished server process [220] +INFO: Started server process [227] +INFO: Shutting down +INFO: Application shutdown complete. +INFO: Finished server process [227] diff --git a/evidence/smoke-native.txt b/evidence/smoke-native.txt new file mode 100644 index 0000000..fc20f9d --- /dev/null +++ b/evidence/smoke-native.txt @@ -0,0 +1 @@ +PASS: lab3 public API scenario; infrastructure and grading evidence remain separate. diff --git a/evidence/smoke.txt b/evidence/smoke.txt new file mode 100644 index 0000000..fc20f9d --- /dev/null +++ b/evidence/smoke.txt @@ -0,0 +1 @@ +PASS: lab3 public API scenario; infrastructure and grading evidence remain separate. diff --git a/evidence/structure.txt b/evidence/structure.txt new file mode 100644 index 0000000..b62af9c --- /dev/null +++ b/evidence/structure.txt @@ -0,0 +1 @@ +PASS: offline skeleton structure, local refs and Python syntax; application NOT tested. diff --git a/evidence/student-tests-native.txt b/evidence/student-tests-native.txt new file mode 100644 index 0000000..3c76ace --- /dev/null +++ b/evidence/student-tests-native.txt @@ -0,0 +1,3 @@ +PASS: 12 concurrent requests across 2 replicas, one message +PASS: conflict, key scope, validation, access and revoked session +PASS: concurrent registration, exactly one 201 and one 409 diff --git a/evidence/student-tests.txt b/evidence/student-tests.txt new file mode 100644 index 0000000..3c76ace --- /dev/null +++ b/evidence/student-tests.txt @@ -0,0 +1,3 @@ +PASS: 12 concurrent requests across 2 replicas, one message +PASS: conflict, key scope, validation, access and revoked session +PASS: concurrent registration, exactly one 201 and one 409 diff --git a/examples/requests.http b/examples/requests.http new file mode 100644 index 0000000..492f938 --- /dev/null +++ b/examples/requests.http @@ -0,0 +1,46 @@ +# 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}} +Idempotency-Key: example-message-001 +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..7b06a7d --- /dev/null +++ b/infra/README.md @@ -0,0 +1,5 @@ +# Инфраструктура + +Стенд задан в compose.yaml. HAProxy использует haproxy.cfg: round-robin между api1 и api2, readiness раз в секунду и обновление адресов через DNS Docker. Публичный порт только у LB. + +Общая PostgreSQL хранит данные и результаты Idempotency-Key; Redis — сессии с AOF. API не создают таблицы при старте: это делает отдельный сервис migrate. Запуск, ограничения и проверки описаны в REPORT.md. diff --git a/infra/haproxy.cfg b/infra/haproxy.cfg new file mode 100644 index 0000000..5316bec --- /dev/null +++ b/infra/haproxy.cfg @@ -0,0 +1,38 @@ +global + log stdout format raw local0 + maxconn 512 + +defaults + mode http + log global + option httplog + timeout connect 1s + timeout client 10s + timeout server 5s + timeout check 2s + retries 1 + option redispatch + +resolvers docker + nameserver dns 127.0.0.11:53 + resolve_retries 2 + timeout resolve 1s + timeout retry 1s + hold valid 1s + hold obsolete 1s + hold nx 1s + hold refused 1s + hold timeout 1s + hold other 1s + +frontend public + bind :8080 + default_backend api + +backend api + balance roundrobin + option httpchk GET /health/ready + http-check expect status 200 + default-server check inter 1s fall 2 rise 1 resolvers docker init-addr libc,none + server api1 api1:8080 + server api2 api2:8080 diff --git a/lab.json b/lab.json new file mode 100644 index 0000000..57bb9fb --- /dev/null +++ b/lab.json @@ -0,0 +1,8 @@ +{ + "number": 3, + "title": "Балансировка и отказ API-реплики", + "contract_version": "1.3.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/requirements-dev.txt b/requirements-dev.txt new file mode 100644 index 0000000..6b103dd --- /dev/null +++ b/requirements-dev.txt @@ -0,0 +1,2 @@ +# Only for full OpenAPI/JSON Schema validation; HTTP tests use stdlib. +openapi-spec-validator==0.7.2 diff --git a/requirements.txt b/requirements.txt new file mode 100644 index 0000000..b34c068 --- /dev/null +++ b/requirements.txt @@ -0,0 +1,8 @@ +fastapi==0.115.4 +uvicorn==0.32.0 +sqlalchemy==2.0.36 +asyncpg==0.30.0 +redis==5.2.0 +passlib[bcrypt]==1.7.4 +bcrypt==4.0.1 +python-dotenv==1.0.1 \ No newline at end of file diff --git a/scripts/check_contract.py b/scripts/check_contract.py new file mode 100644 index 0000000..0c75274 --- /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(encoding='utf-8'))['number'] + spec = json.loads((ROOT/'contracts/openapi.json').read_text(encoding='utf-8')) + 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(encoding='utf-8'),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(encoding='utf-8')) + 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/check_grade4.py b/scripts/check_grade4.py new file mode 100644 index 0000000..b2d74a6 --- /dev/null +++ b/scripts/check_grade4.py @@ -0,0 +1,175 @@ +#!/usr/bin/env python3 +"""Stops each API separately and replaces both under a small closed-loop load.""" +from concurrent.futures import ThreadPoolExecutor +import json +import math +import os +from pathlib import Path +import sys +import subprocess +import threading +import time +import uuid + +ROOT = Path(__file__).resolve().parents[1] +sys.path.insert(0, str(ROOT / "tests")) +from client import Client, Failure, arguments, check, run +from resilience import history +import ops + + +def exercise(c, name, action): + alice, bob, eve, chat = c.bootstrap() + initial_key = uuid.uuid4().hex + initial = c.message(alice, chat, "До воздействия", key=initial_key)["json"] + observed = {c.call("GET", "/api/v1/users/me", actor=alice)["headers"]["X-Instance-Id"] + for _ in range(20)} + check(len(observed) >= 2, "need two actual instances before " + name) + stop = threading.Event() + barrier = threading.Barrier(5) + + def worker(number): + local = Client(c.base, timeout=2) + writes, cycles, errors = [], [], 0 + barrier.wait() + key = uuid.uuid4().hex + body = "worker-%d-%s" % (number, key) + while not stop.is_set(): + started = time.monotonic() + try: + response = local.message(alice, chat, body, key=key) + writes.append(response["json"]) + # Read with the original session while another backend may serve it. + local.call("GET", "/api/v1/chats/" + chat["id"], actor=bob, schema="Chat") + finished = time.monotonic() + cycles.append((finished, finished - started, + response["headers"]["X-Instance-Id"])) + key = uuid.uuid4().hex + body = "worker-%d-%s" % (number, key) + except Failure: + errors += 1 + # An uncertain write keeps its original key and body. + time.sleep(0.05) + return writes, cycles, errors + + started = time.monotonic() + with ThreadPoolExecutor(max_workers=4) as pool: + futures = [pool.submit(worker, n) for n in range(4)] + barrier.wait() + try: + time.sleep(1) + action_started = time.monotonic() + phases = action() + action_finished = time.monotonic() + time.sleep(7) + finally: + stop.set() + results = [f.result() for f in futures] + elapsed = time.monotonic() - started + writes = [msg for messages, _, _ in results for msg in messages] + cycles = sorted(item for _, values, _ in results for item in values) + errors = sum(n for _, _, n in results) + # An in-flight POST can finish before the stop and its paired GET after it. + # Only cycles started after the action count as traffic to a surviving API. + recovered = [t for t, duration, _ in cycles if t - duration >= action_finished] + check(bool(recovered), "no reads/writes after " + name) + recovery = recovered[0] - action_started + check(recovery <= 10 if name.startswith("stop-") else True, + "failover exceeded 10 seconds") + times = [started] + [t for t, _, _ in cycles] + [time.monotonic()] + max_gap = max(b - a for a, b in zip(times, times[1:])) + check(max_gap <= 10, "no successful read/write cycle for more than 10 seconds") + during = [t for t, _, _ in cycles if action_started <= t <= action_finished] + if name == "rolling-update": + check(bool(during), "no successful traffic during rolling replacement") + for phase in phases or []: + check(any(phase["started"] <= t <= phase["finished"] for t in during), + "no successful traffic while replacing " + phase["service"]) + stored = history(c, bob, chat) + ids = {m["id"] for m in stored} + check(len(ids) == len(stored), "duplicate message IDs") + check(len({m["text"] for m in stored}) == len(stored), "retry created duplicate text") + by_id = {m["id"]: m for m in stored} + check(all(by_id.get(m["id"]) == m for m in [initial] + writes), "confirmed data lost") + check(c.message(alice, chat, initial["text"], key=initial_key)["json"] == initial, + "pre-action idempotency result lost") + latency = sorted(d * 1000 for _, d, _ in cycles) + def percentile(p): + return round(latency[max(0, math.ceil(p * len(latency)) - 1)], 3) + result = {"scenario": name, "concurrency": 4, "elapsed_seconds": round(elapsed, 3), + "successful_read_write_cycles": len(cycles), "failed_attempts": errors, + "successful_http_requests": len(writes) + len(cycles), + "successful_rps": round((len(writes) + len(cycles)) / elapsed, 3), + "successful_cycles_per_second": round(len(cycles) / elapsed, 3), + "successful_cycles_during_action": len(during), + "max_success_gap_seconds": round(max_gap, 3), + "first_success_after_action_seconds": round(recovery, 3), + "latency_ms": {"p50": percentile(.5), "p95": percentile(.95), "p99": percentile(.99)}, + "instances_before": sorted(observed), + "instances_after": sorted({i for t, duration, i in cycles + if t - duration >= action_finished}), + "confirmed_messages_preserved": len({m["id"] for m in [initial] + writes}), + "note": "Closed-loop: one POST + one GET per cycle. RPS counts confirmed HTTP responses, including partial cycles. Latency covers successful cycles only. Recovery includes action duration."} + print(json.dumps(result, ensure_ascii=False, indent=2), flush=True) + return result + + +def main(): + args = arguments("Lab3 grade4 Compose experiments") + c = Client(args.base_url, args.ca_file) + ops.BASE_URL = c.base + dest = ROOT / "evidence" + dest.mkdir(exist_ok=True) + http_args = ["--base-url", c.base] + if args.ca_file: + http_args += ["--ca-file", args.ca_file] + + def checked(script, filename, *extra): + result = subprocess.run([sys.executable, str(ROOT / script), *extra], cwd=ROOT, + text=True, encoding="utf-8", stdout=subprocess.PIPE, + stderr=subprocess.STDOUT, + env=dict(os.environ, PYTHONIOENCODING="utf-8")) + (dest / filename).write_text(result.stdout, encoding="utf-8") + print(result.stdout, end="", flush=True) + check(result.returncode == 0, script + " failed; see evidence/" + filename) + + ops.restore() + checked("scripts/check_contract.py", "check.txt") + checked("tests/smoke.py", "smoke.txt", *http_args) + checked("student-tests/run.py", "student-tests.txt", *http_args) + results = [] + processes = [] + for service in ops.SERVICES: + ops.restore() + before = ops.state(service) + try: + result = exercise(c, "stop-" + service, lambda: ops.stop_one(service)) + after = ops.state(service) + check(after["status"] == "exited", "stopped API restarted unexpectedly") + check(all(i.split(":", 1)[0] != before["hostname"] for i in result["instances_after"]), + "stopped replica still handles requests") + results.append(result) + processes.append({"action": "stop-" + service, "before": before, "after": after}) + finally: + ops.restore() + before = [ops.state(s) for s in ops.SERVICES] + results.append(exercise(c, "rolling-update", ops.rolling_update)) + after = [ops.state(s) for s in ops.SERVICES] + check(all(a["container"] != b["container"] for a, b in zip(before, after)), + "both API containers must be replaced") + processes.append({"action": "rolling-update", "before": before, "after": after}) + (dest / "grade4.json").write_text(json.dumps(results, ensure_ascii=False, indent=2) + "\n", encoding="utf-8") + (dest / "processes.json").write_text(json.dumps(processes, ensure_ascii=False, indent=2) + "\n", encoding="utf-8") + suffix = ".cmd" if os.name == "nt" else ".sh" + try: + checked("tests/resilience.py", "failover.txt", "--mode", "failover", + "--action-script", str(ROOT / ("scripts/stop-one" + suffix)), *http_args) + finally: + ops.restore() + checked("tests/resilience.py", "persistence.txt", "--mode", "persistence", + "--action-script", str(ROOT / ("scripts/restart" + suffix)), *http_args) + print("PASS: both replica failures, rolling replacement and confirmed data") + + +if __name__ == "__main__": + run(main) diff --git a/scripts/ops.py b/scripts/ops.py new file mode 100644 index 0000000..344deb1 --- /dev/null +++ b/scripts/ops.py @@ -0,0 +1,112 @@ +#!/usr/bin/env python3 +"""Operator actions for the local Compose stand; volumes are kept.""" +import argparse +import json +import os +from pathlib import Path +import subprocess +import time +import urllib.error +import urllib.request + +ROOT = Path(__file__).resolve().parents[1] +SERVICES = ("api1", "api2") +BASE_URL = os.environ.get("BASE_URL", "http://localhost:8080").rstrip("/") + + +def compose(*args, capture=False): + result = subprocess.run(["docker", "compose", *args], cwd=ROOT, check=True, + text=True, stdout=subprocess.PIPE if capture else None) + return result.stdout.strip() if capture else None + + +def state(service): + cid = compose("ps", "--all", "--quiet", service, capture=True) + if not cid: + raise RuntimeError("No container for " + service) + result = subprocess.check_output( + ["docker", "inspect", "--format", + '{{json .Config.Hostname}} {{json .State.Status}}', cid], text=True) + hostname, status = result.strip().split() + return {"service": service, "container": cid[:12], + "hostname": json.loads(hostname), "status": json.loads(status)} + + +def wait_instances(count=2, timeout=40): + deadline = time.monotonic() + timeout + seen = set() + while time.monotonic() < deadline: + try: + with urllib.request.urlopen(BASE_URL + "/health/ready", timeout=2) as r: + instance = r.headers.get("X-Instance-Id") + if instance: + seen.add(instance) + if len(seen) >= count: + return seen + except (OSError, urllib.error.URLError): + pass + time.sleep(0.2) + raise RuntimeError("Not enough ready API instances through LB") + + +def stop_one(service=None): + target = os.environ.get("TARGET_INSTANCE_ID", "").split(":", 1)[0] + if target: + service = next((s for s in SERVICES if state(s)["hostname"] == target), None) + if not service: + raise RuntimeError("TARGET_INSTANCE_ID is not an API container") + service = service or "api1" + if service not in SERVICES: + raise RuntimeError("Only API replicas may be stopped") + compose("kill", "--signal", "SIGKILL", service) + current = state(service) + if current["status"] != "exited": + raise RuntimeError("API did not stop") + print(json.dumps(current)) + + +def restore(): + compose("up", "-d", "--no-deps", "--no-build", "--wait", "--wait-timeout", "40", *SERVICES) + wait_instances() + + +def restart(): + compose("down") + compose("up", "-d", "--no-build", "--wait", "--wait-timeout", "60") + wait_instances() + + +def rolling_update(): + phases = [] + compose("build", "api1") + # This migration only adds tables and is compatible with the old API. + compose("run", "--rm", "--no-deps", "migrate") + for service in SERVICES: + before = state(service) + started = time.monotonic() + compose("up", "-d", "--no-deps", "--no-build", "--force-recreate", + "--wait", "--wait-timeout", "40", service) + after = state(service) + if before["container"] == after["container"]: + raise RuntimeError("Container was not replaced") + seen = wait_instances() + if not any(i.split(":", 1)[0] == after["hostname"] for i in seen): + raise RuntimeError("LB has not discovered the replacement") + phases.append({"service": service, "started": started, "finished": time.monotonic()}) + print(json.dumps({"replaced": service, "before": before, "after": after})) + return phases + + +def main(): + parser = argparse.ArgumentParser() + parser.add_argument("action", choices=["restart", "stop-one", "restore", "rolling-update"]) + parser.add_argument("--service", choices=SERVICES) + args = parser.parse_args() + if args.action == "stop-one": + stop_one(args.service) + else: + {"restart": restart, "restore": restore, "rolling-update": rolling_update}[args.action]() + + +if __name__ == "__main__": + main() diff --git a/scripts/restart.cmd b/scripts/restart.cmd new file mode 100644 index 0000000..921e224 --- /dev/null +++ b/scripts/restart.cmd @@ -0,0 +1,4 @@ +@echo off +cd /d "%~dp0.." +python scripts\ops.py restart +exit /b %errorlevel% 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..da01f20 --- /dev/null +++ b/scripts/restart.sh @@ -0,0 +1,4 @@ +#!/bin/sh +set -eu +cd "$(dirname "$0")/.." +exec python3 scripts/ops.py restart diff --git a/scripts/stop-one.cmd b/scripts/stop-one.cmd new file mode 100644 index 0000000..8c3cce5 --- /dev/null +++ b/scripts/stop-one.cmd @@ -0,0 +1,4 @@ +@echo off +cd /d "%~dp0.." +python scripts\ops.py stop-one +exit /b %errorlevel% diff --git a/scripts/stop-one.example.sh b/scripts/stop-one.example.sh new file mode 100644 index 0000000..ae149e8 --- /dev/null +++ b/scripts/stop-one.example.sh @@ -0,0 +1,10 @@ +#!/bin/sh +set -eu +# TODO: copy to stop-one.sh, map TARGET_INSTANCE_ID to ONE API container/task. +# Stop that instance and leave it stopped; no stop of DB/LB/volumes. +# Return quickly (within 10 s); the test sends requests during this script. +# Restore the replica explicitly after the test. Never print credentials. +: "${TARGET_INSTANCE_ID:?test provides target API instance alias}" +printf '%s +' 'TODO: implement stop-one.sh for your infrastructure' >&2 +exit 2 diff --git a/scripts/stop-one.sh b/scripts/stop-one.sh new file mode 100644 index 0000000..c7b8ec5 --- /dev/null +++ b/scripts/stop-one.sh @@ -0,0 +1,4 @@ +#!/bin/sh +set -eu +cd "$(dirname "$0")/.." +exec python3 scripts/ops.py stop-one diff --git a/scripts/validate_openapi.py b/scripts/validate_openapi.py new file mode 100644 index 0000000..1542dc6 --- /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(encoding='utf-8')) +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(encoding='utf-8')).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(encoding='utf-8')) + 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/src/__init__.py b/src/__init__.py new file mode 100644 index 0000000..e69de29 diff --git a/src/__main__.py b/src/__main__.py new file mode 100644 index 0000000..d9e021d --- /dev/null +++ b/src/__main__.py @@ -0,0 +1,24 @@ +"""Entry point: uvicorn as PID 1 with env-driven host/port and graceful shutdown.""" +import os + +import uvicorn + +from .main import app + + +def main() -> None: + host = os.environ.get("APP_HOST", "0.0.0.0") + port = int(os.environ.get("APP_PORT", "8080")) + uvicorn.run( + app, + host=host, + port=port, + log_level="info", + access_log=True, + timeout_keep_alive=2, + timeout_graceful_shutdown=5, + ) + + +if __name__ == "__main__": + main() diff --git a/src/auth.py b/src/auth.py new file mode 100644 index 0000000..b9d77a4 --- /dev/null +++ b/src/auth.py @@ -0,0 +1,29 @@ +import os +import secrets +import redis.asyncio as redis +from passlib.context import CryptContext + +# bcrypt_sha256 avoids bcrypt's 72-byte limit. Old lab2 hashes still verify. +pwd_context = CryptContext(schemes=["bcrypt_sha256", "bcrypt"], deprecated="auto") +CACHE_URL = os.environ.get("CACHE_URL", "redis://localhost:6379/0") +SESSION_TTL_SECONDS = int(os.environ.get("SESSION_TTL_SECONDS", "3600")) + +redis_client = redis.from_url(CACHE_URL, decode_responses=True, + socket_connect_timeout=1, socket_timeout=1) + +def hash_password(password: str) -> str: + return pwd_context.hash(password) + +def verify_password(plain_password: str, hashed_password: str) -> bool: + return pwd_context.verify(plain_password, hashed_password) + +async def create_session(user_id: str) -> str: + token = secrets.token_urlsafe(32) + await redis_client.setex(f"session:{token}", SESSION_TTL_SECONDS, user_id) + return token + +async def get_user_id_by_token(token: str) -> str | None: + return await redis_client.get(f"session:{token}") + +async def delete_session(token: str) -> None: + await redis_client.delete(f"session:{token}") diff --git a/src/db.py b/src/db.py new file mode 100644 index 0000000..9d8345c --- /dev/null +++ b/src/db.py @@ -0,0 +1,69 @@ +import os +from datetime import datetime, timezone +from typing import List +from uuid import UUID, uuid4 + +from sqlalchemy import String, ForeignKey, DateTime, Index, Integer +from sqlalchemy.dialects.postgresql import UUID as PG_UUID, JSONB +from sqlalchemy.ext.asyncio import create_async_engine, async_sessionmaker +from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column, relationship + +DATABASE_URL = os.environ.get("DATABASE_URL", "postgresql+asyncpg://user:password@localhost:5432/messenger") +engine = create_async_engine( + DATABASE_URL, echo=False, pool_pre_ping=True, pool_size=5, max_overflow=5, + pool_timeout=2, connect_args={"timeout": 1, "command_timeout": 3, + "server_settings": {"statement_timeout": "2500", "lock_timeout": "2000"}}, +) +async_session = async_sessionmaker(engine, expire_on_commit=False) + +class Base(DeclarativeBase): + pass + +class User(Base): + __tablename__ = "users" + id: Mapped[UUID] = mapped_column(PG_UUID(as_uuid=True), primary_key=True, default=uuid4) + username: Mapped[str] = mapped_column(String(32), unique=True, index=True) + display_name: Mapped[str] = mapped_column(String(100)) + password_hash: Mapped[str] = mapped_column(String(255)) + created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=lambda: datetime.now(timezone.utc)) + +class Chat(Base): + __tablename__ = "chats" + id: Mapped[UUID] = mapped_column(PG_UUID(as_uuid=True), primary_key=True, default=uuid4) + title: Mapped[str] = mapped_column(String(100)) + created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=lambda: datetime.now(timezone.utc)) + members: Mapped[List["ChatMember"]] = relationship(back_populates="chat", lazy="selectin") + +class ChatMember(Base): + __tablename__ = "chat_members" + chat_id: Mapped[UUID] = mapped_column(PG_UUID(as_uuid=True), ForeignKey("chats.id", ondelete="CASCADE"), primary_key=True) + user_id: Mapped[UUID] = mapped_column(PG_UUID(as_uuid=True), ForeignKey("users.id", ondelete="CASCADE"), primary_key=True) + chat: Mapped["Chat"] = relationship(back_populates="members") + user: Mapped["User"] = relationship() + +class Message(Base): + __tablename__ = "messages" + id: Mapped[UUID] = mapped_column(PG_UUID(as_uuid=True), primary_key=True, default=uuid4) + chat_id: Mapped[UUID] = mapped_column(PG_UUID(as_uuid=True), ForeignKey("chats.id", ondelete="CASCADE"), index=True) + sender_id: Mapped[UUID] = mapped_column(PG_UUID(as_uuid=True), ForeignKey("users.id")) + text: Mapped[str] = mapped_column(String(4000)) + created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=lambda: datetime.now(timezone.utc)) + + # Составной индекс для быстрой курсорной пагинации (EXPLAIN покажет Index Scan) + __table_args__ = ( + Index('ix_messages_chat_created_id', 'chat_id', 'created_at', 'id'), + ) + +class IdempotencyKey(Base): + __tablename__ = "idempotency_keys" + user_id: Mapped[UUID] = mapped_column(PG_UUID(as_uuid=True), ForeignKey("users.id"), primary_key=True) + chat_id: Mapped[UUID] = mapped_column(PG_UUID(as_uuid=True), ForeignKey("chats.id"), primary_key=True) + key: Mapped[str] = mapped_column(String(128), primary_key=True) + request_text: Mapped[str] = mapped_column(String(4000)) + response: Mapped[dict | None] = mapped_column(JSONB, nullable=True) + expires_at: Mapped[datetime] = mapped_column(DateTime(timezone=True)) + + +class SchemaVersion(Base): + __tablename__ = "schema_versions" + version: Mapped[int] = mapped_column(Integer, primary_key=True) diff --git a/src/main.py b/src/main.py new file mode 100644 index 0000000..fc1c440 --- /dev/null +++ b/src/main.py @@ -0,0 +1,372 @@ +from __future__ import annotations +import base64 +import asyncio +import binascii +import logging +import os +import re +import socket +import uuid +from contextlib import asynccontextmanager +from datetime import datetime, timezone, timedelta +from typing import Optional + +from fastapi import Depends, FastAPI, Request, Query +from fastapi.exceptions import RequestValidationError +from fastapi.responses import JSONResponse +from fastapi.security import HTTPBearer, HTTPAuthorizationCredentials +from pydantic import BaseModel, ConfigDict, Field, field_validator +from sqlalchemy import select, and_, or_, text +from sqlalchemy.dialects.postgresql import insert +from sqlalchemy.exc import IntegrityError, SQLAlchemyError +from starlette.concurrency import run_in_threadpool +from starlette.exceptions import HTTPException as StarletteHTTPException +from redis.exceptions import RedisError + +from asyncpg import PostgresError +from .db import engine, async_session, User, Chat, ChatMember, Message, IdempotencyKey +from .auth import hash_password, verify_password, create_session, get_user_id_by_token, delete_session, redis_client, SESSION_TTL_SECONDS + +USERNAME_RE = re.compile(r"^[a-z0-9_]{3,32}$") +KEY_RE = re.compile(r"[A-Za-z0-9._:-]{1,128}", re.ASCII) +INSTANCE_ID = socket.gethostname() + ":" + str(os.getpid()) + +def now_iso(dt: datetime = None) -> str: + if not dt: + dt = datetime.now(timezone.utc) + return dt.strftime("%Y-%m-%dT%H:%M:%S.%fZ") + +def error_payload(request_id: str, code: str, message: str) -> dict: + return {"error": {"code": code, "message": message, "request_id": request_id}} + +class ApiError(Exception): + def __init__(self, status: int, code: str, message: str): + self.status = status + self.code = code + self.message = message + super().__init__(message) + +# --- Курсоры для пагинации (с точностью до микросекунд) --- +def _encode_cursor(scope: str, created_at: datetime, obj_id: uuid.UUID) -> str: + raw = f"{scope}|{created_at.isoformat()}|{obj_id}".encode("utf-8") + return base64.urlsafe_b64encode(raw).rstrip(b"=").decode("ascii") + +def _decode_cursor(cursor: str) -> tuple[str, datetime, uuid.UUID]: + try: + padded = cursor + "=" * (-len(cursor) % 4) + raw = base64.urlsafe_b64decode(padded).decode("utf-8") + scope, dt_str, obj_id_str = raw.split("|", 2) + dt = datetime.fromisoformat(dt_str) + if dt.tzinfo is None: + raise ValueError("timezone required") + return scope, dt, uuid.UUID(obj_id_str) + except Exception: + raise ApiError(400, "invalid_request", "invalid cursor") + +# --- Схемы --- +class CreateUser(BaseModel): + model_config = ConfigDict(extra="forbid") + username: str = Field(strict=True) + display_name: str = Field(strict=True, min_length=1, max_length=100) + password: str = Field(strict=True, min_length=12, max_length=128) + + @field_validator("display_name", "password") + @classmethod + def not_blank(cls, value): + if not value.strip(): + raise ValueError("blank value") + return value + +class CreateChat(BaseModel): + model_config = ConfigDict(extra="forbid") + title: str = Field(strict=True, min_length=1, max_length=100) + member_ids: list[uuid.UUID] = Field(min_length=1, max_length=100) + + @field_validator("title") + @classmethod + def not_blank(cls, value): + if not value.strip(): + raise ValueError("blank title") + return value + +class CreateMessage(BaseModel): + model_config = ConfigDict(extra="forbid") + text: str = Field(strict=True, min_length=1, max_length=4000) + + @field_validator("text") + @classmethod + def not_blank(cls, value): + if not value.strip(): + raise ValueError("blank message") + return value + +@asynccontextmanager +async def lifespan(app: FastAPI): + yield + await redis_client.aclose() + await engine.dispose() + +app = FastAPI(title="Messenger", version="1.3.0", lifespan=lifespan) +security_bearer = HTTPBearer(auto_error=False) + +@app.middleware("http") +async def request_id_middleware(request: Request, call_next): + request_id = request.headers.get("X-Request-Id") or str(uuid.uuid4()) + request.state.request_id = request_id + try: + response = await call_next(request) + except Exception: + logging.getLogger(__name__).exception("Request failed: %s", request_id) + response = JSONResponse(status_code=500, content=error_payload(request_id, "internal_error", "internal error")) + response.headers["X-Request-Id"] = request_id + response.headers["X-Instance-Id"] = INSTANCE_ID + return response + +def _rid(request: Request) -> str: + return getattr(request.state, "request_id", None) or str(uuid.uuid4()) + +# --- Обработчики ошибок --- +@app.exception_handler(ApiError) +async def api_error_handler(request: Request, exc: ApiError): + headers = {} + if exc.status == 401: + if request.url.path == "/api/v1/auth/sessions": + headers["WWW-Authenticate"] = 'Basic realm="messenger", charset="UTF-8"' + else: + headers["WWW-Authenticate"] = 'Bearer realm="messenger"' + return JSONResponse(status_code=exc.status, content=error_payload(_rid(request), exc.code, exc.message), headers=headers) + +@app.exception_handler(RequestValidationError) +async def validation_error_handler(request: Request, exc: RequestValidationError): + return JSONResponse(status_code=400, content=error_payload(_rid(request), "invalid_request", "invalid request")) + +@app.exception_handler(StarletteHTTPException) +async def http_exception_handler(request: Request, exc: StarletteHTTPException): + return JSONResponse(status_code=exc.status_code, content=error_payload(_rid(request), "not_found", str(exc.detail))) + +@app.exception_handler(RedisError) +@app.exception_handler(SQLAlchemyError) +@app.exception_handler(PostgresError) +@app.exception_handler(OSError) +@app.exception_handler(TimeoutError) +async def dependency_error_handler(request: Request, exc: Exception): + # Если упала БД или Redis - отдаем 503, как требует контракт + return JSONResponse(status_code=503, content=error_payload(_rid(request), "unavailable", "dependency unavailable")) + +@app.exception_handler(Exception) +async def generic_exception_handler(request: Request, exc: Exception): + return JSONResponse(status_code=500, content=error_payload(_rid(request), "internal_error", "internal error")) + +# --- Зависимости --- +async def get_actor(credentials: HTTPAuthorizationCredentials = Depends(security_bearer)) -> dict: + if not credentials: + raise ApiError(401, "unauthorized", "missing token") + + user_id_str = await get_user_id_by_token(credentials.credentials) + if not user_id_str: + raise ApiError(401, "unauthorized", "invalid or expired token") + + async with async_session() as session: + user = await session.get(User, uuid.UUID(user_id_str)) + if not user: + raise ApiError(401, "unauthorized", "user not found") + return {"id": str(user.id), "username": user.username, "display_name": user.display_name, "created_at": now_iso(user.created_at)} + +# --- Роуты --- +@app.get("/health/live") +def liveness(): + return {"status": "ok"} + +@app.get("/health/ready") +async def readiness(): + async with asyncio.timeout(1.5): + async with async_session() as session: + version = await session.scalar(text("SELECT version FROM schema_versions WHERE version = 3")) + if version != 3: + raise ApiError(503, "unavailable", "migration required") + await redis_client.ping() + return {"status": "ok"} + +@app.post("/api/v1/users", status_code=201) +async def register_user(payload: CreateUser): + if not USERNAME_RE.fullmatch(payload.username): + raise ApiError(400, "invalid_request", "invalid username") + + async with async_session() as session: + existing = await session.scalar(select(User).where(User.username == payload.username)) + if existing: + raise ApiError(409, "conflict", "username already exists") + + password_hash = await run_in_threadpool(hash_password, payload.password) + user = User(username=payload.username, display_name=payload.display_name, password_hash=password_hash) + session.add(user) + try: + await session.commit() + except IntegrityError: + await session.rollback() + raise ApiError(409, "conflict", "username already exists") + + return {"id": str(user.id), "username": user.username, "display_name": user.display_name, "created_at": now_iso(user.created_at)} + +@app.post("/api/v1/auth/sessions", status_code=201) +async def create_session_endpoint(request: Request): + # HTTP Basic carries a UTF-8 password, not only ASCII. + try: + scheme, encoded = request.headers.get("Authorization", "").split(" ", 1) + if scheme.lower() != "basic": + raise ValueError("Basic required") + username, password = base64.b64decode(encoded, validate=True).decode("utf-8").split(":", 1) + except (ValueError, UnicodeError, binascii.Error): + raise ApiError(401, "unauthorized", "invalid credentials") + + async with async_session() as session: + user = await session.scalar(select(User).where(User.username == username)) + if not user or not await run_in_threadpool(verify_password, password, user.password_hash): + raise ApiError(401, "unauthorized", "invalid credentials") + + token = await create_session(str(user.id)) + expires_at = datetime.now(timezone.utc) + timedelta(seconds=SESSION_TTL_SECONDS) + return { + "token": token, + "token_type": "Bearer", + "expires_at": now_iso(expires_at), + "user": {"id": str(user.id), "username": user.username, "display_name": user.display_name, "created_at": now_iso(user.created_at)} + } + +@app.delete("/api/v1/auth/sessions/current", status_code=204) +async def logout(credentials: HTTPAuthorizationCredentials = Depends(security_bearer)): + if not credentials: + raise ApiError(401, "unauthorized", "missing token") + + user_id = await get_user_id_by_token(credentials.credentials) + if not user_id: + raise ApiError(401, "unauthorized", "invalid or expired token") + + await delete_session(credentials.credentials) + +@app.get("/api/v1/users/me") +async def current_user(actor: dict = Depends(get_actor)): + return actor + +@app.post("/api/v1/chats", status_code=201) +async def create_chat(payload: CreateChat, actor: dict = Depends(get_actor)): + member_ids = [str(u) for u in payload.member_ids] + if actor["id"] not in member_ids: + raise ApiError(400, "invalid_request", "creator must be a member") + if len(set(member_ids)) != len(member_ids): + raise ApiError(400, "invalid_request", "duplicate members") + + async with async_session() as session: + users = await session.scalars(select(User.id).where(User.id.in_([uuid.UUID(m) for m in member_ids]))) + if len(list(users)) != len(set(member_ids)): + raise ApiError(400, "invalid_request", "unknown member") + + chat = Chat(title=payload.title) + session.add(chat) + await session.flush() + + for mid in member_ids: + session.add(ChatMember(chat_id=chat.id, user_id=uuid.UUID(mid))) + + await session.commit() + return {"id": str(chat.id), "title": chat.title, "member_ids": member_ids, "created_at": now_iso(chat.created_at)} + +@app.get("/api/v1/chats") +async def list_chats(limit: int = Query(50, ge=1, le=100), cursor: Optional[str] = None, actor: dict = Depends(get_actor)): + async with async_session() as session: + stmt = select(Chat).join(ChatMember).where(ChatMember.user_id == uuid.UUID(actor["id"])) + if cursor: + scope, c_dt, c_id = _decode_cursor(cursor) + if scope != "chats": + raise ApiError(400, "invalid_request", "invalid cursor scope") + stmt = stmt.where(or_( + Chat.created_at > c_dt, + and_(Chat.created_at == c_dt, Chat.id > c_id) + )) + + stmt = stmt.order_by(Chat.created_at.asc(), Chat.id.asc()).limit(limit + 1) + chats = (await session.scalars(stmt)).unique().all() + + has_more = len(chats) > limit + page = chats[:limit] + next_cursor = _encode_cursor("chats", page[-1].created_at, page[-1].id) if has_more and page else None + + items = [] + for c in page: + items.append({ + "id": str(c.id), + "title": c.title, + "created_at": now_iso(c.created_at), + "member_ids": [str(m.user_id) for m in c.members] # Теперь участники возвращаются корректно + }) + + return {"items": items, "next_cursor": next_cursor} + +@app.get("/api/v1/chats/{chat_id}") +async def get_chat(chat_id: uuid.UUID, actor: dict = Depends(get_actor)): + async with async_session() as session: + chat = await session.scalar(select(Chat).join(ChatMember).where(Chat.id == chat_id, ChatMember.user_id == uuid.UUID(actor["id"]))) + if not chat: + raise ApiError(404, "not_found", "chat not found") + return {"id": str(chat.id), "title": chat.title, "member_ids": [str(m.user_id) for m in chat.members], "created_at": now_iso(chat.created_at)} + +@app.post("/api/v1/chats/{chat_id}/messages", status_code=201) +async def post_message(chat_id: uuid.UUID, payload: CreateMessage, request: Request, actor: dict = Depends(get_actor)): + key = request.headers.get("Idempotency-Key", "") + if not KEY_RE.fullmatch(key): + raise ApiError(400, "invalid_request", "invalid Idempotency-Key") + async with async_session() as session: + member = await session.scalar(select(ChatMember).where(and_(ChatMember.chat_id == chat_id, ChatMember.user_id == uuid.UUID(actor["id"])))) + if not member: + raise ApiError(404, "not_found", "chat not found") + + now = datetime.now(timezone.utc) + scope = {"user_id": uuid.UUID(actor["id"]), "chat_id": chat_id, "key": key} + await session.execute(insert(IdempotencyKey).values( + **scope, request_text=payload.text, expires_at=now + timedelta(hours=24) + ).on_conflict_do_nothing()) + record = await session.scalar(select(IdempotencyKey).where( + IdempotencyKey.user_id == scope["user_id"], + IdempotencyKey.chat_id == chat_id, IdempotencyKey.key == key + ).with_for_update()) + if record.response is not None and record.expires_at > now: + if record.request_text != payload.text: + raise ApiError(409, "conflict", "key used with another message") + return record.response + + msg = Message(chat_id=chat_id, sender_id=uuid.UUID(actor["id"]), text=payload.text) + session.add(msg) + await session.flush() + result = {"id": str(msg.id), "chat_id": str(msg.chat_id), "sender_id": str(msg.sender_id), "text": msg.text, "created_at": now_iso(msg.created_at)} + record.request_text = payload.text + record.expires_at = now + timedelta(hours=24) + record.response = result + await session.commit() + return result + +@app.get("/api/v1/chats/{chat_id}/messages") +async def get_messages(chat_id: uuid.UUID, limit: int = Query(50, ge=1, le=100), cursor: Optional[str] = None, actor: dict = Depends(get_actor)): + async with async_session() as session: + member = await session.scalar(select(ChatMember).where(and_(ChatMember.chat_id == chat_id, ChatMember.user_id == uuid.UUID(actor["id"])))) + if not member: + raise ApiError(404, "not_found", "chat not found") + + stmt = select(Message).where(Message.chat_id == chat_id) + if cursor: + scope, c_dt, c_id = _decode_cursor(cursor) + if scope != str(chat_id): + raise ApiError(400, "invalid_request", "invalid cursor scope") + stmt = stmt.where(or_( + Message.created_at > c_dt, + and_(Message.created_at == c_dt, Message.id > c_id) + )) + + stmt = stmt.order_by(Message.created_at.asc(), Message.id.asc()).limit(limit + 1) + messages = (await session.scalars(stmt)).all() + + has_more = len(messages) > limit + page = messages[:limit] + next_cursor = _encode_cursor(str(chat_id), page[-1].created_at, page[-1].id) if has_more and page else None + + items = [{"id": str(m.id), "chat_id": str(m.chat_id), "sender_id": str(m.sender_id), "text": m.text, "created_at": now_iso(m.created_at)} for m in page] + return {"items": items, "next_cursor": next_cursor} diff --git a/src/migrate.py b/src/migrate.py new file mode 100644 index 0000000..2a69d81 --- /dev/null +++ b/src/migrate.py @@ -0,0 +1,18 @@ +import asyncio + +from sqlalchemy import text +from .db import Base, engine + + +async def main(): + async with engine.begin() as conn: + # Only the migrate service creates tables; concurrent operators serialize. + await conn.execute(text("SELECT pg_advisory_xact_lock(300300)")) + await conn.run_sync(Base.metadata.create_all) + await conn.execute(text("INSERT INTO schema_versions(version) VALUES (3) ON CONFLICT DO NOTHING")) + await engine.dispose() + print("Migration 3 applied: existing lab2 tables kept, idempotency added") + + +if __name__ == "__main__": + asyncio.run(main()) diff --git a/student-tests/run.py b/student-tests/run.py new file mode 100644 index 0000000..588ebe2 --- /dev/null +++ b/student-tests/run.py @@ -0,0 +1,76 @@ +#!/usr/bin/env python3 +import sys +import threading +import uuid +from concurrent.futures import ThreadPoolExecutor +from pathlib import Path + +sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "tests")) +from client import Client, arguments, check, run + + +def main(): + args = arguments("Lab3: concurrent idempotency and validation") + c = Client(args.base_url, args.ca_file) + c.call("POST", "/api/v1/users", 400, + body={"username": "valid\n", "display_name": "Test", "password": "LongPassword123"}) + registration = {"username": "race_" + uuid.uuid4().hex[:12], + "display_name": "Race", "password": "LongPassword123"} + registration_barrier = threading.Barrier(2) + + def register(_): + local = Client(args.base_url, args.ca_file) + registration_barrier.wait() + return local.call("POST", "/api/v1/users", [201, 409], + body=registration, schema="User")["status"] + + with ThreadPoolExecutor(max_workers=2) as pool: + check(sorted(pool.map(register, range(2))) == [201, 409], "registration race") + alice, bob, eve, chat = c.bootstrap() + path = "/api/v1/chats/" + chat["id"] + "/messages" + key = uuid.uuid4().hex + barrier = threading.Barrier(12) + + def send(_): + local = Client(args.base_url, args.ca_file) + barrier.wait() + return local.message(alice, chat, "Одна запись", key=key) + + with ThreadPoolExecutor(max_workers=12) as pool: + responses = list(pool.map(send, range(12))) + first = responses[0]["json"] + check(all(r["json"] == first for r in responses), "concurrent replay differs") + instances = {r["headers"]["X-Instance-Id"] for r in responses} + check(len(instances) >= 2, "same key must reach at least two replicas") + page = c.call("GET", path, actor=bob, schema="MessagePage")["json"] + check(page["items"] == [first], "concurrent retry created duplicates") + c.call("POST", path, 409, actor=alice, body={"text": "Изменённый текст"}, + headers={"Idempotency-Key": key}) + c.call("POST", path, 404, actor=eve, body={"text": "Одна запись"}, + headers={"Idempotency-Key": key}) + # The same key belongs to a different scope for Bob and for another chat. + other = c.message(bob, chat, "Другая область", key=key)["json"] + check(other["id"] != first["id"], "different users share an idempotency scope") + second_chat = c.call("POST", "/api/v1/chats", 201, actor=alice, + body={"title": "Второй", "member_ids": [alice["id"]]}, + schema="Chat")["json"] + other = c.message(alice, second_chat, "Одна запись", key=key)["json"] + check(other["id"] != first["id"], "different chats share an idempotency scope") + for bad_key in ("", "bad key", "x" * 129): + c.call("POST", path, 400, actor=alice, body={"text": "Текст"}, + headers={"Idempotency-Key": bad_key}) + for body in ({"text": " "}, {"text": 123}, {"text": "x", "sender_id": alice["id"]}): + c.call("POST", path, 400, actor=alice, body=body, + headers={"Idempotency-Key": uuid.uuid4().hex}) + c.call("POST", path, 400, actor=alice, raw=b'{"text":', + headers={"Content-Type": "application/json", "Idempotency-Key": uuid.uuid4().hex}) + c.call("DELETE", "/api/v1/auth/sessions/current", 204, actor=alice) + c.call("POST", path, 401, actor=alice, body={"text": "Одна запись"}, + headers={"Idempotency-Key": key}) + print("PASS: 12 concurrent requests across %d replicas, one message" % len(instances)) + print("PASS: conflict, key scope, validation, access and revoked session") + print("PASS: concurrent registration, exactly one 201 and one 409") + + +if __name__ == "__main__": + run(main) 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..a32077a --- /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(encoding='utf-8')) + +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 = max(timeout, 5) + 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)