two/docs/exploitation/api-agent/asynchronisme.rst
GnomeZworc edfd24f92b
f-79: doc: section times, suppressions en cascade, notes 0.3.0 #79
Signed-off-by: GnomeZworc <nicolas.boufidjeline@g3e.fr>
2026-10-25 12:42:20 +01:00

105 lines
4.5 KiB
ReStructuredText

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
----------------------------
.. mermaid::
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.
.. code-block:: bash
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
---------------
.. list-table::
:header-rows: 1
:widths: 12 88
* - 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
:doc:`/concepts/cycle-de-vie`.