# Proxy a mano

Con `@neurologyca/capture-server`, el proxy son unas pocas líneas: [Tu backend](/docs/es/sdk/backend/). Esta página es para un backend sin él: tu página obtiene un token de tu backend (`getToken`) y tu proxy reenvía las 13 rutas.

## Por qué un proxy en tu origen

El SDK de navegador nunca llama directamente a Engine: llama a una ruta de **tu** origen (`/engine` por defecto) y tu servidor reenvía la petición.

- Engine solo acepta navegadores desde los orígenes que configura Neurologyca. Un proxy en tu origen no depende de esa lista.
- Tu servidor decide qué rutas puede alcanzar el navegador, y para qué usuarios.
- El token viaja por una sola vía: de tu endpoint de token a la página, y de la página a tu proxy.

## Reenviar el token, o inyectarlo

El SDK pide un token a tu endpoint de token y lo envía como `Authorization: Bearer …` en cada petición. El proxy recomendado **reenvía** esa cabecera, con una lista blanca de rutas. Es lo que hacen los dos ejemplos de abajo.

La alternativa es **inyectar** el token en el proxy: tu endpoint de token devuelve un valor opaco de tu propia sesión, y el proxy lo comprueba y lo sustituye por el token real. El SDK no lee el token, así que funciona igual; el token de Engine nunca llega entonces al navegador.

En los dos casos, cerrar rutas reduce lo que puede hacer una página, pero no es una frontera de seguridad: un token en el navegador se puede usar directamente contra Engine. Quién puede capturar qué lo decide tu backend.

## Las 13 rutas

Son todas las rutas que llama el SDK. `{up}` es el `userProtocolId`, `{pm}` el `protocolMechanicId` y `{externalId}` el id del usuario.

| # | Método | Ruta | Para qué |
| --- | --- | --- | --- |
| 1 | GET | `/user-protocols/{up}` | Estado: siguiente posición, progreso, aviso de baseline, disponibilidad |
| 2 | GET | `/user-protocols/{up}/mechanics/{pm}` | El plan de steps de la posición |
| 3 | GET | `/user-protocols/{up}/{pm}/sessions` | Intentos anteriores; se sondea cada 3 segundos al cerrar |
| 4 | GET | `/users/{externalId}/baseline` | Solo con `getBaselineInfo()` |
| 5 | POST | `/users/{externalId}/baseline` | Solo con `captureBaseline()` |
| 6 | GET | `/stream/{up}` | Eventos en vivo, durante toda la sesión; se reabre si se corta |
| 7 | POST | `/user-protocols/{up}/{pm}/context` | La taxonomía, una vez, antes del primer frame |
| 8 | PATCH | `/user-protocols/{up}/{pm}/query` | Solo si configuras `query` |
| 9 | POST | `/process-kpn-emo` | Cada lote y el `Final` de cada step |
| 10 | GET | `/results/{up}/{pm}` | Al cerrar la posición, y `retrieveResults()` |
| 11 | POST | `/analyze/stream` | La interpretación, como stream con progreso por fases; el SDK solo lo abre con `interpretation: 'stream'` (desde 0.38.0) |
| 12 | POST | `/analyze` | La interpretación, como recuperación, y `client.analyze()` |
| 13 | POST | `/user-protocols/{up}/{pm}/cancel` | `abort()` antes del último `Final`; libera la posición. Desde 0.29.0, una grabación o un replay añade `?captureId=` para cancelar solo su propia captura: deja que esa query llegue a Engine (los dos ejemplos de abajo la reenvían) |

En nuestra prueba, una captura en vivo usó 8 de ellas: 1, 2, 3, 6, 7, 9, 10 y 11. Las demás dependen de las opciones y de lo que pase.

## Rutas que no debes abrir

Estas las llama tu backend con tu API key, nunca el navegador: `POST /token`, `/users` (crear, listar, actualizar o borrar personas), `POST /user-protocols` (inscribir), `/catalog/*` y todo lo que no esté en la tabla. Lo que quede fuera de las 13 rutas debe responder `404`.

## Cabeceras

- **Hacia Engine:** `Authorization`, `Content-Type`, `Accept` y `X-Correlation-Id`. El SDK solo envía `X-Correlation-Id` con `/analyze` y `/analyze/stream`.
- **De vuelta al navegador:** `Content-Type`, `Cache-Control`, `X-Correlation-Id` (solo si Engine la envía), `WWW-Authenticate` (un `401` llega con el cuerpo vacío; esta cabecera es la única pista) y `Retry-After` (la espera de un `429` o de un `202 ANALYSIS_IN_PROGRESS`; sin ella, el SDK usa la suya por defecto). Engine no devuelve `X-Correlation-Id` hoy (medido), así que no cuentes con ella para soporte: usa la que envió tu SDK.
- **Tamaño del cuerpo:** desde el SDK 0.34.0 un lote en vivo lleva como mucho 300 frames y como mucho 3 MB de frames, el `Final` incluido. Con la cámara, un frame ocupa unos 19,7 KB de JSON desde 0.35.0, así que un lote de 3 MB lleva unos 150 frames. Admite al menos 4,5 MB. Un SDK anterior a 0.34.0 corta solo por número, hasta unos 9,3 MB por lote: delante de él, admite al menos 10 MB (el ejemplo de abajo admite 10 MiB, como la pasarela de DevLab).
- **Funciones serverless:** una API route del Pages Router de Next.js (`pages/api`) limita el cuerpo a 1 MB por defecto, por debajo de un lote, así que responde `413` hasta que subas su límite; un route handler del App Router (`app/…/route.js`) no tiene lector de cuerpo, así que el proxy ahí solo aplica su `maxBodyBytes` y el tope de tu hosting. Una función de Vercel lo limita a 4,5 MB: basta para el SDK actual, no para uno anterior a 0.34.0. Un `413` es definitivo al primer intento (`E_UPLOAD_FAILED`). El proxy además mantiene abierto el flujo de eventos durante toda la captura, así que mejor un runtime de larga vida (un contenedor, un VPS, Cloud Run). Detrás de Firebase Hosting (un rewrite a Cloud Run o Cloud Functions), cada petición se corta a los 60 s y solo pasa la cookie `__session`: sirve la página y el proxy en el mismo origen, fuera de Hosting; un proxy en otro origen necesita `credentials: 'include'` en el cliente ([Un proxy en otro origen](#un-proxy-en-otro-origen); [la trampa](/docs/es/resources/pitfalls/#pf-firebase-hosting-rewrite)).
- **`reAnalyze`:** quítalo de los cuerpos de `/analyze` y `/analyze/stream`, para que una página no pueda forzar una interpretación nueva. Es higiene, no protección.
- **Reloj:** el SDK lee la cabecera `Date` para saber cuándo está disponible una posición. Mantén sincronizado el reloj de tu servidor.

Si tu página y tu proxy están en orígenes distintos, envía también `Access-Control-Expose-Headers: X-Correlation-Id, Retry-After` y permite `authorization, content-type, x-correlation-id`. Sin `Retry-After` expuesta, la página no puede leer la espera de un `429` ni de un `202 ANALYSIS_IN_PROGRESS` y usa la suya por defecto (`createEngineProxy` de `capture-server` la expone desde la 0.20.1).

## Un proxy en otro origen

Lo mejor: la página y el proxy en el mismo origen (un rewrite, o el proxy bajo tu propio dominio); entonces no hace falta nada de lo que sigue. Cuando el proxy vive en otro origen y decide por tu cookie de sesión (`createEngineProxy` con `authorize`), hacen falta dos mitades, desde `@neurologyca/capture` 0.45.0:

- **En la página:** `credentials: 'include'` en `createProtocolClient` y `createRecordingClient` (también en `urlTokenProvider(url, { credentials: 'include' })` si tu endpoint de token está en ese origen; `uploadRecording` conserva su propio `credentials`). Vale para todas las peticiones del cliente al proxy, incluidos el flujo de eventos y la interpretación en stream. Sin ella, se aplica la del navegador (`'same-origin'`) y la cookie no viaja: `authorize` no ve sesión y el proxy responde `403`. Cualquier otro valor lanza `E_UNKNOWN_OPTION` al crear el cliente. Con `'include'`, el aviso `token.missing` ya no sale con un `baseUrl` absoluto en otro origen.
- **En el proxy:** `cors: { origins: ['https://app.ejemplo.com'], credentials: true }`: tu origen exacto (nunca `"*"` ni `"null"`) y `access-control-allow-credentials: true`. Usa `capture-server` 0.20.1 o posterior, que además expone `Retry-After` a esa página.
- **La cookie:** el navegador solo envía las cookies válidas para el host del proxy. En un subdominio del mismo sitio (la página en `app.ejemplo.com`, el proxy en `api.ejemplo.com`), dale un `Domain` que cubra los dos (`Domain=ejemplo.com`); basta con `SameSite=Lax`. En otro sitio (por ejemplo, una dirección `*.run.app`) es una cookie de terceros (`SameSite=None; Secure`), que Safari (también en iOS) bloquea por defecto, y otros navegadores en modo privado: ahí, sirve el proxy bajo tu propio dominio.
- **Sin `getToken`** detrás de un proxy que pone su propio token: desde otro origen, la cabecera `authorization` no pasa el preflight del proxy.

Solo viaja la sesión de tu sitio: la key y el token de Engine se quedan en tu servidor.

## Server-Sent Events

`/stream/{up}` y `/analyze/stream` son streams de eventos. El proxy tiene que pasar cada evento en cuanto llega:

- sin buffering (`proxy_buffering off` en nginx; en Node, encauza el cuerpo, nunca lo leas entero);
- sin middleware de compresión sobre `text/event-stream`;
- sin timeout total en los dos streams. `/stream/{up}` envía un `: ping` cada 30 segundos; `/analyze/stream` puede quedarse callado cerca de un minuto antes de su primer evento.

## Ejemplo: Node con Express

Express 5 y Node 18 o posterior. Móntalo con `app.use('/engine', engineProxy())`, detrás de tu propia autenticación:

```js
// Express 5. Mount it with app.use('/engine', engineProxy()). Put your own authentication in front.
import express from 'express'

const ENGINE = process.env.ENGINE_BASE
const ID = '[0-9a-fA-F-]{36}'
const USER = '[^/]+'
// The 13 routes the browser SDK calls, by method. Everything else answers 404.
const ROUTES = [
  ['GET', `/user-protocols/${ID}`],
  ['GET', `/user-protocols/${ID}/mechanics/${ID}`],
  ['GET', `/user-protocols/${ID}/${ID}/sessions`],
  ['GET', `/users/${USER}/baseline`],
  ['POST', `/users/${USER}/baseline`],
  ['GET', `/stream/${ID}`],
  ['POST', `/user-protocols/${ID}/${ID}/context`],
  ['PATCH', `/user-protocols/${ID}/${ID}/query`],
  ['POST', '/process-kpn-emo'],
  ['GET', `/results/${ID}/${ID}`],
  ['POST', '/analyze/stream'],
  ['POST', '/analyze'],
  ['POST', `/user-protocols/${ID}/${ID}/cancel`],
].map(([method, path]) => ({ method, re: new RegExp(`^${path}$`) }))
const allowed = (method, path) => ROUTES.some((r) => r.method === method && r.re.test(path))
const isStream = (path) => path === '/analyze/stream' || path.startsWith('/stream/')

export function engineProxy({ engine = ENGINE, timeoutMs = 300_000 } = {}) {
  const router = express.Router()
  router.use(express.raw({ type: '*/*', limit: '10mb' }))
  router.use(async (req, res) => {
    const path = req.path
    if (!allowed(req.method, path)) return res.status(404).json({ error: 'route not allowed' })
    let body = ['GET', 'HEAD'].includes(req.method) ? undefined : req.body
    if (path === '/analyze' || path === '/analyze/stream') {
      // The browser must not force a new interpretation: drop reAnalyze.
      try {
        const { re_analyze, reAnalyze, ...safe } = JSON.parse(body.toString('utf8'))
        body = JSON.stringify(safe)
      } catch { return res.status(400).json({ error: 'invalid JSON' }) }
    }
    const ctrl = new AbortController()
    const timer = isStream(path) ? null : setTimeout(() => ctrl.abort(), timeoutMs)
    res.on('close', () => ctrl.abort())
    try {
      const headers = { authorization: req.get('authorization') ?? '', accept: req.get('accept') ?? '*/*' }
      if (body !== undefined) headers['content-type'] = req.get('content-type') ?? 'application/json'
      if (req.get('x-correlation-id')) headers['x-correlation-id'] = req.get('x-correlation-id')
      const query = req.originalUrl.includes('?') ? req.originalUrl.slice(req.originalUrl.indexOf('?')) : ''
      const r = await fetch(`${engine}${path}${query}`, { method: req.method, headers, body, signal: ctrl.signal })
      res.status(r.status)
      for (const k of ['content-type', 'cache-control', 'x-correlation-id', 'www-authenticate', 'retry-after']) {
        const v = r.headers.get(k)
        if (v) res.setHeader(k, v)
      }
      if (isStream(path)) res.flushHeaders() // Server-Sent Events: no buffering
      if (r.body) for await (const chunk of r.body) res.write(chunk)
      res.end()
    } catch {
      if (!res.headersSent) res.status(502).json({ error: 'engine unreachable' })
      else res.end()
    } finally {
      if (timer) clearTimeout(timer)
    }
  })
  // A batch over 10 MB answers 413 instead of an HTML error page.
  router.use((err, _req, res, next) => (err?.type === 'entity.too.large' ? res.status(413).json({ error: 'body too large' }) : next(err)))
  return router
}
```

El código responde `404` fuera de las 13 rutas, quita `reAnalyze`, reenvía `X-Correlation-Id` hacia Engine y de vuelta solo si Engine la devuelve (hoy no lo hace), pasa los streams de eventos sin buffering y responde `413` por encima de 10 MB.

## Ejemplo: nginx

nginx reenvía las 13 rutas con las mismas reglas. Sustituye `<engine host>` por el host de la URL base de Engine que te da Neurologyca:

```nginx
# http { } level: the 13 routes the browser SDK calls, by method.
map "$request_method $uri" $engine_route_ok {
  default 0;
  "~^GET /engine/user-protocols/[0-9a-fA-F-]{36}$"                                    1;
  "~^GET /engine/user-protocols/[0-9a-fA-F-]{36}/mechanics/[0-9a-fA-F-]{36}$"         1;
  "~^GET /engine/user-protocols/[0-9a-fA-F-]{36}/[0-9a-fA-F-]{36}/sessions$"          1;
  "~^(GET|POST) /engine/users/[^/]+/baseline$"                                        1;
  "~^GET /engine/stream/[0-9a-fA-F-]{36}$"                                             1;
  "~^POST /engine/user-protocols/[0-9a-fA-F-]{36}/[0-9a-fA-F-]{36}/(context|cancel)$"  1;
  "~^PATCH /engine/user-protocols/[0-9a-fA-F-]{36}/[0-9a-fA-F-]{36}/query$"           1;
  "~^POST /engine/process-kpn-emo$"                                                    1;
  "~^GET /engine/results/[0-9a-fA-F-]{36}/[0-9a-fA-F-]{36}$"                           1;
  "~^POST /engine/analyze(/stream)?$"                                                  1;
}

# server { } level
location /engine/ {
  if ($engine_route_ok = 0) { return 404; }
  proxy_pass https://<engine host>/;
  proxy_set_header Host <engine host>;
  proxy_ssl_server_name on;
  proxy_http_version 1.1;
  proxy_set_header Connection "";
  proxy_buffering off;          # /stream and /analyze/stream are Server-Sent Events
  client_max_body_size 10m;     # batches of frames are large
  proxy_read_timeout 300s;
  proxy_send_timeout 300s;
}
```

nginx sin scripting no puede quitar `reAnalyze` de un cuerpo: si lo necesitas, pon un pequeño manejador delante de `/analyze` y `/analyze/stream`.

## Comprueba que no falta nada

Haz una captura con la pestaña de red del navegador abierta:

- cada petición a `/engine/…` responde `2xx` (o el `401` de un token caducado, que el SDK renueva una vez);
- un `404` con el cuerpo propio de tu proxy (`route not allowed` en el ejemplo de Express) significa que está cerrada una ruta que el SDK necesita;
- los dos streams de eventos muestran eventos que llegan durante la captura, no todos al final.

Los timeouts de cada capa están en [Timeouts](/docs/es/guides/timeouts/).
