Files
mtusi2026lab4/REPORT.md
T
Alexey BodanyukandClaude Opus 5.5 277d06f5b5 lab4: слот загрузки держится до конца S3 PUT (буфер жив до него); причины 503 в замере
Замер 32 одновременных загрузок показал: семафор ограничивал только чтение тела, а буферы
копились на этапе S3 PUT (+214 МБ при 4 слотах). Теперь пик при 32 клиентах тот же, что при 16.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-25 14:33:56 +03:00

86 lines
16 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.
# Отчёт — лабораторная 4
- Автор, группа: Боданюк Алексей, БВТ2302
- Целевая оценка: **5**, трек 2 «Согласованность двух хранилищ»
- Ветка: `solution/bvt2302-bodanyuk`. Форк: `https://gitea.privcloud.tech/wfa/mtusi2026lab4`. PR: «ЛР 4 — БВТ2302 — Боданюк — на 5» в mtusi2026/mtusi2026lab4
- Стек: Python 3.13.16, Starlette 1.7.0, uvicorn 0.54.0, psycopg 3.3.6 + psycopg-pool 3.3.3, redis-py 8.1.0, argon2-cffi 25.1.0, **aiobotocore 3.9.2** (S3), **libjpeg-turbo 2.1.5 `djpeg`** (проверка JPEG); PostgreSQL 18.6, Valkey 8.1.3, HAProxy 3.2.26, **SeaweedFS 4.46**. Все образы закреплены по тегу **и** digest, все Python-пакеты — по sha256 ([requirements.txt](requirements.txt)), Debian-пакет — по версии ([Dockerfile](Dockerfile))
- Источники: README, COURSE, контракт ([openapi.json](contracts/openapi.json), [семантика](contracts/README.md)), документация S3 (PutObject/Content-MD5, ListObjectsV2), SeaweedFS (`weed server`, s3.json identities), PNG (RFC 2083 / W3C PNG 3rd ed.: chunks, CRC, zlib, фильтры, Adam7), libjpeg-turbo (`djpeg -strict`, `-scale`, `-maxmemory`), HAProxy 3.2 (`nbsrv`, `use_backend`, `http-request set-timeout`), cgroup v2 (`memory.peak`, `memory.events`). Учтены все замечания преподавателя к PR lab4 других студентов ([раздел ниже](#проверки-на-которых-ловили-другие-работы))
- Помощь ИИ: код, тесты, скрипты экспериментов и черновик отчёта написаны с помощью ИИ-ассистента Claude Code (Anthropic). Все команды и замеры реально выполнены на стенде ниже; вывод — в [evidence/](evidence/). Ответы на вопросы защиты — [docs/DEFENSE.md](docs/DEFENSE.md), согласованность хранилищ — [docs/CONSISTENCY.md](docs/CONSISTENCY.md), запуск на Windows и сценарий защиты — [docs/WINDOWS.md](docs/WINDOWS.md)
## Запуск из чистого clone
Нужны Git, Docker с Compose v2 (проверено: Docker 29.8.0, Compose 5.5.1), Python 3.9+ и GNU make (на Windows — см. [WINDOWS.md](docs/WINDOWS.md)). Учётные данные в Git не хранятся, их создаёт скрипт.
```sh
git clone https://gitea.privcloud.tech/wfa/mtusi2026lab4 mtusi2026lab4 && cd mtusi2026lab4 && git checkout solution/bvt2302-bodanyuk
python3 scripts/init_secrets.py # пароли PostgreSQL/Valkey и ТРИ пары ключей S3 -> ./secrets (git-ignored), идемпотентно
cp .env.example .env
docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build --wait
# postgres, valkey, s3 healthy -> migrate (0001..0004) и s3-init (bucket + проверка прав) exit 0 -> api x2 healthy -> lb
docker compose logs s3-init # anonymous GET/LIST -> 403, права ключей api/reconciler -> OK
make check && make test
make test-persistence ACTION_SCRIPT=scripts/restart.sh
make test-failover ACTION_SCRIPT=scripts/stop-one.sh && make restore
make reconcile # трек 2: dry-run, read-only отчёт JSON
```
- **Windows:** публичным тестам нужен `PYTHONUTF8=1`; хуки — через `scripts/restart.cmd` и `scripts/stop-one.cmd` (тот же `.sh` в Git Bash).
- **Свои тесты:** `python3 -m venv .venv`, `pip install --require-hashes --no-deps -r requirements.txt`, `pip install -r requirements-test.txt`, затем `make student-test` (~25 мин, стенд должен быть поднят). Без стенда — `make unit-test`.
- **Все доказательства одной командой** (на чистом clone, ~70 мин): `python scripts/collect_evidence.py`.
- **Bootstrap S3** — одноразовый сервис `s3-init` (`python -m messenger.s3_bootstrap`), идемпотентный: существующий bucket не трогает, sentinel-объект перезаписывает, затем проверяет модель доступа и **валит стенд** (exit 1), если bucket не приватный или у ключей лишние права. Повтор: `docker compose run --rm s3-init`.
- **Остановка:** безопасно — `docker compose down` (volumes `pgdata`, `valkeydata`, `s3data` сохраняются). Намеренное удаление учебных данных — `docker compose down -v` и `rm -rf secrets`.
## Архитектура и решения
```text
клиент ──127.0.0.1:8080──> lb: HAProxy 3.2 ──edge──> api × 2 (Starlette, без состояния и без volume)
│ backend api: /health/ready (PG + Valkey + S3) │
│ backend api_core: /health/ready/core (PG + Valkey) — только если ├─data (internal)──> postgres 18.6: users, chats, messages, attachments (метаданные)
│ в api нет ни одного UP (S3 упал у всех) │ valkey 8.1.3: сессии
└ upload: timeout server 60 s └─storage (internal)─> s3: SeaweedFS 4.46, bucket messenger-attachments (байты)
migrate ──data──> 0001…0004 s3-init ──storage──> bucket, sentinel, проверка прав reconciler (по требованию) ──data+storage──> сверка
```
| Роль | Service | Образ | Health / readiness | Volume | Сеть / порт | Credentials | CPU / RAM |
| --- | --- | --- | --- | --- | --- | --- | --- |
| Точка входа | `lb` | `haproxy:3.2.26-alpine@sha256:254e6370…` | `haproxy -c` + stats; бэкенды — активные проверки | — | edge; `127.0.0.1:8080`, `[::1]:8080`, `127.0.0.1:8404` | нет | 1.0 / 128m |
| API × 2 | `api` | `mtusi-messenger:lab4` из исходников | `/health/ready` (PG, Valkey, S3) | — | edge + data + storage, только `expose 8080` | `database_url`, `cache_url`, **своя** пара S3 (Read+Write bucket) | 1.0 / 512m, без swap |
| Миграции | `migrate` | тот же образ | exit 0 | — | data | `database_url` | 0.5 / 256m |
| Bootstrap S3 | `s3-init` | тот же образ | exit 0 | — | storage | admin + api + reconciler (для проверки прав) | 0.5 / 256m |
| БД | `postgres` | `postgres:18.6-bookworm@sha256:afc7e2d4…` | `pg_isready` | `pgdata` | data | `postgres_password` | 2.0 / 1g |
| Сессии | `valkey` | `valkey/valkey:8.1.3-bookworm@sha256:fea8b3e6…` | `valkey-cli ping` | `valkeydata` | data | `valkey_password` | 0.5 / 256m |
| Объекты | `s3` | `chrislusf/seaweedfs:4.46@sha256:08d51613…` | `GET /healthz` | `s3data` | storage, `8333` (S3 API) — не опубликован | identities из secrets ([start.sh](infra/seaweedfs/start.sh)) | 1.0 / 1g |
| Сверка (трек 2) | `reconciler` (профиль `tools`) | тот же образ | — | — | data + storage | `database_url`, пара S3 reconciler (+List) | 1.0 / 256m |
**Что перенесено из lab3** (отдельный коммит `d916d09`, без изменений): API, миграции 0001–0003, HAProxy без sticky с re-resolve DNS, общая идемпотентность, graceful shutdown, сессии в Valkey, все тесты lab3. **Что сделано в lab4:**
- **Выбор S3: SeaweedFS 4.46.** Репозитория `minio/minio` в Docker Hub больше нет (проверено при выборе), SeaweedFS активно развивается и поддерживает identity с правами на bucket. Один контейнер (`weed server`: master + volume + filer + S3 gateway). Web-интерфейсы master/filer/volume и их gRPC слушают **только 127.0.0.1 внутри контейнера** (`-ip.bind`), в сеть `storage` выходит лишь S3 API (8333/18333). Сеть internal, на хосте ничего не опубликовано. Телеметрия выключена, встроенный IAM API выключен, автосоздание bucket выключено.
- **Права.** Три пары ключей (`init_secrets.py`): `admin` (создание bucket) — только у `s3` и `s3-init`; `messenger-api` — `Read`+`Write` **на один bucket**, без `List` и `Admin`; `messenger-reconciler` — плюс `List`. Анонимной identity нет, поэтому bucket приватный. `s3-init` проверяет всё это при каждом запуске, включая канареечный bucket: API не видит его в ListBuckets и не может читать из него (403).
- **Модель данных** ([0004_attachments.sql](migrations/0004_attachments.sql), [DATA_MODEL.md](docs/DATA_MODEL.md)): `attachments` (метаданные; `object_key = o/<128 случайных бит>` назначает сервер; `status pending|ready`; карантин `lost_at/lost_reason`), `message_attachments` (FK + обратный поиск), `messages.attachment_ids uuid[]` (порядок, чтение истории остаётся одним index range scan). Отправка сообщения — SQL-функция `post_message_v2`, тоже одна транзакция.
- **Загрузка** ([attachments.py](src/messenger/attachments.py), [images.py](src/messenger/images.py)): `auth → членство (404) → filename / Content-Type / Content-Length (400/415/413) → слот загрузки → тело кусками с дедлайном → формат и пиксели по первым байтам → полная проверка → pending → PUT → ready → 201`. Подробно о порядке и сбоях — [CONSISTENCY.md](docs/CONSISTENCY.md).
- **Проверка содержимого.** PNG — свой потоковый валидатор: сигнатура, CRC **каждого** chunk, порядок chunk'ов, zlib-поток IDAT распаковывается порциями по 1 MiB и сразу выбрасывается, его длина должна быть ровно `height × (1 + байт в строке)` (Adam7 — по проходам), байт фильтра каждой строки ≤ 4, IEND в конце и ничего после него. Растр в памяти не создаётся. JPEG — `djpeg -strict -scale 1/8 -maxmemory`: эталонный декодер в отдельном процессе декодирует весь файл, любое предупреждение libjpeg — ошибка. Pillow для этого не годится: JPEG без данных после SOS он «успешно» декодирует в серую картинку (проверено). MIME определяется по байтам; несовпадение с `Content-Type` — 415.
- **Лимиты до чтения/декодирования.** `Content-Length > 10 MiB` → 413 без чтения тела; без длины (chunked) — 413 при пересечении лимита. Пиксели — из IHDR/SOFn по первым байтам: 20000×10000 → 413 через 33 байта, ничего не декодируется. Тело — один буфер ровно `Content-Length` байт (без копий до S3 и djpeg). Одновременно на реплику: `UPLOAD_CONCURRENCY=4` тела (остальные ждут ≤ 5 с с байтами в TCP-буфере, затем 503 + `Retry-After`), `IMAGE_VERIFY_CONCURRENCY=1` полная проверка. Дедлайны: тело 30 с, проверка 10 с, S3 3 с (+ время на объём), в HAProxy для загрузки `timeout server 60s`.
- **Скачивание** — только через API, без redirect: членство → `GET` объекта → стриминг кусками по 64 KiB (память не зависит от размера). Заголовки: настоящий `Content-Type`, `Content-Length`, `Content-Disposition: attachment` (ASCII-fallback + RFC 5987), `X-Content-Type-Options: nosniff`, `Cache-Control: private, no-store`, `ETag` = SHA-256.
- **Готовность и деградированный режим.** `/health/ready` включает S3 (загрузка и скачивание — обязательный синхронный путь): S3 недоступен → 503. S3 — общая зависимость, и если он упал у всех, HAProxy переключается на backend `api_core` (проверка `/health/ready/core`: PG + Valkey). Чаты и текст работают, запросы к вложениям API сам отвечает 503 за ≤ 3 с. Если S3 потеряла одна реплика, она DOWN в `api`, трафик идёт на другую.
- **Janitor** (в каждой реплике, раз в ~60 с, advisory-замок): `pending` старше `PENDING_GRACE_SECONDS=900` → под `FOR UPDATE SKIP LOCKED` удалить объект, затем строку.
- **Reconciler (трек 2)** — [reconcile.py](src/messenger/reconcile.py), раздел «Трек 2» ниже.
- **`FAULT_POINTS`** (`after_s3_put`, `after_ready_commit`) — внедрение отказа ровно между шагами записи, только для экспериментов. По умолчанию пусто; неизвестное значение — ошибка конфигурации.
Readiness-критичные зависимости: PostgreSQL, Valkey и S3. LB в деградированном режиме обходится без S3.
Соответствие `.env.example` реальной конфигурации ([config.py](src/messenger/config.py), [compose.yaml](compose.yaml)):
| Переменная | Значение | Где используется |
| --- | --- | --- |
| `APP_HOST`, `APP_PORT`, `APP_ENV`, `SESSION_TTL_SECONDS`, `DATABASE_URL_FILE`, `SESSION_STORE`, `CACHE_URL_FILE`, `API_REPLICAS`, `IDEMPOTENCY_TTL_SECONDS` | как в lab3 | без изменений |
| `S3_ENDPOINT`, `S3_REGION`, `S3_BUCKET` | `http://s3:8333`, `us-east-1`, `messenger-attachments` | клиент S3 API, s3-init, reconciler; bucket создаёт s3-init |
| `S3_ACCESS_KEY_ID_FILE`, `S3_SECRET_ACCESS_KEY_FILE` | `/run/secrets/s3_access_key_id`, `…/s3_secret_access_key` | у API это **его** пара (secrets `s3_api_*` смонтированы под этими именами), у reconciler — его пара |
| `MAX_UPLOAD_BYTES`, `MAX_IMAGE_PIXELS` | `10485760`, `40000000` | лимиты контракта; можно уменьшить, увеличить нельзя (ConfigError) |
| `UPLOAD_CONCURRENCY`, `UPLOAD_QUEUE_TIMEOUT_SECONDS`, `UPLOAD_READ_TIMEOUT_SECONDS` | `4`, `5`, `30` | слоты загрузки на реплику, ожидание слота, дедлайн тела |
| `IMAGE_VERIFY_CONCURRENCY`, `IMAGE_VERIFY_TIMEOUT_SECONDS`, `JPEG_MAX_MEMORY_MB` | `1`, `10`, `256` | одновременные полные проверки, дедлайн проверки, `djpeg -maxmemory` |
| `S3_TIMEOUT_SECONDS` | `3` | дедлайн каждого вызова S3 (PUT — плюс время на объём) |
| `PENDING_GRACE_SECONDS`, `JANITOR_INTERVAL_SECONDS` | `900`, `60` | janitor незавершённых загрузок |
| `FAULT_POINTS` | пусто | внедрение отказов в экспериментах |
| `API_CPUS/MEMORY`, `S3_CPUS/MEMORY`, `PG_*`, `VALKEY_CPUS`, `LB_CPUS` | 1.0/512m, 1.0/1g, 2.0/1g, 0.5, 1.0 | лимиты контейнеров |