docs: propose track2-reconciler
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
@@ -1108,3 +1108,127 @@ apply»; вопрос 1 открыт — сделано 429, как по умо
|
||||
`student-tests/contract.py`, ожидания `test_upload_slots_busy` и
|
||||
`test_rejections_before_queue`, сценарии спеков `attachments` и
|
||||
`api-conventions`, правило `api-contract.md`.
|
||||
|
||||
### track2-reconciler
|
||||
|
||||
#### Решения
|
||||
|
||||
Приняты 2026-10-22 в `/opsx:propose`, подробности — design change
|
||||
`track2-reconciler`. Пробы — design, Context: проект compose `rcprobe`,
|
||||
SeaweedFS и PostgreSQL на tmpfs, bootstrap проекта.
|
||||
|
||||
1. **Сверка — часть уборщика** (решение 1):
|
||||
- команда `python -m src.cleaner reconcile [--apply] [--max-changes
|
||||
N]`, по умолчанию dry-run; цель `make reconcile [APPLY=1]`;
|
||||
- плановая сверка в сервисе `cleaner` — при старте и раз в
|
||||
`[reconciler] interval_seconds` (3600 с), с исправлением;
|
||||
- `--once` — как было.
|
||||
|
||||
Отвергнуты:
|
||||
- отдельный сервис и пользователь S3 `reconciler`: второй процесс и
|
||||
два секрета ради почти пустого разделения прав;
|
||||
- сверка только вручную: PUT-зомби жил бы до запуска.
|
||||
|
||||
С уборщиком на строках `pending` сверка не спорит: убирает их его
|
||||
процедурой (`FOR UPDATE SKIP LOCKED` и пометка), а объект строки любого
|
||||
статуса не удаляет никогда.
|
||||
2. **Права S3** (решение 2). `cleaner-objects` получает `s3:ListBucket`
|
||||
с условием `s3:prefix` `<база>/attachments/*`, префикс bootstrap берёт
|
||||
из `POSTGRES_DB` (`S3_CLEANER_LIST_PREFIX`). Проба: SeaweedFS 4.48
|
||||
условие соблюдает — весь bucket, `test_<db>/` и чужой bucket дают 403.
|
||||
Нового пользователя и секретов нет. `make s3_check` получает строки
|
||||
списка ключом уборщика.
|
||||
3. **Проход** (решение 3):
|
||||
- страницы LIST по 1000;
|
||||
- на страницу — одно выражение к БД по `id` (по тексту ключа — только
|
||||
для нестандартных ключей: по пробе в 15 раз дороже);
|
||||
- множество увиденных ключей, затем keyset строк `ready` по `id`.
|
||||
|
||||
Слияние отсортированных потоков отвергнуто: порядок списка SeaweedFS —
|
||||
обход каталогов, а не порядок байтов (проба). Действия — только после
|
||||
классификации, каждое с перепроверкой в БД и HEAD.
|
||||
4. **Безопасность** (решение 4):
|
||||
- grace уборщика по `LastModified` объекта и времени строки;
|
||||
- удаляются только объекты без строки и зависшие загрузки;
|
||||
- чужие ключи — только отчёт и код 3;
|
||||
- отсутствие объекта не подтверждается без проверки bucket;
|
||||
- предел `[reconciler] max_changes` (100): больше — ни одного
|
||||
изменения, код 3.
|
||||
5. **Потерянный оригинал** (решение 5) — колонка `attachments.lost_at`.
|
||||
`status` и `updated_at` не меняются. Ответы API:
|
||||
- скачивание помеченного — 404 без обращения к S3, до пометки — 500,
|
||||
как было;
|
||||
- метаданные — 200;
|
||||
- ссылка в сообщении — 201.
|
||||
|
||||
Это вариант по умолчанию до ответа на вопрос 1 ниже. Статус
|
||||
`lost`/`failed` отвергнут: контракт лабы 4 знает только `ready`.
|
||||
6. **Миграция** (решение 6) — `ADD COLUMN lost_at` с `SET LOCAL
|
||||
lock_timeout`. По пробе это только каталог: 0,36 мс. Смеси версий не
|
||||
хуже, чем до change. Порядок обновления:
|
||||
- вперёд — `s3-bootstrap`, `make rolling_update`, затем уборщик;
|
||||
- откат — сначала уборщик.
|
||||
7. **Коды разового прохода** (решение 8): 0 — расхождений нет, 3 —
|
||||
остались (в том числе чужой объект или отказ по пределу), 1 —
|
||||
прерван, 2 — конфигурация.
|
||||
8. **Стенд отказов** (решения 9, 11):
|
||||
- плановая сверка выключена (`RECONCILER__INTERVAL_SECONDS=0`);
|
||||
- сверку запускает hook;
|
||||
- новые действия hook: объект мимо API, удаление объекта, строки и
|
||||
размера, сдвиг времени строки, `lost-ids`, `fail-attachments mark`,
|
||||
`reconcile`, `stop|start cleaner`, `run-cleaner`;
|
||||
- восемь тестов отказов, ~+3 мин; объекты без строки ждут grace, а
|
||||
строки состаривает hook.
|
||||
9. **Evidence** (решение 12), `evidence/reconcile/`:
|
||||
- `cycle.md` — драйвер `reconcile-cycle`: dry-run, apply, повтор = 0,
|
||||
возврат оригинала;
|
||||
- `stress.md` — `reconcile-stress`;
|
||||
- `service.md`.
|
||||
|
||||
Плюс `evidence/s3/cleaner-list.md` и `evidence/migrations/lost-at.md`.
|
||||
10. **Граница с `track2-reconcile-cost`** (решение 13). Здесь — одна
|
||||
стратегия «батч» и поверхностная сверка (наличие и размер). Там:
|
||||
- HEAD на строку;
|
||||
- глубокая сверка SHA-256;
|
||||
- ограничение скорости;
|
||||
- профиль `reconcile` стенда `bench/`;
|
||||
- гипотезы 1–4.
|
||||
|
||||
Гипотезу 5 проверяет стресс этого change.
|
||||
11. **Запись `KNOWN_ISSUES.md` о bootstrap после удаления bucket —
|
||||
воспроизведена и объяснена** (design, Context; решение 14). Причина —
|
||||
не имя bucket, а слоты томов:
|
||||
- `-volume.max=0` даёт на tmpfs 4 ГБ три слота;
|
||||
- после удаления коллекции их занимают тома коллекции по умолчанию;
|
||||
- PUT получает «no free volumes left», 500.
|
||||
|
||||
На 16 ГБ повтор bootstrap прошёл за 2 с. У рабочего стенда 403
|
||||
свободных слота. Reconciler bucket не создаёт, поэтому запись не
|
||||
чинится. В apply её текст переписывается, запись остаётся открытой.
|
||||
|
||||
#### Вопросы
|
||||
|
||||
1. **Вопрос преподавателю.** Что отвечает API лабы 4 на вложение,
|
||||
оригинал которого потерян, после того как сверка это подтвердила?
|
||||
Объекта в bucket нет или он другого размера, байтов не восстановить.
|
||||
|
||||
Контракт неоднозначен:
|
||||
- `contracts/openapi.json`: у `Attachment.status` в лабе 4 одно
|
||||
значение — `ready`, `failed` и 409 появляются с лабы 5;
|
||||
- `contracts/README.md`: «Отсутствующий вариант ready-объекта — 404»,
|
||||
«404 — объекта нет или он чужой» и «Неожиданное исключение — 500».
|
||||
|
||||
Варианты:
|
||||
- (а) **по умолчанию:** метаданные — 200 как раньше (`ready`,
|
||||
`error_code=null`), байты — 404 `not_found`, как отсутствующий
|
||||
вариант, ссылка в новом сообщении — 201. До пометки байты — 500:
|
||||
непредвиденное расхождение;
|
||||
- (б) вложение целиком как незавершённое: метаданные, байты и ссылка
|
||||
— 404;
|
||||
- (в) байты — 500 и после пометки: пометка только для отчёта.
|
||||
|
||||
Ответ (б) или (в) меняет только ветку `open_content` и выборку
|
||||
вложений сообщения, сценарий `attachments` «Потерянный оригинал», тест
|
||||
`test_reconcile_finds_and_fixes` и `REPORT.md`. Классы, правила
|
||||
безопасности, схема и задачи сверки не меняются (design, Open
|
||||
Questions).
|
||||
|
||||
@@ -0,0 +1,2 @@
|
||||
schema: spec-driven
|
||||
created: 2026-10-22
|
||||
@@ -0,0 +1,722 @@
|
||||
# Design
|
||||
|
||||
## Context
|
||||
|
||||
Мотивация — `proposal.md`, раздел Why. Требования — `specs/`.
|
||||
|
||||
### Код
|
||||
|
||||
Состояние после `upload-memory` (`5f4b9ff`):
|
||||
|
||||
- **Уборщик.** `python -m src.cleaner [--once]` (`src/cleaner/main.py`):
|
||||
- свой engine (пул 1) и клиент S3 с ключами пользователя `cleaner`;
|
||||
- цикл «проход → ожидание `[cleaner] interval_seconds` или сигнала»,
|
||||
проверка grace > B = 17 с при старте;
|
||||
- коды 0/1/2.
|
||||
|
||||
Проход — `AttachmentCleanupService.clean_stale_pending`: кандидаты
|
||||
keyset по частичному индексу, каждая строка в два шага под `FOR UPDATE
|
||||
SKIP LOCKED` — пометка, затем объект и строка одной транзакцией.
|
||||
Объект без строки и строку `ready` без объекта он не ищет.
|
||||
- **Права S3 уборщика** (`infra/s3/bootstrap.sh`, политика
|
||||
`cleaner-objects`): только `s3:GetObject` и `s3:DeleteObject` на
|
||||
`<bucket>/*`. Bootstrap и `make s3_check` проверяют, что список
|
||||
объектов ключом уборщика — 403. Спек `object-storage` («Ограниченные
|
||||
учётные данные уборщика») прямо запрещает ему список.
|
||||
- **Клиент S3** (`ObjectStorage`) умеет `put`, `head`, `open`, `delete`,
|
||||
списка у него нет. `_call` всегда передаёт `Key`. Удалённый bucket у
|
||||
HEAD неотличим от отсутствующего ключа, правило — `PLAN.md`,
|
||||
`s3-storage`, вопрос 4.
|
||||
- **Скачивание** (`AttachmentService.open_content`): нет объекта или
|
||||
другой размер — `error` «Attachment content is missing» / «…size
|
||||
differs» и 500 (`AttachmentContentMissing`). Строка не меняется.
|
||||
- **Схема `attachments`:**
|
||||
- `status IN ('pending', 'ready')`;
|
||||
- уникальный `object_key` — индекс `uq_attachments_object_key`;
|
||||
- частичный индекс `pending`;
|
||||
- CHECK `updated_at >= created_at`.
|
||||
|
||||
Колонки пометки нет. Чтение и вставка перечисляют свои колонки
|
||||
(`_ATTACHMENT_COLUMNS`), поэтому новая колонка прежнему коду не мешает.
|
||||
- **Тесты.** Стенд отказов запускает уборщика с grace 20 с и интервалом
|
||||
1 с. Hook умеет `attachment-ids`, `object-ids` (`fs.tree`),
|
||||
`fail-attachments …`, `kill-api` / `start-api`. Сверка покрытия
|
||||
требует тест или исключение для каждого сценария `storage-consistency`.
|
||||
|
||||
### Пробы (2026-10-22, scratchpad, проект compose `rcprobe`)
|
||||
|
||||
Стенд пробы:
|
||||
- SeaweedFS тем же образом и аргументами, что `s3`, данные на tmpfs;
|
||||
- PostgreSQL 18.6 на tmpfs;
|
||||
- клиент botocore в образе `mtusi-messenger:lab4`;
|
||||
- bootstrap — сам `infra/s3/bootstrap.sh` проекта (read-only).
|
||||
|
||||
Volumes не создавались. Проект удалён, список volumes и сетей совпал с
|
||||
исходным (155 и 17).
|
||||
|
||||
| Проверка | Результат |
|
||||
|---|---|
|
||||
| Ключ уборщика с текущей политикой: список bucket, с префиксом и без, v1 и v2, HEAD bucket | 403 `AccessDenied`; HEAD отсутствующего ключа — 404, GET — `NoSuchKey` |
|
||||
| `s3:ListBucket` на `arn:aws:s3:::messenger` | список своего bucket — 200, чужого — 403, HEAD bucket — 200, запись — 403 |
|
||||
| `s3:ListBucket` с `Condition: StringLike s3:prefix messenger/attachments/*` | префикс `messenger/attachments/` — 200, весь bucket и `test_messenger/` — 403, HEAD bucket — 403, чужой bucket — 403. Условие SeaweedFS 4.48 соблюдает. Постраничный список под этим условием (3 страницы по 1000) — полный |
|
||||
| `s3:ListBucket` только на ресурсе `<bucket>/*` | списка нет (403), как в AWS |
|
||||
| ListObjectsV2, 2 503 и 20 003 ключа под префиксом, MaxKeys 1000 | 3 и 21 страница, 0,31 с и ~2,0 с (~0,1 мс на ключ); `LastModified` с точностью до секунды, UTC; `Size`, `ETag`; токен продолжения — последний ключ открытым текстом |
|
||||
| Порядок списка на соседях `aaa/…`, `aaa-x`, `aaa.y/…`, `aaa0` | порядок обхода каталогов: `aaa/original`, `aaa/zzz`, затем `aaa-x`. Это не порядок байтов: в нём `aaa-x` < `aaa.y/…` < `aaa/…`. Страницы по одному ключу совпали с одной страницей без пропусков и повторов |
|
||||
| `weed shell fs.rm` объекта в `/buckets/…` | HEAD — 404, в списке объекта нет, пустой каталог `<id>/` в список не попадает |
|
||||
| bucket удалён (`s3.bucket.delete`) | список с префиксом — 404 `NoSuchBucket`, GET — `NoSuchBucket`, HEAD объекта — 404, как отсутствующий ключ |
|
||||
| PostgreSQL, 21 000 строк (20 000 `ready`), общий план | `ALTER TABLE … ADD COLUMN lost_at timestamptz` — 0,36 мс (только каталог). Страница 1000 ключей `object_key = ANY($1) OR id = ANY($2)` — Bitmap OR двух индексов, 6–7 мс: часть по `uq_attachments_object_key` — 5,6–6,2 мс (сравнение текста), часть по `pk_attachments` — 0,3–0,4 мс; один `object_key = ANY` — 6 мс. Обход `ready` keyset по `id` (`status`, `lost_at`, `updated_at` — фильтр) — Index Scan `pk_attachments`, 1000 строк за 0,4–0,6 мс |
|
||||
|
||||
### Запись `KNOWN_ISSUES.md` о bootstrap после удаления bucket
|
||||
|
||||
Воспроизведена на пробе и объяснена: дело в слотах томов, а не в
|
||||
повторном имени bucket.
|
||||
|
||||
| Стенд | Слотов томов | После `s3.bucket.delete` и повторного bootstrap |
|
||||
|---|---|---|
|
||||
| tmpfs 4 ГБ | 3 из 3 заняты | «bucket created», затем «FAILED: api key wait (code 500)» дважды подряд. В журнале S3 — «No writable volumes and no free volumes left for collection:messenger» |
|
||||
| tmpfs 16 ГБ | 15 | «bucket created», проверки прошли за 2 с |
|
||||
|
||||
Почему так:
|
||||
- сервер запущен с `-volume.max=0`, и число слотов считается по
|
||||
свободному месту / 1 ГиБ;
|
||||
- удаление bucket удаляет томá его коллекции, но на маленьком диске
|
||||
слоты занимают тома коллекции по умолчанию (журналы filer);
|
||||
- новых томов для `messenger` выделить некуда.
|
||||
|
||||
У рабочего стенда volume на диске ВМ: 417 слотов, 403 свободны (`weed
|
||||
shell volume.list`, только чтение). Там удаление bucket и повтор
|
||||
bootstrap этим не падают. Решение 14.
|
||||
|
||||
### Рабочий стенд перед change
|
||||
|
||||
Только чтение: 2 019 строк `ready`, 2 019 файлов `original` (`fs.tree`),
|
||||
строк `ready` без объекта и объектов без строки — 0, `pending` — 0.
|
||||
|
||||
## Goals / Non-Goals
|
||||
|
||||
**Goals:**
|
||||
|
||||
- Пункт трека 2 о reconciler (`PLAN.md`, этап 5): обе стороны,
|
||||
dry-run, `--apply`, повтор = 0, стресс с проверкой SHA-256.
|
||||
- Ни при каком порядке действий сверка не удаляет подтверждённое,
|
||||
используемое и свежее (гипотеза 5).
|
||||
- Остаточные риски `upload-consistency` закрыты автоматически. PUT-зомби
|
||||
убирает плановая сверка. Строку `ready` без объекта она помечает, и
|
||||
API отвечает по контракту, а не 500.
|
||||
- Смешанные версии при `make rolling_update` не хуже, чем до change.
|
||||
|
||||
**Non-Goals:**
|
||||
|
||||
- Стоимость обхода, стратегии и ограничение скорости —
|
||||
`track2-reconcile-cost` (решение 13).
|
||||
- Восстановление байтов потерянного оригинала: их нет нигде.
|
||||
- Сверка других префиксов bucket (`test_<db>/`, `.s3-check/`) и чужих
|
||||
баз.
|
||||
- Новые статусы вложения. Контракт лабы 4 знает только `ready`.
|
||||
- Исправление записи `KNOWN_ISSUES.md` о bootstrap: reconciler bucket не
|
||||
создаёт (решение 14).
|
||||
|
||||
## Decisions
|
||||
|
||||
### 1. Сверка — часть уборщика
|
||||
|
||||
Пакет `src/cleaner/` и сервис compose `cleaner` вырастают в reconciler,
|
||||
как и задумано (`PLAN.md`, решение 7; design `upload-consistency`,
|
||||
решение 12):
|
||||
- `python -m src.cleaner` (сервис) — прежний цикл уборки, плюс плановая
|
||||
сверка (решение 9);
|
||||
- `python -m src.cleaner --once` — один проход уборки, как раньше;
|
||||
- `python -m src.cleaner reconcile [--apply] [--max-changes N]` — разовая
|
||||
сверка, по умолчанию dry-run. В compose — `docker compose run --rm
|
||||
--no-deps cleaner reconcile …` (точка входа уже `python -m
|
||||
src.cleaner`). Цель Makefile — `make reconcile [APPLY=1]
|
||||
[MAX_CHANGES=N]`;
|
||||
- сервис `AttachmentReconcileService(db_scope, storage)`
|
||||
(`src/core/services/attachment_reconcile.py`), метод `reconcile(*,
|
||||
older_than, apply, max_changes, page_size, batch_size,
|
||||
stop_requested)`. Зависшие загрузки он отдаёт
|
||||
`AttachmentCleanupService` (решение 7).
|
||||
|
||||
Как уборщик и сверка не мешают друг другу на строках `pending`:
|
||||
- внутри процесса проходы идут по очереди, одновременно не бывают;
|
||||
- между процессами (сервис и разовый `run`) сверка трогает строку
|
||||
`pending` только процедурой уборщика — тот же `FOR UPDATE SKIP LOCKED`
|
||||
и пометка;
|
||||
- объект строки `pending` правило «объект без метаданных» не видит:
|
||||
строка на него ссылается;
|
||||
- пометку потерянного оригинала получает только строка `ready`, а её
|
||||
уборщик не выбирает никогда;
|
||||
- все действия безопасно повторять, поэтому и две сверки разом ничего
|
||||
не ломают: удаление объекта и условный `UPDATE` идемпотентны.
|
||||
|
||||
*Альтернатива:* отдельная точка входа `python -m src.reconciler`, свой
|
||||
сервис и пользователь S3 `reconciler`. Отвергнута:
|
||||
- два процесса с доступом к одной базе, ещё два секрета, пользователь в
|
||||
bootstrap и строки `make s3_check` — ради разделения, которое почти
|
||||
ничего не даёт. У уборщика и так есть ключи всех объектов в БД, чтение
|
||||
и удаление любого объекта bucket. Список по префиксу своей базы
|
||||
(решение 2) добавляет к этому мало;
|
||||
- плановой сверке всё равно нужен долгоживущий процесс, а он уже есть.
|
||||
|
||||
*Альтернатива:* только ручная сверка, без плановой. Отвергнута: PUT-зомби
|
||||
жил бы до ручного запуска, и остаточный риск `upload-consistency` остался
|
||||
бы «навсегда» (решение 9). *Альтернатива:* фоновая задача реплик API.
|
||||
Запрещена (AGENTS.md). *Альтернатива:* lifecycle-правила S3. Отвергнуты:
|
||||
S3 не знает строк БД.
|
||||
|
||||
### 2. Права S3: список по префиксу вложений своей базы
|
||||
|
||||
Политика `cleaner-objects` получает второй оператор (проба —
|
||||
Context):
|
||||
|
||||
```json
|
||||
{"Effect": "Allow", "Action": ["s3:ListBucket"],
|
||||
"Resource": ["arn:aws:s3:::<bucket>"],
|
||||
"Condition": {"StringLike": {"s3:prefix": ["<база>/attachments/*"]}}}
|
||||
```
|
||||
|
||||
Чтение и удаление на `<bucket>/*` — как были.
|
||||
|
||||
- Префикс bootstrap получает в `S3_CLEANER_LIST_PREFIX:
|
||||
${POSTGRES_DB:?…}/attachments/` (окружение `s3-bootstrap` в
|
||||
`docker-compose.yml`). Это не секрет. Скрипт проверяет его по
|
||||
`^[a-z0-9_]+/attachments/$` и подставляет в JSON только проверенное
|
||||
значение. На стенде отказов и в `bench/` (`POSTGRES_DB=bench`) префикс
|
||||
берётся тем же путём. Уборщику его не передают: свой префикс он строит
|
||||
из `settings.database.name`, как ключи объектов.
|
||||
- Проверки `apply`:
|
||||
- ключ уборщика получает 200 на список с префиксом;
|
||||
- 403 на список всего bucket — так же, как сейчас «cleaner key list is
|
||||
not denied».
|
||||
- Режим `check` (`make s3_check`), строки ключа уборщика:
|
||||
- «cleaner key list attachments prefix» — 200;
|
||||
- «cleaner key list objects» без префикса — 403, как было;
|
||||
- «cleaner key list other prefix» (`.s3-check/`) — 403;
|
||||
- «cleaner key list other bucket» — 403, как было.
|
||||
- Порядок обновления. Bootstrap только расширяет права и у API ничего не
|
||||
забирает (`balancer.md`). Новый уборщик со старой политикой получает
|
||||
`AccessDenied` на списке: проход сверки прерван, `error` «Object
|
||||
storage denied access», уборка работает. Поэтому вперёд — сначала
|
||||
`docker compose up -d s3-bootstrap` (решение 6).
|
||||
|
||||
*Альтернатива:* `s3:ListBucket` без условия. Отвергнута: уборщик видел бы
|
||||
ключи других баз (`test_<db>/`) и проверочные объекты, а сверке они не
|
||||
нужны. *Альтернатива:* `s3:ListBucket` на ресурсе `<bucket>/*`. По пробе
|
||||
списка не даёт. *Альтернатива:* сузить по префиксу и чтение с удалением.
|
||||
Отложена: проверки bootstrap удаляют ключом уборщика свои объекты под
|
||||
`.s3-bootstrap/` и `.s3-check/`, их пришлось бы переделать. Ключи
|
||||
объектов уборщик и так берёт из БД своей базы.
|
||||
|
||||
### 3. Классы и проход сверки
|
||||
|
||||
Классы — спек `storage-consistency`, «Сверка bucket и БД». Порог
|
||||
`older_than = utcnow() − [cleaner] pending_grace_seconds` один на
|
||||
проход, по часам приложения, как у уборщика. Проход:
|
||||
|
||||
1. **S3 → БД.** Страницы ListObjectsV2 по префиксу `<база>/attachments/`
|
||||
(`[reconciler] page_size`, до 1000).
|
||||
- Ключ вида `<база>/attachments/<uuid в нижнем регистре>/original`
|
||||
(`attachment_object_repo.parse_original_key`) даёт `id`. Остальные
|
||||
ключи — «нестандартные».
|
||||
- На страницу — одно выражение к БД: `id = ANY(:ids) OR object_key =
|
||||
ANY(:keys)`. Здесь `ids` — из стандартных ключей, `keys` — только
|
||||
нестандартные, обычно их нет. По пробе выборка по `id` в 15 раз
|
||||
дешевле выборки по тексту ключа.
|
||||
- Классификация без новых вызовов S3:
|
||||
- строка `id` с тем же ключом. `pending` — пропуск, это дело
|
||||
уборщика. `ready` без пометки: размер равен — порядок; другой —
|
||||
кандидат «другой размер», если строка старше порога, иначе
|
||||
«свежая». `ready` с пометкой: размер равен — кандидат «оригинал
|
||||
вернулся», иначе «уже помечено»;
|
||||
- строка `id` с другим ключом — «чужой объект»;
|
||||
- строки нет: `LastModified` раньше порога — кандидат «объект без
|
||||
метаданных», иначе «свежий объект»;
|
||||
- нестандартный ключ — строка с таким `object_key` есть: как у
|
||||
строки выше, иначе «чужой объект».
|
||||
- Каждый ключ попадает в множество `seen`.
|
||||
2. **БД → S3.** Keyset по `id` по всем строкам `ready` (`[reconciler]
|
||||
page_size` строк, Index Scan `pk_attachments` — проба).
|
||||
- Строка без пометки старше порога, ключа которой нет в `seen`, —
|
||||
кандидат «метаданные без объекта».
|
||||
- Моложе порога — «свежая».
|
||||
- С пометкой — «уже помечено», если оригинал не вернулся на шаге 1.
|
||||
3. **Зависшие загрузки** — решение 7.
|
||||
4. **Перепроверка** каждого кандидата непосредственно перед решением, в
|
||||
обоих режимах (решение 4).
|
||||
5. **Предел изменений**, затем действия, если `--apply` (решения 4 и
|
||||
8).
|
||||
|
||||
Действия начинаются, только когда классификация закончена. Отказ
|
||||
хранилища на шагах 1–4 прерывает проход без единого изменения.
|
||||
|
||||
Почему множество, а не слияние двух отсортированных потоков. Порядок
|
||||
списка SeaweedFS — обход каталогов, а не порядок байтов (проба). Слияние
|
||||
с `ORDER BY object_key COLLATE "C"` на нестандартных ключах разошлось бы
|
||||
и дало бы ложные расхождения в обе стороны. Цена множества — память
|
||||
O(N): ~150 байт на ключ, при 100 тыс. объектов ~15 МБ при лимите
|
||||
уборщика 256 МБ. Замер — `track2-reconcile-cost`.
|
||||
|
||||
Почему гонка двух снимков (списка и строк) не даёт ложных расхождений:
|
||||
- **объект без метаданных.** API пишет строку до PUT (порядок записи
|
||||
`attachments`). Если объект попал в список, строка его загрузки уже
|
||||
зафиксирована и видна выборке, которая идёт после списка. Её нет,
|
||||
только если её убрал уборщик, — тогда объект и правда лишний;
|
||||
- **метаданные без объекта.** Строки моложе порога не проверяются.
|
||||
Строка старше порога стала `ready` раньше начала прохода, а её объект
|
||||
записан ещё раньше. Объекты `ready` никто, кроме сбоя, не удаляет,
|
||||
поэтому список их видит. Перепроверка HEAD отсекает и неполный ответ
|
||||
списка.
|
||||
|
||||
*Альтернатива:* HEAD на каждую строку вместо множества — стратегия
|
||||
следующего change (гипотеза 2). *Альтернатива:* временная таблица ключей
|
||||
в PostgreSQL и anti-join. Отвергнута: одна долгая транзакция противоречит
|
||||
`idle_in_transaction_session_timeout` и сроку шага 6 с.
|
||||
|
||||
### 4. Правила безопасности
|
||||
|
||||
Свойства — спек «Безопасность сверки». Как они держатся:
|
||||
|
||||
- **Что можно удалить.** Удаление объекта — только у класса «объект без
|
||||
метаданных». Удаление строки — только у зависшей загрузки процедурой
|
||||
уборщика. Строки `ready`, используемые вложения (FK
|
||||
`message_attachments` и так не даст удалить строку) и объекты, на
|
||||
которые ссылается строка, не попадают ни в один удаляющий класс.
|
||||
- **Свежее.**
|
||||
- Объект: по `LastModified` S3 (часы ВМ, точность — секунда).
|
||||
- Строка `ready`: по `updated_at` — время перевода в `ready`.
|
||||
- Строка `pending`: по `created_at`, как у уборщика.
|
||||
|
||||
Grace общий с уборщиком, его проверка границы живой загрузки (17 с)
|
||||
остаётся.
|
||||
- **Перепроверка непосредственно перед решением:**
|
||||
- объект без метаданных: выборка строки по `id` или по ключу
|
||||
(`find_attachment_reference`) — нет; HEAD — объект есть и старше
|
||||
порога. Перед самим DELETE выборка строки — ещё раз. Выборка страницы
|
||||
ищет стандартные ключи только по `id` (решение 3), поэтому строку с
|
||||
чужим `id`, которая ссылается на этот ключ (изменённые метаданные),
|
||||
находит именно перепроверка. Такой объект — «чужой объект», и он не
|
||||
удаляется;
|
||||
- метаданные без объекта и другой размер: `get_attachment` — `ready`,
|
||||
без пометки, тот же ключ; HEAD — объекта нет или размер другой;
|
||||
- оригинал вернулся: пометка на месте, HEAD — размер равен;
|
||||
- не подтвердилось — кандидат выбывает без записи о расхождении.
|
||||
- **Bucket на месте.** Перед подтверждением отсутствия объектов —
|
||||
список с префиксом и `MaxKeys=1`. HEAD bucket при условной политике —
|
||||
403, проба. Удалённый bucket даёт `NoSuchBucket`, и проход прерван.
|
||||
Пустой, пересозданный bucket проходит проверку, но тогда кандидатов
|
||||
больше предела, и действует он.
|
||||
- **Предел изменений.** Число подтверждённых удалений объектов, пометок
|
||||
и снятий пометок сравнивается с `max_changes` (100 или аргумент).
|
||||
Больше — ни одного из этих изменений: `error`, код 3. Уборка зависших
|
||||
загрузок пределом не ограничена: уборщик делает её и без сверки. Предел
|
||||
защищает от сверки с «чужой» базой — пустой или восстановленной из
|
||||
старой копии, при живом bucket — и от пустого bucket.
|
||||
- **Чужой объект** — только отчёт и код 3. Удалять то, чего API не
|
||||
пишет, опасно: в лабе 5 под префиксом появятся варианты, а оператор
|
||||
мог положить копию сам.
|
||||
- **Объект без метаданных удаляется в любой момент после порога.**
|
||||
Объект зомби-загрузки удаляет и её компенсация. Два DELETE одного
|
||||
ключа безопасны.
|
||||
|
||||
*Альтернатива:* пометить строку перед действием, как уборщик. Не нужна:
|
||||
сверка не удаляет строк, а пометка потери — один условный `UPDATE`.
|
||||
*Альтернатива:* относительный предел (доля объектов). Отвергнут: на
|
||||
маленьком стенде он слишком мал, на большом слишком велик. Абсолютный
|
||||
предел понятнее оператору, и его легко поднять аргументом.
|
||||
|
||||
### 5. Потерянный оригинал и ответы API
|
||||
|
||||
- **Пометка** — новая колонка `attachments.lost_at timestamptz NULL`:
|
||||
время, когда сверка подтвердила потерю. `status` и `updated_at` не
|
||||
меняются. Поэтому ответ метаданных прежний, `error_code` — `null`, как
|
||||
требует контракт для `ready`.
|
||||
- `mark_lost`: `UPDATE … SET lost_at = :now WHERE id = :id AND status
|
||||
= 'ready' AND lost_at IS NULL AND object_key = :key RETURNING id`;
|
||||
- `clear_lost`: `… SET lost_at = NULL WHERE id = :id AND lost_at IS NOT
|
||||
NULL AND object_key = :key`.
|
||||
- **API** (спек `attachments`, «Скачивание оригинала»):
|
||||
- скачивание помеченного — 404 `not_found` без обращения к S3, запись
|
||||
`info` «Attachment content is lost»;
|
||||
- непомеченного без объекта — 500, как было;
|
||||
- метаданные — 200, как было;
|
||||
- ссылка в новом сообщении — 201, как на любое `ready`.
|
||||
|
||||
`get_attachment` и DTO получают `lost_at`. `get_attachments` и
|
||||
`MessageService` не меняются.
|
||||
|
||||
Почему так. В контракте лабы 4 у `Attachment.status` одно значение —
|
||||
`ready` (`contracts/openapi.json`), поэтому метаданные не могут сказать
|
||||
«потеряно». Для байтов контракт даёт «Отсутствующий вариант
|
||||
ready-объекта — 404» (`contracts/README.md`). 500 — «неожиданное
|
||||
исключение», а после сверки потеря уже ожидаема. Но прочтения возможны
|
||||
разные, поэтому это вопрос преподавателю (Open Questions; `PLAN.md`,
|
||||
`### track2-reconciler`). Ответ «иначе» меняет только `open_content` и
|
||||
выборку вложений сообщения, спек `attachments` и тесты. Классы, правила
|
||||
и проход сверки от него не зависят.
|
||||
|
||||
*Альтернатива:* статус `lost` или `failed` в CHECK. Отвергнута:
|
||||
- контракт лабы 4 его не знает;
|
||||
- замена CHECK и прежние реплики упали бы на неизвестном значении enum
|
||||
при `make rolling_update`.
|
||||
|
||||
*Альтернатива:* удалить метаданные потерянного вложения, если оно не
|
||||
используется. Отвергнута: «строку без объекта не восстановить, reconciler
|
||||
её находит и помечает» (`PLAN.md`, «Трек 5»). Подтверждённое вложение не
|
||||
удаляется (гипотеза 5), а клиент с его `id` получил бы 404 на метаданные
|
||||
без объяснения. *Альтернатива:* отдельная таблица находок. Отвергнута:
|
||||
лишнее соединение в чтении вложения. Отчёт и так в журнале.
|
||||
|
||||
### 6. Схема и смешанные версии
|
||||
|
||||
Ревизия поверх `739b8f04d5fb`:
|
||||
- первой строкой `op.execute("SET LOCAL lock_timeout = '2s'")`
|
||||
(`migrations.md`: `ACCESS EXCLUSIVE` на рабочую таблицу);
|
||||
- затем `add_column('attachments', Column('lost_at', DateTime(timezone=
|
||||
True), nullable=True))` — только каталог, 0,36 мс на пробе;
|
||||
- `downgrade` — `drop_column` с тем же `lock_timeout`.
|
||||
|
||||
Модель — `lost_at: Mapped[datetime | None]`. Индекса нет: сверка
|
||||
просматривает все строки `ready`, API читает по `id`. CHECK «помечено
|
||||
только `ready`» не добавляется. Для существующей таблицы это `NOT VALID`
|
||||
или скан под блокировкой, а пометку и так ставит только условный
|
||||
`UPDATE`.
|
||||
|
||||
| Смесь | Что происходит | По сравнению с «до change» |
|
||||
|---|---|---|
|
||||
| новая схема + прежние реплики (`5f4b9ff`) | колонку не читают, у помеченного без объекта — 500 | так же |
|
||||
| новый уборщик + прежние реплики | пометки ставятся, прежние реплики их не видят (500); объекты без строки удаляются безопасно — порядок записи прежних версий тот же, строка до PUT, с change `attachments` | не хуже |
|
||||
| прежний уборщик + новые реплики | сверки нет, пометок нет | так же |
|
||||
| новый уборщик + прежняя политика S3 | проход сверки прерван `AccessDenied` (`error`), уборка работает | не хуже |
|
||||
| новый уборщик на прежней схеме | уборка работает; сверка падает на `lost_at`, `error` «Reconcile pass failed», процесс живёт | не хуже; порядок ниже не даёт такой смеси |
|
||||
|
||||
Порядок обновления:
|
||||
1. вперёд — `docker compose up -d s3-bootstrap` (политика со списком);
|
||||
2. затем `make rolling_update` (миграция, затем реплики);
|
||||
3. затем `docker compose up -d --no-deps cleaner`.
|
||||
|
||||
Откат — сначала уборщик (`docker compose stop cleaner` или прежний
|
||||
образ), потом `make rolling_update COMMIT=<прежний> MIGRATE=0`.
|
||||
Колонка и пометки остаются, прежнему коду они не мешают, а после
|
||||
возврата вперёд снова действуют.
|
||||
|
||||
### 7. Зависшие загрузки в сверке
|
||||
|
||||
- Dry-run: кандидаты — `attachment_repo.get_stale_pending` страницами
|
||||
`[cleaner] batch_size`. Каждый — запись с `id`, ключом и возрастом.
|
||||
Ничего не меняется.
|
||||
- `--apply`: `AttachmentCleanupService.clean_stale_pending(older_than=…,
|
||||
batch_size=…, stop_requested=…)` — тот же код, что у сервиса уборки:
|
||||
пометка, затем объект и строка одной транзакцией под блокировкой.
|
||||
Число убранных — в итог сверки.
|
||||
- Порядок действий `--apply`: зависшие загрузки → объекты без метаданных
|
||||
→ пометки → снятия пометок. Остановка (`stop_requested`) проверяется
|
||||
между действиями.
|
||||
|
||||
*Альтернатива:* сверка зависшие загрузки только называет. Отвергнута:
|
||||
без работающего уборщика `--apply` не довёл бы стенд до «повтор = 0», а
|
||||
общий код ничего не стоит.
|
||||
|
||||
### 8. Отчёт, журнал и коды выхода
|
||||
|
||||
- **DTO** (`dto.md`):
|
||||
- `ReconcileFindingDTO`: `kind`, `object_key`, `attachment_id`,
|
||||
`age_seconds`, `size_bytes`, `stored_size`;
|
||||
- `ReconcilePassDTO`: `apply`, `listed_objects`, `checked_rows`,
|
||||
`found` и `fixed` по классам, `fresh_objects`, `fresh_rows`,
|
||||
`lost_known`, `refused`, `interrupted_by`, `duration_ms`.
|
||||
|
||||
`ReconcileFinding` — `StrEnum` в `enums/attachment.py`:
|
||||
`orphan_object`, `missing_object`, `size_mismatch`, `stale_pending`,
|
||||
`restored_object`, `unknown_object`. Строки репозитория —
|
||||
`AttachmentFullDTO`, у него новое поле `lost_at` со значением по
|
||||
умолчанию. Отдельный тип не нужен.
|
||||
- **Журнал** (дельта `service-logging`, модуль
|
||||
`attachment_reconcile_service`):
|
||||
- находка — `warning` «Found storage discrepancy»;
|
||||
- исправленная — `info` «Fixed storage discrepancy» с `action`
|
||||
(`deleted_object`, `marked_lost`, `cleared_lost`, `removed_pending`);
|
||||
- итог — «Finished reconcile pass» (`info` или `warning`);
|
||||
- предел — `error` «Reconcile changes exceed limit»;
|
||||
- отдельные записи — первые `RECONCILE_FINDINGS_LOGGED_MAX` (1000,
|
||||
`constants.py`), в итоге — сколько осталось без записи.
|
||||
- **Отчёт разового прохода** — те же JSON-записи в stdout. Отдельного
|
||||
формата нет: hook и драйвер разбирают записи `Found` / `Fixed` /
|
||||
`Finished`.
|
||||
- **Коды** разового прохода (спек): 0 / 3 / 1 / 2. Код 3 — и при чужом
|
||||
объекте: он требует внимания оператора, хотя сверка его не тронет.
|
||||
Прерванный сигналом разовый проход — 1, сервис — 0 (дельта
|
||||
`graceful-shutdown`).
|
||||
|
||||
### 9. Плановая сверка
|
||||
|
||||
- В цикле сервиса после прохода уборки проверяется срок плановой сверки
|
||||
(`loop.time()` против следующего срока):
|
||||
- первая сверка — при старте;
|
||||
- следующая — через `[reconciler] interval_seconds` (3600 с) после
|
||||
конца предыдущей;
|
||||
- 0 — без плановой сверки.
|
||||
|
||||
Это тот же `reconcile(apply=True, max_changes=[reconciler]
|
||||
max_changes)`. Непредвиденная ошибка — `error` с traceback, процесс
|
||||
живёт, как у уборки.
|
||||
- Граница. Объект без метаданных живёт не дольше grace + интервал +
|
||||
проход: ~15 + 60 мин + секунды. Цена на рабочем стенде (2 тыс.
|
||||
объектов) — меньше секунды в час. При 100 тыс. — порядка минуты под
|
||||
лимитом 0,25 CPU: разбор XML списка botocore — Python. Замер и выбор
|
||||
интервала — `track2-reconcile-cost`.
|
||||
- Стенд отказов — `RECONCILER__INTERVAL_SECONDS: "0"` в
|
||||
`failures.compose.yml`. Иначе плановая сверка исправляла бы
|
||||
расхождения, которые тест внёс и ещё проверяет. Плановую сверку
|
||||
проверяет отдельный уборщик с интервалом 1 с (решение 11). `bench/`
|
||||
уборщика не запускает. У описанного в `bench.compose.yml` уборщика —
|
||||
тоже 0: профиль сверки `track2-reconcile-cost` задаст интервал сам.
|
||||
|
||||
*Альтернатива:* плановая сверка только с dry-run. Отвергнута: зомби
|
||||
оставались бы до ручного `--apply`. Предел и перепроверки делают
|
||||
автоматическое исправление безопасным. *Альтернатива:* первая сверка
|
||||
через интервал после старта. Отвергнута: частые пересоздания уборщика
|
||||
(`make run_docker`, обновление) откладывали бы её бесконечно.
|
||||
|
||||
### 10. Настройки
|
||||
|
||||
Секция `[reconciler]` (класс `Reconciler`, дельта
|
||||
`service-configuration`):
|
||||
- `interval_seconds` — float, ≥ 0, 3600;
|
||||
- `page_size` — int, 1–1000, 1000;
|
||||
- `max_changes` — int, ≥ 1, 100.
|
||||
|
||||
Разовая подмена — `RECONCILER__*`. Grace — `[cleaner]
|
||||
pending_grace_seconds`, одна ручка «свежести» на всю согласованность. Его
|
||||
проверка при старте уже есть и действует и на `reconcile`. Запись
|
||||
«Started cleaner» называет три новых значения и режим — сервис, `--once`
|
||||
или `reconcile` с `apply`. Строки — в `config_example.toml`.
|
||||
|
||||
*Альтернатива:* свой `grace_seconds` у сверки. Отвергнута: две ручки
|
||||
«свежести» разошлись бы. Для объектов без строки граница B не нужна, но
|
||||
меньший grace ничего не даёт, кроме риска.
|
||||
|
||||
### 11. Внедрение ошибок и тесты отказов
|
||||
|
||||
**Новые действия hook** (`fault_hook.py`, только stdlib, ключи S3 hook не
|
||||
получает):
|
||||
|
||||
| Действие | Что делает |
|
||||
|---|---|
|
||||
| `put-object <ключ>` | тело из stdin. `docker exec -i <проект>-api python -c …` — botocore образа с ключами API из окружения контейнера пишет объект мимо приложения. Ключ — только под `<FAULT_DATABASE>/attachments/`, символы `[A-Za-z0-9._/-]` |
|
||||
| `delete-object <ключ>` | `weed shell fs.rm /buckets/<bucket>/<ключ>` — мимо шлюза S3, с той же проверкой ключа |
|
||||
| `delete-row <id>`, `set-size <id> <байт>`, `age-row <id> <секунд>` | psql: удалить строку (неиспользуемого вложения), изменить `size_bytes`, сдвинуть `created_at` и `updated_at` назад вместе. CHECK и непомеченность `pending` сохраняются |
|
||||
| `lost-ids` | `id` строк с `lost_at` |
|
||||
| `fail-attachments mark <filename>` | новый режим: `UPDATE`, который ставит `lost_at` строке с этим `filename`, падает с 08006. Отдельный триггер `BEFORE UPDATE OF lost_at`, чтобы прежние режимы и их функция не зависели от новой колонки; `clear-fail-attachments` снимает и его |
|
||||
| `reconcile dry-run\|apply [<предел>]` | `docker compose -p … run --rm --no-deps -T cleaner reconcile [--apply] [--max-changes N]`: печатает записи процесса и строку `exit_code=<n>`, код hook — 0 |
|
||||
| `stop\|start cleaner` | сервис уборщика стенда (`start` — `up -d --wait --no-recreate`) |
|
||||
| `run-cleaner <секунд>` | отдельный уборщик `<проект>-cleaner-scheduled` (`run -d`, `RECONCILER__INTERVAL_SECONDS=1`) на N секунд, затем `docker stop` и его журнал; `run_failures.py` убирает его вместе с остальными |
|
||||
|
||||
Объекты нельзя состарить: `LastModified` ставит S3. Поэтому тест с
|
||||
объектом без метаданных ждёт G + 1 с. Строки состаривает `age-row`, и
|
||||
там ждать не нужно.
|
||||
|
||||
**Тесты** (маркер `fault`; G = 20 с — grace стенда):
|
||||
|
||||
| Тест | Сценарии | Ход |
|
||||
|---|---|---|
|
||||
| `test_reconcile_finds_and_fixes` | `storage-consistency` «Расхождения с обеих сторон найдены», «Исправление расхождений», «Повторная сверка»; `attachments` «Потерянный оригинал» | `with outage(stop cleaner)` → вложения A (в сообщении), B, C → `put-object` O (стандартный ключ), `delete-object` A, `delete-row` B, `set-size` C, загрузка P с `fail-attachments commit` (строка `pending` и объект) → ждать G + 1 → dry-run: у своих ключей и `id` — свои классы, `exit_code` 3, списки строк, объектов и `lost-ids` прежние, A — 500 → apply: O и объект B убраны, у P нет ни строки, ни объекта, A и C в `lost-ids`, A — 404, метаданные A равны ответу загрузки → повтор dry-run: своих расхождений нет, код соответствует записям |
|
||||
| `test_reconcile_keeps_fresh_used_and_unknown` | «Свежие не тронуты», «Используемое вложение не удаляется», «Чужой объект не удаляется» | U1 в сообщении — `age-row` и `delete-object`; чужой X (`…/attachments/x-<uuid>`) → ждать G + 1 → свежие: U2 с удалённым объектом и F (`put-object`) → apply: F и X на месте, U2 не помечено, U1 помечено, метаданные U1 — 200, история отдаёт U1, строк не убыло, X — «чужой», код 3 → уборка X и F через hook |
|
||||
| `test_reconcile_restored_original` | «Оригинал вернулся» | R: `age-row`, `delete-object`, apply → помечено → `put-object` R теми же байтами → apply → пометки нет, байты — 200 с тем же SHA-256 |
|
||||
| `test_reconcile_change_limit` | «Предел изменений» | L1–L3: `age-row`, `delete-object` → apply с пределом 2: код 3, `error` называет число не меньше 3 и предел 2, `lost-ids` без L → apply с пределом 100 → помечены все три |
|
||||
| `test_reconcile_object_storage_stopped` | «S3 недоступен во время сверки» | M: `age-row`, `delete-object` → `with outage(stop s3)`: apply — код 1, M не помечено → после возврата apply помечает |
|
||||
| `test_reconcile_interrupted_by_database` | «Прерванная сверка доводится повтором» | N1 (filename f), N2: `age-row`, `delete-object` → `fail-attachments mark f` → apply — код 1 → снять триггер → apply → оба помечены → dry-run без них |
|
||||
| `test_reconcile_under_load` | «Сверка под нагрузкой» | внесены 2 объекта без строки и 2 потери (`age-row`); 4 потока ~G + 15 с загружают ~100 KiB PNG из шума и отправляют сообщения со свежими `id`; поток сверки — apply раз в 3 с. В конце: внесённые исправлены, каждое 201-вложение скачивается с тем же SHA-256, каждое сообщение отдаёт свои `attachment_ids`, новые `lost-ids` (разность до и после) — только внесённые |
|
||||
| `test_scheduled_reconcile` | «Плановая сверка без команды» | S: `age-row`, `delete-object` → `run-cleaner 6` → в журнале «Finished reconcile pass», S в `lost-ids` |
|
||||
|
||||
Тесты фильтруют записи сверки по своим `id` и ключам. Остатки прежних
|
||||
тестов (их строки `pending`) могут попасть в отчёт и в код выхода,
|
||||
поэтому код сверяется с записями того же прохода, а не с числом.
|
||||
Уборщик стенда остановлен только в первом тесте и только на его окно
|
||||
(`with outage`). Новые тесты добавляют к `make failure_checks` около
|
||||
2,5–3 мин.
|
||||
|
||||
**Красный прогон до кода.** Новые тесты против прежнего кода — `5f4b9ff`,
|
||||
команды `reconcile` нет. Падают все восемь: hook возвращает код 2
|
||||
команды и ошибку разбора аргументов. Это доказательство, что тесты
|
||||
проверяют новое поведение. Сверка покрытия: новые сценарии
|
||||
`storage-consistency` и `attachments` синхронизируются в основные спеки в
|
||||
apply, как в прежних changes (`spec_coverage.py` читает только
|
||||
`openspec/specs/`).
|
||||
|
||||
### 12. Драйвер и evidence
|
||||
|
||||
Драйвер скилла (stdlib, Python 3.9), только стенд с LB. Разовая сверка —
|
||||
`docker compose run --rm --no-deps -e CLEANER__PENDING_GRACE_SECONDS=<g>
|
||||
cleaner reconcile …`, как у `upload-consistency`.
|
||||
|
||||
- **`reconcile-cycle`** → `evidence/reconcile/cycle.md`:
|
||||
1. исходный dry-run с grace по умолчанию: 0 расхождений, иначе код 2,
|
||||
«стенд не сведён — `make reconcile`»;
|
||||
2. синтетические участники и вложения через LB;
|
||||
3. расхождения:
|
||||
- объект без строки — `docker compose exec -T api python -c …` с
|
||||
ключами реплики;
|
||||
- удалённые объекты — `weed shell fs.rm`;
|
||||
- удалённая строка, изменённый размер — psql;
|
||||
- обрыв между объектом и фиксацией — временный триггер `commit` на
|
||||
уникальный `filename` рабочей базы, снимается в `finally` и в
|
||||
начале следующего прогона;
|
||||
- чужой объект;
|
||||
4. ожидание grace прогона (30 с), затем dry-run: таблица «класс → ключ
|
||||
→ `id` → возраст», снимки строк и объектов до и после совпали;
|
||||
5. байты потерянного — 500;
|
||||
6. `--apply`: таблица исправлений; байты — 404, метаданные — 200;
|
||||
история отдаёт `id`;
|
||||
7. повтор: исправимых 0, остался чужой. Его удаление оператором — шаг
|
||||
драйвера, затем повтор — код 0. Свежий объект не тронут, а после
|
||||
grace удалён;
|
||||
8. возврат оригинала: «оригинал вернулся», байты — 200 с тем же
|
||||
SHA-256.
|
||||
|
||||
Код 1 при любом расхождении. Токенов и секретов в выводе нет.
|
||||
- **`reconcile-stress`** → `evidence/reconcile/stress.md`:
|
||||
1. предусловие — dry-run с grace 20 с без расхождений (иначе код 2);
|
||||
2. внесённые расхождения;
|
||||
3. N клиентов M секунд загружают и отправляют через LB, поток сверки —
|
||||
`--apply` с grace 20 с раз в ~3 с;
|
||||
4. в конце — таблица: загрузки по кодам, сообщения, проходы и
|
||||
исправления по классам, скачивания с несовпавшим SHA-256 — 0,
|
||||
сообщения с недоступным вложением — 0, повтор — 0.
|
||||
|
||||
Это проверка корректности: тихий хост не нужен, паспорт хоста не
|
||||
снимается.
|
||||
- **Остальное evidence:**
|
||||
- `evidence/reconcile/service.md` — запись о старте с параметрами
|
||||
сверки, плановая сверка при старте, `docker compose stop cleaner` во
|
||||
время сверки при `pause s3` (время и код), отказ старта с
|
||||
`RECONCILER__PAGE_SIZE=5000`;
|
||||
- `evidence/s3/cleaner-list.md` — bootstrap с новой политикой, `make
|
||||
s3_check` со строками списка, окружение `s3-bootstrap` в `docker
|
||||
compose config`;
|
||||
- `evidence/migrations/lost-at.md` — ревизия с нуля, повтор, откат,
|
||||
снова `upgrade`, `--sql` с `lock_timeout`;
|
||||
- `evidence/tests/` — `make failure_checks`, `make student_test` через
|
||||
LB, `make test_isolated`.
|
||||
|
||||
Регресс: `make bench_rollout_quick` (замена `e1161f7` → новая
|
||||
ревизия), `bench_failover_quick`, `bench_restore_quick`, `bench_quick`.
|
||||
- **`REPORT.md`:**
|
||||
- раздел «Сверка хранилищ (трек 2)» — классы, правила, предел, права
|
||||
S3, ответы API, вопрос преподавателю;
|
||||
- строки таблицы доказательств уровня «5»;
|
||||
- ограничения (Risks ниже);
|
||||
- ответ на вопрос защиты «PUT прошёл, COMMIT нет» дополняется: зомби
|
||||
убирает сверка.
|
||||
|
||||
### 13. Граница с `track2-reconcile-cost`
|
||||
|
||||
| Здесь | В `track2-reconcile-cost` |
|
||||
|---|---|
|
||||
| одна стратегия: страницы LIST + одно выражение к БД на страницу, множество ключей, HEAD — только перепроверка найденного | `--strategy head` — HEAD на строку и выборка на объект (гипотеза 2) |
|
||||
| поверхностная сверка: наличие и размер из LIST | `--deep [--sample N]` — SHA-256 чтением объекта, класс «другой SHA-256» (гипотеза 3) |
|
||||
| `[reconciler] page_size`, `interval_seconds`, `max_changes` | ограничение скорости обхода и его влияние на p95 фоновой нагрузки (гипотеза 4); выбор интервала по замеру |
|
||||
| в итоге прохода — `listed_objects`, `checked_rows`, `duration_ms` | профиль `reconcile` стенда `bench/`: N = 10k / 100k мимо API, доли расхождений, k6, сэмплер, 3 повтора, A/A, графики (гипотеза 1) |
|
||||
| стресс `--apply` под загрузками — корректность (гипотеза 5) | выводы по гипотезам 1–5 и ограничения в `REPORT.md` |
|
||||
|
||||
### 14. Запись `KNOWN_ISSUES.md` о bootstrap
|
||||
|
||||
Причина найдена (Context): слоты томов на маленьком диске, а не
|
||||
повторное имя bucket. Reconciler bucket не создаёт и не удаляет. На
|
||||
`NoSuchBucket` он прерывает проход без изменений, поэтому чинить запись
|
||||
этому change не нужно.
|
||||
|
||||
В apply запись переписывается:
|
||||
- причина;
|
||||
- условие — диск, на котором `-volume.max=0` даёт мало слотов: tmpfs
|
||||
проб, а не volume стендов проекта;
|
||||
- проба на 16 ГБ;
|
||||
- предложение на будущее — `-master.volumeSizeLimitMB` меньше 1024 или
|
||||
явный `-volume.max` на маленьких дисках.
|
||||
|
||||
Запись остаётся открытой.
|
||||
|
||||
## Risks / Trade-offs
|
||||
|
||||
- **[Источник истины — PostgreSQL: база из старой копии или пустая при
|
||||
живом bucket]** → объекты новых вложений станут «объектами без
|
||||
метаданных», и до предела изменений сверка их удалит. По истине БД это
|
||||
верно. Опасно восстановление базы в живую (`pg_restore` поверх) при
|
||||
работающем уборщике: удалились бы объекты строк, которые ещё не
|
||||
восстановлены. Митигация:
|
||||
- предел 100;
|
||||
- grace по объекту на старые объекты не действует. Поэтому правило в
|
||||
`REPORT.md` и `docker.md`: на время восстановления базы уборщик
|
||||
останавливают (`docker compose stop cleaner`), после — сначала `make
|
||||
reconcile` (dry-run).
|
||||
- **[Чужой объект живёт, пока его не удалит оператор]** → код 3 и
|
||||
`warning` на каждом проходе плановой сверки — видно в журнале. Удалять
|
||||
непонятное опаснее.
|
||||
- **[Повреждение того же размера не видно]** → поверхностная сверка
|
||||
сравнивает только размер. SHA-256 — глубокая сверка следующего change.
|
||||
Скачивание отдаёт такие байты и сейчас: API сверяет только размер.
|
||||
- **[Память O(N) на ключи списка]** → ~15 МБ на 100 тыс. объектов при
|
||||
лимите уборщика 256 МБ. Замер — следующий change.
|
||||
- **[Плановая сверка задерживает уборку зависших загрузок на время
|
||||
прохода]** → на рабочем стенде — меньше секунды. На 100 тыс. — порядка
|
||||
минуты при grace 15 мин. Ограничение — в спеке и `REPORT.md`.
|
||||
- **[Пометка по ложному «нет объекта»]** при неполном списке S3 → HEAD
|
||||
перепроверяет каждый кандидат и проверяет bucket. Остаток — bucket
|
||||
пересоздан пустым или подменён между перепроверкой и `UPDATE`. Тогда
|
||||
пометка верна: объекта правда нет. Она снимается сама, если объект
|
||||
вернётся.
|
||||
- **[Две сверки одновременно]** — плановая и разовая → действия
|
||||
идемпотентны, отчёты могут разойтись в числах `fixed`. Блокировки
|
||||
нет: проходу пришлось бы держать соединение пула уборщика всё время.
|
||||
- **[Часы]** → `LastModified` — часы ВМ (S3), порог — часы контейнера
|
||||
уборщика, это одни часы. Точность `LastModified` — секунда, при grace
|
||||
900 с это ничтожно. `updated_at` строк пишут реплики. Консольный API на
|
||||
macOS расходится на секунды — меньше grace.
|
||||
- **[Ответ API для потерянного оригинала — трактовка контракта]** →
|
||||
вопрос преподавателю. Ответ меняет одну ветку `open_content`, сценарий
|
||||
и тест.
|
||||
- **[Старый образ уборщика после `make rolling_update`]** → сверки нет,
|
||||
как до change. Порядок обновления — решение 6, строка в `balancer.md`.
|
||||
- **[Тесты отказов дольше на ~3 мин]** → объекты нельзя состарить, ждать
|
||||
grace (20 с) нужно только тестам объектов без метаданных. Остальные
|
||||
состаривают строки.
|
||||
|
||||
## Migration Plan
|
||||
|
||||
1. Hook, стенд отказов и тесты раньше кода; красный прогон на нынешнем
|
||||
коде (`5f4b9ff`).
|
||||
2. Настройки `[reconciler]`, enum и DTO, константа предела записей.
|
||||
3. Модель и ревизия `lost_at`: с нуля, повтор, откат, снова `upgrade`,
|
||||
`--sql`.
|
||||
4. Клиент S3 (список, время объекта), repo, `AttachmentService` (404),
|
||||
сервис сверки, пакет `src/cleaner/` (команда, плановая сверка, коды).
|
||||
5. Bootstrap (политика, префикс, проверки), compose (`s3-bootstrap`),
|
||||
`config_example.toml`, `Makefile` (`reconcile`), `bench/`.
|
||||
6. Sync дельт в основные спеки и правка Purpose `storage-consistency`
|
||||
(«Сверку … добавят следующие changes» → сверка есть), полный `make
|
||||
failure_checks`.
|
||||
7. Драйвер, правила, AGENTS.md, `KNOWN_ISSUES.md`, `PLAN.md`; регресс;
|
||||
commit после подтверждения; evidence; `REPORT.md`.
|
||||
|
||||
На рабочем стенде — `make run_docker`: bootstrap обновит политику,
|
||||
`migrate` добавит колонку, реплики и уборщик пересоздаются. Без простоя
|
||||
— порядок решения 6. Первая плановая сверка — при старте нового
|
||||
уборщика. По Context расхождений на стенде нет, ожидается итог без
|
||||
находок.
|
||||
|
||||
Откат — по решению 6. Пометки остаются в колонке. Политика со списком
|
||||
прежнему уборщику не мешает.
|
||||
|
||||
## Open Questions
|
||||
|
||||
- **Ответ API на потерянный оригинал — вопрос преподавателю** (`PLAN.md`,
|
||||
`### track2-reconciler` → «Вопросы», п. 1). Контракт лабы 4 знает
|
||||
только `status=ready`. Есть три близких правила: «Отсутствующий вариант
|
||||
ready-объекта — 404», «404 — объекта нет или он чужой», «Неожиданное
|
||||
исключение — 500». По умолчанию до ответа (решение 5):
|
||||
- метаданные — 200;
|
||||
- байты — 404 после пометки, 500 до неё;
|
||||
- ссылка — 201.
|
||||
|
||||
Ответ меняет ветку `open_content` (и выборку вложений сообщения, если
|
||||
ссылку тоже запретить), сценарий `attachments` «Потерянный оригинал» и
|
||||
тест. Классы, правила безопасности, схема и задачи сверки не меняются.
|
||||
@@ -0,0 +1,146 @@
|
||||
# Proposal
|
||||
|
||||
## Why
|
||||
|
||||
Уровень «5», трек 2 «Согласованность двух хранилищ» (`README.md`):
|
||||
нужен повторяемый reconciler для объектов без метаданных и метаданных
|
||||
без объектов. Ошибки вносятся с обеих сторон, reconciler их находит и
|
||||
безопасно исправляет, с dry-run и повторным запуском. Свежие и
|
||||
используемые вложения он не удаляет. Сейчас уборщик идёт только от строк
|
||||
`pending`, и остаточные риски `upload-consistency` никто не находит
|
||||
(`REPORT.md`, «Ограничения»):
|
||||
- объект без строки — PUT-зомби после уборки, если компенсация не
|
||||
удалась;
|
||||
- строка `ready` без объекта — откат шага 2 уборщика при `mark_ready`
|
||||
прежней версии во время замены реплик.
|
||||
|
||||
Объект, удалённый мимо API, сейчас даёт 500 при каждом скачивании.
|
||||
|
||||
## What Changes
|
||||
|
||||
- **Сверка bucket и БД** — новый проход процесса уборщика. Он сравнивает
|
||||
объекты под `<база>/attachments/` с метаданными той же базы. Классы
|
||||
расхождений:
|
||||
- объект без метаданных;
|
||||
- метаданные `ready` без объекта;
|
||||
- другой размер;
|
||||
- зависшая загрузка;
|
||||
- вернувшийся оригинал;
|
||||
- чужой объект (ключ, которого API не пишет).
|
||||
- **Разовый проход** — `python -m src.cleaner reconcile` (`make
|
||||
reconcile`). По умолчанию это dry-run: отчёт по каждому расхождению
|
||||
(класс, ключ, `id`, возраст) и итог по классам. С `--apply`:
|
||||
- объект без метаданных удаляется;
|
||||
- метаданные без объекта или с другим размером помечаются «оригинал
|
||||
потерян»;
|
||||
- зависшая загрузка убирается порядком уборщика;
|
||||
- с вернувшегося оригинала пометка снимается;
|
||||
- чужой объект попадает только в отчёт.
|
||||
|
||||
Коды выхода: 0 — расхождений нет, 3 — остались, 1 — проход прерван,
|
||||
2 — конфигурация. Повтор после исправления находит 0.
|
||||
- **Плановая сверка** в сервисе `cleaner`: при старте и раз в
|
||||
`[reconciler] interval_seconds` (3600 с, 0 — выключена), с
|
||||
исправлением. Так объект без строки живёт не дольше grace + интервал,
|
||||
а не до ручного запуска.
|
||||
- **Безопасность:**
|
||||
- grace уборщика (900 с) по времени объекта в S3 и по времени
|
||||
метаданных;
|
||||
- перепроверка в БД и в S3 непосредственно перед каждым действием;
|
||||
- объект, на который ссылается строка, и строки `ready` не удаляются
|
||||
никогда;
|
||||
- используемое вложение только помечается;
|
||||
- отсутствие объекта не подтверждается без bucket;
|
||||
- предел изменений за проход `[reconciler] max_changes` (100): больше
|
||||
— ни одного изменения и код 3.
|
||||
- **Потерянный оригинал.** Колонка `attachments.lost_at`, миграция
|
||||
только расширяет схему. Скачивание помеченного вложения — 404
|
||||
`not_found` вместо 500. Метаданные — 200, как раньше, ссылка в
|
||||
сообщении — как раньше. Неоднозначность контракта — вопрос
|
||||
преподавателю (`PLAN.md`), это вариант по умолчанию.
|
||||
- **Права S3 пользователя `cleaner`**: `s3:ListBucket` только с
|
||||
префиксом `<база>/attachments/` (условие `s3:prefix`, проверено на
|
||||
SeaweedFS 4.48). Список всего bucket, других префиксов и bucket-ов —
|
||||
403. Bootstrap и `make s3_check` проверяют это.
|
||||
- **Тесты отказов** (`make failure_checks`). Hook вносит расхождения:
|
||||
- объект мимо API;
|
||||
- удалённый объект;
|
||||
- удалённая или изменённая строка;
|
||||
- обрыв загрузки между записью объекта и фиксацией.
|
||||
|
||||
Ещё hook запускает разовую сверку и уборщика с плановой сверкой.
|
||||
Проверки: dry-run, apply, повтор, свежие и используемые, чужой
|
||||
объект, предел, отказы S3 и БД, прерванный apply, сверка под
|
||||
нагрузкой.
|
||||
- **Драйвер и evidence** `evidence/reconcile/`:
|
||||
- `reconcile-cycle` на рабочем стенде — dry-run, apply, повтор = 0,
|
||||
возврат оригинала;
|
||||
- `reconcile-stress` — `--apply` под одновременными загрузками и
|
||||
отправками, затем каждое подтверждённое вложение скачивается с тем
|
||||
же SHA-256;
|
||||
- процесс сервиса, права S3, миграция.
|
||||
|
||||
Не входит — `track2-reconcile-cost`. Здесь одна стратегия: страницы
|
||||
LIST по 1000 ключей и один запрос к БД на страницу, а точечные HEAD —
|
||||
только для перепроверки найденного. Сверка поверхностная: наличие и
|
||||
размер из LIST. Следующий change добавит:
|
||||
- стратегию «HEAD на строку» (гипотеза 2);
|
||||
- глубокую сверку SHA-256, выборочную или полную, и класс «другой
|
||||
SHA-256» (гипотеза 3);
|
||||
- ограничение скорости обхода (гипотеза 4);
|
||||
- профиль `reconcile` стенда `bench/`, замеры, графики и выводы по
|
||||
гипотезам 1–4.
|
||||
|
||||
Гипотезу 5 («ничего подтверждённого не удалено») проверяет стресс этого
|
||||
change. Ещё не входят presigned upload, превью и 202 (лаба 5), отчёт и
|
||||
PR (этап 7).
|
||||
|
||||
## Capabilities
|
||||
|
||||
### New Capabilities
|
||||
|
||||
Нет.
|
||||
|
||||
### Modified Capabilities
|
||||
|
||||
- `storage-consistency`: новые требования — сверка bucket и БД, её
|
||||
безопасность, потерянный оригинал, отказы хранилищ во время сверки,
|
||||
плановая сверка; у уборщика объект без строки больше не остаётся
|
||||
навсегда.
|
||||
- `attachments`: скачивание потерянного оригинала — 404, до пометки —
|
||||
500.
|
||||
- `object-storage`: список объектов у пользователя уборщика только по
|
||||
префиксу вложений своей базы, его проверка в bootstrap и `make
|
||||
s3_check`, список объектов в клиенте.
|
||||
- `service-configuration`: секция `[reconciler]`.
|
||||
- `service-logging`: журнал сверки и запись о потерянном оригинале.
|
||||
- `graceful-shutdown`: остановка уборщика посреди сверки.
|
||||
- `student-tests`: действия hook для расхождений и сверки, уборщик
|
||||
стенда отказов без плановой сверки.
|
||||
|
||||
## Impact
|
||||
|
||||
- Код:
|
||||
- новый `src/core/services/attachment_reconcile.py`;
|
||||
- `src/core/repos/attachment.py` и `attachment_object.py` — выборки,
|
||||
пометка, список объектов;
|
||||
- `src/infra/s3/client.py` — список страницами, время объекта;
|
||||
- `src/cleaner/` — команда `reconcile`, плановая сверка, коды выхода;
|
||||
- `src/core/services/attachment.py` — 404 потерянного оригинала;
|
||||
- `src/config/settings.py` — `[reconciler]`;
|
||||
- DTO и enum, модель `Attachment` и ревизия alembic.
|
||||
- Стенд: `infra/s3/bootstrap.sh`, `docker-compose.yml` (префикс списка у
|
||||
`s3-bootstrap`), `config_example.toml`, `Makefile` (`reconcile`),
|
||||
`student-tests/failures.compose.yml`.
|
||||
- Тесты: `student-tests/test_failures.py`, `fault_hook.py`,
|
||||
`run_failures.py`.
|
||||
- Документы: скилл `run-mtusi-messenger` (`reconcile-cycle`,
|
||||
`reconcile-stress`, строки `s3-check`). Правила `service-layer.md`,
|
||||
`repo-layer.md`, `dto.md`, `infra.md`, `migrations.md`, `docker.md`,
|
||||
`settings.md`, `logging.md`, `run-modes.md`, `api-contract.md`,
|
||||
`student-tests.md`, `balancer.md`. Ещё AGENTS.md, `REPORT.md`,
|
||||
`PLAN.md` и `KNOWN_ISSUES.md` — запись о bootstrap: причина найдена
|
||||
пробой, design, Context.
|
||||
- Регресс: `make failure_checks` дольше ~3 мин, `make s3_check` (новые
|
||||
строки), быстрые профили `bench/` (`bench_rollout_quick` — новая
|
||||
миграция), `make test_isolated`, `make test-persistence`.
|
||||
@@ -0,0 +1,58 @@
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: Скачивание оригинала
|
||||
|
||||
`GET /api/v1/attachments/{attachment_id}/content` SHALL отвечать 200 с
|
||||
байтами оригинала без изменений: их размер и SHA-256 равны `size_bytes`
|
||||
и `sha256` вложения. Заголовки ответа:
|
||||
- `Content-Type` — `content_type` вложения без параметров;
|
||||
- `Content-Length` — размер оригинала;
|
||||
- `X-Content-Type-Options: nosniff`.
|
||||
|
||||
Байты SHALL отдавать API, ответ MUST NOT быть перенаправлением.
|
||||
Параметр `variant` SHALL принимать только `original`, это и значение по
|
||||
умолчанию. Любое другое значение — 400 `invalid_request`. Ключ объекта,
|
||||
адрес и учётные данные S3 MUST NOT попадать ни в тело, ни в заголовки
|
||||
ответов API.
|
||||
|
||||
Если у готового вложения нет объекта в S3 или его размер не равен
|
||||
`size_bytes`, а сверка хранилищ это ещё не подтвердила, это
|
||||
непредвиденное расхождение. Скачивание SHALL отвечать 500
|
||||
`internal_error` без деталей, причина пишется в журнал. Если сверка уже
|
||||
пометила оригинал потерянным (capability `storage-consistency`,
|
||||
«Потерянный оригинал»), скачивание SHALL отвечать участнику 404
|
||||
`not_found`, как отсутствующий вариант готового объекта, — без
|
||||
обращения к S3. Метаданные такого вложения SHALL отвечать 200 тем же
|
||||
`Attachment`, что и до пометки. Ссылка на него в новом сообщении
|
||||
принимается, как на любое готовое вложение. Когда сверка снимает
|
||||
пометку, скачивание снова отдаёт байты.
|
||||
|
||||
#### Scenario: Побайтный оригинал
|
||||
|
||||
- **WHEN** Боб скачивает PNG и JPEG, загруженные Алисой
|
||||
- **THEN** каждый ответ 200, не перенаправление, байты совпадают с
|
||||
загруженными, `Content-Type` — `image/png` и `image/jpeg`,
|
||||
`Content-Length` равен размеру, есть `X-Content-Type-Options: nosniff`
|
||||
|
||||
#### Scenario: Вариант original
|
||||
|
||||
- **WHEN** участник скачивает вложение с `variant=original`, а затем с
|
||||
`variant=thumbnail` и с пустым `variant`
|
||||
- **THEN** первый ответ 200 с теми же байтами, остальные — 400
|
||||
`invalid_request`
|
||||
|
||||
#### Scenario: Без следов хранилища в ответе
|
||||
|
||||
- **WHEN** участник загружает вложение, читает метаданные и скачивает
|
||||
байты
|
||||
- **THEN** в телах ответов нет полей вне схемы контракта, а в
|
||||
заголовках нет `Location` и заголовков `x-amz-*`
|
||||
|
||||
#### Scenario: Потерянный оригинал
|
||||
|
||||
- **WHEN** объект готового вложения удалён мимо API, затем сверка с
|
||||
`--apply` пометила его оригинал потерянным
|
||||
- **THEN** скачивание до сверки — 500 `internal_error`, после неё — 404
|
||||
`not_found`
|
||||
- **AND** метаданные и до, и после — 200 с тем же JSON, что у ответа на
|
||||
загрузку
|
||||
@@ -0,0 +1,36 @@
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: Остановка уборщика
|
||||
|
||||
По SIGTERM уборщик незавершённых загрузок (capability
|
||||
`storage-consistency`) SHALL довести текущий шаг уборки загрузки до
|
||||
конца или до отката и больше новых шагов не начинать. Загрузка,
|
||||
остановленная между шагами, остаётся в состоянии, из которого её
|
||||
доводит следующий проход.
|
||||
|
||||
Так же — во время сверки bucket и БД. Текущий вызов S3 или шаг с
|
||||
PostgreSQL доводится до конца или до отката. Новые страницы списка и
|
||||
новые действия не начинаются. Сверку, прерванную сигналом, доводит
|
||||
следующий проход, как прерванную отказом.
|
||||
|
||||
Затем сервис уборщика SHALL выйти с кодом 0 раньше срока остановки
|
||||
контейнера (10 с), а не по SIGKILL. Разовый проход сверки, прерванный
|
||||
сигналом, SHALL выходить с кодом 1: проход не завершён. Сигнал во время
|
||||
старта процесса SHALL завершать его с кодом 0 без traceback, как у API
|
||||
(требование «Остановка во время старта»). Остановка SHALL быть видна в
|
||||
журнале записью об остановке уборщика.
|
||||
|
||||
#### Scenario: docker stop уборщика
|
||||
|
||||
- **WHEN** выполняется `docker compose stop cleaner` для работающего
|
||||
уборщика
|
||||
- **THEN** команда завершается быстрее 10 с, код выхода контейнера 0, а
|
||||
в журнале есть запись об остановке
|
||||
|
||||
#### Scenario: docker stop во время сверки
|
||||
|
||||
- **WHEN** `docker compose stop cleaner` выполняется, пока идёт проход
|
||||
сверки, а вызов S3 в нём ждёт ответа
|
||||
- **THEN** команда завершается быстрее 10 с, код выхода контейнера 0, а
|
||||
в журнале — итог сверки с причиной прерывания «остановка» и запись об
|
||||
остановке уборщика
|
||||
@@ -0,0 +1,159 @@
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: Ограниченные учётные данные уборщика
|
||||
|
||||
У уборщика (capability `storage-consistency`) SHALL быть свои учётные
|
||||
данные S3, отдельные от учётных данных API и административных.
|
||||
Пользователю уборщика SHALL быть разрешены только:
|
||||
- чтение и удаление объектов своего bucket;
|
||||
- список объектов своего bucket с префиксом вложений своей базы,
|
||||
`<имя базы>/attachments/`, — для сверки bucket и БД.
|
||||
|
||||
Префикс задаёт bootstrap по имени базы стенда.
|
||||
|
||||
Пользователю уборщика MUST NOT быть разрешены:
|
||||
- запись объектов;
|
||||
- список объектов без этого префикса или с другим префиксом, в том числе
|
||||
с префиксом другой базы;
|
||||
- операции с bucket: создание, удаление, политика, ACL;
|
||||
- публичный ACL объекта;
|
||||
- управление учётными записями;
|
||||
- любой доступ к другим bucket.
|
||||
|
||||
Ключи уборщика MUST NOT передаваться репликам API. Уборщик MUST NOT
|
||||
получать ключи API, административные ключи S3 и ключ подписи.
|
||||
|
||||
#### Scenario: Работа уборщика с объектами
|
||||
|
||||
- **WHEN** ключом API записан объект, а ключом уборщика он прочитан,
|
||||
удалён и удалён ещё раз, и запрошен список объектов с префиксом
|
||||
вложений базы
|
||||
- **THEN** чтение отдаёт те же байты, оба удаления успешны, объекта
|
||||
после них нет, а список отвечает 200
|
||||
|
||||
#### Scenario: Запрещённые операции уборщика
|
||||
|
||||
- **WHEN** ключом уборщика запрашиваются:
|
||||
- запись объекта;
|
||||
- список объектов всего bucket и с префиксом, не принадлежащим
|
||||
вложениям его базы;
|
||||
- создание и удаление bucket, политика и ACL bucket;
|
||||
- публичный ACL объекта;
|
||||
- объект другого bucket и его список
|
||||
- **THEN** каждый запрос получает 403, а bucket и его доступ не
|
||||
меняются
|
||||
|
||||
### Requirement: Проверка приватности вне API
|
||||
|
||||
Приватность bucket и права ключей API и уборщика SHALL проверяться без
|
||||
участия приложения двумя способами.
|
||||
|
||||
1. Каждый запуск bootstrap:
|
||||
- ключ API записывает и читает проверочный объект и получает отказ на
|
||||
список и на создание bucket;
|
||||
- ключ уборщика читает и удаляет этот объект. Он получает отказ на
|
||||
запись и на список всего bucket, а список с префиксом вложений своей
|
||||
базы у него проходит;
|
||||
- аноним получает отказ на чтение существующего объекта и на список.
|
||||
|
||||
При нарушении bootstrap завершается с ненулевым кодом, и реплики API
|
||||
не стартуют.
|
||||
2. Отдельная команда `make s3_check` на запущенном стенде. Она
|
||||
повторяет проверки bootstrap и добавляет:
|
||||
- анонимные запросы с хоста и из сети стенда;
|
||||
- запросы ключей API и уборщика к чужому bucket;
|
||||
- административные запросы ключей API и уборщика;
|
||||
- запись ключом уборщика;
|
||||
- его список всего bucket и с чужим префиксом — отказ, с префиксом
|
||||
вложений своей базы — 200.
|
||||
|
||||
Команда SHALL печатать по каждой проверке ожидаемый и полученный код
|
||||
ответа без секретов. При любом нарушении код выхода SHALL быть
|
||||
ненулевым. Свои проверочные объекты и bucket команда SHALL удалять.
|
||||
|
||||
#### Scenario: Проверка командой
|
||||
|
||||
- **WHEN** на запущенном стенде выполняется `make s3_check`
|
||||
- **THEN** каждая проверка напечатана с полученным кодом ответа, в том
|
||||
числе проверки списка ключом уборщика по своему и чужому префиксу, код
|
||||
выхода 0, а проверочных объектов и bucket после команды нет
|
||||
|
||||
#### Scenario: Bucket стал публичным
|
||||
|
||||
- **WHEN** на bucket открыт анонимный доступ на чтение, например
|
||||
административной командой мимо bootstrap
|
||||
- **THEN** `make s3_check` завершается с ненулевым кодом и называет
|
||||
нарушенную проверку, а следующий запуск bootstrap снова закрывает
|
||||
доступ
|
||||
|
||||
### Requirement: Клиент хранилища в приложении
|
||||
|
||||
Процессы приложения SHALL обращаться к S3 с учётными данными своей роли
|
||||
из секции `[s3]`: реплики API — ключами пользователя API, уборщик —
|
||||
ключами пользователя уборщика. Клиент SHALL уметь:
|
||||
- записать объект;
|
||||
- прочитать его потоком;
|
||||
- получить метаданные;
|
||||
- удалить объект;
|
||||
- перечислить объекты с заданным префиксом страницами, с размером и
|
||||
временем изменения каждого объекта.
|
||||
|
||||
Удаление отсутствующего объекта — не ошибка. Каждый вызов, в том числе
|
||||
каждая страница списка, SHALL быть ограничен сроком из настроек. После
|
||||
отказа или истечения срока вызов MUST NOT повторяться автоматически.
|
||||
|
||||
Ошибкой недоступности, которую API отдаёт как 503 `unavailable` в
|
||||
формате контракта, SHALL заканчиваться вызов, если S3:
|
||||
- недоступен;
|
||||
- не ответил за срок;
|
||||
- отклонил учётные данные;
|
||||
- отказал ключу в доступе или не нашёл bucket.
|
||||
|
||||
Такой вызов MUST NOT давать 500 или зависать. Отсутствующий объект SHALL
|
||||
отличаться от недоступности. Отсутствующий bucket MUST NOT выдаваться
|
||||
за отсутствующий объект у записи, чтения, удаления и списка: список без
|
||||
bucket — ошибка, а не пустая страница. После возврата S3 вызовы SHALL
|
||||
проходить без перезапуска приложения. Соединения с S3 SHALL открываться
|
||||
при первом вызове, а при остановке сервиса клиент SHALL закрываться.
|
||||
|
||||
Ключ объекта SHALL начинаться с имени базы PostgreSQL процесса и `/`.
|
||||
Так объекты прогона на временной базе (`make test_isolated`) отделены
|
||||
от объектов рабочей базы.
|
||||
|
||||
#### Scenario: S3 остановлен
|
||||
|
||||
- **WHEN** S3 остановлен, и приложение записывает объект
|
||||
- **THEN** вызов за доли секунды завершается ошибкой недоступности, без
|
||||
повторов
|
||||
|
||||
#### Scenario: S3 завис
|
||||
|
||||
- **WHEN** контейнер S3 заморожен (`docker pause`), и приложение
|
||||
записывает объект
|
||||
- **THEN** вызов завершается ошибкой недоступности не позже срока
|
||||
вызова
|
||||
|
||||
#### Scenario: S3 вернулся
|
||||
|
||||
- **WHEN** S3 снова доступен, а приложение не перезапускалось
|
||||
- **THEN** следующий вызов проходит
|
||||
|
||||
#### Scenario: Объекта нет
|
||||
|
||||
- **WHEN** приложение читает ключ, которого в bucket нет
|
||||
- **THEN** клиент сообщает, что объекта нет, а не недоступность S3
|
||||
|
||||
#### Scenario: Bucket нет
|
||||
|
||||
- **WHEN** bucket приложения удалён мимо bootstrap, и приложение
|
||||
записывает, читает или удаляет объект либо запрашивает список объектов
|
||||
- **THEN** каждый вызов завершается ошибкой недоступности, а не
|
||||
сообщением «объекта нет» и не пустым списком, и в журнале есть запись
|
||||
уровня `error`
|
||||
|
||||
#### Scenario: Учётные данные отклонены
|
||||
|
||||
- **WHEN** секрет API у приложения не совпадает с секретом на сервере
|
||||
S3
|
||||
- **THEN** вызов завершается ошибкой недоступности, а в журнале есть
|
||||
запись уровня `error` без секрета
|
||||
@@ -0,0 +1,38 @@
|
||||
## ADDED Requirements
|
||||
|
||||
### 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** уборщик не стартует, в журнале — ошибка проверки настроек с
|
||||
именем поля
|
||||
@@ -0,0 +1,44 @@
|
||||
## ADDED Requirements
|
||||
|
||||
### 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`
|
||||
@@ -0,0 +1,290 @@
|
||||
## ADDED Requirements
|
||||
|
||||
### 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** не позже интервала с запасом вложение помечено потерянным
|
||||
без разового прохода, а в журнале уборщика есть итог сверки
|
||||
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: Уборщик незавершённых загрузок
|
||||
|
||||
Незавершённую загрузку SHALL убирать уборщик — отдельный процесс стенда
|
||||
(capability `container-run`), а не реплики API. Незавершённая загрузка —
|
||||
вложение, которое осталось в статусе «загружается» (capability
|
||||
`attachments`, «Порядок записи»).
|
||||
|
||||
Уборщик SHALL проходить по незавершённым загрузкам не реже чем раз в
|
||||
`[cleaner] interval_seconds`. Каждую загрузку, метаданные которой
|
||||
записаны раньше чем `[cleaner] pending_grace_seconds` назад (grace
|
||||
period), он SHALL убирать по шагам:
|
||||
1. пометить её метаданные как убираемые и зафиксировать пометку
|
||||
(требование «Безопасность уборки»);
|
||||
2. удалить объект по ключу из её метаданных; отсутствие объекта — не
|
||||
ошибка;
|
||||
3. только после подтверждённого удаления объекта — удалить метаданные.
|
||||
|
||||
Каждый шаг SHALL быть безопасно повторяемым: проход, прерванный на
|
||||
любом шаге, доводит следующий. После уборки у вложения не остаётся ни
|
||||
метаданных, ни объекта. Объект вложения без метаданных уборка MUST NOT
|
||||
оставлять: метаданные удаляются последними.
|
||||
|
||||
Ограничение называется в `REPORT.md`. Объект может остаться без
|
||||
метаданных, если процесс API заморожен дольше grace посреди записи
|
||||
объекта. После разморозки он дописывает объект уже убранной загрузки, а
|
||||
удалить его не может: запись объекта завершилась для API ошибкой по
|
||||
сроку, или не удалось удаление при компенсации. Такой объект находит и
|
||||
удаляет сверка bucket и БД (требование «Сверка bucket и БД»), когда он
|
||||
старше grace. На стенде это происходит не позже следующей плановой
|
||||
сверки (требование «Плановая сверка»).
|
||||
|
||||
#### Scenario: Зависшая загрузка убрана
|
||||
|
||||
- **WHEN** загрузка оборвалась после записи метаданных: S3 был
|
||||
остановлен или заморожен на время записи объекта, либо PostgreSQL
|
||||
отказал при фиксации `ready`. С записи метаданных прошло больше grace,
|
||||
S3 и PostgreSQL доступны
|
||||
- **THEN** ни метаданных, ни объекта этого вложения нет, а в bucket нет
|
||||
объектов вложений без метаданных
|
||||
|
||||
#### Scenario: Объект без фиксации убран
|
||||
|
||||
- **WHEN** объект вложения записан в S3, а процесс API убит до фиксации
|
||||
`ready`
|
||||
- **THEN** до истечения grace есть и метаданные в статусе
|
||||
«загружается», и объект, а после него нет ни того, ни другого, и в
|
||||
bucket нет объектов вложений без метаданных
|
||||
@@ -0,0 +1,102 @@
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: Проверки отказов на отдельном стенде
|
||||
|
||||
Сценарии отказов SHALL проверяться автоматически одной командой
|
||||
`make failure_checks`:
|
||||
- `sessions`: «Истёкший токен», «Срок не продлевается», «БД остановлена при
|
||||
запросе с токеном»;
|
||||
- `data-storage`: «Сбой при добавлении участников», «БД остановлена»,
|
||||
«БД вернулась», «Соединения исчерпаны»;
|
||||
- `health`: «Хранилище не готово», «Кэш недоступен», «Хранилище
|
||||
объектов недоступно»;
|
||||
- `chat-cache`: «Valkey остановлен», «Valkey завис», «Valkey вернулся»,
|
||||
«Очистка кэша»;
|
||||
- `idempotency`: «Сбой при записи сообщения», «Отказ БД при отправке»,
|
||||
«Ключ после срока»;
|
||||
- `api-conventions`: «Лимит одновременных загрузок»;
|
||||
- `attachments`: «Запись в S3 не удалась», «Отклонённая загрузка ничего
|
||||
не оставляет», «S3 остановлен», «S3 завис», «Незавершённая загрузка не
|
||||
видна», «Сбой записи метаданных», «Фиксация ready не удалась», «Обрыв
|
||||
передачи тела», «Отказ раньше очереди», «Все места заняты», «Очередь
|
||||
ожидания полна», «Ожидание места», «Место освобождается», «Медленный
|
||||
клиент», «Медленная передача в срок», «Потерянный оригинал»;
|
||||
- `storage-consistency`: все сценарии.
|
||||
|
||||
Команда SHALL:
|
||||
- собрать образ из рабочего дерева;
|
||||
- поднять отдельный стенд со своими PostgreSQL, Valkey и S3, применить
|
||||
миграции и bootstrap S3;
|
||||
- запустить три API:
|
||||
- с настройками по умолчанию;
|
||||
- «тесный» — с коротким сроком сессии и ключа идемпотентности и пулом
|
||||
из одного соединения;
|
||||
- «узкий по загрузкам» — с одним местом загрузки, одной загрузкой в
|
||||
очереди, коротким сроком ожидания места и коротким сроком тела. Их
|
||||
значения SHALL передаваться проверкам;
|
||||
- запустить уборщика с коротким grace и интервалом, сравнимыми со
|
||||
временем теста, без плановой сверки, и передать их значения
|
||||
проверкам. Grace при этом SHALL проходить проверку границы живой
|
||||
загрузки (`service-configuration`, «Параметры уборщика»). Сверку
|
||||
проверки запускают сами, и плановая сверка не меняет стенд у них за
|
||||
спиной;
|
||||
- выполнить проверки отказов;
|
||||
- удалить стенд вместе с его данными при любом исходе.
|
||||
|
||||
Hook стенда отказов SHALL уметь:
|
||||
- сообщить вложения стенда в PostgreSQL с их статусами, `id` последнего
|
||||
вложения в статусе «загружается» и `id` вложений с потерянным
|
||||
оригиналом;
|
||||
- сообщить, у каких вложений есть объект в bucket стенда, — по самим
|
||||
объектам, а не по каталогам хранилища;
|
||||
- внедрить отказ PostgreSQL:
|
||||
- при записи метаданных загрузки с заданным `filename`;
|
||||
- при фиксации её `ready`, и задержать такую фиксацию;
|
||||
- при пометке потерянного оригинала такого вложения;
|
||||
- убить и снова запустить обычный API стенда;
|
||||
- внести расхождения хранилищ:
|
||||
- записать объект в bucket стенда мимо API и удалить объект мимо API —
|
||||
только под префиксом вложений базы стенда;
|
||||
- удалить метаданные вложения, изменить в них размер и сдвинуть их
|
||||
время в прошлое;
|
||||
- выполнить разовую сверку — без изменений или с `--apply`, с заданным
|
||||
пределом изменений — и вернуть её записи и код выхода;
|
||||
- остановить и запустить уборщика стенда, а также запустить отдельного
|
||||
уборщика с коротким интервалом плановой сверки на заданное время и
|
||||
вернуть его журнал.
|
||||
|
||||
Других сведений о хранилищах проверки вложений не получают. Объекты без
|
||||
метаданных проверка находит сравнением двух списков: вложений и
|
||||
объектов. Ключи доступа S3 hook не получает и не печатает: объект мимо
|
||||
API записывает процесс в контейнере стенда своими ключами.
|
||||
|
||||
Порты PostgreSQL, Valkey и S3 этого стенда MUST NOT публиковаться на
|
||||
хосте, API — только на `127.0.0.1`. Рабочий стенд, его база, кэш,
|
||||
хранилище объектов и контейнеры MUST NOT затрагиваться. Код выхода
|
||||
SHALL быть ненулевым, если не прошла хотя бы одна проверка или уборка.
|
||||
Параллельный запуск двух прогонов не поддерживается: уборка хвоста в
|
||||
начале второго удаляет стенд первого.
|
||||
|
||||
#### Scenario: Успешный прогон
|
||||
|
||||
- **WHEN** рабочий стенд запущен, и выполнен `make failure_checks`
|
||||
- **THEN** все проверки отказов прошли, код выхода 0, контейнеров и
|
||||
volumes стенда отказов после команды нет, а у контейнеров рабочего
|
||||
стенда прежнее время старта, и рабочий API отвечает
|
||||
|
||||
#### Scenario: Упавшая проверка
|
||||
|
||||
- **WHEN** во время `make failure_checks` падает хотя бы одна проверка
|
||||
- **THEN** код выхода ненулевой, журналы API и уборщика стенда отказов
|
||||
выведены, стенд отказов удалён
|
||||
|
||||
#### Scenario: Прерывание
|
||||
|
||||
- **WHEN** `make failure_checks` прерван Ctrl+C
|
||||
- **THEN** стенд отказов остановлен и удалён вместе с volumes
|
||||
|
||||
#### Scenario: Хвост прошлого прогона
|
||||
|
||||
- **WHEN** контейнеры или volumes стенда отказов остались от прогона,
|
||||
убитого без уборки
|
||||
- **THEN** следующий `make failure_checks` удаляет их и начинает заново
|
||||
@@ -0,0 +1,398 @@
|
||||
# Tasks
|
||||
|
||||
Как строить — `design.md` (дальше «решение N»), что должно получиться —
|
||||
дельты в `specs/`. Порядок — design, Migration Plan, но тесты и hook
|
||||
пишутся первыми: так красный прогон снимается без checkout и stash.
|
||||
Перед первым файлом слоя прочитать его правило: `service-layer.md`,
|
||||
`repo-layer.md`, `dto.md`, `infra.md`, `migrations.md`, `logging.md`,
|
||||
`settings.md`, `run-modes.md`, `docker.md`, `balancer.md`,
|
||||
`student-tests.md`, `api-contract.md`, `bench.md`.
|
||||
|
||||
Commit делает основная сессия после подтверждения пользователя
|
||||
(`bench.md`, «Измеренное состояние — commit»). Evidence — только с
|
||||
закоммиченного кода. Временные проекты compose, их volumes, сети и
|
||||
образы убираются сразу после проверки. Список volumes сверяется с
|
||||
исходным: `docker volume ls -q | sort | shasum`. Volumes
|
||||
`mtusi-lab4_postgres_data` и `mtusi-lab4_s3_data` не удаляются никогда.
|
||||
|
||||
Вопрос преподавателю об ответе API на потерянный оригинал открыт
|
||||
(`PLAN.md`, `### track2-reconciler` → «Вопросы», п. 1). Строится вариант
|
||||
по умолчанию: метаданные — 200, байты — 404 после пометки и 500 до неё,
|
||||
ссылка — 201. Ответ «иначе» меняет задачи 5.1 и 1.3 (тест «Потерянный
|
||||
оригинал») и сценарий `attachments`, остальное — нет.
|
||||
|
||||
Ожидаемо красное по ходу работы, остальное разбирается по AGENTS.md:
|
||||
- между задачами 1.3 и 9.1 сверка покрытия в `make student_test` падает
|
||||
на маркерах новых сценариев («marker points to unknown scenario»);
|
||||
- до задачи 12.2 — `test_exclusion_evidence_exists` не меняется:
|
||||
исключений этот change не добавляет.
|
||||
|
||||
## 1. Hook, стенд отказов, тесты и красный прогон
|
||||
|
||||
- [ ] 1.1 `student-tests/fault_hook.py` по решению 11 (только stdlib,
|
||||
синтаксис 3.9, docstring — новые действия):
|
||||
- `put-object <ключ>`: тело из stdin, `docker exec -i <проект>-api
|
||||
python -c …` — botocore образа с ключами API из окружения
|
||||
контейнера;
|
||||
- `delete-object <ключ>`: `weed shell fs.rm /buckets/<bucket>/<ключ>`.
|
||||
Ключ у обоих — только под `<FAULT_DATABASE>/attachments/`, символы
|
||||
`[A-Za-z0-9._/-]`, иначе код 2;
|
||||
- `delete-row`, `set-size`, `age-row`, `lost-ids` — psql, значения
|
||||
только переменными psql;
|
||||
- `fail-attachments mark <filename>` — отдельный триггер `BEFORE UPDATE
|
||||
OF lost_at`. Его снимает `clear-fail-attachments`, прежние режимы
|
||||
новой колонки не касаются;
|
||||
- `reconcile dry-run|apply [<предел>]`: `compose_run` проекта,
|
||||
записи процесса и строка `exit_code=<n>`, код hook — 0;
|
||||
- `stop|start cleaner`;
|
||||
- `run-cleaner <секунд>`: контейнер `<проект>-cleaner-scheduled` с
|
||||
`RECONCILER__INTERVAL_SECONDS=1`, затем `docker stop`, журнал и
|
||||
`docker rm`.
|
||||
|
||||
Ключей и секретов hook не печатает и не получает. Проверка: `make
|
||||
lint`; поведение — 1.4 и группа 9.
|
||||
- [ ] 1.2 Стенд отказов:
|
||||
- `failures.compose.yml`: у `cleaner` — `RECONCILER__INTERVAL_SECONDS:
|
||||
"0"` с комментарием (решение 9);
|
||||
- `run_failures.py`: `<проект>-cleaner-scheduled` — в списке уборки и
|
||||
журналов при падении; строка `start cleaner` называет и интервал
|
||||
сверки.
|
||||
|
||||
Проверка: `make failure_checks FAULT_ARGS='-k readiness'` — стенд
|
||||
поднят и убран, контейнеров и volumes проекта отказов после команды
|
||||
нет.
|
||||
- [ ] 1.3 Тесты в `student-tests/test_failures.py` по таблице решения 11
|
||||
— восемь тестов с маркерами `fault` и `spec`:
|
||||
- `test_reconcile_finds_and_fixes`;
|
||||
- `test_reconcile_keeps_fresh_used_and_unknown`;
|
||||
- `test_reconcile_restored_original`;
|
||||
- `test_reconcile_change_limit`;
|
||||
- `test_reconcile_object_storage_stopped`;
|
||||
- `test_reconcile_interrupted_by_database`;
|
||||
- `test_reconcile_under_load`;
|
||||
- `test_scheduled_reconcile`.
|
||||
|
||||
Как устроены:
|
||||
- помощники разбора записей сверки (`Found` / `Fixed` / `Finished`,
|
||||
`exit_code`) — в начале раздела;
|
||||
- фильтр — по своим `id` и ключам;
|
||||
- код выхода сверяется с записями того же прохода (решение 11);
|
||||
- объекты без строки ждут G + 1 с, остальные — `age-row`;
|
||||
- остановки — `with outage(...)`;
|
||||
- клиенты потоков — со сроком 30 с.
|
||||
- [ ] 1.4 Красный прогон до кода групп 2–7: `make failure_checks
|
||||
FAULT_ARGS='-k reconcile'` на нынешнем коде (`5f4b9ff`). Ожидаемо
|
||||
падают все восемь: команды `reconcile` нет (argparse — код 2), колонки
|
||||
`lost_at` нет (`lost-ids` — ошибка hook). Число упавших и причины — в
|
||||
tasks при прогоне и в разделе красного прогона
|
||||
`evidence/tests/failure-checks.md` (задача 12.6). Рабочий стенд не
|
||||
трогается.
|
||||
|
||||
## 2. Настройки, константы, enum и DTO
|
||||
|
||||
- [ ] 2.1 Секция `[reconciler]` по решению 10 и дельте
|
||||
`service-configuration`:
|
||||
- класс `Reconciler` в `src/config/settings.py`: `interval_seconds`
|
||||
(float, ≥ 0, 3600), `page_size` (int, 1–1000, 1000), `max_changes`
|
||||
(int, ≥ 1, 100);
|
||||
- поле `reconciler` в `Settings`;
|
||||
- строки с комментариями в `config_example.toml`.
|
||||
|
||||
Проверка: `uv run python -c "from src.config import settings;
|
||||
print(settings.reconciler)"` — значения по умолчанию;
|
||||
`RECONCILER__PAGE_SIZE=5000`, `RECONCILER__MAX_CHANGES=0` и
|
||||
`RECONCILER__INTERVAL_SECONDS=-1` — ошибка проверки называет поле.
|
||||
- [ ] 2.2 Типы по решению 8 и `dto.md`:
|
||||
- `ReconcileFinding` (`StrEnum`) в `src/schemas/enums/attachment.py`;
|
||||
- `ReconcileFindingDTO`, `ReconcilePassDTO` в
|
||||
`src/schemas/dataclasses/attachment.py`;
|
||||
- `AttachmentFullDTO.lost_at: datetime | None = None` — последним
|
||||
полем;
|
||||
- `RECONCILE_FINDINGS_LOGGED_MAX = 1000` в `src/utils/constants.py`;
|
||||
- реэкспорт в `__init__.py` по алфавиту.
|
||||
|
||||
Проверка: `make lint`.
|
||||
|
||||
## 3. Схема
|
||||
|
||||
- [ ] 3.1 Колонка `lost_at` по решению 6:
|
||||
- модель `Attachment` — `lost_at: Mapped[datetime | None]`
|
||||
(`DateTime(timezone=True)`);
|
||||
- ревизия поверх `739b8f04d5fb`: первой строкой `SET LOCAL lock_timeout
|
||||
= '2s'`, `add_column`; `downgrade` — `drop_column` с тем же сроком.
|
||||
|
||||
Проверка на временной базе (`createdb` в контейнере `postgres`,
|
||||
`DATABASE__NAME` в окружении, затем `DROP DATABASE`):
|
||||
- `upgrade` с нуля → повтор без изменений → `downgrade -1` →
|
||||
`upgrade`;
|
||||
- `uv run alembic upgrade head --sql` — `SET LOCAL lock_timeout` перед
|
||||
`ALTER TABLE attachments ADD COLUMN lost_at`;
|
||||
- `\d attachments` — колонка `timestamptz` без значения по умолчанию.
|
||||
|
||||
Вывод — для evidence 12.5.
|
||||
|
||||
## 4. Клиент S3 и repo
|
||||
|
||||
- [ ] 4.1 `src/infra/s3/client.py` по решению 3 и дельте
|
||||
`object-storage`:
|
||||
- `StoredObjectInfo.last_modified` (из LIST и HEAD);
|
||||
- страница списка `list_page(prefix, *, token, max_keys)` —
|
||||
`list_objects_v2`, результат — ключи с размером и временем плюс токен
|
||||
продолжения;
|
||||
- вызов без `Key` в `_call` (общий срок и перевод ошибок);
|
||||
- `NoSuchBucket` и `AccessDenied` на списке — `ObjectStorageUnavailable`
|
||||
с прежними записями `error`.
|
||||
|
||||
Проверка: `make lint`; поведение — 4.4 и группа 9.
|
||||
- [ ] 4.2 `src/core/repos/attachment_object.py`:
|
||||
- `list_originals` — префикс `<namespace>/attachments/`;
|
||||
- `parse_original_key` — `UUID` для ключа вида `<id>/original` в нижнем
|
||||
регистре, иначе `None`;
|
||||
- `head_original`;
|
||||
- `probe_originals` — список с `MaxKeys=1`: bucket на месте и список
|
||||
разрешён.
|
||||
|
||||
Проверка: `make lint`.
|
||||
- [ ] 4.3 `src/core/repos/attachment.py` по решениям 3–5 (одно выражение
|
||||
на функцию, `repo-layer.md`):
|
||||
- `_ATTACHMENT_COLUMNS` + `lost_at`;
|
||||
- выборка страницы по `id = ANY(:ids) OR object_key = ANY(:keys)`;
|
||||
- keyset строк `ready` по `id`;
|
||||
- `find_attachment_reference(id, key)`;
|
||||
- `mark_lost` и `clear_lost` — условный `UPDATE … RETURNING id`.
|
||||
|
||||
Проверка: `make lint`; на временной базе с ≥ 10 000 строк `ready` —
|
||||
`EXPLAIN (ANALYZE, BUFFERS)` выборки страницы (Bitmap OR по
|
||||
`pk_attachments` и `uq_attachments_object_key` или только pk при
|
||||
пустом `keys`) и keyset (Index Scan `pk_attachments`). Итог — в
|
||||
design, «Уточнения apply».
|
||||
- [ ] 4.4 Проверка клиента и repo на временном проекте compose. Как в
|
||||
пробе design, Context: SeaweedFS на tmpfs и bootstrap группы 8.1. Ключ
|
||||
уборщика:
|
||||
- список своего префикса страницами по 1000 — все ключи и
|
||||
`LastModified`;
|
||||
- весь bucket и чужой префикс — `ObjectStorageUnavailable` («denied
|
||||
access»);
|
||||
- удалённый bucket — `ObjectStorageUnavailable` («bucket is missing»),
|
||||
а не пустая страница.
|
||||
|
||||
Проект и его ресурсы убраны.
|
||||
|
||||
## 5. API: потерянный оригинал
|
||||
|
||||
- [ ] 5.1 `AttachmentService.open_content` по решению 5 и дельте
|
||||
`attachments`: `lost_at` задан — `info` «Attachment content is lost»
|
||||
(`attachment_id`, `object_key`) и `AttachmentNotFound` до обращения к
|
||||
S3. Без пометки и без объекта — 500, как было. Метаданные и
|
||||
`MessageService` не меняются. Проверка: `make lint`; тесты 1.3
|
||||
«Потерянный оригинал»; `make test_isolated` — прежние тесты
|
||||
вложений зелёные.
|
||||
|
||||
## 6. Сервис сверки
|
||||
|
||||
- [ ] 6.1 `AttachmentReconcileService(db_scope, storage)` в
|
||||
`src/core/services/attachment_reconcile.py` по решениям 3, 4, 7 и 8:
|
||||
- шаги «S3 → БД», «БД → S3», зависшие загрузки;
|
||||
- перепроверка и проверка bucket до решения;
|
||||
- предел изменений;
|
||||
- действия по порядку решения 7;
|
||||
- `stop_requested` между страницами и действиями;
|
||||
- итог — `ReconcilePassDTO`;
|
||||
- записи журнала по дельте `service-logging` и не больше
|
||||
`RECONCILE_FINDINGS_LOGGED_MAX` записей находок;
|
||||
- уборка зависших — через `AttachmentCleanupService`.
|
||||
|
||||
Проверка: `make lint`; поведение — группа 9.
|
||||
|
||||
## 7. Процесс уборщика
|
||||
|
||||
- [ ] 7.1 `src/cleaner/main.py` (и `__main__.py`, если нужно) по
|
||||
решениям 1, 8 и 9:
|
||||
- команда `reconcile [--apply] [--max-changes N]` (`N` ≥ 1), коды
|
||||
0 / 3 / 1 / 2;
|
||||
- общая подготовка с сервисом: проверка grace, сигналы,
|
||||
`early_stop.disarm()`, engine, клиент S3;
|
||||
- плановая сверка в цикле сервиса (при старте, затем через
|
||||
`[reconciler] interval_seconds`, 0 — нет);
|
||||
- «Started cleaner» с параметрами сверки и режимом;
|
||||
- `--once` — как было.
|
||||
|
||||
Проверка без стенда:
|
||||
- `RECONCILER__PAGE_SIZE=5000 uv run python -m src.cleaner reconcile` —
|
||||
«Invalid cleaner settings» с `reconciler.page_size`, код 2;
|
||||
- `CLEANER__PENDING_GRACE_SECONDS=17 … reconcile` — код 2 до обращения
|
||||
к хранилищам;
|
||||
- `… reconcile --max-changes 0` — ошибка аргумента, код 2;
|
||||
- `make lint`.
|
||||
|
||||
## 8. Стенд
|
||||
|
||||
- [ ] 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`;
|
||||
- проверки `apply` — список префикса 200, всего bucket 403;
|
||||
- строки режима `check` — свой префикс 200, без префикса 403, чужой
|
||||
префикс 403, чужой bucket 403;
|
||||
- шапка скрипта;
|
||||
- `docker-compose.yml`: `S3_CLEANER_LIST_PREFIX:
|
||||
${POSTGRES_DB:?…}/attachments/` у `s3-bootstrap`.
|
||||
|
||||
Проверка на временном проекте compose — tmpfs, синтетические секреты,
|
||||
bootstrap проекта:
|
||||
- первый запуск и повтор дважды — код 0;
|
||||
- неверный префикс — код 1 и шаг в сообщении;
|
||||
- строки `check` с ожидаемыми кодами.
|
||||
|
||||
Затем на рабочем стенде `docker compose up -d s3-bootstrap` и `make
|
||||
s3_check` — код 0, строки списка ключом уборщика есть. Проект пробы
|
||||
убран, volumes сверены.
|
||||
- [ ] 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` получает префикс из
|
||||
`bench.env` (`POSTGRES_DB=bench`). Секретов не прибавилось,
|
||||
`compose_env` не меняется. В `bench.compose.yml` у описанного
|
||||
`cleaner` — `RECONCILER__INTERVAL_SECONDS: "0"`: профиль сверки
|
||||
`track2-reconcile-cost` включит её сам. Проверка: `make
|
||||
bench_uploads_quick` — код 0 (bootstrap с префиксом прошёл), метка
|
||||
`quick-*` в git не идёт.
|
||||
|
||||
## 9. Спеки и проверки отказов
|
||||
|
||||
- [ ] 9.1 Sync дельт в основные спеки — все семь capability, как в
|
||||
прежних changes: сверка покрытия читает только `openspec/specs/`.
|
||||
Purpose `storage-consistency` — без «добавят следующие changes»: сверка
|
||||
описана. Проверка:
|
||||
- `openspec validate track2-reconciler --strict`;
|
||||
- `make student_test` через LB — `test_coverage.py` зелёный, сверка
|
||||
называет новые сценарии `storage-consistency` и `attachments`
|
||||
покрытыми проверками отказов.
|
||||
- [ ] 9.2 Полный `make failure_checks` на дереве после групп 2–8: все
|
||||
проверки зелёные (прежние 37 и новые 8), журнал PostgreSQL стенда без
|
||||
признаков аварии, стенд отказов удалён, `StartedAt` рабочего стенда
|
||||
прежний. Время прогона — в tasks. Два прогона одновременно не
|
||||
запускать (`student-tests.md`).
|
||||
|
||||
## 10. Драйвер скилла
|
||||
|
||||
- [ ] 10.1 `driver.py reconcile-cycle` по решению 12 — только стенд с LB,
|
||||
без LB код 2. Шаги:
|
||||
- исходный dry-run;
|
||||
- внесение расхождений с обеих сторон;
|
||||
- ожидание grace прогона 30 с;
|
||||
- dry-run со снимками до и после;
|
||||
- 500 до сверки, `--apply`, 404 и 200 после;
|
||||
- повтор, удаление чужого объекта, повтор с кодом 0;
|
||||
- свежий объект после grace;
|
||||
- возврат оригинала.
|
||||
|
||||
Триггер `commit` — на уникальный `filename`, снимается в `finally` и в
|
||||
начале следующего прогона. Таблицы без токенов и секретов, код 1 при
|
||||
расхождении. Проверка: прогон на рабочем стенде (`--port 8090`) — код
|
||||
0; повторный прогон — снова 0, и исходный dry-run не находит остатков
|
||||
прошлого.
|
||||
- [ ] 10.2 `driver.py reconcile-stress [--seconds S] [--clients N]` по
|
||||
решению 12. Шаги:
|
||||
- предусловие — dry-run с grace 20 с, иначе код 2;
|
||||
- внесённые расхождения;
|
||||
- загрузки и отправки через LB, поток `--apply` раз в ~3 с;
|
||||
- итоговая таблица и сверка SHA-256 каждого 201.
|
||||
|
||||
Проверка: прогон на рабочем стенде — код 0, несовпадений 0.
|
||||
- [ ] 10.3 `SKILL.md` скилла: обе команды, их evidence и что они меняют
|
||||
на стенде (синтетические вложения, помеченные потерянными, остаются в
|
||||
рабочей базе). Строки `s3-check` приходят из bootstrap, разбор не
|
||||
меняется — проверить вывод `make s3_check`.
|
||||
|
||||
## 11. Правила и документы
|
||||
|
||||
- [ ] 11.1 Правила:
|
||||
- `service-layer.md` — сервис сверки, порядок действий, ветка 404;
|
||||
- `repo-layer.md` — новые функции;
|
||||
- `dto.md` — `lost_at`, DTO сверки, enum;
|
||||
- `infra.md` — список клиента, `last_modified`, префикс;
|
||||
- `migrations.md` — ревизия `lost_at`;
|
||||
- `docker.md` — политика `cleaner-objects`, `S3_CLEANER_LIST_PREFIX`,
|
||||
уборщик на время восстановления БД;
|
||||
- `settings.md` — `[reconciler]`;
|
||||
- `logging.md` — журнал сверки;
|
||||
- `run-modes.md` — команда `reconcile`, плановая сверка, коды;
|
||||
- `api-contract.md` — 404 потерянного оригинала и вопрос;
|
||||
- `student-tests.md` — действия hook, тесты, интервал сверки 0 на
|
||||
стенде отказов;
|
||||
- `balancer.md` — порядок обновления (решение 6).
|
||||
|
||||
Проверка: в каждом правиле — ссылка на design этого change.
|
||||
- [ ] 11.2 AGENTS.md:
|
||||
- абзац инвариантов «Лаба 4, сверка» (что удаляется и что никогда,
|
||||
grace, предел, права S3, 404);
|
||||
- карта кода — `attachment_reconcile.py`, новые функции repo, команда
|
||||
уборщика;
|
||||
- таблица команд — `make reconcile`, `driver.py reconcile-cycle`,
|
||||
`reconcile-stress`;
|
||||
- вступление — change в архиве, когда он будет заархивирован.
|
||||
- [ ] 11.3 `KNOWN_ISSUES.md`, запись «Bootstrap после удаления bucket»,
|
||||
по решению 14: причина (слоты томов на маленьком диске, `-volume.max=0`),
|
||||
проба на 4 и 16 ГБ, стенды проекта не затронуты, предложение. Запись
|
||||
остаётся открытой.
|
||||
|
||||
## 12. Прогоны и evidence
|
||||
|
||||
- [ ] 12.1 Commit кода (основная сессия, после подтверждения). Затем
|
||||
рабочий стенд по порядку решения 6:
|
||||
- `docker compose up -d s3-bootstrap`;
|
||||
- `make rolling_update`;
|
||||
- `docker compose up -d --no-deps cleaner`.
|
||||
|
||||
Проверка:
|
||||
- журнал уборщика — плановая сверка при старте без находок;
|
||||
- `make reconcile` — код 0;
|
||||
- `make test BASE_URL=http://localhost:8090`;
|
||||
- `make student_test BASE_URL=http://localhost:8090`;
|
||||
- `make test-persistence ACTION_SCRIPT=scripts/restart.sh` и `make
|
||||
test-failover ACTION_SCRIPT=scripts/stop-one.sh` для обеих реплик —
|
||||
с `BASE_URL` LB;
|
||||
- `make s3_check`.
|
||||
- [ ] 12.2 `evidence/reconcile/cycle.md` — вывод `driver.py --port 8090
|
||||
reconcile-cycle` с датой и commit.
|
||||
- [ ] 12.3 `evidence/reconcile/stress.md` — вывод `driver.py --port 8090
|
||||
reconcile-stress`.
|
||||
- [ ] 12.4 `evidence/reconcile/service.md`:
|
||||
- «Started cleaner» с параметрами сверки;
|
||||
- плановая сверка при старте;
|
||||
- `docker compose stop cleaner` во время сверки при `docker compose
|
||||
pause s3` — время, код 0, записи прерывания и остановки; затем
|
||||
`unpause`;
|
||||
- отказ старта с `RECONCILER__PAGE_SIZE=5000`;
|
||||
- коды разового прохода 0 и 3.
|
||||
- [ ] 12.5 Остальное evidence:
|
||||
- `evidence/s3/cleaner-list.md` — bootstrap с новой политикой, `make
|
||||
s3_check`, окружение `s3-bootstrap` в `docker compose config`;
|
||||
- `evidence/migrations/lost-at.md` — вывод 3.1 и `make rolling_update`
|
||||
12.1 с ревизией до и после.
|
||||
- [ ] 12.6 `evidence/tests/`:
|
||||
- `failure-checks.md` — полный прогон и раздел красного прогона 1.4;
|
||||
- `student-test-lb.md`;
|
||||
- вывод `make test_isolated`.
|
||||
- [ ] 12.7 Регресс:
|
||||
- `make bench_quick`;
|
||||
- `bench_failover_quick`;
|
||||
- `bench_rollout_quick` (замена `e1161f7` → новая ревизия под
|
||||
нагрузкой, ошибок 0, сообщений = ключей);
|
||||
- `bench_restore_quick`;
|
||||
- `make test_isolated` — код 0 у каждой.
|
||||
|
||||
Метки `quick-*` в git не идут.
|
||||
- [ ] 12.8 `REPORT.md`:
|
||||
- раздел «Сверка хранилищ (трек 2, change `track2-reconciler`)» —
|
||||
классы, проход, правила безопасности, предел, права S3, ответы API
|
||||
и вопрос преподавателю, плановая сверка;
|
||||
- строки таблицы доказательств уровня «5» с командами и путями
|
||||
evidence;
|
||||
- ограничения из design, Risks;
|
||||
- дополнение ответа на вопрос защиты «PUT прошёл, COMMIT нет».
|
||||
|
||||
`PLAN.md` — строка этапа 5 и решения apply в `### track2-reconciler`.
|
||||
Reference in New Issue
Block a user