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>
This commit is contained in:
Alexey Bodanyuk
2026-10-25 14:21:43 +03:00
co-authored by Claude Opus 5.5
parent a2d867bec6
commit 4ea6924db1
18 changed files with 701 additions and 120 deletions
+73
View File
@@ -0,0 +1,73 @@
# Согласованность 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.
+6 -2
View File
@@ -1,6 +1,6 @@
# Модель данных lab3
# Модель данных lab4
Схема: [0001_init.sql](../migrations/0001_init.sql) (lab2), [0002_idempotency_keys.sql](../migrations/0002_idempotency_keys.sql) и [0003_post_message_function.sql](../migrations/0003_post_message_function.sql) (lab3). Миграции применяет один раз отдельный сервис `migrate` до старта реплик API; обе миграции lab3 только добавляют объекты, поэтому совместимы с работающей предыдущей версией (rolling update). Источник истины для пользователей, чатов, участников и сообщений — PostgreSQL 18. Для сессий источник истины — хранилище, выбранное через `SESSION_STORE`. По умолчанию это Valkey с AOF, его можно переключить на таблицу `sessions` в PostgreSQL.
Схема: [0001_init.sql](../migrations/0001_init.sql) (lab2), [0002_idempotency_keys.sql](../migrations/0002_idempotency_keys.sql) и [0003_post_message_function.sql](../migrations/0003_post_message_function.sql) (lab3), [0004_attachments.sql](../migrations/0004_attachments.sql) (lab4). Миграции применяет один раз отдельный сервис `migrate` до старта реплик API; миграции lab3 и lab4 только добавляют объекты (0004 ещё ослабляет `CHECK` длины текста), поэтому совместимы с работающей предыдущей версией. Байты вложений живут **только** в приватном bucket S3 (SeaweedFS), в PostgreSQL — их метаданные; согласованность двух хранилищ — [CONSISTENCY.md](CONSISTENCY.md). Источник истины для пользователей, чатов, участников и сообщений — PostgreSQL 18. Для сессий источник истины — хранилище, выбранное через `SESSION_STORE`. По умолчанию это Valkey с AOF, его можно переключить на таблицу `sessions` в PostgreSQL.
## Таблицы и ограничения
@@ -12,6 +12,8 @@
| `messages` | `id uuid` | FK `(chat_id, sender_id) → chat_members`, длина `text` | отправитель обязан быть участником — это гарантирует сама БД |
| `sessions` | `token_hash bytea` | FK `user_id → users`, длина хеша 32 байта | хранится SHA-256 токена; сам токен не хранится нигде |
| `idempotency_keys` | `(user_id, chat_id, key)` | FK на `users`, `chats`; `message_id → messages` (DEFERRABLE, `UNIQUE`); `CHECK` формата ключа и длины SHA-256 | общая для всех реплик идемпотентность отправки: ключ → отпечаток тела → сообщение. Хранится ≥ `IDEMPOTENCY_TTL_SECONDS` (24 ч), очистка — пачками раз в 10 мин под advisory-замком |
| `attachments` (lab4) | `id uuid` | FK `(chat_id, owner_id) → chat_members`; `UNIQUE object_key` (`COLLATE "C"`, формат `o/<32 hex>`); `CHECK` статуса `pending/ready`, типа `image/png|jpeg`, размера 1…10 MiB, пикселей ≤ 40 млн, длины SHA-256, карантина (`lost_at`/`lost_reason` только у `ready`) | метаданные оригинала; `object_key` генерирует сервер (128 случайных бит), с id и filename не связан. `pending` — намерение загрузки (строка раньше объекта), `ready` — объект записан. Частичный индекс `(created_at) WHERE status='pending'` — для janitor |
| `message_attachments` (lab4) | `(message_id, position)` | FK на `messages` и `attachments`, `UNIQUE (message_id, attachment_id)`, индекс по `attachment_id` | целостность ссылок (вложение, на которое ссылается сообщение, удалить нельзя) и обратный поиск «используется ли вложение» |
| `schema_migrations` | `version` | checksum файла | какие миграции применены; изменённую задним числом миграцию мигратор не применит |
**Почему `bytea` для текста.** Контракт разрешает символ U+0000, а тип `text` в PostgreSQL не может содержать байт NUL (`DataError`). Поэтому `display_name`, `title` и `text` хранятся как байты UTF-8. Длину в code points проверяет API, а `CHECK` в байтах — страховка (1 code point ≤ 4 байта).
@@ -30,6 +32,8 @@
| Регистрация | один `INSERT` | `UniqueViolation` → 409; ровно одна строка при гонке |
| Создание чата | `INSERT chats` → `INSERT chat_members` (все участники одним запросом) → `COMMIT` | неизвестный участник вызывает FK-ошибку **после** вставки чата; откат удаляет и чат, и частичное членство |
| Сообщение (lab3, с ключом) | проверка членства → `INSERT idempotency_keys … ON CONFLICT DO UPDATE … WHERE ключ старше 24 ч` → если вставлен: `UPDATE chats … RETURNING` → `INSERT messages`; если нет: прочитать сохранённое сообщение и сравнить отпечаток → `COMMIT`. По умолчанию всё это — одна SQL-функция `post_message` в autocommit (одно обращение к БД) | ключ, сообщение и «результат» коммитятся вместе или не коммитятся вовсе: «висящего» ключа нет. Конкурентный повтор ждёт на уникальном индексе завершения первой транзакции и затем видит её результат (READ COMMITTED, новый снимок на каждый оператор). Другое тело → 409, тот же — тот же Message |
| Сообщение с `attachment_ids` (lab4) | в той же функции `post_message_v2`: проверка членства → проверка вложений (`ready`, этого чата, не в карантине; `FOR SHARE`) → только если всё хорошо — захват ключа → `UPDATE chats` → `INSERT messages (…, attachment_ids)` → `INSERT message_attachments` | чужое/неизвестное/незавершённое вложение — 404, в карантине — 409, ключ при этом не «сгорает». Порядок `attachment_ids` хранится массивом в строке сообщения: страница истории остаётся одним диапазонным сканом индекса |
| Загрузка вложения (lab4) | `INSERT attachments … 'pending'` (autocommit) → S3 PUT (Content-MD5) → `UPDATE … SET status='ready' WHERE status='pending'` (autocommit) → 201 | 201 только когда и объект, и строка `ready` зафиксированы. Сбой между шагами оставляет `pending`, его убирает janitor после `PENDING_GRACE_SECONDS`. Компенсации в обработчике запроса нет: после потерянного ответа COMMIT неизвестно, `ready` ли строка |
| Сообщение (lab2-часть) | проверка членства → `UPDATE chats SET last_message_at = greatest(clock_timestamp(), last_message_at + 1 мкс) RETURNING` → `INSERT messages` → `COMMIT` | строка чата заблокирована до конца транзакции, поэтому писатели одного чата идут по очереди. Время сообщений строго растёт **в порядке коммитов**: страница по cursor не пропустит сообщение, закоммиченное «задним числом» |
| Вход | `SELECT` пользователя, проверка Argon2id, запись сессии | неверный пароль ничего не пишет |
| Logout | `DELETE` сессии (или `DEL` в Valkey) | повтор с тем же токеном — 401 |
+39
View File
@@ -0,0 +1,39 @@
# Ответы на вопросы защиты ЛР 4
## Почему файл в Docker volume одной API-реплики не равен объектному хранилищу?
- **Volume принадлежит одному контейнеру.** Файл, загруженный через реплику api-1, лежит только у неё. Запрос, который LB отправил на api-2, его не найдёт. Если api-1 остановлена (failover, rolling update, scale down), файл недоступен вовсе. В нашем стенде у сервиса `api` нет ни одного volume: реплики взаимозаменяемы, и тест «загрузка → kill обслужившей реплики → скачивание через другую» проходит ([test_storage_failures.py](../student-tests/test_storage_failures.py)).
- **Общий bind-mount на одном хосте** тоже не выход. Он привязывает все реплики к одной машине, не даёт атомарной записи объекта, проверки целостности (Content-MD5), отдельных прав доступа и HTTP-API для других сервисов (worker в lab5 возьмёт тот же объект по ключу).
- **S3-сервер** — отдельный процесс со своим жизненным циклом и своим volume (`s3data`): он переживает перезапуск и замену API. Права в нём задаются по ключам: у API — только Read+Write своего bucket, без List и без создания bucket.
## Когда можно честно вернуть 201?
Когда оба хранилища подтвердили запись: S3 ответил на PUT, проверив Content-MD5, и после этого закоммичен `UPDATE attachments SET status='ready'`. До этого клиент не получает id вложения. Перед записью проходят все проверки: лимиты, полная проверка изображения, SHA-256. Ответ 201 на «принял в память» или «записал строку, а PUT ещё идёт» был бы ложью: после сбоя по такому id ничего не скачать. Подробно: [CONSISTENCY.md](CONSISTENCY.md).
## Что произойдёт, если S3 PUT прошёл, а COMMIT в PostgreSQL — нет?
Строка-намерение `pending` с ключом объекта закоммичена **до** PUT, поэтому объект не «потеряется»: БД знает его ключ.
- Клиент получает 503 и может повторить: получится новое вложение, контракт это разрешает.
- Строка остаётся `pending`, вложение невидимо (GET → 404, прикрепить → 404).
- Janitor через `PENDING_GRACE_SECONDS` (900 с) под `FOR UPDATE` удаляет объект, затем строку. Проверено внедрением отказа `FAULT_POINTS=after_s3_put`: строка и объект исчезают ([test_consistency.py](../student-tests/test_consistency.py)).
- Если упал не COMMIT, а **ответ** на него (COMMIT прошёл), в обработчике ничего не удаляется: неизвестно, стала ли строка `ready`. Проверено `FAULT_POINTS=after_ready_commit`: файл цел и скачивается.
- Объекты, о которых БД не знает вовсе (ручные действия, старые версии), находит reconciler (трек 2) и удаляет, если они старше grace.
## Почему случайный object key и приватный bucket не заменяют ACL приложения?
- **Приватный bucket** запрещает анонимный доступ к S3, но решение «может ли *этот пользователь* читать *этот файл*» принимает только приложение: оно знает участников чата. Ключи S3 у API одни на всех пользователей. Поэтому каждый `GET /attachments/{id}` и `/content` проверяет членство в чате, посторонний получает 404 (не 403 — существование чужого вложения не раскрывается).
- **Случайный ключ** — защита от перебора, а не авторизация. Ключ может утечь (логи, отладка, бывший участник чата). Удалённого из чата пользователя в нашем API нет, но в общем случае доступ должен отзываться — а ключ, если бы он был единственной защитой, остался бы действующим навсегда. Поэтому ключ не попадает ни в один ответ API, а байты отдаются только через авторизованный API, без redirect на S3.
- То же проверено снаружи: анонимный GET/LIST к S3 → 403 (bootstrap `s3-init` и тест), а запрос с ключом API работает — значит, права проверяет S3, а доступ пользователей — приложение.
## Частые уточняющие вопросы
**Как ограничена память?** Одна загрузка — один буфер ≤ 10 MiB (при известном Content-Length выделяется ровно этот объём, без копий). На реплику одновременно принимается не больше `UPLOAD_CONCURRENCY=4` тел. Остальные ждут ≤ 5 с, их байты остаются в TCP-буферах (backpressure), потом 503 + Retry-After. Полная проверка изображения выполняется по одной (`IMAGE_VERIFY_CONCURRENCY=1`). Пиксели проверяются по заголовку ещё до чтения остального тела. Замер ≥ 10 одновременных загрузок: [REPORT.md](../REPORT.md#эксперименты-и-отказы).
**Почему не Pillow для проверки?** Для PNG Pillow создаёт растр целиком (40 Мпикс RGBA = 160 МБ), а наш валидатор проверяет CRC и zlib-поток потоково и ничего не хранит. Для JPEG Pillow игнорирует предупреждения libjpeg и возвращает серую картинку для файла без данных после SOS. `djpeg -strict` считает любое предупреждение ошибкой, а `-scale 1/8` декодирует все блоки, но пишет растр в 64 раза меньше.
**Что если S3 недоступен?** `/health/ready` → 503 (S3 входит в обязательный синхронный путь). Загрузка и скачивание → 503 за ≤ `S3_TIMEOUT_SECONDS` (3 с). HAProxy переключается на backend `api_core` с проверкой `/health/ready/core` (БД + Valkey): чаты и текстовые сообщения продолжают работать. Если S3 потеряла одна реплика, она DOWN в основном backend, и трафик идёт на другую.
**Почему SeaweedFS, а не MinIO?** Образы MinIO в Docker Hub больше не публикуются (репозиторий `minio/minio` удалён, проверено при выборе). SeaweedFS развивается и умеет identity с правами на bucket (`Read:bucket`, `Write:bucket`, `List:bucket`). Закреплён по digest (4.46, сентябрь 2026). Его web-интерфейсы (master, filer, volume) слушают только 127.0.0.1 внутри контейнера, телеметрия выключена.
**Где dry-run гарантирует, что ничего не меняется?** Не в коде планировщика, а в окружении: сессия PostgreSQL в dry-run открыта с `default_transaction_read_only=on`, объект S3 обёрнут без метода `delete`. Тест сравнивает отпечаток всей таблицы `attachments` и список ключей bucket до и после.
+50 -66
View File
@@ -1,4 +1,4 @@
# Запуск на ноутбуке с Windows и сценарий защиты ЛР 3
# Запуск на ноутбуке с Windows и сценарий защиты ЛР 4
Команды — в **PowerShell** из папки проекта (где лежит `compose.yaml`). Переменные `$env:...` действуют до закрытия окна.
@@ -7,29 +7,23 @@
| Программа | Зачем | Важно |
| --- | --- | --- |
| [Git for Windows](https://git-scm.com/download/win) | clone и Git Bash | путь по умолчанию `C:\Program Files\Git`: оттуда `scripts\*.cmd` запускают `.sh`-хуки |
| [Docker Desktop](https://www.docker.com/products/docker-desktop/) | PostgreSQL, Valkey, HAProxy, API | backend WSL 2, виртуализация в BIOS; для трека 1 в Settings → Resources дать **8 CPU** |
| [Docker Desktop](https://www.docker.com/products/docker-desktop/) | PostgreSQL, Valkey, SeaweedFS (S3), HAProxy, API | backend WSL 2, виртуализация в BIOS; в Settings → Resources ≥ 4 CPU и ≥ 6 ГБ RAM |
| [Python 3.12+](https://www.python.org/downloads/windows/) | secrets, публичные и свои тесты, скрипты замеров | галочка **Add python.exe to PATH** |
| GNU make (необязательно) | `make check/test/test-failover …` | `winget install ezwinports.make`, затем **новое** окно PowerShell. Рецептам Makefile нужен `sh`: в каждом окне PowerShell один раз `$env:Path += ";C:\Program Files\Git\usr\bin"` (или запускать make из Git Bash). Без make те же команды есть в таблице REPORT.md |
Проверка:
```powershell
git --version; docker version --format '{{.Server.Version}}'; docker compose version; python --version; make --version
```
| GNU make (необязательно) | `make check/test/test-failover …` | `winget install ezwinports.make`, затем **новое** окно PowerShell. Рецептам Makefile нужен `sh`: в каждом окне один раз `$env:Path += ";C:\Program Files\Git\usr\bin"` |
## 2. Развернуть проект (дома, заранее — нужен интернет)
```powershell
git clone https://gitea.privcloud.tech/wfa/mtusi2026lab3 mtusi2026lab3
cd mtusi2026lab3
git clone https://gitea.privcloud.tech/wfa/mtusi2026lab4 mtusi2026lab4
cd mtusi2026lab4
git checkout solution/bvt2302-bodanyuk
python scripts\init_secrets.py # случайные пароли в .\secrets (не в Git)
python scripts\init_secrets.py # случайные пароли и 3 пары ключей S3 в .\secrets (не в Git)
Copy-Item .env.example .env
docker compose --env-file .env config --quiet # конфигурация собирается без ошибок
docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build --wait
```
Первый запуск качает образы (~800 МБ) и собирает API — 3–10 минут. Команда завершается, когда postgres, valkey, обе реплики api и lb в состоянии `healthy`, а `migrate` завершился с кодом 0.
Первый запуск качает образы (~1 ГБ) и собирает API — 3–10 минут. Команда завершается, когда postgres, valkey, s3, обе реплики api и lb в состоянии `healthy`, а `migrate` и `s3-init` завершились с кодом 0. Вердикты bootstrap S3 (приватность, права ключей): `docker compose logs s3-init`.
Окружение для своих тестов и скриптов (один раз):
@@ -37,102 +31,92 @@ docker compose --env-file .env up -d --build --wait
python -m venv .venv
.venv\Scripts\python -m pip install --require-hashes --no-deps -r requirements.txt
.venv\Scripts\python -m pip install -r requirements-test.txt -r requirements-dev.txt
$env:PYTHONUTF8 = "1" # публичные тесты читают UTF-8 JSON
$env:PYTHONUTF8 = "1"
```
Проверка в браузере: http://127.0.0.1:8080/health/ready → `{"status":"ok"}`; Swagger — http://127.0.0.1:8080/docs; состояние балансировщика (какие реплики UP/DOWN) — http://127.0.0.1:8404/.
Если запущен стенд lab3, он занимает порт 8080: `docker compose -p mtusi-lab3 stop` (данные lab3 сохранятся).
## 3. Перед защитой (в аудитории)
## 3. Перед защитой
```powershell
cd mtusi2026lab3
$env:PYTHONUTF8 = "1"
$env:Path += ";C:\Program Files\Git\usr\bin" # sh для рецептов Makefile
docker compose up -d --wait # если стенд был остановлен
make check test PYTHON=python # или: python scripts\check_contract.py; python tests\smoke.py
cd mtusi2026lab4
$env:PYTHONUTF8 = "1"; $env:Path += ";C:\Program Files\Git\usr\bin"
docker compose up -d --wait
make check test PYTHON=python # или: python tests\smoke.py
python scripts\lbctl.py status # обе реплики UP
```
## 4. Сценарий защиты из README — по шагам
**Шаг 1. ≥ 2 разных `X-Instance-Id` через LB с одной сессией.**
**Шаг 1. Загрузить fixture, отправить сообщение, скачать вторым участником, сравнить SHA-256.**
```powershell
python scripts\lbctl.py replicas # контейнеры api: имя, X-Instance-Id (= hostname), PID, IP
# Один пользователь, один токен, 6 запросов подряд через LB — номера реплик чередуются:
$u = "demo_" + (Get-Random); $p = "Demo-password-123"
Invoke-RestMethod -Method Post http://127.0.0.1:8080/api/v1/users -ContentType 'application/json' -Body (@{username=$u; display_name='Демо'; password=$p} | ConvertTo-Json)
$basic = [Convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes("${u}:${p}"))
$t = (Invoke-RestMethod -Method Post http://127.0.0.1:8080/api/v1/auth/sessions -Headers @{Authorization="Basic $basic"}).token
1..6 | ForEach-Object { (Invoke-WebRequest http://127.0.0.1:8080/api/v1/users/me -Headers @{Authorization="Bearer $t"} -UseBasicParsing).Headers['X-Instance-Id'] }
.venv\Scripts\python scripts\demo_attachments.py
```
Повторный вход не нужен: сессия лежит в общем Valkey. То же автоматически: `.venv\Scripts\python -m pytest student-tests\test_balancing.py -k one_session -v`.
Скрипт печатает каждый запрос и ответ: регистрирует alice, bob и eve, создаёт чат alice+bob, загружает `tests/fixtures/sample.png` (201 ready, sha256), отправляет сообщение с `attachment_ids` и `text=""`. Затем bob скачивает файл, SHA-256 совпадает. Для eve (посторонний) — 404 на метаданные и на байты. Отдельно показано, что ключ объекта в S3 случайный и в API не раскрывается.
**Шаг 2. Отказ реплики публичным тестом.**
**Шаг 2. Прямой неаутентифицированный GET к S3 не отдаёт объект.** Скрипт из шага 1 в конце делает изнутри сети `storage` (снаружи S3 не опубликован) анонимный GET того же объекта и анонимный листинг bucket — оба 403. Тот же GET, подписанный ключом API, — 200. Вручную:
```powershell
docker compose logs s3-init # anonymous GET/LIST -> 403, права ключей api/reconciler
.venv\Scripts\python -m pytest student-tests\test_storage_failures.py -k private -v
```
**Шаг 3. Persistence и failover: общий тест сохраняет и заново читает оригинал через API.**
```powershell
make test-persistence ACTION_SCRIPT=scripts/restart.cmd PYTHON=python # restart lb, api, postgres, valkey, s3
docker compose ps # у всех «Up N seconds»
make test-failover ACTION_SCRIPT=scripts/stop-one.cmd PYTHON=python
# без make: python tests\resilience.py --mode failover --action-script scripts\stop-one.cmd
python scripts\lbctl.py replicas # остановленная — exited
make restore PYTHON=python
```
Тест сам выбирает реплику, обслужившую его первое сообщение, и передаёт её `X-Instance-Id` хуку. Хук останавливает именно этот контейнер и оставляет его остановленным. Вариант «падение процесса» — `$env:STOP_MODE = "kill"` перед командой (SIGKILL), вернуть — `Remove-Item Env:STOP_MODE`.
Для второй реплики: сдвинуть round-robin одним запросом (`Invoke-WebRequest http://127.0.0.1:8080/health/live -UseBasicParsing | Out-Null`) и повторить `make test-failover`. Загрузка → kill обслужившей реплики → скачивание через другую: `.venv\Scripts\python -m pytest student-tests\test_storage_failures.py -k failover -v`.
**Шаг 3. Показать, какой контейнер действительно остановлен, и повторить для второй.**
**Шаг 4. На API нет локального файла оригинала.**
```powershell
python scripts\lbctl.py replicas # у остановленной: exited, exit_code 0 (stop) или 137 (kill)
python scripts\lbctl.py status # её слот в HAProxy — MAINT/DOWN, вторая UP
docker compose logs --tail 20 api # drain_started -> shutdown_requested -> stopped у остановленной
make restore PYTHON=python # или: & "C:\Program Files\Git\bin\bash.exe" scripts/restore-api.sh; python scripts\lbctl.py wait-up 2
make test-failover ACTION_SCRIPT=scripts/stop-one.cmd PYTHON=python
```
Тест останавливает ту реплику, которая обслужила его первое сообщение, поэтому для второй он может снова выбрать прежнюю. Детерминированно по очереди каждую реплику останавливает серия уровня 4 (~5 мин): `python bench\failover_series.py --output evidence\failover` (stop, kill и pause для каждой реплики, с восстановлением предыдущей).
**Шаг 4. Restart всего стенда с сохранением volumes и прежним токеном.**
```powershell
make test-persistence ACTION_SCRIPT=scripts/restart.cmd PYTHON=python
python scripts\lbctl.py replicas # у всех api свежий started и новый PID; LB снова видит обе реплики
docker compose ps # postgres, valkey, lb — тоже «Up N seconds»
.venv\Scripts\python -m pytest student-tests\test_attachments.py -k not_stored -v # find по ФС реплик
docker compose config --format json | Select-String '"volumes"' # у api нет volume
```
**Уровень 4 вживую.**
```powershell
# Неготовая, но живая реплика исключается из LB (pg_hba reject и docker network disconnect), ~1 мин:
.venv\Scripts\python -m pytest student-tests\test_balancing.py -k not_ready -v -s
# Rolling update под нагрузкой (~1,5 мин): новая ревизия на обеих репликах, 0 ошибок
python bench\rolling_under_load.py --output evidence\rolling-update
# Одновременные повторы с одним ключом через разные реплики:
.venv\Scripts\python -m pytest student-tests\test_idempotency.py -k concurrent -v
# Отказ S3 (stop и pause): readiness 503, загрузка 503 за < 8 с, текст работает (деградированный режим LB):
.venv\Scripts\python -m pytest student-tests\test_storage_failures.py -k outage -v
# Сбой между PUT и COMMIT убирает janitor; потерянный ответ после COMMIT ничего не удаляет:
.venv\Scripts\python -m pytest student-tests\test_consistency.py -v
# Все негативные кейсы файлов (413/415/400, чужой чат, MIME):
.venv\Scripts\python -m pytest student-tests\test_attachments.py -v
```
**Трек 1.** Полная серия идёт часы, поэтому на защите — готовые результаты: [evidence/track1/summary.md](../evidence/track1/summary.md) и графики `evidence/track1/*/*/throughput.svg`. Вживую можно показать профиль одной реплики (~2 мин) и одну короткую серию (~6 мин):
**Трек 2 вживую.**
```powershell
docker compose stop # основной стенд не должен мешать замеру
python bench\track1\profile.py --label demo --rate 240
python bench\track1\run.py --series demo --label now --rates 150,250,350 --repeats 1 --config replicas=2,MESSAGE_WRITE_PATH=multi --config replicas=2,MESSAGE_WRITE_PATH=function
docker compose up -d --wait # вернуть основной стенд
docker compose run --rm reconciler # dry-run: отчёт JSON, ничего не меняет
.venv\Scripts\python -m pytest student-tests\test_reconcile.py -k both_sides -v -s # ошибки на обеих сторонах, ~1,5 мин
docker compose run --rm reconciler --apply # исправить (на чистом стенде — 0 действий)
```
**Все свои тесты** (~8 мин): `.venv\Scripts\python -m pytest student-tests -v`.
Готовые отчёты прогонов — [evidence/reconcile/](../evidence/reconcile/), стоимость обхода — [evidence/reconcile/cost.json](../evidence/reconcile/cost.json).
**Все свои тесты** (~25 мин): `.venv\Scripts\python -m pytest student-tests -v`.
## 5. Если что-то пошло не так
| Симптом | Что сделать |
| --- | --- |
| `error during connect … dockerDesktopLinuxEngine` | Docker Desktop не запущен — запустить и подождать минуту |
| `port is already allocated` на 8080/8404 | занято другим стендом (lab2: `docker compose -p mtusi-lab2 stop`) или в `.env` поставить `APP_PUBLISH_PORT=8081`, `LB_STATS_PORT=8405`; тестам — `--base-url http://127.0.0.1:8081` / `$env:BASE_URL` |
| `port is already allocated` на 8080/8404 | занято стендом lab3 (`docker compose -p mtusi-lab3 stop`) или в `.env` поставить `APP_PUBLISH_PORT=8081`, `LB_STATS_PORT=8405` |
| `secrets/... not found` при `up` | не выполнен `python scripts\init_secrets.py` |
| `s3-init` exit 1 | `docker compose logs s3-init`: какая проверка доступа не прошла |
| `UnicodeDecodeError` в `tests\*.py` | не задан `$env:PYTHONUTF8 = "1"` |
| `*.cmd`: «не удаётся найти путь» | Git установлен не в `C:\Program Files\Git` — поправить путь в `scripts\*.cmd` |
| `make: command not found` | новое окно PowerShell после установки make или команды без make из REPORT.md |
| make: `'test' is not recognized` | в этом окне не добавлен `C:\Program Files\Git\usr\bin` в `$env:Path` (рецептам нужен `sh`) |
| после `stop-one` в LB одна реплика | так и задумано; вернуть: `make restore PYTHON=python` |
| api `unhealthy` после сна ноутбука | `docker compose restart` и `python scripts\lbctl.py wait-up 2` |
| нужно начать с чистого листа | `docker compose down -v` (удаляет учебные данные) → `docker compose up -d --build --wait` |
| нужно начать с чистого листа | `docker compose down -v` (удаляет учебные данные, включая bucket) → `docker compose up -d --build --wait` |
Остановить стенд после защиты: `docker compose down` (данные сохранятся) или `docker compose down -v` (данные удаляются).