Files
mtusi2026lab4/REPORT.md
T
2026-10-30 16:53:49 +03:00

30 KiB
Raw Blame History

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

  • Автор, группа: Максимова, БВТ2303 (TODO: полное ФИО)
  • Целевая оценка; выбранный трек 5: 4 (трек не выбирается)
  • Commit/PR: TODO после публикации (ветка solution/maksimova_bvt2303)
  • Использованные источники, библиотеки и помощь ИИ: FastAPI, SQLAlchemy/asyncpg, argon2-cffi, redis-py, aiobotocore/botocore, Pillow (только для JPEG); SeaweedFS, PostgreSQL, Valkey, HAProxy. Документация: AWS S3 PutObject/SigV4, SeaweedFS wiki (S3 API, s3.json identities), спецификация PNG (RFC 2083), HAProxy 3.0 configuration manual. Помощь ИИ (Claude Code): ревью и доработка кода вложений, написание тестов в student-tests/, проведение экспериментов и черновик этого отчёта; все результаты получены реальными прогонами на стенде и проверены.

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

Проверено на: Windows 11 + Docker Desktop 29.3.0 (WSL2, kernel 6.6.87, 14 vCPU, 7.4 GiB RAM), Docker Compose 5.1.0, Python 3.13 на хосте (для make test; достаточно 3.9+).

Роль т Service т Образ Health / readiness Volume Сеть / порт Credentials
LB lb haproxy:3.0.11-alpine /lb-health; backend-check GET /health/ready раз в 1 s — edge; ${LB_PORT:-8080} на хосте, stats только 127.0.0.1:8404 —
API × 2 api сборка Dockerfile (python:3.12.7-slim) /health/ready (PostgreSQL + не в drain) нет edge + backend, порт не публикуется Docker secrets: database_url, cache_url, s3_access_key_id, s3_secret_access_key
PostgreSQL db postgres:16.4-alpine pg_isready postgres_data backend (internal) postgres_password
Valkey (кэш сессий) valkey valkey/valkey:8.0.1-alpine PING нет (кэш, источник истины — PostgreSQL) backend valkey_password
S3 s3 chrislusf/seaweedfs:3.97 GET :9000/healthz s3_data backend, порт не публикуется; master/filer/volume слушают только 127.0.0.1 внутри контейнера admin + API ключи из secrets подставляются в s3.json при старте
Bootstrap bucket s3-init образ API one-shot, service_completed_successfully — backend единственный, кто получает admin-ключ S3
Миграции migrate образ API one-shot — backend database_url
sh scripts/init-secrets.sh            # создаёт infra/secrets/*.txt (случайные значения, не перезаписывает, не печатает)
cp .env.example .env                  # при занятом 8080 задайте LB_PORT=8081
docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build
#  порядок: db, valkey, s3 -> healthy -> migrate (SQL migrations/*.sql, повтор = SKIP)
#           s3-init (bucket + самопроверки приватности/прав, повтор = keep) -> api x2 healthy -> lb
curl -fsS http://localhost:${LB_PORT:-8080}/health/ready
make test BASE_URL=http://localhost:${LB_PORT:-8080}      # на Windows: PYTHONUTF8=1 python tests/smoke.py --base-url ...

# hook-тесты и собственные проверки — в Linux-контейнере tester (docker CLI + docker.sock):
docker compose --profile tools run --rm tester make test-persistence ACTION_SCRIPT=scripts/restart.sh BASE_URL=http://lb:8080
docker compose --profile tools run --rm tester make test-failover   ACTION_SCRIPT=scripts/stop-one.sh BASE_URL=http://lb:8080
docker compose --profile tools run --rm tester sh scripts/start-api.sh       # вернуть остановленную реплику
docker compose --profile tools run --rm tester python3 student-tests/<test>.py

docker compose stop                   # безопасная остановка, данные сохраняются
docker compose down -v                # НАМЕРЕННОЕ удаление всех учебных данных (volumes)

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

client -> HAProxy (lb) -> api x2 --+--> PostgreSQL: users, chats, messages, sessions, idempotency_keys,
                                   |               attachments (метаданные), message_attachments, upload_intents
                                   +--> Valkey: кэш сессий (tombstone при logout)
                                   +--> SeaweedFS S3: приватный bucket messenger-attachments/originals/<random hex>

Перенесено из lab3 без изменения контракта: регистрация/Basic→Bearer, сессии в PostgreSQL с кэшем в Valkey, идемпотентная отправка сообщений, X-Instance-Id, graceful drain, HAProxy с active check, hooks restart.sh/stop-one.sh. Изменено: CreateMessage принимает attachment_ids (по умолчанию []) и text="" при наличии вложений; fingerprint идемпотентности без вложений совпадает с lab3, так что старые ключи повторяются корректно.

Модель. attachments (id, chat_id, owner_id, filename — только для отображения, content_type, size, sha256, width/height, status=ready, object_key UNIQUE) привязано к чату при загрузке. message_attachments(message_id, attachment_id, position) хранит порядок; одно вложение можно сослать из нескольких сообщений чата. Миграция 004_attachments.sql — expand-only.

Upload (app/attachments.py), всё до сохранения байтов:

  1. filename (400: /, \, NUL, Cc/Cf/bidi, пустое/только точки, >255) → членство в чате (404) → Content-Type ровно image/png|image/jpeg (415, multipart не принимается) → Content-Length > 10 MiB → 413 без чтения тела;
  2. слот загрузки: ≤ MAX_CONCURRENT_UPLOADS=8 на реплику, ожидание ≤10 s, иначе 429;
  3. тело читается потоково в SpooledTemporaryFile (в RAM ≤ 1 MiB на загрузку), считается размер и SHA-256 на лету; превышение 10 MiB в chunked → 413; приём дольше 60 s → 400;
  4. проверка содержимого в потоке: формат по magic bytes и совпадение с заявленным MIME; PNG — собственный потоковый валидатор (CRC каждого чанка, IHDR, распаковка IDAT кусками по 64 KiB с подсчётом и сравнением с ожидаемым размером, без хранения пикселей); лимит 40 млн пикселей проверяется по IHDR/SOF до распаковки (413); JPEG — Pillow draft() 1/8 + load() (повреждённый поток → 415);
  5. INSERT upload_intent + COMMIT → S3 PUT (SigV4 подписывает SHA-256 тела) → одна транзакция «DELETE intent + INSERT attachment» → 201 ready. Честный 201 возможен только после этого COMMIT: и байты, и метаданные уже устойчивы.

Download: авторизация по chat_members в PostgreSQL (чужое/неизвестное → 404), затем потоковая отдача из S3 через API, без redirect, с истинным Content-Type, Content-Length, nosniff, Cache-Control: private, no-store. Приватный bucket не заменяет ACL: случайный ключ можно утечь через лог, а права участника чата знает только приложение.

Согласованность БД/S3 (ответ на «PUT прошёл, а COMMIT нет»):

Отказ Что делает система
PUT упал / истёк дедлайн 503 сразу. Исход PUT неизвестен (S3 может дописать объект после нашего DELETE), поэтому объект удаляется best effort в фоне, а intent остаётся; janitor удалит объект ещё раз после grace и только потом intent
COMMIT упал 503 сразу. Исход COMMIT тоже неизвестен (мог пройти, а потерялся ответ). Фоновая компенсация берёт SELECT … FOR UPDATE intent: intent нет → COMMIT прошёл, объект не трогаем; иначе DELETE объекта → DELETE intent
Процесс умер после PUT intent остался; janitor каждой реплики (JANITOR_INTERVAL_SECONDS=60, jitter) через UPLOAD_GRACE_SECONDS=900 удаляет объект и intent; FOR UPDATE SKIP LOCKED — реплики не мешают друг другу и финализирующейся загрузке
Строка без объекта (потеря байтов вне приложения) download → 500 internal_error и ERROR в логе; метаданные не удаляются (сообщения на них ссылаются)

Инвариант: объект без строки существует, только пока жив его intent; объект закоммиченной строки никогда не удаляется. Grace 900 s ≫ максимального времени upload (60 s приём + 16 s PUT).

Недоступность S3. /health/ready S3 не проверяет: без S3 деградируют только вложения (503), чаты и сообщения работают; иначе отказ S3 вывел бы из LB все реплики. Каждый S3-вызов ограничен общим дедлайном S3_OPERATION_TIMEOUT_SECONDS=6 (DNS + повторы) — меньше timeout server 10s у LB; для PUT дедлайн 6 s + size / 1 MiB/s (≤16 s для 10 MiB), а HAProxy даёт POST вложения 40 s. L7-повторы HAProxy для /api/v1/attachments/ отключены: 503 там означает отказ общего S3, повтор на другой реплике бесполезен.

Права S3 (infra/seaweedfs/s3.json.template): identity admin есть только у s3-init; identity messenger-api — Read/Write/List только на messenger-attachments (Write нужен для DELETE janitor-а). Анонимного доступа нет. Admin UI/API SeaweedFS (master 9333, filer 8888, volume 8080, gRPC) слушают только 127.0.0.1 внутри контейнера.

Соответствие .env.example:* APP_HOST/APP_PORT, SESSION_TTL_SECONDS, DATABASE_URL_FILE, SESSION_STORE=valkey, CACHE_URL_FILE, API_REPLICAS, IDEMPOTENCY_TTL_SECONDS, S3_ENDPOINT, S3_REGION, S3_BUCKET, S3_ACCESS_KEY_ID_FILE, S3_SECRET_ACCESS_KEY_FILE, MAX_UPLOAD_BYTES, MAX_IMAGE_PIXELS читаются app/config.py под теми же именами. Дополнительно в compose.yaml (x-api-env): S3_OBJECT_PREFIX, S3_CONNECT/READ/OPERATION_TIMEOUT_SECONDS, S3_PUT_MIN_BYTES_PER_SECOND, UPLOAD_SPOOL_MEMORY_BYTES, UPLOAD_TIMEOUT_SECONDS, MAX_CONCURRENT_UPLOADS, UPLOAD_SLOT_WAIT_SECONDS, UPLOAD_GRACE_SECONDS, JANITOR_INTERVAL_SECONDS, FAULT_INJECTION (только для экспериментов, пусто в норме). APP_ENV не используется.

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

Все файлы — в evidence/, тесты — в student-tests/; прогоны 2026-10-30 на стенде выше.

Критерий README Команда/сценарий Наблюдаемый результат Файл доказательства
Публичный smoke make test BASE_URL=http://localhost:8081 PASS: lab4 public API scenario (SHA-256, 404 постороннему) smoke.txt
3: S3 в стенде, метаданные в PG, байты в приватном bucket student-tests/s3_failures.py; api-no-local-files.txt object_key только в PG; анонимные GET/HEAD/LIST/PUT/DELETE напрямую в S3 → 403; у API нет volumes, /tmp пуст s3-failures.txt, api-no-local-files.txt
3: PNG/JPEG ≤10 MiB, ≤40 Мпикс, MIME по содержимому, опасные filename student-tests/attachment_edge_cases.py 60/60 OK: ровно 10 MiB и ровно 40 Мпикс → 201; +1 байт → 413; бомба 50 Мпикс (~10 KB) → 413 attachment-edge-cases.txt
3: upload → стоп обслужившей реплики → download через другую make test-failover ×2; student-tests/upload_failover.py failover: 0 ошибок, восстановление записи 4.0/4.2 s; для каждой из двух реплик SHA-256 совпал после её остановки failover.txt, upload-failover.txt
3: restart с volumes сохраняет метаданные и оригинал make test-persistence ACTION_SCRIPT=scripts/restart.sh PASS; те же ID контейнеров db/s3/valkey/api/lb с новым StartedAt, volumes на месте persistence.txt
4: тесты большого файла, повреждения, подмены MIME, чужого id, вложения другого чата; нет 500 attachment_edge_cases.py обрезка/CRC/мусор в zlib при верном CRC/без IEND → 415; PNG как JPEG, JPEG как PNG, text/plain, multipart → 415; вложение чужого и своего другого чата → 404; ни одного 500 attachment-edge-cases.txt
4: компенсация/сверка/очистка с grace student-tests/upload_compensation.py DB error после PUT → 503 + фоновая компенсация, intent не остался; crash после PUT → intent + объект, janitor до grace их не трогает, после grace удаляет оба; свежий intent и готовое вложение целы upload-compensation.txt
4: лимиты RAM, ≥10 одновременных загрузок student-tests/upload_memory.py --concurrency 12/20 12 × 9.5 MiB: прирост пика RSS 13–14 MiB на реплику (наивно 57 MiB данных на реплику) upload-memory-c12.json, upload-memory-c20.json
4: идемпотентный bootstrap, отдельные ограниченные credentials docker compose run --rm s3-init ×2, migrate keep bucket, все самопроверки PASS: API-ключ не создаёт/не удаляет bucket, не видит чужих; миграции SKIP bootstrap-idempotent.txt
4: админ-консоль закрыта, private bucket проверен вне API s3_failures.py из сети стенда порты 9333/8888/8080/19333/18888/23646 недоступны; S3 не опубликован на хосте; анонимные запросы → 403 s3-failures.txt
3/4: недоступность S3 s3_failures.py (docker stop s3) ready 200, сообщения 201, metadata 200; upload/download → 503 за 6.0–6.2 s; 415 остаётся 415; после старта S3 всё работает, старый файл цел s3-failures.txt

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

Память при одновременных загрузках (уровень 4)

Гипотеза: пик памяти API определяется конструкцией (spool ≤1 MiB/загрузку, потоковая проверка PNG, ≤8 слотов), а не числом × размером файлов. Методика: upload_memory.py перезапускает обе реплики (сброс состояния), N потоков стартуют одновременно (Barrier) и загружают валидный PNG из шума 9 962 537 байт (9.5 MiB, несжимаемый — худший случай для проверки IDAT); внутри каждой реплики и S3 каждые 100 мс читаются VmRSS процесса и anon cgroup. VmHWM не подходит: пик импорта библиотек при старте (~170 MiB) выше пика загрузок. Лимиты: API 0.5 CPU / 256 MiB, S3 1 CPU / 1 GiB.

N (на реплику) Статусы Wall, s p50 / max, s Пик RSS API − базовый (≈105 MiB) Наивная оценка «всё в RAM» на реплику Пик RSS SeaweedFS
12 (6+6) 12 × 201 5.2 5.0 / 5.2 +12.9 / +13.7 MiB 57 MiB 546 MiB
20 (10+10, > 8 слотов) 20 × 201 9.9 8.6 / 9.9 +16.5 / +17.7 MiB 95 MiB 779 MiB

Гипотеза для API подтверждена: прирост ~2 MiB на одновременную загрузку и почти не растёт сверх 8 слотов (лишние ждут слот; в одном из повторов при N=20 двое получили 429 после 10 s ожидания — ожидаемый backpressure). SHA-256 проверен.

Побочная находка: узким местом оказался S3-сервер. С исходным лимитом 512 MiB SeaweedFS при 12 параллельных PUT дошёл до 519 MiB и был убит (контейнер перезапущен, все загрузки — 503). Исправлено: лимит 1 GiB и GOMEMLIMIT=600MiB (мягкий лимит Go GC); после нагрузки RSS возвращается к ~210 MiB. Это одно измерение на одном ноутбуке, а не ёмкость SeaweedFS вообще.

Компенсация отказа между S3 и БД (уровень 4)

Найденный дефект (до исправления). Сверка содержимого bucket со строками БД на «грязном» стенде нашла 12 объектов без строки и без intent — то, что запрещено инвариантом. Причина: при истёкшем дедлайне PUT компенсация удаляла объект и intent, а SeaweedFS дописывал PUT после DELETE. Второй риск того же рода: при неоднозначном COMMIT немедленное удаление объекта оставило бы строку без байтов. Исправлено (см. таблицу отказов выше); 12 лишних объектов удалены. upload_compensation.py после исправления проверяет компенсацию при ошибке БД и очистку janitor-ом после падения процесса.

Отказы

Воздействие Что ожидаем Что наблюдали Время восстановления / потеря данных
docker stop обслужившей API-реплики (×2 + для каждой реплики) запись и download через другую 0 ошибок записи; файл скачан по SHA-256 через оставшуюся первая успешная запись через 4.0–4.2 s; потерь нет
Restart lb + api + db + valkey + s3 с volumes данные, сессия и оригинал сохранены PASS с прежним токеном hook и ожидание готовности уложились в лимиты теста (90 + 90 s), длительность отдельно не замерялась; потерь нет
docker stop s3 только вложения → 503, остальное работает ready 200, message 201, metadata 200, upload/download 503 за ~6 s сразу после старта S3; потерь нет, intents неудачных PUT убирает janitor
Падение процесса после PUT до COMMIT клиент без 201, orphan не вечный intent + объект → удалены janitor после grace grace (900 s; 20 s в тесте)
Потеря БД после PUT 503, без мусора 503; фоновая компенсация удалила объект и intent ~0.1 s
12 параллельных PUT по 10 MiB при лимите S3 512 MiB — SeaweedFS убит по памяти, все 503 исправлено лимитом 1 GiB + GOMEMLIMIT
Оборванная клиентом загрузка реплика продолжает работу следующая загрузка 201; по коду PUT начинается только после приёма всего тела, поэтому объекта нет (отдельно не измерялось) —

Ограничения и следующие шаги

  • Один Docker host, один PostgreSQL, один SeaweedFS без репликации, один LB: выдерживается отказ одной API-реплики и перезапуск хранилищ с volumes, но не потеря host/диска/S3-тома. Резервного копирования нет.
  • Нет отдельного reconciler: объект без строки и без intent (ручное вмешательство, баг) автоматически не удаляется; потеря байтов готового вложения видна только по 500 и ERROR в логе при download.
  • Прогрессивные JPEG > 16 Мпикс проверяются только по структуре маркеров (полное декодирование держало бы все DCT-коэффициенты в памяти); такие повреждения внутри энтропийного потока не ловятся.
  • MAX_CONCURRENT_UPLOADS — на реплику, не глобально; общий предел S3 задаётся числом реплик × 8. Ёмкость SeaweedFS при большем числе реплик не измерялась.
  • Измерения памяти — по одному-два прогона на ноутбуке; при N=12 в разных прогонах прирост был от 3.6 до 13.7 MiB на реплику, абсолютные числа зависят от аллокатора и версии Python.