Files
mtusi2026lab2/.github/pull_request_template.md
T
ilya.tyunin 575f8ee386
Skeleton contracts / contracts (pull_request) Canceled after 0s
feat: lab2 done
2026-10-09 15:48:03 +03:00

79 lines
8.9 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.
## Лабораторная 2
Автор / группа: Тюнин Илья БВТ2303
Целевая оценка (3/4/5): 5
Трек 1, если заявлен: Трек 1 «Согласованность кэша» — при 32 конкурентных чтениях холодной страницы × 5 повторностей: **160 SQL-запросов истории в naive против 5 в protected (−96,9 %)**, read-after-write подтверждён, сессия и история переживают рестарт Redis
### Что реализовано
- **PostgreSQL 16.4 — источник истины**: `users`, `chats`, `chat_members`, `messages`; версионируемые миграции `001_initial.sql`, `002_timestamp_precision.sql`; raw `pg.Pool` с ограниченным пулом, connection/statement timeout и параметризованными запросами, без ORM.
- **Транзакционные границы**: создание чата (валидация участников + chat + membership) и отправка сообщения (membership + insert + `message_version`) — в одной транзакции с rollback; проверено отсутствие частичных данных.
- **Redis 7.4.2 с AOF — серверные Bearer-сессии** с TTL, expiry и logout; одновременно версионированный кэш истории с lock на конкретную страницу `(chat_id, message_version, cursor, limit)` и fallback в PostgreSQL при недоступности Redis.
- **Аутентификация по контракту lab2**: Basic только на `POST /auth/sessions` (UTF-8, первый `:`), Bearer на бизнес-endpoint, `X-User-Id` не аутентифицирует и не подменяет владельца, Argon2id, opaque-токен 256 бит.
- **Воспроизводимый стенд**: Compose с pinned-образами, именованными volumes, healthchecks, сервисом миграций перед API, конфигурацией через `.env`.
- **Наблюдаемость**: token-gated `GET /internal/metrics` и `POST /internal/metrics/reset` — SQL-метки, операции Redis, cache hit/miss/lock wait, session get/set/del, request count, агрегаты латентности; деградации кэша и зависимостей пишутся счётчиками и `warn`-логами, а не проглатываются.
- **Перенесено из lab1** с объявленным переходом: health, регистрация/пользователи, чаты и участники, сообщения, keyset-пагинация — переведены на новую аутентификацию.
Подробности решения — [`REPORT.md`](../REPORT.md) (архитектура, схема, транзакции, политика кэша, команды, ограничения).
Проверки уровня 3/4 — [`evidence/level3-4-verification.md`](../evidence/level3-4-verification.md).
Трек 1 — [`evidence/track1-cache-consistency.md`](../evidence/track1-cache-consistency.md) и [`evidence/track1-explain.md`](../evidence/track1-explain.md).
Навигация по доказательствам — [`evidence/README.md`](../evidence/README.md).
Ручной клиент для разбора API — [`bruno/README.md`](../bruno/README.md).
### Команды запуска из чистого clone
```sh
cp .env.example .env
password=$(openssl rand -hex 32)
sed -i "s/^POSTGRES_PASSWORD=.*/POSTGRES_PASSWORD=$password/" .env
sed -i "s|^DATABASE_URL=.*|DATABASE_URL=postgresql://messenger:$password@postgres:5432/messenger|" .env
sed -i "s/^METRICS_TOKEN=.*/METRICS_TOKEN=$(openssl rand -hex 16)/" .env
unset password
docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build # postgres/redis healthy, migrate exit 0, api healthy
curl -fsS http://localhost:8080/health/ready
```
Пояснения по переменным и паролю существующего volume — [`.env.example`](../.env.example) и [REPORT.md § «Конфигурация и секреты»](../REPORT.md).
### Результаты проверок (фактический вывод)
```text
make check PASS
make validate PASS
make test BASE_URL=http://localhost:8080 PASS: lab2 public API scenario
make test-persistence ACTION_SCRIPT=scripts/restart.sh PASS: preserved confirmed data and existing session
(cd app && npm run build) PASS
(cd app && npm test) 5 files, 13 tests passed
(cd app && npx tsc --noEmit) PASS
integration suite (реальные PostgreSQL/Redis) 7 passed | 1 skipped
то же с SESSION_TTL_SECONDS=2 8 passed (expiry → 401)
коллекция Bruno (bru run -r --env local) 28 запросов, 56 проверок — все зелёные
```
Трек 1 (32 конкурентных GET × 5 повторностей, `CACHE_MISS_DELAY_MS=75`):
| Режим | SQL `messages.history` | Cache hits | Ошибок | p50, мс |
| --------- | ---------------------: | ---------: | -----: | ------: |
| naive | 160 | 0 | 0 | ≈ 89 |
| protected | 5 | 155 | 0 | ≈ 20 |
Отдельно проверены: гонка одинакового username (201 + 409, в таблице ровно 1 строка, unique-индекс), rollback при неизвестном участнике чата (`400`, строк не осталось), отказы Redis и PostgreSQL (`/health/ready` 503, анонимный доступ не выдаётся, процесс API жив, после старта — 200 с тем же токеном), `EXPLAIN (ANALYZE, BUFFERS)` на 10 002 сообщениях (Index Scan по `messages_chat_created_id_idx`, keyset-предикат в `Index Cond`).
- [x] Весь обязательный минимум текущей и предыдущих работ сохранён с объявленными переходами.
- [x] Контракт и публичные тесты не ослаблены (`contracts/` и `tests/` не изменялись).
- [x] `make check` и `make test` выполнены; приложен реальный вывод (выше и в evidence).
- [x] Сценарии отказов/безопасности своего уровня воспроизведены (отказы Redis/PostgreSQL, expiry, logout/replay, spoofing, rollback — [журнал](../evidence/level3-4-verification.md)).
- [x] Все секреты и приватные ключи находятся вне Git: `.env` и локальные секреты покрыты `.gitignore`, в отчёте и evidence нет токенов и паролей.
- [x] README задания сохранён, `REPORT.md` содержит инструкцию именно этого решения.
### Ограничения / известные ошибки
- Метрики локальны процессу API и сбрасываются при его рестарте; при нескольких репликах их нельзя суммировать как распределённый снимок.
- Измерения трека 1 — closed-loop на одном хосте (32 конкурентных читателя, 5 повторностей): это не production-пропускная способность.
- `redis-data` хранит действующие сессии: удаление volume осознанно разлогинивает пользователей; AOF плюс сохранённый volume — проверенная граница durability.
- `CACHE_MODE=naive` и `CACHE_MISS_DELAY_MS` предназначены только для эксперимента и задаются переменными окружения при пересоздании контейнера `api` (например, `CACHE_MODE=naive CACHE_MISS_DELAY_MS=75 docker compose --env-file .env up -d api`); задержка влияет только на naive-путь.
- Порты PostgreSQL/Redis наружу не публикуются, поэтому интеграционный набор запускается с адресами контейнеров (команда в [REPORT.md](../REPORT.md) § «Команды проверок»).
- Сырые прогоны бенчмарка не коммитятся (локальные идентификаторы); их хеши — в [`evidence/track1-cache-consistency.md`](../evidence/track1-cache-consistency.md) §8.