Files
mtusi2026lab2/AGENTS.md
T

17 KiB
Raw Blame History

Что это за репозиторий

Skeleton лабораторной 4 курса «Мессенджер под нагрузкой» (МТУСИ, 7 независимых лаб) и решение в ветке solution/bpi2303-kostylev. Skeleton даёт задание (README.md), нормативный контракт (contracts/) и публичные black-box проверки (tests/). Реализация API, Dockerfile, compose-стенд, конфигурация балансировщика и S3, миграции, хуки отказов и собственные тесты — студенческие; решение лабы 4 построено переносом решения лабы 3.

Лаба 4: вложения-изображения в сообщениях. Метаданные вложений живут в PostgreSQL, байты — в приватном bucket S3-совместимого хранилища RustFS внутри стенда, а не в БД и не на диске реплики. POST /api/v1/chats/{chat_id}/attachments принимает сырые байты одного PNG/JPEG (≤10 MiB, ≤40 млн пикселей, тип по содержимому) и отвечает 201 ready только после записи объекта и фиксации метаданных; скачивание идёт только через API участникам чата. Сообщение несёт attachment_ids. Остаётся всё из лабы 3: HAProxy перед ≥2 репликами, X-Instance-Id, обязательный Idempotency-Key, хуки остановки реплики и рестарта стенда.

Команды

make check                      # offline: структура skeleton, JSON, локальные $ref, синтаксис Python, версия 1.4.0
make validate                   # полная валидация OpenAPI 3.1: openapi-spec-validator из .venv (make install); PYTHON= — свой интерпретатор
make install                    # uv sync --group dev
make lint                       # ruff check + ruff format --check + ty check; обязательно перед commit
make student-test               # собственные тесты (поднимают одноразовые PostgreSQL, Valkey и RustFS в Docker)
make student-test PYTEST_ARGS='-v -k drain'   # выборка тестов с именами

make secrets                    # локальные secrets/* (включая root и API-ключи S3) и .env из .env.example
make up                         # docker compose up -d --build --wait: postgres, valkey, s3 → migrate, s3-init → api ×2 → lb; затем ждёт все реплики UP в LB
make test                       # публичный smoke через LB (BASE_URL по умолчанию — docker compose port lb 8080, без стенда http://localhost:8080)
make test-persistence ACTION_SCRIPT=scripts/restart.sh   # рестарт lb, api, postgres, valkey, s3 с сохранением volumes
make test-failover ACTION_SCRIPT=scripts/stop-one.sh     # остановка реплики TARGET_INSTANCE_ID под запросами
make test-faults                # тесты стенда через LB (make faults-evidence → evidence/faults.txt)
make restore                    # вернуть остановленные реплики и дождаться их в ротации LB
make limits                     # лимиты, порты, секреты, volumes и сети всех сервисов против политики → evidence/limits.txt
make lb-check                   # один токен на обеих репликах и 20 гонок одного Idempotency-Key через LB
make retry-check                # потерянный ответ (запись ждёт блокировку чата) на живой и на убитой реплике, повтор тем же ключом
make scenario SCENARIO=failover-upload   # upload → стоп обслужившей реплики → download через другую, SHA-256
make scenario SCENARIO=s3-outage         # S3 остановлен: upload/download 503, тексты работают
make s3-check                   # приватный bucket вне API, ограниченные ключи API и сверки, консоль, повторный bootstrap
make upload-faults              # «4»: негативный suite через LB, компенсация, уборка после grace, обрыв и зависание тела
make upload-memory ARGS='--out evidence/upload-memory/run1'   # «4»: пик памяти реплик и LB при 10/20/40 загрузках 1 и 10 MiB
make load-evidence              # tests/load.py ×3 клиентом-контейнером в сети edge → evidence/load.txt, evidence/load/
make overload-leftovers         # после upload-memory: намерения от 503, сверка и уборка после grace → evidence/overload-leftovers.txt
make clean-clone-evidence       # блок «Запуск из чистого clone» REPORT.md в свежем клоне рядом → evidence/clean-clone.txt
make reconcile ARGS="--apply"   # трек 2: сверка PostgreSQL ↔ S3 (без ARGS — dry-run), one-off сервис reconciler
make reconcile-demo             # трек 2: внедрение ошибок, dry-run/apply/повтор, безопасность, нагрузка → evidence/reconcile/
make reconcile-cost             # трек 2: стоимость обхода 1k/10k/30k/100k × 3 (чистый стенд) → evidence/reconcile/cost/
make down                       # остановка без удаления данных (с профилями bench, tools, reconcile); 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 — единственный источник номера лабы (4). От него зависят scripts/check_contract.py (info.version == 1.4.0, путь /api/v1/attachments/{attachment_id}, X-Instance-Id во всех ответах) и tests/client.py (ветки LAB>=4: upload tests/fixtures/sample.png, сообщение с attachment_ids, скачивание вторым участником, 404 постороннему).
  • tests/client.py шлёт Accept: application/json на каждый запрос, включая скачивание картинки, и считает любой 30x ошибкой: content negotiation и redirect на S3 не делаются.
  • tests/resilience.py: перед хуком загружается sample.png; после persistence метаданные и /content запрашиваются один раз без повторов с таймаутом 2 с, поэтому хук рестарта ждёт здоровья S3. В failover TARGET_INSTANCE_ID — реплика, обслужившая первое сообщение, а не upload; остановку реплики, принявшей upload, доказывает scripts/lab4_scenarios.py failover-upload.
  • contracts/infrastructure.json — роли api (≥2, без локального состояния), postgres (метаданные, persistent volume), load_balancer, s3 (приватный bucket, persistent volume), опциональный redis_or_valkey. compose.example.yaml — только worksheet ролей.

Ключевые правила контракта (lab4)

  • Upload: POST /api/v1/chats/{chat_id}/attachments?filename=…, тело — сырые байты (не multipart), Content-Type: image/png|image/jpeg. Сначала 401, затем объявленный Content-Length (413). Дедлайн запроса продлевается переданными байтами тела по MIN_TRANSFER_RATE_BYTES (128 KiB/s): медленный, но идущий upload и скачивание не обрываются. >10485760 байт или >40 000 000 пикселей — 413; тип по содержимому не совпал, битый файл, иной Content-Type — 415; filename пустой, пробельный, длиннее 255 code points или с /, \, NUL, управляющими символами — 400. Object key назначает сервер. 201 Attachment (status=ready, variants=[], error_code=null, lowercase sha256, size_bytes оригинала) — только после записи в S3 и COMMIT метаданных. Кода 409 у upload нет.
  • GET /api/v1/attachments/{id} и /content?variant=original — только участникам чата вложения, посторонний и неизвестный id — 404. Скачивание отдаёт исходные байты с истинным Content-Type, без redirect, с X-Request-Id и X-Instance-Id.
  • Message.attachment_ids обязателен в каждом ответе ([] у текстовых, в том числе в replay и истории). CreateMessage.attachment_ids — 0–10 уникальных UUID (иначе 400), только вложения этого чата (иначе 404); text="" допустим только с вложением. Отсутствующий attachment_ids и [] — одно тело для Idempotency-Key.
  • Сохраняются правила lab3 (X-Instance-Id, Idempotency-Key, LB не повторяет POST /users, /chats, upload), lab2 (Basic только на входе, Bearer дальше, WWW-Authenticate по пути, logout 204, TTL) и lab1 (формат ошибки, посторонний → 404, keyset (created_at, id), время RFC 3339 с Z).

Правила работы с репозиторием

  • Поздние исправления ЛР3 перенесены из immutable snapshot ba78cf6da439a4ec60fd59389583b38285b0b2b1; диапазон от f591fa64e525679a31c9db7f942d36c789e1a12f и применимость evidence описаны в evidence/forward-port.md.
  • Только свой Compose project mtusi2026lab4 либо hlpipe-lab4-* под разрешённым working_dir; HTTP 18084, остальные host-порты 24000–24999. NO_PROXY и no_proxy: localhost,127.0.0.1,::1. Чужие контейнеры не останавливать, WIP и volumes сохранять. Совместный Docker допустим; эксклюзивность только в финальном release.
  • Runner управляет этапами и агентами: реализация 3→4→5 и evidence → review/fix при major → report → нагрузка/публикация. Самостоятельных агентов, push и Telegram нет; runner/state не менять. Публикация только в разрешённой фазе в private MTUCI-Labs.
  • Исправлять критичное: major — доказанная угроза безопасности, данным, доступности или неработающий обязательный сценарий. Прочие minor остаются в findings и ограничениях REPORT и не блокируют этап. Пригодные измерения сохраняются; повторяется только затронутая или признанная непригодной серия с указанной причиной и фоном нагрузки.
  • Не менять и не ослаблять contracts/, tests/, README.md, COURSE.md, рубрику. Расхождение оформляется вопросом преподавателю.
  • Код — src/messenger/, миграции — alembic/versions/NNNN_*.py, конфигурация LB, нагрузки и S3 — infra/, хуки и обвязка стенда — scripts/, собственные тесты — student-tests/, обезличенные доказательства — evidence/.
  • PostgreSQL — SQLAlchemy 2 async с asyncpg как драйвером; ORM-модели внутри зон, Alembic принимает legacy-схему только после сверки журнала и каталога.
  • Без комментариев в коде; отступы — пробелы ([tool.ruff.format]); Python 3.14 без from __future__ import annotations и TYPE_CHECKING.
  • Порты реплик API и S3 наружу не публикуются: только LB. Нет container_name, hostname и общего INSTANCE_ID у сервиса api. Root-ключи S3 есть только у s3, s3-init и s3-cli; API получает отдельный ключ только на объекты bucket (Get/Put/DeleteObject), сверка — свой ключ (ListBucket, Get/DeleteObject). s3-init и s3-cli работают от uid 65534, migrate и reconciler — с init: true.
  • REPORT.md: команды из чистого clone, архитектура, таблица «критерий → команда → наблюдение → файл», таблица отказов. PASS без команды не доказательство; для отказов — какой контейнер реально остановлен (docker ps -a).
  • Ветка solution/bpi2303-kostylev, коммиты на английском, перед каждым — make lint. Никогда не коммитить .env, secrets/, токены, ключи S3, volumes, дампы.

Уровни оценки

Решение заявлено на «5» с треком 2 «Согласованность двух хранилищ (reconciler)»; таблица доказательств — в REPORT.md, индекс файлов с командой и коммитом каждого — evidence/README.md. Доказательства снимаются на стенде из чистого состояния (make reset-data, make up); при изменении кода приложения или стенда их нужно снять заново.

  • 3 — RustFS и приватный bucket в общем стенде, метаданные в PostgreSQL; upload 201 ready после записи и COMMIT, побайтное скачивание вторым участником, 404 постороннему, 403 анонимному GET в S3; лимиты 10 MiB / 40 MP, тип по содержимому, опасные filename; upload → стоп обслужившей реплики → download через другую; restart с volumes; недоступный S3 → 503 при работающих текстах; минимум lab3 сохранён.
  • 4 — негативные тесты файлов без 500; компенсация сбоя между S3 и БД под блокировкой строки и фоновая уборка намерений pending старше UPLOAD_GRACE_SECONDS (SKIP LOCKED, объект раньше строки); слоты загрузки на воркер, ограниченные буферы сокетов LB и API, фиксированный порог mmap glibc и замер ≥10 одновременных загрузок; идемпотентный bootstrap, ограниченные ключи API, закрытая консоль, проверка приватности вне API.
  • 5 — трек 2: one-off reconciler (python -m messenger.attachments.entrypoints.reconcile, по умолчанию --dry-run) сливает отсортированный листинг bucket и keyset-страницы attachments по object_key (O(N) по времени, O(страница) по памяти); объект без строки старше grace + skew удаляется после повторной проверки строки, готовые строки без объекта или с другими байтами уходят в карантин (миграция 0004, /content → 404) и не удаляются, pending старше grace удаляется (объект, затем строка), карантин снимается только после совпавшего SHA-256 объекта (и без --deep); удаление намерения — audit.attachment_discarded reason=reconcile; SQL-страниц ⌈N/страница⌉; один проход за раз (pg_try_advisory_lock); повторный --apply — 0 действий; стоимость обхода 1k/10k/30k/100k объектов с закреплёнными CPU и отбраковкой прогонов с чужой нагрузкой (evidence/reconcile/).