forked from mtusi2026/mtusi2026lab2
370 lines
58 KiB
Markdown
370 lines
58 KiB
Markdown
# Отчёт — лабораторная 2: PostgreSQL, сессии и Redis
|
||
|
||
- Автор: Поликарпов Даниил Александрович. Группа: БПИ2303.
|
||
- Дата оформления: 6 ноября 2026 года.
|
||
- Выбранный эксперимент уровня «5»: трек 1, cache stampede — одновременные промахи кэша.
|
||
- Базовый commit: `711754bbcd6e47a7b83d7f5c922f5f37f6bc0764`. Реализация и эксперименты относятся к изменённому рабочему дереву поверх этого commit; сам commit не содержит всех описанных изменений. Ссылка на PR не предоставлена.
|
||
- ChatGPT/Codex использовался для доработок Redis/singleflight, исправлений конфигурации и обработки отказов, подготовки сценариев проверки и отчёта. Версии библиотек закреплены в [go.mod](service/go.mod); источники и исходные результаты приведены ниже.
|
||
|
||
Цель работы — перенести пользователей, чаты, участников, сообщения и сессии в PostgreSQL, заменить идентификацию через `X-User-Id` аутентификацией и использовать Redis как необязательный кэш. Завершён эксперимент с защитой от повторных SQL-чтений при наплыве запросов. На исправленной сборке выполнен отдельный автоматизированный прогон требований уровней «3» и «4»: все 16 групп проверок прошли. Доказательства находятся в [evidence/levels-3-4](evidence/levels-3-4/README.md). Эксперимент трека «5» сохранён как результат предшествующей сборки; итоговая оценка остаётся предметом проверки преподавателя.
|
||
|
||
## 1. Запуск из чистого clone
|
||
|
||
### 1.1. Предварительные условия и версии
|
||
|
||
Нужны 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 |
|
||
|
||
Команды этого раздела — инструкция воспроизведения основного стенда. Сборка, миграции и проверки выполнены автоматически на отдельном изолированном Compose-проекте; основной стенд не перезапускался. Реальные результаты находятся в разделе 3 и evidence/levels-3-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` включены миграции Tern, добавлены SESSION_TTL_SECONDS=3600, лимит пула и таймауты PostgreSQL. Для существующего `.env` нужно проверить реквизиты и включение миграций. Если SESSION_TTL_SECONDS отсутствует или пуст, используется прежний JWT_REFRESH_TOKEN_LIFETIME; если обе переменные не заданы — один час. Новая переменная имеет приоритет и проверяется как положительное целое число секунд.
|
||
|
||
Для описанного 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. Чистый первый запуск применил все пять миграций. Повторный запуск сохранил версию 5 и количества строк всех таблиц без изменений; результаты приведены в summary.json проверки уровней 3/4.
|
||
|
||
Compose ожидает здоровый PostgreSQL перед запуском API. Redis является необязательной зависимостью по доступности: API не зависит от его healthcheck и продолжает запуск при ошибке стартового PING. При этом конфигурационные реквизиты Redis, включая пароль для Compose, всё равно должны быть заданы.
|
||
|
||
`/health/live` отражает жизнь HTTP-процесса. `/health/ready` проверяет флаг HTTP-сервера и PING PostgreSQL с бюджетом 200 мс; при недоступной БД возвращает 503. Redis в readiness не участвует. Проверено: при остановленной БД liveness=200, readiness=503, после запуска БД readiness вновь 200.
|
||
|
||
Для диагностики использовать выборочные журналы; полный вывод конфигурации с секретами в отчёт не сохранять:
|
||
|
||
```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. Существующие публичные проверки выполнены без изменений; `make check`, `make test` и полный `make test-persistence` завершились с exit code 0. Реальный вывод сохранён в [checks.txt](evidence/levels-3-4/checks.txt). Новые unit-тесты не добавлялись; дополнительные сценарии автоматизированы в отдельном runner.
|
||
|
||
Повторить проверку всех критериев на отдельном стенде, сохранив новый прогон отдельно:
|
||
|
||
```sh
|
||
python3 scripts/verify_lab2.py --port 18084 --output evidence/levels-3-4-repeat
|
||
```
|
||
|
||
Runner сам создаёт проект, ключи, пароли и volumes. Restart-hook поддерживает COMPOSE_PROJECT_NAME, COMPOSE_ENV_FILE и COMPOSE_OVERRIDE_FILE; он не генерирует ключи заново. После проверки отдельный стенд остановлен, его volumes сохранены, основной проект не затрагивается.
|
||
|
||
Обычная остановка сохраняет именованные 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` | Применяется к `pgxpool.MaxConns`; по умолчанию 10. Проверен лимит 2 при восьми параллельных запросах |
|
||
| `POSTGRES_CONNECT_TIMEOUT`, `POSTGRES_QUERY_TIMEOUT` | По умолчанию 500 мс и 2 с; connect timeout, statement_timeout соединений и общий контекст бизнес-запроса |
|
||
| `REDIS_HOST`, `REDIS_PORT`, `REDIS_USERNAME`, `REDIS_PASSWORD`, `REDIS_DB` | Подключение к Redis; время операций ограничено константами в коде, отдельных env-переменных таймаутов нет |
|
||
| `JWT_REFRESH_TOKEN_LIFETIME` | Legacy fallback срока Bearer-сессии, если SESSION_TTL_SECONDS не задан; при отсутствии обеих переменных — 3600 секунд |
|
||
| `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` | Основной срок сессии в положительных целых секундах; пример окружения задаёт 3600, проверено значение 2 и приоритет над legacy |
|
||
| `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, отказ PostgreSQL и полный рестарт всех сервисов с сохранением данных и прежней сессии на изолированном стенде.
|
||
|
||
По сравнению с lab1 идентификация через `X-User-Id` заменена входом по паролю и серверной сессией. Состояние перенесено в PostgreSQL; добавлены постоянные volumes и кэш. Обязательный публичный smoke прошёл; его вывод сохранён, дополнительно проверены 14 отрицательных случаев валидации.
|
||
|
||
### 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. Rollback проверен запросом с существующим создателем и неизвестным участником: после успешного INSERT чата FK второго INSERT нарушается; ответ 400, частичных строк нет, количества всех таблиц совпадают с исходными.
|
||
|
||
Создание сообщения — один параметризованный 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 с новым случайным nonce из 32 байт crypto/rand; клиент передаёт его как непрозрачную строку и не должен разбирать 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, чтобы не раскрывать наличие чужого ресурса. Публичный smoke подтвердил вход, logout, неверный пароль, отказ Basic на бизнес-endpoint и запрет подмены через X-User-Id. Дополнительно проверены expiry с SESSION_TTL_SECONDS=2, изменённая подпись JWT и неизвестный пользователь. Прежние сессии сохраняют свой expires_at; nonce не стал обязательным для старых JWT.
|
||
|
||
### 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` соответствует фильтрации чата и порядку выдачи. На истории из 20 001 сообщения первая и глубокая страницы проверены EXPLAIN (ANALYZE, BUFFERS): обе используют этот индекс без Seq Scan. Полный обход через API вернул все ID в правильном порядке без потерь и дублей. Текст и JSON планов находятся в evidence/levels-3-4.
|
||
|
||
После подтверждённого 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-запроса. Бизнес-запросы дополнительно ограничены POSTGRES_QUERY_TIMEOUT=2s, этот же бюджет установлен как statement_timeout на соединениях приложения. Отдельный контекст singleflight не зависит от отмены одного клиента и остаётся ограниченным двумя секундами. Ошибки доступности и deadline возвращаются как 503 unavailable, не раскрывая детали подключения.
|
||
|
||
Диагностика: `chat_cache_hit`, `chat_cache_miss`, `chat_cache_read_error`, `chat_db_lookup`; ошибки заполнения кэша записываются как `failed to cache chat`. Отсутствие `chat_db_lookup` означает экономию чтения чата, но не отсутствие SQL проверки сессии.
|
||
|
||
## 3. Соответствие критериям лабораторной
|
||
|
||
Итоговая приёмка уровней «3» и «4» выполнена на исправленной сборке: **16/16 групп PASS**. Период, commit рабочего дерева, image ID и SHA-256 исходников приведены в [методике](evidence/levels-3-4/README.md) и [summary.json](evidence/levels-3-4/summary.json). Основной работающий Compose-проект не перезапускался. Проверки подтверждают перечисленные сценарии и не являются доказательством отсутствия любых ошибок.
|
||
|
||
| Уровень / критерий README | Что выполнено | Фактический результат | Доказательство |
|
||
| --- | --- | --- | --- |
|
||
| 3: минимум lab1 и переход на новую аутентификацию | Публичный smoke и 14 дополнительных отрицательных случаев | PASS: данные, членство, сообщения, пагинация, ошибки; неверный UUID — 400 | [stdout](evidence/levels-3-4/checks.txt), [HTTP](evidence/levels-3-4/http.csv) |
|
||
| Постоянные данные и сессии после рестарта API и всех хранилищ | Публичный persistence с настоящим restart-hook | PASS: все три ID контейнеров изменились; volumes, подтверждённые данные и прежняя сессия сохранены | `full_persistence` в [summary](evidence/levels-3-4/summary.json) |
|
||
| PostgreSQL: таблицы, PK/FK, уникальный username | Миграции новой пустой БД и проверка pg_catalog | PASS: пять миграций, четыре FK, PK и unique; операции API работают | [schema.txt](evidence/levels-3-4/schema.txt) |
|
||
| Миграции с нуля и повтор без дублей | Чистые volumes, затем повторный запуск | PASS: версия 5 и количества строк не изменились | `repeat_migrations` в [summary](evidence/levels-3-4/summary.json) |
|
||
| Атомарное создание чата | FK-ошибка участников после INSERT чата | PASS: 400, чат и частичные участники отсутствуют, количества таблиц прежние | `chat_creation_rollback` в [summary](evidence/levels-3-4/summary.json) |
|
||
| Basic только для входа, Bearer на бизнес-запросах | Публичный smoke | PASS: вход 201; Basic на private endpoint — 401 | [stdout](evidence/levels-3-4/checks.txt) |
|
||
| X-User-Id не даёт доступ | Публичный smoke | PASS: без Bearer — 401; дополнительный заголовок не меняет Bearer-пользователя | [stdout](evidence/levels-3-4/checks.txt) |
|
||
| Expiry, отзыв сессии и KDF | Smoke, короткий TTL, проверка алгоритма БД | PASS: logout/reuse — 401; TTL 2 с истекает; Argon2id m=65536,t=3,p=4; новый nonce 32 байта | [summary](evidence/levels-3-4/summary.json) |
|
||
| make check, make test, make test-persistence | Запуск неизменённых публичных сценариев | PASS: все три команды exit_code=0, реальный вывод сохранён | [checks.txt](evidence/levels-3-4/checks.txt) |
|
||
| Secrets и volumes вне Git | Аудит текущего tracked tree и новых материалов | PASS: env/ключи/volumes не отслеживаются, JWT и приватных ключей в материалах нет; полная история Git не сертифицировалась | `tracked_secrets_and_contract_audit` в [summary](evidence/levels-3-4/summary.json) |
|
||
| 4: осмысленный Redis-кэш, источник истины, expiry/инвалидация | Miss → DB → hit, проверка членства; политика раздела 2.5 | PASS: один lookup при холодном/повторном GET; посторонний — 404; PostgreSQL — источник истины | [summary](evidence/levels-3-4/summary.json), [первая демонстрация](evidence/redis-cache.md) |
|
||
| Параметризованный SQL, ограниченный pool и таймауты | Пул 2 при восьми параллельных запросах и заблокированный SQL | PASS: максимум 2 соединения; 503 примерно за 2 с; основной лимит восстановлен к 10 | [summary](evidence/levels-3-4/summary.json), [startup](evidence/levels-3-4/startup.txt) |
|
||
| Гонка регистрации username | Восемь одновременных POST одного username | PASS: один 201, семь 409, одна строка БД | `username_registration_race` в [summary](evidence/levels-3-4/summary.json) |
|
||
| Rollback составной операции | Создание чата с неизвестным участником | PASS: ошибка второго INSERT не оставляет данных первого | `chat_creation_rollback` в [summary](evidence/levels-3-4/summary.json) |
|
||
| Индекс истории и EXPLAIN на ≥10 000 сообщений | 20 001 сообщение; первая и глубокая страницы | PASS: Limit → Index Scan, без полного scan; 101 запись в каждом плане | [Первая](evidence/levels-3-4/explain-first.txt), [глубокая](evidence/levels-3-4/explain-deep.txt) |
|
||
| Пагинация истории | Полный обход API страницами по 100 | PASS: все 20 001 ID в порядке, без пропусков и дублей | `history_20000_and_explain` в [summary](evidence/levels-3-4/summary.json) |
|
||
| Автоматические expiry при SESSION_TTL_SECONDS, logout, неверный пароль | Изолированный runner и публичный smoke | PASS: SESSION TTL имеет приоритет, 200 → 401; logout и неверный пароль отклоняются | [Сценарий](scripts/verify_lab2.py), [summary](evidence/levels-3-4/summary.json) |
|
||
| Недоступность Redis/БД, отсутствие анонимного доступа при отказе | Stop/start отдельных сервисов проверочного проекта | PASS: без Redis — 200; без PostgreSQL действующая сессия — 503, анонимный/неверный токен — 401; после старта данные доступны | [summary](evidence/levels-3-4/summary.json), [HTTP](evidence/levels-3-4/http.csv) |
|
||
| Контракт и публичные tests не ослаблены | Сравнение с upstream/master | PASS: README задания, contracts и tests не изменены | `tracked_secrets_and_contract_audit` в [summary](evidence/levels-3-4/summary.json) |
|
||
| 5, трек 1: stampede, защита, SQL/latency до и после | Исторический эксперимент 10 × 32 GET | PASS на идентифицированной предшествующей сборке: SELECT чата 308 → 10, ошибок нет | [Методика и результаты](evidence/cache-stampede/README.md) |
|
||
| Read-after-write и Redis restart выбранного трека | Создание сообщения, чтение другим участником, рестарт кэша | Подтверждено историческим экспериментом; сохранность после полного рестарта дополнительно проверена итоговой приёмкой | [Трек 1](evidence/cache-stampede/summary.json), [приёмка](evidence/levels-3-4/summary.json) |
|
||
|
||
Трек 2 с ≥100 000 сообщений и backup → restore не выбран; его выполнение не требуется для выбранного трека и не заявляется.
|
||
|
||
## 4. Эксперименты и отказы
|
||
|
||
Разделы 4.1–4.4 сохраняют результаты предшествующих сборок. Исправления и итоговая проверка уровней 3/4 выполнены позже на отдельном стенде; они описаны в разделе 4.5. Старые численные результаты не пересчитывались и не выдаются за измерения новой сборки.
|
||
|
||
### 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. Дополнительные сценарии и границы восстановления
|
||
|
||
| Воздействие / сценарий | Ожидаемое поведение | Фактический результат | Границы вывода |
|
||
| --- | --- | --- | --- |
|
||
| Смешанный холодный наплыв: два участника и посторонний | 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 | Отказ обязательного пути без обхода аутентификации | В исходном stampede-эксперименте не проверялся; позже подтверждён в разделе 4.5 | Актуальный readiness возвращает 503; RTO потери хоста не измерялся |
|
||
| Полный рестарт всех сервисов / потеря хоста или диска | Сохранность / аварийное восстановление | Полный рестарт позже подтверждён persistence; потеря диска не исследовалась | RPO/RTO потери хоста и backup → restore не измерены |
|
||
|
||
Оба эксперимента завершились с работающими API, PostgreSQL и Redis; итоговые healthy-состояния записаны в приложенных журналах. Это наблюдение на момент эксперимента, а не текущая непрерывная гарантия доступности. Обязательные данные и volumes не удалялись. Синтетические учётные записи и данные экспериментов остаются на локальном стенде.
|
||
|
||
### 4.5. Итоговая приёмка уровней «3» и «4»
|
||
|
||
Прогон 2026-11-06T10:43:16.282804Z — 2026-11-06T10:44:52.582387Z UTC завершился PASS во всех 16 группах. Образ: `sha256:0effe11ab9f4d860b5b79d6096ff95325336c752c0d5ca335878ec89baf4f269`, SHA-256 исходников: `11bd17ca0b86a6db845ec7c2954c91fd8a870e1999ca45d708a546f0f863fb0e`. Точный состав хэшируемых файлов, параметры, проект и stdout сохранены в [evidence/levels-3-4](evidence/levels-3-4/README.md).
|
||
|
||
Включены миграции с нуля и повтор, публичные check/smoke/persistence, реальное пересоздание трёх контейнеров с прежними volumes, KDF/случайность JWT, совместимость TTL и ошибки конфигурации, 14 отрицательных случаев контракта, гонка username, rollback, 20 001 сообщение и EXPLAIN, короткое expiry, отказ Redis/PostgreSQL, pool limit и SQL deadline.
|
||
|
||
При отказе Redis GET дал 200 за 62.898 мс. При отказе PostgreSQL — 503 за 2.511 мс, readiness — 503 за 10.516 мс; анонимный и неверный Bearer получили 401, liveness остался 200. После старта БД прежняя сессия вновь работала. При пуле 2 восемь заблокированных запросов завершились 503 за 2005.983–2008.694 мс; после освобождения блокировки и возврата пула к 10 работа восстановлена.
|
||
|
||
Для EXPLAIN первая и глубокая страницы вернули по 101 записи через индекс; Execution Time — 0.04 и 0.082 мс соответственно. Полный обход API дал все 20 001 сообщений в порядке. Это измерения конкретных запросов на синтетических данных, не универсальный SLA.
|
||
|
||
Проверочный проект остановлен без удаления volumes; локальные секреты находятся вне Git. Основной работающий стенд на 8080 не перезапускался. Исправленная сборка проверена на 18084; для применения изменений к основному стенду его API нужно отдельно пересобрать и пересоздать обычной командой запуска.
|
||
|
||
## 5. Ограничения и дальнейшая работа
|
||
|
||
Обязательные сценарии уровней «3» и «4» теперь имеют реальные успешные результаты. Исправлены SESSION_TTL_SECONDS с совместимым fallback, применение MaxConns, connect/query timeouts, обработка недоступности БД через 503, PostgreSQL readiness, безопасное закрытие мигратора, случайный nonce JWT и HTTP 400 для ошибок валидации. Пример окружения и restart-hook приведены к актуальному запуску.
|
||
|
||
Остаются границы проведённых исследований:
|
||
|
||
1. Проверки выполнены с одной API-репликой. Singleflight объединяет только одинаковую пару «чат + пользователь» внутри процесса; распределённой защиты нет.
|
||
2. Кэш не имеет TTL и автоматической инвалидации. Обязательный API не изменяет членство; будущие изменения состава участников должны сопровождаться отдельной политикой согласованности.
|
||
3. При отказе PostgreSQL авторизованный API не работает независимо от заполненного Redis: серверная сессия проверяется в БД. Это корректный 503, а не режим автономной работы.
|
||
4. Исследованы stop/start и пересоздание контейнеров с сохранением volumes. Потеря питания/диска, HA, сетевой blackhole и backup → restore не исследовались, их RPO/RTO не заявляются.
|
||
5. Старый stampede-эксперимент относится к предшествующей сборке. Его сравнение и ограничения сохранены; его цифры нельзя выдавать за производительность новой конфигурации пула.
|
||
6. Локальный HTTP и PostgreSQL sslmode=disable предназначены для учебного стенда. TLS и production hardening не входят в выполненную проверку.
|
||
7. Аудит секретов охватил текущее отслеживаемое дерево и новые материалы; полная история Git отдельно не сертифицировалась. Публичный smoke также не является полным fuzz/security suite.
|
||
|
||
Доказанная экономия чтений чата не устраняет SELECT и bcrypt-проверку сессии на каждом запросе. Значения задержек в evidence — наблюдения данного стенда; автоматические сценарии и серверные таймауты дают проверяемые ограничения для исследованных отказов, а не универсальные гарантии доступности.
|
||
|
||
## 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).
|
||
- [Приёмка уровней 3/4](evidence/levels-3-4/README.md), [runner](scripts/verify_lab2.py).
|
||
- [Эксперимент кэша и отказа 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/).
|
||
|
||
При актуализации отчёта исправлена реализация и выполнена отдельная приёмка уровней 3/4; старые материалы экспериментов сохранены. Авторские данные и существующие пользовательские изменения сохранены. Ссылки, числа и исходники сверяются с evidence; новые unit-тесты не добавлялись, публичные tests и контракт не изменялись.
|