Apresentamos o Forge: o pipeline de código aberto para gerar SDKs, CLIs, documentação e muito mais

Hoje apresentamos o Forge, uma abordagem renovada para gerar SDKs, CLIs, documentação e bibliotecas. O Forge é um pipeline de geração de código aberto e modular, que qualquer pessoa pode implantar e executar gratuitamente.

O Forge ainda está em um estágio inicial, mas já gera as saídas necessárias para a cf CLI e, ao longo dos próximos meses, ele irá impulsionar a documentação da API, os SDKs e muito mais da Cloudflare.

Criamos o Forge para, internamente, tratar agentes como nossos clientes. Agora estamos disponibilizando-o como código aberto porque acreditamos que todos devem ser capazes de gerar todas as superfícies de que os agentes precisam. Antes, apenas produtos para desenvolvedores precisavam de CLIs, SDKs de API e servidores MCP, todos com documentação impecável. Hoje, esses são requisitos básicos para qualquer produto.

Nossa API superou nossos geradores

A API da Cloudflare conta com mais de 3.500 operações, e as centenas de serviços que a alimentam são escritos em muitas linguagens, incluindo Rust, Go, TypeScript e Python. Ao embarcar na construção de uma CLI para toda a API da Cloudflare, incluindo nossos SDKs e documentação da API, precisávamos de um pipeline de geração de código capaz de operar nessa escala. Esse pipeline precisa ser flexível o suficiente para funcionar entre linguagens e se adaptar à forma de trabalhar de cada um em nossas equipes de engenharia.

Precisávamos de uma forma de reduzir o esforço de coordenação entre equipes. Quando uma equipe de produto da Cloudflare faz uma alteração na API, ela precisa conseguir usar uma versão prévia da CLI, do SDK e do site de documentação comuns à Cloudflare, tudo isso antes de mesclar essa alteração e entregá-la aos clientes. Também era necessário encontrar uma maneira de garantir que não quebrassem inadvertidamente o pipeline de geração. E por fim, havia a necessidade de um sistema que pudesse gerar mais do que apenas um SDK, desde o Cap’n Web ao MCP e além.

Testamos vários produtos hospedados que tentam resolver isso e chegamos a contar com alguns deles em produção. Nenhum resolveu o problema para nós, e alguns foram até mesmo descontinuados. Uma equipe mesclava uma alteração que acabava quebrando o pipeline de geração, outra só descobria isso no momento do lançamento, e perdemos tempo demais nadando contra a corrente usando ferramentas hospedadas que não podíamos controlar, coordenando alterações entre equipes e fornecedores.

Foi assim que começamos a desenvolver o Forge.

O Forge foi criado para resolver todos esses problemas: ele roda em CI, nos repositórios de API de cada equipe, assim como o nosso revisor de código com IA e os pipelines de teste. Ele analisa cada alteração e, em seguida, gera versões prévias da CLI, da documentação e dos SDKs com apenas suas alterações destacadas, que podem ser instaladas para teste. É o mesmo princípio do Workers Previews: uma versão  prévia completa para cada alteração, mas aplicada à geração de SDKs em escala, mesmo quando a superfície da API está distribuída em centenas de serviços e repositórios. É isso que o Forge pretende entregar.

Os transformadores do Forge podem gerar qualquer coisa, incluindo Cap’n Web

Mais do que ninguém, a Cloudflare tem vários motivos para querer um gerador capaz de ir além dos alvos de linguagem habituais. O Cap’n Web é o sistema RPC da Cloudflare que permite ao TypeScript chamar uma API remota como se fosse uma chamada de 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]);

O Forge permite usar uma especificação OpenAPI para gerar diretamente Cap’n Web, o que, por sua vez, possibilita gerar bindings de Workers para outras APIs. Afinal, os bindings no runtime do Workers são implementados como Workers que expõem métodos RPC.

Isso não é exclusivo do Cap’n Web: outras ferramentas populares que vocês talvez já utilizem precisam do mesmo. Se você usa TanStack Query, o ideal seria poder gerar bindings do TanStack Query para seu aplicativo, criados diretamente a partir de sua própria API, sempre atualizados e validados em relação à sua API real. O mesmo vale para gerar schemas Zod ou Valibot, servidores MCP ou qualquer outra coisa que facilite o consumo da sua API.

Isso é possível porque os geradores de código do Forge são flexíveis. Eles foram desenvolvidos para permitir o fluxo de informações de uma saída para outra.

Os transformadores do Forge podem ser encadeados: gerando saídas a partir de outras saídas.

Projetamos o Forge para ser extensível e compatível com diversos tipos de entrada e saída. O Forge oferece geradores de CLI, SDK e documentação, mas nada impede você de adicionar um transformador que gere um pacote específico de uma biblioteca ou até mesmo um painel ou aplicativo completo. Atualmente, o Forge é compatível com OpenAPI como tipo de entrada, mas ele foi projetado para permitir AsyncAPI, GraphQL, Cap’n Proto, Protobuf ou outros formatos de entrada no futuro.

Além de simples compatibilidade, isso permite que você encadeie destinos, usando a saída de um destino para produzir outros. Isso é comum em outros geradores, onde os destinos de CLI e Terraform são produzidos a partir do SDK Go. Mas o que falta, e o que o Forge oferece, é uma forma de o usuário controlar esse sistema de encadeamento por conta própria.

Internamente, nós buscávamos uma solução para essa questão, pois nossa própria cf CLI é escrita em TypeScript, algo que outros geradores de SDK geralmente não encadeiam para CLIs. Mas a nossa própria situação nos fez perceber qual era o real problema: por que uma ferramenta geradora de SDK deveria tomar essa decisão por você? Talvez sua equipe use Python e você queira que a CLI também seja em Python.

Se você está pensando: “E quem se importa se é em Python ou não? O código é gerado automaticamente”, saiba que CLIs são diferentes. As CLIs frequentemente introduzem comportamentos exclusivamente locais que não fariam sentido em um SDK, comportamentos que você escreve manualmente porque, por natureza, não são respaldados por nenhuma chamada de API. Por exemplo, a cf CLI tem comandos como cf dev e cf build que são adicionados ao restante da saída gerada. Estes comandos precisam chamar APIs TypeScript de outros pacotes como o Vite.

Agora adicione a documentação à mistura. Se você está gerando sua CLI e sua documentação puramente a partir de sua especificação OpenAPI, como você reintroduz esses comandos escritos manualmente em sua documentação, para que possam ser documentados junto com o restante?

Não encontramos nenhuma ferramenta existente que faça isso hoje, e ainda assim é exatamente o que precisamos para a cf. Por isso, estamos incorporando isso ao Forge.

Altere sua API sem comprometer os usuários

O Forge também está nos preparando para um melhor versionamento de API. A API v4 da Cloudflare é a única versão principal de nossa API há 10 anos; desde então, pode parecer que não lançamos novas versões principais, mas pelas definições do SemVer, fizemos algumas mudanças que justificam uma nova versão principal. Ao mesmo tempo, diversas operações em nossa API têm tags internas “v2” ou identificadores “beta” que sobreviveram por muito tempo àquela fase do ciclo de vida do produto.

Após tantos anos com a nossa API v4, temos plena consciência de que uma nova v5 deixaria muitos de nossos clientes para trás. Por isso, com o Forge publicando artefatos ao longo do caminho, estamos trabalhando em uma abordagem ao versionamento de API que nos permita lançar novas versões principais sem comprometer clientes ou SDKs antigos.

Em breve teremos muito mais informações sobre nossos SDKs, incluindo TypeScript, Rust, Python, Go, PHP e Terraform. Especialmente o Terraform. Sabemos que atualizar qualquer provedor Terraform exige seu próprio nível de rigor, e vamos prestar atenção especial à transição do Terraform.

Ferramentas essenciais devem ser acessíveis a todos

Acreditamos que construir ferramentas para APIs é uma parte fundamental da internet, e todos devem poder fazê-lo sem precisar de um produto SaaS. Você deve ser o dono de seus SDKs, CLIs e documentação. E se você os gera, deve poder fazer o que quiser com eles, onde quiser, gratuitamente.

Por isso estamos disponibilizando o Forge como código aberto sob a licença permissiva Apache 2.0. Queremos que as pessoas se juntem a nós nessa jornada e contribuam.

Ou não? Talvez você queira guardar tudo para si. Também pode. Você pode executar o Forge para qualquer finalidade, com modificações personalizadas, de forma gratuita e privada na sua própria infraestrutura.

Agradecimentos: Este projeto também foi  viabilizado graças aos esforços de design e implementação de Dan Carter, Steven Chong, Krishna Paritala e Shelley Jones.