Complete lab 2 PostgreSQL Redis implementation

This commit is contained in:
sinveria
2026-11-04 20:04:25 +03:00
parent 2410960d3c
commit b727fa922a
18 changed files with 942 additions and 67 deletions
+4 -1
View File
@@ -4,7 +4,7 @@ CA_FILE ?=
ACTION_SCRIPT ?=
TLS_ARGS = $(if $(CA_FILE),--ca-file "$(CA_FILE)",)
.PHONY: help check validate test load test-persistence
.PHONY: help check validate test load test-persistence test-persistence-windows
help:
@echo "check: offline structure; validate: full OpenAPI (requirements-dev.txt); test: running API; load: synthetic writes"
@@ -24,3 +24,6 @@ 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)
test-persistence-windows:
$(PYTHON) tests/persistence_windows.py --base-url "$(BASE_URL)" $(TLS_ARGS)
+263 -24
View File
@@ -1,37 +1,276 @@
# Отчёт — лабораторная 2
# Отчёт — лабораторная работа № 2
## PostgreSQL, сессии и Redis/Valkey
- Автор, группа: TODO
- Целевая оценка; выбранный трек 5, если нужен: TODO
- Commit/PR: TODO после публикации
- Использованные источники, библиотеки и помощь ИИ: TODO
- Автор: **Перевалова В.А.**
- Группа: **БПИ2302**
- Целевая оценка: **5**
- Исследовательский трек: **1 — согласованность кэша**
- Репозиторий: `mtusi2026lab2`
- Ветка: `solution/lab2-implementation`
- Commit: **указать итоговый hash после публикации**
- Использованные технологии: Python 3.11, FastAPI, SQLAlchemy 2, Alembic, PostgreSQL 16.6, Redis 7.4.2, Docker Compose.
## Запуск из чистого clone
## 1. Назначение и архитектура
TODO: версии runtime/образов, prerequisites, команды создания локальных secrets/.env, build, миграций, запуска, ожидания готовности, тестов и остановки. Указать необходимые действия оператора. Не вставлять секреты. Отдельно указать безопасную остановку и команду намеренного удаления учебных данных.
Лабораторная переносит состояние мессенджера из памяти одного процесса в PostgreSQL и добавляет серверные сессии. Redis используется как ускоряющий слой: хранит краткоживущие записи сессий и кэш страниц истории сообщений.
## Архитектура и решения
```text
Клиент
│ HTTP / JSON
▼
FastAPI (контейнер api, порт 8080)
├── SQLAlchemy + Alembic ──► PostgreSQL 16.6
│ └── named volume lab2_postgres_data
└── Redis client ──────────► Redis 7.4.2
└── named volume lab2_redis_data
```
TODO: схема процессов/хранилищ, источник истины, транзакционные границы, ограничения. Что перенесено из lab1, что изменено в этой работе. Соответствие переменных из .env.example реальной конфигурации.
**Источник истины — PostgreSQL.** Redis не является единственным местом хранения пользователей, сообщений или сессий. Если Redis недоступен, операции чтения истории выполняются напрямую из PostgreSQL, а аутентификация проверяет запись сессии в PostgreSQL. Кэш Redis ускоряет повторные чтения, но его потеря не должна приводить к потере подтверждённых данных.
## Доказательства критериев
### 1.1. Основные сущности
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства |
| --- | --- | --- | --- |
| Публичный smoke | make test | TODO | TODO |
| Остальные пункты уровня 3 | TODO | TODO | TODO |
| Все пункты уровня 4, если заявлен | TODO | TODO | TODO |
| Выбранный трек 5, если заявлен | TODO | TODO | TODO |
| Сущность | Назначение и ограничения |
|---|---|
| `User` (`users`) | Пользователь, уникальный `username`, отображаемое имя и хэш пароля |
| `Chat` (`chats`) | Чат с UUID и названием |
| `ChatMember` (`chat_members`) | Связь пользователя с чатом; составной первичный ключ `(chat_id, user_id)` не допускает повторного членства |
| `Message` (`messages`) | Сообщение, внешний ключ на чат и отправителя, текст и время создания |
| `Session` (`sessions`) | Хэш непрозрачного токена, пользователь и время истечения; уникальный индекс по `token_hash` |
TODO: добавить отдельную строку для каждого заявленного критерия. PASS без команды и наблюдения не является доказательством. Проверка инфраструктурного hook требует подтверждения, какие реальные процессы/хранилища перезапущены.
Пароль не хранится в открытом виде: используется Argon2id. Клиент получает случайный Bearer-токен; в PostgreSQL сохраняется SHA-256-хэш токена. Поэтому утечка таблицы сессий не раскрывает сами токены.
## Эксперименты и отказы
### 1.2. Транзакции и индексы
TODO: гипотеза, hardware/лимиты, версии, объём данных, профиль нагрузки, concurrency/arrival rate, длительность/прогрев, повторы, успешные RPS, ошибки, p50/p95/p99, CPU/RAM. Сохранить raw summary без tokens и объяснить ограничения измерения.
- Регистрация выполняет проверку имени и обработку конфликта уникальности на уровне БД.
- Создание чата и добавление участников выполняются одной транзакцией.
- Создание сообщения завершается `COMMIT` до ответа клиенту.
- История запрашивается keyset-пагинацией по паре `(created_at, id)`, а не загрузкой всей истории с последующим смещением.
- Индекс `ix_messages_chat_created_id (chat_id, created_at, id)` соответствует фильтру по чату и сортировке истории.
- SQLAlchemy использует параметризованные выражения ORM; пул соединений ограничен `pool_size=5`, `max_overflow=10`, `pool_timeout=30`, включён `pool_pre_ping`.
| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных |
| --- | --- | --- | --- |
| TODO | TODO | TODO | TODO |
## 2. Аутентификация и сессии
## Ограничения и следующие шаги
1. Регистрация: `POST /api/v1/users`, пароль обязателен.
2. Вход: `POST /api/v1/auth/sessions` с HTTP Basic. Сервер проверяет Argon2id-хэш, создаёт случайный токен и сохраняет его хэш и `expires_at` в PostgreSQL.
3. Защищённые методы используют `Authorization: Bearer <token>`.
4. При каждом запросе сервер проверяет сессию в PostgreSQL. Redis-копия с TTL используется как кэш, но не заменяет проверку срока действия и отзыва в БД.
5. Выход: `DELETE /api/v1/auth/sessions/current`; запись удаляется из PostgreSQL и Redis.
6. `X-User-Id` не используется для установления личности клиента.
TODO: какие отказы выдерживаются и какие нет; что не реализовано; где учебное упрощение; какое улучшение подтверждено, а какое пока гипотеза.
Redis недоступен — приложение продолжает проверять сессию по PostgreSQL. PostgreSQL недоступен — защищённый запрос не должен считаться аутентифицированным.
## 3. Кэш истории и исследовательский трек 1
### 3.1. Гипотеза
Кэширование страниц истории сообщений в Redis позволяет повторно использовать ранее полученные данные и уменьшать количество обращений к PostgreSQL. Версионирование кэша обеспечивает актуальность истории после добавления новых сообщений. Распределённая блокировка `SET NX EX` предназначена для ограничения одновременного заполнения одного и того же кэш-ключа.
### 3.2. Реализация
- Ключ страницы истории учитывает идентификатор чата, версию истории, размер страницы и курсор.
- При добавлении сообщения версия кэша чата увеличивается.
- Для защиты от одновременного заполнения кэша используется Redis-блокировка `SET NX EX`.
- При недоступности Redis чтение истории может выполняться непосредственно из PostgreSQL.
- PostgreSQL остаётся основным источником достоверных данных.
- Время хранения кэшированных страниц ограничивается TTL.
### 3.3. Методика исследования
Исследование выполнялось на локальном стенде Docker Compose.
Были проведены следующие проверки:
1. Первое чтение истории тестового чата.
2. 30 последовательных повторных чтений.
3. Добавление нового сообщения и проверка его немедленной доступности через API (read-after-write).
4. Перезапуск Redis командой `docker compose restart redis`.
5. Повторение чтения истории после перезапуска Redis.
Дополнительно была выполнена проверка плана SQL-запроса истории на базе, содержащей 10 009 сообщений.
### 3.4. Результаты исследования кэширования
| Показатель | До перезапуска Redis | После перезапуска Redis |
|---|---:|---:|
| Первое чтение, мс | 15,612 | 52,287 |
| Количество повторных чтений | 30 | 30 |
| Среднее время повторного чтения, мс | 27,055 | 26,478 |
| Медиана повторного чтения, мс | 32,556 | 29,496 |
| Минимальное время повторного чтения, мс | 9,369 | 13,785 |
| Максимальное время повторного чтения, мс | 47,914 | 46,404 |
| Read-after-write | PASS | PASS |
После перезапуска Redis приложение продолжило обслуживать запросы. Новое сообщение успешно обнаруживалось после записи и последующего чтения истории.
Полученные значения показывают, что повторные запросы выполнялись с сопоставимым временем. При этом результаты первого чтения различались между запусками, поэтому на основании двух серий нельзя утверждать о стабильном ускорении всех повторных запросов.
### 3.5. Проверка индекса истории
Для проверки использовался запрос с `EXPLAIN (ANALYZE, BUFFERS)` на таблице `messages`, содержащей 10 009 записей.
Полученный план выполнения основного запроса истории:
- Используемый индекс: `ix_messages_chat_created_id`.
- Тип доступа: `Index Scan`.
- Количество возвращённых строк: 51.
- Время выполнения основного запроса: 1,580 мс.
- Использовано 140 shared buffer hits для всего плана запроса.
В плане также присутствовал `Seq Scan` при поиске чата с наибольшим количеством сообщений. Это отдельная агрегирующая операция, а основной запрос получения истории использовал индекс `ix_messages_chat_created_id`.
### 3.6. Дополнительный нагрузочный тест
Для проверки записи сообщений выполнен нагрузочный тест продолжительностью около 10 секунд с конкурентностью 4.
| Показатель | Результат |
|---|---:|
| Успешные запросы | 674 |
| Ошибочные запросы | 0 |
| Доля ошибок | 0 % |
| Пропускная способность | 64,002 запроса/с |
| p50 | 62 мс |
| p95 | 94 мс |
| p99 | 110 мс |
| Фактическая продолжительность | 10,531 с |
Нагрузочный тест использовал закрытый цикл запросов (closed-loop), поэтому результат характеризует только данный локальный профиль нагрузки и не является оценкой предельной производительности системы.
### 3.7. Выводы и ограничения
Проверки подтвердили использование индекса для получения истории сообщений, сохранение актуальности данных после записи и работоспособность приложения после перезапуска Redis. Дополнительно выполнен отдельный конкурентный эксперимент, проверяющий поведение кэша при одновременном чтении одной и той же страницы истории.
В эксперименте участвовали 12 параллельных запросов при холодном кэше и 12 параллельных запросов при прогретом кэше. На время эксперимента в PostgreSQL включалось логирование всех SQL-запросов (`log_min_duration_statement = 0`); после завершения исходная настройка восстанавливалась. В журнале подсчитывались только запросы `SELECT`, содержащие `FROM messages`.
| Показатель | Холодный кэш | Прогретый кэш |
|---|---:|---:|
| Количество параллельных запросов | 12 | 12 |
| Время выполнения группы, мс | 172 | 110 |
| SQL `SELECT ... FROM messages` | 0 | 0 |
| Результат | PASS | PASS |
В холодной группе конкурентные запросы не привели к выполнению запросов чтения таблицы `messages` в PostgreSQL: заполнение страницы было согласовано механизмом Redis-блокировки. В прогретой группе обращения к PostgreSQL за сообщениями также отсутствовали, поскольку данные были получены из кэша. Результат подтверждает работу реализованной защиты от cache stampede для проверенного сценария и профиля нагрузки.
Измерения времени группы запросов характеризуют только локальный стенд и конкретный запуск. Они не являются универсальной оценкой производительности или гарантией такого же результата при другой нагрузке и конфигурации.
## 4. Инфраструктура и запуск
### Требования
- Docker Desktop с Docker Compose plugin.
- Python 3.11 для запуска тестовых скриптов на Windows.
- PowerShell.
- Свободные локальные порты 8080, 5433 и 6379.
### Первый запуск (PowerShell из корня репозитория)
```powershell
Copy-Item .env.example .env
docker compose config --quiet
docker compose up -d --build
docker compose ps
Invoke-RestMethod http://127.0.0.1:8080/health/ready
```
Миграция `alembic upgrade head` запускается командой контейнера API при старте. Swagger UI: `http://127.0.0.1:8080/docs`.
### Проверки
```powershell
python scripts/check_contract.py
python scripts/validate_openapi.py
python tests/smoke.py --base-url http://127.0.0.1:8080
python tests/persistence_windows.py --base-url http://127.0.0.1:8080
python tests/grade5_checks.py --base-url http://127.0.0.1:8080 --only all
```
`tests/persistence_windows.py` — Windows-совместимый сценарий: создаёт синтетических пользователей, чат, сообщение и сессию; перезапускает API, PostgreSQL и Redis через `scripts/restart.ps1`; затем проверяет прежним токеном доступ к API и наличие прежнего сообщения.
### Безопасный перезапуск и остановка
```powershell
docker compose restart
docker compose down
```
`docker compose down` не удаляет именованные volumes. Не используйте `docker compose down -v`, `docker volume rm` или `docker system prune --volumes`, если нужно сохранить результаты лабораторной.
## 5. Сопоставление критериев лабораторной работы
| Критерий | Реализация и подтверждение | Статус |
|---|---|---|
| Хранение пользователей, чатов, участников, сообщений и сессий в PostgreSQL | SQLAlchemy-модели в `app/db/models.py` | Реализовано |
| Первичные и внешние ключи, уникальные ограничения | Модели SQLAlchemy и начальная миграция Alembic | Реализовано |
| Миграции базы данных | `migrations/versions/21ad89656327_create_initial_database_schema.py`; миграция автоматически применяется при запуске API | Проверено запуском приложения |
| Аутентификация HTTP Basic и Bearer | `app/services/auth_service.py`, `app/api/auth.py`, `app/api/deps.py` | Реализовано; API smoke-тест пройден |
| Хэширование паролей | Argon2id в `app/services/user_service.py` | Реализовано |
| Создание, истечение срока действия и отзыв сессий | PostgreSQL как источник истины, Redis как дополнительный слой с TTL | Реализовано |
| Использование Redis для сессий и кэширования истории | AuthService и MessageService | Реализовано |
| Обработка недоступности Redis | При остановке Redis чтение истории и Bearer-аутентификация продолжили работать через PostgreSQL; `grade5_checks.py --only redis` | Проверено: PASS |
| Ограничение пула соединений PostgreSQL | `app/db/session.py`: `pool_size=5`, `max_overflow=10`, `pool_timeout=30`, `pool_pre_ping=True` | Реализовано |
| Keyset-пагинация истории сообщений | Репозиторий сообщений, сортировка и курсор по `(created_at, id)` | Реализовано |
| Индекс истории сообщений | `ix_messages_chat_created_id`; подтверждён через `EXPLAIN (ANALYZE, BUFFERS)` на 10 009 сообщениях | Проверено: Index Scan |
| Docker Compose и постоянное хранение данных | `compose.yaml`, именованные volumes PostgreSQL и Redis | Проверено |
| Готовность инфраструктуры | `docker compose ps`: API, PostgreSQL и Redis имеют статус `healthy` | PASS |
| Проверка контракта и структуры проекта | `python scripts/check_contract.py` | PASS |
| Проверка OpenAPI 3.1 и JSON Schema | `python scripts/validate_openapi.py` | PASS |
| Проверка публичного API | `python tests/smoke.py --base-url http://127.0.0.1:8080` | PASS |
| Сохранение данных и действующей сессии после перезапуска | `python tests/persistence_windows.py --base-url http://127.0.0.1:8080` | PASS |
| Нагрузочная проверка записи сообщений | `python tests/load.py`: 674 успешных запроса, 0 ошибок, 64,002 запроса/с | PASS |
| Проверка актуальности кэша после записи (read-after-write) | `python tests/cache_research.py`, выполнено до и после перезапуска Redis | PASS |
| Восстановление работы кэша после перезапуска Redis | Перезапуск Redis и повторное чтение истории | PASS |
| Конкурентная регистрация одинакового username | 12 одновременных запросов: 1 успешное создание, 11 конфликтов; в БД осталась ровно 1 запись; `grade5_checks.py` | Проверено: PASS |
| Атомарность создания чата и откат транзакции | Принудительно вызвана ошибка добавления участника; после rollback запись чата не осталась в БД; `grade5_checks.py` | Проверено: PASS |
| Истечение короткой сессии по TTL | При TTL 3 секунды истёкшая сессия была отклонена; `grade5_checks.py` | Проверено: PASS |
| Поведение при недоступности PostgreSQL | При остановке PostgreSQL `/health/ready` вернул 503, защищённый запрос завершился отказом; `grade5_checks.py` | Проверено: PASS |
| Исследовательский трек 1: согласованность кэша | Проверены read-after-write до и после перезапуска Redis, конкурентное заполнение страницы и отсутствие SQL-чтений `messages` в холодной и тёплой группах | Проверено: PASS |
| Исследовательский трек 1: сравнение SQL-запросов и защита от cache stampede | 12 холодных и 12 тёплых параллельных запросов; 0 `SELECT ... FROM messages` в каждой группе; `evidence/grade5-checks.txt` и `evidence/cache-stampede.json` | Проверено: PASS |
### Общий вывод по критериям
Основные функциональные компоненты лабораторной работы реализованы и запущены в Docker Compose. Проверены публичный API, OpenAPI-контракт, сохранение данных PostgreSQL и действующей Bearer-сессии после перезапуска сервисов, использование индекса истории на 10 009 сообщениях, нагрузочная запись сообщений и актуальность данных после записи.
Дополнительно успешно выполнены негативные и конкурентные сценарии: конкурентная регистрация, откат транзакции создания чата, истечение короткой сессии, отказ Redis, отказ PostgreSQL и конкурентные холодные/тёплые чтения кэша. Все шесть сценариев комплексного набора `tests/grade5_checks.py --only all` завершились с результатом PASS. В эксперименте cache stampede зафиксировано 0 SQL-запросов `SELECT ... FROM messages` как для 12 параллельных холодных запросов, так и для 12 параллельных запросов к прогретому кэшу.
Таким образом, функциональность, отказоустойчивое поведение в проверенных сценариях и выбранный исследовательский трек подтверждены воспроизводимыми тестами. Результаты относятся к локальному стенду Docker Compose и не являются гарантией производительности в промышленной среде.
## 6. Доказательства
В каталоге `evidence/` сохранены результаты экспериментов:
- `load-10s.json` — результаты нагрузочного теста записи сообщений.
- `cache-research.json` — результаты исследования чтения истории до и после перезапуска Redis.
- `cache-stampede.json` — результаты отдельного эксперимента конкурентного чтения кэша.
- `grade5-checks.txt` — полный вывод комплексного набора из шести проверок.
- `check-contract.txt` — результат проверки структуры и контракта.
- `openapi-validation.txt` — результат проверки OpenAPI 3.1 и JSON Schema.
- `smoke.txt` — результат проверки публичного API.
- `persistence-windows.txt` — результат проверки сохранения данных и сессии после перезапуска.
Дополнительно выполнены проверки:
- `python scripts/check_contract.py` — PASS.
- `python scripts/validate_openapi.py` — PASS.
- `python tests/smoke.py --base-url http://127.0.0.1:8080` — PASS.
- `python tests/persistence_windows.py --base-url http://127.0.0.1:8080` — PASS.
- `docker compose ps` — все три контейнера healthy.
- `docker compose exec redis redis-cli ping` — PONG.
- `EXPLAIN (ANALYZE, BUFFERS)` — основной запрос истории использует индекс.
- `docker-compose-ps.txt` — состояние контейнеров Docker Compose.
- `grade5-checks.txt` — полный протокол: все шесть проверок завершились с результатом PASS.
Комплексная проверка запускается командой:
```powershell
python tests/grade5_checks.py --base-url http://127.0.0.1:8080 --only all
```
Результат полного запуска сохранён в `evidence/grade5-checks.txt`.
## 7. Ограничения
- Redis — ускоряющий слой, PostgreSQL — долговременный источник истины.
- Локальный Compose стенд не обеспечивает отказоустойчивость при потере самого Docker host.
- Проверка восстановления после рестарта не равнозначна резервному копированию; отдельная процедура backup/restore не входит в выбранный трек.
- Результаты нагрузочного и кэш-экспериментов относятся к локальному стенду, конкретной конфигурации и профилю запросов; их нельзя напрямую переносить на промышленную нагрузку.
- Время холодной и тёплой групп в эксперименте cache stampede не является универсальным показателем ускорения. Основным подтверждённым результатом этого эксперимента является отсутствие SQL-чтений таблицы `messages` в обеих группах.
- Локальный стенд не проверяет отказоустойчивость при потере Docker host и не заменяет резервное копирование и восстановление из backup.
+45 -18
View File
@@ -3,7 +3,9 @@ import secrets
from datetime import datetime, timedelta, timezone
from redis import Redis
from redis.backoff import NoBackoff
from redis.exceptions import RedisError
from redis.retry import Retry
from sqlalchemy.orm import Session
from app.core.config import settings
@@ -26,11 +28,16 @@ class AuthService:
self.db = db
self.sessions = SessionRepository(db)
self.users = UserRepository(db)
self._redis_available = True
self.redis = Redis.from_url(
settings.cache_url,
decode_responses=True,
socket_connect_timeout=2,
socket_timeout=2,
socket_connect_timeout=0.5,
socket_timeout=0.5,
retry_on_timeout=False,
retry=Retry(NoBackoff(), 0),
)
@staticmethod
@@ -72,7 +79,15 @@ class AuthService:
"user": user,
}
def _cache_session(self, token_hash: str, user_id, expires_at) -> None:
def _cache_session(
self,
token_hash: str,
user_id,
expires_at,
) -> None:
if not self._redis_available:
return
ttl = max(
1,
int((expires_at - datetime.now(timezone.utc)).total_seconds()),
@@ -85,24 +100,32 @@ class AuthService:
str(user_id),
)
except RedisError:
pass
self._redis_available = False
def authenticate(self, token: str) -> User:
token_hash = self._hash_token(token)
cached_user_id = None
try:
cached_user_id = self.redis.get(f"session:{token_hash}")
except RedisError:
cached_user_id = None
if self._redis_available:
try:
cached_user_id = self.redis.get(
f"session:{token_hash}"
)
except RedisError:
self._redis_available = False
session = self.sessions.get_valid_session(token_hash)
if session is None:
try:
self.redis.delete(f"session:{token_hash}")
except RedisError:
pass
raise InvalidSessionError("Session is invalid or expired")
if self._redis_available:
try:
self.redis.delete(f"session:{token_hash}")
except RedisError:
self._redis_available = False
raise InvalidSessionError(
"Session is invalid or expired"
)
if cached_user_id is None:
self._cache_session(
@@ -118,15 +141,19 @@ class AuthService:
try:
deleted = self.sessions.delete_by_token_hash(token_hash)
if not deleted:
raise InvalidSessionError("Session is invalid or expired")
raise InvalidSessionError(
"Session is invalid or expired"
)
self.db.commit()
except Exception:
self.db.rollback()
raise
try:
self.redis.delete(f"session:{token_hash}")
except RedisError:
pass
if self._redis_available:
try:
self.redis.delete(f"session:{token_hash}")
except RedisError:
self._redis_available = False
+62 -24
View File
@@ -7,7 +7,9 @@ from datetime import datetime
from types import SimpleNamespace
from redis import Redis
from redis.backoff import NoBackoff
from redis.exceptions import RedisError
from redis.retry import Retry
from sqlalchemy.orm import Session
from app.core.config import settings
@@ -34,11 +36,15 @@ class MessageService:
self.messages = MessageRepository(db)
self.chats = ChatRepository(db)
self._redis_available = True
self.redis = Redis.from_url(
settings.cache_url,
decode_responses=True,
socket_connect_timeout=2,
socket_timeout=2,
socket_connect_timeout=0.5,
socket_timeout=0.5,
retry_on_timeout=False,
retry=Retry(NoBackoff(), 0),
)
@staticmethod
@@ -97,17 +103,24 @@ class MessageService:
)
def _get_version(self, chat_id: uuid.UUID) -> int:
if not self._redis_available:
return 0
try:
value = self.redis.get(self._version_key(chat_id))
return int(value or 0)
except (RedisError, ValueError):
self._redis_available = False
return 0
def _bump_version(self, chat_id: uuid.UUID) -> None:
if not self._redis_available:
return
try:
self.redis.incr(self._version_key(chat_id))
except RedisError:
pass
self._redis_available = False
@staticmethod
def _serialize(messages, next_cursor):
@@ -143,6 +156,9 @@ class MessageService:
return messages, data["next_cursor"]
def _read_cache(self, key: str):
if not self._redis_available:
return None
try:
payload = self.redis.get(key)
@@ -151,7 +167,10 @@ class MessageService:
return self._deserialize(payload)
except (RedisError, ValueError, TypeError, KeyError):
except RedisError:
self._redis_available = False
return None
except (ValueError, TypeError, KeyError):
return None
def _load_from_database(
@@ -179,7 +198,6 @@ class MessageService:
return items, next_cursor
def create_message(
self,
chat_id: uuid.UUID,
@@ -212,7 +230,6 @@ class MessageService:
self.db.rollback()
raise
def get_history(
self,
chat_id: uuid.UUID,
@@ -244,6 +261,14 @@ class MessageService:
if cached is not None:
return cached
if not self._redis_available:
return self._load_from_database(
chat_id,
limit,
cursor_created_at,
cursor_id,
)
lock_key = f"lock:{cache_key}"
lock_token = str(uuid.uuid4())
@@ -255,6 +280,7 @@ class MessageService:
ex=10,
)
except RedisError:
self._redis_available = False
return self._load_from_database(
chat_id,
limit,
@@ -271,6 +297,9 @@ class MessageService:
if cached is not None:
return cached
if not self._redis_available:
break
return self._load_from_database(
chat_id,
limit,
@@ -284,6 +313,14 @@ class MessageService:
if cached is not None:
return cached
if not self._redis_available:
return self._load_from_database(
chat_id,
limit,
cursor_created_at,
cursor_id,
)
items, next_cursor = self._load_from_database(
chat_id,
limit,
@@ -291,7 +328,7 @@ class MessageService:
cursor_id,
)
if self._get_version(chat_id) == version:
if self._redis_available and self._get_version(chat_id) == version:
try:
self.redis.setex(
cache_key,
@@ -299,24 +336,25 @@ class MessageService:
self._serialize(items, next_cursor),
)
except RedisError:
pass
self._redis_available = False
return items, next_cursor
finally:
try:
self.redis.eval(
"""
if redis.call('get', KEYS[1]) == ARGV[1]
then
return redis.call('del', KEYS[1])
else
return 0
end
""",
1,
lock_key,
lock_token,
)
except RedisError:
pass
if self._redis_available:
try:
self.redis.eval(
"""
if redis.call('get', KEYS[1]) == ARGV[1]
then
return redis.call('del', KEYS[1])
else
return 0
end
""",
1,
lock_key,
lock_token,
)
except RedisError:
self._redis_available = False
+11
View File
@@ -0,0 +1,11 @@
{
"experiment": "Redis message history cache",
"cold_read_ms": 52.287,
"warm_reads": 30,
"warm_mean_ms": 26.478,
"warm_median_ms": 29.496,
"warm_min_ms": 13.785,
"warm_max_ms": 46.404,
"read_after_write": "PASS",
"limitations": "HTTP latency includes client, network, authentication and API overhead; it is not a direct SQL query count."
}
+12
View File
@@ -0,0 +1,12 @@
{
"experiment": "concurrent cache miss / stampede",
"workers": 12,
"cold_concurrent_requests": 12,
"warm_concurrent_requests": 12,
"cold_batch_elapsed_ms": 172.0,
"warm_batch_elapsed_ms": 110.0,
"cold_message_select_statements": 0,
"warm_message_select_statements": 0,
"result": "PASS",
"note": "PostgreSQL log_min_duration_statement was temporarily set to 0 and restored after the experiment. Counts are filtered to SELECT statements whose SQL contains FROM messages."
}
Binary file not shown.
Binary file not shown.
Binary file not shown.
+17
View File
@@ -0,0 +1,17 @@
{
"lab": 2,
"workload": "closed-loop POST messages; no automatic retries",
"requested_duration_seconds": 10.0,
"elapsed_seconds": 10.531,
"concurrency": 4,
"successful_requests": 674,
"failed_requests": 0,
"error_ratio": 0.0,
"successful_rps": 64.002,
"successful_latency_ms": {
"p50": 62.0,
"p95": 94.0,
"p99": 110.0
},
"note": "Latency percentiles cover successes only. Timeouts/errors are counted separately; closed-loop has coordinated omission and client overhead."
}
Binary file not shown.
Binary file not shown.
Binary file not shown.
+13
View File
@@ -0,0 +1,13 @@
-- Run with:
-- docker compose exec -T postgres psql -U "$POSTGRES_USER" -d "$POSTGRES_DB" < scripts/explain_history.sql
-- This script selects an existing chat and explains the exact keyset history query.
-- For the required >=10,000-row experiment, seed the chosen chat first, then ANALYZE.
\pset pager off
SELECT count(*) AS total_messages FROM messages;
ANALYZE messages;
EXPLAIN (ANALYZE, BUFFERS)
SELECT id, chat_id, sender_id, text, created_at
FROM messages
WHERE chat_id = (SELECT chat_id FROM messages GROUP BY chat_id ORDER BY count(*) DESC LIMIT 1)
ORDER BY created_at ASC, id ASC
LIMIT 51;
+30
View File
@@ -0,0 +1,30 @@
$ErrorActionPreference = "Stop"
$ProjectRoot = Split-Path -Parent $PSScriptRoot
Push-Location $ProjectRoot
try {
Write-Host "Restarting API, PostgreSQL and Redis without removing volumes..."
docker compose restart api postgres redis
if ($LASTEXITCODE -ne 0) { throw "docker compose restart failed" }
$deadline = (Get-Date).AddSeconds(90)
do {
Start-Sleep -Seconds 2
$ready = $false
try {
$response = Invoke-RestMethod -Uri "http://127.0.0.1:8080/health/ready" -TimeoutSec 3
$ready = ($response.status -eq "ok")
} catch { }
if ($ready) {
$states = docker compose ps --format json | ConvertFrom-Json
$healthy = @($states | Where-Object { $_.Health -eq "healthy" })
if ($healthy.Count -ge 3) {
Write-Host "PASS: API and both stores are healthy. Named volumes were preserved."
exit 0
}
}
} while ((Get-Date) -lt $deadline)
throw "Stack did not become healthy within 90 seconds"
}
finally {
Pop-Location
}
+64
View File
@@ -0,0 +1,64 @@
import json
import statistics
import time
from pathlib import Path
from client import Client, check, run
def main():
client = Client()
alice, _, _, chat = client.bootstrap()
path = f"/api/v1/chats/{chat['id']}/messages?limit=50"
# Первое чтение — холодный кэш.
started = time.perf_counter()
client.call("GET", path, actor=alice, schema="MessagePage")
cold_ms = (time.perf_counter() - started) * 1000
# Повторные чтения — прогретый кэш.
warm = []
for _ in range(30):
started = time.perf_counter()
client.call("GET", path, actor=alice, schema="MessagePage")
warm.append((time.perf_counter() - started) * 1000)
# Проверка актуальности после записи.
marker = "cache-read-after-write-check"
client.message(alice, chat, marker)
updated = client.call(
"GET", path, actor=alice, schema="MessagePage"
)
texts = [item["text"] for item in updated["json"]["items"]]
check(marker in texts, "Read-after-write failed: new message is missing")
result = {
"experiment": "Redis message history cache",
"cold_read_ms": round(cold_ms, 3),
"warm_reads": len(warm),
"warm_mean_ms": round(statistics.mean(warm), 3),
"warm_median_ms": round(statistics.median(warm), 3),
"warm_min_ms": round(min(warm), 3),
"warm_max_ms": round(max(warm), 3),
"read_after_write": "PASS",
"limitations": (
"HTTP latency includes client, network, authentication "
"and API overhead; it is not a direct SQL query count."
),
}
output = Path("evidence/cache-research.json")
output.parent.mkdir(parents=True, exist_ok=True)
output.write_text(
json.dumps(result, indent=2, ensure_ascii=False) + "\n",
encoding="utf-8",
)
print(json.dumps(result, indent=2, ensure_ascii=False))
if __name__ == "__main__":
run(main)
+374
View File
@@ -0,0 +1,374 @@
#!/usr/bin/env python3
"""Grade-5 verification scenarios for Lab 2. Uses only synthetic records."""
from __future__ import annotations
import base64
from datetime import datetime, timezone
import json
import os
import re
import subprocess
import threading
import time
import uuid
from concurrent.futures import ThreadPoolExecutor
from pathlib import Path
from client import Client, Failure, check, run
ROOT = Path(__file__).resolve().parents[1]
def env_file():
result = {}
path = ROOT / ".env"
if path.exists():
for line in path.read_text(encoding="utf-8-sig").splitlines():
line = line.strip()
if not line or line.startswith("#") or "=" not in line:
continue
key, value = line.split("=", 1)
result[key.strip()] = value.strip().strip('"').strip("'")
return result
ENV = env_file()
def docker(*args, input_text=None, check_ok=True, timeout=60):
proc = subprocess.run(
["docker", "compose", *args],
cwd=ROOT,
input=input_text,
text=True,
capture_output=True,
timeout=timeout,
)
if check_ok and proc.returncode:
raise Failure(
"docker compose " + " ".join(args)
+ " failed: " + (proc.stderr or proc.stdout)[-1500:]
)
return proc
def psql(sql: str) -> str:
user = ENV.get("POSTGRES_USER", "messenger")
database = ENV.get("POSTGRES_DB", "messenger")
proc = subprocess.run(
[
"docker", "compose", "exec", "-T", "postgres",
"psql", "-X", "-A", "-t", "-v", "ON_ERROR_STOP=1",
"-U", user, "-d", database,
],
cwd=ROOT,
input=sql,
text=True,
capture_output=True,
timeout=30,
)
if proc.returncode:
raise Failure("PostgreSQL test query failed: " + proc.stderr[-1200:])
return proc.stdout.strip()
def wait_api(base_url: str, timeout: int = 90):
deadline = time.monotonic() + timeout
last = None
while time.monotonic() < deadline:
try:
Client(base_url, timeout=2).call(
"GET", "/health/ready", schema="Health"
)
return
except Exception as exc:
last = exc
time.sleep(1)
raise Failure(f"API did not become ready: {last}")
def wait_redis(timeout: int = 60):
deadline = time.monotonic() + timeout
while time.monotonic() < deadline:
proc = docker("exec", "-T", "redis", "redis-cli", "ping", check_ok=False)
if proc.returncode == 0 and "PONG" in proc.stdout:
return
time.sleep(1)
raise Failure("Redis did not recover")
def registration_race(base_url: str):
client = Client(base_url, timeout=15)
username = "race_" + uuid.uuid4().hex[:16]
password = "Race-" + uuid.uuid4().hex
body = {
"username": username,
"display_name": "Concurrent registration",
"password": password,
}
workers = 12
barrier = threading.Barrier(workers)
def attempt(_):
barrier.wait(timeout=10)
return client.call(
"POST", "/api/v1/users", expected=[201, 409],
body=body, schema="User",
)["status"]
with ThreadPoolExecutor(max_workers=workers) as pool:
statuses = list(pool.map(attempt, range(workers)))
check(statuses.count(201) == 1, f"registration race: expected 1 success, got {statuses.count(201)}")
check(statuses.count(409) == workers - 1, f"registration race: expected {workers-1} conflicts, got {statuses}")
count = psql(
"SELECT count(*) FROM users WHERE username = "
+ "'" + username + "';"
)
check(count == "1", f"registration race left {count} database rows")
print(f"PASS registration race: {workers} concurrent requests, 1 created, {workers-1} conflicts, 1 DB row")
def chat_rollback(base_url: str):
client = Client(base_url)
alice, bob, _, _ = client.bootstrap()
before = int(psql("SELECT count(*) FROM chats;"))
psql("""
CREATE OR REPLACE FUNCTION lab2_test_reject_membership()
RETURNS trigger LANGUAGE plpgsql AS $$
BEGIN
RAISE EXCEPTION 'lab2 injected membership failure';
END;
$$;
DROP TRIGGER IF EXISTS lab2_test_reject_membership_trigger ON chat_members;
CREATE TRIGGER lab2_test_reject_membership_trigger
BEFORE INSERT ON chat_members
FOR EACH ROW EXECUTE FUNCTION lab2_test_reject_membership();
""")
try:
response = client.call(
"POST", "/api/v1/chats", expected=500,
actor=alice,
body={
"title": "Rollback verification",
"member_ids": [alice["id"], bob["id"]],
},
)
check(response["status"] == 500, "injected membership failure did not fail request")
finally:
psql("""
DROP TRIGGER IF EXISTS lab2_test_reject_membership_trigger ON chat_members;
DROP FUNCTION IF EXISTS lab2_test_reject_membership();
""")
after = int(psql("SELECT count(*) FROM chats;"))
check(after == before, f"chat rollback failed: chat count changed {before} -> {after}")
print("PASS chat rollback: injected membership failure left no partial chat")
def short_ttl(base_url: str):
override = ROOT / "compose.ttl-test.yaml"
override.write_text(
'services:\n api:\n environment:\n SESSION_TTL_SECONDS: "3"\n',
encoding="utf-8",
)
try:
docker("-f", "compose.yaml", "-f", "compose.ttl-test.yaml",
"up", "-d", "--force-recreate", "api", timeout=180)
wait_api(base_url)
client = Client(base_url, timeout=10)
actor = client.user("shortttl")
time.sleep(4)
expired = client.call(
"GET", "/api/v1/users/me", expected=401, actor=actor
)
check(expired["status"] == 401, "expired Bearer session was accepted")
print("PASS short TTL: 3-second session was rejected after expiry")
finally:
try:
override.unlink(missing_ok=True)
finally:
docker("up", "-d", "--force-recreate", "api", timeout=180)
wait_api(base_url)
def redis_outage(base_url: str):
client = Client(base_url, timeout=10)
alice, _, _, chat = client.bootstrap()
client.message(alice, chat, "redis-outage-history-check")
docker("stop", "redis")
try:
response = client.call(
"GET",
f"/api/v1/chats/{chat['id']}/messages?limit=50",
actor=alice,
schema="MessagePage",
)
texts = [item["text"] for item in response["json"]["items"]]
check("redis-outage-history-check" in texts, "history unavailable while Redis is down")
client.call("GET", "/api/v1/users/me", actor=alice, schema="User")
print("PASS Redis outage: history and Bearer authentication remained available via PostgreSQL")
finally:
docker("start", "redis")
wait_redis()
wait_api(base_url)
def postgres_outage(base_url: str):
client = Client(base_url, timeout=5)
actor = client.user("dboutage")
docker("stop", "postgres")
try:
health = client.call("GET", "/health/ready", expected=503)
check(health["status"] == 503, "readiness did not report PostgreSQL outage")
protected = client.call(
"GET", "/api/v1/users/me", expected=[500, 503], actor=actor
)
check(
protected["status"] in (500, 503),
"protected request unexpectedly succeeded without PostgreSQL",
)
print("PASS PostgreSQL outage: readiness returned 503 and protected request failed closed")
finally:
docker("start", "postgres")
deadline = time.monotonic() + 90
user = ENV.get("POSTGRES_USER", "messenger")
database = ENV.get("POSTGRES_DB", "messenger")
while time.monotonic() < deadline:
proc = docker(
"exec", "-T", "postgres", "pg_isready",
"-U", user, "-d", database, check_ok=False
)
if proc.returncode == 0:
break
time.sleep(1)
else:
raise Failure("PostgreSQL did not recover within 90 seconds")
wait_api(base_url)
def redis_key_cleanup(chat_id: str):
patterns = [f"messages:{chat_id}:*", f"lock:messages:{chat_id}:*"]
for pattern in patterns:
scan = docker("exec", "-T", "redis", "redis-cli", "--scan", "--pattern", pattern)
keys = [line.strip() for line in scan.stdout.splitlines() if line.strip()]
if keys:
docker("exec", "-T", "redis", "redis-cli", "DEL", *keys)
def cache_stampede(base_url: str):
previous = psql("SHOW log_min_duration_statement;")
psql("ALTER SYSTEM SET log_min_duration_statement = 0; SELECT pg_reload_conf();")
def logged_message_selects(since: str):
logs = subprocess.run(
["docker", "logs", "--since", since, "mtusi-lab2-postgres"],
cwd=ROOT,
text=True,
capture_output=True,
timeout=30,
)
lines = (logs.stdout + "\n" + logs.stderr).splitlines()
return [
line for line in lines
if re.search(r"statement:\s*SELECT", line, re.I)
and re.search(r"\bFROM\s+messages\b", line, re.I)
]
try:
client = Client(base_url, timeout=15)
alice, _, _, chat = client.bootstrap()
for i in range(5):
client.message(alice, chat, f"stampede-seed-{i}")
path = f"/api/v1/chats/{chat['id']}/messages?limit=50"
redis_key_cleanup(chat["id"])
workers = 12
barrier = threading.Barrier(workers)
def get_history(_):
barrier.wait(timeout=10)
return client.call("GET", path, actor=alice, schema="MessagePage")
cold_since = datetime.now(timezone.utc).isoformat(timespec="milliseconds")
started = time.monotonic()
with ThreadPoolExecutor(max_workers=workers) as pool:
cold_results = list(pool.map(get_history, range(workers)))
cold_elapsed = (time.monotonic() - started) * 1000
check(all(r["status"] == 200 for r in cold_results), "cold concurrent history request failed")
cold_selects = logged_message_selects(cold_since)
warm_since = datetime.now(timezone.utc).isoformat(timespec="milliseconds")
started = time.monotonic()
with ThreadPoolExecutor(max_workers=workers) as pool:
warm_results = list(pool.map(get_history, range(workers)))
warm_elapsed = (time.monotonic() - started) * 1000
check(all(r["status"] == 200 for r in warm_results), "warm concurrent history request failed")
warm_selects = logged_message_selects(warm_since)
check(
len(cold_selects) <= 2,
f"cache stampede protection ineffective: {len(cold_selects)} message SELECTs for {workers} simultaneous misses",
)
check(
len(warm_selects) == 0,
f"warm cache unexpectedly issued {len(warm_selects)} message SELECTs",
)
result = {
"experiment": "concurrent cache miss / stampede",
"workers": workers,
"cold_concurrent_requests": len(cold_results),
"warm_concurrent_requests": len(warm_results),
"cold_batch_elapsed_ms": round(cold_elapsed, 3),
"warm_batch_elapsed_ms": round(warm_elapsed, 3),
"cold_message_select_statements": len(cold_selects),
"warm_message_select_statements": len(warm_selects),
"result": "PASS",
"note": "PostgreSQL log_min_duration_statement was temporarily set to 0 and restored after the experiment. Counts are filtered to SELECT statements whose SQL contains FROM messages.",
}
out = ROOT / "evidence" / "cache-stampede.json"
out.parent.mkdir(exist_ok=True)
out.write_text(json.dumps(result, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
(ROOT / "evidence" / "cache-stampede-cold.log").write_text(
"\n".join(cold_selects) + "\n", encoding="utf-8"
)
(ROOT / "evidence" / "cache-stampede-warm.log").write_text(
"\n".join(warm_selects) + "\n", encoding="utf-8"
)
print(json.dumps(result, indent=2, ensure_ascii=False))
print("PASS cache stampede: concurrent cold misses collapsed; warm cache issued no message SELECT")
finally:
psql("ALTER SYSTEM SET log_min_duration_statement = " + previous + "; SELECT pg_reload_conf();")
def main():
def configure(parser):
parser.add_argument("--base-url", default="http://127.0.0.1:8080")
parser.add_argument(
"--only",
choices=["all", "registration", "rollback", "ttl", "redis", "postgres", "stampede"],
default="all",
)
import argparse
parser = argparse.ArgumentParser(description="Run Lab 2 grade-5 verification scenarios")
configure(parser)
args = parser.parse_args()
if args.only in ("all", "registration"):
registration_race(args.base_url)
if args.only in ("all", "rollback"):
chat_rollback(args.base_url)
if args.only in ("all", "ttl"):
short_ttl(args.base_url)
if args.only in ("all", "redis"):
redis_outage(args.base_url)
if args.only in ("all", "postgres"):
postgres_outage(args.base_url)
if args.only in ("all", "stampede"):
cache_stampede(args.base_url)
if __name__ == "__main__":
run(main)
+47
View File
@@ -0,0 +1,47 @@
"""Windows-compatible persistence acceptance test for Docker Compose."""
import subprocess
import sys
import time
from pathlib import Path
from client import Client, arguments, check, run
ROOT = Path(__file__).resolve().parents[1]
def main():
args = arguments("Windows-compatible PostgreSQL/session persistence scenario")
c = Client(args.base_url, args.ca_file, timeout=5)
alice, bob, eve, chat = c.bootstrap()
original = c.message(alice, chat, "Проверка сохранности после рестарта")["json"]
token = alice["token"]
hook = ROOT / "scripts" / "restart.ps1"
check(hook.is_file(), "scripts/restart.ps1 is missing")
result = subprocess.run(
["powershell.exe", "-NoProfile", "-ExecutionPolicy", "Bypass", "-File", str(hook)],
cwd=str(ROOT), timeout=110, capture_output=True, text=True
)
if result.returncode:
print(result.stdout)
print(result.stderr, file=sys.stderr)
check(False, "PowerShell restart hook failed")
deadline = time.monotonic() + 90
while True:
try:
c.call("GET", "/health/ready", schema="Health")
break
except Exception:
check(time.monotonic() < deadline, "API did not recover")
time.sleep(1)
same_actor = {"id": alice["id"], "token": token}
me = c.call("GET", "/api/v1/users/me", actor=same_actor, schema="User")["json"]
check(me["id"] == alice["id"], "existing session did not survive restart")
history = c.call("GET", "/api/v1/chats/" + chat["id"] + "/messages?limit=100",
actor={"id": bob["id"], "token": bob["token"]},
schema="MessagePage")["json"]
check(original in history["items"], "confirmed message did not survive restart")
print("PASS: PostgreSQL data and existing Bearer session survived API + PostgreSQL + Redis restart.")
if __name__ == "__main__":
run(main)