Files
mtusi2026lab4/STUDENT_REPORT.md
2026-11-12 19:56:00 +03:00

201 lines
19 KiB
Markdown
Raw Permalink 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 «Согласованность двух хранилищ»; обязательный минимум и уровень 4 сохранены.
- Использованы исходное задание lab4, контракт и публичные проверки предоставленного skeleton.
## Запуск из чистого клона
```sh
python3 scripts/setup-env.py
docker compose config --quiet
docker compose up -d --build --wait
python3 tests/smoke.py
python3 -m venv .venv
.venv/bin/python -m pip install -r requirements-student.txt
make -f student.mk verify-lab4 PYTHON=.venv/bin/python
```
Генератор создаёт локальный `.env` с новыми hex-паролями и правами 0600, значения
не печатает, существующий файл не перезаписывает. Для обновления сохранить прежние
пароли и volumes. Если ранее owner MinIO был записан в `S3_ACCESS_KEY_ID` /
`S3_SECRET_ACCESS_KEY`, перенести его в `MINIO_ROOT_USER` / `MINIO_ROOT_PASSWORD`,
а для API задать отдельного пользователя. Для стенда с прежними значениями по
умолчанию перенос не нужен. Уже существующий пароль администратора не меняется автоматически.
`docker compose down` сохраняет данные. `docker compose down --volumes` — отдельная
команда осознанного удаления учебных данных; сценарии сохранности её не используют.
Clean-start удаляет только собственный UUID-проект с временными volumes.
Версии закреплены: Python 3.13.0, PostgreSQL 16.6-bookworm, Redis 7.4.2-bookworm,
HAProxy 3.0.12-alpine, SQLAlchemy 2.0.44, asyncpg 0.30.0, Alembic 1.17.0,
minio-py 7.2.20, Pillow 13.0.0. MinIO community собирается из commit
`9e49d5e7a648f00e26f2246f4dc28e6b07f8c84a` релиза RELEASE.2025-10-15T17-29-55Z;
готовый официальный образ не требуется. Первый build занимает несколько минут.
## Архитектура и данные
Клиент → HAProxy → API × 2 → PostgreSQL + Redis + приватный MinIO.
Отдельный reconciler обращается к PostgreSQL и S3; bootstrap и migration —
завершающиеся задачи до запуска API. Публикуется только `127.0.0.1:8080` LB;
у API, PostgreSQL, Redis и MinIO нет опубликованных портов. Консоль S3 выключена.
| Компонент | Назначение | Постоянные данные / права |
| --- | --- | --- |
| PostgreSQL | Пользователи, чаты, сообщения, Attachment, идемпотентность, журнал и наблюдения | postgres_data |
| Redis | Сессии с абсолютным expiry, AOF appendfsync always, кэш профиля | redis_data; TTL после рестарта не продлевается |
| MinIO | Неизменённые оригиналы PNG/JPEG | minio_data; приватный bucket messenger-attachments |
| API | Авторизация, проверка картинок, синхронный upload и авторизованный download | Get/Put своего префикса; нет удаления и администрирования S3 |
| Reconciler | Обнаружение orphan/missing и повторяемые исправления | List/Get/Delete своего bucket/prefix; нет PutObject и admin |
| Migration / bootstrap | Миграции до 008, bucket, пользователи и политики | Owner credentials только в bootstrap/MinIO |
Обязательная основа API включает Bearer-сессии, PostgreSQL/Redis, два API за LB, X-Request-Id,
X-Instance-Id, пагинация, доступ к чатам и атомарная идемпотентность на 24 часа.
Идемпотентность теперь сравнивает текст и упорядоченный список вложений.
Миграция 007 создаёт `attachments` и `message_attachments`, разрешает пустой текст
при вложении. Связи с чатом защищены составными FK. Позиции 0–9 с UNIQUE на сообщение
ограничивают число файлов десятью, повтор ID запрещён. Вложение можно повторно
использовать в сообщениях того же чата. Миграция 008 добавляет `upload_intents`,
`storage_findings` и внутреннюю отметку `storage_missing_since`.
S3 object key назначает сервер, filename используется только для отображения.
API отдаёт оригинал побайтно, без redirect и перекодирования. MIME сравнивается
с определённым форматом; проверяются целостность и декодирование после раннего
лимита в 40 млн пикселей. Ограничение тела — 10 MiB, включая chunked-передачу.
Приём ограничен временем и параллелизмом; декодирование — одно на API-процесс.
Временный файл находится в tmpfs 64 MiB и закрывается после запроса. Скачивание
читает S3 порциями. Метаданные не раскрывают внутренний ключ или credentials.
## Согласованность PostgreSQL и S3
До PUT отдельным COMMIT фиксируется pending-намерение. Перед PUT загрузчик берёт
транзакционный advisory lock на ключ и повторно проверяет состояние. Он удерживает
блокировку до общего COMMIT Attachment и committed-намерения. Только после этого
возвращается 201 ready. При обрыве клиента до PUT постоянного объекта ещё нет.
Reconciler каждые 300 секунд перечисляет только наш bucket под originals/ с
пагинацией ListObjectsV2. На ключ берёт неблокирующий advisory lock: занятый
пропускается. Attachment защищает файл даже без сообщения. Старый pending без
Attachment закрывается; бесхозный объект удаляется после проверки возраста
объекта/намерения. Запас — 300 секунд, настраивается. Дополнительного ожидания
после первого обнаружения нет.
Ошибка DELETE не фиксируется как завершённая очистка: транзакция откатывается,
объект остаётся кандидатом при следующем проходе. Потерянный ответ DELETE также
безопасен для повторного запуска. При неизвестном результате COMMIT файл немедленно
не удаляется — это мог бы быть оригинал уже подтверждённого вложения.
Обратный проход HEAD обнаруживает Attachment без оригинала. Сообщения, связи и
метаданные сохраняются, чтение получает 503, новые ссылки — 409. Повтор уже
подтверждённого сообщения сохраняет прежний результат идемпотентности. После
восстановления файла размер и фактический SHA-256 должны совпасть. ETag не заменяет
SHA-256. Бесследное восстановление байтов из метаданных не обещается: нужна копия.
Dry-run выполняет проверки без записей и удаления. Apply перепроверяет условия
под блокировкой; параллельные изменения учитываются. Недоступность БД/S3, AccessDenied
или потеря bucket прерывают проход, а не объявляют все файлы отсутствующими.
Алгоритм, команды и ограничения подробно описаны в `LAB4_RECONCILIATION.md`.
## Готовность и ограничение ожидания
Liveness проверяет процесс. Readiness проверяет схему PostgreSQL, Redis и bucket;
бюджет ответа — 2 секунды, незавершённая отмена драйвера не задерживает HTTP.
Обычные бизнес-запросы имеют бюджет 5 секунд до заголовков. Таймаут не ждёт
зависшего rollback: обработчик отменяется, его слот сохраняется до реального
завершения. Предел незавершённых обработчиков — 64 на процесс. Это ограничивает
накопление работ при замороженной БД. Upload имеет отдельный бюджет приёма 30 секунд
и суммарный предел до заголовков 45 секунд; сокеты S3 ограничены 5 секундами.
Исправление проверено на действительно выполняющемся запросе: сначала история
удерживается SQL-блокировкой messages, наличие ожидающего SELECT подтверждается
через pg_stat_activity, затем PostgreSQL замораживается. История возвращает 503
примерно за 5 секунд, readiness — за 2 секунды; после unpause оба восстанавливаются
без перезапуска API. Одна проверка подключения не доказывала бы этот сценарий.
## Доказательства критериев
| Критерий | Повторяемая проверка | Результат / доказательство |
| --- | --- | --- |
| Контракт и прежнее API | make -f student.mk check validate; tests/smoke.py | lab4-final-structure/openapi/public-smoke.txt |
| PNG/JPEG, оригинал, SHA-256, ACL и 10 вложений | tests/attachments.py | lab4-final-attachments.txt |
| Отказ принявшей файл API | tests/attachment_failover.py | lab4-final-uploader-failover.txt |
| Restart API и всех хранилищ с прежним токеном | scripts/test-persistence.py | lab4-final-persistence-proof.txt: StartedAt до/после всех работающих ролей |
| Чистый build и пустые volumes | scripts/test-clean-lab4.py | lab4-clean-start.json, lab4-final-clean-start.txt: snapshot, build, миграция 008, smoke, вложения |
| Большой/повреждённый файл, MIME, чужой чат | tests/attachments.py; tests/lab4_review.py | lab4-final-attachments/reviewer-cases.txt |
| Обрыв, ошибка S3 PUT, COMMIT и DELETE, повтор очистки | tests/reconciliation.py | lab4-final-reconciliation.txt |
| 10 одновременных загрузок, пик RAM | tests/upload_memory.py | lab4-final-upload-memory.txt |
| Приватность S3, ограниченные роли, повторяемый bootstrap | tests/reconciliation.py; clean-start | unsigned GET 403; API не удаляет/не создаёт чужой bucket; reconciler не загружает |
| Полный трек 2: orphan/missing, dry-run, свежие/занятые файлы | tests/reconciliation.py | snapshot до/после, контролируемые сбои, повторный apply |
| Стоимость обхода, включая >1000 объектов | tests/reconciliation.py | 10/100/1005 объектов, три прогона, LIST/HEAD/SQL и время |
| Замечания преподавателя и восстановление после pause | tests/lab4_review.py; tests/request_deadline.py | lab4-final-reviewer-cases/request-deadline.txt; LAB4_AUDIT.md |
Имена файлов в таблице относятся к `evidence/`. Сводка всех команд и exit codes —
`evidence/lab4-final-summary.json`. Подробные наблюдения и исходные результаты
экспериментов — в JSON-строках соответствующих txt-файлов.
## Исследование и результаты
Гипотеза: журнал до PUT, единая блокировка и сверка устраняют бесхозные объекты
после частичных сбоев, сохраняя свежие и используемые файлы. Стоимость последовательного
обхода растёт примерно линейно по числу объектов. Проверки выполняются на отдельной
UUID-схеме PostgreSQL и приватном UUID-bucket; реальные данные текущего стенда не
удаляются. Используются реальные операции MinIO и аварийное завершение настоящего
кода загрузки после PUT. Дополнительно моделируются отказы БД, S3, потерянный ответ
удаления и публикация между dry-run и apply.
Стоимость dry-run измеряется для 10/100/1005 свежих бесхозных объектов по три раза.
Это metadata-профиль: LIST и HEAD, без чтения оригиналов. Для 1005 объектов нужны
две страницы LIST. Текущая реализация делает около пяти SQL statements на бесхозный
объект; для удалённой БД это заметная стоимость. Измерения итогового прогона приведены в таблице результатов ниже. Hash-проверка восстановления дополнительно
читает исходник и учитывается отдельно.
В опыте RAM временно допускаются пять загрузок на реплику при одном декодировании.
Две реплики принимают 10 одновременных PNG для двух размеров, затем проверяются
SHA-256 и скачанные байты. Cgroup memory.current измеряется каждые 20 мс, включая
tmpfs. После опыта восстанавливается обычный лимит одной загрузки на реплику.
Короткие пики между отсчётами могут быть пропущены; два размера не покрывают все
возможные картинки в 40 млн пикселей. Это не benchmark максимальных RPS.
## Итоговые измерения
Все 16 этапов `make -f student.mk verify-lab4` завершились с exit code 0. Интеграционный
набор сверки содержит 15 проверок, включая отказ DELETE до удаления
и прямой unsigned GET существующего объекта с результатом 403.
| Объектов | Медиана 3 обходов, с | LIST | HEAD | SQL statements |
| --- | --- | --- | --- | --- |
| 10 | 0.0181 | 1 | 10 | 53 |
| 100 | 0.1851 | 1 | 100 | 503 |
| 1005 | 2.0142 | 2 | 1005 | 5028 |
Оба профиля по 10 одновременных загрузок завершились без отказов: 20 ответов 201,
все SHA-256 и скачанные оригиналы совпали. Пики RAM: **131.07 / 120.52 MiB**
при 512 MiB на реплику. Размеры PNG: 197105 и
4923446 байт. Обычный UPLOAD_CONCURRENCY=1 восстановлен.
При замороженной PostgreSQL уже выполнявшаяся история вернула 503 за
**5.1996 с**, readiness — за **2.0638 с**.
После unpause восстановились 200 без рестарта API. Пустой стенд дошёл до миграции
008; API build --no-cache занял 51.866 с. Временный проект,
volumes и его теги образов удалены; действующие данные сохранены.
![Измеренная стоимость обхода и память API](evidence/lab4-research/results.png)
Усы на графике — min/max трёх запусков, не доверительный интервал.
Указанная RAM — максимум отсчётов, а не доказанный абсолютный пик между ними.
## Ограничения
Поддерживается один неверсионируемый bucket; worker отказывается работать с Enabled
или Suspended versioning. Все штатные писатели обязаны соблюдать блокировки;
прямые административные операции в S3 обходят эту координацию. Backup/restore
потерянных байтов не реализованы. PostgreSQL, Redis, MinIO, LB и Docker host остаются
едиными точками отказа. Не обещается отсутствие переходных ошибок при отказах.
Старые журнал и наблюдения пока сохраняются без автоматического сокращения истории.
Тест чистого запуска использует полный снимок рабочего каталога, включая новые
файлы, отдельные образы и пустые volumes; API строится с --no-cache. Кэш сборки
закреплённого MinIO может использоваться. Это проверка исходников сдачи, а не
утверждение, что текущий Git HEAD уже содержит все локальные изменения.