# Отчёт — лабораторная 4 - Автор, группа: Ким Владимир, БВТ2302 - Целевая оценка; 3 - Commit/PR: ветка `solution/bvt2302-kim`; PR в исходный репозиторий открывается после push. - Использованные источники, библиотеки и помощь ИИ: контракт и рубрика репозитория; документация S3 (upload/presigned), SeaweedFS (S3 gateway, `s3.json` identities), boto3/botocore, psycopg 3, Pillow, HAProxy. ## Запуск из чистого clone Версии закреплены: | Роль | Образ | Версия | | --- | --- | --- | | API | `python:3.12.7-slim-bookworm` (digest `sha256:60d9996b6a8a3689d36db740b49f4327be3be09a21122bd02fb8895abb38b50d`) + `requirements.txt` | boto3 1.35.36, Pillow 11.0.0, psycopg 3.2.3, psycopg_pool 3.2.3 | | PostgreSQL | `postgres:16.4-alpine` | 16.4 | | S3 | `chrislusf/seaweedfs:3.71` | 3.71 | | Load balancer | `haproxy:3.0.8-alpine` | 3.0.8 | ```sh # 1. Локальная конфигурация: секреты только в .env, файл в Git не попадает. cp .env.example .env # Отредактировать пароли/секреты. Для локального стенда достаточно синтетических значений. # 2. Проверка структуры и конфигурации Compose. python scripts/check_contract.py python scripts/validate_openapi.py # требует requirements-dev.txt # На Windows глобальный Python может не иметь openapi-spec-validator; # полная валидация выполнялась интерпретатором из .venv: # .\.venv\Scripts\python.exe scripts/validate_openapi.py docker compose --env-file .env config --quiet # 3. Сборка и запуск. Bucket создаёт one-shot контейнер `bootstrap`; схему # PostgreSQL мигрирует каждая API-реплика при старте (идемпотентно, под # advisory lock). docker compose --env-file .env up -d --build # 4. Готовность (PostgreSQL + S3). LAB4_PORT по умолчанию 8080; # на машине автора порт 8080 занят стендом lab3, поэтому в .env стоит 8081. curl -fsS http://127.0.0.1:8081/health/ready # 5. Публичный smoke и собственные проверки. python tests/smoke.py --base-url http://127.0.0.1:8081 python -m unittest discover -s student-tests -v python student-tests/test_api_negative.py --base-url http://127.0.0.1:8081 # 6. Сценарии отказов (явные, останавливают инфраструктуру). python tests/resilience.py --mode persistence --action-script scripts/restart.cmd --base-url http://127.0.0.1:8081 python tests/resilience.py --mode failover --action-script scripts/stop-one.cmd --base-url http://127.0.0.1:8081 python scripts/evidence_s3_outage.py ``` `scripts/restart.sh` / `scripts/stop-one.sh` — POSIX-варианты для Linux/macOS (`chmod +x` нужен перед запуском). `scripts/restart.cmd` / `scripts/stop-one.cmd` — эквиваленты для Windows: тест запускает hook без shell interpolation, поэтому на Windows нужен исполняемый файл с расширением `.cmd`. Безопасная остановка (данные сохраняются): ```sh docker compose --env-file .env stop ``` Намеренное удаление учебных данных (необратимо, только для локального стенда): ```sh docker compose --env-file .env down -v ``` ## Архитектура и решения ``` клиент ──HTTP──> HAProxy :8080 ──> api1:8080 ─┐ │ ├──> PostgreSQL (users, chats, members, └────────> api2:8080 ────┘ messages, attachments, idempotency) └──> SeaweedFS S3 :8333 (приватный bucket, только байты изображений) ``` - **Источник истины** — PostgreSQL. Метаданные вложения (`id`, `chat_id`, `owner_id`, `filename`, `content_type`, `size_bytes`, `sha256`, `object_key`, `status`, `variants`, `error_code`, таймстемпы) хранятся только там. Байты — только в приватном bucket; локального каталога с оригиналами у API нет. - **Object key** назначает сервер: `chats///original`. `filename` — только отображаемое имя, в путь/ключ не попадает. - **Транзакционные границы.** Upload: проверка доступа и лимитов → проверка изображения → `PUT` в S3 → `INSERT` метаданных в PostgreSQL. Если `INSERT` не удался, объект удаляется компенсацией (`app/server.py`, `_upload_attachment`), поэтому неучтённых объектов не остаётся. Обратный случай (метаданные без объекта) виден как `404` на download и не превращается в 500. - **201 ready** возвращается только после успешной записи объекта и метаданных, то есть когда оригинал действительно доступен любой реплике. - **Идемпотентность сообщений.** Таблица `idempotency(user_id, chat_id, key)` + транзакционный advisory lock по SHA-256 области уникальности; сообщение и запись результата создаются в одной транзакции, повтор с другим body — `409`. - **Сессии.** Непрозрачный токен (32 случайных байта, base64url), в БД только SHA-256 токена и expiry. TTL — `SESSION_TTL_SECONDS` (по умолчанию 3600). - **Пароли** — `scrypt` (N=2^14, r=8, p=1) с солью, сравнение `hmac.compare_digest`; для неизвестного username выполняется фиктивная проверка, чтобы не выдавать существование пользователя по времени. - **Курсоры пагинации** — HMAC-подписанный base64url JSON с `(created_at, id)` и привязкой к ресурсу (`kind`, `chat_id`); чужой/испорченный курсор — `400`. - **Readiness.** `/health/ready` проверяет PostgreSQL и S3, потому что обязательный синхронный путь включает скачивание оригинала. При недоступности S3 реплики исключаются из LB, клиент получает `503`; это осознанный выбор, зафиксированный в `app/server.py`. - **Лимиты.** `Content-Length`/chunked чтение ограничены `MAX_UPLOAD_BYTES` (10 MiB) до чтения тела; MIME проверяется по магическим байтам, число пикселей — по заголовку изображения до полного декодирования (`MAX_IMAGE_PIXELS` = 40 млн). Полное тело ограничено 10 MiB, поэтому RAM одной загрузки ограничена сверху; download идёт чанками по 64 KiB. - **Инфраструктура.** SeaweedFS запускается одним процессом `weed server` с master/volume/filer/S3. Административная идентичность (`S3_ADMIN_*`) используется только one-shot `bootstrap`; API использует отдельную идентичность с действиями `Read`/`Write`/`List`/`Tagging`. Bucket создаётся идемпотентно (`app/bootstrap_s3.py`: `head_bucket` → `create_bucket`, повторный запуск безопасен). Порт S3 и внутренние порты API не публикуются на хост; наружу открыт только LB (loopback). - **LB.** HAProxy в режиме HTTP с `option http-server-close`: без него клиентские keep-alive соединения закреплялись за одной репликой и roundrobin не наблюдался. Имена реплик разрешаются через DNS Docker (`resolvers docker`, `init-addr none`) с периодическим переразрешением: иначе HAProxy запоминал IP, полученный при одновременном старте, и после пересоздания контейнера мог ходить не туда. `timeout connect 500ms`, `retries 2`, `option redispatch` и частые health-check дают переключение на живую реплику за единицы секунд. Соответствие переменных `.env.example` реальной конфигурации: | Переменная | Где используется | | --- | --- | | `APP_HOST`, `APP_PORT` | адрес прослушивания API (`app/config.py`) | | `DATABASE_URL` | строка подключения psycopg (в Compose собирается из `POSTGRES_*`) | | `POSTGRES_USER`, `POSTGRES_PASSWORD`, `POSTGRES_DB` | сервис PostgreSQL и сборка `DATABASE_URL` | | `S3_ENDPOINT`, `S3_REGION`, `S3_BUCKET` | клиент S3 и bootstrap | | `S3_ACCESS_KEY_ID`, `S3_SECRET_ACCESS_KEY` | идентичность API в `s3.json` SeaweedFS | | `S3_ADMIN_ACCESS_KEY_ID`, `S3_ADMIN_SECRET_ACCESS_KEY` | идентичность one-shot bootstrap | | `SESSION_TTL_SECONDS`, `IDEMPOTENCY_TTL_SECONDS` | TTL сессий и окно идемпотентности | | `MAX_UPLOAD_BYTES`, `MAX_IMAGE_PIXELS` | лимиты загрузки | | `CURSOR_SECRET` | HMAC-подпись курсоров, одинаковый у всех реплик | | `LAB4_PORT` | host-порт LB (по умолчанию 8080, у автора 8081) | Приложение также поддерживает `*_FILE`-варианты секретов (`DATABASE_URL_FILE`, `S3_SECRET_ACCESS_KEY_FILE` и т.д.) на случай запуска вне Compose. ## Доказательства критериев | Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства | | --- | --- | --- | --- | | Офлайн-структура контракта | `python scripts/check_contract.py` | `PASS: offline skeleton structure...` | `evidence/check-contract.txt` | | Полная валидация OpenAPI 3.1 | `python scripts/validate_openapi.py` (после `requirements-dev.txt`) | `PASS: full OpenAPI 3.1 and JSON Schema validation` | `evidence/validate-openapi.txt` | | Compose-конфигурация | `docker compose --env-file .env config --quiet` | exit 0, ошибок нет | вывод команды в логе работы | | Публичный smoke (health, users, sessions, chats, messages, pagination, idempotency, upload/download, SHA-256, чужой доступ, logout) | `python tests/smoke.py --base-url http://127.0.0.1:8081` | `PASS: lab4 public API scenario` | `evidence/smoke.txt` | | S3-сервер в общем стенде, приватный bucket | `docker compose ps`; `python scripts/verify_private_bucket.py` (внутри сети) | объекты в bucket есть; анонимный GET объекта — `403`, анонимный list — `403` | `evidence/docker-ps.txt`, `evidence/private-bucket.txt` | | Метаданные в PostgreSQL, байты не в БД/локальном каталоге | `\d attachments`; поиск файлов в контейнере API | таблица `attachments` без BLOB-колонок; в `/app` только код, оригиналов нет | `evidence/db-schema.txt` | | 201 ready после сохранения; побайтное скачивание PNG и JPEG | smoke + `student-tests/test_api_negative.py` | `status=ready`, SHA-256 и размер совпадают, скачанные байты идентичны; отдельный сценарий реального JPEG 640×480 проходит загрузку и скачивание | `evidence/smoke.txt`, `evidence/negative.txt` | | Message с `attachment_ids` читается участниками чата | `student-tests/test_api_negative.py` (сценарий `attachment_ids survive message history`) | элемент истории совпадает с ответом POST, `attachment_ids` сохранены | `evidence/negative.txt` | | PNG/JPEG ≤10 MiB и ≤40 млн пикселей; MIME по содержимому; опасные filename; лимиты до декодирования | `python student-tests/test_api_negative.py --base-url ...` | 12/12 сценариев PASS: 413 на размер и пиксели, 415 на битый файл/подмену MIME, 400 на `/`, `\`, NUL, LF | `evidence/negative.txt` | | Чужой чат и чужое вложение | smoke (`eve` → 404), `test_api_negative.py` | `404` на метаданные и bytes, `404` при привязке вложения другого чата, сообщение не создаётся | `evidence/smoke.txt`, `evidence/negative.txt` | | Upload → остановка обслужившей реплики → download через другую | `tests/resilience.py --mode failover --action-script scripts/stop-one.cmd` | 2 реплики до отказа, 112 успешных записей, 0 неопределённых ошибок, восстановление 2.33 с, остановленная реплика не обслуживает, вложение скачано через другую | `evidence/failover.txt` | | Restart стенда с сохранением volumes | `tests/resilience.py --mode persistence --action-script scripts/restart.cmd` | сессия и данные живы, оригинал скачан побайтно после рестарта всех сервисов | `evidence/persistence.txt` | | Недоступность S3 | `python scripts/evidence_s3_outage.py` | readiness `503`, upload/download `503` (в т.ч. JSON `unavailable` с `X-Request-Id` от реплики), после старта S3 оригинал идентичен | `evidence/s3-outage.txt` | | Unit-проверки валидаторов | `python -m unittest discover -s student-tests -v` | 6 тестов OK (пароли, курсоры, изображения, filename) | `evidence/unit-tests.txt` | Дополнительно: `make test BASE_URL=http://127.0.0.1:8081`, `make test-negative`, `make student-tests` — те же сценарии через Makefile. `make check` требует UTF-8 режим Python на Windows (`PYTHONUTF8=1`), иначе `contracts/openapi.json` читается в cp1251. На машине автора `make` не установлен, поэтому все результаты выше получены прямыми командами из блока «Запуск из чистого clone»; цели Makefile — эквивалентные обёртки для POSIX-окружения. ## Эксперименты и отказы Аппаратура: AMD Ryzen 7 7700 (8C/16T), 31.1 GiB RAM, Docker Desktop 29.4.3, Windows 11. Лимиты CPU/RAM контейнерам не задавались (учебный локальный стенд). Данные синтетические. | Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных | | --- | --- | --- | --- | | `docker stop` обслужившей API-реплики во время потока POST | LB уводит трафик на вторую реплику, подтверждённые сообщения не теряются, дублей нет | 2 реплики наблюдались до отказа; 112 успешных записей за 15 с, 0 ошибок; первая успешная запись после старта hook — 2.33 с; остановленная реплика отсутствует в последних ответах. В более ранних прогонах (до настройки `timeout connect`/health-check) было 58–59 записей и 2–4 ошибки переходного периода, дублей не возникало ни разу | восстановление 2.3 с (ранее 5.3–7.4 с); потерь подтверждённых данных нет | | Рестарт `postgres`, `seaweedfs`, `haproxy`, `api1`, `api2` с теми же volumes | сессия, чат, сообщения, метаданные и оригинал сохраняются | `PASS: persistence preserved confirmed data and existing session`; download после рестарта побайтно совпал | простой на время рестарта (~10–20 с); потерь нет | | Остановка S3 (`docker stop lab4-seaweedfs`) | attachment endpoints отвечают 503, метаданные остаются, данные не теряются | LB `/health/ready` → 503; upload и download → 503; прямой запрос к реплике: метаданные `200`, content `503` с `error_code=unavailable`; после старта S3 оригинал идентичен | после старта S3 готовность вернулась; потерь нет | | Повторная загрузка с тем же `Idempotency-Key` и другим body | 409 без второго сообщения | `409 conflict` в smoke | — | Ограничения измерений: отдельный нагрузочный эксперимент (RPS/p50/p95/p99, пик RAM при ≥10 одновременных загрузках) **не проводился**, так как он относится к уровню 4. Числа failover — это наблюдения нескольких локальных прогонов, а не гарантия SLA: LB, PostgreSQL и S3 развёрнуты на одном Docker-host, поэтому потеря хоста не выдерживается. ## Ограничения и следующие шаги - Заявлен и реализован уровень **3**. Инженерно закрыты отдельные практики уровня 4 (компенсация при сбое между S3 и PostgreSQL, отдельная ограниченная идентичность API, проверка приватности bucket, расширенные негативные тесты), но полный уровень 4 не заявляется: нет документированного reconciler с grace period и эксперимента с ≥10 одновременными загрузками и измерением пика RAM. - Изображение читается в память целиком, но не более 10 MiB на запрос; потоковая обработка тела загрузки и вынесение декодирования в отдельный процесс — следующий шаг. - Rate limiting (`429`) не реализован: схема допускает код, но рубрика уровня 3 его не требует. - Сессии хранятся в PostgreSQL; отдельный Redis/Valkey не используется. - Один Docker-host: отказ диска/host/сети не выдерживается; HA PostgreSQL и LB не заявляются. - Компенсация покрывает сбой между `PUT` в S3 и `COMMIT` в PostgreSQL. Полная сверка «БД ↔ S3» (reconciler с dry-run и grace period) — трек 2 уровня 5, он не реализован. - Ключи и пароли в `.env` — синтетические локальные значения; `.env` в Git не попадает.