101 lines
4.2 KiB
ReStructuredText
101 lines
4.2 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, ``dispatcher.timeout_seconds`` (300 s par défaut)
|
|
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 ``dispatcher.timeout_seconds`` ; au-delà, la ressource passe
|
|
en ``error``. Le refus en 422 ne vaut que pour un parent absent, en ``error`` ou en ``deleting``.
|
|
|
|
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 non supprimées
|
|
qui l'utilisent encore
|
|
* - ``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`.
|