Modèle asynchrone et codes de retour#
Toute création et toute suppression sont asynchrones. C’est le point qui surprend le plus
souvent à l’intégration : un 202 ne dit pas que la ressource existe, il dit que la demande
a été acceptée et enregistrée.
Les deux temps d’une requête#
sequenceDiagram
participant C as Appelant
participant A as API
participant W as Worker
C->>A: POST /subnets
A->>A: Prepare — valide, écrit "creating"
A-->>C: 202 + ressource en creating
A->>W: Dispatch (file d'attente)
W->>W: Execute — netns, netif, dhcp
W->>W: état → running (ou error)
C->>A: GET /subnets/<name>
A-->>C: 200 + state
Prepare est synchrone, dans le handler HTTP : il valide l’état, écrit l’état initial en base et répond. Execute est asynchrone : il fait le travail réseau réel, puis positionne l’état final.
Conséquence directe : un échec d”Execute ne peut pas être remonté dans la réponse HTTP. Il
se lit dans l’état de la ressource, qui passe à error.
Attendre correctement#
Il n’y a pas de webhook ni de long-polling : l’appelant interroge GET /<type>/<name> jusqu’à
un état stable.
until [ "$(curl -sf http://127.0.0.1:8080/subnets/sn-000001 | jq -r .state)" = running ]; do
sleep 2
done
Trois règles pour un appelant robuste :
Toujours borner l’attente. Côté agent, la section
timesde la configuration borne les opérations qui attendent une transition ; l’appelant doit avoir sa propre borne.Traiter ``error`` comme terminal, pas comme un échec transitoire. Un
Executeen échec ne se rejoue pas tout seul.Savoir ce qui s’enchaîne. Créer un subnet dont le VPC est encore en
creating, ou démarrer une VM sur un subnet encreating, est accepté : l”Executeattend que le parent passerunning, dans la limite detimes.timeout_subnet_startoutimes.timeout_vms_start; au-delà, la ressource passe enerror. Le refus en 422 ne vaut que pour un parent absent, enerrorou endeleting. À la suppression, c’est l’inverse : une VM puis son subnet, ou un subnet puis son VPC, peuvent être supprimés d’un coup ; le parent attend que ses enfants endeletingsoient supprimés (times.timeout_subnet_stop,times.timeout_vpc_stop), et passe enerrorsi l’un d’eux échoue.
Codes de retour#
Code |
Signification |
|---|---|
|
demande acceptée et enregistrée ; l’état passera à |
|
lecture réussie ( |
|
champ obligatoire manquant, corps invalide, base64 invalide ; CIDR de VPC invalide,
|
|
ressource inexistante |
|
méthode non prise en charge ; corps |
|
conflit d’existence ou d’état : ressource déjà créée, ou suppression depuis un état qui
ne l’autorise pas ; pour un VPC, subnets encore présents, |
|
dépendance absente ou inutilisable : VPC parent d’un subnet, subnet d’une VM, absent, en
|
|
erreur interne |
Le corps d’erreur est uniforme : {"error": "…"}.
Idempotence#
Les créations ne sont pas idempotentes : recréer une ressource existante donne 409, pas 202.
Un appelant qui rejoue une requête après un timeout réseau doit donc traiter 409 comme
« déjà fait », après avoir vérifié l’état par un GET.
Les suppressions depuis l’état error sont acceptées mais best-effort : les ressources
système peuvent n’avoir été créées que partiellement, et il n’y a pas de rollback — voir
Cycle de vie des ressources.