diff --git a/.claude/rules/api-contract.md b/.claude/rules/api-contract.md index 39dd1db5..38c85e15 100644 --- a/.claude/rules/api-contract.md +++ b/.claude/rules/api-contract.md @@ -81,7 +81,7 @@ FastAPI 0.141 из `uv.lock`: | 413 | `payload_too_large` | с лабы 4: тело загрузки больше 10 MiB (по `Content-Length` или счётчику) или изображение больше 40 млн пикселей (`PayloadTooLarge`) | | 415 | `unsupported_media_type` | с лабы 4: `Content-Type` не PNG/JPEG, содержимое не PNG/JPEG, подмена MIME, повреждённое изображение (`UnsupportedMediaType`) | | 429 | `rate_limited` | с change `upload-memory`: места загрузки процесса заняты — очередь ожидания полна или место не освободилось за срок (`UploadsBusy`); всегда с `Retry-After: 1` (`UPLOAD_RETRY_AFTER_SECONDS`, таблица `RETRY_AFTER` в `errors.py`) | -| 500 | `internal_error` | необработанное исключение, без деталей; с лабы 4 ещё у готового вложения нет объекта в S3 или он другого размера (`AttachmentContentMissing`, причина — `error` в журнале) | +| 500 | `internal_error` | необработанное исключение, без деталей; с лабы 4 ещё у готового вложения нет объекта в S3 или он другого размера, а сверка этого ещё не подтвердила (`AttachmentContentMissing`, причина — `error` в журнале); после пометки сверкой — 404 (раздел «Вложения») | | 503 | `unavailable` | недоступен Postgres или хранилище сессий: ограниченная ошибка вместо 500 (`infra.md`); с лабы 4 — недоступен S3 на путях байтов вложений | `429` контракт описывает как ограничение частоты запросов и требует @@ -326,6 +326,19 @@ ACTION_SCRIPT=scripts/restart.sh` (`tests/README.md`), hook — тело сам). `urllib` напрямую к одной реплике ранний ответ на большом теле теряет (`BrokenPipe`) — ограничение, оно в `REPORT.md`; тесты на httpx. +- Потерянный оригинал (design change `track2-reconciler`, решение 5): + если сверка подтвердила, что объекта готового вложения нет или размер + другой, и пометила его (`lost_at`), скачивание — 404 `not_found` без + обращения к S3, как «отсутствующий вариант ready-объекта» + (`contracts/README.md`); метаданные — 200 тем же `Attachment` + (`status=ready`, `error_code=null`: другого статуса контракт лабы 4 не + знает), ссылка в новом сообщении — 201. До пометки — 500, как выше. + Контракт неоднозначен («404 — объекта нет», «неожиданное исключение — + 500», `status` только `ready`): это вопрос преподавателю (`PLAN.md`, + `### track2-reconciler`, «Вопросы», п. 1), сделан вариант по + умолчанию. Ответ «иначе» меняет ветку `open_content`, сценарий + `attachments` «Потерянный оригинал» и тест + `test_reconcile_finds_and_fixes`. - Отказ S3 — 503 только на загрузке и скачивании байтов. Метаданные, сообщения (в том числе со ссылкой на готовое вложение), история и `/health/ready` работают без S3. diff --git a/.claude/rules/balancer.md b/.claude/rules/balancer.md index 56a84d83..f89f9810 100644 --- a/.claude/rules/balancer.md +++ b/.claude/rules/balancer.md @@ -381,6 +381,18 @@ compose stop cleaner`), потом реплики. Обратная совмес новый `mark_ready` на строках, вставленных прежним кодом, работает (вставка всегда писала `created_at` = `updated_at`). +**Порядок обновления со сверкой** (design change `track2-reconciler`, +решение 6): вперёд — `docker compose up -d s3-bootstrap` (политика +уборщика со списком по префиксу), затем `make rolling_update` (миграция +`lost_at`, затем реплики), затем `docker compose up -d --no-deps cleaner`. +Откат — сначала уборщик (`docker compose stop cleaner` или прежний +образ), потом `make rolling_update COMMIT=<прежний> MIGRATE=0`; колонка и +пометки остаются и прежнему коду не мешают. Смеси не хуже, чем до +change: прежние реплики колонку не читают (у помеченного без объекта — +500, как раньше); новый уборщик на прежней политике получает +`AccessDenied` на списке — проход сверки прерван, уборка работает; новый +уборщик на прежней схеме — «Reconcile pass failed», процесс живёт. + **Bootstrap S3 скрипт не запускает** (design change `s3-storage`, решение 9): новая реплика поднимается с `--no-deps`. Bootstrap, как миграции, только расширяет: новые пользователи и политики не отбирают diff --git a/.claude/rules/docker.md b/.claude/rules/docker.md index 309b4762..565c26ec 100644 --- a/.claude/rules/docker.md +++ b/.claude/rules/docker.md @@ -269,8 +269,21 @@ git ls-files -z -co --exclude-standard | tar --null -T - -cf - | docker build -t `cleaner-objects`, пользователи `api` и `cleaner` с их ключами; шаги пользователя общие — `apply_user <имя> <политика>`) и проверяет приватность: ключ API пишет и читает проверочный объект, ключ - уборщика читает его, получает 403 на запись и список и удаляет, после - этого GET ключом API — 404. Ожидание, пока ключ дойдёт до шлюза: у + уборщика читает его, получает 403 на запись и список всего bucket, + 200 на список своего префикса и удаляет его, после этого GET ключом + API — 404. Политика `cleaner-objects` с change `track2-reconciler` + (решение 2) — два оператора: `s3:GetObject` и `s3:DeleteObject` на + `/*` и `s3:ListBucket` на `` с условием `StringLike + s3:prefix <база>/attachments/*` (SeaweedFS 4.48 условие соблюдает: + весь bucket, `test_/`, `.s3-check/` и HEAD bucket — 403). Префикс + bootstrap получает в `S3_CLEANER_LIST_PREFIX: + ${POSTGRES_DB:?…}/attachments/` (окружение `s3-bootstrap`, не секрет) + и проверяет по `^[a-z0-9_]+/attachments/$` до любого шага (иначе + «FAILED: cleaner list prefix» и код 1); уборщику его не передают — + свой префикс он строит из имени базы. Новая политика доходит до шлюза + подпиской, как ключ: проверка списка — с ожиданием. `check` печатает + строки «cleaner key list attachments prefix» (200), «… objects», + «… other prefix», «… other bucket» (403). Ожидание, пока ключ дойдёт до шлюза: у API — PUT проверочного объекта, у уборщика — DELETE несуществующего ключа (204; PUT ему запрещён); `SignatureDoesNotMatch` — новый секрет, ключ пересоздаётся. `check` (свой проверочный объект для @@ -298,9 +311,19 @@ git ls-files -z -co --exclude-standard | tar --null -T - -cf - | docker build -t стал бы `unhealthy`, живость — журнал. `stop_grace_period: 10s`, лимиты 0,25 CPU / 256 МБ (простой ~90 MiB). В консоли (`make run_dev`) уборщика нет; разовый проход — `docker compose run --rm --no-deps - cleaner --once`. Стенд отказов запускает его с grace 20 с и - интервалом 1 с (`student-tests.md`), `bench/` описывает, но не - запускает. + cleaner --once`. Стенд отказов запускает его с grace 20 с, интервалом + 1 с и без плановой сверки (`RECONCILER__INTERVAL_SECONDS: "0"`, + `student-tests.md`), `bench/` описывает (тоже с 0), но не запускает. + С change `track2-reconciler` сервис ещё и сверяет bucket с БД — при + старте и раз в `[reconciler] interval_seconds` (3600 с); разовая + сверка — `make reconcile [APPLY=1] [MAX_CHANGES=N]` (`docker compose + run --rm --no-deps cleaner reconcile …`). **На время восстановления + базы уборщик останавливают** (`docker compose stop cleaner`): база из + старой копии или пустая при живом bucket сделала бы объекты новых + вложений «объектами без метаданных», и сверка удалила бы их в пределах + `max_changes`. После восстановления — сначала `make reconcile` + (dry-run), потом `docker compose start cleaner` (design change + `track2-reconciler`, Risks). - Конфигурации сервисов (`valkey.conf`, при необходимости `postgresql.conf`, скрипт `infra/s3/bootstrap.sh`) — в `infra/<сервис>/`, монтируются read-only diff --git a/.claude/rules/dto.md b/.claude/rules/dto.md index 593d2f0e..e75eea6e 100644 --- a/.claude/rules/dto.md +++ b/.claude/rules/dto.md @@ -46,3 +46,13 @@ paths: поток на отдачу: тип, размер, асинхронный итератор блоков и `close`. `MessageFullDTO.attachment_ids: tuple[UUID, ...] = ()` — значение по умолчанию последним полем. +- Сверка bucket и БД (design change `track2-reconciler`, решение 8): + `AttachmentFullDTO.lost_at: datetime | None = None` — последним полем + (колонка `lost_at`, в API не уходит); `ReconcileFinding` (классы + `orphan_object`, `missing_object`, `size_mismatch`, `stale_pending`, + `restored_object`, `unknown_object`) и `ReconcileAction` + (`deleted_object`, `marked_lost`, `cleared_lost`, `removed_pending`) — + `StrEnum` в `enums/attachment.py`, в БД не хранятся; + `ReconcileFindingDTO` (класс, ключ, `id`, возраст, размеры) и + `ReconcilePassDTO` (итог прохода; `found` и `fixed` — неизменяемые + отображения `MappingProxyType`, а не `dict`: DTO frozen). diff --git a/.claude/rules/infra.md b/.claude/rules/infra.md index 9cdf9165..0da19d57 100644 --- a/.claude/rules/infra.md +++ b/.claude/rules/infra.md @@ -189,6 +189,20 @@ paths: `seek`, `tell` (сервис передаёт свой `BytesIO`), `size` — в журнал вызова. Не `bytes`: botocore обернул бы его в `BytesIO` с общим буфером, и aiohttp скопировал бы тело при `getbuffer()`; + - `list_page(prefix, *, token, max_keys)` (design change + `track2-reconciler`, решение 3) — страница ListObjectsV2: + `StoredObjectPage` (объекты с размером и `last_modified`, токен + продолжения или `None`). Срок — на страницу, как у любого вызова; у + `_call` ключ необязателен (`None` — вызов без `Key`, в журнал — + префикс). Нет bucket — `ObjectStorageUnavailable` («bucket is + missing»), а не пустая страница: у списка и 404 без тела считается + отсутствующим bucket; отказ в списке — «denied access». + `StoredObjectInfo.last_modified` — из списка и HEAD (часы S3, + точность — секунда), у `open` — `None`. Порядок списка SeaweedFS — + обход каталогов, а не порядок байтов: сверка не сливает + отсортированные потоки, а собирает множество ключей. Префикс — + только `/attachments/` (repo): политика уборщика другие + префиксы запрещает; - адресация `path`: `bucket.s3` Docker DNS не разрешает; простаивающее соединение aiohttp закрывает через `S3_KEEPALIVE_TIMEOUT_SECONDS` (15 с), раньше шлюза (120 с); diff --git a/.claude/rules/logging.md b/.claude/rules/logging.md index 03a23d48..8d5de8fb 100644 --- a/.claude/rules/logging.md +++ b/.claude/rules/logging.md @@ -186,6 +186,30 @@ paths: - Причину отказа пишет нижний слой: клиент S3 (`object_storage`) и `session_scope` (`database`, `warning` «Database is unavailable»); сервис только называет `interrupted_by`. +- Сверка bucket и БД (спек `service-logging`, «Журнал сверки»; design + change `track2-reconciler`, решение 8), модуль + `attachment_reconcile_service`, `method=reconcile`, `apply`: + - находка, которая осталась, — `warning` «Found storage discrepancy»; + исправленная — `info` «Fixed storage discrepancy» с `action` + (`deleted_object`, `marked_lost`, `cleared_lost`, `removed_pending`). + Поля: `kind`, `object_key`, `attachment_id`, `age_seconds`, а + `size_bytes` и `stored_size` — только если размеры разные. Отдельных + записей — не больше `RECONCILE_FINDINGS_LOGGED_MAX` (1000) за проход, + остальные — `unlogged` в итоге; + - итог — «Finished reconcile pass» (`listed_objects`, `checked_rows`, + `found` и `fixed` по классам, `remaining`, `fresh_objects`, + `fresh_rows`, `lost_known`, `refused`, `unlogged`, `interrupted_by`, + `duration_ms`): `info`, если ничего не осталось, иначе `warning`; + - предел — `error` «Reconcile changes exceed limit» (`changes`, + `max_changes`); + - непредвиденная ошибка — `error` «Reconcile pass failed» с traceback + (`cleaner`); «Started cleaner» с change называет ещё `mode`, + `reconcile_interval_seconds`, `reconcile_page_size`, + `reconcile_max_changes`, `reconcile_apply`; + - зависшую загрузку сверка убирает шагом уборщика: «Removed stale + attachment» пишет `attachment_cleanup_service`; + - реплика API на скачивание помеченного оригинала — `info` «Attachment + content is lost» (`attachment_id`, `object_key`), а не `error`. - `filename`, ключей и секретов S3, подписей в записях уборщика нет. ## Где логировать diff --git a/.claude/rules/migrations.md b/.claude/rules/migrations.md index 838d4f70..821028de 100644 --- a/.claude/rules/migrations.md +++ b/.claude/rules/migrations.md @@ -80,6 +80,17 @@ paths: autogenerate условие не видит, ревизия руками. Проверено: с нуля, повтор, откат и снова `upgrade` на асинхронном `env.py`, `indisvalid` — true. + - Ревизия `5c3e1f0a9b7d` (лаба 4, design change `track2-reconciler`, + решение 6): колонка `attachments.lost_at timestamptz NULL` без + значения по умолчанию — время, когда сверка подтвердила потерю + оригинала. Первой строкой `SET LOCAL lock_timeout = '2s'` (`ADD + COLUMN` берёт `ACCESS EXCLUSIVE`, но меняет только каталог — 0,36 мс + на пробе), `downgrade` — `drop_column` с тем же сроком. Индекса нет: + сверка просматривает все `ready`, API читает по `id`; CHECK «помечено + только `ready`» не добавлен (на существующей таблице — `NOT VALID` или + скан под блокировкой), пометку ставит только условный `UPDATE`. + Прежние реплики колонку не читают и не пишут. Проверено на временной + базе: с нуля, повтор, `downgrade -1`, снова `upgrade`, `--sql`; - **INVALID-индекс.** Прерванная `CREATE INDEX CONCURRENTLY` (сбой, `lock_timeout`, Ctrl+C) оставляет индекс с `pg_index.indisvalid = false`, и `IF NOT EXISTS` его не пересоздаст: повтор миграции diff --git a/.claude/rules/repo-layer.md b/.claude/rules/repo-layer.md index fc105292..18034318 100644 --- a/.claude/rules/repo-layer.md +++ b/.claude/rules/repo-layer.md @@ -72,7 +72,17 @@ paths: (`literal(..., literal_execute=True)`), а не параметр: условие частичного индекса `ix_attachments_pending_created_at` планировщик доказывает только по константе, и общий план подготовленного - выражения asyncpg иначе индекс не взял бы; + выражения asyncpg иначе индекс не взял бы. Для сверки bucket и БД + (design change `track2-reconciler`, решения 3–5): + `get_attachments_for_objects` (`id = ANY(:ids) OR object_key = + ANY(:keys)`, параметры-массивы, план — Bitmap OR `pk_attachments` и + `uq_attachments_object_key`, при пустом `keys` — по сути только pk), + `get_ready_page` (keyset `ready` по `id`, Index Scan + `pk_attachments`), `find_attachment_reference` (строка этого `id` или + любая с этим ключом, до двух), `mark_lost` (`UPDATE … SET lost_at + WHERE id AND status = 'ready' AND lost_at IS NULL AND object_key + RETURNING id`) и `clear_lost` (`lost_at IS NOT NULL` и тот же ключ); + `_ATTACHMENT_COLUMNS` выбирает и `lost_at`; - `attachment_object.py` — repo над S3, как `chat_cache.py` над Valkey: первый параметр `storage: ObjectStorage`, один вызов на функцию. `original_key` собирает `/attachments// @@ -80,7 +90,11 @@ paths: `put_original`, `open_original` (контекст объекта), `delete_original` (отсутствие объекта — не ошибка; компенсация загрузки и уборщик). Ключ хранится в - строке и при чтении берётся из неё, не вычисляется заново; + строке и при чтении берётся из неё, не вычисляется заново. Для сверки: + `originals_prefix` (`/attachments/`), `parse_original_key` + (`UUID` ключа `/original` в записи сервера, иначе `None`), + `list_originals` (страница списка), `probe_originals` (список с + `MaxKeys=1`: bucket на месте и список разрешён), `head_original`; - `message.py`: `MESSAGE_COLUMNS` с коррелированным подзапросом `ARRAY(SELECT attachment_id … ORDER BY position)` — одно выражение на страницу и на сохранённый результат ключа; план — `SubPlan` по diff --git a/.claude/rules/run-modes.md b/.claude/rules/run-modes.md index 5701771b..f632fadc 100644 --- a/.claude/rules/run-modes.md +++ b/.claude/rules/run-modes.md @@ -120,6 +120,24 @@ access_log=False)`. Импорты в `src/__main__.py` — внутри `if __n startup», код 0. - `--once` — один проход и выход: 0 — дошёл до конца, 1 — прерван отказом хранилища или ошибкой, 2 — неверная конфигурация. +- С change `track2-reconciler` (решения 1, 8, 9): + - `python -m src.cleaner reconcile [--apply] [--max-changes N]` — + разовая сверка bucket и БД, по умолчанию dry-run; в compose — + `docker compose run --rm --no-deps cleaner reconcile …`, цель `make + reconcile [APPLY=1] [MAX_CHANGES=N]`. Коды: 0 — расхождений нет, 3 — + остались (в том числе чужие объекты и отказ по пределу), 1 — прервана + отказом, ошибкой или сигналом, 2 — конфигурация (в том числе + `--max-changes 0` — ошибка аргумента argparse). Подготовка общая с + сервисом: проверка grace, сигналы, `early_stop.disarm()`, engine, + клиент S3; + - плановая сверка в цикле сервиса: после прохода уборки, если подошёл + срок, — `reconcile(apply=True)` с пределом из настроек; первая — при + старте, следующая — через `[reconciler] interval_seconds` после + конца предыдущей (0 — нет); пауза цикла — меньшее из интервала + уборки и времени до сверки. Пока идёт сверка, уборка ждёт; + - SIGTERM во время сверки: текущий вызов S3 или шаг с БД доводится, + новые страницы и действия не начинаются, итог — `interrupted_by: + stop`; сервис выходит с кодом 0, разовый проход — с 1. - Непредвиденная ошибка прохода — `error` с traceback, процесс живёт до следующего прохода; отказ S3 или PostgreSQL — `warning`, без перезапуска (решение 5). diff --git a/.claude/rules/service-layer.md b/.claude/rules/service-layer.md index 852c7f19..6f0f9705 100644 --- a/.claude/rules/service-layer.md +++ b/.claude/rules/service-layer.md @@ -142,7 +142,41 @@ paths: - чтение: `pending`, нет строки, не участник — одно `AttachmentNotFound`; скачивание — `open_original` вне транзакции, нет объекта или другой размер — `error` в журнале и - `AttachmentContentMissing` (500), строка не меняется; + `AttachmentContentMissing` (500), строка не меняется. Оригинал, + который сверка уже пометила потерянным (`lost_at`, design change + `track2-reconciler`, решение 5), — `info` «Attachment content is + lost» и `AttachmentNotFound` (404) до обращения к S3; метаданные и + `MessageService` эту колонку не смотрят (200 и 201, как у любого + `ready`). Ответ — вариант по умолчанию до ответа преподавателя + (`PLAN.md`, `### track2-reconciler`, «Вопросы», п. 1); + - сверка bucket и БД — `AttachmentReconcileService(db_scope, + storage)` (`services/attachment_reconcile.py`, design change + `track2-reconciler`, решения 3, 4, 7, 8), сервис процесса уборщика: + `reconcile(*, older_than, apply, max_changes, page_size, batch_size, + stop_requested)` → `ReconcilePassDTO`. Проход: + 1. S3 → БД: страницы `list_originals`, на страницу одна выборка + `get_attachments_for_objects` (по `id` стандартных ключей, по + тексту — нестандартных), ключи — в множество `seen`; + 2. БД → S3: `get_ready_page` keyset по `id`, ключа нет в `seen` — + кандидат «метаданные без объекта»; + 3. зависшие — `get_stale_pending`; + 4. перепроверка каждого кандидата в БД (`get_attachment`, + `find_attachment_reference`) и HEAD до решения, в обоих режимах; + отсутствие объекта — только после `probe_originals` (bucket на + месте); + 5. предел `max_changes` (удаления объектов, пометки и снятия пометок; + больше — `error`, ни одного из них, код 3), затем с `apply` по + порядку: зависшие (`AttachmentCleanupService.remove_stale_pending` — + тот же шаг уборщика) → объекты без строки (ещё раз + `find_attachment_reference`, затем `delete_original`) → `mark_lost` + → `clear_lost` (перед каждым — HEAD, условный `UPDATE`, свой + commit). + + Удаляется только объект без строки и зависшая загрузка; `ready`, + объект строки любого статуса и чужой ключ — никогда. Действия + начинаются после классификации: отказ на шагах 1–4 — ни одного + изменения. Отказ S3 или БД — `interrupted_by`, после сигнала — + `stop`; `stop_requested()` — между страницами и действиями; - `MessageService.send_message(..., attachment_ids)`: членство → `get_attachments` (все найдены, чат этого сообщения, `ready`; иначе `AttachmentNotFound` до захвата ключа) → хэш → ключ → сообщение → diff --git a/.claude/rules/settings.md b/.claude/rules/settings.md index 42fa9a51..bbbc3c4b 100644 --- a/.claude/rules/settings.md +++ b/.claude/rules/settings.md @@ -15,7 +15,7 @@ console и docker — `.claude/rules/run-modes.md`. Здесь — откуда - `src/config/settings.py`: `Settings(BaseSettings)` из секций-`BaseModel` (`App`, `Database`, `Auth`, `Cache` — Valkey, `S3`, `Idempotency`, - `Uploads`, `Cleaner`). + `Uploads`, `Cleaner`, `Reconciler`). Экземпляр один — `settings` на уровне модуля. Импорт везде `from src.config import settings`. Второй `Settings()` не создавать, поля в рантайме не менять. @@ -226,6 +226,21 @@ timeout_seconds` (17 с) сама точка входа уборщика, а н - Порт API S3 в сети — `S3_PORT`, на `127.0.0.1` хоста — `S3_OUT_PORT` (8334, как 5433 и 6380). +### Сверка (с change `track2-reconciler`) + +`[reconciler]` (класс `Reconciler`, design change `track2-reconciler`, +решение 10) читает только процесс уборщика: `interval_seconds` (float, +`ge=0`, 3600; 0 — без плановой сверки), `page_size` (int, 1–1000, 1000: +больше 1000 ключей S3 за страницу не отдаёт), `max_changes` (int, +`ge=1`, 100). Значения — в `config.toml`, разовая подмена — +`RECONCILER__*`; разовый проход принимает предел ещё и аргументом +`--max-changes`. Своего grace у сверки нет — `[cleaner] +pending_grace_seconds` и его проверка при старте (одна ручка «свежести»). +Неверное значение — «Invalid cleaner settings» с `loc` поля и код 2, как +у `[cleaner]`. «Started cleaner» называет `reconcile_interval_seconds`, +`reconcile_page_size`, `reconcile_max_changes` и `mode`. Стенд отказов и +`bench/` — `RECONCILER__INTERVAL_SECONDS: "0"`. + `.env.example` skeleton lab2 предлагает «логические» имена: `APP_HOST`, `APP_PORT`, `APP_ENV`, `SESSION_TTL_SECONDS`, `DATABASE_URL_FILE`, `SESSION_STORE`, `CACHE_URL_FILE`; шапка шаблона просит сопоставить их diff --git a/.claude/rules/student-tests.md b/.claude/rules/student-tests.md index c0ff75ea..5156b03b 100644 --- a/.claude/rules/student-tests.md +++ b/.claude/rules/student-tests.md @@ -207,6 +207,50 @@ paths: растёт с числом загрузок» — исключения сверки: `make bench_uploads` → `evidence/uploads/baseline/summary.md` (`bench.md`, профиль `uploads`); +- с change `track2-reconciler` (design, решение 11) — сверка bucket и + БД, тоже проверки отказов, в конце `test_failures.py` (их тесты + оставляют вложения, помеченные потерянными, — `ready` без объекта; + прежние тесты таких не ждут, `ready_without_object`): + - hook: `put-object <ключ>` (тело — stdin фикстуры `stand(..., + stdin=байты)`; `docker exec -i <проект>-api python -c …` — botocore + образа ключами API из окружения контейнера, ключи в hook не + попадают), `delete-object <ключ>` (`weed shell fs.rm`, ошибка — по + выводу), оба — только под `/attachments/` и символы + `[A-Za-z0-9._/-]`; `delete-row`, `set-size`, `age-row` (сдвиг + `created_at` и `updated_at` вместе — CHECK и непомеченность `pending` + сохраняются), `lost-ids`; `fail-attachments mark ` — свой + триггер `BEFORE UPDATE OF lost_at` (08006), `clear-fail-attachments` + снимает и его; `reconcile dry-run|apply [<предел>]` — `docker compose + run --rm --no-deps -T cleaner reconcile …`, записи процесса и строка + `exit_code=`, код hook — 0; `stop|start cleaner` (`start` — + `docker start` контейнера: `compose start` проверял бы зависимость + `migrate`, а её одноразового контейнера нет); `run-cleaner + <секунд>` — `<проект>-cleaner-scheduled` с + `RECONCILER__INTERVAL_SECONDS=1`, затем `docker stop`, журнал и `rm` + (`run_failures.py` убирает его вместе с API); + - уборщик стенда — без плановой сверки (`RECONCILER__INTERVAL_SECONDS: + "0"` в `failures.compose.yml`): иначе она исправляла бы внесённое до + проверки; `run_failures.py` печатает интервал сверки в строке `start + cleaner`; + - тесты: `test_reconcile_finds_and_fixes` (уборщик стоит, A в сообщении + без объекта, B без строки, C с другим размером, O мимо API, P — + `commit`; после G + 1 dry-run — свои классы, код 3, ничего не + изменилось, A — 500; apply — O и B удалены, P убрана, A и C помечены, + A — 404, метаданные — 200; повтор — своих нет), `…_keeps_fresh_used_ + and_unknown`, `…_restored_original`, `…_change_limit`, + `…_object_storage_stopped`, `…_interrupted_by_database`, + `…_under_load` (4 потока ~G + 15 с загрузок PNG ~100 KiB и отправок, + apply раз в 3 с; все 201 скачиваются с тем же SHA-256, новые пометки + — только внесённые), `test_scheduled_reconcile`. Записи + фильтруются по своим `id` и ключам, код выхода сверяется с записями + того же прохода (`Reconcile.assert_code_matches`). Объекты без строки + ждут G + 1 с (`LastModified` ставит S3), строки состаривает + `age-row`; у состаренных и с изменённым размером метаданные + сравниваются без полей, которые изменил сам hook; + - красный прогон на `c13df14` (код до change): упали все восемь — + команды `reconcile` нет (argparse, код 2), колонки `lost_at` нет + (`lost-ids` — ошибка psql), плановой сверки нет + (`evidence/tests/failure-checks.md`); - исключения сверки: «Принявшая реплика остановлена» — `driver.py attachment-failover` → `evidence/attachments/failover.md`; «Байты не в БД и не на диске API» — `driver.py attachment-storage` → @@ -292,8 +336,12 @@ paths: compose и передаёт тестам (`FAULT_CLEANER_GRACE_S`, `FAULT_CLEANER_INTERVAL_S`) и строкой `start cleaner: grace … s, interval … s` в вывод. При падении печатается и журнал уборщика. - Прогон — ~5 мин (37 проверок, pytest ~255 с; до `upload-memory` — - 32 и ~220 с, до `upload-consistency` ~70 с); + С change `track2-reconciler` — без плановой сверки + (`RECONCILER__INTERVAL_SECONDS: "0"`, строка `start cleaner` называет + и её интервал), а `<проект>-cleaner-scheduled` hook `run-cleaner` + убирается вместе с API. Прогон — ~8 мин (45 проверок, pytest ~460 с; + до `track2-reconciler` — 37 и ~255 с, до `upload-memory` — 32 и + ~220 с, до `upload-consistency` ~70 с); - `pytest -m fault`, затем журнал PostgreSQL стенда: сводка `postgres log: N lines, crash markers M; "too many clients" X, "administrator command" Y` после каждого прогона и ненулевой код при признаках diff --git a/.claude/skills/run-mtusi-messenger/SKILL.md b/.claude/skills/run-mtusi-messenger/SKILL.md index d54d1299..701d261d 100644 --- a/.claude/skills/run-mtusi-messenger/SKILL.md +++ b/.claude/skills/run-mtusi-messenger/SKILL.md @@ -24,7 +24,9 @@ s3_check`) — приватность bucket вне API, `attachment-failover` `attachment-storage` — доказательства исключений `attachments` (остановка реплики, принявшей файл; где лежат байты), `upload-consistency` — согласованность БД и S3 (компенсация и уборщик -незавершённых загрузок). `upload` и +незавершённых загрузок), `reconcile-cycle` и `reconcile-stress` — сверка +bucket и БД (расхождения с обеих сторон, dry-run, `--apply`, повтор, +возврат оригинала; `--apply` под загрузками). `upload` и `download` — загрузка и скачивание вложения с SHA-256 на любом сервере. `stop-at-start` — остановка контейнеров образа во время старта, без стенда. Только @@ -116,12 +118,14 @@ python3 $D stop | `hang-key` | только стенд с LB: временный триггер `hang_probe_<метка>` задерживает вставку пробного сообщения на 2 с, реплика с этой транзакцией замораживается `docker pause`, повторы того же `Idempotency-Key` через LB до 201 (сначала 504 от LB или 503 по ожиданию блокировки), разморозка; печатает `idle_in_transaction_session_timeout` соединения приложения и строку журнала PostgreSQL о прерывании. Код 0 — повтор получил 201, в чате одно сообщение, обе реплики снова `UP`. Триггер удаляется и реплика размораживается при любом исходе, в том числе по Ctrl+C, SIGTERM и SIGHUP; если удалить не удалось — печатается SQL удаления и код 1 (от SIGKILL уборки нет) | | `cache-check [--require-test-keys]` | только стенд с LB (`--port 8080`): сценарии `chat-cache` «Чтение из кэша», «Срок записи», «Временная база». Два синтетических пользователя и чат; ключ `messenger:v1:<база>:chat:` сразу после 201 (`EXISTS`, TTL ≤ `[cache] chat_ttl_seconds` из реплики, поля значения), `DEL`, через 11 с снимок `seq_scan + idx_scan` таблицы `chats` и `keyspace_hits` / `keyspace_misses`, 50 чтений через LB, через 11 с второй снимок; TTL до и после ещё 10 чтений; число ключей рабочей и тестовой (`test_`) базы. Код 0 — чтений `chats` ≤ 1, hits ≥ +49, промахов ≤ 1, ответы равны ответу на создание, TTL не продлевается, ≥ 2 `X-Instance-Id`. Для «Временной базы» перед ней — `make test_isolated`: без ключей тестовой базы строка `PASS` заканчивается «temporary database: not checked», с `--require-test-keys` — код 1 (доказательство сценария снимается с флагом). На стенде в это время ничего другого не должно идти. Вывод — `evidence/cache/hits.md` | | `auth-storage` | только стенд с LB: сценарии `users` «Хэш в БД» и `sessions` «Токена нет в хранилище». Пароль P (с `:` и кириллицей) и токен T — только в памяти; через psql — префикс `$argon2id$…` до соли и длина у двух пользователей с одним P, неравенство хэшей, строка `sessions` с `token_hash` = SHA-256(T) (32 байта); `pg_dump --data-only` в память — нет ли T (текстом и в hex) и P. Код 0 — всё так. Вывод — `evidence/auth/passwords-and-tokens.md` | -| `s3-check` | стенд compose (`make s3_check`), без приложения: спек `object-storage` «Проверка приватности вне API». `docker compose run --rm --no-deps s3-bootstrap check` — права ключа API (PUT/GET/HEAD объекта, 404 отсутствующего; 403 на список, создание и удаление bucket, политику и ACL bucket, публичный ACL объекта), права ключа уборщика (GET/HEAD/DELETE своего проверочного объекта, повторный DELETE и DELETE отсутствующего — 204; 403 на запись, список, 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` | +| `s3-check` | стенд compose (`make s3_check`), без приложения: спек `object-storage` «Проверка приватности вне API». `docker compose run --rm --no-deps s3-bootstrap check` — права ключа API (PUT/GET/HEAD объекта, 404 отсутствующего; 403 на список, создание и удаление bucket, политику и ACL bucket, публичный ACL объекта), права ключа уборщика (GET/HEAD/DELETE своего проверочного объекта, повторный DELETE и DELETE отсутствующего — 204; список с префиксом `<база>/attachments/` — 200, с change `track2-reconciler`; 403 на запись, список всего bucket и с чужим префиксом, bucket, политику, ACL), временный чужой bucket (403 на всё обоим ключам), аноним изнутри сервера (403); анонимные запросы с хоста (`127.0.0.1:S3_OUT_PORT`) и из сети стенда (одноразовый контейнер образа S3), порты контейнера S3: слушающие сокеты из `netstat -tuln` в контейнере — вне loopback ровно API S3 и gRPC шлюза, а остальные слушающие порты из сети закрыты (`nc -z`); затем `s3-bootstrap cleanup` и `weed shell` — проверочных объектов и bucket не осталось. Таблица «где → проверка → ожидаемо → получено» без секретов, код 1 при расхождении (печатает нарушенные). Вывод — `evidence/s3/privacy.md` | | `upload --token T --chat C --file F [--type …] [--filename …]` | загрузка файла сырыми байтами (`urllib`): статус, `x-instance-id`, тело `Attachment`, размер и SHA-256 файла, совпал ли `sha256` ответа. `--type` по умолчанию — по сигнатуре (PNG, JPEG, иначе `application/octet-stream`), `--filename` — имя файла. Код 2 при статусе ≥ 400 | | `download --token T --attachment A [--out F] [--variant …]` | скачивание оригинала: статус, `x-instance-id`, `Content-Type`, `Content-Length`, размер и SHA-256 полученного; `--out` сохраняет байты. Код 2 при статусе ≠ 200 (тело ошибки печатается) | | `attachment-failover [--mode stop\|kill]` | только стенд с LB: спек `attachments` «Принявшая реплика остановлена». Синтетические Алиса, Боб, Ева и чат; загрузка `tests/fixtures/sample.png` через LB (реплика A — `X-Instance-Id` ответа), сообщение со ссылкой, `scripts/stop-one.sh` с `TARGET_INSTANCE_ID=A` и `STOP_MODE`, Боб скачивает через LB (до 30 попыток), пока не ответит другая реплика: SHA-256 совпадает, метаданные равны ответу загрузки; Ева — 404 на метаданные и байты. В `finally` — `make replicas`, затем ожидание, пока LB снова видит все реплики `UP`. Печатает `docker compose ps` до и после и таблицу «шаг → ожидаемо → получено → реплика» без токенов. Код 1 при расхождении, без LB (порт консольного процесса драйвера) — код 2. Вывод — `evidence/attachments/failover.md` | | `attachment-storage` | только стенд с LB: спек `attachments` «Байты не в БД и не на диске API». Две загрузки fixture через LB; psql — колонки `attachments` и `message_attachments` (из `bytea` только 32-байтный `sha256`), `object_key` = `<база>/attachments//original` без `filename`; `weed shell fs.ls -l` — объект в bucket и его размер; анонимный GET ключа с `127.0.0.1:S3_OUT_PORT` — 403; скачивание участником — тот же SHA-256; `docker diff` каждой реплики — ни одного файла оригинала. Код 1 с названной проверкой, без LB — код 2. Вывод — `evidence/attachments/storage.md` | | `upload-consistency` | только стенд с LB: спеки `attachments` «Порядок записи» и `storage-consistency` (design change `upload-consistency`, решение 11). Синтетические Алиса, Боб и чат; готовое вложение R. Шаги: (1) `docker compose pause s3` → загрузка через LB — 503 за ~5 с → `unpause` в `finally`; новая строка `pending` по psql (`id`, статус, возраст, ключ); (2) триггер «фиксация `ready` падает» (SQLSTATE 08006) на рабочей базе только для уникального `filename` прогона → загрузка 503 → строка `pending`, объекта уже нет (компенсация), триггер снят (`finally`, и остаток прошлого прогона — в начале); (3) метаданные, байты и сообщение со ссылкой на обе строки — 404; (4) после grace прогона 30 с — `docker compose run --rm --no-deps -e CLEANER__PENDING_GRACE_SECONDS=30 cleaner --once`, его JSON-вывод; (5) psql и `weed shell fs.tree` (файлы `original`, а не каталоги) — ни строк, ни объектов обеих загрузок, объектов без строки под префиксом рабочей базы нет; R скачивается с тем же SHA-256. Таблица «проверка → ожидаемо → получено» без токенов и секретов; код 1 при расхождении, без LB — код 2. ~45 с. Вывод — `evidence/attachments/consistency.md` | +| `reconcile-cycle` | только стенд с LB: спеки `storage-consistency` (сверка bucket и БД) и `attachments` «Потерянный оригинал» (design change `track2-reconciler`, решение 12). (1) исходный dry-run с grace по умолчанию — расхождений нет, иначе код 2; (2) синтетические Алиса, Боб, чат, вложения A (в сообщении), B, C; (3) объект O без строки и чужой ключ X — `docker exec` реплики (botocore образа её ключами), объект A удалён (`weed shell fs.rm`), строка B удалена и размер C изменён (psql), P — триггер COMMIT на уникальный `filename` (503, строка `pending` и объект); (4) после grace 30 с dry-run: таблица «класс → действие → ключ → `id` → возраст», снимки строк, объектов и пометок до и после совпали; (5) байты A — 500; (6) свежий F, `--apply`: O, B удалены, A, C помечены, P убрана, F не тронут, байты A — 404, метаданные A — 200 и равны ответу загрузки, история отдаёт A; (7) повтор — только чужой X, код 3; оператор удаляет X — код 0; после grace F удалён; (8) A возвращён теми же байтами — «оригинал вернулся», байты 200 с тем же SHA-256, итоговый dry-run — код 0. Таблица «проверка → ожидаемо → получено» без токенов; код 1 при расхождении, без LB — код 2. ~2 мин. Вывод — `evidence/reconcile/cycle.md` | +| `reconcile-stress [--seconds S] [--clients N]` | только стенд с LB: «Сверка под нагрузкой». Предусловие — dry-run с grace 20 с без расхождений (иначе код 2); два объекта без строки и два вложения без объекта; N клиентов (4) S секунд (40, больше grace) загружают PNG ~100 KiB из шума и отправляют сообщения, поток сверки — `--apply` с grace 20 с раз в ~3 с, затем ещё один проход. Итог: загрузки по кодам, сообщения, коды проходов, исправления по классам; проверки — внесённые исправлены (объекты удалены, новые пометки — ровно внесённые), каждое 201 скачивается с тем же SHA-256, каждое сообщение отдаёт своё вложение, ни одного прерванного прохода, повтор dry-run — код 0. Проверка корректности, не замер. Вывод — `evidence/reconcile/stress.md` | | `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:lab4`, 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` | | `stop-at-start [--image ТЕГ] [--delays 0.2,0.3,0.4,1.5,5] [--server-start 3]` | спек `graceful-shutdown` «Остановка во время старта»: контейнеры образа (по умолчанию `mtusi-messenger:lab4`) с лимитами реплики (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 всей группе; ждёт, пока порт освободится. Чужой сервер и контейнер не трогает | @@ -173,6 +177,10 @@ python3 $D --port 8080 auth-storage # Argon2id в users, SHA-256 ток python3 $D --port 8080 attachment-failover --mode kill # реплика, принявшая файл, убита: скачивание через другую, тот же SHA-256 python3 $D --port 8080 attachment-storage # байты только в приватном bucket: схема, ключ, объект, аноним 403, docker diff python3 $D --port 8080 upload-consistency # S3 заморожен и сбой ready: 503, pending не видны, компенсация, cleaner --once всё убрал +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 lb-upload-timeouts # сроки LB пути загрузки на заглушке: 201 после 12 с молчания, 504 через 10/30 с, 400 в формате контракта; ~35 с 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 — проход дошёл до конца @@ -373,6 +381,28 @@ make lint # ruff; затрагивает и dr - **Разовый проход уборщика — `docker compose run --rm --no-deps cleaner --once`**: у сервиса `cleaner` точка входа `python -m src.cleaner`, а не `command`, поэтому аргументы после имени сервиса — флаги уборщика. + Так же разовая сверка — `… cleaner reconcile [--apply]` (`make + reconcile`). +- **`reconcile-cycle` и `reconcile-stress` меняют рабочий стенд** + (design change `track2-reconciler`, решение 12): синтетические + пользователи, чаты и вложения остаются в рабочей базе, в том числе + вложения, помеченные потерянными (`lost_at`): у одного изменён размер, + у другого удалён объект; их байты — 404, метаданные — 200. Объекты мимо + API (без строки, чужой ключ, свежий) драйвер удаляет сам — сверкой или + `weed shell fs.rm` в `finally`. Триггер COMMIT — на уникальный + `filename` прогона, снимается в `finally` и в начале следующего. Перед + прогоном стенд должен быть сведён: исходный dry-run с расхождениями — + код 2 и «run make reconcile first». Grace прогона — 30 с (цикл) и 20 с + (стресс), больше границы живой загрузки 17 с. Нужен стенд на коде + change: новая политика S3 уборщика (`docker compose up -d + s3-bootstrap`), колонка `lost_at` (миграция) и образ уборщика с + командой `reconcile`; на прежнем — сверка падает (`AccessDenied` на + списке или нет колонки). Evidence — `evidence/reconcile/cycle.md`, + `evidence/reconcile/stress.md`. +- **Строки `s3-check` о списке уборщика** («cleaner key list attachments + prefix» — 200, «… objects», «… other prefix», «… other bucket» — 403) + печатает сам bootstrap в режиме `check`: разбор драйвера их не знает и + не меняется. - **Пустой каталог `/` в bucket после удаления объекта** SeaweedFS убирает лишь через ~2 мин: `fs.ls` его показывает, список S3 — нет. Объекты считать по файлам `original` (`fs.tree`), а не по каталогам. diff --git a/.claude/skills/run-mtusi-messenger/driver.py b/.claude/skills/run-mtusi-messenger/driver.py index 3c9da70f..54482443 100644 --- a/.claude/skills/run-mtusi-messenger/driver.py +++ b/.claude/skills/run-mtusi-messenger/driver.py @@ -96,6 +96,22 @@ нет, готовое вложение скачивается с тем же SHA-256; триггер снимается в finally и в начале следующего прогона; код 1 при расхождении, без LB — код 2 + reconcile-cycle только стенд с LB: спек storage-consistency, сверка + bucket и БД — исходный dry-run без расхождений (иначе код 2), + расхождения с обеих сторон (объект мимо API и чужой ключ — + docker exec реплики своими ключами, удалённые объекты — weed + shell fs.rm, удалённая строка и другой размер — psql, обрыв + между объектом и фиксацией — триггер COMMIT на уникальный + filename), после grace 30 с dry-run без изменений, 500 до + сверки, --apply, 404 и 200 после, повтор, удаление чужого + объекта, свежий объект после grace, возврат оригинала; код 1 + при расхождении, без LB — код 2 + reconcile-stress [--seconds S] [--clients N] только стенд с LB: + «Сверка под нагрузкой» — внесённые расхождения, N клиентов S + секунд загружают PNG ~100 KiB и отправляют сообщения, поток + сверки — --apply с grace 20 с раз в ~3 с; каждое 201 + скачивается с тем же SHA-256, сообщения отдают свои вложения, + повтор — 0; код 1 при расхождении lb-upload-timeouts [--config F] [--image ТЕГ] без стенда: спек load-balancing «Загрузки через балансировщик» — временная сеть, HAProxy закреплённого образа с конфигурацией F (по @@ -137,6 +153,7 @@ import re import secrets import signal import socket +import struct import subprocess import sys import threading @@ -145,7 +162,9 @@ import urllib.error import urllib.parse import urllib.request import uuid +import zlib from collections import Counter +from collections.abc import Callable from datetime import datetime, timezone from pathlib import Path @@ -2771,6 +2790,826 @@ def report_rows(rows: list[tuple[str, str, str]]) -> int: return 0 +# reconcile-cycle и reconcile-stress (design change track2-reconciler, +# решение 12): разовая сверка — в одноразовом контейнере уборщика стенда с +# grace прогона. Триггер обрыва между объектом и фиксацией — отложенный +# триггер ограничения на уникальный filename: COMMIT перевода в ready +# падает (08006), объект остаётся, строка pending. Имя постоянное: остаток +# прерванного прогона убирается в начале следующего +RC_TRIGGER = "driver_rc_fail_commit" +RC_FAIL_COMMIT_SQL = """\ +CREATE OR REPLACE FUNCTION {name}() RETURNS trigger +LANGUAGE plpgsql AS $$ +BEGIN + IF NEW.filename = TG_ARGV[0] AND OLD.status = 'pending' + AND NEW.status = 'ready' THEN + RAISE EXCEPTION 'driver: attachment ready commit failure' + USING ERRCODE = '08006'; + END IF; + RETURN NULL; +END +$$; +DROP TRIGGER IF EXISTS {name} ON attachments; +CREATE CONSTRAINT TRIGGER {name} AFTER UPDATE ON attachments + DEFERRABLE INITIALLY DEFERRED FOR EACH ROW + EXECUTE FUNCTION {name}('{filename}'); +""" +RC_CLEAR_SQL = f"""\ +DROP TRIGGER IF EXISTS {RC_TRIGGER} ON attachments; +DROP FUNCTION IF EXISTS {RC_TRIGGER}(); +""" +# grace прогона цикла и стресса: больше границы живой загрузки (17 с) +RC_GRACE_S = 30 +RC_STRESS_GRACE_S = 20 +RC_STRESS_PERIOD_S = 3 +RC_STRESS_PAUSE_S = 0.2 +# объект мимо API: botocore образа с настройками процесса реплики (адрес, +# регион, ключи API — из окружения контейнера, в драйвер не попадают) +RC_PUT_OBJECT_PY = """\ +import sys +import botocore.session +from botocore.config import Config +from src.config import settings +s3 = settings.s3 +client = botocore.session.get_session().create_client( + "s3", + endpoint_url=s3.endpoint_url, + region_name=s3.region, + aws_access_key_id=s3.access_key_id.get_secret_value(), + aws_secret_access_key=s3.secret_access_key.get_secret_value(), + config=Config(s3={"addressing_style": "path"}, + retries={"total_max_attempts": 1}), +) +body = sys.stdin.buffer.read() +client.put_object(Bucket=s3.bucket, Key=sys.argv[1], Body=body) +""" +RC_FOUND = "Found storage discrepancy" +RC_FIXED = "Fixed storage discrepancy" +RC_FINISHED = "Finished reconcile pass" + + +def rc_reconcile( + *, + apply: bool, + grace: int | None = None, +) -> tuple[int, list[dict[str, object]]]: + """Разовая сверка в контейнере уборщика: код выхода и записи журнала.""" + env = ( + [] + if grace is None + else ["-e", f"CLEANER__PENDING_GRACE_SECONDS={grace}"] + ) + proc = subprocess.run( + [ + "docker", + "compose", + "run", + "--rm", + "--no-deps", + "-T", + *env, + "cleaner", + "reconcile", + *(["--apply"] if apply else []), + ], + cwd=ROOT, + capture_output=True, + text=True, + check=False, + ) + records = [] + for line in proc.stdout.splitlines(): + if line.startswith("{"): + with contextlib.suppress(json.JSONDecodeError): + records.append(json.loads(line)) + return proc.returncode, records + + +def rc_events( + records: list[dict[str, object]], + event: str, +) -> list[dict[str, object]]: + return [item for item in records if item.get("event") == event] + + +def rc_finished(records: list[dict[str, object]]) -> dict[str, object]: + found = rc_events(records, RC_FINISHED) + return found[-1] if found else {} + + +def rc_print_pass( + title: str, + code: int, + records: list[dict[str, object]], +) -> None: + """Таблица «класс → ключ → id → возраст» прохода и его итог.""" + finished = rc_finished(records) + print(f"{title}: exit {code}") + for record in ( + *rc_events(records, RC_FOUND), + *rc_events(records, RC_FIXED), + ): + action = record.get("action") or "-" + sizes = "" + if record.get("stored_size") is not None: + sizes = ( + f" size {record.get('size_bytes')} stored " + f"{record.get('stored_size')}" + ) + print( + f" {record.get('level', ''):<7} {record.get('kind', ''):<16} " + f"{action:<15} {record.get('object_key')} id " + f"{record.get('attachment_id') or '-'} age " + f"{record.get('age_seconds')} s{sizes}", + ) + keys = ( + "listed_objects", + "checked_rows", + "found", + "fixed", + "remaining", + "fresh_objects", + "fresh_rows", + "lost_known", + "refused", + "interrupted_by", + "duration_ms", + ) + print( + " total: " + ", ".join(f"{key}={finished.get(key)}" for key in keys), + ) + + +def rc_kinds( + records: list[dict[str, object]], + event: str, + names: dict[str, str], +) -> dict[str, str]: + """Свои находки: имя в прогоне → класс (по ключу объекта).""" + by_key = {value: name for name, value in names.items()} + return { + by_key[str(record.get("object_key"))]: str(record.get("kind")) + for record in rc_events(records, event) + if str(record.get("object_key")) in by_key + } + + +def rc_put_object(key: str, data: bytes) -> int: + """Объект мимо API процессом в контейнере реплики; код выхода.""" + replicas = compose("ps", "-q", "--status", "running", "api").split() + if not replicas: + return 1 + proc = subprocess.run( + ["docker", "exec", "-i", replicas[0], "python", "-c", RC_PUT_OBJECT_PY] + + [key], + input=data, + capture_output=True, + check=False, + ) + return proc.returncode + + +def rc_lost_ids() -> set[str]: + return set( + stand_psql( + "SELECT id FROM attachments WHERE lost_at IS NOT NULL;\n", + ).split(), + ) + + +def rc_rows() -> dict[str, str]: + """Строки вложений рабочей базы: `id` → `статус размер`.""" + rows = stand_psql( + "SELECT id || '|' || status || ' ' || size_bytes FROM attachments;\n", + ).splitlines() + return dict(line.split("|") for line in rows if "|" in line) + + +def rc_png(seed: int, *, width: int = 200, height: int = 170) -> bytes: + """Настоящий RGB PNG из шума (~100 KiB при 200 × 170) на stdlib.""" + noise = random_bytes(seed, height * (width * 3)) + rows = b"".join( + b"\x00" + noise[row * width * 3 : (row + 1) * width * 3] + for row in range(height) + ) + + def chunk(kind: bytes, body: bytes) -> bytes: + crc = zlib.crc32(kind + body) + return ( + struct.pack(">I", len(body)) + kind + body + struct.pack(">I", crc) + ) + + header = struct.pack(">IIBBBBB", width, height, 8, 2, 0, 0, 0) + return ( + b"\x89PNG\r\n\x1a\n" + + chunk(b"IHDR", header) + + chunk(b"IDAT", zlib.compress(rows, 1)) + + chunk(b"IEND", b"") + ) + + +def random_bytes(seed: int, size: int) -> bytes: + """Детерминированные «шумовые» байты по зерну: PNG из них почти не + сжимается, и размер файла — около `size`.""" + out = bytearray() + counter = 0 + while len(out) < size: + out += hashlib.sha256(f"{seed}:{counter}".encode()).digest() + counter += 1 + return bytes(out[:size]) + + +def rc_stand() -> tuple[str, str] | None: + """Bucket и имя базы рабочего стенда из `docker compose config`.""" + try: + stand = s3_stand() + config = json.loads(compose("config", "--format", "json")) + database = str( + config["services"]["api"]["environment"]["DATABASE__NAME"], + ) + except (RuntimeError, KeyError, StopIteration, ValueError) as e: + print(f"FAIL: compose config of the stand: {e}") + return None + return stand["bucket"], database + + +def rc_signals(body: Callable[[], int]) -> int: + """SIGTERM и SIGHUP — как Ctrl+C: `finally` тела снимает триггер.""" + + def interrupted(signum: int, _frame: object) -> None: + raise KeyboardInterrupt(signal.Signals(signum).name) + + previous = { + signum: signal.signal(signum, interrupted) + for signum in (signal.SIGTERM, signal.SIGHUP) + } + try: + return body() + finally: + for signum, handler in previous.items(): + signal.signal(signum, handler) + + +def cmd_reconcile_cycle(port: int) -> int: + """Спек `storage-consistency`, сверка bucket и БД на рабочем стенде + через LB (design change `track2-reconciler`, решение 12): исходный + dry-run без расхождений, расхождения с обеих сторон, dry-run без + изменений, 500 до сверки, `--apply`, 404 и 200 после, повтор, удаление + чужого объекта оператором, свежий объект после grace, возврат + оригинала. Триггер — на уникальный `filename`, снимается в `finally` и + в начале следующего прогона. Токенов и секретов в выводе нет.""" + if no_lb(port): + print("reconcile-cycle needs the stand with the load balancer") + return 2 + return rc_signals(lambda: reconcile_cycle(port)) + + +def reconcile_cycle(port: int) -> int: + """Тело `cmd_reconcile_cycle`.""" + names = rc_stand() + if names is None: + return 1 + bucket, database = names + prefix = f"{database}/{ATTACHMENT_KEY_PREFIX}" + stand_psql(RC_CLEAR_SQL) + rows: list[tuple[str, str, str]] = [] + + # 1. исходный dry-run с grace по умолчанию: стенд сведён + code, records = rc_reconcile(apply=False) + rc_print_pass("initial dry-run (default grace)", code, records) + if code != 0 or rc_events(records, RC_FOUND): + print("FAIL: the stand is not reconciled, run make reconcile first") + return 2 + + # 2. участники и вложения через LB + people = attachment_people(port, "rc") + if people is None: + return 1 + _, tokens, chat_id = people + data = FIXTURE_PNG.read_bytes() + tag = uuid.uuid4().hex[:8] + uploaded: dict[str, dict[str, object]] = {} + for name in ("A", "B", "C"): + status, _, attachment = upload_bytes( + port, + tokens["alice"], + chat_id, + data, + content_type="image/png", + filename=f"rc-{tag}-{name}.png", + ) + rows.append((f"upload {name}", "201", str(status))) + if status != 201 or not isinstance(attachment, dict): + return report_reconcile(rows) + uploaded[name] = attachment + status, _, message = call( + port, + "POST", + f"{CHATS}/{chat_id}/messages", + token=tokens["alice"], + body={"text": "", "attachment_ids": [uploaded["A"]["id"]]}, + extra=key_header(), + ) + rows.append(("message with A", "201", str(status))) + message_id = message.get("id") if isinstance(message, dict) else None + keys = { + name: f"{prefix}/{attachment['id']}/{ATTACHMENT_ORIGINAL}" + for name, attachment in uploaded.items() + } + keys["O"] = f"{prefix}/{uuid.uuid4()}/{ATTACHMENT_ORIGINAL}" + keys["X"] = f"{prefix}/x-{uuid.uuid4()}" + ids = { + name: str(attachment["id"]) for name, attachment in uploaded.items() + } + try: + # 3. расхождения с обеих сторон + rows.append( + ("put O without a row", "0", str(rc_put_object(keys["O"], data))), + ) + rows.append( + ("put X (unknown key)", "0", str(rc_put_object(keys["X"], data))), + ) + weed_shell(f"fs.rm /buckets/{bucket}/{keys['A']}") + # id — UUID из ответа API: безопасны в тексте SQL + stand_psql(f"DELETE FROM attachments WHERE id = '{ids['B']}';\n") + stand_psql( + "UPDATE attachments SET size_bytes = size_bytes + 1 " + f"WHERE id = '{ids['C']}';\n", + ) + fail_name = f"rc-{tag}-P.png" + before = attachment_statuses() + stand_psql( + RC_FAIL_COMMIT_SQL.format(name=RC_TRIGGER, filename=fail_name), + ) + status, _, _ = upload_bytes( + port, + tokens["alice"], + chat_id, + data, + content_type="image/png", + filename=fail_name, + ) + stand_psql(RC_CLEAR_SQL) + rows.append(("upload P with COMMIT failure", "503", str(status))) + pending = sorted(set(attachment_statuses()) - set(before)) + rows.append(("pending rows of P", "1", str(len(pending)))) + if len(pending) != 1: + return report_reconcile(rows) + ids["P"] = pending[0] + keys["P"] = f"{prefix}/{ids['P']}/{ATTACHMENT_ORIGINAL}" + print("keys of the run:") + for name, key in sorted(keys.items()): + print(f" {name}: {key}") + + # 4. после grace прогона — dry-run без изменений + print(f"waiting {RC_GRACE_S + 1} s for grace {RC_GRACE_S} s") + time.sleep(RC_GRACE_S + 1) + snapshot = ( + rc_rows(), + stored_attachment_ids(bucket, database), + rc_lost_ids(), + ) + code, records = rc_reconcile(apply=False, grace=RC_GRACE_S) + rc_print_pass(f"dry-run (grace {RC_GRACE_S} s)", code, records) + after = ( + rc_rows(), + stored_attachment_ids(bucket, database), + rc_lost_ids(), + ) + rows.append(("dry-run exit code", "3", str(code))) + found = rc_kinds(records, RC_FOUND, keys) + for name, kind in ( + ("O", "orphan_object"), + ("B", "orphan_object"), + ("A", "missing_object"), + ("C", "size_mismatch"), + ("P", "stale_pending"), + ("X", "unknown_object"), + ): + rows.append((f"dry-run finds {name}", kind, found.get(name, "-"))) + rows.append( + ( + "dry-run changes rows, objects, marks", + "no", + "no" if after == snapshot else "yes", + ), + ) + + # 5. байты потерянного до сверки + status, _, _ = call_bytes( + port, + "GET", + f"{ATTACHMENTS}/{ids['A']}/content", + token=tokens["bob"], + ) + rows.append(("A content before apply", "500", str(status))) + + # 6. --apply; свежий объект F записан прямо перед ним + keys["F"] = f"{prefix}/{uuid.uuid4()}/{ATTACHMENT_ORIGINAL}" + rows.append(("put fresh F", "0", str(rc_put_object(keys["F"], data)))) + fresh_written = time.monotonic() + code, records = rc_reconcile(apply=True, grace=RC_GRACE_S) + rc_print_pass(f"apply (grace {RC_GRACE_S} s)", code, records) + rows.append(("apply exit code (X left)", "3", str(code))) + fixed = { + name: str(record.get("action")) + for record in rc_events(records, RC_FIXED) + for name, key in keys.items() + if record.get("object_key") == key + } + for name, action in ( + ("O", "deleted_object"), + ("B", "deleted_object"), + ("A", "marked_lost"), + ("C", "marked_lost"), + ("P", "removed_pending"), + ): + rows.append((f"apply fixes {name}", action, fixed.get(name, "-"))) + rows.append(("apply touches F (fresh)", "-", fixed.get("F", "-"))) + stored = stored_attachment_ids(bucket, database) + statuses = attachment_statuses() + lost = rc_lost_ids() + rows.append( + ("A and C marked lost", "yes", yes({ids["A"], ids["C"]} <= lost)), + ) + rows.append( + ( + "P row and object", + "absent", + "present" + if ids["P"] in statuses or ids["P"] in stored + else "absent", + ), + ) + for name in ("O", "B"): + object_id = keys[name].split("/")[-2] + rows.append( + ( + f"object {name}", + "absent", + "present" if object_id in stored else "absent", + ), + ) + rows.append( + ( + "fresh F kept", + "present", + "present" if keys["F"].split("/")[-2] in stored else "absent", + ), + ) + status, _, _ = call_bytes( + port, + "GET", + f"{ATTACHMENTS}/{ids['A']}/content", + token=tokens["bob"], + ) + rows.append(("A content after apply", "404", str(status))) + status, _, meta = call( + port, + "GET", + f"{ATTACHMENTS}/{ids['A']}", + token=tokens["bob"], + ) + rows.append(("A metadata after apply", "200", str(status))) + rows.append( + ( + "A metadata = upload response", + "yes", + yes(meta == uploaded["A"]), + ), + ) + status, _, page = call( + port, + "GET", + f"{CHATS}/{chat_id}/messages", + token=tokens["bob"], + ) + linked = [ + item.get("attachment_ids") + for item in ( + page.get("items", []) if isinstance(page, dict) else [] + ) + if item.get("id") == message_id + ] + rows.append( + ( + "history keeps A in the message", + "yes", + yes(linked == [[ids["A"]]]), + ), + ) + + # 7. повтор: остался только чужой X; оператор удаляет его + code, records = rc_reconcile(apply=False, grace=RC_GRACE_S) + rc_print_pass("repeat dry-run", code, records) + found = rc_kinds(records, RC_FOUND, keys) + rows.append( + ("repeat finds only X", "X", ",".join(sorted(found)) or "-"), + ) + rows.append(("repeat exit code", "3", str(code))) + weed_shell(f"fs.rm /buckets/{bucket}/{keys['X']}") + print("operator removed X (weed shell fs.rm)") + code, records = rc_reconcile(apply=False, grace=RC_GRACE_S) + rc_print_pass("dry-run after X is removed", code, records) + rows.append(("exit code after X is removed", "0", str(code))) + wait = max(0.0, fresh_written + RC_GRACE_S + 1 - time.monotonic()) + print(f"waiting {wait:.0f} s until F is older than grace") + time.sleep(wait) + code, records = rc_reconcile(apply=True, grace=RC_GRACE_S) + rc_print_pass("apply after F aged", code, records) + fixed = rc_kinds(records, RC_FIXED, keys) + rows.append( + ("F removed after grace", "orphan_object", fixed.get("F", "-")), + ) + rows.append(("apply exit code (F)", "0", str(code))) + + # 8. возврат оригинала + rows.append( + ("put A original back", "0", str(rc_put_object(keys["A"], data))), + ) + code, records = rc_reconcile(apply=True, grace=RC_GRACE_S) + rc_print_pass("apply after A is back", code, records) + fixed = rc_kinds(records, RC_FIXED, keys) + rows.append(("A restored", "restored_object", fixed.get("A", "-"))) + status, _, payload = call_bytes( + port, + "GET", + f"{ATTACHMENTS}/{ids['A']}/content", + token=tokens["bob"], + ) + rows.append(("A content after restore", "200", str(status))) + rows.append( + ( + "A sha256 = uploaded", + "yes", + yes(sha256_hex(payload) == uploaded["A"]["sha256"]), + ), + ) + code, records = rc_reconcile(apply=False, grace=RC_GRACE_S) + rc_print_pass("final dry-run", code, records) + rows.append(("final dry-run exit code", "0", str(code))) + finally: + stand_psql(RC_CLEAR_SQL) + # чужой и свежий объект не остаются при любом исходе + for name in ("X", "F", "O"): + if name in keys: + weed_shell(f"fs.rm /buckets/{bucket}/{keys[name]}") + triggers = stand_psql( + f"SELECT count(*) FROM pg_trigger WHERE tgname = '{RC_TRIGGER}';\n", + ).strip() + rows.append(("driver trigger left", "0", triggers)) + return report_reconcile(rows) + + +def yes(value: bool) -> str: + return "yes" if value else "no" + + +def report_reconcile(rows: list[tuple[str, str, str]]) -> int: + """Таблица «проверка → ожидаемо → получено»; код 1 при расхождении.""" + width = max(len(check) for check, _, _ in rows) + failed = 0 + for check, expected, got in rows: + ok = expected == got + failed += not ok + print( + f"{check:<{width}} expected {expected:<15} got {got}" + + ("" if ok else " FAIL"), + ) + if failed: + print(f"FAIL: {failed} check(s) failed") + return 1 + print("PASS: reconcile found and fixed the discrepancies, repeat found 0") + return 0 + + +def cmd_reconcile_stress(port: int, *, seconds: float, clients: int) -> int: + """Спек `storage-consistency`, «Сверка под нагрузкой», на рабочем + стенде через LB (design change `track2-reconciler`, решение 12): + внесённые расхождения, `clients` клиентов `seconds` секунд загружают + PNG ~100 KiB и отправляют сообщения, поток сверки — `--apply` с grace + 20 с раз в ~3 с. В конце — каждое 201 скачивается с тем же SHA-256, + каждое сообщение отдаёт своё вложение, повтор — 0. Проверка + корректности, не замер: тихий хост не нужен.""" + if no_lb(port): + print("reconcile-stress needs the stand with the load balancer") + return 2 + if seconds <= RC_STRESS_GRACE_S: + print(f"--seconds must be longer than grace {RC_STRESS_GRACE_S} s") + return 2 + return rc_signals(lambda: reconcile_stress(port, seconds, clients)) + + +def reconcile_stress(port: int, seconds: float, clients: int) -> int: + """Тело `cmd_reconcile_stress`.""" + names = rc_stand() + if names is None: + return 1 + bucket, database = names + prefix = f"{database}/{ATTACHMENT_KEY_PREFIX}" + code, records = rc_reconcile(apply=False, grace=RC_STRESS_GRACE_S) + rc_print_pass( + f"precondition dry-run (grace {RC_STRESS_GRACE_S} s)", + code, + records, + ) + if code != 0 or rc_events(records, RC_FOUND): + print("FAIL: the stand is not reconciled, run make reconcile first") + return 2 + people = attachment_people(port, "rs") + if people is None: + return 1 + _, tokens, chat_id = people + data = FIXTURE_PNG.read_bytes() + rows: list[tuple[str, str, str]] = [] + orphans = [ + f"{prefix}/{uuid.uuid4()}/{ATTACHMENT_ORIGINAL}" for _ in range(2) + ] + for key in orphans: + rows.append( + ("put object without a row", "0", str(rc_put_object(key, data))), + ) + injected: list[str] = [] + for _ in range(2): + status, _, attachment = upload_bytes( + port, + tokens["alice"], + chat_id, + data, + content_type="image/png", + filename="rs-lost.png", + ) + if status != 201 or not isinstance(attachment, dict): + print(f"FAIL: upload {status}") + return 1 + injected.append(str(attachment["id"])) + weed_shell( + f"fs.rm /buckets/{bucket}/{prefix}/{attachment['id']}/" + f"{ATTACHMENT_ORIGINAL}", + ) + lost_before = rc_lost_ids() + deadline = time.monotonic() + seconds + lock = threading.Lock() + uploads: dict[str, str] = {} + messages: dict[str, str] = {} + codes: Counter[int] = Counter() + passes: list[tuple[int, list[dict[str, object]]]] = [] + errors: list[str] = [] + + def load(worker: int) -> None: + token = tokens["alice"] if worker % 2 == 0 else tokens["bob"] + number = 0 + while time.monotonic() < deadline: + number += 1 + body = rc_png(worker * 1_000_000 + number) + status, _, attachment = upload_bytes( + port, + token, + chat_id, + body, + content_type="image/png", + filename="rs.png", + ) + with lock: + codes[status] += 1 + if status != 201 or not isinstance(attachment, dict): + continue + attachment_id = str(attachment["id"]) + with lock: + uploads[attachment_id] = sha256_hex(body) + status, _, message = call( + port, + "POST", + f"{CHATS}/{chat_id}/messages", + token=token, + body={"text": "", "attachment_ids": [attachment_id]}, + extra=key_header(), + timeout=30, + ) + if status == 201 and isinstance(message, dict): + with lock: + messages[str(message["id"])] = attachment_id + else: + with lock: + errors.append(f"message {status}") + # пауза клиента: синтетические объекты остаются в рабочем + # bucket, без неё 4 клиента за 40 с пишут ~5 800 по 100 KiB + time.sleep(RC_STRESS_PAUSE_S) + + def reconcile() -> None: + while time.monotonic() < deadline: + started = time.monotonic() + passes.append(rc_reconcile(apply=True, grace=RC_STRESS_GRACE_S)) + time.sleep( + max(0.0, started + RC_STRESS_PERIOD_S - time.monotonic()), + ) + + def guarded(target: Callable[..., None], *args: object) -> None: + try: + target(*args) + except Exception as e: # noqa: BLE001 — в отчёт, а не в stderr + with lock: + errors.append(repr(e)) + + print( + f"load: {clients} clients for {seconds:.0f} s, apply every {RC_STRESS_PERIOD_S} s", + ) + threads = [ + threading.Thread(target=guarded, args=(load, worker)) + for worker in range(clients) + ] + threads.append(threading.Thread(target=guarded, args=(reconcile,))) + for thread in threads: + thread.start() + for thread in threads: + thread.join() + # проход после нагрузки: всё внесённое уже старше grace + final_code, final_records = rc_reconcile( + apply=True, + grace=RC_STRESS_GRACE_S, + ) + passes.append((final_code, final_records)) + fixed: Counter[str] = Counter() + for _, pass_records in passes: + for record in rc_events(pass_records, RC_FIXED): + fixed[str(record.get("kind"))] += 1 + stored = stored_attachment_ids(bucket, database) + lost_new = rc_lost_ids() - lost_before + mismatched = 0 + for attachment_id, digest in uploads.items(): + status, _, payload = call_bytes( + port, + "GET", + f"{ATTACHMENTS}/{attachment_id}/content", + token=tokens["bob"], + ) + if status != 200 or sha256_hex(payload) != digest: + mismatched += 1 + history: dict[str, list[object]] = {} + cursor = None + while True: + path = f"{CHATS}/{chat_id}/messages?limit=100" + if cursor: + path += "&" + urllib.parse.urlencode({"cursor": cursor}) + status, _, page = call(port, "GET", path, token=tokens["alice"]) + if status != 200 or not isinstance(page, dict): + errors.append(f"history {status}") + break + for item in page["items"]: + history[str(item["id"])] = item["attachment_ids"] + cursor = page.get("next_cursor") + if not cursor: + break + broken = sum( + history.get(message_id) != [attachment_id] + for message_id, attachment_id in messages.items() + ) + code, records = rc_reconcile(apply=False, grace=RC_STRESS_GRACE_S) + rc_print_pass("repeat dry-run", code, records) + print( + "uploads by status: " + + ", ".join(f"{k}={v}" for k, v in sorted(codes.items())), + ) + print(f"messages sent: {len(messages)}") + print("reconcile passes: " + ", ".join(str(item[0]) for item in passes)) + print( + "fixed by class: " + + (", ".join(f"{k}={v}" for k, v in sorted(fixed.items())) or "-"), + ) + rows.append(("uploads 201", ">0", ">0" if uploads else "0")) + rows.append( + ( + "uploads not 201", + "0", + str(sum(v for k, v in codes.items() if k != 201)), + ), + ) + rows.append( + ( + "passes interrupted (exit 1)", + "0", + str(sum(item[0] == 1 for item in passes)), + ), + ) + rows.append( + ( + "objects without a row removed", + "yes", + yes(not {key.split("/")[-2] for key in orphans} & stored), + ), + ) + rows.append( + ("new lost marks = injected", "yes", yes(lost_new == set(injected))), + ) + rows.append(("downloads with other sha256", "0", str(mismatched))) + rows.append(("messages with unavailable attachment", "0", str(broken))) + rows.append(("thread errors", "0", str(len(errors)))) + rows.append(("repeat dry-run exit code", "0", str(code))) + for error in errors[:5]: + print(f" error: {error}") + return report_reconcile(rows) + + # lb-upload-timeouts: сроки LB пути загрузки на заглушке (design change # upload-memory, решение 7). Молчание заглушки: дольше timeout server # прочих путей (10 с), но меньше срока пути загрузки (30 с) — и дольше его @@ -3574,6 +4413,10 @@ def main() -> int: failover.add_argument("--mode", choices=("stop", "kill"), default="stop") sub.add_parser("attachment-storage") sub.add_parser("upload-consistency") + sub.add_parser("reconcile-cycle") + stress = sub.add_parser("reconcile-stress") + stress.add_argument("--seconds", type=float, default=40) + stress.add_argument("--clients", type=int, default=4) lbto = sub.add_parser("lb-upload-timeouts") lbto.add_argument( "--config", @@ -3667,6 +4510,14 @@ def main() -> int: return cmd_attachment_storage(port) if args.cmd == "upload-consistency": return cmd_upload_consistency(port) + if args.cmd == "reconcile-cycle": + return cmd_reconcile_cycle(port) + if args.cmd == "reconcile-stress": + return cmd_reconcile_stress( + port, + seconds=args.seconds, + clients=args.clients, + ) if args.cmd == "lb-upload-timeouts": return cmd_lb_upload_timeouts(args.config, args.image) if args.cmd == "stop-at-start": diff --git a/AGENTS.md b/AGENTS.md index 26381ce1..82fcc046 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -147,6 +147,22 @@ structlog (JSON в stdout), redis-py (клиент Valkey), aiobotocore `ready` уборщик не трогает. У уборщика свой пользователь S3 — только чтение и удаление объектов своего bucket, ключи `S3_CLEANER_*` только у него и bootstrap (`docker.md`, `settings.md`). +- Лаба 4, сверка bucket и БД (change `track2-reconciler`, трек 2): её + делает процесс уборщика — разовая `make reconcile [APPLY=1]` (по + умолчанию dry-run; коды 0 / 3 / 1 / 2) и плановая в сервисе `cleaner` + при старте и раз в `[reconciler] interval_seconds` (3600 с) с + исправлением. Удаляется только объект без строки старше grace и + зависшая загрузка (шагом уборщика); строки `ready`, объект, на который + ссылается строка, и чужой ключ — никогда. Grace — тот же `[cleaner] + pending_grace_seconds`, по `LastModified` объекта и времени строки; + перед каждым действием — перепроверка в БД и HEAD, отсутствие объекта — + только при живом bucket; больше `[reconciler] max_changes` (100) + изменений — ни одного и код 3. Потерянный оригинал помечается + (`attachments.lost_at`): скачивание — 404, метаданные — 200, ссылка — + 201 (вопрос преподавателю, `PLAN.md`). Уборщику разрешён список только + с префиксом `<база>/attachments/` (`S3_CLEANER_LIST_PREFIX` у + bootstrap). На время восстановления базы уборщик останавливают + (`docker.md`). - Лаба 4, память загрузок (change `upload-memory`): память загрузок реплики ограничена числом мест, а не числом клиентов. Место берётся после проверок 401/400/404/415/413 и до чтения тела, держится до @@ -339,6 +355,9 @@ structlog (JSON в stdout), redis-py (клиент Valkey), aiobotocore | `driver.py --port attachment-storage` | схема таблиц вложений, вид `object_key`, объект в bucket, анонимный GET — 403, `docker diff` реплик; доказательство исключения «Байты не в БД и не на диске API» | | `driver.py --port upload-consistency` | согласованность БД и S3 на рабочем стенде (~45 с): загрузка при `pause` S3 и со сбоем фиксации `ready` (триггер на `filename` прогона) — 503, строки `pending` не видны, компенсация удалила объект; `cleaner --once` с grace 30 с убирает обе, объектов без строки нет, готовое вложение цело; `evidence/attachments/consistency.md` | | `driver.py lb-upload-timeouts [--config F]` | сроки LB пути загрузки без стенда (~35 с): `haproxy -c`, временная сеть, HAProxy закреплённого образа с F (по умолчанию `infra/haproxy/haproxy.cfg`) и заглушка реплики `api` на образе API; молчание 12 с до и после тела загрузки — 201, 12 с на другом пути — 504 через ~10 с, 32 с на пути загрузки — 504 через ~30 с, клиент молчит посреди тела — 400 в формате контракта; уборка при любом исходе, код 1 при расхождении; `evidence/uploads/lb-timeouts.md` | +| `make reconcile [APPLY=1] [MAX_CHANGES=N]` | разовая сверка bucket и БД в контейнере уборщика (`docker compose run --rm --no-deps cleaner reconcile [--apply] [--max-changes N]`): по умолчанию dry-run — записи «Found storage discrepancy» по классам и итог; `APPLY=1` — исправить; 0 — расхождений нет, 3 — остались (чужие объекты, отказ по пределу), 1 — прервана, 2 — конфигурация | +| `driver.py --port reconcile-cycle` | сверка на рабочем стенде (~2 мин): исходный dry-run без расхождений (иначе код 2), расхождения с обеих сторон, dry-run без изменений, 500 → `--apply` → 404 и 200, повтор, удаление чужого объекта, свежий объект после grace, возврат оригинала; `evidence/reconcile/cycle.md` | +| `driver.py --port reconcile-stress [--seconds S] [--clients N]` | `--apply` раз в ~3 с под загрузками и отправками N клиентов S секунд (4 × 40 с): внесённое исправлено, каждое 201 скачивается с тем же SHA-256, повтор — 0; `evidence/reconcile/stress.md` | | `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` прежнего образа упадёт на новой ревизии) | @@ -384,8 +403,8 @@ src/ __main__.py # python -m src: early_stop.install() до импорта приложения → main.main() main.py # FastAPI app: lifespan, middlewares, обработчики ошибок, uvicorn.run 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, цикл с интервалом, SIGTERM — довести текущий шаг строки и выйти 0, --once — коды 0/1/2 - 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 + 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] — разовая сверка, коды 0/3/1/2 + 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 api/ routers/health.py # /health/live, /health/ready: вне версии, без идентификации routers/v1/.py # ручки под /api/v1, сборка в routers/v1/__init__.py; Idempotency-Key — параметр POST сообщения (message.py); attachment.py — один роутер с двумя префиксами: загрузка (тело через request.stream(), схема — openapi_extra, строгий UTF-8 filename по scope["query_string"]), метаданные, байты StreamingResponse @@ -397,12 +416,13 @@ src/ repos/.py # атомарный доступ к хранилищу, модульные функции repos/idempotency.py # ключ идемпотентности: захват ON CONFLICT DO UPDATE WHERE просрочен, чтение сохранённого результата repos/chat_cache.py # карточка чата в Valkey: ключ с именем базы, JSON ↔ ChatFullDTO - repos/attachment.py # строки вложений: вставка pending (created_at = updated_at), mark_ready (pending и непомеченная → ready RETURNING), чтение одной и до 10; уборщику — get_stale_pending (keyset по частичному индексу), lock_stale_pending (FOR UPDATE SKIP LOCKED), mark_removing (пометка updated_at), delete_attachment - repos/attachment_object.py # оригинал в S3: ключ <база>/attachments//original, put_original (поток BytesIO и size, без копии тела), open, delete_original + repos/attachment.py # строки вложений: вставка pending (created_at = updated_at), mark_ready (pending и непомеченная → ready RETURNING), чтение одной и до 10; уборщику — get_stale_pending (keyset по частичному индексу), lock_stale_pending (FOR UPDATE SKIP LOCKED), mark_removing (пометка updated_at), delete_attachment; сверке — get_attachments_for_objects (id = ANY OR object_key = ANY), get_ready_page (keyset ready по id), find_attachment_reference, mark_lost / clear_lost (условный UPDATE lost_at) + repos/attachment_object.py # оригинал в S3: ключ <база>/attachments//original, put_original (поток BytesIO и size, без копии тела), open, delete_original; сверке — originals_prefix, parse_original_key, list_originals, probe_originals (bucket на месте), head_original repos/message.py # MESSAGE_COLUMNS с ARRAY(подзапрос attachment_ids по position), вставка связей одной вставкой services/.py # Service: логика, проверки доступа, id и время, логи; чаты и сообщения — с кэшем; отправка — ключ, сообщение и связи с вложениями одной транзакцией services/attachment.py # AttachmentService(db_scope, cache, storage, slots): загрузка (проверки → место загрузки, 429 → тело со счётчиком и сроком в BytesIO, 400 по сроку → структура и SHA-256 в потоке над getvalue() → del → pending → PUT тем же BytesIO → ready; сбой ready до COMMIT или пропавшая строка — удаление объекта и 503; место — до ответа), метаданные, отдача потоком - services/attachment_cleanup.py # AttachmentCleanupService(db_scope, storage): проход уборщика — кандидаты keyset, каждая строка в два шага: блокировка и пометка (commit) → блокировка, DELETE объекта и DELETE строки (commit); отказ S3 или БД прерывает проход, SIGTERM — после текущего шага; CleanupPassDTO + 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 (bucket — probe), предел изменений, действия с apply (зависшие шагом уборщика → объекты без строки → пометки → снятия); журнал Found / Fixed / Finished; ReconcilePassDTO exceptions/.py # доменные исключения, реэкспорт в __init__.py; storage.py — ObjectStorageUnavailable (503) и StoredObjectMissing; attachment.py — 404, 413, 415, 400 обрыва и срока тела (UploadTimedOut), 429 занятых мест (UploadsBusy), 500 пропавшего объекта infra/ early_stop.py # ранний обработчик SIGTERM/SIGINT (только stdlib): до старта сервера — запись «Stopped <процесс> before startup» (API, cleaner) и выход 0; disarm() — первая строка lifespan; write_record — запись мимо structlog @@ -413,14 +433,14 @@ src/ db/session.py # глобалы engine и session_factory процесса API db/scope.py # session_scope(factory, timeout_seconds): сессия на шаг, срок, отказ БД → invalidate, warning, ServiceUnavailable; общая для API и уборщика db/errors.py # is_db_unavailable: какие ошибки драйвера — 503 - db/models/ # модели SQLAlchemy (Base с created_at и to_dict); idempotency.py — ключи, FK на сообщение отложен до commit; attachment.py — Attachment (частичный индекс pending по (created_at, id)) и MessageAttachment (порядок position, FK без каскада) + db/models/ # модели SQLAlchemy (Base с created_at и to_dict); idempotency.py — ключи, FK на сообщение отложен до commit; attachment.py — Attachment (частичный индекс pending по (created_at, id), lost_at — пометка потерянного оригинала) и MessageAttachment (порядок position, FK без каскада) cache/client.py # create_cache (redis-py: повтор только на обрыв, блокирующий пул), Cache: срок на команду, отказ — промах и пропуск cache/instance.py # глобал cache процесса API - s3/client.py # create_object_storage (aiobotocore: path-адресация, без повторов, пул), ObjectStorage: put (поток read/seek/tell и size) / head / open (чтение блоками) / delete, срок на вызов и блок, ошибки → ObjectStorageUnavailable / StoredObjectMissing; StoredObjectInfo, StoredObject + s3/client.py # create_object_storage (aiobotocore: path-адресация, без повторов, пул), ObjectStorage: put (поток read/seek/tell и size) / head / open (чтение блоками) / delete / list_page (ListObjectsV2 по префиксу, нет bucket — ошибка), срок на вызов и блок, ошибки → ObjectStorageUnavailable / StoredObjectMissing; StoredObjectInfo (с last_modified), StoredObject, StoredObjectPage s3/instance.py # глобал object_storage процесса API, namespace — имя базы; start() и aclose() в lifespan schemas/ dataclasses/.py # DTO между repo → service → api - enums/.py # StrEnum доменов, RunModeEnum; attachment.py — AttachmentStatus, ImageType + enums/.py # StrEnum доменов, RunModeEnum; attachment.py — AttachmentStatus, ImageType, ReconcileFinding, ReconcileAction utils/ constants.py # лимиты контракта (с лабы 4 — 10 MiB, 40 млн пикселей, filename, 10 вложений), размер страницы, префиксы путей, имя bucket S3, разделитель и части ключа объекта, keep-alive клиента S3 image.py # inspect_image: структурная проверка PNG/JPEG без декодирования пикселей (stdlib), тип, размеры, UnsupportedImage / DamagedImage / TooManyPixels @@ -439,9 +459,9 @@ student-tests/ # black-box тесты по HTTP (уровень 4) test_.py # сценарии основных спеков, маркер @pytest.mark.spec test_failures.py # проверки отказов (маркер fault): только make failure_checks run_isolated.py # make test_isolated: образ на временной базе test_, уборка базы и префикса test_/ в S3 (weed shell fs.rm, затем проверка fs.ls: код 0 weed shell успеха не значит; префикс только из проверенного имени) (stdlib) - run_failures.py # make failure_checks: стенд <рабочий>-failures (Postgres, Valkey, S3 + bootstrap, уборщик с grace 20 с и интервалом 1 с → FAULT_CLEANER_*), три API (обычный, «тесный», «узкий по загрузкам» с UPLOADS_ENV → FAULT_UPLOADS_BASE_URL / FAULT_UPLOADS_ENV), pytest -m fault, журнал PostgreSQL стенда (сводка, признаки аварии — ненулевой код), журналы API и уборщика при падении, уборка (stdlib) - fault_hook.py # hook стенда отказов: stop/start/pause/unpause postgres|valkey|s3, кэш, триггеры сбоя участников, сообщений и вложений (fail-attachments insert|ready|stall|commit|outlive|undeletable: сбой вставки, перевода в ready до и на COMMIT, задержка, строка «старше grace» с ожиданием уборщика, неудаляемая строка), заполнение слотов max_connections, счётчик сессий PostgreSQL db-sessions, attachment-ids, last-pending, object-ids (файлы original по fs.tree), kill-api / start-api (stdlib) - failures.compose.yml # override стенда отказов: без публикации портов (Postgres, Valkey, S3, LB), уборщик с CLEANER__* 20 / 1 и restart "no", stop_grace_period 2 с у S3, healthcheck PostgreSQL — на служебную базу postgres (не добавляет сессий в базу приложения), init: true у PostgreSQL (сирот psql из fill-connections подбирает init, а не postmaster) + run_failures.py # make failure_checks: стенд <рабочий>-failures (Postgres, Valkey, S3 + bootstrap, уборщик с grace 20 с и интервалом 1 с без плановой сверки → FAULT_CLEANER_*, FAULT_RECONCILER_INTERVAL_S; уборщик с плановой сверкой <проект>-cleaner-scheduled убирается вместе с API), три API (обычный, «тесный», «узкий по загрузкам» с UPLOADS_ENV → FAULT_UPLOADS_BASE_URL / FAULT_UPLOADS_ENV), pytest -m fault, журнал PostgreSQL стенда (сводка, признаки аварии — ненулевой код), журналы API и уборщика при падении, уборка (stdlib) + fault_hook.py # hook стенда отказов: stop/start/pause/unpause postgres|valkey|s3, кэш, триггеры сбоя участников, сообщений и вложений (fail-attachments insert|ready|stall|commit|outlive|undeletable: сбой вставки, перевода в ready до и на COMMIT, задержка, строка «старше grace» с ожиданием уборщика, неудаляемая строка), заполнение слотов max_connections, счётчик сессий PostgreSQL db-sessions, attachment-ids, last-pending, object-ids (файлы original по fs.tree), kill-api / start-api; расхождения и сверка (change track2-reconciler): put-object (тело — stdin, botocore в контейнере API его ключами) / delete-object (weed fs.rm) только под <база>/attachments/, delete-row, set-size, age-row, lost-ids, fail-attachments mark, reconcile dry-run|apply [предел] (записи и exit_code=), stop|start cleaner, run-cleaner <с> (stdlib) + failures.compose.yml # override стенда отказов: без публикации портов (Postgres, Valkey, S3, LB), уборщик с CLEANER__* 20 / 1, RECONCILER__INTERVAL_SECONDS 0 и restart "no", stop_grace_period 2 с у S3, healthcheck PostgreSQL — на служебную базу postgres (не добавляет сессий в базу приложения), init: true у PostgreSQL (сирот psql из fill-connections подбирает init, а не postmaster) bench/ # нагрузочный стенд на HAProxy + N реплик API + Postgres + Valkey: make bench / bench_quick / bench_restore / bench_failover / bench_rollout / bench_scaling / bench_uploads (с S3) run.py # оркестратор: стенд compose, реплики и готовность по LB, фоновые чаты и расписание наполнения, матрица, обслуживание БД, планы и варианты, пробы записи, backup и восстановление во второе хранилище со сверкой, фазы профиля failover (события цели — поток docker events по контейнеру, а не буфер демона), профиль rollout (образ прежнего commit через git archive, scripts/rolling-update.sh против проекта стенда, поток событий Docker с exec_start), ресурсы профилей failover и rollout (Profile.sample_resources: сэмплер scan, карта контейнеров по меткам compose, окна, бюджет на пике, сторож), серии трека 1 (профили scaling_*, ячейки на свежем стенде, ступени k6 и поиск R*, сэмплер, продолжение RESUME, блокировка bench/.bench.lock), метрики (сумма по репликам), runs.csv / phases.csv / searches.csv / samples.csv / summary.md / meta.json; профиль uploads (S3 и bootstrap на стенде, на прогон — новый volume S3 и реплика с окружением варианта через .work/variant.compose.yml, образ «до» — тег bench-from, сэмплер peak), в паспорте всех профилей stand.api_tcp_rmem и docker.kernel scaling.py # серии трека 1 без docker: лестница и автомат поиска R*, разбор итога k6 и строк сэмплера, агрегаты окна, вердикт SLO и брака генератора, признаки узкого места (THRESHOLDS), предельный CPU на запрос, сводка серии; --selftest @@ -456,10 +476,10 @@ bench/ # нагрузочный стенд на HAProxy + k6/ # сценарии k6 (через LB http://haproxy:8080): prepare (вход по Basic, фоновые чаты), prefill (по расписанию), cursors, plan_cursors (страницы плана фоновых чатов), explain, read, tail, write, after_backup и restore_check (этап восстановления), failover (постоянная интенсивность записи и чтения, строка на запрос) и retry (повтор неуспешных записей с тем же ключом), mixed (ступень серии трека 1: ramping-arrival-rate 70/20/10, тег окна, распределение по X-Instance-Id, досрочный выход), uploads (constant-vus загрузок тела из /work, пауза Retry-After на 429 и 1 с на прочие ошибки, строка на запрос, WARMUP — одна загрузка); lib.js — Bearer, messageHeaders (новый или заданный Idempotency-Key) и хелперы compare.py # make bench_compare: дельта двух меток (ячейки матрицы или общие конфигурации серий), уровень шума, эффект или шум; отказ при разной методике, в том числе метке без LB и серии против матрицы ab.py # make bench_ab: прогоны «до» и «после» одного изменения подряд, с --series — серии трека 1 -migrations/, alembic.ini # ревизии alembic, async env.py; применяет одноразовый сервис compose; 739b8f04d5fb — частичный индекс pending CONCURRENTLY в autocommit_block +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, пользователи api и cleaner с ключами из .env, проверки приватности обоих ключей; check (и строки ключа уборщика) и cleanup — для make s3_check; секреты — stdin weed shell и файл curl на tmpfs + 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 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 с); 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 diff --git a/KNOWN_ISSUES.md b/KNOWN_ISSUES.md index ad3fbe34..da1a10ae 100644 --- a/KNOWN_ISSUES.md +++ b/KNOWN_ISSUES.md @@ -3,24 +3,35 @@ Найдены попутно, не исправлены без отдельной просьбы (AGENTS.md). Исправленные удаляются отсюда, история — в git. -## Bootstrap после удаления bucket: «api key put (code 500)» +## Bootstrap после удаления bucket на маленьком диске: «api key wait (code 500)» -- **Где:** `infra/s3/bootstrap.sh` (режим `apply`), SeaweedFS 4.48. -- **Что:** на временном стенде bucket удалили вручную, повторный - bootstrap написал «bucket created», затем «FAILED: api key put (code - 500)». Предположение: SeaweedFS не принимает запись в заново созданный - bucket с тем же именем сразу после удаления. Причина не установлена: - контейнер S3 в тот момент мог перезапускаться. Найдено в правках по - verify change `s3-storage` (2026-10-20), в evidence не входит. -- **Чем грозит:** восстановление стенда после удаления bucket мимо API - не проходит одним повтором bootstrap. Штатный путь (bucket не - удаляют) не затронут. -- **Предложение:** воспроизвести на свежем стенде (`fs.rm` / `s3.bucket.delete`, - затем `docker compose run --rm s3-bootstrap`). Если повторяется — - bootstrap после создания bucket ждёт, пока проверочная запись пройдёт - (повтор с ограниченным сроком), и описать это в `docker.md`. Удобно - разобрать в change `track2-reconciler`: там ошибки на стороне S3 - вносятся намеренно. +- **Где:** `infra/s3/bootstrap.sh` (режим `apply`) и сервер `s3` + (`docker-compose.yml`: entrypoint образа добавляет `-volume.max=0 + -master.volumeSizeLimitMB=1024`), SeaweedFS 4.48. +- **Что:** после удаления bucket мимо bootstrap (`s3.bucket.delete`) + повторный bootstrap пишет «bucket created», затем «FAILED: api key wait + (code 500)». Найдено в правках по verify change `s3-storage` + (2026-10-20); воспроизведено и объяснено пробой design change + `track2-reconciler` (Context, 2026-10-22, проект `rcprobe`). +- **Причина:** не повторное имя bucket, а слоты томов. С `-volume.max=0` + число слотов считается по свободному месту диска / 1 ГиБ. Удаление + bucket удаляет тома его коллекции, но на маленьком диске слоты уже + заняты томами коллекции по умолчанию (журналы filer), и новых томов для + `messenger` выделить некуда: в журнале S3 — «No writable volumes and no + free volumes left for collection:messenger», PUT получает 500. +- **Условие:** диск, на котором `-volume.max=0` даёт мало слотов, — tmpfs + проб, а не volume стендов проекта. Проба: tmpfs 4 ГБ — 3 слота из 3 + заняты, ошибка дважды подряд; tmpfs 16 ГБ — 15 слотов, повтор + bootstrap прошёл за 2 с. Рабочий стенд (volume на диске ВМ) — 417 + слотов, 403 свободны (`weed shell volume.list`): удаление bucket и + повтор bootstrap этим не падают. Стенды проекта не затронуты. +- **Чем грозит:** только временным стендам на маленьком tmpfs: после + удаления bucket повтор bootstrap не проходит. Сверка bucket и БД + bucket не создаёт и не удаляет: на `NoSuchBucket` она прерывает проход + без изменений (design change `track2-reconciler`, решение 14). +- **Предложение:** на маленьких дисках — `-master.volumeSizeLimitMB` + меньше 1024 (больше слотов на тот же объём) или явный `-volume.max`; + для стендов проекта не нужно. Запись остаётся открытой. ## LB отвечает 408 на медленные заголовки текстом HAProxy diff --git a/Makefile b/Makefile index 78f0d355..b499dc87 100644 --- a/Makefile +++ b/Makefile @@ -207,6 +207,15 @@ stop_s3: s3_check: $(PYTHON) .claude/skills/run-mtusi-messenger/driver.py s3-check +# разовая сверка bucket и БД в контейнере уборщика (образ собирает +# make run_docker): по умолчанию dry-run — отчёт без изменений; APPLY=1 — +# исправить, MAX_CHANGES=N — предел изменений прохода вместо [reconciler] +# max_changes. Код 0 — расхождений нет, 3 — остались, 1 — прерван, 2 — +# конфигурация (design change track2-reconciler, решения 1 и 8) +.PHONY: reconcile +reconcile: + $(DC) run --rm --no-deps cleaner reconcile$(if $(filter 1,$(APPLY)), --apply)$(if $(MAX_CHANGES), --max-changes $(MAX_CHANGES)) + # ------------------------- # Реплики за балансировщиком (HAProxy) diff --git a/PLAN.md b/PLAN.md index 551c7949..4bfe2e1b 100644 --- a/PLAN.md +++ b/PLAN.md @@ -1205,6 +1205,25 @@ SeaweedFS и PostgreSQL на tmpfs, bootstrap проекта. На 16 ГБ повтор bootstrap прошёл за 2 с. У рабочего стенда 403 свободных слота. Reconciler bucket не создаёт, поэтому запись не чинится. В apply её текст переписывается, запись остаётся открытой. +12. **Решения apply (2026-10-22)** — подробно design, «Уточнения apply»: + - потерянный оригинал — вариант (а) до ответа на вопрос 1; + - `ReconcileAction` (названия действий), в итоге — `remaining` и + `unlogged`, `found` / `fixed` — `MappingProxyType`; + - шаг уборщика публичный (`remove_stale_pending`): сверка убирает + зависшие по одной, с записью «Fixed» на каждую; + - у `--apply` исправленное — `info` «Fixed», оставшееся — `warning` + «Found»; + - перед каждым действием — ещё одна проверка его условия (HEAD, + условный `UPDATE`, ссылки на ключ), перед пометками — снова bucket; + - свежие чужие объекты и объекты без `LastModified` — свежие; + - отказ после сигнала — `interrupted_by: stop`; + - 404 у списка — отсутствующий bucket; + - ревизия `5c3e1f0a9b7d`; планы: страница по `id` — BitmapOr, 1,5 мс, + keyset `ready` — Index Scan `pk_attachments`, 0,57 мс; + - hook `start cleaner` — `docker start` контейнера (`compose start` + требует контейнер `migrate`); + - драйвер на рабочем стенде — только после перестройки 12.1; в apply + он проверен на временном полном стенде. #### Вопросы @@ -1232,3 +1251,14 @@ SeaweedFS и PostgreSQL на tmpfs, bootstrap проекта. `test_reconcile_finds_and_fixes` и `REPORT.md`. Классы, правила безопасности, схема и задачи сверки не меняются (design, Open Questions). + + **Состояние на apply 2026-10-22:** ответа нет, сделан вариант (а) + (поручение основной сессии). Строки, которые поменяет ответ «иначе»: + ветка `lost_at` в `AttachmentService.open_content` + (`src/core/services/attachment.py`), для (б) — ещё проверка `lost_at` + в `get_attachment` и `MessageService` (выборка вложений сообщения); + сценарий `attachments` «Потерянный оригинал», `assert_lost_content` и + ожидания `test_reconcile_finds_and_fixes`, + `test_reconcile_keeps_fresh_used_and_unknown`, + `test_reconcile_restored_original`, шаги 5–6 и 8 `driver.py + reconcile-cycle`, правило `api-contract.md`. diff --git a/bench/bench.compose.yml b/bench/bench.compose.yml index 26e5110e..c79fdb26 100644 --- a/bench/bench.compose.yml +++ b/bench/bench.compose.yml @@ -64,12 +64,17 @@ services: # уборщик незавершённых загрузок (design change upload-consistency, # решение 9) описан, как s3, и тоже не запускается: старт стенда # перечисляет сервисы, реплики — с --no-deps. Если его всё же запустят — - # образ стенда, без config.toml рабочего стенда, без перезапуска + # образ стенда, без config.toml рабочего стенда, без перезапуска и без + # плановой сверки bucket и БД: профиль сверки (change + # track2-reconcile-cost) задаст её интервал сам (design change + # track2-reconciler, решение 9) cleaner: container_name: mtusi-bench-cleaner image: mtusi-messenger:bench restart: "no" volumes: !reset [] + environment: + RECONCILER__INTERVAL_SECONDS: "0" migrate: image: mtusi-messenger:bench diff --git a/config_example.toml b/config_example.toml index 421e63ba..32206039 100644 --- a/config_example.toml +++ b/config_example.toml @@ -105,3 +105,15 @@ interval_seconds = 60 pending_grace_seconds = 900 # строк pending в одной выборке кандидатов batch_size = 100 + +[reconciler] +# Сверка bucket и БД процессом уборщика: плановая в сервисе cleaner и +# разовая — make reconcile. Grace — [cleaner] pending_grace_seconds. +# Разовая подмена — окружением RECONCILER__*. +# секунды между плановыми сверками; 0 — без плановой сверки +interval_seconds = 3600 +# ключей на страницу списка S3 и строк на запрос к PostgreSQL, 1–1000 +page_size = 1000 +# предел изменений за проход: больше — ни одного изменения и код 3; +# разовый проход принимает больший аргументом --max-changes +max_changes = 100 diff --git a/docker-compose.yml b/docker-compose.yml index 9358d046..24d7f16d 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -242,6 +242,10 @@ 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} + # список объектов уборщику — только по префиксу вложений своей базы + # (сверка bucket и БД, design change track2-reconciler, решение 2); + # не секрет, уборщик строит префикс сам из имени базы + S3_CLEANER_LIST_PREFIX: ${POSTGRES_DB:?POSTGRES_DB is not set, run make env_setup}/attachments/ HOME: /tmp volumes: - type: bind diff --git a/infra/s3/bootstrap.sh b/infra/s3/bootstrap.sh index 4534fd58..d2d9c7bc 100755 --- a/infra/s3/bootstrap.sh +++ b/infra/s3/bootstrap.sh @@ -1,9 +1,11 @@ #!/bin/sh # Bootstrap S3 стенда (SeaweedFS): приватный bucket, пользователь API с # политикой «только объекты своего bucket», пользователь уборщика с -# политикой «чтение и удаление объектов своего bucket», проверки -# приватности вне API. Design change s3-storage, решения 3, 4 и 8, design -# change upload-consistency, решение 8; правила — docker.md. +# политикой «чтение и удаление объектов своего bucket и их список только по +# префиксу вложений своей базы» (S3_CLEANER_LIST_PREFIX, <база>/attachments/: +# для сверки bucket и БД), проверки приватности вне API. Design change +# s3-storage, решения 3, 4 и 8, design change upload-consistency, решение 8, +# design change track2-reconciler, решение 2; правила — docker.md. # # Запускается сервисом compose s3-bootstrap на образе сервера в сетевом # пространстве сервиса s3 (network_mode: service:s3): master и filer @@ -17,7 +19,8 @@ # check — ничего не менять в настройке, проверить права и приватность # шире, чем apply: чужой bucket (временный, создаётся и удаляется # здесь же), административные запросы ключей API и уборщика, запись -# и список ключом уборщика, анонимные запросы. Общий проверочный +# ключом уборщика, его список по своему префиксу (200), без префикса и +# с чужим (403), анонимные запросы. Общий проверочный # объект остаётся для проверок с хоста и из сети (make s3_check) до # режима cleanup; объект проверок удаления ключом уборщика — свой; # cleanup — удалить проверочные объекты и временные bucket-ы check. @@ -35,6 +38,9 @@ S3_PORT=${S3_PORT:?S3_PORT is not set} : "${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}" : "${WEED_JWT_FILER_SIGNING_KEY:?S3_JWT_SIGNING_KEY is empty, copy S3 lines from .env.example}" +# префикс списка уборщика: имя базы и /attachments/; в JSON политики идёт +# только проверенное значение +LIST_PREFIX=${S3_CLEANER_LIST_PREFIX:-} MASTER=127.0.0.1:9333 S3=http://127.0.0.1:${S3_PORT} @@ -228,11 +234,40 @@ EOF ws_step "policy put $1" "s3.policy -put -name=$1 -file=$WORK/policy.json" } +# префикс списка уборщика — только вида <база>/attachments/: иначе в +# условие политики попало бы что угодно +check_list_prefix() { + database=${LIST_PREFIX%/attachments/} + # ^[a-z0-9_]+/attachments/$: суффикс на месте, имя базы непустое и без + # других символов (в том числе перевода строки и «/») + case "$database" in + "$LIST_PREFIX" | "" | *[!a-z0-9_]*) + fail "cleaner list prefix: S3_CLEANER_LIST_PREFIX must be /attachments/" + ;; + esac +} + +# уборщику — чтение и удаление объектов своего bucket и их список только с +# префиксом вложений своей базы (условие s3:prefix соблюдает SeaweedFS 4.48: +# весь bucket, другой префикс и HEAD bucket — 403); без записи и прав на +# bucket (design change track2-reconciler, решение 2) +put_cleaner_policy() { + cat >"$WORK/policy.json" < None: + # expand (design change track2-reconciler, решение 6): пометка + # потерянного оригинала. Колонка NULL без значения по умолчанию — только + # каталог, без перезаписи таблицы, но ACCESS EXCLUSIVE на attachments: + # lock_timeout, чтобы чужая долгая транзакция не остановила загрузки + # всех реплик в очереди за миграцией (migrations.md). Прежние реплики + # колонку не читают и не пишут: их выборки перечисляют свои колонки + op.execute("SET LOCAL lock_timeout = '2s'") + op.add_column( + "attachments", + sa.Column("lost_at", sa.DateTime(timezone=True), nullable=True), + ) + + +def downgrade() -> None: + op.execute("SET LOCAL lock_timeout = '2s'") + op.drop_column("attachments", "lost_at") diff --git a/openspec/changes/track2-reconciler/design.md b/openspec/changes/track2-reconciler/design.md index 780e482a..e882c1bd 100644 --- a/openspec/changes/track2-reconciler/design.md +++ b/openspec/changes/track2-reconciler/design.md @@ -720,3 +720,122 @@ cleaner reconcile …`, как у `upload-consistency`. Ответ меняет ветку `open_content` (и выборку вложений сообщения, если ссылку тоже запретить), сценарий `attachments` «Потерянный оригинал» и тест. Классы, правила безопасности, схема и задачи сверки не меняются. + +## Уточнения apply + +Решения, принятые в `/opsx:apply` (2026-10-22) без вопроса пользователю: +мелкие, по спекам и решениям выше. + +1. **Ответ на потерянный оригинал — вариант (а)** по поручению основной + сессии: вопрос 1 `PLAN.md` открыт, сделано по умолчанию (решение 5). +2. **`ReconcileAction`** — второй `StrEnum` рядом с `ReconcileFinding`: + названия действий в записях «Fixed» (`deleted_object`, `marked_lost`, + `cleared_lost`, `removed_pending`) — значения enum, а не литералы. +3. **`ReconcilePassDTO`** сверх решения 8: `remaining` (сколько + подтверждённых осталось — по нему код 0 / 3) и `unlogged` (сколько + находок не записано из-за `RECONCILE_FINDINGS_LOGGED_MAX`). `found` и + `fixed` — `MappingProxyType`: DTO frozen, `dict` в нём был бы + изменяемым (`dto.md`). +4. **Шаг уборщика — публичный.** `AttachmentCleanupService._remove` + стал `remove_stale_pending` (поведение то же, `clean_stale_pending` + зовёт его), и сверка с `--apply` убирает зависшие загрузки им по + одной, а не `clean_stale_pending` целиком (решение 7): так у каждой + убранной загрузки своя запись «Fixed … removed_pending» с `id`, как у + остальных классов, а кандидаты — те же, что в dry-run. +5. **Какие записи у `--apply`.** Исправленное — только `info` «Fixed», + оставшееся (чужой объект, отказ по пределу, прерванный проход) — + `warning` «Found» в конце прохода. Так требует сценарий + `service-logging` «Журнал разового прохода» (в `--apply` — две записи + `info`, а не четыре). +6. **Перепроверка и перед самим действием.** Шаг 4 перепроверяет всех + кандидатов в обоих режимах; с `--apply` каждое действие ещё раз + проверяет своё условие непосредственно перед собой: объект без строки + — `find_attachment_reference`, пометка и снятие пометки — HEAD и + условный `UPDATE`; перед первой пометкой bucket проверяется ещё раз + (`probe_originals`). Не подтвердилось на действии — находка выбывает + без записи и не считается оставшейся. +7. **Свежий чужой объект — свежий.** Грейс действует на все объекты + списка, в том числе чужие ключи: «свежее не считается расхождением» + (спек «Безопасность сверки»). Объект без `LastModified` считается + свежим: удалять без доказанного возраста нельзя. +8. **Отказ после сигнала — остановка.** Если вызов S3 или шаг с БД + упал, когда сигнал уже пришёл (вызов ждал замороженный S3 до срока), + `interrupted_by` — `stop`: этого ждёт сценарий `graceful-shutdown` + «docker stop во время сверки». Причину отказа всё равно записал + нижний слой (`object_storage`, `database`). +9. **404 без тела у списка — отсутствующий bucket.** Клиент переводит + `NoSuchKey` / `404` у `list_objects_v2` в «bucket is missing»: у списка + «объекта нет» не бывает, а пустой список вместо ошибки сделал бы + удалённый bucket «потерей всех оригиналов». +10. **Цикл сервиса.** После прохода уборки — плановая сверка, если + подошёл срок; пауза — меньшее из `[cleaner] interval_seconds` и + времени до сверки. `--once` плановой сверки не делает (как раньше — + один проход уборки). +11. **Проверка префикса bootstrap** — `case`, а не `grep -x`: значение с + переводом строки (`x\n<база>/attachments/`) `grep -x` пропустил бы + по второй строке. Проверка — до любого шага в режимах `apply` и + `check`. Список своего префикса в `apply` проверяется с ожиданием + (`wait_key 200`): новая политика доходит до шлюза подпиской, как + ключ. +12. **Ревизия `5c3e1f0a9b7d`** (`2026_10_22_1200-…_added_attachments_lost_at.py`). + Проверка на временной базе `rc_lost_at_probe` рабочего PostgreSQL: + с нуля — все 7 ревизий, повтор — без изменений, `downgrade -1` и + снова `upgrade`, `\d attachments` — `lost_at timestamp with time + zone`, без значения по умолчанию; `--sql` 739b8f04d5fb:head — `SET + LOCAL lock_timeout = '2s'` перед `ALTER TABLE attachments ADD COLUMN + lost_at TIMESTAMP WITH TIME ZONE`. +13. **Планы (задача 4.3)** — та же база, 21 000 строк (20 000 `ready`), + `VACUUM (ANALYZE)`, общий план (`plan_cache_mode = + force_generic_plan`, `PREPARE` текста, который рендерит SQLAlchemy для + asyncpg): + - страница 1000 `id`, пустой `keys` — Bitmap Heap Scan ← BitmapOr + (`pk_attachments`, 1000 строк, 0,41 мс; `uq_attachments_object_key` + — 0 поисков), 1,5 мс, 652 буфера; + - 1000 `id` и 2 нестандартных ключа — тот же BitmapOr, по ключам — 1 + поиск, 0,6 мс; + - keyset `ready` по `id` с середины, 1000 строк — Index Scan + `pk_attachments` (`id > $2`, статус — фильтр), 0,57 мс. + + Параметры — массивы (`= ANY($1::UUID[])`), а не список `IN`: план не + зависит от длины страницы. +14. **Проба клиента и bootstrap (задачи 4.4 и 8.1)** — проект `rcapply` + (SeaweedFS проекта на tmpfs 16 ГБ, синтетические секреты, bootstrap и + `docker-compose.yml` проекта): bootstrap трижды — код 0 (bucket и + пользователи созданы, затем «exists»); префиксы `messenger/`, `*`, + `messenger/attachments/x`, пустой, `a/b/attachments/`, с переводом + строки, `Messenger/attachments/` — «FAILED: cleaner list prefix» и + код 1; `check` — «cleaner key list attachments prefix» 200, «… + objects», «… other prefix», «… other bucket» 403. Клиентом проекта + ключом уборщика: 2 504 ключа под префиксом — 3 страницы по 1000 за + 0,29 с, все ключи, у каждого `LastModified`; весь bucket, префикс + `messenger/other/` и `test_messenger/attachments/` — + `ObjectStorageUnavailable` («denied access», `AccessDenied`); после + `s3.bucket.delete` список и `probe_originals` — + `ObjectStorageUnavailable` («bucket is missing», `NoSuchBucket`), а не + пустая страница. Проект удалён, список volumes совпал с исходным + (155). +15. **Hook: `start cleaner` — `docker start` контейнера.** `docker compose + start cleaner` проверяет зависимости сервиса, а `migrate` стенд + запускает `run --rm` — его контейнера нет («cleaner is missing + dependency migrate»; найдено первым прогоном новых тестов на новом + коде). +16. **Фикстура `stand(..., stdin=байты)`** — тело `put-object`; + `subprocess` фикстуры — в байтовом режиме (stdout и stderr + декодируются сами), прежние действия stdin не читают. +17. **Метаданные состаренных строк.** `age-row` сдвигает `created_at` и + `updated_at`, `set-size` меняет `size_bytes` — это поля ответа API. + Тесты сравнивают метаданные помеченных с ответом загрузки без полей, + которые изменил сам hook (`assert_lost_content(aged=True)`, у C — + размер из `set-size`); пометка сверки полей ответа не меняет — это + проверяет вложение A без таких правок. Первый прогон новых тестов на + новом коде падал именно на этом (дефект теста: ожидание + противоречило его же внесённому изменению). +18. **Драйвер на рабочем стенде — только после 12.1.** `reconcile-cycle` + и `reconcile-stress` нужны колонка `lost_at`, новая политика S3 + уборщика и образ с командой `reconcile`; до `docker compose up -d + s3-bootstrap` и `make rolling_update` сверка на рабочем стенде падает + (`AccessDenied` на списке, нет колонки). Рабочий стенд в apply не + перестраивается (поручение основной сессии), поэтому проверка + драйвера в задачах 10.1–10.2 — на временном полном стенде (проект + compose с LB, своими хранилищами на tmpfs и портами); на рабочем — в + группе 12. diff --git a/openspec/changes/track2-reconciler/tasks.md b/openspec/changes/track2-reconciler/tasks.md index cd99625e..a63b392a 100644 --- a/openspec/changes/track2-reconciler/tasks.md +++ b/openspec/changes/track2-reconciler/tasks.md @@ -29,7 +29,7 @@ Commit делает основная сессия после подтвержд ## 1. Hook, стенд отказов, тесты и красный прогон -- [ ] 1.1 `student-tests/fault_hook.py` по решению 11 (только stdlib, +- [x] 1.1 `student-tests/fault_hook.py` по решению 11 (только stdlib, синтаксис 3.9, docstring — новые действия): - `put-object <ключ>`: тело из stdin, `docker exec -i <проект>-api python -c …` — botocore образа с ключами API из окружения @@ -51,7 +51,7 @@ Commit делает основная сессия после подтвержд Ключей и секретов hook не печатает и не получает. Проверка: `make lint`; поведение — 1.4 и группа 9. -- [ ] 1.2 Стенд отказов: +- [x] 1.2 Стенд отказов: - `failures.compose.yml`: у `cleaner` — `RECONCILER__INTERVAL_SECONDS: "0"` с комментарием (решение 9); - `run_failures.py`: `<проект>-cleaner-scheduled` — в списке уборки и @@ -61,7 +61,12 @@ Commit делает основная сессия после подтвержд Проверка: `make failure_checks FAULT_ARGS='-k readiness'` — стенд поднят и убран, контейнеров и volumes проекта отказов после команды нет. -- [ ] 1.3 Тесты в `student-tests/test_failures.py` по таблице решения 11 + + Apply: вместо отдельного `-k readiness` — прогоны `-k reconcile` и + полный 9.2: строка «start cleaner: grace 20 s, interval 1 s, reconcile + interval 0 s (0 — off)», после команды контейнеров проекта отказов 0, + volumes — 155, как до. +- [x] 1.3 Тесты в `student-tests/test_failures.py` по таблице решения 11 — восемь тестов с маркерами `fault` и `spec`: - `test_reconcile_finds_and_fixes`; - `test_reconcile_keeps_fresh_used_and_unknown`; @@ -80,7 +85,7 @@ Commit делает основная сессия после подтвержд - объекты без строки ждут G + 1 с, остальные — `age-row`; - остановки — `with outage(...)`; - клиенты потоков — со сроком 30 с. -- [ ] 1.4 Красный прогон до кода групп 2–7: `make failure_checks +- [x] 1.4 Красный прогон до кода групп 2–7: `make failure_checks FAULT_ARGS='-k reconcile'` на нынешнем коде (`5f4b9ff`). Ожидаемо падают все восемь: команды `reconcile` нет (argparse — код 2), колонки `lost_at` нет (`lost-ids` — ошибка hook). Число упавших и причины — в @@ -88,9 +93,21 @@ Commit делает основная сессия после подтвержд `evidence/tests/failure-checks.md` (задача 12.6). Рабочий стенд не трогается. + Прогон (2026-10-22): код приложения `c13df14` (код тот же, что + `5f4b9ff`: после него только документы), тесты окончательные — `git + archive c13df14` в scratch с тестами и hook рабочего дерева, `python3 + student-tests/run_failures.py -k reconcile`: **8 failed** за 95 с. + Причины: `lost-ids` и `fail-attachments mark` — нет колонки `lost_at` + (`finds_and_fixes`, `under_load`, `interrupted_by_database`); команды + `reconcile` нет — код 2 и ни одной записи (`keeps_fresh_used_and_ + unknown`, `restored_original`, `change_limit` — 2 вместо 3, + `object_storage_stopped` — 2 вместо 1); плановой сверки нет — + `scheduled_reconcile`. Первый прогон того же кода до правок тестов + тоже дал 8 failed (вывод обрезан). Сводка без токенов — для 12.6. + ## 2. Настройки, константы, enum и DTO -- [ ] 2.1 Секция `[reconciler]` по решению 10 и дельте +- [x] 2.1 Секция `[reconciler]` по решению 10 и дельте `service-configuration`: - класс `Reconciler` в `src/config/settings.py`: `interval_seconds` (float, ≥ 0, 3600), `page_size` (int, 1–1000, 1000), `max_changes` @@ -102,7 +119,7 @@ Commit делает основная сессия после подтвержд print(settings.reconciler)"` — значения по умолчанию; `RECONCILER__PAGE_SIZE=5000`, `RECONCILER__MAX_CHANGES=0` и `RECONCILER__INTERVAL_SECONDS=-1` — ошибка проверки называет поле. -- [ ] 2.2 Типы по решению 8 и `dto.md`: +- [x] 2.2 Типы по решению 8 и `dto.md`: - `ReconcileFinding` (`StrEnum`) в `src/schemas/enums/attachment.py`; - `ReconcileFindingDTO`, `ReconcilePassDTO` в `src/schemas/dataclasses/attachment.py`; @@ -115,7 +132,7 @@ Commit делает основная сессия после подтвержд ## 3. Схема -- [ ] 3.1 Колонка `lost_at` по решению 6: +- [x] 3.1 Колонка `lost_at` по решению 6: - модель `Attachment` — `lost_at: Mapped[datetime | None]` (`DateTime(timezone=True)`); - ревизия поверх `739b8f04d5fb`: первой строкой `SET LOCAL lock_timeout @@ -133,7 +150,7 @@ Commit делает основная сессия после подтвержд ## 4. Клиент S3 и repo -- [ ] 4.1 `src/infra/s3/client.py` по решению 3 и дельте +- [x] 4.1 `src/infra/s3/client.py` по решению 3 и дельте `object-storage`: - `StoredObjectInfo.last_modified` (из LIST и HEAD); - страница списка `list_page(prefix, *, token, max_keys)` — @@ -144,7 +161,7 @@ Commit делает основная сессия после подтвержд с прежними записями `error`. Проверка: `make lint`; поведение — 4.4 и группа 9. -- [ ] 4.2 `src/core/repos/attachment_object.py`: +- [x] 4.2 `src/core/repos/attachment_object.py`: - `list_originals` — префикс `/attachments/`; - `parse_original_key` — `UUID` для ключа вида `/original` в нижнем регистре, иначе `None`; @@ -153,7 +170,7 @@ Commit делает основная сессия после подтвержд разрешён. Проверка: `make lint`. -- [ ] 4.3 `src/core/repos/attachment.py` по решениям 3–5 (одно выражение +- [x] 4.3 `src/core/repos/attachment.py` по решениям 3–5 (одно выражение на функцию, `repo-layer.md`): - `_ATTACHMENT_COLUMNS` + `lost_at`; - выборка страницы по `id = ANY(:ids) OR object_key = ANY(:keys)`; @@ -166,7 +183,7 @@ Commit делает основная сессия после подтвержд `pk_attachments` и `uq_attachments_object_key` или только pk при пустом `keys`) и keyset (Index Scan `pk_attachments`). Итог — в design, «Уточнения apply». -- [ ] 4.4 Проверка клиента и repo на временном проекте compose. Как в +- [x] 4.4 Проверка клиента и repo на временном проекте compose. Как в пробе design, Context: SeaweedFS на tmpfs и bootstrap группы 8.1. Ключ уборщика: - список своего префикса страницами по 1000 — все ключи и @@ -180,7 +197,7 @@ Commit делает основная сессия после подтвержд ## 5. API: потерянный оригинал -- [ ] 5.1 `AttachmentService.open_content` по решению 5 и дельте +- [x] 5.1 `AttachmentService.open_content` по решению 5 и дельте `attachments`: `lost_at` задан — `info` «Attachment content is lost» (`attachment_id`, `object_key`) и `AttachmentNotFound` до обращения к S3. Без пометки и без объекта — 500, как было. Метаданные и @@ -190,7 +207,7 @@ Commit делает основная сессия после подтвержд ## 6. Сервис сверки -- [ ] 6.1 `AttachmentReconcileService(db_scope, storage)` в +- [x] 6.1 `AttachmentReconcileService(db_scope, storage)` в `src/core/services/attachment_reconcile.py` по решениям 3, 4, 7 и 8: - шаги «S3 → БД», «БД → S3», зависшие загрузки; - перепроверка и проверка bucket до решения; @@ -206,7 +223,7 @@ Commit делает основная сессия после подтвержд ## 7. Процесс уборщика -- [ ] 7.1 `src/cleaner/main.py` (и `__main__.py`, если нужно) по +- [x] 7.1 `src/cleaner/main.py` (и `__main__.py`, если нужно) по решениям 1, 8 и 9: - команда `reconcile [--apply] [--max-changes N]` (`N` ≥ 1), коды 0 / 3 / 1 / 2; @@ -227,7 +244,7 @@ Commit делает основная сессия после подтвержд ## 8. Стенд -- [ ] 8.1 Права S3 по решению 2 и дельте `object-storage`: +- [x] 8.1 Права S3 по решению 2 и дельте `object-storage`: - `infra/s3/bootstrap.sh`: `S3_CLEANER_LIST_PREFIX` (проверка `^[a-z0-9_]+/attachments/$`, иначе «FAILED» и код 1); - политика `cleaner-objects` с `s3:ListBucket` и условием `s3:prefix`; @@ -247,12 +264,19 @@ Commit делает основная сессия после подтвержд Затем на рабочем стенде `docker compose up -d s3-bootstrap` и `make s3_check` — код 0, строки списка ключом уборщика есть. Проект пробы убран, volumes сверены. -- [ ] 8.2 `Makefile`: цель `reconcile` (`$(DC) run --rm --no-deps cleaner + + Apply: проба `rcapply` — design, «Уточнения apply», п. 14 (код 0 + трижды, 7 неверных префиксов — код 1, строки `check` ожидаемые); + проект удалён, volumes — 155, как до. Шаг на рабочем стенде (`up -d + s3-bootstrap`, `make s3_check`) перенесён в 12.1: рабочий стенд в apply + не перестраивается (поручение основной сессии), а `make s3_check` с + новым `bootstrap.sh` на прежней политике ждёт 200 на списке и упадёт. +- [x] 8.2 `Makefile`: цель `reconcile` (`$(DC) run --rm --no-deps cleaner reconcile`, `APPLY=1` → `--apply`, `MAX_CHANGES=N` → `--max-changes N`) с комментарием в стиле файла. Проверка: `make -n reconcile APPLY=1 MAX_CHANGES=5` печатает команду с обоими флагами, `make -n reconcile` — без них. -- [ ] 8.3 `bench/`: bootstrap профиля `uploads` получает префикс из +- [x] 8.3 `bench/`: bootstrap профиля `uploads` получает префикс из `bench.env` (`POSTGRES_DB=bench`). Секретов не прибавилось, `compose_env` не меняется. В `bench.compose.yml` у описанного `cleaner` — `RECONCILER__INTERVAL_SECONDS: "0"`: профиль сверки @@ -260,9 +284,16 @@ Commit делает основная сессия после подтвержд bench_uploads_quick` — код 0 (bootstrap с префиксом прошёл), метка `quick-*` в git не идёт. + Apply: префикс приходит из `docker-compose.yml` (`${POSTGRES_DB}` из + `bench.env` — `bench/attachments/`), `run.py` не менялся. `make + bench_uploads_quick` (2026-10-22, метка `quick-uploads-20261022T161946Z`, + в `.gitignore`) — «s3 healthy, bootstrap done», 6/6 прогонов за 4 мин + 31 с; предупреждение хоста о swap — это не замер. Контейнеров + `mtusi-bench*` после — 0, volumes — 155. + ## 9. Спеки и проверки отказов -- [ ] 9.1 Sync дельт в основные спеки — все семь capability, как в +- [x] 9.1 Sync дельт в основные спеки — все семь capability, как в прежних changes: сверка покрытия читает только `openspec/specs/`. Purpose `storage-consistency` — без «добавят следующие changes»: сверка описана. Проверка: @@ -270,15 +301,31 @@ Commit делает основная сессия после подтвержд - `make student_test` через LB — `test_coverage.py` зелёный, сверка называет новые сценарии `storage-consistency` и `attachments` покрытыми проверками отказов. -- [ ] 9.2 Полный `make failure_checks` на дереве после групп 2–8: все + + Apply: семь спеков синхронизированы руками (Edit), каждый блок сверен + `diff` с дельтой — совпадает. `openspec validate track2-reconciler + --strict` — valid, `openspec validate --specs --strict` — 24 passed. + `make student_test BASE_URL=http://localhost:8090` (рабочий стенд на + прежнем коде: новых тестов вне `fault` нет) — 198 passed, «coverage: + 240 scenarios in 13 specs, 223 tested (58 by make failure_checks), 17 + excluded». +- [x] 9.2 Полный `make failure_checks` на дереве после групп 2–8: все проверки зелёные (прежние 37 и новые 8), журнал PostgreSQL стенда без признаков аварии, стенд отказов удалён, `StartedAt` рабочего стенда прежний. Время прогона — в tasks. Два прогона одновременно не запускать (`student-tests.md`). + Прогон 2026-10-22 (дерево apply): **45 passed** за 458 с pytest, вся + команда — 8 мин 01 с; `postgres log: 442 lines, crash markers 0; "too + many clients" 24, "administrator command" 142`; `results: {'fault': 0, + 'postgres': 0}`. `StartedAt` всех контейнеров `mtusi-lab4` до и после — + прежние, контейнеров `mtusi-lab4-failures` — 0, volumes — 155. До + этого два прогона `-k reconcile` на новом коде падали на дефектах + тестов и hook (design, «Уточнения apply», пп. 15 и 17), не кода. + ## 10. Драйвер скилла -- [ ] 10.1 `driver.py reconcile-cycle` по решению 12 — только стенд с LB, +- [x] 10.1 `driver.py reconcile-cycle` по решению 12 — только стенд с LB, без LB код 2. Шаги: - исходный dry-run; - внесение расхождений с обеих сторон; @@ -294,7 +341,19 @@ Commit делает основная сессия после подтвержд расхождении. Проверка: прогон на рабочем стенде (`--port 8090`) — код 0; повторный прогон — снова 0, и исходный dry-run не находит остатков прошлого. -- [ ] 10.2 `driver.py reconcile-stress [--seconds S] [--clients N]` по + + Apply: рабочий стенд ещё на прежнем коде (без колонки, политики и + команды; перестройка — 12.1), поэтому проверено на временном полном + стенде `rcdrv` (`docker-compose.yml` проекта + override с хранилищами на + tmpfs, синтетические секреты, LB на `127.0.0.1:18091`; драйвер — с + `COMPOSE_PROJECT_NAME`, `COMPOSE_FILE`, `COMPOSE_ENV_FILES`): первый + прогон — 45 проверок, PASS, код 0, 1 мин 36 с; повторный — код 0, + исходный dry-run: `found={}`, `lost_known=1` (C прошлого прогона). + Там же проверена остановка уборщика во время сверки при `pause s3`: + `docker compose stop cleaner` — 4,7 с, код 0, «Finished reconcile pass» + с `interrupted_by: stop` и «Stopped cleaner». Прогон на рабочем стенде + — 12.2. Стенд `rcdrv` удалён, volumes — 155. +- [x] 10.2 `driver.py reconcile-stress [--seconds S] [--clients N]` по решению 12. Шаги: - предусловие — dry-run с grace 20 с, иначе код 2; - внесённые расхождения; @@ -302,14 +361,20 @@ Commit делает основная сессия после подтвержд - итоговая таблица и сверка SHA-256 каждого 201. Проверка: прогон на рабочем стенде — код 0, несовпадений 0. -- [ ] 10.3 `SKILL.md` скилла: обе команды, их evidence и что они меняют + + Apply: на том же временном стенде `rcdrv` — код 0, 649 загрузок 201 + (клиенты с паузой 0,2 с: без неё 4 клиента за 40 с записали 5 818 + объектов по 100 KiB, для рабочего bucket это лишнее), 8 проходов + `--apply` с кодом 0, исправлено `missing_object=2`, `orphan_object=2`, + несовпадений SHA-256 0, повтор — 0. Прогон на рабочем стенде — 12.3. +- [x] 10.3 `SKILL.md` скилла: обе команды, их evidence и что они меняют на стенде (синтетические вложения, помеченные потерянными, остаются в рабочей базе). Строки `s3-check` приходят из bootstrap, разбор не меняется — проверить вывод `make s3_check`. ## 11. Правила и документы -- [ ] 11.1 Правила: +- [x] 11.1 Правила: - `service-layer.md` — сервис сверки, порядок действий, ветка 404; - `repo-layer.md` — новые функции; - `dto.md` — `lost_at`, DTO сверки, enum; @@ -326,7 +391,7 @@ Commit делает основная сессия после подтвержд - `balancer.md` — порядок обновления (решение 6). Проверка: в каждом правиле — ссылка на design этого change. -- [ ] 11.2 AGENTS.md: +- [x] 11.2 AGENTS.md: - абзац инвариантов «Лаба 4, сверка» (что удаляется и что никогда, grace, предел, права S3, 404); - карта кода — `attachment_reconcile.py`, новые функции repo, команда @@ -334,7 +399,10 @@ Commit делает основная сессия после подтвержд - таблица команд — `make reconcile`, `driver.py reconcile-cycle`, `reconcile-stress`; - вступление — change в архиве, когда он будет заархивирован. -- [ ] 11.3 `KNOWN_ISSUES.md`, запись «Bootstrap после удаления bucket», + + Apply: абзац, карта кода и команды — сделаны; вступление — при + архивировании (change ещё активен). +- [x] 11.3 `KNOWN_ISSUES.md`, запись «Bootstrap после удаления bucket», по решению 14: причина (слоты томов на маленьком диске, `-volume.max=0`), проба на 4 и 16 ГБ, стенды проекта не затронуты, предложение. Запись остаётся открытой. diff --git a/openspec/specs/attachments/spec.md b/openspec/specs/attachments/spec.md index 3d93f13a..a5d71e05 100644 --- a/openspec/specs/attachments/spec.md +++ b/openspec/specs/attachments/spec.md @@ -355,6 +355,18 @@ UUID — 400 `invalid_request`. адрес и учётные данные S3 MUST NOT попадать ни в тело, ни в заголовки ответов API. +Если у готового вложения нет объекта в S3 или его размер не равен +`size_bytes`, а сверка хранилищ это ещё не подтвердила, это +непредвиденное расхождение. Скачивание SHALL отвечать 500 +`internal_error` без деталей, причина пишется в журнал. Если сверка уже +пометила оригинал потерянным (capability `storage-consistency`, +«Потерянный оригинал»), скачивание SHALL отвечать участнику 404 +`not_found`, как отсутствующий вариант готового объекта, — без +обращения к S3. Метаданные такого вложения SHALL отвечать 200 тем же +`Attachment`, что и до пометки. Ссылка на него в новом сообщении +принимается, как на любое готовое вложение. Когда сверка снимает +пометку, скачивание снова отдаёт байты. + #### Scenario: Побайтный оригинал - **WHEN** Боб скачивает PNG и JPEG, загруженные Алисой @@ -376,6 +388,15 @@ UUID — 400 `invalid_request`. - **THEN** в телах ответов нет полей вне схемы контракта, а в заголовках нет `Location` и заголовков `x-amz-*` +#### Scenario: Потерянный оригинал + +- **WHEN** объект готового вложения удалён мимо API, затем сверка с + `--apply` пометила его оригинал потерянным +- **THEN** скачивание до сверки — 500 `internal_error`, после неё — 404 + `not_found` +- **AND** метаданные и до, и после — 200 с тем же JSON, что у ответа на + загрузку + ### Requirement: Где хранятся вложения Метаданные вложения SHALL храниться в PostgreSQL, байты оригинала — diff --git a/openspec/specs/graceful-shutdown/spec.md b/openspec/specs/graceful-shutdown/spec.md index 38894c7f..a20696d7 100644 --- a/openspec/specs/graceful-shutdown/spec.md +++ b/openspec/specs/graceful-shutdown/spec.md @@ -199,11 +199,19 @@ SIGTERM и SIGINT, пришедшие процессу сервиса во вр `storage-consistency`) SHALL довести текущий шаг уборки загрузки до конца или до отката и больше новых шагов не начинать. Загрузка, остановленная между шагами, остаётся в состоянии, из которого её -доводит следующий проход. Затем он SHALL выйти с -кодом 0 раньше срока остановки контейнера (10 с), а не по SIGKILL. -Сигнал во время старта процесса SHALL завершать его с кодом 0 без -traceback, как у API (требование «Остановка во время старта»). -Остановка SHALL быть видна в журнале записью об остановке уборщика. +доводит следующий проход. + +Так же — во время сверки bucket и БД. Текущий вызов S3 или шаг с +PostgreSQL доводится до конца или до отката. Новые страницы списка и +новые действия не начинаются. Сверку, прерванную сигналом, доводит +следующий проход, как прерванную отказом. + +Затем сервис уборщика SHALL выйти с кодом 0 раньше срока остановки +контейнера (10 с), а не по SIGKILL. Разовый проход сверки, прерванный +сигналом, SHALL выходить с кодом 1: проход не завершён. Сигнал во время +старта процесса SHALL завершать его с кодом 0 без traceback, как у API +(требование «Остановка во время старта»). Остановка SHALL быть видна в +журнале записью об остановке уборщика. #### Scenario: docker stop уборщика @@ -211,3 +219,11 @@ traceback, как у API (требование «Остановка во вре уборщика - **THEN** команда завершается быстрее 10 с, код выхода контейнера 0, а в журнале есть запись об остановке + +#### Scenario: docker stop во время сверки + +- **WHEN** `docker compose stop cleaner` выполняется, пока идёт проход + сверки, а вызов S3 в нём ждёт ответа +- **THEN** команда завершается быстрее 10 с, код выхода контейнера 0, а + в журнале — итог сверки с причиной прерывания «остановка» и запись об + остановке уборщика diff --git a/openspec/specs/object-storage/spec.md b/openspec/specs/object-storage/spec.md index 0c75297d..d9084e6e 100644 --- a/openspec/specs/object-storage/spec.md +++ b/openspec/specs/object-storage/spec.md @@ -225,10 +225,17 @@ SHALL получать 403 на: У уборщика (capability `storage-consistency`) SHALL быть свои учётные данные S3, отдельные от учётных данных API и административных. -Пользователю уборщика SHALL быть разрешены только чтение и удаление -объектов своего bucket. Ему MUST NOT быть разрешены: +Пользователю уборщика SHALL быть разрешены только: +- чтение и удаление объектов своего bucket; +- список объектов своего bucket с префиксом вложений своей базы, + `<имя базы>/attachments/`, — для сверки bucket и БД. + +Префикс задаёт bootstrap по имени базы стенда. + +Пользователю уборщика MUST NOT быть разрешены: - запись объектов; -- список объектов; +- список объектов без этого префикса или с другим префиксом, в том числе + с префиксом другой базы; - операции с bucket: создание, удаление, политика, ACL; - публичный ACL объекта; - управление учётными записями; @@ -240,15 +247,20 @@ SHALL получать 403 на: #### Scenario: Работа уборщика с объектами - **WHEN** ключом API записан объект, а ключом уборщика он прочитан, - удалён и удалён ещё раз -- **THEN** чтение отдаёт те же байты, оба удаления успешны, а объекта - после них нет + удалён и удалён ещё раз, и запрошен список объектов с префиксом + вложений базы +- **THEN** чтение отдаёт те же байты, оба удаления успешны, объекта + после них нет, а список отвечает 200 #### Scenario: Запрещённые операции уборщика -- **WHEN** ключом уборщика запрашиваются запись объекта, список - объектов, создание и удаление bucket, политика и ACL bucket, публичный - ACL объекта и объект другого bucket +- **WHEN** ключом уборщика запрашиваются: + - запись объекта; + - список объектов всего bucket и с префиксом, не принадлежащим + вложениям его базы; + - создание и удаление bucket, политика и ACL bucket; + - публичный ACL объекта; + - объект другого bucket и его список - **THEN** каждый запрос получает 403, а bucket и его доступ не меняются @@ -260,8 +272,9 @@ SHALL получать 403 на: 1. Каждый запуск bootstrap: - ключ API записывает и читает проверочный объект и получает отказ на список и на создание bucket; - - ключ уборщика читает и удаляет этот объект и получает отказ на - запись и на список; + - ключ уборщика читает и удаляет этот объект. Он получает отказ на + запись и на список всего bucket, а список с префиксом вложений своей + базы у него проходит; - аноним получает отказ на чтение существующего объекта и на список. При нарушении bootstrap завершается с ненулевым кодом, и реплики API @@ -271,7 +284,9 @@ SHALL получать 403 на: - анонимные запросы с хоста и из сети стенда; - запросы ключей API и уборщика к чужому bucket; - административные запросы ключей API и уборщика; - - запись и список ключом уборщика. + - запись ключом уборщика; + - его список всего bucket и с чужим префиксом — отказ, с префиксом + вложений своей базы — 200. Команда SHALL печатать по каждой проверке ожидаемый и полученный код ответа без секретов. При любом нарушении код выхода SHALL быть @@ -281,8 +296,8 @@ SHALL получать 403 на: - **WHEN** на запущенном стенде выполняется `make s3_check` - **THEN** каждая проверка напечатана с полученным кодом ответа, в том - числе проверки ключа уборщика, код выхода 0, а проверочных объектов и - bucket после команды нет + числе проверки списка ключом уборщика по своему и чужому префиксу, код + выхода 0, а проверочных объектов и bucket после команды нет #### Scenario: Bucket стал публичным @@ -316,11 +331,17 @@ SHALL сохраняться и после принудительного зав Процессы приложения SHALL обращаться к S3 с учётными данными своей роли из секции `[s3]`: реплики API — ключами пользователя API, уборщик — -ключами пользователя уборщика. Клиент SHALL уметь записать объект, -прочитать его потоком, получить метаданные и удалить. Удаление -отсутствующего объекта — не ошибка. Каждый вызов SHALL быть ограничен -сроком из настроек. После отказа или истечения срока вызов MUST NOT -повторяться автоматически. +ключами пользователя уборщика. Клиент SHALL уметь: +- записать объект; +- прочитать его потоком; +- получить метаданные; +- удалить объект; +- перечислить объекты с заданным префиксом страницами, с размером и + временем изменения каждого объекта. + +Удаление отсутствующего объекта — не ошибка. Каждый вызов, в том числе +каждая страница списка, SHALL быть ограничен сроком из настроек. После +отказа или истечения срока вызов MUST NOT повторяться автоматически. Ошибкой недоступности, которую API отдаёт как 503 `unavailable` в формате контракта, SHALL заканчиваться вызов, если S3: @@ -330,10 +351,11 @@ SHALL сохраняться и после принудительного зав - отказал ключу в доступе или не нашёл bucket. Такой вызов MUST NOT давать 500 или зависать. Отсутствующий объект SHALL -отличаться от недоступности: отсутствующий bucket MUST NOT выдаваться за -отсутствующий объект у записи, чтения и удаления. После возврата S3 вызовы SHALL проходить -без перезапуска приложения. Соединения с S3 SHALL открываться при -первом вызове, а при остановке сервиса клиент SHALL закрываться. +отличаться от недоступности. Отсутствующий bucket MUST NOT выдаваться +за отсутствующий объект у записи, чтения, удаления и списка: список без +bucket — ошибка, а не пустая страница. После возврата S3 вызовы SHALL +проходить без перезапуска приложения. Соединения с S3 SHALL открываться +при первом вызове, а при остановке сервиса клиент SHALL закрываться. Ключ объекта SHALL начинаться с имени базы PostgreSQL процесса и `/`. Так объекты прогона на временной базе (`make test_isolated`) отделены @@ -365,9 +387,10 @@ SHALL сохраняться и после принудительного зав #### Scenario: Bucket нет - **WHEN** bucket приложения удалён мимо bootstrap, и приложение - записывает, читает или удаляет объект + записывает, читает или удаляет объект либо запрашивает список объектов - **THEN** каждый вызов завершается ошибкой недоступности, а не - сообщением «объекта нет», и в журнале есть запись уровня `error` + сообщением «объекта нет» и не пустым списком, и в журнале есть запись + уровня `error` #### Scenario: Учётные данные отклонены diff --git a/openspec/specs/service-configuration/spec.md b/openspec/specs/service-configuration/spec.md index 185d9e6e..06f27092 100644 --- a/openspec/specs/service-configuration/spec.md +++ b/openspec/specs/service-configuration/spec.md @@ -463,3 +463,40 @@ grace SHALL быть описаны в `REPORT.md`. `UPLOADS__MAX_WAITING=-1` или `UPLOADS__BODY_TIMEOUT_SECONDS=abc` - **THEN** сервис не стартует, в журнале — ошибка проверки настроек с именем поля + +### Requirement: Параметры сверки + +Параметры сверки bucket и БД (capability `storage-consistency`) SHALL +задаваться в секции `[reconciler]`: +- `interval_seconds` — пауза между плановыми сверками процесса + уборщика, по умолчанию 3600; 0 — без плановой сверки; +- `page_size` — сколько ключей сверка берёт одной страницей списка S3 + и сколько строк одним запросом к PostgreSQL, по умолчанию 1000, не + больше 1000; +- `max_changes` — предел изменений за проход, по умолчанию 100. + +`interval_seconds` SHALL быть неотрицательным числом, `page_size` и +`max_changes` — целыми не меньше 1. Иначе уборщик MUST NOT стартовать +(требование «Некорректное значение останавливает запуск»). + +Отдельного grace у сверки нет: она берёт `[cleaner] +pending_grace_seconds` и его проверку границы живой загрузки +(требование «Параметры уборщика»). Разовая подмена SHALL работать через +окружение `RECONCILER__*` без правки файлов. Разовый проход SHALL +принимать предел изменений и аргументом команды. Значения по умолчанию +и их обоснование SHALL быть описаны в `REPORT.md`. Реплики API секцию +`[reconciler]` не используют. + +#### Scenario: Параметры сверки по умолчанию + +- **WHEN** уборщик запущен без секции `[reconciler]` и без переменных + `RECONCILER__*` +- **THEN** запись о его старте называет интервал сверки 3600 с, + страницу 1000 и предел изменений 100 + +#### Scenario: Неверный параметр сверки + +- **WHEN** уборщик запускается с `RECONCILER__PAGE_SIZE=5000`, + `RECONCILER__MAX_CHANGES=0` или `RECONCILER__INTERVAL_SECONDS=-1` +- **THEN** уборщик не стартует, в журнале — ошибка проверки настроек с + именем поля diff --git a/openspec/specs/service-logging/spec.md b/openspec/specs/service-logging/spec.md index a2e74e0c..89e81836 100644 --- a/openspec/specs/service-logging/spec.md +++ b/openspec/specs/service-logging/spec.md @@ -173,3 +173,46 @@ traceback и `request_id` запроса. - **WHEN** S3 остановлен, а уборщику есть что убирать - **THEN** в журнале запись уровня `warning` о прерванном проходе с причиной, без секретов, а метаданные загрузки на месте + +### Requirement: Журнал сверки + +Сверка bucket и БД (capability `storage-consistency`) SHALL писать в +журнал процесса уборщика JSON-записи в формате этой capability, в каждой +— `instance_id` процесса. Записи: +- запись о старте уборщика дополнительно называет интервал сверки, + размер страницы и предел изменений; +- каждое найденное расхождение — класс, ключ объекта, `id` вложения, + если он известен, возраст, размеры объекта и метаданных, если они + разные. Уровень `warning`, если расхождение осталось, и `info`, если + проход с `--apply` его исправил, с названием действия; +- итог прохода — режим, сколько объектов и строк просмотрено, сколько + найдено и исправлено по классам, сколько свежих и уже помеченных, + длительность и причина прерывания. Уровень `info`, если расхождений не + осталось, иначе `warning`; +- превышение предела изменений — `error` с числом изменений и пределом; +- отказ S3 или PostgreSQL — `warning`, непредвиденная ошибка — `error` с + traceback. + +Если расхождений за проход больше тысячи, отдельными записями SHALL +писаться только первые, а итог SHALL называть, сколько осталось без +записи. Скачивание потерянного оригинала реплика API SHALL писать +записью уровня `info` с `id` вложения и ключом объекта, а не `error`. +Записи сверки MUST NOT содержать ключи доступа и секреты S3, ключ +подписи, подписи запросов, `filename` вложений и байты объектов. + +#### Scenario: Журнал разового прохода + +- **WHEN** сверка находит объект без метаданных и метаданные без + объекта, а затем исправляет их с `--apply` +- **THEN** результат такой: + - в журнале dry-run — две записи `warning` с классом, ключом и + возрастом и итог `warning`; + - в журнале прохода с `--apply` — две записи `info` с действием и + итог `info`; + - секретов S3 и `filename` в журнале нет + +#### Scenario: Предел изменений в журнале + +- **WHEN** сверка с `--apply` отказывается исправлять из-за предела +- **THEN** в журнале запись `error` с числом изменений и пределом, а + итог прохода — `warning` diff --git a/openspec/specs/storage-consistency/spec.md b/openspec/specs/storage-consistency/spec.md index 40039be1..8f81cd08 100644 --- a/openspec/specs/storage-consistency/spec.md +++ b/openspec/specs/storage-consistency/spec.md @@ -6,9 +6,13 @@ лабы 4. Здесь описано: - уборщик незавершённых загрузок: что и когда он убирает; - безопасный grace period; -- поведение уборщика при отказах хранилищ. +- поведение уборщика при отказах хранилищ; +- сверка bucket и БД (трек 2, change `track2-reconciler`): классы + расхождений, разовый и плановый проход, правила безопасности, предел + изменений, потерянный оригинал и отказы хранилищ во время сверки. -Сверку bucket и БД (трек 2) добавят следующие changes. +Стоимость обхода и стратегии сверки описывает change +`track2-reconcile-cost`. ## Requirements @@ -36,10 +40,12 @@ period), он SHALL убирать по шагам: Ограничение называется в `REPORT.md`. Объект может остаться без метаданных, если процесс API заморожен дольше grace посреди записи -объекта и после разморозки дописал объект уже убранной загрузки, а -удалить его не смог: запись объекта завершилась для API ошибкой по -сроку, или не удалось удаление при компенсации. Такой объект находит -только сверка bucket и БД (трек 2). +объекта. После разморозки он дописывает объект уже убранной загрузки, а +удалить его не может: запись объекта завершилась для API ошибкой по +сроку, или не удалось удаление при компенсации. Такой объект находит и +удаляет сверка bucket и БД (требование «Сверка bucket и БД»), когда он +старше grace. На стенде это происходит не позже следующей плановой +сверки (требование «Плановая сверка»). #### Scenario: Зависшая загрузка убрана @@ -157,3 +163,242 @@ S3 выполнил удаление уже после срока вызова. работает и незавершённая загрузка ещё моложе grace - **THEN** после возврата PostgreSQL и истечения grace уборщик без перезапуска убирает эту загрузку + +### Requirement: Сверка bucket и БД + +Сверка SHALL сравнивать объекты вложений в bucket — ключи с префиксом +`<имя базы>/attachments/` — с метаданными вложений той же базы в +PostgreSQL и находить расхождения шести классов: +- **объект без метаданных** — объект с ключом вида + `<база>/attachments//original`, на который не ссылается ни одна + строка и для `id` которого строки нет; +- **метаданные без объекта** — вложение `ready`, объекта по ключу из его + метаданных в bucket нет; +- **другой размер** — вложение `ready`, размер объекта не равен + `size_bytes`; +- **зависшая загрузка** — вложение в статусе «загружается» старше grace, + то же, что убирает уборщик (требование «Уборщик незавершённых + загрузок»); +- **оригинал вернулся** — оригинал вложения помечен потерянным + (требование «Потерянный оригинал»), а объект снова есть с тем же + размером; +- **чужой объект** — объект под префиксом вложений, ключа такого вида + API не пишет, либо ключ вида `/original`, у строки которого + другой ключ. + +Сверку SHALL выполнять процесс уборщика, а не реплики API: разовым +проходом (`make reconcile` или команда сверки в контейнере уборщика) и +плановым (требование «Плановая сверка»). Разовый проход по умолчанию +SHALL ничего не менять (dry-run). С `--apply` он SHALL исправлять: +- объект без метаданных — удалить объект; +- метаданные без объекта и другой размер — пометить оригинал вложения + потерянным; +- зависшую загрузку — убрать тем же порядком, что уборщик; +- вернувшийся оригинал — снять пометку. + +Чужой объект сверка MUST NOT удалять: он попадает только в отчёт. + +Отчёт SHALL называть по каждому расхождению класс, ключ объекта, `id` +вложения, если он известен, и возраст. Итог прохода SHALL называть: +- сколько объектов и строк просмотрено; +- сколько расхождений найдено и исправлено по классам; +- сколько объектов и строк пропущено как свежие; +- сколько вложений уже помечены потерянными. + +После успешного исправления повторный проход SHALL не находить ни одного +исправимого расхождения. + +Код выхода разового прохода: +- 0 — расхождений нет: dry-run их не нашёл, `--apply` исправил все, и + чужих объектов нет; +- 3 — расхождения остались: их нашёл dry-run, `--apply` отказался по + пределу изменений или в bucket есть чужие объекты; +- 1 — проход прерван отказом хранилища, ошибкой или сигналом; +- 2 — неверная конфигурация. + +#### Scenario: Расхождения с обеих сторон найдены + +- **WHEN** всё это старше grace, и выполняется сверка без `--apply`: + - в bucket мимо API записан объект вложения; + - у готового вложения удалён объект; + - у неиспользуемого готового вложения удалены метаданные; + - у другого в метаданных изменён размер; + - загрузка оборвалась между записью объекта и фиксацией `ready` +- **THEN** отчёт называет каждое расхождение его классом, ключом и + возрастом, код выхода 3, а в PostgreSQL и в bucket ничего не + изменилось + +#### Scenario: Исправление расхождений + +- **WHEN** после этого выполняется сверка с `--apply` +- **THEN** результат такой: + - объекты без метаданных удалены; + - зависшей загрузки нет — ни метаданных, ни объекта; + - оба вложения с потерянным оригиналом помечены, их метаданные на + месте; + - код выхода 0 + +#### Scenario: Повторная сверка + +- **WHEN** сразу после исправления сверка выполняется ещё раз +- **THEN** ни одного из этих расхождений в отчёте нет, а код выхода + соответствует отчёту: 0, если расхождений в нём нет + +### Requirement: Безопасность сверки + +Сверка MUST NOT удалять: +- метаданные вложений, кроме уборки зависшей загрузки; +- объект, на который ссылаются метаданные, в любом статусе; +- объект с ключом вида `/original`, если строка этого `id` есть. + +Вложение, на которое ссылается сообщение, MUST NOT терять из-за сверки +ни метаданные, ни объект, ни ссылку в истории. Если его оригинал +потерян, сверка его только помечает. + +Свежее сверка MUST NOT трогать и не считает расхождением: +- объект, записанный или изменённый в S3 меньше grace назад; +- вложение, метаданные которого записаны или переведены в `ready` меньше + grace назад. + +Grace — тот же, что у уборщика (capability `service-configuration`, +«Параметры уборщика»). + +Каждое расхождение SHALL перепроверяться в PostgreSQL и в S3 +непосредственно перед действием: +- объект без метаданных — строки с этим ключом или `id` по-прежнему + нет, объект на месте и старше grace; +- метаданные без объекта и другой размер — вложение по-прежнему `ready` + с тем же ключом, а объекта по ключу нет или его размер другой; +- вернувшийся оригинал — пометка на месте, объект того же размера. + +Не подтвердилось — действие не выполняется. Отсутствие объекта MUST NOT +считаться подтверждённым, пока не проверено, что bucket на месте. Иначе +удалённый bucket выглядел бы как потеря всех оригиналов. + +Предел изменений: если за проход нужно удалить объекты, пометить +оригиналы или снять пометки больше чем у `[reconciler] max_changes` +вложений, сверка с `--apply` MUST NOT выполнять ни одно из этих +изменений. Она пишет ошибку с числом изменений и пределом и завершается +кодом 3. Разовый проход SHALL принимать больший предел аргументом. +Уборка зависших загрузок пределом не ограничена. + +Сверка, уборщик и две сверки одновременно SHALL не мешать друг другу: +- каждое действие безопасно повторять; +- зависшую загрузку сверка убирает тем же порядком и под той же + блокировкой, что уборщик. + +Объекты других баз и ключи вне префикса вложений своей базы сверка MUST +NOT читать и менять. + +#### Scenario: Свежие не тронуты + +- **WHEN** в bucket мимо API записан объект вложения, у готового + вложения удалён объект, обоим меньше grace, и выполняется сверка с + `--apply` +- **THEN** объект на месте, вложение не помечено, а отчёт считает их + свежими, а не расхождениями + +#### Scenario: Используемое вложение не удаляется + +- **WHEN** у вложения, на которое ссылается сообщение, удалён объект, + ему больше grace, и выполняется сверка с `--apply` +- **THEN** результат такой: + - вложение помечено потерянным; + - его метаданные — 200; + - история чата по-прежнему отдаёт его `id` в сообщении; + - ни одна строка вложений не удалена + +#### Scenario: Чужой объект не удаляется + +- **WHEN** под префиксом вложений базы лежит объект с ключом, которого + API не пишет, ему больше grace, и выполняется сверка с `--apply` +- **THEN** объект на месте, отчёт называет его чужим, код выхода 3 + +#### Scenario: Предел изменений + +- **WHEN** расхождений, которые сверка исправила бы, больше предела, и + выполняется сверка с `--apply` +- **THEN** ни один объект не удалён, ни одно вложение не помечено, + ошибка называет число изменений и предел, код выхода 3 +- **AND** с пределом не меньше их числа повтор исправляет все + +#### Scenario: Сверка под нагрузкой + +- **WHEN** выполняются все условия: + - участники дольше grace загружают вложения и отправляют сообщения с + ними; + - в это время сверка с `--apply` повторяется раз в несколько секунд; + - в стенде есть внесённые расхождения +- **THEN** внесённые расхождения исправлены, каждое вложение, загрузка + которого ответила 201, скачивается с тем же SHA-256, а каждое + сообщение отдаёт свои `attachment_ids` + +### Requirement: Потерянный оригинал + +Если сверка подтвердила, что объекта готового вложения нет или его +размер другой, она SHALL пометить оригинал вложения потерянным и +записать время пометки в метаданные. Сверка не удаляет ни метаданные, ни +ссылки сообщений, ни объект другого размера. Байты сверка не +восстанавливает: их нет нигде. Что видит API для помеченного вложения — +capability `attachments`, «Скачивание оригинала». + +Пометка MUST NOT менять поля вложения в ответах API, в том числе +`status` и `updated_at`. Пометку SHALL снимать сверка с `--apply`, когда +объект по ключу вложения снова есть и его размер равен `size_bytes`. + +#### Scenario: Оригинал вернулся + +- **WHEN** оригинал вложения помечен потерянным, затем те же байты + записаны в bucket под его ключом, и выполняется сверка с `--apply` +- **THEN** пометка снята, байты вложения скачиваются — 200 с тем же + SHA-256, а следующий проход не находит расхождений по этому вложению + +### Requirement: Сверка при отказах хранилищ + +Если S3 недоступен, не ответил за срок вызова, отказал в доступе или +bucket нет, либо недоступна PostgreSQL, проход сверки SHALL прерываться +на первом же отказе. Новых изменений после отказа он не делает. Код +выхода разового прохода — 1. Плановая сверка повторяется через свой +интервал без перезапуска процесса. + +Изменения, сделанные до отказа, остаются верными. Каждое действие +сверки — отдельный безопасный шаг, поэтому прерванный проход SHALL +доводить следующий. + +#### Scenario: S3 недоступен во время сверки + +- **WHEN** в стенде есть расхождения старше grace, S3 остановлен, и + выполняется сверка с `--apply` +- **THEN** код выхода 1, ни один объект не удалён, ни одно вложение не + помечено +- **AND** после возврата S3 повтор исправляет все расхождения + +#### Scenario: Прерванная сверка доводится повтором + +- **WHEN** сверка с `--apply` прерывается отказом PostgreSQL на пометке + одного из вложений +- **THEN** код выхода 1 +- **AND** когда PostgreSQL снова принимает запись, повтор исправляет + оставшиеся расхождения, и следующий проход их не находит + +### Requirement: Плановая сверка + +Процесс уборщика SHALL сам выполнять сверку с исправлением, без +разового прохода: +- при старте; +- затем не реже чем раз в `[reconciler] interval_seconds`; +- с пределом изменений из настроек. + +Значение 0 выключает плановую сверку. Плановая и разовая сверки — один +и тот же проход с теми же правилами безопасности. + +Ограничение называется в `REPORT.md`. Пока идёт проход сверки, уборка +зависших загрузок ждёт его конца. Объект без метаданных на стенде живёт +не дольше суммы grace, интервала сверки и прохода. + +#### Scenario: Плановая сверка без команды + +- **WHEN** у готового вложения старше grace удалён объект, а уборщик + работает с коротким интервалом сверки +- **THEN** не позже интервала с запасом вложение помечено потерянным + без разового прохода, а в журнале уборщика есть итог сверки diff --git a/openspec/specs/student-tests/spec.md b/openspec/specs/student-tests/spec.md index bf18bed0..5bfe5ad4 100644 --- a/openspec/specs/student-tests/spec.md +++ b/openspec/specs/student-tests/spec.md @@ -373,7 +373,7 @@ PostgreSQL стенда, с Valkey и S3 стенда. Команда SHALL по видна», «Сбой записи метаданных», «Фиксация ready не удалась», «Обрыв передачи тела», «Отказ раньше очереди», «Все места заняты», «Очередь ожидания полна», «Ожидание места», «Место освобождается», «Медленный - клиент», «Медленная передача в срок»; + клиент», «Медленная передача в срок», «Потерянный оригинал»; - `storage-consistency`: все сценарии. Команда SHALL: @@ -388,23 +388,40 @@ PostgreSQL стенда, с Valkey и S3 стенда. Команда SHALL по очереди, коротким сроком ожидания места и коротким сроком тела. Их значения SHALL передаваться проверкам; - запустить уборщика с коротким grace и интервалом, сравнимыми со - временем теста, и передать их значения проверкам. Grace при этом - SHALL проходить проверку границы живой загрузки (`service- - configuration`, «Параметры уборщика»); + временем теста, без плановой сверки, и передать их значения + проверкам. Grace при этом SHALL проходить проверку границы живой + загрузки (`service-configuration`, «Параметры уборщика»). Сверку + проверки запускают сами, и плановая сверка не меняет стенд у них за + спиной; - выполнить проверки отказов; - удалить стенд вместе с его данными при любом исходе. Hook стенда отказов SHALL уметь: -- сообщить вложения стенда в PostgreSQL с их статусами и `id` - последнего вложения в статусе «загружается»; +- сообщить вложения стенда в PostgreSQL с их статусами, `id` последнего + вложения в статусе «загружается» и `id` вложений с потерянным + оригиналом; - сообщить, у каких вложений есть объект в bucket стенда, — по самим объектам, а не по каталогам хранилища; -- внедрить отказ PostgreSQL при записи метаданных и при фиксации - `ready` загрузки с заданным `filename` и задержать такую фиксацию; -- убить и снова запустить обычный API стенда. +- внедрить отказ PostgreSQL: + - при записи метаданных загрузки с заданным `filename`; + - при фиксации её `ready`, и задержать такую фиксацию; + - при пометке потерянного оригинала такого вложения; +- убить и снова запустить обычный API стенда; +- внести расхождения хранилищ: + - записать объект в bucket стенда мимо API и удалить объект мимо API — + только под префиксом вложений базы стенда; + - удалить метаданные вложения, изменить в них размер и сдвинуть их + время в прошлое; +- выполнить разовую сверку — без изменений или с `--apply`, с заданным + пределом изменений — и вернуть её записи и код выхода; +- остановить и запустить уборщика стенда, а также запустить отдельного + уборщика с коротким интервалом плановой сверки на заданное время и + вернуть его журнал. Других сведений о хранилищах проверки вложений не получают. Объекты без -метаданных проверка находит сравнением этих двух списков. +метаданных проверка находит сравнением двух списков: вложений и +объектов. Ключи доступа S3 hook не получает и не печатает: объект мимо +API записывает процесс в контейнере стенда своими ключами. Порты PostgreSQL, Valkey и S3 этого стенда MUST NOT публиковаться на хосте, API — только на `127.0.0.1`. Рабочий стенд, его база, кэш, diff --git a/src/cleaner/main.py b/src/cleaner/main.py index d3b34a3b..a887d03d 100644 --- a/src/cleaner/main.py +++ b/src/cleaner/main.py @@ -1,15 +1,24 @@ -"""Уборщик незавершённых загрузок: `python -m src.cleaner [--once]`. +"""Уборщик незавершённых загрузок и сверка bucket и БД. + +`python -m src.cleaner [--once]` — сервис уборки; `python -m src.cleaner +reconcile [--apply] [--max-changes N]` — разовая сверка, по умолчанию +dry-run (design change `track2-reconciler`, решение 1). Отдельный процесс стенда, а не задача реплик API (design change `upload-consistency`, решения 2, 4, 5). Свои engine (пул из `DATABASE__POOL_SIZE`, на стенде 1) и клиент S3 с ключами пользователя уборщика; глобалы процесса API (`src/infra/db/session.py`, -`src/infra/s3/instance.py`) не импортируются. +`src/infra/s3/instance.py`) не импортируются. Сервис после прохода уборки +выполняет плановую сверку с исправлением: при старте и раз в +`[reconciler] interval_seconds` (0 — без неё; решение 9). -Коды выхода: 0 — остановлен сигналом или `--once` дошёл до конца -прохода; 1 — `--once` прерван отказом хранилища или ошибкой; 2 — -неверная конфигурация (grace не больше границы живой загрузки, ошибка -настроек — `src/cleaner/__main__.py`). +Коды выхода сервиса и `--once`: 0 — остановлен сигналом или `--once` +дошёл до конца прохода; 1 — `--once` прерван отказом хранилища или +ошибкой; 2 — неверная конфигурация (grace не больше границы живой +загрузки, ошибка настроек — `src/cleaner/__main__.py`, неверный +аргумент — argparse). Разовая сверка: 0 — расхождений нет, 3 — остались +(в том числе чужие объекты и отказ по пределу), 1 — прервана отказом, +ошибкой или сигналом, 2 — конфигурация (решение 8). """ import argparse @@ -22,7 +31,10 @@ from sqlalchemy.ext.asyncio import AsyncSession from src.config import settings from src.config.settings import Settings -from src.core.services import AttachmentCleanupService +from src.core.services import ( + AttachmentCleanupService, + AttachmentReconcileService, +) from src.core.services.attachment_cleanup import INTERRUPTED_BY_STOP from src.infra import early_stop from src.infra.db import create_engine, create_session_factory @@ -37,6 +49,12 @@ logger: AbstractLogger = get_logger().bind(module="cleaner") EXIT_OK = 0 EXIT_PASS_FAILED = 1 EXIT_CONFIG = 2 +# разовая сверка: расхождения остались +EXIT_DISCREPANCIES = 3 + +MODE_SERVICE = "service" +MODE_ONCE = "once" +MODE_RECONCILE = "reconcile" def live_upload_bound_seconds(config: Settings) -> float: @@ -52,27 +70,72 @@ def live_upload_bound_seconds(config: Settings) -> float: ) +def _positive_int(value: str) -> int: + number = int(value) + if number < 1: + raise argparse.ArgumentTypeError("must be at least 1") + return number + + def _parse_args(argv: list[str] | None) -> argparse.Namespace: parser = argparse.ArgumentParser( prog="python -m src.cleaner", - description="Remove stale pending attachments and their objects.", + description="Remove stale pending attachments and their objects; " + "reconcile the bucket with the database.", ) parser.add_argument( "--once", action="store_true", - help="one pass and exit: 0 done, 1 interrupted, 2 bad config", + help="one cleanup pass and exit: 0 done, 1 interrupted, 2 bad config", + ) + commands = parser.add_subparsers(dest="command") + reconcile = commands.add_parser( + MODE_RECONCILE, + help="one reconcile pass, dry-run by default: 0 no discrepancies, " + "3 discrepancies left, 1 interrupted, 2 bad config", + ) + reconcile.add_argument( + "--apply", + action="store_true", + help="fix what is safe to fix", + ) + reconcile.add_argument( + "--max-changes", + type=_positive_int, + default=None, + help="change limit of the pass (default: [reconciler] max_changes)", ) return parser.parse_args(argv) def main(argv: list[str] | None = None) -> int: args = _parse_args(argv) - return asyncio.run(run(once=args.once)) + if args.command == MODE_RECONCILE: + return asyncio.run( + run( + mode=MODE_RECONCILE, + apply=args.apply, + max_changes=( + settings.reconciler.max_changes + if args.max_changes is None + else args.max_changes + ), + ), + ) + return asyncio.run(run(mode=MODE_ONCE if args.once else MODE_SERVICE)) -async def run(*, once: bool) -> int: - """Проверка grace, затем проходы до сигнала (или один с `--once`).""" +async def run( + *, + mode: str, + apply: bool = True, + max_changes: int | None = None, +) -> int: + """Проверка grace, затем проходы уборки до сигнала (или один с + `--once`) с плановой сверкой — или одна разовая сверка.""" cleaner = settings.cleaner + reconciler = settings.reconciler + limit = reconciler.max_changes if max_changes is None else max_changes bound = live_upload_bound_seconds(settings) if cleaner.pending_grace_seconds <= bound: # до engine и клиента S3: ни одного обращения к хранилищам @@ -91,8 +154,8 @@ async def run(*, once: bool) -> int: loop = asyncio.get_running_loop() for signum in (signal.SIGTERM, signal.SIGINT): loop.add_signal_handler(signum, stop.set) - # дальше сигналы обрабатывает цикл: текущий шаг уборки доводится до - # commit или отката, новые не начинаются + # дальше сигналы обрабатывает цикл: текущий шаг уборки или сверки + # доводится до commit или отката, новые не начинаются early_stop.disarm() engine = create_engine(settings.database) @@ -108,7 +171,8 @@ async def run(*, once: bool) -> int: timeout_seconds=settings.database.request_timeout_seconds, ) - service = AttachmentCleanupService(db_scope=db_scope, storage=storage) + cleanup = AttachmentCleanupService(db_scope=db_scope, storage=storage) + reconcile = AttachmentReconcileService(db_scope=db_scope, storage=storage) exit_code = EXIT_OK try: if not ( @@ -120,11 +184,16 @@ async def run(*, once: bool) -> int: await storage.start() logger.info( "Started cleaner", + mode=mode, interval_seconds=cleaner.interval_seconds, pending_grace_seconds=cleaner.pending_grace_seconds, batch_size=cleaner.batch_size, live_upload_bound_seconds=bound, - once=once, + once=mode == MODE_ONCE, + reconcile_interval_seconds=reconciler.interval_seconds, + reconcile_page_size=reconciler.page_size, + reconcile_max_changes=limit, + reconcile_apply=apply if mode == MODE_RECONCILE else None, database_host=settings.database.host, database_port=settings.database.port, database_name=settings.database.name, @@ -133,26 +202,21 @@ async def run(*, once: bool) -> int: s3_port=settings.s3.port, s3_bucket=settings.s3.bucket, ) - while not stop.is_set(): - result = await _clean_once( - service, - grace_seconds=cleaner.pending_grace_seconds, - batch_size=cleaner.batch_size, + if mode == MODE_RECONCILE: + result = await _reconcile_once( + reconcile, + apply=apply, + max_changes=limit, + stop=stop, + ) + exit_code = _reconcile_exit_code(result) + else: + exit_code = await _serve( + cleanup, + reconcile, + once=mode == MODE_ONCE, stop=stop, ) - if once: - if result is None or result.interrupted_by not in ( - None, - INTERRUPTED_BY_STOP, - ): - exit_code = EXIT_PASS_FAILED - break - # пауза до следующего прохода или до сигнала - with suppress(TimeoutError): - await asyncio.wait_for( - stop.wait(), - timeout=cleaner.interval_seconds, - ) finally: await engine.dispose() await storage.aclose() @@ -160,6 +224,51 @@ async def run(*, once: bool) -> int: return exit_code +async def _serve( + cleanup: AttachmentCleanupService, + reconcile: AttachmentReconcileService, + *, + once: bool, + stop: asyncio.Event, +) -> int: + """Проходы уборки до сигнала; после прохода — плановая сверка, если + подошёл её срок: первая — при старте, следующая — через + `[reconciler] interval_seconds` после конца предыдущей.""" + cleaner = settings.cleaner + interval = settings.reconciler.interval_seconds + loop = asyncio.get_running_loop() + next_reconcile = loop.time() if interval > 0 and not once else None + while not stop.is_set(): + result = await _clean_once( + cleanup, + grace_seconds=cleaner.pending_grace_seconds, + batch_size=cleaner.batch_size, + stop=stop, + ) + if once: + if result is None or result.interrupted_by not in ( + None, + INTERRUPTED_BY_STOP, + ): + return EXIT_PASS_FAILED + return EXIT_OK + pause = cleaner.interval_seconds + if next_reconcile is not None and not stop.is_set(): + if loop.time() >= next_reconcile: + await _reconcile_once( + reconcile, + apply=True, + max_changes=settings.reconciler.max_changes, + stop=stop, + ) + next_reconcile = loop.time() + interval + pause = min(pause, max(0.0, next_reconcile - loop.time())) + # пауза до следующего прохода или до сигнала + with suppress(TimeoutError): + await asyncio.wait_for(stop.wait(), timeout=pause) + return EXIT_OK + + async def _clean_once( service: AttachmentCleanupService, *, @@ -180,3 +289,39 @@ async def _clean_once( except Exception as e: logger.error("Cleanup pass failed", exc_info=e) return None + + +async def _reconcile_once( + service: AttachmentReconcileService, + *, + apply: bool, + max_changes: int, + stop: asyncio.Event, +) -> dataclasses.ReconcilePassDTO | None: + """Проход сверки; `None` — непредвиденная ошибка: `error` с + traceback, сервис живёт до следующей плановой сверки.""" + older_than = utcnow() - timedelta( + seconds=settings.cleaner.pending_grace_seconds, + ) + try: + return await service.reconcile( + older_than=older_than, + apply=apply, + max_changes=max_changes, + page_size=settings.reconciler.page_size, + batch_size=settings.cleaner.batch_size, + stop_requested=stop.is_set, + ) + except Exception as e: + logger.error("Reconcile pass failed", exc_info=e) + return None + + +def _reconcile_exit_code(result: dataclasses.ReconcilePassDTO | None) -> int: + """Код разового прохода сверки: прерван (в том числе сигналом) — 1, + остались расхождения или отказ по пределу — 3, иначе 0.""" + if result is None or result.interrupted_by is not None: + return EXIT_PASS_FAILED + if result.remaining or result.refused: + return EXIT_DISCREPANCIES + return EXIT_OK diff --git a/src/config/settings.py b/src/config/settings.py index d48c090f..672c538a 100644 --- a/src/config/settings.py +++ b/src/config/settings.py @@ -263,6 +263,25 @@ class Cleaner(BaseModel): batch_size: int = Field(default=100, ge=1) +class Reconciler(BaseModel): + """Сверка bucket и БД процессом уборщика (design change + `track2-reconciler`, решение 10). + + Значения — из `config.toml`, разовая подмена — окружением + `RECONCILER__*`. Grace у сверки свой не заводится: она берёт `[cleaner] + pending_grace_seconds` и его проверку при старте. Реплики API секцию не + читают. + """ + + # секунды между плановыми сверками сервиса уборщика; 0 — без плановой + interval_seconds: float = Field(default=3600, ge=0) + # ключей на страницу списка S3 и строк на запрос к PostgreSQL; S3 отдаёт + # не больше 1000 ключей за страницу + page_size: int = Field(default=1000, ge=1, le=1000) + # предел изменений за проход: больше — ни одного изменения и код 3 + max_changes: int = Field(default=100, ge=1) + + class Settings(BaseSettings): model_config = SettingsConfigDict( extra="ignore", @@ -280,6 +299,7 @@ class Settings(BaseSettings): idempotency: Idempotency = Idempotency() uploads: Uploads = Uploads() cleaner: Cleaner = Cleaner() + reconciler: Reconciler = Reconciler() @classmethod def settings_customise_sources( diff --git a/src/core/repos/attachment.py b/src/core/repos/attachment.py index 3ed9f150..ca473bd9 100644 --- a/src/core/repos/attachment.py +++ b/src/core/repos/attachment.py @@ -4,7 +4,10 @@ `ready` после неё (design change `attachments`, решение 1). Видимость `pending` решает сервис: repo отдаёт строку как есть. Незавершённые загрузки выбирает, блокирует, помечает и удаляет уборщик (design change -`upload-consistency`, решение 3). +`upload-consistency`, решение 3). Сверка bucket и БД выбирает строки +страницы списка S3 и строки `ready`, помечает потерянный оригинал +(`lost_at`) и снимает пометку (design change `track2-reconciler`, решения +3–5). """ from collections.abc import Collection @@ -12,16 +15,24 @@ from datetime import datetime from uuid import UUID from sqlalchemy import ( + BindParameter, ColumnElement, Row, + Text, + Uuid, + any_, + bindparam, delete, insert, literal, + or_, select, tuple_, update, ) +from sqlalchemy.dialects.postgresql import ARRAY from sqlalchemy.ext.asyncio import AsyncSession +from sqlalchemy.types import TypeEngine from src.infra.db.models import Attachment from src.schemas import dataclasses @@ -39,6 +50,7 @@ _ATTACHMENT_COLUMNS = ( Attachment.status, Attachment.created_at, Attachment.updated_at, + Attachment.lost_at, ) @@ -223,3 +235,115 @@ async def delete_attachment( .returning(Attachment.id) ) return (await db_session.execute(statement)).one_or_none() is not None + + +# сверка bucket и БД (design change track2-reconciler, решения 3–5) + + +async def get_attachments_for_objects( + db_session: AsyncSession, + *, + attachment_ids: Collection[UUID], + object_keys: Collection[str], +) -> list[dataclasses.AttachmentFullDTO]: + """Строки страницы списка S3 одним выражением: `id = ANY(:ids) OR + object_key = ANY(:keys)`. `ids` — из стандартных ключей + `/original`, `keys` — только нестандартные ключи: по `id` выборка + в 15 раз дешевле, чем по тексту ключа (design, Context).""" + statement = select(*_ATTACHMENT_COLUMNS).where( + or_( + Attachment.id == any_(_array(list(attachment_ids), Uuid())), + Attachment.object_key == any_(_array(list(object_keys), Text())), + ), + ) + rows = (await db_session.execute(statement)).all() + return [_to_dto(row) for row in rows] + + +async def get_ready_page( + db_session: AsyncSession, + *, + after: UUID | None, + limit: int, +) -> list[dataclasses.AttachmentFullDTO]: + """Строки `ready` keyset по `id` после `after` (Index Scan + `pk_attachments`, статус — фильтр).""" + statement = ( + select(*_ATTACHMENT_COLUMNS) + .where(Attachment.status == AttachmentStatus.READY.value) + .order_by(Attachment.id) + .limit(limit) + ) + if after is not None: + statement = statement.where(Attachment.id > after) + rows = (await db_session.execute(statement)).all() + return [_to_dto(row) for row in rows] + + +async def find_attachment_reference( + db_session: AsyncSession, + *, + attachment_id: UUID, + object_key: str, +) -> list[dataclasses.AttachmentFullDTO]: + """Строки, из-за которых объект нельзя удалить: строка этого `id` или + любая строка, которая ссылается на этот ключ (до двух строк).""" + statement = select(*_ATTACHMENT_COLUMNS).where( + or_( + Attachment.id == attachment_id, + Attachment.object_key == object_key, + ), + ) + rows = (await db_session.execute(statement)).all() + return [_to_dto(row) for row in rows] + + +async def mark_lost( + db_session: AsyncSession, + *, + attachment_id: UUID, + object_key: str, + lost_at: datetime, +) -> bool: + """Пометить оригинал потерянным: только `ready`, ещё не помеченное, с + тем же ключом. `status` и `updated_at` не меняются. `False` — условие + уже не выполняется.""" + statement = ( + update(Attachment) + .where( + Attachment.id == attachment_id, + Attachment.status == AttachmentStatus.READY.value, + Attachment.lost_at.is_(None), + Attachment.object_key == object_key, + ) + .values(lost_at=lost_at) + .returning(Attachment.id) + ) + return (await db_session.execute(statement)).one_or_none() is not None + + +async def clear_lost( + db_session: AsyncSession, + *, + attachment_id: UUID, + object_key: str, +) -> bool: + """Снять пометку: оригинал снова есть. `False` — пометки уже нет или + ключ другой.""" + statement = ( + update(Attachment) + .where( + Attachment.id == attachment_id, + Attachment.lost_at.is_not(None), + Attachment.object_key == object_key, + ) + .values(lost_at=None) + .returning(Attachment.id) + ) + return (await db_session.execute(statement)).one_or_none() is not None + + +def _array(values: list, item_type: TypeEngine) -> BindParameter: + # один параметр-массив вместо списка параметров IN: план не зависит от + # длины страницы (до 1000) + return bindparam(None, values, type_=ARRAY(item_type)) diff --git a/src/core/repos/attachment_object.py b/src/core/repos/attachment_object.py index bfe4f733..cd78f307 100644 --- a/src/core/repos/attachment_object.py +++ b/src/core/repos/attachment_object.py @@ -12,7 +12,12 @@ from contextlib import AbstractAsyncContextManager from typing import BinaryIO from uuid import UUID -from src.infra.s3 import ObjectStorage, StoredObject +from src.infra.s3 import ( + ObjectStorage, + StoredObject, + StoredObjectInfo, + StoredObjectPage, +) from src.utils.constants import ( ATTACHMENT_KEY_PREFIX, ATTACHMENT_ORIGINAL_SUFFIX, @@ -31,6 +36,68 @@ def original_key(storage: ObjectStorage, *, attachment_id: UUID) -> str: ) +def originals_prefix(storage: ObjectStorage) -> str: + """Префикс объектов вложений своей базы: `/attachments/`. + Других префиксов сверка не читает, список ключу уборщика разрешён + только с ним (design change `track2-reconciler`, решение 2).""" + return ( + f"{storage.namespace}{S3_KEY_SEPARATOR}" + f"{ATTACHMENT_KEY_PREFIX}{S3_KEY_SEPARATOR}" + ) + + +def parse_original_key(storage: ObjectStorage, *, key: str) -> UUID | None: + """`id` вложения из ключа `/attachments//original`, где + `id` — UUID в записи сервера (нижний регистр, с дефисами); ключ другого + вида — `None`: такого API не пишет.""" + prefix = originals_prefix(storage) + suffix = f"{S3_KEY_SEPARATOR}{ATTACHMENT_ORIGINAL_SUFFIX}" + if not key.startswith(prefix) or not key.endswith(suffix): + return None + text = key[len(prefix) : -len(suffix)] + try: + attachment_id = UUID(text) + except ValueError: + return None + return attachment_id if str(attachment_id) == text else None + + +async def list_originals( + storage: ObjectStorage, + *, + token: str | None, + max_keys: int, +) -> StoredObjectPage: + """Страница объектов под префиксом вложений своей базы.""" + return await storage.list_page( + originals_prefix(storage), + token=token, + max_keys=max_keys, + ) + + +async def probe_originals(storage: ObjectStorage) -> None: + """Bucket на месте и список разрешён: страница из одного ключа. Иначе + — `ObjectStorageUnavailable`. HEAD bucket не подходит: при условной + политике списка он 403 (design, Context).""" + await storage.list_page( + originals_prefix(storage), + token=None, + max_keys=1, + ) + + +async def head_original( + storage: ObjectStorage, + *, + key: str, +) -> StoredObjectInfo | None: + """Размер и время записи объекта; `None` — объекта нет (или нет + bucket: у HEAD они неотличимы, поэтому сверка проверяет bucket + отдельно, `probe_originals`).""" + return await storage.head(key) + + async def put_original( storage: ObjectStorage, *, diff --git a/src/core/services/__init__.py b/src/core/services/__init__.py index 5ee2408b..2c815098 100644 --- a/src/core/services/__init__.py +++ b/src/core/services/__init__.py @@ -1,5 +1,6 @@ from .attachment import AttachmentService from .attachment_cleanup import AttachmentCleanupService +from .attachment_reconcile import AttachmentReconcileService from .chat import ChatService from .message import MessageService from .session import SessionService @@ -7,6 +8,7 @@ from .user import UserService __all__ = [ "AttachmentCleanupService", + "AttachmentReconcileService", "AttachmentService", "ChatService", "MessageService", diff --git a/src/core/services/attachment.py b/src/core/services/attachment.py index 0f3a6fe6..1f587087 100644 --- a/src/core/services/attachment.py +++ b/src/core/services/attachment.py @@ -394,7 +394,11 @@ class AttachmentService: """Оригинал потоком из S3 (решение 7). Отказ S3 — 503 до заголовков ответа. Нет объекта или размер в S3 - другой — `error` в журнале и 500; строку сервис не меняет. + другой — `error` в журнале и 500; строку сервис не меняет. Оригинал, + который сверка уже пометила потерянным (`lost_at`), — `info` и 404 + без обращения к S3, как отсутствующий вариант готового вложения + (design change `track2-reconciler`, решение 5; ответ — вопрос + преподавателю, вариант по умолчанию). """ attachment = await self.get_attachment( attachment_id=attachment_id, @@ -405,6 +409,9 @@ class AttachmentService: attachment_id=attachment_id, object_key=attachment.object_key, ) + if attachment.lost_at is not None: + log.info("Attachment content is lost") + raise exceptions.AttachmentNotFound stack = AsyncExitStack() try: stored = await stack.enter_async_context( diff --git a/src/core/services/attachment_cleanup.py b/src/core/services/attachment_cleanup.py index a7888dc8..7d41abe6 100644 --- a/src/core/services/attachment_cleanup.py +++ b/src/core/services/attachment_cleanup.py @@ -85,7 +85,7 @@ class AttachmentCleanupService: if stop_requested(): interrupted_by = INTERRUPTED_BY_STOP break - if await self._remove( + if await self.remove_stale_pending( attachment_id=candidate.id, older_than=older_than, stop_requested=stop_requested, @@ -129,16 +129,17 @@ class AttachmentCleanupService: log.debug("Finished cleanup pass", **fields) return result - async def _remove( + async def remove_stale_pending( self, *, attachment_id: UUID, older_than: datetime, - stop_requested: Callable[[], bool], - log: AbstractLogger, + stop_requested: Callable[[], bool] = _never, + log: AbstractLogger = logger, ) -> bool: """Убрать одну строку; `False` — её уже нет, она `ready` или её - держит другой процесс. + держит другой процесс. Тот же шаг вызывает сверка bucket и БД для + зависших загрузок (design change `track2-reconciler`, решение 7). Два шага («Уточнения apply», п. 16 и 21): 1. Пометка — своя транзакция: блокировка, `updated_at` = сейчас, diff --git a/src/core/services/attachment_reconcile.py b/src/core/services/attachment_reconcile.py new file mode 100644 index 00000000..ab8fd220 --- /dev/null +++ b/src/core/services/attachment_reconcile.py @@ -0,0 +1,741 @@ +"""Сверка bucket и БД (design change `track2-reconciler`, решения 3, 4, 7 +и 8). + +Сервис процесса уборщика (`src/cleaner/`), а не реплик API. Проход: +1. S3 → БД: страницы списка объектов под `<база>/attachments/`, на + страницу — одно выражение к БД по `id` из стандартных ключей и по + тексту нестандартных; каждый ключ — в множество `seen`; +2. БД → S3: keyset строк `ready` по `id`, ключа нет в `seen` — кандидат + «метаданные без объекта»; +3. зависшие загрузки — кандидаты уборщика (`get_stale_pending`); +4. перепроверка каждого кандидата в БД и HEAD перед решением, в обоих + режимах; отсутствие объекта — только после проверки, что bucket на + месте; +5. предел изменений, затем, с `apply`, действия по порядку: зависшие + загрузки (процедурой уборщика) → объекты без метаданных → пометки + потерянных → снятия пометок. Каждое действие перед собой ещё раз + перепроверяет своё условие. + +Удаляется только объект без строки и зависшая загрузка; строки `ready`, +объекты, на которые ссылается строка, и чужие ключи — никогда. Отказ +хранилища на шагах 1–4 прерывает проход без единого изменения, на шаге 5 — +после текущего действия; каждое действие безопасно повторять. +""" + +import time +from collections import Counter +from collections.abc import Callable +from dataclasses import replace +from datetime import datetime +from types import MappingProxyType +from uuid import UUID + +from src.core import exceptions +from src.core.repos import attachment as attachment_repo +from src.core.repos import attachment_object as attachment_object_repo +from src.core.services.attachment import DbScope +from src.core.services.attachment_cleanup import ( + INTERRUPTED_BY_DATABASE, + INTERRUPTED_BY_OBJECT_STORAGE, + INTERRUPTED_BY_STOP, + AttachmentCleanupService, +) +from src.infra.logger import AbstractLogger, get_logger +from src.infra.s3 import ObjectStorage, StoredObjectInfo +from src.schemas import dataclasses +from src.schemas.enums import ( + AttachmentStatus, + ReconcileAction, + ReconcileFinding, +) +from src.utils.constants import RECONCILE_FINDINGS_LOGGED_MAX +from src.utils.utc import utcnow + +logger: AbstractLogger = get_logger().bind( + module="attachment_reconcile_service", +) + +# классы, исправление которых — изменение под пределом `max_changes` +LIMITED_KINDS = frozenset( + { + ReconcileFinding.ORPHAN_OBJECT, + ReconcileFinding.MISSING_OBJECT, + ReconcileFinding.SIZE_MISMATCH, + ReconcileFinding.RESTORED_OBJECT, + }, +) +# порядок действий `apply` (решение 7); чужой объект действия не имеет +ACTION_ORDER = ( + ReconcileFinding.STALE_PENDING, + ReconcileFinding.ORPHAN_OBJECT, + ReconcileFinding.MISSING_OBJECT, + ReconcileFinding.SIZE_MISMATCH, + ReconcileFinding.RESTORED_OBJECT, +) +# классы, у которых отсутствие объекта подтверждается: сначала — bucket +NEEDS_BUCKET = frozenset( + {ReconcileFinding.MISSING_OBJECT, ReconcileFinding.SIZE_MISMATCH}, +) + + +def _never() -> bool: + return False + + +def _age_seconds(moment: datetime, *, now: datetime) -> int: + return max(0, round((now - moment).total_seconds())) + + +class _Stopped(Exception): + """Сигнал остановки между страницами или действиями.""" + + +class _Pass: + """Счётчики и находки одного прохода.""" + + def __init__(self, *, apply: bool, now: datetime) -> None: + self.apply = apply + self.now = now + self.listed_objects = 0 + self.checked_rows = 0 + self.fresh_objects = 0 + self.fresh_rows = 0 + self.lost_known = 0 + self.seen: set[str] = set() + self.candidates: list[dataclasses.ReconcileFindingDTO] = [] + self.confirmed: list[dataclasses.ReconcileFindingDTO] = [] + # индексы `confirmed`: исправленные и выбывшие на действии + self.fixed: dict[int, ReconcileAction] = {} + self.dropped: set[int] = set() + self.refused = False + self.logged = 0 + self.unlogged = 0 + + def age(self, moment: datetime) -> int: + return _age_seconds(moment, now=self.now) + + +class AttachmentReconcileService: + """Сверка объектов вложений своей базы с их метаданными. + + `db_scope` — фабрика короткой сессии процесса уборщика, `storage` — + клиент S3 с ключами пользователя уборщика (список — только по + префиксу вложений своей базы). Зависшие загрузки убирает + `AttachmentCleanupService` тем же шагом, что сервис уборки. + """ + + def __init__(self, db_scope: DbScope, storage: ObjectStorage) -> None: + self.db_scope = db_scope + self.storage = storage + self.cleanup = AttachmentCleanupService( + db_scope=db_scope, + storage=storage, + ) + + async def reconcile( + self, + *, + older_than: datetime, + apply: bool, + max_changes: int, + page_size: int, + batch_size: int, + stop_requested: Callable[[], bool] = _never, + ) -> dataclasses.ReconcilePassDTO: + """Один проход сверки; `older_than` — порог grace прохода. + + Без `apply` ничего не меняет. Отказ S3 или PostgreSQL прерывает + проход (`interrupted_by`); сигнал (`stop_requested()`) — между + страницами и действиями, текущий вызов доводится до конца. Отказ, + пришедший уже после сигнала, считается остановкой. + """ + started = time.monotonic() + log = logger.bind(method="reconcile", apply=apply) + state = _Pass(apply=apply, now=utcnow()) + interrupted_by: str | None = None + try: + await self._list_objects( + state, + older_than=older_than, + page_size=page_size, + stop_requested=stop_requested, + ) + await self._check_rows( + state, + older_than=older_than, + page_size=page_size, + stop_requested=stop_requested, + ) + await self._stale_pending( + state, + older_than=older_than, + batch_size=batch_size, + stop_requested=stop_requested, + ) + await self._recheck_all( + state, + older_than=older_than, + stop_requested=stop_requested, + ) + if apply: + await self._act( + state, + older_than=older_than, + max_changes=max_changes, + stop_requested=stop_requested, + log=log, + ) + except _Stopped: + interrupted_by = INTERRUPTED_BY_STOP + except exceptions.ObjectStorageUnavailable: + # причину уже записал клиент S3 (`object_storage`) + interrupted_by = ( + INTERRUPTED_BY_STOP + if stop_requested() + else INTERRUPTED_BY_OBJECT_STORAGE + ) + except exceptions.ServiceUnavailable: + # причину уже записал `session_scope` (`database`) + interrupted_by = ( + INTERRUPTED_BY_STOP + if stop_requested() + else INTERRUPTED_BY_DATABASE + ) + return self._finish( + state, + interrupted_by=interrupted_by, + duration_ms=round((time.monotonic() - started) * 1000), + log=log, + ) + + # --------------------------------------------------------- классификация + + async def _list_objects( + self, + state: _Pass, + *, + older_than: datetime, + page_size: int, + stop_requested: Callable[[], bool], + ) -> None: + """Шаг 1, S3 → БД: страницы списка и строки страницы одним + выражением; классификация без новых вызовов S3.""" + token: str | None = None + while True: + if stop_requested(): + raise _Stopped + page = await attachment_object_repo.list_originals( + self.storage, + token=token, + max_keys=page_size, + ) + state.listed_objects += len(page.objects) + parsed = { + item.key: attachment_object_repo.parse_original_key( + self.storage, + key=item.key, + ) + for item in page.objects + } + ids = {value for value in parsed.values() if value is not None} + keys = {key for key, value in parsed.items() if value is None} + rows: list[dataclasses.AttachmentFullDTO] = [] + if parsed: + async with self.db_scope() as db_session: + rows = await attachment_repo.get_attachments_for_objects( + db_session=db_session, + attachment_ids=ids, + object_keys=keys, + ) + by_id = {row.id: row for row in rows} + by_key = {row.object_key: row for row in rows} + for item in page.objects: + state.seen.add(item.key) + attachment_id = parsed[item.key] + row = ( + by_id.get(attachment_id) + if attachment_id is not None + else by_key.get(item.key) + ) + if row is not None and row.object_key == item.key: + self._row_with_object( + state, + row=row, + stored=item, + older_than=older_than, + ) + continue + if _is_fresh(item, older_than=older_than): + state.fresh_objects += 1 + continue + # нет строки — объект без метаданных; строка этого id с + # другим ключом или ключ, которого API не пишет, — чужой + kind = ( + ReconcileFinding.ORPHAN_OBJECT + if attachment_id is not None and row is None + else ReconcileFinding.UNKNOWN_OBJECT + ) + state.candidates.append( + dataclasses.ReconcileFindingDTO( + kind=kind, + object_key=item.key, + attachment_id=attachment_id, + age_seconds=_object_age(state, item), + ), + ) + token = page.next_token + if token is None: + return + + def _row_with_object( + self, + state: _Pass, + *, + row: dataclasses.AttachmentFullDTO, + stored: StoredObjectInfo, + older_than: datetime, + ) -> None: + if row.status != AttachmentStatus.READY: + # строка pending: объект её загрузки — дело уборщика + return + same_size = stored.size == row.size_bytes + if row.lost_at is not None: + if same_size: + state.candidates.append( + _finding( + ReconcileFinding.RESTORED_OBJECT, + row, + state, + stored_size=stored.size, + ), + ) + else: + state.lost_known += 1 + return + if same_size: + return + if row.updated_at >= older_than: + state.fresh_rows += 1 + return + state.candidates.append( + _finding( + ReconcileFinding.SIZE_MISMATCH, + row, + state, + stored_size=stored.size, + ), + ) + + async def _check_rows( + self, + state: _Pass, + *, + older_than: datetime, + page_size: int, + stop_requested: Callable[[], bool], + ) -> None: + """Шаг 2, БД → S3: строки `ready`, ключей которых нет в списке.""" + after: UUID | None = None + while True: + if stop_requested(): + raise _Stopped + async with self.db_scope() as db_session: + rows = await attachment_repo.get_ready_page( + db_session=db_session, + after=after, + limit=page_size, + ) + for row in rows: + state.checked_rows += 1 + if row.object_key in state.seen: + continue + if row.lost_at is not None: + state.lost_known += 1 + elif row.updated_at >= older_than: + state.fresh_rows += 1 + else: + state.candidates.append( + _finding(ReconcileFinding.MISSING_OBJECT, row, state), + ) + if len(rows) < page_size: + return + after = rows[-1].id + + async def _stale_pending( + self, + state: _Pass, + *, + older_than: datetime, + batch_size: int, + stop_requested: Callable[[], bool], + ) -> None: + """Шаг 3: зависшие загрузки — те же кандидаты, что у уборщика.""" + after: tuple[datetime, UUID] | None = None + while True: + if stop_requested(): + raise _Stopped + async with self.db_scope() as db_session: + rows = await attachment_repo.get_stale_pending( + db_session=db_session, + older_than=older_than, + after=after, + limit=batch_size, + ) + state.candidates.extend( + dataclasses.ReconcileFindingDTO( + kind=ReconcileFinding.STALE_PENDING, + object_key=row.object_key, + attachment_id=row.id, + age_seconds=state.age(row.created_at), + ) + for row in rows + ) + if len(rows) < batch_size: + return + after = (rows[-1].created_at, rows[-1].id) + + # ---------------------------------------------------------- перепроверка + + async def _recheck_all( + self, + state: _Pass, + *, + older_than: datetime, + stop_requested: Callable[[], bool], + ) -> None: + """Шаг 4: каждый кандидат подтверждается в БД и S3 до решения; + не подтвердился — выбывает без записи.""" + if any(item.kind in NEEDS_BUCKET for item in state.candidates): + await attachment_object_repo.probe_originals(self.storage) + for candidate in state.candidates: + if stop_requested(): + raise _Stopped + confirmed = await self._recheck( + candidate, + older_than=older_than, + state=state, + ) + if confirmed is not None: + state.confirmed.append(confirmed) + + async def _recheck( + self, + candidate: dataclasses.ReconcileFindingDTO, + *, + older_than: datetime, + state: _Pass, + ) -> dataclasses.ReconcileFindingDTO | None: + kind = candidate.kind + if kind in ( + ReconcileFinding.STALE_PENDING, + ReconcileFinding.UNKNOWN_OBJECT, + ): + # зависшую загрузку уборщик перепроверяет под блокировкой сам, + # чужой объект сверка не трогает + return candidate + if kind == ReconcileFinding.ORPHAN_OBJECT: + return await self._recheck_orphan( + candidate, + older_than=older_than, + state=state, + ) + row = await self._get_row(candidate) + if row is None or row.status != AttachmentStatus.READY: + return None + stored = await attachment_object_repo.head_original( + self.storage, + key=candidate.object_key, + ) + if kind == ReconcileFinding.RESTORED_OBJECT: + if row.lost_at is None or stored is None: + return None + return candidate if stored.size == row.size_bytes else None + if row.lost_at is not None: + return None + if stored is None: + return _finding(ReconcileFinding.MISSING_OBJECT, row, state) + if stored.size != row.size_bytes: + return _finding( + ReconcileFinding.SIZE_MISMATCH, + row, + state, + stored_size=stored.size, + ) + return None + + async def _recheck_orphan( + self, + candidate: dataclasses.ReconcileFindingDTO, + *, + older_than: datetime, + state: _Pass, + ) -> dataclasses.ReconcileFindingDTO | None: + """Строки с этим `id` или ключом нет, объект на месте и старше + порога. Строка другого `id` ссылается на ключ — чужой объект.""" + references = await self._references(candidate) + if any( + row.object_key == candidate.object_key + and row.id != candidate.attachment_id + for row in references + ): + return replace(candidate, kind=ReconcileFinding.UNKNOWN_OBJECT) + if references: + return None + stored = await attachment_object_repo.head_original( + self.storage, + key=candidate.object_key, + ) + if stored is None or _is_fresh(stored, older_than=older_than): + return None + return replace(candidate, age_seconds=_object_age(state, stored)) + + async def _get_row( + self, + candidate: dataclasses.ReconcileFindingDTO, + ) -> dataclasses.AttachmentFullDTO | None: + if candidate.attachment_id is None: + return None + async with self.db_scope() as db_session: + row = await attachment_repo.get_attachment( + db_session=db_session, + attachment_id=candidate.attachment_id, + ) + if row is None or row.object_key != candidate.object_key: + return None + return row + + async def _references( + self, + candidate: dataclasses.ReconcileFindingDTO, + ) -> list[dataclasses.AttachmentFullDTO]: + if candidate.attachment_id is None: + return [] + async with self.db_scope() as db_session: + return await attachment_repo.find_attachment_reference( + db_session=db_session, + attachment_id=candidate.attachment_id, + object_key=candidate.object_key, + ) + + # -------------------------------------------------------------- действия + + async def _act( + self, + state: _Pass, + *, + older_than: datetime, + max_changes: int, + stop_requested: Callable[[], bool], + log: AbstractLogger, + ) -> None: + """Шаг 5: предел изменений, затем действия по порядку решения 7.""" + changes = sum(item.kind in LIMITED_KINDS for item in state.confirmed) + if changes > max_changes: + state.refused = True + log.error( + "Reconcile changes exceed limit", + changes=changes, + max_changes=max_changes, + ) + bucket_probed = False + for kind in ACTION_ORDER: + if state.refused and kind in LIMITED_KINDS: + continue + for index, finding in enumerate(state.confirmed): + if finding.kind != kind: + continue + if stop_requested(): + raise _Stopped + if kind in NEEDS_BUCKET and not bucket_probed: + # отсутствие объекта — снова только при живом bucket + await attachment_object_repo.probe_originals(self.storage) + bucket_probed = True + action = await self._fix( + finding, + older_than=older_than, + stop_requested=stop_requested, + ) + if action is None: + state.dropped.add(index) + continue + state.fixed[index] = action + self._record(state, finding, action=action, log=log) + + async def _fix( + self, + finding: dataclasses.ReconcileFindingDTO, + *, + older_than: datetime, + stop_requested: Callable[[], bool], + ) -> ReconcileAction | None: + """Одно действие с перепроверкой непосредственно перед ним; `None` + — условие уже не выполняется, ничего не изменено.""" + kind = finding.kind + if kind == ReconcileFinding.STALE_PENDING: + removed = await self.cleanup.remove_stale_pending( + attachment_id=finding.attachment_id, + older_than=older_than, + stop_requested=stop_requested, + log=logger.bind(method="reconcile"), + ) + return ReconcileAction.REMOVED_PENDING if removed else None + if kind == ReconcileFinding.ORPHAN_OBJECT: + if await self._references(finding): + return None + await attachment_object_repo.delete_original( + self.storage, + key=finding.object_key, + ) + return ReconcileAction.DELETED_OBJECT + stored = await attachment_object_repo.head_original( + self.storage, + key=finding.object_key, + ) + if kind == ReconcileFinding.RESTORED_OBJECT: + if stored is None or stored.size != finding.size_bytes: + return None + async with self.db_scope() as db_session: + cleared = await attachment_repo.clear_lost( + db_session=db_session, + attachment_id=finding.attachment_id, + object_key=finding.object_key, + ) + await db_session.commit() + return ReconcileAction.CLEARED_LOST if cleared else None + # метаданные без объекта или другой размер: объекта по-прежнему нет + # или размер по-прежнему другой + if stored is not None and stored.size == finding.size_bytes: + return None + async with self.db_scope() as db_session: + marked = await attachment_repo.mark_lost( + db_session=db_session, + attachment_id=finding.attachment_id, + object_key=finding.object_key, + lost_at=utcnow(), + ) + await db_session.commit() + return ReconcileAction.MARKED_LOST if marked else None + + # ------------------------------------------------------------------ итог + + def _record( + self, + state: _Pass, + finding: dataclasses.ReconcileFindingDTO, + *, + action: ReconcileAction | None, + log: AbstractLogger, + ) -> None: + """Запись о расхождении: `info` с действием — исправлено, + `warning` — осталось. Не больше `RECONCILE_FINDINGS_LOGGED_MAX` + записей за проход, остальные — числом в итоге.""" + if state.logged >= RECONCILE_FINDINGS_LOGGED_MAX: + state.unlogged += 1 + return + state.logged += 1 + fields: dict[str, object] = { + "kind": finding.kind.value, + "object_key": finding.object_key, + "attachment_id": finding.attachment_id, + "age_seconds": finding.age_seconds, + } + if ( + finding.stored_size is not None + and finding.stored_size != finding.size_bytes + ): + fields["size_bytes"] = finding.size_bytes + fields["stored_size"] = finding.stored_size + if action is None: + log.warning("Found storage discrepancy", **fields) + else: + log.info( + "Fixed storage discrepancy", + action=action.value, + **fields, + ) + + def _finish( + self, + state: _Pass, + *, + interrupted_by: str | None, + duration_ms: int, + log: AbstractLogger, + ) -> dataclasses.ReconcilePassDTO: + remaining = [ + finding + for index, finding in enumerate(state.confirmed) + if index not in state.fixed and index not in state.dropped + ] + for finding in remaining: + self._record(state, finding, action=None, log=log) + found = Counter( + finding.kind + for index, finding in enumerate(state.confirmed) + if index not in state.dropped + ) + fixed = Counter(state.confirmed[index].kind for index in state.fixed) + result = dataclasses.ReconcilePassDTO( + apply=state.apply, + listed_objects=state.listed_objects, + checked_rows=state.checked_rows, + found=MappingProxyType(dict(found)), + fixed=MappingProxyType(dict(fixed)), + remaining=len(remaining), + fresh_objects=state.fresh_objects, + fresh_rows=state.fresh_rows, + lost_known=state.lost_known, + refused=state.refused, + unlogged=state.unlogged, + interrupted_by=interrupted_by, + duration_ms=duration_ms, + ) + fields = { + "listed_objects": result.listed_objects, + "checked_rows": result.checked_rows, + "found": {kind.value: count for kind, count in found.items()}, + "fixed": {kind.value: count for kind, count in fixed.items()}, + "remaining": result.remaining, + "fresh_objects": result.fresh_objects, + "fresh_rows": result.fresh_rows, + "lost_known": result.lost_known, + "refused": result.refused, + "unlogged": result.unlogged, + "interrupted_by": result.interrupted_by, + "duration_ms": result.duration_ms, + } + if result.remaining or result.refused or interrupted_by is not None: + log.warning("Finished reconcile pass", **fields) + else: + log.info("Finished reconcile pass", **fields) + return result + + +def _is_fresh(stored: StoredObjectInfo, *, older_than: datetime) -> bool: + """Объект записан или изменён не раньше порога; без времени — свежий: + удалять без доказанного возраста нельзя.""" + return stored.last_modified is None or stored.last_modified >= older_than + + +def _object_age(state: _Pass, stored: StoredObjectInfo) -> int: + return ( + 0 if stored.last_modified is None else state.age(stored.last_modified) + ) + + +def _finding( + kind: ReconcileFinding, + row: dataclasses.AttachmentFullDTO, + state: _Pass, + *, + stored_size: int | None = None, +) -> dataclasses.ReconcileFindingDTO: + """Находка по строке: возраст — от перевода в `ready` (`updated_at`).""" + return dataclasses.ReconcileFindingDTO( + kind=kind, + object_key=row.object_key, + attachment_id=row.id, + age_seconds=state.age(row.updated_at), + size_bytes=row.size_bytes, + stored_size=stored_size, + ) diff --git a/src/infra/db/models/attachment.py b/src/infra/db/models/attachment.py index 2c1cca65..a894f1d1 100644 --- a/src/infra/db/models/attachment.py +++ b/src/infra/db/models/attachment.py @@ -98,6 +98,11 @@ class Attachment(Base): object_key: Mapped[str] = mapped_column(Text, unique=True) status: Mapped[str] = mapped_column(Text) updated_at: Mapped[datetime] = mapped_column(DateTime(timezone=True)) + # когда сверка подтвердила, что оригинала ready нет или он другого + # размера (design change track2-reconciler, решения 5 и 6); NULL — не + # помечено. Индекса нет: сверка просматривает все строки ready, API + # читает по id + lost_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True)) class MessageAttachment(Base): diff --git a/src/infra/s3/__init__.py b/src/infra/s3/__init__.py index 953e925c..911ed8c5 100644 --- a/src/infra/s3/__init__.py +++ b/src/infra/s3/__init__.py @@ -2,6 +2,7 @@ from src.infra.s3.client import ( ObjectStorage, StoredObject, StoredObjectInfo, + StoredObjectPage, create_object_storage, ) @@ -9,5 +10,6 @@ __all__ = [ "ObjectStorage", "StoredObject", "StoredObjectInfo", + "StoredObjectPage", "create_object_storage", ] diff --git a/src/infra/s3/client.py b/src/infra/s3/client.py index 7b876c2b..12e1be5a 100644 --- a/src/infra/s3/client.py +++ b/src/infra/s3/client.py @@ -15,7 +15,12 @@ Valkey, не повторяется, а загрузку повторяет кл Удалённый bucket у HEAD не отличить от отсутствующего ключа: у ответа нет тела, и SeaweedFS отвечает одинаковым 404. `head` тогда отдаёт `None`, а -`put`, `open` и `delete` — `ObjectStorageUnavailable`. +`put`, `open`, `delete` и `list_page` — `ObjectStorageUnavailable`. + +Список объектов по префиксу (`list_page`, ListObjectsV2) — для сверки +bucket и БД процессом уборщика (design change `track2-reconciler`, +решение 3): страница — один вызов со сроком, нет bucket — ошибка, а не +пустая страница. В журнал — адрес, bucket, ключ объекта, размер, длительность и класс ошибки; ключей доступа, секрета и подписи там нет. Логгеры botocore, @@ -28,6 +33,7 @@ import time from collections.abc import AsyncIterator from contextlib import AsyncExitStack, asynccontextmanager from dataclasses import dataclass +from datetime import datetime from typing import Any, BinaryIO import aiohttp @@ -82,11 +88,23 @@ DEFAULT_CHUNK_BYTES = 64 * 1024 @dataclass(frozen=True, slots=True) class StoredObjectInfo: - """Метаданные объекта в bucket.""" + """Метаданные объекта в bucket. `last_modified` — время записи по часам + S3 (точность — секунда), из списка и HEAD; у `open` его нет.""" key: str size: int content_type: str | None + last_modified: datetime | None = None + + +@dataclass(frozen=True, slots=True) +class StoredObjectPage: + """Страница списка объектов по префиксу; `next_token` — продолжение, + `None` — страница последняя (design change `track2-reconciler`, + решение 3).""" + + objects: tuple[StoredObjectInfo, ...] + next_token: str | None class StoredObject: @@ -200,8 +218,44 @@ class ObjectStorage: key=key, size=response["ContentLength"], content_type=response.get("ContentType"), + last_modified=response.get("LastModified"), ) + async def list_page( + self, + prefix: str, + *, + token: str | None, + max_keys: int, + ) -> StoredObjectPage: + """Страница ListObjectsV2 по префиксу: до `max_keys` ключей с + размером и временем записи, плюс токен продолжения. + + Срок — как у любого вызова, на страницу. Нет bucket — не пустая + страница, а `ObjectStorageUnavailable` («bucket is missing»), + отказ в списке — «denied access» (спек `object-storage`, «Клиент + хранилища в приложении»). + """ + params: dict[str, Any] = {"Prefix": prefix, "MaxKeys": max_keys} + if token is not None: + params["ContinuationToken"] = token + response = await self._call("list_objects_v2", None, **params) + objects = tuple( + StoredObjectInfo( + key=item["Key"], + size=item["Size"], + content_type=None, + last_modified=item["LastModified"], + ) + for item in response.get("Contents", ()) + ) + next_token = ( + response.get("NextContinuationToken") + if response.get("IsTruncated") + else None + ) + return StoredObjectPage(objects=objects, next_token=next_token) + @asynccontextmanager async def open(self, key: str) -> AsyncIterator[StoredObject]: """Объект на чтение блоками; нет объекта — `StoredObjectMissing`. @@ -268,26 +322,31 @@ class ObjectStorage: async def _call( self, operation: str, - key: str, + key: str | None, *, size: int | None = None, **params: Any, ) -> dict[str, Any]: + """Вызов клиента со сроком и переводом ошибок. `key=None` — вызов + над bucket без ключа (список), в журнал тогда — `prefix`.""" client = await self._get_client() started = time.monotonic() + if key is not None: + params["Key"] = key + target = key if key is not None else params.get("Prefix") try: async with asyncio.timeout(self._timeout_seconds): response = await getattr(client, operation)( Bucket=self.bucket, - Key=key, **params, ) except TRANSLATED_ERRORS as e: failure = self._failure( e, operation=operation, - key=key, + key=target, started=started, + listing=key is None, ) if failure is None: raise @@ -296,7 +355,7 @@ class ObjectStorage: "Called object storage", operation=operation, bucket=self.bucket, - key=key, + key=target, size=size, duration_ms=self._duration_ms(started), ) @@ -329,11 +388,13 @@ class ObjectStorage: error: Exception, *, operation: str, - key: str, + key: str | None, started: float, + listing: bool = False, ) -> Exception | None: """Доменное исключение вместо ошибки клиента; `None` — ошибку не - переводить (дефект, 500).""" + переводить (дефект, 500). У списка (`listing`) 404 без тела — тоже + отсутствующий bucket: «объекта нет» у списка не бывает.""" fields = { "operation": operation, "endpoint": self._endpoint, @@ -348,7 +409,9 @@ class ObjectStorage: "HTTPStatusCode", 0, ) - if code in MISSING_BUCKET_ERROR_CODES: + if code in MISSING_BUCKET_ERROR_CODES or ( + listing and code in MISSING_ERROR_CODES + ): logger.error( "Object storage bucket is missing", error_code=code, diff --git a/src/schemas/dataclasses/__init__.py b/src/schemas/dataclasses/__init__.py index 1cfdba49..ba37b23c 100644 --- a/src/schemas/dataclasses/__init__.py +++ b/src/schemas/dataclasses/__init__.py @@ -3,6 +3,8 @@ from .attachment import ( AttachmentFullDTO, AttachmentInListDTO, CleanupPassDTO, + ReconcileFindingDTO, + ReconcilePassDTO, ) from .chat import ChatFullDTO, ChatPageDTO from .idempotency import IdempotencyRecordDTO @@ -21,6 +23,8 @@ __all__ = [ "IdempotencyRecordDTO", "MessageFullDTO", "MessagePageDTO", + "ReconcileFindingDTO", + "ReconcilePassDTO", "SessionFullDTO", "SessionTokenDTO", "UserCredentialsDTO", diff --git a/src/schemas/dataclasses/attachment.py b/src/schemas/dataclasses/attachment.py index f8731990..6f799f25 100644 --- a/src/schemas/dataclasses/attachment.py +++ b/src/schemas/dataclasses/attachment.py @@ -1,9 +1,9 @@ -from collections.abc import AsyncIterator, Awaitable, Callable +from collections.abc import AsyncIterator, Awaitable, Callable, Mapping from dataclasses import dataclass from datetime import datetime from uuid import UUID -from src.schemas.enums import AttachmentStatus, ImageType +from src.schemas.enums import AttachmentStatus, ImageType, ReconcileFinding @dataclass(frozen=True, slots=True) @@ -11,7 +11,9 @@ class AttachmentFullDTO: """Строка вложения: метаданные и ключ объекта в S3. `object_key` и статус `pending` в API не попадают; `sha256` — байты - SHA-256 оригинала, hex собирает модель ответа. + SHA-256 оригинала, hex собирает модель ответа. `lost_at` — когда сверка + подтвердила потерю оригинала (design change `track2-reconciler`, + решение 5); в ответы API не попадает. """ id: UUID @@ -25,6 +27,7 @@ class AttachmentFullDTO: status: AttachmentStatus created_at: datetime updated_at: datetime + lost_at: datetime | None = None @dataclass(frozen=True, slots=True) @@ -54,6 +57,52 @@ class CleanupPassDTO: duration_ms: int +@dataclass(frozen=True, slots=True) +class ReconcileFindingDTO: + """Расхождение bucket и БД, найденное сверкой (design change + `track2-reconciler`, решение 8). + + `attachment_id` — если известен (из ключа или строки), `age_seconds` — + возраст объекта (`LastModified`) или строки (`updated_at` у ready, + `created_at` у pending). `size_bytes` и `stored_size` — размеры строки и + объекта, если известны оба. + """ + + kind: ReconcileFinding + object_key: str + attachment_id: UUID | None + age_seconds: int + size_bytes: int | None = None + stored_size: int | None = None + + +@dataclass(frozen=True, slots=True) +class ReconcilePassDTO: + """Итог прохода сверки. + + `found` и `fixed` — подтверждённые и исправленные расхождения по + классам (неизменяемые отображения), `remaining` — сколько осталось. + `refused` — `--apply` отказался по пределу изменений, `unlogged` — + сколько расхождений не записано отдельными записями, + `interrupted_by` — причина прерывания (`object_storage`, `database`, + `stop`) или `None`. + """ + + apply: bool + listed_objects: int + checked_rows: int + found: Mapping[ReconcileFinding, int] + fixed: Mapping[ReconcileFinding, int] + remaining: int + fresh_objects: int + fresh_rows: int + lost_known: int + refused: bool + unlogged: int + interrupted_by: str | None + duration_ms: int + + @dataclass(frozen=True, slots=True) class AttachmentContentDTO: """Оригинал вложения на отдачу потоком. diff --git a/src/schemas/enums/__init__.py b/src/schemas/enums/__init__.py index a3c6b217..b15f410f 100644 --- a/src/schemas/enums/__init__.py +++ b/src/schemas/enums/__init__.py @@ -1,8 +1,15 @@ -from .attachment import AttachmentStatus, ImageType +from .attachment import ( + AttachmentStatus, + ImageType, + ReconcileAction, + ReconcileFinding, +) from .settings import RunModeEnum __all__ = [ "AttachmentStatus", "ImageType", + "ReconcileAction", + "ReconcileFinding", "RunModeEnum", ] diff --git a/src/schemas/enums/attachment.py b/src/schemas/enums/attachment.py index a3d95ef5..260edc0c 100644 --- a/src/schemas/enums/attachment.py +++ b/src/schemas/enums/attachment.py @@ -18,3 +18,32 @@ class ImageType(StrEnum): PNG = "image/png" JPEG = "image/jpeg" + + +class ReconcileFinding(StrEnum): + """Класс расхождения bucket и БД (design change `track2-reconciler`, + решения 3 и 8). Значения пишутся в журнал и отчёт сверки, в БД их нет. + """ + + # объект `/original` без строки, и ни одна строка на него не ссылается + ORPHAN_OBJECT = "orphan_object" + # строка ready без объекта + MISSING_OBJECT = "missing_object" + # строка ready, размер объекта не равен size_bytes + SIZE_MISMATCH = "size_mismatch" + # строка pending старше grace — то, что убирает уборщик + STALE_PENDING = "stale_pending" + # оригинал помечен потерянным, а объект снова есть того же размера + RESTORED_OBJECT = "restored_object" + # ключ под префиксом вложений, которого API не пишет, или ключ строки + # другого вида + UNKNOWN_OBJECT = "unknown_object" + + +class ReconcileAction(StrEnum): + """Действие сверки с `--apply` над подтверждённым расхождением.""" + + DELETED_OBJECT = "deleted_object" + MARKED_LOST = "marked_lost" + CLEARED_LOST = "cleared_lost" + REMOVED_PENDING = "removed_pending" diff --git a/src/utils/constants.py b/src/utils/constants.py index c19ae071..d55c3bea 100644 --- a/src/utils/constants.py +++ b/src/utils/constants.py @@ -79,6 +79,10 @@ OBJECT_KEY_MAX_BYTES = 1024 # ключ объекта: `<имя базы>/attachments//original` ATTACHMENT_KEY_PREFIX = "attachments" ATTACHMENT_ORIGINAL_SUFFIX = "original" +# сверка bucket и БД: сколько расхождений за проход пишется отдельными +# записями журнала; остальные — только числом в итоге (design change +# `track2-reconciler`, решение 8) +RECONCILE_FINDINGS_LOGGED_MAX = 1000 # секунды в Retry-After ответа 429, когда места загрузки процесса заняты: # за секунду реплика доводит несколько загрузок (7–8,5 по 10 MiB), а повтор # через LB уходит на следующую реплику (design change `upload-memory`, diff --git a/student-tests/conftest.py b/student-tests/conftest.py index c8b0b00f..62209dcf 100644 --- a/student-tests/conftest.py +++ b/student-tests/conftest.py @@ -150,18 +150,19 @@ def stand() -> Callable[..., str]: маркером `fault`: он только выбирает тесты (`-m fault`). """ - def call(*args: str) -> str: + def call(*args: str, stdin: bytes = b"") -> str: + # stdin — байты: тело объекта, который hook пишет мимо API + # (`put-object`, design change track2-reconciler, решение 11) result = subprocess.run( [FAULT_HOOK, *args], + input=stdin, capture_output=True, - text=True, timeout=FAULT_HOOK_TIMEOUT_S, check=False, ) - assert result.returncode == 0, ( - f"fault hook {' '.join(args)}: {result.stderr.strip()}" - ) - return result.stdout.strip() + stderr = result.stderr.decode(errors="replace").strip() + assert result.returncode == 0, f"fault hook {' '.join(args)}: {stderr}" + return result.stdout.decode().strip() return call diff --git a/student-tests/failures.compose.yml b/student-tests/failures.compose.yml index 17981dcb..3ca2f6ce 100644 --- a/student-tests/failures.compose.yml +++ b/student-tests/failures.compose.yml @@ -42,9 +42,14 @@ services: # загрузки при сроках по умолчанию (2 × 6 + 5 = 17 с): занижать сроки ради # меньшего grace значило бы обойти проверку. Без перезапуска: падение не # прячется. Значения run_failures.py передаёт тестам - # (FAULT_CLEANER_GRACE_S, FAULT_CLEANER_INTERVAL_S) + # (FAULT_CLEANER_GRACE_S, FAULT_CLEANER_INTERVAL_S). Плановая сверка + # выключена: иначе она исправляла бы расхождения, которые тест внёс и ещё + # проверяет. Сверку запускают сами тесты (hook reconcile), плановую — + # отдельный уборщик hook run-cleaner (design change track2-reconciler, + # решения 9 и 11) cleaner: restart: "no" environment: CLEANER__PENDING_GRACE_SECONDS: "20" CLEANER__INTERVAL_SECONDS: "1" + RECONCILER__INTERVAL_SECONDS: "0" diff --git a/student-tests/fault_hook.py b/student-tests/fault_hook.py index 45c2dbb2..67d86b75 100755 --- a/student-tests/fault_hook.py +++ b/student-tests/fault_hook.py @@ -51,18 +51,54 @@ сразу), а перевод в ready ждёт до 4,5 с, пока строка pending не исчезнет; undeletable — как outlive, и удаление строки падает + fail-attachments mark + пометка потерянного оригинала (UPDATE + lost_at) вложения с этим filename падает + (08006); свой триггер BEFORE UPDATE OF + lost_at, прежние режимы колонку не трогают clear-fail-attachments убрать триггеры kill-api docker kill обычного API стенда (`-api`) start-api docker start того же контейнера и ожидание healthy его healthcheck + put-object <ключ> записать объект с телом из stdin в bucket + стенда мимо API: botocore в контейнере + обычного API его ключами из окружения + контейнера. Ключ — только под + `/attachments/`, символы + [A-Za-z0-9._/-] + delete-object <ключ> удалить объект мимо шлюза S3: `weed shell + fs.rm /buckets//<ключ>`; ключ — с той + же проверкой + delete-row удалить строку вложения (неиспользуемого: + ссылку сообщения не даст удалить FK) + set-size <байт> изменить size_bytes строки + age-row <секунд> сдвинуть created_at и updated_at строки + назад на одно и то же время: CHECK и + непомеченность pending сохраняются + lost-ids `id` вложений с потерянным оригиналом + (lost_at задан) + reconcile dry-run|apply [<предел>] + разовая сверка (`docker compose run --rm + --no-deps -T cleaner reconcile [--apply] + [--max-changes N]`): записи процесса и + строка `exit_code=`; код hook — 0 + stop|start cleaner сервис уборщика стенда + run-cleaner <секунд> отдельный уборщик + `-cleaner-scheduled` с + плановой сверкой раз в 1 с + (RECONCILER__INTERVAL_SECONDS=1) на это + время, затем docker stop, его журнал и + docker rm -Bucket и имя базы для object-ids — FAULT_S3_BUCKET и FAULT_DATABASE, -их задаёт run_failures.py. Пароли и ключи не печатает: valkey-cli берёт -пароль из VALKEYCLI_AUTH контейнера, psql работает от POSTGRES_USER -контейнера, weed shell — с ключом подписи из окружения контейнера s3. -Только stdlib. Действия вложений — design change `upload-consistency`, -решение 10. +Bucket и имя базы для object-ids и ключей объектов — FAULT_S3_BUCKET и +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. """ from __future__ import annotations @@ -305,14 +341,81 @@ CREATE TRIGGER fault_wait_attachments FOR EACH STATEMENT EXECUTE FUNCTION fault_wait_attachments(:'mode', :'title'); """ +# пометка потерянного оригинала падает: отдельный триггер на колонку +# lost_at (design change track2-reconciler, решение 11) — прежние режимы и +# их функция от новой колонки не зависят +FAIL_ATTACHMENTS_MARK_SQL = """\ +CREATE OR REPLACE FUNCTION fault_fail_attachments_mark() RETURNS trigger +LANGUAGE plpgsql AS $$ +BEGIN + IF NEW.filename = TG_ARGV[0] AND OLD.lost_at IS NULL + AND NEW.lost_at IS NOT NULL THEN + RAISE EXCEPTION 'fault injected: attachment mark lost' + USING ERRCODE = '08006'; + END IF; + RETURN NEW; +END +$$; +DROP TRIGGER IF EXISTS fault_fail_attachments_mark ON attachments; +CREATE TRIGGER fault_fail_attachments_mark + BEFORE UPDATE OF lost_at ON attachments + FOR EACH ROW EXECUTE FUNCTION fault_fail_attachments_mark(:'title'); +""" CLEAR_FAIL_ATTACHMENTS_SQL = """\ DROP TRIGGER IF EXISTS fault_fail_attachments ON attachments; DROP TRIGGER IF EXISTS fault_fail_attachments_commit ON attachments; DROP TRIGGER IF EXISTS fault_wait_attachments ON attachments; +DROP TRIGGER IF EXISTS fault_fail_attachments_mark ON attachments; DROP FUNCTION IF EXISTS fault_fail_attachments(); DROP FUNCTION IF EXISTS fault_fail_attachments_commit(); DROP FUNCTION IF EXISTS fault_wait_attachments(); +DROP FUNCTION IF EXISTS fault_fail_attachments_mark(); """ +# расхождения хранилищ (design change track2-reconciler, решение 11): +# значения — переменные psql (:'title' — id, :'mode' — число) +DELETE_ROW_SQL = """\ +DELETE FROM attachments WHERE id = :'title'::uuid RETURNING id; +""" +SET_SIZE_SQL = """\ +UPDATE attachments SET size_bytes = :'mode'::integer +WHERE id = :'title'::uuid RETURNING id; +""" +AGE_ROW_SQL = """\ +UPDATE attachments +SET created_at = created_at - make_interval(secs => :'mode'::float8), + updated_at = updated_at - make_interval(secs => :'mode'::float8) +WHERE id = :'title'::uuid RETURNING id; +""" +LOST_IDS_SQL = """\ +SELECT id FROM attachments WHERE lost_at IS NOT NULL ORDER BY id; +""" +# объект мимо API: botocore образа (зависимость aiobotocore) с адресом, +# регионом и ключами из настроек процесса в контейнере API — ключи в hook +# не попадают. Ключ — argv[1], тело — stdin +PUT_OBJECT_PY = """\ +import sys +import botocore.session +from botocore.config import Config +from src.config import settings +s3 = settings.s3 +client = botocore.session.get_session().create_client( + "s3", + endpoint_url=s3.endpoint_url, + region_name=s3.region, + aws_access_key_id=s3.access_key_id.get_secret_value(), + aws_secret_access_key=s3.secret_access_key.get_secret_value(), + config=Config(s3={"addressing_style": "path"}, + retries={"total_max_attempts": 1}), +) +body = sys.stdin.buffer.read() +client.put_object(Bucket=s3.bucket, Key=sys.argv[1], Body=body) +""" +# символы ключа объекта, который hook пишет или удаляет мимо API +OBJECT_KEY_RE = re.compile(r"^[A-Za-z0-9._/-]+$") +RECONCILE_MODES = {"dry-run": (), "apply": ("--apply",)} +# плановая сверка отдельного уборщика: раз в секунду +SCHEDULED_CLEANER_ENV = "RECONCILER__INTERVAL_SECONDS=1" +SCHEDULED_CLEANER_MAX_S = 60 FAIL_ATTACHMENTS_MODES = ( "insert", "ready", @@ -578,12 +681,7 @@ def ids_with_original(tree: str) -> list[str]: def object_ids(project: str) -> str: """`id` вложений с объектом в bucket стенда, строка на `id`. Нет префикса — пусто.""" - bucket = os.environ.get("FAULT_S3_BUCKET", "") - database = os.environ.get("FAULT_DATABASE", "") - if not BUCKET_NAME_RE.fullmatch(bucket): - raise HookError(f"FAULT_S3_BUCKET is not a bucket name: {bucket!r}") - if not DB_NAME_RE.fullmatch(database): - raise HookError(f"FAULT_DATABASE is not a database name: {database!r}") + bucket, database = storage_names() tree = compose( project, "exec", @@ -600,11 +698,173 @@ def object_ids(project: str) -> str: def fail_attachments(project: str, mode: str, filename: str) -> str: + if mode == "mark": + return psql(project, FAIL_ATTACHMENTS_MARK_SQL, title=filename) if mode not in FAIL_ATTACHMENTS_MODES: - raise HookError(f"mode must be one of {FAIL_ATTACHMENTS_MODES}") + raise HookError( + f"mode must be one of {(*FAIL_ATTACHMENTS_MODES, 'mark')}", + ) return psql(project, FAIL_ATTACHMENTS_SQL, title=filename, mode=mode) +def storage_names() -> tuple[str, str]: + """Проверенные bucket и имя базы стенда (FAULT_S3_BUCKET, + FAULT_DATABASE): пути filer и ключи собираются только из них.""" + bucket = os.environ.get("FAULT_S3_BUCKET", "") + database = os.environ.get("FAULT_DATABASE", "") + if not BUCKET_NAME_RE.fullmatch(bucket): + raise HookError(f"FAULT_S3_BUCKET is not a bucket name: {bucket!r}") + if not DB_NAME_RE.fullmatch(database): + raise HookError(f"FAULT_DATABASE is not a database name: {database!r}") + return bucket, database + + +def object_key(key: str) -> str: + """Ключ объекта вложений базы стенда; иначе — отказ (код 2).""" + _, database = storage_names() + prefix = f"{database}/{ATTACHMENT_KEY_PREFIX}/" + if ( + not key.startswith(prefix) + or len(key) == len(prefix) + or not OBJECT_KEY_RE.fullmatch(key) + or ".." in key.split("/") + ): + raise HookError(f"object key must be under {prefix}: {key!r}") + return key + + +def put_object(project: str, key: str) -> str: + """Объект с телом из stdin мимо API — процессом в контейнере API.""" + result = subprocess.run( + [ + "docker", + "exec", + "-i", + api_container(project), + "python", + "-c", + PUT_OBJECT_PY, + object_key(key), + ], + input=sys.stdin.buffer.read(), + capture_output=True, + check=False, + ) + if result.returncode != 0: + sys.stderr.write(result.stderr.decode(errors="replace")) + raise SystemExit(result.returncode) + return "" + + +def delete_object(project: str, key: str) -> str: + """Удалить объект в filer, мимо шлюза S3. `weed shell` выходит с кодом + 0 и при ошибке команды: ошибка — по её выводу.""" + bucket, _ = storage_names() + output = compose( + project, + "exec", + "-T", + "s3", + "sh", + "-c", + "exec weed shell -master=127.0.0.1:9333 2>&1", + stdin=f"fs.rm /buckets/{bucket}/{object_key(key)}\n", + ) + failed = [ + line + for line in output.splitlines() + if "error" in line.lower() or "not found" in line.lower() + ] + if failed: + raise HookError(f"fs.rm failed: {failed[0]}") + return "" + + +def row_change(project: str, sql: str, attachment_id: str, value: str) -> str: + """Изменение одной строки вложения; строки нет — отказ (код 2).""" + changed = psql( + project, + sql, + title=str(uuid.UUID(attachment_id)), + mode=value, + ) + if not changed: + raise HookError(f"attachment {attachment_id} not found") + return "" + + +def reconcile(project: str, mode: str, args: list[str]) -> str: + """Разовая сверка в одноразовом контейнере уборщика стенда: записи + процесса и строка `exit_code=`.""" + if mode not in RECONCILE_MODES or len(args) > 1: + raise HookError("reconcile dry-run|apply []") + limit = ("--max-changes", str(int(args[0]))) if args else () + result = compose_run( + project, + "run", + "--rm", + "--no-deps", + "-T", + "cleaner", + "reconcile", + *RECONCILE_MODES[mode], + *limit, + ) + lines = [*result.stdout.splitlines(), *result.stderr.splitlines()] + return "\n".join([*lines, f"exit_code={result.returncode}"]) + + +def cleaner_action(project: str, action: str) -> str: + """`stop` или `start` сервиса уборщика стенда — тот же контейнер. + + `docker compose start` проверял бы зависимости сервиса, а одноразовый + `migrate` стенд запускал через `run --rm`, и контейнера его нет + («missing dependency migrate»): поэтому `docker start` контейнера. + """ + if action == "stop": + return compose(project, "stop", "cleaner") + container = compose(project, "ps", "-a", "-q", "cleaner") + if not container: + raise HookError("cleaner container of the stand not found") + docker("start", container) + return "" + + +def run_cleaner(project: str, seconds: str) -> str: + """Отдельный уборщик с плановой сверкой раз в 1 с на `seconds`, затем + остановка; его журнал.""" + duration = float(seconds) + if not 0 < duration <= SCHEDULED_CLEANER_MAX_S: + raise HookError(f"seconds must be in (0, {SCHEDULED_CLEANER_MAX_S}]") + name = f"{project}-cleaner-scheduled" + subprocess.run( + ["docker", "rm", "-f", name], + capture_output=True, + check=False, + ) + compose( + project, + "run", + "-d", + "--no-deps", + "--name", + name, + "-e", + SCHEDULED_CLEANER_ENV, + "cleaner", + ) + try: + time.sleep(duration) + docker("stop", name) + return docker("logs", name) + finally: + subprocess.run( + ["docker", "rm", "-f", name], + capture_output=True, + check=False, + ) + + def api_container(project: str) -> str: # обычный API стенда отказов: имя задаёт run_failures.py return f"{project}-api" @@ -643,6 +903,8 @@ def docker(*args: str) -> str: 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", "pause") and len(args) == 1: return compose(project, action, service(args[0])) if action == "start" and len(args) == 1: @@ -687,6 +949,27 @@ def run(project: str, action: str, args: list[str]) -> str: return docker("kill", api_container(project)) and "" if action == "start-api" and not args: return start_api(project) + if action == "put-object" and len(args) == 1: + return put_object(project, args[0]) + if action == "delete-object" and len(args) == 1: + return delete_object(project, args[0]) + if action == "delete-row" and len(args) == 1: + return row_change(project, DELETE_ROW_SQL, args[0], "") + if action == "set-size" and len(args) == 2: + return row_change(project, SET_SIZE_SQL, args[0], str(int(args[1]))) + if action == "age-row" and len(args) == 2: + return row_change( + project, + AGE_ROW_SQL, + args[0], + str(float(args[1])), + ) + if action == "lost-ids" and not args: + return psql(project, LOST_IDS_SQL) + if action == "reconcile" and args: + return reconcile(project, args[0], args[1:]) + if action == "run-cleaner" and len(args) == 1: + return run_cleaner(project, args[0]) raise HookError(f"unknown action or arguments: {action} {args}") diff --git a/student-tests/run_failures.py b/student-tests/run_failures.py index ed3de557..80d3580c 100644 --- a/student-tests/run_failures.py +++ b/student-tests/run_failures.py @@ -6,7 +6,9 @@ S3 со своими volumes, порты хранилищ не публикую - собирает образ из рабочего дерева, применяет миграции и bootstrap S3; - запускает уборщика незавершённых загрузок с grace 20 с и интервалом 1 с (`failures.compose.yml`; design change `upload-consistency`, - решение 10) и передаёт оба значения тестам; + решение 10) без плановой сверки (design change `track2-reconciler`, + решение 9) и передаёт значения тестам; уборщика с плановой сверкой + `<проект>-cleaner-scheduled` запускает hook и убирает этот скрипт; - запускает три контейнера API: обычный (с `MAX_UPLOAD_BYTES=1` и `MAX_IMAGE_PIXELS=1` в окружении — лимиты вложений от них не зависят), «тесный» (сроки сессии и ключа идемпотентности 2 с, пул из одного @@ -167,6 +169,9 @@ def cleaner_timings(project: str) -> dict[str, str]: return { "FAULT_CLEANER_GRACE_S": environment["CLEANER__PENDING_GRACE_SECONDS"], "FAULT_CLEANER_INTERVAL_S": environment["CLEANER__INTERVAL_SECONDS"], + "FAULT_RECONCILER_INTERVAL_S": environment[ + "RECONCILER__INTERVAL_SECONDS" + ], } @@ -303,7 +308,10 @@ def main() -> int: default_name = f"{project}-api" tight_name = f"{project}-api-tight" uploads_name = f"{project}-api-uploads" - containers = [default_name, tight_name, uploads_name] + # уборщик с плановой сверкой — его запускает hook run-cleaner (design + # change track2-reconciler, решение 11); убирается вместе с API + scheduled_name = f"{project}-cleaner-scheduled" + containers = [default_name, tight_name, uploads_name, scheduled_name] say(f"project={project} (working stand: {working})") if not cleanup(project, containers): @@ -333,7 +341,9 @@ def main() -> int: timings = cleaner_timings(project) say( f"start cleaner: grace {timings['FAULT_CLEANER_GRACE_S']} s, " - f"interval {timings['FAULT_CLEANER_INTERVAL_S']} s", + f"interval {timings['FAULT_CLEANER_INTERVAL_S']} s, " + "reconcile interval " + f"{timings['FAULT_RECONCILER_INTERVAL_S']} s (0 — off)", ) dc(project, "up", "-d", "--no-deps", "cleaner") say("start api containers") diff --git a/student-tests/test_failures.py b/student-tests/test_failures.py index cf8baffa..dcd7ae96 100644 --- a/student-tests/test_failures.py +++ b/student-tests/test_failures.py @@ -10,17 +10,21 @@ Valkey и S3, уборщик незавершённых загрузок (grace `upload-memory`). На хранилища и API тесты действуют только через фикстуру `stand` (hook `student-tests/fault_hook.py`) и всегда возвращают их в рабочее состояние. Решение 4 design change `failure-checks`, решение 10 -design change `upload-consistency`. +design change `upload-consistency`, решение 11 design change +`track2-reconciler` (сверка bucket и БД — в конце модуля: её тесты +оставляют помеченные потерянными вложения, прежние тесты таких не ждут). """ import hashlib +import json import os import statistics import threading import time import uuid -from collections.abc import Callable, Iterator +from collections.abc import Callable, Collection, Iterator from contextlib import contextmanager +from dataclasses import dataclass from typing import Any import httpx @@ -1478,3 +1482,545 @@ def test_slow_body( data, "image/png", ) + + +# --------------------------------------------------------------------------- +# Сверка bucket и БД (change track2-reconciler, design, решение 11). Hook +# вносит расхождения с обеих сторон и запускает разовую сверку; плановая +# сверка уборщика стенда выключена. Записи сверки фильтруются по своим id и +# ключам: остатки прежних тестов (строки pending) могут попасть в отчёт, и +# код выхода сверяется с записями того же прохода, а не с числом. Объекты +# состарить нельзя (LastModified ставит S3): тесты объектов без строки ждут +# G + 1 с, строки состаривает hook (age-row) +# --------------------------------------------------------------------------- + +# имя базы стенда: ключ объекта вложения — `<база>/attachments//original` +FAULT_DATABASE = os.environ.get("FAULT_DATABASE", "messenger") +# на сколько hook состаривает строку: заведомо больше grace +AGED_S = CLEANER_GRACE_S + 60 +# объекты без строки старше grace: grace и секунда точности LastModified +OBJECT_AGE_WAIT_S = CLEANER_GRACE_S + 1 +FOUND = "Found storage discrepancy" +FIXED = "Fixed storage discrepancy" +FINISHED = "Finished reconcile pass" +LIMIT_EXCEEDED = "Reconcile changes exceed limit" +# сверка под нагрузкой: потоки загрузок, период сверки, пауза потока +LOAD_THREADS = 4 +LOAD_EXTRA_S = 15 +LOAD_RECONCILE_PERIOD_S = 3 +LOAD_PAUSE_S = 0.1 +# плановая сверка отдельного уборщика: столько секунд он работает +SCHEDULED_RUN_S = 6 + + +@dataclass(frozen=True) +class Reconcile: + """Один разовый проход сверки: записи журнала процесса и код выхода.""" + + records: list[dict[str, Any]] + exit_code: int + + def events(self, event: str) -> list[dict[str, Any]]: + return [item for item in self.records if item.get("event") == event] + + @property + def finished(self) -> dict[str, Any]: + (record,) = self.events(FINISHED) + return record + + def about( + self, + event: str, + *, + ids: Collection[str] = (), + keys: Collection[str] = (), + ) -> list[dict[str, Any]]: + """Записи `event` о своих `id` вложений и ключах объектов.""" + return [ + item + for item in self.events(event) + if item.get("attachment_id") in ids + or item.get("object_key") in keys + ] + + def kinds( + self, + event: str, + *, + ids: Collection[str] = (), + keys: Collection[str] = (), + ) -> dict[str, str]: + """`id` или ключ → класс расхождения в записях `event`.""" + found: dict[str, str] = {} + for item in self.about(event, ids=ids, keys=keys): + name = ( + item["attachment_id"] + if item.get("attachment_id") in ids + else item["object_key"] + ) + found[name] = item["kind"] + return found + + def assert_code_matches(self) -> None: + """Код выхода соответствует записям прохода: 3 — остались + расхождения (запись `Found`) или отказ по пределу, иначе 0.""" + finished = self.finished + assert finished["interrupted_by"] is None, finished + expected = 3 if self.events(FOUND) or finished["refused"] else 0 + assert self.exit_code == expected, (self.exit_code, finished) + + +def run_reconcile( + stand: Stand, + mode: str, + limit: int | None = None, +) -> Reconcile: + """Разовая сверка hook: `dry-run` или `apply`, с пределом изменений.""" + args = [mode] if limit is None else [mode, str(limit)] + lines = stand("reconcile", *args).splitlines() + assert lines and lines[-1].startswith("exit_code="), lines[-5:] + records = [] + for line in lines[:-1]: + if line.startswith("{"): + records.append(json.loads(line)) + return Reconcile(records=records, exit_code=int(lines[-1].split("=")[1])) + + +def object_key(attachment_id: str) -> str: + return f"{FAULT_DATABASE}/attachments/{attachment_id}/original" + + +def lost_ids(stand: Stand) -> set[str]: + return set(stand("lost-ids").splitlines()) + + +def put_object(stand: Stand, key: str, data: bytes) -> None: + stand("put-object", key, stdin=data) + + +def lose_original(stand: Stand, attachment: dict[str, Any]) -> None: + """Готовое вложение старше grace без объекта: строка состарена, объект + удалён мимо API.""" + stand("age-row", attachment["id"], str(AGED_S)) + stand("delete-object", object_key(attachment["id"])) + + +def assert_lost_content( + api: Api, + actor: Actor, + attachment: dict[str, Any], + *, + aged: bool = False, +) -> None: + """Помеченное вложение: байты — 404, метаданные — как при загрузке. + + `aged` — строку состарил hook (`age-row`): её `created_at` и + `updated_at` сдвинуты им, а не сверкой, и сравниваются остальные поля. + """ + assert_error(api.attachment_content(actor, attachment["id"]), 404) + meta = assert_ok( + api.attachment_meta(actor, attachment["id"]), + 200, + "Attachment", + ) + if aged: + times = ("created_at", "updated_at") + meta = {key: value for key, value in meta.items() if key not in times} + attachment = { + key: value for key, value in attachment.items() if key not in times + } + assert meta == attachment + + +@pytest.mark.spec("storage-consistency", "Расхождения с обеих сторон найдены") +@pytest.mark.spec("storage-consistency", "Исправление расхождений") +@pytest.mark.spec("storage-consistency", "Повторная сверка") +@pytest.mark.spec("attachments", "Потерянный оригинал") +def test_reconcile_finds_and_fixes( + api: Api, + stand: Stand, + alice: Actor, + chat: dict[str, Any], +) -> None: + data = images.sample_png() + # уборщик стенда стоит: зависшую загрузку P должна убрать сверка + with outage(stand, "stop", "cleaner"): + a, b, c = (api.upload(alice, chat["id"], data) for _ in range(3)) + api.send_message(alice, chat["id"], "", attachment_ids=[a["id"]]) + orphan = str(uuid.uuid4()) + keys = {"o": object_key(orphan), "b": object_key(b["id"])} + put_object(stand, keys["o"], data) + stand("delete-object", object_key(a["id"])) + stand("delete-row", b["id"]) + stand("set-size", c["id"], str(len(data) + 1)) + filename = fault_filename() + before = attachment_rows(stand) + stand("fail-attachments", "commit", filename) + try: + resp = upload_raw(api, alice, chat, data, filename=filename) + assert_error(resp, 503) + finally: + stand("clear-fail-attachments") + (pending,) = new_ids(before, attachment_rows(stand)) + assert pending in stored_ids(stand) + # последний объект записан только что: после G + 1 всё старше grace + time.sleep(OBJECT_AGE_WAIT_S) + ids = {a["id"], c["id"], pending} + snapshot = (attachment_rows(stand), stored_ids(stand), lost_ids(stand)) + + dry = run_reconcile(stand, "dry-run") + assert dry.kinds(FOUND, ids=ids, keys=keys.values()) == { + keys["o"]: "orphan_object", + keys["b"]: "orphan_object", + a["id"]: "missing_object", + c["id"]: "size_mismatch", + pending: "stale_pending", + } + for record in dry.about(FOUND, ids=ids, keys=keys.values()): + assert record["age_seconds"] >= CLEANER_GRACE_S, record + assert dry.exit_code == 3 + # dry-run ничего не меняет: ни строк, ни объектов, ни пометок + after = (attachment_rows(stand), stored_ids(stand), lost_ids(stand)) + assert after == snapshot + assert_error(api.attachment_content(alice, a["id"]), 500) + assert_ok(api.attachment_meta(alice, a["id"]), 200, "Attachment") + + fixed = run_reconcile(stand, "apply") + actions = { + record.get("attachment_id") + if record.get("attachment_id") in ids + else record["object_key"]: record["action"] + for record in fixed.about(FIXED, ids=ids, keys=keys.values()) + } + assert actions == { + keys["o"]: "deleted_object", + keys["b"]: "deleted_object", + a["id"]: "marked_lost", + c["id"]: "marked_lost", + pending: "removed_pending", + } + assert not fixed.about(FOUND, ids=ids, keys=keys.values()) + fixed.assert_code_matches() + rows, stored = attachment_rows(stand), stored_ids(stand) + assert not {orphan, b["id"], pending} & stored + assert pending not in rows + assert {a["id"], c["id"]} <= lost_ids(stand) + assert rows[a["id"]] == rows[c["id"]] == "ready" + assert_lost_content(api, alice, a) + # у C размер в метаданных изменил hook (set-size), а не сверка + assert_lost_content(api, alice, c | {"size_bytes": len(data) + 1}) + + again = run_reconcile(stand, "dry-run") + assert not again.about(FOUND, ids=ids, keys=keys.values()) + assert not again.about(FIXED, ids=ids, keys=keys.values()) + again.assert_code_matches() + + +@pytest.mark.spec("storage-consistency", "Свежие не тронуты") +@pytest.mark.spec("storage-consistency", "Используемое вложение не удаляется") +@pytest.mark.spec("storage-consistency", "Чужой объект не удаляется") +def test_reconcile_keeps_fresh_used_and_unknown( + api: Api, + stand: Stand, + alice: Actor, + chat: dict[str, Any], +) -> None: + data = images.sample_png() + used = api.upload(alice, chat["id"], data) + message = api.send_message( + alice, + chat["id"], + "", + attachment_ids=[used["id"]], + ) + lose_original(stand, used) + # ключ, которого API не пишет: под префиксом вложений, но не /original + unknown = f"{FAULT_DATABASE}/attachments/x-{uuid.uuid4()}" + put_object(stand, unknown, data) + time.sleep(OBJECT_AGE_WAIT_S) + # свежие: готовое вложение без объекта и объект без строки + fresh = api.upload(alice, chat["id"], data) + stand("delete-object", object_key(fresh["id"])) + fresh_object = str(uuid.uuid4()) + put_object(stand, object_key(fresh_object), data) + ready_before = ready_ids(attachment_rows(stand)) + try: + run = run_reconcile(stand, "apply") + keys = {unknown, object_key(fresh_object)} + ids = {used["id"], fresh["id"], fresh_object} + assert run.kinds(FOUND, ids=ids, keys=keys) == { + unknown: "unknown_object", + } + assert run.kinds(FIXED, ids=ids, keys=keys) == { + used["id"]: "missing_object", + } + assert run.exit_code == 3 + assert run.finished["fresh_objects"] >= 1, run.finished + assert run.finished["fresh_rows"] >= 1, run.finished + # свежий объект на месте, свежее вложение не помечено + assert fresh_object in stored_ids(stand) + lost = lost_ids(stand) + assert fresh["id"] not in lost + # используемое: помечено, метаданные и ссылка в истории на месте + assert used["id"] in lost + assert_lost_content(api, alice, used, aged=True) + history = api.all_messages(alice, chat["id"]) + (sent,) = (item for item in history if item["id"] == message["id"]) + assert sent["attachment_ids"] == [used["id"]] + assert ready_before <= ready_ids(attachment_rows(stand)) + # чужой объект не тронут: следующий проход снова его видит + again = run_reconcile(stand, "dry-run") + assert again.kinds(FOUND, keys={unknown}) == { + unknown: "unknown_object", + } + finally: + # стенд — без чужого и лишнего объекта, у свежего — его байты + stand("delete-object", unknown) + stand("delete-object", object_key(fresh_object)) + put_object(stand, object_key(fresh["id"]), data) + + +@pytest.mark.spec("storage-consistency", "Оригинал вернулся") +def test_reconcile_restored_original( + api: Api, + stand: Stand, + alice: Actor, + chat: dict[str, Any], +) -> None: + data = images.png_noise(64, 48, seed=7) + restored = api.upload(alice, chat["id"], data) + lose_original(stand, restored) + marked = run_reconcile(stand, "apply") + assert marked.kinds(FIXED, ids={restored["id"]}) == { + restored["id"]: "missing_object", + } + assert restored["id"] in lost_ids(stand) + assert_lost_content(api, alice, restored, aged=True) + # те же байты снова под ключом вложения + put_object(stand, object_key(restored["id"]), data) + cleared = run_reconcile(stand, "apply") + (record,) = cleared.about(FIXED, ids={restored["id"]}) + assert (record["kind"], record["action"]) == ( + "restored_object", + "cleared_lost", + ) + assert restored["id"] not in lost_ids(stand) + assert_content( + api.attachment_content(alice, restored["id"]), + data, + "image/png", + ) + again = run_reconcile(stand, "dry-run") + assert not again.about(FOUND, ids={restored["id"]}) + + +@pytest.mark.spec("storage-consistency", "Предел изменений") +def test_reconcile_change_limit( + api: Api, + stand: Stand, + alice: Actor, + chat: dict[str, Any], +) -> None: + limit = 2 + batch = [ + api.upload(alice, chat["id"], images.sample_png()) for _ in range(3) + ] + ids = {item["id"] for item in batch} + for item in batch: + lose_original(stand, item) + refused = run_reconcile(stand, "apply", limit) + assert refused.exit_code == 3 + (error,) = refused.events(LIMIT_EXCEEDED) + assert error["level"] == "error" + assert error["changes"] >= len(batch), error + assert error["max_changes"] == limit + assert refused.finished["refused"] is True + assert refused.finished["level"] == "warning" + assert not refused.about(FIXED, ids=ids) + assert not ids & lost_ids(stand) + assert all( + record["kind"] == "missing_object" + for record in refused.about(FOUND, ids=ids) + ) + # предел не меньше числа изменений: исправлено всё + applied = run_reconcile(stand, "apply", 100) + assert set(applied.kinds(FIXED, ids=ids)) == ids + assert ids <= lost_ids(stand) + + +@pytest.mark.spec("storage-consistency", "S3 недоступен во время сверки") +def test_reconcile_object_storage_stopped( + api: Api, + stand: Stand, + alice: Actor, + chat: dict[str, Any], +) -> None: + missing = api.upload(alice, chat["id"], images.sample_png()) + lose_original(stand, missing) + with outage(stand, "stop", "s3"): + interrupted = run_reconcile(stand, "apply") + assert interrupted.exit_code == 1 + assert interrupted.finished["interrupted_by"] == "object_storage" + assert not interrupted.events(FIXED) + assert missing["id"] not in lost_ids(stand) + applied = run_reconcile(stand, "apply") + assert applied.kinds(FIXED, ids={missing["id"]}) == { + missing["id"]: "missing_object", + } + assert missing["id"] in lost_ids(stand) + + +@pytest.mark.spec( + "storage-consistency", + "Прерванная сверка доводится повтором", +) +def test_reconcile_interrupted_by_database( + api: Api, + stand: Stand, + alice: Actor, + chat: dict[str, Any], +) -> None: + filename = fault_filename() + failing = api.upload( + alice, + chat["id"], + images.sample_png(), + filename=filename, + ) + other = api.upload(alice, chat["id"], images.sample_png()) + ids = {failing["id"], other["id"]} + for item in (failing, other): + lose_original(stand, item) + stand("fail-attachments", "mark", filename) + try: + interrupted = run_reconcile(stand, "apply") + assert interrupted.exit_code == 1 + assert interrupted.finished["interrupted_by"] == "database" + assert failing["id"] not in lost_ids(stand) + finally: + stand("clear-fail-attachments") + applied = run_reconcile(stand, "apply") + assert ids <= lost_ids(stand) + assert not applied.about(FOUND, ids=ids) + again = run_reconcile(stand, "dry-run") + assert not again.about(FOUND, ids=ids) + + +@pytest.mark.spec("storage-consistency", "Сверка под нагрузкой") +def test_reconcile_under_load( + api: Api, + stand: Stand, + alice: Actor, + bob: Actor, + chat: dict[str, Any], +) -> None: + """Загрузки и отправки дольше grace, сверка с `--apply` раз в 3 с: + внесённое исправлено, ни одно подтверждённое вложение не потеряно.""" + data = images.sample_png() + orphans = {str(uuid.uuid4()) for _ in range(2)} + for item in orphans: + put_object(stand, object_key(item), data) + injected = [api.upload(alice, chat["id"], data) for _ in range(2)] + for item in injected: + lose_original(stand, item) + lost_before = lost_ids(stand) + deadline = time.monotonic() + CLEANER_GRACE_S + LOAD_EXTRA_S + lock = threading.Lock() + uploads: dict[str, str] = {} + messages: dict[str, list[str]] = {} + failures: list[str] = [] + passes: list[Reconcile] = [] + + def load(worker: int) -> None: + actor = alice if worker % 2 == 0 else bob + with Api( + str(api.client.base_url), + timeout=THREAD_CLIENT_TIMEOUT_S, + ) as client: + number = 0 + while time.monotonic() < deadline: + number += 1 + body = images.png_noise(200, 170, seed=worker * 10**6 + number) + resp = client.post_attachment(actor, chat["id"], body) + if resp.status_code != 201: + with lock: + failures.append(f"upload {resp.status_code}") + continue + attachment = assert_ok(resp, 201, "Attachment") + # загрузка подтверждена: она обязана скачиваться + with lock: + uploads[attachment["id"]] = hashlib.sha256( + body, + ).hexdigest() + message = client.send_message( + actor, + chat["id"], + "", + attachment_ids=[attachment["id"]], + ) + with lock: + messages[message["id"]] = [attachment["id"]] + time.sleep(LOAD_PAUSE_S) + + def reconcile() -> None: + while time.monotonic() < deadline: + started = time.monotonic() + passes.append(run_reconcile(stand, "apply")) + sleep_until(started + LOAD_RECONCILE_PERIOD_S) + + def guarded(target: Callable[..., None], *args: Any) -> None: + # исключение потока — в список, а не молча в stderr + try: + target(*args) + except Exception as e: + with lock: + failures.append(repr(e)) + + threads = [ + threading.Thread(target=guarded, args=(load, worker)) + for worker in range(LOAD_THREADS) + ] + threads.append(threading.Thread(target=guarded, args=(reconcile,))) + for thread in threads: + thread.start() + for thread in threads: + thread.join() + assert not failures, failures[:5] + assert uploads, "no uploads under load" + assert len(passes) >= 3, len(passes) + assert all(item.exit_code in (0, 3) for item in passes), [ + item.exit_code for item in passes + ] + # внесённые исправлены: объекты без строки удалены, потери помечены + assert not orphans & stored_ids(stand) + assert lost_ids(stand) - lost_before == {item["id"] for item in injected} + # ни одно подтверждённое вложение не потеряно + for attachment_id, digest in uploads.items(): + resp = api.attachment_content(alice, attachment_id) + assert resp.status_code == 200, (attachment_id, resp.status_code) + assert hashlib.sha256(resp.content).hexdigest() == digest + history = { + item["id"]: item["attachment_ids"] + for item in api.all_messages(alice, chat["id"]) + } + for message_id, attachment_ids in messages.items(): + assert history[message_id] == attachment_ids + + +@pytest.mark.spec("storage-consistency", "Плановая сверка без команды") +def test_scheduled_reconcile( + api: Api, + stand: Stand, + alice: Actor, + chat: dict[str, Any], +) -> None: + scheduled = api.upload(alice, chat["id"], images.sample_png()) + lose_original(stand, scheduled) + log = stand("run-cleaner", str(SCHEDULED_RUN_S)) + records = [ + json.loads(line) for line in log.splitlines() if line.startswith("{") + ] + passes = [item for item in records if item.get("event") == FINISHED] + assert passes, log[-2000:] + assert any(item["apply"] for item in passes), passes + assert scheduled["id"] in lost_ids(stand)