Заполнить отчёт и README лабораторной работы
REPORT.md: запуск, архитектура, логика загрузки, ограничения уровня 3, таблица доказательств. README: ссылка на отчёт вместо отсутствующего START_HERE.md.
This commit is contained in:
@@ -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)
|
||||
|
||||
|
||||
@@ -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/<random>/<random>`.
|
||||
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-объектов нет |
|
||||
|
||||
Reference in New Issue
Block a user