Découvrez Forge : le pipeline open source dédié à la génération de SDK, de CLI, de documentation et bien d’autres choses

Aujourd’hui, nous présentons Forge, une nouvelle approche pour générer des SDK, des CLI, de la documentation et des bibliothèques. Forge est un pipeline de génération open source, modulaire et extensible, que chacun peut déployer et utiliser gratuitement.

Forge n’en est qu’à ses débuts, mais génère déjà les ressources nécessaires à la CLI cf et, au cours des mois à venir, il alimentera la documentation de l’API Cloudflare, les SDK et bien d’autres choses.

Nous avons créé Forge parce que nous en avions nous-mêmes besoin pour traiter les agents comme nos clients. Maintenant, nous le rendons open source parce que nous pensons que chacun devrait pouvoir générer l’ensemble des interfaces dont les agents ont besoin. Autrefois, seuls les produits destinés aux développeurs nécessitaient des CLI, des SDK d’API, des serveurs MCP, tous accompagnés d’une documentation d’excellente qualité. Aujourd’hui, ces ressources constituent les prérequis fondamentaux pour chaque produit.

Notre API est devenue trop vaste pour nos générateurs

L’API de Cloudflare compte plus de 3 500 opérations, et les centaines de services qui alimentent ces API sont écrits dans de nombreux langages, notamment Rust, Go, TypeScript et Python. Lorsque nous nous sommes lancés dans le développement d’une CLI pour l’ensemble de l’API Cloudflare (y compris nos SDK et notre documentation d’API), nous avons eu besoin d’un pipeline de génération de code capable d’absorber cette échelle. Ce pipeline doit être suffisamment flexible pour fonctionner avec les différents langages et les méthodes de travail de chacune de nos équipes d’ingénierie.

Nous avions besoin d’un moyen de réduire la surcharge de travail qu’entraînait la coordination des différentes équipes. Lorsqu’une équipe produit de Cloudflare apporte une modification à une API, elle doit pouvoir utiliser une version de prévisualisation de la CLI, du SDK et du site de documentation qui seront générés à l’échelle de Cloudflare avant de fusionner cette modification et de la déployer auprès des clients. Nous avions besoin d’un moyen de nous assurer qu’une équipe ne compromettrait pas involontairement le pipeline de génération, et nous avions besoin d’un système extensible, capable de générer bien plus qu’un SDK, de Cap’n Web à MCP et au-delà.

Nous avons essayé plusieurs produits hébergés qui tentent de résoudre ce problème, et nous en avons même essayé certains en production. Aucun d’eux n’a permis de résoudre ce problème, et certains se sont purement et simplement bloqués. Une équipe fusionnait une modification qui entraînait une interruption involontaire du pipeline de génération, une autre équipe s’en apercevait au moment du déploiement, et nous passions trop de temps à remonter le courant en jonglant avec des outils hébergés que nous ne contrôlions pas, à coordonner les modifications entre équipes et fournisseurs.

C’est ainsi que nous avons commencé à développer Forge.

Forge vise à résoudre tous ces problèmes : il s’exécute dans le pipeline d’intégration continue, sur les dépôts d’API de chaque équipe, tout comme notre relecteur de code IA et nos pipelines de tests. Il analyse statistiquement (lint) chaque modification, puis génère des versions de prévisualisation de la CLI, de la documentation et des SDK en mettant uniquement en évidence vos modifications, que vous pouvez installer afin de les tester. Le principe est identique à Workers Previews : une version de prévisualisation complète pour chaque modification, mais appliquée à la génération de SDK à grande échelle, notamment lorsque la surface d’API est répartie sur des centaines de services et de dépôts. C’est ce que promet Forge.

Les transformateurs de Forge peuvent tout générer, y compris Cap’n Web

Cloudflare a plus de raisons que la plupart des entreprises de vouloir un générateur capable d’aller bien au-delà des cibles de langages habituelles. Cap’n Web est le système de RPC de Cloudflare qui permet à TypeScript d’appeler une API distante comme s’il s’agissait d’une méthode locale.

// Authenticate, get the user's ID, fetch their profile, and fetch every friend's profile...
let authed = api.authenticate(apiToken);
let profile = api.getUserProfile(authed.getUserId());
let friends = authed.getFriendIds().map(id => api.getUserProfile(id));

// ...in a *single* request
let [me, myFriends] = await Promise.all([profile, friends]);

Forge permet de prendre une spécification OpenAPI et de générer directement du Cap’n Web. Cette capacité ouvre la porte à la génération de bindings entre Workers et d’autres API. Après tout, dans le runtime Workers, les bindings sont implémentés sous forme d’instances Workers qui exposent des méthodes RPC.

Et ce n’est pas spécifique à Cap’n Web : d’autres outils populaires sur lesquels vous vous appuyez peut-être déjà ont le même besoin. Si vous utilisez TanStack Query, vous souhaiteriez idéalement pouvoir générer des bindings TanStack Query pour votre application, créés directement depuis votre API ; toujours à jour, et toujours validés par rapport à votre API réelle. Cela s’applique également à la génération de schémas Zod ou Valibot, de serveurs MCP ou de tout autre élément facilitant la consommation de votre API.

Tout cela est possible grâce à la flexibilité des générateurs de code de Forge, qui sont conçus pour faire circuler l’information d’une ressource à une autre.

Les transformateurs de Forge peuvent être chaînés : générer des ressources à partir d’autres ressources

Nous avons conçu Forge pour être modulaire et extensible et prendre en charge de nombreux types d’entrées et de sorties. Forge fournit des générateurs de CLI, de SDK et de documentation, mais rien ne vous empêche d’ajouter un transformateur générant un package spécifique à une bibliothèque, voire un tableau de bord ou une application complète. Aujourd’hui, Forge prend en charge OpenAPI comme format d’entrée, mais nous l’avons pensé pour intégrer, à l’avenir, AsyncAPI, GraphQL, Cap’n Proto, Protobuf ou d’autres formats d’entrée.

Il s’agit de bien plus que d’une simple compatibilité : cela vous permet de chaîner des cibles en utilisant le résultat d’une cible pour en produire d’autres. C’est une pratique courante dans d’autres générateurs, où les cibles CLI et Terraform sont produites à partir du SDK Go. Mais ce qui manque, et ce que Forge apporte, c’est un moyen pour l’utilisateur de contrôler lui-même ce système de chaînage.

Nous avions nous-mêmes besoin d’une solution à ce problème, car notre propre CLI cf est écrite en TypeScript, un langage dont d’autres générateurs de SDK ne permettent généralement pas le chaînage pour les CLI. Cependant, notre propre situation nous a fait prendre conscience d’un problème plus profond : pourquoi un outil de génération de SDK prendrait-il cette décision à votre place ? Peut-être utilisez-vous essentiellement Python et souhaitez-vous que votre CLI soit développée dans ce langage.

Si vous vous dites « Et alors, qu’importe que ce soit en Python ou pas ? Le code est généré automatiquement, » c’est parce que les CLI sont différentes. Les CLI introduisent souvent des comportements locaux qui n’auraient aucun sens dans un SDK ; des comportements que vous écrivez à la main, car ils ne reposent intrinsèquement pas sur un appel d’API. Par exemple, la CLI cf propose des commandes comme cf dev et cf build, qui s’ajoutent au reste des résultats générés. Ces commandes doivent appeler des API TypeScript fournis par d’autres packages, comme Vite.

Maintenant, ajoutons la documentation à l’équation. Si vous générez votre CLI et votre documentation exclusivement à partir de votre spécification OpenAPI, comment réintégrez-vous ces commandes écrites à la main dans votre documentation, pour qu’elles soient documentées aux côtés des autres ressources ?

Nous n’avons trouvé aucun outil existant capable de faire cela aujourd’hui, et pourtant, c’est exactement ce dont nous avons besoin pour cf. C’est pourquoi nous l’intégrons directement dans Forge.

Modifier votre API sans laisser vos utilisateurs sur le carreau

Forge nous prépare également à une meilleure gestion des versions d’API. L’API v4 de Cloudflare incarne l’unique version majeure de notre API depuis dix ans. Depuis lors, il peut sembler que nous n’avons publié aucune nouvelle version majeure ; toutefois, au sens strict des définitions SemVer (versionnage sémantique), nous avons effectué un nombre considérable de modifications, qui mériteraient une nouvelle version majeure. Dans le même temps, plusieurs opérations à travers notre API comportent des indicateurs internes « v2 » ou des identifiants « beta » qui ont depuis longtemps dépassé cette étape du cycle de vie du produit.

Après tant d’années passées sur notre API v4, nous sommes parfaitement conscients qu’une nouvelle version majeure v5 laisserait beaucoup de nos clients sur le carreau. C’est pourquoi, grâce aux artefacts publiés par Forge entre temps, nous travaillons sur une approche de la gestion des versions de l’API qui nous permettra de publier de nouvelles versions majeures d’API sans briser la compatibilité avec les anciens clients ou SDK.

Nous vous communiquerons très prochainement de nouvelles informations sur nos SDK, notamment TypeScript, Rust, Python, Go, PHP et Terraform – et plus particulièrement sur Terraform. Nous savons que la mise à niveau d’un fournisseur Terraform exige une rigueur particulière, et nous allons accorder un soin spécifique à cette transition.

Les outils critiques devraient être accessibles à tous

Nous sommes convaincus que le développement d’outils pour les API constitue un pilier essentiel d’Internet, et vous devriez pouvoir accomplir cette démarche sans avoir besoin d’un produit SaaS. Vous devriez être propriétaire de vos SDK, vos CLI et votre documentation. Et si vous les générez, vous devriez pouvoir en faire ce que vous voulez, où vous le voulez, gratuitement.

C’est pourquoi nous proposons Forge en open source sous la licence permissive Apache 2.0. Nous voulons que la communauté nous rejoigne lors de ce voyage et contribue à l’aventure.

Toutefois, peut-être préférez-vous tout garder pour vous. Pas de problème ! Vous pouvez exécuter Forge par vous-même à n’importe quelle fin, avec vos propres modifications, gratuitement et en toute confidentialité.

Remerciements : ce projet a également pu voir le jour grâce au travail de conception et de mise en œuvre de Dan Carter, Steven Chong, Krishna Paritala et Shelley Jones.