feat: process attachments asynchronously with RabbitMQ and a worker
Upload answers 202 after staging, a queued job in PostgreSQL and a broker confirm; a separate worker publishes the original and a thumbnail with bounded retries. Adds the job and variant tables, the broker service, the worker S3 user, cleanup and reconcile support for staging and variants, the failure stand with broker and worker, bench and driver updates. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
@@ -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 в готовность не входит.
|
||||
|
||||
@@ -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)
|
||||
|
||||
@@ -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, как
|
||||
миграции, только расширяет: новые пользователи и политики не отбирают
|
||||
|
||||
+23
-14
@@ -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,
|
||||
|
||||
@@ -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` на `<bucket>/*` — без удаления и
|
||||
списка; `check` печатает строки «worker key …».
|
||||
- **`restart.sh`** перезапускает и брокер; worker и уборщика не трогает: защита
|
||||
вызывает hook при остановленном worker, и он останется остановленным.
|
||||
|
||||
## Обновление кода на стенде
|
||||
|
||||
- `make run_docker` после пересборки пересоздаёт реплики, образ которых
|
||||
|
||||
@@ -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/<domain>.py` — DTO между repo → service → api;
|
||||
`src/schemas/enums/<domain>.py` — `StrEnum` доменов. HTTP-модели
|
||||
(pydantic) лежат не здесь, а в `src/api/schemas/` (`api-layer.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/`), дальше —
|
||||
брокер, телеметрия. Бизнес-правил (уникальность, доступ, валидация) здесь нет:
|
||||
|
||||
@@ -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: логи полезные, но **без содержимого сообщений**.
|
||||
|
||||
@@ -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` его не пересоздаст: повтор миграции
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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`,
|
||||
|
||||
@@ -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` не
|
||||
|
||||
@@ -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`,
|
||||
|
||||
@@ -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_<db>.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`,
|
||||
|
||||
@@ -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`.
|
||||
@@ -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 <token из ответа выше>
|
||||
python3 $D req POST /api/v1/chats/<chat>/messages --token <token> --data '{"text":"hi"}'
|
||||
# печатает idempotency-key; повтор той же отправки — тот же запрос с --key <ключ>
|
||||
python3 $D upload --token <token> --chat <chat> --file tests/fixtures/sample.png
|
||||
# 201, x-instance-id, Attachment, SHA-256 файла и «sha256 matches: True»
|
||||
python3 $D download --token <token> --attachment <id> [--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 <token> --attachment <id> [--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:<port> — ~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=<port> uv run python -m src` в своей группе процессов |
|
||||
| `start` | `make upgrade start_cache start_s3 start_broker`, затем `APP__RUN_MODE=console APP__PORT=<port> uv run python -m src` и `make run_worker` (ключи S3 worker) в одной группе процессов; готово — `/health/ready` 200 и запись worker «Connected to broker». Журнал worker — `/tmp/mtusi-worker-<port>.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:<id>` сразу после 201 (`EXISTS`, TTL ≤ `[cache] chat_ttl_seconds` из реплики, поля значения), `DEL`, через 11 с снимок `seq_scan + idx_scan` таблицы `chats` и `keyspace_hits` / `keyspace_misses`, 50 чтений через LB, через 11 с второй снимок; TTL до и после ещё 10 чтений; число ключей рабочей и тестовой (`test_<db>`) базы. Код 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/<id>/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/<id>/original` без `filename`, `staging_key` = `<база>/staging/<id>/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/<uuid>/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/<uuid>/` (сверка этот префикс не читает), удаляются в `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 <LB>`; спек `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 <LB>`; спеки `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'])"`.
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
+31
-2
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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 с:
|
||||
|
||||
@@ -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/<id>/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 <LB> defense-scenario` | сценарий защиты на рабочем стенде: worker остановлен → 202 → сообщение 201 → 409 → текст 201 → `scripts/restart.sh` → worker → `ready`, оригинал и thumbnail; `id` и `StartedAt`, worker запускается при любом исходе; `evidence/attachments/defense.md` |
|
||||
| `driver.py --port <LB> broker-check [--require-test-queue]` | образ и digest, volume, порт, предел памяти, очередь, остановка брокера; `evidence/broker/stand.md`, `evidence/broker/isolated.md` |
|
||||
| `driver.py --port <LB> 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_<db>` с Valkey и S3 стенда (ключи кэша и объектов разделены именем базы): сборка, миграции, отдельный контейнер API на `TEST_APP_PORT`, `make test` + `make student_test EXPECT_REPLICAS=1` (тесты реплик пропускаются с причиной), уборка при любом исходе — база и объекты под префиксом `test_<db>/` (`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/<domain>.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/<id>/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/<id>/original, variant_key и parse_variant_key <база>/attachments/<id>/v<N>-<имя>, оригинал <база>/attachments/<id>/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/<domain>.py # <Domain>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; строка с ключом <id>/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/<domain>.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/<domain>.py # DTO между repo → service → api
|
||||
enums/<domain>.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`,
|
||||
|
||||
@@ -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`
|
||||
|
||||
@@ -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_<db>/ удаляется при уборке.
|
||||
# $(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) на отдельном стенде: свой проект
|
||||
|
||||
@@ -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».
|
||||
|
||||
### Вопросы
|
||||
|
||||
|
||||
@@ -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 рабочего стенда: настройки — окружение и дефолты
|
||||
|
||||
@@ -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
|
||||
|
||||
+8
-4
@@ -5,7 +5,9 @@
|
||||
// <отправка мс>,<длительность мс>,<статус>,<X-Instance-Id>» в файл консоли
|
||||
// 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);
|
||||
}
|
||||
}
|
||||
|
||||
+95
-31
@@ -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,
|
||||
|
||||
+69
-13
@@ -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",
|
||||
|
||||
@@ -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
|
||||
|
||||
+113
-8
@@ -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:
|
||||
|
||||
@@ -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): при смене префикса менять вместе
|
||||
|
||||
@@ -0,0 +1,6 @@
|
||||
# Предел памяти брокера задан явно: лимит контейнера он не видит (проба: 4760
|
||||
# МиБ при лимите 512 МБ, design change async-attachments, Context) и был бы
|
||||
# завершён ядром, а не сдерживал публикацию. Сработавший предел блокирует
|
||||
# публикацию: загрузки получают 503 по сроку, сообщения не теряются.
|
||||
# Новую настройку этого файла проверять запуском: неверное имя — отказ старта.
|
||||
vm_memory_high_watermark.absolute = 400MiB
|
||||
+95
-8
@@ -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, пишет конечный префикс; удаления и списка нет.
|
||||
# По <bucket>/*, а не по префиксу: make test_isolated работает под
|
||||
# test_<db>/ с теми же ключами (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 ;;
|
||||
|
||||
+187
@@ -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")
|
||||
@@ -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, ни контейнеров, ни базы, ни очереди).
|
||||
|
||||
@@ -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 <LB> 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 и отчёт (после коммита, основная сессия)
|
||||
|
||||
@@ -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` с ним
|
||||
@@ -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/<id>/original`;
|
||||
- конечный оригинал — `<база>/attachments/<id>/original`;
|
||||
- вариант — `<база>/attachments/<id>/v<pipeline_version>-<вариант>`.
|
||||
|
||||
Staging и конечный префикс — один и тот же сервер S3 и bucket. Устойчивость
|
||||
staging — устойчивость этого сервера. Граница называется в `REPORT.md`:
|
||||
отказ диска или ВМ теряет и то, и другое.
|
||||
|
||||
Каждая загрузка SHALL создавать новое вложение и новые объекты, в том
|
||||
числе повтор той же загрузки: прозрачных повторов загрузки нет
|
||||
(`contracts/README.md`).
|
||||
|
||||
#### Scenario: Байты не в БД и не на диске API
|
||||
|
||||
- **WHEN** после загрузок через балансировщик проверяющий смотрит
|
||||
схему таблиц вложений, ключи объектов в PostgreSQL, объекты в bucket
|
||||
и изменения файловой системы контейнеров реплик API
|
||||
- **THEN** в таблицах нет колонки с байтами изображения, ключ каждого
|
||||
объекта имеет вид `<база>/attachments/<id>/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`
|
||||
|
||||
@@ -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** декодера изображений среди них нет
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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 выполняться одной
|
||||
|
||||
@@ -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 применять миграции
|
||||
|
||||
@@ -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 до старта
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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: Другое тело с тем же ключом
|
||||
|
||||
Если ключ в своей области уже использован с другим телом и срок не
|
||||
|
||||
@@ -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 держать в буферах ядра ограниченный
|
||||
|
||||
@@ -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: Реплика убита из-за памяти
|
||||
|
||||
|
||||
@@ -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 не изменился
|
||||
@@ -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`
|
||||
|
||||
@@ -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 и его доступ
|
||||
не меняются
|
||||
|
||||
@@ -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 не стартует, код выхода ненулевой, в журнале — запись с именем поля
|
||||
без значений настроек
|
||||
|
||||
@@ -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 и байтов
|
||||
|
||||
@@ -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/<id>/original`, на который не ссылается ни одна
|
||||
строка и для `id` которого строки нет;
|
||||
`<база>/attachments/<id>/original` или ключом варианта
|
||||
`<база>/attachments/<id>/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 удалять:
|
||||
- метаданные вложений, кроме уборки зависшей загрузки;
|
||||
- объект, на который ссылаются метаданные, в любом статусе;
|
||||
- объект с ключом вида `<id>/original`, если строка этого `id` есть.
|
||||
- объект с ключом вида `<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: Потерянный оригинал
|
||||
|
||||
|
||||
@@ -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_<db>/`.
|
||||
6. остановить и удалить оба контейнера, удалить базу, объекты S3 под
|
||||
префиксом `test_<db>/` и очередь временной базы.
|
||||
|
||||
Это один процесс 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_<db>`, ни тестового контейнера, ни
|
||||
объектов под префиксом `test_<db>/` после команды нет, число строк в
|
||||
таблицах рабочей базы и объекты рабочей базы не изменились, а
|
||||
рабочий стенд продолжает отвечать через балансировщик
|
||||
код выхода 0, ни базы `test_<db>`, ни тестовых контейнеров, ни
|
||||
объектов под префиксом `test_<db>/`, ни очереди временной базы после команды
|
||||
нет, число строк в таблицах рабочей базы и объекты рабочей базы не изменились,
|
||||
а рабочий стенд продолжает отвечать через балансировщик
|
||||
|
||||
#### Scenario: Упавшие тесты
|
||||
|
||||
- **WHEN** во время `make test_isolated` падает хотя бы один тест
|
||||
- **THEN** код выхода ненулевой, журнал тестового контейнера выведен,
|
||||
контейнер удалён, база `test_<db>` и объекты под префиксом
|
||||
`test_<db>/` удалены
|
||||
- **THEN** код выхода ненулевой, журналы тестовых контейнеров выведены,
|
||||
контейнеры удалены, база `test_<db>`, объекты под префиксом `test_<db>/` и
|
||||
очередь временной базы удалены
|
||||
|
||||
#### Scenario: Прерывание
|
||||
|
||||
- **WHEN** `make test_isolated` прерван Ctrl+C
|
||||
- **THEN** тестовый контейнер остановлен и удалён, база `test_<db>` и
|
||||
объекты под префиксом `test_<db>/` удалены
|
||||
- **THEN** тестовые контейнеры остановлены и удалены, база `test_<db>`, объекты
|
||||
под префиксом `test_<db>/` и очередь временной базы удалены
|
||||
|
||||
#### Scenario: Хвост прошлого прогона
|
||||
|
||||
- **WHEN** тестовый контейнер, база `test_<db>` или объекты под
|
||||
префиксом `test_<db>/` остались от прогона, убитого без уборки
|
||||
- **WHEN** тестовые контейнеры, база `test_<db>`, объекты под префиксом
|
||||
`test_<db>/` или очередь временной базы остались от прогона, убитого без уборки
|
||||
- **THEN** следующий `make test_isolated` удаляет их и начинает заново
|
||||
|
||||
#### Scenario: Сохранить базу для разбора
|
||||
|
||||
- **WHEN** выполнен `make test_isolated KEEP_TEST_DB=1`
|
||||
- **THEN** после прогона тестовый контейнер удалён, база `test_<db>` и
|
||||
объекты под префиксом `test_<db>/` остаются, а команда печатает имя
|
||||
базы и префикс
|
||||
- **THEN** после прогона тестовые контейнеры удалены, база `test_<db>`, объекты под
|
||||
префиксом `test_<db>/` и очередь временной базы остаются, а команда печатает имя
|
||||
базы, префикс и очередь
|
||||
|
||||
### 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 снова запущен, а код выхода ненулевой
|
||||
|
||||
+4
-3
@@ -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]
|
||||
|
||||
+7
-4
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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,
|
||||
)
|
||||
|
||||
|
||||
|
||||
@@ -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),
|
||||
|
||||
@@ -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",
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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(
|
||||
|
||||
@@ -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",
|
||||
|
||||
@@ -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 или его размер другой.
|
||||
|
||||
|
||||
@@ -10,6 +10,12 @@ class ObjectStorageUnavailable(ServiceUnavailable):
|
||||
"""
|
||||
|
||||
|
||||
class BrokerUnavailable(ServiceUnavailable):
|
||||
"""Брокер не подтвердил публикацию: недоступен, не ответил за срок,
|
||||
отказал или сообщению некуда идти. 503 `unavailable`; исход сообщения
|
||||
по сроку неизвестен (design change `async-attachments`, решение 3)."""
|
||||
|
||||
|
||||
class StoredObjectMissing(DomainError):
|
||||
"""Объекта с таким ключом в bucket нет.
|
||||
|
||||
|
||||
@@ -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], ...]:
|
||||
|
||||
@@ -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
|
||||
@@ -1,13 +1,18 @@
|
||||
"""Оригинал вложения в S3: ключ объекта и операции над ним.
|
||||
"""Объекты вложения в S3: ключи и операции над ними.
|
||||
|
||||
Repo над хранилищем объектов, как `chat_cache.py` над Valkey: первый
|
||||
параметр — `storage`, один вызов на функцию. Ключ —
|
||||
`<имя базы>/attachments/<id>/original` (design change `attachments`,
|
||||
решение 4): назначает сервер, `filename` в него не входит; объекты
|
||||
`make test_isolated` лежат под `test_<db>/`. Ключ хранится в строке
|
||||
вложения и при чтении берётся оттуда.
|
||||
параметр — `storage`, один вызов на функцию. Ключи (design change
|
||||
`attachments`, решение 4; `async-attachments`, решение 1) назначает сервер,
|
||||
`filename` в них не входит; объекты `make test_isolated` лежат под
|
||||
`test_<db>/`:
|
||||
- `<имя базы>/staging/<id>/original` — до обработки;
|
||||
- `<имя базы>/attachments/<id>/original` — конечный оригинал;
|
||||
- `<имя базы>/attachments/<id>/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:
|
||||
"""Префикс объектов вложений своей базы: `<namespace>/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,
|
||||
*,
|
||||
|
||||
@@ -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)
|
||||
+182
-48
@@ -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,
|
||||
)
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
@@ -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`,
|
||||
нестандартного — с каждой строкой этого ключа. Строку, ключ которой
|
||||
— `<id>/original` другого вложения, сравнивает шаг строк
|
||||
нестандартного — с каждой строкой этого ключа, объект варианта —
|
||||
только с наличием строки своего `id`. Строку, ключ которой —
|
||||
`<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),
|
||||
)
|
||||
|
||||
@@ -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,
|
||||
|
||||
@@ -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",
|
||||
]
|
||||
@@ -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)
|
||||
@@ -0,0 +1,16 @@
|
||||
"""Издатель заданий процесса API.
|
||||
|
||||
Создаётся при импорте по `settings.broker`, соединение открывает первая
|
||||
публикация: без брокера процесс стартует. Импортируют модуль только
|
||||
`src/main.py` (закрытие в lifespan) и `src/api/dependencies.py`. Очередь — по
|
||||
имени базы из `settings.database`: `make test_isolated` с базой `test_<db>` не
|
||||
смешивается с рабочей.
|
||||
"""
|
||||
|
||||
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,
|
||||
)
|
||||
@@ -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",
|
||||
|
||||
@@ -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):
|
||||
|
||||
@@ -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"},
|
||||
},
|
||||
},
|
||||
)
|
||||
|
||||
+10
-2
@@ -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)
|
||||
|
||||
@@ -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",
|
||||
|
||||
@@ -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]]
|
||||
|
||||
@@ -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",
|
||||
|
||||
@@ -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):
|
||||
|
||||
@@ -0,0 +1,3 @@
|
||||
from .attachment import AttachmentJobMessage, build_job_body
|
||||
|
||||
__all__ = ["AttachmentJobMessage", "build_job_body"]
|
||||
@@ -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()
|
||||
@@ -79,6 +79,21 @@ OBJECT_KEY_MAX_BYTES = 1024
|
||||
# ключ объекта: `<имя базы>/attachments/<id>/original`
|
||||
ATTACHMENT_KEY_PREFIX = "attachments"
|
||||
ATTACHMENT_ORIGINAL_SUFFIX = "original"
|
||||
# обработка вложения (с лабы 5, design change `async-attachments`):
|
||||
# объект до обработки — `<имя базы>/staging/<id>/original`, вариант —
|
||||
# `<имя базы>/attachments/<id>/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)
|
||||
|
||||
@@ -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(),
|
||||
)
|
||||
@@ -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)
|
||||
@@ -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)
|
||||
@@ -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,
|
||||
|
||||
@@ -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", "")
|
||||
|
||||
@@ -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 с): занижать сроки ради
|
||||
|
||||
+350
-37
@@ -39,18 +39,48 @@
|
||||
s3). Каталог `<id>` без файла не считается:
|
||||
после DELETE SeaweedFS убирает его лишь
|
||||
через ~2 мин
|
||||
fail-attachments insert|ready|stall|commit|outlive|undeletable <filename>
|
||||
staging-ids то же под `<база>/staging/<id>/`
|
||||
variant-object-count <id> сколько у вложения объектов вариантов
|
||||
(`<база>/attachments/<id>/v<N>-<имя>`)
|
||||
job <attachment_id> строка задания вложения: JSON с id, state,
|
||||
attempt, last_error_code, next_attempt_at,
|
||||
published_at; нет задания — пусто
|
||||
fail-attachments insert|queued|stall|commit|outlive|undeletable <filename>
|
||||
триггеры на вложения с этим 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 <filename>
|
||||
фиксация 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 <filename>
|
||||
пометка потерянного оригинала (UPDATE
|
||||
lost_at) вложения с этим filename падает
|
||||
@@ -65,13 +95,15 @@
|
||||
стенда мимо API: botocore в контейнере
|
||||
обычного API его ключами из окружения
|
||||
контейнера. Ключ — только под
|
||||
`<FAULT_DATABASE>/attachments/`, символы
|
||||
`<FAULT_DATABASE>/attachments/` или
|
||||
`<FAULT_DATABASE>/staging/`, символы
|
||||
[A-Za-z0-9._/-]
|
||||
delete-object <ключ> удалить объект мимо шлюза S3: `weed shell
|
||||
fs.rm /buckets/<bucket>/<ключ>`; ключ — с той
|
||||
же проверкой
|
||||
delete-row <id> удалить строку вложения (неиспользуемого:
|
||||
ссылку сообщения не даст удалить FK)
|
||||
delete-row <id> удалить строку вложения с его заданием и
|
||||
вариантами (неиспользуемого: ссылку
|
||||
сообщения не даст удалить FK)
|
||||
set-size <id> <байт> изменить size_bytes строки
|
||||
age-row <id> <секунд> сдвинуть 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` каталога `<база>/<prefix>` 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:
|
||||
|
||||
@@ -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."""
|
||||
|
||||
@@ -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")
|
||||
|
||||
@@ -1,17 +1,19 @@
|
||||
"""`make test_isolated`: образ на временной базе `test_<db>`.
|
||||
|
||||
Создаёт базу в 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_<db>/`
|
||||
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
|
||||
|
||||
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user