Files
mtusi2026lab4/REPORT.md
T
Mikhail Verkovykh 728e53cc55 Реализовать lab4 на оценку 4: SeaweedFS, вложения и согласованность БД/S3.
Перенесён стенд lab3 (API, Redis-сессии, идемпотентность, HAProxy, реплики API). Добавлены приватный bucket SeaweedFS с отдельным ключом API, загрузка PNG/JPEG с лимитами и полной проверкой, компенсация и reconciler, плавная остановка API, тесты и evidence.
2026-11-06 19:48:37 +03:00

49 KiB
Raw Blame History

Отчёт — лабораторная 4

  • Автор, группа: Болотов Илья, БВТ2303
  • Целевая оценка; выбранный трек 5, если нужен: 4 (трек 5 не выбран)
  • Ветка: solution/bvt2303-bolotov
  • Использованные источники, библиотеки и помощь ИИ:
    • FastAPI, Uvicorn, psycopg3 (+pool), redis-py, argon2-cffi, boto3 1.35.99, HAProxy 2.9, SeaweedFS 3.97, libjpeg-turbo 2.1.5 (djpeg);
    • спецификации PNG (W3C PNG 2nd ed.) и JPEG (ITU T.81), документация AWS S3 и SeaweedFS;
    • материалы курса: README, contracts, tests;
    • перенос lab3, реализация и эксперименты выполнены с помощью ИИ-ассистента (Cursor). Все числа ниже взяты из файлов evidence/.

Запуск из чистого clone

Prerequisites:

  • Docker Engine + Compose v2 (проверено: Docker 29.9.2, Compose v5.6.1, Docker Desktop/WSL2);
  • Python 3.9+ на хосте для скрипта секретов и тестов (stdlib). На Windows задайте PYTHONUTF8=1.
cp .env.example .env                       # Windows: copy .env.example .env
python scripts/init_secrets.py             # создаёт ./secrets/* (идемпотентно, печатает только имена файлов)
docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build --scale api=2
# то же одной командой: scripts\up.cmd (Windows) или ./scripts/up.sh (Unix)

Порядок старта задан в compose:

  1. postgres и s3 становятся healthy.
  2. One-shot migrate применяет migrations/*.sql, s3-init идемпотентно создаёт приватный bucket. Оба должны завершиться с кодом 0.
  3. Стартуют api ×2, затем lb.

Готовность: GET http://127.0.0.1:8080/health/ready → 200. На Windows используйте 127.0.0.1, а не localhost: иначе каждое соединение сначала ≈2 с ждёт IPv6 ::1, на котором порт не опубликован.

Проверки (PowerShell; в Unix те же команды с export):

$env:PYTHONUTF8=1
python scripts/check_contract.py                       # make check
.venv\Scripts\python.exe scripts/validate_openapi.py   # make validate (venv с requirements-dev.txt)
python tests/smoke.py --base-url http://127.0.0.1:8080 # make test
python tests/resilience.py --mode persistence --action-script scripts/restart.cmd  --base-url http://127.0.0.1:8080
python tests/resilience.py --mode failover    --action-script scripts/stop-one.cmd --base-url http://127.0.0.1:8080
docker compose --env-file .env up -d --scale api=2     # вернуть остановленную реплику
python scripts/seq_failover_evidence.py                # поочерёдный отказ каждой реплики (lab3)
python scripts/rolling_load_evidence.py                # rolling update под нагрузкой (lab3)
python scripts/lb_interleave_evidence.py               # распределение длинных загрузок по репликам (leastconn)
scripts\rolling-update.cmd                             # rolling update без нагрузки
$env:RUN_DOCKER_TESTS=1; $env:RUN_DEPS_TEST=1; python student-tests/run_all.py
docker compose --env-file .env exec -T api python -m messenger.selfcheck s3
docker compose --env-file .env exec -T api python -m messenger.selfcheck consistency
docker compose --env-file .env exec -T api python -m messenger.reconcile --dry-run --check-missing

На Unix используйте scripts/restart.sh, scripts/stop-one.sh и scripts/rolling-update.sh. Если файлы получены без executable bit, выполните chmod +x scripts/*.sh.

  • Остановка без потери данных: docker compose --env-file .env down.
  • Намеренное удаление учебных данных (PostgreSQL, Redis, S3): docker compose --env-file .env down -v.

Архитектура и решения

Клиент → HAProxy lb (127.0.0.1:8080, единственная публикация)
          ├─ messenger_api          (check /health/ready)  → API × N
          └─ messenger_api_degraded (check /health/live)   → те же API, если не готова ни одна
API → PostgreSQL  users/chats/messages/idempotency + attachments, upload_intents  (сеть labnet)
    → Redis       сессии (AOF)                                                     (сеть labnet)
    → s3:9000     s3-gw (HAProxy TCP) → SeaweedFS S3 127.0.0.1:8333               (сеть storage, internal)
One-shot: migrate (миграции), s3-init (bucket + проверка анонимного 403).

Перенесено из lab3: весь src/messenger, Redis-сессии, идемпотентность POST сообщений в PostgreSQL, ≥2 реплики за HAProxy с server-template, one-shot миграции, лимиты CPU/RAM, hook-скрипты, студенческие тесты, доказательства уровня 4 lab3 (поочерёдный отказ каждой реплики и rolling update под нагрузкой, повторены на стенде lab4).

Решения lab4:

  • S3-сервер — SeaweedFS 3.97 (образ закреплён по digest), том s3data. Все его порты (master/filer/volume UI и gRPC) привязаны к 127.0.0.1 внутри контейнера. В internal-сеть storage попадает только S3 API через сайдкар s3-gw в том же network namespace. Сеть storage видят лишь api и s3-init. Анонимной identity нет.

    У s3 и s3-gw, как у остальных долгоживущих сервисов, стоит restart: unless-stopped; у one-shot migrate и s3-init политики нет. После рестарта s3 получает новый network namespace, а s3-gw остаётся в старом, где есть только lo. Поэтому HAProxy в s3-gw запущен через infra/s3-gw-entrypoint.sh: скрипт раз в 2 с проверяет интерфейсы. Если остался один lo, он выжидает 5 с и завершает контейнер, а restart policy запускает s3-gw уже в namespace нового s3. Healthcheck s3-gw проверяет то же условие. Перезапуски через compose (restart s3) перезапускают и s3-gw (depends_on … restart: true).

  • Credentials: init_secrets.py генерирует две identity SeaweedFS.

    • admin — только у s3-init;
    • messenger-api — права Read/Write/List только на bucket вложений.

    Секреты передаются как Docker secrets (*_FILE), общий .env в контейнеры не пробрасывается.

  • Модель данных (003_attachments.sql):

    • attachments (id, chat_id, owner_id, filename, content_type, size_bytes, sha256, width, height, object_key, status=ready);
    • upload_intents (object_key, created_at);
    • связь «сообщение — вложения» с позицией: порядок attachment_ids сохраняется.

    Object key = случайный UUID, назначается сервером; filename служит только для отображения.

  • Конвейер загрузки (attachments.py):

    1. До чтения тела проверяются filename (400), Content-Type (415), членство в чате (404) и наличие слота (8 на реплику, ожидание 5 с, иначе 503).
    2. Тело читается кусками по 64 KiB, на каждом куске проверяются лимиты: 10 MiB (413), idle 10 с, общий дедлайн 120 с. Байты сразу идут в потоковый валидатор и во временный файл /tmp/messenger-spool.
    3. PNG проверяется прямо в потоке, вместе с полной распаковкой IDAT. Лимит 40 млн пикселей проверяется по IHDR/SOF до распаковки.
    4. JPEG после потоковой проверки структуры полностью декодируется: djpeg -strict -scale 1/8 под prlimit --as=384MiB, таймаут 15 с, 1 декодирование на реплику.
    5. intent → S3 PUT из файла → транзакция «INSERT attachments + DELETE intent» → 201 ready. Временный файл удаляется в finally.

    Честно о буферизации: тело (≤10 MiB) буферизуется на диске реплики на время запроса и не стримится в S3 напрямую. Зато оно не накапливается в RAM, и после ответа на реплике ничего не остаётся (тест test_no_original_kept_on_api_replicas, selfcheck-spool.json).

  • Балансировка — balance leastconn в обоих backend HAProxy. Загрузка вложения держит соединение секунды, а round-robin этого не видит и может отправлять длинные upload на занятую реплику, пока у другой свободны слоты. leastconn выбирает реплику с наименьшим числом открытых соединений. При равной нагрузке реплики чередуются, поэтому последовательные короткие запросы по-прежнему видят обе реплики (40 запросов → 20/20). Сравнение — в эксперименте с памятью ниже (evidence/lb-interleave.json).

  • Readiness = PostgreSQL + Redis + S3: S3 стоит на обязательном синхронном пути upload/download. Чтобы падение S3 не обрушило текстовый чат, HAProxy при nbsrv(messenger_api) = 0 переключается на backend с проверкой /health/live. Затронутые endpoint отвечают JSON 503 самого API, остальные работают.

  • Таймауты против зависаний:

    • S3: connect 2 с, read 5 с, 2 попытки. dns_opt timeout:1 attempts:1, иначе неудачный DNS-запрос к остановленному s3 занимал 8 с.
    • PostgreSQL: watchdog обрывает сокет libpq у соединения, занятого дольше 6 с, затем breaker на 3 с. statement_timeout при docker pause не срабатывает, потому что сервер заморожен.
    • HAProxy: timeout server 45s больше худшего пути API (≈35 с).
  • Graceful shutdown реплики с окном drain (lifecycle.DrainingServer — подкласс uvicorn.Server). Процесс API — PID 1 (exec-форма CMD), поэтому SIGTERM от docker stop приходит прямо в него.

    1. Первый SIGTERM переводит в 503 «Shutting down» только /health/ready. Остальные запросы обслуживаются как обычно в течение SHUTDOWN_DRAIN_SECONDS=3: этого хватает, чтобы HAProxy (inter 1s fall 2) исключил реплику.
    2. Затем uvicorn закрывает listener и до SHUTDOWN_TIMEOUT_SECONDS=8 ждёт идущие запросы, включая загрузку (spool → S3 PUT → COMMIT).
    3. Lifespan останавливает reconciler (join ≤1 с) и закрывает Redis и пул БД (≤1 с).

    stop_grace_period: 15s больше 3 + 8 + 2 с; скрипты, которые зовут docker stop напрямую, используют -t 15. Если запрос всё-таки прерван по таймауту, исход тот же, что при падении процесса: intent остаётся для reconciler, ветка CommitUncertain не меняется. Остановка реплики длится ≈3.6 с вместо ≈0.6 с, зато HAProxy больше не получает от неё 503.

  • Переменные .env.example → конфигурация: compose подставляет все параметры загрузки и S3 в api (S3_*, MAX_*, UPLOAD_*, RECONCILE_INTERVAL_SECONDS, SHUTDOWN_*). Секретные значения лежат не в .env, а в ./secrets/* (gitignored) и монтируются по *_FILE. API_REPLICAS читают scripts/up.*. Каждая ${VAR} из compose.yaml есть в .env.example (проверено скриптом).

  • Миграции lab4:

    • 003_attachments.sql;
    • 004_message_text_bytes.sql: messages.text → BYTEA, idempotency_records.response_body → JSON. PostgreSQL TEXT/JSONB не хранят U+0000, а контракт разрешает его в тексте.

Согласованность PostgreSQL и S3

Отказ Что делает код Итог
БД недоступна до PUT intent не записан → 503 в S3 ничего нет
S3 PUT упал компенсация: DELETE объекта (если S3 жив) и intent нет объекта, нет метаданных (selfcheck A)
PUT прошёл, INSERT/COMMIT достоверно откатился компенсация удаляет объект и intent selfcheck B
Обрыв связи во время COMMIT (исход неизвестен) CommitUncertain → 503, объект не удаляется если COMMIT прошёл — ready с байтами; если нет — intent остаётся для reconciler (selfcheck F)
Процесс упал между PUT и COMMIT / компенсация не смогла удалить остаётся intent reconciler удаляет объект и intent после grace (selfcheck C, reconcile-run.txt)
Объект без intent и без метаданных sweep по LastModified объекта удаляется только старше grace (selfcheck D)

Reconciler (messenger.reconcile):

  • работает в фоне на каждой реплике раз в 300 с ±20%; одновременно — только один (pg_try_advisory_lock);
  • запускается и из CLI с --dry-run, --grace-seconds, --check-missing;
  • grace = 900 с, это ≥ 2 × дедлайна загрузки 120 с, поэтому идущая загрузка не может быть старше grace;
  • intent берётся FOR UPDATE SKIP LOCKED и не гонится с COMMIT той же загрузки;
  • объект, ключ которого есть в attachments, не удаляется никогда, даже при --grace-seconds 0 (selfcheck E);
  • метаданные reconciler не удаляет: отсутствующий оригинал только репортится.

Доказательства критериев

Критерий README Команда/сценарий Наблюдаемый результат Файл доказательства
Offline check / OpenAPI check_contract.py, validate_openapi.py PASS / PASS evidence/check.txt, evidence/validate.txt
Публичный smoke lab4 tests/smoke.py PASS lab4 public API scenario (checksum, 404 постороннему) evidence/smoke.txt
Все студенческие тесты (уровни 3–4 + lab3) student-tests/run_all.py, RUN_DOCKER_TESTS=1 RUN_DEPS_TEST=1 69 passed, 0 failed (тест истечения сессии при TTL 3600 печатает SKIP; отдельно при SESSION_TTL_SECONDS=2: 2 passed) evidence/student-tests.txt, evidence/session-expiry.txt
Байты в приватном bucket, не в БД/на API test_no_original_kept_on_api_replicas, selfcheck spool на репликах нет файлов с SHA-256 оригинала, spool пуст evidence/student-tests.txt, evidence/selfcheck-spool.json
Upload → stop обслужившей → download через другую scripts/attachment_failover_evidence.py (2 раунда) первый 200 через 3.625 с / 3.64 с от начала docker stop (сама остановка с окном drain — 3.59 / 3.62 с); 20+20 скачиваний, 0 ошибок, SHA-256 совпадает, остановленная не отвечала evidence/attachment-failover.json
Restart с сохранением volumes scripts/full_restart_evidence.py (down без -v → up) down 15.0 с, down→ready 45.6 с; тот же token, метаданные, SHA-256, текст с U+0000; bucket exists evidence/full-restart.json
Persistence/failover (публичные) tests/resilience.py persistence PASS (хук перезапускает API, PostgreSQL, Redis, S3); failover PASS: до отказа видны 2 реплики, 127 записей, 0 неудачных попыток; тест засчитывает запись только после возврата хука, первая — через 3.95 с от его старта (хук ждёт drain ≈3.6 с, запись при этом не прерывалась) evidence/persistence*.txt, evidence/failover*.txt
Поочерёдный отказ каждой реплики (lab3) scripts/seq_failover_evidence.py (2 раунда, stop-one → запись → restore) раунд 0: 168 записей, 0 неудачных попыток, первая запись после возврата хука через 3.906 с; раунд 1: 166 записей, 0 неудачных попыток, 3.89 с; в каждом раунде до отказа видны обе реплики, остановленная отсутствует в последних 5 ответах, после restore снова в ротации LB через 3.5 / 2.938 с evidence/seq-failover.json
Rolling update под нагрузкой (lab3) scripts/rolling_load_evidence.py (4 потока POST, scripts/rolling-update.* — та же процедура) обе реплики заменены новыми контейнерами за 23.9 с: 1436 успешных, 0 ошибок, p50/p95/p99 = 16/47/62 мс (предыдущий прогон: 1332 успешных, 0 ошибок; до graceful drain было 857 успешных и 4 × 503) evidence/rolling-load.json
Graceful shutdown реплики student-tests/test_shutdown.py (RUN_DOCKER_TESTS=1) после SIGTERM 22 пробы изнутри реплики: /health/ready 503, /users/me 200, выход через 3.29 с; docker stop под нагрузкой — 405 × 201, 0 ошибок, 58 из них обслужила останавливаемая реплика, остановка 3.58 с; загрузка, тело которой ещё шло при закрытии listener, → 201 и скачивается через LB evidence/student-tests.txt
Балансировка длинных загрузок scripts/lb_interleave_evidence.py (8 медленных загрузок вперемешку с короткими GET) roundrobin: загрузки 8/0 по репликам; leastconn: 4/4; все 201 evidence/lb-interleave.json
Слишком большой файл test_too_large_413, test_exact_limit_png_through_lb_accepted 10 485 760 байт → 201 через LB; +1 байт и chunked без длины → JSON 413 evidence/student-tests.txt
Пиксели test_too_many_pixels_413 8000×5000 → 201, 8000×5001 → 413 evidence/student-tests.txt
Повреждённое изображение test_corrupted_images_415, test_reviewer_corrupted_images_415 11 повреждённых PNG и 7 JPEG → 415; Adam7 PNG со всеми фильтрами и progressive JPEG → 201 evidence/student-tests.txt
Независимая перекрёстная проверка корпуса scripts/decoder_crosscheck.py (Pillow 11.1 + djpeg -strict) PASS: все повреждённые не декодируются (4 PNG — нарушения спецификации, которые Pillow терпит), все валидные декодируются evidence/decoder-crosscheck.txt
Подмена MIME test_mime_spoofing_415 PNG как image/jpeg и наоборот, GIF/PDF/HTML/EXE, чужие Content-Type → 415 evidence/student-tests.txt
Чужое attachment_id / файл другого чата test_foreign_and_unknown_attachment_ids_404 404 для обоих, сообщение не создаётся evidence/student-tests.txt
Пользовательская ошибка ≠ 500 хелпер upload проверяет статус < 500 во всех негативных тестах 0 ответов 5xx на пользовательские ошибки evidence/student-tests.txt
Прерывание загрузки test_interrupted_and_stalled_uploads_leave_nothing обрыв и зависание тела → объектов/intent не прибавилось, сервис жив evidence/student-tests.txt
Отказ между S3/БД, компенсация, сверка selfcheck consistency (A–F), reconcile все проверки ok; реальный проход: 10 зависших intent (хвосты отказов S3) удалены, повтор — 0; объектов 1382 → 1378, 0 orphan, 0 missing evidence/selfcheck-consistency.json, evidence/reconcile-run.txt
≥10 одновременных загрузок, пик памяти scripts/upload_memory_experiment.py --levels 10 20 40 см. эксперимент ниже evidence/upload-memory.json
Bucket bootstrap идемпотентен повторный s3-init при каждом up bucket exists … anonymous access denied (HTTP 403); bootstrap complete evidence/full-restart.json
Отдельные S3 credentials с ограниченными правами selfcheck s3 ключ API: ListBuckets/CreateBucket/DeleteBucket/ACL/чужой bucket → 403 AccessDenied evidence/selfcheck-s3.json
Private bucket вне API, консоль закрыта selfcheck s3 (из сети storage), test_bucket_private_and_api_key_least_privilege анонимный GET/LIST → 403; порты 8333/18333/8888/18888/9333/19333/8080/18080 закрыты, открыт только S3 API evidence/selfcheck-s3.json
Недоступность S3 test_s3_stop_degrades_only_attachments ready 503; upload 503 за 0.11 с; download 503; метаданные 200 и сообщение 201; после старта S3 — download 200 evidence/student-tests.txt
Пауза/остановка PostgreSQL, Redis test_postgres_pause_fails_fast, test_postgres_stop_returns_503, test_redis_stop_returns_503_or_unready pause: JSON 503 за 6.14 / 3.03 / 6.22 с (все < 15 с), ready 503, после unpause 200; stop: 503 < 15 с evidence/student-tests.txt
Нагрузка (baseline) tests/load.py --duration 20 --concurrency 4 5319 успешных, 0 ошибок, 265.13 RPS, p50/p95/p99 = 15/32/78 мс evidence/load.json

Hook-скрипты (scripts/restart.*, scripts/stop-one.*) действительно перезапускают и останавливают контейнеры. Это видно по docker compose ps до и после (evidence/*-ps-*.txt): в failover остановленная реплика Exited (0), в persistence заново стартуют postgres, redis, s3 и api. Последнее закреплено тестом test_restart_hook_restarts_api_and_stores: он сравнивает StartedAt контейнеров до и после хука.

Эксперименты и отказы

Память при одновременных загрузках (evidence/upload-memory.json).

Гипотеза: потоковая обработка (64 KiB → валидатор → файл → PUT из файла) удерживает рост RSS процесса API намного ниже N × размер файла, LB не накапливает тела, а S3-сервер выдерживает все PUT, которые пропускают слоты API.

Методика:

  • PNG 9 960 421 байт, N загрузок одновременно (barrier) через LB;
  • перед каждым уровнем — свежий restart s3, s3-gw, api и lb, прогрев каждой реплики;
  • сброс VmHWM, опрос cgroup (API, LB, S3) каждые 0.25 с;
  • 2 реплики по 512m / 0.5 CPU, LB 128m / 0.25 CPU, S3 1g / 0.5 CPU с GOMEMLIMIT=768MiB, один прогон на уровень.
N статусы p50 / max, с рост RSS API (VmHWM − база), MiB cgroup peak API, MiB page cache API, MiB cgroup peak LB, MiB (лимит 128) S3: max anon / cgroup peak, MiB (лимит 1024)
10 10 × 201 3.03 / 3.42 16 / 16 151.8 / 155.2 47.5 / 47.5 31.8 401.3 / 547.6
20 18 × 201, 2 × 503 6.16 / 6.36 24 / 29 192.1 / 181.9 76.0 / 76.0 40.7 541.0 / 734.0
40 18 × 201, 22 × 503 6.30 / 7.00 28 / 31 187.2 / 198.7 76.0 / 76.0 60.3 566.4 / 733.0

Интерпретация:

  • Рост RSS — 16–31 MiB при 5–20 загрузках на реплику. Полная буферизация в RAM дала бы 47.5–76 MiB только на тела (naive_full_buffer_estimate_mib), поэтому тела в памяти процесса не держатся.
  • Рост cgroup в основном состоит из page cache временных файлов (до 76 MiB = 8 слотов × 9.5 MiB). Это ядро, и cache вытесняем.
  • При N = 20 и 40 срабатывает backpressure: слотов 2 × 8, ожидание 5 с, а лишние запросы получают JSON 503 «Too many concurrent uploads» с Retry-After вместо роста памяти. Текст 503 проверен отдельным прогоном (evidence/s3-memory-limit.txt, блок AFTER): все не-201 ответы — именно этот отказ по слотам, ошибок хранилища нет.
  • Балансировка на пике не узкое место. Под leastconn на N = 40 — 18 × 201 / 22 × 503, запросы разошлись ровно 20/20 (uploads_served): пачка приходит одновременно, и у реплик в каждый момент поровну открытых соединений. Число 201 ограничивают 16 слотов: загрузка 9.5 MiB занимает слот ≈6 с, дольше 5-секундного ожидания, поэтому из очереди успевают единицы.
  • leastconn выигрывает при смешанном трафике, когда длинные загрузки чередуются с короткими запросами (scripts/lb_interleave_evidence.py → evidence/lb-interleave.json; 8 загрузок по 1 MiB с телом, которое отправляется ≈4 с, между ними короткие GET; для прогона roundrobin в конфиге LB временно возвращалась прежняя стратегия). Round-robin отправил все 8 загрузок на одну реплику, а все GET — на другую (8/0). leastconn разложил загрузки 4/4.
  • LB не падал (restarts 0, OOMKilled false). Раньше, до фиксации сокетных буферов (tune.*buf, sysctl tcp_rmem/wmem), он уходил в OOM на 40 загрузках.
  • S3 не падал (running, OOMKilled false). Один процесс weed держит ≈30–40 MiB на каждый идущий PUT 10 MiB. При прежних 512m без GOMEMLIMIT он упирался в лимит уже на 10 загрузках и на 20 был убит OOM (exit 137) — см. «Найденные и исправленные по ходу дефекты» и evidence/s3-memory-limit.txt.
  • Ограничение замера: один хост, один прогон на уровень, клиент на том же хосте. Пик S3 зависит от момента сборки мусора Go и меняется между прогонами: в отдельном прогоне (s3-memory-limit.txt, AFTER) max anon составил 481–635 MiB, в этом — 401–566 MiB.

Память полного декодирования JPEG (evidence/jpeg-decode-memory.txt; 8000×5000, отдельный процесс на файл):

файл размер время пик RSS djpeg
baseline 4:2:0 9.20 MiB 0.10 с 10.8 MiB
progressive 4:2:0 8.09 MiB 0.53 с 116.7 MiB
progressive 4:4:4 8.23 MiB 0.70 с 231.0 MiB
progressive CMYK 18.19 MiB 1.32 с 307.1 MiB

Отсюда лимиты:

  • prlimit --as=384MiB, проверено: под 256MiB худший случай даёт «Insufficient memory» → API отвечает 503, а не 415;
  • одно декодирование на реплику;
  • mem_limit: 512m у API.

CMYK-файл больше 10 MiB и через API не пройдёт. Это верхняя оценка памяти.

Отказы:

Воздействие Что ожидаем Что наблюдали Время восстановления / потеря данных
stop-one API (публичный failover) запись через оставшуюся ≤10 с, без дублей 127 записей, 0 неудачных попыток запись не прерывалась; хук возвращается через ≈3.6 с (drain), первая засчитанная запись через 3.95 с; подтверждённые данные целы
stop-one каждой из двух реплик по очереди запись через оставшуюся, остановленная не отвечает 168 + 166 записей, 0 неудачных попыток первая запись после хука через 3.906 / 3.89 с; после restore реплика в ротации через 3.5 / 2.9 с
Rolling update: stop → rm → новый контейнер, по одной реплике сервис не прерывается 1436 × 201, 0 ошибок следующая реплика останавливается только после того, как LB отдаёт ответы новой
docker stop реплики под нагрузкой (test_shutdown) ни одной ошибки, реплика дослуживает окно drain 405 × 201, 0 ошибок, 58 ответов от останавливаемой остановка 3.58 с, после start в ротации через 2.5 с
Stop реплики, загрузившей файл download через другую 0 ошибок за 2 × 20 скачиваний 3.625 / 3.64 с от начала docker stop (остановка 3.59 / 3.62 с)
docker compose down → up (тома сохранены) те же token, файл, текст всё совпало down 15.0 с, 45.6 с до ready; потерь нет
docker restart контейнера s3 / падение процесса weed пара s3 + s3-gw поднимается сама s3-gw выходит из старого namespace, restart policy запускает его в новом; upload 201 и download 200 с тем же SHA-256 ready 200 через 37 / 29 с; потерь нет (evidence/s3-restart.txt)
docker compose stop s3 ready 503, вложения 503, чат работает так и есть, upload 503 за 0.11 с после start s3 download 200, хвост intent убран reconciler
docker compose pause postgres JSON 503 за ограниченное время, восстановление каждый запрос — 503 не дольше ≈6.3 с: watchdog 6 с, ожидание пула 3 с, пока breaker открыт — сразу (в прогоне 6.14 / 3.03 / 6.22 с); ready 503 после unpause 200, перезапусков реплик 0
docker compose stop postgres / stop redis 503 JSON, восстановление 503 < 15 с; logout при упавшем Redis → 503 (не ложный 204) 200 после start
40 одновременных загрузок 9.5 MiB без OOM, лишние — 503 18 × 201, 22 × 503; LB peak 60.3 MiB, S3 anon 566.4 MiB из 1024 LB и S3 без рестартов

Найденные и исправленные по ходу дефекты:

  • Двойной close() дескриптора в watchdog БД. uvloop падал с uv__io_poll: Assertion errno == EEXIST, реплика перезапускалась и отдавала 502. После исправления тест паузы прошёл 3 раза отдельно и ещё в двух полных прогонах, без рестартов реплик.
  • timeout connect 3s в HAProxy был больше 2-секундного таймаута клиента в публичном failover-тесте. Стало 1s + observe layer4.
  • Неверный путь при остановленном S3. Раньше upload давал 504 через 30 с из-за медленного DNS, теперь 503 не дольше 2 с (в последнем прогоне — 0.11 с).
  • OOM SeaweedFS при параллельных загрузках. Слоты API пропускают до 2 × 8 = 16 одновременных PUT, а один weed держит ≈30–40 MiB на каждый. С mem_limit: 512m без мягкого лимита Go anon доходил до 494 MiB уже при N = 10, а при N = 20 контейнер s3 был убит OOM (exit 137). Загрузки получали 503 «Attachment storage unavailable», хвосты intent потом убирал reconciler. Стало: mem_limit: 1g и GOMEMLIMIT=768MiB — OOM нет, max anon 481–635 MiB (evidence/s3-memory-limit.txt, блоки BEFORE/AFTER). Тест: test_parallel_large_uploads_keep_s3_within_memory.
  • Ёмкость S3 была ограничена 9 томами по 512 MiB (≈4.7 GiB) при свободном диске. Из 16 слотов -volume.max=16 7 занимает служебный collection по умолчанию. Когда 9 томов бакета заполнились, каждый PUT получал от SeaweedFS «No writable volumes», и API отвечал 503 при /health/ready = 200. Стало -volume.max=0: SeaweedFS считает лимит как свободное место ÷ размер тома, на стенде 1896 слотов, свободно 1873 (evidence/s3-volumes.json). Тест: test_s3_can_grow_volumes.
  • Хук scripts/restart.* не перезапускал API. up -d --scale не трогает уже работающие реплики, поэтому публичный persistence проверял перезапуск хранилищ без перезапуска API (tests/README требует «API и всех используемых хранилищ»). Добавлен docker compose restart api. Тест: test_restart_hook_restarts_api_and_stores сравнивает StartedAt до и после.
  • Rolling update из lab3 не заменял реплики и не дожидался новой. docker stop + up --scale api=2 просто запускал тот же остановленный контейнер, а готовность проверялась по публичному /health/ready, который отвечает 200 через оставшуюся реплику. Поэтому вторая реплика останавливалась, пока первая ещё стартовала: 10 ошибок за прогон, в конце одна реплика не была healthy. Стало: stop → rm → up --no-recreate --scale api=N создаёт новый контейнер и не трогает работающий; следующий шаг начинается, когда LB отдаёт ответы с X-Instance-Id нового контейнера. То же ожидание добавлено в restore seq_failover_evidence.py. Итог: вместо 10 ошибок оставались единичные JSON 503 от останавливаемой реплики (их убрал graceful drain, следующий пункт), ID контейнеров до и после различаются (evidence/rolling-load.json, поле replaced).
  • Останавливаемая реплика отвечала JSON 503 на живой трафик. По SIGTERM она сразу снимала readiness и отвечала 503 «Service unavailable» на все запросы, а uvicorn закрывал listener. HAProxy же ещё 1–2 с (inter 1s fall 2) направлял на неё запросы. Быстрые 503 не держат соединений, поэтому leastconn отправлял на неё заметную долю трафика: rolling update под нагрузкой давал 4 ошибки на 857 успешных, под round-robin — 1. Стало: окно drain (lifecycle.DrainingServer, см. «Решения lab4»), в нём 503 отдаёт только /health/ready. Результат: rolling update — 0 ошибок в двух прогонах (1332 и 1436 успешных), failover — 0 неудачных попыток вместо 1. Тесты test_shutdown.*: на прежней сборке test_replica_stop_under_load_has_no_errors получил 4 × 503, а test_sigterm_drains_readiness_but_keeps_serving — выход реплики сразу после SIGTERM; на текущей оба проходят.
  • Filename с невалидным UTF-8 молча переписывался. Starlette заменяет такие байты в query_params на U+FFFD, поэтому ?filename=%FF%FE.png превращался в "\ufffd\ufffd.png" и проходил проверку, а из повторённых filename молча брался последний. Теперь query разбирается строго (attachments.query_filename): невалидный UTF-8 (включая суррогаты %ED%A0%80) и повтор filename → 400. Тест: test_filename_query_decoded_strictly_400.
  • После рестарта s3 хранилище вложений не возвращалось. У s3 и s3-gw не было restart policy, и после рестарта Docker они не поднялись бы сами. Кроме того, после docker restart s3 контейнер s3-gw оставался в старом network namespace: s3 был healthy, а /health/ready больше 90 с отвечал 503. Healthcheck s3-gw (haproxy -c) при этом показывал healthy. Стало: restart: unless-stopped и entrypoint-сторож s3-gw (см. «Решения lab4»). docker restart s3 → ready 200 через 37 с, падение процесса weed → через 29 с; upload и download после этого работают (evidence/s3-restart.txt).

Ответы на вопросы защиты

  • Почему файл в Docker volume одной API-реплики не равен объектному хранилищу?
    • Volume принадлежит одному контейнеру и хосту. Другая реплика его не видит: download после остановки загрузившей реплики вернул бы 404 или 500. Масштабирование и замена контейнера тоже теряют файл.
    • У такого volume нет независимого жизненного цикла, ключей доступа, политики bucket и общего для всех реплик namespace.
    • S3 — отдельный сервис с собственным томом, к нему одинаково обращаются все реплики. Поэтому failover вложений и работает (attachment-failover.json).
  • Когда можно честно вернуть 201?
    • Только когда объект целиком и успешно записан в S3 (PUT подтверждён, размер и SHA-256 посчитаны по реально прочитанным байтам) и транзакция с метаданными ready закоммичена в PostgreSQL.
    • После этого любая реплика отдаёт файл побайтно. 201 до PUT или до COMMIT обещал бы данные, которых может не быть.
  • Что, если S3 PUT прошёл, а COMMIT в PostgreSQL — нет?
    • Если откат достоверен (ошибка до COMMIT или транзакция не начиналась), API удаляет объект (компенсация) и intent, а клиент получает 503.
    • Если связь оборвалась во время самого COMMIT, исход неизвестен. Объект не удаляется (CommitUncertain), иначе могли бы остаться метаданные ready без байтов.
    • Если COMMIT всё-таки прошёл, intent удалён в той же транзакции и объект защищён ссылкой из attachments. Если не прошёл, осталась строка intent, и reconciler удалит объект после grace 900 с.
    • Если процесс упал между PUT и COMMIT, тоже остаётся intent → reconciler. Объект без всякой ссылки удаляет sweep, но только когда он старше grace по LastModified.
  • Почему случайный object key и приватный bucket не заменяют ACL приложения?
    • Приватный bucket защищает от анонимного доступа к S3, но не различает пользователей приложения: у API один ключ на всех.
    • Случайный ключ — это секрет-ссылка. Его не отозвать, он может утечь (логи, пересланная ссылка), а бывший участник чата продолжал бы им пользоваться.
    • Решение «кто может видеть файл» зависит от членства в чате прямо сейчас, и знает это только приложение. Поэтому каждый download идёт через API с проверкой сессии и членства в чате вложения: посторонний получает 404 и на метаданные, и на bytes.

Ограничения

  • Один Docker-хост, по одному экземпляру PostgreSQL, Redis, SeaweedFS и LB. Отказ API-реплики выдерживается, отказ хоста, БД или S3 — нет. При недоступном S3 работает только текстовая часть.

  • Тело загрузки (≤10 MiB) буферизуется во временный файл на реплике до PUT, прямой потоковой передачи в S3 нет. Page cache этих файлов учитывается в cgroup контейнера.

  • Вызовы БД синхронные (psycopg в threadpool, часть — в event loop). При зависшей БД запрос ждёт до 6 с (watchdog), дальше breaker отвечает сразу.

  • s3-gw привязан к контейнеру s3. Падение или docker restart s3 пара переживает сама (см. «Решения lab4»). Есть два исключения:

    • после пересоздания одного s3 (up -d --force-recreate s3) у него новый ID, и s3-gw не может к нему присоединиться. Нужен обычный docker compose --env-file .env up -d, который пересоздаёт и s3-gw;
    • Docker не повторяет старт, который не удался из-за того, что s3 ещё не запущен. Если после рестарта Docker-демона s3-gw окажется в Exited, его поднимает тот же docker compose up -d. Рестарт самого демона на стенде не проверялся.

    docker compose stop s3 + start s3 (как в test_s3_stop_degrades_only_attachments) — ручная остановка: restart policy на неё не действует, поэтому тест после start s3 делает restart s3-gw.

  • Память и ёмкость S3. s3 получает 1g и GOMEMLIMIT=768MiB под 16 одновременных PUT (2 реплики × 8 слотов). При увеличении числа реплик или слотов лимит надо пересчитать (≈30–40 MiB на PUT). Число томов ограничено только свободным местом (-volume.max=0). Readiness не проверяет свободное место: при заполненном диске загрузки дадут 503 при ready 200.

  • Остановка реплики занимает ≈3.6 с из-за окна drain, поэтому stop-one, rolling update и docker compose down идут на ≈3 с дольше. Окно рассчитано на health check HAProxy inter 1s fall 2: при изменении этих параметров надо пересчитать SHUTDOWN_DRAIN_SECONDS и stop_grace_period. Запрос, который не уложился в 8 с после закрытия listener (например, медленный клиент загрузки), обрывается. Это равносильно падению процесса: клиент не получает ответа и повторяет запрос (POST сообщения — с тем же Idempotency-Key), хвост intent убирает reconciler. Отказ реплики без SIGTERM (kill -9, OOM) по-прежнему может дать единичные ошибки, пока HAProxy её не исключит.

  • Конфиги HAProxy примонтированы файлом. После правки нужен docker compose restart lb.

  • PNG проверяется строже Pillow по 4 правилам спецификации (PLTE и неизвестный критический чанк), как libpng. Кроме того, отвергаются (415) PNG с данными после IEND и без IEND, хотя Pillow такие открывает. Это сознательная политика: поток PNG по спецификации заканчивается на IEND. Для JPEG данные после EOI допускаются, как в распространённых декодерах.

  • Ошибки разбора HTTP самим HAProxy (400/408 на некорректный запрос) отдаются его стандартной HTML-страницей. http-error на ошибки уровня H1-парсера не действует. 413 формирует API (лимит тела у LB не задан), а 502/503/504 самого LB — http-error с JSON, X-Request-Id и X-Instance-Id.

  • Если в JPEG-декодере не хватило памяти, это 503, а не 415: это ресурсный отказ, а не ошибка пользователя.

  • Windows: публичные тесты требуют PYTHONUTF8=1; make не установлен — использовались эквивалентные команды из Makefile.

  • Трек 5 не выполнялся. Reconciler с dry-run есть, но исследование трека 2 не заявляется.