Files
mtusi2026lab2/docs/PROJECT_MAP.md
T
Никита 6a8908ab99
Skeleton contracts / contracts (pull_request) Failing after 30s
ЛР 2: PostgreSQL, сессии, Redis и исследование
2026-10-06 13:34:34 +03:00

16 KiB
Raw Blame History

n1k0der: где находится мессенджер

Весь репозиторий: /Users/nikitakamensky/Documents/mtusi2026lab2.

Код приложения: src/Messenger.Api/. Код страницы: src/Messenger.Api/wwwroot/.

На Mac открыть проект в Finder можно так:

open ~/Documents/mtusi2026lab2

Сервер и страница находятся в одном ASP.NET Core проекте. База PostgreSQL и Redis запускаются отдельными контейнерами. Данные сообщений находятся в PostgreSQL, не в HTML-файле и не в папке с исходниками.

1. Карта папок

mtusi2026lab2/
├── src/Messenger.Api/          приложение
│   ├── Program.cs             запуск и подключение частей
│   ├── Endpoints/             HTTP-адреса, проверки и ответы
│   ├── Services/              операции приложения
│   ├── Data/                  SQL и работа с PostgreSQL
│   │   ├── Entities/          внутренние записи базы в C#
│   │   └── Migrations/        SQL создания структуры базы
│   ├── Contracts/             формат входных/выходных данных
│   ├── Middleware/            общая обработка HTTP-запросов
│   ├── Infrastructure/        работа с Redis
│   └── wwwroot/               HTML, CSS, JavaScript страницы
├── compose.yaml               API, PostgreSQL, Redis, восстановление
├── Dockerfile                 сборка контейнера приложения
├── Makefile                   короткие команды запуска и проверок
├── scripts/                   перезапуск и запуск проверок
├── student-tests/             собственные тесты и исследование
├── tests/                     публичные проверки преподавателя
├── contracts/                 обязательный контракт задания
├── docs/                      объяснения и подготовка к защите
└── evidence/                  результаты проверок и исследования

2. Что открыть, если спрашивают конкретную возможность

Вопрос Файл Простое объяснение
Где запускается сервер? Program.cs Настраивает приложение и подключает остальные части
Где регистрация и ограничения login/password? UserEndpoints.cs Принимает данные, проверяет их и возвращает HTTP-ответ
Где сохраняется новый пользователь? UserService.cs Хеширует пароль, вызывает БД, обрабатывает занятый username
Где хешируется пароль? PasswordService.cs Argon2id со случайной солью; Hash и Verify
Где вход и выход? AuthEndpoints.cs Вход через Basic, выход через DELETE текущей сессии
Где токен, срок и проверка сессии? SessionService.cs LoginAsync, AuthenticateAsync, RevokeAsync
Где создание чата и проверка повторных участников? ChatEndpoints.cs Проверяет список участников, включая повторы и создателя
Где отправка и история сообщений? MessageEndpoints.cs Проверяет сессию, доступ к чату и текст сообщения
Где SQL, INSERT и транзакция? AppDatabase.cs Выполняет команды PostgreSQL; CreateChatAsync объединяет чат и участников
Где проверяется участие в чате? AppDatabase.cs FindChatForMemberAsync проверяет chat_members; endpoint использует результат
Где таблицы, UNIQUE и индекс? 001_initial.sql CREATE TABLE и CREATE INDEX
Где применяются миграции? DatabaseMigrator.cs Выполняет новые SQL-версии и отмечает их в schema_migrations
Где Redis и его TTL? RedisSessionCache.cs Чтение, запись и удаление кэша, таймауты и fallback
Где страницы истории и cursor? CursorService.cs Кодирует/декодирует cursor; ApiSupport проверяет его и limit
Где ошибки 400/401? ApiSupport.cs Общие JSON-ошибки, Bearer/Basic challenge и проверки параметров
Где ответ 503 при отказе базы? ExceptionHandlingMiddleware.cs Переводит ошибки зависимости в безопасный HTTP-ответ
Где журнал запросов? RequestLoggingMiddleware.cs Метод, путь, статус и длительность
Где X-Request-Id? RequestIdMiddleware.cs Идентификатор для сопоставления ответа и журнала
Где проверка готовности? HealthEndpoints.cs /health/live и /health/ready

Пример ответа: «Повторных участников проверяем в ChatEndpoints.cs. Список сравнивается с Distinct. Если есть повтор, возвращаем 400. База дополнительно запрещает повтор пары chat_id/user_id».

3. Весь фронтенд: шесть файлов

Файл Что в нём
index.html Название n1k0der, формы входа/регистрации, кнопки, список чатов, область сообщений, окна и элементы фигур
app.css Цвета, размеры, расположение, мобильная версия, внешний вид фигур и CSS-анимации облачков
app.js Обработчики кнопок, fetch к API, токен, отображение чатов/сообщений, обновление раз в 4 секунды
mascots.js Реакции фигур на поля и пароль, прыжки к вводу и назад, наклоны, страх и сон
defense.js Панель режима защиты: последние запросы, HTTP-коды, X-Request-Id, срок сессии
scenarios.js Кнопки подготовки демонстрации и проверки типичных ошибок через реальные API-запросы

Если просят изменить название - index.html. Цвет - app.css, переменные --accent/--paper/--ink. Движение фигуры - mascots.js. Отправку сообщения из браузера - app.js, обработчик message-form.

UiEndpoints.cs - дополнительная серверная часть для фронтенда: список участников и чтение последних сообщений с загрузкой более старых. Это C# endpoint, не файл дизайна. Обязательный API /api/v1 сохранён отдельно.

4. Оставшиеся серверные файлы

Services

  • ChatService.cs: операции с чатами и преобразование записей БД в ответы.
  • MessageService.cs: запись/чтение сообщений и преобразование в ответы.
  • UserService.cs: регистрация и публичные данные пользователей.
  • SessionService.cs: создание, проверка и отзыв сессии.
  • PasswordService.cs: hash/проверка пароля.
  • CursorService.cs: упаковка/разбор указателя страницы.
  • ApiSupport.cs: общие проверки входных данных и JSON-ошибки.

Здесь некоторые сервисы небольшие: они делегируют SQL в AppDatabase. Проверки входных данных и доступа также находятся в Endpoints.

Contracts: какие данные принимает/возвращает API

  • CreateUserRequest.cs: username, display_name, password при регистрации.
  • CreateChatRequest.cs: title и member_ids при создании чата.
  • CreateMessageRequest.cs: text при отправке сообщения.
  • UserDto.cs: публичные данные пользователя, без hash пароля.
  • ChatDto.cs: данные чата.
  • MessageDto.cs: данные сообщения.
  • SessionDto.cs: результат входа с токеном, сроком и пользователем.
  • ChatCursor.cs: место продолжения списка чатов или истории.

DTO - объект, который отправляем клиенту. Request - объект входного запроса.

Data/Entities: внутренние записи

  • UserEntity.cs: пользователь, включая внутренний password_hash.
  • ChatEntity.cs: чат и его участники в представлении C#.
  • MessageEntity.cs: сообщение.
  • SessionEntity.cs: пользователь и срок найденной активной сессии.

Участники хранятся в отдельной SQL-таблице chat_members; отдельный ChatMemberEntity.cs здесь не нужен и отсутствует. UtcClock.cs задаёт время UTC с точностью, подходящей PostgreSQL.

Настройки и библиотеки

  • Messenger.Api.csproj: версия .NET, библиотеки Npgsql/Argon2/Redis, включение SQL-миграций в сборку.
  • appsettings.json и appsettings.Development.json: настройки приложения и журнала.
  • Properties/launchSettings.json: параметры локального запуска через dotnet.

5. Запуск, база и проверка работы

Файл/папка Что сказать
compose.yaml Запускает компоненты и подключает volume БД; дополнительная база восстановления включается профилем research
Dockerfile Собирает C# и упаковывает приложение для запуска в контейнере
Makefile Даёт команды make up, make test, make test-persistence, make verify-grade5
.env Локальный порт и срок сессии; в Git не публикуется
secrets/ Локальные секреты подключения; создаются init-secrets.sh, в Git не публикуются
scripts/init-secrets.sh Подготавливает секреты для запуска
scripts/restart.sh Перезапускает API и хранилища с сохранением volume
scripts/test-expiry.sh Проверяет короткий срок сессии
scripts/verify-grade4.sh и verify-grade5.sh Запускают наборы проверок и сохраняют лог
tests/ Публичные проверки лабораторной
student-tests/ Дополнительные проверки этой реализации
evidence/ Сохранённые результаты проверок и планы SQL
backups/ Локальные резервные копии; игнорируются Git
REPORT.md Описание реализации, запуск, проверки и ограничения
docs/RESEARCH.md Сравнение индексов и восстановление уровня 5

В student-tests: lab2_tests.py - дополнительный API; grade4_tests.py - гонка регистрации, rollback и кэш; dependency_tests.py - отказы; explain_history.py - индекс на 10 тысячах сообщений; research_track2.py - 100 тысяч, два индекса, backup/restore; ui_api_tests.py - серверные маршруты для интерфейса.

6. Проследить одну возможность по файлам

Отправка сообщения

index.html: форма message-form
→ app.js: обработчик submit, HTTP POST через fetch
→ MessageEndpoints.cs: сессия, доступ и проверка текста
→ MessageService.cs: операция создания
→ AppDatabase.cs: CreateMessageAsync, SQL INSERT
→ PostgreSQL: таблица messages
→ ответ API
→ app.js: отображение сообщения.

Перед выполнением операции SessionService.AuthenticateAsync проверяет токен. Проверка участия проходит через ChatService.FindForMemberAsync и AppDatabase.FindChatForMemberAsync.

Вход

app.js: отправляет Basic
→ AuthEndpoints.cs: разбирает заголовок
→ SessionService.LoginAsync
→ AppDatabase: найти пользователя
→ PasswordService.Verify: проверить пароль
→ SessionService: создать случайный токен
→ AppDatabase: сохранить hash токена и срок
→ RedisSessionCache: попытаться заполнить кэш
→ app.js: сохранить сессию и открыть чаты.

Создание чата

app.js → ChatEndpoints.cs → ChatService.cs → AppDatabase.CreateChatAsync
→ одна транзакция: chats + chat_members → COMMIT.

Изменение оформления

Название/элементы → index.html
Цвета/размеры → app.css
Реакции фигур → mascots.js
Поведение кнопок/запросы → app.js

7. Восемь файлов, которые стоит запомнить сначала

Program.cs → запуск. index.html → страница. app.css → вид. app.js → действия клиента. MessageEndpoints.cs → сообщение приходит на сервер. SessionService.cs → проверка входа. AppDatabase.cs → SQL. 001_initial.sql → таблицы и индексы.

Рассказ на защите: «Открою путь этой операции от браузера до базы». Покажи перечисленные файлы по цепочке. Так проще объяснить связь частей, чем читать весь проект подряд.