Реализация на 5

This commit is contained in:
Grbisba
2026-11-06 13:11:04 +03:00
parent 8d44c74535
commit 711754bbcd
27 changed files with 5999 additions and 116 deletions
+6
View File
@@ -31,3 +31,9 @@ coverage/
certs/
# Keep small, sanitized evidence summaries in evidence/ under version control.
# Inspect git diff --cached: ignore rules are not a secret scanner.
# Sanitized Redis experiment log accompanying evidence/redis-cache.md.
!evidence/redis-cache-api.log
# Sanitized cache stampede experiment evidence.
!evidence/cache-stampede/api.log
+329 -22
View File
@@ -1,37 +1,344 @@
# Отчёт — лабораторная 2
# Отчёт — лабораторная 2: PostgreSQL, сессии и Redis
- Автор, группа: TODO
- Целевая оценка; выбранный трек 5, если нужен: TODO
- Commit/PR: TODO после публикации
- Использованные источники, библиотеки и помощь ИИ: TODO
- Автор: Поликарпов Даниил Александрович. Группа: БПИ2303.
- Дата оформления: 6 ноября 2026 года.
- Выбранный эксперимент уровня «5»: трек 1, cache stampede — одновременные промахи кэша.
- Базовый commit: `9493763dc8ee29907a77026329e474974209b646`. Реализация и эксперименты относятся к изменённому рабочему дереву поверх этого commit; сам commit не содержит всех описанных изменений. Ссылка на PR не предоставлена.
- ChatGPT/Codex использовался для проверки функционала и подготовки отчёта. Версии библиотек закреплены в [go.mod](service/go.mod); источники и исходные результаты приведены ниже.
## Запуск из чистого clone
Цель работы — перенести пользователей, чаты, участников, сообщения и сессии в PostgreSQL, заменить идентификацию через `X-User-Id` аутентификацией и использовать Redis как необязательный кэш. Завершён эксперимент с защитой от повторных SQL-чтений при наплыве запросов. Полное выполнение всех требований уровней 3 и 4 имеющимися доказательствами не подтверждено; выполненный трек сам по себе не означает получение оценки «5».
TODO: версии runtime/образов, prerequisites, команды создания локальных secrets/.env, build, миграций, запуска, ожидания готовности, тестов и остановки. Указать необходимые действия оператора. Не вставлять секреты. Отдельно указать безопасную остановку и команду намеренного удаления учебных данных.
## 1. Запуск из чистого clone
## Архитектура и решения
### 1.1. Предварительные условия и версии
TODO: схема процессов/хранилищ, источник истины, транзакционные границы, ограничения. Что перенесено из lab1, что изменено в этой работе. Соответствие переменных из .env.example реальной конфигурации.
Нужны Git, Docker Engine с Docker Compose v2, поддерживающим `--wait`, OpenSSL, Make и Python 3.9+. На Linux для приведённой настройки доступа к ключам нужна утилита `setfacl` и поддержка POSIX ACL файловой системой. Go на хосте нужен для локальной сборки; Docker собирает приложение самостоятельно.
## Доказательства критериев
| Компонент | Версия / образ |
| --- | --- |
| Язык Go | `go 1.27.0` в go.mod; сборка контейнера `golang:1.27.2-alpine3.23` |
| Runtime API | `alpine:3.23.6`, пользователь `65532:65532` |
| PostgreSQL | `postgres:17.11-alpine3.23` |
| Redis | `redis:8.2.11-alpine3.22` |
| HTTP-маршрутизация | chi v5.5.0 |
| Доступ к PostgreSQL / миграции | pgx v5.11.0 / Tern v2.4.3 |
| Redis / объединение загрузок | go-redis v9.23.0 / x/sync v0.23.0 |
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства |
Команды этого раздела — инструкция воспроизведения. При оформлении отчёта они заново не выполнялись. Проверявшиеся ранее сборки и сценарии перечислены в разделе 4. Инструкция рассчитана на итоговое дерево исходников с описанными изменениями, а не только на базовый commit.
```sh
git clone https://gitea.privcloud.tech/mtusi2026/mtusi2026lab2.git
cd mtusi2026lab2
```
### 1.2. Локальное окружение
Следующая команда создаёт новый `.env` из [примера](.env.example), генерирует отдельные пароли PostgreSQL и Redis и включает миграции. Существующий `.env` не перезаписывается; пароли не выводятся. Выполнять из корня проекта:
```sh
umask 077
python3 - <<'PY'
from pathlib import Path
import re
import secrets
text = Path('.env.example').read_text()
values = {
'POSTGRES_PASSWORD': secrets.token_urlsafe(32),
'REDIS_PASSWORD': secrets.token_urlsafe(32),
'POSTGRES_RUN_MIGRATIONS': 'true',
}
for key, value in values.items():
text = re.sub(r'^' + key + r'=.*$', key + '=' + value, text, flags=re.MULTILINE)
with Path('.env').open('x') as stream:
stream.write(text)
PY
```
В `.env.example` сохранились устаревшие комментарий об отсутствии Go-мигратора и значение `POSTGRES_RUN_MIGRATIONS=false`. В текущем коде мигратор реализован; без его включения пустая БД не получит схему. Для уже существующего `.env` оператор должен самостоятельно проверить пароли, адреса и установить `POSTGRES_RUN_MIGRATIONS=true`. Ссылка на `infra/README.md` в комментарии примера неактуальна: этого файла в текущем дереве нет.
Для описанного Compose адреса внутри сети — `postgres:5432` и `redis:6379`; API слушает `0.0.0.0:8080`, на хост опубликован только `127.0.0.1:8080`. `HOST_PORT` меняет хостовый порт. `APP_PORT` следует оставить равным 8080: целевой порт публикации в Compose закреплён на 8080. PostgreSQL и Redis на хост не публикуются.
Пароли и ключи необходимо сохранять между перезапусками. Изменение пароля PostgreSQL в `.env` само по себе не меняет пароль роли в существующем volume.
### 1.3. RSA-ключи
На чистом clone создать пару ключей для подписи JWT. При повторном запуске существующие ключи нужно использовать повторно: их замена делает прежние подписанные сессии непригодными.
```sh
umask 077
make key-gen
chmod 600 certs/private_key.pem
chmod 644 certs/public_key.pem
```
Команда `make key-gen` генерирует RSA-ключ 2048 бит и публичную часть. Это ключи JWT, а не TLS-сертификат; локальный API работает по HTTP. Каталог `certs` монтируется только для чтения в `/run/certs`.
API работает от UID 65532. На Linux выдать этому UID доступ, сохраняя приватный ключ закрытым для остальных пользователей:
```sh
setfacl -m u:65532:rx certs
setfacl -m u:65532:r certs/private_key.pem certs/public_key.pem
```
На Docker Desktop отображение прав зависит от механизма файлового обмена. После сборки проверить чтение обоих файлов из контейнера командой ниже; ошибка требует настройки прав bind mount для UID 65532. Открывать приватный ключ всем пользователям через `chmod 644` не требуется.
### 1.4. Сборка, миграции и готовность
```sh
docker compose --env-file .env config --quiet
docker compose --env-file .env build api
docker compose --env-file .env run --rm --no-deps --entrypoint sh api \
-c 'test -r /run/certs/private_key.pem && test -r /run/certs/public_key.pem'
docker compose --env-file .env up -d --no-build --wait --wait-timeout 120
curl --fail --silent --show-error http://127.0.0.1:8080/health/live
curl --fail --silent --show-error http://127.0.0.1:8080/health/ready
docker compose --env-file .env ps -a
```
На старте API Tern применяет встроенные SQL-миграции и ведёт версию в таблице `versions`. Отдельный SQL-bootstrap контейнера PostgreSQL в текущем Compose не настроен. Ошибка миграции останавливает запуск API. При повторном запуске мигратор использует сохранённую версию; отдельный эксперимент чистого первого запуска и проверки отсутствия дублей в этом отчёте не заявлен.
Compose ожидает здоровый PostgreSQL перед запуском API. Redis является необязательной зависимостью по доступности: API не зависит от его healthcheck и продолжает запуск при ошибке стартового PING. При этом конфигурационные реквизиты Redis, включая пароль для Compose, всё равно должны быть заданы.
`/health/live` отражает жизнь HTTP-процесса. Реальный `/health/ready` проверяет флаг запущенного HTTP-сервера, а не соединение с PostgreSQL. Поэтому его 200 и статус Docker `healthy` не доказывают работоспособность обязательного пути БД при последующем отказе PostgreSQL.
Для диагностики использовать выборочные журналы; полный вывод конфигурации с секретами в отчёт не сохранять:
```sh
docker compose --env-file .env logs --tail 100 api
```
При нестандартном `HOST_PORT` заменить порт в curl и передать соответствующий `BASE_URL` проверкам.
### 1.5. Готовые проверки и остановка
Доступные команды проекта:
```sh
make check
make test BASE_URL=http://127.0.0.1:8080
make test-persistence ACTION_SCRIPT=scripts/restart.sh BASE_URL=http://127.0.0.1:8080
```
В [tests/README.md](tests/README.md) описана методика. `make test` создаёт синтетические данные. Persistence использует [scripts/restart.sh](scripts/restart.sh): он пересобирает API, останавливает его, пересоздаёт PostgreSQL и Redis с прежними volumes, затем пересоздаёт API и ждёт healthchecks. Для выполнения hook нужен executable bit. Сохранённых результатов этих двух проверок в приложенных материалах нет; команды здесь не обозначают PASS. При подготовке данного отчёта новые тесты не писались и эти проверки не запускались.
Обычная остановка сохраняет именованные volumes и локальные ключи:
```sh
docker compose --env-file .env down
```
Следующая отдельная команда предназначена только для намеренного сброса учебного стенда. Она удаляет volumes PostgreSQL и Redis текущего Compose-проекта, включая пользователей, сообщения, сессии и кэш; это не способ обычного перезапуска:
```sh
docker compose --env-file .env down --volumes
```
### 1.6. Фактически используемая конфигурация
| Переменные | Назначение и текущее поведение |
| --- | --- |
| `HOST_PORT`, `APP_HOST`, `APP_PORT` | Публикация хостового порта и адрес HTTP-listener; целевой порт публикации — 8080 |
| `APP_ENABLED` | В Compose принудительно задано `true` |
| `APP_READ_TIMEOUT`, `APP_WRITE_TIMEOUT`, `APP_IDLE_TIMEOUT`, `APP_SHUTDOWN_TIMEOUT` | Таймауты HTTP и graceful shutdown; значения Compose по умолчанию 5/10/60/8 секунд |
| `POSTGRES_HOST`, `POSTGRES_PORT`, `POSTGRES_USER`, `POSTGRES_PASSWORD`, `POSTGRES_DATABASE` | Соединение с PostgreSQL; внутри Compose следует использовать имя сервиса |
| `POSTGRES_RUN_MIGRATIONS`, `POSTGRES_VERSION_TABLE` | Включение Tern и таблица версии; для первого запуска нужны `true` и `versions` |
| `POSTGRES_MAX_CONNECTIONS` | Читается в конфигурацию, но не применяется к пулу: `config.Postgres` не реализует ожидаемый `GetMaxConnections() int32`; фактически остаётся настройка pgxpool по умолчанию |
| `REDIS_HOST`, `REDIS_PORT`, `REDIS_USERNAME`, `REDIS_PASSWORD`, `REDIS_DB` | Подключение к Redis; время операций ограничено константами в коде, отдельных env-переменных таймаутов нет |
| `JWT_REFRESH_TOKEN_LIFETIME` | Срок Bearer-сессии, по умолчанию в Compose 24 часа |
| `JWT_ACCESS_TOKEN_LIFETIME` | Срок отдельного access JWT, по умолчанию 15 минут; обязательный API принимает session token, а не этот access token |
| `JWT_PUBLIC_KEY_PATH`, `JWT_PRIVATE_KEY_PATH` | Контейнерные пути `/run/certs/public_key.pem` и `/run/certs/private_key.pem` |
| `SESSION_TTL_SECONDS` | Требуется контрактом лабораторной, но текущим загрузчиком конфигурации не поддерживается; для короткого срока в реализации используется `JWT_REFRESH_TOKEN_LIFETIME`, например `2s` |
| `APPLICATION_ENVIRONMENT`, `APPLICATION_LOG_LEVEL`, `APPLICATION_SHUTDOWN_TIMEOUT` | Читаются конфигурацией приложения; наличие этих полей не заменяет фактическую настройку HTTP shutdown через `APP_SHUTDOWN_TIMEOUT` или обработчика slog |
| `APPLICATION_REQUEST_RATE_LIMIT`, `APPLICATION_BURST_RATE_LIMIT`, `APPLICATION_RATE_LIMIT_TTL` | Читаются в конфигурацию; в текущем запуске rate-limit middleware не подключён |
| `COOKIES_*` | Остались в примере окружения; текущий основной Config их не загружает, обязательный путь аутентификации использует заголовок Bearer |
## 2. Архитектура и решения
### 2.1. Компоненты и источник истины
Клиент обращается к HTTP API на Go. Маршрутизатор chi применяет request ID, логирование и проверку сессии; обработчики декодируют и проверяют JSON, сервисы выполняют бизнес-операции, репозитории используют pgx и go-redis. Контракт находится в [OpenAPI](contracts/openapi.json) и [описании семантики](contracts/README.md).
PostgreSQL — источник истины для пользователей, чатов, членства, сообщений и сессий. Redis хранит только копии метаданных чатов. Отказ или очистка кэша не должны удалять сообщения и отзывать сессии. Это подтверждено для stop/start Redis; полный рестарт всех сервисов остаётся отдельной неподтверждённой проверкой.
По сравнению с lab1 идентификация через `X-User-Id` заменена входом по паролю и серверной сессией. Состояние перенесено в PostgreSQL; добавлены постоянные volumes и кэш. Полная совместимость обязательного API должна подтверждаться публичным smoke, результата которого в материалах нет.
### 2.2. Схема и транзакционные границы
[SQL-миграции](service/migrations) встроены в бинарник через `go:embed` и применяются Tern последовательно.
| Таблица | Основные данные и ограничения |
| --- | --- |
| `users` | UUID PK, уникальный username, имя, Argon2id-хэш пароля, времена; CHECK формата username и непустых данных |
| `refresh_tokens` | UUID PK сессии, FK пользователя, хэш токена, роль, `expires_at`, `revoked_at`; индексы по пользователю и сроку |
| `chats` | UUID PK, непустой заголовок, время; индекс `(created_at, id)` |
| `chat_members` | Составной PK `(chat_id, user_id)`, FK на чат и пользователя; дополнительный индекс `(user_id, chat_id)` |
| `messages` | UUID PK, чат, отправитель, текст и время; составной FK `(chat_id, sender_id)` на членство и индекс `(chat_id, created_at, id)` |
Создание чата и всех участников выполняется одной транзакцией: сначала INSERT чата, затем INSERT участников. Сервис проверяет отсутствие дублей и включение создателя; FK не позволяет записать неизвестного пользователя. Commit выполняется только после успешного завершения всей операции; при ошибке или panic менеджер пытается выполнить rollback. Это описание кода, а не результат отдельного fault-injection эксперимента rollback.
Создание сообщения — один параметризованный INSERT после проверки доступа. Успешный ответ отправляется после успешного выполнения SQL. Создание и отзыв серверной сессии используют транзакции; при logout строка сессии блокируется для проверки и обновления `revoked_at`. Прикладной COMMIT не является самостоятельным доказательством сохранности при потере диска или питания: отдельной проверки durability и восстановления backup нет.
### 2.3. Аутентификация и доступ
`POST /api/v1/users` регистрирует пользователя. Пароль хранится в виде Argon2id: память 64 MiB, 3 прохода, параллелизм 4, случайная соль 16 байт и ключ 32 байта. Пароль и хэш не включаются в публичный объект User.
`POST /api/v1/auth/sessions` принимает Basic и возвращает `201` с `token`, `token_type`, `expires_at`, `user`. Формат токена реализации — JWT RS256; клиент передаёт его как непрозрачную строку и не должен разбирать claims. Возвращается refresh/session JWT. Сгенерированный отдельно access JWT не подходит для обязательного session middleware.
Для каждого защищённого запроса middleware проверяет подпись и claims, читает `refresh_tokens`, проверяет срок, отсутствие отзыва, соответствие пользователя и роли, затем сравнивает хэш токена. Сессионный хэш вычисляется как bcrypt от hex-представления SHA-256 токена, с `bcrypt.DefaultCost`. Это отдельная CPU-работа даже при попадании чата в Redis. `DELETE /api/v1/auth/sessions/current` отзывает текущую сессию. `X-User-Id` не используется этим middleware как источник идентификации.
Членство проверяется в SQL или по `MemberIDs` кэшированного чата. Постороннему возвращается 404, чтобы не раскрывать наличие чужого ресурса. Положительный вход и отказ постороннему проверены экспериментом; logout, неверный пароль, отсутствие Bearer и expiry не объявляются отдельно проверенными без соответствующих результатов.
### 2.4. История и read-after-write
История читается из PostgreSQL по `chat_id`, отсортирована по `(created_at, id)` и использует keyset-условие `(created_at, id) > (cursor_created_at, cursor_id)`. Курсор API содержит UUID записи; сервер получает её позицию в пределах нужного ресурса. Размер страницы ограничен 1–100, по умолчанию 50; дополнительная запись определяет наличие следующей страницы. OFFSET и кэш истории не используются.
Индекс `idx_messages_chat_id_created_at_id` соответствует фильтрации чата и порядку выдачи. Это обоснование по структуре запроса; отсутствие полного scan на большой истории ещё не доказано EXPLAIN (ANALYZE, BUFFERS) на ≥10 000 сообщениях.
После подтверждённого POST следующий запрос истории другого участника увидел ID сообщения. Проверка выполнялась с одной API-репликой. Отдельного snapshot между страницами нет; при конкурентных вставках новые записи с позицией до уже выданного курсора могут не попасть в дальнейший обход. Многорепличная конфигурация и распределённая синхронизация часов не исследовались.
### 2.5. Политика кэша и singleflight
Ключ Redis — `chat:<UUID>`, значение — JSON с ID, заголовком, списком участников и временем создания. Чат сохраняется в кэш после успешного чтения из PostgreSQL. Срок хранения не задан (`SET` с expiration=0); автоматической инвалидации нет. В обязательном API нет изменения или удаления состава участников, поэтому существующий сценарий не содержит такого источника устаревших разрешений. При добавлении этих операций потребуется инвалидация или иная политика согласованности.
При промахе или ошибке Redis приложение читает PostgreSQL. `redis.Nil` обозначает отсутствие ключа, остальные ошибки чтения логируются отдельно. Ошибка записи в кэш не отменяет успешное чтение из БД. Redis использует AOF с `appendfsync everysec` и именованный volume; наблюдалось сохранение ключа при корректном stop/start, а не при аварийном отключении питания.
В `GetForMember` singleflight объединяет одновременные загрузки по `(ChatID, UserID)` внутри одного процесса. Общая загрузка повторно проверяет Redis, читает БД при необходимости и заполняет кэш. Пользователь входит в ключ, поскольку SQL-результат зависит от его членства: нельзя разделить отказ одного пользователя с другим. Отмена ожидающего HTTP-клиента не отменяет общую загрузку; для неё установлен отдельный таймаут 2 секунды. Членство проверяется перед возвратом результата.
Dial/read/write/pool timeout Redis установлены по 200 мс, повторы команд отключены (`MaxRetries=-1`), `DialerRetries=1`; GET, SET и стартовый PING имеют отдельные контексты по 300 мс. Чтение и последующая запись могут расходовать разные бюджеты; 300 мс не является общим таймаутом HTTP-запроса. Обычные SQL-пути вне общей загрузки не получают от HTTP WriteTimeout отдельного гарантированного срока выполнения запроса к БД.
Диагностика: `chat_cache_hit`, `chat_cache_miss`, `chat_cache_read_error`, `chat_db_lookup`; ошибки заполнения кэша записываются как `failed to cache chat`. Отсутствие `chat_db_lookup` означает экономию чтения чата, но не отсутствие SQL проверки сессии.
## 3. Соответствие критериям лабораторной
«Подтверждено» означает наличие результата выполнения в приложенных материалах. «По коду» означает найденную реализацию без отдельного результата требуемой проверки. «Не проверено» не является PASS; наличие команды или скрипта не заменяет его выполнение.
| Критерий README | Реализация / команда воспроизведения | Фактический статус | Основание / доказательство |
| --- | --- | --- | --- |
| Публичный smoke | make test | TODO | TODO |
| Остальные пункты уровня 3 | TODO | TODO | TODO |
| Все пункты уровня 4, если заявлен | TODO | TODO | TODO |
| Выбранный трек 5, если заявлен | TODO | TODO | TODO |
| Уровень 3: минимум lab1 и переход на новую аутентификацию | `make test` | По коду переход реализован; полный публичный smoke не подтверждён | [Auth middleware](service/internal/pkg/rest/middleware/auth.go), [публичный сценарий](tests/smoke.py) |
| Сохранность обязательных данных и действующих сессий после рестарта API и всех хранилищ | `make test-persistence ACTION_SCRIPT=scripts/restart.sh` | Не проверено полным сценарием; отдельно подтверждены Redis restart и использование прежней сессии | [Hook](scripts/restart.sh), [результаты Redis](evidence/cache-stampede/README.md) |
| Пользователи, чаты, участники и сообщения в PostgreSQL; PK/FK/unique | SQL-схема и операции репозиториев | По коду ограничения есть; синтетические операции создания и чтения выполнены | [Миграции](service/migrations), [проверки эксперимента](evidence/cache-stampede/summary.json) |
| Версионируемые миграции с нуля и повтор без дублей | Tern при `POSTGRES_RUN_MIGRATIONS=true`, повторный запуск API | По коду реализовано; отдельного протокола чистой БД и сверки дублей нет | [Мигратор](service/internal/pkg/migrator/tern.go) |
| Атомарное создание чата | Транзакция создания чата и участников; отказ при ошибке второго INSERT | По коду реализовано; принудительный rollback не проверен | [Репозиторий чатов](service/internal/adapter/repository/storage/chats.go), [транзакции](service/internal/pkg/postgres/txmanager/tx.go) |
| Basic только для входа, Bearer на бизнес-запросах | Создание сессии и GET чата в эксперименте | Положительные запросы подтверждены; отдельный отрицательный сценарий Basic на бизнес-endpoint не сохранён | [Auth handler](service/internal/adapter/controller/http/authHandler.go), [скрипт эксперимента](scripts/cache_stampede.py) |
| `X-User-Id` не даёт доступ | Проверка `Authorization: Bearer` в middleware | По коду; отдельного HTTP-результата для одного `X-User-Id` нет | [Middleware](service/internal/pkg/rest/middleware/auth.go) |
| Expiry, logout и password KDF | Проверка серверной сессии; DELETE current; Argon2id | KDF и проверки реализованы по коду; expiry/logout отдельно не подтверждены | [Auth service](service/internal/service/auth/svc.go), [Argon2id](service/internal/pkg/encrypting/argon2id.go) |
| `make test` и `make test-persistence` проходят | Команды раздела 1.5 | Не проверено по имеющимся результатам | [Инструкции публичных проверок](tests/README.md) |
| Secrets и volumes не попадают в Git | Правила исключений и подготовка локального окружения | Правила есть; история Git целиком на секреты не аудировалась | [.gitignore](.gitignore); результаты экспериментов обезличены |
| Уровень 4: осмысленный Redis-кэш, источник истины, expiry и инвалидация | GET чата после удаления одного ключа и повторный GET | Подтверждены miss → PostgreSQL → hit; политика хранения описана в разделе 2.5 | [Первый сценарий](evidence/redis-cache.md), [логи](evidence/redis-cache-api.log) |
| Параметризованный SQL, ограниченный пул и таймауты | Репозитории pgx, конфигурация соединений | SQL параметризован; Redis и HTTP имеют таймауты; `POSTGRES_MAX_CONNECTIONS` не применяется, общего SQL deadline нет | [Репозитории](service/internal/adapter/repository/storage), [пул](service/internal/pkg/postgres/postgres.go), [Redis config](service/internal/config/redis.go) |
| Гонка регистрации одинакового username | Параллельные POST одного username | Не проверено; unique constraint и преобразование в 409 есть по коду | [Users repo](service/internal/adapter/repository/storage/users.go) |
| Rollback составной операции | Ошибка после INSERT чата до завершения участников | Не проверено экспериментом | [Транзакции](service/internal/pkg/postgres/txmanager/tx.go) |
| Индекс истории и EXPLAIN на ≥10 000 сообщений | EXPLAIN (ANALYZE, BUFFERS) для запроса истории | Индекс и keyset есть; требуемый EXPLAIN и объём не подтверждены | [Миграция сообщений](service/migrations/005_create_messages_table.sql), [запрос](service/internal/adapter/repository/storage/messages.go) |
| Автоматические короткий TTL, logout, неверный пароль | Отдельные отрицательные сценарии сессий | Не проверено; `SESSION_TTL_SECONDS` не поддерживается текущей конфигурацией | [JWT config](service/internal/config/jwt.go), [контракт](contracts/README.md) |
| Недоступность Redis и БД; отсутствие анонимного доступа при отказе | Redis stop/start; отдельный отказ PostgreSQL и анонимный запрос | Обход отказа Redis подтверждён; PostgreSQL failure и анонимный запрос в условиях отказа не проверены | [Отказ Redis](evidence/redis-cache.md), [повторный сценарий](evidence/cache-stampede/README.md) |
| Уровень 5, трек 1: конкурентный stampede, защита, SQL и latency до/после | `python3 scripts/cache_stampede.py` после подготовки двух образов | Подтверждено: 10 × 32 GET, SELECT чата 308 → 10; ошибки ответов — 0 | [Методика](evidence/cache-stampede/README.md), [SQL-снимки](evidence/cache-stampede/summary.json), [CSV](evidence/cache-stampede/requests.csv) |
| Read-after-write из контракта | POST сообщения → GET истории другим участником | Подтверждено на одной API-реплике: ID сообщения найден после записи и после Redis restart | [Checks](evidence/cache-stampede/summary.json) |
| Восстановление после рестарта кэша | Redis stop/start, затем DEL ключа и повторный наплыв | Подтверждено: API не перезапускался, после DEL один SELECT чата на 32 GET | [Журнал и состояния](evidence/cache-stampede/api.log) |
TODO: добавить отдельную строку для каждого заявленного критерия. PASS без команды и наблюдения не является доказательством. Проверка инфраструктурного hook требует подтверждения, какие реальные процессы/хранилища перезапущены.
Трек 2 с ≥100 000 сообщений, сравнением двух вариантов индекса/запроса и backup → restore не выбран и не заявляется выполненным.
## Эксперименты и отказы
## 4. Эксперименты и отказы
TODO: гипотеза, hardware/лимиты, версии, объём данных, профиль нагрузки, concurrency/arrival rate, длительность/прогрев, повторы, успешные RPS, ошибки, p50/p95/p99, CPU/RAM. Сохранить raw summary без tokens и объяснить ограничения измерения.
### 4.1. Последовательный кэш и необязательный Redis
| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных |
[Первый эксперимент](evidence/redis-cache.md) выполнен 6 ноября 2026 года до добавления singleflight. Удалялся только ключ синтетического чата. Первый GET дал `chat_cache_miss` и `chat_db_lookup`, повторный — `chat_cache_hit` без чтения чата из БД. Посторонний пользователь при заполненном кэше получил 404.
При остановленном Redis GET вернул 200 за 56,076 мс. API был пересоздан при всё ещё остановленном Redis и продолжил работу: GET — 200 за 72,418 мс. После запуска Redis кэш восстановился без ещё одного перезапуска API. Эти результаты относятся к предшествующей сборке, идентифицированной в соответствующем отчёте; отказ Redis также повторён на версии с singleflight в следующем эксперименте.
### 4.2. Cache stampede: гипотеза и методика
Гипотеза: при одновременном промахе один и тот же пользователь многократно читает чат из PostgreSQL; singleflight позволит выполнять одну общую загрузку.
Итоговый сравнительный прогон: 6 ноября 2026 года, 09:49:37–09:50:20 UTC. Стенд — Docker Engine 29.7.2, Linux/aarch64, 14 CPU, 8 320 954 368 байт памяти Docker VM (примерно 7,75 GiB), без отдельных CPU/RAM-лимитов контейнеров. PostgreSQL 17.11, Redis 8.2.11, одна API-реплика. Один синтетический чат с двумя участниками; третий пользователь посторонний.
Перед исправлением собран baseline, затем отдельный образ с singleflight. Их точные IDs, хэши исходников и [patch изменения](evidence/cache-stampede/singleflight.patch.txt) сохранены вместе с результатами. Полная инструкция восстановления baseline в отдельной копии и сборки двух образов находится в [методике](evidence/cache-stampede/README.md); переключатель отключения защиты в приложение не добавлялся. В текущем дереве patch называется `singleflight.patch.txt`; при воспроизведении команды из методики нужно использовать это актуальное имя вместо прежнего `singleflight.patch`:
```sh
# В отдельной временной копии итоговых исходников baseline восстанавливается так:
git apply --reverse evidence/cache-stampede/singleflight.patch.txt
```
Обратный patch следует применять только в копии для сборки baseline, сохраняя основное рабочее дерево с исправлением.
Для обеих версий проведены 10 холодных наплывов по 32 GET одного участника с общим стартовым барьером. Перед каждым удалялся только экспериментальный ключ. Чтобы промахи воспроизводились на быстрой локальной БД, отдельная транзакция получала `ACCESS EXCLUSIVE` на таблицу `chats` и освобождала её через 200 мс после барьера. Это искусственная задержка чтения, одинаковая до/после; она блокирует всю таблицу и предназначена только для локального стенда. Дополнительно выполнены по 5 тёплых наплывов по 32 GET без блокировки. Между группами была пауза 300 мс.
SQL измерялся по разности `pg_stat_statements.calls` до/после каждого прогона, отдельно для SELECT чата и SELECT сессии. Расширение и preload включались временно, без глобального сброса статистики; после завершения убраны с восстановлением обычного Compose и сохранением volumes. Это серверный подсчёт SQL, а не вывод только из `chat_db_lookup`.
HTTP-длительности измерены монотонными часами клиента; timeout — 5 секунд. Перцентили рассчитаны ближайшим рангом по всем запросам серии. Все успешные GET сравнены с полным объектом чата. В дополнительных сценариях получены ожидаемые 404, ошибки доступа не смешаны с сетевыми сбоями.
### 4.3. Результаты до и после
| Версия / режим | Группы / GET | SELECT чата | SELECT сессии | p50, мс | p95, мс | p99, мс | Ошибки ответов |
| --- | --- | --- | --- | --- | --- | --- | --- |
| До, пустой кэш | 10 / 320 | 308 | 320 | 208,124 | 215,502 | 260,385 | 0 |
| После, пустой кэш | 10 / 320 | 10 | 320 | 207,056 | 209,568 | 210,032 | 0 |
| До, заполненный кэш | 5 / 160 | 0 | 160 | 138,915 | 161,038 | 172,568 | 0 |
| После, заполненный кэш | 5 / 160 | 0 | 160 | 136,467 | 172,304 | 200,266 | 0 |
Чтения чата сократились на **96,75%**: в среднем 30,8 → 1 на холодный наплыв. С учётом SELECT проверки сессий эти два вида SQL сократились с 628 до 330, на **47,45%**. Проверки сессий по-прежнему выполняются на каждом GET, поэтому «один SELECT чата» не означает «один SQL на весь наплыв».
В холодной серии p50 почти не изменился из-за общей задержки 200 мс; p99 уменьшился примерно на 50 мс. Тёплый p95, наоборот, вырос. Один последовательный порядок «до → после», небольшой объём и искусственная блокировка не доказывают устойчивое ускорение или предел throughput. Подтверждённый результат — устранение дублирующихся загрузок для выбранного ключа, а не ускорение любого HTTP-запроса.
Во время обеих фаз одинаково собирался `docker stats`. Максимальные значения среди восьми выборок каждой фазы:
| Контейнер | CPU до / после | MemUsage до / после |
| --- | --- | --- |
| API | 280,69% / 213,82% | 140,30 / 19,36 MiB |
| PostgreSQL | 5,44% / 5,44% | 52,64 / 48,31 MiB |
| Redis | 1,97% / 1,84% | 11,29 / 11,21 MiB |
Это максимумы наблюдавшихся выборок, а не точные мгновенные пики; CPU более 100% означает несколько ядер. Регистрация пользователей выполнялась перед baseline, а исправленный API использовал уже созданные записи. Поэтому различие heap/GC и памяти API нельзя приписывать singleflight.
Сводные исходные данные:
- [summary.json](evidence/cache-stampede/summary.json): параметры, образы, SQL-снимки и разности, перцентили по группам, batch RPS, выборки ресурсов и функциональные checks.
- [requests.csv](evidence/cache-stampede/requests.csv): 1016 GET основного сравнения и дополнительных наплывов, включая 8 ожидаемых 404; все ответы признаны корректными.
- [api.log](evidence/cache-stampede/api.log): выбранные события кэша и состояния контейнеров.
- [Первый сценарий: CSV](evidence/redis-cache-requests.csv) и [журнал](evidence/redis-cache-api.log).
Batch RPS в JSON учитывает время завершения группы и исключает подготовку и паузы. Он не является измерением устойчивой производительности открытого потока запросов. Пароли, Bearer-токены и ответы создания сессий в материалы не включались.
### 4.4. Дополнительные сценарии и границы восстановления
| Воздействие / сценарий | Ожидаемое поведение | Фактический результат | Границы вывода |
| --- | --- | --- | --- |
| TODO | TODO | TODO | TODO |
| Смешанный холодный наплыв: два участника и посторонний | 200 участникам, 404 постороннему | 12 GET, 3 SELECT чата, 12 SELECT сессии; все статусы корректны | Ключ singleflight включает пользователя, поэтому общее чтение не одно для всех пользователей |
| Та же группа с заполненным кэшем | Те же права без чтения чата из БД | 12 GET, 0 SELECT чата | Проверки сессий остаются |
| Отмена первого клиента во время заблокированного SELECT | Остальные клиенты продолжают общую загрузку | Следующий клиент получил 200 за 104,652 мс; один SELECT чата на два запроса | Проверена отмена инициатора, не все возможные сетевые отказы |
| POST сообщения → GET другим участником | Подтверждённое сообщение сразу видно | POST — 201; следующий GET — 200, ID сообщения найден | Одна API-реплика, история читается из PostgreSQL |
| Остановка Redis на исправленной версии | Доступ к чату через PostgreSQL | GET — 200 за 62,674 мс | Docker DNS вернул ошибку подключения; сетевой blackhole не моделировался |
| Запуск Redis с прежним volume | Возобновление кэша без рестарта API | `EXISTS` до/после — 1/1; GET — 200 за 48,701 мс; ID контейнера API не изменился | 48,701 мс — длительность GET после готовности, а не RTO Redis |
| Чтение истории после Redis restart | Сессия и подтверждённое сообщение сохранены | Прежняя сессия дала 200, ID сообщения найден | PostgreSQL в этом сценарии не перезапускался |
| DEL тестового ключа после восстановления | Защищённое заполнение пустого кэша | 32 GET, один SELECT чата, 32 SELECT сессии, ошибок нет | Действует для одного пользователя внутри одной API-реплики |
| Пересоздание API при остановленном Redis | Запуск без необязательной зависимости | На предшествующей версии GET — 200 за 72,418 мс, startup warning записан | Результат отдельно идентифицирован в первом эксперименте |
| Отказ PostgreSQL | Отказ обязательного пути без обхода аутентификации | Не проверено | Readiness сейчас не обнаруживает такой отказ; гарантированный RTO не установлен |
| Полный рестарт всех хранилищ, потеря хоста или диска | Проверка durability и восстановления | Не проверено | RPO/RTO и backup → restore не измерены |
## Ограничения и следующие шаги
Оба эксперимента завершились с работающими API, PostgreSQL и Redis; итоговые healthy-состояния записаны в приложенных журналах. Это наблюдение на момент эксперимента, а не текущая непрерывная гарантия доступности. Обязательные данные и volumes не удалялись. Синтетические учётные записи и данные экспериментов остаются на локальном стенде.
TODO: какие отказы выдерживаются и какие нет; что не реализовано; где учебное упрощение; какое улучшение подтверждено, а какое пока гипотеза.
## 5. Ограничения и дальнейшая работа
Реализован и измерен выбранный трек cache stampede, но полный набор требований лабораторной пока не доказан. Для завершения приёмки необходимо отдельно получить результаты публичного smoke, полного persistence-hook, отрицательных сценариев аутентификации, гонки username, rollback и EXPLAIN на требуемом объёме истории.
Известные расхождения реализации и конфигурации:
1. Поддержка `SESSION_TTL_SECONDS` отсутствует; срок session JWT задаётся другой переменной. Это нужно привести к контракту и проверить короткое expiry вместе с logout и неверным паролем.
2. `POSTGRES_MAX_CONNECTIONS` не управляет пулом из-за отсутствующего метода конфигурационного интерфейса. Требуется связать параметр с `pgxpool.MaxConns` и отдельно определить SQL deadlines. Таймаут HTTP-записи не заменяет таймаут SQL.
3. Readiness отражает только состояние HTTP-сервера. Нужна проверка обязательного пути PostgreSQL, сохраняющая необязательность Redis.
4. Singleflight действует только внутри одного процесса и для одной пары «чат + пользователь». Для нескольких реплик или большого числа разных пользователей понадобятся дополнительные решения и новые замеры.
5. Кэш чатов не имеет TTL и инвалидации. Для будущего изменения членства нужно определить обновление или удаление ключа до использования этой функции.
6. В примере окружения остались устаревшие сведения о миграциях и неиспользуемые настройки. При текущей работе исправлен только отчёт; приложение и конфигурационные файлы не менялись.
7. Локальный HTTP и соединение PostgreSQL с `sslmode=disable` относятся к учебному стенду. TLS, HA БД, резервное копирование и восстановление, а также потеря хоста здесь не исследовались.
Доказанная экономия SQL не устраняет обращения в PostgreSQL и bcrypt-проверку сессии на каждом запросе. При отказе PostgreSQL даже заполненный Redis не обеспечивает независимую работу авторизованного API. AOF Redis сохраняет кэш при исследованном корректном рестарте, но не заменяет backup PostgreSQL и не определяет RPO всего приложения.
## 6. Источники и материалы
- [Задание и критерии](README.md), [семантика API](contracts/README.md), [OpenAPI](contracts/openapi.json), [описание публичных проверок](tests/README.md).
- [Dockerfile](Dockerfile), [Compose](docker-compose.yml), [пример окружения](.env.example), [список зависимостей](service/go.mod).
- [Эксперимент кэша и отказа Redis](evidence/redis-cache.md), [эксперимент stampede](evidence/cache-stampede/README.md), [скрипт воспроизведения](scripts/cache_stampede.py).
- [singleflight v0.23.0](https://pkg.go.dev/golang.org/x/sync@v0.23.0/singleflight), [PostgreSQL 17: pg_stat_statements](https://www.postgresql.org/docs/17/pgstatstatements.html).
- [Redis: использование go-redis](https://redis.io/docs/latest/develop/clients/go/produsage/), [Redis INFO](https://redis.io/docs/latest/commands/info/).
При оформлении отчёта использованы исходники и уже сохранённые результаты; приложение и экспериментальные материалы не изменялись. Авторские данные и ссылка на PR не выдумывались. Проверки документа ограничены существованием локальных ссылок, соответствием чисел JSON/CSV, отсутствием незаполненных шаблонных пометок и `git diff --check`.
+14 -15
View File
@@ -3,12 +3,13 @@ services:
build:
context: .
dockerfile: Dockerfile
container_name: api
image: mtusi-messenger:lab2
restart: unless-stopped
environment:
APP_ENABLED: "true"
APP_HOST: 0.0.0.0
APP_PORT: "8080"
APP_HOST: ${APP_HOST:-0.0.0.0}
APP_PORT: ${APP_PORT:-8080}
APP_READ_TIMEOUT: ${APP_READ_TIMEOUT:-5s}
APP_WRITE_TIMEOUT: ${APP_WRITE_TIMEOUT:-10s}
APP_IDLE_TIMEOUT: ${APP_IDLE_TIMEOUT:-60s}
@@ -19,29 +20,26 @@ services:
APPLICATION_REQUEST_RATE_LIMIT: ${APPLICATION_REQUEST_RATE_LIMIT:-100}
APPLICATION_BURST_RATE_LIMIT: ${APPLICATION_BURST_RATE_LIMIT:-100}
APPLICATION_RATE_LIMIT_TTL: ${APPLICATION_RATE_LIMIT_TTL:-1m}
POSTGRES_HOST: postgres
POSTGRES_PORT: "5432"
POSTGRES_HOST: ${POSTGRES_HOST:-postgres}
POSTGRES_PORT: ${POSTGRES_PORT:-5432}
POSTGRES_USER: ${POSTGRES_USER:-messenger}
POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?Set POSTGRES_PASSWORD in .env}
POSTGRES_DATABASE: ${POSTGRES_DATABASE:-messenger}
POSTGRES_VERSION_TABLE: ${POSTGRES_VERSION_TABLE:-versions}
# Schema bootstrap is handled by postgres; the Go migration runner is not implemented.
POSTGRES_RUN_MIGRATIONS: "false"
POSTGRES_RUN_MIGRATIONS: ${POSTGRES_RUN_MIGRATIONS:-true}
POSTGRES_MAX_CONNECTIONS: ${POSTGRES_MAX_CONNECTIONS:-10}
REDIS_HOST: redis
REDIS_PORT: "6379"
REDIS_USERNAME: default
REDIS_HOST: ${REDIS_HOST:-redis}
REDIS_PORT: ${REDIS_PORT:-6379}
REDIS_USERNAME: ${REDIS_USERNAME:-default}
REDIS_PASSWORD: ${REDIS_PASSWORD:?Set REDIS_PASSWORD in .env}
REDIS_DB: ${REDIS_DB:-0}
JWT_ACCESS_TOKEN_LIFETIME: ${JWT_ACCESS_TOKEN_LIFETIME:-15m}
JWT_REFRESH_TOKEN_LIFETIME: ${JWT_REFRESH_TOKEN_LIFETIME:-24h}
JWT_PUBLIC_KEY_PATH: /run/certs/public_key.pem
JWT_PRIVATE_KEY_PATH: /run/certs/private_key.pem
JWT_PUBLIC_KEY_PATH: ${JWT_PUBLIC_KEY_PATH:-/run/certs/public_key.pem}
JWT_PRIVATE_KEY_PATH: ${JWT_PRIVATE_KEY_PATH:-/run/certs/private_key.pem}
depends_on:
postgres:
condition: service_healthy
redis:
condition: service_healthy
volumes:
- type: bind
source: ./certs
@@ -63,13 +61,14 @@ services:
volumes:
- postgres_data:/var/lib/postgresql/data
healthcheck:
test: ["CMD-SHELL", "pg_isready -h 127.0.0.1 -U \"$${POSTGRES_USER}\" -d \"$${POSTGRES_DB}\""]
test: [ "CMD-SHELL", "pg_isready -h 127.0.0.1 -U \"$${POSTGRES_USER}\" -d \"$${POSTGRES_DB}\"" ]
interval: 5s
timeout: 3s
start_period: 30s
retries: 12
stop_grace_period: 60s
redis:
image: redis:8.2.11-alpine3.22
restart: unless-stopped
@@ -84,7 +83,7 @@ services:
volumes:
- redis_data:/data
healthcheck:
test: ["CMD-SHELL", "REDISCLI_AUTH=\"$${REDIS_PASSWORD}\" redis-cli --no-auth-warning ping | grep -qx PONG"]
test: [ "CMD-SHELL", "REDISCLI_AUTH=\"$${REDIS_PASSWORD}\" redis-cli --no-auth-warning ping | grep -qx PONG" ]
interval: 5s
timeout: 3s
start_period: 5s
+6
View File
@@ -3,3 +3,9 @@
Храните небольшие обезличенные результаты: команды и stdout проверок, JSON/CSV агрегатов нагрузки, EXPLAIN, dashboard JSON, текст разбора отказа. Укажите дату, commit, аппаратные лимиты и профиль нагрузки.
Не добавляйте .env, session tokens, cookies, приватные ключи, credentials, реальные сообщения, raw dumps и signed URLs. Для скриншотов скрывайте секреты. Большие логи/бинарные traces сохраняйте отдельно по правилам преподавателя; одного скриншота без методики недостаточно.
## Выполненные проверки
- [Кэш чатов и отказ Redis](redis-cache.md): экономия чтения чата, проверка доступа, запуск API без Redis и восстановление кэша; журнал и CSV приложены.
- [Cache stampede: эксперимент до/после](cache-stampede/README.md): SQL-статистика PostgreSQL, задержки, защита singleflight, read-after-write и рестарт Redis.
+121
View File
@@ -0,0 +1,121 @@
# Cache stampede: воспроизведение, исправление и сравнение
## Результат и гипотеза
При одновременном GET одного чата несколько запросов видят пустой Redis и независимо выполняют один и тот же SELECT PostgreSQL. Гипотеза: объединение таких загрузок через singleflight сократит число SQL-запросов чтения чата до одного на наплыв одного пользователя.
В завершённом сравнении **308 SELECT чата до исправления → 10 после** для одинаковых 10 наплывов по 32 GET: снижение на 96.75%, в среднем 30.8 → 1.0 SELECT на наплыв. До исправления получалось 27–32 чтения на наплыв, после — ровно одно в каждом из 10 прогонов.
Проверки сессий отдельно выполнили 320 SELECT в каждой серии. С учётом этих двух видов SELECT общее число уменьшилось с 628 до 330, на 47.45%. Это измерения `pg_stat_statements`, а не оценка по числу HTTP-запросов или логов.
## Стенд и идентификация
- Время: 2026-11-06T09:49:37.903672Z — 2026-11-06T09:50:20.072991Z UTC (Москва UTC+3).
- Базовый commit: `8d44c745358f131ac2836ac05153af687bcf6bc0`; проверялось изменённое рабочее дерево с ранее незакоммиченными изменениями пользователя. Этот commit сам по себе не содержит проверяемую реализацию.
- Baseline image ID: `sha256:9c289d3a5a1043411647917239ec36394a5950203d03bb2c40e8dc1ff59da9cc`.
- Fixed image ID: `sha256:98776dbb15c7e0b2827a1fb96ac04a96dc48dd584a1076f71847b80cb36bc332`.
- Docker Engine 29.7.2; linux/aarch64 CPUs=14 memory_bytes=8320954368. Docker VM имеет примерно 7,75 GiB памяти; отдельных лимитов CPU/RAM у сервисов нет. Одна API-реплика; Go 1.27.2 в Dockerfile; PostgreSQL 17.11, Redis 8.2.11, go-redis v9.23.0, golang.org/x/sync v0.23.0.
- Тестовый чат: `f6da90da-8c90-4044-b1f6-29d41b5081c0`. Один новый чат с двумя синтетическими участниками; третий пользователь в него не входит. Создано одно синтетическое сообщение. Существующие пользовательские данные не удалялись; экспериментальные записи остаются в PostgreSQL.
SHA-256 исходника сервиса, go.mod и скрипта, параметры запуска и ограничения контейнера сохранены в [summary.json](summary.json). До/после использовались те же чат, пользователи и сессии. Для сбора SQL-статистики PostgreSQL временно запускался с `shared_preload_libraries=pg_stat_statements`; расширение отсутствовало до эксперимента и было создано только на время измерения.
## Изменение реализации
В `GetForMember` быстрый путь Redis сохранён. На промахе запросы объединяются `singleflight.Group.DoChan` по ключу `(ChatID, UserID)`. SQL `GetForMember` зависит от пользователя, поэтому объединять его результаты только по ChatID нельзя: отказ постороннего мог бы попасть участнику.
Внутри общей загрузки Redis проверяется повторно, затем при необходимости читается PostgreSQL и заполняется кэш. Каждый ожидающий запрос учитывает собственную отмену; общая загрузка использует `context.WithoutCancel` и отдельный таймаут 2 секунды. Отмена первого клиента не срывает загрузку для остальных. Перед возвратом проверяется `MemberIDs`. Ошибки загрузки не сохраняются после завершения singleflight; ошибки Redis по-прежнему обходятся через PostgreSQL. Таймауты Redis из предыдущей работы сохранены.
HTTP-контракт и SQL-схема приложения не менялись. Модуль x/sync уже был в зависимостях; версия не обновлялась. Точная разница с baseline сохранена в [singleflight.patch](singleflight.patch).
## Повторяемая методика
Запускать на локальном стенде без постороннего трафика. Требуются Docker Compose, Python 3.9+ и подготовленные `.env` и сертификаты по инструкции проекта. Скрипт создаёт синтетические учётные записи; пароли и Bearer-токены остаются только в памяти и не попадают в файлы или аргументы процессов.
Для повторного сравнения из итогового исходного дерева сначала подготовить baseline в отдельной временной копии. Обратный patch применяется только в копии:
```sh
baseline_dir=$(mktemp -d)
tar --exclude='.git' --exclude='.env*' --exclude='certs' --exclude='.venv' \
-cf - . | tar -xf - -C "$baseline_dir"
(cd "$baseline_dir" && git apply --reverse evidence/cache-stampede/singleflight.patch)
docker build -t mtusi-messenger:stampede-before "$baseline_dir"
docker compose --env-file .env build api
docker image tag mtusi-messenger:lab2 mtusi-messenger:stampede-after
docker compose --env-file .env up -d --no-build
python3 scripts/cache_stampede.py \
--before-image mtusi-messenger:stampede-before \
--after-image mtusi-messenger:stampede-after \
--concurrency 32 --repetitions 10 --lock-ms 200
```
Скрипт временно включает pg_stat_statements через отдельный Compose override в системном временном каталоге и переключает образы API без изменения основного Compose. Перезапуск PostgreSQL сохраняет volume. Глобальный сброс SQL-статистики не используется: для каждого прогона снимаются значения `calls` до и после отдельно для SELECT чата и SELECT сессии, с фильтром по БД и нормализованной форме запроса. Значения параметров SQL не выгружаются. Снимки, query IDs и разности находятся в JSON. Диагностические `chat_db_lookup` в журнале служат дополнительным подтверждением.
Перед каждым холодным прогоном удаляется только `chat:<экспериментальный ChatID>` в настроенной Redis DB. Все 32 потока сначала обращаются к `/health/live`, затем ожидают общего барьера. Отдельная транзакция предварительно получает `LOCK TABLE chats IN ACCESS EXCLUSIVE MODE`; через 200 мс после барьера выполняется ROLLBACK. Это моделирует медленное чтение чатов и делает одновременные промахи воспроизводимыми. Session SELECT таблицу `chats` не использует. Блокировка освобождается в `finally`; дополнительно действует пятисекундный `idle_in_transaction_session_timeout`.
Блокировка относится ко всей таблице `chats`, а не только к тестовому чату: во время этих коротких окон прочие операции с этой таблицей также будут ждать. Поэтому методика предназначена для локального стенда. В приложение искусственные задержки не добавлены.
Для каждого образа выполнены 10 холодных наплывов по 32 GET и 5 тёплых наплывов по 32 GET без блокировки. Между группами выдерживается пауза 300 мс; создание пользователей, переключение образа, сбор статистики и паузы не входят в длительность HTTP-запросов. Часы клиента монотонные; HTTP timeout — 5 секунд. Все 200-ответы сравнены с полным объектом созданного чата.
## SQL и задержки до/после
Перцентили ниже вычислены методом ближайшего ранга по всем запросам соответствующей серии; это не среднее перцентилей отдельных прогонов. Основная таблица исключает дополнительные функциональные сценарии и прогон после рестарта Redis.
| Версия и режим | Прогоны / GET | SELECT чата | SELECT сессии | p50 / p95 / p99, мс | Ошибки |
| --- | --- | --- | --- | --- | --- |
| До: пустой кэш, 200 мс | 10 / 320 | 308 | 320 | 208.124 / 215.502 / 260.385 | 0 |
| До: заполненный кэш | 5 / 160 | 0 | 160 | 138.915 / 161.038 / 172.568 | 0 |
| После: пустой кэш, 200 мс | 10 / 320 | 10 | 320 | 207.056 / 209.568 / 210.032 | 0 |
| После: заполненный кэш | 5 / 160 | 0 | 160 | 136.467 / 172.304 / 200.266 | 0 |
Полные длительности, статусы, корректность ответов и request IDs находятся в [requests.csv](requests.csv); по каждому наплыву JSON содержит перцентили, время завершения группы и successful batch RPS. Batch RPS не учитывает паузы и подготовку и не является доказательством устойчивой пропускной способности.
В холодной серии p50 почти одинаков: основную задержку задаёт общее ожидание блокировки. p99 в этом запуске уменьшился с 260,385 до 210,032 мс, однако один порядок запуска «до → после» не доказывает устойчивое ускорение. У тёплой серии p95 вырос с 161,038 до 172,304 мс, хотя SQL чтения чата в обеих версиях равен нулю. Нагрузка проверок сессии, включая bcrypt-проверку токена, осталась; шум и порядок запуска не контролировались отдельными случайными перестановками. Надёжный результат эксперимента — подавление дублирующихся SELECT чата, а не универсальное сокращение задержки каждого запроса.
### Ресурсы
`docker stats --no-stream` собирался параллельно одинаково для обеих фаз. Ниже максимальные **наблюдавшиеся значения выборки**; CPU более 100% означает использование нескольких ядер. Выборка включает холодные и тёплые серии и интервалы между ними, это не точный мгновенный пик.
| Фаза | Контейнер | Выборок | Максимум CPU | Максимум MemUsage |
| --- | --- | --- | --- | --- |
| До | api | 8 | 280.69% | 140.30 MiB |
| До | mtusi2026lab2-postgres-1 | 8 | 5.44% | 52.64 MiB |
| До | mtusi2026lab2-redis-1 | 8 | 1.97% | 11.29 MiB |
| После | api | 8 | 213.82% | 19.36 MiB |
| После | mtusi2026lab2-postgres-1 | 8 | 5.44% | 48.31 MiB |
| После | mtusi2026lab2-redis-1 | 8 | 1.84% | 11.21 MiB |
У baseline перед замерами регистрировались пользователи, тогда как после переключения на исправленную версию использовались готовые данные. Поэтому различие занятой памяти API нельзя приписать singleflight: подготовка, состояние heap и GC различаются. Значения приведены для описания условий, без вывода об экономии RAM.
## Доступ, отмена, read-after-write и рестарт
Дополнительный смешанный холодный наплыв: 12 запросов от двух участников и постороннего; участники получили 200, посторонний — 404, ошибок ответов нет. Выполнено 3 SELECT чата — разные пользователи имеют разные ключи singleflight. При заполненном кэше та же группа выполнила 0 SELECT чата с теми же статусами.
В сценарии отмены первый HTTP-клиент дошёл до заблокированного SELECT, затем его соединение было закрыто. Следующий клиент того же пользователя получил 200 после освобождения блокировки; серверная статистика показала один SELECT чата на оба запроса. Общая загрузка пережила отмену инициатора.
Сразу после создания чат прочитан другим участником без расхождений. После подтверждённого POST сообщения другой участник сразу прочитал историю и нашёл ID созданного сообщения. История сообщений не кэшируется; источником истины остаётся PostgreSQL.
При `stop redis` GET вернул 200 из PostgreSQL за 62,674 мс. После `start redis` ключ сохранился: `EXISTS` до/после вернул `1` / `1`. Это корректный stop/start с AOF и сохранённым volume, а не проверка аварийного отключения питания. ID контейнера API не изменился; прежние сессии продолжили работать. Сообщение снова найдено в истории. После удаления тестового ключа дополнительный наплыв 32 GET выполнил один SELECT чата, 32 SELECT сессии и завершился без ошибок.
| Проверка | HTTP | Время клиента, мс |
| --- | --- | --- |
| `chat_created` | 201 | 50.800 |
| `before_chat_read_after_create` | 200 | 50.977 |
| `after_chat_read_after_create` | 200 | 60.209 |
| `leader_cancelled_survivor_succeeded` | 200 | 104.652 |
| `message_committed` | 201 | 79.656 |
| `read_after_write` | 200 | 50.551 |
| `redis_unavailable` | 200 | 62.674 |
| `redis_recovered` | 200 | 48.701 |
| `message_after_restart` | 200 | 46.597 |
В конце скрипт удалил созданное им расширение, вернул исходный запуск PostgreSQL без preload, восстановил обычный Compose с исправленным API и запущенным Redis. `restored_preload` пуст, `extension_restored=true`; volumes не удалялись. Итоговые состояния контейнеров и диагностические записи находятся в [api.log](api.log). Логи содержат только выбранные события экспериментального чата и состояния контейнеров, без тел запросов и ответов создания сессий.
## Ограничения и вывод
Защита подавляет одновременные загрузки одинаковой пары `(ChatID, UserID)` внутри одной API-реплики. Для наплыва разных пользователей или нескольких реплик может выполняться несколько SELECT; распределённой блокировки нет. Отрицательные ответы не кэшируются. Чат хранится в Redis без TTL; обязательный API не изменяет состав участников. При добавлении таких изменений понадобится инвалидация.
Функциональные проверки read-after-write выполнены на имеющемся стенде с одной API-репликой, а не на многорепличной конфигурации. Данные небольшие; 200 мс созданы блокировкой, а не измерены как естественная задержка production-БД. Сравнение не оценивает предел throughput, поведение при сетевом blackhole или все требования оценки «5».
Сборка `go build -mod=readonly ./...` прошла локально с GOCACHE во временном каталоге и в Docker. `git diff --check` прошёл. Новые unit-тесты не добавлялись; скрипт является воспроизводимым инструментом эксперимента. Реализация и эксперимент подготовлены с помощью ИИ Codex.
Источники: [singleflight](https://pkg.go.dev/golang.org/x/sync@v0.23.0/singleflight), [PostgreSQL 17 pg_stat_statements](https://www.postgresql.org/docs/17/pgstatstatements.html), требования трека в [README](../../README.md), [контракт read-after-write](../../contracts/README.md).
File diff suppressed because it is too large Load Diff
File diff suppressed because it is too large Load Diff
@@ -0,0 +1,135 @@
--- a/service/internal/service/chat/svc.go
+++ b/service/internal/service/chat/svc.go
@@ -11,6 +11,7 @@
"github.com/google/uuid"
"github.com/jackc/pgx/v5"
"github.com/redis/go-redis/v9"
+ "golang.org/x/sync/singleflight"
"gitea.privcloud.tech/mtusi2026/internal/dto"
"gitea.privcloud.tech/mtusi2026/internal/pkg/apperr"
@@ -18,12 +19,15 @@
)
var _ API = (*Chat)(nil)
+
+const chatLoadTimeout = 2 * time.Second
type Chat struct {
tm *txmanager.TransactionManager
chatsRepo chatsRepo
messagesRepo messagesRepo
chatsCache chatsCache
+ loads singleflight.Group
}
func New(tm *txmanager.TransactionManager, chatsRepo chatsRepo, messagesRepo messagesRepo, chatsCache chatsCache) *Chat {
@@ -72,30 +76,68 @@
}
func (c *Chat) GetForMember(ctx context.Context, req dto.ChatMember) (*dto.Chat, error) {
- chat, err := c.chatsCache.Get(ctx, req.ChatID)
- if err == nil {
- slog.Info("chat_cache_hit", "chat_id", req.ChatID)
- if !slices.Contains(chat.MemberIDs, req.UserID) {
- return nil, apperr.New(apperr.CodeNotFound, "chat not found")
+ if err := ctx.Err(); err != nil {
+ return nil, err
+ }
+ if chat, err := c.cachedChat(ctx, req.ChatID); err == nil {
+ return chatForMember(chat, req.UserID)
+ }
+
+ // Repository results depend on membership: never share a user's 404 with
+ // another user requesting the same chat.
+ key := req.ChatID.String() + ":" + req.UserID.String()
+ result := c.loads.DoChan(key, func() (any, error) {
+ // One client disconnecting must not cancel the other clients' load.
+ loadCtx, cancel := context.WithTimeout(context.WithoutCancel(ctx), chatLoadTimeout)
+ defer cancel()
+
+ // A previous load may have populated Redis after our initial miss.
+ if chat, err := c.cachedChat(loadCtx, req.ChatID); err == nil {
+ return chatForMember(chat, req.UserID)
+ }
+
+ slog.Info("chat_db_lookup", "chat_id", req.ChatID)
+ chat, err := c.chatsRepo.GetForMember(loadCtx, req)
+ if err != nil {
+ return nil, err
+ }
+ if err = c.chatsCache.Create(loadCtx, *chat); err != nil {
+ slog.Warn("failed to cache chat", "chat_id", req.ChatID, "error", err)
}
return chat, nil
- }
-
- if errors.Is(err, redis.Nil) {
- slog.Info("chat_cache_miss", "chat_id", req.ChatID)
- } else {
- slog.Warn("chat_cache_read_error", "chat_id", req.ChatID, "error", err)
- }
-
- slog.Info("chat_db_lookup", "chat_id", req.ChatID)
- chat, err = c.chatsRepo.GetForMember(ctx, req)
- if err != nil {
- return nil, err
- }
- if err = c.chatsCache.Create(ctx, *chat); err != nil {
- slog.Warn("failed to cache chat", "chat_id", req.ChatID, "error", err)
- }
-
+ })
+
+ select {
+ case <-ctx.Done():
+ return nil, ctx.Err()
+ case loaded := <-result:
+ if err := ctx.Err(); err != nil {
+ return nil, err
+ }
+ if loaded.Err != nil {
+ return nil, loaded.Err
+ }
+ return chatForMember(loaded.Val.(*dto.Chat), req.UserID)
+ }
+}
+
+func (c *Chat) cachedChat(ctx context.Context, chatID uuid.UUID) (*dto.Chat, error) {
+ chat, err := c.chatsCache.Get(ctx, chatID)
+ switch {
+ case err == nil:
+ slog.Info("chat_cache_hit", "chat_id", chatID)
+ case errors.Is(err, redis.Nil):
+ slog.Info("chat_cache_miss", "chat_id", chatID)
+ default:
+ slog.Warn("chat_cache_read_error", "chat_id", chatID, "error", err)
+ }
+ return chat, err
+}
+
+func chatForMember(chat *dto.Chat, userID uuid.UUID) (*dto.Chat, error) {
+ if !slices.Contains(chat.MemberIDs, userID) {
+ return nil, apperr.New(apperr.CodeNotFound, "chat not found")
+ }
return chat, nil
}
--- a/service/go.mod
+++ b/service/go.mod
@@ -14,6 +14,7 @@
github.com/spf13/viper v1.21.0
go.uber.org/multierr v1.11.0
golang.org/x/crypto v0.57.0
+ golang.org/x/sync v0.23.0
google.golang.org/grpc v1.85.0
)
@@ -51,7 +52,6 @@
github.com/vgarvardt/pgx-google-uuid/v5 v5.6.0 // indirect
go.uber.org/atomic v1.12.0 // indirect
go.yaml.in/yaml/v3 v3.0.5 // indirect
- golang.org/x/sync v0.23.0 // indirect
golang.org/x/sys v0.48.0 // indirect
golang.org/x/text v0.42.0 // indirect
)
File diff suppressed because it is too large Load Diff
+61
View File
@@ -0,0 +1,61 @@
# cold_cache
api | 2026-11-06T09:34:43.708491097Z 2026/11/06 09:34:43 INFO chat_cache_miss chat_id=cf51691d-995d-497d-a361-6d0e5685943c
api | 2026-11-06T09:34:43.708526889Z 2026/11/06 09:34:43 INFO chat_db_lookup chat_id=cf51691d-995d-497d-a361-6d0e5685943c
# warm_cache
api | 2026-11-06T09:34:43.952036889Z 2026/11/06 09:34:43 INFO chat_cache_hit chat_id=cf51691d-995d-497d-a361-6d0e5685943c
# outsider_warm_cache
api | 2026-11-06T09:34:44.167119014Z 2026/11/06 09:34:44 INFO chat_cache_hit chat_id=cf51691d-995d-497d-a361-6d0e5685943c
# Redis stopped
NAME IMAGE COMMAND SERVICE CREATED STATUS PORTS
api mtusi-messenger:lab2 "/usr/local/bin/mess…" api About a minute ago Up About a minute (healthy) 127.0.0.1:8080->8080/tcp
mtusi2026lab2-postgres-1 postgres:17.11-alpine3.23 "docker-entrypoint.s…" postgres 9 minutes ago Up 9 minutes (healthy) 5432/tcp
mtusi2026lab2-redis-1 redis:8.2.11-alpine3.22 "docker-entrypoint.s…" redis 9 minutes ago Exited (0) Less than a second ago
# redis_down
api | 2026-11-06T09:34:44.767687125Z 2026/11/06 09:34:44 WARN chat_cache_read_error chat_id=cf51691d-995d-497d-a361-6d0e5685943c error="failed to read chat cache: dial tcp: lookup redis on 127.0.0.11:53: no such host"
api | 2026-11-06T09:34:44.767689750Z 2026/11/06 09:34:44 INFO chat_db_lookup chat_id=cf51691d-995d-497d-a361-6d0e5685943c
api | 2026-11-06T09:34:44.770251333Z 2026/11/06 09:34:44 WARN failed to cache chat chat_id=cf51691d-995d-497d-a361-6d0e5685943c error="failed to create chat cache: dial tcp: lookup redis on 127.0.0.11:53: no such host"
# API recreated with Redis stopped
api | 2026-11-06T09:34:45.388880375Z 2026/11/06 09:34:45 WARN redis unavailable at startup; continuing without cache error="dial tcp: lookup redis on 127.0.0.11:53: no such host"
api | 2026-11-06T09:34:45.388881917Z 2026/11/06 09:34:45 INFO HTTP server started address=0.0.0.0:8080
# API ready while Redis remains stopped
NAME IMAGE COMMAND SERVICE CREATED STATUS PORTS
api mtusi-messenger:lab2 "/usr/local/bin/mess…" api Less than a second ago Up Less than a second (health: starting) 127.0.0.1:8080->8080/tcp
mtusi2026lab2-postgres-1 postgres:17.11-alpine3.23 "docker-entrypoint.s…" postgres 9 minutes ago Up 9 minutes (healthy) 5432/tcp
mtusi2026lab2-redis-1 redis:8.2.11-alpine3.22 "docker-entrypoint.s…" redis 9 minutes ago Exited (0) 1 second ago
# startup_without_redis
api | 2026-11-06T09:34:46.010891250Z 2026/11/06 09:34:46 WARN chat_cache_read_error chat_id=cf51691d-995d-497d-a361-6d0e5685943c error="failed to read chat cache: dial tcp: lookup redis on 127.0.0.11:53: no such host"
api | 2026-11-06T09:34:46.010893125Z 2026/11/06 09:34:46 INFO chat_db_lookup chat_id=cf51691d-995d-497d-a361-6d0e5685943c
api | 2026-11-06T09:34:46.014563084Z 2026/11/06 09:34:46 WARN failed to cache chat chat_id=cf51691d-995d-497d-a361-6d0e5685943c error="failed to create chat cache: dial tcp: lookup redis on 127.0.0.11:53: no such host"
# redis_recovered
api | 2026-11-06T09:34:46.555832459Z 2026/11/06 09:34:46 INFO chat_cache_hit chat_id=cf51691d-995d-497d-a361-6d0e5685943c
# recovery_cold_cache
api | 2026-11-06T09:34:46.884677792Z 2026/11/06 09:34:46 INFO chat_cache_miss chat_id=cf51691d-995d-497d-a361-6d0e5685943c
api | 2026-11-06T09:34:46.884696959Z 2026/11/06 09:34:46 INFO chat_db_lookup chat_id=cf51691d-995d-497d-a361-6d0e5685943c
# recovery_warm_cache
api | 2026-11-06T09:34:47.112979084Z 2026/11/06 09:34:47 INFO chat_cache_hit chat_id=cf51691d-995d-497d-a361-6d0e5685943c
# recovery_outsider
api | 2026-11-06T09:34:47.354961709Z 2026/11/06 09:34:47 INFO chat_cache_hit chat_id=cf51691d-995d-497d-a361-6d0e5685943c
# Final container state
NAME IMAGE COMMAND SERVICE CREATED STATUS PORTS
api mtusi-messenger:lab2 "/usr/local/bin/mess…" api 2 seconds ago Up 2 seconds (health: starting) 127.0.0.1:8080->8080/tcp
mtusi2026lab2-postgres-1 postgres:17.11-alpine3.23 "docker-entrypoint.s…" postgres 9 minutes ago Up 9 minutes (healthy) 5432/tcp
mtusi2026lab2-redis-1 redis:8.2.11-alpine3.22 "docker-entrypoint.s…" redis 9 minutes ago Up 1 second (health: starting) 6379/tcp
# Final health checks settled
NAME IMAGE COMMAND SERVICE CREATED STATUS PORTS
api mtusi-messenger:lab2 "/usr/local/bin/mess…" api 2 minutes ago Up 2 minutes (healthy) 127.0.0.1:8080->8080/tcp
mtusi2026lab2-postgres-1 postgres:17.11-alpine3.23 "docker-entrypoint.s…" postgres 11 minutes ago Up 11 minutes (healthy) 5432/tcp
mtusi2026lab2-redis-1 redis:8.2.11-alpine3.22 "docker-entrypoint.s…" redis 11 minutes ago Up 2 minutes (healthy) 6379/tcp
+10
View File
@@ -0,0 +1,10 @@
stage,timestamp_utc,actor,status,duration_ms,request_id
cold_cache,2026-11-06T09:34:43.658980Z,alice,200,52.955,bc83a4a8-d946-4a47-bf56-2fa665bd0656
warm_cache,2026-11-06T09:34:43.892999Z,alice,200,60.433,cbc53e92-06d6-4929-9ec8-95d285ad2c49
outsider_warm_cache,2026-11-06T09:34:44.118562Z,eve,404,50.171,7b97fcb4-7144-4856-a06b-bfecf5408ca4
redis_down,2026-11-06T09:34:44.714879Z,alice,200,56.076,e08e99da-70a6-4cf4-865b-b86885e40dcf
startup_without_redis,2026-11-06T09:34:45.942892Z,alice,200,72.418,ad8653e4-1f7c-482a-a475-f4b34ed9235c
redis_recovered,2026-11-06T09:34:46.508318Z,alice,200,48.239,e7661654-9218-48d5-9056-d64f36ee477b
recovery_cold_cache,2026-11-06T09:34:46.828222Z,alice,200,57.662,6799b337-7c13-486c-a53f-7c93d8ef7dea
recovery_warm_cache,2026-11-06T09:34:47.052792Z,alice,200,60.97,17c00939-9b2a-4d49-bf7f-3e47807772e7
recovery_outsider,2026-11-06T09:34:47.291011Z,eve,404,64.866,0919aec6-9e42-47c0-879f-4cf09ccb836d
1 stage timestamp_utc actor status duration_ms request_id
2 cold_cache 2026-11-06T09:34:43.658980Z alice 200 52.955 bc83a4a8-d946-4a47-bf56-2fa665bd0656
3 warm_cache 2026-11-06T09:34:43.892999Z alice 200 60.433 cbc53e92-06d6-4929-9ec8-95d285ad2c49
4 outsider_warm_cache 2026-11-06T09:34:44.118562Z eve 404 50.171 7b97fcb4-7144-4856-a06b-bfecf5408ca4
5 redis_down 2026-11-06T09:34:44.714879Z alice 200 56.076 e08e99da-70a6-4cf4-865b-b86885e40dcf
6 startup_without_redis 2026-11-06T09:34:45.942892Z alice 200 72.418 ad8653e4-1f7c-482a-a475-f4b34ed9235c
7 redis_recovered 2026-11-06T09:34:46.508318Z alice 200 48.239 e7661654-9218-48d5-9056-d64f36ee477b
8 recovery_cold_cache 2026-11-06T09:34:46.828222Z alice 200 57.662 6799b337-7c13-486c-a53f-7c93d8ef7dea
9 recovery_warm_cache 2026-11-06T09:34:47.052792Z alice 200 60.97 17c00939-9b2a-4d49-bf7f-3e47807772e7
10 recovery_outsider 2026-11-06T09:34:47.291011Z eve 404 64.866 0919aec6-9e42-47c0-879f-4cf09ccb836d
+89
View File
@@ -0,0 +1,89 @@
# Кэш чатов: экономия SQL и отказ Redis
## Условия и изменения
Эксперимент выполнен 2026-11-06T09:34:40.942506Z — 2026-11-06T09:34:47.751055Z (UTC, Москва UTC+3).
Базовый commit: `8d44c745358f131ac2836ac05153af687bcf6bc0`. Проверялась сборка из изменённого рабочего дерева, включая ранее незакоммиченные изменения пользователя; этот commit сам по себе не содержит проверенную реализацию.
API image ID: `sha256:9d4af3c2a5c8209475eb195bf04598b843208527f7278af64326fcc4fd7423ec`.
Стенд: Docker Engine 29.7.2, linux/aarch64; CPUs=14; memory_bytes=8320954368; доступно примерно 7,75 GiB памяти Docker VM. У API, PostgreSQL и Redis отдельные ограничения CPU/RAM не заданы (`Memory=0`, `NanoCpus=0`, `CpuQuota=0`, `CpuPeriod=0`). Redis 8.2.11, PostgreSQL image `postgres:17.11-alpine3.23`, сборка контейнера Go 1.27.2, локально `go version go1.27.0 darwin/arm64`. go-redis v9.23.0.
В `GetForMember` оставлены Info-события `chat_cache_hit`, `chat_cache_miss`, `chat_db_lookup`. `errors.Is(err, redis.Nil)` отличает обычный промах от ошибки чтения `chat_cache_read_error` уровня Warn. Проверка `MemberIDs` выполняется до возврата кэшированного чата. Ошибки чтения и записи Redis не мешают получить чат из PostgreSQL.
Стартовый PING Redis больше не останавливает приложение при ошибке; зависимость API от Redis в Compose удалена. PostgreSQL остаётся обязательной зависимостью. В go-redis установлены `DialTimeout`, `ReadTimeout`, `WriteTimeout`, `PoolTimeout` по 200 мс; `MaxRetries=-1`, `DialerRetries=1`, `ContextTimeoutEnabled=true`. Каждый GET/SET кэша и стартовый PING получает отдельный дочерний контекст с бюджетом 300 мс. Контекст обращения к PostgreSQL остаётся исходным. При GET и последующем SET возможны два отдельных бюджета кэша; это не общий таймаут всего HTTP-запроса.
## Методика и команды
Перед экспериментом успешно выполнены `go build ./...` из `service/`, `docker compose --env-file .env config --quiet` и `docker compose --env-file .env up -d --build api redis`. Новые тесты не добавлялись.
Через API зарегистрированы три уникальных синтетических пользователя alice, bob и eve. Через `POST /api/v1/auth/sessions` с Basic-аутентификацией получены действующие Bearer session tokens. В этом API используется поле `token` ответа создания сессии. Создан один чат с alice и bob; eve в него не входит. Пароли и токены хранились только в памяти процесса проверки; ответы создания сессий не сохранялись. Созданные пользователи и чат остались на локальном стенде.
Тестовый чат: `cf51691d-995d-497d-a361-6d0e5685943c`. Redis DB: `0`, ключ: `chat:cf51691d-995d-497d-a361-6d0e5685943c`.
Профиль: один последовательный поток, 9 GET одного чата, без нагрузки от экспериментального клиента параллельно. Это функциональная демонстрация, а не измерение пропускной способности или процентилей задержки.
Для удаления ровно одного ключа использовалась команда ниже. Пароль разворачивается внутри контейнера и не передаётся значением в аргументах хостовой команды:
```sh
docker compose --env-file .env exec -T redis sh -c \
'REDISCLI_AUTH="$REDIS_PASSWORD" exec redis-cli --no-auth-warning -n 0 DEL "$1"' \
redis-cli chat:cf51691d-995d-497d-a361-6d0e5685943c
```
Первый DEL вернул `0`: новый чат ещё не был закэширован. Затем выполнены два GET участником и один GET посторонним. Запросы имели вид:
```sh
curl -sS -D - -o /dev/null \
-H "Authorization: Bearer $SESSION_TOKEN" \
http://127.0.0.1:8080/api/v1/chats/cf51691d-995d-497d-a361-6d0e5685943c
```
`SESSION_TOKEN` здесь — локальная переменная с действующей сессией нужного пользователя; её значение не включается в отчёт. Реальный прогон выполнялся HTTP-клиентом Python с таймаутом 5 секунд и замером через монотонные часы. У каждого ответа записаны статус, длительность и `X-Request-Id`. Все успешные ответы GET сравнены с полным объектом созданного чата, расхождений нет.
Затем выполнена последовательность:
```sh
docker compose --env-file .env stop redis
# GET участником: 200 из PostgreSQL.
docker compose --env-file .env up -d --no-deps --force-recreate api
# /health/ready: 200; GET прежним Bearer-токеном: 200 при остановленном Redis.
docker compose --env-file .env start redis
# Дождаться PONG; GET: cache hit без перезапуска API.
# Повторить DEL одного ключа, затем два GET участником и один GET посторонним.
docker compose --env-file .env ps -a
```
До остановки `EXISTS` ключа вернул `1`, после запуска Redis — `1`. Повторный DEL вернул `1`. Ключ пережил корректный stop/start с включёнными AOF (`appendonly yes`, `appendfsync everysec`) и сохранённым volume. Это наблюдение для корректной остановки, а не доказательство сохранности при аварийном отключении питания. Удалялись только указанные тестовые ключи; volumes не удалялись.
## Фактические результаты
| Этап | HTTP | Время клиента, мс | События API |
| --- | --- | --- | --- |
| Пустой кэш, участник | 200 | 52.955 | miss → db_lookup |
| Заполненный кэш, участник | 200 | 60.433 | hit, без db_lookup |
| Заполненный кэш, посторонний | 404 | 50.171 | hit, без db_lookup |
| Redis остановлен | 200 | 56.076 | read_error → db_lookup; ошибка SET |
| API пересоздан без Redis | 200 | 72.418 | read_error → db_lookup; ошибка SET |
| Redis восстановлен, API не перезапускался | 200 | 48.239 | hit, без db_lookup |
| После восстановления и DEL | 200 | 57.662 | miss → db_lookup |
| Повтор после заполнения | 200 | 60.97 | hit, без db_lookup |
| Посторонний после восстановления | 404 | 64.866 | hit, без db_lookup |
Здесь `hit`, `miss`, `read_error`, `db_lookup` соответствуют событиям `chat_cache_hit`, `chat_cache_miss`, `chat_cache_read_error`, `chat_db_lookup`. При остановленном контейнере Docker DNS возвращал `lookup redis ... no such host`; это ошибка подключения, а не `redis.Nil`. В этих запросах зафиксированы также ошибки записи кэша, но клиент получил корректный чат.
При старте API без Redis записано предупреждение `redis unavailable at startup; continuing without cache`, затем `HTTP server started`. Готовность проверена через HTTP, поэтому промежуточный статус Docker `health: starting` в журнале не означает, что запросы ещё не обслуживались.
[CSV запросов](redis-cache-requests.csv) содержит точные времена и request IDs. [Журнал API и состояния контейнеров](redis-cache-api.log) содержит отобранные строки исходных логов по временным окнам каждого последовательного запроса. События кэша содержат `chat_id`; HTTP-статусы и request IDs взяты непосредственно из ответов и находятся в CSV. Журнал не является полным дампом логов контейнеров.
## Что доказано и ограничения
Первый GET вызывает `ChatsRepo.GetForMember`, выполняющий один SQL SELECT чата с проверкой членства. Повторный GET возвращается из Redis до вызова репозитория. Таким образом, пара GET участника выполняет **один запрос чтения чата вместо двух: один запрос сэкономлен**. После восстановления Redis это подтверждено повторно. Число вызовов установлено по диагностическим веткам кода; серверный SQL-трейс или `pg_stat_statements` в этом эксперименте не собирались.
Каждый авторизованный GET отдельно проверяет сессию в PostgreSQL (`VerifySession` → `refreshTokensRepo.GetByID`), включая попадание в кэш. Поэтому отсутствие `chat_db_lookup` не означает отсутствие любых SQL-запросов. Время второго запроса в этой короткой серии не уменьшилось; демонстрация подтверждает экономию чтений чата, а не ускорение HTTP.
Посторонний пользователь получил 404 при заполненном кэше до и после отказа. API обслуживает запросы и запускается при недоступном Redis; после восстановления Redis тот же клиент возобновляет работу. Проверялось отключение через stop, а не зависшее соединение или потеря пакетов, поэтому наблюдаемые 56–72 мс не доказывают верхнюю границу задержки для всех сетевых отказов.
Текущий кэш хранит чат без TTL (`SET` с expiration=0). Для существующего API без изменения состава участников это не менялось; при добавлении такого изменения потребуется инвалидация кэша, чтобы кэшированная проверка доступа не устаревала.
Общие `keyspace_hits`/`keyspace_misses` Redis в доказательство отдельных GET не использовались: они включают обращения других клиентов.
Справочники: [таймауты и повторы go-redis](https://redis.io/docs/latest/develop/clients/go/produsage/), [Redis INFO](https://redis.io/docs/latest/commands/info/), [Docker Compose stop](https://docs.docker.com/reference/cli/docker/compose/stop/), [Docker Compose start](https://docs.docker.com/reference/cli/docker/compose/start/).
+418
View File
@@ -0,0 +1,418 @@
#!/usr/bin/env python3
"""Repeatable local cache experiment; uses Docker, Python stdlib and synthetic data.
Requires prebuilt before/after API images. Temporarily restarts local PostgreSQL
with pg_stat_statements, then restores Compose without deleting data or volumes.
"""
import argparse
import base64
import concurrent.futures as futures
import contextlib
import csv
import datetime as dt
import http.client
import hashlib
import json
import math
import pathlib
import secrets
import select
import socket
import subprocess
import tempfile
import threading
import time
import uuid
ROOT = pathlib.Path(__file__).resolve().parents[1]
NORMAL = ['docker', 'compose', '--env-file', str(ROOT / '.env'), '-f', str(ROOT / 'docker-compose.yml')]
PSQL = ['exec', '-T', 'postgres', 'sh', '-c',
'exec psql -X -q -At -v ON_ERROR_STOP=1 -U "$POSTGRES_USER" -d "$POSTGRES_DB"']
def now():
return dt.datetime.now(dt.timezone.utc).isoformat().replace('+00:00', 'Z')
def run(args, sql=None, timeout=90):
result = subprocess.run(args, input=sql, text=True, capture_output=True, cwd=ROOT, timeout=timeout)
if result.returncode:
# Never echo config, SQL parameters, HTTP bodies or credentials on failure.
raise RuntimeError('External command failed: ' + ' '.join(args[:3]))
return result.stdout.strip()
def percentile(values, fraction):
values = sorted(values)
return round(values[max(0, math.ceil(len(values) * fraction) - 1)], 3)
class Experiment:
def __init__(self, args, override):
self.args, self.override = args, override
self.out = ROOT / args.output
self.out.mkdir(parents=True, exist_ok=True)
cfg = json.loads(run(NORMAL + ['config', '--format', 'json']))
api = cfg['services']['api']
self.port = int(api['ports'][0]['published'])
self.db = str(api['environment']['REDIS_DB'])
self.pg_command = cfg['services']['postgres'].get('command') or ['postgres']
self.normal_image = api['image']
self.requests, self.runs, self.checks, self.logs, self.resources = [], [], [], [], []
self.summary = dict(started_utc=now(), commit=run(['git', 'rev-parse', 'HEAD']), dirty=True,
method=vars(args).copy(), images={}, runs=self.runs, checks=self.checks, resources=self.resources)
self.summary['docker_resources'] = run(['docker', 'info', '--format',
'{{.OSType}}/{{.Architecture}} CPUs={{.NCPU}} memory_bytes={{.MemTotal}}'])
self.summary['docker_version'] = run(['docker', 'version', '--format', '{{.Server.Version}}'])
for name, image in [('before', args.before_image), ('after', args.after_image)]:
self.summary['images'][name] = run(['docker', 'image', 'inspect', '--format', '{{.Id}}', image])
if self.summary['images']['after'] != run(['docker', 'image', 'inspect', '--format', '{{.Id}}', self.normal_image]):
raise RuntimeError('Build/tag the after image as the normal Compose API image before running')
self.summary['postgres_version'] = self.sql('SHOW server_version;')
self.summary['redis_version'] = self.redis('INFO', 'server').split('redis_version:')[1].splitlines()[0]
self.summary['source_sha256'] = {name: hashlib.sha256((ROOT/name).read_bytes()).hexdigest() for name in ('service/internal/service/chat/svc.go','service/go.mod','scripts/cache_stampede.py')}
self.preload = self.sql('SHOW shared_preload_libraries;')
self.had_extension = self.sql("SELECT count(*) FROM pg_extension WHERE extname='pg_stat_statements';") == '1'
libraries = [s.strip() for s in self.preload.split(',') if s.strip()]
if 'pg_stat_statements' not in libraries:
libraries.append('pg_stat_statements')
self.libraries = ','.join(libraries)
def compose(self, *args):
return run(NORMAL + ['-f', str(self.override)] + list(args))
def sql(self, sql):
return run(NORMAL + PSQL, sql=sql)
def use_image(self, image):
self.override.write_text(json.dumps({'services': {
'api': {'image': image},
'postgres': {'command': self.pg_command + ['-c', 'shared_preload_libraries=' + self.libraries]}}}))
def redis(self, *args):
return run(NORMAL + ['exec', '-T', 'redis', 'sh', '-c',
'REDISCLI_AUTH="$REDIS_PASSWORD" exec redis-cli --no-auth-warning -n "$@"',
'redis-cli', self.db] + list(args))
def wait_postgres(self):
deadline = time.monotonic() + 60
while time.monotonic() < deadline:
try:
if self.sql('SELECT 1;') == '1':
return
except RuntimeError:
pass
time.sleep(.3)
raise RuntimeError('PostgreSQL readiness timeout')
def http(self, method, path, actor=None, body=None, basic=None, timeout=5):
conn = http.client.HTTPConnection('127.0.0.1', self.port, timeout=timeout)
headers = {}
if actor:
headers['Authorization'] = 'Bearer ' + actor['token']
if basic:
headers['Authorization'] = 'Basic ' + base64.b64encode(basic.encode()).decode()
if body is not None:
headers['Content-Type'] = 'application/json'
stamp, started = now(), time.perf_counter()
try:
conn.request(method, path, body=None if body is None else json.dumps(body), headers=headers)
response = conn.getresponse()
data = response.read()
return dict(status=response.status, data=json.loads(data) if data else None,
request_id=response.getheader('X-Request-Id', ''), timestamp_utc=stamp,
duration_ms=round((time.perf_counter() - started) * 1000, 3))
finally:
conn.close()
def ready(self):
deadline = time.monotonic() + 45
while time.monotonic() < deadline:
try:
if self.http('GET', '/health/ready')['status'] == 200:
return
except (OSError, http.client.HTTPException):
pass
time.sleep(.3)
raise RuntimeError('API readiness timeout')
def collect_logs(self, since, label):
time.sleep(.05)
lines = run(NORMAL + ['logs', '--no-color', '--timestamps', '--since', since, 'api'])
safe = [line for line in lines.splitlines() if
(self.chat['id'] in line and ('chat_cache_' in line or 'chat_db_lookup' in line or 'failed to cache chat' in line))
or 'redis unavailable at startup' in line or 'HTTP server started' in line]
self.logs.append('\n# ' + label + '\n' + '\n'.join(safe) + '\n')
self.flush()
def flush(self):
self.summary['updated_utc'] = now()
(self.out / 'summary.json').write_text(json.dumps(self.summary, indent=2) + '\n')
(self.out / 'api.log').write_text(''.join(self.logs))
if self.requests:
with (self.out / 'requests.csv').open('w', newline='') as stream:
writer = csv.DictWriter(stream, fieldnames=list(self.requests[0]), lineterminator="\n")
writer.writeheader()
writer.writerows(self.requests)
def actor(self, label):
username, password = 'stampede_' + uuid.uuid4().hex[:16], secrets.token_urlsafe(24)
user = self.http('POST', '/api/v1/users', body=dict(username=username, display_name='Experiment ' + label, password=password))
if user['status'] != 201:
raise RuntimeError('Synthetic registration failed')
session = self.http('POST', '/api/v1/auth/sessions', basic=username + ':' + password)
if session['status'] != 201:
raise RuntimeError('Synthetic login failed')
return dict(label=label, id=user['data']['id'], token=session['data']['token'])
def snapshot(self):
# Only normalized query identities and counters are exported, never SQL parameters.
data = self.sql("""SELECT coalesce(json_agg(row_to_json(s)), '[]'::json) FROM (
SELECT queryid::text AS queryid, calls, total_exec_time,
CASE WHEN query LIKE '%FROM chats c%' THEN 'chat' ELSE 'session' END AS kind
FROM pg_stat_statements WHERE dbid=(SELECT oid FROM pg_database WHERE datname=current_database())
AND ((query LIKE '%FROM chats c%' AND query LIKE '%AND EXISTS%')
OR (query LIKE '%FROM refresh_tokens%' AND query LIKE '%WHERE id = $1%' AND query NOT LIKE '%FOR UPDATE%'))
) s;""")
return json.loads(data)
@staticmethod
def delta(before, after):
result = {}
for kind in ('chat', 'session'):
result[kind + '_sql'] = sum(r['calls'] for r in after if r['kind'] == kind) - sum(r['calls'] for r in before if r['kind'] == kind)
result[kind + '_sql_exec_ms'] = round(sum(r['total_exec_time'] for r in after if r['kind'] == kind) - sum(r['total_exec_time'] for r in before if r['kind'] == kind), 3)
return result
@contextlib.contextmanager
def lock(self):
proc = subprocess.Popen(NORMAL + PSQL, stdin=subprocess.PIPE, stdout=subprocess.PIPE,
stderr=subprocess.PIPE, text=True, cwd=ROOT)
try:
proc.stdin.write("SET statement_timeout='5s'; SET idle_in_transaction_session_timeout='5s';\nBEGIN;\nLOCK TABLE chats IN ACCESS EXCLUSIVE MODE;\n\\echo LOCKED\n")
proc.stdin.flush()
if not select.select([proc.stdout], [], [], 8)[0] or proc.stdout.readline().strip() != 'LOCKED':
raise RuntimeError('Could not acquire experimental table lock')
yield
finally:
if proc.poll() is None:
try:
proc.communicate('ROLLBACK;\n\\q\n', timeout=8)
except (subprocess.TimeoutExpired, BrokenPipeError):
proc.kill()
proc.communicate()
def burst(self, phase, mode, repetition, actors=None):
actors = actors or [self.alice] * self.args.concurrency
if mode not in ('warm', 'mixed_warm'):
self.redis('DEL', self.key)
before, since = self.snapshot(), now()
barrier = threading.Barrier(len(actors) + 1, timeout=15)
path = '/api/v1/chats/' + self.chat['id']
def worker(index, actor):
# Establish threads and touch HTTP before releasing the simultaneous burst.
if self.http('GET', '/health/live')['status'] != 200:
raise RuntimeError('Worker warmup failed')
barrier.wait()
try:
result = self.http('GET', path, actor)
expected = 404 if actor['label'] == 'eve' else 200
ok = result['status'] == expected and (expected == 404 or result['data'] == self.chat)
status, ms, rid, stamp = result['status'], result['duration_ms'], result['request_id'], result['timestamp_utc']
except (OSError, http.client.HTTPException):
ok, status, ms, rid, stamp = False, 0, 5000, '', now()
return dict(phase=phase, mode=mode, repetition=repetition, worker=index, actor=actor['label'],
timestamp_utc=stamp, status=status, duration_ms=ms, request_id=rid, correct=ok)
with futures.ThreadPoolExecutor(max_workers=len(actors)) as pool:
jobs = [pool.submit(worker, i, actor) for i, actor in enumerate(actors)]
controlled = mode in ('cold', 'mixed_cold')
with self.lock() if controlled else contextlib.nullcontext():
barrier.wait()
started = time.perf_counter()
if controlled:
time.sleep(self.args.lock_ms / 1000)
group = [job.result(timeout=10) for job in jobs]
elapsed = time.perf_counter() - started
after = self.snapshot()
errors = sum(not row['correct'] for row in group)
durations = [row['duration_ms'] for row in group]
measured = dict(phase=phase, mode=mode, repetition=repetition, requests=len(group), errors=errors,
elapsed_ms=round(elapsed*1000, 3), successful_rps=round((len(group)-errors)/elapsed, 3),
latency_ms={f'p{p}': percentile(durations, p/100) for p in (50,95,99)},
sql_before=before, sql_after=after, **self.delta(before, after))
self.requests.extend(group)
self.runs.append(measured)
self.collect_logs(since, f'{phase}/{mode}/{repetition}')
print(f'{phase}/{mode}/{repetition}: chat SQL={measured["chat_sql"]}, session SQL={measured["session_sql"]}, p95={measured["latency_ms"]["p95"]} ms, errors={errors}', flush=True)
if errors:
raise RuntimeError('Incorrect responses during burst')
if mode == 'cold' and phase == 'after' and measured['chat_sql'] != 1:
raise RuntimeError('Expected exactly one chat SELECT with singleflight')
if mode in ('warm', 'mixed_warm') and measured['chat_sql'] != 0:
raise RuntimeError('Warm cache unexpectedly queried chats')
if measured['session_sql'] != len(actors):
raise RuntimeError('Session SQL accounting differs from request count; check concurrent traffic')
time.sleep(.3)
def checked(self, name, method, path, actor, body=None, status=200):
result = self.http(method, path, actor, body)
if result['status'] != status:
raise RuntimeError('Functional check failed: ' + name)
self.checks.append(dict(name=name, status=result['status'], duration_ms=result['duration_ms'], request_id=result['request_id']))
return result['data']
def cancellation(self):
self.redis('DEL', self.key)
before, since = self.snapshot(), now()
path = '/api/v1/chats/' + self.chat['id']
with futures.ThreadPoolExecutor(max_workers=1) as pool:
with self.lock():
leader = http.client.HTTPConnection('127.0.0.1', self.port, timeout=5)
try:
leader.request('GET', path, headers={'Authorization': 'Bearer ' + self.alice['token']})
deadline = time.monotonic() + 1
while self.sql("SELECT count(*) FROM pg_stat_activity WHERE pid <> pg_backend_pid() AND wait_event_type='Lock' AND query LIKE 'SELECT c.id%';") == '0':
if time.monotonic() > deadline:
raise RuntimeError('Leader did not reach SQL')
time.sleep(.01)
leader.sock.shutdown(socket.SHUT_RDWR)
finally:
leader.close()
survivor = pool.submit(self.http, 'GET', path, self.alice)
time.sleep(.1)
result = survivor.result(timeout=5)
counters = self.delta(before, self.snapshot())
if result['status'] != 200 or result['data'] != self.chat or counters['chat_sql'] != 1:
raise RuntimeError('Client cancellation broke shared loading')
self.checks.append(dict(name='leader_cancelled_survivor_succeeded', status=result['status'],
request_id=result['request_id'], duration_ms=result['duration_ms'], **counters))
self.collect_logs(since, 'Cancelled initiating client; surviving client received chat')
def functional(self):
self.cancellation()
path = '/api/v1/chats/' + self.chat['id']
self.burst('after', 'mixed_cold', 1, [self.eve, self.alice, self.bob] * 4)
self.burst('after', 'mixed_warm', 1, [self.eve, self.alice, self.bob] * 4)
message = self.checked('message_committed', 'POST', path+'/messages', self.alice,
{'text': 'Synthetic read-after-write evidence'}, status=201)
history = self.checked('read_after_write', 'GET', path+'/messages?limit=100', self.bob)
if message['id'] not in [item['id'] for item in history['items']]:
raise RuntimeError('Committed message missing from following read')
since = now()
api_before = run(NORMAL + ['ps', '-q', 'api'])
self.summary['key_before_restart'] = self.redis('EXISTS', self.key)
try:
run(NORMAL + ['stop', 'redis'])
self.checked('redis_unavailable', 'GET', path, self.alice)
finally:
run(NORMAL + ['start', 'redis'])
deadline = time.monotonic()+30
while self.redis('PING') != 'PONG':
if time.monotonic()>deadline:
raise RuntimeError('Redis recovery timeout')
time.sleep(.3)
self.summary['key_after_restart'] = self.redis('EXISTS', self.key)
self.checked('redis_recovered', 'GET', path, self.bob)
history = self.checked('message_after_restart', 'GET', path+'/messages?limit=100', self.bob)
if message['id'] not in [item['id'] for item in history['items']]:
raise RuntimeError('Message lost after Redis restart')
if api_before != run(NORMAL + ['ps', '-q', 'api']):
raise RuntimeError('API restarted during Redis recovery')
self.collect_logs(since, 'Redis stop/start and read-after-write')
self.burst('after', 'cold', self.args.repetitions+1)
@contextlib.contextmanager
def sample_resources(self, phase):
stop = threading.Event()
containers = [run(NORMAL + ['ps', '-q', name]) for name in ('api','postgres','redis')]
def sample():
while not stop.is_set():
try:
output = run(['docker','stats','--no-stream','--format','{{json .}}'] + containers, timeout=10)
values = [json.loads(line) for line in output.splitlines() if line.strip()]
self.resources.append(dict(phase=phase, timestamp_utc=now(), containers=[
{key: value[key] for key in ('Name','CPUPerc','MemUsage','MemPerc','PIDs')} for value in values]))
except (RuntimeError, subprocess.TimeoutExpired):
self.resources.append(dict(phase=phase, timestamp_utc=now(), error='resource sampling failed'))
stop.wait(.2)
thread = threading.Thread(target=sample, daemon=True)
thread.start()
try:
yield
finally:
stop.set()
thread.join(timeout=12)
def execute(self):
self.use_image(self.args.before_image)
extension_created = False
try:
self.compose('up', '-d', '--no-build', '--force-recreate', 'postgres')
self.wait_postgres()
if not self.had_extension:
self.sql('CREATE EXTENSION pg_stat_statements;')
extension_created = True
run(NORMAL + ['start', 'redis'])
for phase, image in [('before', self.args.before_image), ('after', self.args.after_image)]:
self.use_image(image)
self.compose('up', '-d', '--no-build', '--no-deps', '--force-recreate', 'api')
self.ready()
if phase == 'before':
self.alice, self.bob, self.eve = [self.actor(label) for label in ('alice', 'bob', 'eve')]
self.chat = self.checked('chat_created', 'POST', '/api/v1/chats', self.alice,
{'title':'Stampede experiment', 'member_ids':[self.alice['id'],self.bob['id']]}, status=201)
self.key = 'chat:' + self.chat['id']
self.summary['chat_id'] = self.chat['id']
observed = self.checked(phase+'_chat_read_after_create', 'GET', '/api/v1/chats/'+self.chat['id'], self.bob)
if observed != self.chat:
raise RuntimeError('Chat read-after-create differs')
self.summary.setdefault('container_limits', {})[phase] = json.loads(run(['docker','inspect','--format',
'{"memory_bytes":{{.HostConfig.Memory}},"nano_cpus":{{.HostConfig.NanoCpus}},"cpu_quota":{{.HostConfig.CpuQuota}}}',
run(NORMAL+['ps','-q','api'])]))
with self.sample_resources(phase):
for repetition in range(1, self.args.repetitions+1):
self.burst(phase, 'cold', repetition)
for repetition in range(1, 6):
self.burst(phase, 'warm', repetition)
if not any(r['chat_sql'] > 1 for r in self.runs if r['phase']=='before' and r['mode']=='cold'):
raise RuntimeError('Baseline stampede not reproduced')
self.functional()
self.summary['success'] = True
finally:
if extension_created:
self.sql('DROP EXTENSION pg_stat_statements;')
# Restore the original Compose command and fixed normal API image.
run(NORMAL + ['up','-d','--no-build','--force-recreate','postgres'])
self.wait_postgres()
run(NORMAL + ['start','redis'])
run(NORMAL + ['up','-d','--no-build','--no-deps','--force-recreate','api'])
self.ready()
self.summary['restored_preload'] = self.sql('SHOW shared_preload_libraries;')
self.summary['extension_restored'] = (self.sql("SELECT count(*) FROM pg_extension WHERE extname='pg_stat_statements';") == ('1' if self.had_extension else '0'))
self.logs.append('\n# Final Compose state\n'+run(NORMAL+['ps','-a'])+'\n')
self.summary['ended_utc'] = now()
self.flush()
def main():
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument('--before-image', default='mtusi-messenger:stampede-before')
parser.add_argument('--after-image', default='mtusi-messenger:stampede-after')
parser.add_argument('--concurrency', type=int, default=32)
parser.add_argument('--repetitions', type=int, default=10)
parser.add_argument('--lock-ms', type=int, default=200)
parser.add_argument('--output', default='evidence/cache-stampede')
args = parser.parse_args()
if not (2 <= args.concurrency <= 64 and 1 <= args.repetitions <= 50 and 50 <= args.lock_ms <= 500):
parser.error('Use concurrency 2..64, repetitions 1..50, lock-ms 50..500')
with tempfile.TemporaryDirectory(prefix='cache-stampede-') as directory:
Experiment(args, pathlib.Path(directory)/'compose.json').execute()
print('Experiment complete; normal Compose restored.', flush=True)
if __name__ == '__main__':
main()
+13 -5
View File
@@ -10,9 +10,11 @@ import (
"time"
"gitea.privcloud.tech/mtusi2026/internal/adapter/controller/http"
"gitea.privcloud.tech/mtusi2026/internal/adapter/repository/cache/outside"
"gitea.privcloud.tech/mtusi2026/internal/adapter/repository/storage"
"gitea.privcloud.tech/mtusi2026/internal/config"
"gitea.privcloud.tech/mtusi2026/internal/pkg/auth/jwtprovider"
"gitea.privcloud.tech/mtusi2026/internal/pkg/cache"
"gitea.privcloud.tech/mtusi2026/internal/pkg/encrypting"
"gitea.privcloud.tech/mtusi2026/internal/pkg/migrator"
"gitea.privcloud.tech/mtusi2026/internal/pkg/postgres"
@@ -39,10 +41,8 @@ func run() error {
return fmt.Errorf("load server config: %w", err)
}
pgx, err := postgres.New(cfg.Postgres)
if err != nil {
return fmt.Errorf("init postgres: %w", err)
}
pgx := postgres.New(cfg.Postgres)
rx := cache.New(cfg)
postgresMigrator := migrator.New(cfg)
tm := txmanager.New(pgx)
provider := jwtprovider.New(cfg)
@@ -53,9 +53,11 @@ func run() error {
refreshTokensRepo := storage.NewRefreshTokensRepo(pgx)
userRepo := storage.NewUsersRepo(pgx)
chatCache := outside.NewChatCache(rx)
authSvc := auth.New(provider, tm, encryptor, userRepo, refreshTokensRepo)
userSvc := user.New(encryptor, userRepo)
chatSvc := chat.New(tm, chatsRepo, messageRepo)
chatSvc := chat.New(tm, chatsRepo, messageRepo, chatCache)
httpRouter := router.New(
middleware.NewAuthMiddleware(authSvc),
@@ -80,6 +82,9 @@ func run() error {
if err = server.Start(ctx); err != nil {
return fmt.Errorf("start HTTP server: %w", err)
}
if err = rx.Start(ctx); err != nil {
slog.Warn("redis unavailable at startup; continuing without cache", "error", err)
}
slog.Info("HTTP server started", "address", cfg.Server.BindAddress())
<-ctx.Done()
@@ -91,6 +96,9 @@ func run() error {
if err = postgresMigrator.Close(shutdownCtx); err != nil {
return fmt.Errorf("close postgres migrator: %w", err)
}
if err = rx.Close(); err != nil {
return fmt.Errorf("close redis: %w", err)
}
return nil
}
+1 -1
View File
@@ -14,6 +14,7 @@ require (
github.com/spf13/viper v1.21.0
go.uber.org/multierr v1.11.0
golang.org/x/crypto v0.57.0
golang.org/x/sync v0.23.0
google.golang.org/grpc v1.85.0
)
@@ -51,7 +52,6 @@ require (
github.com/vgarvardt/pgx-google-uuid/v5 v5.6.0 // indirect
go.uber.org/atomic v1.12.0 // indirect
go.yaml.in/yaml/v3 v3.0.5 // indirect
golang.org/x/sync v0.23.0 // indirect
golang.org/x/sys v0.48.0 // indirect
golang.org/x/text v0.42.0 // indirect
)
@@ -2,9 +2,15 @@ package http
import (
"net/http"
"regexp"
"strings"
"unicode/utf8"
"github.com/google/uuid"
"gitea.privcloud.tech/mtusi2026/internal/dto"
"gitea.privcloud.tech/mtusi2026/internal/gen/contracts"
"gitea.privcloud.tech/mtusi2026/internal/pkg/apperr"
"gitea.privcloud.tech/mtusi2026/internal/pkg/auth/jwtprovider"
"gitea.privcloud.tech/mtusi2026/internal/pkg/rest/framework"
"gitea.privcloud.tech/mtusi2026/internal/pkg/rest/router"
@@ -29,6 +35,8 @@ func NewUserHandler(r router.Router, provider jwtprovider.Provider, v *validator
}
}
var usernamePattern = regexp.MustCompile(`^[a-z0-9_]{3,32}$`)
func (h *UserHandler) RegisterRoutes() {
h.router.Public(http.MethodPost, "/api/v1/users", h.Create)
h.router.Private(http.MethodGet, "/api/v1/users/me", h.GetMe)
@@ -51,6 +59,17 @@ func (h *UserHandler) Create(w http.ResponseWriter, r *http.Request) {
toCreate.Password = *req.Password
}
if !usernamePattern.MatchString(req.Username) || !utf8.ValidString(req.DisplayName) ||
strings.TrimSpace(req.DisplayName) == "" || utf8.RuneCountInString(req.DisplayName) > 100 {
framework.JSONError(ctx, w, apperr.New(apperr.CodeBadRequest, "invalid user fields"))
return
}
passwordLen := utf8.RuneCountInString(toCreate.Password)
if !utf8.ValidString(toCreate.Password) || strings.TrimSpace(toCreate.Password) == "" || passwordLen < 12 || passwordLen > 128 {
framework.JSONError(ctx, w, apperr.New(apperr.CodeBadRequest, "invalid password"))
return
}
resp, err := h.user.Create(ctx, toCreate)
if err != nil {
framework.JSONError(ctx, w, err)
@@ -74,6 +93,11 @@ func (h *UserHandler) GetMe(w http.ResponseWriter, r *http.Request) {
return
}
if userData.UserID == uuid.Nil {
framework.JSONError(ctx, w, apperr.New(apperr.CodeBadRequest, "invalid user id"))
return
}
resp, err := h.user.GetByID(ctx, userData.UserID)
if err != nil {
framework.JSONError(ctx, w, err)
@@ -0,0 +1,78 @@
package outside
import (
"context"
"encoding/json"
"fmt"
"time"
"github.com/google/uuid"
"gitea.privcloud.tech/mtusi2026/internal/dto"
"gitea.privcloud.tech/mtusi2026/internal/pkg/apperr"
"gitea.privcloud.tech/mtusi2026/internal/pkg/cache"
)
const (
// chatRedisKey equals "chat:{chat_id}" path
chatRedisKey = "chat:%s"
)
type ChatCache struct {
client *cache.Client
}
func NewChatCache(client *cache.Client) *ChatCache {
return &ChatCache{
client: client,
}
}
type chat struct {
ID uuid.UUID `json:"id"`
Title string `json:"title"`
MemberIDs []uuid.UUID `json:"member_ids"`
CreatedAt time.Time `json:"created_at"`
}
func (r *ChatCache) Create(ctx context.Context, req dto.Chat) error {
data, err := json.Marshal(chat{
ID: req.ID,
Title: req.Title,
MemberIDs: req.MemberIDs,
CreatedAt: req.CreatedAt,
})
if err != nil {
return apperr.Wrap(err, apperr.CodeInternal, "failed to marshal chat cache")
}
ctx, cancel := context.WithTimeout(ctx, cache.OperationTimeout)
defer cancel()
err = r.client.Set(ctx, fmt.Sprintf(chatRedisKey, req.ID), data, 0).Err()
if err != nil {
return apperr.WrapRedis(err, "failed to create chat cache")
}
return nil
}
func (r *ChatCache) Get(ctx context.Context, chatID uuid.UUID) (*dto.Chat, error) {
ctx, cancel := context.WithTimeout(ctx, cache.OperationTimeout)
defer cancel()
data, err := r.client.Get(ctx, fmt.Sprintf(chatRedisKey, chatID.String())).Bytes()
if err != nil {
return nil, apperr.WrapRedis(err, "failed to read chat cache")
}
var item chat
if err = json.Unmarshal(data, &item); err != nil {
return nil, apperr.Wrap(err, apperr.CodeInternal, "failed to unmarshal chat cache")
}
return &dto.Chat{
ID: item.ID,
Title: item.Title,
MemberIDs: item.MemberIDs,
CreatedAt: item.CreatedAt,
}, nil
}
+12 -4
View File
@@ -4,6 +4,7 @@ import (
"errors"
"fmt"
"net"
"time"
"github.com/redis/go-redis/v9"
"github.com/spf13/viper"
@@ -33,10 +34,17 @@ func (c *Redis) BuildRedisOptions() *redis.Options {
return nil
}
return &redis.Options{
Addr: net.JoinHostPort(c.Host, fmt.Sprintf("%d", c.Port)),
Username: c.Username,
Password: c.Password,
DB: c.DB,
Addr: net.JoinHostPort(c.Host, fmt.Sprintf("%d", c.Port)),
Username: c.Username,
Password: c.Password,
DB: c.DB,
DialTimeout: 200 * time.Millisecond,
ReadTimeout: 200 * time.Millisecond,
WriteTimeout: 200 * time.Millisecond,
PoolTimeout: 200 * time.Millisecond,
MaxRetries: -1,
DialerRetries: 1,
ContextTimeoutEnabled: true,
}
}
+43
View File
@@ -0,0 +1,43 @@
package cache
import (
"context"
"time"
"github.com/redis/go-redis/v9"
"gitea.privcloud.tech/mtusi2026/internal/config"
)
const defaultRedisPort = 6379
// OperationTimeout bounds each optional cache operation independently of the request.
const OperationTimeout = 300 * time.Millisecond
type Client struct {
*redis.Client
}
func New(cfg *config.Config) *Client {
if cfg.Redis.Port == 0 {
cfg.Redis.Port = defaultRedisPort
}
return &Client{
Client: redis.NewClient(cfg.Redis.BuildRedisOptions()),
}
}
func (c *Client) Ping(ctx context.Context) error {
ctx, cancel := context.WithTimeout(ctx, OperationTimeout)
defer cancel()
return c.Client.Ping(ctx).Err()
}
func (c *Client) Start(ctx context.Context) error {
return c.Ping(ctx)
}
func (c *Client) Stop(_ context.Context) error {
return c.Client.Close()
}
+4 -4
View File
@@ -33,7 +33,7 @@ func addMaxConnectionsToCfg(cfg any, poolCfg *pgxpool.Config) {
}
}
func New(cfg MigrationConfig, afterConnect ...AfterConnect) (*pgxpool.Pool, error) {
func New(cfg MigrationConfig, afterConnect ...AfterConnect) *pgxpool.Pool {
lvl := getLevelFromConfig(cfg)
if len(afterConnect) == 0 {
@@ -43,7 +43,7 @@ func New(cfg MigrationConfig, afterConnect ...AfterConnect) (*pgxpool.Pool, erro
poolConfig, err := pgxpool.ParseConfig(cfg.GetURI())
if err != nil {
slog.Error("failed to parse postgres config", "error", err)
return nil, errParseConfig
panic(err)
}
addMaxConnectionsToCfg(cfg, poolConfig)
@@ -61,11 +61,11 @@ func New(cfg MigrationConfig, afterConnect ...AfterConnect) (*pgxpool.Pool, erro
pool, err := pgxpool.NewWithConfig(context.Background(), poolConfig)
if err != nil {
slog.Error("failed to create postgres pool", "error", err)
return nil, errCreatingPool
panic(err)
}
slog.Info("successfully connected to postgres pool")
return pool, nil
return pool
}
func load(afterConnects ...AfterConnect) func(ctx context.Context, conn *pgx.Conn) error {
@@ -20,3 +20,8 @@ type messagesRepo interface {
GetByIDForChat(ctx context.Context, chatID, messageID uuid.UUID) (*dto.Message, error)
ListForChat(ctx context.Context, chatID uuid.UUID, page dto.PageQuery) ([]dto.Message, error)
}
type chatsCache interface {
Create(ctx context.Context, req dto.Chat) error
Get(ctx context.Context, chatID uuid.UUID) (*dto.Chat, error)
}
+75 -8
View File
@@ -3,11 +3,15 @@ package chat
import (
"bytes"
"context"
"errors"
"log/slog"
"slices"
"time"
"github.com/google/uuid"
"github.com/jackc/pgx/v5"
"github.com/redis/go-redis/v9"
"golang.org/x/sync/singleflight"
"gitea.privcloud.tech/mtusi2026/internal/dto"
"gitea.privcloud.tech/mtusi2026/internal/pkg/apperr"
@@ -16,21 +20,26 @@ import (
var _ API = (*Chat)(nil)
const chatLoadTimeout = 2 * time.Second
type Chat struct {
tm *txmanager.TransactionManager
chatsRepo chatsRepo
messagesRepo messagesRepo
chatsCache chatsCache
loads singleflight.Group
}
func New(tm *txmanager.TransactionManager, chatsRepo chatsRepo, messagesRepo messagesRepo) *Chat {
return &Chat{tm: tm, chatsRepo: chatsRepo, messagesRepo: messagesRepo}
func New(tm *txmanager.TransactionManager, chatsRepo chatsRepo, messagesRepo messagesRepo, chatsCache chatsCache) *Chat {
return &Chat{
tm: tm,
chatsRepo: chatsRepo,
messagesRepo: messagesRepo,
chatsCache: chatsCache,
}
}
func (c *Chat) CreateChat(ctx context.Context, req dto.CreateChat) (*dto.Chat, error) {
if err := ctx.Err(); err != nil {
return nil, err
}
seen := make(map[uuid.UUID]struct{}, len(req.MemberIDs))
for _, id := range req.MemberIDs {
if id == uuid.Nil {
@@ -67,10 +76,68 @@ func (c *Chat) CreateChat(ctx context.Context, req dto.CreateChat) (*dto.Chat, e
}
func (c *Chat) GetForMember(ctx context.Context, req dto.ChatMember) (*dto.Chat, error) {
chat, err := c.chatsRepo.GetForMember(ctx, req)
if err != nil {
if err := ctx.Err(); err != nil {
return nil, err
}
if chat, err := c.cachedChat(ctx, req.ChatID); err == nil {
return chatForMember(chat, req.UserID)
}
// Repository results depend on membership: never share a user's 404 with
// another user requesting the same chat.
key := req.ChatID.String() + ":" + req.UserID.String()
result := c.loads.DoChan(key, func() (any, error) {
// One client disconnecting must not cancel the other clients' load.
loadCtx, cancel := context.WithTimeout(context.WithoutCancel(ctx), chatLoadTimeout)
defer cancel()
// A previous load may have populated Redis after our initial miss.
if chat, err := c.cachedChat(loadCtx, req.ChatID); err == nil {
return chatForMember(chat, req.UserID)
}
slog.Info("chat_db_lookup", "chat_id", req.ChatID)
chat, err := c.chatsRepo.GetForMember(loadCtx, req)
if err != nil {
return nil, err
}
if err = c.chatsCache.Create(loadCtx, *chat); err != nil {
slog.Warn("failed to cache chat", "chat_id", req.ChatID, "error", err)
}
return chat, nil
})
select {
case <-ctx.Done():
return nil, ctx.Err()
case loaded := <-result:
if err := ctx.Err(); err != nil {
return nil, err
}
if loaded.Err != nil {
return nil, loaded.Err
}
return chatForMember(loaded.Val.(*dto.Chat), req.UserID)
}
}
func (c *Chat) cachedChat(ctx context.Context, chatID uuid.UUID) (*dto.Chat, error) {
chat, err := c.chatsCache.Get(ctx, chatID)
switch {
case err == nil:
slog.Info("chat_cache_hit", "chat_id", chatID)
case errors.Is(err, redis.Nil):
slog.Info("chat_cache_miss", "chat_id", chatID)
default:
slog.Warn("chat_cache_read_error", "chat_id", chatID, "error", err)
}
return chat, err
}
func chatForMember(chat *dto.Chat, userID uuid.UUID) (*dto.Chat, error) {
if !slices.Contains(chat.MemberIDs, userID) {
return nil, apperr.New(apperr.CodeNotFound, "chat not found")
}
return chat, nil
}
+3 -3
View File
@@ -9,7 +9,7 @@ import (
)
type API interface {
Create(ctx context.Context, req dto.CreateUser) (dto.User, error)
GetByID(ctx context.Context, id uuid.UUID) (dto.User, error)
GetByUsername(ctx context.Context, username string) (dto.User, error)
Create(ctx context.Context, req dto.CreateUser) (*dto.User, error)
GetByID(ctx context.Context, id uuid.UUID) (*dto.User, error)
GetByUsername(ctx context.Context, username string) (*dto.User, error)
}
+24 -54
View File
@@ -2,10 +2,7 @@ package user
import (
"context"
"regexp"
"strings"
"time"
"unicode/utf8"
"github.com/google/uuid"
@@ -15,8 +12,7 @@ import (
)
var (
_ API = (*User)(nil)
usernamePattern = regexp.MustCompile(`^[a-z0-9_]{3,32}$`)
_ API = (*User)(nil)
)
type User struct {
@@ -28,70 +24,44 @@ func New(encryptor encrypting.Encryptor, usersRepo userRepo) *User {
return &User{encryptor: encryptor, usersRepo: usersRepo}
}
func (u *User) Create(ctx context.Context, req dto.CreateUser) (dto.User, error) {
if err := ctx.Err(); err != nil {
return dto.User{}, err
}
if !usernamePattern.MatchString(req.Username) || !utf8.ValidString(req.DisplayName) ||
strings.TrimSpace(req.DisplayName) == "" || utf8.RuneCountInString(req.DisplayName) > 100 {
return dto.User{}, apperr.New(apperr.CodeBadRequest, "invalid user fields")
}
passwordLen := utf8.RuneCountInString(req.Password)
if !utf8.ValidString(req.Password) || strings.TrimSpace(req.Password) == "" || passwordLen < 12 || passwordLen > 128 {
return dto.User{}, apperr.New(apperr.CodeBadRequest, "invalid password")
}
id, err := uuid.NewRandom()
if err != nil {
return dto.User{}, apperr.Wrap(err, apperr.CodeInternal, "failed to generate user id")
}
func (u *User) Create(ctx context.Context, req dto.CreateUser) (*dto.User, error) {
hash, err := u.encryptor.EncryptSecretUsingArgon2id(ctx, req.Password)
if err != nil {
if ctx.Err() != nil {
return dto.User{}, ctx.Err()
}
return dto.User{}, apperr.Wrap(err, apperr.CodeInternal, "failed to hash password")
return nil, apperr.Wrap(err, apperr.CodeInternal, "failed to hash password")
}
now := time.Now().Truncate(time.Microsecond)
user := dto.User{ID: id, Username: req.Username, DisplayName: req.DisplayName, CreatedAt: now}
user := dto.User{
ID: uuid.New(),
Username: req.Username,
DisplayName: req.DisplayName,
CreatedAt: time.Now().Truncate(time.Microsecond),
}
if err = u.usersRepo.Create(ctx, dto.CreateStoredUser{
ID: user.ID,
Username: user.Username,
DisplayName: user.DisplayName,
PasswordHash: hash,
CreatedAt: now,
UpdatedAt: now,
CreatedAt: user.CreatedAt,
UpdatedAt: user.CreatedAt,
}); err != nil {
return dto.User{}, err
return nil, err
}
return &user, nil
}
func (u *User) GetByID(ctx context.Context, id uuid.UUID) (*dto.User, error) {
user, err := u.usersRepo.GetByID(ctx, id)
if err != nil {
return nil, err
}
return user, nil
}
func (u *User) GetByID(ctx context.Context, id uuid.UUID) (dto.User, error) {
if err := ctx.Err(); err != nil {
return dto.User{}, err
}
if id == uuid.Nil {
return dto.User{}, apperr.New(apperr.CodeBadRequest, "invalid user id")
}
user, err := u.usersRepo.GetByID(ctx, id)
if err != nil {
return dto.User{}, err
}
return *user, nil
}
func (u *User) GetByUsername(ctx context.Context, username string) (dto.User, error) {
if err := ctx.Err(); err != nil {
return dto.User{}, err
}
if !usernamePattern.MatchString(username) {
return dto.User{}, apperr.New(apperr.CodeBadRequest, "invalid username")
}
func (u *User) GetByUsername(ctx context.Context, username string) (*dto.User, error) {
user, err := u.usersRepo.GetByUsername(ctx, username)
if err != nil {
return dto.User{}, err
return nil, err
}
return *user, nil
return user, nil
}