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 times de 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 Execute en é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 en creating, est accepté : l”Execute attend que le parent passe running, dans la limite de times.timeout_subnet_start ou times.timeout_vms_start ; au-delà, la ressource passe en error. Le refus en 422 ne vaut que pour un parent absent, en error ou en deleting. À 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 en deleting soient supprimés (times.timeout_subnet_stop, times.timeout_vpc_stop), et passe en error si l’un d’eux échoue.

Codes de retour#

Code

Signification

202

demande acceptée et enregistrée ; l’état passera à running ou error

200

lecture réussie (GET)

400

champ obligatoire manquant, corps invalide, base64 invalide ; CIDR de VPC invalide, l3vni hors plage ; interface_ip absent (bridge, public_ip) ou fourni (vxlan) ; interface de VM sans mac, nombre d’interfaces primary différent de 1

404

ressource inexistante

405

méthode non prise en charge ; corps {"error": "method not allowed"}, mais servi en text/plain par /vpcs et /subnets (et leurs /{name}), en JSON par /vms

409

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, l3vni déjà utilisée par un autre VPC, ou l3vni demandée sans section bgp ; pour un subnet, VM qui l’utilisent encore, ni supprimées ni en deleting

422

dépendance absente ou inutilisable : VPC parent d’un subnet, subnet d’une VM, absent, en error ou en deleting ; mode de subnet inconnu ; CIDR vxlan invalide ou plus petit que /29 ; IP de VM hors du CIDR du subnet ou réservée

500

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.