forked from mtusi2026/mtusi2026lab4
Add two API replicas, safe object reconciliation, upload validation, regression tests and documented load experiments.
187 lines
27 KiB
Markdown
187 lines
27 KiB
Markdown
# Отчёт — лабораторная 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% в обоих раундах, все запросы успешны. Следующий шаг — больше повторов на выделенном хосте, независимый генератор и профиль нативных выделений декодера.
|