Files
mtusi2026lab4/REPORT.md
T

145 lines
18 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. Целевая оценка: 5. Трек 2 — согласованность двух хранилищ.**
Локальное выполнение без публикации PR. Отдельный application workflow описывает build/readiness/smoke/own tests на изолированной hosted VM; удалённый CI в рамках этой работы не запускался. Оригинальные README, COURSE, CONTRIBUTING, contracts и публичные tests сохранены. Собственный код ЛР3 перенесён в отдельный skeleton ЛР4; добавлены вложения и исследование согласованности. Использована помощь ИИ при реализации, тестировании и подготовке отчёта. Замечания преподавателей изучены заранее, ссылки и регрессии — в [REVIEW_NOTES.md](REVIEW_NOTES.md). Код и чужие измерения не заимствованы.
## Запуск из чистого clone
Нужны Docker Engine с Compose v2, Python 3.12 и uv, make. Для публичных тестов достаточно системного Python 3.9+. API и все хранилища запускаются из этого репозитория; ручная установка PostgreSQL/S3 не нужна.
```sh
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 напрямую не публикуются.
Обычная остановка с сохранением данных:
```sh
make down
```
Намеренное удаление учебных данных выполняется отдельно командой `docker compose down --volumes`; она не нужна для restart и не применяется к основному стенду при проверке сохранности.
Полная проверка рестарта и отказа одной API:
```sh
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. Поочерёдная замена одинаковой версии с уже применённой схемой не требует повторной миграции.
## Архитектура и источник истины
```text
Клиент → 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
1. Проверяются сессия, чат, filename, MIME.
2. Тело читается частями в spool: первые 256 KiB в RAM, далее временный файл в ограниченном tmpfs. Максимум 10 MiB, таймаут чтения 15 секунд.
3. По одному upload slot на API, лишняя работа получает 429/Retry-After. Размеры изображения проверяются до decode: максимум 40 млн пикселей.
4. Pillow verify и повторный полный load проверяют PNG/JPEG. Для JPEG djpeg -strict дополнительно отклоняет недодекодируемые изображения, которые Pillow может принять с предупреждением; timeout5s, maxmemory192m.
5. После полной валидации фиксируется durable upload_intent. Под его row lock выполняются S3 PUT и транзакция ready metadata + удаление intent.
6. Только успешное завершение 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](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 вложения не удаляются даже без сообщения.
```sh
# Обычная сверка основного стенда — без изменений:
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](evidence/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. Проверки кода опираются на сохранённые версии зависимостей и реальные ответы стенда.