# Отчёт — лабораторная 4: S3-вложения **Автор / группа:** Авзалов Артур Марсович / БПИ2301 **Целевая оценка:** 5 **Выбранный трек:** №2 — согласованность PostgreSQL и S3 **Среда:** Windows PowerShell, Docker Desktop, Python, Docker Compose; прогоны представлены в переписке 12.11.2026. **Статус:** основной функционал, восстановление потерянного объекта, очистка orphan и сравнительная стоимость обхода **проверены локально 12.11.2026**. Не проверены отдельно одновременная потеря двух S3-копий и реальная авария COMMIT PostgreSQL; ограничения явно указаны ниже. ## Архитектура и перенос Lab3 ```text Клиент (127.0.0.1:8080) │ HAProxy, HTTP L7, round-robin ├── FastAPI api1 ─┐ └── FastAPI api2 ─┤ ├── PostgreSQL: пользователи, чаты, сообщения, metadata вложений, receipts ├── Redis: общие bearer-сессии └── SeaweedFS S3: приватные объекты-оригиналы и recovery copy One-shot: migrate / s3-policy / s3-bootstrap Maintenance: reconcile (dry-run по умолчанию) ``` Сохранены публичное API и механизмы Lab3: Bearer-сессии, сообщения, миграции, курсорная пагинация, Idempotency-Key, конкуренция через PostgreSQL advisory lock, X-Instance-Id, X-Request-Id, readiness/healthchecks, две взаимозаменяемые реплики и отказ одной из них. Все реплики используют общие PostgreSQL, Redis и S3. В наружную сеть публикуется только порт HAProxy `127.0.0.1:8080`; S3-консоль/API и PostgreSQL/Redis не публикуются на хост. В `compose.yaml` закреплены образы `postgres:16.10-bookworm`, `redis:7.4.5-alpine`, `haproxy:3.1.7-alpine`, `chrislusf/seaweedfs:4.53`. S3 хранит данные в именованных volumes. `s3-policy` формирует политику доступа, `s3-bootstrap` создаёт приватный bucket; API и reconciler используют выделенные ключи, ограниченные bucket. Локальные `.env` и приватные credentials не должны попадать в Git. ## Контракт вложений - `POST /api/v1/chats/{chat_id}/attachments?filename=...`: raw PNG/JPEG, не `multipart`; `201` только после успешных S3 PUT оригинала/резервной копии и COMMIT метаданных в PostgreSQL. - Изображение проверяется по сигнатуре/декодированию, соответствию заявленному MIME, границам размера (10 MiB) и пикселей (40 млн), небезопасные имена файлов отклоняются. Имя файла используется только в metadata, S3-ключ генерирует сервер. - `GET /api/v1/attachments/{id}` и `GET /api/v1/attachments/{id}/content` проверяют участие пользователя в чате, иначе 404. Оригинал читается из общего S3 и отдаётся через API без публичного S3 URL. - Ограничение памяти: streaming/spool с RAM-порогом 1 MiB, максимум исходника 10 MiB; семафор для Pillow-декодирования. Контейнер API имеет `mem_limit: 384m`. - Для каждого attachment хранятся `attachments//original` и `recovery//original`. Это две логические копии **на одном SeaweedFS**, не защита от потери всего S3-узла. ## Проблема согласованности PostgreSQL и S3 S3 PUT и PostgreSQL COMMIT не образуют распределённой транзакции. Возможные сбои: 1. S3-объект уже создан, а транзакция БД не завершилась — **orphan**, объект без metadata. 2. Metadata присутствует, но основного S3-ключа нет — **missing primary**; его можно восстановить из recovery copy. 3. Metadata присутствует, но резервного S3-ключа нет — **missing backup**; его можно восстановить из основного. 4. Отсутствуют обе копии — автоматическое восстановление невозможно; нужен внешний backup/ручной разбор. В пути загрузки выполняется best-effort компенсационное удаление при ошибке. Периодическая сверка (`python -m app.reconcile`) перечисляет S3-ключи и записи PostgreSQL, классифицирует несовпадения, печатает JSON. По умолчанию **dry-run**, без изменений. `--apply` восстанавливает потерянную копию или удаляет orphan только после `grace_seconds >= 300` и повторной проверки, что объект не указан в зафиксированной таблице БД. Повторный `--apply` при согласованном состоянии не должен делать действий. При потере обеих копий metadata не удаляются. Гипотеза трека: **сверка двух хранилищ, recovery copy и защитный интервал позволяют исправлять одиночные пропажи ключей и безопасно убирать orphan-объекты без удаления используемых файлов**. Издержка решения — около двух копий занимаемого S3-пространства; полный проход держит инвентаризацию в памяти порядка `O(N_s3_keys + N_db_rows)` и выполняет соответствующее число проверок/перечислений. ## Запуск с чистого clone (PowerShell) Требуются Docker Desktop с Compose v2, Python 3.9+ (для локальных тестов), работающий Docker Engine. Запуск из корня текущей Lab4: ```powershell Copy-Item .env.example .env notepad .env # Установить разные случайные POSTGRES_PASSWORD, S3_ADMIN_SECRET_KEY, S3_SECRET_KEY; # проверить значения остальных обязательных переменных без публикации секретов. $env:PYTHONUTF8 = '1' docker compose --env-file .env config --quiet docker compose --env-file .env up -d --build --wait docker compose --env-file .env ps python scripts/check_contract.py python tests/smoke.py python tests/attachments_negative.py python tests/idempotency_parallel.py ``` Эквивалент `make check` — `python scripts/check_contract.py`; эквивалент `make test` — `python tests/smoke.py`. В представленных логах проверялись прямые вызовы Python, а не отдельный запуск `make`. На Windows можно вызвать `make check PYTHON=python` и `make test PYTHON=python`, если make установлен. **Persistence:** `python tests/resilience.py --mode persistence --action-script scripts/restart.cmd` **Failover:** `python tests/resilience.py --mode failover --action-script scripts/stop-one.cmd`; после теста восстановить `docker compose --env-file .env up -d --no-deps --wait api1 api2`. **S3:** `docker compose --env-file .env run --rm reconcile python -m app.s3_probe`. **Reconciler:** `docker compose --env-file .env run --rm reconcile python -m app.reconcile [--apply]`. В `LAB4_TEST_COMMANDS.md` перечислены демонстрационные и негативные сценарии. Безопасная остановка: `docker compose --env-file .env down` **без `-v`**, иначе удалятся данные. ## Фактические результаты локальных испытаний Результаты ниже основаны на переданных stdout PowerShell/Docker. Это локальные прогоны, не CI. Следы команд и ключевые JSON-выводы обезличенно переписаны в `evidence/verified_results_2026-11-12.md`. Неинструментированная производительность из одного запуска не обобщается на production. | Проверка | Результат | Комментарий | |---|---|---| | `docker compose config --quiet`, `up -d --build --wait` | PASS | Контейнеры API × 2, HAProxy, PostgreSQL, Redis, S3 запущены; API/LB/DB/Redis healthy | | `python scripts/check_contract.py` | PASS | Offline-проверка структуры и синтаксиса, не интеграционный тест | | `python tests/smoke.py` | PASS | Public API, вложение, checksum, ACL | | `python tests/attachments_negative.py` | PASS | MIME, повреждение, размер, filename, ACL, cross-chat | | `python tests/idempotency_parallel.py` | PASS | Две реплики, одно сообщение, replay 201, конфликт 409 | | `python -m app.s3_probe` | PASS | Private bucket: анонимные listing/object GET запрещены | | `python -m app.reconcile_selftest` | PASS | Изолированная проверка dry-run, grace, restore, повторного apply; не заменяет интеграционные тесты | | `python -m app.reconcile` до инъекций | PASS | 4 S3-ключа, 2 строки БД; нет расхождений и ошибок | | Persistence с `restart.cmd` | PASS | После перезапуска сохранены сообщения, сессия и байты вложения; тест сверяет скачанное с исходником | | Failover с `stop-one.cmd` | PASS | 2 реплики до отказа, 6 успешных записей, 1 неуспешная попытка; восстановление за **6,156 с** | | 10 параллельных PNG-загрузок | PASS | 10/10, ошибок 0, 2,796 с, 3,577 upload/s, p50 2164 мс, max 2344 мс, 111817 байт/файл | | RAM API при конкурентных загрузках | Наблюдено | Пиковые из выборочных `docker stats`: api1 **109,1 MiB**, api2 **96,21 MiB**, оба лимита 384 MiB; не абсолютный пик | | Отказ S3 | PASS | После `docker compose stop s3` HAProxy вернул HTTP 503; после запуска S3 и готовности API smoke PASS | | Повторная сверка после всех восстановлений | PASS | 34 S3-ключа, 17 строк БД; проблем нет; время обхода 0,213 с | ### Эксперимент A: потерян основной S3-объект **Инъекция:** `python -m app.reconcile_fault delete-primary --id ` под `LAB4_ALLOW_FAULT_INJECTION=yes`. Только учебное окружение. Изменён объект `attachments/045ee0a6-be0d-4712-884f-b82145888ad6/original` (идентификатор синтетического вложения). | Шаг | Наблюдение | |---|---| | Удаление оригинала | `fault: delete-primary`; recovery copy сохранена | | Первый dry-run | `missing_primary_repairable` содержит UUID, `actions=[]`, `errors=[]`; 31 ключ, 16 строк, **0,162 с** | | `--apply` | `action: restore`, копирование из `recovery//original` → `attachments//original`, `errors=[]`; **0,216 с** | | Повторный dry-run | 32 ключа, 16 строк, пустые mismatch и actions; **0,159 с** | | Повторный apply, отдельный прогон | 34 ключа, 17 строк, `actions=[]` и `errors=[]`; **0,179 с** | | Smoke после восстановления | PASS | **Вывод:** успешное восстановление одиночной пропажи основного ключа подтверждено на реальном SeaweedFS/PostgreSQL. Приведённый публичный smoke проходил после исправления, но байтовая сверка **именно выбранного вручную UUID** отдельно не снималась. ### Эксперимент B: объект существует в S3 без metadata **Инъекция:** `python -m app.reconcile_fault create-orphan` (моделирует разрыв «S3 PUT успел, PostgreSQL COMMIT не произошёл»). Создан `attachments/db466391-0d91-4757-990f-f2bb93872f5d/original`. | Шаг | Наблюдение | |---|---| | Dry-run сразу после создания | `orphan_keys_young` содержит объект, `orphan_keys=[]`, `actions=[]`, 35 ключей/17 строк, **0,190 с** | | `--apply` до истечения 300 с | Объект **не удалён**, `actions=[]`, `orphan_keys_young` содержит ключ, **0,225 с** | | Пауза | Явное `Start-Sleep -Seconds 310` | | `--apply` после паузы | `orphan_keys` содержит ключ, `action: delete-old-orphan`, `errors=[]`, **0,228 с** | | Финальный dry-run | 34 ключа, 17 строк, нет orphan/missing/errors/actions, **0,213 с** | **Вывод:** grace period не позволяет удалить свежий объект; stale orphan удаляется только в apply. Отдельная авария/откат реальной PG-транзакции при загрузке не инъецировалась — испытан эквивалентный итоговый случай «S3 объект есть, metadata нет». ### Эксперимент C: недоступность SeaweedFS `docker compose --env-file .env stop s3` → публичный `GET /health/ready` через HAProxy вернул **HTTP 503** (`No server is available to handle this request`). Затем `up -d s3`, `up -d --wait api1 api2 lb` и `python tests/smoke.py` → **PASS**. Это подтверждает отказ публичной готовности и восстановление работоспособности. Прямые ответы каждой реплики `/health/ready` при отключённом S3 отдельно не снимались. ### Эксперимент D: стоимость обхода при трёх объёмах данных **Гипотеза:** при увеличении числа объектов S3 и строк PostgreSQL растёт объём инвентаризации и потенциальная стоимость полной сверки, но для небольшого локального набора время одного прохода остаётся приемлемым. **Методика:** из корня Lab4 запущен `powershell -ExecutionPolicy Bypass -File scripts/measure_reconcile.ps1`. На каждом этапе выполнялось **5 независимых dry-run**, всего **15**. После этапов 0 и 1 добавлялось по 50 PNG-вложений (5 пакетов × 10 параллельных upload), всего **100 новых вложений**, **0 ошибок загрузки**. Каждый upload создаёт две S3-копии. Измеряется **`scan_elapsed_seconds` внутри reconciler**, а не общее время создания временного Docker-контейнера. Никакого `--apply` во время замеров не было. | Этап | Ключей S3 | Строк БД | Прогонов | Среднее, с | Медиана, с | Диапазон, с | |---|---:|---:|---:|---:|---:|---:| | 0 | 36 | 18 | 5 | **0,3208** | **0,245** | 0,207–0,624 | | 1 | 136 | 68 | 5 | **0,3068** | **0,285** | 0,270–0,401 | | 2 | 236 | 118 | 5 | **0,3814** | **0,341** | 0,289–0,568 | Измерения из stdout соответствуют файлу, созданному на машине тестирования: **`evidence/reconcile-cost-20261112-180238.csv`**. Приложите **оригинальный CSV**, а не вручную переписанные данные, в Git вместе с отчётом. Обезличенная сводка и 15 значений приведены также в `evidence/verified_results_2026-11-12.md`. **Интерпретация:** при росте числа ключей с 36 до 236 (≈6,56 раза) медиана выросла с 0,245 до 0,341 с (≈39%). Среднее на этапе 1 оказалось чуть ниже этапа 0 из-за разброса/первого длительного замера; упорядоченный рост трёх медиан — наблюдение, **не доказательство линейной масштабируемости**. Малый набор, один хост, 5 прогонов на этап, кеширование и сетевые колебания ограничивают переносимость результатов. Полный inventory хранит списки ключей/строк в RAM; для больших объёмов нужны потоковая пагинация и батчинг. Отдельный ранний контрольный замер: **34 ключа S3 + 17 строк БД → 0,213 с**; он относится к другому моменту измерений и не заменяет серию выше. ## Что пока не заявляется как PASS - Инъекция **одновременной потери обеих S3-копий** и подтверждение nonzero/ручной обработки. Алгоритм содержит ветку `missing_both_unrecoverable`, но интеграционный тест не предъявлен. - Полноценная реальная ошибка PostgreSQL COMMIT посреди upload; созданный orphan моделирует конечное состояние этого сбоя. - Вариант, когда чужой объект получает ссылку из БД строго **между** inventory и DELETE, отдельно не проверен в живой гонке (в коде есть повторная проверка ссылки). - Измерены только небольшие локальные наборы (36–236 S3-ключей); на сотнях тысяч и миллионах объектов время/память не измерялись. - Стресс ≥10 параллельных больших файлов: тест использовал 10 файлов по 111817 байт; измеренные значения RAM относятся к этому профилю. - Доступность при потере PostgreSQL, Redis, S3-диска, Docker-host/HAProxy, реальное rolling deployment несовместимых версий, TLS/дистрибутивные секреты. ## Ограничения и безопасность Один Docker-host, один S3/PG/Redis/LB — точки отказа. Recovery copy находится на том же SeaweedFS и не заменяет внешний backup. Результат HTTP `503` ожидаем при критической недоступности S3. На локальном учебном окружении transport S3/PG/Redis не использует mTLS; для production нужны TLS, внешний secret manager, backups, логи и метрики. При оборванной потоковой отдаче уже отправленный `200` нельзя отозвать: проверяйте полноту ответа/checksum на стороне клиента. Поведение отката при сбое между двух независимых хранилищ основано на компенсации и сверке, не на общей ACID-транзакции. Полный inventory держится в памяти и требует батчинга на больших объёмах. ## Источники и применение ИИ Основание: `README.md`, `contracts/`, `tests/README.md` лабораторной №4, документация S3/SeaweedFS, PostgreSQL, Redis, Docker Compose, HAProxy, FastAPI и Pillow. ChatGPT использовался для проектирования, программирования, SQL-миграций, тестов, Docker-конфигурации, скриптов и текста отчёта. Данные испытаний получены локальными командами пользователя, а не сгенерированы ИИ. В Git не публикуются `.env`, credentials, session tokens, приватные ключи, приватные данные и volumes.