Add two API replicas, safe object reconciliation, upload validation, regression tests and documented load experiments.
27 KiB
Отчёт — лабораторная 4
- Автор, группа: Пинаев Олег Константинович, БПИ2302.
- Целевая оценка: 5, трек 1 — прямой upload по presigned URL.
- Версия: локальная реализация, PR пока не опубликован. Образы API и SHA-256 исходников/конфигурации на момент проверки сохранены в final-regression.json. После проверки оформлены отчёт и документация, удалены устаревшие результаты; код приложения не менялся.
- Источники:
README.md,COURSE.md,contracts/, документация Node.js, Nginx, Sharp, AWS S3 и RustFS. ИИ использовался при разработке, подготовке проверок, замеров и отчёта.
Запуск из чистого clone
Нужны Docker Desktop с Linux-контейнерами и Compose, Python 3.9+, Node.js 24.20.0, pnpm 10.14.0. На Windows restart-hook использует Git Bash; при нестандартной установке задаётся GIT_BASH. Наблюдатели памяти используют Linux /proc и cgroup v2 внутри контейнеров.
Образы закреплены: node:24.20.0-bookworm-slim, postgres:17.6-bookworm, redis:7.4.5-alpine, nginx:1.30.6-alpine, rustfs/rustfs:1.0.4. Приложение — NestJS 12 / Fastify 5, Prisma 7.10.0, Sharp 0.35.5; конкретные зависимости закреплены в pnpm-lock.yaml.
cp .env.example .env
pnpm install --frozen-lockfile
docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build --wait --wait-timeout 180
chmod +x scripts/restart.sh scripts/stop-one.sh
python -X utf8 test/final-regression.py
migrate применяет миграции PostgreSQL. Одноразовый s3-init создаёт приватный bucket и ограниченные роли. API ждут миграции, хранилища и bootstrap; Nginx и reconciler — готовность API. Повторный bootstrap идемпотентен. Перед проверками должны быть healthy все семь runtime-контейнеров и доступны обе API через /health/ready. При обновлении существующего стенда возможен переходный unhealthy Nginx во время смены upstream; runner ждёт фактического восстановления маршрутов.
API доступен на http://127.0.0.1:8080, документация — /swagger и /docs, OpenAPI — /swagger-json. 127.0.0.1:9000 — отдельный listener Nginx для presigned PUT, не открытая консоль RustFS.
| Настройка | Фактическое использование |
|---|---|
APP_PORT |
Публичный порт Nginx; внутри API всегда 8080 |
S3_PUBLIC_PORT, S3_PUBLIC_ENDPOINT |
Listener PUT и origin подписи; адрес и порт должны совпадать |
S3_ENDPOINT, S3_REGION, S3_BUCKET |
В Compose закреплены как http://s3:9000, us-east-1, messenger-attachments; одноимённые поля примера не переопределяют эти константы |
POSTGRES_DB/USER/PASSWORD |
Общая БД; Compose собирает DATABASE_URL, адрес Redis задаёт через CACHE_URL |
SESSION_TTL_SECONDS, IDEMPOTENCY_TTL_SECONDS |
По умолчанию 3600 и 86400 с; сессии и идемпотентность хранятся в PostgreSQL |
DB_POOL_MAX, CACHE_PREFIX |
По умолчанию 15 соединений на API и общее пространство ключей Redis; у сверщика пул 2 |
S3_ROOT_*, S3_API_*, S3_RECONCILER_* |
Раздельные credentials bootstrap, API и сверщика |
MAX_UPLOAD_BYTES, MAX_IMAGE_PIXELS |
Не более 10485760 байт и 40000000 пикселей; можно уменьшить |
UPLOAD_BODY_TIMEOUT_MS |
Общий срок приёма тела, по умолчанию 15000 мс |
DIRECT_UPLOAD_TTL_SECONDS |
Максимальный срок URL, по умолчанию 60 с, допустимо 1–300 с |
ORPHAN_GRACE_SECONDS, RECONCILE_INTERVAL_SECONDS |
Grace 600 с и пауза между проходами 60 с |
UPLOAD_MEMORY_PROFILE |
0 штатно; 1 только для подробного эксперимента |
Архитектура и решения
flowchart LR
C[Клиент] --> N[Nginx: API]
N --> A1[API 1]
N --> A2[API 2]
A1 --> P[(PostgreSQL)]
A2 --> P
A1 --> R[(Redis: общий кеш)]
A2 --> R
A1 --> S[(RustFS: приватный bucket)]
A2 --> S
C --> U[Nginx: presigned PUT]
U --> S
W[Reconciler] --> P
W --> S
Proxy upload и скачивание
POST /api/v1/chats/{chat_id}/attachments принимает сырые PNG/JPEG. Fastify собирает ограниченный Buffer; сервис проверяет участие в чате, filename, фактический формат и MIME. Sharp сначала читает размеры и число страниц, отклоняет более 40 млн пикселей, затем выполняет полное декодирование через stats(). Оригинал не перекодируется. Пустые имена, /, \ и управляющие символы отклоняются; filename не используется как S3-путь.
Сервер назначает ключ originals/<chat UUID>/<attachment UUID>. API сохраняет объект, считает SHA-256 и записывает метаданные в PostgreSQL; только после успеха возвращает 201 ready, variants=[], error_code=null. Вложение прикрепляется к сообщению через attachment_ids. Чужое/неизвестное вложение и файл другого чата дают 404; другое содержимое с прежним Idempotency-Key — 409.
GET /api/v1/attachments/{id}/content проверяет членство в чате и передаёт поток RustFS клиенту, без сбора целого файла в Buffer и без redirect. Bucket приватен, анонимный GET проверяется отдельно.
Приём тела ограничен 15 с с заголовков; новые байты не продлевают срок. Таймер снимается после получения тела, проверка и запись имеют отдельные бюджеты. При обрыве неполное тело не попадает в сервис вложений. Для раннего 413 остаток тела ограниченно вычитывается и отбрасывается перед ответом: закрытие upstream не должно превращать 413 в 502 у Nginx. Discard ограничен объёмом и оставшимся исходным сроком приёма, остаток не собирается в память. Нормальный upload по-прежнему использует Buffer до 10 MiB.
Согласованность PostgreSQL и RustFS
Распределённой атомарной транзакции между ними нет. Upload держит транзакционную advisory-блокировку по object key от PUT до завершения метаданных. При ошибке выполняется компенсация под той же блокировкой: повторная проверка записи, возврат уже подтверждённого вложения либо удаление неучтённого объекта. Ошибка БД не трактуется как отсутствие метаданных.
Отдельный reconciler выполняет последовательные проходы; после завершения прохода ждёт 60 с. Grace — 10 минут. Сверщик рассматривает только управляемые UUID-ключи, проверяет БД, возраст, блокировку и свежий HEAD, затем повторно проверяет метаданные перед DELETE. Свежие и связанные объекты сохраняются. Отсутствующий файл существующего Attachment диагностируется, метаданные автоматически не удаляются. Есть dry-run и повторяемый apply. Успех обновляет health-marker, ошибка снимает готовность сверщика.
Транзакция работы с объектом ограничена 20 с, ожидание транзакции — 5 с, idle-транзакция — 15 с. Подключение и SQL — 5 с. S3-операции имеют собственные таймауты; direct-чтение в файл — бюджет 15 с. Падение писателя освобождает транзакционную блокировку.
Presigned upload: трек 1
Клиент считает SHA-256 и вызывает POST /api/v1/chats/{chat_id}/attachment-uploads с filename, MIME, размером и checksum. API проверяет доступ, резервирует ожидаемую загрузку в БД и выдаёт короткий PUT URL. Ключ уникален: staging/<chat UUID>/<upload UUID>. Подпись связывает ключ, Content-Length, Content-Type, SHA-256 и If-None-Match: *; больший TTL клиент запросить не может.
Байты идут через специальный listener Nginx в RustFS, минуя NestJS. Затем владелец вызывает complete. API снова проверяет доступ и срок, потоково читает объект во временный файл, ограничивает длину и считает SHA-256, проверяет изображение через Sharp. Условный серверный COPY публикует originals; в одной транзакции PostgreSQL создаётся ready Attachment и разрешение отмечается completed. Временный файл удаляется и не является хранилищем готового оригинала.
Повтор complete возвращает тот же Attachment. Конкурирующий complete может получить 409 и повториться с прежним ID. Staging и original разделены: повтор PUT по ещё действующей ссылке не меняет готовое вложение. Неверные размер/hash дают 400/413, изображение — 415; нет файла или срок истёк — 409. Старый staging удаляется после истечения разрешения и grace; история разрешений остаётся в БД.
API получает CRUD для originals/* и staging/*, без LIST. Сверщик получает ограниченный LIST/GET/HEAD/DELETE, без PUT. Root доступен только RustFS и bootstrap. Listener PUT пропускает только PUT/OPTIONS на staging-пути.
Доказательства критериев
| Критерий | Команда/сценарий | Результат / доказательство |
|---|---|---|
| Структура и ссылки | python -X utf8 scripts/check_contract.py |
PASS, офлайн-проверка отдельно от приложения |
| Сборка, линтер, unit | docker compose build, pnpm lint, pnpm test --runInBand |
Образы собраны; линтер PASS, 9 suites / 47 tests PASS |
| Обязательный API | tests/smoke.py --base-url http://127.0.0.1:8080 до и после отказов |
PASS: сессии, сообщения, идемпотентность, файл, SHA-256, запрет постороннему |
| Форматы и лимиты | test/attachments.py --lifecycle |
PNG/JPEG побайтно; неверные MIME/изображения/filename, >10 MiB и >40 млн пикселей отклонены |
| Ответ на большой body | test/oversized-uploads.py |
16 Content-Length/chunked-запросов → канонический 413; обе API, следующая загрузка работает. JSON |
| ACL и связь с сообщением | test/attachments.py --lifecycle |
Чужой ID/чат — 404; дубли ID — 400, конфликт idem-key — 409 |
| Приватность и отказ S3 | test/attachments.py --lifecycle |
Анонимный GET — 403; при остановке S3 metadata — 200, content/upload/readiness API — 503; LB исключает неготовые API; после восстановления оригинал доступен |
| Сохранность после restart | test/hooks.py, публичный persistence-hook |
Все 7 runtime действительно перезапущены, ID контейнеров сохранены, прежние данные/сессия/файл доступны. Состояния |
| Отказ каждой API | test/hooks.py, публичный failover-hook |
Обе API остановлены по отдельности, другие сервисы не перезапускались; запись восстановилась за 4,206 / 4,127 с, подтверждённые сообщения сохранены, без дублей |
| Download другой репликой, Swagger | test/replicas.py --base-url http://127.0.0.1:8080 |
Канонические пути/схемы на обеих API; файл и idem-replay доступны после остановки загрузившей реплики |
| Обрыв и deadline | test/upload-interruption.py |
PASS на обеих API и Nginx: нет bytes/metadata после обрыва, медленная передача → 408, следующий upload/download работает. JSON |
| Сбой между PUT и БД, очистка | test/run-reconcile.py |
Реальное завершение writer после PUT, DB outage, dry-run/apply, orphan-delete, защита активного/свежего/связанного, повтор и missing-report — PASS |
| Ограниченные S3-роли | test/s3-permissions.mjs через s3-init |
API без LIST, scanner без PUT; чужие bucket/префиксы, IAM и bucket policy запрещены; anonymous access закрыт |
| Presigned и негативные сценарии | test/direct-uploads.py |
ACL, подпись/заголовки/checksum, PNG/JPEG/MIME/pixels, expiry, concurrent/replay complete, staging cleanup и proxy — PASS. JSON |
| Гарантии выбранного S3 | test/s3-direct-capabilities.mjs через s3-init |
RustFS 1.0.4 проверяет SHA-256, create-only PUT и условный COPY |
| ≥10 upload и RAM | test/direct-upload-load.py |
128/128 upload/download, без ошибок, OOM и рестартов API; точный прогрев. JSON |
| Трек 1: ≥2 размера, сеть и RAM | test/direct-upload-benchmark.py --restart-api --rounds 2 |
24 измеряемых upload, два размера, полный flow, RSS и RX+TX. JSON |
Эксперименты и отказы
Гипотеза и среда
Гипотеза: прямой PUT с серверным COPY уменьшит трафик API; при параллельных больших upload отсутствие нескольких полных входных Buffer должно уменьшить пик памяти. Проверка изображения остаётся на API, поэтому нулевой трафик и гарантированное снижение RSS одиночного запроса не ожидаются.
Вход — детерминированные плохо сжимаемые PNG: 512×512, 787247 байт (~0,75 MiB) и 1792×1792, 9638577 байт (~9,19 MiB). Две API во всех вариантах; PG/Redis/RustFS между сериями не перезапускаются. У direct измеряется весь flow: выдача URL, PUT и complete. Скачивания выполняются после измерения. Прозрачных повторов запросов нет.
Основная память — RSS главного Node-процесса API, отдельно по репликам, через /proc/<PID>/status каждые 50 мс. Наблюдатели в эту RSS не входят. Cgroup memory контейнера, включающая наблюдатель и файловый кеш, сохраняется отдельно. Табличный RSS — наибольший наблюдавшийся пик одной реплики. Сеть — RX+TX обеих API, включая БД/S3 и healthchecks.
Последовательный upload: два размера
Перед каждой серией обе API перезапускаются; четыре прогревочные загрузки со скачиванием, подтверждён прогрев обеих API. Затем три измеряемые загрузки. Два раунда, во втором порядок режимов обратный. Все восемь серий прошли: 24/24, без OOM, исходные байты проверены, fixtures удалены. Диапазоны ниже — по двум раундам, трафик на три файла.
| Файл | Proxy RX+TX, MiB | Direct RX+TX, MiB | Proxy RSS, MiB | Direct RSS, MiB |
|---|---|---|---|---|
| 0,75 MiB | 4,555–4,572 | 2,325–2,330 | 190,12–192,58 | 195,95–198,17 |
| 9,19 MiB | 55,510–55,861 | 27,687–27,750 | 233,62–238,40 | 245,64–248,80 |
Трафик API сократился примерно вдвое. Direct исключает передачу клиентского файла через API в S3, но API читает его из S3 для проверки; публикация — server-side COPY. Снижение RSS в последовательной серии не подтвердилось: у direct пик был выше. Этот результат не подменяется более удачным последующим прогоном.
Конкуренция 1 / 5 / 10
Большой файл, два раунда с обратным порядком, по две волны каждого уровня. Перед каждым случаем API перезапускаются; временный docker-exec клиент делает ровно две прогревочные загрузки/скачивания на каждой API по внутреннему адресу и завершается. Измеряемые запросы идут через публичный Nginx. Адресный прогрев устраняет ситуацию, когда все complete при обычной последовательности запросов попадали на одну реплику.
Все клиенты отправляют заголовки и незавершённое тело до барьера, затем порциями передают остаток за 2 с. У direct второй барьер одновременно выпускает complete и нагружает проверку изображений API. Это closed-loop волны с pacing, не постоянный arrival rate и не поиск предельной производительности.
| Одновременных загрузок всего | Proxy RSS, MiB | Direct RSS, MiB |
|---|---|---|
| 1 | 244,19–252,16 | 240,58–242,36 |
| 5 | 301,10–303,25 | 264,11–273,75 |
| 10 | 369,99–379,35 | 296,47–313,26 |
Все 128 загрузок и 128 скачиваний прошли; ошибок, OOM и рестартов API внутри серии нет. При N=10 каждая API завершила по 10 загрузок за две волны. Direct снизил пик одной API на 10–12% при N=5, 17–20% при N=10, в обоих раундах. Максимальный прирост от прогретого baseline при N=10 — 149,93–150,64 MiB у proxy против 71,76–84,69 MiB у direct.
| N=10, раунды 1 / 2 | Proxy | Direct |
|---|---|---|
| Успешных upload/с | 0,868 / 1,144 | 0,830 / 0,760 |
| p50 полного времени, с | 11,082 / 8,257 | 11,782 / 12,860 |
| p95, с | 13,762 / 10,847 | 12,011 / 13,849 |
| p99, с | 13,806 / 10,851 | 12,075 / 13,949 |
Разбор расхода памяти
Дополнительно сняты 24 HTTP-upload по этапам и 48 вызовов реального валидатора в 16 свежих процессах: Buffer/файл, обычный/выключенный кеш Sharp, два размера и два раунда. Принудительная GC и очистка кеша выполнялись только после измеряемой серии в отдельном процессе; в рабочем API их нет.
Для большого файла медиана прироста arrayBuffers при приёме proxy — 18,38 MiB, при direct-чтении S3 — 9,04 MiB. Основной скачок RSS на Sharp.stats() — около 9,88 / 9,75 MiB, при почти неизменной JS-куче. В изолированном валидаторе с обычным кешем RSS — 162,64–167,71 MiB для Buffer против 130,26–149,82 MiB для файла. После диагностической GC буферы уменьшались с ~9,35 до 0,16 MiB; RSS даже после очистки кеша не всегда падала.
Поток уменьшает необходимость держать целые входные Buffer, но не устраняет декодирование и удержание выделенной памяти. Наблюдение само меняет тайминги: в профилированной HTTP-серии порядок RSS-пиков был противоположен последовательной серии без профиля. Экономия под нагрузкой подтверждается отдельным N=1/5/10 прогоном без внутреннего профилировщика.
Отказы
| Воздействие | Ожидание | Наблюдение |
|---|---|---|
| Остановка API | Запись восстановится ≤10 с, данные/сессия сохранятся | PASS для обеих: 4,206 / 4,127 с, 1 / 2 переходные ошибки, подтверждённые записи сохранены |
| Полный restart | Те же данные и токен после рестарта всех хранилищ | PASS; StartedAt изменился у всех семи runtime, ID контейнеров сохранены |
| Остановка RustFS | Readiness/upload/content — 503, metadata доступны | PASS; после восстановления оригинал скачивается побайтно |
| Writer завершён после PUT до БД | Orphan будет обнаружен и безопасно удалён | PASS: dry-run не удаляет, apply удаляет, повтор безопасен |
| БД недоступна при сверке | Ошибка не означает «объект ничей» | PASS, небезопасного удаления нет |
| Пропали байты существующего Attachment | Диагностика без удаления метаданных | PASS, missing отражён в отчёте |
| Обрыв / медленная передача | Нет неполного вложения, срок приёма ограничен | PASS на обеих API и Nginx, 408, следующий upload/download успешен |
| Истёкшая/подменённая подпись | Не публиковать вложение | PASS: PUT отклонён, expired complete — 409, старый staging очищается |
| Повтор PUT/complete после публикации | Оригинал не изменится | PASS: create-only PUT, идемпотентный complete, исходные байты сохранены |
Ограничения и следующие шаги
Proxy буферизует до 10 MiB и не является сквозным streaming upload. Sharp расходует память декодированных пикселей. Grace не заменяет контроль писателей: прямые изменения S3/БД в обход блокировок не поддерживаются. Сбой между хранилищами может оставить объект до следующей безопасной сверки. История разрешений direct сохраняется; отдельная политика её хранения не реализована.
Серии локальные и короткие: два раунда, общие фоновые процессы/кеши, периодическое сэмплирование, генератор на том же хосте. Быстрые пики могли быть пропущены; это наблюдавшиеся значения, не верхняя граница RAM. Общая память RustFS/ОС/стенда не объявляется сэкономленной. Длительная нагрузка, большие чаты и другая машина этими сериями не проверены.
Итог исследования: direct примерно вдвое уменьшил трафик API на двух размерах. При последовательном upload преимущества RSS нет; при десяти одновременных больших upload пик одной API снизился на 17–20% в обоих раундах, все запросы успешны. Следующий шаг — больше повторов на выделенном хосте, независимый генератор и профиль нативных выделений декодера.