Guide de la version préliminaire · 0.1.0
Événements, rejeu et reconnexion
Traitez les streams comme des indications bornées et réconciliez l’état REST faisant autorité.
La référence de l’API est en anglais.
Le stream indique aux clients que des ressources faisant autorité ont peut-être changé. Il ne livre pas de constats complets, ne possède pas la vie d’un job et ne remplace pas les vérifications de révision. L’enregistrement durable reste la référence pour établir ce qui s’est passé.
Valider la modification avant de l’annoncer
- Connecter le client admis
Le navigateur utilise sa session ; l’IDE exige event:read pour sa génération active. Secrets et curseur de rejeu n’ont pas leur place dans les paramètres d’URL.
- Recevoir une indication bornée
project.changed, scan.changed, job.changed et findings.changed désignent des ressources modifiées. Les commentaires keepalive indiquent seulement l’activité du transport.
- Lire la ressource
Actualisez projet, analyse, job ou pages prévus et réconciliez leurs révisions actuelles.
- Reconnecter avec Last-Event-ID
Conservez le dernier identifiant observé et reconnectez après temporisation. Le rejeu est borné.
- Reconstruire après stream.reset
Si les événements conservés ne comblent pas le trou, relisez l’état actuel plutôt que de supposer un intervalle vide.
Les modifications placent des intentions d’événement bornées dans une outbox au sein de la transaction. Un répartiteur attribue des séquences de rejeu aux intentions validées. Les notifications PostgreSQL réveillent l’écouteur API, qui lit ensuite les lignes durables. Une notification est un réveil, pas l’historique complet.
L’API partage une connexion PostgreSQL LISTEN bloquante dans son processus. Elle établit l’abonnement avant la lecture initiale pour fermer la course écoute/requête. Les streams lisent l’outbox et envoient des server-sent events aux clients autorisés. Un réveil manqué ou une vue ancienne exige toujours une réconciliation des ressources.
Voir répartition de l’outbox et lectures.
Ouvrir un stream avec des droits actuels
GET /v1/events retourne text/event-stream. Le navigateur utilise sa session ; l’IDE exige event:read pour sa génération active exacte. Aucun paramètre de requête URL n’est accepté. Utilisez l’en-tête Last-Event-ID pour le rejeu, avec une séquence décimale non négative dans la plage admise.
La limite est de 32 streams au total et quatre par sujet dans chaque processus API. C’est une borne locale au processus, pas un quota distribué entre instances indépendantes. La dépasser retourne 429 ; un écouteur indisponible retourne 503. Créer plus de streams ne récupère aucune de ces situations.
Les droits IDE sont vérifiés contre l’emplacement durable de capacité et sa génération avant émission des trames, y compris les keepalives. La révocation ferme le stream sans exposer de secrets dans un événement spécial ; la reconnexion avec des droits révoqués est refusée.
Lire les événements de protocole et de domaine
| Événement | Signification et réaction du client |
|---|---|
stream.ready |
Indique schéma et identifiants courants maximal et le plus ancien. Réconcilier l’état initial. |
stream.reset |
Le curseur fourni ne peut être rejoué sans risque. Reconstruire l’état REST pertinent avant reconnexion. |
project.changed, scan.changed, job.changed, findings.changed |
Indications bornées de changement. Actualiser la ressource ou collection concernée en préservant les révisions. |
ide.source.open |
Commande ciblée en attente pour la génération IDE exacte autorisée. Ce n’est ni une diffusion générale ni une charge de constat rejouable. |
Les événements de domaine ont des séquences. Les trames de protocole et commandes de sources ciblées ne deviennent pas des entrées ordinaires de rejeu. La livraison ciblée est retenue si plusieurs streams actifs rendent le destinataire ambigu ; ouvrir plus de fenêtres ne doit pas choisir un destinataire arbitraire.
Les documents sont limités à 4 KiB. Un commentaire keepalive est émis toutes les 15 secondes d’attente. Il n’avance pas le rejeu et ne prouve pas la fin d’une analyse. Voir émission et contrôles d’autorisation.
Reconnecter et réinitialiser
Un premier abonnement sans curseur commence au niveau maximal actuel. Il ne rejoue pas tous les événements antérieurs ; une vue REST initiale reste nécessaire. À la reconnexion, conservez le dernier identifiant de domaine observé et envoyez-le dans l’en-tête après temporisation.
Le rejeu est borné à 256 événements. L’outbox conserve au plus 50 000 événements distribués et 24 heures ; aucune borne ne garantit donc la disponibilité d’un curseur. Le stream émet une réinitialisation puis ferme dans ces cas :
| Raison | Pourquoi le rejeu ne continue pas |
|---|---|
cursor_ahead |
La séquence dépasse le maximum actuel. |
cursor_expired |
Les événements antérieurs nécessaires ne sont plus conservés. |
backlog_too_large |
Le rejeu en attente dépasse le lot borné. |
Après reset, reconstruisez projet/analyse choisi, jobs actifs et pages pertinentes depuis REST actuel, puis établissez une nouvelle base de stream. Réconciliez à nouveau après perte de connexion ou changement de droits. Un trou n’est pas un résultat vide : ne gardez pas un curseur périmé et ne terminez pas silencieusement un job.
L’outbox est un mécanisme de synchronisation borné, pas un audit illimité ni une garantie d’action client exactement une fois. La référence du stream reste liée à son instantané publié ; l’implémentation liée explique le comportement actuel examiné. Ce site n’ouvre aucune connexion d’événements.