Files
mtusi2026lab4/REPORT.md
2026-11-13 14:09:36 +03:00

22 KiB
Raw Permalink Blame History

Отчёт — лабораторная 4

  • Автор: Щербаков Марк Игоревич, БПИ2303.
  • Целевая оценка: «3». Уровни 4/5 и исследовательские треки не заявляются.
  • Ветка: solution/BPI2303-Scherbakov.
  • Название коммита решения: «ЛР 4 — БПИ2303 — Щербаков — на 3».
  • История коммитов: git log --oneline. Текст сдачи: SUBMISSION.md.
  • Помощь ИИ: OpenAI Codex — изучение lab1–3, реализация, проверки и отчёт.
  • Основа: собственные предыдущие работы; чужие студенческие решения не использовались.

Запуск из чистого clone

Нужны Docker с Linux-контейнерами, Compose v2 и Python 3.12 для проверок. Все зависимости поднимаются из текущего каталога. Соседние lab1–3 для запуска не нужны.

python scripts/bootstrap.py
docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build --wait
python scripts/check_contract.py
python tests/smoke.py --base-url http://localhost:8080

Bootstrap создаёт .env и случайные учебные credentials в secrets/, не выводит и не перезаписывает существующие файлы. Они исключены из Git и Docker build context. Файлы postgres_password и database_url задают PostgreSQL; s3_access_key_id, s3_secret_access_key и s3_config.json задают согласованную S3 identity. В конфигурации нет anonymous identity. Секреты из lab3 не копируются.

На проверенном Windows-хосте в .env установлен APP_PORT=18084. Адрес стенда: http://127.0.0.1:18084. Для повторения результатов установить этот порт перед запуском. В .env.example по умолчанию задан 8080. При наличии HTTP proxy добавить localhost и 127.0.0.1 в NO_PROXY. Скрипт полной проверки сам задаёт NO_PROXY.

Миграции выполняет одноразовый сервис migrate после готовности PostgreSQL. Сервис s3-init ждёт S3, создаёт bucket, если его нет, и устанавливает private ACL. API запускаются после успешного завершения обоих jobs; Exited (0) у них — норма. Повторный bootstrap bucket не удаляет объекты. Изменение credentials требует согласованной перенастройки хранилища и API.

Полная проверка с реальными отказами:

python scripts/verify.py --base-url http://127.0.0.1:18084 --output evidence/grade3-checks.txt

Скрипт выполняет публичный smoke, собственные тесты, повтор миграций, restart пяти сервисов, остановку загрузившей файл API (по очереди обеих), анонимный S3 GET, отказ S3 и публичные failover-сценарии обеих API. Он создаёт синтетические данные и временно останавливает сервисы только проекта mtusi2026lab4; volumes сохраняются. Требуется доступ к Docker.

Отдельные проверки в PowerShell:

$env:BASE_URL = 'http://127.0.0.1:18084'
python -m unittest discover -s student-tests -v
python tests/resilience.py --mode persistence --action-script scripts/restart.cmd --base-url $env:BASE_URL
python tests/resilience.py --mode failover --action-script scripts/stop-one.cmd --base-url $env:BASE_URL
docker compose --env-file .env up -d --wait api1 api2

Linux/macOS: выполнить chmod +x scripts/restart.sh scripts/stop-one.sh и использовать .sh вместо .cmd. С GNU Make:

make check test test-student PYTHON=python BASE_URL=http://127.0.0.1:18084
make test-persistence PYTHON=python BASE_URL=http://127.0.0.1:18084 ACTION_SCRIPT=scripts/restart.sh
make test-failover PYTHON=python BASE_URL=http://127.0.0.1:18084 ACTION_SCRIPT=scripts/stop-one.sh
docker compose --env-file .env up -d --wait api1 api2

На Windows проверки выполнены прямыми Python-командами, эквивалентными Make targets.

Штатная остановка: docker compose --env-file .env down — volumes сохраняются. Намеренный сброс всех учебных данных: docker compose --env-file .env down -v. Команда удаления volumes не используется в hooks и проверках.

Архитектура и версии

flowchart LR
    C[Клиенты] --> LB[HAProxy / localhost:APP_PORT]
    LB --> A1[api1]
    LB --> A2[api2]
    A1 --> PG[(PostgreSQL: metadata / sessions / message keys)]
    A2 --> PG
    A1 --> S3[(SeaweedFS: private originals)]
    A2 --> S3
    PG --> PV[postgres_data]
    S3 --> SV[s3_data]
Роль / service Версия Readiness / bootstrap Хранение / сеть
api1, api2 Python 3.12.12, собственный Dockerfile /health/ready: PostgreSQL + schema 003 + S3 HeadBucket Read-only root, без data volume и опубликованных портов
postgres postgres:16.10-bookworm pg_isready; отдельный migrate postgres_data, только внутренняя сеть
s3 chrislusf/seaweedfs:3.85 s3-init ждёт подписанный ListBuckets; API проверяет HeadBucket s3_data на /data; S3 :8333, порты наружу не публикуются
lb haproxy:3.0.11-alpine HTTP checks API каждую секунду, fall=2/rise=1 Только 127.0.0.1:APP_PORT → :8080

API: 1 CPU / 512 MiB на реплику; PostgreSQL: 1 CPU / 256 MiB; S3: 1 CPU / 512 MiB; LB: 0.5 CPU / 128 MiB. Миграции и bucket job: 0.5 CPU / 128 MiB. Docker secrets монтируются в /run/secrets; значения не входят в образ и HTTP-ответы.

Runtime-зависимости закреплены в requirements.txt: psycopg 3.2.6, psycopg-pool 3.2.6, typing_extensions 4.16.0, boto3 1.40.61, Pillow 12.0.0. Реально разрешённые транзитивные версии сохранены в evidence/final-checks.txt. Полного lockfile с hashes нет. Образы MinIO в официальных реестрах оказались недоступны при подготовке; выбран разрешённый заданием SeaweedFS.

SeaweedFS server -filer -s3 запускает master, volume server, filer и S3 gateway. Рабочий каталог образа — /data; он целиком находится в persistent volume, включая метаданные filer и данные volumes. Размер volume ограничен 100 MiB, максимум 8 volumes — учебная настройка ёмкости без репликации на другой host.

Что перенесено и изменено

Из lab1 унаследованы HTTP transport, строгая валидация, ошибки, keyset-пагинация и завершение по SIGTERM. Lab2 перевела состояние в PostgreSQL, добавила scrypt и общие Bearer-сессии. Из lab3 перенесены эти исходники, неизменённые миграции 001/002, собственные тесты, две API за HAProxy и message_keys. Предыдущие каталоги не изменялись. README задания, COURSE, contracts и публичные tests текущей lab4 сохранены; соседние skeleton поверх них не копировались.

Новая миграция 003 создаёт Attachment с FK на чат и владельца-участника, размером, MIME, SHA-256, случайным object_key и UTC timestamps. Бинарных столбцов в PostgreSQL нет. Поле messages.attachment_ids — JSONB-массив до десяти уникальных UUID; все ссылки проверяются в транзакции отправки, участники неизменяемы. История возвращает attachment_ids, в том числе [] для старых текстовых сообщений.

Текст с отсутствующим attachment_ids и с [] семантически равен. Идемпотентность сравнивает text и упорядоченный список нормализованных UUID. Блокировка строки чата в PostgreSQL сериализует конкурирующие отправки всех API; запись сообщения и результата ключа коммитятся атомарно. Ключ действует 24 часа. Сессии, HMAC cursor key и результат повторной отправки переживают restart.

Синхронная загрузка:

  1. Bearer-сессия и членство в чате проверяются до чтения тела.
  2. filename — 1–255 Unicode code points. Slash, backslash, NUL, управляющие символы, surrogate и пустое/пробельное имя отклоняются. Это только отображаемое имя.
  3. Требуется Content-Length, Transfer-Encoding не принимается. До чтения проверяется максимум 10 MiB; читается ровно объявленное число байтов.
  4. Pillow открывает только PNG/JPEG, сравнивает настоящий MIME с Content-Type, проверяет размер из заголовка до load(), затем выполняет verify() и полное декодирование для отбрасывания повреждённых данных. Предел — 40 млн пикселей включительно.
  5. S3 PUT по случайному ключу originals/ → INSERT метаданных → COMMIT → 201 ready. Поля variants=[], error_code=null. Оригинал не перекодируется.

На API нет локального файла оригинала. Один одновременный decode на реплику ограничен semaphore; остальные загрузки получают 503 через 1 секунду ожидания. Тело максимум 10 MiB хранится в RAM; это ограниченная буферизация, а не потоковая обработка уровня 4. Сокет клиента: 10 s; S3 connect/read: 1/3 s, без retry SDK; LB client/server: 30/20 s. Ограничения bytes/pixels можно только уменьшить env. Опыт десяти параллельных uploads не проводился; общая защита от DoS не заявляется.

Download: Bearer → membership query → S3 GET → ограниченное чтение → проверка size/SHA-256 → bytes с истинным Content-Type, X-Request-Id и X-Instance-Id. Редиректа и публичного S3 URL нет. Посторонний получает одинаковый 404 для metadata и content. Неизвестный вариант даёт 404. Публичные metadata не раскрывают object_key.

/health/live не обращается к хранилищам. /health/ready требует PostgreSQL, миграцию 003 и S3, поскольку оригинал — обязательный синхронный путь. При отказе S3 LB выводит обе реплики из балансировки. Текстовые операции и metadata сами по себе могли бы работать с PostgreSQL, но политика общей readiness намеренно строже.

Настройки .env.example используются Compose: APP_PORT — внешний порт LB, APP_ENV/SESSION_TTL_SECONDS — среда/сессии, S3_ENDPOINT/REGION/BUCKET — S3 client и bootstrap, MAX_UPLOAD_BYTES/MAX_IMAGE_PIXELS — ограничения API. Внутренние APP_HOST=0.0.0.0, APP_PORT=8080 и пути к secret-файлам заданы непосредственно в compose.yaml. API_REPLICAS не требуется: явно объявлены api1/api2.

Доказательства критериев

Полный реальный вывод отказов: evidence/grade3-checks.txt. Финальная сборка, smoke, 23 собственных теста и версии зависимостей: evidence/final-checks.txt.

Первый полный прогон содержал 21 тест; затем добавлены два граничных сценария, все 23 теста выполнены на финальной сборке. Контракт и публичные tests сверены с Git.

Полная факультативная OpenAPI-валидация не выполнялась: на host отсутствует openapi-spec-validator. Для неё выполнить:

python -m pip install -r requirements-dev.txt
python scripts/validate_openapi.py

Обязательный check_contract прошёл.

Дата испытаний: 13 ноября 2026. Windows-хост, Docker Desktop 4.77.0, Engine 29.5.3; Docker VM: 8 CPU, 2 967 707 648 байт RAM. Это ресурсы VM; модель физического CPU и пределы производительности не исследовались. Версии Docker, instance aliases, контейнеры, StartedAt, mounts и результаты записаны в протокол автоматически.

Критерий уровня 3 Команда / сценарий Наблюдение
Предыдущий минимум и публичный smoke scripts/check_contract.py; tests/smoke.py; student-tests Контрактный сценарий и собственные проверки API/сессий/пагинации/идемпотентности прошли
S3 в общем стенде, метаданные отдельно compose config; state() в verify.py; миграция 003 PostgreSQL и SeaweedFS с отдельными volumes; API без data volume
201 ready, оригинал побайтно smoke; test_original_and_message_shared_with_member; test_jpeg_original_and_truncation PNG/JPEG, размер и SHA-256 совпадают; attachment-only сообщение читает другой участник
Приватный bucket и ACL чата verify_upload_failover; test_acl_before_image_validation Прямой unsigned GET существующего S3-объекта — 403; посторонний в API — 404
Byte/pixel/MIME/filename limits test_byte_limit_before_reading_body; test_image_validation; test_filename 413 до передачи oversized тела; 415 для подмены/порчи; 400 для опасного имени
Граничные допустимые размеры test_maximum_byte_size_accepted; test_exactly_40_million_pixels_accepted Приняты 10 MiB включительно и валидный PNG 8000×5000
Остановка загрузившей API verify_upload_failover, обе API по очереди Останавливается alias из ответа upload; download другой репликой побайтно совпадает
Restart всех stores и API Публичный persistence с restart.cmd/.sh + inspect до/после StartedAt меняется у s3/postgres/api1/api2/lb, volumes сохраняются; прежний token и файл работают
Минимум failover lab3 Публичный failover обеих API; inspect exited Подтверждённые сообщения и файл сохранены, retry без дублей, запись восстанавливается за бюджет теста
Недоступность S3 verify_s3_failure Прямо в API: live=200, ready=503, metadata=200, upload/download=503; число metadata не увеличилось

Проверки завершились успешно: публичные persistence и failover обеих API, анонимный S3 GET=403, контролируемый отказ S3, 23 собственных теста.

В полном прогоне: остановка api1 — 97 успешных записей, 0 неудачных POST, first_recovery=3.844 s; остановка api2 — 96 записей, 0 неудачных POST, first_recovery=4.750 s. Параллельные чтения: 148/145 успешных, по одной переходной ошибке. first_recovery включает запуск Docker hook; это не длительность полного простоя. Показатели относятся к этому локальному эксперименту.

Отказы, согласованность и ограничения

Повторы migration jobs сверяются по checksum под advisory lock; повторный запуск не меняет количества строк. При restart публичная проверка сохраняет прежнюю сессию, сообщения и файл; дополнительные проверки сохраняют cursor и результат идемпотентного POST. Отдельно inspect подтверждает реальный перезапуск процессов.

Воздействие Ожидаемый результат Проверяемое наблюдение
Остановить загрузившую API Файл доступен другой реплике Два UPLOAD_FAILOVER с разными stopped/download aliases и одинаковым SHA-256
Остановить одну API во время POST Вторая продолжает запись; retry без дублей Публичный failover: successes, failures, first_recovery_seconds в протоколе
Перезапустить весь стенд Сохранить volumes, токены и данные BEFORE_RESTART/AFTER_RESTART, persistence PASS
Остановить S3 Контролируемые 503, без ложного 201 S3 outage PASS, неизменное число attachments; после start оригинал совпадает
GET чужого файла Скрыть существование объекта 404 для metadata/content, 401 без сессии

У PostgreSQL и S3 нет общей транзакции. Если PUT успешен, а INSERT/COMMIT не подтверждён, клиент не получает 201; возможен orphan object. При неопределённом результате COMMIT объект не удаляется, чтобы не разрушить уже зафиксированную запись. Автоматические reconciler/компенсация с grace period не реализованы и относятся к уровню 4/5. При отказе S3 во время GET/PUT API возвращает 503; ошибка записи не фиксируется как успешный результат идемпотентности.

Учебное упрощение: одна S3 identity с административными правами используется API и bootstrap. Секреты не публикуются, anonymous identity отсутствует; отдельные ограниченные credentials API относятся к уровню 4. Сеть Compose считается доверенной; внутренние HTTP-интерфейсы SeaweedFS доступны соседним контейнерам, наружу не опубликованы. Это не защита от компрометации контейнера внутри сети.

Один Docker-host, LB, PostgreSQL и SeaweedFS остаются точками единого отказа. Нет репликации S3/БД, backup, TLS, workers, presigned upload, thumbnail, защиты от потери volumes/host и гарантии доступности при отказе stores. Проверены остановка отдельной API и сохранность при полном restart; они не доказывают промышленную HA. Нагрузочное исследование, RPS и p95/p99 для уровня 3 не заявляются. Файлы и пользователи в проверках синтетические.

Источники