- Добавлен heartbeat для продления lease долгих задач. - Добавлен общий таймаут с остановкой дерева процессов. - Сохранена защита от устаревших исполнителей. - Добавлены тесты и обновлена документация.
18 KiB
Карта проекта для подготовки к защите
Составлена по исходному коду 13.11.2026. Ссылки вида src/jobs.py:29 обозначают файл и начальную строку функции; при изменении исходников номера нужно перепроверять.
Что это
Учебный HTTP-мессенджер на Python/FastAPI. Лабораторная 5 добавляет очередь и асинхронную обработку изображений; в REPORT.md заявлена оценка 4. Возможности предыдущих работ сохранены: пользователи, сессии, чаты, сообщения, вложения, пагинация и идемпотентность сообщений.
README.md описывает исходное задание и называет репозиторий skeleton. Фактическая реализация уже есть в src/ и compose.yaml. При ответах о поведении ориентироваться прежде всего на код. Ссылки в отчёте на REPORT.lab2/3/4.md не означают, что эти файлы присутствуют в текущем дереве.
Клиент → HAProxy → FastAPI ×2 → PostgreSQL (данные, jobs, outbox)
→ Valkey (сессии)
→ SeaweedFS S3 (staging)
PostgreSQL outbox → publisher → отдельный Valkey Streams broker
↓
worker ×2 процесса
↓
subprocess Pillow → S3 результаты
↓
PostgreSQL ready → ACK
cleanup → незавершённые загрузки и ненужный staging
Как запускается проект
Команда из корня в Bash/WSL/Git Bash при доступном Docker Compose: ./scripts/start.sh.
scripts/start.sh:5: вызываетpython3 scripts/init_local.py.scripts/init_local.py:12: создаёт отсутствующие .env и secrets, сохраняет существующие значения; генерирует конфигурацию доступа к S3.scripts/start.sh:6:docker compose up -d --build lb cleanup publisher worker. Остальные сервисы поднимаются через depends_on.compose.yaml:90: API собирается из Dockerfile, по умолчанию две реплики. PostgreSQL/сессии/миграции/S3/bootstrap перечислены в зависимостях API.compose.yaml:107→src/migrate.py:20: отдельный migrate применяет SQL по порядку, под advisory lock, запоминает SHA-256.src/migrate.py:11: API только проверяет применённую схему.compose.yaml:144→src/bootstrap_s3.py:13: подготовка приватного bucket.Dockerfile:28: команда контейнера APIpython -m src.src/__main__.py:8: Uvicorn загружаетsrc.app:app, host/port из окружения, один процесс на контейнер.src/app.py:24: lifespan открывает пул БД и проверяет миграции;src/app.py:33создаёт FastAPI.compose.yaml:169: HAProxy публикуется на 127.0.0.1:8080;infra/haproxy.cfg:34— backend с roundrobin и проверкой readiness.scripts/start.sh:7→scripts/wait-ready.sh:5: ожидание стенда черезscripts/replicas.py wait.
Остановка: ./scripts/stop.sh; перезапуск: ./scripts/restart.sh. Worker: scripts/stop-worker.sh, scripts/start-worker.sh. Остановка контейнеров с сохранением volumes отличается от удаления volumes.
Общий путь HTTP-запроса
src/app.py:38: middleware создаёт request_id, определяет пользователя (Basic для входа, Bearer для остальных защищённых API), проверяет JSON, добавляет X-Request-Id и X-Instance-Id, пишет время/статус в лог.src/models.py:8: Pydantic-модели и проверки входных данных; модели пользователя/чата/сообщения начинаются со строк 21/27/40.src/app.py:77: обработчики ошибок; неверные параметры дают контрактный 400, вместо стандартного FastAPI 422.src/errors.py:7: ApiError;src/errors.py:16: общий формат HTTP-ошибки.src/db.py:28: пул соединений;src/db.py:42: контекст отдельной транзакции, COMMIT при успешном выходе, rollback при ошибке.
Регистрация, вход, сессия
- Регистрация:
src/app.py:112→src/passwords.py:12(Argon2id) →src/storage.py:35(INSERT users; занятый username — 409). - Вход: middleware
src/app.py:38→src/auth.py:44(Basic username/password) →src/app.py:180→src/auth.py:61(случайный Bearer token, запись в Valkey с TTL). - В Valkey ключ
session:SHA256(token), значение — user_id/expires_at:src/auth.py:57. Default TTL — 3600 с:src/config.py:11. - Защищённый запрос:
src/auth.py:70читает сессию, проверяет срок и существование пользователя. - Выход:
src/app.py:185→src/auth.py:85, удаление сессии. - Valkey сессий и Valkey broker — разные сервисы:
compose.yaml:38иcompose.yaml:50.
Чаты, сообщения и доступ
- Создание чата:
src/app.py:122→src/storage.py:57, чат и участники в одной транзакции. - Проверка членства:
src/storage.py:73. Для недоступного чата возвращается 404. - Создание сообщения:
src/app.py:138проверяет Idempotency-Key →src/storage.py:106проверяет доступ, вложения, сохраняет сообщение и результат повтора. - Идемпотентность сообщений: advisory lock по пользователю/пути чата/ключу, таблица message_idempotency. Тот же ключ и тело возвращают прежнее сообщение; другое тело — 409. TTL ≥24 ч:
src/config.py:18. - queued/processing можно прикреплять к сообщению; failed — 409:
src/storage.py:106. - История:
src/app.py:175→src/storage.py:144. Чаты:src/storage.py:87. - Keyset-пагинация по (created_at,id), LIMIT size+1; cursor содержит scope/дату/UUID:
src/pagination.py:12,src/pagination.py:33. Это не OFFSET и не snapshot между страницами.
Загрузка изображения и ответ 202
src/app.py:146 → src/attachments.py:99 → src/attachments.py:73.
- Проверка членства, имени, MIME; поток сырых PNG/JPEG, не multipart.
- Ограничения: до 10 MiB, до 40 млн пикселей; фактический формат, verify и полное декодирование:
src/attachments.py:19,src/attachments.py:47. API проверяет изображение, но не генерирует варианты. - Временный файл и SHA-256; семафор ограничивает приём/проверку одной загрузкой на API-реплику.
- Отдельно фиксируется attachment_uploads — журнал до S3 PUT.
- Под advisory lock выполняется PUT в
attachments/staging/<UUID>. - В одной транзакции: attachments(status=queued), attachment_jobs, attachment_outbox; удаление строки журнала.
- Ответ 202 после завершённого PUT и COMMIT. Возвращается снимок queued, даже если worker уже успел закончить.
Важная граница: 202 означает устойчивый приём и сохранённое намерение обработки; готовность проверяется отдельно. В PostgreSQL хранятся метаданные, байты — в S3. TemporaryFile не является durable staging.
Outbox и брокер
src/publisher.py:8: выбирает доступную неопубликованную запись outbox с FOR UPDATE SKIP LOCKED → XADD → published_at → COMMIT.- Сбой после COMMIT upload до публикации: запись остаётся в outbox. Сбой после XADD до COMMIT publisher: возможен повтор XADD.
src/broker.py:26: JSON содержит ID, версию, attempt, время; без байтов, паролей и клиентских путей.src/broker.py:18: XGROUP CREATE MKSTREAM с началом 0, stream attachments:v1, группа image-workers.compose.yaml:50: AOF appendfsync always, volume broker_data, noeviction.src/broker.py:33: ACK и XDEL в одной транзакции брокера; здесь только одна consumer group.
Worker, состояния, защита от дублей
src/worker.py:166: supervisor запускает до двух consumer-процессов и заменяет умершие.src/worker.py:140: XAUTOCLAIM старых pending, затем XREADGROUP новых, count=1 (prefetch=1).src/worker.py:89: валидация сообщения →src/jobs.py:29(claim).- Claim блокирует job и attachment, проверяет версию/attempt/статус, выставляет lease_token/lease_until и processing.
src/worker.py:40: читает staging, сверяет размер/SHA-256, запускает отдельный subprocess Pillow с timeout.- Перед финальными PUT повторно блокирует строки, проверяет lease_token и срок аренды. Старый исполнитель не публикует результат после потери аренды.
- Ключи детерминированы:
attachments/<UUID>/v1/{original,thumbnail,crop,optimized}. Повтор PUT пишет в те же ключи. - После записи всех объектов одна транзакция фиксирует ready, variants и audit; затем ACK.
- Дубль ready:
src/worker.py:28проверяет состав вариантов и размеры объектов, после чего ACK; обработки заново нет. - Состояния: queued → processing → ready; временная ошибка → queued; постоянная ошибка/исчерпанный бюджет → failed.
- Это at-least-once доставка и идемпотентный эффект. XADD/PUT могут повторяться; exactly-once доставки нет.
Retry, зависшие работы, replay
- Исправление 13.11.2026:
src/jobs.py:51продлевает действующий lease по токену. Consumer вызывает heartbeat каждые min(10, lease/3) секунд черезsrc/task_supervisor.py:49и выполняет работу вsrc/job_runner.py:9. - Срок аренды не ограничивает общую длительность: разрешено TIMEOUT > LEASE. Независимый JOB_TASK_TIMEOUT_SECONDS (default 180 с) останавливает всё дерево задачи при зависании; ошибка продления/потеря аренды тоже останавливает обработку. Resize timeout остаётся отдельным.
- Локальные сценарии supervisor:
student-tests/test_task_supervisor.py. Полный Docker-прогон новой версии ещё требуется; старые evidence не подтверждают heartbeat. - Defaults: 5 попыток, timeout subprocess 60 с, lease 90 с, backoff base 2 с:
src/jobs.py:8. src/jobs.py:72: exponential backoff с jitter 0.5–1.5; базовая экспонента ограничена 60 с до jitter. Постоянная ошибка сразу failed, исчерпание попыток — retry_exhausted.src/jobs.py:91: отказ записывается только при совпадении lease_token.src/jobs.py:98: publisher вызывает recover для истёкших processing; причина worker_lost, ограниченный retry.src/jobs.py:111: replay только failed с неудалённым staging; тот же job_id, attempt растёт, новый ограниченный бюджет и audit.- Реестр failed вместо отдельной DLQ:
src/job_admin.py:9. Команды:docker compose exec worker python -m src.job_admin failedиdocker compose exec worker python -m src.job_admin replay <job_id>.
Варианты изображения
src/image_pipeline.py:22: EXIF orientation, белый фон прозрачности, RGB, удаление metadata.
| Объект | Правило |
|---|---|
| original | Исходные байты без перекодирования |
| thumbnail | JPEG, вписать в 256×256, пропорции сохранены, без увеличения, quality=85 |
| crop | JPEG 128×128, центрированный crop, увеличение возможно, quality=85 |
| optimized | WebP, вписать в 1280×1280, без увеличения, quality=80, method=4 |
src/image_pipeline.py:14: размеры округляются вниз, минимум 1 px. src/image_pipeline.py:58: лимиты адресной памяти и CPU subprocess; wall timeout — src/worker.py:40.
Чтение и очистка
- Metadata:
src/app.py:151→src/attachments.py:136, доступ по членству в чате. - Content:
src/app.py:156: не-ready — 409; отсутствующий вариант ready — 404; StreamingResponse через API без redirect.src/attachments.py:145закрывает S3 response. src/object_store.py:16: приватный bucket через Minio SDK к SeaweedFS;src/object_store.py:42— PUT.src/cleanup.py:17: orphan-журнал старше grace period; та же advisory lock, активные загрузки пропускаются.src/cleanup.py:48: staging ready удаляется, failed хранится по retention (default сутки); queued/processing не удаляются. После удаления failed staging replay запрещён.
Схема, диагностика, проверки
migrations/001_initial.sql: пользователи/чаты/участники/сообщения; 002 — идемпотентность; 003 — вложения/журнал/связи; 004 — статусы/jobs/outbox/events.docs/schema.md: описание схемы и транзакционных границ.src/app.py:99: live без зависимостей;src/app.py:104: ready проверяет PostgreSQL, сессии и bucket. Broker/worker не входят в readiness API: намерение принимается через outbox при их простое.src/config.py:7: секреты читаются из файлов, заданных переменными *_FILE; значения секретов не выводить при подготовке.make check: структура/контракт без запуска приложения;make validate: OpenAPI;make test: smoke работающего API.scripts/check-docker.sh→student-tests/lab5_pipeline.py:22: полный изолированный Docker-сценарий, включая падения и восстановление.student-tests/lab5_pipeline.py: offline worker/рестарты, долгий runner с heartbeat, зависший runner с общим timeout, падение publisher/worker, retry/replay, лимиты subprocess, cleanup и offline broker. После изменений искать сценарии по комментариям и record(...).src/faults.py:9: одноразовые failpoints, включаются только ENABLE_FAULT_INJECTION=1; crash до/после публикации/эффекта/ACK, timeout/memory/transient.evidence/lab5-checks.json,evidence/lab5-checks.txt,evidence/lab5-restart.json: сохранённые результаты прошлых запусков, не подтверждение текущего живого стенда.
Формат быстрых ответов
Сначала прямой ответ на вопрос в 1–3 предложениях. Ниже короткое пояснение и 1–3 ссылки на соответствующие строки кода. Термины объяснять по необходимости. По запросу о запуске показывать цепочку start.sh → Compose → Dockerfile → __main__.py → app/lifespan. При изменениях проверять номера строк заново.