Guía de la versión preliminar · 0.1.0
Eventos, reproducción y reconexión
Trata los flujos de eventos como avisos acotados y contrasta el estado REST autoritativo.
La referencia de la API está en inglés.
El flujo informa de posibles cambios en recursos autoritativos. No entrega hallazgos completos, controla la vida de un trabajo ni sustituye comprobaciones de revisión. El registro duradero de la base sigue estableciendo lo ocurrido.
Confirma el cambio antes de anunciarlo
- Conecta el cliente admitido
El navegador usa sesión; el IDE necesita event:read para su generación activa. Ni credenciales ni cursor van en parámetros de consulta.
- Recibe un aviso acotado
project.changed, scan.changed, job.changed y findings.changed señalan recursos cambiados. Keepalive solo indica actividad del transporte.
- Lee el recurso
Recarga proyecto, análisis, trabajo o páginas de hallazgos previstos y contrasta revisiones actuales.
- Reconecta con Last-Event-ID
Conserva el último ID observado y reconecta tras la espera progresiva. La reproducción es acotada.
- Reconstruye tras stream.reset
Si los eventos conservados no cubren el hueco, relee el estado sin suponer que el intervalo estaba vacío.
Los cambios de base preparan intenciones de evento acotadas en una outbox dentro de la transacción. Un despachador asigna secuencias de reproducción a intenciones confirmadas. Las notificaciones PostgreSQL despiertan al listener API, que lee filas duraderas. La notificación es una señal, no todo el historial.
La API comparte una conexión PostgreSQL LISTEN bloqueante en su proceso. Establece la suscripción antes de la lectura inicial para cerrar la carrera entre escucha y consulta. Los flujos leen la outbox y envían eventos del servidor a clientes autorizados. Si se pierde una señal o la vista es antigua, sigue siendo necesaria la reconciliación de recursos.
Consulta despacho de outbox y lectura de flujos.
Abre un flujo con permisos actuales
GET /v1/events devuelve text/event-stream. El navegador usa su sesión; el IDE necesita event:read para su generación activa exacta. No se admiten parámetros de consulta URL. Usa Last-Event-ID para reproducción, con secuencia decimal no negativa dentro del rango admitido.
La implementación limita cada proceso API a 32 flujos totales y cuatro por sujeto. Es un límite local de seguridad, no una cuota distribuida entre instancias escaladas. Superarlo devuelve 429; un listener no disponible, 503. Crear más flujos no recupera ninguna condición.
Los permisos IDE se comprueban contra la ranura duradera de capacidad y su generación antes de emitir tramas, incluidos keepalives. La revocación cierra el flujo sin exponer credenciales en un evento especial; reconectar con permisos revocados se rechaza.
Lee eventos de protocolo y dominio
| Evento | Significado y respuesta del cliente |
|---|---|
stream.ready |
Informa del esquema y de los ID de evento máximo actual y más antiguo. Contrasta el estado inicial de recursos. |
stream.reset |
El cursor no puede reproducirse con seguridad. Reconstruye el estado REST pertinente antes de reconectar. |
project.changed, scan.changed, job.changed, findings.changed |
Avisos acotados de cambios. Recarga recurso o colección conservando comprobaciones de revisión. |
ide.source.open |
Comando pendiente dirigido a la generación IDE autorizada exacta para abrir código. No es difusión general ni carga reproducible de hallazgos. |
Los eventos de dominio tienen ID de secuencia. Tramas de protocolo y comandos de código dirigidos no se convierten en entradas ordinarias de reproducción. La entrega dirigida se retiene si varios flujos vivos hacen ambiguo el destinatario; abrir más ventanas no debe elegir uno arbitrario.
Los documentos de evento se limitan a 4 KiB. El código emite un comentario keepalive cada 15 segundos de espera. No avanza la reproducción ni prueba que terminara un análisis. Consulta emisión y permisos.
Reconecta y restablece
La primera suscripción sin cursor empieza en la secuencia máxima actual. No reproduce todos los eventos anteriores; el cliente necesita una vista REST inicial. Al reconectar, conserva el último ID de dominio observado y envíalo por el header tras una espera progresiva.
La reproducción se limita a 256 eventos. La outbox retiene hasta 50.000 eventos despachados y 24 horas; ninguno garantiza que un cursor siga disponible. El flujo devuelve un reset y se cierra en estos casos:
| Razón | Por qué no puede continuar |
|---|---|
cursor_ahead |
La secuencia supera el máximo actual. |
cursor_expired |
Ya no se conservan los eventos anteriores necesarios. |
backlog_too_large |
Lo pendiente supera el lote acotado. |
Tras reset, reconstruye proyecto y análisis seleccionados, trabajos activos y páginas de hallazgos con REST actual; establece luego una base nueva del flujo. Repite la reconciliación tras perder conexión o cambiar permisos. No interpretes un hueco como resultado vacío, conserves un cursor obsoleto ni marques silenciosamente un trabajo como terminado.
La outbox sincroniza de forma acotada; no es un registro de auditoría indefinido ni garantiza una acción cliente exactamente una vez. La referencia del flujo sigue ligada a su snapshot API; la implementación enlazada explica el comportamiento revisado actual. Este sitio no abre conexiones de eventos.