Documentation développeur

Démarrage rapide

Créez une clé API avec les portées Rig dans le portail Ironfang, puis committez un ironfang.rig.yaml à côté de l'application. Le fichier déclare les identités externes dont une exécution a besoin et ce que l'exécution doit observer.

version: 1
project: acme-shop
suite: checkout
name: Checkout flow
defaults:
  run_ttl: 30m
resources:
  customer_email:
    type: email
  stripe_callback:
    type: callback
    connector:
      route: stripe
  shipping_api:
    type: mock_http
    rules:
      - match: { method: POST, path: /v1/ship/* }
        respond: { status: 201, json: { tracking: "IF-1" } }
expectations:
  - id: order_email
    resource: customer_email
    event: email.received
    match: { subject_contains: "Your order" }
  - id: stripe_forwarded
    resource: stripe_callback
    event: connector.request.completed
    match: { outcome: delivered, status: 200 }

Le client en ligne de commande synchronise le fichier, démarre une exécution, exporte l'adresse de chaque ressource vers la commande placée après --, l'exécute, puis termine l'exécution avec un verdict.

export IRONFANG_API_KEY=if_live_...
ironfang rig run -- npm test

# In the test process:
#   IRONFANG_RIG_RUN_ID           the run
#   IRONFANG_RIG_CUSTOMER_EMAIL   run-....@inbox.rig.ironfang.uk
#   IRONFANG_RIG_STRIPE_CALLBACK  https://hooks.rig.ironfang.uk/h/...
#   IRONFANG_RIG_SHIPPING_API     https://mock.rig.ironfang.uk/m/...

La même exécution est disponible en HTTP. Chaque requête porte la clé comme jeton bearer, et l'URL de base est https://api.ironfang.uk/rig.

curl -X POST https://api.ironfang.uk/rig/v1/suites/$SUITE_ID/runs \
  -H "Authorization: Bearer $IRONFANG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "ttl": "30m", "external_id": "ci-4821" }'

La description OpenAPI 3.1 complète est servie à https://api.ironfang.uk/rig/openapi.yaml.

Modèle

Les suites persistent, les exécutions sont jetables, les ressources ont une durée de vie explicite. Rien ici n'exécute votre code : Ironfang Rig est le monde extérieur auquel vos tests parlent, et l'enregistrement de ce qu'il a vu.

Tout est rattaché à une organisation. Un objet qui appartient à une autre organisation est signalé comme introuvable, jamais comme interdit.

Clés API et portées

Les clés API de la plateforme sont créées dans le portail et commencent par if_live_. Les portées d'une clé sont ses autorisations, et elle n'agit que dans l'organisation pour laquelle elle a été créée. Envoyez-la comme jeton bearer.

Authorization: Bearer if_live_...

• rig:readLister et lire les projets, suites, exécutions, ressources, pannes, connecteurs et événements ; attendre sur la chronologie ; exporter les preuves
• rig:writeCréer et réviser les projets et les suites
• rig:runDémarrer, terminer et annuler les exécutions ; allouer des ressources ; modifier les règles de mock ; armer des pannes ; rejouer des callbacks
• rig:connectorCréer des connecteurs et leurs jetons d'amorçage
• rig:*Tout ce qui précède

Un jeton utilisateur Warden est également accepté, avec l'organisation agissante dans X-Ironfang-Tenant ; chaque route exige alors la permission de tenant correspondante (rig.read, rig.write, rig.run, rig.connector).

Erreurs

Chaque erreur est un objet JSON avec un code stable, un message lisible par une personne et l'identifiant de requête à communiquer au support.

{
  "error": {
    "code": "run_not_active",
    "message": "the run has already ended",
    "docs": "https://ironfang.uk/rig/docs#errors"
  },
  "request_id": "01a0c375-7bae-7f02-a3d4-91e6b8c25f70"
}

docs est un lien vers cette section, et request_id reprend l'en-tête de réponse X-Ironfang-Request-ID.

Le fichier de suite

ironfang.rig.yaml se trouve dans le dépôt, à côté de l'application qu'il teste. Il contient exactement la définition que l'API stocke, si bien que ce qu'un développeur committe est ce à partir de quoi une exécution est créée. La synchronisation du fichier crée le projet et la suite à la première utilisation et enregistre une nouvelle version de la suite chaque fois que la définition change.

Spécifications de ressource

Les libellés de route respectent ^[a-z0-9][a-z0-9-]{0,62}$. La plateforme ne nomme jamais qu'un libellé ; ce vers quoi il pointe est décidé sur la ligne de commande du connecteur et ne quitte jamais votre machine.

Correspondance

Un objet match est un ensemble de conditions sur les champs de premier niveau des données d'un événement, et chaque clé doit être satisfaite. Une clé simple se compare en JSON : nombres, booléens, chaînes et objets entiers se comparent par valeur. Une clé se terminant par _contains exige que le champ soit une chaîne contenant la valeur. La même règle évalue les attendus de la suite, l'endpoint d'attente et l'option --match de la CLI, si bien qu'une condition a le même sens partout. Jusqu'à 16 clés, de 4096 caractères chacune.

Ressources

Démarrer une exécution alloue chaque ressource déclarée. Chacune est impossible à deviner, n'appartient qu'à cette exécution et cesse d'accepter toute activité quand l'exécution se termine. D'autres peuvent être allouées sur une exécution active avec POST /v1/runs/{runId}/resources.

Boîtes de réception e-mail

Une ressource email est une adresse comme run-k7c3m2wp9e4q5r6t@inbox.rig.ironfang.uk. Le courrier qui lui est destiné est reçu par mx.rig.ironfang.uk, analysé et enregistré comme email.received avec l'expéditeur, le destinataire, l'objet, les liens, les codes de vérification, les pièces jointes et les détails de transport. Le message brut est conservé comme charge utile de l'événement. Les messages jusqu'à 10 MiB et 500 messages par exécution sont acceptés ; au-delà, tout est refusé dès l'échange SMTP, de sorte que l'expéditeur voit le rejet.

Chaque message est aussi vérifié comme le ferait un serveur de messagerie destinataire : SPF pour l'adresse d'envoi par rapport au domaine de l'expéditeur d'enveloppe, DKIM pour chaque signature qu'il porte, et DMARC pour le domaine From avec l'alignement et la politique que demande son enregistrement. Les résultats sont enregistrés sur l'événement sous authentication (spf, dkim[], dmarc avec le domaine, la politique, l'alignement et les motifs) et repris sous forme des champs d'un seul mot spf, dkim et dmarc, pour qu'un attendu ou une attente puisse demander { "dmarc": "pass" }. Ce sont des observations de ce que l'expéditeur publiait au moment de la réception : une défaillance DNS vaut temperror, jamais un verdict.

URL de callback

Une ressource callback est une URL comme https://hooks.rig.ironfang.uk/h/.... Toute méthode et tout chemin sous cette URL sont acceptés. La requête est enregistrée comme callback.received avec sa méthode, son chemin, sa query, son type de contenu, sa longueur en octets et son SHA-256, et l'expéditeur reçoit immédiatement un 200 avec l'identifiant de l'événement. Les octets exacts sont disponibles via l'endpoint de charge utile de l'événement. Les corps de plus de 64 KiB sont refusés avec un 413 et enregistrés comme callback.rejected ; une exécution accepte jusqu'à 1000 callbacks.

{ "received": true, "run_id": "...", "event_id": "...", "sequence": 7 }

Avec une connector.route, chaque requête enregistrée est aussi mise en file pour cette route et transmise par votre connecteur ; voir Connecteur local.

Endpoints HTTP simulés

Une ressource mock_http est une URL de base comme https://mock.rig.ironfang.uk/m/.... Les requêtes sous cette URL reçoivent la réponse de la première règle dont le match est satisfait ; sans correspondance, la réponse est un 404 avec le code no_mock_rule. Chaque requête est enregistrée comme mock.request.received et sa réponse comme mock.response.sent avec la règle correspondante. Les règles peuvent être remplacées tant que l'exécution est active avec PUT /v1/runs/{runId}/resources/{resourceId}/mock, ce qui enregistre mock.rules.updated.

Déterministe : la même requête face aux mêmes règles, à la même étape, obtient la même réponse, délai compris. Une exécution peut faire jusqu'à 5000 appels de mock.

Un mock peut tenir lieu d'une API documentée au lieu de porter des règles : donnez à la ressource openapi.file (un chemin à côté du fichier de suite, que la CLI intègre) ou openapi.document (le texte OpenAPI 3, en JSON ou YAML, jusqu'à 256 KiB). Une règle est dérivée par opération, dans l'ordre du document : le modèle de chemin est le match, la réponse 2xx la plus basse ou la réponse par défaut est la réponse, et l'exemple documenté, ou une valeur construite à partir du schéma (enum d'abord, chaînes conformes au format, nombres à zéro, un élément de tableau), est le corps. Les références sont résolues dans le document et rien n'est téléchargé. Un mock contient au plus 32 opérations ; nommez celles dont une suite a besoin dans openapi.include sous la forme GET /pets/{id}, et définissez openapi.prefer: schema pour ignorer les exemples.

Routes de connecteur

Une connector_route n'a pas d'adresse publique. Elle existe pour qu'un connecteur puisse se lier au libellé et que des callbacks puissent le nommer. La plupart des suites déclarent la route directement sur le callback et n'ont jamais besoin d'une ressource distincte.

Chronologie et attente

GET /v1/runs/{runId}/events?since=0&limit=100 renvoie les événements de l'exécution dans l'ordre de séquence après since, jusqu'à 500 à la fois, avec next_since pour continuer. Les séquences sont continues à partir de 1 et ne changent jamais, si bien que la même requête renvoie toujours les mêmes événements. Les charges utiles plus volumineuses que ce que porte un événement sont référencées par blob_ref, jamais intégrées.

{
  "id": "...",
  "run_id": "...",
  "resource_id": "...",
  "type": "callback.received",
  "sequence": 7,
  "occurred_at": "2026-09-19T09:14:02.118Z",
  "data": {
    "resource": "stripe_callback",
    "method": "POST",
    "path": "/",
    "content_type": "application/json",
    "byte_length": 812,
    "sha256": "..."
  }
}

POST /v1/runs/{runId}/wait bloque jusqu'à ce qu'un événement postérieur à since corresponde, ou que le délai expire. L'attente lit d'abord la chronologie, si bien qu'un événement déjà survenu obtient une réponse immédiate, puis elle se réveille à l'arrivée de nouveaux événements.

curl -X POST https://api.ironfang.uk/rig/v1/runs/$RUN_ID/wait \
  -H "Authorization: Bearer $IRONFANG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "email.received",
    "resource": "customer_email",
    "match": { "subject_contains": "Your order" },
    "since": 0,
    "timeout": "30s"
  }'

Un délai expiré est un 200 avec matched: false, jamais une erreur : rien ne s'est mal passé, la chose attendue n'est simplement pas encore arrivée, et next_since indique où reprendre. Les délais vont de 1 à 90 secondes (30 par défaut) ; bouclez avec next_since pour attendre plus longtemps. Déterministe : la même chronologie et la même requête renvoient toujours le même événement. Au plus 16 attentes peuvent être ouvertes en même temps par organisation.

Charges utiles

GET /v1/runs/{runId}/events/{eventId}/payload renvoie les octets exacts qu'un callback ou un message transportait, sous forme de pièce jointe opaque quoi que l'expéditeur ait déclaré, afin que le contenu de tiers ne soit jamais rendu sur l'origine de l'API. Le type de média déclaré figure dans X-Ironfang-Payload-Media-Type et le SHA-256 dans X-Ironfang-Payload-SHA256. Les octets de charge utile sont conservés 7 jours après la fin de l'exécution ; ensuite l'événement demeure et l'endpoint répond 410.

Catalogue des événements

Chaque type qu'un attendu ou une attente peut nommer, avec les champs de données qu'un match peut viser. Tous les événements portent aussi resource (le nom déclaré) lorsqu'il y en a un.

Connecteur local

Un callback doté d'une connector.route est transmis à une application sur votre machine ou votre runner CI sans ouvrir de port entrant. Le binaire ironfang rig connect contacte la passerelle à wss://connect.rig.ironfang.uk/v1/connect, se lie aux libellés de route et adresse chaque requête transmise à la cible locale que vous avez indiquée pour ce libellé. Le résultat local revient et est enregistré comme connector.request.completed.

Créez un connecteur sur une exécution active. La réponse contient un jeton d'amorçage à usage unique qui expire au bout de dix minutes, l'URL de la passerelle et la ligne de commande à compléter. Le jeton apparaît ici et nulle part ailleurs.

curl -X POST https://api.ironfang.uk/rig/v1/runs/$RUN_ID/connectors \
  -H "Authorization: Bearer $IRONFANG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "ci-runner-3", "routes": ["stripe"] }'

# Then, with the token in the environment rather than an argument:
IRONFANG_CONNECT_TOKEN=ift_boot_... ironfang rig connect \
  --route stripe=http://127.0.0.1:8080/webhooks/stripe

Le connecteur échange le jeton d'amorçage contre un identifiant de session lié à cette organisation, cette exécution et ces routes, qui ne vit pas plus longtemps que l'exécution. Les livraisons pour une route attendent qu'un connecteur la détienne, puis arrivent dans l'ordre, chacune avec un délai local de 30 secondes ; le résultat que signale le connecteur est définitif. Un connecteur qui décroche en cours d'exécution reprend avec son identifiant de session, et les livraisons auxquelles il n'avait pas répondu sont remises en file pour la session suivante avec leur compteur de tentatives incrémenté. GET /v1/runs/{runId}/connectors indique l'état de chaque connecteur et le nombre de livraisons encore en attente. Une exécution peut avoir jusqu'à 16 connecteurs.

Les requêtes transmises portent la méthode, le chemin, la query, les en-têtes et le corps d'origine, plus X-Ironfang-Delivery-ID, X-Ironfang-Event-ID et X-Ironfang-Route, pour que l'application puisse distinguer un rejeu ou un doublon d'une première livraison. Les trames sont limitées à 256 KiB.

Pannes

Une panne est une perturbation déterministe armée sur une ressource d'une exécution active avec POST /v1/runs/{runId}/faults. Elle se déclenche sur la prochaine observation à laquelle elle s'applique, count fois (une fois par défaut) ou, si elle est persistent, jusqu'à son retrait ou la fin de l'exécution. Chaque déclenchement est un événement fault.injected à côté de l'observation sur laquelle il a agi. Aucun hasard : les mêmes pannes face au même trafic donnent la même chronologie.

curl -X POST https://api.ironfang.uk/rig/v1/runs/$RUN_ID/faults \
  -H "Authorization: Bearer $IRONFANG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "type": "duplicate", "resource": "stripe_callback", "copies": 2 }'

Une panne active de chaque type par ressource, et jusqu'à 64 pannes par exécution. Quand plusieurs s'appliquent à la même livraison, drop l'emporte, puis delay, puis duplicate ; un reorder retient la livraison quel que soit son delay, et une mutation de charge utile façonne chaque copie. Les pannes de mock agissent ensemble dans l'ordre où elles ont été armées : un remplacement de statut change le statut, et une réinitialisation, un bridage ou une coupure s'applique à ce qui est alors envoyé. DELETE /v1/runs/{runId}/faults/{faultId} en désarme une et enregistre fault.removed ; la ligne est conservée, car l'historique des pannes fait partie des preuves. Les pannes n'agissent jamais sur un rejeu, qui est un acte explicite du test lui-même.

Attendus et verdicts

Les attendus sont évalués quand l'exécution est terminée, sur l'ensemble de la chronologie. Chacun est satisfait si un événement de son type sur sa ressource satisfait son match, et le premier de ces événements est enregistré avec le verdict. Le résultat de l'exécution découle des verdicts : pass quand tous les attendus sont satisfaits, fail quand l'un d'eux échoue, none pour une suite sans attendus. Passez un résultat pour remplacer cette déduction quand votre propre harnais de test en sait davantage.

curl -X POST https://api.ironfang.uk/rig/v1/runs/$RUN_ID/finish \
  -H "Authorization: Bearer $IRONFANG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "npm test exited 0" }'

{
  "run": { "id": "...", "status": "finished", "outcome": "pass", ... },
  "expectations": [
    { "id": "order_email", "resource": "customer_email", "event": "email.received",
      "passed": true, "event_id": "...", "sequence": 9 },
    { "id": "stripe_forwarded", "resource": "stripe_callback",
      "event": "connector.request.completed", "passed": true, "event_id": "...", "sequence": 12 }
  ]
}

La clôture enregistre un expectation.passed ou un expectation.failed par attendu, puis run.completed. Une exécution annulée ou qui atteint son TTL se termine par run.cancelled ou run.expired, sans verdict. Envoyez un en-tête Idempotency-Key au démarrage d'une exécution pour qu'une étape de CI relancée récupère l'exécution déjà démarrée.

Rejeu

POST /v1/runs/{runId}/events/{eventId}/replay retransmet à sa route de connecteur un callback reçu par l'exécution, exactement tel qu'enregistré, pour prouver que l'application gère une répétition. L'événement doit être un callback.received sur une ressource dotée d'une route de connecteur, et l'exécution doit être active.

curl -X POST https://api.ironfang.uk/rig/v1/runs/$RUN_ID/events/$EVENT_ID/replay \
  -H "Authorization: Bearer $IRONFANG_API_KEY"

{ "event": { "type": "callback.replayed", "data": { "event_id": "...", "replay": 1, ... } },
  "delivery_id": "..." }

Le rejeu est enregistré comme callback.replayed puis circule comme toute livraison : la chronologie montre ses propres callback.forwarded et connector.request.completed rattachés à l'identifiant de l'événement d'origine, et la complétion nomme le delivery_id que la réponse vous a donné. Les pannes armées n'agissent pas sur un rejeu. Au plus 200 rejeux par exécution ; un 422 not_replayable désigne un événement qui n'est pas un callback transmissible.

Paquet de preuves

POST /v1/runs/{runId}/evidence construit le paquet de preuves de l'exécution à partir de ce qu'elle a enregistré et le diffuse en ZIP. Il est en lecture seule : le paquet contient ce que l'appelant peut déjà lire événement par événement, emballé pour être joint à un ticket, un audit ou une version.

Limité à 10 000 événements et 256 MiB de charges utiles ; le manifeste indique quand une limite a joué et liste les charges utiles que la conservation avait déjà supprimées. Avec Accept: application/json, seul le manifeste est renvoyé, avec le chemin qui télécharge le paquet.

Preuve des actions

Chaque événement porte un hash : SHA-256 sur le hash de l'événement précédent, l'identifiant de l'exécution, la séquence, le type, l'horodatage et les données de l'événement en JSON canonique (clés dans l'ordre des octets, sans espaces, nombres tels qu'écrits), joints par des retours à la ligne. L'exécution porte la tête de la chaîne dans chain_head, le manifeste enregistre la chaîne qu'il a recalculée en construisant le paquet, et un octet modifié n'importe où rompt la chaîne à cet événement. Les événements antérieurs au hachage forment un préfixe non haché, que le rapport signale.

POST /v1/runs/{runId}/receipt est une déclaration signée de l'exécution : projet, suite et version, statut et résultat, chaque verdict, le nombre d'événements et la tête de la chaîne, signée sur son JSON canonique. GET /v1/evidence/keys publie les clés de signature par identifiant. Le paquet comme le reçu portent la clé avec laquelle ils ont été signés, si bien qu'ils se vérifient n'importe où :

ironfang rig evidence verify ironfang-rig-$RUN_ID.zip --key <base64 public key>
ironfang rig receipt $RUN_ID --key <base64 public key>

La commande verify contrôle l'empreinte de chaque fichier par rapport au manifeste, recalcule la chaîne à partir de events.json et vérifie la signature ; avec --key, la signature doit provenir d'une clé en laquelle vous avez confiance, sans cette option c'est la clé portée par le paquet qui est utilisée, et le rapport le signale. Le code de sortie 3 signifie qu'une vérification a échoué.

La conservation supprime les charges utiles après 7 jours et les exécutions après 90. PUT /v1/runs/{runId}/hold avec { "until": "..." } (au plus un an à l'avance) conserve une exécution et tout ce qu'elle a enregistré jusqu'à cette date ; DELETE lève le gel. Les deux sont des événements sur la propre chronologie de l'exécution, retention.held et retention.released.

ironfang rig evidence $RUN_ID -o checkout-$RUN_ID.zip
# prints the bundle's SHA-256

Ligne de commande

ironfang rig est un binaire statique unique pour Linux, macOS et Windows, publié avec un fichier de sommes de contrôle SHA-256 par version sur la page des versions. Il lit la clé dans IRONFANG_API_KEY ou --api-key-file, jamais dans un argument, et s'adresse à https://api.ironfang.uk/rig sauf si IRONFANG_API_URL indique autre chose.

ironfang rig sync     [-f ironfang.rig.yaml]
ironfang rig run      [-f file] [--ttl 30m] [--external-id id] [--output text|env|github|json] [-- command args...]
ironfang rig finish   <run-id> [--outcome pass|fail|none] [--reason text]
ironfang rig status   <run-id>
ironfang rig events   <run-id> [--since 0] [--json]
ironfang rig wait     <run-id> --type <event type> [--resource name] [--match key=value]... [--since 0] [--timeout 30s]
ironfang rig evidence <run-id> [-o ironfang-rig-<run-id>.zip]
ironfang rig replay   <run-id> <event-id>
ironfang rig version

run synchronise la suite, démarre une exécution et affiche ses adresses. Avec une commande après --, il exécute cette commande avec IRONFANG_RIG_RUN_ID et une variable IRONFANG_RIG_<RESOURCE> par ressource, puis termine l'exécution. --output env affiche ces affectations pour qu'un shell les charge ; --output github les écrit dans les sorties et l'environnement du job.

GitHub Actions

Deux actions composites du dépôt public ironfang-ltd/rig-action encapsulent la CLI. start synchronise le fichier de suite, démarre une exécution et exporte ses adresses comme sorties d'étape et variables d'environnement du job ; finish termine l'exécution, affiche les verdicts et fait échouer l'étape quand le résultat est fail. Stockez la clé comme secret du dépôt.

jobs:
  integration:
    runs-on: ubuntu-latest
    env:
      IRONFANG_API_KEY: ${{ secrets.IRONFANG_API_KEY }}
    steps:
      - uses: actions/checkout@v4
      - id: test
        uses: ironfang-ltd/rig-action/start@v1
        with:
          suite-file: ironfang.rig.yaml
          ttl: 20m
      - run: npm test
        # IRONFANG_RIG_RUN_ID and IRONFANG_RIG_<RESOURCE> are in the environment
      - if: always()
        uses: ironfang-ltd/rig-action/finish@v1
        with:
          run-id: ${{ steps.test.outputs.run_id }}

L'étape start expose aussi resources, un objet JSON associant chaque nom de ressource à son adresse, pour les étapes qui préfèrent le lire comme des données.

Outils MCP

Le serveur MCP Ironfang expose le même produit aux assistants de code, pour qu'un agent puisse démarrer une exécution, lire la chronologie, armer une panne et exporter les preuves sans quitter l'éditeur. Chaque outil est rattaché à l'organisation de la connexion et ne coûte aucun crédit. Les outils qui créent ou modifient quelque chose l'indiquent dans leurs métadonnées.

Les octets de charge utile ne sont jamais renvoyés par la connexion ; les outils renvoient ce que la chronologie a enregistré et renvoient vers l'API pour le reste.

Limites et conservation

Exportez le paquet de preuves avant que la conservation ne s'applique si une exécution doit lui survivre. Les suites, leurs versions et les projets persistent.

Référence de l'API

URL de base https://api.ironfang.uk/rig. Le document OpenAPI 3.1 à https://api.ironfang.uk/rig/openapi.yaml contient chaque schéma, exemple et erreur, avec des identifiants d'opération stables pour les clients générés. Les identifiants sont des UUID ; les listes se paginent avec cursor et limit (jusqu'à 100).

Interfaces pour machines