forked from mtusi2026/mtusi2026lab5
- Добавлен heartbeat для продления lease долгих задач. - Добавлен общий таймаут с остановкой дерева процессов. - Сохранена защита от устаревших исполнителей. - Добавлены тесты и обновлена документация.
155 lines
18 KiB
Markdown
155 lines
18 KiB
Markdown
# Карта проекта для подготовки к защите
|
||
|
||
Составлена по исходному коду 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. При изменениях проверять номера строк заново.
|