Files
2026-10-10 02:13:35 +03:00

100 lines
6.8 KiB
Markdown
Raw Permalink 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.
# Коллекция 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`). Секретов в файлах нет: пароль и токен
метрик задаются переменными окружения.