33 KiB
Отчёт — лабораторная 4
- Автор, группа: Боцоев Арсен, БВТ2303.
- Целевая оценка: 4 — все требования уровней 3 и 4. Исследовательские треки оценки 5 не заявлены.
- Стенд: Docker Compose, HAProxy, две реплики FastAPI, PostgreSQL, Valkey, SeaweedFS с приватным S3 bucket.
- Commit/PR: после публикации. В этой копии нет git-репозитория, поэтому evidence/lab4-checks.json содержит source_commit=null и working_tree=null.
- Источники и помощь: официальные материалы перечислены в конце; код и проверки подготовлены с помощью 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/lab4-checks.json, evidence/lab4-checks.txt и evidence/postgres-pause.json.
Добавлена миграция 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, project lab4-pg-pause-6c3e872952: SQL без серверного таймера прерван за 2.0 s, соединение закрыто; прямой readiness вернул 503 за 2.012 s. Все 10 параллельных readiness-запросов вернули 503, максимум 2.197 s. PostgreSQL оставалась на pause 14.918 s; live отвечал 200. После unpause действующая сессия и сообщение доступны через LB за 1.355 s, без restart API.
Согласованность S3 и PostgreSQL на уровне 4
- После приёма и проверки файла отдельный COMMIT сохраняет attachment_uploads с ID и object_key.
- Следующая транзакция берёт advisory lock object_key, выполняет S3 PUT, вставляет attachments и удаляет журнал. Только после COMMIT отправляется 201.
- При обрыве клиентского тела до проверки S3/журнал ещё не затрагиваются. При ошибке PUT или отказе БД после PUT сохраняется долговечное намерение. Если исход COMMIT неизвестен, немедленного DELETE нет: ready-метаданные могли сохраниться.
- Cleaner каждые 30 s выбирает до 100 записей старше grace period, пробует ту же advisory lock и повторно проверяет возраст и наличие ready-метаданных. Активный lock означает пропуск. Если ready существует, очищается только журнал. Иначе выполняются идемпотентный S3 DELETE и удаление журнала.
- Ошибка 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
Среда: Linux x86_64 в WSL; Docker 29.4.2 x86_64 CPUs=16 RAM=8019410944; Compose 5.1.3. Две API-реплики, по 1 CPU и 384 MiB. Прогрев — полный smoke и 39 тестов до эксперимента; накопившаяся память отражена в baseline. Временный project: lab4-check-1ad8ecf540.
| Показатель | Наблюдение |
|---|---|
| Параллельные uploads | 10 из 10, ошибок 0 |
| Один PNG | 5769329 bytes, 1600×1200 RGB |
| Длительность / успешные upload/s | 1.119 s / 8.934 |
| p50 / p95 HTTP upload | 639.1 / 1104.59 ms |
| Оригиналы | 10 download, все SHA-256 совпали |
| OOM | Нет |
| API instance | Baseline cgroup, MiB | Пик выборки во время uploads, MiB | Пик cgroup за жизнь контейнера, MiB | Лимит, MiB |
|---|---|---|---|---|
| 330027f55a61 | 200.83 | 223.73 | 225.47 | 384 |
| 27e984eebdb7 | 66.77 | 100.57 | 158.78 | 384 |
Различие baseline между репликами возникло после предыдущих проверок и аллокаций; сравнение не трактуется как чистое измерение стоимости одного декодирования. Пик за жизнь контейнера включает более ранние тесты. Гипотеза о соблюдении лимита в этом профиле подтверждена; универсальная производительность или поведение при произвольном числе клиентов не выводятся.
| Воздействие | Наблюдение | Восстановление / потеря подтверждённых данных |
|---|---|---|
| Остановлена загрузившая API-реплика 27e984eebdb7 | Download обслужила 330027f55a61; исходный SHA-256 совпал | 2.093 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.737 s | Прямой ready=503 за 2.01 s; 10 повторов, максимум 2.197 s; live=200 | После unpause 2.2 s; API не перезапущены, сессия и сообщение сохранены |
| Restart всего стенда с volumes | StartedAt всех постоянных процессов изменились; сессия, metadata, bytes и повтор сообщения сохранены | Уложилось в бюджет ожидания 90 s; потерь нет |
| SIGTERM с незавершённым POST | Новые соединения прекращены за 0.26 s; exit code 0, без OOM | Выход за 6.036 s, меньше 8 s |
Дополнительно сохранены результаты отказа каждой реплики и поочерёдной замены под нагрузкой:
| Сценарий | Длительность, s | Успешные HTTP/s | Переходные ошибки | Макс. пауза POST / GET, s | Потери / дубли |
|---|---|---|---|---|---|
| stop 27e984eebdb7 | 16.032 | 68.86 | 4 | 1.99 / 1.937 | 0 / 0 |
| stop 330027f55a61 | 16.105 | 70.91 | 4 | 1.997 / 2.0 | 0 / 0 |
| sequential API replacement | 30.186 | 71.16 | 8 | 1.995 / 2.146 | 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 и использует синтетические учебные данные.