Files
mtusi2026lab4/REPORT.md

33 KiB
Raw Permalink Blame History

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

  • Автор, группа: Савельев Иван, БВТ2304.
  • Целевая оценка: 4 — все требования уровней 3 и 4. Исследовательские треки оценки 5 не заявлены.
  • Стенд: Docker Compose, HAProxy, две реплики FastAPI, PostgreSQL, Valkey, SeaweedFS с приватным S3 bucket.
  • Commit/PR: после публикации. Evidence содержит source_commit и working_tree=true: проверялась рабочая версия поверх этого commit.
  • Источники и помощь: официальные материалы перечислены в конце; код и проверки подготовлены с помощью Codex, результаты получены запуском Docker-стенда.

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

Нужны Docker Engine с Compose v2, Python 3.11, Bash и make; для demo.sh — curl и jq. Проверенная среда записана в evidence/lab4-checks.json. Все команды выполняются из корня этого репозитория, внешние установленные БД или S3 не нужны.

python3 -m venv .venv
.venv/bin/python -m pip install -r requirements.txt -r requirements-dev.txt
make check validate PYTHON=.venv/bin/python
./scripts/start.sh
./scripts/check.sh

Адрес API: http://localhost:8080. start.sh генерирует локальные .env и secrets/, собирает образ, поднимает хранилища, выполняет миграции и bootstrap bucket, запускает API, LB и cleaner. Возврат из скрипта означает готовность обеих API-реплик через LB. Существующие пароли и настройки не перезаписываются. Локальный IAM-конфиг S3 собирается из тех же secret-файлов. Каталог secrets имеет права 0700; файлы 0444 позволяют UID 10001 контейнера читать смонтированные Docker secrets. .env, secrets и .venv игнорируются Git; Docker build context содержит только необходимые исходники.

Если 8080 занят другим стендом, сохраните HOST_PORT=8081 в .env и используйте BASE_URL=http://localhost:8081 для HTTP-проверок. Либо передайте HOST_PORT=8081 в окружении start.sh. Compose project mtusi-lab4 и его volumes отделены от lab3.

docker compose ps -a
./scripts/demo.sh
./scripts/restart.sh     # перезапуск всех постоянных процессов; volumes сохраняются
./scripts/stop.sh        # удаление контейнеров/сетей; volumes сохраняются
./scripts/start.sh       # повторный запуск с прежними данными

# Только для намеренного удаления учебных данных текущего Compose project:
docker compose down --volumes

Закреплены Python 3.11.15-slim-bookworm с digest в Dockerfile, PostgreSQL 17.6-bookworm, Valkey 8.1.3, HAProxy 3.2.6-alpine, SeaweedFS 3.85 с digest sha256:49312939c00c01e5ee6afbd7d728b18027821d3764c35a797a72acd4fdf3296a. Версии Python-библиотек зафиксированы в requirements.txt; добавлены MinIO Python SDK 7.2.20 и Pillow 13.0.0. SDK работает с S3 API SeaweedFS; сервер MinIO не требуется.

Архитектура и перенос из lab3

Клиент → HAProxy :8080 → API × 2 → PostgreSQL (метаданные, сообщения, идемпотентность)
                              → Valkey (серверные Bearer-сессии)
                              → S3 gateway :9000 → SeaweedFS storage → s3_data
Одноразовые migrate → PostgreSQL; s3-bootstrap → приватный bucket
Постоянный cleanup → журнал PostgreSQL + DELETE незавершённых объектов S3

Из lab3 сохранены пользователи, Argon2id, Basic-вход и Bearer-сессии, ACL чатов, текстовые сообщения, keyset-пагинация, X-Request-Id/X-Instance-Id, общая идемпотентность, миграции, LB, ограничения ресурсов и скрипты отказа/замены реплик. Предыдущие отчёты — REPORT.lab2.md и REPORT.lab3.md. Архивные evidence/lab3-* относятся к прежней работе.

Добавлена миграция 003: attachments, message_attachments, attachment_uploads и request_attachment_ids в таблице идемпотентности. Миграции 001/002 не изменены. Старые сообщения читаются с attachment_ids=[]. Новый POST сообщения принимает до 10 уникальных attachment_ids; чужой/неизвестный ID или ID другого чата даёт 404. Весь список проверяется до вставки сообщения в одной транзакции. Пустой/пробельный text допустим только при наличии вложений. Любой участник может использовать вложение своего чата. Порядок списка сохраняется; при повторе ключа сравниваются text и список UUID. Пропущенный список и [] равнозначны.

Бинарного содержимого в PostgreSQL нет. Случайный object_key вида attachments/ назначает сервер; filename используется только для отображения и Content-Disposition. В API нет endpoint удаления/изменения вложения. Ready-метаданные и связи сообщений постоянны, локальный файл API для чтения оригинала не нужен. Детали FK, индексов и транзакций — в docs/schema.md.

Настройка .env.example Реальное использование
APP_HOST, APP_PORT 0.0.0.0:8080 внутри API
HOST_PORT Публичный порт LB на 127.0.0.1
APP_ENV Учебная метка, не переключает поведение
SESSION_STORE, SESSION_TTL_SECONDS Valkey; TTL сессии, по умолчанию 3600 s
DATABASE_URL_FILE, CACHE_URL_FILE Пути Docker secrets PostgreSQL и Valkey
API_REPLICAS Две реплики по умолчанию; LB рассчитан на 10
IDEMPOTENCY_TTL_SECONDS Не меньше 86400 s; одинаковый ответ при повторе
S3_ENDPOINT, S3_REGION, S3_BUCKET http://s3:9000, us-east-1, messenger-attachments
S3_ACCESS_KEY_ID_FILE, S3_SECRET_ACCESS_KEY_FILE Только ограниченные credentials приложения
MAX_UPLOAD_BYTES, MAX_IMAGE_PIXELS 10485760 bytes, 40000000 pixels; повышение выше контракта запрещено
UPLOAD_CLEANUP_GRACE_SECONDS 3600 s, минимум 60 s; защита свежих/незавершённых загрузок

Приватный bucket и bootstrap

Выбран один S3-совместимый сервер — SeaweedFS. Два сервиса одного продукта разделяют его S3 gateway и внутренние master/volume/filer. s3-storage и его административные HTTP/gRPC-интерфейсы находятся только в закрытой сети s3-internal; API к ней не подключены. Только S3 gateway соединяет эту сеть с сетью приложения. Наружу опубликован лишь LB: ни 9000, ни UI, ни внутренние API-порты не опубликованы.

init_local.py создаёт отдельные случайные root и application credentials. S3 загружает статическую IAM-конфигурацию из secret s3_config, без anonymous identity. Администратор используется только одноразовым s3-bootstrap; тот проверяет наличие bucket и создаёт его при отсутствии. Повторный bootstrap сохраняет bucket и объекты. Root secrets/IAM-файл не монтируются в API или cleaner.

Приложению разрешены Read и List только своего bucket и Write только prefix attachments/*. В терминах SeaweedFS Write включает PUT/DELETE объектов; административных действий и записи вне prefix нет. Тест напрямую, вне API приложения, проверяет anonymous GET=403, запрет создания другого bucket и записи вне prefix, недоступность административных портов и изоляцию storage-сети. Приватность S3 дополняется ACL приложения: запрос без Bearer даёт 401, посторонний участнику чата пользователь — 404 как для metadata, так и для content.

Приём, проверка и скачивание

POST /api/v1/chats/{id}/attachments?filename=... принимает сырые bytes PNG/JPEG. Сначала выполняются аутентификация и проверка чата, затем валидация имени и MIME. Запрещены slash, backslash, NUL, управляющие символы, пустое/пробельное имя и длина более 255 code points.

Content-Length свыше лимита отклоняется до чтения тела. Независимо от заголовка, включая chunked upload, счётчик проверяется при каждом полученном фрагменте до записи в TemporaryFile: больше 10 MiB — 413. Тело не собирается через request.body(). Временный файл закрывается и удаляется при успехе, ошибке, прерывании клиента и завершении процесса; он не является постоянным хранилищем оригинала.

Pillow открывает только PNG/JPEG, проверяет реальный формат и число пикселей до load(), затем verify() и полное декодирование обнаруживают повреждения. Подмена MIME/чужой формат/повреждённое изображение — 415; превышение pixels — 413. DecompressionBombWarning считается ошибкой. Оригинал не перекодируется, SHA-256 считается по исходному потоку.

На одну API-реплику приходится одна активная загрузка/декодирование; остальные запросы ждут слот до 20 s с обратным давлением ASGI, далее получают 503. Приём тела ограничен 30 s. S3 имеет connect timeout 1 s, read timeout 3 s и отключённые автоматические повторы. Один оригинал ≤10 MiB отправляется одним PUT, без multipart и его незавершённых частей. SDK может держать до 10 MiB для PUT; декодирование ограничено 40 млн pixels и одним изображением. Каждый API имеет лимит 384 MiB и 1 CPU; количество загрузок не умножает число полных декодирований на реплике.

201 ready отправляется только после сохранения S3 и COMMIT metadata. variants=[], error_code=null. GET metadata/content снова проверяет членство в чате. Content идёт через API без redirect, порциями 64 KiB с истинным Content-Type, Content-Length, безопасным Content-Disposition и nosniff. Файл не читается целиком в RAM при скачивании; S3-соединение закрывается в finally. SHA-256 и size_bytes описывают исходные bytes.

/health/ready проверяет PostgreSQL, Valkey и существование S3 bucket подписанным HEAD. /health/live проверяет процесс. При отказе S3 обязательные upload/download получают 503; LB исключает неготовые API. После отправки части download последующий сетевой обрыв означает неполный HTTP download: статус уже не заменяется, клиент может повторить безопасный GET.

Пауза PostgreSQL и клиентский таймаут

Помимо connect_timeout=2 s, ожидания пула 2 s и серверного statement_timeout=3 s, каждое ожидание PostgreSQL I/O ограничено на стороне приложения двумя секундами. TimedConnection использует timeout метода wait() закреплённой версии Psycopg 3.3.6. Это распространяется на проверку соединения из пула, выполнение SQL, COMMIT и ROLLBACK, даже когда процесс PostgreSQL приостановлен и серверный таймер не работает.

При OperationalError соединение закрывается до выхода из контекста транзакции. API возвращает 503 unavailable в обычном формате, не ожидая отмены запроса или ROLLBACK от приостановленного сервера. Зависших потоков и выданных навсегда соединений не остаётся; пул создаёт замену. После docker compose unpause postgres readiness и запросы с прежними сессиями восстанавливаются без перезапуска API.

Регрессионная проверка получает соединение до pause и отключает серверный statement_timeout, чтобы отдельно проверить клиентское ограничение SQL. Затем держит настоящую PostgreSQL на pause не менее 12 s, проверяет прямой /health/ready, 10 параллельных повторов и /health/live внутри API-контейнера, минуя LB. После unpause сверяются неизменные ID/StartedAt API, действующая сессия и сохранённое сообщение. Сценарий включён в check-docker.sh; отдельно запускается в своём временном стенде:

./scripts/build.sh
.venv/bin/python student-tests/postgres_pause.py

Результат отдельного запуска: evidence/postgres-pause.json. Полный прогон сохраняет этот сценарий в поле postgres_pause файла lab4-checks.json.

Фактическая проверка 06.11.2026: SQL без серверного таймера прерван за 2.001 s, соединение закрыто; прямой readiness вернул 503 за 2.012 s. Все 10 параллельных readiness-запросов вернули 503, максимум 2.299 s. PostgreSQL оставалась на pause 12.565 s; live отвечал 200. После unpause действующая сессия и сообщение доступны через LB за 2.874 s, без restart API.

Согласованность S3 и PostgreSQL на уровне 4

  1. После приёма и проверки файла отдельный COMMIT сохраняет attachment_uploads с ID и object_key.
  2. Следующая транзакция берёт advisory lock object_key, выполняет S3 PUT, вставляет attachments и удаляет журнал. Только после COMMIT отправляется 201.
  3. При обрыве клиентского тела до проверки S3/журнал ещё не затрагиваются. При ошибке PUT или отказе БД после PUT сохраняется долговечное намерение. Если исход COMMIT неизвестен, немедленного DELETE нет: ready-метаданные могли сохраниться.
  4. Cleaner каждые 30 s выбирает до 100 записей старше grace period, пробует ту же advisory lock и повторно проверяет возраст и наличие ready-метаданных. Активный lock означает пропуск. Если ready существует, очищается только журнал. Иначе выполняются идемпотентный S3 DELETE и удаление журнала.
  5. Ошибка S3/БД откладывает проход. Если DELETE уже прошёл, а COMMIT удаления журнала нет, повторный DELETE безопасен. При восстановлении зависимостей worker продолжает работу.

По умолчанию grace=1 час существенно больше таймаутов загрузки; минимальное значение — 60 s. Транзакция записи имеет idle timeout 30 s. Свежие и активные загрузки защищены возрастом и блокировкой, ready-объекты не удаляются даже без привязки к сообщению. После восстановления сервисов журнал не остаётся без обработчика.

# Ручной дополнительный проход; постоянный cleanup-service уже работает:
docker compose run --rm --no-deps cleanup python -m src.cleanup --once

Это ограниченная компенсация операций приложения. Полный reconciler, presigned upload, варианты изображений и фоновая обработка из следующих лабораторных не добавлялись.

Команды проверки и доказательства критериев

make check validate PYTHON=.venv/bin/python
./scripts/check.sh
make test-persistence PYTHON=.venv/bin/python ACTION_SCRIPT=scripts/restart.sh
make test-failover PYTHON=.venv/bin/python ACTION_SCRIPT=scripts/stop-one.sh
docker compose start api
./scripts/wait-ready.sh

# Полный повторяемый прогон уровня 4 в отдельном временном Compose project:
./scripts/check-docker.sh

check-docker.sh выбирает отдельное имя lab4-check- и свободный порт, создаёт только синтетические данные. В finally удаляет только свои контейнеры и volumes; обычный mtusi-lab4 остаётся доступным. Моделирование отказа БД использует временный trigger в тестовой БД; trigger удаляется в finally. Рабочий API не содержит fault-injection endpoint или специального заголовка.

Критерий README Команда/сценарий Наблюдение и evidence
Сохранены возможности lab3, две реплики, общая сессия/идемпотентность check.sh, повтор ключа через реплики, повтор после рестарта, SIGTERM, rolling update под нагрузкой api_tests, persistence, sigterm, failovers, rolling_update
S3 в общем стенде; metadata в PostgreSQL, bytes в приватном bucket Docker inspect, прямой S3 GET, проверки прав containers, attachments.private_bucket
201 ready, Message с attachment_ids, SHA-256 и побайтный download Публичный smoke и test_attachments lab4-checks.txt; api_tests
Реальные PNG/JPEG, MIME, 10 MiB и 40 MP, опасные filename test_png_and_jpeg_originals, corruption_and_mime_spoof, pixel_limit_before_decode, filename_rejected_before_storage 39 собственных тестов; lab4-checks.txt
Upload → остановка загрузившей реплики → download другой Сопоставление X-Instance-Id и Docker ID, реальная stop-one attachments.upload_replica_failover
Restart сохраняет metadata/bytes/действующую сессию Публичный persistence, StartedAt всех процессов до/после persistence
Слишком большой файл, повреждение, подмена MIME, чужой ID/другой чат не дают 500 Отдельные негативные HTTP-тесты, включая chunked без Content-Length test_attachments; lab4-checks.txt
Прерывание загрузки и сбой между S3/БД не оставляют вечные неучтённые объекты Обрыв сокета; trigger отказывает после PUT; затем ручной и автоматический cleaner attachments.interrupted_body, compensation
Безопасный grace period, защита активных/готовых объектов, повторная очистка Свежий журнал, backdate, удержание advisory lock, ready-ссылка, повтор DELETE compensation.fresh_kept/active_locked_kept/ready_kept/repeat_safe/automatic_worker
Ограничены RAM/таймауты; ≥10 одновременных загрузок с замером памяти Barrier на 10 клиентах, настоящие PNG 1600×1200, cgroup каждые 20 ms, SHA-256 всех downloads attachments.parallel_uploads
Идемпотентный bootstrap и ограниченные S3 credentials; закрытая администрация Два bootstrap, запрещённые S3 операции, TCP-пробы из API attachments.private_bucket
Недоступность S3 и восстановление Остановка настоящего s3-service, запросы внутри API в обход исключившего backend LB attachments.s3_outage; dependency_readiness
PostgreSQL на pause: ограниченный прямой readiness и восстановление без restart API postgres_pause.py: SQL без серверного таймера, pause ≥12 s, 10 параллельных запросов, unpause postgres_pause; evidence/postgres-pause.json

Все актуальные результаты — evidence/lab4-checks.txt и evidence/lab4-checks.json. Токены, пароли и исходные тела запросов туда не сохраняются. PASS публичного smoke сам по себе не считается доказательством всех критериев.

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

Гипотеза: десять одновременных загрузок не вызывают десять полных декодирований на API; слот и лимиты удерживают RAM ниже контейнерного лимита, оригиналы сохраняются без изменений. Методика: один случайный несжимаемый RGB PNG 1600×1200 (~5.5 MiB), десять потоков с общим barrier, две API-реплики; после каждого 201 второй участник скачивает оригинал, проверяется SHA-256. Монитор в каждой API читает cgroup v2 memory.current каждые 20 ms. Сохраняются исходные временные ряды, memory.peak за всю жизнь контейнера и лимит, duration, successful RPS, p50/p95, число ошибок и OOMKilled. Файл генерируется заново при каждом запуске; его точный размер/checksum записаны в JSON.

Замер включает Python-процесс монитора и файловый cache cgroup; это консервативная оценка контейнерной памяти, а не чистый RSS приложения. Пик выборки может пропустить события короче 20 ms; memory.peak дополнительно показывает пик за жизнь контейнера. Это один ограниченный учебный прогон с 10 клиентами, без поиска предельной производительности. p50/p95 относятся к успешным HTTP upload; coordinated omission и влияние клиента остаются ограничениями.

Результат фактического прогона 06.11.2026

Среда: Darwin arm64; Docker 29.0.1 aarch64 CPUs=10 RAM=8217448448; Compose 2.40.3-desktop.1. Две API-реплики, по 1 CPU и 384 MiB. Прогрев — полный smoke и 39 тестов до эксперимента; накопившаяся память отражена в baseline. Временный project: lab4-check-5aad8e0065.

Показатель Наблюдение
Параллельные uploads 10 из 10, ошибок 0
Один PNG 5769335 bytes, 1600×1200 RGB
Длительность / успешные upload/s 0.914 s / 10.939
p50 / p95 HTTP upload 610.113 / 904.09 ms
Оригиналы 10 download, все SHA-256 совпали
OOM Нет
API instance Baseline cgroup, MiB Пик выборки во время uploads, MiB Пик cgroup за жизнь контейнера, MiB Лимит, MiB
19a474c69210 190.10 205.22 261.53 384
ca1f62dfc015 64.43 98.59 100.28 384

Различие baseline между репликами возникло после предыдущих проверок и аллокаций; сравнение не трактуется как чистое измерение стоимости одного декодирования. Пик за жизнь контейнера включает более ранние тесты. Гипотеза о соблюдении лимита в этом профиле подтверждена; универсальная производительность или поведение при произвольном числе клиентов не выводятся.

Воздействие Наблюдение Восстановление / потеря подтверждённых данных
Остановлена загрузившая API-реплика ca1f62dfc015 Download обслужила 19a474c69210; исходный SHA-256 совпал 3.535 s от начала stop; потерь нет
Прервано HTTP-тело Metadata и журнал не созданы; S3 PUT не начинался Очистка временного файла; ready-объектов не затрагивает
БД отказала после S3 PUT HTTP 503; объект существует вместе с журналом; ready-metadata отсутствует Свежий/активный объект сохранён; после искусственного старения безопасно удалён; worker проверен отдельно
S3 service остановлен live=200, ready/upload/download=503 в едином формате API После старта прежний токен и оригинал работают; downtime отдельно не измерялся
PostgreSQL на pause 14.572 s Прямой ready=503 за 2.013 s; 10 повторов, максимум 2.107 s; live=200 После unpause 1.975 s; API не перезапущены, сессия и сообщение сохранены
Restart всего стенда с volumes StartedAt всех постоянных процессов изменились; сессия, metadata, bytes и повтор сообщения сохранены Уложилось в бюджет ожидания 90 s; потерь нет
SIGTERM с незавершённым POST Новые соединения прекращены за 0.185 s; exit code 0, без OOM Выход за 5.523 s, меньше 8 s

Дополнительно сохранены результаты отказа каждой реплики и поочерёдной замены под нагрузкой:

Сценарий Длительность, s Успешные HTTP/s Переходные ошибки Макс. пауза POST / GET, s Потери / дубли
stop 19a474c69210 16.012 88.68 4 2.002 / 1.995 0 / 0
stop ca1f62dfc015 16.008 91.58 4 2.002 / 1.999 0 / 0
sequential API replacement 24.869 90.63 8 1.04 / 1.04 0 / 0

Этот профиль из lab3 использует четыре закрытых клиента: POST сообщения и GET истории, пауза 50 ms. При неопределённом POST повторяется тот же ключ/тело. Длительность включает 1 s прогрева и воздействие; исходные посекундные счётчики есть в JSON. Это проверка восстановления и отсутствия потерь, а не поиск предельного RPS.

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

Гарантируется сохранность при проверенном обычном restart с volumes и отказе одной API-реплики при доступных зависимостях. PostgreSQL, Valkey, S3 и LB остаются отдельными точками отказа; HA хранилищ, отказ хоста/электропитания и backup этой работы не заявлены. HEAD bucket в readiness не является тестом записи каждого объекта. Потеря или удаление volumes уничтожает соответствующие данные.

После 201 данные доступны всем участникам через любую готовую реплику. Неопределённый ответ upload может привести к ещё одному готовому вложению при повторе: идемпотентность upload контрактом не предусмотрена. Cleaner удаляет только незавершённые журналируемые операции; потеря одновременно БД/журнала или ручная запись посторонних объектов требует работы оператора. При длительной недоступности S3/БД очистка откладывается до восстановления.

Слоты и ресурсные лимиты ограничивают память, но не обещают отсутствие 503 при произвольной нагрузке. Временный spool хранится на ephemeral disk API только во время запроса. Для удалённого стенда нужен TLS; текущий HTTP привязан к localhost и использует синтетические учебные данные.

Первичные источники