SDK, CLI, 문서 등을 생성하는 오픈 소스 파이프라인 Forge를 소개합니다

오늘 우리는 Forge를 소개합니다. SDK, CLI, 문서, 라이브러리를 생성하는 새로운 접근 방식입니다. Forge는 누구나 무료로 배포하고 실행할 수 있는 오픈 소스 플러그형 생성 파이프라인입니다.

Forge는 아직 초기 단계이지만 이미 cf CLI에 필요한 출력을 생성하고 있으며, 앞으로 몇 달 안에 Cloudflare의 API 문서, SDK 등 더 많은 영역을 지원할 예정입니다.

우리는 에이전트를 고객으로 대하기 위해 우리 스스로 Forge가 필요했기 때문에 이를 구축했습니다. 이제 누구나 에이전트에 필요한 모든 인터페이스를 생성할 수 있어야 한다고 생각해 Forge를 오픈 소스로 공개합니다. 예전에는 개발자 제품에만 CLI, API SDK, MCP 서버와 그에 맞는 훌륭한 문서가 필요했습니다. 이제는 모든 제품의 기본 요건입니다.

우리 API는 기존 생성기의 한계를 넘어섰습니다

Cloudflare API에는 3,500개가 넘는 작업이 있으며, 이러한 API를 지원하는 수백 개 서비스는 Rust, Go, TypeScript, Python 등 다양한 언어로 작성되어 있습니다. SDK와 API 문서를 포함해 전체 Cloudflare API를 위한 CLI를 구축하기 시작하면서, 이 규모를 처리할 수 있는 코드 생성 파이프라인이 필요했습니다. 이 파이프라인은 다양한 언어와 각 엔지니어링 팀의 작업 방식에 맞출 수 있을 만큼 유연해야 합니다.

팀 간 조정 오버헤드를 줄일 방법도 필요했습니다. Cloudflare 제품 팀이 API를 변경할 때는 변경 사항을 병합하고 고객에게 배포하기 전에, 생성될 Cloudflare 전체 CLI, SDK, 문서 사이트의 미리 보기 빌드를 사용할 수 있어야 합니다. 실수로 생성 파이프라인을 깨뜨리지 않았는지 확인할 방법이 필요했습니다. 또한 Cap‘n Web부터 MCP를 넘어 더 많은 것을 생성하도록 확장할 수 있는 시스템이 필요했습니다.

우리는 이 문제를 해결하려는 여러 호스팅 제품을 사용해 봤고, 일부는 프로덕션에서도 사용했습니다. 하지만 어느 것도 우리 문제를 해결하지 못했고, 아예 서비스를 종료한 제품도 있었습니다. 한 팀이 생성 파이프라인을 의도치 않게 깨뜨리는 변경 사항을 병합하면 다른 팀이 출시 시점에야 이를 발견하곤 했습니다. 우리는 통제할 수 없는 호스팅 도구를 거슬러 올라가며 팀과 공급업체 사이의 변경 사항을 조정하는 데 너무 많은 시간을 썼습니다.

그렇게 Forge를 만들기 시작했습니다.

Forge는 이 모든 문제 해결을 목표로 합니다. AI 코드 검토 도구와 테스트 파이프라인처럼 각 팀의 API 리포지토리에서 CI로 실행됩니다. 모든 변경 사항을 린트 검사한 뒤, 설치해 테스트할 수 있도록 여러분의 변경 사항만 강조된 CLI, 문서, SDK의 미리 보기 빌드를 생성합니다. 이는 Workers Previews와 같은 발상입니다. 모든 변경 사항에 완전한 미리 보기 빌드를 제공하되, 수백 개 서비스와 리포지토리에 API 범위가 분산된 경우까지 포함해 대규모 SDK 생성에 적용합니다. 이것이 Forge가 제공하려는 기능입니다.

Forge 변환기는 Cap’n Web을 포함해 무엇이든 생성할 수 있습니다

Cloudflare에는 일반적인 언어 타깃을 훨씬 넘어서는 생성기가 필요한 이유가 특히 많습니다. Cap’n Web은 TypeScript가 로컬 메서드를 호출하듯 원격 API를 호출할 수 있게 하는 Cloudflare의 RPC 시스템입니다:

// 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를 사용하면 OpenAPI 사양에서 Cap’n Web을 직접 생성할 수 있습니다. 이를 통해 Workers에서 다른 API로 연결되는 바인딩을 생성할 수 있습니다. 결국 Workers 런타임의 바인딩은 RPC 메서드를 노출하는 Workers로 구현됩니다.

이는 Cap’n Web에만 해당하는 이야기가 아닙니다. 이미 사용하고 있을 수 있는 다른 인기 도구에도 같은 기능이 필요합니다. TanStack Query를 사용한다면, 애플리케이션의 API 자체에서 직접 빌드되는 TanStack Query 바인딩을 생성할 수 있는 것이 이상적입니다. 항상 최신 상태를 유지하고, 항상 실제 API를 기준으로 검증할 수 있습니다. API를 더 쉽게 사용할 수 있게 하는 Zod 또는 Valibot 스키마, MCP 서버, 그 밖의 무엇을 생성하든 마찬가지입니다.

이것이 가능한 이유는 Forge 코드 생성기가 유연하기 때문입니다. 한 출력의 정보를 다른 출력으로 이어 전달할 수 있도록 설계되어 있습니다.

Forge 변환기는 체이닝할 수 있습니다: 다른 출력에서 새 출력 생성

우리는 Forge를 플러그형으로 설계해 다양한 입력 및 출력 형식을 지원하도록 했습니다. Forge는 CLI, SDK, 문서 생성기를 제공하지만, 라이브러리별 패키지나 전체 대시보드 또는 애플리케이션까지 생성하는 변환기를 추가하는 것을 막는 것은 없습니다. 현재 Forge는 OpenAPI를 입력 형식으로 지원하며, 향후 AsyncAPI, GraphQL, Cap’n Proto, Protobuf 등의 입력 형식도 허용할 수 있도록 설계했습니다.

이는 단순한 호환성 이상의 의미가 있습니다. 한 타깃의 출력을 사용해 다른 출력을 만드는 방식으로 타깃을 체이닝할 수 있습니다. CLI와 Terraform 타깃을 Go SDK에서 생성하는 다른 생성기에서는 흔한 방식입니다. 하지만 빠져 있는 것은, 그리고 Forge가 제공하는 것은, 사용자가 이 체이닝 시스템을 직접 제어할 수 있는 방법입니다.

우리에게도 이 문제를 해결할 방법이 필요했습니다. 자체 cf CLI가 TypeScript로 작성되어 있는데, 다른 SDK 생성기는 일반적으로 CLI를 만들 때 TypeScript에서 체이닝하지 않기 때문입니다. 하지만 우리 상황을 통해 더 근본적인 문제를 깨달았습니다. 왜 SDK 생성 도구가 여러분 대신 이런 결정을 해야 할까요? 여러분이 Python을 주로 쓰는 조직이고 CLI도 Python으로 만들고 싶을 수 있습니다.

“그런데 Python인지 아닌지가 무슨 상관이지? 코드는 자동 생성되는데.”라고 생각하신다면, 그 이유는 CLI가 다르기 때문입니다. CLI에는 SDK에는 맞지 않는 로컬 전용 동작이 들어가는 경우가 많습니다. 이런 동작은 본질적으로 API 호출을 기반으로 하지 않기 때문에 직접 작성합니다. 예를 들어 cf CLI에는 나머지 생성 출력 위에 추가되는 cf dev, cf build 같은 명령이 있습니다. 이러한 명령은 Vite와 같은 다른 패키지의 TypeScript API를 호출해야 합니다. 

이제 문서까지 함께 생각해 보겠습니다. CLI와 문서를 OpenAPI 사양만으로 전적으로 생성한다면, 직접 작성한 명령을 문서에 다시 반영해 나머지 명령과 함께 문서화하려면 어떻게 해야 할까요?

현재 이런 기능을 제공하는 기존 도구를 찾지 못했지만, cf에는 정확히 이 기능이 필요합니다. 그래서 Forge에 이를 구축하고 있습니다.

사용자에게 영향을 주지 않고 API를 변경하세요

Forge는 더 나은 API 버전 관리도 가능하게 해 줍니다. Cloudflare의 v4 API는 10년 동안 우리 API의 유일한 메이저 버전이었습니다. 그동안 새로운 메이저 버전을 출시하지 않은 것처럼 보이지만, SemVer 정의에 따르면 새 메이저 버전이 필요할 만한 변경을 꽤 많이 해 왔습니다. 동시에 API 전반의 여러 작업에는 제품 수명 주기에서 해당 단계가 끝난 지 오래인데도 내부 ‘v2’ 태그나 ‘beta’ 식별자가 남아 있습니다.

v4 API를 오랫동안 운영해 온 우리는 새로운 대규모 v5가 많은 고객을 뒤에 남겨둘 수 있다는 점을 잘 알고 있습니다. 그래서 Forge가 중간중간 아티팩트를 릴리스하는 방식과 함께, 기존 클라이언트나 SDK를 깨뜨리지 않고 새로운 메이저 API 버전을 출시할 수 있는 API 버전 관리 접근 방식을 개발하고 있습니다.

곧 TypeScript, Rust, Python, Go, PHP, Terraform을 포함한 SDK에 관해 더 많은 내용을 공유하겠습니다. 특히 Terraform입니다. Terraform 공급자를 업그레이드할 때는 그만큼의 엄격함과 주의가 필요하다는 것을 알고 있으며, Terraform 전환에는 특별히 더 세심하게 접근하겠습니다.

핵심 도구는 모두에게 열려 있어야 합니다

우리는 API용 도구를 구축하는 것이 인터넷의 핵심 부분이며, SaaS 제품 없이도 그런 작업을 할 수 있어야 한다고 생각합니다. 여러분은 자신의 SDK, CLI, 문서를 소유해야 합니다. 그리고 직접 생성한다면 원하는 곳에서 원하는 방식으로 무료로 사용할 수 있어야 합니다.

그래서 우리는 Forge를 오픈 소스로 공개하고 허용 범위가 넓은 Apache 2.0 라이선스로 제공합니다. 사람들이 이 여정에 우리와 함께하고 기여하기를 바랍니다.

아니어도 괜찮습니다. 모든 것을 혼자 보관하고 싶을 수도 있습니다. 그렇게 하세요! Forge는 어떤 목적으로든 커스텀 수정과 함께 비공개로 무료 실행할 수 있습니다.

감사의 말: 이 프로젝트는 Dan Carter, Steven Chong, Krishna Paritala, Shelley Jones의 설계 및 구현 노력 덕분에도 가능했습니다.