Forge, el proceso de código abierto para generar SDK, interfaces de línea de comandos, documentación y mucho más

Hoy presentamos Forge, un enfoque renovado para generar SDK, interfaces de línea de comandos,, documentación y bibliotecas. Forge es un proceso de generación de código abierto, modular y extensible que cualquiera puede desplegar y ejecutar de forma gratuita.

Forge está en sus primeros pasos, pero ya genera el contenido necesario para el CLI cf, y en los próximos meses impulsará la documentación de la API de Cloudflare, los SDK y mucho más.

Desarrollamos Forge porque lo necesitábamos nosotros mismos para tratar a los agentes como nuestros clientes. Ahora lo publicamos como código abierto porque creemos que todos deberían poder generar todas las superficies que los agentes necesitan. Antes, solo los productos para desarrolladores necesitaban CLI, SDK de API y servidores MCP, todos con una documentación excelente. Ahora esos son los requisitos básicos para cualquier producto.

Nuestra API superó a nuestros generadores

La API de Cloudflare cuenta con más de 3.500 operaciones, y los cientos de servicios que alimentan estas API están escritos en muchos lenguajes, incluidos Rust, Go, TypeScript y Python. Al embarcarnos en el desarrollo de una CLI para toda la API de Cloudflare, incluidos nuestros SDK y la documentación de la API, necesitábamos un proceso de generación de código capaz de manejar esta escala. Ese proceso debe ser lo suficientemente flexible para funcionar en todos los lenguajes y adaptarse a las formas de trabajar de cada uno de nuestros equipos de ingeniería.

Necesitábamos una forma para reducir la sobrecarga de coordinación entre equipos. Cuando un equipo de producto de Cloudflare realiza un cambio en la API, tiene que poder utilizar una versión de vista previa de la CLI, el SDK y el sitio de documentación generados para toda Cloudflare antes de fusionar ese cambio y ofrecerlo a los clientes. Necesitábamos una forma de garantizar que no rompieran inadvertidamente el pipeline de generación. Y necesitábamos un sistema que pudiéramos ampliar para generar más que un simple SDK, desde Cap'n Web hasta MCP y más allá.

Probamos varios productos alojados que pretendían resolver esto y utilizamos algunos de ellos en producción. Ninguno resolvió este problema para nosotros, y algunos dejaron de funcionar por completo. Un equipo implementaba un cambio que sin querer rompía el proceso de generación, otro equipo lo detectaba en el momento del lanzamiento, y hemos perdido demasiado tiempo nadando contra la corriente a través de herramientas alojadas que no podíamos controlar, coordinando cambios entre equipos y proveedores.

Así fue como empezamos a desarrollar Forge.

Forge busca solucionar todos estos problemas: se ejecuta en CI, en los repositorios de la API de cada equipo, igual que nuestro revisor de código de la IA y nuestros proceso de pruebas. Analiza cada cambio y luego genera versiones de vista previa de la CLI, la documentación y los SDK con solo los cambios resaltados, que se pueden instalar para probar. Es el mismo principio que Workers Previews: una versión de vista previa completa para cada cambio, pero aplicada a la generación de SDK a escala, incluso cuando la superficie de la API está distribuida en cientos de servicios y repositorios. Eso es lo que Forge busca ofrecer.

Los transformadores de Forge pueden generar cualquier cosa, incluido Cap'n Web

Cloudflare tiene más razones que la mayoría para querer un generador que pueda superar los objetivos de lenguaje habituales. Cap'n Web es el sistema RPC de Cloudflare que permite a TypeScript llamar a una API remota como si fuera un método local.

// 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 hace posible tomar una especificación OpenAPI y generar Cap'n Web directamente. Esto permite generar bindings de Workers a otras API. Al fin y al cabo, los enlaces en el entorno de ejecución de Workers se implementan como Workers que exponen métodos RPC.

Esto no es exclusivo de Cap'n Web: otras herramientas conocidas que quizás ya utilizas necesitan lo mismo. Si utilizas TanStack Query, idealmente querrías poder generar enlaces de TanStack Query para tu aplicación, creados directamente desde su propia API. Siempre actualizados, siempre validados contra tu API real. Lo mismo ocurre con la generación de esquemas Zod o Valibot, servidores MCP, o cualquier otra cosa que facilite el consumo de tu API.

Esto es posible porque los generadores de código de Forge son flexibles. Están diseñados para mover información de una salida a otra.

Los transformadores de Forge se pueden encadenar: generar salidas a partir de otras salidas

Hemos diseñado Forge para ser modular y extensible y admitir muchos tipos de entradas y salidas. Forge proporciona generadores de CLI, SDK y documentación, pero nada les impide añadir un transformador que genere un paquete específico de una biblioteca o incluso un panel de control o una aplicación completa. Forge admite OpenAPI como tipo de entrada hoy en día, pero lo hemos diseñado para permitir AsyncAPI, GraphQL, Cap'n Proto, Protobuf u otros formatos de entrada en el futuro.

Esto va más allá de la simple compatibilidad: les permite encadenar objetivos, mediante la salida de un objetivo para producir otros. Esto es habitual en otros generadores donde los objetivos de CLI y Terraform se producen a partir del SDK de Go. Pero lo que falta, y lo que Forge proporciona, es una forma de que el usuario controle este sistema de encadenamiento por sí mismo.

Nosotros mismos necesitábamos una solución para esto, porque nuestra propia CLI cf está escrita en TypeScript, algo que otros generadores de SDK generalmente no encadenan para las CLI. Pero nuestra propia situación nos hizo reconocer un problema mayor: ¿por qué debería una herramienta generadora de SDK tomar esta decisión por ustedes? Quizás son un equipo de Python y quieren que la CLI esté en Python.

Si están pensando «Bueno, ¿y a quién le importa si está en Python o no? El código se genera automáticamente», es porque las CLIs son diferentes. Las CLIs suelen introducir comportamientos solo locales que no tendrían sentido en un SDK. Comportamientos que se escriben a mano porque inherentemente no están respaldados por ninguna llamada a la API. Por ejemplo, la CLI cf tiene comandos como cf dev y cf build que se añaden sobre el resto de la salida generada. Estos comandos necesitan llamar a API de TypeScript de otros paquetes como Vite.

Ahora añadamos la documentación a la mezcla. Si estás generando tu CLI y tu documentación puramente a partir de tu especificación OpenAPI, ¿cómo introducís esos comandos escritos a mano en tu documentación, para que puedan documentarse junto al resto?

No encontramos ninguna herramienta existente que haga esto hoy en día, y sin embargo es exactamente lo que necesitamos para cf. Así que lo estamos incorporando a Forge.

Modifica tu API sin afectar a los usuarios

Forge también nos está preparando para una mejor versión de API. La API v4 de Cloudflare ha sido la única versión principal de nuestra API durante 10 años. Desde entonces, parece que no hemos lanzado ninguna nueva versión principal, pero según las definiciones de SemVer hemos realizado bastantes cambios que merecerían una nueva versión principal. Al mismo tiempo, varias operaciones de nuestra API presentan etiquetas internas «v2» o identificadores «beta» que han sobrevivido con dificultades a esa parte del ciclo de vida del producto.

Después de tantos años con nuestra API v4, somos muy conscientes de que una nueva versión v5 dejaría atrás a muchos de nuestros clientes. Por eso, Forge está lanzando novedades y nosotros estamos trabajando en un enfoque de versionado de API que nos permita lanzar nuevas versiones principales de API sin afectar a los clientes o SDKs antiguos.

Muy pronto tendremos más información sobre nuestros SDK, incluidos TypeScript, Rust, Python, Go, PHP y Terraform. Especialmente Terraform. Sabemos que actualizar cualquier proveedor de Terraform conlleva su propio nivel de rigor, y vamos a prestar una atención especial a la transición de Terraform.

Las herramientas esenciales deben estar al alcance de todos

Creemos que construir herramientas para APIs es una parte fundamental del Internet, y deberían poder hacerlo sin necesitar un producto SaaS. Deberían ser dueños de sus SDKs, CLIs y documentación. Y si los generan, deberían poder hacer con ellos lo que quieran, donde quieran, de forma gratuita.

Por eso ponemos Forge a disposición de todos como código abierto bajo la permisiva licencia Apache 2.0. Queremos que la gente se una a nosotros en este camino y contribuya.

¿O no? Quizás quieren guardarlo todo para ustedes. ¡Adelante! Pueden ejecutar Forge por su cuenta para cualquier propósito, con modificaciones personalizadas, de forma gratuita y en privado.

Agradecimientos: Este proyecto también fue posible gracias a los esfuerzos de diseño e implementación de Dan Carter, Steven Chong, Krishna Paritala y Shelley Jones.