41 KiB
Отчёт — лабораторная 2
- Автор, группа: BVT2304 Shiyan
- Целевая оценка; выбранный трек 5: 5; Трек 1 — согласованность кэша истории (stale read + cache stampede)
- Commit/PR: solution/BVT2304-Shiyan (обновляется по мере PR)
- Использованные источники, библиотеки и помощь ИИ:
- Язык и runtime: Go 1.22, только стандартная библиотека
net/http(без стороннего web-фреймворка) github.com/google/uuid v1.6.0(MIT) — генерация UUIDgithub.com/jackc/pgx/v5 v5.5.5(MIT) — драйвер PostgreSQL с пулом соединенийgithub.com/redis/go-redis/v9 v9.5.1(BSD-2) — Redis-клиентgolang.org/x/crypto v0.23.0(BSD-3) —scryptдля KDF паролей- Образы:
postgres:16-alpine,redis:7-alpine(зафиксированы вcompose.yaml) - Помощь ИИ: консультации при проектировании схемы БД, транзакционных границ, политики инвалидации кэша и single-flight защиты. Весь код написан и проверен вручную; публичные
tests/иcontracts/не изменялись.
- Язык и runtime: Go 1.22, только стандартная библиотека
Запуск из чистого clone
Prerequisites и версии
| Компонент | Версия | Назначение |
|---|---|---|
| Docker Desktop + Compose | v2 | запуск стенда (единственный обязательный способ) |
| Go | 1.22+ | только для локальной разработки; в контейнере не требуется |
| Python | 3.9+ | публичные и студенческие тесты (только стандартная библиотека) |
| GNU Make | любой | make check / make test (Windows — WSL или choco install make) |
| postgres | 16-alpine | источник истины |
| redis | 7-alpine | кэш сессий и истории |
Локальные secrets / .env
Секреты создаются локально и в Git не коммитятся — в репозитории лежит только .env.example; .env добавлен в .gitignore. Значения в отчёте не приводятся как секрет (учебный стенд, значения совпадают с .env.example).
cp .env.example .env
# Отредактируйте .env — значения должны совпадать с .env.example:
# APP_HOST=0.0.0.0
# APP_PORT=8080
# APP_ENV=lab
# SESSION_TTL_SECONDS=3600
# SESSION_STORE=redis
# CACHE_MODE=versioned
# DATABASE_URL=postgres://messenger:messenger_password@postgres:5432/messenger?sslmode=disable
# REDIS_URL=redis://redis:6379/0
Build и запуск
docker compose --env-file .env up -d --build
Поднимаются три сервиса:
| Сервис | Образ / сборка | Роль | Volume |
|---|---|---|---|
mtusi-postgres |
postgres:16-alpine |
источник истины | mtusi_postgres_data |
mtusi-redis |
redis:7-alpine |
кэш сессий и истории | mtusi_redis_data |
mtusi-api |
локальный Dockerfile (multi-stage, non-root) | stateless API, ждёт готовности БД и Redis | — |
Миграции
Запускаются автоматически при старте API (store.RunMigrations в main.go), отдельная команда оператора не нужна:
- встроены в бинарник через
//go:embed migrations/*.sql; - идемпотентны за счёт
IF NOT EXISTS— повторный запуск не дублирует таблицы; - единственная миграция
0001_init.sqlсоздаётusers,chats,chat_members,messages,sessionsсо всеми PK/FK/индексами.
Ожидание готовности
docker compose ps # все три сервиса должны стать healthy
curl http://localhost:8080/health/ready # 200 {"status":"ok"}
Тесты
# 1. Офлайн-проверка структуры контракта
make check
# 2. Публичный smoke против работающего стенда
make test
# 3. Persistence-сценарий: рестарт API + Postgres + Redis с сохранением volumes
make test-persistence ACTION_SCRIPT=scripts/restart.bat
# 4. Студенческие проверки уровня 4
python student-tests/run_tests.py --base-url http://localhost:8080
python student-tests/failover_tests.py --base-url http://localhost:8080
scripts\expiry.bat
# 5. Трек 5: эксперименты кэша (off → naive → versioned → recovery)
scripts\cache_demo.bat
# 6. EXPLAIN-доказательство индекса (≥10k сообщений)
scripts\explain_demo.bat
Действия оператора (что нельзя автоматизировать)
| Шаг | Действие оператора |
|---|---|
| 1 | Создать .env из .env.example (значения — как в примере) |
| 2 | Поднять стенд и дождаться healthy у всех трёх сервисов |
| 3 | Запустить make check, затем make test |
| 4 | Для persistence-сценария подтвердить, какие именно процессы/хранилища перезапущены: scripts/restart.bat выполняет docker compose restart postgres redis api, то есть перезапускаются контейнер API, контейнер Postgres и контейнер Redis; volumes mtusi_postgres_data и mtusi_redis_data не удаляются |
| 5 | Для failover-проверок вручную останавливать/запускать redis и postgres (docker compose stop / docker compose start) и фиксировать время восстановления |
| 6 | Для expiry-теста временно выставить SESSION_TTL_SECONDS=2, пересоздать контейнер API, вернуть 3600 |
| 7 | Сохранить terminal output как доказательство (строки RESULT ..., [PASS] ...) |
Безопасная остановка
docker compose down # останавливает контейнеры; volumes сохраняются
Намеренное удаление учебных данных
docker compose down -v # удаляет контейнеры И volumes (данные теряются безвозвратно)
Архитектура и решения
Схема процессов и хранилищ
Клиент ──HTTP──► API (Go, stateless, PID 1 в контейнере)
│
├──► PostgreSQL 16 (источник истины)
│ volume: mtusi_postgres_data
│ таблицы: users, chats, chat_members, messages, sessions
│
└──► Redis 7 (кэш сессий + истории)
volume: mtusi_redis_data
роль: ускорение hot path "токен → пользователь"
и чтение истории (с инвалидацией версией)
Источник истины
- PostgreSQL — источник истины для всего: пользователи, чаты, участники, сообщения и сессии.
- Redis — опциональный кэш: при его недоступности API деградирует в postgres-only режим (
log.Warn), а не отказывает. - Такое разделение закрывает требование уровня 3 «ещё действительные сессии переживают перезапуск» конструктивно: Postgres volume сохраняется между рестартами, отдельная настройка persistence в Redis не требуется.
Транзакционные границы
| Операция | Транзакция | Гарантии |
|---|---|---|
CreateUser |
один INSERT | гонка двух одинаковых username → SQLSTATE 23505 (unique violation) → детерминированно маппится в 409 Conflict |
UserByCredentials |
один SELECT | неизвестный user и неверный пароль дают один и тот же ErrInvalidLogin → наружу 401 без раскрытия существования учётки |
CreateSession |
SELECT + INSERT | expires_at = now() + TTL; TTL не продлевается рестартом |
CreateChat |
составная транзакция: проверка всех member_ids → INSERT chats → INSERT chat_members → COMMIT |
любая ошибка → ROLLBACK: «получата» в БД не бывает |
CreateMessage |
транзакция: проверка членства → INSERT | после COMMIT сообщение видимо следующему чтению (read-after-write); в режиме versioned — bumpChatVersion инвалидирует кэш истории |
ListMessages |
одиночный SELECT, keyset | (created_at, id) > (курсор) LIMIT n+1 использует композитный индекс messages_history_idx (доказательство — scripts/explain_plans.md) |
Ограничения
- TTL сессии не продлевается при рестарте:
expires_atфиксируется в момент создания. - Миграции идемпотентны (
IF NOT EXISTS), но без таблицы версий; для эксплуатации нужен миграционный фреймворк. - Redis-кэш: TTL ключа сессии = остаток TTL сессии; при logout и expiry ключ инвалидируется.
X-User-Idигнорируется начиная с lab2 (требование README); аутентификация только через Bearer.- Healthcheck контейнера стучит в
/health/live;/health/readyвозвращает 503 при недоступности Postgres (весь обязательный путь зависит от БД). - TTL кэша истории = 60 с; single-flight действует внутри одного процесса API.
Что перенесено из lab1
- Структура API-слоя:
router.go,handlers.go,middleware.go,helpers.go,apperr/. - Graceful shutdown, healthcheck, таймауты, middleware-цепочка (requestID → logging → recover → mux).
- Dockerfile (multi-stage, non-root, healthcheck на live).
Timestampс детерминированной JSON-сериализацией (ровно 3 знака миллисекунд).Page[T]— дженерик-страница, курсоры base64url соScope.- Конверт ошибок
apperr.Write.
Что изменено в lab2
- In-memory
Storeзаменён на PostgreSQL-репозиторий (store/postgres.go) + Redis-кэш (store/cache.go). - Аутентификация:
X-User-Id→ Bearer; Basic только наPOST /auth/sessions(отдельный middlewarebasicOnly). - Регистрация принимает
password(хеш через scrypt, форматscrypt$N$r$p$salt$hash). - Добавлены миграции (embed в бинарник, запуск в
main.goдо старта сервера). - Добавлены handlers
createSession,revokeSession(logout → 204). /health/readyпингует БД: недоступность → 503.- Добавлен режим
CACHE_MODE(off / naive / versioned) для исследования кэша (трек 5).
Соответствие переменных .env.example реальной конфигурации
| Переменная | Роль | Дефолт в .env.example |
Реальное значение в .env |
|---|---|---|---|
APP_HOST |
bind-адрес | 0.0.0.0 |
0.0.0.0 |
APP_PORT |
порт API | 8080 |
8080 |
APP_ENV |
окружение | lab |
lab |
SESSION_TTL_SECONDS |
срок жизни сессии | 3600 |
3600 (≥300 для smoke; 2 — только в expiry-тесте) |
SESSION_STORE |
postgres или redis |
postgres |
redis |
CACHE_MODE |
режим кэша истории | versioned |
versioned (off / naive — только в экспериментах) |
DATABASE_URL |
строка подключения Postgres | — | postgres://messenger:messenger_password@postgres:5432/messenger?sslmode=disable |
REDIS_URL |
строка подключения Redis | — | redis://redis:6379/0 |
Доказательства критериев
Каждая строка = отдельный заявленный критерий: указана команда/сценарий и наблюдаемый результат (PASS без команды и наблюдения доказательством не считается).
| Критерий README | Команда / сценарий | Наблюдаемый результат | Файл доказательства |
|---|---|---|---|
| Уровень 3. Публичный smoke | make test |
PASS: lab2 public API scenario; infrastructure and grading evidence remain separate. |
terminal output |
| Уровень 3. Минимум lab1 сохранён с новой аутентификацией | make test |
smoke проходит health → users → createSession (Basic) → chats → messages → пагинация → logout | terminal output |
| Уровень 3. Данные и сессии переживают рестарт без удаления volumes | make test-persistence ACTION_SCRIPT=scripts/restart.bat |
PASS: persistence preserved confirmed data and existing session. Hook scope needs operator evidence. |
terminal output + ручные доказательства ниже |
| Уровень 3. Подтверждение hook: какие процессы/хранилища перезапущены | scripts/restart.bat → docker compose restart postgres redis api |
перезапущены контейнеры API, Postgres и Redis; volumes mtusi_postgres_data и mtusi_redis_data не удалены и существуют после рестарта (docker volume ls) |
terminal output + docker compose ps |
| Уровень 3. PostgreSQL содержит пользователей, чаты, участников, сообщения | docker compose exec postgres psql ... |
5 таблиц существуют и содержат данные: users / sessions / messages | terminal output |
| Уровень 3. PK / FK / unique username | 0001_init.sql |
PK на users.id, chats.id, messages.(chat_id, id); FK с ON DELETE CASCADE на chat_members, sessions, messages; UNIQUE INDEX users_username_key |
src/internal/store/migrations/0001_init.sql |
| Уровень 3. Миграции выполняются с нуля | docker compose up --build (первый запуск) |
running migration 0001_init.sql в логах API |
docker compose logs api |
| Уровень 3. Миграции перезапускаются без дублирования данных | docker compose restart api → логи |
та же строка running migration, но IF NOT EXISTS не создаёт дублей |
docker compose logs api |
| Уровень 3. Составная операция создания чата атомарна | run_tests.py: chat with unknown member -> 400, rollback: no partial chat |
PASS: чат не создан, выполнен ROLLBACK | terminal output |
Уровень 3. make test и make test-persistence проходят |
команды выше | оба PASS | terminal output |
| Уровень 3. Секреты и volumes не в Git | git status, .gitignore |
.env отсутствует среди tracked-файлов |
terminal output |
| Уровень 4. Redis реально используется для сессий с TTL | SESSION_STORE=redis + docker compose exec redis redis-cli INFO keyspace |
ключи sess:* существуют; TTL согласован с expires_at в Postgres |
terminal output |
| Уровень 4. Параметризованные запросы | grep по store/*.go |
все SQL используют $1, $2, ... через pgx; конкатенации строк нет |
src/internal/store/postgres.go |
| Уровень 4. Ограниченный пул и таймауты | чтение main.go |
MaxConns=10, ConnectTimeout=5s, statement_timeout=15000, HealthCheckPeriod=10s |
src/cmd/server/main.go |
| Уровень 4. Гонка регистрации | run_tests.py: race registration: one 201, rest 409 |
UNIQUE-ограничение детерминированно разрешает гонку: 1×201 + 9×409 | terminal output |
| Уровень 4. Откат составной операции | run_tests.py: rollback: no partial chat |
частичный чат невозможен | terminal output |
| Уровень 4. Индекс истории обоснован EXPLAIN (ANALYZE, BUFFERS) на ≥10k | scripts\explain_demo.bat |
Index Scan 0.118 ms / buffers hit=4 read=1 против Seq Scan 4.613 ms / buffers hit=383 (≈×39 быстрее, ≈×77 меньше I/O) | scripts/explain_plans.md |
| Уровень 4. Автоматическая проверка expiry | scripts\expiry.bat (SESSION_TTL_SECONDS=2) |
EXPIRY CHECKS PASSED: свежий токен → 200, через 3 с → 401 + WWW-Authenticate: Bearer, повторный вход → 201 |
terminal output |
| Уровень 4. Logout | run_tests.py: logout -> 204, revoked token -> 401 |
повторное использование отозванного токена → 401 | terminal output |
| Уровень 4. Неверный пароль | run_tests.py: wrong password WWW-Authenticate Basic |
PASS: 401 + WWW-Authenticate: Basic realm="messenger", charset="UTF-8" |
terminal output |
| Уровень 4. Недоступность Redis | failover_tests.py: redis down: write 201, redis down: read 200 |
API деградирует в postgres-only: все операции 200 | terminal output |
| Уровень 4. Недоступность Postgres | failover_tests.py: postgres down: ready becomes 503, protected request 503, anonymous still 401 |
/health/ready → 503; защищённый запрос → 503 (не 401 и не 200); анонимный по-прежнему 401 |
terminal output |
Уровень 4. Basic только на /auth/sessions |
run_tests.py: Basic on business endpoint -> 401 Bearer |
401 + WWW-Authenticate: Bearer |
terminal output |
Уровень 4. X-User-Id не даёт доступ |
run_tests.py: X-User-Id ignored -> 401 |
401 даже с валидным UUID | terminal output |
| Трек 5. Baseline без кэша: каждое чтение = SQL | scripts\cache_demo.bat, CACHE_MODE=off |
RESULT mode=off reads=100 sql=132 stampede_sql=32; [PASS] off: every read hits SQL; [PASS] off: concurrent cold reads -> each hits SQL |
terminal output |
| Трек 5. Stale read воспроизведён на неинвалидированном кэше | scripts\cache_demo.bat, CACHE_MODE=naive |
RESULT mode=naive stale_observed=True; [PASS] naive: stale read OBSERVED (cache returned old page after write) |
terminal output |
| Трек 5. Read-after-write сохранён при инвалидации версией | scripts\cache_demo.bat, CACHE_MODE=versioned |
[PASS] read-after-write OK; [PASS] warm reads from cache |
terminal output |
| Трек 5. Single-flight ограничивает cache stampede | 32 конкурентных холодных чтения (threading.Barrier), CACHE_MODE=versioned |
stampede_sql=1 — ровно один SQL на ключ ([PASS] single-flight -> exactly 1 SQL) |
terminal output |
| Трек 5. Recovery: кэш перестраивается после рестарта Redis | docker compose restart redis + read-after-write |
RESULT mode=recovery sql_after_restart=1; [PASS] api ready; [PASS] session still valid; [PASS] history readable; [PASS] read-after-write OK; [PASS] cache rebuilds |
terminal output |
Ручные доказательства persistence (как требует tests/README.md)
- До рестарта:
docker compose psпоказывает все три сервиса healthy;SELECT COUNT(*)возвращает число пользователей, сессий и сообщений. - После
scripts/restart.bat(docker compose restart postgres redis api): все три сервиса снова healthy, счётчики не уменьшились (добавились только синтетические данные самого теста), volumesmtusi_postgres_dataиmtusi_redis_dataсуществуют. - Логи API:
shutdown signal received→server stopped cleanly→postgres connected→running migration→server started; защищённые эндпоинты отвечают 200 с тем же Bearer-токеном, что и до рестарта.
EXPLAIN-доказательство индекса (детализация строки уровня 4)
30 002 сообщения в одном чате, один и тот же запрос keyset-пагинации (первая страница, LIMIT 51):
| Метрика | С индексом messages_history_idx |
Без индекса | Отношение |
|---|---|---|---|
| План | Index Scan using messages_history_idx, Index Cond: chat_id AND ROW(created_at, id) > ROW(...) |
Seq Scan on messages + Sort по всей истории |
— |
| Execution Time | 0.118 ms | 4.613 ms | ×39 быстрее |
| Buffers (shared) | hit=4, read=1 | hit=383 | ×77 меньше I/O |
| Строк прочитано | 51 (ровно страница) | 30 002 (вся история) + Rows Removed by Filter: 520 |
×588 |
Полные планы: scripts/explain_plans.md. Вывод: пагинация использует покрывающий композитный индекс и не сканирует всю историю на страницу.
Эксперименты и отказы
Гипотеза
Без кэша каждый GET /api/v1/chats/{id}/messages выполняет SQL-запрос, и при конкуренции читателей это нагружает БД. Кэш в Redis способен снять эту нагрузку, но:
- без инвалидации нарушается контракт read-after-write (клиент видит stale-страницу);
- без защиты от cache stampede конкурентные холодные чтения лавинно бьют в БД (N читателей = N SQL).
Проверяемое утверждение: версионирование ключа кэша + single-flight сохраняют оба контракта и сокращают число SQL-запросов чтения до 1 на ключ при холодном старте и до 0 при тёплых чтениях.
Условия измерения
| Параметр | Значение |
|---|---|
| Hardware | рабочая станция разработчика, Docker Desktop |
| Лимиты контейнеров | CPU/RAM-лимиты не выставлялись (локальный учебный стенд) |
| Версии | Go 1.22; postgres:16-alpine; redis:7-alpine (зафиксированы в compose.yaml) |
| Объём данных | 30 002 сообщения в одном чате (+ пользователи, чаты, сессии smoke-сценария) |
| Профиль нагрузки — чтения | READS=100: последовательные GET на один чат, один клиент |
| Профиль нагрузки — concurrency | STAMPEDE=32: 32 конкурентных холодных чтения, синхронизированных через threading.Barrier (одномоментный burst, не постоянный arrival rate) |
| Arrival rate | не задавался: закрытая модель, следующий запрос после ответа предыдущего |
| Длительность / прогрев | фаза naive и versioned измеряются на прогретом кэше (warm-up чтениями до начала подсчёта); фаза off — без кэша, прогрев не требуется |
| Повторы | 1 прогон на фазу; для статистической значимости нужно ≥3 повтора — указано в ограничениях |
| Успешные RPS | напрямую не измерялись; оценка по медиане клиентской latency одного последовательного клиента: ≈1000/23.34 ≈ 43 RPS (off) и ≈1000/25.92 ≈ 39 RPS (versioned) — оценка, а не измерение |
| Ошибки | HTTP-ошибок в фазах кэша нет (все чтения 200, все записи 201); в failover-тестах 401/503 — ожидаемое поведение, а не ошибка |
| CPU / RAM | не собирались (docker stats не снимался) — TODO для повторного прогона |
| Метрика SQL | grep sql_list_messages по docker compose logs api --since <timestamp> |
| Метрика latency | time.perf_counter() на клиенте вокруг HTTP-запроса |
Режимы кэша (переключаются переменной CACHE_MODE, бинарник один)
| Режим | Поведение кэша | Защита от stale read | Защита от stampede | Назначение в эксперименте |
|---|---|---|---|---|
off |
кэш выключен | N/A | N/A | baseline: каждое чтение = SQL |
naive |
кэш без инвалидации | ❌ отсутствует | ❌ отсутствует | демонстрация проблемы (stale read) |
versioned |
кэш с версией чата в ключе + single-flight | ✅ bump версии на COMMIT | ✅ single-flight на ключ | решение: контракты соблюдены |
Фазы эксперимента
| Фаза | Сценарий | Наблюдаемый результат | Чек |
|---|---|---|---|
off |
baseline без кэша | RESULT mode=off reads=100 sql=132 stampede_sql=32 p50=23.34 p95=44.10 p99=46.98 |
[PASS] off: every read hits SQL; [PASS] off: concurrent cold reads -> each hits SQL |
naive |
тёплый кэш + запись + повторное чтение | RESULT mode=naive stale_observed=True |
[PASS] naive: stale read OBSERVED (cache returned old page after write) |
versioned |
защищённый кэш: read-after-write + stampede + warm reads | RESULT mode=versioned reads=100 sql=0 stampede_sql=1 p50=25.92 p95=45.12 p99=47.59 |
[PASS] read-after-write OK; [PASS] single-flight -> exactly 1 SQL; [PASS] warm reads from cache |
recovery |
docker compose restart redis + read-after-write |
RESULT mode=recovery sql_after_restart=1 |
[PASS] api ready; [PASS] session still valid; [PASS] history readable; [PASS] read-after-write OK; [PASS] cache rebuilds |
Raw summary (без токенов и секретов)
RESULT mode=off reads=100 sql=132 stampede_sql=32 p50=23.34 p95=44.10 p99=46.98
RESULT mode=naive stale_observed=True
RESULT mode=versioned reads=100 sql=0 stampede_sql=1 p50=25.92 p95=45.12 p99=47.59
RESULT mode=recovery sql_after_restart=1
EXPIRY CHECKS PASSED
PASS: lab2 public API scenario; infrastructure and grading evidence remain separate.
PASS: persistence preserved confirmed data and existing session. Hook scope needs operator evidence.
Все строки получены из terminal output скриптов scripts\cache_demo.bat, scripts\expiry.bat, make test, make test-persistence; токены сессий и значения .env в них не попадают и в отчёте не приводятся.
Счётчик SQL — главная метрика трека
| Режим | reads | sql (всего) | stampede_sql (32 холодных) | read-after-write |
|---|---|---|---|---|
off |
100 | 132 | 32 (каждый miss = SQL) | N/A |
naive |
— | — | — | FAIL (stale read OBSERVED) |
versioned |
100 | 0 (все тёплые из кэша) | 1 (single-flight) | OK |
recovery |
2 | 1 (rebuild кэша) | — | OK |
Latency p50/p95/p99 (ms, клиентское измерение)
| Режим | p50 | p95 | p99 |
|---|---|---|---|
off |
23.34 | 44.10 | 46.98 |
versioned |
25.92 | 45.12 | 47.59 |
Качественные наблюдения
- Stale read в
naive: прогретый кэш + успешная запись + повторное чтение → клиент видит старую страницу (нового сообщения нет вitems). Это конструктивная демонстрация проблемы, которую решаетversioned. - Stampede в
off: 32 конкурентных холодных чтения = 32 SQL-запроса; без кэша stampede ничем не ограничен. - Stampede-защита в
versioned: те же 32 чтения = ровно 1 SQL — single-flight схлопывает их в один SELECT. - Read-after-write в
versioned: после успешной записиbumpChatVersionменяет версию чата; следующий GET строит ключ с новой версией → cache miss → свежий SELECT → кэш перестраивается. - Recovery:
docker compose restart redisтеряет все кэш-ключи, но API продолжает работать через SQL; источник истины (сессии в Postgres) не теряется; кэш перестраивается на следующих чтениях.
Реализация защиты
| Компонент | Файл | Принцип |
|---|---|---|
| Версионирование ключа кэша | store/cache.go, HistoryCacheKey |
ключ hist:v<N>:<chat>:<cursor>:<limit>, где N = ChatVersion из Redis |
| Инвалидация на COMMIT | store/postgres.go, CreateMessage |
после успешного tx.Commit вызывается bumpChatVersion(ctx, chatID) → INCR счётчика; ключи с v<N-1 становятся «мёртвыми» |
| Single-flight против stampede | store/cache.go, SingleFlight.Do |
sync.Mutex + sync.WaitGroup на key: при конкурентных miss в SQL идёт один поток, остальные ждут его результат |
| Деградация | store/cache.go, все функции |
redisTimeout = 300ms; при ошибке Redis — log.Warn и возврат в SQL, не отказ |
Ограничения измерения
- Latency измерялась на локальном стенде и отражает суммарное время (сеть + JSON + БД/Redis). Доминируют сетевые задержки и JSON-сериализация на клиенте, поэтому p50/p95/p99 в
offиversionedблизки (23–26 ms). Для корректного сравнения выигрыша от кэша нужен отдельный бенчмарк внутри процесса API (без HTTP) — за рамками обязательного минимума трека 1. - Разница видна в счётчике SQL: 132 SQL на 100 чтений в
offпротив 0 SQL на 100 тёплых чтений вversioned— именно это доказывает, что кэш снимает нагрузку с БД. - Single-flight действует внутри одного процесса API: при нескольких репликах (тема lab3) stampede между процессами возможен.
- Один прогон на фазу без повторов и без сбора CPU/RAM: результаты latency следует считать индикативными, а не статистически значимыми.
- TTL кэша истории = 60 с: достаточно для hot-чтений и достаточно коротко, чтобы не держать устаревшие данные долго.
Таблица отказов
| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных |
|---|---|---|---|
docker compose stop redis |
/health/ready 200; запросы обслуживаются через SQL |
redis down: ready stays 200, auth via postgres 200, write 201, read 200 |
мгновенно; кэш пуст, источник истины не теряется |
docker compose start redis |
readiness 200, кэш восстанавливается | redis back: ready 200 |
< 60 с |
docker compose stop postgres |
/health/ready 503; защищённые запросы 503 |
ready becomes 503, protected request 503, anonymous still 401 |
мгновенно |
docker compose start postgres |
readiness 200; та же сессия валидна | postgres back: same session valid 200 |
< 90 с |
docker compose restart redis (фаза recovery) |
сессия жива, read-after-write OK | все PASS в recovery-фазе; sql_after_restart=1 (rebuild кэша) |
мгновенно |
Истечение TTL (SESSION_TTL_SECONDS=2, ожидание 3 с) |
401 + WWW-Authenticate: Bearer |
PASS: expired token -> 401, expired WWW-Authenticate Bearer |
N/A |
Logout (DELETE /auth/sessions/current) |
204; повторное использование токена → 401 | PASS: logout -> 204, revoked token -> 401 |
N/A |
Рестарт API + Postgres + Redis (scripts/restart.bat) |
volumes сохранены, данные и сессии живы | PASS: persistence preserved confirmed data and existing session |
мгновенно; volumes mtusi_postgres_data и mtusi_redis_data не удалены |
Stampede: 32 конкурентных холодных чтения, режим off |
каждый miss = SQL | stampede_sql=32 (ожидаемо для baseline) |
N/A |
Stampede: 32 конкурентных холодных чтения, режим versioned |
single-flight → 1 SQL | stampede_sql=1 |
N/A |
Ограничения и следующие шаги
Какие отказы выдерживаются
- Перезапуск API-контейнера: данные и сессии сохраняются (Postgres volume).
- Перезапуск Postgres-контейнера: данные сохраняются (volume).
- Перезапуск Redis-контейнера: сессии сохраняются (источник истины — Postgres), кэш перестраивается.
- SIGTERM → graceful shutdown за ~0.5 с (< 10 с бюджета
docker stop). - Потеря кэш-ключа Redis: деградация в SQL, не отказ.
- Stampede внутри процесса API: single-flight ограничивает нагрузку на БД.
- Истечение сессии: токен помечается как
ErrNotFound, ленивая чистка просрочки.
Какие отказы НЕ выдерживаются (честно указано)
- Потеря Docker-host: один host не обеспечивает HA (COURSE.md).
- Потеря volume Postgres: данные будут потеряны (репликации в lab2 нет; тема lab3+).
- Отказ Postgres: API возвращает 503, но не обслуживает запросы (read-replica в lab2 нет).
- Stampede между процессами API при горизонтальном масштабировании — тема lab3.
- S3-вложения, фоновая обработка, OTel, Argon2id — темы следующих лабораторных.
Что не реализовано (темы следующих лаб)
- Idempotency-Key для POST сообщений (lab3).
- X-Instance-Id в ответах (lab3).
- Балансировщик и ≥2 API-реплики (lab3).
- S3-хранилище вложений (lab4).
- Брокер и worker для преобразования изображений (lab5).
- OTel-observability (lab6).
- Argon2id вместо scrypt (lab7 требует Argon2id; текущая схема
scrypt$N$r$p$salt$hashпозволяет мигрировать без поломки старых паролей — параметры едут вместе с хэшем).
Где учебное упрощение
- Пароли хешируются
scryptс параметрами N=32768, r=8, p=1, keyLen=32 — достаточно для учебного стенда, но в production параметры подбираются бенчмарком под целевое железо. - Курсоры хранятся как base64url-encoded JSON; в production их подписывали бы HMAC, чтобы исключить подделку клиентом.
ChatForUserиспользует correlated subquery(SELECT array_agg(cm.user_id) ...); для больших чатов эффективнее JOIN с LIMIT.- Миграции запускаются через embed в бинарник; в production нужен отдельный инструмент с таблицей версий (goose, golang-migrate).
- Single-flight и TTL кэша (60 с) рассчитаны на один процесс API и учебный профиль нагрузки.
Что подтверждено, а что остаётся гипотезой
Подтверждено измерениями:
- Кэш с инвалидацией версией сохраняет контракт read-after-write (
versioned: read-after-write OK). - Single-flight ограничивает stampede внутри процесса ровно одним SQL на ключ (
versioned: stampede_sql=1). - В warm-режиме кэш полностью снимает SQL-нагрузку чтения (
versioned: sql=0на 100 чтений). - Деградация при Redis down работает корректно (
failover: redis down: ready stays 200, write 201, read 200). - Источник истины Postgres переживает restart Redis без потери сессий (
recovery: session still valid). - Композитный индекс истории даёт выигрыш на ≥10k сообщений: 0.118 ms против 4.613 ms, hit=4 read=1 против hit=383.
Остаётся гипотезой (до бенчмарка внутри процесса):
- Реальный выигрыш latency p50/p95/p99 от кэша: на локальном стенде с HTTP-оверхедом разница не выражена (23.34 vs 25.92 ms p50), требуется бенчмарк без HTTP-слоя.
- Поведение stampede-защиты при нескольких репликах API (нужен распределённый single-flight или Redis-lock) — проверка возможна только в lab3.
- Ресурсная цена кэша (CPU/RAM API и Redis под нагрузкой) — измерения не собирались.