Files
mtusi2026lab4/REPORT.md
T
2026-11-12 19:00:07 +03:00

25 KiB
Raw Blame History

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

  • Автор, группа: Запорожец Михаил, БВТ2304
  • Целевая оценка: 3 (трек 5 не заявлен)
  • Commit/PR: #115 (ветка solution/bvt2304-zaporozhets, коммит 2dca5c1)
  • Использованные источники, библиотеки и помощь ИИ: документация AWS S3 (object uploads, bucket policy), RustFS (docs.rustfs.com, переменные RUSTFS_*), спецификация PNG (IHDR, IDAT, Adam7), Pillow (lazy open, verify, draft, MAX_IMAGE_PIXELS), Docker Compose (secrets, healthcheck, service_completed_successfully). Библиотеки: FastAPI 0.115, uvicorn 0.34, asyncpg 0.30, argon2-cffi 23.1, redis-py 5.2, minio-py 7.2.18 (S3-клиент), Pillow 11.3.0. Код, конфигурации и тесты написаны с помощью ИИ-ассистента (Claude); решения разобраны и проверены автором.

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

Нужно: Docker Engine/Desktop с Compose v2.20+ (проверено: Docker 29.8.2, Compose 5.6.0, Windows 11 + Docker Desktop, WSL2) и POSIX-shell (Linux/macOS или Git Bash). Python и make на хосте не нужны: проверки запускаются в сервисе tester.

Роль Сервис Образ Health/readiness Volume Сеть / порт Credentials
Балансировщик lb haproxy:3.2.8-alpine wget /stats; сам проверяет API по /health/ready — edge; единственная публикация 127.0.0.1:8080 (+ 127.0.0.1:8404 статистика) не нужны
API × N api (deploy.replicas: ${API_REPLICAS:-2}) сборка Dockerfile (python:3.12.12-slim-bookworm) HEALTHCHECK /health/ready нет; root fs read-only, /tmp tmpfs edge + data; порты не публикуются secrets database_url, cache_url, s3_access_key_id, s3_secret_access_key
Миграции migrate (one-shot) тот же образ exit 0 — data secret database_url
S3 s3 rustfs/rustfs:1.0.4@sha256:ed9210d6…dcc2 curl /health s3data data (internal); порты не публикуются, веб-консоль выключена RUSTFS_ACCESS_KEY_FILE, RUSTFS_SECRET_KEY_FILE
Bootstrap bucket s3-init (one-shot) образ API, python -m app.s3_bootstrap exit 0 — data S3 secrets
PostgreSQL postgres postgres:17.7-bookworm pg_isready pgdata data (internal) POSTGRES_PASSWORD_FILE
Кэш сессий valkey valkey/valkey:8.1.4 valkey-cli ping нет (кэш) data (internal) requirepass в secret valkey_conf
API с TTL=2 с api-ttl (profile test) образ API как у api — edge + data как у api
Тестовый стенд tester (profile tools) python:3.12.12-alpine3.22 + make + curl + docker-cli — bind . edge docker.sock
git clone <repo> && cd <repo>
sh scripts/init-secrets.sh                 # ./secrets/* (пароль БД, Valkey, ключи S3) и .env из .env.example; значения не печатает
docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build --wait
#   postgres, s3, valkey -> migrate (схема) -> s3-init (bucket) -> api x2 (healthy) -> lb

# Публичные проверки (Linux-контейнер tester; на Linux-хосте можно просто `make ...`)
docker compose --env-file .env --profile tools run --rm tester make check
docker compose --env-file .env --profile tools run --rm tester make test
docker compose --env-file .env --profile tools run --rm tester make test-failover ACTION_SCRIPT=scripts/stop-one.sh
docker compose --env-file .env --profile tools run --rm tester sh scripts/restore.sh       # вернуть реплику
docker compose --env-file .env --profile tools run --rm tester make test-persistence ACTION_SCRIPT=scripts/restart.sh

sh scripts/test-lab4.sh            # собственные тесты lab4 + регрессия lab3 и lab2
sh scripts/collect-evidence.sh     # все доказательства evidence/*.txt одной командой
  • Bootstrap БД: python -m app.migrate (сервис migrate) применяет migrations/NNNN_*.sql по порядку под pg_advisory_lock. Новая миграция lab4 — 0004_attachments.sql, она только добавляет объекты (expand).
  • Bootstrap S3: python -m app.s3_bootstrap (сервис s3-init). Создаёт bucket messenger-attachments, если его нет. Если у bucket есть политика анонимного доступа, удаляет её. Затем кладёт служебный объект и делает анонимный GET в обход API: ожидается 403, иначе bootstrap падает и API не стартует. Повторный запуск безопасен: печатает exists и данные не трогает (evidence/stand.txt).
  • Действий оператора, кроме init-secrets.sh, не требуется. Если на 8080 работает стенд lab3, его нужно остановить (docker compose -p mtusi-lab3 stop) или задать LB_PUBLISHED_PORT в .env.
  • Безопасная остановка (данные сохраняются): docker compose --env-file .env stop или ... down.
  • Намеренное удаление учебных данных: docker compose --env-file .env down -v (удаляет volumes mtusi-lab4_pgdata и mtusi-lab4_s3data); секреты — каталог secrets/.

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

клиент ──HTTP──> lb: HAProxy 3.2 (127.0.0.1:8080)                       сеть edge
                  │ roundrobin, без sticky, /health/ready раз в 1 с
          ┌───────┴────────┐
          ▼                ▼
        api-1  ...       api-N      (FastAPI/uvicorn, stateless, read-only FS)
          │                │                                             сеть data (internal)
   ┌──────┼────────────────┼──────────┐
   ▼      ▼                ▼          ▼
postgres (pgdata)    s3: RustFS (s3data)    valkey (кэш сессий)
users, chats,        приватный bucket
messages, sessions,  messenger-attachments/
attachments (мета),    attachments/<uuid>  ← байты оригиналов
message_attachments

Что перенесено из lab3 без изменений: HAProxy (DNS-обнаружение реплик, проверка готовности, повтор только безопасных запросов), drain по SIGTERM, X-Instance-Id, обязательный Idempotency-Key, Argon2id, Bearer-сессии в PostgreSQL с кэшем в Valkey, однократные миграции, hook-скрипты stop-one.sh/restore.sh. Тесты lab3 и lab2 оставлены как регрессия.

Что добавлено в lab4:

Где Что
migrations/0004_attachments.sql Таблица attachments: id, chat_id, owner_id, filename, content_type, size_bytes, sha256, width, height, object_key, status, created_at, updated_at. Таблица message_attachments (message_id, attachment_id, chat_id, position). Ограничение text ослаблено до 0..4000: сообщение может состоять только из вложений.
app/storage.py S3-клиент (minio-py → RustFS по S3 API): put/get/delete с дедлайном на операцию и компенсирующее удаление.
app/images.py Ограниченное чтение тела и проверка PNG/JPEG по содержимому.
app/s3_bootstrap.py Идемпотентное создание приватного bucket и проверка анонимного доступа.
app/main.py POST /chats/{id}/attachments, GET /attachments/{id}, GET /attachments/{id}/content; attachment_ids в сообщениях.

Источник истины. Метаданные вложения и связь с чатом и сообщением хранятся в PostgreSQL. Байты оригинала лежат только в S3: ни в БД, ни на диске API их нет. Вложение заранее привязано к чату: attachments.chat_id задаётся при загрузке, а к сообщению файл привязывается позже, через attachment_ids. Составные FK (attachment_id, chat_id) и (message_id, chat_id) не дают даже на уровне БД прикрепить файл другого чата.

Object key назначает сервер: attachments/<случайный UUID>. Имя файла клиента в ключе не участвует и хранится только для отображения. В ответах API ключа, адреса S3 и credentials нет.

Порядок загрузки и когда честно вернуть 201:

  1. Аутентификация, затем проверка членства в чате. Посторонний получает 404 до чтения тела, то есть не может залить в чужой чат ни байта.
  2. Проверка filename (400) и Content-Type (только image/png или image/jpeg, иначе 415).
  3. Чтение тела с лимитом. Если Content-Length больше 10 MiB — сразу 413. Тело читается потоком с обрывом на 10 485 761-м байте, так что и chunked без длины ограничен.
  4. Проверка содержимого: сигнатура должна совпасть с Content-Type, иначе 415. Размеры читаются из заголовка; если ширина × высота больше 40 млн, ответ 413 до распаковки пикселей. Только после этого идёт проверка целостности: у PNG — CRC чанков и потоковая распаковка IDAT со сверкой объёма с IHDR (пиксели не хранятся), у JPEG — декодирование в режиме draft 1/8. Повреждённый файл получает 415.
  5. PUT в S3. Сбой даёт 503, метаданных при этом нет.
  6. INSERT метаданных в PostgreSQL. Если он не прошёл (БД недоступна, клиент оборвал соединение), API удаляет только что записанный объект: это компенсация.
  7. 201 status=ready отдаётся только после COMMIT. К этому моменту и байты, и запись уже надёжно сохранены.

Если S3 PUT прошёл, а COMMIT в PostgreSQL — нет, срабатывает компенсация из шага 6: объект удаляется, клиент получает 503 и может повторить загрузку. Если упадёт и сама компенсация (S3 тоже недоступен) или процесс API убьют между шагами 5 и 6, в bucket останется неучтённый объект. На метаданные и доступ он не влияет, но место занимает. Автоматическая сверка и очистка таких объектов с grace period — это критерий уровня 4, здесь она не реализована (см. «Ограничения»). Обратная ситуация невозможна: запись в БД без объекта не появится, потому что INSERT выполняется только после успешного PUT.

Скачивание проходит через API: сначала аутентификация, потом проверка членства в чате вложения, затем чтение из S3. Байты отдаются с истинным Content-Type и без redirect. Посторонний получает 404 одинаково на метаданные и на content. Ответ несёт заголовки Cache-Control: private, no-store, X-Content-Type-Options: nosniff и ETag = sha256.

Почему приватный bucket и случайный ключ не заменяют ACL приложения. Ключ попадает в логи, URL и историю браузера, его можно переслать. Кроме того, «случайный» не значит «секретный навсегда»: участника могут исключить из чата, а ключ останется прежним. Приватный bucket защищает только от анонимного доступа к S3, а знает, кто участник чата, одно приложение. Поэтому проверка выполняется на каждый запрос к API.

Почему файл в Docker volume одной реплики — не объектное хранилище. Volume привязан к конкретному контейнеру и хосту. Файл, загруженный через api-1, не виден api-2: после остановки api-1 download через другую реплику вернул бы 404 или 500. Именно это проверяет test_failover_of_uploading_replica. У API в этом решении корневая ФС read-only, а /tmp — tmpfs, так что локальной копии нет физически (test_no_local_copy_on_api).

Готовность (/health/ready). Критична только PostgreSQL, как и в lab3. Недоступность S3 не выводит реплики из балансировки: текст, история и метаданные вложений продолжают работать, а upload и download честно отвечают 503 за ограниченное время. Если бы S3 входил в readiness, его сбой выключил бы весь мессенджер, включая текстовые сообщения.

Таймауты S3. Подключение — 2 с, чтение — S3_TIMEOUT_MS (5 с), повторов на уровне HTTP-клиента нет. Дополнительно стоит общий дедлайн операции (asyncio.wait_for): DNS-резолв остановленного контейнера во внутренней сети Docker занимал около 8 с и не ограничивался таймаутами urllib3. Дедлайн (5 с) меньше timeout server HAProxy (15 с), поэтому клиент получает 503 от API, а не 504 от LB.

Память. Тело загрузки держится в памяти целиком (до 10 MiB). Проверку изображений одновременно выполняют не больше IMAGE_CHECK_WORKERS=2 на реплику. PNG не декодируется в пиксели, JPEG декодируется в масштабе 1/8. Лимит контейнера API — 384 MiB. Эксперимент с ≥10 одновременными загрузками и замером пика RAM относится к уровню 4 и не проводился.

S3-сервер: RustFS, а не MinIO. Образы MinIO на момент выполнения удалены из публичных реестров (Docker Hub: «repository does not exist», quay.io: 401). RustFS 1.0.4 (релиз 25.10.2026) закреплён по тегу и digest и совместим по S3 API, поэтому клиент — стандартный minio-py. Веб-консоль RustFS по умолчанию выключена (RUSTFS_CONSOLE_ENABLE не задан), порты S3 на хост не публикуются, сеть data помечена internal.

Соответствие .env.example реальной конфигурации:

Переменная Где используется
S3_ENDPOINT, S3_REGION, S3_BUCKET app/config.py → app/storage.py, app/s3_bootstrap.py; RUSTFS_REGION у сервиса s3
S3_ACCESS_KEY_ID_FILE, S3_SECRET_ACCESS_KEY_FILE compose secrets s3_access_key_id, s3_secret_access_key (создаёт init-secrets.sh); те же файлы — root credentials RustFS
MAX_UPLOAD_BYTES, MAX_IMAGE_PIXELS app/config.py, значения можно только уменьшить относительно контракта
S3_TIMEOUT_MS, IMAGE_CHECK_WORKERS добавлены решением: дедлайн S3-операции и число параллельных проверок изображений
остальные без изменений с lab3

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

Все файлы получены одной командой sh scripts/collect-evidence.sh на запущенном стенде 12.11.2026.

Критерий README Команда/сценарий Наблюдаемый результат Файл доказательства
Публичный smoke make check, make validate, make test PASS: lab4 public API scenario (upload 201 ready, attachment_ids, download вторым участником = оригинал, 404 постороннему) evidence/public-tests.txt
Возможности lab3 сохранены make test-failover ×2, регрессия test_lab3.py, test_lab2_regression.py обе реплики остановлены по очереди, failed_attempts: 0; 8/8 и 10/10 evidence/failover-hook.txt, evidence/student-tests.txt
S3 в общем стенде, приватный bucket compose ps, логи s3-init, повторный запуск s3-init rustfs:1.0.4@sha256 healthy, volume s3data; анонимный GET → HTTP 403; повтор: exists evidence/stand.txt
Метаданные в PostgreSQL, байты в S3, не в БД и не на API test_no_local_copy_on_api, test_bucket_private_outside_api rootfs API read-only, нет volume и записываемых bind, /tmp пуст; в attachments только метаданные и object_key evidence/student-tests.txt, migrations/0004_attachments.sql
201 ready, побайтный download, SHA-256 test_png_and_jpeg_roundtrip PNG и JPEG: status=ready, variants=[]; bytes и sha256 совпадают; Content-Type истинный evidence/student-tests.txt
Message с attachment_ids читается участниками test_message_with_attachments text="" + 2 вложения, порядок сохранён, идемпотентный повтор равен оригиналу, история возвращает attachment_ids там же
Посторонний не имеет доступа smoke, test_png_and_jpeg_roundtrip, test_foreign_attachment_rejected 404 на метаданные и content, 401 без токена; upload в чужой чат → 404; вложение другого чата в сообщении → 404, сообщение не создано там же
Лимиты ≤10 MiB / ≤40 Мпикс до чтения/декодирования test_limits_and_mime 10 MiB + 1 → 413; PNG-заголовок 10000×5000 (~100 байт) → 413 без декодирования; 6000×6000 без пикселей → 415 там же
MIME по содержимому test_limits_and_mime PNG как image/jpeg и JPEG как image/png → 415; GIF, обрезанные PNG/JPEG, пустое тело, text/plain, multipart → 415 там же
Опасные filename test_dangerous_filenames ../etc/passwd, a/b.png, a\b.png, NUL, \t, \n, DEL, пустое, .., 256 символов → 400; Unicode-имя и 255 символов принимаются там же
Upload → стоп обслужившей реплики → download через другую test_failover_of_uploading_replica uploaded via 406b73449330-…, downloaded via 9f9f380ebef7-…, байты совпадают там же
Restart с volumes сохраняет метаданные и оригинал make test-persistence ACTION_SCRIPT=scripts/restart.sh PASS (тест lab4 повторно читает метаданные и скачивает оригинал прежним токеном); StartedAt всех процессов (lb, api×2, postgres, s3, valkey) сменился evidence/persistence.txt
Недоступность S3 test_s3_unavailable docker stop s3: upload и download → 503 (не 500, не 504), текст → 201, метаданные → 200, /health/ready → 200; после docker start тот же файл скачивается evidence/student-tests.txt

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

Стенд: Windows 11, Docker Desktop (WSL2) — VM 8 CPU / 4 GiB. Лимиты: API 1 CPU / 384 MiB на реплику, RustFS 1 CPU / 512 MiB, PostgreSQL 2 CPU / 768 MiB. Fixture: tests/fixtures/sample.png (111 817 байт) и синтетический student-tests/fixtures/sample.jpg 160×100 (1 992 байта).

Воздействие Что ожидаем Что наблюдали Время восстановления / потеря данных
docker stop реплики, загрузившей файл download через другую реплику тот же файл, другой X-Instance-Id сразу (LB исключил реплику по drain); потерь нет
make test-failover для каждой реплики 0 потерянных подтверждённых записей 125 успешных записей, failed_attempts: 0, вложение скачано после отказа первая запись после отказа через 4,2–4,7 с; потерь нет
docker stop s3 503 на файлы, остальное работает upload/download 503 за ≤5 с каждый; текст 201; ready 200 после docker start s3 файл снова скачивается (≤60 с ожидания в тесте); потерь нет
scripts/restart.sh (lb, api, postgres, s3, valkey) данные, сессия и файл сохраняются PASS, StartedAt всех 6 процессов новые весь hook с повторным migrate/s3-init — около 45 с; потерь нет

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

  • Нет сверки и очистки неучтённых объектов (уровень 4). Компенсация на месте срабатывает при ошибке INSERT, но объект останется, если процесс API убьют между PUT и COMMIT, если не удастся сама компенсация или если PUT завершится в фоне уже после того, как дедлайн вернул клиенту 503. Следующий шаг — фоновый reconciler: обходит bucket, сравнивает ключи с attachments.object_key и удаляет объекты без метаданных старше grace period, например 24 часов.
  • API работает с root credentials RustFS. Отдельный пользователь S3 с правами только на bucket (уровень 4) не настроен.
  • Тело загрузки целиком в памяти (до 10 MiB на запрос); потоковой передачи в S3 и замера пика RAM при ≥10 параллельных загрузках нет (уровень 4).
  • RustFS в single-node режиме без избыточности (storage_class has no parity в логе): отказ диска означает потерю файлов. Для учебного стенда это допустимо, в production нужен distributed-режим или реплицированное хранилище.
  • Неучтённые объекты от отменённых PUT возможны из-за дедлайна: поток, который нельзя прервать, может дописать объект уже после ответа 503. Это ещё одна причина, по которой нужен reconciler.
  • Подтверждено: все обязательные сценарии уровня 3 и регрессия lab3/lab2 (evidence/). Остальные пункты уровней 4 и 5 не заявлены.