Cloudflare, SDK'lar, CLI'lar ve dokümantasyon üreten eklenebilir bir pipeline olan Forge'u açık kaynak yaptı

Cloudflare, API spesifikasyonlarından SDK, CLI ve dokümantasyon üreten eklenebilir bir pipeline olan Forge'u açık kaynak yaptı. Şirketin blog yazısına göre Forge, halihazırda cf CLI'nın arkasındaki çıktıyı üretiyor ve önümüzdeki aylarda Cloudflare'ın API dokümantasyonunu, SDK'larını ve diğer üretilen yüzeylerini de yönetecek. Proje, izin veren Apache 2.0 lisansıyla yayınlandı ve ücretsiz olarak dağıtılıp çalıştırılabiliyor.

Cloudflare neden geliştirdi

Cloudflare'ın API'si 3.500'den fazla işlemi kapsıyor ve arkasındaki yüzlerce servis Rust, Go, TypeScript ve Python dahil olmak üzere çeşitli dillerle yazılmış durumda. Şirket, tüm API'sini kapsayan bir CLI ile birlikte SDK'lar ve dokümantasyon oluşturmaya kalkıştığında, bu ölçeği birçok ekip ve depo genelinde yönetebilecek kadar esnek bir üretim pipeline'ına ihtiyaç duydu.

Cloudflare daha önce barındırılan kod üretimi ürünlerine bel bağladığını, ancak bunların hiçbirinin sorunu çözmediğini ve bazılarının tamamen kapandığını söylüyor. Uygulamada bir ekip, üretim pipeline'ını sessizce bozan bir API değişikliğini merge ederken, başka bir ekip bozulmayı ancak yayın sırasında fark ediyordu. Ekipler ve tedarikçiler arasındaki koordinasyon yükü bir vergi haline gelmişti.

Forge farklı bir yaklaşım benimsiyor: test pipeline'ına çok benzer şekilde her ekibin API deposundaki CI içinde çalışıyor. Her değişikliği lint'liyor ve yalnızca o değişikliği içeren CLI, dokümantasyon ve SDK'ların önizleme build'lerini üretiyor; yazar bunları merge etmeden önce kurup test edebiliyor.

Eklenebilir ve zincirlenebilir üreticiler

Forge bugün girdi formatı olarak OpenAPI kabul ediyor ve Cloudflare, tasarımın ileride AsyncAPI, GraphQL, Cap'n Proto, Protobuf ve diğer formatlara da olanak tanımak için yapıldığını söylüyor. Üreticiler eklenebilir: Cloudflare CLI, SDK ve dokümantasyon üreticileriyle birlikte geliyor, ancak bir transformer eklenerek kütüphaneye özel bir paket ya da prensipte tam bir uygulama üretilebilir.

Öne çıkan bir özellik ise zincirleme (chaining); bir hedefin çıktısı diğerini besliyor. Cloudflare'ın özgün OpenAPI tanımı TypeScript SDK'sının içine gömülüyor ve bu da cf CLI ile Cap'n Web spesifikasyonlarını üretmek için kullanılıyor. Diğer üreticiler genellikle bu tür zincirleri sabit kodlar, örneğin bir Go SDK'sından CLI ve Terraform hedefleri türetilir; ancak Forge zincirin kontrolünü kullanıcıya veriyor. Bu, Cloudflare için önemli, çünkü kendi CLI'ları TypeScript ile yazılmış ve çoğu SDK üreticisi bu dilden zincirleme yapmıyor.

Yazıda belirtildiği üzere CLI'lar da SDK'lardan farklı davranıyor. cf dev ve cf build gibi API çağrısı arkası olmayan, elle yazılmış, yalnızca yerel komutlar içeriyorlar ve bunlar Vite gibi TypeScript paketlerini çağırıyor. Cloudflare, bu elle yazılmış komutların diğer her şeyin yanı sıra üretilen dokümantasyona geri katılmasını istiyor ve bugün bunu yapan mevcut bir araç olmadığını, bu nedenle bu yeteneği Forge'a inşa ettiğini söylüyor.

Agent'lar göz önünde bulundurularak geliştirildi

Cloudflare bu çabayı agent'ları müşteri olarak görmek çerçevesinde konumlandırıyor. CLI'lar, API SDK'ları, MCP sunucuları ve iyi dokümantasyon bir zamanlar yalnızca geliştirici ürünlerinin derdiydi; şirket ise bunların artık her ürün için temel gereklilik olduğunu savunuyor.

Cap'n Web tam bu noktada devreye giriyor. Cap'n Web, Cloudflare'ın RPC sistemidir ve TypeScript'in uzak bir API'yi sanki yerel bir yöntemmiş gibi çağırmasını, birden fazla çağrıyı tek bir istekte toplamasını sağlıyor. Forge, Cap'n Web binding'lerini doğrudan bir OpenAPI spesifikasyonundan üretebiliyor; bu da Cloudflare'a göre Workers'tan diğer API'lara binding üretmenin önünü açıyor, çünkü Workers runtime'ındaki binding'lerin kendileri de RPC yöntemleri ortaya koyan Workers'tır.

Aynı fikir daha geniş ekosisteme de uzanıyor: transformer'lar, hepsi gerçek API'ye göre doğrulanan TanStack Query binding'leri, Zod veya Valibot şemaları ya da MCP sunucuları üretebilir.

Sürüm planları

Forge ayrıca bir API sürümleme çabasının da temelini oluşturuyor. Cloudflare'ın v4 API'si on yıldır tek büyük sürümü oldu ve bu durum onu istikrarlı gösterse de şirket, SemVer kapsamında yeni büyük sürüm sayılacak değişiklikler yayınladığını, ayrıca ürünlerinden daha uzun ömürlü olan dahili v2 etiketleri ve beta etiketleri olduğunu kabul ediyor. Forge yol boyunca artifact'leri yayınladıkça Cloudflare, eski istemcileri veya SDK'ları bozmadan yeni büyük API sürümleri yayınlamaya doğru çalışıyor. TypeScript, Rust, Python, Go, PHP ve Terraform için yeni SDK'lar vaat ediliyor ve Cloudflare, Terraform geçişi konusunda özellikle özen göstereceğini taahhüt ediyor.

Neden önemli

Bugün üretilen SDK'lar ve dokümantasyon genellikle barındırılan SaaS araçlarıyla geliyor; Cloudflare'a göre bunlar kontrolü sizden alıyor ve ortadan kaybolabiliyor. Forge'un bahsi şu: üretim, testler gibi CI'da sahibi olduğunuz ve çalıştırdığınız temel bir altyapı olmalı; her pull request'te her artifact'ın tam bir önizleme build'i üretilmeli, API yüzeyi yüzlerce depoya yayılmış olsa bile. Pipeline genel geçerli olduğu kanıtlanırsa, hem Cloudflare hem de onu benimseyen herkes için hızla değişen API'lerle CLI'ları, SDK'ları, MCP sunucularını ve dokümantasyonu senkron tutmanın maliyetini ciddi biçimde düşürebilir.