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

155 lines
18 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Карта проекта для подготовки к защите
Составлена по исходному коду 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 не означают, что эти файлы присутствуют в текущем дереве.
```text
Клиент → 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. При изменениях проверять номера строк заново.