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, dnsmasq
     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.
* **Ne pas enchaîner sans vérifier.** Créer un subnet dont le VPC est encore en ``creating``
  échoue en 422 ; démarrer une VM sur un subnet en ``creating`` ou ``running`` est en revanche
  accepté.

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, ``iface_type`` inconnu, base64 invalide
   * - ``404``
     - ressource inexistante
   * - ``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
   * - ``422``
     - dépendance absente ou pas prête : VPC parent d'un subnet, subnet d'une VM
   * - ``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`.