100 lines
6.8 KiB
Markdown
100 lines
6.8 KiB
Markdown
# Коллекция Bruno: ручки messenger (lab 2)
|
||
|
||
Ручной клиент для API: регистрация, Basic-вход, Bearer-доступ, чаты, сообщения
|
||
с пагинацией, метрики и негативные проверки. Формат — стандартный Bruno (`.bru`).
|
||
|
||
Связанные документы: [`../REPORT.md`](../REPORT.md) (архитектура и решения),
|
||
[`../evidence/README.md`](../evidence/README.md) (индекс доказательств),
|
||
[`../.github/pull_request_template.md`](../.github/pull_request_template.md) (сдача).
|
||
|
||
## Как открыть и запустить
|
||
|
||
```sh
|
||
# GUI: Collection -> Open -> выбрать папку bruno/ этого репозитория.
|
||
# baseUrl уже подставлен на уровне коллекции (collection.bru), вводить его
|
||
# в каждой ручке не нужно. Для реального METRICS_TOKEN выберите окружение
|
||
# `local` в правом верхнем углу и поправьте metricsToken.
|
||
|
||
# CLI (требуется @usebruno/cli; запускать из корня коллекции):
|
||
npm install -g @usebruno/cli
|
||
cd bruno
|
||
bru run -r --env-var metricsToken=$(grep '^METRICS_TOKEN=' ../.env | cut -d= -f2)
|
||
```
|
||
|
||
Проверено на `bru` 4.2.1 против локального стенда: 29 запросов, 58 проверок,
|
||
все зелёные (см. `../evidence/level3-4-verification.md` §12).
|
||
|
||
Стенд должен быть поднят: `docker compose --env-file .env up -d --build`,
|
||
готовность — `curl -fsS http://localhost:8080/health/ready`.
|
||
|
||
## Переменные и приоритет
|
||
|
||
| Источник | Что задаёт | Приоритет |
|
||
|---|---|---|
|
||
| `collection.bru` → `script:pre-request` | `baseUrl=http://localhost:8080`, `password=demo-password-123`, `metricsToken=change-me-metrics-token` | самый низкий: подставляется только если переменная нигде не задана |
|
||
| `environments/local.bru` (`--env local`) | те же три переменные для конкретного стенда | выше дефолтов |
|
||
| `--env-var name=value` (CLI) / runtime-переменные (GUI) | разовое значение | самый высокий |
|
||
|
||
Поэтому адрес API больше не нужно вводить в каждой ручке: он берётся из
|
||
настроек коллекции. Если `metricsToken` оставить заглушкой, два запроса к
|
||
`/internal/*` вернут 401 — это ожидаемо и описано в их `docs`; остальные 26
|
||
запросов проходят.
|
||
|
||
## Окружение
|
||
|
||
`environments/local.bru`:
|
||
|
||
| Переменная | Значение по умолчанию | Комментарий |
|
||
|---|---|---|
|
||
| `baseUrl` | `http://localhost:8080` | адрес API |
|
||
| `password` | `demo-password-123` | пароль демо-пользователей (12–128 code points) |
|
||
| `metricsToken` | `change-me-metrics-token` | возьмите `METRICS_TOKEN` из `.env`, иначе запросы к `/internal/*` вернут 401 |
|
||
|
||
## Порядок выполнения
|
||
|
||
Папки обходятся по алфавиту, внутри папки — по `seq`:
|
||
|
||
```text
|
||
auth/ регистрация трёх пользователей и три Basic-сессии, /users/me
|
||
chats/ создание чата (два участника), список чатов, чат по id
|
||
health/ /health/live и /health/ready
|
||
internal/ /internal/metrics и /internal/metrics/reset
|
||
messages/ два сообщения, первая страница истории, страница по курсору
|
||
negative/ неверный пароль, Basic на бизнес-endpoint, X-User-Id, 404 чужого чата, 400 на limit/cursor,
|
||
несуществующую календарную дату курсора и пробельный текст, 409 дубликата
|
||
zz-cleanup/ logout и проверка, что отозванный токен даёт 401 (выполняется последним)
|
||
```
|
||
|
||
Коллекция сохраняет переменные между запросами: `suffix`, `username`,
|
||
`secondUsername`, `thirdUsername`, `userId`, `secondUserId`, `thirdUserId`,
|
||
`token`, `secondToken`, `thirdToken`, `chatId`, `messageId`, `nextCursor`.
|
||
Повторный запуск не конфликтует с прошлым прогоном: username генерируется
|
||
из случайного суффикса, а дубликат проверяется отдельной негативной ручкой.
|
||
|
||
## Что проверяет каждая ручка
|
||
|
||
- `auth/register-user.bru` — 201, ответ без `password`/`password_hash`;
|
||
- `auth/create-session*.bru` — 201, `token_type: Bearer`, `expires_at` в UTC, `user` совпадает с зарегистрированным;
|
||
- `auth/me.bru` — Bearer-доступ и совпадение владельца;
|
||
- `chats/create-chat.bru` — атомарное создание чата с двумя участниками;
|
||
- `messages/send-message*.bru` — `sender_id` выведен из сессии, `chat_id` верный;
|
||
- `messages/history-*.bru` — `limit` соблюдён, курсор ведёт на следующую страницу и не повторяет элемент;
|
||
- `internal/metrics.bru` — счётчики и агрегаты латентности без секретов;
|
||
- `negative/*` — коды и challenge-заголовки, отсутствие подмены владельца через `X-User-Id`, 404 вместо 403 для чужого чата, 409 при дубликате username, 400 на невалидные limit/cursor (включая несуществующую дату `2026-02-31`, которая раньше доходила до SQL и давала 500) и пробельный текст.
|
||
|
||
## Проверка истечения сессии
|
||
|
||
```sh
|
||
SESSION_TTL_SECONDS=2 docker compose --env-file .env up -d api
|
||
# в Bruno: auth/create-session.bru -> создать сессию, подождать ~2.5 с
|
||
# затем auth/me.bru -> ожидается 401 с Bearer-challenge
|
||
docker compose --env-file .env up -d api # вернуть штатный TTL из .env
|
||
```
|
||
|
||
## Границы
|
||
|
||
Коллекция — удобный ручной клиент, а не замена автоматике: контракт и приёмку
|
||
проверяют `make test`, набор из `app/test/app.e2e-spec.ts` и бенчмарк трека 1
|
||
(`scripts/track1_cache_benchmark.py`). Секретов в файлах нет: пароль и токен
|
||
метрик задаются переменными окружения.
|