Files
mtusi2026lab5/PROJECT_MAP.md
Savelev_Ivan fd501cbf68 fix: продление аренды задач и контроль зависшей обработки
- Добавлен heartbeat для продления lease долгих задач.
- Добавлен общий таймаут с остановкой дерева процессов.
- Сохранена защита от устаревших исполнителей.
- Добавлены тесты и обновлена документация.
2026-11-20 14:00:53 +03:00

18 KiB
Raw Permalink Blame History

Карта проекта для подготовки к защите

Составлена по исходному коду 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.

  1. scripts/start.sh:5: вызывает python3 scripts/init_local.py.
  2. scripts/init_local.py:12: создаёт отсутствующие .env и secrets, сохраняет существующие значения; генерирует конфигурацию доступа к S3.
  3. scripts/start.sh:6: docker compose up -d --build lb cleanup publisher worker. Остальные сервисы поднимаются через depends_on.
  4. compose.yaml:90: API собирается из Dockerfile, по умолчанию две реплики. PostgreSQL/сессии/миграции/S3/bootstrap перечислены в зависимостях API.
  5. compose.yaml:107 → src/migrate.py:20: отдельный migrate применяет SQL по порядку, под advisory lock, запоминает SHA-256. src/migrate.py:11: API только проверяет применённую схему.
  6. compose.yaml:144 → src/bootstrap_s3.py:13: подготовка приватного bucket.
  7. Dockerfile:28: команда контейнера API python -m src.
  8. src/__main__.py:8: Uvicorn загружает src.app:app, host/port из окружения, один процесс на контейнер.
  9. src/app.py:24: lifespan открывает пул БД и проверяет миграции; src/app.py:33 создаёт FastAPI.
  10. compose.yaml:169: HAProxy публикуется на 127.0.0.1:8080; infra/haproxy.cfg:34 — backend с roundrobin и проверкой readiness.
  11. 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.

  1. Проверка членства, имени, MIME; поток сырых PNG/JPEG, не multipart.
  2. Ограничения: до 10 MiB, до 40 млн пикселей; фактический формат, verify и полное декодирование: src/attachments.py:19, src/attachments.py:47. API проверяет изображение, но не генерирует варианты.
  3. Временный файл и SHA-256; семафор ограничивает приём/проверку одной загрузкой на API-реплику.
  4. Отдельно фиксируется attachment_uploads — журнал до S3 PUT.
  5. Под advisory lock выполняется PUT в attachments/staging/<UUID>.
  6. В одной транзакции: attachments(status=queued), attachment_jobs, attachment_outbox; удаление строки журнала.
  7. Ответ 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. При изменениях проверять номера строк заново.