diff --git a/.env.example b/.env.example index 714c8076..b5270b86 100644 --- a/.env.example +++ b/.env.example @@ -3,9 +3,17 @@ APP_HOST=0.0.0.0 APP_PORT=8080 APP_ENV=lab +LOG_LEVEL=info +SHUTDOWN_GRACE_SECONDS=10 SESSION_TTL_SECONDS=3600 +CACHE_TTL_SECONDS=60 # 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 +SESSION_STORE=redis CACHE_URL_FILE=/run/secrets/cache_url + +# Compose interpolates these. Synthetic local values only; replace after copy. +POSTGRES_PASSWORD=lab2-dev-only-change-me +DATABASE_URL=postgresql://messenger:lab2-dev-only-change-me@postgres:5432/messenger +REDIS_URL=redis://redis:6379/0 diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 8ceefa10..c6de4713 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -1,18 +1,18 @@ ## Лабораторная 2 -Автор / группа: TODO -Целевая оценка (3/4/5): TODO -Трек 5, если заявлен: TODO +Автор / группа: Bulatsev / БПИ2301 +Целевая оценка (3/4/5): 5 +Трек 5, если заявлен: 1 — согласованность кэша -Что реализовано и что перенесено: TODO -Команды запуска из чистого clone: TODO -Результаты проверок и ссылка на REPORT.md: TODO -Ограничения / известные ошибки: TODO -Источники и использование ИИ: TODO +Что реализовано и что перенесено: Starlette API из lab1; PostgreSQL как источник истины; Argon2id; Basic→opaque Bearer; Redis AOF для сессий и кэш истории с singleflight/версией. +Команды запуска из чистого clone: `cp .env.example .env && docker compose --env-file .env up -d --build` (см. REPORT.md). +Результаты проверок и ссылка на REPORT.md: smoke PASS; persistence PASS; 15 student tests PASS; infra 2 PASS; expiry PASS; EXPLAIN на 10k сообщений; stampede 24→1 SQL. Подробности в REPORT.md. +Ограничения / известные ошибки: один host; singleflight в рамках одного процесса; учебный Argon2 memory_cost. +Источники и использование ИИ: контракт курса, документация PostgreSQL/Redis; ИИ — помощь в переносе store и черновике отчёта. -- [ ] Весь обязательный минимум текущей и предыдущих работ сохранён с объявленными переходами. -- [ ] Контракт и публичные тесты не ослаблены. -- [ ] make check и make test выполнены; приложен реальный вывод. -- [ ] Сценарии отказов/безопасности своего уровня воспроизведены. -- [ ] Все секреты и приватные ключи находятся вне Git; отчёт не содержит tokens. -- [ ] README задания сохранён, REPORT.md содержит инструкцию именно моего решения. +- [x] Весь обязательный минимум текущей и предыдущих работ сохранён с объявленными переходами. +- [x] Контракт и публичные тесты не ослаблены. +- [x] make check и make test выполнены; приложен реальный вывод. +- [x] Сценарии отказов/безопасности своего уровня воспроизведены. +- [x] Все секреты и приватные ключи находятся вне Git; отчёт не содержит tokens. +- [x] README задания сохранён, REPORT.md содержит инструкцию именно моего решения. diff --git a/.github/workflows/contracts.yml b/.github/workflows/contracts.yml index 11cf289f..5236da6e 100644 --- a/.github/workflows/contracts.yml +++ b/.github/workflows/contracts.yml @@ -12,5 +12,28 @@ jobs: 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. + application: + 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-test.txt + - run: cp .env.example .env + - run: docker compose --env-file .env up -d --build + - name: Wait until API is ready + run: | + for i in $(seq 1 60); do + if curl -fsS http://127.0.0.1:8080/health/ready; then exit 0; fi + sleep 2 + done + docker compose --env-file .env logs + exit 1 + - run: make test PYTHON=python + - run: chmod +x scripts/restart.sh + - run: make test-persistence ACTION_SCRIPT=scripts/restart.sh PYTHON=python + - run: python -m pytest student_tests -q -m "not infra and not expiry" + - run: RUN_INFRA=1 python -m pytest student_tests/test_infra.py -q -m infra + - run: python scripts/run_expiry.py + - run: docker compose --env-file .env exec -T api python -m app.tools.explain diff --git a/Dockerfile b/Dockerfile new file mode 100644 index 00000000..65e21fb0 --- /dev/null +++ b/Dockerfile @@ -0,0 +1,29 @@ +FROM python:3.12.8-slim-bookworm AS runtime + +WORKDIR /app + +RUN groupadd --system app && useradd --system --gid app --home /app --shell /usr/sbin/nologin app \ + && apt-get update \ + && apt-get install -y --no-install-recommends curl \ + && rm -rf /var/lib/apt/lists/* + +COPY requirements.txt . +RUN pip install --no-cache-dir -r requirements.txt + +COPY app ./app +COPY migrations ./migrations +COPY contracts/openapi.json ./contracts/openapi.json + +USER app + +ENV APP_HOST=0.0.0.0 \ + APP_PORT=8080 \ + APP_ENV=lab \ + PYTHONUNBUFFERED=1 + +EXPOSE 8080 + +HEALTHCHECK --interval=5s --timeout=3s --start-period=15s --retries=12 \ + CMD python -c "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8080/health/ready', timeout=2)" + +CMD ["python", "-m", "app.main"] diff --git a/Makefile b/Makefile index 9ecb223e..3f2a813e 100644 --- a/Makefile +++ b/Makefile @@ -4,7 +4,7 @@ CA_FILE ?= ACTION_SCRIPT ?= TLS_ARGS = $(if $(CA_FILE),--ca-file "$(CA_FILE)",) -.PHONY: help check validate test load test-persistence +.PHONY: help check validate test load test-persistence test-student test-infra test-expiry explain help: @echo "check: offline structure; validate: full OpenAPI (requirements-dev.txt); test: running API; load: synthetic writes" @@ -16,11 +16,23 @@ validate: $(PYTHON) scripts/validate_openapi.py test: - $(PYTHON) tests/smoke.py --base-url "$(BASE_URL)" $(TLS_ARGS) + $(PYTHON) -X utf8 tests/smoke.py --base-url "$(BASE_URL)" $(TLS_ARGS) load: - $(PYTHON) tests/load.py --base-url "$(BASE_URL)" $(TLS_ARGS) + $(PYTHON) -X utf8 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) + $(PYTHON) -X utf8 tests/resilience.py --mode persistence --action-script "$(ACTION_SCRIPT)" --base-url "$(BASE_URL)" $(TLS_ARGS) + +test-student: + $(PYTHON) -m pytest student_tests -q -m "not infra and not expiry" + +test-infra: + RUN_INFRA=1 $(PYTHON) -m pytest student_tests/test_infra.py -q -m infra + +test-expiry: + $(PYTHON) scripts/run_expiry.py + +explain: + docker compose --env-file .env exec -T api python -m app.tools.explain diff --git a/REPORT.md b/REPORT.md index e42f2b05..3e9e6107 100644 --- a/REPORT.md +++ b/REPORT.md @@ -1,37 +1,128 @@ # Отчёт — лабораторная 2 -- Автор, группа: TODO -- Целевая оценка; выбранный трек 5, если нужен: TODO -- Commit/PR: TODO после публикации -- Использованные источники, библиотеки и помощь ИИ: TODO +- Автор, группа: **Bulatsev**, **БПИ2301** (ветка `solution/bpi2301-Bulatsev`) +- Целевая оценка; выбранный трек 5: **5**, трек **1 — согласованность кэша** +- Commit/PR: после push ветки `solution/bpi2301-Bulatsev` +- Источники: контракт lab2, PostgreSQL EXPLAIN, Redis AOF; код API перенесён из lab1 (Starlette/Uvicorn, валидация, cursor, graceful shutdown). Помощь ИИ — структура store/кэша и формулировки отчёта. ## Запуск из чистого clone -TODO: версии runtime/образов, prerequisites, команды создания локальных secrets/.env, build, миграций, запуска, ожидания готовности, тестов и остановки. Указать необходимые действия оператора. Не вставлять секреты. Отдельно указать безопасную остановку и команду намеренного удаления учебных данных. +**Prerequisites:** Docker 24+, Docker Compose v2, Python 3.9+ (локальные проверки), Git. + +**Образы:** `python:3.12.8-slim-bookworm` (API), `postgres:16.6-alpine`, `redis:7.4.2-alpine`. Лимиты compose: API 1 CPU / 512 MiB, PostgreSQL 1 CPU / 512 MiB, Redis 0.5 CPU / 128 MiB. + +```sh +git clone +cd mtusi2026lab2 +git checkout solution/bpi2301-Bulatsev +cp .env.example .env +# при необходимости замените POSTGRES_PASSWORD в .env +docker compose --env-file .env config --quiet +docker compose --env-file .env up -d --build +``` + +Готовность: `GET http://127.0.0.1:8080/health/ready` → `200 {"status":"ok"}`. Документация: `/docs`. + +**Проверки (другой терминал, Windows: `PYTHON=python` и `-X utf8` уже в Makefile):** + +```sh +make check +make test BASE_URL=http://127.0.0.1:8080 PYTHON=python +python -m pip install -r requirements-test.txt +make test-student PYTHON=python +make test-persistence ACTION_SCRIPT=scripts/restart.sh PYTHON=python +# Windows без Git Bash: +python -X utf8 tests/resilience.py --mode persistence --action-script scripts/restart.bat --base-url http://127.0.0.1:8080 +RUN_INFRA=1 python -m pytest student_tests/test_infra.py -q +python scripts/run_expiry.py +docker compose --env-file .env exec -T api python -m app.tools.explain +``` + +Миграции применяются при старте API (`schema_migrations`). Повторный старт не дублирует таблицы/данные. + +**Остановка:** `docker compose --env-file .env stop` — volumes сохраняются. +**Удаление учебных данных:** `docker compose --env-file .env down -v` (уничтожит `pg_data` и `redis_data`). + +Секреты только в локальном `.env` (gitignored). В Git нет tokens и паролей стенда, кроме синтетического примера в `.env.example`. ## Архитектура и решения -TODO: схема процессов/хранилищ, источник истины, транзакционные границы, ограничения. Что перенесено из lab1, что изменено в этой работе. Соответствие переменных из .env.example реальной конфигурации. +``` +Клиент ──HTTP JSON──► Starlette (lab1) ──asyncpg pool──► PostgreSQL 16 + │ + └── redis.asyncio ──► Redis 7 (AOF + RDB) + сессии sess: TTL + кэш hist:::: +``` + +**Перенесено из lab1:** пакет `app/` на Starlette, middleware `X-Request-Id`, валидация JSON/Unicode, opaque cursor, Dockerfile non-root `app`, SIGTERM/`shutting_down` → 503, healthcheck. + +**Изменено в lab2:** + +| Lab1 | Lab2 | +| --- | --- | +| `InMemoryStore` | PostgreSQL: `users`, `chats`, `chat_members`, `messages` | +| `X-User-Id` | `Authorization: Bearer` (opaque token ≥256 бит) | +| регистрация без пароля | `password` + Argon2id | +| нет сессий | `POST /api/v1/auth/sessions` (Basic), `DELETE .../current` | +| состояние умирает с процессом | named volumes + Redis AOF | + +**Источник истины:** PostgreSQL. Сессии — Redis с AOF (`appendonly yes`, `appendfsync everysec`) и `save 60 1`; TTL ключа = `SESSION_TTL_SECONDS` (по умолчанию 3600, в smoke ≥300). Рестарт Redis не продлевает TTL. Кэш истории — производный: версия `histver:` увеличивается после INSERT сообщения. + +**Транзакции:** создание чата — один `transaction`: проверка участников + INSERT chat + INSERT members. Неизвестный UUID → 400, чат не появляется в списке. + +**Пул и таймауты:** `asyncpg` min 1 / max 10, `command_timeout=5`, `timeout=5`; Redis socket timeout 2 с. Запросы параметризованные (`$1…`). + +**Соответствие `.env.example`:** `DATABASE_URL` / `DATABASE_URL_FILE` → DSN Postgres; `REDIS_URL` / `CACHE_URL_FILE` по смыслу — Redis; `SESSION_STORE=redis`; `SESSION_TTL_SECONDS` читается приложением. + +**Готовность:** `/health/live` — только процесс; `/health/ready` — ping Postgres **и** Redis. Недоступность Redis на Bearer → **503**, не анонимный доступ. ## Доказательства критериев | Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства | | --- | --- | --- | --- | -| Публичный smoke | make test | TODO | TODO | -| Остальные пункты уровня 3 | TODO | TODO | TODO | -| Все пункты уровня 4, если заявлен | TODO | TODO | TODO | -| Выбранный трек 5, если заявлен | TODO | TODO | TODO | +| Публичный smoke | `python -X utf8 tests/smoke.py --base-url http://127.0.0.1:8080` | `PASS: lab2 public API scenario` | stdout | +| Данные и сессия после рестарта | `python -X utf8 tests/resilience.py --mode persistence --action-script scripts/restart.bat --base-url http://127.0.0.1:8080` | `PASS: persistence preserved confirmed data and existing session` | `evidence/compose_before_restart.txt`, `evidence/compose_after_restart.txt` (hook: `docker compose restart postgres redis api`, volumes не удалялись) | +| Миграции с нуля / повторно | повторный `up` API | `schema_migrations` пропускает `001_init.sql` | `migrations/001_init.sql`, логи старта | +| Basic только на login; Bearer; X-User-Id игнорируется | smoke + `pytest student_tests/test_api.py` | 401 на Basic/me и на `X-User-Id`; logout 204 затем 401 | `student_tests/test_api.py` | +| Password KDF | регистрация | Argon2id (`argon2-cffi`) | `app/passwords.py` | +| Гонка username | `test_register_race` | ровно один 201 и пятнадцать 409 | `student_tests/test_grade4.py` | +| Rollback чата | `test_chat_rollback` | 400, лишний чат не виден | `student_tests/test_grade4.py` | +| Индекс истории ≥10k | `docker compose exec api python -m app.tools.explain` | Index Scan, 0.061 ms vs Seq Scan 2.081 ms на 10000 сообщений | `evidence/explain-history.txt` | +| Expiry при TTL=2 | `python scripts/run_expiry.py` | 1 passed (me → 401 после TTL+1.5 с) | stdout | +| Redis/БД down | `RUN_INFRA=1 pytest student_tests/test_infra.py` | live 200, ready 503; me при Redis down 503 | 2 passed | +| Трек 1 stampede | `test_stampede_singleflight_reduces_sql` | SQL history: **24 без** singleflight, **1 с** (24 waiter, delay 250 ms) | `evidence/stampede.json` | +| Трек 1 read-after-write | `test_read_after_write` | новое сообщение сразу в GET | pytest | +| Трек 1 stale без invalidate | `test_stale_without_invalidation_then_fixed` | GET без новой строки, после включения invalidate — строка есть | pytest | +| Трек 1 рестарт кэша | `test_redis_restart_keeps_session_and_history` | тот же Bearer и то же сообщение после `compose restart redis` | pytest infra | +| Нагрузка (закрытый цикл) | `python -X utf8 tests/load.py --duration 15 --concurrency 4 --output evidence/load.json` | 337.3 successful RPS, ошибки 0, p50 9.7 / p95 27.4 / p99 33.3 ms | `evidence/load.json` | +| `make check` | `python scripts/check_contract.py` | `PASS: offline skeleton structure` | stdout | -TODO: добавить отдельную строку для каждого заявленного критерия. PASS без команды и наблюдения не является доказательством. Проверка инфраструктурного hook требует подтверждения, какие реальные процессы/хранилища перезапущены. +Собственные тесты (без infra/expiry): **15 passed** за 4.37 с. ## Эксперименты и отказы -TODO: гипотеза, hardware/лимиты, версии, объём данных, профиль нагрузки, concurrency/arrival rate, длительность/прогрев, повторы, успешные RPS, ошибки, p50/p95/p99, CPU/RAM. Сохранить raw summary без tokens и объяснить ограничения измерения. +**Гипотеза трека 1.** Параллельные GET одной страницы истории после cache miss без координации порождают N одинаковых SQL; in-process singleflight оставляет один load. Инвалидация версией ключа обеспечивает read-after-write; без неё кэш отдаёт stale. После рестарта Redis сессия живёт за счёт AOF, страницы кэша восстанавливаются из PostgreSQL. + +**Методика.** 24 потока, `threading.Barrier`, искусственная задержка load 250 ms (только `APP_ENV=lab` через `POST /api/v1/_lab/flags`), счётчик `metrics:sql:messages_select`. Сравнение `cfg:singleflight=0/1`. Отдельно: выключение `cfg:invalidate`, POST, GET; затем включение и повтор. Затем `docker compose restart redis`. + +**Результаты.** 24 SQL → 1 SQL. Stale подтверждён при выключенной инвалидации. После рестарта Redis прежний token читает `/users/me` и историю. + +**Hardware:** Windows 10, Docker Desktop, один host. Измерения — учебные, closed-loop `tests/load.py` страдает coordinated omission. | Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных | | --- | --- | --- | --- | -| TODO | TODO | TODO | TODO | +| `compose restart postgres redis api` | тот же token, то же сообщение | persistence PASS | секунды, volumes целы | +| `compose stop redis` | ready 503, Bearer не становится анонимом | 503 на `/users/me` | после `start redis` — ready | +| `compose stop postgres` | ready 503 | 503 | после `start` — ready | +| `compose restart redis` | сессия из AOF, история из PG | token и message на месте | готовность API ≤ десятка секунд | +| TTL=2 с | 401 после истечения | pytest expiry PASS | нет потери бизнес-данных | ## Ограничения и следующие шаги -TODO: какие отказы выдерживаются и какие нет; что не реализовано; где учебное упрощение; какое улучшение подтверждено, а какое пока гипотеза. +- Один Docker-host: отказ машины теряет всё. Redis AOF `everysec` допускает потерю <1 с сессий при crash. +- Singleflight — внутри одного процесса API (lab2: одна реплика). С lab3 нужен распределённый lock. +- Задержка 250 ms в эксперименте stampede нужна, чтобы 24 HTTP-клиента успели попасть в окно miss; без неё на localhost первый GET заполняет кэш раньше остальных. +- Argon2id с `memory_cost=8192` — учебный компромисс для гонки регистрации, не production-параметры lab7. +- Не выдерживается: потеря volume, повреждение AOF, сеть между API и Postgres. +- Улучшение stampede (24→1 SQL) **подтверждено** измерением. Линейная масштабируемость кэша на нескольких репликах — пока гипотеза. diff --git a/app/__init__.py b/app/__init__.py new file mode 100644 index 00000000..eeb0eb82 --- /dev/null +++ b/app/__init__.py @@ -0,0 +1 @@ +"""Messenger API (lab 2): PostgreSQL source of truth, Redis sessions/cache.""" diff --git a/app/cache.py b/app/cache.py new file mode 100644 index 00000000..ed9261df --- /dev/null +++ b/app/cache.py @@ -0,0 +1,151 @@ +import asyncio +import json +from collections.abc import Awaitable, Callable +from typing import TypeVar + +from app import config, rediscli +from app.errors import AppError + +T = TypeVar("T") +CFG_SINGLEFLIGHT = "cfg:singleflight" +CFG_INVALIDATE = "cfg:invalidate" +CFG_DELAY_MS = "cfg:delay_ms" +SQL_HISTORY = "metrics:sql:messages_select" + + +class SingleFlight: + def __init__(self) -> None: + self._lock = asyncio.Lock() + self._inflight: dict[str, asyncio.Task] = {} + + async def do(self, key: str, factory: Callable[[], Awaitable[T]]) -> T: + async with self._lock: + task = self._inflight.get(key) + if task is None: + task = asyncio.create_task(factory()) + self._inflight[key] = task + owner = True + else: + owner = False + try: + return await asyncio.shield(task) + finally: + if owner: + async with self._lock: + self._inflight.pop(key, None) + + +_sf = SingleFlight() + + +async def _flag(name: str, default: bool = True) -> bool: + if not config.lab_mode(): + return default + try: + raw = await rediscli.require().get(name) + except Exception: + return default + if raw is None: + return default + return raw not in {"0", "false", "off"} + + +async def singleflight_enabled() -> bool: + return await _flag(CFG_SINGLEFLIGHT, True) + + +async def invalidate_enabled() -> bool: + return await _flag(CFG_INVALIDATE, True) + + +async def incr_history_sql() -> None: + try: + await rediscli.require().incr(SQL_HISTORY) + except Exception: + pass + + +async def history_sql_count() -> int: + try: + return int(await rediscli.require().get(SQL_HISTORY) or 0) + except Exception: + return 0 + + +async def reset_history_sql_count() -> None: + try: + await rediscli.require().set(SQL_HISTORY, 0) + except Exception: + pass + + +async def load_delay_seconds() -> float: + if not config.lab_mode(): + return 0.0 + try: + raw = await rediscli.require().get(CFG_DELAY_MS) + except Exception: + return 0.0 + try: + return max(0.0, float(raw or 0) / 1000.0) + except (TypeError, ValueError): + return 0.0 + + +async def set_flags( + *, + singleflight: bool | None = None, + invalidate: bool | None = None, + delay_ms: int | None = None, +) -> dict: + r = rediscli.require() + if singleflight is not None: + await r.set(CFG_SINGLEFLIGHT, "1" if singleflight else "0") + if invalidate is not None: + await r.set(CFG_INVALIDATE, "1" if invalidate else "0") + if delay_ms is not None: + await r.set(CFG_DELAY_MS, str(int(delay_ms))) + return { + "singleflight": await singleflight_enabled(), + "invalidate": await invalidate_enabled(), + "history_sql": await history_sql_count(), + "delay_ms": int((await load_delay_seconds()) * 1000), + } + + +async def get_history_page(chat_id: str, cursor: str, limit: int, loader: Callable[[], Awaitable[dict]]) -> dict: + r = rediscli.require() + try: + version = await r.get("histver:" + chat_id) or "0" + key = f"hist:{chat_id}:{version}:{cursor}:{limit}" + cached = await r.get(key) + if cached: + return json.loads(cached) + + async def load_and_store() -> dict: + delay = await load_delay_seconds() + if delay: + await asyncio.sleep(delay) + page = await loader() + try: + await r.set(key, json.dumps(page, ensure_ascii=False), ex=config.CACHE_TTL_SECONDS) + except Exception: + pass + return page + + if await singleflight_enabled(): + return await _sf.do(key, load_and_store) + return await load_and_store() + except AppError: + raise + except Exception: + return await loader() + + +async def invalidate_history(chat_id: str) -> None: + if not await invalidate_enabled(): + return + try: + await rediscli.require().incr("histver:" + chat_id) + except Exception: + pass diff --git a/app/config.py b/app/config.py new file mode 100644 index 00000000..7103d8b5 --- /dev/null +++ b/app/config.py @@ -0,0 +1,35 @@ +import os +from pathlib import Path + + +def _env(name: str, default: str = "") -> str: + value = os.environ.get(name) + return default if value is None or value == "" else value + + +def _file_or_env(name: str, default: str = "") -> str: + path = os.environ.get(name + "_FILE") + if path: + return Path(path).read_text(encoding="utf-8").strip() + return _env(name, default) + + +HOST = _env("APP_HOST", "0.0.0.0") +PORT = int(_env("APP_PORT", "8080")) +ENV = _env("APP_ENV", "lab") +LOG_LEVEL = _env("LOG_LEVEL", "info").lower() +SHUTDOWN_GRACE_SECONDS = float(_env("SHUTDOWN_GRACE_SECONDS", "10")) +SESSION_TTL_SECONDS = int(_env("SESSION_TTL_SECONDS", "3600")) +CACHE_TTL_SECONDS = int(_env("CACHE_TTL_SECONDS", "60")) +DATABASE_URL = _file_or_env("DATABASE_URL") +REDIS_URL = _file_or_env("REDIS_URL", "redis://redis:6379/0") +SESSION_STORE = _env("SESSION_STORE", "redis") +DB_POOL_MIN = int(_env("DB_POOL_MIN", "1")) +DB_POOL_MAX = int(_env("DB_POOL_MAX", "10")) +DB_COMMAND_TIMEOUT = float(_env("DB_COMMAND_TIMEOUT", "5")) +DB_CONNECT_TIMEOUT = float(_env("DB_CONNECT_TIMEOUT", "5")) +REDIS_SOCKET_TIMEOUT = float(_env("REDIS_SOCKET_TIMEOUT", "2")) + + +def lab_mode() -> bool: + return ENV == "lab" diff --git a/app/cursor_codec.py b/app/cursor_codec.py new file mode 100644 index 00000000..40e6ce20 --- /dev/null +++ b/app/cursor_codec.py @@ -0,0 +1,112 @@ +import base64 + +import json + +from datetime import datetime + +from typing import Any + +from uuid import UUID + + + + + +def encode_cursor(chat_id: str, created_at: str, entity_id: str) -> str: + + payload = json.dumps({"c": chat_id, "t": created_at, "i": entity_id}, separators=(",", ":")) + + return base64.urlsafe_b64encode(payload.encode("utf-8")).decode("ascii").rstrip("=") + + + + + +def _validate_cursor_timestamp(value: str) -> None: + + if not value.endswith("Z"): + + raise ValueError("invalid cursor timestamp") + + try: + + datetime.fromisoformat(value[:-1] + "+00:00") + + except ValueError as exc: + + raise ValueError("invalid cursor timestamp") from exc + + + + + +def _require_str_field(data: dict, key: str) -> str: + + if key not in data: + + raise ValueError("invalid cursor") + + value = data[key] + + if not isinstance(value, str): + + raise ValueError("invalid cursor") + + return value + + + + + +def decode_cursor(cursor: str, expected_chat_id: str) -> tuple[str, str]: + + pad = "=" * (-len(cursor) % 4) + + try: + + raw = base64.urlsafe_b64decode((cursor + pad).encode("ascii")) + + data: Any = json.loads(raw.decode("utf-8")) + + except (ValueError, json.JSONDecodeError, UnicodeDecodeError) as exc: + + raise ValueError("invalid cursor") from exc + + if not isinstance(data, dict): + + raise ValueError("invalid cursor") + + try: + + chat_id = _require_str_field(data, "c") + + created_at = _require_str_field(data, "t") + + entity_id = _require_str_field(data, "i") + + except ValueError as exc: + + raise ValueError("invalid cursor") from exc + + if chat_id != expected_chat_id: + + raise ValueError("cursor chat mismatch") + + try: + + UUID(entity_id) + + except ValueError as exc: + + raise ValueError("invalid cursor") from exc + + try: + + _validate_cursor_timestamp(created_at) + + except ValueError as exc: + + raise ValueError("invalid cursor") from exc + + return created_at, entity_id + diff --git a/app/db.py b/app/db.py new file mode 100644 index 00000000..d655513e --- /dev/null +++ b/app/db.py @@ -0,0 +1,79 @@ +from pathlib import Path + +import asyncpg + +from app import config +from app.errors import AppError + +pool: asyncpg.Pool | None = None +INTEGRITY = ( + asyncpg.UniqueViolationError, + asyncpg.ForeignKeyViolationError, + asyncpg.CheckViolationError, +) + + +def _migrations_dir() -> Path: + here = Path(__file__).resolve().parent + for candidate in (here.parent / "migrations", Path("/app/migrations")): + if candidate.is_dir(): + return candidate + raise RuntimeError("migrations directory not found") + + +async def connect() -> asyncpg.Pool: + global pool + if not config.DATABASE_URL: + raise RuntimeError("DATABASE_URL is not set") + pool = await asyncpg.create_pool( + dsn=config.DATABASE_URL, + min_size=config.DB_POOL_MIN, + max_size=config.DB_POOL_MAX, + command_timeout=config.DB_COMMAND_TIMEOUT, + timeout=config.DB_CONNECT_TIMEOUT, + ) + return pool + + +async def close() -> None: + global pool + if pool is not None: + await pool.close() + pool = None + + +def require() -> asyncpg.Pool: + if pool is None: + raise AppError(503, "service unavailable") + return pool + + +async def ping() -> None: + try: + async with require().acquire() as conn: + await conn.execute("SELECT 1") + except AppError: + raise + except Exception: + raise AppError(503, "service unavailable") from None + + +async def apply_migrations() -> None: + directory = _migrations_dir() + async with require().acquire() as conn: + await conn.execute( + """ + CREATE TABLE IF NOT EXISTS schema_migrations ( + filename TEXT PRIMARY KEY, + applied_at TIMESTAMPTZ NOT NULL DEFAULT now() + ) + """ + ) + applied = {row["filename"] for row in await conn.fetch("SELECT filename FROM schema_migrations")} + for path in sorted(p for p in directory.glob("*.sql") if p.is_file()): + if path.name in applied: + continue + sql = path.read_text(encoding="utf-8") + async with conn.transaction(): + await conn.execute(sql) + await conn.execute("INSERT INTO schema_migrations(filename) VALUES($1)", path.name) diff --git a/app/docs.py b/app/docs.py new file mode 100644 index 00000000..7f68e1d9 --- /dev/null +++ b/app/docs.py @@ -0,0 +1,52 @@ +import json +from functools import lru_cache +from pathlib import Path + +from starlette.requests import Request +from starlette.responses import HTMLResponse, JSONResponse, Response + +_SPEC_CANDIDATES = ( + Path(__file__).resolve().parents[1] / "contracts" / "openapi.json", + Path("/app/contracts/openapi.json"), +) + +_SWAGGER_HTML = """ + + + + MTUSI Messenger — Swagger (lab2) + + + +
+ + + + +""" + + +@lru_cache(maxsize=1) +def _load_spec() -> dict: + for path in _SPEC_CANDIDATES: + if path.is_file(): + return json.loads(path.read_text(encoding="utf-8")) + return {"openapi": "3.1.0", "info": {"title": "MTUSI Messenger", "version": "1.2.0"}, "paths": {}} + + +async def openapi_json(_: Request) -> Response: + return JSONResponse(_load_spec()) + + +async def swagger_ui(_: Request) -> Response: + return HTMLResponse(_SWAGGER_HTML) diff --git a/app/errors.py b/app/errors.py new file mode 100644 index 00000000..105e8ca3 --- /dev/null +++ b/app/errors.py @@ -0,0 +1,49 @@ +from typing import Dict, Optional + +from starlette.responses import JSONResponse + + +ERROR_CODES = { + 400: "invalid_request", + 401: "unauthorized", + 404: "not_found", + 409: "conflict", + 413: "payload_too_large", + 415: "unsupported_media_type", + 429: "rate_limited", + 503: "unavailable", + 500: "internal_error", +} + +BASIC_CHALLENGE = 'Basic realm="messenger", charset="UTF-8"' +BEARER_CHALLENGE = 'Bearer realm="messenger"' + + +class AppError(Exception): + def __init__(self, status: int, message: str, www_authenticate: str | None = None) -> None: + super().__init__(message) + self.status = status + self.message = message + self.www_authenticate = www_authenticate + + +def error_response( + status: int, + message: str, + request_id: str, + extra_headers: Optional[Dict[str, str]] = None, +) -> JSONResponse: + code = ERROR_CODES.get(status, "internal_error") + headers = {"X-Request-Id": request_id, "Content-Type": "application/json"} + if extra_headers: + headers.update(extra_headers) + return JSONResponse( + status_code=status, + headers=headers, + content={"error": {"code": code, "message": message, "request_id": request_id}}, + ) + + +def from_app_error(exc: AppError, request_id: str) -> JSONResponse: + extra = {"WWW-Authenticate": exc.www_authenticate} if exc.www_authenticate else None + return error_response(exc.status, exc.message, request_id, extra) diff --git a/app/main.py b/app/main.py new file mode 100644 index 00000000..de77f6cd --- /dev/null +++ b/app/main.py @@ -0,0 +1,129 @@ +import asyncio +import logging +import signal +import sys +import uuid + +import uvicorn +from starlette.applications import Starlette +from starlette.exceptions import HTTPException +from starlette.requests import Request +from starlette.responses import Response +from starlette.routing import Route + +from app import config, db, rediscli +from app.docs import openapi_json, swagger_ui +from app.errors import AppError, error_response, from_app_error +from app.middleware import RequestContextMiddleware +from app.routes import ( + create_chat, + create_message, + create_session, + current_user, + get_chat, + health_live, + health_ready, + lab_flags, + lab_metrics, + list_chats, + list_messages, + register_user, + revoke_session, +) + + +def _request_id(request: Request) -> str: + existing = getattr(request.state, "request_id", None) + if existing: + return existing + return request.headers.get("X-Request-Id") or str(uuid.uuid4()) + + +async def not_found_handler(request: Request, exc: HTTPException) -> Response: + return error_response(404, "not found", _request_id(request)) + + +async def app_error_handler(request: Request, exc: AppError) -> Response: + return from_app_error(exc, _request_id(request)) + + +async def startup() -> None: + await db.connect() + await db.apply_migrations() + await rediscli.connect() + + +async def shutdown() -> None: + await rediscli.close() + await db.close() + + +def build_app() -> Starlette: + app = Starlette( + routes=[ + Route("/docs", swagger_ui, methods=["GET"]), + Route("/openapi.json", openapi_json, methods=["GET"]), + Route("/health/live", health_live, methods=["GET"]), + Route("/health/ready", health_ready, methods=["GET"]), + Route("/api/v1/users", register_user, methods=["POST"]), + Route("/api/v1/users/me", current_user, methods=["GET"]), + Route("/api/v1/auth/sessions", create_session, methods=["POST"]), + Route("/api/v1/auth/sessions/current", revoke_session, methods=["DELETE"]), + Route("/api/v1/chats", create_chat, methods=["POST"]), + Route("/api/v1/chats", list_chats, methods=["GET"]), + Route("/api/v1/chats/{chat_id}", get_chat, methods=["GET"]), + Route("/api/v1/chats/{chat_id}/messages", create_message, methods=["POST"]), + Route("/api/v1/chats/{chat_id}/messages", list_messages, methods=["GET"]), + Route("/api/v1/_lab/metrics", lab_metrics, methods=["GET"]), + Route("/api/v1/_lab/flags", lab_flags, methods=["POST"]), + ], + exception_handlers={404: not_found_handler, AppError: app_error_handler}, + on_startup=[startup], + on_shutdown=[shutdown], + ) + app.state.shutting_down = False + app.add_middleware(RequestContextMiddleware) + return app + + +def configure_logging() -> None: + logging.basicConfig( + level=getattr(logging, config.LOG_LEVEL.upper(), logging.INFO), + format="%(asctime)s %(levelname)s %(name)s %(message)s", + stream=sys.stdout, + ) + + +def main() -> None: + configure_logging() + app = build_app() + loop = asyncio.new_event_loop() + asyncio.set_event_loop(loop) + + server = uvicorn.Server( + uvicorn.Config( + app, + host=config.HOST, + port=config.PORT, + log_level=config.LOG_LEVEL, + access_log=False, + timeout_graceful_shutdown=int(config.SHUTDOWN_GRACE_SECONDS), + ) + ) + + def _begin_shutdown() -> None: + logging.getLogger("messenger").info("shutdown signal received") + app.state.shutting_down = True + server.should_exit = True + + for sig in (signal.SIGTERM, signal.SIGINT): + try: + loop.add_signal_handler(sig, _begin_shutdown) + except NotImplementedError: + signal.signal(sig, lambda *_: _begin_shutdown()) + + loop.run_until_complete(server.serve()) + + +if __name__ == "__main__": + main() diff --git a/app/middleware.py b/app/middleware.py new file mode 100644 index 00000000..76f3d06b --- /dev/null +++ b/app/middleware.py @@ -0,0 +1,41 @@ +import logging +import time +import uuid +from typing import Callable + +from starlette.middleware.base import BaseHTTPMiddleware +from starlette.requests import Request +from starlette.responses import Response + +from app.errors import AppError, error_response, from_app_error + +logger = logging.getLogger("messenger.access") + + +class RequestContextMiddleware(BaseHTTPMiddleware): + async def dispatch(self, request: Request, call_next: Callable) -> Response: + request_id = request.headers.get("X-Request-Id") or str(uuid.uuid4()) + request.state.request_id = request_id + + if request.app.state.shutting_down and request.url.path not in ("/health/live",): + return error_response(503, "service is shutting down", request_id) + + started = time.perf_counter() + try: + response = await call_next(request) + except AppError as exc: + return from_app_error(exc, request_id) + except Exception: + logger.exception("request_id=%s unhandled error path=%s", request_id, request.url.path) + return error_response(500, "internal error", request_id) + elapsed_ms = (time.perf_counter() - started) * 1000 + response.headers["X-Request-Id"] = request_id + logger.info( + "request_id=%s method=%s path=%s status=%s duration_ms=%.2f", + request_id, + request.method, + request.url.path, + response.status_code, + elapsed_ms, + ) + return response diff --git a/app/passwords.py b/app/passwords.py new file mode 100644 index 00000000..8a640cd0 --- /dev/null +++ b/app/passwords.py @@ -0,0 +1,23 @@ +from argon2 import PasswordHasher +from argon2.exceptions import InvalidHashError, VerifyMismatchError + +hasher = PasswordHasher(time_cost=2, memory_cost=8192, parallelism=1) +_dummy = None + + +def hash_password(password: str) -> str: + return hasher.hash(password) + + +def dummy_hash() -> str: + global _dummy + if _dummy is None: + _dummy = hash_password("timing-dummy-password") + return _dummy + + +def verify_password(password_hash: str, password: str) -> bool: + try: + return hasher.verify(password_hash, password) + except (VerifyMismatchError, InvalidHashError, TypeError, ValueError): + return False diff --git a/app/rediscli.py b/app/rediscli.py new file mode 100644 index 00000000..de173117 --- /dev/null +++ b/app/rediscli.py @@ -0,0 +1,40 @@ +import redis.asyncio as redis + +from app import config +from app.errors import AppError + +client: redis.Redis | None = None + + +async def connect() -> redis.Redis: + global client + client = redis.from_url( + config.REDIS_URL, + socket_connect_timeout=config.REDIS_SOCKET_TIMEOUT, + socket_timeout=config.REDIS_SOCKET_TIMEOUT, + decode_responses=True, + ) + await client.ping() + return client + + +async def close() -> None: + global client + if client is not None: + await client.close() + client = None + + +def require() -> redis.Redis: + if client is None: + raise AppError(503, "service unavailable") + return client + + +async def ping() -> None: + try: + await require().ping() + except AppError: + raise + except Exception: + raise AppError(503, "service unavailable") from None diff --git a/app/routes.py b/app/routes.py new file mode 100644 index 00000000..a5539b72 --- /dev/null +++ b/app/routes.py @@ -0,0 +1,273 @@ +import base64 +import binascii + +from starlette.requests import Request +from starlette.responses import JSONResponse, Response + +from app import cache, config, db, rediscli, sessions, store +from app.cursor_codec import decode_cursor, encode_cursor +from app.errors import BASIC_CHALLENGE, BEARER_CHALLENGE, AppError, error_response +from app.passwords import dummy_hash, hash_password, verify_password +from app.validation import ( + parse_json_body, + require_exact_keys, + validate_display_name, + validate_limit, + validate_message_text, + validate_password, + validate_title, + validate_username, + validate_uuid, +) + + +def _json(data: dict, request_id: str, status: int = 200) -> JSONResponse: + return JSONResponse(status_code=status, headers={"X-Request-Id": request_id}, content=data) + + +def _empty(request_id: str) -> Response: + return Response(status_code=204, headers={"X-Request-Id": request_id}) + + +async def _bearer_user(request: Request) -> dict: + header = request.headers.get("Authorization") or "" + scheme, _, rest = header.partition(" ") + if scheme.lower() != "bearer" or not rest.strip(): + raise AppError(401, "authentication required", BEARER_CHALLENGE) + user_id = str(await sessions.resolve(rest.strip())) + user = await store.get_user(user_id) + if user is None: + raise AppError(401, "authentication required", BEARER_CHALLENGE) + return user + + +async def health_live(request: Request) -> Response: + return _json({"status": "ok"}, request.state.request_id) + + +async def health_ready(request: Request) -> Response: + rid = request.state.request_id + if request.app.state.shutting_down: + return error_response(503, "service is shutting down", rid) + await db.ping() + await rediscli.ping() + return _json({"status": "ok"}, rid) + + +async def register_user(request: Request) -> Response: + rid = request.state.request_id + if request.headers.get("content-type", "").split(";")[0].strip().lower() not in ("application/json", ""): + if request.headers.get("content-type"): + return error_response(415, "unsupported media type", rid) + raw = await request.body() + body, err = parse_json_body(raw) + if err: + return error_response(400, err, rid) + assert body is not None + if require_exact_keys(body, {"username", "display_name", "password"}, {"username", "display_name", "password"}): + return error_response(400, "invalid user payload", rid) + if validate_username(body["username"]) or validate_display_name(body["display_name"]) or validate_password(body["password"]): + return error_response(400, "invalid user fields", rid) + user, conflict = await store.create_user(body["username"], body["display_name"], hash_password(body["password"])) + if conflict: + return error_response(409, "username already taken", rid) + assert user is not None + return _json(user, rid, 201) + + +async def current_user(request: Request) -> Response: + user = await _bearer_user(request) + return _json(user, request.state.request_id) + + +async def create_session(request: Request) -> Response: + rid = request.state.request_id + header = request.headers.get("Authorization") or "" + scheme, _, rest = header.partition(" ") + if scheme.lower() != "basic" or not rest.strip(): + return error_response(401, "authentication required", rid, {"WWW-Authenticate": BASIC_CHALLENGE}) + try: + decoded = base64.b64decode(rest.strip(), validate=True).decode("utf-8") + except (binascii.Error, UnicodeError, ValueError): + return error_response(401, "authentication required", rid, {"WWW-Authenticate": BASIC_CHALLENGE}) + username, sep, password = decoded.partition(":") + if not sep: + return error_response(401, "authentication required", rid, {"WWW-Authenticate": BASIC_CHALLENGE}) + row = await store.get_user_by_username(username) + password_hash = row["password_hash"] if row else dummy_hash() + if row is None or not verify_password(password_hash, password): + return error_response(401, "authentication required", rid, {"WWW-Authenticate": BASIC_CHALLENGE}) + token, expires_at = await sessions.create(row["id"]) + return _json( + { + "token": token, + "token_type": "Bearer", + "expires_at": expires_at, + "user": store.user_dict(row), + }, + rid, + 201, + ) + + +async def revoke_session(request: Request) -> Response: + header = request.headers.get("Authorization") or "" + scheme, _, rest = header.partition(" ") + if scheme.lower() != "bearer" or not rest.strip(): + raise AppError(401, "authentication required", BEARER_CHALLENGE) + await sessions.revoke(rest.strip()) + return _empty(request.state.request_id) + + +async def create_chat(request: Request) -> Response: + rid = request.state.request_id + user = await _bearer_user(request) + ct = request.headers.get("content-type", "").split(";")[0].strip().lower() + if ct and ct != "application/json": + return error_response(415, "unsupported media type", rid) + raw = await request.body() + body, err = parse_json_body(raw) + if err: + return error_response(400, err, rid) + assert body is not None + if require_exact_keys(body, {"title", "member_ids"}, {"title", "member_ids"}): + return error_response(400, "invalid chat payload", rid) + if validate_title(body["title"]): + return error_response(400, "invalid title", rid) + members = body["member_ids"] + if not isinstance(members, list) or not members: + return error_response(400, "invalid member_ids", rid) + if len(members) > 100: + return error_response(400, "too many members", rid) + for mid in members: + if validate_uuid(mid): + return error_response(400, "invalid member id", rid) + chat, create_err = await store.create_chat(body["title"], members, user["id"]) + if create_err == "caller not in members": + return error_response(400, "caller must be a member", rid) + if create_err in ("duplicate members", "unknown member"): + return error_response(400, "invalid members", rid) + assert chat is not None + return _json(chat, rid, 201) + + +async def list_chats(request: Request) -> Response: + rid = request.state.request_id + user = await _bearer_user(request) + limit, limit_err = validate_limit(request.query_params.get("limit")) + if limit_err: + return error_response(400, limit_err, rid) + assert limit is not None + cursor_raw = request.query_params.get("cursor") + after = None + if cursor_raw is not None: + if not cursor_raw.strip(): + return error_response(400, "invalid cursor", rid) + try: + created_at, entity_id = decode_cursor(cursor_raw, user["id"]) + except ValueError: + return error_response(400, "invalid cursor", rid) + after = (created_at, entity_id) + items, next_key = await store.list_chats(user["id"], limit, after) + next_cursor = None + if next_key is not None: + next_cursor = encode_cursor(user["id"], next_key[0], next_key[1]) + return _json({"items": items, "next_cursor": next_cursor}, rid) + + +async def get_chat(request: Request) -> Response: + rid = request.state.request_id + user = await _bearer_user(request) + chat_id = request.path_params["chat_id"] + if validate_uuid(chat_id): + return error_response(400, "invalid chat id", rid) + chat = await store.get_chat(chat_id, user["id"]) + if chat is None: + return error_response(404, "chat not found", rid) + return _json(chat, rid) + + +async def create_message(request: Request) -> Response: + rid = request.state.request_id + user = await _bearer_user(request) + chat_id = request.path_params["chat_id"] + if validate_uuid(chat_id): + return error_response(400, "invalid chat id", rid) + ct = request.headers.get("content-type", "").split(";")[0].strip().lower() + if ct and ct != "application/json": + return error_response(415, "unsupported media type", rid) + raw = await request.body() + body, err = parse_json_body(raw) + if err: + return error_response(400, err, rid) + assert body is not None + if require_exact_keys(body, {"text"}, {"text"}): + return error_response(400, "invalid message payload", rid) + if validate_message_text(body["text"]): + return error_response(400, "invalid message text", rid) + message, msg_err = await store.add_message(chat_id, user["id"], body["text"]) + if msg_err == "not_found": + return error_response(404, "chat not found", rid) + assert message is not None + return _json(message, rid, 201) + + +async def list_messages(request: Request) -> Response: + rid = request.state.request_id + user = await _bearer_user(request) + chat_id = request.path_params["chat_id"] + if validate_uuid(chat_id): + return error_response(400, "invalid chat id", rid) + limit, limit_err = validate_limit(request.query_params.get("limit")) + if limit_err: + return error_response(400, limit_err, rid) + assert limit is not None + cursor_raw = request.query_params.get("cursor") + after = None + if cursor_raw is not None: + if not cursor_raw.strip(): + return error_response(400, "invalid cursor", rid) + try: + created_at, entity_id = decode_cursor(cursor_raw, chat_id) + except ValueError: + return error_response(400, "invalid cursor", rid) + after = (created_at, entity_id) + page, next_key, list_err = await store.list_messages(chat_id, user["id"], limit, after) + if list_err == "not_found": + return error_response(404, "chat not found", rid) + assert page is not None + next_cursor = None + if next_key is not None: + next_cursor = encode_cursor(chat_id, next_key[0], next_key[1]) + return _json({"items": page, "next_cursor": next_cursor}, rid) + + +async def lab_metrics(request: Request) -> Response: + if not config.lab_mode(): + return error_response(404, "not found", request.state.request_id) + return _json( + { + "singleflight": await cache.singleflight_enabled(), + "invalidate": await cache.invalidate_enabled(), + "history_sql": await cache.history_sql_count(), + }, + request.state.request_id, + ) + + +async def lab_flags(request: Request) -> Response: + if not config.lab_mode(): + return error_response(404, "not found", request.state.request_id) + raw = await request.body() + body, err = parse_json_body(raw) + if err: + return error_response(400, err, request.state.request_id) + assert body is not None + if body.get("reset_sql"): + await cache.reset_history_sql_count() + flags = await cache.set_flags( + singleflight=body.get("singleflight"), + invalidate=body.get("invalidate"), + delay_ms=body.get("delay_ms"), + ) + return _json(flags, request.state.request_id) diff --git a/app/sessions.py b/app/sessions.py new file mode 100644 index 00000000..b0e30b11 --- /dev/null +++ b/app/sessions.py @@ -0,0 +1,56 @@ +import hashlib +import json +import secrets +from datetime import datetime, timedelta, timezone +from uuid import UUID + +from app import config, rediscli +from app.errors import AppError, BEARER_CHALLENGE + + +def new_token() -> str: + return secrets.token_urlsafe(32) + + +def _key(token: str) -> str: + return "sess:" + hashlib.sha256(token.encode("utf-8")).hexdigest() + + +def _fmt(dt: datetime) -> str: + return dt.astimezone(timezone.utc).isoformat(timespec="microseconds").replace("+00:00", "Z") + + +async def create(user_id: UUID) -> tuple[str, str]: + token = new_token() + expires = datetime.now(timezone.utc) + timedelta(seconds=config.SESSION_TTL_SECONDS) + payload = json.dumps({"user_id": str(user_id), "expires_at": _fmt(expires)}) + try: + await rediscli.require().set(_key(token), payload, ex=config.SESSION_TTL_SECONDS) + except AppError: + raise + except Exception: + raise AppError(503, "service unavailable") from None + return token, _fmt(expires) + + +async def resolve(token: str) -> UUID: + try: + raw = await rediscli.require().get(_key(token)) + except AppError: + raise + except Exception: + raise AppError(503, "service unavailable") from None + if not raw: + raise AppError(401, "authentication required", BEARER_CHALLENGE) + return UUID(json.loads(raw)["user_id"]) + + +async def revoke(token: str) -> None: + try: + deleted = await rediscli.require().delete(_key(token)) + except AppError: + raise + except Exception: + raise AppError(503, "service unavailable") from None + if not deleted: + raise AppError(401, "authentication required", BEARER_CHALLENGE) diff --git a/app/store.py b/app/store.py new file mode 100644 index 00000000..5c580f17 --- /dev/null +++ b/app/store.py @@ -0,0 +1,276 @@ +from __future__ import annotations + +from datetime import datetime, timezone +from typing import List, Optional, Tuple +from uuid import UUID, uuid4 + +import asyncpg + +from app import cache, db +from app.errors import AppError + + +def format_ts(dt: datetime) -> str: + if dt.tzinfo is None: + dt = dt.replace(tzinfo=timezone.utc) + return dt.astimezone(timezone.utc).isoformat(timespec="microseconds").replace("+00:00", "Z") + + +def user_dict(row) -> dict: + return { + "id": str(row["id"]), + "username": row["username"], + "display_name": row["display_name"], + "created_at": format_ts(row["created_at"]), + } + + +def chat_dict(row, member_ids: List[str]) -> dict: + return { + "id": str(row["id"]), + "title": row["title"], + "member_ids": member_ids, + "created_at": format_ts(row["created_at"]), + } + + +def message_dict(row) -> dict: + return { + "id": str(row["id"]), + "chat_id": str(row["chat_id"]), + "sender_id": str(row["sender_id"]), + "text": row["text"], + "created_at": format_ts(row["created_at"]), + } + + +async def _run(coro): + try: + return await coro + except AppError: + raise + except db.INTEGRITY: + raise + except Exception: + raise AppError(503, "service unavailable") from None + + +async def create_user(username: str, display_name: str, password_hash: str) -> Tuple[Optional[dict], Optional[str]]: + user_id = uuid4() + created = datetime.now(timezone.utc) + try: + async with db.require().acquire() as conn: + await conn.execute( + """ + INSERT INTO users (id, username, display_name, password_hash, created_at) + VALUES ($1, $2, $3, $4, $5) + """, + user_id, + username, + display_name, + password_hash, + created, + ) + except asyncpg.UniqueViolationError: + return None, "conflict" + except Exception: + raise AppError(503, "service unavailable") from None + return user_dict({"id": user_id, "username": username, "display_name": display_name, "created_at": created}), None + + +async def get_user(user_id: str) -> Optional[dict]: + row = await _run( + _fetchrow("SELECT id, username, display_name, created_at FROM users WHERE id = $1", UUID(user_id)) + ) + return user_dict(row) if row else None + + +async def get_user_by_username(username: str): + return await _run( + _fetchrow( + "SELECT id, username, display_name, password_hash, created_at FROM users WHERE username = $1", + username, + ) + ) + + +async def _fetchrow(sql: str, *args): + async with db.require().acquire() as conn: + return await conn.fetchrow(sql, *args) + + +async def _fetch(sql: str, *args): + async with db.require().acquire() as conn: + return await conn.fetch(sql, *args) + + +async def member_ids_of(chat_id: UUID) -> List[str]: + rows = await _run(_fetch("SELECT user_id FROM chat_members WHERE chat_id = $1 ORDER BY user_id", chat_id)) + return [str(r["user_id"]) for r in rows] + + +async def create_chat(title: str, member_ids: List[str], caller_id: str) -> Tuple[Optional[dict], Optional[str]]: + if caller_id not in member_ids: + return None, "caller not in members" + if len(set(member_ids)) != len(member_ids): + return None, "duplicate members" + ids = [UUID(x) for x in member_ids] + chat_id = uuid4() + created = datetime.now(timezone.utc) + try: + async with db.require().acquire() as conn: + async with conn.transaction(): + existing = await conn.fetch("SELECT id FROM users WHERE id = ANY($1::uuid[])", ids) + if len(existing) != len(ids): + return None, "unknown member" + await conn.execute( + "INSERT INTO chats (id, title, created_at) VALUES ($1, $2, $3)", + chat_id, + title, + created, + ) + await conn.executemany( + "INSERT INTO chat_members (chat_id, user_id) VALUES ($1, $2)", + [(chat_id, mid) for mid in ids], + ) + except AppError: + raise + except Exception: + raise AppError(503, "service unavailable") from None + return chat_dict({"id": chat_id, "title": title, "created_at": created}, member_ids), None + + +async def get_chat(chat_id: str, user_id: str) -> Optional[dict]: + row = await load_chat_for_member(chat_id, user_id) + if row is None: + return None + return chat_dict(row, await member_ids_of(UUID(chat_id))) + + +async def load_chat_for_member(chat_id: str, user_id: str): + return await _run( + _fetchrow( + """ + SELECT c.id, c.title, c.created_at + FROM chats c + JOIN chat_members m ON m.chat_id = c.id AND m.user_id = $2 + WHERE c.id = $1 + """, + UUID(chat_id), + UUID(user_id), + ) + ) + + +async def list_chats(user_id: str, limit: int, after: Optional[Tuple[str, str]] = None): + args: list = [UUID(user_id)] + clause = "" + if after is not None: + clause = "AND (c.created_at, c.id) > ($2, $3)" + args.extend([datetime.fromisoformat(after[0].replace("Z", "+00:00")), UUID(after[1])]) + rows = await _run( + _fetch( + f""" + SELECT c.id, c.title, c.created_at + FROM chats c + JOIN chat_members me ON me.chat_id = c.id AND me.user_id = $1 + WHERE 1=1 {clause} + ORDER BY c.created_at, c.id + LIMIT {int(limit) + 1} + """, + *args, + ) + ) + page = rows[:limit] + items = [chat_dict(row, await member_ids_of(row["id"])) for row in page] + next_key = None + if len(rows) > limit: + last = page[-1] + next_key = (format_ts(last["created_at"]), str(last["id"])) + return items, next_key + + +async def add_message(chat_id: str, sender_id: str, text: str) -> Tuple[Optional[dict], Optional[str]]: + if await load_chat_for_member(chat_id, sender_id) is None: + return None, "not_found" + message_id = uuid4() + created = datetime.now(timezone.utc) + try: + async with db.require().acquire() as conn: + await conn.execute( + """ + INSERT INTO messages (id, chat_id, sender_id, text, created_at) + VALUES ($1, $2, $3, $4, $5) + """, + message_id, + UUID(chat_id), + UUID(sender_id), + text, + created, + ) + except Exception: + raise AppError(503, "service unavailable") from None + await cache.invalidate_history(chat_id) + return message_dict( + { + "id": message_id, + "chat_id": UUID(chat_id), + "sender_id": UUID(sender_id), + "text": text, + "created_at": created, + } + ), None + + +async def list_messages(chat_id: str, user_id: str, limit: int, after: Optional[Tuple[str, str]] = None): + if await load_chat_for_member(chat_id, user_id) is None: + return None, None, "not_found" + cursor = "" + after_ts = after_id = None + if after is not None: + cursor = after[0] + ":" + after[1] + after_ts = datetime.fromisoformat(after[0].replace("Z", "+00:00")) + after_id = UUID(after[1]) + + async def loader() -> dict: + await cache.incr_history_sql() + if after_ts is None: + rows = await _run( + _fetch( + """ + SELECT id, chat_id, sender_id, text, created_at + FROM messages + WHERE chat_id = $1 + ORDER BY created_at, id + LIMIT $2 + """, + UUID(chat_id), + limit + 1, + ) + ) + else: + rows = await _run( + _fetch( + """ + SELECT id, chat_id, sender_id, text, created_at + FROM messages + WHERE chat_id = $1 AND (created_at, id) > ($2, $3) + ORDER BY created_at, id + LIMIT $4 + """, + UUID(chat_id), + after_ts, + after_id, + limit + 1, + ) + ) + page = rows[:limit] + items = [message_dict(r) for r in page] + next_key = None + if len(rows) > limit: + last = page[-1] + next_key = (format_ts(last["created_at"]), str(last["id"])) + return {"items": items, "next_key": next_key} + + page = await cache.get_history_page(chat_id, cursor, limit, loader) + return page["items"], page.get("next_key"), None diff --git a/app/tools/__init__.py b/app/tools/__init__.py new file mode 100644 index 00000000..8b137891 --- /dev/null +++ b/app/tools/__init__.py @@ -0,0 +1 @@ + diff --git a/app/tools/explain.py b/app/tools/explain.py new file mode 100644 index 00000000..e649ad14 --- /dev/null +++ b/app/tools/explain.py @@ -0,0 +1,73 @@ +"""Seed ≥10 000 messages and print EXPLAIN (ANALYZE, BUFFERS) for keyset pagination.""" +import asyncio +import os +from uuid import uuid4 + +import asyncpg + +from app.passwords import hash_password + + +async def main() -> None: + conn = await asyncpg.connect(dsn=os.environ["DATABASE_URL"], timeout=10, command_timeout=120) + try: + alice = uuid4() + bob = uuid4() + chat = uuid4() + pwd = hash_password("Example-only-not-a-real-secret-123") + await conn.execute( + "INSERT INTO users (id, username, display_name, password_hash) VALUES ($1,$2,$3,$4),($5,$6,$7,$4)", + alice, + "explain_a_" + alice.hex[:8], + "Alice", + pwd, + bob, + "explain_b_" + bob.hex[:8], + "Bob", + ) + await conn.execute("INSERT INTO chats (id, title) VALUES ($1,$2)", chat, "Explain chat") + await conn.execute( + "INSERT INTO chat_members (chat_id, user_id) VALUES ($1,$2),($1,$3)", + chat, + alice, + bob, + ) + n = int(os.environ.get("EXPLAIN_MESSAGES", "10000")) + await conn.execute( + """ + INSERT INTO messages (id, chat_id, sender_id, text, created_at) + SELECT gen_random_uuid(), $1, $2, 'seed-' || g, now() - (g || ' milliseconds')::interval + FROM generate_series(1, $3) AS g + """, + chat, + alice, + n, + ) + count = await conn.fetchval("SELECT count(*) FROM messages WHERE chat_id = $1", chat) + print("seeded_messages", count, "chat_id", chat) + first = await conn.fetchrow( + "SELECT created_at, id FROM messages WHERE chat_id = $1 ORDER BY created_at, id LIMIT 1", + chat, + ) + query = """ + SELECT id, chat_id, sender_id, text, created_at + FROM messages + WHERE chat_id = $1 AND (created_at, id) > ($2, $3) + ORDER BY created_at, id + LIMIT 50 + """ + print("\n=== WITH index messages_chat_created_id_idx ===") + plan = await conn.fetch("EXPLAIN (ANALYZE, BUFFERS) " + query, chat, first["created_at"], first["id"]) + print("\n".join(row[0] for row in plan)) + await conn.execute("SET enable_indexscan = off") + await conn.execute("SET enable_bitmapscan = off") + await conn.execute("SET enable_indexonlyscan = off") + print("\n=== WITHOUT index scans (seq scan baseline) ===") + plan2 = await conn.fetch("EXPLAIN (ANALYZE, BUFFERS) " + query, chat, first["created_at"], first["id"]) + print("\n".join(row[0] for row in plan2)) + finally: + await conn.close() + + +if __name__ == "__main__": + asyncio.run(main()) diff --git a/app/validation.py b/app/validation.py new file mode 100644 index 00000000..6b4f39db --- /dev/null +++ b/app/validation.py @@ -0,0 +1,95 @@ +import json +import re +from typing import Any, Dict, Optional, Tuple +from uuid import UUID + +USERNAME_RE = re.compile(r"^[a-z0-9_]{3,32}$") + + +def parse_json_body(raw: bytes) -> Tuple[Optional[Dict[str, Any]], Optional[str]]: + if not raw: + return None, "empty body" + try: + data = json.loads(raw.decode("utf-8")) + except (UnicodeDecodeError, json.JSONDecodeError): + return None, "malformed JSON" + if not isinstance(data, dict): + return None, "JSON body must be an object" + return data, None + + +def require_exact_keys(data: Dict[str, Any], allowed: set, required: set) -> Optional[str]: + keys = set(data.keys()) + if keys - allowed: + return "unexpected fields" + if required - keys: + return "missing required fields" + return None + + +def validate_username(value: Any) -> Optional[str]: + if not isinstance(value, str) or not USERNAME_RE.fullmatch(value): + return "invalid username" + return None + + +def validate_display_name(value: Any) -> Optional[str]: + if not isinstance(value, str): + return "invalid display_name" + if not value.strip(): + return "display_name must not be blank" + if len(value) > 100: + return "display_name too long" + return None + + +def validate_password(value: Any) -> Optional[str]: + if not isinstance(value, str): + return "invalid password" + if not value.strip(): + return "password must not be blank" + if len(value) < 12 or len(value) > 128: + return "password length" + return None + + +def validate_title(value: Any) -> Optional[str]: + if not isinstance(value, str): + return "invalid title" + if not value.strip(): + return "title must not be blank" + if len(value) > 100: + return "title too long" + return None + + +def validate_uuid(value: Any) -> Optional[str]: + if not isinstance(value, str): + return "invalid uuid" + try: + UUID(value) + except ValueError: + return "invalid uuid" + return None + + +def validate_message_text(value: Any) -> Optional[str]: + if not isinstance(value, str): + return "invalid text" + if not value.strip(): + return "text must not be blank" + if len(value) > 4000: + return "text too long" + return None + + +def validate_limit(value: Optional[str], default: int = 50) -> Tuple[Optional[int], Optional[str]]: + if value is None: + return default, None + try: + limit = int(value) + except ValueError: + return None, "invalid limit" + if limit < 1 or limit > 100: + return None, "limit out of range" + return limit, None diff --git a/compose.yaml b/compose.yaml new file mode 100644 index 00000000..d61e1dba --- /dev/null +++ b/compose.yaml @@ -0,0 +1,80 @@ +services: + api: + build: + context: . + dockerfile: Dockerfile + image: mtusi-messenger:lab2 + ports: + - "127.0.0.1:8080:8080" + environment: + APP_HOST: 0.0.0.0 + APP_PORT: "8080" + APP_ENV: lab + LOG_LEVEL: info + SHUTDOWN_GRACE_SECONDS: "10" + SESSION_TTL_SECONDS: ${SESSION_TTL_SECONDS:-3600} + CACHE_TTL_SECONDS: ${CACHE_TTL_SECONDS:-60} + SESSION_STORE: redis + DATABASE_URL: postgresql://messenger:${POSTGRES_PASSWORD}@postgres:5432/messenger + REDIS_URL: redis://redis:6379/0 + DB_POOL_MIN: "1" + DB_POOL_MAX: "10" + DB_COMMAND_TIMEOUT: "5" + DB_CONNECT_TIMEOUT: "5" + depends_on: + postgres: + condition: service_healthy + redis: + condition: service_healthy + restart: unless-stopped + mem_limit: 512m + cpus: "1.0" + healthcheck: + test: ["CMD", "curl", "-fsS", "http://127.0.0.1:8080/health/ready"] + interval: 5s + timeout: 3s + retries: 12 + start_period: 20s + + postgres: + image: postgres:16.6-alpine + environment: + POSTGRES_USER: messenger + POSTGRES_PASSWORD: ${POSTGRES_PASSWORD} + POSTGRES_DB: messenger + volumes: + - pg_data:/var/lib/postgresql/data + healthcheck: + test: ["CMD-SHELL", "pg_isready -U messenger -d messenger"] + interval: 3s + timeout: 3s + retries: 20 + restart: unless-stopped + mem_limit: 512m + cpus: "1.0" + + redis: + image: redis:7.4.2-alpine + command: + - redis-server + - --appendonly + - "yes" + - --appendfsync + - everysec + - --save + - "60" + - "1" + volumes: + - redis_data:/data + healthcheck: + test: ["CMD", "redis-cli", "ping"] + interval: 3s + timeout: 3s + retries: 20 + restart: unless-stopped + mem_limit: 128m + cpus: "0.50" + +volumes: + pg_data: + redis_data: diff --git a/evidence/compose_after_restart.txt b/evidence/compose_after_restart.txt new file mode 100644 index 00000000..8ef15e83 --- /dev/null +++ b/evidence/compose_after_restart.txt @@ -0,0 +1,3 @@ +{"Command":"\"python -m app.main\"","CreatedAt":"2026-11-07 11:46:43 +0300 MSK","ExitCode":0,"Health":"starting","ID":"35a7c6412cc4","Image":"mtusi-messenger:lab2","Labels":"com.docker.compose.container-number=1,com.docker.compose.project.config_files=C:\\Users\\david\\Desktop\\mtuci\\highload\\lab2\\mtusi2026lab2\\compose.yaml,com.docker.compose.project.environment_file=C:\\Users\\david\\Desktop\\mtuci\\highload\\lab2\\mtusi2026lab2\\.env,com.docker.compose.project.working_dir=C:\\Users\\david\\Desktop\\mtuci\\highload\\lab2\\mtusi2026lab2,com.docker.compose.replace=api-1,com.docker.compose.depends_on=redis:service_healthy:false,postgres:service_healthy:false,com.docker.compose.image=sha256:68ca44864e87cf6b2e15ff1ae2a62a58e754282d7cfd58e7c44e7e3820eb4129,com.docker.compose.oneoff=False,com.docker.compose.project=mtusi2026lab2,com.docker.compose.service=api,com.docker.compose.version=5.1.4,desktop.docker.io/ports.scheme=v2,desktop.docker.io/ports/8080/tcp=127.0.0.1:8080,com.docker.compose.config-hash=a7a455b20e0dbc0b8ebe9657814869a6dd93509709073efef2180caaa2708102","LocalVolumes":"0","Mounts":"","Name":"mtusi2026lab2-api-1","Names":"mtusi2026lab2-api-1","Networks":"mtusi2026lab2_default","Ports":"127.0.0.1:8080-\u003e8080/tcp","Project":"mtusi2026lab2","Publishers":[{"URL":"127.0.0.1","TargetPort":8080,"PublishedPort":8080,"Protocol":"tcp"}],"RunningFor":"24 seconds ago","Service":"api","Size":"0B","State":"running","Status":"Up 1 second (health: starting)"} +{"Command":"\"docker-entrypoint.sΓǪ\"","CreatedAt":"2026-11-07 11:41:21 +0300 MSK","ExitCode":0,"Health":"starting","ID":"e56b24d17f33","Image":"postgres:16.6-alpine","Labels":"com.docker.compose.config-hash=f1371900a17bcdc05dede1af7f1eb40384c58a16f0e7dd521f9bf9fd59cba4d4,com.docker.compose.container-number=1,com.docker.compose.image=sha256:1d04b9ba1d4996401f2552b51beda8187f175c0645c091e4781134fc9c9a3eef,com.docker.compose.oneoff=False,com.docker.compose.project=mtusi2026lab2,com.docker.compose.project.working_dir=C:\\Users\\david\\Desktop\\mtuci\\highload\\lab2\\mtusi2026lab2,com.docker.compose.version=5.1.4,desktop.docker.io/ports.scheme=v2,com.docker.compose.depends_on=,com.docker.compose.project.config_files=C:\\Users\\david\\Desktop\\mtuci\\highload\\lab2\\mtusi2026lab2\\compose.yaml,com.docker.compose.project.environment_file=C:\\Users\\david\\Desktop\\mtuci\\highload\\lab2\\mtusi2026lab2\\.env,com.docker.compose.service=postgres","LocalVolumes":"1","Mounts":"mtusi2026lab2_ΓǪ","Name":"mtusi2026lab2-postgres-1","Names":"mtusi2026lab2-postgres-1","Networks":"mtusi2026lab2_default","Ports":"5432/tcp","Project":"mtusi2026lab2","Publishers":[{"URL":"","TargetPort":5432,"PublishedPort":0,"Protocol":"tcp"}],"RunningFor":"5 minutes ago","Service":"postgres","Size":"0B","State":"running","Status":"Up 1 second (health: starting)"} +{"Command":"\"docker-entrypoint.sΓǪ\"","CreatedAt":"2026-11-07 11:41:21 +0300 MSK","ExitCode":0,"Health":"starting","ID":"e36d755039e4","Image":"redis:7.4.2-alpine","Labels":"com.docker.compose.config-hash=c3421b01b047dac5406b7325d9879914f4830500c975d999822051d3926fdf3c,com.docker.compose.container-number=1,com.docker.compose.depends_on=,com.docker.compose.image=sha256:02419de7eddf55aa5bcf49efb74e88fa8d931b4d77c07eff8a6b2144472b6952,com.docker.compose.oneoff=False,com.docker.compose.project.config_files=C:\\Users\\david\\Desktop\\mtuci\\highload\\lab2\\mtusi2026lab2\\compose.yaml,desktop.docker.io/ports.scheme=v2,com.docker.compose.project=mtusi2026lab2,com.docker.compose.project.environment_file=C:\\Users\\david\\Desktop\\mtuci\\highload\\lab2\\mtusi2026lab2\\.env,com.docker.compose.project.working_dir=C:\\Users\\david\\Desktop\\mtuci\\highload\\lab2\\mtusi2026lab2,com.docker.compose.service=redis,com.docker.compose.version=5.1.4","LocalVolumes":"1","Mounts":"mtusi2026lab2_ΓǪ","Name":"mtusi2026lab2-redis-1","Names":"mtusi2026lab2-redis-1","Networks":"mtusi2026lab2_default","Ports":"6379/tcp","Project":"mtusi2026lab2","Publishers":[{"URL":"","TargetPort":6379,"PublishedPort":0,"Protocol":"tcp"}],"RunningFor":"5 minutes ago","Service":"redis","Size":"0B","State":"running","Status":"Up 1 second (health: starting)"} diff --git a/evidence/compose_before_restart.txt b/evidence/compose_before_restart.txt new file mode 100644 index 00000000..9b965a4f --- /dev/null +++ b/evidence/compose_before_restart.txt @@ -0,0 +1,3 @@ +{"Command":"\"python -m app.main\"","CreatedAt":"2026-11-07 11:46:43 +0300 MSK","ExitCode":0,"Health":"healthy","ID":"35a7c6412cc4","Image":"mtusi-messenger:lab2","Labels":"com.docker.compose.project.working_dir=C:\\Users\\david\\Desktop\\mtuci\\highload\\lab2\\mtusi2026lab2,com.docker.compose.replace=api-1,com.docker.compose.service=api,desktop.docker.io/ports.scheme=v2,com.docker.compose.container-number=1,com.docker.compose.depends_on=redis:service_healthy:false,postgres:service_healthy:false,com.docker.compose.image=sha256:68ca44864e87cf6b2e15ff1ae2a62a58e754282d7cfd58e7c44e7e3820eb4129,com.docker.compose.oneoff=False,com.docker.compose.project=mtusi2026lab2,com.docker.compose.project.environment_file=C:\\Users\\david\\Desktop\\mtuci\\highload\\lab2\\mtusi2026lab2\\.env,com.docker.compose.version=5.1.4,desktop.docker.io/ports/8080/tcp=127.0.0.1:8080,com.docker.compose.config-hash=a7a455b20e0dbc0b8ebe9657814869a6dd93509709073efef2180caaa2708102,com.docker.compose.project.config_files=C:\\Users\\david\\Desktop\\mtuci\\highload\\lab2\\mtusi2026lab2\\compose.yaml","LocalVolumes":"0","Mounts":"","Name":"mtusi2026lab2-api-1","Names":"mtusi2026lab2-api-1","Networks":"mtusi2026lab2_default","Ports":"127.0.0.1:8080-\u003e8080/tcp","Project":"mtusi2026lab2","Publishers":[{"URL":"127.0.0.1","TargetPort":8080,"PublishedPort":8080,"Protocol":"tcp"}],"RunningFor":"22 seconds ago","Service":"api","Size":"0B","State":"running","Status":"Up 19 seconds (healthy)"} +{"Command":"\"docker-entrypoint.sΓǪ\"","CreatedAt":"2026-11-07 11:41:21 +0300 MSK","ExitCode":0,"Health":"healthy","ID":"e56b24d17f33","Image":"postgres:16.6-alpine","Labels":"com.docker.compose.service=postgres,com.docker.compose.version=5.1.4,desktop.docker.io/ports.scheme=v2,com.docker.compose.config-hash=f1371900a17bcdc05dede1af7f1eb40384c58a16f0e7dd521f9bf9fd59cba4d4,com.docker.compose.container-number=1,com.docker.compose.oneoff=False,com.docker.compose.project.config_files=C:\\Users\\david\\Desktop\\mtuci\\highload\\lab2\\mtusi2026lab2\\compose.yaml,com.docker.compose.depends_on=,com.docker.compose.image=sha256:1d04b9ba1d4996401f2552b51beda8187f175c0645c091e4781134fc9c9a3eef,com.docker.compose.project=mtusi2026lab2,com.docker.compose.project.environment_file=C:\\Users\\david\\Desktop\\mtuci\\highload\\lab2\\mtusi2026lab2\\.env,com.docker.compose.project.working_dir=C:\\Users\\david\\Desktop\\mtuci\\highload\\lab2\\mtusi2026lab2","LocalVolumes":"1","Mounts":"mtusi2026lab2_ΓǪ","Name":"mtusi2026lab2-postgres-1","Names":"mtusi2026lab2-postgres-1","Networks":"mtusi2026lab2_default","Ports":"5432/tcp","Project":"mtusi2026lab2","Publishers":[{"URL":"","TargetPort":5432,"PublishedPort":0,"Protocol":"tcp"}],"RunningFor":"5 minutes ago","Service":"postgres","Size":"0B","State":"running","Status":"Up 5 minutes (healthy)"} +{"Command":"\"docker-entrypoint.sΓǪ\"","CreatedAt":"2026-11-07 11:41:21 +0300 MSK","ExitCode":0,"Health":"healthy","ID":"e36d755039e4","Image":"redis:7.4.2-alpine","Labels":"com.docker.compose.config-hash=c3421b01b047dac5406b7325d9879914f4830500c975d999822051d3926fdf3c,com.docker.compose.image=sha256:02419de7eddf55aa5bcf49efb74e88fa8d931b4d77c07eff8a6b2144472b6952,com.docker.compose.project=mtusi2026lab2,com.docker.compose.project.working_dir=C:\\Users\\david\\Desktop\\mtuci\\highload\\lab2\\mtusi2026lab2,desktop.docker.io/ports.scheme=v2,com.docker.compose.container-number=1,com.docker.compose.depends_on=,com.docker.compose.oneoff=False,com.docker.compose.project.config_files=C:\\Users\\david\\Desktop\\mtuci\\highload\\lab2\\mtusi2026lab2\\compose.yaml,com.docker.compose.project.environment_file=C:\\Users\\david\\Desktop\\mtuci\\highload\\lab2\\mtusi2026lab2\\.env,com.docker.compose.service=redis,com.docker.compose.version=5.1.4","LocalVolumes":"1","Mounts":"mtusi2026lab2_ΓǪ","Name":"mtusi2026lab2-redis-1","Names":"mtusi2026lab2-redis-1","Networks":"mtusi2026lab2_default","Ports":"6379/tcp","Project":"mtusi2026lab2","Publishers":[{"URL":"","TargetPort":6379,"PublishedPort":0,"Protocol":"tcp"}],"RunningFor":"5 minutes ago","Service":"redis","Size":"0B","State":"running","Status":"Up 5 minutes (healthy)"} diff --git a/evidence/explain-history.txt b/evidence/explain-history.txt new file mode 100644 index 00000000..3f393507 --- /dev/null +++ b/evidence/explain-history.txt @@ -0,0 +1,26 @@ +seeded_messages 10000 chat_id 364e2ede-c155-44e4-9a70-4f1a7cfcac5c + +=== WITH index messages_chat_created_id_idx === +Limit (cost=0.28..8.30 rows=1 width=86) (actual time=0.012..0.017 rows=50 loops=1) + Buffers: shared hit=3 + -> Index Scan using messages_chat_created_id_idx on messages (cost=0.28..8.30 rows=1 width=86) (actual time=0.011..0.014 rows=50 loops=1) + Index Cond: ((chat_id = '364e2ede-c155-44e4-9a70-4f1a7cfcac5c'::uuid) AND (ROW(created_at, id) > ROW('2026-11-07 08:47:19.224775+00'::timestamp with time zone, 'b63c0a90-e11b-4742-b7a3-122f5ec164ca'::uuid))) + Buffers: shared hit=3 +Planning: + Buffers: shared hit=36 +Planning Time: 0.307 ms +Execution Time: 0.061 ms + +=== WITHOUT index scans (seq scan baseline) === +Limit (cost=206.18..206.19 rows=1 width=86) (actual time=2.041..2.046 rows=50 loops=1) + Buffers: shared hit=130 read=11 + -> Sort (cost=206.18..206.19 rows=1 width=86) (actual time=2.040..2.042 rows=50 loops=1) + Sort Key: created_at, id + Sort Method: top-N heapsort Memory: 38kB + Buffers: shared hit=130 read=11 + -> Seq Scan on messages (cost=0.00..206.17 rows=1 width=86) (actual time=0.080..0.805 rows=9999 loops=1) + Filter: ((chat_id = '364e2ede-c155-44e4-9a70-4f1a7cfcac5c'::uuid) AND (ROW(created_at, id) > ROW('2026-11-07 08:47:19.224775+00'::timestamp with time zone, 'b63c0a90-e11b-4742-b7a3-122f5ec164ca'::uuid))) + Rows Removed by Filter: 350 + Buffers: shared hit=124 read=11 +Planning Time: 0.053 ms +Execution Time: 2.081 ms diff --git a/evidence/load.json b/evidence/load.json new file mode 100644 index 00000000..cc1cd510 --- /dev/null +++ b/evidence/load.json @@ -0,0 +1,17 @@ +{ + "lab": 2, + "workload": "closed-loop POST messages; no automatic retries", + "requested_duration_seconds": 15.0, + "elapsed_seconds": 15.052, + "concurrency": 4, + "successful_requests": 5077, + "failed_requests": 0, + "error_ratio": 0.0, + "successful_rps": 337.306, + "successful_latency_ms": { + "p50": 9.684, + "p95": 27.385, + "p99": 33.26 + }, + "note": "Latency percentiles cover successes only. Timeouts/errors are counted separately; closed-loop has coordinated omission and client overhead." +} diff --git a/evidence/stampede.json b/evidence/stampede.json new file mode 100644 index 00000000..b2c87c4d --- /dev/null +++ b/evidence/stampede.json @@ -0,0 +1,10 @@ +{ + "hypothesis": "Without singleflight, concurrent cache misses on the same history page issue one SQL SELECT per waiter; with in-process singleflight they share one load.", + "concurrency": 24, + "artificial_miss_delay_ms": 250, + "stampede_sql_without_singleflight": 24, + "stampede_sql_with_singleflight": 1, + "read_after_write": "POST message increments histver; next GET misses and returns the new row", + "stale_when_invalidate_disabled": "GET after POST omitted the new text until invalidate was re-enabled", + "redis_restart": "AOF restored the Bearer session; history was rebuilt from PostgreSQL" +} diff --git a/migrations/001_init.sql b/migrations/001_init.sql new file mode 100644 index 00000000..2501deea --- /dev/null +++ b/migrations/001_init.sql @@ -0,0 +1,49 @@ +-- Lab2 schema (written before application queries). +-- Source of truth: PostgreSQL for users, chats, membership, messages. +-- Transaction boundary: INSERT chat + INSERT members in one transaction (rollback together). +-- Sessions are stored in Redis with AOF, not in this database. + +CREATE TABLE IF NOT EXISTS schema_migrations ( + filename TEXT PRIMARY KEY, + applied_at TIMESTAMPTZ NOT NULL DEFAULT now() +); + +CREATE TABLE users ( + id UUID PRIMARY KEY, + username TEXT NOT NULL, + display_name TEXT NOT NULL, + password_hash TEXT NOT NULL, + created_at TIMESTAMPTZ NOT NULL DEFAULT now(), + CONSTRAINT users_username_format CHECK (username ~ '^[a-z0-9_]{3,32}$'), + CONSTRAINT users_display_name_len CHECK (char_length(display_name) BETWEEN 1 AND 100) +); + +CREATE UNIQUE INDEX users_username_key ON users (username); + +CREATE TABLE chats ( + id UUID PRIMARY KEY, + title TEXT NOT NULL, + created_at TIMESTAMPTZ NOT NULL DEFAULT now(), + CONSTRAINT chats_title_len CHECK (char_length(title) BETWEEN 1 AND 100) +); + +CREATE TABLE chat_members ( + chat_id UUID NOT NULL REFERENCES chats (id) ON DELETE CASCADE, + user_id UUID NOT NULL REFERENCES users (id), + PRIMARY KEY (chat_id, user_id) +); + +CREATE INDEX chat_members_user_id_idx ON chat_members (user_id); +CREATE INDEX chats_created_at_id_idx ON chats (created_at, id); + +CREATE TABLE 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(), + CONSTRAINT messages_text_len CHECK (char_length(text) BETWEEN 1 AND 4000) +); + +-- Keyset history: WHERE chat_id = $1 AND (created_at, id) > ($2, $3) ORDER BY created_at, id LIMIT n +CREATE INDEX messages_chat_created_id_idx ON messages (chat_id, created_at, id); diff --git a/pytest.ini b/pytest.ini new file mode 100644 index 00000000..ce023a9a --- /dev/null +++ b/pytest.ini @@ -0,0 +1,6 @@ +[pytest] +testpaths = student_tests +pythonpath = . +markers = + infra: compose stop/restart of redis or postgres + expiry: requires SESSION_TTL_SECONDS<=3 diff --git a/requirements-test.txt b/requirements-test.txt new file mode 100644 index 00000000..f7f80320 --- /dev/null +++ b/requirements-test.txt @@ -0,0 +1,2 @@ +pytest==8.3.4 +httpx==0.28.1 diff --git a/requirements.txt b/requirements.txt new file mode 100644 index 00000000..4a028ebb --- /dev/null +++ b/requirements.txt @@ -0,0 +1,5 @@ +starlette==0.41.3 +uvicorn[standard]==0.32.1 +asyncpg==0.30.0 +redis==5.2.1 +argon2-cffi==23.1.0 diff --git a/scripts/restart.bat b/scripts/restart.bat new file mode 100644 index 00000000..d96ae9d7 --- /dev/null +++ b/scripts/restart.bat @@ -0,0 +1,3 @@ +@echo off +python "%~dp0restart.py" +exit /b %ERRORLEVEL% diff --git a/scripts/restart.py b/scripts/restart.py new file mode 100644 index 00000000..639651e8 --- /dev/null +++ b/scripts/restart.py @@ -0,0 +1,20 @@ +#!/usr/bin/env python3 +"""Restart API, PostgreSQL and Redis without removing named volumes.""" +from pathlib import Path +import subprocess +import sys + +ROOT = Path(__file__).resolve().parents[1] + + +def main() -> int: + env_file = ROOT / ".env" + cmd = ["docker", "compose"] + if env_file.is_file(): + cmd.extend(["--env-file", str(env_file)]) + cmd.extend(["restart", "postgres", "redis", "api"]) + return subprocess.run(cmd, cwd=ROOT).returncode + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/scripts/restart.sh b/scripts/restart.sh new file mode 100644 index 00000000..81d27153 --- /dev/null +++ b/scripts/restart.sh @@ -0,0 +1,9 @@ +#!/bin/sh +set -eu +ROOT=$(CDPATH= cd -- "$(dirname -- "$0")/.." && pwd) +cd "$ROOT" +if [ -f .env ]; then + docker compose --env-file .env restart postgres redis api +else + docker compose restart postgres redis api +fi diff --git a/scripts/run_expiry.py b/scripts/run_expiry.py new file mode 100644 index 00000000..42d87200 --- /dev/null +++ b/scripts/run_expiry.py @@ -0,0 +1,55 @@ +#!/usr/bin/env python3 +"""Recreate API with SESSION_TTL_SECONDS=2, test expiry, restore TTL.""" +import os +import subprocess +import sys +import time +from pathlib import Path + +ROOT = Path(__file__).resolve().parents[1] + + +def compose(args, extra_env=None): + env = os.environ.copy() + if extra_env: + env.update(extra_env) + cmd = ["docker", "compose"] + if (ROOT / ".env").is_file(): + cmd.extend(["--env-file", str(ROOT / ".env")]) + cmd.extend(args) + proc = subprocess.run(cmd, cwd=ROOT, env=env) + if proc.returncode != 0: + raise SystemExit(proc.returncode) + + +def wait_ready(): + import urllib.request + + deadline = time.monotonic() + 90 + while time.monotonic() < deadline: + try: + urllib.request.urlopen("http://127.0.0.1:8080/health/ready", timeout=2) + return + except Exception: + time.sleep(0.5) + raise SystemExit("API did not become ready") + + +def main(): + compose(["up", "-d", "--no-deps", "--force-recreate", "api"], {"SESSION_TTL_SECONDS": "2"}) + wait_ready() + env = os.environ.copy() + env["SESSION_TTL_SECONDS"] = "2" + env["RUN_EXPIRY"] = "1" + proc = subprocess.run( + [sys.executable, "-m", "pytest", "student_tests/test_expiry.py", "-q"], + cwd=ROOT, + env=env, + ) + compose(["up", "-d", "--no-deps", "--force-recreate", "api"], {"SESSION_TTL_SECONDS": "3600"}) + wait_ready() + raise SystemExit(proc.returncode) + + +if __name__ == "__main__": + main() diff --git a/solve.md b/solve.md new file mode 100644 index 00000000..2e9423c6 --- /dev/null +++ b/solve.md @@ -0,0 +1,196 @@ +# Что происходит в лабораторной 2 + +Lab1 доказала, что контракт можно реализовать процессом в контейнере. Состояние жило в RAM и исчезало вместе с процессом. Lab2 решает другую задачу: **подтверждённые данные и ещё действующая сессия должны пережить рестарт**, а клиент должен быть **аутентифицированным пользователем**, а не строкой `X-User-Id`, которую любой может подставить. + +Целевая оценка этой работы — **5**, трек **согласованность кэша**. Ниже — не перечень файлов, а причины решений. + +--- + +## 1. Зачем вообще уходить из памяти + +In-memory store в lab1 был правильным минимумом: нет внешних зависимостей, легко гонять smoke. Он ломается в тот момент, когда появляется требование «после `docker compose restart` токен и сообщения на месте». + +Память процесса не является хранилищем: + +- SIGTERM / OOM / `restart` обнуляют словари; +- второй экземпляр API (это уже lab3) не увидит тех же пользователей; +- нельзя честно говорить про транзакции и индексы. + +Поэтому источник истины для пользователей, чатов, членства и сообщений — **PostgreSQL**. API становится тонким слоем: проверить контракт, открыть транзакцию, отдать JSON. Если Postgres недоступен, бизнес-путь нельзя обслуживать «из кэша как из правды»: кэш может быть неполным или устаревшим. + +SQLite сознательно не используется: стенд должен совпадать с тем, что будет масштабироваться дальше (сеть, пул, WAL, volume). + +--- + +## 2. Схема: ограничения в БД, а не только в Python + +Проверки в `app/validation.py` отсекают мусор на границе HTTP. Этого мало. Два клиента могут одновременно пройти проверку «username свободен» и оба сделать INSERT. Поэтому уникальность username — **UNIQUE INDEX в Postgres**. Гонка даёт `UniqueViolation` → один `201`, остальные `409`. Это не «оптимизация», а единственный способ получить корректность без распределённой блокировки на уровне приложения. + +Чат создаётся **атомарно**: строка `chats` и все строки `chat_members` в одной транзакции. Если среди `member_ids` есть несуществующий UUID, транзакция откатывается. Иначе получился бы «чат-сирота» без полного списка участников — объект, которого контракт не описывает и который нельзя честно отдать в `GET /chats`. + +Внешние ключи (`chat_members.user_id → users`, `messages.chat_id → chats`) держат инвариант даже если код ошибётся. `ON DELETE CASCADE` здесь учебный: обязательный API удаления не даёт, но схема не оставляет висящих членов при ручной чистке стенда. + +Порядок истории задан контрактом: `(created_at, id)` по возрастанию, keyset-cursor, `limit` 1–100. Запрос страницы: + +```sql +WHERE chat_id = $1 AND (created_at, id) > ($2, $3) +ORDER BY created_at, id +LIMIT n +``` + +Индекс `messages (chat_id, created_at, id)` построен **под этот предикат**, а не «на всякий случай по chat_id». Без него Postgres читает и сортирует всю историю чата (seq scan). На 10 000 сообщений это видно в `EXPLAIN (ANALYZE, BUFFERS)`: Index Scan ~0.06 ms против Seq Scan ~2 ms. Пагинация не должна каждый раз сканировать всю таблицу — иначе стоимость чтения растёт линейно с возрастом чата, а cursor теряет смысл. + +Почему не `OFFSET`? `OFFSET 10000` всё равно просматривает 10 000 строк и отбрасывает их. Keyset опирается на уже известную точку `(created_at, id)` и идёт дальше по индексу. + +Cursor непрозрачный (base64 JSON + привязка к `chat_id`). Клиент не должен листать чужой чат, подставив cursor от другого. Это не криптография, а привязка курсора к ресурсу, как требует контракт. + +--- + +## 3. Почему сессия, а не `X-User-Id` + +В lab1 любой, кто знает UUID Алисы, *является* Алисой. Это учебный ярлык, не аутентификация. + +Новая модель: + +1. Регистрация принимает `password`. В таблицу попадает не пароль, а **Argon2id**. +2. Вход — только `POST /api/v1/auth/sessions` с `Authorization: Basic`. Basic здесь **кодирование** `username:password` в Base64, не шифрование. По HTTP на учебной машине это допустимо; на удалённой демонстрации нужен TLS (это lab7). +3. Ответ — opaque Bearer (≥256 бит случайности). Это не JWT и не username: сервер не парсит токен как утверждение, а **смотрит запись сессии**. +4. Остальные защищённые пути принимают только Bearer. Basic на `/users/me` — 401. `X-User-Id` игнорируется: иначе старый клиент lab1 обошёл бы новую модель. + +Logout удаляет ключ сессии. Повтор с тем же токеном — 401. TTL задаётся `SESSION_TTL_SECONDS`; рестарт **не продлевает** жизнь сессии. + +Токен в Redis хранится не как есть, а как `sess:`. Утечка дампа Redis не даёт сразу валидный Bearer (нужен прообраз). Это не замена TLS, но снижает ущерб от бэкапа volume. + +Если Redis недоступен в момент проверки Bearer, ответ **503**, не «ну нет сессии, пустим как анонима» и не 401 «неверный пароль». 401 означает «идентификация не принята». 503 означает «мы не можем её проверить». Путать их опасно: клиент при 401 выкинет токен, при 503 — повторит. + +--- + +## 4. Почему сессии в Redis, а не в Postgres + +Контракт разрешает оба варианта. Выбран Redis, потому что у сессии другая природа, чем у сообщения: + +- сессия — горячий ключ с TTL, частые GET на каждый запрос; +- сообщение — факт, который должен пережить годы и участвовать в JOIN/EXPLAIN; +- logout и expiry — естественный `DEL` / TTL ключа, без cron по таблице `sessions`. + +Проблема: **один TTL в памяти Redis не переживает рестарт**. Persistence-тест держит токен в памяти Python-процесса и перезапускает API **и хранилища**, volumes не трогая. Если сессии только в RAM Redis, после restart токен внезапно 401 — тест красный, хотя Postgres цел. + +Поэтому Redis запущен с **AOF** (`appendonly yes`, `appendfsync everysec`) и дополнительным RDB `save 60 1`. AOF после рестарта восстанавливает ключи **вместе с оставшимся TTL**. `everysec` — компромисс: можно потерять до ~1 с записей при crash процесса Redis, зато не платить `fsync` на каждый SET. Для учебных сессий это честная граница durability, её нужно называть на защите. + +Кэш истории живёт в том же Redis, но это **не источник истины**. Потеря кэша допустима: страница перечитывается из Postgres. Потеря сессий без AOF — уже нарушение контракта «действующая сессия переживает рестарт». + +--- + +## 5. Кэш истории и трек 5: какую ошибку мы чиним + +Контракт: после успешного POST сообщения следующее чтение через любую реплику должно его видеть. Кэш имеет право существовать, но **не имеет права отдать страницу старше успешной записи**. + +Наивный кэш `GET → Redis → иначе SQL → SET` ломается двумя способами. + +**Stale read.** Страница уже в Redis. POST пишет в Postgres и не трогает кэш. GET отдаёт старый `items` без нового сообщения. В эксперименте это воспроизводится флагом `invalidate=false`: так мы *показываем баг*, а не оставляем его в проде. Защита — версия `histver:`. Ключ страницы включает версию. После INSERT делается `INCR histver`. Старые ключи просто перестают попадать в lookup (и истекают по TTL). Не нужно SCAN/DEL всех страниц чата. + +**Cache stampede.** Истёк TTL или сменилась версия. 24 клиента одновременно делают miss. Без координации — 24 одинаковых `SELECT`. На горячем чате это бьёт в Postgres в тот момент, когда кэш как раз должен был его разгрузить. + +Singleflight: первый waiter запускает load, остальные ждут тот же `asyncio.Task` и получают тот же результат. Измерение: 24 SQL → 1 SQL при 24 конкурентных GET. Задержка 250 ms на load в lab-режиме нужна, чтобы HTTP-клиенты успели попасть в одно окно miss; без неё на localhost первый GET заполняет кэш раньше остальных, и stampede «не виден», хотя код всё ещё гоночный. + +Это in-process защита. Одна реплика lab2 — ок. На lab3 с двумя API понадобится lock в Redis (`SET NX`), иначе каждая реплика выполнит свой SQL. + +--- + +## 6. Инфраструктура: почему Compose и named volumes + +Skeleton даёт пустой `compose.example.yaml` — это список ролей, не стенд. Свой `compose.yaml` фиксирует: + +- версии образов, не `latest`; +- сеть только внутри compose: Postgres и Redis **не** публикуются на хост (API слушает `127.0.0.1:8080`); +- volumes `pg_data` / `redis_data` — данные переживают recreate контейнера; +- healthcheck: API не стартует, пока Postgres/Redis не `healthy`; `/health/ready` требует оба ping. + +`scripts/restart.sh` (на Windows — `restart.bat`) делает `docker compose restart postgres redis api` **без** `-v`. Persistence-тест не умеет отличить честный рестарт от no-op, поэтому в отчёте лежат `compose ps` до и после. + +Пул соединений ограничен (1–10) и с таймаутами: без этого при зависании Postgres запросы копятся бесконечно, а при всплеске легко исчерпать `max_connections`. + +Пароль — Argon2id, не SHA-256: SHA быстрый специально, его можно перебирать миллиардами попыток в секунду. Argon2 специально медленный и память-затратный. Параметры в этой работе учебные (`memory_cost=8192`), чтобы гонка 16 регистраций не убила контейнер на 512 MiB. В lab7 ждут более жёсткий Argon2id. + +--- + +## 7. Ошибки зависимостей + +| Ситуация | Код | Почему так | +| --- | --- | --- | +| Процесс жив, зависимости не важны | `/health/live` 200 | оркестратор не должен убивать процесс из-за рестарта Redis | +| Postgres или Redis не отвечают | `/health/ready` 503 | нельзя обещать безопасный синхронный путь | +| Bearer, Redis лежит | 503 | нельзя ни принять, ни отвергнуть сессию | +| Неверный пароль / нет токена | 401 + `WWW-Authenticate` | идентификация не удалась, сервис здоров | +| Чат чужой или не существует | 404 | 403 раскрыл бы факт существования чата | +| Username занят | 409 | конфликт уникальности, не «неверный запрос» | + +Сообщения ошибок не содержат SQL и stack trace. + +--- + +## Вопросы на защите (из README) + +### Что подтверждает COMMIT и какие гарантии зависят от настройки durability? + +`COMMIT` в PostgreSQL означает: транзакция завершена, изменения видны другим сессиям (с оговорками про уровень изоляции) и **записаны в WAL**. Это не магия «данные на диск навсегда». + +Что именно гарантировано, зависит от `synchronous_commit` и fsync: + +- по умолчанию `synchronous_commit=on`: клиент получает успех **после** сброса WAL на диск (на практике — в page cache ОС + политика fsync Postgres). После краша процесса Postgres транзакция, на которую API уже ответил 201, должна найтись после recovery. +- `synchronous_commit=off`: COMMIT возвращается раньше, можно потерять последние транзакции при crash — быстрее, слабее durability. +- Один `COMMIT` чата покрывает и чат, и членов: либо оба факта, либо ни одного. Это как раз граница транзакции в нашей схеме. + +Docker volume не равен репликации. `COMMIT` на одном диске ноутбука не спасает от `down -v` и от смерти диска. Persistence-тест доказывает другое: **контейнеры можно убить и поднять**, если volume на месте. + +Для Redis «COMMIT» в том же смысле нет. Есть запись в AOF. `appendfsync everysec` подтверждает SET клиенту, не дожидаясь fsync каждого ключа: окно потери ≈ 1 с. Это сознательная более слабая модель, чем у Postgres, и поэтому **сообщения не кладут только в Redis**. + +### Где хранятся сессии и что будет после flush/restart Redis? + +Сессия: ключ `sess:` в Redis, TTL = `SESSION_TTL_SECONDS`, payload `{user_id, expires_at}`. Пользователь, чат, текст сообщения — в Postgres. + +- **Штатный restart Redis с volume и AOF:** ключи и оставшийся TTL поднимаются. Persistence-тест и `test_redis_restart_keeps_session_and_history` это показывают. Кэш истории холодный, страницы читаются из Postgres, контракт read-after-write не ломается. +- **`FLUSHALL` / удаление volume Redis:** все сессии исчезают. Прежний Bearer → 401. Сообщения в Postgres на месте, но клиент должен войти заново. Для обязательного сценария lab2 это уже провал, если Redis — единственное хранилище сессий и persistence не включён. +- **Истёк TTL:** ключ удаляется самим Redis. Рестарт тут ни при чём и **не должен** оживлять сессию. + +Итог: Redis для сессий допустим только вместе с persistence, которая переживает проверяемый рестарт. Один TTL — это политика истечения, не сохранность. + +### Чем аутентификация отличается от доступа к конкретному чату? + +Два независимых решения, и контракт требует именно такого порядка: **сначала «кто ты», потом «можно ли этот объект»**. + +- **Аутентификация:** есть ли действительная сессия. Нет/истекла/отозвана/Redis не смогли проверить → 401 (или 503). На этом шаге чат ещё не смотрим. `X-User-Id` не аутентификация. +- **Авторизация на ресурс:** этот user_id есть в `chat_members` данного `chat_id`? Нет → **404**, не 403. 403 сказал бы клиенту: «чат существует, просто не твой». Для постороннего чат неотличим от несуществующего. + +Практический пример: Ева с валидным Bearer читает чат Алисы и Боба. Она аутентифицирована (не 401), но не член → 404. Список `GET /chats` отдаёт только её чаты. + +Создание чата: вызывающий обязан быть в `member_ids`. Это не «аутентификация», а правило состава объекта. Нарушение → 400 (некорректный список), не 401. + +### Почему hash пароля и быстрый checksum имеют разные задачи? + +Разные угрозы и разные желаемые свойства функции. + +**Password KDF (Argon2id).** Секрет, который человек помнит, короткий и угадываемый. Хеш лежит в БД. Если дамп утечёт, атакующий будет перебирать пароли. Нужна функция, которую **дорого** считать много раз: память, итерации, уникальная соль в каждом хеше. Быстрый SHA-256 здесь вреден: видеокарта перебирает миллиарды вариантов в секунду. Мы специально платим CPU на каждый login. + +**Checksum (SHA-256 файла, CRC, хеш токена в ключе Redis).** Цель — **обнаружить изменение или сделать короткий отпечаток**, не спрятать секрет от перебора. Нужна скорость и детерминизм. Для вложений в lab4 SHA-256 исходного PNG сверяет, что download = upload. Для ключа сессии SHA-256(token) — это lookup-индекс, не KDF: токен уже 256 бит случайности, его не подбирают по словарю как `qwerty123`. + +Путать их — типичная ошибка: «у нас пароли в SHA-256, как checksum файла». Checksum не задерживает атакующего. KDF не нужен, чтобы проверить целостность 10 MiB картинки. + +--- + +## Карта «проблема → решение» + +| Проблема | Решение | +| --- | --- | +| Рестарт API стирает чаты | Postgres + named volume | +| Два клиента занимают один username | UNIQUE + обработка UniqueViolation | +| Чат без части участников | Одна транзакция на chat+members | +| Пагинация сканирует всю историю | Составной индекс и keyset `(created_at, id)` | +| Клиент выдаёт себя за другого UUID | Opaque Bearer, `X-User-Id` игнорируется | +| Пароль в открытом виде / быстрый хеш | Argon2id | +| Сессия умирает вместе с Redis RAM | AOF + volume | +| GET после POST отдаёт старую страницу | Инвалидация `histver` | +| Толпа miss бьёт в одну и ту же SQL | Singleflight | +| Redis/Postgres лежат, а API врёт что готов | `/health/ready` 503; Bearer не downgrade в анонима | + +Это ровно переход lab1 → lab2: от «процесс умеет контракт» к «состояние и личность существуют отдельно от процесса и переживают его смерть». diff --git a/student_tests/__init__.py b/student_tests/__init__.py new file mode 100644 index 00000000..e69de29b diff --git a/student_tests/conftest.py b/student_tests/conftest.py new file mode 100644 index 00000000..ae6a3291 --- /dev/null +++ b/student_tests/conftest.py @@ -0,0 +1,24 @@ +import os +import sys +from pathlib import Path + +import pytest + +ROOT = Path(__file__).resolve().parents[1] +sys.path.insert(0, str(ROOT / "tests")) +from client import Client, Failure # noqa: E402 + + +@pytest.fixture(scope="session") +def base_url(): + return os.environ.get("BASE_URL", "http://127.0.0.1:8080") + + +@pytest.fixture(scope="session") +def live(base_url): + c = Client(base_url, timeout=15) + try: + c.call("GET", "/health/ready", schema="Health") + except Failure as exc: + pytest.skip("API is not ready: %s" % exc) + return c diff --git a/student_tests/test_api.py b/student_tests/test_api.py new file mode 100644 index 00000000..60971ea1 --- /dev/null +++ b/student_tests/test_api.py @@ -0,0 +1,195 @@ +"""Negative, pagination and auth tests for lab 2.""" +import uuid +from urllib.parse import quote + +from client import Client + + +PASSWORD = "Example-only-not-a-real-secret-123" + + +def register(c: Client, username=None): + username = username or ("u_" + uuid.uuid4().hex[:10]) + user = c.call( + "POST", + "/api/v1/users", + 201, + body={"username": username, "display_name": "Test User", "password": PASSWORD}, + schema="User", + )["json"] + return user + + +def login(c: Client, username, password=PASSWORD): + import base64 + + cred = base64.b64encode((username + ":" + password).encode()).decode() + session = c.call( + "POST", + "/api/v1/auth/sessions", + 201, + headers={"Authorization": "Basic " + cred}, + schema="Session", + )["json"] + return {"id": session["user"]["id"], "user": session["user"], "token": session["token"], "registration": {"username": username, "password": password}} + + +def actor_of(c: Client, username=None): + user = register(c, username) + return login(c, user["username"]) + + +def test_malformed_json(live: Client): + response = live.call( + "POST", + "/api/v1/users", + 400, + raw=b"{not-json", + headers={"Content-Type": "application/json"}, + ) + assert response["json"]["error"]["code"] == "invalid_request" + assert response["headers"].get("X-Request-Id") + + +def test_duplicate_username(live: Client): + user = register(live, username="dup_" + uuid.uuid4().hex[:8]) + again = live.call( + "POST", + "/api/v1/users", + 409, + body={"username": user["username"], "display_name": "Other", "password": PASSWORD}, + ) + assert again["json"]["error"]["code"] == "conflict" + + +def test_empty_message_rejected(live: Client): + alice = actor_of(live) + bob = actor_of(live) + chat = live.call( + "POST", + "/api/v1/chats", + 201, + actor=alice, + body={"title": "t", "member_ids": [alice["id"], bob["id"]]}, + schema="Chat", + )["json"] + response = live.call( + "POST", + "/api/v1/chats/" + chat["id"] + "/messages", + 400, + actor=alice, + body={"text": " "}, + ) + assert response["status"] == 400 + + +def test_outsider_chat_is_404(live: Client): + alice = actor_of(live) + bob = actor_of(live) + eve = actor_of(live) + chat = live.call( + "POST", + "/api/v1/chats", + 201, + actor=alice, + body={"title": "secret", "member_ids": [alice["id"], bob["id"]]}, + schema="Chat", + )["json"] + response = live.call("GET", "/api/v1/chats/" + chat["id"], 404, actor=eve) + assert response["json"]["error"]["code"] == "not_found" + + +def test_message_pagination_multiple_pages(live: Client): + alice = actor_of(live) + bob = actor_of(live) + chat = live.call( + "POST", + "/api/v1/chats", + 201, + actor=alice, + body={"title": "pages", "member_ids": [alice["id"], bob["id"]]}, + schema="Chat", + )["json"] + created = [] + for idx in range(5): + created.append(live.message(alice, chat, "m%s" % idx)["json"]) + collected = [] + cursor = None + for _ in range(10): + path = "/api/v1/chats/%s/messages?limit=2" % chat["id"] + if cursor: + path += "&cursor=" + quote(cursor, safe="") + page = live.call("GET", path, actor=bob, schema="MessagePage")["json"] + collected.extend(page["items"]) + cursor = page["next_cursor"] + if cursor is None: + break + assert len(collected) == 5 + ordered = sorted(created, key=lambda x: (x["created_at"], x["id"])) + assert collected == ordered + + +def test_cursor_from_other_chat_rejected(live: Client): + alice = actor_of(live) + bob = actor_of(live) + chat_a = live.call( + "POST", + "/api/v1/chats", + 201, + actor=alice, + body={"title": "a", "member_ids": [alice["id"], bob["id"]]}, + schema="Chat", + )["json"] + chat_b = live.call( + "POST", + "/api/v1/chats", + 201, + actor=alice, + body={"title": "b", "member_ids": [alice["id"], bob["id"]]}, + schema="Chat", + )["json"] + msg = live.message(alice, chat_a, "only in a")["json"] + page = live.call( + "GET", + "/api/v1/chats/%s/messages?limit=1" % chat_a["id"], + actor=alice, + schema="MessagePage", + )["json"] + assert page["items"][0]["id"] == msg["id"] + cursor = page["next_cursor"] + # If history is a single item, next_cursor is null; encode a foreign cursor via first page of A after a dummy extra message. + if cursor is None: + live.message(alice, chat_a, "second") + page = live.call( + "GET", + "/api/v1/chats/%s/messages?limit=1" % chat_a["id"], + actor=alice, + schema="MessagePage", + )["json"] + cursor = page["next_cursor"] + response = live.call( + "GET", + "/api/v1/chats/%s/messages?limit=10&cursor=%s" % (chat_b["id"], quote(cursor, safe="")), + 400, + actor=alice, + ) + assert response["status"] == 400 + + +def test_x_user_id_does_not_authenticate(live: Client): + alice = actor_of(live) + live.call("GET", "/api/v1/users/me", 401, headers={"X-User-Id": alice["id"]}) + + +def test_wrong_password(live: Client): + user = register(live) + import base64 + + bad = base64.b64encode((user["username"] + ":wrong-password-xx").encode()).decode() + live.call("POST", "/api/v1/auth/sessions", 401, headers={"Authorization": "Basic " + bad}) + + +def test_logout(live: Client): + alice = actor_of(live) + live.call("DELETE", "/api/v1/auth/sessions/current", 204, actor=alice) + live.call("GET", "/api/v1/users/me", 401, actor=alice) diff --git a/student_tests/test_concurrent.py b/student_tests/test_concurrent.py new file mode 100644 index 00000000..5265031e --- /dev/null +++ b/student_tests/test_concurrent.py @@ -0,0 +1,48 @@ +"""10 clients × 10 messages = 100 unique messages.""" +import threading +import uuid + +from client import Client + +from student_tests.test_api import actor_of + + +def test_concurrent_messages(live: Client): + users = [actor_of(live) for _ in range(10)] + member_ids = [u["id"] for u in users] + chat = live.call( + "POST", + "/api/v1/chats", + 201, + actor=users[0], + body={"title": "load", "member_ids": member_ids}, + schema="Chat", + )["json"] + + errors = [] + lock = threading.Lock() + + def worker(user): + local = Client(live.base, timeout=15) + for _ in range(10): + try: + local.message(user, chat, uuid.uuid4().hex) + except Exception as exc: + with lock: + errors.append(str(exc)) + + threads = [threading.Thread(target=worker, args=(u,)) for u in users] + for thread in threads: + thread.start() + for thread in threads: + thread.join(timeout=60) + + assert not errors, "unexpected failures: %s" % errors[:5] + page = live.call( + "GET", + "/api/v1/chats/%s/messages?limit=100" % chat["id"], + actor=users[0], + schema="MessagePage", + )["json"] + ids = [item["id"] for item in page["items"]] + assert len(ids) == len(set(ids)) == 100 diff --git a/student_tests/test_expiry.py b/student_tests/test_expiry.py new file mode 100644 index 00000000..da31f3c9 --- /dev/null +++ b/student_tests/test_expiry.py @@ -0,0 +1,17 @@ +import os +import time + +import pytest +from client import Client + + +@pytest.mark.expiry +def test_session_expires(live: Client): + ttl = int(os.environ.get("SESSION_TTL_SECONDS", "3600")) + if os.environ.get("RUN_EXPIRY") != "1": + pytest.skip("set RUN_EXPIRY=1 and SESSION_TTL_SECONDS<=3") + assert ttl <= 3 + actor = live.user("ttl") + live.call("GET", "/api/v1/users/me", actor=actor, schema="User") + time.sleep(ttl + 1.5) + live.call("GET", "/api/v1/users/me", 401, actor=actor) diff --git a/student_tests/test_grade4.py b/student_tests/test_grade4.py new file mode 100644 index 00000000..92ceb895 --- /dev/null +++ b/student_tests/test_grade4.py @@ -0,0 +1,44 @@ +"""Grade-4: username race and atomic chat rollback.""" +import threading +import uuid + +from client import Client + +from student_tests.test_api import PASSWORD, actor_of + + +def test_register_race(live: Client): + username = "r_" + uuid.uuid4().hex[:12] + body = {"username": username, "display_name": "Race", "password": PASSWORD} + results = [] + + def once(): + local = Client(live.base, timeout=20) + try: + results.append(local.call("POST", "/api/v1/users", [201, 409], body=body)["status"]) + except Exception as exc: + results.append(str(exc)) + + threads = [threading.Thread(target=once) for _ in range(16)] + for t in threads: + t.start() + for t in threads: + t.join() + assert results.count(201) == 1, results + assert results.count(409) == 15, results + + +def test_chat_rollback(live: Client): + alice = actor_of(live) + before = live.call("GET", "/api/v1/chats?limit=100", actor=alice, schema="ChatPage")["json"]["items"] + missing = str(uuid.uuid4()) + live.call( + "POST", + "/api/v1/chats", + 400, + actor=alice, + body={"title": "rollback-should-not-exist", "member_ids": [alice["id"], missing]}, + ) + after = live.call("GET", "/api/v1/chats?limit=100", actor=alice, schema="ChatPage")["json"]["items"] + assert len(after) == len(before) + assert all(x["title"] != "rollback-should-not-exist" for x in after) diff --git a/student_tests/test_infra.py b/student_tests/test_infra.py new file mode 100644 index 00000000..fe1a022e --- /dev/null +++ b/student_tests/test_infra.py @@ -0,0 +1,89 @@ +"""Dependency failure and Redis restart (AOF + cache rebuild).""" +import os +import subprocess +import time +from pathlib import Path + +import pytest +from client import Client, Failure + +ROOT = Path(__file__).resolve().parents[1] + + +def compose(*args): + env_file = ROOT / ".env" + cmd = ["docker", "compose"] + if env_file.is_file(): + cmd.extend(["--env-file", str(env_file)]) + cmd.extend(args) + proc = subprocess.run(cmd, cwd=ROOT, capture_output=True, text=True) + if proc.returncode != 0: + raise AssertionError("docker compose %s failed: %s" % (" ".join(args), (proc.stderr or "")[-500:])) + return proc + + +def wait_ready(c: Client, seconds=90): + deadline = time.monotonic() + seconds + last = None + while time.monotonic() < deadline: + try: + c.call("GET", "/health/ready", schema="Health") + return + except Failure as exc: + last = exc + time.sleep(0.5) + raise AssertionError("ready not restored: %s" % last) + + +def wait_status(c: Client, path, expected, seconds=30, actor=None): + deadline = time.monotonic() + seconds + last = None + while time.monotonic() < deadline: + try: + schema = "Health" if expected == 200 and path.startswith("/health") else None + c.call("GET", path, expected, actor=actor, schema=schema) + return + except Failure as exc: + last = exc + time.sleep(0.4) + raise AssertionError("did not observe %s for %s: %s" % (expected, path, last)) + + +@pytest.mark.infra +def test_redis_and_postgres_unavailable(live: Client): + if os.environ.get("RUN_INFRA") != "1": + pytest.skip("set RUN_INFRA=1 to stop compose services") + alice = live.user("infra") + compose("stop", "redis") + wait_status(live, "/health/live", 200) + wait_status(live, "/health/ready", 503) + wait_status(live, "/api/v1/users/me", 503, actor=alice) + compose("start", "redis") + wait_ready(live) + live.call("GET", "/api/v1/users/me", actor=alice, schema="User") + + compose("stop", "postgres") + wait_status(live, "/health/live", 200) + wait_status(live, "/health/ready", 503) + compose("start", "postgres") + wait_ready(live) + live.call("GET", "/api/v1/users/me", actor=alice, schema="User") + + +@pytest.mark.infra +def test_redis_restart_keeps_session_and_history(live: Client): + if os.environ.get("RUN_INFRA") != "1": + pytest.skip("set RUN_INFRA=1 to restart redis") + alice, bob, _eve, chat = live.bootstrap() + msg = live.message(alice, chat, "before-redis-restart")["json"] + compose("restart", "redis") + wait_ready(live) + me = live.call("GET", "/api/v1/users/me", actor=alice, schema="User")["json"] + assert me["id"] == alice["id"] + page = live.call( + "GET", + "/api/v1/chats/%s/messages?limit=100" % chat["id"], + actor=bob, + schema="MessagePage", + )["json"] + assert any(m["id"] == msg["id"] for m in page["items"]) diff --git a/student_tests/test_track1.py b/student_tests/test_track1.py new file mode 100644 index 00000000..d71c3192 --- /dev/null +++ b/student_tests/test_track1.py @@ -0,0 +1,83 @@ +"""Track 1: cache consistency — stampede, stale read, read-after-write.""" +import json +import threading +import uuid +from concurrent.futures import ThreadPoolExecutor + +from client import Client + + +def _lab_metrics(c: Client): + return json.loads(c.call("GET", "/api/v1/_lab/metrics")["bytes"].decode()) + + +def _lab_flags(c: Client, body): + return json.loads(c.call("POST", "/api/v1/_lab/flags", 200, body=body)["bytes"].decode()) + + +def test_read_after_write(live: Client): + alice, bob, _eve, chat = live.bootstrap() + _lab_flags(live, {"invalidate": True, "singleflight": True, "reset_sql": True}) + first = live.message(alice, chat, "raw-visible-" + uuid.uuid4().hex)["json"] + page = live.call( + "GET", + "/api/v1/chats/%s/messages?limit=100" % chat["id"], + actor=bob, + schema="MessagePage", + )["json"] + assert any(m["id"] == first["id"] for m in page["items"]) + + +def test_stale_without_invalidation_then_fixed(live: Client): + alice, bob, _eve, chat = live.bootstrap() + path = "/api/v1/chats/%s/messages?limit=50" % chat["id"] + live.call("GET", path, actor=alice, schema="MessagePage") + _lab_flags(live, {"invalidate": False, "singleflight": True}) + try: + stale_text = "stale-probe-" + uuid.uuid4().hex + live.message(alice, chat, stale_text) + page = live.call("GET", path, actor=bob, schema="MessagePage")["json"] + assert all(m["text"] != stale_text for m in page["items"]) + finally: + _lab_flags(live, {"invalidate": True}) + fresh_text = "fresh-probe-" + uuid.uuid4().hex + live.message(alice, chat, fresh_text) + page2 = live.call("GET", path, actor=bob, schema="MessagePage")["json"] + assert any(m["text"] == fresh_text for m in page2["items"]) + + +def test_stampede_singleflight_reduces_sql(live: Client): + alice, _bob, _eve, chat = live.bootstrap() + live.message(alice, chat, "stampede-seed") + path = "/api/v1/chats/%s/messages?limit=50" % chat["id"] + + def burst(n=24): + barrier = threading.Barrier(n) + + def one(_i): + local = Client(live.base) + barrier.wait() + return local.call("GET", path, actor=alice, schema="MessagePage") + + with ThreadPoolExecutor(max_workers=n) as pool: + list(pool.map(one, range(n))) + + try: + _lab_flags(live, {"singleflight": False, "invalidate": True, "reset_sql": True, "delay_ms": 250}) + live.message(alice, chat, "miss-" + uuid.uuid4().hex) + _lab_flags(live, {"reset_sql": True, "singleflight": False, "delay_ms": 250}) + burst() + unprotected = _lab_metrics(live)["history_sql"] + + _lab_flags(live, {"singleflight": True, "reset_sql": True, "delay_ms": 250}) + live.message(alice, chat, "miss2-" + uuid.uuid4().hex) + _lab_flags(live, {"reset_sql": True, "singleflight": True, "delay_ms": 250}) + burst() + protected = _lab_metrics(live)["history_sql"] + finally: + _lab_flags(live, {"invalidate": True, "singleflight": True, "delay_ms": 0}) + + print(json.dumps({"stampede_sql_without_singleflight": unprotected, "stampede_sql_with_singleflight": protected})) + assert unprotected >= 8, unprotected + assert protected < unprotected, (protected, unprotected) + assert protected <= 4, protected