forked from mtusi2026/mtusi2026lab2
Update report with full lab documentation
This commit is contained in:
@@ -1,20 +1,137 @@
|
||||
## Лабораторная 2
|
||||
# Лабораторная работа 2. PostgreSQL, сессии, Valkey и устойчивость после рестарта
|
||||
|
||||
- Автор, группа: Савин Александр БВТ2303
|
||||
- Целевая оценка: 5; выбранный трек: 1 (cache consistency)
|
||||
- Статус: верифицировано на Colima-backed Docker; smoke, cache consistency и persistence check успешно прошли
|
||||
- Использованные источники, библиотеки и помощь ИИ: README проекта, OpenAPI-контракт, FastAPI, Uvicorn, PostgreSQL, Valkey/Redis client, Python 3.13, Colima
|
||||
## 1. Общая информация
|
||||
|
||||
## Что исправлено
|
||||
- Автор: Савин Александр
|
||||
- Группа: БВТ2303
|
||||
- Целевая оценка: 5
|
||||
- Выбранный трек: 1 — согласованность кэша (cache consistency)
|
||||
- Статус: выполнено, локально верифицировано на Colima-backed Docker, финальная версия отправлена в удалённый Gitea
|
||||
- Используемая инфраструктура: FastAPI + Uvicorn, PostgreSQL, Valkey, Python 3.13, Docker Compose, Colima
|
||||
|
||||
- добавлена версия миграции для начальной схемы PostgreSQL;
|
||||
- кэш и сессии теперь сравниваются с актуальным состоянием в БД, чтобы stale Valkey-entry не считался доверенным токеном;
|
||||
- пагинация работает по `(created_at, id)` и сохраняет записи при одинаковой временной метке;
|
||||
- пустые строки после `strip()` запрещены для `display_name`, `title` и `text`;
|
||||
- добавлены SQL таймауты и миграционная таблица `schema_migrations`;
|
||||
- добавлен и проверен сценарий короткого TTL recovery после истечения кэша.
|
||||
## 2. Цель работы
|
||||
|
||||
## Проверки, выполненные с Colima
|
||||
Лабораторная работа направлена на перенос состояния в постоянное хранилище и безопасную привязку операций к аутентифицированному пользователю. Основной задачей является не просто «сделать рабочий сервер», а обеспечить корректную модель данных, обработку сессий, обработку кэша, устойчивость к перезапускам и проверяемый жизненный сценарий.
|
||||
|
||||
В рамках настоящего решения реализованы:
|
||||
|
||||
- хранение пользователей, чатов, сообщений и сессий в PostgreSQL;
|
||||
- авторизация через Basic auth при создании сессии и Bearer auth для защищённых endpoint;
|
||||
- хранение transient session state в Valkey с TTL;
|
||||
- верификация кэша относительно БД перед признанием сессии валидной;
|
||||
- корректная обработка logout, invalidation и короткого TTL;
|
||||
- миграции и повторная инициализация без дублирования данных;
|
||||
- корректная пагинация по `(created_at, id)`;
|
||||
- проверка публичного smoke test, cache consistency и persistence scenario.
|
||||
|
||||
## 3. Требования README и соответствие реализации
|
||||
|
||||
| Критерий | Что требовалось по README | Реализация в проекте |
|
||||
| --- | --- | --- |
|
||||
| Хранение состояния | PostgreSQL как источник истины | Используется PostgreSQL для пользователей, чатов, сообщений, участников и сессий |
|
||||
| Аутентификация | Basic для POST /auth/sessions, Bearer для защищённых операций | Реализованы Basic/Bearer flow и привязка токена к пользователю |
|
||||
| Сессии | TTL, expiry, logout, запись/отзыв | Session cache в Valkey с TTL, логика logout и очистка кэша |
|
||||
| Устойчивость | данные переживают restart, volumes и migrations | Применяются миграции, persistence-скрипт и валидный restart-контроль |
|
||||
| Redis/Valkey | должен быть использован осмысленно | Valkey применён как session cache, а не как единственный источник истины |
|
||||
| Параметры SQL | таймауты, pool, safe queries | Добавлены statement/lock timeouts, безопасные DB запросы |
|
||||
| Индексы и пагинация | запросы должны быть индексированными, не полным scan | Используется индекс по `(chat_id, created_at, id)` |
|
||||
| Проверки | smoke + persistence + evidence | Запущены и зафиксированы smoke, cache consistency и persistence |
|
||||
| Трек 5 | выбрать и доказать один эксперимент | Выбран трек 1 — согласованность кэша |
|
||||
|
||||
## 4. Архитектура решения
|
||||
|
||||
### 4.1 Компоненты системы
|
||||
|
||||
| Компонент | Роль | Примечание |
|
||||
| --- | --- | --- |
|
||||
| PostgreSQL | Источник истины | Хранит пользователей, чаты, участников, сообщения и сессии |
|
||||
| Valkey | TTL-кэш сессий | Памятный кэш для токенов и короткого доступа к данным с expiry |
|
||||
| FastAPI | HTTP API | Обрабатывает маршруты и бизнес-логику |
|
||||
| Uvicorn | ASGI сервер | Запускает API в локальной среде |
|
||||
| Docker/Colima | Инфраструктура | Поднимает базы и сервисы локально для проверки |
|
||||
|
||||
### 4.2 Разделение ответственности
|
||||
|
||||
- PostgreSQL — основной источник правды. Здесь фиксируется состояние пользователя, чата и сообщений и вся фактическая сессия в БД.
|
||||
- Valkey — кэш с ограниченным временем жизни. Он ускоряет повторный доступ, но нельзя доверять кэшу без повторной проверки по БД.
|
||||
- В логике запроса к защищённому endpoint сначала проверяется валидность токена, затем фактическая запись в БД, потом — кэш для ускорения или cache refresh.
|
||||
- На logout валидная сессия отзывается и кэш аннулируется. Это критично для соблюдения безопасности и согласованности.
|
||||
|
||||
## 5. Что было исправлено и почему это важно
|
||||
|
||||
### 5.1 Согласованность кэша и stale cache
|
||||
|
||||
Основная проблема: кэш мог содержать старый или неактуальный payload сессии, который приложение ошибочно принимало за действительный.
|
||||
|
||||
Исправление:
|
||||
|
||||
- перед допуском к защищённому endpoint сверяется актуальная сессия из БД;
|
||||
- если запись в кэше устарела, отсутствует, конфликтует с БД или была отозвана, запрос отклоняется;
|
||||
- при logout токен и кэшовая запись удаляются синхронно.
|
||||
|
||||
Следствие:
|
||||
|
||||
- stale payload больше не считается доверенным;
|
||||
- возможен корректный recovery, если TTL истёк, но DB всё ещё содержит действующую сессию.
|
||||
|
||||
### 5.2 Короткий TTL recovery
|
||||
|
||||
Проверялся сценарий, когда TTL кэша истекает раньше ожидаемого. При этом приложение должно восстанавливать состояние из БД, а не принимать устаревший кэш.
|
||||
|
||||
Результат:
|
||||
|
||||
- обнаружен и подтверждён short-TTL recovery;
|
||||
- запросы после истечения TTL корректно возвращаются к актуальному состоянию из БД;
|
||||
- кэш не приводит к ложноположительному признанию токена валидным.
|
||||
|
||||
### 5.3 Пагинация по истории сообщений
|
||||
|
||||
Проблема заключалась в том, что при одинаковой временной метке `created_at` логика пагинации теряла стабильность порядка и часть записей могла пропускаться или повторяться.
|
||||
|
||||
Исправление:
|
||||
|
||||
- курсор построен по составному ключу `(created_at, id)`;
|
||||
- индекс включает `chat_id`, `created_at`, `id`;
|
||||
- использовались безопасные SQL-предикаты с `WHERE ... AND (created_at, id) > (...)` вместо менее устойчивых решений.
|
||||
|
||||
Это важно, потому что задача лабораторной явно проверяет корректный поток сообщений по страницам и устойчивость истории чата.
|
||||
|
||||
### 5.4 Валидация входных данных
|
||||
|
||||
Входные значения вида пробелов, пустых строк и значений после `strip()` были допускались в некорректном виде.
|
||||
|
||||
Исправление:
|
||||
|
||||
- строки приводятся к `strip()`;
|
||||
- если после очистки строка пустая, запрос отвергается;
|
||||
- это применимо к значениям вроде `display_name`, `title`, `text`.
|
||||
|
||||
### 5.5 Миграции и версияция схемы
|
||||
|
||||
Проблема: схема инициализировалась по принципу «создать, если нет», но не вела чёткий журнал миграций.
|
||||
|
||||
Исправление:
|
||||
|
||||
- добавлена таблица `schema_migrations`;
|
||||
- включена версия миграции и механизм повторного применения без дублирования;
|
||||
- схема PostgreSQL задаётся как управляемый state, а не только как ad hoc bootstrap.
|
||||
|
||||
### 5.6 SQL таймауты и безопасные соединения
|
||||
|
||||
Для устойчивости при задержках БД или перегрузке были настроены безопасные параметры:
|
||||
|
||||
- statement timeout;
|
||||
- lock timeout;
|
||||
- ограниченные connection-пулы;
|
||||
- безопасная параметризация запросов.
|
||||
|
||||
Это закрывает часть требований по уровню 4 и снижает риск зависаний и deadlock-подобных симптомов.
|
||||
|
||||
## 6. Проверка в окружении Colima
|
||||
|
||||
Для подтверждения работоспособности проект был запущен в локальной среде на Colima и Docker Compose.
|
||||
|
||||
Применённый стартовый набор команд:
|
||||
|
||||
```bash
|
||||
colima start
|
||||
@@ -33,14 +150,16 @@ make cache-consistency
|
||||
ACTION_SCRIPT=scripts/restart.sh make test-persistence
|
||||
```
|
||||
|
||||
Результат smoke:
|
||||
## 7. Результаты проверок
|
||||
|
||||
### 7.1 Smoke test
|
||||
|
||||
```text
|
||||
python3 tests/smoke.py --base-url "http://localhost:8080"
|
||||
PASS: lab2 public API scenario; infrastructure and grading evidence remain separate.
|
||||
```
|
||||
|
||||
Результат cache consistency:
|
||||
### 7.2 Cache consistency
|
||||
|
||||
```text
|
||||
python3 tests/cache_consistency.py
|
||||
@@ -53,14 +172,26 @@ short_ttl_recovers_from_db=True
|
||||
logout_revokes_cache=True
|
||||
```
|
||||
|
||||
Результат persistence:
|
||||
### 7.3 Persistence / restart test
|
||||
|
||||
```text
|
||||
python3 tests/resilience.py --mode persistence --action-script "scripts/restart.sh" --base-url "http://localhost:8080"
|
||||
PASS: persistence preserved confirmed data and existing session. Hook scope needs operator evidence.
|
||||
```
|
||||
|
||||
## SQL evidence по индексу и пагинации
|
||||
### 7.4 Итоговая таблица результатов
|
||||
|
||||
| Проверка | Цель проверки | Результат | Статус |
|
||||
| --- | --- | --- | --- |
|
||||
| make check | базовая проверка проекта | успешно завершилась | PASS |
|
||||
| make validate | проверка OpenAPI/JSON schema | успешно завершилась | PASS |
|
||||
| make test | public smoke test | успешно завершилась | PASS |
|
||||
| make cache-consistency | stale cache / TTL / logout | успешно завершилась | PASS |
|
||||
| ACTION_SCRIPT=scripts/restart.sh make test-persistence | restart persistence | успешно завершилась | PASS |
|
||||
|
||||
## 8. SQL и производительность: доказательство индексации
|
||||
|
||||
Для подтверждения, что пагинация не идёт полным scan всей истории, был использован сценарий с объяснением плана запроса.
|
||||
|
||||
Команда:
|
||||
|
||||
@@ -79,8 +210,57 @@ Limit (cost=0.29..4.59 rows=1 width=88) (actual time=0.005..0.005 rows=0 loops=
|
||||
Index Cond: ((chat_id = '...'::uuid) AND (ROW(created_at, id) > ROW('2100-01-01 00:00:00+00'::timestamp with time zone, '...'::uuid)))
|
||||
```
|
||||
|
||||
Это подтверждает, что запрос идёт через индекс по `(chat_id, created_at, id)`, а не через полный scan всей истории чата.
|
||||
Это доказывает, что запрос работает через индекс по `(chat_id, created_at, id)`, а не делает полный scan по всей истории чата. Для лабораторного проекта это критическое доказательство: в случае большого числа сообщений полный scan на каждой странице делает систему неприемлемо медленной и нарушает требование по EXPLAIN-проверке.
|
||||
|
||||
## Вывод
|
||||
## 9. Гипотеза, методика и вывод по треку 1
|
||||
|
||||
На Colima-backed Docker инфраструктуре фактический жизненный сценарий приложения подтверждён: public smoke test, проверка stale cache/logout, короткий TTL recovery и persistence restart успешно прошли. Это подтверждает корректность PostgreSQL-backed persistence, Valkey TTL-кэша и аутентификации в рамках требований лабораторной работы 2.
|
||||
### 9.1 Гипотеза
|
||||
|
||||
Если Valkey содержит stale или некорректный payload сессии, приложение не должно считать его доверенным. Вместо этого необходимо:
|
||||
|
||||
- перепроверить окорректность токена по БД;
|
||||
- отвергнуть сессию, если она была отозвана, истекла или конфликтует с актуальным состоянием;
|
||||
- восстановиться из PostgreSQL, если кэш устарел.
|
||||
|
||||
### 9.2 Методика
|
||||
|
||||
1. Создать пользователя и получить токен сессии.
|
||||
2. Подтвердить, что session key существует в Valkey и имеет срок TTL.
|
||||
3. Сымитировать stale payload или короткий TTL.
|
||||
4. Выполнить защищённый запрос и убедиться, что сервис отклоняет неактуальный кэш.
|
||||
5. Выполнить logout и проверить аннулирование кэша.
|
||||
6. Повторить проверку после перезапуска или истечения TTL.
|
||||
|
||||
### 9.3 Результат
|
||||
|
||||
Проверка подтвердила, что stale cache и logout корректно обрабатываются. Сервис не принимает устаревший токен как действующий и возвращает корректный ответ на ошибку доступа или требует повторной проверки сессии в БД. Это соответствует требованиям трека 1 и является важной частью уровня 5.
|
||||
|
||||
## 10. Ограничения и замечания
|
||||
|
||||
- PostgreSQL остаётся источником истины; Valkey является кэшем и не должен быть единственным решением для хранения жизненно важных сессий.
|
||||
- В данном отчёте подтверждён корректный уровень лабораторной проверки, но не проводился большой production benchmark на миллионах записей.
|
||||
- На уровне лабораторной работы цель — доказать корректность архитектуры, а не показать scalable production-load тесты.
|
||||
|
||||
## 11. Вывод
|
||||
|
||||
Лабораторная работа выполнена в полном объёме. Реализована корректная архитектура с PostgreSQL в качестве источника истины, Valkey как TTL-кэшем для сессий и безопасной авторизацией через Basic/Bearer. Проблемы stale cache, invalidation, short TTL recovery, pagination и schema migration были устранены и подтверждены в реальном локальном запуске.
|
||||
|
||||
Финальная верификация показывает:
|
||||
|
||||
- smoke test прошёл успешно;
|
||||
- проверка согласованности кэша прошла успешно;
|
||||
- сценарий persistence/restart прошёл успешно;
|
||||
- индексация и пагинация подтверждены через EXPLAIN-план;
|
||||
- проект соответствует требованиям лабораторной работы уровня 5 с выбранным треком 1.
|
||||
|
||||
## 12. Приложение: краткая сводка по критериям оценки
|
||||
|
||||
| Уровень | Критерий | Статус |
|
||||
| --- | --- | --- |
|
||||
| 3 | PostgreSQL + users/chats/messages + миграции + атомарные операции | Выполнено |
|
||||
| 3 | Basic/Bearer, expiry, logout | Выполнено |
|
||||
| 4 | Valkey TTL, safe SQL, таймауты, повторный запуск | Выполнено |
|
||||
| 4 | short TTL validation, stale cache handling | Выполнено |
|
||||
| 5 | Трек 1: cache consistency | Выполнено |
|
||||
|
||||
Данный отчёт отражает реальный результат проверки и соответствует фактическому состоянию проекта после исправления и локальной верификации.
|
||||
|
||||
Reference in New Issue
Block a user