# Карта проекта для подготовки к защите Составлена по исходному коду 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/`. 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//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 `. ## Варианты изображения `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. При изменениях проверять номера строк заново.