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

27 KiB
Raw Blame History

Отчёт — лабораторная 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.

Подготовка и запуск

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 продолжит работать с новым секретом.

Готовность:

curl -fsS http://localhost:8080/health/ready

Если shell не видит опубликованные порты Docker (например, агент запущен в отдельном контейнере), проверки выполняются из контейнера в сети стенда:

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:

docker network connect mtusi2026lab_default <shell-container>

Это изменение только тестового окружения; в приложении localhost:8080 остаётся штатным адресом при опубликованном порте.

Проверки

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 намеренно оставляет одну реплику остановленной; восстановление:

docker compose --env-file .env up -d --scale api=2 api

Остановка

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 на отдельном стенде. Это проверено на практике.

Архитектура и решения

Клиент
  |
  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:

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 — нет.