Files
mtusi2026lab4/REPORT.md
T

60 lines
14 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
- Автор, группа: не указаны пользователем.
- Целевая оценка: 5; выбран трек 2 — согласованность PostgreSQL/S3.
- Commit/PR: не создавались.
- Источники и инструменты: контракт и материалы `mtusi2026lab4`; основа приложения и тест конкурентной идемпотентности перенесены из `mtusi2026lab3`; Python 3.12, psycopg 3, boto3, Pillow, SeaweedFS, HAProxy. Использована помощь AI assistant using Copilot SDK in VS Code при переносе, реализации и написании документации.
## Запуск из чистого clone
Требуются Docker Engine с Compose v2 и Python 3.9+ для локальных проверок. Образы стенда закреплены: `python:3.12.7-slim`, `postgres:16.4-alpine`, `chrislusf/seaweedfs:4.51`, `haproxy:3.0.7-alpine`.
Полная последовательность build, миграций, readiness, тестов, безопасного останова и удаления учебных данных находится в [code.md](code.md). Секреты генерируются локально `scripts/bootstrap-secrets.sh`; они не выводятся в stdout и не входят в Git. Compose не публикует API-реплики, PostgreSQL или S3 API; наружу доступен только HAProxy на `127.0.0.1`. В проверенной среде порт 8080 был занят, поэтому стенд запускался на 18080.
## Архитектура и решения
```text
HTTP client -> HAProxy -> 2+ stateless API replicas
|-> PostgreSQL (users, chats, messages, sessions, idempotency, attachment metadata)
|-> private SeaweedFS S3 bucket (original image bytes)
```
Перенесены основные handler/store/server, миграции и поведение пользователей, сессий, чатов, пагинации и идемпотентности lab3. В сообщение добавлено необязательное `attachment_ids`, пустой текст принимается только при наличии вложений. Идемпотентный JSON канонизируется с `attachment_ids: []`, поэтому отсутствующее поле и пустой список эквивалентны.
Новый маршрут принимает только сырые PNG/JPEG, максимум 10 MiB и 40 млн пикселей. Content-Length проверяется до чтения; загрузка читается по 64 KiB в `SpooledTemporaryFile` с порогом памяти 1 MiB, ограничением времени 60 секунд и лимитом 10 одновременных загрузок на процесс. После проверки формата и размеров Pillow полностью декодирует пиксели; декодирование сериализовано до одного изображения на процесс, повреждённые IDAT должны завершаться 415. MIME сверяется с форматом декодера. `filename` хранится только как display metadata; object key строится из серверного UUID. Оригинал сначала записывается в S3, после чего транзакционно сохраняется metadata. При ошибке БД выполняется best-effort удаление S3-объекта; если процесс оборвался между операциями, объект обнаружит reconciler.
Download сначала проверяет членство пользователя в чате через PostgreSQL, затем проксирует байты из приватного S3 bucket. API не выдаёт redirect или object key. Отдельный ограниченный S3-пользователь создаётся bootstrap с правами только на бакет `messenger-attachments`; admin credentials не монтируются в API. SeaweedFS master/filer/volume запущены в отдельной internal-сети, к которой API не подключён; API имеет доступ только к отдельному S3 gateway, дополнительные HTTP-порты которого выключены. PostgreSQL и SeaweedFS core используют persistent volumes.
Reconciler сравнивает полный список объектов с metadata и выдаёт счётчики/время обхода. Ручной запуск по умолчанию read-only. Compose-сервис `reconciler` автоматически вызывает его с `--apply` каждые 900 секунд; grace period по умолчанию — 3600 секунд. Автоматический проход удаляет только старые orphan objects, регистрирует missing-object incidents и очищает устаревшие incident-записи. Если metadata существует, но object отсутствует, восстановление допускается только из предоставленной оператором точной копии с теми же размером и SHA-256; копия называется UUID вложения. Периодический сервис не имеет restore directory, поэтому без отдельного ручного восстановления отсутствующие байты не восстанавливает.
## Доказательства критериев
Проверки выполнены в Docker Compose на локальном стенде (две API-реплики, PostgreSQL, SeaweedFS и HAProxy). Для этого запуска HAProxy опубликован на `localhost:18080`; секреты и данные находятся в локальных ignored-файлах/volumes.
| Критерий | Команда/сценарий | Результат / наблюдение | Доказательство |
| --- | --- | --- | --- |
| Контракт и структура | `make check`; `make validate PYTHON=.venv/bin/python` | PASS | `scripts/check_contract.py`, `scripts/validate_openapi.py` |
| Публичный API, checksum и доступ | `make test BASE_URL=http://localhost:18080` | PASS | `tests/smoke.py` |
| Конкурентная идемпотентность | 12 одинаковых POST через HAProxy и две API-реплики | PASS: все ответы совпали, в истории сохранено одно сообщение | `student-tests/test_idempotency_race.py` |
| Ограничения upload и негативные случаи | `make test-attachments BASE_URL=http://localhost:18080` | Ранее PASS для oversized bytes/pixels, повреждённого изображения, MIME spoof, unsafe filename и авторизации; добавлен отдельный IDAT corruption case, его интеграционный запуск после изменения ожидает доступного Docker стенда | `student-tests/test_attachments.py` |
| Десять одновременных upload и память | `make test-upload-concurrency BASE_URL=http://localhost:18080` | PASS: 10 параллельных upload по 5 883 411 байт, две API-реплики, 1.648 с; максимальная память одного API-контейнера: baseline 57 126 420 B, peak 68 209 868 B, delta 11 083 448 B. За время upload получено 4 samples, результат приблизительный | `student-tests/upload_concurrency.py` |
| Persist volumes и API failover | `make test-persistence ACTION_SCRIPT=scripts/restart.sh`; `make test-failover ACTION_SCRIPT=scripts/stop-one.sh` | PASS: PostgreSQL/S3 restart сохранил запись, вложение и прежнюю сессию; failover видел 2 реплики до остановки, после двух неуспешных попыток записал 111 сообщений, первое восстановление за 3.25 с | `tests/resilience.py`, `scripts/` |
| S3 private bucket и least privilege | unauthenticated GET; повторный bootstrap; проверка сети master/filer | Анонимный GET и повторный bootstrap ранее PASS; добавлено разделение SeaweedFS core и S3 gateway и интеграционная проверка изоляции DNS, её запуск после изменения ожидает доступного Docker стенда | `compose.yaml`, `student-tests/test_reconcile_integration.py` |
| Track 2: orphan/missing reconciliation | `make test-reconcile`; `make test-reconcile-integration BASE_URL=http://localhost:18080` | PASS: реальные PostgreSQL/SeaweedFS, 45 объектов и 45 metadata-записей; 1 orphan обнаружен и удалён, 1 missing object восстановлен по точной копии, повторный scan чистый, 21.638 ms | `student-tests/test_reconcile.py`, `student-tests/test_reconcile_integration.py` |
## Эксперименты и отказы
### Track 2 — гипотеза и методика
**Гипотеза:** reconciliation не удалит ни свежий orphan, ни известное metadata-вложение; orphan старше grace period удалится при `--apply`; missing object восстановится только из файла, размер и SHA-256 которого совпадают с metadata. Повторный запуск не должен повторно удалять уже удалённый объект или создавать дубликаты metadata.
**Повторяемая методика:** выполнить API upload тестовых изображений; добавить synthetic S3 orphan под уникальным `original/<uuid>`; удалить объект одного тестового attachment через S3 admin-инструмент; сделать копию оригинальных bytes в recovery directory под UUID attachment; запускать `src/reconcile.py` в dry-run и с `--apply --restore-dir <path>`, выдерживая заданный grace period. Для стоимости обхода сохранить JSON `duration_ms`, `objects_seen`, `metadata_seen`, `orphan_objects`, `missing_objects` для нескольких размеров набора; фиксировать версии, CPU/RAM, длительность прогрева и объём данных. Объекты с сообщениями не удалять: они имеют metadata и не входят в orphan set.
**Наблюдаемые результаты:** интеграционный сценарий выполнен на реальных PostgreSQL/SeaweedFS: при dry-run найден synthetic orphan и отсутствующий объект, dry-run ничего не удалил; свежий orphan пережил `--apply`, точный backup восстановил missing object, после 61 секунды orphan удалён, повторная сверка чистая. Зафиксировано 45 S3 объектов, 45 metadata-записей и 21.638 ms scan time. Этот единичный результат не является полноценным performance benchmark; RPS не измерялся.
| Воздействие | Ожидаемое поведение | Наблюдение | Восстановление / потеря данных |
| --- | --- | --- | --- |
| Повторный bootstrap S3 | Bucket остаётся приватным, credentials не меняются | Повторный bootstrap завершился успешно; анонимный GET получил отказ | Integration test, Compose logs |
| PostgreSQL недоступен после S3 PUT | Compensation удалит объект; если процесс завершился до компенсации, поздний orphan уберёт reconciler после grace | Интеграционный отказ ещё не выполнен | Orphan не трогается до границы grace |
| Missing S3 object | Dry-run фиксирует; `--apply` записывает incident; оригинал восстанавливается только из exact-hash backup | Реальный интеграционный сценарий удалил synthetic объект и восстановил его по checksum; attachment download совпал с исходными bytes | Невосстановимый объект сохраняет metadata и требует оператора |
| Остановка API-реплики / restart с volumes | LB направляет запросы на другую реплику; данные/токен остаются | PASS: до отказа замечены 2 инстанса; после остановки одной API-реплики восстановление записи 3.25 с; restart PostgreSQL/S3/API сохранил данные, вложение и существующую сессию | `tests/resilience.py`; volumes сохраняются |