Files
mtusi2026lab2/REPORT.md
T

26 KiB
Raw Blame History

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

  • Автор: Крайкин Глеб Алексеевич, БВТ2303.
  • Цель: 5, трек 2 — план SQL-запроса и восстановление.
  • Skeleton: 65003b61195361aac238f19c9bff0027ca58e09e.
  • Ветка: solution/bvt2303-kraykin. Текущий commit: git rev-parse HEAD.
  • Дата проверок: 02.10.2026; времена в evidence — UTC.
  • Исходное задание. README, COURSE, contracts и публичные tests сохранены.
  • Перенесено собственное решение lab1: структуры ответов, строгий JSON decoder, Unicode-валидация, UUID, подписанные scoped cursors, HTTP lifecycle и non-root multi-stage Docker. Хранение в памяти и X-User-Id заменены PostgreSQL и Basic/Bearer. Linear/binary поиск из lab1 не переносился: здесь поиск выполняет БД по составному индексу.
  • Использование ИИ: Codex помог с проектированием, реализацией, проверками, исследованием и материалами защиты. Исходный контракт/публичные тесты — преподавателя; старое приложение — собственное решение первой работы. Чужие студенческие решения не использованы.

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

Нужны Docker Desktop/Linux daemon, Docker Compose v2 с поддержкой --wait, Python 3.9+ и make. Для локального go test -race нужны Go 1.24.4 и C-компилятор; контейнерная make test-race альтернатива не требует Go на хосте.

# В каталоге решения:
make up
curl http://localhost:8082/health/ready
make check
make test
make test-student
make test-race
make test-docker
make test-persistence ACTION_SCRIPT=scripts/restart.sh
make experiment
python3 student-tests/clean_clone.py

make up вызывает bootstrap (генерирует .env, локальные credentials и cursor key), затем build/up с ожиданием готовности. На первом старте пустой PostgreSQL-volume получает схему через версионированную embedded SQL-миграцию. Каждый следующий старт проверяет ledger/checksum и не повторяет создание таблиц/данных. Нет требования иметь заранее установленную БД.

Порт хоста по умолчанию 8082, чтобы не конфликтовать с предыдущей лабораторной. Внутри API APP_PORT=8080; опубликовано только 127.0.0.1. APP_PORT в .env регулирует host port Compose; при изменении задайте make test BASE_URL=http://localhost:НОВЫЙ_ПОРТ и то же значение остальным HTTP-проверкам/Postman. SESSION_TTL_SECONDS из .env передаётся API. Для проверки expiry integration временно передаёт 2 через окружение Compose, затем возвращает 3600.

Dockerfile: Go 1.24.4-alpine3.22 build, Alpine 3.22.1 runtime; PostgreSQL 17.6-alpine, Valkey 8.1.3-alpine. Конкретные image IDs/digests находятся в evidence/lifecycle.json. go.mod/go.sum закрепляют pgx 5.7.6, go-redis 9.12.1, x/crypto 0.41.0 и транзитивные зависимости. Compiler/source отсутствуют в runtime; USER 10001:10001, PID 1 messenger, healthcheck и SIGTERM.

Secrets: secrets/postgres_password, database_url, cache_url, valkey_config, cursor_key. Они генерируются локально, исключены из Git/build context, монтируются как отдельные Compose secrets. Host-directory имеет mode 0700, отдельные mount-файлы — 0444 для чтения container UID. Bootstrap не перезаписывает существующие credentials. API читает DATABASE_URL_FILE, CACHE_URL_FILE, CURSOR_KEY_FILE. Источник сессий фиксирован PostgreSQL; SESSION_STORE — описательная метка, runtime-переключения нет. API host/environment заданы Compose.

Остановка и повторный запуск с сохранением данных:

make down
make up

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

docker compose --profile research down -v

Рабочие проверки никогда не выполняют эту команду. Clean-clone проверка удаляет только собственный disposable проект с уникальным именем. Research повторно создаёт новые БД, старые результаты/БД остаются; их дальнейшее обслуживание — действие оператора.

Архитектура, таблицы и транзакции

Postman / HTTP → API → PostgreSQL (users, chats, membership, messages, sessions)
                    → Valkey (immutable public User cache, TTL 300)

PostgreSQL — единственный источник истины для обязательных данных и действительности сессий. postgres_data — именованный volume. Valkey профили можно потерять: RDB/AOF отключены, после miss/рестарта профиль загрузится из БД. Его valkey_data volume не используется как гарантия persistence оперативной памяти. История сообщений кэшом не обслуживается, поэтому read-after-write идёт напрямую в primary PostgreSQL. Будущие API-реплики должны использовать ту же БД и общий persistent cursor key; в принятом стенде одна API-реплика.

Таблица Ограничения / индексы Назначение
users UUID PK; UNIQUE username; CHECK длины/формата Публичные поля + Argon2id hash
chats UUID PK; title CHECK; (created_at,id) index Чат и persistent last_message_at
chat_members PK (chat_id,user_id); оба FK; (user_id,chat_id) index Членство и доступные чаты пользователя
messages UUID PK; FK chat; составной FK (chat_id,sender_id) к membership; text CHECK Подтверждённые сообщения
messages_history_idx B-tree (chat_id,created_at,id) Диапазон keyset и порядок страницы
sessions PK token_hash 32 bytes; FK user; expiry index Постоянные opaque сессии
schema_migrations PK version; checksum; applied_at Однократное применение версионированных миграций

Создание чата: BEGIN → INSERT chat → INSERT всех участников → COMMIT; неизвестный user даёт FK violation, весь чат откатывается. Проверки UUID/дублей/наличия вызывающего выполняются до BEGIN, существование участника подтверждается FK внутри транзакции. Гонка username решается UNIQUE, 23505 преобразуется в 409.

Сообщение: BEGIN → UPDATE строки chat с last_message_at=GREATEST(clock_timestamp(),last_message_at+1µs) → INSERT → COMMIT → 201. UPDATE сериализует писателей только одного чата и делает порядок времени устойчивым к откату часов, в том числе между API-процессами. Часы не уникальный ID: используется random UUID. FK дополнительно подтверждает, что sender — участник чата. Горячий чат ограничен одной row-lock очередью писателей.

SQL значения поступают как параметры $1…, динамическая часть строк состоит только из серверного выбора формы запроса/номера placeholder. Pool ограничен 10 соединениями; connect timeout 2 s, server statement timeout 2 s, lock timeout 1 s, HTTP request context 3 s. Redis budgets 80 ms на вызов, socket/pool 60 ms, retry отключён. Это ограничивает ожидание зависимости; KDF не имеет прерывания посередине вычисления, но одновременно допускаются максимум две работы.

Миграции embedded в binary, выполняются в одной транзакции с ledger и advisory xact lock. Изменённая уже применённая migration не принимается. Startup требует готовую БД; restart hook сначала останавливает API, перезапускает PostgreSQL/Valkey, ждёт ready БД и стартует API. Публичный тест ждёт HTTP readiness отдельно.

Аутентификация, cache и pagination

Регистрация хранит Argon2id: 64 MiB, 3 passes, 2 lanes, случайная соль 16 bytes и результат 32 bytes. Учитывается полный UTF-8 диапазон 12–128 code points без bcrypt truncation; проверены длинные emoji и двоеточие. Basic используется только для создания сессии, body пустой, неверные credentials дают одинаковый 401 и challenge. Неизвестный username проходит dummy KDF, без заявления абсолютной timing-security.

Opaque token: 32 random bytes, 256 bits, base64url. В sessions хранятся SHA-256 строки токена, user_id и абсолютный expires_at от часов БД. Bearer проверяется через sessions на каждом запросе; expired/revoked/unknown → 401 с Bearer challenge. X-User-Id игнорируется. Logout DELETE подтверждается до 204; кэш профиля не способен отменить отзыв. Входная сессия не JWT.

Valkey ключ profile:v1:<uuid>, public User JSON, TTL 300 s. Cache-aside: GET hit экономит SELECT users; miss/error читает PostgreSQL и пытается SET с отдельным ограниченным budget. Авторизация сессии всё равно требует SQL. Профиль неизменяемый в обязательном API, поэтому явной инвалидации нет. Будущий update/delete потребует новой политики. Кэш не критичен для ready; PostgreSQL критичен. Live проверяет процесс, ready — остановку и Ping БД.

Keyset: signed scope + (created_at,id), HMAC-SHA256 со стабильным локальным секретом. Курсор чужого чата/пользователя и повреждённая подпись дают 400. SQL использует chat_id=$1 AND (created_at,id)>($2,$3) ORDER BY messages.created_at,messages.id LIMIT limit+1; native UUID указан явно, чтобы текстовый SELECT alias не менял план сортировки. Возвращаются limit элементов, дополнительный определяет next_cursor; последняя запись не повторяется. Snapshot между страницами не обещается. Монотонность времени гарантирована для сообщений одного чата; для нового чата при откате часов возможно появление до уже выданной границы.

Строгий decoder и business Unicode limits сохранены. При неизвестном или чужом чате одинаковый 404. Каждому ответу соответствует X-Request-Id, у ошибки совпадающий request_id. Structured stdout-логи содержат шаблон route/метод/status/duration/request_id без body, query, паролей и токенов.

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

Критерий Команда / наблюдение Реальное доказательство
Skeleton/контракт сохранён make check; git diff исходного SHA по README/COURSE/contracts/tests пуст evidence/check.txt; Git diff
Минимум lab1 с новым auth make test, Unicode, membership, страницы, ошибки evidence/public-smoke.txt
SQL schema, PK/FK/UNIQUE Первая migration; работа на новом volume migration; clean-clone.txt
Атомарное создание чата Неизвестный второй участник после INSERT чата → 400, в БД нет частичного чата integration.json, student-tests.txt
Гонка username 4 concurrent регистрации: 1×201 + 3×409 integration.json
Argon2id и широкий пароль Проверка формата KDF в рабочей БД, HTTP emoji/colon, Go negative verification student-tests.txt; race-http.txt
Basic только для входа Basic на бизнес-пути 401; неверный password 401 public smoke; integration
Bearer, expiry, logout TTL=2 → 401, DELETE→204→401 при warm profile cache integration.json
X-User-Id не даёт доступа Один заголовок→401; вместе с Bearer не меняет владельца public smoke
Все данные и сессия переживают рестарт make test-persistence ACTION_SCRIPT=scripts/restart.sh; same token/message; StartedAt изменился у api/postgres/valkey integration.json; student-tests.txt
Повторная migration без дублей schema_migrations count=1 после рестартов integration.json
100 сообщений / 10 клиентов Проверка counts/IDs/text/order и cursor scope student-tests.txt
Race detector на реальном HTTP/PG make test-race → 100 уникальных подтверждённых сообщений race-http.txt
Реальное использование Valkey Key TTL 1..300, FLUSHDB → восстановление профиля с прежней сессией integration.json
Недоступность Valkey Запросы и POST→GET продолжаются, аноним не получает доступ integration.json
Недоступность PostgreSQL Live 200, ready 503, protected 503 в ограниченный срок integration.json
Параметры, pool, timeouts $1…; 10 connections; 2/1/3 s budgets исходный код
Индекс на ≥10k сообщений 100k total, 80k chat; Index Scan range, 51 строка, без Sort explain-history.txt; experiment.json
Docker/non-root/SIGTERM/secret-free logs PID1 messenger, UID10001, exit0, old session restored lifecycle.json
Трек 2: три индекса и запись 3×4 chat sizes×2 positions×2 client levels×3 repetitions experiment.json, experiment-summary.md
Трек 2: новое хранилище restore 100k сообщений, counts/fingerprint/5 samples совпали experiment.json backup_restore
Сборка из чистого clone Новые secrets/volumes, uncached build, smoke/persistence/lifecycle clean-clone.txt

go vet ./... завершился с кодом 0, stdout пуст. make check проверяет skeleton, а не приложение. Go-тест с настоящей БД локально skip без DATABASE_TEST_URL_FILE; make test-race включает его в Compose. PASS не является автоматическим выставлением оценки.

Исследование индексов

Гипотеза: индекс только chat_id не позволяет быстро перейти за cursor и выдать упорядоченную страницу; составной ключ включает обе задачи. INCLUDE полей может убрать heap fetch, но увеличит storage/write amplification. Поэтому сравниваются чтение, размер, batch запись и WAL, а не только TPS.

Метод: отдельный research-db, каждый запуск создаёт новую database. 100 000 synthetic сообщений, чаты 80 000 / 15 000 / 4900 / 100, fixed 128-symbol filler; seed выполняется SQL, без заявления скорости HTTP seed. PostgreSQL 2 CPU, 512 MiB, Docker Desktop Linux/arm64 на macOS arm64. Конкретный host и version/durability сохранены. Индексы рабочего API не меняются.

Для каждого варианта: VACUUM ANALYZE после seed, ANALYZE после смены индекса; первая страница и граница около 90%, limit 51; 1/4 pgbench клиентов, prepared запрос, прогрев 20 transactions/client, 100 transactions/client, 3 повтора. Всего 144 read-прогона + планы. Измеряется средняя transaction latency/TPS каждого прогона; таблица показывает медианы повторов. Это SQL, без auth/cache/HTTP/JSON. EXPLAIN (ANALYZE, BUFFERS, WAL) выполняет настоящий тот же SELECT.

Запись: одинаковая write_probe (PK + один выбранный secondary index), batch 1000 INSERT + COMMIT, 3 повтора и EXPLAIN/WAL. Между повторами TRUNCATE только write_probe; рабочие/fixture сообщения не удаляются. Это цена batch-транзакции на пустой таблице, а не sustained single-message API writes и не строгая статистическая оценка отличий в несколько миллисекунд.

Поздняя страница чата 80 000, один SQL-клиент:

Индекс latency ms TPS Размер KiB INSERT1000+COMMIT ms INSERT WAL bytes
chat_only 11.053 90.5 704 8.679 418474
composite 0.090 11144.5 5776 5.915 448576
covering 0.096 10378.8 24416 7.541 639392

Вывод: production использует composite. Большая поздняя страница получает сильное улучшение относительно chat_only. Covering в этом прогоне не дал выигрыша latency, при этом занимает примерно 4,2× места composite и генерирует больше WAL в batch-пробе. Одна установка индекса не гарантирует universal speedup всех запросов.

Cgroup наблюдения исследовательского PostgreSQL за окно всего варианта (включает setup; не API RSS и не пик памяти):

Индекс CPU % (100%=1 core) Memory до MiB Memory после MiB Окно s
chat_only 129.4 344.1 330.6 54.5
composite 16.8 329.9 335.5 18.2
covering 17.1 335.6 374.0 19.6

Memory включает shared buffers и page cache. Значения на границах окна не доказывают max RSS. Порядок вариантов фиксирован; данные warm, нагрузка closed-loop, прогоны короткие; влияние фоновой нагрузки и SQL-клиента не исключено.

Отдельная контрольная нагрузка настоящего HTTP API: три прогона POST по 5 s, 4 clients, no retry. Медиана успешных RPS 1456.6, медианы per-run p50/p95/p99 2.524 / 4.128 / 6.279 ms, ошибок 0. Raw: http-load-1/2/3.json. Это growing history, coordinated omission и percentiles только успешных ответов; не максимальная capacity и не сравнение SQL-индексов через HTTP.

Восстановление и отказы

pg_dump -Fc --no-owner --no-acl → pg_restore --single-transaction --exit-on-error в новую пустую БД на отдельном restore-db/restore_data volume. Сверены counts users/chats/members/messages, MD5 fingerprint всех message fields в детерминированном порядке и 5 выбранных полных записей. MD5 тут только checksum синтетической fixture, не password scheme. После restore выполнен ANALYZE.

Backup 0.317 s, pg_restore 0.5 s, dump 3021508 bytes. Восстановлены 100 000 сообщений; counts, fingerprint и samples совпали. В source после backup успешно добавлен marker: source 100001, restore 100000, marker отсутствует. Без WAL archive/PITR данные после snapshot могут потеряться; эксперимент не обещает максимум одну потерянную запись. Измерен restore-only RTO, без detection/provisioning/переадресации API.

Исследовательский SQL fixture использует synthetic-no-login password_hash и не является зарегистрированным API-пользователем. Сохранность настоящих Argon2id пользователей и сессий доказывается отдельным публичным persistence-сценарием. Dump не коммитится, tokens отсутствуют в evidence.

Воздействие Наблюдение Граница
API restart Same token, profile, message Данные в PostgreSQL, key курсора persistent
Full API+PG+Valkey restart Прежний token работает, данные/курсоры доступны; все StartedAt изменились Volumes не удаляются
Valkey flush/down Fallback users SELECT, запись сразу видна Возможны дополнительные SQL и задержка cache budget
PG down Live200, ready503, protected503 Аноним не становится доверенным; нет HA primary
TTL2 После ~2 s token401, старый long TTL token работает Срок от БД, не от локального cache TTL
Logout DELETE204, повтор401 при заполненном cache In-flight запрос до logout может завершиться
SIGTERM 0.208 s, exit0, OOM=false Shutdown budget5 s, Compose grace7 s
Backup cutoff Полное совпадение snapshot, позже добавленного marker нет Без WAL archive отсутствует PITR

Durability проверена: fsync=on, synchronous_commit=on, full_page_writes=on. Эти локальные гарантии не защищают от потери всего host/disk; volume не backup.

Ограничения и развитие

Локальный учебный HTTP, только синтетические credentials; для удалённой демонстрации нужен TLS. Один PostgreSQL primary, один API, нет HA/failover хранилища или PITR. Учебный POSTGRES_USER имеет роль bootstrap-superuser; для production нужно разделить migration owner и минимальную runtime-role. Не реализованы delete/update, periodic session cleanup, rate limiting login, idempotent POST lab3, password parameter migration, circuit breaker/singleflight и внешнее резервное хранение.

Исчезновение Valkey допускается только потому, что это cache профилей, а не authoritative sessions. Hot-chat row lock ограничивает write concurrency. Request deadlines ограничивают I/O, KDF уже начавшейся работы не прерывается. Курсор HMAC-подписан, но не encrypted. Snapshot между страницами не обещается. Research про SQL и batch INSERT; контрольный HTTP load не даёт универсальной оценки throughput.

Материалы защиты: DEFENSE.md (разбор кода, примеры, 26 вопросов и 12 заданий самопроверки), QUICKSTART.md, postman/lab2.postman_collection.json.

Первичные источники