Files
mtusi2026lab4/REPORT.md
T
2026-10-29 15:00:36 +03:00

184 lines
29 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
- Автор, группа: Кораблев Петр, БВТ2304
- Целевая оценка: **5** (уровень 3 + уровень 4 + **трек 2 «Согласованность двух хранилищ»**)
- Commit/PR: ветка `solution/BVT2304-korablev`
- Использованные источники, библиотеки и помощь ИИ: Go 1.23.4, net/http, pgx/v5 5.7.2, go-redis/v9 9.7.0, golang.org/x/crypto (Argon2id), golang.org/x/sync 0.10.0 (semaphore), google/uuid 1.6.0, **minio-go/v7 7.0.82** (S3-клиент, работает с любым S3-совместимым сервером), стандартные `image/png` и `image/jpeg`. Образы: PostgreSQL 17.2-alpine3.21, Valkey 8.0.2-alpine3.21, HAProxy 3.0.5-alpine, **SeaweedFS 3.80** (`chrislusf/seaweedfs:3.80`), golang:1.23.4-alpine3.21 → alpine:3.21.2; для проверок вне API — python:3.12.8-alpine3.21. Документация: AWS S3 (uploads, SigV4, ListObjectsV2), SeaweedFS wiki (S3 API, `s3.config` identities), Go `image.DecodeConfig`. Помощь ИИ использовалась при написании отчёта.
## Запуск из чистого clone
Prerequisites: Docker 29.x + Compose v2 (Docker Desktop/WSL2), Python 3.9+, Git. Go и make локально не нужны (сборка в Docker; без make команды ниже запускаются через `python`). На Windows тесты запускать с `PYTHONUTF8=1` (контракт в UTF-8).
```sh
python3 scripts/init_secrets.py # = make secrets: secrets/* + .env из .env.example
docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build --wait # = make up
make check && make test # smoke через LB http://localhost:8080
make test-student # собственные тесты (18 кейсов)
make test-persistence ACTION_SCRIPT=scripts/restart.sh # Windows: scripts/restart.cmd
make test-failover ACTION_SCRIPT=scripts/stop-one.sh # Windows: scripts/stop-one.cmd
docker compose up -d --no-recreate --wait api # вернуть остановленную реплику
make ops-checks memory track2-faults track2-cost # уровень 4 и трек 2 (нужен Docker)
```
- `init_secrets.py` генерирует случайные пароли PostgreSQL/Valkey и **две S3-идентичности**: `bootstrap-admin` (только для `s3-init`) и `messenger-api` (права `Read/Write/List` только на bucket `messenger-attachments`), а также `secrets/s3_identities.json` — конфиг SeaweedFS. Всё в `secrets/` (в `.gitignore` и `.dockerignore`), контейнерам передаётся как Compose secrets `/run/secrets/*`.
- Порядок старта задан `depends_on`: postgres/valkey/s3 healthy → `migrate` (миграции под advisory lock) → `s3-init` (идемпотентное создание bucket) → `api` ×2 → `lb`; `reconciler` стартует после `s3-init`. Готовность — `--wait`/`/health/ready`.
- Безопасная остановка: `docker compose stop` (`make down`), данные в volumes `pgdata`, `s3data` сохраняются. Намеренное удаление учебных данных: `docker compose down -v` (удаляет volumes — необратимо).
## Архитектура и решения
```
client → HAProxy (lb, 127.0.0.1:8080) → api ×2 (Go, read-only rootfs)
├─ PostgreSQL: users, chats, messages, sessions, idempotency,
│ attachments (метаданные), message_attachments
├─ Valkey: кэш сессий (из lab3)
└─ SeaweedFS S3 (bucket messenger-attachments, приватный): байты
reconciler (тот же образ, `reconcile --apply --every 10m`) — сверка БД ↔ S3
```
**Перенесено из lab3** без изменения поведения: пользователи, Basic → Bearer-сессии (Argon2id, Valkey-кэш), чаты, keyset-пагинация, обязательный `Idempotency-Key`, `X-Instance-Id`, HAProxy с health-check, хуки restart/stop-one. **Изменено:** убран экспериментальный путь `MESSAGE_WRITE_PATH=tx` трека 1 lab3 (остался один путь — one-shot CTE), лимит памяти API 256M → 512M, таймауты HAProxy client/server 30s/10s → 75s (загрузка до 10 MiB).
**Выбор S3-сервера.** Планировался MinIO, но на 2026-10 образы `minio/minio` и `minio/mc` недоступны ни в Docker Hub, ни в quay.io (pull access denied / 401). Выбран SeaweedFS 3.80: одна команда `weed server -s3` (master+volume+filer+S3), идентичности с правами на конкретный bucket через `-s3.config`, без анонимной идентичности — значит bucket приватный. S3-порт 8333 не публикуется, консоли master (9333) и filer (8888) тоже: сервис только в сети `data`.
**Модель данных** (`src/internal/db/migrations/0003_attachments.sql`):
- `attachments`: `id`, `chat_id`, `owner_id`, `filename` (только для отображения), `content_type`, `size_bytes`, `sha256`, `width`, `height`, `object_key` (UNIQUE, генерирует сервер: `attachments/<chat_id>/<attachment_id>`), `status ∈ {pending, ready}`, `missing_at`, `created_at`, `updated_at`. FK `(chat_id, owner_id) → chat_members`, CHECK-и на размер ≤ 10 MiB, пиксели ≤ 40M, формат sha256.
- `message_attachments(message_id, chat_id, attachment_id, position)` с составным FK `(chat_id, attachment_id) → attachments(chat_id, id)`: **сама БД** не даёт привязать к сообщению файл другого чата.
- `messages.text` теперь может быть пустым (CHECK 0..4000); правило «пустой текст только при ≥1 вложении» проверяет API.
**Загрузка** `POST /api/v1/chats/{id}/attachments?filename=…` (`src/internal/api/attachments.go`):
1. Аутентификация → членство в чате (посторонний получает 404 до чтения тела) → `filename` (1..255 code points, без `/`, `\`, NUL, управляющих и bidi-override символов, не `.`/`..`) → `Content-Type` ∈ {image/png, image/jpeg} иначе 415 → `Content-Length > 10 MiB` → 413 сразу.
2. Слот загрузки (семафор `UPLOAD_CONCURRENCY=8` на реплику), тело читается через `http.MaxBytesReader(10 MiB)` → 413 при превышении. Тело буферизуется в памяти (≤ 10 MiB на слот), значит память одной реплики под загрузки ограничена 8 × 10 MiB.
3. Формат определяется по magic bytes и сравнивается с заявленным (подмена → 415); `image.DecodeConfig` читает только заголовок: >40M пикселей → 413 **до** декодирования; затем полное декодирование под общим бюджетом памяти (`DECODE_BUDGET_BYTES=128 MiB`, взвешенный семафор по оценке `пиксели × байт/пиксель`) — повреждённые данные → 415.
4. Транзакционная граница: **(a)** `INSERT attachments status='pending'` → **(b)** S3 `PUT` (Content-MD5) → **(c)** `UPDATE … SET status='ready' WHERE status='pending'` → `201 ready`. 201 возвращается только когда и байты, и метаданные зафиксированы.
5. Ошибка на (b) или (c) → 503 и фоновая компенсация, которая начинается со строки: `DELETE … WHERE status='pending'`, и только если строка удалена — удаление объекта. Если `UPDATE → ready` на самом деле закоммитился, а ответ БД потерялся, строка уже ready, и объект не трогаем (иначе получилось бы ready-вложение без байтов). Если недоступна БД, остаётся stale pending; если недоступен S3, может остаться объект без строки. Оба случая убирает reconciler после grace.
**Скачивание** `GET /attachments/{id}/content`: только участники чата (иначе 404), только `status='ready'`; `Stat` до первого байта ответа (отсутствие объекта → 404, недоступность S3 → 503), затем поток из S3 в ответ, без redirect; заголовки `Content-Type` (истинный), `Content-Length`, `X-Content-Type-Options: nosniff`, `Cache-Control: private, no-store`, `ETag: "<sha256>"`. `variant=thumbnail|crop|optimized` → 404 (вариантов в lab4 нет), неизвестный → 400.
**Сообщение** с `attachment_ids`: 0..10 уникальных UUID (иначе 400). Проверка «все ready и в этом чате», запись idempotency, сообщения и связей — **одним SQL-оператором** (CTE), как в lab3. Чужое, неизвестное или из другого чата → 404, ничего не сохраняется. Отпечаток идемпотентности считается по `{text, attachment_ids}` с нормализацией «нет поля» = `[]`.
**Готовность и отказы.** `/health/ready` зависит только от PostgreSQL. Недоступность S3 ломает только эндпоинты вложений (503), а текстовый мессенджер продолжает работать: если бы ready зависел от S3, LB снял бы обе реплики и упал бы весь API. SDK S3 настроен на быстрый отказ: `MaxRetry=1`, dial-таймаут 2 с, `ResponseHeaderTimeout` 10 с, операции под `S3_TIMEOUT=15s`.
**Соответствие `.env.example`** — все переменные реально используются в `compose.yaml`: `S3_ENDPOINT=http://s3:8333`, `S3_REGION`, `S3_BUCKET`, `S3_*_FILE` (secrets), `MAX_UPLOAD_BYTES` (не больше 10 MiB, иначе старт с ошибкой), `MAX_IMAGE_PIXELS`, плюс `UPLOAD_CONCURRENCY`, `DECODE_BUDGET_BYTES`, `UPLOAD_TIMEOUT`, `S3_TIMEOUT`, `API_MEMORY`, `API_GOMEMLIMIT`, `RECONCILE_GRACE`, `RECONCILE_EVERY`.
| Роль | Service | Образ | Health | Volume | Сеть / порт | Credentials |
| --- | --- | --- | --- | --- | --- | --- |
| LB | lb | haproxy:3.0.5-alpine | `:8404/healthz` | — | app; 127.0.0.1:8080 | — |
| API ×2 | api | mtusi-messenger:lab4 (сборка) | `/health/ready` | нет (read-only rootfs, tmpfs /tmp 1m) | app, data | secrets: database_url, cache_url, s3_access_key_id, s3_secret_access_key |
| БД | postgres | postgres:17.2-alpine3.21 | pg_isready | pgdata | data | pg_password |
| Сессии | valkey | valkey/valkey:8.0.2-alpine3.21 | ping | — | data | valkey_auth |
| S3 | s3 | chrislusf/seaweedfs:3.80 | `:8333/healthz` | s3data | data, не публикуется | s3_identities.json |
| Bootstrap | migrate, s3-init | mtusi-messenger:lab4 | one-shot | — | data | database_url / s3_admin_* |
| Сверка | reconciler | mtusi-messenger:lab4 | — | — | data | database_url, s3 api-ключи |
## Доказательства критериев
Окружение всех замеров: Windows 11, Docker Desktop 29.7.2 / Compose 5.5.0, WSL2 kernel 6.18; лимиты: API 1 CPU / 512M ×2, S3 1 CPU / 1G, PostgreSQL 2 CPU / 1G, reconciler 0.5 CPU / 128M. Дата — 2026-10-29.
### Уровень 3
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл |
| --- | --- | --- | --- |
| Публичный smoke | `make check`, `make test` | PASS: lab4 public API scenario | evidence/check-smoke.txt |
| Возможности lab3 сохранены | `make test-student` (8 кейсов lab3) | no-sticky, идемпотентность через 2 реплики, logout на всех репликах — PASS | evidence/student-tests.txt |
| S3 в общем стенде, байты в приватном bucket | `lab4ops.py private` | аноним GET/LIST/CreateBucket → 403; api-ключ GET → 200, sha256 совпадает; порт S3 не опубликован | evidence/private.json |
| Метаданные в PostgreSQL, не байты в БД/на диске API | `lab4ops.py no-local-file` | у API read-only rootfs (`touch` → Read-only file system), монтируются только secrets, новых файлов 0 | evidence/no-local-file.json |
| 201 ready, побайтный download, ACL | smoke + `t_upload_formats`, `t_attachment_acl` | PNG и JPEG: sha256/размер/Content-Type совпадают; посторонний получает 404 на метаданные/content/upload, без токена 401 | evidence/student-tests.txt |
| Реальные PNG/JPEG ≤10 MiB, ≤40M px, MIME по содержимому, опасные filename | `t_size_limit`, `t_bomb`, `t_corrupt_and_spoof`, `t_filenames` | PNG 10 420 335 B → 201; 10 MiB+1 → 413; заголовок 20000×20000 → 413 за 32 мс; 9 вариантов подмены/повреждения → 415; 12 опасных имён → 400 | evidence/student-tests.txt |
| Upload → стоп обслужившей реплики → download через другую | `lab4ops.py failover-upload` | загрузка через `api-2`, `docker stop api-2`, 10/10 скачиваний через `api-1` с верным sha256 | evidence/failover-upload.json |
| Failover (публичный тест) | `make test-failover` для каждой реплики | остановлена api-2: PASS, 123 записи, 0 ошибок, восстановление за 4.1 с; остановлена api-1: PASS, 116 записей, 0 ошибок, 4.1 с; файл цел в обоих случаях | evidence/failover.txt |
| Restart всего стенда с volumes | `make test-persistence` (`restart.cmd`) | PASS; postgres/valkey/s3/api перезапущены (uptime до/после в файле), файл и сессия сохранились | evidence/persistence.txt |
### Уровень 4
| Критерий | Команда/сценарий | Наблюдаемый результат | Файл |
| --- | --- | --- | --- |
| Тесты: большой файл, повреждённое изображение, подмена MIME, чужой attachment_id, файл другого чата; нет 500 | `make test-student` (10 кейсов lab4) | 18/18 PASS; в логах API за все прогоны нет ни одного 500 | evidence/student-tests.txt |
| Нет вечных неучтённых объектов: компенсация + сверка с grace | pending-intent + компенсация + `reconciler` (grace 15 мин, каждые 10 мин) | см. трек 2; реальный случай: после падения S3 reconciler нашёл 19 stale pending из прерванных загрузок и удалил их | evidence/track2/faults.json |
| Отказ S3 | `lab4ops.py s3-outage` | upload 503 за 2.0 с, download 503 за 2.0 с, метаданные 200, текстовое сообщение 201, ready 200; после старта S3 загрузки сразу работают, старый файл цел; pending-строк не осталось (компенсация удалила строку) | evidence/s3-outage.json |
| Ограниченная RAM, ≥10 одновременных загрузок | `make memory` | см. «Эксперименты»: пик API ≤ 311 MiB при 40 одновременных 10-МБ загрузках, плато уже после 20 | evidence/memory.json |
| Bootstrap идемпотентен | `lab4ops.py bootstrap` (двойной запуск `migrate` и `s3-init`) | «migrations up to date», `created:false` | evidence/bootstrap.json |
| Отдельные ограниченные S3 credentials; консоль закрыта; private bucket проверен вне API | `lab4ops.py private` | api-идентичность: CreateBucket → 403, PUT в другой bucket → 403; S3/консоли не опубликованы; аноним → 403 | evidence/private.json |
### Трек 5.2 «Согласованность двух хранилищ»
| Критерий | Команда | Результат | Файл |
| --- | --- | --- | --- |
| Повторяемый reconciler с dry-run | `server reconcile [--apply] [--grace] [--every]` | dry-run по умолчанию; advisory lock — одновременно идёт один проход | src/internal/reconcile/reconcile.go |
| Ошибки на обеих сторонах: обнаружение и исправление | `make track2-faults` | 5 из 5 внедрённых сбоев найдены, 7 исправлений, повторный apply → 0 | evidence/track2/faults.json |
| Свежие и используемые не удаляются | там же | свежий orphan, свежий pending и используемые U1/U2 остались целы | evidence/track2/faults.json |
| Стоимость обхода | `make track2-cost` | линейно, ~70 мкс/объект, 20k за 1.4–1.6 с | evidence/track2/cost.json |
## Эксперименты и отказы
### Память API при одновременных загрузках (уровень 4)
**Гипотеза:** пиковая память реплики ограничена `≈ база + UPLOAD_CONCURRENCY × 10 MiB + бюджет декодирования`, поэтому она выходит на плато и не растёт с числом клиентов.
**Методика:** `scripts/lab4ops.py memory`. Синтетический шумовой PNG 1000×3480, 10 420 335 B (почти лимит). Перед каждым прогоном `docker compose restart api`, одна прогревочная загрузка, затем N одновременных загрузок (барьер) через LB. Пик читается из cgroup v2 `memory.peak` каждой реплики. По 2 повтора.
| Одновременно | Успешно | Wall, с | p50 / max, мс | Пик API, MiB (max из 2 реплик) |
| --- | --- | --- | --- | --- |
| 1 | 1/1, 1/1 | 0.35 | 337–344 | 64.4 / 66.4 |
| 10 | 10/10, 10/10 | 3.1–4.1 | 2844–3830 / 2882–3945 | 148.2 / 151.7 |
| 20 | 20/20, 20/20 | 6.4–7.1 | 5476–6097 / 6062–6830 | 286.0 / 263.7 |
| 40 | 40/40, 40/40 | 11.8–12.6 | 8542–9590 / 11156–12044 | 264.5 / 311.1 |
**Вывод:** память выходит на плато ~250–310 MiB между 20 и 40 клиентами (слоты по 8 на реплику). Лишние клиенты ждут слота, это видно по росту latency, а не памяти. Это ниже лимита 512M и GOMEMLIMIT 400MiB. **Ограничения:** буфер одного тела ≤10 MiB в RAM — сознательное упрощение вместо потокового парсера PNG. 40M-пиксельный RGBA PNG при декодировании занимает ~160 MB и упирается в бюджет 128 MiB (декодируется один, остальные ждут). Запуск на одном ноутбуке, клиент и стенд делят CPU.
**Найденный отказ:** первый прогон шёл с лимитом S3 512M, и на 20 параллельных PUT процесс SeaweedFS перезапустился (RestartCount 1, логов завершения нет — kill по памяти). 18 из 20 загрузок получили корректный 503, их pending-строки остались (тогдашняя версия компенсации сначала удаляла объект и при недоступном S3 сохраняла строку) и затем были найдены reconciler как 19 stale pending, вместе с одной от теста отказа S3. Лимит S3 поднят до 1G: в повторе 0 рестартов при `memory.peak` ≈ 1 GiB. Этот пик включает page cache записываемых файлов, который ядро может вытеснить.
### Трек 2: внедрение ошибок (grace = 1 мин для эксперимента, 15 мин в стенде)
Методика `scripts/track2/run_track2.py faults`. Периодический reconciler на время теста останавливается. Сбои вносятся напрямую: в S3 через `scripts/track2/s3tool.py` (SigV4 на stdlib, запускается в одноразовом контейнере в сети `data`), в БД через `psql`.
| Сбой (сторона) | Ожидание | dry-run | apply |
| --- | --- | --- | --- |
| F1 объект без строки (S3) | удалить после grace | orphan_object | удалён |
| F2 потеряна строка неиспользуемого U3 (БД) | объект стал сиротой → удалить | orphan_object | удалён |
| F3 потерян объект используемого U2 (S3) | **метаданные не трогать**, пометить | missing_object | `missing_at` выставлен; GET метаданных 200, content 404, сообщение по-прежнему ссылается на U2 |
| F4 падение между PUT и ready (pending + объект, 1 ч) | удалить строку, затем объект | stale_pending | удалены оба |
| F5 падение до PUT (pending без объекта, 1 ч) | удалить строку | stale_pending | удалена |
| F7 загрузка «в процессе» (свежие pending + объект) | не трогать | не найдена (row известен) | цела |
| F8 свежий объект без строки | не трогать | `skip: younger than grace` | цел |
| U1 используемый, исправный | не трогать | — | скачивается, sha256 верный |
- **Dry-run ничего не меняет:** счётчики S3-объектов, строк, pending и missing до и после совпадают (`dry_run_changed_nothing: true`).
- **Первый apply:** 7 исправлений, 0 ошибок.
- **Повторный apply:** 0 исправлений, только `skip` свежего F8 — проход идемпотентен.
- **Восстановление:** после возврата объекта U2 «из бэкапа» (те же байты) apply выдаёт `recovered=1`, снимает `missing_at`, и скачивание отдаёт исходный sha256.
- **Сторонние находки:** dry-run отдельно учитывает находки вне чата эксперимента (`other_findings_outside_experiment`) — это остатки предыдущих прогонов.
**Почему это безопасно.** Порядок «сначала LIST S3, потом скан БД» плюс «pending-строка пишется до PUT» означают, что у любого объекта из листинга строка уже есть. Перед каждым разрушающим действием есть повторная проверка: сирота — `ObjectKeyKnown` в БД, missing — `StatObject`, pending — `DELETE … WHERE status='pending'`. Удаляются только объекты без строк и pending-строки; ни одна из них не может быть в `message_attachments`, потому что привязать можно только ready. Используемые метаданные никогда не удаляются. Grace 15 мин намного больше бюджета загрузки (60 с). Если `UPDATE → ready` проигрывает гонку с reconciler, загрузка отвечает 503, а не 201.
### Трек 2: стоимость обхода
`scripts/track2/run_track2.py cost`: в БД добавляются N ready-строк (SQL `generate_series`), в S3 — N объектов по 100 B. Каждый размер замеряется трижды в dry-run, после замеров bench-данные удаляются.
| Объектов | list S3, мс | скан БД, мс | всего, мс | мкс/объект | пик памяти reconciler, MiB | находок |
| --- | --- | --- | --- | --- | --- | --- |
| 1 229 | 52 | 6–9 | 59–61 | 48–50 | 10.1–10.9 | 0 |
| 5 229 | 258–345 | 62–70 | 326–408 | 62–78 | 15.8–17.2 | 0 |
| 20 229 | 1321–1537 | 41–95 | 1404–1618 | 69–80 | 30.8–31.2 | 0 |
**Вывод:** стоимость линейна, примерно 70 мкс и 1 КБ RAM на объект. Больше 90% времени занимает постраничный LIST в S3 (по 1000 ключей). На 20k объектов ложных срабатываний 0. При частоте раз в 10 минут нагрузка ничтожна. **Ограничение:** все ключи держатся в памяти, на 10M объектов это ~1 ГБ. Дальше нужен обход по префиксам `attachments/<chat_id>/` или потоковое слияние двух отсортированных списков: ключи S3 и `ORDER BY object_key` в БД.
### Сводка отказов
| Воздействие | Что ожидаем | Что наблюдали | Восстановление / потеря данных |
| --- | --- | --- | --- |
| `docker stop` обслужившей API-реплики | LB уводит трафик | первая успешная запись через ~4 с, 0 дублей; файл скачивается через другую | без потерь |
| Restart postgres+valkey+s3+api | данные, сессия и файл живы | PASS, тот же токен работает | без потерь |
| Остановка S3 | 503 только на вложениях | upload/download 503 за 2 с, текст и ready работают | после старта S3 сразу; pending-строк не осталось |
| SeaweedFS убит по памяти (лимит 512M) | 503, без 201 на несохранённое | 18× 503, 2× 201 | 19 pending-строк убраны reconciler; лимит поднят до 1G |
| Внедрённые orphan/missing/pending | найти, исправить безопасно | 5/5 найдены, повторный apply = no-op | missing-байты невосстановимы без бэкапа: метаданные помечены и сохранены |
## Ограничения и следующие шаги
- Один Docker-host, по одному PostgreSQL, S3-узлу и LB: выдерживается отказ одной API-реплики и рестарт стенда, но не потеря хоста или диска S3. В SeaweedFS нет репликации томов.
- Тело загрузки буферизуется в RAM до 10 MiB на слот. Это ограничено и измерено, но не полностью потоковый режим.
- Полное декодирование нужно для отсева повреждённых файлов и стоит CPU: 40 одновременных загрузок 10 МБ занимают ~12 с на 2×1 CPU.
- Объект, у которого обнаружен `missing`, невосстановим без бэкапа. Reconciler только помечает его, и API отдаёт 404 на content.
- Reconciler хранит все ключи в памяти (ограничение указано выше). `size_mismatch` только сообщается, автоматически не исправляется.
- Цель failover-теста выбирается по `X-Instance-Id` обслужившего ответа, а HAProxy раздаёт запросы по кругу, поэтому без вмешательства тест детерминированно останавливал api-2. Для проверки api-1 перед запуском был сделан один лишний запрос через LB (`curl http://localhost:8080/health/live`), сдвигающий очередь; так получен прогон с остановкой api-1.
- CI-job со сборкой стенда и `make test` не добавлен: workflow skeleton проверяет только контракт.