laba 5 mark 4

This commit is contained in:
2026-11-10 14:52:47 +03:00
parent 5ca6b6f7ad
commit fec72a0189
3 changed files with 0 additions and 288 deletions
-8
View File
@@ -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
View File
@@ -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, номер попытки и постоянные ключи результатов защищают от дублей. Эти ситуации проверяются отдельными тестами с остановками и аварийными выходами».
-14
View File
@@ -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: {}