31 KiB
Лабораторная 5: объяснение и подготовка к защите
Начни с этого файла. В REPORT.md находятся подробный отчёт, результаты проверок и ограничения. Здесь — логика решения и команды, которые помогают её показать. Цель реализации — требования на 4; исследовательский трек на 5 не заявляется.
1. Что мы сделали простыми словами
Есть мессенджер: пользователь создаёт чат, отправляет сообщения и загружает картинки. В этой лабораторной после загрузки нужно подготовить несколько версий картинки. Это занимает время и память, поэтому обработку выполняет отдельный процесс — worker.
Представь приёмную мастерской: сотрудник принимает вещь и записывает заказ, а мастер выполняет работу позднее. Приёмная продолжает принимать посетителей, даже если мастер временно отсутствует. В программе API принимает файл, очередь передаёт задание, а worker создаёт варианты изображения.
Главная задача — сделать такую схему надёжной: после ответа «принято» файл и задание должны переживать остановку процессов, а повторная доставка задания должна давать один итоговый набор файлов.
Асинхронность не отменяет загрузку. Клиент сначала передаёт все байты. API проверяет файл и сохраняет его. Позднее worker выполняет преобразования.
2. Кто за что отвечает
| Компонент | Его работа | Что в нём хранится |
|---|---|---|
HAProxy (lb) |
Принимает HTTP-запросы и распределяет их между API | Настройки балансировки |
FastAPI (api, две реплики) |
Проверяет пользователя, доступ к чату и загрузку; отвечает клиенту | Собственных постоянных данных нет |
PostgreSQL (db) |
Хранит состояние приложения и намерение обработать файл | Пользователи, сессии, чаты, сообщения, вложения, outbox, история задач |
Valkey (valkey) |
Ускоряет проверку сессий | Восстанавливаемый кэш; исходные сессии есть в PostgreSQL |
SeaweedFS (s3) |
Предоставляет приватное S3-хранилище | Байты исходников и готовых файлов |
Publisher (publisher) |
Переносит сохранённые задания из outbox в RabbitMQ | Постоянное состояние находится в PostgreSQL |
RabbitMQ (broker) |
Хранит и доставляет сообщения с заданиями | Очередь attachments, очередь ошибочных сообщений attachments.dlq |
Worker (worker) |
Получает задание, создаёт варианты, фиксирует результат | Постоянные результаты пишет в S3 и PostgreSQL |
PostgreSQL — источник истины о состоянии, S3 — хранилище байтов. RabbitMQ сообщает worker, какую работу выполнить. В сообщение очереди входят ID и служебные поля; сам файл, пароли и пользовательский URL туда не помещаются.
3. Путь одной картинки
Пример: пользователь загружает PNG размером 320×200.
- Клиент отправляет сырые байты в
POST /api/v1/chats/{chat_id}/attachments?filename=photo.pngс Bearer-токеном иContent-Type: image/png. - API проверяет доступ к чату, имя, формат по содержимому, размер и целостность изображения. По ходу чтения считает SHA-256 — контрольную сумму исходных байтов.
- API записывает исходник в приватный раздел S3
staging/. Staging — место для надёжно принятого исходника, ожидающего обработки. - В одной транзакции PostgreSQL создаются вложение со статусом
queuedи строкаoutboxс намерением отправить задание. - После успешного COMMIT API отвечает 202 Accepted: «исходник принят, работа сохранена». В этом ответе
status=queued,variants=[]. - Publisher отправляет задание в RabbitMQ и получает подтверждение от брокера.
- Worker захватывает задачу, ставит
processing, читает staging и сверяет размер и SHA-256. Отдельный дочерний процесс создаёт варианты. - Worker записывает неизменённый оригинал и варианты в конечные ключи S3. Затем одной транзакцией публикует метаданные вариантов и состояние
readyв PostgreSQL. - После устойчивой фиксации worker подтверждает доставку брокеру. Клиент узнаёт
readyчерез GET метаданных и скачивает файлы через авторизованный API. - Publisher позднее удаляет staging-копию: готовый оригинал уже находится в конечном разделе S3.
Клиент → API → исходник в S3 staging + вложение/outbox в PostgreSQL → 202
↓
publisher
↓
RabbitMQ
↓
worker
↓
конечные файлы в S3 + ready в PostgreSQL
↓
GET клиента видит ready
Если worker очень быстрый, первый GET уже может показать ready. Ответ самого upload всё равно содержит сохранённый снимок queued.
4. Какие файлы получаются
| Имя | Правило | Для исходника 320×200 |
|---|---|---|
original |
Исходные байты без перекодирования | Тот же PNG 320×200 и тот же SHA-256 |
thumbnail |
JPEG, вписан в 256×256, пропорции сохранены, маленькие изображения не увеличиваются | 256×160 |
crop |
JPEG, квадрат из центра, приведённый к 128×128 | 128×128 |
optimized |
WebP, вписан в 1280×1280 без увеличения | 320×200 |
У JPEG-вариантов качество 85, у WebP — 80, method=4. Для вариантов учитывается EXIF-поворот, метаданные удаляются. Прозрачность JPEG заменяется белым фоном; WebP может сохранить прозрачность. Оригинал остаётся неизменным. WebP не обязан весить меньше каждого маленького исходника.
5. Четыре состояния
| Статус | Как объяснить | Можно скачать? |
|---|---|---|
queued |
Файл принят, работа ожидает выполнения или запланированного повтора | Нет, 409 |
processing |
Worker получил право выполнить текущую попытку | Нет, 409 |
ready |
Все обещанные файлы записаны, метаданные опубликованы | Да |
failed |
Постоянная ошибка либо закончились попытки | Нет, 409 |
Обычный путь: queued → processing → ready. При временной ошибке: processing → queued, затем новая попытка. При постоянной ошибке или исчерпании попыток: processing → failed. После устранения причины оператор может явно вернуть failed → queued командой replay, пока исходник сохранён.
В сообщение чата разрешается прикрепить queued или processing: сообщение уже существует, а картинка появится после обработки. Прикрепить failed нельзя — 409. Проверку доступа к чату выполняет API при каждом чтении и скачивании.
6. Самое важное: outbox, confirm и ack
Зачем нужна outbox
Запись в PostgreSQL и отправка в RabbitMQ — две отдельные операции. Возможен сбой:
Сохранили вложение в БД → процесс упал → задание не дошло до RabbitMQ
Чтобы задание не потерялось, вложение и запись outbox создаются одной транзакцией. Outbox — обычная таблица в PostgreSQL: «эту работу ещё нужно отправить». После перезапуска publisher найдёт строку и отправит задание.
Publisher отмечает строку опубликованной только после подтверждения брокера. Если брокер уже принял сообщение, а publisher упал до отметки в БД, произойдёт повторная отправка. Поэтому worker обязан безопасно обрабатывать дубли.
Два разных подтверждения
| Подтверждение | Кто кому отправляет | Что оно означает |
|---|---|---|
| Publisher confirm | RabbitMQ → publisher | Брокер принял публикацию |
| Consumer ack | Worker → RabbitMQ | Эту доставку можно удалить: результат либо решение о повторе/ошибке устойчиво сохранены |
Confirm не означает готовность картинки. Ack нельзя отправлять сразу после получения задания: если затем worker погибнет, брокер уже будет считать доставку завершённой.
7. Почему дубли нормальны и не размножают результат
Здесь используется at least once: при восстановлении сообщение может прийти повторно. Например, worker записал ready и погиб до отправки ack. RabbitMQ повторит доставку, потому что не знает о COMMIT в PostgreSQL.
Идемпотентность означает, что повтор работы сохраняет тот же логический результат. В этой реализации:
job_idобозначает одну логическую работу и сохраняется при повторах и replay.attemptобозначает управляемую попытку. Старое сообщение с другим номером не запускает актуальную работу.- Ключ эффекта —
(attachment_id, pipeline_version, variant). Например: одно вложение, версия 1, вариантthumbnail. Конечные S3-ключи определяются этими данными, а не случайным именем для каждого повтора. - Worker проверяет состояние в БД: дубль уже готовой задачи получает ack, повторное преобразование не запускается.
- Метаданные всех вариантов и
readyфиксируются одной транзакцией. Клиент не получает частично готовый список как завершённый результат.
Это не exactly once доставка: сообщение действительно может доставляться несколько раз. Безопасным делается его эффект. В работе используется только pipeline_version=1; исследование нескольких версий относится к треку на 5.
8. Повторы, lease и ограничения
Retry — автоматическая повторная попытка после временной ошибки. Например, S3 временно недоступно. Максимум по умолчанию — пять попыток на запуск обработки; после этого failed с retry_exhausted. Неверная контрольная сумма или повреждённый файл считаются постоянной ошибкой: повторять те же плохие данные автоматически бессмысленно.
Backoff увеличивает ожидание между попытками, а jitter добавляет случайность, чтобы многие задачи не повторялись одновременно. При базовой задержке 1 секунда первые интервалы — 0.5–1, 1–2, 2–4, 4–8 секунд. Дата следующей попытки и новая строка outbox сохраняются в БД до ack старой доставки.
Lease — временное право worker обрабатывать задачу. Вместе с processing записываются срок аренды и случайный lease_token. По умолчанию срок 120 секунд, а вся попытка ограничена 90 секундами. Записать результат может только владелец действующего token. Если процесс погибнет, publisher обнаружит истёкшую аренду и сохранит повтор либо окончательную ошибку при исчерпанном бюджете. Дубль сообщения сам по себе не запускает второй декодер для уже захваченной задачи.
| Ограничение | По умолчанию | Для чего |
|---|---|---|
| Размер upload | 10 MiB | Ограничить входной трафик и хранение |
| Размер изображения | 40 млн пикселей | Отсеять изображения, требующие слишком большой распаковки |
| Одновременные upload | 8 на API-реплику | Ограничить занятость API |
| Активные задачи worker / prefetch | 1 / 1 | Не забирать большую пачку задач и не запускать много декодеров |
| Время декодера / всей попытки | 30 / 90 секунд | Остановить слишком долгую обработку |
| Адресное пространство декодера | 768 MiB в Linux | Ограничить память дочернего процесса |
| Память контейнера worker | 1 GiB | Дополнительно ограничить весь worker |
При timeout родитель убивает дочерний процесс и ожидает его завершения. Лимит 40 млн пикселей — верхняя граница допуска, а не обещание, что любой такой файл успешно обработается в лимите памяти.
Готовый staging удаляется после ready. Для failed исходник и частичные результаты хранятся семь суток, чтобы можно было устранить причину и выполнить replay. После очистки нужен новый upload.
9. Где это искать в коде
| Файл | Что показать преподавателю |
|---|---|
| app/attachments.py | Приём файла, staging, создание queued/outbox, чтение и скачивание |
| app/images.py | Проверка PNG/JPEG по содержимому, целостности и числу пикселей |
| app/jobs.py | relay_one — отправка outbox; recover_leases — восстановление; cleanup_staging — уборка |
| app/pipeline.py | Очереди, формат сообщения, confirm, backoff, retry_or_fail, точки сбоев |
| app/worker.py | claim — захват; build_objects — файлы; finish — фиксация; handle — обработка доставки и ack |
| app/image_worker.py | Thumbnail/crop/WebP, ограничения дочернего процесса |
| app/operator.py | Реестр failed, явный replay, тестовая повторная доставка, включение сбоев |
| migrations/005_async_pipeline.sql | Поля задач, таблицы outbox, job_events и fault_injections |
| compose.yaml | Все сервисы, версии образов, volumes, сети и ресурсы |
| student-tests/lab5_recovery.py | Воспроизводимые сценарии остановок, падений, повторов и replay |
10. Как показать работу в PowerShell
Команды выполняются из корня проекта. Сначала запусти Docker Desktop с Linux-контейнерами.
# Первичная подготовка; существующий .env сохраняем.
powershell -ExecutionPolicy Bypass -File scripts/init-secrets.ps1
if (-not (Test-Path .env)) { Copy-Item .env.example .env }
docker compose config --quiet
docker compose up -d --build --wait --wait-timeout 180
docker compose ps
# Узнаём фактический внешний порт LB; не выводим содержимое .env и secrets.
$binding = docker compose port lb 8080 | Select-Object -First 1
if ($binding -notmatch ':(\d+)$') { throw 'Не удалось определить порт lb' }
$base = "http://localhost:$($Matches[1])"
Invoke-RestMethod "$base/health/ready"
# Контракт и обычная работа API.
python -X utf8 scripts/check_contract.py
python -X utf8 tests/smoke.py --base-url $base
# Подготовка инструментов для проверок с управлением контейнерами.
docker compose --profile tools build tester
docker compose --profile tools run --rm tester python3 student-tests/lab5_images.py
Если порт 8080 занят другим приложением, задай свободный LB_PORT в локальном .env перед запуском. Внутри Docker тесты обращаются к http://lb:8080, внешний порт им не нужен.
Для автоматического запуска всех проверок после старта стенда достаточно python -X utf8 scripts/test_lab5.py. Скрипт сам собирает tester, запускает проверки и сохраняет вывод в evidence/. Полный запуск включает остановки и падения процессов и занимает несколько минут. Вариант python -X utf8 scripts/test_lab5.py --quick проверяет API, изображения и лимиты без остановок сервисов. Проверка схем OpenAPI описана отдельно в отчёте.
В полном запуске публичный persistence-тест сначала останавливает приложение, затем аварийно завершает хранилища через SIGKILL и запускает их с теми же volumes. Так проверяется сохранность уже подтверждённых данных после аварии. Для обычной остановки стенда используется docker compose stop.
Сценарии отказов запускай последовательно на учебном стенде. Они создают синтетические данные, управляют его контейнерами и возвращают остановленные сервисы в finally; реальные токены не печатаются.
# Worker выключен → upload202 → API и broker перезапущены → тот же файл ready.
docker compose --profile tools run --rm tester python3 student-tests/lab5_recovery.py --mode persistence
# Падение publisher после COMMIT, до publish → восстановление через outbox.
docker compose --profile tools run --rm tester python3 student-tests/lab5_recovery.py --mode outbox
# Падение worker после записи S3, до COMMIT → восстановление по lease.
# Здесь нормально ждать примерно срок аренды, по умолчанию 120 секунд.
docker compose --profile tools run --rm tester python3 student-tests/lab5_recovery.py --mode objects
# Падение после COMMIT ready, до ack → безопасная повторная доставка.
docker compose --profile tools run --rm tester python3 student-tests/lab5_recovery.py --mode ack
# Повреждённый исходник → failed → восстановление исходника → явный replay.
# Затем дубль готовой задачи должен оставить результат прежним.
docker compose --profile tools run --rm tester python3 student-tests/lab5_recovery.py --mode replay
# S3 недоступно → ограниченные повторы → failed → replay после восстановления.
docker compose --profile tools run --rm tester python3 student-tests/lab5_recovery.py --mode retry
# Ограничения декодера на настоящем изображении.
Get-Content -Raw student-tests/lab5_limits.py | docker compose exec -T worker python
PASS означает, что проверен конкретный сценарий. Один smoke не подтверждает все требования на 4. Фактические результаты и ссылки на логи находятся в отчёте; этот файл описывает назначение проверок.
Для ручной работы оператора доступны следующие команды. В $attachmentId подставляется ID нужного вложения из ответа API или реестра failed:
docker compose exec --index 1 api python -m app.operator failed
$attachmentId = 'UUID_нужного_вложения'
docker compose exec --index 1 api python -m app.operator replay $attachmentId --reason 'Причина устранена'
docker compose exec --index 1 api python -m app.operator redeliver $attachmentId
Replay восстанавливает failed после устранения причины и сбрасывает бюджет автоматических попыток; действие записывается в аудит. Для ready replay — no-op. Redeliver отправляет дубль того же задания для проверки защиты от повторной доставки.
Остановить стенд с сохранением данных: docker compose stop. Возобновить: docker compose up -d --wait --wait-timeout 180. Данные PostgreSQL, S3 и RabbitMQ находятся в Docker volumes; удаление volumes уничтожает учебные данные.
11. Короткие ответы на вопросы защиты
Что уже сохранено к моменту 202? Полный проверенный исходник в устойчивом staging, метаданные queued и намерение обработки в outbox. Варианты ещё могут быть не готовы.
Почему используется 202? HTTP-приём завершён, а фоновая обработка продолжается. Её состояние читается отдельным GET.
Почему обычная фоновая задача внутри API недостаточна? Память процесса пропадёт при его остановке. Здесь байты находятся в S3, намерение — в PostgreSQL, доставка — в устойчивой очереди.
Зачем outbox, если RabbitMQ и так надёжный? RabbitMQ не может сохранить сообщение, которое до него не успели отправить. Outbox закрывает разрыв между COMMIT PostgreSQL и отправкой брокеру.
Что будет, если worker остановлен? Новые файлы остаются queued, сообщения чата продолжают работать, content возвращает 409. После запуска worker обработает накопленную работу.
Что будет, если worker упал после записи файлов? Если ready не закоммичен, истечёт lease и будет новая попытка с теми же ключами. Если ready уже закоммичен, повторная доставка станет no-op.
Как определяется зависшая задача? По истёкшему lease_until. Предел всей попытки меньше lease, а token защищает фиксацию результата от старой попытки.
Чем retry отличается от replay? Retry выполняется автоматически по ограниченной политике. Replay запускает оператор после failed и устранения причины, с причиной в аудите.
Где видны ошибки? В API — failed и безопасный error_code; оператор видит реестр failed, история находится в job_events. Некорректные сообщения очереди попадают в DLQ.
Почему нельзя удалить staging сразу после получения задания? Worker может погибнуть до готового результата. Для восстановления всё ещё нужны исходные байты.
Что переживает перезапуск? При сохранённых volumes — данные БД, файлы S3 и очередь RabbitMQ. Потеря всего диска, удаление volumes и резервное восстановление этой лабораторной не покрываются.
Что добавлено для оценки 4? Crop и WebP, ограничения ресурсов, outbox с проверкой сбоя, backoff/jitter, различение ошибок, реестр failed и replay, lease, проверки падений и очистка staging.
12. Рассказ примерно на минуту
«В пятой лабораторной я отделила приём картинки от её обработки. API проверяет файл, сохраняет исходник в S3 staging, а одной транзакцией PostgreSQL создаёт вложение queued и запись outbox. Только после этого клиент получает 202.
Отдельный publisher отправляет задание в RabbitMQ и ждёт publisher confirm. Worker берёт задание, получает lease, проверяет исходник и создаёт thumbnail, crop и WebP в ограниченном дочернем процессе. Затем записывает файлы в S3 и фиксирует ready с метаданными. После этого отправляет consumer ack.
Outbox восстанавливает отправку после сбоя между БД и брокером. Lease восстанавливает обработку после смерти worker. Временные ошибки повторяются с backoff и jitter, постоянные завершаются failed. Есть явный replay и история действий. Доставка может повторяться, поэтому job_id, номер попытки и постоянные ключи результатов защищают от дублей. Эти ситуации проверяются отдельными тестами с остановками и аварийными выходами».