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

187 lines
27 KiB
Markdown
Raw Permalink 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
- Автор, группа: **Пинаев Олег Константинович, БПИ2302**.
- Целевая оценка: **5, трек 1 — прямой upload по presigned URL**.
- Версия: локальная реализация, PR пока не опубликован. Образы API и SHA-256 исходников/конфигурации на момент проверки сохранены в [final-regression.json](evidence/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`.
```sh
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` только для подробного эксперимента |
## Архитектура и решения
```mermaid
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](evidence/oversized-uploads.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 контейнеров сохранены, прежние данные/сессия/файл доступны. [Состояния](evidence/hooks.json) |
| Отказ каждой 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](evidence/upload-interruption.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](evidence/direct-uploads.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](evidence/direct-upload-load.json) |
| Трек 1: ≥2 размера, сеть и RAM | `test/direct-upload-benchmark.py --restart-api --rounds 2` | 24 измеряемых upload, два размера, полный flow, RSS и RX+TX. [JSON](evidence/direct-upload-benchmark-restarted.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% в обоих раундах, все запросы успешны. Следующий шаг — больше повторов на выделенном хосте, независимый генератор и профиль нативных выделений декодера.