forked from mtusi2026/mtusi2026lab4
feat: add REPORT.md
This commit is contained in:
@@ -1,37 +1,183 @@
|
||||
# Отчёт — лабораторная 4
|
||||
|
||||
- Автор, группа: TODO
|
||||
- Целевая оценка; выбранный трек 5, если нужен: TODO
|
||||
- Commit/PR: TODO после публикации
|
||||
- Использованные источники, библиотеки и помощь ИИ: TODO
|
||||
- Автор, группа: Спесивцев Даниил, БПИ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
|
||||
|
||||
TODO: версии runtime/образов, prerequisites, команды создания локальных secrets/.env, build, миграций, запуска, ожидания готовности, тестов и остановки. Указать необходимые действия оператора. Не вставлять секреты. Отдельно указать безопасную остановку и команду намеренного удаления учебных данных.
|
||||
Стенд: 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.
|
||||
|
||||
## Архитектура и решения
|
||||
|
||||
TODO: схема процессов/хранилищ, источник истины, транзакционные границы, ограничения. Что перенесено из lab3, что изменено в этой работе. Соответствие переменных из .env.example реальной конфигурации.
|
||||
```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`.
|
||||
|
||||
## Доказательства критериев
|
||||
|
||||
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства |
|
||||
| Критерий | Команда/сценарий | Наблюдаемый результат | Файл |
|
||||
| --- | --- | --- | --- |
|
||||
| Публичный smoke | make test | TODO | TODO |
|
||||
| Остальные пункты уровня 3 | TODO | TODO | TODO |
|
||||
| Все пункты уровня 4, если заявлен | TODO | TODO | TODO |
|
||||
| Выбранный трек 5, если заявлен | TODO | TODO | TODO |
|
||||
|
||||
TODO: добавить отдельную строку для каждого заявленного критерия. PASS без команды и наблюдения не является доказательством. Проверка инфраструктурного hook требует подтверждения, какие реальные процессы/хранилища перезапущены.
|
||||
| Публичный 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` |
|
||||
|
||||
## Эксперименты и отказы
|
||||
|
||||
TODO: гипотеза, hardware/лимиты, версии, объём данных, профиль нагрузки, concurrency/arrival rate, длительность/прогрев, повторы, успешные RPS, ошибки, p50/p95/p99, CPU/RAM. Сохранить raw summary без tokens и объяснить ограничения измерения.
|
||||
### Память при загрузках
|
||||
|
||||
| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных |
|
||||
Гипотеза: лимиты тела и пикселей вместе с семафором декодирования не дают одной загрузке занять неограниченную память.
|
||||
|
||||
Методика: 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`). Аудит выявил три места, где реализация была мягче контракта; они исправлены:
|
||||
|
||||
| Место | Было | Стало | Основание |
|
||||
| --- | --- | --- | --- |
|
||||
| TODO | TODO | TODO | TODO |
|
||||
| `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 сохранён.
|
||||
|
||||
## Ограничения и следующие шаги
|
||||
|
||||
TODO: какие отказы выдерживаются и какие нет; что не реализовано; где учебное упрощение; какое улучшение подтверждено, а какое пока гипотеза.
|
||||
- Один Docker-host: отказ host, единственного PostgreSQL и единственного LB не выдерживается. Проверен только отказ одной API-реплики.
|
||||
- Reconciler — операторская утилита, запускается вручную; расписания и фонового worker'а нет (это уже тема lab5). Удаление объектов последовательное.
|
||||
- Если объект утрачен, но на него ссылается сообщение, автоматический ремонт невозможен: байты не восстановить, а удаление строки нарушило бы историю. Такие случаи остаются в отчёте reconciler'а и требуют решения оператора. В демонстрационном наборе данных есть одно такое вложение — оно появилось в результате учения и остаётся видимым в `missing`.
|
||||
- Тело загрузки буферизуется в память: верхняя граница — `MAX_CONCURRENT_UPLOADS × MAX_UPLOAD_BYTES` (по умолчанию 80 MiB) плюс один декод.
|
||||
- Нет ограничения частоты запросов, TLS/mTLS, асинхронной обработки и вариантов изображений — это следующие лабораторные.
|
||||
- `filename` хранится как отображаемое имя и не используется в ключах; санитизация ограничена контролем недопустимых символов.
|
||||
|
||||
Reference in New Issue
Block a user