145 lines
18 KiB
Markdown
145 lines
18 KiB
Markdown
# Отчёт — лабораторная 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. Проверки кода опираются на сохранённые версии зависимостей и реальные ответы стенда.
|