18 KiB
Отчёт — лабораторная 4
Васильев Никита, БВТ2301. Целевая оценка: 5. Трек 2 — согласованность двух хранилищ.
Локальное выполнение без публикации PR. Отдельный application workflow описывает build/readiness/smoke/own tests на изолированной hosted VM; удалённый CI в рамках этой работы не запускался. Оригинальные README, COURSE, CONTRIBUTING, contracts и публичные tests сохранены. Собственный код ЛР3 перенесён в отдельный skeleton ЛР4; добавлены вложения и исследование согласованности. Использована помощь ИИ при реализации, тестировании и подготовке отчёта. Замечания преподавателей изучены заранее, ссылки и регрессии — в REVIEW_NOTES.md. Код и чужие измерения не заимствованы.
Запуск из чистого clone
Нужны Docker Engine с Compose v2, Python 3.12 и uv, make. Для публичных тестов достаточно системного Python 3.9+. API и все хранилища запускаются из этого репозитория; ручная установка PostgreSQL/S3 не нужна.
uv sync --locked --python 3.12
make up
make check validate PYTHON=.venv/bin/python
make test
make student-test
make up создаёт локальные секреты один раз, сохраняет существующие значения, собирает образ, ждёт PostgreSQL, применяет миграции и идемпотентно создаёт приватный bucket. Затем запускаются две API-реплики и HAProxy. На хост опубликован только 127.0.0.1:8084 балансировщика; API и storage напрямую не публикуются.
Обычная остановка с сохранением данных:
make down
Намеренное удаление учебных данных выполняется отдельно командой docker compose down --volumes; она не нужна для restart и не применяется к основному стенду при проверке сохранности.
Полная проверка рестарта и отказа одной API:
make test-persistence ACTION_SCRIPT=scripts/restart.sh
make test-failover ACTION_SCRIPT=scripts/stop-one.sh
docker compose up -d --wait --no-recreate
После восстановления первой реплики failover повторяется для другой. Hook использует TARGET_INSTANCE_ID, читает действительный alias процесса и останавливает соответствующий контейнер. Сопоставление alias/контейнера и timestamps до/после фиксируются в evidence.
Переменные: PUBLIC_PORT=8084, API_REPLICAS=2, API_CPUS=0.5, API_MEMORY=512m, POOL_MAX_SIZE=8, SESSION_TTL_SECONDS=3600. DSN, S3 access/secret keys читаются из файлов Compose secrets; app и admin keys разделены. .env, secrets и volumes не находятся в Git. .env.example содержит поддерживаемые переменные и комментарии с фиксированными внутренними адресами; реальные секреты генерирует scripts/bootstrap.py. Изменение S3 bucket/endpoint требует согласованного изменения Compose и bucket-scoped identity, а не только строки в .env.
Версии и ограничения ресурсов
- Python 3.12, Python-зависимости закреплены в uv.lock (FastAPI 0.162.0, Pillow 12.3.0, boto3/botocore 1.43.125 и прочие).
- Python base закреплён digest, uv в Docker 0.11.7. Native decoder libjpeg-turbo-progs 1:2.1.5-4 закреплён явно.
- PostgreSQL 17.10-alpine: 1 CPU, 768 MiB, durable WAL settings включены.
- Valkey 8.1.3-alpine: 0.5 CPU, 128 MiB; кэш публичных пользователей, не сессий.
- HAProxy 3.2-alpine закреплён digest: 0.5 CPU, 128 MiB; stream forwarding без полного буферирования тела.
- SeaweedFS 4.15 закреплён digest: backend 1 CPU/512 MiB, S3 gateway 0.5 CPU/256 MiB.
- Каждая API: 0.5 CPU/512 MiB, один worker, non-root UID10001, read-only FS, tmpfs16MiB, drop capabilities, no-new-privileges.
При первоначальном переносе bytea-миграция несовместима со старым runtime ЛР2: такой переход требует maintenance window. Поочерёдная замена одинаковой версии с уже применённой схемой не требует повторной миграции.
Архитектура и источник истины
Клиент → HAProxy → API × 2 → PostgreSQL (сессии/данные/метаданные/intent)
↘ Valkey (кэш публичных карточек пользователей)
↘ S3 gateway → Seaweed backend (bytes)
Seaweed backend подключён только к отдельной storage_backend internal network. API к ней не подключается: filer/master/volume интерфейсы недоступны из общей API-сети. S3 gateway подключён к обеим сетям и предоставляет только S3-интерфейс на общей сети; публичных host ports у него нет. Admin identity присутствует только у gateway и bootstrap/research, API получает bucket-scoped Read/Write/List identity.
Readiness проверяет обязательные таблицы и столбцы PostgreSQL запросом WHERE false, затем доступность S3 bucket. Простого SELECT 1 недостаточно для обнаружения отсутствующей схемы.
Ни случайный UUID, ни приватный bucket не заменяют ACL: метаданные и content выдаются только после проверки PostgreSQL-сессии и членства в чате. Сессии не кэшируются. Валидный токен не открывает чужой чат. Оригинал скачивается через авторизованный API без redirect.
Сообщения сохраняют порядок attachment_ids в message_attachments.position. Идемпотентность из ЛР3 атомарно сохраняет сообщение, связи и точный ответ; перестановка вложений при том же ключе считается другим body. Пропущенный attachment_ids и [] эквивалентны. UTF-8 поля сообщений/имён хранятся lossless в bytea, включая NUL, который PostgreSQL text не принимает.
Upload и download
- Проверяются сессия, чат, filename, MIME.
- Тело читается частями в spool: первые 256 KiB в RAM, далее временный файл в ограниченном tmpfs. Максимум 10 MiB, таймаут чтения 15 секунд.
- По одному upload slot на API, лишняя работа получает 429/Retry-After. Размеры изображения проверяются до decode: максимум 40 млн пикселей.
- Pillow verify и повторный полный load проверяют PNG/JPEG. Для JPEG djpeg -strict дополнительно отклоняет недодекодируемые изображения, которые Pillow может принять с предупреждением; timeout5s, maxmemory192m.
- После полной валидации фиксируется durable upload_intent. Под его row lock выполняются S3 PUT и транзакция ready metadata + удаление intent.
- Только успешное завершение COMMIT даёт 201 ready с variants=[] и error_code=null. SHA-256/size/MIME относятся к исходным bytes.
Filename не используется в object key. Отклоняются slash, backslash, все Unicode Cc (включая C0, C1 и DEL), пустые/пробельные имена и длина вне1..255. MIME сравнивается с фактическим PNG/JPEG. Download получает S3 stream заранее и отдаёт части по64KiB; отсутствие variant у ready возвращает404, failed content409. Ошибка S3 до начала ответа переводится в503. Если сеть оборвётся после отправки HTTP headers, клиент увидит оборванный поток и должен проверить размер/checksum.
Прерванный HTTP приём закрывает spool и освобождает slot до создания intent/объекта. Неопределённый COMMIT не приводит к немедленному удалению S3: возможно, ready уже зафиксирован. Остатки очищаются сверкой после grace.
Согласованность и исследование на 5
Подробная гипотеза, окна отказа и команды находятся в research/README.md.
Reconciler по умолчанию dry-run. Явный apply может удалять старые orphan objects и завершать очистку abandoned intent; live intent защищён row lock, свежие bytes — независимой проверкой LastModified. Перед мутацией выполняется актуальный HEAD, не используется только старый LIST snapshot. Пропавший оригинал старой ready metadata помечается failed/storage_missing, но запись и связи сообщений сохраняются. Валидные ready вложения не удаляются даже без сообщения.
# Обычная сверка основного стенда — без изменений:
docker compose run --rm --no-deps api python -m messenger.reconcile
# Явное исправление после просмотра dry-run:
docker compose run --rm --no-deps api python -m messenger.reconcile --apply --grace-seconds 3600
# Изолированное исследование в новых временных БД и bucket:
docker compose run --rm --no-deps research
Проверяются реальные PG INSERT failure после PUT, ошибка подключения S3, потеря подтверждения после успешного COMMIT, PG DELETE failure после удаления S3, повторный dry-run после частичного удаления, S3 delete failure/recovery, fresh orphan, old intent с fresh bytes, live writer lock, missing used metadata. Временные исследовательские ресурсы удаляются в finally, рабочая messenger не очищается.
Стоимость обхода измеряется на10/100/1000 добавленных intact attachments, по3 dry-run, page_size100. Перед измерением все добавленные объекты выдерживаются за границу grace, чтобы fresh-skip не менял профиль работы. Точные размеры с учётом сохранённых fault fixtures находятся в JSON. Измеряются время и количество просмотренных объектов/метаданных; это SQL+S3 обход, не HTTP throughput.
Результат исследовательского прогона
reconcile-study.json содержит 30 успешных проверок, девять замеров обхода и hashes runtime. Первый apply удалил остатки двух старых intent и orphan, пометил один missing original failed; повтор не сделал новых изменений. Проверены также ошибка DELETE после удаления bytes и последующий read-only dry-run. Временные БД и bucket удалены.
| Добавлено intact | Фактически просмотрено metadata | Медиана трёх обходов |
|---|---|---|
| 10 | 13 | 0,018528 с |
| 100 | 103 | 0,126891 с |
| 1000 | 1003 | 1,684725 с |
Рост близок к росту числа HEAD/SQL round trips. Это локальная стоимость консервативного обхода; нет утверждения о линейности для любой БД/сети. Помимо добавленных строк остаются три intact fault fixtures; missing failed исключён из ready scan.
Результат десяти конкурентных upload
После рестарта API с сохранением старого токена проверены PNG 788100 и 8683594 байт. На каждом размере десять клиентов начали одновременно; 2 получили 201, 8 — контролируемый 429, затем readiness200. У API и LB oom=0, oom_kill=0, процессы остались живы. Cgroup lifetime peaks: API 130342912 и130285568 байт, LB18243584 байт. Лимиты соответственно512/512/128MiB.
Before/after peaks не выросли: начальная загрузка приложения/Argon2 уже создала больший high-water. Поэтому опыт доказывает ограниченное поведение выбранной нагрузки без OOM, но не выделяет точную память одной загрузки и не доказывает экономию RAM самим spool.
Проверки и доказательства
| Критерий | Сценарий | Доказательство |
|---|---|---|
| Контракт и схема | make check validate | evidence/contract-checks.txt |
| Обязательный API, PNG/ACL/checksum/idempotency | make test | evidence/smoke-strict.txt |
| Негативные/параллельные/Unicode/вложения | make student-test | evidence/tests-strict.txt: 88 passed |
| Повреждённый JPEG с поддельным EOI | regression до исправления и полный тест после djpeg | evidence/attachments-before-strict-jpeg.txt; evidence/tests-strict.txt |
| Независимая проверка реального HTTP | root external regression | Отдельная итоговая проверка общего пакета |
| Десять одновременных upload | research/upload_memory.py | evidence/upload-memory-final.json |
| Reconciler/fault-injection/стоимость | tools profile research | evidence/reconcile-study.json |
| Сохранность/переключение/отказы | публичные resilience + собственные реальные stop/pause | Итоговые evidence persistence/failover/storage-checks |
Ограничения
- Один host, LB, PostgreSQL и Seaweed backend остаются точками отказа; две API-реплики не создают HA всех зависимостей.
- Сверка может пометить потерянные bytes failed, но не восстановить их без backup. Здесь не настраивается внешнее резервное копирование S3.
- Нет распределённого COMMIT через PostgreSQL и S3: остатки допустимы до grace/apply. Уникальные immutable server keys и intent делают выбранную очистку безопасной для штатного API; конкурентное ручное изменение администратором после HEAD находится вне этой гарантии.
- Очереди обработки изображений нет: ЛР4 синхронная, thumbnail/crop/optimized относятся к ЛР5.
- HTTP допустим для локального изолированного стенда с синтетическими данными. Удалённая передача секретов требует TLS.
- Native decoder/libjpeg ограничен memory/time/cgroup; полная корректность каждого экзотического изображения зависит от библиотечного декодера. Специально проверены конкретные повреждения из замечаний преподавателя.
- Client-side deadline ограничивает ожидание одного обращения к PostgreSQL, а не весь HTTP-путь; при неопределённом результате записи ключ идемпотентности защищает повтор сообщения. Upload не имеет такого ключа и не должен автоматически повторяться как будто это тот же объект.
Источники
Оригинальные contracts/README и OpenAPI текущего skeleton, Docker Compose reference, документация PostgreSQL/psycopg, boto3 S3 client и SeaweedFS S3 configuration, Pillow Image API и libjpeg-turbo djpeg. Проверки кода опираются на сохранённые версии зависимостей и реальные ответы стенда.