Files
mtusi2026lab4/AGENTS.md
T
ArtyomandClaude Opus 5.5 c8cb263c77 Retake the lab 4 evidence on the final code and finish the report
The level 3 and 4 evidence was taken on 24f9d61 and a774a2f, before the
lab 3 fixes were carried over and before the reconciler. Take all of it
again in one series on 81dd816, whose application and stand code is the
final one: a fresh clone runs the launch block of the report from secrets
to reset-data, then one stand from clean volumes gives the smoke, stack,
limits, lb-check, failover of each replica and of the upload replica,
persistence, S3 outage, S3 privacy, lost-answer retry, upload faults, all
stack checks, storage layout and three runs of the upload memory matrix.

The three memory runs keep the peak with three slots at 297-345 MiB
against 512 MiB at the limit without them, but at 40 uploads of 10 MiB
the wait for a slot nears the 8 s request timeout and one run of three
gave 7 of 80 a 503. Those timeouts left 67 invisible intents; the record
shows the reconciler seeing them as fresh and the sweep removing all of
them after the grace period.

Message write load is taken with tests/load.py from a container on the
edge network: 2 106 RPS, no errors, replicas and PostgreSQL at their CPU
limits. The first try from the macOS host is kept as a discarded attempt,
it ran out of ephemeral ports while the replicas answered every request.

The report gets the defense answers, the load section, the evidence
commits, the upload limit order as the pipeline applies it, medians in
the track 2 cost table and the proposals over the word limit; the evidence
index lists every file with its command and commit.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01V1d3RLHNBBMA6UqBLLJv27
2026-10-30 07:55:34 +03:00

14 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              # «4»: пик памяти реплик и LB при 10/20/40 одновременных загрузках 1 и 10 MiB
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 × 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. >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).

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

  • Не менять и не ослаблять 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 наружу не публикуются: только LB. Нет container_name, hostname и общего INSTANCE_ID у сервиса api. Root-ключи S3 есть только у s3, s3-init и s3-cli; API получает отдельный ключ с политикой на один bucket.
  • 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 удаляется (объект, затем строка), сошедшийся карантин снимается; один проход за раз (pg_try_advisory_lock); повторный --apply — 0 действий; стоимость обхода 1k/10k/30k объектов с закреплёнными CPU и отбраковкой прогонов с чужой нагрузкой (evidence/reconcile/).