Files
mtusi2026lab3/openspec/config.yaml
T
ArtyomandClaude Opus 5.5 e425a9d236 Finalize the lab 3 report against recorded evidence
Rerun the clean clone pass on the final commit in its own compose project:
secrets, config, up with migrations on empty volumes, readiness, smoke,
replica spread and same key races, failover, persistence, repeated
migrations, down keeping volumes and reset-data removing them. Record the
student tests by name and the limits policy on the final code.

Check every figure of the report against evidence files and fix the ones
that drifted: data set sizes, the share of the chat lock statement, the
WAL waits, the aborted series, the disturbed steps, the restart timing
and the image ID of the rolling update. State which commit each evidence
file was taken on, answer the defense questions, index evidence/ and
bring AGENTS.md and the openspec context up to date for lab 3.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01V1d3RLHNBBMA6UqBLLJv27
2026-10-29 03:13:24 +03:00

153 lines
22 KiB
YAML
Raw 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.
schema: spec-driven
context: |
# Лабораторная 3 «Балансировка и отказ API-реплики» — контекст проекта
## Что это
Skeleton лабораторной 3 курса «Мессенджер под нагрузкой» (МТУСИ, 7 независимых лаб) и решение
в ветке `solution/bpi2303-kostylev`, построенное переносом решения лабы 2. Skeleton содержит
задание (`README.md`), нормативный контракт (`contracts/`, версия 1.3.0) и публичные black-box
проверки (`tests/`). Целевая оценка — «5»: весь уровень 4 плюс трек 1 «Цена масштабирования».
## Границы (менять нельзя)
In scope лабы 3: несколько взаимозаменяемых реплик API (≥2) за единственной публичной точкой
входа — балансировщиком с проверкой готовности backend и обновлением адресов через DNS, без
sticky-сессий; `X-Instance-Id` обслужившей реплики в каждом ответе API; обязательный
`Idempotency-Key` в `POST /api/v1/chats/{chat_id}/messages` с общей для всех реплик
идемпотентностью (повтор, конкурентный повтор, смена реплики); миграции однократно, а не гонкой
реплик; graceful shutdown; явные хуки остановки одной реплики и рестарта стенда. Весь
обязательный минимум lab1 и lab2 (PostgreSQL, Basic → Bearer, Argon2id, TTL и отзыв сессий,
keyset-пагинация, переживание рестарта) сохраняется с объявленными переходами.
Out of scope (не проектировать, не закладывать «на будущее»): вложения и S3 (лаба 4); worker,
брокер и обработка изображений (лаба 5); OTel и Grafana (лаба 6); TLS, mTLS, OpenBao и
непрозрачный alias вместо hostname в `X-Instance-Id` (лаба 7); Docker Swarm и несколько узлов;
репликация и HA PostgreSQL, резервирование балансировщика; Web UI, WebSocket, редактирование и
удаление сообщений, изменение состава участников, публичный поиск пользователей, Kubernetes.
## Стек
Python 3.14 (аннотации вычисляются лениво по PEP 649, `TYPE_CHECKING` и
`from __future__ import annotations` не используются), FastAPI, gunicorn с несколькими
`UvicornWorker` (пакет `uvicorn-worker`), dishka (DI), pydantic v2 + pydantic-settings, structlog,
asyncpg (параметризованный SQL без ORM), redis-py (`redis.asyncio`) для Valkey, argon2-cffi,
pytest + pytest-asyncio + httpx. Зависимости — uv и `uv.lock`; ruff и ty обязательны на `src/`,
`student-tests/` и Python-обвязке стенда; `scripts/*.py` держат синтаксис Python 3.9 и stdlib.
Инфраструктура — Docker Compose: `lb` (HAProxy 3.2 LTS по digest, единственные опубликованные
порты — HTTP и статистика на 127.0.0.1, активная проверка `GET /health/ready`, `server-template`
с resolvers Docker DNS, round robin), `api` (один compose-service с `deploy.replicas`, без
`container_name` и опубликованных портов, `X-Instance-Id` = hostname контейнера, non-root,
read-only, лимиты CPU/RAM, `SIGTERM` ≤ `stop_grace_period`), одноразовый `migrate` на образе
приложения под advisory lock, `postgres` (17.x-alpine по digest, volume, `pg_stat_statements`),
`valkey` (8.x-alpine по digest, AOF), `k6` под профилем `bench` для измерений. Сети `edge`
(LB и генератор нагрузки) и `backend` (internal). Секреты — compose secrets из gitignored
`secrets/`, приложение читает их через `*_FILE`.
## Архитектура
Монолит с двумя доменными зонами по книге Персиваля и Грегори
(`openspec/notes/architecture-patterns-python.md`), развёрнутый N одинаковыми репликами:
main.py сборка приложения: собирает вклады зон в один процесс
migrate.py одноразовая точка входа: применяет SQL-миграции под advisory lock
identity/ пользователи, пароли и сессии: ошибки, события, команды, значения, порты,
адаптеры PostgreSQL/Valkey/Argon2 и весь свой HTTP-слой, включая аутентификацию
messaging/ чаты, история и идемпотентная отправка: ошибки, события, команды, агрегат Chat,
курсор, адаптеры PostgreSQL и весь свой HTTP-слой
shared/ только платформа: domain / application / infrastructure (часы, id, журнал,
пул PostgreSQL, UoW-база) и entrypoints/ (конвейер, health, ошибки, настройки,
идентификатор реплики)
Стрелки указывают внутрь: `domain/` не импортирует инфраструктуру, `application/` зависит только
от портов, адаптеры подключаются в `ioc.py` зоны. Ядро `shared/` не импортирует веб-фреймворк.
Зоны не импортируют друг друга; общая точка — схема БД: внешние ключи между таблицами зон
допустимы как ограничение целостности, но SQL одной зоны не читает таблицы другой.
Реплика не держит состояния, от которого зависит корректность: PostgreSQL — источник истины
для всего, включая сессии и ключи идемпотентности; Valkey — только общий кэш сессий.
Отправка сообщения (после трека 1) — одна команда SQL адаптера `PostgresMessageLog` за портом
`MessageLog`: блокировка строки чата, членство, отметка времени, квитанция ключа и сообщение
фиксируются вместе; агрегат `Chat` в записи не участвует, эти правила держат SQL и
интеграционные тесты.
## Источники норм
- `contracts/README.md` — нормативная семантика API, включая «Балансировка и повторная отправка».
- `contracts/openapi.json` — OpenAPI 3.1.0, обязательный минимум.
- `contracts/infrastructure.json`, `infra/README.md` — роли инфраструктуры и что о них отчитать.
- `README.md` — рубрика уровней «3» / «4» / «5».
- `COURSE.md` — карта курса и объявленные переходы API между лабами.
- `openspec/notes/architecture-patterns-python.md` — словарь паттернов и их компромиссов.
При расхождении артефакта с `contracts/` источником считается `contracts/`.
Подгонка контракта или публичных тестов под реализацию решением не является.
rules:
proposal:
- "Пиши на русском; идентификаторы, поля, коды ошибок и имена файлов — в оригинальном виде."
- "Держи в пределах 400 слов: Why / What changes / Impact без воды."
- "Указывай, какой уровень рубрики закрывает изменение: «3», «4» или заявленный трек «5»."
- "Обязательна секция «Non-goals» со ссылкой на Out of scope; не тащи в лабу 3 возможности лаб 4–7."
- "Связывай изменение с конкретным пунктом рубрики `README.md` и строкой таблицы доказательств `REPORT.md`."
- "Если изменение трогает `contracts/`, `tests/`, `README.md` или `COURSE.md` — это запрещено, оформляй как вопрос преподавателю."
specs:
- "Имя capability начинается с префикса лабы, в которой требование введено: `lab<N>-<имя>`, например `lab1-messenger-history`. Номер берётся из `lab.json`."
- "Префикс означает происхождение, а не срок действия: требование с `lab1-` продолжает действовать в лабах 2–7, пока его явно не изменит новая дельта."
- "Требование существующей capability правится дельтой к ней же, под её исходным префиксом; новый префикс заводится только для по-настоящему нового поведения."
- "Дельта-спека описывает только наблюдаемое поведение, не реализацию."
- "Требования о границах доменных зон формулируй как наблюдаемые: через поведение API или через проверяемый граф зависимостей модулей."
- "Формулируй требования как `### Requirement:` плюс `#### Scenario:` в форме WHEN/THEN на русском."
- "Для API-требований фиксируй метод, путь, коды ответов, заголовки и форму тела ошибки."
- "Каждое требование трассируется на пункт `contracts/README.md` или на критерий рубрики `README.md`."
- "Сценарии обязаны покрывать негативные пути: отсутствующий и неверный `Idempotency-Key`, тот же ключ с другим телом, тот же ключ у другого пользователя или в другом чате, повтор после отзыва сессии, конкурентный повтор через разные реплики, остановленная реплика, недоступная зависимость, а также прежние: malformed JSON, лишние поля, чужой чат (404, не 403), cursor от другого чата, limit вне 1–100, истёкший токен."
- "Для инфраструктурных требований фиксируй наблюдаемое: какие порты опубликованы, какие реплики видны по `X-Instance-Id`, за какое время восстанавливается запись, что показывает `docker ps -a`."
- "Не вводи в контракт поля и коды, которых нет в `contracts/openapi.json`."
design:
- "Создавай, если изменение затрагивает границы доменных зон, слои, агрегаты, конкурентность, идемпотентность, балансировку, поведение при сигналах или конфигурацию контейнера."
- "Для каждого введённого паттерна отвечай по формуле книги: что за это получаем и чего это стоит."
- "Явно называй порт, его адаптеры и точку сборки; проверяй правило зависимостей: домен не импортирует инфраструктуру."
- "Указывай, к какой доменной зоне относится изменение; если оно задевает обе — объясняй, каким событием они связаны."
- "Всё, что кладётся в `shared/`, обосновывай отдельно: туда попадает только платформа и механизм связи, но не доменные понятия."
- "Ошибки, события и команды принадлежат зоне; в `shared/` живут лишь их базовые типы, без кодов контракта."
- "Фиксируй границы согласованности и способ защиты состояния от гонок между процессами и репликами; объясняй выбранную семантику времени и сортировки."
- "Для балансировщика фиксируй алгоритм, проверку готовности (период, fall/rise, таймаут), обнаружение адресов, политику повторов (какие запросы LB может повторить и почему) и цепочку таймаутов клиент > LB > приложение > БД."
- "Секреты, токены и реальные данные в артефакт не попадают — только плейсхолдеры и имена переменных окружения."
- "Отмечай, что требуется от контейнера: пользователь, закрепление версий, healthcheck, обработка SIGTERM, лимиты, опубликованные порты, переменные окружения."
- "Для каждого хранилища называй источник истины, границы транзакций, политику expiry и инвалидации, поведение при недоступности (503 или обход кэша) и что переживает рестарт."
- "SQL описывай вместе с индексом, который его обслуживает, и ожидаемым планом; схему, ограничения и индексы фиксируй до запросов; миграции — аддитивные (expand/contract), совместимые с работающей версией."
tasks:
- "Задачи — атомарные шаги не длиннее 2 часов, в порядке исполнения."
- "Группируй по слоям и артефактам: схема и миграции, доменные зоны, приложение, инфраструктура, точка входа, стенд, хуки отказов, тесты, измерения, отчёт."
- "Одна задача не пересекает границу доменной зоны; связь зон (событие или внешний ключ схемы) оформляется отдельной задачей."
- "Первой в цепочке идёт задача уровня «3», задачи уровня «4» и трека «5» — после неё."
- "Каждая группа завершается задачей проверки: какой командой убедиться, что критерий рубрики выполнен."
- "Не создавай задач, меняющих `contracts/`, `tests/`, `README.md`, `COURSE.md` или рубрику."
operations:
apply:
guidance:
- "Соблюдай правило зависимостей: адаптер добавляется за существующим портом, а не импортом инфраструктуры в домен."
- "Новый код кладётся в свою доменную зону вместе со своими ошибками, событиями, командами и HTTP-фасадом."
- "`shared/` пополняется только платформой и механизмом связи; доменное понятие туда не попадает никогда."
- "Коды контракта и HTTP-статусы объявляет зона в своём `entrypoints/errors.py`; платформа только применяет реестр."
- "Роутер, провайдер DI, журнал, отображение ошибок и настройки зоны лежат в её `entrypoints/` и `config.py`."
- "Ядро `shared/` (domain, application, infrastructure) не импортирует веб-фреймворк: транспорт живёт только в `shared/entrypoints/` и в `entrypoints/` зон."
- "Отдельного каталога точек входа на верхнем уровне не заводи: общее кладётся в `shared/`, доменное — в зону, сборка — в `main.py`."
- "Зоны не импортируют модули друг друга, кроме объявления события, — это проверяется тестом; в БД связь зон — только внешний ключ, SQL зоны читает лишь свои таблицы."
- "Пиши под Python 3.14 с ленивыми аннотациями: без `TYPE_CHECKING` и без `from __future__ import annotations`."
- "Логирование — только через порт `Logger`; второй логгер в приложении не заводится, сообщения сервера и библиотек идут через тот же поток."
- "Код приложения — в `src/`, конфигурация LB и нагрузки — в `infra/`, собственные тесты — в `student-tests/`, обезличенные доказательства — в `evidence/`."
- "Перед коммитом прогоняй `make lint`, `make student-test` и `make check`."
- "SQL только параметризованный (`$1`, `$2`); значения из запроса никогда не склеиваются в текст запроса."
- "Реплика не хранит в памяти процесса ничего, от чего зависит корректность ответа другой реплики: сессии, ключи идемпотентности и курсоры проверяются через общее хранилище или общий секрет."
- "Ошибка зависимости (PostgreSQL, Valkey) превращается в `503 unavailable` за ограниченное время; отказ кэша обходится и никогда не превращается в анонимный доступ."
- "Схема меняется только новым файлом миграции; применённую миграцию не редактируют; миграция совместима с работающей предыдущей версией."
- "Публичные `make test`, `make test-persistence ACTION_SCRIPT=scripts/restart.sh` и `make test-failover ACTION_SCRIPT=scripts/stop-one.sh` запускаются против поднятого стенда (`make up`) через LB после готовности всех реплик; после failover реплика возвращается `make restore`."
- "Каждый заявленный критерий рубрики подтверждай командой и наблюдаемым результатом в `REPORT.md`; PASS без команды доказательством не считается."
- "Отмечай выполнение в `tasks.md`; резюме держи кратким."
archive:
guidance:
- "Имя архивной папки начинается с даты архивации в формате `ГГГГ-ММ-ДД`, а не с даты создания change."
- "В `.openspec.yaml` архивной папки проставь `archived: <дата архивации>` и `lab: <номер из lab.json>` — по ним видно, когда и в какой лабе изменение закрыто."
- "Перед архивацией сверься с рубрикой `README.md`: какой уровень закрывает изменение и каким файлом доказательства."
- "Убедись, что `make check`, `make lint`, `make student-test`, `make test`, `make test-persistence ACTION_SCRIPT=scripts/restart.sh` и `make test-failover ACTION_SCRIPT=scripts/stop-one.sh` против стенда проходят."
- "Сохранившиеся дальше требования должны попасть в `openspec/specs/`, иначе исчезнут вместе с архивом."
- "Зафиксируй, что именно демонстрируется в сценарии защиты и какие измерения приложены к треку «5»."