# Лабораторная 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)