Guida alla versione preliminare · 0.1.0
Eventi, replay e riconnessione
Tratta gli stream di eventi come segnali limitati e riconcilia lo stato REST autorevole.
Il riferimento API è in inglese.
Lo stream segnala possibili cambiamenti alle risorse autorevoli. Non consegna rilievi completi, non governa la vita di un job e non sostituisce controlli di revisione. Il record persistente del database resta il punto in cui accertare l’accaduto.
Conferma il cambiamento prima di annunciarlo
- Connetti il client ammesso
Il browser usa la sessione; l’IDE richiede event:read per la generazione attiva. Credenziali e cursore non vanno nei parametri query.
- Ricevi un segnale limitato
project.changed, scan.changed, job.changed e findings.changed indicano risorse cambiate. Keepalive indica solo attività di trasporto.
- Leggi la risorsa
Aggiorna progetto, scansione, job o pagine dei rilievi previsti e riconcilia le revisioni correnti.
- Riconnetti con Last-Event-ID
Conserva l’ultimo ID osservato e riconnetti dopo il backoff. Il replay è limitato.
- Ricostruisci dopo stream.reset
Se gli eventi conservati non coprono la lacuna, rileggi lo stato senza presumere che l’intervallo fosse vuoto.
Le modifiche database preparano intenzioni di evento limitate in una outbox nella transazione. Un dispatcher assegna sequenze di replay alle intenzioni confermate. Le notifiche PostgreSQL svegliano il listener API, che legge righe persistenti. La notifica è un segnale, non tutta la cronologia.
L’API condivide una connessione PostgreSQL LISTEN bloccante nel processo. Sottoscrive prima della lettura iniziale per chiudere la corsa tra ascolto e query. Gli stream leggono l’outbox e inviano eventi server ai client autorizzati. Se manca un risveglio o la vista è vecchia, serve comunque la riconciliazione delle risorse.
Consulta dispatch dell’outbox e letture degli stream.
Apri uno stream con autorità corrente
GET /v1/events restituisce text/event-stream. Il browser usa la sessione; l’IDE richiede event:read per la generazione attiva esatta. Non sono ammessi parametri query URL. Usa Last-Event-ID per il replay, con sequenza decimale non negativa nell’intervallo supportato.
Ogni processo API ammette 32 stream totali e quattro per soggetto. È un limite locale di sicurezza, non una quota distribuita tra istanze scalate. Superarlo restituisce 429; un listener indisponibile restituisce 503. Aprire altri stream non risolve nessuna delle due condizioni.
L’autorità IDE viene verificata contro slot persistente e generazione della capacità prima delle frame, inclusi keepalive. La revoca chiude lo stream senza esporre credenziali in un evento speciale; la riconnessione con autorità revocata viene rifiutata.
Leggi eventi di protocollo e dominio
| Evento | Significato e risposta del client |
|---|---|
stream.ready |
Riporta schema e ID massimo corrente e più antico. Riconcilia lo stato iniziale delle risorse. |
stream.reset |
Il cursore non è riproducibile in sicurezza. Ricostruisci lo stato REST pertinente prima di riconnettere. |
project.changed, scan.changed, job.changed, findings.changed |
Segnali limitati di modifica. Aggiorna risorsa o raccolta mantenendo i controlli di revisione. |
ide.source.open |
Comando pendente per aprire sorgenti sulla generazione IDE autorizzata esatta. Non è un broadcast o un payload di rilievi riproducibile. |
Gli eventi di dominio hanno ID di sequenza. Frame di protocollo e comandi sorgente mirati non diventano normali voci di replay. La consegna mirata viene sospesa se più stream vivi rendono ambiguo il destinatario; aprire altre finestre non deve selezionarne uno arbitrario.
I documenti evento sono limitati a 4 KiB. Il codice emette un commento keepalive ogni 15 secondi di attesa. Non avanza il replay e non prova il completamento di una scansione. Consulta emissione e controlli d’autorità.
Riconnetti e reimposta
La prima sottoscrizione senza cursore parte dalla sequenza massima attuale. Non riproduce tutti gli eventi precedenti; serve ancora una vista REST iniziale. Alla riconnessione, conserva l’ultimo ID di dominio osservato e invialo nell’header dopo il backoff.
Il replay è limitato a 256 eventi. L’outbox conserva fino a 50.000 eventi distribuiti e 24 ore; nessuno dei due limiti garantisce che un cursore resti disponibile. Lo stream restituisce un reset e si chiude nei casi seguenti:
| Motivo | Perché il replay non continua |
|---|---|
cursor_ahead |
La sequenza supera il massimo attuale. |
cursor_expired |
Gli eventi precedenti necessari non sono più conservati. |
backlog_too_large |
Il replay pendente supera il lotto limitato. |
Dopo il reset, ricostruisci progetto e scansione selezionati, job attivi e pagine dei rilievi da REST corrente, poi stabilisci una nuova base dello stream. Riconcilia ancora dopo perdita di connessione o cambio d’autorità. Non trattare una lacuna come risultato vuoto, conservare un cursore obsoleto o dichiarare silenziosamente un job completato.
L’outbox è sincronizzazione limitata, non un audit log indefinito o una garanzia di azione client esattamente una volta. Il riferimento dello stream resta legato allo snapshot API; l’implementazione collegata spiega il comportamento corrente esaminato. Questo sito non apre connessioni evento.