From d790976c302de03934d92a23a07bb12ac9d6309d Mon Sep 17 00:00:00 2001 From: myDan Date: Fri, 20 Nov 2026 05:04:28 +0300 Subject: [PATCH] feat: add REPORT.md --- REPORT.md | 180 ++++++++++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 163 insertions(+), 17 deletions(-) diff --git a/REPORT.md b/REPORT.md index 9ad2b84..b9c8282 100644 --- a/REPORT.md +++ b/REPORT.md @@ -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` хранится как отображаемое имя и не используется в ключах; санитизация ограничена контролем недопустимых символов.