# Отчёт — лабораторная 4 - Автор, группа: Булла Максим, БПИ2301 - Целевая оценка: **4** - Commit/PR: ``b4239f8`` - Использованные источники, библиотеки и помощь ИИ: контракт курса (`contracts/`), публичные тесты (`tests/`), документация RustFS, AWS SDK for Go v2, Fiber v3, pgx. ИИ-ассистент (DeepSeek v4.1 Flash) использовался для генерации и ревью кода, текста отчёта и тестовых сценариев; все результаты ниже получены на реально запущенном стенде. ## Запуск из чистого 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 && 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 ``` Это изменение только тестового окружения; в приложении `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//`. Имя файла от клиента используется только для отображения и никогда не становится путём. - Загрузка: авторизация по членству в чате → проверка 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` — нет.