# Отчёт — лабораторная 4 - Автор, группа: Сергей Возжин, БПИ2301. - Целевая оценка: 5; выбран трек 2 — согласованность PostgreSQL и S3. - Commit/PR: https://gitea.privcloud.tech/mtusi2026/mtusi2026lab4/pulls/70 - Использованные источники: контракт репозитория, документация Docker Compose, Chainguard Images, MinIO SDK и Pillow. - Библиотеки: FastAPI, Uvicorn, SQLAlchemy, asyncpg, Alembic, redis-py, MinIO Python SDK, Pillow, Argon2, pytest. - Помощь ИИ: OpenAI Codex использовался для плана, реализации, тестов и оформления отчёта; результат проверен исполняемыми тестами. ## Запуск из чистого clone Требуются Docker Engine с Compose v2, Python 3.9+ для публичных тестов и свободный host-порт 8080. Проверенный стенд: Apple M4 Pro, 12 CPU cores, 24 GB RAM, Docker Desktop; API на Python 3.13.15. Закреплённые компоненты: - `python:3.13.15-slim`; - `postgres:17.4-alpine`; - `redis:7.4.2-alpine`; - `haproxy:3.2.26-alpine`; - Chainguard MinIO `RELEASE.2026-10-23T20-06-51Z`, OCI index digest `sha256:3c60a2a8c4d33409a9bc7a623a7fcbfb4605adc3d89422d2f53b3f673a6e5597`; - Chainguard MinIO Client, вариант `latest-dev`, OCI index digest `sha256:39768db4c3fa811bc8f2e2a3e0add8ea391648b1c980de179985e1c353dc1805` (`mc --version` сообщает upstream build marker `DEVELOPMENT.GOGET`). Готовые образы MinIO и `mc` скачиваются из реестра Chainguard `cgr.dev`; в Compose оба образа закреплены по OCI digest. Сервис `s3` использует минимальный образ `minio` и в учебном стенде запускается с `user: "0"`, чтобы иметь доступ к Docker volume `/data`; его порты на host не публикуются. Для одноразового `s3-bootstrap` используется образ `minio-client` с shell и `sed`, необходимыми для создания bucket, отдельного пользователя API и bucket-scoped policy. Создать локальную конфигурацию и заменить синтетические пароли, не добавляя `.env` в Git: ```sh cp .env.example .env ``` `S3_BUCKET` допускает изменение: bootstrap при каждом запуске заново применяет ограниченную policy с текущим именем bucket. `MINIO_ROOT_*` получает только MinIO и bootstrap; API получает отдельные `S3_ACCESS_KEY_ID` и `S3_SECRET_ACCESS_KEY`. Access key и secret считаются параметрами первоначальной инициализации пользователя MinIO; их ротация требует явной операторской процедуры, а не изменения `.env` на работающем volume. Проверить конфигурацию, собрать образы, применить миграции и дождаться готовности: ```sh docker compose --env-file .env config --quiet docker compose --env-file .env up -d --build --wait docker compose --env-file .env ps ``` `migrate` выполняет `alembic upgrade head` отдельно и однократно. `s3-bootstrap` идемпотентно создаёт приватный bucket, отдельного пользователя API и bucket-scoped policy. Две API-реплики стартуют только после миграции, Redis и успешного bootstrap. Единственная публичная точка входа — `http://localhost:8080`; API, PostgreSQL, Redis, S3 API и административная консоль MinIO наружу не публикуются. Основные проверки: ```sh python3 -m venv .venv .venv/bin/python -m pip install -r requirements-dev.txt make check make validate PYTHON=.venv/bin/python make test make test-attachments PYTHON=.venv/bin/python make test-persistence ACTION_SCRIPT=scripts/restart.sh make test-failover ACTION_SCRIPT=scripts/stop-one.sh docker compose --env-file .env up -d --wait --wait-timeout 60 api lb make test-attachment-failover ACTION_SCRIPT=scripts/stop-one.sh docker compose --env-file .env up -d --wait --wait-timeout 60 api lb scripts/check-private-bucket.sh scripts/check-s3-outage.sh .venv/bin/python scripts/measure-upload-memory.py --concurrency 10 --uploads 30 make reconcile-dry make benchmark-reconciler ``` Исправления следует сначала просмотреть через `make reconcile-dry`. Изменяющий данные `make reconcile-apply` запускается оператором только после проверки dry-run. `make benchmark-reconciler` по умолчанию создаёт 100, 1000 и 10000 изолированных пар metadata/object, выполняет по три dry-run для каждого размера и удаляет тестовые данные. Набор и число повторов меняются через `SIZES="..."` и `RUNS=...`; старый одиночный параметр `SIZE=...` также поддерживается. Каждый failover-тест намеренно оставляет выбранную API-реплику остановленной, поэтому между сценариями и после последнего сценария она явно восстанавливается указанной командой `docker compose up`. Безопасная остановка с сохранением данных: ```sh docker compose --env-file .env down ``` Намеренное необратимое удаление учебных данных выполняет только оператор: ```sh docker compose --env-file .env down -v ``` ## Архитектура и решения ```text HTTP client | v HAProxy :8080 | +-- round-robin --> API replica 1 --+--> PostgreSQL: metadata | +--> Redis: sessions +-- round-robin --> API replica 2 --+--> private MinIO: original bytes ``` Из lab3 сохранены две взаимозаменяемые API-реплики, HAProxy, общие PostgreSQL/Redis, Bearer-сессии, `X-Instance-Id`, общая идемпотентность сообщений, readiness и failover hooks. В lab4 добавлены: - MinIO и persistent `s3_data` volume; - таблицы `attachments` и `message_attachments`; - синхронный binary upload PNG/JPEG; - авторизованные metadata/download endpoints; - `attachment_ids` в сообщениях и в области сравнения идемпотентного body; - компенсационное удаление объекта и безопасный cleanup старых orphan-объектов; - повторяемый reconciler метаданных PostgreSQL и оригиналов S3. PostgreSQL является источником истины для метаданных. В БД не хранятся bytes изображения. MinIO хранит оригинал по серверному ключу `originals/`. Пользовательский `filename` хранится только как метаданные и не используется в object key или пути файловой системы. ### Upload и лимиты API сначала проверяет сессию, доступ к чату, filename и заявленный MIME. Тело читается чанками в `SpooledTemporaryFile`: до 1 MiB находится в памяти, затем временно сбрасывается на ephemeral disk API. Как только суммарный размер становится больше 10 MiB, запрос отклоняется с 413; превысивший лимит чанк в spool не записывается. Постоянной локальной копии нет. Pillow определяет реальный PNG/JPEG, проверяет совпадение MIME, размеры до декодирования пикселей и целостность изображения через `verify()`. Максимум — 10 485 760 bytes и 40 000 000 пикселей. Пустой, повреждённый или чужой формат возвращает 415; превышение лимита bytes/pixels — 413. S3-вызовы выполняются вне event loop. HTTP client S3 имеет ограниченные connect/read timeout и retry. Readiness проверяет PostgreSQL, Redis и существование bucket. ### Транзакционная граница PostgreSQL/S3 Атомарной транзакции между S3 и PostgreSQL нет. Для синхронного `201 ready` выбран порядок: 1. Полностью проверить ограниченный файл. 2. Выполнить S3 PUT. 3. Выполнить транзакцию INSERT метаданных. 4. Вернуть `201` только после успешного завершения обоих шагов. Если PUT не удался, метаданные не создаются. Если PUT прошёл, а транзакция БД упала, API выполняет best-effort S3 DELETE. Unit-тест с внедрённой ошибкой БД подтверждает компенсацию. Если компенсационное удаление также не удалось, остаётся orphan без метаданных. CLI находит такие объекты: ```sh docker compose --env-file .env run --rm --no-deps api \ python -m app.tools.cleanup_orphans --dry-run --grace-seconds 3600 docker compose --env-file .env run --rm --no-deps api \ python -m app.tools.cleanup_orphans --apply --grace-seconds 3600 ``` По умолчанию используется grace period один час; CLI запрещает значения меньше 60 секунд. Объекты с существующими метаданными и свежие orphan-объекты не удаляются. Сначала используется `--dry-run`, затем осознанный `--apply`. ### Reconciler PostgreSQL/S3 — трек 2 Гипотеза эксперимента: полный снимок PostgreSQL и listing MinIO дадут линейную асимптотику `O(N)` по времени и памяти. На диапазоне 100–10000 согласованных пар рост времени не должен становиться сверхлинейным; абсолютные значения зависят от Docker-host и прогрева, поэтому для каждой точки используются три последовательных запуска и медиана. Расширенный reconciler запускается внутри API-контейнера, где уже есть те же настройки и ограниченные S3 credentials, что у приложения: ```sh docker compose exec -T api \ python -m app.tools.reconcile_attachments --dry-run --grace-seconds 3600 docker compose exec -T api \ python -m app.tools.reconcile_attachments --apply --grace-seconds 3600 ``` Он читает снимок всех `attachments` и список `originals/`, после чего различает: - `orphan`: объект S3 есть, но ни одной строки с таким `object_key` нет; - `missing`: строка в состоянии `ready` есть, а оригинала S3 нет; - корректную пару: присутствуют обе стороны; - свежее расхождение: возраст меньше grace period, изменять его нельзя. В `--dry-run` выводятся `WOULD_DELETE_ORPHAN` и `WOULD_MARK_MISSING`, но записи и объекты не меняются. В `--apply` старый orphan удаляется, а missing-метаданные сохраняются и переходят в `status=failed`, `error_code=original_missing`. Сообщение и связь с вложением не удаляются. Повторный `--apply` ничего не делает: orphan уже отсутствует, а `failed` больше не считается ожидающим оригинал состоянием. При этом строка `failed` по-прежнему защищает внезапно появившийся объект с тем же ключом от удаления как orphan. Grace period защищает upload, который ещё выполняется, и запрещён ниже 60 секунд. Используемые сообщением вложения не имеют особого исключения: любой известный PostgreSQL ключ защищён одинаково, поэтому корректный оригинал связанного сообщения не удаляется. Content для `failed` возвращает 409, а привязать такое вложение к новому сообщению нельзя. Начальные снимки могут устареть во время apply. Поэтому перед удалением orphan reconciler повторно проверяет отсутствие `object_key` в PostgreSQL, перед маркировкой missing выполняет `HEAD/stat` объекта, а SQL `UPDATE` дополнительно сравнивает `id`, `object_key`, `status` и исходный `updated_at`. Гонки логируются как `SKIP_*` и учитываются в `race_protected`. Общей транзакции между PostgreSQL и S3 всё равно нет: остаётся узкое TOCTOU-окно между последней проверкой и действием. Полностью закрыть его можно только протоколом состояний/ lease или запретом параллельного восстановления на время apply. Операции между двумя хранилищами всё ещё не образуют общей транзакции. Если apply прервётся, уже выполненное безопасное удаление orphan не требует отката, условный SQL UPDATE меняет только всё ещё `ready` строки, а повторный запуск завершает оставшуюся работу. ### Доступ и идемпотентность Метаданные и content доступны любому участнику чата. Неизвестный объект и запрос постороннего одинаково возвращают 404. Download идёт через API без redirect. Публичный ответ не раскрывает object key, endpoint или credentials. Сообщение принимает 0–10 уникальных `attachment_ids`. Все вложения должны быть `ready` и относиться к тому же чату. Пустой текст допустим только с вложением. Сравнение идемпотентного запроса включает упорядоченный список attachment ID; отсутствие поля и `[]` считаются одинаковыми. ## Доказательства критериев | Критерий README | Команда/сценарий | Наблюдаемый результат | Доказательство | | --- | --- | --- | --- | | Offline/OpenAPI | `make check`; `make validate PYTHON=.venv/bin/python` | оба PASS | `evidence/results.md` | | Публичный smoke | `make test` | `PASS: lab4 public API scenario` | `evidence/results.md` | | Негативные сценарии | `make test-attachments PYTHON=.venv/bin/python` | `12 passed` | `tests/test_attachments.py`, `evidence/results.md` | | Компенсация S3/БД | unit-тест с ошибкой repository | S3 DELETE вызван для загруженного ключа; `1 passed` | `tests/test_attachment_compensation.py` | | Private bucket | `scripts/check-private-bucket.sh` | anonymous GET получил 403 | `evidence/results.md` | | Недоступность S3 | `scripts/check-s3-outage.sh` | readiness вернул структурированный 503; стенд восстановлен | `evidence/results.md` | | Persistence | `make test-persistence ACTION_SCRIPT=scripts/restart.sh` | прежние token, metadata и bytes доступны после restart PostgreSQL/Redis/MinIO/API | `evidence/results.md` | | Общий lab3 failover | `make test-failover ACTION_SCRIPT=scripts/stop-one.sh` | 111 записей, 1 переходная ошибка, восстановление 2,333 с, файл сохранён | `evidence/results.md` | | Точный attachment failover | `make test-attachment-failover ACTION_SCRIPT=scripts/stop-one.sh` | загрузившая реплика остановлена, download через другую за 3,912 с, SHA-256 совпал | `evidence/results.md` | | Concurrency/RAM | `scripts/measure-upload-memory.py --concurrency 10 --uploads 30` | 30/30 upload, обе реплики, пики 68,50/68,33 MiB | `evidence/upload-memory.json` | | Идемпотентный bootstrap | повторный запуск `docker compose up` после restart/failover | bootstrap повторно завершился с code 0 | `evidence/results.md` | | Cleanup dry-run | `cleanup_orphans --dry-run --grace-seconds 60` | 164 известных объекта, удалено 0 | `evidence/results.md` | | Reconciler fault injection | реальный PostgreSQL + MinIO: orphan, missing, fresh и три конкурентных изменения | apply исправляет только подтверждённые расхождения; свежие/изменённые данные защищены; повторный apply — 0 действий | `tests/test_reconciler_integration.py`, `evidence/results.md` | | Полный тестовый стенд | изолированный Compose, все pytest | `17 passed` | `evidence/results.md` | | Стоимость обхода | `SIZES="100 1000 10000" RUNS=3 make benchmark-reconciler` | медианы: 80,712 / 227,467 / 1733,545 мс; Python peak 2,62 / 4,21 / 8,08 MB | `evidence/results.md` | ## Эксперименты и отказы Проверяемые ожидания: - остановка загрузившей API-реплики не меняет файл и не лишает вторую реплику доступа; - restart обязательных хранилищ с volumes сохраняет метаданные, bytes и сессию; - недоступность S3 наблюдаема как 503, а не 500; - 10 параллельных upload не приводят к неограниченному росту RAM. Профиль upload: 30 запросов, concurrency 10, fixture 111 817 bytes, closed-loop, без retry. Получено 30 успешных upload за 0,382 с; максимальная latency 0,300 с; задействованы обе API-реплики. Пиковая наблюдаемая RAM: 68,50 MiB и 68,33 MiB при лимите 256 MiB на реплику. Fault injection reconciler выполняется на настоящих PostgreSQL и MinIO. Тест создаёт старую `ready` строку без объекта, объект без строки и корректное вложение, уже связанное с сообщением. Дополнительно он восстанавливает missing-объект, изменяет `updated_at` другой missing-строки и создаёт metadata для orphan уже после получения начальных снимков, а также проверяет настоящий свежий orphan. Управляемые часы имитируют истечение grace period без минутного ожидания. Apply исправляет только подтверждённые расхождения; свежий объект и все три конкурентно изменённые сущности защищены. Повторный apply не повторяет исправления, связь сообщения сохраняется. Воспроизводимый benchmark для каждого размера удаляет прежнюю фикстуру, создаёт одинаковое число строк `attachments` и объектов MinIO, выполняет три полных dry-run и удаляет данные. | Пар metadata/object | Время, мс (три запуска) | Медиана, мс | Медианный peak Python allocations | | ---: | --- | ---: | ---: | | 100 | 78,847; 80,712; 82,781 | 80,712 | 2 620 657 bytes | | 1 000 | 232,254; 227,467; 226,264 | 227,467 | 4 205 016 bytes | | 10 000 | 1701,005; 1792,955; 1733,545 | 1733,545 | 8 075 853 bytes | Измерение включает запрос PostgreSQL, listing MinIO и сравнение снимков; подготовка и очистка в `elapsed_ms` не входят. Результат согласуется с гипотезой `O(N)`: после заметной фиксированной стоимости время и память монотонно растут, на исследованном диапазоне нет признаков сверхлинейного взрыва. Это не доказательство для production-масштаба: измеряется Python `tracemalloc`, а не RSS контейнера, и полный снимок всё равно требует памяти `O(N)`. | Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных | | --- | --- | --- | --- | | Restart API + PostgreSQL + Redis + MinIO | token, metadata и bytes сохраняются | persistence PASS | потерь нет | | Остановка API в общем failover | вторая реплика продолжает чтение/запись | 111 записей, 1 краткая ошибка | 2,333 с; потерь и дублей нет | | Остановка загрузившей API | файл скачивается через другую | SHA-256 совпал, разные instance ID | 3,912 с; потерь нет | | Остановка MinIO | readiness сообщает отказ зависимости | структурированный 503, после запуска readiness восстановился | потерь нет | ## Ограничения и следующие шаги Стенд выдерживает остановку одной API-реплики и штатный restart контейнеров с сохранёнными volumes. Он не выдерживает потерю Docker-host, единственного HAProxy, PostgreSQL, Redis или MinIO volume. Несколько API-процессов не делают единственные хранилища высокодоступными. Upload синхронный, поэтому клиент ждёт S3 и PostgreSQL. `SpooledTemporaryFile` ограничивает RAM одной загрузки, но временный disk API должен иметь достаточный объём и отдельную квоту в production. Reconciler загружает полный список объектов и строк БД в память, поэтому его стоимость O(N), а для большого bucket нужны страничный/потоковый обход, метрики, checkpoint и плановый запуск. Chainguard-образы зафиксированы по digest, поэтому обновляются только явно. Стенд изолирован учебной сетью. Перед production-развёртыванием потребовались бы непривилегированный UID с корректными правами на volume, TLS, внешний secret manager, HA хранилищ, аудит и резервное копирование. Presigned upload, worker, thumbnail и варианты изображений намеренно не реализованы: для выбранного трека 2 они не требуются.