Wir stellen Forge vor: die Open-Source-Pipeline zur Generierung von SDKs, CLIs, Dokumentation und mehr

Heute stellen wir Forge vor – einen frischen Ansatz zur Generierung von SDKs, CLIs, Dokumentation und Bibliotheken. Forge ist eine  modular erweiterbare Open-Source-Generierungs-Pipeline, die jeder kostenlos auf eigener Infrastruktur einsetzen und betreiben kann.

Forge steht noch am Anfang, generiert aber bereits die benötigten Ausgaben für die cf CLI  In den kommenden Monaten wird es auch die API-Dokumentation, SDKs und vieles mehr von Cloudflare generieren.

Wir haben Forge entwickelt, weil wir selbst ein solches Werkzeug brauchten, um Agents als Kunden bedienen zu können. Jetzt veröffentlichen wir es als Open Source. Denn wir finden, dass jeder die Schnittstellen und Werkzeuge generieren können sollte, die KI-Agenten benötigen. Früher brauchten vor allem Produkte für Entwicklerinnen und Entwickler eine CLI, API-SDKs und MCP-Server – jeweils mit einer guten Dokumentation. Heute gehört all das zur Grundausstattung jedes Produkts.

Unsere API ist zu groß für die bisherigen Generatoren geworden

Die API von Cloudflare umfasst über 3.500 Operationen. Dahinter stehen Hunderte von Diensten, die in unterschiedlichen Programmiersprachen entwickelt wurden, darunter Rust, Go, TypeScript und Python. Für eine CLI, die die gesamte Cloudflare-API abdeckt, sowie für unsere SDKs und die API-Dokumentation brauchten wir eine Pipeline zur Codegenerierung, die mit diesem Umfang umgehen kann. Gleichzeitig musste sie verschiedene Sprachen unterstützen und sich in die unterschiedlichen Arbeitsabläufe unserer Entwicklungsteams einfügen.

Wir wollten den Abstimmungsaufwand zwischen den Teams reduzieren. Wenn ein Produktteam eine API ändert, muss es vorab testen können, wie sich diese Änderung auf die CLI für ganz Cloudflare, die SDKs und die Dokumentationswebsite auswirkt. Dazu braucht es Vorschauversionen – bevor die Änderung zusammengeführt und an Kunden ausgeliefert wird. So lässt sich prüfen, ob der Generierungsprozess weiterhin funktioniert. Außerdem wollten wir das System erweitern können, um mehr als SDKs zu erzeugen: etwa Komponenten für Cap’n Web, MCP-Server und weitere Integrationen.

Wir haben mehrere gehostete Produkte ausprobiert, die dieses Problem lösen sollen, und einige davon auch produktiv eingesetzt. Doch keines erfüllte unsere Anforderungen vollständig. Einige wurden sogar ganz eingestellt. Immer wieder führte ein Team eine Änderung zusammen, die unbemerkt den Generierungsprozess störte. Ein anderes Team bemerkte das erst bei der Veröffentlichung. Wir verbrachten zu viel Zeit damit, die Einschränkungen gehosteter Tools zu umgehen, die wir nicht selbst kontrollieren konnten, und Änderungen zwischen Teams und Anbietern abzustimmen.

Deshalb haben wir begonnen, Forge zu entwickeln.

Forge soll diese Probleme lösen. Es läuft direkt in den CI-Pipelines der API-Repositories unserer Teams – ebenso wie unsere KI-gestützte Codeprüfung und unsere automatisierten Tests. Forge prüft jede Änderung mit einem Linter und erstellt anschließend Vorschauversionen der CLI, der Dokumentation und der SDKs. Darin sind eure Änderungen hervorgehoben. Ihr könnt die Vorschauversionen installieren und direkt testen. Das Prinzip entspricht dem von Workers Previews: Für jede Änderung entsteht eine vollständige Vorschauversion. Forge überträgt diesen Ansatz auf die SDK-Generierung im großen Maßstab – auch wenn die API-Funktionen über Hunderte von Diensten und Repositories verteilt sind. Genau dafür entwickeln wir Forge.

Forge-Transformer können mehr als SDKs generieren -  ​​auch für Cap'n Web

Für Cloudflare ist ein Generator besonders wichtig, der mehr kann als SDKs für verschiedene Programmiersprachen zu erzeugen. Cap’n Web ist Cloudflares RPC-System. Damit lassen sich entfernte APIs aus TypeScript heraus so aufrufen, als wären es lokale Methoden.

// 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 kann die benötigten Komponenten für Cap’n Web direkt aus einer OpenAPI-Spezifikation generieren. Damit lassen sich künftig auch Bindings erzeugen, über die Workers auf andere APIs zugreifen können. Schließlich sind Bindings in der Workers-Laufzeitumgebung selbst als Workers implementiert, die RPC-Methoden bereitstellen.

Dieser Ansatz ist nicht auf Cap’n Web beschränkt. Auch andere verbreitete Tools, die ihr vielleicht bereits nutzt, profitieren davon. Wenn ihr mit TanStack Query arbeitet, wäre es beispielsweise hilfreich, die passenden Bindings für eure Anwendung direkt aus eurer eigenen API generieren zu können. So bleiben sie aktuell und werden anhand eurer tatsächlichen API geprüft. Dasselbe gilt für Zod- oder Valibot-Schemas, MCP-Server und andere Komponenten, die die Nutzung eurer API erleichtern.

Möglich wird das durch die flexiblen Codegeneratoren von Forge. Sie sind darauf ausgelegt, die Ergebnisse eines Generierungsschritts im nächsten weiterzuverwenden.

Forge-Transformer können verketten: Ergebnisse weiterverwenden

Wir haben Forge so konzipiert, dass es modular erweiterbar ist und viele Eingabe- und Ausgabetypen unterstützt. Forge bietet CLI-, SDK- und Dokumentationsgeneratoren.  Ihr könnt aber auch eigene Transformer ergänzen, die ein Paket für eine bestimmte Bibliothek, ein vollständiges Dashboard oder eine Anwendung erzeugen. Derzeit unterstützt Forge OpenAPI als Eingabeformat. Die Architektur ist jedoch darauf vorbereitet, künftig auch AsyncAPI, GraphQL, Cap’n Proto, Protobuf und weitere Formate zu verarbeiten

Dabei geht es um mehr als die Unterstützung verschiedener Formate: Ihr könnt mehrere Generierungsschritte miteinander verknüpfen und die Ergebnisse eines Schritts als Grundlage für weitere nutzen. Andere Generatoren machen das ebenfalls. Sie erzeugen beispielsweise CLIs und Terraform-Komponenten auf Grundlage eines Go-SDKs. Was bisher fehlt und Forge ermöglicht: Ihr legt selbst fest, wie diese Schritte miteinander verbunden werden.

Wir brauchten diese Möglichkeit für unsere eigene cf-CLI, die in TypeScript geschrieben ist. Andere SDK-Generatoren nutzen TypeScript-SDKs jedoch in der Regel nicht als Grundlage für die CLI-Generierung. Dabei wurde uns eine grundlegendere Frage klar: Warum sollte ein SDK-Generator diese Entscheidung für euch treffen? Vielleicht arbeitet euer Team hauptsächlich mit Python und möchte auch die CLI in Python entwickeln.

Vielleicht fragt ihr euch jetzt: Ist die Programmiersprache nicht egal, wenn der Code ohnehin automatisch generiert wird? Bei CLIs macht sie tatsächlich einen Unterschied. Denn CLIs bieten häufig Funktionen, die ausschließlich lokal ausgeführt werden und in einem SDK keinen Sinn ergeben würden. Diese Funktionen implementiert ihr von Hand, weil sie nicht auf einem API-Aufruf beruhen. Die cf-CLI enthält beispielsweise Befehle wie cf dev und cf build, die wir den generierten Befehlen manuell ergänzen. Sie müssen TypeScript-APIs aus anderen Paketen wie Vite aufrufen können.

Hinzu kommt die Dokumentation. Wenn ihr sowohl die CLI als auch die Dokumentation ausschließlich aus eurer OpenAPI-Spezifikation generiert, stellt sich eine weitere Frage: Wie werden die manuell implementierten Befehle ebenfalls automatisch dokumentiert?

Wir haben kein bestehendes Tool gefunden, das diese Aufgabe übernimmt. Genau diese Funktion brauchen wir aber für cf. Deshalb integrieren wir sie in Forge.

Die API weiterentwickeln, ohne Nutzer zu beeinträchtigen

Forge schafft auch die Grundlage für eine bessere API-Versionierung. Seit zehn Jahren ist v4 die einzige Hauptversion der Cloudflare-API. Nach außen wirkt es deshalb so, als hätten wir seitdem keine neuen Hauptversionen veröffentlicht. Nach den Regeln der semantischen Versionierung (SemVer) hätten allerdings mehrere unserer Änderungen eine neue Hauptversion erfordert. Gleichzeitig tragen einige API-Operationen noch interne Kennzeichnungen wie „v2“ oder „beta“, obwohl die entsprechenden Entwicklungsphasen längst abgeschlossen sind.

Nach so vielen Jahren mit unserer v4-API wissen wir, dass ein umfassender Wechsel auf Version 5 viele unserer Kunden vor Probleme stellen würde. Deshalb arbeiten wir an einem Versionierungsansatz, mit dem wir neue API-Hauptversionen veröffentlichen können, ohne die Kompatibilität mit bestehenden Clients oder SDKs zu verlieren. Parallel dazu stellt Forge nach und nach die generierten Komponenten bereit.

Schon bald werden wir mehr über unsere SDKs und die Unterstützung für TypeScript, Rust, Python, Go, PHP und Terraform berichten. Besonders über Terraform. Wir wissen, dass Updates von Terraform-Providern sorgfältig vorbereitet werden müssen. Deshalb werden wir bei dieser Umstellung besonders behutsam vorgehen.

Wichtige Tools sollten allen offenstehen

Die Entwicklung von Werkzeugen für APIs ist für uns ein wesentlicher Bestandteil des Internets. Dafür solltet ihr nicht auf einen SaaS-Dienst angewiesen sein. Eure SDKs, CLIs und eure Dokumentation sollten euch gehören. Wenn ihr sie generiert, solltet ihr sie kostenlos so nutzen und dort betreiben können, wie und wo ihr möchtet.

Deshalb veröffentlichen wir Forge als Open Source unter der Apache-2.0-Lizenz. Wir freuen uns über alle, die Forge gemeinsam mit uns weiterentwickeln möchten.

Ihr möchtet eure Anpassungen lieber für euch behalten? Auch das ist möglich. Ihr könnt Forge kostenlos für beliebige Zwecke auf eurer eigenen Infrastruktur betreiben und an eure Anforderungen anpassen, ohne eure Änderungen veröffentlichen zu müssen.

Danksagung: Auch die Arbeit von Dan Carter, Steven Chong, Krishna Paritala und Shelley Jones an der Konzeption und Implementierung hat dieses Projekt möglich gemacht.