Files
mtusi2026lab4/REPORT.md
drunkdiente 935307d412 Реализовать ЛР4: S3-хранилище и вложения на оценку 3
Стенд: PostgreSQL 16 + две API-реплики за HAProxy + SeaweedFS S3 в приватном bucket. Метаданные вложений в PostgreSQL, байты в S3, object key назначает сервер. Лимиты 10 MiB и 40 млн пикселей, MIME по магическим байтам, проверка filename. Добавлены smoke/негативные тесты, хуки restart/stop-one, сценарий отказа S3 и отчёт с доказательствами.
2026-11-08 14:29:02 +03:00

193 lines
20 KiB
Markdown
Raw Permalink 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
- Целевая оценка; 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/<chat_id>/<attachment_id>/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 не попадает.