forked from mtusi2026/mtusi2026lab4
60 lines
14 KiB
Markdown
60 lines
14 KiB
Markdown
# Отчёт — лабораторная 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 сохраняются | |