From e914e384fc233c147867ca5f1224b6983e0101c3 Mon Sep 17 00:00:00 2001 From: Ilya <145450507+IIcon18@users.noreply.github.com> Date: Wed, 7 Oct 2026 18:28:12 +0300 Subject: [PATCH 1/3] =?UTF-8?q?=D0=B2=D1=8B=D0=BF=D0=BE=D0=BB=D0=BD=D0=B5?= =?UTF-8?q?=D0=BD=D0=B8=D0=B5=20=D0=BB=D1=802=20=D0=BD=D0=B0=204?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .env.example | 6 + Dockerfile | 23 +++ Makefile | 18 +- REPORT.md | 133 +++++++++++-- app/__init__.py | 0 app/auth.py | 122 ++++++++++++ app/cache.py | 102 ++++++++++ app/config.py | 46 +++++ app/errors.py | 24 +++ app/main.py | 234 +++++++++++++++++++++++ app/migrate.py | 68 +++++++ app/models.py | 73 ++++++++ app/storage.py | 288 +++++++++++++++++++++++++++++ compose.yaml | 100 ++++++++++ evidence/explain_history.txt | 74 ++++++++ evidence/fresh_migrations.txt | 20 ++ evidence/persistence.txt | 20 ++ evidence/smoke.txt | 5 + evidence/student_tests.txt | 44 +++++ migrations/0001_init.sql | 58 ++++++ requirements.txt | 6 + scripts/init-secrets.sh | 32 ++++ scripts/restart.sh | 12 ++ student-tests/auth_test.py | 70 +++++++ student-tests/concurrency_test.py | 61 ++++++ student-tests/db_integrity_test.py | 53 ++++++ student-tests/dependency_test.py | 86 +++++++++ student-tests/explain_history.sh | 81 ++++++++ student-tests/own_tests.py | 120 ++++++++++++ student-tests/run_all.sh | 24 +++ student-tests/sigterm_test.sh | 19 ++ student-tests/stack.py | 47 +++++ 32 files changed, 2054 insertions(+), 15 deletions(-) create mode 100644 Dockerfile create mode 100644 app/__init__.py create mode 100644 app/auth.py create mode 100644 app/cache.py create mode 100644 app/config.py create mode 100644 app/errors.py create mode 100644 app/main.py create mode 100644 app/migrate.py create mode 100644 app/models.py create mode 100644 app/storage.py create mode 100644 compose.yaml create mode 100644 evidence/explain_history.txt create mode 100644 evidence/fresh_migrations.txt create mode 100644 evidence/persistence.txt create mode 100644 evidence/smoke.txt create mode 100644 evidence/student_tests.txt create mode 100644 migrations/0001_init.sql create mode 100644 requirements.txt create mode 100755 scripts/init-secrets.sh create mode 100755 scripts/restart.sh create mode 100755 student-tests/auth_test.py create mode 100755 student-tests/concurrency_test.py create mode 100755 student-tests/db_integrity_test.py create mode 100755 student-tests/dependency_test.py create mode 100755 student-tests/explain_history.sh create mode 100755 student-tests/own_tests.py create mode 100755 student-tests/run_all.sh create mode 100755 student-tests/sigterm_test.sh create mode 100755 student-tests/stack.py diff --git a/.env.example b/.env.example index 714c8076..623ea676 100644 --- a/.env.example +++ b/.env.example @@ -9,3 +9,9 @@ DATABASE_URL_FILE=/run/secrets/database_url # Optional on 3, required use on 4 in lab2; Redis OR Valkey: SESSION_STORE=postgres CACHE_URL_FILE=/run/secrets/cache_url +# --- Actual lab2 implementation (see REPORT.md) --- +# APP_PORT is also the host port published on 127.0.0.1 by compose.yaml. +# SESSION_STORE=postgres: sessions live in PostgreSQL; Valkey (CACHE_URL_FILE) caches lookups. +SESSION_CACHE_MAX_SECONDS=300 +DB_POOL_MAX=10 +SHORT_TTL_PORT=8081 diff --git a/Dockerfile b/Dockerfile new file mode 100644 index 00000000..4b94588c --- /dev/null +++ b/Dockerfile @@ -0,0 +1,23 @@ +FROM python:3.12.8-slim-bookworm + +WORKDIR /app + +COPY requirements.txt . +RUN pip install --no-cache-dir -r requirements.txt + +COPY app ./app +COPY migrations ./migrations + +RUN useradd --system --no-create-home --uid 10001 appuser +USER appuser + +ENV APP_HOST=0.0.0.0 \ + APP_PORT=8080 \ + PYTHONUNBUFFERED=1 + +EXPOSE 8080 + +HEALTHCHECK --interval=10s --timeout=3s --start-period=5s --retries=3 \ + CMD python -c "import os,urllib.request,sys; sys.exit(0 if urllib.request.urlopen('http://127.0.0.1:'+os.environ.get('APP_PORT','8080')+'/health/ready',timeout=2).status==200 else 1)" + +CMD ["sh", "-c", "exec uvicorn app.main:app --host ${APP_HOST} --port ${APP_PORT} --timeout-graceful-shutdown 8"] diff --git a/Makefile b/Makefile index 9ecb223e..51336484 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 secrets up down test-student explain help: @echo "check: offline structure; validate: full OpenAPI (requirements-dev.txt); test: running API; load: synthetic writes" @@ -24,3 +24,19 @@ load: 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) + +# --- Student implementation helpers (see REPORT.md) --- +secrets: + sh scripts/init-secrets.sh + +up: secrets + docker compose up -d --build --wait + +down: + docker compose --profile ttl-test down + +test-student: + BASE_URL="$(BASE_URL)" sh student-tests/run_all.sh + +explain: + sh student-tests/explain_history.sh diff --git a/REPORT.md b/REPORT.md index e42f2b05..4767fe8c 100644 --- a/REPORT.md +++ b/REPORT.md @@ -1,37 +1,142 @@ # Отчёт — лабораторная 2 - Автор, группа: TODO -- Целевая оценка; выбранный трек 5, если нужен: TODO +- Целевая оценка: **4** (трек 5 не заявлен) - Commit/PR: TODO после публикации -- Использованные источники, библиотеки и помощь ИИ: TODO +- Использованные источники, библиотеки и помощь ИИ: FastAPI, uvicorn, pydantic, asyncpg, redis-py (клиент к Valkey), argon2-cffi; документация PostgreSQL (transactions, EXPLAIN), Valkey persistence, RFC 7617. Код lab1 перенесён из собственного решения. При переносе на PostgreSQL, написании тестов и отчёта использовался ИИ-ассистент Claude (Anthropic); решения проверены и объяснимы автором. ## Запуск из чистого clone -TODO: версии runtime/образов, prerequisites, команды создания локальных secrets/.env, build, миграций, запуска, ожидания готовности, тестов и остановки. Указать необходимые действия оператора. Не вставлять секреты. Отдельно указать безопасную остановку и команду намеренного удаления учебных данных. +Требования: Docker Engine с Compose v2 (проверено: Docker 28.0.1, Compose 2.33.1), Python 3.9+ для тестов (проверено на 3.14), `make`. + +| Роль | Образ | Версия | +| --- | --- | --- | +| api / migrate | `mtusi-messenger:lab2`, сборка из `Dockerfile` | `python:3.12.8-slim-bookworm`, зависимости закреплены в `requirements.txt` | +| postgres | `postgres:17.6-alpine3.22` | PostgreSQL 17.6 | +| valkey | `valkey/valkey:8.1.4-alpine3.22` | Valkey 8.1.4 | + +```sh +cp .env.example .env # при занятом 8080 поменять APP_PORT (у автора 18080) +make secrets # scripts/init-secrets.sh: случайные пароли в ./secrets (в .gitignore) +docker compose --env-file .env config --quiet +make up # docker compose up -d --build --wait: postgres -> migrate -> api; ждёт healthcheck /health/ready +make check +make test BASE_URL=http://localhost:8080 +make test-persistence ACTION_SCRIPT=scripts/restart.sh BASE_URL=http://localhost:8080 +make test-student BASE_URL=http://localhost:8080 # собственные тесты; останавливает/запускает контейнеры +make explain # засев 70 000 синтетических сообщений + EXPLAIN +``` + +- Миграции: отдельный одноразовый сервис `migrate` (`python -m app.migrate`). API стартует только после его успешного завершения. Повторный запуск безопасен (`schema_migrations` + `pg_advisory_lock`). +- Безопасная остановка без потери данных: `make down` (= `docker compose --profile ttl-test down`, volume `pgdata` сохраняется). +- **Намеренное удаление учебных данных:** `docker compose --profile ttl-test down -v` (удаляет volume `messenger-lab2_pgdata`; необратимо). +- Действия оператора: только `make secrets` перед первым запуском. Секреты в образ и Git не попадают. ## Архитектура и решения -TODO: схема процессов/хранилищ, источник истины, транзакционные границы, ограничения. Что перенесено из lab1, что изменено в этой работе. Соответствие переменных из .env.example реальной конфигурации. +``` +клиент ──HTTP──> api (FastAPI/uvicorn, 1 процесс) + ├──> postgres : источник истины — users, chats, chat_members, messages, sessions + └──> valkey : кэш поиска сессии (только ускорение, может пропасть в любой момент) +migrate (one-shot) ──> postgres : применение migrations/*.sql +``` + +**Перенесено из lab1:** модели pydantic, формат ошибок и `X-Request-Id`, keyset-курсор, привязанный к ресурсу, проверки контракта (пустой текст, дубликаты участников, 404 на чужой чат), Dockerfile (non-root, graceful SIGTERM). In-memory `Store` заменён на репозиторий PostgreSQL (`app/storage.py`). + +**Изменено по контракту lab2:** `password` при регистрации, `POST /auth/sessions` через Basic, Bearer на всех бизнес-endpoint, `DELETE /auth/sessions/current`. `X-User-Id` не читается вообще. + +### Схема БД (`migrations/0001_init.sql`) + +| Таблица | Ключи и ограничения | Индексы | +| --- | --- | --- | +| users | PK id; `UNIQUE(username)`; CHECK формата username и длины display_name | уникальный по username | +| chats | PK id; CHECK длины title | — | +| chat_members | PK (chat_id, user_id); FK на chats и users; `position` хранит порядок member_ids | `(user_id, chat_id)` для списка чатов пользователя | +| messages | PK id; **FK (chat_id, sender_id) → chat_members**: отправитель обязан быть участником на уровне БД; CHECK длины текста | `(chat_id, created_at, id)` для истории | +| sessions | PK token_hash (sha256 токена, сам токен не хранится); FK user_id; expires_at, revoked_at | `(expires_at)` | + +Время (`created_at`, `expires_at`) назначает PostgreSQL (`clock_timestamp()`), в API выдаётся RFC 3339 UTC с микросекундами. Порядок `(created_at, id)`; сравнение uuid в PostgreSQL побайтовое и совпадает с порядком UUID-int в тестах. + +### Транзакционные границы + +- **Создание чата** — одна транзакция: `INSERT chats` + `INSERT chat_members … FROM unnest($2::uuid[])`. Неизвестный участник отлавливает FK внутри транзакции → `ROLLBACK` → 400. Предварительного SELECT нет, поэтому откат реально выполняется (тест `db_integrity_test.py`). +- **Регистрация** — один `INSERT`; гонку одинаковых username решает `UNIQUE` (`UniqueViolationError` → 409), а не проверка «SELECT, потом INSERT». +- **Отправка сообщения** — одна инструкция `INSERT … SELECT … WHERE EXISTS(участник)`: проверка доступа и запись атомарны. +- **Logout** — `UPDATE sessions SET revoked_at` (истина), затем надгробие в Valkey. +- `COMMIT` подтверждает запись в WAL; при настройках по умолчанию (`fsync=on`, `synchronous_commit=on`) подтверждённое сообщение переживает падение процесса PostgreSQL. Ответ 201 отправляется только после COMMIT. + +### Аутентификация и сессии + +- Пароль: **Argon2id** (argon2-cffi, профиль RFC 9106 low-memory: t=3, m=64 MiB, p=4). Хеширование в thread pool, не более 4 одновременно (`PASSWORD_HASH_CONCURRENCY`), чтобы ограничить RAM. Для несуществующего username проверяется фиктивный хеш, поэтому время ответа одинаковое. +- Basic разбирается строго: base64 → UTF-8 → разделение по **первому** `:` (двоеточие в пароле допустимо), username только ASCII, пароль 12–128 code points. Любая ошибка даёт одинаковый 401 с `WWW-Authenticate: Basic realm="messenger", charset="UTF-8"`. +- Токен — `secrets.token_urlsafe(32)` (256 бит). В БД и кэше хранится только `sha256(token)`. Быстрый хеш здесь уместен: токен случайный, перебирать его бессмысленно, в отличие от человеческого пароля, которому нужен медленный KDF. +- Срок жизни `SESSION_TTL_SECONDS` (по умолчанию 3600) задаётся в БД как `expires_at`, поэтому рестарт его не продлевает. + +### Роль Valkey (уровень 4): кэш сессий + +- **Источник истины — PostgreSQL.** Valkey хранит `session:` → `{user, expires_at}`, чтобы не ходить в БД на каждом запросе; `/users/me` обслуживается вообще без БД. +- **Expiry:** TTL записи = `min(остаток сессии, SESSION_CACHE_MAX_SECONDS=300)`, плюс при чтении из кэша сравнивается `expires_at`. Просроченная сессия не принимается ни из кэша, ни из БД. +- **Инвалидация:** при logout сначала `revoked_at` в PostgreSQL, затем в Valkey пишется **надгробие** `revoked` (а не DEL). Заполнение кэша идёт через `SET NX`, поэтому параллельный запрос, прочитавший БД до отзыва, не сможет вернуть сессию в кэш. +- **Persistence не нужна и выключена** (`save ""`, `appendonly no`): после flush или рестарта Valkey первая проверка идёт в PostgreSQL. Потеря кэша ничего не ломает, это подтверждает тест сохранности, где Valkey тоже перезапускается. +- **Отказ Valkey:** таймаут 0.3 с, затем circuit breaker на 5 с, в течение которых кэш не используется. Readiness при этом остаётся 200: Valkey не критичен. +- Конфигурация с `requirepass` лежит в секрете `secrets/valkey.conf`, порт наружу не публикуется. + +### Устойчивость к отказам + +- asyncpg pool: `max_size=10`, таймауты подключения 3 с, захвата соединения 3 с, команды 5 с. `min_size=0` позволяет API стартовать при недоступной БД (тогда readiness = 503). +- Недоступность или рестарт PostgreSQL (`OSError`, `PostgresConnectionError`, `InterfaceError`, `TooManyConnections`, admin shutdown, statement timeout) превращается в `503 unavailable` без деталей. Без токена по-прежнему 401. Токен, который нельзя проверить (нет в кэше, БД недоступна), получает 503 и **никогда** не считается аутентифицированным. +- Readiness: 200 только при успешном `SELECT 1` в PostgreSQL. Liveness всегда 200. +- Все SQL-запросы параметризованы (`$1…`), строк, склеенных из пользовательского ввода, нет. + +### Переменные `.env.example` → реальная конфигурация + +| Переменная | Где используется | +| --- | --- | +| APP_HOST / APP_PORT | uvicorn внутри контейнера слушает 0.0.0.0:8080; `APP_PORT` в `.env` — порт хоста (`127.0.0.1:${APP_PORT}`) | +| APP_ENV | передаётся в контейнер, логики не меняет | +| SESSION_TTL_SECONDS | срок сессии; у `api-short-ttl` = 2 | +| DATABASE_URL_FILE | `/run/secrets/database_url` (compose secret из `secrets/database_url`) | +| SESSION_STORE=postgres | сессии хранятся в PostgreSQL | +| CACHE_URL_FILE | `/run/secrets/cache_url`, URL Valkey; без него кэш отключён | +| SESSION_CACHE_MAX_SECONDS, DB_POOL_MAX, SHORT_TTL_PORT | добавлены этой работой (см. выше) | ## Доказательства критериев +Все файлы в `evidence/` сняты 2026-10-07 на MacBook (Apple Silicon, Docker Desktop, без CPU/RAM-лимитов в compose). Порт стенда автора — 18080, потому что 8080 занят другим проектом. + | Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства | | --- | --- | --- | --- | -| Публичный smoke | make test | TODO | TODO | -| Остальные пункты уровня 3 | TODO | TODO | TODO | -| Все пункты уровня 4, если заявлен | TODO | TODO | TODO | -| Выбранный трек 5, если заявлен | TODO | TODO | TODO | - -TODO: добавить отдельную строку для каждого заявленного критерия. PASS без команды и наблюдения не является доказательством. Проверка инфраструктурного hook требует подтверждения, какие реальные процессы/хранилища перезапущены. +| Публичный smoke | `make check`, `make test` | PASS обоих | `evidence/smoke.txt` | +| 3: данные и сессии переживают рестарт API **и хранилищ** | `make test-persistence ACTION_SCRIPT=scripts/restart.sh` | PASS; `StartedAt` api/postgres/valkey изменились, volume тот же, тот же токен читает данные | `evidence/persistence.txt` | +| 3: миграции с нуля и повторно | `docker compose -p lab2-clean up` на пустом volume, затем ещё `run migrate` | `1 applied now, 0 before`, затем `0 applied now, 1 before`; smoke PASS на новом стенде | `evidence/fresh_migrations.txt` | +| 3: PK/FK, UNIQUE username, атомарное создание чата | `student-tests/db_integrity_test.py` | чат с неизвестным участником → 400, в `chats` 0 строк с этим title и 0 чатов без участников | `evidence/student_tests.txt` | +| 3: Basic только на /auth/sessions, Bearer, X-User-Id игнорируется, logout, KDF | `auth_test.py`, smoke, `db_integrity_test.py` | Basic/X-User-Id на бизнес-endpoint → 401; повторный logout → 401; hash начинается с `$argon2id$` | `evidence/student_tests.txt` | +| 3: secrets/volumes не в Git | `git status`, `.gitignore` (`secrets/`, `.env`) | секреты только в `./secrets`, в репозитории нет | `.gitignore` | +| 4: Valkey реально используется, TTL, инвалидация | `dependency_test.py` | ключи `session:*` с TTL ≤ 300, после logout значение `revoked` | `evidence/student_tests.txt` | +| 4: параметризованные запросы, ограниченный pool, таймауты | код `app/storage.py`, `app/config.py` | `$n`-параметры, `max_size=10`, таймауты 3/3/5 с | — | +| 4: гонка регистрации | `db_integrity_test.py` | 20 параллельных запросов → 1×201, 19×409, 1 строка | `evidence/student_tests.txt` | +| 4: rollback составной операции | `db_integrity_test.py` | см. строку «атомарное создание чата» | `evidence/student_tests.txt` | +| 4: индекс истории + EXPLAIN на ≥10 000 | `make explain` | 70 000 сообщений, в чате 20 000; с индексом Index Scan, 4 буфера, 0.03 мс на первой и глубокой (#15000) странице; без индекса Seq Scan + Sort, 940 буферов, 3–4 мс | `evidence/explain_history.txt` | +| 4: expiry при коротком TTL | `auth_test.py` против `api-short-ttl` (TTL=2) | через 3 с → 401 (и из кэша) | `evidence/student_tests.txt` | +| 4: logout, неверный пароль | `auth_test.py` | неверный пароль и неизвестный user дают одинаковый 401 | `evidence/student_tests.txt` | +| 4: недоступность Redis/БД | `dependency_test.py` | Valkey stop: ready=200, запросы ~4 мс; PostgreSQL stop: live=200, ready и бизнес-запросы 503 мгновенно, непроверенный токен → 503, без токена 401; после start всё восстанавливается без рестарта API | `evidence/student_tests.txt` | +| Graceful shutdown (из lab1) | `sigterm_test.sh` | `docker compose stop api` → exit 0 за < 1 с | `evidence/student_tests.txt` | ## Эксперименты и отказы -TODO: гипотеза, hardware/лимиты, версии, объём данных, профиль нагрузки, concurrency/arrival rate, длительность/прогрев, повторы, успешные RPS, ошибки, p50/p95/p99, CPU/RAM. Сохранить raw summary без tokens и объяснить ограничения измерения. - | Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных | | --- | --- | --- | --- | -| TODO | TODO | TODO | TODO | +| `scripts/restart.sh`: stop api, valkey, postgres → up | данные и сессия на месте, токен тот же | PASS, кэш пустой, сессии берутся из PostgreSQL | ~11 с весь hook / потерь нет | +| `docker compose stop valkey` | API работает без кэша | 200, ~4 мс на запрос (breaker), revoked-токен 401 | мгновенно / потерь нет (кэш) | +| `docker compose stop postgres` | 503 без зависаний, анонимный доступ не появляется | ready 503, бизнес 503, live 200, всё за < 0.1 с | API восстанавливается сам после `start postgres`, без своего рестарта; подтверждённые данные целы | +| SIGTERM api | graceful exit 0 | exit 0, «Application shutdown complete» | `docker compose up -d --wait api` | ## Ограничения и следующие шаги -TODO: какие отказы выдерживаются и какие нет; что не реализовано; где учебное упрощение; какое улучшение подтверждено, а какое пока гипотеза. +- Один Docker-host, по одному PostgreSQL и Valkey, без репликации: потеря host или диска = потеря сервиса (бэкапы не настроены, это трек 2 пятёрки). +- Если logout пришёлся на момент сетевой недоступности Valkey, а сам Valkey при этом не перезапускался, старая запись в кэше может жить до `SESSION_CACHE_MAX_SECONDS` (≤ 5 мин). Это осознанная граница: TTL кэша ограничен именно поэтому. +- Просроченные строки `sessions` не удаляются автоматически (есть индекс `expires_at` для будущей периодической очистки). +- `/health/ready` не проверяет Valkey намеренно. +- Тело запроса проверяется до аутентификации: на неавторизованный запрос с битым JSON вернётся 400, а не 401 (особенность FastAPI). Это не раскрывает данных. +- `make test` создаёт синтетических пользователей при каждом запуске; удаления в API нет. +- Нагрузочное измерение (`make load`) не делалось: для уровня 4 не требуется. diff --git a/app/__init__.py b/app/__init__.py new file mode 100644 index 00000000..e69de29b diff --git a/app/auth.py b/app/auth.py new file mode 100644 index 00000000..259e3a11 --- /dev/null +++ b/app/auth.py @@ -0,0 +1,122 @@ +"""Passwords (Argon2id), Basic login and opaque Bearer sessions.""" +from __future__ import annotations + +import asyncio +import base64 +import binascii +import hashlib +import secrets +from datetime import datetime, timezone +from typing import Optional, Tuple + +from argon2 import PasswordHasher +from argon2.exceptions import InvalidHashError, VerificationError +from starlette.concurrency import run_in_threadpool + +from app import config +from app.cache import REVOKED, SessionCache +from app.errors import BASIC_CHALLENGE, unauthorized +from app.storage import Store, fmt_ts, user_row + +# argon2-cffi defaults = RFC 9106 low-memory profile (Argon2id, t=3, m=64 MiB, p=4). +_hasher = PasswordHasher() +_hash_slots = asyncio.Semaphore(config.PASSWORD_HASH_CONCURRENCY) +# Verified when the username does not exist, so both failures cost the same time. +_DUMMY_HASH = _hasher.hash("dummy-password-for-timing") + + +async def hash_password(password: str) -> str: + async with _hash_slots: + return await run_in_threadpool(_hasher.hash, password) + + +async def verify_password(password_hash: str, password: str) -> bool: + def verify() -> bool: + try: + return _hasher.verify(password_hash, password) + except (VerificationError, InvalidHashError): + return False + + async with _hash_slots: + return await run_in_threadpool(verify) + + +def token_digest(token: str) -> bytes: + # A fast hash is enough here: the token already carries 256 random bits, + # unlike a human password that needs a slow KDF against guessing. + return hashlib.sha256(token.encode("ascii")).digest() + + +def parse_basic(header: Optional[str]) -> Tuple[str, str]: + bad = unauthorized("invalid credentials", BASIC_CHALLENGE) + if not header: + raise bad + scheme, _, value = header.partition(" ") + if scheme.lower() != "basic" or not value.strip(): + raise bad + try: + decoded = base64.b64decode(value.strip(), validate=True).decode("utf-8") + except (binascii.Error, UnicodeDecodeError): + raise bad from None + username, sep, password = decoded.partition(":") # the password may contain ':' + if not sep or not username.isascii() or not 12 <= len(password) <= 128: + raise bad + return username, password + + +def parse_bearer(header: Optional[str]) -> str: + if not header: + raise unauthorized("bearer token required") + scheme, _, token = header.partition(" ") + token = token.strip() + if scheme.lower() != "bearer" or not token or not token.isascii() or len(token) > 256: + raise unauthorized("bearer token required") + return token + + +async def login(store: Store, header: Optional[str]) -> dict: + username, password = parse_basic(header) + row = await store.get_credentials(username) + if row is None: + await verify_password(_DUMMY_HASH, password) + raise unauthorized("invalid credentials", BASIC_CHALLENGE) + if not await verify_password(row["password_hash"], password): + raise unauthorized("invalid credentials", BASIC_CHALLENGE) + token = secrets.token_urlsafe(32) # 256 bits of entropy + expires_at = await store.create_session(token_digest(token), row["id"], config.SESSION_TTL_SECONDS) + return {"token": token, "token_type": "Bearer", "expires_at": fmt_ts(expires_at), "user": user_row(row)} + + +async def authenticate(store: Store, cache: SessionCache, header: Optional[str]) -> dict: + """Return the session's user or raise 401. Cache first, PostgreSQL on a miss. + + If PostgreSQL is down and the cache has no answer the error propagates as 503: + an unverifiable token is never treated as authenticated.""" + digest = token_digest(parse_bearer(header)) + cached = await cache.get(digest) + if cached == REVOKED: + raise unauthorized("session expired or revoked") + if isinstance(cached, dict): + expires_at = datetime.fromisoformat(cached["expires_at"].replace("Z", "+00:00")) + if expires_at > datetime.now(timezone.utc): + return cached["user"] + raise unauthorized("session expired or revoked") + + row = await store.find_session(digest) + if row is None: + raise unauthorized("session expired or revoked") + user = user_row(row) + remaining = int((row["expires_at"] - datetime.now(timezone.utc)).total_seconds()) + await cache.put(digest, {"user": user, "expires_at": fmt_ts(row["expires_at"])}, remaining) + return user + + +async def logout(store: Store, cache: SessionCache, header: Optional[str]) -> None: + # Authenticate first so an already revoked token gets 401, as the contract requires. + await authenticate(store, cache, header) + digest = token_digest(parse_bearer(header)) + expires_at = await store.revoke_session(digest) # PostgreSQL first: it is the truth + if expires_at is None: + raise unauthorized("session expired or revoked") + remaining = int((expires_at - datetime.now(timezone.utc)).total_seconds()) + 1 + await cache.revoke(digest, remaining) diff --git a/app/cache.py b/app/cache.py new file mode 100644 index 00000000..c0da5ab2 --- /dev/null +++ b/app/cache.py @@ -0,0 +1,102 @@ +"""Valkey session cache. Never the source of truth: every failure degrades to a miss. + +Keys: session: +Value: JSON {"user": {...}, "expires_at": "..."} - a valid session + "revoked" - tombstone written by logout +Entry TTL = min(time left in the session, SESSION_CACHE_MAX_SECONDS). +""" +from __future__ import annotations + +import json +import logging +import time +from typing import Optional, Union + +import redis.asyncio as redis +from redis.exceptions import RedisError + +from app import config + +logger = logging.getLogger("messenger.cache") + +REVOKED = "revoked" + + +class SessionCache: + def __init__(self, url: Optional[str]): + self._client: Optional[redis.Redis] = None + self._down_until = 0.0 + if url: + pool = redis.BlockingConnectionPool.from_url( + url, + max_connections=config.CACHE_POOL_MAX, + timeout=config.CACHE_TIMEOUT, + socket_timeout=config.CACHE_TIMEOUT, + socket_connect_timeout=config.CACHE_TIMEOUT, + decode_responses=True, + ) + self._client = redis.Redis(connection_pool=pool) + + @property + def enabled(self) -> bool: + return self._client is not None + + def _usable(self) -> bool: + return self._client is not None and time.monotonic() >= self._down_until + + def _failed(self, op: str, exc: Exception) -> None: + # Circuit breaker: one slow failure, then skip the cache for a few seconds. + self._down_until = time.monotonic() + config.CACHE_RETRY_AFTER + logger.warning("cache %s failed (%s); bypassing cache for %.0fs", op, type(exc).__name__, config.CACHE_RETRY_AFTER) + + @staticmethod + def _key(token_hash: bytes) -> str: + return "session:" + token_hash.hex() + + async def get(self, token_hash: bytes) -> Union[dict, str, None]: + if not self._usable(): + return None + try: + raw = await self._client.get(self._key(token_hash)) + except (RedisError, OSError) as exc: + self._failed("get", exc) + return None + if raw is None or raw == REVOKED: + return raw + try: + return json.loads(raw) + except ValueError: + return None + + async def put(self, token_hash: bytes, entry: dict, ttl_seconds: int) -> None: + """Fill after a PostgreSQL read. NX: never overwrite a logout tombstone.""" + ttl = min(ttl_seconds, config.SESSION_CACHE_MAX_SECONDS) + if ttl <= 0 or not self._usable(): + return + try: + await self._client.set(self._key(token_hash), json.dumps(entry), ex=ttl, nx=True) + except (RedisError, OSError) as exc: + self._failed("set", exc) + + async def revoke(self, token_hash: bytes, ttl_seconds: int) -> None: + """Tombstone instead of DEL: a concurrent fill that read PostgreSQL before the + revoke cannot re-insert the session afterwards (its SET NX loses). + Tried even while the breaker is open: logout is rare and correctness matters more.""" + if self._client is None: + return + try: + await self._client.set(self._key(token_hash), REVOKED, ex=max(1, min(ttl_seconds, config.SESSION_CACHE_MAX_SECONDS))) + except (RedisError, OSError) as exc: + self._failed("revoke", exc) + + async def ping(self) -> bool: + if self._client is None: + return False + try: + return bool(await self._client.ping()) + except (RedisError, OSError): + return False + + async def close(self) -> None: + if self._client is not None: + await self._client.aclose() diff --git a/app/config.py b/app/config.py new file mode 100644 index 00000000..a651d4bd --- /dev/null +++ b/app/config.py @@ -0,0 +1,46 @@ +"""Runtime configuration from environment; secrets are read from *_FILE paths.""" +from __future__ import annotations + +import os +from typing import Optional + + +def _secret(name: str) -> Optional[str]: + """NAME wins over NAME_FILE; NAME_FILE keeps the value out of `docker inspect`.""" + value = os.environ.get(name) + if value: + return value.strip() + path = os.environ.get(name + "_FILE") + if path and os.path.exists(path): + with open(path, encoding="utf-8") as fh: + return fh.read().strip() or None + return None + + +def _int(name: str, default: int) -> int: + return int(os.environ.get(name, default)) + + +def _float(name: str, default: float) -> float: + return float(os.environ.get(name, default)) + + +DATABASE_URL = _secret("DATABASE_URL") +CACHE_URL = _secret("CACHE_URL") + +SESSION_TTL_SECONDS = _int("SESSION_TTL_SECONDS", 3600) +# Upper bound for one cached session entry; PostgreSQL is re-checked after it. +SESSION_CACHE_MAX_SECONDS = _int("SESSION_CACHE_MAX_SECONDS", 300) + +DB_POOL_MAX = _int("DB_POOL_MAX", 10) +DB_CONNECT_TIMEOUT = _float("DB_CONNECT_TIMEOUT", 3) +DB_ACQUIRE_TIMEOUT = _float("DB_ACQUIRE_TIMEOUT", 3) +DB_COMMAND_TIMEOUT = _float("DB_COMMAND_TIMEOUT", 5) + +CACHE_TIMEOUT = _float("CACHE_TIMEOUT", 0.3) +CACHE_POOL_MAX = _int("CACHE_POOL_MAX", 20) +# After a cache error, skip the cache for this long instead of paying the timeout per request. +CACHE_RETRY_AFTER = _float("CACHE_RETRY_AFTER", 5) + +# Argon2id hashing is CPU/RAM heavy: bound how many run at once. +PASSWORD_HASH_CONCURRENCY = _int("PASSWORD_HASH_CONCURRENCY", 4) diff --git a/app/errors.py b/app/errors.py new file mode 100644 index 00000000..97933e98 --- /dev/null +++ b/app/errors.py @@ -0,0 +1,24 @@ +"""API error type shared by all layers.""" +from __future__ import annotations + +from typing import Dict, Optional + +BEARER_CHALLENGE = 'Bearer realm="messenger"' +BASIC_CHALLENGE = 'Basic realm="messenger", charset="UTF-8"' + + +class ApiError(Exception): + def __init__(self, status_code: int, code: str, message: str, headers: Optional[Dict[str, str]] = None): + super().__init__(message) + self.status_code = status_code + self.code = code + self.message = message + self.headers = headers or {} + + +def unauthorized(message: str, challenge: str = BEARER_CHALLENGE) -> ApiError: + return ApiError(401, "unauthorized", message, {"WWW-Authenticate": challenge}) + + +def unavailable() -> ApiError: + return ApiError(503, "unavailable", "service temporarily unavailable") diff --git a/app/main.py b/app/main.py new file mode 100644 index 00000000..8ada91fc --- /dev/null +++ b/app/main.py @@ -0,0 +1,234 @@ +"""Lab 2: messenger API on PostgreSQL with Bearer sessions and a Valkey session cache.""" +from __future__ import annotations + +import logging +import uuid +from contextlib import asynccontextmanager +from typing import Optional + +import asyncpg +from fastapi import Depends, FastAPI, Query, Request, Response +from fastapi.exceptions import RequestValidationError +from fastapi.responses import JSONResponse +from starlette.exceptions import HTTPException as StarletteHTTPException + +from app import auth, config +from app.cache import SessionCache +from app.errors import ApiError +from app.models import Chat, ChatPage, CreateChat, CreateMessage, CreateUser, Health, Message, MessagePage, Session, User +from app.storage import Store + +logging.basicConfig(level=logging.INFO) +logger = logging.getLogger("messenger") + +store = Store() +cache = SessionCache(config.CACHE_URL) + + +@asynccontextmanager +async def lifespan(_app: FastAPI): + if not config.DATABASE_URL: + raise RuntimeError("DATABASE_URL or DATABASE_URL_FILE is required") + await store.open() + logger.info("session cache: %s", "valkey" if cache.enabled else "disabled") + yield + await cache.close() + await store.close() + + +app = FastAPI(title="MTUSI Messenger — lab2", lifespan=lifespan) + + +# --------------------------------------------------------------------------- +# Cross-cutting: request id + uniform error envelope +# --------------------------------------------------------------------------- + +# PostgreSQL unreachable, restarting or pool exhausted -> bounded 503, never a hang. +DB_UNAVAILABLE = ( + OSError, # includes ConnectionRefusedError and TimeoutError (pool acquire / connect) + asyncpg.PostgresConnectionError, + asyncpg.InterfaceError, + asyncpg.TooManyConnectionsError, + asyncpg.exceptions.OperatorInterventionError, # admin shutdown, cannot connect now + asyncpg.exceptions.QueryCanceledError, # statement timeout +) + + +def error_body(code: str, message: str, request_id: str) -> dict: + return {"error": {"code": code, "message": message, "request_id": request_id}} + + +def error_response(request: Request, status: int, code: str, message: str, headers: Optional[dict] = None) -> JSONResponse: + request_id = getattr(request.state, "request_id", "") + return JSONResponse(status_code=status, content=error_body(code, message, request_id), headers=headers) + + +@app.middleware("http") +async def request_id_middleware(request: Request, call_next): + request_id = uuid.uuid4().hex + request.state.request_id = request_id + try: + response = await call_next(request) + except Exception: + # Unhandled errors must be answered here: Starlette's own 500 handler runs + # outside this middleware and would drop the X-Request-Id header. + logger.exception("unhandled error for request_id=%s", request_id) + response = JSONResponse(status_code=500, content=error_body("internal_error", "internal error", request_id)) + response.headers["X-Request-Id"] = request_id + return response + + +@app.exception_handler(ApiError) +async def api_error_handler(request: Request, exc: ApiError): + return error_response(request, exc.status_code, exc.code, exc.message, exc.headers) + + +@app.exception_handler(RequestValidationError) +async def validation_error_handler(request: Request, exc: RequestValidationError): + return error_response(request, 400, "invalid_request", "request failed validation") + + +@app.exception_handler(StarletteHTTPException) +async def http_exception_handler(request: Request, exc: StarletteHTTPException): + code = {404: "not_found", 405: "invalid_request", 415: "unsupported_media_type"}.get(exc.status_code, "invalid_request") + message = exc.detail if isinstance(exc.detail, str) else "request failed" + return error_response(request, exc.status_code, code, message) + + +async def db_unavailable_handler(request: Request, exc: Exception): + logger.warning("database unavailable for request_id=%s: %s", request.state.request_id, type(exc).__name__) + return error_response(request, 503, "unavailable", "service temporarily unavailable") + + +for _exc in DB_UNAVAILABLE: + app.add_exception_handler(_exc, db_unavailable_handler) + + +# --------------------------------------------------------------------------- +# Auth: Basic only on POST /auth/sessions, Bearer everywhere else. +# X-User-Id is ignored since lab2. +# --------------------------------------------------------------------------- + +async def current_user(request: Request) -> dict: + return await auth.authenticate(store, cache, request.headers.get("Authorization")) + + +def parse_uuid(value: str, field: str) -> uuid.UUID: + try: + return uuid.UUID(value) + except ValueError: + raise ApiError(400, "invalid_request", f"{field} is not a valid UUID") from None + + +def not_found() -> ApiError: + return ApiError(404, "not_found", "chat not found") + + +# --------------------------------------------------------------------------- +# Health +# --------------------------------------------------------------------------- + +@app.get("/health/live", response_model=Health) +async def liveness(): + return Health() + + +@app.get("/health/ready", response_model=Health) +async def readiness(): + # PostgreSQL is critical; Valkey is not (the API bypasses the cache without it). + try: + await store.ping() + except DB_UNAVAILABLE: + raise ApiError(503, "unavailable", "database is not available") from None + return Health() + + +# --------------------------------------------------------------------------- +# Users and sessions +# --------------------------------------------------------------------------- + +@app.post("/api/v1/users", response_model=User, status_code=201) +async def register_user(body: CreateUser): + if not body.display_name.strip() or not body.password.strip(): + raise ApiError(400, "invalid_request", "display_name and password must not be blank") + password_hash = await auth.hash_password(body.password) + return await store.create_user(body.username, body.display_name, password_hash) + + +@app.get("/api/v1/users/me", response_model=User) +async def current_user_endpoint(user: dict = Depends(current_user)): + return user + + +@app.post("/api/v1/auth/sessions", response_model=Session, status_code=201) +async def create_session(request: Request): + return await auth.login(store, request.headers.get("Authorization")) + + +@app.delete("/api/v1/auth/sessions/current", status_code=204) +async def delete_session(request: Request): + await auth.logout(store, cache, request.headers.get("Authorization")) + return Response(status_code=204) + + +# --------------------------------------------------------------------------- +# Chats +# --------------------------------------------------------------------------- + +@app.post("/api/v1/chats", response_model=Chat, status_code=201) +async def create_chat(body: CreateChat, user: dict = Depends(current_user)): + if not body.title.strip(): + raise ApiError(400, "invalid_request", "title must not be blank") + if len(set(body.member_ids)) != len(body.member_ids): + raise ApiError(400, "invalid_request", "member_ids must not contain duplicates") + if uuid.UUID(user["id"]) not in body.member_ids: + raise ApiError(400, "invalid_request", "caller must be a member of the chat") + return await store.create_chat(body.title, list(body.member_ids)) + + +@app.get("/api/v1/chats", response_model=ChatPage) +async def list_chats( + user: dict = Depends(current_user), + limit: int = Query(default=50, ge=1, le=100), + cursor: Optional[str] = Query(default=None, min_length=1), +): + return await store.list_chats(uuid.UUID(user["id"]), limit, cursor) + + +@app.get("/api/v1/chats/{chat_id}", response_model=Chat) +async def get_chat(chat_id: str, user: dict = Depends(current_user)): + chat = await store.get_chat_for_member(parse_uuid(chat_id, "chat_id"), uuid.UUID(user["id"])) + if chat is None: + raise not_found() + return chat + + +# --------------------------------------------------------------------------- +# Messages +# --------------------------------------------------------------------------- + +@app.post("/api/v1/chats/{chat_id}/messages", response_model=Message, status_code=201) +async def create_message(chat_id: str, body: CreateMessage, user: dict = Depends(current_user)): + chat_uuid = parse_uuid(chat_id, "chat_id") + if not body.text.strip(): + # Access is checked before content: an outsider gets 404 even for a blank text. + if not await store.is_member(chat_uuid, uuid.UUID(user["id"])): + raise not_found() + raise ApiError(400, "invalid_request", "text must not be blank") + message = await store.create_message(chat_uuid, uuid.UUID(user["id"]), body.text) + if message is None: + raise not_found() + return message + + +@app.get("/api/v1/chats/{chat_id}/messages", response_model=MessagePage) +async def list_messages( + chat_id: str, + user: dict = Depends(current_user), + limit: int = Query(default=50, ge=1, le=100), + cursor: Optional[str] = Query(default=None, min_length=1), +): + chat_uuid = parse_uuid(chat_id, "chat_id") + if not await store.is_member(chat_uuid, uuid.UUID(user["id"])): + raise not_found() + return await store.list_messages(chat_uuid, limit, cursor) diff --git a/app/migrate.py b/app/migrate.py new file mode 100644 index 00000000..fa3da67f --- /dev/null +++ b/app/migrate.py @@ -0,0 +1,68 @@ +"""Apply versioned SQL migrations from migrations/; safe to run repeatedly and concurrently. + +Usage: python -m app.migrate +""" +from __future__ import annotations + +import asyncio +import logging +import sys +from pathlib import Path + +import asyncpg + +from app import config + +logging.basicConfig(level=logging.INFO, format="%(levelname)s %(name)s: %(message)s") +logger = logging.getLogger("migrate") + +MIGRATIONS_DIR = Path(__file__).resolve().parents[1] / "migrations" +# Arbitrary constant: serialises concurrent runners (e.g. several API replicas in lab3). +LOCK_ID = 2026_0002 + + +async def connect_with_retry(attempts: int = 30) -> asyncpg.Connection: + for attempt in range(1, attempts + 1): + try: + return await asyncpg.connect(config.DATABASE_URL, timeout=config.DB_CONNECT_TIMEOUT) + except (OSError, asyncpg.PostgresError, asyncpg.InterfaceError) as exc: + logger.warning("database not reachable (attempt %d/%d): %s", attempt, attempts, type(exc).__name__) + await asyncio.sleep(1) + raise SystemExit("database is not reachable") + + +async def migrate() -> int: + if not config.DATABASE_URL: + raise SystemExit("DATABASE_URL or DATABASE_URL_FILE is required") + conn = await connect_with_retry() + applied_now = 0 + try: + await conn.execute("SELECT pg_advisory_lock($1)", LOCK_ID) + await conn.execute( + """ + CREATE TABLE IF NOT EXISTS schema_migrations ( + version text PRIMARY KEY, + applied_at timestamptz NOT NULL DEFAULT now() + ) + """ + ) + done = {r["version"] for r in await conn.fetch("SELECT version FROM schema_migrations")} + for path in sorted(MIGRATIONS_DIR.glob("*.sql")): + version = path.stem + if version in done: + continue + logger.info("applying %s", version) + async with conn.transaction(): + await conn.execute(path.read_text(encoding="utf-8")) + await conn.execute("INSERT INTO schema_migrations (version) VALUES ($1)", version) + applied_now += 1 + logger.info("migrations up to date: %d applied now, %d before", applied_now, len(done)) + finally: + await conn.execute("SELECT pg_advisory_unlock($1)", LOCK_ID) + await conn.close() + return applied_now + + +if __name__ == "__main__": + asyncio.run(migrate()) + sys.exit(0) diff --git a/app/models.py b/app/models.py new file mode 100644 index 00000000..b9aab0bc --- /dev/null +++ b/app/models.py @@ -0,0 +1,73 @@ +"""Pydantic request/response schemas mirroring contracts/openapi.json.""" +from __future__ import annotations + +import uuid +from typing import List, Optional + +from pydantic import BaseModel, ConfigDict, Field + +USERNAME_PATTERN = r"^[a-z0-9_]{3,32}$" + + +class CreateUser(BaseModel): + model_config = ConfigDict(extra="forbid") + + username: str = Field(pattern=USERNAME_PATTERN) + display_name: str = Field(min_length=1, max_length=100) + password: str = Field(min_length=12, max_length=128) + + +class User(BaseModel): + id: uuid.UUID + username: str + display_name: str + created_at: str + + +class CreateChat(BaseModel): + model_config = ConfigDict(extra="forbid") + + title: str = Field(min_length=1, max_length=100) + member_ids: List[uuid.UUID] = Field(min_length=1, max_length=100) + + +class Chat(BaseModel): + id: uuid.UUID + title: str + member_ids: List[uuid.UUID] + created_at: str + + +class ChatPage(BaseModel): + items: List[Chat] + next_cursor: Optional[str] = None + + +class CreateMessage(BaseModel): + model_config = ConfigDict(extra="forbid") + + text: str = Field(max_length=4000) + + +class Message(BaseModel): + id: uuid.UUID + chat_id: uuid.UUID + sender_id: uuid.UUID + text: str + created_at: str + + +class MessagePage(BaseModel): + items: List[Message] + next_cursor: Optional[str] = None + + +class Session(BaseModel): + token: str + token_type: str = "Bearer" + expires_at: str + user: User + + +class Health(BaseModel): + status: str = "ok" diff --git a/app/storage.py b/app/storage.py new file mode 100644 index 00000000..0666515d --- /dev/null +++ b/app/storage.py @@ -0,0 +1,288 @@ +"""PostgreSQL repository. Every query is parameterised; PostgreSQL is the source of truth.""" +from __future__ import annotations + +import base64 +import json +import uuid +from datetime import datetime, timezone +from typing import List, Optional, Tuple + +import asyncpg + +from app import config +from app.errors import ApiError + + +def fmt_ts(value: datetime) -> str: + # Always 6 fractional digits: exact round trip with PostgreSQL microseconds. + return value.astimezone(timezone.utc).strftime("%Y-%m-%dT%H:%M:%S.%fZ") + + +def user_row(row: asyncpg.Record) -> dict: + return { + "id": str(row["id"]), + "username": row["username"], + "display_name": row["display_name"], + "created_at": fmt_ts(row["created_at"]), + } + + +def chat_row(row: asyncpg.Record) -> dict: + return { + "id": str(row["id"]), + "title": row["title"], + "member_ids": [str(m) for m in row["member_ids"]], + "created_at": fmt_ts(row["created_at"]), + } + + +def message_row(row: asyncpg.Record) -> dict: + return { + "id": str(row["id"]), + "chat_id": str(row["chat_id"]), + "sender_id": str(row["sender_id"]), + "text": row["text"], + "created_at": fmt_ts(row["created_at"]), + } + + +# --------------------------------------------------------------------------- +# Opaque keyset cursor bound to one resource +# --------------------------------------------------------------------------- + +def encode_cursor(resource: str, created_at: str, item_id: str) -> str: + payload = json.dumps({"r": resource, "t": created_at, "i": item_id}, separators=(",", ":")) + return base64.urlsafe_b64encode(payload.encode("utf-8")).decode("ascii").rstrip("=") + + +def decode_cursor(resource: str, cursor: str) -> Tuple[datetime, uuid.UUID]: + try: + padded = cursor + "=" * (-len(cursor) % 4) + payload = json.loads(base64.urlsafe_b64decode(padded.encode("ascii")).decode("utf-8")) + if payload.get("r") != resource: + raise ValueError("cursor belongs to a different resource") + created_at = datetime.fromisoformat(payload["t"].replace("Z", "+00:00")) + if created_at.tzinfo is None: + raise ValueError("cursor time has no timezone") + return created_at, uuid.UUID(payload["i"]) + except Exception as exc: # noqa: BLE001 - any malformed cursor is a 400 + raise ApiError(400, "invalid_request", "invalid cursor") from exc + + +def page_of(items: List[dict], resource: str, limit: int) -> dict: + """Queries fetch limit+1 rows: the extra row only tells whether a next page exists.""" + page = items[:limit] + next_cursor = None + if len(items) > limit: + last = page[-1] + next_cursor = encode_cursor(resource, last["created_at"], last["id"]) + return {"items": page, "next_cursor": next_cursor} + + +# --------------------------------------------------------------------------- +# Repository +# --------------------------------------------------------------------------- + +class Store: + def __init__(self): + self.pool: Optional[asyncpg.Pool] = None + + async def open(self) -> None: + # min_size=0: connections open on demand, so the API starts even while + # PostgreSQL is down and readiness reports 503 until it is back. + self.pool = await asyncpg.create_pool( + config.DATABASE_URL, + min_size=0, + max_size=config.DB_POOL_MAX, + timeout=config.DB_CONNECT_TIMEOUT, + command_timeout=config.DB_COMMAND_TIMEOUT, + max_inactive_connection_lifetime=60, + ) + + async def close(self) -> None: + if self.pool is not None: + await self.pool.close() + + def acquire(self): + return self.pool.acquire(timeout=config.DB_ACQUIRE_TIMEOUT) + + async def ping(self) -> bool: + async with self.acquire() as conn: + return await conn.fetchval("SELECT 1") == 1 + + # -- users -------------------------------------------------------------- + + async def create_user(self, username: str, display_name: str, password_hash: str) -> dict: + async with self.acquire() as conn: + try: + row = await conn.fetchrow( + """ + INSERT INTO users (id, username, display_name, password_hash) + VALUES ($1, $2, $3, $4) + RETURNING id, username, display_name, created_at + """, + uuid.uuid4(), username, display_name, password_hash, + ) + except asyncpg.UniqueViolationError: + # The UNIQUE constraint, not a prior SELECT, decides concurrent registrations. + raise ApiError(409, "conflict", "username already taken") from None + return user_row(row) + + async def get_credentials(self, username: str) -> Optional[asyncpg.Record]: + async with self.acquire() as conn: + return await conn.fetchrow( + "SELECT id, username, display_name, created_at, password_hash FROM users WHERE username = $1", + username, + ) + + # -- sessions ----------------------------------------------------------- + + async def create_session(self, token_hash: bytes, user_id: uuid.UUID, ttl_seconds: int) -> datetime: + async with self.acquire() as conn: + return await conn.fetchval( + """ + INSERT INTO sessions (token_hash, user_id, expires_at) + VALUES ($1, $2, clock_timestamp() + make_interval(secs => $3)) + RETURNING expires_at + """, + token_hash, user_id, float(ttl_seconds), + ) + + async def find_session(self, token_hash: bytes) -> Optional[asyncpg.Record]: + """Only a live session: not revoked and not expired by the database clock.""" + async with self.acquire() as conn: + return await conn.fetchrow( + """ + SELECT s.expires_at, u.id, u.username, u.display_name, u.created_at + FROM sessions s JOIN users u ON u.id = s.user_id + WHERE s.token_hash = $1 AND s.revoked_at IS NULL AND s.expires_at > clock_timestamp() + """, + token_hash, + ) + + async def revoke_session(self, token_hash: bytes) -> Optional[datetime]: + async with self.acquire() as conn: + return await conn.fetchval( + """ + UPDATE sessions SET revoked_at = clock_timestamp() + WHERE token_hash = $1 AND revoked_at IS NULL AND expires_at > clock_timestamp() + RETURNING expires_at + """, + token_hash, + ) + + # -- chats -------------------------------------------------------------- + + async def create_chat(self, title: str, member_ids: List[uuid.UUID]) -> dict: + """Chat and all memberships commit together or not at all. + + Unknown members are detected by the foreign key inside the transaction, so a + failure after the chat row was inserted really exercises the rollback.""" + chat_id = uuid.uuid4() + async with self.acquire() as conn: + try: + async with conn.transaction(): + row = await conn.fetchrow( + "INSERT INTO chats (id, title) VALUES ($1, $2) RETURNING id, title, created_at", + chat_id, title, + ) + await conn.execute( + """ + INSERT INTO chat_members (chat_id, user_id, position) + SELECT $1, m.user_id, m.ord - 1 + FROM unnest($2::uuid[]) WITH ORDINALITY AS m(user_id, ord) + """, + chat_id, member_ids, + ) + except asyncpg.ForeignKeyViolationError: + raise ApiError(400, "invalid_request", "unknown member in member_ids") from None + return { + "id": str(row["id"]), + "title": row["title"], + "member_ids": [str(m) for m in member_ids], + "created_at": fmt_ts(row["created_at"]), + } + + async def get_chat_for_member(self, chat_id: uuid.UUID, user_id: uuid.UUID) -> Optional[dict]: + async with self.acquire() as conn: + row = await conn.fetchrow( + """ + SELECT c.id, c.title, c.created_at, + array_agg(m.user_id ORDER BY m.position) AS member_ids + FROM chats c JOIN chat_members m ON m.chat_id = c.id + WHERE c.id = $1 + AND EXISTS (SELECT 1 FROM chat_members me WHERE me.chat_id = c.id AND me.user_id = $2) + GROUP BY c.id + """, + chat_id, user_id, + ) + return chat_row(row) if row else None + + async def list_chats(self, user_id: uuid.UUID, limit: int, cursor: Optional[str]) -> dict: + after_t, after_i = decode_cursor("chats", cursor) if cursor else (None, None) + async with self.acquire() as conn: + rows = await conn.fetch( + """ + SELECT c.id, c.title, c.created_at, + array_agg(m.user_id ORDER BY m.position) AS member_ids + FROM chat_members me + JOIN chats c ON c.id = me.chat_id + JOIN chat_members m ON m.chat_id = c.id + WHERE me.user_id = $1 + AND ($2::timestamptz IS NULL OR (c.created_at, c.id) > ($2, $3::uuid)) + GROUP BY c.id + ORDER BY c.created_at, c.id + LIMIT $4 + """, + user_id, after_t, after_i, limit + 1, + ) + return page_of([chat_row(r) for r in rows], "chats", limit) + + async def is_member(self, chat_id: uuid.UUID, user_id: uuid.UUID) -> bool: + async with self.acquire() as conn: + return bool(await conn.fetchval( + "SELECT EXISTS (SELECT 1 FROM chat_members WHERE chat_id = $1 AND user_id = $2)", + chat_id, user_id, + )) + + # -- messages ----------------------------------------------------------- + + async def create_message(self, chat_id: uuid.UUID, sender_id: uuid.UUID, text: str) -> Optional[dict]: + """Membership check and insert in one statement; None means "no such chat for you".""" + async with self.acquire() as conn: + row = await conn.fetchrow( + """ + INSERT INTO messages (id, chat_id, sender_id, text) + SELECT $1, $2, $3, $4 + WHERE EXISTS (SELECT 1 FROM chat_members WHERE chat_id = $2 AND user_id = $3) + RETURNING id, chat_id, sender_id, text, created_at + """, + uuid.uuid4(), chat_id, sender_id, text, + ) + return message_row(row) if row else None + + async def list_messages(self, chat_id: uuid.UUID, limit: int, cursor: Optional[str]) -> dict: + resource = str(chat_id) + async with self.acquire() as conn: + if cursor: + after_t, after_i = decode_cursor(resource, cursor) + rows = await conn.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 + """, + chat_id, after_t, after_i, limit + 1, + ) + else: + rows = await conn.fetch( + """ + SELECT id, chat_id, sender_id, text, created_at FROM messages + WHERE chat_id = $1 + ORDER BY created_at, id + LIMIT $2 + """, + chat_id, limit + 1, + ) + return page_of([message_row(r) for r in rows], resource, limit) diff --git a/compose.yaml b/compose.yaml new file mode 100644 index 00000000..a04811c1 --- /dev/null +++ b/compose.yaml @@ -0,0 +1,100 @@ +# Lab 2 stack: api -> postgres (source of truth) + valkey (session cache). +# Prepare secrets first: scripts/init-secrets.sh. Start: docker compose up -d --build --wait +name: messenger-lab2 + +x-api: &api + build: . + image: mtusi-messenger:lab2 + environment: &api-env + APP_HOST: 0.0.0.0 + APP_PORT: "8080" + APP_ENV: ${APP_ENV:-lab} + SESSION_TTL_SECONDS: ${SESSION_TTL_SECONDS:-3600} + SESSION_STORE: postgres + SESSION_CACHE_MAX_SECONDS: ${SESSION_CACHE_MAX_SECONDS:-300} + DATABASE_URL_FILE: /run/secrets/database_url + CACHE_URL_FILE: /run/secrets/cache_url + DB_POOL_MAX: ${DB_POOL_MAX:-10} + secrets: [database_url, cache_url] + depends_on: + postgres: + condition: service_healthy + valkey: + # The cache is optional for correctness: only wait for the container to start. + condition: service_started + migrate: + condition: service_completed_successfully + stop_grace_period: 10s + restart: unless-stopped + +services: + postgres: + image: postgres:17.6-alpine3.22 + environment: + POSTGRES_DB: messenger + POSTGRES_USER: messenger + POSTGRES_PASSWORD_FILE: /run/secrets/postgres_password + secrets: [postgres_password] + volumes: + - pgdata:/var/lib/postgresql/data + healthcheck: + test: ["CMD-SHELL", "pg_isready -U messenger -d messenger"] + interval: 2s + timeout: 3s + retries: 30 + stop_grace_period: 30s + restart: unless-stopped + + valkey: + image: valkey/valkey:8.1.4-alpine3.22 + # requirepass and cache-only settings live in the secret config file. + command: ["valkey-server", "/run/secrets/valkey_conf"] + secrets: [valkey_conf] + healthcheck: + # NOAUTH also proves the server answers; the password stays out of the process list. + test: ["CMD-SHELL", "valkey-cli ping 2>&1 | grep -qE 'PONG|NOAUTH'"] + interval: 2s + timeout: 3s + retries: 30 + restart: unless-stopped + + migrate: + build: . + image: mtusi-messenger:lab2 + command: ["python", "-m", "app.migrate"] + environment: + DATABASE_URL_FILE: /run/secrets/database_url + secrets: [database_url] + depends_on: + postgres: + condition: service_healthy + restart: "no" + + api: + <<: *api + ports: + - "127.0.0.1:${APP_PORT:-8080}:8080" + + # Same image with a 2-second TTL, only for the expiry test: + # docker compose --profile ttl-test up -d --wait api-short-ttl + api-short-ttl: + <<: *api + profiles: [ttl-test] + environment: + <<: *api-env + SESSION_TTL_SECONDS: "2" + ports: + - "127.0.0.1:${SHORT_TTL_PORT:-8081}:8080" + +volumes: + pgdata: + +secrets: + postgres_password: + file: ./secrets/postgres_password + database_url: + file: ./secrets/database_url + cache_url: + file: ./secrets/cache_url + valkey_conf: + file: ./secrets/valkey.conf diff --git a/evidence/explain_history.txt b/evidence/explain_history.txt new file mode 100644 index 00000000..c6d5b362 --- /dev/null +++ b/evidence/explain_history.txt @@ -0,0 +1,74 @@ +# EXPLAIN evidence for message history pagination +# date: 2026-10-07T14:17:55Z commit: 65003b6 +# postgres: 17.6 +# messages total: 70112, in measured chat: 20000 + +PREPARE +PREPARE +=== 1. WITH index messages_chat_history_idx: first page (limit 50 + 1) === + QUERY PLAN +--------------------------------------------------------------------------------------------------------------------------------------------------- + Limit (cost=0.42..8.60 rows=51 width=78) (actual time=0.014..0.019 rows=51 loops=1) + Buffers: shared hit=4 + -> Index Scan using messages_chat_history_idx on messages (cost=0.42..3227.11 rows=20122 width=78) (actual time=0.013..0.015 rows=51 loops=1) + Index Cond: (chat_id = '00000000-0000-4000-8000-000000000100'::uuid) + Buffers: shared hit=4 + Planning: + Buffers: shared hit=106 + Planning Time: 0.272 ms + Execution Time: 0.031 ms +(9 rows) + +=== 2. WITH index: deep page, cursor after message #15000 of 20000 === + QUERY PLAN +------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ + Limit (cost=0.42..55.74 rows=51 width=78) (actual time=0.012..0.017 rows=51 loops=1) + Buffers: shared hit=4 + -> Index Scan using messages_chat_history_idx on messages (cost=0.42..1590.70 rows=1466 width=78) (actual time=0.012..0.014 rows=51 loops=1) + Index Cond: ((chat_id = '00000000-0000-4000-8000-000000000100'::uuid) AND (ROW(created_at, id) > ROW('2026-01-01 04:10:00+00'::timestamp with time zone, '47ba2a9c-d238-4807-2008-6ea72cb0f95c'::uuid))) + Buffers: shared hit=4 + Planning: + Buffers: shared hit=42 + Planning Time: 0.276 ms + Execution Time: 0.035 ms +(9 rows) + +BEGIN +DROP INDEX +=== 3. WITHOUT index: first page === + QUERY PLAN +-------------------------------------------------------------------------------------------------------------------------- + Limit (cost=2487.71..2487.84 rows=51 width=78) (actual time=4.235..4.239 rows=51 loops=1) + Buffers: shared hit=946 + -> Sort (cost=2487.71..2538.02 rows=20122 width=78) (actual time=4.234..4.236 rows=51 loops=1) + Sort Key: created_at, id + Sort Method: top-N heapsort Memory: 31kB + Buffers: shared hit=946 + -> Seq Scan on messages (cost=0.00..1816.40 rows=20122 width=78) (actual time=0.011..3.325 rows=20000 loops=1) + Filter: (chat_id = '00000000-0000-4000-8000-000000000100'::uuid) + Rows Removed by Filter: 50112 + Buffers: shared hit=940 + Planning: + Buffers: shared hit=16 + Planning Time: 0.098 ms + Execution Time: 4.249 ms +(14 rows) + +=== 4. WITHOUT index: deep page === + QUERY PLAN +-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- + Limit (cost=2215.87..2216.00 rows=51 width=78) (actual time=3.117..3.121 rows=51 loops=1) + Buffers: shared hit=940 + -> Sort (cost=2215.87..2219.53 rows=1466 width=78) (actual time=3.116..3.118 rows=51 loops=1) + Sort Key: created_at, id + Sort Method: top-N heapsort Memory: 31kB + Buffers: shared hit=940 + -> Seq Scan on messages (cost=0.00..2166.96 rows=1466 width=78) (actual time=0.605..2.853 rows=5000 loops=1) + Filter: ((chat_id = '00000000-0000-4000-8000-000000000100'::uuid) AND (ROW(created_at, id) > ROW('2026-01-01 04:10:00+00'::timestamp with time zone, '47ba2a9c-d238-4807-2008-6ea72cb0f95c'::uuid))) + Rows Removed by Filter: 65112 + Buffers: shared hit=940 + Planning Time: 0.069 ms + Execution Time: 3.133 ms +(12 rows) + +ROLLBACK diff --git a/evidence/fresh_migrations.txt b/evidence/fresh_migrations.txt new file mode 100644 index 00000000..03c84113 --- /dev/null +++ b/evidence/fresh_migrations.txt @@ -0,0 +1,20 @@ +# Fresh volume: migrations from scratch + public smoke +# date: 2026-10-07T14:18:43Z +$ APP_PORT=18090 docker compose -p lab2-clean up -d --wait + Container lab2-clean-api-1 Created + Container lab2-clean-api-1 Healthy + Container lab2-clean-migrate-1 Created + Container lab2-clean-migrate-1 Exited + Container lab2-clean-postgres-1 Created + Container lab2-clean-postgres-1 Healthy + Container lab2-clean-valkey-1 Created + Container lab2-clean-valkey-1 Healthy + Network lab2-clean_default Created + Volume "lab2-clean_pgdata" Created +$ docker compose -p lab2-clean logs migrate +INFO migrate: applying 0001_init +INFO migrate: migrations up to date: 1 applied now, 0 before +$ make test BASE_URL=http://localhost:18090 +PASS: lab2 public API scenario; infrastructure and grading evidence remain separate. +$ docker compose -p lab2-clean run --rm migrate # second run +INFO migrate: migrations up to date: 0 applied now, 1 before diff --git a/evidence/persistence.txt b/evidence/persistence.txt new file mode 100644 index 00000000..30973aac --- /dev/null +++ b/evidence/persistence.txt @@ -0,0 +1,20 @@ +# Persistence: API + PostgreSQL + Valkey restarted, volume kept, same token +# date: 2026-10-07T14:19:03Z +## containers BEFORE +api 2026-10-07T14:18:25.262485419Z running restarts=0 +postgres 2026-10-07T14:18:22.306271835Z running restarts=0 +valkey 2026-10-07T14:18:21.888265501Z running restarts=0 +volume messenger-lab2_pgdata + +$ make test-persistence ACTION_SCRIPT=scripts/restart.sh +Executing explicit persistence hook; hook output suppressed to avoid leaking secrets. +PASS: persistence preserved confirmed data and existing session. Hook scope needs operator evidence. + +## containers AFTER (StartedAt changed for all three) +api 2026-10-07T14:19:08.428103009Z running restarts=0 +postgres 2026-10-07T14:19:05.240867716Z running restarts=0 +valkey 2026-10-07T14:19:05.240850591Z running restarts=0 +volume messenger-lab2_pgdata + +$ docker compose logs migrate | tail -1 +INFO migrate: migrations up to date: 0 applied now, 1 before diff --git a/evidence/smoke.txt b/evidence/smoke.txt new file mode 100644 index 00000000..51d84e48 --- /dev/null +++ b/evidence/smoke.txt @@ -0,0 +1,5 @@ +# date: 2026-10-07T14:19:14Z +$ make check +PASS: offline skeleton structure, local refs and Python syntax; application NOT tested. +$ make test +PASS: lab2 public API scenario; infrastructure and grading evidence remain separate. diff --git a/evidence/student_tests.txt b/evidence/student_tests.txt new file mode 100644 index 00000000..be684fbd --- /dev/null +++ b/evidence/student_tests.txt @@ -0,0 +1,44 @@ +# date: 2026-10-07T14:19:14Z +$ make test-student +BASE_URL="http://localhost:18080" sh student-tests/run_all.sh +== own_tests.py +ok - malformed JSON -> 400 invalid_request +ok - foreign chat access -> 404 (no leak) +ok - empty/whitespace message text -> 400 +ok - duplicate username -> 409, original user intact +ok - multi-page pagination traversal: 4 pages, 7 messages, no dup/loss +ok - cursor from another chat -> 400 (cursor is bound to its resource) +PASS: 6/6 student checks + +== concurrency_test.py +PASS: 100 unique messages written and read back from 10 concurrent clients + +== auth_test.py +ok - wrong password / unknown user -> identical 401 Basic +ok - missing / malformed / non-Basic login -> 401 +ok - UTF-8 password containing ':' -> 201 +ok - password shorter than 12 / missing -> 400 +ok - Basic / X-User-Id / unknown token on business endpoint -> 401 +ok - logout revokes only the current token; repeat logout -> 401 +ok - session with TTL=2s is rejected after 3s (cache entry included) +PASS: 7 checks + +== db_integrity_test.py +ok - 20 concurrent registrations of one username -> 1x201, 19x409, 1 row +ok - chat with unknown member -> 400 and transaction rolled back (no orphan chat) +ok - password stored as $argon2id$..., sessions keep only sha256(token) +ok - migrations run twice more: schema_migrations and data unchanged (1:49) +PASS: 4 checks + +== dependency_test.py +ok - Valkey caches sessions with TTL<=300s and keeps logout tombstones +ok - Valkey stopped: ready=200, reads/writes OK, revoked token 401, 4 ms/request +ok - PostgreSQL stopped: live=200, ready/business=503 in 0.0s total, unverified token not trusted +ok - PostgreSQL started again: API recovers without restart, data intact +PASS: 4 checks + +== sigterm_test.sh +api stopped in 0s, exit code 0 (0 = graceful, 137 = SIGKILL) +PASS: graceful SIGTERM shutdown, api restarted + +ALL STUDENT TESTS PASSED diff --git a/migrations/0001_init.sql b/migrations/0001_init.sql new file mode 100644 index 00000000..89e1e4c9 --- /dev/null +++ b/migrations/0001_init.sql @@ -0,0 +1,58 @@ +-- Initial schema for lab2. Applied once by app/migrate.py inside one transaction. + +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 clock_timestamp(), + CONSTRAINT users_username_key UNIQUE (username), + 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 TABLE chats ( + id uuid PRIMARY KEY, + title text NOT NULL, + created_at timestamptz NOT NULL DEFAULT clock_timestamp(), + CONSTRAINT chats_title_len CHECK (char_length(title) BETWEEN 1 AND 100) +); + +-- position keeps member_ids in the order the creator sent them. +CREATE TABLE chat_members ( + chat_id uuid NOT NULL REFERENCES chats (id), + user_id uuid NOT NULL REFERENCES users (id), + position smallint NOT NULL, + PRIMARY KEY (chat_id, user_id) +); + +-- "Chats of a user": GET /chats starts from the caller's memberships. +CREATE INDEX chat_members_user_idx ON chat_members (user_id, chat_id); + +CREATE TABLE messages ( + id uuid PRIMARY KEY, + chat_id uuid NOT NULL, + sender_id uuid NOT NULL, + text text NOT NULL, + created_at timestamptz NOT NULL DEFAULT clock_timestamp(), + -- The sender must be a member of the chat, enforced by the database itself. + CONSTRAINT messages_sender_member_fk FOREIGN KEY (chat_id, sender_id) + REFERENCES chat_members (chat_id, user_id), + CONSTRAINT messages_text_len CHECK (char_length(text) BETWEEN 1 AND 4000) +); + +-- Keyset pagination of history: WHERE chat_id = $1 AND (created_at, id) > ($2, $3) +-- ORDER BY created_at, id LIMIT n. Justified by EXPLAIN in evidence/explain_history.txt. +CREATE INDEX messages_chat_history_idx ON messages (chat_id, created_at, id); + +-- Sessions: PostgreSQL is the source of truth; Valkey only caches lookups. +-- token_hash = sha256(token); the raw token is never stored. +CREATE TABLE sessions ( + token_hash bytea PRIMARY KEY, + user_id uuid NOT NULL REFERENCES users (id), + created_at timestamptz NOT NULL DEFAULT clock_timestamp(), + expires_at timestamptz NOT NULL, + revoked_at timestamptz +); + +CREATE INDEX sessions_expires_idx ON sessions (expires_at); diff --git a/requirements.txt b/requirements.txt new file mode 100644 index 00000000..d1f75a4d --- /dev/null +++ b/requirements.txt @@ -0,0 +1,6 @@ +fastapi==0.142.2 +uvicorn[standard]==0.54.0 +pydantic==2.13.5 +asyncpg==0.32.0 +redis==8.1.0 +argon2-cffi==25.1.0 diff --git a/scripts/init-secrets.sh b/scripts/init-secrets.sh new file mode 100755 index 00000000..f7df3788 --- /dev/null +++ b/scripts/init-secrets.sh @@ -0,0 +1,32 @@ +#!/bin/sh +# Generate local synthetic credentials into ./secrets (git-ignored). Idempotent: +# existing files are kept, so a running stack keeps working. Prints no secret values. +set -eu + +cd "$(dirname "$0")/.." +mkdir -p secrets + +gen() { python3 -c 'import secrets; print(secrets.token_hex(24))'; } + +if [ ! -f secrets/postgres_password ]; then + gen > secrets/postgres_password + echo "created secrets/postgres_password" +fi +PG_PASS=$(cat secrets/postgres_password) +printf 'postgresql://messenger:%s@postgres:5432/messenger\n' "$PG_PASS" > secrets/database_url + +if [ ! -f secrets/valkey.conf ]; then + { + printf 'requirepass %s\n' "$(gen)" + # Pure cache: PostgreSQL holds the sessions, so no RDB/AOF is needed. + printf 'save ""\nappendonly no\n' + printf 'maxmemory 64mb\nmaxmemory-policy volatile-lru\n' + } > secrets/valkey.conf + echo "created secrets/valkey.conf" +fi +VK_PASS=$(sed -n 's/^requirepass //p' secrets/valkey.conf) +printf 'redis://:%s@valkey:6379/0\n' "$VK_PASS" > secrets/cache_url + +# Containers run as non-root users that do not own these files on Linux. +chmod 644 secrets/* +echo "secrets ready in ./secrets (not tracked by git)" diff --git a/scripts/restart.sh b/scripts/restart.sh new file mode 100755 index 00000000..a5d7ee43 --- /dev/null +++ b/scripts/restart.sh @@ -0,0 +1,12 @@ +#!/bin/sh +# Restart the API and ALL state stores (PostgreSQL, Valkey), keeping volumes. +# Never `down -v`, never flush, never re-seed. Migrations run again (idempotent). +set -eu + +cd "$(dirname "$0")/.." + +docker compose stop api +docker compose stop valkey postgres +# depends_on brings postgres, valkey and migrate up first; --wait = api healthcheck (/health/ready). +docker compose up -d --no-build --wait api +docker compose ps --all --format 'table {{.Service}}\t{{.Status}}' diff --git a/student-tests/auth_test.py b/student-tests/auth_test.py new file mode 100755 index 00000000..d8935b20 --- /dev/null +++ b/student-tests/auth_test.py @@ -0,0 +1,70 @@ +#!/usr/bin/env python3 +"""Sessions: wrong password, Basic/Bearer separation, X-User-Id ignored, logout, expiry. + +Expiry runs against the api-short-ttl service (SESSION_TTL_SECONDS=2): + docker compose --profile ttl-test up -d --wait api-short-ttl +""" +import base64 +import time +import uuid + +from stack import BASE_URL, SHORT_TTL_URL, Client, check, main_wrapper, ok + + +def basic(username, password): + return {"Authorization": "Basic " + base64.b64encode((username + ":" + password).encode("utf-8")).decode()} + + +def main(): + c = Client(BASE_URL) + alice = c.user("auth") + reg = alice["registration"] + + # Wrong password and unknown user: the same 401 with a Basic challenge. + r1 = c.call("POST", "/api/v1/auth/sessions", 401, headers=basic(reg["username"], "wrong-password-123")) + r2 = c.call("POST", "/api/v1/auth/sessions", 401, headers=basic("nobody_" + uuid.uuid4().hex[:8], "wrong-password-123")) + check(r1["json"]["error"]["message"] == r2["json"]["error"]["message"], "unknown user must look like a wrong password") + ok("wrong password / unknown user -> identical 401 Basic") + + c.call("POST", "/api/v1/auth/sessions", 401) + c.call("POST", "/api/v1/auth/sessions", 401, headers={"Authorization": "Basic !!!not-base64"}) + c.call("POST", "/api/v1/auth/sessions", 401, headers={"Authorization": "Bearer " + alice["token"]}) + ok("missing / malformed / non-Basic login -> 401") + + # A password with ':' and non-ASCII characters survives Basic encoding. + tricky = "пароль:с:двоеточием-" + uuid.uuid4().hex[:6] + user = c.call("POST", "/api/v1/users", 201, body={"username": "u_colon_" + uuid.uuid4().hex[:8], "display_name": "Двоеточие", "password": tricky}, schema="User")["json"] + c.call("POST", "/api/v1/auth/sessions", 201, headers=basic(user["username"], tricky), schema="Session") + ok("UTF-8 password containing ':' -> 201") + + c.call("POST", "/api/v1/users", 400, body={"username": "u_short_" + uuid.uuid4().hex[:8], "display_name": "x", "password": "short-11ch"}) + c.call("POST", "/api/v1/users", 400, body={"username": "u_nopass_" + uuid.uuid4().hex[:8], "display_name": "x"}) + ok("password shorter than 12 / missing -> 400") + + me = c.call("GET", "/api/v1/users/me", 401, headers=basic(reg["username"], reg["password"])) + check(me["headers"].get("WWW-Authenticate", "").startswith("Bearer"), "Bearer challenge expected") + c.call("GET", "/api/v1/users/me", 401, headers={"X-User-Id": alice["id"]}) + c.call("GET", "/api/v1/users/me", 401, headers={"Authorization": "Bearer " + uuid.uuid4().hex * 2}) + ok("Basic / X-User-Id / unknown token on business endpoint -> 401") + + session = c.call("POST", "/api/v1/auth/sessions", 201, headers=basic(reg["username"], reg["password"]), schema="Session")["json"] + check(session["token"] != alice["token"], "every login must issue a new token") + second = dict(alice, token=session["token"]) + c.call("DELETE", "/api/v1/auth/sessions/current", 204, actor=alice) + c.call("GET", "/api/v1/users/me", 401, actor=alice) + c.call("DELETE", "/api/v1/auth/sessions/current", 401, actor=alice) + c.call("GET", "/api/v1/users/me", 200, actor=second, schema="User") + ok("logout revokes only the current token; repeat logout -> 401") + + # Expiry: separate instance of the same image with SESSION_TTL_SECONDS=2. + s = Client(SHORT_TTL_URL) + bob = s.user("ttl") + s.call("GET", "/api/v1/users/me", 200, actor=bob, schema="User") + time.sleep(3) + s.call("GET", "/api/v1/users/me", 401, actor=bob) + s.call("DELETE", "/api/v1/auth/sessions/current", 401, actor=bob) + ok("session with TTL=2s is rejected after 3s (cache entry included)") + + +if __name__ == "__main__": + main_wrapper(main) diff --git a/student-tests/concurrency_test.py b/student-tests/concurrency_test.py new file mode 100755 index 00000000..da3666db --- /dev/null +++ b/student-tests/concurrency_test.py @@ -0,0 +1,61 @@ +#!/usr/bin/env python3 +"""Level-4 race-protection evidence: 10 clients send 100 messages concurrently; +expect exactly 100 unique messages, with no loss/duplication under pagination. +""" +import sys +import urllib.parse +import concurrent.futures +from pathlib import Path + +ROOT = Path(__file__).resolve().parents[1] +sys.path.insert(0, str(ROOT / "tests")) +from client import Client, check # noqa: E402 + + +def main(): + base_url = sys.argv[1] if len(sys.argv) > 1 else "http://localhost:8080" + n_messages = 100 + n_clients = 10 + + c = Client(base_url) + users = [c.user("race%d" % i) for i in range(n_clients)] + chat = c.call( + "POST", "/api/v1/chats", 201, actor=users[0], + body={"title": "race", "member_ids": [u["id"] for u in users]}, + schema="Chat", + )["json"] + path = "/api/v1/chats/" + chat["id"] + "/messages" + + def send(i): + actor = users[i % n_clients] + return c.message(actor, chat, "race-%d" % i)["json"]["id"] + + with concurrent.futures.ThreadPoolExecutor(max_workers=n_clients) as pool: + ids = list(pool.map(send, range(n_messages))) + + check(len(ids) == n_messages, "expected %d responses" % n_messages) + check(len(set(ids)) == n_messages, "expected %d unique message ids, got %d" % (n_messages, len(set(ids)))) + + # Walk the full history back through the API to confirm the store itself + # (not just the HTTP responses) holds exactly n_messages distinct rows. + seen = [] + cursor = None + while True: + qs = "?limit=25" + ("&cursor=" + urllib.parse.quote(cursor, safe="") if cursor else "") + page = c.call("GET", path + qs, actor=users[0], schema="MessagePage")["json"] + seen.extend(page["items"]) + cursor = page["next_cursor"] + if not cursor: + break + check(len(seen) == n_messages, "expected to read back %d messages, got %d" % (n_messages, len(seen))) + check(len({m["id"] for m in seen}) == n_messages, "readback contains duplicates") + + print("PASS: %d unique messages written and read back from %d concurrent clients" % (n_messages, n_clients)) + + +if __name__ == "__main__": + try: + main() + except AssertionError as exc: + print("FAIL:", exc) + raise SystemExit(1) diff --git a/student-tests/db_integrity_test.py b/student-tests/db_integrity_test.py new file mode 100755 index 00000000..9b10d300 --- /dev/null +++ b/student-tests/db_integrity_test.py @@ -0,0 +1,53 @@ +#!/usr/bin/env python3 +"""PostgreSQL integrity: registration race, rollback of chat creation, repeatable migrations, +password storage. Needs the compose stack (reads tables via `docker compose exec postgres`).""" +import concurrent.futures +import uuid + +from stack import BASE_URL, Client, check, compose, main_wrapper, ok, psql + + +def main(): + c = Client(BASE_URL) + + # 1. Registration race: 20 parallel requests for one username. + username = "u_race_" + uuid.uuid4().hex[:10] + body = {"username": username, "display_name": "Гонка", "password": "Race-password-123"} + + def register(_): + return c.call("POST", "/api/v1/users", [201, 409], body=body)["status"] + + with concurrent.futures.ThreadPoolExecutor(max_workers=20) as pool: + statuses = list(pool.map(register, range(20))) + check(statuses.count(201) == 1, "exactly one registration must win, got %s" % statuses) + check(statuses.count(409) == 19, "all others must get 409, got %s" % statuses) + check(psql("SELECT count(*) FROM users WHERE username = '%s'" % username) == "1", "exactly one row expected") + ok("20 concurrent registrations of one username -> 1x201, 19x409, 1 row") + + # 2. Rollback: the chat row is inserted, then the member insert hits the FK. + alice = c.user("rb") + title = "rollback-" + uuid.uuid4().hex + c.call("POST", "/api/v1/chats", 400, actor=alice, body={"title": title, "member_ids": [alice["id"], str(uuid.uuid4())]}) + check(psql("SELECT count(*) FROM chats WHERE title = '%s'" % title) == "0", "failed chat creation left a chat row") + check(psql("SELECT count(*) FROM chats c WHERE NOT EXISTS (SELECT 1 FROM chat_members m WHERE m.chat_id = c.id)") == "0", + "chat without members exists") + ok("chat with unknown member -> 400 and transaction rolled back (no orphan chat)") + + # 3. Passwords are stored as Argon2id hashes, never plaintext. + stored = psql("SELECT password_hash FROM users WHERE username = '%s'" % username) + check(stored.startswith("$argon2id$") and "Race-password-123" not in stored, "password must be an Argon2id hash") + check(psql("SELECT count(*) FROM information_schema.columns WHERE table_name = 'sessions' AND column_name = 'token'") == "0", + "raw tokens must not be stored") + ok("password stored as $argon2id$..., sessions keep only sha256(token)") + + # 4. Migrations re-run without duplicates or data changes. + before = psql("SELECT (SELECT count(*) FROM schema_migrations) || ':' || (SELECT count(*) FROM users)") + compose("run", "--rm", "--no-deps", "migrate") + compose("run", "--rm", "--no-deps", "migrate") + after = psql("SELECT (SELECT count(*) FROM schema_migrations) || ':' || (SELECT count(*) FROM users)") + check(before == after, "migrations changed data on re-run: %s -> %s" % (before, after)) + ok("migrations run twice more: schema_migrations and data unchanged (%s)" % after) + + +if __name__ == "__main__": + main_wrapper(main) diff --git a/student-tests/dependency_test.py b/student-tests/dependency_test.py new file mode 100755 index 00000000..af9ac078 --- /dev/null +++ b/student-tests/dependency_test.py @@ -0,0 +1,86 @@ +#!/usr/bin/env python3 +"""Valkey's role and failures of each dependency. STOPS AND STARTS containers of this stack. + +- Valkey really caches sessions and holds logout tombstones. +- Valkey down: API keeps working (cache bypassed), readiness stays 200. +- PostgreSQL down: bounded 503 quickly, readiness 503, liveness 200; an unverifiable + token is never accepted; no token is still 401. Recovery after start. +""" +import time + +from stack import BASE_URL, Client, Failure, check, compose, main_wrapper, ok, valkey + + +def wait_ready(c, seconds=60): + deadline = time.monotonic() + seconds + while time.monotonic() < deadline: + try: + c.call("GET", "/health/ready", 200) + return + except Failure: + time.sleep(0.5) + raise Failure("API did not become ready") + + +def main(): + c = Client(BASE_URL, timeout=10) + alice, bob, _eve, chat = c.bootstrap() + history = "/api/v1/chats/" + chat["id"] + "/messages" + + # Role of Valkey: a session lookup fills the cache, logout leaves a tombstone. + before = int(valkey("DBSIZE")) + c.call("GET", "/api/v1/users/me", actor=alice, schema="User") + keys = valkey("--scan", "--pattern", "session:*").split() + check(len(keys) >= 1 and int(valkey("DBSIZE")) >= before, "session lookups must be cached in Valkey") + ttl = int(valkey("TTL", keys[0])) + check(0 < ttl <= 300, "cache entries must expire (TTL %d)" % ttl) + temp = c.user("tomb") + c.call("GET", "/api/v1/users/me", actor=temp, schema="User") + c.call("DELETE", "/api/v1/auth/sessions/current", 204, actor=temp) + tombstones = [k for k in valkey("--scan", "--pattern", "session:*").split() if valkey("GET", k) == "revoked"] + check(tombstones, "logout must leave a 'revoked' tombstone in the cache") + ok("Valkey caches sessions with TTL<=300s and keeps logout tombstones") + + # Valkey down -> the API bypasses the cache, PostgreSQL stays the source of truth. + try: + compose("stop", "valkey") + c.call("GET", "/health/ready", 200) + c.call("GET", "/api/v1/users/me", actor=alice, schema="User") + c.message(bob, chat, "без кэша") + c.call("GET", "/api/v1/users/me", 401, actor=temp) # revoked in PostgreSQL too + start = time.monotonic() + for _ in range(10): + c.call("GET", history + "?limit=1", actor=alice, schema="MessagePage") + per_request = (time.monotonic() - start) / 10 + check(per_request < 0.5, "cache bypass must be fast (%.3fs per request)" % per_request) + ok("Valkey stopped: ready=200, reads/writes OK, revoked token 401, %.0f ms/request" % (per_request * 1000)) + finally: + compose("start", "valkey") + + # PostgreSQL down -> bounded 503, never anonymous access. + fresh = c.user("dbdown") # token never looked up yet: not in the cache + try: + compose("stop", "postgres") + c.call("GET", "/health/live", 200) + start = time.monotonic() + r = c.call("GET", "/health/ready", 503) + check(r["json"]["error"]["code"] == "unavailable", "readiness must report unavailable") + c.call("GET", "/api/v1/chats", 503, actor=alice) + c.call("POST", history, 503, actor=alice, body={"text": "в никуда"}) + c.call("GET", "/api/v1/users/me", 503, actor=fresh) # cannot verify -> not trusted + c.call("GET", "/api/v1/users/me", 401) # no credentials at all + elapsed = time.monotonic() - start + check(elapsed < 20, "errors must be bounded in time (%.1fs)" % elapsed) + ok("PostgreSQL stopped: live=200, ready/business=503 in %.1fs total, unverified token not trusted" % elapsed) + finally: + compose("start", "postgres") + + wait_ready(c) + c.call("GET", "/api/v1/users/me", actor=fresh, schema="User") + page = c.call("GET", history + "?limit=100", actor=alice, schema="MessagePage")["json"] + check(any(m["text"] == "без кэша" for m in page["items"]), "message written without cache must persist") + ok("PostgreSQL started again: API recovers without restart, data intact") + + +if __name__ == "__main__": + main_wrapper(main) diff --git a/student-tests/explain_history.sh b/student-tests/explain_history.sh new file mode 100755 index 00000000..d153f906 --- /dev/null +++ b/student-tests/explain_history.sh @@ -0,0 +1,81 @@ +#!/bin/sh +# Seed synthetic history (20 000 messages in one chat + 50 000 in 50 other chats) and +# record EXPLAIN (ANALYZE, BUFFERS) of the exact keyset queries used by the API, +# with and without messages_chat_history_idx. Output: evidence/explain_history.txt +# Seeding is idempotent (fixed IDs, ON CONFLICT DO NOTHING); data is synthetic. +set -eu + +cd "$(dirname "$0")/.." +OUT="${OUT:-evidence/explain_history.txt}" +PSQL="docker compose exec -T postgres psql -U messenger -d messenger -X -v ON_ERROR_STOP=1" + +$PSQL -q <<'SQL' +INSERT INTO users (id, username, display_name, password_hash) VALUES + ('00000000-0000-4000-8000-000000000001', 'seed_explain_a', 'Seed A', 'not-a-login'), + ('00000000-0000-4000-8000-000000000002', 'seed_explain_b', 'Seed B', 'not-a-login') +ON CONFLICT DO NOTHING; + +-- chat ...0100 is the measured one; ...0101-0150 are background noise. +INSERT INTO chats (id, title, created_at) +SELECT ('00000000-0000-4000-8000-' || lpad((100 + g)::text, 12, '0'))::uuid, 'explain ' || g, now() +FROM generate_series(0, 50) g +ON CONFLICT DO NOTHING; + +INSERT INTO chat_members (chat_id, user_id, position) +SELECT c.id, u.id, u.pos +FROM chats c +CROSS JOIN (VALUES ('00000000-0000-4000-8000-000000000001'::uuid, 0), + ('00000000-0000-4000-8000-000000000002'::uuid, 1)) AS u(id, pos) +WHERE c.title LIKE 'explain %' +ON CONFLICT DO NOTHING; + +INSERT INTO messages (id, chat_id, sender_id, text, created_at) +SELECT md5('explain-' || c.n || '-' || g)::uuid, + ('00000000-0000-4000-8000-' || lpad((100 + c.n)::text, 12, '0'))::uuid, + CASE WHEN g % 2 = 0 THEN '00000000-0000-4000-8000-000000000001'::uuid + ELSE '00000000-0000-4000-8000-000000000002'::uuid END, + 'synthetic message ' || g, + timestamptz '2026-01-01' + (g * interval '1 second') + (c.n * interval '1 millisecond') +FROM (SELECT n, CASE WHEN n = 0 THEN 20000 ELSE 1000 END AS cnt FROM generate_series(0, 50) n) c +CROSS JOIN LATERAL generate_series(1, c.cnt) g +ON CONFLICT DO NOTHING; + +ANALYZE users; ANALYZE chats; ANALYZE chat_members; ANALYZE messages; +SQL + +{ + echo "# EXPLAIN evidence for message history pagination" + echo "# date: $(date -u +%Y-%m-%dT%H:%M:%SZ) commit: $(git rev-parse --short HEAD 2>/dev/null || echo n/a)" + echo "# postgres: $($PSQL -tA -c 'SHOW server_version')" + $PSQL -tA -c "SELECT '# messages total: ' || count(*) || ', in measured chat: ' || count(*) FILTER (WHERE chat_id = '00000000-0000-4000-8000-000000000100') FROM messages" + echo + $PSQL <<'SQL' +-- The same statements as app/storage.py (Store.list_messages), as prepared statements. +PREPARE first_page(uuid, int) AS + SELECT id, chat_id, sender_id, text, created_at FROM messages + WHERE chat_id = $1 ORDER BY created_at, id LIMIT $2; +PREPARE next_page(uuid, timestamptz, uuid, int) AS + 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; + +\echo '=== 1. WITH index messages_chat_history_idx: first page (limit 50 + 1) ===' +EXPLAIN (ANALYZE, BUFFERS) EXECUTE first_page('00000000-0000-4000-8000-000000000100', 51); + +\echo '=== 2. WITH index: deep page, cursor after message #15000 of 20000 ===' +EXPLAIN (ANALYZE, BUFFERS) EXECUTE next_page('00000000-0000-4000-8000-000000000100', + timestamptz '2026-01-01' + interval '15000 seconds', md5('explain-0-15000')::uuid, 51); + +-- Same queries without the index, inside a transaction that is rolled back. +BEGIN; +DROP INDEX messages_chat_history_idx; +\echo '=== 3. WITHOUT index: first page ===' +EXPLAIN (ANALYZE, BUFFERS) EXECUTE first_page('00000000-0000-4000-8000-000000000100', 51); +\echo '=== 4. WITHOUT index: deep page ===' +EXPLAIN (ANALYZE, BUFFERS) EXECUTE next_page('00000000-0000-4000-8000-000000000100', + timestamptz '2026-01-01' + interval '15000 seconds', md5('explain-0-15000')::uuid, 51); +ROLLBACK; +SQL +} > "$OUT" + +echo "written $OUT" +grep -E '^===|Index|Seq Scan|Sort|Buffers|Execution Time' "$OUT" diff --git a/student-tests/own_tests.py b/student-tests/own_tests.py new file mode 100755 index 00000000..56c7c022 --- /dev/null +++ b/student-tests/own_tests.py @@ -0,0 +1,120 @@ +#!/usr/bin/env python3 +"""Student-written negative/edge-case tests, additional to the public tests/smoke.py. + +Covers level-4 requirements from README.md: +- malformed JSON +- foreign chat access +- empty message text +- duplicate username +- multi-page pagination traversal +""" +import json +import sys +import urllib.error +import urllib.parse +import urllib.request +from pathlib import Path + +ROOT = Path(__file__).resolve().parents[1] +sys.path.insert(0, str(ROOT / "tests")) +from client import Client, check # noqa: E402 + +PASSED = 0 + + +def ok(label): + global PASSED + PASSED += 1 + print("ok -", label) + + +def raw_call(base, method, path, data=None, headers=None): + h = {"Accept": "application/json"} + h.update(headers or {}) + req = urllib.request.Request(base + path, data=data, headers=h, method=method) + try: + resp = urllib.request.urlopen(req, timeout=10) + except urllib.error.HTTPError as exc: + resp = exc + with resp: + return resp.code, resp.read() + + +def main(): + base_url = sys.argv[1] if len(sys.argv) > 1 else "http://localhost:8080" + c = Client(base_url) + alice, bob, eve, chat = c.bootstrap() + path = "/api/v1/chats/" + chat["id"] + + # 1. Malformed JSON body -> 400 invalid_request, not a 500. + status, body = raw_call( + base_url, "POST", "/api/v1/users", + data=b'{"username": "broken", "display_name": ', + headers={"Content-Type": "application/json", "X-User-Id": alice["id"]}, + ) + check(status == 400, "malformed JSON must yield 400, got %d" % status) + parsed = json.loads(body) + check(parsed["error"]["code"] == "invalid_request", "malformed JSON must report invalid_request") + ok("malformed JSON -> 400 invalid_request") + + # 2. Foreign chat: eve is not a member -> 404, not 403 (no existence leak). + c.call("GET", path, 404, actor=eve) + c.call("GET", path + "/messages", 404, actor=eve) + ok("foreign chat access -> 404 (no leak)") + + # 3. Empty / whitespace-only message text -> 400. + c.call("POST", path + "/messages", 400, actor=alice, body={"text": ""}) + c.call("POST", path + "/messages", 400, actor=alice, body={"text": " "}) + ok("empty/whitespace message text -> 400") + + # 4. Duplicate username -> 409 conflict, original user untouched. + c.call("POST", "/api/v1/users", 409, body=alice["registration"]) + me = c.call("GET", "/api/v1/users/me", actor=alice, schema="User")["json"] + check(me == alice["user"], "existing user must be unaffected by a rejected duplicate registration") + ok("duplicate username -> 409, original user intact") + + # 5. Multi-page pagination traversal: write N messages, walk every page with a small + # limit and confirm the full, ordered, duplicate-free set is recovered. + sent = [c.message(alice, chat, "page-msg-%d" % i)["json"] for i in range(7)] + collected = [] + cursor = None + pages = 0 + while True: + qs = "?limit=2" + ("&cursor=" + urllib.parse.quote(cursor, safe="") if cursor else "") + page = c.call("GET", path + "/messages" + qs, actor=bob, schema="MessagePage")["json"] + pages += 1 + check(len(page["items"]) <= 2, "page must respect limit") + collected.extend(page["items"]) + cursor = page["next_cursor"] + if not cursor: + break + check(pages < 50, "pagination did not terminate") + ids_seen = [m["id"] for m in collected] + check(len(ids_seen) == len(set(ids_seen)), "pagination must not repeat messages") + check({m["id"] for m in sent}.issubset(set(ids_seen)), "pagination must not drop messages") + tail = [m for m in collected if m["id"] in {s["id"] for s in sent}] + check(tail == sorted(tail, key=lambda m: (m["created_at"], m["id"])), "pagination must stay ordered") + ok("multi-page pagination traversal: %d pages, %d messages, no dup/loss" % (pages, len(collected))) + + # 6. A cursor is bound to the chat it was issued for: reusing it on a + # different chat the same actor can also read must be rejected. + first_page = c.call("GET", path + "/messages?limit=1", actor=alice, schema="MessagePage")["json"] + check(first_page["next_cursor"], "need a non-null cursor to test cross-chat reuse") + chat2 = c.call( + "POST", "/api/v1/chats", 201, actor=alice, + body={"title": "second chat", "member_ids": [alice["id"], bob["id"]]}, schema="Chat", + )["json"] + c.message(alice, chat2, "unrelated message") + foreign_cursor = urllib.parse.quote(first_page["next_cursor"], safe="") + c.call("GET", "/api/v1/chats/" + chat2["id"] + "/messages?limit=1&cursor=" + foreign_cursor, 400, actor=alice) + ok("cursor from another chat -> 400 (cursor is bound to its resource)") + + print("PASS: %d/%d student checks" % (PASSED, 6)) + + +if __name__ == "__main__": + try: + main() + except AssertionError as exc: + print("FAIL:", exc) + raise SystemExit(1) diff --git a/student-tests/run_all.sh b/student-tests/run_all.sh new file mode 100755 index 00000000..d348ec24 --- /dev/null +++ b/student-tests/run_all.sh @@ -0,0 +1,24 @@ +#!/bin/sh +# All student tests in one command. Needs the running compose stack; starts the +# short-TTL instance itself. dependency_test/sigterm_test STOP AND START containers. +# Usage: BASE_URL=http://localhost:8080 student-tests/run_all.sh +set -eu + +cd "$(dirname "$0")/.." +PY="${PYTHON:-python3}" +export BASE_URL="${BASE_URL:-http://localhost:8080}" +export SHORT_TTL_URL="${SHORT_TTL_URL:-http://localhost:8081}" + +docker compose --profile ttl-test up -d --no-build --wait api-short-ttl >/dev/null 2>&1 + +for t in own_tests.py concurrency_test.py auth_test.py db_integrity_test.py dependency_test.py; do + echo "== $t" + "$PY" "student-tests/$t" "$BASE_URL" + echo +done +echo "== sigterm_test.sh" +sh student-tests/sigterm_test.sh + +docker compose --profile ttl-test stop api-short-ttl >/dev/null 2>&1 +echo +echo "ALL STUDENT TESTS PASSED" diff --git a/student-tests/sigterm_test.sh b/student-tests/sigterm_test.sh new file mode 100755 index 00000000..b6016a5e --- /dev/null +++ b/student-tests/sigterm_test.sh @@ -0,0 +1,19 @@ +#!/bin/sh +# Graceful shutdown of the compose api service: SIGTERM -> exit 0 within 10s +# (not SIGKILL 137), then the service is started again. Volumes are untouched. +set -eu + +cd "$(dirname "$0")/.." +CID=$(docker compose ps -q api) +[ -n "$CID" ] || { echo "FAIL: api is not running"; exit 1; } + +START=$(date +%s) +docker compose stop api >/dev/null 2>&1 +ELAPSED=$(( $(date +%s) - START )) +EXIT_CODE=$(docker inspect -f '{{.State.ExitCode}}' "$CID") +echo "api stopped in ${ELAPSED}s, exit code ${EXIT_CODE} (0 = graceful, 137 = SIGKILL)" +docker compose logs --since 30s api 2>&1 | grep -q "Application shutdown complete" || { echo "FAIL: no graceful shutdown line"; exit 1; } +[ "$ELAPSED" -le 10 ] && [ "$EXIT_CODE" -eq 0 ] || { docker compose up -d --wait api; echo "FAIL: not graceful"; exit 1; } + +docker compose up -d --no-build --wait api >/dev/null 2>&1 +echo "PASS: graceful SIGTERM shutdown, api restarted" diff --git a/student-tests/stack.py b/student-tests/stack.py new file mode 100755 index 00000000..df5d3c94 --- /dev/null +++ b/student-tests/stack.py @@ -0,0 +1,47 @@ +"""Shared helpers for student tests: public client + direct access to the compose stack.""" +import os +import subprocess +import sys +from pathlib import Path + +ROOT = Path(__file__).resolve().parents[1] +sys.path.insert(0, str(ROOT / "tests")) +from client import Client, Failure, check # noqa: E402,F401 + +BASE_URL = os.environ.get("BASE_URL", "http://localhost:8080") +SHORT_TTL_URL = os.environ.get("SHORT_TTL_URL", "http://localhost:8081") + +PASSED = [] + + +def ok(label): + PASSED.append(label) + print("ok -", label) + + +def compose(*args, check_rc=True): + """docker compose in the repository root; output is captured, never printed raw.""" + proc = subprocess.run(["docker", "compose", *args], cwd=ROOT, capture_output=True, text=True) + if check_rc and proc.returncode != 0: + raise Failure("docker compose %s failed: %s" % (args[0], proc.stderr.strip()[-300:])) + return proc.stdout + + +def psql(sql): + """Run SQL inside the postgres container (local socket, no password on the wire).""" + return compose("exec", "-T", "postgres", "psql", "-U", "messenger", "-d", "messenger", "-tAX", "-c", sql).strip() + + +def valkey(*args): + """valkey-cli with the password read inside the container, never on this host's argv.""" + cmd = 'valkey-cli --no-auth-warning -a "$(sed -n "s/^requirepass //p" /run/secrets/valkey_conf)" "$@"' + return compose("exec", "-T", "valkey", "sh", "-c", cmd, "valkey-cli", *args).strip() + + +def main_wrapper(main): + try: + main() + except (AssertionError, Failure) as exc: + print("FAIL:", exc) + raise SystemExit(1) + print("PASS: %d checks" % len(PASSED)) -- 2.54.0 From 13fa1852cb226197a25269a2021755b55cab3efd Mon Sep 17 00:00:00 2001 From: Ilya <145450507+IIcon18@users.noreply.github.com> Date: Fri, 9 Oct 2026 12:44:56 +0300 Subject: [PATCH 2/3] =?UTF-8?q?=D0=B2=D1=8B=D0=BF=D0=BE=D0=BB=D0=BD=D0=B5?= =?UTF-8?q?=D0=BD=D0=B8=D0=B5=20=D0=BB=D1=802=20=D0=BD=D0=B0=204?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .env.example | 3 - DEMO.md | 526 +++++++++++++++++++++++++++++ Makefile | 1 - REPORT.md | 4 +- app/auth.py | 16 +- app/cache.py | 12 - app/config.py | 5 - app/errors.py | 1 - app/main.py | 37 +- app/migrate.py | 5 - app/models.py | 1 - app/storage.py | 26 +- compose.yaml | 7 - evidence/explain_history.txt | 56 +-- evidence/fresh_migrations.txt | 6 +- evidence/persistence.txt | 14 +- evidence/smoke.txt | 2 +- evidence/student_tests.txt | 9 +- migrations/0001_init.sql | 9 - scripts/init-secrets.sh | 4 - scripts/restart.sh | 3 - student-tests/auth_test.py | 8 - student-tests/concurrency_test.py | 7 +- student-tests/db_integrity_test.py | 6 - student-tests/dependency_test.py | 18 +- student-tests/explain_history.sh | 7 - student-tests/own_tests.py | 19 +- student-tests/run_all.sh | 3 - student-tests/sigterm_test.sh | 2 - student-tests/stack.py | 6 +- 30 files changed, 585 insertions(+), 238 deletions(-) create mode 100644 DEMO.md diff --git a/.env.example b/.env.example index 623ea676..c467d5d9 100644 --- a/.env.example +++ b/.env.example @@ -9,9 +9,6 @@ DATABASE_URL_FILE=/run/secrets/database_url # Optional on 3, required use on 4 in lab2; Redis OR Valkey: SESSION_STORE=postgres CACHE_URL_FILE=/run/secrets/cache_url -# --- Actual lab2 implementation (see REPORT.md) --- -# APP_PORT is also the host port published on 127.0.0.1 by compose.yaml. -# SESSION_STORE=postgres: sessions live in PostgreSQL; Valkey (CACHE_URL_FILE) caches lookups. SESSION_CACHE_MAX_SECONDS=300 DB_POOL_MAX=10 SHORT_TTL_PORT=8081 diff --git a/DEMO.md b/DEMO.md new file mode 100644 index 00000000..520936b3 --- /dev/null +++ b/DEMO.md @@ -0,0 +1,526 @@ +# Демонстрация лабораторной 2 на защите + +Сценарий повторяет раздел «Сценарий защиты» из README: стек поднимается с нуля на пустом volume, затем показываются сессии, сохранность после рестарта, роль Valkey, план SQL и отказы зависимостей. + +**Важно:** выполняйте команды по порядку **в одном окне терминала**. Переменные `B`, `S`, `ALICE`, `BOB`, `CAROL`, `CHAT`, `TA`, `TB`, `TC` и функции `j`, `pg`, `vk` живут только в этом окне. + +--- + +## 0. Подготовка: чистый clone + +Если запущен рабочий стенд, останавливаем его. Volume при этом сохраняется, порт 8080 освобождается: + +```bash +(cd ~/Desktop/вуз/ВНП/lab2/mtusi2026lab2 && docker compose --profile ttl-test down) +``` + +Скачиваем решение в новую папку: + +```bash +git clone -b solution/bvt2304-koshelev ssh://git@gitea.privcloud.tech:2222/Iicon18/mtusi2026lab2.git ~/Desktop/lab2-demo +``` + +```bash +cd ~/Desktop/lab2-demo +``` + +Отдельное имя compose-проекта даёт отдельные контейнеры и **новый пустой volume**: + +```bash +export COMPOSE_PROJECT_NAME=lab2-demo +``` + +```bash +cp .env.example .env +``` + +Если порт 8080 или 8081 занят, поменяйте `APP_PORT` / `SHORT_TTL_PORT` в `.env`, следующая команда сама подхватит новые значения. + +```bash +B=http://127.0.0.1:$(sed -n 's/^APP_PORT=//p' .env); S=http://127.0.0.1:$(sed -n 's/^SHORT_TTL_PORT=//p' .env); echo "$B $S" +``` + +Вспомогательные функции: достать поле из JSON, выполнить SQL, выполнить команду Valkey. + +```bash +j() { python3 -c 'import sys,json;print(json.load(sys.stdin)[sys.argv[1]])' "$1"; } +pg() { docker compose exec -T postgres psql -U messenger -d messenger -c "$1"; } +vk() { docker compose exec -T valkey sh -c 'valkey-cli --no-auth-warning -a "$(sed -n "s/^requirepass //p" /run/secrets/valkey_conf)" "$@"' valkey-cli "$@"; } +``` + +> **Сказать:** «Это свежий clone моей ветки в отдельный compose-проект, база будет пустой. `.env` и секреты не хранятся в Git, создаю их локально». + +--- + +## 1. Секреты + +```bash +make secrets +``` + +```bash +ls -l secrets/ +``` + +```bash +git check-ignore -v secrets/database_url .env +``` + +> **Сказать:** +> - «`scripts/init-secrets.sh` генерирует случайные пароли PostgreSQL и Valkey в папку `secrets/`. Она в `.gitignore`, поэтому в репозиторий не попадает». +> - «В контейнеры пароли приходят как compose secrets, файлами в `/run/secrets/...`, а не переменными окружения. Поэтому их не видно в `docker inspect`». +> - «Приложение читает `DATABASE_URL_FILE` и `CACHE_URL_FILE`, то есть путь к файлу, а не сам пароль». + +--- + +## 2. Запуск стека и миграции + +```bash +cat compose.yaml +``` + +> **Сказать:** +> - «Четыре сервиса: `postgres` — источник истины, `valkey` — кэш сессий, `migrate` — одноразовый запуск миграций, `api` — приложение». +> - «Версии образов закреплены: `postgres:17.6-alpine3.22`, `valkey/valkey:8.1.4-alpine3.22`; `latest` нигде нет». +> - «`depends_on` с условиями: api стартует, только когда postgres `healthy`, а migrate завершился с кодом 0». +> - «Данные PostgreSQL лежат в именованном volume `pgdata`». +> - «Порт api опубликован только на `127.0.0.1`, порты БД и Valkey наружу не публикуются». + +```bash +make up +``` + +```bash +docker compose ps --all +``` + +```bash +docker compose logs migrate +``` + +```bash +curl -si "$B/health/ready" +``` + +> **Сказать:** +> - «`make up` = `docker compose up -d --build --wait`, ждёт, пока healthcheck api станет healthy. Healthcheck api проверяет `/health/ready`, а readiness делает `SELECT 1` в PostgreSQL». +> - «`migrate` в статусе `Exited (0)`: применил `0001_init` на пустую базу (`1 applied now, 0 before`)». + +--- + +## 3. Схема БД + +```bash +pg '\dt' +``` + +```bash +pg '\d messages' +``` + +```bash +pg 'SELECT * FROM schema_migrations' +``` + +> **Сказать:** +> - «Таблицы `users`, `chats`, `chat_members`, `messages`, `sessions` и служебная `schema_migrations`, где записаны применённые миграции». +> - «`UNIQUE(username)`, CHECK на формат и длины». +> - «Внешний ключ `messages (chat_id, sender_id) → chat_members`: база сама не даст записать сообщение от не-участника». +> - «Индекс `messages_chat_history_idx (chat_id, created_at, id)` повторяет запрос истории, обоснование в шаге 12». +> - «Миграции версионируются. Раннер берёт `pg_advisory_lock` и пропускает уже применённые версии, поэтому повторный запуск безопасен». + +--- + +## 4. Публичный тест + +```bash +make check +``` + +```bash +make test BASE_URL="$B" +``` + +> **Сказать:** «Это публичный smoke-тест преподавателя для lab2: регистрация с паролем, вход через Basic, работа по Bearer, чаты, сообщения, пагинация, ошибки и logout». + +--- + +## 5. Регистрация, вход, общий чат + +Регистрация теперь требует `password` (12–128 символов): + +```bash +ALICE=$(curl -s -X POST "$B/api/v1/users" -H 'Content-Type: application/json' -d '{"username":"alice","display_name":"Алиса","password":"Alice-demo-pass-1"}' | tee /dev/stderr | j id) +``` + +```bash +BOB=$(curl -s -X POST "$B/api/v1/users" -H 'Content-Type: application/json' -d '{"username":"bob","display_name":"Боб 🚀","password":"Bob-demo-pass-123"}' | tee /dev/stderr | j id) +``` + +```bash +CAROL=$(curl -s -X POST "$B/api/v1/users" -H 'Content-Type: application/json' -d '{"username":"carol","display_name":"Кэрол","password":"Carol:with:colons"}' | tee /dev/stderr | j id) +``` + +> **Сказать:** «В ответе нет ни пароля, ни хеша, только `id`, `username`, `display_name`, `created_at`. Время назначает PostgreSQL». + +Пароль в базе хранится только как хеш: + +```bash +pg "SELECT username, left(password_hash, 40) AS hash FROM users WHERE username IN ('alice','bob','carol')" +``` + +> **Сказать:** «Хеш Argon2id, строка начинается с `$argon2id$v=19$m=65536,t=3,p=4`: 64 МБ памяти и 3 прохода на одну проверку. Соль своя у каждого пароля, поэтому одинаковые пароли дают разные хеши». + +Вход: Basic только на `POST /auth/sessions`. `curl -u` сам собирает заголовок `Authorization: Basic base64(username:password)`: + +```bash +curl -si -X POST -u 'carol:Carol:with:colons' "$B/api/v1/auth/sessions" +``` + +```bash +TA=$(curl -s -X POST -u 'alice:Alice-demo-pass-1' "$B/api/v1/auth/sessions" | j token); TB=$(curl -s -X POST -u 'bob:Bob-demo-pass-123' "$B/api/v1/auth/sessions" | j token); TC=$(curl -s -X POST -u 'carol:Carol:with:colons' "$B/api/v1/auth/sessions" | j token); echo "длина токена: ${#TA}" +``` + +> **Сказать:** +> - «Ответ 201: `token`, `token_type: Bearer`, `expires_at`, `user`. Двоеточие в пароле допустимо, потому что строка делится по **первому** `:`». +> - «Токен — `secrets.token_urlsafe(32)`, 256 случайных бит. Он непрозрачный: внутри нет ни id, ни username, это не JWT». +> - «Срок жизни из `SESSION_TTL_SECONDS` (по умолчанию 3600 с), `expires_at` считает база». + +В базе лежит не сам токен, а его sha256: + +```bash +pg "SELECT encode(token_hash,'hex') AS token_hash, expires_at, revoked_at FROM sessions ORDER BY created_at DESC LIMIT 3" +``` + +> **Сказать:** «Если украдут дамп БД, войти по нему не получится: из sha256 токен не восстановить. Медленный KDF для токена не нужен: он случайный, 2^256 вариантов не перебрать. Пароль же выбирает человек, его можно перебрать по словарю, поэтому для пароля нужен медленный Argon2id». + +Алиса создаёт чат с Бобом, оба пишут: + +```bash +CHAT=$(curl -s -X POST "$B/api/v1/chats" -H 'Content-Type: application/json' -H "Authorization: Bearer $TA" -d "{\"title\":\"Проект по ВНП\",\"member_ids\":[\"$ALICE\",\"$BOB\"]}" | tee /dev/stderr | j id) +``` + +```bash +curl -s -X POST "$B/api/v1/chats/$CHAT/messages" -H 'Content-Type: application/json' -H "Authorization: Bearer $TA" -d '{"text":"Привет, Боб! 👋"}' +``` + +```bash +curl -s -X POST "$B/api/v1/chats/$CHAT/messages" -H 'Content-Type: application/json' -H "Authorization: Bearer $TB" -d '{"text":"Привет, Алиса!"}' +``` + +```bash +curl -s "$B/api/v1/chats/$CHAT/messages" -H "Authorization: Bearer $TB" | python3 -m json.tool --no-ensure-ascii +``` + +> **Сказать:** +> - «Чат и участники создаются **одной транзакцией**. Если участник неизвестен, FK срабатывает внутри транзакции, вставка чата откатывается и клиент получает 400. Полупустого чата не остаётся (проверяет `db_integrity_test.py`)». +> - «`sender_id` сервер берёт из сессии. Сообщение вставляется одним запросом `INSERT … WHERE EXISTS (участник)`: проверка доступа и запись атомарны». + +Кэрол аутентифицирована, но не участник чата: + +```bash +curl -i "$B/api/v1/chats/$CHAT/messages" -H "Authorization: Bearer $TC" +``` + +> **Сказать:** «Аутентификация отвечает на вопрос "кто ты": токен Кэрол валиден. Доступ отвечает на вопрос "можно ли тебе в этот чат": нельзя, поэтому 404, а не 403, чтобы не раскрывать, что такой чат существует». + +--- + +## 6. Ошибки аутентификации + +Неверный пароль и несуществующий пользователь дают одинаковый 401 с вызовом `Basic`: + +```bash +curl -i -X POST -u 'alice:wrong-password-1' "$B/api/v1/auth/sessions" +``` + +```bash +curl -i -X POST -u 'nobody:wrong-password-1' "$B/api/v1/auth/sessions" +``` + +> **Сказать:** «Ответы одинаковые, поэтому подобрать существующие username не выйдет. Для несуществующего пользователя всё равно проверяется фиктивный хеш, чтобы время ответа тоже было одинаковым». + +Basic на бизнес-endpoint даёт 401 с вызовом `Bearer`: + +```bash +curl -i -u 'alice:Alice-demo-pass-1' "$B/api/v1/users/me" +``` + +`X-User-Id` из lab1 больше ничего не значит: + +```bash +curl -i "$B/api/v1/users/me" -H "X-User-Id: $ALICE" +``` + +```bash +curl -s "$B/api/v1/users/me" -H "Authorization: Bearer $TC" -H "X-User-Id: $ALICE" +``` + +> **Сказать:** «Без токена `X-User-Id` даёт 401. С токеном Кэрол и `X-User-Id` Алисы ответ — Кэрол: заголовок просто игнорируется». + +Короткий пароль при регистрации даёт 400: + +```bash +curl -i -X POST "$B/api/v1/users" -H 'Content-Type: application/json' -d '{"username":"dave","display_name":"Дэйв","password":"short"}' +``` + +--- + +## 7. Роль Valkey: кэш сессий + +Все ключи сессий: сколько секунд осталось жить и значение. + +```bash +for k in $(vk --scan --pattern 'session:*'); do echo "$(vk TTL "$k")s $(vk GET "$k" | cut -c1-70)"; done +``` + +> **Сказать:** +> - «Строки `{"user": …}` — закэшированные живые сессии. Строки `revoked` — tombstone'ы после logout, например от smoke-теста в шаге 4 (подробно в шаге 9)». +> - «**Источник истины — PostgreSQL**. Valkey только кэширует проверку токена, чтобы не ходить в БД на каждом запросе. `/users/me` вообще обслуживается из кэша». +> - «Ключ — `session:` + sha256 токена, значение — пользователь и `expires_at`». +> - «TTL записи = min(остаток сессии, 300 с). При чтении из кэша `expires_at` сравнивается ещё раз, поэтому просроченная сессия из кэша не пройдёт». +> - «Persistence у Valkey выключена (`save ""`, `appendonly no`). После flush или рестарта кэш просто пуст: следующий запрос проверит токен в PostgreSQL и снова положит его в кэш. Данные при этом не теряются». + +--- + +## 8. Сохранность: рестарт API и всех хранилищ + +```bash +cat scripts/restart.sh +``` + +```bash +docker compose ps --format 'table {{.Service}}\t{{.Status}}' +``` + +```bash +make test-persistence ACTION_SCRIPT=scripts/restart.sh BASE_URL="$B" +``` + +```bash +docker compose ps --format 'table {{.Service}}\t{{.Status}}' +``` + +> **Сказать:** «Тест держит токен только в памяти, вызывает мой `restart.sh` (остановить api, valkey и postgres, затем поднять заново, volume не трогается) и тем же токеном читает те же данные. По `Up N seconds` видно, что все три контейнера действительно перезапускались». + +Проверим руками тем же токеном Алисы: + +```bash +vk DBSIZE +``` + +```bash +curl -s "$B/api/v1/chats/$CHAT/messages" -H "Authorization: Bearer $TA" | python3 -m json.tool --no-ensure-ascii +``` + +```bash +docker compose logs migrate | tail -1 +``` + +> **Сказать:** +> - «Прежний токен работает, сообщения на месте. Сессия пережила рестарт, потому что хранится в PostgreSQL. Срок не продлился: `expires_at` записан в базе». +> - «Старые записи кэша пропали вместе с рестартом Valkey. Те несколько ключей, что видны в `DBSIZE`, заново положили проверочные запросы теста после рестарта: кэш наполняется сам из PostgreSQL». +> - «Миграции при рестарте прогнались ещё раз: `0 applied now, 1 before`, без дублирования». +> - «Ответ на вопрос "что подтверждает COMMIT": запись попала в WAL и сброшена на диск (`fsync=on`, `synchronous_commit=on` по умолчанию). Поэтому 201 после COMMIT означает, что сообщение переживёт и падение PostgreSQL. Если выключить `synchronous_commit`, последние подтверждённые транзакции можно потерять». + +--- + +## 9. Logout + +```bash +curl -i -X DELETE "$B/api/v1/auth/sessions/current" -H "Authorization: Bearer $TC" +``` + +```bash +curl -i "$B/api/v1/users/me" -H "Authorization: Bearer $TC" +``` + +```bash +curl -i -X DELETE "$B/api/v1/auth/sessions/current" -H "Authorization: Bearer $TC" +``` + +```bash +for k in $(vk --scan --pattern 'session:*'); do echo "$k => $(vk GET "$k" | cut -c1-40)"; done +``` + +> **Сказать:** +> - «Logout даёт 204 без тела. После него тот же токен получает 401, повторный logout тоже 401». +> - «Порядок такой: сначала `revoked_at` в PostgreSQL (источник истины), потом в Valkey пишется **tombstone** `revoked`, а не простое удаление ключа». +> - «Зачем tombstone: параллельный запрос мог прочитать сессию из БД **до** logout и положить её в кэш **после**. Кэш заполняется через `SET NX` и не перезапишет tombstone, поэтому отозванная сессия не воскреснет». + +--- + +## 10. Истечение сессии (короткий TTL) + +Поднимаем второй экземпляр того же образа с `SESSION_TTL_SECONDS=2`: + +```bash +docker compose --profile ttl-test up -d --wait api-short-ttl +``` + +Вход и обе проверки одной строкой: окно в 2 секунды слишком короткое, чтобы успеть вставить отдельные команды. + +```bash +TD=$(curl -s -X POST -u 'bob:Bob-demo-pass-123' "$S/api/v1/auth/sessions" | tee /dev/stderr | j token); echo; curl -s -o /dev/null -w 'сразу: %{http_code}\n' "$S/api/v1/users/me" -H "Authorization: Bearer $TD"; sleep 3; curl -si "$S/api/v1/users/me" -H "Authorization: Bearer $TD" +``` + +```bash +docker compose --profile ttl-test stop api-short-ttl +``` + +> **Сказать:** «`expires_at` всего через 2 секунды после входа. Сразу 200, через 3 секунды 401 с `WWW-Authenticate: Bearer`, хотя запись была и в кэше. Обычный api работает с TTL 3600, так как smoke требует не меньше 300». + +--- + +## 11. Отказы зависимостей + +### Valkey недоступен — API работает без кэша + +```bash +docker compose stop valkey +``` + +```bash +curl -si "$B/health/ready" +``` + +```bash +time curl -s "$B/api/v1/users/me" -H "Authorization: Bearer $TA" +``` + +```bash +curl -s -o /dev/null -w '%{http_code}\n' "$B/api/v1/users/me" -H "Authorization: Bearer $TC" +``` + +```bash +docker compose logs --tail 3 api +``` + +```bash +docker compose start valkey +``` + +> **Сказать:** +> - «Readiness 200: Valkey для API не критичен». +> - «Запросы идут напрямую в PostgreSQL, ответ за миллисекунды. Остановленный контейнер сразу отказывает в соединении. Если бы сеть зависла, сработал бы таймаут 0.3 с. После первой ошибки circuit breaker 5 секунд вообще не обращается к Valkey, поэтому задержка не копится. В логе предупреждение `bypassing cache`». +> - «Отозванный токен Кэрол по-прежнему 401: отзыв записан в БД». + +### PostgreSQL недоступен — ограниченная ошибка, анонимного доступа нет + +Заранее берём новый токен Боба. Проверок по нему ещё не было, поэтому в кэше его нет: + +```bash +TB2=$(curl -s -X POST -u 'bob:Bob-demo-pass-123' "$B/api/v1/auth/sessions" | j token) +``` + +```bash +docker compose stop postgres +``` + +```bash +curl -si "$B/health/live"; echo; curl -si "$B/health/ready" +``` + +```bash +curl -si "$B/api/v1/chats" -H "Authorization: Bearer $TA" +``` + +```bash +curl -s -o /dev/null -w '%{http_code}\n' "$B/api/v1/users/me" -H "Authorization: Bearer $TB2"; curl -s -o /dev/null -w '%{http_code}\n' "$B/api/v1/users/me" +``` + +> **Сказать:** +> - «Liveness 200: процесс жив. Readiness 503: обслуживать запросы безопасно нельзя». +> - «Бизнес-запрос даёт `503 unavailable` мгновенно, без SQL и стектрейсов в теле. Pool ограничен 10 соединениями, таймауты подключения, захвата соединения и команды — 3, 3 и 5 с, так что зависнуть запрос не может». +> - «Токен, который проверить негде (в кэше его нет, БД лежит), получает **503, а не 200**: непроверенный запрос не считается аутентифицированным. Без токена — по-прежнему 401». + +```bash +docker compose start postgres +``` + +```bash +until curl -s -o /dev/null -w '%{http_code}' "$B/health/ready" | grep -q 200; do sleep 0.5; done; echo ready +``` + +```bash +curl -s "$B/api/v1/users/me" -H "Authorization: Bearer $TB2" +``` + +> **Сказать:** «API восстановился сам, без своего рестарта: pool переподключается к базе по требованию». + +--- + +## 12. Индекс истории и EXPLAIN + +```bash +make explain +``` + +```bash +cat evidence/explain_history.txt +``` + +> **Сказать:** +> - «Скрипт засевает 70 000 синтетических сообщений, 20 000 из них в одном чате, и выполняет **тот же запрос, что в коде**, как prepared statement: `WHERE chat_id = $1 AND (created_at, id) > ($2, $3) ORDER BY created_at, id LIMIT 51`». +> - «С индексом `(chat_id, created_at, id)`: `Index Scan`, условие по курсору уходит прямо в `Index Cond`, читается 4 буфера, около 0.03 мс. Даже на глубокой странице после 15 000-го сообщения работа та же». +> - «Без индекса (DROP INDEX внутри транзакции и ROLLBACK): `Seq Scan` по всей таблице и `Sort`, 940 буферов, 3–4 мс, и время растёт вместе с таблицей». +> - «Keyset против OFFSET: `OFFSET 15000` заставил бы прочитать и выбросить 15 000 строк на каждой странице. Курсор сразу прыгает в нужное место индекса». + +--- + +## 13. Уровень 4: свои тесты одной командой + +```bash +make test-student BASE_URL="$B" SHORT_TTL_URL="$S" +``` + +> **Сказать:** +> - **own_tests.py**, **concurrency_test.py** — перенесены из lab1: битый JSON, чужой чат, пустое сообщение, пагинация; 100 параллельных сообщений от 10 клиентов. +> - **auth_test.py** — неверный пароль, Basic и `X-User-Id` на бизнес-endpoint, пароль с `:` и UTF-8, logout только текущего токена, истечение при TTL=2 с. +> - **db_integrity_test.py**: +> - 20 параллельных регистраций одного username → ровно один 201 и девятнадцать 409. Гонку решает `UNIQUE` в БД, а не проверка "SELECT, потом INSERT"; +> - rollback создания чата; +> - Argon2id в базе; +> - повторные миграции ничего не меняют. +> - **dependency_test.py** — роль Valkey (кэш, TTL, tombstone), остановка Valkey, остановка PostgreSQL и восстановление. +> - **sigterm_test.sh** — `docker compose stop api` → код выхода 0, а не 137. + +--- + +## 14. Остановка и удаление данных + +Обычная остановка: данные остаются в volume. + +```bash +docker compose --profile ttl-test down +``` + +```bash +docker volume ls | grep lab2-demo +``` + +Намеренное удаление учебных данных демо-стенда (необратимо): + +```bash +docker compose --profile ttl-test down -v +``` + +> **Сказать:** «`down` удаляет контейнеры, но не volume, поэтому данные переживут и это. Только `down -v` удаляет volume. В `restart.sh` и тестах `-v` не используется нигде». + +--- + +## Короткие ответы на вопросы из README + +- **Что подтверждает COMMIT и от чего зависят гарантии.** + - COMMIT значит, что транзакция записана в WAL и, при `synchronous_commit=on` и `fsync=on` (по умолчанию), сброшена на диск. Такая запись переживает падение процесса и рестарт ОС. + - С `synchronous_commit=off` последние подтверждённые транзакции можно потерять. С `fsync=off` после сбоя питания можно повредить базу. + - Потерю самого диска или хоста COMMIT не покрывает: нужны реплики и бэкапы. +- **Где хранятся сессии и что будет после flush или рестарта Redis.** + - Сессии хранятся в PostgreSQL, в таблице `sessions` (`sha256(token)`, `expires_at`, `revoked_at`). Valkey только кэш. + - После flush кэш пуст, первая проверка токена идёт в БД. Ни одна сессия не теряется и не воскрешается: отзыв тоже записан в БД. Поэтому persistence у Valkey не нужна. +- **Аутентификация против доступа к чату.** + - Аутентификация устанавливает, кто ты: валидный Bearer-токен, иначе 401. + - Доступ (авторизация) решает, можно ли этому пользователю к этому ресурсу: участник ли он чата. Если нет — 404, а не 403, чтобы не раскрывать существование чата. +- **Hash пароля против быстрого checksum.** + - Быстрый хеш (sha256) нужен для целостности и для индексации случайных значений: так мы храним токены. + - Пароль низкоэнтропийный, его подбирают по словарю. Для него нужен медленный KDF с солью и затратами памяти (Argon2id), чтобы каждая попытка подбора была дорогой даже на GPU. diff --git a/Makefile b/Makefile index 51336484..549992b9 100644 --- a/Makefile +++ b/Makefile @@ -25,7 +25,6 @@ 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) -# --- Student implementation helpers (see REPORT.md) --- secrets: sh scripts/init-secrets.sh diff --git a/REPORT.md b/REPORT.md index 4767fe8c..7fb98fe2 100644 --- a/REPORT.md +++ b/REPORT.md @@ -16,7 +16,7 @@ | valkey | `valkey/valkey:8.1.4-alpine3.22` | Valkey 8.1.4 | ```sh -cp .env.example .env # при занятом 8080 поменять APP_PORT (у автора 18080) +cp .env.example .env # при занятом 8080 поменять APP_PORT make secrets # scripts/init-secrets.sh: случайные пароли в ./secrets (в .gitignore) docker compose --env-file .env config --quiet make up # docker compose up -d --build --wait: postgres -> migrate -> api; ждёт healthcheck /health/ready @@ -102,7 +102,7 @@ migrate (one-shot) ──> postgres : применение migrations/*.sql ## Доказательства критериев -Все файлы в `evidence/` сняты 2026-10-07 на MacBook (Apple Silicon, Docker Desktop, без CPU/RAM-лимитов в compose). Порт стенда автора — 18080, потому что 8080 занят другим проектом. +Файлы в `evidence/` сняты 2026-10-07 (explain_history) и 2026-10-08 UTC (остальные) на MacBook (Apple Silicon, Docker Desktop, без CPU/RAM-лимитов в compose). | Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства | | --- | --- | --- | --- | diff --git a/app/auth.py b/app/auth.py index 259e3a11..fc6d1f28 100644 --- a/app/auth.py +++ b/app/auth.py @@ -1,4 +1,3 @@ -"""Passwords (Argon2id), Basic login and opaque Bearer sessions.""" from __future__ import annotations import asyncio @@ -18,10 +17,8 @@ from app.cache import REVOKED, SessionCache from app.errors import BASIC_CHALLENGE, unauthorized from app.storage import Store, fmt_ts, user_row -# argon2-cffi defaults = RFC 9106 low-memory profile (Argon2id, t=3, m=64 MiB, p=4). _hasher = PasswordHasher() _hash_slots = asyncio.Semaphore(config.PASSWORD_HASH_CONCURRENCY) -# Verified when the username does not exist, so both failures cost the same time. _DUMMY_HASH = _hasher.hash("dummy-password-for-timing") @@ -42,8 +39,6 @@ async def verify_password(password_hash: str, password: str) -> bool: def token_digest(token: str) -> bytes: - # A fast hash is enough here: the token already carries 256 random bits, - # unlike a human password that needs a slow KDF against guessing. return hashlib.sha256(token.encode("ascii")).digest() @@ -58,7 +53,7 @@ def parse_basic(header: Optional[str]) -> Tuple[str, str]: decoded = base64.b64decode(value.strip(), validate=True).decode("utf-8") except (binascii.Error, UnicodeDecodeError): raise bad from None - username, sep, password = decoded.partition(":") # the password may contain ':' + username, sep, password = decoded.partition(":") if not sep or not username.isascii() or not 12 <= len(password) <= 128: raise bad return username, password @@ -82,16 +77,12 @@ async def login(store: Store, header: Optional[str]) -> dict: raise unauthorized("invalid credentials", BASIC_CHALLENGE) if not await verify_password(row["password_hash"], password): raise unauthorized("invalid credentials", BASIC_CHALLENGE) - token = secrets.token_urlsafe(32) # 256 bits of entropy + token = secrets.token_urlsafe(32) expires_at = await store.create_session(token_digest(token), row["id"], config.SESSION_TTL_SECONDS) return {"token": token, "token_type": "Bearer", "expires_at": fmt_ts(expires_at), "user": user_row(row)} async def authenticate(store: Store, cache: SessionCache, header: Optional[str]) -> dict: - """Return the session's user or raise 401. Cache first, PostgreSQL on a miss. - - If PostgreSQL is down and the cache has no answer the error propagates as 503: - an unverifiable token is never treated as authenticated.""" digest = token_digest(parse_bearer(header)) cached = await cache.get(digest) if cached == REVOKED: @@ -112,10 +103,9 @@ async def authenticate(store: Store, cache: SessionCache, header: Optional[str]) async def logout(store: Store, cache: SessionCache, header: Optional[str]) -> None: - # Authenticate first so an already revoked token gets 401, as the contract requires. await authenticate(store, cache, header) digest = token_digest(parse_bearer(header)) - expires_at = await store.revoke_session(digest) # PostgreSQL first: it is the truth + expires_at = await store.revoke_session(digest) if expires_at is None: raise unauthorized("session expired or revoked") remaining = int((expires_at - datetime.now(timezone.utc)).total_seconds()) + 1 diff --git a/app/cache.py b/app/cache.py index c0da5ab2..7600b48a 100644 --- a/app/cache.py +++ b/app/cache.py @@ -1,10 +1,3 @@ -"""Valkey session cache. Never the source of truth: every failure degrades to a miss. - -Keys: session: -Value: JSON {"user": {...}, "expires_at": "..."} - a valid session - "revoked" - tombstone written by logout -Entry TTL = min(time left in the session, SESSION_CACHE_MAX_SECONDS). -""" from __future__ import annotations import json @@ -45,7 +38,6 @@ class SessionCache: return self._client is not None and time.monotonic() >= self._down_until def _failed(self, op: str, exc: Exception) -> None: - # Circuit breaker: one slow failure, then skip the cache for a few seconds. self._down_until = time.monotonic() + config.CACHE_RETRY_AFTER logger.warning("cache %s failed (%s); bypassing cache for %.0fs", op, type(exc).__name__, config.CACHE_RETRY_AFTER) @@ -69,7 +61,6 @@ class SessionCache: return None async def put(self, token_hash: bytes, entry: dict, ttl_seconds: int) -> None: - """Fill after a PostgreSQL read. NX: never overwrite a logout tombstone.""" ttl = min(ttl_seconds, config.SESSION_CACHE_MAX_SECONDS) if ttl <= 0 or not self._usable(): return @@ -79,9 +70,6 @@ class SessionCache: self._failed("set", exc) async def revoke(self, token_hash: bytes, ttl_seconds: int) -> None: - """Tombstone instead of DEL: a concurrent fill that read PostgreSQL before the - revoke cannot re-insert the session afterwards (its SET NX loses). - Tried even while the breaker is open: logout is rare and correctness matters more.""" if self._client is None: return try: diff --git a/app/config.py b/app/config.py index a651d4bd..e17bf661 100644 --- a/app/config.py +++ b/app/config.py @@ -1,4 +1,3 @@ -"""Runtime configuration from environment; secrets are read from *_FILE paths.""" from __future__ import annotations import os @@ -6,7 +5,6 @@ from typing import Optional def _secret(name: str) -> Optional[str]: - """NAME wins over NAME_FILE; NAME_FILE keeps the value out of `docker inspect`.""" value = os.environ.get(name) if value: return value.strip() @@ -29,7 +27,6 @@ DATABASE_URL = _secret("DATABASE_URL") CACHE_URL = _secret("CACHE_URL") SESSION_TTL_SECONDS = _int("SESSION_TTL_SECONDS", 3600) -# Upper bound for one cached session entry; PostgreSQL is re-checked after it. SESSION_CACHE_MAX_SECONDS = _int("SESSION_CACHE_MAX_SECONDS", 300) DB_POOL_MAX = _int("DB_POOL_MAX", 10) @@ -39,8 +36,6 @@ DB_COMMAND_TIMEOUT = _float("DB_COMMAND_TIMEOUT", 5) CACHE_TIMEOUT = _float("CACHE_TIMEOUT", 0.3) CACHE_POOL_MAX = _int("CACHE_POOL_MAX", 20) -# After a cache error, skip the cache for this long instead of paying the timeout per request. CACHE_RETRY_AFTER = _float("CACHE_RETRY_AFTER", 5) -# Argon2id hashing is CPU/RAM heavy: bound how many run at once. PASSWORD_HASH_CONCURRENCY = _int("PASSWORD_HASH_CONCURRENCY", 4) diff --git a/app/errors.py b/app/errors.py index 97933e98..38729915 100644 --- a/app/errors.py +++ b/app/errors.py @@ -1,4 +1,3 @@ -"""API error type shared by all layers.""" from __future__ import annotations from typing import Dict, Optional diff --git a/app/main.py b/app/main.py index 8ada91fc..0f13c117 100644 --- a/app/main.py +++ b/app/main.py @@ -1,4 +1,3 @@ -"""Lab 2: messenger API on PostgreSQL with Bearer sessions and a Valkey session cache.""" from __future__ import annotations import logging @@ -39,18 +38,13 @@ async def lifespan(_app: FastAPI): app = FastAPI(title="MTUSI Messenger — lab2", lifespan=lifespan) -# --------------------------------------------------------------------------- -# Cross-cutting: request id + uniform error envelope -# --------------------------------------------------------------------------- - -# PostgreSQL unreachable, restarting or pool exhausted -> bounded 503, never a hang. DB_UNAVAILABLE = ( - OSError, # includes ConnectionRefusedError and TimeoutError (pool acquire / connect) + OSError, asyncpg.PostgresConnectionError, asyncpg.InterfaceError, asyncpg.TooManyConnectionsError, - asyncpg.exceptions.OperatorInterventionError, # admin shutdown, cannot connect now - asyncpg.exceptions.QueryCanceledError, # statement timeout + asyncpg.exceptions.OperatorInterventionError, + asyncpg.exceptions.QueryCanceledError, ) @@ -70,8 +64,6 @@ async def request_id_middleware(request: Request, call_next): try: response = await call_next(request) except Exception: - # Unhandled errors must be answered here: Starlette's own 500 handler runs - # outside this middleware and would drop the X-Request-Id header. logger.exception("unhandled error for request_id=%s", request_id) response = JSONResponse(status_code=500, content=error_body("internal_error", "internal error", request_id)) response.headers["X-Request-Id"] = request_id @@ -104,11 +96,6 @@ for _exc in DB_UNAVAILABLE: app.add_exception_handler(_exc, db_unavailable_handler) -# --------------------------------------------------------------------------- -# Auth: Basic only on POST /auth/sessions, Bearer everywhere else. -# X-User-Id is ignored since lab2. -# --------------------------------------------------------------------------- - async def current_user(request: Request) -> dict: return await auth.authenticate(store, cache, request.headers.get("Authorization")) @@ -124,10 +111,6 @@ def not_found() -> ApiError: return ApiError(404, "not_found", "chat not found") -# --------------------------------------------------------------------------- -# Health -# --------------------------------------------------------------------------- - @app.get("/health/live", response_model=Health) async def liveness(): return Health() @@ -135,7 +118,6 @@ async def liveness(): @app.get("/health/ready", response_model=Health) async def readiness(): - # PostgreSQL is critical; Valkey is not (the API bypasses the cache without it). try: await store.ping() except DB_UNAVAILABLE: @@ -143,10 +125,6 @@ async def readiness(): return Health() -# --------------------------------------------------------------------------- -# Users and sessions -# --------------------------------------------------------------------------- - @app.post("/api/v1/users", response_model=User, status_code=201) async def register_user(body: CreateUser): if not body.display_name.strip() or not body.password.strip(): @@ -171,10 +149,6 @@ async def delete_session(request: Request): return Response(status_code=204) -# --------------------------------------------------------------------------- -# Chats -# --------------------------------------------------------------------------- - @app.post("/api/v1/chats", response_model=Chat, status_code=201) async def create_chat(body: CreateChat, user: dict = Depends(current_user)): if not body.title.strip(): @@ -203,15 +177,10 @@ async def get_chat(chat_id: str, user: dict = Depends(current_user)): return chat -# --------------------------------------------------------------------------- -# Messages -# --------------------------------------------------------------------------- - @app.post("/api/v1/chats/{chat_id}/messages", response_model=Message, status_code=201) async def create_message(chat_id: str, body: CreateMessage, user: dict = Depends(current_user)): chat_uuid = parse_uuid(chat_id, "chat_id") if not body.text.strip(): - # Access is checked before content: an outsider gets 404 even for a blank text. if not await store.is_member(chat_uuid, uuid.UUID(user["id"])): raise not_found() raise ApiError(400, "invalid_request", "text must not be blank") diff --git a/app/migrate.py b/app/migrate.py index fa3da67f..29df5991 100644 --- a/app/migrate.py +++ b/app/migrate.py @@ -1,7 +1,3 @@ -"""Apply versioned SQL migrations from migrations/; safe to run repeatedly and concurrently. - -Usage: python -m app.migrate -""" from __future__ import annotations import asyncio @@ -17,7 +13,6 @@ logging.basicConfig(level=logging.INFO, format="%(levelname)s %(name)s: %(messag logger = logging.getLogger("migrate") MIGRATIONS_DIR = Path(__file__).resolve().parents[1] / "migrations" -# Arbitrary constant: serialises concurrent runners (e.g. several API replicas in lab3). LOCK_ID = 2026_0002 diff --git a/app/models.py b/app/models.py index b9aab0bc..d6e9a381 100644 --- a/app/models.py +++ b/app/models.py @@ -1,4 +1,3 @@ -"""Pydantic request/response schemas mirroring contracts/openapi.json.""" from __future__ import annotations import uuid diff --git a/app/storage.py b/app/storage.py index 0666515d..2652791e 100644 --- a/app/storage.py +++ b/app/storage.py @@ -1,4 +1,3 @@ -"""PostgreSQL repository. Every query is parameterised; PostgreSQL is the source of truth.""" from __future__ import annotations import base64 @@ -14,7 +13,6 @@ from app.errors import ApiError def fmt_ts(value: datetime) -> str: - # Always 6 fractional digits: exact round trip with PostgreSQL microseconds. return value.astimezone(timezone.utc).strftime("%Y-%m-%dT%H:%M:%S.%fZ") @@ -46,10 +44,6 @@ def message_row(row: asyncpg.Record) -> dict: } -# --------------------------------------------------------------------------- -# Opaque keyset cursor bound to one resource -# --------------------------------------------------------------------------- - def encode_cursor(resource: str, created_at: str, item_id: str) -> str: payload = json.dumps({"r": resource, "t": created_at, "i": item_id}, separators=(",", ":")) return base64.urlsafe_b64encode(payload.encode("utf-8")).decode("ascii").rstrip("=") @@ -65,12 +59,11 @@ def decode_cursor(resource: str, cursor: str) -> Tuple[datetime, uuid.UUID]: if created_at.tzinfo is None: raise ValueError("cursor time has no timezone") return created_at, uuid.UUID(payload["i"]) - except Exception as exc: # noqa: BLE001 - any malformed cursor is a 400 + except Exception as exc: raise ApiError(400, "invalid_request", "invalid cursor") from exc def page_of(items: List[dict], resource: str, limit: int) -> dict: - """Queries fetch limit+1 rows: the extra row only tells whether a next page exists.""" page = items[:limit] next_cursor = None if len(items) > limit: @@ -79,17 +72,11 @@ def page_of(items: List[dict], resource: str, limit: int) -> dict: return {"items": page, "next_cursor": next_cursor} -# --------------------------------------------------------------------------- -# Repository -# --------------------------------------------------------------------------- - class Store: def __init__(self): self.pool: Optional[asyncpg.Pool] = None async def open(self) -> None: - # min_size=0: connections open on demand, so the API starts even while - # PostgreSQL is down and readiness reports 503 until it is back. self.pool = await asyncpg.create_pool( config.DATABASE_URL, min_size=0, @@ -110,7 +97,6 @@ class Store: async with self.acquire() as conn: return await conn.fetchval("SELECT 1") == 1 - # -- users -------------------------------------------------------------- async def create_user(self, username: str, display_name: str, password_hash: str) -> dict: async with self.acquire() as conn: @@ -124,7 +110,6 @@ class Store: uuid.uuid4(), username, display_name, password_hash, ) except asyncpg.UniqueViolationError: - # The UNIQUE constraint, not a prior SELECT, decides concurrent registrations. raise ApiError(409, "conflict", "username already taken") from None return user_row(row) @@ -135,7 +120,6 @@ class Store: username, ) - # -- sessions ----------------------------------------------------------- async def create_session(self, token_hash: bytes, user_id: uuid.UUID, ttl_seconds: int) -> datetime: async with self.acquire() as conn: @@ -149,7 +133,6 @@ class Store: ) async def find_session(self, token_hash: bytes) -> Optional[asyncpg.Record]: - """Only a live session: not revoked and not expired by the database clock.""" async with self.acquire() as conn: return await conn.fetchrow( """ @@ -171,13 +154,8 @@ class Store: token_hash, ) - # -- chats -------------------------------------------------------------- async def create_chat(self, title: str, member_ids: List[uuid.UUID]) -> dict: - """Chat and all memberships commit together or not at all. - - Unknown members are detected by the foreign key inside the transaction, so a - failure after the chat row was inserted really exercises the rollback.""" chat_id = uuid.uuid4() async with self.acquire() as conn: try: @@ -245,10 +223,8 @@ class Store: chat_id, user_id, )) - # -- messages ----------------------------------------------------------- async def create_message(self, chat_id: uuid.UUID, sender_id: uuid.UUID, text: str) -> Optional[dict]: - """Membership check and insert in one statement; None means "no such chat for you".""" async with self.acquire() as conn: row = await conn.fetchrow( """ diff --git a/compose.yaml b/compose.yaml index a04811c1..8241e61a 100644 --- a/compose.yaml +++ b/compose.yaml @@ -1,5 +1,3 @@ -# Lab 2 stack: api -> postgres (source of truth) + valkey (session cache). -# Prepare secrets first: scripts/init-secrets.sh. Start: docker compose up -d --build --wait name: messenger-lab2 x-api: &api @@ -20,7 +18,6 @@ x-api: &api postgres: condition: service_healthy valkey: - # The cache is optional for correctness: only wait for the container to start. condition: service_started migrate: condition: service_completed_successfully @@ -47,11 +44,9 @@ services: valkey: image: valkey/valkey:8.1.4-alpine3.22 - # requirepass and cache-only settings live in the secret config file. command: ["valkey-server", "/run/secrets/valkey_conf"] secrets: [valkey_conf] healthcheck: - # NOAUTH also proves the server answers; the password stays out of the process list. test: ["CMD-SHELL", "valkey-cli ping 2>&1 | grep -qE 'PONG|NOAUTH'"] interval: 2s timeout: 3s @@ -75,8 +70,6 @@ services: ports: - "127.0.0.1:${APP_PORT:-8080}:8080" - # Same image with a 2-second TTL, only for the expiry test: - # docker compose --profile ttl-test up -d --wait api-short-ttl api-short-ttl: <<: *api profiles: [ttl-test] diff --git a/evidence/explain_history.txt b/evidence/explain_history.txt index c6d5b362..03d6da32 100644 --- a/evidence/explain_history.txt +++ b/evidence/explain_history.txt @@ -1,36 +1,36 @@ # EXPLAIN evidence for message history pagination -# date: 2026-10-07T14:17:55Z commit: 65003b6 +# date: 2026-10-09T09:35:29Z commit: e914e38 # postgres: 17.6 -# messages total: 70112, in measured chat: 20000 +# messages total: 70006, in measured chat: 20000 PREPARE PREPARE === 1. WITH index messages_chat_history_idx: first page (limit 50 + 1) === QUERY PLAN --------------------------------------------------------------------------------------------------------------------------------------------------- - Limit (cost=0.42..8.60 rows=51 width=78) (actual time=0.014..0.019 rows=51 loops=1) + Limit (cost=0.42..7.37 rows=51 width=78) (actual time=0.017..0.022 rows=51 loops=1) Buffers: shared hit=4 - -> Index Scan using messages_chat_history_idx on messages (cost=0.42..3227.11 rows=20122 width=78) (actual time=0.013..0.015 rows=51 loops=1) + -> Index Scan using messages_chat_history_idx on messages (cost=0.42..2712.54 rows=19884 width=78) (actual time=0.016..0.019 rows=51 loops=1) Index Cond: (chat_id = '00000000-0000-4000-8000-000000000100'::uuid) Buffers: shared hit=4 Planning: Buffers: shared hit=106 - Planning Time: 0.272 ms - Execution Time: 0.031 ms + Planning Time: 0.287 ms + Execution Time: 0.035 ms (9 rows) === 2. WITH index: deep page, cursor after message #15000 of 20000 === QUERY PLAN ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ - Limit (cost=0.42..55.74 rows=51 width=78) (actual time=0.012..0.017 rows=51 loops=1) + Limit (cost=0.42..54.50 rows=51 width=78) (actual time=0.016..0.021 rows=51 loops=1) Buffers: shared hit=4 - -> Index Scan using messages_chat_history_idx on messages (cost=0.42..1590.70 rows=1466 width=78) (actual time=0.012..0.014 rows=51 loops=1) + -> Index Scan using messages_chat_history_idx on messages (cost=0.42..1492.33 rows=1407 width=78) (actual time=0.016..0.019 rows=51 loops=1) Index Cond: ((chat_id = '00000000-0000-4000-8000-000000000100'::uuid) AND (ROW(created_at, id) > ROW('2026-01-01 04:10:00+00'::timestamp with time zone, '47ba2a9c-d238-4807-2008-6ea72cb0f95c'::uuid))) Buffers: shared hit=4 Planning: Buffers: shared hit=42 - Planning Time: 0.276 ms - Execution Time: 0.035 ms + Planning Time: 0.286 ms + Execution Time: 0.039 ms (9 rows) BEGIN @@ -38,37 +38,37 @@ DROP INDEX === 3. WITHOUT index: first page === QUERY PLAN -------------------------------------------------------------------------------------------------------------------------- - Limit (cost=2487.71..2487.84 rows=51 width=78) (actual time=4.235..4.239 rows=51 loops=1) - Buffers: shared hit=946 - -> Sort (cost=2487.71..2538.02 rows=20122 width=78) (actual time=4.234..4.236 rows=51 loops=1) + Limit (cost=2472.45..2472.58 rows=51 width=78) (actual time=4.141..4.146 rows=51 loops=1) + Buffers: shared hit=940 + -> Sort (cost=2472.45..2522.16 rows=19884 width=78) (actual time=4.141..4.143 rows=51 loops=1) Sort Key: created_at, id Sort Method: top-N heapsort Memory: 31kB - Buffers: shared hit=946 - -> Seq Scan on messages (cost=0.00..1816.40 rows=20122 width=78) (actual time=0.011..3.325 rows=20000 loops=1) + Buffers: shared hit=940 + -> Seq Scan on messages (cost=0.00..1809.08 rows=19884 width=78) (actual time=0.004..3.157 rows=20000 loops=1) Filter: (chat_id = '00000000-0000-4000-8000-000000000100'::uuid) - Rows Removed by Filter: 50112 - Buffers: shared hit=940 + Rows Removed by Filter: 50006 + Buffers: shared hit=934 Planning: Buffers: shared hit=16 - Planning Time: 0.098 ms - Execution Time: 4.249 ms + Planning Time: 0.091 ms + Execution Time: 4.167 ms (14 rows) === 4. WITHOUT index: deep page === QUERY PLAN -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- - Limit (cost=2215.87..2216.00 rows=51 width=78) (actual time=3.117..3.121 rows=51 loops=1) - Buffers: shared hit=940 - -> Sort (cost=2215.87..2219.53 rows=1466 width=78) (actual time=3.116..3.118 rows=51 loops=1) + Limit (cost=2206.05..2206.17 rows=51 width=78) (actual time=2.882..2.886 rows=51 loops=1) + Buffers: shared hit=934 + -> Sort (cost=2206.05..2209.56 rows=1407 width=78) (actual time=2.881..2.883 rows=51 loops=1) Sort Key: created_at, id Sort Method: top-N heapsort Memory: 31kB - Buffers: shared hit=940 - -> Seq Scan on messages (cost=0.00..2166.96 rows=1466 width=78) (actual time=0.605..2.853 rows=5000 loops=1) + Buffers: shared hit=934 + -> Seq Scan on messages (cost=0.00..2159.11 rows=1407 width=78) (actual time=0.628..2.654 rows=5000 loops=1) Filter: ((chat_id = '00000000-0000-4000-8000-000000000100'::uuid) AND (ROW(created_at, id) > ROW('2026-01-01 04:10:00+00'::timestamp with time zone, '47ba2a9c-d238-4807-2008-6ea72cb0f95c'::uuid))) - Rows Removed by Filter: 65112 - Buffers: shared hit=940 - Planning Time: 0.069 ms - Execution Time: 3.133 ms + Rows Removed by Filter: 65006 + Buffers: shared hit=934 + Planning Time: 0.059 ms + Execution Time: 2.898 ms (12 rows) ROLLBACK diff --git a/evidence/fresh_migrations.txt b/evidence/fresh_migrations.txt index 03c84113..16e1305b 100644 --- a/evidence/fresh_migrations.txt +++ b/evidence/fresh_migrations.txt @@ -1,6 +1,6 @@ # Fresh volume: migrations from scratch + public smoke -# date: 2026-10-07T14:18:43Z -$ APP_PORT=18090 docker compose -p lab2-clean up -d --wait +# date: 2026-10-08T21:04:06Z +$ docker compose -p lab2-clean up -d --wait Container lab2-clean-api-1 Created Container lab2-clean-api-1 Healthy Container lab2-clean-migrate-1 Created @@ -14,7 +14,7 @@ $ APP_PORT=18090 docker compose -p lab2-clean up -d --wait $ docker compose -p lab2-clean logs migrate INFO migrate: applying 0001_init INFO migrate: migrations up to date: 1 applied now, 0 before -$ make test BASE_URL=http://localhost:18090 +$ make test PASS: lab2 public API scenario; infrastructure and grading evidence remain separate. $ docker compose -p lab2-clean run --rm migrate # second run INFO migrate: migrations up to date: 0 applied now, 1 before diff --git a/evidence/persistence.txt b/evidence/persistence.txt index 30973aac..6c9b7579 100644 --- a/evidence/persistence.txt +++ b/evidence/persistence.txt @@ -1,9 +1,9 @@ # Persistence: API + PostgreSQL + Valkey restarted, volume kept, same token -# date: 2026-10-07T14:19:03Z +# date: 2026-10-08T21:04:36Z ## containers BEFORE -api 2026-10-07T14:18:25.262485419Z running restarts=0 -postgres 2026-10-07T14:18:22.306271835Z running restarts=0 -valkey 2026-10-07T14:18:21.888265501Z running restarts=0 +api 2026-10-08T21:04:21.524285049Z running restarts=0 +postgres 2026-10-08T21:04:18.312105839Z running restarts=0 +valkey 2026-10-08T21:04:18.312749256Z running restarts=0 volume messenger-lab2_pgdata $ make test-persistence ACTION_SCRIPT=scripts/restart.sh @@ -11,9 +11,9 @@ Executing explicit persistence hook; hook output suppressed to avoid leaking sec PASS: persistence preserved confirmed data and existing session. Hook scope needs operator evidence. ## containers AFTER (StartedAt changed for all three) -api 2026-10-07T14:19:08.428103009Z running restarts=0 -postgres 2026-10-07T14:19:05.240867716Z running restarts=0 -valkey 2026-10-07T14:19:05.240850591Z running restarts=0 +api 2026-10-08T21:04:41.315237919Z running restarts=0 +postgres 2026-10-08T21:04:38.136785584Z running restarts=0 +valkey 2026-10-08T21:04:38.136211584Z running restarts=0 volume messenger-lab2_pgdata $ docker compose logs migrate | tail -1 diff --git a/evidence/smoke.txt b/evidence/smoke.txt index 51d84e48..b98247e2 100644 --- a/evidence/smoke.txt +++ b/evidence/smoke.txt @@ -1,4 +1,4 @@ -# date: 2026-10-07T14:19:14Z +# date: 2026-10-08T21:04:36Z $ make check PASS: offline skeleton structure, local refs and Python syntax; application NOT tested. $ make test diff --git a/evidence/student_tests.txt b/evidence/student_tests.txt index be684fbd..f7f211a3 100644 --- a/evidence/student_tests.txt +++ b/evidence/student_tests.txt @@ -1,6 +1,5 @@ -# date: 2026-10-07T14:19:14Z +# date: 2026-10-08T21:04:47Z $ make test-student -BASE_URL="http://localhost:18080" sh student-tests/run_all.sh == own_tests.py ok - malformed JSON -> 400 invalid_request ok - foreign chat access -> 404 (no leak) @@ -27,18 +26,18 @@ PASS: 7 checks ok - 20 concurrent registrations of one username -> 1x201, 19x409, 1 row ok - chat with unknown member -> 400 and transaction rolled back (no orphan chat) ok - password stored as $argon2id$..., sessions keep only sha256(token) -ok - migrations run twice more: schema_migrations and data unchanged (1:49) +ok - migrations run twice more: schema_migrations and data unchanged (1:113) PASS: 4 checks == dependency_test.py ok - Valkey caches sessions with TTL<=300s and keeps logout tombstones -ok - Valkey stopped: ready=200, reads/writes OK, revoked token 401, 4 ms/request +ok - Valkey stopped: ready=200, reads/writes OK, revoked token 401, 3 ms/request ok - PostgreSQL stopped: live=200, ready/business=503 in 0.0s total, unverified token not trusted ok - PostgreSQL started again: API recovers without restart, data intact PASS: 4 checks == sigterm_test.sh -api stopped in 0s, exit code 0 (0 = graceful, 137 = SIGKILL) +api stopped in 1s, exit code 0 (0 = graceful, 137 = SIGKILL) PASS: graceful SIGTERM shutdown, api restarted ALL STUDENT TESTS PASSED diff --git a/migrations/0001_init.sql b/migrations/0001_init.sql index 89e1e4c9..a46a618c 100644 --- a/migrations/0001_init.sql +++ b/migrations/0001_init.sql @@ -1,5 +1,3 @@ --- Initial schema for lab2. Applied once by app/migrate.py inside one transaction. - CREATE TABLE users ( id uuid PRIMARY KEY, username text NOT NULL, @@ -18,7 +16,6 @@ CREATE TABLE chats ( CONSTRAINT chats_title_len CHECK (char_length(title) BETWEEN 1 AND 100) ); --- position keeps member_ids in the order the creator sent them. CREATE TABLE chat_members ( chat_id uuid NOT NULL REFERENCES chats (id), user_id uuid NOT NULL REFERENCES users (id), @@ -26,7 +23,6 @@ CREATE TABLE chat_members ( PRIMARY KEY (chat_id, user_id) ); --- "Chats of a user": GET /chats starts from the caller's memberships. CREATE INDEX chat_members_user_idx ON chat_members (user_id, chat_id); CREATE TABLE messages ( @@ -35,18 +31,13 @@ CREATE TABLE messages ( sender_id uuid NOT NULL, text text NOT NULL, created_at timestamptz NOT NULL DEFAULT clock_timestamp(), - -- The sender must be a member of the chat, enforced by the database itself. CONSTRAINT messages_sender_member_fk FOREIGN KEY (chat_id, sender_id) REFERENCES chat_members (chat_id, user_id), CONSTRAINT messages_text_len CHECK (char_length(text) BETWEEN 1 AND 4000) ); --- Keyset pagination of history: WHERE chat_id = $1 AND (created_at, id) > ($2, $3) --- ORDER BY created_at, id LIMIT n. Justified by EXPLAIN in evidence/explain_history.txt. CREATE INDEX messages_chat_history_idx ON messages (chat_id, created_at, id); --- Sessions: PostgreSQL is the source of truth; Valkey only caches lookups. --- token_hash = sha256(token); the raw token is never stored. CREATE TABLE sessions ( token_hash bytea PRIMARY KEY, user_id uuid NOT NULL REFERENCES users (id), diff --git a/scripts/init-secrets.sh b/scripts/init-secrets.sh index f7df3788..9ee484a5 100755 --- a/scripts/init-secrets.sh +++ b/scripts/init-secrets.sh @@ -1,6 +1,4 @@ #!/bin/sh -# Generate local synthetic credentials into ./secrets (git-ignored). Idempotent: -# existing files are kept, so a running stack keeps working. Prints no secret values. set -eu cd "$(dirname "$0")/.." @@ -18,7 +16,6 @@ printf 'postgresql://messenger:%s@postgres:5432/messenger\n' "$PG_PASS" > secret if [ ! -f secrets/valkey.conf ]; then { printf 'requirepass %s\n' "$(gen)" - # Pure cache: PostgreSQL holds the sessions, so no RDB/AOF is needed. printf 'save ""\nappendonly no\n' printf 'maxmemory 64mb\nmaxmemory-policy volatile-lru\n' } > secrets/valkey.conf @@ -27,6 +24,5 @@ fi VK_PASS=$(sed -n 's/^requirepass //p' secrets/valkey.conf) printf 'redis://:%s@valkey:6379/0\n' "$VK_PASS" > secrets/cache_url -# Containers run as non-root users that do not own these files on Linux. chmod 644 secrets/* echo "secrets ready in ./secrets (not tracked by git)" diff --git a/scripts/restart.sh b/scripts/restart.sh index a5d7ee43..b5731fc0 100755 --- a/scripts/restart.sh +++ b/scripts/restart.sh @@ -1,12 +1,9 @@ #!/bin/sh -# Restart the API and ALL state stores (PostgreSQL, Valkey), keeping volumes. -# Never `down -v`, never flush, never re-seed. Migrations run again (idempotent). set -eu cd "$(dirname "$0")/.." docker compose stop api docker compose stop valkey postgres -# depends_on brings postgres, valkey and migrate up first; --wait = api healthcheck (/health/ready). docker compose up -d --no-build --wait api docker compose ps --all --format 'table {{.Service}}\t{{.Status}}' diff --git a/student-tests/auth_test.py b/student-tests/auth_test.py index d8935b20..adc266aa 100755 --- a/student-tests/auth_test.py +++ b/student-tests/auth_test.py @@ -1,9 +1,4 @@ #!/usr/bin/env python3 -"""Sessions: wrong password, Basic/Bearer separation, X-User-Id ignored, logout, expiry. - -Expiry runs against the api-short-ttl service (SESSION_TTL_SECONDS=2): - docker compose --profile ttl-test up -d --wait api-short-ttl -""" import base64 import time import uuid @@ -20,7 +15,6 @@ def main(): alice = c.user("auth") reg = alice["registration"] - # Wrong password and unknown user: the same 401 with a Basic challenge. r1 = c.call("POST", "/api/v1/auth/sessions", 401, headers=basic(reg["username"], "wrong-password-123")) r2 = c.call("POST", "/api/v1/auth/sessions", 401, headers=basic("nobody_" + uuid.uuid4().hex[:8], "wrong-password-123")) check(r1["json"]["error"]["message"] == r2["json"]["error"]["message"], "unknown user must look like a wrong password") @@ -31,7 +25,6 @@ def main(): c.call("POST", "/api/v1/auth/sessions", 401, headers={"Authorization": "Bearer " + alice["token"]}) ok("missing / malformed / non-Basic login -> 401") - # A password with ':' and non-ASCII characters survives Basic encoding. tricky = "пароль:с:двоеточием-" + uuid.uuid4().hex[:6] user = c.call("POST", "/api/v1/users", 201, body={"username": "u_colon_" + uuid.uuid4().hex[:8], "display_name": "Двоеточие", "password": tricky}, schema="User")["json"] c.call("POST", "/api/v1/auth/sessions", 201, headers=basic(user["username"], tricky), schema="Session") @@ -56,7 +49,6 @@ def main(): c.call("GET", "/api/v1/users/me", 200, actor=second, schema="User") ok("logout revokes only the current token; repeat logout -> 401") - # Expiry: separate instance of the same image with SESSION_TTL_SECONDS=2. s = Client(SHORT_TTL_URL) bob = s.user("ttl") s.call("GET", "/api/v1/users/me", 200, actor=bob, schema="User") diff --git a/student-tests/concurrency_test.py b/student-tests/concurrency_test.py index da3666db..7d8cdc27 100755 --- a/student-tests/concurrency_test.py +++ b/student-tests/concurrency_test.py @@ -1,7 +1,4 @@ #!/usr/bin/env python3 -"""Level-4 race-protection evidence: 10 clients send 100 messages concurrently; -expect exactly 100 unique messages, with no loss/duplication under pagination. -""" import sys import urllib.parse import concurrent.futures @@ -9,7 +6,7 @@ from pathlib import Path ROOT = Path(__file__).resolve().parents[1] sys.path.insert(0, str(ROOT / "tests")) -from client import Client, check # noqa: E402 +from client import Client, check def main(): @@ -36,8 +33,6 @@ def main(): check(len(ids) == n_messages, "expected %d responses" % n_messages) check(len(set(ids)) == n_messages, "expected %d unique message ids, got %d" % (n_messages, len(set(ids)))) - # Walk the full history back through the API to confirm the store itself - # (not just the HTTP responses) holds exactly n_messages distinct rows. seen = [] cursor = None while True: diff --git a/student-tests/db_integrity_test.py b/student-tests/db_integrity_test.py index 9b10d300..5e213260 100755 --- a/student-tests/db_integrity_test.py +++ b/student-tests/db_integrity_test.py @@ -1,6 +1,4 @@ #!/usr/bin/env python3 -"""PostgreSQL integrity: registration race, rollback of chat creation, repeatable migrations, -password storage. Needs the compose stack (reads tables via `docker compose exec postgres`).""" import concurrent.futures import uuid @@ -10,7 +8,6 @@ from stack import BASE_URL, Client, check, compose, main_wrapper, ok, psql def main(): c = Client(BASE_URL) - # 1. Registration race: 20 parallel requests for one username. username = "u_race_" + uuid.uuid4().hex[:10] body = {"username": username, "display_name": "Гонка", "password": "Race-password-123"} @@ -24,7 +21,6 @@ def main(): check(psql("SELECT count(*) FROM users WHERE username = '%s'" % username) == "1", "exactly one row expected") ok("20 concurrent registrations of one username -> 1x201, 19x409, 1 row") - # 2. Rollback: the chat row is inserted, then the member insert hits the FK. alice = c.user("rb") title = "rollback-" + uuid.uuid4().hex c.call("POST", "/api/v1/chats", 400, actor=alice, body={"title": title, "member_ids": [alice["id"], str(uuid.uuid4())]}) @@ -33,14 +29,12 @@ def main(): "chat without members exists") ok("chat with unknown member -> 400 and transaction rolled back (no orphan chat)") - # 3. Passwords are stored as Argon2id hashes, never plaintext. stored = psql("SELECT password_hash FROM users WHERE username = '%s'" % username) check(stored.startswith("$argon2id$") and "Race-password-123" not in stored, "password must be an Argon2id hash") check(psql("SELECT count(*) FROM information_schema.columns WHERE table_name = 'sessions' AND column_name = 'token'") == "0", "raw tokens must not be stored") ok("password stored as $argon2id$..., sessions keep only sha256(token)") - # 4. Migrations re-run without duplicates or data changes. before = psql("SELECT (SELECT count(*) FROM schema_migrations) || ':' || (SELECT count(*) FROM users)") compose("run", "--rm", "--no-deps", "migrate") compose("run", "--rm", "--no-deps", "migrate") diff --git a/student-tests/dependency_test.py b/student-tests/dependency_test.py index af9ac078..2e7a7964 100755 --- a/student-tests/dependency_test.py +++ b/student-tests/dependency_test.py @@ -1,11 +1,4 @@ #!/usr/bin/env python3 -"""Valkey's role and failures of each dependency. STOPS AND STARTS containers of this stack. - -- Valkey really caches sessions and holds logout tombstones. -- Valkey down: API keeps working (cache bypassed), readiness stays 200. -- PostgreSQL down: bounded 503 quickly, readiness 503, liveness 200; an unverifiable - token is never accepted; no token is still 401. Recovery after start. -""" import time from stack import BASE_URL, Client, Failure, check, compose, main_wrapper, ok, valkey @@ -27,7 +20,6 @@ def main(): alice, bob, _eve, chat = c.bootstrap() history = "/api/v1/chats/" + chat["id"] + "/messages" - # Role of Valkey: a session lookup fills the cache, logout leaves a tombstone. before = int(valkey("DBSIZE")) c.call("GET", "/api/v1/users/me", actor=alice, schema="User") keys = valkey("--scan", "--pattern", "session:*").split() @@ -41,13 +33,12 @@ def main(): check(tombstones, "logout must leave a 'revoked' tombstone in the cache") ok("Valkey caches sessions with TTL<=300s and keeps logout tombstones") - # Valkey down -> the API bypasses the cache, PostgreSQL stays the source of truth. try: compose("stop", "valkey") c.call("GET", "/health/ready", 200) c.call("GET", "/api/v1/users/me", actor=alice, schema="User") c.message(bob, chat, "без кэша") - c.call("GET", "/api/v1/users/me", 401, actor=temp) # revoked in PostgreSQL too + c.call("GET", "/api/v1/users/me", 401, actor=temp) start = time.monotonic() for _ in range(10): c.call("GET", history + "?limit=1", actor=alice, schema="MessagePage") @@ -57,8 +48,7 @@ def main(): finally: compose("start", "valkey") - # PostgreSQL down -> bounded 503, never anonymous access. - fresh = c.user("dbdown") # token never looked up yet: not in the cache + fresh = c.user("dbdown") try: compose("stop", "postgres") c.call("GET", "/health/live", 200) @@ -67,8 +57,8 @@ def main(): check(r["json"]["error"]["code"] == "unavailable", "readiness must report unavailable") c.call("GET", "/api/v1/chats", 503, actor=alice) c.call("POST", history, 503, actor=alice, body={"text": "в никуда"}) - c.call("GET", "/api/v1/users/me", 503, actor=fresh) # cannot verify -> not trusted - c.call("GET", "/api/v1/users/me", 401) # no credentials at all + c.call("GET", "/api/v1/users/me", 503, actor=fresh) + c.call("GET", "/api/v1/users/me", 401) elapsed = time.monotonic() - start check(elapsed < 20, "errors must be bounded in time (%.1fs)" % elapsed) ok("PostgreSQL stopped: live=200, ready/business=503 in %.1fs total, unverified token not trusted" % elapsed) diff --git a/student-tests/explain_history.sh b/student-tests/explain_history.sh index d153f906..fac5a536 100755 --- a/student-tests/explain_history.sh +++ b/student-tests/explain_history.sh @@ -1,8 +1,4 @@ #!/bin/sh -# Seed synthetic history (20 000 messages in one chat + 50 000 in 50 other chats) and -# record EXPLAIN (ANALYZE, BUFFERS) of the exact keyset queries used by the API, -# with and without messages_chat_history_idx. Output: evidence/explain_history.txt -# Seeding is idempotent (fixed IDs, ON CONFLICT DO NOTHING); data is synthetic. set -eu cd "$(dirname "$0")/.." @@ -15,7 +11,6 @@ INSERT INTO users (id, username, display_name, password_hash) VALUES ('00000000-0000-4000-8000-000000000002', 'seed_explain_b', 'Seed B', 'not-a-login') ON CONFLICT DO NOTHING; --- chat ...0100 is the measured one; ...0101-0150 are background noise. INSERT INTO chats (id, title, created_at) SELECT ('00000000-0000-4000-8000-' || lpad((100 + g)::text, 12, '0'))::uuid, 'explain ' || g, now() FROM generate_series(0, 50) g @@ -50,7 +45,6 @@ SQL $PSQL -tA -c "SELECT '# messages total: ' || count(*) || ', in measured chat: ' || count(*) FILTER (WHERE chat_id = '00000000-0000-4000-8000-000000000100') FROM messages" echo $PSQL <<'SQL' --- The same statements as app/storage.py (Store.list_messages), as prepared statements. PREPARE first_page(uuid, int) AS SELECT id, chat_id, sender_id, text, created_at FROM messages WHERE chat_id = $1 ORDER BY created_at, id LIMIT $2; @@ -65,7 +59,6 @@ EXPLAIN (ANALYZE, BUFFERS) EXECUTE first_page('00000000-0000-4000-8000-000000000 EXPLAIN (ANALYZE, BUFFERS) EXECUTE next_page('00000000-0000-4000-8000-000000000100', timestamptz '2026-01-01' + interval '15000 seconds', md5('explain-0-15000')::uuid, 51); --- Same queries without the index, inside a transaction that is rolled back. BEGIN; DROP INDEX messages_chat_history_idx; \echo '=== 3. WITHOUT index: first page ===' diff --git a/student-tests/own_tests.py b/student-tests/own_tests.py index 56c7c022..e30bf23d 100755 --- a/student-tests/own_tests.py +++ b/student-tests/own_tests.py @@ -1,13 +1,4 @@ #!/usr/bin/env python3 -"""Student-written negative/edge-case tests, additional to the public tests/smoke.py. - -Covers level-4 requirements from README.md: -- malformed JSON -- foreign chat access -- empty message text -- duplicate username -- multi-page pagination traversal -""" import json import sys import urllib.error @@ -17,7 +8,7 @@ from pathlib import Path ROOT = Path(__file__).resolve().parents[1] sys.path.insert(0, str(ROOT / "tests")) -from client import Client, check # noqa: E402 +from client import Client, check PASSED = 0 @@ -46,7 +37,6 @@ def main(): alice, bob, eve, chat = c.bootstrap() path = "/api/v1/chats/" + chat["id"] - # 1. Malformed JSON body -> 400 invalid_request, not a 500. status, body = raw_call( base_url, "POST", "/api/v1/users", data=b'{"username": "broken", "display_name": ', @@ -57,24 +47,19 @@ def main(): check(parsed["error"]["code"] == "invalid_request", "malformed JSON must report invalid_request") ok("malformed JSON -> 400 invalid_request") - # 2. Foreign chat: eve is not a member -> 404, not 403 (no existence leak). c.call("GET", path, 404, actor=eve) c.call("GET", path + "/messages", 404, actor=eve) ok("foreign chat access -> 404 (no leak)") - # 3. Empty / whitespace-only message text -> 400. c.call("POST", path + "/messages", 400, actor=alice, body={"text": ""}) c.call("POST", path + "/messages", 400, actor=alice, body={"text": " "}) ok("empty/whitespace message text -> 400") - # 4. Duplicate username -> 409 conflict, original user untouched. c.call("POST", "/api/v1/users", 409, body=alice["registration"]) me = c.call("GET", "/api/v1/users/me", actor=alice, schema="User")["json"] check(me == alice["user"], "existing user must be unaffected by a rejected duplicate registration") ok("duplicate username -> 409, original user intact") - # 5. Multi-page pagination traversal: write N messages, walk every page with a small - # limit and confirm the full, ordered, duplicate-free set is recovered. sent = [c.message(alice, chat, "page-msg-%d" % i)["json"] for i in range(7)] collected = [] cursor = None @@ -96,8 +81,6 @@ def main(): check(tail == sorted(tail, key=lambda m: (m["created_at"], m["id"])), "pagination must stay ordered") ok("multi-page pagination traversal: %d pages, %d messages, no dup/loss" % (pages, len(collected))) - # 6. A cursor is bound to the chat it was issued for: reusing it on a - # different chat the same actor can also read must be rejected. first_page = c.call("GET", path + "/messages?limit=1", actor=alice, schema="MessagePage")["json"] check(first_page["next_cursor"], "need a non-null cursor to test cross-chat reuse") chat2 = c.call( diff --git a/student-tests/run_all.sh b/student-tests/run_all.sh index d348ec24..eae79f6e 100755 --- a/student-tests/run_all.sh +++ b/student-tests/run_all.sh @@ -1,7 +1,4 @@ #!/bin/sh -# All student tests in one command. Needs the running compose stack; starts the -# short-TTL instance itself. dependency_test/sigterm_test STOP AND START containers. -# Usage: BASE_URL=http://localhost:8080 student-tests/run_all.sh set -eu cd "$(dirname "$0")/.." diff --git a/student-tests/sigterm_test.sh b/student-tests/sigterm_test.sh index b6016a5e..cbe1f331 100755 --- a/student-tests/sigterm_test.sh +++ b/student-tests/sigterm_test.sh @@ -1,6 +1,4 @@ #!/bin/sh -# Graceful shutdown of the compose api service: SIGTERM -> exit 0 within 10s -# (not SIGKILL 137), then the service is started again. Volumes are untouched. set -eu cd "$(dirname "$0")/.." diff --git a/student-tests/stack.py b/student-tests/stack.py index df5d3c94..159f8e6a 100755 --- a/student-tests/stack.py +++ b/student-tests/stack.py @@ -1,4 +1,3 @@ -"""Shared helpers for student tests: public client + direct access to the compose stack.""" import os import subprocess import sys @@ -6,7 +5,7 @@ from pathlib import Path ROOT = Path(__file__).resolve().parents[1] sys.path.insert(0, str(ROOT / "tests")) -from client import Client, Failure, check # noqa: E402,F401 +from client import Client, Failure, check BASE_URL = os.environ.get("BASE_URL", "http://localhost:8080") SHORT_TTL_URL = os.environ.get("SHORT_TTL_URL", "http://localhost:8081") @@ -20,7 +19,6 @@ def ok(label): def compose(*args, check_rc=True): - """docker compose in the repository root; output is captured, never printed raw.""" proc = subprocess.run(["docker", "compose", *args], cwd=ROOT, capture_output=True, text=True) if check_rc and proc.returncode != 0: raise Failure("docker compose %s failed: %s" % (args[0], proc.stderr.strip()[-300:])) @@ -28,12 +26,10 @@ def compose(*args, check_rc=True): def psql(sql): - """Run SQL inside the postgres container (local socket, no password on the wire).""" return compose("exec", "-T", "postgres", "psql", "-U", "messenger", "-d", "messenger", "-tAX", "-c", sql).strip() def valkey(*args): - """valkey-cli with the password read inside the container, never on this host's argv.""" cmd = 'valkey-cli --no-auth-warning -a "$(sed -n "s/^requirepass //p" /run/secrets/valkey_conf)" "$@"' return compose("exec", "-T", "valkey", "sh", "-c", cmd, "valkey-cli", *args).strip() -- 2.54.0 From a8b160346dac726916fc89e36015c06163b19cb6 Mon Sep 17 00:00:00 2001 From: Ilya <145450507+IIcon18@users.noreply.github.com> Date: Thu, 15 Oct 2026 14:00:24 +0300 Subject: [PATCH 3/3] =?UTF-8?q?=D0=98=D1=81=D0=BF=D1=80=D0=B0=D0=B2=D0=B8?= =?UTF-8?q?=D1=82=D1=8C=20logout=20=D0=BF=D1=80=D0=B8=20=D1=81=D0=B1=D0=BE?= =?UTF-8?q?=D0=B5=20=D0=B7=D0=B0=D0=BF=D0=B8=D1=81=D0=B8=20=D0=B2=20=D0=BA?= =?UTF-8?q?=D1=8D=D1=88=20=D1=81=D0=B5=D1=81=D1=81=D0=B8=D0=B9?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- REPORT.md | 10 +++++-- app/auth.py | 5 ++-- app/cache.py | 45 +++++++++++++++++++++++++++---- evidence/logout_cache_failure.txt | 16 +++++++++++ student-tests/dependency_test.py | 24 +++++++++++++++++ 5 files changed, 91 insertions(+), 9 deletions(-) create mode 100644 evidence/logout_cache_failure.txt diff --git a/REPORT.md b/REPORT.md index 7fb98fe2..9134736d 100644 --- a/REPORT.md +++ b/REPORT.md @@ -77,6 +77,10 @@ migrate (one-shot) ──> postgres : применение migrations/*.sql - **Источник истины — PostgreSQL.** Valkey хранит `session:` → `{user, expires_at}`, чтобы не ходить в БД на каждом запросе; `/users/me` обслуживается вообще без БД. - **Expiry:** TTL записи = `min(остаток сессии, SESSION_CACHE_MAX_SECONDS=300)`, плюс при чтении из кэша сравнивается `expires_at`. Просроченная сессия не принимается ни из кэша, ни из БД. - **Инвалидация:** при logout сначала `revoked_at` в PostgreSQL, затем в Valkey пишется **надгробие** `revoked` (а не DEL). Заполнение кэша идёт через `SET NX`, поэтому параллельный запрос, прочитавший БД до отзыва, не сможет вернуть сессию в кэш. +- **Сбой записи tombstone (исправлено по замечанию к PR):** раньше ошибка записи в Valkey проглатывалась и logout отвечал 204, хотя в кэше оставалась действующая запись сессии; после восстановления Valkey отозванный токен снова получал 200 до 5 минут. Теперь: + - logout отвечает **503** («не подтверждён»), если tombstone не записан; сессия в PostgreSQL при этом уже отозвана; + - хеш токена запоминается в процессе как «отзыв ожидает записи», и запись из кэша для него игнорируется: проверка идёт в PostgreSQL → 401; + - фоновая задача раз в секунду повторяет запись tombstone, пока Valkey не ответит, но не дольше `SESSION_CACHE_MAX_SECONDS` (за это время устаревшая запись истекла бы сама). - **Persistence не нужна и выключена** (`save ""`, `appendonly no`): после flush или рестарта Valkey первая проверка идёт в PostgreSQL. Потеря кэша ничего не ломает, это подтверждает тест сохранности, где Valkey тоже перезапускается. - **Отказ Valkey:** таймаут 0.3 с, затем circuit breaker на 5 с, в течение которых кэш не используется. Readiness при этом остаётся 200: Valkey не критичен. - Конфигурация с `requirepass` лежит в секрете `secrets/valkey.conf`, порт наружу не публикуется. @@ -102,7 +106,7 @@ migrate (one-shot) ──> postgres : применение migrations/*.sql ## Доказательства критериев -Файлы в `evidence/` сняты 2026-10-07 (explain_history) и 2026-10-08 UTC (остальные) на MacBook (Apple Silicon, Docker Desktop, без CPU/RAM-лимитов в compose). +Файлы в `evidence/` сняты 2026-10-07 (explain_history), 2026-10-08 UTC (основные) и 2026-10-15 UTC (logout_cache_failure, на отдельном стенде с портом 18280) на MacBook (Apple Silicon, Docker Desktop, без CPU/RAM-лимитов в compose). | Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства | | --- | --- | --- | --- | @@ -119,6 +123,7 @@ migrate (one-shot) ──> postgres : применение migrations/*.sql | 4: индекс истории + EXPLAIN на ≥10 000 | `make explain` | 70 000 сообщений, в чате 20 000; с индексом Index Scan, 4 буфера, 0.03 мс на первой и глубокой (#15000) странице; без индекса Seq Scan + Sort, 940 буферов, 3–4 мс | `evidence/explain_history.txt` | | 4: expiry при коротком TTL | `auth_test.py` против `api-short-ttl` (TTL=2) | через 3 с → 401 (и из кэша) | `evidence/student_tests.txt` | | 4: logout, неверный пароль | `auth_test.py` | неверный пароль и неизвестный user дают одинаковый 401 | `evidence/student_tests.txt` | +| 4: logout при сбое записи в кэш | `dependency_test.py` (`docker compose pause valkey` во время logout) | до исправления: 204 и отозванный токен → 200 из кэша; после: 503, токен → 401, tombstone дописан после `unpause` | `evidence/logout_cache_failure.txt` | | 4: недоступность Redis/БД | `dependency_test.py` | Valkey stop: ready=200, запросы ~4 мс; PostgreSQL stop: live=200, ready и бизнес-запросы 503 мгновенно, непроверенный токен → 503, без токена 401; после start всё восстанавливается без рестарта API | `evidence/student_tests.txt` | | Graceful shutdown (из lab1) | `sigterm_test.sh` | `docker compose stop api` → exit 0 за < 1 с | `evidence/student_tests.txt` | @@ -128,13 +133,14 @@ migrate (one-shot) ──> postgres : применение migrations/*.sql | --- | --- | --- | --- | | `scripts/restart.sh`: stop api, valkey, postgres → up | данные и сессия на месте, токен тот же | PASS, кэш пустой, сессии берутся из PostgreSQL | ~11 с весь hook / потерь нет | | `docker compose stop valkey` | API работает без кэша | 200, ~4 мс на запрос (breaker), revoked-токен 401 | мгновенно / потерь нет (кэш) | +| `docker compose pause valkey` во время logout | logout не сообщает об успехе, отозванный токен не принимается | 503; после `unpause` токен → 401, tombstone записан фоновой задачей | ~1 с после восстановления Valkey / потерь нет | | `docker compose stop postgres` | 503 без зависаний, анонимный доступ не появляется | ready 503, бизнес 503, live 200, всё за < 0.1 с | API восстанавливается сам после `start postgres`, без своего рестарта; подтверждённые данные целы | | SIGTERM api | graceful exit 0 | exit 0, «Application shutdown complete» | `docker compose up -d --wait api` | ## Ограничения и следующие шаги - Один Docker-host, по одному PostgreSQL и Valkey, без репликации: потеря host или диска = потеря сервиса (бэкапы не настроены, это трек 2 пятёрки). -- Если logout пришёлся на момент сетевой недоступности Valkey, а сам Valkey при этом не перезапускался, старая запись в кэше может жить до `SESSION_CACHE_MAX_SECONDS` (≤ 5 мин). Это осознанная граница: TTL кэша ограничен именно поэтому. +- Защита от устаревшей записи после неудачного logout живёт в памяти процесса API. Если сам API перезапустится до того, как Valkey снова станет доступен, или (с lab3) запрос придёт на другую реплику, устаревшая запись может приниматься до `SESSION_CACHE_MAX_SECONDS` (≤ 5 мин). Клиент при этом получил 503, а не 204. Для нескольких реплик нужен общий механизм, например версия сессии в кэше или pub/sub-инвалидация. - Просроченные строки `sessions` не удаляются автоматически (есть индекс `expires_at` для будущей периодической очистки). - `/health/ready` не проверяет Valkey намеренно. - Тело запроса проверяется до аутентификации: на неавторизованный запрос с битым JSON вернётся 400, а не 401 (особенность FastAPI). Это не раскрывает данных. diff --git a/app/auth.py b/app/auth.py index fc6d1f28..298a65d6 100644 --- a/app/auth.py +++ b/app/auth.py @@ -14,7 +14,7 @@ from starlette.concurrency import run_in_threadpool from app import config from app.cache import REVOKED, SessionCache -from app.errors import BASIC_CHALLENGE, unauthorized +from app.errors import BASIC_CHALLENGE, ApiError, unauthorized from app.storage import Store, fmt_ts, user_row _hasher = PasswordHasher() @@ -109,4 +109,5 @@ async def logout(store: Store, cache: SessionCache, header: Optional[str]) -> No if expires_at is None: raise unauthorized("session expired or revoked") remaining = int((expires_at - datetime.now(timezone.utc)).total_seconds()) + 1 - await cache.revoke(digest, remaining) + if not await cache.revoke(digest, remaining): + raise ApiError(503, "unavailable", "logout not confirmed by session cache, retry later") diff --git a/app/cache.py b/app/cache.py index 7600b48a..02db961c 100644 --- a/app/cache.py +++ b/app/cache.py @@ -1,9 +1,10 @@ from __future__ import annotations +import asyncio import json import logging import time -from typing import Optional, Union +from typing import Dict, Optional, Set, Union import redis.asyncio as redis from redis.exceptions import RedisError @@ -19,6 +20,8 @@ class SessionCache: def __init__(self, url: Optional[str]): self._client: Optional[redis.Redis] = None self._down_until = 0.0 + self._pending_revokes: Dict[bytes, float] = {} + self._retry_tasks: Set[asyncio.Task] = set() if url: pool = redis.BlockingConnectionPool.from_url( url, @@ -45,8 +48,17 @@ class SessionCache: def _key(token_hash: bytes) -> str: return "session:" + token_hash.hex() + def _revoke_pending(self, token_hash: bytes) -> bool: + deadline = self._pending_revokes.get(token_hash) + if deadline is None: + return False + if time.monotonic() >= deadline: + self._pending_revokes.pop(token_hash, None) + return False + return True + async def get(self, token_hash: bytes) -> Union[dict, str, None]: - if not self._usable(): + if not self._usable() or self._revoke_pending(token_hash): return None try: raw = await self._client.get(self._key(token_hash)) @@ -69,13 +81,34 @@ class SessionCache: except (RedisError, OSError) as exc: self._failed("set", exc) - async def revoke(self, token_hash: bytes, ttl_seconds: int) -> None: - if self._client is None: - return + async def _write_tombstone(self, token_hash: bytes, ttl_seconds: int) -> bool: try: await self._client.set(self._key(token_hash), REVOKED, ex=max(1, min(ttl_seconds, config.SESSION_CACHE_MAX_SECONDS))) + return True except (RedisError, OSError) as exc: self._failed("revoke", exc) + return False + + async def revoke(self, token_hash: bytes, ttl_seconds: int) -> bool: + if self._client is None: + return True + if await self._write_tombstone(token_hash, ttl_seconds): + return True + deadline = time.monotonic() + config.SESSION_CACHE_MAX_SECONDS + 1 + self._pending_revokes[token_hash] = deadline + task = asyncio.create_task(self._retry_revoke(token_hash, ttl_seconds, deadline)) + self._retry_tasks.add(task) + task.add_done_callback(self._retry_tasks.discard) + return False + + async def _retry_revoke(self, token_hash: bytes, ttl_seconds: int, deadline: float) -> None: + while time.monotonic() < deadline: + await asyncio.sleep(1) + remaining = int(deadline - time.monotonic()) + if remaining > 0 and await self._write_tombstone(token_hash, min(ttl_seconds, remaining)): + logger.info("revocation tombstone written after cache recovery") + break + self._pending_revokes.pop(token_hash, None) async def ping(self) -> bool: if self._client is None: @@ -86,5 +119,7 @@ class SessionCache: return False async def close(self) -> None: + for task in list(self._retry_tasks): + task.cancel() if self._client is not None: await self._client.aclose() diff --git a/evidence/logout_cache_failure.txt b/evidence/logout_cache_failure.txt new file mode 100644 index 00000000..f85551e0 --- /dev/null +++ b/evidence/logout_cache_failure.txt @@ -0,0 +1,16 @@ +# Logout while the session cache cannot be written (PR feedback) +# date: 2026-10-15T10:56:08Z base commit: 13fa185 + fix in app/cache.py, app/auth.py +# scenario: live session cached -> docker compose pause valkey -> DELETE /auth/sessions/current -> unpause -> wait 6s -> GET /users/me +# before fix: logout 204, revoked token -> 200 from stale cache + +$ python3 student-tests/dependency_test.py +ok - Valkey caches sessions with TTL<=300s and keeps logout tombstones +ok - Valkey stopped: ready=200, reads/writes OK, revoked token 401, 2 ms/request +ok - tombstone write failed during logout -> 503, cached session never accepted again, tombstone repaired +ok - PostgreSQL stopped: live=200, ready/business=503 in 0.0s total, unverified token not trusted +ok - PostgreSQL started again: API recovers without restart, data intact +PASS: 5 checks + +$ docker compose logs api | grep -E "revoke|tombstone" +WARNING:messenger.cache:cache revoke failed (TimeoutError); bypassing cache for 5s +INFO:messenger.cache:revocation tombstone written after cache recovery diff --git a/student-tests/dependency_test.py b/student-tests/dependency_test.py index 2e7a7964..67d9b4a2 100755 --- a/student-tests/dependency_test.py +++ b/student-tests/dependency_test.py @@ -1,4 +1,5 @@ #!/usr/bin/env python3 +import hashlib import time from stack import BASE_URL, Client, Failure, check, compose, main_wrapper, ok, valkey @@ -48,6 +49,29 @@ def main(): finally: compose("start", "valkey") + paused = c.user("pause") + key = "session:" + hashlib.sha256(paused["token"].encode("ascii")).hexdigest() + deadline = time.monotonic() + 15 + while not valkey("GET", key).startswith("{"): + check(time.monotonic() < deadline, "live session must be cached before the failure") + c.call("GET", "/api/v1/users/me", actor=paused, schema="User") + time.sleep(0.5) + try: + compose("pause", "valkey") + status = c.call("DELETE", "/api/v1/auth/sessions/current", [204, 503], actor=paused)["status"] + finally: + compose("unpause", "valkey") + check(status == 503, "logout must not report success while the cache still holds the live session (got %d)" % status) + time.sleep(6) + c.call("GET", "/api/v1/users/me", 401, actor=paused) + deadline = time.monotonic() + 10 + while valkey("GET", key) != "revoked": + check(time.monotonic() < deadline, "tombstone must be written once Valkey is back") + time.sleep(0.5) + c.call("GET", "/api/v1/users/me", 401, actor=paused) + c.call("DELETE", "/api/v1/auth/sessions/current", 401, actor=paused) + ok("tombstone write failed during logout -> 503, cached session never accepted again, tombstone repaired") + fresh = c.user("dbdown") try: compose("stop", "postgres") -- 2.54.0