Files
mtusi2026lab5/EXPLANATION.md
T
2026-11-10 14:47:33 +03:00

31 KiB
Raw Blame History

Лабораторная 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.

  1. Клиент отправляет сырые байты в POST /api/v1/chats/{chat_id}/attachments?filename=photo.png с Bearer-токеном и Content-Type: image/png.
  2. API проверяет доступ к чату, имя, формат по содержимому, размер и целостность изображения. По ходу чтения считает SHA-256 — контрольную сумму исходных байтов.
  3. API записывает исходник в приватный раздел S3 staging/. Staging — место для надёжно принятого исходника, ожидающего обработки.
  4. В одной транзакции PostgreSQL создаются вложение со статусом queued и строка outbox с намерением отправить задание.
  5. После успешного COMMIT API отвечает 202 Accepted: «исходник принят, работа сохранена». В этом ответе status=queued, variants=[].
  6. Publisher отправляет задание в RabbitMQ и получает подтверждение от брокера.
  7. Worker захватывает задачу, ставит processing, читает staging и сверяет размер и SHA-256. Отдельный дочерний процесс создаёт варианты.
  8. Worker записывает неизменённый оригинал и варианты в конечные ключи S3. Затем одной транзакцией публикует метаданные вариантов и состояние ready в PostgreSQL.
  9. После устойчивой фиксации worker подтверждает доставку брокеру. Клиент узнаёт ready через GET метаданных и скачивает файлы через авторизованный API.
  10. 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, номер попытки и постоянные ключи результатов защищают от дублей. Эти ситуации проверяются отдельными тестами с остановками и аварийными выходами».