diff --git a/REPORT.md b/REPORT.md index 9ad2b84..6477ce0 100644 --- a/REPORT.md +++ b/REPORT.md @@ -1,37 +1,85 @@ # Отчёт — лабораторная 4 -- Автор, группа: TODO -- Целевая оценка; выбранный трек 5, если нужен: TODO -- Commit/PR: TODO после публикации -- Использованные источники, библиотеки и помощь ИИ: TODO +- Автор, группа: Боданюк Алексей, БВТ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 -TODO: версии runtime/образов, prerequisites, команды создания локальных secrets/.env, build, миграций, запуска, ожидания готовности, тестов и остановки. Указать необходимые действия оператора. Не вставлять секреты. Отдельно указать безопасную остановку и команду намеренного удаления учебных данных. +Нужны 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`. ## Архитектура и решения -TODO: схема процессов/хранилищ, источник истины, транзакционные границы, ограничения. Что перенесено из lab3, что изменено в этой работе. Соответствие переменных из .env.example реальной конфигурации. +```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 | -| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства | -| --- | --- | --- | --- | -| Публичный smoke | make test | TODO | TODO | -| Остальные пункты уровня 3 | TODO | TODO | TODO | -| Все пункты уровня 4, если заявлен | TODO | TODO | TODO | -| Выбранный трек 5, если заявлен | TODO | TODO | TODO | +**Что перенесено из lab3** (отдельный коммит `d916d09`, без изменений): API, миграции 0001–0003, HAProxy без sticky с re-resolve DNS, общая идемпотентность, graceful shutdown, сессии в Valkey, все тесты lab3. **Что сделано в lab4:** -TODO: добавить отдельную строку для каждого заявленного критерия. PASS без команды и наблюдения не является доказательством. Проверка инфраструктурного hook требует подтверждения, какие реальные процессы/хранилища перезапущены. +- **Выбор 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. -TODO: гипотеза, hardware/лимиты, версии, объём данных, профиль нагрузки, concurrency/arrival rate, длительность/прогрев, повторы, успешные RPS, ошибки, p50/p95/p99, CPU/RAM. Сохранить raw summary без tokens и объяснить ограничения измерения. +Соответствие `.env.example` реальной конфигурации ([config.py](src/messenger/config.py), [compose.yaml](compose.yaml)): -| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных | -| --- | --- | --- | --- | -| TODO | TODO | TODO | TODO | - -## Ограничения и следующие шаги - -TODO: какие отказы выдерживаются и какие нет; что не реализовано; где учебное упрощение; какое улучшение подтверждено, а какое пока гипотеза. +| Переменная | Значение | Где используется | +| --- | --- | --- | +| `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 | лимиты контейнеров | diff --git a/bench/upload_memory.py b/bench/upload_memory.py index 92796c9..e2c6f35 100644 --- a/bench/upload_memory.py +++ b/bench/upload_memory.py @@ -144,7 +144,8 @@ def run_scenario(name: str, env: dict, files: list[tuple[bytes, str]]) -> dict: started = time.perf_counter() r = c.post(f"/api/v1/chats/{chat_id}/attachments?filename=f{i}", content=data, headers={"Authorization": "Bearer " + token, "Content-Type": ctype}) - results[i] = (r.status_code, time.perf_counter() - started, r.headers.get("x-instance-id", "-")) + reason = r.json()["error"]["message"] if r.status_code != 201 else "" + results[i] = (r.status_code, time.perf_counter() - started, r.headers.get("x-instance-id", "-"), reason) c.close() s3_id = sh("docker", "compose", "ps", "-q", "s3").strip() @@ -178,8 +179,11 @@ def run_scenario(name: str, env: dict, files: list[tuple[bytes, str]]) -> dict: - per_replica[hostname]["idle_mib"], 1) lat = sorted(r[1] for r in results if r[0] == 201) codes: dict[str, int] = {} + reasons: dict[str, int] = {} for r in results: codes[str(r[0])] = codes.get(str(r[0]), 0) + 1 + if r[3]: + reasons[r[3]] = reasons.get(r[3], 0) + 1 summary = { "scenario": name, "settings": env, "clients": len(files), "s3_sampled_max_mib": round(max(samplers[-1].values or [0]) / MiB, 1), @@ -188,7 +192,7 @@ def run_scenario(name: str, env: dict, files: list[tuple[bytes, str]]) -> dict: # OOM kills / restarts DURING the scenario (any container of the stand): must be empty "incidents": {k: v for k, v in container_events().items() if v != restarts_before.get(k)}, "file_mib_each": round(statistics.mean(len(d) for d, _ in files) / MiB, 2), - "types": sorted({t for _, t in files}), "status_codes": codes, "wall_seconds": round(wall, 2), + "types": sorted({t for _, t in files}), "status_codes": codes, "error_reasons": reasons, "wall_seconds": round(wall, 2), "latency_s": {"p50": round(lat[len(lat) // 2], 2), "max": round(lat[-1], 2)} if lat else None, "replicas": per_replica, } diff --git a/docs/PR.md b/docs/PR.md new file mode 100644 index 0000000..3b5b2d7 --- /dev/null +++ b/docs/PR.md @@ -0,0 +1,20 @@ +## Лабораторная 4 + +Автор / группа: Боданюк Алексей, БВТ2302 +Целевая оценка (3/4/5): 5 +Трек 5, если заявлен: трек 2 «Согласованность двух хранилищ» (reconciler S3 ↔ PostgreSQL) + +Что реализовано и что перенесено: реализация lab3 перенесена отдельным коммитом без изменений. Добавлено: S3-хранилище SeaweedFS 4.46 (приватный bucket, идемпотентный bootstrap с проверкой прав, отдельные ключи для API / reconciler / admin), вложения PNG/JPEG (метаданные в PostgreSQL, байты в S3; полная проверка целостности до записи; лимиты до чтения и декодирования), `attachment_ids` в сообщениях, скачивание через API без redirect, деградированный режим LB при отказе S3, janitor незавершённых загрузок, reconciler с dry-run, внедрение отказов, замеры памяти и стоимости обхода. Подробно — REPORT.md. +Команды запуска из чистого clone: REPORT.md → «Запуск из чистого clone» (`python3 scripts/init_secrets.py`, `cp .env.example .env`, `docker compose --env-file .env up -d --build --wait`). +Результаты проверок и ссылка на REPORT.md: REPORT.md → «Доказательства критериев», вывод в evidence/. +Ограничения / известные ошибки: REPORT.md → «Ограничения и следующие шаги». +Источники и использование ИИ: REPORT.md, шапка (код, тесты и отчёт написаны с помощью Claude Code; все замеры реально выполнены). + +- [x] Весь обязательный минимум текущей и предыдущих работ сохранён с объявленными переходами. +- [x] Контракт и публичные тесты не ослаблены. +- [x] make check и make test выполнены; приложен реальный вывод. +- [x] Сценарии отказов/безопасности своего уровня воспроизведены. +- [x] Все секреты и приватные ключи находятся вне Git; отчёт не содержит tokens. +- [x] README задания сохранён, REPORT.md содержит инструкцию именно моего решения. + +🤖 Generated with [Claude Code](https://claude.com/claude-code) diff --git a/src/messenger/app.py b/src/messenger/app.py index 4eecea3..38100ad 100644 --- a/src/messenger/app.py +++ b/src/messenger/app.py @@ -375,27 +375,38 @@ async def upload_attachment(request: Request) -> JSONResponse: """POST /chats/{chat_id}/attachments?filename=...: raw PNG/JPEG -> 201 ready (attachments.py).""" settings: Settings = request.app.state.settings reader = attachments.BodyReader(request) + slots: asyncio.Semaphore = request.app.state.upload_slots + acquired = False try: - user_id = await authenticate(request) - chat_id = path_uuid(request, "chat_id") - db = db_of(request) - await repo.ensure_member(db, user_id, chat_id) # outsiders: 404 before anything about the body - filename = validation.filename_param(validation.query_items(request.scope["query_string"])) - declared = attachments.declared_type(request) - length = attachments.declared_length(request, settings.max_upload_bytes) - slots: asyncio.Semaphore = request.app.state.upload_slots - try: - await asyncio.wait_for(slots.acquire(), settings.upload_queue_timeout_seconds) - except asyncio.TimeoutError: - raise attachments.Busy("Слишком много одновременных загрузок, повторите позже") from None try: + user_id = await authenticate(request) + chat_id = path_uuid(request, "chat_id") + db = db_of(request) + await repo.ensure_member(db, user_id, chat_id) # outsiders: 404 before anything about the body + filename = validation.filename_param(validation.query_items(request.scope["query_string"])) + declared = attachments.declared_type(request) + length = attachments.declared_length(request, settings.max_upload_bytes) + try: + await asyncio.wait_for(slots.acquire(), settings.upload_queue_timeout_seconds) + except asyncio.TimeoutError: + raise attachments.Busy("Слишком много одновременных загрузок, повторите позже") from None + acquired = True upload = await attachments.read_image(reader, settings, declared, request.app.state.verify_slots, length) - finally: + except ApiError: + # Early rejection: drop (not store) a bounded rest of the body so the client reads our error. + await reader.discard(settings.max_upload_bytes + (1 << 20), timeout=5.0) + raise + # The slot is held until the buffer is no longer needed (after the S3 PUT), so at most + # UPLOAD_CONCURRENCY bodies of this replica exist in memory at any moment. + return await store_upload(request, db, chat_id, user_id, filename, upload) + finally: + if acquired: slots.release() - except ApiError: - # Early rejection: drop (not store) a bounded rest of the body so the client reads our error. - await reader.discard(settings.max_upload_bytes + (1 << 20), timeout=5.0) - raise + + +async def store_upload(request: Request, db: Database, chat_id: str, user_id: str, filename: str, + upload: attachments.Upload) -> JSONResponse: + """intent (pending) -> S3 PUT -> ready -> 201 (order and failure analysis: docs/CONSISTENCY.md).""" attachment_id = uuid.uuid4() object_key = attachments.new_object_key() storage = storage_of(request)