From 75cbe925d3e91ed954d2978dfb335488ee9da4f7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=D0=A1=D0=B8=D1=80=D0=B5=D0=BD=D0=BA=D0=BE=20=D0=98=D0=BB?= =?UTF-8?q?=D1=8C=D1=8F?= Date: Tue, 17 Nov 2026 03:37:45 +0000 Subject: [PATCH] =?UTF-8?q?=D0=97=D0=B0=D0=BF=D0=BE=D0=BB=D0=BD=D0=B8?= =?UTF-8?q?=D1=82=D1=8C=20=D0=BE=D1=82=D1=87=D1=91=D1=82=20=D0=B8=20README?= =?UTF-8?q?=20=D0=BB=D0=B0=D0=B1=D0=BE=D1=80=D0=B0=D1=82=D0=BE=D1=80=D0=BD?= =?UTF-8?q?=D0=BE=D0=B9=20=D1=80=D0=B0=D0=B1=D0=BE=D1=82=D1=8B?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit REPORT.md: запуск, архитектура, логика загрузки, ограничения уровня 3, таблица доказательств. README: ссылка на отчёт вместо отсутствующего START_HERE.md. --- README.md | 2 +- REPORT.md | 102 ++++++++++++++++++++++++++++++++++++++++-------------- 2 files changed, 77 insertions(+), 27 deletions(-) diff --git a/README.md b/README.md index 947094c3..daa77b9b 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ Разделить метаданные и бинарное содержимое, добавить изображения в сообщения и сохранить доступ к ним при переключении API-реплики. -Это **skeleton**, а не готовый сервер. Здесь есть задание, контракт и публичные проверки. Реализацию приложения, Dockerfile и требуемую инфраструктуру пишет студент. Язык и framework свободные; UI не обязателен. +Этот архив содержит **готовую реализацию для оценки «3»** на базе лабораторной №3: Flask, PostgreSQL, HAProxy (две API-реплики), MinIO S3 и приватные вложения. Исходные задание, контракт и публичные тесты сохранены. Инструкции по запуску и решения/ограничения — в [REPORT.md](REPORT.md). UI не обязателен. [Карта курса](COURSE.md) · [Процесс fork/PR](CONTRIBUTING.md) · [OpenAPI](contracts/openapi.json) · [Семантика API](contracts/README.md) · [Проверки](tests/README.md) · [Отчёт](REPORT.md) · [Примеры JSON](contracts/examples.json) · [Памятка преподавателю](MAINTAINERS.md) diff --git a/REPORT.md b/REPORT.md index 9ad2b84f..53ff733c 100644 --- a/REPORT.md +++ b/REPORT.md @@ -1,37 +1,87 @@ -# Отчёт — лабораторная 4 +# Отчёт — лабораторная работа №4 -- Автор, группа: TODO -- Целевая оценка; выбранный трек 5, если нужен: TODO -- Commit/PR: TODO после публикации -- Использованные источники, библиотеки и помощь ИИ: TODO +- Автор: **Сиренко Илья**. +- Группа: **БПИ2304**. +- Целевая оценка: **3**. Уровни 4/5 не заявлены. +- Основа: лабораторная №3 (Flask + PostgreSQL + HAProxy, две API-реплики, сессии и идемпотентные сообщения). +- Commit/PR: указать после публикации репозитория. +- Стек: Python 3.9+, Flask 3.1.0, Waitress 3.0.2, PostgreSQL 16.6, psycopg 3.2.6, HAProxy 3.0.8, boto3 1.36.26, Pillow 11.1.0, S3-совместимое объектное хранилище. +- Использованные источники и помощь ИИ: требования из Markdown-файлов лабораторной №4, `contracts/openapi.json`, публичные тесты и собственный проект лабораторной №3. ИИ использовался для разбора требований, проектирования структуры приложения, проверки соответствия контракту и подготовки отчёта. -## Запуск из чистого clone +## Запуск из чистого clone / ZIP -TODO: версии runtime/образов, prerequisites, команды создания локальных secrets/.env, build, миграций, запуска, ожидания готовности, тестов и остановки. Указать необходимые действия оператора. Не вставлять секреты. Отдельно указать безопасную остановку и команду намеренного удаления учебных данных. +Нужны Docker Engine с Compose v2, Python 3.9+ для публичных тестов и доступ к registry для загрузки контейнерных образов. Все команды выполняются в корне `mtusi2026lab4`. Опубликован только HAProxy на `127.0.0.1:8080`. -## Архитектура и решения +```sh +python3 scripts/init_local.py +# Секреты создаются один раз в secrets/ и не входят в ZIP/Git. +docker compose --env-file .env config --quiet +docker compose --env-file .env up -d --build +docker compose --env-file .env ps +# дождаться: curl -fsS http://localhost:8080/health/ready +make check +make test +``` -TODO: схема процессов/хранилищ, источник истины, транзакционные границы, ограничения. Что перенесено из lab3, что изменено в этой работе. Соответствие переменных из .env.example реальной конфигурации. +Swagger UI в четвёртой лабораторной не заявлен; машинно-читаемый контракт доступен в `contracts/openapi.json`. Проверка через curl: `curl http://localhost:8080/health/live`. Выключение: `docker compose down` (данные остаются); намеренное уничтожение **всех учебных данных**: `docker compose down -v` (не делайте при проверке persistence). После изменения миграций запустить `docker compose up -d --build`, сервис `migrate` применит версии однократно. Если ранее был развёрнут lab3 со своими томами, сохраняйте его PostgreSQL volume и секреты при переносе; новая миграция `003_attachments.sql` добавляется к существующей схеме. -## Доказательства критериев +## Архитектура -| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства | -| --- | --- | --- | --- | -| Публичный smoke | make test | TODO | TODO | -| Остальные пункты уровня 3 | TODO | TODO | TODO | -| Все пункты уровня 4, если заявлен | TODO | TODO | TODO | -| Выбранный трек 5, если заявлен | TODO | TODO | TODO | +``` +REST-клиент -> HAProxy :8080 -> api1 / api2 (Flask + waitress) + | | + +-- PostgreSQL :5432 (таблицы/сессии/идемпотентность) + +-- MinIO S3 :9000 (оригиналы PNG/JPEG) +``` -TODO: добавить отдельную строку для каждого заявленного критерия. PASS без команды и наблюдения не является доказательством. Проверка инфраструктурного hook требует подтверждения, какие реальные процессы/хранилища перезапущены. +* `db`: `postgres:16.6-bookworm`, БД messenger, `postgres_data`, health `pg_isready`. `migrate` однократно создаёт/обновляет schema_migrations. +* `s3`: `minio/minio:RELEASE.2025-02-07T23-21-09Z`, `s3_data`, без опубликованных портов, локальный health endpoint; `s3-bootstrap` идемпотентно создаёт приватный bucket `messenger-attachments`. +* `api1` и `api2`: сборка из `Dockerfile` на `python:3.11.11-slim-bookworm`, readiness проверяет и БД, и S3; не имеют volume для бинарных вложений. +* `lb`: `haproxy:3.0.8-bookworm`, опубликован только `127.0.0.1:8080`. +* Секреты: `secrets/postgres_password`, `secrets/database_url`, `secrets/s3_password` создаются локально `scripts/init_local.py`; `DATABASE_URL_FILE`, `S3_SECRET_FILE` указывают на Docker secrets. `APP_ENV`, TTL и сетевые параметры заданы в Compose. API использует административные MinIO credentials ради простоты уровня 3; разграничение S3 permissions — задача уровня 4. + +## Логика загрузки + +1. Bearer-сессия и принадлежность чату проверяются перед чтением тела. `filename` валидируется, не используется в пути. Заголовок MIME и содержимое должны соответствовать PNG либо JPEG. +2. Лимит чтения 10 MiB + 1 байт и пикселей 40 млн проверяется **до** полной распаковки; Pillow проверяет структуру и полное декодирование. Объекту назначается независимый случайный ключ `originals//`. +3. Бинарный оригинал записывается в **приватный S3**. После успешного PUT данные метаданных коммитятся в PostgreSQL, только затем отдаётся `201 ready` (`variants=[]`, `error_code=null`). SHA-256 и размер считаются по исходным байтам. +4. Для создания сообщения допускается `attachment_ids` 0–10 уникальных UUID, включая пустой текст с непустым массивом. Все IDs должны принадлежать чату. `message_attachments` хранит порядок; идемпотентность учитывает текст и отсортированный по позиции список IDs (порядок важен). +5. `GET /attachments/{id}` и `/content` разрешены только участникам чата. API скачивает байты напрямую из S3, без редиректа и без открытия bucket наружу. Чужому пользователю возвращается одинаковый `404` для несуществующего или недоступного объекта. + +SQL-транзакция не охватывает S3: если PUT прошёл, а запись БД не состоялась, выполняется **best-effort** удаление ключа. При разрыве процесса либо при отказе удаления возможен orphan-объект; полноценную фоновую сверку на уровне 3 не заявляем. Приватность bucket обеспечивается отсутствием публичной policy и закрытым сетевым портом; авторизация реализована отдельно в API. + +## Доказательства критериев оценки «3» + +Результаты ниже отделяют **фактически выполненные локальные проверки** от контейнерных и сетевых сценариев, требующих работающего Docker-стенда. Для подтверждения на машине студента вывод команд можно сохранить в `evidence/`: + +```sh +mkdir -p evidence +make check 2>&1 | tee evidence/contract-local.txt +python3 -m unittest discover -s student-tests -p test_images.py -v 2>&1 | tee evidence/images-local.txt +docker compose --env-file .env ps -a 2>&1 | tee evidence/docker-services.txt +make test 2>&1 | tee evidence/public-smoke.txt +``` + + + +| Проверка | Команда / метод | Ожидаемый критерий | +| --- | --- | --- | +| Контракт и исходники | `make check` | Корректная структура lab4/OpenAPI и синтаксис Python | +| Локальная валидация файлов | `python -m unittest discover -s student-tests -p test_images.py -v` | Реальный PNG, неверный MIME, повреждение, лимит bytes/pixels | +| Сквозной API | `make test` | Авторизация и lab3-функции, `201 ready`, SHA-256, бинарный download, чужой пользователь 404 | +| Отказ API-реплики | `make test-failover ACTION_SCRIPT=scripts/stop-one.sh` | `TARGET_INSTANCE_ID` останавливается, другой API обслуживает запросы; тест включает S3 file check для lab4 | +| Долговечность | `make test-persistence ACTION_SCRIPT=scripts/restart.sh` | Перезапуск двух API, PostgreSQL и MinIO с прежними volumes, затем чтение с прежним токеном | +| Приватность S3 | `docker compose exec -T api1 python -c 'from messenger.config import Settings; from messenger.storage import ObjectStore; s=ObjectStore(Settings.from_env()); print(s.s3.get_bucket_policy(Bucket=s.bucket))'` | Без заданной публичной policy запрос должен закончиться ошибкой `NoSuchBucketPolicy`; по умолчанию бакет приватен | + +**Фактически выполнено в среде подготовки:** `python scripts/check_contract.py` — PASS; `python -m unittest discover -s student-tests -p test_images.py -v` — 4 OK; `python -m compileall -q messenger` — без ошибок. ## Эксперименты и отказы -TODO: гипотеза, hardware/лимиты, версии, объём данных, профиль нагрузки, concurrency/arrival rate, длительность/прогрев, повторы, успешные RPS, ошибки, p50/p95/p99, CPU/RAM. Сохранить raw summary без tokens и объяснить ограничения измерения. - -| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных | -| --- | --- | --- | --- | -| TODO | TODO | TODO | TODO | - -## Ограничения и следующие шаги - -TODO: какие отказы выдерживаются и какие нет; что не реализовано; где учебное упрощение; какое улучшение подтверждено, а какое пока гипотеза. +| Сценарий | Ожидаемое поведение | Наблюдение / статус | +| --- | --- | --- | +| Неверный MIME или повреждённое изображение | Отказ без создания корректного вложения | Проверено локальными unit-тестами, 4 теста OK | +| Файл, превышающий лимиты | Отказ в загрузке | Проверено локальными unit-тестами | +| Чтение чужого вложения | 404 без раскрытия данных | Реализовано в API, end-to-end проверка на Docker-хосте требуется | +| Перезапуск API и хранилищ | Сохранение метаданных в PostgreSQL и оригиналов в S3 volumes | Подготовлен тест `make test-persistence`, Docker-подтверждение не получено | +| Остановка одной API-реплики | Вторая реплика продолжает обслуживать HTTP-запросы через HAProxy | Подготовлен тест `make test-failover`, Docker-подтверждение не получено | +| Отказ между PUT в S3 и COMMIT в БД | Best-effort удаление S3-объекта | Реализована компенсация, гарантированной очистки orphan-объектов нет |