Carry sourcef591fa64e5forward from72a1e57. Preserve lab4 attachment transactions, reconciliation locks, quarantine, and existing schema data through verified legacy adoption. Keep report and evidence work in progress untouched.
16 KiB
Что это за репозиторий
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: uploadtests/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. ВfailoverTARGET_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, lowercasesha256,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по пути, logout204, TTL) и lab1 (формат ошибки, посторонний →404, keyset(created_at, id), время RFC 3339 сZ).
Правила работы с репозиторием
- Не менять и не ослаблять
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, фиксированный порогmmapglibc и замер ≥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/).