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

278 lines
22 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
- Автор: Щербаков Марк Игоревич, БПИ2303.
- Целевая оценка: **«3»**. Уровни 4/5 и исследовательские треки не заявляются.
- Ветка: solution/BPI2303-Scherbakov.
- Название коммита решения: «ЛР 4 — БПИ2303 — Щербаков — на 3».
- История коммитов: git log --oneline. Текст сдачи: [SUBMISSION.md](SUBMISSION.md).
- Помощь ИИ: OpenAI Codex — изучение lab1–3, реализация, проверки и отчёт.
- Основа: собственные предыдущие работы; чужие студенческие решения не использовались.
## Запуск из чистого clone
Нужны Docker с Linux-контейнерами, Compose v2 и Python 3.12 для проверок.
Все зависимости поднимаются из текущего каталога. Соседние lab1–3 для запуска не нужны.
~~~sh
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.
Полная проверка с реальными отказами:
~~~sh
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:
~~~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:
~~~sh
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 и проверках.
## Архитектура и версии
~~~mermaid
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/<uuid> → 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](evidence/grade3-checks.txt).
Финальная сборка, smoke, 23 собственных теста и версии зависимостей:
[evidence/final-checks.txt](evidence/final-checks.txt).
Первый полный прогон содержал 21 тест; затем добавлены два граничных сценария,
все 23 теста выполнены на финальной сборке.
Контракт и публичные tests сверены с Git.
Полная факультативная OpenAPI-валидация не выполнялась: на host отсутствует
openapi-spec-validator. Для неё выполнить:
~~~sh
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 не заявляются. Файлы и пользователи в проверках синтетические.
## Источники
- [Обязательная семантика lab4](contracts/README.md) и [OpenAPI](contracts/openapi.json).
- [SeaweedFS S3 API](https://github.com/seaweedfs/seaweedfs/wiki/Amazon-S3-API):
server с S3 gateway, конфигурация identities.
- [Pillow Image](https://pillow.readthedocs.io/en/stable/reference/Image.html):
open/verify/load, размеры до декодирования и защита от decompression bomb.
- [Boto3 PUT](https://docs.aws.amazon.com/boto3/latest/reference/services/s3/client/put_object.html)
и [GET](https://docs.aws.amazon.com/boto3/latest/reference/services/s3/client/get_object.html):
сохранение bytes и чтение оригинала.
- [HAProxy 3.0](https://docs.haproxy.org/3.0/configuration.html).
- [psycopg transactions](https://www.psycopg.org/psycopg3/docs/basic/transactions.html).