forked from mtusi2026/mtusi2026lab4
138 lines
13 KiB
Markdown
138 lines
13 KiB
Markdown
# Отчёт — лабораторная 4
|
||
|
||
Автор: Шурман А.Р., БПИ2302. Целевая оценка: **4**. Исследовательские треки на 5 не выполнялись.
|
||
|
||
## Статус проверки
|
||
|
||
Реализация подготовлена, но **полный Docker-прогон ещё не выполнен**. В среде подготовки
|
||
нет доступа к Docker socket. Проверены структура задания, Python-синтаксис,
|
||
Compose-конфигурация и пять локальных тестов валидации изображений.
|
||
Фактические локальные результаты находятся в `evidence/offline.txt`.
|
||
Smoke, сохранность, отказ реплики, доступ к приватному bucket, очистка после сбоя
|
||
и эксперимент с 10 загрузками необходимо выполнить приведённой ниже командой.
|
||
До этого выполнение всех критериев оценки 4 не подтверждено.
|
||
|
||
## Запуск
|
||
|
||
Нужны Docker с Compose, Python 3.9+ на хосте (для memory/unit — Pillow).
|
||
API работает на Python 3.12.7. Новый стенд использует порт **8084**, отдельные volumes
|
||
и Compose project `mtusi-lab4`, поэтому не занимает порт предыдущих работ.
|
||
|
||
```sh
|
||
cd labs/mtusi2026lab4
|
||
python3 scripts/bootstrap.py
|
||
docker compose config --quiet
|
||
docker compose up -d --build --wait
|
||
BASE_URL=http://localhost:8084 python3 scripts/verify.py
|
||
```
|
||
|
||
Команды выполняются из корня этой лабораторной. Если репозиторий склонирован отдельно,
|
||
первую команду замените на переход в его каталог. `bootstrap.py` генерирует локальные
|
||
секреты, не выводит и не перезаписывает их. Повторный запуск сохраняет данные.
|
||
Для локальных тестов при отсутствии Pillow: отдельное venv и `pip install Pillow==11.1.0`.
|
||
Полная проверка OpenAPI: `pip install -r requirements-dev.txt`, затем `make validate`.
|
||
|
||
API: http://localhost:8084; Swagger: http://localhost:8084/docs.
|
||
Остановка без потери данных: `docker compose down` (без `-v`).
|
||
Возобновление: `docker compose up -d --wait`.
|
||
|
||
## Архитектура
|
||
|
||
HAProxy → две FastAPI-реплики → общий PostgreSQL и приватный MinIO.
|
||
Valkey кэширует публичные профили; сессии проверяются в PostgreSQL при каждом запросе.
|
||
Исходная основа — собственная лабораторная 2: модели пользователей/чатов,
|
||
аутентификация, SQL-хранилище и мигратор. Возможности лабораторной 3 добавлены здесь:
|
||
балансировка, `X-Instance-Id`, общая таблица идемпотентности.
|
||
Контракт и публичные тесты skeleton не изменены.
|
||
|
||
Каждая реплика возвращает `api1` или `api2`. HAProxy проверяет readiness каждую секунду,
|
||
исключает реплику после двух неудач. Он не повторяет POST автоматически. При потере ответа
|
||
клиент повторяет сообщение с тем же `Idempotency-Key`. Advisory lock в PostgreSQL
|
||
сериализует один ключ пользователя/чата, вставка сообщения и результата атомарны.
|
||
Повтор в течение 24 часов возвращает исходный объект; другой текст/список вложений — 409.
|
||
Отсутствующий список вложений и `[]` равны. Просроченная запись ключа заменяется при повторном использовании.
|
||
История читается из primary без кэша. Keyset cursor не обеспечивает snapshot между страницами.
|
||
|
||
Метаданные Attachment находятся в PostgreSQL, байты — только в S3. Временный файл API
|
||
существует исключительно во время приёма и проверки запроса и закрывается по выходу.
|
||
Имя пользователя не используется как S3 key. Ключ — `originals/<UUID>`.
|
||
Скачивание идёт через API после проверки членства, без redirect и публичных URL.
|
||
|
||
## Валидация и ресурсы
|
||
|
||
Загрузка принимает сырые PNG/JPEG, максимум 10 MiB. Content-Length проверяется заранее,
|
||
но фактические байты также считаются во время потока. Общий срок приёма — 30 секунд.
|
||
Pillow проверяет формат, MIME, структуру и декодирование. Размер не выше 40 млн пикселей
|
||
проверяется до загрузки пикселей. Анимированные PNG в этой реализации отклоняются.
|
||
Оригинал сохраняется без преобразования; SHA-256 и размер вычисляются при чтении.
|
||
Пустые/опасные filename, MIME-подмена и чужие вложения имеют ошибки контракта.
|
||
|
||
Одновременно каждая реплика обрабатывает максимум две загрузки. Ожидание слота до 0.5 s,
|
||
затем явный 503. Две реплики ограничены по 768 MiB и 1 CPU. На диск пишется максимум
|
||
10 MiB на активную загрузку, декодирование занимает ограниченную память до размера
|
||
изображения. S3: connect timeout 2 s, read timeout 10 s, автоматических повторов нет.
|
||
Download читает S3 чанками по 64 KiB. Оригинал не загружается целиком в RAM при скачивании.
|
||
|
||
## Согласованность S3 и БД
|
||
|
||
1. API принимает и проверяет временный файл.
|
||
2. Отдельная транзакция сохраняет `pending` и назначенный object key до S3 PUT.
|
||
3. Новая транзакция блокирует строку, выполняет PUT и переводит её в `ready`.
|
||
4. Ответ 201 отправляется только после COMMIT. `pending` не показывается публично.
|
||
|
||
При обрыве передачи клиента до PUT остаётся только автоматически закрываемый временный
|
||
файл. При сбое PUT, падении процесса или неуспешном COMMIT остаётся учтённый `pending`.
|
||
Фоновый cleaner раз в минуту выбирает pending старше **1 часа**, блокируя строку
|
||
`FOR UPDATE SKIP LOCKED`, удаляет соответствующий S3 key и затем запись БД. Активная
|
||
транзакция пропускается. При ошибке S3 строка сохраняется для следующего прохода.
|
||
При сбое COMMIT очистка повторит безопасный DELETE отсутствующего объекта.
|
||
`ready` никогда не выбирается. Часовой grace period значительно больше таймаутов загрузки.
|
||
Это не распределённая транзакция: некоторое время возможны pending-метаданные и лишние байты.
|
||
Объекты, вручную записанные администратором без intent, вне модели очистки.
|
||
|
||
## Приватность и запуск хранилища
|
||
|
||
MinIO, PostgreSQL, Valkey и API не публикуют порты на хост. Только HAProxy доступен
|
||
на loopback. Консоль MinIO слушает 127.0.0.1 внутри его контейнера.
|
||
Идемпотентный `s3-init` создаёт bucket, запрещает anonymous и назначает отдельному API user
|
||
политику: ListBucket одного bucket и Get/Put/Delete исключительно в `originals/*`.
|
||
Root credentials доступны только MinIO и init, API их не получает.
|
||
Readiness зависит от PostgreSQL и MinIO. Valkey имеет fallback в PostgreSQL.
|
||
Секреты находятся в исключённом из Git каталоге `secrets/`.
|
||
|
||
## Проверки и доказательства
|
||
|
||
| Критерий | Проверка | Статус на момент подготовки |
|
||
|---|---|---|
|
||
| Структура и синтаксис | `make check`, AST всех новых Python-файлов | выполнено |
|
||
| Конфигурация | `docker compose config --quiet` | выполнено |
|
||
| Реальные PNG/JPEG, MIME, повреждение, пиксели | `python3 student-tests/unit.py` | 5 тестов пройдено |
|
||
| Обязательный API и checksum | `make test BASE_URL=http://localhost:8084` | требуется запуск Docker |
|
||
| Ошибки файлов и ACL, конкуренция ключа | `BASE_URL=http://localhost:8084 python3 student-tests/verify.py` | требуется запуск Docker |
|
||
| Приватность bucket и безопасная очистка | `student-tests/storage_checks.py` внутри API через общий runner | требуется запуск Docker |
|
||
| Обрыв загрузки и отказ S3 | `student-tests/outage.py` | требуется запуск Docker |
|
||
| Повторный bootstrap | повтор `docker compose run --rm s3-init` | требуется запуск Docker |
|
||
| Перезапуск всех сервисов | persistence + `scripts/restart.sh` | требуется запуск Docker |
|
||
| Остановка обслужившей реплики | failover + `scripts/stop-one.sh` | требуется запуск Docker |
|
||
| 10 одновременных загрузок и RSS | `student-tests/memory.py` | измерения ещё не получены |
|
||
|
||
`python3 scripts/verify.py` выполняет проверки и сохраняет реальные результаты в evidence,
|
||
останавливаясь при первом провале. Тест очистки создаёт только синтетические строки и объекты,
|
||
моделирует rollback финализации после PUT, проверяет grace period и сохранность ready.
|
||
Он удаляет только свои синтетические данные. До запуска убедитесь, что это учебный стенд.
|
||
|
||
Memory-тест создаёт PNG примерно 9 MiB и одновременно запускает 10 запросов.
|
||
Он пишет коды ответов, длительность, выборки VmRSS процессов API и измеренный максимум.
|
||
Отказы 503 из-за ограничения слотов учитываются явно; они не записываются как успешные загрузки.
|
||
Последовательная выборка `/proc/1/status` может пропустить короткий пик, поэтому результат —
|
||
максимум наблюдений, а не гарантированный абсолютный пик. Числа не подставлены заранее.
|
||
|
||
## Ограничения
|
||
|
||
Один host, HAProxy, PostgreSQL и MinIO остаются точками отказа. Это отказоустойчивость
|
||
к остановке одной API-реплики, не полноценная HA-система. При отказе S3 readiness
|
||
становится 503; после восстановления новые обращения повторяются клиентом.
|
||
Обрыв S3 посреди уже начатого download закрывает поток, поэтому клиент проверяет длину/checksum.
|
||
Нет UI, обработки изображений в очереди, presigned URL и исследовательских треков.
|
||
Проверка реальных контейнеров и образов остаётся обязательной перед сдачей.
|