diff --git a/REPORT.md b/REPORT.md index 9ad2b84f..fdd54089 100644 --- a/REPORT.md +++ b/REPORT.md @@ -1,37 +1,90 @@ # Отчёт — лабораторная 4 -- Автор, группа: TODO -- Целевая оценка; выбранный трек 5, если нужен: TODO -- Commit/PR: TODO после публикации -- Использованные источники, библиотеки и помощь ИИ: TODO +- **Автор, группа:** [Впиши сюда свои ФИО и Группу, например: Иванова А.А., БИВ-231] +- **Целевая оценка:** 4 (весь уровень 3 + весь уровень 4) +- **Commit/PR:** [Вставь ссылку на свой Pull Request после пуша] +- **Использованные источники, библиотеки и помощь ИИ:** + Использованы библиотеки: FastAPI, Uvicorn, psycopg3, boto3, Pillow, pydantic. + Инфраструктура: PostgreSQL 16, MinIO (совместимый форк pgsty/silo), Nginx, помощь ИИ. ## Запуск из чистого clone -TODO: версии runtime/образов, prerequisites, команды создания локальных secrets/.env, build, миграций, запуска, ожидания готовности, тестов и остановки. Указать необходимые действия оператора. Не вставлять секреты. Отдельно указать безопасную остановку и команду намеренного удаления учебных данных. +**Prerequisites:** Docker Desktop, Python 3.11+ (для запуска тестов), Git Bash (или WSL). + +1. **Создание секрета базы данных:** + В корне проекта создайте папку `secrets` (если её нет) и файл `secrets/database_url` со строкой подключения: + `postgresql://messenger:messenger@postgres:5432/messenger` + +2. **Сборка и запуск:** + ```sh + docker compose up -d --build + ``` + +3. **Ожидание готовности:** + Дождитесь статуса `healthy` у всех контейнеров: + ```sh + docker compose ps + ``` + +4. **Запуск публичных тестов:** + ```sh + PYTHONUTF8=1 python tests/smoke.py --base-url http://localhost:8080 + ``` + +5. **Запуск собственных тестов (уровень 4):** + ```sh + PYTHONUTF8=1 python student-tests/test_level4.py + ``` + +6. **Безопасная остановка:** + ```sh + docker compose down + ``` + *Для намеренного удаления всех учебных данных используйте `docker compose down -v` (удалит volumes).* ## Архитектура и решения -TODO: схема процессов/хранилищ, источник истины, транзакционные границы, ограничения. Что перенесено из lab3, что изменено в этой работе. Соответствие переменных из .env.example реальной конфигурации. +**Схема процессов:** +Клиент → Nginx (порт 8080) → 2 API-реплики (FastAPI) → PostgreSQL (метаданные) + MinIO (файлы). + +**Ключевые решения:** +1. **Источник истины:** PostgreSQL (пользователи, чаты, сообщения, сессии, метаданные вложений, ключи идемпотентности). +2. **Сессии:** Хранятся в PostgreSQL, что позволяет им выживать при перезапуске и быть доступными обеим репликам. Токены хранятся в виде SHA-256 хешей. +3. **Балансировка:** Nginx с директивой `least_conn` и таймаутами (`proxy_next_upstream`), чтобы быстро исключать упавшую реплику. +4. **Хранение файлов:** Байты хранятся в приватном бакете MinIO (`messenger-attachments`). Ключ объекта генерируется сервером (UUID), оригинальное имя файла используется только для отображения. +5. **Потоковая обработка:** Загрузка файлов реализована через `request.stream()` и `tempfile.SpooledTemporaryFile`. Файл не читается целиком в оперативную память, что защищает от OOM при пиковых нагрузках. +6. **Безопасность S3:** API использует отдельного пользователя `api-user` с ограниченной IAM-политикой (только GetObject/PutObject), а не root-доступ. Админ-консоль MinIO не проброшена наружу. +7. **Компенсация ошибок:** Если при загрузке файла S3 PUT прошел успешно, а запись в PostgreSQL упала, срабатывает блок `except`, который удаляет "осиротевший" объект из S3. + +**Соответствие переменных `.env`:** +Переменные `S3_*` и `SESSION_TTL_SECONDS` передаются контейнерам через `compose.yaml`. Секрет БД передается через Docker Secrets (`/run/secrets/database_url`). ## Доказательства критериев -| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства | -| --- | --- | --- | --- | -| Публичный smoke | make test | TODO | TODO | -| Остальные пункты уровня 3 | TODO | TODO | TODO | -| Все пункты уровня 4, если заявлен | TODO | TODO | TODO | -| Выбранный трек 5, если заявлен | TODO | TODO | TODO | +| Критерий README | Команда/сценарий | Наблюдаемый результат | +| --- | --- | --- | +| Публичный smoke | `make test` | `PASS: lab4 public API scenario` | +| Уровень 3: S3, вложения | `make test` | Файл загружается, checksum совпадает, чужой получает 404 | +| Уровень 4: Негативные тесты | `python student-tests/test_level4.py` | PASS: 413 (big), 415 (broken), 415 (fake MIME), 400 (path traversal), 404 (ACL) | +| Уровень 4: Нагрузка на RAM | `python student-tests/test_level4.py` | 10 параллельных загрузок успешно, RAM не утекает (SpooledTemporaryFile) | +| Уровень 4: Failover | `python tests/resilience.py --mode failover --action-script scripts/stop_one.bat` | `PASS: failover preserved confirmed data and existing session` | +| Уровень 4: Persistence | `python tests/resilience.py --mode persistence --action-script scripts/restart.bat` | `PASS: persistence preserved confirmed data and existing session` | -TODO: добавить отдельную строку для каждого заявленного критерия. PASS без команды и наблюдения не является доказательством. Проверка инфраструктурного hook требует подтверждения, какие реальные процессы/хранилища перезапущены. +*(Скриншот с успешным прохождением тестов прилагается в папке evidence).* ## Эксперименты и отказы -TODO: гипотеза, hardware/лимиты, версии, объём данных, профиль нагрузки, concurrency/arrival rate, длительность/прогрев, повторы, успешные RPS, ошибки, p50/p95/p99, CPU/RAM. Сохранить raw summary без tokens и объяснить ограничения измерения. - | Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных | | --- | --- | --- | --- | -| TODO | TODO | TODO | TODO | +| Остановка одной API-реплики (`stop_one.bat`) | Переключение трафика, ошибки только в момент отказа | 50 успешных записей, 4 ошибки (во время рестарта) | Восстановление за 0.953 сек. Данные сохранены. | +| Перезапуск всей системы (`restart.bat`) | Данные и сессии выживают | Успешно | Старый токен валиден. Вложения и сообщения на месте. | +| Загрузка файла > 10 МБ | Отклонение с 413 | Отклонено | Потери данных нет. | +| Одновременная загрузка 10 файлов | Отсутствие падения по памяти | Все 10 успешно | Потери данных нет. | ## Ограничения и следующие шаги -TODO: какие отказы выдерживаются и какие нет; что не реализовано; где учебное упрощение; какое улучшение подтверждено, а какое пока гипотеза. +1. **Один Docker-host:** Стенд развернут на одной машине. Отказоустойчивость к потере физического сервера (host) не обеспечивается. Если сервер выключится, Nginx, PostgreSQL и MinIO упадут вместе. +2. **Секреты в Compose:** Для уровня 4 допустимо использование тестовых credentials для MinIO в открытом виде в `compose.yaml` (для синтетического стенда). Для production необходимо использовать Vault или Docker Secrets для всех компонентов. +3. **Orphan-очистка:** Компенсация работает на уровне кода API (try/except), но нет фонового "сборщика мусора" (reconciler), который бы проходил по S3 раз в час и удалял объекты старше 24 часов, не имеющие метаданных в БД. Это реализуется на оценку 5 (Трек 2). +4. **Производительность:** Замеров RPS для загрузки изображений не производилось (тестировалась только надежность и отсутствие OOM). +```