From 956b84f2d7fcda016e9d6377b7830977bf4e3705 Mon Sep 17 00:00:00 2001 From: kudesn1k Date: Tue, 6 Oct 2026 16:05:24 +0300 Subject: [PATCH] =?UTF-8?q?=D0=97=D0=B0=D0=BF=D0=BE=D0=BB=D0=BD=D0=B8?= =?UTF-8?q?=D1=82=D1=8C=20=D0=BE=D1=82=D1=87=D1=91=D1=82=20=D0=B8=20=D0=B4?= =?UTF-8?q?=D0=BE=D0=BA=D0=B0=D0=B7=D0=B0=D1=82=D0=B5=D0=BB=D1=8C=D1=81?= =?UTF-8?q?=D1=82=D0=B2=D0=B0=20=D0=BB=D0=B0=D0=B1=D0=BE=D1=80=D0=B0=D1=82?= =?UTF-8?q?=D0=BE=D1=80=D0=BD=D0=BE=D0=B9=202?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .github/pull_request_template.md | 28 +++--- REPORT.md | 144 +++++++++++++++++++++++++++---- evidence/bootstrap.txt | 63 ++++++++++++++ evidence/concurrency.json | 16 ++++ evidence/dependency-failures.txt | 30 +++++++ evidence/expiry.txt | 12 +++ evidence/explain-history.txt | 61 +++++++++++++ evidence/persistence.txt | 17 ++++ evidence/smoke.txt | 9 ++ evidence/tests.txt | 49 +++++++++++ 10 files changed, 400 insertions(+), 29 deletions(-) create mode 100644 evidence/bootstrap.txt create mode 100644 evidence/concurrency.json create mode 100644 evidence/dependency-failures.txt create mode 100644 evidence/expiry.txt create mode 100644 evidence/explain-history.txt create mode 100644 evidence/persistence.txt create mode 100644 evidence/smoke.txt create mode 100644 evidence/tests.txt diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 8ceefa10..610c14a1 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -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 содержит инструкцию именно моего решения. diff --git a/REPORT.md b/REPORT.md index e42f2b05..698b6fc5 100644 --- a/REPORT.md +++ b/REPORT.md @@ -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: → 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:` со значением user_id и абсолютным сроком (`SET … PXAT/EXAT`): утечка AOF не даёт рабочих токенов, а рестарт не продлевает сессию. Все остальные endpoint'ы требуют `Authorization: Bearer ` (схема без учёта регистра); отсутствие, 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:` и подделать сессию. + +Отказы и таймауты. Пул 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 уже сейчас). diff --git a/evidence/bootstrap.txt b/evidence/bootstrap.txt new file mode 100644 index 00000000..5546e177 --- /dev/null +++ b/evidence/bootstrap.txt @@ -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":[]} diff --git a/evidence/concurrency.json b/evidence/concurrency.json new file mode 100644 index 00000000..1ec0437c --- /dev/null +++ b/evidence/concurrency.json @@ -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 +} diff --git a/evidence/dependency-failures.txt b/evidence/dependency-failures.txt new file mode 100644 index 00000000..749c7691 --- /dev/null +++ b/evidence/dependency-failures.txt @@ -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 diff --git a/evidence/expiry.txt b/evidence/expiry.txt new file mode 100644 index 00000000..bf39d1b2 --- /dev/null +++ b/evidence/expiry.txt @@ -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 diff --git a/evidence/explain-history.txt b/evidence/explain-history.txt new file mode 100644 index 00000000..53f5ca27 --- /dev/null +++ b/evidence/explain-history.txt @@ -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) + diff --git a/evidence/persistence.txt b/evidence/persistence.txt new file mode 100644 index 00000000..a5372f01 --- /dev/null +++ b/evidence/persistence.txt @@ -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 diff --git a/evidence/smoke.txt b/evidence/smoke.txt new file mode 100644 index 00000000..f76f8fd2 --- /dev/null +++ b/evidence/smoke.txt @@ -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. diff --git a/evidence/tests.txt b/evidence/tests.txt new file mode 100644 index 00000000..6a942d96 --- /dev/null +++ b/evidence/tests.txt @@ -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