Flux d'événements

Kisenon diffuse l'activité des organisations et des projets sous forme de Server-Sent Events. Ouvrez une connexion HTTP à longue durée, définissez Accept: text/event-stream, et le plan de contrôle pousse une enveloppe JSON chaque fois que quelque chose change.

La console alimente ses vues d'activité en direct à partir de ce même flux.

Endpoints

Deux routes, toutes deux en SSE :

Les deux vivent sous https://api.test.kisenon.com. La route limitée à un projet renvoie un 404 si le projet n'appartient pas à votre organisation, donc l'existence ne fuit jamais entre organisations.

Authentification

Le même identifiant Bearer que tout autre appel du plan de contrôle : une clé API (nsk_…) ou un JWT web signé par cp. Voir Authentification. L'appelant doit être membre de l'organisation ; les non-membres obtiennent un 403.

Enveloppe d'événement

Chaque événement est un objet JSON à la forme stable :

La forme de l'enveloppe ne change jamais de manière incompatible. Les nouveaux champs sont additifs, et les nouvelles variantes d'événement obtiennent un nouveau type (p. ex. un futur operation.updated.v2) plutôt que de muter un existant.

Types d'événements

Aujourd'hui, le plan de contrôle publie un type d'événement applicatif :

• operation.updated.v1 (source operations) — une opération a changé d'état de cycle de vie. data porte operation_id, action, status, et, quand la ligne est encore présente, branch_id, endpoint_id, error et initiator.

Le broker émet également trois événements de contrôle internes (source _broker) :

• resume.gap.v1 — votre Last-Event-ID est plus ancien que le tampon du broker ; des événements ont été manqués. Re-récupérez l'état complet via REST, puis continuez à streamer.
• overflow.v1 — votre client a lu trop lentement et a été abandonné ; data.dropped compte les événements perdus. Reconnectez-vous et re-récupérez l'état complet.
• error.v1 — un marqueur d'erreur côté producteur.

Les sources audit, invitations et billing sont réservées mais n'émettent pas encore d'événements ; cette liste s'allonge à mesure que ces chantiers sont livrés.

Reprise

L'id de chaque événement est son id SSE, donc un EventSource natif renvoie automatiquement le dernier sous forme d'en-tête Last-Event-ID à la reconnexion, et le broker rejoue tout ce qui a été mis en tampon après lui. Vous pouvez aussi le passer explicitement :

Last-Event-ID: 01JX5N4R8ZT2W7Q9V3B1C6D8EF

Si l'écart est plus large que l'anneau en mémoire du broker, vous recevez un resume.gap.v1 au lieu d'un rejeu. Traitez cela (et overflow.v1) comme « vous avez manqué des événements » : re-récupérez l'état affecté via l'API REST, puis reprenez le streaming à partir du dernier id.

Exemple

curl -N -H "Authorization: Bearer $KISENON_API_KEY" \
  -H "Accept: text/event-stream" \
  https://api.test.kisenon.com/v1/events

Un événement diffusé ressemble à :

id: 01JX5N4R8ZT2W7Q9V3B1C6D8EF
event: operation.updated.v1
data: {"id":"01JX5N4R8ZT2W7Q9V3B1C6D8EF","type":"operation.updated.v1","source":"operations","org_id":"6f1d2c3b-4a59-4e87-9b10-2d3e4f5a6b7c","project_id":"prj_4c1d9e2a7b3f5c8d0e1f2a3b","region_id":"home-proxmox","at":"2026-06-03T12:00:00Z","data":{"operation_id":"op_77a1","action":"create_branch","status":"finished","branch_id":"br_91c2"}}

Les lignes commençant par : (p. ex. : keepalive) sont des commentaires de heartbeat ; ignorez-les.

Dans la console

Les vues d'activité en direct de la console consomment ce même flux (relayé via l'origine de la console, puisqu'un EventSource de navigateur ne peut pas définir d'en-tête Authorization). Sur resume.gap.v1 ou overflow.v1, elle re-récupère l'état complet via REST — exactement le contrat ci-dessus. Si vous construisez votre propre consommateur, reproduisez ce comportement.

Liens connexes

• Authentification — identifiants Bearer.
• Organisations — appartenance et portée.