Bring the Claude Code settings, the lint hook, the opsx commands and skills, the architecture notes, the lab 1 to lab 4 specs and the archived lab 1 to lab 4 changes into the lab 5 skeleton, so lab 5 continues the same spec history instead of starting from scratch. The files come from the lab 4 solution commit d2744bc. Rewrite AGENTS.md and the openspec context and rules for lab 5: upload answers 202 queued after the original is in a private staging prefix and the attachment, the job and the outbox row are committed in one transaction, a separate relay publishes the outbox to RabbitMQ with publisher confirms, a separate worker built from the same image consumes the queue through FastStream with a manual ack after the result commit, PostgreSQL stays the source of truth for job states, Out of scope moves to labs 6-7, track 1 and broker HA, and the rules add the failure windows between PostgreSQL and the broker, the effect key and the lease to specs and designs. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
181 lines
27 KiB
YAML
181 lines
27 KiB
YAML
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, asyncpg (параметризованный SQL без ORM),
|
||
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-подписчик очереди заданий
|
||
migrate.py одноразовая точка входа: применяет SQL-миграции под advisory lock
|
||
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 только параметризованный (`$1`, `$2`); значения из запроса никогда не склеиваются в текст запроса."
|
||
- "Тело загрузки читается потоком со счётчиком до лимита; изображение не декодируется целиком до проверки размера по заголовку; тяжёлая проверка идёт в потоке под ограничением параллелизма."
|
||
- "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»."
|