Files
mtusi2026lab5/openspec/config.yaml
T

181 lines
27 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: |
# Лабораторная 5 «Очереди и асинхронная обработка изображений» — контекст проекта
## Что это
Skeleton лабораторной 5 курса «Мессенджер под нагрузкой» (МТУСИ, 7 независимых лаб) и решение
в ветке `solution/bpi2303-kostylev`, построенное переносом решения лабы 4. Skeleton содержит
задание (`README.md`), нормативный контракт (`contracts/`, версия 1.5.0, `jobs.schema.json`,
`attachment-states.md`) и публичные black-box проверки (`tests/`). Целевая оценка — «5»: весь
уровень 4 плюс трек 2 «Доказанная идемпотентность pipeline».
## Границы (менять нельзя)
In scope лабы 5: асинхронная обработка вложений. Upload проверяется как в лабе 4, оригинал
кладётся в устойчивый staging (приватный префикс S3), вложение `queued`, задание и намерение
публикации фиксируются одной транзакцией PostgreSQL (transactional outbox), ответ — `202` со
снимком `queued`. Relay публикует outbox в брокер с publisher confirm; отдельный worker
потребляет очередь at-least-once, захватывает задание арендой, публикует оригинал в конечный
префикс, строит thumbnail (уровень «3»), crop и optimized WebP (уровень «4») и подтверждает
сообщение только после `COMMIT` результата. Состояния `queued/processing/ready/failed`,
ограниченный retry и финальный `error_code`, идемпотентный эффект по ключу
`(attachment_id, pipeline_version, variant)`, `409` на `/content` до `ready`, `409` на
прикрепление `failed`. Уровень «4» — лимиты worker по времени и памяти, crash-точки окон
отказа, backoff с jitter и классификация ошибок, DLQ и явный replay, lease и fencing,
очистка staging. Трек 2 — versioned pipeline (`pipeline_version` 1 и 2), монотонная
публикация и автоматический fault-injection с проверкой инвариантов. Весь обязательный
минимум lab1–lab4 (PostgreSQL, Basic → Bearer, Argon2id, TTL и отзыв сессий,
keyset-пагинация, HAProxy и ≥2 реплики, `X-Instance-Id`, общий `Idempotency-Key`, RustFS с
приватным bucket, лимиты upload, хуки отказов) сохраняется с объявленным переходом
upload `201 ready` → `202 queued`.
Out of scope (не проектировать, не закладывать «на будущее»): OTel, Prometheus-метрики
приложения и Grafana (лаба 6); TLS, mTLS, OpenBao (лаба 7); трек 1 «Очередь под
перегрузкой» с admission control и матрицей concurrency/prefetch (не выбран); presigned
upload/download; HA брокера (кластер RabbitMQ), HA PostgreSQL, Docker Swarm и несколько
узлов; exactly-once доставка; HTTP-эндпоинты оператора (replay — только CLI); удаление
вложений и сообщений, Web UI, WebSocket, Kubernetes.
## Стек
Python 3.14 (аннотации вычисляются лениво по PEP 649, `TYPE_CHECKING` и
`from __future__ import annotations` не используются), FastAPI, gunicorn с несколькими
`UvicornWorker` (пакет `uvicorn-worker`), dishka (DI, интеграции FastAPI и FastStream),
pydantic v2 + pydantic-settings, structlog, SQLAlchemy 2 async (драйвер asyncpg), Alembic,
redis-py (`redis.asyncio`) для Valkey, argon2-cffi, aiobotocore (S3 path-style, SigV4,
таймауты, checksum `when_required`), Pillow (проверка в API, варианты в worker), FastStream
0.7 с `faststream[rabbit]` поверх aio-pika (consumer worker с `AckPolicy.MANUAL` и prefetch,
publisher relay с confirm и `mandatory`), 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), `api` (один compose-service с `deploy.replicas`, без
`container_name` и портов, `X-Instance-Id` = hostname, non-root, read-only, лимиты), одноразовый
`migrate`, `postgres` (17.x-alpine по digest, volume), `valkey` (8.x-alpine по digest, AOF),
`s3` (RustFS 1.0.4 по digest, volume, консоль выключена), одноразовый `s3-init` (bucket,
политики и пользователи API и worker), `broker` (RabbitMQ 4.1.8 management-alpine по digest,
фиксированный `hostname`, volume, топология и пользователи из definitions, UI только на
127.0.0.1), `relay` и `worker` (образ приложения, свои entrypoint, heartbeat-healthcheck,
`init: true`, лимиты). Сети `edge` и `backend` (internal). Секреты — compose secrets из
gitignored `secrets/`, приложение читает их через `*_FILE`; у API нет секрета брокера, у
worker — свой S3-ключ и свой пользователь брокера только на чтение очереди.
## Архитектура
Монолит с тремя доменными зонами по книге Персиваля и Грегори
(`openspec/notes/architecture-patterns-python.md`), развёрнутый как N реплик API и отдельные
процессы relay и worker из того же образа:
main.py сборка HTTP-приложения: собирает вклады зон, связывает зоны портами
relay.py сборка процесса relay: outbox → брокер, возврат просроченных аренд
worker.py сборка процесса worker: FastStream-подписчик очереди заданий
alembic/ одноразовые миграции под advisory lock с проверкой legacy-схемы
identity/ пользователи, пароли и сессии
messaging/ чаты, история и идемпотентная отправка, ссылки сообщения на вложения
attachments/ вложения: приём и staging, задания и outbox, обработка и варианты,
порты объектного хранилища, брокера и рендера с адаптерами S3, FastStream
и Pillow, свой HTTP-слой и точки входа relay и worker
shared/ только платформа: часы, id, журнал, пул PostgreSQL, UoW-база, конвейер, health,
ошибки, настройки, идентификатор реплики
Стрелки указывают внутрь: `domain/` не импортирует инфраструктуру, `application/` зависит только
от портов, адаптеры подключаются в `ioc.py` зоны. Ядро `shared/` не импортирует ни веб-фреймворк,
ни FastStream. Зоны не импортируют друг друга; общая точка — схема БД: внешние ключи между
таблицами зон допустимы как ограничение целостности, но SQL одной зоны не читает таблицы другой.
Вопрос одной зоны к другой (членство в чате, состояние вложения при отправке сообщения) — порт
зоны-потребителя, адаптер которого собирает `main.py`. PostgreSQL — источник истины для всего,
включая состояние вложений и заданий; S3 — только для байтов; брокер — транспорт и будильник,
потеря сообщения восстанавливается из PostgreSQL; Valkey — кэш сессий.
## Источники норм
- `contracts/README.md` — нормативная семантика API, включая «Вложения (с lab4)» и
«Фоновая обработка (с lab5)».
- `contracts/openapi.json` — OpenAPI 3.1.0, обязательный минимум.
- `contracts/jobs.schema.json`, `contracts/attachment-states.md` — сообщение брокера, машина
состояний и окна отказа.
- `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; не тащи в лабу 5 возможности лаб 6–7 и трека 1."
- "Связывай изменение с конкретным пунктом рубрики `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`."
- "Сценарии обязаны покрывать негативные пути и окна отказа: повторная доставка той же job (тот же `job_id`) до и после `ready`, worker остановлен, рестарт API и брокера с volume, недоступный S3 во время обработки, постоянная ошибка изображения, исчерпание `JOB_MAX_ATTEMPTS`, `/content` для `queued`, `processing` и `failed` (`409`), неизвестный `variant` (`400`), отсутствующий вариант `ready` (`404`), прикрепление `failed` к сообщению (`409`), сообщение брокера не по `jobs.schema.json`, а также прежние: файл ровно 10485760 и 10485761 байт, больше 40 млн пикселей, битый PNG/JPEG, подмена MIME, опасный `filename`, чужое и неизвестное вложение, посторонний на метаданных и скачивании, остановленная реплика, отсутствующий и неверный `Idempotency-Key`, чужой чат (404, не 403), истёкший токен."
- "Для инфраструктурных требований фиксируй наблюдаемое: какие порты опубликованы, где лежат байты (bucket, volume), какие очереди и с какими свойствами видит `rabbitmqctl list_queues`, что лежит в очереди при остановленном worker, какие реплики видны по `X-Instance-Id`, что показывает `docker ps -a`."
- "Не вводи в контракт поля и коды, которых нет в `contracts/openapi.json`."
design:
- "Создавай, если изменение затрагивает границы доменных зон, слои, агрегаты, конкурентность, идемпотентность, согласованность двух хранилищ, балансировку, поведение при сигналах или конфигурацию контейнера."
- "Для каждого введённого паттерна отвечай по формуле книги: что за это получаем и чего это стоит."
- "Явно называй порт, его адаптеры и точку сборки; проверяй правило зависимостей: домен не импортирует инфраструктуру."
- "Указывай, к какой доменной зоне относится изменение; если оно задевает несколько — объясняй, каким портом, событием или внешним ключом они связаны."
- "Всё, что кладётся в `shared/`, обосновывай отдельно: туда попадает только платформа и механизм связи, но не доменные понятия."
- "Ошибки, события и команды принадлежат зоне; в `shared/` живут лишь их базовые типы, без кодов контракта."
- "Для пары PostgreSQL + S3 фиксируй источник истины каждого факта, порядок записи (intent → PUT → COMMIT), что остаётся после сбоя на каждом шаге и кто это убирает; `201` — только после обеих записей."
- "Для пары PostgreSQL + брокер фиксируй транзакционные границы (вложение, задание и outbox — одна транзакция), каждое окно отказа из `attachment-states.md`, что после него лежит в PostgreSQL, S3 и очереди и кто восстанавливает работу; отличай publisher confirm от consumer ack и объясняй, почему это at-least-once, а не exactly-once."
- "Для обработки задания фиксируй ключ эффекта, условие захвата и аренды, условие фиксации результата (fencing), что делает повторная доставка на каждом шаге и почему она не создаёт второго набора вариантов и не откатывает `ready`."
- "Для обработки файлов фиксируй, где и в каком порядке применяются лимиты (заголовок, поток, заголовок изображения, декодирование), сколько памяти занимает одна загрузка и сколько их идёт одновременно."
- "Для балансировщика и S3-клиента фиксируй цепочку таймаутов клиент > LB > приложение > БД/S3 и политику повторов: какие запросы можно повторить и почему."
- "Секреты, токены, ключи S3 и реальные данные в артефакт не попадают — только плейсхолдеры и имена переменных окружения."
- "Отмечай, что требуется от контейнера: пользователь, закрепление версий, healthcheck, обработка SIGTERM, лимиты, опубликованные порты, переменные окружения."
- "Для каждого хранилища называй источник истины, границы транзакций, поведение при недоступности (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`, `relay.py` и `worker.py`."
- "Зоны не импортируют модули друг друга, кроме объявления события, — это проверяется тестом; в БД связь зон — только внешний ключ, SQL зоны читает лишь свои таблицы."
- "Пиши под Python 3.14 с ленивыми аннотациями: без `TYPE_CHECKING` и без `from __future__ import annotations`."
- "Логирование — только через порт `Logger`; второй логгер в приложении не заводится. Object key, ключи S3 и содержимое файлов в журнал не пишутся."
- "Код приложения — в `src/`, конфигурация LB, нагрузки и S3 — в `infra/`, собственные тесты — в `student-tests/`, обезличенные доказательства — в `evidence/`."
- "Перед коммитом прогоняй `make lint`, `make student-test` и `make check`."
- "SQL через SQLAlchemy ORM/Core с параметрами; миграции Alembic; значения запроса не склеиваются в SQL."
- "Тело загрузки читается потоком со счётчиком до лимита; изображение не декодируется целиком до проверки размера по заголовку; тяжёлая проверка идёт в потоке под ограничением параллелизма."
- "API не обрабатывает изображения синхронно и не подключается к брокеру: задание уходит только через outbox; `202` возвращает снимок записанного объекта."
- "Worker и relay не объявляют очереди и exchange: топология и права — в `infra/rabbitmq/`; `ack` — строго после `COMMIT`, сообщение брокера — ровно поля `jobs.schema.json`."
- "FastStream и aio-pika живут только в `entrypoints/` и `infrastructure/` зоны вложений и в сборке процесса; `shared/` их не импортирует."
- "Реплика не хранит в памяти процесса и на своём диске ничего, от чего зависит корректность ответа другой реплики: сессии, ключи идемпотентности, курсоры и файлы — через общее хранилище или общий секрет."
- "Ошибка зависимости (PostgreSQL, Valkey, S3, брокер) превращается в `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 validate`, `make lint`, `make student-test`, `make test`, `make test-persistence ACTION_SCRIPT=scripts/restart.sh`, `make test-failover ACTION_SCRIPT=scripts/stop-one.sh` и сценарии отказов уровня (`make level3`, `make level4`, `make track2`) против стенда проходят."
- "Сохранившиеся дальше требования должны попасть в `openspec/specs/`, иначе исчезнут вместе с архивом."
- "Зафиксируй, что именно демонстрируется в сценарии защиты и какие измерения приложены к треку «5»."