103 lines
10 KiB
Markdown
103 lines
10 KiB
Markdown
# Лабораторная 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)
|