Files
mtusi2026lab4/REPORT.md
T

379 lines
52 KiB
Markdown
Raw 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
- **Автор, группа:** Илья Тюнин; группа — БВТ2303
- **Целевая оценка:** 5, трек 1 «Прямой upload» (presigned PUT)
- **Commit/PR:** ветка `lab4`, коммиты с префиксом `lab4: ` (стенд MinIO; конфигурация и `ObjectStorage`;
схема и потоковый валидатор; вложения и `attachment_ids`; e2e и отказы; прямая загрузка, скрипты
экспериментов). PR — после пуша ветки в origin.
- **Источники, библиотеки и помощь ИИ:** контракт `contracts/openapi.json`, `contracts/README.md`;
AWS S3 User Guide (object uploads, presigned URLs, checksums); документация MinIO (`mc`, политики,
`MINIO_*_FILE`); AWS SDK for JavaScript v3 (`@aws-sdk/client-s3` 3.1156.0, `s3-request-presigner`,
`@smithy/node-http-handler`); спецификации PNG (RFC 2083 / W3C) и JPEG (ITU-T T.81) для
потокового валидатора. Код и эксперименты подготовлены с помощью ИИ-ассистента; все числа ниже
получены прогонами на описанном стенде и лежат в `evidence/lab4/`.
## Запуск из чистого clone
Версии: Docker 29.9.1, Docker Compose v5.6.0, Node.js 25.7.0 (сборка API — образ `node:25.7.0-slim`),
Python 3.14 (проверки и харнесс; нужен ≥3.9). Образы закреплены по digest:
`minio/minio:RELEASE.2025-09-07T16-13-09Z@sha256:14cea493…8936e`,
`minio/mc:RELEASE.2025-08-13T08-35-41Z@sha256:a7fe349e…1727`, `postgres:16.4-alpine`,
`redis:7.4.2-alpine`, `haproxy:3.2-alpine`. Хост — Fedora, 8 логических CPU, 16 GiB RAM.
```sh
git clone <origin> lab4 && cd lab4
make init-env # создаёт .env (пароль PG, METRICS_TOKEN) и secrets/* (root и API-credentials MinIO); идемпотентно, значения не печатает
make stand-up # docker compose up -d --build --wait: postgres, redis, s3, s3-init, migrate, api x2, haproxy
make wait-ready # GET /health/ready через LB
make test # публичный smoke (через LB)
make check # оффлайн-проверка структуры контракта
make test-e2e # black-box набор: app / attachments / direct-upload (нужны loopback-порты PG, Redis, MinIO)
make test-dependencies # отказы Redis/PG/S3 (останавливают контейнеры стенда и возвращают их)
make s3-security # приватность bucket и права API-credentials вне API
make consistency # сверка bucket и БД (orphans / missing)
make bench # матрица экспериментов, пишет evidence/lab4/bench/*.json и summary.md
make test-persistence ACTION_SCRIPT=scripts/restart.sh
make test-failover ACTION_SCRIPT=scripts/stop-one.sh && scripts/start-replica.sh
```
Действия оператора: только `make init-env`. Он не перезаписывает существующий `.env`: при обновлении с
предыдущей версии сверьте несекретные значения с `.env.example` (команда не печатает секреты):
`diff <(grep -vE '^(POSTGRES_PASSWORD|DATABASE_URL|METRICS_TOKEN)=' .env.example) <(grep -vE '^(POSTGRES_PASSWORD|DATABASE_URL|METRICS_TOKEN)=' .env)`
— иначе останутся старые лимиты (так один из прогонов этой работы шёл с `UPLOAD_MAX_IN_FLIGHT=32`).
Секреты создаются локально в `secrets/` (каталог в
`.gitignore`; `secrets/` и `.env` нельзя коммитить). Остановка с сохранением данных — `make stand-down`
(тома `postgres-data`, `redis-data`, `s3-data` сохраняются). **Намеренное удаление учебных данных:**
`docker compose --env-file .env down -v` (удаляет все три тома, включая загруженные файлы; следующий
`make stand-up` создаёт пустую схему и заново идемпотентно настраивает bucket).
Короткий TTL для проверки истёкшего URL: `DIRECT_UPLOAD_URL_TTL_SECONDS=5 ATTACHMENT_SWEEP_GRACE_SECONDS=0
ATTACHMENT_SWEEP_INTERVAL_MS=1000 docker compose --env-file .env up -d --no-deps api`, затем
`E2E_DIRECT_TTL_SHORT=1 scripts/app-e2e.sh direct-upload`, затем вернуть стенд тем же `up -d --no-deps api`
без переменных.
## Архитектура и решения
```
клиент ──► HAProxy ──► API × 2 ──► PostgreSQL (метаданные, связи, идемпотентность)
│ ├──► Redis (сессии, кэш истории)
│ └──► MinIO (s3) (байты оригиналов, приватный bucket)
клиент ───────────── presigned PUT (трек 1) ───► MinIO (минуя API)
```
- **Источник истины:** метаданные и связи «сообщение ↔ вложение» — PostgreSQL (`attachments`,
`message_attachments`); байты — только в bucket по ключу `attachments/<uuid>/original`. Имя файла
хранится для отображения и никогда не попадает в ключ или путь. На API нет локального файла
оригинала: корневая ФС контейнера `read_only: true`, `/tmp` — tmpfs 16 MiB
(`evidence/lab4/readonly-api.txt`).
- **Жизненный цикл строки:** `pending` (байты не подтверждены) → `ready` (видна участникам чата),
либо `deleting` (захвачена компенсацией или уборщиком) → строка удалена, либо (direct) `rejected`
(проверка не пройдена, URL ещё может действовать) → уборщик. Публично существуют только `ready`.
Инварианты в БД: составные FK `(chat_id, owner_id) → chat_members` и
`(attachment_id, chat_id) → attachments(id, chat_id)` делают «вложение другого чата» невозможным;
`CHECK` требует size/sha256/width/height у `ready` и `expires_at` у незавершённых; FK
`message_attachments → attachments` без каскада запрещает удалить вложение, на которое ссылается
сообщение, а каскад удаления чата проходит.
- **Когда честно 201 (proxy):** только после того, как S3 принял весь объект (`PutObject` завершён) и
`UPDATE … SET status='ready' WHERE status='pending'` изменил строку. Этот `UPDATE` проигрывает
захвату уборщиком атомарно (строка уже `deleting` → 503, а не фальшивый 201).
- **S3 PUT прошёл, а COMMIT нет — и как не потерять оригинал.** Ошибка `markReady` на стороне API
не означает, что COMMIT не прошёл: соединение может оборваться *после* фиксации, и тогда строка
уже `ready`. Поэтому компенсация сначала **захватывает строку**
(`UPDATE … SET status='deleting' WHERE id=$1 AND status='pending'`) и удаляет объект **только после
успешного захвата**, затем удаляет строку:
- захват не сработал (строка уже не `pending`) — объект не трогается; если строка `ready`, API
отвечает 201 с этим вложением (`attachments.upload.recovered`): COMMIT был, это правда;
- PostgreSQL недоступен — ничего не удаляется (`attachments.compensation_deferred`): по строке
`pending` объект найдёт уборщик через `expires_at + ATTACHMENT_SWEEP_GRACE_SECONDS`, и он тоже
сначала захватывает строку;
- S3 недоступен после захвата — строка остаётся `deleting` и перезахватывается уборщиком через минуту;
- запрос оборван (таймаут) уже после того, как последний байт ушёл в S3, — S3 может зафиксировать PUT
*после* нашего DELETE; поэтому строка остаётся `deleting`, и уборщик через минуту удаляет ключ ещё
раз и только потом строку. Если же последний байт не ушёл (обрыв клиента, отказ проверки), S3 не
может зафиксировать объект с неполным телом, и строка удаляется сразу.
Так «объект без строки» не возникает ни в одном из этих сценариев, а `ready` без объекта — только при внешнем
удалении из bucket. Первая версия удаляла объект до строки и теряла оригинал при потерянном ответе
COMMIT; регрессия — `attachments.service.spec.ts` (unit, мок «COMMIT прошёл, ответ потерян»), а
fault-тест `dependency-failures` «keeps the object while PostgreSQL is down before ready» проверяет,
что при остановленном PG объект сохраняется до уборки.
- **Proxy: потоковая передача + полная проверка изображения.** Тело читается как поток и сразу идёт
в S3 с заранее известным `Content-Length` (≤ 10 MiB, иначе 413 до чтения). Проверка в два слоя:
1. `ImageInspector` — байтовый автомат PNG/JPEG без буферизации: сигнатура, структура, CRC чанков
PNG, тип по содержимому и число пикселей (≤ 40 млн → 413) по IHDR/SOF. До появления заголовка
нет ни строки, ни объекта (фаза заголовка ограничена `Content-Length` ≤ 10 MiB: у JPEG до SOF
бывают мегабайты APPn-метаданных); pixel bomb отвергается до любого декодирования.
2. `ImageDecoder` — полный декод libvips (sharp 0.35, `failOn: 'warning'`, `limitInputPixels`),
стоком служит уменьшение до 64 px: оно читает все сжатые данные, но держит в памяти меньше
полноразмерного конвейера (вердикты по 14 видам корректных и битых файлов совпадают с `stats()`,
худший пик памяти — 339 против 329–232 MiB у других стоков… см. `decode-memory.txt`). Структуры и
CRC недостаточно: PNG с мусорным zlib-потоком (верные CRC) и JPEG без данных скана проходят первый
слой — их ловит только декод. Ошибка самого сервера (нет места, нет памяти) не выдаётся за 415:
она логируется и даёт 500. `VIPS_DISC_THRESHOLD=1g` не даёт libvips уносить большие изображения во
временный файл: `/tmp` у API — tmpfs 16 MiB, и до этой настройки снимки ≈40 Мп получали 415.
Последний кусок отдаётся в S3 только после обоих слоёв — S3 не получает полное тело невалидного
файла и не фиксирует объект. Цена — память: копия тела (≤ 10 MiB, libvips не принимает поток) и
декод. Худший допустимый вход — 40 Мп RGBA 16 bit с Adam7-чередованием (декодер обязан держать всё
изображение): **338 MiB** на декод в контейнере (`decode-memory.txt`; baseline JPEG 4.5 MiB,
progressive JPEG 118 MiB, CMYK 7.5 MiB, RGBA16 без чередования 67 MiB). Отсюда настройки:
`IMAGE_DECODE_MAX_CONCURRENT=1` (остальные ждут в очереди; ожидающий запрос, у которого истёк
`UPLOAD_TIMEOUT_MS`, покидает очередь вместе со своим буфером) и `API_MEMORY_PER_REPLICA=1024m`.
Граница на реплику: базовый RSS ≈250 MiB + `UPLOAD_MAX_IN_FLIGHT` 16 × 10 MiB + 1 × 340 MiB
≈ 750 MiB. Нагрузочный прогон худшего случая (32 клиента одновременно шлют именно такой файл
10 MiB) дал пик RSS 791 MiB из 1024 без OOM и рестартов (`bench/*-worst-c32.json`,
`bench-oom-check.txt`). Слоты: `UPLOAD_MAX_IN_FLIGHT` на реплику и `UPLOAD_MAX_IN_FLIGHT_PER_USER`
(4) на пользователя — медленный клиент (держит слот до `UPLOAD_TIMEOUT_MS`) не занимает слоты
остальных; при исчерпании — 429 + `Retry-After`. Слоты общие для proxy и direct complete.
Маршрут загрузки получает тело сырым потоком при любом `Content-Type`: хук `onRequest` помечает
запрос, и тип проверяет сервис уже после guard (401 раньше 415, как требует contracts/README);
Fastify `bodyLimit` к нему не применяется (лимит считает сервис), остальные маршруты используют
штатные парсеры Fastify (`text/plain` > 1 MiB → 413 в конверте ошибки).
- **Таймауты S3.** `S3_REQUEST_TIMEOUT_MS` (15 с) действует как жёсткий предел: `throwOnRequestTimeout`
(без него smithy только пишет предупреждение) и `socketTimeout` на простой при чтении тела. Для PUT
предел — `UPLOAD_TIMEOUT_MS` (сигнал отмены), чтобы медленный клиент не обрывался на 15 с.
Проверено fault-тестом с `docker pause s3` (порт открыт, ответа нет): download → 503 быстрее 20 с,
метаданные и readiness — 200, после `unpause` файл отдаётся.
- **Прямая загрузка (трек 1):** `POST /api/v1/chats/{id}/attachments/direct-uploads` создаёт строку
`pending` (`expires_at = now + TTL`) и возвращает presigned PUT. Подписаны `content-type`,
`content-length` и `x-amz-checksum-sha256`: S3 сам отвергает тело другого размера (403
`SignatureDoesNotMatch`) или с другим SHA-256 (400 `XAmzContentChecksumMismatch`), объект при этом
не создаётся (`evidence/lab4/presign-spike.txt`). `POST /api/v1/attachments/{id}/complete`
(только владелец): `HEAD` (размер + подписанный checksum), затем объект **читается целиком** и
проходит те же два слоя, что и proxy (инспектор + полный декод), сверка типа и пикселей, `markReady`.
Подписанный checksum доказывает лишь, что байты те, что заявил клиент, а не что это изображение:
первая версия читала только начало и принимала усечённый PNG и файл, повреждённый после первых
64 KiB (оба с верным checksum). Цена — входящий трафик API = size на `complete` (см. H2). Чтение и
декод ограничены `UPLOAD_TIMEOUT_MS`, обрыв чтения из S3 → 503. Параллельные `complete` одной заявки
все получают 200 (проигравший `markReady` перечитывает строку). Несоответствие
(размер/checksum/тип/пиксели) → 409/413/415, объект удаляется, а строка получает статус
`rejected` и сохраняет `expires_at`: подписанный URL ещё может быть использован, и повторный PUT
оставил бы объект без строки; уборщик удаляет `rejected` после `expires_at` + grace, пока же строка
занимает слот лимита, а повторный `complete` даёт 404. «Upload has not been received» (409)
строку не трогает — клиент может доотправить. Повторный `complete` готового — 200. Лимит
незавершённых заявок на пользователя: `DIRECT_UPLOAD_MAX_PENDING_PER_USER` (429 с `Retry-After`).
Перезапись по тому же URL до истечения TTL возможна только теми же байтами (checksum подписан).
Расширение контракта: `contracts/extensions.openapi.json`; обязательный proxy endpoint не менялся.
- **Почему volume реплики ≠ объектное хранилище:** файл в volume одной реплики недоступен другой,
теряется при пересоздании контейнера и не масштабируется; здесь байты лежат в общем MinIO со своим
томом, поэтому download через любую реплику возвращает тот же объект
(`evidence/lab4/failover-attachment.txt`).
- **Почему случайный ключ и приватный bucket не заменяют ACL приложения:** ключ — не секрет (он
может утечь через логи, presigned URL, дамп БД), а bucket приватен для всех, кроме API. Решение
«кто из пользователей видит вложение» принимает только приложение: каждый запрос метаданных и
content проверяет членство в чате (`findVisible`), посторонний получает 404; у bucket нет
понятия «участник чата».
- **Недоступность S3 — деградация, не отказ готовности:** S3 не входит в `/health/ready`;
вложения отвечают bounded `503 unavailable`, а текст, чаты, история, метаданные продолжают работать.
Так реплики не уходят из ротации LB из-за зависимости, нужной лишь части функций.
- **Секреты:** `secrets/*` монтируются как Docker secrets; MinIO читает root через
`MINIO_ROOT_USER_FILE`/`MINIO_ROOT_PASSWORD_FILE`, API — через `S3_*_FILE`. У API отдельный
пользователь с политикой `messenger-api`: `Get/Put/DeleteObject` только на `attachments/*` и
`ListBucket` (чтобы отсутствующий ключ давал 404, а не 403). `migrate` S3-секретов не получает
(`parseDatabaseConfig`). Консоль MinIO отключена (`MINIO_BROWSER=off`), порт 9001 не публикуется,
порт API S3 `9000` опубликован только на loopback (`S3_PUBLIC_BIND=127.0.0.1`) — нужен клиенту
presigned URL и тестам.
Что перенесено из lab3: приложение NestJS/Fastify, HAProxy, Redis-сессии, идемпотентность, хуки.
Изменено: `messages.attachment_ids` (в `CREATE_ONCE_SQL` проверка и вставка ссылок в том же операторе,
что и сообщение и ключ идемпотентности; отпечаток текстовых сообщений совпадает с lab3), пустой
`text` допустим при наличии вложений, метрики (`add`, пики памяти с шагом 50 мс), заголовок
`Retry-After` у 429.
### Соответствие `.env.example` → конфигурация
| Переменная | Где читается | Назначение |
| --- | --- | --- |
| `S3_ENDPOINT`, `S3_PUBLIC_ENDPOINT` | `ObjectStorage` (клиент `internal` / клиент подписи) | сетевой адрес для API / хост в presigned URL |
| `S3_REGION`, `S3_BUCKET` | `ObjectStorage`, `infra/minio/bootstrap.sh` | регион подписи; имя bucket |
| `S3_ACCESS_KEY_ID_FILE`, `S3_SECRET_ACCESS_KEY_FILE` | `resolveSecret` → `S3_ACCESS_KEY_ID`/`S3_SECRET_ACCESS_KEY` | API-credentials из Docker secrets |
| `S3_CONNECT_TIMEOUT_MS`, `S3_REQUEST_TIMEOUT_MS` | `NodeHttpHandler` | тайм-ауты S3-клиента |
| `MAX_UPLOAD_BYTES`, `MAX_IMAGE_PIXELS` | `AttachmentsService`, `DirectUploadsService` | 10 MiB, 40 млн пикселей |
| `UPLOAD_TIMEOUT_MS` | `AttachmentsService`, `DirectUploadsService` | дедлайн загрузки и `complete` (25 с), включая ожидание декода |
| `UPLOAD_MAX_IN_FLIGHT`, `UPLOAD_MAX_IN_FLIGHT_PER_USER` | `UploadSlots` | одновременные proxy-загрузки и direct complete на реплику (16) и на пользователя (4) |
| `IMAGE_DECODE_MAX_CONCURRENT` | `ImageDecoder` | одновременные полные декоды на реплику (1; худший декод ≈340 MiB) |
| `VIPS_DISC_THRESHOLD` | `compose.yaml` → libvips | 1g: декод в памяти, не во временном файле в tmpfs `/tmp` |
| `API_MEMORY_PER_REPLICA` | `compose.yaml` | лимит памяти реплики, 1024m (бюджет ≈750 MiB, см. выше) |
| `ATTACHMENT_SWEEP_INTERVAL_MS`, `ATTACHMENT_SWEEP_GRACE_SECONDS` | `AttachmentSweeper`, CLI | период фонового прохода (0 = выкл.) и grace после `expires_at` |
| `DIRECT_UPLOAD_URL_TTL_SECONDS`, `DIRECT_UPLOAD_MAX_PENDING_PER_USER` | `DirectUploadsService` | TTL подписи; лимит незавершённых заявок |
| `S3_PUBLIC_BIND`, `S3_PUBLIC_PORT`, `S3_CPUS`, `S3_MEMORY` | `compose.yaml` (сервис `s3`) | публикация порта на loopback; лимиты контейнера |
| `minio_root_*`, `s3_api_*` | `secrets/*` → `compose.yaml` secrets | credentials; создаются `scripts/init-env.sh` |
Остальные переменные (`DATABASE_URL`, `REDIS_URL`, `METRICS_TOKEN`, лимиты, порты) — как в lab3.
### Компенсация, сверка, очистка (grace period)
`expires_at` у proxy = старт + `UPLOAD_TIMEOUT_MS` (жёсткий дедлайн запроса), у direct = выдача URL + TTL.
Уборщик берёт строки `pending`/`rejected` только через `ATTACHMENT_SWEEP_GRACE_SECONDS` (900 с по умолчанию) после этого:
живую загрузку он не застанет, а `markReady … WHERE status='pending'` проигрывает захвату
(`pending → deleting`, `FOR UPDATE SKIP LOCKED`, реплики не мешают друг другу). Застрявшая в
`deleting` строка (упавший уборщик или компенсация, которой не ответил S3) перезахватывается через
минуту — живая компенсация за это время либо завершается, либо уже не идёт. Ручной запуск:
`docker compose exec api node dist/attachments/attachments-sweep.cli.js`. Сверка в обе стороны (только
чтение): `make consistency` — `orphans` (объект без строки) и `missing` (`ready` без объекта).
Отсутствующий объект у `ready`-строки при download — это потеря данных: 500 и счётчик
`attachments.object_missing`, а не клиентская ошибка.
## Доказательства критериев
Все файлы — в `evidence/lab4/`; в них нет `.env`, токенов, секретов и подписанных URL.
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства |
| --- | --- | --- | --- |
| Публичный smoke | `make test` | `PASS: lab4 public API scenario` (upload 201 ready, сообщение с `''` и `attachment_ids`, download bob = байты, eve 404) | `make-test.txt` |
| Контракт offline | `make check` | PASS, `contracts/extensions.openapi.json` — валидный JSON | `make-check.txt` |
| 3: S3 в общем стенде, приватный bucket, метаданные в PG, байты в bucket | `make stand-up`; `docker compose ps`; `make consistency` | `s3` healthy, `s3-init` завершён с 0; bucket приватный (`mc anonymous set none`); после серий `make bench`, e2e и fault-тестов: 5066 объектов на 5065 `ready` + 15 незавершённых строк (`pending`/`rejected`, ждут истечения + grace; одна из них — с объектом), orphans/missing = 0 | `bootstrap-rerun.txt`, `consistency.txt` |
| 3: 201 ready, побайтный download, `attachment_ids` | `make test-e2e` (`attachments.e2e-spec.ts`) | sha256 в ответе = sha256 файла; content = байты, `nosniff`, `Content-Length` | `make-test-e2e.txt` |
| 3: PNG/JPEG ≤10 MiB и ≤40 млн px; MIME по содержимому; опасные filename; лимиты до чтения | e2e: снимок 7728×5152 (39.8 Мп) baseline и progressive JPEG → 201, PNG 8000×5000 RGBA16 → 201, JPEG с 1.3 MB метаданных до SOF → 201; 10485760 → 201, 10485761 → 413, pixel bomb 8000×5001 → 413 сразу после IHDR, PNG как `image/jpeg` → 415, `a/b.png`, `\u202E`, NUL, 256 символов → 400, 255×😀 → 201 | кейсы перечислены в `app/test/attachments.e2e-spec.ts` (в evidence — итог: 44 passed, 9 skipped opt-in); raw image/text тело на JSON-маршрутах → 415/400, `text/plain` > 1 MiB → 413, без токена с `application/zip` → 401 (не 415) | `make-test-e2e.txt`, `unit-tests.txt` (48 passed: `image-inspector.spec.ts`, `image-decoder.spec.ts`, `attachments.service.spec.ts`, `upload-slots.spec.ts`) |
| 3: другая реплика отдаёт файл после остановки загрузившей; restart сохраняет данные | `scripts/stop-one.sh` (обе реплики по очереди), `make test-failover`; `make test-persistence ACTION_SCRIPT=scripts/restart.sh` | failover: 0 неуспешных попыток, восстановление ≈3.3 с; download с тем же sha256 после остановки api-1 и api-2; persistence: `StartedAt` у postgres, redis, s3, api×2, haproxy изменился, данные и сессия сохранены | `failover.txt`, `failover-attachment.txt`, `persistence.txt` |
| 3: на API нет локального файла оригинала | `touch` в корне контейнера | `Read-only file system` | `readonly-api.txt` |
| 4: тесты: большой файл, повреждённое изображение, подмена MIME, чужое `attachment_id`, вложение другого чата, нет 500 | `make test-e2e` | 413; усечённый PNG, флип байта (CRC), сигнатура+мусор, пустое тело, PNG с мусорным zlib-потоком при верных CRC, JPEG (baseline и прогрессивный) без данных скана → 415; подмена MIME → 415; чужое/неизвестное/незавершённое → 404; вложение чата eve в чате alice → 404 | `make-test-e2e.txt` |
| 4: прерывание загрузки и отказ между S3/БД не оставляют вечных объектов | e2e «client drops the connection»; `make test-dependencies` | обрыв клиента → строк 0 за ≤10 с; S3 down → строка в `deleting`, после старта перезахвачена и убрана sweep; PG down между PUT и ready → 503, объект сохранён до уборки (строка `pending` его учитывает), после sweep нет ни объекта, ни строки; потерянный ответ COMMIT → объект не удаляется, 201 (unit `attachments.service.spec.ts`); затем `orphans: 0, missing: 0` | `make-test-e2e.txt`, `make-test-dependencies.txt`, `consistency.txt` |
| 4: лимиты, таймауты, потоковая обработка; эксперимент ≥10 загрузок с пиком памяти | `make bench`: proxy 9.5 MiB при C=10 и C=20; худший случай — 32 клиента с 40 Мп RGBA16 Adam7 10 MiB; `docker pause s3` в `make test-dependencies` | типичные: Δrss 20 / 43 MiB; худший: пик RSS 791 из 1024 MiB, без OOM, избыток — 429; граница по конфигурации ≈750 MiB; худший декод в контейнере 338 MiB; зависший S3 → 503 за ≤ 20 с | `summary.md`, `bench/*.json`, `bench-oom-check.txt`, `decode-memory.txt`, `make-test-dependencies.txt` |
| 4: идемпотентный bootstrap; отдельные ограниченные credentials; консоль закрыта; private bucket вне API | `docker compose run s3-init` дважды; `make s3-security` | повтор → `bootstrap ok`; анонимные GET/list/PUT → 403; API-credentials не создают bucket, не вызывают admin, не пишут вне `attachments/`, читают `attachments/*`; порт 9001 не опубликован и не отвечает | `bootstrap-rerun.txt`, `s3-security.txt` |
| 5 / трек 1: presigned flow (короткая подпись, уникальный ключ, принадлежность, размер/checksum на complete, незавершённые) | `direct-upload.e2e-spec.ts`; спайк подписи | init → PUT мимо API → complete → metadata/content → сообщение; чужой/посторонний complete → 404; 4 параллельных complete → 200 × 4; усечённый PNG и PNG, повреждённый после первых 64 KiB (оба с верным checksum) → 415, затем 404; подмена байта → S3 400, затем complete 409; JPEG под видом PNG → 415, затем 404; pixel bomb → 413; 11-я заявка → 429 + `Retry-After` | `make-test-e2e.txt`, `presign-spike.txt` |
| 5 / трек 1: истёкший URL и уборка | `E2E_DIRECT_TTL_SHORT=1` на стенде с TTL 5 с | PUT после `expires_at` → 403, строка убрана уборщиком, complete → 404 | `direct-ttl-short.txt` |
| 5 / трек 1: сравнение трафика и RAM API на ≥2 размерах | `make bench` (0.125, 1, 9.5 MiB) | см. таблицу ниже | `summary.md`, `bench/*.json` |
Оговорка по hook'ам: `make test-persistence` и `make test-failover` подтверждают сохранность данных и
сессии; какие процессы перезапущены, видно по `StartedAt` до/после (`persistence.txt`).
`scripts/stop-one.sh` останавливает только реплику, обслужившую сессию теста (в обоих прогонах
`make test-failover` это была одна и та же реплика), поэтому остановка обеих реплик показана отдельно
`failover-attachment.txt`. Persistence, failover, бенчмарк, безопасность и сверка перезапущены на
коммите `9caa031` (код приложения тот же, что в `4b53e03`); unit, e2e, отказы и короткий TTL — на `4b53e03`.
## Эксперименты и отказы
**Методика.** Хост: 8 логических CPU, 16 GiB RAM, один Docker-хост. Лимиты: API 1.5 CPU / 1024 MiB на
реплику (2 реплики), MinIO 1 CPU / 512 MiB, PG 1.5 CPU / 512 MiB; `UPLOAD_MAX_IN_FLIGHT=16`,
`UPLOAD_MAX_IN_FLIGHT_PER_USER=4`, `IMAGE_DECODE_MAX_CONCURRENT=1`. Версии — см. «Запуск». Нагрузка:
`scripts/lab4/attachments_bench.py`, closed-loop: C потоков (у каждого свой пользователь и чат) × K
загрузок, R = 3 повтора; один прогрев на конфигурацию (2 × число реплик загрузок, не измеряется), перед
каждым повтором — `POST /internal/metrics/reset` на каждой реплике. Два вида входа:
1. **типичный** — несжимаемые PNG ширины 1024 (`noise_png`, разные seed) 0.125 / 1 / 9.5 MiB, K = 5:
нагружают сеть и S3, декод у них дешёвый (≈15 мс на 9.5 MiB);
2. **худший для памяти** — 40 Мп RGBA 16 bit, Adam7, дополненный до 10 MiB (`pngkit.py`), C = 32, K = 2:
каждый запрос требует максимального декода (≈810 мс, 338 MiB), а C = 32 упирается в
`UPLOAD_MAX_IN_FLIGHT` обеих реплик.
Трафик API — дельта `eth0` rx/tx из `/proc/net/dev` контейнера; RAM — пик `process.memoryUsage().rss`
с шагом 50 мс (Δrss — минус RSS в момент reset; peak RSS — абсолютный максимум по репликам и повторам);
отказы классифицируются по шагу и статусу. В таблицу идут медианы по повторам. Команда: `make bench`
(`scripts/lab4/run_matrix.sh`); raw — `evidence/lab4/bench/*.json` (без токенов и URL), коммит `9caa031`.
**H1 (уровень 4).** Память реплики ограничена сверху конфигурацией — базовый RSS ≈250 MiB +
`UPLOAD_MAX_IN_FLIGHT × 10 MiB` + `IMAGE_DECODE_MAX_CONCURRENT × 340 MiB` ≈ 750 MiB < 1024 MiB — при любом
числе клиентов и любом допустимом изображении; избыток нагрузки получает 429, а не OOM. (Исходная
формулировка «Δrss почти не зависит от размера файла» для текущей версии неверна по построению: ради
полного декода API держит копию тела.)
**H2 (трек 1).** Прямая загрузка снимает с API передачу байтов в S3 (tx) и не требует держать соединение
клиента на время заливки; входящий трафик API она не снижает, потому что `complete` читает объект
целиком для проверки; латентность direct выше из-за трёх round trip и повторного чтения.
Результаты (`evidence/lab4/summary.md`; 150 загрузок на строку при C=10, 300 при C=20, 192 в худшем случае):
| mode | size, MiB | C | ok | отказы | API rx/upload, MiB | API tx/upload, MiB | max Δrss, MiB | peak RSS, MiB | p50, ms | p95, ms |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| direct | 0.12 | 10 | 150/150 | — | 0.13 | 0.01 | 0.38 | 394 | 40 | 71 |
| proxy | 0.12 | 10 | 150/150 | — | 0.13 | 0.13 | 0.00 | 447 | 26 | 46 |
| direct | 1.00 | 10 | 150/150 | — | 1.01 | 0.01 | 0.00 | 244 | 71 | 107 |
| proxy | 1.00 | 10 | 150/150 | — | 1.01 | 1.01 | 0.12 | 395 | 50 | 82 |
| direct | 9.50 | 10 | 150/150 | — | 9.52 | 0.01 | 67.06 | 344 | 448 | 672 |
| proxy | 9.50 | 10 | 150/150 | — | 9.52 | 9.53 | 20.31 | 273 | 245 | 399 |
| proxy | 9.50 | 20 | 300/300 | — | 9.53 | 9.53 | 42.53 | 274 | 433 | 781 |
| direct, худший | 10.00 | 32 | 167/192 | complete 429 × 25 | 9.24 | 0.01 | 366.88 | 791 | 11067 | 13423 |
| proxy, худший | 10.00 | 32 | 190/192 | upload 429 × 2 | 10.04 | 9.90 | 356.76 | 785 | 11982 | 13068 |
Выводы:
- **H1 подтверждена.** В худшем случае пик RSS реплики — 785–791 MiB из 1024, OOM и рестартов нет
(`bench-oom-check.txt`); все неуспехи — 429 с `Retry-After` (сработал лимит слотов), ни одного 5xx.
Пик выше расчётных ≈750 MiB на ≈40 MiB: базовый RSS к этому прогону уже был выше 250 MiB (аллокатор
не возвращает память ОС после предыдущих прогонов — поэтому и абсолютный peak RSS у малых файлов
в таблице 394–447 MiB при Δrss ≈ 0). Для типичных файлов Δrss — 0–2 MiB на 0.12–1 MiB и 20–43 MiB на
9.5 MiB (C = 10 / 20) при ≈95 / 190 MiB тел в полёте на весь стенд. Латентность худшего случая
(p50 ≈ 11–12 с) — очередь к единственному декоду: 16 запросов × ≈0.8 с; это плата за ограничение
памяти, ожидающие дольше `UPLOAD_TIMEOUT_MS` уходят из очереди с 503.
- **H2 подтверждена в новой формулировке.** API tx у direct ≈0.01 MiB против size у proxy (≈1000× для
9.5 MiB); API rx одинаков (≈size), потому что `complete` читает объект целиком. Ранняя версия, читавшая
только начало объекта, давала rx ≈0.07 MiB, но принимала повреждённые изображения — этот выигрыш был
ценой корректности и отозван. Δrss у direct 9.5 MiB выше, чем у proxy (67 против 20 MiB): объект
читается из S3 быстрее, чем приходит от клиента, и больше копий одновременно ждут декода. Латентность
direct выше на всех размерах (p50 40/71/448 против 26/50/245 мс): три запроса и повторное чтение
объекта. Выигрыш direct в этой реализации — снятие с API исходящего трафика в S3 и времени заливки
клиентом; для выигрыша по rx проверку нужно вынести с API (асинхронный воркер рядом с хранилищем,
`status: processing`) — следующий шаг, не реализован.
- История версий: до полного декода (`830e581`) p50 proxy 9.5 MiB C=10 — 239 мс; с декодом через
`stats()` (`4badd5a`, тот прогон по ошибке шёл с `UPLOAD_MAX_IN_FLIGHT=32` из устаревшего локального
`.env`) — 642 мс; с декодом через уменьшение (`9caa031`) — 245 мс.
**Ограничения измерений.** Один Docker-хост: клиент, LB, API и MinIO делят 8 CPU, без реальной сети;
`/proc/net/dev` реплики включает трафик PG/Redis и служебные запросы метрик (≈7–13 KiB на загрузку,
видно в tx у direct); closed-loop клиент не моделирует arrival rate; выборка RSS 50 мс может
пропустить короткий пик; абсолютный RSS зависит от истории процесса; типичные файлы — синтетический
шум, а не фото (худший случай по памяти проверен отдельно); нет TLS (до lab7); Python-клиент сам
ограничен по CPU, поэтому абсолютные латентности не переносимы.
### Отказы
| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных |
| --- | --- | --- | --- |
| S3 остановлен (`compose stop s3`) | вложения → bounded 503; текст, история, метаданные, `/health/ready` работают | upload → 503 `unavailable` без утечки деталей; метаданные 200; content 503; текстовое сообщение 201; readiness 200; строка неудачной загрузки в `deleting` (захвачена, удаление объекта не прошло) | после `start s3` и healthy download старого файла 200 с теми же байтами, новый upload 201; строка перезахвачена и убрана sweep через минуту; потерь нет |
| PostgreSQL остановлен между S3 PUT и `ready` | 503; API не знает, прошёл ли COMMIT, — ничего не удаляет; объект учтён строкой | ответ 503; после старта PG строка `pending`, объект на месте (`mc stat` — есть); после `expires_at` sweep удалил объект и строку | уборка через `expires_at` + grace; `orphans: 0`, `missing: 0` |
| COMMIT `ready` прошёл, ответ PostgreSQL потерян | объект не удаляется, клиент получает 201 | unit `attachments.service.spec.ts`: захват строки не срабатывает, `delete` не вызывается, ответ 201 `ready` | потерь нет (в стенде не воспроизводится без прокси, разрывающего соединение после COMMIT) |
| S3 «завис» (`docker pause s3`: порт открыт, ответа нет) | ответ в пределах `S3_REQUEST_TIMEOUT_MS`, а не бесконечное ожидание | download → 503 быстрее 20 с (15 с таймаут); метаданные и readiness — 200 | после `unpause` download 200 с теми же байтами; потерь нет |
| Медленный клиент держит 12 соединений загрузки | его лишние запросы → 429, остальные пользователи не страдают | его 13-я загрузка → 429 `Retry-After: 1`; 4 загрузки другого пользователя подряд → 201 | соединения закрыты — строк не осталось |
| 4 параллельных `complete` одной прямой загрузки | все получают готовое вложение | 200 × 4 с одним и тем же `id` | — |
| 32 клиента одновременно шлют худший по памяти файл | без OOM; избыток → 429 | пик RSS 791 из 1024 MiB, OOM нет, 27 отказов — все 429 | — |
| Обрыв клиента посреди загрузки (512 KiB из 2 MiB) | не остаётся ни строки, ни объекта | PUT прерывается (`S3 put failed: AbortError` в логе API, в evidence не сохранён) без ожидания тайм-аута, компенсация, строк в чате 0 | ≤10 с (предел ожидания теста; точное время не измерялось) |
| Остановка обслужившей реплики | другая реплика отдаёт тот же файл | download 200, тот же sha256, другой `X-Instance-Id` для api-1 и api-2 | ≈3.2 с до первого успешного запроса, 0 неуспешных записей из 133–141 |
| Restart стенда (`scripts/restart.sh`) | метаданные и оригиналы сохраняются, сессия жива | persistence PASS; `StartedAt` всех сервисов изменился | потерь нет (время до готовности отдельно не измерялось) |
| Истёкший presigned URL | PUT отвергается, заявка убирается | PUT → 403; строка убрана уборщиком; complete → 404 | TTL (5 с в прогоне) + grace 0 + период уборщика 1 с |
| Подмена байтов / размера при прямой загрузке | S3 отвергает, объект не создаётся | 400 `XAmzContentChecksumMismatch` / 403 `SignatureDoesNotMatch`; complete → 409 | заявка остаётся до TTL, клиент может доотправить |
## Ограничения и следующие шаги
- **MinIO:** закреплён образ `RELEASE.2025-09-07T16-13-09Z`; по данным, использованным при планировании,
репозиторий `minio/minio` архивирован — новых образов и исправлений не будет *(в этой сессии не
перепроверялось)*. Для продакшена потребуется замена (SeaweedFS/RustFS) или форк.
- **Полная проверка изображения стоит памяти и времени:** копия тела (≤ 10 MiB) на загрузку и декод
через libvips (нативная зависимость sharp; худший вход — 338 MiB, ≈0.8 с). Поэтому декод на реплике
строго по одному, а реплике нужен 1 GiB; под потоком «тяжёлых» изображений латентность растёт до
секунд (очередь), а лишние запросы получают 429. `failOn: 'warning'` строже браузеров: файл с
предупреждением libjpeg/libpng будет отвергнут (на 300 изображениях с хоста ложных отказов не было,
но выборка не репрезентативна для фото с камер). Проверяются декодируемость и целостность, а не
«безопасность для всех декодеров» — перекодирование в чистый формат не делается.
- **Изменённый байт внутри сжатых данных baseline JPEG может пройти проверку:** у JPEG нет контрольной
суммы, и такой байт часто даёт другой, но корректный поток Хаффмана (замер: из 14 видов порчи не
пойман только этот). Для PNG то же поймает CRC/Adler-32. В direct байты дополнительно зафиксированы
подписанным SHA-256 — они ровно те, что заявил клиент.
- **Direct не экономит входящий трафик API** (см. H2); это следствие проверки на API. Следующий шаг —
асинхронная проверка воркером рядом с хранилищем (`status: processing`), что требует расширения
контракта.
- **Лимит на пользователя не защищает от многих аккаунтов:** регистрация открыта, поэтому распределённый
«медленный клиент» из ≥ 4 аккаунтов на реплику всё ещё может занять все слоты на `UPLOAD_TIMEOUT_MS`
(25 с). Защита — минимальная скорость приёма тела или ограничения на LB; не реализовано.
- **Гонка лимита заявок:** `countPendingDirect` и `insertPending` не атомарны — параллельные `init`
одного пользователя могут превысить лимит на число параллельных запросов; для лабораторной принято.
- **Незавершённые загрузки занимают место до уборки** (`expires_at` + grace 15 мин): в т. ч. прямые
заявки, чей `complete` получил 429 (после серии бенчмарка в `consistency.txt` видно 84 `pending`).
Если строка уже `deleting` из-за поздно зафиксированного PUT после таймаута, уборщик повторно удалит
ключ через минуту.
- **Компенсация при недоступной БД ничего не удаляет:** объект остаётся до уборки
(`expires_at` + 900 с grace) — сознательный выбор: без БД нельзя отличить «COMMIT не прошёл» от «ответ
потерян», а удаление во втором случае теряет оригинал. Объект без строки (например, строку удалили
вручную) обнаружит только `make consistency` — автоматического reconciler'а нет (это трек 2).
- **Потерянный COMMIT проверен только unit-тестом** с моком репозитория: стенд не умеет разорвать
соединение PostgreSQL ровно после COMMIT (для этого нужен прокси вроде toxiproxy).
- **Таймаут загрузки** уничтожает тело (и сокет) — клиент получает обрыв соединения (через HAProxy — 502
без `X-Request-Id`) вместо 400 «Upload was interrupted»; строка и объект при этом компенсируются.
- **TLS нет** до lab7: presigned URL и токены ходят по HTTP; консоль MinIO отключена полностью, поэтому
администрирование — только через `mc` из контейнера.
- **Не реализовано:** варианты вложений (`variants` всегда `[]`; `variant=thumbnail|crop|optimized` → 404),
delete-API вложений, WebP, `Range` на download (игнорируется, отдаётся весь файл с 200).
- **Подтверждено измерением:** память реплики ограничена конфигурацией и в худшем случае не доходит до
лимита; direct снимает с API исходящий трафик в S3. **Опровергнуто для текущей версии:** снижение
входящего трафика API прямой загрузкой. **Остаётся гипотезой:** поведение на реальных фото (типичный
бенчмарк — синтетический шум) и при C, многократно превышающем лимит слотов.