diff --git a/Dockerfile.example b/Dockerfile.example deleted file mode 100644 index e333a12e..00000000 --- a/Dockerfile.example +++ /dev/null @@ -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. diff --git a/EXPLANATION.md b/EXPLANATION.md deleted file mode 100644 index 3406d32f..00000000 --- a/EXPLANATION.md +++ /dev/null @@ -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, номер попытки и постоянные ключи результатов защищают от дублей. Эти ситуации проверяются отдельными тестами с остановками и аварийными выходами». diff --git a/compose.example.yaml b/compose.example.yaml deleted file mode 100644 index 792b3f4e..00000000 --- a/compose.example.yaml +++ /dev/null @@ -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: {}