diff --git a/.claude/rules/api-contract.md b/.claude/rules/api-contract.md index 2b37ffb2..736aa65e 100644 --- a/.claude/rules/api-contract.md +++ b/.claude/rules/api-contract.md @@ -266,14 +266,18 @@ ACTION_SCRIPT=scripts/restart.sh` (`tests/README.md`), hook — `attachments`; устройство — design change `attachments`. - Ручки: `POST /api/v1/chats/{chat_id}/attachments?filename=…` — сырые - байты одного PNG/JPEG (не multipart, не JSON), `201 Attachment` со - `status=ready`, `variants=[]`, `error_code=null` только после записи - объекта в S3 и `ready` в PostgreSQL; `GET /api/v1/attachments/{id}` — - метаданные, равные ответу загрузки; `GET …/{id}/content` — байты - оригинала потоком, `Content-Type` вложения без параметров, - `Content-Length`, `X-Content-Type-Options: nosniff`, без redirect. - `variant` — только `original` (иное — 400). Ключ объекта, адрес и - ключи S3 в ответ не попадают. + байты одного PNG/JPEG (не multipart, не JSON), с лабы 5 — `202 Attachment` + со снимком `status=queued`, `variants=[]`, `error_code=null` только после + записи объекта в staging, `queued` с заданием в PostgreSQL и подтверждения + брокера; брокер не подтвердил — 503 (design change `async-attachments`, + решение 3); `GET /api/v1/attachments/{id}` — метаданные: `queued`, + `processing`, `ready`, `failed` — 200, у `ready` есть `variants`, у `failed` + — `error_code` (`invalid_image`, `processing_failed`, `retry_exhausted`); + `GET …/{id}/content` — байты оригинала или варианта потоком, `Content-Type` + без параметров, `Content-Length`, `X-Content-Type-Options: nosniff`, без + redirect. `variant` — `original`, `thumbnail`, `crop`, `optimized` (иное — + 400). Не `ready` — 409 `conflict` на любой `variant`; варианта нет — 404. + Ключ объекта, адрес и ключи S3 в ответ не попадают. - Доступ — любой участник чата вложения. Посторонний, неизвестный id и вложение в статусе `pending` — одинаковый 404 «Not found». - Порядок проверок загрузки: 401 → 400 (`chat_id`, `filename`, их @@ -320,9 +324,11 @@ ACTION_SCRIPT=scripts/restart.sh` (`tests/README.md`), hook — байт вне ASCII — `InvalidFilename` (400) до проверки членства. - `attachment_id` в пути и элементы `attachment_ids` в теле — `UuidIn` (раздел «Валидация → 400»). `attachment_ids`: 0–10, без повторов (и в - другом регистре), иначе 400; каждое — готовое вложение этого чата, - иначе 404 до захвата ключа идемпотентности. Ответы — id в нижнем - регистре, в порядке отправки. + другом регистре), иначе 400; каждое — принятое вложение этого чата + (`queued`, `processing`, `ready`), иначе 404 до захвата ключа + идемпотентности; `failed` — 409 после захвата, с откатом, а повтор уже + отправленного сообщения с тем же ключом — тот же 201 (вопрос преподавателю, + `QUESTIONS.md`). Ответы — id в нижнем регистре, в порядке отправки. - Текст сообщения: до 4000 code points; пустой текст — `""` или строка из одних пробельных символов — допустим только с хотя бы одним вложением, без вложений 400. Сохраняется как прислан, без обрезки @@ -348,4 +354,5 @@ ACTION_SCRIPT=scripts/restart.sh` (`tests/README.md`), hook — `test_reconcile_finds_and_fixes`. - Отказ S3 — 503 только на загрузке и скачивании байтов. Метаданные, сообщения (в том числе со ссылкой на готовое вложение), история и - `/health/ready` работают без S3. + `/health/ready` работают без S3. Отказ брокера — 503 только на загрузке, + остальное API и готовность работают; worker в готовность не входит. diff --git a/.claude/rules/api-layer.md b/.claude/rules/api-layer.md index 7d3622d9..e6646994 100644 --- a/.claude/rules/api-layer.md +++ b/.claude/rules/api-layer.md @@ -83,9 +83,10 @@ FastAPI, один процесс на реплику; реплик ≥2 за HAP `Content-Length`, `X-Content-Type-Options: nosniff`; генератор сам закрывает объект в `finally`, тот же закрыватель — фоновой задачей ответа на случай, если генератор не начался; - - `variant` — `Literal["original"]` с `Query(json_schema_extra={"enum": - ["original"]})`: Literal из одного значения pydantic пишет как - `const`, а контракт — `enum`. + - `variant` — `Literal` четырёх значений контракта, по умолчанию + `original`; в сервис — `AttachmentVariantName` или `None` (оригинал); + - загрузка — `status_code=202`, а не 201: приём, а не создание готового + объекта. JSON-ручки по-прежнему на `get_db_session`. - Ошибки — доменные исключения из сервиса. `HTTPException` не бросать. Статус, `code` и заголовки ответа (`WWW-Authenticate` у 401) diff --git a/.claude/rules/balancer.md b/.claude/rules/balancer.md index e8a3dc4b..478a45d8 100644 --- a/.claude/rules/balancer.md +++ b/.claude/rules/balancer.md @@ -150,13 +150,15 @@ paths: api`. Больше самого долгого молчания живой загрузки: до тела `2 × request_timeout_seconds + [uploads] wait_timeout_seconds` = 17 с (вход, членство, ожидание места), после тела — проверка (до ~4 с) + - tx1 6 + PUT 5 + tx2 6 + компенсация 5 ≈ 26 с. Тело ограничивают + tx1 6 + PUT 5 + tx2 6 + публикация 2 + отметка или отмена 6 ≈ 29 с (change + `async-attachments`, решение 3; ветка компенсации после неудачной tx2 — + прежние 26 с). Тело ограничивают `[uploads] body_timeout_seconds` (30 с) и `timeout client` (30 с). Остальные пути — прежние 10 с: общий 30 с держал бы любой запрос к зависшей реплике 30 с до 504, а замеры `failover` рассчитаны на 10. Выражение повторяет путь ручки в `src/api/routers/v1/attachment.py`: при смене префикса API менять вместе. Наибольшая длительность загрузки - U = 17 + 30 + 26 ≈ 73 с < `ROLLOUT_DRAIN_TIMEOUT` 90 с; + U = 17 + 30 + 29 ≈ 76 с < `ROLLOUT_DRAIN_TIMEOUT` 90 с; `graceful_shutdown_seconds` прежний (8 с): `stop-one.sh` и `docker stop` — отказ, загрузка дольше 8 с обрывается, строку `pending` убирает уборщик. Проверка поведения — `driver.py lb-upload-timeouts`: @@ -292,7 +294,7 @@ Compose не умеет rolling update сам (это `update_config` Swarm). Ц 5. Вывод старой из LB через runtime API (ниже): `drain` → запросов в полёте (`scur`) 0, не дольше `ROLLOUT_DRAIN_TIMEOUT` 90 с (с change `upload-memory`; больше `timeout server` пути загрузки 30 с и - наибольшей длительности загрузки ≈ 73 с, иначе замена обрывала бы + наибольшей длительности загрузки ≈ 76 с, иначе замена обрывала бы живую загрузку; обычно дренаж — 0–2 с) → `maint` → `docker stop --timeout 10` (в строке скрипта — время и код выхода: 0 — graceful, 137 — SIGKILL по сроку) → `docker @@ -393,6 +395,15 @@ change: прежние реплики колонку не читают (у по `AccessDenied` на списке — проход сверки прерван, уборка работает; новый уборщик на прежней схеме — «Reconcile pass failed», процесс живёт. +**Порядок обновления с брокером** (design change `async-attachments`, решение +14): вперёд — `docker compose up -d --wait rabbitmq`, `docker compose up -d +s3-bootstrap`, `make rolling_update`, `docker compose up -d --no-deps cleaner +worker`. Смесь версий: прежняя реплика загружает по-старому (201, `ready`, +конечный ключ) и даёт 500 на чтении строки нового статуса, новая читает её строку +как `ready` без вариантов; переход 201 → 202 всё равно несовместим для клиента на +время замены — названо в `REPORT.md`. Откат — `make rolling_update COMMIT=<прежний> +MIGRATE=0`, `docker compose stop worker`, прежний образ уборщика. + **Bootstrap S3 скрипт не запускает** (design change `s3-storage`, решение 9): новая реплика поднимается с `--no-deps`. Bootstrap, как миграции, только расширяет: новые пользователи и политики не отбирают diff --git a/.claude/rules/bench.md b/.claude/rules/bench.md index 6c43360a..36304200 100644 --- a/.claude/rules/bench.md +++ b/.claude/rules/bench.md @@ -327,15 +327,22 @@ change `s3-storage`, решение 9): старт стенда перечисл Спек `load-benchmark`, «Профиль загрузок»; design change `upload-memory`, решение 10. Методика — поля `Profile` (`uploads_*`) в `run.py`, разбор без -docker — `bench/uploads.py` (`--selftest`). +docker — `bench/uploads.py` (`--selftest`). С лабы 5 (design change +`async-attachments`, решение 16) брокер запускает только этот профиль, на прогон — +новый volume брокера, worker описан и не запускается; успех — 201 или 202 по +варианту: столбец `s201` не переименован, код называет `success_code` в конце +`runs.csv` и раздел `uploads` паспорта. - **Стенд:** LB, одна реплика API 1 CPU / 512 МБ без swap (OOM-kill виден, а не прячется в swap), PostgreSQL, Valkey, S3 и `s3-bootstrap` - (раздел выше); k6 без лимита. -- **Варианты:** «до» — образ `Profile.uploads_before` (`f894040`, - последний до change `upload-memory`; `git archive` → тег `bench-from`, - проверка commit до стенда — код 2, как у `rollout_from`, смена при - переходе в лабу 5 — так же); «без лимита» — образ checkout с + (раздел выше), брокер рабочего стенда (`BENCH_BROKER_*`, 1 CPU / 512 МБ, + swap = память, `rabbitmq.conf` основного файла; образ — `stand.rabbitmq`, + лимиты — `limits.rabbitmq`); k6 без лимита. +- **Варианты:** «до» — образ `Profile.uploads_before` (`04f8592`, commit + переноса лабы 4: код лабы 4 с местами загрузок, успех 201; прежнего кода + `f894040` в истории лабы 5 нет, поэтому H2 про «до» старой метки здесь не + воспроизводится; `git archive` → тег `bench-from`, + проверка commit до стенда — код 2, как у `rollout_from`); «без лимита» — образ checkout с `UPLOADS__MAX_CONCURRENT=1000`, `UPLOADS__MAX_WAITING=0`; «с лимитом» — образ checkout со значениями по умолчанию. Окружение варианта задаёт override `.work/variant.compose.yml`, а не `BENCH_*`: иначе изменился @@ -346,8 +353,8 @@ docker — `bench/uploads.py` (`--selftest`). 10 485 760; размеры и SHA-256 — в паспорте. Тело 10 MiB у `uploads` и `uploads_quick` побайтно одно. - **Прогон:** вариант × размер × C ∈ {1, 10, 20, 40} × повтор (3), круги - с перестановкой по зерну. Перед каждым — новый volume S3 с bootstrap, - новая реплика с окружением варианта, ожидание процесса и `UP` в LB, + с перестановкой по зерну. Перед каждым — новые volume S3 с bootstrap и + брокера (`kill`, очередь не копится), новая реплика с окружением варианта, ожидание процесса и `UP` в LB, одна разогревающая загрузка. PostgreSQL, пользователь и чат — один раз на метку. Окно — `constant-vus` k6 (`k6/uploads.js`): C VU, 3 с разгона и 20 с окна без пауз; на 429 — пауза `Retry-After`, на прочие @@ -360,14 +367,14 @@ docker — `bench/uploads.py` (`--selftest`). t0 + 23)`, ответы по кодам — за весь прогон, в том числе после OOM. - **Пометки:** `oom` (реплика завершена ядром — результат варианта, не сбой команды; следующий прогон на новой реплике), `host_swap`, - `peak_sampled`, `s3_down`. Блокировка `bench/.bench.lock`, отказ + `peak_sampled`, `s3_down`, `broker_down`. Блокировка `bench/.bench.lock`, отказ занятой метки и остатков стенда — как у остальных профилей. - **Результаты:** `evidence/uploads/<метка>/` — `meta.json` (раздел `uploads`: commit «до», образы, тела, план, `app_env`), `runs.csv` (строка на прогон: вариант, размер, C, повтор, память до окна, пик окна, пик старта, наибольшие `anon` и `sock`, `oom_kill`, код выхода и - `OOMKilled`, ответы по кодам, загрузок 201/с, p50/p95/p99, пики S3 и - LB, пометки), `summary.md` (медиана и min–max по ячейкам, сценарии + `OOMKilled`, ответы по кодам, успешных загрузок/с, p50/p95/p99, пики S3 + и LB, пометки, код успеха; прочий 201 или 202 — `s_other`), `summary.md` (медиана и min–max по ячейкам, сценарии спеков — с ростом на клиента и итогом «Буферы соединений ограничены» по сумме роста LB и `sock` реплики от C = 1 до 40, H1–H4 с итогом только по ячейкам гипотез; у метки `baseline` этих строк ещё нет — @@ -404,10 +411,12 @@ design change `track2-reconcile-cost`, решения 1–3, 7–13. Метод на вызов), затем `docker wait`, журнал, `docker inspect` и `docker rm` при любом исходе. Вариант «до» — тот же вызов с override `.work/cleaner-before.compose.yml` (`image: mtusi-messenger:bench-from`, - `Profile.reconcile_before` — `7f4e626`, последний commit до change; + `Profile.reconcile_before` — `04f8592`, commit переноса лабы 4: прежнего + `7f4e626` в истории нет, ранний отказ по пределу в «до» уже есть, поэтому + S4 ждёт у обеих ячеек одно число находок, а вердикт S4 «до и после» + ничего не показывает — метка лабы 4 осталась в её отчёте; `git archive` → тег `bench-from`, проверка commit до стенда — код 2, как - у `rollout_from`; смена при переходе в лабу 5 — так же). Тег стенда не - меняется. + у `rollout_from`). Тег стенда не меняется. - **Этапы полной метки:** A — свежий стенд, 1 000 × 1 MiB, `batch`, `deep`, `deep-fast`; B — свежий, 10 000 × 4 KiB, `batch`, `head`, `deep`; C — тот же, +20 000, `batch`, `head`; D — тот же, +70 000, diff --git a/.claude/rules/docker.md b/.claude/rules/docker.md index 8c19be47..2d294165 100644 --- a/.claude/rules/docker.md +++ b/.claude/rules/docker.md @@ -347,6 +347,31 @@ git ls-files -z -co --exclude-standard | tar --null -T - -cf - | docker build -t на образе API в `docker-compose.yml` — строка и в override, иначе job упадёт на `bind source path does not exist` или возьмёт чужой образ. +## Брокер и worker (с лабы 5) + +Design change `async-attachments`, решения 4, 6, 12, 14. + +- **`rabbitmq`** — `rabbitmq:4.3.7@sha256:bd88…` (индекс), `hostname: rabbitmq`: + имя узла задаёт каталог данных, без него `up --force-recreate` теряет очередь. + Volume `rabbitmq_data:/var/lib/rabbitmq`, `RABBITMQ_NODE_PORT`, порт только AMQP + на `127.0.0.1:${RABBITMQ_OUT_PORT}`, алиас, healthcheck + `check_port_connectivity`, `stop_grace_period: 20s` (на деле ~2 с), лимиты 1 CPU / + 512 МБ. **`vm_memory_high_watermark.absolute = 400MiB`** в + `infra/rabbitmq/rabbitmq.conf` (`conf.d`, read-only): лимит cgroup брокер не видит + (проба: 4760 МиБ), и его убило бы ядро. Неверная настройка этого файла — отказ + старта, проверять запуском. Без management-плагина: состояние — `rabbitmqctl`. +- **`worker`** — образ API, `entrypoint: ["python", "-m", "src.worker"]`, + `restart: unless-stopped`, без портов, `healthcheck: disable: true`, окружение + `<<: [*db-env, *s3-env, *broker-env]`, `DATABASE__POOL_SIZE: "2"`, ключи + `S3_WORKER_*`; `depends_on` PostgreSQL и брокер healthy, `migrate` и + `s3-bootstrap` completed; `stop_grace_period: 10s`, лимиты 1 CPU / 1 ГБ. +- **Секреты:** пароль брокера — только `rabbitmq`, `api`, `worker`; ключи worker — + только `s3-bootstrap` и `worker`. Пользователь S3 `worker`, политика + `worker-objects`: `s3:GetObject`, `s3:PutObject` на `/*` — без удаления и + списка; `check` печатает строки «worker key …». +- **`restart.sh`** перезапускает и брокер; worker и уборщика не трогает: защита + вызывает hook при остановленном worker, и он останется остановленным. + ## Обновление кода на стенде - `make run_docker` после пересборки пересоздаёт реплики, образ которых diff --git a/.claude/rules/dto.md b/.claude/rules/dto.md index bf2d7cf9..223a54ed 100644 --- a/.claude/rules/dto.md +++ b/.claude/rules/dto.md @@ -5,6 +5,15 @@ paths: # DTO и enum-ы (`src/schemas/`) +Обработка вложений (design change `async-attachments`, решения 1–3): +`AttachmentFullDTO` — ещё `staging_key`, `error_code` и `variants` кортежем +(не колонка: подставляет сервис); `AttachmentInListDTO.staging_key`; +`AttachmentJobDTO`, `AttachmentVariantDTO`; enum `AttachmentJobState`, +`AttachmentVariantName`, `AttachmentErrorCode`, `AttachmentJobReason`, +`JobOutcome`. Сообщение брокера — pydantic-модель +`src/schemas/jobs/attachment.py`, а не DTO: оно приходит извне и разбирается по +`contracts/jobs.schema.json`. + `src/schemas/dataclasses/.py` — DTO между repo → service → api; `src/schemas/enums/.py` — `StrEnum` доменов. HTTP-модели (pydantic) лежат не здесь, а в `src/api/schemas/` (`api-layer.md`). diff --git a/.claude/rules/infra.md b/.claude/rules/infra.md index 0d59e429..f2296728 100644 --- a/.claude/rules/infra.md +++ b/.claude/rules/infra.md @@ -5,6 +5,23 @@ paths: # Инфраструктура (`src/infra/`) +Брокер (`broker/`, с лабы 5, design change `async-attachments`, решение 5): +`client.py` — `JobPublisher`, `JobConsumer`, `JobDelivery`, `queue_name`; +`instance.py` — глобал издателя процесса API (импортируют только `main.py` и +`dependencies.py`). aio-pika без `connect_robust`: фоновый reconnect скрыл бы, +что исход публикации неизвестен. Издатель открывает соединение первым вызовом, +всё — под `[broker] publish_timeout_seconds`, `publisher_confirms=True`, +`mandatory`, `on_return_raises=True`, очередь объявляется при каждом соединении. +Любая ошибка — сброс соединения (`is_closed` соединения не верить: канал закрыт при +«живом» соединении), закрытие в фоне (при заморозке оно само зависло бы), +`warning` «Broker is unavailable», `BrokerUnavailable`; повторов нет. Закрытый +канал (`is_closed` канала) перед публикацией — брокер перезапускался, пока +загрузок не было: в него ничего не ушло, поэтому это новое соединение, а не повтор. +Иначе первая загрузка на каждой реплике после возврата брокера получала 503. +Потребитель +— своё соединение: блокировка публикации не должна останавливать ack. Строка URL +с паролем не собирается, `aio_pika` и `aiormq` на `WARNING`. + Всё, что не содержит бизнес-логики и может смениться от лабы к лабе: логгер, PostgreSQL (`db/`), кэш Valkey (`cache/`), S3 (`s3/`), дальше — брокер, телеметрия. Бизнес-правил (уникальность, доступ, валидация) здесь нет: diff --git a/.claude/rules/logging.md b/.claude/rules/logging.md index d226fa92..ea4ed837 100644 --- a/.claude/rules/logging.md +++ b/.claude/rules/logging.md @@ -112,6 +112,24 @@ paths: оператор, и она выполнена верно (design change `fix-known-issues`, решение 5). +## Журнал worker и брокера (с лабы 5) + +Спек `service-logging`, «Журнал worker»; design change `async-attachments`, +решение 18. Модуль `attachment_processing_service`, `request_id` — `job_id`: +`info` «Started job attempt», «Attachment became ready» (`variant_width`, +`variant_height`, `variant_size_bytes`, `duration_ms`), «Skipped job message» +(`reason`: `finished`, `unknown`, `busy`); `warning` «Retrying job» (`reason`, +`delay_seconds`), «Attachment failed» (`error_code`, `reason`), «Job waits for +database»; `error` «Dropped malformed job message» — без содержимого, «Job attempt +failed» с traceback. Модуль `worker`: «Started worker» со всеми значениями, +«Stopped worker» с `exit_code`, «Invalid worker settings» мимо structlog, «Stopped +worker before startup». Модуль `broker`: `warning` «Broker is unavailable», +`info` «Broker is available again», `debug` на публикацию; API: «Uploaded attachment» +— ещё `job_id`, `warning` «Attachment job was not published» (`outcome`: +`cancelled`, `taken`), «Attachment job publish mark failed». «Started API» — ещё +`broker_host`, `broker_port`, `broker_queue`, `broker_publish_timeout_seconds`. +Пароля брокера и тел сообщений в записях нет. + ## Чего в логах быть не должно Рубрика уровня 4: логи полезные, но **без содержимого сообщений**. diff --git a/.claude/rules/migrations.md b/.claude/rules/migrations.md index 821028de..d0374340 100644 --- a/.claude/rules/migrations.md +++ b/.claude/rules/migrations.md @@ -91,6 +91,15 @@ paths: скан под блокировкой), пометку ставит только условный `UPDATE`. Прежние реплики колонку не читают и не пишут. Проверено на временной базе: с нуля, повтор, `downgrade -1`, снова `upgrade`, `--sql`; + - Ревизия `a1d4c7e90b23` (лаба 5, design change `async-attachments`, решение + 1): `attachments.staging_key`, `error_code` (NULL), таблицы `attachment_jobs` + (FK без каскада, UNIQUE вложение + версия, CHECK состояния и попыток) и + `attachment_variants` (PK — ключ эффекта, UNIQUE `object_key`, CHECK). + Статус — ослабление: `DROP` и `ADD CHECK … NOT VALID` в той же транзакции, как + `ck_messages_text_length`; новый `ck_attachments_error_code_failed` тоже `NOT + VALID`: прежние строки условию отвечают. Первой строкой `SET LOCAL lock_timeout + = '2s'`; `downgrade` — зеркально. Прежний образ на новой схеме работает, но + падает 500 на чтении строки нового статуса: ограничение в `REPORT.md`. - **INVALID-индекс.** Прерванная `CREATE INDEX CONCURRENTLY` (сбой, `lock_timeout`, Ctrl+C) оставляет индекс с `pg_index.indisvalid = false`, и `IF NOT EXISTS` его не пересоздаст: повтор миграции diff --git a/.claude/rules/repo-layer.md b/.claude/rules/repo-layer.md index f4c8ecfc..52bbee18 100644 --- a/.claude/rules/repo-layer.md +++ b/.claude/rules/repo-layer.md @@ -51,9 +51,18 @@ paths: сервисе. Ключ в исключения и логи не попадает. - Repo вложений (лаба 4, design change `attachments`, решения 3, 4, 8): - `attachment.py`: `insert_attachment` (`created_at` и `updated_at` - одним значением), `mark_ready` (`UPDATE … WHERE status = 'pending' + одним значением), `mark_queued` (`UPDATE … WHERE status = 'pending' AND updated_at = created_at RETURNING`, `None` — строки `pending` нет - или уборщик пометил её к уборке), + или уборщик пометил её к уборке), с лабы 5 (design change + `async-attachments`, решения 1–3) `return_to_pending`, `mark_processing`, + `return_to_queued`, `commit_ready`, `commit_failed` — условные `UPDATE`, + `updated_at` через `greatest`: часы процессов расходятся, а CHECK + `updated_at >= created_at` падал бы; + `attachment_job.py` (`insert_job`, `lock_job` — `FOR UPDATE`, `get_job`, + `get_attachment_job`, `start_attempt`, `return_to_queued` с условием своей + попытки, `finish_job`, `mark_published`, `delete_unstarted`) и + `attachment_variant.py` (`insert_variant` — `ON CONFLICT DO NOTHING`, + `get_variants`, `get_variant`); `get_attachment`, `get_attachments` (до 10 строк по первичному ключу). Значения `content_type` и `status` — `.value` enum на записи и enum в DTO на чтении. Для уборщика (design change diff --git a/.claude/rules/run-modes.md b/.claude/rules/run-modes.md index 404b8a86..c58a7a2e 100644 --- a/.claude/rules/run-modes.md +++ b/.claude/rules/run-modes.md @@ -158,6 +158,17 @@ access_log=False)`. Импорты в `src/__main__.py` — внутри `if __n `docker compose run --rm --no-deps cleaner --once`. Цели Makefile нет: образ для него собирает `make run_docker`. +## Worker (с лабы 5) + +`python -m src.worker` → `src/worker/__main__.py` → `early_stop.install("worker")` +→ `main()` (`worker.md`), в compose — сервис `worker`, PID 1. SIGTERM: новые +сообщения не берутся, начатые ждут ≤ `[worker] graceful_shutdown_seconds`, +остальные отменяются, «Stopped worker», код 0, `os._exit`: поток декодирования не +отменить. Сигнал на старте — «Stopped worker before startup». Неверные настройки — +код 2. Отказ брокера, S3, PostgreSQL процесс не роняет. Консоль — `make run_dev` +(поднимает и брокер) плюс `make run_worker` в другом терминале: тот же `.env`, +ключи worker в окружении процесса. + ## Makefile - Цели skeleton `help`, `check`, `validate`, `test`, `load`, diff --git a/.claude/rules/service-layer.md b/.claude/rules/service-layer.md index 80d75f39..ad7a1b03 100644 --- a/.claude/rules/service-layer.md +++ b/.claude/rules/service-layer.md @@ -84,10 +84,19 @@ paths: body_timeout_seconds)` (истёк — `UploadTimedOut`, 400) → структура изображения и SHA-256 одним `anyio.to_thread.run_sync` над `buffer.getvalue()` → `size = len(data)`, `del data` → строка - `pending` с `object_key` (commit) → `buffer.seek(0)`, PUT этим же - `BytesIO` (`attachment_object_repo.put_original(..., body=buffer, - size=size)`) → `_mark_ready` (commit) → DTO; место освобождается при - выходе из контекста, в том числе после компенсации и при отмене. + `pending` с `object_key` и `staging_key` (commit) → `buffer.seek(0)`, + PUT этим же `BytesIO` в staging (`attachment_object_repo.put_original(..., + body=buffer, size=size)`), `buffer.close()` → `_mark_queued`: `queued` и + задание одной транзакцией → `_publish_job`: публикация с подтверждением + (`JobPublisher`), отметка `published_at` (сбой — `warning`, ответ 202) → + снимок DTO; место освобождается при выходе из контекста, в том числе + после компенсации и при отмене. С лабы 5 (design change + `async-attachments`, решение 3) брокер не подтвердил (любой исход: + исход по сроку неизвестен) — условная транзакция `_cancel_job`: + `delete_unstarted` (0 строк — worker взял, сообщение дошло, 202) → + `return_to_pending` (объект и строку убирает уборщик) → 503. Падение + процесса между COMMIT и подтверждением оставляет `queued` без сообщения: + разрыв закрывает `pipeline-reliability`. Worker — `worker.md`. Отказ S3 или БД после `pending` — 503, строка остаётся до уборщика. Отклонённая до `pending` загрузка ничего не пишет (design change `upload-memory`, решения 1–5); @@ -100,12 +109,12 @@ paths: граница живой загрузки уборщика (B = 17 с) от очереди и медленного клиента не растёт (`settings.md`, «Уборщик»); - компенсация (design change `upload-consistency`, решение 1) — только - удаление объекта и только при известном исходе, в `_mark_ready`: + удаление объекта staging и только при известном исходе, в `_mark_queued`: флаг «COMMIT отправлен» ставится прямо перед `commit()` и только при найденной строке. Сбой до него (сам `UPDATE`, пул, срок) — объект удаляется до ответа (`_compensate`: `delete_original` без повторов, неудача — `warning`, исходная ошибка уходит дальше); сбой на - `commit()` — исход неизвестен, объект не трогается. `mark_ready` → + `commit()` — исход неизвестен, объект не трогается. `mark_queued` → `None` (строку убрал или пометил к уборке уборщик) — `error`, удаление объекта, 503 `ServiceUnavailable`. После неудачного PUT компенсации нет, строку @@ -123,7 +132,9 @@ paths: `delete_original` → `delete_attachment` → commit; строки нет или она занята — пропуск. - Помеченную строку `mark_ready` в `ready` не переводит (`updated_at = + Шаг 2 удаляет `staging_key or object_key`: строка прежней версии — + конечный объект, новая — staging. Помеченную строку `mark_queued` в + `queued` не переводит (`updated_at = created_at`), поэтому сбой после удаления объекта (откат шага 2, DELETE, который S3 выполнил после срока) не даёт `ready` без объекта. Не одна транзакция на строку: её откат после удачного @@ -140,7 +151,10 @@ paths: `stop_requested()` проверяется перед строкой и между шагами. Итог — `CleanupPassDTO`; - чтение: `pending`, нет строки, не участник — одно - `AttachmentNotFound`; скачивание — `open_original` вне транзакции, + `AttachmentNotFound`; варианты подставляются только у `ready`; + скачивание любого `variant` не `ready` вложения — `AttachmentNotReady` + (409) без обращения к S3; нет варианта — 404, нет его объекта или другой + размер — 500; оригинал — `open_original` вне транзакции, нет объекта или другой размер — `error` в журнале и `AttachmentContentMissing` (500), строка не меняется. Оригинал, который сверка уже пометила потерянным (`lost_at`, design change @@ -234,10 +248,17 @@ paths: `AttachmentCleanupService`; длительность шагов — `_Pass.phase` (`list`, `rows`, `stale`, `recheck`, `act`). Плановая сверка — `batch`, без `deep`, предел из настроек (`src/cleaner/main.py`); + - сверка (с лабы 5, решение 11): объект варианта + (`parse_variant_key`) — строка `id` есть, пропуск; нет — объект без + метаданных (удаление с `--apply`), свежий — свежий. Staging вне префикса + списка, `processing` и `failed` не находки, зависшая загрузка называет ключ + staging; - `MessageService.send_message(..., attachment_ids)`: членство → - `get_attachments` (все найдены, чат этого сообщения, `ready`; иначе - `AttachmentNotFound` до захвата ключа) → хэш → ключ → сообщение → - `insert_message_attachments` (если список непустой) → один commit; + `get_attachments` (все найдены, чат этого сообщения, не `pending`; иначе + `AttachmentNotFound` до захвата ключа) → хэш → ключ → новый ключ при + `failed` среди вложений: откат и `AttachmentFailed` (409), ключ свободен; + занятый — прежняя ветка повтора, на состояние вложения не глядя → сообщение + → `insert_message_attachments` (если список непустой) → один commit; - хэш: `message_request_hash(text, attachment_ids)` — `attachment_ids` в каноническом JSON только непустым, id — `str(UUID)` (нижний регистр), порядок значим. Пустой список хэш версии `e1161f7` не diff --git a/.claude/rules/settings.md b/.claude/rules/settings.md index b246d25c..285c4d42 100644 --- a/.claude/rules/settings.md +++ b/.claude/rules/settings.md @@ -208,6 +208,21 @@ API» называет все четыре. проверка идут до `created_at` строки `pending`, а сроки tx1, PUT и tx2 не менялись. Поэтому `[uploads]` в проверку grace уборщика не входит. +### Брокер и worker (с лабы 5) + +`[broker]` (класс `Broker`, design change `async-attachments`, решение 13): +`host`, `port`, `user`, `password` (`SecretStr`) — мосты из `RABBITMQ_*` в `.env`, +в docker — `x-broker-env`; `connect_timeout_seconds` (2), +`publish_timeout_seconds` (2; при смене пересчитать цепочку LB: после тела 29 с +< `timeout server` 30 с). `[worker]` (класс `Worker`): `concurrency` (2), `max_attempts` +(5), `job_timeout_seconds` (60), `retry_delay_seconds` (10), +`graceful_shutdown_seconds` (8, ≤ 9), `reconnect_seconds` (2). Подмена — `BROKER__*`, +`WORKER__*`. Ключи worker `S3_WORKER_*` — в `.env`, контейнеру — `environment` +compose, консоль — `make run_worker` (мост `S3__*` в `.env` — ключи API). Имена +skeleton: `BROKER_URL_FILE` → мосты `RABBITMQ_*`; `WORKER_CONCURRENCY`, +`JOB_MAX_ATTEMPTS`, `JOB_TIMEOUT_SECONDS` → поля `[worker]`; +`STAGING_RETENTION_SECONDS` — поля пока нет, появится с очисткой staging. + ### Уборщик (с лабы 4) `[cleaner]` (класс `Cleaner`, design change `upload-consistency`, diff --git a/.claude/rules/student-tests.md b/.claude/rules/student-tests.md index 9bb2eff2..6311fd8b 100644 --- a/.claude/rules/student-tests.md +++ b/.claude/rules/student-tests.md @@ -91,8 +91,8 @@ paths: заголовок скана, пустой скан, 27 байт из замечания ревьюера — `test_undecodable_jpeg`, красный на `e30b649`), обрезка и хвост. Большие файлы и «бомбы» живут в памяти теста, в git - не попадают. Pillow — только dev-группа (`uv add --dev pillow`): в - образе (`uv sync --no-dev`) и в `src` его нет; + не попадают. С лабы 5 Pillow — основная зависимость worker; в тестах он + генератор и проверка пикселей; - `api_client.py`: `post_attachment` (байты или итератор — частями, без `Content-Length`; `None` — без заголовка или параметра), `upload` (201 и проверка размера, SHA-256, `owner_id`, `filename`), @@ -347,6 +347,30 @@ paths: test-persistence` (с `LAB=4` публичная проверка скачивает оригинал после hook) → `evidence/replicas/test-persistence.md`. +Лаба 5 добавляет (design change `async-attachments`, решение 15): + +- `api_client.py`: `upload` — 202 и снимок `queued` (`assert_accepted`), + `wait_attachment(actor, id, status=…, timeout=60)` — опрос раз в 0,2 с, + падение с последним состоянием, `upload_ready` — загрузка и ожидание. + Тест, которому нужны байты, ждёт `ready`, а не считает его готовым после 202; + форма ответа 202 проверяется до ожидания. `contract.py`: + `assert_variant_content` (заголовки, размер и SHA-256 варианта). `images.py`: + `jpeg_precision_12`, `jpeg_halves(orientation)`, `png_half_transparent`, + `png_palette_transparent`, `png_rgba_large`; +- `test_attachment_processing.py` — thumbnail, варианты, `failed` по HTTP на + любом стенде с worker; +- hook — ещё действия брокера и worker, `worker-state`, `queue-state`, + `peek-job`, `publish-job`, `delete-queue`, `job`, `staging-ids`, + `variant-object-count`, режимы `fail-attachments` на `queued`, а `ready-fail`, + `ready-stall` — на фиксацию worker; ключи и пароль брокера hook не получает: + `peek-job` и `publish-job` — Python в контейнере API его настройками; +- стенд отказов: `rabbitmq` без порта, worker с `restart: "no"`, 4 попытки, + пауза 5 с, срок 10 с, graceful 2 с (`FAULT_WORKER_*`), журнал worker при + падении; `make test_isolated` — ещё контейнер `<проект>-test-worker` и уборка + очереди `test_.attachment.process.v1`. Полный прогон — 99 проверок, pytest + ~1300 с, вся команда ~22 мин. Описание лабы 4 выше — история: `upload` там + отвечал 201, режим hook `ready` стал `queued`, тесты `test_ready_*` — `test_queued_*`. + Проверки отказов реплик (остановка, kill, зависание, rolling update) — не pytest, а `make test-failover`, профиль `failover` стенда `bench/` (`make bench_failover`, `bench.md`), команды драйвера `kill-inflight`, diff --git a/.claude/rules/worker.md b/.claude/rules/worker.md new file mode 100644 index 00000000..8e61011a --- /dev/null +++ b/.claude/rules/worker.md @@ -0,0 +1,53 @@ +--- +paths: + - "src/worker/**" + - "src/core/services/attachment_processing.py" + - "src/utils/thumbnail.py" +--- + +# Worker обработки вложений (с лабы 5) + +Спеки `attachment-processing`, `message-broker`; решения — design change +`async-attachments` (решения 2, 6–8). Здесь то, что легко нарушить. + +- **Процесс:** `python -m src.worker` → `src/worker/__main__.py` + (`early_stop.install("worker")`, «Invalid worker settings» и код 2, + `os._exit` в конце: поток декодирования отменить нельзя) → + `src/worker/main.py`. Свои engine, клиент S3 с ключами worker и клиенты + брокера; глобалы процесса API не импортируются. Сервис compose — на образе + API, без портов и healthcheck, не реплика: вне `rolling-update.sh` и + `restart.sh`. В консоли — `make run_worker`. +- **Pillow** импортирует только `src/utils/thumbnail.py`, его — только сервис + обработки: реплики API декодер в память не загружают и варианты не создают + ни при каких условиях (проверка — `/proc/1/maps` реплики). +- **Ack — только после устойчивого эффекта:** зафиксировано `ready` или + `failed` либо брокер подтвердил сообщение следующей попытки. Подтверждает + `main.py` по `JobOutcome` сервиса (`ACK`, `REQUEUE`, `DROP`). +- **Сообщение** — `src/schemas/jobs/attachment.py`, по + `contracts/jobs.schema.json`: только id и служебные поля. Ключи, размер, + SHA-256 и тип worker берёт из PostgreSQL. Не по схеме — `error` без + содержимого, `reject(requeue=False)`. +- **Счёт попыток — в БД,** а не заголовками брокера: `attempt` растёт при + взятии (`start_attempt`). `job_id` при повторах не меняется. Временная ошибка — + S3, срок, непредвиденное: `queued`, пауза `retry_delay_seconds` (сигнал её + прерывает), новое сообщение `attempt + 1`. Постоянная — сразу `failed`. + PostgreSQL недоступен — пауза и `REQUEUE`, попытка не считается: записать + нельзя. +- **Порядок блокировок везде:** задание (`lock_job`), затем вложение; вызовов + S3 внутри транзакций нет. Вложение `ready`, вариант и итог задания — одна + транзакция; результат старой попытки принимается, эффект тот же: те же ключи. +- **Ключ эффекта** `(attachment_id, pipeline_version, variant)` — первичный ключ + `attachment_variants`; ключ объекта варианта из него следует. Оригинал — не + строка этой таблицы. +- **Thumbnail:** размер считает `thumbnail_size`, а не `Image.thumbnail`: Pillow + округляет к ближайшему, контракт — вниз. `draft` у JPEG и transpose на малом + изображении держат пик памяти. `Image.Transpose.FLIP_LEFT_RIGHT` равен 0: + результат `.get` сравнивать с `None`, а не по истинности (нашёл тест всех + ориентаций). +- **Журнал:** `request_id` — `job_id` (ставит сервис: задача доставки своя, контекст + не течёт); `filename`, байтов, тел сообщений и секретов в записях нет + (`logging.md`, «Журнал worker»). +- **Ограничения** называются в `REPORT.md`: зависший worker с живым соединением + держит задание до срока подтверждения брокера, поток декодирования сроком не + прерывается, пауза повтора постоянна; `lease`, backoff и outbox — + `pipeline-reliability`. diff --git a/.claude/skills/run-mtusi-messenger/SKILL.md b/.claude/skills/run-mtusi-messenger/SKILL.md index 03eae7c0..7d14e059 100644 --- a/.claude/skills/run-mtusi-messenger/SKILL.md +++ b/.claude/skills/run-mtusi-messenger/SKILL.md @@ -1,18 +1,19 @@ --- name: run-mtusi-messenger -description: Запустить, остановить, прогнать и подёргать API мессенджера MTUSI (FastAPI, PostgreSQL, Valkey; лаба 3 — HAProxy перед репликами API; лаба 4 — S3 на SeaweedFS) — на хосте или в Docker. Use when asked to run / start / stop the server or the stand, run the smoke test, `make test`, `make student_test`, `make test_isolated`, `make test-persistence` or `make test-failover`, `make s3_check`, check that the S3 bucket is private, stop or restore an API replica, show X-Instance-Id distribution, check that an API change works on a live server, send a request to an endpoint, reproduce a bug over HTTP, check the containers, or call services directly without HTTP. +description: Запустить, остановить, прогнать и подёргать API мессенджера MTUSI (FastAPI, PostgreSQL, Valkey; лаба 3 — HAProxy перед репликами API; лаба 4 — S3 на SeaweedFS; лаба 5 — RabbitMQ и worker) — на хосте или в Docker. Use when asked to run / start / stop the server or the stand, run the smoke test, `make test`, `make student_test`, `make test_isolated`, `make test-persistence` or `make test-failover`, `make s3_check`, check that the S3 bucket is private, run the defense scenario, check the broker or the worker process, stop or restore an API replica, show X-Instance-Id distribution, check that an API change works on a live server, send a request to an endpoint, reproduce a bug over HTTP, check the containers, or call services directly without HTTP. --- REST API мессенджера (пользователи, чаты, сообщения) — сервер на FastAPI/uvicorn, данные в PostgreSQL из compose, карточки чатов кэшируются в Valkey из compose, с лабы 4 есть S3 (SeaweedFS) для байтов -вложений. Агент управляет им через +вложений, с лабы 5 — RabbitMQ и worker: загрузка отвечает 202, файл +становится `ready` в фоне. Агент управляет им через `.claude/skills/run-mtusi-messenger/driver.py`: он поднимает Postgres, -накатывает миграции, поднимает Valkey и S3 с bootstrap (`make upgrade -start_cache start_s3`), -запускает свой экземпляр сервера в фоне, гоняет сценарий по HTTP, +накатывает миграции, поднимает Valkey, S3 с bootstrap и брокер (`make +upgrade start_cache start_s3 start_broker`), +запускает свой экземпляр сервера и worker в фоне, гоняет сценарий по HTTP, публичный smoke и собственные тесты, шлёт одиночные запросы и -останавливает сервер. Против стенда compose (`make run_docker`: +останавливает их. Против стенда compose (`make run_docker`: HAProxy на `APP_OUT_PORT` перед репликами API) работают те же команды драйвера, кроме `start`/`stop`, плюс `instances` — распределение одной сессии по репликам, `kill-inflight` — kill реплики с запросами в @@ -26,7 +27,9 @@ s3_check`) — приватность bucket вне API, `attachment-failover` `upload-consistency` — согласованность БД и S3 (компенсация и уборщик незавершённых загрузок), `reconcile-cycle` и `reconcile-stress` — сверка bucket и БД (расхождения с обеих сторон, dry-run, `--apply`, повтор, -возврат оригинала; `--apply` под загрузками). `upload` и +возврат оригинала; `--apply` под загрузками), `defense-scenario` — сценарий +защиты лабы 5, `broker-check` и `worker-process` — брокер и процесс worker +(раздел «Лаба 5: брокер и worker»). `upload` и `download` — загрузка и скачивание вложения с SHA-256 на любом сервере. `stop-at-start` — остановка контейнеров образа во время старта, без стенда. Только @@ -57,7 +60,7 @@ Argon2id, около 30 мс на регистрацию и вход в конс ```bash uv sync --all-extras # venv с ruff и dev-группой (pytest, httpx, валидатор) -make env_setup # .env (случайные POSTGRES_PASSWORD, VALKEY_PASSWORD и 5 секретов S3, печатает только имена) и config.toml, существующие не трогает +make env_setup # .env (случайные POSTGRES_PASSWORD, VALKEY_PASSWORD, RABBITMQ_DEFAULT_PASS и секреты S3, печатает только имена) и config.toml, существующие не трогает ``` Нужен запущенный Docker: Postgres, Valkey и S3 живут в compose. Без @@ -65,8 +68,10 @@ Postgres сервер стартует, но `/health/ready` отвечает 50 всё работает, но мимо кэша (`warning` «Cache is unavailable» в логе); без S3 `/health/ready` — 200, а загрузка и скачивание байтов вложений — 503 (метаданные, сообщения и история работают). S3 нужен -только путям вложений. `driver.py start` сам делает `make upgrade start_cache -start_s3`. В `.env`, созданном до `membership-cache` или `s3-storage`, +только путям вложений. Без брокера `/health/ready` — 200, а загрузка — 503; +без worker загрузка — 202, вложение остаётся `queued`, скачивание — 409. +`driver.py start` сам делает `make upgrade start_cache +start_s3 start_broker`. В `.env`, созданном до `membership-cache` или `s3-storage`, нет строк Valkey или S3: их переносят из `.env.example` руками, иначе compose падает с `… is empty, copy … lines from .env.example`. @@ -81,23 +86,25 @@ python3 $D all # start → flow → tests/smoke.py → student-tests → st посмотреть лог, послать свой запрос): ```bash -python3 $D start # make upgrade start_cache start_s3, затем фон; ждёт /health/ready до 30 с +python3 $D start # make upgrade start_cache start_s3 start_broker, затем API и worker в фоне; ждёт /health/ready и брокер до 30 с python3 $D status # listeners: [pid reloader, pid worker], ready: True python3 $D flow # ~60 проверок: регистрация с паролем, вход, 409, неверный пароль, # 401 с WWW-Authenticate, X-User-Id игнорируется, чат, 5 сообщений, # пагинация limit=2 по курсору, чужой → 404, 400-е, повтор с ключом, - # 409 на другое тело, без ключа → 400, вложение: загрузка fixture, - # сообщение со ссылкой, оригинал Бобу (SHA-256), 404 Еве; logout; - # X-Instance-Id везде + # 409 на другое тело, без ключа → 400, вложение: загрузка fixture 202, + # сообщение со ссылкой, опрос до ready, оригинал Бобу (SHA-256), + # thumbnail (JPEG 256×160), 404 Еве; logout; X-Instance-Id везде python3 $D req POST /api/v1/users --data '{"username":"zoe_demo","display_name":"Зоя","password":"Zoe-password-1"}' python3 $D req POST /api/v1/auth/sessions --basic zoe_demo:Zoe-password-1 python3 $D req GET /api/v1/users/me --token python3 $D req POST /api/v1/chats//messages --token --data '{"text":"hi"}' # печатает idempotency-key; повтор той же отправки — тот же запрос с --key <ключ> python3 $D upload --token --chat --file tests/fixtures/sample.png - # 201, x-instance-id, Attachment, SHA-256 файла и «sha256 matches: True» -python3 $D download --token --attachment [--out /tmp/x.png] - # 200, Content-Type, размер, SHA-256 полученного (99ea7533… у fixture) + # 202, x-instance-id, снимок queued, SHA-256 файла и «sha256 matches: True», + # затем опрос до ready и итоговые метаданные +python3 $D download --token --attachment [--out /tmp/x.png] [--variant thumbnail] [--wait] + # 200, Content-Type, размер, SHA-256 полученного (99ea7533… у fixture), + # у JPEG — размеры по SOF; не ready — 409, с --wait — сначала опрос python3 $D smoke # публичный tests/smoke.py против этого порта python3 $D student # make student_test BASE_URL=http://localhost: — ~20 с python3 $D --port 8080 instances # стенд через LB: X-Instance-Id 12 запросов одной сессии @@ -106,7 +113,7 @@ python3 $D stop | команда | что делает | |---|---| -| `start` | `make upgrade start_cache start_s3`, затем `APP__RUN_MODE=console APP__PORT= uv run python -m src` в своей группе процессов | +| `start` | `make upgrade start_cache start_s3 start_broker`, затем `APP__RUN_MODE=console APP__PORT= uv run python -m src` и `make run_worker` (ключи S3 worker) в одной группе процессов; готово — `/health/ready` 200 и запись worker «Connected to broker». Журнал worker — `/tmp/mtusi-worker-.log` | | `status` | кто слушает порт, отвечает ли `/health/ready`; код 1, если никого | | `flow` | сквозной сценарий; `[FAIL]` в строке и код 1 при провале; в конце печатает id alice/bob/eve/chat и синтетический токен alice | | `req METHOD PATH [--token T \| --basic USER:PASS] [--data JSON] [--key K \| --no-key]` | один запрос: статус, `x-request-id`, `x-instance-id`, `www-authenticate` у 401, тело; код 2 при статусе ≥ 400. `POST …/messages` без `--key` получает новый `Idempotency-Key` (он печатается), `--no-key` — без заголовка | @@ -119,16 +126,19 @@ python3 $D stop | `cache-check [--require-test-keys]` | только стенд с LB (`--port 8080`): сценарии `chat-cache` «Чтение из кэша», «Срок записи», «Временная база». Два синтетических пользователя и чат; ключ `messenger:v1:<база>:chat:` сразу после 201 (`EXISTS`, TTL ≤ `[cache] chat_ttl_seconds` из реплики, поля значения), `DEL`, через 11 с снимок `seq_scan + idx_scan` таблицы `chats` и `keyspace_hits` / `keyspace_misses`, 50 чтений через LB, через 11 с второй снимок; TTL до и после ещё 10 чтений; число ключей рабочей и тестовой (`test_`) базы. Код 0 — чтений `chats` ≤ 1, hits ≥ +49, промахов ≤ 1, ответы равны ответу на создание, TTL не продлевается, ≥ 2 `X-Instance-Id`. Для «Временной базы» перед ней — `make test_isolated`: без ключей тестовой базы строка `PASS` заканчивается «temporary database: not checked», с `--require-test-keys` — код 1 (доказательство сценария снимается с флагом). На стенде в это время ничего другого не должно идти. Вывод — `evidence/cache/hits.md` | | `auth-storage` | только стенд с LB: сценарии `users` «Хэш в БД» и `sessions` «Токена нет в хранилище». Пароль P (с `:` и кириллицей) и токен T — только в памяти; через psql — префикс `$argon2id$…` до соли и длина у двух пользователей с одним P, неравенство хэшей, строка `sessions` с `token_hash` = SHA-256(T) (32 байта); `pg_dump --data-only` в память — нет ли T (текстом и в hex) и P. Код 0 — всё так. Вывод — `evidence/auth/passwords-and-tokens.md` | | `s3-check` | стенд compose (`make s3_check`), без приложения: спек `object-storage` «Проверка приватности вне API». `docker compose run --rm --no-deps s3-bootstrap check` — права ключа API (PUT/GET/HEAD объекта, 404 отсутствующего; 403 на список, создание и удаление bucket, политику и ACL bucket, публичный ACL объекта), права ключа уборщика (GET/HEAD/DELETE своего проверочного объекта, повторный DELETE и DELETE отсутствующего — 204; список с префиксом `<база>/attachments/` — 200, с change `track2-reconciler`; 403 на запись, список всего bucket и с чужим префиксом, bucket, политику, ACL), временный чужой bucket (403 на всё обоим ключам), аноним изнутри сервера (403); анонимные запросы с хоста (`127.0.0.1:S3_OUT_PORT`) и из сети стенда (одноразовый контейнер образа S3), порты контейнера S3: слушающие сокеты из `netstat -tuln` в контейнере — вне loopback ровно API S3 и gRPC шлюза, а остальные слушающие порты из сети закрыты (`nc -z`); затем `s3-bootstrap cleanup` и `weed shell` — проверочных объектов и bucket не осталось. Таблица «где → проверка → ожидаемо → получено» без секретов, код 1 при расхождении (печатает нарушенные). Вывод — `evidence/s3/privacy.md` | -| `upload --token T --chat C --file F [--type …] [--filename …]` | загрузка файла сырыми байтами (`urllib`): статус, `x-instance-id`, тело `Attachment`, размер и SHA-256 файла, совпал ли `sha256` ответа. `--type` по умолчанию — по сигнатуре (PNG, JPEG, иначе `application/octet-stream`), `--filename` — имя файла. Код 2 при статусе ≥ 400 | -| `download --token T --attachment A [--out F] [--variant …]` | скачивание оригинала: статус, `x-instance-id`, `Content-Type`, `Content-Length`, размер и SHA-256 полученного; `--out` сохраняет байты. Код 2 при статусе ≠ 200 (тело ошибки печатается) | -| `attachment-failover [--mode stop\|kill]` | только стенд с LB: спек `attachments` «Принявшая реплика остановлена». Синтетические Алиса, Боб, Ева и чат; загрузка `tests/fixtures/sample.png` через LB (реплика A — `X-Instance-Id` ответа), сообщение со ссылкой, `scripts/stop-one.sh` с `TARGET_INSTANCE_ID=A` и `STOP_MODE`, Боб скачивает через LB (до 30 попыток), пока не ответит другая реплика: SHA-256 совпадает, метаданные равны ответу загрузки; Ева — 404 на метаданные и байты. В `finally` — `make replicas`, затем ожидание, пока LB снова видит все реплики `UP`. Печатает `docker compose ps` до и после и таблицу «шаг → ожидаемо → получено → реплика» без токенов. Код 1 при расхождении, без LB (порт консольного процесса драйвера) — код 2. Вывод — `evidence/attachments/failover.md` | -| `attachment-storage` | только стенд с LB: спек `attachments` «Байты не в БД и не на диске API». Две загрузки fixture через LB; psql — колонки `attachments` и `message_attachments` (из `bytea` только 32-байтный `sha256`), `object_key` = `<база>/attachments//original` без `filename`; `weed shell fs.ls -l` — объект в bucket и его размер; анонимный GET ключа с `127.0.0.1:S3_OUT_PORT` — 403; скачивание участником — тот же SHA-256; `docker diff` каждой реплики — ни одного файла оригинала. Код 1 с названной проверкой, без LB — код 2. Вывод — `evidence/attachments/storage.md` | -| `upload-consistency` | только стенд с LB: спеки `attachments` «Порядок записи» и `storage-consistency` (design change `upload-consistency`, решение 11). Синтетические Алиса, Боб и чат; готовое вложение R. Шаги: (1) `docker compose pause s3` → загрузка через LB — 503 за ~5 с → `unpause` в `finally`; новая строка `pending` по psql (`id`, статус, возраст, ключ); (2) триггер «фиксация `ready` падает» (SQLSTATE 08006) на рабочей базе только для уникального `filename` прогона → загрузка 503 → строка `pending`, объекта уже нет (компенсация), триггер снят (`finally`, и остаток прошлого прогона — в начале); (3) метаданные, байты и сообщение со ссылкой на обе строки — 404; (4) после grace прогона 30 с — `docker compose run --rm --no-deps -e CLEANER__PENDING_GRACE_SECONDS=30 cleaner --once`, его JSON-вывод; (5) psql и `weed shell fs.tree` (файлы `original`, а не каталоги) — ни строк, ни объектов обеих загрузок, объектов без строки под префиксом рабочей базы нет; R скачивается с тем же SHA-256. Таблица «проверка → ожидаемо → получено» без токенов и секретов; код 1 при расхождении, без LB — код 2. ~45 с. Вывод — `evidence/attachments/consistency.md` | -| `reconcile-cycle` | только стенд с LB: спеки `storage-consistency` (сверка bucket и БД) и `attachments` «Потерянный оригинал» (design change `track2-reconciler`, решение 12). (1) исходный dry-run с grace по умолчанию — расхождений нет, иначе код 2; (2) синтетические Алиса, Боб, чат, вложения A (в сообщении), B, C; (3) объект O без строки и чужой ключ X — `docker exec` реплики (botocore образа её ключами), объект A удалён (`weed shell fs.rm`), строка B удалена и размер C изменён (psql), P — триггер COMMIT на уникальный `filename` (503, строка `pending` и объект); (4) после grace 30 с dry-run: таблица «класс → действие → ключ → `id` → возраст», снимки строк, объектов и пометок до и после совпали; (5) байты A — 500; (6) свежий F, `--apply`: O, B удалены, A, C помечены, P убрана, F не тронут, байты A — 404, метаданные A — 200 и равны ответу загрузки, история отдаёт A; (7) повтор — только чужой X, код 3; оператор удаляет X — код 0; после grace F удалён; (8) A возвращён теми же байтами — «оригинал вернулся», байты 200 с тем же SHA-256, итоговый dry-run — код 0. Таблица «проверка → ожидаемо → получено» без токенов; код 1 при расхождении, без LB — код 2. ~2 мин. Вывод — `evidence/reconcile/cycle.md` | -| `reconcile-stress [--seconds S] [--clients N]` | только стенд с LB: «Сверка под нагрузкой». Предусловие — dry-run с grace 20 с без расхождений (иначе код 2); два объекта без строки и два вложения без объекта; N клиентов (4) S секунд (40, больше grace) загружают PNG ~100 KiB из шума и отправляют сообщения, поток сверки — `--apply` с grace 20 с раз в ~3 с, затем ещё один проход. Итог: загрузки по кодам, сообщения, коды проходов, исправления по классам; проверки — внесённые исправлены (объекты удалены, новые пометки — ровно внесённые), каждое 201 скачивается с тем же SHA-256, каждое сообщение отдаёт своё вложение, ни одного прерванного прохода, повтор dry-run — код 0. Проверка корректности, не замер. Вывод — `evidence/reconcile/stress.md` | +| `upload --token T --chat C --file F [--type …] [--filename …]` | загрузка файла сырыми байтами (`urllib`): статус (202), `x-instance-id`, снимок `Attachment`, размер и SHA-256 файла, совпал ли `sha256` ответа, затем опрос метаданных раз в 0,2 с до `ready` или `failed` (до 60 с) и итоговое тело. `--type` по умолчанию — по сигнатуре (PNG, JPEG, иначе `application/octet-stream`), `--filename` — имя файла. Код 2 при статусе ≥ 400, `failed` и сроке ожидания | +| `download --token T --attachment A [--out F] [--variant …] [--wait]` | скачивание оригинала или варианта: статус, `x-instance-id`, `Content-Type`, `Content-Length`, размер и SHA-256 полученного, у JPEG — размеры по SOF; `--out` сохраняет байты. Код 2 при статусе ≠ 200 (тело ошибки печатается): не `ready` — 409 `conflict`, так его и показывают; `--wait` — сначала опрос до `ready` | +| `defense-scenario` | только стенд с LB: сценарий защиты лабы 5, раздел «Лаба 5: брокер и worker» | +| `broker-check [--require-test-queue]` | стенд compose: брокер, тот же раздел | +| `worker-process` | только стенд с LB: процесс worker, тот же раздел | +| `attachment-failover [--mode stop\|kill]` | только стенд с LB: спек `attachments` «Принявшая реплика остановлена». Синтетические Алиса, Боб, Ева и чат; загрузка `tests/fixtures/sample.png` через LB — 202 и ожидание `ready` (реплика A — `X-Instance-Id` ответа), сообщение со ссылкой, `scripts/stop-one.sh` с `TARGET_INSTANCE_ID=A` и `STOP_MODE`, Боб скачивает через LB (до 30 попыток), пока не ответит другая реплика: SHA-256 совпадает, метаданные равны метаданным `ready`; Ева — 404 на метаданные и байты. В `finally` — `make replicas`, затем ожидание, пока LB снова видит все реплики `UP`. Печатает `docker compose ps` до и после и таблицу «шаг → ожидаемо → получено → реплика» без токенов. Код 1 при расхождении, без LB (порт консольного процесса драйвера) — код 2. Вывод — `evidence/attachments/failover.md` | +| `attachment-storage` | только стенд с LB: спек `attachments` «Байты не в БД и не на диске API» и `data-storage` «Ограничения обработки в схеме». Две загрузки fixture через LB, 202 и ожидание `ready`; psql — колонки `attachments`, `message_attachments`, `attachment_jobs`, `attachment_variants` (из `bytea` только 32-байтные `sha256` вложения и варианта), `object_key` = `<база>/attachments//original` без `filename`, `staging_key` = `<база>/staging//original`; `weed shell fs.ls -l` — объект и thumbnail в bucket, размер; анонимный GET ключа и thumbnail с `127.0.0.1:S3_OUT_PORT` — 403; скачивание участником — тот же SHA-256; пробы в откатываемой транзакции — второе задание той же версии, второй вариант того же имени, `error_code` у не `failed`: каждая вставка отклонена (SQLSTATE и имя ограничения), после проб по одной строке задания и варианта; `docker diff` каждой реплики и worker — ни одного файла оригинала. Код 1 с названной проверкой, без LB — код 2. Вывод — `evidence/attachments/storage.md` | +| `upload-consistency` | только стенд с LB: спеки `attachments` «Порядок записи» и `storage-consistency` (design change `upload-consistency`, решение 11; `async-attachments`, решения 3 и 11). Синтетические Алиса, Боб и чат; вложение R — 202 и `ready`. Шаги: (1) `docker compose pause s3` → загрузка через LB — 503 за ~5 с → `unpause` в `finally`; новая строка `pending` по psql (`id`, статус, возраст, ключ); (2) триггер «перевод в `queued` падает» (SQLSTATE 08006) на рабочей базе только для уникального `filename` прогона → загрузка 503 → строка `pending`, объекта staging уже нет (компенсация), триггер снят (`finally`, и остаток прошлого прогона — в начале); (3) метаданные, байты и сообщение со ссылкой на обе строки — 404; (4) после grace прогона 30 с — `docker compose run --rm --no-deps -e CLEANER__PENDING_GRACE_SECONDS=30 cleaner --once`, его JSON-вывод; (5) psql и `weed shell fs.tree` (файлы `original`, а не каталоги, под `attachments/` и `staging/`) — ни строк, ни объектов обеих загрузок, объектов без строки под префиксом вложений рабочей базы нет; R скачивается с тем же SHA-256. Таблица «проверка → ожидаемо → получено» без токенов и секретов; код 1 при расхождении, без LB — код 2. ~45 с. Вывод — `evidence/attachments/consistency.md` | +| `reconcile-cycle` | только стенд с LB: спеки `storage-consistency` (сверка bucket и БД) и `attachments` «Потерянный оригинал» (design change `track2-reconciler`, решение 12). (1) исходный dry-run с grace по умолчанию — расхождений нет, иначе код 2; (2) синтетические Алиса, Боб, чат, вложения A (в сообщении), B, C — 202 и `ready`; (3) объект O без строки и чужой ключ X — `docker exec` реплики (botocore образа её ключами), объект A удалён (`weed shell fs.rm`), строка B с заданием и вариантом удалена и размер C изменён (psql), P — триггер COMMIT перевода в `queued` на уникальный `filename` (503, строка `pending` и объект staging; находка называет ключ staging); (4) после grace 30 с dry-run: таблица «класс → действие → ключ → `id` → возраст», снимки строк, объектов и пометок до и после совпали; ещё находка — объект thumbnail B без строки; (5) байты A — 500; (6) свежий F, `--apply`: O, B и thumbnail B удалены, A, C помечены, P убрана, F не тронут, байты A — 404, метаданные A — 200 и равны ответу загрузки, история отдаёт A; (7) повтор — только чужой X, код 3; оператор удаляет X — код 0; после grace F удалён; (8) A возвращён теми же байтами — «оригинал вернулся», байты 200 с тем же SHA-256, итоговый dry-run — код 0. Таблица «проверка → ожидаемо → получено» без токенов; код 1 при расхождении, без LB — код 2. ~2 мин. Вывод — `evidence/reconcile/cycle.md` | +| `reconcile-stress [--seconds S] [--clients N]` | только стенд с LB: «Сверка под нагрузкой». Предусловие — dry-run с grace 20 с без расхождений (иначе код 2); два объекта без строки и два вложения без объекта; N клиентов (4) S секунд (40, больше grace) загружают PNG ~100 KiB из шума и отправляют сообщения, поток сверки — `--apply` с grace 20 с раз в ~3 с, затем ещё один проход. Итог: загрузки по кодам, сообщения, коды проходов, исправления по классам; проверки — внесённые исправлены (объекты удалены, новые пометки — ровно внесённые), каждое 202 дошло до `ready` и скачивается с тем же SHA-256, каждое сообщение отдаёт своё вложение, ни одного прерванного прохода, повтор dry-run — код 0. Проверка корректности, не замер. Вывод — `evidence/reconcile/stress.md` | | `reconcile-signal` | только не рабочий проект compose (выбор — окружением `COMPOSE_PROJECT_NAME`, `COMPOSE_FILE`, `COMPOSE_ENV_FILES`; `mtusi-lab5` — отказ, код 2): спек `graceful-shutdown`, разовый проход сверки, прерванный сигналом, — код 1 (design change `track2-reconciler`, «Уточнения apply», п. 23). Нужны запущенные `s3` и образ уборщика, LB и реплики не нужны. `docker compose pause s3` → `run -d --no-deps --name <проект>-reconcile-signal cleaner reconcile --apply` → через секунду после «Started cleaner» `docker stop` → код контейнера и журнал → `rm`, `unpause s3` в `finally`. Записи процесса (событие, уровень, операция, `interrupted_by`, `exit_code`) и таблица: код 1, `interrupted_by: stop`, «Stopped cleaner» с `exit_code` 1, записей «Fixed» 0, остановка быстрее 10 с; код 1 при расхождении. ~10 с. `--pace` (design change `track2-reconcile-cost`, решение 14): вместо `pause s3` — 8 объектов пробы под `<база>/attachments/pace-signal-*` мимо API (`docker compose run --rm --no-deps -T --entrypoint python api -`: botocore образа ключами API из окружения контейнера), `cleaner reconcile --max-objects-per-second 1` (dry-run), `docker stop` через 2 с после «Started cleaner» — во время паузы предела скорости; ожидание — код 1, `interrupted_by: stop`, «Stopped cleaner» с `exit_code` 1, остановка ≤ 1 с, `listed_objects` итога — 8 (ключи страницы перед паузой, verify W1); объекты пробы удаляются в `finally`. `--pace --apply` (verify W1, ~45 с): объекты пробы — `<база>/attachments//original` без строки, через 19 с (grace прохода 18 с, `-e CLEANER__PENDING_GRACE_SECONDS=18`) `reconcile --apply --max-objects-per-second 1`, `docker stop` через 19,5 с после «Started cleaner» — посреди удалений, в паузе после DELETE; перед уборкой — сколько объектов пробы осталось (HEAD); ожидание — то же и «Fixed» = `fixed.orphan_object` = удалённых > 0. Нужен ещё сервис `api` в конфигурации проекта (реплики не нужны). Вывод — раздел `evidence/reconcile/service.md` | | `s3-idle [--rounds 3] [--downloads 10] [--puts 12] [--size-mib 4] [--pause-ms 0.5]` | только стенд с LB: спеки `object-storage` «Вызов после простоя» и `attachments` «Загрузка после простоя S3» (design change `fix-upload-put-flake`, решение 4). Проба клиента S3 в первой работающей реплике `api`: `docker exec -i <реплика> python -` со скриптом из stdin — код, настройки и ключи образа, ключи в драйвер не попадают; uvloop, если есть. Два варианта по очереди, у каждого свой `ObjectStorage` и пул: `image` (как в образе) и `reference` (прежний `read_timeout` aiohttp = `[s3] timeout_seconds`, подменой `AioConfig` при создании клиента). Раунд: `--downloads` одновременных скачиваний объекта `--size-mib` MiB через `open` / `iter_chunks` с паузой `--pause-ms` после блока 64 KiB, простой `[s3] timeout_seconds + 0,5` с, `--puts` PUT по 128 KiB по одному. Таблица по раундам: `read_timeout` клиента, скачивания с тем же SHA-256, соединения пула со взведённым сроком чтения после скачиваний (`armed`) и с сохранённым исключением после простоя (`broken`) — закрытые поля aiohttp `_conns`, `_read_timeout_handle`, `_exception`, нет их — «n/a», тогда судят только по PUT; PUT прошло и упало, у упавших — цепочка исключений и мс; каждый записанный объект читается обратно (размер и SHA-256). Объекты — под `<база>/.s3-idle-probe//` (сверка этот префикс не читает), удаляются в `finally` отдельным клиентом; затем `weed shell fs.tree` — файлов пробы 0. Код 0 — у `image` ни испорченного соединения, ни упавшего PUT, ни расхождения байтов, все раунды пройдены и файлов не осталось; 1 — иначе (эталон может падать: так видно механизм); 2 — нет реплики или консольный процесс драйвера. Пул API не трогает (отдельный процесс), но на время команды берёт ~100 MiB и CPU реплики — без нагрузки на стенд. ~40 с при 3 раундах и `timeout_seconds` 5. Вывод — `evidence/s3/idle-connection.md` | -| `lb-upload-timeouts [--config F] [--image ТЕГ]` | без стенда (рабочий стенд и проекты compose не трогает): спек `load-balancing` «Загрузки через балансировщик» и «Ошибки балансировщика в формате контракта» (design change `upload-memory`, решение 7). `haproxy -c` конфигурации F (по умолчанию `infra/haproxy/haproxy.cfg`) в закреплённом образе LB из `docker-compose.yml`, затем временная сеть `mtusi-lbto-<метка>`: заглушка реплики на образе API (по умолчанию `mtusi-messenger:lab5`, asyncio stdlib) под сетевым именем `api` и HAProxy с F и `API_PORT=8080` на свободном `127.0.0.1`; ожидание `UP` заглушки по `/health/ready` через LB. Пять случаев параллельно, у каждого своё соединение и свой `case` в строке запроса: заглушка молчит 12 с до чтения тела загрузки 10 MiB и после него — 201 от заглушки; 12 с на `GET /api/v1/users/me` — 504 LB через ~10 с; 32 с на пути загрузки — 504 LB через ~30 с; клиент отправил половину тела и молчит — 400 LB через ~30 с (`timeout client`). Ошибки LB — `application/json`, ровно `{"error": {"code", "message", "request_id"}}`, `code` по статусу, `request_id` = `X-Request-Id`. Таблица «случай → ожидаемо → получено → время», код 1 при расхождении. Сеть и контейнеры (метка `mtusi.lb-upload-timeouts`) удаляются при любом исходе, в том числе по Ctrl+C, SIGTERM, SIGHUP. ~35 с. На `haproxy.cfg` до change (`git archive f894040 infra/haproxy/haproxy.cfg \| tar -x -C <каталог>`, `--config <каталог>/infra/haproxy/haproxy.cfg`) — код 1: 502 и 504 через 10 с на пути загрузки, 400 в HTML. Вывод — `evidence/uploads/lb-timeouts.md` | +| `lb-upload-timeouts [--config F] [--image ТЕГ]` | без стенда (рабочий стенд и проекты compose не трогает): спек `load-balancing` «Загрузки через балансировщик» и «Ошибки балансировщика в формате контракта» (design change `upload-memory`, решение 7). `haproxy -c` конфигурации F (по умолчанию `infra/haproxy/haproxy.cfg`) в закреплённом образе LB из `docker-compose.yml`, затем временная сеть `mtusi-lbto-<метка>`: заглушка реплики на образе API (по умолчанию `mtusi-messenger:lab5`, asyncio stdlib) под сетевым именем `api` и HAProxy с F и `API_PORT=8080` на свободном `127.0.0.1`; ожидание `UP` заглушки по `/health/ready` через LB. Пять случаев параллельно, у каждого своё соединение и свой `case` в строке запроса: заглушка молчит 12 с до чтения тела загрузки 10 MiB и после него — 202 от заглушки; 12 с на `GET /api/v1/users/me` — 504 LB через ~10 с; 32 с на пути загрузки — 504 LB через ~30 с; клиент отправил половину тела и молчит — 400 LB через ~30 с (`timeout client`). Ошибки LB — `application/json`, ровно `{"error": {"code", "message", "request_id"}}`, `code` по статусу, `request_id` = `X-Request-Id`. Таблица «случай → ожидаемо → получено → время», код 1 при расхождении. Сеть и контейнеры (метка `mtusi.lb-upload-timeouts`) удаляются при любом исходе, в том числе по Ctrl+C, SIGTERM, SIGHUP. ~35 с. На `haproxy.cfg` до change (`git archive f894040 infra/haproxy/haproxy.cfg \| tar -x -C <каталог>`, `--config <каталог>/infra/haproxy/haproxy.cfg`) — код 1: 502 и 504 через 10 с на пути загрузки, 400 в HTML. Вывод — `evidence/uploads/lb-timeouts.md` | | `stop-at-start [--image ТЕГ] [--delays 0.2,0.3,0.4,1.5,5] [--server-start 3]` | спек `graceful-shutdown` «Остановка во время старта»: контейнеры образа (по умолчанию `mtusi-messenger:lab5`) с лимитами реплики (1 CPU / 512 МиБ без swap), без сети и `config.toml`; `docker stop --timeout 10` через паузу после `docker run` и сразу по строке «Started server process». По потоку `docker events` и журналу: «сигнал через», время `docker stop`, «выход после сигнала», код выхода, этап (`import` / `server-start` / `running`), кто остановил (`early` / `uvicorn`). Код 0 — каждая попытка с кодом 0 и `docker stop` ≤ 1 с, есть `import`, остановленный ранним обработчиком, и `running`. Проекты compose не трогает, свои контейнеры удаляет по метке `mtusi.stop-at-start`. Вывод — `evidence/failover/stop-at-start.md` | | `stop` | SIGTERM всей группе; ждёт, пока порт освободится. Чужой сервер и контейнер не трогает | | `all` | всё подряд (`student` — если есть `student-tests/`), `stop` в `finally` | @@ -144,15 +154,17 @@ python3 $D stop Проект `mtusi-lab5`, образ `mtusi-messenger:lab5`, compose-сервисы `postgres`, `valkey`, `s3` (SeaweedFS, API S3 на `127.0.0.1:S3_OUT_PORT` -— 8334), `migrate` (одноразовые миграции), `s3-bootstrap` (одноразовый: -приватный bucket, пользователи API и уборщика), `api` × `API_REPLICAS` -(по умолчанию 2, без портов на хосте), `cleaner` (уборщик незавершённых +— 8334), `rabbitmq` (AMQP на `127.0.0.1:5673`, volume `rabbitmq_data`), +`migrate` (одноразовые миграции), `s3-bootstrap` (одноразовый: +приватный bucket, пользователи API, уборщика и worker), `api` × `API_REPLICAS` +(по умолчанию 2, без портов на хосте), `worker` (`python -m src.worker`, без +портов и healthcheck), `cleaner` (уборщик незавершённых загрузок, без портов и healthcheck) и `haproxy` — единственный порт API на хосте, `127.0.0.1:APP_OUT_PORT` (8080). Конфиг LB — `infra/haproxy/haproxy.cfg`, правила — `balancer.md` и `docker.md`. ```bash -make run_docker # build + up -d: postgres, valkey, s3 → migrate, s3-bootstrap → api × 2 → haproxy +make run_docker # build + up -d: postgres, valkey, s3, rabbitmq → migrate, s3-bootstrap → api × 2, worker, cleaner → haproxy make s3_check # приватность bucket вне API: таблица проверок, код 0 docker compose logs s3-bootstrap # bucket/user exists|created, checks passed docker compose run --rm s3-bootstrap # повтор bootstrap: «exists», код 0 @@ -165,7 +177,7 @@ docker compose logs --no-log-prefix api | tail -5 # JSON всех реплик docker compose logs --no-log-prefix haproxy | tail # LB: ошибки, повторы (+N), смена состояния реплик docker compose exec valkey sh -c 'valkey-cli -p "$VALKEY_PORT" --scan --pattern "messenger:*" | head' # ключи кэша; пароль — из VALKEYCLI_AUTH контейнера -scripts/restart.sh # рестарт LB, всех реплик, Postgres, Valkey и S3 (~25 с): данные, токены и объекты остаются, кэш пуст +scripts/restart.sh # рестарт LB, всех реплик, Postgres, Valkey, S3 и брокера (~35 с): данные, токены, объекты и очередь остаются, кэш пуст; worker и уборщик не трогает make test-persistence ACTION_SCRIPT=scripts/restart.sh # то же публичной проверкой make test-failover ACTION_SCRIPT=scripts/stop-one.sh # остановка реплики, обслужившей тест; ~20 с STOP_MODE=kill STOP_ONE_LOG=/tmp/stop-one.log make test-failover ACTION_SCRIPT=scripts/stop-one.sh @@ -182,12 +194,16 @@ python3 $D --port 8080 upload-consistency # S3 заморожен и сбой make reconcile # разовая сверка bucket и БД, dry-run: код 0 — расхождений нет, 3 — остались make reconcile APPLY=1 [MAX_CHANGES=N] # то же с исправлением (предел изменений прохода — 100 или N) python3 $D --port 8080 reconcile-cycle # расхождения с обеих сторон: dry-run, --apply, 404/200, повтор = 0, возврат оригинала; ~2 мин -python3 $D --port 8080 reconcile-stress # --apply раз в 3 с под загрузками 4 клиентов 40 с: все 201 скачиваются с тем же SHA-256 +python3 $D --port 8080 reconcile-stress # --apply раз в 3 с под загрузками 4 клиентов 40 с: все 202 доходят до ready и скачиваются с тем же SHA-256 COMPOSE_PROJECT_NAME=<временный> python3 $D reconcile-signal # pause s3 + docker stop разового --apply: код 1, interrupted_by stop; не на mtusi-lab5 COMPOSE_PROJECT_NAME=<временный> python3 $D reconcile-signal --pace # docker stop во время паузы предела скорости: код 1, ≤ 1 с COMPOSE_PROJECT_NAME=<временный> python3 $D reconcile-signal --pace --apply # то же посреди удалений: каждое удалённое — «Fixed» python3 $D --port 8080 s3-idle # клиент S3 после скачиваний и простоя: у образа 0 испорченных соединений и упавших PUT, эталон портит; ~40 с -python3 $D lb-upload-timeouts # сроки LB пути загрузки на заглушке: 201 после 12 с молчания, 504 через 10/30 с, 400 в формате контракта; ~35 с +python3 $D lb-upload-timeouts # сроки LB пути загрузки на заглушке: 202 после 12 с молчания, 504 через 10/30 с, 400 в формате контракта; ~35 с +python3 $D --port 8080 defense-scenario # защита лабы 5: worker стоит, 202, 201, 409, 201, рестарт, worker, ready, оригинал и thumbnail; ~1,5 мин +python3 $D broker-check # брокер: образ, volume, порт, предел памяти, очередь, остановка с кодом 0; ~30 с +python3 $D --port 8080 worker-process # процесс worker: PID 1, лимиты, Pillow, журнал, неверные настройки, остановка, рестарт хранилищ; ~2 мин +docker compose logs --no-log-prefix worker | tail -3 # worker: Started worker, Connected to broker, задания docker compose logs --no-log-prefix cleaner | tail -3 # уборщик: Started cleaner (60/900/100), проходы, отказы docker compose run --rm --no-deps cleaner --once # разовый проход уборщика (grace 900 с): код 0 — проход дошёл до конца python3 $D stop-at-start # docker stop стартующей реплики: ~0,06 с и код 0 (раньше 10 с и 137) @@ -227,6 +243,83 @@ replicas` он снова выберет ту же. Чтобы останови сдвигают одним запросом перед тестом: `curl -s -o /dev/null http://127.0.0.1:8080/health/live`. +## Лаба 5: брокер и worker + +Design change `async-attachments`, решение 17. Команды останавливают сервисы +рабочего стенда, поэтому идут одни, без параллельных загрузок и тестов на нём. +Вывод — без токенов и секретов. + +**`defense-scenario`** (`--port `; спек `student-tests`, «Сценарий защиты +автоматизирован»; ~1,5 мин). Синтетические Алиса, Боб, Ева и чат, затем: + +1. `docker compose stop worker`; +2. загрузка `tests/fixtures/sample.png` — 202, снимок `queued`, `id` вложения; +3. сообщение с вложением — 201, `id` сообщения; +4. скачивание Бобом — 409; +5. текстовое сообщение — 201; +6. в очереди ≥ 1 сообщение и 0 потребителей; +7. `scripts/restart.sh`, ожидание LB, сообщение всё ещё в очереди, прежний токен + читает метаданные: `queued`; +8. `docker compose start worker`, опрос до `ready` (до 60 с); +9. оригинал — 200 и тот же SHA-256; thumbnail — 200, `image/jpeg`, 256×160 по + SOF (без Pillow, стандартной библиотекой), SHA-256 равен метаданным; +10. история отдаёт оба сообщения; `StartedAt` всех реплик `api` и `rabbitmq` до и + после — разный. + +Коды: 0 — всё сошлось; 1 — расхождение (таблица «проверка → ожидаемо → +получено»); 130 — прерван сигналом; 2 — нет стенда на порту или консольный процесс +драйвера. Вывод — `evidence/attachments/defense.md`. + +**`broker-check [--require-test-queue]`** (спек `message-broker`; ~30 с, порт не +нужен). Таблица «проверка → ожидаемо → получено»: образ `rabbitmq:X.Y.Z@sha256:…` в +`docker compose config`, `healthy`, volume `<проект>_rabbitmq_data` на +`/var/lib/rabbitmq`, `docker port` — ровно AMQP на `127.0.0.1`, лимит контейнера 512 +МиБ и `vm_memory_high_watermark_limit` меньше него (`rabbitmqctl -q status --formatter +json`), рабочая очередь `<база>.attachment.process.v1` durable (`rabbitmqctl -q +list_queues … --formatter json`). С флагом — ещё очередь +`test_<база>.attachment.process.v1`, без неё код 1, без флага — строка «not checked». +Затем `docker compose stop rabbitmq` — код 0 раньше срока 20 с, код контейнера 0; +`up -d --wait --no-recreate rabbitmq` (при любом исходе), очередь на месте, worker снова +потребляет (если потреблял). Коды: 0, 1 — расхождение, 130 — сигнал. Вывод — +`evidence/broker/stand.md`. + +**`worker-process`** (`--port `; спеки `container-run`, `graceful-shutdown`, +`service-configuration`; ~2 мин). PID 1 — `python -m src.worker`, healthcheck `NONE`, лимиты +1 CPU и 1 ГБ; `_imaging` нет в `/proc/1/maps` ни одной реплики API; версия Pillow в +образе равна `uv.lock`; последняя запись «Started worker» со всеми значениями, значения по +умолчанию; `WORKER__CONCURRENCY=0`, `WORKER__MAX_ATTEMPTS=abc`, +`WORKER__GRACEFUL_SHUTDOWN_SECONDS=10` (`docker compose run --rm --no-deps -e … worker`) — +код 2, запись называет поле, значения в ней нет; подмена окружением в одноразовом контейнере +(`WORKER__CONCURRENCY=3`, `WORKER__RECONNECT_SECONDS=1`); `docker compose stop worker` — код +контейнера 0, быстрее 10 с, «Stopped worker» с `exit_code` 0, затем `start`; `docker stop` +контейнера образа (без сети) через 0,2–0,4 с после `docker run` — код 0, не дольше 1 с, +«Stopped worker before startup» хотя бы в одной попытке; `scripts/restart.sh` — у worker +прежний `StartedAt`, `RestartCount` 0, новая загрузка `ready`. Коды: 0, 1 — расхождение, 130 — +сигнал, 2 — нет стенда. Вывод — `evidence/worker/process.md`. + +Gotchas: + +- **Сигнал во время `defense-scenario` или `worker-process`.** SIGINT, SIGTERM, SIGHUP + прерывают сценарий с кодом 130. Начатый `restart.sh` (своя сессия) доводится до конца, worker + запускается, повторные сигналы на это время игнорируются: выход может занять до минуты. От + SIGKILL защиты нет: `docker compose start worker` руками. +- **`broker-check --require-test-queue` имеет смысл только во время `make test_isolated`:** + после прогона очереди временной базы нет (спек «Очереди разных баз разделены»), поэтому отдельный + запуск — код 1, и это верно. Флаг запускают из другого терминала посреди прогона. +- **На время `broker-check` загрузки стенда — 503:** брокер остановлен ~5–10 с. +- **Без `--port` у `defense-scenario` и `worker-process` — код 2** («no stand on port 18080»): + стенд на 8080, а порт драйвера по умолчанию 18080. +- **Подмена окружением и `worker-process`.** Одноразовый контейнер — такой же потребитель рабочей + очереди; он живёт секунды и убирается `docker rm -f`: задание, если оно ему досталось, брокер + доставит снова. +- **Staging после `ready` остаётся** (очистка — следующее изменение + `pipeline-reliability`): `fs.tree … staging` показывает файлы готовых вложений, это не утечка. + Сверка staging не видит; у `reconcile-cycle` строка B удаляется вместе с заданием и вариантом + (FK без каскада), объект её варианта становится находкой, а её staging драйвер убирает сам. +- **Консольный `driver.py start` и стенд делят очередь:** имя очереди — от имени базы, база та же. + Если контейнер `worker` стенда запущен, задания консольного API может взять он (результат тот же). + Worker в консоли не перезагружается при правке `src/`: `driver.py stop`, затем `start`. + ## Direct invocation (без HTTP) Для правок в `src/core/` сервисы вызываются поверх сессии БД, сервер не @@ -287,7 +380,7 @@ make lint # ruff; затрагивает и dr ``` Ожидаемо: `PASS: offline skeleton structure...`, `FAILED: none` у -`flow`, smoke — `PASS: lab4 public API scenario...`, student — все +`flow`, smoke — `PASS: lab5 public API scenario...`, student — все прошли (тесты `fault` — `deselected`), `All checks passed!`; `all`, `test_isolated` и `failure_checks` — код 0. Пока файлы `evidence/`, на которые ссылаются исключения сверки покрытия, не сняты на стенде лабы @@ -312,6 +405,9 @@ make lint # ruff; затрагивает и dr по умолчанию набор ждёт `API_REPLICAS` реплик за `BASE_URL`. Против `make run_dev` — `make student_test EXPECT_REPLICAS=1`; `driver.py student` и `make test_isolated` передают его сами. +- **Загрузка отвечает 202, а не 201 (с лабы 5):** все команды вложений ждут + `ready` опросом метаданных раз в 0,2 с, до 60 с. Сообщение можно отправить и + с `queued`, а скачивание до `ready` — 409. - **Порт отдельной реплики на хосте не опубликован.** Запрос мимо LB — только изнутри сети: `docker compose exec --index 2 api python -c "import urllib.request as u; print(u.urlopen('http://127.0.0.1:8080/health/ready').headers['X-Instance-Id'])"`. diff --git a/.claude/skills/run-mtusi-messenger/driver.py b/.claude/skills/run-mtusi-messenger/driver.py index 72abb7a1..c2290abb 100644 --- a/.claude/skills/run-mtusi-messenger/driver.py +++ b/.claude/skills/run-mtusi-messenger/driver.py @@ -6,10 +6,12 @@ python3 .claude/skills/run-mtusi-messenger/driver.py [--port N] Команды: - start `make upgrade start_cache start_s3` (Postgres из compose и - миграции, Valkey, S3 с bootstrap), затем поднять - `python -m src` в фоне (console, reload) и дождаться - /health/ready; лог и pid — /tmp/mtusi-api-.{log,pid} + start `make upgrade start_cache start_s3 start_broker` (Postgres из + compose и миграции, Valkey, S3 с bootstrap, RabbitMQ), затем + поднять `python -m src` (console, reload) и `make run_worker` в + одной группе процессов и дождаться /health/ready и соединения + worker с брокером; лог и pid — /tmp/mtusi-api-.{log,pid}, + лог worker — /tmp/mtusi-worker-.log status кто слушает порт и что отвечает /health/ready flow сквозной сценарий по HTTP с проверками; код выхода 1 при провале req один запрос: req METHOD PATH [--token T | --basic USER:PASS] @@ -69,33 +71,61 @@ (ранний обработчик или uvicorn); код 1, если стартующий контейнер останавливается дольше 1 с или не с кодом 0 upload --token T --chat C --file F [--type …] [--filename …] - загрузка вложения: статус, X-Instance-Id, тело, SHA-256 файла - download --token T --attachment A [--out F] [--variant …] - скачивание оригинала: статус, X-Instance-Id, Content-Type, - размер и SHA-256 полученного + загрузка вложения: статус (202), X-Instance-Id, тело, SHA-256 + файла, затем опрос метаданных до ready; код 2 при статусе ≥ 400, + failed или сроке ожидания + download --token T --attachment A [--out F] [--variant …] [--wait] + скачивание оригинала или варианта: статус, X-Instance-Id, + Content-Type, размер и SHA-256 полученного, у JPEG — размеры по + SOF; не ready — 409 и код 2, с --wait — сначала опрос до ready attachment-failover [--mode stop|kill] только стенд с LB: спек attachments «Принявшая реплика остановлена» — загрузка - tests/fixtures/sample.png через LB, сообщение со ссылкой, - scripts/stop-one.sh реплики, принявшей файл, скачивание Бобом - через другую реплику (SHA-256 совпадает), 404 Еве; в finally - — make replicas; docker compose ps до и после, таблица без - токенов; код 1 при расхождении, без LB — код 2 + tests/fixtures/sample.png через LB (202, ожидание ready), + сообщение со ссылкой, scripts/stop-one.sh реплики, принявшей + файл, скачивание Бобом через другую реплику (SHA-256 совпадает), + 404 Еве; в finally — make replicas; docker compose ps до и + после, таблица без токенов; код 1 при расхождении, без LB — код 2 attachment-storage только стенд с LB: спек attachments «Байты не в БД и не на диске API» — колонки таблиц вложений (байты — только - 32-байтный SHA-256), object_key вида <база>/attachments// - original без filename, объект в bucket (weed shell), анонимный - GET ключа с хоста — 403, docker diff реплик без файлов - оригиналов; код 1 при расхождении, без LB — код 2 + 32-байтные SHA-256), object_key вида <база>/attachments// + original без filename, staging_key вида <база>/staging// + original, объект и вариант в bucket (weed shell), анонимный GET + ключа с хоста — 403, docker diff реплик и worker без файлов + оригиналов; спек data-storage «Ограничения обработки в схеме» — + вставки в откатываемой транзакции отклонены; код 1 при + расхождении, без LB — код 2 upload-consistency только стенд с LB: спеки attachments «Порядок записи» и storage-consistency — загрузка при docker compose - pause s3 (503, строка pending), загрузка со сбоем фиксации - ready (триггер на уникальный filename, 503, объект удалён - компенсацией), обе строки не видны через API (404), после + pause s3 (503, строка pending), загрузка со сбоем перевода в + queued (триггер на уникальный filename, 503, объект staging + удалён компенсацией), обе строки не видны через API (404), после grace 30 с — docker compose run --rm --no-deps cleaner --once, ни строк, ни объектов, объектов без строки под префиксом базы нет, готовое вложение скачивается с тем же SHA-256; триггер снимается в finally и в начале следующего прогона; код 1 при расхождении, без LB — код 2 + defense-scenario только стенд с LB: спек student-tests «Сценарий защиты + автоматизирован» — docker compose stop worker, загрузка + sample.png 202, сообщение с вложением 201, скачивание 409, + текстовое сообщение 201, scripts/restart.sh, docker compose + start worker, ожидание ready, оригинал (SHA-256) и thumbnail + (настоящий JPEG 256×160); шаги, коды, id, StartedAt api и + rabbitmq до и после, без токенов. Worker запускается при любом + исходе, в том числе по SIGINT, SIGTERM, SIGHUP; код 1 при + расхождении, 130 по сигналу, 2 — нет стенда + broker-check [--require-test-queue] стенд compose: спек message-broker + — образ тегом и digest, volume, docker port только AMQP на + 127.0.0.1, предел памяти меньше лимита контейнера, рабочая + очередь durable, с флагом — очередь test_ есть, docker + compose stop rabbitmq с кодом 0 раньше срока и возврат; таблица, + код 1 при расхождении, 130 по сигналу + worker-process только стенд с LB: спеки container-run и + graceful-shutdown — PID 1 worker, нет healthcheck, лимиты, Pillow + нет в процессе API, версия Pillow, «Started worker», неверные + WORKER__* (код 2), подмена окружением, значения по умолчанию, + остановка простаивающего и на старте, «Worker переживает рестарт + хранилищ»; worker запущен при любом исходе; код 1 при + расхождении, 130 по сигналу, 2 — нет стенда reconcile-cycle только стенд с LB: спек storage-consistency, сверка bucket и БД — исходный dry-run без расхождений (иначе код 2), расхождения с обеих сторон (объект мимо API и чужой ключ — @@ -109,8 +139,8 @@ reconcile-stress [--seconds S] [--clients N] только стенд с LB: «Сверка под нагрузкой» — внесённые расхождения, N клиентов S секунд загружают PNG ~100 KiB и отправляют сообщения, поток - сверки — --apply с grace 20 с раз в ~3 с; каждое 201 - скачивается с тем же SHA-256, сообщения отдают свои вложения, + сверки — --apply с grace 20 с раз в ~3 с; каждое 202 доходит до + ready и скачивается с тем же SHA-256, сообщения отдают вложения, повтор — 0; код 1 при расхождении reconcile-signal только не рабочий проект compose (окружение COMPOSE_PROJECT_NAME / COMPOSE_FILE; mtusi-lab5 — код 2): спек @@ -146,7 +176,7 @@ сеть, HAProxy закреплённого образа с конфигурацией F (по умолчанию infra/haproxy/haproxy.cfg) и заглушка реплики под именем api; молчание заглушки 12 с до и после тела загрузки — - 201, 12 с на другом пути — 504 через ~10 с, 32 с на пути + 202, 12 с на другом пути — 504 через ~10 с, 32 с на пути загрузки — 504 через ~30 с, клиент молчит посреди тела — 400 в формате контракта; сеть и контейнеры удаляются при любом исходе; код 1 при расхождении @@ -208,6 +238,8 @@ BASIC_CHALLENGE = 'Basic realm="messenger", charset="UTF-8"' BEARER_CHALLENGE = 'Bearer realm="messenger"' # с лабы 3 обязателен у POST сообщения: одна отправка — один ключ IDEMPOTENCY_KEY = "Idempotency-Key" +# запись журнала worker: соединение с брокером есть, очередь объявлена +WORKER_CONNECTED = "Connected to broker" def key_header(key: str | None = None) -> dict[str, str]: @@ -222,6 +254,19 @@ def paths(port: int) -> tuple[Path, Path]: ) +def worker_log(port: int) -> Path: + return Path(f"/tmp/mtusi-worker-{port}.log") + + +def group_alive(group: int) -> bool: + """Есть ли ещё процессы в группе.""" + try: + os.killpg(group, 0) + except ProcessLookupError: + return False + return True + + def base_url(port: int) -> str: return f"http://127.0.0.1:{port}" @@ -303,27 +348,44 @@ def cmd_start(port: int) -> int: print(f"port {port} is busy:", listener_pids(port)) return 1 # без Postgres сервис стартует, но /health/ready отвечает 503; без - # Valkey работает, но мимо кэша; без S3 — 503 на путях вложений + # Valkey работает, но мимо кэша; без S3 — 503 на путях вложений; без + # брокера — 503 на загрузке + targets = ["upgrade", "start_cache", "start_s3", "start_broker"] upgrade = subprocess.run( - ["make", "upgrade", "start_cache", "start_s3"], + ["make", *targets], cwd=ROOT, capture_output=True, text=True, check=False, ) if upgrade.returncode != 0: - print("make upgrade start_cache start_s3 failed:") + print(f"make {' '.join(targets)} failed:") print((upgrade.stdout + upgrade.stderr)[-2000:]) return 1 - env = os.environ | {"APP__RUN_MODE": "console", "APP__PORT": str(port)} + worker_log_path = worker_log(port) + worker_log_path.write_bytes(b"") + env = os.environ | { + "APP__RUN_MODE": "console", + "APP__PORT": str(port), + "MTUSI_WORKER_LOG": str(worker_log_path), + } with log_path.open("wb") as log: + # своя группа процессов: stop гасит uv, reloader и worker разом. + # Worker запускает сам sh: в группу другой сессии снаружи не войти, а + # sh без job control оставляет фоновую команду в своей группе, и exec + # сохраняет её номер. make run_worker подставляет ключи пользователя + # S3 worker и в вывод их не печатает proc = subprocess.Popen( - ["uv", "run", "python", "-m", "src"], + [ + "sh", + "-c", + 'make run_worker >"$MTUSI_WORKER_LOG" 2>&1 int: print(f"server exited with {proc.returncode}; log: {log_path}") print(log_path.read_text()[-2000:]) return 1 - if is_ready(port): - print(f"up on {base_url(port)} pgid={proc.pid} log={log_path}") + if is_ready(port) and WORKER_CONNECTED in worker_log_path.read_text(): + print( + f"up on {base_url(port)} pgid={proc.pid} log={log_path} " + f"worker log={worker_log_path}", + ) return 0 time.sleep(0.25) - print(f"not ready after 30s; log: {log_path}") + print(f"not ready after 30s; logs: {log_path} {worker_log_path}") return 1 @@ -350,8 +415,9 @@ def cmd_stop(port: int) -> int: return 1 print(f"nothing on {port}") return 0 + group = int(pid_path.read_text()) with contextlib.suppress(ProcessLookupError): - os.killpg(int(pid_path.read_text()), signal.SIGTERM) + os.killpg(group, signal.SIGTERM) pid_path.unlink() deadline = time.monotonic() + 12 while listener_pids(port) and time.monotonic() < deadline: @@ -359,6 +425,12 @@ def cmd_stop(port: int) -> int: if listener_pids(port): print(f"still listening on {port}:", listener_pids(port)) return 1 + # worker выходит сам, но не дольше срока остановки (≤ 9 с) + while group_alive(group) and time.monotonic() < deadline: + time.sleep(0.2) + if group_alive(group): + print(f"process group {group} is still running") + return 1 print(f"stopped {port}") return 0 @@ -659,8 +731,8 @@ def cmd_flow(port: int) -> int: listed = [item["id"] for item in chats["items"]] flow.check("bob sees the chat", chat["id"] in listed) - # вложения (лаба 4): загрузка fixture, сообщение со ссылкой, оригинал - # Бобу побайтно, 404 Еве + # вложения (лабы 4 и 5): загрузка fixture 202, сообщение со ссылкой, + # ожидание ready, оригинал Бобу побайтно, thumbnail, 404 Еве data = FIXTURE_PNG.read_bytes() status, hdrs, attachment = upload_bytes( port, @@ -670,10 +742,12 @@ def cmd_flow(port: int) -> int: content_type="image/png", filename=FIXTURE_PNG.name, ) - uploaded = status == 201 and isinstance(attachment, dict) + uploaded = status == ATTACHMENT_ACCEPTED and isinstance(attachment, dict) flow.check( - f"POST {CHATS}/…/attachments -> 201 (upload fixture)", - uploaded and attachment.get("sha256") == sha256_hex(data), + f"POST {CHATS}/…/attachments -> 202 (upload fixture)", + uploaded + and attachment.get("sha256") == sha256_hex(data) + and attachment.get("status") == "queued", f"{status} {hdrs.get('x-instance-id')}", ) if uploaded: @@ -692,6 +766,12 @@ def cmd_flow(port: int) -> int: isinstance(with_file, dict) and with_file.get("attachment_ids") == [attachment["id"]], ) + ready = wait_attachment(port, bob, str(attachment["id"])) + flow.check( + f"GET {ATTACHMENTS}/… -> ready (poll)", + ready.get("status") == "ready", + f"{ready.get('status')} {ready.get('error_code')}", + ) status, hdrs, payload = call_bytes( port, "GET", @@ -703,6 +783,17 @@ def cmd_flow(port: int) -> int: status == 200 and sha256_hex(payload) == sha256_hex(data), f"{status} {hdrs.get('content-type')} {len(payload)} bytes", ) + status, hdrs, payload = call_bytes( + port, + "GET", + f"{attachment_path}/content?variant=thumbnail", + token=bob, + ) + flow.check( + f"GET {ATTACHMENTS}/…/content?variant=thumbnail -> 200 (JPEG)", + status == 200 and jpeg_dimensions(payload) == THUMBNAIL_SIZE, + f"{status} {hdrs.get('content-type')} {jpeg_dimensions(payload)}", + ) flow.expect( "outsider metadata", "GET", @@ -2027,9 +2118,19 @@ FAILOVER_PAUSE_S = 0.5 # сколько ждать, пока LB снова пометит вернувшуюся реплику UP LB_UP_WAIT_S = 20 # ключ объекта: <база>/attachments//original (design change -# attachments, решение 4) +# attachments, решение 4), до обработки — <база>/staging//original +# (design change async-attachments, решение 1) ATTACHMENT_KEY_PREFIX = "attachments" +STAGING_KEY_PREFIX = "staging" ATTACHMENT_ORIGINAL = "original" +# загрузка с лабы 5: 202 и снимок queued, ready — опросом метаданных +ATTACHMENT_ACCEPTED = 202 +READY_POLL_S = 0.2 +READY_WAIT_S = 60 +# thumbnail tests/fixtures/sample.png (320 × 200): ширина и высота по SOF +THUMBNAIL_SIZE = (256, 160) +# маркеры начала кадра JPEG, у которых есть размеры (tests/image_probe.py) +JPEG_SOF = frozenset(range(0xC0, 0xD0)) - {0xC4, 0xC8, 0xCC} def call_bytes( @@ -2100,12 +2201,107 @@ def upload_bytes( return status, hdrs, parsed +def wait_attachment( + port: int, + token: str, + attachment_id: str, + *, + timeout: float = READY_WAIT_S, +) -> dict[str, object]: + """Опрос метаданных раз в 0,2 с до `ready` или `failed`; срок вышел — + последний полученный ответ. Сбой запроса опрос не прерывает: стенд может + ещё подниматься.""" + deadline = time.monotonic() + timeout + last: dict[str, object] = {} + while True: + with contextlib.suppress(OSError, http.client.HTTPException): + status, _, payload = call( + port, + "GET", + f"{ATTACHMENTS}/{attachment_id}", + token=token, + ) + if status == 200 and isinstance(payload, dict): + last = payload + if payload.get("status") in ("ready", "failed"): + return payload + if time.monotonic() >= deadline: + return last + time.sleep(READY_POLL_S) + + +def upload_ready( + port: int, + token: str, + chat_id: str, + data: bytes, + *, + content_type: str, + filename: str, +) -> tuple[int, dict[str, str], object]: + """Загрузка и ожидание `ready`: статус ответа загрузки и метаданные + готового вложения. Не дошло до `ready` — вместо метаданных `None`, причина + напечатана.""" + status, hdrs, payload = upload_bytes( + port, + token, + chat_id, + data, + content_type=content_type, + filename=filename, + ) + if status != ATTACHMENT_ACCEPTED or not isinstance(payload, dict): + return status, hdrs, payload + ready = wait_attachment(port, token, str(payload["id"])) + if ready.get("status") != "ready": + print( + f"attachment {payload['id']}: status {ready.get('status')}, " + f"error_code {ready.get('error_code')} (waited {READY_WAIT_S} s)", + ) + return status, hdrs, None + return status, hdrs, ready + + def sha256_hex(data: bytes) -> str: return hashlib.sha256(data).hexdigest() +def jpeg_dimensions(data: bytes) -> tuple[int, int] | None: + """Ширина и высота JPEG по SOF без внешних библиотек, как + `tests/image_probe.py`; ещё начало скана и EOI: это не декодер, но обрезок + и подделку заголовка видно. Иначе — `None`.""" + if data[:2] != b"\xff\xd8" or not data.endswith(b"\xff\xd9"): + return None + size: tuple[int, int] | None = None + at = 2 + while at + 4 <= len(data): + if data[at] != 0xFF: + return None + while at < len(data) and data[at] == 0xFF: + at += 1 + if at >= len(data): + return None + marker = data[at] + at += 1 + if marker == 0xDA: + return size + if marker in (0x01, 0xD8) or 0xD0 <= marker <= 0xD7: + continue + length = int.from_bytes(data[at : at + 2], "big") + if length < 2 or at + length > len(data): + return None + if marker in JPEG_SOF and length >= 8: + size = ( + int.from_bytes(data[at + 5 : at + 7], "big"), + int.from_bytes(data[at + 3 : at + 5], "big"), + ) + at += length + return None + + def cmd_upload(port: int, args: argparse.Namespace) -> int: - """Загрузка файла: статус, `X-Instance-Id`, тело, SHA-256 файла.""" + """Загрузка файла: статус, `X-Instance-Id`, тело, SHA-256 файла, затем + опрос до `ready`.""" data = Path(args.file).read_bytes() content_type = args.type or image_type(data) status, hdrs, payload = upload_bytes( @@ -2119,16 +2315,26 @@ def cmd_upload(port: int, args: argparse.Namespace) -> int: print(status, "x-instance-id:", hdrs.get("x-instance-id")) print(json.dumps(payload, ensure_ascii=False, indent=2)) print(f"file: {len(data)} bytes, sha256 {sha256_hex(data)}") - if status == 201 and isinstance(payload, dict): - print("sha256 matches:", payload.get("sha256") == sha256_hex(data)) - return 0 if status < 400 else 2 + if status >= 400: + return 2 + if status != ATTACHMENT_ACCEPTED or not isinstance(payload, dict): + return 0 + print("sha256 matches:", payload.get("sha256") == sha256_hex(data)) + ready = wait_attachment(port, args.token, str(payload["id"])) + print(json.dumps(ready, ensure_ascii=False, indent=2)) + return 0 if ready.get("status") == "ready" else 2 def cmd_download(port: int, args: argparse.Namespace) -> int: - """Скачивание оригинала: статус, тип, размер, SHA-256 полученного.""" + """Скачивание оригинала или варианта: статус, тип, размер, SHA-256 + полученного. Не `ready` — 409 и код 2: так его и показывают; `--wait` — + сначала опрос до `ready`.""" path = f"{ATTACHMENTS}/{args.attachment}/content" if args.variant is not None: path += "?" + urllib.parse.urlencode({"variant": args.variant}) + if args.wait: + ready = wait_attachment(port, args.token, args.attachment) + print(f"status {ready.get('status')}") status, hdrs, payload = call_bytes(port, "GET", path, token=args.token) print( status, @@ -2143,6 +2349,8 @@ def cmd_download(port: int, args: argparse.Namespace) -> int: print(payload.decode(errors="replace")) return 2 print(f"received: {len(payload)} bytes, sha256 {sha256_hex(payload)}") + if hdrs.get("content-type") == "image/jpeg": + print(f"JPEG size by SOF: {jpeg_dimensions(payload)}") if args.out: Path(args.out).write_bytes(payload) print(f"saved to {args.out}") @@ -2204,7 +2412,7 @@ def cmd_attachment_failover(port: int, mode: str) -> int: _, tokens, chat_id = people rows: list[tuple[str, str, str, str]] = [] problems: list[str] = [] - status, hdrs, attachment = upload_bytes( + status, hdrs, attachment = upload_ready( port, tokens["alice"], chat_id, @@ -2213,10 +2421,11 @@ def cmd_attachment_failover(port: int, mode: str) -> int: filename=FIXTURE_PNG.name, ) accepted_by = hdrs.get("x-instance-id", "") - rows.append(("alice uploads", "201", str(status), accepted_by)) - if status != 201 or not isinstance(attachment, dict): - print(f"FAIL: upload {status}") + rows.append(("alice uploads", "202", str(status), accepted_by)) + if status != ATTACHMENT_ACCEPTED or not isinstance(attachment, dict): + print(f"FAIL: upload {status}, not ready") return 1 + rows.append(("attachment is ready", "ready", attachment["status"], "")) attachment_id = str(attachment["id"]) uploaded_sha = str(attachment["sha256"]) status, hdrs, message = call( @@ -2323,13 +2532,13 @@ def cmd_attachment_failover(port: int, mode: str) -> int: time.sleep(FAILOVER_PAUSE_S) rows.append(("LB slots UP", str(replicas), str(up), "")) width = max(len(step) for step, _, _, _ in rows) - print(f"{'step':<{width}} expected got x-instance-id") + print(f"{'step':<{width}} expected got x-instance-id") failed = 0 for step, expected, got, instance in rows: ok = expected == got failed += not ok print( - f"{step:<{width}} {expected:<8} {got:<4} {instance}" + f"{step:<{width}} {expected:<8} {got:<5} {instance}" + ("" if ok else " FAIL"), ) for problem in problems: @@ -2346,8 +2555,9 @@ def cmd_attachment_failover(port: int, mode: str) -> int: def cmd_attachment_storage(port: int) -> int: """Спек `attachments`, «Байты не в БД и не на диске API» (design change `attachments`, решение 13): колонки таблиц вложений, вид - `object_key`, объект в bucket, анонимный GET — 403, `docker diff` - реплик без файлов оригиналов.""" + `object_key` и `staging_key`, объекты в bucket, анонимный GET — 403, + `docker diff` реплик и worker без файлов оригиналов. Спек `data-storage`, + «Ограничения обработки в схеме»: вставки в откатываемой транзакции.""" if no_lb(port): print("attachment-storage needs the stand with the load balancer") return 2 @@ -2368,7 +2578,7 @@ def cmd_attachment_storage(port: int) -> int: uploads = [] for number in range(2): filename = f"storage-check-{uuid.uuid4().hex[:8]}-{number}.png" - status, hdrs, attachment = upload_bytes( + status, hdrs, attachment = upload_ready( port, tokens["alice"], chat_id, @@ -2376,24 +2586,33 @@ def cmd_attachment_storage(port: int) -> int: content_type="image/png", filename=filename, ) - if status != 201 or not isinstance(attachment, dict): - print(f"FAIL: upload {status}") + if status != ATTACHMENT_ACCEPTED or not isinstance(attachment, dict): + print(f"FAIL: upload {status}, not ready") return 1 uploads.append((attachment, filename, hdrs.get("x-instance-id", ""))) rows: list[tuple[str, str, str]] = [] columns = stand_psql( "SELECT table_name, column_name, data_type " "FROM information_schema.columns WHERE table_schema = 'public' " - "AND table_name IN ('attachments', 'message_attachments') " + "AND table_name IN ('attachments', 'message_attachments', " + "'attachment_jobs', 'attachment_variants') " "ORDER BY table_name, ordinal_position;\n", ).splitlines() print("columns of attachment tables:") for line in columns: print(" " + line.replace("|", " ")) binary = [ - line.split("|")[1] for line in columns if line.endswith("|bytea") + line.split("|")[0] + "." + line.split("|")[1] + for line in columns + if line.endswith("|bytea") ] - rows.append(("bytea columns", "sha256", ",".join(binary) or "-")) + rows.append( + ( + "bytea columns", + "attachment_variants.sha256,attachments.sha256", + ",".join(binary) or "-", + ), + ) # id — UUID ответа API: безопасны в тексте SQL ids = ", ".join(f"'{a['id']}'" for a, _, _ in uploads) sha_length = stand_psql( @@ -2401,15 +2620,23 @@ def cmd_attachment_storage(port: int) -> int: f"WHERE id IN ({ids});\n", ).strip() rows.append(("octet_length(sha256)", "32", sha_length)) - keys = dict( + keys = { + line.split("|")[0]: line.split("|")[1:] + for line in stand_psql( + "SELECT id, object_key, staging_key FROM attachments " + f"WHERE id IN ({ids});\n", + ).splitlines() + } + variant_keys = dict( line.split("|") for line in stand_psql( - f"SELECT id, object_key FROM attachments WHERE id IN ({ids});\n", + "SELECT attachment_id, object_key FROM attachment_variants " + f"WHERE attachment_id IN ({ids});\n", ).splitlines() ) for attachment, filename, instance in uploads: attachment_id = str(attachment["id"]) - key = keys.get(attachment_id, "") + key, staging = keys.get(attachment_id, ["", ""]) expected = "/".join( ( database, @@ -2418,11 +2645,52 @@ def cmd_attachment_storage(port: int) -> int: ATTACHMENT_ORIGINAL, ), ) - print(f"upload via {instance}: object_key {key}") + print( + f"upload via {instance}: object_key {key}, staging_key {staging}", + ) rows.append(("object_key form", expected, key)) + rows.append( + ( + "staging_key form", + "/".join( + ( + database, + STAGING_KEY_PREFIX, + attachment_id, + ATTACHMENT_ORIGINAL, + ), + ), + staging, + ), + ) rows.append( ("filename not in key", "no", "yes" if filename in key else "no"), ) + variant = variant_keys.get(attachment_id, "") + rows.append( + ( + "thumbnail in bucket", + "yes", + yes( + bool(variant) + and variant.split("/")[-1] + in weed_shell( + f"fs.ls /buckets/{stand['bucket']}/{database}/" + f"{ATTACHMENT_KEY_PREFIX}/{attachment_id}", + ), + ), + ), + ) + rows.append( + ( + "anonymous GET of the thumbnail", + "403", + anonymous_code( + f"http://127.0.0.1:{stand['out_port']}/" + f"{stand['bucket']}/{variant}", + ), + ), + ) listing = weed_shell( f"fs.ls -l /buckets/{stand['bucket']}/{database}/" f"{ATTACHMENT_KEY_PREFIX}/{attachment_id}", @@ -2460,7 +2728,26 @@ def cmd_attachment_storage(port: int) -> int: "yes" if sha256_hex(payload) == attachment["sha256"] else "no", ), ) - replicas = compose("ps", "-q", "api").split() + # ограничения обработки: вставка копии строки готового вложения + probe_id = str(uploads[0][0]["id"]) + probes = dict( + line.split("|", 1) + for line in stand_psql( + PROCESSING_LIMITS_SQL.format(attachment_id=probe_id), + ).splitlines() + if "|" in line + ) + print("constraint probes (rolled back):") + for name, expected in PROCESSING_LIMITS: + print(f" {name}: {probes.get(name, 'no result')}") + rows.append((f"probe: {name}", expected, probes.get(name, "-"))) + left = stand_psql( + "SELECT (SELECT count(*) FROM attachment_jobs WHERE attachment_id = " + f"'{probe_id}') || '|' || (SELECT count(*) FROM attachment_variants " + f"WHERE attachment_id = '{probe_id}');\n", + ).strip() + rows.append(("jobs | variants after the probes", "1|1", left)) + replicas = compose("ps", "-q", "api", "worker").split() for container in replicas: diff = subprocess.run( ["docker", "diff", container], @@ -2502,17 +2789,77 @@ def cmd_attachment_storage(port: int) -> int: return 0 +# attachment-storage: спек data-storage, «Ограничения обработки в схеме». +# Каждая вставка — в своём блоке, итог — SQLSTATE и имя ограничения; ROLLBACK +# в конце: на рабочей базе не остаётся ничего. Копии — той же строки, поэтому +# отказ даёт только проверяемое ограничение +PROCESSING_LIMITS = ( + ( + "second job of the version", + "23505 uq_attachment_jobs_attachment_id_pipeline_version", + ), + ("second variant of the name", "23505 pk_attachment_variants"), + ( + "error_code on not failed", + "23514 ck_attachments_error_code_failed", + ), +) +PROCESSING_LIMITS_SQL = """\ +BEGIN; +CREATE TEMP TABLE driver_probe (name text, outcome text) ON COMMIT DROP; +CREATE FUNCTION pg_temp.driver_try(name text, statement text) +RETURNS void LANGUAGE plpgsql AS $$ +DECLARE + state text; + limit_name text; +BEGIN + EXECUTE statement; + INSERT INTO driver_probe VALUES (name, 'accepted'); +EXCEPTION WHEN others THEN + GET STACKED DIAGNOSTICS state = RETURNED_SQLSTATE, + limit_name = CONSTRAINT_NAME; + INSERT INTO driver_probe VALUES (name, state || ' ' || limit_name); +END +$$; +SELECT pg_temp.driver_try('second job of the version', $q$ + INSERT INTO attachment_jobs (id, attachment_id, pipeline_version, state, + attempt, updated_at, created_at) + SELECT gen_random_uuid(), attachment_id, pipeline_version, 'queued', 0, + now(), now() + FROM attachment_jobs WHERE attachment_id = '{attachment_id}' +$q$) \\g /dev/null +SELECT pg_temp.driver_try('second variant of the name', $q$ + INSERT INTO attachment_variants (attachment_id, pipeline_version, variant, + object_key, content_type, size_bytes, width, height, sha256, + created_at) + SELECT attachment_id, pipeline_version, variant, + object_key || '-probe', content_type, size_bytes, width, height, + sha256, now() + FROM attachment_variants WHERE attachment_id = '{attachment_id}' +$q$) \\g /dev/null +SELECT pg_temp.driver_try('error_code on not failed', $q$ + INSERT INTO attachments (id, chat_id, owner_id, filename, content_type, + size_bytes, sha256, object_key, staging_key, status, error_code, + updated_at, created_at) + SELECT gen_random_uuid(), chat_id, owner_id, filename, content_type, + size_bytes, sha256, object_key || '-probe', staging_key, status, + 'probe', now(), now() + FROM attachments WHERE id = '{attachment_id}' +$q$) \\g /dev/null +SELECT name || '|' || outcome FROM driver_probe; +ROLLBACK; +""" # upload-consistency: имена триггера и функции постоянные — остаток # прерванного прогона убирается в начале следующего. Отказ — SQLSTATE 08006: # для API это отказ БД (503), а не дефект (500) -UC_TRIGGER = "driver_uc_fail_ready" -UC_FAIL_READY_SQL = """\ +UC_TRIGGER = "driver_uc_fail_queued" +UC_FAIL_QUEUED_SQL = """\ CREATE OR REPLACE FUNCTION {name}() RETURNS trigger LANGUAGE plpgsql AS $$ BEGIN IF NEW.filename = TG_ARGV[0] AND OLD.status = 'pending' - AND NEW.status = 'ready' THEN - RAISE EXCEPTION 'driver: attachment ready failure' + AND NEW.status = 'queued' THEN + RAISE EXCEPTION 'driver: attachment queued failure' USING ERRCODE = '08006'; END IF; RETURN NEW; @@ -2525,6 +2872,8 @@ CREATE TRIGGER {name} BEFORE UPDATE ON attachments UC_CLEAR_SQL = f"""\ DROP TRIGGER IF EXISTS {UC_TRIGGER} ON attachments; DROP FUNCTION IF EXISTS {UC_TRIGGER}(); +DROP TRIGGER IF EXISTS driver_uc_fail_ready ON attachments; +DROP FUNCTION IF EXISTS driver_uc_fail_ready(); """ # grace разового прохода: больше границы живой загрузки (17 с) UC_GRACE_S = 30 @@ -2536,13 +2885,15 @@ UC_UUID = re.compile( ) -def stored_attachment_ids(bucket: str, database: str) -> set[str]: - """`id` вложений с файлом `original` под `<база>/attachments/` bucket - стенда — по файлам `fs.tree`, а не по каталогам: пустой каталог - `/` SeaweedFS убирает лишь через ~2 мин после DELETE.""" - tree = weed_shell( - f"fs.tree /buckets/{bucket}/{database}/{ATTACHMENT_KEY_PREFIX}", - ) +def stored_attachment_ids( + bucket: str, + database: str, + prefix: str = ATTACHMENT_KEY_PREFIX, +) -> set[str]: + """`id` вложений с файлом `original` под `<база>/attachments/` (или + `<база>/staging/`) bucket стенда — по файлам `fs.tree`, а не по каталогам: + пустой каталог `/` SeaweedFS убирает лишь через ~2 мин после DELETE.""" + tree = weed_shell(f"fs.tree /buckets/{bucket}/{database}/{prefix}") found: set[str] = set() current = "" for line in tree.splitlines(): @@ -2576,9 +2927,10 @@ def pending_row(attachment_id: str) -> str: def cmd_upload_consistency(port: int) -> int: """Спеки `attachments` («Порядок записи») и `storage-consistency` на рабочем стенде через LB (design change `upload-consistency`, решение - 11): загрузка при замороженном S3 и при сбое фиксации `ready`, их - строки `pending` не видны через API, компенсация удаляет объект, - разовый проход уборщика убирает обе загрузки, готовое вложение цело. + 11; `async-attachments`, решения 3 и 11): загрузка при замороженном S3 и + при сбое перевода в `queued`, их строки `pending` не видны через API, + компенсация удаляет объект staging, разовый проход уборщика убирает обе + загрузки, готовое вложение цело. Триггер — только на уникальный `filename` прогона, снимается в `finally` и в начале следующего прогона; S3 размораживается в `finally`. Токенов и секретов в выводе нет.""" @@ -2639,11 +2991,14 @@ def upload_consistency(port: int) -> int: return status, None status, payload = upload(f"uc-{tag}-ready.png") - if status != 201 or not isinstance(payload, dict): + if status != ATTACHMENT_ACCEPTED or not isinstance(payload, dict): print(f"FAIL: ready upload {status}") return 1 - ready = payload - rows.append(("ready attachment R uploaded", "201", str(status))) + ready = wait_attachment(port, tokens["alice"], str(payload["id"])) + rows.append(("attachment R uploaded", "202", str(status))) + rows.append(("attachment R processed", "ready", str(ready.get("status")))) + if ready.get("status") != "ready": + return report_rows(rows) # 1. S3 заморожен на время PUT before = attachment_statuses() @@ -2664,30 +3019,37 @@ def upload_consistency(port: int) -> int: paused_id = paused[0] print(f"pending {paused_id}: {pending_row(paused_id)}") - # 2. фиксация ready падает: компенсация удаляет объект - fail_name = f"uc-{tag}-ready-failure.png" + # 2. перевод в queued падает: компенсация удаляет объект staging + fail_name = f"uc-{tag}-queued-failure.png" before = attachment_statuses() try: stand_psql( - UC_FAIL_READY_SQL.format(name=UC_TRIGGER, filename=fail_name), + UC_FAIL_QUEUED_SQL.format(name=UC_TRIGGER, filename=fail_name), ) status, _ = upload(fail_name) finally: stand_psql(UC_CLEAR_SQL) - rows.append(("upload with ready failure", "503", str(status))) + rows.append(("upload with queued failure", "503", str(status))) failed = sorted(set(attachment_statuses()) - set(before)) - rows.append(("new pending rows (ready failure)", "1", str(len(failed)))) + rows.append(("new pending rows (queued failure)", "1", str(len(failed)))) if len(failed) != 1: - print("FAIL: no single pending row of the ready failure") + print("FAIL: no single pending row of the queued failure") return report_rows(rows) failed_id = failed[0] print(f"pending {failed_id}: {pending_row(failed_id)}") - stored = stored_attachment_ids(bucket, database) + staged = stored_attachment_ids(bucket, database, STAGING_KEY_PREFIX) rows.append( ( - "object after compensation", + "staging object after compensation", "absent", - "present" if failed_id in stored else "absent", + "present" if failed_id in staged else "absent", + ), + ) + rows.append( + ( + "staging object of the paused upload", + "absent", + "present" if paused_id in staged else "absent", ), ) triggers = stand_psql( @@ -2721,7 +3083,7 @@ def upload_consistency(port: int) -> int: rows.append((f"message with {pending_id[:8]}", "404", str(status))) # 3. разовый проход уборщика после grace прогона - # строка сбоя ready — младшая из двух: ждём, пока и она старше grace + # строка сбоя queued — младшая из двух: ждём, пока и она старше grace wait = max(0.0, UC_GRACE_S + 1 - float(age_of(failed_id))) print(f"waiting {wait:.0f} s for grace {UC_GRACE_S} s") time.sleep(wait) @@ -2751,6 +3113,7 @@ def upload_consistency(port: int) -> int: # 4. ни строк, ни объектов; объектов без строки нет statuses = attachment_statuses() stored = stored_attachment_ids(bucket, database) + staged = stored_attachment_ids(bucket, database, STAGING_KEY_PREFIX) for pending_id in (paused_id, failed_id): rows.append( ( @@ -2763,7 +3126,9 @@ def upload_consistency(port: int) -> int: ( f"object of {pending_id[:8]}", "absent", - "present" if pending_id in stored else "absent", + "present" + if pending_id in stored or pending_id in staged + else "absent", ), ) orphans = stored - set(statuses) @@ -2813,7 +3178,7 @@ def report_rows(rows: list[tuple[str, str, str]]) -> int: print(f"FAIL: {failed} check(s) failed") return 1 print( - "PASS: pending rows are invisible, the ready failure is compensated, " + "PASS: pending rows are invisible, the queued failure is compensated, " "the cleaner removed both uploads, no object without a row, R intact", ) return 0 @@ -2822,17 +3187,17 @@ def report_rows(rows: list[tuple[str, str, str]]) -> int: # reconcile-cycle и reconcile-stress (design change track2-reconciler, # решение 12): разовая сверка — в одноразовом контейнере уборщика стенда с # grace прогона. Триггер обрыва между объектом и фиксацией — отложенный -# триггер ограничения на уникальный filename: COMMIT перевода в ready -# падает (08006), объект остаётся, строка pending. Имя постоянное: остаток -# прерванного прогона убирается в начале следующего +# триггер ограничения на уникальный filename: COMMIT перевода в queued +# падает (08006), объект staging остаётся, строка pending. Имя постоянное: +# остаток прерванного прогона убирается в начале следующего RC_TRIGGER = "driver_rc_fail_commit" RC_FAIL_COMMIT_SQL = """\ CREATE OR REPLACE FUNCTION {name}() RETURNS trigger LANGUAGE plpgsql AS $$ BEGIN IF NEW.filename = TG_ARGV[0] AND OLD.status = 'pending' - AND NEW.status = 'ready' THEN - RAISE EXCEPTION 'driver: attachment ready commit failure' + AND NEW.status = 'queued' THEN + RAISE EXCEPTION 'driver: attachment queued commit failure' USING ERRCODE = '08006'; END IF; RETURN NULL; @@ -3119,7 +3484,7 @@ def reconcile_cycle(port: int) -> int: tag = uuid.uuid4().hex[:8] uploaded: dict[str, dict[str, object]] = {} for name in ("A", "B", "C"): - status, _, attachment = upload_bytes( + status, _, attachment = upload_ready( port, tokens["alice"], chat_id, @@ -3127,8 +3492,8 @@ def reconcile_cycle(port: int) -> int: content_type="image/png", filename=f"rc-{tag}-{name}.png", ) - rows.append((f"upload {name}", "201", str(status))) - if status != 201 or not isinstance(attachment, dict): + rows.append((f"upload {name}", "202", str(status))) + if status != ATTACHMENT_ACCEPTED or not isinstance(attachment, dict): return report_reconcile(rows) uploaded[name] = attachment status, _, message = call( @@ -3150,6 +3515,11 @@ def reconcile_cycle(port: int) -> int: ids = { name: str(attachment["id"]) for name, attachment in uploaded.items() } + # объект варианта B: строки B не станет, он тоже объект без метаданных + keys["B-thumbnail"] = stand_psql( + "SELECT object_key FROM attachment_variants " + f"WHERE attachment_id = '{ids['B']}';\n", + ).strip() try: # 3. расхождения с обеих сторон rows.append( @@ -3160,7 +3530,13 @@ def reconcile_cycle(port: int) -> int: ) weed_shell(f"fs.rm /buckets/{bucket}/{keys['A']}") # id — UUID из ответа API: безопасны в тексте SQL - stand_psql(f"DELETE FROM attachments WHERE id = '{ids['B']}';\n") + stand_psql( + "BEGIN;\n" + f"DELETE FROM attachment_variants WHERE attachment_id = '{ids['B']}';\n" + f"DELETE FROM attachment_jobs WHERE attachment_id = '{ids['B']}';\n" + f"DELETE FROM attachments WHERE id = '{ids['B']}';\n" + "COMMIT;\n", + ) stand_psql( "UPDATE attachments SET size_bytes = size_bytes + 1 " f"WHERE id = '{ids['C']}';\n", @@ -3185,7 +3561,11 @@ def reconcile_cycle(port: int) -> int: if len(pending) != 1: return report_reconcile(rows) ids["P"] = pending[0] - keys["P"] = f"{prefix}/{ids['P']}/{ATTACHMENT_ORIGINAL}" + # зависшая загрузка называет ключ staging (design change + # async-attachments, решение 11) + keys["P"] = ( + f"{database}/{STAGING_KEY_PREFIX}/{ids['P']}/{ATTACHMENT_ORIGINAL}" + ) print("keys of the run:") for name, key in sorted(keys.items()): print(f" {name}: {key}") @@ -3210,6 +3590,7 @@ def reconcile_cycle(port: int) -> int: for name, kind in ( ("O", "orphan_object"), ("B", "orphan_object"), + ("B-thumbnail", "orphan_object"), ("A", "missing_object"), ("C", "size_mismatch"), ("P", "stale_pending"), @@ -3249,6 +3630,7 @@ def reconcile_cycle(port: int) -> int: for name, action in ( ("O", "deleted_object"), ("B", "deleted_object"), + ("B-thumbnail", "deleted_object"), ("A", "marked_lost"), ("C", "marked_lost"), ("P", "removed_pending"), @@ -3256,6 +3638,7 @@ def reconcile_cycle(port: int) -> int: rows.append((f"apply fixes {name}", action, fixed.get(name, "-"))) rows.append(("apply touches F (fresh)", "-", fixed.get("F", "-"))) stored = stored_attachment_ids(bucket, database) + staged = stored_attachment_ids(bucket, database, STAGING_KEY_PREFIX) statuses = attachment_statuses() lost = rc_lost_ids() rows.append( @@ -3263,10 +3646,10 @@ def reconcile_cycle(port: int) -> int: ) rows.append( ( - "P row and object", + "P row and staging object", "absent", "present" - if ids["P"] in statuses or ids["P"] in stored + if ids["P"] in statuses or ids["P"] in staged else "absent", ), ) @@ -3383,6 +3766,11 @@ def reconcile_cycle(port: int) -> int: for name in ("X", "F", "O"): if name in keys: weed_shell(f"fs.rm /buckets/{bucket}/{keys[name]}") + # staging B: на этом уровне его никто не убирает, а строки уже нет + weed_shell( + f"fs.rm /buckets/{bucket}/{database}/{STAGING_KEY_PREFIX}/" + f"{ids['B']}/{ATTACHMENT_ORIGINAL}", + ) triggers = stand_psql( f"SELECT count(*) FROM pg_trigger WHERE tgname = '{RC_TRIGGER}';\n", ).strip() @@ -3421,8 +3809,8 @@ def cmd_reconcile_stress(port: int, *, seconds: float, clients: int) -> int: стенде через LB (design change `track2-reconciler`, решение 12): внесённые расхождения, `clients` клиентов `seconds` секунд загружают PNG ~100 KiB и отправляют сообщения, поток сверки — `--apply` с grace - 20 с раз в ~3 с. В конце — каждое 201 скачивается с тем же SHA-256, - каждое сообщение отдаёт своё вложение, повтор — 0. Проверка + 20 с раз в ~3 с. В конце — каждое 202 дошло до `ready` и скачивается с + тем же SHA-256, каждое сообщение отдаёт своё вложение, повтор — 0. Проверка корректности, не замер: тихий хост не нужен.""" if no_lb(port): print("reconcile-stress needs the stand with the load balancer") @@ -3464,7 +3852,7 @@ def reconcile_stress(port: int, seconds: float, clients: int) -> int: ) injected: list[str] = [] for _ in range(2): - status, _, attachment = upload_bytes( + status, _, attachment = upload_ready( port, tokens["alice"], chat_id, @@ -3472,8 +3860,8 @@ def reconcile_stress(port: int, seconds: float, clients: int) -> int: content_type="image/png", filename="rs-lost.png", ) - if status != 201 or not isinstance(attachment, dict): - print(f"FAIL: upload {status}") + if status != ATTACHMENT_ACCEPTED or not isinstance(attachment, dict): + print(f"FAIL: upload {status}, not ready") return 1 injected.append(str(attachment["id"])) weed_shell( @@ -3495,7 +3883,7 @@ def reconcile_stress(port: int, seconds: float, clients: int) -> int: while time.monotonic() < deadline: number += 1 body = rc_png(worker * 1_000_000 + number) - status, _, attachment = upload_bytes( + status, _, attachment = upload_ready( port, token, chat_id, @@ -3505,7 +3893,11 @@ def reconcile_stress(port: int, seconds: float, clients: int) -> int: ) with lock: codes[status] += 1 - if status != 201 or not isinstance(attachment, dict): + if status != ATTACHMENT_ACCEPTED: + continue + if not isinstance(attachment, dict): + with lock: + errors.append("attachment did not become ready") continue attachment_id = str(attachment["id"]) with lock: @@ -3609,12 +4001,12 @@ def reconcile_stress(port: int, seconds: float, clients: int) -> int: "fixed by class: " + (", ".join(f"{k}={v}" for k, v in sorted(fixed.items())) or "-"), ) - rows.append(("uploads 201", ">0", ">0" if uploads else "0")) + rows.append(("uploads 202 and ready", ">0", ">0" if uploads else "0")) rows.append( ( - "uploads not 201", + "uploads not 202", "0", - str(sum(v for k, v in codes.items() if k != 201)), + str(sum(v for k, v in codes.items() if k != ATTACHMENT_ACCEPTED)), ), ) rows.append( @@ -4053,16 +4445,16 @@ async def handle(reader, writer): if case == "before-body": await asyncio.sleep(SILENT) await reader.readexactly(length) - status = 201 + status = 202 elif case in ("after-body", "too-long"): await reader.readexactly(length) await asyncio.sleep(SILENT if case == "after-body" else LONG) - status = 201 + status = 202 elif case == "other-path": await asyncio.sleep(SILENT) else: await reader.readexactly(length) - status = 201 + status = 202 body = json.dumps({"status": "ok", "case": case}).encode() writer.write( f"HTTP/1.1 {status} Stub\r\nContent-Type: application/json\r\n" @@ -4334,14 +4726,14 @@ def lbto_cases(port: int) -> int: ( "upload: replica silent 12 s before body", lambda: lbto_request(port, "POST", f"{upload}before-body", body), - 201, + 202, "", (LBTO_SILENT_S - 0.5, LBTO_SILENT_S + 5), ), ( "upload: replica silent 12 s after body", lambda: lbto_request(port, "POST", f"{upload}after-body", body), - 201, + 202, "", (LBTO_SILENT_S - 0.5, LBTO_SILENT_S + 5), ), @@ -5187,6 +5579,996 @@ def cmd_s3_idle( return 0 +# defense-scenario, broker-check, worker-process (design change +# async-attachments, решение 17). Сервис worker и брокер останавливаются на +# рабочем стенде, поэтому возврат — при любом исходе +INTERRUPTED_EXIT = 130 +RESTORE_SIGNALS = (signal.SIGINT, signal.SIGTERM, signal.SIGHUP) +# scripts/restart.sh: ~35 с, на шумном хосте дольше +RESTART_WAIT_S = 180 +LB_READY_WAIT_S = 60 +# worker считается запущенным, если столько проверок подряд видят его живым: +# прерванный docker compose stop ещё может его погасить +WORKER_STABLE_CHECKS = 3 +WORKER_RESTORE_WAIT_S = 60 +# очередь заданий: имя базы + суффикс (src/infra/broker) +QUEUE_SUFFIX = ".attachment.process.v1" +BROKER_IMAGE = re.compile(r"^rabbitmq:\d+\.\d+\.\d+@sha256:[0-9a-f]{64}$") +BROKER_MEMORY_LIMIT = 512 * 1024 * 1024 +# срок остановки брокера: stop_grace_period в docker-compose.yml +BROKER_STOP_GRACE_S = 20 +BROKER_CONSUMER_WAIT_S = 30 +BROKER_START_WAIT_S = 120 +# спек container-run и service-configuration: лимиты и значения по умолчанию +WORKER_LIMITS = {"NanoCpus": 1_000_000_000, "Memory": 1024 * 1024 * 1024} +WORKER_DEFAULTS = { + "concurrency": 2, + "max_attempts": 5, + "job_timeout_seconds": 60, + "retry_delay_seconds": 10, + "graceful_shutdown_seconds": 8, + "reconnect_seconds": 2, +} +WORKER_BAD_SETTINGS = ( + ("WORKER__CONCURRENCY", "0", "worker.concurrency"), + ("WORKER__MAX_ATTEMPTS", "abc", "worker.max_attempts"), + ( + "WORKER__GRACEFUL_SHUTDOWN_SECONDS", + "10", + "worker.graceful_shutdown_seconds", + ), +) +WORKER_STOP_LIMIT_S = 10 +WORKER_LOG_WAIT_S = 30 +# docker stop на старте: паузы после docker run, пока процесс импортирует +# приложение. Остановленный позже уже не «before startup» — следующая пауза +WORKER_EARLY_DELAYS = (0.3, 0.2, 0.4) +WORKER_EARLY_STOP_LIMIT_S = 1.0 +WORKER_EARLY_LABEL = "mtusi.worker-process" + + +@contextlib.contextmanager +def signals_ignored(): + """Возврат стенда не прерывается вторым сигналом.""" + saved = { + sig: signal.signal(sig, signal.SIG_IGN) for sig in RESTORE_SIGNALS + } + try: + yield + finally: + for sig, handler in saved.items(): + signal.signal(sig, handler) + + +def detached(*args: str, timeout: float | None = None) -> tuple[int, str]: + """Команда в своей сессии: Ctrl+C терминала её не прерывает. Код и + вывод; в выводе секретов нет у команд compose без `config`.""" + proc = subprocess.run( + list(args), + cwd=ROOT, + capture_output=True, + text=True, + check=False, + start_new_session=True, + timeout=timeout, + ) + return proc.returncode, proc.stdout + proc.stderr + + +def service_containers(service: str) -> list[dict[str, object]]: + """`docker inspect` работающих контейнеров сервиса. Там есть окружение + с секретами: печатать только отдельные поля.""" + ids = compose("ps", "-q", "--status", "running", service).split() + if not ids: + return [] + return json.loads( + subprocess.run( + ["docker", "inspect", *ids], + capture_output=True, + text=True, + check=True, + ).stdout, + ) + + +def container_starts(*services: str) -> dict[str, str]: + """Имя контейнера → `StartedAt` работающих контейнеров сервисов.""" + return { + str(item["Name"]).lstrip("/"): str(item["State"]["StartedAt"]) + for service in services + for item in service_containers(service) + } + + +def json_records(text: str) -> list[dict[str, object]]: + """Записи журнала: строки JSON среди прочего вывода.""" + records = [] + for line in text.splitlines(): + if line.startswith("{"): + with contextlib.suppress(json.JSONDecodeError): + records.append(json.loads(line)) + return records + + +def broker_queues() -> dict[str, dict[str, object]]: + """Очереди брокера: имя → durable, messages, consumers.""" + out = compose( + "exec", + "-T", + "rabbitmq", + "rabbitmqctl", + "-q", + "list_queues", + "name", + "durable", + "messages", + "consumers", + "--formatter", + "json", + ) + return {str(item["name"]): item for item in json.loads(out)} + + +def wait_lb_ready(port: int) -> bool: + deadline = time.monotonic() + LB_READY_WAIT_S + while time.monotonic() < deadline: + if is_ready(port): + return True + time.sleep(0.5) + return False + + +def stand_answers(port: int, command: str) -> bool: + """Стенд отвечает на порту: иначе команде нечего проверять.""" + if no_lb(port): + print(f"{command} needs the stand with the load balancer") + return False + if not is_ready(port): + print(f"{command}: no stand on port {port}, use --port ") + return False + return True + + +def ensure_worker_running() -> bool: + """`docker compose start worker`, пока worker не живёт стабильно.""" + deadline = time.monotonic() + WORKER_RESTORE_WAIT_S + stable = 0 + while time.monotonic() < deadline: + code, out = detached( + "docker", + "compose", + "ps", + "-q", + "--status", + "running", + "worker", + ) + if code == 0 and out.strip(): + stable += 1 + if stable >= WORKER_STABLE_CHECKS: + return True + else: + stable = 0 + detached("docker", "compose", "start", "worker") + time.sleep(1) + return False + + +class WorkerGuard: + """Рестарт стенда, который доводится до конца, и worker, запущенный при + любом исходе. `restart.sh` — в своей сессии: сигнал его не обрывает на + полпути с остановленными репликами.""" + + def __init__(self) -> None: + self.restart: subprocess.Popen[bytes] | None = None + + def run_restart(self) -> int: + self.restart = subprocess.Popen( + [str(ROOT / "scripts" / "restart.sh")], + cwd=ROOT, + stdout=subprocess.DEVNULL, + stderr=subprocess.DEVNULL, + start_new_session=True, + ) + return self.restart.wait(timeout=RESTART_WAIT_S) + + def restore(self) -> bool: + """Дождаться начатого рестарта и запустить worker.""" + with signals_ignored(): + finished = True + if self.restart is not None and self.restart.poll() is None: + print("waiting for scripts/restart.sh to finish", flush=True) + try: + self.restart.wait(timeout=RESTART_WAIT_S) + except subprocess.TimeoutExpired: + print("FAIL: scripts/restart.sh did not finish") + finished = False + running = ensure_worker_running() + print(f"worker running at the end: {yes(running)}", flush=True) + if not running: + print("FAIL: start it by hand: docker compose start worker") + return running and finished + + +def run_guarded(body: Callable[[WorkerGuard], int]) -> int: + """Тело с `WorkerGuard`: сигнал — код 130, worker запущен всегда.""" + + def guarded() -> int: + guard = WorkerGuard() + code = 1 + try: + code = body(guard) + except KeyboardInterrupt as e: + print(f"FAIL: interrupted by {str(e) or 'SIGINT'}", flush=True) + code = INTERRUPTED_EXIT + except ( + RuntimeError, + OSError, + http.client.HTTPException, + subprocess.TimeoutExpired, + ) as e: + print(f"FAIL: {type(e).__name__}: {e}", flush=True) + code = 1 + finally: + if not guard.restore(): + code = code or 1 + return code + + return rc_signals(guarded) + + +def cmd_defense_scenario(port: int) -> int: + """Спек `student-tests`, «Сценарий защиты автоматизирован», на рабочем + стенде через LB (design change `async-attachments`, решение 17). Токенов + и секретов в выводе нет.""" + if not stand_answers(port, "defense-scenario"): + return 2 + return run_guarded(lambda guard: defense_scenario(port, guard)) + + +def defense_scenario(port: int, guard: WorkerGuard) -> int: + """Тело `cmd_defense_scenario`.""" + names = rc_stand() + if names is None: + return 1 + _, database = names + queue = database + QUEUE_SUFFIX + data = FIXTURE_PNG.read_bytes() + people = attachment_people(port, "ds") + if people is None: + return 1 + _, tokens, chat_id = people + messages = f"{CHATS}/{chat_id}/messages" + rows: list[tuple[str, str, str]] = [] + before = container_starts("api", "rabbitmq") + print( + f"fixture {FIXTURE_PNG.name}: {len(data)} bytes, sha256 " + f"{sha256_hex(data)}", + ) + + def step(name: str, expected: object, got: object) -> None: + rows.append((name, str(expected), str(got))) + print(f"{name}: {got}", flush=True) + + compose("stop", "worker") + step("docker compose stop worker", "0", "0") + status, hdrs, attachment = upload_bytes( + port, + tokens["alice"], + chat_id, + data, + content_type="image/png", + filename=FIXTURE_PNG.name, + ) + step("upload sample.png", ATTACHMENT_ACCEPTED, status) + if status != ATTACHMENT_ACCEPTED or not isinstance(attachment, dict): + return report_defense(rows, before) + attachment_id = str(attachment["id"]) + content = f"{ATTACHMENTS}/{attachment_id}/content" + print(f"attachment id {attachment_id}, via {hdrs.get('x-instance-id')}") + step("snapshot status", "queued", attachment.get("status")) + status, _, message = call( + port, + "POST", + messages, + token=tokens["alice"], + body={"text": "", "attachment_ids": [attachment_id]}, + extra=key_header(), + ) + step("message with the attachment", 201, status) + message_id = message.get("id") if isinstance(message, dict) else None + print(f"message id {message_id}") + status, _, _ = call_bytes(port, "GET", content, token=tokens["bob"]) + step("download before processing", 409, status) + status, _, text = call( + port, + "POST", + messages, + token=tokens["alice"], + body={"text": "text while the worker is stopped"}, + extra=key_header(), + ) + step("text message", 201, status) + text_id = text.get("id") if isinstance(text, dict) else None + print(f"text message id {text_id}") + depth = broker_queues().get(queue, {}) + step( + "job in the queue before restart", + "yes", + yes(int(str(depth.get("messages", 0))) >= 1), + ) + step("queue consumers before restart", "0", depth.get("consumers")) + + step("scripts/restart.sh", "0", guard.run_restart()) + step("LB ready after restart", "yes", yes(wait_lb_ready(port))) + depth = broker_queues().get(queue, {}) + step( + "job in the queue after restart", + "yes", + yes(int(str(depth.get("messages", 0))) >= 1), + ) + status, _, meta = call( + port, + "GET", + f"{ATTACHMENTS}/{attachment_id}", + token=tokens["bob"], + ) + step("metadata after restart (same session)", 200, status) + step( + "status after restart", + "queued", + meta.get("status") if isinstance(meta, dict) else meta, + ) + + code, _ = detached("docker", "compose", "start", "worker") + step("docker compose start worker", "0", code) + ready = wait_attachment(port, tokens["bob"], attachment_id) + step("attachment status", "ready", ready.get("status")) + status, _, original = call_bytes(port, "GET", content, token=tokens["bob"]) + step("download original", 200, status) + step( + "original sha256 = uploaded", + "yes", + yes(sha256_hex(original) == sha256_hex(data)), + ) + variants = { + str(item.get("name")): item + for item in ready.get("variants", []) # type: ignore[union-attr] + } + thumbnail = variants.get("thumbnail", {}) + status, hdrs, jpeg = call_bytes( + port, + "GET", + f"{content}?variant=thumbnail", + token=tokens["bob"], + ) + step("download thumbnail", 200, status) + step("thumbnail content type", "image/jpeg", hdrs.get("content-type")) + step("thumbnail by SOF", THUMBNAIL_SIZE, jpeg_dimensions(jpeg)) + step( + "thumbnail sha256 = metadata", + "yes", + yes(sha256_hex(jpeg) == thumbnail.get("sha256")), + ) + status, _, page = call(port, "GET", messages, token=tokens["bob"]) + items = page.get("items", []) if isinstance(page, dict) else [] + step("history after restart", 200, status) + step( + "history keeps both messages", + "yes", + yes({item.get("id") for item in items} >= {message_id, text_id}), + ) + return report_defense(rows, before) + + +def report_defense( + rows: list[tuple[str, str, str]], + before: dict[str, str], +) -> int: + """Время старта до и после и таблица шагов.""" + after = container_starts("api", "rabbitmq") + print("containers: StartedAt before -> after") + for name in sorted(set(before) | set(after)): + print(f" {name}: {before.get(name)} -> {after.get(name)}") + if rows[-1][0] != "upload sample.png": + same = sorted( + name + for name, started in before.items() + if after.get(name) == started + ) + rows.append( + ( + "api and rabbitmq restarted", + "yes", + yes(not same and bool(after)), + ), + ) + return report_reconcile( + rows, + passed="the file is accepted while the worker is stopped and becomes " + "ready after the restart", + ) + + +def cmd_broker_check(*, require_test_queue: bool) -> int: + """Спек `message-broker`: «Сервис брокера запущен», «Предел памяти + брокера», «Очереди разных баз разделены», «Остановка брокера». Брокер + возвращается при любом исходе; секретов в выводе нет.""" + + def guarded() -> int: + try: + return broker_check(require_test_queue=require_test_queue) + except KeyboardInterrupt as e: + print(f"FAIL: interrupted by {str(e) or 'SIGINT'}", flush=True) + return INTERRUPTED_EXIT + except RuntimeError as e: + print(f"FAIL: {e}", flush=True) + return 1 + + return rc_signals(guarded) + + +def broker_check(*, require_test_queue: bool) -> int: + """Тело `cmd_broker_check`.""" + names = rc_stand() + if names is None: + return 1 + _, database = names + config = json.loads(compose("config", "--format", "json")) + project = str(config["name"]) + service = config["services"]["rabbitmq"] + containers = service_containers("rabbitmq") + if not containers: + print("FAIL: service rabbitmq is not running, make run_docker first") + return 1 + container = containers[0] + name = str(container["Name"]).lstrip("/") + rows: list[tuple[str, str, str]] = [] + + image = str(service["image"]) + print(f"image {image}") + rows.append( + ( + "image is tag and digest", + "yes", + yes(bool(BROKER_IMAGE.match(image))), + ), + ) + rows.append( + ( + "container health", + "healthy", + str(container["State"].get("Health", {}).get("Status")), + ), + ) + mounts = [ + str(item.get("Name")) + for item in container["Mounts"] + if item.get("Type") == "volume" + and item.get("Destination") == "/var/lib/rabbitmq" + ] + rows.append( + ( + "data volume", + f"{project}_rabbitmq_data", + ",".join(mounts) or "-", + ), + ) + published = subprocess.run( + ["docker", "port", name], + capture_output=True, + text=True, + check=False, + ).stdout.split("\n") + published = [line for line in published if line.strip()] + amqp = next( + item["published"] + for item in service["ports"] + if int(item["target"]) == 5672 + ) + rows.append( + ( + "docker port", + f"5672/tcp -> 127.0.0.1:{amqp}", + ";".join(published) or "-", + ), + ) + + limit = int(container["HostConfig"]["Memory"]) + rows.append( + ("container memory limit", str(BROKER_MEMORY_LIMIT), str(limit)), + ) + status = json.loads( + compose( + "exec", + "-T", + "rabbitmq", + "rabbitmqctl", + "-q", + "status", + "--formatter", + "json", + ), + ) + watermark = int(status["vm_memory_high_watermark_limit"]) + print(f"memory high watermark {watermark}, container limit {limit}") + rows.append( + ("watermark below container limit", "yes", yes(0 < watermark < limit)), + ) + + queues = broker_queues() + print("queues (name durable messages consumers):") + for item in queues.values(): + print( + f" {item['name']} {item['durable']} {item['messages']} " + f"{item['consumers']}", + ) + work = database + QUEUE_SUFFIX + rows.append(("work queue exists", "yes", yes(work in queues))) + rows.append( + ( + "work queue durable", + "yes", + yes(queues.get(work, {}).get("durable") is True), + ), + ) + test_queue = f"test_{database}{QUEUE_SUFFIX}" + if require_test_queue: + rows.append( + (f"queue {test_queue}", "yes", yes(test_queue in queues)), + ) + else: + print(f"temporary database queue {test_queue}: not checked") + + had_consumer = int(str(queues.get(work, {}).get("consumers", 0))) > 0 + try: + started = time.monotonic() + code, _ = detached("docker", "compose", "stop", "rabbitmq") + took = time.monotonic() - started + exit_code = subprocess.run( + ["docker", "inspect", "-f", "{{.State.ExitCode}}", name], + capture_output=True, + text=True, + check=False, + ).stdout.strip() + print(f"docker compose stop rabbitmq: {took:.1f} s") + rows.append(("docker compose stop exit code", "0", str(code))) + rows.append(("container exit code", "0", exit_code)) + rows.append( + ( + f"stopped before the {BROKER_STOP_GRACE_S} s grace", + "yes", + yes(took < BROKER_STOP_GRACE_S), + ), + ) + finally: + with signals_ignored(): + code, _ = detached( + "docker", + "compose", + "up", + "-d", + "--wait", + "--no-recreate", + "rabbitmq", + ) + rows.append(("broker back (up --wait)", "0", str(code))) + queues = broker_queues() + rows.append( + ( + "work queue after restart", + "yes", + yes(queues.get(work, {}).get("durable") is True), + ), + ) + if had_consumer: + deadline = time.monotonic() + BROKER_CONSUMER_WAIT_S + while time.monotonic() < deadline: + current = int( + str(broker_queues().get(work, {}).get("consumers", 0)), + ) + if current > 0: + break + time.sleep(1) + rows.append(("worker consumes again", "yes", yes(current > 0))) + return report_reconcile(rows, passed="the broker stand matches the spec") + + +def cmd_worker_process(port: int) -> int: + """Спеки `container-run`, `graceful-shutdown`, `service-configuration` + о процессе worker на рабочем стенде (design change `async-attachments`, + решение 17). Секретов в выводе нет: печатаются только нужные поля.""" + if not stand_answers(port, "worker-process"): + return 2 + return run_guarded(lambda guard: worker_process(port, guard)) + + +def worker_process(port: int, guard: WorkerGuard) -> int: + """Тело `cmd_worker_process`.""" + config = json.loads(compose("config", "--format", "json")) + project = str(config["name"]) + image = str(config["services"]["worker"]["image"]) + containers = service_containers("worker") + if not containers: + print("FAIL: service worker is not running, make run_docker first") + return 2 + container = containers[0] + worker_id = str(container["Id"]) + name = str(container["Name"]).lstrip("/") + rows: list[tuple[str, str, str]] = [] + + # процесс + cmdline = subprocess.run( + ["docker", "exec", name, "cat", "/proc/1/cmdline"], + capture_output=True, + check=False, + ).stdout + rows.append( + ( + "PID 1 of the worker", + "python -m src.worker", + cmdline.replace(b"\0", b" ").decode().strip(), + ), + ) + rows.append( + ( + "healthcheck", + "NONE", + " ".join( + (container["Config"].get("Healthcheck") or {}).get("Test") + or [], + ), + ), + ) + for field, expected in WORKER_LIMITS.items(): + rows.append( + ( + f"limit {field}", + str(expected), + str(container["HostConfig"][field]), + ), + ) + replicas = service_containers("api") + for replica in replicas: + maps = subprocess.run( + ["docker", "exec", str(replica["Id"]), "cat", "/proc/1/maps"], + capture_output=True, + text=True, + check=False, + ).stdout + rows.append( + ( + f"_imaging in {str(replica['Name']).lstrip('/')}", + "no", + yes("_imaging" in maps), + ), + ) + rows.append(("API replicas checked", "yes", yes(bool(replicas)))) + pillow = subprocess.run( + [ + "docker", + "exec", + name, + "python", + "-c", + "import PIL; print(PIL.__version__)", + ], + capture_output=True, + text=True, + check=False, + ).stdout.strip() + locked = re.search( + r'name = "pillow"\nversion = "([^"]+)"', + (ROOT / "uv.lock").read_text(), + ) + rows.append( + ( + "Pillow in the image = uv.lock", + locked.group(1) if locked else "-", + pillow or "-", + ), + ) + + # запись о старте и значения по умолчанию + logs = compose("logs", "--no-log-prefix", "worker") + started = [ + r for r in json_records(logs) if r.get("event") == "Started worker" + ] + rows.append(("'Started worker' record", "yes", yes(bool(started)))) + record = started[-1] if started else {} + print("Started worker:") + for key in ( + *WORKER_DEFAULTS, + "broker_host", + "broker_port", + "broker_queue", + "s3_host", + "s3_port", + "s3_bucket", + "database_host", + "database_port", + "database_name", + "database_pool_size", + ): + print(f" {key}: {record.get(key)}") + for key, value in WORKER_DEFAULTS.items(): + rows.append( + ( + f"default {key}", + str(float(value)), + str(float(str(record.get(key, "nan")))), + ), + ) + + # неверные настройки: код 2, поле называется, значения нет + for variable, value, field in WORKER_BAD_SETTINGS: + code, out = detached( + "docker", + "compose", + "run", + "--rm", + "--no-deps", + "-T", + "-e", + f"{variable}={value}", + "worker", + ) + invalid = next( + ( + item + for item in json_records(out) + if item.get("event") == "Invalid worker settings" + ), + {}, + ) + errors = invalid.get("errors") or [] + print(f"{variable}={value}: exit {code}, errors {errors}") + rows.append((f"{variable}={value} exit code", "2", str(code))) + rows.append( + ( + f"{variable} names the field", + "yes", + yes(any(item.get("loc") == field for item in errors)), + ), + ) + rows.append( + ( + f"{variable} hides the value", + "yes", + yes(value not in json.dumps(errors)), + ), + ) + + # подмена окружением: одноразовый контейнер рядом с сервисом + probe = f"{project}-worker-process-{uuid.uuid4().hex[:8]}" + try: + code, _ = detached( + "docker", + "compose", + "run", + "-d", + "--no-deps", + "--name", + probe, + "-e", + "WORKER__CONCURRENCY=3", + "-e", + "WORKER__RECONNECT_SECONDS=1", + "worker", + ) + rows.append(("env override container started", "0", str(code))) + overridden: dict[str, object] = {} + deadline = time.monotonic() + WORKER_LOG_WAIT_S + while time.monotonic() < deadline and not overridden: + _, out = detached("docker", "logs", probe) + overridden = next( + ( + item + for item in json_records(out) + if item.get("event") == "Started worker" + ), + {}, + ) + time.sleep(0.2) + rows.append( + ( + "env override concurrency", + "3", + str(overridden.get("concurrency")), + ), + ) + rows.append( + ( + "env override reconnect_seconds", + "1.0", + str(overridden.get("reconnect_seconds")), + ), + ) + finally: + with signals_ignored(): + detached("docker", "rm", "-f", probe) + + # остановка простаивающего сервиса + started_at = time.monotonic() + code, _ = detached("docker", "compose", "stop", "worker") + took = time.monotonic() - started_at + print(f"docker compose stop worker: {took:.1f} s") + state = subprocess.run( + ["docker", "inspect", "-f", "{{.State.ExitCode}}", worker_id], + capture_output=True, + text=True, + check=False, + ).stdout.strip() + _, out = detached("docker", "logs", worker_id) + last = [ + item + for item in json_records(out) + if item.get("event") in ("Started worker", "Stopped worker") + ] + rows.append(("stop idle: command exit code", "0", str(code))) + rows.append(("stop idle: container exit code", "0", state)) + rows.append( + ( + f"stop idle: under {WORKER_STOP_LIMIT_S} s", + "yes", + yes(took < WORKER_STOP_LIMIT_S), + ), + ) + rows.append( + ( + "stop idle: last record", + "Stopped worker", + str(last[-1].get("event")) if last else "-", + ), + ) + rows.append( + ( + "stop idle: record exit_code", + "0", + str(last[-1].get("exit_code")) if last else "-", + ), + ) + code, _ = detached("docker", "compose", "start", "worker") + rows.append(("docker compose start worker", "0", str(code))) + + # остановка на старте + rows.extend(worker_early_stop(image)) + + # рестарт хранилищ + before = service_containers("worker") + rows.append(("worker running before restart", "yes", yes(bool(before)))) + started_before = before[0]["State"]["StartedAt"] if before else None + rows.append(("scripts/restart.sh", "0", str(guard.run_restart()))) + rows.append(("LB ready after restart", "yes", yes(wait_lb_ready(port)))) + after = service_containers("worker") + rows.append( + ( + "worker StartedAt unchanged", + "yes", + yes( + bool(after) + and after[0]["State"]["StartedAt"] == started_before, + ), + ), + ) + rows.append( + ( + "worker RestartCount", + "0", + str(after[0]["RestartCount"]) if after else "-", + ), + ) + people = attachment_people(port, "wp") + if people is None: + rows.append(("new upload after restart", "ready", "no users")) + return report_reconcile(rows) + _, tokens, chat_id = people + status, _, attachment = upload_ready( + port, + tokens["alice"], + chat_id, + FIXTURE_PNG.read_bytes(), + content_type="image/png", + filename=FIXTURE_PNG.name, + ) + rows.append(("new upload after restart", "202", str(status))) + rows.append( + ( + "new upload becomes ready", + "yes", + yes(isinstance(attachment, dict)), + ), + ) + return report_reconcile(rows, passed="the worker process matches the spec") + + +def worker_early_stop(image: str) -> list[tuple[str, str, str]]: + """`docker stop` во время импорта приложения: контейнер образа без сети + и `config.toml`, как `stop-at-start`. Каждая попытка — код 0 и не дольше + секунды; записи «before startup» нужно увидеть хотя бы раз.""" + rows: list[tuple[str, str, str]] = [] + label = f"{WORKER_EARLY_LABEL}={uuid.uuid4().hex[:8]}" + seen = False + try: + for delay in WORKER_EARLY_DELAYS: + code, out = detached( + "docker", + "run", + "-d", + "--network", + "none", + "--cpus", + "1", + "--memory", + "1g", + "--label", + label, + "--entrypoint", + "python", + image, + "-m", + "src.worker", + ) + if code != 0: + rows.append(("early stop: docker run", "0", str(code))) + break + # в выводе есть и предупреждения Docker о лимитах + found = re.search(r"\b[0-9a-f]{64}\b", out) + if found is None: + rows.append(("early stop: container id", "yes", "no")) + break + container = found.group(0) + time.sleep(delay) + started = time.monotonic() + stop_code, _ = detached( + "docker", + "stop", + "--timeout", + str(WORKER_STOP_LIMIT_S), + container, + ) + took = time.monotonic() - started + state = subprocess.run( + ["docker", "inspect", "-f", "{{.State.ExitCode}}", container], + capture_output=True, + text=True, + check=False, + ).stdout.strip() + _, logs = detached("docker", "logs", container) + events = [str(r.get("event")) for r in json_records(logs)] + early = "Stopped worker before startup" in events + seen = seen or early + print( + f"docker stop after {delay} s: {took:.2f} s, exit {state}, " + f"records {events}", + ) + rows.append( + (f"early stop {delay} s: docker stop", "0", str(stop_code)), + ) + rows.append((f"early stop {delay} s: exit code", "0", state)) + rows.append( + ( + f"early stop {delay} s: within " + f"{WORKER_EARLY_STOP_LIMIT_S:.0f} s", + "yes", + yes(took <= WORKER_EARLY_STOP_LIMIT_S), + ), + ) + finally: + with signals_ignored(): + _, out = detached( + "docker", + "ps", + "-aq", + "--filter", + f"label={label}", + ) + if out.split(): + detached("docker", "rm", "-f", *out.split()) + rows.append(("'Stopped worker before startup' seen", "yes", yes(seen))) + return rows + + def main() -> int: parser = argparse.ArgumentParser(description=__doc__.splitlines()[0]) parser.add_argument("--port", type=int, default=DEFAULT_PORT) @@ -5229,6 +6611,19 @@ def main() -> int: download.add_argument("--attachment", required=True) download.add_argument("--out", help="сохранить полученные байты") download.add_argument("--variant") + download.add_argument( + "--wait", + action="store_true", + help="сначала опрос метаданных до ready или failed", + ) + sub.add_parser("defense-scenario") + broker = sub.add_parser("broker-check") + broker.add_argument( + "--require-test-queue", + action="store_true", + help="код 1 без очереди временной базы (идёт make test_isolated)", + ) + sub.add_parser("worker-process") failover = sub.add_parser("attachment-failover") failover.add_argument("--mode", choices=("stop", "kill"), default="stop") sub.add_parser("attachment-storage") @@ -5338,6 +6733,12 @@ def main() -> int: return cmd_upload(port, args) if args.cmd == "download": return cmd_download(port, args) + if args.cmd == "defense-scenario": + return cmd_defense_scenario(port) + if args.cmd == "broker-check": + return cmd_broker_check(require_test_queue=args.require_test_queue) + if args.cmd == "worker-process": + return cmd_worker_process(port) if args.cmd == "attachment-failover": return cmd_attachment_failover(port, args.mode) if args.cmd == "attachment-storage": diff --git a/.env.example b/.env.example index 43bf1f07..42f3f7c3 100644 --- a/.env.example +++ b/.env.example @@ -1,6 +1,7 @@ # Шаблон .env: `make env_setup` создаёт из него .env и подставляет -# случайные значения в пустые POSTGRES_PASSWORD, VALKEY_PASSWORD и шесть -# секретов S3 (S3_ROOT_*, S3_JWT_SIGNING_KEY, S3_API_*, S3_CLEANER_*). +# случайные значения в пустые POSTGRES_PASSWORD, VALKEY_PASSWORD, +# RABBITMQ_DEFAULT_PASS и секреты S3 (S3_ROOT_*, S3_JWT_SIGNING_KEY, +# S3_API_*, S3_CLEANER_*, S3_WORKER_*). # Существующий .env он не перезаписывает, а дописывает в конец # переменные шаблона, которых в нём нет: секреты — случайными, остальные # — значениями шаблона; печатает только имена. @@ -16,6 +17,11 @@ # MAX_UPLOAD_BYTES, MAX_IMAGE_PIXELS) — в REPORT.md, «Архитектура и # решения». Имена skeleton S3_* буквально не заводятся: S3 настраивают # строки блока S3 ниже. +# С lab5 — BROKER_URL_FILE: [broker] мостами из RABBITMQ_* ниже (значения, а +# не файл); WORKER_CONCURRENCY: [worker] concurrency; JOB_MAX_ATTEMPTS: +# [worker] max_attempts; JOB_TIMEOUT_SECONDS: [worker] job_timeout_seconds; +# STAGING_RETENTION_SECONDS: поля пока нет, появляется с очисткой staging в +# change pipeline-reliability. # порт сервиса ([app] port): на нём слушает приложение, его же # публикует compose, на нём же healthcheck @@ -88,6 +94,11 @@ S3_API_SECRET_KEY= # ними, сервис cleaner ходит с ними в S3; реплики API их не получают S3_CLEANER_ACCESS_KEY= S3_CLEANER_SECRET_KEY= +# ключи пользователя worker (только чтение и запись объектов своего +# bucket): bootstrap заводит пользователя с ними, сервис worker и make +# run_worker ходят с ними в S3; реплики API их не получают +S3_WORKER_ACCESS_KEY= +S3_WORKER_SECRET_KEY= # адрес и порт API S3 внутри сети compose: по ним ходит API в docker, # порт слушает сам сервер и проверяет bootstrap S3_HOST=s3 @@ -101,6 +112,24 @@ S3__PORT=${S3_OUT_PORT} S3__ACCESS_KEY_ID=${S3_API_ACCESS_KEY} S3__SECRET_ACCESS_KEY=${S3_API_SECRET_KEY} +# RabbitMQ — брокер заданий обработки вложений. Пользователя и пароль читает +# и образ брокера: учётная запись создаётся при первом старте на пустом +# volume. Пустой пароль make env_setup заменяет случайным +RABBITMQ_DEFAULT_USER=messenger +RABBITMQ_DEFAULT_PASS= +# адрес и порт AMQP внутри сети compose: по ним ходят API и worker в docker, +# порт слушает сам брокер +RABBITMQ_HOST=rabbitmq +RABBITMQ_PORT=5672 +# порт на 127.0.0.1 хоста, куда публикуется AMQP: к нему подключаются +# приложение и worker в console; другие порты брокера не публикуются +RABBITMQ_OUT_PORT=5673 +# мосты для console: в docker их задаёт environment compose +BROKER__HOST=127.0.0.1 +BROKER__PORT=${RABBITMQ_OUT_PORT} +BROKER__USER=${RABBITMQ_DEFAULT_USER} +BROKER__PASSWORD=${RABBITMQ_DEFAULT_PASS} + # make test_isolated: порт на 127.0.0.1, куда публикуется тестовый # контейнер API TEST_APP_PORT=18088 diff --git a/.github/ci/compose.yml b/.github/ci/compose.yml index 79bdc6da..2cdbdca9 100644 --- a/.github/ci/compose.yml +++ b/.github/ci/compose.yml @@ -35,6 +35,15 @@ services: - source: s3_bootstrap target: /opt/s3/bootstrap.sh + rabbitmq: + ports: !reset [] + # !override: bind mount конфига заменяют configs, volume данных остаётся + volumes: !override + - rabbitmq_data:/var/lib/rabbitmq + configs: + - source: rabbitmq_conf + target: /etc/rabbitmq/conf.d/90-messenger.conf + migrate: image: &ci-image mtusi-messenger:${CI_IMAGE_TAG:?CI_IMAGE_TAG is not set} volumes: !reset [] @@ -52,6 +61,11 @@ services: volumes: !reset [] configs: *config-toml + worker: + image: *ci-image + volumes: !reset [] + configs: *config-toml + haproxy: ports: !reset [] volumes: !reset [] @@ -68,5 +82,7 @@ configs: environment: CI_VALKEY_CONF s3_bootstrap: environment: CI_S3_BOOTSTRAP + rabbitmq_conf: + environment: CI_RABBITMQ_CONF haproxy_cfg: environment: CI_HAPROXY_CFG diff --git a/.github/ci/stand-env.sh b/.github/ci/stand-env.sh index 9845577f..c8ab7cff 100644 --- a/.github/ci/stand-env.sh +++ b/.github/ci/stand-env.sh @@ -10,7 +10,8 @@ CI_CONFIG_TOML="$(cat config.toml)$nl" CI_VALKEY_CONF="$(cat infra/valkey/valkey.conf)$nl" CI_S3_BOOTSTRAP="$(cat infra/s3/bootstrap.sh)$nl" CI_HAPROXY_CFG="$(cat infra/haproxy/haproxy.cfg)$nl" -export CI_CONFIG_TOML CI_VALKEY_CONF CI_S3_BOOTSTRAP CI_HAPROXY_CFG +CI_RABBITMQ_CONF="$(cat infra/rabbitmq/rabbitmq.conf)$nl" +export CI_CONFIG_TOML CI_VALKEY_CONF CI_S3_BOOTSTRAP CI_HAPROXY_CFG CI_RABBITMQ_CONF # готовность стенда через LB: /health/ready отвечает 200 от API_REPLICAS # (из .env, по умолчанию 2) разных реплик — X-Instance-Id. Срок 60 с: diff --git a/AGENTS.md b/AGENTS.md index e413b38c..6736c994 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -11,7 +11,11 @@ RabbitMQ 4 (выбор пользователя), отдельный worker, с оценка 5, трек 1 «Очередь под перегрузкой» (выбор пользователя). Предупреждения о хосте, которые явно не влияют на результат замера, прогон не останавливают (указание пользователя 2026-10-31). Решения, принятые -без пользователя, и открытые вопросы — `QUESTIONS.md`. Код перенесён из +без пользователя, и открытые вопросы — `QUESTIONS.md`. Change +`async-attachments` (уровень 3): загрузка — 202 после staging, задания в +PostgreSQL и подтверждения брокера, worker на образе API, thumbnail, очередь +RabbitMQ 4; следующие — `pipeline-reliability` (4), `track1-queue-overload` +(5). Код перенесён из лабы 4 (репозиторий `mtusi2026lab4-safronov`, ветка `solution/bvt2301-safronov`, commit `2546deb`) по разделу «Переход в следующую лабу»; отчёт и evidence лабы 4 остались в её репозитории. Дальше @@ -175,8 +179,9 @@ structlog (JSON в stdout), redis-py (клиент Valkey), aiobotocore иначе уборщик не стартует) под `FOR UPDATE SKIP LOCKED`, в два шага: пометка строки (`updated_at`) отдельной транзакцией, затем объект и строка одной транзакцией под блокировкой (объект раньше строки); - помеченную строку `mark_ready` в `ready` не переводит, - `ready` уборщик не трогает. У уборщика свой пользователь S3 — только + помеченную строку `mark_queued` в `queued` не переводит, + `queued`, `processing`, `ready` и `failed` уборщик не трогает, удаляет + `staging_key`, а у строки прежней версии `object_key`. У уборщика свой пользователь S3 — только чтение и удаление объектов своего bucket, ключи `S3_CLEANER_*` только у него и bootstrap (`docker.md`, `settings.md`). - Лаба 4, сверка bucket и БД (change `track2-reconciler`, трек 2): её @@ -220,6 +225,17 @@ structlog (JSON в stdout), redis-py (клиент Valkey), aiobotocore Буфер приёма сокетов `api` — 512 KiB (`sysctls`), буфер отправки LB к реплике — 256 KiB, буфер приёма LB от клиента — 128 KiB; `timeout server` пути загрузки 30 с, остальных — 10 с; `ROLLOUT_DRAIN_TIMEOUT` 90 с (`balancer.md`, `docker.md`). +- Лаба 5, фоновая обработка (change `async-attachments`, `worker.md`): ответ 202 + — только после оригинала в staging (`<база>/staging//original`), `queued` с + заданием одной транзакцией и подтверждения брокера; брокер не подтвердил — 503 + и условная отмена. Декодирует и делает варианты только worker + (`python -m src.worker`), реплики API — никогда, Pillow в их процесс не + загружается. Ack — после устойчивого эффекта, повтор — те же ключи, ключ эффекта + `(attachment_id, pipeline_version, variant)`. Брокер и worker не входят в + `/health/ready`, без них работают текст, история, метаданные и готовые байты. + Очередь — `<база>.attachment.process.v1`, durable, сообщения persistent, в них + только id и служебные поля (`contracts/jobs.schema.json`). Разрыв COMMIT и publish + на этом уровне открыт и назван (`KNOWN_ISSUES.md`, `REPORT.md`). - `.env`, `config.toml`, секреты, токены и реальные данные не попадают ни в git, ни в образ. В `evidence/` и `REPORT.md` — только обезличенные выводы команд. @@ -252,7 +268,7 @@ structlog (JSON в stdout), redis-py (клиент Valkey), aiobotocore | `README.md` | задание лабы: рубрика 3/4/5, сценарий и вопросы защиты, что приложить к PR | | `COURSE.md` | карта семи лаб, три объявленных перехода API (1→2, 2→3, 4→5), правила честных измерений | | `contracts/openapi.json` | нормативный OpenAPI 3.1: пути, схемы, коды ответов | -| `contracts/README.md` | нормативная семантика: формат ошибок, валидация, пагинация, Basic → Bearer-сессии, TTL и отзыв, с lab3 — `Idempotency-Key` и `X-Instance-Id`, с lab4 — вложения: сырые bytes PNG/JPEG ≤10 MiB и ≤40 млн пикселей, `201 Attachment` (`ready`), `attachment_ids` в сообщении, download только участникам; пустой текст (в том числе из пробелов) — только с вложением (согласование 2026-10-20); разделы lab5+ — на будущее; как это сделано — `api-contract.md`, «Вложения (лаба 4)» | +| `contracts/README.md` | нормативная семантика: формат ошибок, валидация, пагинация, Basic → Bearer-сессии, TTL и отзыв, с lab3 — `Idempotency-Key` и `X-Instance-Id`, с lab4 — вложения: сырые bytes PNG/JPEG ≤10 MiB и ≤40 млн пикселей, на лабе 4 `201 Attachment` (`ready`), с лабы 5 — `202` (`queued`), `attachment_ids` в сообщении, download только участникам; пустой текст (в том числе из пробелов) — только с вложением (согласование 2026-10-20); разделы lab5+ — на будущее; как это сделано — `api-contract.md`, «Вложения (лаба 4)» | | `contracts/examples.json`, `infrastructure.json` | примеры тел (проверяет `make validate`); роли инфраструктуры лабы: api ×2+ без локального состояния, postgres, load_balancer, s3 (одно из MinIO, SeaweedFS, RustFS; приватный bucket, persistent volume); Redis/Valkey — необязательно; внутренние порты реплик в обход LB не публикуются | | `lab.json` | номер лабы (5); по нему `tests/client.py` выбирает профиль (с лабы 2 — Basic при входе, дальше Bearer; с лабы 3 — идемпотентность; с лабы 4 — вложение, 201 вместо 202 с лабы 5) | | `tests/smoke.py`, `tests/client.py` | публичный сквозной сценарий `make test`; с лабы 4 — загрузка `tests/fixtures/sample.png`, сообщение с `attachment_ids`, SHA-256 скачанного оригинала, 404 постороннему; что он проверяет и чего нет — `tests/README.md` | @@ -298,6 +314,7 @@ structlog (JSON в stdout), redis-py (клиент Valkey), aiobotocore | `docker.md` | `Dockerfile`, `docker-compose.yml`, `.dockerignore`, `scripts/restart.sh`, `infra/**`, `.github/ci/**`, `.github/workflows/application.yml`: мультистейдж, non-root, пины, healthcheck, стенд compose, S3 и bootstrap, секреты по сервисам, volumes, restart hook | | `balancer.md` | `docker-compose.yml`, `infra/haproxy/**`, `scripts/stop-one.sh`, `scripts/rolling-update.sh`: реплики за HAProxy, проверки и цепочка таймаутов, повторы LB, failover hook, поочерёдная замена, лимиты и пулы (с лабы 3) | | `student-tests.md` | `student-tests/**`: обязательные проверки уровня 4, black-box по HTTP, особый стенд | + | `worker.md` | `src/worker/**`, `src/core/services/attachment_processing.py`, `src/utils/thumbnail.py`: процесс worker, ack и повторы, счёт попыток, thumbnail | | `bench.md` | `bench/**`: нагрузочный стенд на Postgres (проект compose `mtusi-bench`), что не меняется между метками замеров, граница чёрного ящика и планы запроса, сравнение меток, коммиты измеренных состояний | | `migrations.md` | `migrations/**`, `alembic.ini`, `src/infra/db/models/**`: схема до запросов, ограничения, индексы, повторный запуск миграций | @@ -409,6 +426,11 @@ structlog (JSON в stdout), redis-py (клиент Valkey), aiobotocore | `docker compose run --rm --no-deps cleaner --once` | разовый проход уборщика незавершённых загрузок (grace — `[cleaner]` или `-e CLEANER__PENDING_GRACE_SECONDS=…`, не меньше 18 с): 0 — проход дошёл до конца, 1 — прерван отказом, 2 — неверная конфигурация; журнал сервиса — `docker compose logs --no-log-prefix cleaner` | | `make lb_stats` | слоты HAProxy: адрес, состояние проверки (`DRAIN`, `MAINT` при замене), запросы, повторы, перенаправления (CSV статистики изнутри контейнера LB) | | `make rolling_update [COMMIT=...] [MIGRATE=0]` | поочерёдная замена реплик без простоя (`scripts/rolling-update.sh`, `balancer.md`): сборка из рабочего дерева (или файлов `COMMIT` через `git archive`), миграции один раз, затем по одной — новая `healthy` и `UP` в LB, старая `drain` → запросов в полёте 0 → `maint` → stop → rm → слот `ready`. Нужен штатный стенд (`make replicas`) без слотов LB в ручном `drain` / `maint` (иначе код 2 и команда `set server … state ready`); сбой и Ctrl+C — `API_REPLICAS` готовых реплик, повтор доводит; `MIGRATE=0` — откат на прежний образ (после него `docker compose up` без сборки не запускать: `migrate` прежнего образа упадёт на новой ревизии) | +| `make run_worker` | worker в консоли (`python -m src.worker`, тот же `.env`, ключи `S3_WORKER_*` в окружении процесса, рецепт без эха); рядом с `make run_dev` | +| `make start_broker` / `make stop_broker` | брокер стенда: `up -d --wait rabbitmq` / `stop rabbitmq` | +| `driver.py --port defense-scenario` | сценарий защиты на рабочем стенде: worker остановлен → 202 → сообщение 201 → 409 → текст 201 → `scripts/restart.sh` → worker → `ready`, оригинал и thumbnail; `id` и `StartedAt`, worker запускается при любом исходе; `evidence/attachments/defense.md` | +| `driver.py --port broker-check [--require-test-queue]` | образ и digest, volume, порт, предел памяти, очередь, остановка брокера; `evidence/broker/stand.md`, `evidence/broker/isolated.md` | +| `driver.py --port worker-process` | PID 1, лимиты, остановка, неверные `WORKER__*`, рестарт хранилищ; `evidence/worker/process.md` | | `make start_db` / `make stop_db` | Postgres стенда: `up -d --wait postgres` / `stop postgres` | | `make start_cache` / `make stop_cache` | Valkey стенда: `up -d --wait valkey` / `stop valkey`; volume нет, кэш после рестарта пуст | | `make start_s3` / `make stop_s3` | S3 стенда: `up -d --wait s3`, затем `up --no-deps --exit-code-from s3-bootstrap s3-bootstrap` (код bootstrap — код цели: `--wait` одноразовый сервис не ждёт) / `stop s3` | @@ -418,7 +440,7 @@ structlog (JSON в stdout), redis-py (клиент Valkey), aiobotocore | `make wipe_data` | `down -v` — удалить данные стенда (volumes Postgres и S3 называются в запросе) и кэш; только после ввода `yes` | | `make test_isolated [KEEP_TEST_DB=1]` | образ на временной базе `test_` с Valkey и S3 стенда (ключи кэша и объектов разделены именем базы): сборка, миграции, отдельный контейнер API на `TEST_APP_PORT`, `make test` + `make student_test EXPECT_REPLICAS=1` (тесты реплик пропускаются с причиной), уборка при любом исходе — база и объекты под префиксом `test_/` (`student-tests.md`) | | `make student_test [BASE_URL=...] [EXPECT_REPLICAS=...]` | собственные тесты `student-tests/` (pytest) против запущенного сервера, кроме проверок отказов (`-m 'not fault'`); `EXPECT_REPLICAS` (по умолчанию `API_REPLICAS`) — сколько реплик за `BASE_URL`, против одного процесса — 1; сервер недоступен — код 2 и одна строка с адресом | -| `make failure_checks [FAULT_ARGS=...]` | проверки отказов (`pytest -m fault`, 56 проверок, ~15 мин) на отдельном стенде: проект `<рабочий>-failures` со своими Postgres, Valkey и S3 (с bootstrap), уборщик (grace 20 с, интервал 1 с), четыре API — обычный, «тесный» (срок 2 с, пул 1), «узкий по загрузкам» и «с коротким сроком S3» (1 с), hook `student-tests/fault_hook.py`; после тестов — журнал PostgreSQL стенда: сводка (`crash markers`, «too many clients», «administrator command») и ненулевой код при признаках аварийного перезапуска; стенд и его volumes удаляются при любом исходе, рабочий не трогается (`student-tests.md`) | +| `make failure_checks [FAULT_ARGS=...]` | проверки отказов (`pytest -m fault`, 99 проверок, ~22 мин) на отдельном стенде: проект `<рабочий>-failures` со своими Postgres, Valkey и S3 (с bootstrap), уборщик (grace 20 с, интервал 1 с), четыре API — обычный, «тесный» (срок 2 с, пул 1), «узкий по загрузкам» и «с коротким сроком S3» (1 с), hook `student-tests/fault_hook.py`; после тестов — журнал PostgreSQL стенда: сводка (`crash markers`, «too many clients», «administrator command») и ненулевой код при признаках аварийного перезапуска; стенд и его volumes удаляются при любом исходе, рабочий не трогается (`student-tests.md`) | | `make bench [BENCH_LABEL=...]` | полная матрица 10k / 100k / 500k читаемого чата плюс 100 000 сообщений в 1 110 фоновых чатах разного размера (~35 мин, оценка по `bench_quick`) на своём проекте compose `mtusi-bench` (HAProxy и одна реплика API, Postgres, Valkey с лимитами, без портов хоста и без `.env` рабочего стенда; k6 ходит через LB); на каждый размер — свежий стенд, `VACUUM (ANALYZE)`, планы запроса истории (`auto_explain`) по уровням чатов с вариантами индекса и запроса, в конце — пробы стоимости записи по вариантам. Результаты в `evidence/bench/<метка>/`, занятая метка — отказ. Перед запуском — подготовка хоста (`bench.md`) | | `make bench_quick` | самопроверка стенда на 1k / 5k / 10k и 3 500 фоновых сообщений (~3 мин), метка `quick-<время>`, в git не идёт | | `make bench_restore [RESTORE_LABEL=...]` | трек 2, восстановление (~20 мин, метка `restore` по умолчанию): тот же стенд и данные, без матрицы прогонов; на каждый размер — `pg_dump` во время записи через HTTP, активность после backup, `pg_restore -j` в новый контейнер Postgres на новом volume, сверка обеих баз построчно, переключение API, проверки через HTTP до и после `FLUSHALL`; время dump / restore / RTO и потерянные сообщения — в `summary.md` | @@ -450,6 +472,8 @@ structlog (JSON в stdout), redis-py (клиент Valkey), aiobotocore src/ __main__.py # python -m src: early_stop.install() до импорта приложения → main.main() main.py # FastAPI app: lifespan, middlewares, обработчики ошибок, uvicorn.run + worker/__main__.py # python -m src.worker: early_stop.install("worker") до импорта → main(); неверные настройки — запись без значений и код 2; os._exit в конце + worker/main.py # worker обработки вложений: свои engine, S3 и брокер; цикл соединений с паузой, задачи доставок с prefetch = concurrency, ack / requeue / drop по итогу, SIGTERM — начатые ждут в срок cleaner/__main__.py # python -m src.cleaner [--once]: early_stop.install("cleaner") до импорта → main(); неверные настройки — запись без значений и код 2 cleaner/main.py # уборщик незавершённых загрузок: проверка grace > 2 × request_timeout + s3 timeout (иначе код 2), свой engine и клиент S3, цикл с интервалом и плановой сверкой (при старте и раз в [reconciler] interval_seconds), SIGTERM — довести текущий шаг и выйти 0, --once — коды 0/1/2; reconcile [--apply] [--max-changes N] [--strategy batch|head] [--deep] [--max-objects-per-second R] — разовая сверка, коды 0/3/1/2; плановая — batch, поверхностная, предел скорости из настроек config/settings.py # Settings (pydantic-settings), экземпляр settings; [app] instance_id (пусто → hostname) и keep_alive_seconds, [database] pool_size 10 и max_overflow 0 (постоянный пул без переполнения), idle_in_transaction_timeout_ms, [s3] адрес, bucket (валидатор имени), ключи API, регион, сроки, пул и endpoint_url, [idempotency] ttl_seconds, [uploads] max_concurrent 4, max_waiting 16, wait_timeout_seconds 5, body_timeout_seconds 30 (места загрузок процесса API), [cleaner] interval_seconds 60, pending_grace_seconds 900, batch_size 100, [reconciler] interval_seconds 3600, page_size 1000, max_changes 100, max_objects_per_second 2000 (предел скорости сверки; 0 — без него) @@ -464,11 +488,14 @@ src/ repos/.py # атомарный доступ к хранилищу, модульные функции repos/idempotency.py # ключ идемпотентности: захват ON CONFLICT DO UPDATE WHERE просрочен, чтение сохранённого результата repos/chat_cache.py # карточка чата в Valkey: ключ с именем базы, JSON ↔ ChatFullDTO - repos/attachment.py # строки вложений: вставка pending (created_at = updated_at), mark_ready (pending и непомеченная → ready RETURNING), чтение одной и до 10; уборщику — get_stale_pending (keyset по частичному индексу), lock_stale_pending (FOR UPDATE SKIP LOCKED), mark_removing (пометка updated_at), delete_attachment; сверке — get_attachments_for_objects (id = ANY OR object_key = ANY), get_ready_page (keyset ready по id), find_attachment_reference, mark_lost / clear_lost (условный UPDATE lost_at) - repos/attachment_object.py # оригинал в S3: ключ <база>/attachments//original, put_original (поток BytesIO и size, без копии тела), open, delete_original; сверке — originals_prefix, is_own_key (ключ под префиксом вложений своей базы), parse_original_key, list_originals, probe_originals (bucket на месте), head_original + repos/attachment_job.py # задание вложения: вставка, lock_job FOR UPDATE, start_attempt, return_to_queued своей попытки, finish_job, mark_published, delete_unstarted (queued и attempt 0) + repos/attachment_variant.py # варианты: вставка ON CONFLICT DO NOTHING по ключу эффекта, варианты вложения, один по имени + repos/attachment.py # строки вложений: вставка pending (created_at = updated_at), mark_queued (pending и непомеченная → queued RETURNING), return_to_pending, mark_processing, return_to_queued, commit_ready, commit_failed, чтение одной и до 10; уборщику — get_stale_pending (keyset по частичному индексу), lock_stale_pending (FOR UPDATE SKIP LOCKED), mark_removing (пометка updated_at), delete_attachment; сверке — get_attachments_for_objects (id = ANY OR object_key = ANY), get_ready_page (keyset ready по id), find_attachment_reference, mark_lost / clear_lost (условный UPDATE lost_at) + repos/attachment_object.py # объекты в S3: staging_key <база>/staging//original, variant_key и parse_variant_key <база>/attachments//v-<имя>, оригинал <база>/attachments//original, put_original (поток BytesIO и size, без копии тела), open, delete_original; сверке — originals_prefix, is_own_key (ключ под префиксом вложений своей базы), parse_original_key, list_originals, probe_originals (bucket на месте), head_original repos/message.py # MESSAGE_COLUMNS с ARRAY(подзапрос attachment_ids по position), вставка связей одной вставкой services/.py # Service: логика, проверки доступа, id и время, логи; чаты и сообщения — с кэшем; отправка — ключ, сообщение и связи с вложениями одной транзакцией - services/attachment.py # AttachmentService(db_scope, cache, storage, slots): загрузка (проверки → место загрузки, 429 → тело со счётчиком и сроком в BytesIO, 400 по сроку → структура и SHA-256 в потоке над getvalue() → del → pending → PUT тем же BytesIO → ready; сбой ready до COMMIT или пропавшая строка — удаление объекта и 503; место — до ответа), метаданные, отдача потоком + services/attachment.py # AttachmentService(db_scope, cache, storage, slots, publisher): загрузка (проверки → место загрузки, 429 → тело со счётчиком и сроком в BytesIO, 400 по сроку → структура и SHA-256 в потоке над getvalue() → del → pending → PUT в staging тем же BytesIO → queued и задание; сбой до COMMIT или пропавшая строка — удаление объекта и 503 → публикация с подтверждением, published_at; отказ брокера — условная отмена и 503; место — до ответа), метаданные с вариантами, отдача потоком + services/attachment_processing.py # AttachmentProcessingService: разбор сообщения, claim, GET staging и сверка, PUT оригинала, thumbnail в потоке, PUT варианта, фиксация ready одной транзакцией; временные ошибки — queued и новое сообщение, постоянные — failed; JobOutcome services/attachment_cleanup.py # AttachmentCleanupService(db_scope, storage): проход уборщика — кандидаты keyset, каждая строка в два шага (remove_stale_pending): блокировка и пометка (commit) → блокировка, DELETE объекта и DELETE строки (commit); отказ S3 или БД прерывает проход, SIGTERM — после текущего шага; CleanupPassDTO services/attachment_reconcile.py # AttachmentReconcileService(db_scope, storage): сверка bucket и БД — S3 → БД (страницы списка, выборка на страницу, множество ключей), БД → S3 (keyset ready; ключ строки вне префикса вложений — чужой объект без HEAD; строка с ключом /original другого вложения — HEAD её объекта, verify W2), зависшие, перепроверка в БД и HEAD (bucket — probe), сигнал — перед каждым вызовом хранилища, предел изменений, действия с apply (зависшие шагом уборщика → объекты без строки → пометки → снятия); журнал Found / Fixed / Finished; ReconcilePassDTO. С change track2-reconcile-cost: strategy head (выборка строки на объект, HEAD на строку, без множества), deep (GET и SHA-256 потоком, checksum_mismatch; «оригинал вернулся» — тот же SHA-256), предел скорости после каждого вызова S3 (_pace, куски 0,2 с; сигнал прекращает паузу, останавливает следующий check_stop — verify W1), ранний отказ по пределу (unchecked), счёт сеансов обёрткой db_scope, стоимость в итоге (storage_objects, s3_requests, read_bytes, db_sessions, phase_ms) exceptions/.py # доменные исключения, реэкспорт в __init__.py; storage.py — ObjectStorageUnavailable (503) и StoredObjectMissing; attachment.py — 404, 413, 415, 400 обрыва и срока тела (UploadTimedOut), 429 занятых мест (UploadsBusy), 500 пропавшего объекта @@ -476,6 +503,8 @@ src/ early_stop.py # ранний обработчик SIGTERM/SIGINT (только stdlib): до старта сервера — запись «Stopped <процесс> before startup» (API, cleaner) и выход 0; disarm() — первая строка lifespan; write_record — запись мимо structlog logger.py # structlog, get_logger(), contextvar-ы request_id / user_id, instance_id в каждой записи password.py # Argon2id в потоке со своим лимитом, фиктивный хэш для неизвестного username + broker/client.py # aio-pika: JobPublisher (соединение лениво, confirm и срок на всё, сброс после любой ошибки, BrokerUnavailable), JobConsumer (своё соединение, prefetch), JobDelivery, queue_name <база>.attachment.process.v1 + broker/instance.py # глобал job_publisher процесса API; импортируют main.py и dependencies.py upload_slots.py # UploadSlots (asyncio.Semaphore по порядку прихода, счётчик ожидающих, срок ожидания; slot() — UploadsBusy или ожидание в мс, место в finally) и глобал upload_slots из [uploads]; импортирует только dependencies.py db/engine.py # фабрики engine и сессий, BoundedCloseConnection, ping db/session.py # глобалы engine и session_factory процесса API @@ -487,9 +516,11 @@ src/ s3/client.py # create_object_storage (aiobotocore: path-адресация, без повторов, пул), ObjectStorage: put (поток read/seek/tell и size) / head / open (чтение блоками) / delete / list_page (ListObjectsV2 по префиксу, нет bucket — ошибка), срок на вызов и блок — единственный срок клиента (read_timeout aiohttp выключен: переживал ответ и портил соединение в пуле, change fix-upload-put-flake), ошибки → ObjectStorageUnavailable / StoredObjectMissing; StoredObjectInfo (с last_modified, у open — тоже), StoredObject, StoredObjectPage; счётчики попыток по операциям, ключей списка и прочитанных байт — stats() → StorageStats (change track2-reconcile-cost) s3/instance.py # глобал object_storage процесса API, namespace — имя базы; start() и aclose() в lifespan schemas/ + jobs/attachment.py # AttachmentJobMessage (pydantic по contracts/jobs.schema.json) и build_job_body dataclasses/.py # DTO между repo → service → api enums/.py # StrEnum доменов, RunModeEnum; attachment.py — AttachmentStatus, ImageType, ReconcileFinding, ReconcileAction, ReconcileStrategy (batch, head) utils/ + thumbnail.py # render_thumbnail: JPEG 256 × 256, размер вниз своим расчётом, EXIF orientation, alpha на белый, InvalidImage; импортирует Pillow, поэтому только сервис обработки constants.py # лимиты контракта (с лабы 4 — 10 MiB, 40 млн пикселей, filename, 10 вложений), размер страницы, префиксы путей, имя bucket S3, разделитель и части ключа объекта, keep-alive клиента S3 image.py # inspect_image: структурная проверка PNG/JPEG без декодирования пикселей (stdlib), тип, размеры, UnsupportedImage / DamagedImage / TooManyPixels; у JPEG ещё таблицы DQT/DHT, компоненты и полоса скана, определённые к скану таблицы (0 и 1 Хаффмана непрогрессивного кадра — необязательны), данные скана Хаффмана — условия отказа djpeg utc.py # utcnow() (aware UTC), формат RFC 3339 с Z @@ -499,6 +530,7 @@ student-tests/ # black-box тесты по HTTP (уровень 4) api_client.py # Api поверх httpx; Actor.headers() — единственное место идентификации; post_message/send_message (с attachment_ids) — с Idempotency-Key; post_attachment/upload, attachment_meta, attachment_content, attachment_content_slowly (потоком с паузой после блока) contract.py # тела по схемам contracts/openapi.json, форматы id, attachment_ids и времени, X-Instance-Id, assert_error (с 413, 415 и 429 — Retry-After положительное целое), assert_errors (статусы всех вариантов запроса разом), assert_content (байты, тип, nosniff, без Location и x-amz-*), assert_replicas images.py # изображения для тестов: PNG на stdlib (любые IHDR, Adam7, точный размер, бомба, огромные размеры, порча байта, шум RGB ~1 MiB от зерна — png_noise), JPEG через Pillow (dev): разновидности, подмена размеров, без таблиц, изменённый заголовок скана и пустой скан (jpeg_undecodable); обрезка и хвост + test_attachment_processing.py # спек attachment-processing по HTTP: готовность, thumbnail, варианты, failed от недекодируемого JPEG test_attachments.py # спек attachments: загрузка, лимиты, тип и целостность, filename, доступ, метаданные, оригинал, variant, повтор, 10 одновременных загрузок, другая реплика test_idempotency.py # спек idempotency: ключ, повтор, 409, область, порядок кодов, повтор через другую реплику (гонка — test_race.py, отказы — test_failures.py) test_load_balancing.py # спек load-balancing (вне сверки покрытия): одна сессия на разных репликах, запись видна через другую реплику @@ -529,7 +561,8 @@ bench/ # нагрузочный стенд на HAProxy + migrations/, alembic.ini # ревизии alembic, async env.py; применяет одноразовый сервис compose; 739b8f04d5fb — частичный индекс pending CONCURRENTLY в autocommit_block; 5c3e1f0a9b7d — attachments.lost_at (NULL, SET LOCAL lock_timeout) infra/ # конфигурации сервисов стенда; README.md — skeleton valkey/valkey.conf # лимит памяти и LRU, persistence выключен - s3/bootstrap.sh # bootstrap S3 (сервис s3-bootstrap, network_mode: service:s3): apply — bucket, анонимный доступ none, политики api-objects и cleaner-objects (у уборщика — ещё список только с префиксом S3_CLEANER_LIST_PREFIX = <база>/attachments/), пользователи api и cleaner с ключами из .env, проверки приватности обоих ключей; check (и строки ключа уборщика) и cleanup — для make s3_check; секреты — stdin weed shell и файл curl на tmpfs + rabbitmq/rabbitmq.conf # предел памяти брокера 400 МиБ: лимит контейнера он не видит + s3/bootstrap.sh # bootstrap S3 (ещё пользователь worker: чтение и запись объектов; сервис s3-bootstrap, network_mode: service:s3): apply — bucket, анонимный доступ none, политики api-objects и cleaner-objects (у уборщика — ещё список только с префиксом S3_CLEANER_LIST_PREFIX = <база>/attachments/), пользователи api и cleaner с ключами из .env, проверки приватности обоих ключей; check (и строки ключа уборщика) и cleanup — для make s3_check; секреты — stdin weed shell и файл curl на tmpfs haproxy/haproxy.cfg # LB рабочего стенда и bench/: реплики через DNS Docker (8 слотов), проверки /health/ready (inter, fastinter, формулы обнаружения), цепочка таймаутов, http-reuse never (простаивающее соединение закрывает LB), повтор только на conn-failure, ответы LB в формате контракта (400, 502, 503, 504), timeout server 30 с пути загрузки (set-timeout, остальные 10 с), tune.sndbuf.server 256 KiB и tune.rcvbuf.client 128 KiB, мониторинг :8404, runtime API на 127.0.0.1:9999 внутри контейнера (drain / maint / ready при замене) scripts/restart.sh # restart hook для make test-persistence, по restart.example.sh: LB, все реплики api, postgres, valkey, s3 (~25 с); ожидание хранилищ — up --wait --no-recreate (Compose 5.4 иначе пересоздаёт контейнеры, чьи образы скачивались при первом up, и s3-bootstrap не стартует); start api повторяет migrate и s3-bootstrap (no-op); уборщика не трогает — рестарт хранилищ он переживает сам scripts/stop-one.sh # failover hook для make test-failover: TARGET_INSTANCE_ID → реплика api этого проекта, STOP_MODE stop или kill, STOP_ONE_LOG @@ -538,7 +571,9 @@ Dockerfile # builder (uv sync --locked) → runtime: .venv + s docker-compose.yml # проект mtusi-lab5: postgres, valkey, s3 (SeaweedFS, служебное на loopback, API S3 на 127.0.0.1:S3_OUT_PORT), migrate, s3-bootstrap, api × API_REPLICAS без портов (sysctls: буфер приёма сокетов до 512 KiB), cleaner (уборщик: точка входа python -m src.cleaner, пул 1, ключи S3_CLEANER_*, без healthcheck), haproxy — единственный порт API; адреса и порты из .env, volumes postgres_data и s3_data, лимиты у всех, окружение и секреты по сервисам (x-db-env, x-cache-env, x-s3-env, x-s3-api-keys-env) .dockerignore config_example.toml, .env.example -evidence/attachments/ # change attachments: smoke.md, failover.md (driver.py attachment-failover stop и kill), storage.md (driver.py attachment-storage), slow-transfer.md (10 MiB через LB дольше 6 с); change upload-consistency: consistency.md (driver.py upload-consistency и журналы API и уборщика), cleaner-process.md (старт, отказ конфигурации, остановка, окно 0, рестарт хранилищ, отказ S3 во время прохода); по замечанию ревьюера: jpeg-structure.md (варианты JPEG — прежняя и новая проверка, Pillow, djpeg; регрессия на 301 JPEG; время; красный и зелёный прогоны test_undecodable_jpeg) +evidence/broker/ # change async-attachments: stand.md (driver.py broker-check), isolated.md (очередь временной базы) +evidence/worker/ # change async-attachments: process.md (driver.py worker-process), logs.md (журнал задания) +evidence/attachments/ # change async-attachments: defense.md (driver.py defense-scenario); change attachments: smoke.md, failover.md (driver.py attachment-failover stop и kill), storage.md (driver.py attachment-storage), slow-transfer.md (10 MiB через LB дольше 6 с); change upload-consistency: consistency.md (driver.py upload-consistency и журналы API и уборщика), cleaner-process.md (старт, отказ конфигурации, остановка, окно 0, рестарт хранилищ, отказ S3 во время прохода); по замечанию ревьюера: jpeg-structure.md (варианты JPEG — прежняя и новая проверка, Pillow, djpeg; регрессия на 301 JPEG; время; красный и зелёный прогоны test_undecodable_jpeg) evidence/s3/ # change s3-storage: bootstrap.md (первый запуск, повтор, смена секрета, ошибка шага, до bootstrap), privacy.md (make s3_check, нарушение и исправление, порты, секреты по сервисам), grpc-admin.md (gRPC шлюза без токена), restart.md (restart.sh и SIGKILL S3), client.md (операции, pause/stop, неверный секрет, журнал), memory.md (20 × 10 MiB PUT); change upload-consistency: cleaner-key.md (пользователь уборщика в bootstrap, смена секрета, make s3_check с ключом уборщика, секреты по сервисам); change track2-reconciler: cleaner-list.md (bootstrap с политикой списка по префиксу, неверный префикс, make s3_check со строками списка уборщика, окружение s3-bootstrap) evidence/reconcile/ # change track2-reconciler: cycle.md (driver.py reconcile-cycle), stress.md (driver.py reconcile-stress), service.md (Started cleaner с параметрами сверки, плановая сверка при старте, docker stop во время сверки при pause s3, код 1 разового прохода по сигналу — driver.py reconcile-signal, отказ старта на RECONCILER__*, коды 3 и 0; с change track2-reconcile-cost — остановка во время паузы предела скорости, driver.py reconcile-signal --pace) evidence/reconcile/<метка>/ # результаты make bench_reconcile (change track2-reconcile-cost): meta.json (раздел reconcile: план, этапы и модели, commit и образы «до», аргументы S3), passes.csv, windows.csv, summary.md (H1–H4 и S4), cost-by-n.svg, requests-by-n.svg, background-p95.svg, raw/ (записи уборщика по проходам, итог k6 блока H4) @@ -581,7 +616,7 @@ KNOWN_ISSUES.md # найденные попутно дефекты, настройки (`src/config/` вместо `src/data/`) и HTTP-модели (`src/api/schemas/` вместо `schemas/pydantic/`). В `core/` остались доменные слои: repos, services, exceptions. Бота, loader и контроллера - нет; фоновая работа появится в лабе 5 отдельным worker. + нет; фоновая работа с лабы 5 — отдельный worker (`src/worker/`). - Ошибки: сервис бросает доменное исключение. `src/api/errors.py` одной таблицей переводит его в статус и `code` и отдаёт тело `{"error": {...}}` с `request_id`. `HTTPException` в сервисах и ручках @@ -638,7 +673,7 @@ KNOWN_ISSUES.md # найденные попутно дефекты, - Переносить: `src/`, `student-tests/`, `migrations/`, `alembic.ini`, `Dockerfile`, `docker-compose.yml`, `infra/valkey/`, - `infra/haproxy/`, `infra/s3/` (без `infra/README.md` skeleton), свои + `infra/haproxy/`, `infra/s3/`, `infra/rabbitmq/` (без `infra/README.md` skeleton), свои `scripts/restart.sh`, `scripts/stop-one.sh` и `scripts/rolling-update.sh` (без примеров и проверок skeleton в `scripts/`), `pyproject.toml`, `uv.lock`, `.python-version`, diff --git a/KNOWN_ISSUES.md b/KNOWN_ISSUES.md index 536aa4cb..91d7e048 100644 --- a/KNOWN_ISSUES.md +++ b/KNOWN_ISSUES.md @@ -3,6 +3,32 @@ Найдены попутно, не исправлены без отдельной просьбы (AGENTS.md). Исправленные удаляются отсюда, история — в git. +## Разрыв COMMIT и publish: `queued` без сообщения + +- **Где:** `src/core/services/attachment.py`, `_store` → `_publish_job` + (design change `async-attachments`, решение 3). +- **Что:** если процесс API умер между фиксацией `queued` с заданием и + подтверждением брокера, либо PostgreSQL отказал в транзакции отмены, вложение + остаётся `queued` с заданием без `published_at`, и никто его не публикует. + Клиент 202 не получил, поэтому принятая работа не теряется, но строка и объект + staging висят, а `id` никому не известен. +- **Как увидеть:** `SELECT id FROM attachment_jobs WHERE state = 'queued' AND + published_at IS NULL`. +- **Предложение:** relay в change `pipeline-reliability` (outbox на этой же + таблице). Внедрённого сбоя на этом уровне нет: это предмет проверки уровня 4. + +## Смесь версий при замене реплик на первый релиз с обработкой + +- **Где:** `make rolling_update` с прежней версии (design change + `async-attachments`, решение 14), `AttachmentStatus` прежнего образа. +- **Что:** на время замены прежняя реплика отвечает 201 `ready` и даёт 500 на + чтении строки нового статуса (`ValueError` в `_to_dto`), а новая — 202. То же + после отката: незавершённые `queued` и `processing` дают 500 на прежней версии. +- **Чем грозит:** окно замены ограничено, переход 201 → 202 всё равно несовместим + для клиента на это окно; названо в `REPORT.md`. +- **Предложение:** не лечить: объявленный переход контракта. Новые статусы в + будущих версиях добавлять так, чтобы прежняя версия читала строку. + ## Bootstrap после удаления bucket на маленьком диске: «api key wait (code 500)» - **Где:** `infra/s3/bootstrap.sh` (режим `apply`) и сервер `s3` diff --git a/Makefile b/Makefile index da857510..de7a7a50 100644 --- a/Makefile +++ b/Makefile @@ -37,9 +37,15 @@ test-failover: # Postgres из compose и миграции, Valkey и S3 с bootstrap из compose, # затем сервис на хосте: 127.0.0.1:APP__PORT, reload по src/ .PHONY: run_dev -run_dev: upgrade start_cache start_s3 +run_dev: upgrade start_cache start_s3 start_broker APP__RUN_MODE=console uv run python -m src +# worker в консоли: тот же .env, адреса на хосте; ключи worker — в окружение +# процесса (мост S3__* в .env — ключи API). @: значения в вывод не попадают +.PHONY: run_worker +run_worker: + @S3__ACCESS_KEY_ID="$(S3_WORKER_ACCESS_KEY)" S3__SECRET_ACCESS_KEY="$(S3_WORKER_SECRET_KEY)" APP__RUN_MODE=console uv run python -m src.worker + # шаблоны копируются только если файла ещё нет: локальные значения # не затираются. В .env подставляются случайные пароли Postgres и # Valkey и секреты S3: в шаблоне они пустые, общего секрета стенда в git @@ -47,7 +53,7 @@ run_dev: upgrade start_cache start_s3 # нет (секреты — случайными, остальные — значениями шаблона), прежние # строки не меняются (design change upload-consistency). Печатаются # только имена, значения — нет -ENV_SECRETS = POSTGRES_PASSWORD VALKEY_PASSWORD S3_ROOT_ACCESS_KEY S3_ROOT_SECRET_KEY S3_JWT_SIGNING_KEY S3_API_ACCESS_KEY S3_API_SECRET_KEY S3_CLEANER_ACCESS_KEY S3_CLEANER_SECRET_KEY +ENV_SECRETS = POSTGRES_PASSWORD VALKEY_PASSWORD RABBITMQ_DEFAULT_PASS S3_ROOT_ACCESS_KEY S3_ROOT_SECRET_KEY S3_JWT_SIGNING_KEY S3_API_ACCESS_KEY S3_API_SECRET_KEY S3_CLEANER_ACCESS_KEY S3_CLEANER_SECRET_KEY S3_WORKER_ACCESS_KEY S3_WORKER_SECRET_KEY # шаблон с подставленными секретами — в поток, не в вывод команды ENV_FILLED = sed \ -e "s/^POSTGRES_PASSWORD=$$/POSTGRES_PASSWORD=$$(openssl rand -hex 16)/" \ @@ -59,6 +65,9 @@ ENV_FILLED = sed \ -e "s/^S3_API_SECRET_KEY=$$/S3_API_SECRET_KEY=$$(openssl rand -hex 20)/" \ -e "s/^S3_CLEANER_ACCESS_KEY=$$/S3_CLEANER_ACCESS_KEY=$$(openssl rand -hex 10)/" \ -e "s/^S3_CLEANER_SECRET_KEY=$$/S3_CLEANER_SECRET_KEY=$$(openssl rand -hex 20)/" \ + -e "s/^S3_WORKER_ACCESS_KEY=$$/S3_WORKER_ACCESS_KEY=$$(openssl rand -hex 10)/" \ + -e "s/^S3_WORKER_SECRET_KEY=$$/S3_WORKER_SECRET_KEY=$$(openssl rand -hex 20)/" \ + -e "s/^RABBITMQ_DEFAULT_PASS=$$/RABBITMQ_DEFAULT_PASS=$$(openssl rand -hex 16)/" \ .env.example # строки NAME=… шаблона, имени которых в .env нет, — в конец .env под # комментарием; в вывод — только имена @@ -100,8 +109,8 @@ API_REPLICAS ?= 2 EXPECT_REPLICAS ?= $(API_REPLICAS) DC=docker compose -# стенд: postgres, valkey, s3 -> migrate, s3-bootstrap -> api × -# API_REPLICAS -> haproxy +# стенд: postgres, valkey, s3, rabbitmq -> migrate, s3-bootstrap -> api × +# API_REPLICAS, cleaner, worker -> haproxy # (единственный порт API на хосте — у haproxy). env_setup создаёт # недостающие .env и config.toml из шаблонов: без config.toml compose не # запустится (bind с create_host_path: false), без паролей — тоже. @@ -158,7 +167,7 @@ revision: upgrade wipe_data: @project=$$($(DC) config | sed -n 's/^name: //p'); \ volumes=$$($(DC) config --volumes | sed "s/^/$${project}_/" | paste -sd ' ' -); \ - read -p "Удалить все данные стенда (volumes Postgres и S3: $$volumes)? Введите yes: " answer; \ + read -p "Удалить все данные стенда (volumes Postgres, S3 и брокера: $$volumes)? Введите yes: " answer; \ if [ "$$answer" = "yes" ]; then \ $(DC) down -v --remove-orphans; \ else \ @@ -198,6 +207,15 @@ start_s3: env_setup stop_s3: $(DC) stop s3 +# брокер стенда: --wait ждёт healthcheck; данные — в volume rabbitmq_data +.PHONY: start_broker +start_broker: env_setup + $(DC) up -d --wait rabbitmq + +.PHONY: stop_broker +stop_broker: + $(DC) stop rabbitmq + # проверка приватности bucket вне API на запущенном стенде: права ключа # API, чужой bucket и административные запросы (bootstrap в режиме check), # анонимные запросы с хоста и из сети стенда, порты контейнера S3 из сети; @@ -461,7 +479,7 @@ student_test: # объектов разделены именем базы, префикс test_/ удаляется при уборке. # $(PYTHON), а не uv run: uv повторно шлёт SIGINT, и Ctrl+C обрывал уборку .PHONY: test_isolated -test_isolated: env_setup start_db start_cache start_s3 +test_isolated: env_setup start_db start_cache start_s3 start_broker $(PYTHON) student-tests/run_isolated.py $(if $(KEEP_TEST_DB),--keep-db,) # проверки отказов (pytest -m fault) на отдельном стенде: свой проект diff --git a/QUESTIONS.md b/QUESTIONS.md index 0dd68c8d..817d07b8 100644 --- a/QUESTIONS.md +++ b/QUESTIONS.md @@ -91,6 +91,10 @@ `STAGING_RETENTION_SECONDS` — поля пока нет, появляется с очисткой staging. - **Цепочка LB:** срок публикации 2 с: после тела 29 с < `timeout server` 30 с, наибольшая длительность загрузки 76 с < дренаж 90 с. Прежние значения LB не меняются. +- **Apply:** `request_id` записей задания ставит сервис обработки сразу после разбора сообщения (а не `main.py`): разбор — его + шаг, задача доставки своя, контекст не течёт. `DROP` — третий исход `JobOutcome` рядом с `ACK` и `REQUEUE` дизайна: сообщение не + по схеме возвращать в очередь нельзя. Сообщение задания с `attachment_id` не своей строки считается неизвестным (`ACK`). + Подробности — design, «Уточнения apply». ### Вопросы diff --git a/bench/bench.compose.yml b/bench/bench.compose.yml index b370231b..d8477483 100644 --- a/bench/bench.compose.yml +++ b/bench/bench.compose.yml @@ -83,6 +83,38 @@ services: memory: ${BENCH_CLEANER_MEMORY:?run make bench} memswap_limit: ${BENCH_CLEANER_MEMORY:?run make bench} + # брокер (design change async-attachments, решение 16) запускает только + # профиль uploads: образ, rabbitmq.conf и лимиты рабочего стенда, swap = + # память, на прогон — новый volume. Прочие профили его не запускают: + # старт стенда перечисляет сервисы, реплики — с --no-deps (depends_on api + # не действует), а издатель API соединяется первой публикацией. Без порта + # хоста, без перезапуска, под своим именем + rabbitmq: + container_name: mtusi-bench-rabbitmq + restart: "no" + ports: !reset [] + deploy: + resources: + limits: + cpus: ${BENCH_BROKER_CPUS:?run make bench} + memory: ${BENCH_BROKER_MEMORY:?run make bench} + memswap_limit: ${BENCH_BROKER_MEMORY:?run make bench} + + # worker описан и не запускается ни одним профилем: стенд меряет реплику, + # а не обработку, задания ждут в очереди. Образ стенда, без config.toml + # рабочего стенда; лимиты BENCH_WORKER_* compose требует при разборе + worker: + container_name: mtusi-bench-worker + image: mtusi-messenger:bench + restart: "no" + volumes: !reset [] + deploy: + resources: + limits: + cpus: ${BENCH_WORKER_CPUS:?run make bench} + memory: ${BENCH_WORKER_MEMORY:?run make bench} + memswap_limit: ${BENCH_WORKER_MEMORY:?run make bench} + migrate: image: mtusi-messenger:bench # без config.toml рабочего стенда: настройки — окружение и дефолты diff --git a/bench/bench.env b/bench/bench.env index e6ddaa0c..2e9fbf57 100644 --- a/bench/bench.env +++ b/bench/bench.env @@ -13,4 +13,8 @@ VALKEY_PORT=6379 S3_HOST=s3 S3_PORT=8333 S3__BUCKET=bench +# брокер запускает только профиль uploads (лаба 5); пароль генерирует run.py +RABBITMQ_HOST=rabbitmq +RABBITMQ_PORT=5672 +RABBITMQ_DEFAULT_USER=bench APP__PORT=8080 diff --git a/bench/k6/uploads.js b/bench/k6/uploads.js index 8aedb4ad..ca16361b 100644 --- a/bench/k6/uploads.js +++ b/bench/k6/uploads.js @@ -5,7 +5,9 @@ // <отправка мс>,<длительность мс>,<статус>,» в файл консоли // k6 (--console-output); setup() пишет «up-t0,<мс>» — начало нагрузки на // часах ВМ: окно замера — [t0 + RAMP_S, t0 + RAMP_S + WINDOW_S). WARMUP=1 — -// одна разогревающая загрузка, она должна получить 201. +// одна разогревающая загрузка, она должна получить код успеха. Успех — 202, у +// варианта с образом commit до перехода на 202 — 201 (design change +// async-attachments, решение 16); чей код чей, считает bench/uploads.py. import exec from "k6/execution"; import http from "k6/http"; import { fail, sleep } from "k6"; @@ -25,6 +27,7 @@ const CLIENTS = Number(__ENV.CLIENTS || 1); const RAMP_S = Number(__ENV.RAMP_S || 3); const WINDOW_S = Number(__ENV.WINDOW_S || 20); const WARMUP = __ENV.WARMUP === "1"; +const SUCCESS = [201, 202]; // больше timeout server LB пути загрузки (30 с): клиент видит ответ LB const TIMEOUT = "60s"; const URL = `${API}/chats/${fixture.readChatId}/attachments?filename=bench.png`; @@ -83,16 +86,17 @@ export default function () { headers: HEADERS, responseType: "none", timeout: TIMEOUT, - responseCallback: http.expectedStatuses(201), + responseCallback: http.expectedStatuses(...SUCCESS), }); report(start, res); - if (WARMUP && res.status !== 201) { + const success = SUCCESS.includes(res.status); + if (WARMUP && !success) { fail(`warmup upload: ${res.status}`); } if (res.status === 429) { const retry = Number(res.headers["Retry-After"]); sleep(retry > 0 ? retry : 1); - } else if (res.status !== 201) { + } else if (!success) { sleep(1); } } diff --git a/bench/run.py b/bench/run.py index b30ce2f1..67d78393 100644 --- a/bench/run.py +++ b/bench/run.py @@ -72,6 +72,11 @@ CACHE = "mtusi-bench-valkey" # только профиль uploads, volume пересоздаётся перед каждым прогоном S3 = "mtusi-bench-s3" S3_VOLUME = f"{PROJECT}_s3_data" +# брокер стенда (design change async-attachments, решение 16): запускает +# только профиль uploads, volume пересоздаётся перед каждым прогоном +BROKER_SERVICE = "rabbitmq" +BROKER = "mtusi-bench-rabbitmq" +BROKER_VOLUME = f"{PROJECT}_rabbitmq_data" # окружение реплики по варианту профиля uploads: override поверх # bench.compose.yml в рабочем каталоге метки VARIANT_COMPOSE = "variant.compose.yml" @@ -120,8 +125,9 @@ ENV_FILE = ROOT / "bench" / "bench.env" # числе POSTGRES_* из shell) в стенд не попадает HOST_ENV = ("PATH", "HOME", "USER", "TMPDIR", "DOCKER_HOST", "DOCKER_CONFIG") # части имён переменных окружения API, которые в паспорт (stand.app_env) не -# пишутся: пароли Postgres и Valkey, секрет и ключ доступа S3 -SECRET_ENV_MARKS = ("PASSWORD", "SECRET", "ACCESS_KEY") +# пишутся: пароли Postgres, Valkey и брокера (PASS — и BROKER__PASSWORD, и +# RABBITMQ_DEFAULT_PASS), секреты и ключи доступа S3, в том числе S3_WORKER_* +SECRET_ENV_MARKS = ("PASS", "SECRET", "ACCESS_KEY") # статистика HAProxy изнутри контейнера LB (как make lb_stats): порт 8404 # наружу не опубликован, curl в образе нет, bash есть LB_STATS = ( @@ -347,9 +353,15 @@ class Profile: # высота PNG из шума шириной 1024, число одновременных клиентов, разгон # и окно прогона, окружение варианта «без лимита», интервал сэмплера # peak. Лимиты S3 — у всех профилей (compose требует их при разборе), - # но S3 запускает только этот профиль + # но S3 запускает только этот профиль. Код успеха варианта (design change + # async-attachments, решение 16): 202, у образа commit до перехода — 201 uploads_variants: tuple[str, ...] = () uploads_before: str = "" + uploads_success_codes: tuple[tuple[str, int], ...] = ( + ("before", 201), + ("unlimited", 202), + ("limited", 202), + ) uploads_sizes: tuple[tuple[str, int], ...] = () uploads_clients: tuple[int, ...] = () uploads_ramp_s: int = 3 @@ -361,6 +373,13 @@ class Profile: uploads_sample_interval_s: float = 0.2 s3_cpus: str = "1" s3_memory: str = "512m" + # брокер и worker: лимиты рабочего стенда без swap — у всех профилей + # (compose требует их при разборе); брокер запускает только профиль + # загрузок, worker — никто (design change async-attachments, решение 16) + broker_cpus: str = "1" + broker_memory: str = "512m" + worker_cpus: str = "1" + worker_memory: str = "1g" # уборщик (сервис cleaner): лимиты рабочего стенда без swap — у всех # профилей (compose требует их при разборе), запускает его только # профиль сверки (design change track2-reconcile-cost, решение 1) @@ -1218,8 +1237,12 @@ def vm_warnings(profile: Profile) -> list[str]: elif profile.sample_resources: extra = (profile.sampler_memory,) elif profile.is_uploads: - # профиль загрузок: S3 и сэмплер peak - extra = (profile.s3_memory, profile.sampler_memory) + # профиль загрузок: S3, брокер и сэмплер peak + extra = ( + profile.s3_memory, + profile.broker_memory, + profile.sampler_memory, + ) elif profile.is_reconcile: # профиль сверки: S3, разовый уборщик и сэмплер scan extra = ( @@ -1450,7 +1473,9 @@ def compose_env(profile: Profile) -> dict[str, str]: реплики API получают ключи, но к S3 не обращаются (design change `s3-storage`, решение 9). С уборщиком (design change `upload-consistency`, решение 9) — ещё ключи его пользователя: сервис - `cleaner` описан, но профили его не запускают. + `cleaner` описан, но профили его не запускают. С брокером и worker (design + change `async-attachments`, решение 16) — пароль брокера и ключи + пользователя worker: bootstrap S3 заводит его и в профилях с S3. """ env = {key: os.environ[key] for key in HOST_ENV if key in os.environ} return { @@ -1465,6 +1490,9 @@ def compose_env(profile: Profile) -> dict[str, str]: "S3_API_SECRET_KEY": secrets.token_hex(20), "S3_CLEANER_ACCESS_KEY": secrets.token_hex(10), "S3_CLEANER_SECRET_KEY": secrets.token_hex(20), + "S3_WORKER_ACCESS_KEY": secrets.token_hex(10), + "S3_WORKER_SECRET_KEY": secrets.token_hex(20), + "RABBITMQ_DEFAULT_PASS": secrets.token_urlsafe(24), "BENCH_APP_CPUS": profile.cpus, "BENCH_APP_MEMORY": profile.memory, "BENCH_DB_CPUS": profile.db_cpus, @@ -1480,6 +1508,10 @@ def compose_env(profile: Profile) -> dict[str, str]: "BENCH_S3_MEMORY": profile.s3_memory, "BENCH_CLEANER_CPUS": profile.cleaner_cpus, "BENCH_CLEANER_MEMORY": profile.cleaner_memory, + "BENCH_BROKER_CPUS": profile.broker_cpus, + "BENCH_BROKER_MEMORY": profile.broker_memory, + "BENCH_WORKER_CPUS": profile.worker_cpus, + "BENCH_WORKER_MEMORY": profile.worker_memory, } @@ -1736,6 +1768,10 @@ class Stand: # решение 10) и сверки; прочие профили его не запускают self.start_s3() say("s3 healthy, bootstrap done") + # брокер — только профиль загрузок (design change + # async-attachments, решение 16); worker не запускается никем + self.start_broker() + say("broker healthy") if self.profile.is_reconcile: # профиль сверки: аргументы S3 рабочего стенда и порт метрик # шлюза на loopback контейнера (design change @@ -1804,6 +1840,10 @@ class Stand: "s3-bootstrap", ) + def start_broker(self) -> None: + """Брокер стенда: `up --wait`, готовность — healthcheck сервиса.""" + self.compose("up", "-d", "--wait", BROKER_SERVICE) + def s3_command(self) -> list[str]: """Аргументы сервера S3 по `docker compose config` стенда без override метрик: те же, что у рабочего стенда.""" @@ -2023,26 +2063,31 @@ class Stand: ) def recycle_uploads(self, image: str, env: dict[str, str]) -> None: - """Перед прогоном профиля загрузок (решение 10): новый volume S3 с - bootstrap и новый контейнер реплики на образе варианта `image` с - окружением `env` (override `VARIANT_COMPOSE`), затем готовность - процесса и `UP` в LB. + """Перед прогоном профиля загрузок (решение 10): новые volume S3 с + bootstrap и брокера (иначе очередь копилась бы между прогонами) и + новый контейнер реплики на образе варианта `image` с окружением + `env` (override `VARIANT_COMPOSE`), затем готовность процесса и `UP` + в LB. - S3 останавливается `kill`, а не плавно (~15 с): его volume всё - равно удаляется. Реплика — сначала удаляется: новый контейнер - может получить тот же адрес, и LB держал бы слот `UP` от прежнего - (поэтому, как в `switch_api`, сначала готовность процесса).""" + S3 и брокер останавливаются `kill`, а не плавно (у S3 ~15 с): их + volume всё равно удаляются. Реплика — сначала удаляется: новый + контейнер может получить тот же адрес, и LB держал бы слот `UP` от + прежнего (поэтому, как в `switch_api`, сначала готовность + процесса).""" self.compose("rm", "-s", "-f", APP_SERVICE, check=False) - self.compose("kill", "s3", "s3-bootstrap", check=False) - self.compose("rm", "-f", "s3", "s3-bootstrap") - subprocess.run( - ["docker", "volume", "rm", S3_VOLUME], - capture_output=True, - check=False, - ) - if S3_VOLUME in sh("docker", "volume", "ls", "-q").split(): - raise BenchError(f"volume {S3_VOLUME} was not removed") + services = ("s3", "s3-bootstrap", BROKER_SERVICE) + self.compose("kill", *services, check=False) + self.compose("rm", "-f", *services) + for volume in (S3_VOLUME, BROKER_VOLUME): + subprocess.run( + ["docker", "volume", "rm", volume], + capture_output=True, + check=False, + ) + if volume in sh("docker", "volume", "ls", "-q").split(): + raise BenchError(f"volume {volume} was not removed") self.start_s3() + self.start_broker() sh("docker", "tag", image, APP_IMAGE) path = self.work_dir / VARIANT_COMPOSE self.extra_files = [] @@ -2376,6 +2421,8 @@ class Stand: roles = {APP_SERVICE: replicas[0], **CONTAINERS, "k6": K6} if self.profile.is_uploads or self.profile.is_reconcile: roles["s3"] = S3 + if self.profile.is_uploads: + roles[BROKER_SERVICE] = BROKER limits: dict[str, Any] = {} for role, name in roles.items(): limits[role] = self.container_limits(name) @@ -2899,6 +2946,9 @@ class Stand: # S3 — только у профилей загрузок и сверки; образ и аргументы — # рабочего стенда (у сверки ещё порт метрик, meta.reconcile) extra["s3"] = image(S3) + if self.profile.is_uploads: + # брокер — только у профиля загрузок; лимиты — limits.rabbitmq + extra[BROKER_SERVICE] = image(BROKER) return { **extra, # буфер приёма сокетов реплики: sysctls сервиса api (design @@ -5870,8 +5920,9 @@ class Bench: def run_uploads(self) -> None: """Профиль загрузок (design change `upload-memory`, решение 10): - образы вариантов, тела, план кругами, стенд с S3, пользователь и - чат, затем прогоны — на каждый новые volume S3 и реплика.""" + образы вариантов, тела, план кругами, стенд с S3 и брокером, + пользователь и чат, затем прогоны — на каждый новые volume S3 и + брокера и реплика.""" p = self.profile stand = self.stand meta = self.results.meta @@ -5894,6 +5945,8 @@ class Bench: f"uploads: image of {commit} built ({images['before'][:19]}…)", ) info["images"] = {v: images[v] for v in p.uploads_variants} + codes = dict(p.uploads_success_codes) + info["success_codes"] = {v: codes[v] for v in p.uploads_variants} bodies = uploads.build_bodies(p.uploads_sizes, p.seed) heights = dict(p.uploads_sizes) info["bodies"] = { @@ -5948,7 +6001,7 @@ class Bench: image: str, bodies: dict[str, bytes], ) -> None: - """Один прогон: новые S3 и реплика варианта, разогревающая + """Один прогон: новые S3, брокер и реплика варианта, разогревающая загрузка, сэмплер `peak` (сброс пика перед нагрузкой), k6 `constant-vus`, затем пики, состояние реплики и строка `runs.csv`. Реплика, убитая из-за памяти, — пометка `oom`, а не @@ -5970,7 +6023,8 @@ class Bench: info["app_env"][run["variant"]] = stand.app_env(replica) self.results.write_meta() body = f"body-{run['size']}.png" - # разогрев: одна загрузка 201 до окна (соединения, модели botocore) + # разогрев: одна успешная загрузка до окна (соединения, модели + # botocore, соединение с брокером) stand.k6("uploads.js", {"BODY": body, "WARMUP": 1}) targets = { "api": stand.full_id(replica), @@ -6018,6 +6072,10 @@ class Bench: state = stand.exit_state(replica) s3_state = stand.exit_state(S3) state["s3_down"] = not s3_state["running"] or s3_state["oom_killed"] + broker_state = stand.exit_state(BROKER) + state["broker_down"] = ( + not broker_state["running"] or broker_state["oom_killed"] + ) text = (stand.work_dir / log_name).read_text( encoding="utf-8", errors="replace", @@ -6044,6 +6102,7 @@ class Bench: t0, p.uploads_ramp_s, p.uploads_window_s, + success_code=info["success_codes"][run["variant"]], ) swapped = ( None @@ -6063,7 +6122,8 @@ class Bench: self.say( f"{name} ({run['order']}/{self.runs_total}): before " f"{row['mem_before_mib']} MiB, peak {row['peak_mib']} MiB " - f"({row['peak_source']}), sock {row['sock_max_mib']} MiB, 201 " + f"({row['peak_source']}), sock {row['sock_max_mib']} MiB, " + f"{stats['success_code']} " f"{stats['s201']}, 429 {stats['s429']}, 5xx {fives}, conn " f"{stats['s_conn_error']}, {stats['uploads_per_s']}/s, p95 " f"{stats['p95_ms']} ms{' OOM' if 'oom' in row['flags'] else ''}", @@ -6588,10 +6648,14 @@ class Bench: expected = reconcile.model(0, clean=clean, missing=count) stage = f"S4-{count}" for entry in (e for e in plan if e["stage"] == stage): + # и «до», и «после» отказывают по пределу рано: commit «до» — + # перенос лабы 4, ранний отказ в нём уже есть (прежнего + # `7f4e626` в истории лабы 5 нет) found = { - "missing_object": count - if entry["cell"] == "before" - else min(count, p.reconcile_s4_max_changes + 1), + "missing_object": min( + count, + p.reconcile_s4_max_changes + 1, + ), } result = self.reconcile_pass( entry, diff --git a/bench/uploads.py b/bench/uploads.py index b2f7c3d6..f3662dd5 100644 --- a/bench/uploads.py +++ b/bench/uploads.py @@ -34,7 +34,11 @@ VARIANT_NAMES = { "unlimited": "без лимита", "limited": "с лимитом", } -# коды ответов в runs.csv; 0 — ошибка соединения (ответа нет) +# коды ответов в runs.csv; 0 — ошибка соединения (ответа нет). Столбец s201 не +# переименовывается (.claude/rules/bench.md, «Результаты»): в нём код успеха +# варианта, а какой — называет success_code (design change async-attachments, +# решение 16). Второй код успеха у того же варианта — s_other +SUCCESS_FIELD = "s201" CODES = (201, 429, 400, 413, 415, 502, 503, 504, 0) CODE_FIELDS = [f"s{code}" if code else "s_conn_error" for code in CODES] @@ -69,6 +73,7 @@ RUN_FIELDS = [ "lb_sock_max_mib", "host_swapouts", "flags", + "success_code", ] @@ -230,14 +235,20 @@ def k6_stats( t0: int, ramp_s: float, window_s: float, + *, + success_code: int, ) -> dict[str, Any]: """Ответы по кодам — за весь прогон (разгон и окно, в том числе после - гибели реплики); загрузок 201 в секунду и перцентили успешных — по - загрузкам, отправленным в окне `[t0 + ramp, t0 + ramp + window)`.""" + гибели реплики); успешных загрузок в секунду и их перцентили — по + загрузкам, отправленным в окне `[t0 + ramp, t0 + ramp + window)`. + Успешная — ответ с `success_code` варианта, он считается в `s201`; + прочий 201 или 202 — в `s_other`.""" counts = dict.fromkeys(CODE_FIELDS, 0) other = 0 for item in uploads: - if item.status in CODES: + if item.status == success_code: + counts[SUCCESS_FIELD] += 1 + elif item.status in CODES and item.status != 201: key = f"s{item.status}" if item.status else "s_conn_error" counts[key] += 1 else: @@ -247,7 +258,7 @@ def k6_stats( ok = [ item.duration_ms for item in uploads - if item.status == 201 and w0 <= item.start_ms < w1 + if item.status == success_code and w0 <= item.start_ms < w1 ] def ms(value: float | None) -> float | None: @@ -255,6 +266,7 @@ def k6_stats( return { **counts, + "success_code": success_code, "s_other": other, "requests": len(uploads), "window_s": window_s, @@ -367,7 +379,8 @@ def run_row( из-за памяти (`OOMKilled` контейнера или `oom_kill` cgroup), `host_swap` — хост выгружал страницы в swap во время прогона, `peak_sampled` — пик окна по выборкам, а не по сброшенному - `memory.peak`.""" + `memory.peak`, `s3_down` и `broker_down` — S3 или брокер не дожил до + конца прогона.""" app = peaks.roles.get("api", Peak()) s3 = peaks.roles.get("s3", Peak()) lb = peaks.roles.get("haproxy", Peak()) @@ -381,6 +394,8 @@ def run_row( flags.append("peak_sampled") if state.get("s3_down"): flags.append("s3_down") + if state.get("broker_down"): + flags.append("broker_down") return { **{key: run[key] for key in ("run", "variant", "size", "clients")}, "repeat": run["repeat"], @@ -599,8 +614,8 @@ def hypotheses( out.append( { "id": "H3", - "text": "загрузок 201 в секунду при C ≥ 10: «с лимитом» ≥ 90 % " - "«без лимита» на тех же C, пока тот жив", + "text": "успешных загрузок в секунду при C ≥ 10: «с лимитом» ≥ " + "90 % «без лимита» на тех же C, пока тот жив", "numbers": "; ".join( f"{s} C={c}: {a:.2f} / {b:.2f} = {ratio:.0%}" for s, c, a, b, ratio in ratios @@ -676,8 +691,20 @@ def render_summary(meta: dict[str, Any], rows: list[dict[str, Any]]) -> str: ), f"- Реплика {profile['cpus']} CPU / {profile['memory']} без swap, " f"буфер приёма `{meta.get('stand', {}).get('api_tcp_rmem', '—')}`; " - f"S3 {profile['s3_cpus']} CPU / {profile['s3_memory']}; LB " - f"{profile['lb_cpus']} CPU / {profile['lb_memory']}", + f"S3 {profile['s3_cpus']} CPU / {profile['s3_memory']}; брокер " + f"{profile['broker_cpus']} CPU / {profile['broker_memory']}; LB " + f"{profile['lb_cpus']} CPU / {profile['lb_memory']}. Worker не " + "запущен: задания ждут в очереди, на прогон — новый volume брокера", + "- Код успеха: " + + ( + ", ".join( + f"«{VARIANT_NAMES[v]}» — {code}" + for v, code in info.get("success_codes", {}).items() + ) + or "—" + ) + + " (столбец `s201` `runs.csv` считает код варианта, его называет " + "`success_code`)", "- Пик — `memory.peak` cgroup, сброшенный через свой дескриптор " "перед нагрузкой (`peak_source` = reset); без сброса — наибольшая " "выборка раз в " @@ -695,7 +722,7 @@ def render_summary(meta: dict[str, Any], rows: list[dict[str, Any]]) -> str: "включает.", "", "| Вариант | Тело | C | Пик старта, MiB | До окна, MiB | Пик, MiB | " - "anon, MiB | sock, MiB | OOM | 201 | 429 | 5xx | ошибка соединения | " + "anon, MiB | sock, MiB | OOM | Успех | 429 | 5xx | ошибка соединения | " "Загрузок/с | p50, мс | p95, мс | S3 пик, MiB | S3 anon, MiB | " "LB пик, MiB | Пометки |", "|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|" @@ -933,8 +960,9 @@ def selftest() -> int: t0, ups = parse_k6(console) expect("t0", t0, 1000) expect("uploads", len(ups), 6) - stats = k6_stats(ups, t0 or 0, 3, 20) + stats = k6_stats(ups, t0 or 0, 3, 20, success_code=201) expect("201", stats["s201"], 3) + expect("success code", stats["success_code"], 201) expect("429", stats["s429"], 1) expect("conn", stats["s_conn_error"], 1) expect("503", stats["s503"], 1) @@ -942,6 +970,24 @@ def selftest() -> int: expect("uploads/s", stats["uploads_per_s"], 0.05) expect("p95", stats["p95_ms"], 80.0) expect("percentile", percentile([1, 2, 3, 4], 0.5), 2.5) + # лаба 5: код успеха варианта — 202, столбец тот же; чужой код успеха — + # s_other, и в окно не идёт + _, async_ups = parse_k6(console.replace(",201,", ",202,")) + accepted = k6_stats(async_ups, t0 or 0, 3, 20, success_code=202) + expect("202 in s201", accepted["s201"], 3) + expect("success code 202", accepted["success_code"], 202) + expect("202 p95", accepted["p95_ms"], 80.0) + expect("202 other", accepted["s_other"], 0) + wrong = k6_stats(ups, t0 or 0, 3, 20, success_code=202) + expect("201 is not success of 202", wrong["s201"], 0) + expect("201 in s_other", wrong["s_other"], 3) + expect("no window uploads", wrong["uploads_per_s"], 0.0) + expect("no percentiles", wrong["p95_ms"], None) + swapped = k6_stats(async_ups, t0 or 0, 3, 20, success_code=201) + expect("202 is not success of 201", swapped["s201"], 0) + expect("202 in s_other", swapped["s_other"], 3) + expect("success_code column last", RUN_FIELDS[-1], "success_code") + expect("s201 column kept", "s201" in RUN_FIELDS, True) sampler = "\n".join( [ @@ -976,6 +1022,9 @@ def selftest() -> int: expect("row flags", row["flags"], "oom host_swap") expect("row fields", set(RUN_FIELDS) >= set(row), True) expect("row peak", row["peak_mib"], 145.0) + expect("row success code", row["success_code"], 201) + downed = run_row(run, 1, parsed, stats, {"broker_down": True}, 0) + expect("row broker_down", downed["flags"], "broker_down") def synth(variant: str, clients: int, peak: float, **extra: Any) -> dict: base = { @@ -1042,13 +1091,20 @@ def selftest() -> int: "memory": "512m", "s3_cpus": "1", "s3_memory": "512m", + "broker_cpus": "1", + "broker_memory": "512m", "lb_cpus": "1", "lb_memory": "256m", }, - "uploads": {"bodies": {"10MiB": body_passport("10MiB", 3409, b"x")}}, + "uploads": { + "bodies": {"10MiB": body_passport("10MiB", 3409, b"x")}, + "success_codes": {"unlimited": 202, "limited": 202}, + }, } text = render_summary(meta, rows) expect("summary has H1", "| H1 |" in text, True) + expect("summary names code", "«с лимитом» — 202" in text, True) + expect("summary names broker", "брокер 1 CPU / 512m" in text, True) expect("summary has cells", "| с лимитом | 10MiB | 40 |" in text, True) expect( "replica growth over C=10", diff --git a/config_example.toml b/config_example.toml index 3d85715b..be20d604 100644 --- a/config_example.toml +++ b/config_example.toml @@ -121,3 +121,30 @@ max_changes = 100 # HEAD, GET, DELETE) в среднем от начала прохода; 0 — без предела; # разовый проход принимает другой аргументом --max-objects-per-second max_objects_per_second = 2000 + +[broker] +# Адрес, порт, пользователь и пароль RabbitMQ приходят из .env (мосты к +# RABBITMQ_*) и из environment compose; здесь их не указывать. +# секунды на установку соединения с брокером +connect_timeout_seconds = 2 +# секунды на публикацию целиком: соединение, канал, публикация и +# подтверждение; по сроку загрузка отвечает 503. Часть цепочки таймаутов +# пути загрузки: после тела 29 с меньше timeout server LB (30 с) +publish_timeout_seconds = 2 + +[worker] +# Worker обработки вложений (сервис compose worker); реплики API секцию не +# читают. Разовая подмена — окружением WORKER__*. +# заданий, которые worker обрабатывает одновременно (лимит памяти +# контейнера — на эту конкуренцию) +concurrency = 2 +# начатых попыток у задания, включая первую +max_attempts = 5 +# секунды на одну попытку +job_timeout_seconds = 60 +# секунды паузы перед следующей попыткой +retry_delay_seconds = 10 +# секунды, которые worker ждёт начатые задания после SIGTERM, не больше 9 +graceful_shutdown_seconds = 8 +# секунды паузы между попытками соединиться с брокером +reconnect_seconds = 2 diff --git a/docker-compose.yml b/docker-compose.yml index 427433c7..71e03312 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -1,6 +1,7 @@ # Стенд лабы 5: HAProxy — единственная точка входа, за ним API × # API_REPLICAS; PostgreSQL, Valkey (кэш), S3 (SeaweedFS, байты вложений), -# одноразовые миграции и bootstrap S3, уборщик незавершённых загрузок. +# RabbitMQ (задания обработки), одноразовые миграции и bootstrap S3, уборщик +# незавершённых загрузок, worker обработки вложений. # Правила — .claude/rules/docker.md и balancer.md. Значения — из .env # (шаблон .env.example); литералы только у адреса публикации 127.0.0.1 и # у режима docker. Имя проекта меняется в каждой лабе: от него зависят @@ -8,7 +9,7 @@ name: mtusi-lab5 # окружение по сервисам: секреты получают только те, кому они нужны. -# PostgreSQL — api, cleaner и migrate +# PostgreSQL — api, cleaner, worker и migrate x-db-env: &db-env APP__RUN_MODE: docker DATABASE__HOST: ${POSTGRES_HOST:-postgres} @@ -23,11 +24,12 @@ x-cache-env: &cache-env CACHE__PORT: ${VALKEY_PORT:-6379} CACHE__PASSWORD: ${VALKEY_PASSWORD:?VALKEY_PASSWORD is empty, copy Valkey lines from .env.example} -# S3 — api и cleaner: адрес в сети и bucket; ключи — у каждого своего +# S3 — api, cleaner и worker: адрес в сети и bucket; ключи — у каждого своего # пользователя (не административные). Секреты S3 по сервисам (design # change s3-storage, решение 3; upload-consistency, решение 9): # административная пара — только s3, ключ подписи — s3 и s3-bootstrap, -# ключи API — s3-bootstrap и api, ключи уборщика — s3-bootstrap и cleaner +# ключи API — s3-bootstrap и api, ключи уборщика — s3-bootstrap и cleaner, +# ключи worker — s3-bootstrap и worker x-s3-env: &s3-env S3__HOST: ${S3_HOST:-s3} S3__PORT: ${S3_PORT:-8333} @@ -38,6 +40,15 @@ x-s3-api-keys-env: &s3-api-keys-env S3__ACCESS_KEY_ID: ${S3_API_ACCESS_KEY:?S3_API_ACCESS_KEY is empty, copy S3 lines from .env.example} S3__SECRET_ACCESS_KEY: ${S3_API_SECRET_KEY:?S3_API_SECRET_KEY is empty, copy S3 lines from .env.example} +# RabbitMQ — api и worker: адрес в сети и учётные данные; один пользователь +# на оба сервиса, разделение прав — лаба 7 (design change async-attachments, +# решение 4) +x-broker-env: &broker-env + BROKER__HOST: ${RABBITMQ_HOST:-rabbitmq} + BROKER__PORT: ${RABBITMQ_PORT:-5672} + BROKER__USER: ${RABBITMQ_DEFAULT_USER:?RABBITMQ_DEFAULT_USER is not set, run make env_setup} + BROKER__PASSWORD: ${RABBITMQ_DEFAULT_PASS:?RABBITMQ_DEFAULT_PASS is empty, run make env_setup} + # образ сервера S3 и bootstrap: тег с версией и digest индекса (amd64 и # arm64) x-s3-image: &s3-image chrislusf/seaweedfs:4.48@sha256:4e61d15fd35994cb1e43e1e553dff106794841fd9a99ade2fc8c8bfce4d7872d @@ -88,9 +99,9 @@ services: resources: limits: # соединения реплик: API_REPLICAS × pool_size (переполнения нет, - # max_overflow 0) + migrate + cleaner (пул 1) ≤ max_connections - # (100): 2 × 10 + 1 + 1, при поочерёдной замене 3 × 10 + 1 + 1; - # расчёт — REPORT.md + # max_overflow 0) + migrate + cleaner (пул 1) + worker (пул 2) ≤ + # max_connections (100): 2 × 10 + 1 + 1 + 2, при поочерёдной замене + # 3 × 10 + 1 + 1 + 2; расчёт — REPORT.md cpus: "2.0" memory: 1G @@ -219,6 +230,51 @@ services: cpus: "1.0" memory: 512M + # брокер заданий обработки вложений (design change async-attachments, + # решение 4). hostname постоянный: имя узла задаёт каталог данных, и + # пересозданный контейнер иначе не нашёл бы свои данные в том же volume. + # Учётная запись приложения создаётся при первом старте на пустом volume. + # Наружу — только AMQP на loopback, для запуска в консоли + rabbitmq: + image: rabbitmq:4.3.7@sha256:bd88985187aa73cd598fa0d8b31d49b2f814a6d9e58f6d5a89bae588669d946a + hostname: rabbitmq + restart: unless-stopped + environment: + RABBITMQ_DEFAULT_USER: ${RABBITMQ_DEFAULT_USER:?RABBITMQ_DEFAULT_USER is not set, run make env_setup} + RABBITMQ_DEFAULT_PASS: ${RABBITMQ_DEFAULT_PASS:?RABBITMQ_DEFAULT_PASS is empty, run make env_setup} + RABBITMQ_NODE_PORT: ${RABBITMQ_PORT:-5672} + ports: + - "127.0.0.1:${RABBITMQ_OUT_PORT:-5673}:${RABBITMQ_PORT:-5672}" + volumes: + # volume образа (Config.Volumes): очереди и сообщения + - rabbitmq_data:/var/lib/rabbitmq + - type: bind + source: ./infra/rabbitmq/rabbitmq.conf + target: /etc/rabbitmq/conf.d/90-messenger.conf + read_only: true + bind: + create_host_path: false + networks: + default: + # любое значение RABBITMQ_HOST указывает на этот сервис + aliases: + - ${RABBITMQ_HOST:-rabbitmq} + healthcheck: + test: ["CMD-SHELL", "rabbitmq-diagnostics -q check_port_connectivity"] + interval: 10s + timeout: 5s + retries: 10 + start_period: 30s + start_interval: 1s + # брокер завершается сам за ~2 с; 20 с — запас на большую очередь + stop_grace_period: 20s + deploy: + resources: + limits: + # предел памяти брокера — 400 МиБ в infra/rabbitmq/rabbitmq.conf + cpus: "1.0" + memory: 512M + # bootstrap S3 — один раз до реплик, как миграции (решение 4): приватный # bucket, пользователь API с политикой «только объекты своего bucket», # пользователь уборщика — «чтение и удаление объектов своего bucket», @@ -242,6 +298,8 @@ services: S3_API_SECRET_KEY: ${S3_API_SECRET_KEY:?S3_API_SECRET_KEY is empty, copy S3 lines from .env.example} S3_CLEANER_ACCESS_KEY: ${S3_CLEANER_ACCESS_KEY:?S3_CLEANER_ACCESS_KEY is empty, run make env_setup} S3_CLEANER_SECRET_KEY: ${S3_CLEANER_SECRET_KEY:?S3_CLEANER_SECRET_KEY is empty, run make env_setup} + S3_WORKER_ACCESS_KEY: ${S3_WORKER_ACCESS_KEY:?S3_WORKER_ACCESS_KEY is empty, run make env_setup} + S3_WORKER_SECRET_KEY: ${S3_WORKER_SECRET_KEY:?S3_WORKER_SECRET_KEY is empty, run make env_setup} # список объектов уборщику — только по префиксу вложений своей базы # (сверка bucket и БД, design change track2-reconciler, решение 2); # не секрет, уборщик строит префикс сам из имени базы @@ -299,7 +357,7 @@ services: image: mtusi-messenger:lab5 restart: unless-stopped environment: - <<: [*db-env, *cache-env, *s3-env, *s3-api-keys-env] + <<: [*db-env, *cache-env, *s3-env, *s3-api-keys-env, *broker-env] APP__PORT: ${APP__PORT:-8080} volumes: - *config-toml @@ -309,6 +367,10 @@ services: # без кэша API работает, но в штатном стенде он есть с первого запроса valkey: condition: service_healthy + # без брокера API стартует и отвечает 503 на загрузке, но в штатном + # стенде он есть с первого запроса + rabbitmq: + condition: service_healthy migrate: condition: service_completed_successfully # bucket и пользователь API есть до первого запроса @@ -375,6 +437,48 @@ services: cpus: "0.25" memory: 256M + # worker обработки вложений (design change async-attachments, решение 6): + # отдельный процесс на образе API, декодирование и thumbnail — только + # здесь. Портов нет, HTTP не слушает; реплики его не ждут + worker: + image: mtusi-messenger:lab5 + pull_policy: never + entrypoint: ["python", "-m", "src.worker"] + restart: unless-stopped + environment: + <<: [*db-env, *s3-env, *broker-env] + # шаги с БД короткие: соединение на задание + DATABASE__POOL_SIZE: "2" + # пользователь worker: чтение и запись объектов, без удаления и + # списка; ключей API и уборщика, пароля Valkey и административных + # ключей S3 нет + S3__ACCESS_KEY_ID: ${S3_WORKER_ACCESS_KEY:?S3_WORKER_ACCESS_KEY is empty, run make env_setup} + S3__SECRET_ACCESS_KEY: ${S3_WORKER_SECRET_KEY:?S3_WORKER_SECRET_KEY is empty, run make env_setup} + volumes: + - *config-toml + depends_on: + postgres: + condition: service_healthy + rabbitmq: + condition: service_healthy + migrate: + condition: service_completed_successfully + s3-bootstrap: + condition: service_completed_successfully + # healthcheck образа — HTTP /health/ready, а worker HTTP не слушает. + # Живость — журнал и очередь + healthcheck: + disable: true + # SIGTERM: начатые задания ждут ≤ [worker] graceful_shutdown_seconds + stop_grace_period: 10s + deploy: + resources: + limits: + # две задачи PNG RGBA на 40 Мпкс: по замеру 323 МиБ на задачу, с + # клиентами и телами ≈ 800 МиБ при конкуренции 2 + cpus: "1.0" + memory: 1G + # единственная точка входа: реплики находит через DNS Docker, проверяет # /health/ready; конфиг — infra/haproxy/haproxy.cfg. Секретов не получает haproxy: @@ -415,3 +519,4 @@ services: volumes: postgres_data: s3_data: + rabbitmq_data: diff --git a/infra/haproxy/haproxy.cfg b/infra/haproxy/haproxy.cfg index d6c5168b..d73dd41d 100644 --- a/infra/haproxy/haproxy.cfg +++ b/infra/haproxy/haproxy.cfg @@ -101,10 +101,11 @@ backend api # загрузки: # до тела — 2 × [database] request_timeout_seconds (вход, членство) + # [uploads] wait_timeout_seconds = 2 × 6 + 5 = 17 с; - # после тела — проверка (до ~4 с) + pending 6 + PUT 5 + ready 6 + - # компенсация 5 ≈ 26 с. + # после тела — проверка (до ~4 с) + pending 6 + PUT 5 + queued 6 + + # публикация 2 + отметка или отмена 6 ≈ 29 с; ветка компенсации после + # неудачной фиксации queued — компенсация 5 вместо публикации, 26 с. # Тело ограничивают [uploads] body_timeout_seconds (30 с) и timeout - # client; наибольшая длительность загрузки 17 + 30 + 26 ≈ 73 с < + # client; наибольшая длительность загрузки 17 + 30 + 29 ≈ 76 с < # ROLLOUT_DRAIN_TIMEOUT (90 с, scripts/rolling-update.sh). Остальные # пути — прежние 10 с. Выражение — путь ручки в API # (src/api/routers/v1/attachment.py): при смене префикса менять вместе diff --git a/infra/rabbitmq/rabbitmq.conf b/infra/rabbitmq/rabbitmq.conf new file mode 100644 index 00000000..84dce47c --- /dev/null +++ b/infra/rabbitmq/rabbitmq.conf @@ -0,0 +1,6 @@ +# Предел памяти брокера задан явно: лимит контейнера он не видит (проба: 4760 +# МиБ при лимите 512 МБ, design change async-attachments, Context) и был бы +# завершён ядром, а не сдерживал публикацию. Сработавший предел блокирует +# публикацию: загрузки получают 503 по сроку, сообщения не теряются. +# Новую настройку этого файла проверять запуском: неверное имя — отказ старта. +vm_memory_high_watermark.absolute = 400MiB diff --git a/infra/s3/bootstrap.sh b/infra/s3/bootstrap.sh index d2d9c7bc..6a371d14 100755 --- a/infra/s3/bootstrap.sh +++ b/infra/s3/bootstrap.sh @@ -3,9 +3,11 @@ # политикой «только объекты своего bucket», пользователь уборщика с # политикой «чтение и удаление объектов своего bucket и их список только по # префиксу вложений своей базы» (S3_CLEANER_LIST_PREFIX, <база>/attachments/: -# для сверки bucket и БД), проверки приватности вне API. Design change +# для сверки bucket и БД), пользователь worker с политикой «чтение и запись +# объектов своего bucket», проверки приватности вне API. Design change # s3-storage, решения 3, 4 и 8, design change upload-consistency, решение 8, -# design change track2-reconciler, решение 2; правила — docker.md. +# design change track2-reconciler, решение 2, design change +# async-attachments, решение 12; правила — docker.md. # # Запускается сервисом compose s3-bootstrap на образе сервера в сетевом # пространстве сервиса s3 (network_mode: service:s3): master и filer @@ -20,7 +22,7 @@ # шире, чем apply: чужой bucket (временный, создаётся и удаляется # здесь же), административные запросы ключей API и уборщика, запись # ключом уборщика, его список по своему префиксу (200), без префикса и -# с чужим (403), анонимные запросы. Общий проверочный +# с чужим (403), права ключа worker, анонимные запросы. Общий проверочный # объект остаётся для проверок с хоста и из сети (make s3_check) до # режима cleanup; объект проверок удаления ключом уборщика — свой; # cleanup — удалить проверочные объекты и временные bucket-ы check. @@ -37,6 +39,8 @@ S3_PORT=${S3_PORT:?S3_PORT is not set} : "${S3_API_SECRET_KEY:?S3_API_SECRET_KEY is empty, copy S3 lines from .env.example}" : "${S3_CLEANER_ACCESS_KEY:?S3_CLEANER_ACCESS_KEY is empty, run make env_setup}" : "${S3_CLEANER_SECRET_KEY:?S3_CLEANER_SECRET_KEY is empty, run make env_setup}" +: "${S3_WORKER_ACCESS_KEY:?S3_WORKER_ACCESS_KEY is empty, run make env_setup}" +: "${S3_WORKER_SECRET_KEY:?S3_WORKER_SECRET_KEY is empty, run make env_setup}" : "${WEED_JWT_FILER_SIGNING_KEY:?S3_JWT_SIGNING_KEY is empty, copy S3 lines from .env.example}" # префикс списка уборщика: имя базы и /attachments/; в JSON политики идёт # только проверенное значение @@ -48,6 +52,8 @@ API_USER=api API_POLICY=api-objects CLEANER_USER=cleaner CLEANER_POLICY=cleaner-objects +WORKER_USER=worker +WORKER_POLICY=worker-objects # регион подписи; SeaweedFS берёт его из запроса REGION=us-east-1 TAG="s3-bootstrap" @@ -57,6 +63,8 @@ CHECK_KEY=.s3-check/probe # объект проверок ключа уборщика: его он удаляет, общий нужен проверкам с # хоста CLEANER_CHECK_KEY=.s3-check/cleaner-probe +# объект проверок ключа worker: его он пишет; удаляет ключ API +WORKER_CHECK_KEY=.s3-check/worker-probe CHECK_BUCKET_PREFIX="${BUCKET}-check-" # сколько секунд ждать, пока изменения IAM дойдут до шлюза (подписка на # filer) @@ -66,6 +74,7 @@ umask 077 WORK=$(mktemp -d) API_CRED="$WORK/api.cred" CLEANER_CRED="$WORK/cleaner.cred" +WORKER_CRED="$WORK/worker.cred" BODY="$WORK/body" TEMP_BUCKET="" @@ -108,11 +117,13 @@ ws_secret_step() { ws "$*" >/dev/null || fail "$step" } -# ключи API и уборщика для curl: файлы на tmpfs, в argv только путь +# ключи API, уборщика и worker для curl: файлы на tmpfs, в argv только путь printf 'user = "%s:%s"\n' "$S3_API_ACCESS_KEY" "$S3_API_SECRET_KEY" \ >"$API_CRED" printf 'user = "%s:%s"\n' "$S3_CLEANER_ACCESS_KEY" "$S3_CLEANER_SECRET_KEY" \ >"$CLEANER_CRED" +printf 'user = "%s:%s"\n' "$S3_WORKER_ACCESS_KEY" "$S3_WORKER_SECRET_KEY" \ + >"$WORKER_CRED" # подписанный ключом из файла $1 запрос: печатает код ответа, тело — в # $BODY @@ -133,6 +144,11 @@ cleaner_signed() { signed_by "$CLEANER_CRED" "$@" } +# подписанный ключом worker запрос +worker_signed() { + signed_by "$WORKER_CRED" "$@" +} + # анонимный запрос: печатает код ответа anon() { curl -s -o "$BODY" -w '%{http_code}' --max-time 5 "$@" || echo 000 @@ -191,6 +207,11 @@ wait_cleaner_key() { wait_key 204 "$CLEANER_CRED" -X DELETE "$1" } +# ключ worker — записью проверочного объекта, как у API +wait_worker_key() { + wait_key 200 "$WORKER_CRED" -X PUT --data-binary "$TAG" "$1" +} + # ждать ключ пользователя $1 через функцию $2 с адресом $3; новый секрет # (SignatureDoesNotMatch) — пересоздать ключ и ждать снова wait_user_key() { @@ -268,6 +289,10 @@ apply_policies() { put_policy "$API_POLICY" \ '["s3:GetObject", "s3:PutObject", "s3:DeleteObject"]' put_cleaner_policy + # worker: читает staging, пишет конечный префикс; удаления и списка нет. + # По /*, а не по префиксу: make test_isolated работает под + # test_/ с теми же ключами (design change async-attachments, решение 12) + put_policy "$WORKER_POLICY" '["s3:GetObject", "s3:PutObject"]' } # ключ и секрет пользователя $1 — из окружения (.env) @@ -281,6 +306,10 @@ user_keys() { ACCESS_KEY=$S3_CLEANER_ACCESS_KEY SECRET_KEY=$S3_CLEANER_SECRET_KEY ;; + "$WORKER_USER") + ACCESS_KEY=$S3_WORKER_ACCESS_KEY + SECRET_KEY=$S3_WORKER_SECRET_KEY + ;; *) fail "unknown user $1" ;; esac } @@ -329,7 +358,9 @@ recreate_key() { # проверки каждого запуска: ключ API пишет и читает проверочный объект, # список и создание bucket — 403; ключ уборщика читает его, запись и -# список — 403, затем удаляет; после удаления ключ API получает 404; +# список — 403, затем удаляет; после удаления ключ API получает 404; ключ +# worker пишет и читает свой объект, читает объект API (тут же записанный), +# удаление, список и создание bucket — 403, объект убирает ключ API; # аноним не читает объект и не видит список apply_checks() { probe="${S3}/${BUCKET}/.s3-bootstrap/check-$$" @@ -355,9 +386,29 @@ apply_checks() { || fail "cleaner key list ${LIST_PREFIX} (code ${code})" [ "$(cleaner_signed -X DELETE "$probe")" = 204 ] || fail "cleaner key delete" [ "$(signed "$probe")" = 404 ] || fail "object is still there after delete" + worker_probe="${S3}/${BUCKET}/.s3-bootstrap/worker-check-$$" + wait_user_key "$WORKER_USER" wait_worker_key "$worker_probe" + [ "$(worker_signed "$worker_probe")" = 200 ] && [ "$(cat "$BODY")" = "$TAG" ] \ + || fail "worker key get" + [ "$(signed -X PUT --data-binary "$TAG api" "$probe")" = 200 ] \ + || fail "api key put for worker" + [ "$(worker_signed "$probe")" = 200 ] && [ "$(cat "$BODY")" = "$TAG api" ] \ + || fail "worker key get object of api key" + [ "$(worker_signed -X DELETE "$worker_probe")" = 403 ] \ + || fail "worker key delete is not denied" + [ "$(worker_signed "${S3}/${BUCKET}?list-type=2")" = 403 ] \ + || fail "worker key list is not denied" + [ "$(worker_signed "$(list_url "$LIST_PREFIX")")" = 403 ] \ + || fail "worker key list ${LIST_PREFIX} is not denied" + [ "$(worker_signed -X PUT "${S3}/${CHECK_BUCKET_PREFIX}forbidden-$$")" = 403 ] \ + || fail "worker key bucket create is not denied" + [ "$(signed -X DELETE "$probe")" = 204 ] || fail "api key delete probe" + [ "$(signed -X DELETE "$worker_probe")" = 204 ] \ + || fail "api key delete worker probe" say "checks passed (api key put/get; cleaner key get/delete and list" \ - "${LIST_PREFIX}; api key list and bucket create, cleaner key put and" \ - "list of the bucket, anonymous get and list denied)" + "${LIST_PREFIX}; worker key put/get; api key list and bucket create," \ + "cleaner key put and list of the bucket, worker key delete, list and" \ + "bucket create, anonymous get and list denied)" } # адрес ListObjectsV2 своего bucket с префиксом $1 (символы [a-z0-9_.-/], @@ -432,6 +483,35 @@ run_checks() { "$(cleaner_signed -X PUT -H 'x-amz-acl: public-read' "${S3}/${BUCKET}?acl")" check "cleaner key put object acl public-read" 403 \ "$(cleaner_signed -X PUT -H 'x-amz-acl: public-read' "${obj}?acl")" + # ключ worker: чтение и запись объектов своего bucket, в том числе объект, + # записанный ключом API + worker_own="${S3}/${BUCKET}/${WORKER_CHECK_KEY}" + check "worker key put object" 200 \ + "$(worker_signed -X PUT --data-binary "$TAG worker" "$worker_own")" + check "worker key get object" 200 "$(worker_signed "$worker_own")" + check "worker key head object" 200 "$(worker_signed -I "$worker_own")" + check "worker key get object of api key" 200 "$(worker_signed "$obj")" + # ключ worker: удаление, список и всё, что с bucket, запрещено + check "worker key delete object" 403 "$(worker_signed -X DELETE "$worker_own")" + check "api key get object after worker delete" 200 "$(signed "$worker_own")" + check "worker key list objects" 403 \ + "$(worker_signed "${S3}/${BUCKET}?list-type=2")" + check "worker key list attachments prefix" 403 \ + "$(worker_signed "$(list_url "$LIST_PREFIX")")" + check "worker key create bucket" 403 \ + "$(worker_signed -X PUT "${S3}/${CHECK_BUCKET_PREFIX}forbidden-$$")" + check "worker key delete bucket" 403 \ + "$(worker_signed -X DELETE "${S3}/${BUCKET}")" + check "worker key get bucket policy" 403 \ + "$(worker_signed "${S3}/${BUCKET}?policy")" + check "worker key put bucket policy" 403 \ + "$(worker_signed -X PUT --data-binary '{"Version":"2012-10-17","Statement":[{"Effect":"Allow","Principal":"*","Action":"s3:GetObject","Resource":"arn:aws:s3:::'"${BUCKET}"'/*"}]}' "${S3}/${BUCKET}?policy")" + check "worker key get bucket acl" 403 \ + "$(worker_signed "${S3}/${BUCKET}?acl")" + check "worker key put bucket acl public-read" 403 \ + "$(worker_signed -X PUT -H 'x-amz-acl: public-read' "${S3}/${BUCKET}?acl")" + check "worker key put object acl public-read" 403 \ + "$(worker_signed -X PUT -H 'x-amz-acl: public-read' "${worker_own}?acl")" # чужой bucket: временный, создаёт и удаляет weed shell TEMP_BUCKET="${CHECK_BUCKET_PREFIX}$(od -An -N4 -tx4 /dev/urandom | tr -d ' ')" ws_step "temporary bucket create" "s3.bucket.create -name ${TEMP_BUCKET}" @@ -449,6 +529,12 @@ run_checks() { "$(cleaner_signed "${other}?list-type=2")" check "cleaner key delete other bucket" 403 \ "$(cleaner_signed -X DELETE "$other")" + check "worker key put object to other bucket" 403 \ + "$(worker_signed -X PUT --data-binary "$TAG" "${other}/probe")" + check "worker key get object from other bucket" 403 \ + "$(worker_signed "${other}/probe")" + check "worker key list other bucket" 403 \ + "$(worker_signed "${other}?list-type=2")" ws_step "temporary bucket delete" "s3.bucket.delete -name ${TEMP_BUCKET}" TEMP_BUCKET="" # аноним изнутри сервера; с хоста и из сети стенда — make s3_check @@ -468,7 +554,7 @@ run_checks() { } run_cleanup() { - for key in "$CHECK_KEY" "$CLEANER_CHECK_KEY"; do + for key in "$CHECK_KEY" "$CLEANER_CHECK_KEY" "$WORKER_CHECK_KEY"; do code=$(signed -X DELETE "${S3}/${BUCKET}/${key}") case "$code" in 204 | 404) say "probe object ${BUCKET}/${key} removed" ;; @@ -493,6 +579,7 @@ case "$MODE" in apply_policies apply_user "$API_USER" "$API_POLICY" apply_user "$CLEANER_USER" "$CLEANER_POLICY" + apply_user "$WORKER_USER" "$WORKER_POLICY" apply_checks ;; check) run_checks ;; diff --git a/migrations/versions/2026_10_31_1200-a1d4c7e90b23_added_attachment_jobs_and_variants.py b/migrations/versions/2026_10_31_1200-a1d4c7e90b23_added_attachment_jobs_and_variants.py new file mode 100644 index 00000000..67535f30 --- /dev/null +++ b/migrations/versions/2026_10_31_1200-a1d4c7e90b23_added_attachment_jobs_and_variants.py @@ -0,0 +1,187 @@ +"""added attachment jobs and variants + +Revision ID: a1d4c7e90b23 +Revises: 5c3e1f0a9b7d +Create Date: 2026-10-31 12:00:00.000000 + +""" + +from collections.abc import Sequence + +import sqlalchemy as sa +from alembic import op + +# revision identifiers, used by Alembic. +revision: str = "a1d4c7e90b23" +down_revision: str | Sequence[str] | None = "5c3e1f0a9b7d" +branch_labels: str | Sequence[str] | None = None +depends_on: str | Sequence[str] | None = None + + +def upgrade() -> None: + # expand (design change async-attachments, решение 1): колонки NULL без + # значения по умолчанию и новые таблицы; прежняя версия новых колонок не + # читает и не пишет. ACCESS EXCLUSIVE на attachments — lock_timeout, + # чтобы чужая долгая транзакция не остановила загрузки всех реплик в + # очереди за миграцией (migrations.md) + op.execute("SET LOCAL lock_timeout = '2s'") + op.add_column( + "attachments", + sa.Column("staging_key", sa.Text(), nullable=True), + ) + op.add_column( + "attachments", + sa.Column("error_code", sa.Text(), nullable=True), + ) + # ослабление статуса: прежние строки строже нового условия, поэтому + # NOT VALID в той же транзакции — VALIDATE держал бы блокировку на время + # просмотра таблицы, как ck_messages_text_length ревизии ef25d50b01a8. + # op.f: имя готовое, шаблон имён к нему не применяется + op.drop_constraint( + op.f("ck_attachments_status"), + "attachments", + type_="check", + ) + op.execute( + "ALTER TABLE attachments ADD CONSTRAINT ck_attachments_status " + "CHECK (status IN " + "('pending', 'queued', 'processing', 'ready', 'failed')) NOT VALID", + ) + op.execute( + "ALTER TABLE attachments ADD CONSTRAINT " + "ck_attachments_error_code_failed " + "CHECK ((status = 'failed') = (error_code IS NOT NULL)) NOT VALID", + ) + op.create_table( + "attachment_jobs", + sa.Column("id", sa.Uuid(), nullable=False), + sa.Column("attachment_id", sa.Uuid(), nullable=False), + sa.Column("pipeline_version", sa.Integer(), nullable=False), + sa.Column("state", sa.Text(), nullable=False), + sa.Column( + "attempt", + sa.Integer(), + server_default=sa.text("0"), + nullable=False, + ), + sa.Column("last_error_code", sa.Text(), nullable=True), + sa.Column( + "next_attempt_at", + sa.DateTime(timezone=True), + nullable=True, + ), + sa.Column( + "lease_expires_at", + sa.DateTime(timezone=True), + nullable=True, + ), + sa.Column( + "published_at", + sa.DateTime(timezone=True), + nullable=True, + ), + sa.Column("updated_at", sa.DateTime(timezone=True), nullable=False), + sa.Column("finished_at", sa.DateTime(timezone=True), nullable=True), + sa.Column("created_at", sa.DateTime(timezone=True), nullable=False), + sa.CheckConstraint( + "pipeline_version >= 1", + name=op.f("ck_attachment_jobs_pipeline_version"), + ), + sa.CheckConstraint( + "state IN ('queued', 'processing', 'succeeded', 'failed')", + name=op.f("ck_attachment_jobs_state"), + ), + sa.CheckConstraint( + "attempt >= 0", + name=op.f("ck_attachment_jobs_attempt"), + ), + sa.ForeignKeyConstraint( + ["attachment_id"], + ["attachments.id"], + name=op.f("fk_attachment_jobs_attachment_id_attachments"), + ), + sa.PrimaryKeyConstraint("id", name=op.f("pk_attachment_jobs")), + sa.UniqueConstraint( + "attachment_id", + "pipeline_version", + name=op.f("uq_attachment_jobs_attachment_id_pipeline_version"), + ), + ) + op.create_table( + "attachment_variants", + sa.Column("attachment_id", sa.Uuid(), nullable=False), + sa.Column("pipeline_version", sa.Integer(), nullable=False), + sa.Column("variant", sa.Text(), nullable=False), + sa.Column("object_key", sa.Text(), nullable=False), + sa.Column("content_type", sa.Text(), nullable=False), + sa.Column("size_bytes", sa.Integer(), nullable=False), + sa.Column("width", sa.Integer(), nullable=False), + sa.Column("height", sa.Integer(), nullable=False), + sa.Column("sha256", sa.LargeBinary(), nullable=False), + sa.Column("created_at", sa.DateTime(timezone=True), nullable=False), + sa.CheckConstraint( + "variant IN ('thumbnail', 'crop', 'optimized')", + name=op.f("ck_attachment_variants_variant"), + ), + sa.CheckConstraint( + "octet_length(object_key) BETWEEN 1 AND 1024", + name=op.f("ck_attachment_variants_object_key_length"), + ), + sa.CheckConstraint( + "content_type IN ('image/jpeg', 'image/png', 'image/webp')", + name=op.f("ck_attachment_variants_content_type"), + ), + sa.CheckConstraint( + "size_bytes > 0", + name=op.f("ck_attachment_variants_size_bytes"), + ), + sa.CheckConstraint( + "width > 0", + name=op.f("ck_attachment_variants_width"), + ), + sa.CheckConstraint( + "height > 0", + name=op.f("ck_attachment_variants_height"), + ), + sa.CheckConstraint( + "octet_length(sha256) = 32", + name=op.f("ck_attachment_variants_sha256_length"), + ), + sa.ForeignKeyConstraint( + ["attachment_id"], + ["attachments.id"], + name=op.f("fk_attachment_variants_attachment_id_attachments"), + ), + sa.PrimaryKeyConstraint( + "attachment_id", + "pipeline_version", + "variant", + name=op.f("pk_attachment_variants"), + ), + sa.UniqueConstraint( + "object_key", + name=op.f("uq_attachment_variants_object_key"), + ), + ) + + +def downgrade() -> None: + op.execute("SET LOCAL lock_timeout = '2s'") + op.drop_table("attachment_variants") + op.drop_table("attachment_jobs") + op.drop_constraint( + op.f("ck_attachments_error_code_failed"), + "attachments", + type_="check", + ) + op.drop_constraint( + op.f("ck_attachments_status"), + "attachments", + type_="check", + ) + op.execute( + "ALTER TABLE attachments ADD CONSTRAINT ck_attachments_status " + "CHECK (status IN ('pending', 'ready')) NOT VALID", + ) + op.drop_column("attachments", "error_code") + op.drop_column("attachments", "staging_key") diff --git a/openspec/changes/async-attachments/design.md b/openspec/changes/async-attachments/design.md index 4899c035..b033cc40 100644 --- a/openspec/changes/async-attachments/design.md +++ b/openspec/changes/async-attachments/design.md @@ -578,4 +578,24 @@ publish, потом COMMIT. Отвергнута: worker увидел бы за ## Уточнения apply -Пусто: заполняет `/opsx:apply`. +1. **`JobOutcome`: третий исход `DROP`** рядом с `ACK` и `REQUEUE` решения 7: сообщение не по схеме — `reject(requeue=False)`, а его решает сервис, а не `main.py`. +2. **`request_id` записей задания ставит сервис обработки** сразу после разбора, а не `main.py` (задача 7.3): разбор — его шаг, задача доставки своя, контекст не течёт. Сообщение не по схеме `request_id` не получает: задания нет. +3. **Сообщение с `attachment_id` не той строки задания** — как неизвестное: `ACK` без эффекта. Такого API не публикует; ключи берутся только из строки. +4. **Издатель проверяет `is_closed` канала перед публикацией** (`_get_channel`), вопреки решению 5, которое запрещало верить признаку: нашёл `driver.py defense-scenario`. Запрет относится к соединению. После рестарта брокера без единой загрузки издатель держал закрытый канал, и первая загрузка на каждой реплике получала 503 (`ChannelInvalidStateError`, 0 мс). В закрытый канал ничего не ушло, поэтому новое соединение — не повтор публикации. Проверяет `test_worker_survives_broker_restart`: загрузка только после возврата брокера. +5. **`Image.Transpose.FLIP_LEFT_RIGHT` равен 0:** проверка `if transpose := …` пропускала orientation 2. Нашла проба задачи 5.1, сверка с `ImageOps.exif_transpose`; тест `test_thumbnail_every_orientation` держит все восемь значений. +6. **`rabbitmqctl delete_queue` отсутствующей очереди** — код 64 и «No such queue was found», а не `not_found`: так проверяют `run_isolated.py` и hook. Нашёл первый `make test_isolated`. +7. **`delete-row` hook удаляет и задание с вариантами** одной транзакцией: FK без каскада иначе не дал бы удалить строку готового вложения. Новое действие `worker-log` — запись `error` журнала worker, которой требует спек, иначе тесту негде её увидеть. +8. **Две прежние проверки отказов сформулированы иначе,** worker теперь параллельно доводит задания прежних тестов, и равенство множеств стало бы гонкой: `ready_ids(after) == ready_ids(before)` в `test_upload_with_object_storage_stopped` → «новая строка одна, `pending`, задания нет»; «новых объектов нет» не считает объекты у `id`, известных до теста (`new_objects`). +9. **Дубль во время фиксации результата** таблица решения 7 не называет: фиксация держит строку задания, поэтому дубль ждёт блокировку и видит итог (`finished`), а не `busy`. `test_duplicate_during_processing` проверяет обе ветки: `busy` при замороженном S3 и `finished` при задержанной фиксации, `attempt` 1. +10. **Сверка фиксирует объект варианта строки, удалённой вручную:** у вложения без строки находка — и `original`, и `v1-thumbnail`, оба `orphan_object`; проверяют тесты расхождений. +11. **Время `make failure_checks`:** 99 проверок, pytest 1304 с, вся команда 1326 с (было 56, ~15 мин). Плюс больше ожидаемых ~5 мин design: 43 новые проверки, из них часть ждёт паузы повтора и grace. +12. **Регрессии задачи 10.10** (каждая откачена, хэши `src` совпали со снимком до них): + - ack до фиксации → `test_worker_killed_during_processing` красный: не `ready` за 60 с, последний статус `processing`; + - публикация без подтверждения → `test_upload_with_broker_paused` красный: 202 вместо 503; `test_upload_with_broker_stopped` зелёный, обрыв соединения публикация видит и так; + - очередь не `durable` → `test_broker_restart_keeps_job` красный, но раньше сценария: на входе `wait_queue_empty` очереди нет; причину (отказ брокера в объявлении или иное) не разбирал. На верном коде тот же запуск — зелёный; + - `Image.thumbnail` вместо своего расчёта → `test_thumbnail_rounding` красный на 1000 × 601; + - `failed` до захвата ключа → `test_replay_after_attachment_failed` красный: 409 вместо 201; + - сверка без ветки варианта → `test_reconcile_variant_objects` красный. +13. **S4 профиля `reconcile` с commit «до» лабы 5:** `make bench_reconcile_quick` падал на `S4-300-before-r1: missing_object found 101, injected 300`. Дефект с `cc33a03`, а не этого change: commit «до» стал `04f8592`, в нём ранний отказ по пределу уже есть, а проверка ждала все находки. В `run.py` обе ячейки теперь ждут `min(count, max_changes + 1)`; вердикт S4 «до и после» на этих commit ничего не показывает, правило `bench.md` это называет. Вариант «до» профиля `uploads` тоже уже с местами загрузок: H2 старой метки не воспроизводится (там же). +14. **Пик памяти thumbnail:** первая версия давала 484 МиБ на PNG RGBA 8000 × 5000 вместо ~323 пробы: `convert("RGBA")` в тот же режим копирует все пиксели. `_prepared` теперь отдаёт RGBA как есть, пик в контейнере образа с лимитом 1 ГБ — 332 МиБ. Правка внесена после полного `make failure_checks`, после неё перепроверены `-k "max_pixels or redelivery"` и `test_attachment_processing.py`. +15. **`make test_isolated` — код 2 до группы 15:** smoke `PASS`, 205 passed, 6 skipped (реплики), единственный failed — `test_exclusion_evidence_exists`; уборка полная. Проверено и `KEEP_TEST_DB=1` (остаются база, префикс, очередь; `broker-check --require-test-queue` — код 0), и прерывание SIGINT (код 130, ни контейнеров, ни базы, ни очереди). diff --git a/openspec/changes/async-attachments/tasks.md b/openspec/changes/async-attachments/tasks.md index 399d4375..b38eb754 100644 --- a/openspec/changes/async-attachments/tasks.md +++ b/openspec/changes/async-attachments/tasks.md @@ -27,12 +27,12 @@ evidence и `REPORT.md`: её запускает основная сессия ## 1. Зависимости, настройки, общие типы -- [ ] 1.1 Зависимости: `aio-pika>=10.2.1,<11` в основной группе, `pillow>=13,<14` из dev-группы +- [x] 1.1 Зависимости: `aio-pika>=10.2.1,<11` в основной группе, `pillow>=13,<14` из dev-группы в основную, `uv lock`. Проверка: `uv lock --check`; в `uv.lock` aio-pika 10.2.1, aiormq 7.2.4, pamqp 4.0.1, Pillow 13.0.0; `uv tree --no-dev` содержит обе. -- [ ] 1.2 Настройки по решению 13 и дельте `service-configuration`: +- [x] 1.2 Настройки по решению 13 и дельте `service-configuration`: - классы `Broker` и `Worker` в `src/config/settings.py`, пароль — `SecretStr`, как у `[s3]`; - `graceful_shutdown_seconds` не больше 9, сроки больше нуля, `concurrency` и `max_attempts` не меньше 1; @@ -42,7 +42,7 @@ evidence и `REPORT.md`: её запускает основная сессия значения по умолчанию; `BROKER__PUBLISH_TIMEOUT_SECONDS=0` и `=abc`, `WORKER__CONCURRENCY=0`, `WORKER__MAX_ATTEMPTS=abc`, `WORKER__GRACEFUL_SHUTDOWN_SECONDS=10` — ошибка проверки настроек называет поле. -- [ ] 1.3 Секреты и порты по решению 13: +- [x] 1.3 Секреты и порты по решению 13: - `.env.example`: блок брокера (`RABBITMQ_DEFAULT_USER`, `RABBITMQ_DEFAULT_PASS` пустой, `RABBITMQ_HOST`, `RABBITMQ_PORT`, `RABBITMQ_OUT_PORT`, мосты `BROKER__*`), ключи `S3_WORKER_*`, шапка с сопоставлением имён skeleton `BROKER_URL_FILE`, `WORKER_CONCURRENCY`, @@ -52,7 +52,7 @@ evidence и `REPORT.md`: её запускает основная сессия Проверка: подстановки рецепта `env_setup` дважды в поток, а не в файл: новые секреты непустые и различаются, сравнение по хэшу, значения не печатаются. `make env_setup` на рабочем каталоге печатает только имена дописанных переменных, повтор ничего не дописывает. -- [ ] 1.4 Общие типы: +- [x] 1.4 Общие типы: - `src/schemas/enums/attachment.py`: `AttachmentStatus` — ещё `queued`, `processing`, `failed`; новые `AttachmentJobState`, `AttachmentVariantName`, `AttachmentErrorCode`, `AttachmentJobReason`; @@ -66,11 +66,11 @@ evidence и `REPORT.md`: её запускает основная сессия ## 2. Схема -- [ ] 2.1 Модели по решению 1: новые колонки и CHECK `Attachment`, `AttachmentJob`, +- [x] 2.1 Модели по решению 1: новые колонки и CHECK `Attachment`, `AttachmentJob`, `AttachmentVariant` в `src/infra/db/models/attachment.py`. Проверка: `make lint`; совпадение со схемой — задача 2.2. -- [ ] 2.2 Ревизия поверх `5c3e1f0a9b7d` руками по решению 1 и `migrations.md`: первой строкой +- [x] 2.2 Ревизия поверх `5c3e1f0a9b7d` руками по решению 1 и `migrations.md`: первой строкой `SET LOCAL lock_timeout = '2s'`, колонки, замена CHECK статуса и новый CHECK `error_code` с `NOT VALID`, две таблицы, `downgrade`. @@ -87,12 +87,12 @@ evidence и `REPORT.md`: её запускает основная сессия ## 3. DTO и repo -- [ ] 3.1 DTO по `dto.md`: `AttachmentFullDTO` — `staging_key`, `error_code`, `variants` кортежем +- [x] 3.1 DTO по `dto.md`: `AttachmentFullDTO` — `staging_key`, `error_code`, `variants` кортежем по умолчанию; `AttachmentInListDTO.staging_key`; `AttachmentJobDTO`, `AttachmentVariantDTO`; `__init__.py`. Проверка: `make lint`. -- [ ] 3.2 `src/core/repos/attachment.py` по решениям 1–3 и `repo-layer.md`, одно выражение на +- [x] 3.2 `src/core/repos/attachment.py` по решениям 1–3 и `repo-layer.md`, одно выражение на функцию, `updated_at` через `greatest`: - `_ATTACHMENT_COLUMNS`, `_STALE_COLUMNS`, вставка со `staging_key`; - `mark_ready` заменяется на `mark_queued` с теми же условиями (`pending`, `updated_at = @@ -101,16 +101,16 @@ evidence и `REPORT.md`: её запускает основная сессия `ready` и `failed` с кодом. Проверка: `make lint`; поведение — группы 6–8 и 10. -- [ ] 3.3 `src/core/repos/attachment_job.py` по решениям 1, 3, 7: вставка, чтение с `FOR UPDATE`, +- [x] 3.3 `src/core/repos/attachment_job.py` по решениям 1, 3, 7: вставка, чтение с `FOR UPDATE`, чтение по вложению, начало попытки, возврат в `queued` с условием своей попытки, завершение, отметка `published_at`, условное удаление (`state = 'queued' AND attempt = 0`). Проверка: `make lint`; поведение — группы 6–7 и 10. -- [ ] 3.4 `src/core/repos/attachment_variant.py`: вставка `ON CONFLICT DO NOTHING` по ключу эффекта, +- [x] 3.4 `src/core/repos/attachment_variant.py`: вставка `ON CONFLICT DO NOTHING` по ключу эффекта, варианты вложения, один вариант по имени. Проверка: `make lint`; поведение — группы 6–7 и 10. -- [ ] 3.5 `src/core/repos/attachment_object.py` по решению 1: `staging_key`, `variant_key`, +- [x] 3.5 `src/core/repos/attachment_object.py` по решению 1: `staging_key`, `variant_key`, `parse_variant_key`; запись и чтение остаются по ключу. Проверка: разовый вызов `parse_variant_key`: свой `id` и `v1-thumbnail` — `id`, верхний регистр, @@ -118,7 +118,7 @@ evidence и `REPORT.md`: её запускает основная сессия ## 4. Брокер: сервис и клиент -- [ ] 4.1 Сервис `rabbitmq` по решению 4 и `docker.md`: +- [x] 4.1 Сервис `rabbitmq` по решению 4 и `docker.md`: - `docker-compose.yml`: образ с тегом и digest из решения 4, `hostname`, volume, порт, алиас, healthcheck, лимиты, `stop_grace_period`, якорь `x-broker-env`; - `infra/rabbitmq/rabbitmq.conf`, монтирование read-only длинной записью; @@ -131,7 +131,7 @@ evidence и `REPORT.md`: её запускает основная сессия - `docker compose stop rabbitmq` — код 0 раньше срока; - `docker compose up -d --force-recreate rabbitmq` — `healthy`, имя узла `rabbit@rabbitmq` прежнее; очередь с сообщениями после пересоздания — тест `test_broker_recreated`. -- [ ] 4.2 Клиент по решению 5: `src/infra/broker/client.py` (`JobPublisher`, `JobConsumer`, имя +- [x] 4.2 Клиент по решению 5: `src/infra/broker/client.py` (`JobPublisher`, `JobConsumer`, имя очереди из namespace, сброс соединения после любой ошибки), `aio_pika` и `aiormq` на `WARNING` в `src/infra/logger.py`, записи журнала по решению 18. @@ -142,7 +142,7 @@ evidence и `REPORT.md`: её запускает основная сессия - после возврата брокера следующая публикация проходит на том же объекте издателя; - потребитель получает сообщение, `prefetch_count` соблюдён, обрыв завершает его итератор; - значения пароля в выводе нет (сравнение с `.env` без печати). -- [ ] 4.3 Глобал API по решению 5: `src/infra/broker/instance.py`, `src/api/dependencies.py`, +- [x] 4.3 Глобал API по решению 5: `src/infra/broker/instance.py`, `src/api/dependencies.py`, закрытие в lifespan `src/main.py`, поля брокера в «Started API». Проверка: `make lint`; процесс API стартует и отвечает `/health/ready` при остановленном @@ -150,7 +150,7 @@ evidence и `REPORT.md`: её запускает основная сессия ## 5. Thumbnail -- [ ] 5.1 `src/utils/thumbnail.py` по решению 8. +- [x] 5.1 `src/utils/thumbnail.py` по решению 8. Проверка — разовый скрипт в scratchpad с генераторами `student-tests/images.py`: - 320 × 200 → 256 × 160, 100 × 50 и 256 × 256 без изменений, 1000 × 601 → 256 × 153, 601 × 1000 → @@ -164,24 +164,24 @@ evidence и `REPORT.md`: её запускает основная сессия ## 6. API -- [ ] 6.1 `AttachmentService` по решению 3: издатель в конструкторе и зависимости; `_store` пишет в +- [x] 6.1 `AttachmentService` по решению 3: издатель в конструкторе и зависимости; `_store` пишет в staging; `_mark_ready` → перевод в `queued` с заданием и той же компенсацией; публикация, отметка `published_at`, транзакция отмены; места загрузки держатся до ответа; записи журнала по решению 18, `filename` в них нет. Проверка: `make lint`; один PNG против консольного API и брокера стенда — 202, строка `queued`, объект только в staging, одно сообщение; сбои — тесты группы 10. -- [ ] 6.2 Чтение по решению 9: `pending` — 404, остальные — 200, варианты только у `ready`; +- [x] 6.2 Чтение по решению 9: `pending` — 404, остальные — 200, варианты только у `ready`; `open_content(variant=…)`: статус не `ready` — `AttachmentNotReady` без обращения к S3, нет варианта — 404, нет объекта варианта или другой размер — 500 с записью `error`; ветки оригинала и `lost_at` прежние. Проверка: `make lint`; поведение — тесты группы 10. -- [ ] 6.3 `MessageService` по решению 9: неизвестное, чужое и `pending` — 404 до ключа; `failed` — +- [x] 6.3 `MessageService` по решению 9: неизвестное, чужое и `pending` — 404 до ключа; `failed` — после захвата ключа: новый ключ — откат и `AttachmentFailed`, занятый — прежняя ветка повтора. Проверка: `make lint`; поведение — тесты группы 10, в том числе «Повтор после failed вложения». -- [ ] 6.4 HTTP по решению 9: `status_code=202`, `variant` как `Literal` четырёх значений, модель +- [x] 6.4 HTTP по решению 9: `status_code=202`, `variant` как `Literal` четырёх значений, модель `Attachment` с `status`, `variants`, `error_code`, модель варианта, `DOMAIN_ERRORS`, версия `1.5.0` в `create_app`. @@ -190,19 +190,19 @@ evidence и `REPORT.md`: её запускает основная сессия ## 7. Worker -- [ ] 7.1 Сообщение задания: pydantic-модель `src/schemas/jobs/attachment.py` (решение 7), сборка тела +- [x] 7.1 Сообщение задания: pydantic-модель `src/schemas/jobs/attachment.py` (решение 7), сборка тела из строки задания и номера попытки. Правило `dto.md` дополняется в задаче 13.1. Проверка: тело по `contracts/jobs.schema.json` (`jsonschema` dev-группы); лишнее поле, чужая `schema_version`, `attempt` 0, неверный `traceparent` — ошибка разбора; `traceparent` и `tracestate` по схеме проходят. -- [ ] 7.2 `AttachmentProcessingService` в `src/core/services/attachment_processing.py` по решениям 2 и 7: +- [x] 7.2 `AttachmentProcessingService` в `src/core/services/attachment_processing.py` по решениям 2 и 7: разбор, таблица claim, обработка под сроком, фиксация `ready` с вариантом одной транзакцией, временные и постоянные ошибки, недоступный PostgreSQL, исход `ACK` или `REQUEUE`; порядок блокировок — задание, затем вложение; журнал по дельте `service-logging`. Проверка: `make lint`; поведение — тесты группы 10. -- [ ] 7.3 Процесс `src/worker/` по решению 6: `__main__.py` (`early_stop.install("worker")`, «Invalid +- [x] 7.3 Процесс `src/worker/` по решению 6: `__main__.py` (`early_stop.install("worker")`, «Invalid worker settings», код 2, `os._exit`), `main.py` (сигналы, свои engine, S3 и клиенты брокера, цикл переподключения, ограниченная конкуренция, контекст `request_id`, остановка в срок, «Started worker» и «Stopped worker»). @@ -212,12 +212,12 @@ evidence и `REPORT.md`: её запускает основная сессия ## 8. Уборщик и сверка -- [ ] 8.1 Уборщик по решению 11: `staging_key` в выборках; `remove_stale_pending` удаляет `staging_key or +- [x] 8.1 Уборщик по решению 11: `staging_key` в выборках; `remove_stale_pending` удаляет `staging_key or object_key`, запись журнала называет удалённый ключ. Проверка: `make lint`; разовый `python -m src.cleaner --once` на стенде после 9.6 — код 0; поведение — тесты группы 10. Профиль `reconcile` со строками прежнего вида — задача 11.2. -- [ ] 8.2 Сверка по решению 11: разбор ключа варианта в `_list_objects`, `id` вариантов в выборке страницы, +- [x] 8.2 Сверка по решению 11: разбор ключа варианта в `_list_objects`, `id` вариантов в выборке страницы, ветка варианта в `_classify_object` (строка есть — пропуск, нет — объект без метаданных, свежий — свежий); находка зависшей загрузки называет ключ staging; `is_own_key` по-прежнему смотрит `object_key`. @@ -226,36 +226,36 @@ evidence и `REPORT.md`: её запускает основная сессия ## 9. Стенд -- [ ] 9.1 `docker-compose.yml` по решениям 6 и 10: сервис `worker`, `x-broker-env` и `depends_on` брокера у +- [x] 9.1 `docker-compose.yml` по решениям 6 и 10: сервис `worker`, `x-broker-env` и `depends_on` брокера у `api`, ключи `S3_WORKER_*` у `s3-bootstrap`. Проверка: `docker compose --env-file .env config --quiet`; `docker compose config` — секреты по сервисам по дельте `container-run`: пароль брокера только у `rabbitmq`, `api`, `worker`, ключи worker только у `s3-bootstrap` и `worker`, у `worker` нет пароля Valkey и ключей API и уборщика. -- [ ] 9.2 `infra/s3/bootstrap.sh` по решению 12: `apply_user worker worker-objects`, политика, ожидание ключа, +- [x] 9.2 `infra/s3/bootstrap.sh` по решению 12: `apply_user worker worker-objects`, политика, ожидание ключа, проверки `apply` и `check`, отказ на удаление и список; `driver.py s3-check` — строки ключа worker. Проверка на временном проекте compose (`-p` своё имя, `--env-file` — файл в scratchpad, порты свободные; без `down -v`: созданные volumes перечислить в отчёте и оставить основной сессии): первый запуск — «user worker created»; повтор дважды — «exists», код 0; новый секрет — ключ пересоздан, прежний отклонён; все запреты сценария «Запрещённые операции worker» — 403. -- [ ] 9.3 `Makefile`: `run_worker` (рецепт с `@`, ключи worker в окружение процесса), `run_dev` и `test_isolated` +- [x] 9.3 `Makefile`: `run_worker` (рецепт с `@`, ключи worker в окружение процесса), `run_dev` и `test_isolated` зависят от `start_broker`, текст `wipe_data` называет volume брокера, комментарии стенда. Проверка: `make run_worker` не печатает значения ключей; `make run_dev` и `make run_worker` — загрузка становится `ready`, «Started worker» называет адрес `127.0.0.1:$RABBITMQ_OUT_PORT`. -- [ ] 9.4 `scripts/restart.sh` по решению 14 (брокер в `restart` и `up --wait --no-recreate`), шапка; комментарии +- [x] 9.4 `scripts/restart.sh` по решению 14 (брокер в `restart` и `up --wait --no-recreate`), шапка; комментарии `scripts/rolling-update.sh` и `infra/haproxy/haproxy.cfg` — 29 с и 76 с. Проверка: `scripts/restart.sh` на стенде — код 0 не дольше 90 с, у брокера и реплик те же ID и новый `StartedAt`, у worker и уборщика прежний `StartedAt`, `RestartCount` 0; `haproxy -c` закреплённым образом. -- [ ] 9.5 CI по решению 14: `.github/ci/compose.yml` (`rabbitmq`, `worker`), `.github/ci/stand-env.sh` +- [x] 9.5 CI по решению 14: `.github/ci/compose.yml` (`rabbitmq`, `worker`), `.github/ci/stand-env.sh` (`CI_RABBITMQ_CONF`); шаги workflow не меняются. Проверка: `COMPOSE_FILE=docker-compose.yml:.github/ci/compose.yml`, `CI_IMAGE_TAG` и `. .github/ci/stand-env.sh`, `docker compose config --quiet` — без ошибок; в `docker compose config` у `rabbitmq` и `worker` нет `ports` и bind mount, у `rabbitmq` есть volume данных, а образ `worker` — тег прогона. -- [ ] 9.6 Рабочий стенд на рабочем дереве: `make run_docker`. +- [x] 9.6 Рабочий стенд на рабочем дереве: `make run_docker`. Проверка: - `docker compose ps` — две реплики, уборщик, worker, брокер и S3 в рабочем состоянии, bootstrap с кодом 0; @@ -270,40 +270,40 @@ evidence и `REPORT.md`: её запускает основная сессия ## 10. Тесты -- [ ] 10.1 Клиент и генераторы по решению 15: `api_client.py` (`upload` — 202 и снимок `queued`, `wait_attachment`, +- [x] 10.1 Клиент и генераторы по решению 15: `api_client.py` (`upload` — 202 и снимок `queued`, `wait_attachment`, `upload_ready`, скачивание варианта), `contract.py` (код 202, схема `Variant`, `assert_content` для варианта), `images.py` (JPEG с точностью 12 и с EXIF orientation, половины цветов, PNG с прозрачной половиной и палитрой с tRNS, большой PNG RGBA). Проверка: `make lint`; `wait_attachment` при остановленном worker падает и называет `queued` (сценарий «Worker не работает»). -- [ ] 10.2 Прежние сценарии вложений во всех модулях обычного набора (`test_attachments.py`, `test_messages.py`, +- [x] 10.2 Прежние сценарии вложений во всех модулях обычного набора (`test_attachments.py`, `test_messages.py`, `test_idempotency.py`, `test_rubric.py`, `test_data_storage.py`, `test_api_conventions.py`, `test_load_balancing.py` и другие, где есть загрузка): 202 и ожидание `ready` там, где нужны байты или итог; метаданные сравниваются по полям оригинала и отдельно по полям состояния; проверки не ослабляются и не пропускаются (спек `student-tests`, «Готовность вложения в тестах»). Проверка: `make student_test` через LB — прежние сценарии зелёные, красное только из шапки. -- [ ] 10.3 Новый модуль `test_attachment_processing.py` и новые тесты обычного набора по таблице «Покрытие сценариев» design: +- [x] 10.3 Новый модуль `test_attachment_processing.py` и новые тесты обычного набора по таблице «Покрытие сценариев» design: `test_attachment_becomes_ready`, `test_thumbnail_*`, `test_download_thumbnail`, `test_missing_variant`, `test_variant_outsider`, `test_message_with_failed_attachment`, `test_accepted_attachment_visible_on_other_replica`; маркеры `spec` дословно по сценариям дельт. Проверка: `uv run pytest student-tests/test_attachment_processing.py` с `BASE_URL` стенда; thumbnail скачан и его настоящие размеры, `sha256` и `size_bytes` сверены с метаданными варианта. -- [ ] 10.4 Hook `student-tests/fault_hook.py` по решению 15 и дельте `student-tests`: действия брокера и worker, `worker-state`, +- [x] 10.4 Hook `student-tests/fault_hook.py` по решению 15 и дельте `student-tests`: действия брокера и worker, `worker-state`, `queue-state`, `peek-job`, `publish-job`, `delete-queue`, `job`, `staging-ids`, `variant-object-count`; `put-object` и `delete-object` под префиксами вложений и staging; режимы `fail-attachments` на `queued` и `→ ready`; docstring. Ключи S3 и пароль брокера hook не получает и не печатает. Проверка: разбор `fs.tree` на образце (`original` и `v1-thumbnail` в одном каталоге, staging отдельно); hook отказывается работать с проектом рабочего стенда; поведение действий — тесты 10.6 и 10.7. -- [ ] 10.5 Стенд отказов по решению 15: `failures.compose.yml` (`rabbitmq` без порта, `worker` с короткими сроками, `restart: "no"`), +- [x] 10.5 Стенд отказов по решению 15: `failures.compose.yml` (`rabbitmq` без порта, `worker` с короткими сроками, `restart: "no"`), `run_failures.py` (брокер в `up --wait`, worker после bootstrap, `FAULT_WORKER_*`, журнал worker при падении, строка `start worker`, уборка), docstring. Проверка: `make failure_checks FAULT_ARGS='-k health'` — код 0, строка worker в выводе, стенд и volumes удалены; `-k no_such_test` — ненулевой код, журналы API, уборщика и worker напечатаны, стенд удалён. -- [ ] 10.6 Прежние проверки отказов `test_failures.py` по решению 15 и дельтам `attachments` и `storage-consistency`: +- [x] 10.6 Прежние проверки отказов `test_failures.py` по решению 15 и дельтам `attachments` и `storage-consistency`: - `upload_ready` и множества `id` там, где нужен готовый объект; - `test_ready_failure_compensated` → `test_queued_failure_compensated`, `test_ready_commit_outcome_unknown` → `test_queued_commit_outcome_unknown`; `test_killed_between_put_and_ready`, `test_upload_outlives_grace`, @@ -311,21 +311,21 @@ evidence и `REPORT.md`: её запускает основная сессия - тесты сверки: зависшая загрузка — объект в staging, готовые вложения — с объектами вариантов. Проверка: `make failure_checks FAULT_ARGS='-k "attachment or object_storage or cleaner or reconcile or upload"'` — код 0. -- [ ] 10.7 Новые проверки отказов по таблице «Покрытие сценариев» design: сценарии `attachment-processing`, `message-broker`, +- [x] 10.7 Новые проверки отказов по таблице «Покрытие сценариев» design: сценарии `attachment-processing`, `message-broker`, `messages`, `idempotency`, `health`, `attachments`, `storage-consistency`, а также `test_worker_stop_during_processing` (спек `graceful-shutdown` в докстринге). Отказы — в `with outage(...)`, worker запускается в `finally`, триггеры снимаются в `finally`. Сообщение проверяется по `contracts/jobs.schema.json`. Проверка: полный `make failure_checks` — код 0, сводка журнала PostgreSQL без признаков аварии, стенд удалён, у контейнеров рабочего стенда прежний `StartedAt`; время прогона — в design, «Уточнения apply». -- [ ] 10.8 `make test_isolated` по решению 15: `run_isolated.py` — контейнер `<проект>-test-worker` с той же подменой базы, журналы +- [x] 10.8 `make test_isolated` по решению 15: `run_isolated.py` — контейнер `<проект>-test-worker` с той же подменой базы, журналы обоих контейнеров, удаление очереди в начале и в конце, `KEEP_TEST_DB` печатает очередь; проверка имени очереди — как у префикса, иначе код 2. Проверка: `make test_isolated` при работающем стенде — код 0; после него нет контейнеров, базы, объектов и очереди временной базы, а сообщения и счётчики рабочей очереди и `StartedAt` рабочего стенда прежние; прерывание Ctrl+C — уборка выполнена; `KEEP_TEST_DB=1` — остаётся и печатается. -- [ ] 10.9 Сверка покрытия: +- [x] 10.9 Сверка покрытия: - `attachment-processing` и `message-broker` в `CAPABILITIES`, записи `EXCLUDED` с причинами и способом проверки по design (`message-broker` «Сервис брокера запущен», «Предел памяти брокера», «Остановка брокера», «Очереди разных баз разделены», `data-storage` «Ограничения обработки в схеме»); @@ -333,7 +333,7 @@ evidence и `REPORT.md`: её запускает основная сессия Проверка: `openspec validate --specs`; `make student_test` — сверка без «no test and no exclusion» и «unknown scenario», красное только `missing_evidence`; итог называет число сценариев проверок отказов с новыми. -- [ ] 10.10 Тесты ловят нарушение: временные регрессии, каждая откатывается и не попадает в рабочее дерево: +- [x] 10.10 Тесты ловят нарушение: временные регрессии, каждая откатывается и не попадает в рабочее дерево: - ack до фиксации результата → `test_worker_killed_during_processing` красный; - публикация без подтверждения → `test_upload_with_broker_stopped` или `test_upload_with_broker_paused` красный; - очередь не `durable` → `test_broker_restart_keeps_job` красный; @@ -345,11 +345,11 @@ evidence и `REPORT.md`: её запускает основная сессия ## 11. `bench/` -- [ ] 11.1 Стенд по решению 16: `bench.compose.yml` (`rabbitmq`, `worker`, лимиты), `bench.env`, `compose_env` (пароль брокера, ключи worker), поля +- [x] 11.1 Стенд по решению 16: `bench.compose.yml` (`rabbitmq`, `worker`, лимиты), `bench.env`, `compose_env` (пароль брокера, ключи worker), поля `Profile`, `SECRET_ENV_MARKS` покрывает новые имена, старт брокера в профиле загрузок, новый volume брокера на прогон, остатки и уборка. Проверка: `uv run python bench/uploads.py --selftest`; `make bench_quick` — код 0, брокер и worker не запущены, `stand.app_env` без секретов. -- [ ] 11.2 Профиль загрузок по решению 16: `k6/uploads.js`, `uploads.py` (`s201` — код успеха варианта, столбец `success_code` в конце, раздел паспорта), +- [x] 11.2 Профиль загрузок по решению 16: `k6/uploads.js`, `uploads.py` (`s201` — код успеха варианта, столбец `success_code` в конце, раздел паспорта), `run.py`, тексты сводки. Проверка: `make bench_uploads_quick` — код 0, успешные загрузки — 202, пик памяти реплики и 429 — в тех же границах, что у прежних сценариев спека; @@ -357,12 +357,12 @@ evidence и `REPORT.md`: её запускает основная сессия ## 12. Драйвер скилла `run-mtusi-messenger` -- [ ] 12.1 Прежние команды по решению 17: `start` поднимает брокер и worker, `upload`, `download`, `flow`, `attachment-failover`, `attachment-storage`, +- [x] 12.1 Прежние команды по решению 17: `start` поднимает брокер и worker, `upload`, `download`, `flow`, `attachment-failover`, `attachment-storage`, `upload-consistency`, `reconcile-*`, `s3-idle` — 202 и ожидание `ready`; заглушка реплики `lb-upload-timeouts` — 202; `attachment-storage` — ещё пробы ограничений обработки в откатываемой транзакции. Проверка: каждая из этих команд на рабочем стенде — код 0; `driver.py lb-upload-timeouts` — пять случаев с 202. -- [ ] 12.2 Новые команды по решению 17: `defense-scenario`, `broker-check [--require-test-queue]`, `worker-process`; раздел в `SKILL.md`: шаги, что +- [x] 12.2 Новые команды по решению 17: `defense-scenario`, `broker-check [--require-test-queue]`, `worker-process`; раздел в `SKILL.md`: шаги, что проверяется, коды выхода, gotchas. Проверка: @@ -373,7 +373,7 @@ evidence и `REPORT.md`: её запускает основная сессия ## 13. Правила и карта кода -- [ ] 13.1 Правила по решениям: +- [x] 13.1 Правила по решениям: - новое `.claude/rules/worker.md` с `paths` (`src/worker/**`, сервис обработки, `thumbnail.py`), строка в `AGENTS.md`, «Где лежат инструкции»; - `api-contract.md` — 202, 409, 404, `attachment_ids`; `api-layer.md` — параметр `variant`; - `service-layer.md`, `repo-layer.md`, `dto.md` (модель сообщения), `infra.md` (`broker/`), `migrations.md`, `logging.md`, `settings.md`, @@ -381,7 +381,7 @@ evidence и `REPORT.md`: её запускает основная сессия `bench.md`. Проверка: `grep -rn "201 Attachment\|mark_ready\|Pillow — только dev" .claude AGENTS.md` — только верные упоминания; `make lint`. -- [ ] 13.2 `AGENTS.md`: текущий статус, правила лабы 5, таблица важных файлов и команд, карта кода (`src/worker/`, `src/infra/broker/`, сервис обработки, +- [x] 13.2 `AGENTS.md`: текущий статус, правила лабы 5, таблица важных файлов и команд, карта кода (`src/worker/`, `src/infra/broker/`, сервис обработки, `thumbnail.py`, `infra/rabbitmq/`, новые модули и файлы тестов), время `make failure_checks`. `KNOWN_ISSUES.md` — разрыв COMMIT и publish до `pipeline-reliability`, смесь версий при замене. `QUESTIONS.md` — решения, принятые в apply. @@ -389,14 +389,14 @@ evidence и `REPORT.md`: её запускает основная сессия ## 14. Регресс на рабочем дереве -- [ ] 14.1 Смесь версий и откат по Migration Plan design на рабочем стенде: `docker compose stop worker cleaner`, `make rolling_update COMMIT=cc33a03 MIGRATE=0`, +- [x] 14.1 Смесь версий и откат по Migration Plan design на рабочем стенде: `docker compose stop worker cleaner`, `make rolling_update COMMIT=cc33a03 MIGRATE=0`, затем вперёд: `make rolling_update`, `docker compose up -d --no-deps cleaner worker`. Первое обновление с прежней версии под нагрузкой показывает `make bench_rollout_quick` (задача 14.3). Проверка: на прежнем образе сообщения и история — 200, загрузка — 201 `ready`, чтение вложения в новом статусе — 500 (названное ограничение); после возврата на текущий код `lb_stats` без ручных состояний, новые вложения становятся `ready`, вложение прежнего образа — 200, `variants` пуст, `variant=thumbnail` — 404, сверка без расхождений по нему. -- [ ] 14.2 Рабочий стенд: +- [x] 14.2 Рабочий стенд: - `make test` — `PASS: lab5`, `make validate`, `make check`; - `make student_test` через LB — красное только `missing_evidence`; - `make run_dev` с `make run_worker` и `EXPECT_REPLICAS=1 make student_test` — те же итоги, кроме тестов реплик; @@ -406,11 +406,11 @@ evidence и `REPORT.md`: её запускает основная сессия - `make s3_check`, `make reconcile` — код 0; - `driver.py --port defense-scenario`; - `make wipe_data` не выполнять: текст запроса и `docker compose config --volumes` проверить чтением. -- [ ] 14.3 Регресс `bench/`: `make bench_quick`, `make bench_failover_quick`, `make bench_rollout_quick` (обе фазы образов, новая миграция под нагрузкой без +- [x] 14.3 Регресс `bench/`: `make bench_quick`, `make bench_failover_quick`, `make bench_rollout_quick` (обе фазы образов, новая миграция под нагрузкой без ошибок), `make bench_restore_quick`, `make bench_uploads_quick`, `make bench_reconcile_quick` — код 0. -- [ ] 14.4 Сборка из чистого дерева: команда `git ls-files -z -co --exclude-standard | tar …` из `docker.md`; в образе импорт Pillow и aio-pika, версии как в +- [x] 14.4 Сборка из чистого дерева: команда `git ls-files -z -co --exclude-standard | tar …` из `docker.md`; в образе импорт Pillow и aio-pika, версии как в `uv.lock`, `uv` и компиляторов нет. `make lint`, `openspec validate async-attachments --strict`, `openspec validate --specs`. -- [ ] 14.5 Отчёт apply для основной сессии: `git status`, `git diff --stat`, предложенное сообщение коммита, созданные пробами volumes, что осталось красным и +- [x] 14.5 Отчёт apply для основной сессии: `git status`, `git diff --stat`, предложенное сообщение коммита, созданные пробами volumes, что осталось красным и почему. Агент останавливается здесь: коммит и группу 15 выполняет основная сессия. ## 15. Evidence и отчёт (после коммита, основная сессия) diff --git a/openspec/specs/attachment-processing/spec.md b/openspec/specs/attachment-processing/spec.md new file mode 100644 index 00000000..f407e1f4 --- /dev/null +++ b/openspec/specs/attachment-processing/spec.md @@ -0,0 +1,396 @@ +# attachment-processing Specification + +## Purpose + +Фоновая обработка принятого вложения с лабы 5. Здесь описано: +- состояния вложения и переходы между ними; +- задание в PostgreSQL и сообщение брокера; +- доставка at least once и подтверждение после устойчивого эффекта; +- публикация оригинала и thumbnail; +- идемпотентный эффект, ограниченные повторы и коды ошибок; +- worker как отдельный процесс и сохранность принятой работы. + +## Requirements + +### Requirement: Состояния вложения + +Вложение, принятое ответом 202, SHALL находиться в одном из состояний +API: `queued`, `processing`, `ready`, `failed`. Переходы: +- `queued` → `processing` — worker взял задание; зафиксированы номер + попытки и её срок; +- `processing` → `queued` — временная ошибка, попытки остались; + зафиксированы причина без секретов и время следующей попытки; +- `processing` → `ready` — оригинал и thumbnail записаны, а метаданные + вариантов и состояние зафиксированы одной транзакцией; +- `processing` → `failed` — ошибка постоянная или попытки исчерпаны; + зафиксированы код ошибки и запись для оператора. + +Готовое вложение MUST NOT возвращаться в другое состояние, в том числе +из-за повторной доставки. Отправка в `queued` из `failed` (replay) на +этом уровне не входит: `failed` окончательно. `error_code` SHALL быть +null во всех состояниях, кроме `failed`, `variants` — пустым во всех, +кроме `ready`. + +#### Scenario: Принятое вложение в очереди + +- **WHEN** worker остановлен, и участник загружает настоящий PNG +- **THEN** ответ 202 со `status` `queued`, а метаданные через несколько + секунд — 200 со `status` `queued`, `variants` `[]`, `error_code` null + +#### Scenario: Вложение становится готовым + +- **WHEN** worker работает, участник загружает `tests/fixtures/sample.png` + и опрашивает метаданные +- **THEN** не позже чем через 60 с `status` `ready`, `error_code` null, + а в `variants` ровно один элемент `thumbnail` + +#### Scenario: Обработка видна в API + +- **WHEN** worker взял задание, а фиксация его результата задержана +- **THEN** метаданные — 200 со `status` `processing`, скачивание — 409 + `conflict`, а после фиксации метаданные — `ready`, скачивание — 200 + +#### Scenario: Готовое вложение не откатывается + +- **WHEN** задание готового вложения доставлено ещё раз +- **THEN** метаданные совпадают с прежними во всех полях, включая + `updated_at` + +### Requirement: Задание в PostgreSQL + +Вложению SHALL соответствовать одно логическое задание на +`pipeline_version`; в курсе `pipeline_version` равен 1. У задания есть +идентификатор, вложение, версия, состояние, число начатых попыток, +причина последней ошибки, время следующей попытки, срок текущей попытки +и время, когда брокер подтвердил его последнее сообщение. + +Перевод вложения в `queued` и запись задания SHALL быть одной +транзакцией: это устойчивое намерение обработать файл. Идентификатор +задания MUST NOT меняться при повторах и повторной доставке. + +#### Scenario: Что сохранено к ответу 202 + +- **WHEN** worker остановлен, и участник получил ответ 202 +- **THEN** объект оригинала есть в staging, а в конечном префиксе его + нет, в PostgreSQL вложение `queued` и одно задание с нулём начатых + попыток и временем подтверждения брокером, а в очереди одно сообщение + +#### Scenario: Повторы под одним заданием + +- **WHEN** обработка вложения прошла две попытки и закончилась `ready` +- **THEN** задание у вложения одно, с тем же идентификатором, что после + первой попытки, а число начатых попыток — 2 + +### Requirement: Сообщение брокера + +Сообщение SHALL соответствовать `contracts/jobs.schema.json`: +`schema_version`, `job_id`, `type`, `attachment_id`, `pipeline_version`, +`attempt`, `created_at`. Сообщение MUST NOT содержать байты файла, имя +файла, ключи и адреса объектов, URL и учётные данные. Ключи объектов, +размер, SHA-256 и тип worker SHALL брать только из PostgreSQL. + +`attempt` начинается с 1 и растёт с каждой управляемой повторной +попыткой. Повторная доставка брокером нового `job_id` не создаёт. + +Сообщение не по схеме worker MUST NOT обрабатывать: он SHALL отбросить +его с записью уровня `error` без содержимого сообщения. Сообщение с +неизвестным заданием worker SHALL подтверждать без эффекта. + +#### Scenario: Сообщение по схеме + +- **WHEN** worker остановлен, участник загрузил файл с уникальным + `filename`, и сообщение прочитано из очереди без подтверждения +- **THEN** тело проходит проверку по `contracts/jobs.schema.json`, + `attachment_id` — это вложение, `attempt` — 1, а `filename`, ключей + объектов, адресов и учётных данных в сообщении нет + +#### Scenario: Сообщение не по схеме + +- **WHEN** в очередь попало сообщение, которое не проходит схему, а затем + участник загружает файл +- **THEN** чужое сообщение из очереди ушло, в журнале worker есть запись + `error`, а вложение становится `ready` + +#### Scenario: Неизвестное задание + +- **WHEN** в очередь попало сообщение по схеме с `job_id`, которого нет в + PostgreSQL +- **THEN** сообщение подтверждено, новых вложений и объектов не появилось + +### Requirement: Доставка at least once + +Worker SHALL подтверждать сообщение (ack) только после устойчивого +эффекта: в PostgreSQL зафиксировано `ready` или `failed`, либо следующая +попытка уже передана брокеру и подтверждена им. Если worker потерян до +подтверждения, брокер SHALL доставить сообщение снова, и задание +доводится до конца, в том числе если его состояние осталось +`processing`. + +Повторная доставка завершённого задания SHALL быть no-op с подтверждением +после проверки зафиксированного эффекта. + +Дубль сообщения, пока попытка другого worker идёт в свой срок, MUST NOT +порождать второй набор вариантов. + +Ограничение называется в `REPORT.md`. Зависший worker, у которого живо +соединение, на этом уровне освобождает задание только по сроку +подтверждения брокера; срок аренды и его восстановление — +`pipeline-reliability`. + +#### Scenario: Worker убит посреди обработки + +- **WHEN** worker завершён сигналом KILL, пока задание в `processing`, и + затем снова запущен +- **THEN** вложение становится `ready` с одним `thumbnail`, число начатых + попыток — 2, сообщений в очереди не осталось + +#### Scenario: Повторная доставка готового + +- **WHEN** в очередь для готового вложения снова попало сообщение его + задания +- **THEN** сообщение подтверждено, а метаданные, число вариантов и объекты + вариантов не изменились + +#### Scenario: Дубль во время обработки + +- **WHEN** пока попытка задания идёт, в очередь попадает ещё одно сообщение + этого задания +- **THEN** вложение становится `ready` с одним `thumbnail`, сообщений в + очереди не осталось + +### Requirement: Публикация оригинала + +Worker SHALL прочитать оригинал из staging по ключу из PostgreSQL, сверить +его размер и SHA-256 с метаданными вложения и записать те же байты в +конечный префикс. Оригинал SHALL оставаться неизменным: скачанные после +`ready` байты равны загруженным. Объект staging MUST NOT удаляться до +фиксации `ready`. + +Объект staging другого размера или с другим SHA-256 и его отсутствие — +постоянная ошибка `processing_failed`. Причина SHALL быть в записи для +оператора. + +Ограничение называется в `REPORT.md`. На этом уровне объект staging после +`ready` остаётся, а у `failed` не имеет срока хранения; очистка — +`pipeline-reliability`. + +#### Scenario: Оригинал неизменен + +- **WHEN** загруженный PNG стал `ready` +- **THEN** скачанный оригинал побайтно равен загруженному, а его SHA-256 + равен `sha256` метаданных, и объект есть и в конечном префиксе, и в + staging + +#### Scenario: Испорченный staging + +- **WHEN** worker остановлен, участник загрузил файл, объект staging + заменён другими байтами, и worker запущен +- **THEN** вложение `failed` с `error_code` `processing_failed`, число + начатых попыток — 1, а объекта в конечном префиксе нет + +#### Scenario: Нет объекта staging + +- **WHEN** worker остановлен, участник загрузил файл, объект staging + удалён, и worker запущен +- **THEN** вложение `failed` с `error_code` `processing_failed`, число + начатых попыток — 1 + +### Requirement: Thumbnail + +Thumbnail SHALL быть изображением JPEG, вписанным в 256 × 256 с +сохранением пропорций: +- большая сторона становится 256, меньшая вычисляется от неё и + округляется вниз, но не меньше 1 px; +- изображение, которое и так вписано в 256 × 256, MUST NOT увеличиваться; +- EXIF orientation SHALL применяться: размеры и содержимое thumbnail — как + у показанного с учётом ориентации; +- alpha SHALL компоноваться на белый, в том числе прозрачность палитры. + +Метаданные варианта SHALL содержать `name` `thumbnail`, `content_type` +`image/jpeg`, `size_bytes`, `sha256`, `width` и `height` записанного +объекта. Формат декодируется только как PNG или JPEG. Память декодирования +SHALL укладываться в лимит контейнера worker на изображении в лимит +контракта при настроенной конкуренции. + +#### Scenario: Fixture 320 × 200 + +- **WHEN** `tests/fixtures/sample.png` стал `ready`, и участник скачивает + `variant=thumbnail` +- **THEN** ответ 200 `image/jpeg`, настоящие размеры JPEG 256 × 160, а + `width`, `height`, `size_bytes` и `sha256` варианта совпадают со + скачанным объектом + +#### Scenario: Маленькое изображение не увеличивается + +- **WHEN** участник загружает PNG 100 × 50 и PNG 256 × 256 +- **THEN** размеры thumbnail — 100 × 50 и 256 × 256 + +#### Scenario: Округление вниз и минимум + +- **WHEN** участник загружает изображения 1000 × 601, 601 × 1000, + 5000 × 10 и 10 × 5000 +- **THEN** размеры thumbnail — 256 × 153, 153 × 256, 256 × 1 и 1 × 256 + +#### Scenario: EXIF orientation + +- **WHEN** участник загружает JPEG 400 × 200 с левой половиной красной и + правой синей и EXIF orientation 6 +- **THEN** thumbnail 128 × 256, его верхняя половина красная, а нижняя + синяя + +#### Scenario: Alpha на белый + +- **WHEN** участник загружает PNG с прозрачной половиной и PNG с палитрой + и прозрачностью +- **THEN** на месте прозрачных пикселей thumbnail белый + +#### Scenario: Разновидности форматов + +- **WHEN** участник загружает PNG с палитрой, с альфа-каналом, серый с + альфа-каналом, серый 16 бит, RGB 16 бит, 1 бит, чересстрочный и JPEG + прогрессивный, серый, CMYK, с EXIF и без таблиц Хаффмана +- **THEN** каждое вложение становится `ready`, а его thumbnail — настоящий + JPEG + +#### Scenario: Изображение в лимите пикселей + +- **WHEN** участник загружает столько PNG с альфа-каналом 8000 × 5000, сколько + заданий worker обрабатывает одновременно +- **THEN** каждое вложение становится `ready`, thumbnail 256 × 160, а контейнер + worker не завершён из-за памяти + +### Requirement: Идемпотентный эффект + +Ключ эффекта SHALL быть `(attachment_id, pipeline_version, variant)`. Из +него однозначно следует ключ объекта варианта, а метаданные варианта +уникальны по нему в PostgreSQL. Повтор задания MUST NOT создавать второй +набор вариантов: он пишет те же ключи объектов. Метаданные вариантов и +состояние `ready` SHALL фиксироваться одной транзакцией: вложение `ready` +без метаданных варианта MUST NOT появляться. + +#### Scenario: Повтор после записи объектов + +- **WHEN** объекты вложения записаны, а фиксация `ready` не удалась, и + worker выполняет следующую попытку +- **THEN** вложение `ready`, у него один вариант `thumbnail`, а объект + варианта в bucket один, и его SHA-256 равен `sha256` варианта + +### Requirement: Ограниченные повторы + +Временная ошибка — недоступность или отказ S3, истёкший срок попытки или +другая непредвиденная ошибка — SHALL вести к новой попытке, пока их число +не достигло `[worker] max_attempts` (`service-configuration`, «Параметры +worker»). Между попытками вложение SHALL быть в `queued`, новая попытка +начинается не раньше паузы `[worker] retry_delay_seconds`. Сообщение новой +попытки несёт тот же `job_id` и `attempt` на единицу больше. + +Каждая начатая попытка считается, в том числе та, в которой worker был +потерян. Когда попытки исчерпаны, вложение SHALL стать `failed` с +`error_code` `retry_exhausted`. Бесконечный немой повтор MUST NOT +происходить. Пока недоступен PostgreSQL, исход записать нельзя: задание +остаётся в очереди, попытки не считаются, а журнал worker называет отказ. + +Ограничение называется в `REPORT.md`. Пауза постоянна, поэтому отказ S3 +дольше суммы пауз и сроков переводит взятые задания в `failed`; backoff с +jitter и replay — `pipeline-reliability`. + +#### Scenario: Временная ошибка + +- **WHEN** S3 остановлен, worker взял задание, и S3 возвращается раньше, + чем исчерпаны попытки +- **THEN** вложение становится `ready`, число начатых попыток больше 1, а + у задания тот же идентификатор + +#### Scenario: Состояние между попытками + +- **WHEN** попытка задания закончилась временной ошибкой, и попытки остались +- **THEN** до следующей попытки метаданные — `queued` с `error_code` null, + а в записи задания есть причина и время следующей попытки + +#### Scenario: Попытки исчерпаны + +- **WHEN** S3 остановлен дольше, чем длятся все попытки задания +- **THEN** вложение становится `failed` с `error_code` `retry_exhausted`, + число начатых попыток равно `max_attempts`, сообщений в очереди не + осталось, а после возврата S3 состояние прежнее + +#### Scenario: PostgreSQL недоступен при обработке + +- **WHEN** PostgreSQL останавливается, пока в очереди есть задание, а затем + снова запускается +- **THEN** worker без перезапуска доводит задание до `ready`, сообщений в + очереди не осталось + +### Requirement: Постоянные ошибки и коды + +Ошибка, которую повтор не исправит, SHALL сразу вести к `failed`, без +новых попыток. Коды `error_code`: +- `invalid_image` — изображение прошло проверку при загрузке, но не + декодируется; +- `processing_failed` — объект staging отсутствует или испорчен; +- `retry_exhausted` — попытки исчерпаны. + +`error_code` MUST NOT содержать stack trace, пути, ключи и адреса. Причину +SHALL называть запись задания и журнал worker, доступные оператору. + +#### Scenario: Изображение не декодируется + +- **WHEN** участник загружает JPEG с 12 битами на компоненту, который + проходит проверку структуры, но не декодируется +- **THEN** ответ 202, затем вложение `failed` с `error_code` `invalid_image`, + число начатых попыток — 1, вариантов нет, а скачивание — 409 `conflict` + +### Requirement: Worker — отдельный процесс + +Обработку SHALL выполнять worker — отдельный процесс стенда (`container-run`). +Реплики API MUST NOT декодировать изображения и создавать варианты ни при +каких обстоятельствах, в том числе когда worker недоступен. Worker SHALL +обрабатывать одновременно не больше `[worker] concurrency` заданий, а брокер +выдаёт ему не больше стольких неподтверждённых сообщений. + +#### Scenario: Worker недоступен + +- **WHEN** worker остановлен, и участник загружает файл, отправляет текст и + читает историю +- **THEN** загрузка — 202, вложение `queued`, вариантов нет, отправка — 201, + история — 200, `/health/ready` — 200 + +#### Scenario: Ограниченная конкуренция + +- **WHEN** в очереди заданий больше, чем `[worker] concurrency`, и фиксация + результатов задержана +- **THEN** неподтверждённых сообщений и вложений в `processing` не больше + `concurrency`, а остальные задания — `queued`, и все они затем становятся + `ready` + +### Requirement: Принятая работа переживает рестарты + +Работа, на которую ответили 202, MUST NOT теряться при остановке API, worker +и брокера с сохранённым volume. Клиент узнаёт итог опросом метаданных. + +#### Scenario: Реплика API убита после ответа + +- **WHEN** участник получил 202, и реплика API сразу завершена сигналом KILL +- **THEN** вложение становится `ready`, а метаданные и thumbnail читаются + после возврата реплики + +#### Scenario: Рестарт брокера с volume + +- **WHEN** worker остановлен, участник получил 202, брокер перезапущен с + сохранённым volume, а затем worker запущен +- **THEN** вложение становится `ready` + +#### Scenario: Принудительное завершение брокера + +- **WHEN** worker остановлен, участник получил 202 на несколько загрузок, + брокер сразу завершён сигналом KILL и запущен снова, а затем worker + запущен +- **THEN** каждое вложение становится `ready` + +#### Scenario: Сценарий защиты + +- **WHEN** worker остановлен, участник загрузил файл (202), отправил сообщение + с этим вложением (201), скачивание дало 409, текстовое сообщение — 201, + затем перезапущены API и брокер с сохранёнными volumes и запущен worker +- **THEN** то же вложение становится `ready`, его оригинал равен загруженному, а + thumbnail — настоящий JPEG, и сообщение отдаёт `attachment_ids` с ним diff --git a/openspec/specs/attachments/spec.md b/openspec/specs/attachments/spec.md index 91c0b822..3550fa52 100644 --- a/openspec/specs/attachments/spec.md +++ b/openspec/specs/attachments/spec.md @@ -16,26 +16,27 @@ `POST /api/v1/chats/{chat_id}/attachments?filename=<имя>` SHALL принимать тело — сырые байты одного изображения PNG или JPEG, не multipart и не JSON, с `Content-Type: image/png` или `image/jpeg`. При -успехе ответ SHALL быть 201 с объектом `Attachment` без других полей: +успехе ответ SHALL быть 202 с объектом `Attachment` без других полей: - `id` — новый UUID, его назначает сервер; - `chat_id` — чат из пути, `owner_id` — текущий пользователь; - `filename` — переданное имя без изменений; - `content_type` — тип, определённый по содержимому; - `size_bytes` и `sha256` (64 шестнадцатеричных символа в нижнем регистре) — размер и SHA-256 принятых байтов; -- `status` — `ready`, `variants` — `[]`, `error_code` — null; +- `status` — `queued`, `variants` — `[]`, `error_code` — null; - `created_at` и `updated_at` — время сервера в RFC 3339 UTC. -Ответ 201 SHALL означать, что сохранены и оригинал, и метаданные -(требование «Порядок записи»). Загрузку может выполнить любой участник -чата. +Это снимок на момент приёма: быстрый worker мог закончить раньше ответа, и +готовность клиент SHALL узнавать по метаданным. Ответ 202 SHALL означать, что +устойчиво сохранены оригинал, метаданные и задание обработки (требование +«Порядок записи»). Загрузку может выполнить любой участник чата. #### Scenario: Загрузка PNG - **WHEN** Алиса загружает в свой чат публичный fixture `tests/fixtures/sample.png` с `Content-Type: image/png` и `filename=sample.png` -- **THEN** ответ 201, `status` `ready`, `variants` `[]`, `error_code` +- **THEN** ответ 202, `status` `queued`, `variants` `[]`, `error_code` null, `owner_id` — Алиса, `chat_id` — этот чат, `filename` `sample.png`, `content_type` `image/png`, `size_bytes` 111817, а `sha256` равен SHA-256 файла @@ -44,7 +45,7 @@ multipart и не JSON, с `Content-Type: image/png` или `image/jpeg`. При - **WHEN** Боб загружает в общий с Алисой чат настоящий JPEG с `Content-Type: image/jpeg` -- **THEN** ответ 201, `content_type` `image/jpeg`, `owner_id` — Боб, а +- **THEN** ответ 202, `content_type` `image/jpeg`, `owner_id` — Боб, а `size_bytes` и `sha256` совпадают с размером и SHA-256 файла #### Scenario: Разновидности PNG и JPEG @@ -53,7 +54,7 @@ multipart и не JSON, с `Content-Type: image/png` или `image/jpeg`. При оттенках серого с альфа-каналом, 16 и 1 бит на канал, чересстрочный (Adam7), а также JPEG прогрессивный, в оттенках серого, CMYK, с EXIF и baseline без таблиц Хаффмана (кадр Motion JPEG) -- **THEN** каждый ответ 201 с `content_type` по формату файла +- **THEN** каждый ответ 202 с `content_type` по формату файла ### Requirement: Лимит размера до чтения тела @@ -74,7 +75,7 @@ SHALL отдаваться без чтения тела. Без `Content-Length` - **WHEN** участник загружает настоящий PNG размером ровно 10 485 760 байт, а затем такой же PNG на один байт длиннее -- **THEN** первый ответ 201, второй — 413 `payload_too_large` +- **THEN** первый ответ 202, второй — 413 `payload_too_large` #### Scenario: Заявленный размер больше лимита @@ -117,7 +118,7 @@ SHALL отдаваться без чтения тела. Без `Content-Length` #### Scenario: Ровно 40 млн пикселей - **WHEN** участник загружает настоящий PNG 8000 × 5000 пикселей -- **THEN** ответ 201 +- **THEN** ответ 202, и вложение становится `ready` #### Scenario: Данные длиннее размеров @@ -153,7 +154,7 @@ PNG — `image/png`, маркер начала JPEG — `image/jpeg`. Ответ - **WHEN** участник загружает настоящий PNG с `Content-Type` `application/octet-stream`, `text/plain` и без `Content-Type`, а затем с `Content-Type: IMAGE/PNG; charset=binary` -- **THEN** первые три ответа 415, последний — 201 +- **THEN** первые три ответа 415, последний — 202 ### Requirement: Повреждённое изображение @@ -190,7 +191,9 @@ PNG — `image/png`, маркер начала JPEG — `image/jpeg`. Ответ формата нет контрольной суммы. Таблицы Хаффмана 0 и 1 непрогрессивного кадра без DHT декодеры берут стандартные (кадры Motion JPEG), поэтому такой JPEG принимается. Пустые данные скана с кодами Хаффмана — -обрыв: код даёт хотя бы бит на блок. +обрыв: код даёт хотя бы бит на блок. Изображение, которое прошло эту +проверку, но не декодируется при обработке, становится `failed` +(`attachment-processing`, «Постоянные ошибки и коды»). #### Scenario: Обрезанный файл @@ -217,8 +220,8 @@ PNG — `image/png`, маркер начала JPEG — `image/jpeg`. Ответ - **WHEN** участник загружает PNG и JPEG, к которым дописаны байты после IEND и EOI -- **THEN** оба ответа 201, `size_bytes` и `sha256` учитывают дописанные - байты, а скачанный оригинал содержит их +- **THEN** оба ответа 202, `size_bytes` и `sha256` учитывают дописанные + байты, а скачанный оригинал готового вложения содержит их ### Requirement: Имя файла @@ -251,7 +254,7 @@ U+FFFD MUST NOT превращать отказ в принятое имя. - **WHEN** участник загружает настоящий PNG с `filename=a%FFb.png`, `filename=a%C3.png` и `filename=a%ED%A0%80b.png`, а затем с `filename=%C3%A9t%C3%A9.png` -- **THEN** первые три ответа 400 `invalid_request`, последний — 201 с +- **THEN** первые три ответа 400 `invalid_request`, последний — 202 с `filename` `été.png` #### Scenario: Опасное имя @@ -266,14 +269,14 @@ U+FFFD MUST NOT превращать отказ в принятое имя. - **WHEN** участник загружает файл с `filename` из 255 code points: кириллица, emoji с ZWJ и пробелы по краям -- **THEN** ответ 201, а `filename` в ответе загрузки и в метаданных +- **THEN** ответ 202, а `filename` в ответе загрузки и в метаданных совпадает с переданным #### Scenario: Символы форматирования в имени - **WHEN** участник загружает файлы, в `filename` которых есть U+202E, U+2066 с U+2069, U+2028 и мягкий перенос U+00AD -- **THEN** каждый ответ 201, а `filename` в ответе загрузки и в +- **THEN** каждый ответ 202, а `filename` в ответе загрузки и в метаданных совпадает с переданным ### Requirement: Порядок проверок загрузки @@ -323,14 +326,14 @@ U+FFFD MUST NOT превращать отказ в принятое имя. Метаданные и байты вложения SHALL быть доступны любому участнику чата вложения, а не только владельцу. Посторонний, неизвестный `id` и -вложение, загрузка которого не завершена, SHALL получать одинаковый 404 -`not_found`. Запрос без действительной сессии — 401, `attachment_id` не -UUID — 400 `invalid_request`. +вложение, загрузка которого не завершена (ответа 202 ещё не было), +SHALL получать одинаковый 404 `not_found`. Запрос без действительной +сессии — 401, `attachment_id` не UUID — 400 `invalid_request`. #### Scenario: Другой участник -- **WHEN** Алиса загрузила вложение в чат с Бобом, и Боб запрашивает - его метаданные и байты +- **WHEN** Алиса загрузила вложение в чат с Бобом, оно стало `ready`, и Боб + запрашивает его метаданные и байты - **THEN** оба ответа 200 #### Scenario: Посторонний и неизвестный id @@ -353,29 +356,40 @@ UUID — 400 `invalid_request`. ### Requirement: Метаданные вложения -`GET /api/v1/attachments/{attachment_id}` SHALL отвечать 200 с -объектом `Attachment`, равным ответу на загрузку этого вложения. +`GET /api/v1/attachments/{attachment_id}` SHALL отвечать 200 с объектом +`Attachment` во всех состояниях `queued`, `processing`, `ready` и `failed` +(`attachment-processing`, «Состояния вложения»). Поля `id`, `chat_id`, +`owner_id`, `filename`, `content_type`, `size_bytes`, `sha256` и `created_at` +SHALL совпадать с ответом на загрузку. `size_bytes`, `sha256` и `content_type` +всегда описывают оригинал, у вариантов — свои поля. `status`, `variants`, +`error_code` и `updated_at` SHALL отражать текущее состояние. У готового вложения +`variants` содержит каждый записанный вариант; вложение, ставшее готовым до этого +изменения, вариантов не имеет. #### Scenario: Метаданные равны ответу загрузки - **WHEN** Алиса загрузила вложение, а Боб запрашивает его метаданные -- **THEN** ответ 200, JSON совпадает с ответом на загрузку во всех - полях +- **THEN** ответ 200, поля, описывающие оригинал, совпадают с ответом на + загрузку, а когда вложение становится `ready`, — `error_code` null и + непустые `variants` ### Requirement: Скачивание оригинала `GET /api/v1/attachments/{attachment_id}/content` SHALL отвечать 200 с -байтами оригинала без изменений: их размер и SHA-256 равны `size_bytes` -и `sha256` вложения. Заголовки ответа: +байтами оригинала без изменений, если вложение `ready`: их размер и +SHA-256 равны `size_bytes` и `sha256` вложения. Заголовки ответа: - `Content-Type` — `content_type` вложения без параметров; - `Content-Length` — размер оригинала; - `X-Content-Type-Options: nosniff`. Байты SHALL отдавать API, ответ MUST NOT быть перенаправлением. -Параметр `variant` SHALL принимать только `original`, это и значение по -умолчанию. Любое другое значение — 400 `invalid_request`. Ключ объекта, -адрес и учётные данные S3 MUST NOT попадать ни в тело, ни в заголовки -ответов API. +Параметр `variant` SHALL принимать `original`, `thumbnail`, `crop` и +`optimized`, по умолчанию `original`. Любое другое значение — 400 +`invalid_request`. Ключ объекта, адрес и учётные данные S3 MUST NOT +попадать ни в тело, ни в заголовки ответов API. + +Если вложение `queued`, `processing` или `failed`, ответ на любой `variant` +SHALL быть 409 `conflict` без обращения к S3. Если у готового вложения нет объекта в S3 или его размер не равен `size_bytes`, а сверка хранилищ это ещё не подтвердила, это @@ -391,22 +405,22 @@ UUID — 400 `invalid_request`. #### Scenario: Побайтный оригинал -- **WHEN** Боб скачивает PNG и JPEG, загруженные Алисой +- **WHEN** Боб скачивает готовые PNG и JPEG, загруженные Алисой - **THEN** каждый ответ 200, не перенаправление, байты совпадают с загруженными, `Content-Type` — `image/png` и `image/jpeg`, `Content-Length` равен размеру, есть `X-Content-Type-Options: nosniff` #### Scenario: Вариант original -- **WHEN** участник скачивает вложение с `variant=original`, а затем с - `variant=thumbnail` и с пустым `variant` +- **WHEN** участник скачивает готовое вложение с `variant=original`, а + затем с `variant=big` и с пустым `variant` - **THEN** первый ответ 200 с теми же байтами, остальные — 400 `invalid_request` #### Scenario: Без следов хранилища в ответе - **WHEN** участник загружает вложение, читает метаданные и скачивает - байты + байты готового вложения и его thumbnail - **THEN** в телах ответов нет полей вне схемы контракта, а в заголовках нет `Location` и заголовков `x-amz-*` @@ -416,64 +430,91 @@ UUID — 400 `invalid_request`. `--apply` пометила его оригинал потерянным - **THEN** скачивание до сверки — 500 `internal_error`, после неё — 404 `not_found` -- **AND** метаданные и до, и после — 200 с тем же JSON, что у ответа на - загрузку +- **AND** метаданные и до, и после — 200 с тем же JSON + +#### Scenario: Скачивание до готовности + +- **WHEN** участник скачивает вложение в `queued`, `processing` и `failed`, + без `variant`, с `variant=original` и с `variant=thumbnail` +- **THEN** каждый ответ 409 `conflict` в формате ошибки ### Requirement: Где хранятся вложения -Метаданные вложения SHALL храниться в PostgreSQL, байты оригинала — -одним объектом в приватном bucket S3 (`object-storage`). Байты MUST -NOT храниться ни в PostgreSQL, ни в файлах реплики API. Ключ объекта -назначает сервер: имя базы, `/attachments/`, `id` вложения и -`/original`. Каждая загрузка SHALL создавать новое вложение и новый -объект, в том числе повтор той же загрузки: прозрачных повторов -загрузки нет (`contracts/README.md`). +Метаданные вложения SHALL храниться в PostgreSQL, байты — объектами в +приватном bucket S3 (`object-storage`). Байты MUST NOT храниться ни в +PostgreSQL, ни в файлах реплики API и worker. Ключ объекта назначает +сервер, `filename` в него MUST NOT входить: +- устойчивый staging — `<база>/staging//original`; +- конечный оригинал — `<база>/attachments//original`; +- вариант — `<база>/attachments//v-<вариант>`. + +Staging и конечный префикс — один и тот же сервер S3 и bucket. Устойчивость +staging — устойчивость этого сервера. Граница называется в `REPORT.md`: +отказ диска или ВМ теряет и то, и другое. + +Каждая загрузка SHALL создавать новое вложение и новые объекты, в том +числе повтор той же загрузки: прозрачных повторов загрузки нет +(`contracts/README.md`). #### Scenario: Байты не в БД и не на диске API -- **WHEN** после загрузок через балансировщик проверяющий смотрит - схему таблиц вложений, ключи объектов в PostgreSQL, объекты в bucket - и изменения файловой системы контейнеров реплик API -- **THEN** в таблицах нет колонки с байтами изображения, ключ каждого - объекта имеет вид `<база>/attachments//original` и не содержит - `filename`, объект с этим ключом есть в bucket, анонимный GET его - ключа — 403, а в контейнерах реплик нет файлов оригиналов +- **WHEN** после загрузок через балансировщик вложения стали `ready`, и + проверяющий смотрит схему таблиц вложений, ключи объектов в PostgreSQL, + объекты в bucket и изменения файловой системы контейнеров реплик API и + worker +- **THEN** в таблицах нет колонки с байтами изображения, ключи объектов + имеют вид из требования и не содержат `filename`, объекты с этими + ключами есть в bucket, анонимный GET их ключей — 403, а в контейнерах + реплик и worker нет файлов оригиналов и вариантов #### Scenario: Повторная загрузка - **WHEN** участник дважды загружает один и тот же файл -- **THEN** оба ответа 201 с разными `id` и одинаковым `sha256`, и оба - вложения скачиваются +- **THEN** оба ответа 202 с разными `id` и одинаковым `sha256`, и оба + вложения становятся `ready` и скачиваются ### Requirement: Порядок записи Загрузка SHALL выполняться по шагам: 1. проверки и чтение тела; 2. запись метаданных в статусе «загружается» (`pending`) вместе с - ключом объекта, фиксация в PostgreSQL; -3. запись объекта в S3; -4. статус `ready`, фиксация; -5. ответ 201. + ключами объектов, фиксация в PostgreSQL; +3. запись оригинала в staging; +4. статус `queued` и задание обработки — одной транзакцией; +5. публикация задания брокеру и его подтверждение (`message-broker`); +6. ответ 202. Объект, который записал API, SHALL быть известен PostgreSQL до записи в -S3: без зафиксированных метаданных объект не записывается. Вложение не -в статусе `ready` MUST NOT быть видно через API: его метаданные и байты +S3: без зафиксированных метаданных объект не записывается. Вложение в +статусе `pending` MUST NOT быть видно через API: его метаданные и байты — 404, ссылка на него в сообщении — 404. Сбой после шага 2 из-за отказа хранилища SHALL давать 503 -`unavailable`, а не 500. Отказ — S3 или PostgreSQL недоступен, не -ответил за срок или отказал. Метаданные «загружается» при этом +`unavailable`, а не 500. Отказ — S3, PostgreSQL или брокер недоступен, +не ответил за срок или отказал. Метаданные «загружается» при этом остаются. Их и объект убирает уборщик после grace period (capability `storage-consistency`). Компенсация — сверх этого: -- объект записан, а перевод в `ready` не удался до того, как фиксация - отправлена в PostgreSQL. API SHALL удалить записанный объект до - ответа. Удаление не гарантировано: если оно не удалось, объект убирает - уборщик; -- исход фиксации `ready` неизвестен: связь оборвалась во время - фиксации. API MUST NOT удалять объект — вложение могло стать `ready`; +- объект записан, а шаг 4 не удался до того, как фиксация отправлена в + PostgreSQL. API SHALL удалить записанный объект до ответа. Удаление не + гарантировано: если оно не удалось, объект убирает уборщик; +- исход фиксации шага 4 неизвестен: связь оборвалась во время фиксации. + API MUST NOT удалять объект — вложение могло стать `queued`; - к шагу 4 метаданных «загружается» уже нет или уборщик уже начал их уборку, потому что загрузка длилась дольше grace. Ответ SHALL быть - 503 `unavailable`, и API SHALL удалить записанный объект. + 503 `unavailable`, и API SHALL удалить записанный объект; +- брокер не подтвердил задание на шаге 5. API SHALL вернуть вложение в + `pending`, отменить задание и ответить 503 `unavailable`: 202 без + подтверждения брокера MUST NOT отдаваться. Объект убирает уборщик. + Сообщение, дошедшее до брокера после отмены, worker подтверждает без + эффекта. Если worker уже взял задание, сообщение дошло: ответ SHALL + быть 202. + +Ограничение называется в `REPORT.md`, это разрыв между фиксацией и +публикацией на этом уровне. Если процесс API завершился между шагами 4 +и 5 или не смог отменить задание, клиент 202 не получил, а вложение +остаётся `queued` с заданием без подтверждения брокера, и его никто не +публикует. Принятая работа при этом не теряется: 202 не было. Закрывает +разрыв `pipeline-reliability`. Если запись метаданных на шаге 2 не удалась, объект MUST NOT записываться; отказ PostgreSQL при этом — 503 `unavailable`. Загрузка, @@ -484,9 +525,9 @@ S3: без зафиксированных метаданных объект не - **WHEN** S3 остановлен, и участник загружает настоящий PNG - **THEN** ответ 503 `unavailable`, в PostgreSQL появилось одно новое - вложение — в статусе «загружается», а число готовых не изменилось + вложение — в статусе «загружается», заданий и принятых не прибавилось - **AND** текстовое сообщение в тот же чат — 201, а после возврата S3 - та же загрузка — 201 + та же загрузка — 202 #### Scenario: Отклонённая загрузка ничего не оставляет @@ -510,29 +551,43 @@ S3: без зафиксированных метаданных объект не - **THEN** ответ 503 `unavailable`, а нового вложения нет ни в PostgreSQL, ни в bucket -#### Scenario: Фиксация ready не удалась +#### Scenario: Фиксация задания не удалась -- **WHEN** объект вложения записан в S3, а PostgreSQL отказывает при - переводе вложения в `ready` +- **WHEN** объект вложения записан в staging, а PostgreSQL отказывает при + переводе вложения в `queued` - **THEN** ответ 503 `unavailable`, а не 500, и объекта этого вложения - в bucket уже нет + в bucket уже нет, а задания у него нет - **AND** вложение остаётся в статусе «загружается» до уборщика, а по API его не видно +#### Scenario: Фиксация ready не удалась + +- **WHEN** worker записал объекты вложения, а PostgreSQL отказывает при + фиксации `ready` +- **THEN** вложение не готово: метаданные — `queued` или `processing`, + скачивание — 409 `conflict`, а следующая попытка доводит его до `ready` + #### Scenario: Исход фиксации неизвестен -- **WHEN** объект вложения записан в S3, а фиксация перевода в `ready` - обрывается отказом PostgreSQL +- **WHEN** объект вложения записан в staging, а фиксация перевода в + `queued` обрывается отказом PostgreSQL - **THEN** ответ 503 `unavailable`, вложение в статусе «загружается» и по API не видно, а его объект в bucket остаётся: API его не удаляет - **AND** после grace уборщик убирает и метаданные, и объект, а в bucket нет объектов вложений без метаданных +#### Scenario: Брокер не подтвердил задание + +- **WHEN** брокер остановлен, и участник загружает настоящий PNG +- **THEN** ответ 503 `unavailable`, вложение в статусе «загружается» и по + API не видно, задания у него нет +- **AND** после grace уборщик убирает и метаданные, и объект staging + #### Scenario: Обрыв передачи тела - **WHEN** клиент обрывает соединение посреди тела загрузки - **THEN** нового вложения нет ни в PostgreSQL, ни в bucket, а следующая - загрузка того же участника — 201 + загрузка того же участника — 202 ### Requirement: Недоступность S3 @@ -546,7 +601,8 @@ S3: без зафиксированных метаданных объект не - `/health/ready`. После возврата S3 загрузка и скачивание SHALL проходить без перезапуска -API. +API. Что делает при этом worker — `attachment-processing`, «Ограниченные +повторы». 503 на загрузке и скачивании SHALL означать только такой отказ S3: недоступен, не ответил за срок или отказал. Доступный S3 MUST NOT давать @@ -555,7 +611,7 @@ API. #### Scenario: S3 остановлен -- **WHEN** вложение загружено, затем S3 остановлен, и участник +- **WHEN** вложение стало `ready`, затем S3 остановлен, и участник скачивает байты, читает метаданные, отправляет сообщение с этим вложением и запрашивает `/health/ready` - **THEN** скачивание — 503 `unavailable`, метаданные — 200, сообщение @@ -574,21 +630,21 @@ API. - **WHEN** участники одновременно скачали оригинал в несколько MiB, затем реплика дольше срока вызова S3 не обращалась к S3, а S3 всё это время доступен, и участник одну за другой загружает файлы -- **THEN** каждая загрузка — 201, ни одной 503 +- **THEN** каждая загрузка — 202, ни одной 503 - **AND** скачанные байты совпадают с загруженными ### Requirement: Вложение доступно через любую реплику -Готовое вложение SHALL скачиваться через любую реплику API за -балансировщиком, в том числе после остановки реплики, которая его -приняла. Метаданные и оригинал SHALL переживать перезапуск стенда -(`scripts/restart.sh`, вместе с S3) с сохранёнными volumes и читаться -прежним токеном. +Метаданные любого принятого вложения и байты готового SHALL читаться +через любую реплику API за балансировщиком, в том числе после остановки +реплики, которая его приняла. Метаданные, оригинал и варианты SHALL +переживать перезапуск стенда (`scripts/restart.sh`, вместе с S3) с +сохранёнными volumes и читаться прежним токеном. #### Scenario: Скачивание через другую реплику - **WHEN** вложение загружено через балансировщик, ответ дала реплика - с одним `X-Instance-Id` + с одним `X-Instance-Id`, и оно стало `ready` - **THEN** байты скачиваются через реплику с другим `X-Instance-Id` и совпадают с загруженными @@ -596,12 +652,13 @@ API. - **WHEN** вложение загружено через балансировщик, затем реплика с `X-Instance-Id` ответа на загрузку остановлена `scripts/stop-one.sh` -- **THEN** метаданные и байты через балансировщик — 200 от другой - реплики, SHA-256 совпадает с загруженным, посторонний получает 404 +- **THEN** метаданные — 200 от другой реплики, вложение становится `ready`, + байты через балансировщик — 200, SHA-256 совпадает с загруженным, + посторонний получает 404 #### Scenario: Рестарт стенда -- **WHEN** вложение загружено, затем выполнен `scripts/restart.sh` +- **WHEN** вложение стало `ready`, затем выполнен `scripts/restart.sh` - **THEN** прежним токеном метаданные — 200, а байты совпадают с загруженными по SHA-256 @@ -611,7 +668,7 @@ API. max_concurrent` загрузок (`service-configuration`, «Параметры загрузок»): у процесса столько мест загрузки. Загрузка занимает место после проверок 1–5 требования «Порядок проверок загрузки» и до чтения -тела. Место SHALL освобождаться при любом исходе загрузки: 201, ошибка, +тела. Место SHALL освобождаться при любом исходе загрузки: 202, ошибка, обрыв клиента, истёкший срок, отмена запроса. Загрузка, которой места нет, SHALL ждать его в очереди процесса по @@ -637,8 +694,8 @@ NOT оставлять ни метаданных, ни объекта. Ожид - **WHEN** 10 участников одного чата одновременно загружают по настоящему PNG около 1 MiB, а параметры загрузок — по умолчанию -- **THEN** все ответы 201 с разными `id`, и каждое вложение скачивается - с тем же SHA-256 +- **THEN** все ответы 202 с разными `id`, и каждое вложение становится + `ready` и скачивается с тем же SHA-256 #### Scenario: Все места заняты @@ -659,8 +716,8 @@ NOT оставлять ни метаданных, ни объекта. Ожид - **WHEN** место занято загрузкой, которая заканчивается раньше срока ожидания, а следующая загрузка ждёт его в очереди -- **THEN** ожидавшая загрузка получает 201, и её вложение скачивается с - тем же SHA-256 +- **THEN** ожидавшая загрузка получает 202, и её вложение становится `ready` + и скачивается с тем же SHA-256 #### Scenario: Место освобождается @@ -668,7 +725,7 @@ NOT оставлять ни метаданных, ни объекта. Ожид счётчику, 415 по содержимому, 400 по сроку тела, обрывом клиента или 503 при остановленном S3 - **THEN** после каждой такой загрузки следующая получает место сразу: - ответ 201 без ожидания (после 503 — когда S3 вернулся) + ответ 202 без ожидания (после 503 — когда S3 вернулся) #### Scenario: Память не растёт с числом загрузок @@ -694,10 +751,43 @@ body_timeout_seconds` после того, как загрузка заняла - **WHEN** участник шлёт настоящий PNG частями так, что тело идёт дольше срока передачи - **THEN** ответ 400 `invalid_request`, нового вложения нет ни в - PostgreSQL, ни в bucket, а следующая загрузка — 201 без ожидания места + PostgreSQL, ни в bucket, а следующая загрузка — 202 без ожидания места #### Scenario: Медленная передача в срок - **WHEN** участник шлёт настоящий PNG мелкими частями с паузами и укладывается в срок передачи -- **THEN** ответ 201, а `size_bytes` и `sha256` совпадают с файлом +- **THEN** ответ 202, а `size_bytes` и `sha256` совпадают с файлом + +### Requirement: Скачивание варианта + +`GET /api/v1/attachments/{attachment_id}/content?variant=thumbnail` у +готового вложения SHALL отвечать 200 с байтами варианта через API, без +перенаправления. Заголовки ответа: `Content-Type` — `content_type` варианта, +`Content-Length` — его размер, `X-Content-Type-Options: nosniff`. Размер и +SHA-256 байтов равны полям варианта в метаданных. Доступ — как у оригинала +(требование «Доступ к вложению»). + +Вариант, которого у готового вложения нет, SHALL давать 404 `not_found`. На +этом уровне это `crop` и `optimized`, а ещё `thumbnail` у вложения, ставшего +готовым до этого изменения. Нет объекта варианта в S3 или размер другой — 500 +`internal_error` без деталей, причина в журнале. + +#### Scenario: Скачивание thumbnail + +- **WHEN** Боб скачивает `variant=thumbnail` готового вложения, загруженного + Алисой +- **THEN** ответ 200, не перенаправление, `Content-Type: image/jpeg`, + `Content-Length` равен `size_bytes` варианта, есть `X-Content-Type-Options: + nosniff`, а SHA-256 равен `sha256` варианта + +#### Scenario: Отсутствующий вариант + +- **WHEN** участник скачивает `variant=crop` и `variant=optimized` готового + вложения +- **THEN** оба ответа 404 `not_found` в формате ошибки + +#### Scenario: Вариант для постороннего + +- **WHEN** Ева скачивает `variant=thumbnail` вложения чата Алисы и Боба +- **THEN** ответ 404 `not_found` с тем же `message`, что у неизвестного `id` diff --git a/openspec/specs/container-image/spec.md b/openspec/specs/container-image/spec.md index e4a2d3ed..1ac5e3a9 100644 --- a/openspec/specs/container-image/spec.md +++ b/openspec/specs/container-image/spec.md @@ -110,3 +110,32 @@ MUST NOT быть доступны этому пользователю на за - **WHEN** healthcheck отрабатывает несколько раз - **THEN** итоговых записей о запросах к health в журнале сервиса нет + +### Requirement: Worker на образе приложения + +Worker SHALL запускаться из того же образа, что и API, своей командой. Процессом +с PID 1 контейнера worker SHALL быть сам worker (`python -m src.worker`), без +оболочки между Docker и им. Декодер изображений SHALL входить в образ зависимостью +времени выполнения из `uv.lock`, без компиляторов в runtime. Healthcheck образа +проверяет HTTP и worker не подходит: у контейнера worker он SHALL быть выключен, и +живость видна по журналу. + +Реплики API MUST NOT загружать декодер изображений в память процесса. + +#### Scenario: PID 1 worker + +- **WHEN** в работающем контейнере worker читается командная строка процесса 1 +- **THEN** это `python -m src.worker`, а `docker inspect` не показывает у контейнера + проверки здоровья + +#### Scenario: Декодер в образе + +- **WHEN** в образе, собранном из чистого clone, импортируется декодер изображений + и запрашивается версия +- **THEN** импорт проходит, версия совпадает с `uv.lock`, а `uv` и компиляторов в + образе нет + +#### Scenario: Декодера нет в процессе API + +- **WHEN** в работающей реплике API проверяются загруженные модули +- **THEN** декодера изображений среди них нет diff --git a/openspec/specs/container-run/spec.md b/openspec/specs/container-run/spec.md index 02c99bc3..96055960 100644 --- a/openspec/specs/container-run/spec.md +++ b/openspec/specs/container-run/spec.md @@ -16,19 +16,23 @@ Valkey, сервером S3, одноразовыми миграциями и bo `docker compose`. В стенд входят: - PostgreSQL и Valkey; - сервер S3 (capability `object-storage`); +- брокер (capability `message-broker`); - одноразовые сервисы миграций и bootstrap S3; - `API_REPLICAS` реплик API (capability `load-balancing`); - уборщик незавершённых загрузок (capability `storage-consistency`) — один долгоживущий процесс на образе API со своей командой; +- worker (capability `attachment-processing`) — долгоживущий процесс на образе + API со своей командой; - балансировщик (LB). -Реплики API SHALL стартовать после готовности PostgreSQL и Valkey, +Реплики API SHALL стартовать после готовности PostgreSQL, Valkey и брокера, успешных миграций и успешного bootstrap S3. Миграции и bootstrap SHALL выполняться один раз за запуск отдельными сервисами, а не репликами. Уборщик SHALL стартовать после готовности PostgreSQL, успешных миграций -и успешного bootstrap S3. Реплики API его не ждут, а фоновую уборку -MUST NOT выполнять сами. Уборщик MUST NOT публиковать порты и SHALL -перезапускаться после сбоя. +и успешного bootstrap S3. Worker SHALL стартовать после готовности PostgreSQL +и брокера, успешных миграций и успешного bootstrap S3. Реплики API их не ждут, +а фоновую уборку и обработку изображений MUST NOT выполнять сами. Уборщик и +worker MUST NOT публиковать порты и SHALL перезапускаться после сбоя. Перед этим цель SHALL создавать недостающие `.env` и `config.toml` из шаблонов (`make env_setup`) и MUST NOT перезаписывать существующие: в @@ -42,21 +46,22 @@ MUST NOT выполнять сами. Уборщик MUST NOT публикова - **WHEN** в свежем clone выполнен `make run_docker` - **THEN** сервис отвечает через LB на - `http://localhost:8080/health/ready`, работают две реплики API и - уборщик, сервер S3 в состоянии `healthy`, bootstrap S3 завершился с - кодом 0, и `make student_test` проходит + `http://localhost:8080/health/ready`, работают две реплики API, + уборщик и worker, сервер S3 и брокер в состоянии `healthy`, bootstrap S3 + завершился с кодом 0, и `make student_test` проходит #### Scenario: Миграции один раз - **WHEN** выполнен `make run_docker` с двумя репликами - **THEN** журнал сервиса миграций содержит один прогон, а в журналах - реплик API нет запуска миграций + реплик API и worker нет запуска миграций #### Scenario: Bootstrap S3 один раз - **WHEN** выполнен `make run_docker` с двумя репликами - **THEN** журнал bootstrap S3 содержит один прогон, завершённый до - старта реплик и уборщика, а в журналах реплик API нет создания bucket + старта реплик, уборщика и worker, а в журналах реплик API нет создания + bucket ### Requirement: Порты из .env @@ -75,12 +80,15 @@ MUST NOT выполнять сами. Уборщик MUST NOT публикова `VALKEY_OUT_PORT` на `127.0.0.1` для запуска в консоли; - порт API S3 внутри сети compose — `S3_PORT`, его слушает сам сервер S3, используют API в docker и bootstrap; внешний — `S3_OUT_PORT` на + `127.0.0.1` для запуска в консоли; +- порт AMQP брокера внутри сети compose — `RABBITMQ_PORT`, его слушает сам + брокер, используют API и worker в docker; внешний — `RABBITMQ_OUT_PORT` на `127.0.0.1` для запуска в консоли. Если переменная порта API не задана, SHALL действовать 8080. Параметры приложения в `.env` SHALL записываться в формате настроек (`SECTION__FIELD`). Имя без секции допускается только для переменных, -которые приложение не читает. Адреса и порты PostgreSQL, Valkey и S3 +которые приложение не читает. Адреса и порты PostgreSQL, Valkey, S3 и брокера MUST NOT быть записаны в compose литералами. #### Scenario: Другой внешний порт @@ -119,13 +127,21 @@ MUST NOT быть записаны в compose литералами. проходит, `make s3_check` проходит, а приложение в консоли обращается к S3 на `127.0.0.1:$S3_OUT_PORT` +#### Scenario: Другой порт брокера + +- **WHEN** в `.env` заданы другие `RABBITMQ_PORT` и `RABBITMQ_OUT_PORT`, а + compose не правился +- **THEN** брокер слушает `RABBITMQ_PORT` и становится `healthy`, загрузка + через LB становится `ready`, а приложение в консоли обращается к брокеру на + `127.0.0.1:$RABBITMQ_OUT_PORT` + ### Requirement: Оба способа запуска описаны в REPORT.md Раздел «Запуск из чистого clone» в `REPORT.md` SHALL описывать два способа запуска стенда: - `make run_docker` — всё в compose; -- `make run_dev` — PostgreSQL, Valkey и S3 с bootstrap в compose, - сервис на хосте. +- `make run_dev` — PostgreSQL, Valkey, S3 с bootstrap и брокер в compose, + сервис на хосте; worker на хосте — `make run_worker`. Для каждого SHALL быть указаны подготовка (`make env_setup`), команды, которые выполняет цель Makefile, применение миграций и bootstrap S3, @@ -140,21 +156,21 @@ MUST NOT быть записаны в compose литералами. ### Requirement: Публикация только на localhost -Порты LB, PostgreSQL и Valkey и порт API S3 SHALL публиковаться в -compose только на `127.0.0.1` хоста. Адрес публикации SHALL быть +Порты LB, PostgreSQL и Valkey, порт API S3 и порт AMQP брокера SHALL +публиковаться в compose только на `127.0.0.1` хоста. Адрес публикации SHALL быть записан литералом, а не переменной. Другие порты сервера S3 (консоль, -UI, внутренние серверы хранилища) MUST NOT публиковаться. Реплики API и -одноразовые сервисы MUST NOT публиковать порты на хосте: к репликам -ходят только LB и контейнеры сети compose. Учебный стенд MUST NOT быть -доступен с других машин сети. +UI, внутренние серверы хранилища) и другие порты брокера (метрики, связь узлов) +MUST NOT публиковаться. Реплики API, worker и одноразовые сервисы MUST NOT +публиковать порты на хосте: к репликам ходят только LB и контейнеры сети compose. +Учебный стенд MUST NOT быть доступен с других машин сети. #### Scenario: Адрес публикации -- **WHEN** для запущенных контейнеров LB, API, Postgres, Valkey и S3 - выполняется `docker port` -- **THEN** порты LB, Postgres, Valkey и порт API S3 опубликованы на - `127.0.0.1`, а не на `0.0.0.0`; других портов у S3 не опубликовано, а - у контейнеров API опубликованных портов нет +- **WHEN** для запущенных контейнеров LB, API, worker, Postgres, Valkey, S3 и + брокера выполняется `docker port` +- **THEN** порты LB, Postgres, Valkey, порт API S3 и порт AMQP брокера + опубликованы на `127.0.0.1`, а не на `0.0.0.0`; других портов у S3 и брокера + не опубликовано, а у контейнеров API и worker опубликованных портов нет ### Requirement: Конфигурация на старте @@ -185,27 +201,27 @@ compose, и приложению, SHALL передаваться через `env ### Requirement: Данные переживают рестарт стенда -Данные PostgreSQL и S3 SHALL храниться в именованных volumes. Скрипт +Данные PostgreSQL, S3 и брокера SHALL храниться в именованных volumes. Скрипт `scripts/restart.sh` SHALL перезапускать LB, все реплики API и все -используемые хранилища — PostgreSQL, Valkey и S3. Volumes, схема, -bucket, учётные записи S3 и данные SHALL сохраняться: без удаления -volumes, очистки и повторного наполнения. Bootstrap S3, который снова +используемые хранилища — PostgreSQL, Valkey, S3 и брокер. Volumes, схема, +bucket, учётные записи S3, очередь, её сообщения и данные SHALL сохраняться: без +удаления volumes, очистки и повторного наполнения. Bootstrap S3, который снова выполняется при старте реплик, состояние хранилища не меняет. Число -реплик после рестарта SHALL оставаться прежним. Скрипт SHALL быть -исполняемым, завершаться с кодом 0 только после перезапуска, -укладываться в 90 с и MUST NOT печатать секреты. Публичная проверка -`make test-persistence ACTION_SCRIPT=scripts/restart.sh` SHALL -проходить через LB. +реплик после рестарта SHALL оставаться прежним. Worker и уборщика скрипт не +трогает: они переживают рестарт хранилищ сами, а остановленный worker остаётся +остановленным. Скрипт SHALL быть исполняемым, завершаться с кодом 0 только после +перезапуска, укладываться в 90 с и MUST NOT печатать секреты. Публичная проверка +`make test-persistence ACTION_SCRIPT=scripts/restart.sh` SHALL проходить через LB. #### Scenario: Рестарт hook-ом - **WHEN** пользователь вошёл, отправил сообщение, затем выполнен `scripts/restart.sh` -- **THEN** контейнеры LB, всех реплик API, Postgres, Valkey и S3 +- **THEN** контейнеры LB, всех реплик API, Postgres, Valkey, S3 и брокера перезапущены: те же ID и новое время старта в `docker inspect`. После готовности запрос с прежним токеном через LB получает 200 и видит своё сообщение, а bootstrap S3 после рестарта сообщает, что bucket и - пользователь уже есть + пользователи уже есть #### Scenario: Публичная проверка сохранности @@ -213,24 +229,32 @@ volumes, очистки и повторного наполнения. Bootstrap ACTION_SCRIPT=scripts/restart.sh` - **THEN** команда завершается с кодом 0 и печатает `PASS` +#### Scenario: Worker переживает рестарт хранилищ + +- **WHEN** worker работает, выполнен `scripts/restart.sh`, и участник загружает + файл +- **THEN** вложение становится `ready`, а у контейнера worker прежнее время + старта и счётчик перезапусков 0 + ### Requirement: Удаление учебных данных -`make stop` и `make down` MUST NOT удалять volumes с данными PostgreSQL -и S3. Удаление данных стенда SHALL выполняться отдельной явной командой +`make stop` и `make down` MUST NOT удалять volumes с данными PostgreSQL, +S3 и брокера. Удаление данных стенда SHALL выполняться отдельной явной командой `make wipe_data`, которая запрашивает подтверждение и называет удаляемые данные. #### Scenario: down сохраняет данные - **WHEN** выполнены `make down`, затем `make run_docker` -- **THEN** ранее созданные пользователи, сообщения и объекты S3 на месте +- **THEN** ранее созданные пользователи, сообщения, объекты S3 и задания в + очереди на месте #### Scenario: Явное удаление - **WHEN** выполнен `make wipe_data` и удаление подтверждено -- **THEN** volumes Postgres и S3 удалены, и следующий `make run_docker` - поднимает пустую базу со схемой из миграций и пустой приватный bucket, - созданный bootstrap +- **THEN** volumes Postgres, S3 и брокера удалены, и следующий `make + run_docker` поднимает пустую базу со схемой из миграций, пустой приватный + bucket, созданный bootstrap, и брокер без сообщений ### Requirement: Журнал контейнера @@ -256,41 +280,47 @@ MUST NOT затрагивать ресурсы проектов прошлых репозитории выполнены `make run_docker`, затем `make wipe_data` с подтверждением - **THEN** стенд создаёт и затем удаляет только volumes своего проекта - (`mtusi-lab5_postgres_data`, `mtusi-lab5_s3_data`), а - `mtusi-lab4_postgres_data` остаётся с прежней датой создания + (`mtusi-lab5_postgres_data`, `mtusi-lab5_s3_data`, + `mtusi-lab5_rabbitmq_data`), а `mtusi-lab4_postgres_data` остаётся с прежней + датой создания ### Requirement: Лимиты ресурсов и секреты по сервисам Каждый сервис стенда SHALL иметь лимиты CPU и памяти: LB, реплики API, -уборщик, сервисы миграций и bootstrap S3, PostgreSQL, Valkey и сервер -S3. Сумма лимитов и расчёт соединений PostgreSQL для заявленного числа -реплик и уборщика SHALL быть описаны в `REPORT.md`. Секреты SHALL +уборщик, worker, сервисы миграций и bootstrap S3, PostgreSQL, Valkey, сервер +S3 и брокер. Сумма лимитов и расчёт соединений PostgreSQL для заявленного числа +реплик, уборщика и worker SHALL быть описаны в `REPORT.md`. Секреты SHALL передаваться только тем сервисам, которым они нужны: -- пароль PostgreSQL — PostgreSQL, репликам API, уборщику и сервису +- пароль PostgreSQL — PostgreSQL, репликам API, уборщику, worker и сервису миграций; - пароль Valkey — Valkey и репликам API; +- пароль брокера — брокеру, репликам API и worker; - административные ключ и секрет S3 — только серверу S3; - ключ подписи служебных вызовов S3 — серверу S3 и bootstrap; - ключи пользователя API в S3 — bootstrap и репликам API; - ключи пользователя уборщика в S3 — bootstrap и уборщику; -- LB MUST NOT получать ни одного секрета, а сервис миграций, PostgreSQL - и Valkey MUST NOT получать секретов S3. Уборщик MUST NOT получать - пароль Valkey, ключи API, административные ключи S3 и ключ подписи. +- ключи пользователя worker в S3 — bootstrap и worker; +- LB MUST NOT получать ни одного секрета, а сервис миграций, PostgreSQL, + Valkey и брокер MUST NOT получать секретов S3. Уборщик MUST NOT получать + пароли Valkey и брокера, ключи API и worker, административные ключи S3 и ключ + подписи. Worker MUST NOT получать пароль Valkey, ключи API и уборщика, + административные ключи S3 и ключ подписи. #### Scenario: Лимиты у всех контейнеров - **WHEN** для каждого контейнера запущенного стенда выполняется `docker inspect` (`HostConfig.NanoCpus`, `HostConfig.Memory`) -- **THEN** у LB, каждой реплики API, уборщика, сервисов миграций и - bootstrap S3, PostgreSQL, Valkey и сервера S3 оба значения больше нуля +- **THEN** у LB, каждой реплики API, уборщика, worker, сервисов миграций и + bootstrap S3, PostgreSQL, Valkey, сервера S3 и брокера оба значения больше нуля #### Scenario: Секреты по сервисам - **WHEN** проверяющий смотрит окружение сервисов в `docker compose config` -- **THEN** у LB нет ни одного секрета; у сервиса миграций нет пароля - Valkey и секретов S3; пароль Valkey есть только у Valkey и реплик API; - административные ключи S3 — только у сервера S3, ключ подписи — у - сервера S3 и bootstrap, ключи API в S3 — у bootstrap и реплик API, - ключи уборщика в S3 — у bootstrap и уборщика +- **THEN** у LB нет ни одного секрета; у сервиса миграций нет паролей + Valkey и брокера и секретов S3; пароль Valkey есть только у Valkey и реплик + API; пароль брокера — только у брокера, реплик API и worker; административные + ключи S3 — только у сервера S3, ключ подписи — у сервера S3 и bootstrap, ключи + API в S3 — у bootstrap и реплик API, ключи уборщика в S3 — у bootstrap и + уборщика, ключи worker в S3 — у bootstrap и worker diff --git a/openspec/specs/data-storage/spec.md b/openspec/specs/data-storage/spec.md index 16c0d950..3bd12087 100644 --- a/openspec/specs/data-storage/spec.md +++ b/openspec/specs/data-storage/spec.md @@ -11,13 +11,15 @@ PostgreSQL как источник истины, сохранность посл ### Requirement: Хранение в PostgreSQL -Пользователи, чаты, участники чатов, сообщения, сессии, а с лабы 4 — -метаданные вложений и связи сообщений с вложениями SHALL храниться в -PostgreSQL, он — источник истины. Сервис MUST NOT хранить эти данные -в памяти процесса, файлах или SQLite. Байты вложений SHALL храниться в -S3 (capability `attachments`, `object-storage`), а не в PostgreSQL и не -в файлах реплик. Подтверждённая запись (ответ 201 или 204) SHALL быть -зафиксирована до ответа и видна следующему запросу. +Пользователи, чаты, участники чатов, сообщения, сессии, с лабы 4 — +метаданные вложений и связи сообщений с вложениями, а с лабы 5 — задания +обработки и метаданные вариантов SHALL храниться в PostgreSQL, он — источник +истины. Сервис MUST NOT хранить эти данные в памяти процесса, файлах или +SQLite. Сообщение брокера лишь сообщает о задании: состояние задания MUST NOT +определяться по брокеру. Байты вложений SHALL храниться в S3 (capability +`attachments`, `object-storage`), а не в PostgreSQL и не в файлах реплик. +Подтверждённая запись (ответ 201, 202 или 204) SHALL быть зафиксирована до +ответа и видна следующему запросу. #### Scenario: Созданное видно сразу @@ -26,6 +28,12 @@ S3 (capability `attachments`, `object-storage`), а не в PostgreSQL и не - **THEN** вход успешен, и `GET /api/v1/users/me` с выданным токеном возвращает этого пользователя +#### Scenario: Принятое вложение видно сразу + +- **WHEN** участник получил ответ 202 на загрузку и сразу запрашивает + метаданные через другую реплику +- **THEN** ответ 200 с тем же `id`, а `status` — `queued` или более поздний + ### Requirement: Данные переживают рестарт После перезапуска сервиса и PostgreSQL с сохранённым volume все ранее @@ -80,6 +88,15 @@ S3 (capability `attachments`, `object-storage`), а не в PostgreSQL и не - допустимые значения размера, SHA-256, типа, статуса и длины `filename`; ключ объекта уникален. +С лабы 5 БД SHALL проверять и обработку: +- код ошибки есть только у вложения `failed`, и у `failed` он есть; +- на вложение и версию конвейера одно задание, оно ссылается на существующее + вложение; вложение с заданием удалить нельзя; +- допустимые значения состояния и числа попыток задания; +- вариант уникален по вложению, версии конвейера и имени; он ссылается на + существующее вложение; допустимые значения имени, типа, размера, ширины, + высоты и SHA-256; ключ объекта варианта уникален. + Порядок `member_ids`, заданный при создании чата, и порядок `attachment_ids` сообщения SHALL сохраняться. Принадлежность вложения чату сообщения проверяет сервис в той же транзакции: чат вложения и @@ -97,6 +114,12 @@ S3 (capability `attachments`, `object-storage`), а не в PostgreSQL и не - **THEN** ответ на отправку, история чата и повтор с тем же ключом возвращают `[C, A, B]` +#### Scenario: Ограничения обработки в схеме + +- **WHEN** проверяющий пытается вставить второе задание той же версии конвейера, + второй вариант с тем же именем и `error_code` у вложения не `failed` +- **THEN** PostgreSQL отклоняет каждую вставку нарушением ограничения + ### Requirement: Составная операция в одной транзакции Создание чата вместе с участниками SHALL выполняться одной diff --git a/openspec/specs/db-migrations/spec.md b/openspec/specs/db-migrations/spec.md index fe906538..ac5a7d95 100644 --- a/openspec/specs/db-migrations/spec.md +++ b/openspec/specs/db-migrations/spec.md @@ -100,7 +100,9 @@ Ослабленное ограничение SHALL добавляться без проверки существующих строк под эксклюзивной блокировкой таблицы: эти строки уже -удовлетворяли более строгому условию. +удовлетворяли более строгому условию. Новое ограничение на новые колонки +существующей таблицы SHALL добавляться так же: прежняя версия эти колонки не +пишет, а значения прежних строк ему удовлетворяют. Удаление и переименование таблицы, колонки или ограничения (кроме замены ограничения ослабленным), а также новое ограничение, которое @@ -111,7 +113,9 @@ Реплики прежнего образа SHALL обслуживать обязательные запросы на схеме после новой миграции. Откат кода к прежнему образу MUST NOT -требовать отката схемы. +требовать отката схемы. Новые значения статуса вложения прежний образ +прочитать не может; это ограничение смешанных версий при переходе 4 → 5 SHALL +быть в `REPORT.md`. Ожидание блокировки таблицы миграцией SHALL быть ограничено сроком. Долгая транзакция приложения не должна заставить миграцию держать @@ -129,7 +133,7 @@ - **THEN** проверки, которые прежний образ проходил на прежней схеме, проходят и на новой: запись сообщений через прежние реплики — 201, история — 200, ответов 5xx нет (замер замены реплик — - `evidence/rollout/attachments/summary.md`) + `evidence/rollout/async-attachments/summary.md`) - **AND** проверки, которых прежний образ не проходил и на прежней схеме (новые требования контракта, например вложения лабы 4 для образа лабы 4 до `attachments`), совместимостью схемы не считаются @@ -158,6 +162,14 @@ реплик во время и после неё — 201, а после замены реплик сообщение с пустым текстом и вложением — 201 +#### Scenario: Новые состояния вложения + +- **WHEN** миграция обработки вложений применена к базе с вложениями `pending` + и `ready`, а реплики прежнего образа ещё работают +- **THEN** миграция не проверяет существующие строки под эксклюзивной + блокировкой, их `status` прежний, загрузка через прежнюю реплику проходит, + как раньше, а повторный запуск миграций ничего не меняет + ### Requirement: Однократные миграции при замене реплик Поочерёдная замена реплик (`load-balancing`) SHALL применять миграции diff --git a/openspec/specs/graceful-shutdown/spec.md b/openspec/specs/graceful-shutdown/spec.md index 75bc0827..ca6ded14 100644 --- a/openspec/specs/graceful-shutdown/spec.md +++ b/openspec/specs/graceful-shutdown/spec.md @@ -237,3 +237,40 @@ PostgreSQL доводится до конца или до отката. Новы - **THEN** контейнер останавливается не позже чем через секунду после сигнала, код выхода 1, а в журнале — итог сверки с причиной прерывания «остановка» и запись об остановке уборщика + +### Requirement: Остановка worker + +По SIGTERM worker (capability `attachment-processing`) SHALL перестать принимать +новые сообщения и дать начатым заданиям завершиться, но не дольше `[worker] +graceful_shutdown_seconds`. Задание, которое не успело, SHALL оставаться +неподтверждённым: брокер доставит его снова (`attachment-processing`, «Доставка at +least once»). Затем worker SHALL выйти с кодом 0 раньше срока остановки контейнера +(10 с), а не по SIGKILL, в том числе если декодирование ещё идёт. + +Значение `graceful_shutdown_seconds` MUST быть не больше 9. Сигнал во время старта +процесса SHALL завершать его с кодом 0 без traceback, как у API (требование +«Остановка во время старта»). Остановка SHALL быть видна в журнале записью об +остановке worker. + +Ограничение называется в `REPORT.md`. Задание, прерванное остановкой, считается +начатой попыткой. + +#### Scenario: docker stop простаивающего worker + +- **WHEN** выполняется `docker compose stop worker` для worker без заданий +- **THEN** команда завершается быстрее 10 с, код выхода контейнера 0, а в журнале + есть запись об остановке + +#### Scenario: docker stop во время обработки + +- **WHEN** `docker compose stop worker` выполняется, пока фиксация результата задания + задержана дольше срока остановки worker +- **THEN** команда завершается быстрее 10 с, код выхода контейнера 0, сообщение + задания снова в очереди, а после запуска worker вложение становится `ready` + +#### Scenario: docker stop во время старта worker + +- **WHEN** контейнер worker остановлен в первые доли секунды после старта, пока + процесс ещё импортирует приложение +- **THEN** `docker stop` завершается не дольше чем за 1 с, код выхода контейнера 0, а в + журнале есть запись об остановке worker до старта diff --git a/openspec/specs/health/spec.md b/openspec/specs/health/spec.md index 306cc713..53831956 100644 --- a/openspec/specs/health/spec.md +++ b/openspec/specs/health/spec.md @@ -27,15 +27,19 @@ MUST NOT зависеть от состояния хранилища. зависимость — PostgreSQL: проверка SHALL выполнять запрос к нему с коротким таймаутом при каждом обращении. -Две зависимости не критичны, и их недоступность MUST NOT делать сервис +Четыре зависимости не критичны, и их недоступность MUST NOT делать сервис неготовым: - Valkey — кэш: без него обязательные запросы обслуживаются из PostgreSQL; -- S3 — хранилище байтов вложений: путь без вложений его не использует. +- S3 — хранилище байтов вложений: путь без вложений его не использует; +- брокер — приём новых вложений: без него загрузка отвечает 503, а текст, + история, метаданные и скачивание готового вложения работают. Иначе отказ + брокера вывел бы из балансировщика все реплики разом; +- worker — фоновая обработка: без него загрузки ждут в очереди. -Проверка MUST NOT обращаться к S3 и MUST NOT требовать идентификации. -Перечень критичных и некритичных зависимостей с причинами SHALL быть в -`REPORT.md`. +Проверка MUST NOT обращаться к S3 и брокеру и MUST NOT требовать +идентификации. Перечень критичных и некритичных зависимостей с причинами +SHALL быть в `REPORT.md`. #### Scenario: Сервис запущен @@ -61,6 +65,13 @@ MUST NOT зависеть от состояния хранилища. - **THEN** `GET /health/ready` и `GET /health/live` отвечают 200 быстрее секунды: проверка к S3 не обращается +#### Scenario: Брокер и worker недоступны + +- **WHEN** брокер остановлен или заморожен (`docker pause`), worker + остановлен, а PostgreSQL доступен +- **THEN** `GET /health/ready` и `GET /health/live` отвечают 200 быстрее + секунды: проверка к брокеру не обращается + ### Requirement: Health вне версии API и без идентификации Эндпоинты health SHALL находиться вне префикса `/api/v1`, MUST NOT diff --git a/openspec/specs/idempotency/spec.md b/openspec/specs/idempotency/spec.md index a5719812..56d4e80c 100644 --- a/openspec/specs/idempotency/spec.md +++ b/openspec/specs/idempotency/spec.md @@ -60,6 +60,9 @@ сообщении. Ключ, сохранённый версией сервиса без вложений, SHALL повторяться тем же телом и после замены реплик на версию с вложениями. +Повтор MUST NOT зависеть от текущего состояния вложений сообщения: +вложение, ставшее `failed` после отправки, не меняет ответ на повтор. + #### Scenario: Повтор того же тела - **WHEN** Алиса отправляет текст T с ключом K и повторяет тот же @@ -87,6 +90,13 @@ - **THEN** оба ответа 201 с тем же `Message` и `attachment_ids` `[A, B]`, в истории одно такое сообщение +#### Scenario: Повтор после failed вложения + +- **WHEN** Алиса отправила с ключом K сообщение с вложением в `queued`, вложение + стало `failed`, и она повторяет с K то же тело, а затем с другим ключом +- **THEN** повтор с K — 201 с тем же `Message`, отправка с другим ключом — 409 + `conflict`, а в истории одно такое сообщение + ### Requirement: Другое тело с тем же ключом Если ключ в своей области уже использован с другим телом и срок не diff --git a/openspec/specs/load-balancing/spec.md b/openspec/specs/load-balancing/spec.md index 14814dba..6123df84 100644 --- a/openspec/specs/load-balancing/spec.md +++ b/openspec/specs/load-balancing/spec.md @@ -440,7 +440,7 @@ SHALL быть доступно только изнутри контейнера - **WHEN** через LB идёт загрузка вложения, тело которой передаётся дольше 12 с, и во время неё `make rolling_update` выводит реплику, которая её принимает -- **THEN** загрузка получает 201 от этой реплики, и только после ответа +- **THEN** загрузка получает 202 от этой реплики, и только после ответа реплика останавливается ### Requirement: Сбой поочерёдной замены @@ -487,17 +487,18 @@ SHALL быть без состояния, выставленного вручн - до чтения тела — вход, членство в чате и ожидание места загрузки, не дольше `2 × [database] request_timeout_seconds + [uploads] wait_timeout_seconds` (17 с); -- после тела — проверка изображения, запись метаданных, запись объекта, - перевод в `ready` и удаление объекта при компенсации, не дольше `2 × - request_timeout_seconds + 2 × [s3] timeout_seconds` плюс проверка - изображения (около 26 с). +- после тела — проверка изображения, запись метаданных, запись объекта в + staging, перевод в `queued` с заданием и либо удаление объекта при + компенсации, либо публикация брокеру и запись о ней, не дольше `3 × + request_timeout_seconds + [s3] timeout_seconds + [broker] + publish_timeout_seconds` плюс проверка изображения (около 29 с). У остальных путей срок SHALL оставаться прежним, 10 с: цепочка таймаутов лабы 3 для них не меняется. Наибольшая длительность живой загрузки — молчание до тела, срок передачи тела (`[uploads] body_timeout_seconds`) и молчание после тела, -около 73 с при значениях по умолчанию. Она и формула SHALL быть в +около 76 с при значениях по умолчанию. Она и формула SHALL быть в `REPORT.md`. Соединение с недочитанным телом SHALL держать в буферах ядра ограниченный diff --git a/openspec/specs/load-benchmark/spec.md b/openspec/specs/load-benchmark/spec.md index f6d5d84d..715d8742 100644 --- a/openspec/specs/load-benchmark/spec.md +++ b/openspec/specs/load-benchmark/spec.md @@ -69,10 +69,11 @@ run_dev` / `make run_docker`). После завершения, в том чис Стенд SHALL состоять из балансировщика (LB), реплик приложения, PostgreSQL и Valkey. В профилях загрузок и сверки к ним SHALL -добавляться S3 с его bootstrap, а в профиле сверки — ещё разовые проходы -процесса уборщика. Число реплик SHALL задаваться методикой, по умолчанию -одна. Приложение SHALL запускаться в контейнерах из образа, собранного -из текущего checkout тем же `Dockerfile`. Исключения — профиль +добавляться S3 с его bootstrap, в профиле загрузок — ещё брокер, а в профиле +сверки — разовые проходы процесса уборщика. Worker стенд не запускает: профили +этого спека меряют реплику, а не обработку. Число реплик SHALL задаваться +методикой, по умолчанию одна. Приложение SHALL запускаться в контейнерах из образа, +собранного из текущего checkout тем же `Dockerfile`. Исключения — профиль поочерёдной замены и варианты «до» профилей загрузок и сверки. Они берут образ commit, заданного методикой: образ собирается тем же `Dockerfile` из файлов этого commit без изменения рабочего дерева. Профиль замены @@ -83,7 +84,8 @@ PostgreSQL и Valkey. В профилях загрузок и сверки к н получает те же настройки образа плюс модуль записи планов, выключенный вне снятия плана. S3 SHALL запускаться из того же образа и с теми же аргументами сервера, что у рабочего стенда, а bucket и пользователей -создаёт тот же bootstrap. В профиле сверки к аргументам S3 добавляется +создаёт тот же bootstrap. Брокер SHALL запускаться из того же образа и с той же +конфигурацией, что у рабочего стенда. В профиле сверки к аргументам S3 добавляется порт метрик шлюза: он слушает только loopback контейнера S3, и по нему оркестратор считает запросы к S3. В сериях трека 1 предел соединений PostgreSQL (`max_connections`) — параметр конфигурации серии, по @@ -95,8 +97,8 @@ PostgreSQL (`max_connections`) — параметр конфигурации с - у каждой реплики приложения — лимит CPU и памяти без swap, заданный методикой (в профилях лабы 2 — 1 CPU и 2 ГБ, в серии трека 1 — по конфигурации); -- у LB, PostgreSQL, Valkey, S3 и уборщика — свои лимиты CPU и памяти без - swap, заданные методикой; в серии трека 1 они одинаковы во всех +- у LB, PostgreSQL, Valkey, S3, брокера и уборщика — свои лимиты CPU и памяти + без swap, заданные методикой; в серии трека 1 они одинаковы во всех конфигурациях; у уборщика в управляемом опыте профиля сверки — другой лимит CPU, тоже заданный методикой; - у генератора нагрузки в профилях трека 1 — лимит CPU и памяти без @@ -109,8 +111,8 @@ PostgreSQL (`max_connections`) — параметр конфигурации с Healthcheck образа приложения SHALL быть отключён: готовность реплик проверяет LB. Порты стенда на хост MUST NOT публиковаться. Настройки приложения и хранилищ SHALL браться из методики стенда, а не из `.env` -и `config.toml` рабочего стенда. Пароли хранилищ и секреты S3 SHALL -генерироваться на прогон. Генератор нагрузки SHALL работать в той же +и `config.toml` рабочего стенда. Пароли хранилищ, пароль брокера и секреты S3 +SHALL генерироваться на прогон. Генератор нагрузки SHALL работать в той же docker-сети и обращаться к приложению через LB по имени сервиса, минуя проброс портов хоста. Стенд SHALL считаться готовым, когда LB видит готовыми все реплики. @@ -171,6 +173,12 @@ docker-сети и обращаться к приложению через LB п и лимитами, bootstrap завершился успешно, а образ и лимиты S3 и ограничение буфера приёма реплики записаны в паспорт +#### Scenario: Брокер в профиле загрузок + +- **WHEN** запускается профиль загрузок +- **THEN** брокер стенда запущен из образа рабочего стенда с его конфигурацией и + лимитами, worker не запущен, а образ и лимиты брокера записаны в паспорт + #### Scenario: S3 и уборщик в профиле сверки - **WHEN** запускается профиль сверки @@ -1862,7 +1870,8 @@ change `attachments`. Commit SHALL меняться при переходе в отказ до запуска стенда. Стенд — LB и одна реплика с лимитами рабочего стенда (1 CPU, 512 МБ без -swap), PostgreSQL, Valkey и S3 с лимитами рабочего стенда. +swap), PostgreSQL, Valkey, S3 и брокер с лимитами рабочего стенда. Worker не +запускается: задания ждут в очереди. Варианты кода: - «до» — образ commit из методики, последнего до change `upload-memory`; @@ -1871,12 +1880,16 @@ swap), PostgreSQL, Valkey и S3 с лимитами рабочего стенд - «с лимитом» — образ текущего checkout с параметрами загрузок по умолчанию. +Успешная загрузка — 202, а у варианта с образом commit до перехода на 202 — +201. Код успеха варианта SHALL быть в паспорте. Столбец успешных загрузок считает +код успеха варианта. + Тела — настоящие PNG около 1 MiB и около 10 MiB, не больше лимита контракта. Их строит оркестратор, детерминированно от зерна методики. Прогон — вариант × размер × число одновременных клиентов (1, 10, 20 и 40) × повтор. Повторов в полном профиле три. Каждый прогон SHALL идти на -новом контейнере реплики и новом volume S3. Клиенты загружают без пауз +новом контейнере реплики и новых volume S3 и брокера. Клиенты загружают без пауз окно, заданное методикой. На 429 клиент ждёт `Retry-After`, на прочие ошибки — секунду. @@ -1896,7 +1909,8 @@ swap), PostgreSQL, Valkey и S3 с лимитами рабочего стенд Граница чёрного ящика: генератор обращается к приложению только по HTTP через LB, оркестратор управляет стендом через docker CLI. Сверх этого он читает счётчики памяти cgroup контейнеров и пересоздаёт volume S3 с -bootstrap между прогонами. К bucket и объектам он не обращается. +bootstrap и volume брокера между прогонами. К bucket, объектам и сообщениям он не +обращается. В паспорте метки SHALL быть: - лимиты и образы, в том числе commit варианта «до»; @@ -1919,7 +1933,7 @@ bootstrap между прогонами. К bucket и объектам он не - **WHEN** выполнен `make bench_uploads_quick` - **THEN** за несколько минут проходят варианты «без лимита» и «с лимитом» на 10 MiB при 1, 10 и 40 клиентах, по одному повтору, код - выхода 0, каталог метки в git не попадает + выхода 0, каталог метки в git не попадает, а успешные загрузки — 202 #### Scenario: Реплика убита из-за памяти diff --git a/openspec/specs/message-broker/spec.md b/openspec/specs/message-broker/spec.md new file mode 100644 index 00000000..0aca0e4c --- /dev/null +++ b/openspec/specs/message-broker/spec.md @@ -0,0 +1,149 @@ +# message-broker Specification + +## Purpose + +Брокер сообщений стенда с лабы 5: запуск и закрепление сервера, устойчивая +очередь заданий, подтверждение публикации, сохранность при рестарте и клиент +в приложении. + +## Requirements + +### Requirement: Брокер в стенде + +Рабочий стенд compose SHALL включать один брокер RabbitMQ 4. Его образ SHALL +быть закреплён тегом с версией и digest индекса. Данные брокера SHALL +храниться в именованном volume, а имя узла SHALL быть постоянным: иначе +пересозданный контейнер не нашёл бы свои данные в том же volume. + +Сервису SHALL быть заданы healthcheck, перезапуск после сбоя, лимиты CPU и +памяти и срок остановки, за который брокер завершается сам. Предел памяти +брокера SHALL быть задан явно меньше лимита контейнера: определить лимит +контейнера сам брокер не может и иначе был бы завершён ядром, а не сдерживал +бы публикацию. Порт AMQP SHALL публиковаться только на `127.0.0.1` хоста, для +запуска в консоли; другие порты брокера MUST NOT публиковаться. + +Брокер создаёт учётную запись приложения из `.env` при первом старте на пустом +volume. Пользователя с паролем по умолчанию MUST NOT быть. + +#### Scenario: Сервис брокера запущен + +- **WHEN** в свежем clone выполнен `make run_docker` +- **THEN** контейнер брокера `healthy`, его образ указан тегом с версией и + digest, данные лежат в именованном volume проекта, а `docker port` показывает + только порт AMQP на `127.0.0.1` + +#### Scenario: Предел памяти брокера + +- **WHEN** брокер запущен с лимитом контейнера 512 МБ +- **THEN** его предел памяти меньше лимита контейнера, а не вычислен от памяти + ВМ Docker + +#### Scenario: Остановка брокера + +- **WHEN** выполняется `docker compose stop` брокера +- **THEN** контейнер завершается с кодом 0 раньше срока остановки + +### Requirement: Устойчивая очередь заданий + +Задания SHALL идти через устойчивую (durable) очередь постоянными (persistent) +сообщениями. Имя очереди SHALL содержать имя базы PostgreSQL процесса: так +прогон на временной базе не смешивается с рабочим, как объекты S3 и ключи кэша. +Очередь SHALL существовать к первой публикации, даже если worker ни разу не +запускался: её объявляет и издатель, и потребитель, повторное объявление +безопасно. + +#### Scenario: Очередь и сообщения устойчивы + +- **WHEN** участник загрузил файл при остановленном worker +- **THEN** очередь в брокере `durable`, в ней одно сообщение с постоянной + доставкой, а прочитанное без подтверждения сообщение возвращается в очередь + +#### Scenario: Очереди разных баз разделены + +- **WHEN** на рабочем стенде выполняется прогон на временной базе +- **THEN** его задания идут через очередь с именем временной базы, worker + рабочего стенда их не получает, а после прогона этой очереди нет + +### Requirement: Подтверждение публикации + +Издатель SHALL считать сообщение принятым только после подтверждения брокера +(publisher confirm). Сообщение, которое брокеру некуда направить, отказ брокера, +обрыв соединения и истечение `[broker] publish_timeout_seconds` SHALL быть +ошибкой недоступности, и API отвечает 503 `unavailable` в формате контракта, а не +500 и не зависанием. Ответ SHALL приходить не позже этого срока с запасом. +Издатель MUST NOT повторять публикацию сам. + +Брокер не критичен для обязательного пути: без него SHALL работать отправка +текста, история, метаданные, скачивание готового вложения и `/health/ready` +(`health`, «Readiness»). + +После возврата брокера публикация SHALL проходить без перезапуска процесса. + +#### Scenario: Брокер остановлен при загрузке + +- **WHEN** брокер остановлен, и участник загружает файл, отправляет текст, + читает метаданные готового вложения и скачивает его +- **THEN** загрузка — 503 `unavailable` быстрее срока публикации с запасом, + отправка — 201, метаданные и скачивание — 200, а вложения этой загрузки по API не + видно + +#### Scenario: Брокер завис + +- **WHEN** контейнер брокера заморожен (`docker pause`), и участник загружает файл +- **THEN** ответ 503 `unavailable` не позже срока публикации с запасом, а сообщение, + дошедшее до брокера после разморозки, не делает вложение видимым и не создаёт + объектов варианта + +#### Scenario: Брокер вернулся + +- **WHEN** брокер снова запущен, а реплика API не перезапускалась +- **THEN** следующая загрузка — 202, и вложение становится `ready` + +#### Scenario: Очередь удалена + +- **WHEN** worker остановлен, очередь заданий удалена мимо приложения, участник + дважды загружает файл, а затем worker запущен +- **THEN** первая загрузка — 503 `unavailable`, вторая — 202, очередь объявлена + заново, и принятое вложение становится `ready` + +### Requirement: Данные брокера переживают рестарт + +Очередь и подтверждённые сообщения SHALL переживать перезапуск брокера и всего +стенда с сохранённым volume, принудительное завершение процесса брокера и +пересоздание контейнера на том же volume. Сообщение, подтверждённое издателю и +ещё не подтверждённое потребителем, MUST NOT теряться. + +#### Scenario: Подтверждённые сообщения после KILL + +- **WHEN** worker остановлен, брокер подтвердил несколько сообщений и сразу + завершён сигналом KILL +- **THEN** после его запуска в очереди столько же сообщений, сколько было + подтверждено + +#### Scenario: Пересоздание контейнера + +- **WHEN** worker остановлен, в очереди есть сообщения, и контейнер брокера + пересоздан (`docker compose up --force-recreate`) на том же volume +- **THEN** очередь и сообщения на месте + +### Requirement: Клиент брокера в приложении + +Реплики API и worker SHALL обращаться к брокеру с настройками секции `[broker]`. +Соединение SHALL открываться при первом вызове, а не при старте: без брокера +процесс стартует. При остановке сервиса клиент SHALL закрываться. Потерянное +соединение SHALL восстанавливаться следующим вызовом, у worker — с паузой между +попытками, без перезапуска процесса. Пароль брокера MUST NOT попадать в журнал и +в ответы API. + +#### Scenario: Старт без брокера + +- **WHEN** реплика API и worker запускаются при остановленном брокере +- **THEN** реплика становится готовой и обслуживает текст, worker пишет в журнал + об отказе брокера и не завершается, а после запуска брокера загрузка — 202, и + вложение становится `ready` + +#### Scenario: Рестарт брокера при работающем worker + +- **WHEN** брокер перезапущен, а worker в это время работает +- **THEN** worker без перезапуска снова получает задания: новая загрузка становится + `ready`, а счётчик перезапусков контейнера worker не изменился diff --git a/openspec/specs/messages/spec.md b/openspec/specs/messages/spec.md index 1054e82b..7a426e62 100644 --- a/openspec/specs/messages/spec.md +++ b/openspec/specs/messages/spec.md @@ -132,16 +132,23 @@ capability `pagination`. Любой участник SHALL видеть все идентификатора, в том числе в другом регистре букв, больше 10 элементов, элемент не UUID и не массив — 400 `invalid_request`. -Каждое вложение SHALL быть готовым вложением этого чата. Одинаковый 404 -`not_found` дают: +Каждое вложение SHALL быть принятым вложением этого чата в состоянии +`queued`, `processing` или `ready`. Одинаковый 404 `not_found` дают: - неизвестное вложение; - вложение другого чата, в том числе чата, где отправитель не состоит; - вложение, загрузка которого не завершена. +Вложение `failed` этого чата SHALL давать 409 `conflict`: прикрепить его +нельзя. Если в списке есть и такое, и вложение из перечня выше, ответ — 404. +Повтор уже отправленного сообщения с тем же ключом SHALL проходить, даже если +его вложение стало `failed` после отправки (`idempotency`, «Повтор возвращает +исходный результат»). + Сообщение при этом MUST NOT создаваться. Сервис SHALL принимать ссылку на вложение чата от любого его участника, а не только от владельца, и одно вложение SHALL входить в несколько сообщений. Сообщение и его -связи с вложениями SHALL сохраняться одной транзакцией. +связи с вложениями SHALL сохраняться одной транзакцией. Вложение, которое стало +`failed` после отправки, остаётся в `attachment_ids` сообщения. #### Scenario: Вложение другого участника @@ -180,3 +187,25 @@ capability `pagination`. Любой участник SHALL видеть все вложением - **THEN** оба ответа 201, у обоих сообщений это вложение в `attachment_ids` + +#### Scenario: Вложение в обработке + +- **WHEN** worker остановлен, участник загрузил файл и сразу отправляет + сообщение с этим вложением +- **THEN** ответ 201, `attachment_ids` содержит вложение, его метаданные — + `queued`, а история отдаёт это сообщение + +#### Scenario: Вложение failed + +- **WHEN** вложение чата стало `failed`, и участник отправляет сообщение с ним, + а затем с ним и случайным UUID +- **THEN** первый ответ 409 `conflict`, второй — 404 `not_found`, сообщений не + создано, а ключ идемпотентности свободен: новая отправка с этим ключом без + вложения — 201 + +#### Scenario: Вложение стало failed после отправки + +- **WHEN** участник отправил сообщение с вложением в `queued`, а затем вложение + стало `failed` +- **THEN** история отдаёт сообщение с его `attachment_ids`, а метаданные вложения — + `failed` с `error_code` diff --git a/openspec/specs/object-storage/spec.md b/openspec/specs/object-storage/spec.md index 22409810..8b39b687 100644 --- a/openspec/specs/object-storage/spec.md +++ b/openspec/specs/object-storage/spec.md @@ -103,16 +103,18 @@ Bootstrap SHALL: - завести пользователя API с политикой доступа (требование «Ограниченные учётные данные API») и ключами из `.env`; - завести пользователя уборщика с его политикой (требование - «Ограниченные учётные данные уборщика») и ключами из `.env`. + «Ограниченные учётные данные уборщика») и ключами из `.env`; +- завести пользователя worker с его политикой (требование + «Ограниченные учётные данные worker») и ключами из `.env`. -На рабочем стенде реплики API и уборщик MUST NOT стартовать, пока +На рабочем стенде реплики API, уборщик и worker MUST NOT стартовать, пока bootstrap не завершился успешно. Стенды проверок с S3 (`make test_isolated`, `make failure_checks`) запускают bootstrap до своих -контейнеров API, а стенд отказов — и до своего уборщика. +контейнеров API и worker, а стенд отказов — и до своего уборщика. Повторный запуск SHALL завершаться успешно и не менять уже правильное состояние: bucket и его объекты сохраняются, пользователи не -пересоздаются. Если в `.env` изменился секрет API или уборщика, +пересоздаются. Если в `.env` изменился секрет API, уборщика или worker, повторный запуск SHALL привести к нему учётные данные этого пользователя, а прежний секрет SHALL перестать действовать. @@ -122,19 +124,19 @@ test_isolated`, `make failure_checks`) запускают bootstrap до сво #### Scenario: Первый запуск - **WHEN** стенд поднимается на пустом volume S3 -- **THEN** bootstrap создаёт bucket, пользователей API и уборщика и - завершается с кодом 0, и только после этого стартуют реплики API и - уборщик +- **THEN** bootstrap создаёт bucket, пользователей API, уборщика и worker и + завершается с кодом 0, и только после этого стартуют реплики API, уборщик + и worker #### Scenario: Повторный запуск - **WHEN** на работающем стенде bootstrap запускается ещё дважды подряд - **THEN** оба запуска завершаются с кодом 0 и сообщают, что bucket и - оба пользователя уже есть, а записанные ранее объекты читаются + все три пользователя уже есть, а записанные ранее объекты читаются #### Scenario: Новый секрет API -- **WHEN** в `.env` изменён секрет API или секрет уборщика, и bootstrap +- **WHEN** в `.env` изменён секрет API, уборщика или worker, и bootstrap запущен снова - **THEN** запросы S3 с новым секретом этого пользователя проходят, а с прежним получают отказ @@ -266,13 +268,15 @@ SHALL получать 403 на: ### Requirement: Проверка приватности вне API -Приватность bucket и права ключей API и уборщика SHALL проверяться без -участия приложения двумя способами. +Приватность bucket и права ключей API, уборщика и worker SHALL проверяться +без участия приложения двумя способами. 1. Каждый запуск bootstrap: - ключ API записывает и читает проверочный объект и получает отказ на список и на создание bucket; - - ключ уборщика читает и удаляет этот объект. Он получает отказ на + - ключ worker записывает и читает проверочный объект и получает отказ на + удаление, на список и на создание bucket; + - ключ уборщика читает и удаляет проверочный объект. Он получает отказ на запись и на список всего bucket, а список с префиксом вложений своей базы у него проходит; - аноним получает отказ на чтение существующего объекта и на список. @@ -282,8 +286,8 @@ SHALL получать 403 на: 2. Отдельная команда `make s3_check` на запущенном стенде. Она повторяет проверки bootstrap и добавляет: - анонимные запросы с хоста и из сети стенда; - - запросы ключей API и уборщика к чужому bucket; - - административные запросы ключей API и уборщика; + - запросы ключей API, уборщика и worker к чужому bucket; + - административные запросы ключей API, уборщика и worker; - запись ключом уборщика; - его список всего bucket и с чужим префиксом — отказ, с префиксом вложений своей базы — 200. @@ -296,8 +300,9 @@ SHALL получать 403 на: - **WHEN** на запущенном стенде выполняется `make s3_check` - **THEN** каждая проверка напечатана с полученным кодом ответа, в том - числе проверки списка ключом уборщика по своему и чужому префиксу, код - выхода 0, а проверочных объектов и bucket после команды нет + числе проверки списка ключом уборщика по своему и чужому префиксу и + отказ ключу worker на удаление и список, код выхода 0, а проверочных + объектов и bucket после команды нет #### Scenario: Bucket стал публичным @@ -331,7 +336,8 @@ SHALL сохраняться и после принудительного зав Процессы приложения SHALL обращаться к S3 с учётными данными своей роли из секции `[s3]`: реплики API — ключами пользователя API, уборщик — -ключами пользователя уборщика. Клиент SHALL уметь: +ключами пользователя уборщика, worker — ключами пользователя worker. Клиент +SHALL уметь: - записать объект; - прочитать его потоком; - получить метаданные; @@ -417,3 +423,38 @@ bucket — ошибка, а не пустая страница. После во S3 - **THEN** вызов завершается ошибкой недоступности, а в журнале есть запись уровня `error` без секрета + +### Requirement: Ограниченные учётные данные worker + +У worker (capability `attachment-processing`) SHALL быть свои учётные данные +S3, отдельные от учётных данных API, уборщика и административных. Пользователю +worker SHALL быть разрешены только чтение и запись объектов своего bucket: он +читает staging и пишет в конечный префикс. + +Пользователю worker MUST NOT быть разрешены: +- удаление объектов; +- список объектов; +- операции с bucket: создание, удаление, политика, ACL; +- публичный ACL объекта; +- управление учётными записями; +- любой доступ к другим bucket. + +Ключи worker MUST NOT передаваться репликам API и уборщику. Worker MUST NOT +получать ключи API и уборщика, административные ключи S3 и ключ подписи. + +#### Scenario: Работа worker с объектами + +- **WHEN** ключом worker записан объект и прочитан, в том числе объект, записанный + ключом API +- **THEN** все операции проходят, а прочитанные байты совпадают с записанными + +#### Scenario: Запрещённые операции worker + +- **WHEN** ключом worker запрашиваются: + - удаление объекта; + - список объектов, в том числе с префиксом вложений базы; + - создание и удаление bucket, политика и ACL bucket; + - публичный ACL объекта; + - объект другого bucket и его список +- **THEN** каждый запрос получает 403, объект на месте, а bucket и его доступ + не меняются diff --git a/openspec/specs/service-configuration/spec.md b/openspec/specs/service-configuration/spec.md index 1486ae1e..a3cda219 100644 --- a/openspec/specs/service-configuration/spec.md +++ b/openspec/specs/service-configuration/spec.md @@ -126,7 +126,7 @@ SHALL быть в `REPORT.md`. Переключение между запуском в консоли и в docker MUST NOT требовать правки `.env`, `config.toml` или compose, в том числе комментирования и раскомментирования блоков. В консоли сервис SHALL -подключаться к PostgreSQL, Valkey и S3 по адресам публикации на хосте +подключаться к PostgreSQL, Valkey, S3 и брокеру по адресам публикации на хосте из `.env`, в docker — по адресам и портам внутри сети compose, которые compose передаёт в окружение контейнера из переменных `.env`. @@ -136,7 +136,7 @@ compose передаёт в окружение контейнера из пер `make run_docker`, а файлы конфигурации между запусками не менялись - **THEN** оба запуска доходят до `/health/ready` 200, видят одни и те же данные и пишут карточки чатов в Valkey, а запись о старте называет - S3 стенда: в консоли — адрес публикации на хосте, в docker — адрес в + S3 и брокер стенда: в консоли — адрес публикации на хосте, в docker — адрес в сети compose ### Requirement: Подключение к Valkey @@ -165,18 +165,18 @@ SHALL получать случайный пароль. Пароль MUST NOT п - адрес и порт; - имя bucket; - ключи пользователя S3 процесса: у реплик API — пользователя API, у - уборщика — пользователя уборщика; + уборщика — пользователя уборщика, у worker — пользователя worker; - регион; - срок вызова и срок установки соединения; - размер пула соединений клиента. -Секреты API и уборщика SHALL иметь по одному источнику — переменной +Секреты API, уборщика и worker SHALL иметь по одному источнику — переменной `.env`, которую читает и bootstrap S3. Процесс получает свой секрет мостом или через `environment` compose. Имя bucket читают и приложение, и bootstrap, поэтому в `.env` оно записывается в формате настроек. Новый `.env` из `make env_setup` SHALL получать случайные секреты S3: -административный секрет, секрет API, секрет уборщика и ключ подписи. -В существующий `.env` `make env_setup` SHALL дописывать переменные +административный секрет, секрет API, секрет уборщика, секрет worker и ключ +подписи. В существующий `.env` `make env_setup` SHALL дописывать переменные шаблона, которых в нём нет: секреты — случайными значениями, остальные — значениями шаблона. Существующие строки он MUST NOT менять, а в вывод SHALL печатать только имена дописанных переменных, без значений. @@ -202,13 +202,13 @@ MUST NOT стартовать (требование «Некорректное - **WHEN** `make env_setup` дважды выполняется в каталоге без `.env`, и между запусками `.env` удаляется -- **THEN** секреты S3, в том числе секрет уборщика, в обоих `.env` - непустые и различаются +- **THEN** секреты S3, в том числе секреты уборщика и worker, и пароль брокера в + обоих `.env` непустые и различаются #### Scenario: Недостающие переменные в существующем .env - **WHEN** в существующем `.env` нет переменных, которые есть в шаблоне - (например, секретов уборщика), и выполняется `make env_setup` + (например, секретов worker и брокера), и выполняется `make env_setup` - **THEN** эти переменные дописаны в конец `.env`, секреты среди них непустые, прежние строки не изменились, а вывод называет только имена дописанных переменных; повторный запуск ничего не дописывает @@ -508,3 +508,86 @@ pending_grace_seconds` и его проверку границы живой за `RECONCILER__MAX_OBJECTS_PER_SECOND=inf` - **THEN** уборщик не стартует, в журнале — ошибка проверки настроек с именем поля + +### Requirement: Подключение к брокеру + +Параметры брокера SHALL задаваться в секции `[broker]`: +- адрес и порт; +- пользователь и пароль; +- срок установки соединения; +- срок публикации — от начала публикации до подтверждения брокера, включая + установку соединения; по умолчанию 2 с. + +Пароль SHALL иметь один источник — переменную `.env`, которую читает и контейнер +брокера. Новый `.env` из `make env_setup` SHALL получать случайный пароль. Пароль +MUST NOT попадать в журнал. Сроки SHALL быть положительными числами, иначе сервис +MUST NOT стартовать (требование «Некорректное значение останавливает запуск»). +Разовая подмена SHALL работать через окружение `BROKER__*` без правки файлов. + +Соответствие имени skeleton `BROKER_URL_FILE` реальной конфигурации SHALL быть +описано в шапке `.env.example` и в `REPORT.md`. + +#### Scenario: Пароль брокера в одном месте + +- **WHEN** в `.env` задан пароль брокера, и стенд поднят на новом volume +- **THEN** брокер, реплики и worker в консоли и в docker используют его без правки + других файлов + +#### Scenario: Пароль брокера не в журнале + +- **WHEN** сервис и worker стартуют и обращаются к брокеру, в том числе при его + недоступности +- **THEN** в журнале нет значения пароля + +#### Scenario: Запись о старте называет брокер + +- **WHEN** реплика API и worker стартуют +- **THEN** их записи о старте называют адрес брокера и имя очереди, а срок публикации + по умолчанию — 2 с + +#### Scenario: Неверный срок публикации + +- **WHEN** сервис запускается с `BROKER__PUBLISH_TIMEOUT_SECONDS=0` или `abc` +- **THEN** сервис не стартует, в журнале — ошибка проверки настроек с именем поля + +### Requirement: Параметры worker + +Параметры worker (capability `attachment-processing`) SHALL задаваться в секции +`[worker]`: +- `concurrency` — сколько заданий worker обрабатывает одновременно, по умолчанию 2; +- `max_attempts` — сколько попыток у задания, по умолчанию 5; +- `job_timeout_seconds` — срок одной попытки, по умолчанию 60; +- `retry_delay_seconds` — пауза перед следующей попыткой, по умолчанию 10; +- `graceful_shutdown_seconds` — сколько worker ждёт начатые задания после SIGTERM, + по умолчанию 8, не больше 9; +- `reconnect_seconds` — пауза между попытками соединиться с брокером, по умолчанию 2. + +`concurrency` и `max_attempts` SHALL быть целыми не меньше 1, сроки — положительными +числами. Иначе worker MUST NOT стартовать: код выхода ненулевой, а ошибка называет +поле. Разовая подмена SHALL работать через окружение `WORKER__*` без правки файлов. +Реплики API секцию `[worker]` не используют. Запись о старте worker SHALL называть +все значения. + +Соответствие имён skeleton `WORKER_CONCURRENCY`, `JOB_MAX_ATTEMPTS` и +`JOB_TIMEOUT_SECONDS` этим полям, а `STAGING_RETENTION_SECONDS` — очистке staging в +следующем изменении SHALL быть описано в шапке `.env.example` и в `REPORT.md`. + +#### Scenario: Параметры worker по умолчанию + +- **WHEN** worker запущен без секции `[worker]` и без переменных `WORKER__*` +- **THEN** запись о его старте называет конкуренцию 2, 5 попыток, срок 60 с, паузу + 10 с, срок остановки 8 с и паузу соединения 2 с + +#### Scenario: Подмена параметров worker окружением + +- **WHEN** worker запущен с `WORKER__CONCURRENCY=1` и `WORKER__MAX_ATTEMPTS=2`, а + файлы не менялись +- **THEN** запись о старте называет эти значения, и одновременно обрабатывается одно + задание + +#### Scenario: Неверный параметр worker + +- **WHEN** worker запускается с `WORKER__CONCURRENCY=0`, `WORKER__MAX_ATTEMPTS=abc` или + `WORKER__GRACEFUL_SHUTDOWN_SECONDS=10` +- **THEN** worker не стартует, код выхода ненулевой, в журнале — запись с именем поля + без значений настроек diff --git a/openspec/specs/service-logging/spec.md b/openspec/specs/service-logging/spec.md index 6a26ce0b..e9110fe4 100644 --- a/openspec/specs/service-logging/spec.md +++ b/openspec/specs/service-logging/spec.md @@ -87,10 +87,13 @@ - байты объектов; - `filename` вложений. +С лабы 5 записи MUST NOT содержать пароль брокера и тела его сообщений. + Для обращений к S3 допускаются адрес S3, имя bucket, ключ объекта, размер, длительность и класс ошибки. Для вложений допускаются `id` вложения и чата, размер, тип, ширина и высота изображения, длина -`filename` и причина отказа в загрузке. +`filename` и причина отказа в загрузке. Для обращений к брокеру допускаются адрес +брокера, имя очереди, `id` задания и вложения, длительность и класс ошибки. #### Scenario: Отправка сообщения @@ -128,8 +131,14 @@ - **WHEN** участник загружает изображение с уникальным `filename` F, а затем повреждённый файл с тем же именем - **THEN** ни одна запись журнала не содержит F; запись о загрузке - содержит `id` вложения, размер и тип, а запись об отказе — причину - отказа без имени файла + содержит `id` вложения, `id` задания, размер и тип, а запись об отказе — + причину отказа без имени файла + +#### Scenario: Отказ публикации задания + +- **WHEN** брокер остановлен, и участник загружает файл +- **THEN** в журнале реплики есть запись `warning` об отказе брокера и запись о + непереданном задании с `id` вложения, а пароля брокера и `filename` в журнале нет ### Requirement: Непредвиденные ошибки в журнале @@ -234,3 +243,35 @@ SHA-256. затронутые объекты S3, запросы к S3 по операциям, прочитанные байты, сеансы с PostgreSQL и длительность каждого шага, а секретов S3, `filename` и SHA-256 объектов в журнале нет + +### Requirement: Журнал worker + +Worker (capability `attachment-processing`) SHALL писать журнал в формате этой +capability: JSON-записи в stdout, в каждой `instance_id` процесса worker и `request_id` +— `id` обрабатываемого задания. Записи: +- старт — конкуренция, число попыток, сроки, адрес брокера и имя очереди, адрес S3, + bucket и имя базы; +- взятое задание — `id` задания и вложения, номер попытки, признак повторной доставки; +- готовое вложение — размеры thumbnail, размер объекта, длительность; +- новая попытка — код причины, номер попытки, пауза; уровень `warning`; +- `failed` — код и причина; уровень `warning`; +- пропущенное сообщение — причина: задание завершено, неизвестно, занято; +- сообщение не по схеме — уровень `error`, без содержимого сообщения; +- отказ брокера, S3 или PostgreSQL — уровень `warning`, непредвиденная ошибка — `error` с + traceback; +- остановка процесса с кодом выхода. + +Записи worker MUST NOT содержать `filename` вложений, байты объектов, тела сообщений, +ключи доступа и секреты S3, пароль брокера и пароль PostgreSQL. + +#### Scenario: Обработка в журнале + +- **WHEN** worker доводит вложение с уникальным `filename` F до `ready` +- **THEN** все записи этого задания связаны одним `request_id` — `id` задания, в них + есть номер попытки, размеры thumbnail и длительность, а F и секретов в журнале нет + +#### Scenario: Постоянная ошибка в журнале + +- **WHEN** вложение стало `failed` с `invalid_image` +- **THEN** в журнале есть запись `warning` с `id` задания и вложения и кодом, без + stack trace и байтов diff --git a/openspec/specs/storage-consistency/spec.md b/openspec/specs/storage-consistency/spec.md index 9be6a85b..eb66aae3 100644 --- a/openspec/specs/storage-consistency/spec.md +++ b/openspec/specs/storage-consistency/spec.md @@ -21,7 +21,7 @@ Незавершённую загрузку SHALL убирать уборщик — отдельный процесс стенда (capability `container-run`), а не реплики API. Незавершённая загрузка — вложение, которое осталось в статусе «загружается» (capability -`attachments`, «Порядок записи»). +`attachments`, «Порядок записи»): на него ещё не ответили 202. Уборщик SHALL проходить по незавершённым загрузкам не реже чем раз в `[cleaner] interval_seconds`. Каждую загрузку, метаданные которой @@ -29,7 +29,8 @@ period), он SHALL убирать по шагам: 1. пометить её метаданные как убираемые и зафиксировать пометку (требование «Безопасность уборки»); -2. удалить объект по ключу из её метаданных; отсутствие объекта — не +2. удалить объект: staging по ключу из её метаданных, а у загрузки прежней + версии без ключа staging — объект конечного ключа; отсутствие объекта — не ошибка; 3. только после подтверждённого удаления объекта — удалить метаданные. @@ -42,56 +43,66 @@ period), он SHALL убирать по шагам: метаданных, если процесс API заморожен дольше grace посреди записи объекта. После разморозки он дописывает объект уже убранной загрузки, а удалить его не может: запись объекта завершилась для API ошибкой по -сроку, или не удалось удаление при компенсации. Такой объект находит и -удаляет сверка bucket и БД (требование «Сверка bucket и БД»), когда он -старше grace. На стенде это происходит не позже следующей плановой -сверки (требование «Плановая сверка»). +сроку, или не удалось удаление при компенсации. Такой объект под конечным +префиксом находит и удаляет сверка bucket и БД (требование «Сверка bucket и +БД»), когда он старше grace, на стенде — не позже следующей плановой сверки +(требование «Плановая сверка»). Такой объект в staging сверка не видит: его +убирает очистка staging в `pipeline-reliability`. #### Scenario: Зависшая загрузка убрана - **WHEN** загрузка оборвалась после записи метаданных: S3 был остановлен или заморожен на время записи объекта, либо PostgreSQL - отказал при фиксации `ready`. С записи метаданных прошло больше grace, + отказал при фиксации `queued`. С записи метаданных прошло больше grace, S3 и PostgreSQL доступны - **THEN** ни метаданных, ни объекта этого вложения нет, а в bucket нет объектов вложений без метаданных #### Scenario: Объект без фиксации убран -- **WHEN** объект вложения записан в S3, а процесс API убит до фиксации - `ready` +- **WHEN** объект вложения записан в staging, а процесс API убит до + фиксации `queued` - **THEN** до истечения grace есть и метаданные в статусе «загружается», и объект, а после него нет ни того, ни другого, и в bucket нет объектов вложений без метаданных +#### Scenario: Загрузка без подтверждения брокера убрана + +- **WHEN** загрузка получила 503, потому что брокер не подтвердил задание, + и с записи метаданных прошло больше grace +- **THEN** ни метаданных, ни объекта staging этого вложения нет, а задание у + него было отменено ещё до ответа + ### Requirement: Безопасность уборки -Уборщик MUST NOT трогать готовые вложения (`ready`) ни в каком возрасте. -Незавершённую загрузку моложе grace он тоже MUST NOT трогать. +Уборщик MUST NOT трогать принятые вложения (`queued`, `processing`, `ready`, +`failed`) ни в каком возрасте: на них уже ответили 202, и это либо текущая +работа, либо её итог. Незавершённую загрузку моложе grace он тоже MUST NOT +трогать. Grace SHALL быть больше наибольшего времени, за которое живая загрузка -проходит путь от записи метаданных до фиксации `ready`. Это два шага с +проходит путь от записи метаданных до фиксации `queued`. Это два шага с PostgreSQL и запись объекта, у каждого свой срок (capability -`service-configuration`, «Параметры уборщика»). Возраст загрузки -отсчитывается от записи её метаданных по часам приложения. Ожидание -места загрузки, чтение тела и проверка изображения (capability -`attachments`, «Одновременные загрузки реплики», «Срок передачи тела») -SHALL идти до записи метаданных и в эту границу не входят: очередь -загрузок и медленный клиент её не удлиняют. +`service-configuration`, «Параметры уборщика»). Публикация брокеру идёт после +фиксации и в эту границу не входит. Возраст загрузки отсчитывается от записи её +метаданных по часам приложения. Ожидание места загрузки, чтение тела и проверка +изображения (capability `attachments`, «Одновременные загрузки реплики», «Срок +передачи тела») SHALL идти до записи метаданных и в эту границу не входят: +очередь загрузок и медленный клиент её не удлиняют. Загрузка, которая длится дольше grace (процесс API заморожен), и уборщик SHALL исключать друг друга на одном вложении. Исходов два: -- вложение стало `ready` вместе с объектом, и уборщик его не трогает; +- вложение стало `queued` вместе с заданием, и уборщик его не трогает; - уборщик начал его уборку, а загрузка отвечает 503 `unavailable` и удаляет записанный ею объект. До удаления объекта уборщик SHALL помечать метаданные вложения как убираемые и фиксировать пометку отдельно. Помеченное вложение MUST NOT -становиться `ready`. Поэтому сбой уборки после удаления объекта не даёт -вложения `ready` без объекта: загрузка отвечает 503, а уборку доводит +становиться `queued`. Поэтому сбой уборки после удаления объекта не даёт +принятого вложения без объекта: загрузка отвечает 503, а уборку доводит следующий проход. Сбой — например, не удалось удалить метаданные, или -S3 выполнил удаление уже после срока вызова. Вложение `ready` без -объекта MUST NOT появляться ни при каком порядке этих действий. +S3 выполнил удаление уже после срока вызова. Принятое вложение без +объекта staging MUST NOT появляться ни при каком порядке этих действий. Ограничение называется в `REPORT.md`. Пока идёт поочерёдная замена реплик API, реплики прежней версии пометку не проверяют. Для их @@ -99,20 +110,20 @@ S3 выполнил удаление уже после срока вызова. #### Scenario: Загрузка дольше grace -- **WHEN** загрузка записала объект, а к переводу в `ready` её +- **WHEN** загрузка записала объект, а к переводу в `queued` её метаданным уже больше grace, и уборщик убирает их, пока загрузка ждёт перевода -- **THEN** ответ 503 `unavailable`, а не 201 и не 500, нет ни +- **THEN** ответ 503 `unavailable`, а не 202 и не 500, нет ни метаданных, ни объекта этого вложения, а в bucket нет объектов вложений без метаданных #### Scenario: Сбой уборки после удаления объекта -- **WHEN** загрузка ждёт перевода в `ready`, её метаданным больше grace, +- **WHEN** загрузка ждёт перевода в `queued`, её метаданным больше grace, а уборщик удалил её объект, но удалить метаданные не смог: PostgreSQL отказал -- **THEN** ответ загрузки 503 `unavailable`, а не 201, метаданные в - статусе «загружается», и вложения `ready` без объекта нет +- **THEN** ответ загрузки 503 `unavailable`, а не 202, метаданные в + статусе «загружается», и принятого вложения без объекта нет - **AND** когда удаление метаданных снова проходит, уборщик доводит уборку, и в bucket нет объектов вложений без метаданных @@ -130,12 +141,20 @@ S3 выполнил удаление уже после срока вызова. - **THEN** метаданные вложения — 200 в статусе `ready`, а байты скачиваются с тем же SHA-256 +#### Scenario: Текущая работа не тронута + +- **WHEN** worker остановлен, у вложений в `queued`, `processing` и `failed` + возраст больше grace, и уборщик всё это время работает +- **THEN** их метаданные и объекты staging на месте, а после запуска worker + вложение в `queued` становится `ready` + #### Scenario: Ожидание места не входит в возраст загрузки - **WHEN** загрузка ждала места, пока его держала другая загрузка того - же процесса, и обе завершились 201 + же процесса, и обе завершились 202 - **THEN** время записи метаданных ожидавшей (`created_at`) позже - перевода в `ready` той, что держала место (`updated_at`) + перевода в `queued` той, что держала место (`updated_at` снимка из её + ответа) ### Requirement: Уборка при отказах хранилищ @@ -170,8 +189,9 @@ S3 выполнил удаление уже после срока вызова. `<имя базы>/attachments/` — с метаданными вложений той же базы в PostgreSQL и находить расхождения семи классов: - **объект без метаданных** — объект с ключом вида - `<база>/attachments//original`, на который не ссылается ни одна - строка и для `id` которого строки нет; + `<база>/attachments//original` или ключом варианта + `<база>/attachments//v<версия>-<вариант>`, на который не ссылается ни + одна строка и для `id` которого строки нет; - **метаданные без объекта** — вложение `ready`, объекта по ключу из его метаданных в bucket нет; - **другой размер** — вложение `ready`, размер объекта не равен @@ -192,6 +212,12 @@ PostgreSQL и находить расхождения семи классов: - ключ вне префикса вложений своей базы в метаданных вложения: объект по такому ключу сверка не читает. +Объект варианта, у `id` которого строка есть, расхождением не считается, в +каком бы состоянии ни было вложение. Объекты staging — ключи вне префикса +вложений — сверка MUST NOT читать и менять: это текущая работа. Наличие и размер +объектов вариантов сверка на этом уровне не проверяет; это ограничение SHALL быть +в `REPORT.md`. + Сверку SHALL выполнять процесс уборщика, а не реплики API: разовым проходом (`make reconcile` или команда сверки в контейнере уборщика) и плановым (требование «Плановая сверка»). Разовый проход по умолчанию @@ -260,7 +286,7 @@ SHA-256 его содержимого с метаданными. Планова - у готового вложения удалён объект; - у неиспользуемого готового вложения удалены метаданные; - у другого в метаданных изменён размер; - - загрузка оборвалась между записью объекта и фиксацией `ready` + - загрузка оборвалась между записью объекта и фиксацией `queued` - **THEN** отчёт называет каждое расхождение его классом, ключом и возрастом, код выхода 3, а в PostgreSQL и в bucket ничего не изменилось @@ -316,12 +342,31 @@ SHA-256 его содержимого с метаданными. Планова - **AND** сверка с `--deep --apply` помечает Y1 и Y2 потерянными, а все четыре объекта на месте +#### Scenario: Объекты вариантов своих вложений + +- **WHEN** готовые вложения с thumbnail старше grace, и выполняется сверка без + `--apply` обеими стратегиями +- **THEN** объекты вариантов не названы расхождениями и чужими, а код выхода не + зависит от них + +#### Scenario: Объект варианта без метаданных + +- **WHEN** в bucket мимо API записан объект с ключом варианта, для `id` которого + строки нет, ему больше grace, и выполняется сверка с `--apply` +- **THEN** объект удалён, а отчёт называет его объектом без метаданных + ### Requirement: Безопасность сверки Сверка MUST NOT удалять: - метаданные вложений, кроме уборки зависшей загрузки; - объект, на который ссылаются метаданные, в любом статусе; -- объект с ключом вида `/original`, если строка этого `id` есть. +- объект с ключом вида `/original` или ключом варианта, если строка + этого `id` есть; +- объект staging. + +Вложение в `queued`, `processing` или `failed` сверка MUST NOT помечать +потерянным и считать зависшей загрузкой: объекта конечного префикса у него может +не быть, это текущая работа или её итог. Вложение, на которое ссылается сообщение, MUST NOT терять из-за сверки ни метаданные, ни объект, ни ссылку в истории. Если его оригинал @@ -431,7 +476,7 @@ NOT читать и менять. Вложение, в метаданных ко #### Scenario: Предел не останавливает уборку зависших -- **WHEN** загрузка оборвалась между записью объекта и фиксацией `ready` +- **WHEN** загрузка оборвалась между записью объекта и фиксацией `queued` больше grace назад, расхождений, которые сверка исправила бы, больше предела, и выполняется сверка с `--apply` - **THEN** код выхода 3, ни одно вложение не помечено, а зависшей @@ -466,8 +511,17 @@ NOT читать и менять. Вложение, в метаданных ко - в это время сверка с `--apply` повторяется раз в несколько секунд; - в стенде есть внесённые расхождения - **THEN** внесённые расхождения исправлены, каждое вложение, загрузка - которого ответила 201, скачивается с тем же SHA-256, а каждое - сообщение отдаёт свои `attachment_ids` + которого ответила 202, становится `ready` и скачивается с тем же SHA-256, а + каждое сообщение отдаёт свои `attachment_ids` + +#### Scenario: Текущая работа не считается расхождением + +- **WHEN** worker остановлен, вложения в `queued`, `processing` и `failed` + старше grace, их объекты в staging, у одного из них уже есть объект конечного + ключа, и выполняется сверка с `--apply` +- **THEN** ни одно из них не названо расхождением и не помечено потерянным, а их + метаданные, объекты staging и этот объект конечного ключа на месте, код выхода + от них не зависит ### Requirement: Потерянный оригинал diff --git a/openspec/specs/student-tests/spec.md b/openspec/specs/student-tests/spec.md index fca57f9e..543daee2 100644 --- a/openspec/specs/student-tests/spec.md +++ b/openspec/specs/student-tests/spec.md @@ -41,16 +41,16 @@ MUST завершаться с ненулевым кодом и сообщени Тесты SHALL обращаться к сервису только по HTTP и MUST NOT импортировать код приложения, запускать или останавливать сервер. Проверки отказов -SHALL действовать на хранилища стенда и узнавать их состояние только -через hook, который им передаёт `make failure_checks`. Без hook они +SHALL действовать на хранилища стенда, брокер и worker и узнавать их состояние +только через hook, который им передаёт `make failure_checks`. Без hook они MUST завершаться ошибкой с указанием этой команды, а не обращаться к хранилищам сами. Один и тот же набор SHALL проходить против сервера, запущенного на хосте, и против контейнера. #### Scenario: Консоль и контейнер -- **WHEN** набор запускается сначала против `make run_dev`, затем против - `make run_docker` +- **WHEN** набор запускается сначала против `make run_dev` с `make run_worker`, + затем против `make run_docker` - **THEN** оба прогона проходят одинаково #### Scenario: Проверка отказа без hook @@ -234,8 +234,9 @@ MUST NOT считаться пройденными. При `EXPECT_REPLICAS` ≥ Для каждого сценария основных спеков `api-conventions`, `identification`, `sessions`, `users`, `chats`, `messages`, -`pagination`, `data-storage`, `chat-cache`, `health`, `idempotency` и с -лабы 4 `attachments` и `storage-consistency`, который воспроизводится +`pagination`, `data-storage`, `chat-cache`, `health`, `idempotency`, с +лабы 4 `attachments` и `storage-consistency` и с лабы 5 +`attachment-processing` и `message-broker`, который воспроизводится по HTTP против работающего сервера, в том числе на стенде отказов, SHALL быть тест. Из имени или описания теста SHALL быть понятно, какой capability и сценарий он проверяет. Сценарий, который проверяет тест @@ -291,17 +292,17 @@ commit, адресом стенда и итогом. `REPORT.md` SHALL ссыл `make test_isolated` SHALL проверять образ, собранный из рабочего дерева, в связке compose на временной базе `test_<имя рабочей базы>` в -PostgreSQL стенда, с Valkey и S3 стенда. Команда SHALL по порядку: -1. поднять PostgreSQL, Valkey и S3 с bootstrap; +PostgreSQL стенда, с Valkey, S3 и брокером стенда. Команда SHALL по порядку: +1. поднять PostgreSQL, Valkey, S3 с bootstrap и брокер; 2. собрать образ и создать базу заново; 3. применить к ней миграции сервисом миграций compose; -4. запустить отдельный контейнер API из определения сервиса compose, в - котором подменено только имя базы, и опубликовать его на +4. запустить отдельный контейнер API и отдельный контейнер worker из определений + сервисов compose, в которых подменено только имя базы, и опубликовать API на `127.0.0.1:TEST_APP_PORT` из `.env`; 5. дождаться готовности и выполнить публичный smoke (`make test`) и весь набор (`make student_test`) против этого контейнера; -6. остановить и удалить контейнер, удалить базу и объекты S3 под - префиксом `test_/`. +6. остановить и удалить оба контейнера, удалить базу, объекты S3 под + префиксом `test_/` и очередь временной базы. Это один процесс API без балансировщика: набор SHALL запускаться с `EXPECT_REPLICAS=1`, и тесты реплик пропускаются с причиной. Код @@ -312,9 +313,10 @@ PostgreSQL стенда, с Valkey и S3 стенда. Команда SHALL по - карточки чатов в Valkey — именем базы в ключе (capability `chat-cache`); - объекты в S3 — префиксом имени базы в ключе объекта (capability - `object-storage`). + `object-storage`); +- задания — именем базы в имени очереди (capability `message-broker`). -Объекты рабочей базы при уборке MUST NOT удаляться. Параллельный +Объекты и очередь рабочей базы при уборке MUST NOT удаляться. Параллельный запуск двух прогонов не поддерживается. #### Scenario: Успешный прогон @@ -322,36 +324,36 @@ PostgreSQL стенда, с Valkey и S3 стенда. Команда SHALL по - **WHEN** в рабочей базе есть данные, рабочий стенд запущен, и выполнен `make test_isolated` - **THEN** smoke и набор прошли, тесты реплик пропущены с причиной, - код выхода 0, ни базы `test_`, ни тестового контейнера, ни - объектов под префиксом `test_/` после команды нет, число строк в - таблицах рабочей базы и объекты рабочей базы не изменились, а - рабочий стенд продолжает отвечать через балансировщик + код выхода 0, ни базы `test_`, ни тестовых контейнеров, ни + объектов под префиксом `test_/`, ни очереди временной базы после команды + нет, число строк в таблицах рабочей базы и объекты рабочей базы не изменились, + а рабочий стенд продолжает отвечать через балансировщик #### Scenario: Упавшие тесты - **WHEN** во время `make test_isolated` падает хотя бы один тест -- **THEN** код выхода ненулевой, журнал тестового контейнера выведен, - контейнер удалён, база `test_` и объекты под префиксом - `test_/` удалены +- **THEN** код выхода ненулевой, журналы тестовых контейнеров выведены, + контейнеры удалены, база `test_`, объекты под префиксом `test_/` и + очередь временной базы удалены #### Scenario: Прерывание - **WHEN** `make test_isolated` прерван Ctrl+C -- **THEN** тестовый контейнер остановлен и удалён, база `test_` и - объекты под префиксом `test_/` удалены +- **THEN** тестовые контейнеры остановлены и удалены, база `test_`, объекты + под префиксом `test_/` и очередь временной базы удалены #### Scenario: Хвост прошлого прогона -- **WHEN** тестовый контейнер, база `test_` или объекты под - префиксом `test_/` остались от прогона, убитого без уборки +- **WHEN** тестовые контейнеры, база `test_`, объекты под префиксом + `test_/` или очередь временной базы остались от прогона, убитого без уборки - **THEN** следующий `make test_isolated` удаляет их и начинает заново #### Scenario: Сохранить базу для разбора - **WHEN** выполнен `make test_isolated KEEP_TEST_DB=1` -- **THEN** после прогона тестовый контейнер удалён, база `test_` и - объекты под префиксом `test_/` остаются, а команда печатает имя - базы и префикс +- **THEN** после прогона тестовые контейнеры удалены, база `test_`, объекты под + префиксом `test_/` и очередь временной базы остаются, а команда печатает имя + базы, префикс и очередь ### Requirement: Проверки отказов на отдельном стенде @@ -362,24 +364,29 @@ PostgreSQL стенда, с Valkey и S3 стенда. Команда SHALL по - `data-storage`: «Сбой при добавлении участников», «БД остановлена», «БД вернулась», «Соединения исчерпаны»; - `health`: «Хранилище не готово», «Кэш недоступен», «Хранилище - объектов недоступно»; + объектов недоступно», «Брокер и worker недоступны»; - `chat-cache`: «Valkey остановлен», «Valkey завис», «Valkey вернулся», «Очистка кэша»; - `idempotency`: «Сбой при записи сообщения», «Отказ БД при отправке», - «Ключ после срока»; + «Ключ после срока», «Повтор после failed вложения»; - `api-conventions`: «Лимит одновременных загрузок»; +- `messages`: «Вложение в обработке», «Вложение стало failed после отправки»; - `attachments`: «Запись в S3 не удалась», «Отклонённая загрузка ничего не оставляет», «S3 остановлен», «S3 завис», «Незавершённая загрузка не - видна», «Сбой записи метаданных», «Фиксация ready не удалась», «Обрыв - передачи тела», «Отказ раньше очереди», «Все места заняты», «Очередь - ожидания полна», «Ожидание места», «Место освобождается», «Медленный - клиент», «Медленная передача в срок», «Потерянный оригинал», «Загрузка - после простоя S3»; + видна», «Сбой записи метаданных», «Фиксация задания не удалась», «Фиксация ready не + удалась», «Исход фиксации неизвестен», «Брокер не подтвердил задание», «Обрыв + передачи тела», «Отказ раньше + очереди», «Все места заняты», «Очередь ожидания полна», «Ожидание места», «Место + освобождается», «Медленный клиент», «Медленная передача в срок», «Потерянный + оригинал», «Загрузка после простоя S3», «Скачивание до готовности»; +- `attachment-processing`: все сценарии, которым нужны остановка worker, брокера или + S3 и сбой внутри обработки; +- `message-broker`: все сценарии, которые не названы исключениями сверки покрытия; - `storage-consistency`: все сценарии. Команда SHALL: - собрать образ из рабочего дерева; -- поднять отдельный стенд со своими PostgreSQL, Valkey и S3, применить +- поднять отдельный стенд со своими PostgreSQL, Valkey, S3 и брокером, применить миграции и bootstrap S3; - запустить четыре API: - с настройками по умолчанию; @@ -398,6 +405,8 @@ PostgreSQL стенда, с Valkey и S3 стенда. Команда SHALL по загрузки (`service-configuration`, «Параметры уборщика»). Сверку проверки запускают сами, и плановая сверка не меняет стенд у них за спиной; +- запустить worker с короткими сроками и малым числом попыток, сравнимыми со + временем теста, и передать их значения проверкам; - выполнить проверки отказов; - удалить стенд вместе с его данными при любом исходе. @@ -405,16 +414,25 @@ Hook стенда отказов SHALL уметь: - сообщить вложения стенда в PostgreSQL с их статусами, `id` последнего вложения в статусе «загружается» и `id` вложений с потерянным оригиналом; -- сообщить, у каких вложений есть объект в bucket стенда, — по самим - объектам, а не по каталогам хранилища; +- сообщить задание вложения: идентификатор, состояние, число начатых попыток, + причину последней ошибки, время следующей попытки и время подтверждения брокером; +- сообщить, у каких вложений есть объект в конечном префиксе и в staging bucket + стенда, и сколько у вложения объектов вариантов, — по самим объектам, а не по + каталогам хранилища; - внедрить отказ PostgreSQL: - при записи метаданных загрузки с заданным `filename`; - - при фиксации её `ready`, и задержать такую фиксацию; + - при фиксации её `queued`, и задержать такую фиксацию; + - при фиксации `ready` с заданным `filename`, и задержать такую фиксацию; - при пометке потерянного оригинала такого вложения; - убить и снова запустить обычный API стенда; +- остановить, убить, заморозить и запустить брокер и worker стенда; +- сообщить состояние очереди: сообщений, готовых, неподтверждённых, потребителей, + устойчива ли она; +- прочитать сообщение из очереди без подтверждения, добавить в очередь сообщение + и удалить очередь; - внести расхождения хранилищ: - записать объект в bucket стенда мимо API и удалить объект мимо API — - только под префиксом вложений базы стенда; + только под префиксами вложений и staging базы стенда; - удалить метаданные вложения, изменить в них размер и сдвинуть их время в прошлое; - выполнить разовую сверку — без изменений или с `--apply`, с заданным @@ -426,12 +444,12 @@ Hook стенда отказов SHALL уметь: Других сведений о хранилищах проверки вложений не получают. Объекты без метаданных проверка находит сравнением двух списков: вложений и -объектов. Ключи доступа S3 hook не получает и не печатает: объект мимо -API записывает процесс в контейнере стенда своими ключами. +объектов. Ключи доступа S3 и пароль брокера hook не получает и не печатает: объект +мимо API и сообщение в очередь записывает процесс в контейнере стенда своими ключами. -Порты PostgreSQL, Valkey и S3 этого стенда MUST NOT публиковаться на +Порты PostgreSQL, Valkey, S3 и брокера этого стенда MUST NOT публиковаться на хосте, API — только на `127.0.0.1`. Рабочий стенд, его база, кэш, -хранилище объектов и контейнеры MUST NOT затрагиваться. Код выхода +хранилище объектов, брокер и контейнеры MUST NOT затрагиваться. Код выхода SHALL быть ненулевым, если не прошла хотя бы одна проверка или уборка. Параллельный запуск двух прогонов не поддерживается: уборка хвоста в начале второго удаляет стенд первого. @@ -446,7 +464,7 @@ SHALL быть ненулевым, если не прошла хотя бы од #### Scenario: Упавшая проверка - **WHEN** во время `make failure_checks` падает хотя бы одна проверка -- **THEN** код выхода ненулевой, журналы API и уборщика стенда отказов +- **THEN** код выхода ненулевой, журналы API, уборщика и worker стенда отказов выведены, стенд отказов удалён #### Scenario: Прерывание @@ -472,7 +490,7 @@ SHALL быть ненулевым, если не прошла хотя бы од называть сценарий и путь. Такое доказательство MUST NOT содержать токенов, паролей и их хэшей -целиком, ключей доступа и секретов S3 — только факты, счётчики и +целиком, ключей доступа и секретов S3, пароля брокера — только факты, счётчики и префиксы. #### Scenario: Ссылка на отсутствующий файл @@ -497,9 +515,17 @@ SHALL быть ненулевым, если не прошла хотя бы од `attachments` «Принявшая реплика остановлена», «Байты не в БД и не на диске API» и «Рестарт стенда» - **THEN** в них вывод названной в исключении команды на стенде с - балансировщиком, двумя репликами и S3, дата и commit, SHA-256 + балансировщиком, двумя репликами, S3, брокером и worker, дата и commit, SHA-256 загруженного и скачанного файла, а токенов и секретов S3 нет +#### Scenario: Обработка на стенде лабы + +- **WHEN** проверяющий открывает файлы, на которые ссылаются исключения + `attachment-processing` и `message-broker` +- **THEN** в них вывод названной в исключении команды на стенде с балансировщиком, + двумя репликами, брокером и worker, дата и commit, а токенов, секретов S3 и пароля + брокера нет + ### Requirement: PostgreSQL стенда отказов без аварийных перезапусков Проверки отказов MUST NOT приводить к аварийному перезапуску PostgreSQL @@ -531,3 +557,45 @@ PostgreSQL стенда отказов и искать признаки авар перезапустился аварийно - **THEN** код выхода команды ненулевой, найденные строки журнала выведены, а стенд отказов удалён + +### Requirement: Готовность вложения в тестах + +Тест, которому нужны байты вложения, SHALL ждать `ready` опросом метаданных со сроком, +а не считать вложение готовым после ответа 202. Срок ожидания — не больше 60 с, как у +публичного smoke. Истёк срок или вложение стало `failed` — тест SHALL падать и называть +последнее состояние. Проверки формы ответа 202 SHALL идти до ожидания: `status` `queued`, +`variants` `[]`, `error_code` null. Ослаблять проверки и пропускать сценарии вложений +ради этого перехода MUST NOT. + +#### Scenario: Ожидание готовности + +- **WHEN** тест загружает файл, ждёт `ready` и скачивает оригинал +- **THEN** загрузка проверена по схеме контракта как 202 со `status` `queued`, а + скачивание — 200 с теми же байтами + +#### Scenario: Worker не работает + +- **WHEN** worker стенда не запущен, и выполняется `make student_test` +- **THEN** тесты, которым нужна готовность, падают с сообщением, что вложение не стало + `ready` за срок, и называют его состояние `queued` + +### Requirement: Сценарий защиты автоматизирован + +Сценарий защиты из `README.md` SHALL быть автоматизирован на стенде отказов и командой +драйвера на рабочем стенде: worker остановлен → загрузка 202 → сообщение с вложением 201 → +скачивание 409 → текстовое сообщение 201 → перезапуск API и брокера с сохранёнными volumes → +worker запущен → то же вложение `ready`, оригинал равен загруженному, thumbnail — настоящий +JPEG. Команда драйвера SHALL печатать порядок действий и `id` без токенов и завершаться +ненулевым кодом при расхождении, а её вывод SHALL сохраняться в `evidence/`. Worker SHALL +быть запущен снова при любом исходе. + +#### Scenario: Команда на рабочем стенде + +- **WHEN** на запущенном рабочем стенде выполняется команда защиты драйвера +- **THEN** код выхода 0, вывод называет шаги, коды ответов, `id` вложения и сообщения и время + старта контейнеров API и брокера до и после, а токенов и секретов в выводе нет + +#### Scenario: Сбой посреди сценария + +- **WHEN** сценарий команды прерван расхождением или сигналом +- **THEN** worker снова запущен, а код выхода ненулевой diff --git a/pyproject.toml b/pyproject.toml index d74792ac..7ba6699a 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -23,6 +23,10 @@ dependencies = [ # клиент S3 (SeaweedFS), решение 6 design change s3-storage; # botocore закреплён узко, обновлять вместе через uv lock "aiobotocore>=3.9.2,<4", + # клиент RabbitMQ (design change async-attachments, решение 5) + "aio-pika>=10.2.1,<11", + # thumbnail в процессе worker; импортирует только src/utils/thumbnail.py + "pillow>=13,<14", ] [project.optional-dependencies] @@ -66,9 +70,6 @@ dev = [ "pytest>=9.1.1,<10", "httpx>=0.28.1,<1", "jsonschema>=4.26.0,<5", - # student-tests: JPEG разных видов в памяти теста; в образ (uv sync - # --no-dev) и в приложение не входит - "pillow>=13.0.0,<14", ] [tool.pytest.ini_options] diff --git a/scripts/restart.sh b/scripts/restart.sh index 1bba1eea..56d5e725 100755 --- a/scripts/restart.sh +++ b/scripts/restart.sh @@ -3,10 +3,13 @@ set -eu # Restart hook для make test-persistence (tests/README.md) по образцу # scripts/restart.example.sh; правила — .claude/rules/docker.md. # Перезапускает балансировщик, все реплики API и все хранилища стенда -# (Postgres, Valkey и S3) с сохранением volumes, схемы и данных: без +# (Postgres, Valkey, S3 и брокер) с сохранением volumes, схемы и данных: без # down -v, FLUSHALL и повторного наполнения. Кэш Valkey после рестарта # пуст: persistence у него выключен, данные — в Postgres. Bucket, учётные -# записи и объекты S3 лежат в его volume. +# записи и объекты S3 лежат в его volume, очередь и сообщения — в volume +# брокера. Worker и уборщик hook не трогает: они не реплики и не хранилища, +# рестарт хранилищ переживают сами. Остановленный worker останется +# остановленным (сценарий защиты). # LB гасится первым и поднимается последним. start поднимает те же # контейнеры всех реплик: число реплик не меняется (реплика, остановленная # stop-one.sh, тоже запускается). start api запускает и его зависимости @@ -16,11 +19,11 @@ set -eu cd "$(dirname "$0")/.." docker compose stop haproxy api -docker compose restart postgres valkey s3 +docker compose restart postgres valkey s3 rabbitmq # те же контейнеры: --wait только дожидается их healthcheck. # --no-recreate обязателен: Compose 5.4 пересоздаёт контейнер, если его # образ скачивался при первом up (в метке — digest индекса, при сверке — # манифеста платформы), и s3-bootstrap (network_mode: service:s3) после # пересоздания s3 не стартует — код 128, start api падает -docker compose up -d --wait --no-recreate postgres valkey s3 +docker compose up -d --wait --no-recreate postgres valkey s3 rabbitmq docker compose start api haproxy diff --git a/scripts/rolling-update.sh b/scripts/rolling-update.sh index d3f4d058..f06e1c62 100755 --- a/scripts/rolling-update.sh +++ b/scripts/rolling-update.sh @@ -26,8 +26,9 @@ set -eu # ROLLOUT_READY_TIMEOUT (60) — срок готовности новой реплики, с; # ROLLOUT_DRAIN_TIMEOUT (90) — срок дренажа старой, с: больше timeout # server пути загрузки и наибольшей длительности загрузки (LB 30 с, -# загрузка ≈ 73 с — haproxy.cfg, design change upload-memory, решение -# 7), иначе плановая замена оборвала бы живую загрузку. Обычно дренаж +# загрузка ≈ 76 с — haproxy.cfg, design change upload-memory, решение +# 7; async-attachments, решение 3), иначе плановая замена оборвала бы +# живую загрузку. Обычно дренаж # кончается за 0–2 с, срок нужен только медленной загрузке. # Проект compose — как у самого docker compose: COMPOSE_PROJECT_NAME, # COMPOSE_FILE, COMPOSE_ENV_FILES или docker-compose.yml и .env diff --git a/src/api/dependencies.py b/src/api/dependencies.py index e66459b3..f34fcaad 100644 --- a/src/api/dependencies.py +++ b/src/api/dependencies.py @@ -2,8 +2,9 @@ Сервисы получают сессию БД, а чаты и сообщения — ещё и кэш процесса (`src/infra/cache/instance.py`). Вложения — фабрику короткой сессии на -шаг, кэш, хранилище объектов (`src/infra/s3/instance.py`) и места -загрузок процесса (`src/infra/upload_slots.py`). +шаг, кэш, хранилище объектов (`src/infra/s3/instance.py`), места +загрузок процесса (`src/infra/upload_slots.py`) и издатель заданий +(`src/infra/broker/instance.py`). """ import base64 @@ -28,6 +29,7 @@ from src.core.services import ( SessionService, UserService, ) +from src.infra.broker.instance import job_publisher from src.infra.cache.instance import cache from src.infra.db import ping from src.infra.db.scope import session_scope @@ -111,6 +113,7 @@ async def get_attachment_service() -> AttachmentService: cache=cache, storage=object_storage, slots=upload_slots, + publisher=job_publisher, ) diff --git a/src/api/errors.py b/src/api/errors.py index 2a01422f..d11f0930 100644 --- a/src/api/errors.py +++ b/src/api/errors.py @@ -28,6 +28,9 @@ DOMAIN_ERRORS: dict[type[exceptions.DomainError], tuple[int, ErrorCode]] = { exceptions.Unauthenticated: (401, ErrorCode.UNAUTHORIZED), exceptions.UsernameTaken: (409, ErrorCode.CONFLICT), exceptions.IdempotencyConflict: (409, ErrorCode.CONFLICT), + # вложение не готово и failed в новом сообщении (с лабы 5) + exceptions.AttachmentNotReady: (409, ErrorCode.CONFLICT), + exceptions.AttachmentFailed: (409, ErrorCode.CONFLICT), exceptions.ChatNotFound: (404, ErrorCode.NOT_FOUND), exceptions.AttachmentNotFound: (404, ErrorCode.NOT_FOUND), exceptions.InvalidChatMembers: (400, ErrorCode.INVALID_REQUEST), diff --git a/src/api/routers/v1/attachment.py b/src/api/routers/v1/attachment.py index dc469f52..71a0a795 100644 --- a/src/api/routers/v1/attachment.py +++ b/src/api/routers/v1/attachment.py @@ -1,4 +1,4 @@ -"""Вложения: загрузка, метаданные, байты оригинала. +"""Вложения: загрузка, метаданные, байты оригинала и вариантов. Один роутер с двумя префиксами путей — `/chats/{chat_id}/attachments` и `/attachments/{attachment_id}`: домен один. Сессии БД на весь запрос @@ -18,7 +18,7 @@ from starlette.requests import ClientDisconnect from src.api.dependencies import AttachmentServiceDep, CurrentUserBrief from src.api.schemas import Attachment, DisplayFilename, UuidIn from src.core import exceptions -from src.schemas.enums import ImageType +from src.schemas.enums import AttachmentVariantName, ImageType from src.utils.constants import ( ATTACHMENT_FILENAME_MAX_LENGTH, ATTACHMENT_FILENAME_MIN_LENGTH, @@ -41,7 +41,7 @@ _UPLOAD_BODY = { } _DOWNLOAD_RESPONSES = { 200: { - "description": "Original bytes", + "description": "Original or variant bytes", "content": {image_type.value: _BINARY for image_type in ImageType}, }, } @@ -102,7 +102,7 @@ async def _body(request: Request) -> AsyncIterator[bytes]: @router.post( "/chats/{chat_id}/attachments", - status_code=201, + status_code=202, response_model=Attachment, openapi_extra=_UPLOAD_BODY, ) @@ -113,7 +113,8 @@ async def upload_attachment( request: Request, attachments: AttachmentServiceDep, ) -> Attachment: - """201 — оригинал в S3 и метаданные в PostgreSQL сохранены. + """202 — оригинал в staging, метаданные и задание в PostgreSQL, брокер + подтвердил сообщение; итог клиент узнаёт по метаданным. Тело не читается, пока не пройдены вход, параметры, членство, `Content-Type` и `Content-Length` (спек «Порядок проверок загрузки»). @@ -154,25 +155,29 @@ async def download_attachment( user: CurrentUserBrief, attachment_id: UuidIn, attachments: AttachmentServiceDep, - # проверка значения — по схеме; вариант на лабе 4 один. enum — как в - # контракте: Literal из одного значения pydantic пишет как const - variant: Annotated[ # noqa: ARG001 - Literal["original"], - Query(json_schema_extra={"enum": ["original"]}), + # перечисление контракта; иное значение — 400 по схеме + variant: Literal[ + "original", + "thumbnail", + "crop", + "optimized", ] = "original", ) -> StreamingResponse: - """Байты оригинала потоком из S3, без redirect. + """Байты оригинала или варианта потоком из S3, без redirect. - `variant` — только `original` (перечисление контракта лабы 4). - Отказ S3 до заголовков — 503; посреди потока соединение обрывается. + Не готовое вложение — 409; варианта нет — 404. Отказ S3 до заголовков — + 503; посреди потока соединение обрывается. """ content = await attachments.open_content( attachment_id=attachment_id, user_id=user.id, + variant=( + None if variant == "original" else AttachmentVariantName(variant) + ), ) return StreamingResponse( content.chunks, - media_type=content.content_type.value, + media_type=content.content_type, headers={ "Content-Length": str(content.size_bytes), "X-Content-Type-Options": "nosniff", diff --git a/src/api/schemas/attachment.py b/src/api/schemas/attachment.py index 1859aa90..335b5633 100644 --- a/src/api/schemas/attachment.py +++ b/src/api/schemas/attachment.py @@ -1,5 +1,5 @@ import unicodedata -from typing import Annotated, Any, Literal +from typing import Annotated, Literal from uuid import UUID from pydantic import AfterValidator, BaseModel, BeforeValidator, ConfigDict @@ -44,8 +44,21 @@ def _sha256_hex(value: object) -> object: DisplayFilename = Annotated[str, AfterValidator(_check_filename)] +class Variant(BaseModel): + """Схема контракта `Variant`; ключа объекта и версии в ней нет.""" + + model_config = ConfigDict(from_attributes=True) + + name: Literal["thumbnail", "crop", "optimized"] + content_type: Literal["image/jpeg", "image/png", "image/webp"] + size_bytes: int + width: int + height: int + sha256: Annotated[str, BeforeValidator(_sha256_hex)] + + class Attachment(BaseModel): - """Схема контракта `Attachment`; ключа объекта в ней нет.""" + """Схема контракта `Attachment`; ключей объектов и `pending` в ней нет.""" model_config = ConfigDict(from_attributes=True) @@ -56,9 +69,9 @@ class Attachment(BaseModel): content_type: ImageType size_bytes: int sha256: Annotated[str, BeforeValidator(_sha256_hex)] - # API показывает только готовые вложения; варианты — с лабы 5 - status: Literal["ready"] - variants: list[dict[str, Any]] = [] - error_code: None = None + # pending наружу не виден: сервис отвечает на него 404 + status: Literal["queued", "processing", "ready", "failed"] + variants: list[Variant] + error_code: str | None created_at: UtcDatetime updated_at: UtcDatetime diff --git a/src/config/settings.py b/src/config/settings.py index c48d2485..de3c7573 100644 --- a/src/config/settings.py +++ b/src/config/settings.py @@ -291,6 +291,64 @@ class Reconciler(BaseModel): ) +class Broker(BaseModel): + """Подключение к RabbitMQ (design change `async-attachments`, решения 5 + и 13). + + Адрес и учётные данные приходят из `.env`: в console — мостами к + `RABBITMQ_*`, в docker — из `environment` compose. Сроки — из + `config.toml`, разовая подмена — окружением `BROKER__*`. Имя skeleton + `BROKER_URL_FILE` сопоставлено в `REPORT.md`: значения, а не файл. + """ + + host: str = "127.0.0.1" + port: int = Field(default=5672, ge=1, le=65535) + user: str = "messenger" + password: SecretStr = SecretStr("") + # секунды на установку соединения с брокером + connect_timeout_seconds: float = Field( + default=2, + gt=0, + allow_inf_nan=False, + ) + # секунды на публикацию целиком: соединение, канал, публикация и + # подтверждение брокера. Часть цепочки таймаутов пути загрузки в LB + publish_timeout_seconds: float = Field( + default=2, + gt=0, + allow_inf_nan=False, + ) + + +class Worker(BaseModel): + """Worker обработки вложений (`python -m src.worker`). + + Значения — из `config.toml`, разовая подмена — окружением `WORKER__*`. + Реплики API секцию не читают. Имена skeleton `WORKER_CONCURRENCY`, + `JOB_MAX_ATTEMPTS`, `JOB_TIMEOUT_SECONDS` сопоставлены в `REPORT.md`. + """ + + # заданий, которые worker обрабатывает одновременно; столько же + # неподтверждённых сообщений выдаёт брокер + concurrency: int = Field(default=2, ge=1) + # начатых попыток у задания, включая первую + max_attempts: int = Field(default=5, ge=1) + # секунды на одну попытку + job_timeout_seconds: float = Field(default=60, gt=0, allow_inf_nan=False) + # секунды паузы перед следующей попыткой + retry_delay_seconds: float = Field(default=10, gt=0, allow_inf_nan=False) + # секунды, которые worker ждёт начатые задания после SIGTERM; docker шлёт + # SIGKILL через 10 с, поэтому не больше 9 + graceful_shutdown_seconds: float = Field( + default=8, + gt=0, + le=9, + allow_inf_nan=False, + ) + # секунды паузы между попытками соединиться с брокером + reconnect_seconds: float = Field(default=2, gt=0, allow_inf_nan=False) + + class Settings(BaseSettings): model_config = SettingsConfigDict( extra="ignore", @@ -309,6 +367,8 @@ class Settings(BaseSettings): uploads: Uploads = Uploads() cleaner: Cleaner = Cleaner() reconciler: Reconciler = Reconciler() + broker: Broker = Broker() + worker: Worker = Worker() @classmethod def settings_customise_sources( diff --git a/src/core/exceptions/__init__.py b/src/core/exceptions/__init__.py index 90de92d6..aba95bd2 100644 --- a/src/core/exceptions/__init__.py +++ b/src/core/exceptions/__init__.py @@ -1,6 +1,8 @@ from .attachment import ( AttachmentContentMissing, + AttachmentFailed, AttachmentNotFound, + AttachmentNotReady, InvalidFilename, PayloadTooLarge, UnsupportedMediaType, @@ -14,12 +16,19 @@ from .idempotency import IdempotencyConflict from .pagination import InvalidCursor from .service import ServiceUnavailable from .session import InvalidCredentials, Unauthenticated -from .storage import ObjectStorageUnavailable, StoredObjectMissing +from .storage import ( + BrokerUnavailable, + ObjectStorageUnavailable, + StoredObjectMissing, +) from .user import UsernameTaken __all__ = [ "AttachmentContentMissing", + "AttachmentFailed", "AttachmentNotFound", + "AttachmentNotReady", + "BrokerUnavailable", "ChatNotFound", "DomainError", "IdempotencyConflict", diff --git a/src/core/exceptions/attachment.py b/src/core/exceptions/attachment.py index aa51488b..9898f036 100644 --- a/src/core/exceptions/attachment.py +++ b/src/core/exceptions/attachment.py @@ -49,6 +49,19 @@ class UploadTimedOut(DomainError): default_message = "Upload body was not received in time" +class AttachmentNotReady(DomainError): + """Байты запрошены у вложения, которое не `ready`: 409 без обращения к + S3.""" + + default_message = "Attachment is not ready" + + +class AttachmentFailed(DomainError): + """В новое сообщение нельзя положить вложение `failed`: 409.""" + + default_message = "Attachment processing failed" + + class AttachmentContentMissing(DomainError): """У готового вложения нет объекта в S3 или его размер другой. diff --git a/src/core/exceptions/storage.py b/src/core/exceptions/storage.py index f0919923..56e15e51 100644 --- a/src/core/exceptions/storage.py +++ b/src/core/exceptions/storage.py @@ -10,6 +10,12 @@ class ObjectStorageUnavailable(ServiceUnavailable): """ +class BrokerUnavailable(ServiceUnavailable): + """Брокер не подтвердил публикацию: недоступен, не ответил за срок, + отказал или сообщению некуда идти. 503 `unavailable`; исход сообщения + по сроку неизвестен (design change `async-attachments`, решение 3).""" + + class StoredObjectMissing(DomainError): """Объекта с таким ключом в bucket нет. diff --git a/src/core/repos/attachment.py b/src/core/repos/attachment.py index ca473bd9..d5dd4754 100644 --- a/src/core/repos/attachment.py +++ b/src/core/repos/attachment.py @@ -2,7 +2,12 @@ Строка пишется в статусе `pending` до записи объекта и переводится в `ready` после неё (design change `attachments`, решение 1). Видимость -`pending` решает сервис: repo отдаёт строку как есть. Незавершённые +`pending` решает сервис: repo отдаёт строку как есть. С лабы 5 (design +change `async-attachments`, решения 1–3) `pending` становится `queued` +вместе с заданием, а `processing`, `ready` и `failed` ставит worker; +`updated_at` пишется через `greatest`: часы консольного API и worker +расходятся, а CHECK `updated_at >= created_at` иначе ронял бы запись. +Незавершённые загрузки выбирает, блокирует, помечает и удаляет уборщик (design change `upload-consistency`, решение 3). Сверка bucket и БД выбирает строки страницы списка S3 и строки `ready`, помечает потерянный оригинал @@ -11,7 +16,7 @@ """ from collections.abc import Collection -from datetime import datetime +from datetime import datetime, timedelta from uuid import UUID from sqlalchemy import ( @@ -23,6 +28,7 @@ from sqlalchemy import ( any_, bindparam, delete, + func, insert, literal, or_, @@ -36,7 +42,11 @@ from sqlalchemy.types import TypeEngine from src.infra.db.models import Attachment from src.schemas import dataclasses -from src.schemas.enums import AttachmentStatus, ImageType +from src.schemas.enums import ( + AttachmentErrorCode, + AttachmentStatus, + ImageType, +) _ATTACHMENT_COLUMNS = ( Attachment.id, @@ -51,6 +61,8 @@ _ATTACHMENT_COLUMNS = ( Attachment.created_at, Attachment.updated_at, Attachment.lost_at, + Attachment.staging_key, + Attachment.error_code, ) @@ -58,9 +70,15 @@ def _to_dto(row: Row) -> dataclasses.AttachmentFullDTO: fields = dict(row._mapping) fields["content_type"] = ImageType(fields["content_type"]) fields["status"] = AttachmentStatus(fields["status"]) + if fields["error_code"] is not None: + fields["error_code"] = AttachmentErrorCode(fields["error_code"]) return dataclasses.AttachmentFullDTO(**fields) +def _later_of_now(now: datetime) -> ColumnElement[datetime]: + return func.greatest(now, Attachment.updated_at) + + async def insert_attachment( db_session: AsyncSession, *, @@ -77,6 +95,7 @@ async def insert_attachment( size_bytes=attachment.size_bytes, sha256=attachment.sha256, object_key=attachment.object_key, + staging_key=attachment.staging_key, status=attachment.status.value, created_at=attachment.created_at, updated_at=attachment.updated_at, @@ -85,19 +104,20 @@ async def insert_attachment( return attachment -async def mark_ready( +async def mark_queued( db_session: AsyncSession, *, attachment_id: UUID, updated_at: datetime, ) -> dataclasses.AttachmentFullDTO | None: - """`pending` → `ready`; `None` — строки `pending` нет или уборщик уже + """`pending` → `queued`; `None` — строки `pending` нет или уборщик уже пометил её к уборке. Вставка пишет `created_at` и `updated_at` одним значением, а уборщик - до удаления объекта сдвигает `updated_at` (`mark_removing`): `ready` + до удаления объекта сдвигает `updated_at` (`mark_removing`): `queued` становится только непомеченная строка (design change - `upload-consistency`, «Уточнения apply», п. 16). + `upload-consistency`, «Уточнения apply», п. 16). `updated_at` растёт: + строка, вернувшаяся в `pending` отменой, больше не переводится. """ statement = ( update(Attachment) @@ -106,13 +126,154 @@ async def mark_ready( Attachment.status == AttachmentStatus.PENDING.value, Attachment.updated_at == Attachment.created_at, ) - .values(status=AttachmentStatus.READY.value, updated_at=updated_at) + .values( + status=AttachmentStatus.QUEUED.value, + updated_at=_later_of_now(updated_at), + ) .returning(*_ATTACHMENT_COLUMNS) ) row = (await db_session.execute(statement)).one_or_none() return None if row is None else _to_dto(row) +async def return_to_pending( + db_session: AsyncSession, + *, + attachment_id: UUID, + updated_at: datetime, +) -> bool: + """Отмена приёма: `queued` → `pending`, брокер не подтвердил задание. + + `updated_at` строго растёт, поэтому строка не равна `created_at`: для + `mark_queued` и уборщика она уже помечена, объект и саму строку убирает + уборщик (design change `async-attachments`, решение 3). + """ + statement = ( + update(Attachment) + .where( + Attachment.id == attachment_id, + Attachment.status == AttachmentStatus.QUEUED.value, + ) + .values( + status=AttachmentStatus.PENDING.value, + updated_at=func.greatest( + updated_at, + Attachment.updated_at + timedelta(microseconds=1), + ), + ) + .returning(Attachment.id) + ) + return (await db_session.execute(statement)).one_or_none() is not None + + +async def mark_processing( + db_session: AsyncSession, + *, + attachment_id: UUID, + updated_at: datetime, +) -> bool: + """`queued` или `processing` (прежняя попытка потеряна) → `processing`. + `ready` и `failed` не трогаются; `False` — условие не выполнено.""" + statement = ( + update(Attachment) + .where( + Attachment.id == attachment_id, + Attachment.status.in_( + ( + AttachmentStatus.QUEUED.value, + AttachmentStatus.PROCESSING.value, + ), + ), + ) + .values( + status=AttachmentStatus.PROCESSING.value, + updated_at=_later_of_now(updated_at), + ) + .returning(Attachment.id) + ) + return (await db_session.execute(statement)).one_or_none() is not None + + +async def return_to_queued( + db_session: AsyncSession, + *, + attachment_id: UUID, + updated_at: datetime, +) -> bool: + """Временная ошибка: `processing` → `queued`.""" + statement = ( + update(Attachment) + .where( + Attachment.id == attachment_id, + Attachment.status == AttachmentStatus.PROCESSING.value, + ) + .values( + status=AttachmentStatus.QUEUED.value, + updated_at=_later_of_now(updated_at), + ) + .returning(Attachment.id) + ) + return (await db_session.execute(statement)).one_or_none() is not None + + +async def commit_ready( + db_session: AsyncSession, + *, + attachment_id: UUID, + updated_at: datetime, +) -> bool: + """`queued` или `processing` → `ready`; `False` — итог уже есть: готовое + вложение не откатывается и не меняет `updated_at`.""" + statement = ( + update(Attachment) + .where( + Attachment.id == attachment_id, + Attachment.status.in_( + ( + AttachmentStatus.QUEUED.value, + AttachmentStatus.PROCESSING.value, + ), + ), + ) + .values( + status=AttachmentStatus.READY.value, + updated_at=_later_of_now(updated_at), + ) + .returning(Attachment.id) + ) + return (await db_session.execute(statement)).one_or_none() is not None + + +async def commit_failed( + db_session: AsyncSession, + *, + attachment_id: UUID, + error_code: AttachmentErrorCode, + updated_at: datetime, +) -> bool: + """`queued` или `processing` → `failed` с кодом; `False` — итог уже + есть.""" + statement = ( + update(Attachment) + .where( + Attachment.id == attachment_id, + Attachment.status.in_( + ( + AttachmentStatus.QUEUED.value, + AttachmentStatus.PROCESSING.value, + ), + ), + ) + .values( + status=AttachmentStatus.FAILED.value, + error_code=error_code.value, + updated_at=_later_of_now(updated_at), + ) + .returning(Attachment.id) + ) + return (await db_session.execute(statement)).one_or_none() is not None + + async def get_attachment( db_session: AsyncSession, *, @@ -141,7 +302,12 @@ async def get_attachments( # незавершённые загрузки для уборщика (design change upload-consistency, # решение 3): условия совпадают с частичным индексом # ix_attachments_pending_created_at -_STALE_COLUMNS = (Attachment.id, Attachment.object_key, Attachment.created_at) +_STALE_COLUMNS = ( + Attachment.id, + Attachment.object_key, + Attachment.created_at, + Attachment.staging_key, +) def _stale_pending(older_than: datetime) -> tuple[ColumnElement[bool], ...]: diff --git a/src/core/repos/attachment_job.py b/src/core/repos/attachment_job.py new file mode 100644 index 00000000..732f59b1 --- /dev/null +++ b/src/core/repos/attachment_job.py @@ -0,0 +1,222 @@ +"""Задание обработки вложения в PostgreSQL (design change `async-attachments`, +решения 1, 3, 7). + +Логическая работа одна на вложение и версию; `id` — `job_id` контракта, при +повторах не меняется. Порядок блокировок везде один: сначала строка задания, +затем вложения. `updated_at` — через `greatest`: часы процессов расходятся. +""" + +from datetime import datetime +from uuid import UUID + +from sqlalchemy import ColumnElement, Row, delete, func, insert, select, update +from sqlalchemy.ext.asyncio import AsyncSession + +from src.infra.db.models import AttachmentJob +from src.schemas import dataclasses +from src.schemas.enums import AttachmentJobReason, AttachmentJobState + +_JOB_COLUMNS = ( + AttachmentJob.id, + AttachmentJob.attachment_id, + AttachmentJob.pipeline_version, + AttachmentJob.state, + AttachmentJob.attempt, + AttachmentJob.created_at, + AttachmentJob.updated_at, + AttachmentJob.last_error_code, + AttachmentJob.next_attempt_at, + AttachmentJob.lease_expires_at, + AttachmentJob.published_at, + AttachmentJob.finished_at, +) + + +def _to_dto(row: Row) -> dataclasses.AttachmentJobDTO: + fields = dict(row._mapping) + fields["state"] = AttachmentJobState(fields["state"]) + return dataclasses.AttachmentJobDTO(**fields) + + +def _later_of_now(now: datetime) -> ColumnElement[datetime]: + return func.greatest(now, AttachmentJob.updated_at) + + +async def insert_job( + db_session: AsyncSession, + *, + job: dataclasses.AttachmentJobDTO, +) -> dataclasses.AttachmentJobDTO: + """Новая работа; вложение становится `queued` в той же транзакции.""" + await db_session.execute( + insert(AttachmentJob).values( + id=job.id, + attachment_id=job.attachment_id, + pipeline_version=job.pipeline_version, + state=job.state.value, + attempt=job.attempt, + created_at=job.created_at, + updated_at=job.updated_at, + ), + ) + return job + + +async def lock_job( + db_session: AsyncSession, + *, + job_id: UUID, +) -> dataclasses.AttachmentJobDTO | None: + """Задание под `FOR UPDATE` до конца транзакции.""" + statement = ( + select(*_JOB_COLUMNS) + .where(AttachmentJob.id == job_id) + .with_for_update() + ) + row = (await db_session.execute(statement)).one_or_none() + return None if row is None else _to_dto(row) + + +async def get_job( + db_session: AsyncSession, + *, + job_id: UUID, +) -> dataclasses.AttachmentJobDTO | None: + statement = select(*_JOB_COLUMNS).where(AttachmentJob.id == job_id) + row = (await db_session.execute(statement)).one_or_none() + return None if row is None else _to_dto(row) + + +async def get_attachment_job( + db_session: AsyncSession, + *, + attachment_id: UUID, + pipeline_version: int, +) -> dataclasses.AttachmentJobDTO | None: + statement = select(*_JOB_COLUMNS).where( + AttachmentJob.attachment_id == attachment_id, + AttachmentJob.pipeline_version == pipeline_version, + ) + row = (await db_session.execute(statement)).one_or_none() + return None if row is None else _to_dto(row) + + +async def start_attempt( + db_session: AsyncSession, + *, + job_id: UUID, + lease_expires_at: datetime, + now: datetime, +) -> dataclasses.AttachmentJobDTO | None: + """Начать попытку под блокировкой `lock_job`: счётчик +1, срок попытки, + `processing`. Вызывающий проверил, что итога ещё нет.""" + statement = ( + update(AttachmentJob) + .where(AttachmentJob.id == job_id) + .values( + state=AttachmentJobState.PROCESSING.value, + attempt=AttachmentJob.attempt + 1, + lease_expires_at=lease_expires_at, + next_attempt_at=None, + updated_at=_later_of_now(now), + ) + .returning(*_JOB_COLUMNS) + ) + row = (await db_session.execute(statement)).one_or_none() + return None if row is None else _to_dto(row) + + +async def return_to_queued( + db_session: AsyncSession, + *, + job_id: UUID, + attempt: int, + reason: AttachmentJobReason, + next_attempt_at: datetime, + now: datetime, +) -> bool: + """Временная ошибка: `processing` → `queued`, только своя попытка (номер + совпал). Сообщение следующей попытки ещё не передано: `published_at` — + NULL. `False` — задание уже ведёт другая попытка или есть итог.""" + statement = ( + update(AttachmentJob) + .where( + AttachmentJob.id == job_id, + AttachmentJob.state == AttachmentJobState.PROCESSING.value, + AttachmentJob.attempt == attempt, + ) + .values( + state=AttachmentJobState.QUEUED.value, + last_error_code=reason.value, + next_attempt_at=next_attempt_at, + lease_expires_at=None, + published_at=None, + updated_at=_later_of_now(now), + ) + .returning(AttachmentJob.id) + ) + return (await db_session.execute(statement)).one_or_none() is not None + + +async def finish_job( + db_session: AsyncSession, + *, + job_id: UUID, + state: AttachmentJobState, + reason: AttachmentJobReason | None, + now: datetime, +) -> bool: + """Итог задания: `succeeded` или `failed`, под блокировкой `lock_job`.""" + values: dict[str, object] = { + "state": state.value, + "lease_expires_at": None, + "next_attempt_at": None, + "finished_at": now, + "updated_at": _later_of_now(now), + } + if reason is not None: + values["last_error_code"] = reason.value + statement = ( + update(AttachmentJob) + .where(AttachmentJob.id == job_id) + .values(**values) + .returning(AttachmentJob.id) + ) + return (await db_session.execute(statement)).one_or_none() is not None + + +async def mark_published( + db_session: AsyncSession, + *, + job_id: UUID, + now: datetime, +) -> bool: + """Брокер подтвердил сообщение. Время — отметка, а не условие: итог + работы от неё не зависит.""" + statement = ( + update(AttachmentJob) + .where(AttachmentJob.id == job_id) + .values(published_at=now, updated_at=_later_of_now(now)) + .returning(AttachmentJob.id) + ) + return (await db_session.execute(statement)).one_or_none() is not None + + +async def delete_unstarted( + db_session: AsyncSession, + *, + job_id: UUID, +) -> bool: + """Отмена приёма: только задание без начатых попыток. `False` — worker + его уже взял, значит, сообщение дошло (design change `async-attachments`, + решение 3).""" + statement = ( + delete(AttachmentJob) + .where( + AttachmentJob.id == job_id, + AttachmentJob.state == AttachmentJobState.QUEUED.value, + AttachmentJob.attempt == 0, + ) + .returning(AttachmentJob.id) + ) + return (await db_session.execute(statement)).one_or_none() is not None diff --git a/src/core/repos/attachment_object.py b/src/core/repos/attachment_object.py index 2edd2e9a..928a10ae 100644 --- a/src/core/repos/attachment_object.py +++ b/src/core/repos/attachment_object.py @@ -1,13 +1,18 @@ -"""Оригинал вложения в S3: ключ объекта и операции над ним. +"""Объекты вложения в S3: ключи и операции над ними. Repo над хранилищем объектов, как `chat_cache.py` над Valkey: первый -параметр — `storage`, один вызов на функцию. Ключ — -`<имя базы>/attachments//original` (design change `attachments`, -решение 4): назначает сервер, `filename` в него не входит; объекты -`make test_isolated` лежат под `test_/`. Ключ хранится в строке -вложения и при чтении берётся оттуда. +параметр — `storage`, один вызов на функцию. Ключи (design change +`attachments`, решение 4; `async-attachments`, решение 1) назначает сервер, +`filename` в них не входит; объекты `make test_isolated` лежат под +`test_/`: +- `<имя базы>/staging//original` — до обработки; +- `<имя базы>/attachments//original` — конечный оригинал; +- `<имя базы>/attachments//v<версия>-<вариант>` — вариант. + +Ключ хранится в строке и при чтении берётся оттуда. """ +import re from contextlib import AbstractAsyncContextManager from typing import BinaryIO from uuid import UUID @@ -18,12 +23,21 @@ from src.infra.s3 import ( StoredObjectInfo, StoredObjectPage, ) +from src.schemas.enums import AttachmentVariantName from src.utils.constants import ( ATTACHMENT_KEY_PREFIX, ATTACHMENT_ORIGINAL_SUFFIX, + ATTACHMENT_STAGING_PREFIX, S3_KEY_SEPARATOR, ) +# последняя часть ключа варианта: версия от 1, без ведущих нулей, и имя +_VARIANT_SUFFIX_PATTERN = re.compile( + r"v[1-9][0-9]*-(" + + "|".join(item.value for item in AttachmentVariantName) + + r")", +) + def original_key(storage: ObjectStorage, *, attachment_id: UUID) -> str: return S3_KEY_SEPARATOR.join( @@ -36,6 +50,35 @@ def original_key(storage: ObjectStorage, *, attachment_id: UUID) -> str: ) +def staging_key(storage: ObjectStorage, *, attachment_id: UUID) -> str: + return S3_KEY_SEPARATOR.join( + ( + storage.namespace, + ATTACHMENT_STAGING_PREFIX, + str(attachment_id), + ATTACHMENT_ORIGINAL_SUFFIX, + ), + ) + + +def variant_key( + storage: ObjectStorage, + *, + attachment_id: UUID, + pipeline_version: int, + name: AttachmentVariantName, +) -> str: + """Ключ эффекта однозначно задаёт ключ объекта: повтор пишет туда же.""" + return S3_KEY_SEPARATOR.join( + ( + storage.namespace, + ATTACHMENT_KEY_PREFIX, + str(attachment_id), + f"v{pipeline_version}-{name.value}", + ), + ) + + def originals_prefix(storage: ObjectStorage) -> str: """Префикс объектов вложений своей базы: `/attachments/`. Других префиксов сверка не читает, список ключу уборщика разрешён @@ -70,6 +113,22 @@ def parse_original_key(storage: ObjectStorage, *, key: str) -> UUID | None: return attachment_id if str(attachment_id) == text else None +def parse_variant_key(storage: ObjectStorage, *, key: str) -> UUID | None: + """`id` вложения из ключа варианта, `id` — UUID в записи сервера; ключ + другого вида — `None`.""" + prefix = originals_prefix(storage) + if not key.startswith(prefix): + return None + parts = key[len(prefix) :].split(S3_KEY_SEPARATOR) + if len(parts) != 2 or not _VARIANT_SUFFIX_PATTERN.fullmatch(parts[1]): + return None + try: + attachment_id = UUID(parts[0]) + except ValueError: + return None + return attachment_id if str(attachment_id) == parts[0] else None + + async def list_originals( storage: ObjectStorage, *, diff --git a/src/core/repos/attachment_variant.py b/src/core/repos/attachment_variant.py new file mode 100644 index 00000000..fa33e0eb --- /dev/null +++ b/src/core/repos/attachment_variant.py @@ -0,0 +1,96 @@ +"""Варианты готового вложения в PostgreSQL (design change +`async-attachments`, решение 1). Ключ эффекта контракта — первичный ключ: +повтор работы второй строки не создаёт. +""" + +from uuid import UUID + +from sqlalchemy import Row, select +from sqlalchemy.dialects.postgresql import insert as pg_insert +from sqlalchemy.ext.asyncio import AsyncSession + +from src.infra.db.models import AttachmentVariant +from src.schemas import dataclasses +from src.schemas.enums import AttachmentVariantName + +_VARIANT_COLUMNS = ( + AttachmentVariant.variant.label("name"), + AttachmentVariant.pipeline_version, + AttachmentVariant.object_key, + AttachmentVariant.content_type, + AttachmentVariant.size_bytes, + AttachmentVariant.width, + AttachmentVariant.height, + AttachmentVariant.sha256, + AttachmentVariant.created_at, +) + + +def _to_dto(row: Row) -> dataclasses.AttachmentVariantDTO: + fields = dict(row._mapping) + fields["name"] = AttachmentVariantName(fields["name"]) + return dataclasses.AttachmentVariantDTO(**fields) + + +async def insert_variant( + db_session: AsyncSession, + *, + attachment_id: UUID, + variant: dataclasses.AttachmentVariantDTO, +) -> bool: + """Вариант по ключу эффекта; `False` — такой уже есть.""" + statement = ( + pg_insert(AttachmentVariant) + .values( + attachment_id=attachment_id, + pipeline_version=variant.pipeline_version, + variant=variant.name.value, + object_key=variant.object_key, + content_type=variant.content_type, + size_bytes=variant.size_bytes, + width=variant.width, + height=variant.height, + sha256=variant.sha256, + created_at=variant.created_at, + ) + .on_conflict_do_nothing( + index_elements=["attachment_id", "pipeline_version", "variant"], + ) + .returning(AttachmentVariant.attachment_id) + ) + return (await db_session.execute(statement)).one_or_none() is not None + + +async def get_variants( + db_session: AsyncSession, + *, + attachment_id: UUID, +) -> list[dataclasses.AttachmentVariantDTO]: + """Варианты вложения в постоянном порядке.""" + statement = ( + select(*_VARIANT_COLUMNS) + .where(AttachmentVariant.attachment_id == attachment_id) + .order_by(AttachmentVariant.variant) + ) + rows = (await db_session.execute(statement)).all() + return [_to_dto(row) for row in rows] + + +async def get_variant( + db_session: AsyncSession, + *, + attachment_id: UUID, + name: AttachmentVariantName, +) -> dataclasses.AttachmentVariantDTO | None: + """Один вариант по имени, самой новой версии обработки.""" + statement = ( + select(*_VARIANT_COLUMNS) + .where( + AttachmentVariant.attachment_id == attachment_id, + AttachmentVariant.variant == name.value, + ) + .order_by(AttachmentVariant.pipeline_version.desc()) + .limit(1) + ) + row = (await db_session.execute(statement)).one_or_none() + return None if row is None else _to_dto(row) diff --git a/src/core/services/attachment.py b/src/core/services/attachment.py index 1f587087..f93d5e13 100644 --- a/src/core/services/attachment.py +++ b/src/core/services/attachment.py @@ -4,6 +4,7 @@ import io import time from collections.abc import AsyncIterator, Callable from contextlib import AbstractAsyncContextManager, AsyncExitStack +from dataclasses import replace from typing import TYPE_CHECKING from uuid import UUID, uuid4 @@ -13,14 +14,27 @@ from sqlalchemy.ext.asyncio import AsyncSession from src.config import settings from src.core import exceptions from src.core.repos import attachment as attachment_repo +from src.core.repos import attachment_job as attachment_job_repo from src.core.repos import attachment_object as attachment_object_repo +from src.core.repos import attachment_variant as attachment_variant_repo from src.core.services.chat import ChatService +from src.infra.broker import JobPublisher from src.infra.cache import Cache from src.infra.logger import AbstractLogger, get_logger from src.infra.s3 import ObjectStorage from src.schemas import dataclasses -from src.schemas.enums import AttachmentStatus, ImageType -from src.utils.constants import ATTACHMENT_MAX_BYTES, ATTACHMENT_MAX_PIXELS +from src.schemas.enums import ( + AttachmentJobState, + AttachmentStatus, + AttachmentVariantName, + ImageType, +) +from src.schemas.jobs import build_job_body +from src.utils.constants import ( + ATTACHMENT_MAX_BYTES, + ATTACHMENT_MAX_PIXELS, + ATTACHMENT_PIPELINE_VERSION, +) from src.utils.image import ( DamagedImage, ImageInfo, @@ -59,6 +73,8 @@ class AttachmentService: `attachments`, решение 5). Загрузка идёт на месте из `slots` — мест процесса (design change `upload-memory`, решение 1); ожидающая загрузка соединения с БД не держит. `filename` в журнал не пишется. + Декодирования здесь нет: изображения обрабатывает worker, а `publisher` + передаёт ему задание (design change `async-attachments`, решение 3). """ def __init__( @@ -67,11 +83,13 @@ class AttachmentService: cache: Cache, storage: ObjectStorage, slots: "UploadSlots", + publisher: JobPublisher, ) -> None: self.db_scope = db_scope self.cache = cache self.storage = storage self.slots = slots + self.publisher = publisher async def _require_member( self, @@ -95,7 +113,7 @@ class AttachmentService: content_length: int | None, body: AsyncIterator[bytes], ) -> dataclasses.AttachmentFullDTO: - """Загрузка оригинала; 201 только после `ready` в БД. + """Приём оригинала; 202 только после подтверждения брокера. Порядок проверок — спек «Порядок проверок загрузки»: членство (404), `Content-Type` (415), `Content-Length` (413) — без места; @@ -104,11 +122,13 @@ class AttachmentService: 413). Место держится до ответа, включая запись и компенсацию. Ожидание места, тело и проверка идут до строки `pending`, поэтому граница живой загрузки уборщика прежняя. Порядок записи (design - change `attachments`, решение 1): строка `pending` с ключом - объекта — commit, PUT, `ready` — commit. Отказ S3 или БД после + change `async-attachments`, решение 3): строка `pending` с ключами + — commit, PUT в staging, `queued` и задание — commit, публикация с + подтверждением, отметка `published_at`. Отказ S3 или БД после строки `pending` — 503, строка остаётся до уборщика; компенсация - после записанного объекта — `_mark_ready` (design change - `upload-consistency`, решение 1). + после записанного объекта — `_mark_queued` (design change + `upload-consistency`, решение 1), отмена при отказе брокера — + `_publish_job`. """ started = time.monotonic() log = logger.bind( @@ -208,10 +228,17 @@ class AttachmentService: self.storage, attachment_id=attachment_id, ), + staging_key=attachment_object_repo.staging_key( + self.storage, + attachment_id=attachment_id, + ), status=AttachmentStatus.PENDING, created_at=now, updated_at=now, ) + staging = pending.staging_key + if staging is None: + raise RuntimeError("Pending attachment has no staging key") async with self.db_scope() as db_session: await attachment_repo.insert_attachment( db_session=db_session, @@ -223,7 +250,7 @@ class AttachmentService: try: await attachment_object_repo.put_original( self.storage, - key=pending.object_key, + key=staging, body=buffer, size=size, content_type=pending.content_type.value, @@ -233,61 +260,142 @@ class AttachmentService: # срок вызова, а тело без ответа сервера не уходит (решение 1) log.warning("Attachment upload left pending", step="put") raise - ready = await self._mark_ready( + # тело устойчиво в staging: на ожидании БД и брокера оно память не + # занимает + buffer.close() + queued, job = await self._mark_queued( attachment_id=attachment_id, - object_key=pending.object_key, + staging=staging, log=log, ) + await self._publish_job(job=job, log=log) log.info( "Uploaded attachment", - size_bytes=ready.size_bytes, - content_type=ready.content_type, + job_id=job.id, + size_bytes=queued.size_bytes, + content_type=queued.content_type, width=info.width, height=info.height, waited_ms=waited_ms, duration_ms=round((time.monotonic() - started) * 1000), ) - return ready + return queued - async def _mark_ready( + async def _mark_queued( self, *, attachment_id: UUID, - object_key: str, + staging: str, log: AbstractLogger, - ) -> dataclasses.AttachmentFullDTO: - """`pending` → `ready` после записанного объекта (решение 1). + ) -> tuple[dataclasses.AttachmentFullDTO, dataclasses.AttachmentJobDTO]: + """`pending` → `queued` и задание одной транзакцией: устойчивое + намерение обработать файл (design change `async-attachments`, + решение 3). - Сбой до отправки COMMIT — вложение `ready` не станет: объект + Сбой до отправки COMMIT — вложение `queued` не станет: объект удаляется до ответа (без гарантии), строку убирает уборщик. Сбой на самом COMMIT — исход неизвестен, объект не трогается. Строки - `pending` уже нет (её убрал уборщик: загрузка пережила grace) — + `pending` уже нет или уборщик её пометил (загрузка пережила grace) — объект удаляется, ответ 503. """ - # True — COMMIT ушёл в PostgreSQL, и вложение могло стать ready + # True — COMMIT ушёл в PostgreSQL, и вложение могло стать queued commit_sent = False + job: dataclasses.AttachmentJobDTO | None = None try: async with self.db_scope() as db_session: - ready = await attachment_repo.mark_ready( + now = utcnow() + queued = await attachment_repo.mark_queued( db_session=db_session, attachment_id=attachment_id, - updated_at=utcnow(), + updated_at=now, ) - commit_sent = ready is not None - await db_session.commit() + if queued is not None: + job = await attachment_job_repo.insert_job( + db_session=db_session, + job=dataclasses.AttachmentJobDTO( + id=uuid4(), + attachment_id=attachment_id, + pipeline_version=ATTACHMENT_PIPELINE_VERSION, + state=AttachmentJobState.QUEUED, + attempt=0, + created_at=now, + updated_at=now, + ), + ) + commit_sent = True + await db_session.commit() except Exception: # CancelledError сюда не попадает: при отмене задачи await # ненадёжен, остаток убирает уборщик - step = "commit" if commit_sent else "ready" + step = "commit" if commit_sent else "queued" log.warning("Attachment upload left pending", step=step) if not commit_sent: - await self._compensate(object_key=object_key, log=log) + await self._compensate(object_key=staging, log=log) raise - if ready is None: - log.error("Pending attachment was removed before ready") - await self._compensate(object_key=object_key, log=log) + if queued is None or job is None: + log.error("Pending attachment was removed before queued") + await self._compensate(object_key=staging, log=log) raise exceptions.ServiceUnavailable - return ready + return queued, job + + async def _publish_job( + self, + *, + job: dataclasses.AttachmentJobDTO, + log: AbstractLogger, + ) -> None: + """Публикация с подтверждением и отметка `published_at`. + + Исход по сроку неизвестен: сообщение могло дойти позже. Решает + условная транзакция отмены: задание ещё не взято — вложение обратно + в `pending` (объект и строку убирает уборщик), 503; взято — сообщение + дошло, ответ 202. Запоздавшее сообщение worker подтверждает без + эффекта: задания нет. Сбой самой отмены или падение процесса + оставляют `queued` без сообщения: разрыв COMMIT и publish, его + закрывает `pipeline-reliability`. Сбой отметки — не сбой приёма. + """ + try: + await self.publisher.publish( + build_job_body(job, attempt=1), + message_id=job.id, + ) + except exceptions.BrokerUnavailable: + cancelled = await self._cancel_job(job=job) + log.warning( + "Attachment job was not published", + job_id=job.id, + outcome="cancelled" if cancelled else "taken", + ) + if cancelled: + raise + return + try: + async with self.db_scope() as db_session: + await attachment_job_repo.mark_published( + db_session=db_session, + job_id=job.id, + now=utcnow(), + ) + await db_session.commit() + except exceptions.ServiceUnavailable: + log.warning("Attachment job publish mark failed", job_id=job.id) + + async def _cancel_job(self, *, job: dataclasses.AttachmentJobDTO) -> bool: + """Отмена приёма; `False` — worker уже взял задание. Порядок + блокировок как у worker: задание, затем вложение.""" + async with self.db_scope() as db_session: + deleted = await attachment_job_repo.delete_unstarted( + db_session=db_session, + job_id=job.id, + ) + if deleted: + await attachment_repo.return_to_pending( + db_session=db_session, + attachment_id=job.attachment_id, + updated_at=utcnow(), + ) + await db_session.commit() + return deleted async def _compensate( self, @@ -295,7 +403,7 @@ class AttachmentService: object_key: str, log: AbstractLogger, ) -> None: - """Удалить объект загрузки, которая не станет `ready`; без повторов. + """Удалить объект загрузки, которая не станет `queued`; без повторов. Не удалось — `warning`, исходная ошибка загрузки уходит дальше, а объект вместе со строкой убирает уборщик. @@ -360,10 +468,11 @@ class AttachmentService: attachment_id: UUID, user_id: UUID, ) -> dataclasses.AttachmentFullDTO: - """Готовое вложение для участника его чата; иначе 404. + """Принятое вложение для участника его чата; иначе 404. Нет строки, она `pending` или пользователь не участник — - одинаковый `AttachmentNotFound`. + одинаковый `AttachmentNotFound`. Варианты — только у `ready`: строка + читается раньше вариантов, поэтому `ready` без них увидеть нельзя. """ async with self.db_scope() as db_session: attachment = await attachment_repo.get_attachment( @@ -372,7 +481,7 @@ class AttachmentService: ) if ( attachment is None - or attachment.status != AttachmentStatus.READY + or attachment.status == AttachmentStatus.PENDING ): raise exceptions.AttachmentNotFound try: @@ -383,6 +492,12 @@ class AttachmentService: ) except exceptions.ChatNotFound as e: raise exceptions.AttachmentNotFound from e + if attachment.status == AttachmentStatus.READY: + variants = await attachment_variant_repo.get_variants( + db_session=db_session, + attachment_id=attachment_id, + ) + attachment = replace(attachment, variants=tuple(variants)) return attachment async def open_content( @@ -390,26 +505,45 @@ class AttachmentService: *, attachment_id: UUID, user_id: UUID, + variant: AttachmentVariantName | None = None, ) -> dataclasses.AttachmentContentDTO: - """Оригинал потоком из S3 (решение 7). + """Оригинал (`variant` `None`) или вариант потоком из S3. - Отказ S3 — 503 до заголовков ответа. Нет объекта или размер в S3 - другой — `error` в журнале и 500; строку сервис не меняет. Оригинал, - который сверка уже пометила потерянным (`lost_at`), — `info` и 404 - без обращения к S3, как отсутствующий вариант готового вложения - (design change `track2-reconciler`, решение 5; ответ — вопрос - преподавателю, вариант по умолчанию). + Доступ — как у метаданных. Вложение не `ready` — 409 без обращения к + S3 (design change `async-attachments`, решение 9). Отказ S3 — 503 до + заголовков ответа. Нет объекта или размер в S3 другой — `error` в + журнале и 500; строку сервис не меняет. Оригинал, который сверка уже + пометила потерянным (`lost_at`), — `info` и 404 без обращения к S3, + как отсутствующий вариант готового вложения (design change + `track2-reconciler`, решение 5; ответ — вопрос преподавателю, вариант + по умолчанию). Варианта у готового вложения нет — 404. """ attachment = await self.get_attachment( attachment_id=attachment_id, user_id=user_id, ) + if attachment.status != AttachmentStatus.READY: + raise exceptions.AttachmentNotReady + if variant is None: + key = attachment.object_key + content_type = attachment.content_type.value + size_bytes = attachment.size_bytes + else: + found = next( + (item for item in attachment.variants if item.name == variant), + None, + ) + if found is None: + raise exceptions.AttachmentNotFound + key = found.object_key + content_type = found.content_type + size_bytes = found.size_bytes log = logger.bind( method="open_content", attachment_id=attachment_id, - object_key=attachment.object_key, + object_key=key, ) - if attachment.lost_at is not None: + if variant is None and attachment.lost_at is not None: log.info("Attachment content is lost") raise exceptions.AttachmentNotFound stack = AsyncExitStack() @@ -417,17 +551,17 @@ class AttachmentService: stored = await stack.enter_async_context( attachment_object_repo.open_original( self.storage, - key=attachment.object_key, + key=key, ), ) except exceptions.StoredObjectMissing as e: log.error("Attachment content is missing") raise exceptions.AttachmentContentMissing from e - if stored.size != attachment.size_bytes: + if stored.size != size_bytes: await stack.aclose() log.error( "Attachment content size differs", - size_bytes=attachment.size_bytes, + size_bytes=size_bytes, stored_size=stored.size, ) raise exceptions.AttachmentContentMissing @@ -440,8 +574,8 @@ class AttachmentService: await stack.aclose() return dataclasses.AttachmentContentDTO( - content_type=attachment.content_type, - size_bytes=attachment.size_bytes, + content_type=content_type, + size_bytes=size_bytes, chunks=chunks(), close=stack.aclose, ) diff --git a/src/core/services/attachment_cleanup.py b/src/core/services/attachment_cleanup.py index 7d41abe6..f3888fc4 100644 --- a/src/core/services/attachment_cleanup.py +++ b/src/core/services/attachment_cleanup.py @@ -189,9 +189,12 @@ class AttachmentCleanupService: ) if locked is None: return False + # строка прежней версии — конечный объект, новая — staging + # (design change async-attachments, решение 11) + object_key = locked.staging_key or locked.object_key await attachment_object_repo.delete_original( self.storage, - key=locked.object_key, + key=object_key, ) await attachment_repo.delete_attachment( db_session=db_session, @@ -201,7 +204,7 @@ class AttachmentCleanupService: log.info( "Removed stale attachment", attachment_id=stale.id, - object_key=stale.object_key, + object_key=object_key, age_seconds=round((utcnow() - stale.created_at).total_seconds()), ) return True diff --git a/src/core/services/attachment_processing.py b/src/core/services/attachment_processing.py new file mode 100644 index 00000000..bbab4649 --- /dev/null +++ b/src/core/services/attachment_processing.py @@ -0,0 +1,605 @@ +"""Обработка задания вложения: сервис процесса worker (`src/worker/`). + +Design change `async-attachments`, решения 2 и 7. `handle` разбирает сообщение, +берёт задание, публикует оригинал из staging в конечный ключ, делает thumbnail +и одной транзакцией фиксирует `ready` с вариантом; что делать с сообщением +(`JobOutcome`) решает итог, подтверждает его `src/worker/main.py`. Доставка at +least once: повтор пишет те же ключи, а метаданные варианта уникальны по ключу +эффекта. + +Каждый шаг с БД — своя короткая транзакция, вызовов S3 внутри транзакций нет. +Порядок блокировок везде один: задание, затем вложение. Счёт попыток — в БД. +""" + +import asyncio +import hashlib +import io +import time +from collections.abc import AsyncIterator +from contextlib import asynccontextmanager +from datetime import timedelta +from uuid import UUID + +import anyio +import anyio.to_thread +from pydantic import ValidationError +from sqlalchemy.ext.asyncio import AsyncSession + +from src.config import settings +from src.core import exceptions +from src.core.repos import attachment as attachment_repo +from src.core.repos import attachment_job as attachment_job_repo +from src.core.repos import attachment_object as attachment_object_repo +from src.core.repos import attachment_variant as attachment_variant_repo +from src.core.services.attachment import DbScope +from src.infra.broker import JobPublisher +from src.infra.logger import AbstractLogger, get_logger, http_request_id +from src.infra.s3 import ObjectStorage +from src.schemas import dataclasses +from src.schemas.enums import ( + AttachmentErrorCode, + AttachmentJobReason, + AttachmentJobState, + AttachmentStatus, + AttachmentVariantName, + JobOutcome, +) +from src.schemas.jobs import AttachmentJobMessage, build_job_body +from src.utils.constants import ATTACHMENT_PIPELINE_VERSION +from src.utils.thumbnail import InvalidImage, RenderedVariant, render_thumbnail +from src.utils.utc import utcnow + +logger: AbstractLogger = get_logger().bind( + module="attachment_processing_service", +) + +_THUMBNAIL_CONTENT_TYPE = "image/jpeg" + + +class _PermanentError(Exception): + """Повтор не исправит: сразу `failed`.""" + + def __init__( + self, + *, + reason: AttachmentJobReason, + error_code: AttachmentErrorCode, + ) -> None: + super().__init__(reason.value) + self.reason = reason + self.error_code = error_code + + +class AttachmentProcessingService: + """Обработка заданий. `db_scope` — короткая сессия процесса worker, + `storage` — клиент S3 с ключами worker, `publisher` — сообщения следующих + попыток, `stop` — сигнал остановки: он прерывает паузы. `limiter` — + потоки декодирования: не больше `[worker] concurrency`.""" + + def __init__( + self, + db_scope: DbScope, + storage: ObjectStorage, + publisher: JobPublisher, + limiter: anyio.CapacityLimiter, + stop: asyncio.Event, + ) -> None: + self.db_scope = db_scope + self.storage = storage + self.publisher = publisher + self.limiter = limiter + self.stop = stop + + async def handle(self, *, body: bytes, redelivered: bool) -> JobOutcome: + """Одна доставка; непредвиденная ошибка до попытки — `error` с + traceback, пауза и возврат в очередь: не немой повтор.""" + try: + message = AttachmentJobMessage.model_validate_json(body) + except ValidationError: + # содержимое сообщения и текст ошибки с его значениями — не в журнал + logger.error("Dropped malformed job message", size_bytes=len(body)) + return JobOutcome.DROP + # задача доставки своя, контекст не уходит к другим заданиям + http_request_id.set(str(message.job_id)) + log = logger.bind( + job_id=message.job_id, + attachment_id=message.attachment_id, + ) + try: + return await self._run( + message=message, + redelivered=redelivered, + log=log, + ) + except exceptions.ServiceUnavailable: + # записать нельзя: задание ждёт в очереди, попытка не считается. + # Причину уже записал session_scope + log.warning("Job waits for database") + await self._pause() + return JobOutcome.REQUEUE + + async def _run( + self, + *, + message: AttachmentJobMessage, + redelivered: bool, + log: AbstractLogger, + ) -> JobOutcome: + claim = await self._claim( + message=message, + redelivered=redelivered, + log=log, + ) + if isinstance(claim, JobOutcome): + return claim + job, attachment = claim + log = log.bind(attempt=job.attempt) + log.info("Started job attempt", redelivered=redelivered) + started = time.monotonic() + try: + async with asyncio.timeout(settings.worker.job_timeout_seconds): + rendered = await self._produce(attachment=attachment, log=log) + committed = await self._commit_ready( + job=job, + attachment=attachment, + rendered=rendered, + ) + except _PermanentError as e: + return await self._fail( + job=job, + error_code=e.error_code, + reason=e.reason, + log=log, + ) + except exceptions.ObjectStorageUnavailable: + return await self._retry( + job=job, + reason=AttachmentJobReason.STORAGE_UNAVAILABLE, + log=log, + ) + except TimeoutError: + return await self._retry( + job=job, + reason=AttachmentJobReason.TIMEOUT, + log=log, + ) + except exceptions.ServiceUnavailable: + raise + except Exception as e: + log.error("Job attempt failed", exc_info=e) + return await self._retry( + job=job, + reason=AttachmentJobReason.UNEXPECTED, + log=log, + ) + if committed: + log.info( + "Attachment became ready", + variant_width=rendered.width, + variant_height=rendered.height, + variant_size_bytes=len(rendered.data), + duration_ms=round((time.monotonic() - started) * 1000), + ) + else: + log.info("Skipped job message", reason="finished") + return JobOutcome.ACK + + async def _claim( + self, + *, + message: AttachmentJobMessage, + redelivered: bool, + log: AbstractLogger, + ) -> ( + tuple[dataclasses.AttachmentJobDTO, dataclasses.AttachmentFullDTO] + | JobOutcome + ): + """Взять задание под блокировкой (таблица решения 7) или вернуть итог + без попытки.""" + busy = False + taken: ( + tuple[dataclasses.AttachmentJobDTO, dataclasses.AttachmentFullDTO] + | None + ) = None + outcome: JobOutcome | None = None + async with self.db_scope() as db_session: + job = await attachment_job_repo.lock_job( + db_session=db_session, + job_id=message.job_id, + ) + if job is None or job.attachment_id != message.attachment_id: + log.info("Skipped job message", reason="unknown") + outcome = JobOutcome.ACK + elif job.state == AttachmentJobState.SUCCEEDED: + await self._check_finished( + db_session=db_session, + job=job, + log=log, + ) + outcome = JobOutcome.ACK + elif job.state == AttachmentJobState.FAILED: + log.info("Skipped job message", reason="finished") + outcome = JobOutcome.ACK + elif ( + job.state == AttachmentJobState.PROCESSING + and not redelivered + and job.lease_expires_at is not None + and job.lease_expires_at > utcnow() + ): + busy = True + elif job.attempt >= settings.worker.max_attempts: + # задание, которое роняет worker: сообщение придёт снова, а + # попытка уже посчитана + await self._write_failed( + db_session=db_session, + job=job, + error_code=AttachmentErrorCode.RETRY_EXHAUSTED, + reason=None, + ) + await db_session.commit() + log.warning( + "Attachment failed", + error_code=AttachmentErrorCode.RETRY_EXHAUSTED.value, + reason=job.last_error_code, + attempt=job.attempt, + ) + outcome = JobOutcome.ACK + else: + taken = await self._start_attempt( + db_session=db_session, + job=job, + ) + await db_session.commit() + if taken is None: + log.info("Skipped job message", reason="unknown") + outcome = JobOutcome.ACK + if busy: + # дубль при живой попытке: второй набор эффектов не нужен. + # Следующая доставка придёт с redelivered, а попытка к тому + # времени обычно закончена + log.info("Skipped job message", reason="busy") + await self._pause() + return JobOutcome.REQUEUE + return taken if taken is not None else (outcome or JobOutcome.ACK) + + async def _start_attempt( + self, + *, + db_session: AsyncSession, + job: dataclasses.AttachmentJobDTO, + ) -> ( + tuple[dataclasses.AttachmentJobDTO, dataclasses.AttachmentFullDTO] + | None + ): + now = utcnow() + started = await attachment_job_repo.start_attempt( + db_session=db_session, + job_id=job.id, + lease_expires_at=now + + timedelta(seconds=settings.worker.job_timeout_seconds), + now=now, + ) + if started is None: + return None + if not await attachment_repo.mark_processing( + db_session=db_session, + attachment_id=job.attachment_id, + updated_at=now, + ): + return None + attachment = await attachment_repo.get_attachment( + db_session=db_session, + attachment_id=job.attachment_id, + ) + return None if attachment is None else (started, attachment) + + @staticmethod + async def _check_finished( + *, + db_session: AsyncSession, + job: dataclasses.AttachmentJobDTO, + log: AbstractLogger, + ) -> None: + """Повторная доставка завершённого: проверка эффекта, без записи.""" + attachment = await attachment_repo.get_attachment( + db_session=db_session, + attachment_id=job.attachment_id, + ) + variant = await attachment_variant_repo.get_variant( + db_session=db_session, + attachment_id=job.attachment_id, + name=AttachmentVariantName.THUMBNAIL, + ) + if ( + attachment is None + or attachment.status != AttachmentStatus.READY + or variant is None + ): + log.error("Finished job has no effect") + return + log.info("Skipped job message", reason="finished") + + async def _produce( + self, + *, + attachment: dataclasses.AttachmentFullDTO, + log: AbstractLogger, + ) -> RenderedVariant: + """Оригинал из staging — в конечный ключ, затем thumbnail: те же + ключи при каждом повторе.""" + data = await self._read_staging(attachment=attachment, log=log) + await attachment_object_repo.put_original( + self.storage, + key=attachment.object_key, + body=io.BytesIO(data), + size=len(data), + content_type=attachment.content_type.value, + ) + try: + # поток не прерывается сроком: отмена дождётся конца декодирования + rendered = await anyio.to_thread.run_sync( + render_thumbnail, + data, + limiter=self.limiter, + ) + except InvalidImage as e: + raise _PermanentError( + reason=AttachmentJobReason.UNDECODABLE, + error_code=AttachmentErrorCode.INVALID_IMAGE, + ) from e + await attachment_object_repo.put_original( + self.storage, + key=self._thumbnail_key(attachment.id), + body=io.BytesIO(rendered.data), + size=len(rendered.data), + content_type=_THUMBNAIL_CONTENT_TYPE, + ) + return rendered + + async def _read_staging( + self, + *, + attachment: dataclasses.AttachmentFullDTO, + log: AbstractLogger, + ) -> bytes: + """Байты staging и сверка с метаданными строки: другие метаданные + worker не читает.""" + corrupted = _PermanentError( + reason=AttachmentJobReason.SOURCE_CORRUPTED, + error_code=AttachmentErrorCode.PROCESSING_FAILED, + ) + missing = _PermanentError( + reason=AttachmentJobReason.SOURCE_MISSING, + error_code=AttachmentErrorCode.PROCESSING_FAILED, + ) + if attachment.staging_key is None: + raise missing + try: + async with attachment_object_repo.open_original( + self.storage, + key=attachment.staging_key, + ) as stored: + if stored.size != attachment.size_bytes: + log.warning( + "Staging object size differs", + size_bytes=attachment.size_bytes, + stored_size=stored.size, + ) + raise corrupted + data = await stored.read() + except exceptions.StoredObjectMissing as e: + raise missing from e + if hashlib.sha256(data).digest() != attachment.sha256: + log.warning("Staging object checksum differs") + raise corrupted + return data + + def _thumbnail_key(self, attachment_id: UUID) -> str: + return attachment_object_repo.variant_key( + self.storage, + attachment_id=attachment_id, + pipeline_version=ATTACHMENT_PIPELINE_VERSION, + name=AttachmentVariantName.THUMBNAIL, + ) + + async def _commit_ready( + self, + *, + job: dataclasses.AttachmentJobDTO, + attachment: dataclasses.AttachmentFullDTO, + rendered: RenderedVariant, + ) -> bool: + """Вложение `ready`, вариант и итог задания — одной транзакцией; + `False` — итог уже есть. Принимается и результат старой попытки: + эффект тот же, те же ключи.""" + async with self.db_scope() as db_session: + locked = await attachment_job_repo.lock_job( + db_session=db_session, + job_id=job.id, + ) + if locked is None: + return False + now = utcnow() + if not await attachment_repo.commit_ready( + db_session=db_session, + attachment_id=attachment.id, + updated_at=now, + ): + return False + await attachment_variant_repo.insert_variant( + db_session=db_session, + attachment_id=attachment.id, + variant=dataclasses.AttachmentVariantDTO( + name=AttachmentVariantName.THUMBNAIL, + pipeline_version=job.pipeline_version, + object_key=self._thumbnail_key(attachment.id), + content_type=_THUMBNAIL_CONTENT_TYPE, + size_bytes=len(rendered.data), + width=rendered.width, + height=rendered.height, + sha256=rendered.sha256, + created_at=now, + ), + ) + await attachment_job_repo.finish_job( + db_session=db_session, + job_id=job.id, + state=AttachmentJobState.SUCCEEDED, + reason=None, + now=now, + ) + await db_session.commit() + return True + + async def _write_failed( + self, + *, + db_session: AsyncSession, + job: dataclasses.AttachmentJobDTO, + error_code: AttachmentErrorCode, + reason: AttachmentJobReason | None, + ) -> bool: + now = utcnow() + if not await attachment_repo.commit_failed( + db_session=db_session, + attachment_id=job.attachment_id, + error_code=error_code, + updated_at=now, + ): + return False + await attachment_job_repo.finish_job( + db_session=db_session, + job_id=job.id, + state=AttachmentJobState.FAILED, + reason=reason, + now=now, + ) + return True + + async def _fail( + self, + *, + job: dataclasses.AttachmentJobDTO, + error_code: AttachmentErrorCode, + reason: AttachmentJobReason, + log: AbstractLogger, + ) -> JobOutcome: + """`failed` своей попытки; задание уже ведёт другая — без записи.""" + async with self.db_scope() as db_session: + locked = await attachment_job_repo.lock_job( + db_session=db_session, + job_id=job.id, + ) + if not self._own_attempt(locked, job=job): + log.info("Skipped job message", reason="busy") + return JobOutcome.ACK + written = await self._write_failed( + db_session=db_session, + job=job, + error_code=error_code, + reason=reason, + ) + await db_session.commit() + if written: + log.warning( + "Attachment failed", + error_code=error_code.value, + reason=reason.value, + ) + return JobOutcome.ACK + + @staticmethod + def _own_attempt( + locked: dataclasses.AttachmentJobDTO | None, + *, + job: dataclasses.AttachmentJobDTO, + ) -> bool: + return ( + locked is not None + and locked.state == AttachmentJobState.PROCESSING + and locked.attempt == job.attempt + ) + + async def _retry( + self, + *, + job: dataclasses.AttachmentJobDTO, + reason: AttachmentJobReason, + log: AbstractLogger, + ) -> JobOutcome: + """Временная ошибка: `queued` и новое сообщение с `attempt + 1` после + паузы. Попытки исчерпаны — `failed`. Отказ брокера — старое сообщение + возвращается, claim возьмёт `queued`.""" + if job.attempt >= settings.worker.max_attempts: + return await self._fail( + job=job, + error_code=AttachmentErrorCode.RETRY_EXHAUSTED, + reason=reason, + log=log, + ) + delay = settings.worker.retry_delay_seconds + async with self.db_scope() as db_session: + now = utcnow() + own = await attachment_job_repo.return_to_queued( + db_session=db_session, + job_id=job.id, + attempt=job.attempt, + reason=reason, + next_attempt_at=now + timedelta(seconds=delay), + now=now, + ) + if not own: + log.info("Skipped job message", reason="busy") + return JobOutcome.ACK + await attachment_repo.return_to_queued( + db_session=db_session, + attachment_id=job.attachment_id, + updated_at=now, + ) + await db_session.commit() + log.warning( + "Retrying job", + reason=reason.value, + delay_seconds=delay, + ) + if await self._pause(): + # остановка: брокер вернёт сообщение, а следующий запуск возьмёт + # задание + return JobOutcome.REQUEUE + try: + await self.publisher.publish( + build_job_body(job, attempt=job.attempt + 1), + message_id=job.id, + ) + except exceptions.BrokerUnavailable: + return JobOutcome.REQUEUE + async with self._step_quietly(log=log) as db_session: + await attachment_job_repo.mark_published( + db_session=db_session, + job_id=job.id, + now=utcnow(), + ) + await db_session.commit() + return JobOutcome.ACK + + @asynccontextmanager + async def _step_quietly( + self, + *, + log: AbstractLogger, + ) -> AsyncIterator[AsyncSession]: + """Отметка, от которой итог работы не зависит: сбой — `warning`.""" + try: + async with self.db_scope() as db_session: + yield db_session + except exceptions.ServiceUnavailable: + log.warning("Attachment job publish mark failed") + + async def _pause(self) -> bool: + """Пауза повтора; `True` — её прервал сигнал остановки.""" + try: + async with asyncio.timeout(settings.worker.retry_delay_seconds): + await self.stop.wait() + except TimeoutError: + return False + return True diff --git a/src/core/services/attachment_reconcile.py b/src/core/services/attachment_reconcile.py index 0ef8f612..92276bcb 100644 --- a/src/core/services/attachment_reconcile.py +++ b/src/core/services/attachment_reconcile.py @@ -420,13 +420,34 @@ class AttachmentReconcileService: ) for item in page.objects } + variants = { + key: variant_id + for key, value in parsed.items() + if value is None + and ( + variant_id := attachment_object_repo.parse_variant_key( + self.storage, + key=key, + ) + ) + is not None + } if state.strategy == ReconcileStrategy.HEAD: for item in page.objects: + variant_id = variants.get(item.key) row = await self._row_for_object( state, key=item.key, - attachment_id=parsed[item.key], + attachment_id=parsed[item.key] or variant_id, ) + if variant_id is not None: + self._classify_variant( + state, + item, + attachment_id=variant_id, + row=row, + ) + continue await self._classify_object( state, item, @@ -434,7 +455,12 @@ class AttachmentReconcileService: row=row, ) else: - await self._classify_page(state, page.objects, parsed) + await self._classify_page( + state, + page.objects, + parsed, + variants, + ) token = page.next_token if token is None: return @@ -444,14 +470,21 @@ class AttachmentReconcileService: state: _Pass, objects: tuple[StoredObjectInfo, ...], parsed: dict[str, UUID | None], + variants: dict[str, UUID], ) -> None: """`batch`: строки страницы одним выражением, ключи — в `seen`. Объект стандартного ключа сравнивается со строкой своего `id`, - нестандартного — с каждой строкой этого ключа. Строку, ключ которой - — `/original` другого вложения, сравнивает шаг строк + нестандартного — с каждой строкой этого ключа, объект варианта — + только с наличием строки своего `id`. Строку, ключ которой — + `/original` другого вложения, сравнивает шаг строк (`_check_rows`).""" ids = {value for value in parsed.values() if value is not None} - keys = {key for key, value in parsed.items() if value is None} + ids.update(variants.values()) + keys = { + key + for key, value in parsed.items() + if value is None and key not in variants + } rows: list[dataclasses.AttachmentFullDTO] = [] if parsed: # страница списка уже могла ждать S3 до срока @@ -469,6 +502,15 @@ class AttachmentReconcileService: for item in objects: state.seen.add(item.key) attachment_id = parsed[item.key] + variant_id = variants.get(item.key) + if variant_id is not None: + self._classify_variant( + state, + item, + attachment_id=variant_id, + row=by_id.get(variant_id), + ) + continue if attachment_id is None and item.key in by_key: for row in by_key[item.key]: await self._row_with_object(state, row=row, stored=item) @@ -509,6 +551,31 @@ class AttachmentReconcileService: return row return None + @staticmethod + def _classify_variant( + state: _Pass, + item: StoredObjectInfo, + *, + attachment_id: UUID, + row: dataclasses.AttachmentFullDTO | None, + ) -> None: + """Объект варианта: строка вложения есть — свой, содержимое на этом + уровне не сверяется (design change `async-attachments`, решение 11); + нет — объект без метаданных, свежий не трогается.""" + if row is not None: + return + if _is_fresh(item, older_than=state.older_than): + state.fresh_objects += 1 + return + state.candidates.append( + dataclasses.ReconcileFindingDTO( + kind=ReconcileFinding.ORPHAN_OBJECT, + object_key=item.key, + attachment_id=attachment_id, + age_seconds=_object_age(state, item), + ), + ) + async def _classify_object( self, state: _Pass, @@ -719,7 +786,12 @@ class AttachmentReconcileService: if self._own_key(row.object_key) else ReconcileFinding.UNKNOWN_OBJECT ), - object_key=row.object_key, + # объект загрузки — в staging; чужой — по ключу строки + object_key=( + (row.staging_key or row.object_key) + if self._own_key(row.object_key) + else row.object_key + ), attachment_id=row.id, age_seconds=state.age(row.created_at), ) diff --git a/src/core/services/message.py b/src/core/services/message.py index fff5bc06..8432141d 100644 --- a/src/core/services/message.py +++ b/src/core/services/message.py @@ -74,9 +74,13 @@ class MessageService: Ключ, сообщение и его связи с вложениями пишутся одной транзакцией, ключ — первым. Повтор того же тела возвращает сохранённое сообщение, другое тело — `IdempotencyConflict` - (design change `instance-id-idempotency`, решения 2–5). Вложения - проверяются до захвата ключа: ошибка его не занимает (design - change `attachments`, решение 8). Ключ не логируется. + (design change `instance-id-idempotency`, решения 2–5). Неизвестное, + чужое и `pending` вложение проверяются до захвата ключа: ошибка его + не занимает (design change `attachments`, решение 8). `failed` — после + захвата: повтор уже отправленного сообщения идёт по прежней ветке и на + текущее состояние вложения не смотрит, а новый ключ откатывается + вместе с транзакцией, и ответ 409 его не занимает (design change + `async-attachments`, решение 9). Ключ не логируется. """ log = logger.bind( method="send_message", @@ -91,8 +95,9 @@ class MessageService: chat_id=chat_id, user_id=sender_id, ) + has_failed = False if attachment_ids: - await self._require_ready_attachments( + has_failed = await self._check_attachments( chat_id=chat_id, attachment_ids=attachment_ids, log=log, @@ -121,6 +126,10 @@ class MessageService: expired_before=now - timedelta(seconds=settings.idempotency.ttl_seconds), ) + if claimed and has_failed: + await self.db_session.rollback() + log.info("Rejected message attachments", reason="failed") + raise exceptions.AttachmentFailed if claimed: await message_repo.insert_message( db_session=self.db_session, @@ -163,33 +172,36 @@ class MessageService: ) return saved.message - async def _require_ready_attachments( + async def _check_attachments( self, *, chat_id: UUID, attachment_ids: Sequence[UUID], log: AbstractLogger, - ) -> None: - """Каждое вложение — готовое вложение этого чата; иначе 404. + ) -> bool: + """Каждое вложение — принятое вложение этого чата; иначе 404. `True` — + среди них есть `failed`: решает ветка после захвата ключа. - Неизвестное, другого чата и `pending` неразличимы. Чат вложения не - меняется, а `ready` не откатывается, поэтому проверка в этой же - транзакции не устареет до commit; существование держит ещё и - внешний ключ связи. + Неизвестное, другого чата и `pending` неразличимы. `queued` и + `processing` можно: клиент узнает итог по метаданным. Вложение, + ставшее `failed` сразу после проверки, даст сообщение со ссылкой на + него — тот же итог, что и `failed` чуть позже отправки. Существование + держит ещё и внешний ключ связи. """ found = await attachment_repo.get_attachments( db_session=self.db_session, attachment_ids=attachment_ids, ) - ready = { - attachment.id + accepted = { + attachment.id: attachment.status for attachment in found if attachment.chat_id == chat_id - and attachment.status == AttachmentStatus.READY + and attachment.status != AttachmentStatus.PENDING } - if not ready.issuperset(attachment_ids): - log.info("Rejected message attachments") + if not accepted.keys() >= set(attachment_ids): + log.info("Rejected message attachments", reason="not_found") raise exceptions.AttachmentNotFound + return AttachmentStatus.FAILED in accepted.values() async def list_messages( self, diff --git a/src/infra/broker/__init__.py b/src/infra/broker/__init__.py new file mode 100644 index 00000000..30ad7e1f --- /dev/null +++ b/src/infra/broker/__init__.py @@ -0,0 +1,15 @@ +from src.infra.broker.client import ( + JobConsumer, + JobDelivery, + JobPublisher, + create_job_publisher, + queue_name, +) + +__all__ = [ + "JobConsumer", + "JobDelivery", + "JobPublisher", + "create_job_publisher", + "queue_name", +] diff --git a/src/infra/broker/client.py b/src/infra/broker/client.py new file mode 100644 index 00000000..f4ee11d6 --- /dev/null +++ b/src/infra/broker/client.py @@ -0,0 +1,321 @@ +"""Клиент RabbitMQ на aio-pika: издатель с подтверждением и потребитель. + +Design change `async-attachments`, решение 5. Соединение открывает первый +вызов, поэтому процесс стартует без брокера. Очередь — классическая durable +`<база>.attachment.process.v1`, без аргументов: их нельзя изменить, а +следующие изменения ставят настройки политиками. Её объявляют и издатель, и +потребитель при каждом соединении, повторное объявление безопасно. + +У `connect_robust` нет места: фоновый reconnect поверх ожидания подтверждения +скрыл бы, что исход публикации неизвестен. Признаку `is_closed` соединения +верить нельзя: проба показала закрытый канал при «живом» соединении, поэтому +издатель сбрасывает соединение после любой ошибки, а новое откроет следующий +вызов. Закрытый канал перед публикацией — брокер перезапускался, пока загрузок +не было: в него ничего не ушло, и это не повтор, а новое соединение. Иначе +первая загрузка после возврата брокера получила бы 503 (спек `message-broker`, +«Брокер вернулся»). Повторов издатель не делает: загрузку повторяет клиент. + +Адрес и пароль передаются отдельными аргументами, строка URL с паролем не +собирается. В журнал — адрес, очередь, `id`, длительность и класс ошибки; +тел сообщений и пароля там нет. +""" + +import asyncio +import time +from collections.abc import AsyncIterator +from dataclasses import dataclass +from typing import Any +from uuid import UUID + +import aio_pika +from aio_pika.abc import ( + AbstractChannel, + AbstractIncomingMessage, + AbstractQueue, + AbstractRobustConnection, +) + +from src.config.settings import Broker as BrokerSettings +from src.core.exceptions import BrokerUnavailable +from src.infra.logger import AbstractLogger, get_logger +from src.utils.constants import ATTACHMENT_QUEUE_SUFFIX + +logger: AbstractLogger = get_logger().bind(module="broker") + +# закрытие прежнего соединения в фоне: при замороженном брокере оно само +# зависло бы +_BACKGROUND_CLOSE_TIMEOUT_SECONDS = 5 + + +def queue_name(namespace: str) -> str: + """Имя очереди заданий базы: прогон на временной базе не смешивается с + рабочим, как объекты S3 и ключи кэша.""" + return f"{namespace}.{ATTACHMENT_QUEUE_SUFFIX}" + + +async def _open_connection( + broker: BrokerSettings, + *, + client_name: str, +) -> AbstractRobustConnection: + return await aio_pika.connect( + host=broker.host, + port=broker.port, + login=broker.user, + password=broker.password.get_secret_value(), + timeout=broker.connect_timeout_seconds, + client_properties={"connection_name": client_name}, + ) + + +async def _declare_queue( + channel: AbstractChannel, + *, + name: str, +) -> AbstractQueue: + return await channel.declare_queue(name, durable=True) + + +class JobPublisher: + """Издатель заданий процесса: одно соединение, публикации по очереди + подтверждений канала. + + `publish` считает сообщение принятым только после подтверждения брокера. + Срок `[broker] publish_timeout_seconds` покрывает соединение, канал, + публикацию и подтверждение. Любая ошибка — `BrokerUnavailable`. + """ + + def __init__(self, broker: BrokerSettings, *, namespace: str) -> None: + self._broker = broker + self.namespace = namespace + self.queue = queue_name(namespace) + self._connection: AbstractRobustConnection | None = None + self._channel: AbstractChannel | None = None + # открытие одно на процесс: конкурентные загрузки ждут его, а не + # открывают по соединению + self._opening = asyncio.Lock() + self._down = False + self._close_tasks: set[asyncio.Task[None]] = set() + + async def publish(self, body: bytes, *, message_id: UUID) -> None: + """Сообщение persistent в очередь через default exchange, `mandatory`: + без маршрута брокер вернёт его, и это ошибка.""" + started = time.monotonic() + channel: AbstractChannel | None = None + try: + async with asyncio.timeout(self._broker.publish_timeout_seconds): + channel = await self._get_channel() + await channel.default_exchange.publish( + aio_pika.Message( + body, + content_type="application/json", + delivery_mode=aio_pika.DeliveryMode.PERSISTENT, + message_id=str(message_id), + ), + routing_key=self.queue, + mandatory=True, + ) + except Exception as e: + self._reset(channel) + self._down = True + logger.warning( + "Broker is unavailable", + broker_host=self._broker.host, + broker_port=self._broker.port, + broker_queue=self.queue, + error_type=type(e).__name__, + duration_ms=round((time.monotonic() - started) * 1000), + ) + raise BrokerUnavailable from e + if self._down: + self._down = False + logger.info( + "Broker is available again", + broker_host=self._broker.host, + broker_port=self._broker.port, + ) + logger.debug( + "Published job", + job_id=message_id, + broker_queue=self.queue, + duration_ms=round((time.monotonic() - started) * 1000), + ) + + async def _get_channel(self) -> AbstractChannel: + if self._channel is not None and self._channel.is_closed: + self._reset(self._channel) + if self._channel is not None: + return self._channel + async with self._opening: + if self._channel is not None: + return self._channel + connection = await _open_connection( + self._broker, + client_name="messenger-publisher", + ) + try: + channel = await connection.channel( + publisher_confirms=True, + on_return_raises=True, + ) + await _declare_queue(channel, name=self.queue) + except BaseException: + self._close_in_background(connection) + raise + self._connection = connection + self._channel = channel + return channel + + def _reset(self, failed: AbstractChannel | None) -> None: + """Сбросить соединение после ошибки; закрытие ответа не держит. + + Конкурентная публикация того же соединения тоже падает и зовёт + сброс: соединение, которое уже открыл следующий вызов, он не трогает. + """ + if failed is not None and failed is not self._channel: + return + connection = self._connection + self._connection = None + self._channel = None + if connection is not None: + self._close_in_background(connection) + + def _close_in_background( + self, + connection: AbstractRobustConnection, + ) -> None: + task = asyncio.create_task(_close_quietly(connection)) + self._close_tasks.add(task) + task.add_done_callback(self._close_tasks.discard) + + async def aclose(self) -> None: + """Закрыть соединение при остановке процесса.""" + connection = self._connection + self._connection = None + self._channel = None + if connection is not None: + await _close_quietly(connection) + if self._close_tasks: + await asyncio.gather(*self._close_tasks, return_exceptions=True) + + +@dataclass(slots=True) +class JobDelivery: + """Сообщение от брокера; подтверждает его `src/worker/main.py`.""" + + body: bytes + redelivered: bool + _message: AbstractIncomingMessage + + async def ack(self) -> None: + await self._settle(self._message.ack()) + + async def requeue(self) -> None: + await self._settle(self._message.nack(requeue=True)) + + async def drop(self) -> None: + """Сообщение не по схеме: без возврата в очередь.""" + await self._settle(self._message.reject(requeue=False)) + + @staticmethod + async def _settle(operation: Any) -> None: + """Канал уже закрыт — сообщение вернётся само, повтор безвреден.""" + try: + await operation + except Exception as e: + logger.info( + "Broker delivery was not settled", + error_type=type(e).__name__, + ) + + +class JobConsumer: + """Потребитель очереди на своём соединении: блокировка публикации + брокером не должна останавливать подтверждения. Брокер выдаёт не больше + `prefetch` неподтверждённых сообщений.""" + + def __init__( + self, + broker: BrokerSettings, + *, + namespace: str, + prefetch: int, + ) -> None: + self._broker = broker + self.queue = queue_name(namespace) + self._prefetch = prefetch + self._connection: AbstractRobustConnection | None = None + self._channel: AbstractChannel | None = None + self._queue: AbstractQueue | None = None + + async def connect(self) -> None: + """Соединение, канал, объявление очереди; ошибка уходит вызывающему. + Срок — `connect_timeout_seconds` на шаг открытия целиком.""" + async with asyncio.timeout(self._broker.connect_timeout_seconds * 2): + connection = await _open_connection( + self._broker, + client_name="messenger-worker", + ) + try: + self._channel = await connection.channel() + await self._channel.set_qos(prefetch_count=self._prefetch) + self._queue = await _declare_queue( + self._channel, + name=self.queue, + ) + except BaseException: + await _close_quietly(connection) + raise + self._connection = connection + + async def deliveries(self) -> AsyncIterator[JobDelivery]: + """Сообщения, пока соединение живо. Обрыв завершает итератор: цикл + worker сам открывает новое.""" + connection = self._connection + if connection is None or self._channel is None or self._queue is None: + raise RuntimeError("JobConsumer is not connected") + queue: asyncio.Queue[AbstractIncomingMessage | None] = asyncio.Queue() + + async def on_message(message: AbstractIncomingMessage) -> None: + await queue.put(message) + + def on_close(*_: object) -> None: + queue.put_nowait(None) + + connection.close_callbacks.add(on_close) + self._channel.close_callbacks.add(on_close) + await self._queue.consume(on_message) + while True: + message = await queue.get() + if message is None: + return + yield JobDelivery( + body=message.body, + redelivered=bool(message.redelivered), + _message=message, + ) + + async def aclose(self) -> None: + connection = self._connection + self._connection = None + if connection is not None: + await _close_quietly(connection) + + +async def _close_quietly(connection: AbstractRobustConnection) -> None: + try: + async with asyncio.timeout(_BACKGROUND_CLOSE_TIMEOUT_SECONDS): + await connection.close() + except Exception as e: + logger.debug( + "Broker connection was not closed cleanly", + error_type=type(e).__name__, + ) + + +def create_job_publisher( + broker: BrokerSettings, + *, + namespace: str, +) -> JobPublisher: + return JobPublisher(broker, namespace=namespace) diff --git a/src/infra/broker/instance.py b/src/infra/broker/instance.py new file mode 100644 index 00000000..aab4b25d --- /dev/null +++ b/src/infra/broker/instance.py @@ -0,0 +1,16 @@ +"""Издатель заданий процесса API. + +Создаётся при импорте по `settings.broker`, соединение открывает первая +публикация: без брокера процесс стартует. Импортируют модуль только +`src/main.py` (закрытие в lifespan) и `src/api/dependencies.py`. Очередь — по +имени базы из `settings.database`: `make test_isolated` с базой `test_` не +смешивается с рабочей. +""" + +from src.config import settings +from src.infra.broker.client import create_job_publisher + +job_publisher = create_job_publisher( + settings.broker, + namespace=settings.database.name, +) diff --git a/src/infra/db/models/__init__.py b/src/infra/db/models/__init__.py index 744aa030..bea14a6e 100644 --- a/src/infra/db/models/__init__.py +++ b/src/infra/db/models/__init__.py @@ -1,7 +1,12 @@ """Модели БД. Новая модель импортируется здесь, иначе autogenerate её не видит.""" -from src.infra.db.models.attachment import Attachment, MessageAttachment +from src.infra.db.models.attachment import ( + Attachment, + AttachmentJob, + AttachmentVariant, + MessageAttachment, +) from src.infra.db.models.base import Base from src.infra.db.models.chat import Chat, ChatMember from src.infra.db.models.idempotency import IdempotencyKey @@ -11,6 +16,8 @@ from src.infra.db.models.user import User __all__ = [ "Attachment", + "AttachmentJob", + "AttachmentVariant", "Base", "Chat", "ChatMember", diff --git a/src/infra/db/models/attachment.py b/src/infra/db/models/attachment.py index a894f1d1..d03d20d7 100644 --- a/src/infra/db/models/attachment.py +++ b/src/infra/db/models/attachment.py @@ -70,9 +70,14 @@ class Attachment(Base): name="object_key_length", ), CheckConstraint( - "status IN ('pending', 'ready')", + "status IN ('pending', 'queued', 'processing', 'ready', 'failed')", name="status", ), + # код ошибки — только у failed, и у failed он обязателен + CheckConstraint( + "(status = 'failed') = (error_code IS NOT NULL)", + name="error_code_failed", + ), CheckConstraint( "updated_at >= created_at", name="updated_after_created", @@ -103,6 +108,98 @@ class Attachment(Base): # помечено. Индекса нет: сверка просматривает все строки ready, API # читает по id lost_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True)) + # ключ объекта в staging (design change async-attachments, решение 1); + # NULL — строка прежней версии, объект которой сразу по `object_key` + staging_key: Mapped[str | None] = mapped_column(Text) + # код failed в API; NULL во всех остальных состояниях + error_code: Mapped[str | None] = mapped_column(Text) + + +class AttachmentJob(Base): + """Логическая работа над вложением: `job_id` контракта, счёт попыток и + будущий outbox — `state = 'queued' AND published_at IS NULL` (design + change `async-attachments`, решение 1). Одна на вложение и версию; при + повторах и повторной доставке `id` не меняется.""" + + __tablename__ = "attachment_jobs" + __table_args__ = ( + UniqueConstraint("attachment_id", "pipeline_version"), + CheckConstraint("pipeline_version >= 1", name="pipeline_version"), + CheckConstraint( + "state IN ('queued', 'processing', 'succeeded', 'failed')", + name="state", + ), + CheckConstraint("attempt >= 0", name="attempt"), + ) + + id: Mapped[UUID] = mapped_column(primary_key=True) + # без каскада: вложение с заданием удалить нельзя + attachment_id: Mapped[UUID] = mapped_column(ForeignKey("attachments.id")) + pipeline_version: Mapped[int] = mapped_column(Integer) + state: Mapped[str] = mapped_column(Text) + # начатые попытки; источник истины счёта, а не заголовки брокера + attempt: Mapped[int] = mapped_column( + Integer, + server_default=text("0"), + ) + # причина последней ошибки для оператора, без секретов + last_error_code: Mapped[str | None] = mapped_column(Text) + next_attempt_at: Mapped[datetime | None] = mapped_column( + DateTime(timezone=True), + ) + lease_expires_at: Mapped[datetime | None] = mapped_column( + DateTime(timezone=True), + ) + # когда брокер подтвердил последнее сообщение; NULL — намерение не передано + published_at: Mapped[datetime | None] = mapped_column( + DateTime(timezone=True), + ) + updated_at: Mapped[datetime] = mapped_column(DateTime(timezone=True)) + finished_at: Mapped[datetime | None] = mapped_column( + DateTime(timezone=True), + ) + + +class AttachmentVariant(Base): + """Вариант готового вложения; первичный ключ — ключ эффекта контракта + `(attachment_id, pipeline_version, variant)`: повтор второй строки не + создаёт. Оригинал — не строка этой таблицы.""" + + __tablename__ = "attachment_variants" + __table_args__ = ( + CheckConstraint( + "variant IN ('thumbnail', 'crop', 'optimized')", + name="variant", + ), + CheckConstraint( + f"octet_length(object_key) BETWEEN 1 AND {OBJECT_KEY_MAX_BYTES}", + name="object_key_length", + ), + CheckConstraint( + "content_type IN ('image/jpeg', 'image/png', 'image/webp')", + name="content_type", + ), + CheckConstraint("size_bytes > 0", name="size_bytes"), + CheckConstraint("width > 0", name="width"), + CheckConstraint("height > 0", name="height"), + CheckConstraint( + f"octet_length(sha256) = {ATTACHMENT_SHA256_BYTES}", + name="sha256_length", + ), + ) + + attachment_id: Mapped[UUID] = mapped_column( + ForeignKey("attachments.id"), + primary_key=True, + ) + pipeline_version: Mapped[int] = mapped_column(Integer, primary_key=True) + variant: Mapped[str] = mapped_column(Text, primary_key=True) + object_key: Mapped[str] = mapped_column(Text, unique=True) + content_type: Mapped[str] = mapped_column(Text) + size_bytes: Mapped[int] = mapped_column(Integer) + width: Mapped[int] = mapped_column(Integer) + height: Mapped[int] = mapped_column(Integer) + sha256: Mapped[bytes] = mapped_column(LargeBinary) class MessageAttachment(Base): diff --git a/src/infra/logger.py b/src/infra/logger.py index 60566bd4..3354ad54 100644 --- a/src/infra/logger.py +++ b/src/infra/logger.py @@ -192,6 +192,10 @@ def configure_logger() -> None: "botocore": {"level": "WARNING"}, "aiobotocore": {"level": "WARNING"}, "aiohttp": {"level": "WARNING"}, + # клиент брокера: на DEBUG aio_pika и aiormq пишут кадры + # протокола с телами сообщений и строку подключения + "aio_pika": {"level": "WARNING"}, + "aiormq": {"level": "WARNING"}, }, }, ) diff --git a/src/main.py b/src/main.py index 6695cbca..38135448 100644 --- a/src/main.py +++ b/src/main.py @@ -9,6 +9,7 @@ from src.api.middlewares import RequestContextMiddleware from src.api.routers import health_router, v1_router from src.config import settings from src.infra import early_stop +from src.infra.broker.instance import job_publisher from src.infra.cache.instance import cache from src.infra.db.session import engine from src.infra.logger import AbstractLogger, get_logger @@ -29,7 +30,7 @@ async def lifespan(_: FastAPI) -> AsyncIterator[None]: s3 = settings.s3 # engine, кэш и S3 подключаются лениво: без Postgres сервис стартует, а # /health/ready отвечает 503; без Valkey запросы идут в Postgres; без - # S3 — 503 только на путях вложений + # S3 — 503 только на путях вложений, без брокера — на загрузке if not database.password.get_secret_value(): logger.warning("Database password is empty") if not settings.cache.password.get_secret_value(): @@ -61,6 +62,12 @@ async def lifespan(_: FastAPI) -> AsyncIterator[None]: uploads_max_waiting=settings.uploads.max_waiting, uploads_wait_timeout_seconds=settings.uploads.wait_timeout_seconds, uploads_body_timeout_seconds=settings.uploads.body_timeout_seconds, + broker_host=settings.broker.host, + broker_port=settings.broker.port, + broker_queue=job_publisher.queue, + broker_publish_timeout_seconds=( + settings.broker.publish_timeout_seconds + ), ) try: yield @@ -68,12 +75,13 @@ async def lifespan(_: FastAPI) -> AsyncIterator[None]: await engine.dispose() await cache.aclose() await object_storage.aclose() + await job_publisher.aclose() logger.info("Stopped API") def create_app() -> FastAPI: # версия — info.version контракта (contracts/openapi.json) - app = FastAPI(title="MTUSI Messenger", version="1.3.0", lifespan=lifespan) + app = FastAPI(title="MTUSI Messenger", version="1.5.0", lifespan=lifespan) app.add_middleware(RequestContextMiddleware) errors.register(app) app.include_router(health_router) diff --git a/src/schemas/dataclasses/__init__.py b/src/schemas/dataclasses/__init__.py index ba37b23c..4e0bc60f 100644 --- a/src/schemas/dataclasses/__init__.py +++ b/src/schemas/dataclasses/__init__.py @@ -2,6 +2,8 @@ from .attachment import ( AttachmentContentDTO, AttachmentFullDTO, AttachmentInListDTO, + AttachmentJobDTO, + AttachmentVariantDTO, CleanupPassDTO, ReconcileFindingDTO, ReconcilePassDTO, @@ -16,6 +18,8 @@ __all__ = [ "AttachmentContentDTO", "AttachmentFullDTO", "AttachmentInListDTO", + "AttachmentJobDTO", + "AttachmentVariantDTO", "ChatFullDTO", "ChatPageDTO", "CleanupPassDTO", diff --git a/src/schemas/dataclasses/attachment.py b/src/schemas/dataclasses/attachment.py index 8dd8b470..1f4f2d2f 100644 --- a/src/schemas/dataclasses/attachment.py +++ b/src/schemas/dataclasses/attachment.py @@ -5,7 +5,10 @@ from types import MappingProxyType from uuid import UUID from src.schemas.enums import ( + AttachmentErrorCode, + AttachmentJobState, AttachmentStatus, + AttachmentVariantName, ImageType, ReconcileFinding, ReconcileStrategy, @@ -17,13 +20,30 @@ def _empty_mapping() -> Mapping[str, int]: @dataclass(frozen=True, slots=True) -class AttachmentFullDTO: - """Строка вложения: метаданные и ключ объекта в S3. +class AttachmentVariantDTO: + """Строка варианта; ключ объекта и версия в API не уходят, `sha256` — + байты, как у вложения. `name` — колонка `variant`, имя схемы контракта.""" - `object_key` и статус `pending` в API не попадают; `sha256` — байты - SHA-256 оригинала, hex собирает модель ответа. `lost_at` — когда сверка - подтвердила потерю оригинала (design change `track2-reconciler`, - решение 5); в ответы API не попадает. + name: AttachmentVariantName + pipeline_version: int + object_key: str + content_type: str + size_bytes: int + width: int + height: int + sha256: bytes + created_at: datetime + + +@dataclass(frozen=True, slots=True) +class AttachmentFullDTO: + """Строка вложения: метаданные и ключи объектов в S3. + + `object_key`, `staging_key` и статус `pending` в API не попадают; + `sha256` — байты SHA-256 оригинала, hex собирает модель ответа. `lost_at` + — когда сверка подтвердила потерю оригинала (design change + `track2-reconciler`, решение 5); в ответы API не попадает. `variants` — + не колонка: сервис подставляет их только готовому вложению. """ id: UUID @@ -38,17 +58,41 @@ class AttachmentFullDTO: created_at: datetime updated_at: datetime lost_at: datetime | None = None + staging_key: str | None = None + error_code: AttachmentErrorCode | None = None + variants: tuple[AttachmentVariantDTO, ...] = () @dataclass(frozen=True, slots=True) class AttachmentInListDTO: - """Незавершённая загрузка для уборщика: `id`, ключ объекта и время + """Незавершённая загрузка для уборщика: `id`, ключи объектов и время записи строки — ровно то, что нужно проходу (design change - `upload-consistency`, решение 3).""" + `upload-consistency`, решение 3). `staging_key` NULL — строка прежней + версии, её объект по `object_key`.""" id: UUID object_key: str created_at: datetime + staging_key: str | None = None + + +@dataclass(frozen=True, slots=True) +class AttachmentJobDTO: + """Строка задания обработки (design change `async-attachments`, + решение 1).""" + + id: UUID + attachment_id: UUID + pipeline_version: int + state: AttachmentJobState + attempt: int + created_at: datetime + updated_at: datetime + last_error_code: str | None = None + next_attempt_at: datetime | None = None + lease_expires_at: datetime | None = None + published_at: datetime | None = None + finished_at: datetime | None = None @dataclass(frozen=True, slots=True) @@ -135,7 +179,7 @@ class ReconcilePassDTO: @dataclass(frozen=True, slots=True) class AttachmentContentDTO: - """Оригинал вложения на отдачу потоком. + """Оригинал или вариант вложения на отдачу потоком. `chunks` — блоки объекта из S3; `close` освобождает соединение с S3, вызов повторно безопасен. Генератор вызывает его сам, когда поток @@ -143,7 +187,7 @@ class AttachmentContentDTO: генератор так и не начался. """ - content_type: ImageType + content_type: str size_bytes: int chunks: AsyncIterator[bytes] close: Callable[[], Awaitable[None]] diff --git a/src/schemas/enums/__init__.py b/src/schemas/enums/__init__.py index 57479844..41371136 100644 --- a/src/schemas/enums/__init__.py +++ b/src/schemas/enums/__init__.py @@ -1,6 +1,11 @@ from .attachment import ( + AttachmentErrorCode, + AttachmentJobReason, + AttachmentJobState, AttachmentStatus, + AttachmentVariantName, ImageType, + JobOutcome, ReconcileAction, ReconcileFinding, ReconcileStrategy, @@ -8,8 +13,13 @@ from .attachment import ( from .settings import RunModeEnum __all__ = [ + "AttachmentErrorCode", + "AttachmentJobReason", + "AttachmentJobState", "AttachmentStatus", + "AttachmentVariantName", "ImageType", + "JobOutcome", "ReconcileAction", "ReconcileFinding", "ReconcileStrategy", diff --git a/src/schemas/enums/attachment.py b/src/schemas/enums/attachment.py index 47796d31..ac99e206 100644 --- a/src/schemas/enums/attachment.py +++ b/src/schemas/enums/attachment.py @@ -4,13 +4,64 @@ from enum import StrEnum class AttachmentStatus(StrEnum): """Состояние вложения в БД. - `pending` — строка-намерение до записи объекта в S3, наружу не видна; - `ready` — оригинал и метаданные сохранены. Значения хранятся в БД - (`CHECK`), новое значение — миграция. + `pending` — строка-намерение до записи объекта в staging, наружу не + видна; `queued`, `processing`, `ready`, `failed` — состояния контракта + после 202. Значения хранятся в БД (`CHECK`), новое значение — миграция. """ PENDING = "pending" + QUEUED = "queued" + PROCESSING = "processing" READY = "ready" + FAILED = "failed" + + +class AttachmentJobState(StrEnum): + """Состояние логической работы над вложением, хранится в БД.""" + + QUEUED = "queued" + PROCESSING = "processing" + SUCCEEDED = "succeeded" + FAILED = "failed" + + +class AttachmentVariantName(StrEnum): + """Имя варианта контракта, хранится в БД. На уровне 3 пишется только + `thumbnail`; `crop` и `optimized` — следующее изменение.""" + + THUMBNAIL = "thumbnail" + CROP = "crop" + OPTIMIZED = "optimized" + + +class AttachmentErrorCode(StrEnum): + """`error_code` вложения `failed` в API.""" + + INVALID_IMAGE = "invalid_image" + PROCESSING_FAILED = "processing_failed" + RETRY_EXHAUSTED = "retry_exhausted" + + +class AttachmentJobReason(StrEnum): + """Причина последней ошибки задания для оператора + (`attachment_jobs.last_error_code`), без секретов.""" + + SOURCE_MISSING = "source_missing" + SOURCE_CORRUPTED = "source_corrupted" + UNDECODABLE = "undecodable" + STORAGE_UNAVAILABLE = "storage_unavailable" + TIMEOUT = "timeout" + UNEXPECTED = "unexpected" + + +class JobOutcome(StrEnum): + """Что worker делает с сообщением после обработки; в БД не хранится. + `ack` — устойчивый эффект есть, `requeue` — вернуть в очередь, `drop` — + сообщение не по схеме, возврат не поможет.""" + + ACK = "ack" + REQUEUE = "requeue" + DROP = "drop" class ImageType(StrEnum): diff --git a/src/schemas/jobs/__init__.py b/src/schemas/jobs/__init__.py new file mode 100644 index 00000000..bf30cb93 --- /dev/null +++ b/src/schemas/jobs/__init__.py @@ -0,0 +1,3 @@ +from .attachment import AttachmentJobMessage, build_job_body + +__all__ = ["AttachmentJobMessage", "build_job_body"] diff --git a/src/schemas/jobs/attachment.py b/src/schemas/jobs/attachment.py new file mode 100644 index 00000000..31a85a43 --- /dev/null +++ b/src/schemas/jobs/attachment.py @@ -0,0 +1,63 @@ +"""Сообщение брокера о задании обработки: `contracts/jobs.schema.json`. + +Pydantic, а не DTO: сообщение приходит извне, из очереди, и разбирается по схеме +контракта (design change `async-attachments`, решение 7). Байтов, имени файла, +ключей объектов и адресов в нём нет: их worker берёт из PostgreSQL. +""" + +import json +from datetime import datetime +from typing import Annotated, Literal +from uuid import UUID + +from pydantic import BaseModel, ConfigDict, Field + +from src.schemas.dataclasses import AttachmentJobDTO +from src.utils.constants import ( + ATTACHMENT_JOB_SCHEMA_VERSION, + ATTACHMENT_JOB_TYPE, +) +from src.utils.utc import to_rfc3339 + +_TRACEPARENT_PATTERN = r"^00-[0-9a-f]{32}-[0-9a-f]{16}-[0-9a-f]{2}$" +_TRACESTATE_MAX_LENGTH = 512 + + +class AttachmentJobMessage(BaseModel): + """Тело сообщения; лишнее поле и чужая версия — ошибка разбора. + + `traceparent` и `tracestate` на этом уровне приложение не пишет и не + читает, но принимает: их допускает контракт. + """ + + model_config = ConfigDict(extra="forbid") + + schema_version: Literal[1] + job_id: UUID + type: Literal["attachment.process.v1"] + attachment_id: UUID + pipeline_version: Annotated[int, Field(ge=1, strict=True)] + attempt: Annotated[int, Field(ge=1, strict=True)] + created_at: datetime + traceparent: Annotated[str, Field(pattern=_TRACEPARENT_PATTERN)] | None = ( + None + ) + tracestate: ( + Annotated[str, Field(max_length=_TRACESTATE_MAX_LENGTH)] | None + ) = None + + +def build_job_body(job: AttachmentJobDTO, *, attempt: int) -> bytes: + """Тело сообщения из строки задания: повторы несут тот же `job_id` и + `attempt` управляемой попытки.""" + return json.dumps( + { + "schema_version": ATTACHMENT_JOB_SCHEMA_VERSION, + "job_id": str(job.id), + "type": ATTACHMENT_JOB_TYPE, + "attachment_id": str(job.attachment_id), + "pipeline_version": job.pipeline_version, + "attempt": attempt, + "created_at": to_rfc3339(job.created_at), + }, + ).encode() diff --git a/src/utils/constants.py b/src/utils/constants.py index b2112f0a..281fffc0 100644 --- a/src/utils/constants.py +++ b/src/utils/constants.py @@ -79,6 +79,21 @@ OBJECT_KEY_MAX_BYTES = 1024 # ключ объекта: `<имя базы>/attachments//original` ATTACHMENT_KEY_PREFIX = "attachments" ATTACHMENT_ORIGINAL_SUFFIX = "original" +# обработка вложения (с лабы 5, design change `async-attachments`): +# объект до обработки — `<имя базы>/staging//original`, вариант — +# `<имя базы>/attachments//v<версия>-<вариант>` +ATTACHMENT_STAGING_PREFIX = "staging" +# версия обработки; курс использует одну (contracts/attachment-states.md) +ATTACHMENT_PIPELINE_VERSION = 1 +# поля type и schema_version сообщения contracts/jobs.schema.json +ATTACHMENT_JOB_TYPE = "attachment.process.v1" +ATTACHMENT_JOB_SCHEMA_VERSION = 1 +# очередь заданий — `<имя базы>.attachment.process.v1`: прогон на временной +# базе не смешивается с рабочим, как объекты S3 и ключи кэша +ATTACHMENT_QUEUE_SUFFIX = "attachment.process.v1" +# thumbnail контракта: вписан в квадрат, JPEG +THUMBNAIL_MAX_SIDE = 256 +THUMBNAIL_JPEG_QUALITY = 85 # сверка bucket и БД: сколько расхождений за проход пишется отдельными # записями журнала; остальные — только числом в итоге (design change # `track2-reconciler`, решение 8) diff --git a/src/utils/thumbnail.py b/src/utils/thumbnail.py new file mode 100644 index 00000000..7c2c0cd8 --- /dev/null +++ b/src/utils/thumbnail.py @@ -0,0 +1,153 @@ +"""Thumbnail контракта: JPEG, вписан в 256 × 256, без увеличения. + +Чистая функция (design change `async-attachments`, решение 8). Импортирует +Pillow, поэтому импортирует модуль только сервис обработки: реплики API +декодер в память не загружают. Вызывается в потоке, результат при том же +входе и версии Pillow детерминирован: повтор пишет те же байты. +""" + +import hashlib +import io +from dataclasses import dataclass + +from PIL import Image, UnidentifiedImageError + +from src.utils.constants import ( + ATTACHMENT_MAX_PIXELS, + THUMBNAIL_JPEG_QUALITY, + THUMBNAIL_MAX_SIDE, +) + +# тег EXIF Orientation +_EXIF_ORIENTATION = 0x0112 +# транспонирование на малом изображении: на полном размере поворот удвоил бы +# пик памяти (два буфера пикселей разом) +_TRANSPOSE = { + 2: Image.Transpose.FLIP_LEFT_RIGHT, + 3: Image.Transpose.ROTATE_180, + 4: Image.Transpose.FLIP_TOP_BOTTOM, + 5: Image.Transpose.TRANSPOSE, + 6: Image.Transpose.ROTATE_270, + 7: Image.Transpose.TRANSVERSE, + 8: Image.Transpose.ROTATE_90, +} +# при этих значениях показанное изображение повёрнуто на 90° +_SWAPS_SIDES = frozenset({5, 6, 7, 8}) +_HIGH_DEPTH_MODES = frozenset({"I;16", "I;16B", "I;16L", "I"}) +_ALPHA_MODES = frozenset({"RGBA", "LA", "PA"}) +_WHITE = (255, 255, 255, 255) +_FORMATS = ("PNG", "JPEG") + + +class InvalidImage(Exception): + """Изображение не декодируется: постоянная ошибка обработки.""" + + +@dataclass(frozen=True, slots=True) +class RenderedVariant: + """Готовый вариант: байты, настоящие размеры и SHA-256.""" + + data: bytes + width: int + height: int + sha256: bytes + + +def thumbnail_size(width: int, height: int) -> tuple[int, int]: + """Размер показанного изображения: большая сторона — 256, меньшая + округляется вниз, не меньше 1; вписанное не увеличивается. + + Не `Image.thumbnail`: он округляет к ближайшей пропорции (1000 × 601 → + 256 × 154), а контракт — вниз (153). + """ + if width <= THUMBNAIL_MAX_SIDE and height <= THUMBNAIL_MAX_SIDE: + return width, height + if width >= height: + return ( + THUMBNAIL_MAX_SIDE, + max(1, height * THUMBNAIL_MAX_SIDE // width), + ) + return ( + max(1, width * THUMBNAIL_MAX_SIDE // height), + THUMBNAIL_MAX_SIDE, + ) + + +def _prepared(image: Image.Image) -> Image.Image: + """Режим, в котором масштабирование считает среднее, а не ближайшего + соседа: 16 бит → 8, с альфой → RGBA, 1 бит → L, палитра и CMYK → RGB.""" + if image.mode in _HIGH_DEPTH_MODES: + scaled = image.convert("I").point(lambda value: value / 256) + return scaled.convert("L") + if image.mode == "RGBA": + # convert в тот же режим — копия всех пикселей: пик памяти 40 Мпкс + # вырос бы с ~320 до ~480 МиБ + return image + if image.mode in _ALPHA_MODES or "transparency" in image.info: + return image.convert("RGBA") + if image.mode == "1": + return image.convert("L") + if image.mode in ("P", "CMYK"): + return image.convert("RGB") + return image + + +def _flattened(image: Image.Image) -> Image.Image: + """Альфа на белый, результат — режим, который принимает JPEG.""" + if image.mode == "RGBA": + background = Image.new("RGBA", image.size, _WHITE) + return Image.alpha_composite(background, image).convert("RGB") + return image + + +def render_thumbnail(data: bytes) -> RenderedVariant: + """Thumbnail из байтов PNG или JPEG; не декодируется — `InvalidImage`.""" + try: + return _render(data) + except ( + UnidentifiedImageError, + OSError, + ValueError, + SyntaxError, + Image.DecompressionBombError, + ) as e: + raise InvalidImage from e + + +def _render(data: bytes) -> RenderedVariant: + # предел пикселей контракта проверяет этот код: запас Pillow не нужен + with Image.open(io.BytesIO(data), formats=_FORMATS) as image: + if image.width * image.height > ATTACHMENT_MAX_PIXELS: + raise InvalidImage + orientation = image.getexif().get(_EXIF_ORIENTATION, 1) + swaps = orientation in _SWAPS_SIDES + shown = ( + (image.height, image.width) + if swaps + else (image.width, image.height) + ) + target = thumbnail_size(*shown) + stored = (target[1], target[0]) if swaps else target + if image.format == "JPEG": + # масштаб DCT: пик памяти на порядок меньше. Для CMYK режим не + # меняет, только размер декодирования + image.draft("RGB", stored) + prepared = _prepared(image) + small = prepared.resize( + stored, + Image.Resampling.LANCZOS, + reducing_gap=2.0, + ) + # is not None: значение FLIP_LEFT_RIGHT — 0 + if (transpose := _TRANSPOSE.get(orientation)) is not None: + small = small.transpose(transpose) + flat = _flattened(small).convert("RGB") + output = io.BytesIO() + flat.save(output, format="JPEG", quality=THUMBNAIL_JPEG_QUALITY) + result = output.getvalue() + return RenderedVariant( + data=result, + width=flat.width, + height=flat.height, + sha256=hashlib.sha256(result).digest(), + ) diff --git a/src/worker/__init__.py b/src/worker/__init__.py new file mode 100644 index 00000000..e69de29b diff --git a/src/worker/__main__.py b/src/worker/__main__.py new file mode 100644 index 00000000..10777c77 --- /dev/null +++ b/src/worker/__main__.py @@ -0,0 +1,40 @@ +if __name__ == "__main__": + # обработчик SIGTERM и SIGINT — до импорта приложения, как у API и + # уборщика (src/infra/early_stop.py): запись «Stopped worker before + # startup» и код 0 + from src.infra import early_stop + + early_stop.install("worker") + import sys + + from pydantic import ValidationError + + try: + from src.worker.main import main + except ValidationError as e: + # неверные настройки: логгер их тоже читает и не настроен. Одна + # запись без значений полей (в них могут быть секреты) и код 2 + early_stop.write_record( + "Invalid worker settings", + level="error", + module="worker", + errors=[ + { + "loc": ".".join(str(part) for part in error["loc"]), + "msg": error["msg"], + } + for error in e.errors(include_input=False) + ], + ) + sys.exit(2) + + code = main() + # клиенты закрыты, «Stopped worker» записан. Поток декодирования отменить + # нельзя, а финализация интерпретатора его ждала бы: именно os._exit + # укладывается в срок остановки контейнера (design change + # async-attachments, решение 6) + import os + + sys.stdout.flush() + sys.stderr.flush() + os._exit(code) diff --git a/src/worker/main.py b/src/worker/main.py new file mode 100644 index 00000000..b5310f79 --- /dev/null +++ b/src/worker/main.py @@ -0,0 +1,249 @@ +"""Worker обработки вложений: `python -m src.worker`. + +Отдельный процесс стенда, а не задача реплик API (design change +`async-attachments`, решение 6). Свои engine, клиент S3 с ключами worker и +клиенты брокера; глобалы процесса API не импортируются, поэтому реплики не +загружают декодер, а worker — приложение HTTP. + +Цикл: соединение, объявление очереди, потребление до сигнала или обрыва. При +обрыве worker не падает: дожидается своих задач прежнего соединения (иначе +своя же повторная доставка), пауза `[worker] reconnect_seconds` и новое +соединение. Конкуренция ограничена `prefetch_count = [worker] concurrency`. + +SIGTERM: новые сообщения не принимаются, начатые задачи ждут не дольше +`graceful_shutdown_seconds`, остальные отменяются, соединения закрываются, +неподтверждённое брокер вернёт в очередь, «Stopped worker», код 0. Коды выхода: +0 — остановлен сигналом, 2 — неверная конфигурация (`src/worker/__main__.py`). +""" + +import asyncio +import signal +from contextlib import AbstractAsyncContextManager, suppress + +import anyio +from sqlalchemy.ext.asyncio import AsyncSession + +from src.config import settings +from src.core.services.attachment_processing import ( + AttachmentProcessingService, +) +from src.infra import early_stop +from src.infra.broker import JobConsumer, JobDelivery, JobPublisher +from src.infra.db import create_engine, create_session_factory +from src.infra.db.scope import session_scope +from src.infra.logger import AbstractLogger, get_logger +from src.infra.s3 import create_object_storage +from src.schemas.enums import JobOutcome + +logger: AbstractLogger = get_logger().bind(module="worker") + +EXIT_OK = 0 +# секунды на закрытие клиента при остановке: сумма с ожиданием задач меньше +# срока остановки контейнера (10 с) +_CLOSE_TIMEOUT_SECONDS = 0.5 + + +def main() -> int: + return asyncio.run(run()) + + +async def run() -> int: + stop = asyncio.Event() + loop = asyncio.get_running_loop() + for signum in (signal.SIGTERM, signal.SIGINT): + loop.add_signal_handler(signum, stop.set) + # дальше сигналы обрабатывает цикл + early_stop.disarm() + + worker = settings.worker + namespace = settings.database.name + engine = create_engine(settings.database) + session_factory = create_session_factory(engine) + storage = create_object_storage(settings.s3, namespace=namespace) + publisher = JobPublisher(settings.broker, namespace=namespace) + + def db_scope() -> AbstractAsyncContextManager[AsyncSession]: + return session_scope( + session_factory, + timeout_seconds=settings.database.request_timeout_seconds, + ) + + service = AttachmentProcessingService( + db_scope=db_scope, + storage=storage, + publisher=publisher, + limiter=anyio.CapacityLimiter(worker.concurrency), + stop=stop, + ) + try: + if not ( + settings.s3.access_key_id.get_secret_value() + and settings.s3.secret_access_key.get_secret_value() + ): + logger.warning("Object storage credentials are empty") + # модели botocore — при старте, сети нет + await storage.start() + logger.info( + "Started worker", + concurrency=worker.concurrency, + max_attempts=worker.max_attempts, + job_timeout_seconds=worker.job_timeout_seconds, + retry_delay_seconds=worker.retry_delay_seconds, + graceful_shutdown_seconds=worker.graceful_shutdown_seconds, + reconnect_seconds=worker.reconnect_seconds, + broker_host=settings.broker.host, + broker_port=settings.broker.port, + broker_queue=publisher.queue, + s3_host=settings.s3.host, + s3_port=settings.s3.port, + s3_bucket=settings.s3.bucket, + database_host=settings.database.host, + database_port=settings.database.port, + database_name=namespace, + database_pool_size=settings.database.pool_size, + ) + await _serve(service, namespace=namespace, stop=stop) + finally: + for closing in ( + engine.dispose(), + storage.aclose(), + publisher.aclose(), + ): + with suppress(Exception): + async with asyncio.timeout(_CLOSE_TIMEOUT_SECONDS): + await closing + logger.info("Stopped worker", exit_code=EXIT_OK) + return EXIT_OK + + +async def _serve( + service: AttachmentProcessingService, + *, + namespace: str, + stop: asyncio.Event, +) -> None: + """Соединения с брокером до сигнала.""" + worker = settings.worker + tasks: set[asyncio.Task[None]] = set() + while not stop.is_set(): + consumer = JobConsumer( + settings.broker, + namespace=namespace, + prefetch=worker.concurrency, + ) + try: + await consumer.connect() + except Exception as e: + logger.warning( + "Broker is unavailable", + broker_host=settings.broker.host, + broker_port=settings.broker.port, + error_type=type(e).__name__, + ) + await _wait_stop(stop, timeout=worker.reconnect_seconds) + continue + logger.info("Connected to broker", broker_queue=consumer.queue) + pump = asyncio.create_task(_pump(consumer, service, tasks)) + stopping = asyncio.create_task(stop.wait()) + await asyncio.wait( + {pump, stopping}, + return_when=asyncio.FIRST_COMPLETED, + ) + if stop.is_set(): + pump.cancel() + with suppress(asyncio.CancelledError, Exception): + await pump + await _finish_tasks(tasks) + with suppress(Exception): + async with asyncio.timeout(_CLOSE_TIMEOUT_SECONDS): + await consumer.aclose() + return + stopping.cancel() + try: + await pump + except Exception as e: + logger.warning( + "Broker consumer stopped", + error_type=type(e).__name__, + ) + logger.warning("Broker connection lost") + # свои задачи прежнего соединения: иначе своя же повторная доставка + # взяла бы задание второй раз + await _wait_tasks_or_stop(tasks, stop) + await consumer.aclose() + await _wait_stop(stop, timeout=worker.reconnect_seconds) + await _finish_tasks(tasks) + + +async def _pump( + consumer: JobConsumer, + service: AttachmentProcessingService, + tasks: set[asyncio.Task[None]], +) -> None: + """Каждая доставка — своя задача со своим контекстом журнала.""" + async for delivery in consumer.deliveries(): + task = asyncio.create_task(_handle(service, delivery)) + tasks.add(task) + task.add_done_callback(tasks.discard) + + +async def _handle( + service: AttachmentProcessingService, + delivery: JobDelivery, +) -> None: + """Подтверждение — только после итога сервиса. Отмена при остановке + сообщение не подтверждает: брокер вернёт его после закрытия соединения.""" + try: + outcome = await service.handle( + body=delivery.body, + redelivered=delivery.redelivered, + ) + except Exception as e: + logger.error("Job handling failed", exc_info=e) + with suppress(TimeoutError): + await asyncio.wait_for( + service.stop.wait(), + timeout=settings.worker.retry_delay_seconds, + ) + outcome = JobOutcome.REQUEUE + if outcome == JobOutcome.ACK: + await delivery.ack() + elif outcome == JobOutcome.DROP: + await delivery.drop() + else: + await delivery.requeue() + + +async def _finish_tasks(tasks: set[asyncio.Task[None]]) -> None: + """Начатые задачи — не дольше срока, остальные отменяются. Поток + декодирования отменить нельзя: его не ждём, выход — `os._exit`.""" + if not tasks: + return + _, pending = await asyncio.wait( + set(tasks), + timeout=settings.worker.graceful_shutdown_seconds, + ) + for task in pending: + task.cancel() + if pending: + await asyncio.wait(pending, timeout=_CLOSE_TIMEOUT_SECONDS) + + +async def _wait_tasks_or_stop( + tasks: set[asyncio.Task[None]], + stop: asyncio.Event, +) -> None: + stopping = asyncio.create_task(stop.wait()) + try: + while tasks and not stop.is_set(): + await asyncio.wait( + {*tasks, stopping}, + return_when=asyncio.FIRST_COMPLETED, + ) + finally: + stopping.cancel() + + +async def _wait_stop(stop: asyncio.Event, *, timeout: float) -> None: + with suppress(TimeoutError): + await asyncio.wait_for(stop.wait(), timeout=timeout) diff --git a/student-tests/api_client.py b/student-tests/api_client.py index 15b49472..b1c879a5 100644 --- a/student-tests/api_client.py +++ b/student-tests/api_client.py @@ -13,9 +13,12 @@ from typing import Any import httpx -from contract import assert_ok +from contract import assert_accepted, assert_ok API = "/api/v1" +# срок ожидания готовности вложения — как у публичного smoke, и шаг опроса +READY_TIMEOUT_S = 60 +READY_POLL_S = 0.2 SESSIONS = f"{API}/auth/sessions" # защита от бесконечного обхода, если next_cursor никогда не станет null MAX_PAGES = 1000 @@ -291,7 +294,7 @@ class Api: content_type: str = "image/png", filename: str = "image.png", ) -> dict[str, Any]: - """Успешная загрузка: 201 и `Attachment` с размером и SHA-256.""" + """Принятая загрузка: 202 и снимок `queued` с размером и SHA-256.""" resp = self.post_attachment( actor, chat_id, @@ -299,7 +302,7 @@ class Api: content_type=content_type, filename=filename, ) - attachment = assert_ok(resp, 201, "Attachment") + attachment = assert_accepted(resp) assert attachment["size_bytes"] == len(data), "size_bytes differs" assert attachment["sha256"] == hashlib.sha256(data).hexdigest(), ( "sha256 differs" @@ -309,6 +312,57 @@ class Api: assert attachment["filename"] == filename, "filename changed" return attachment + def wait_attachment( + self, + actor: Actor, + attachment_id: str, + *, + status: str = "ready", + timeout: float = READY_TIMEOUT_S, + ) -> dict[str, Any]: + """Метаданные вложения, когда оно в статусе `status`: опрос раз в + 0,2 с. Истёк срок или вложение стало `failed`, а ждали другое — + падение с последним состоянием (спек `student-tests`, «Готовность + вложения в тестах»).""" + deadline = time.monotonic() + timeout + while True: + meta = assert_ok( + self.attachment_meta(actor, attachment_id), + 200, + "Attachment", + ) + if meta["status"] == status: + return meta + assert meta["status"] != "failed", ( + f"attachment {attachment_id} became failed " + f"({meta['error_code']}), waited for {status}" + ) + assert time.monotonic() < deadline, ( + f"attachment {attachment_id} did not become {status} in " + f"{timeout} s, last status {meta['status']}: is the worker " + "running?" + ) + time.sleep(READY_POLL_S) + + def upload_ready( + self, + actor: Actor, + chat_id: str, + data: bytes, + *, + content_type: str = "image/png", + filename: str = "image.png", + ) -> dict[str, Any]: + """Загрузка и ожидание `ready`: метаданные готового вложения.""" + accepted = self.upload( + actor, + chat_id, + data, + content_type=content_type, + filename=filename, + ) + return self.wait_attachment(actor, accepted["id"]) + def attachment_meta( self, actor: Actor | None, diff --git a/student-tests/contract.py b/student-tests/contract.py index c7df759d..86f52fa2 100644 --- a/student-tests/contract.py +++ b/student-tests/contract.py @@ -1,5 +1,6 @@ """Проверка ответов по `contracts/openapi.json` и форматам контракта.""" +import hashlib import json import re from collections.abc import Iterable, Mapping @@ -130,6 +131,16 @@ def assert_ok(resp: httpx.Response, status: int, schema: str) -> Any: return body +def assert_accepted(resp: httpx.Response) -> dict[str, Any]: + """Принятая загрузка: 202 и снимок на момент приёма по схеме контракта + (спек `student-tests`, «Готовность вложения в тестах»).""" + attachment = assert_ok(resp, 202, "Attachment") + assert attachment["status"] == "queued", describe(resp, "not queued") + assert attachment["variants"] == [], describe(resp, "has variants") + assert attachment["error_code"] is None, describe(resp, "has error_code") + return attachment + + def assert_error(resp: httpx.Response, status: int) -> dict[str, Any]: """Ошибка в формате контракта; `code` соответствует статусу.""" assert resp.status_code == status, describe(resp, f"expected {status}") @@ -226,6 +237,37 @@ def assert_content( ) +def assert_variant_content( + resp: httpx.Response, + variant: Mapping[str, Any], +) -> bytes: + """Байты варианта: те же заголовки, что у оригинала, размер и SHA-256 — + поля варианта в метаданных. Возвращает байты.""" + check_body(dict(variant), "Variant") + assert resp.status_code == 200, describe(resp, "expected 200") + assert resp.headers.get("X-Request-Id", "").strip(), describe( + resp, + "no X-Request-Id", + ) + assert_instance_id(resp) + assert resp.headers.get("Content-Type") == variant["content_type"], ( + describe(resp, f"Content-Type is not {variant['content_type']}") + ) + assert resp.headers.get("Content-Length") == str(variant["size_bytes"]), ( + describe(resp, f"Content-Length is not {variant['size_bytes']}") + ) + assert resp.headers.get("X-Content-Type-Options") == "nosniff", describe( + resp, + "no X-Content-Type-Options: nosniff", + ) + assert_no_storage_traces(resp) + assert len(resp.content) == variant["size_bytes"], "size_bytes differs" + assert hashlib.sha256(resp.content).hexdigest() == variant["sha256"], ( + "sha256 of variant differs" + ) + return resp.content + + def assert_instance_id(resp: httpx.Response) -> str: """Непустой `X-Instance-Id` допустимого формата; возвращает значение.""" instance_id = resp.headers.get("X-Instance-Id", "") diff --git a/student-tests/failures.compose.yml b/student-tests/failures.compose.yml index 5418146b..e8fe2a8a 100644 --- a/student-tests/failures.compose.yml +++ b/student-tests/failures.compose.yml @@ -37,6 +37,20 @@ services: stop_grace_period: 2s haproxy: ports: !reset [] + # свой брокер со своим volume, порт AMQP не публикуется + rabbitmq: + ports: !reset [] + # worker со сроками, сравнимыми со временем теста, и без перезапуска: его + # останавливают и убивают сами проверки (design change async-attachments, + # решение 15). Сумма пауз 3 × 5 с больше возврата S3 (~8 с): «Временная + # ошибка» успевает. Значения run_failures.py передаёт тестам (FAULT_WORKER_*) + worker: + restart: "no" + environment: + WORKER__MAX_ATTEMPTS: "4" + WORKER__RETRY_DELAY_SECONDS: "5" + WORKER__JOB_TIMEOUT_SECONDS: "10" + WORKER__GRACEFUL_SHUTDOWN_SECONDS: "2" # уборщик с grace и интервалом, сравнимыми со временем теста (design # change upload-consistency, решение 10). Grace 20 с больше границы живой # загрузки при сроках по умолчанию (2 × 6 + 5 = 17 с): занижать сроки ради diff --git a/student-tests/fault_hook.py b/student-tests/fault_hook.py index 7d7c57f1..d4d74b3d 100755 --- a/student-tests/fault_hook.py +++ b/student-tests/fault_hook.py @@ -39,18 +39,48 @@ s3). Каталог `` без файла не считается: после DELETE SeaweedFS убирает его лишь через ~2 мин - fail-attachments insert|ready|stall|commit|outlive|undeletable + staging-ids то же под `<база>/staging//` + variant-object-count сколько у вложения объектов вариантов + (`<база>/attachments//v-<имя>`) + job строка задания вложения: JSON с id, state, + attempt, last_error_code, next_attempt_at, + published_at; нет задания — пусто + fail-attachments insert|queued|stall|commit|outlive|undeletable триггеры на вложения с этим filename (сбой — SQLSTATE 08006, для API это отказ БД, 503): - insert — вставка строки падает; ready — - перевод в ready падает до COMMIT; stall — - перевод в ready ждёт pg_sleep(4); commit — - перевод в ready падает на COMMIT (исход для + insert — вставка строки падает; queued — + перевод в queued падает до COMMIT; stall — + перевод в queued ждёт pg_sleep(4); commit — + перевод в queued падает на COMMIT (исход для API неизвестен); outlive — строка вставляется на час старше (уборщик берёт её - сразу), а перевод в ready ждёт до 4,5 с, пока + сразу), а перевод в queued ждёт до 4,5 с, пока строка pending не исчезнет; undeletable — как outlive, и удаление строки падает + fail-attachments ready-fail|ready-stall + фиксация worker: перевод в ready падает + (08006) или ждёт pg_sleep(4) + stop|start|pause|unpause|kill|recreate rabbitmq + брокер стенда; recreate — up --force-recreate + на том же volume; после start, recreate и + unpause — ожидание ответа брокера + stop|start|kill worker worker стенда; start — docker start контейнера + worker-state JSON: running, restart_count, oom_killed, + exit_code + worker-log журнал контейнера worker (stdout), все + запуски подряд + queue-state JSON очереди: messages, messages_ready, + messages_unacknowledged, consumers, durable; + очереди нет — null + peek-job тело одного сообщения очереди, прочитанного + без подтверждения (возвращается в очередь); + JSON с полями body (JSON-строка), delivery_mode; + сообщения нет — пусто. Python в контейнере API + его настройками: пароль в hook не попадает + publish-job сообщение с телом из stdin в очередь, + persistent; тот же контейнер + delete-queue удалить очередь (rabbitmqctl в контейнере + брокера); отсутствие — не ошибка fail-attachments mark пометка потерянного оригинала (UPDATE lost_at) вложения с этим filename падает @@ -65,13 +95,15 @@ стенда мимо API: botocore в контейнере обычного API его ключами из окружения контейнера. Ключ — только под - `/attachments/`, символы + `/attachments/` или + `/staging/`, символы [A-Za-z0-9._/-] delete-object <ключ> удалить объект мимо шлюза S3: `weed shell fs.rm /buckets//<ключ>`; ключ — с той же проверкой - delete-row удалить строку вложения (неиспользуемого: - ссылку сообщения не даст удалить FK) + delete-row удалить строку вложения с его заданием и + вариантами (неиспользуемого: ссылку + сообщения не даст удалить FK) set-size <байт> изменить size_bytes строки age-row <секунд> сдвинуть created_at и updated_at строки назад на одно и то же время: CHECK и @@ -107,9 +139,10 @@ FAULT_DATABASE, их задаёт run_failures.py. Пароли и ключи н не печатает: valkey-cli берёт пароль из VALKEYCLI_AUTH контейнера, psql работает от POSTGRES_USER контейнера, weed shell — с ключом подписи из окружения контейнера s3, put-object — ключами API из окружения -контейнера API. Только stdlib. Действия вложений — design change -`upload-consistency`, решение 10; расхождения хранилищ и сверка — design -change `track2-reconciler`, решение 11. +контейнера API, peek-job и publish-job — настройками брокера там же. Только +stdlib. Действия вложений — design change `upload-consistency`, решение 10; +расхождения хранилищ и сверка — design change `track2-reconciler`, решение +11; брокер, worker и задания — design change `async-attachments`, решение 15. """ from __future__ import annotations @@ -129,7 +162,7 @@ COMPOSE_FILES = ( ROOT / "student-tests" / "failures.compose.yml", ) PROJECT_SUFFIX = "-failures" -SERVICES = ("postgres", "valkey", "s3") +SERVICES = ("postgres", "valkey", "s3", "rabbitmq") # та же проверка, что в healthcheck сервиса в docker-compose.yml. У # PostgreSQL стенда отказов healthcheck переопределён на базу postgres # (failures.compose.yml), а проба после start / unpause ходит в базу @@ -146,6 +179,7 @@ PROBES = { "grep -qF '\"DataNodes\":[{' && " "wget -q -O /dev/null http://127.0.0.1:8888/healthz && " 'wget -q -O /dev/null "http://127.0.0.1:$S3_PORT/healthz"', + "rabbitmq": "rabbitmq-diagnostics -q check_port_connectivity", } PROBE_TIMEOUT_S = 30 # начало ключа карточки — копия CACHE_KEY_PREFIX из src/utils/constants.py: @@ -259,15 +293,16 @@ ORDER BY created_at DESC, id DESC LIMIT 1; # (connection_failure) приложение считает отказом БД: 503, а не 500 # (design change upload-consistency, пробы). Три триггера, каждый # срабатывает только в своих режимах: -# - fault_fail_attachments (строка, BEFORE): insert, ready, stall; в outlive +# - fault_fail_attachments (строка, BEFORE): insert, queued, stall; в outlive # и undeletable вставка «на час старше» — created_at и updated_at вместе, -# строка остаётся непомеченной (mark_ready требует updated_at = -# created_at); в undeletable удаление строки падает; +# строка остаётся непомеченной (mark_queued требует updated_at = +# created_at); в undeletable удаление строки падает; ready-fail и +# ready-stall — перевод worker в ready; # - fault_fail_attachments_commit (отложенный триггер ограничения, AFTER -# UPDATE): commit — перевод в ready падает на COMMIT, исход для API +# UPDATE): commit — перевод в queued падает на COMMIT, исход для API # неизвестен; # - fault_wait_attachments (оператор, BEFORE UPDATE OF status): outlive и -# undeletable — перевод в ready ждёт, пока строка pending с этим +# undeletable — перевод в queued ждёт, пока строка pending с этим # filename не исчезнет, но не дольше WAIT. На уровне оператора строка ещё # не заблокирована, уборщик её берёт. UPDATE OF status: пометку уборщика # (меняет только updated_at) ожидание не задерживает. @@ -297,15 +332,24 @@ BEGIN END IF; RETURN NEW; END IF; - IF OLD.status = 'pending' AND NEW.status = 'ready' THEN - IF TG_ARGV[0] = 'ready' THEN - RAISE EXCEPTION 'fault injected: attachment ready' + IF OLD.status = 'pending' AND NEW.status = 'queued' THEN + IF TG_ARGV[0] = 'queued' THEN + RAISE EXCEPTION 'fault injected: attachment queued' USING ERRCODE = '08006'; END IF; IF TG_ARGV[0] = 'stall' THEN PERFORM pg_sleep(4); END IF; END IF; + IF OLD.status <> 'ready' AND NEW.status = 'ready' THEN + IF TG_ARGV[0] = 'ready-fail' THEN + RAISE EXCEPTION 'fault injected: attachment ready' + USING ERRCODE = '08006'; + END IF; + IF TG_ARGV[0] = 'ready-stall' THEN + PERFORM pg_sleep(4); + END IF; + END IF; RETURN NEW; END $$; @@ -313,8 +357,8 @@ CREATE OR REPLACE FUNCTION fault_fail_attachments_commit() RETURNS trigger LANGUAGE plpgsql AS $$ BEGIN IF TG_ARGV[0] = 'commit' AND NEW.filename = TG_ARGV[1] - AND OLD.status = 'pending' AND NEW.status = 'ready' THEN - RAISE EXCEPTION 'fault injected: attachment ready commit' + AND OLD.status = 'pending' AND NEW.status = 'queued' THEN + RAISE EXCEPTION 'fault injected: attachment queued commit' USING ERRCODE = '08006'; END IF; RETURN NULL; @@ -384,8 +428,14 @@ DROP FUNCTION IF EXISTS fault_fail_attachments_mark(); """ # расхождения хранилищ (design change track2-reconciler, решение 11): # значения — переменные psql (:'title' — id, :'mode' — число) +# задание и варианты ссылаются на строку без каскада: у готового вложения +# метаданные удаляются вместе с ними DELETE_ROW_SQL = """\ +BEGIN; +DELETE FROM attachment_variants WHERE attachment_id = :'title'::uuid; +DELETE FROM attachment_jobs WHERE attachment_id = :'title'::uuid; DELETE FROM attachments WHERE id = :'title'::uuid RETURNING id; +COMMIT; """ SET_SIZE_SQL = """\ UPDATE attachments SET size_bytes = :'mode'::integer @@ -404,6 +454,79 @@ WHERE id = :'title'::uuid RETURNING id; LOST_IDS_SQL = """\ SELECT id FROM attachments WHERE lost_at IS NOT NULL ORDER BY id; """ +JOB_SQL = """\ +SELECT row_to_json(j) FROM ( + SELECT id, state, attempt, last_error_code, next_attempt_at, + lease_expires_at, published_at + FROM attachment_jobs WHERE attachment_id = :'title'::uuid +) j; +""" +# брокер — настройками процесса в контейнере API: пароль в hook не попадает. +# Соединение прямо на сообщение, без подтверждения (peek): закрытие +# соединения возвращает его в очередь. Очередь — из имени базы процесса +PEEK_JOB_PY = """\ +import asyncio +import json +import aio_pika +from src.config import settings +from src.infra.broker import queue_name +async def main(): + broker = settings.broker + connection = await aio_pika.connect( + host=broker.host, port=broker.port, login=broker.user, + password=broker.password.get_secret_value(), timeout=5, + ) + async with connection: + channel = await connection.channel() + queue = await channel.declare_queue( + queue_name(settings.database.name), durable=True, + ) + message = await queue.get(no_ack=False, fail=False, timeout=5) + if message is None: + return + print(json.dumps({ + "body": message.body.decode(), + "delivery_mode": message.delivery_mode, + })) + await message.nack(requeue=True) +asyncio.run(main()) +""" +PUBLISH_JOB_PY = """\ +import asyncio +import sys +import aio_pika +from src.config import settings +from src.infra.broker import queue_name +async def main(): + broker = settings.broker + connection = await aio_pika.connect( + host=broker.host, port=broker.port, login=broker.user, + password=broker.password.get_secret_value(), timeout=5, + ) + async with connection: + channel = await connection.channel(publisher_confirms=True) + name = queue_name(settings.database.name) + await channel.declare_queue(name, durable=True) + await channel.default_exchange.publish( + aio_pika.Message( + sys.stdin.buffer.read(), + delivery_mode=aio_pika.DeliveryMode.PERSISTENT, + ), + routing_key=name, + ) +asyncio.run(main()) +""" +# поля list_queues; очередь — точное имя из FAULT_DATABASE +QUEUE_COLUMNS = ( + "name", + "messages", + "messages_ready", + "messages_unacknowledged", + "consumers", + "durable", +) +# копия ATTACHMENT_QUEUE_SUFFIX из src/utils/constants.py +QUEUE_SUFFIX = "attachment.process.v1" # объект мимо API: botocore образа (зависимость aiobotocore) с адресом, # регионом и ключами из настроек процесса в контейнере API — ключи в hook # не попадают. Ключ — argv[1], тело — stdin @@ -437,11 +560,13 @@ SCHEDULED_CLEANER_ENV = "RECONCILER__INTERVAL_SECONDS=1" SCHEDULED_CLEANER_MAX_S = 60 FAIL_ATTACHMENTS_MODES = ( "insert", - "ready", + "queued", "stall", "commit", "outlive", "undeletable", + "ready-fail", + "ready-stall", ) # как S3_BUCKET_NAME_PATTERN в src/utils/constants.py; имя базы — как в # run_isolated.py: путь filer собирается только из проверенных имён @@ -453,7 +578,10 @@ ATTACHMENT_DIR_RE = re.compile( r"^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", ) ATTACHMENT_KEY_PREFIX = "attachments" +ATTACHMENT_STAGING_PREFIX = "staging" ATTACHMENT_ORIGINAL = "original" +# объект варианта в каталоге вложения: v<версия>-<имя> +VARIANT_FILE_RE = re.compile(r"^v[1-9][0-9]*-(thumbnail|crop|optimized)$") # строка fs.tree: отступ по 4 символа на уровень («│ » или « »), затем # «├──» или «└──» и имя TREE_LINE_RE = re.compile(r"^((?:[│ ] {3})*)[├└]──\s*(.*?)\s*$") @@ -697,11 +825,31 @@ def ids_with_original(tree: str) -> list[str]: return found -def object_ids(project: str) -> str: - """`id` вложений с объектом в bucket стенда, строка на `id`. Нет - префикса — пусто.""" +def variant_files(tree: str, attachment_id: str) -> list[str]: + """Файлы вариантов в каталоге `attachment_id` вывода `fs.tree`.""" + found: list[str] = [] + current = "" + for line in tree.splitlines(): + match = TREE_LINE_RE.match(line) + if match is None: + continue + depth = len(match.group(1)) // 4 + 1 + name = match.group(2) + if depth == 1: + current = name + elif ( + depth == 2 + and current == attachment_id + and VARIANT_FILE_RE.fullmatch(name) + ): + found.append(name) + return found + + +def tree_of(project: str, prefix: str) -> str: + """`fs.tree` каталога `<база>/` bucket стенда; нет — пусто.""" bucket, database = storage_names() - tree = compose( + return compose( project, "exec", "-T", @@ -709,11 +857,141 @@ def object_ids(project: str) -> str: "sh", "-c", "exec weed shell -master=127.0.0.1:9333 2>&1", - stdin=( - f"fs.tree /buckets/{bucket}/{database}/{ATTACHMENT_KEY_PREFIX}\n" - ), + stdin=f"fs.tree /buckets/{bucket}/{database}/{prefix}\n", ) - return "\n".join(ids_with_original(tree)) + + +def object_ids(project: str, prefix: str = ATTACHMENT_KEY_PREFIX) -> str: + """`id` вложений с объектом `original` под префиксом bucket стенда, + строка на `id`. Нет префикса — пусто.""" + return "\n".join(ids_with_original(tree_of(project, prefix))) + + +def variant_object_count(project: str, attachment_id: str) -> str: + wanted = str(uuid.UUID(attachment_id)) + tree = tree_of(project, ATTACHMENT_KEY_PREFIX) + return str(len(variant_files(tree, wanted))) + + +def queue() -> str: + _, database = storage_names() + return f"{database}.{QUEUE_SUFFIX}" + + +def queue_state(project: str) -> str: + """Состояние очереди стенда JSON-ом или `null`: `rabbitmqctl` в контейнере + брокера, без management API.""" + output = compose( + project, + "exec", + "-T", + "rabbitmq", + "rabbitmqctl", + "-q", + "list_queues", + *QUEUE_COLUMNS, + "--formatter", + "json", + ) + for item in json.loads(output or "[]"): + if item["name"] == queue(): + return json.dumps(item) + return "null" + + +def delete_queue(project: str) -> str: + """Удалить очередь стенда; её отсутствие — не ошибка.""" + result = compose_run( + project, + "exec", + "-T", + "rabbitmq", + "rabbitmqctl", + "-q", + "delete_queue", + queue(), + ) + if result.returncode != 0 and "No such queue" not in ( + result.stdout + result.stderr + ): + sys.stderr.write(result.stderr) + raise SystemExit(result.returncode) + return "" + + +def api_python(project: str, code: str, stdin: bytes | None = None) -> str: + """Код в контейнере обычного API: настройки процесса, а не hook, знают + пароль брокера.""" + result = subprocess.run( + ["docker", "exec", "-i", api_container(project), "python", "-c", code], + input=b"" if stdin is None else stdin, + capture_output=True, + check=False, + ) + if result.returncode != 0: + tail = result.stderr.decode(errors="replace").strip().splitlines()[-1:] + raise HookError(f"api python failed: {tail}") + # лишние записи настройки логгера в stdout: строка результата — последняя + lines = result.stdout.decode(errors="replace").strip().splitlines() + return lines[-1] if lines else "" + + +def worker_container(project: str) -> str: + container = compose(project, "ps", "-a", "-q", "worker") + if not container: + raise HookError("worker container of the stand not found") + return container + + +def worker_action(project: str, action: str) -> str: + """`start` — тот же контейнер, `docker start`, как у уборщика: у compose + start нет контейнера одноразовых зависимостей.""" + if action == "stop": + return compose(project, "stop", "worker") + docker(action, worker_container(project)) + return "" + + +def worker_state(project: str) -> str: + fields = docker( + "inspect", + "-f", + "{{.State.Running}} {{.RestartCount}} {{.State.OOMKilled}} " + "{{.State.ExitCode}}", + worker_container(project), + ).split() + return json.dumps( + { + "running": fields[0] == "true", + "restart_count": int(fields[1]), + "oom_killed": fields[2] == "true", + "exit_code": int(fields[3]), + }, + ) + + +def broker_action(project: str, action: str) -> str: + """Действия брокера; ждёт ответа после возврата.""" + if action in ("stop", "pause"): + compose(project, action, "rabbitmq") + return "" + if action == "kill": + docker("kill", compose(project, "ps", "-q", "rabbitmq")) + return "" + if action == "start": + docker("start", compose(project, "ps", "-a", "-q", "rabbitmq")) + elif action == "unpause": + compose(project, "unpause", "rabbitmq") + else: + compose( + project, + "up", + "-d", + "--no-deps", + "--force-recreate", + "rabbitmq", + ) + return wait_answers(project, "rabbitmq") def fail_attachments(project: str, mode: str, filename: str) -> str: @@ -739,16 +1017,22 @@ def storage_names() -> tuple[str, str]: def object_key(key: str) -> str: - """Ключ объекта вложений базы стенда; иначе — отказ (код 2).""" + """Ключ объекта вложений или staging базы стенда; иначе — отказ (код + 2).""" _, database = storage_names() - prefix = f"{database}/{ATTACHMENT_KEY_PREFIX}/" + prefixes = ( + f"{database}/{ATTACHMENT_KEY_PREFIX}/", + f"{database}/{ATTACHMENT_STAGING_PREFIX}/", + ) if ( - not key.startswith(prefix) - or len(key) == len(prefix) + not any( + key.startswith(prefix) and len(key) > len(prefix) + for prefix in prefixes + ) or not OBJECT_KEY_RE.fullmatch(key) or ".." in key.split("/") ): - raise HookError(f"object key must be under {prefix}: {key!r}") + raise HookError(f"object key must be under {prefixes}: {key!r}") return key @@ -975,6 +1259,35 @@ def run(project: str, action: str, args: list[str]) -> str: """Выполнить действие; синтаксис без match: hook запускают и 3.9.""" if action in ("stop", "start") and args == ["cleaner"]: return cleaner_action(project, action) + if action in ("stop", "start", "kill") and args == ["worker"]: + return worker_action(project, action) + if action in ( + "stop", + "start", + "pause", + "unpause", + "kill", + "recreate", + ) and args == ["rabbitmq"]: + return broker_action(project, action) + if action == "worker-state" and not args: + return worker_state(project) + if action == "worker-log" and not args: + return docker("logs", worker_container(project)) + if action == "queue-state" and not args: + return queue_state(project) + if action == "delete-queue" and not args: + return delete_queue(project) + if action == "peek-job" and not args: + return api_python(project, PEEK_JOB_PY) + if action == "publish-job" and not args: + return api_python(project, PUBLISH_JOB_PY, sys.stdin.buffer.read()) + if action == "job" and len(args) == 1: + return psql(project, JOB_SQL, title=str(uuid.UUID(args[0]))) + if action == "staging-ids" and not args: + return object_ids(project, ATTACHMENT_STAGING_PREFIX) + if action == "variant-object-count" and len(args) == 1: + return variant_object_count(project, args[0]) if action in ("stop", "pause") and len(args) == 1: return compose(project, action, service(args[0])) if action == "start" and len(args) == 1: diff --git a/student-tests/images.py b/student-tests/images.py index 248a13ab..2665e00b 100644 --- a/student-tests/images.py +++ b/student-tests/images.py @@ -267,6 +267,74 @@ def jpeg_empty_scan(data: bytes | None = None) -> bytes: return data[: _jpeg_header(data)[-1][2]] + JPEG_EOI +def jpeg_precision_12() -> bytes: + """JPEG с 12 битами на компоненту в SOF: структура верна, а Pillow такой + не декодирует (спек `attachment-processing`, «Изображение не + декодируется»).""" + data = bytearray(jpeg()) + sof = data.index(b"\xff\xc0") + data[sof + 4] = 12 + return bytes(data) + + +def jpeg_halves( + orientation: int | None = None, + size: tuple[int, int] = (400, 200), +) -> bytes: + """JPEG: левая половина красная, правая синяя; EXIF orientation — + необязательно.""" + from PIL import Image # noqa: PLC0415 + + width, height = size + image = Image.new("RGB", size, (255, 0, 0)) + image.paste((0, 0, 255), (width // 2, 0, width, height)) + save: dict[str, object] = {"quality": 95} + if orientation is not None: + exif = Image.Exif() + exif[0x0112] = orientation + save["exif"] = exif + buffer = io.BytesIO() + image.save(buffer, "JPEG", **save) + return buffer.getvalue() + + +def png_half_transparent(size: tuple[int, int] = (200, 100)) -> bytes: + """PNG RGBA: левая половина чёрная и непрозрачная, правая прозрачная.""" + from PIL import Image # noqa: PLC0415 + + width, height = size + image = Image.new("RGBA", size, (0, 0, 0, 255)) + image.paste((0, 0, 0, 0), (width // 2, 0, width, height)) + buffer = io.BytesIO() + image.save(buffer, "PNG") + return buffer.getvalue() + + +def png_palette_transparent(size: tuple[int, int] = (200, 100)) -> bytes: + """PNG с палитрой и tRNS: левая половина — чёрный цвет палитры, правая — + прозрачный.""" + from PIL import Image # noqa: PLC0415 + + width, height = size + image = Image.new("P", size, 0) + image.putpalette([0, 0, 0, 0, 0, 0]) + image.paste(1, (width // 2, 0, width, height)) + buffer = io.BytesIO() + image.save(buffer, "PNG", transparency=bytes((255, 0))) + return buffer.getvalue() + + +def png_rgba_large(width: int = 8000, height: int = 5000) -> bytes: + """PNG RGBA на 40 млн пикселей: пик памяти декодирования — как у + настоящего, файл мал и собирается быстро.""" + from PIL import Image # noqa: PLC0415 + + image = Image.new("RGBA", (width, height), (10, 20, 30, 128)) + buffer = io.BytesIO() + image.save(buffer, "PNG", compress_level=1) + return buffer.getvalue() + + def png_variants() -> dict[str, bytes]: """Разновидности PNG спека: палитра, альфа, серый с альфой, 16 и 1 бит, Adam7.""" diff --git a/student-tests/run_failures.py b/student-tests/run_failures.py index e27bd1e4..917c13a0 100644 --- a/student-tests/run_failures.py +++ b/student-tests/run_failures.py @@ -1,14 +1,16 @@ """`make failure_checks`: проверки отказов на отдельном стенде. Поднимает тот же `docker-compose.yml` под проектом `<рабочий>-failures` -с override `student-tests/failures.compose.yml`: свои PostgreSQL, Valkey и -S3 со своими volumes, порты хранилищ не публикуются. Затем: +с override `student-tests/failures.compose.yml`: свои PostgreSQL, Valkey, +S3 и брокер со своими volumes, порты хранилищ не публикуются. Затем: - собирает образ из рабочего дерева, применяет миграции и bootstrap S3; - запускает уборщика незавершённых загрузок с grace 20 с и интервалом 1 с (`failures.compose.yml`; design change `upload-consistency`, решение 10) без плановой сверки (design change `track2-reconciler`, решение 9) и передаёт значения тестам; уборщика с плановой сверкой `<проект>-cleaner-scheduled` запускает hook и убирает этот скрипт; +- запускает worker с короткими сроками и малым числом попыток (design + change `async-attachments`, решение 15) и передаёт значения тестам; - запускает четыре контейнера API: обычный (с `MAX_UPLOAD_BYTES=1` и `MAX_IMAGE_PIXELS=1` в окружении — лимиты вложений от них не зависят), «тесный» (сроки сессии и ключа идемпотентности 2 с, пул из одного @@ -17,8 +19,8 @@ S3 со своими volumes, порты хранилищ не публикую «с коротким сроком S3» (срок вызова S3 1 с; change `fix-upload-put-flake`); - прогоняет тесты с маркером `fault` (`pytest -m fault`), передав им hook - `student-tests/fault_hook.py`; при падении печатает журналы API и - уборщика; + `student-tests/fault_hook.py`; при падении печатает журналы API, уборщика + и worker; - после тестов читает журнал PostgreSQL стенда: печатает сводку и падает на признаках аварийного перезапуска (решение 12 design change `fix-known-issues`); @@ -184,6 +186,27 @@ def cleaner_timings(project: str) -> dict[str, str]: } +def worker_timings(project: str) -> dict[str, str]: + """Сроки и попытки worker стенда — из конфигурации compose + (`failures.compose.yml`): тесты ждут по ним.""" + config = dc(project, "config", "--format", "json", quiet=True) + environment = json.loads(config.stdout)["services"]["worker"][ + "environment" + ] + return { + "FAULT_WORKER_MAX_ATTEMPTS": environment["WORKER__MAX_ATTEMPTS"], + "FAULT_WORKER_RETRY_DELAY_S": environment[ + "WORKER__RETRY_DELAY_SECONDS" + ], + "FAULT_WORKER_JOB_TIMEOUT_S": environment[ + "WORKER__JOB_TIMEOUT_SECONDS" + ], + "FAULT_WORKER_GRACEFUL_S": environment[ + "WORKER__GRACEFUL_SHUTDOWN_SECONDS" + ], + } + + def env_pairs(env: dict[str, str]) -> str: """`KEY=value` через пробел: так окружение API получают тесты.""" return " ".join(f"{key}={value}" for key, value in env.items()) @@ -339,8 +362,17 @@ def main() -> int: try: say("build image") dc(project, "build", "api") - say("start postgres, valkey and s3") - dc(project, "up", "-d", "--wait", "postgres", "valkey", "s3") + say("start postgres, valkey, s3 and rabbitmq") + dc( + project, + "up", + "-d", + "--wait", + "postgres", + "valkey", + "s3", + "rabbitmq", + ) say("migrations") dc(project, "run", "--rm", "migrate") # --wait одноразовый сервис считает готовым уже запущенным: код @@ -362,6 +394,14 @@ def main() -> int: f"{timings['FAULT_RECONCILER_INTERVAL_S']} s (0 — off)", ) dc(project, "up", "-d", "--no-deps", "cleaner") + workers = worker_timings(project) + say( + f"start worker: attempts {workers['FAULT_WORKER_MAX_ATTEMPTS']}, " + f"retry delay {workers['FAULT_WORKER_RETRY_DELAY_S']} s, " + f"job timeout {workers['FAULT_WORKER_JOB_TIMEOUT_S']} s, " + f"graceful {workers['FAULT_WORKER_GRACEFUL_S']} s", + ) + dc(project, "up", "-d", "--no-deps", "worker") say("start api containers") base_url = start_api(project, default_name, free_port(), LIMITS_ENV) tight_url = start_api(project, tight_name, free_port(), TIGHT_ENV) @@ -391,6 +431,7 @@ def main() -> int: } | storage_names(project) | timings + | workers ) say("pytest -m fault") results["fault"] = run( @@ -426,16 +467,17 @@ def main() -> int: name, check=False, ) - say(f"last {LOG_TAIL_LINES} lines of cleaner") - dc( - project, - "logs", - "--no-log-prefix", - "--tail", - str(LOG_TAIL_LINES), - "cleaner", - check=False, - ) + for service in ("cleaner", "worker"): + say(f"last {LOG_TAIL_LINES} lines of {service}") + dc( + project, + "logs", + "--no-log-prefix", + "--tail", + str(LOG_TAIL_LINES), + service, + check=False, + ) say("cleanup") if not cleanup(project, containers): say("cleanup failed") diff --git a/student-tests/run_isolated.py b/student-tests/run_isolated.py index 71e8bfe0..dc0862d7 100644 --- a/student-tests/run_isolated.py +++ b/student-tests/run_isolated.py @@ -1,17 +1,19 @@ """`make test_isolated`: образ на временной базе `test_`. Создаёт базу в Postgres стенда, накатывает на неё миграции сервисом -`migrate`, поднимает отдельный контейнер `api` из определения compose с -подменой только `DATABASE__NAME`, прогоняет `make test` и +`migrate`, поднимает отдельные контейнеры `api` и `worker` из определений +compose с подменой только `DATABASE__NAME`, прогоняет `make test` и `make student_test` (`EXPECT_REPLICAS=1`: один процесс без -балансировщика, тесты реплик пропускаются), затем удаляет контейнер и +балансировщика, тесты реплик пропускаются), затем удаляет контейнеры и базу — при любом исходе, в том числе по Ctrl+C. Рабочая база и рабочие контейнеры стенда не трогаются. Valkey стенда общий: ключи кэша включают имя базы, и карточки тестового прогона не смешиваются с рабочими. S3 стенда тоже общий: ключи объектов начинаются с имени базы, и префикс `test_/` bucket удаляется в начале (хвост прошлого прогона) и в уборке через `weed shell` в контейнере `s3` (design change `s3-storage`, решение 9). -Только stdlib: всё через docker compose и make. Решение 12 design change +Брокер стенда общий: задания идут через очередь `<база>.attachment.process.v1`, +и очередь временной базы удаляется в начале и в уборке (design change +`async-attachments`, решение 15). Только stdlib: всё через docker compose и make. Решение 12 design change `postgres-storage`. Запускается напрямую `$(PYTHON)`, как проверки skeleton, а не через @@ -46,6 +48,9 @@ DEFAULT_BUCKET = "messenger" WEED_NO_ENTRY = "no entry is found" READY_TIMEOUT_S = 60 LOG_TAIL_LINES = 50 +# копия ATTACHMENT_QUEUE_SUFFIX из src/utils/constants.py; скрипт на stdlib и +# код приложения не импортирует +QUEUE_SUFFIX = "attachment.process.v1" def say(message: str) -> None: @@ -122,6 +127,37 @@ def object_prefix(bucket: str, test_db: str) -> str: return f"/buckets/{bucket}/{test_db}" +def queue_of(test_db: str) -> str: + """Очередь временной базы; другое имя — отказ, как у префикса: ошибка не + может удалить рабочую очередь.""" + if not TEST_DB_NAME_RE.fullmatch(test_db): + raise ValueError(f"not a test database name: {test_db}") + return f"{test_db}.{QUEUE_SUFFIX}" + + +def remove_queue(queue: str) -> None: + """Удалить очередь `rabbitmqctl` в контейнере брокера; её отсутствие — не + ошибка. Иначе — `RuntimeError`.""" + result = run( + "docker", + "compose", + "exec", + "-T", + "rabbitmq", + "rabbitmqctl", + "-q", + "delete_queue", + queue, + check=False, + quiet=True, + ) + output = result.stdout + result.stderr + if result.returncode != 0 and "No such queue" not in output: + raise RuntimeError( + f"queue {queue} not removed: {output.strip()[:200]}", + ) + + def weed_shell(command: str) -> str: """Одна команда `weed shell` в контейнере `s3`: ключ подписи — в его окружении, master и filer — на его loopback. Вывод — stdout и stderr @@ -205,23 +241,29 @@ def main() -> int: return 2 try: prefix = object_prefix(env.get("S3__BUCKET", DEFAULT_BUCKET), test_db) + queue = queue_of(test_db) except ValueError as e: say(str(e)) return 2 port = env["TEST_APP_PORT"] app_port = env.get("APP__PORT", "8080") - container = f"{compose_project()}-test-api" + project = compose_project() + container = f"{project}-test-api" + worker = f"{project}-test-worker" + containers = (container, worker) base_url = f"http://127.0.0.1:{port}" say( - f"database={test_db} objects={prefix}/ container={container} " - f"base_url={base_url}", + f"database={test_db} objects={prefix}/ queue={queue} " + f"containers={container} {worker} base_url={base_url}", ) - remove_container(container) + for name in containers: + remove_container(name) drop_database(test_db) - say(f"remove objects {prefix}/") + say(f"remove objects {prefix}/ and queue {queue}") try: remove_objects(prefix) + remove_queue(queue) except (subprocess.CalledProcessError, RuntimeError) as e: say(f"setup failed: {e}") return 1 @@ -261,6 +303,20 @@ def main() -> int: quiet=True, ) wait_ready(f"{base_url}/health/ready", container) + say("start worker container") + run( + "docker", + "compose", + "run", + "-d", + "--no-deps", + "--name", + worker, + "-e", + f"DATABASE__NAME={test_db}", + "worker", + quiet=True, + ) say("ready") for target in ("test", "student_test"): say(f"make {target}") @@ -284,25 +340,31 @@ def main() -> int: # повторный Ctrl+C не должен оборвать уборку на полпути signal.signal(signal.SIGINT, signal.SIG_IGN) if failed: - say(f"last {LOG_TAIL_LINES} lines of {container}") - run( - "docker", - "logs", - "--tail", - str(LOG_TAIL_LINES), - container, - check=False, - ) + for name in containers: + say(f"last {LOG_TAIL_LINES} lines of {name}") + run( + "docker", + "logs", + "--tail", + str(LOG_TAIL_LINES), + name, + check=False, + ) say("cleanup") - run("docker", "stop", container, check=False, quiet=True) - remove_container(container) + for name in containers: + run("docker", "stop", name, check=False, quiet=True) + remove_container(name) try: if args.keep_db: - say(f"kept database {test_db} and objects {prefix}/") + say( + f"kept database {test_db}, objects {prefix}/ and queue " + f"{queue}", + ) else: drop_database(test_db) - say(f"remove objects {prefix}/") + say(f"remove objects {prefix}/ and queue {queue}") remove_objects(prefix) + remove_queue(queue) except (subprocess.CalledProcessError, RuntimeError) as e: say(f"cleanup failed: {e}") results["cleanup"] = 1 diff --git a/student-tests/spec_coverage.py b/student-tests/spec_coverage.py index 96126b2d..2fdfef2d 100644 --- a/student-tests/spec_coverage.py +++ b/student-tests/spec_coverage.py @@ -27,6 +27,9 @@ CAPABILITIES = ( # уборщик: все сценарии — проверки отказов (design change # upload-consistency, решение 10) "storage-consistency", + # с лабы 5 (design change async-attachments, решение 15) + "attachment-processing", + "message-broker", ) SCENARIO_RE = re.compile(r"^#### Scenario: (.+?)\s*$", re.MULTILINE) @@ -151,6 +154,39 @@ EXCLUDED: dict[Scenario, Exclusion] = { "разные хэши одинаковых паролей, пароля нет в pg_dump базы — " "evidence/auth/passwords-and-tokens.md", ), + ("message-broker", "Сервис брокера запущен"): Exclusion( + reason="образ, volume и порты контейнера видны только в Docker", + check="driver.py --port broker-check: образ с тегом и digest, " + "именованный volume, docker port только AMQP на 127.0.0.1 — " + "evidence/broker/stand.md", + ), + ("message-broker", "Предел памяти брокера"): Exclusion( + reason="предел памяти виден только в статусе брокера", + check="driver.py --port broker-check: предел памяти из " + "rabbitmqctl status меньше лимита контейнера — " + "evidence/broker/stand.md", + ), + ("message-broker", "Остановка брокера"): Exclusion( + reason="код выхода и время остановки контейнера видны только в " + "Docker, а проверка плавной остановки — на рабочем стенде", + check="driver.py --port broker-check: docker compose stop " + "брокера — код 0 раньше срока — evidence/broker/stand.md", + ), + ("message-broker", "Очереди разных баз разделены"): Exclusion( + reason="прогон на временной базе и взгляд на очереди брокера, а " + "набор не знает, на какой базе работает", + check="make test_isolated KEEP_TEST_DB=1, driver.py --port " + "broker-check --require-test-queue, make test_isolated: очередь " + "временной базы есть после первого прогона и нет после второго — " + "evidence/broker/isolated.md", + ), + ("data-storage", "Ограничения обработки в схеме"): Exclusion( + reason="нужна прямая вставка в таблицы PostgreSQL, а тесты ходят по " + "HTTP", + check="driver.py --port attachment-storage: пробы ограничений " + "обработки в откатываемой транзакции — " + "evidence/attachments/storage.md", + ), } # ссылка исключения на доказательство в репозитории лабы EVIDENCE_RE = re.compile(r"evidence/[\w./-]+\.md") diff --git a/student-tests/test_api_conventions.py b/student-tests/test_api_conventions.py index 7d96f6f4..3040b07a 100644 --- a/student-tests/test_api_conventions.py +++ b/student-tests/test_api_conventions.py @@ -451,7 +451,7 @@ def test_attachment_ids_in_upper_case( chat: dict[str, Any], ) -> None: data = images.sample_png() - attachment = api.upload(alice, chat["id"], data) + attachment = api.upload_ready(alice, chat["id"], data) upper = attachment["id"].upper() meta = assert_ok(api.attachment_meta(alice, upper), 200, "Attachment") assert meta == attachment diff --git a/student-tests/test_attachment_processing.py b/student-tests/test_attachment_processing.py new file mode 100644 index 00000000..8df95c97 --- /dev/null +++ b/student-tests/test_attachment_processing.py @@ -0,0 +1,345 @@ +"""Спек `attachment-processing`: то, что видно по HTTP на любом стенде с worker. + +Thumbnail, скачивание варианта, готовность и `failed` от недекодируемого +изображения. Сценарии с остановкой worker, брокера и S3 — проверки отказов +(`test_failures.py`). +""" + +import io +import time +from typing import Any + +import pytest +from PIL import Image + +import images +from api_client import Actor, Api +from contract import ( + assert_error, + assert_instance_id, + assert_ok, + assert_replicas, + assert_variant_content, +) + +# сколько раз читать метаданные через LB, чтобы увидеть другую реплику +REPLICA_ATTEMPTS = 20 +# допуск к цвету пикселя: JPEG теряет, но красный, синий и белый различимы +COLOR_TOLERANCE = 40 +RED = (255, 0, 0) +BLUE = (0, 0, 255) +WHITE = (255, 255, 255) +BLACK = (0, 0, 0) + + +def thumbnail_of( + api: Api, + actor: Actor, + attachment: dict[str, Any], +) -> Image.Image: + """Вариант из метаданных готового вложения: скачан, сверен и открыт + как настоящий JPEG; настоящие размеры равны полям варианта.""" + assert [item["name"] for item in attachment["variants"]] == ["thumbnail"] + variant = attachment["variants"][0] + data = assert_variant_content( + api.attachment_content(actor, attachment["id"], variant="thumbnail"), + variant, + ) + image = Image.open(io.BytesIO(data)) + assert image.format == "JPEG" + assert image.size == (variant["width"], variant["height"]) + assert variant["content_type"] == "image/jpeg" + return image + + +def assert_color( + image: Image.Image, + position: tuple[int, int], + color: tuple[int, int, int], +) -> None: + got = image.convert("RGB").getpixel(position) + assert all( + abs(a - b) <= COLOR_TOLERANCE for a, b in zip(got, color, strict=True) + ), f"pixel {position}: {got}, expected about {color}" + + +def thumbnail_size( + api: Api, + actor: Actor, + chat_id: str, + data: bytes, +) -> tuple[int, int]: + attachment = api.upload_ready(actor, chat_id, data) + return thumbnail_of(api, actor, attachment).size + + +@pytest.mark.spec("attachment-processing", "Вложение становится готовым") +def test_attachment_becomes_ready( + api: Api, + alice: Actor, + chat: dict[str, Any], +) -> None: + data = images.sample_png() + accepted = api.upload(alice, chat["id"], data, filename="sample.png") + started = time.monotonic() + ready = api.wait_attachment(alice, accepted["id"]) + print(f"ready in {time.monotonic() - started:.2f} s") + assert ready["error_code"] is None + assert [item["name"] for item in ready["variants"]] == ["thumbnail"] + + +@pytest.mark.spec("attachment-processing", "Fixture 320 × 200") +def test_thumbnail_fixture( + api: Api, + alice: Actor, + chat: dict[str, Any], +) -> None: + attachment = api.upload_ready(alice, chat["id"], images.sample_png()) + assert thumbnail_of(api, alice, attachment).size == (256, 160) + + +@pytest.mark.spec( + "attachment-processing", + "Маленькое изображение не увеличивается", +) +def test_thumbnail_not_enlarged( + api: Api, + alice: Actor, + chat: dict[str, Any], +) -> None: + for size in ((100, 50), (256, 256)): + data = images.png(*size) + assert thumbnail_size(api, alice, chat["id"], data) == size + + +@pytest.mark.spec("attachment-processing", "Округление вниз и минимум") +def test_thumbnail_rounding( + api: Api, + alice: Actor, + chat: dict[str, Any], +) -> None: + for size, expected in ( + ((1000, 601), (256, 153)), + ((601, 1000), (153, 256)), + ((5000, 10), (256, 1)), + ((10, 5000), (1, 256)), + ): + data = images.png(*size) + assert thumbnail_size(api, alice, chat["id"], data) == expected, size + + +@pytest.mark.spec("attachment-processing", "EXIF orientation") +def test_thumbnail_exif_orientation( + api: Api, + alice: Actor, + chat: dict[str, Any], +) -> None: + attachment = api.upload_ready( + alice, + chat["id"], + images.jpeg_halves(orientation=6), + content_type="image/jpeg", + ) + image = thumbnail_of(api, alice, attachment) + assert image.size == (128, 256) + assert_color(image, (64, 32), RED) + assert_color(image, (64, 224), BLUE) + + +def test_thumbnail_every_orientation( + api: Api, + alice: Actor, + chat: dict[str, Any], +) -> None: + """Спек `attachment-processing`, «EXIF orientation»: все восемь значений — + где оказывается красная половина показанного изображения.""" + # значение → размер и точки красного и синего: левая половина файла + # красная, правая синяя + wide, tall = (256, 128), (128, 256) + left, right = (32, 64), (224, 64) + top, bottom = (64, 32), (64, 224) + expected = { + 1: (wide, left, right), + 2: (wide, right, left), + 3: (wide, right, left), + 4: (wide, left, right), + 5: (tall, top, bottom), + 6: (tall, top, bottom), + 7: (tall, bottom, top), + 8: (tall, bottom, top), + } + for orientation, (size, red, blue) in expected.items(): + attachment = api.upload_ready( + alice, + chat["id"], + images.jpeg_halves(orientation=orientation), + content_type="image/jpeg", + ) + image = thumbnail_of(api, alice, attachment) + assert image.size == size, orientation + assert_color(image, red, RED) + assert_color(image, blue, BLUE) + + +@pytest.mark.spec("attachment-processing", "Alpha на белый") +def test_thumbnail_alpha( + api: Api, + alice: Actor, + chat: dict[str, Any], +) -> None: + for data in ( + images.png_half_transparent(), + images.png_palette_transparent(), + ): + attachment = api.upload_ready(alice, chat["id"], data) + image = thumbnail_of(api, alice, attachment) + assert_color(image, (20, image.height // 2), BLACK) + assert_color(image, (image.width - 20, image.height // 2), WHITE) + + +@pytest.mark.spec("attachment-processing", "Разновидности форматов") +def test_thumbnail_format_variants( + api: Api, + alice: Actor, + chat: dict[str, Any], +) -> None: + kinds = [ + ("image/png", name, data) + for name, data in images.png_variants().items() + ] + [ + ("image/jpeg", name, data) + for name, data in images.jpeg_variants().items() + ] + for content_type, name, data in kinds: + attachment = api.upload_ready( + alice, + chat["id"], + data, + content_type=content_type, + filename=f"{name}.img", + ) + thumbnail_of(api, alice, attachment) + + +@pytest.mark.spec("attachments", "Скачивание thumbnail") +def test_download_thumbnail( + api: Api, + alice: Actor, + bob: Actor, + chat: dict[str, Any], +) -> None: + attachment = api.upload_ready(alice, chat["id"], images.sample_png()) + resp = api.attachment_content( + bob, + attachment["id"], + variant="thumbnail", + ) + assert not resp.is_redirect + assert_variant_content(resp, attachment["variants"][0]) + assert resp.headers["Content-Type"] == "image/jpeg" + + +@pytest.mark.spec("attachments", "Отсутствующий вариант") +def test_missing_variant( + api: Api, + alice: Actor, + chat: dict[str, Any], +) -> None: + attachment = api.upload_ready(alice, chat["id"], images.sample_png()) + for variant in ("crop", "optimized"): + assert_error( + api.attachment_content(alice, attachment["id"], variant=variant), + 404, + ) + + +@pytest.mark.spec("attachments", "Вариант для постороннего") +def test_variant_outsider( + api: Api, + alice: Actor, + eve: Actor, + chat: dict[str, Any], +) -> None: + attachment = api.upload_ready(alice, chat["id"], images.sample_png()) + outsider = assert_error( + api.attachment_content(eve, attachment["id"], variant="thumbnail"), + 404, + ) + unknown = assert_error( + api.attachment_content( + alice, + "00000000-0000-4000-8000-000000000000", + variant="thumbnail", + ), + 404, + ) + assert outsider["message"] == unknown["message"] + + +@pytest.mark.spec("messages", "Вложение failed") +def test_message_with_failed_attachment( + api: Api, + alice: Actor, + chat: dict[str, Any], +) -> None: + accepted = api.upload( + alice, + chat["id"], + images.jpeg_precision_12(), + content_type="image/jpeg", + ) + failed = api.wait_attachment(alice, accepted["id"], status="failed") + assert failed["error_code"] == "invalid_image" + assert failed["variants"] == [] + key = "failed-attachment-key" + assert_error( + api.post_message( + alice, + chat["id"], + json={"text": "x", "attachment_ids": [failed["id"]]}, + key=key, + ), + 409, + ) + assert_error( + api.post_message( + alice, + chat["id"], + json={ + "text": "x", + "attachment_ids": [ + failed["id"], + "00000000-0000-4000-8000-000000000000", + ], + }, + key=key, + ), + 404, + ) + assert api.all_messages(alice, chat["id"]) == [] + # откат освободил ключ: то же значение годится для другого тела + sent = api.send_message(alice, chat["id"], "без вложения", key=key) + assert sent["attachment_ids"] == [] + + +@pytest.mark.spec("data-storage", "Принятое вложение видно сразу") +def test_accepted_attachment_visible_on_other_replica( + api: Api, + alice: Actor, + bob: Actor, + chat: dict[str, Any], + replicas: int, +) -> None: + upload = api.post_attachment(alice, chat["id"], images.sample_png()) + assert upload.status_code == 202, upload.text + accepted = upload.json() + uploaded_via = assert_instance_id(upload) + seen = {uploaded_via} + for _ in range(REPLICA_ATTEMPTS): + resp = api.attachment_meta(bob, accepted["id"]) + meta = assert_ok(resp, 200, "Attachment") + assert meta["id"] == accepted["id"] + seen.add(assert_instance_id(resp)) + if len(seen) > 1: + break + assert_replicas(seen, replicas) diff --git a/student-tests/test_attachments.py b/student-tests/test_attachments.py index 46e0ac03..af19b81c 100644 --- a/student-tests/test_attachments.py +++ b/student-tests/test_attachments.py @@ -21,6 +21,7 @@ import images from api_client import API, Actor, Api from contract import ( BEARER_CHALLENGE, + assert_accepted, assert_content, assert_error, assert_errors, @@ -29,8 +30,20 @@ from contract import ( assert_ok, assert_replicas, assert_unauthorized, + assert_variant_content, ) +# поля оригинала: не меняются после ответа на загрузку +ORIGINAL_FIELDS = ( + "id", + "chat_id", + "owner_id", + "filename", + "content_type", + "size_bytes", + "sha256", + "created_at", +) # больше лимита в 3 раза: 30 MiB BIG_BYTES = 30 * 1024 * 1024 # сколько скачиваний ждать ответа другой реплики (round-robin LB) @@ -56,7 +69,7 @@ def big_body() -> bytes: def test_upload_png(api: Api, alice: Actor, chat: dict[str, Any]) -> None: data = images.sample_png() attachment = api.upload(alice, chat["id"], data, filename="sample.png") - assert attachment["status"] == "ready" + assert attachment["status"] == "queued" assert attachment["variants"] == [] assert attachment["error_code"] is None assert attachment["content_type"] == "image/png" @@ -167,7 +180,7 @@ def test_exactly_max_pixels( chat: dict[str, Any], ) -> None: data = images.png(8000, 5000, color=0, depth=1) - api.upload(alice, chat["id"], data) + api.upload_ready(alice, chat["id"], data) @pytest.mark.spec("attachments", "Данные длиннее размеров") @@ -247,7 +260,7 @@ def test_unsuitable_content_type( data, content_type="IMAGE/PNG; charset=binary", ) - assert assert_ok(resp, 201, "Attachment")["content_type"] == "image/png" + assert assert_accepted(resp)["content_type"] == "image/png" @pytest.mark.spec("attachments", "Обрезанный файл") @@ -329,7 +342,7 @@ def test_tail_after_end( ("image/png", images.with_tail(images.sample_png())), ("image/jpeg", images.with_tail(images.jpeg())), ): - attachment = api.upload( + attachment = api.upload_ready( alice, chat["id"], data, @@ -385,7 +398,7 @@ def test_filename_not_utf8( chat: dict[str, Any], ) -> None: """Процент-коды `filename` идут в строке запроса как есть: httpx их - не перекодирует. Без строгого разбора `a%FFb.png` давал 201 с U+FFFD + не перекодирует. Без строгого разбора `a%FFb.png` давал успех с U+FFFD в имени вместо байта.""" data = images.sample_png() path = f"{API}/chats/{chat['id']}/attachments" @@ -408,11 +421,7 @@ def test_filename_not_utf8( 400, ) # верный UTF-8 в процент-кодах — то же имя, что прислано - attachment = assert_ok( - upload("filename=%C3%A9t%C3%A9.png"), - 201, - "Attachment", - ) + attachment = assert_accepted(upload("filename=%C3%A9t%C3%A9.png")) assert attachment["filename"] == "été.png" @@ -511,7 +520,7 @@ def test_other_member_reads( chat: dict[str, Any], ) -> None: data = images.sample_png() - attachment = api.upload(alice, chat["id"], data) + attachment = api.upload_ready(alice, chat["id"], data) assert_ok(api.attachment_meta(bob, attachment["id"]), 200, "Attachment") assert_content( api.attachment_content(bob, attachment["id"]), @@ -582,7 +591,13 @@ def test_meta_equals_upload( 200, "Attachment", ) - assert meta == attachment + for field in ORIGINAL_FIELDS: + assert meta[field] == attachment[field], field + ready = api.wait_attachment(bob, attachment["id"]) + for field in ORIGINAL_FIELDS: + assert ready[field] == attachment[field], field + assert ready["error_code"] is None + assert ready["variants"], "ready attachment has no variants" @pytest.mark.spec("attachments", "Побайтный оригинал") @@ -596,7 +611,7 @@ def test_original_bytes( ("image/png", images.sample_png()), ("image/jpeg", images.jpeg(size=(320, 200))), ): - attachment = api.upload( + attachment = api.upload_ready( alice, chat["id"], data, @@ -615,7 +630,7 @@ def test_variant_original( chat: dict[str, Any], ) -> None: data = images.sample_png() - attachment = api.upload(alice, chat["id"], data) + attachment = api.upload_ready(alice, chat["id"], data) assert_content( api.attachment_content(alice, attachment["id"], variant="original"), data, @@ -628,7 +643,7 @@ def test_variant_original( attachment["id"], variant=variant, ) - for variant in ("thumbnail", "") + for variant in ("big", "") }, 400, ) @@ -643,12 +658,19 @@ def test_no_storage_traces( data = images.sample_png() upload = api.post_attachment(alice, chat["id"], data) # assert_ok сверяет тело со схемой контракта: лишних полей нет - attachment = assert_ok(upload, 201, "Attachment") + attachment = assert_accepted(upload) + ready = api.wait_attachment(alice, attachment["id"]) meta = api.attachment_meta(alice, attachment["id"]) assert_ok(meta, 200, "Attachment") content = api.attachment_content(alice, attachment["id"]) assert_content(content, data, "image/png") - for resp in (upload, meta, content): + thumbnail = api.attachment_content( + alice, + attachment["id"], + variant="thumbnail", + ) + assert_variant_content(thumbnail, ready["variants"][0]) + for resp in (upload, meta, content, thumbnail): assert_no_storage_traces(resp) @@ -660,8 +682,8 @@ def test_repeated_upload( chat: dict[str, Any], ) -> None: data = images.sample_png() - first = api.upload(alice, chat["id"], data) - second = api.upload(alice, chat["id"], data) + first = api.upload_ready(alice, chat["id"], data) + second = api.upload_ready(alice, chat["id"], data) assert first["id"] != second["id"] assert first["sha256"] == second["sha256"] for attachment in (first, second): @@ -711,6 +733,7 @@ def test_concurrent_uploads(api: Api, base_url: str) -> None: overlapping = sum(started < spans[0][1] for started, _ in spans) assert overlapping >= 2, f"uploads did not overlap: {spans}" for number, attachment in enumerate(attachments): + api.wait_attachment(actors[0], attachment["id"]) assert_content( api.attachment_content(actors[0], attachment["id"]), bodies[number], @@ -728,8 +751,9 @@ def test_download_through_other_replica( ) -> None: data = images.sample_png() upload = api.post_attachment(alice, chat["id"], data) - attachment = assert_ok(upload, 201, "Attachment") + attachment = assert_accepted(upload) uploaded_via = assert_instance_id(upload) + api.wait_attachment(alice, attachment["id"]) seen = {uploaded_via} for _ in range(REPLICA_ATTEMPTS): resp = api.attachment_content(bob, attachment["id"]) diff --git a/student-tests/test_failures.py b/student-tests/test_failures.py index 9f5986e3..66dedb4f 100644 --- a/student-tests/test_failures.py +++ b/student-tests/test_failures.py @@ -8,17 +8,20 @@ Valkey и S3, уборщик незавершённых загрузок (grace соединения), «узкий по загрузкам» (`FAULT_UPLOADS_BASE_URL`: одно место загрузки, одна в очереди, ожидание 1 с, срок тела 3 с — change `upload-memory`) и «с коротким сроком S3» (`FAULT_S3_BASE_URL`: срок вызова -S3 1 с — change `fix-upload-put-flake`). На хранилища и API тесты -действуют только через фикстуру `stand` (hook -`student-tests/fault_hook.py`) и всегда возвращают их в рабочее -состояние. Решение 4 design change `failure-checks`, решение 10 design -change `upload-consistency`, решение 11 design change `track2-reconciler` -(сверка bucket и БД — в конце модуля: её тесты оставляют помеченные -потерянными вложения, прежние тесты таких не ждут), решение 3 design -change `fix-upload-put-flake`. +S3 1 с — change `fix-upload-put-flake`), брокер и worker (4 попытки, пауза +5 с, срок попытки 10 с, срок остановки 2 с — `FAULT_WORKER_*`, change +`async-attachments`). На хранилища и API тесты действуют только через +фикстуру `stand` (hook `student-tests/fault_hook.py`) и всегда возвращают +их в рабочее состояние. Решение 4 design change `failure-checks`, решение +10 design change `upload-consistency`, решение 11 design change +`track2-reconciler` (сверка bucket и БД — в конце модуля: её тесты +оставляют помеченные потерянными вложения и объекты staging без строки, +прежние тесты таких не ждут), решение 3 design change +`fix-upload-put-flake`, решение 15 design change `async-attachments`. """ import hashlib +import io import json import math import os @@ -31,19 +34,24 @@ from collections.abc import Callable, Collection, Iterator, Sequence from concurrent.futures import ThreadPoolExecutor from contextlib import contextmanager from dataclasses import dataclass +from datetime import datetime +from pathlib import Path from typing import Any import httpx import pytest +from jsonschema import Draft202012Validator, FormatChecker import images from api_client import API, Actor, Api, new_key from contract import ( BEARER_CHALLENGE, + assert_accepted, assert_content, assert_error, assert_ok, assert_unauthorized, + assert_variant_content, describe, ) @@ -51,7 +59,7 @@ pytestmark = pytest.mark.fault type Stand = Callable[..., str] -RESTORE = {"stop": "start", "pause": "unpause"} +RESTORE = {"stop": "start", "pause": "unpause", "kill": "start"} # запас к границам времени: планировщик Docker Desktop SLACK_S = 0.3 # [cache] timeout_seconds и retry_after_seconds по умолчанию @@ -76,7 +84,7 @@ ME = f"{API}/users/me" @contextmanager def outage(stand: Stand, action: str, service: str) -> Iterator[None]: - """`stop` или `pause` хранилища; в `finally` — обратно.""" + """`stop`, `pause` или `kill` сервиса; в `finally` — обратно.""" stand(action, service) try: yield @@ -565,10 +573,14 @@ CLEANER_INTERVAL_S = float(os.environ.get("FAULT_CLEANER_INTERVAL_S", "1")) # запас поверх grace и интервала: проход, вызов hook, планировщик Docker # Desktop CLEANUP_SLACK_S = 5 -# задержка перевода в ready триггером stall (fault_hook.py) +# задержка перевода в queued триггером stall и в ready триггером ready-stall +# (fault_hook.py) STALL_S = 4 # срок клиента загрузок в потоке THREAD_CLIENT_TIMEOUT_S = 30 +# имя базы стенда: ключи объектов — `<база>/attachments//original` и +# `<база>/staging//original` +FAULT_DATABASE = os.environ.get("FAULT_DATABASE", "messenger") def attachment_rows(stand: Stand) -> dict[str, str]: @@ -577,28 +589,65 @@ def attachment_rows(stand: Stand) -> dict[str, str]: def stored_ids(stand: Stand) -> set[str]: - """`id` вложений, у которых есть объект в bucket стенда.""" + """`id` вложений с объектом в конечном префиксе bucket стенда.""" return set(stand("object-ids").splitlines()) +def staged_ids(stand: Stand) -> set[str]: + """`id` вложений с объектом в staging.""" + return set(stand("staging-ids").splitlines()) + + +def object_ids(stand: Stand) -> set[str]: + """`id` вложений с объектом в любом из двух префиксов.""" + return stored_ids(stand) | staged_ids(stand) + + def orphan_objects(stand: Stand) -> set[str]: """Объекты вложений без строки. Сначала строки, потом объекты: уборщик удаляет объект раньше строки, и убранная между вызовами строка не даёт ложного «объекта без строки».""" rows = attachment_rows(stand) - return stored_ids(stand) - set(rows) + return object_ids(stand) - set(rows) -def ready_without_object(stand: Stand) -> set[str]: - """Готовые вложения без объекта: строки `ready` уборщик не трогает, - поэтому порядок вызовов здесь не важен.""" - return ready_ids(attachment_rows(stand)) - stored_ids(stand) +def accepted_without_staging(stand: Stand) -> set[str]: + """Принятые вложения в работе и готовые без объекта staging: у `failed` + его может не быть по самой причине отказа.""" + accepted = { + item + for item, status in attachment_rows(stand).items() + if status in ("queued", "processing", "ready") + } + return accepted - staged_ids(stand) def new_ids(before: dict[str, str], after: dict[str, str]) -> set[str]: return set(after) - set(before) +def objects_and_rows(stand: Stand) -> tuple[dict[str, str], set[str]]: + """Снимок: строки и объекты вложений обоих префиксов.""" + return attachment_rows(stand), object_ids(stand) + + +def new_objects( + before: tuple[dict[str, str], set[str]], + stand: Stand, +) -> set[str]: + """Объекты, которых не было в снимке, у `id`, которых в нём тоже не было. + Worker параллельно доводит задания прежних тестов: объект конечного ключа + у прежнего `id` — не след новой загрузки.""" + return object_ids(stand) - before[1] - set(before[0]) + + +def job_row(stand: Stand, attachment_id: str) -> dict[str, Any] | None: + """Задание вложения; нет — `None`. Два задания дали бы две строки и + ошибку разбора: задание у вложения одно.""" + output = stand("job", attachment_id) + return json.loads(output) if output else None + + def ready_ids(rows: dict[str, str]) -> set[str]: return {item for item, status in rows.items() if status == "ready"} @@ -609,7 +658,7 @@ def wait_cleaned(stand: Stand, attachment_id: str, *, since: float) -> None: deadline = since + CLEANER_GRACE_S + CLEANER_INTERVAL_S + CLEANUP_SLACK_S while True: rows = attachment_rows(stand) - stored = stored_ids(stand) + stored = object_ids(stand) if attachment_id not in rows and attachment_id not in stored: return if time.monotonic() > deadline: @@ -647,8 +696,8 @@ def assert_invisible( chat: dict[str, Any], attachment_id: str, ) -> None: - """Вложение не в статусе ready: метаданные, байты и ссылка в сообщении - — 404 с тем же `message`, что у неизвестного `id`.""" + """Незавершённая загрузка: метаданные, байты и ссылка в сообщении — 404 + с тем же `message`, что у неизвестного `id`.""" def calls(item: str) -> tuple[httpx.Response, ...]: return ( @@ -687,7 +736,8 @@ def test_upload_with_object_storage_stopped( # уборщик (test_cleaner_survives_outages) (pending,) = new_ids(before, after) assert after[pending] == "pending" - assert ready_ids(after) == ready_ids(before) + # заданий и принятых не прибавилось: новая строка одна и pending + assert job_row(stand, pending) is None # замечание S6 verify attachments: id последней pending — от hook assert stand("last-pending") == pending assert_invisible(api, alice, chat, pending) @@ -710,10 +760,11 @@ def test_rejected_uploads_leave_nothing( yield big[offset : offset + 1024 * 1024] # хотя бы одно готовое вложение: списки hook не пусты случайно - ready = api.upload(alice, chat["id"], images.sample_png()) - before = (attachment_rows(stand), stored_ids(stand)) + ready = api.upload_ready(alice, chat["id"], images.sample_png()) + before = objects_and_rows(stand) assert before[0].get(ready["id"]) == "ready", before[0] assert ready["id"] in before[1], before[1] + assert ready["id"] in staged_ids(stand) rejected = ( (404, upload_raw(api, eve, chat, images.sample_png())), (413, upload_raw(api, alice, chat, big)), @@ -734,7 +785,7 @@ def test_rejected_uploads_leave_nothing( for status, resp in rejected: assert_error(resp, status) assert not new_ids(before[0], attachment_rows(stand)) - assert not stored_ids(stand) - before[1] + assert not new_objects(before, stand) @pytest.mark.spec("attachments", "Сбой записи метаданных") @@ -745,7 +796,7 @@ def test_metadata_insert_failure( chat: dict[str, Any], ) -> None: filename = fault_filename() - before = (attachment_rows(stand), stored_ids(stand)) + before = objects_and_rows(stand) stand("fail-attachments", "insert", filename) try: resp = upload_raw( @@ -760,7 +811,7 @@ def test_metadata_insert_failure( stand("clear-fail-attachments") # строки нет — объект не записывался assert not new_ids(before[0], attachment_rows(stand)) - assert not stored_ids(stand) - before[1] + assert not new_objects(before, stand) class BodyAborted(Exception): @@ -774,7 +825,7 @@ def test_interrupted_body( alice: Actor, chat: dict[str, Any], ) -> None: - before = (attachment_rows(stand), stored_ids(stand)) + before = objects_and_rows(stand) def aborted_body() -> Iterator[bytes]: yield images.PNG_SIGNATURE + bytes(1024 * 1024) @@ -790,14 +841,14 @@ def test_interrupted_body( # случае time.sleep(1) assert not new_ids(before[0], attachment_rows(stand)) - assert not stored_ids(stand) - before[1] + assert not new_objects(before, stand) api.upload(alice, chat["id"], images.sample_png()) -@pytest.mark.spec("attachments", "Фиксация ready не удалась") +@pytest.mark.spec("attachments", "Фиксация задания не удалась") @pytest.mark.spec("storage-consistency", "Свежая загрузка не тронута") @pytest.mark.spec("storage-consistency", "Зависшая загрузка убрана") -def test_ready_failure_compensated( +def test_queued_failure_compensated( api: Api, stand: Stand, alice: Actor, @@ -805,7 +856,7 @@ def test_ready_failure_compensated( ) -> None: filename = fault_filename() before = attachment_rows(stand) - stand("fail-attachments", "ready", filename) + stand("fail-attachments", "queued", filename) try: started = time.monotonic() resp = upload_raw( @@ -822,8 +873,9 @@ def test_ready_failure_compensated( (pending,) = new_ids(before, after) assert after[pending] == "pending" assert stand("last-pending") == pending - # компенсация: объект удалён до ответа 503 - assert pending not in stored_ids(stand) + # компенсация: объект удалён до ответа 503, задания нет + assert pending not in object_ids(stand) + assert job_row(stand, pending) is None assert_invisible(api, alice, chat, pending) # моложе grace строку уборщик не трогает: к половине grace он сделал # около G / 2 / I проходов @@ -863,7 +915,8 @@ def test_killed_between_put_and_ready( started = time.monotonic() thread = threading.Thread(target=upload) thread.start() - # строка pending и объект — до конца задержки перевода в ready + # строка pending и объект staging — до конца задержки перевода в + # queued deadline = started + STALL_S pending = "" while time.monotonic() < deadline: @@ -871,7 +924,7 @@ def test_killed_between_put_and_ready( if ( pending and pending not in before - and pending in stored_ids(stand) + and pending in staged_ids(stand) ): break time.sleep(0.05) @@ -881,10 +934,11 @@ def test_killed_between_put_and_ready( killed = True thread.join(THREAD_CLIENT_TIMEOUT_S) assert not thread.is_alive() - # 201 до клиента не дошёл: перевод в ready ждал в триггере - assert outcome.get("status") != 201, outcome + # 202 до клиента не дошёл: перевод в queued ждал в триггере + assert outcome.get("status") != 202, outcome assert attachment_rows(stand).get(pending) == "pending" - assert pending in stored_ids(stand) + assert pending in staged_ids(stand) + assert job_row(stand, pending) is None finally: client.close() stand("clear-fail-attachments") @@ -896,13 +950,13 @@ def test_killed_between_put_and_ready( @pytest.mark.spec("attachments", "Исход фиксации неизвестен") -def test_ready_commit_outcome_unknown( +def test_queued_commit_outcome_unknown( api: Api, stand: Stand, alice: Actor, chat: dict[str, Any], ) -> None: - """Перевод в ready падает на самом COMMIT (отложенный триггер): API не + """Перевод в queued падает на самом COMMIT (отложенный триггер): API не знает, зафиксировано ли вложение, и объект не трогает (verify W2).""" filename = fault_filename() before = attachment_rows(stand) @@ -922,8 +976,8 @@ def test_ready_commit_outcome_unknown( after = attachment_rows(stand) (pending,) = new_ids(before, after) assert after[pending] == "pending" - # компенсации нет: вложение могло стать ready - assert pending in stored_ids(stand) + # компенсации нет: вложение могло стать queued + assert pending in staged_ids(stand) assert_invisible(api, alice, chat, pending) wait_cleaned(stand, pending, since=started) assert not orphan_objects(stand) @@ -936,11 +990,11 @@ def test_upload_outlives_grace( alice: Actor, chat: dict[str, Any], ) -> None: - """Строка вставлена «на час старше», перевод в ready ждёт в триггере, + """Строка вставлена «на час старше», перевод в queued ждёт в триггере, пока её не уберёт уборщик стенда: загрузка, пережившая grace, без заморозки процесса (verify W3).""" filename = fault_filename() - before = attachment_rows(stand) + before = objects_and_rows(stand) stand("fail-attachments", "outlive", filename) # ожидание в триггере до 4,5 с: срок клиента больше slow = Api(str(api.client.base_url), timeout=THREAD_CLIENT_TIMEOUT_S) @@ -953,13 +1007,13 @@ def test_upload_outlives_grace( images.sample_png(), filename=filename, ) - # не 201 (ready без объекта) и не 500 (дефект ветки) + # не 202 (принято без объекта) и не 500 (дефект ветки) assert_error(resp, 503) finally: stand("clear-fail-attachments") rows = attachment_rows(stand) - assert not new_ids(before, rows), rows - assert not stored_ids(stand) - set(before) + assert not new_ids(before[0], rows), rows + assert not new_objects(before, stand) assert not orphan_objects(stand) @@ -971,7 +1025,7 @@ def test_cleaner_failure_after_object_delete( chat: dict[str, Any], ) -> None: """Уборщик удалил объект, а удаление строки упало (08006), пока загрузка - ждёт перевода в ready: строка помечена до удаления объекта и ready уже + ждёт перевода в queued: строка помечена до удаления объекта и queued уже не станет (verify W1).""" filename = fault_filename() before = attachment_rows(stand) @@ -989,7 +1043,9 @@ def test_cleaner_failure_after_object_delete( assert_error(resp, 503) (pending,) = new_ids(before, attachment_rows(stand)) assert attachment_rows(stand).get(pending) == "pending" - assert not ready_without_object(stand) + assert job_row(stand, pending) is None + assert pending not in staged_ids(stand) + assert not accepted_without_staging(stand) assert_invisible(api, alice, chat, pending) finally: stand("clear-fail-attachments") @@ -997,7 +1053,7 @@ def test_cleaner_failure_after_object_delete( returned = time.monotonic() wait_cleaned(stand, pending, since=returned - CLEANER_GRACE_S) assert not orphan_objects(stand) - assert not ready_without_object(stand) + assert not accepted_without_staging(stand) @pytest.mark.spec("storage-consistency", "S3 недоступен во время уборки") @@ -1010,7 +1066,7 @@ def test_cleaner_survives_outages( chat: dict[str, Any], ) -> None: data = images.sample_png() - ready = api.upload(alice, chat["id"], data) + ready = api.upload_ready(alice, chat["id"], data) with outage(stand, "stop", "s3"): before = attachment_rows(stand) started = time.monotonic() @@ -1031,7 +1087,7 @@ def test_cleaner_survives_outages( f"{time.monotonic() - returned:.1f}s after S3 came back" ) time.sleep(0.5) - assert pending not in stored_ids(stand) + assert pending not in object_ids(stand) assert not orphan_objects(stand) # готовое вложение старше grace на месте meta = assert_ok( @@ -1057,7 +1113,7 @@ def test_object_storage_stopped( chat: dict[str, Any], ) -> None: data = images.sample_png() - attachment = api.upload(alice, chat["id"], data) + attachment = api.upload_ready(alice, chat["id"], data) with outage(stand, "stop", "s3"): resp, elapsed = timed( lambda: api.attachment_content(bob, attachment["id"]), @@ -1118,7 +1174,7 @@ def test_object_storage_paused( chat: dict[str, Any], ) -> None: data = images.sample_png() - attachment = api.upload(alice, chat["id"], data) + attachment = api.upload_ready(alice, chat["id"], data) before = attachment_rows(stand) started = time.monotonic() # срок клиента больше срока вызова S3: ждём ответ API, а не свой обрыв @@ -1272,10 +1328,6 @@ def slow_chunks(data: bytes, *, parts: int, seconds: float) -> Iterator[bytes]: yield data[offset : offset + size] -def objects_and_rows(stand: Stand) -> tuple[dict[str, str], set[str]]: - return attachment_rows(stand), stored_ids(stand) - - @pytest.mark.spec("attachments", "Все места заняты") @pytest.mark.spec("attachments", "Очередь ожидания полна") @pytest.mark.spec("api-conventions", "Лимит одновременных загрузок") @@ -1304,11 +1356,10 @@ def test_upload_slots_busy( assert waited_s >= WAIT_TIMEOUT_S, f"429 after {waited_s:.2f}s" for resp in (busy, waited): assert int(resp.headers["Retry-After"]) >= 1 - attachment = assert_ok(holder, 201, "Attachment") + attachment = assert_accepted(holder) # из трёх загрузок осталась только принятая: у 429 ни строки, ни объекта - rows, stored = objects_and_rows(stand) - assert new_ids(before[0], rows) == {attachment["id"]} - assert stored - before[1] == {attachment["id"]} + assert new_ids(before[0], attachment_rows(stand)) == {attachment["id"]} + assert new_objects(before, stand) == {attachment["id"]} @pytest.mark.spec("attachments", "Отказ раньше очереди") @@ -1355,7 +1406,7 @@ def test_rejections_before_queue( # без ожидания места: ожидающий получил бы его не раньше срока assert elapsed < WAIT_TIMEOUT_S, f"{status} after {elapsed:.2f}s" assert early[1][1].request.headers["Content-Length"] == "31457280" - assert_ok(holder, 201, "Attachment") + assert_accepted(holder) @pytest.mark.spec("attachments", "Ожидание места") @@ -1377,14 +1428,15 @@ def test_upload_waits_for_slot( time.sleep(SETTLE_S) # A заканчивается раньше срока ожидания B holder = finish_holder() - held = assert_ok(holder, 201, "Attachment") + held = assert_accepted(holder) waited_resp, waited_s, _ = waiting.result() - waited = assert_ok(waited_resp, 201, "Attachment") + waited = assert_accepted(waited_resp) assert waited_s < WAIT_TIMEOUT_S + BODY_TIMEOUT_S, waited_s - # метаданные ожидавшей записаны после перевода в ready державшей место: + # метаданные ожидавшей записаны после перевода в queued державшей место: # ожидание прошло до строки pending (граница B уборщика прежняя) assert waited["created_at"] > held["updated_at"], (held, waited) for attachment, data in ((held, first), (waited, second)): + uploads_api.wait_attachment(alice, attachment["id"]) assert_content( uploads_api.attachment_content(alice, attachment["id"]), data, @@ -1410,7 +1462,7 @@ def test_slot_released_after_failures( resp, elapsed = timed( lambda: upload_raw(uploads_api, alice, chat, images.sample_png()), ) - assert_ok(resp, 201, "Attachment") + assert_accepted(resp) assert elapsed < WAIT_TIMEOUT_S, ( f"upload after {after} waited {elapsed:.2f}s for a slot" ) @@ -1472,18 +1524,18 @@ def test_slow_body( ) error = assert_error(late, 400) assert error["message"] == "Upload body was not received in time" - rows, stored = objects_and_rows(stand) - assert not new_ids(before[0], rows) - assert not stored - before[1] + assert not new_ids(before[0], attachment_rows(stand)) + assert not new_objects(before, stand) # мелкие части с паузами, но в срок: тело принято как есть in_time = slow_chunks(data, parts=20, seconds=BODY_TIMEOUT_S / 2) resp, elapsed = timed( lambda: upload_raw(uploads_api, alice, chat, in_time), ) - attachment = assert_ok(resp, 201, "Attachment") + attachment = assert_accepted(resp) assert elapsed < WAIT_TIMEOUT_S + BODY_TIMEOUT_S, elapsed assert attachment["size_bytes"] == len(data) assert attachment["sha256"] == hashlib.sha256(data).hexdigest() + uploads_api.wait_attachment(alice, attachment["id"]) assert_content( uploads_api.attachment_content(alice, attachment["id"]), data, @@ -1528,7 +1580,7 @@ def test_upload_after_idle_s3( chat: dict[str, Any], ) -> None: """Скачивания большого оригинала, простой S3 дольше срока вызова, - затем загрузки — каждая 201, ни одной 503. + затем загрузки — каждая 202, ни одной 503. Раунд: 10 одновременных медленных скачиваний (своё соединение у каждого клиента, барьер, 2 мс на блок 64 KiB) PNG ~4 MiB, простой @@ -1544,7 +1596,7 @@ def test_upload_after_idle_s3( assert_s3_stand() base_url = str(s3_api.client.base_url) original = images.png_noise(1024, 1365, seed=4) - attachment = s3_api.upload( + attachment = s3_api.upload_ready( alice, chat["id"], original, @@ -1574,12 +1626,1432 @@ def test_upload_after_idle_s3( time.sleep(SHORT_S3_TIMEOUT_S + IDLE_EXTRA_S) for upload_number in range(1, IDLE_UPLOADS + 1): resp = upload_raw(s3_api, alice, chat, sample) - assert resp.status_code == 201, describe( + assert resp.status_code == 202, describe( resp, f"round {round_number}, upload {upload_number} after " f"{SHORT_S3_TIMEOUT_S + IDLE_EXTRA_S:.1f}s of S3 idle", ) - assert_ok(resp, 201, "Attachment") + assert_accepted(resp) + + +# --------------------------------------------------------------------------- +# Фоновая обработка, брокер и worker (change async-attachments, design, решение +# 15). Worker стенда: 4 попытки, пауза 5 с, срок попытки 10 с, срок остановки +# 2 с (FAULT_WORKER_*). Перед остановкой worker очередь доводится до пустой: +# задания прежних тестов не считаются в «одно сообщение». Worker и триггеры +# возвращаются в finally, упавшая проверка не ломает следующие +# --------------------------------------------------------------------------- + +WORKER_MAX_ATTEMPTS = int(os.environ.get("FAULT_WORKER_MAX_ATTEMPTS", "4")) +WORKER_RETRY_DELAY_S = float(os.environ.get("FAULT_WORKER_RETRY_DELAY_S", "5")) +# [worker] concurrency по умолчанию: стенд отказов её не меняет +WORKER_CONCURRENCY = 2 +# [broker] publish_timeout_seconds и запас на шаги с БД вокруг публикации +PUBLISH_TIMEOUT_S = 2 +BROKER_SLACK_S = 1 +# отказ брокера не держит health: быстрее секунды, как у S3 +BROKER_HEALTH_S = 1 +# срок ожидания итога задания: все попытки и паузы с запасом +JOB_WAIT_S = 60 +JOBS_SCHEMA_PATH = ( + Path(__file__).resolve().parents[1] / "contracts" / "jobs.schema.json" +) +# срок «Stopped worker» по контракту остановки контейнера +WORKER_STOP_MAX_S = 10 +THUMBNAIL_VARIANTS = (None, "original", "thumbnail") + + +def queue_state(stand: Stand) -> dict[str, Any]: + state = json.loads(stand("queue-state")) + assert state is not None, "job queue does not exist" + return state + + +def wait_queue_empty(stand: Stand, *, timeout: float = 90) -> None: + """В очереди не осталось сообщений, в том числе неподтверждённых.""" + deadline = time.monotonic() + timeout + while True: + state = queue_state(stand) + if state["messages"] == 0: + return + assert time.monotonic() < deadline, f"queue is not empty: {state}" + time.sleep(0.5) + + +@contextmanager +def worker_stopped(stand: Stand) -> Iterator[None]: + """Worker остановлен при пустой очереди; в `finally` запускается.""" + wait_queue_empty(stand) + with outage(stand, "stop", "worker"): + yield + + +def worker_records(stand: Stand) -> list[dict[str, Any]]: + """Записи журнала worker за все его запуски.""" + return [ + json.loads(line) + for line in stand("worker-log").splitlines() + if line.startswith("{") + ] + + +def wait_worker_record( + stand: Stand, + event: str, + *, + timeout: float = 30, + skip: int = 0, + **fields: Any, +) -> dict[str, Any]: + """Запись журнала worker с этими полями после первых `skip` записей.""" + deadline = time.monotonic() + timeout + while True: + for record in worker_records(stand)[skip:]: + if record.get("event") == event and all( + record.get(name) == value for name, value in fields.items() + ): + return record + assert time.monotonic() < deadline, ( + f"no worker record {event!r} with {fields} in {timeout} s" + ) + time.sleep(0.3) + + +def job_body( + job_id: str, + attachment_id: str, + *, + attempt: int = 1, +) -> bytes: + """Сообщение задания по `contracts/jobs.schema.json`.""" + return json.dumps( + { + "schema_version": 1, + "job_id": job_id, + "type": "attachment.process.v1", + "attachment_id": attachment_id, + "pipeline_version": 1, + "attempt": attempt, + "created_at": "2026-10-31T12:00:00.000000Z", + }, + ).encode() + + +def wait_job( + stand: Stand, + attachment_id: str, + *, + state: str, + attempt: int, + timeout: float = 20, +) -> dict[str, Any]: + """Задание в этом состоянии с этим или большим числом попыток.""" + deadline = time.monotonic() + timeout + while True: + job = job_row(stand, attachment_id) + if job and job["state"] == state and job["attempt"] >= attempt: + return job + assert time.monotonic() < deadline, ( + f"job of {attachment_id} is not {state} with attempt >= " + f"{attempt}: {job}" + ) + time.sleep(0.2) + + +def thumbnail_size(data: bytes) -> tuple[int, int]: + """Настоящие размеры JPEG: файл открывается декодером.""" + from PIL import Image # noqa: PLC0415 + + with Image.open(io.BytesIO(data)) as image: + image.load() + assert image.format == "JPEG", image.format + return image.size + + +def assert_one_thumbnail( + api: Api, + stand: Stand, + actor: Actor, + meta: dict[str, Any], +) -> dict[str, Any]: + """Один `thumbnail` в метаданных и один объект варианта с его SHA-256.""" + assert meta["status"] == "ready", meta + (variant,) = meta["variants"] + assert variant["name"] == "thumbnail", variant + assert stand("variant-object-count", meta["id"]) == "1" + assert_variant_content( + api.attachment_content(actor, meta["id"], variant="thumbnail"), + variant, + ) + return variant + + +def assert_not_ready_content( + api: Api, + actor: Actor, + attachment_id: str, +) -> None: + """Любое скачивание вложения не в `ready` — 409.""" + for variant in THUMBNAIL_VARIANTS: + assert_error( + api.attachment_content(actor, attachment_id, variant=variant), + 409, + ) + + +def staging_key(attachment_id: str) -> str: + return f"{FAULT_DATABASE}/staging/{attachment_id}/original" + + +@pytest.mark.spec("attachment-processing", "Принятое вложение в очереди") +def test_queued_while_worker_stopped( + api: Api, + stand: Stand, + alice: Actor, + chat: dict[str, Any], +) -> None: + with worker_stopped(stand): + accepted = api.upload(alice, chat["id"], images.sample_png()) + time.sleep(3) + meta = assert_ok( + api.attachment_meta(alice, accepted["id"]), + 200, + "Attachment", + ) + assert meta == accepted + api.wait_attachment(alice, accepted["id"]) + + +@pytest.mark.spec("attachment-processing", "Обработка видна в API") +def test_processing_visible( + api: Api, + stand: Stand, + alice: Actor, + chat: dict[str, Any], +) -> None: + data = images.sample_png() + filename = fault_filename() + stand("fail-attachments", "ready-stall", filename) + try: + accepted = api.upload(alice, chat["id"], data, filename=filename) + api.wait_attachment( + alice, + accepted["id"], + status="processing", + timeout=JOB_WAIT_S, + ) + assert_error(api.attachment_content(alice, accepted["id"]), 409) + api.wait_attachment(alice, accepted["id"], timeout=JOB_WAIT_S) + finally: + stand("clear-fail-attachments") + assert_content( + api.attachment_content(alice, accepted["id"]), + data, + "image/png", + ) + + +@pytest.mark.spec("attachment-processing", "Готовое вложение не откатывается") +@pytest.mark.spec("attachment-processing", "Повторная доставка готового") +def test_redelivery_of_ready_is_noop( + api: Api, + stand: Stand, + alice: Actor, + chat: dict[str, Any], +) -> None: + meta = api.upload_ready(alice, chat["id"], images.sample_png()) + job = job_row(stand, meta["id"]) + assert job is not None + wait_queue_empty(stand) + seen = len(worker_records(stand)) + stand("publish-job", stdin=job_body(job["id"], meta["id"])) + wait_worker_record( + stand, + "Skipped job message", + skip=seen, + job_id=job["id"], + reason="finished", + ) + wait_queue_empty(stand) + assert ( + assert_ok(api.attachment_meta(alice, meta["id"]), 200, "Attachment") + == meta + ) + assert job_row(stand, meta["id"]) == job + assert_one_thumbnail(api, stand, alice, meta) + + +@pytest.mark.spec("attachment-processing", "Что сохранено к ответу 202") +def test_durable_state_at_202( + api: Api, + stand: Stand, + alice: Actor, + chat: dict[str, Any], +) -> None: + with worker_stopped(stand): + accepted = api.upload(alice, chat["id"], images.sample_png()) + attachment_id = accepted["id"] + assert attachment_id in staged_ids(stand) + assert attachment_id not in stored_ids(stand) + assert attachment_rows(stand)[attachment_id] == "queued" + job = job_row(stand, attachment_id) + assert job is not None + assert (job["state"], job["attempt"]) == ("queued", 0), job + assert job["published_at"] is not None, job + assert queue_state(stand)["messages"] == 1 + api.wait_attachment(alice, attachment_id) + + +@pytest.mark.spec("attachment-processing", "Временная ошибка") +@pytest.mark.spec("attachment-processing", "Повторы под одним заданием") +def test_transient_error_retried( + api: Api, + stand: Stand, + alice: Actor, + chat: dict[str, Any], +) -> None: + """Сначала S3 остановлен и возвращается за ~8 с: попыток больше одной. + Затем S3 заморожен на первую попытку и размораживается в паузе между + попытками: ровно две, задание то же.""" + data = images.sample_png() + with worker_stopped(stand): + stopped = api.upload(alice, chat["id"], data) + first = job_row(stand, stopped["id"]) + with outage(stand, "stop", "s3"): + stand("start", "worker") + wait_job(stand, stopped["id"], state="queued", attempt=1) + meta = api.wait_attachment(alice, stopped["id"], timeout=JOB_WAIT_S) + assert_one_thumbnail(api, stand, alice, meta) + job = job_row(stand, stopped["id"]) + assert job is not None and first is not None + assert job["id"] == first["id"], (job, first) + assert job["attempt"] > 1, job + assert job["state"] == "succeeded", job + + with worker_stopped(stand): + paused = api.upload(alice, chat["id"], data) + first = job_row(stand, paused["id"]) + with outage(stand, "pause", "s3"): + stand("start", "worker") + # срок вызова S3 5 с: первая попытка заканчивается отказом S3 + wait_job(stand, paused["id"], state="queued", attempt=1) + meta = api.wait_attachment(alice, paused["id"], timeout=JOB_WAIT_S) + job = job_row(stand, paused["id"]) + assert job is not None and first is not None + assert job["id"] == first["id"], (job, first) + assert job["attempt"] == 2, job + assert_one_thumbnail(api, stand, alice, meta) + + +@pytest.mark.spec("attachment-processing", "Сообщение по схеме") +def test_job_message_matches_schema( + api: Api, + stand: Stand, + alice: Actor, + chat: dict[str, Any], +) -> None: + schema = json.loads(JOBS_SCHEMA_PATH.read_text(encoding="utf-8")) + filename = fault_filename() + with worker_stopped(stand): + accepted = api.upload( + alice, + chat["id"], + images.sample_png(), + filename=filename, + ) + peeked = json.loads(stand("peek-job")) + text = peeked["body"] + body = json.loads(text) + errors = list( + Draft202012Validator( + schema, + format_checker=FormatChecker(), + ).iter_errors(body), + ) + assert not errors, [error.message for error in errors] + datetime.fromisoformat(body["created_at"]) + job = job_row(stand, accepted["id"]) + assert job is not None + assert body["attachment_id"] == accepted["id"] + assert body["job_id"] == job["id"] + assert body["attempt"] == 1 + # ни имени файла, ни ключей, ни адресов, ни учётных данных + lowered = text.lower() + for word in ( + filename.lower(), + os.environ.get("FAULT_S3_BUCKET", "attachments").lower(), + f"{FAULT_DATABASE}/", + "staging", + "original", + "http", + "password", + "secret", + ): + assert word not in lowered, f"{word!r} in the job message" + api.wait_attachment(alice, accepted["id"]) + + +@pytest.mark.spec("message-broker", "Очередь и сообщения устойчивы") +def test_queue_durable( + api: Api, + stand: Stand, + alice: Actor, + chat: dict[str, Any], +) -> None: + with worker_stopped(stand): + accepted = api.upload(alice, chat["id"], images.sample_png()) + state = queue_state(stand) + assert state["durable"] is True, state + assert state["messages"] == 1, state + peeked = json.loads(stand("peek-job")) + assert peeked["delivery_mode"] == 2, peeked + # прочитанное без подтверждения вернулось в очередь + state = queue_state(stand) + assert (state["messages"], state["messages_ready"]) == (1, 1), state + api.wait_attachment(alice, accepted["id"]) + + +@pytest.mark.spec("attachment-processing", "Сообщение не по схеме") +def test_malformed_message_dropped( + api: Api, + stand: Stand, + alice: Actor, + chat: dict[str, Any], +) -> None: + marker = uuid.uuid4().hex + wait_queue_empty(stand) + seen = len(worker_records(stand)) + stand( + "publish-job", + stdin=json.dumps({"schema_version": 1, "note": marker}).encode(), + ) + record = wait_worker_record( + stand, + "Dropped malformed job message", + skip=seen, + ) + assert record["level"] == "error", record + # содержимое сообщения в журнал не попало + assert marker not in stand("worker-log") + wait_queue_empty(stand) + api.upload_ready(alice, chat["id"], images.sample_png()) + + +@pytest.mark.spec("attachment-processing", "Неизвестное задание") +def test_unknown_job_acked(stand: Stand) -> None: + job_id, attachment_id = str(uuid.uuid4()), str(uuid.uuid4()) + wait_queue_empty(stand) + before = objects_and_rows(stand) + seen = len(worker_records(stand)) + stand("publish-job", stdin=job_body(job_id, attachment_id)) + wait_worker_record( + stand, + "Skipped job message", + skip=seen, + job_id=job_id, + reason="unknown", + ) + wait_queue_empty(stand) + assert not new_ids(before[0], attachment_rows(stand)) + assert not new_objects(before, stand) + + +@pytest.mark.spec("attachment-processing", "Worker убит посреди обработки") +def test_worker_killed_during_processing( + api: Api, + stand: Stand, + alice: Actor, + chat: dict[str, Any], +) -> None: + filename = fault_filename() + wait_queue_empty(stand) + stand("fail-attachments", "ready-stall", filename) + try: + accepted = api.upload( + alice, + chat["id"], + images.sample_png(), + filename=filename, + ) + api.wait_attachment( + alice, + accepted["id"], + status="processing", + timeout=JOB_WAIT_S, + ) + stand("kill", "worker") + finally: + stand("clear-fail-attachments") + stand("start", "worker") + meta = api.wait_attachment(alice, accepted["id"], timeout=JOB_WAIT_S) + assert_one_thumbnail(api, stand, alice, meta) + job = job_row(stand, accepted["id"]) + assert job is not None + assert job["attempt"] == 2, job + wait_queue_empty(stand) + + +@pytest.mark.spec("attachment-processing", "Дубль во время обработки") +def test_duplicate_during_processing( + api: Api, + stand: Stand, + alice: Actor, + chat: dict[str, Any], +) -> None: + """Две ветки дубля. S3 заморожен, попытка ждёт его без блокировок БД: дубль + видит живую попытку («busy») и возвращается в очередь. Фиксация ждёт в + триггере и держит строку задания: дубль дожидается её и видит итог + («finished»), вторая попытка не начинается.""" + with worker_stopped(stand): + live = api.upload(alice, chat["id"], images.sample_png()) + job = job_row(stand, live["id"]) + assert job is not None + # оба сообщения в очереди: prefetch выдаёт их разом, пока попытка идёт + stand("publish-job", stdin=job_body(job["id"], live["id"])) + seen = len(worker_records(stand)) + with outage(stand, "pause", "s3"): + stand("start", "worker") + wait_worker_record( + stand, + "Skipped job message", + skip=seen, + job_id=job["id"], + reason="busy", + ) + meta = api.wait_attachment(alice, live["id"], timeout=JOB_WAIT_S) + wait_queue_empty(stand) + assert_one_thumbnail(api, stand, alice, meta) + + filename = fault_filename() + seen = len(worker_records(stand)) + stand("fail-attachments", "ready-stall", filename) + try: + accepted = api.upload( + alice, + chat["id"], + images.sample_png(), + filename=filename, + ) + api.wait_attachment( + alice, + accepted["id"], + status="processing", + timeout=JOB_WAIT_S, + ) + job = job_row(stand, accepted["id"]) + assert job is not None + stand("publish-job", stdin=job_body(job["id"], accepted["id"])) + wait_worker_record( + stand, + "Skipped job message", + skip=seen, + job_id=job["id"], + reason="finished", + ) + meta = api.wait_attachment(alice, accepted["id"], timeout=JOB_WAIT_S) + finally: + stand("clear-fail-attachments") + wait_queue_empty(stand) + assert_one_thumbnail(api, stand, alice, meta) + done = job_row(stand, accepted["id"]) + assert done is not None + assert done["attempt"] == 1, done + + +@pytest.mark.spec("attachment-processing", "Оригинал неизменен") +def test_original_published_unchanged( + api: Api, + stand: Stand, + alice: Actor, + chat: dict[str, Any], +) -> None: + data = images.png_noise(64, 48, seed=23) + meta = api.upload_ready(alice, chat["id"], data) + assert_content( + api.attachment_content(alice, meta["id"]), + data, + "image/png", + ) + assert meta["sha256"] == hashlib.sha256(data).hexdigest() + assert meta["id"] in stored_ids(stand) + assert meta["id"] in staged_ids(stand) + + +@pytest.mark.spec("attachment-processing", "Испорченный staging") +def test_staging_corrupted( + api: Api, + stand: Stand, + alice: Actor, + chat: dict[str, Any], +) -> None: + """Те же размер и другие байты — и другой размер: обе ветки сверки.""" + data = images.png_noise(64, 48, seed=29) + with worker_stopped(stand): + same_size = api.upload(alice, chat["id"], data) + other_size = api.upload(alice, chat["id"], data) + put_object( + stand, + staging_key(same_size["id"]), + same_size_bytes(data, seed=29), + ) + put_object(stand, staging_key(other_size["id"]), data + b"\0") + for accepted in (same_size, other_size): + meta = api.wait_attachment( + alice, + accepted["id"], + status="failed", + timeout=JOB_WAIT_S, + ) + assert meta["error_code"] == "processing_failed", meta + assert meta["variants"] == [], meta + job = job_row(stand, accepted["id"]) + assert job is not None + assert job["attempt"] == 1, job + assert job["last_error_code"] == "source_corrupted", job + assert accepted["id"] not in stored_ids(stand) + + +@pytest.mark.spec("attachment-processing", "Нет объекта staging") +def test_staging_missing( + api: Api, + stand: Stand, + alice: Actor, + chat: dict[str, Any], +) -> None: + with worker_stopped(stand): + accepted = api.upload(alice, chat["id"], images.sample_png()) + stand("delete-object", staging_key(accepted["id"])) + meta = api.wait_attachment( + alice, + accepted["id"], + status="failed", + timeout=JOB_WAIT_S, + ) + assert meta["error_code"] == "processing_failed", meta + job = job_row(stand, accepted["id"]) + assert job is not None + assert job["attempt"] == 1, job + assert job["last_error_code"] == "source_missing", job + + +@pytest.mark.spec("attachment-processing", "Изображение в лимите пикселей") +def test_max_pixels_fit_worker_memory( + base_url: str, + stand: Stand, + alice: Actor, + chat: dict[str, Any], +) -> None: + """Столько PNG RGBA 8000 × 5000, сколько заданий worker обрабатывает + одновременно: они берутся разом, и контейнер не завершён из-за памяти.""" + data = images.png_rgba_large() + before = json.loads(stand("worker-state")) + # срок клиента: тело на 40 млн пикселей проверяется дольше 5 с по умолчанию + with Api(base_url, timeout=THREAD_CLIENT_TIMEOUT_S) as slow: + with worker_stopped(stand): + accepted = [ + slow.upload(alice, chat["id"], data) + for _ in range(WORKER_CONCURRENCY) + ] + for item in accepted: + meta = slow.wait_attachment(alice, item["id"], timeout=JOB_WAIT_S) + (variant,) = meta["variants"] + assert (variant["width"], variant["height"]) == (256, 160), variant + content = assert_variant_content( + slow.attachment_content( + alice, + item["id"], + variant="thumbnail", + ), + variant, + ) + assert thumbnail_size(content) == (256, 160) + state = json.loads(stand("worker-state")) + assert state["running"] is True, state + assert state["oom_killed"] is False, state + assert state["restart_count"] == before["restart_count"], state + + +@pytest.mark.spec("attachment-processing", "Повтор после записи объектов") +@pytest.mark.spec("attachments", "Фиксация ready не удалась") +def test_ready_failure_retried( + api: Api, + stand: Stand, + alice: Actor, + chat: dict[str, Any], +) -> None: + """Объекты записаны, фиксация падает отказом БД (08006): попытка уходит в + очередь; пока триггер стоит, вложение не готово. Триггер снимается в + паузе перед следующей доставкой.""" + filename = fault_filename() + wait_queue_empty(stand) + seen = len(worker_records(stand)) + stand("fail-attachments", "ready-fail", filename) + try: + accepted = api.upload( + alice, + chat["id"], + images.sample_png(), + filename=filename, + ) + job = job_row(stand, accepted["id"]) + assert job is not None + wait_worker_record( + stand, + "Job waits for database", + skip=seen, + job_id=job["id"], + ) + assert stand("variant-object-count", accepted["id"]) == "1" + assert accepted["id"] in stored_ids(stand) + meta = assert_ok( + api.attachment_meta(alice, accepted["id"]), + 200, + "Attachment", + ) + assert meta["status"] in ("queued", "processing"), meta + assert_not_ready_content(api, alice, accepted["id"]) + finally: + stand("clear-fail-attachments") + meta = api.wait_attachment(alice, accepted["id"], timeout=JOB_WAIT_S) + assert_one_thumbnail(api, stand, alice, meta) + done = job_row(stand, accepted["id"]) + assert done is not None + assert done["id"] == job["id"], done + assert done["attempt"] >= 2, done + + +@pytest.mark.spec("attachment-processing", "Состояние между попытками") +def test_queued_between_attempts( + api: Api, + stand: Stand, + alice: Actor, + chat: dict[str, Any], +) -> None: + with worker_stopped(stand): + accepted = api.upload(alice, chat["id"], images.sample_png()) + with outage(stand, "stop", "s3"): + stand("start", "worker") + job = wait_job(stand, accepted["id"], state="queued", attempt=1) + assert job["last_error_code"] == "storage_unavailable", job + assert job["next_attempt_at"] is not None, job + meta = assert_ok( + api.attachment_meta(alice, accepted["id"]), + 200, + "Attachment", + ) + assert meta["status"] == "queued", meta + assert meta["error_code"] is None, meta + api.wait_attachment(alice, accepted["id"], timeout=JOB_WAIT_S) + + +@pytest.mark.spec("attachment-processing", "Попытки исчерпаны") +def test_attempts_exhausted( + api: Api, + stand: Stand, + alice: Actor, + chat: dict[str, Any], +) -> None: + with worker_stopped(stand): + accepted = api.upload(alice, chat["id"], images.sample_png()) + with outage(stand, "stop", "s3"): + stand("start", "worker") + meta = api.wait_attachment( + alice, + accepted["id"], + status="failed", + timeout=JOB_WAIT_S, + ) + assert meta["error_code"] == "retry_exhausted", meta + job = job_row(stand, accepted["id"]) + assert job is not None + assert job["attempt"] == WORKER_MAX_ATTEMPTS, job + assert job["state"] == "failed", job + wait_queue_empty(stand) + # S3 вернулся: итог окончателен + time.sleep(WORKER_RETRY_DELAY_S) + after = assert_ok( + api.attachment_meta(alice, accepted["id"]), + 200, + "Attachment", + ) + assert after == meta + assert job_row(stand, accepted["id"]) == job + + +@pytest.mark.spec( + "attachment-processing", + "PostgreSQL недоступен при обработке", +) +def test_database_outage_during_processing( + api: Api, + stand: Stand, + alice: Actor, + chat: dict[str, Any], +) -> None: + before = json.loads(stand("worker-state")) + with worker_stopped(stand): + accepted = api.upload(alice, chat["id"], images.sample_png()) + job = job_row(stand, accepted["id"]) + assert job is not None + seen = len(worker_records(stand)) + with outage(stand, "stop", "postgres"): + stand("start", "worker") + # журнал называет отказ, задание ждёт в очереди + wait_worker_record(stand, "Job waits for database", skip=seen) + meta = api.wait_attachment(alice, accepted["id"], timeout=JOB_WAIT_S) + assert_one_thumbnail(api, stand, alice, meta) + wait_queue_empty(stand) + done = job_row(stand, accepted["id"]) + assert done is not None + # попытки на отказе БД не считаются + assert done["attempt"] == 1, done + state = json.loads(stand("worker-state")) + assert state["running"] is True, state + assert state["restart_count"] == before["restart_count"], state + + +@pytest.mark.spec("attachment-processing", "Изображение не декодируется") +def test_undecodable_becomes_failed( + api: Api, + stand: Stand, + alice: Actor, + chat: dict[str, Any], +) -> None: + accepted = api.upload( + alice, + chat["id"], + images.jpeg_precision_12(), + content_type="image/jpeg", + filename="image.jpg", + ) + meta = api.wait_attachment( + alice, + accepted["id"], + status="failed", + timeout=JOB_WAIT_S, + ) + assert meta["error_code"] == "invalid_image", meta + assert meta["variants"] == [], meta + job = job_row(stand, accepted["id"]) + assert job is not None + assert job["attempt"] == 1, job + assert job["last_error_code"] == "undecodable", job + assert_error(api.attachment_content(alice, accepted["id"]), 409) + + +@pytest.mark.spec("attachment-processing", "Worker недоступен") +def test_worker_down_api_serves( + api: Api, + stand: Stand, + alice: Actor, + bob: Actor, + chat: dict[str, Any], +) -> None: + with worker_stopped(stand): + accepted = api.upload(alice, chat["id"], images.sample_png()) + assert accepted["status"] == "queued" + message = api.send_message(alice, chat["id"], "текст без worker") + history = api.all_messages(bob, chat["id"]) + assert [item["id"] for item in history] == [message["id"]] + assert_ok(api.request("GET", "/health/ready"), 200, "Health") + api.wait_attachment(alice, accepted["id"]) + + +@pytest.mark.spec("attachment-processing", "Ограниченная конкуренция") +def test_concurrency_bounded( + api: Api, + stand: Stand, + alice: Actor, + chat: dict[str, Any], +) -> None: + """Фиксация каждого задания ждёт 4 с в триггере: заданий больше, чем + мест, и видно, сколько worker держит разом.""" + filename = fault_filename() + total = WORKER_CONCURRENCY + 3 + stand("fail-attachments", "ready-stall", filename) + try: + with worker_stopped(stand): + ids = [ + api.upload( + alice, + chat["id"], + images.sample_png(), + filename=filename, + )["id"] + for _ in range(total) + ] + api.wait_attachment( + alice, + ids[0], + status="processing", + timeout=JOB_WAIT_S, + ) + most = 0 + for _ in range(4): + rows = attachment_rows(stand) + statuses = [rows[item] for item in ids] + busy = statuses.count("processing") + most = max(most, busy) + assert busy <= WORKER_CONCURRENCY, statuses + assert ( + statuses.count("queued") + + busy + + statuses.count( + "ready", + ) + == total + ), statuses + state = queue_state(stand) + assert state["messages_unacknowledged"] <= WORKER_CONCURRENCY, ( + state + ) + time.sleep(0.3) + assert most == WORKER_CONCURRENCY, most + for item in ids: + api.wait_attachment(alice, item, timeout=JOB_WAIT_S) + finally: + stand("clear-fail-attachments") + wait_queue_empty(stand) + + +@pytest.mark.spec("attachment-processing", "Реплика API убита после ответа") +def test_api_killed_after_202( + api: Api, + stand: Stand, + alice: Actor, + chat: dict[str, Any], +) -> None: + accepted = api.upload(alice, chat["id"], images.sample_png()) + stand("kill-api") + try: + # реплики нет, а работа идёт: итог — от worker + wait_job( + stand, + accepted["id"], + state="succeeded", + attempt=1, + timeout=JOB_WAIT_S, + ) + finally: + stand("start-api") + meta = api.wait_attachment(alice, accepted["id"]) + assert_one_thumbnail(api, stand, alice, meta) + + +@pytest.mark.spec("attachment-processing", "Рестарт брокера с volume") +def test_broker_restart_keeps_job( + api: Api, + stand: Stand, + alice: Actor, + chat: dict[str, Any], +) -> None: + with worker_stopped(stand): + accepted = api.upload(alice, chat["id"], images.sample_png()) + with outage(stand, "stop", "rabbitmq"): + pass + assert queue_state(stand)["messages"] == 1 + api.wait_attachment(alice, accepted["id"], timeout=JOB_WAIT_S) + + +@pytest.mark.spec("attachment-processing", "Принудительное завершение брокера") +@pytest.mark.spec("message-broker", "Подтверждённые сообщения после KILL") +def test_broker_kill_keeps_confirmed( + api: Api, + stand: Stand, + alice: Actor, + chat: dict[str, Any], +) -> None: + confirmed = 5 + with worker_stopped(stand): + accepted = [ + api.upload(alice, chat["id"], images.sample_png()) + for _ in range(confirmed) + ] + with outage(stand, "kill", "rabbitmq"): + pass + assert queue_state(stand)["messages"] == confirmed + for item in accepted: + api.wait_attachment(alice, item["id"], timeout=JOB_WAIT_S) + + +@pytest.mark.spec("attachment-processing", "Сценарий защиты") +def test_defense_scenario( + api: Api, + stand: Stand, + alice: Actor, + chat: dict[str, Any], +) -> None: + data = images.sample_png() + with worker_stopped(stand): + accepted = api.upload(alice, chat["id"], data) + attachment_id = accepted["id"] + message = api.send_message( + alice, + chat["id"], + "", + attachment_ids=[attachment_id], + ) + assert_error(api.attachment_content(alice, attachment_id), 409) + text = api.send_message(alice, chat["id"], "текст при очереди") + with outage(stand, "stop", "rabbitmq"): + stand("kill-api") + stand("start-api") + meta = api.wait_attachment(alice, attachment_id, timeout=JOB_WAIT_S) + assert meta["id"] == attachment_id + assert_content( + api.attachment_content(alice, attachment_id), + data, + "image/png", + ) + variant = assert_one_thumbnail(api, stand, alice, meta) + content = api.attachment_content(alice, attachment_id, variant="thumbnail") + assert thumbnail_size(content.content) == ( + variant["width"], + variant["height"], + ) + history = { + item["id"]: item for item in api.all_messages(alice, chat["id"]) + } + assert history[message["id"]]["attachment_ids"] == [attachment_id] + assert text["id"] in history + + +@pytest.mark.spec("message-broker", "Брокер остановлен при загрузке") +@pytest.mark.spec("message-broker", "Брокер вернулся") +@pytest.mark.spec("attachments", "Брокер не подтвердил задание") +@pytest.mark.spec( + "storage-consistency", + "Загрузка без подтверждения брокера убрана", +) +def test_upload_with_broker_stopped( + api: Api, + stand: Stand, + alice: Actor, + chat: dict[str, Any], +) -> None: + data = images.sample_png() + ready = api.upload_ready(alice, chat["id"], data) + before = attachment_rows(stand) + started = time.monotonic() + with outage(stand, "stop", "rabbitmq"): + resp, elapsed = timed(lambda: upload_raw(api, alice, chat, data)) + assert_error(resp, 503) + assert elapsed < PUBLISH_TIMEOUT_S + BROKER_SLACK_S, elapsed + after = attachment_rows(stand) + (pending,) = new_ids(before, after) + assert after[pending] == "pending" + assert job_row(stand, pending) is None + assert pending in staged_ids(stand) + assert_invisible(api, alice, chat, pending) + # обязательный путь без брокера работает + api.send_message(alice, chat["id"], "текст без брокера") + assert ( + assert_ok( + api.attachment_meta(alice, ready["id"]), + 200, + "Attachment", + ) + == ready + ) + assert_content( + api.attachment_content(alice, ready["id"]), + data, + "image/png", + ) + # реплика не перезапускалась: следующая загрузка проходит + api.upload_ready(alice, chat["id"], data) + wait_cleaned(stand, pending, since=started) + assert job_row(stand, pending) is None + + +@pytest.mark.spec("message-broker", "Брокер завис") +def test_upload_with_broker_paused( + base_url: str, + api: Api, + stand: Stand, + alice: Actor, + chat: dict[str, Any], +) -> None: + """Соединение издателя живо: публикация уходит в заморозку и кончается + сроком, а исход неизвестен. Сообщение, дошедшее после разморозки, worker + подтверждает без эффекта.""" + data = images.sample_png() + api.upload_ready(alice, chat["id"], data) + wait_queue_empty(stand) + before = attachment_rows(stand) + slow = Api(base_url, timeout=THREAD_CLIENT_TIMEOUT_S) + with slow, outage(stand, "pause", "rabbitmq"): + resp, elapsed = timed(lambda: upload_raw(slow, alice, chat, data)) + assert_error(resp, 503) + assert elapsed < PUBLISH_TIMEOUT_S + BROKER_SLACK_S, elapsed + (pending,) = new_ids(before, attachment_rows(stand)) + wait_queue_empty(stand) + assert job_row(stand, pending) is None + assert stand("variant-object-count", pending) == "0" + assert pending not in stored_ids(stand) + assert_invisible(api, alice, chat, pending) + # брокер вернулся: приём снова работает + api.upload_ready(alice, chat["id"], data) + + +@pytest.mark.spec("message-broker", "Очередь удалена") +def test_queue_deleted( + api: Api, + stand: Stand, + alice: Actor, + chat: dict[str, Any], +) -> None: + data = images.sample_png() + # соединение издателя живо: его канал очередь больше не найдёт + api.upload_ready(alice, chat["id"], data) + with worker_stopped(stand): + stand("delete-queue") + assert json.loads(stand("queue-state")) is None + assert_error(upload_raw(api, alice, chat, data), 503) + accepted = api.upload(alice, chat["id"], data) + state = queue_state(stand) + assert (state["durable"], state["messages"]) == (True, 1), state + api.wait_attachment(alice, accepted["id"], timeout=JOB_WAIT_S) + + +@pytest.mark.spec("message-broker", "Пересоздание контейнера") +def test_broker_recreated( + api: Api, + stand: Stand, + alice: Actor, + chat: dict[str, Any], +) -> None: + confirmed = 2 + with worker_stopped(stand): + accepted = [ + api.upload(alice, chat["id"], images.sample_png()) + for _ in range(confirmed) + ] + stand("recreate", "rabbitmq") + state = queue_state(stand) + assert (state["durable"], state["messages"]) == (True, confirmed), ( + state + ) + for item in accepted: + api.wait_attachment(alice, item["id"], timeout=JOB_WAIT_S) + + +@pytest.mark.spec("message-broker", "Старт без брокера") +def test_start_without_broker( + api: Api, + stand: Stand, + alice: Actor, + chat: dict[str, Any], +) -> None: + with worker_stopped(stand), outage(stand, "stop", "rabbitmq"): + seen = len(worker_records(stand)) + stand("kill-api") + stand("start-api") + stand("start", "worker") + # реплика готова и обслуживает текст + assert_ok(api.request("GET", "/health/ready"), 200, "Health") + api.send_message(alice, chat["id"], "текст при старте без брокера") + # worker называет отказ и не завершается + wait_worker_record(stand, "Broker is unavailable", skip=seen) + state = json.loads(stand("worker-state")) + assert state["running"] is True, state + # брокер запущен, ни реплика, ни worker не перезапускались + api.upload_ready(alice, chat["id"], images.sample_png()) + + +@pytest.mark.spec("message-broker", "Рестарт брокера при работающем worker") +def test_worker_survives_broker_restart( + api: Api, + stand: Stand, + alice: Actor, + chat: dict[str, Any], +) -> None: + before = json.loads(stand("worker-state")) + assert before["running"] is True, before + with outage(stand, "stop", "rabbitmq"): + pass + api.upload_ready(alice, chat["id"], images.sample_png()) + state = json.loads(stand("worker-state")) + assert state["running"] is True, state + assert state["restart_count"] == before["restart_count"], state + + +@pytest.mark.spec("attachments", "Скачивание до готовности") +def test_content_before_ready( + api: Api, + stand: Stand, + alice: Actor, + chat: dict[str, Any], +) -> None: + """Каждое скачивание вложения в `queued`, `processing` и `failed` — 409.""" + filename = fault_filename() + stand("fail-attachments", "ready-stall", filename) + try: + with worker_stopped(stand): + accepted = api.upload( + alice, + chat["id"], + images.sample_png(), + filename=filename, + ) + assert_not_ready_content(api, alice, accepted["id"]) + api.wait_attachment( + alice, + accepted["id"], + status="processing", + timeout=JOB_WAIT_S, + ) + assert_not_ready_content(api, alice, accepted["id"]) + api.wait_attachment(alice, accepted["id"], timeout=JOB_WAIT_S) + finally: + stand("clear-fail-attachments") + failed = api.upload( + alice, + chat["id"], + images.jpeg_precision_12(), + content_type="image/jpeg", + filename="image.jpg", + ) + api.wait_attachment( + alice, + failed["id"], + status="failed", + timeout=JOB_WAIT_S, + ) + assert_not_ready_content(api, alice, failed["id"]) + + +@pytest.mark.spec("messages", "Вложение в обработке") +def test_message_with_queued_attachment( + api: Api, + stand: Stand, + alice: Actor, + bob: Actor, + chat: dict[str, Any], +) -> None: + with worker_stopped(stand): + accepted = api.upload(alice, chat["id"], images.sample_png()) + message = api.send_message( + alice, + chat["id"], + "с вложением в очереди", + attachment_ids=[accepted["id"]], + ) + meta = assert_ok( + api.attachment_meta(alice, accepted["id"]), + 200, + "Attachment", + ) + assert meta["status"] == "queued", meta + assert api.all_messages(bob, chat["id"]) == [message] + api.wait_attachment(alice, accepted["id"]) + + +@pytest.mark.spec("messages", "Вложение стало failed после отправки") +def test_attachment_failed_after_message( + api: Api, + stand: Stand, + alice: Actor, + chat: dict[str, Any], +) -> None: + with worker_stopped(stand): + accepted = api.upload( + alice, + chat["id"], + images.jpeg_precision_12(), + content_type="image/jpeg", + filename="image.jpg", + ) + message = api.send_message( + alice, + chat["id"], + "", + attachment_ids=[accepted["id"]], + ) + meta = api.wait_attachment( + alice, + accepted["id"], + status="failed", + timeout=JOB_WAIT_S, + ) + assert meta["error_code"] == "invalid_image", meta + assert api.all_messages(alice, chat["id"]) == [message] + + +@pytest.mark.spec("idempotency", "Повтор после failed вложения") +def test_replay_after_attachment_failed( + api: Api, + stand: Stand, + alice: Actor, + chat: dict[str, Any], +) -> None: + key = new_key() + with worker_stopped(stand): + accepted = api.upload( + alice, + chat["id"], + images.jpeg_precision_12(), + content_type="image/jpeg", + filename="image.jpg", + ) + body = {"text": "повтор", "attachment_ids": [accepted["id"]]} + message = assert_ok( + api.post_message(alice, chat["id"], key=key, json=body), + 201, + "Message", + ) + api.wait_attachment( + alice, + accepted["id"], + status="failed", + timeout=JOB_WAIT_S, + ) + replay = assert_ok( + api.post_message(alice, chat["id"], key=key, json=body), + 201, + "Message", + ) + assert replay == message + assert_error(api.post_message(alice, chat["id"], json=body), 409) + assert api.all_messages(alice, chat["id"]) == [message] + + +@pytest.mark.spec("health", "Брокер и worker недоступны") +@pytest.mark.parametrize("action", ["stop", "pause"]) +def test_readiness_without_broker_and_worker( + api: Api, + stand: Stand, + action: str, +) -> None: + with worker_stopped(stand), outage(stand, action, "rabbitmq"): + for path in ("/health/ready", "/health/live"): + resp, took = timed(lambda path=path: api.request("GET", path)) + assert assert_ok(resp, 200, "Health") == {"status": "ok"} + assert took < BROKER_HEALTH_S, f"{path} took {took:.2f}s" + + +def test_worker_stop_during_processing( + api: Api, + stand: Stand, + alice: Actor, + chat: dict[str, Any], +) -> None: + """Спек `graceful-shutdown`, «docker stop во время обработки» (вне сверки + покрытия — сценарий в докстринге): фиксация ждёт 4 с, а срок остановки + worker стенда 2 с. `stop` быстрее 10 с, код 0, сообщение снова в очереди, + а после запуска worker вложение становится `ready`.""" + filename = fault_filename() + wait_queue_empty(stand) + stand("fail-attachments", "ready-stall", filename) + stopped = False + try: + accepted = api.upload( + alice, + chat["id"], + images.sample_png(), + filename=filename, + ) + api.wait_attachment( + alice, + accepted["id"], + status="processing", + timeout=JOB_WAIT_S, + ) + seen = len(worker_records(stand)) + started = time.monotonic() + stand("stop", "worker") + stopped = True + assert time.monotonic() - started < WORKER_STOP_MAX_S + state = json.loads(stand("worker-state")) + assert (state["running"], state["exit_code"]) == (False, 0), state + assert queue_state(stand)["messages"] == 1 + records = worker_records(stand)[seen:] + assert any(item.get("event") == "Stopped worker" for item in records) + finally: + stand("clear-fail-attachments") + if not stopped: + stand("stop", "worker") + stand("start", "worker") + meta = api.wait_attachment(alice, accepted["id"], timeout=JOB_WAIT_S) + assert_one_thumbnail(api, stand, alice, meta) + wait_queue_empty(stand) + + +@contextmanager +def current_work( + api: Api, + stand: Stand, + alice: Actor, + chat: dict[str, Any], +) -> Iterator[dict[str, dict[str, Any]]]: + """Worker убит посреди задания и лежит. Вложения F в `failed` (конечный + объект у него есть), P в `processing` (объекты записаны, фиксация не + дошла) и Q в `queued`, все старше grace по строке. Выход — worker запущен, + P и Q становятся `ready`.""" + wait_queue_empty(stand) + failed = api.upload( + alice, + chat["id"], + images.jpeg_precision_12(), + content_type="image/jpeg", + filename="image.jpg", + ) + api.wait_attachment( + alice, + failed["id"], + status="failed", + timeout=JOB_WAIT_S, + ) + filename = fault_filename() + stand("fail-attachments", "ready-stall", filename) + work: dict[str, dict[str, Any]] = {"failed": failed} + try: + processing = api.upload( + alice, + chat["id"], + images.sample_png(), + filename=filename, + ) + api.wait_attachment( + alice, + processing["id"], + status="processing", + timeout=JOB_WAIT_S, + ) + work["processing"] = processing + # конечный объект записан до фиксации; ждём и thumbnail + deadline = time.monotonic() + STALL_S + while stand("variant-object-count", processing["id"]) != "1": + assert time.monotonic() < deadline, "no variant object in time" + time.sleep(0.1) + stand("kill", "worker") + stand("clear-fail-attachments") + work["queued"] = api.upload(alice, chat["id"], images.sample_png()) + for item in work.values(): + stand("age-row", item["id"], str(AGED_S)) + yield work + finally: + stand("clear-fail-attachments") + stand("start", "worker") + for name in ("processing", "queued"): + api.wait_attachment(alice, work[name]["id"], timeout=JOB_WAIT_S) + + +@pytest.mark.spec("storage-consistency", "Текущая работа не тронута") +def test_cleaner_keeps_current_work( + api: Api, + stand: Stand, + alice: Actor, + chat: dict[str, Any], +) -> None: + with current_work(api, stand, alice, chat) as work: + # проходов уборщика за это время — несколько + time.sleep(3 * CLEANER_INTERVAL_S + CLEANUP_SLACK_S) + rows = attachment_rows(stand) + staged = staged_ids(stand) + for name, item in work.items(): + assert rows.get(item["id"]) == name, (name, rows.get(item["id"])) + assert item["id"] in staged, name # --------------------------------------------------------------------------- @@ -1592,8 +3064,6 @@ def test_upload_after_idle_s3( # G + 1 с, строки состаривает hook (age-row) # --------------------------------------------------------------------------- -# имя базы стенда: ключ объекта вложения — `<база>/attachments//original` -FAULT_DATABASE = os.environ.get("FAULT_DATABASE", "messenger") # на сколько hook состаривает строку: заведомо больше grace AGED_S = CLEANER_GRACE_S + 60 # объекты без строки старше grace: grace и секунда точности LastModified @@ -1692,6 +3162,10 @@ def object_key(attachment_id: str) -> str: return f"{FAULT_DATABASE}/attachments/{attachment_id}/original" +def variant_key(attachment_id: str) -> str: + return f"{FAULT_DATABASE}/attachments/{attachment_id}/v1-thumbnail" + + def lost_ids(stand: Stand) -> set[str]: return set(stand("lost-ids").splitlines()) @@ -1747,10 +3221,14 @@ def test_reconcile_finds_and_fixes( data = images.sample_png() # уборщик стенда стоит: зависшую загрузку P должна убрать сверка with outage(stand, "stop", "cleaner"): - a, b, c = (api.upload(alice, chat["id"], data) for _ in range(3)) + a, b, c = (api.upload_ready(alice, chat["id"], data) for _ in range(3)) api.send_message(alice, chat["id"], "", attachment_ids=[a["id"]]) orphan = str(uuid.uuid4()) - keys = {"o": object_key(orphan), "b": object_key(b["id"])} + keys = { + "o": object_key(orphan), + "b": object_key(b["id"]), + "bv": variant_key(b["id"]), + } put_object(stand, keys["o"], data) stand("delete-object", object_key(a["id"])) stand("delete-row", b["id"]) @@ -1764,16 +3242,17 @@ def test_reconcile_finds_and_fixes( finally: stand("clear-fail-attachments") (pending,) = new_ids(before, attachment_rows(stand)) - assert pending in stored_ids(stand) + assert pending in staged_ids(stand) # последний объект записан только что: после G + 1 всё старше grace time.sleep(OBJECT_AGE_WAIT_S) ids = {a["id"], c["id"], pending} - snapshot = (attachment_rows(stand), stored_ids(stand), lost_ids(stand)) + snapshot = (attachment_rows(stand), object_ids(stand), lost_ids(stand)) dry = run_reconcile(stand, "dry-run") assert dry.kinds(FOUND, ids=ids, keys=keys.values()) == { keys["o"]: "orphan_object", keys["b"]: "orphan_object", + keys["bv"]: "orphan_object", a["id"]: "missing_object", c["id"]: "size_mismatch", pending: "stale_pending", @@ -1782,7 +3261,7 @@ def test_reconcile_finds_and_fixes( assert record["age_seconds"] >= CLEANER_GRACE_S, record assert dry.exit_code == 3 # dry-run ничего не меняет: ни строк, ни объектов, ни пометок - after = (attachment_rows(stand), stored_ids(stand), lost_ids(stand)) + after = (attachment_rows(stand), object_ids(stand), lost_ids(stand)) assert after == snapshot assert_error(api.attachment_content(alice, a["id"]), 500) assert_ok(api.attachment_meta(alice, a["id"]), 200, "Attachment") @@ -1797,6 +3276,7 @@ def test_reconcile_finds_and_fixes( assert actions == { keys["o"]: "deleted_object", keys["b"]: "deleted_object", + keys["bv"]: "deleted_object", a["id"]: "marked_lost", c["id"]: "marked_lost", pending: "removed_pending", @@ -1805,6 +3285,8 @@ def test_reconcile_finds_and_fixes( fixed.assert_code_matches() rows, stored = attachment_rows(stand), stored_ids(stand) assert not {orphan, b["id"], pending} & stored + assert stand("variant-object-count", b["id"]) == "0" + assert pending not in staged_ids(stand) assert pending not in rows assert {a["id"], c["id"]} <= lost_ids(stand) assert rows[a["id"]] == rows[c["id"]] == "ready" @@ -1828,7 +3310,7 @@ def test_reconcile_keeps_fresh_used_and_unknown( chat: dict[str, Any], ) -> None: data = images.sample_png() - used = api.upload(alice, chat["id"], data) + used = api.upload_ready(alice, chat["id"], data) message = api.send_message( alice, chat["id"], @@ -1841,7 +3323,7 @@ def test_reconcile_keeps_fresh_used_and_unknown( put_object(stand, unknown, data) time.sleep(OBJECT_AGE_WAIT_S) # свежие: готовое вложение без объекта и объект без строки - fresh = api.upload(alice, chat["id"], data) + fresh = api.upload_ready(alice, chat["id"], data) stand("delete-object", object_key(fresh["id"])) fresh_object = str(uuid.uuid4()) put_object(stand, object_key(fresh_object), data) @@ -1890,7 +3372,7 @@ def test_reconcile_restored_original( chat: dict[str, Any], ) -> None: data = images.png_noise(64, 48, seed=7) - restored = api.upload(alice, chat["id"], data) + restored = api.upload_ready(alice, chat["id"], data) lose_original(stand, restored) marked = run_reconcile(stand, "apply") assert marked.kinds(FIXED, ids={restored["id"]}) == { @@ -1925,7 +3407,8 @@ def test_reconcile_change_limit( ) -> None: limit = 2 batch = [ - api.upload(alice, chat["id"], images.sample_png()) for _ in range(3) + api.upload_ready(alice, chat["id"], images.sample_png()) + for _ in range(3) ] ids = {item["id"] for item in batch} for item in batch: @@ -1964,7 +3447,7 @@ def test_reconcile_keeps_referenced_objects( ключ, и объект `/original`, на который ссылается строка Y другого `id`, — чужие, а не объекты без метаданных.""" data = images.sample_png() - x, y = (api.upload(alice, chat["id"], data) for _ in range(2)) + x, y = (api.upload_ready(alice, chat["id"], data) for _ in range(2)) z = str(uuid.uuid4()) keys = { "x": object_key(x["id"]), @@ -2037,9 +3520,9 @@ def test_reconcile_limit_keeps_cleanup( finally: stand("clear-fail-attachments") (pending,) = new_ids(before, attachment_rows(stand)) - assert pending in stored_ids(stand) + assert pending in staged_ids(stand) stand("age-row", pending, str(AGED_S)) - batch = [api.upload(alice, chat["id"], data) for _ in range(3)] + batch = [api.upload_ready(alice, chat["id"], data) for _ in range(3)] ids = {item["id"] for item in batch} for item in batch: lose_original(stand, item) @@ -2055,7 +3538,7 @@ def test_reconcile_limit_keeps_cleanup( (record,) = refused.about(FIXED, ids={pending}) assert record["action"] == "removed_pending" assert pending not in attachment_rows(stand) - assert pending not in stored_ids(stand) + assert pending not in staged_ids(stand) # изменений под пределом нет: ни одной пометки assert not refused.about(FIXED, ids=ids) assert not ids & lost_ids(stand) @@ -2080,7 +3563,7 @@ def test_reconcile_foreign_key_untouched( data = images.sample_png() # уборщик стенда стоит: иначе зависшую загрузку убрал бы он with outage(stand, "stop", "cleaner"): - ready = api.upload(alice, chat["id"], data) + ready = api.upload_ready(alice, chat["id"], data) filename = fault_filename() before = attachment_rows(stand) stand("fail-attachments", "commit", filename) @@ -2113,7 +3596,8 @@ def test_reconcile_foreign_key_untouched( "pending", ) assert ready["id"] not in lost_ids(stand) - assert ids <= stored_ids(stand) + assert ready["id"] in stored_ids(stand) + assert pending in staged_ids(stand) finally: # прежние ключи у тех строк, что остались: зависшую загрузку # после теста уберёт уборщик стенда вместе с её объектом @@ -2129,7 +3613,7 @@ def test_reconcile_object_storage_stopped( alice: Actor, chat: dict[str, Any], ) -> None: - missing = api.upload(alice, chat["id"], images.sample_png()) + missing = api.upload_ready(alice, chat["id"], images.sample_png()) lose_original(stand, missing) with outage(stand, "stop", "s3"): interrupted = run_reconcile(stand, "apply") @@ -2155,13 +3639,13 @@ def test_reconcile_interrupted_by_database( chat: dict[str, Any], ) -> None: filename = fault_filename() - failing = api.upload( + failing = api.upload_ready( alice, chat["id"], images.sample_png(), filename=filename, ) - other = api.upload(alice, chat["id"], images.sample_png()) + other = api.upload_ready(alice, chat["id"], images.sample_png()) ids = {failing["id"], other["id"]} for item in (failing, other): lose_original(stand, item) @@ -2194,7 +3678,7 @@ def test_reconcile_under_load( orphans = {str(uuid.uuid4()) for _ in range(2)} for item in orphans: put_object(stand, object_key(item), data) - injected = [api.upload(alice, chat["id"], data) for _ in range(2)] + injected = [api.upload_ready(alice, chat["id"], data) for _ in range(2)] for item in injected: lose_original(stand, item) lost_before = lost_ids(stand) @@ -2216,12 +3700,12 @@ def test_reconcile_under_load( number += 1 body = images.png_noise(200, 170, seed=worker * 10**6 + number) resp = client.post_attachment(actor, chat["id"], body) - if resp.status_code != 201: + if resp.status_code != 202: with lock: failures.append(f"upload {resp.status_code}") continue - attachment = assert_ok(resp, 201, "Attachment") - # загрузка подтверждена: она обязана скачиваться + attachment = assert_accepted(resp) + # загрузка подтверждена: она обязана стать ready и скачиваться with lock: uploads[attachment["id"]] = hashlib.sha256( body, @@ -2270,6 +3754,7 @@ def test_reconcile_under_load( assert lost_ids(stand) - lost_before == {item["id"] for item in injected} # ни одно подтверждённое вложение не потеряно for attachment_id, digest in uploads.items(): + api.wait_attachment(alice, attachment_id) resp = api.attachment_content(alice, attachment_id) assert resp.status_code == 200, (attachment_id, resp.status_code) assert hashlib.sha256(resp.content).hexdigest() == digest @@ -2288,7 +3773,7 @@ def test_scheduled_reconcile( alice: Actor, chat: dict[str, Any], ) -> None: - scheduled = api.upload(alice, chat["id"], images.sample_png()) + scheduled = api.upload_ready(alice, chat["id"], images.sample_png()) lose_original(stand, scheduled) log = stand("run-cleaner", str(SCHEDULED_RUN_S)) records = [ @@ -2343,10 +3828,14 @@ def test_reconcile_head_strategy_same_findings( data = images.sample_png() # уборщик стенда стоит: зависшую загрузку P не уберут между проходами with outage(stand, "stop", "cleaner"): - a, b, c = (api.upload(alice, chat["id"], data) for _ in range(3)) + a, b, c = (api.upload_ready(alice, chat["id"], data) for _ in range(3)) api.send_message(alice, chat["id"], "", attachment_ids=[a["id"]]) orphan = str(uuid.uuid4()) - keys = {"o": object_key(orphan), "b": object_key(b["id"])} + keys = { + "o": object_key(orphan), + "b": object_key(b["id"]), + "bv": variant_key(b["id"]), + } put_object(stand, keys["o"], data) stand("delete-object", object_key(a["id"])) stand("delete-row", b["id"]) @@ -2365,11 +3854,12 @@ def test_reconcile_head_strategy_same_findings( expected = { keys["o"]: "orphan_object", keys["b"]: "orphan_object", + keys["bv"]: "orphan_object", a["id"]: "missing_object", c["id"]: "size_mismatch", pending: "stale_pending", } - snapshot = (attachment_rows(stand), stored_ids(stand), lost_ids(stand)) + snapshot = (attachment_rows(stand), object_ids(stand), lost_ids(stand)) batch = run_reconcile(stand, "dry-run") head = run_reconcile(stand, "dry-run", options=HEAD_STRATEGY) @@ -2389,7 +3879,7 @@ def test_reconcile_head_strategy_same_findings( > batch.finished["s3_requests"]["head"] ), (head.finished, batch.finished) assert head.finished["db_sessions"] > batch.finished["db_sessions"] - after = (attachment_rows(stand), stored_ids(stand), lost_ids(stand)) + after = (attachment_rows(stand), object_ids(stand), lost_ids(stand)) assert after == snapshot # стенд — без внесённых расхождений для следующих тестов @@ -2410,7 +3900,7 @@ def test_reconcile_deep_checksum( chat: dict[str, Any], ) -> None: data = images.png_noise(64, 48, seed=11) - a = api.upload(alice, chat["id"], data) + a = api.upload_ready(alice, chat["id"], data) api.send_message(alice, chat["id"], "", attachment_ids=[a["id"]]) other = same_size_bytes(data, seed=11) # объект перезаписан мимо API байтами того же размера @@ -2457,7 +3947,7 @@ def test_reconcile_restore_needs_same_bytes( chat: dict[str, Any], ) -> None: data = images.png_noise(64, 48, seed=13) - restored = api.upload(alice, chat["id"], data) + restored = api.upload_ready(alice, chat["id"], data) ids = {restored["id"]} lose_original(stand, restored) marked = run_reconcile(stand, "apply") @@ -2511,8 +4001,8 @@ def test_reconcile_rate_limit( объектов на предел, находки и код — как без предела.""" data = images.sample_png() for _ in range(RATE_UPLOADS): - api.upload(alice, chat["id"], data) - lost = api.upload(alice, chat["id"], data) + api.upload_ready(alice, chat["id"], data) + lost = api.upload_ready(alice, chat["id"], data) ids = {lost["id"]} lose_original(stand, lost) # уборщик стенда стоит: между проходами стенд не меняется @@ -2553,7 +4043,8 @@ def test_reconcile_limit_stops_rechecks( ) -> None: limit = 2 batch = [ - api.upload(alice, chat["id"], images.sample_png()) for _ in range(6) + api.upload_ready(alice, chat["id"], images.sample_png()) + for _ in range(6) ] ids = {item["id"] for item in batch} for item in batch: @@ -2608,7 +4099,7 @@ def test_reconcile_row_with_other_id_key( её ключу: другой размер и, с `--deep`, другой SHA-256 — расхождения Y; объекты Z и `/original` — чужие и на месте.""" data = images.png_noise(64, 48, seed=17) - y1, y2 = (api.upload(alice, chat["id"], data) for _ in range(2)) + y1, y2 = (api.upload_ready(alice, chat["id"], data) for _ in range(2)) z1, z2 = (str(uuid.uuid4()) for _ in range(2)) keys = { "y1": object_key(y1["id"]), @@ -2685,7 +4176,7 @@ def test_reconcile_fresh_overwrite_untouched( `--deep --apply` и HEAD-стратегией считает оба объекта свежими; после grace — расхождения.""" data = images.png_noise(64, 48, seed=19) - a, b = (api.upload(alice, chat["id"], data) for _ in range(2)) + a, b = (api.upload_ready(alice, chat["id"], data) for _ in range(2)) ids = {a["id"], b["id"]} for item in (a, b): stand("age-row", item["id"], str(AGED_S)) @@ -2726,3 +4217,84 @@ def test_reconcile_fresh_overwrite_untouched( # стенд — с исходными байтами: расхождений не остаётся for item in (a, b): put_object(stand, object_key(item["id"]), data) + + +# --------------------------------------------------------------------------- +# Сверка и фоновая обработка (change async-attachments, design, решение 11): +# объекты вариантов своих вложений и текущая работа — не расхождения +# --------------------------------------------------------------------------- + + +@pytest.mark.spec("storage-consistency", "Объекты вариантов своих вложений") +def test_reconcile_variant_objects( + api: Api, + stand: Stand, + alice: Actor, + chat: dict[str, Any], +) -> None: + data = images.sample_png() + batch = [api.upload_ready(alice, chat["id"], data) for _ in range(2)] + ids = {item["id"] for item in batch} + keys = {variant_key(item["id"]) for item in batch} + for item in batch: + assert stand("variant-object-count", item["id"]) == "1" + stand("age-row", item["id"], str(AGED_S)) + # объекты вариантов записаны только что: после G + 1 старше grace + time.sleep(OBJECT_AGE_WAIT_S) + for options in ((), HEAD_STRATEGY): + run = run_reconcile(stand, "dry-run", options=options) + assert not run.about(FOUND, ids=ids, keys=keys), run.finished + run.assert_code_matches() + + +@pytest.mark.spec("storage-consistency", "Объект варианта без метаданных") +def test_reconcile_orphan_variant( + stand: Stand, +) -> None: + data = images.sample_png() + orphan = str(uuid.uuid4()) + key = variant_key(orphan) + put_object(stand, key, data) + assert stand("variant-object-count", orphan) == "1" + time.sleep(OBJECT_AGE_WAIT_S) + run = run_reconcile(stand, "apply") + (record,) = run.about(FIXED, keys={key}) + assert (record["kind"], record["action"]) == ( + "orphan_object", + "deleted_object", + ) + assert not run.about(FOUND, keys={key}) + assert stand("variant-object-count", orphan) == "0" + + +@pytest.mark.spec( + "storage-consistency", + "Текущая работа не считается расхождением", +) +def test_reconcile_keeps_current_work( + api: Api, + stand: Stand, + alice: Actor, + chat: dict[str, Any], +) -> None: + with current_work(api, stand, alice, chat) as work: + # конечные объекты F и P и варианты P старше grace + time.sleep(OBJECT_AGE_WAIT_S) + ids = {item["id"] for item in work.values()} + keys = {staging_key(item) for item in ids} | { + object_key(item) for item in ids + } + run = run_reconcile(stand, "apply") + assert not run.about(FOUND, ids=ids, keys=keys), run.finished + assert not run.about(FIXED, ids=ids, keys=keys), run.finished + run.assert_code_matches() + assert not ids & lost_ids(stand) + rows = attachment_rows(stand) + staged = staged_ids(stand) + for name, item in work.items(): + assert rows.get(item["id"]) == name, (name, rows.get(item["id"])) + assert item["id"] in staged, name + stored = stored_ids(stand) + # конечный объект у задания, дошедшего до него, на месте + assert work["failed"]["id"] in stored + assert work["processing"]["id"] in stored diff --git a/student-tests/test_messages.py b/student-tests/test_messages.py index 461b7597..4a587c7f 100644 --- a/student-tests/test_messages.py +++ b/student-tests/test_messages.py @@ -36,7 +36,8 @@ def test_member_sends( def upload(api: Api, actor: Actor, chat_id: str) -> str: - """Готовое вложение чата; id.""" + """Принятое вложение чата; id. Сообщение можно отправить и с вложением в + обработке: `ready` не ждём.""" return api.upload(actor, chat_id, images.sample_png())["id"] diff --git a/uv.lock b/uv.lock index 3186e69b..0842a847 100644 --- a/uv.lock +++ b/uv.lock @@ -11,6 +11,19 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/72/15/504337e302d070bd2ff2f39418bb17d2ad73c662c403a4f37cb4e5c5b237/agent_detector-2.0.0-py3-none-any.whl", hash = "sha256:22c6a1c9c23894a12f55aea625f060b8d3330fba774de72d02d5442bb580417f", size = 9352, upload-time = "2026-09-02T14:19:50.971Z" }, ] +[[package]] +name = "aio-pika" +version = "10.2.1" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "aiormq" }, + { name = "yarl" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/5d/31/70f0d7a9fe1affc3241d86d24c24714a4a2ac648961efd3d835ef734a6a1/aio_pika-10.2.1.tar.gz", hash = "sha256:e4f77afd9179a3cca5a904c3b0a1190256a36d9f90650db908b1b2245eb27487", size = 101040, upload-time = "2026-10-25T11:47:24.577Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/b4/ae/f69eb62f240f743d5d3aff659a6ed76077f73b722a0d8f9f9559ab825836/aio_pika-10.2.1-py3-none-any.whl", hash = "sha256:66c85d311e30f1dd3e28109d686c9bf1d9dd1a74582004c7cb7bed284d8fe3b1", size = 61568, upload-time = "2026-10-25T11:47:23.119Z" }, +] + [[package]] name = "aiobotocore" version = "3.9.2" @@ -84,6 +97,19 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/10/a1/510b0a7fadc6f43a6ce50152e69dbd86415240835868bb0bd9b5b88b1e06/aioitertools-0.13.0-py3-none-any.whl", hash = "sha256:0be0292b856f08dfac90e31f4739432f4cb6d7520ab9eb73e143f4f2fa5259be", size = 24182, upload-time = "2025-11-06T22:17:06.502Z" }, ] +[[package]] +name = "aiormq" +version = "7.2.4" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "pamqp" }, + { name = "yarl" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/71/11/8b93eac7630c5087c34df3d34ce0bdf50d6ea2fb83061f17e8c73877141d/aiormq-7.2.4.tar.gz", hash = "sha256:5fd20bb9583d73de85572198496b65cf028f27527c1733c9840d458e0b40e8fa", size = 81569, upload-time = "2026-10-24T12:36:22.703Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/29/a7/346b74a5f19d0acbd9d428f5f7b070537a8a079e45a74fba58c7831e058d/aiormq-7.2.4-py3-none-any.whl", hash = "sha256:2b9d6dade171318185ab8f507717b630f20b8b2303a075f9293d3f6b0d166f1d", size = 40694, upload-time = "2026-10-24T12:36:21.054Z" }, +] + [[package]] name = "aiosignal" version = "1.4.0" @@ -745,11 +771,13 @@ name = "mtusi-messenger" version = "0.1.0" source = { editable = "." } dependencies = [ + { name = "aio-pika" }, { name = "aiobotocore" }, { name = "alembic" }, { name = "argon2-cffi" }, { name = "asyncpg" }, { name = "fastapi", extra = ["all"] }, + { name = "pillow" }, { name = "pydantic" }, { name = "pydantic-settings" }, { name = "redis" }, @@ -769,18 +797,19 @@ dev = [ { name = "httpx" }, { name = "jsonschema" }, { name = "openapi-spec-validator" }, - { name = "pillow" }, { name = "pre-commit" }, { name = "pytest" }, ] [package.metadata] requires-dist = [ + { name = "aio-pika", specifier = ">=10.2.1,<11" }, { name = "aiobotocore", specifier = ">=3.9.2,<4" }, { name = "alembic", specifier = ">=1.20.0,<2" }, { name = "argon2-cffi", specifier = ">=25.1.0,<26" }, { name = "asyncpg", specifier = ">=0.31.0,<0.32" }, { name = "fastapi", extras = ["all"], specifier = ">=0.137.2,<1.0.0" }, + { name = "pillow", specifier = ">=13,<14" }, { name = "pydantic", specifier = ">=2.6.3,<3.0.0" }, { name = "pydantic-settings", specifier = ">=2.15.0,<3.0.0" }, { name = "redis", specifier = ">=8.1,<9" }, @@ -797,7 +826,6 @@ dev = [ { name = "httpx", specifier = ">=0.28.1,<1" }, { name = "jsonschema", specifier = ">=4.26.0,<5" }, { name = "openapi-spec-validator", specifier = "==0.7.2" }, - { name = "pillow", specifier = ">=13.0.0,<14" }, { name = "pre-commit", specifier = ">=4.5.0" }, { name = "pytest", specifier = ">=9.1.1,<10" }, ] @@ -887,6 +915,15 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/63/34/ba1c580383c9eada3711951fef0795c80b829a078d72188184bcab9dd527/packaging-26.3-py3-none-any.whl", hash = "sha256:d7193f7c8e4e93f444fde0262bf90af30e16fa0ad0ad44cb553c87339b23cd1c", size = 129956, upload-time = "2026-08-04T18:15:27.159Z" }, ] +[[package]] +name = "pamqp" +version = "4.0.1" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/31/4c/33a0ddaaac7bc42f9a542dbaaee8b580ceca3f89bf5da7c498d1fa97ff9a/pamqp-4.0.1.tar.gz", hash = "sha256:9dd13b828e346622793981f14a5df817fce5de998c746209d6c0154eb8403970", size = 137192, upload-time = "2026-07-06T16:37:51.732Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/71/14/1dfc08b743ba995a38dee0ea09beb46a05c7fe8ac53d729095905f7bf11d/pamqp-4.0.1-py3-none-any.whl", hash = "sha256:a547f45128b06e42ce8d7a739b0cfcc40f2c724770622eaaff4a3f587b1cf7d0", size = 32773, upload-time = "2026-07-06T16:37:50.623Z" }, +] + [[package]] name = "pathable" version = "0.4.4"