From 3aba500a0eb473fb622a604d22e9483f298de00b Mon Sep 17 00:00:00 2001 From: drunkdiente <145261179+drunkdiente@users.noreply.github.com> Date: Sat, 7 Nov 2026 16:04:29 +0300 Subject: [PATCH] =?UTF-8?q?=D0=A0=D0=B5=D0=B0=D0=BB=D0=B8=D0=B7=D0=BE?= =?UTF-8?q?=D0=B2=D0=B0=D1=82=D1=8C=20=D1=81=D1=82=D0=B5=D0=BD=D0=B4=20?= =?UTF-8?q?=D0=BB=D0=B0=D0=B1=D0=BE=D1=80=D0=B0=D1=82=D0=BE=D1=80=D0=BD?= =?UTF-8?q?=D0=BE=D0=B9=203:=20=D0=B4=D0=B2=D0=B5=20API-=D1=80=D0=B5=D0=BF?= =?UTF-8?q?=D0=BB=D0=B8=D0=BA=D0=B8=20=D0=B8=20=D0=B1=D0=B0=D0=BB=D0=B0?= =?UTF-8?q?=D0=BD=D1=81=D0=B8=D1=80=D0=BE=D0=B2=D0=BA=D0=B0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit FastAPI + PostgreSQL как единый источник истины: пользователи, Basic/Bearer-сессии, чаты, сообщения. Сессии и идемпотентные ключи хранятся в БД, поэтому реплики взаимозаменяемы. Общая идемпотентность POST сообщения по Idempotency-Key, включая конкурентный повтор через разные реплики. compose.yaml: postgres, one-shot migrate, api1, api2 и nginx как единственная публичная точка входа. Добавлены scripts/stop-one.sh и scripts/restart.sh, student-tests, evidence и заполненный REPORT.md. --- .env.example | 26 +- .gitattributes | 7 + Dockerfile | 25 + REPORT.md | 132 ++++- app/__init__.py | 0 app/errors.py | 19 + app/main.py | 599 +++++++++++++++++++++++ app/migrate.py | 60 +++ app/security.py | 63 +++ app/settings.py | 42 ++ app/validation.py | 99 ++++ compose.yaml | 123 +++++ evidence/check.txt | 1 + evidence/concurrent-idempotency.txt | 2 + evidence/db-counts.txt | 25 + evidence/failover-1-ps.txt | 6 + evidence/failover-1.txt | 3 + evidence/failover-2-ps.txt | 6 + evidence/failover-2.txt | 3 + evidence/failover-3-ps.txt | 6 + evidence/failover-3.txt | 3 + evidence/failover-4-ps.txt | 6 + evidence/failover-4.txt | 3 + evidence/failover-final-2-ps.txt | 6 + evidence/failover-final-2.txt | 3 + evidence/failover-final-ps.txt | 6 + evidence/failover-final.txt | 3 + evidence/final-ps.txt | 5 + evidence/instances.txt | 11 + evidence/load.json | 17 + evidence/load.txt | 17 + evidence/persistence-final.txt | 2 + evidence/persistence.txt | 2 + evidence/restart-scope.txt | 12 + evidence/session-across-replicas.txt | 2 + evidence/smoke-after-restart.txt | 1 + evidence/smoke-final.txt | 1 + evidence/smoke.txt | 1 + evidence/verify-failover-ps.txt | 6 + evidence/verify-failover.txt | 3 + evidence/verify-idempotency.txt | 2 + evidence/verify-persistence.txt | 2 + evidence/verify-sessions.txt | 2 + evidence/verify-smoke.txt | 1 + infra/nginx/nginx.conf | 70 +++ migrations/001_init.sql | 61 +++ requirements.txt | 4 + scripts/restart.sh | 9 + scripts/stop-one.sh | 23 + student-tests/concurrent_idempotency.py | 80 +++ student-tests/session_across_replicas.py | 40 ++ 51 files changed, 1629 insertions(+), 22 deletions(-) create mode 100644 .gitattributes create mode 100644 Dockerfile create mode 100644 app/__init__.py create mode 100644 app/errors.py create mode 100644 app/main.py create mode 100644 app/migrate.py create mode 100644 app/security.py create mode 100644 app/settings.py create mode 100644 app/validation.py create mode 100644 compose.yaml create mode 100644 evidence/check.txt create mode 100644 evidence/concurrent-idempotency.txt create mode 100644 evidence/db-counts.txt create mode 100644 evidence/failover-1-ps.txt create mode 100644 evidence/failover-1.txt create mode 100644 evidence/failover-2-ps.txt create mode 100644 evidence/failover-2.txt create mode 100644 evidence/failover-3-ps.txt create mode 100644 evidence/failover-3.txt create mode 100644 evidence/failover-4-ps.txt create mode 100644 evidence/failover-4.txt create mode 100644 evidence/failover-final-2-ps.txt create mode 100644 evidence/failover-final-2.txt create mode 100644 evidence/failover-final-ps.txt create mode 100644 evidence/failover-final.txt create mode 100644 evidence/final-ps.txt create mode 100644 evidence/instances.txt create mode 100644 evidence/load.json create mode 100644 evidence/load.txt create mode 100644 evidence/persistence-final.txt create mode 100644 evidence/persistence.txt create mode 100644 evidence/restart-scope.txt create mode 100644 evidence/session-across-replicas.txt create mode 100644 evidence/smoke-after-restart.txt create mode 100644 evidence/smoke-final.txt create mode 100644 evidence/smoke.txt create mode 100644 evidence/verify-failover-ps.txt create mode 100644 evidence/verify-failover.txt create mode 100644 evidence/verify-idempotency.txt create mode 100644 evidence/verify-persistence.txt create mode 100644 evidence/verify-sessions.txt create mode 100644 evidence/verify-smoke.txt create mode 100644 infra/nginx/nginx.conf create mode 100644 migrations/001_init.sql create mode 100644 requirements.txt create mode 100755 scripts/restart.sh create mode 100755 scripts/stop-one.sh create mode 100644 student-tests/concurrent_idempotency.py create mode 100644 student-tests/session_across_replicas.py diff --git a/.env.example b/.env.example index d32b9be0..d937d8b9 100644 --- a/.env.example +++ b/.env.example @@ -1,13 +1,25 @@ # Copy to .env for your LOCAL synthetic test environment; never commit .env. -# These are logical interface suggestions; map actual framework names in REPORT.md. +# Values below are local-only placeholders, not production secrets. APP_HOST=0.0.0.0 APP_PORT=8080 APP_ENV=lab + +# Session lifetime in seconds. Public smoke needs >= 300, default is 3600. SESSION_TTL_SECONDS=3600 -# Choose credentials locally. File paths contain no secret values. -DATABASE_URL_FILE=/run/secrets/database_url -# Optional on 3, required use on 4 in lab2; Redis OR Valkey: -SESSION_STORE=postgres -CACHE_URL_FILE=/run/secrets/cache_url -API_REPLICAS=2 + +# Idempotency result retention (contract: at least 24 hours). IDEMPOTENCY_TTL_SECONDS=86400 + +# PostgreSQL is the single source of truth: users, chats, messages, +# sessions and idempotency keys all live here. +POSTGRES_DB=messenger +POSTGRES_USER=messenger +POSTGRES_PASSWORD=local_lab3_synthetic_password + +# The API accepts either DATABASE_URL or DATABASE_URL_FILE (path to a file +# containing the URL). compose.yaml builds DATABASE_URL from POSTGRES_*. +# DATABASE_URL=postgresql://messenger:local_lab3_synthetic_password@localhost:5432/messenger +# DATABASE_URL_FILE=/run/secrets/database_url + +# Informational: number of API replicas described in compose.yaml. +API_REPLICAS=2 diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 00000000..05c66ac2 --- /dev/null +++ b/.gitattributes @@ -0,0 +1,7 @@ +# Keep POSIX shell hooks usable on Linux/macOS checkouts. +* text=auto +*.sh text eol=lf +Dockerfile text eol=lf +*.yaml text eol=lf +*.yml text eol=lf +*.sql text eol=lf diff --git a/Dockerfile b/Dockerfile new file mode 100644 index 00000000..e8875ec0 --- /dev/null +++ b/Dockerfile @@ -0,0 +1,25 @@ +# API runtime for laboratory 3. Pinned base image and Python dependencies. +FROM python:3.12.6-slim-bookworm + +ENV PYTHONDONTWRITEBYTECODE=1 \ + PYTHONUNBUFFERED=1 \ + PIP_NO_CACHE_DIR=1 \ + PIP_DISABLE_PIP_VERSION_CHECK=1 + +WORKDIR /app + +COPY requirements.txt ./ +RUN pip install --no-cache-dir -r requirements.txt + +COPY app ./app +COPY migrations ./migrations + +RUN groupadd --gid 10001 app \ + && useradd --uid 10001 --gid 10001 --create-home app + +USER 10001:10001 +EXPOSE 8080 + +# Uvicorn is PID 1: it handles SIGTERM, stops accepting new connections and +# drains in-flight requests within the graceful shutdown window. +CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8080", "--no-access-log", "--timeout-graceful-shutdown", "5"] diff --git a/REPORT.md b/REPORT.md index c2679005..5f4607f7 100644 --- a/REPORT.md +++ b/REPORT.md @@ -1,37 +1,139 @@ # Отчёт — лабораторная 3 -- Автор, группа: TODO -- Целевая оценка; выбранный трек 5, если нужен: TODO +- Автор, группа: TODO (заполнить перед PR) +- Целевая оценка: **3 — работающий минимум**. Уровень 4 и трек 5 не заявлены. - Commit/PR: TODO после публикации -- Использованные источники, библиотеки и помощь ИИ: TODO +- Использованные источники, библиотеки и помощь ИИ: `contracts/openapi.json`, `contracts/README.md`, `README.md`, публичные тесты `tests/`; FastAPI 0.115.0, uvicorn 0.30.6, psycopg 3.2.3, psycopg-pool 3.3.3, PostgreSQL 16.4, Nginx 1.26.2. Реализация и текст отчёта подготовлены с помощью ИИ-ассистента Koda; все приведённые проверки выполнены и воспроизведены локально. ## Запуск из чистого clone -TODO: версии runtime/образов, prerequisites, команды создания локальных secrets/.env, build, миграций, запуска, ожидания готовности, тестов и остановки. Указать необходимые действия оператора. Не вставлять секреты. Отдельно указать безопасную остановку и команду намеренного удаления учебных данных. +Проверено на: Windows 11 Pro 22621 x64, AMD Ryzen 7 7700 (8 ядер / 16 потоков), 32 GB RAM, Docker Engine 29.4.3, Docker Compose v5.1.3 (Linux containers), Python 3.10.11 для публичных тестов. Дата прогонов: 2026-11-07. + +Версии зафиксированы: `python:3.12.6-slim-bookworm`, `postgres:16.4-alpine`, `nginx:1.26.2-alpine`; Python-зависимости — в `requirements.txt`. + +```sh +# 1. Локальная конфигурация (значения в примере синтетические, .env не коммитится) +cp .env.example .env + +# 2. Проверка и сборка/запуск всего стенда +docker compose --env-file .env config --quiet +docker compose --env-file .env up -d --build + +# 3. Ожидание готовности (миграции выполняются автоматически отдельным сервисом) +curl -fsS http://localhost:8080/health/ready + +# 4. Проверки +make check +make test BASE_URL=http://localhost:8080 +make test-persistence ACTION_SCRIPT=scripts/restart.sh +make test-failover ACTION_SCRIPT=scripts/stop-one.sh + +# 5. Восстановление остановленной в failover реплики (api1 или api2) +docker compose --env-file .env start api1 +docker compose --env-file .env restart lb + +# 6. Штатная остановка без удаления данных +docker compose --env-file .env down + +# 7. Намеренное удаление учебных данных и volumes (необратимо) +docker compose --env-file .env down -v +``` + +На Windows-хосте `make` не установлен, поэтому вместо целей Makefile выполнены те же команды напрямую: `python scripts/check_contract.py`, `python tests/smoke.py --base-url http://localhost:8080`, `python tests/resilience.py --mode persistence|failover --action-script ...`. Скрипты `restart.sh`/`stop-one.sh` — POSIX shell, поэтому resilience-тесты запускались в Linux-контейнере `docker:27-cli` с смонтированным репозиторием и Docker-сокетом: + +```sh +docker run --rm --network mtusi-lab3_appnet \ + -v ":/repo" -v /var/run/docker.sock:/var/run/docker.sock \ + -w /repo -e PYTHONUTF8=1 docker:27-cli \ + sh -lc "apk add --no-cache python3 >/dev/null && \ + python3 tests/resilience.py --mode failover \ + --action-script scripts/stop-one.sh --base-url http://lb:8080" +``` + +На Linux/macOS те же проверки запускаются обычными командами Makefile из блока выше. ## Архитектура и решения -TODO: схема процессов/хранилищ, источник истины, транзакционные границы, ограничения. Что перенесено из lab2, что изменено в этой работе. Соответствие переменных из .env.example реальной конфигурации. +```text +клиент + | + v +lb (nginx :8080) — единственный опубликованный порт + | round-robin, passive health, retry на вторую реплику + +--> api1 (uvicorn :8080, INSTANCE_ID=api-1) --+ + +--> api2 (uvicorn :8080, INSTANCE_ID=api-2) --+ + v + postgres:16.4 (volume pgdata) + users, chats, chat_members, messages, + sessions, idempotency_keys +``` + +- **Источник истины — PostgreSQL.** В API нет локальных сессий, сообщений или идемпотентных ключей. Единственное локальное состояние процесса — стабильный `X-Instance-Id` (`api-1`/`api-2`) из переменной окружения. +- **Реплики взаимозаменяемы.** `api1` и `api2` собираются из одного Dockerfile и образа, не публикуют порты наружу, имеют одинаковый `DATABASE_URL`. Клиент ходит только через `lb`. +- **Балансировщик.** Nginx upstream `api1:8080`, `api2:8080`, `max_fails=1 fail_timeout=5s`, `proxy_connect_timeout 1s`, `proxy_read_timeout 10s`. `proxy_next_upstream ... non_idempotent` повторяет POST на второй реплике; это безопасно, потому что создание сообщения идемпотентно по `Idempotency-Key`. +- **Миграции отдельно.** Сервис `migrate` запускается один раз, ждёт готовности PostgreSQL, берёт advisory lock, применяет идемпотентный `migrations/001_init.sql` и завершается с кодом 0. Реплики стартуют только после `service_completed_successfully`, поэтому гонки DDL между ними нет. +- **Graceful shutdown.** Uvicorn — PID 1, получает SIGTERM, перестаёт принимать соединения и до 5 с завершает текущие запросы (`--timeout-graceful-shutdown 5`), `stop_grace_period: 10s`. Nginx в это время повторяет запрос на живую реплику. +- **Сессии.** Basic используется только в `POST /api/v1/auth/sessions`. Токен — `secrets.token_urlsafe(48)` (384 бита), в БД хранится только SHA-256 токена и `expires_at`; TTL из `SESSION_TTL_SECONDS` (по умолчанию 3600). Перезапуск не продлевает TTL. +- **Пароли.** `hashlib.scrypt` (N=2^14, r=8, p=1, 32-байтовый digest, случайная соль), не SHA-256 и не plaintext. +- **Транзакционные границы.** Регистрация — один INSERT с уникальным `username`. Создание чата — чат и все `chat_members` в одной транзакции после проверки существования участников. Отправка сообщения — проверка членства, вставка/чтение `idempotency_keys`, вставка `messages` и запись сохранённого ответа в одной транзакции. +- **Идемпотентность.** Первичный ключ `(user_id, method, path, key)`; `INSERT ... ON CONFLICT DO NOTHING` определяет владельца, конкурентный запрос ждёт завершения транзакции владельца и читает сохранённый ответ. Хранится канонический хеш тела: другой JSON при том же ключе — `409`, тот же JSON — исходный `201` и то же сообщение. Срок хранения — `IDEMPOTENCY_TTL_SECONDS` (24 ч). +- **История.** Keyset-пагинация по `(created_at, id)` по возрастанию, `limit` 1–100 (по умолчанию 50), непрозрачный base64-cursor со scope. Cursor от другого чата/коллекции — `400`; последний элемент страницы не повторяется; `next_cursor=null`, если следующей записи нет. +- **Ошибки.** Единый конверт `{"error":{"code","message","request_id"}}`, `X-Request-Id` совпадает с телом, `X-Instance-Id` добавляется middleware ко всем ответам API, включая ошибки и health. +- **Перенос из lab2.** В этом репозитории нет кода lab2, поэтому обязательные возможности lab2 (PostgreSQL, регистрация с паролем, Basic → Bearer-сессия, миграции, сохранность) реализованы здесь же. In-memory fallback отсутствует. + +Соответствие `.env.example` реальной конфигурации: + +| Переменная | Где используется | Смысл | +| --- | --- | --- | +| `APP_HOST`, `APP_PORT`, `APP_ENV` | compose | информационные параметры стенда | +| `SESSION_TTL_SECONDS` | API | TTL сессии, по умолчанию 3600 | +| `IDEMPOTENCY_TTL_SECONDS` | API | срок хранения результата, по умолчанию 86400 | +| `POSTGRES_DB`, `POSTGRES_USER`, `POSTGRES_PASSWORD` | compose → `DATABASE_URL` | общая БД; пароль в примере синтетический | +| `DATABASE_URL` / `DATABASE_URL_FILE` | API, migrate | альтернативные способы передать строку подключения | +| `API_REPLICAS` | документация | фактическое число реплик задано сервисами `api1`/`api2` | ## Доказательства критериев | Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства | | --- | --- | --- | --- | -| Публичный smoke | make test | TODO | TODO | -| Остальные пункты уровня 3 | TODO | TODO | TODO | -| Все пункты уровня 4, если заявлен | TODO | TODO | TODO | -| Выбранный трек 5, если заявлен | TODO | TODO | TODO | - -TODO: добавить отдельную строку для каждого заявленного критерия. PASS без команды и наблюдения не является доказательством. Проверка инфраструктурного hook требует подтверждения, какие реальные процессы/хранилища перезапущены. +| Офлайн-структура и контракт | `python scripts/check_contract.py` (эквивалент `make check`) | `PASS: offline skeleton structure...` | `evidence/check.txt` | +| Compose-стенд описан и валиден | `docker compose --env-file .env config --quiet` | код 0, ошибок нет | вывод в отчёте, `compose.yaml` | +| Публичный smoke | `python tests/smoke.py --base-url http://localhost:8080` (эквивалент `make test`) | `PASS: lab3 public API scenario` | `evidence/smoke-final.txt`, `evidence/smoke.txt` | +| ≥2 API-реплики, одна точка входа, общая БД | `docker compose ps`; 10 запросов `/health/live` | `api1`/`api2` healthy; опубликован только `lb` 8080; `postgres` healthy | `evidence/instances.txt`, `evidence/final-ps.txt` | +| Одна сессия обслуживается разными репликами без повторного входа | `python student-tests/session_across_replicas.py` | 12 запросов с одним Bearer: `api-1, api-2, api-1, api-2, ...` | `evidence/session-across-replicas.txt` | +| Остановка одной реплики: чтение/запись продолжаются | failover-тест, цель `api-1` | 85 успешных записей, 0 ошибок, первое восстановление 0.558 с (в повторных прогонах 0.65–1.43 с); `api1` — `Exited (0)`, `api2` работает | `evidence/failover-final.txt`, `evidence/failover-final-ps.txt` | +| Остановка второй реплики | failover-тест, цель `api-2` | 90 успешных записей, 0 ошибок, восстановление 0.546 с; `api2` — `Exited (0)`, `api1` работает | `evidence/failover-final-2.txt`, `evidence/failover-final-2-ps.txt` | +| Подтверждённые сообщения доступны после отказа, дублей нет | тот же failover-тест | тест читает всю историю, проверяет исходное сообщение, все подтверждённые записи и уникальность текстов | `evidence/failover-final.txt` | +| Последовательный повтор `Idempotency-Key` | публичный smoke | повтор возвращает то же сообщение; другой body — `409`; без ключа — `400` | `evidence/smoke-final.txt` | +| Конкурентный повтор через разные реплики | `python student-tests/concurrent_idempotency.py` | 40 одновременных POST с одним ключом: реплики `api-1` и `api-2`, ровно 1 сообщение, другой body — `409` | `evidence/concurrent-idempotency.txt` | +| Сохранность данных и сессии после перезапуска | persistence-тест + `scripts/restart.sh` | `PASS`; прежний токен и данные доступны без повторного входа; в БД после всех прогонов 40 пользователей, 13 чатов, 4171 сообщение, 37 сессий | `evidence/persistence-final.txt`, `evidence/db-counts.txt` | +| Hook действительно перезапустил хранилища | `docker inspect` до/после `scripts/restart.sh` | у `postgres`, `api1`, `api2`, `lb` изменился `State.StartedAt` | `evidence/restart-scope.txt` | +| Health/readiness | `curl /health/ready` | `{"status":"ok"}`; readiness проверяет `SELECT 1` к PostgreSQL | `evidence/instances.txt` | +| Миграции не гоняются репликами | `docker compose ps -a` | `migrate` завершился `Exited (0)` до старта API | `evidence/failover-final-ps.txt` | +| Версии образов/зависимостей зафиксированы | `Dockerfile`, `compose.yaml`, `requirements.txt` | явные теги/пины, без `latest` | файлы репозитория | +| Нагрузочный профиль (дополнительно) | `python tests/load.py --duration 15 --concurrency 4` | 3722 успешных запроса, 0 ошибок, 247.6 RPS, p50/p95/p99 = 16/32/46 мс | `evidence/load.txt`, `evidence/load.json` | ## Эксперименты и отказы -TODO: гипотеза, hardware/лимиты, версии, объём данных, профиль нагрузки, concurrency/arrival rate, длительность/прогрев, повторы, успешные RPS, ошибки, p50/p95/p99, CPU/RAM. Сохранить raw summary без tokens и объяснить ограничения измерения. +Условия: один Docker-host, сервисные лимиты `api` 1 CPU / 256 MB, `postgres` 1 CPU / 512 MB, `lb` 0.5 CPU / 128 MB. Все запросы идут через `http://localhost:8080` (nginx). Данные синтетические. -| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных | +| Воздействие | Что ожидали | Что наблюдали | Время восстановления / потеря данных | | --- | --- | --- | --- | -| TODO | TODO | TODO | TODO | +| `stop api1` во время 15-секундной серии POST | Записи продолжаются через `api2`, подтверждённые сообщения не теряются | 85 успешных записей, 0 неудачных попыток; `api1` остановлен (`Exited (0)`), `api2` healthy | первое восстановление 0.558 с; потерь и дублей нет | +| `stop api2` во время такой же серии | То же через `api1` | 90 успешных записей, 0 неудачных; `api2` остановлен, `api1` healthy | 0.546 с; потерь и дублей нет | +| 40 одновременных POST с одним `Idempotency-Key` | Ровно одно сообщение, одинаковые ответы | Оба экземпляра обслужили запросы, все ответы совпали, в истории 1 копия; другой body — `409` | потерь нет | +| `scripts/restart.sh`: рестарт PostgreSQL, api1, api2, lb | Данные, сессии и схема сохраняются | Persistence-тест `PASS`; у всех четырёх контейнеров новый `StartedAt` | сессия и сообщения доступны без повторного входа | +| Пересборка образа и `up -d --build` | Сессии/сообщения не зависят от жизни процесса | Smoke после пересборки `PASS`; в PostgreSQL сохранились 40 пользователей, 13 чатов, 4171 сообщение и 37 сессий | потерь нет | + +Нагрузочный прогон: 15 с, concurrency 4, closed-loop генератор `tests/load.py` без автоматических retry. Получено 3722 успешных POST, 0 ошибок, 247.6 успешных RPS, p50 16 мс, p95 32 мс, p99 46 мс. Это throughput HTTP-подтверждений через LB, а не точный счётчик COMMIT; генератор ограничен клиентом, страдает coordinated omission, а latency посчитана только по успешным запросам. CPU/RAM контейнеров в этом прогоне не сэмплировались, поэтому цифры не заявляются как saturation point. ## Ограничения и следующие шаги -TODO: какие отказы выдерживаются и какие нет; что не реализовано; где учебное упрощение; какое улучшение подтверждено, а какое пока гипотеза. +- Стенд работает на одном Docker-host. Потеря узла, а также отказ единственных PostgreSQL и nginx не выдерживаются: они остаются SPOF. Проверен только отказ одного API-процесса. +- Nginx разрешает имена `api1`/`api2` при старте. После восстановления остановленной реплики надёжный способ вернуть её в балансировку — `docker compose start apiN` и `docker compose restart lb`; в проверенных прогонах Docker переиспользовал IP, но на это не следует опираться. Следующий шаг — динамический resolver/`resolve` в upstream. +- После восстановления реплика возвращается в балансировку не мгновенно: если первый запрос к ней попал в момент старта, nginx держит её вне пула до `fail_timeout=5s`. Это наблюдалось один раз сразу после `restart lb`; в рабочий период оба экземпляра получают запросы. Поэтому `student-tests/session_across_replicas.py` сначала ждёт появления обоих экземпляров, а затем проверяет одну сессию. +- Сессии и идемпотентные ключи хранятся в PostgreSQL; Redis/Valkey не используется. Это соответствует контракту lab3, но увеличивает нагрузку на БД. +- Просроченные идемпотентные ключи удаляются лениво — при повторном использовании ключа; фоновой очистки нет. +- Не реализованы TLS, rate limiting, вложения, фоновая обработка, телеметрия — это следующие лабораторные, для оценки 3 они не требуются. +- Уровень 4 (поочерёдная остановка всех реплик с метриками RPS/ошибок, rolling update под нагрузкой, CPU/RAM-лимиты как проверяемый критерий) и трек 5 не заявляются. Лимиты ресурсов в compose заданы, но измерение saturation и сравнение 1/2/4 реплик не проводилось. +- На Windows-хосте отсутствует `make`, поэтому публичные цели запускались эквивалентными командами; на Linux/macOS команды Makefile применимы без изменений. diff --git a/app/__init__.py b/app/__init__.py new file mode 100644 index 00000000..e69de29b diff --git a/app/errors.py b/app/errors.py new file mode 100644 index 00000000..7ca121db --- /dev/null +++ b/app/errors.py @@ -0,0 +1,19 @@ +"""Domain errors mapped to the contract error envelope.""" +from __future__ import annotations + +from typing import Mapping + + +class ApiError(Exception): + def __init__( + self, + status_code: int, + code: str, + message: str, + headers: Mapping[str, str] | None = None, + ) -> None: + super().__init__(message) + self.status_code = status_code + self.code = code + self.message = message + self.headers = dict(headers or {}) diff --git a/app/main.py b/app/main.py new file mode 100644 index 00000000..ba13bbb9 --- /dev/null +++ b/app/main.py @@ -0,0 +1,599 @@ +"""HTTP API for laboratory 3: shared state, two interchangeable replicas.""" +from __future__ import annotations + +import base64 +import hashlib +import json +import logging +import uuid +from contextlib import asynccontextmanager +from datetime import datetime, timezone +from typing import Any + +from fastapi import FastAPI, Request, Response +from fastapi.responses import JSONResponse +from psycopg import errors as pg_errors +from psycopg.rows import dict_row +from psycopg.types.json import Jsonb +from psycopg_pool import AsyncConnectionPool +from starlette.exceptions import HTTPException as StarletteHTTPException + +from .errors import ApiError +from .security import hash_password, new_session_token, token_digest, verify_password +from .settings import load_settings +from .validation import ( + invalid, + parse_limit, + parse_uuid, + reject_unknown_fields, + require_string, + validate_display_name, + validate_idempotency_key, + validate_member_ids, + validate_message_text, + validate_password, + validate_title, + validate_username, +) + +logger = logging.getLogger("messenger.api") +logging.basicConfig(level=logging.INFO, format="%(asctime)s %(levelname)s %(name)s %(message)s") + +settings = load_settings() + +BASIC_CHALLENGE = {"WWW-Authenticate": 'Basic realm="messenger", charset="UTF-8"'} +BEARER_CHALLENGE = {"WWW-Authenticate": 'Bearer realm="messenger"'} + + +@asynccontextmanager +async def lifespan(app: FastAPI): + pool = AsyncConnectionPool( + settings.database_url, + min_size=1, + max_size=10, + timeout=5, + open=False, + kwargs={"application_name": settings.instance_id}, + ) + await pool.open(wait=False) + app.state.pool = pool + try: + yield + finally: + await pool.close() + + +app = FastAPI(title="MTUSI Messenger lab3", lifespan=lifespan, docs_url=None, redoc_url=None) + + +def error_response( + request: Request, + status_code: int, + code: str, + message: str, + headers: dict[str, str] | None = None, +) -> JSONResponse: + request_id = getattr(request.state, "request_id", None) or str(uuid.uuid4()) + response = JSONResponse( + status_code=status_code, + content={"error": {"code": code, "message": message, "request_id": request_id}}, + ) + for name, value in (headers or {}).items(): + response.headers[name] = value + return response + + +@app.middleware("http") +async def add_instance_and_request_headers(request: Request, call_next): + request_id = str(uuid.uuid4()) + request.state.request_id = request_id + try: + response = await call_next(request) + except ApiError as exc: # defensive: handlers normally convert this first + response = error_response(request, exc.status_code, exc.code, exc.message, exc.headers) + except Exception: + logger.exception("unhandled error while serving request") + response = error_response(request, 500, "internal_error", "Internal server error") + response.headers["X-Request-Id"] = request_id + response.headers["X-Instance-Id"] = settings.instance_id + return response + + +@app.exception_handler(ApiError) +async def api_error_handler(request: Request, exc: ApiError) -> JSONResponse: + return error_response(request, exc.status_code, exc.code, exc.message, exc.headers) + + +@app.exception_handler(StarletteHTTPException) +async def http_error_handler(request: Request, exc: StarletteHTTPException) -> JSONResponse: + code = "not_found" if exc.status_code == 404 else "invalid_request" + return error_response(request, exc.status_code, code, "Request could not be processed") + + +@app.exception_handler(Exception) +async def unhandled_error_handler(request: Request, exc: Exception) -> JSONResponse: + logger.exception("unhandled error: %s", type(exc).__name__) + return error_response(request, 500, "internal_error", "Internal server error") + + +def iso_utc(value: datetime) -> str: + if value.tzinfo is None: + value = value.replace(tzinfo=timezone.utc) + return value.astimezone(timezone.utc).isoformat().replace("+00:00", "Z") + + +def user_json(row: dict[str, Any]) -> dict[str, Any]: + return { + "id": str(row["id"]), + "username": row["username"], + "display_name": row["display_name"], + "created_at": iso_utc(row["created_at"]), + } + + +def message_json(row: dict[str, Any]) -> dict[str, Any]: + return { + "id": str(row["id"]), + "chat_id": str(row["chat_id"]), + "sender_id": str(row["sender_id"]), + "text": row["text"], + "created_at": iso_utc(row["created_at"]), + } + + +def chat_json(row: dict[str, Any], member_ids: list[str]) -> dict[str, Any]: + return { + "id": str(row["id"]), + "title": row["title"], + "member_ids": member_ids, + "created_at": iso_utc(row["created_at"]), + } + + +async def read_json_object(request: Request) -> dict[str, Any]: + raw = await request.body() + try: + value = json.loads(raw) + except (ValueError, UnicodeDecodeError) as exc: + raise invalid("Request body must be valid JSON") from exc + if not isinstance(value, dict): + raise invalid("Request body must be a JSON object") + return value + + +async def authenticate(request: Request) -> dict[str, Any]: + header = request.headers.get("authorization", "") + scheme, _, token = header.partition(" ") + token = token.strip() + if scheme.lower() != "bearer" or not token: + raise ApiError(401, "unauthorized", "Bearer token required", BEARER_CHALLENGE) + + digest = token_digest(token) + async with request.app.state.pool.connection() as conn: + async with conn.cursor(row_factory=dict_row) as cur: + await cur.execute( + """ + SELECT u.id, u.username, u.display_name, u.created_at + FROM sessions s + JOIN users u ON u.id = s.user_id + WHERE s.token_hash = %s AND s.expires_at > now() + """, + (digest,), + ) + row = await cur.fetchone() + if row is None: + raise ApiError(401, "unauthorized", "Session is not valid", BEARER_CHALLENGE) + request.state.token_hash = digest + return row + + +async def require_member(pool: AsyncConnectionPool, chat_id: uuid.UUID, user_id: uuid.UUID) -> None: + async with pool.connection() as conn: + async with conn.cursor() as cur: + await cur.execute( + "SELECT 1 FROM chat_members WHERE chat_id = %s AND user_id = %s", + (chat_id, user_id), + ) + if await cur.fetchone() is None: + raise ApiError(404, "not_found", "Chat not found") + + +async def chat_members(pool: AsyncConnectionPool, chat_ids: list[uuid.UUID]) -> dict[uuid.UUID, list[str]]: + result: dict[uuid.UUID, list[str]] = {chat_id: [] for chat_id in chat_ids} + if not chat_ids: + return result + async with pool.connection() as conn: + async with conn.cursor() as cur: + await cur.execute( + """ + SELECT chat_id, user_id + FROM chat_members + WHERE chat_id = ANY(%s::uuid[]) + ORDER BY chat_id, user_id + """, + (chat_ids,), + ) + for chat_id, user_id in await cur.fetchall(): + result[chat_id].append(str(user_id)) + return result + + +def encode_cursor(scope: str, created_at: datetime, item_id: uuid.UUID) -> str: + payload = {"v": 1, "s": scope, "t": iso_utc(created_at), "i": str(item_id)} + raw = json.dumps(payload, separators=(",", ":"), ensure_ascii=False).encode("utf-8") + return base64.urlsafe_b64encode(raw).decode("ascii").rstrip("=") + + +def decode_cursor(raw: str) -> tuple[str, datetime, uuid.UUID]: + try: + padded = raw + "=" * (-len(raw) % 4) + payload = json.loads(base64.urlsafe_b64decode(padded.encode("ascii"))) + if not isinstance(payload, dict) or payload.get("v") != 1: + raise ValueError + scope = payload["s"] + created_at = datetime.fromisoformat(str(payload["t"]).replace("Z", "+00:00")) + item_id = uuid.UUID(str(payload["i"])) + if not isinstance(scope, str): + raise ValueError + except (ValueError, KeyError, TypeError, UnicodeDecodeError) as exc: + raise invalid("cursor is invalid") from exc + if created_at.tzinfo is None: + created_at = created_at.replace(tzinfo=timezone.utc) + return scope, created_at, item_id + + +@app.get("/health/live") +async def health_live() -> dict[str, str]: + return {"status": "ok"} + + +@app.get("/health/ready") +async def health_ready(request: Request) -> dict[str, str]: + try: + async with request.app.state.pool.connection(timeout=2) as conn: + async with conn.cursor() as cur: + await cur.execute("SELECT 1") + await cur.fetchone() + except Exception as exc: + logger.warning("readiness check failed: %s", type(exc).__name__) + raise ApiError(503, "unavailable", "Database is not available") from exc + return {"status": "ok"} + + +@app.post("/api/v1/users") +async def register_user(request: Request) -> JSONResponse: + data = await read_json_object(request) + reject_unknown_fields(data, {"username", "display_name", "password"}) + username = validate_username(require_string(data, "username")) + display_name = validate_display_name(require_string(data, "display_name")) + password = validate_password(require_string(data, "password")) + + password_hash = hash_password(password) + try: + async with request.app.state.pool.connection() as conn: + async with conn.cursor(row_factory=dict_row) as cur: + await cur.execute( + """ + INSERT INTO users (id, username, display_name, password_hash) + VALUES (%s, %s, %s, %s) + RETURNING id, username, display_name, created_at + """, + (uuid.uuid4(), username, display_name, password_hash), + ) + row = await cur.fetchone() + await conn.commit() + except pg_errors.UniqueViolation as exc: + raise ApiError(409, "conflict", "username is already taken") from exc + return JSONResponse(status_code=201, content=user_json(row)) + + +@app.post("/api/v1/auth/sessions") +async def create_session(request: Request) -> JSONResponse: + header = request.headers.get("authorization", "") + scheme, _, credential = header.partition(" ") + if scheme.lower() != "basic" or not credential.strip(): + raise ApiError(401, "unauthorized", "Basic credentials required", BASIC_CHALLENGE) + + try: + decoded = base64.b64decode(credential.strip(), validate=True).decode("utf-8") + username, password = decoded.split(":", 1) + except (ValueError, UnicodeDecodeError) as exc: + raise ApiError(401, "unauthorized", "Invalid credentials", BASIC_CHALLENGE) from exc + if not username or not password: + raise ApiError(401, "unauthorized", "Invalid credentials", BASIC_CHALLENGE) + + async with request.app.state.pool.connection() as conn: + async with conn.cursor(row_factory=dict_row) as cur: + await cur.execute( + "SELECT id, username, display_name, password_hash, created_at FROM users WHERE username = %s", + (username,), + ) + row = await cur.fetchone() + if row is None or not verify_password(password, row["password_hash"]): + raise ApiError(401, "unauthorized", "Invalid credentials", BASIC_CHALLENGE) + + token = new_session_token() + await cur.execute( + """ + INSERT INTO sessions (token_hash, user_id, expires_at) + VALUES (%s, %s, now() + make_interval(secs => %s)) + RETURNING expires_at + """, + (token_digest(token), row["id"], settings.session_ttl_seconds), + ) + expires_at = (await cur.fetchone())["expires_at"] + await conn.commit() + + return JSONResponse( + status_code=201, + content={ + "token": token, + "token_type": "Bearer", + "expires_at": iso_utc(expires_at), + "user": user_json(row), + }, + ) + + +@app.delete("/api/v1/auth/sessions/current") +async def delete_current_session(request: Request) -> Response: + await authenticate(request) + async with request.app.state.pool.connection() as conn: + async with conn.cursor() as cur: + await cur.execute("DELETE FROM sessions WHERE token_hash = %s", (request.state.token_hash,)) + await conn.commit() + return Response(status_code=204) + + +@app.get("/api/v1/users/me") +async def current_user(request: Request) -> dict[str, Any]: + user = await authenticate(request) + return user_json(user) + + +@app.post("/api/v1/chats") +async def create_chat(request: Request) -> JSONResponse: + user = await authenticate(request) + data = await read_json_object(request) + reject_unknown_fields(data, {"title", "member_ids"}) + title = validate_title(require_string(data, "title")) + member_ids = validate_member_ids(data.get("member_ids")) + user_id = user["id"] + if user_id not in member_ids: + raise invalid("Caller must be a member of the new chat") + + chat_id = uuid.uuid4() + async with request.app.state.pool.connection() as conn: + async with conn.transaction(): + async with conn.cursor(row_factory=dict_row) as cur: + await cur.execute("SELECT id FROM users WHERE id = ANY(%s::uuid[])", (member_ids,)) + known = {row["id"] for row in await cur.fetchall()} + if known != set(member_ids): + raise invalid("member_ids contains unknown users") + await cur.execute( + "INSERT INTO chats (id, title) VALUES (%s, %s) RETURNING id, title, created_at", + (chat_id, title), + ) + chat = await cur.fetchone() + await cur.executemany( + "INSERT INTO chat_members (chat_id, user_id) VALUES (%s, %s)", + [(chat_id, member_id) for member_id in member_ids], + ) + return JSONResponse( + status_code=201, + content=chat_json(chat, sorted(str(member_id) for member_id in member_ids)), + ) + + +@app.get("/api/v1/chats") +async def list_chats(request: Request) -> dict[str, Any]: + user = await authenticate(request) + limit = parse_limit(request) + cursor_raw = request.query_params.get("cursor") + + conditions = ["m.user_id = %s"] + params: list[Any] = [user["id"]] + if cursor_raw: + scope, created_at, item_id = decode_cursor(cursor_raw) + if scope != "chats": + raise invalid("cursor does not belong to this collection") + conditions.append("(c.created_at, c.id) > (%s::timestamptz, %s::uuid)") + params.extend([created_at, item_id]) + params.append(limit + 1) + + async with request.app.state.pool.connection() as conn: + async with conn.cursor(row_factory=dict_row) as cur: + await cur.execute( + """ + SELECT c.id, c.title, c.created_at + FROM chats c + JOIN chat_members m ON m.chat_id = c.id + WHERE """ + + " AND ".join(conditions) + + " ORDER BY c.created_at ASC, c.id ASC LIMIT %s", + params, + ) + rows = await cur.fetchall() + + has_more = len(rows) > limit + rows = rows[:limit] + members = await chat_members(request.app.state.pool, [row["id"] for row in rows]) + next_cursor = ( + encode_cursor("chats", rows[-1]["created_at"], rows[-1]["id"]) if has_more and rows else None + ) + return { + "items": [chat_json(row, members[row["id"]]) for row in rows], + "next_cursor": next_cursor, + } + + +@app.get("/api/v1/chats/{chat_id}") +async def get_chat(chat_id: str, request: Request) -> dict[str, Any]: + user = await authenticate(request) + parsed_chat_id = parse_uuid(chat_id, "chat_id") + await require_member(request.app.state.pool, parsed_chat_id, user["id"]) + + async with request.app.state.pool.connection() as conn: + async with conn.cursor(row_factory=dict_row) as cur: + await cur.execute( + "SELECT id, title, created_at FROM chats WHERE id = %s", + (parsed_chat_id,), + ) + row = await cur.fetchone() + if row is None: + raise ApiError(404, "not_found", "Chat not found") + members = await chat_members(request.app.state.pool, [parsed_chat_id]) + return chat_json(row, members[parsed_chat_id]) + + +def canonical_request_hash(payload: dict[str, Any]) -> str: + canonical = json.dumps(payload, sort_keys=True, separators=(",", ":"), ensure_ascii=False) + return hashlib.sha256(canonical.encode("utf-8")).hexdigest() + + +async def create_message_idempotent( + pool: AsyncConnectionPool, + user_id: uuid.UUID, + chat_id: uuid.UUID, + idempotency_key: str, + text: str, +) -> tuple[int, dict[str, Any]]: + path = f"/api/v1/chats/{chat_id}/messages" + request_hash = canonical_request_hash({"text": text}) + + for _ in range(5): + async with pool.connection() as conn: + async with conn.transaction(): + async with conn.cursor(row_factory=dict_row) as cur: + await cur.execute( + "SELECT 1 FROM chat_members WHERE chat_id = %s AND user_id = %s", + (chat_id, user_id), + ) + if await cur.fetchone() is None: + raise ApiError(404, "not_found", "Chat not found") + + await cur.execute( + """ + INSERT INTO idempotency_keys + (user_id, method, path, key, request_hash, expires_at) + VALUES (%s, 'POST', %s, %s, %s, now() + make_interval(secs => %s)) + ON CONFLICT DO NOTHING + RETURNING user_id + """, + ( + user_id, + path, + idempotency_key, + request_hash, + settings.idempotency_ttl_seconds, + ), + ) + if await cur.fetchone() is not None: + await cur.execute( + """ + INSERT INTO messages (id, chat_id, sender_id, text) + VALUES (%s, %s, %s, %s) + RETURNING id, chat_id, sender_id, text, created_at + """, + (uuid.uuid4(), chat_id, user_id, text), + ) + message = message_json(await cur.fetchone()) + await cur.execute( + """ + UPDATE idempotency_keys + SET status_code = 201, response_body = %s + WHERE user_id = %s AND method = 'POST' AND path = %s AND key = %s + """, + (Jsonb(message), user_id, path, idempotency_key), + ) + return 201, message + + await cur.execute( + """ + SELECT request_hash, status_code, response_body, expires_at, now() AS now_ts + FROM idempotency_keys + WHERE user_id = %s AND method = 'POST' AND path = %s AND key = %s + """, + (user_id, path, idempotency_key), + ) + existing = await cur.fetchone() + if existing is None: + continue + if existing["expires_at"] <= existing["now_ts"]: + await cur.execute( + """ + DELETE FROM idempotency_keys + WHERE user_id = %s AND method = 'POST' AND path = %s AND key = %s + """, + (user_id, path, idempotency_key), + ) + continue + if existing["request_hash"] != request_hash: + raise ApiError( + 409, + "conflict", + "Idempotency-Key was reused with a different request body", + ) + if existing["status_code"] is None or existing["response_body"] is None: + continue + return existing["status_code"], existing["response_body"] + + raise ApiError(503, "unavailable", "Concurrent idempotent request did not complete") + + +@app.post("/api/v1/chats/{chat_id}/messages") +async def create_message(chat_id: str, request: Request) -> JSONResponse: + user = await authenticate(request) + parsed_chat_id = parse_uuid(chat_id, "chat_id") + await require_member(request.app.state.pool, parsed_chat_id, user["id"]) + + idempotency_key = validate_idempotency_key(request) + data = await read_json_object(request) + reject_unknown_fields(data, {"text"}) + text = validate_message_text(require_string(data, "text")) + + status_code, message = await create_message_idempotent( + request.app.state.pool, user["id"], parsed_chat_id, idempotency_key, text + ) + return JSONResponse(status_code=status_code, content=message) + + +@app.get("/api/v1/chats/{chat_id}/messages") +async def list_messages(chat_id: str, request: Request) -> dict[str, Any]: + user = await authenticate(request) + parsed_chat_id = parse_uuid(chat_id, "chat_id") + await require_member(request.app.state.pool, parsed_chat_id, user["id"]) + + limit = parse_limit(request) + cursor_raw = request.query_params.get("cursor") + conditions = ["chat_id = %s"] + params: list[Any] = [parsed_chat_id] + if cursor_raw: + scope, created_at, item_id = decode_cursor(cursor_raw) + if scope != str(parsed_chat_id): + raise invalid("cursor does not belong to this chat") + conditions.append("(created_at, id) > (%s::timestamptz, %s::uuid)") + params.extend([created_at, item_id]) + params.append(limit + 1) + + async with request.app.state.pool.connection() as conn: + async with conn.cursor(row_factory=dict_row) as cur: + await cur.execute( + """ + SELECT id, chat_id, sender_id, text, created_at + FROM messages + WHERE """ + + " AND ".join(conditions) + + " ORDER BY created_at ASC, id ASC LIMIT %s", + params, + ) + rows = await cur.fetchall() + + has_more = len(rows) > limit + rows = rows[:limit] + next_cursor = ( + encode_cursor(str(parsed_chat_id), rows[-1]["created_at"], rows[-1]["id"]) + if has_more and rows + else None + ) + return {"items": [message_json(row) for row in rows], "next_cursor": next_cursor} diff --git a/app/migrate.py b/app/migrate.py new file mode 100644 index 00000000..bcfe6a0d --- /dev/null +++ b/app/migrate.py @@ -0,0 +1,60 @@ +"""One-shot, idempotent schema migration runner. + +The compose stack starts this module as a separate service before any API +replica, so replicas never race on DDL. +""" +from __future__ import annotations + +import asyncio +import sys +from pathlib import Path + +import psycopg + +from .settings import load_settings + +MIGRATION_FILE = Path(__file__).resolve().parents[1] / "migrations" / "001_init.sql" +MIGRATION_VERSION = "001_init" +ADVISORY_LOCK_ID = 727_001_003 + + +def statements(sql: str) -> list[str]: + return [part.strip() for part in sql.split(";") if part.strip()] + + +async def wait_for_database(database_url: str, attempts: int = 60) -> psycopg.AsyncConnection: + last_error: Exception | None = None + for _ in range(attempts): + try: + return await psycopg.AsyncConnection.connect(database_url) + except psycopg.OperationalError as exc: + last_error = exc + await asyncio.sleep(1) + raise SystemExit(f"database is not reachable: {type(last_error).__name__}") + + +async def main() -> None: + settings = load_settings() + sql = MIGRATION_FILE.read_text(encoding="utf-8") + conn = await wait_for_database(settings.database_url) + async with conn: + async with conn.cursor() as cur: + await cur.execute("SELECT pg_advisory_lock(%s)", (ADVISORY_LOCK_ID,)) + try: + for statement in statements(sql): + await cur.execute(statement) + await cur.execute( + "INSERT INTO schema_migrations (version) VALUES (%s) ON CONFLICT DO NOTHING", + (MIGRATION_VERSION,), + ) + finally: + await cur.execute("SELECT pg_advisory_unlock(%s)", (ADVISORY_LOCK_ID,)) + await conn.commit() + print(f"migrations applied: {MIGRATION_VERSION}") + + +if __name__ == "__main__": + try: + asyncio.run(main()) + except KeyboardInterrupt: + sys.exit(130) diff --git a/app/security.py b/app/security.py new file mode 100644 index 00000000..e9af2241 --- /dev/null +++ b/app/security.py @@ -0,0 +1,63 @@ +"""Password hashing (scrypt) and opaque session tokens.""" +from __future__ import annotations + +import base64 +import hashlib +import hmac +import os +import secrets + +_SCRYPT_N = 2**14 +_SCRYPT_R = 8 +_SCRYPT_P = 1 +_SCRYPT_DKLEN = 32 +_SCRYPT_MAXMEM = 64 * 1024 * 1024 + + +def hash_password(password: str) -> str: + salt = os.urandom(16) + digest = hashlib.scrypt( + password.encode("utf-8"), + salt=salt, + n=_SCRYPT_N, + r=_SCRYPT_R, + p=_SCRYPT_P, + dklen=_SCRYPT_DKLEN, + maxmem=_SCRYPT_MAXMEM, + ) + return "scrypt${}${}${}${}${}".format( + _SCRYPT_N, + _SCRYPT_R, + _SCRYPT_P, + base64.b64encode(salt).decode("ascii"), + base64.b64encode(digest).decode("ascii"), + ) + + +def verify_password(password: str, encoded: str) -> bool: + try: + scheme, n_raw, r_raw, p_raw, salt_raw, digest_raw = encoded.split("$") + if scheme != "scrypt": + return False + expected = base64.b64decode(digest_raw, validate=True) + actual = hashlib.scrypt( + password.encode("utf-8"), + salt=base64.b64decode(salt_raw, validate=True), + n=int(n_raw), + r=int(r_raw), + p=int(p_raw), + dklen=len(expected), + maxmem=_SCRYPT_MAXMEM, + ) + except (ValueError, TypeError, MemoryError): + return False + return hmac.compare_digest(actual, expected) + + +def new_session_token() -> str: + # 48 random bytes -> 384 bits of entropy, encoded as an opaque URL-safe string. + return secrets.token_urlsafe(48) + + +def token_digest(token: str) -> str: + return hashlib.sha256(token.encode("utf-8")).hexdigest() diff --git a/app/settings.py b/app/settings.py new file mode 100644 index 00000000..f05e06c9 --- /dev/null +++ b/app/settings.py @@ -0,0 +1,42 @@ +"""Runtime configuration loaded from environment variables.""" +from __future__ import annotations + +import os +from dataclasses import dataclass +from pathlib import Path + + +@dataclass(frozen=True) +class Settings: + database_url: str + session_ttl_seconds: int + idempotency_ttl_seconds: int + instance_id: str + + +def _positive_int(name: str, default: int) -> int: + raw = os.environ.get(name, str(default)) + try: + value = int(raw) + except ValueError as exc: + raise RuntimeError(f"{name} must be an integer") from exc + if value < 1: + raise RuntimeError(f"{name} must be positive") + return value + + +def load_settings() -> Settings: + database_url = os.environ.get("DATABASE_URL", "").strip() + if not database_url: + secret_path = os.environ.get("DATABASE_URL_FILE", "").strip() + if secret_path and Path(secret_path).is_file(): + database_url = Path(secret_path).read_text(encoding="utf-8").strip() + if not database_url: + raise RuntimeError("DATABASE_URL or DATABASE_URL_FILE must be set") + + return Settings( + database_url=database_url, + session_ttl_seconds=_positive_int("SESSION_TTL_SECONDS", 3600), + idempotency_ttl_seconds=_positive_int("IDEMPOTENCY_TTL_SECONDS", 86400), + instance_id=os.environ.get("INSTANCE_ID") or os.environ.get("HOSTNAME") or "api", + ) diff --git a/app/validation.py b/app/validation.py new file mode 100644 index 00000000..16f43a34 --- /dev/null +++ b/app/validation.py @@ -0,0 +1,99 @@ +"""Strict request validation matching contracts/README.md.""" +from __future__ import annotations + +import re +import uuid +from typing import Any, Iterable + +from fastapi import Request + +from .errors import ApiError + +USERNAME_RE = re.compile(r"[a-z0-9_]{3,32}") +IDEMPOTENCY_KEY_RE = re.compile(r"[A-Za-z0-9._:-]{1,128}") + + +def invalid(message: str) -> ApiError: + return ApiError(400, "invalid_request", message) + + +def reject_unknown_fields(data: dict[str, Any], allowed: Iterable[str]) -> None: + unknown = set(data) - set(allowed) + if unknown: + raise invalid("Request contains unknown fields") + + +def require_string(data: dict[str, Any], field: str) -> str: + value = data.get(field) + if not isinstance(value, str): + raise invalid(f"Field '{field}' must be a string") + return value + + +def validate_username(value: str) -> str: + if USERNAME_RE.fullmatch(value) is None: + raise invalid("username must match [a-z0-9_]{3,32}") + return value + + +def validate_display_name(value: str) -> str: + if not 1 <= len(value) <= 100 or not value.strip(): + raise invalid("display_name must contain 1..100 non-blank characters") + return value + + +def validate_password(value: str) -> str: + if not 12 <= len(value) <= 128 or not value.strip(): + raise invalid("password must contain 12..128 non-blank characters") + return value + + +def validate_title(value: str) -> str: + if not 1 <= len(value) <= 100 or not value.strip(): + raise invalid("title must contain 1..100 non-blank characters") + return value + + +def validate_message_text(value: str) -> str: + if not 1 <= len(value) <= 4000 or not value.strip(): + raise invalid("text must contain 1..4000 non-blank characters") + return value + + +def parse_uuid(value: str, field: str = "id") -> uuid.UUID: + try: + return uuid.UUID(value) + except (ValueError, AttributeError, TypeError) as exc: + raise invalid(f"'{field}' must be a UUID") from exc + + +def validate_member_ids(value: Any) -> list[uuid.UUID]: + if not isinstance(value, list) or not 1 <= len(value) <= 100: + raise invalid("member_ids must contain 1..100 UUIDs") + members: list[uuid.UUID] = [] + for item in value: + if not isinstance(item, str): + raise invalid("member_ids must contain UUID strings") + members.append(parse_uuid(item, "member_ids")) + if len(set(members)) != len(members): + raise invalid("member_ids must not contain duplicates") + return members + + +def validate_idempotency_key(request: Request) -> str: + key = request.headers.get("Idempotency-Key") + if key is None or IDEMPOTENCY_KEY_RE.fullmatch(key) is None: + raise invalid("Idempotency-Key is required and must match [A-Za-z0-9._:-]{1,128}") + return key + + +def parse_limit(request: Request) -> int: + raw = request.query_params.get("limit") + if raw is None: + return 50 + if re.fullmatch(r"[0-9]{1,3}", raw) is None: + raise invalid("limit must be an integer between 1 and 100") + value = int(raw) + if not 1 <= value <= 100: + raise invalid("limit must be an integer between 1 and 100") + return value diff --git a/compose.yaml b/compose.yaml new file mode 100644 index 00000000..c8a92a86 --- /dev/null +++ b/compose.yaml @@ -0,0 +1,123 @@ +# Laboratory 3 stand: one public entry point, two interchangeable API +# replicas, one shared PostgreSQL (data + sessions + idempotency keys). +# +# Usage: +# cp .env.example .env +# docker compose --env-file .env up -d --build +# curl -fsS http://localhost:8080/health/ready +name: mtusi-lab3 + +x-api-environment: &api-environment + APP_ENV: ${APP_ENV:-lab} + APP_HOST: 0.0.0.0 + APP_PORT: "8080" + SESSION_TTL_SECONDS: ${SESSION_TTL_SECONDS:-3600} + IDEMPOTENCY_TTL_SECONDS: ${IDEMPOTENCY_TTL_SECONDS:-86400} + DATABASE_URL: postgresql://${POSTGRES_USER:-messenger}:${POSTGRES_PASSWORD:?set POSTGRES_PASSWORD in .env}@postgres:5432/${POSTGRES_DB:-messenger} + +x-api-base: &api-base + build: + context: . + dockerfile: Dockerfile + image: mtusi-lab3-api:1.0.0 + restart: unless-stopped + environment: *api-environment + depends_on: + postgres: + condition: service_healthy + migrate: + condition: service_completed_successfully + healthcheck: + test: + - CMD + - python + - -c + - import urllib.request; urllib.request.urlopen('http://127.0.0.1:8080/health/ready', timeout=2).read() + interval: 5s + timeout: 3s + retries: 5 + start_period: 10s + stop_grace_period: 10s + mem_limit: 256m + cpus: 1.0 + networks: + - appnet + +services: + postgres: + image: postgres:16.4-alpine + restart: unless-stopped + environment: + POSTGRES_DB: ${POSTGRES_DB:-messenger} + POSTGRES_USER: ${POSTGRES_USER:-messenger} + POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?set POSTGRES_PASSWORD in .env} + volumes: + - pgdata:/var/lib/postgresql/data + healthcheck: + test: ["CMD-SHELL", "pg_isready -U $${POSTGRES_USER} -d $${POSTGRES_DB}"] + interval: 5s + timeout: 3s + retries: 10 + start_period: 5s + stop_grace_period: 20s + mem_limit: 512m + cpus: 1.0 + networks: + - appnet + + # Runs once and exits 0 before any API replica starts. Replicas never run DDL. + migrate: + build: + context: . + dockerfile: Dockerfile + image: mtusi-lab3-api:1.0.0 + command: ["python", "-m", "app.migrate"] + restart: "no" + environment: *api-environment + depends_on: + postgres: + condition: service_healthy + networks: + - appnet + + api1: + <<: *api-base + environment: + <<: *api-environment + INSTANCE_ID: api-1 + + api2: + <<: *api-base + environment: + <<: *api-environment + INSTANCE_ID: api-2 + + lb: + image: nginx:1.26.2-alpine + restart: unless-stopped + ports: + - "8080:8080" + volumes: + - ./infra/nginx/nginx.conf:/etc/nginx/nginx.conf:ro + depends_on: + api1: + condition: service_healthy + api2: + condition: service_healthy + healthcheck: + test: ["CMD-SHELL", "wget -q -O /dev/null http://127.0.0.1:8080/health/live || exit 1"] + interval: 5s + timeout: 3s + retries: 5 + start_period: 5s + mem_limit: 128m + cpus: 0.5 + networks: + - appnet + +volumes: + pgdata: + +networks: + appnet: + driver: bridge diff --git a/evidence/check.txt b/evidence/check.txt new file mode 100644 index 00000000..3e59dc98 --- /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/concurrent-idempotency.txt b/evidence/concurrent-idempotency.txt new file mode 100644 index 00000000..536a9b64 --- /dev/null +++ b/evidence/concurrent-idempotency.txt @@ -0,0 +1,2 @@ +{"concurrent_requests": 40, "instances": ["api-1", "api-2"], "stored_copies": 1} +PASS: one Idempotency-Key, concurrent replicas, exactly one message diff --git a/evidence/db-counts.txt b/evidence/db-counts.txt new file mode 100644 index 00000000..1a0ff1c3 --- /dev/null +++ b/evidence/db-counts.txt @@ -0,0 +1,25 @@ + users +------- + 40 +(1 row) + + chats +------- + 13 +(1 row) + + messages +---------- + 4171 +(1 row) + + sessions +---------- + 37 +(1 row) + + idempotency_keys +------------------ + 4171 +(1 row) + diff --git a/evidence/failover-1-ps.txt b/evidence/failover-1-ps.txt new file mode 100644 index 00000000..3fed7b4f --- /dev/null +++ b/evidence/failover-1-ps.txt @@ -0,0 +1,6 @@ +NAME IMAGE COMMAND SERVICE CREATED STATUS PORTS +mtusi-lab3-api1-1 mtusi-lab3-api:1.0.0 "uvicorn app.main:ap…" api1 5 minutes ago Exited (0) 30 seconds ago +mtusi-lab3-api2-1 mtusi-lab3-api:1.0.0 "uvicorn app.main:ap…" api2 5 minutes ago Up 2 minutes (healthy) 8080/tcp +mtusi-lab3-lb-1 nginx:1.26.2-alpine "/docker-entrypoint.…" lb 5 minutes ago Up 2 minutes (healthy) 0.0.0.0:8080->8080/tcp, [::]:8080->8080/tcp +mtusi-lab3-migrate-1 mtusi-lab3-api:1.0.0 "python -m app.migra…" migrate 5 minutes ago Exited (0) 5 minutes ago +mtusi-lab3-postgres-1 postgres:16.4-alpine "docker-entrypoint.s…" postgres 5 minutes ago Up 2 minutes (healthy) 5432/tcp diff --git a/evidence/failover-1.txt b/evidence/failover-1.txt new file mode 100644 index 00000000..d02d2b94 --- /dev/null +++ b/evidence/failover-1.txt @@ -0,0 +1,3 @@ +Executing explicit failover hook; hook output suppressed to avoid leaking secrets. +{"observed_instances_before": 2, "successful_writes": 87, "failed_attempts": 0, "first_recovery_seconds": 0.648} +PASS: failover preserved confirmed data and existing session. Hook scope needs operator evidence. diff --git a/evidence/failover-2-ps.txt b/evidence/failover-2-ps.txt new file mode 100644 index 00000000..df3087d0 --- /dev/null +++ b/evidence/failover-2-ps.txt @@ -0,0 +1,6 @@ +NAME IMAGE COMMAND SERVICE CREATED STATUS PORTS +mtusi-lab3-api1-1 mtusi-lab3-api:1.0.0 "uvicorn app.main:ap…" api1 8 minutes ago Exited (0) 33 seconds ago +mtusi-lab3-api2-1 mtusi-lab3-api:1.0.0 "uvicorn app.main:ap…" api2 8 minutes ago Up 4 minutes (healthy) 8080/tcp +mtusi-lab3-lb-1 nginx:1.26.2-alpine "/docker-entrypoint.…" lb 8 minutes ago Up 52 seconds (healthy) 0.0.0.0:8080->8080/tcp, [::]:8080->8080/tcp +mtusi-lab3-migrate-1 mtusi-lab3-api:1.0.0 "python -m app.migra…" migrate 8 minutes ago Exited (0) 53 seconds ago +mtusi-lab3-postgres-1 postgres:16.4-alpine "docker-entrypoint.s…" postgres 8 minutes ago Up 4 minutes (healthy) 5432/tcp diff --git a/evidence/failover-2.txt b/evidence/failover-2.txt new file mode 100644 index 00000000..7a3fe3f5 --- /dev/null +++ b/evidence/failover-2.txt @@ -0,0 +1,3 @@ +Executing explicit failover hook; hook output suppressed to avoid leaking secrets. +{"observed_instances_before": 2, "successful_writes": 89, "failed_attempts": 0, "first_recovery_seconds": 0.649} +PASS: failover preserved confirmed data and existing session. Hook scope needs operator evidence. diff --git a/evidence/failover-3-ps.txt b/evidence/failover-3-ps.txt new file mode 100644 index 00000000..05722d1d --- /dev/null +++ b/evidence/failover-3-ps.txt @@ -0,0 +1,6 @@ +NAME IMAGE COMMAND SERVICE CREATED STATUS PORTS +mtusi-lab3-api1-1 mtusi-lab3-api:1.0.0 "uvicorn app.main:ap…" api1 9 minutes ago Exited (0) 15 seconds ago +mtusi-lab3-api2-1 mtusi-lab3-api:1.0.0 "uvicorn app.main:ap…" api2 9 minutes ago Up 5 minutes (healthy) 8080/tcp +mtusi-lab3-lb-1 nginx:1.26.2-alpine "/docker-entrypoint.…" lb 9 minutes ago Up 2 minutes (healthy) 0.0.0.0:8080->8080/tcp, [::]:8080->8080/tcp +mtusi-lab3-migrate-1 mtusi-lab3-api:1.0.0 "python -m app.migra…" migrate 9 minutes ago Exited (0) 54 seconds ago +mtusi-lab3-postgres-1 postgres:16.4-alpine "docker-entrypoint.s…" postgres 9 minutes ago Up 5 minutes (healthy) 5432/tcp diff --git a/evidence/failover-3.txt b/evidence/failover-3.txt new file mode 100644 index 00000000..6076993a --- /dev/null +++ b/evidence/failover-3.txt @@ -0,0 +1,3 @@ +Executing explicit failover hook; hook output suppressed to avoid leaking secrets. +{"observed_instances_before": 2, "successful_writes": 85, "failed_attempts": 0, "first_recovery_seconds": 1.434} +PASS: failover preserved confirmed data and existing session. Hook scope needs operator evidence. diff --git a/evidence/failover-4-ps.txt b/evidence/failover-4-ps.txt new file mode 100644 index 00000000..1f0659cc --- /dev/null +++ b/evidence/failover-4-ps.txt @@ -0,0 +1,6 @@ +NAME IMAGE COMMAND SERVICE CREATED STATUS PORTS +mtusi-lab3-api1-1 mtusi-lab3-api:1.0.0 "uvicorn app.main:ap…" api1 11 minutes ago Up About a minute (healthy) 8080/tcp +mtusi-lab3-api2-1 mtusi-lab3-api:1.0.0 "uvicorn app.main:ap…" api2 11 minutes ago Exited (0) 15 seconds ago +mtusi-lab3-lb-1 nginx:1.26.2-alpine "/docker-entrypoint.…" lb 11 minutes ago Up 4 minutes (healthy) 0.0.0.0:8080->8080/tcp, [::]:8080->8080/tcp +mtusi-lab3-migrate-1 mtusi-lab3-api:1.0.0 "python -m app.migra…" migrate 11 minutes ago Exited (0) About a minute ago +mtusi-lab3-postgres-1 postgres:16.4-alpine "docker-entrypoint.s…" postgres 11 minutes ago Up 7 minutes (healthy) 5432/tcp diff --git a/evidence/failover-4.txt b/evidence/failover-4.txt new file mode 100644 index 00000000..ff3d69e3 --- /dev/null +++ b/evidence/failover-4.txt @@ -0,0 +1,3 @@ +Executing explicit failover hook; hook output suppressed to avoid leaking secrets. +{"observed_instances_before": 2, "successful_writes": 88, "failed_attempts": 0, "first_recovery_seconds": 0.65} +PASS: failover preserved confirmed data and existing session. Hook scope needs operator evidence. diff --git a/evidence/failover-final-2-ps.txt b/evidence/failover-final-2-ps.txt new file mode 100644 index 00000000..3668de16 --- /dev/null +++ b/evidence/failover-final-2-ps.txt @@ -0,0 +1,6 @@ +NAME IMAGE COMMAND SERVICE CREATED STATUS PORTS +mtusi-lab3-api1-1 mtusi-lab3-api:1.0.0 "uvicorn app.main:ap…" api1 18 minutes ago Up 5 minutes (healthy) 8080/tcp +mtusi-lab3-api2-1 mtusi-lab3-api:1.0.0 "uvicorn app.main:ap…" api2 18 minutes ago Exited (0) 15 seconds ago +mtusi-lab3-lb-1 nginx:1.26.2-alpine "/docker-entrypoint.…" lb 36 minutes ago Up 5 minutes (healthy) 0.0.0.0:8080->8080/tcp, [::]:8080->8080/tcp +mtusi-lab3-migrate-1 mtusi-lab3-api:1.0.0 "python -m app.migra…" migrate 18 minutes ago Exited (0) 5 minutes ago +mtusi-lab3-postgres-1 postgres:16.4-alpine "docker-entrypoint.s…" postgres 36 minutes ago Up 17 minutes (healthy) 5432/tcp diff --git a/evidence/failover-final-2.txt b/evidence/failover-final-2.txt new file mode 100644 index 00000000..cf76fbaf --- /dev/null +++ b/evidence/failover-final-2.txt @@ -0,0 +1,3 @@ +Executing explicit failover hook; hook output suppressed to avoid leaking secrets. +{"observed_instances_before": 2, "successful_writes": 90, "failed_attempts": 0, "first_recovery_seconds": 0.546} +PASS: failover preserved confirmed data and existing session. Hook scope needs operator evidence. diff --git a/evidence/failover-final-ps.txt b/evidence/failover-final-ps.txt new file mode 100644 index 00000000..153b6d06 --- /dev/null +++ b/evidence/failover-final-ps.txt @@ -0,0 +1,6 @@ +NAME IMAGE COMMAND SERVICE CREATED STATUS PORTS +mtusi-lab3-api1-1 mtusi-lab3-api:1.0.0 "uvicorn app.main:ap…" api1 9 minutes ago Exited (0) 15 seconds ago +mtusi-lab3-api2-1 mtusi-lab3-api:1.0.0 "uvicorn app.main:ap…" api2 9 minutes ago Up 7 minutes (healthy) 8080/tcp +mtusi-lab3-lb-1 nginx:1.26.2-alpine "/docker-entrypoint.…" lb 27 minutes ago Up 56 seconds (healthy) 0.0.0.0:8080->8080/tcp, [::]:8080->8080/tcp +mtusi-lab3-migrate-1 mtusi-lab3-api:1.0.0 "python -m app.migra…" migrate 9 minutes ago Exited (0) 9 minutes ago +mtusi-lab3-postgres-1 postgres:16.4-alpine "docker-entrypoint.s…" postgres 27 minutes ago Up 7 minutes (healthy) 5432/tcp diff --git a/evidence/failover-final.txt b/evidence/failover-final.txt new file mode 100644 index 00000000..a5ea02f5 --- /dev/null +++ b/evidence/failover-final.txt @@ -0,0 +1,3 @@ +Executing explicit failover hook; hook output suppressed to avoid leaking secrets. +{"observed_instances_before": 2, "successful_writes": 85, "failed_attempts": 0, "first_recovery_seconds": 0.558} +PASS: failover preserved confirmed data and existing session. Hook scope needs operator evidence. diff --git a/evidence/final-ps.txt b/evidence/final-ps.txt new file mode 100644 index 00000000..b5d0c28b --- /dev/null +++ b/evidence/final-ps.txt @@ -0,0 +1,5 @@ +NAME IMAGE COMMAND SERVICE CREATED STATUS PORTS +mtusi-lab3-api1-1 mtusi-lab3-api:1.0.0 "uvicorn app.main:ap…" api1 19 minutes ago Up 6 minutes (healthy) 8080/tcp +mtusi-lab3-api2-1 mtusi-lab3-api:1.0.0 "uvicorn app.main:ap…" api2 19 minutes ago Up 11 seconds (healthy) 8080/tcp +mtusi-lab3-lb-1 nginx:1.26.2-alpine "/docker-entrypoint.…" lb 37 minutes ago Up 10 seconds (healthy) 0.0.0.0:8080->8080/tcp, [::]:8080->8080/tcp +mtusi-lab3-postgres-1 postgres:16.4-alpine "docker-entrypoint.s…" postgres 37 minutes ago Up 18 minutes (healthy) 5432/tcp diff --git a/evidence/instances.txt b/evidence/instances.txt new file mode 100644 index 00000000..04709ae2 --- /dev/null +++ b/evidence/instances.txt @@ -0,0 +1,11 @@ +READINESS: {"status":"ok"} +X-Instance-Id=api-2 +X-Instance-Id=api-1 +X-Instance-Id=api-2 +X-Instance-Id=api-1 +X-Instance-Id=api-2 +X-Instance-Id=api-1 +X-Instance-Id=api-2 +X-Instance-Id=api-1 +X-Instance-Id=api-2 +X-Instance-Id=api-1 diff --git a/evidence/load.json b/evidence/load.json new file mode 100644 index 00000000..210881db --- /dev/null +++ b/evidence/load.json @@ -0,0 +1,17 @@ +{ + "lab": 3, + "workload": "closed-loop POST messages; no automatic retries", + "requested_duration_seconds": 15.0, + "elapsed_seconds": 15.032, + "concurrency": 4, + "successful_requests": 3722, + "failed_requests": 0, + "error_ratio": 0.0, + "successful_rps": 247.605, + "successful_latency_ms": { + "p50": 16.0, + "p95": 32.0, + "p99": 46.0 + }, + "note": "Latency percentiles cover successes only. Timeouts/errors are counted separately; closed-loop has coordinated omission and client overhead." +} diff --git a/evidence/load.txt b/evidence/load.txt new file mode 100644 index 00000000..afb93b29 --- /dev/null +++ b/evidence/load.txt @@ -0,0 +1,17 @@ +{ + "lab": 3, + "workload": "closed-loop POST messages; no automatic retries", + "requested_duration_seconds": 15.0, + "elapsed_seconds": 15.032, + "concurrency": 4, + "successful_requests": 3722, + "failed_requests": 0, + "error_ratio": 0.0, + "successful_rps": 247.605, + "successful_latency_ms": { + "p50": 16.0, + "p95": 32.0, + "p99": 46.0 + }, + "note": "Latency percentiles cover successes only. Timeouts/errors are counted separately; closed-loop has coordinated omission and client overhead." +} diff --git a/evidence/persistence-final.txt b/evidence/persistence-final.txt new file mode 100644 index 00000000..044a7fde --- /dev/null +++ b/evidence/persistence-final.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 00000000..044a7fde --- /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/restart-scope.txt b/evidence/restart-scope.txt new file mode 100644 index 00000000..54c41c7f --- /dev/null +++ b/evidence/restart-scope.txt @@ -0,0 +1,12 @@ +BEFORE +------- +/mtusi-lab3-postgres-1 2026-11-07T12:18:04.238732906Z +/mtusi-lab3-api1-1 2026-11-07T12:24:49.374406167Z +/mtusi-lab3-api2-1 2026-11-07T12:26:23.168391355Z +/mtusi-lab3-lb-1 2026-11-07T12:21:51.698457822Z +AFTER +----- +/mtusi-lab3-postgres-1 2026-11-07T12:26:32.284192891Z +/mtusi-lab3-api1-1 2026-11-07T12:26:32.573504264Z +/mtusi-lab3-api2-1 2026-11-07T12:26:32.646884829Z +/mtusi-lab3-lb-1 2026-11-07T12:26:32.434680808Z diff --git a/evidence/session-across-replicas.txt b/evidence/session-across-replicas.txt new file mode 100644 index 00000000..359ac370 --- /dev/null +++ b/evidence/session-across-replicas.txt @@ -0,0 +1,2 @@ +{"requests": 12, "instances": ["api-2", "api-1", "api-2", "api-1", "api-2", "api-1", "api-2", "api-1", "api-2", "api-1", "api-2", "api-1"]} +PASS: one bearer session served by both replicas without re-login diff --git a/evidence/smoke-after-restart.txt b/evidence/smoke-after-restart.txt new file mode 100644 index 00000000..aa347f34 --- /dev/null +++ b/evidence/smoke-after-restart.txt @@ -0,0 +1 @@ +PASS: lab3 public API scenario; infrastructure and grading evidence remain separate. diff --git a/evidence/smoke-final.txt b/evidence/smoke-final.txt new file mode 100644 index 00000000..aa347f34 --- /dev/null +++ b/evidence/smoke-final.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 00000000..aa347f34 --- /dev/null +++ b/evidence/smoke.txt @@ -0,0 +1 @@ +PASS: lab3 public API scenario; infrastructure and grading evidence remain separate. diff --git a/evidence/verify-failover-ps.txt b/evidence/verify-failover-ps.txt new file mode 100644 index 00000000..50d6922a --- /dev/null +++ b/evidence/verify-failover-ps.txt @@ -0,0 +1,6 @@ +NAME IMAGE COMMAND SERVICE CREATED STATUS PORTS +mtusi-lab3-api1-1 mtusi-lab3-api:1.0.0 "uvicorn app.main:ap…" api1 28 minutes ago Up 36 seconds (healthy) 8080/tcp +mtusi-lab3-api2-1 mtusi-lab3-api:1.0.0 "uvicorn app.main:ap…" api2 28 minutes ago Exited (0) 15 seconds ago +mtusi-lab3-lb-1 nginx:1.26.2-alpine "/docker-entrypoint.…" lb 46 minutes ago Up 37 seconds (healthy) 0.0.0.0:8080->8080/tcp, [::]:8080->8080/tcp +mtusi-lab3-migrate-1 mtusi-lab3-api:1.0.0 "python -m app.migra…" migrate 28 minutes ago Exited (0) 9 minutes ago +mtusi-lab3-postgres-1 postgres:16.4-alpine "docker-entrypoint.s…" postgres 46 minutes ago Up 37 seconds (healthy) 5432/tcp diff --git a/evidence/verify-failover.txt b/evidence/verify-failover.txt new file mode 100644 index 00000000..6156f3f1 --- /dev/null +++ b/evidence/verify-failover.txt @@ -0,0 +1,3 @@ +Executing explicit failover hook; hook output suppressed to avoid leaking secrets. +{"observed_instances_before": 2, "successful_writes": 85, "failed_attempts": 0, "first_recovery_seconds": 0.539} +PASS: failover preserved confirmed data and existing session. Hook scope needs operator evidence. diff --git a/evidence/verify-idempotency.txt b/evidence/verify-idempotency.txt new file mode 100644 index 00000000..536a9b64 --- /dev/null +++ b/evidence/verify-idempotency.txt @@ -0,0 +1,2 @@ +{"concurrent_requests": 40, "instances": ["api-1", "api-2"], "stored_copies": 1} +PASS: one Idempotency-Key, concurrent replicas, exactly one message diff --git a/evidence/verify-persistence.txt b/evidence/verify-persistence.txt new file mode 100644 index 00000000..044a7fde --- /dev/null +++ b/evidence/verify-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/verify-sessions.txt b/evidence/verify-sessions.txt new file mode 100644 index 00000000..359ac370 --- /dev/null +++ b/evidence/verify-sessions.txt @@ -0,0 +1,2 @@ +{"requests": 12, "instances": ["api-2", "api-1", "api-2", "api-1", "api-2", "api-1", "api-2", "api-1", "api-2", "api-1", "api-2", "api-1"]} +PASS: one bearer session served by both replicas without re-login diff --git a/evidence/verify-smoke.txt b/evidence/verify-smoke.txt new file mode 100644 index 00000000..aa347f34 --- /dev/null +++ b/evidence/verify-smoke.txt @@ -0,0 +1 @@ +PASS: lab3 public API scenario; infrastructure and grading evidence remain separate. diff --git a/infra/nginx/nginx.conf b/infra/nginx/nginx.conf new file mode 100644 index 00000000..4f3e2023 --- /dev/null +++ b/infra/nginx/nginx.conf @@ -0,0 +1,70 @@ +user nginx; +worker_processes auto; +pid /var/run/nginx.pid; + +error_log /dev/stderr warn; + +events { + worker_connections 1024; +} + +http { + include /etc/nginx/mime.types; + default_type application/octet-stream; + + access_log /dev/stdout; + server_tokens off; + client_max_body_size 1m; + sendfile on; + keepalive_timeout 65; + + # Two interchangeable API replicas. Passive health checks: one failed + # connection marks a backend unavailable for fail_timeout (5 s). + upstream api_backend { + server api1:8080 max_fails=1 fail_timeout=5s; + server api2:8080 max_fails=1 fail_timeout=5s; + keepalive 16; + } + + server { + listen 8080; + server_name _; + + # Message creation is the only POST that is safe to retry at the LB: + # the same Idempotency-Key makes the second attempt return the same + # message. This regex location also covers GET history (idempotent). + location ~ ^/api/v1/chats/[^/]+/messages$ { + proxy_pass http://api_backend; + proxy_http_version 1.1; + proxy_set_header Connection ""; + proxy_set_header Host $host; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_set_header X-Forwarded-Proto $scheme; + + proxy_connect_timeout 1s; + proxy_send_timeout 5s; + proxy_read_timeout 10s; + + proxy_next_upstream error timeout http_502 http_503 http_504 non_idempotent; + proxy_next_upstream_tries 2; + } + + # Registration, login and chat creation are not retried transparently: + # without an idempotency contract a retry could create a second object. + location / { + proxy_pass http://api_backend; + proxy_http_version 1.1; + proxy_set_header Connection ""; + proxy_set_header Host $host; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_set_header X-Forwarded-Proto $scheme; + + proxy_connect_timeout 1s; + proxy_send_timeout 5s; + proxy_read_timeout 10s; + + proxy_next_upstream error timeout http_502 http_503 http_504; + proxy_next_upstream_tries 2; + } + } +} diff --git a/migrations/001_init.sql b/migrations/001_init.sql new file mode 100644 index 00000000..8924b760 --- /dev/null +++ b/migrations/001_init.sql @@ -0,0 +1,61 @@ +CREATE TABLE IF NOT EXISTS schema_migrations ( + version text PRIMARY KEY, + applied_at timestamptz NOT NULL DEFAULT now() +); + +CREATE TABLE IF NOT EXISTS users ( + id uuid PRIMARY KEY, + username text NOT NULL UNIQUE, + display_name text NOT NULL, + password_hash text NOT NULL, + created_at timestamptz NOT NULL DEFAULT now() +); + +CREATE TABLE IF NOT EXISTS sessions ( + token_hash text PRIMARY KEY, + user_id uuid NOT NULL REFERENCES users(id) ON DELETE CASCADE, + created_at timestamptz NOT NULL DEFAULT now(), + expires_at timestamptz NOT NULL +); + +CREATE INDEX IF NOT EXISTS sessions_user_id_idx ON sessions(user_id); +CREATE INDEX IF NOT EXISTS sessions_expires_at_idx ON sessions(expires_at); + +CREATE TABLE IF NOT EXISTS chats ( + id uuid PRIMARY KEY, + title text NOT NULL, + created_at timestamptz NOT NULL DEFAULT now() +); + +CREATE TABLE IF NOT EXISTS chat_members ( + chat_id uuid NOT NULL REFERENCES chats(id) ON DELETE CASCADE, + user_id uuid NOT NULL REFERENCES users(id) ON DELETE CASCADE, + PRIMARY KEY (chat_id, user_id) +); + +CREATE INDEX IF NOT EXISTS chat_members_user_id_idx ON chat_members(user_id); + +CREATE TABLE IF NOT EXISTS messages ( + id uuid PRIMARY KEY, + chat_id uuid NOT NULL REFERENCES chats(id) ON DELETE CASCADE, + sender_id uuid NOT NULL REFERENCES users(id), + text text NOT NULL, + created_at timestamptz NOT NULL DEFAULT now() +); + +CREATE INDEX IF NOT EXISTS messages_chat_order_idx ON messages(chat_id, created_at, id); + +CREATE TABLE IF NOT EXISTS idempotency_keys ( + user_id uuid NOT NULL REFERENCES users(id) ON DELETE CASCADE, + method text NOT NULL, + path text NOT NULL, + key text NOT NULL, + request_hash text NOT NULL, + status_code integer, + response_body jsonb, + created_at timestamptz NOT NULL DEFAULT now(), + expires_at timestamptz NOT NULL, + PRIMARY KEY (user_id, method, path, key) +); + +CREATE INDEX IF NOT EXISTS idempotency_keys_expires_at_idx ON idempotency_keys(expires_at); diff --git a/requirements.txt b/requirements.txt new file mode 100644 index 00000000..ac8842c4 --- /dev/null +++ b/requirements.txt @@ -0,0 +1,4 @@ +fastapi==0.115.0 +uvicorn==0.30.6 +psycopg[binary]==3.2.3 +psycopg-pool==3.3.3 diff --git a/scripts/restart.sh b/scripts/restart.sh new file mode 100755 index 00000000..2fa1ad1f --- /dev/null +++ b/scripts/restart.sh @@ -0,0 +1,9 @@ +#!/bin/sh +# Restart the API replicas, the load balancer and the shared PostgreSQL. +# Volumes are preserved: no `down -v`, no re-seed, no data removal. +set -eu + +ROOT=$(CDPATH= cd -- "$(dirname -- "$0")/.." && pwd) +cd "$ROOT" + +docker compose --env-file .env -f compose.yaml restart postgres api1 api2 lb diff --git a/scripts/stop-one.sh b/scripts/stop-one.sh new file mode 100755 index 00000000..e9485293 --- /dev/null +++ b/scripts/stop-one.sh @@ -0,0 +1,23 @@ +#!/bin/sh +# Stop exactly one API replica identified by the X-Instance-Id alias supplied +# by the failover test. The replica is intentionally left stopped; restore it +# explicitly with: docker compose start api1 (or api2). +set -eu + +: "${TARGET_INSTANCE_ID:?test provides target API instance alias}" + +case "$TARGET_INSTANCE_ID" in + api-1) service=api1 ;; + api-2) service=api2 ;; + *) + printf 'unknown API instance alias: %s\n' "$TARGET_INSTANCE_ID" >&2 + exit 2 + ;; +esac + +ROOT=$(CDPATH= cd -- "$(dirname -- "$0")/.." && pwd) +cd "$ROOT" + +# -t 2 keeps the hook well inside the test's 10 second budget. `stop` keeps the +# container (and volumes) in place and the container is not restarted by policy. +exec docker compose --env-file .env -f compose.yaml stop --timeout 2 "$service" diff --git a/student-tests/concurrent_idempotency.py b/student-tests/concurrent_idempotency.py new file mode 100644 index 00000000..ace66f93 --- /dev/null +++ b/student-tests/concurrent_idempotency.py @@ -0,0 +1,80 @@ +#!/usr/bin/env python3 +"""Concurrent replay of one Idempotency-Key through the load balancer. + +The public smoke checks sequential replay. This test fires many simultaneous +POSTs with the same key/body so requests land on both API replicas, then +verifies that exactly one message was stored and every response is identical. +""" +import json +import sys +import threading +import uuid +from concurrent.futures import ThreadPoolExecutor +from pathlib import Path + +ROOT = Path(__file__).resolve().parents[1] +sys.path.insert(0, str(ROOT / "tests")) + +from client import Client, Failure, LAB, check, run # noqa: E402 + + +def main(): + check(LAB >= 3, "concurrent idempotency requires lab3") + base = sys.argv[1] if len(sys.argv) > 1 else "http://localhost:8080" + client = Client(base) + alice, bob, eve, chat = client.bootstrap() + + key = "concurrent-" + uuid.uuid4().hex + text = "Одновременный повтор " + uuid.uuid4().hex + requests = 40 + barrier = threading.Barrier(requests) + + def worker(_): + local = Client(base) + barrier.wait() + try: + response = local.message(alice, chat, text, key=key) + return ("ok", response["json"], response["headers"]["X-Instance-Id"]) + except Failure as exc: + return ("fail", str(exc), None) + + with ThreadPoolExecutor(max_workers=requests) as pool: + results = list(pool.map(worker, range(requests))) + + failures = [result for result in results if result[0] == "fail"] + if failures: + raise Failure("concurrent replay failed: " + failures[0][1]) + bodies = {json.dumps(result[1], sort_keys=True) for result in results} + check(len(bodies) == 1, "concurrent replays returned different messages") + instances = {result[2] for result in results} + check(len(instances) >= 2, "requests did not reach both replicas: " + repr(instances)) + + history_path = "/api/v1/chats/" + chat["id"] + "/messages?limit=100" + page = client.call("GET", history_path, actor=bob, schema="MessagePage")["json"] + copies = sum(1 for message in page["items"] if message["text"] == text) + check(copies == 1, "expected exactly one stored message, got %d" % copies) + + client.call( + "POST", + "/api/v1/chats/" + chat["id"] + "/messages", + 409, + actor=alice, + body={"text": text + " (different body)"}, + headers={"Idempotency-Key": key}, + ) + + print( + json.dumps( + { + "concurrent_requests": requests, + "instances": sorted(instances), + "stored_copies": copies, + }, + ensure_ascii=False, + ) + ) + print("PASS: one Idempotency-Key, concurrent replicas, exactly one message") + + +if __name__ == "__main__": + run(main) diff --git a/student-tests/session_across_replicas.py b/student-tests/session_across_replicas.py new file mode 100644 index 00000000..b1a33d08 --- /dev/null +++ b/student-tests/session_across_replicas.py @@ -0,0 +1,40 @@ +#!/usr/bin/env python3 +"""One session, many requests, both replicas: proves shared session state.""" +import json +import sys +import time +from pathlib import Path + +ROOT = Path(__file__).resolve().parents[1] +sys.path.insert(0, str(ROOT / "tests")) + +from client import Client, LAB, check, run # noqa: E402 + + +def main(): + check(LAB >= 3, "shared sessions across replicas require lab3") + base = sys.argv[1] if len(sys.argv) > 1 else "http://localhost:8080" + client = Client(base) + alice = client.user("replica") + + # A just-restored replica can stay out of the nginx pool for up to + # fail_timeout=5s. Wait for normal two-replica operation before measuring. + deadline = time.monotonic() + 10 + warm = set() + while time.monotonic() < deadline and len(warm) < 2: + warm.add(client.call("GET", "/health/live", schema="Health")["headers"]["X-Instance-Id"]) + time.sleep(0.1) + check(len(warm) >= 2, "load balancer currently has only one healthy replica") + + instances = [] + for _ in range(12): + response = client.call("GET", "/api/v1/users/me", actor=alice, schema="User") + instances.append(response["headers"]["X-Instance-Id"]) + + check(len(set(instances)) >= 2, "one session was served by a single replica only") + print(json.dumps({"requests": len(instances), "instances": instances}, ensure_ascii=False)) + print("PASS: one bearer session served by both replicas without re-login") + + +if __name__ == "__main__": + run(main)