Files
mtusi2026lab4/REPORT.md
T

33 KiB
Raw Permalink Blame History

Лабораторная 4 — Горбанюк, БВТ2301

Целевая оценка: 5, трек 2 «Согласованность двух хранилищ». Работа подготовлена для проверки. Название МР: ЛР 4 — БВТ2301 — Горбанюк — на 5. Проверенная версия отмечается lab4-verified. Окончательную оценку выставляет преподаватель, публичный smoke — только минимум.

Перенесена собственная реализация lab3: слои HTTP/domain/service/repository, сессии PostgreSQL, Argon2id, кэш Valkey, keyset-пагинация, две API за HAProxy, идемпотентные сообщения, отдельный migrate, action hooks. README, COURSE, CONTRIBUTING, contracts и публичные tests именно lab4 сохранены без изменений. Все заявленные результаты подтверждаются командами и evidence.

Публичный форк: https://gitea.privcloud.tech/Wemiliam/mtusi2026lab4. Ветка решения: solution/bvt2301-gorbanyuk, целевая ветка преподавателя — main. Ветка опубликована; МР преподавателю: https://gitea.privcloud.tech/mtusi2026/mtusi2026lab4/pulls/36.

Запуск из отдельного чистого clone

Нужны Docker Engine/Desktop + Compose v2, Git, Python 3.14.7 и uv 0.12.13. Go на host не нужен: S3-сервер и клиент собираются внутри Docker. Первая сборка требует доступа к реестрам, Python packages и Go modules и занимает заметное время. Повторные сборки используют слои/cache. Нужны свободные RAM/диск для компиляции и контейнеров; испытанный Docker-host: ARM64, 18 CPU, около 7.75 GiB RAM.

make bootstrap
uv sync --locked
make check
uv run --locked python scripts/validate_openapi.py
make up
make test

Адрес клиента: http://127.0.0.1:8084, только локальные синтетические данные. bootstrap создаёт новый случайный пароль PostgreSQL и отдельные S3 credentials для root/API/reconciler/tests в игнорируемом secrets/, создаёт .env; существующие значения не заменяет. Каталог 0700, файлы 0644 для non-root Compose secret mounts. Не переносить чужие .env/secrets из lab3: у этой работы собственные volumes/проект.

make up собирает образы, поднимает PostgreSQL и S3, выполняет отдельные migrate и bucket-init, затем API ×2/Valkey/HAProxy и ждёт readiness. Bucket-init идемпотентен: создание bucket с ignore-existing, запрет anonymous, повторное применение scoped policies/users с теми же локальными ключами. Все зависимости поднимаются здесь. Ни S3 API/console, ни PostgreSQL/Valkey, ни API напрямую в обычном compose не публикуются; единственный host-port — loopback HAProxy.

Для собственных тестов используется override. Он открывает только loopback PostgreSQL 55435, Valkey 56382 и S3 API 59004 и создаёт отдельные test bucket/identity:

docker compose --env-file .env -f compose.yaml -f compose.test.yaml up -d --build --wait
make test-student
make lint
make test-failover ACTION_SCRIPT=scripts/stop-one.sh
# Вернуть остановленную реплику:
docker compose --env-file .env up -d --no-build --wait
make test-persistence ACTION_SCRIPT=scripts/restart.sh

Тестовая БД создаётся/удаляется отдельно; test bucket не совпадает с основным. API основной системы не имеет credentials тестового bucket. Не запускать разрушительные ручные тесты/эксперименты против данных вне этого учебного проекта.

Полная проверка реальных контейнеров создаёт новые синтетические объекты:

make verify

По умолчанию получается новое evidence/cluster-.json. Для сохранённого запуска использовалось --output evidence/cluster.json. Проверяется stop каждой API по очереди, реальный CID/PID, сообщения, rolling replacement и полный restart включая S3. Восстанавливается остановленная реплика. Hook stop-one.sh требует TARGET_INSTANCE_ID, публичный resilience.py передаёт его сам.

Обычная остановка сохраняет PostgreSQL/S3 volumes:

make down

Намеренно удалить только учебные данные lab4, если они больше не нужны:

docker compose --env-file .env down --volumes

Скрипты не используют общий Docker prune и не останавливают другие лабораторные.

Дополнительно проверен отдельный чистый clone коммита 900182c: новые credentials, новые PostgreSQL/S3 volumes, сборка образа с OCI revision этого коммита, все 65 тестов, публичные smoke и persistence. Хеши всех runtime-модулей в образе совпали с исходниками clone и версией измерений. Временный стенд и только его новые volumes удалены; основные данные lab4 сохранены. Доказательства: clean-clone.txt, clean-clone.json. Workflow application.yml подготовлен, удалённый runner здесь не запускался.

Архитектура и версии

flowchart LR
    C[Client] --> LB[HAProxy :8084]
    LB --> A1[API 1]
    LB --> A2[API 2]
    A1 --> PG[(PostgreSQL: metadata, sessions, messages)]
    A2 --> PG
    A1 --> S3[(Private S3: original bytes)]
    A2 --> S3
    A1 --> V[Valkey: disposable User cache]
    A2 --> V
    R[Reconciler: dry-run/apply] --> PG
    R --> S3

Детальная схема/протокол и ограничения — SCHEMA.md. Новая миграция 003: Attachment, внутренний storage_state, связи с message; составные FK запрещают вложение из другого чата. Сервер назначает UUID key originals/, filename остаётся отображаемой строкой. Идентификация/ACL проверяются при upload, metadata, content и отправке сообщения. Участник может прикрепить вложение другого участника этого же чата. Посторонний получает 404. Публичный ответ не раскрывает object key.

Используется реляционная модель для связей/транзакций, объектное хранилище для байтов, stateless API и явный протокол восстановления. PostgreSQL — источник сессий, членства и результатов повторов. Кэш не даёт право доступа. Sticky sessions нет. Идемпотентность сообщения включает text и упорядоченные attachment_ids; отсутствующий список равен []. Message + links + результат ключа коммитятся вместе.

Версии: Python 3.14.7 (digest в Dockerfile), FastAPI 0.143.3, Pydantic 2.14.1, psycopg 3.3.6, Argon2id через argon2-cffi 25.1.0, boto3 1.43.109, Pillow 13.0.0. Точные транзитивные версии/hashes — uv.lock. PostgreSQL 18.3, Valkey 8.1.3-alpine, HAProxy 3.2.1-alpine. Образы S3 собираются из официального исходного релиза MinIO RELEASE.2025-10-15T17-29-55Z с исправлением CVE, mc — RELEASE.2025-08-13T08-35-41Z. Готовые upstream Docker Hub теги оказались недоступны, поэтому используется infra/s3.Dockerfile. Компилятор Go 1.26.7-alpine3.23 и runtime Alpine 3.23 закреплены digest. Community-репозиторий MinIO архивный: это воспроизводимая учебная версия, поддержка production здесь не заявляется. Go module source/tag и локальный image ID фиксируются в доказательствах, а не подменяются обещанием latest. Собранный через go install бинарник сообщает DEVELOPMENT.GOGET; это build label, а точная исходная pseudo-version/commit и SumDB hash извлечены из Go build info в s3-source-version.txt.

Миграции выполняются одной отдельной службой под advisory lock с checksum. API сам DDL не запускает. Миграции 001/002 не менялись. 003 добавляет схему вложений, но внешние wire-ответы lab4 изменились: старые lab3 API нельзя смешивать с lab4 за LB. Rolling здесь — последовательное пересоздание процессов тем же образом, с ожиданием готовности между шагами, не произвольное обновление бизнес-схемы.

Поток, безопасность и ограничение ресурсов

Upload — raw PNG/JPEG, не multipart. Auth/ACL, filename и Content-Length проверяются до чтения body. Опасные разделители, NUL/управляющие символы/суррогаты отклоняются. Внешний MIME должен совпасть с PNG/JPEG, обнаруженным Pillow. До полной распаковки проверяется площадь; verify и повторное load отсекают повреждённый поток. Байты никогда не перекодируются, SHA-256 считается инкрементально.

На API одновременно обрабатывается один upload, остальные ждут до 5 s, потом 429. Сам поток ограничен 15 s и фактическими 10 485 760 bytes; объявленному Content-Length без проверки не доверяем. 40 000 000 пикселей проверяются до load. Анонимный временный файл находится в tmpfs 32 MiB и закрывается при успехе, ошибке или отключении клиента. Это scratch, от него не зависит доступность файла после 201. RAM декодера зависит от ограниченной площади, не только сжатых bytes; один слот не даёт десяти декодерам одновременно занять память одной API.

Boto3 выполняет один PutObject ≤10 MiB: multipart transfer/автоматических retries нет, connect timeout 0.5 s, socket read timeout 2 s. Повтор сообщения защищён Idempotency-Key, повтор upload может создать новое вложение. SDK/SQL/декодирование выполняются вне event loop. Download передаёт 64 KiB chunks через API с ACL, Content-Length, истинным Content-Type, безопасным Content-Disposition и nosniff; redirect в S3 нет. Клиент проверяет итоговый SHA. Разрыв stream после начала ответа нельзя превратить в JSON-ошибку задним числом: такой GET нужно повторить.

API: 1 CPU / 512 MiB, readonly filesystem, UID 10001, cap_drop ALL, tmpfs 32 MiB, один Uvicorn worker. PostgreSQL: 1 CPU / 768 MiB; S3: 1 CPU / 768 MiB; Valkey: 0.5 CPU / 128 MiB; LB: 0.5 CPU / 128 MiB. API swap сверх лимита запрещён. API не публикует порт и не имеет container_name. Пулы/SQL timeout сохранены из lab3. SIGTERM: Uvicorn перестаёт принимать соединения, grace 5 s, Compose ждёт 7 s. Не подтвердившийся upload оставляет pending, который восстановит сверка.

HAProxy: round-robin, readiness каждые 500 ms, fall 2/rise 1, connect/check 500 ms, Docker DNS обновляется с hold valid 1 s; адреса не зашиты. LB client timeout 20 s, server timeout 30 s учитывают bounded upload. Readiness требует PostgreSQL и S3; при отказе S3 LB может временно исключить все API. Valkey не критичен.

Приватность/права: API identity умеет Get/Put только в originals/ основного bucket, List/GetLocation только этого bucket для readiness. Нет DeleteObject, bucket/admin операций или доступа к чужому bucket. Reconciler имеет List/Get/Delete своего prefix, без Put. Root передан только S3/bootstrap. Консоль привязана к loopback внутри S3-контейнера и не опубликована. Отдельный test identity ограничен test bucket. Secret values отсутствуют в Git, образах, evidence и логах; локальные secret mounts не заменяют защиту Docker-host и secret manager удалённого окружения.

Согласованность и сверка: трек 2

201 возвращается после PUT и COMMIT ready. До PUT уже есть устойчивый pending. Это не двухфазный COMMIT между S3 и PostgreSQL. При отключении клиента до конца body не создаются ни intent, ни S3 объект; после intent любой неясный исход остаётся учтённым. Сверка отдельно восстанавливает запись или удаляет брошенное намерение.

make reconcile                 # только dry-run
# Изменения включаются явно:
docker compose --env-file .env run --rm reconciler python -m messenger.reconcile --apply --grace-seconds 300

Grace не может быть меньше 300 s. CLI работает постранично (S3 до 1000 объектов, PostgreSQL до 100 строк), preview до 100 actions, counters полные. Один reconciler на БД благодаря advisory lock, исправляемые строки блокируются FOR UPDATE.

Обнаружено Безопасное исправление после grace
Старый orphan нашего UUID-prefix без metadata Повторный HEAD, проверка ETag/size/возраста, DELETE только этого объекта
Старый pending, PUT сохранил правильный объект ready; checksum/size/MIME сверяются с намерением
Старый pending, подтверждённое 404 объекта, нет links Удаление брошенного намерения
Ready, объект пропал/не соответствует metadata missing, metadata и Message links сохраняются; API выдаёт 409
Missing, правильный оригинал восстановлен оператором ready, тот же ID и связи
Свежие объекты/намерения, ready с/без Message links Не удаляются
Сетевой сбой, 403, 5xx Проход завершается ошибкой, это не отсутствие объекта
Неожиданные bytes у pending Review action, автоматическое удаление запрещено

S3 LIST и HEAD имеют разную точность даты. Проверяется возраст обеих наблюдаемых записей и ETag/size, а не точное равенство LastModified. ETag используется как проверка неизменности, не как SHA оригинала. Приложение не переиспользует ключи. Сторонний writer с правом overwrite не должен менять originals/ во время сверки.

В dry-run нет изменений данных. Повтор apply сходится к отсутствию новых actions. При ошибке часть независимых исправлений могла уже закоммититься; запуск можно повторить. Потерянные bytes нельзя восстановить из SHA: для фактического восстановления нужна исходная копия/backup. Сверка проверяет HEAD metadata, а не перехеширует весь bucket; сквозные проверки отдельно скачивают оригинал и считают SHA.

Команды исследований и критерии

Для проверки настоящего orphan нужен его реальный возраст ≥300 s, часы S3 не подменяются. Сначала создать seed, затем выполнять прочие проверки:

uv run --locked python scripts/verify_storage.py --seed evidence/storage-seed-new.json
make test-student
make verify
# Когда LastModified seed старше 300 s:
uv run --locked python scripts/verify_storage.py --seed-file evidence/storage-seed-new.json --output evidence/storage-new.json
uv run --locked --group research python research/analyze.py evidence/storage-new.json

Сохранённый запуск разбит на базовые проверки и продолжение после aging (--resume-basics evidence/storage-basics.json); memory/cost повторены отдельно на финальном образе без параллельного запуска тестов. Итоговый набор — storage.json. Скрипт отказывается перезаписывать output. Для графиков сохранённой серии analyze.py читает evidence/storage.json. Raw содержит cgroup readings, времена каждой загрузки, CID/alias и counters/время всех проходов сверки, без токенов.

Критерий Проверка Доказательство
Исходный skeleton/OpenAPI make check; validate_openapi contracts.txt
Весь API lab4 и прежние возможности make test; make test-student smoke.txt, student-tests.txt
PNG/JPEG, MIME, лимиты, ACL, чужой chat/id 65 собственных тестов с настоящими PG/S3 test_attachments.py
Байты с другой API после stop загрузившей cross_replica в verify_storage storage.json
Сохранность metadata/bytes/session при restart публичный persistence, StartedAt PG/Valkey/S3/LB persistence.txt, cluster.json
Каждая API, идемпотентность, rolling make verify cluster.json
Приватный bucket и ограниченный API user анонимный GET 403, Delete/other bucket 403 storage.json
Прерванный body / отказ S3 raw TCP abort; реальный stop/start S3 storage.json
PUT прошёл, DB finalize упал; PUT не прошёл injected failure между шагами, dry-run/apply/repeat test_attachments.py
≥10 загрузок, bounded RAM барьер 10 клиентов, два размера, kernel memory.peak storage.json
Orphan/missing, свежие/used защищены реальный aged orphan, удаление used bytes, восстановление storage.json
Стоимость обхода 0/100/1100 дополнительных объектов, 3 dry-run повтора storage.json

Наблюдаемые результаты

65 собственных тестов и публичный smoke прошли. Публичные persistence/failover сохранили прежнюю сессию и оригинал; реальный S3 stop дал два 503, после start тот же файл снова скачался. Консоль недоступна из API, повторный bucket bootstrap дважды завершился успешно с теми же credentials и данными.

Серия загрузок Клиенты Успешные RPS p50/p95/p99, ms Максимум memory.peak одной API, MiB Ошибки
1,081,015 bytes, 360,000 pixels 10 58.07 121.6/159.4/159.4 162.77 0
8,674,572 bytes, 2,890,000 pixels 10 13.52 500.3/726.9/726.9 163.62 0

Средняя суммарная загрузка CPU двух API по delta cgroup cpu.stat: 0.58 ядра, 0.91 ядра для малого/большого payload. Окно включает probes чтения счётчиков и служебные процессы после readiness; это короткая усреднённая оценка, не CPU p95. Raw cpu.stat сохранён в before/after каждой серии.

Kernel peak около 163 MiB при лимите 512 MiB. Он включает startup (в том числе Argon2id) и является верхней границей за весь trial. Из близости двух peak не следует, что размер файла не влияет на RAM: эксперимент не отделяет пик startup от пика декодирования. Файлы больше проверенных размеров, но в пределах 10 MiB/40 млн pixels, покрыты лимитами реализации; их полная матрица RAM не измерялась.

Дополнительные fresh S3 objects dry-run min / median / max, ms LIST pages
0 137.78 / 141.20 / 184.41 1,1,1
100 150.60 / 163.01 / 166.15 1,1,1
1100 189.81 / 216.18 / 233.53 2,2,2

Настоящий orphan был выдержан 503.0 s. Dry-run обнаружил его и брошенный intent, но не изменил S3/БД; apply удалил ровно эти объекты, повторный apply вернул пустой actions. Свежий orphan сохранён. Для used-вложения после удаления bytes dry-run показал mark_missing без изменения metadata; apply сохранил ID и Message link и перевёл запись в missing. После возврата правильных bytes следующий проход вернул ready, download снова совпал с fixture. Это подтверждённое улучшение протокола: сбой между двумя хранилищами больше не оставляет незаметный вечный orphan/pending; он обнаруживается и сходится к явному состоянию. Это не обещание восстановления без исходных bytes.

Воздействие API Успешные RPS Ошибки/попытки Успех после hook, s p95, ms
Остановка API 1 421.2 167/2615 2.225 31.2
Остановка API 2 334.3 153/1964 1.819 44.8
Rolling replacement 432.3 287/7903 13.610 47.9

Каждая остановка укладывается в 10 s; подтверждённые сообщения сохранены. first_success_after_action_seconds отсчитывается от старта hook до первого успеха после его завершения, это не длительность сплошного простоя. Другая API может отвечать в течение hook. В stopped хранится паспорт процесса до stop; скрипт отдельно проверяет running=false. Проверка cross_replica сохраняет также фактический after_stop с running=false и alias другой скачавшей API.

RAM загрузок и стоимость сверки

CPU/RAM лимиты проверялись inspect. Kernel memory.peak включает Python, decoder, tmpfs, page cache и startup; это не process RSS и не усреднение Docker stats. Каждый размер испытывался одной серией из 10 клиентов, API пересоздавались до серии. Десять клиентов не означают десять одновременных декодеров: именно gate ограничивает активную обработку, остальные ждут, все десять завершились успешно. Короткие локальные измерения не являются production capacity/SLO.

Стоимость сверки измерена при неизменном числе metadata и росте числа свежих S3 objects. Это проверяет paging и постоянные накладные расходы; масштабирование по числу metadata отдельно не измерялось. LIST стоит O(objects/1000), индексированный DB lookup нужен для старых объектов, HEAD — для старых metadata. Нет вывода, будто полное чтение/хеширование всех bytes столь же дёшево. Три повтора дают min/median/max, не статистический доверительный интервал. Обе API и health probes работают во время замеров, остальные тесты/сборки не запускаются.

Вопросы на защите

Почему Docker volume одной API не равен S3? Локальный файл зависит от выбранного host/контейнера и не появляется у соседней реплики. S3 — общий адресуемый сервис с object key, API хранения и отдельными правами. Временный tmpfs здесь нужен только во время запроса; после 201 оригинал читается из общего S3, что проверено остановкой uploading process. S3 volume тоже нуждается в защите от отказа диска/host.

Когда честно вернуть 201? Когда bytes полностью приняты, проверены, PUT успешно подтверждён и metadata ready закоммичена. Возвращать 201 после помещения в локальную память нельзя. В lab5 будет другой контракт: 202 после устойчивого staging и надёжного сохранения намерения обработки; ready появится позже.

PUT прошёл, а COMMIT — нет? Два хранилища не откатываются одной SQL-транзакцией. До PUT уже сохранён pending, поэтому объект не теряется из учёта. После grace reconciler сверит key/checksum/size/MIME и восстановит ready. Если Put не дошёл, старый пустой intent удалится. Если metadata вообще нет, старый orphan удаляется после дополнительной проверки. HTTP timeout сам по себе не доказывает rollback.

Почему случайный key/private bucket не заменяют ACL? Случайность — защита от угадывания, приватность — от анонимного S3. Любой участник приложения всё равно может знать ID чужого вложения. Только проверка действительной сессии и членства в конкретном чате на metadata/content/message запрещает чужой доступ. Автор выводится из сессии, filename/key не используются как доказательство прав.

Ограничения и продолжение

Защищён отказ одной API, но host/LB/PostgreSQL/MinIO и их диски остаются SPOF. Backup/PITR/репликация storage не заявляются. Это локальный HTTP-стенд с вымышленными данными; удалённая демонстрация потребует TLS. Presigned upload (трек 1) не реализован. Готовые неиспользованные вложения сохраняются; политики удаления истории нет. Для неожиданного несовпадения pending требуется оператор, оно явно видно в report. Reconciler запускается вручную по команде; для регулярной эксплуатации его нужно запускать по расписанию, вечное автоматическое исправление без запуска не обещается.

В lab5 появятся устойчивое staging, outbox/job, брокер и worker. Объекты очереди будут ссылками, не bytes. Потребуются lease/retry и защита активной обработки от GC; обязательный thumbnail будет отдельным вариантом. Lab4 останется независимым проверенным репозиторием, его контракт 201 ready не меняется будущей работой.

Источники

Соответствие ревизий

После редактуры отчёта, шаблона и служебных метаданных сохранено соответствие прежних и текущих Git-ревизий: revision-map.json. Код приложения, миграции, зависимости, Dockerfile, конфигурация сервисов и исходные публичные проверки не изменены. Численные результаты и исторические image/source identifiers в evidence сохранены в исходном виде; их не следует трактовать как новый запуск измерений.