Files

49 lines
9.0 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
Версия 4, локальная реализация и развёртывание в Kubernetes dev проверены. Цель: весь уровень 3 и 4, один исследовательский трек уровня 5; дополнительно распределённый admission и демонстрация шардирования.
Нормативные источники: [задание](../README.md), [курс](../COURSE.md), [контракт](../contracts/README.md), [OpenAPI](../contracts/openapi.json), [правила сдачи](../CONTRIBUTING.md). Обязательные контракты и публичные проверки сохраняются.
| ID | Требование | Критерий приёмки |
| --- | --- | --- |
| L2-REQ-01 | Перенести бизнес-возможности lab1, хранить пользователей, чаты, участников и сообщения в PostgreSQL | Публичный smoke; уникальность username; FK; атомарное создание чата; миграции с нуля и повторно |
| L2-REQ-02 | Пароль 12–128 Unicode code points, библиотечный KDF; Basic только при входе; случайная opaque Bearer-сессия | Неверный пароль, UTF-8, expiry, logout, игнорирование X-User-Id, WWW-Authenticate |
| L2-REQ-03 | PostgreSQL — источник истины для сессий; Redis/Valkey — осмысленный кэш | Сохранность после полного рестарта; TTL не продлевается; отзыв виден сразу; отказ кэша не предоставляет доступ |
| L2-REQ-04 | Ограниченные pool и timeout; ошибки зависимостей не раскрывают секреты | Изолированные проверки отказа PostgreSQL и Valkey; readiness |
| L2-REQ-05 | Keyset pagination, индекс истории, read-after-write | EXPLAIN ANALYZE BUFFERS на ≥10 000 сообщений; отсутствие повторов неизменной истории |
| L2-REQ-06 | Redis/Valkey admission: глобальные и пользовательские лимиты, группы auth/read/write | Конкурентные запросы не превышают лимит; освобождение lease и TTL при аварии; отказ хранилища закрывает admission |
| L2-REQ-07 | 2–3 шарда и клиентское consistent hashing | При добавлении третьего узла перемещается только часть ключей; сохранение лимитов при смене topology; явное описание SPOF |
| L2-REQ-08 | Проверить DIP и соглашения Go | Controller→service interface; service→store/client interfaces; gofmt, vet, lint, race; ≥90% statements в каждом исполняемом Go-файле, порог CI |
| L2-REQ-09 | Воспроизводимый стенд и restart hook | Bootstrap из отдельного clone, сохранённые volumes, публичный persistence |
| L2-REQ-10 | Полный исследовательский трек | Трек 2: ≥100 000 сообщений, ≥2 варианта запросов/индексов, стоимость записи, backup/restore и сверка; проверен в изолированном PostgreSQL |
## Инварианты
Авторизация остаётся в service. Store получает проверенные UUID и обеспечивает транзакции и ограничения. Сессии хранят hash токена; парольный hash никогда не попадает в HTTP User. Кэш не является основанием обойти проверку действительности сессии. Чужой чат возвращает 404. История читается из PostgreSQL для read-after-write.
Глобальный лимит требует общего координатора: распределение пользовательских ключей по шардам само по себе не даёт атомарного общего лимита. Изменение topology выполняется управляемо; нельзя потерять активные счётчики и предоставить новый burst.
## Открытые вопросы
- Основной реализованный стенд — Kubernetes dev; формальное принятие преподавателем отдельно не подтверждено. Второй путь оркестрации не реализуется.
- Исследовательский трек 2 реализован; результаты и ограничения приведены в REPORT.
- Git-публикация и принятие преподавателем не выполнены; commit/push/PR не выполняются без поручения.
## Развёртывание в dev
L2-REQ-11: использовать существующий Yandex Container Registry `cr.yandex/crpv8disueqk68pv29jg`, отдельный image `mtusi2026lab2`, контекст `dev` и namespace `highload-applications`. Локальный service-account key читается из `~/key.json`, не копируется в Git и не выводится. Deployment закрепляется по опубликованному digest из build metadata; tag обозначает время сборки. Проверки: pull, rollout, smoke, полный persistence, расширение 2→3 shard и повторный smoke. Применение в dev разрешено; принятие Kubernetes преподавателем учитывается отдельно.
## Упрощение стенда
L2-REQ-12: единственный источник Kubernetes-ресурсов — Helm chart. Values задают образ, ресурсы и 2–3 шарда; одна лабораторная размещается в одном namespace. Повторный upgrade сохраняет PVC, секреты и данные. Изменение кольца требует остановки API и истечения lease. Python остаётся только в публичных проверках задания; собственная обвязка заменяется стандартными Helm/Docker/kubectl, shell, SQL и awk. REPORT содержит однозначные команды запуска, фактические проверки и ограничения. Приёмка: helm lint/template, adoption текущего стенда без замены PVC, повторный upgrade, smoke/persistence, проверка новых команд покрытия и SQL-эксперимента.
## Перенос в Gitea
L2-REQ-13: решение размещается в репозитории `ssh://git@gitea.privcloud.tech:2222/vlad_marlo/mtusi2026lab2.git`. Имя Go-модуля и внутренние imports соответствуют новому хосту. Задание, contracts и публичные tests нового репозитория сохраняются. Секреты, runtime-данные и история исходного `.git` не переносятся. Проверки: сборка, unit/race, vet, chart lint и неизменность публичных материалов. Измерения от 2026-10-07 остаются историческими и не подменяют проверки переноса.
## Классификация отказов зависимостей
Уточнение L2-REQ-04: потеря соединения, timeout и недоступность PostgreSQL возвращают HTTP 503 / `unavailable`, включая проверку действительной сессии. Ошибки SQL/неизвестные ошибки сохраняют безопасный 500. Воспроизводимый `make test-faults` создаёт изолированные Docker-зависимости, останавливает PostgreSQL и Valkey по очереди, проверяет историю с прежним токеном, отсутствие анонимного доступа, readiness/liveness и восстановление. Пользовательский кластер и данные не затрагиваются.
Уточнение L2-REQ-11 от 2026-10-16: основной registry — `asisti.registry.twcstorage.ru`, локальный токен — `~/.secrets/twc-registry-token`. Helm использует `registry-pull` и опубликованный digest исправления 87e1e5d. Переустановка lab2 в dev сохраняет существующие PVC и Secret БД; соседние releases не изменяются.