Flux d'état

Utilisez GET /v1/events/conditions quand un client authentifié du plan de contrôle a besoin des changements de condition entre deux actualisations d’instantanés d’état. Le flux est une optimisation par-dessus les lectures d’instantanés, et non leur remplacement.

Se connecter

curl --no-buffer --fail-with-body \
  -H "Authorization: Bearer $THALOVANT_TOKEN" \
  -H "Accept: text/event-stream" \
  https://api.thalovant.com/v1/events/conditions

Le point de terminaison accepte les filtres uids, kinds, namespaces, statuses, reasons et types, séparés par des virgules. L’appelant a besoin d’au moins une portée de lecture prise en charge pour les hubs, les clients ou les ACL.

Chaque événement de condition conserve les champs de condition existants et ajoute une enveloppe de flux ordonnée :

id: 1842
event: condition
data: {"version":1,"sequence":1842,"event_type":"upsert","resource":{"kind":"Hub","uid":"hub-uid","name":"primary","namespace":"tenant-a"},"resource_kind":"Hub","resource_uid":"hub-uid","type":"Ready","status":"True"}

Champ	Signification
id SSE	Un numéro d’événement ordonné, encodé en chaîne décimale.
version	Version de l’enveloppe publique des événements d’état. La version actuelle est 1.
sequence	La même valeur numérique que l’id SSE.
event_type	upsert pour une observation, ou delete pour l’observation d’une suppression durable.
resource	Le type (kind) et l’UID stables, plus le nom et l’espace de noms observés.
Champs de condition existants	La charge utile rétrocompatible utilisée par les clients plus anciens.

Reprendre sans risque

1. Stockez la dernière séquence numérique entièrement traitée. Enregistrez-la seulement après que votre gestionnaire a accepté l’événement.
2. Reconnectez-vous avec le curseur. Envoyez Last-Event-ID: 1842, ou utilisez ?last_event_id=1842 quand le client de flux ne peut pas définir cet en-tête.
3. Traitez les événements dans l’ordre croissant des séquences. Ignorez toute séquence égale ou inférieure à la dernière valeur traitée.
4. Actualisez un instantané d’état après la réinitialisation du curseur. Reconnectez-vous sans le curseur refusé seulement après avoir lancé la récupération par instantané.

La relecture se fait dans l’ordre et se limite à 1 000 événements. L’API renvoie 409 avec detail.code: status_cursor_expired quand la récupération dépasserait cette fenêtre. Un curseur en avance sur le flux enregistré renvoie 409 avec detail.code: invalid_status_cursor. Ces échecs sont explicites pour qu’un client ne saute jamais d’état en silence.

Note

Pendant la migration, un ancien curseur non numérique est accepté en mode direct seulement. Il ne permet pas de relecture durable. Passez à la séquence numérique de la version 1 dès que la réponse inclut X-Thalovant-Status-Stream-Version: 1.

Les SDK officiels Python, Node, Go et Rust n’encapsulent pas encore ce point de terminaison SSE du plan de contrôle. Utilisez un client de flux HTTP qui prend en charge l’autorisation bearer, le découpage SSE, l’annulation de la reconnexion et un délai d’attente croissant et plafonné (backoff).

Règles de livraison

• Un événement relu garde son numéro de séquence d’origine; ignorez les événements que vous avez déjà traités.
• Les signaux de vie (heartbeats) sont des commentaires SSE et ne font pas avancer le curseur.
• Reconnectez-vous avec le dernier curseur traité pour demander les événements manqués.
• Les lectures périodiques d’instantanés restent le chemin de récupération en cas de curseur refusé, de longue période hors ligne ou d’échec d’analyse du côté client.