Add resilient Valkey User cache with PostgreSQL authorization

This commit is contained in:
Самохвалов Андрей Ремович
2026-10-02 11:25:10 +03:00
parent ed7a27629d
commit d59d3f4adc
8 changed files with 205 additions and 13 deletions
+1
View File
@@ -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.
+13 -6
View File
@@ -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 теста.
+9
View File
@@ -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
+48
View File
@@ -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).
+1 -1
View File
@@ -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
+53
View File
@@ -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
+9 -6
View File
@@ -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:
+71
View File
@@ -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()