17 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).
Правила работы с репозиторием
- Поздние исправления ЛР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, фиксированный порог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/).