mtusi2026lab2/COURSE.md

Сквозной проект: мессенджер под нагрузкой

Семь самостоятельных репозиториев содержат задания и проверяемые контракты одной системы. Вы переносите собственную реализацию между лабораторными. Язык, фреймворк и библиотеки выбираете сами. Web UI, WebSocket, редактирование/удаление сообщений, публичный поиск пользователей и Kubernetes не входят в обязательный минимум: достаточно REST API.

Лаба	Новая инженерная задача	Что появляется в системе
1	Контракт, процессы и контейнер	In-memory API, Dockerfile, HTTP smoke
2	Сохранность и идентификация	PostgreSQL, Basic → сессия; Redis/Valkey на 4
3	Горизонтальное масштабирование	Балансировщик, ≥2 API-реплики, общие сессии, идемпотентность
4	Бинарные данные	Приватное S3-совместимое хранилище и вложения
5	Фоновая работа	Брокер, worker, состояния вложений и преобразование изображений
6	Диагностика	OTel Collector, хранилища сигналов, Grafana
7	Защита и эксплуатация	Argon2id, TLS/mTLS, OpenBao, минимальные привилегии

Как оценивать

Оценки накопительные внутри лабораторной: 4 = весь уровень 3 + весь уровень 4; 5 = весь уровень 4 + один полностью выполненный трек 5 на выбор. Несколько недоделанных треков не заменяют один завершённый. Условие «весь уровень» включает реализацию, проверку и объяснение на защите. Красивые схемы и дополнительные технологии не компенсируют неработающий обязательный сценарий.

Для начала следующей лабы достаточно обязательного минимума предыдущей. Сохраняются предыдущие обязательные возможности, с явно описанными переходами API ниже. Не требуется сначала получить 5 за все ранние лабы. Можно исправлять свою базу по ходу курса; такие исправления выделяйте в PR. Реализация на 3 работоспособна, но не претендует на промышленную готовность. Даже 5 в lab7 — учебная доказанная защита в заявленной модели угроз, а не сертификат полной безопасности.

На 3 студент самостоятельно собирает рабочую систему. На 4 показывает практики, ожидаемые от стажёра/джуна в команде: воспроизводимость, диагностику, обработку ошибок и проверки отказов. На 5 формулирует гипотезу, ставит эксперимент, приводит измерения и обсуждает границы решения — это предмет конкретной похвалы магистранту.

Контракт и совместимость

contracts/openapi.json — OpenAPI 3.1.0, contracts/README.md — нормативная семантика. Контракт каждого репозитория самодостаточен; соседние папки на машине преподавателя не нужны. tests/ — публичные проверки, а не эталонное решение. Контракт, рубрика и публичные тесты имеют приоритет над случайным поведением библиотек. При противоречии создайте вопрос преподавателю; не подгоняйте тест под приложение.

Три объявленных изменения обязательного API:

1. 1 → 2: регистрация требует password; X-User-Id заменяется Bearer. Basic используется только при создании сессии.
2. 2 → 3: Idempotency-Key обязателен для отправки сообщения; ответы API содержат X-Instance-Id.
3. 4 → 5: загрузка вложения возвращает 202 вместо 201, состояние становится асинхронным. Клиент опрашивает метаданные. Старое текстовое сообщение остаётся валидным: attachment_ids по умолчанию [].

У lab7 меняется транспорт на HTTPS, бизнес-эндпоинты остаются прежними. Внутреннее mTLS не заменяет пользовательскую сессию. Новые возможности на 4/5 добавляйте обратно совместимо, в отдельном contracts/extensions.openapi.json или документе; обязательный контракт сохраняйте.

Общая предметная модель

Пользователь (username, display_name) состоит в чатах. Список участников задаётся при создании чата и в обязательном API не изменяется. В чате отправляются сообщения, с lab4 — со ссылками на вложения этого чата. Сервер назначает UUID и время. Порядок истории — (created_at, id) по возрастанию. Для защиты достаточно показать взаимодействие нескольких API-клиентов; фронтенд не требуется.

С lab2 данные PostgreSQL — источник истины. Сессии могут храниться в PostgreSQL или Redis/Valkey, если выполняют контракт срока жизни и перезапуска. Файлы с lab4 живут в S3, метаданные — в PostgreSQL. Redis и Valkey — альтернативы: оба одновременно не нужны. Аналогично выбирается одно S3-хранилище, один брокер и один основной путь оркестрации.

Воспроизводимость и честные измерения

• Укажите версии runtime и контейнерных образов, аппаратную конфигурацию, CPU/RAM-лимиты, команду запуска и время прогрева. Для образов используйте явный тег версии или digest, не latest.
• Все тестовые пользователи и изображения синтетические. make test создаёт данные: запускайте его на учебном стенде. Не публикуйте пароли, токены, приватные ключи, персональные данные или подписанные URL.
• Минимальный отчёт о нагрузке: длительность, конкуренция/интенсивность, успешные RPS, доля ошибок, p50/p95/p99, CPU/RAM, размер набора данных. Универсального проходного RPS для разных ноутбуков нет.
• Сравнивайте одинаковые запросы при одинаковых ресурсах. Успешный /health/live не доказывает сохранность сообщений, а HTTP 202 — окончание обработки.
• Один Docker-host не обеспечивает отказоустойчивость к потере этого host. Несколько API-процессов не делают единственную БД или LB высокодоступными. Отдельно называйте, какие отказы выдерживает эксперимент.

Что сдавать

Исходники, Dockerfile, нужные манифесты и конфигурации, миграции, собственные тесты, заполненный REPORT.md, сведения об использовании внешнего кода и ИИ. Уметь объяснить и изменить своё решение на защите обязательно. Приложите команды и текстовые результаты; скриншоты — дополнение, а не единственное доказательство.

PR должен собираться из чистого clone по инструкции автора. Секреты создаются отдельно; тестовые fixtures и открытые конфигурации хранятся в репозитории. Перенос кода между лабами описан в CONTRIBUTING.md.