Proxy a mano
Las 13 rutas que llama el SDK de navegador, reenviadas a Engine por un proxy propio (Express o nginx), para cuando no usas capture-server.
Con @neurologyca/capture-server, el proxy son unas pocas líneas: Tu 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
Sección titulada «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
Sección titulada «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
Sección titulada «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
Sección titulada «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
Sección titulada «Cabeceras»- Hacia Engine:
Authorization,Content-Type,AcceptyX-Correlation-Id. El SDK solo envíaX-Correlation-Idcon/analyzey/analyze/stream. - De vuelta al navegador:
Content-Type,Cache-Control,X-Correlation-Id(solo si Engine la envía),WWW-Authenticate(un401llega con el cuerpo vacío; esta cabecera es la única pista) yRetry-After(la espera de un429o de un202 ANALYSIS_IN_PROGRESS; sin ella, el SDK usa la suya por defecto). Engine no devuelveX-Correlation-Idhoy (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
Finalincluido. 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 responde413hasta 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 sumaxBodyBytesy 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. Un413es 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 necesitacredentials: 'include'en el cliente (Un proxy en otro origen; la trampa). reAnalyze: quítalo de los cuerpos de/analyzey/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
Datepara 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
Sección titulada «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'encreateProtocolClientycreateRecordingClient(también enurlTokenProvider(url, { credentials: 'include' })si tu endpoint de token está en ese origen;uploadRecordingconserva su propiocredentials). 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:authorizeno ve sesión y el proxy responde403. Cualquier otro valor lanzaE_UNKNOWN_OPTIONal crear el cliente. Con'include', el avisotoken.missingya no sale con unbaseUrlabsoluto en otro origen. - En el proxy:
cors: { origins: ['https://app.ejemplo.com'], credentials: true }: tu origen exacto (nunca"*"ni"null") yaccess-control-allow-credentials: true. Usacapture-server0.20.1 o posterior, que además exponeRetry-Aftera 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 enapi.ejemplo.com), dale unDomainque cubra los dos (Domain=ejemplo.com); basta conSameSite=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
getTokendetrás de un proxy que pone su propio token: desde otro origen, la cabeceraauthorizationno 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
Sección titulada «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 offen 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: pingcada 30 segundos;/analyze/streampuede quedarse callado cerca de un minuto antes de su primer evento.
Ejemplo: Node con Express
Sección titulada «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:
// Express 5. Mount it with app.use('/engine', engineProxy()). Put your own authentication in front.import express from 'express'
const ENGINE = process.env.ENGINE_BASEconst 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
Sección titulada «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:
# 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 { } levellocation /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
Sección titulada «Comprueba que no falta nada»Haz una captura con la pestaña de red del navegador abierta:
- cada petición a
/engine/…responde2xx(o el401de un token caducado, que el SDK renueva una vez); - un
404con el cuerpo propio de tu proxy (route not alloweden 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.