From 6c5ba026f13c4894cb8ba6d0bc129d34314419e6 Mon Sep 17 00:00:00 2001 From: Vladislav Kunetskiy Date: Thu, 29 Oct 2026 23:36:12 +0300 Subject: [PATCH] =?UTF-8?q?=D0=91=D0=B0=D0=B7=D0=B0=20lab5:=20=D0=BA=D0=BE?= =?UTF-8?q?=D0=BD=D1=82=D1=80=D0=B0=D0=BA=D1=82=201.5.0=20=D0=B8=20=D1=80?= =?UTF-8?q?=D0=B5=D0=B0=D0=BB=D0=B8=D0=B7=D0=B0=D1=86=D0=B8=D1=8F=20lab1?= =?UTF-8?q?=E2=80=93lab4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .github/pull_request_template.md | 2 +- MAINTAINERS.md | 2 +- README.md | 66 ++++++------- REPORT.md | 158 ++++--------------------------- compose.example.yaml | 4 +- contracts/attachment-states.md | 21 ++++ contracts/infrastructure.json | 18 +++- contracts/jobs.schema.json | 63 ++++++++++++ contracts/openapi.json | 16 +++- lab.json | 6 +- 10 files changed, 171 insertions(+), 185 deletions(-) create mode 100644 contracts/attachment-states.md create mode 100644 contracts/jobs.schema.json diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 1bec5472..7d1ff4a4 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -1,4 +1,4 @@ -## Лабораторная 4 +## Лабораторная 5 Автор / группа: TODO Целевая оценка (3/4/5): TODO diff --git a/MAINTAINERS.md b/MAINTAINERS.md index bb10fed7..85601aee 100644 --- a/MAINTAINERS.md +++ b/MAINTAINERS.md @@ -1,4 +1,4 @@ -# Памятка преподавателю — лабораторная 4 +# Памятка преподавателю — лабораторная 5 ## Что подготовлено diff --git a/README.md b/README.md index 947094c3..009d6997 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ -# Лабораторная 4. S3-хранилище и вложения +# Лабораторная 5. Очереди и асинхронная обработка изображений -Разделить метаданные и бинарное содержимое, добавить изображения в сообщения и сохранить доступ к ним при переключении API-реплики. +Отделить приём файла от тяжёлой обработки, корректно переживать повторную доставку и остановку worker. Это **skeleton**, а не готовый сервер. Здесь есть задание, контракт и публичные проверки. Реализацию приложения, Dockerfile и требуемую инфраструктуру пишет студент. Язык и framework свободные; UI не обязателен. @@ -8,41 +8,42 @@ ## Откуда начинаем -Перенесите минимум lab3. Дополняются поля сообщения и endpoint вложений; прежние текстовые POST остаются валидными. +Нужен минимум lab4. POST upload теперь возвращает 202 queued, а готовность выясняется через метаданные. В HTTP upload клиент по-прежнему передаёт все байты. -**Архитектура:** Клиент → LB → API × 2+ → PostgreSQL (метаданные) + приватное S3-хранилище (байты). +**Архитектура:** API → устойчивый staging + запись задания → брокер → worker → конечный S3 + PostgreSQL. Клиент опрашивает статус. ## Что сделать -1. Выберите один S3-совместимый сервер: MinIO, SeaweedFS или RustFS. Закрепите проверенную версию образа и опишите создание приватного bucket. -2. Спроектируйте Attachment и связь с чатом/сообщением. S3 object key назначает сервер, filename используется только для отображения. -3. Реализуйте синхронный binary upload PNG/JPEG с ограничениями, сохранение метаданных и авторизованный download через API. -4. Включите S3 и persistent volumes в общий Compose/Swarm. Проверьте, что другая API-реплика скачивает файл после остановки загрузившей. -5. Проверьте недоступность S3, чужой чат и restart всего стенда. +1. Выберите RabbitMQ, Redis/Valkey Streams, NATS JetStream или другой брокер с persistence и подтверждениями. Обычный Pub/Sub без хранения не подходит. +2. Разделите приём, durable staging, публикацию задания, обработку и фиксацию результата. Прочитайте contracts/attachment-states.md. +3. Реализуйте worker отдельно от API: публикация оригинала в конечный S3-prefix и thumbnail 256×256 по правилам контракта. +4. Добавьте конечные состояния, ограниченные повторы и идемпотентную запись результатов. Не помещайте bytes или credentials в сообщения брокера. +5. Остановите worker, загрузите файл, перезапустите API/worker, убедитесь в завершении принятой задачи. Затем проверьте повторную доставку. ## Оценка «3»: работающий минимум -- Все обязательные возможности lab3 сохранены. S3-сервер находится в общем стенде; метаданные вложений живут в PostgreSQL, байты — в приватном bucket, не в БД или локальном каталоге API. -- POST вложения возвращает 201 ready после сохранения; оригинал скачивается побайтно. Message с attachment_ids читается участниками чата. Публичный smoke проверяет checksum и отсутствие доступа у постороннего. -- Принимаются реальные PNG/JPEG ≤10 MiB и ≤40 млн пикселей; MIME проверяется по содержимому, опасные filename отклоняются, лимиты применяются до неограниченного чтения/декодирования. -- Upload → остановка обслужившей API-реплики → download через другую возвращает тот же файл. Restart с сохранением volumes сохраняет метаданные и оригинал. +- Весь минимум lab4 сохранён с переходом upload 201 → 202. API возвращает 202 только после устойчивого приёма оригинала и сохранения задания; остановка API после ответа не теряет работу. +- В общем Compose/Swarm есть отдельные broker и worker. Сообщения durable, доставка at least once, подтверждение только после устойчивого эффекта. Недоступность worker не заставляет API выполнять resize синхронно. +- Состояния queued/processing/ready/failed доступны в API. Worker сохраняет оригинал и один thumbnail; original неизменен, thumbnail соответствует контракту. Публичный smoke проходит. +- Есть ограниченный retry (конкретное число попыток в конфигурации, например 5), финальное failed с безопасным error_code. Повтор одной job не создаёт второго набора вариантов. +- Демонстрация: worker остановлен → upload 202 → сообщение с вложением создано → API перезапущен → worker запущен → ready и доступный thumbnail. Принятое задание не исчезает при рестарте broker с volume. ## Оценка «4»: уровень стажёра/джуна Весь уровень 3 **и все** пункты ниже: -- Тесты покрывают слишком большой файл, повреждённое изображение, подмену MIME, чужое attachment_id и привязку файла другого чата. Пользовательская ошибка не превращается в 500. -- Прерывание загрузки и отказ между записью S3/БД не оставляют вечных неучтённых объектов: есть документированный механизм компенсации/сверки/очистки с безопасным grace period. -- Лимиты/таймауты и потоковая обработка не позволяют одной загрузке занять неограниченную RAM. Проведён эксперимент ≥10 одновременных загрузок с измерением пика памяти. -- Bucket bootstrap идемпотентен; API использует отдельные S3 credentials с ограниченными правами. Административная консоль не открыта в общей сети. Есть проверка private bucket вне API. +- Добавлены crop 128×128 и optimized WebP по контракту, параметры качества/удаления метаданных описаны. Невалидные/огромные изображения ограничены по bytes, пикселям, времени и памяти worker. +- Разрыв между PostgreSQL и broker закрыт transactional outbox или другой доказанной схемой восстановления намерения. Внедрён crash между COMMIT и publish; после восстановления задача доходит до ready без ручного создания нового задания. +- Retry использует backoff с jitter, различает постоянные/временные ошибки; есть DLQ/реестр failed и безопасный явный replay. «Повторить» не означает безусловно исполнить дубль уже успешной job. +- Проверена остановка worker после записи объекта, но до ack; повтор завершает тот же результат. Есть timeout/lease для зависшего processing, ограниченная конкуренция/prefetch и очистка staging после безопасной фиксации. ## Оценка «5»: исследование и доказанный результат Весь уровень 4 **и один законченный трек на выбор**. Приведите гипотезу, повторяемую методику, результаты и ограничения. -**Трек 1. Прямой upload.** Добавьте отдельный безопасный presigned-upload flow: короткая подпись, уникальный ключ, проверка принадлежности, размера/checksum при complete, обработка незавершённой загрузки. Сохраните обязательный proxy endpoint. Сравните трафик и RAM API при ≥2 размерах файлов, покажите негативные сценарии. +**Трек 1. Очередь под перегрузкой.** Сравните ≥3 настройки concurrency/prefetch на разных размерах изображений. Измерьте throughput, queue lag, p95 времени до ready и RSS; покажите backpressure и ограничение количества принятой работы. Докажите восстановление после перегрузки, объясните компромисс latency/ресурсы. -**Трек 2. Согласованность двух хранилищ.** Разработайте повторяемый reconciler для orphan/missing объектов и метаданных. Внедрите ошибки на обеих сторонах, покажите обнаружение и безопасное исправление с dry-run/повторным запуском. Докажите, что свежие и используемые вложения не удаляются; измерьте стоимость обхода. +**Трек 2. Доказанная идемпотентность pipeline.** Постройте versioned pipeline и автоматический fault-injection для дубля, reorder, crash до/после side effect и устаревшей job после новой версии. Зафиксируйте инварианты, покажите отсутствие потери подтверждённых задач и перезаписи нового результата старым. Обсудите почему это не exactly-once доставка. ## Как начать и проверить @@ -78,28 +79,27 @@ Smoke не выставляет оценку автоматически. Про ## Сценарий защиты -1. Загрузить fixture, отправить message с attachment_ids, скачать как второй участник и сравнить SHA-256. -2. С третьим пользователем получить 404 для метаданных и bytes; direct unauthenticated S3 GET не отдаёт объект. -3. Выполнить persistence и failover: общий тест начиная с lab4 сохраняет и повторно читает оригинал через API. -4. Показать, что на API нет обязательного локального файла оригинала. Для 4/5 — отказы и эксперименты. +1. Запустить make test: API возвращает 202, GET доходит до ready, оригинал и настоящий JPEG thumbnail проверяются. +2. Остановить worker своим скриптом, загрузить файл, убедиться, что content отвечает 409, а другие сообщения продолжают работать. +3. Перезапустить API/broker с сохранением volumes, запустить worker; та же запись должна стать ready. Зафиксировать порядок действий и ID без токенов. +4. Для 4: воспроизвести crash после side effect до ack, разрыв COMMIT/publish и replay failed; для 5 — выбранный эксперимент. ## Что должно быть в PR -Дополненный стенд, настройка bucket/политики, миграции Attachment, тесты файлов, описание согласованности БД/S3 и результаты. +Worker, брокер в общем стенде, схема jobs, migrations/outbox по уровню, конфигурация retry, тесты сбоев и отчёт. Заполните `REPORT.md` и [шаблон PR](.github/pull_request_template.md), укажите целевую оценку/трек. Не меняйте обязательный контракт и публичные tests ради зелёного результата. Сохраняйте возможности предыдущих лабораторных в пределах [объявленных переходов](COURSE.md). ## Вопросы на защите -- Почему файл в Docker volume одной API-реплики не равен объектному хранилищу? -- Когда можно честно вернуть 201? -- Что произойдёт, если S3 PUT прошёл, а COMMIT в PostgreSQL — нет? -- Почему случайный object key и приватный bucket не заменяют ACL приложения? +- Чем publisher confirm отличается от consumer ack? +- Что именно уже сохранено в момент 202? +- Почему повторная доставка нормальна и где находится ключ идемпотентности job? +- Как отличить зависший worker от долго работающего и не запустить два неконтролируемых дубля? ## Первичные материалы -- [S3 object uploads](https://docs.aws.amazon.com/AmazonS3/latest/userguide/upload-objects.html) -- [Presigned URLs](https://docs.aws.amazon.com/AmazonS3/latest/userguide/using-presigned-url.html) -- [MinIO](https://github.com/minio/minio) -- [SeaweedFS](https://github.com/seaweedfs/seaweedfs) -- [RustFS](https://docs.rustfs.com/) +- [RabbitMQ reliability](https://www.rabbitmq.com/docs/reliability) +- [Publisher confirms and acknowledgements](https://www.rabbitmq.com/docs/confirms) +- [Redis Streams](https://redis.io/docs/latest/develop/data-types/streams/) +- [NATS JetStream](https://docs.nats.io/nats-concepts/jetstream) diff --git a/REPORT.md b/REPORT.md index 39554c0c..e98f75e9 100644 --- a/REPORT.md +++ b/REPORT.md @@ -1,159 +1,37 @@ -# Отчёт — лабораторная 4 +# Отчёт — лабораторная 5 -- Автор, группа: Кунецкий Владислав, БВТ2303 -- Целевая оценка; выбранный трек 5: **5, трек 1 (presigned direct upload)** -- Commit/PR: ветка `lab4`; см. `git log --oneline` -- Использованные источники, библиотеки и помощь ИИ: Go 1.27, PostgreSQL 18, SeaweedFS 3.80, HAProxy 3.2, AWS SDK for Go v2, ogen 1.24, sqlc, goose, mockery. Внешние источники: контракт 1.4.0, OWASP File Upload Cheat Sheet, AWS S3 presigned URL docs, Stripe idempotency docs, PostgreSQL advisory locks, Docker Compose startup order, SeaweedFS S3 docs. ИИ-ассистент использовался для генерации кода и текста; все сценарии воспроизведены локально, результаты сохранены в `evidence/lab4/`. +- Автор, группа: TODO +- Целевая оценка; выбранный трек 5, если нужен: TODO +- Commit/PR: TODO после публикации +- Использованные источники, библиотеки и помощь ИИ: TODO ## Запуск из чистого clone -Prerequisites: Docker Engine/Desktop с Compose v2, Python 3.10+ для публичных и студенческих тестов, -Go 1.27 — только для unit/integration тестов и `make generate` (образ собирает приложение сам). - -```sh -git clone mtusi2026lab4 && cd mtusi2026lab4 -git switch lab4 -cp -n .env.example .env -# синтетические креды S3 уже согласованы с infra/s3/s3.json: -make check -docker compose --env-file .env config --quiet -docker compose --env-file .env up -d --build -# дождаться /health/ready (LB, localhost:8080), затем: -make test -make test-attachments -make test-presign -make test-persistence ACTION_SCRIPT=scripts/restart.sh -``` - -Остановка без потери данных: `docker compose --env-file .env down` (named volumes сохраняются). -Намеренное удаление учебных данных: `docker compose --env-file .env down -v` (PostgreSQL, Redis, -SeaweedFS). `make test-failover ACTION_SCRIPT=scripts/stop-one.sh` останавливает одну API-реплику; -вернуть её: `docker compose --env-file .env up -d --no-deps api`. - -`make validate` требует `requirements-dev.txt`; локально использовался `.venv`: -`python3 -m venv .venv && .venv/bin/pip install -r requirements-dev.txt`. -`make check` проверяет контракт, Python-синтаксис и совпадение S3 identities с `.env`. -`.env` не коммитится; все значения в `infra/s3/s3.json` — синтетические для локального стенда. +TODO: версии runtime/образов, prerequisites, команды создания локальных secrets/.env, build, миграций, запуска, ожидания готовности, тестов и остановки. Указать необходимые действия оператора. Не вставлять секреты. Отдельно указать безопасную остановку и команду намеренного удаления учебных данных. ## Архитектура и решения -```mermaid -flowchart LR - C[Клиент] -->|HTTP| LB[HAProxy :8080] - LB --> A1[API 1] - LB --> A2[API 2] - A1 --> PG[(PostgreSQL: метаданные)] - A2 --> PG - A1 -->|S3 SDK| S3[(SeaweedFS: байты)] - A2 -->|S3 SDK| S3 - A1 -->|presigned PUT URL| C - C -->|PUT напрямую| S3 - A1 -.->|sweep + advisory lock| PG - A1 -.->|sweep| S3 -``` - -- **Источник истины:** метаданные (`users`, `chats`, `messages`, `attachments`, `message_attachments`) — PostgreSQL; оригиналы — только приватный bucket SeaweedFS. Redis используется для кэша списка чатов и не является источником истины. -- **201 честный:** upload сначала валидирует изображение, пишет объект в S3, затем переводит pending-строку в ready. 201 возвращается только после обоих шагов. Если процесс умер между ними, строка остаётся pending, объект уже в S3; sweeper либо восстанавливает ready, либо удаляет пару после grace. -- **Границы транзакций:** сообщение и связи `message_attachments` вставляются в одной транзакции вместе с Idempotency-Key; вложения проверяются до claim. Сам S3 не транзакционен, поэтому используется pending/ready + компенсация. -- **Идемпотентность сообщений:** fingerprint включает `text` и `attachment_ids` в исходном порядке; отсутствующий `attachment_ids` и `[]` эквивалентны. Повтор с другим набором или порядком — 409. -- **Sweeper:** один владелец через `pg_try_advisory_lock`, grace period. Удаляет только объекты старше grace и только не ready; pending с валидным объектом восстанавливает в ready. Повторный запуск идемпотентен. -- **Readiness:** проверяет PostgreSQL, но не S3. S3 общий для всех реплик; его недоступность не должна убирать из ротации весь стенд. Attachment-endpoint при этом отвечают 503, остальные продолжают работать. Это осознанное решение зафиксировано здесь. -- **Перенесено из lab3:** пользователи, сессии, чаты, сообщения, идемпотентность, LB, PostgreSQL, Redis, Compose/Swarm-подход, HAProxy active checks. Добавлено: S3-стенд, `s3-init`, миграция `00004`, вложения, presign-расширение, sweeper. -- **Переменные:** `.env.example` перечисляет реальные имена, которые читает viper (`S3_*`, `MAX_UPLOAD_BYTES`, `MAX_IMAGE_PIXELS`, `S3_SWEEP_*`). Для двух лимитов добавлены явные alias-биндинги, потому что skeleton предлагал имена без префикса `S3_`. - -### Presigned extension - -Контракт `contracts/openapi.json` не изменён. Дополнительные endpoint: - -- `POST /api/v1/chats/{chat_id}/attachments/presign` — JSON с `filename`, `content_type`, `size_bytes`, `sha256`; создаёт pending-строку и возвращает короткоживущий URL. -- `POST /api/v1/attachments/{attachment_id}/complete` — проверяет размер, фактический SHA-256 и структуру изображения, копирует объект из `staging/` в `attachments/` и переводит строку в ready. - -Преимущества и ограничения: -- тело не проходит через API/LB (в замере LB RX падает с 9,49 МБ до 3,8 КБ для 9 МиБ); -- complete перечитывает объект из S3 для проверки SHA, поэтому API RX остаётся около размера файла; выигрыш — в клиентском плече и в отказе от приёма тела; -- `Content-Length` подписан в URL, поэтому S3 отклоняет PUT другого размера с 403 ещё до сохранения; - complete повторно сверяет размер, SHA-256 и структуру. Брошенные объекты удаляет sweeper после grace; -- URL — bearer-токен, многоразовый до `expires_at`; подпись привязана к host+key, Content-Type не подписывается. +TODO: схема процессов/хранилищ, источник истины, транзакционные границы, ограничения. Что перенесено из lab4, что изменено в этой работе. Соответствие переменных из .env.example реальной конфигурации. ## Доказательства критериев -| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл | +| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства | | --- | --- | --- | --- | -| Публичный smoke | `make test` | PASS, lab4 | `evidence/lab4/smoke.txt` | -| Все обязательные endpoint lab3 сохранены | smoke + `make test-persistence` | PASS | `smoke.txt`, `persistence.txt` | -| S3 в общем стенде, bucket приватный | `docker compose exec seaweedfs wget …/attachments/nope` | HTTP 403 | `private-bucket.txt` | -| Метаданные в PostgreSQL, байты в S3 | архитектура + `GET /content` после остановки реплики | скачивание через другую реплику | `failover.txt` | -| POST вложения 201 ready, оригинал побайтно | `attachment()` в smoke | checksum/size совпадают | `smoke.txt` | -| Message с attachment_ids | smoke, `student-tests/attachments_negative.py` | `attachment_ids` сохранены | `smoke.txt`, `negative.txt` | -| PNG/JPEG ≤10 MiB, ≤40 МП, MIME по содержимому | `make test-attachments` | 413/415 на границах | `negative.txt` | -| Опасные filename | 400 на `/`, `\`, NUL, control | 400 | `negative.txt` | -| Upload → stop реплики → download другой | `attachment_failover.py` | SHA совпадает | `failover.txt` | -| Restart с volumes | `make test-persistence` | данные и сессия сохранены | `persistence.txt` | -| Уровень 4: негативные тесты | `make test-attachments` | PASS, ни одного 500 | `negative.txt` | -| Отказ между S3/БД не оставляет вечных объектов | `sweep.txt` + unit-тесты sweeper | pending удалён после grace, ready жив | `sweep.txt` | -| Лимиты/таймауты/стриминг, RAM ограничена | memory experiment | 10 одновременных × 9,45 МБ; anon +1,97 МБ | `memory/` | -| Bootstrap bucket идемпотентен | `s3-init` дважды | оба запуска exit 0 | `s3-init.txt` | -| Отдельные ограниченные S3 credentials | `s3-init` probes + `docker compose exec` | app не пишет вне префиксов; anonymous 403 | `s3-init.txt`, `private-bucket.txt` | -| Админ-консоль/порты не в общей сети | `docker compose ps` | опубликованы только LB и loopback S3 | `private-bucket.txt` | -| Трек 1: presigned upload | `make test-presign`, `expiry.txt` | happy path, foreign, incomplete, checksum, expiry | `presign.txt`, `expiry.txt` | -| Трек 1: трафик и RAM на ≥2 размерах | `scripts/lab4_track1.py` | LB RX 3,8 КБ vs 1,05/9,49 МБ | `track1/` | +| Публичный smoke | make test | TODO | TODO | +| Остальные пункты уровня 3 | TODO | TODO | TODO | +| Все пункты уровня 4, если заявлен | TODO | TODO | TODO | +| Выбранный трек 5, если заявлен | TODO | TODO | TODO | + +TODO: добавить отдельную строку для каждого заявленного критерия. PASS без команды и наблюдения не является доказательством. Проверка инфраструктурного hook требует подтверждения, какие реальные процессы/хранилища перезапущены. ## Эксперименты и отказы -Стенд: Apple Silicon (arm64), Docker Desktop с VM 1,9 ГБ, Compose; API 2 реплики × 256 МБ, -SeaweedFS 640 МБ (GOMEMLIMIT 512 MiB), PostgreSQL 192 МБ, Redis 96 МБ, HAProxy 48 МБ. -Все замеры — локальные, без внешней сети. +TODO: гипотеза, hardware/лимиты, версии, объём данных, профиль нагрузки, concurrency/arrival rate, длительность/прогрев, повторы, успешные RPS, ошибки, p50/p95/p99, CPU/RAM. Сохранить raw summary без tokens и объяснить ограничения измерения. -| Воздействие | Что ожидали | Что наблюдали | Восстановление / потери | +| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных | | --- | --- | --- | --- | -| Upload, затем `stop` обслужившей реплики | download через вторую реплику | PASS, байты и SHA совпали | HAProxy убрал реплику; возврат `up -d --no-deps api` | -| Restart PostgreSQL/Redis/SeaweedFS/API с volumes | метаданные, сессия и оригинал сохраняются | PASS | 43,9 с до readiness; потерь нет | -| Остановка SeaweedFS | upload/download 503, остальное 200 | `/health/ready` 200, чаты 200, upload/download 503 | после старта upload снова 201 | -| Брошенный presign без PUT | удаление после grace, ready не трогать | pending исчез после ~2 с grace; ready скачан | sweeper, потерь ready нет | -| 10 одновременных загрузок по 9 454 448 Б, 3 раунда | API не OOM, RAM ограничена | 30 загрузок за 2,98 с; anon baseline 280,3 МБ, peak 281,7 МБ (+1,34 МБ); `memory.current` peak 411,8 МБ на две реплики; SeaweedFS restarts=0, OOM=false | без OOM после подбора лимитов под 1,9 ГБ VM | -| Presigned URL с TTL=3 с | 403 после истечения | 403 через 4 с | — | -| Неверный SHA на complete | отказ и очистка | 409/400, объект удалён | повторная загрузка возможна | - -### Трек 1: proxy vs presigned - -| Размер | Поток | Медиана, с | p95, с | LB RX, Б | API RX, Б | API anon peak, Б | -|---|---|---:|---:|---:|---:|---:| -| ~1 МиБ | proxy | 0,228 | 0,233 | 1 058 392 | 1 061 729 | 285 638 656 | -| ~1 МиБ | presign | 0,230 | 0,239 | 3 755 | 1 058 061 | 286 216 192 | -| ~9 МиБ | proxy | 0,237 | 0,240 | 9 490 341 | 9 494 663 | 286 285 824 | -| ~9 МиБ | presign | 0,239 | 0,246 | 3 879 | 9 472 840 | 286 367 744 | - -Методика: 5 итераций на сценарий без прогрева (стенд уже прогрет), PNG фиксированного размера, -клиент — тот же хост. `lb_rx` — сумма по LB; `api_rx` — сумма по двум API; `anon` — cgroup -`memory.stat`, сэмплирование 0,1 с. Ограничение: `memory.current` включает page cache временных -файлов; поэтому основная метрика — `anon`. Стенд локальный, сеть Docker bridge, поэтому абсолютные -латентности не переносятся на production. +| TODO | TODO | TODO | TODO | ## Ограничения и следующие шаги -- **Readiness не включает S3.** Это выбрано, чтобы недоступность общего S3 не убирала из ротации - все API-реплики; attachment-endpoint деградируют в 503. Если политика требует fail-closed, - добавьте S3 в readiness отдельным флагом. -- **Presigned PUT ограничен подписанным `Content-Length`.** Клиент обязан прислать ровно - заявленный размер; иначе SeaweedFS отвечает 403 (проверено). Это защищает от записи огромного - staging-объекта, но не заменяет rate limiting: число готовых вложений и pending-строк - по-прежнему не квотируется. -- **Complete перечитывает объект из S3.** SeaweedFS не валидирует и не хранит checksum, поэтому - честная проверка SHA требует чтения. Для больших файлов это удваивает внутренний трафик. -- **S3 — одна нода SeaweedFS.** Это учебный стенд; HA/replication не настроены. Потеря volume - означает потерю байтов; метаданные в PostgreSQL при этом остаются. Лимиты контейнеров подобраны - под Docker Desktop VM 1,9 ГБ; HAProxy `timeout server` увеличен до 45 с для 10 MiB загрузок, - readiness-проба по-прежнему 1 с. -- **lab5 не реализован:** thumbnail, варианты, queued/processing/202, worker. Поле `variants` - всегда `[]`, `status` — только `ready`. -- **Старые Idempotency-Key lab3** имеют fingerprint без `attachment_ids`; повтор такого ключа в - пределах TTL даст 409. Это осознанное изменение формата, данные не мигрируются. -- **Rate limiting (429) и квоты не реализованы**; контракт их не требует. Локальный - `docker-compose.local.yaml` публикует PostgreSQL/Redis на loopback с учебными паролями, а - HAProxy stats на 8404 не требует аутентификации — это операторские порты, не публичный стенд. -- **Секреты:** локальные S3-креды синтетические и лежат в `infra/s3/s3.json`/`.env.example`; - admin-креды не входят в `.env` и не попадают в API-контейнер (проверено `docker compose exec api env`). - Для production нужны отдельные секреты и отзыв URL через ротацию кредов. -- **Проверка изображений структурная**, без decode+re-encode (OWASP рекомендует re-encode для - недоверенных изображений). В lab4 изображения не обрабатываются и не исполняются; lab5 добавит - контролируемый decode для thumbnail. +TODO: какие отказы выдерживаются и какие нет; что не реализовано; где учебное упрощение; какое улучшение подтверждено, а какое пока гипотеза. diff --git a/compose.example.yaml b/compose.example.yaml index 76a785ff..792b3f4e 100644 --- a/compose.example.yaml +++ b/compose.example.yaml @@ -1,12 +1,14 @@ # Topology worksheet, deliberately NOT a runnable stack (no application supplied). # Implement compose.yaml or stack.yaml; do not submit this empty file as deployment. # Service names below are logical roles, not imposed container names. -x-lab-number: 4 +x-lab-number: 5 x-required-roles: - api - postgres - load_balancer - s3 + - broker + - worker # TODO: implement real images/builds, network wiring, volumes, healthchecks, # credentials and bootstrap. Details: contracts/infrastructure.json and README.md. services: {} diff --git a/contracts/attachment-states.md b/contracts/attachment-states.md new file mode 100644 index 00000000..9e0eb163 --- /dev/null +++ b/contracts/attachment-states.md @@ -0,0 +1,21 @@ +# Состояния вложения и договор между producer/worker + +Сообщение broker соответствует [jobs.schema.json](jobs.schema.json). Можно применять native headers брокера для trace context, но семантика carrier сохраняется; для проверки покажите отображение полей. `job_id` идентифицирует одну логическую работу и не меняется при redelivery; `attempt` начинается с 1 и отражает управляемую попытку обработки (broker redelivery сам по себе не создаёт новый job_id). Ключ эффекта — `(attachment_id, pipeline_version, variant)`. + +| Переход | Условие | Что устойчиво сохранено | +| --- | --- | --- | +| нет → queued | Принимаем upload; только после durable handoff отвечаем 202 | Полный проверенный оригинал в staging, метаданные, намерение обработки | +| queued → processing | Worker захватил/арендовал работу | Попытка, lease/deadline или эквивалентная защита | +| processing → queued | Временная ошибка и остались попытки | Причина без секретов, время следующей попытки | +| processing → ready | Все обязательные объекты записаны и результат атомарно опубликован | Оригинал, thumbnail (на 4 ещё crop/optimized), метаданные/checksums | +| processing → failed | Ошибка постоянная или попытки исчерпаны | error_code и запись, доступная оператору | +| processing → queued | Истёк lease после смерти worker | Восстановленная работа, без дублирования эффектов | +| failed → queued | Явный операторский replay, доступен на 4 | Audit, новая попытка, прежний логический эффект защищён от дубля | + +Повторная доставка уже ready-задачи — no-op с ack после проверки завершённого эффекта. Конкурентные попытки не перезаписывают более новый pipeline_version. Основной курс использует pipeline_version=1; версионирование нескольких pipeline — трек 5. Заявляйте готовность только когда все обещанные уровнем варианты доступны. Нельзя откатывать ready в processing из-за старого дубля. + +**Окна отказа для защиты:** после staging до записи задания; после COMMIT до publish; после publish до confirm; после записи S3 до COMMIT результата; после COMMIT результата до ack. На 3 покажите сохранность успешно принятой работы и повторную доставку; на 4 автоматическое восстановление разрыва DB/broker (outbox/эквивалент) и зависшего processing. + +Staging не удаляется до безопасной публикации результатов. Неуспешные/непривязанные исходники имеют документированный retention и cleanup; он не удаляет текущую работу. Broker принимает только ID/служебные данные, не произвольный URL для скачивания и не путь из клиентского filename. Worker берёт доверенные storage metadata из БД. + +Ack подтверждает устойчивую обработку, publisher confirm — приём брокером; это разные границы. См. [RabbitMQ reliability](https://www.rabbitmq.com/docs/reliability). At-least-once + идемпотентный эффект не означает exactly-once доставку. diff --git a/contracts/infrastructure.json b/contracts/infrastructure.json index dd2edf2d..a4cfcb7b 100644 --- a/contracts/infrastructure.json +++ b/contracts/infrastructure.json @@ -1,5 +1,5 @@ { - "lab": 4, + "lab": 5, "kind": "requirements, not runnable deployment", "required_for_grade_3": [ { @@ -27,6 +27,22 @@ ], "private_bucket": true, "persistent_volume": true + }, + { + "role": "broker", + "choose_one": [ + "RabbitMQ", + "Redis Streams", + "Valkey Streams", + "NATS JetStream", + "documented durable equivalent" + ], + "persistent_volume": true, + "delivery": "at-least-once" + }, + { + "role": "worker", + "separate_process": true } ], "optional_components": [ diff --git a/contracts/jobs.schema.json b/contracts/jobs.schema.json new file mode 100644 index 00000000..2e9aa484 --- /dev/null +++ b/contracts/jobs.schema.json @@ -0,0 +1,63 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "urn:mtusi:messenger:attachment-job:v1", + "title": "Durable attachment processing job v1", + "type": "object", + "additionalProperties": false, + "required": [ + "schema_version", + "job_id", + "type", + "attachment_id", + "pipeline_version", + "attempt", + "created_at" + ], + "properties": { + "schema_version": { + "const": 1 + }, + "job_id": { + "type": "string", + "format": "uuid" + }, + "type": { + "const": "attachment.process.v1" + }, + "attachment_id": { + "type": "string", + "format": "uuid" + }, + "pipeline_version": { + "type": "integer", + "minimum": 1 + }, + "attempt": { + "type": "integer", + "minimum": 1 + }, + "created_at": { + "type": "string", + "format": "date-time" + }, + "traceparent": { + "type": "string", + "pattern": "^00-[0-9a-f]{32}-[0-9a-f]{16}-[0-9a-f]{2}$" + }, + "tracestate": { + "type": "string", + "maxLength": 512 + } + }, + "examples": [ + { + "schema_version": 1, + "job_id": "11111111-1111-4111-8111-111111111111", + "type": "attachment.process.v1", + "attachment_id": "22222222-2222-4222-8222-222222222222", + "pipeline_version": 1, + "attempt": 1, + "created_at": "2026-09-01T12:00:00Z" + } + ] +} diff --git a/contracts/openapi.json b/contracts/openapi.json index 138f07c0..4face909 100644 --- a/contracts/openapi.json +++ b/contracts/openapi.json @@ -1,8 +1,8 @@ { "openapi": "3.1.0", "info": { - "title": "MTUSI Messenger — лабораторная 4", - "version": "1.4.0", + "title": "MTUSI Messenger — лабораторная 5", + "version": "1.5.0", "description": "Нормативный минимум на 3. Семантика: contracts/README.md. Расширения на 4/5 не должны менять этот API. Наличие кода ошибки в схеме не требует реализовать факультативную причину его выдачи." }, "servers": [ @@ -2151,7 +2151,7 @@ "operationId": "uploadAttachment", "summary": "Принять один PNG/JPEG, до 10 MiB", "responses": { - "201": { + "202": { "description": "Успех", "headers": { "X-Request-Id": { @@ -2936,7 +2936,10 @@ "schema": { "type": "string", "enum": [ - "original" + "original", + "thumbnail", + "crop", + "optimized" ], "default": "original" } @@ -3461,7 +3464,10 @@ "status": { "type": "string", "enum": [ - "ready" + "queued", + "processing", + "ready", + "failed" ] }, "variants": { diff --git a/lab.json b/lab.json index e9ffc9f7..db0c9c35 100644 --- a/lab.json +++ b/lab.json @@ -1,7 +1,7 @@ { - "number": 4, - "title": "S3-хранилище и вложения", - "contract_version": "1.4.0", + "number": 5, + "title": "Очереди и асинхронная обработка изображений", + "contract_version": "1.5.0", "default_base_url": "http://localhost:8080", "grading": "3; 4 includes 3; 5 includes 4 plus one completed research track", "scaffold_has_application": false