Files
mtusi2026lab4-implementation/REPORT.md
T
2026-11-20 05:04:28 +03:00

184 lines
22 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 — согласованность двух хранилищ
- Commit/PR: commit 60e8f4474b9f635acbbc4920ff04c7901431acda
- Использованные источники, библиотеки и помощь ИИ: Go 1.27, стандартная библиотека и перечисленные ниже модули; S3 API и MinIO-совместимая семантика — по документации AWS и RustFS. При подготовке решения и текста отчёта использовались LLM; все команды и результаты в отчёте воспроизведены на локальном стенде.
Библиотеки и компоненты:
| Компонент | Версия | Назначение |
| --- | --- | --- |
| go-chi/chi | v5.3.2 | HTTP-роутинг и middleware |
| jackc/pgx | v5.11.0 | PostgreSQL, пул `pgxpool`, транзакции |
| redis/go-redis | v9.23.0 | общие сессии |
| golang.org/x/crypto | v0.58.0 | Argon2id |
| minio/minio-go | v7.4.1 | S3-клиент (API и операторские утилиты) |
| minio/madmin-go | v3.0.110 | идемпотентный bootstrap пользователя и политики |
| migrate/migrate | v4.20.1 (образ) | однократные миграции |
| HAProxy | 3.4.7-alpine (образ) | единая точка входа |
## Запуск из чистого clone
Стенд: i5-11400H (12 потоков), 15 GiB RAM, Linux 7.3.5, podman 6.2.0 + podman-compose 1.6.0 (`evidence/env.txt`). Образы закреплены тегами: `rustfs/rustfs:1.0.6`, `postgres:18.6-alpine3.24`, `redis:8.10.3-alpine3.23`, `haproxy:3.4.7-alpine`, `migrate/migrate:v4.20.1`, сборка API — `golang:1.27.1-alpine3.24` → `alpine:3.24.1`.
```sh
scripts/init-secrets.sh
make up
until curl -sf http://localhost:8080/health/ready; do sleep 1; done
make check
make validate PYTHON=.venv/bin/python
make test
make test-attachments
make test-contract
make test-memory
make test-cost
make test-reconcile
make test-go
make test-idempotency
make test-persistence ACTION_SCRIPT=scripts/restart.sh
make test-failover ACTION_SCRIPT=scripts/stop-one.sh
scripts/reconcile.sh # dry-run, grace 1h
scripts/reconcile.sh -grace 0s -dry-run=false
make down # остановка, volumes сохраняются
podman-compose down -v # намеренное удаление учебных данных
```
Движок выбирается так же, как в lab3: `ENGINE=podman`/`COMPOSE=podman-compose` при наличии podman, иначе docker. `compose.yaml` проходит `docker compose config --quiet` и `podman-compose config`.
`scripts/init-secrets.sh` создаёт локальные файлы секретов, повторный запуск их не перезаписывает (проверено хэшами, `evidence/credentials.txt`). Bootstrap S3 (`s3-init`) идемпотентен и запускается один раз перед API.
## Архитектура и решения
```text
client → lb (HAProxy :8080) ──edge──▶ api ×2 ──backend──▶ postgres (метаданные, источник истины)
├────────▶ rustfs (байты, приватный bucket)
└────────▶ redis (сессии)
migrate (one-shot) ─▶ postgres
s3-init (one-shot) ─▶ rustfs: bucket + policy + app user
reconcile (операторский запуск) ─▶ rustfs + postgres
```
| Роль | Service | Образ | Health/readiness | Volume | Сеть / порты | Credentials |
| --- | --- | --- | --- | --- | --- | --- |
| LB | `lb` | `haproxy:3.4.7-alpine` | активная проверка `/health/ready` | — | edge, публикует `8080` | нет |
| API | `api` ×2 | `localhost/messenger-api:lab4` | `/health/live`; `/health/ready` = PostgreSQL + Redis + S3 + не draining | — | edge + backend, порт не публикуется | `database_url`, `cache_url`, app-креды S3 |
| БД | `postgres` | `postgres:18.6-alpine3.24` | `pg_isready` | `pgdata` | backend, `127.0.0.1:55432` для `make test-go` | `postgres_password` |
| Сессии | `redis` | `redis:8.10.3-alpine3.23` | `redis-cli ping` | `redisdata` (AOF) | backend, `127.0.0.1:56379` | нет |
| S3 | `s3` | `rustfs/rustfs:1.0.6` | `GET /health` | `s3data` | backend, порт 9000 не публикуется, консоль отключена | root-креды |
| Bootstrap | `s3-init` | тот же образ | exit 0 | — | backend | root + app креды |
| Миграции | `migrate` | `migrate/migrate:v4.20.1` | exit 0 | SQL read-only | backend | `database_url` |
Ключевые решения:
- **Хранилище.** Выбран RustFS: MinIO-совместимый S3, публично доступный образ с обычным semver-тегом (`1.0.6`). MinIO community-образы на момент работы не отдаются ни Docker Hub, ни Quay (проверено), поэтому закреплять их тег было бы невоспроизводимо.
- **Разделение данных.** В PostgreSQL только метаданные и связи; байты — в приватном bucket. Ключ объекта `chats/{chat_id}/{attachment_id}` генерирует сервер, `filename` — только для отображения. В таблице `attachments` нет бинарных колонок (`evidence/storage.txt`).
- **Порядок записи.** `PUT` в S3 → транзакция PostgreSQL (метаданные + ключ идемпотентности + связи). При ошибке БД выполняется компенсирующий `DELETE`; если и он не удался — объект остаётся и снимается reconciler'ом после grace period.
- **Креды.** API работает отдельным S3-пользователем с политикой `ListBucket`/`GetBucketLocation` на bucket и `GetObject`/`PutObject`/`DeleteObject` на объекты. Root-креды смонтированы только в `s3` и `s3-init`; удаление bucket app-кредами запрещено (`Access Denied`).
- **Ограничение RAM.** Тело ограничено 10 MiB и читается потоково в буфер; до полной распаковки проверяются формат (`image.DecodeConfig`) и лимит 40 млн пикселей; полное декодирование идёт под семафором (`MAX_CONCURRENT_DECODES=1`), общая параллельность загрузок — `MAX_CONCURRENT_UPLOADS=8`. Один декод 40-мегапиксельного PNG — самая дорогая операция, поэтому верхняя граница памяти детерминирована.
- **Идемпотентность сообщений.** Ключ, сообщение и связи `message_attachments` пишутся одной транзакцией; в хэш входят `text` и канонизированный (отсортированный) набор `attachment_ids`, отсутствие поля эквивалентно `[]`.
- **Reconciler.** Сверяет объекты S3 (по префиксу) со строками `attachments`. Orphan-объект удаляется только если он старше grace period и на него нет строки метаданных. «Мёртвая» строка метаданных (объект отсутствует) удаляется, только если сообщения на неё не ссылаются; используемая строка сохраняется и попадает в отчёт, потому что восстановить утраченные байты нельзя, а удаление нарушило бы историю.
- **Соответствие `.env.example`.** `SESSION_STORE=postgres` в примере, фактически используются Redis-сессии из lab3 (контракт допускает оба варианта); `S3_ACCESS_KEY_ID_FILE`/`S3_SECRET_ACCESS_KEY_FILE` указывают на app-креды; `MAX_UPLOAD_BYTES`/`MAX_IMAGE_PIXELS` передаются в API; `API_REPLICAS` → `scale`; `IDEMPOTENCY_TTL_SECONDS` не используется — ключи хранятся бессрочно.
Таймауты: PostgreSQL `statement_timeout` 5 s / connect 3 s; readiness-ping 1 s; HTTP-сервер 5/15/15/60 s; HAProxy connect/server/check 2/20/1 s; graceful shutdown: drain 3 s + `Shutdown` 5 s при `stop_grace_period: 10s`.
## Доказательства критериев
| Критерий | Команда/сценарий | Наблюдаемый результат | Файл |
| --- | --- | --- | --- |
| Публичный smoke | `make test` | PASS | `evidence/smoke.txt` |
| Контракт вложений и сообщений | `make test-attachments` | 23/23 проверки | `evidence/negative.txt` |
| Аудит краевых случаев контракта | `make test-contract` | 30/30 проверки | `evidence/contract-audit.txt` |
| Полная OpenAPI-валидация | `make validate PYTHON=.venv/bin/python` | PASS | вывод команды |
| Собственные Go-тесты | `make test-go` | 26 PASS | `evidence/test-go.txt` |
| ≥2 реплики, одна точка входа, `X-Instance-Id` | `make up`, 20 запросов через LB | 10/10 на каждую реплику, публикует только `lb` | `evidence/instances.txt` |
| S3 в стенде, приватный bucket, постоянный volume | анонимный GET и listing | 403, порт наружу не публикуется | `evidence/private-bucket.txt` |
| Метаданные в PostgreSQL, байты в S3 | `psql`, листинг volume | в таблице нет бинарных колонок, объект лежит в `s3data` | `evidence/storage.txt` |
| `201 ready` после S3 и БД; скачивание байт-в-байт | `make test` | SHA-256 и размер совпадают | `evidence/smoke.txt` |
| Доступ только участникам (404 постороннему) | `make test`, `make test-attachments` | 404 для metadata и content | `evidence/smoke.txt`, `evidence/negative.txt` |
| Ограничения 10 MiB / 40 млн пикселей / MIME / filename | `make test-attachments` | 413, 415, 400; PNG ровно 40 000 000 px принят | `evidence/negative.txt` |
| Ошибки пользователя не превращаются в 500 | `make test-attachments` | только 400/404/409/413/415 | `evidence/negative.txt` |
| Upload → остановка реплики → download через другую | `make test-failover` ×2 | 0 ошибок, восстановление 3.19–3.32 s | `evidence/failover-1.txt`, `evidence/failover-2.txt` |
| Restart с volumes сохраняет метаданные и оригинал | `make test-persistence` | PASS, контейнеры перезапущены, volumes те же | `evidence/persistence.txt` |
| Идемпотентность сообщений через разные реплики | `make test-idempotency` | 20 запросов → одно сообщение, обе реплики | `evidence/idempotency-race.txt` |
| Миграции отдельным контейнером | `make up` | версия 3, `dirty=f`, повторный запуск — `no change` | `evidence/migrate.txt` |
| Лимиты и секреты по ролям | `inspect`, `ls /run/secrets` | лимиты у всех сервисов, секреты только у нужных ролей | `evidence/limits.txt` |
| Недоступность S3 | `/health/live` 200, `/health/ready` 503, клиент через LB получает 503 | `evidence/s3-outage.txt` |
| Ограничение памяти, ≥10 параллельных загрузок | `make test-memory` | пик 333 МБ при лимите 512 МБ, 10/10 успешно | `evidence/memory.txt`, `evidence/upload-memory.json` |
| Отказ между S3 и БД не оставляет объектов | инъекция отказа вставки + `reconcile` | 503, число объектов не изменилось | `evidence/compensation.txt` |
| Идемпотентный bootstrap | `s3-init` дважды | одинаковый результат | `evidence/credentials.txt` |
| Ограниченные креды API | удаление bucket app-кредами | `Access Denied` | `evidence/credentials.txt` |
| Трек 2: reconciler, инъекции с обеих сторон | `scripts/reconcile.sh`, `scripts/s3tool.sh` | детекция и безопасный ремонт | `evidence/track2-injection.txt` |
| Трек 2: dry-run и повторный запуск | `-dry-run`, повтор `-dry-run=false` | второй прогон ничего не меняет | `evidence/reconcile.txt`, `evidence/track2-injection.txt` |
| Трек 2: свежие и используемые не удаляются | apply с grace 1h | свежий объект и используемое вложение целы | `evidence/track2-injection.txt` |
| Трек 2: стоимость обхода | `make test-cost` | 0.033–0.09 мс/объект, 1 LIST-страница на 1000 | `evidence/track2-cost.txt` |
## Эксперименты и отказы
### Память при загрузках
Гипотеза: лимиты тела и пикселей вместе с семафором декодирования не дают одной загрузке занять неограниченную память.
Методика: 10 одновременных загрузок PNG 8000×5000 (40 000 000 пикселей, 126 609 байт) на реплику, лимит API 512 MiB, `MAX_CONCURRENT_UPLOADS=8`, `MAX_CONCURRENT_DECODES=1`; пик снимался через `/sys/fs/cgroup/memory.peak` после пересоздания реплик.
Результат: 10/10 успешно, 1.01 s, p50 613 мс, p95 1040 мс, пик **333 МБ** на реплику (65 % лимита). При `MAX_CONCURRENT_DECODES=2` пик упирался в лимит 512 МБ, поэтому значение по умолчанию — 1.
### Стоимость обхода (трек 2)
| Объектов | Скан | S3-запросов (LIST) | DB-запросов | мс/объект | Ремонт (удаление) |
| --- | --- | --- | --- | --- | --- |
| 100 | 9 мс | 1 | 2 | 0.09 | 1.3 s (100 DELETE) |
| 1000 | 34 мс | 1 | 2 | 0.034 | 12.2 s (1000 DELETE) |
| 5000 | 166 мс | 5 | 2 | 0.033 | 69.9 s (5000 DELETE) |
Скан линеен по числу объектов и страниц LIST (1000 на страницу), число обращений к БД постоянно. Ремонт доминируется последовательными DELETE — это осознанное упрощение, возможное улучшение — пакетное или параллельное удаление.
### Инъекции и восстановление
| Воздействие | Ожидание | Наблюдение |
| --- | --- | --- |
| Отказ вставки метаданных после успешного `PUT` | объект удаляется компенсацией, ответ 503 | число объектов не изменилось, после снятия инъекции загрузка снова 201 |
| Объект без метаданных (свежий) | не удаляется в пределах grace | при `-grace 1h` `deleted_objects=0`, объект на месте |
| Объект без метаданных (старше grace) | удаляется | `-grace 0s` → `deleted_objects=1`, повторный прогон — 0 |
| Метаданные без объекта, сообщение не ссылается | строка удаляется | `deleted_metadata=1` |
| Метаданные без объекта, сообщение ссылается | строка сохраняется, попадает в отчёт | `retained_missing=1`, строка в БД остаётся |
| Остановка реплики под нагрузкой | без потери подтверждённых данных | 85–100 успешных записей, 0 ошибок |
| Перезапуск всех сервисов | данные и токен сохраняются | PASS, volumes не тронуты |
| Недоступность S3 | `/health/live` 200, `/health/ready` 503, восстановление | 200 / 503 / 200 |
## Аудит контракта и спорные места
Краевые случаи проверяются отдельным сьютом `make test-contract` (`scripts/contract-audit.py`, 30 проверок, `evidence/contract-audit.txt`). Аудит выявил три места, где реализация была мягче контракта; они исправлены:
| Место | Было | Стало | Основание |
| --- | --- | --- | --- |
| `attachment_ids: null` | принималось как отсутствие поля | `400` | схема: поле — массив; «неверные типы — 400» |
| `?variant=` (пустое значение) | считалось `original` | `400` | «в lab4 допустим только `original`»; отсутствие параметра — отдельный случай |
| `filename` из одних пробелов | принималось | `400` | «обязательные строки не состоят только из пробельных символов» |
Решения по остальным неоднозначностям:
- `Content-Type` с параметрами (`image/png; charset=utf-8`) принимается: сравнивается медиатип, параметры не влияют.
- Порядок проверок загрузки: `Content-Type` (415) → размер тела (413) → MIME по содержимому (415) → лимит пикселей (413) → целостность (415). Если нарушено несколько правил, возвращается первая сработавшая проверка; контракт приоритет не задаёт.
- Пустой или пробельный `text` разрешён только с вложениями (`anyOf` в схеме); без вложений — `400`.
- `variant` проверяется до проверки членства: посторонний с неизвестным вариантом получает `400`, а не `404`. Существование чужого объекта это не раскрывает: для любого `id` ответ одинаков.
- Ключи идемпотентности хранятся бессрочно; контракт требует лишь повтор «в течение 24 часов».
- Неподдерживаемый HTTP-метод на известном пути даёт `405` с кодом `invalid_request` — контракт этот код не описывает, поведение выбрано явно.
- `429 rate_limited` есть в перечислении кодов, но rate limiting не входит в обязательный минимум и не реализован.
- Cursor привязан к ресурсу: курсор истории чата на списке чатов и наоборот даёт `400` (проверяется аудитом).
- S3 включён в readiness. Пока объектное хранилище недоступно, реплики выводятся из балансировщика и клиент получает `503` на любой запрос, включая текстовые сообщения; так гарантируется, что обязательный синхронный путь (сообщения с вложениями) не обслуживается частично. `/health/live` при этом остаётся `200` (`evidence/s3-outage.txt`).
- Валидация выполняется до проверки доступа только там, где это не раскрывает существование объекта; порядок «сначала аутентификация, затем ресурс» в middleware сохранён.
## Ограничения и следующие шаги
- Один Docker-host: отказ host, единственного PostgreSQL и единственного LB не выдерживается. Проверен только отказ одной API-реплики.
- Reconciler — операторская утилита, запускается вручную; расписания и фонового worker'а нет (это уже тема lab5). Удаление объектов последовательное.
- Если объект утрачен, но на него ссылается сообщение, автоматический ремонт невозможен: байты не восстановить, а удаление строки нарушило бы историю. Такие случаи остаются в отчёте reconciler'а и требуют решения оператора. В демонстрационном наборе данных есть одно такое вложение — оно появилось в результате учения и остаётся видимым в `missing`.
- Тело загрузки буферизуется в память: верхняя граница — `MAX_CONCURRENT_UPLOADS × MAX_UPLOAD_BYTES` (по умолчанию 80 MiB) плюс один декод.
- Нет ограничения частоты запросов, TLS/mTLS, асинхронной обработки и вариантов изображений — это следующие лабораторные.
- `filename` хранится как отображаемое имя и не используется в ключах; санитизация ограничена контролем недопустимых символов.