Add resilient Valkey User cache with PostgreSQL authorization
This commit is contained in:
@@ -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.
|
||||
|
||||
@@ -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 теста.
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
@@ -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
|
||||
|
||||
@@ -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
@@ -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:
|
||||
|
||||
@@ -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()
|
||||
Reference in New Issue
Block a user