forked from mtusi2026/mtusi2026lab2
108 lines
15 KiB
Markdown
108 lines
15 KiB
Markdown
# Лабораторная 2: хранение, сессии и шардирование
|
||
|
||
## Реализация
|
||
|
||
Возможности lab1 перенесены на PostgreSQL: пользователи, чаты, участники, сообщения и сессии сохраняются после перезапуска. Пароли обрабатываются Argon2id; Basic используется при входе, Bearer — для остальных операций. Сессия имеет фиксированный TTL и немедленно отзывается при logout. Valkey хранит кэш профилей и состояние rate limiter: общий и пользовательский лимиты, группы auth/read/write, слоты одновременного выполнения.
|
||
|
||
Пользовательские ключи распределяются consistent hashing между тремя Valkey. Глобальные ограничения проверяет `shard0`. Это клиентское шардирование самостоятельных узлов, а не Redis Cluster. Controller, service и store связаны интерфейсами через Fx. Подробности: [ARCHITECTURE](ARCHITECTURE.md), требования: [SPEC](docs/SPEC.md).
|
||
|
||
Целевой объём: уровни 3 и 4, исследовательский трек 2 «План запроса и восстановление». Основной стенд — Kubernetes; допустимость замены Compose/Swarm преподавателем пока не подтверждена.
|
||
|
||
## Запуск
|
||
|
||
Нужны Helm, kubectl, Docker buildx, curl, jq и openssl. Для публичных проверок задания дополнительно нужен Python 3.9+. Для тестов Go — toolchain из `go.mod` и golangci-lint. Контекст по умолчанию `dev`, namespace `highload-applications`, Helm release `lab2`. Namespace общий с другими лабораторными; этот чарт управляет только ресурсами lab2.
|
||
|
||
Все параметры стенда находятся в [values.yaml](charts/messenger/values.yaml): опубликованный образ по digest, количество шардов, ресурсы, размеры дисков и окружение API. PostgreSQL — 17.6-alpine, Valkey — 8.1.3-alpine. По умолчанию используется default StorageClass; другой класс нужно задать перед первой установкой.
|
||
|
||
```sh
|
||
make init # namespace и секреты; пароль БД сохраняется, pull-secret обновляется
|
||
make deploy # установка или обновление Helm release
|
||
make port-forward # держать терминал открытым; localhost:8080
|
||
```
|
||
|
||
Registry — `asisti.registry.twcstorage.ru/mtusi2026lab2`. `make init` читает токен из `~/.secrets/twc-registry-token`, обновляет `registry-pull` и создаёт случайный пароль PostgreSQL только при отсутствии Secret БД. Секреты не входят в chart, values или Git. Chart использует их по имени. PVC сохраняются при рестарте и upgrade.
|
||
|
||
Для публикации изменённого приложения:
|
||
|
||
```sh
|
||
make build-push
|
||
```
|
||
|
||
Из `evidence/image-build.json` перенести значение `containerimage.digest` в `image.digest` файла values, затем выполнить `make deploy`. Для другого окружения: `make deploy VALUES=path/to/values.yaml KUBE_CONTEXT=... NAMESPACE=...`. Для временного выбора образа допускается `IMAGE_DIGEST=sha256:...`; следующий deploy снова использует digest из values.
|
||
|
||
Изменение числа шардов требует остановки API:
|
||
|
||
```sh
|
||
make reshard SHARDS=2 # или 3; простой включает ожидание lease 31 секунду
|
||
```
|
||
|
||
После успешной команды изменить `valkey.shards` в values. Обычный upgrade с работающим API отклоняет смену кольца. При ошибке reshard API остаётся остановленным; исправить причину и повторить команду. Если API было несколько реплик, задать `API_REPLICAS` при reshard.
|
||
|
||
## Проверки
|
||
|
||
Во втором терминале:
|
||
|
||
```sh
|
||
make ready
|
||
make check
|
||
make test
|
||
make test-persistence ACTION_SCRIPT=scripts/restart.sh
|
||
make chart-check
|
||
```
|
||
|
||
Persistence перезапускает API, PostgreSQL и все Valkey, затем читает прежние данные с прежней сессией. Туннель автоматически переподключается. Доступ к API открыт только на loopback; внешнего ingress нет.
|
||
|
||
Go-проверки: `make vet`, `make lint`, `make test-student`. Полная проверка `make coverage` требует `DATABASE_URL`, `VALKEY_SHARDS`, `TEST_DATABASE_URL`, `TEST_VALKEY_ADDRESS`, указывающих на **изолированные тестовые** зависимости. Она запускает race, интеграционные тесты, настоящий сервер, smoke и SIGTERM; shell/awk объединяют профили и проверяют ≥90% statements отдельно в каждом исполняемом Go-файле. CI создаёт зависимости автоматически. Без TEST-переменных интеграционные тесты пропускаются.
|
||
|
||
Проверки после перехода на Helm: [adoption и upgrade](evidence/helm-deployment.txt), [smoke](evidence/helm-smoke.txt), [persistence](evidence/helm-persistence.txt), [coverage](evidence/helm-coverage-per-file.json). Более ранние измерения и их область действия перечислены в [evidence/README](evidence/README.md). Удалённый CI не подтверждён; актуальная публикация и PR указаны ниже.
|
||
|
||
## SQL-эксперимент
|
||
|
||
```sh
|
||
make research
|
||
```
|
||
|
||
Команда создаёт отдельный временный PostgreSQL в Docker, применяет миграцию приложения и запускает [SQL-сценарий](student-tests/research.sql). Профиль: 100 000 сообщений, распределение по чатам 90% / 9% / 1%, два индекса — `chat_id` и `(chat_id,created_at,id)`. Для каждого выполняются три поздних keyset-чтения и три вставки 1000 строк с rollback. Затем полный логический dump восстанавливается в новую БД; сверяются количество, checksum сообщений и выборка записей. После проверки контейнер удаляется.
|
||
|
||
Гипотеза: составной индекс ускоряет поздние страницы за счёт дополнительной работы при записи. Планы, время операций, ограничения ресурсов, контрольные суммы исходников и результат восстановления: [raw results](evidence/sql-research-helm.txt). Более раннее измерение с агрегированными данными: [sql-research-domain.json](evidence/sql-research-domain.json). Новый прогон также подтвердил выигрыш чтения. Диапазоны времени вставки перекрываются; трёх повторов недостаточно для вывода об устойчивом росте стоимости записи.
|
||
|
||
Эксперимент синтетический, на одном Docker-хосте, без конкурентных записей. Восстановление в другую БД того же instance подтверждает логический backup/restore; оно не проверяет потерю узла или PITR. Данные после момента dump в таком backup отсутствуют.
|
||
|
||
## Ограничения
|
||
|
||
- Один PostgreSQL и глобальный координатор — точки отказа; репликация и автоматический failover не реализованы. При недоступности limiter новые запросы отклоняются.
|
||
- Расширение кольца требует простоя API. Обязательные данные остаются в PostgreSQL, кэш прогревается заново.
|
||
- Cursor подписан ключом процесса: после рестарта обход страниц начинается заново. Данные и действующие сессии сохраняются.
|
||
- Истёкшие сессии отвергаются запросом к БД, но фоновая очистка строк ещё не реализована.
|
||
- PVC на `microk8s-hostpath` обеспечивает сохранность при рестарте pod; он не заменяет резервную копию.
|
||
|
||
Версии Go и зависимостей закреплены в `go.mod`, `go.sum` и Dockerfile. Источники решений: [ADR-0001](docs/decisions/0001-postgres-sessions-shards.md), [ADR-0002](docs/decisions/0002-helm.md). При разработке использован Codex. Автор: Агапов Владислав, БПИ2303; PR №52 указан ниже.
|
||
|
||
## Репозиторий Gitea
|
||
|
||
Решение перенесено 2026-10-15 в `ssh://git@gitea.privcloud.tech:2222/vlad_marlo/mtusi2026lab2.git`. Go-модуль и imports обновлены под новый адрес. [Проверки переноса](evidence/gitea-transfer-tests.txt) относятся к новой рабочей копии; прежние измерения и опубликованный образ относятся к снимку от 2026-10-07. Повторное развёртывание, новый image build и Git push при переносе не выполнялись.
|
||
|
||
## Исправление классификации отказов — 2026-10-16
|
||
|
||
В PostgreSQL-адаптере недоступность соединения и timeout выделены в отдельную категорию. HTTP возвращает `503 unavailable` с безопасным сообщением, включая отказ на этапе проверки сессии. Неожиданные ошибки SQL сохраняют `500 internal_error`.
|
||
|
||
```sh
|
||
make test-faults
|
||
```
|
||
|
||
Сценарий воспроизводится из отдельного clone с Docker, curl, jq, rg, OpenSSL и shasum. Он создаёт собственные PostgreSQL 17.6 и Valkey 8.1.3, собирает API из рабочего дерева, проверяет реальные `stop` и `pause` каждого backend и удаляет временные ресурсы. Ни существующие Docker-контейнеры, ни dev-кластер не используются. В начале вывода сохраняются базовая Git-ревизия и SHA-256 исходников: проверенный снимок включает ещё не закоммиченные изменения.
|
||
|
||
[Результат](evidence/fault-regression.txt): все четыре сценария прошли. История с действующей сессией возвращала 503 за 0.002–0.508 с; зависание ограничено timeout 500 мс и внешним HTTP deadline 3 с. Проверены отсутствие анонимного доступа и обхода через X-User-Id/повреждённый/неизвестный Bearer, безопасный error envelope, liveness/readiness. После каждого восстановления исходная сессия читает то же сообщение без повторного входа. При отказе Valkey admission отклоняет запрос до аутентификации, поэтому анонимный запрос тоже получает 503, а не данные.
|
||
|
||
Свежие [race/integration/coverage](evidence/fault-coverage.txt), [покрытие по файлам](evidence/fault-coverage-per-file.json), [lint](evidence/fault-lint.txt), [vet](evidence/fault-vet.txt) и [contract check](evidence/fault-contract.txt) прошли. Все 57 исполняемых Go-файлов имеют покрытие ≥90%. Fault-сценарий добавлен в application CI; удалённый runner этим локальным прогоном не проверяется. Кластерный образ в рамках этого исправления не обновлялся.
|
||
|
||
Работа сдаётся в [PR №52](https://gitea.privcloud.tech/mtusi2026/mtusi2026lab2/pulls/52), ветка `main` → `master`, автор Агапов Владислав, БПИ2303.
|
||
|
||
## Timeweb и повторное развёртывание — 2026-10-16
|
||
|
||
Релиз `lab2` удалён через Helm и установлен заново в `dev / highload-applications`. Применён образ кода `87e1e5d` из Timeweb, digest закреплён в [values](charts/messenger/values.yaml); [метаданные сборки](evidence/timeweb-image-build.json), [проверка registry](evidence/timeweb-image-inspect.txt), [установка](evidence/timeweb-reinstall.txt). Используется Secret `registry-pull`; пароль БД не менялся. Другие releases не переустанавливались.
|
||
|
||
Четыре PVC сохранили UID и привязку к прежним PV ([до](evidence/timeweb-pvc-before.txt), [после](evidence/timeweb-pvc-after.txt)). До запуска новых тестов совпали количества пользователей/чатов/сообщений: 36/12/18 ([до](evidence/timeweb-counts-before.txt), [после](evidence/timeweb-counts-after.txt)). Это проверка количества, не полная сверка содержимого БД. Полный цикл HTTP проверяется отдельно: [smoke](evidence/timeweb-smoke.txt), [persistence](evidence/timeweb-persistence.txt).
|
||
|
||
[План защиты на 9 минут 30 секунд](docs/DEFENSE.md) содержит порядок демонстрации, команды и ограничения результатов. Эксперименты SQL и fault-проверки готовятся заранее, чтобы уложиться в десятиминутный лимит.
|