forked from mtusi2026/mtusi2026lab4
- тело загрузки: один буфер ровно Content-Length, без копий до S3 и djpeg; - PNG: zlib получает вход кусками по 64 KiB (unconsumed_tail копировал остаток IDAT); - djpeg, убитый OOM-killer'ом, -> 503 (ресурсы сервера), а не 415; - api: memswap_limit = memory (жёсткий лимит без swap); S3: GOMEMLIMIT и лимиты одновременных загрузок SeaweedFS, память 1g; - docs: CONSISTENCY.md, DEFENSE.md, WINDOWS.md, DATA_MODEL.md под lab4; scripts/demo_attachments.py для сценария защиты; CI и collect_evidence под lab4; - bench/reconcile_faults.py: отчёты трека 2 (ошибки с обеих сторон, прерванный apply). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
74 lines
9.8 KiB
Markdown
74 lines
9.8 KiB
Markdown
# Согласованность PostgreSQL и S3 (lab4: уровень 4 и трек 2)
|
||
|
||
Байты вложения лежат в приватном bucket S3 (SeaweedFS), метаданные — в таблице `attachments` PostgreSQL. Общей транзакции у двух хранилищ нет, поэтому порядок записи и механизм уборки определяют, что остаётся после любого сбоя.
|
||
|
||
## Инвариант и порядок записи
|
||
|
||
**Объект никогда не существует без строки, которая называет его ключ.** Строка появляется раньше объекта, а при уборке исчезает позже.
|
||
|
||
```text
|
||
upload: [проверки, тело в памяти, полная проверка изображения]
|
||
1. INSERT attachments(status='pending', object_key=o/<128 бит>) COMMIT ← намерение
|
||
2. S3 PUT o/<key> (Content-MD5)
|
||
3. UPDATE status='ready' WHERE status='pending' COMMIT
|
||
4. 201 ready
|
||
janitor: SELECT … WHERE status='pending' AND старше PENDING_GRACE FOR UPDATE SKIP LOCKED
|
||
S3 DELETE (идемпотентно) → DELETE строки COMMIT
|
||
```
|
||
|
||
| Сбой | Что остаётся | Кто и когда убирает | Что видит клиент |
|
||
| --- | --- | --- | --- |
|
||
| До шага 1 (лимит, 415, обрыв тела, таймаут) | ничего: до полной проверки в хранилища ничего не пишется | — | 4xx/обрыв |
|
||
| Шаг 1 не прошёл (БД недоступна) | ничего | — | 503 |
|
||
| Между 1 и 2, S3 PUT упал или неизвестно, записан ли объект | строка `pending` (+ возможно объект) | janitor через `PENDING_GRACE_SECONDS` (900 с): удаляет объект, затем строку | 503, повтор создаёт новое вложение (контракт это разрешает) |
|
||
| Между 2 и 3 (процесс упал, БД пропала) — `FAULT_POINTS=after_s3_put` | строка `pending` + объект | janitor | 503 |
|
||
| Шаг 3 закоммичен, ответ потерян — `FAULT_POINTS=after_ready_commit` | корректное `ready`-вложение | **никто не трогает**: janitor работает только с `pending` | 503; файл скачивается по id ([test_consistency.py](../student-tests/test_consistency.py)) |
|
||
|
||
В обработчике запроса **компенсации нет**. Если ответ на COMMIT потерян, неизвестно, стала ли строка `ready`. Удалить объект «на всякий случай» значило бы получить `ready` без байтов — именно это преподаватель нашёл в чужом PR. Решение принимает только janitor, по зафиксированному состоянию и под блокировкой строки: «зависшая» загрузка, если бы она ещё шла, ждала бы на этой строке и затем получила бы 503.
|
||
|
||
**Почему grace 900 с безопасен.** Самая долгая загрузка: ожидание слота 5 с + тело 30 с + проверка 10 с + S3 PUT ≈ 4 с, итого < 60 с. Grace на порядок больше. Reconciler отказывается работать с `--grace` < 60 с без явного флага `--allow-small-grace` (флаг нужен только тестам).
|
||
|
||
**Когда честно вернуть 201.** Только после шага 3: объект записан (S3 подтвердил PUT и проверил Content-MD5), строка `ready` закоммичена. До этого клиент не получает id.
|
||
|
||
## Reconciler (трек 2)
|
||
|
||
`python -m messenger.reconcile` — отдельный CLI в том же образе, compose-сервис `reconciler` (профиль `tools`, запускается по требованию). У него свои ключи S3 (`Read+Write+List` на bucket), у API права `List` нет.
|
||
|
||
### Как он обходит хранилища
|
||
|
||
Оба хранилища читаются как упорядоченные по ключу потоки, и над ними выполняется merge-join:
|
||
|
||
- S3: `ListObjectsV2(prefix=o/, StartAfter, MaxKeys=1000)` — ключи в порядке байтов;
|
||
- PostgreSQL: keyset-страницы `SELECT … FROM attachments WHERE object_key > $1 ORDER BY object_key LIMIT 1000` — колонка `COLLATE "C"`, тот же порядок байтов, уникальный индекс.
|
||
|
||
Память не зависит от размера bucket. Стоимость прохода ≈ N/1000 запросов листинга + N/1000 страниц БД; с `--verify-checksums` добавляется чтение всех байтов.
|
||
|
||
### Что находит и что исправляет `--apply`
|
||
|
||
| Вид | Условие | `--apply` |
|
||
| --- | --- | --- |
|
||
| `orphan_object` | объект без строки, старше `--grace` | удалить объект (перед этим заново проверить, что строки нет и объект всё ещё старый) |
|
||
| `stale_intent` | строка `pending` старше `--grace` (с объектом или без) | под `FOR UPDATE`: удалить объект, затем строку |
|
||
| `missing_object` | строка `ready`, объекта нет, старше `--grace` | **карантин** строки: `lost_at`, `lost_reason` |
|
||
| `size_mismatch` | у `ready` размер объекта ≠ `size_bytes` | карантин |
|
||
| `checksum_mismatch` | SHA-256 объекта ≠ сохранённому (`--verify-checksums`) | карантин |
|
||
| `restored_object` | строка в карантине, объект снова на месте и верный | снять карантин |
|
||
| `fresh_*` | то же, но моложе `--grace` (загрузка в процессе) | ничего |
|
||
|
||
Карантин: `GET …/content` → 404 «оригинал утрачен», прикрепить к новому сообщению нельзя (409, как failed-вложение). Метаданные и ссылки из старых сообщений сохраняются. Карантин обратим: когда объект восстановят из резервной копии, следующий проход его снимет.
|
||
|
||
### Почему исправление безопасно
|
||
|
||
1. **Dry-run read-only конструктивно, а не «по if-у».** Сессия PostgreSQL открывается с `default_transaction_read_only=on`: любая запись упадёт в самой БД. Объект S3 в dry-run обёрнут в `ReadOnlyStorage` без метода `delete`. Тест сравнивает отпечаток всех строк `attachments` и список ключей bucket до и после dry-run. Это закрывает ошибку, которую нашли в чужом PR: «dry-run продолжает частично завершённое удаление».
|
||
2. **`ready`-строки никогда не удаляются**, ни используемые, ни неиспользуемые: только обратимый карантин. Удаляются лишь объекты без строк и строки-намерения `pending`. Ссылки `message_attachments → attachments` защищены FK, поэтому используемое вложение не удалить даже по ошибке.
|
||
3. **Всё, что моложе `--grace`, не трогается.**
|
||
4. **Перепроверка перед каждым действием**, под `FOR UPDATE`, где есть строка. `post_message_v2` берёт `FOR SHARE` на прикрепляемые вложения, поэтому карантин и отправка сообщения сериализуются.
|
||
5. **Объект первым, строка второй.** Прерванный проход оставляет состояние, которое следующий проход доводит до конца. Повторный запуск идемпотентен.
|
||
6. **Предохранитель.** Если «сиротами» выглядят больше `--max-orphan-fraction` (50 %) объектов — например, reconciler направили не в ту БД, — `--apply` завершается с кодом 3, ничего не удалив.
|
||
7. **Отказ хранилища** во время прохода: выход с кодом 1 и JSON-отчётом `store_unavailable`; уже сделанное зафиксировано, остальное сделает следующий запуск.
|
||
|
||
### Janitor и reconciler — зачем оба
|
||
|
||
- **Janitor** (в каждой реплике API, раз в ~60 с, advisory-замок — работает одна реплика за раз) дёшев: частичный индекс по `pending` и ничего больше. Он убирает типичный мусор — незавершённые загрузки.
|
||
- **Reconciler** проходит оба хранилища целиком и находит то, о чём БД не знает: объекты без строк (ручные действия, баги прошлых версий, восстановление bucket из другой копии), пропавшие и испорченные объекты. Его запускают по расписанию или вручную, всегда сначала в dry-run.
|