Files
qrtx dc46ac213d feat(storage): add RustFS attachments and presigned uploads
Add two API replicas, safe object reconciliation, upload validation, regression tests and documented load experiments.
2026-11-12 10:16:39 +03:00

27 KiB
Raw Permalink Blame History

Отчёт — лабораторная 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% в обоих раундах, все запросы успешны. Следующий шаг — больше повторов на выделенном хосте, независимый генератор и профиль нативных выделений декодера.