Files
mtusi2026lab4/REPORT.md
T

275 lines
30 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Отчёт — лабораторная работа №4
Автор: **Ляхонов Сергей**, группа **БВТ2301**. Дата: **30 октября 2026 года**.
Целевая оценка: **5**, выбран **трек 2 — согласованность двух хранилищ**. Пользователь выбрал трек до реализации.
Ветка: `solution/BVT2301-lyakhonov`. Только локальные русскоязычные коммиты; push и PR не выполнялись.
## Запуск из чистого clone
Нужны Docker Engine/Compose с Linux-контейнерами, Python 3.12+ на хосте и make (самим публичным тестам достаточно Python 3.9+) (либо прямые эквивалентные Python-команды ниже).
Проверено: Windows, Python хоста 3.13.7, Docker Engine 28.5.1 / Docker Desktop, i5-1340P, 16 логических CPU и 16 GB RAM.
Docker VM: 16 CPU, 8 126 664 704 bytes RAM. См. [CPU](evidence/cpu.json), [RAM](evidence/hardware.json), [Docker](evidence/docker-resources.json).
Для сборки исходников S3 и всех экспериментов разумно выделить Docker около 8 GB RAM и иметь около 10 GB свободного диска под build cache/образы/учебные данные.
Постоянные runtime-лимиты стенда: суммарно 4 CPU и 2816 MiB; генератор и одноразовые сервисы требуют дополнительного ресурса.
Это лимиты, а не гарантированное фактическое потребление.
PowerShell, из корня лабораторной 4:
```powershell
$env:PYTHONUTF8='1'
python scripts/bootstrap.py
docker compose --env-file .env config --quiet
docker compose --env-file .env build api s3
docker compose --env-file .env up -d
python scripts/wait_ready.py --base-url http://localhost:8084 --replicas 2
make check test PYTHON=python BASE_URL=http://localhost:8084
python -m venv .venv
.venv/Scripts/python -m pip install -r requirements-research.txt
make validate PYTHON=.venv/Scripts/python
```
Bootstrap создаёт случайные DB/S3 secrets и `.env` из `lab4.env.example` **только при отсутствии**; существующие файлы сохраняются.
Пароли и ключи не выводятся и не попадают в Git. Отдельный migrate применяет версии 001–003 под advisory lock до старта API.
Bucket-init создаёт приватный bucket и ограниченного пользователя приложения; повтор безопасен.
Все зависимости запускаются из этого репозитория; установленные ранее БД/S3 не используются.
Реестр отказал в скачивании официальных образов MinIO/mc (Docker Hub denied, Quay 401), поэтому окончательный стенд
собирает S3 из исходников через `Dockerfile.s3`: MinIO commit `07c3a429bfed433e49018cb0f78a52145d4bedeb`
(исходники RELEASE.2025-09-07T16-13-09Z), mc RELEASE.2025-04-16T18-13-26Z.
Оба архива закреплены SHA-256 в ADD; Go и Debian закреплены digest, Go-зависимости проверяются go.sum.
Первичная сборка реально прошла, повтор использует build cache. Нужен доступ к GitHub, Docker Hub и Go module proxy;
наличие локального старого MinIO-образа не требуется. Версия самосборного бинарника может выводиться как DEVELOPMENT.GOGET;
точная идентичность задаётся commit и архивом, не этой строкой. Лицензии MinIO/mc AGPL включены в образ.
[Контрольные суммы](evidence/s3-source-hashes.json), [рецепт](Dockerfile.s3).
Остановка без удаления данных: `docker compose down`. Стенд №3 не затрагивается.
Только при намеренном удалении собственных учебных данных: `docker compose down --volumes`.
Последняя команда необратима; в проверках основного стенда она не используется. Одноразовый стенд проверки чистого экспорта удаляет только собственные вновь созданные scratch volumes. Внешние volumes и чужие Compose projects не удаляются.
На POSIX использовать python3 и executable `.sh` hooks (`chmod +x scripts/restart.sh scripts/stop-one.sh`).
Чистый Git-экспорт коммита `6c87ed2` отдельно проверен скриптом `python scripts/verify_clean_export.py`:
новые secrets, уникальные project/images/volumes и свободный loopback-порт; сборка API/S3, две готовые реплики и публичный smoke прошли.
Основные стенды не изменялись. После проверки одноразовые контейнеры/сеть/тома удалены.
[Результат](evidence/clean-export.json), [сборка](evidence/repro-build.txt).
## Архитектура и конфигурация
```mermaid
flowchart LR
Client[Клиент] --> LB[HAProxy localhost:8084]
LB --> API1[API 1]
LB --> API2[API 2]
API1 --> DB[(PostgreSQL: метаданные и сессии)]
API2 --> DB
API1 --> S3[(MinIO: приватные оригиналы)]
API2 --> S3
API1 --> Redis[(Redis: необязательный кэш профилей)]
API2 --> Redis
Reconciler[Периодическая сверка] --> DB
Reconciler --> S3
```
| Роль → service | Версия / CPU / RAM | Готовность / durable state / доступ |
| --- | --- | --- |
| API → api ×2 | Python 3.11.10, lock dependencies; 0.5 CPU / 512 MiB каждая | `/health/ready`: PostgreSQL + S3; без durable локальных оригиналов; только внутренняя сеть |
| БД → db | PostgreSQL 16.6-alpine; 1 CPU / 512 MiB | pg_isready; отдельный postgres_data; порт не опубликован |
| S3 → s3 | Собственная сборка из закреплённых исходников; 1 CPU / 768 MiB | bootstrap ждёт S3; API проверяет LIST рабочего prefix; отдельный s3_data; без внешних портов |
| LB → lb | HAProxy 3.0.6-alpine; 0.5 CPU / 128 MiB | HTTP readiness API; только 127.0.0.1:8084 |
| Кэш → redis | Redis 7.4.1-alpine; 0.25 CPU / 128 MiB | Необязателен; профили, без сессий/истории; persistence отключён |
| Миграции → migrate | Тот же исходный образ; 0.5 CPU / 512 MiB | Одноразовый exit 0 до API, schema_migrations |
| Bucket bootstrap → bucket-init | Тот же S3-образ, mc; 0.25 CPU / 128 MiB | Одноразовый exit 0; приватность и политика; root secrets доступны только здесь и S3 |
| Сверка → reconciler | Тот же исходный образ; 0.25 CPU / 256 MiB | Apply каждые 300 с, grace 3600 с; отдельный процесс, restart unless-stopped |
Compose project `lyakhonov-lab4`, собственные сеть, `lyakhonov-lab4_postgres_data`, `lyakhonov-lab4_s3_data`,
образы `lyakhonov-messenger:lab4` и `lyakhonov-storage:lab4`. Нет container_name и наружных портов API/БД/S3/Redis.
Консоль MinIO слушает только loopback самого S3-контейнера. Пароли передаются через read-only Compose secrets files.
Приложение имеет S3 LIST только своего bucket/prefix и Get/Put/Delete только `attachments/originals/*`;
не имеет административного доступа, list buckets, delete bucket или записи вне prefix. Bucket — `attachments`, публичного чтения нет.
API работает без root. Единственные PostgreSQL, S3, LB и Docker-host остаются SPOF.
`lab4.env.example` задаёт реальные пользовательские параметры LAB4_PORT, API_REPLICAS, API_CPUS, API_MEMORY,
POOL_SIZE, SESSION_TTL_SECONDS и OPTIMIZED_WRITES. Исходный `.env.example` skeleton сохранён как список логических интерфейсов:
APP_HOST/APP_PORT соответствуют фиксированному listener 0.0.0.0:8080; APP_ENV не используется; SESSION_STORE=postgres фиксирован;
CACHE_URL_FILE заменён внутренним CACHE_URL=redis://redis:6379/0; DATABASE_URL_FILE совпадает.
S3_ENDPOINT и регион совпадают; S3_BUCKET в решении фиксирован `attachments` вместо предложенного messenger-attachments.
S3_ACCESS_KEY_ID_FILE/S3_SECRET_ACCESS_KEY_FILE отображаются на внутренние S3_ACCESS_KEY_FILE/S3_SECRET_KEY_FILE.
IDEMPOTENCY_TTL_SECONDS=86400, MAX_UPLOAD_BYTES=10485760, MAX_IMAGE_PIXELS=40000000 — обязательные фиксированные лимиты,
не произвольные пользовательские настройки. Изменение старого `.env.example` не меняет эти внутренние значения.
## Перенос и границы транзакций
Источник: собственная лабораторная №3, HEAD `374c43e`, только чтение. Оба рабочих дерева до начала были чистыми.
Перенесены исходники, миграции, зависимости, Dockerfile и необходимые конфигурации/scripts.
README, COURSE, обязательные contracts, публичные tests и fixture лабораторной №4 сохранены.
Не переносились .git, .env, secrets, volumes, venv, старые измерения/графики. [Акт переноса](evidence/transfer.md).
Сохранены PostgreSQL-сессии, Argon2id, ACL чатов, пагинация, две реплики и общая транзакционная идемпотентность.
В отличие от lab3, Message теперь всегда содержит attachment_ids; допускает пустой текст с вложениями.
Ключ сравнивает полный нормализованный body, включая порядок ID; отсутствующее attachment_ids равно [].
Результат ключа, Message и связи вложений фиксируются атомарно. Конкурентные повторы сериализуются общей блокировкой.
Миграция 003 переносит старые текстовые результаты ключей в JSON и добавляет Attachment/message_attachments.
Обратное смешивание lab3/lab4 API после этой миграции не поддерживается: требуется согласованный переход.
В этой работе использован новый отдельный volume, исходная БД lab3 не изменялась.
Upload: авторизация/ACL → bounded temporary spool → MIME/размер/пиксели/verify/load → уникальный S3 PUT → INSERT → COMMIT → 201 ready.
Оригинал сохраняется побайтно. Приём <=10 MiB, <=40 млн px; один декодер на реплику, <=20 с на body, <=25 с ожидания слота.
Только временный spool живёт локально до PUT; download читает S3 блоками 64 KiB без redirect.
S3 timeout connect=2/read=5 с и без retry, LB client=60/server=45 с и без повторов POST.
Неопределённый COMMIT не вызывает слепое удаление объекта. Подробный протокол и инварианты: [infra/reconciliation.md](infra/reconciliation.md).
## Доказательства критериев
| Критерий | Команда/сценарий | Реальный результат / доказательство |
| --- | --- | --- |
| Обязательная база lab3 и контракт lab4 | make check/test/validate | PASS: [make](evidence/make-check-test.txt), [validate](evidence/validate.txt) |
| Upload 201 ready, сообщение, checksum, ACL | публичный smoke | PASS: [smoke](evidence/smoke.txt); PNG/JPEG неизменны |
| ≥2 API, остановка именно загрузившей реплики | python student-tests/test_operations.py | Обе разные реальные реплики остановлены по очереди; другой процесс вернул оригинал: [JSON](evidence/operations.json) |
| Retry и сохранность при failover | публичный resilience --mode failover | PASS, ошибки перехода учтены: [1](evidence/failover-1.txt), [2](evidence/failover-2.txt) |
| Рестарт с volumes и прежней сессией | публичный persistence + test_operations.py | PASS, реальные StartedAt до/после API/БД/Redis/S3/LB: [persistence](evidence/persistence.txt), [operations](evidence/operations.json) |
| S3 недоступен / восстановлен | test_operations.py | Ограниченный 503, после восстановления те же bytes и сессия |
| Bytes/пиксели/MIME/filename/повреждения | test_attachments.py | PASS, включая chunked body >10 MiB, >40 млн px и допустимые ровно 40 млн px: [negative suite](evidence/attachments.txt) |
| Чужой ID, другой чат, дубли ID | test_attachments.py | 404/400, без 500 |
| Обрыв body | реальный TCP disconnect | Постоянный объект не создан |
| Сбой после PUT до INSERT | ограниченный synthetic DB trigger | Получен 500, объект найден сверкой как orphan; trigger снят в finally |
| Ограничение RAM при ≥10 загрузках | python scripts/run_upload_load.py | 60/60 успешно, два размера, cgroup peak и Docker stats: [raw](evidence/upload-load.json), [CSV](evidence/upload-summary.csv) |
| Приватность и минимальные S3-права | unsigned GET + запрещённые S3 API | 403; отдельные credentials приложения: [suite](evidence/attachments.txt) |
| Идемпотентный bucket bootstrap | docker compose run --rm --no-deps bucket-init | Повтор exit 0: [вывод](evidence/bootstrap-repeat.txt) |
| Orphan/missing/corrupt | test_reconcile.py | Найдены; old orphan удалены; missing/corrupt изолированы без удаления метаданных |
| Dry-run, повтор и конкуренция | test_reconcile.py | Все метаданные до/после dry-run совпали; блокировка/свежесть/ссылки сохранены; два прохода безопасны |
| Безопасное восстановление | неверный, затем правильный оригинал | Неверные bytes не вернули ready; проверенный оригинал восстановил его: [исследование](evidence/reconcile.json) |
| Стоимость обхода | 0/50/200 дополнительных объектов ×3 | Время, LIST/HEAD/GET и bytes измерены, график ниже |
## Эксперимент загрузки и память
Фиксированный seed, PNG RGB 1024² и 1792², один прогрев на размер. Три партии по 10 клиентов на размер через LB,
прозрачных retry нет. Клиенты готовы до начала измерительного окна; все одновременно отпускаются event.
Суммарное timed elapsed для шести партий — 6.966 с; это короткий опыт, не steady-state soak test.
Elapsed включает завершение всех запросов, не подготовку клиентов и не последующее скачивание подтверждённых оригиналов.
p50/p95/p99 интерполируются линейно по успешным запросам; при 10 наблюдениях хвост оценён грубо.
Генератор — отдельный контейнер с 0.5 CPU / 512 MiB. API пересозданы перед замером; фоновая сверка остановлена и затем восстановлена.
Не менялись ресурсы/версии между размерами. Это closed-loop партии, без контроля arrival rate и с coordinated omission;
универсальная максимальная пропускная способность не заявляется. Ранние пилоты с подготовкой клиента внутри окна заменены этой серией.
| Размер PNG, bytes | Успехи / попытки | RPS, медиана | p50 / p95 / p99, с (медианы) |
| --- | --- | --- | --- |
| 3151219 | 30 / 30 | 16.73 | 0.408 / 0.585 / 0.591 |
| 9648062 | 30 / 30 | 5.63 | 1.061 / 1.716 / 1.764 |
![Скорость и задержка загрузки](evidence/figures/upload-throughput.png)
![Память API](evidence/figures/upload-memory.png)
Docker stats показывает выборочный working set, cgroup memory.peak — kernel high-water mark за жизнь новых API-контейнеров
(включает старт, прогрев, загрузки и проверку скачивания). Эти два показателя различаются учётом cache и частотой наблюдения.
- API `68ab8db39c84`: kernel peak **167.95 MiB** при лимите 512 MiB.
- API `a6106479affd`: kernel peak **156.98 MiB** при лимите 512 MiB.
Для CPU 100% Docker stats означает одно логическое ядро. Сырые CPU%/RAM, временные метки и cpu.stat сохранены
в upload-load.json; sampled memory для API ниже лимита. Выборки включают прогрев, подготовку клиентов и скачивание, поэтому это не интеграл CPU только внутри timed batches.
| Служба | CPU%, медиана / максимум выборок |
| --- | --- |
| lyakhonov-lab4-api-1 | 7.90 / 49.68 |
| lyakhonov-lab4-api-2 | 7.60 / 51.60 |
| lyakhonov-lab4-db-1 | 1.54 / 4.78 |
| lyakhonov-lab4-lb-1 | 2.25 / 12.86 |
| lyakhonov-lab4-s3-1 | 1.21 / 27.30 |
Это не доказательство нулевых аллокаций:
декодер допустимого 40 MP изображения может занять порядка 160 MB дополнительно; одновременно декодируется одна картинка на процесс.
## Исследование согласованности: гипотеза и результаты
Гипотеза: PostgreSQL/S3 нельзя объединить обычным локальным COMMIT; безопасная периодическая сверка с общей блокировкой
и защитным интервалом убирает orphan и отмечает missing, сохраняя свежие и используемые вложения.
Цена — обход всех объектов/строк и чтение подтверждаемых bytes, поэтому она растёт с числом объектов и объёмом оригиналов.
Методика: реальный INSERT отказал после PUT; отдельно удалён S3-оригинал уже привязанного к сообщению вложения.
Созданы старый orphan, свежий orphan и объект под удерживаемой общей блокировкой (имитация окна upload до COMMIT).
Dry-run сверяет полный снимок id/state/updated_at; apply удаляет только безопасные orphan и ставит missing.
Следующий проход не дублирует изменение state. После снятия блокировки/истечения grace ранее защищённые orphan могут быть удалены —
это ожидаемое продолжение очистки, а не ошибка идемпотентности. Существующие строки Attachment защищаются независимо от возраста и наличия сообщения.
Два конкурентных reconciler пропускают занятые ключи. Неверные bytes оставляют missing; корректные bytes возвращают ready;
связь с исходным сообщением сохраняется. Тестовый grace=5 с, ожидание старения=6 с; рабочий default=3600 с.
[Полные агрегаты](evidence/reconcile.json), [сценарий](student-tests/test_reconcile.py).
Измерение стоимости: фиксированный набор метаданных и оригиналов, добавляются 0/50/200 неучтённых объектов по 1 KiB.
По три dry-run на точку, page_size=50; сервис периодической сверки остановлен, другая нагрузка не запускается.
Порядок 0→50→200; cache состояния не сбрасывался. Выигрыш/регрессию оптимизации этот опыт не измеряет.
| Всего объектов | Время, медиана [min; max], с | LIST / HEAD / GET | Проверено bytes за проход |
| --- | --- | --- | --- |
| 221 | 4.964 [4.835; 5.073] | 5 / 221 / 221 | 1193831654 |
| 271 | 5.185 [4.994; 5.314] | 6 / 271 / 221 | 1193831654 |
| 421 | 6.356 [6.225; 6.826] | 9 / 421 / 221 | 1193831654 |
![Стоимость сверки](evidence/figures/reconcile-cost.png)
В этой серии GET/проверенные bytes постоянны, рост дополнительных orphan увеличивает HEAD и LIST.
Это подтверждает рост цены обхода; три повтора и небольшой bucket не доказывают асимптотическую производительность большой инсталляции.
Чтение всех оригиналов ради проверки SHA-256 может доминировать над числом объектов. RAM ограничена страницей и chunk 64 KiB,
но трафик и общее время не являются константными. Между страницами нет общего snapshot: проход eventually consistent,
новые записи/пропуски блокировок проверяются следующим запуском.
## Воспроизведение и отказы
```powershell
docker compose stop reconciler
docker compose run --rm --no-deps -T -v "${PWD}:/suite:ro" -w /suite api python student-tests/test_attachments.py
docker compose run --rm --no-deps -T -v "${PWD}:/suite:ro" -w /suite api python student-tests/test_reconcile.py
docker compose start reconciler
python student-tests/test_operations.py
python tests/resilience.py --mode persistence --action-script scripts/restart.cmd --base-url http://localhost:8084
python tests/resilience.py --mode failover --action-script scripts/stop-one.cmd --base-url http://localhost:8084
docker compose start api
docker compose up -d --no-deps --force-recreate api
python scripts/wait_ready.py --base-url http://localhost:8084 --replicas 2
python scripts/run_upload_load.py
.venv/Scripts/python scripts/plot_results.py
# Dry-run вручную:
docker compose run --rm --no-deps api python -m src.reconcile
```
Собственные suites создают данные; повтор увеличивает набор и меняет результаты времени, это не фиксированный golden benchmark.
Графики Matplotlib 3.10.7 построены из сохранённых JSON, PNG и SVG лежат в evidence/figures.
Отключённый сервис после ручных опытов следует восстановить; нагрузочный runner делает это в finally.
Подробности, включая временный DB trigger и восстановление после аварийного завершения suite: [student-tests/README.md](student-tests/README.md).
| Воздействие | Наблюдение | Сохранность / граница |
| --- | --- | --- |
| Остановлена lyakhonov-lab4-api-1 | Download через другую API за 1.286 с от начала действия | SHA-256 совпал, target реально остановлен |
| Остановлена lyakhonov-lab4-api-2 | Download через другую API за 1.406 с от начала действия | SHA-256 совпал, target реально остановлен |
| Остановка S3 | Первый 503 за 4.043 с | После восстановления прежние bytes/сессия; при исключении обеих API весь LB недоступен |
| Рестарт API/БД/Redis/S3/LB | StartedAt изменились у всех | Подтверждённые данные и прежний токен сохранены |
| PUT прошёл, INSERT отказал | 500 + orphan | Reconciler удалил после grace; слепой rollback S3 не применяется |
| Утрата/порча используемого оригинала | missing / API 503 | Метаданные/ссылки не удалены; нужен правильный оригинал из backup |
В ранних публичных failover-прогонах: 109 подтверждённых записей в каждом, 2 и 3 ошибки перехода,
первая успешная запись после начала hook через 2.439 и 2.442 с. Пользовательские операции не выдаются за мгновенный failover.
Публичный hook выбирает заданный процесс; отдельный test_operations доказывает остановку обеих именно загрузивших реплик.
## Ограничения и источники
Сверка обнаруживает утрату и возвращает состояние после восстановления из внешней копии, но не создаёт потерянные bytes из hash.
HTTP только localhost и синтетические данные.
Ключевые инварианты предполагают, что все писатели рабочего S3 namespace соблюдают общий протокол блокировки;
администратор с root credentials может его нарушить. Обрыв download после отправки headers может оборвать поток:
200 headers сами по себе не гарантируют полный файл, клиент проверяет длину/checksum.
Нагрузочные результаты зависят от Docker Desktop, CPU-квот, клиента и dataset; SLA и максимальные RPS не заявляются.
Добавлен отдельный application workflow без production secrets/privileged PR trigger.
Использованы собственная лабораторная 3 и материалы курса; FastAPI/Uvicorn/Pydantic, psycopg, Redis, Argon2, boto3/botocore,
Pillow (версии в requirements.lock.txt), Matplotlib для графиков. Реализация, проверки, анализ и отчёт подготовлены с помощью Codex.
Исходный контракт и публичные проверки преподавателя не ослаблялись.
Первичные источники: [Pillow Image / verify / pixel limits](https://pillow.readthedocs.io/en/stable/reference/Image.html),
[S3 PUT и условная запись](https://docs.aws.amazon.com/boto3/latest/reference/services/s3/client/put_object.html),
[LIST pagination](https://docs.aws.amazon.com/boto3/latest/reference/services/s3/paginator/ListObjectsV2.html),
[исходники MinIO](https://github.com/minio/minio/tree/07c3a429bfed433e49018cb0f78a52145d4bedeb),
[исходники mc](https://github.com/minio/mc/tree/RELEASE.2025-04-16T18-13-26Z),
[PostgreSQL advisory locks](https://www.postgresql.org/docs/16/explicit-locking.html#ADVISORY-LOCKS).
Этапы истории: `2e5f5bf` — перенос; `4f85fb9` — обязательный минимум; `9dded97` — уровень 4;
`6c87ed2` — трек 2, графики и отчёт; последующий коммит сохраняет проверку чистого экспорта и заключительный аудит.
Манифест source-файлов использует UTF-8/LF, чтобы перенос строк Windows/Linux не менял контрольные суммы.