Заполнить отчёт и доказательства лабораторной 2

This commit is contained in:
2026-10-06 16:05:24 +03:00
parent 949622ed93
commit 956b84f2d7
10 changed files with 400 additions and 29 deletions
+14 -14
View File
@@ -1,18 +1,18 @@
## Лабораторная 2
Автор / группа: TODO
Целевая оценка (3/4/5): TODO
Трек 5, если заявлен: TODO
Автор / группа: Бакулин, БПИ2301
Целевая оценка (3/4/5): 4
Трек 5, если заявлен: не заявлен
Что реализовано и что перенесено: TODO
Команды запуска из чистого clone: TODO
Результаты проверок и ссылка на REPORT.md: TODO
Ограничения / известные ошибки: TODO
Источники и использование ИИ: TODO
Что реализовано и что перенесено: перенесён минимум lab1 (формат ошибок, keyset-пагинация, UUIDv7, graceful shutdown). Пользователи, чаты, участники и сообщения хранятся в PostgreSQL 18 (pgx, миграции goose при старте, атомарное создание чата). Регистрация с паролем (Argon2id), вход через Basic, непрозрачный Bearer-токен, сессии в Valkey с AOF `appendfsync always` и абсолютным сроком, logout. Недоступность PostgreSQL или Valkey даёт 503 с причиной в логе. Стенд в compose с secrets, хук перезапуска, EXPLAIN истории. Подробности и исправления базы lab1 — в REPORT.md.
Команды запуска из чистого clone: `make secrets && make up`, затем `make test`, `make test-persistence ACTION_SCRIPT=scripts/restart.sh`, `make unit` (нужен Docker), `make explain`; удаление данных — `make destroy`.
Результаты проверок и ссылка на REPORT.md: REPORT.md, раздел «Доказательства критериев»; файлы в `evidence/`.
Ограничения / известные ошибки: один host без репликации; потеря Valkey разлогинивает всех; без TLS (lab7); описание семантики пагинации при конкурентных вставках — в REPORT.md.
Источники и использование ИИ: перечислены в REPORT.md. ИИ-ассистент использовался как парный программист: генерация кода, тестов и черновиков документации по моим архитектурным решениям с последующим ревью каждого модуля и переработкой по замечаниям; выбор стека, структура проекта, модель данных, обработка ошибок, логирование и границы модулей определены мной; все проверки воспроизведены мной вручную.
- [ ] Весь обязательный минимум текущей и предыдущих работ сохранён с объявленными переходами.
- [ ] Контракт и публичные тесты не ослаблены.
- [ ] make check и make test выполнены; приложен реальный вывод.
- [ ] Сценарии отказов/безопасности своего уровня воспроизведены.
- [ ] Все секреты и приватные ключи находятся вне Git; отчёт не содержит tokens.
- [ ] README задания сохранён, REPORT.md содержит инструкцию именно моего решения.
- [x] Весь обязательный минимум текущей и предыдущих работ сохранён с объявленными переходами.
- [x] Контракт и публичные тесты не ослаблены.
- [x] make check и make test выполнены; приложен реальный вывод.
- [x] Сценарии отказов/безопасности своего уровня воспроизведены.
- [x] Все секреты и приватные ключи находятся вне Git; отчёт не содержит tokens.
- [x] README задания сохранён, REPORT.md содержит инструкцию именно моего решения.
+129 -15
View File
@@ -1,37 +1,151 @@
# Отчёт — лабораторная 2
- Автор, группа: TODO
- Целевая оценка; выбранный трек 5, если нужен: TODO
- Commit/PR: TODO после публикации
- Использованные источники, библиотеки и помощь ИИ: TODO
- Автор, группа: Бакулин, БПИ2301
- Целевая оценка; выбранный трек 5, если нужен: 4. Уровни 3 и 4 выполнены полностью, трек 5 не заявлен.
- Commit/PR: ветка `solution/bpi2301-bakulin`; ссылка на PR — после публикации.
- Использованные источники, библиотеки и помощь ИИ: документация PostgreSQL 18 (транзакции, EXPLAIN, `uuidv7`, типы даты/времени), PostgreSQL wiki «Don't Do This», документация Valkey (persistence, ACL/requirepass, eviction), RFC 7617 (Basic), RFC 6750 и RFC 7235 (Bearer, `WWW-Authenticate`), RFC 9106 и OWASP Password Storage Cheat Sheet (Argon2id), документация Docker Compose (secrets, healthcheck, `depends_on`). Библиотеки: `github.com/gin-gonic/gin` v1.12.0, `github.com/google/uuid` v1.6.0, `github.com/jackc/pgx/v5` v5.11.0 (драйвер и пул), `github.com/pressly/goose/v3` v3.27.0 (миграции), `github.com/redis/go-redis/v9` v9.23.0 (клиент Valkey), `golang.org/x/crypto/argon2`, в тестах `github.com/testcontainers/testcontainers-go` v0.39.0. ИИ-ассистент использовался как парный программист: генерация кода, тестов и черновиков документации по моим архитектурным решениям с последующим ревью каждого модуля и переработкой по замечаниям; выбор стека, структура проекта, модель данных, обработка ошибок, логирование и границы модулей определены мной; все проверки воспроизведены мной вручную.
## Запуск из чистого clone
TODO: версии runtime/образов, prerequisites, команды создания локальных secrets/.env, build, миграций, запуска, ожидания готовности, тестов и остановки. Указать необходимые действия оператора. Не вставлять секреты. Отдельно указать безопасную остановку и команду намеренного удаления учебных данных.
Версии, на которых выполнялись проверки: Go 1.27.1 (`go.mod`), Docker Desktop 28.5.1 с Compose v2 (нужен 2.24+ из-за `env_file … required: false`), Python 3.13 для публичных проверок (нужен 3.9+), GNU Make. Образы закреплены digest'ами: `postgres:18.6-alpine3.24`, `valkey/valkey:9.1.2-alpine3.24` в `compose.yaml`, `golang:1.27.1-alpine3.23` и `alpine:3.23` в `Dockerfile`.
```sh
make secrets # ./secrets: пароли PostgreSQL и Valkey и URL для API; существующие файлы не перезаписываются
make up # docker compose up -d --build --wait: postgres и valkey healthy → api применяет миграции → healthy
make check PYTHON=python
make test PYTHON=python
make test-persistence ACTION_SCRIPT=scripts/restart.sh PYTHON=python # на Windows: ACTION_SCRIPT=scripts/restart.cmd
make unit # собственные тесты; нужен запущенный Docker: тесты поднимают свои PostgreSQL и Valkey
make explain > evidence/explain-history.txt
make concurrency # 10 клиентов × 10 сообщений, отчёт в evidence/concurrency.json
```
`.env` не обязателен: все настройки имеют значения по умолчанию, а пути к секретам задаёт `compose.yaml`. Если порт 8080 занят — `PUBLISH=127.0.0.1:18080 make up` и `BASE_URL=http://localhost:18080` для проверок. Короткий TTL для проверки истечения: `SESSION_TTL_SECONDS=2 make up` (Compose пересоздаст только api; вернуть — `make up`).
Секреты. `scripts/init-secrets.sh` создаёт в `./secrets` (каталог в `.gitignore` и `.dockerignore`) четыре файла: пароль PostgreSQL, DSN для API, `requirepass` для Valkey и URL Valkey для API. Compose монтирует их как secrets в `/run/secrets/*`; API читает их через `DATABASE_URL_FILE` и `SESSION_STORE_URL_FILE`, PostgreSQL — через `POSTGRES_PASSWORD_FILE`, Valkey — через `include` в `infra/valkey/valkey.conf`. Значения секретов не попадают ни в env контейнера (`docker inspect`), ни в образ, ни в логи. Скрипт не перезаписывает существующие файлы: PostgreSQL применяет пароль только при инициализации volume, новый пароль при живом volume заблокировал бы API.
Bootstrap и миграции. Схема — `migrations/00001_init.sql`, вшита в бинарник через `embed`. API при старте до открытия порта применяет миграции goose под session advisory lock (несколько реплик в lab3 сериализуются на нём), в логе `schema ready applied_migrations=[1]`, повторный старт — `applied_migrations=[]`. Отдельного шага оператора нет.
Остановка и удаление данных. `docker compose stop` — graceful остановка всех трёх процессов (API дорабатывает запросы, PostgreSQL пишет checkpoint, Valkey дописывает AOF); `make down` — удалить контейнеры с сохранением volumes; `make destroy` (`docker compose down -v`) — **намеренное удаление всех учебных данных**: пользователей, чатов, сообщений и сессий. Для полного сброса затем удалить `./secrets`.
## Архитектура и решения
TODO: схема процессов/хранилищ, источник истины, транзакционные границы, ограничения. Что перенесено из lab1, что изменено в этой работе. Соответствие переменных из .env.example реальной конфигурации.
```
клиент ──HTTP──> api (Go, gin) ──pgx pool (≤10)──> postgres [volume pgdata] users, chats, chat_members, messages
└─go-redis (≤10)──> valkey [volume valkeydata] session:<sha256(token)> → user_id
```
Источник истины: PostgreSQL — для пользователей, чатов, участников и сообщений; Valkey — единственное хранилище сессий и, значит, их источник истины (кэша в работе нет). Обе зависимости критичны для синхронного пути: без Valkey нельзя аутентифицировать ни один запрос, без PostgreSQL — прочитать или записать данные. `/health/ready` проверяет обе (общий бюджет 1 с) и флаг shutdown; `/health/live` — только процесс.
Модель данных (`migrations/00001_init.sql`). В схеме только модель данных — `NOT NULL`, PK, FK, `UNIQUE`; правила валидации (форматы, длины) живут в приложении и в БД не дублируются. Время — `timestamptz` (момент времени, в UTC по построению), `created_at` пишет приложение из UUIDv7 id, поэтому порядок `(created_at, id)` совпадает с порядком id.
| Таблица | Ключи и индексы | Зачем |
| --- | --- | --- |
| users | PK id, `users_username_key UNIQUE (username)` | уникальность username держит constraint, поэтому гонка регистраций безопасна |
| chats | PK id | |
| chat_members | PK (chat_id, user_id), индекс (user_id, chat_id), FK на chats и users | членство и состав чата; список чатов пользователя keyset-ом по второму индексу |
| messages | PK (chat_id, id), FK на chats и users | ключ и есть индекс истории: `WHERE chat_id=$1 AND id>$2 ORDER BY id LIMIT $3` |
Ключ сообщений — `(chat_id, id)`, отдельного индекса по id нет. Сообщение по одному id API не ищет, а такой индекс стоил бы записи и, как показал EXPLAIN на 102 000 сообщений, уводил планировщик в обход всех сообщений по порядку id с фильтром по чату (15 303 отброшенные строки и 1092 буфера на первой странице). Цена: уникальность id гарантирована внутри чата; id генерирует сервер (UUIDv7, 74 случайных бита), коллизия практически исключена. Время диапазоном тоже не требует отдельного индекса: UUIDv7 содержит время, интервал `[t1, t2)` превращается в диапазон id по тому же ключу.
Транзакционные границы. Регистрация — один `INSERT`, `23505` по `users_username_key` даёт 409. Создание чата — одна транзакция: `INSERT chats` и `INSERT chat_members … unnest($2::uuid[])`; существование участников проверяется до транзакции одним batch-запросом (400 на неизвестного), FK остаётся страховкой. Отправка сообщения — проверка членства и один `INSERT`. Чтения — одиночные `SELECT` на `READ COMMITTED`. Ограничение (contracts/README:20): id выдаётся до `INSERT`, поэтому коммиты конкурентных отправок могут лечь не в порядке id; читатель, чей cursor уже прошёл больший id, не увидит «опоздавшее» сообщение при продолжении обхода, при чтении с начала оно стоит на своём месте, повторов нет.
Аутентификация (`internal/auth`). `POST /api/v1/auth/sessions` принимает только `Authorization: Basic` (`Request.BasicAuth` делит строку по первому двоеточию, так что двоеточие в пароле допустимо). Неизвестный пользователь, неверный пароль, username с NUL или не-UTF-8 дают одинаковый 401 с `WWW-Authenticate: Basic realm="messenger", charset="UTF-8"`; для неизвестного username всё равно выполняется KDF на фиктивном хеше, чтобы время ответа не выдавало существование пользователя. Успех — `201 {token, token_type: "Bearer", expires_at, user}`. Токен — 32 случайных байта в base64url (256 бит), непрозрачный. В Valkey хранится ключ `session:<sha256(token)>` со значением user_id и абсолютным сроком (`SET … PXAT/EXAT`): утечка AOF не даёт рабочих токенов, а рестарт не продлевает сессию. Все остальные endpoint'ы требуют `Authorization: Bearer <token>` (схема без учёта регистра); отсутствие, Basic, неизвестный, истёкший или отозванный токен — 401 с `WWW-Authenticate: Bearer realm="messenger"`. `X-User-Id` не читается вообще. `DELETE /api/v1/auth/sessions/current` удаляет ключ и отвечает 204, повтор — 401. Срок жизни задаёт `SESSION_TTL_SECONDS` и фиксируется при входе; скользящего продления нет, иначе `expires_at` в ответе был бы ложью. Пароли — Argon2id (`m=19 MiB, t=2, p=1`, соль 16 байт) в PHC-строке; параметры читаются из строки, поэтому их можно поднять без инвалидации старых хешей.
Valkey (`infra/valkey/valkey.conf`): `appendonly yes`, `appendfsync always` — запись сессии подтверждается после fsync, как COMMIT в PostgreSQL; пишут только вход и выход, чтение сессии fsync не трогает. `save ""` — RDB не нужен рядом с AOF. `maxmemory 256mb` с `noeviction` — сессии никогда не вытесняются: при заполнении новые входы получают 503, а не молча разлогинивают пользователей. Пароль Valkey задан: иначе любой процесс в docker-сети мог бы записать `session:<sha256(своего токена)>` и подделать сессию.
Отказы и таймауты. Пул PostgreSQL ограничен 10 соединениями, `statement_timeout=5s`, `idle_in_transaction_session_timeout=10s`, подключение и поиск имени хоста — 1 с. Клиент Valkey: пул 10, дозвон 1 с одной попыткой, чтение и запись 1 с, повторы команд выключены. Каждый запрос к `/api` ограничен дедлайном 5 с (меньше `WriteTimeout` сервера 10 с, чтобы 503 успел записаться). Недоступность зависимости (отказ соединения, таймаут, классы ошибок PostgreSQL 08/53/57) превращается в `503 unavailable`; клиенту уходит только безопасное сообщение (`database unavailable`, `session store unavailable`), причина пишется в лог строкой `request failed` с `request_id` и `cause`. Аноним при недоступном Valkey не пропускается: ответ 503, а не 401 и не 200. Регистрация от Valkey не зависит и продолжает работать.
Код и что изменилось относительно lab1:
```
cmd/server конфигурация, пул PostgreSQL, миграции, клиент Valkey, listener, сигналы
migrations/ SQL-миграции goose, вшиты в бинарник
internal/app composition root (Deps: пул, клиент Valkey, TTL, таймаут запроса)
internal/server http.Server и graceful shutdown; принимает http.Handler и флаг readiness
internal/auth session.go, repository.go, service.go, handler.go, middleware.go; store/valkey.go
internal/user + пароль и Authenticate; store/postgres.go (inmem удалён)
internal/chat участники в каноническом порядке по id; store/postgres.go (inmem удалён)
internal/health live/ready с проверками зависимостей
internal/platform/ config (+ *_FILE, SESSION_TTL_SECONDS), postgres (пул, Migrate, Classify),
valkey (клиент), password (Argon2id), httpx (+ WithUser, Timeout), apperr, ident, pagination
internal/testenv PostgreSQL и Valkey в testcontainers для тестов; в бинарник не входит
tools/concurrency чёрный ящик гонок, теперь с паролем и Bearer
```
Перенесено из lab1 без изменений: формат ошибок и `X-Request-Id`, keyset-пагинация и cursor, UUIDv7 и вывод `created_at` из id, access log по уровням, graceful shutdown. Изменено по объявленному переходу 1 → 2: регистрация требует `password`, `X-User-Id` заменён Bearer-сессией, Basic только на входе. Исправления базы: `WithUser` переехал из `auth` в `httpx` (иначе цикл импортов `auth ↔ user`), `server.Run` больше не зависит от сборки приложения, `member_ids` всегда в порядке id (контракт считает их множеством). Удалены in-memory хранилища и сценарий `student-tests/lifecycle.sh` (он проверял потерю данных после рестарта — в lab2 нужно обратное, это проверяет `make test-persistence`).
Тесты. Сервисы, хранилища и HTTP тестируются против настоящих PostgreSQL и Valkey (testcontainers-go, один контейнер на пакет, `TRUNCATE` всех таблиц и `FLUSHDB` перед каждым тестом); чистая логика (валидация, cursor, конфигурация, Argon2id) — обычными юнит-тестами. testcontainers закреплён на v0.39.0: с v0.40 он запрашивает публикацию порта с `HostPort "0"`, которую Docker Desktop 28.5.1 на Windows не выполняет; goose — на v3.27.0 из-за совместимости транзитивной зависимости с этой версией.
Соответствие `.env.example` реальной конфигурации:
| Переменная | `.env.example` | Реализация | По умолчанию |
| --- | --- | --- | --- |
| APP_HOST, APP_PORT, APP_ENV | да | как в lab1 | 0.0.0.0, 8080, lab |
| SESSION_TTL_SECONDS | да | срок сессии, целое > 0 | 3600 |
| DATABASE_URL_FILE | да | файл с DSN PostgreSQL, обязателен | `/run/secrets/database_url` в compose |
| SESSION_STORE | да (`postgres`) | не читается: сессии всегда в Valkey | — |
| CACHE_URL_FILE | да | не используется: кэша нет; имя оставлено для кэша, если он появится | — |
| SESSION_STORE_URL_FILE | нет | файл с URL Valkey, обязателен | `/run/secrets/session_store_url` в compose |
| APP_LOG_LEVEL, APP_SHUTDOWN_TIMEOUT, APP_MAX_BODY_BYTES | нет | как в lab1 | info, 8s, 65536 |
Ошибка в любой переменной или нечитаемый файл секрета останавливают процесс на старте с кодом 2; сообщение называет переменную, но не значение.
Роли стенда:
| Роль | Сервис | Версия | Health/readiness | Volume | Сеть/порт | Credentials |
| --- | --- | --- | --- | --- | --- | --- |
| api | api (`mtusi-messenger-lab2`) | сборка из исходников | `/health/ready` (PG + Valkey) | — | `127.0.0.1:8080` | secrets `database_url`, `session_store_url` |
| postgres | postgres | 18.6-alpine3.24 @digest | `pg_isready -h 127.0.0.1` | `pgdata:/var/lib/postgresql` | только внутренняя сеть | secret `postgres_password` |
| redis_or_valkey | valkey | 9.1.2-alpine3.24 @digest | `valkey-cli ping` с паролем | `valkeydata:/data` (AOF) | только внутренняя сеть | secret `valkey_auth` |
CI. `.github/workflows/app.yml`: unit-тесты с race detector (на runner нужен Docker для testcontainers), затем `make secrets`, `docker compose up --build --wait`, smoke, persistence с `scripts/restart.sh`, concurrency, логи и `down -v` (стенд CI одноразовый). Skeleton-job `contracts.yml` не менялся.
## Доказательства критериев
Все файлы сняты на одном стенде, поднятом с пустых volumes (дата, commit и параметры хоста в заголовке каждого файла).
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства |
| --- | --- | --- | --- |
| Публичный smoke | make test | TODO | TODO |
| Остальные пункты уровня 3 | TODO | TODO | TODO |
| Все пункты уровня 4, если заявлен | TODO | TODO | TODO |
| Выбранный трек 5, если заявлен | TODO | TODO | TODO |
TODO: добавить отдельную строку для каждого заявленного критерия. PASS без команды и наблюдения не является доказательством. Проверка инфраструктурного hook требует подтверждения, какие реальные процессы/хранилища перезапущены.
| Публичный smoke | `make check`, `make test` | оба PASS | evidence/smoke.txt |
| Минимум lab1 с переходом на Bearer | `make test` (сценарий lab2), `TestProtectedRoutesAcceptOnlyBearer` и остальные HTTP-тесты `internal/app` | PASS | evidence/smoke.txt, evidence/tests.txt |
| Данные и действующие сессии переживают рестарт API и хранилищ без удаления volumes | `make test-persistence ACTION_SCRIPT=scripts/restart.cmd` (`restart.sh`: `docker compose stop` + `up -d --wait`) | PASS тем же токеном; `StartedAt` всех трёх контейнеров изменился | evidence/persistence.txt |
| PostgreSQL: пользователи, чаты, участники, сообщения; PK/FK, UNIQUE username; миграции с нуля | `make destroy && make up`, `\dt`, `\di` | `schema ready applied_migrations=[1]`, 4 таблицы и индексы | evidence/bootstrap.txt |
| Повторный запуск миграций без дублирования | рестарт api; `TestMigrateIsRepeatable` | `applied_migrations=[]` | evidence/bootstrap.txt, evidence/tests.txt |
| Атомарное создание чата и его rollback | `TestCreateRollsBackWhenMemberInsertFails` | после ошибки FK нет ни строки чата, ни участников | evidence/tests.txt |
| Basic только на входе, Bearer на остальных, `X-User-Id` не даёт доступ | `TestProtectedRoutesAcceptOnlyBearer`, `TestLoginFailuresAreUniformBasicChallenges` | 401 с нужным `WWW-Authenticate`; `X-User-Id` игнорируется | evidence/tests.txt |
| Срок жизни и отзыв сессии | `TestSessionExpiresAfterTTL`, `TestLogoutRevokesOnlyTheCurrentToken`; стенд с `SESSION_TTL_SECONDS=2` | через 3 с 401 Bearer; logout 204, повтор 401 | evidence/expiry.txt, evidence/tests.txt |
| Пароли через password KDF | `TestRegisterStoresUserWithPasswordHash` | в БД `$argon2id$v=19$m=19456,t=2,p=1$…` | evidence/tests.txt |
| Secrets/volumes не в Git | `git ls-files secrets .env` | пусто; `secrets/` в `.gitignore` и `.dockerignore` | — |
| Valkey реально используется для сессий с TTL и persistence | `CONFIG GET`; остановка/запуск Valkey с тем же токеном | `appendonly yes`, `appendfsync always`, `noeviction`; после рестарта Valkey токен работает | evidence/bootstrap.txt, evidence/dependency-failures.txt |
| Параметризованные запросы, ограниченный пул и таймауты | код `store/postgres.go` (только `$n`), `TestPoolAppliesLimitsAndTimeouts`, `TestTimeoutBoundsTheRequestContext` | `MaxConns=10`, `statement_timeout=5s`, connect 1 с, дедлайн запроса | evidence/tests.txt |
| Гонка регистрации одного username | `TestConcurrentRegistrationOfOneUsernameHasOneWinner` | 10 параллельных попыток: ровно 1 успех, 9 × 409, одна строка | evidence/tests.txt |
| Индекс истории обоснован EXPLAIN на ≥10 000 сообщений, без полного scan на страницу | `make explain` (102 000 сообщений, 12 000 в целевом чате, транзакция с ROLLBACK) | `Index Scan using messages_pkey`, `Index Cond (chat_id = … AND id > …)`, 51 строка; 51 буфер на первой странице и 6 на глубокой, 0.05–0.1 мс; OFFSET той же страницы — сортировка 10 052 строк, 495 буферов, 4.6 мс | evidence/explain-history.txt |
| Автопроверки expiry, logout, неверного пароля, недоступности Redis/БД | `TestSessionExpiresAfterTTL`, `TestLogoutRevokesOnlyTheCurrentToken`, `TestLoginFailuresAreUniformBasicChallenges`, `TestValkeyOutageAnswers503`, `TestPostgresOutageAnswers503`, `TestHungPostgresAnswers503WithinTheRequestTimeout` | все PASS; при отказе — 503, никогда 200 или 401 | evidence/tests.txt, evidence/dependency-failures.txt |
| Гонки отправки сообщений | `make concurrency` | 100/100 созданы, перечислены и уникальны, порядок по id | evidence/concurrency.json |
| Выбранный трек 5 | не заявлен | — | — |
## Эксперименты и отказы
TODO: гипотеза, hardware/лимиты, версии, объём данных, профиль нагрузки, concurrency/arrival rate, длительность/прогрев, повторы, успешные RPS, ошибки, p50/p95/p99, CPU/RAM. Сохранить raw summary без tokens и объяснить ограничения измерения.
Стенд: Windows 11 Pro, Docker Desktop 28.5.1 (4 CPU, 3.8 GiB RAM для Linux-VM), без лимитов CPU/RAM на контейнеры, loopback-сеть. Нагрузочные измерения не проводились (трек 5 не заявлен); ниже проверки отказов уровня 4.
| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных |
| --- | --- | --- | --- |
| TODO | TODO | TODO | TODO |
| Полный рестарт: `docker compose stop` и `up -d --wait` (хук persistence) | те же данные и тот же токен | PASS, все три процесса перезапущены | весь тест с хуком ~15 с; потерь нет |
| `docker compose stop valkey` | 503 на защищённые запросы и вход, ready 503, регистрация работает | 503 за 1.2 с (дозвон ограничен 1 с; DNS Docker для остановленного контейнера отвечает ~4 с), `POST /users` 201, в логе `cause: dial tcp: lookup valkey: i/o timeout` | после `start` тот же токен 200: сессии восстановлены из AOF |
| `docker compose stop postgres` | 503 на операции с данными, ready 503 | 503 за 0.2 с, в логе причина подключения | после `start` 200 без перезапуска API: пул переподключается |
| PostgreSQL на паузе (`docker pause`, тест) | запрос не висит дольше дедлайна | 503 при дедлайне 300 мс, ready 503 | — |
| `SESSION_TTL_SECONDS=2` | сессия истекает | 200 сразу, 401 Bearer через 3 с | — |
| Ввод, который PostgreSQL не может хранить: NUL в `display_name`/`title`/`text`, NUL или не-UTF-8 в Basic username | 400 / 401, не 500 | 400 и 401 (проверка в приложении) | — |
## Ограничения и следующие шаги
TODO: какие отказы выдерживаются и какие нет; что не реализовано; где учебное упрощение; какое улучшение подтверждено, а какое пока гипотеза.
- Один Docker-host и по одному экземпляру PostgreSQL и Valkey: отказ host или диска теряет сервис; репликации и бэкапов нет. `appendfsync always` защищает подтверждённые сессии от падения процесса Valkey, но не от потери volume.
- Потеря или `FLUSHALL` Valkey разлогинивает всех: сессии существуют только там. Данные пользователей при этом не теряются, нужен повторный вход.
- Valkey — вторая критичная зависимость: при его отказе защищённый API отвечает 503, хотя PostgreSQL жив. Это осознанная цена хранения сессий вне БД.
- Argon2id тратит 19 MiB на вход или регистрацию; ограничения частоты входа нет (429 в контракте факультативен), всплеск входов нагружает CPU и память API.
- Семантика пагинации при конкурентных вставках описана выше: сообщение, закоммиченное позже сообщения с большим id, может быть пропущено продолжением уже идущего обхода.
- Уникальность id сообщения гарантирована в пределах чата; поиск сообщения по одному id потребует отдельного индекса.
- HTTP без TLS допустим только на локальном стенде (Basic передаёт пароль в открытом виде); TLS — в lab7. API ходит в PostgreSQL пользователем `messenger`, которого создаёт образ (он суперпользователь); отдельная роль без DDL и прав суперпользователя — задача lab7.
- `scripts/restart.cmd` нужен только на Windows: `tests/resilience.py` запускает хук без shell, а Windows не исполняет `.sh` напрямую.
- Дальше: трек 5 по согласованности кэша истории (отдельный экземпляр Valkey под кэш, имя переменной `CACHE_URL_FILE` зарезервировано) либо подготовка к lab3 (реплики API используют общие сессии в Valkey уже сейчас).
+63
View File
@@ -0,0 +1,63 @@
# Bootstrap from empty volumes: make destroy && make secrets up
# date: 2026-10-06T12:59:03Z, commit: 949622e (branch solution/bpi2301-bakulin)
# host: Windows 11, Docker Desktop 28.5.1 (4 CPU, 4111327232 bytes RAM), Go go1.27.1, Python 3.13.1
$ make up
Network mtusi2026lab2_default Created
Volume mtusi2026lab2_pgdata Created
Volume mtusi2026lab2_valkeydata Created
Container mtusi2026lab2-valkey-1 Created
Container mtusi2026lab2-postgres-1 Created
Container mtusi-messenger-lab2 Created
Container mtusi2026lab2-postgres-1 Started
Container mtusi2026lab2-valkey-1 Started
Container mtusi2026lab2-postgres-1 Healthy
Container mtusi2026lab2-valkey-1 Healthy
Container mtusi-messenger-lab2 Started
Container mtusi2026lab2-postgres-1 Healthy
Container mtusi2026lab2-valkey-1 Healthy
Container mtusi-messenger-lab2 Healthy
$ docker compose ps
SERVICE IMAGE STATUS PORTS
api mtusi-messenger:lab2 Up 6 seconds (healthy) 127.0.0.1:8080->8080/tcp
postgres postgres:18.6-alpine3.24@sha256:77f585114c32fbca283dc835b0596f4e52b51b4c6662d7810b2f4084f60a1873 Up 11 seconds (healthy) 5432/tcp
valkey valkey/valkey:9.1.2-alpine3.24@sha256:48332870af354a799964c0012ae1194a0bf2bf894eb508f945810596dc2d8d11 Up 11 seconds (healthy) 6379/tcp
$ docker compose logs api | grep -E "schema ready|starting"
{"time":"2026-10-06T13:00:02.672577874Z","level":"INFO","msg":"schema ready","applied_migrations":[1]}
{"time":"2026-10-06T13:00:02.689453662Z","level":"INFO","msg":"starting","env":"lab","addr":"0.0.0.0:8080","shutdown_timeout":"8s","session_ttl":"1h0m0s"}
$ psql \dt and \di (schema created by the migration)
List of tables
Schema | Name | Type | Owner
--------+------------------+-------+-----------
public | chat_members | table | messenger
public | chats | table | messenger
public | goose_db_version | table | messenger
public | messages | table | messenger
public | users | table | messenger
(5 rows)
List of indexes
Schema | Name | Type | Owner | Table
--------+----------------------------+-------+-----------+------------------
public | chat_members_pkey | index | messenger | chat_members
public | chat_members_user_chat_idx | index | messenger | chat_members
public | chats_pkey | index | messenger | chats
public | goose_db_version_pkey | index | messenger | goose_db_version
public | messages_pkey | index | messenger | messages
public | users_pkey | index | messenger | users
public | users_username_key | index | messenger | users
(7 rows)
$ valkey-cli CONFIG GET (persistence of the session store)
appendonly yes
appendfsync always
save
maxmemory 268435456
maxmemory-policy noeviction
$ second start: migrations are a no-op
{"time":"2026-10-06T13:00:12.891361865Z","level":"INFO","msg":"schema ready","applied_migrations":[]}
+16
View File
@@ -0,0 +1,16 @@
{
"base_url": "http://localhost:8080",
"started_at": "2026-10-06T13:01:23.3690872Z",
"clients": 10,
"per_client": 10,
"expected_messages": 100,
"created_201": 100,
"failed_posts": 0,
"listed_messages": 100,
"unique_ids": 100,
"created_but_not_listed": 0,
"history_ordered_by_id": true,
"pages_read": 1,
"elapsed_seconds": 0.1081132,
"passed": true
}
+30
View File
@@ -0,0 +1,30 @@
# Dependency outages on the stand (request deadline 5 s, dial/connect 1 s)
# date: 2026-10-06T12:59:03Z, commit: 949622e (branch solution/bpi2301-bakulin)
# host: Windows 11, Docker Desktop 28.5.1 (4 CPU, 4111327232 bytes RAM), Go go1.27.1, Python 3.13.1
baseline GET /users/me: 200
$ docker compose stop valkey
{"error":{"code":"unavailable","message":"session store unavailable","request_id":"6dc8e40f8ed60f3d3e32c65da449744e"}}
-> 503 in 1.223578s
POST /auth/sessions: 503 in 1.235624s
POST /users (PostgreSQL only): 201
{"error":{"code":"unavailable","message":"valkey is unavailable","request_id":"99a17ea0c0423c3142e004f27e09f739"}}
-> 503
api log:
{"time":"2026-10-06T13:01:03.639113985Z","level":"ERROR","msg":"request failed","request_id":"99a17ea0c0423c3142e004f27e09f739","error":"valkey is unavailable","cause":"dial tcp: lookup valkey: i/o timeout"}
after docker compose start valkey, same token: 200 (session survived via AOF)
$ docker compose stop postgres
{"error":{"code":"unavailable","message":"database unavailable","request_id":"eeb05d0a51641fb655e0f516f3704b67"}}
-> 503 in 0.230062s
{"error":{"code":"unavailable","message":"postgres is unavailable","request_id":"1df2b60f6d15c835ed4549601fba01d5"}}
-> 503
api log:
{"time":"2026-10-06T13:01:10.362999264Z","level":"ERROR","msg":"request failed","request_id":"1df2b60f6d15c835ed4549601fba01d5","error":"postgres is unavailable","cause":"failed to connect to `user=messenger database=messenger`: hostname resolving error: lookup postgres on 127.0.0.11:53: dial udp 127.0.0.11:53: i/o timeout"}
after docker compose start postgres: 200
GET /health/ready: 200
+12
View File
@@ -0,0 +1,12 @@
# Session expiry with SESSION_TTL_SECONDS=2
# date: 2026-10-06T12:59:03Z, commit: 949622e (branch solution/bpi2301-bakulin)
# host: Windows 11, Docker Desktop 28.5.1 (4 CPU, 4111327232 bytes RAM), Go go1.27.1, Python 3.13.1
api SESSION_TTL_SECONDS=2
GET /users/me right after login: 200
GET /users/me 3 s later:
HTTP/1.1 401 Unauthorized
Www-Authenticate: Bearer realm="messenger"
{"error":{"code":"unauthorized","message":"a valid bearer token is required","request_id":"30f35aed484df88d7c07e7ee17e2a92a"}}
api restored with SESSION_TTL_SECONDS=3600
+61
View File
@@ -0,0 +1,61 @@
# EXPLAIN (ANALYZE, BUFFERS) of the history query: make explain
# date: 2026-10-06T12:59:03Z, commit: 949622e (branch solution/bpi2301-bakulin)
# host: Windows 11, Docker Desktop 28.5.1 (4 CPU, 4111327232 bytes RAM), Go go1.27.1, Python 3.13.1
big_chat_messages | all_messages
-------------------+--------------
12000 | 102003
(1 row)
== First page: no cursor, limit 50 (+1 row that tells whether a next page exists)
QUERY PLAN
------------------------------------------------------------------------------------------------------------------------------------------
Limit (cost=0.42..23.86 rows=51 width=67) (actual time=0.020..0.077 rows=51.00 loops=1)
Buffers: shared hit=51
-> Index Scan using messages_pkey on messages (cost=0.42..5535.89 rows=12045 width=67) (actual time=0.018..0.072 rows=51.00 loops=1)
Index Cond: ((chat_id = '01a1114d-de5d-7f2e-8176-990d37b9797e'::uuid) AND (id > '00000000-0000-0000-0000-000000000000'::uuid))
Index Searches: 1
Buffers: shared hit=51
Planning:
Buffers: shared hit=17
Planning Time: 0.327 ms
Execution Time: 0.101 ms
(10 rows)
== Deep page: cursor after the 10 001st message of the chat
QUERY PLAN
----------------------------------------------------------------------------------------------------------------------------------------
Limit (cost=0.42..185.00 rows=51 width=67) (actual time=0.021..0.033 rows=51.00 loops=1)
Buffers: shared hit=6
-> Index Scan using messages_pkey on messages (cost=0.42..655.49 rows=181 width=67) (actual time=0.020..0.029 rows=51.00 loops=1)
Index Cond: ((chat_id = '01a1114d-de5d-7f2e-8176-990d37b9797e'::uuid) AND (id > '01a1114d-e03e-797e-bdd0-3cb5b8cb3079'::uuid))
Index Searches: 1
Buffers: shared hit=6
Planning Time: 0.093 ms
Execution Time: 0.050 ms
(8 rows)
== For contrast, OFFSET pagination of the same page reads every skipped row
QUERY PLAN
-----------------------------------------------------------------------------------------------------------------------------------------------
Limit (cost=2837.94..2838.07 rows=51 width=67) (actual time=4.491..4.496 rows=51.00 loops=1)
Buffers: shared hit=495
-> Sort (cost=2812.94..2843.06 rows=12047 width=67) (actual time=3.874..4.232 rows=10052.00 loops=1)
Sort Key: id
Sort Method: quicksort Memory: 1978kB
Buffers: shared hit=495
-> Bitmap Heap Scan on messages (cost=585.78..1996.37 rows=12047 width=67) (actual time=0.422..1.796 rows=12000.00 loops=1)
Recheck Cond: (chat_id = '01a1114d-de5d-7f2e-8176-990d37b9797e'::uuid)
Heap Blocks: exact=363
Buffers: shared hit=495
-> Bitmap Index Scan on messages_pkey (cost=0.00..582.77 rows=12047 width=0) (actual time=0.386..0.386 rows=12000.00 loops=1)
Index Cond: (chat_id = '01a1114d-de5d-7f2e-8176-990d37b9797e'::uuid)
Index Searches: 1
Buffers: shared hit=132
Planning Time: 0.043 ms
Execution Time: 4.629 ms
(16 rows)
+17
View File
@@ -0,0 +1,17 @@
# Persistence: make test-persistence ACTION_SCRIPT=scripts/restart.cmd (scripts/restart.sh on Linux)
# date: 2026-10-06T12:59:03Z, commit: 949622e (branch solution/bpi2301-bakulin)
# host: Windows 11, Docker Desktop 28.5.1 (4 CPU, 4111327232 bytes RAM), Go go1.27.1, Python 3.13.1
== containers before
/mtusi-messenger-lab2 started=2026-10-06T13:00:12.720916013Z status=running
/mtusi2026lab2-postgres-1 started=2026-10-06T12:59:56.582818179Z status=running
/mtusi2026lab2-valkey-1 started=2026-10-06T12:59:56.579702461Z status=running
$ make test-persistence ACTION_SCRIPT=scripts/restart.cmd PYTHON=python
Executing explicit persistence hook; hook output suppressed to avoid leaking secrets.
PASS: persistence preserved confirmed data and existing session. Hook scope needs operator evidence.
== containers after (every StartedAt changed: all three processes were restarted, volumes kept)
/mtusi-messenger-lab2 started=2026-10-06T13:00:28.600983618Z status=running
/mtusi2026lab2-postgres-1 started=2026-10-06T13:00:22.758610805Z status=running
/mtusi2026lab2-valkey-1 started=2026-10-06T13:00:22.751213945Z status=running
+9
View File
@@ -0,0 +1,9 @@
# Public checks: make check, make test
# date: 2026-10-06T12:59:03Z, commit: 949622e (branch solution/bpi2301-bakulin)
# host: Windows 11, Docker Desktop 28.5.1 (4 CPU, 4111327232 bytes RAM), Go go1.27.1, Python 3.13.1
$ make check PYTHON=python
PASS: offline skeleton structure, local refs and Python syntax; application NOT tested.
$ make test PYTHON=python
PASS: lab2 public API scenario; infrastructure and grading evidence remain separate.
+49
View File
@@ -0,0 +1,49 @@
# Automated tests against real PostgreSQL and Valkey (testcontainers): go test -race -v
# date: 2026-10-06T13:02:19Z, commit: 949622e (branch solution/bpi2301-bakulin)
# host: Windows 11, Docker Desktop 28.5.1 (4 CPU, 4111327232 bytes RAM), Go go1.27.1
# full suite: make unit (go test -race -count=1 ./...), 16 packages ok
--- PASS: TestRegisterUserShapeAndConflicts (0.31s)
--- PASS: TestConcurrentSendsProduceExactlyUniqueMessages (1.92s)
--- PASS: TestLoginReturnsBearerSession (0.35s)
--- PASS: TestLoginFailuresAreUniformBasicChallenges (0.43s)
--- PASS: TestLoginAcceptsColonAndUnicodePasswords (0.14s)
--- PASS: TestProtectedRoutesAcceptOnlyBearer (0.26s)
--- PASS: TestLogoutRevokesOnlyTheCurrentToken (0.19s)
--- PASS: TestSessionExpiresAfterTTL (1.35s)
--- PASS: TestValkeyOutageAnswers503 (3.98s)
--- PASS: TestPostgresOutageAnswers503 (4.06s)
--- PASS: TestHungPostgresAnswers503WithinTheRequestTimeout (5.45s)
ok messenger/internal/app 29.152s
--- PASS: TestLoginIssuesOpaqueTokenBackedByStoredSession (0.20s)
--- PASS: TestLoginWithBadCredentialsCreatesNoSession (0.30s)
--- PASS: TestAuthenticateResolvesTheOwner (0.27s)
--- PASS: TestLogoutRevokesOnlyThatSession (0.36s)
--- PASS: TestSessionExpiresAfterTTL (1.34s)
ok messenger/internal/auth 13.245s
--- PASS: TestCreateRollsBackWhenMemberInsertFails (0.08s)
--- PASS: TestConcurrentAppendsKeepEveryMessage (0.21s)
ok messenger/internal/chat/store 9.320s
--- PASS: TestKindOfDefaultsToInternal (0.00s)
ok messenger/internal/platform/apperr 1.572s
--- PASS: TestDefaults (0.02s)
--- PASS: TestSecretFilesAreRequiredAndNeverEchoed (0.07s)
--- PASS: TestOverrides (0.02s)
--- PASS: TestInvalidValuesAreReported (0.09s)
ok messenger/internal/platform/config 1.801s
--- PASS: TestUnavailableCauseIsLoggedButNotReturned (0.06s)
--- PASS: TestTimeoutBoundsTheRequestContext (0.05s)
ok messenger/internal/platform/httpx 5.748s
--- PASS: TestMigrateIsRepeatable (0.01s)
--- PASS: TestPoolAppliesLimitsAndTimeouts (0.01s)
--- PASS: TestClassifyMarksUnreachableDatabaseAsUnavailable (0.00s)
--- PASS: TestClassifyRealConnectFailure (0.00s)
ok messenger/internal/platform/postgres 9.271s
--- PASS: TestRegisterStoresUserWithPasswordHash (0.11s)
--- PASS: TestRegisterRejectsInvalidInputAndStoresNothing (0.02s)
--- PASS: TestRegisterReportsDuplicateAsConflict (0.21s)
--- PASS: TestConcurrentRegistrationOfOneUsernameHasOneWinner (0.30s)
--- PASS: TestExistingIDsReturnsOnlyRegistered (0.27s)
--- PASS: TestAuthenticateChecksPassword (0.16s)
--- PASS: TestAuthenticateFailuresLookTheSame (0.39s)
ok messenger/internal/user 10.562s