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

Hoy te presentamos Forge, una nueva forma de generar SDK, interfaces de línea de comandos (CLI), documentación y bibliotecas. Forge es un proceso de generación de código abierto y extensible que cualquiera puede implementar y ejecutar gratis.

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

Creamos Forge porque lo necesitábamos nosotros mismos para tratar a los agentes como si fueran nuestros clientes. Ahora lo hacemos de código abierto porque creemos que todo el mundo debería poder generar todo lo que los agentes necesitan. Antes, solo los productos para desarrolladores necesitaban CLI, SDK de API y servidores MCP, todos con una buena documentación. Ahora, eso es lo mínimo que se espera de cualquier producto.

Nuestra API superó a nuestros generadores

La API de Cloudflare cuenta con más de 3500 operaciones, y los cientos de servicios que alimentan estas API están escritos en muchos lenguajes, incluidos Rust, Go, TypeScript y Python. Cuando nos pusimos a crear una CLI para toda la API de Cloudflare, incluyendo nuestros SDK y la documentación de la API, necesitábamos un proceso de generación de código capaz de gestionar esta escala. Ese proceso tiene que ser lo suficientemente flexible como para funcionar con distintos lenguajes y adaptarse a la forma de trabajar de cada uno de nuestros equipos de ingeniería.

Necesitábamos una forma de reducir la carga de coordinación entre equipos. Cuando un equipo de producto de Cloudflare realiza un cambio en la API, tiene que poder usar una versión preliminar de la CLI, el SDK y el sitio de documentación de todo Cloudflare que se va a generar, antes de fusionar ese cambio y ofrecerlo a los clientes. Necesitábamos una forma de asegurarnos de que no interrumpieran inadvertidamente el proceso de generación. Y necesitábamos un sistema que pudiéramos ampliar para generar algo más que un SDK, desde Cap‘n Web hasta MCP y más allá.

Probamos varios productos alojados que pretendían resolver esto y llegamos a usar algunos en producción. Ninguno nos solucionó el problema y algunos incluso han dejado de funcionar por completo. Un equipo fusionaba un cambio que, sin darse cuenta, rompía el proceso de generación; otro equipo se daba cuenta de ello en el momento del lanzamiento, y nos pasábamos demasiado tiempo luchando contra corriente con 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 API de cada equipo, igual que nuestro revisor de código con IA y nuestros procesos de pruebas. Analiza cada cambio y, a continuación, genera compilaciones de vista previa de la CLI, la documentación y los SDK con tus cambios resaltados, que puedes instalar para probarlos. Es la misma premisa que Workers Previews: una compilació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 entre cientos de servicios y repositorios. Eso es lo que Forge pretende 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 ir mucho más allá de 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 te permite tomar una especificación OpenAPI y generar Cap’n Web directamente. Esto abre la puerta a generar enlaces desde 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 populares en las que quizá ya confíes necesitan lo mismo. Si usas TanStack Query, lo ideal sería que pudieras generar enlaces de TanStack Query para tu aplicación, creados directamente a partir de tu propia API. Siempre al día, siempre validados con tu API real. Lo mismo ocurre con la generación de esquemas de Zod o Valibot, servidores MCP o cualquier otra cosa que facilite el uso de tu API.

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

Los transformadores de Forge se pueden encadenar. Genera salidas a partir de otras salidas

Hemos diseñado Forge para que sea extensible y admita muchos tipos de entrada y salida. Forge ofrece generadores de CLI, SDK y documentación, pero nada te impide añadir un transformador que genere un paquete específico para una biblioteca o incluso un panel de control o una aplicación completa. Forge admite actualmente OpenAPI como tipo de entrada, pero lo hemos diseñado para que admita AsyncAPI, GraphQL, Cap’n Proto, Protobuf u otros formatos de entrada en el futuro.

Esto va más allá de la simple compatibilidad: te permite encadenar objetivos, utilizando la salida de un objetivo para generar otras. Esto es habitual en otros generadores, donde los objetivos de la CLI y de Terraform se generan a partir del SDK de Go. Pero lo que falta, y lo que ofrece Forge, 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 CLI de cf está escrita en TypeScript, un lenguaje desde el que otros generadores de SDK no suelen encadenar para crear CLI. Pero nuestra propia situación nos hizo darnos cuenta del problema mayor: ¿por qué debería cualquier herramienta generadora de SDK tomar esta decisión por ti? Quizá trabajes con Python y quieras que la CLI esté en Python.

Si estás pensando “Bueno, pero ¿a quién le importa si está en Python o no? El código se genera automáticamente”, es porque las CLI son diferentes. Las CLI suelen introducir comportamientos exclusivos del entorno local que no tendrían sentido en un SDK. Comportamientos que escribes a mano, ya que, por naturaleza, no están respaldados por ninguna llamada a la API. Por ejemplo, la CLI de cf tiene comandos como cf dev y cf build que se añaden al resto del código generado. Estos comandos necesitan llamar a las API de TypeScript desde otros paquetes como Vite.

Ahora añadamos la documentación a la ecuación. Si estás generando tu CLI y tu documentación únicamente a partir de tu especificación OpenAPI, ¿cómo incorporas esos comandos escritos a mano a tu documentación, para que puedan documentarse junto con el resto?

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

Cambia tu API sin afectar a los usuarios

Forge también nos está preparando para una mejor gestión de versiones de la API. La API v4 de Cloudflare ha sido la única versión significativa de nuestra API durante 10 años. Desde entonces, parece que no hayamos lanzado ninguna nueva versión importante, pero según las definiciones de SemVer hemos hecho bastantes cambios que merecerían una nueva versión principal. Al mismo tiempo, varias operaciones de nuestra API incluyen etiquetas internas v2 o identificadores beta que hace tiempo que han superado esa fase del ciclo de vida del producto.

Después de tantos años con nuestra API v4, somos muy conscientes de que una gran versión v5 dejaría atrás a muchos de nuestros clientes. Por eso, ahora que Forge va lanzando novedades, estamos trabajando en un enfoque de versionado de la API que nos permita lanzar nuevas versiones principales sin que los antiguos clientes o SDK dejen de funcionar.

Muy pronto daremos más detalles sobre nuestros SDK, incluyendo TypeScript, Rust, Python, Go, PHP y Terraform. Especialmente Terraform. Sabemos que actualizar cualquier proveedor de Terraform conlleva su propio nivel de complejidad, 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 crear herramientas para API es una parte fundamental de Internet, y deberías poder hacerlo sin necesidad de un producto SaaS. Tus SDK, CLI y documentación deben ser tuyos. Y si los generas tú mismo, deberías poder hacer lo que quieras, donde quieras y de forma gratuita.

Por eso estamos haciendo que Forge esté disponible como código abierto bajo la permisiva licencia Apache 2.0. Queremos que la gente se una a este viaje con nosotros y aporte su granito de arena.

¿O no? Quizás prefieras quedártelo todo para ti. ¡Adelante! Puedes ejecutar Forge por tu cuenta para cualquier propósito, con modificaciones personalizadas, gratis y en privado.

Agradecimientos: Este proyecto también ha sido posible gracias al trabajo de diseño y desarrollo de Dan Carter, Steven Chong, Krishna Paritala y Shelley Jones.