# Отчёт — лабораторная 4 - Автор, группа: Зюлина Екатерина Михайловна, БВТ2302. - Целевая оценка: 3. - Commit/PR: заполнить после публикации. - Источники, библиотеки и помощь ИИ: контракт и материалы текущего skeleton; собственная реализация lab3; FastAPI, SQLAlchemy, Alembic, boto3, Pillow; [MinIO image mirror](https://hub.docker.com/r/dappros/minio) как закреплённый S3 server образ; Codex использовался для анализа требований, переноса и реализации. ## Запуск из чистого clone Для Windows PowerShell и Docker Desktop с Linux containers нужен Docker Compose v2 и Python 3.11 на хосте для запуска публичных тестов. Runtime в Docker закреплён на Python 3.11.10; API-зависимости перечислены с версиями в `requirements.txt`. Секреты генерируются локально в игнорируемом `.env`; их значения не хранятся в репозитории. В PowerShell из чистого clone выполните: ```powershell $dbSecret = [Convert]::ToHexString([Security.Cryptography.RandomNumberGenerator]::GetBytes(24)) $rootSecret = [Convert]::ToHexString([Security.Cryptography.RandomNumberGenerator]::GetBytes(24)) $s3Secret = [Convert]::ToHexString([Security.Cryptography.RandomNumberGenerator]::GetBytes(32)) $envText = Get-Content -Raw .env.example $envText = $envText.Replace('replace-db-password-with-random-value', $dbSecret) $envText = $envText.Replace('replace-minio-root-password-with-random-value', $rootSecret) $envText = $envText.Replace('replace-s3-secret-with-random-value', $s3Secret) [IO.File]::WriteAllText((Join-Path (Get-Location) '.env'), $envText, [Text.UTF8Encoding]::new($false)) $env:PYTHONUTF8 = '1' docker compose --env-file .env config --quiet docker compose --env-file .env up -d --build do { Start-Sleep -Seconds 2; try { Invoke-WebRequest http://localhost:8080/health/ready -UseBasicParsing | Out-Null; $ready = $true } catch { $ready = $false } } until ($ready) py -3.11 scripts/check_contract.py py -3.11 tests/smoke.py --base-url http://localhost:8080 py -3.11 tests/resilience.py --mode persistence --action-script scripts/restart.bat --base-url http://localhost:8080 py -3.11 tests/resilience.py --mode failover --action-script scripts/stop-one.bat --base-url http://localhost:8080 docker compose --env-file .env start api1 api2 py -3.11 student-tests/s3_unavailable.py --base-url http://localhost:8080 ``` Тесты создают пользователей и чаты, которые не удаляются API. Повторяйте проверки на отдельном учебном volume. Make-цели `make check` и `make test` соответствуют Python-командам выше. Образы закреплены версиями: `postgres:16.4-alpine`, `redis:7.4.2-alpine`, `dappros/minio:RELEASE.2025-09-07T16-13-09Z` (зеркальная копия MinIO RELEASE), `ghcr.io/golithus/mc:RELEASE.2025-08-13T08-35-41Z` (зафиксирован digest `sha256:dde55ccc0bc9e65dc582c8e652d652eea1438c6e60d774524f4da15d7b26a900`), `nginx:1.27.5-alpine`. API образ собирается из Dockerfile текущего репозитория как `mtusi-messenger-api:4.0.0`. Схема БД создаётся одноразовым сервисом `migrate` командой `alembic upgrade head`. Сервис `s3-bootstrap` настраивает закрытый от anonymous bucket. DB, Redis и MinIO сохраняются в named volumes. Из API наружу опубликован только LB на `localhost:8080`. ### Сохранность и отказ ```powershell py -3.11 tests/resilience.py --mode persistence --action-script scripts/restart.bat --base-url http://localhost:8080 py -3.11 tests/resilience.py --mode failover --action-script scripts/stop-one.bat --base-url http://localhost:8080 docker compose --env-file .env start api1 api2 py -3.11 student-tests/s3_unavailable.py --base-url http://localhost:8080 ``` Failover последовательно останавливает обе API-реплики. После сценария запустите их обе и дождитесь `/health/ready`. Restart hook перезапускает PostgreSQL, Redis, MinIO, API и LB с сохранением named volumes; данные и volumes не удаляются. Тест отказа останавливает MinIO, проверяет недоступность readiness/upload и затем восстанавливает сервис. Для Linux перед запуском hooks задайте executable bit: `chmod +x scripts/restart.sh scripts/stop-one.sh`. При подготовке Git-коммита из Windows зафиксируйте режим файлов командой `git update-index --chmod=+x scripts/restart.sh scripts/stop-one.sh` после их добавления в index. ## Архитектура и решения Путь запроса: клиент → Nginx → две API-реплики → общие PostgreSQL, Redis и приватный MinIO. Данные пользователей, сессии, чаты, сообщения, идемпотентность и метаданные вложений хранятся в PostgreSQL; байты оригинала — только в S3. Ключ `original/` генерирует сервер. Исходное имя хранится как display filename и не используется в S3 key. Каждая реплика ограничивает HTTP body 10 MiB. Pillow проверяет реальный формат, целостность и размеры, отклоняя изображения больше 40 млн пикселей. Проверяются MIME, filename, chat membership и UUID. Ответ `201 ready` выдаётся после сохранения объекта в S3 и metadata в PostgreSQL. GET metadata/content повторно проверяют членство в чате; API не отдаёт redirect или S3 key. Порядок upload: сначала S3 PUT, затем metadata в PostgreSQL; ответ `201 ready` возвращается после обоих операций. При отказе S3 API возвращает JSON 503. При сбое БД после успешного PUT может остаться объект без metadata; автоматическая сверка и очистка не входят в целевой уровень этой работы. Из lab3 перенесены Python API, PostgreSQL/Redis store, сессионная аутентификация, межрепличная идемпотентность, Alembic migrations, Dockerfile, Nginx и restart/failover hooks. Добавлены миграция `004_attachments`, S3 слой, binary endpoints, attachment references в сообщениях, MinIO/bootstrap. Изменения контракта ограничены переходом lab4: старые текстовые сообщения сохраняют `attachment_ids=[]`; upload возвращает 201 ready. | Роль | Service / версия | Health/readiness | Volume, сеть и доступ | | --- | --- | --- | --- | | LB | `lb`, nginx:1.27.5-alpine | Compose process; активный probe API — `health/ready` | Host `localhost:8080`; client body max 11 MiB для JSON 413 приложения на 10 MiB; не ретраит POST | | API | `api1`, `api2`, локальный Python 3.11.10 image | `/health/ready` проверяет PostgreSQL, Redis и bucket | Только внутренняя Compose-сеть; S3 доступ через credentials из локального `.env` | | Миграции | `migrate`, локальный API image | `alembic upgrade head`, однократный exit 0 | PostgreSQL; до API | | PostgreSQL | `db`, postgres:16.4-alpine | SQL readiness проверяется API | `postgres_data`; сеть внутренняя | | Session cache | `redis`, redis:7.4.2-alpine | Redis ping проверяется API | `redis_data`, AOF `appendfsync always`; внутренняя сеть | | Binary store | `minio`, dappros mirror of MinIO RELEASE.2025-09-07T16-13-09Z | `/minio/health/ready`, bucket probe в API | `minio_data`; S3 API только внутри сети, console не опубликована | | Bucket bootstrap | `s3-bootstrap`, mc RELEASE.2025-08-13T08-35-41Z, GHCR digest закреплён | Одноразовый успешный exit | Изменяет bucket/policy/user через локальные `.env` credentials | ## Доказательства критериев Проверки проведены на Compose стенде 30.10.2026. Contract, Compose config/build, OpenAPI/schema validation, публичный smoke, persistence, failover и S3 outage прошли. Операторские записи hooks — в [`evidence/persistence-actions.txt`](evidence/persistence-actions.txt) и [`evidence/failover-actions.txt`](evidence/failover-actions.txt). После проверок все сервисы и обе API реплики healthy. | Критерий | Команда/сценарий | Результат и доказательство | | --- | --- | --- | | Структура skeleton и контракт | `scripts/check_contract.py` | PASS; обязательные skeleton-файлы сохранены. | | Синтаксис реализации | Offline Python compile | PASS. | | Compose configuration и сборка | `docker compose config --quiet`, `docker compose build` | PASS; стенд запущен. | | Полная OpenAPI 3.1 и JSON Schema | `scripts/validate_openapi.py` с `requirements-dev.txt` | PASS. | | Публичный smoke и доступ участников к вложению | `tests/smoke.py --base-url http://127.0.0.1:8080` | PASS; участник скачал оригинал, постороннему отказано. | | Failover и persistence | `tests/resilience.py --mode failover/persistence` | PASS: 95 успешных записей, 0 ошибок, recovery 3.234 s; persistence сохранил данные и сессию. StartedAt записан в evidence. | | S3 outage и восстановление | `student-tests/s3_unavailable.py` | PASS: contract JSON 503/504 для readiness/upload и восстановление после старта MinIO. | Evidence содержит сводные метрики, состояния сервисов до/после hooks и идентификаторы тестовых target без секретов. Не добавляйте `.env`, токены или реальные данные. ## Проверки отказа | Воздействие | Ожидаемое поведение | Наблюдение / восстановление | | --- | --- | --- | | MinIO недоступен при readiness/upload | Public gateway возвращает contract JSON 503 с request ID; upload не становится ready | PASS; MinIO запущен повторно, readiness восстановилась | | API остановлена после upload | LB переключает запрос на вторую реплику; bytes и metadata доступны | PASS: 95 записей, 0 failed attempts, recovery 3.234 s | | Restart PostgreSQL/Redis/MinIO/API/LB с volumes | прежняя сессия и attachment bytes остаются доступны | PASS; StartedAt до/после сохранён в persistence evidence | Стенд на одном Docker host переживает остановку одной API-реплики, но не потерю host, LB, PostgreSQL, Redis или самого MinIO. MinIO тут single-node; репликация S3 и HA БД не заявлены. ## Ограничения и следующие шаги Реализация и отчёт ограничены критериями уровня 3; функции уровней 4/5 не заявляются. Одна реплика MinIO и одна БД являются SPOF. Если PostgreSQL откажет после успешного S3 PUT, объект может остаться без записи metadata; автоматическая сверка не реализована.