111 lines
4.0 KiB
Markdown
111 lines
4.0 KiB
Markdown
# API /api/session
|
|
|
|
Este README documenta la API de sesión incluida en `app/api/session` del proyecto.
|
|
|
|
Objetivo
|
|
- Proveer endpoints simples para crear y recuperar sesiones E2E que devuelven un token LiveKit y una `studioUrl` construida con la convención `/rooms/<roomName>`.
|
|
|
|
Endpoints
|
|
|
|
1) POST /api/session
|
|
- Uso: crea una sesión (genera token JWT con `livekit-server-sdk`) y guarda una entrada en el store en memoria.
|
|
- Request body (JSON):
|
|
- room (string) — nombre de la sala (opcional, por defecto `e2e-room`).
|
|
- username (string) — identidad del participante (opcional).
|
|
- ttl (number) — tiempo de vida en segundos del token (opcional, por defecto 300).
|
|
- Response (200):
|
|
```json
|
|
{ "id": "sess_<ts>_<rand>", "token": "<JWT>", "studioUrl": "https://mi-dominio/rooms/<room>" }
|
|
```
|
|
|
|
2) GET /api/session/:id
|
|
- Uso: recuperar la sesión previamente creada por `POST /api/session`.
|
|
- Response (200): retorna el objeto de sesión guardado en memoria, por ejemplo:
|
|
```json
|
|
{
|
|
"id": "sess_...",
|
|
"token": "...",
|
|
"room": "mi-room",
|
|
"username": "visual-runner",
|
|
"studioUrl": "https://mi-dominio/rooms/mi-room",
|
|
"createdAt": 169...
|
|
}
|
|
```
|
|
|
|
Variables de entorno relevantes
|
|
- LIVEKIT_API_KEY (required): clave pública para LiveKit.
|
|
- LIVEKIT_API_SECRET (required): secreto para firmar tokens.
|
|
- STUDIO_BASE (optional): base URL del frontend; si está definida, `studioUrl` se construye como `${STUDIO_BASE}/rooms/${room}`.
|
|
- Alternativas atendidas: `STUDIO_URL` o `BROADCAST_URL` si `STUDIO_BASE` no existe.
|
|
|
|
Notas técnicas
|
|
- El store es un Map en memoria (`app/api/session/store.ts`). Es volátil: si el servidor se reinicia, las sesiones se perderán. Para entornos reales usa Redis o una DB.
|
|
- El token se genera con `AccessToken` del paquete `livekit-server-sdk` y contiene los grants para `roomJoin`, `canPublish` y `canSubscribe`.
|
|
|
|
Comandos de ejemplo
|
|
|
|
1) Crear sesión (POST):
|
|
|
|
```bash
|
|
curl -sS -X POST http://localhost:3000/api/session \
|
|
-H 'Content-Type: application/json' \
|
|
-d '{"room":"mi-room-e2e","username":"tester","ttl":300}' | jq .
|
|
```
|
|
|
|
2) Recuperar sesión (GET):
|
|
|
|
```bash
|
|
curl -sS http://localhost:3000/api/session/sess_169... | jq .
|
|
```
|
|
|
|
3) Decodificar el token (inspección del payload JWT):
|
|
|
|
```bash
|
|
TOKEN="eyJhbGciOiJ..."
|
|
echo $TOKEN | cut -d '.' -f2 | tr '_-' '/+' | base64 -d 2>/dev/null | jq .
|
|
```
|
|
|
|
4) Probar manualmente en el frontend (DevTools)
|
|
- Abre: `https://mi-dominio/rooms/mi-room-e2e`.
|
|
- En la consola ejecuta:
|
|
|
|
```js
|
|
window.postMessage({ type: 'LIVEKIT_TOKEN', token: 'TOKEN_AQUI', room: '' }, window.location.origin);
|
|
```
|
|
|
|
El frontend debe escuchar `message` y conectar usando el token.
|
|
|
|
Probar con el E2E script
|
|
- Arrancar Chrome con remote-debugging (usa `packages/broadcast-panel/e2e/start-chrome-remote.sh`).
|
|
- Ejecutar el script:
|
|
|
|
```bash
|
|
REMOTE_DEBUG_ADDRESS=127.0.0.1 REMOTE_DEBUG_PORT=9222 \
|
|
TOKEN_SERVER="http://localhost:3000" \
|
|
ROOM="mi-room-e2e" \
|
|
BROADCAST_BASE="https://mi-dominio" \
|
|
node packages/broadcast-panel/e2e/generate_visual_baseline.js
|
|
```
|
|
|
|
Artefactos generados por el E2E script
|
|
- Logs: `packages/broadcast-panel/e2e/e2e/out/generate_visual_baseline.log` (o `e2e/out/...` en la raíz del repo)
|
|
- Captura: `packages/broadcast-panel/e2e/e2e/out/visual_<timestamp>/studio.png`
|
|
- Baseline: `packages/broadcast-panel/e2e/e2e/baseline/studio.png`
|
|
|
|
Depuración rápida
|
|
- Si `POST /api/session` devuelve 500: revisa `LIVEKIT_API_KEY`/`LIVEKIT_API_SECRET` en el entorno del backend.
|
|
- Si `studioUrl` es vacío: exporta `STUDIO_BASE` antes de hacer POST.
|
|
- Si la página no reacciona al `postMessage`: revisa el listener `window.addEventListener('message', ...)` en el frontend.
|
|
|
|
Siguientes pasos recomendados
|
|
- Reemplazar el store en memoria por Redis para persistencia en entornos multi-instanacia.
|
|
- Añadir autenticación y control de acceso para la creación/consulta de sesiones.
|
|
|
|
Si quieres, puedo:
|
|
- Añadir un mock token server con `tools/mock-token-server.js` para pruebas locales sin credenciales reales.
|
|
- Añadir un endpoint para listar sesiones (solo para debugging).
|
|
|
|
---
|
|
**Fin del README de `app/api/session`**
|
|
|