Files
mtusi2026lab2/REPORT.md
T

31 KiB
Raw Blame History

Отчёт — лабораторная 2

  • Автор, группа: Брезгунова Анжелика, БВТ2303.
  • Целевая оценка: 5. Трек 2 — план запроса и восстановление.
  • Рабочая ветка: solution/BVT2303-Брезгунова-на5. Commit/PR появятся при публикации работы.
  • Реализация: Go; PostgreSQL как источник истины; Redis как кэш неизменяемых профилей.
  • Использована помощь Codex для реализации, тестов и оформления. Основа HTTP API, модели и ограничения запросов перенесены из собственной первой лабы. Контракт, задание и публичные тесты второй лабы сохранены.

Запуск из чистого clone

Нужны Docker Engine с Compose v2+ и Python 3.9+. Локальный Go и make необязательны: Dockerfile выполняет go test ./..., go vet ./... и сборку. Образы закреплены: Go 1.24.7-alpine3.22, Alpine 3.22.1, PostgreSQL 17.6-alpine3.22, Redis 7.4.5-alpine3.21. Приложение имеет локальный тег mtusi-messenger:lab2.

Из каталога репозитория, в PowerShell или POSIX shell:

python scripts/bootstrap.py
docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build
python scripts/wait_ready.py --base-url http://127.0.0.1:8080
python scripts/check_contract.py
python tests/smoke.py --base-url http://127.0.0.1:8080

Bootstrap генерирует случайный локальный пароль, .env и secrets/database_url, secrets/cache_url. При повторе пароль не меняется. Эти файлы игнорируются Git и исключены из build context. На Linux .env имеет права 0600, каталог secrets — 0700; отдельные URL-файлы имеют 0644 для чтения непривилегированным API после bind mount. Не копировать сюда secrets или volume первой лабы. Изменение пароля в .env не меняет пароль уже инициализированной БД.

API доступен на 127.0.0.1:8080; порт хоста меняется через HOST_PORT в .env. PostgreSQL и Redis не публикуют порты. В Windows выбран IPv4-адрес, чтобы исключить наблюдавшуюся задержку разрешения localhost. Если меняете порт, передайте соответствующий --base-url, а для собственного integration-теста задайте BASE_URL.

При наличии make те же проверки:

make up PYTHON=python
make check test PYTHON=python BASE_URL=http://127.0.0.1:8080
chmod +x scripts/restart.sh
make test-persistence PYTHON=python ACTION_SCRIPT=scripts/restart.sh BASE_URL=http://127.0.0.1:8080
make test-extra research PYTHON=python

Для Windows hook запускается непосредственно публичным тестом:

python tests/resilience.py --mode persistence --action-script scripts/restart.cmd --base-url http://127.0.0.1:8080

Полный последовательный прогон с сохранением доказательств:

python student-tests/verify.py
python student-tests/profile_load.py

verify.py создаёт синтетические данные, перезапускает только сервисы этой лабы, временно останавливает Redis/PostgreSQL и восстанавливает их в finally. Для expiry временно пересоздаёт API с TTL=2, затем возвращает значение из .env. Исследование работает в собственных уникальных БД и удаляет только созданные этим запуском БД; учебные данные приложения не меняет. Backup остаётся в игнорируемом каталоге backups/. Исследовательский сервис restore после эксперимента остановлен; его отдельный volume сохранён.

Безопасная остановка с сохранением всех данных:

docker compose --env-file .env --profile research down

Намеренное удаление всех учебных данных этого Compose-проекта, только когда они больше не нужны:

docker compose --env-file .env --profile research down --volumes

Для полной проверки OpenAPI установите requirements-dev.txt в venv и выполните python scripts/validate_openapi.py. CI skeleton выполняет эту проверку отдельно. Собственный workflow application.yml собирает приложение и запускает smoke, persistence, дополнительные тесты и исследование; он не использует секреты аккаунта.

Архитектура и решения

Клиент -> API :8080 -> PostgreSQL :5432
                  \-> Redis :6379 (необязательный кэш профилей)
Исследование -> pg_dump -> отдельный PostgreSQL restore -> отдельный volume

Приложение работает от непривилегированного пользователя, с read-only файловой системой и без Linux capabilities. Состояние API не хранится локально. Основные volumes: postgres_data, redis_data; для эксперимента — restore_data. Redis не содержит обязательных данных и не требует persistence. Его volume не используется как доказательство сохранности сессий.

Схема, ограничения и транзакционные границы

Схема задаётся миграцией migrations/001_initial.sql:

Таблица Содержимое и ограничения Индексы
users UUID PK, уникальный username, display_name, password_hash, время БД; CHECK формата username и длины display_name PK, UNIQUE username
chats UUID PK, title с ограничением длины, время БД PK, (created_at,id)
chat_members FK на chat/user, PK (chat_id,user_id), уникальный порядок участника в чате PK, UNIQUE (chat_id,position), (user_id,chat_id)
messages UUID PK, FK на чат; составной FK (chat_id,sender_id) на членство; text 1–4000 code points, время БД PK, (chat_id,created_at,id)
sessions SHA-256 случайного токена как bytea PK длиной 32; FK user; абсолютный expires_at больше created_at PK, expires_at для очистки
schema_migrations Имя миграции, контрольная сумма SHA-256, время применения PK имени

Создание чата и всех его участников — одна SQL-транзакция. Неизвестный второй участник вызывает FK-ошибку уже после вставки чата и первого участника; rollback удаляет все изменения. Регистрация — один INSERT; UNIQUE в PostgreSQL разрешает гонку одинаковых username. Запись сообщения и создание/удаление сессии — отдельные атомарные SQL-операции. Ответ 201/204 отправляется после успешного выполнения/COMMIT. Используются штатные настройки PostgreSQL fsync, synchronous_commit, full_page_writes; рестарт контейнера проверен, отказ диска/хоста этим не моделируется.

Миграции встроены в бинарник. При старте advisory lock сериализует запуск, а миграции и запись их контрольных сумм коммитятся вместе. Повторный старт пропускает применённые миграции; изменение уже применённого файла приводит к ошибке старта. Новые изменения схемы нужно оформлять новым нумерованным файлом. Миграции не выполняют seed приложения.

Все пользовательские значения передаются параметрами $1…; SQL не собирается из полей HTTP. Пул ограничен 8 соединениями, контекст HTTP/БД — 2 секунды, подключение — 2 секунды, SQL statement timeout — 2 секунды, lock timeout — 1 секунда. HTTP имеет ограничения размера тела (1 MiB), заголовков и таймауты чтения/записи. Admission gate — 64 бизнес-запроса; одновременно работают максимум 4 password KDF. При заполнении gate возвращается 429 с Retry-After. Health остаётся доступен при заполнении gate.

Аутентификация и доступ

Регистрация принимает пароль из 12–128 Unicode code points. Argon2id v19: память 32 MiB, 3 итерации, 2 lanes, случайная соль 16 bytes, результат 32 bytes. Сравнение ключей выполняется в постоянное время. Пароли не усекутся на 72 bytes; проверен пароль длиной 128 Unicode-символов с двоеточием. Пустые и состоящие только из пробелов значения отклоняются.

POST /api/v1/auth/sessions принимает Basic без тела. Неверный пароль и неизвестный пользователь возвращают одинаковый 401 и Basic challenge; для неизвестного пользователя также выполняется dummy KDF. Сессия получает 32 случайных bytes (256 бит), закодированных base64url. Это opaque токен; в PostgreSQL сохраняется только его SHA-256. SHA-256 здесь служит индексом случайного высокоэнтропийного токена, а не password KDF.

Защищённые запросы принимают Bearer; X-User-Id игнорируется, Basic на бизнес-эндпоинтах не принимается. Авторизация всегда проверяет сессию в PostgreSQL с expires_at > clock_timestamp(). TTL задаёт SESSION_TTL_SECONDS, по умолчанию 3600; абсолютное время не изменяется из-за рестарта. Logout атомарно удаляет действительную сессию. Повторный logout и запрос после expiry — 401 с Bearer challenge. Фоновая очистка удаляет истёкшие сессии раз в минуту; действительность не зависит от запуска этой очистки.

Далее проверяется членство пользователя в чате: постороннему возвращается 404. Sender определяется по сессии, клиентское поле sender_id отклоняется. User никогда не содержит password/hash/token. Регистрация, вход и health публичны; /metrics — локальное диагностическое расширение.

Redis, expiry и инвалидация

Redis действительно кэширует ответы профиля GET /users/me по ключу profile:v1:<user_id>, TTL 300 секунд. Источник истины — users в PostgreSQL. API текущей лабы не меняет и не удаляет профиль, поэтому инвалидация при записи не нужна: кэш заполняется только из успешно сохранённого User. При добавлении редактирования понадобится явная инвалидация/версионирование. История чата не кэшируется: следующее чтение после подтверждённой записи сразу идёт в PostgreSQL.

Сессия проверяется в PostgreSQL до обращения к Redis; кэш не может обойти logout, expiry или отказ БД. При miss/ошибке/потере Redis профиль читается из PostgreSQL. GET/SET кэша ограничены 150 ms каждый, retry выключен; cache hit/miss/failure видны в /metrics. Redis ограничен 64 MiB, политика allkeys-lru. Недоступность Redis не блокирует readiness. Недоступность PostgreSQL приводит к 503 readiness и защищённых запросов; liveness остаётся 200. Приложение не принимает анонимного пользователя как доверенного.

Пагинация и порядок

История читает максимум limit+1 записей по предикату chat_id=$1 AND (created_at,id)>($2,$3), сортировке (created_at,id) и индексу (chat_id,created_at,id). OFFSET и чтение всей истории в память отсутствуют. Дополнительная запись определяет next_cursor; последний элемент страницы не повторяется. Cursor содержит ресурс, время и UUID; cursor чужого чата или списка другого пользователя отклоняется. Допускается смена limit, диапазон 1–100.

Время назначается PostgreSQL с точностью microseconds; UUID разрешает равенство времён. Между HTTP-страницами нет snapshot: конкурентная вставка с ключом раньше уже пройденного cursor может не попасть в этот обход. Обратный ход системных часов также может создать такую запись. Для неизменяемой истории обход полный и без повторов. Следующее чтение с начала видит все подтверждённые записи.

Конфигурация

APP_HOST, APP_PORT, SESSION_TTL_SECONDS, SESSION_STORE, DATABASE_URL_FILE, CACHE_URL_FILE, DB_MAX_CONNECTIONS, DB_TIMEOUT_MS, KDF_CONCURRENCY, MAX_IN_FLIGHT, MAX_BODY_BYTES читаются приложением. _FILE имеет приоритет над прямым URL; SESSION_STORE допускает только postgres. POSTGRES_PASSWORD и HOST_PORT используются Compose, APP_ENV=lab в примере — информационная метка. HTTP допустим здесь для локального стенда с синтетическими данными; Basic кодирует, но не шифрует пароль.

Доказательства критериев

Фактические результаты сохраняются в evidence/verification.json, integration.json, research.json, load.json, resources.json, build.txt. Команды внутри JSON позволяют повторить проверку. Публичные Python-команды — прямые эквиваленты соответствующих targets Makefile; локальный make на проверяемой Windows-машине отсутствует.

Критерий Команда/сценарий Доказательство
Контракт и сборка python scripts/check_contract.py; Docker build с go test и go vet verification.json; build.txt
Обязательный API, неверный пароль, Basic/Bearer, доступ, logout python tests/smoke.py --base-url http://127.0.0.1:8080 verification.json
Данные и действующие сессии после рестарта всех сервисов публичный resilience с restart.cmd/restart.sh verification.json: PASS, StartedAt всех трёх контейнеров до/после
Миграции с нуля и повторный запуск первая инициализация volume; restart API и сравнение migration/user/message counts build.txt; integration.json
Username race, атомарность чата, параметризованный SQL 4 конкурентные регистрации; чат с неизвестным вторым участником; чтение SQL-результатов integration.json; database.go
Password KDF, Unicode, безопасное хранение токена проверки префикса hash/digest в БД, Unicode login, Go-тест integration.json; build.txt
Реальная роль Redis рост cache_hits; stop Redis и FLUSHDB; тот же токен читает данные integration.json
Expiry, logout, отказ Redis/БД TTL=2; 401/503/200 по сценарию integration.json
Ограниченный пул/таймауты конфигурация приложения, bounded outage assertions main.go; compose.yaml; integration.json
Индекс на ≥10 000 сообщений EXPLAIN ANALYZE BUFFERS на 100 000 research.json
Трек 2 целиком два индекса, чтение/запись, dump/restore в другой контейнер/volume, сверка research.json

Эксперимент: план запроса и восстановление

Гипотеза: индекс (chat_id,created_at,id) ограничивает работу на keyset-страницу независимо от длины истории чата, но увеличивает объём индекса и стоимость вставки относительно (chat_id).

Стенд: Windows, Docker Desktop Linux/WSL2; Intel Core i7-12700H, 14 физических ядер / 20 логических процессоров, RAM около 16 GiB. Compose лимиты: API 1 CPU / 512 MiB, PostgreSQL 1 CPU / 512 MiB, Redis 0.5 CPU / 128 MiB. Restore PostgreSQL — отдельный контейнер 1 CPU / 512 MiB. Образы и зависимости закреплены в Dockerfile/compose/go.mod/go.sum.

Методика python student-tests/research.py: отдельная исследовательская БД, 100 000 сообщений в 10 чатах: 80 000, 15 000 и 8×625. В большом чате text имеет 200 символов, в остальных 40. Сравниваются (chat_id) и (chat_id,created_at,id). Три страницы большого чата: начало, после 40 000, после 79 000; LIMIT 51, два прогрева и пять измерений каждой страницы. В raw JSON сохранены execution times, actual rows и BUFFERS. Для каждого индекса — пять INSERT по 2000 строк под EXPLAIN ANALYZE, затем rollback. Это сравнение работы вставки с FK/triggers, без измерения COMMIT; rollback может оставить dead tuples, что явно ограничивает точность сравнения.

После измерений выбранный составной индекс сохраняется в схеме. pg_dump -Fc создаёт snapshot; pg_restore --exit-on-error восстанавливает его в пустую БД отдельного PostgreSQL-контейнера на отдельном named volume. Проверяются counts users/chats/members/messages, digest всех сообщений в устойчивом порядке и 10 полных сообщений. Исследовательские БД после успешной сверки удаляются, backup исключён из Git.

Результаты 10 октября 2026 года

Полный последовательный прогон прошёл. Smoke и persistence вернули PASS; verification.json дополнительно подтверждает изменение StartedAt API, PostgreSQL и Redis. Гонка регистрации дала ровно один 201 и три 409; составной чат после FK-ошибки отсутствовал. При отказе Redis сценарий fallback занял 0,375 с; последовательная проверка отказа PostgreSQL заняла 4,031 с (два запроса к БД с таймаутом 2 с, liveness и отказ анонимному пользователю). TTL=2 и logout дали ожидаемые 401.

Измерение, медиана пяти повторов (chat_id) (chat_id,created_at,id)
Страница в начале, ms 18,687 0,158
Страница после 40 000, ms 14,587 0,170
Страница после 79 000, ms 12,460 0,149
INSERT 2000 строк с последующим rollback, ms 125,699 116,631
Размер индекса, bytes 720 896 5 914 624
Shared hit blocks средней страницы, выбранный третий повтор 3224 7

План (chat_id) на большом чате выбрал parallel sequential scan и top-N sort. Составной индекс дал Index Scan с соответствующим Index Cond и 51 фактической строкой под Limit; полной сортировки/сканирования истории нет. Средняя страница ускорилась примерно в 85,8 раза на этом стенде. Цена по размеру индекса — около 8,2 раза. Предположение о замедлении INSERT в этом коротком опыте не подтвердилось: составной индекс оказался немного быстрее. Нельзя выдавать это за отсутствие стоимости индекса; ограничения порядка вариантов, прогрева, rollback и доминирующих FK/triggers не позволяют сделать такой вывод. Уверенно подтверждены выигрыш чтения и рост размера индекса.

Backup: 2 882 994 bytes, создание 1,500 с, восстановление 1,734 с. В исходной и восстановленной БД совпали 1 пользователь, 10 чатов, 10 membership и 100 000 сообщений; digest всех сообщений be1222f55df222fef96c1d71910ec87b, а также 10 полных выбранных сообщений совпали. Эти данные сохранены вместе с raw планами в evidence/research.json. Restore выполнен в отдельном контейнере и отдельном volume, без повторного seed.

Первый HTTP-прогон: 30,125 с, concurrency=4, 9873 успешных запроса, 0 ошибок, 327,734 successful RPS; p50=15, p95=31, p99=32 ms. Его вывод сохранён в verification.json.

Повтор на финальном образе с одновременными CPU/RAM-сэмплами: 30,093 с, 10 435 успешных запросов, 0 ошибок, 346,758 successful RPS; p50=15, p95=31, p99=32 ms. В resources.json сохранены шесть сэмплов Docker stats во время этого прогона; load.json содержит итог. HTTP-прогоны начинаются после readiness/bootstrap; отдельный временной прогрев HTTP-нагрузки не выделялся. Максимум среди этих сэмплов (это не непрерывный peak): API 72,90% CPU и 73,16 MiB RAM; PostgreSQL 74,11% и 84,70 MiB; Redis 6,00% и 6,496 MiB. CPU-процент Docker относится к одному логическому CPU. Изменение размера истории и фоновые операции/измерения входят в профиль; разница RPS между повторами не интерпретируется как отдельное доказательство оптимизации.

Ограничения

Исправления по замечаниям от 29 октября 2026 года

Перед декодированием HTTP body добавлена проверка точных имён верхнеуровневых полей по JSON-тегам DTO. encoding/json по умолчанию сопоставляет имена без учёта регистра даже с DisallowUnknownFields; теперь {"text":"valid","TEXT":"unexpected-property"} отклоняется с 400 invalid_request до заполнения структуры и записи сообщения. Повторяющиеся JSON-ключи также отклоняются. Проверка общая для регистрации, создания чата и отправки сообщения; текущие DTO не содержат вложенных объектов.

Пагинация различает отсутствие параметра и переданное пустое значение: без limit используется 50, но ?limit=, ?cursor= и параметры без = возвращают 400 invalid_request. Повторяющиеся limit/cursor отклоняются как неоднозначные. Исправление действует для истории сообщений и списка чатов.

Проверено: Docker build с go test ./... и go vet ./..., python scripts/check_contract.py, публичный smoke и python student-tests/regression.py --base-url http://127.0.0.1:8080 — PASS. В последнем проверяются авторизованные запросы, отсутствие новых сообщений после отклонённых POST, точный error code, пустые параметры и корректное продолжение страниц. Результаты — evidence/regression.json. Проверка добавлена в локальный verify.py и workflow Application. Полное исследование производительности при этом исправлении повторно не запускалось; измерения выше относятся к прогону 10 октября.

Эксплуатационные ограничения

Одна API-реплика и одна основная БД: отказ PostgreSQL не скрывается, HA не заявляется. Redis — доверенный внутренний сервис локальной Compose-сети, без TLS/ACL; он не опубликован наружу. Пользователь БД в учебном стенде управляет миграциями; разделение migration/runtime ролей оставлено для последующих лабораторных. Secrets Compose — файлы локального оператора, внешний secret manager не используется.

Перезапуск с volumes проверяет сохранность контейнерного стенда, а не внезапное отключение питания или повреждение диска. Отдельные request contexts ограничивают время ожидания; 201 может быть потерян на сети после COMMIT, поэтому прозрачный retry POST в lab2 не добавлен. Идемпотентность появляется по контракту lab3.

Backup включает данные на snapshot начала dump. Сообщения, подтверждённые позже этого snapshot, в backup не входят: без WAL archiving/PITR предел потери данных равен времени с последнего backup. Измеренное время восстановления относится к restore уже подготовленного локального контейнера и не включает обнаружение аварии и provisioning.

Нагрузочный генератор closed-loop, concurrency=4, 30 секунд; latency — только успешных запросов, есть coordinated omission. Это успешные HTTP-подтверждения, а не универсальная максимальная пропускная способность или точный счётчик COMMIT. Индексный эксперимент — пять последовательных повторов на прогретом локальном buffer cache; порядок вариантов фиксирован, статистическая универсальность не заявляется.

Из факультативной первой лабы сохранены лимит тела, admission gate и метрики; in-memory лимит числа сообщений заменён устойчивым хранением без искусственного ограничения истории. Grafana/Prometheus не входят в обязательный минимум второй лабы, /metrics позволяет подключить их отдельно. Следующие шаги: несколько API-реплик и идемпотентность по lab3, разделение DB-ролей, TLS и управление secrets в соответствующих лабораторных.

Источники

  • Задание этой лабораторной, COURSE.md, contracts/README.md, contracts/openapi.json, публичные тесты.
  • Собственная реализация первой лабораторной: HTTP API, модели, метрики и admission gate.
  • Библиотеки github.com/lib/pq, github.com/redis/go-redis/v9, golang.org/x/crypto/argon2; точные версии в go.mod/go.sum. Код SQL, KDF и cache integration написан под контракт этой лабы.