Files
mtusi2026lab4/REPORT.md
T
2026-11-06 19:06:21 +03:00

375 lines
27 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
- Автор, группа: заполняется студентом перед сдачей (ФИО, группа).
- Целевая оценка: **4** (уровень 3 и все пункты уровня 4). Дополнительный
исследовательский трек не заявлен.
- Commit/PR: локальная ветка поверх `68968c4`; ссылка на PR добавляется после
публикации.
- Использованные источники, библиотеки и помощь ИИ: контракт курса
(`contracts/`), публичные тесты (`tests/`), документация RustFS, AWS SDK for
Go v2, Fiber v3, pgx. ИИ-ассистент использовался для генерации и ревью кода,
текста отчёта и тестовых сценариев; все результаты ниже получены на реально
запущенном стенде.
## Запуск из чистого clone
### Требования
- Linux с Docker Engine 29.9.1 и Docker Compose v5.6.0 (проверено на этих
версиях; нужен обычный bridge network и named volumes).
- Не менее ~5 ГБ свободного места: образы Go builder, RustFS, PostgreSQL,
Redis, HAProxy, Python и volumes. При переполнении диска стенд не считается
исправным.
- `make`, `curl`, Python 3.12 для HTTP-проверок. Go для локальных проверок:
модуль объявляет `go 1.27.1`, Dockerfile использует
`golang:1.27.1-alpine`; локальный `go1.25.6` собирает проект через
авто-загрузку toolchain.
- Версии образов закреплены: `rustfs/rustfs:1.0.4`, `rustfs/rc:v0.1.36`,
`postgres:16.10-alpine`, `redis:7.4.7-alpine`, `haproxy:3.2.6-alpine`,
`python:3.12-alpine`, `alpine:3.22`, `grafana/k6:1.3.0`.
### Подготовка и запуск
```sh
git clone <repo> && cd mtusi2026lab4
cp .env.example .env
# Отредактировать .env: POSTGRES_PASSWORD, S3_ROOT_ACCESS_KEY,
# S3_ROOT_SECRET_KEY, S3_SECRET_ACCESS_KEY. Значения не коммитить.
# S3_ACCESS_KEY_ID по умолчанию messenger-api; это имя scoped IAM-user,
# а не root-пользователь RustFS.
docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build
```
Порядок запуска: `postgres`, `redis`, `rustfs` → healthchecks → одноразовый
`s3-init` (bucket, private access, IAM-user и policy) → `migrate` (встроенные
миграции) → `api` (2 реплики) и `reconciler` → `haproxy`. API запускаются с
`RUN_MIGRATIONS=false`, поэтому миграции не гоняются репликами.
Если позже изменить `S3_SECRET_ACCESS_KEY` в `.env`, bootstrap нужно повторить
вручную: `docker compose run --rm --no-deps -T s3-init`. IAM-user обновится,
API продолжит работать с новым секретом.
Готовность:
```sh
curl -fsS http://localhost:8080/health/ready
```
Если shell не видит опубликованные порты Docker (например, агент запущен в
отдельном контейнере), проверки выполняются из контейнера в сети стенда:
```sh
docker run --rm --network mtusi2026lab_default -v "$PWD:/work:ro" -w /work \
python:3.12-alpine python3 tests/smoke.py --base-url http://haproxy:8080
```
Для hook-тестов (`persistence`, `failover`) удобнее подключить сам shell к сети
стенда и использовать `BASE_URL=http://haproxy:8080`:
```sh
docker network connect mtusi2026lab_default <shell-container>
```
Это изменение только тестового окружения; в приложении `localhost:8080`
остаётся штатным адресом при опубликованном порте.
### Проверки
```sh
make check
python3 -m venv .venv && .venv/bin/pip install -r requirements-dev.txt
make validate PYTHON=.venv/bin/python
cd app && go vet ./... && go test ./... && go build ./... && cd ..
make test BASE_URL=http://localhost:8080
make test-persistence BASE_URL=http://localhost:8080 ACTION_SCRIPT=scripts/restart.sh
make test-failover BASE_URL=http://localhost:8080 ACTION_SCRIPT=scripts/stop-one.sh
make test-concurrency BASE_URL=http://localhost:8080
make test-attachments BASE_URL=http://localhost:8080
make test-upload-memory
make test-reconcile
make test-private-bucket
make test-attachment-failover
make test-interrupted-upload
```
Если `localhost` недоступен, заменить `BASE_URL` на `http://haproxy:8080` и
выполнять из контейнера/сети стенда, как описано выше. `make test-failover`
намеренно оставляет одну реплику остановленной; восстановление:
```sh
docker compose --env-file .env up -d --scale api=2 api
```
### Остановка
```sh
docker compose --env-file .env down # volumes сохраняются
docker compose --env-file .env down -v # намеренное удаление учебных данных
```
`down -v` удаляет PostgreSQL, Redis и RustFS volumes. При смене
`POSTGRES_PASSWORD` на уже существующем `pgdata` PostgreSQL не пустит API:
нужно либо вернуть прежний пароль, либо осознанно пересоздать volume на
отдельном стенде. Это проверено на практике.
## Архитектура и решения
```text
Клиент
|
v
HAProxy :8080 (единственный опубликованный вход, stats :8404)
|
+--> api-1 (Go/Fiber, expose 8080) --+
+--> api-2 (Go/Fiber, expose 8080) --+--> PostgreSQL 16.10 (метаданные, истина)
+--> Redis 7.4 (сессии, AOF)
+--> RustFS 1.0.4 (приватные байты)
|
reconciler (pending/orphan cleanup)
s3-init (one-shot): bucket + anonymous=private + IAM messenger-api + policy
migrate (one-shot): встроенные миграции 0001..0003
```
| Роль | Где | Ответственность |
| --- | --- | --- |
| Вход | `haproxy` | round-robin, health `GET /health/ready`, 16 слотов DNS |
| API | `api` × 2 | stateless HTTP, авторизация, streaming upload/download |
| Метаданные | `postgres` | пользователи, чаты, сообщения, idempotency, attachments |
| Сессии | `redis` | SHA-256 digest токена, absolute TTL |
| Байты | `rustfs` | private bucket, object key назначает сервер |
| Bootstrap | `s3-init` | идемпотентные bucket/IAM/policy |
| Сверка | `reconciler` | stale pending и orphan objects после grace period |
### Что перенесено из lab3
Сохранены пользователи, Basic-login, сессии в Redis, чаты, сообщения,
идемпотентность POST сообщений, пагинация, HAProxy, две API-реплики,
readiness с PostgreSQL/Redis, graceful shutdown, `X-Request-Id` и
`X-Instance-Id`, а также форматы ошибок. Текстовые сообщения остаются
валидными; `attachment_ids` по умолчанию `[]`.
### Что добавлено в lab4
- Метаданные вложения хранятся в PostgreSQL, байты — только в RustFS. В API нет
ни локального постоянного файла оригинала, ни публичного URL bucket.
- Object key: `attachments/<chat_id>/<attachment_id>`. Имя файла от клиента
используется только для отображения и никогда не становится путём.
- Загрузка: авторизация по членству в чате → проверка filename и
Content-Type → ограниченное чтение тела во временный файл с SHA-256 →
MIME/DecodeConfig/full decode → `pending` row → S3 PUT → `ready` row → 201.
201 означает, что сохранены и объект, и метаданные.
- Если процесс упал после `pending`, но до `ready`, reconciler удаляет и row, и
объект после grace period. Если объект остался без row (крайне узкое окно
или ручное вмешательство), reconciler удаляет orphan.
- `/health/ready` требует PostgreSQL, Redis и S3 `HeadBucket`; при SIGTERM
сначала выставляется флаг shutdown и readiness начинает отдавать 503.
- Bucket не опубликован, console выключена. API и reconciler используют
отдельного IAM-user с policy только на `attachments/*`; root-credential есть
только у `s3-init`.
- `/health/ready` и все ответы API по-прежнему содержат `X-Request-Id` и
`X-Instance-Id`.
### Как посмотреть bucket без публичного порта
S3 API и admin console не опубликованы, поэтому осмотр и проверки выполняются
одноразовым контейнером в сети стенда. Тот же приём используют
`scripts/check-private-bucket.sh` и `scripts/verify-reconcile.sh`:
```sh
docker run --rm --network mtusi2026lab_default --env-file .env -e HOME=/tmp \
--entrypoint /bin/sh rustfs/rc:v0.1.36 -c \
'rc alias set app "$S3_ENDPOINT" "$S3_ACCESS_KEY_ID" "$S3_SECRET_ACCESS_KEY" >/dev/null &&
rc ls "app/$S3_BUCKET/attachments/"'
```
Контейнер использует scoped-ключ API, а не root; для административных действий
(например, повторного bootstrap) есть отдельный root-ключ у `s3-init`.
### Транзакционные границы и согласованность
1. Валидация и чтение тела заканчиваются до создания строки. Обрыв соединения
не создаёт ни row, ни object.
2. `INSERT ... status='pending'` коммитится до S3 PUT. Это намеренно: при
падении процесса остаётся указатель, по которому reconciler найдёт объект.
3. S3 PUT выполняется с `Content-Length` и `Content-Type`; при ошибке —
компенсирующее удаление объекта и pending-строки.
4. `UPDATE ... SET status='ready'` выполняется после успешного PUT. Ошибка
обновления также запускает компенсацию.
5. Сообщение и `message_attachments` вставляются в одной транзакции с
idempotency-записью. Все вложения проверяются на принадлежность чату и
статус `ready` в той же транзакции.
6. Fingerprint идемпотентности: для сообщений без вложений сохранён старый
`sha256(text)`; с вложениями добавлены канонически отсортированные UUID.
7. Reconciler работает с grace period (по умолчанию 900 с), поэтому свежая
загрузка не может быть удалена как «зависшая».
### Лимиты, таймауты и память
| Механизм | Значение | Где |
| --- | --- | --- |
| Максимальный размер оригинала | 10 MiB = 10 485 760 байт | config + SQL constraint |
| Максимум пикселей | 40 000 000 | config, проверяется по header до decode |
| Глобальный HTTP body | 10 MiB + 1 MiB | Fiber `BodyLimit` |
| JSON body | 1 MiB | `common.BindJSON` |
| Копирование upload | 32 KiB buffer, `io.LimitReader` | handler |
| Бюджет decode | 256 MiB weighted semaphore | `attachments/image.go` |
| Upload/download timeout | 30 с / 60 с | handler context |
| S3 health | 2 с | `HeadBucket` |
| Pending/orphan grace | 900 с | reconciler |
Тело не читается через `io.ReadAll` для upload и не буферизуется Fiber
(`StreamRequestBody: true`). Даже отклонённый по `Content-Length` запрос
дочитывается только в пределах `max + 1 MiB`, чтобы клиент успел получить 413,
а не connection reset.
## Доказательства критериев
Все команды выполнены на запущенном стенде 2026-10-31; smoke, негативные
сценарии, reconciler и interrupted upload повторены 2026-11-06 после
рефакторинга с тем же результатом. `BASE_URL` в лог-файлах —
`http://haproxy:8080` (shell подключён к сети стенда).
| Критерий | Команда/сценарий | Наблюдаемый результат | Файл |
| --- | --- | --- | --- |
| Публичный smoke lab4 | `make test BASE_URL=http://haproxy:8080` | `PASS: lab4 public API scenario` | `evidence/smoke.txt` |
| S3 в общем стенде, приватный bucket | `make test-private-bucket` | anonymous GET → 403; scoped PUT/HEAD в `attachments/` разрешён, вне prefix и CreateBucket запрещены | `evidence/private-bucket.txt` |
| Идемпотентный bootstrap | `docker compose run --rm --no-deps -T s3-init` дважды | оба запуска `S3 bootstrap complete`, exit 0 | `evidence/s3-bootstrap.txt` |
| Upload 201 ready + checksum | public smoke | `status=ready`, `variants=[]`, `error_code=null`, SHA-256 и size совпали, download байт-в-байт | `evidence/smoke.txt` |
| Доступ участника и запрет постороннему | `make test-attachments` | bob скачал оригинал; eve получила 404 на metadata и bytes | `evidence/attachments-negative.txt` |
| Слишком большой файл | `make test-attachments` | 10 MiB + 1 → 413, без 5xx | `evidence/attachments-negative.txt` |
| Повреждённое изображение | `make test-attachments` | PNG-сигнатура с битым телом → 415 | `evidence/attachments-negative.txt` |
| Подмена MIME | `make test-attachments` | PNG с `Content-Type: image/jpeg` → 415 | `evidence/attachments-negative.txt` |
| Чужой attachment_id | `make test-attachments` | 404 для metadata/content; чужой чат → 404 | `evidence/attachments-negative.txt` |
| Вложение другого чата | `make test-attachments` | привязка к другому чату → 404 в обе стороны | `evidence/attachments-negative.txt` |
| Пользовательская ошибка не 500 | `make test-attachments` | все негативные сценарии 400/404/413/415 | `evidence/attachments-negative.txt` |
| Upload → остановка реплики → download с другой | `make test-attachment-failover` | upload принят `ad8141b5e17c`, download обслужен `2229551f45ac`, SHA-256 совпал | `evidence/attachment-failover.txt` |
| Обрыв загрузки | `make test-interrupted-upload` | rows 52 → 52, objects 52 → 52, temp files 0 | `evidence/interrupted-upload.txt` |
| Reconciliation: stale pending | `make test-reconcile` | dry-run ничего не изменил; реальный прогон `deleted_rows=1 deleted_objects=1` | `evidence/reconcile.txt` |
| Reconciliation: fresh pending | `make test-reconcile` | строка и объект остались при `grace=1s` | `evidence/reconcile.txt` |
| Reconciliation: orphan object | `make test-reconcile` | после удаления row объект удалён `deleted_objects=1` | `evidence/reconcile.txt` |
| Reconciliation: ready не трогается | `make test-reconcile` | row и объект ready-вложения остались | `evidence/reconcile.txt` |
| ≥10 одновременных загрузок, пик RAM | `make test-upload-memory` | 10 × 7 563 763 B, 2 реплики, peak 354.1 MiB total, 174.1/180.1 MiB на реплику при лимите 512 MiB | `evidence/upload-memory.json`, `evidence/upload-memory-run.txt` |
| Persistence после restart | `make test-persistence ACTION_SCRIPT=scripts/restart.sh` | PASS; `StartedAt` PostgreSQL/Redis/RustFS/HAProxy/API изменился, данные и сессия сохранились | `evidence/persistence.txt`, `evidence/persistence-containers.txt` |
| Failover одной API-реплики | `make test-failover ACTION_SCRIPT=scripts/stop-one.sh` | 2 реплики до отказа, 118 успешных записей, 1 переходная ошибка, recovery 2.557 с, дублей нет | `evidence/failover.txt` |
| Конкурентная идемпотентность | `make test-concurrency` | 12 запросов, 2 реплики, одна запись | `evidence/idempotency.txt` |
| Readiness отражает PostgreSQL | stop/start `postgres`, запрос `/health/ready` внутри API | 503 при остановке, 200 после восстановления | `evidence/readiness-postgres.txt` |
| Readiness отражает Redis | stop/start `redis` | 503 при остановке, 200 после восстановления | `evidence/readiness-redis.txt` |
| Readiness отражает S3 | stop/start `rustfs` | 503 при остановке, 200 после восстановления | `evidence/readiness-s3.txt` |
| Graceful shutdown | SIGTERM/`docker stop` при restart/failover | процесс пишет `shutting down`, readiness 503, соединения завершаются; hooks укладываются в лимит | `evidence/persistence.txt`, `evidence/failover.txt` |
| Offline-контракт | `make check`, `make validate` | оба PASS | вывод команд в этом отчёте |
## Эксперименты и отказы
### Профиль стенда
Docker на Linux, Compose bridge network, лимиты из `.env`:
API — 0.5 CPU / 512 MiB на реплику, PostgreSQL — 1.0 CPU / 512 MiB,
Redis — 0.5 CPU / 256 MiB, RustFS — 1.0 CPU / 512 MiB,
HAProxy — 0.5 CPU / 128 MiB. Это учебный стенд, а не production-измерение;
результаты зависят от хоста и общего Docker daemon.
### Нагрузка POST сообщений
`python3 tests/load.py --base-url http://haproxy:8080 --duration 15 --concurrency 8 --output evidence/load.json`
| Показатель | Значение |
| --- | --- |
| Длительность / concurrency | 15.216 с / 8 |
| Успешные / ошибки | 6249 / 0 |
| Successful RPS | 410.689 |
| p50 / p95 / p99 | 18.104 / 31.058 / 46.769 мс |
Это closed-loop генератор: он страдает coordinated omission, не делает
прозрачных retry и измеряет только успешные HTTP-подтверждения. Числа
показывают, что стенд не деградировал после добавления S3, но не являются
пределом пропускной способности.
### Память при одновременных загрузках
Методика: 10 потоков одновременно отправляют один и тот же сгенерированный
PNG 1800×1400 (7 563 763 байт, 2.52 Мп) через HAProxy; host-side скрипт
опрашивает Docker Engine stats каждые 50 мс и суммирует `memory_stats.usage`
двух API-контейнеров. Перед прогоном API перезапущены, чтобы baseline не
содержал page cache прошлых тестов.
| Показатель | Значение |
| --- | --- |
| Baseline total | 14.7 MiB |
| Peak total | 354.1 MiB |
| Peak на реплику | 174.1 / 180.1 MiB |
| Лимит на реплику | 512 MiB |
| Время 10 загрузок | 2.60 с |
| Проверка download | SHA-256 совпал |
Одиночная загрузка того же файла на свежем стенде дала peak 280.4 MiB total
(142.9/137.5 MiB на контейнер). Рост при переходе от 1 к 10 одновременным
загрузкам существенно меньше 10×: тело не буферизуется целиком, decode
ограничен семафором. Docker stats включает page cache, поэтому абсолютные
значения выше, чем «чистая» heap-память Go.
### Persistence
`scripts/restart.sh` перезапускает `postgres redis rustfs haproxy api` без
удаления volumes. В `evidence/persistence-containers.txt` видно, что
`StartedAt` всех пяти сервисов изменился, а публичный тест после этого снова
прочитал исходное сообщение, сессию и оригинал вложения. Это подтверждает, что
hook действительно перезапустил процессы, а не только вернул 0.
### Failover
`scripts/stop-one.sh` сопоставляет `TARGET_INSTANCE_ID` с hostname контейнера и
оставляет ровно эту реплику остановленной. Публичный тест наблюдал 2 реплики,
отправил 118 успешных записей за 15 секунд, допустил 1 переходную ошибку,
зафиксировал восстановление за 2.557 с и не нашёл дублей. Отдельный
`verify-attachment-failover.sh` загрузил файл через одну реплику, остановил её
и скачал тот же SHA-256 через другую.
### Матрица отказов
| Воздействие | Ожидание | Наблюдение | Восстановление / потери |
| --- | --- | --- | --- |
| Остановлена одна API-реплика | HAProxy исключает её, вторая продолжает | 2 реплики до, 118 успешных записей, 1 переходная ошибка | 2.557 с; подтверждённые данные не потеряны |
| Upload, затем остановка принявшей реплики | Файл доступен через другую | download обслужила другая реплика, SHA-256 совпал | без потерь, 1 попытка |
| Restart всего стенда | Сессии, сообщения и файлы сохраняются | persistence PASS; все `StartedAt` изменились | volumes сохранены, повторный логин не нужен |
| Остановлен RustFS | readiness 503, новые upload не принимаются | `/health/ready` → 503 | после старта → 200, данные в volume |
| Остановлен Redis | readiness 503 | `/health/ready` → 503 | после старта → 200; сессия пережила restart в persistence-тесте |
| Остановлен PostgreSQL | readiness 503 | `/health/ready` → 503 | после старта → 200; данные в volume |
| Обрыв HTTP-загрузки | Нет row/object/temp | rows и objects не изменились, temp files 0 | автоматически, без reconciler |
| Падение между pending и ready | reconciler удаляет пару после grace | dry-run + реальный прогон | до 900 с удержания, затем очистка |
| Orphan object без row | reconciler удаляет после grace | `deleted_objects=1` | до 900 с, затем очистка |
| Переполнение диска хоста | Не гарантируется | один прогон дал 500/503 (`No space left on device`) | после очистки build cache повторные прогоны зелёные; это ограничение стенда, не заявленная HA-функция |
## Ограничения и следующие шаги
- Стенд не является production-HA: PostgreSQL, Redis и RustFS — одиночные
контейнеры с volume; HAProxy и API реплицированы, но хост и хранилища не
кластеризованы. Остановка БД или S3 — это отказ, а не прозрачное
переключение.
- Reconciler — safety net, а не мгновенная транзакция. Между S3 PUT и
`status=ready` существует окно, в котором объект уже есть, но 201 ещё не
возвращён; после grace периода такая пара удаляется. Клиент, не получивший
201, должен повторить загрузку, что создаст новый object key.
- Grace period 900 с и интервал 300 с — учебные значения. Для реальной системы
их нужно согласовать с максимальной длительностью загрузки и SLA очистки.
- Лимит 10 MiB / 40 Мп и таймауты 30/60 с проверены на локальном стенде. На
медленном канале загрузка 10 MiB может не уложиться в 30 с; это осознанное
ограничение, а не обещание поддерживать любой RTT.
- Нет presigned URL, фоновой обработки, thumbnails и вариантов изображений:
контракт lab4 этого не требует, а обязательный proxy download оставлен
единственным способом доступа к байтам.
- Нет отдельного API для удаления вложений и сообщений; очистка выполняется
только reconciler-ом для abandoned данных. Пользовательские данные в
учебном стенде не удаляются автоматически.
- Нагрузка измерена closed-loop генератором; для честного throughput нужен
open-loop/k6 с фиксированным arrival rate и отдельным профилем upload.
- Проверка private bucket и scoped policy выполняется изнутри Compose network;
снаружи S3 API и console недоступны, что и требуется.
- Все секреты хранятся только в локальном `.env`; в отчёт, evidence и git они
не попадают. `CHANGELOG.md` теперь отслеживается, `.env` — нет.