Files
2026-11-06 20:05:11 +03:00

30 KiB
Raw Permalink Blame History

Лабораторная 4 — S3-хранилище и вложения

Автор: Савин Александр, БВТ2303. Целевая оценка: 5, трек 2 — согласованность двух хранилищ.

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

Нужны Docker Engine/Compose v2 и Python 3.9+ для внешних тестов; для перестроения графиков — Python 3.10+ (локально 3.13). Сборка использует Python 3.11.11. Скрипт compose.sh поддерживает docker compose и docker-compose.

cd mtusi2026lab4
./scripts/bootstrap.sh
./scripts/compose.sh config --quiet
./scripts/compose.sh up -d --build
python3 scripts/wait_ready.py --base-url http://localhost:8084
export BASE_URL=http://localhost:8084
make check
make test
make test-idempotency
make test-cache
make test-uploads
make test-private
make test-attachment-failover
./scripts/compose.sh start api
python3 scripts/wait_ready.py --base-url "$BASE_URL"
make test-failover ACTION_SCRIPT=scripts/stop-one.sh
./scripts/compose.sh start api
python3 scripts/wait_ready.py --base-url "$BASE_URL"
make test-persistence ACTION_SCRIPT=scripts/restart.sh
make test-dependencies
make research-consistency
make research-memory

Все зависимости запускаются этим проектом. .env создаётся один раз с тремя разными случайными паролями и правами 600; существующий файл не перезаписывается. APP_PORT по умолчанию 8084. Хранилища/volumes предыдущих лабораторных не подключаются. API_REPLICAS, API_CPUS и API_IMAGE управляют числом, CPU и образом API; остальные обязательные значения описаны в compose.yaml/.env.example. Секреты исключены из Git и Docker build context. Credentials в environment доступны оператору Docker — учебное упрощение.

Остановка без потери данных: ./scripts/compose.sh down; возврат: ./scripts/compose.sh up -d. Намеренное удаление всех учебных данных lab4: ./scripts/compose.sh down -v; для проверок команда не нужна.

python3 -m venv .venv
.venv/bin/python -m pip install -r requirements-dev.txt -r requirements-research.txt
make validate PYTHON=.venv/bin/python
.venv/bin/python scripts/plot_research.py

Компоненты и версии

Клиент → HAProxy → API ×2 → PostgreSQL (метаданные) и приватный MinIO (оригиналы). Valkey остаётся общим кэшем сессий. Мигратор и S3 bootstrap запускаются отдельно; reconciler автоматически сверяет хранилища. ops — профиль инструментов для тестов/ручной сверки, обычный запуск его не поднимает.

Компонент Проверенная версия/ограничение
API Python 3.11.11-slim, FastAPI 0.115.0, Uvicorn 0.30.6; 2 CPU/512 MiB на реплику
PostgreSQL 16.6-alpine; 1 CPU/512 MiB
Valkey 8.0.2-alpine, AOF; 0.25 CPU/128 MiB
HAProxy 3.0.5-alpine; 0.25 CPU/64 MiB
MinIO RELEASE.2025-09-07T16-13-09Z, digest закреплён в Compose; 0.5 CPU/768 MiB
MinIO mc RELEASE.2025-08-13T08-35-41Z, digest закреплён; bootstrap 1 CPU/512 MiB, затем завершается
Reconciler Тот же образ приложения; 0.25 CPU/256 MiB
Инструменты ops 1 CPU/512 MiB, запускаются явно
SDK/декодер boto3 1.42.0, Pillow 13.0.0

Проверено на macOS/Colima, Linux arm64, Docker 27.4.0, VM 4 vCPU и около 8 GB RAM. Квоты — пределы, не резервирование: сумма возможных CPU-квот больше 4 vCPU. Все образы закреплены тегом или digest; проверена arm64-среда. Фактические процессы, image IDs, лимиты, порты и volumes — evidence/final-containers.json.

Что перенесено из lab3

Две взаимозаменяемые API за HAProxy, Docker DNS discovery, round robin, общие сессии PostgreSQL/Valkey, Argon2id, проверка прав, keyset-пагинация, X-Request-Id/X-Instance-Id, транзакционная идемпотентность сообщений и отдельный согласованный мигратор. SQL-пул каждой API ограничен пятью соединениями.

Новые текстовые сообщения остаются валидны и получают attachment_ids=[]. Миграция 003 переводит сохранённые lab3 request bodies в JSONB и добавляет [] к сохранённым ответам, чтобы сохранить replay при таком обновлении. В этом стенде используется отдельная новая БД lab4.

Идемпотентность теперь сравнивает текст и упорядоченный список attachment_ids. Порядок JSON-полей несущественен, отсутствующий список равен []. Те же ключ/тело дают прежнее сообщение и 201; другой body — 409. Ключ действует в области пользователя/чата/POST, срок результата — 24 часа. Вложения проверяются в транзакции, их принадлежность чату обязательна. Один и тот же файл чата может прикреплять другой участник, не только загрузивший пользователь.

Метаданные, загрузка и download

attachments хранит UUID, чат, владельца, отображаемое filename, внутренний object_key, тип, размер, SHA-256 и состояние. message_attachments хранит связь и порядок вложений. Бинарного поля в PostgreSQL нет. Имя объекта назначается сервером: originals/. Filename не участвует в пути.

Порядок upload:

  1. Bearer-аутентификация и проверка членства в чате.
  2. Проверка filename (1–255 символов, без разделителей и управляющих символов) и допустимого Content-Type.
  3. Отклонение слишком большого Content-Length до чтения тела. Затем потоковое чтение с повторной проверкой суммарных bytes, в том числе при chunked transfer.
  4. SHA-256 рассчитывается по поступающим байтам. SpooledTemporaryFile держит до 256 KiB в RAM, дальше использует временный файл. Исходник не становится обязательным локальным хранилищем API: spool закрывается/удаляется после операции, ошибки, disconnect или завершения процесса.
  5. Pillow открывает только PNG/JPEG, проверяет фактический формат, размеры до полного decode, затем verify и полный load. Лимиты — 10 MiB и 40 млн пикселей; обрезанные JPEG тоже отклоняются.
  6. Создание устойчивого pending-намерения в PostgreSQL, S3 PUT и перевод записи в ready. 201 возвращается после успешной фиксации ready, когда обе части сохранены.

Размер и пиксели ограничены константами обязательного контракта. Multipart/form-data не используется. Превышение limits — 413; испорченное/чужое содержимое или подмена MIME — 415; неверные поля — 400; чужой/неизвестный объект — 404. Ошибки SDK не раскрывают credentials и превращаются в 503.

GET /attachments/{id} и /content сначала проверяют сессию и членство в чате. Download идёт через API без redirect и отдаёт исходные байты порциями 64 KiB с настоящим Content-Type. В ответах отсутствуют object key, адрес MinIO и секреты. Только ready выдаётся как Attachment обязательной схемы с variants=[] и error_code=null. Для внутреннего pending/failed доступ участнику возвращает 409; чужой пользователь по-прежнему получает 404. При исчезновении объекта download сначала возвращает 503, после обнаружения reconciler — 409. Ссылка в подтверждённом сообщении сохраняется.

Ограничение ресурсов и timeouts

На процесс допускаются две активные upload-операции; остальные ждут свободный слот до 30 секунд с ASGI-backpressure. При чтении тела — idle timeout 5 секунд и общий бюджет 30 секунд. Декодирование ограничено одним изображением на процесс. Блокирующие file/Pillow/S3-операции вынесены в thread pool. Uvicorn limit-concurrency=64 ограничивает общее число соединений/задач; при перегрузке возможна 503 самого сервера.

S3 SDK: connect timeout=1s, read timeout=3s, одна попытка без скрытого повторного PUT. Применяется single PUT, multipart-upload-сессии не создаются. Ресурс декодирования ограничен bytes/pixels и семафором; отдельного принудительного wall-clock timeout нативного Pillow decode нет.

API readiness требует PostgreSQL и MinIO; Valkey остаётся необязательным. HAProxy проверяет readiness каждую секунду, fall=2/rise=1/check timeout=1s; connect=1s, client/server inactivity timeout=45s. Docker healthcheck имеет процессный бюджет 4s. Uvicorn graceful shutdown=35s, Compose stop_grace_period=40s. Явный stop-one hook намеренно использует лишь 3s, проверяя и возможность обрыва запросов. SIGTERM reconciler завершает ожидание и закрывает соединения; при слишком долгом проходе возможен внешний SIGKILL, повтор остаётся безопасным.

Приватность MinIO и bootstrap

MinIO и его консоль не публикуют порты на хост. Консоль привязана к loopback внутри S3-контейнера, browser UI выключен. API знает отдельного пользователя lab4api; root credentials есть только у MinIO и bootstrap, в API их нет.

S3-init создаёт bucket messenger-attachments, убирает anonymous policy и создаёт/обновляет пользователя и политику. Повтор bootstrap не удаляет объекты. Разрешены ListBucket только этого bucket, Get/Put/DeleteObject только originals/*. У API нет прав создавать bucket, читать его политику или писать за пределами префикса. MinIO разрешает filtered ListBuckets с именем разрешённого bucket; это наблюдение отдельно записано, отказ в этой конкретной операции не заявляется.

Реальная внешняя для API проверка выполняется из ops-контейнера непосредственно к MinIO: анонимные list/get возвращают 403; административные операции API-пользователя запрещены; console port недоступен. Политика — infra/api-policy.json, результаты — evidence/private-storage.json.

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

Распределённой транзакции между PostgreSQL и S3 нет. Вместо немедленного удаления объекта при любой ошибке COMMIT используется устойчивое намерение и повторяемая сверка. Это важно: при потере ответа COMMIT мог реально пройти, поэтому слепая компенсация могла бы удалить уже готовый объект.

Перед PUT сохраняется pending со случайным UUID, ключом, размером и checksum. На время PUT/ready COMMIT берётся PostgreSQL advisory lock области object_key. Reconciler использует тот же lock и повторно читает обе стороны под ним. После успешного COMMIT запись ready больше автоматически не удаляется.

Расхождение Безопасное действие
Объект есть, записи нет (orphan) После grace и повторной проверки удалить объект, если нет использования
Старый pending, PUT не было или процесс умер после PUT Удалить оставшийся объект, если он есть, отметить incomplete_upload; сохранить запись
Ready-метаданные есть, объект отсутствует Отметить missing_object; сохранить UUID, метаданные и связи сообщений
Не совпадают размер/sha256 metadata в HEAD Отметить corrupt_object, сохранить данные для диагностики
Missing/corrupt объект восстановлен и HEAD снова соответствует записи Вернуть ready; не генерировать новый UUID и не менять сообщения
Свежий объект/запись, используемый готовый объект, занятый lock Не удалять
Ошибка БД, S3 403/5xx/timeout Прервать проход; не трактовать как отсутствие

Штатный grace=300s, проверяется возраст и объекта, и pending-записи. Обычный CLI запрещает grace меньше 60s. Автопроцесс выполняет apply, затем ждёт 60s до следующего прохода. Одновременные запуски сериализуются отдельным lock. Инвентарь S3 и метаданные читаются страницами по 200; JSON содержит максимум 1000 подробных действий и счётчики остальных, чтобы отчёт тоже не рос без ограничения RAM.

make reconcile        # dry-run по умолчанию
make reconcile-apply  # те же правила с реальным исправлением

В исследовании только на изолированных синтетических данных grace=5s разрешён явным флагом; это не настройка штатного worker. Само восстановление утраченных bytes требует сохранившегося оригинала/backup. Reconciler обнаруживает и корректно обозначает потерю, но не создаёт исходное изображение из хэша. Проверка HEAD не является полным повторным SHA-аудитом всех байтов: размер и серверные sha256 metadata сравниваются с БД.

Доказательства уровней 3 и 4

Критерий Проверка Файл
Контракт и схема make check; make validate evidence/check.txt, validate.txt
Обязательный lab4 API make test evidence/smoke.txt
Сессии/идемпотентность lab3 make test-idempotency; make test-cache evidence/idempotency.txt, cache-consistency.txt
Форматы, limits, filename, ACL, чужой чат/attachment, прерывание make test-uploads, 21 случая evidence/uploads-negative.json
Приватный bucket и ограниченные права make test-private evidence/private-storage.json
Установленная загрузившая API действительно остановлена make test-attachment-failover evidence/attachment-failover.json
Публичный failover и исходный файл make test-failover ACTION_SCRIPT=scripts/stop-one.sh evidence/failover.txt, after-public-failover.json
Полный restart с прежним токеном и файлом make test-persistence ACTION_SCRIPT=scripts/restart.sh evidence/persistence.txt, before-persistence.json, after-persistence.json
Реальная недоступность MinIO и PostgreSQL make test-dependencies evidence/dependency-outages.json, dependency-outages-compose.txt
≥10 одновременных uploads и peak RAM make research-memory evidence/upload-memory.json, upload-memory.png
Компенсация и безопасный grace make research-consistency evidence/reconciliation.json
Повторяемый bootstrap и отсутствие публичной консоли s3-init + test-private infra/init-s3.sh, evidence/private-storage.json

В outage-тесте диагностические запросы идут внутри Compose к api:8080: это позволяет проверить структурированные ошибки приложения, когда HAProxy уже исключил обе API из-за недоступного S3/БД. Обычный маршрут всех успешных пользовательских сценариев — LB.

Все таблицы результатов и оба графика включены ниже в этот отчёт; полная методика уровня 5 — в RESEARCH.md. Проверки изменяют только синтетические данные отдельного проекта lab4. Токены/подписанные URL/пароли в evidence не сохраняются.

Фактические результаты

  • Публичный smoke, 16 конкурентных повторов сообщений и регрессии идентичности кэша — PASS.
  • Негативный suite: 21 проверка — PASS. Приватный S3 GET/List: 403, опасные операции API principal запрещены, console недоступна.
  • Остановка загрузившей API: uploader e2b4291a5ae6, скачавшая реплика f73f3d296d3e; восстановление download+write 2.159s, неудачных попыток 3. Bytes и SHA-256 совпали, настоящий uploader оставался остановленным до отдельного восстановления.
  • Публичный failover: 111 успешных записей, 3 неудачные попытки, восстановление 1.846s. Подтверждённые сообщения, прежняя сессия и оригинал сохранены.
  • Persistence — PASS. Реально перезапущены семь процессов API×2/DB/Valkey/MinIO/LB/reconciler; ID и volumes сохранились, StartedAt изменился.
  • Десять одновременных uploads, 40 запросов двух размеров: 0 ошибок. Измеренные пики API: около 91 MiB и 125–146 MiB при лимите 512 MiB.
  • Трек 2: real crash после PUT завершился с кодом 86; dry-run не изменил данные; apply исправил расхождения; повтор — 0 новых действий; fresh/used/locked объекты сохранены.

Таблицы и графики экспериментов

Числа и рисунки ниже получены из сохранённых JSON. Полная методика и исходные условия приведены в RESEARCH.md.

Обнаружение и исправление

Действие Количество в apply
abort_pending 2
corrupt_object 1
delete_orphan 1
missing_object 1

Реальный fault-процесс завершился с кодом 86 после PUT. Последующий apply нашёл его pending и удалил объект после grace. Для исчезнувшего/повреждённого используемого вложения сохраняются метаданные и связи сообщений; меняется доступность, а не история. После восстановления исходного объекта действие restore_ready снова разрешило скачивание с тем же UUID.

Проверка безопасности Результат
fresh_orphan_preserved True
fresh_ready_preserved True
used_ready_preserved True
active_lock_preserved True
missing_metadata_and_links_retained True
dry_run_no_mutation True
second_apply_actions 0

Повторный apply не предложил новых действий. Это относится к уже исправленному тестовому состоянию; при появлении новых объектов/ошибок следующий проход закономерно может выполнить новые действия. Ошибки зависимостей в отдельной проверке не изменили статусы. Реальные остановки MinIO/PostgreSQL дополнительно проверены в evidence/dependency-outages.json.

Стоимость обхода

К существующему фиксированному набору метаданных добавлялись 0, 50, 200 S3-объектов без метаданных. Это отдельные известные test-only ключи. Перед нулевой группой базовые timestamps выдерживаются за пределами тестового grace; после создания каждой следующей группы также выдерживается grace. Для каждого размера выполнено три dry-run, затем известные дополнительные ключи удалены. Порядок размеров возрастающий, кэш не сбрасывался.

Время измеряется time.monotonic внутри инструмента; запуск контейнера, подготовка fixtures и ожидание grace не входят в elapsed. Исходные отдельные результаты: reconciliation.json → scan_cost_runs. В таблице среднее/выборочное стандартное отклонение, не доверительный интервал.

Дополнительных orphan Объектов S3 Метаданных Время, мс: mean ± SD min–max, мс List / HEAD вызовов
0 65 65 160.59 ± 10.962 151.176–172.625 1 / 130
50 115 65 259.99 ± 62.361 219.672–331.819 1 / 180
200 265 65 579.413 ± 113.494 460.906–687.121 2 / 330

Стоимость обхода

При росте набора увеличиваются число point-checks и время. Список S3 и DB-метаданные читаются страницами по 200, подробный журнал ограничен 1000 действиями; остальные учитываются счётчиками. Алгоритм делает O(N+M) обход при N объектах и M подходящих метаданных, с индексированными DB point lookups. Полный SHA-аудит bytes сюда не входит: HEAD сравнивает размер и записанный uploader-ом sha256 metadata. Результат не доказывает предельную производительность хранилища или точную линейность на миллионах объектов.

Эксперимент уровня 4: память при параллельной загрузке

Десять клиентов одновременно стартуют по barrier, два раунда для каждого из двух размеров. Генератор находится внутри Compose-сети и идёт через LB. Каждая загрузка проверяет 201/ready, размер и SHA-256; один оригинал каждой фазы скачивается вторым участником и сравнивается побайтно.

Изображения — реальные синтетические RGB PNG, однотонные, сохранены без сжатия (compress_level=0), чтобы получить воспроизводимый большой файл. Это профиль передачи/памяти, а не worst-case для времени сложного JPEG/PNG-декодирования. Payload создаётся один раз на фазу и разделяется клиентскими потоками.

В каждом API cgroup memory.current читается раз в 50ms. Измерение включает page cache, kernel charges и небольшой Python sampler; это не RSS/heap-профиль. Пики — максимумы samples внутри фазы, не математическая гарантия отсутствия краткого пропущенного пика. В raw traces отдельно есть lifetime memory.peak, который включает более ранние операции. Лимит каждой API — 512 MiB, активных upload slots=2, decoder=1.

Файл, байт Размер, MiB Успешных загрузок Ошибок p50 / p95 / p99, мс Пики API 1 / API 2, MiB
787271 0.751 20 0 102.767 / 176.198 / 183.16 91.094 / 91.312
7081758 6.754 20 0 617.87 / 832.535 / 896.355 124.629 / 146.086

Параллельные загрузки и память

Все 40 запросов прошли, в каждой фазе наблюдались две настоящие API. Измеренные пики ниже лимита. Это подтверждает выбранный профиль ≥10 конкурентных загрузок, но не доказывает пик для всех изображений вплоть до 40 млн пикселей или для одновременных массовых логинов Argon2id.

Ограничения

Один Docker-host; MinIO, PostgreSQL и LB не реплицированы. Поддержан отказ процесса API и обычный restart с volumes, а не потеря диска/узла/backup. HTTP используется для локального синтетического стенда. Краткие ошибки при обнаружении отказа учитываются. Обрыв S3 в середине уже начатого streaming-download может оборвать HTTP-тело после отправки headers; клиент сверяет длину/хэш и повторяет безопасный GET.

Готовые, но ещё не прикреплённые вложения автоматически не удаляются: клиент может сослаться на них позже. Failed-записи и связи сохраняются для диагностики; tombstone retention отдельно не реализован. Изменять приватные объекты напрямую допускается только оператору; ключи приложения неизменяемы и не переиспользуются. Защита от произвольных злонамеренных изменений root/SQL-администратора и от несогласованного восстановления всей БД вне модели этой работы.