forked from mtusi2026/mtusi2026lab4
278 lines
22 KiB
Markdown
278 lines
22 KiB
Markdown
# Отчёт — лабораторная 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).
|