Files
mtusi2026lab5/AGENTS.md
T
ArtyomandClaude Opus 5.5 1210dd899c Carry over the agent context and openspec history from lab 4
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>
2026-10-29 00:32:37 +03:00

62 lines
12 KiB
Markdown
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.
## Что это за репозиторий
Skeleton лабораторной 5 курса «Мессенджер под нагрузкой» (МТУСИ, 7 независимых лаб) и решение в ветке `solution/bpi2303-kostylev`. Skeleton даёт задание (`README.md`), нормативный контракт (`contracts/`) и публичные black-box проверки (`tests/`). Реализация API, worker, relay, Dockerfile, compose-стенд, конфигурация балансировщика, S3 и брокера, миграции, хуки отказов и собственные тесты — студенческие; решение лабы 5 построено переносом решения лабы 4.
Лаба 5: приём вложения отделён от тяжёлой обработки. `POST /api/v1/chats/{chat_id}/attachments` проверяет файл как в лабе 4, кладёт оригинал в приватный префикс `staging/` bucket **RustFS** и одной транзакцией PostgreSQL фиксирует вложение `queued`, задание (`jobs`) и строку **transactional outbox**; только после этого отвечает `202` со снимком `queued`. Отдельный сервис `relay` публикует outbox в **RabbitMQ 4.1** (quorum queue, DLX, publisher confirms, `mandatory`, persistent), отдельный сервис `worker` (тот же образ, свой entrypoint) потребляет очередь через **FastStream** поверх aio-pika с ручным `ack` строго после `COMMIT` результата, захватывает задание арендой (`lease_token`), публикует оригинал в `originals/` и строит варианты Pillow. Источник истины состояний — PostgreSQL, брокер — транспорт и будильник. Остаётся всё из лаб 1–4: HAProxy перед ≥2 репликами, `X-Instance-Id`, `Idempotency-Key`, Basic → Bearer, хуки остановки реплики и рестарта стенда.
## Команды
```sh
make check # offline: структура skeleton, JSON, локальные $ref, синтаксис Python, версия 1.5.0
make validate PYTHON=.venv/bin/python # полная валидация OpenAPI 3.1 и jobs.schema.json (venv с requirements-dev.txt)
make install # uv sync --group dev
make lint # ruff check + ruff format --check + ty check; обязательно перед commit
make student-test # собственные тесты (одноразовые PostgreSQL, Valkey, RustFS и RabbitMQ в Docker)
make secrets # локальные secrets/* (PostgreSQL, Valkey, S3 root/API/worker, RabbitMQ) и .env
make up # docker compose up -d --build --wait: хранилища и broker → migrate, s3-init → api ×2, relay, worker → lb
make test # публичный smoke через LB (BASE_URL, по умолчанию http://localhost:8080)
make test-persistence ACTION_SCRIPT=scripts/restart.sh # рестарт lb, api, relay, worker и postgres, valkey, s3, broker с volumes
make test-failover ACTION_SCRIPT=scripts/stop-one.sh # остановка реплики TARGET_INSTANCE_ID под запросами
make restore # вернуть остановленные реплики и дождаться их в ротации LB
make worker-stop / worker-start # демонстрация «worker недоступен»
make queues # очереди брокера: ready, unacked, consumers
make level3 # сценарии уровня «3» suite (scripts/pipeline_suite.py) → evidence/level3.json
make down # остановка без удаления данных; make reset-data — намеренное удаление volumes
```
`tests/*.py` и `scripts/*.py` — только stdlib, синтаксис Python 3.9 (`make check` разбирает их системным `python3`). Проверки сами не поднимают стенд. Хуки `scripts/stop-one.sh` и `scripts/restart.sh` запускаются тестом без shell, поэтому исполняемые и с shebang. Данные не удаляются автоматически: каждый прогон smoke создаёт новых синтетических пользователей и вложения.
## Архитектура skeleton
- `lab.json` — единственный источник номера лабы (5). От него зависят `scripts/check_contract.py` (`info.version == 1.5.0`) и `tests/client.py` (ветки `LAB>=5`: upload отвечает `202 queued`, сообщение с вложением сразу, ожидание `ready` до 60 с от второго участника, ровно один вариант `thumbnail` 256×160 настоящим JPEG).
- `tests/` байт в байт как в лабе 4; поведение переключает только `lab.json`. `tests/resilience.py` после хука рестарта запрашивает метаданные и оригинал один раз с таймаутом 2 с.
- `contracts/jobs.schema.json` — формат сообщения брокера (7 обязательных полей, без bytes, URL, ключей S3 и filename); `contracts/attachment-states.md` — машина состояний и окна отказа.
- `contracts/infrastructure.json` — роли `api`, `postgres`, `load_balancer`, `s3`, `broker` (persistent volume, at-least-once), `worker` (отдельный процесс). `compose.example.yaml` — только worksheet ролей.
## Ключевые правила контракта (lab5)
- Upload: те же лимиты и коды, что в лабе 4 (`413`, `415`, `400`, `404`), но успех — `202 Attachment` со снимком `status=queued`, `variants=[]`, `error_code=null`; снимок берётся из записанного объекта, а не перечитывается после публикации. `202` — только после записи оригинала в `staging/` и `COMMIT` вложения, задания и outbox.
- Состояния: `queued → processing → ready | failed`; `processing → queued` при временной ошибке или истёкшей аренде; `failed → queued` только явным replay. `ready` не откатывается. `ready` выставляется, только когда записаны оригинал и все обещанные уровнем варианты.
- `/content` для `queued`, `processing`, `failed` — `409 conflict` для любого `variant`, включая `original`; неизвестный `variant` — `400`; отсутствующий вариант `ready`-вложения — `404`; посторонний — `404`. Варианты: `thumbnail` JPEG вписан в 256×256 без увеличения, EXIF orientation применяется, alpha на белом, размеры вниз, минимум 1 px.
- Сообщение: вложение `queued`/`processing` прикрепляется (`201`), `failed` — `409`, вложение другого чата или неизвестное — `404`.
- Сообщение брокера — ровно поля `jobs.schema.json`; `job_id` не меняется при redelivery, `attempt` растёт только при управляемом повторе через outbox. Ключ эффекта — `(attachment_id, pipeline_version, variant)`.
- Сохраняются правила lab4 (сырые байты, тип по содержимому, скачивание только через API без redirect), lab3 (`X-Instance-Id`, `Idempotency-Key`, LB не повторяет upload), lab2 (`Basic` только на входе, `Bearer` дальше, `WWW-Authenticate` по пути) и lab1 (формат ошибки, посторонний → `404`, keyset `(created_at, id)`, время RFC 3339 с `Z`).
## Правила работы с репозиторием
- Не менять и не ослаблять `contracts/`, `tests/`, `README.md`, `COURSE.md`, рубрику. Расхождение оформляется вопросом преподавателю.
- Код — `src/messenger/`, миграции — `src/messenger/migrations/NNNN_*.sql`, конфигурация LB, нагрузки, S3 и брокера — `infra/`, хуки и обвязка стенда — `scripts/`, собственные тесты — `student-tests/`, обезличенные доказательства — `evidence/`.
- Без комментариев в коде; отступы — пробелы (`[tool.ruff.format]`); Python 3.14 без `from __future__ import annotations` и `TYPE_CHECKING`.
- Порты реплик API, S3, AMQP наружу не публикуются: только LB и UI брокера на `127.0.0.1`. API к брокеру не подключается. Клиенты брокера не объявляют очереди: топология — в `infra/rabbitmq/definitions.json`, права configure есть только у оператора.
- `REPORT.md`: команды из чистого clone, архитектура, таблица «критерий → команда → наблюдение → файл», таблица отказов. PASS без команды не доказательство; для отказов — какой контейнер реально остановлен (`docker ps -a`).
- Ветка `solution/bpi2303-kostylev`, коммиты на английском, перед каждым — `make lint`. Никогда не коммитить `.env`, `secrets/`, токены, ключи S3, пароли брокера, volumes, дампы.
## Уровни оценки
Решение заявлено на **«5»** с треком 2 «Доказанная идемпотентность pipeline»; таблица доказательств — в `REPORT.md`.
- **3** — `202 queued` после staging и `COMMIT` задания с outbox; отдельные `broker`, `relay`, `worker` в стенде; durable quorum queue, publisher confirm, ручной `ack` после `COMMIT`; состояния `queued/processing/ready/failed`, оригинал в `originals/` и thumbnail; ограниченный retry (`JOB_MAX_ATTEMPTS=5`) и `failed` с `error_code`; повтор job без второго набора вариантов; worker остановлен → upload → сообщение → рестарт API и broker → worker → `ready`; минимум lab4 сохранён.
- **4** — crop и optimized WebP, лимиты worker по байтам, пикселям, времени и памяти, crash между `COMMIT` и publish, backoff с jitter и классификация ошибок, DLQ и replay, crash после записи объекта до `ack`, lease и fencing для зависшего `processing`, prefetch, очистка staging.
- **5** — трек 2: `pipeline_version` 1 и 2, монотонная публикация, автоматический fault-injection (дубль, reorder, crash до и после side effect, устаревшая job) и проверка инвариантов одной командой.