Автор / группа: ivanstorozhev, БВТ2304 Целевая оценка (3/4/5): 4 Трек 5, если заявлен: не заявлен Что реализовано и что перенесено: из lab4 перенесены Spring Boot API, PostgreSQL, Redis-кэш сессий, Argon2id, Liquibase через одноразовый сервис migrate, HAProxy без sticky session, две реплики, X-Instance-Id, обязательный Idempotency-Key, scripts/stop-one.sh и scripts/restart.sh, приватный SeaweedFS, таблица attachments и скачивание оригинала через API. Ключ объекта назначает сервер. У API отдельный ключ S3 с правами Read/Write/List; Admin используется только чтобы создать bucket. Объект без строки в базе старше двух минут удаляет фоновая очистка. Добавлены ответ 202, staging, transactional outbox, отдельный worker, Kafka 3.9.1 (KRaft, volume kafka-data), состояния queued/processing/ready/failed, JPEG thumbnail и crop, lossy WebP, retry с backoff и jitter, топик attachments.failed, явный replay и lease. Сообщение брокера содержит только идентификаторы. Подтверждение записи брокером (acks=all) и commit смещения потребителя разделены. Команды запуска из чистого clone: cp .env.example .env docker compose --env-file .env config --quiet docker compose --env-file .env up -d --build curl -fsS http://127.0.0.1:8080/health/ready make test make test-persistence ACTION_SCRIPT=scripts/restart.sh make test-failover ACTION_SCRIPT=scripts/stop-one.sh docker compose --env-file .env start api python3 scripts/grade4-evidence.py Результаты проверок и ссылка на REPORT.md: подробности и числа в REPORT.md make check — PASS: offline skeleton structure, local refs and Python syntax. make test — PASS: lab5 public API scenario. make test-persistence ACTION_SCRIPT=scripts/restart.sh — PASS: persistence preserved confirmed data and existing session. Хук перезапускает и kafka. make test-failover ACTION_SCRIPT=scripts/stop-one.sh — PASS: две реплики до отказа, восстановление записи за 1.795 с, 117 успешных записей и 1 ошибка перехода. python3 scripts/grade4-evidence.py — PASS. Worker остановлен: после рестарта API вложение осталось queued, затем стало ready; thumbnail JPEG 256×160, crop JPEG 128×128, optimized WebP 320×200, оригинал 111817 байт совпал. Конец топика attachments.process вырос 2→3 и после restart kafka остался 3. Пауза outbox пережила kill API, unpublished=1, затем тот же id стал ready. System.exit после записи объектов: RestartCount 0→1, один набор вариантов. Постоянный сбой processing_failed, топик attachments.failed, replay доводит то же вложение до ready, второй replay остаётся ready. mvn -q test в backend/ — код выхода 0, 22 теста: 202 и варианты, слишком большой файл 413, порча и подмена MIME 415, чужой id и другой чат 404, сирота в S3 удаляется. Анонимный GET объекта в сети стенда — HTTP 403. Ограничения / известные ошибки: трек 5 не делался. Один Docker-хост, единственные PostgreSQL, Redis, SeaweedFS, Kafka и HAProxy остаются точками отказа. Replication factor топиков равен 1. Доставка at least once: повтор перезаписывает те же ключи, но это не exactly-once на стороне S3. Если процесс умер после PUT staging и до COMMIT, объект без строки живёт не дольше grace period, затем удаляется. Staging failed-задания хранится сутки; позже replay уже не находит байты. Пока HAProxy не снял backend, часть запросов на останавливаемую реплику завершается ошибкой соединения; повтор с тем же Idempotency-Key безопасен для отправки сообщения. Источники и использование ИИ: контракт contracts/openapi.json, contracts/README.md, contracts/attachment-states.md, contracts/jobs.schema.json; код lab4; Spring Boot 4.1.1, Spring Data JPA, spring-security-crypto, Spring Data Redis, Spring Kafka, Liquibase, Actuator, MapStruct 1.6.3, OpenAPI Generator 7.17.0, AWS SDK for Java 2.31.50, Thumbnailator 0.4.20, webp-imageio 0.11.0, Bouncy Castle, PostgreSQL 16.10, Redis 7.4.6, HAProxy 3.2.6, SeaweedFS 4.52, Apache Kafka 3.9.1, Testcontainers. Реализация собрана в Cursor. Весь обязательный минимум текущей и предыдущих работ сохранён с объявленными переходами. Контракт и публичные тесты не ослаблены. make check и make test выполнены; приложен реальный вывод. Сценарии отказов своего уровня воспроизведены. Все секреты и приватные ключи находятся вне Git; отчёт не содержит tokens. README задания сохранён, REPORT.md содержит инструкцию именно моего решения. Co-authored-by: Cursor <cursoragent@cursor.com>
22 KiB
Отчёт — лабораторная 5
- Автор, группа: ivanstorozhev, БВТ2304
- Целевая оценка: 4
- Трек 5: не выбран
- Commit/PR: ветка
solution/bvt2304-storozhev - Использованные источники, библиотеки и помощь ИИ: контракт
contracts/openapi.json,contracts/README.md,contracts/attachment-states.md,contracts/jobs.schema.json. Код lab4 перенесён как основа (Spring Boot 4.1.1, Spring Data JPA, Liquibase, Redis-кэш сессий, HAProxy, Argon2id, OpenAPI Generator 7.17.0, AWS SDK for Java 2.31.50, SeaweedFS 4.52). Новое: Spring Kafka, Apache Kafka 3.9.1 (KRaft), Thumbnailator 0.4.20, webp-imageio 0.11.0. Помощь ИИ: перенос lab4, обработка вложений и отчёт сделаны в Cursor.
Запуск из чистого clone
Нужны Docker Desktop (проверено 28.5.1), Docker Compose и Python 3.9+. JDK 21 и Maven 3.9 нужны только для mvn test вне образа. На этой машине JDK — /opt/homebrew/opt/openjdk@21.
cp .env.example .env
# Перед общим стендом замените учебные пароли PostgreSQL и ключи S3 в .env.
docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build
curl -fsS http://127.0.0.1:8080/health/ready
make test
make test-persistence ACTION_SCRIPT=scripts/restart.sh
make test-failover ACTION_SCRIPT=scripts/stop-one.sh
# Поднять остановленную реплику:
docker compose --env-file .env start api
python3 scripts/grade4-evidence.py
Образ приложения собирает сервис migrate (messenger-lab5:1.0.0). У api и worker тот же образ и pull_policy: never. Миграции — одноразовый migrate, профиль migrate, Liquibase до changelog 007-jobs. Реплики api и worker стартуют после него с SPRING_LIQUIBASE_ENABLED=false. Bucket messenger-attachments создаёт API при readiness.
Остановка без удаления данных: docker compose --env-file .env stop. Снятие контейнеров с сохранением volumes: docker compose --env-file .env down. Намеренное удаление учебных данных: docker compose --env-file .env down -v. Файл .env в Git не входит.
Свои проверки: JAVA_HOME=/opt/homebrew/opt/openjdk@21 mvn -f backend/pom.xml test. Testcontainers поднимает PostgreSQL, Redis, Kafka и SeaweedFS.
Архитектура и решения
Клиент ходит только в HAProxy на 127.0.0.1:8080. Две реплики api портов наружу не публикуют. Пользователи, чаты, сообщения, сессии и идемпотентность перенесены из lab4: PostgreSQL — источник истины, Redis — только кэш разбора Bearer.
Загрузка больше не делает производные в запросе. POST /api/v1/chats/{chat_id}/attachments проверяет тип, размер и заголовки картинки, пишет байты в ключ staging/{id} и в одной транзакции сохраняет строку attachments (queued) и строку job_outbox. После COMMIT API отвечает 202. В брокер на этом шаге ещё ничего не уходит. Если транзакция не прошла, тот же запрос удаляет staging-объект.
Публикацию делает отдельный цикл outbox и в API, и в worker. Строка берётся FOR UPDATE SKIP LOCKED, запись уходит в топик attachments.process с acks=all, и только потом ставится published_at. Пока брокер не подтвердил запись, строка остаётся и будет отправлена снова. Пауза публикатора для демонстрации лежит в таблице demo_flags, поэтому переживает kill API. Сообщение — JSON attachment.process.v1: идентификаторы, номер попытки и версия конвейера. Байтов и ключей S3 в нём нет. Ключ Kafka-записи — attachment_id. Топик лежит на volume kafka-data.
Worker — отдельный процесс (--spring.profiles.active=worker, без HTTP). Он коммитит смещение Kafka только после записи исхода в PostgreSQL. Оригинал копируется в originals/{id} без изменения байтов. Производные пишутся в фиксированные ключи variants/{id}/thumbnail, crop, optimized. Повторная доставка перезаписывает те же ключи и заново вставляет тот же набор строк attachment_variants. Ключ эффекта — (attachment_id, pipeline_version, variant), сейчас pipeline_version=1.
Состояния в API: queued, processing, ready, failed. Пока статус не ready и не успешный original после ready, GET .../content отвечает 409. Failed-вложение к сообщению не прикрепляется (409). Queued и processing прикрепить можно. sha256 и size_bytes описывают оригинал.
Производные, качество записано в ImageVariants и в .env.example (JPEG_QUALITY=0.85, WEBP_QUALITY=0.8):
- thumbnail — JPEG, вписать в 256×256 без увеличения, размеры вниз, минимум 1 px. Фикстура 320×200 даёт 256×160;
- crop — JPEG 128×128 из центра, увеличение разрешено;
- optimized — lossy WebP, вписать в 1280×1280 без увеличения. Та же фикстура остаётся 320×200.
Перед изменением размера применяется EXIF orientation. Альфа кладётся на белый. В JPEG и WebP метаданные исходника не копируются. WebP quality 0.8 — это качество libwebp 80.
Лимиты: тело не больше 10 MiB (MAX_UPLOAD_BYTES), пиксели не больше 40 млн (MAX_IMAGE_PIXELS, проверка по заголовку до полного decode). Воркер обрывает обработку по JOB_TIMEOUT_SECONDS (60 с). Контейнер worker — 1 CPU и 1024 MiB, JVM -XX:MaxRAMPercentage=60 -XX:+ExitOnOutOfMemoryError. Одновременно воркер держит WORKER_CONCURRENCY потребителей (2) и такой же prefetch.
Повтор: не больше JOB_MAX_ATTEMPTS (5). Постоянные ошибки invalid_image и processing_failed сразу дают failed. Временные (S3, обрыв, неожиданный runtime) возвращают задание в queued с задержкой. База задержки — 1 с, на каждую следующую попытку она удваивается и упирается в 30 с; фактическая пауза выбирается случайно от половины этой базы до всей базы. После исчерпания попыток код retry_exhausted. Исход failed пишется в failed_jobs и best-effort публикуется в топик attachments.failed. Битый JSON пишется туда же, и только потом коммитится смещение, иначе запись навсегда заняла бы партицию.
Явный replay: POST /internal/demo/attachments/{id}/replay с заголовком X-Demo-Token (DEMO_TOKEN). Эти маршруты вне публичного контракта. Для ready вызов ничего не ставит в очередь. Для failed тот же attachment_id снова становится queued, счётчик попыток обнуляется, в outbox появляется одна новая строка. Staging failed-задания хранится до STAGING_RETENTION_SECONDS (86400), поэтому replay ещё может прочитать байты. После ready staging удаляется только если транзакция исхода закоммитилась.
На время processing ставится lease на JOB_TIMEOUT_SECONDS. Пока этот процесс сам держит lease_token, вторая запись того же задания пропускается. Если процесс умер до acknowledge(), новый процесс токена не помнит и забирает processing себе. Если запись брокера так и не вернулась, reaper раз в 5 с возвращает просроченный lease в outbox либо закрывает его как retry_exhausted.
/health/ready смотрит PostgreSQL и S3. Kafka в readiness не входит: брокер может лежать, а upload всё равно отвечает 202 за счёт outbox. Таймауты HAProxy подняты (клиент и разбор запроса 60 с, сервер 30 с), чтобы загрузка не обрывалась на старых 5 с.
| Роль | Сервис | Образ | Готовность | Volume | Сеть | Credentials |
|---|---|---|---|---|---|---|
| API | api × API_REPLICAS |
messenger-lab5:1.0.0 |
GET /health/ready |
нет файла оригинала | порт наружу не опубликован | env Spring, S3, Kafka |
| Worker | worker |
тот же образ, профиль worker |
kill -0 1, restart unless-stopped |
нет | порт наружу не опубликован | те же env, JAVA_TOOL_OPTIONS |
| Балансировщик | lb |
haproxy:3.2.6 |
процесс слушает 8080 | нет | только 127.0.0.1:8080 |
нет |
| Метаданные | postgres |
postgres:16.10 |
pg_isready |
postgres-data |
5432 только внутри сети | POSTGRES_* из .env |
| Кэш сессии | redis |
redis:7.4.6 |
redis-cli ping |
redis-data |
6379 только внутри сети | без пароля, сеть стенда |
| Брокер | kafka |
apache/kafka:3.9.1 |
kafka-broker-api-versions |
kafka-data |
9092 только внутри сети | без SASL, порт наружу не опубликован |
| Объекты | s3 |
chrislusf/seaweedfs:4.52 |
GET :9333/cluster/status |
s3-data |
8333/9333 только внутри сети | API: Read/Write/List. Bootstrap: Admin, только создание bucket |
| Миграции | migrate |
тот же образ | код 0 | нет | нет | тот же datasource |
Лимиты: API и worker по 1 CPU и 1024 MiB, PostgreSQL 1 CPU и 512 MiB, S3 0.5 CPU и 512 MiB, Kafka 0.5 CPU и 768 MiB (heap 256 MiB), Redis и HAProxy по 0.25 CPU и 128 MiB.
Соответствие .env.example: переменные lab4 те же. Добавлены SPRING_KAFKA_BOOTSTRAP_SERVERS, WORKER_CONCURRENCY, JOB_MAX_ATTEMPTS, JOB_TIMEOUT_SECONDS, JOB_BACKOFF_BASE_MS, JOB_BACKOFF_CAP_MS, STAGING_RETENTION_SECONDS, DEMO_TOKEN, JPEG_QUALITY, WEBP_QUALITY. Имена *_FILE из курса оставлены комментарием: стенд передаёт доступ переменными окружения, не файлами секретов. Kafka без пароля, потому что слушатель не опубликован наружу.
Доказательства критериев
Стенд: Mac, arm64, 12 CPU, 24 GiB RAM, Docker 28.5.1. Прогон 12 ноября 2026. Команды и цифры — evidence/results.txt и evidence/grade4.txt. Токены туда не записывались.
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства |
|---|---|---|---|
| Публичный smoke: 202, ready, оригинал и JPEG thumbnail | make test |
PASS: lab5 public API scenario |
evidence/results.txt |
| Оригинал и метаданные переживают рестарт всего стенда, включая worker и Kafka | make test-persistence ACTION_SCRIPT=scripts/restart.sh |
После смены брокера: PASS. Хук перезапускает и kafka, volumes не удаляет |
evidence/results.txt, scripts/restart.sh |
| Другая реплика API отдаёт тот же оригинал | make test-failover ACTION_SCRIPT=scripts/stop-one.sh на прогретом стенде |
2 instance id до отказа; 117 успешных записей, 1 ошибка на переходе, первая успешная запись через 1.795 с. PASS. Реплика поднята start api |
evidence/results.txt |
| Worker остановлен, upload 202, сообщение с вложением, рестарт API, затем worker | python3 scripts/grade4-evidence.py |
9c4ab448-af4d-4acf-883d-4a8929a8b5e1: после рестарта API всё ещё queued, content 409 conflict. После старта worker — ready. Оригинал 111817 байт совпал. Thumbnail JPEG 256×160, crop JPEG 128×128, optimized WebP 320×200 |
evidence/grade4.txt |
| Задание в брокере переживает рестарт Kafka с volume | worker остановлен, upload, compose restart kafka |
Конец топика attachments.process вырос 2→3 и после рестарта остался 3. Затем то же вложение 45a5da06-a3c3-4d12-ad25-3d5a9154d531 стало ready |
evidence/grade4.txt |
| Crash между COMMIT и publish | outbox на паузе, upload, compose kill api, start api, снять паузу |
До и после kill: paused=true, unpublished=1, статус queued, id 26bd80e5-7074-44b8-b2d5-1a28b14343fe. После resume тот же id ready с тремя вариантами |
evidence/grade4.txt |
| Падение worker после записи объектов и до commit смещения | файл /tmp/messenger-crash-after-write в контейнере worker, один upload |
RestartCount 0→1. Id 9e1ed645-d5b7-4006-a84c-75ac547eb165 стал ready. В БД по одной строке crop, optimized и thumbnail. Replay ready вернул ready и не добавил вариант |
evidence/grade4.txt |
| Постоянная ошибка, DLQ/реестр, явный replay | файл /tmp/messenger-fail-permanent, затем replay дважды |
Id 05e76bf9-a6d0-4dc9-9ea0-ee1950a1218b: failed, error_code=processing_failed. Сообщение с ним — 409 conflict. Реестр failed 1→2. Топик attachments.failed дошёл до смещения 1. Replay вернул queued, затем тот же id ready, в БД снова по одной строке варианта. Второй replay остался ready |
evidence/grade4.txt |
| Мусор вместо картинки | POST 415 в том же сценарии | unsupported_media_type. Лимиты 10 MiB и 40 млн пикселей закрывает AttachmentIntegrationTest |
evidence/grade4.txt, mvn test |
| Приватный bucket и порты | docker ps / inspect в том же сценарии, анонимный GET из сети стенда |
Наружу только lb на 127.0.0.1:8080. У api, worker, postgres, redis, kafka и s3 host-порт пустой. Kafka 768 MiB. Анонимный GET объекта — 403 |
evidence/grade4.txt |
| Конкуренция worker | лог старта worker | Два потребителя группы attachment-worker, партиции attachments.process-0 и attachments.process-1 |
лог messenger-lab5-worker-1 |
| Свои тесты | mvn -f backend/pom.xml -q test |
код выхода 0, 22 теста | evidence/results.txt |
| Трек 5 | не заявлен | — | — |
Живой прогон ждал 60 с истёкшего lease не делал: фикстура обрабатывается быстрее таймаута. Проверен соседний путь — повторная доставка при ещё живом lease после System.exit между PUT и COMMIT. Reaper для просроченного lease в коде worker есть (JOB_TIMEOUT_SECONDS, период 5 с).
Эксперименты и отказы
Отдельного замера RPS нет: оценка 4 этого не требует. Наблюдения ниже сняты тем же стендом.
| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных |
|---|---|---|---|
scripts/restart.sh сразу после серии kill/crash, пауза хука 5 с |
тот же Bearer читает оригинал | TimeoutError на GET content: клиент теста ждёт 2 с |
подтверждённые данные на месте; хук увеличен до 12 с |
| Тот же хук с паузой 12 с | /health/ready, затем чтение оригинала |
PASS |
метаданные, сессия и байты на месте |
stop-one.sh сразу после холодного рестарта |
загрузка и остановка одной реплики | TimeoutError на POST вложения ещё до hook |
повтор на прогретом стенде ниже |
stop-one.sh на прогретом стенде |
другая реплика принимает запись, остановленная сама не поднимается | 2 instance id, восстановление 1.795 с, 117 записей и 1 ошибка, PASS |
подтверждённые сообщения и оригинал на месте; реплика поднята start api |
| Worker остановлен, затем убит API | 202 и строка задания не пропадают | статус остался queued, после старта worker — ready |
работа не потеряна |
| Рестарт Kafka при записи в топике | запись остаётся на volume | конец топика 3 до и после рестарта, затем ready |
задание не потеряно |
Пауза outbox и kill обеих реплик API |
строка outbox переживает процесс | unpublished=1 до и после kill, затем тот же id ready |
новое задание вручную не создавалось |
System.exit после PUT и до ack |
повторная доставка заканчивает тот же результат | контейнер сам поднялся, один набор вариантов | дубля вариантов нет |
| Постоянный сбой до записи вариантов | failed, replay, повторный replay ready |
processing_failed, потом ready, второй replay остался ready |
второй набор вариантов не создан |
Ограничения и следующие шаги
Один Docker-host не переживает потерю этой машины. PostgreSQL, Redis, SeaweedFS, Kafka и HAProxy в одном экземпляре. Replication factor топиков равен 1.
Доставка at least once. Подтверждение брокера (acks=all) и commit смещения потребителя — разные границы. Повтор перезаписывает те же ключи и те же строки вариантов, но это не exactly-once на стороне S3: объект может быть записан дважды одинаковыми байтами.
Если процесс умирает после PUT staging и до COMMIT строки, объект без строки забирает sweeper после grace. Если строка failed живёт дольше STAGING_RETENTION_SECONDS, replay уже не находит байты и завершается processing_failed.
Пока HAProxy не снял backend, часть запросов попадает в останавливаемую реплику. Балансировщик POST не повторяет. Клиент может повторить тот же Idempotency-Key. Клиент публичных тестов отказов обрывает запрос через 2 с, поэтому хук рестарта ждёт не только /health/ready, но и 12 с, пока SeaweedFS начинает отдавать объекты быстрее этого таймаута.
Внутренние demo-маршруты закрыты общим токеном из окружения и не входят в OpenAPI. Для учебной демонстрации этого достаточно; отдельной роли оператора нет.