JA EN
shiichan

Forge 誕生！API 定義から SDK・CLI・ドキュメントを作る Cloudflare 発 OSS パイプライン

Cloudflare Blog ★★★★ Markdown で見る
#cloudflare#devops#infrastructure

みんな、しぃちゃんだよ！今日は Cloudflare の中で使われていた生成ツールが、オープンソースになったよ。

Cloudflare Blog blog.cloudflare.com

なにが発表されたの？

Cloudflare の Blog で、Forge が紹介されたよ。Forge は、API 定義から SDK・CLI・ドキュメント・ライブラリなどを自動生成する、プラグイン式のオープンソースパイプラインで、CI の中で動くの。ライセンスは Apache 2.0 だよ。

今までどうだったの？

Cloudflare の API は 3,500 以上のオペレーションがあって、Rust・Go・TypeScript・Python で書かれた多数のサービスにまたがっているの。既存のホスト型の生成ツールでは、何百ものリポジトリにわたる変更の調整や、リリース前のパイプラインの破損防止が難しかったんだって。チーム間の調整コストを減らして、API の変更をプレビュービルドで確かめる方法が必要だったそうだよ。

これで何が変わるの？

生成の仕組みを個々のチームのリポジトリ側に移すことで、開発者向けツールが常に API 定義と同期されるようになるよ。

深く潜ってみよう

Forge の特徴はこれだよ。

  • プラグイン式: 入力は今のところ OpenAPI。AsyncAPI、GraphQL、Cap'n Proto、Protobuf への対応も予定されている
  • Transformer の連鎖: ある生成物を別の生成物の入力にできる。たとえば TypeScript の CLI は SDK から生成され、それが Cap'n Web の仕様やドキュメントにもつながる
  • Cap'n Web 連携: OpenAPI の仕様から Cloudflare の RPC システムを生成する。TypeScript からリモート API をローカルのメソッドのように呼べて、リクエストは 1 回のネットワーク呼び出しにまとめられる
  • プレビュービルド: Workers Previews と同じ考え方で、PR ごとに変更部分だけを目立たせた完全なプレビュービルドを作る。生成パイプラインの失敗を早めに見つけられる

今後は、v4 API が 10 年続いたあとで、既存クライアントを壊さない API バージョニングを Forge で実現する計画もあるよ。近く出る SDK は、TypeScript、Rust、Python、Go、PHP、Terraform で、とくに Terraform プロバイダーの移行に注意を払うそうなの。

まとめ

  • API 定義から SDK・CLI・ドキュメントを生成する OSS パイプライン、Apache 2.0
  • 3,500 以上のオペレーションを扱う課題から生まれた
  • 生成を各チームの CI に移し、PR ごとにプレビュービルドを作る
  • 入力は OpenAPI で、ほかの形式も今後対応予定

SDK や CLI の生成・保守に悩んでいる API 提供側の人に刺さる話だよ！

関連記事