forked from mtusi2026/mtusi2026lab4
Стенд: PostgreSQL 16 + две API-реплики за HAProxy + SeaweedFS S3 в приватном bucket. Метаданные вложений в PostgreSQL, байты в S3, object key назначает сервер. Лимиты 10 MiB и 40 млн пикселей, MIME по магическим байтам, проверка filename. Добавлены smoke/негативные тесты, хуки restart/stop-one, сценарий отказа S3 и отчёт с доказательствами.
193 lines
20 KiB
Markdown
193 lines
20 KiB
Markdown
# Отчёт — лабораторная 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 не попадает.
|