Files
mtusi2026lab4/docs/CONSISTENCY.md
T
Alexey BodanyukandClaude Opus 5.5 4ea6924db1 lab4: память загрузок и S3 под лимитом, документация защиты
- тело загрузки: один буфер ровно 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>
2026-10-25 14:21:43 +03:00

74 lines
9.8 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Согласованность 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.