feat: reconcile the bucket against attachment rows in the cleaner

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-10-22 19:32:08 +03:00
co-authored by Claude Opus 5.5
parent c13df14f36
commit c1648d9b83
53 changed files with 4207 additions and 205 deletions
+14 -1
View File
@@ -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.
+12
View File
@@ -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, как
миграции, только расширяет: новые пользователи и политики не отбирают
+28 -5
View File
@@ -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` на
`<bucket>/*` и `s3:ListBucket` на `<bucket>` с условием `StringLike
s3:prefix <база>/attachments/*` (SeaweedFS 4.48 условие соблюдает:
весь bucket, `test_<db>/`, `.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
+10
View File
@@ -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).
+14
View File
@@ -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 —
обход каталогов, а не порядок байтов: сверка не сливает
отсортированные потоки, а собирает множество ключей. Префикс —
только `<namespace>/attachments/` (repo): политика уборщика другие
префиксы запрещает;
- адресация `path`: `bucket.s3` Docker DNS не разрешает;
простаивающее соединение aiohttp закрывает через
`S3_KEEPALIVE_TIMEOUT_SECONDS` (15 с), раньше шлюза (120 с);
+24
View File
@@ -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, подписей в записях уборщика нет.
## Где логировать
+11
View File
@@ -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` его не пересоздаст: повтор миграции
+16 -2
View File
@@ -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` собирает `<namespace>/attachments/<id>/
@@ -80,7 +90,11 @@ paths:
`put_original`, `open_original` (контекст объекта),
`delete_original` (отсутствие объекта — не ошибка; компенсация
загрузки и уборщик). Ключ хранится в
строке и при чтении берётся из неё, не вычисляется заново;
строке и при чтении берётся из неё, не вычисляется заново. Для сверки:
`originals_prefix` (`<namespace>/attachments/`), `parse_original_key`
(`UUID` ключа `<id>/original` в записи сервера, иначе `None`),
`list_originals` (страница списка), `probe_originals` (список с
`MaxKeys=1`: bucket на месте и список разрешён), `head_original`;
- `message.py`: `MESSAGE_COLUMNS` с коррелированным подзапросом
`ARRAY(SELECT attachment_id … ORDER BY position)` — одно выражение на
страницу и на сохранённый результат ключа; план — `SubPlan` по
+18
View File
@@ -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).
+35 -1
View File
@@ -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` до захвата ключа) → хэш → ключ → сообщение →
+16 -1
View File
@@ -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`; шапка шаблона просит сопоставить их
+50 -2
View File
@@ -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`, ошибка — по
выводу), оба — только под `<FAULT_DATABASE>/attachments/` и символы
`[A-Za-z0-9._/-]`; `delete-row`, `set-size`, `age-row` (сдвиг
`created_at` и `updated_at` вместе — CHECK и непомеченность `pending`
сохраняются), `lost-ids`; `fail-attachments mark <filename>` — свой
триггер `BEFORE UPDATE OF lost_at` (08006), `clear-fail-attachments`
снимает и его; `reconcile dry-run|apply [<предел>]` — `docker compose
run --rm --no-deps -T cleaner reconcile …`, записи процесса и строка
`exit_code=<n>`, код 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` после каждого прогона и ненулевой код при признаках
+32 -2
View File
@@ -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:<id>` сразу после 201 (`EXISTS`, TTL ≤ `[cache] chat_ttl_seconds` из реплики, поля значения), `DEL`, через 11 с снимок `seq_scan + idx_scan` таблицы `chats` и `keyspace_hits` / `keyspace_misses`, 50 чтений через LB, через 11 с второй снимок; TTL до и после ещё 10 чтений; число ключей рабочей и тестовой (`test_<db>`) базы. Код 0 — чтений `chats` ≤ 1, hits ≥ +49, промахов ≤ 1, ответы равны ответу на создание, TTL не продлевается, ≥ 2 `X-Instance-Id`. Для «Временной базы» перед ней — `make test_isolated`: без ключей тестовой базы строка `PASS` заканчивается «temporary database: not checked», с `--require-test-keys` — код 1 (доказательство сценария снимается с флагом). На стенде в это время ничего другого не должно идти. Вывод — `evidence/cache/hits.md` |
| `auth-storage` | только стенд с LB: сценарии `users` «Хэш в БД» и `sessions` «Токена нет в хранилище». Пароль P (с `:` и кириллицей) и токен T — только в памяти; через psql — префикс `$argon2id$…` до соли и длина у двух пользователей с одним P, неравенство хэшей, строка `sessions` с `token_hash` = SHA-256(T) (32 байта); `pg_dump --data-only` в память — нет ли T (текстом и в hex) и P. Код 0 — всё так. Вывод — `evidence/auth/passwords-and-tokens.md` |
| `s3-check` | стенд compose (`make s3_check`), без приложения: спек `object-storage` «Проверка приватности вне API». `docker compose run --rm --no-deps s3-bootstrap check` — права ключа API (PUT/GET/HEAD объекта, 404 отсутствующего; 403 на список, создание и удаление bucket, политику и ACL bucket, публичный ACL объекта), права ключа уборщика (GET/HEAD/DELETE своего проверочного объекта, повторный DELETE и DELETE отсутствующего — 204; 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/<id>/original` без `filename`; `weed shell fs.ls -l` — объект в bucket и его размер; анонимный GET ключа с `127.0.0.1:S3_OUT_PORT` — 403; скачивание участником — тот же SHA-256; `docker diff` каждой реплики — ни одного файла оригинала. Код 1 с названной проверкой, без LB — код 2. Вывод — `evidence/attachments/storage.md` |
| `upload-consistency` | только стенд с LB: спеки `attachments` «Порядок записи» и `storage-consistency` (design change `upload-consistency`, решение 11). Синтетические Алиса, Боб и чат; готовое вложение R. Шаги: (1) `docker compose pause s3` → загрузка через LB — 503 за ~5 с → `unpause` в `finally`; новая строка `pending` по psql (`id`, статус, возраст, ключ); (2) триггер «фиксация `ready` падает» (SQLSTATE 08006) на рабочей базе только для уникального `filename` прогона → загрузка 503 → строка `pending`, объекта уже нет (компенсация), триггер снят (`finally`, и остаток прошлого прогона — в начале); (3) метаданные, байты и сообщение со ссылкой на обе строки — 404; (4) после grace прогона 30 с — `docker compose run --rm --no-deps -e CLEANER__PENDING_GRACE_SECONDS=30 cleaner --once`, его JSON-вывод; (5) psql и `weed shell fs.tree` (файлы `original`, а не каталоги) — ни строк, ни объектов обеих загрузок, объектов без строки под префиксом рабочей базы нет; R скачивается с тем же SHA-256. Таблица «проверка → ожидаемо → получено» без токенов и секретов; код 1 при расхождении, без LB — код 2. ~45 с. Вывод — `evidence/attachments/consistency.md` |
| `reconcile-cycle` | только стенд с LB: спеки `storage-consistency` (сверка bucket и БД) и `attachments` «Потерянный оригинал» (design change `track2-reconciler`, решение 12). (1) исходный dry-run с grace по умолчанию — расхождений нет, иначе код 2; (2) синтетические Алиса, Боб, чат, вложения A (в сообщении), B, C; (3) объект O без строки и чужой ключ X — `docker exec` реплики (botocore образа её ключами), объект A удалён (`weed shell fs.rm`), строка B удалена и размер C изменён (psql), P — триггер COMMIT на уникальный `filename` (503, строка `pending` и объект); (4) после grace 30 с dry-run: таблица «класс → действие → ключ → `id` → возраст», снимки строк, объектов и пометок до и после совпали; (5) байты A — 500; (6) свежий F, `--apply`: O, B удалены, A, C помечены, P убрана, F не тронут, байты A — 404, метаданные A — 200 и равны ответу загрузки, история отдаёт A; (7) повтор — только чужой X, код 3; оператор удаляет X — код 0; после grace F удалён; (8) A возвращён теми же байтами — «оригинал вернулся», байты 200 с тем же SHA-256, итоговый dry-run — код 0. Таблица «проверка → ожидаемо → получено» без токенов; код 1 при расхождении, без LB — код 2. ~2 мин. Вывод — `evidence/reconcile/cycle.md` |
| `reconcile-stress [--seconds S] [--clients N]` | только стенд с LB: «Сверка под нагрузкой». Предусловие — dry-run с grace 20 с без расхождений (иначе код 2); два объекта без строки и два вложения без объекта; N клиентов (4) S секунд (40, больше grace) загружают PNG ~100 KiB из шума и отправляют сообщения, поток сверки — `--apply` с grace 20 с раз в ~3 с, затем ещё один проход. Итог: загрузки по кодам, сообщения, коды проходов, исправления по классам; проверки — внесённые исправлены (объекты удалены, новые пометки — ровно внесённые), каждое 201 скачивается с тем же SHA-256, каждое сообщение отдаёт своё вложение, ни одного прерванного прохода, повтор dry-run — код 0. Проверка корректности, не замер. Вывод — `evidence/reconcile/stress.md` |
| `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`: разбор драйвера их не знает и
не меняется.
- **Пустой каталог `<id>/` в bucket после удаления объекта** SeaweedFS
убирает лишь через ~2 мин: `fs.ls` его показывает, список S3 — нет.
Объекты считать по файлам `original` (`fs.tree`), а не по каталогам.
@@ -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":
+33 -13
View File
@@ -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 <LB> attachment-storage` | схема таблиц вложений, вид `object_key`, объект в bucket, анонимный GET — 403, `docker diff` реплик; доказательство исключения «Байты не в БД и не на диске API» |
| `driver.py --port <LB> 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 <LB> reconcile-cycle` | сверка на рабочем стенде (~2 мин): исходный dry-run без расхождений (иначе код 2), расхождения с обеих сторон, dry-run без изменений, 500 → `--apply` → 404 и 200, повтор, удаление чужого объекта, свежий объект после grace, возврат оригинала; `evidence/reconcile/cycle.md` |
| `driver.py --port <LB> 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/<domain>.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/<domain>.py # атомарный доступ к хранилищу, модульные функции
repos/idempotency.py # ключ идемпотентности: захват ON CONFLICT DO UPDATE WHERE просрочен, чтение сохранённого результата
repos/chat_cache.py # карточка чата в Valkey: ключ с именем базы, JSON ↔ ChatFullDTO
repos/attachment.py # строки вложений: вставка pending (created_at = updated_at), mark_ready (pending и непомеченная → ready RETURNING), чтение одной и до 10; уборщику — get_stale_pending (keyset по частичному индексу), lock_stale_pending (FOR UPDATE SKIP LOCKED), mark_removing (пометка updated_at), delete_attachment
repos/attachment_object.py # оригинал в S3: ключ <база>/attachments/<id>/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/<id>/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/<domain>.py # <Domain>Service: логика, проверки доступа, id и время, логи; чаты и сообщения — с кэшем; отправка — ключ, сообщение и связи с вложениями одной транзакцией
services/attachment.py # AttachmentService(db_scope, cache, storage, slots): загрузка (проверки → место загрузки, 429 → тело со счётчиком и сроком в BytesIO, 400 по сроку → структура и SHA-256 в потоке над getvalue() → del → pending → PUT тем же BytesIO → ready; сбой ready до COMMIT или пропавшая строка — удаление объекта и 503; место — до ответа), метаданные, отдача потоком
services/attachment_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/<domain>.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/<domain>.py # DTO между repo → service → api
enums/<domain>.py # StrEnum доменов, RunModeEnum; attachment.py — AttachmentStatus, ImageType
enums/<domain>.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_<capability>.py # сценарии основных спеков, маркер @pytest.mark.spec
test_failures.py # проверки отказов (маркер fault): только make failure_checks
run_isolated.py # make test_isolated: образ на временной базе test_<db>, уборка базы и префикса test_<db>/ в 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
+28 -17
View File
@@ -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
+9
View File
@@ -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)
+30
View File
@@ -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`.
+6 -1
View File
@@ -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
+12
View File
@@ -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
+4
View File
@@ -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
+62 -9
View File
@@ -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 <database>/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" <<EOF
{"Version": "2012-10-17", "Statement": [{"Effect": "Allow",
"Action": ["s3:GetObject", "s3:DeleteObject"],
"Resource": ["arn:aws:s3:::${BUCKET}/*"]},
{"Effect": "Allow", "Action": ["s3:ListBucket"],
"Resource": ["arn:aws:s3:::${BUCKET}"],
"Condition": {"StringLike": {"s3:prefix": ["${LIST_PREFIX}*"]}}}]}
EOF
ws_step "policy put ${CLEANER_POLICY}" \
"s3.policy -put -name=${CLEANER_POLICY} -file=$WORK/policy.json"
}
apply_policies() {
put_policy "$API_POLICY" \
'["s3:GetObject", "s3:PutObject", "s3:DeleteObject"]'
# уборщику — без записи, списка и прав на bucket
put_policy "$CLEANER_POLICY" '["s3:GetObject", "s3:DeleteObject"]'
put_cleaner_policy
}
# ключ и секрет пользователя $1 — из окружения (.env)
@@ -315,11 +350,21 @@ apply_checks() {
|| fail "cleaner key put is not denied"
[ "$(cleaner_signed "${S3}/${BUCKET}?list-type=2")" = 403 ] \
|| fail "cleaner key list is not denied"
# список своего префикса: политика доходит до шлюза подпиской, как ключ
wait_key 200 "$CLEANER_CRED" "$(list_url "$LIST_PREFIX")" \
|| fail "cleaner key list ${LIST_PREFIX} (code ${code})"
[ "$(cleaner_signed -X DELETE "$probe")" = 204 ] || fail "cleaner key delete"
[ "$(signed "$probe")" = 404 ] || fail "object is still there after delete"
say "checks passed (api key put/get; cleaner key get/delete; api key" \
"list and bucket create, cleaner key put and list, anonymous get and" \
"list denied)"
say "checks passed (api key put/get; cleaner key get/delete and list" \
"${LIST_PREFIX}; api key list and bucket create, cleaner key put and" \
"list of the bucket, anonymous get and list denied)"
}
# адрес ListObjectsV2 своего bucket с префиксом $1 (символы [a-z0-9_.-/],
# «/» — %2F в строке запроса подписи) и одним ключом
list_url() {
encoded=$(printf '%s' "$1" | sed 's#/#%2F#g')
printf '%s' "${S3}/${BUCKET}?list-type=2&max-keys=1&prefix=${encoded}"
}
# ---------------------------------------------------------------- check
@@ -369,6 +414,10 @@ run_checks() {
"$(cleaner_signed -X PUT --data-binary "$TAG" "$own")"
check "cleaner key list objects" 403 \
"$(cleaner_signed "${S3}/${BUCKET}?list-type=2")"
check "cleaner key list attachments prefix" 200 \
"$(cleaner_signed "$(list_url "$LIST_PREFIX")")"
check "cleaner key list other prefix" 403 \
"$(cleaner_signed "$(list_url .s3-check/)")"
check "cleaner key create bucket" 403 \
"$(cleaner_signed -X PUT "${S3}/${CHECK_BUCKET_PREFIX}forbidden-$$")"
check "cleaner key delete bucket" 403 \
@@ -434,6 +483,10 @@ run_cleanup() {
done
}
case "$MODE" in
apply | check) check_list_prefix ;;
esac
case "$MODE" in
apply)
apply_bucket
@@ -0,0 +1,37 @@
"""added attachments lost_at
Revision ID: 5c3e1f0a9b7d
Revises: 739b8f04d5fb
Create Date: 2026-10-22 12:00:00.000000
"""
from collections.abc import Sequence
import sqlalchemy as sa
from alembic import op
# revision identifiers, used by Alembic.
revision: str = "5c3e1f0a9b7d"
down_revision: str | Sequence[str] | None = "739b8f04d5fb"
branch_labels: str | Sequence[str] | None = None
depends_on: str | Sequence[str] | None = None
def upgrade() -> 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")
@@ -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.
+93 -25
View File
@@ -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` — префикс `<namespace>/attachments/`;
- `parse_original_key` — `UUID` для ключа вида `<id>/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 ГБ, стенды проекта не затронуты, предложение. Запись
остаётся открытой.
+21
View File
@@ -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, байты оригинала —
+21 -5
View File
@@ -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, а
в журнале — итог сверки с причиной прерывания «остановка» и запись об
остановке уборщика
+48 -25
View File
@@ -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: Учётные данные отклонены
@@ -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** уборщик не стартует, в журнале — ошибка проверки настроек с
именем поля
+43
View File
@@ -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`
+251 -6
View File
@@ -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/<id>/original`, на который не ссылается ни одна
строка и для `id` которого строки нет;
- **метаданные без объекта** — вложение `ready`, объекта по ключу из его
метаданных в bucket нет;
- **другой размер** — вложение `ready`, размер объекта не равен
`size_bytes`;
- **зависшая загрузка** — вложение в статусе «загружается» старше grace,
то же, что убирает уборщик (требование «Уборщик незавершённых
загрузок»);
- **оригинал вернулся** — оригинал вложения помечен потерянным
(требование «Потерянный оригинал»), а объект снова есть с тем же
размером;
- **чужой объект** — объект под префиксом вложений, ключа такого вида
API не пишет, либо ключ вида `<id>/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 удалять:
- метаданные вложений, кроме уборки зависшей загрузки;
- объект, на который ссылаются метаданные, в любом статусе;
- объект с ключом вида `<id>/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** не позже интервала с запасом вложение помечено потерянным
без разового прохода, а в журнале уборщика есть итог сверки
+27 -10
View File
@@ -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`. Рабочий стенд, его база, кэш,
+179 -34
View File
@@ -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
+20
View File
@@ -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(
+125 -1
View File
@@ -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` — из стандартных ключей
`<id>/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))
+68 -1
View File
@@ -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:
"""Префикс объектов вложений своей базы: `<namespace>/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` вложения из ключа `<namespace>/attachments/<id>/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,
*,
+2
View File
@@ -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",
+8 -1
View File
@@ -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(
+6 -5
View File
@@ -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` = сейчас,
+741
View File
@@ -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,
)
+5
View File
@@ -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):
+2
View File
@@ -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",
]
+72 -9
View File
@@ -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,
+4
View File
@@ -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",
+52 -3
View File
@@ -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:
"""Оригинал вложения на отдачу потоком.
+8 -1
View File
@@ -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",
]
+29
View File
@@ -18,3 +18,32 @@ class ImageType(StrEnum):
PNG = "image/png"
JPEG = "image/jpeg"
class ReconcileFinding(StrEnum):
"""Класс расхождения bucket и БД (design change `track2-reconciler`,
решения 3 и 8). Значения пишутся в журнал и отчёт сверки, в БД их нет.
"""
# объект `<id>/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"
+4
View File
@@ -79,6 +79,10 @@ OBJECT_KEY_MAX_BYTES = 1024
# ключ объекта: `<имя базы>/attachments/<id>/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`,
+7 -6
View File
@@ -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
+6 -1
View File
@@ -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"
+296 -13
View File
@@ -51,18 +51,54 @@
сразу), а перевод в ready ждёт до 4,5 с, пока
строка pending не исчезнет; undeletable — как
outlive, и удаление строки падает
fail-attachments mark <filename>
пометка потерянного оригинала (UPDATE
lost_at) вложения с этим filename падает
(08006); свой триггер BEFORE UPDATE OF
lost_at, прежние режимы колонку не трогают
clear-fail-attachments убрать триггеры
kill-api docker kill обычного API стенда
(`<FAULT_PROJECT>-api`)
start-api docker start того же контейнера и ожидание
healthy его healthcheck
put-object <ключ> записать объект с телом из stdin в bucket
стенда мимо API: botocore в контейнере
обычного API его ключами из окружения
контейнера. Ключ — только под
`<FAULT_DATABASE>/attachments/`, символы
[A-Za-z0-9._/-]
delete-object <ключ> удалить объект мимо шлюза S3: `weed shell
fs.rm /buckets/<bucket>/<ключ>`; ключ — с той
же проверкой
delete-row <id> удалить строку вложения (неиспользуемого:
ссылку сообщения не даст удалить FK)
set-size <id> <байт> изменить size_bytes строки
age-row <id> <секунд> сдвинуть 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=<n>`; код hook — 0
stop|start cleaner сервис уборщика стенда
run-cleaner <секунд> отдельный уборщик
`<FAULT_PROJECT>-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=<n>`."""
if mode not in RECONCILE_MODES or len(args) > 1:
raise HookError("reconcile dry-run|apply [<max changes>]")
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}")
+13 -3
View File
@@ -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")
+548 -2
View File
@@ -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/<id>/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 не пишет: под префиксом вложений, но не <id>/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)