Files
mtusi2026lab2/REPORT.md
T
BVT2304_Shiyan f07ad1e097
Skeleton contracts / contracts (pull_request) Canceled after 0s
lab2 - оценка 5
2026-10-07 19:06:42 +03:00

41 KiB
Raw Blame History

Отчёт — лабораторная 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) — генерация UUID
    • github.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/ не изменялись.

Запуск из чистого 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 (отдельный middleware basicOnly).
  • Регистрация принимает 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, счётчики не уменьшились (добавились только синтетические данные самого теста), volumes mtusi_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 способен снять эту нагрузку, но:

  1. без инвалидации нарушается контракт read-after-write (клиент видит stale-страницу);
  2. без защиты от 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 под нагрузкой) — измерения не собирались.