Files

108 lines
15 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Лабораторная 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-проверки готовятся заранее, чтобы уложиться в десятиминутный лимит.