diff --git a/.env.example b/.env.example index 6f07f87..5fa7e49 100644 --- a/.env.example +++ b/.env.example @@ -2,3 +2,4 @@ APP_PORT=8080 SESSION_TTL_SECONDS=3600 # Create secrets/postgres_password and secrets/database_url locally before Compose. +# Valkey is internal only and caches User projections for 60 seconds; no named volume is needed. diff --git a/REPORT.md b/REPORT.md index 86eac0d..412da26 100644 --- a/REPORT.md +++ b/REPORT.md @@ -1,13 +1,13 @@ # Отчёт — лабораторная 2 - Автор, группа: Самохвалов Андрей Ремович, БПИ-2302. -- Целевая оценка: 5, трек 2 (сравнение запросов и восстановление). Доказательства уровня 4 и трека 2 дополняются в следующих блоках работы. +- Целевая оценка: 5, трек 2 (сравнение запросов и восстановление). Кэш и отказы проверены; индекс и исследование трека дополняются в следующих блоках. - Ветка: `solution/bpi2302-samohvalov`; commit/PR указываются после публикации. - Источники: `README.md`, `COURSE.md`, `contracts/README.md`, `contracts/openapi.json`, публичные тесты и примеры этого репозитория; FastAPI, psycopg, PostgreSQL и Argon2id. Код и инструкции подготовлены с помощью ИИ Codex и проверяются запуском команд ниже. ## Запуск из чистого clone -Нужны Docker с Compose, Python 3.9+ и `make`. Стенд рассчитан на учебный localhost. API собирается из исходников в `python:3.12.12-slim-bookworm`; БД — `postgres:17.6-bookworm`. Python-зависимости закреплены в `requirements.txt`. Порт API опубликован только на `127.0.0.1:8080`; PostgreSQL наружу не публикуется. На моей macOS с Colima команды `make test` и `make test-persistence` выполнялись на хосте с разрешённым доступом к Docker socket и loopback. В ограниченном sandbox `127.0.0.1:8080` был недоступен; проверка не запускалась внутри VM и SSH-туннель не требовался. +Нужны Docker с Compose, Python 3.9+ и `make`. Стенд рассчитан на учебный localhost. API собирается из исходников в `python:3.12.12-slim-bookworm`; БД — `postgres:17.6-bookworm`, кэш — `valkey/valkey:8.0.2-alpine`. Python-зависимости закреплены в `requirements.txt`; кэш использует короткий RESP-клиент стандартной библиотеки. Порт API опубликован только на `127.0.0.1:8080`; PostgreSQL и Valkey наружу не публикуются. На моей macOS с Colima команды `make test` и `make test-persistence` выполнялись на хосте с разрешённым доступом к Docker socket и loopback. В ограниченном sandbox `127.0.0.1:8080` был недоступен; проверка не запускалась внутри VM и SSH-туннель не требовался. После чистого clone создать локальные файлы, которые исключены из Git: @@ -36,12 +36,15 @@ make test-persistence ACTION_SCRIPT=scripts/restart.sh ## Архитектура и решения -Клиент → FastAPI (`api`) → PostgreSQL (`postgres`); `postgres_data` сохраняет состояние между перезапусками. PostgreSQL — источник истины для users, chats, memberships, messages и sessions. Создание чата с участниками выполняется одной транзакцией. Пароль хранится как Argon2id hash, непрозрачный токен выдаётся только клиенту, в БД лежит его SHA-256 и абсолютный срок действия. Из lab1 сохранены чаты, членство, сообщения и keyset-пагинация; `X-User-Id` заменён входом по Basic и запросами по Bearer. `.env.example` задаёт опубликованный `APP_PORT` и `SESSION_TTL_SECONDS`; `DATABASE_URL_FILE`, `APP_HOST` и порт внутри контейнера установлены Compose. Pool ограничен восемью соединениями и SQL timeout 5 секунд. +Клиент → FastAPI (`api`) → PostgreSQL (`postgres`) и необязательный Valkey (`valkey`); `postgres_data` сохраняет состояние между перезапусками. PostgreSQL — источник истины для users, chats, memberships, messages и sessions. Создание чата с участниками выполняется одной транзакцией. Пароль хранится как Argon2id hash, непрозрачный токен выдаётся только клиенту, в БД лежит его SHA-256 и абсолютный срок действия. Из lab1 сохранены чаты, членство, сообщения и keyset-пагинация; `X-User-Id` заменён входом по Basic и запросами по Bearer. `.env.example` задаёт опубликованный `APP_PORT` и `SESSION_TTL_SECONDS`; `DATABASE_URL_FILE`, `VALKEY_URL`, `APP_HOST` и порт внутри контейнера установлены Compose. Pool ограничен восемью соединениями и SQL timeout 5 секунд. + +Каждый Bearer-запрос проверяет hash, срок и отзыв сессии в PostgreSQL. После этого публичная проекция User читается по UUID из Valkey с TTL 60 секунд; на промахе или отказе кэша читается PostgreSQL. После регистрации создаётся новый UUID; endpoint изменения/удаления пользователя в lab2 нет, поэтому инвалидация при записи не требуется. Потеря Valkey очищает лишь ускоритель, не сессии или подтверждённые данные. У кэша нет именованного volume, и приложение не полагается на сохранность его данных. При потере PostgreSQL авторизация не использует даже заполненный кэш и возвращает 503; `/health/ready` зависит от БД, но не от кэша. | Роль | Образ/версия | Проверка | Хранилище/секрет | | --- | --- | --- | --- | | API | Собственный build на Python 3.12.12 | `/health/ready` | Без volume; `database_url` через Docker secret | | PostgreSQL | postgres:17.6-bookworm | `pg_isready` | `postgres_data`; `postgres_password` через Docker secret | +| Valkey | valkey/valkey:8.0.2-alpine | `valkey-cli ping` | Временный кэш User; без именованного volume и внешнего порта | ## Доказательства критериев @@ -51,10 +54,11 @@ make test-persistence ACTION_SCRIPT=scripts/restart.sh | Стенд и миграции уровня 3 | `docker compose --env-file .env up -d --build --wait`; повторный `scripts/migrate.py` | API и БД healthy, повторная миграция завершилась без ошибки | `evidence/restart-2026-10-02.txt` | | Сохранность уровня 3 | `make test-persistence ACTION_SCRIPT=scripts/restart.sh` | PASS: прежние данные и сессия после рестарта обоих сервисов | `evidence/restart-2026-10-02.txt` | | Отказ обязательной БД | Остановить `postgres`, запросить readiness и защищённый endpoint | Оба HTTP 503; затем БД восстановлена, сервисы healthy | `evidence/restart-2026-10-02.txt` | -| Уровень 4 | Выполняется в следующих блоках | Пока не заявлен как проверенный | — | +| Кэш и отказы уровня 4 | `docker compose exec -T api python - < student-tests/test_cache_failures.py`; отказ Valkey/БД | Два интеграционных теста PASS; SQL 2/1/2 на miss/hit/reload; Valkey hit/miss 1/2; smoke проходит без кэша; при отказе БД 503, отозванный токен после рестарта кэша 401 | `evidence/cache-2026-10-02.txt` | +| Индекс и остальные проверки уровня 4 | Выполняются в следующем блоке | Пока не заявлены как проверенные | — | | Трек 5 | Выполняется после уровня 4 | Пока не заявлен как проверенный | — | -У `api` и `postgres` изменились времена `StartedAt` при сохранении именованного volume; точные значения приведены в evidence. Это подтверждает фактический перезапуск обоих контейнеров. Проверка `make validate` локально пока не завершена: DNS до `files.pythonhosted.org` не позволил установить `openapi-spec-validator==0.7.2`; отдельный CI workflow устанавливает зависимости из `requirements-dev.txt` для проверки контракта. +У `api`, `postgres` и `valkey` изменились времена `StartedAt` при сохранении именованного volume; точные значения приведены в evidence. Это подтверждает фактический перезапуск трёх контейнеров. Проверка `make validate` локально пока не завершена: DNS до `files.pythonhosted.org` не позволил установить `openapi-spec-validator==0.7.2`; отдельный CI workflow устанавливает зависимости из `requirements-dev.txt` для проверки контракта. ## Эксперименты и отказы @@ -64,7 +68,10 @@ make test-persistence ACTION_SCRIPT=scripts/restart.sh | --- | --- | --- | --- | | Полный restart API и PostgreSQL | Тот же действующий токен читает сообщение | Публичный persistence PASS | Подтверждённая запись сохранена; время восстановления в пределах лимита hook | | Остановка PostgreSQL | Readiness и защищённый запрос дают ограниченный отказ | Оба HTTP 503; после запуска БД healthy | Без принятия анонимного запроса | +| Остановка Valkey | Запросы идут через PostgreSQL | Публичный smoke PASS при остановленном кэше; затем Valkey healthy | Данные и сессии не зависят от кэша | +| Остановка PostgreSQL при заполненном User-кэше | Кэш не авторизует без БД | Readiness и защищённый запрос 503; после восстановления действующий токен 200 | HTTP-клиенту нужен timeout больше 5-секундного ожидания pool | +| Отзыв токена и рестарт Valkey | Старый токен остаётся недействительным | После restart кэша прежний токен 401 | Отзыв хранится в PostgreSQL | ## Ограничения и следующие шаги -Подтверждён рестарт одного API и одного PostgreSQL с сохранением volume. Это не высокая доступность: отказ БД временно делает API недоступным. Локальный HTTP не предназначен для удалённой передачи паролей без TLS. Valkey, проверки уровня 4, сравнение ≥100 000 сообщений и восстановление в новое хранилище ещё должны быть добавлены; их результаты нельзя выводить из smoke или persistence теста. +Подтверждён рестарт одного API, одного PostgreSQL и Valkey с сохранением volume БД. Это не высокая доступность: отказ БД временно делает API недоступным, а заполненный кэш не может заменить проверку сессии. Локальный HTTP не предназначен для удалённой передачи паролей без TLS. Проверки индекса на ≥10 000 сообщений, сравнение ≥100 000 сообщений и восстановление в новое хранилище ещё должны быть добавлены; их результаты нельзя выводить из smoke или persistence теста. diff --git a/compose.yaml b/compose.yaml index 036ca8e..9ad899d 100644 --- a/compose.yaml +++ b/compose.yaml @@ -23,6 +23,7 @@ services: APP_HOST: 0.0.0.0 APP_PORT: 8080 DATABASE_URL_FILE: /run/secrets/database_url + VALKEY_URL: redis://valkey:6379/0 SESSION_TTL_SECONDS: ${SESSION_TTL_SECONDS:-3600} secrets: - database_url @@ -38,6 +39,14 @@ services: retries: 20 start_period: 5s + valkey: + image: valkey/valkey:8.0.2-alpine + healthcheck: + test: ["CMD", "valkey-cli", "ping"] + interval: 2s + timeout: 2s + retries: 20 + secrets: postgres_password: file: ./secrets/postgres_password diff --git a/evidence/cache-2026-10-02.txt b/evidence/cache-2026-10-02.txt new file mode 100644 index 0000000..06f1c90 --- /dev/null +++ b/evidence/cache-2026-10-02.txt @@ -0,0 +1,48 @@ +Lab 2 U4: Valkey User cache, 2026-10-02, macOS/Colima arm64. +Commands were run on the local Compose stack with PostgreSQL data volume preserved. + +docker compose --env-file .env up -d --build --wait + PASS: api, postgres, valkey healthy; valkey/valkey:8.0.2-alpine. + +docker compose --env-file .env exec -T api python - < student-tests/test_cache_failures.py + Ran 2 tests in 0.207s: OK. + SQL queries (miss/hit/reload): 2/1/2; Valkey hit/miss deltas: 1/2. + The reload deletes only the disposable test user's cache key. + The SQL counter wraps real psycopg connection.execute calls in the Store process. + Every authenticated request still checks its session in PostgreSQL; only User lookup is cached. + The test also points Valkey at a closed TCP port and verifies PostgreSQL fallback, + then revokes the token and verifies 401. + +make test BASE_URL=http://127.0.0.1:8080 + PASS: lab2 public API scenario with Valkey healthy. + +docker compose --env-file .env stop valkey +make test BASE_URL=http://127.0.0.1:8080 +docker compose --env-file .env up -d --wait valkey + PASS: same public API scenario with Valkey stopped; it was restored healthy. + +Before persistence hook, docker inspect StartedAt (UTC): + api 2026-10-02T08:05:51.833412908Z + postgres 2026-10-02T07:24:25.230933733Z + valkey 2026-10-02T08:05:51.322012488Z + +make test-persistence ACTION_SCRIPT=scripts/restart.sh BASE_URL=http://127.0.0.1:8080 + PASS: persistence preserved confirmed data and existing session. + +After persistence hook, docker inspect StartedAt (UTC): + api 2026-10-02T08:07:11.335901585Z + postgres 2026-10-02T08:07:08.754444696Z + valkey 2026-10-02T08:07:08.754742886Z +All three containers really restarted; PostgreSQL volume was not deleted. + +Manual HTTP failure run (one token held in process memory, no token printed): + Warm User cache through two authenticated GET /users/me requests. + Stop PostgreSQL: /health/ready=503, authenticated cached-User request=503. + Restore PostgreSQL: authenticated request=200. + Revoke session: DELETE /auth/sessions/current=204. + Stop/start Valkey: same revoked token still receives 401. + The HTTP observer needed timeout=15s; timeout=5s expired at the same boundary + as the configured PostgreSQL pool timeout and did not observe the 503. + +make check + PASS: skeleton structure, refs and Python syntax (not an application test). diff --git a/scripts/restart.sh b/scripts/restart.sh index 639f272..de19bad 100755 --- a/scripts/restart.sh +++ b/scripts/restart.sh @@ -2,7 +2,7 @@ set -eu cd "$(dirname "$0")/.." -# Stop and start every current service, including state stores added in later labs. +# Stop and start API, PostgreSQL and Valkey without deleting PostgreSQL data. # Compose preserves named volumes because neither command removes them. docker compose --env-file .env stop docker compose --env-file .env up -d --wait diff --git a/src/cache.py b/src/cache.py new file mode 100644 index 0000000..b4248a9 --- /dev/null +++ b/src/cache.py @@ -0,0 +1,53 @@ +"""Best-effort cache of immutable public User projections.""" + +import json +import os +import socket +from urllib.parse import urlparse + +USER_TTL_SECONDS = 60 + + +def command(*parts: str) -> str | None: + """Send one RESP command; every call has bounded connect and read times.""" + target = urlparse(os.environ.get("VALKEY_URL", "redis://valkey:6379/0")) + payload = b"*" + str(len(parts)).encode() + b"\r\n" + for part in parts: + value = part.encode("utf-8") + payload += b"$" + str(len(value)).encode() + b"\r\n" + value + b"\r\n" + with socket.create_connection((target.hostname or "valkey", target.port or 6379), timeout=0.5) as sock: + sock.settimeout(0.5) + sock.sendall(payload) + with sock.makefile("rb") as response: + kind = response.read(1) + if kind in (b"+", b":"): + return response.readline().rstrip(b"\r\n").decode("utf-8") + if kind == b"$": + length = int(response.readline()) + if length < 0: + return None + value = response.read(length) + if len(value) != length or response.read(2) != b"\r\n": + raise OSError("incomplete Valkey response") + return value.decode("utf-8") + raise OSError("invalid Valkey response") + + +def get_user(user_id: str) -> dict | None: + try: + value = command("GET", "user:" + user_id) + except (OSError, ValueError, UnicodeError): + return None + if value is None: + return None + try: + return json.loads(value) + except (json.JSONDecodeError, TypeError): + return None + + +def put_user(user_id: str, user: dict) -> None: + try: + command("SET", "user:" + user_id, json.dumps(user, ensure_ascii=False), "EX", str(USER_TTL_SECONDS)) + except (OSError, ValueError, UnicodeError): + pass diff --git a/src/store.py b/src/store.py index 14c6d63..6f43bda 100644 --- a/src/store.py +++ b/src/store.py @@ -16,7 +16,7 @@ from fastapi import HTTPException from psycopg.errors import UniqueViolation from psycopg_pool import PoolTimeout -from . import db +from . import cache, db from .auth import BASIC_CHALLENGE, BEARER_CHALLENGE, token_hash, unauthorized password_hasher = PasswordHasher() @@ -112,13 +112,18 @@ class Store: user_uuid = UUID(user_id) except (ValueError, TypeError): raise HTTPException(401) from None + cached = cache.get_user(str(user_uuid)) + if cached is not None: + return cached with connection() as conn: row = conn.execute( "SELECT id,username,display_name,created_at FROM users WHERE id=%s", (user_uuid,) ).fetchone() if row is None: raise HTTPException(401) - return user_view(row) + result = user_view(row) + cache.put_user(str(user_uuid), result) + return result def create_session(self, username: str, password: str) -> dict: with connection() as conn: @@ -144,14 +149,12 @@ class Store: def authenticated(self, token: str) -> dict: with connection() as conn: row = conn.execute( - "SELECT u.id,u.username,u.display_name,u.created_at FROM sessions s " - "JOIN users u ON u.id=s.user_id " - "WHERE s.token_hash=%s AND s.expires_at>clock_timestamp()", + "SELECT user_id FROM sessions WHERE token_hash=%s AND expires_at>clock_timestamp()", (token_hash(token),), ).fetchone() if row is None: raise unauthorized(BEARER_CHALLENGE) - return user_view(row) + return self.user(str(row["user_id"])) def revoke_session(self, token: str) -> None: with connection() as conn: diff --git a/student-tests/test_cache_failures.py b/student-tests/test_cache_failures.py new file mode 100644 index 0000000..d3c6929 --- /dev/null +++ b/student-tests/test_cache_failures.py @@ -0,0 +1,71 @@ +"""Real PostgreSQL and Valkey checks for the optional User cache.""" + +import os +import unittest +from contextlib import contextmanager +from unittest.mock import patch +from uuid import uuid4 + +from src import cache +from src.store import Store, connection + + +@unittest.skipUnless((os.environ.get("DATABASE_URL") or os.environ.get("DATABASE_URL_FILE")) + and os.environ.get("VALKEY_URL"), + "set DATABASE_URL or DATABASE_URL_FILE and VALKEY_URL for disposable services") +class CacheTests(unittest.TestCase): + def setUp(self): + self.store = Store() + self.user = self.store.register("u_" + uuid4().hex[:16], "Кэш", "Test-password-123") + self.token = self.store.create_session(self.user["username"], "Test-password-123")["token"] + + def test_hit_miss_and_sql_counts(self): + statements = [] + + class CountingConnection: + def __init__(self, wrapped): + self.wrapped = wrapped + + def execute(self, query, params=None): + statements.append(query) + return self.wrapped.execute(query, params) + + @contextmanager + def counted_connection(): + with connection() as conn: + yield CountingConnection(conn) + + with patch("src.store.connection", counted_connection): + before = cache.command("INFO", "stats") + self.assertEqual(self.store.authenticated(self.token), self.user) + miss_sql = len(statements) + self.assertEqual(miss_sql, 2) # session plus User on miss + statements.clear() + self.assertEqual(self.store.authenticated(self.token), self.user) + hit_sql = len(statements) + self.assertEqual(hit_sql, 1) # session only on cache hit + cache.command("DEL", "user:" + self.user["id"]) + statements.clear() + self.assertEqual(self.store.authenticated(self.token), self.user) + reload_sql = len(statements) + self.assertEqual(reload_sql, 2) # User reload after flush + after = cache.command("INFO", "stats") + def stat(info, name): + return int(next(line.split(":", 1)[1] for line in info.splitlines() if line.startswith(name + ":"))) + self.assertGreaterEqual(stat(after, "keyspace_hits") - stat(before, "keyspace_hits"), 1) + self.assertGreaterEqual(stat(after, "keyspace_misses") - stat(before, "keyspace_misses"), 2) + print(f"SQL queries (miss/hit/reload): {miss_sql}/{hit_sql}/{reload_sql}; " + f"Valkey hit/miss deltas: {stat(after, 'keyspace_hits') - stat(before, 'keyspace_hits')}/" + f"{stat(after, 'keyspace_misses') - stat(before, 'keyspace_misses')}") + + def test_cache_failure_does_not_change_authentication(self): + with patch.dict(os.environ, {"VALKEY_URL": "redis://127.0.0.1:1/0"}): + self.assertEqual(self.store.authenticated(self.token), self.user) + self.store.revoke_session(self.token) + with self.assertRaises(Exception) as failure: + self.store.authenticated(self.token) + self.assertEqual(failure.exception.status_code, 401) + + +if __name__ == "__main__": + unittest.main()