forked from mtusi2026/mtusi2026lab3
Prepare verified laboratory 3 implementation and evidence
This commit is contained in:
@@ -0,0 +1,62 @@
|
||||
# Лабораторная 3. Балансировка и отказ API-реплики
|
||||
|
||||
Автор: Медведев Андрей Михайлович, БПИ2303. Целевая оценка: 5, трек 1 «Цена масштабирования». Реализация, эксперименты и ограничения описаны ниже; оценку выставляет преподаватель. Исходный skeleton: https://gitea.privcloud.tech/mtusi2026/mtusi2026lab3. Команды находятся в [RUN.md](RUN.md). Код, тесты и отчёт подготовлены с помощью Codex и проверены независимым агентом.
|
||||
|
||||
## Архитектура
|
||||
|
||||
Клиент обращается к HAProxy, который распределяет запросы между двумя Go API. PostgreSQL и Valkey общие. Сессии проверяются в PostgreSQL; Valkey кэширует неизменяемые профили. Sticky sessions нет. API не публикуют свои порты на host, единственный вход привязан к localhost:28203. Контейнеры имеют CPU/RAM limits, container_name не задаётся.
|
||||
|
||||
HAProxy проверяет /health/ready каждые 500 мс, исключает backend после двух неудач и возвращает после одного успеха. Docker DNS разрешается повторно через resolver с коротким hold, а не только при старте LB. Конфигурация рассчитана на 1–4 реплики, включая эксперимент 1/2/4. Каждая API-реплика возвращает свой стабильный X-Instance-Id, соответствующий hostname контейнера. Автоматических прозрачных повторов произвольных POST нет.
|
||||
|
||||
SIGTERM переводит readiness в 503 и прекращает приём новых соединений. Graceful shutdown API ограничен 8 секундами, stop_grace_period контейнера равен 10 секундам. Для обычных запросов действует контекст 5 секунд; connection/statement/lock timeouts PostgreSQL согласованы с этим бюджетом.
|
||||
|
||||
## Общая идемпотентность
|
||||
|
||||
Idempotency-Key обязателен для POST сообщения и проверяется по ASCII pattern и длине 1–128. Область ключа задаётся пользователем и чатом; HTTP-операция фиксирована самим endpoint. В PostgreSQL хранятся hash семантического payload, ID сообщения и expiry на 24 часа.
|
||||
|
||||
Резервирование ключа, списание квоты, создание сообщения и ссылка результата выполняются одной транзакцией. Конкурентный повтор ждёт общий UNIQUE constraint; после подтверждения читает тот же Message с 201. Другой payload даёт 409. При откате нет ни сообщения, ни окончательного результата ключа. Неподтверждённый клиентский ответ можно повторить через другую реплику; сессия и доступ к чату проверяются заново.
|
||||
|
||||
Миграции запускает один отдельный service. Проверенная поочерёдная замена использует уже подготовленную совместимую схему. Произвольное несовместимое изменение схемы под трафиком не заявляется.
|
||||
|
||||
## Проверки обязательных уровней
|
||||
|
||||
Публичный smoke и дополнительные HTTP-проверки подтвердили авторизацию, страницы, rollback, конкурентную регистрацию, двенадцать одновременных повторов одного сообщения, конфликт payload и одну сессию через разные реплики. Результаты находятся в evidence/smoke.txt и evidence/acceptance.txt. Persistence сохранил данные и исходный токен после рестарта всех stores и API; файлы restart-before/after фиксируют реальные container ID и StartedAt.
|
||||
|
||||
Каждая API-реплика была остановлена по TARGET_INSTANCE_ID, вторая продолжила чтение и запись. Скрипт проверяет, что выбранный контейнер относится к нужному Compose-проекту; факт остановки записан в stopped-1/2.txt. Public failover учитывает переходные ошибки, проверяет сохранность и отсутствие дублей. Результаты находятся в evidence/failover-1.txt и evidence/failover-2.txt.
|
||||
|
||||
Обязательные операции предыдущей лабы сохраняют свои правила. Source check, OpenAPI validation, Go race tests, lint/depguard, Docker build и генерация проверяются отдельно от smoke. Авторские тестовые данные изолированы случайным prefix, cleanup отказывается удалять чат с посторонним участником. Compose manifest и project name закреплены явно.
|
||||
|
||||
## Исследование масштабирования
|
||||
|
||||
Гипотеза: дополнительные API помогают, только пока они являются узким местом. Нагрузка здесь намеренно состоит из отправки сообщений одним пользователем в один чат. Измерялся closed-loop клиент с concurrency 16, по 5 секунд, два повтора; база данных очищалась только внутри отдельного одноразового исследовательского проекта перед каждым запуском.
|
||||
|
||||
В первой серии суммарный бюджет API постоянен: 2 CPU и 2048 МиБ. Во второй каждая реплика получает 1 CPU и 512 МиБ. PostgreSQL, Valkey и LB сохраняют одинаковые ресурсы. Фактические NanoCpus, Memory, число контейнеров и PG_MAX_CONNS проверялись через Docker и API; снимались CPU/RAM и wait events PostgreSQL. Все запросы основной серии завершились без HTTP-ошибок.
|
||||
|
||||
| Серия | Реплики | CPU API суммарно | RAM API суммарно, МиБ | Успешные RPS, среднее | p95, мс, среднее |
|
||||
| --- | --- | --- | --- | --- | --- |
|
||||
| Постоянный бюджет | 1 | 2 | 2048 | 117,70 | 171,00 |
|
||||
| Постоянный бюджет | 2 | 2 | 2048 | 112,99 | 287,81 |
|
||||
| Постоянный бюджет | 4 | 2 | 2048 | 116,69 | 346,31 |
|
||||
| Рост ресурсов | 1 | 1 | 512 | 116,71 | 175,68 |
|
||||
| Рост ресурсов | 2 | 2 | 1024 | 117,87 | 258,62 |
|
||||
| Рост ресурсов | 4 | 4 | 2048 | 117,09 | 342,18 |
|
||||
|
||||
Данные и диапазоны двух повторов сохранены в evidence/research/run-ImJmOz/. Графики scaling.svg и pool.svg строятся из исходных JSON, а не из переписанных вручную чисел.
|
||||
|
||||
Для этого профиля насыщение видно уже при одной реплике: добавление API/CPU не повышает throughput, а хвост latency растёт. В 160 снимках активных SQL-запросов ожидание WalSync наблюдалось 151 раз, transactionid 139 раз; категории могут одновременно присутствовать в одном снимке. В исходном коде каждое сообщение обновляет квоту одного sender, поэтому конкурентные транзакции сериализуются на его строке и подтверждают WAL. Число API не снимает эту общую границу.
|
||||
|
||||
## Подтверждённое улучшение
|
||||
|
||||
Отдельно проведена серия ABBA с pool=8 → 1 → 1 → 8 при неизменных 1 API, 2 CPU, 2048 МиБ и том же профиле. Результаты находятся в evidence/research/run-sB0hdP/. Средние успешные RPS составили 117,78 → 118,52, то есть практически не изменились. Средний p95 снизился с 166,86 до 145,97 мс; оба повтора с pool=1 оказались ниже обоих с pool=8.
|
||||
|
||||
Это подтверждённое улучшение хвостовой задержки на одном горячем sender: меньшая конкуренция за общий SQL-ресурс уменьшает очереди, но не ускоряет COMMIT. Для независимых пользователей и другого хранилища вывод не переносится автоматически. Общий default pool=8 сохранён; экспериментальная настройка доступна через PG_MAX_CONNS.
|
||||
|
||||
## Замена под нагрузкой и ограничения
|
||||
|
||||
В том же отдельном проекте обе исходные API по очереди заменены новыми контейнерами под непрерывной 30-секундной нагрузкой. Между заменами проверялась готовность двух реплик; успешные записи должны были продолжаться, а генератор оставаться активным. Сохранены старые ID и количества сообщений до/после каждой замены.
|
||||
|
||||
Получено 2684 успешных запроса и 46 переходных ошибок, доля ошибок 1,685%, успешные RPS 89,27. Это допустимые обнаруженные ошибки во время замены, а не zero-downtime обещание. Проверена замена контейнеров одного собранного образа; upgrade с несовместимой миграцией не испытывался.
|
||||
|
||||
Стенд находится на одном host и имеет единственные PostgreSQL, LB и storage. Поэтому отказ API проверен, а потеря host/БД/LB не покрыта. Closed-loop клиент имеет coordinated omission; latency относится только к успешным запросам, ошибки считаются отдельно. Серии короткие и не доказывают универсальный предел сервера. Объёмы, ресурсы, raw JSON и ограничения сохранены для повторения.
|
||||
|
||||
На защите показать две реальные реплики с одной сессией, конкурентный одинаковый ключ, остановку каждой реплики, повтор без дубля, persistence и графики. Объяснить, почему четыре API не превращают единственную PostgreSQL в отказоустойчивую БД и не отменяют транзакционную сериализацию.
|
||||
@@ -0,0 +1,74 @@
|
||||
# Запуск лабораторной 3
|
||||
|
||||
> Историческая инструкция Compose/HAProxy. Основной путь теперь описан в ../../RUN.md. Для старых action helpers явно задайте VP_RUNTIME=compose; прежний runner исследования сохранён как student-tests/research-compose.ts. Числа этого варианта не являются измерениями k3s/Pingap.
|
||||
|
||||
Автор: Медведев Андрей Михайлович, БПИ2303. Исходное задание и контракт сохранены в README.md и contracts/. Реализация находится в backend/, дополнительные проверки в student-tests/.
|
||||
|
||||
Нужны Docker Engine с Compose, Bun 1.4 и Python 3.9+. Для Go-тестов на хосте нужен Go 1.27.2 или новее. Проверенный стенд: Linux x86_64, Docker 29.9.2, Compose 5.6.1, Bun 1.4.4; образ компилируется Go 1.27.2. Образы PostgreSQL 18.6 и Valkey 9 закреплены digest в compose.yaml.
|
||||
|
||||
Команды выполняются из этого каталога. scripts/compose.sh закрепляет manifest и имя vp-lab3-medvedev, чтобы переменные другого проекта не перенаправили операции.
|
||||
|
||||
```sh
|
||||
bun --no-env-file scripts/bootstrap.ts
|
||||
./scripts/compose.sh up -d --build
|
||||
BASE_URL=http://127.0.0.1:28203 bun --no-env-file student-tests/wait.ts
|
||||
python3 -m venv .venv
|
||||
.venv/bin/pip install -r requirements-dev.txt
|
||||
make check
|
||||
make validate PYTHON=.venv/bin/python
|
||||
make test BASE_URL=http://127.0.0.1:28203
|
||||
BASE_URL=http://127.0.0.1:28203 bun --no-env-file student-tests/acceptance.ts
|
||||
make test-persistence BASE_URL=http://127.0.0.1:28203 ACTION_SCRIPT=scripts/restart.sh
|
||||
cd backend
|
||||
go test -race ./...
|
||||
go tool golangci-lint run
|
||||
go generate ./...
|
||||
```
|
||||
|
||||
Bootstrap создаёт отдельные случайные учебные credentials в .local/ и не печатает их. Каталог исключён из git и Docker context. Существующие файлы не перезаписываются. Миграции запускает отдельный service migrate; API не выполняет их конкурентно.
|
||||
|
||||
HTTP доступен только через localhost. Все данные тестов синтетические; публичные тесты сохраняют свой набор данных для демонстрации, дополнительные acceptance-тесты удаляют только свой случайный набор. Пароли и сессии не выводятся в отчёты.
|
||||
|
||||
Обычная остановка сохраняет volumes:
|
||||
|
||||
```sh
|
||||
./scripts/compose.sh stop
|
||||
```
|
||||
|
||||
Повторный запуск с сохранением данных:
|
||||
|
||||
```sh
|
||||
./scripts/compose.sh up -d
|
||||
```
|
||||
|
||||
Только для намеренного полного сброса собственных учебных данных:
|
||||
|
||||
```sh
|
||||
./scripts/compose.sh down --volumes
|
||||
```
|
||||
|
||||
Для проверки отказа запустите публичный сценарий. Он передаёт реальный TARGET_INSTANCE_ID hook-скрипту; после проверки верните обе реплики и дождитесь готовности.
|
||||
|
||||
```sh
|
||||
make test-failover BASE_URL=http://127.0.0.1:28203 ACTION_SCRIPT=scripts/stop-one.sh
|
||||
./scripts/compose.sh up -d
|
||||
BASE_URL=http://127.0.0.1:28203 bun --no-env-file student-tests/wait.ts
|
||||
```
|
||||
|
||||
Чтобы проверить вторую реплику, повторите сценарий после восстановления; фактический остановленный контейнер записывается в evidence/stop-one-after.txt.
|
||||
|
||||
Трек 1 запускается на omarchy без игры; скрипт проверяет это до и после замеров. Он создаёт отдельный случайный Compose-проект на localhost:28303, сравнивает 1/2/4 реплики, выполняет ABBA для пула и замену под нагрузкой, затем удаляет только свои containers/volumes. Обычный демонстрационный стенд сохраняется.
|
||||
|
||||
```sh
|
||||
bun --no-env-file student-tests/research.ts
|
||||
bun --no-env-file student-tests/research.ts --pool-only
|
||||
```
|
||||
|
||||
Первой команды достаточно для полного исследования; вторая отдельно повторяет четыре замера пула. Результат каждого запуска появляется в новом evidence/research/run-*. Для приложенных графиков:
|
||||
|
||||
```sh
|
||||
.venv/bin/pip install -r requirements-plots.txt
|
||||
.venv/bin/python student-tests/plot_research.py evidence/research/run-ImJmOz/summary.json --pool-summary evidence/research/run-sB0hdP/summary.json
|
||||
```
|
||||
|
||||
Подтверждённые результаты и ограничения перечислены в REPORT.md. Автоматические проверки не выставляют оценку преподавателя.
|
||||
@@ -0,0 +1,15 @@
|
||||
# Implementation plan and boundaries
|
||||
|
||||
Archived: this inherited lab2 plan is retained as historical context only. The completed lab3 implementation, results and limitations are documented in ../../REPORT.md; startup instructions are in ../../RUN.md.
|
||||
|
||||
This repository carries our lab1 domain, pagination, HTTP/error handling, bounded queue and shutdown code into the original lab2 skeleton. The lab1 memory adapter and its obsolete HTTP identity tests are not carried forward.
|
||||
|
||||
PostgreSQL is authoritative for users, passwords, sessions, chats, membership and messages. Valkey caches immutable public profiles for 60 seconds; no chat/message/session cache is used. Authentication always reads the session from PostgreSQL, and cache failure falls back to PostgreSQL within an 80 ms budget. Logout deletes the persisted token hash. Cache contents contain no password or bearer token.
|
||||
|
||||
Transactions: chat allocation + chat row + membership; sender quota + message; session owner lock + expiry cleanup + session insertion. PostgreSQL constraints enforce username uniqueness and foreign keys. Maximums: 1000 created chats and 1,000,000 messages per owner; 100 unexpired sessions. No user data is silently deleted. The history index covers `(chat_id,created_at,id)` and queries fetch only `limit+1` rows. Keyset traversal is not a snapshot; writes whose wall-clock timestamps fall before a consumed cursor can be missed during concurrent traversal.
|
||||
|
||||
Argon2id uses a random 16-byte salt, 32 MiB, two iterations, one lane, 32-byte result. Tokens use 32 random bytes; PostgreSQL stores only SHA-256 of the token. SHA-256 is appropriate for high-entropy tokens, not passwords. The API gate bounds concurrent KDF calls to four. PostgreSQL pool: eight connections, statement timeout 2 s, lock timeout 1 s, connect timeout 1 s; request context 5 s.
|
||||
|
||||
Readiness checks PostgreSQL. Valkey is optional to safe operation; its absence is observable through cache hit statistics and failure tests, not an anonymous-authentication fallback. HTTP is bound to localhost and uses only generated synthetic data.
|
||||
|
||||
Research: compare history queries over at least 100,000 skewed messages; restore a backup into a new database, compare row counts and selected message bytes. See `REPORT.md` for actual results; planned experiments are not evidence.
|
||||
@@ -0,0 +1,36 @@
|
||||
# k3s and Pingap migration
|
||||
|
||||
Completed implementation specification. Native source, acceptance, measurements and reports are complete. Final ZIP verification and file hashes are recorded separately by the parent delivery workflow in DELIVERY.json.
|
||||
|
||||
Approved by the owner: replace the lab3 and lab4 runtime with k3s + Pingap, following the azur-games ingress pattern. Keep the existing Compose path until equivalent acceptance passes. Preserve original public contracts, tests and assignment files. No external publication or submission is authorized.
|
||||
|
||||
Use a separate single-server k3d cluster per lab on the test host, with an explicit private kubeconfig and context. Kubernetes resources and Pingap TOML live in git; generated synthetic credentials remain outside git and enter Kubernetes Secrets through stdin. This is a disposable coursework stand, not a multi-host HA cluster. No changes to the azur-games cluster are required.
|
||||
|
||||
Pingap is a Deployment behind a LoadBalancer Service. API uses a headless Service, DNS discovery and readiness. PostgreSQL, Valkey and lab4 RustFS use PVCs and private Services. Migrations and S3 bootstrap are bounded Jobs. User data stays outside API pods. Local k3d uses the already installed k3s image; image digests are pinned.
|
||||
|
||||
## Acceptance cases before implementation
|
||||
|
||||
| Situation | Example | Expected result | Level |
|
||||
| --- | --- | --- | --- |
|
||||
| Wrong target | foreign cluster/context, missing receipt, malformed name | reject before mutation | helper unit |
|
||||
| Startup | new isolated cluster and empty volumes | migrations, dependencies, API and Pingap ready | integration |
|
||||
| Discovery | two API pods, scale 1/2/4 | distinct real pod IDs, DNS updates | HTTP integration |
|
||||
| API failure | delete the actual serving pod | surviving API serves within public test deadline, no duplicates | e2e |
|
||||
| Rolling replacement | restart API Deployment during writes | readiness, continuing writes, measured errors | e2e |
|
||||
| Persistence | restart API, PostgreSQL, Valkey, Pingap and S3 | old session, messages and original bytes survive | e2e |
|
||||
| Private S3 | anonymous object read, unrelated bucket creation | denied | integration |
|
||||
| Partial upload | S3 or SQL error after write | existing reconciliation guarantees preserved | isolated integration |
|
||||
| Resource limits | fixed and growing API budget, pool ABBA | verify actual requests/limits and collect new measurements | experiment |
|
||||
| Memory | ten uploads and extreme PNG decoder | bounded rejection and measured memory | experiment |
|
||||
|
||||
Failures include unavailable DNS/API/store, wrong namespace, unclaimed cluster, failed Jobs, stale readiness, rollout timeout and cleanup failure. Never turn a failed inventory read into permission to create or remove a cluster. Existing HAProxy evidence remains explicitly historical and is not relabeled as Pingap evidence.
|
||||
|
||||
## Progress
|
||||
|
||||
- [x] Runtime and guarded operational helpers; native image inventory, scoped stdin, Pod UID ownership and cleanup guards verified.
|
||||
- [x] Equivalent public and student acceptance for lab3 and lab4. Smoke, full persistence, both failover scenarios and lab4 isolated reconciliation passed. Final HTTP acceptance passed409/457 assertions; SQL stdin and replaced original Pod UIDs verified.
|
||||
- [x] New measurements and reports:16 lab3 samples plus a30-second rollout, ten concurrent image uploads and the extreme PNG/Adam7 memory Job. Game guards returned exactly1. Historical Compose numbers stay separate.
|
||||
- [x] Independent runtime review and verified source sync:89 lab3 and115 lab4 source files match the remote checked copy.
|
||||
- [x] Final native source and reports prepared for clean local commits and archive generation. CRC and complete byte-equality receipts are maintained separately in the parent DELIVERY.json.
|
||||
|
||||
Independent read-only runtime/model/experiment-helper review found no remaining confirmed P1/P2. All84 unit cases and read-only Biome formatting/lint passed. Checked native source hashes are retained with the evidence. Independent review also verified the new measurements/report, including the negative pool result and the41.04% p95 reduction at4→2 API with equal total limits.
|
||||
Reference in New Issue
Block a user