# Отчёт — лабораторная 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/`. Скачивание идёт через 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 и исследовательских треков. Проверка реальных контейнеров и образов остаётся обязательной перед сдачей.