Files
mtusi2026lab4/README.md
T

103 lines
10 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Лабораторная 1. Docker и in-memory мессенджер
Научиться превращать API-контракт в работающий процесс и воспроизводимый контейнер. Все данные хранятся в памяти одного процесса и намеренно исчезают после его перезапуска.
Это **skeleton**, а не готовый сервер. Здесь есть задание, контракт и публичные проверки. Реализацию приложения, Dockerfile и требуемую инфраструктуру пишет студент. Язык и framework свободные; 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)
## Откуда начинаем
Предыдущая работа не требуется. Нужны основы HTTP/JSON, выбранного языка и Git. Прочитайте общую модель в COURSE.md.
**Архитектура:** Клиент → HTTP API → структуры в памяти одного процесса.
## Что сделать
1. Изучите OpenAPI и запустите публичный тест против отсутствующего сервера: он должен завершиться ошибкой соединения. Это ожидаемо для skeleton.
2. Реализуйте пользователей, чаты и историю сообщений; отдельно проверьте Unicode, валидацию и выбор текущего пользователя через X-User-Id.
3. Напишите Dockerfile: приложение слушает 0.0.0.0:8080, конфигурация приходит из окружения, сервер — основной процесс контейнера.
4. Соберите образ из чистого clone, запустите контейнер и выполните make test. Затем перезапустите контейнер и покажите, что состояние сбросилось.
## Оценка «3»: работающий минимум
- Все endpoint lab1, форматы ошибок, членство в чатах и пагинация соответствуют contracts/openapi.json и contracts/README.md. Публичный smoke проходит.
- Состояние только в памяти одного процесса: без PostgreSQL, Redis, файлов состояния и внешних сервисов. Параллельные запросы не должны повреждать базовые структуры.
- Dockerfile собирает приложение из исходников; запуск docker run публикует API на localhost:8080. Повторная сборка и запуск описаны в REPORT.md.
- Демонстрация жизненного цикла: создать сообщение → прочитать → перезапустить контейнер → прежний пользователь больше не существует. Объяснить границы in-memory хранения.
## Оценка «4»: уровень стажёра/джуна
Весь уровень 3 **и все** пункты ниже:
- Отдельные собственные тесты для неверного JSON, чужого чата, пустого сообщения, дубликата username и обхода нескольких страниц; тесты запускаются одной командой.
- Защита состояния от гонок: параллельно отправьте 100 сообщений от 10 клиентов, затем получите ровно 100 уникальных сообщений. Сохраните команду и результат.
- Контейнер работает от непривилегированного пользователя; зависимости и версия базового образа закреплены, .dockerignore исключает лишнее. Если язык компилируемый — сборка и runtime разделены.
- SIGTERM корректно завершает процесс в заявленный срок не более 10 секунд; новые запросы перестают приниматься. Есть Docker healthcheck, а stdout/stderr содержат полезные логи без содержимого сообщений.
## Оценка «5»: исследование и доказанный результат
Весь уровень 4 **и один законченный трек на выбор**. Приведите гипотезу, повторяемую методику, результаты и ограничения.
**Трек 1. Предел in-memory архитектуры.** Проведите повторяемый эксперимент с ростом числа сообщений и конкурентных клиентов: ≥3 размера истории и ≥3 уровня конкуренции. Измерьте throughput, p95/p99 и RSS, найдите узкое место, внесите одно изменение и сравните до/после при тех же лимитах. Сохраните данные и объясните, почему это улучшение работает.
**Трек 2. Управляемая деградация.** Введите явные лимиты памяти/числа сообщений/очереди запросов. При превышении сервер предсказуемо отклоняет запросы документированным 429/413/503, не падает с OOM и восстанавливается после снятия нагрузки. Покажите график нагрузки, ошибок и памяти, не удаляя подтверждённые сообщения незаметно.
## Как начать и проверить
```sh
# Работает прямо в skeleton, Python 3.9+; приложение не запускается:
make check
# После реализации запустите свой сервер/стенд по REPORT.md.
# По умолчанию тест использует http://localhost:8080.
make test
```
Для lab1 ориентир команд после написания Dockerfile:
```sh
docker build -t mtusi-messenger:lab1 .
docker run --rm --name mtusi-messenger-lab1 -p 127.0.0.1:8080:8080 --env-file .env mtusi-messenger:lab1
# В другом терминале: make test
```
Создайте локальный `.env` на основе `.env.example`. В skeleton нет Dockerfile с готовой реализацией; `Dockerfile.example` — список опорных шагов.
Примеры запросов доступны в `examples/requests.http`, примеры JSON — в `contracts/examples.json`. Для полной проверки схемы (по желанию локально; CI делает её автоматически):
```sh
python3 -m venv .venv
.venv/bin/python -m pip install -r requirements-dev.txt
make validate PYTHON=.venv/bin/python
```
Smoke не выставляет оценку автоматически. Проверку сохранности/отказов запускайте явно по [tests/README.md](tests/README.md), остальные доказательства приведите в отчёте.
## Сценарий защиты лабораторной работы
1. Из чистого clone собрать образ и открыть /health/ready; выполнить make test.
2. Показать через двух пользователей один чат и историю из двух сообщений; третий пользователь получает 404.
3. Перезапустить контейнер с тем же образом; прежний X-User-Id получает 401. Это ожидаемая потеря данных lab1.
4. Для 4: воспроизвести конкурентный тест и SIGTERM. Для 5: повторить выбранный эксперимент, объяснить измерения.
## Что должно быть в PR
Dockerfile, исходники, инструкция docker build/run, собственные тесты и заполненный REPORT.md. Compose не обязателен.
Заполните `REPORT.md` и [шаблон PR](.github/pull_request_template.md), укажите целевую оценку/трек. Не меняйте обязательный контракт и публичные tests ради зелёного результата. Сохраняйте возможности предыдущих лабораторных в пределах [объявленных переходов](COURSE.md).
## Вопросы на защите
- Чем процесс, контейнер и образ отличаются друг от друга?
- Почему bind на 127.0.0.1 внутри контейнера мешает доступу через published port?
- Что произойдёт при двух процессах с независимой памятью?
- Почему cursor лучше offset при росте истории и какие гарантии он сам по себе не даёт?
## Первичные материалы
- [Dockerfile reference](https://docs.docker.com/reference/dockerfile/)
- [Docker build best practices](https://docs.docker.com/build/building/best-practices/)
- [OpenAPI 3.1](https://spec.openapis.org/oas/v3.1.0.html)