laba 5 mark 4
This commit is contained in:
@@ -1,8 +0,0 @@
|
||||
# Teaching outline, not a runnable Dockerfile. Implement your own Dockerfile.
|
||||
# 1. Choose a runtime/toolchain version and pin the base image tag/digest.
|
||||
# 2. Copy dependency manifests first; install from the language lockfile.
|
||||
# 3. Copy source and build. For compiled languages use a separate runtime stage.
|
||||
# 4. Run the HTTP process as PID 1; listen on 0.0.0.0:8080.
|
||||
# 5. Add non-root, signals and healthcheck according to the current rubric.
|
||||
# 6. Pass runtime config/secrets at startup, never COPY .env or secret files.
|
||||
# This file deliberately has no FROM/CMD: selecting/implementing them is the task.
|
||||
-266
@@ -1,266 +0,0 @@
|
||||
# Лабораторная 5: объяснение и подготовка к защите
|
||||
|
||||
Начни с этого файла. В [REPORT.md](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.
|
||||
|
||||
```text
|
||||
Клиент → 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 — две отдельные операции. Возможен сбой:
|
||||
|
||||
```text
|
||||
Сохранили вложение в БД → процесс упал → задание не дошло до 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](app/attachments.py) | Приём файла, staging, создание queued/outbox, чтение и скачивание |
|
||||
| [app/images.py](app/images.py) | Проверка PNG/JPEG по содержимому, целостности и числу пикселей |
|
||||
| [app/jobs.py](app/jobs.py) | `relay_one` — отправка outbox; `recover_leases` — восстановление; `cleanup_staging` — уборка |
|
||||
| [app/pipeline.py](app/pipeline.py) | Очереди, формат сообщения, confirm, backoff, `retry_or_fail`, точки сбоев |
|
||||
| [app/worker.py](app/worker.py) | `claim` — захват; `build_objects` — файлы; `finish` — фиксация; `handle` — обработка доставки и ack |
|
||||
| [app/image_worker.py](app/image_worker.py) | Thumbnail/crop/WebP, ограничения дочернего процесса |
|
||||
| [app/operator.py](app/operator.py) | Реестр failed, явный replay, тестовая повторная доставка, включение сбоев |
|
||||
| [migrations/005_async_pipeline.sql](migrations/005_async_pipeline.sql) | Поля задач, таблицы outbox, job_events и fault_injections |
|
||||
| [compose.yaml](compose.yaml) | Все сервисы, версии образов, volumes, сети и ресурсы |
|
||||
| [student-tests/lab5_recovery.py](student-tests/lab5_recovery.py) | Воспроизводимые сценарии остановок, падений, повторов и replay |
|
||||
|
||||
## 10. Как показать работу в PowerShell
|
||||
|
||||
Команды выполняются из корня проекта. Сначала запусти Docker Desktop с Linux-контейнерами.
|
||||
|
||||
```powershell
|
||||
# Первичная подготовка; существующий .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`; реальные токены не печатаются.
|
||||
|
||||
```powershell
|
||||
# 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:
|
||||
|
||||
```powershell
|
||||
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, номер попытки и постоянные ключи результатов защищают от дублей. Эти ситуации проверяются отдельными тестами с остановками и аварийными выходами».
|
||||
@@ -1,14 +0,0 @@
|
||||
# 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: 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: {}
|
||||
Reference in New Issue
Block a user