JA EN
shiichan

Cloudflare TypeScript SDK v6.0.0、まさかの Retry-After 挙動チェンジ！

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

こんにちは、しぃちゃんだよ！今日は Cloudflare の開発者まわりからちょっと重めのニュースを見つけたから紹介するね。地味に見えるけど、中身は盛りだくさんなアップデートだよ。

Cloudflare Changelog developers.cloudflare.com

なにが発表されたの？

Cloudflare の Changelog で、公式 TypeScript SDK のメジャーバージョン v6.0.0 のリリースが発表されたよ。v5.x 系からのメジャーアップグレードで、11 個の完全新規トップレベル API リソースの追加、50 以上の既存リソースへの新しいサブリソース・メソッドの追加、そして SDK 内部の挙動を変える複数の破壊的変更が含まれているの。

今までどうだったの？

v5.x 系の SDK には、地味に困る挙動がいくつかあったみたい。

  • レート制限にかかったとき、サーバーが返す Retry-After の値が 60 秒を超えていると SDK 側で無視されて、代わりに SDK 標準のバックオフ処理が使われていた
  • content-length: 0 の空レスポンスに対しても、SDK は律儀に body のパースを試みていた
  • 環境変数が空文字列(例: CLOUDFLARE_API_TOKEN="")でも、SDK はそれを「値が設定されている」として扱っていた

どれも一見小さな挙動だけど、レート制限からの復帰タイミングがずれたり、空レスポンスのパースで想定外のエラーが出たり、空の認証トークンをそのまま送ってしまったりと、実運用ではハマりどころになっていた部分だよ。

これで何が変わるの？

v6.0.0 では、この辺りの挙動がまとめて修正されたの。

  • サーバーが返す Retry-After の値を、60 秒を超えていてもそのまま尊重するように変更。レート制限からの復帰がより正確になるよ
  • content-length: 0 のレスポンスは body のパースを試みず、undefined を返すように変更
  • 空文字列の環境変数は「未設定」として扱われるようになった(意図せず空のトークンで API を叩いてしまう事故を防げる)

さらに、AI Search や Realtime Kit、Organizations といった 11 個の新しいトップレベルリソースが丸ごと使えるようになったから、これまで SDK 経由では触れなかった機能にもアクセスできるようになるよ。ただし v5.x からのアップグレードでは、17 個の HTTP エンドポイント削除やメソッドのシグネチャ変更もあるから、そのまま差し替えるとビルドが壊れる可能性があるので要注意なの。

深く潜ってみよう

新しく追加された 11 個のトップレベルリソースはこれだよ。

  • client.realtimeKit — Realtime Kit API、54 メソッド
  • client.aiSearch — AI Search のインスタンス・名前空間・トークン管理、46 メソッド
  • client.vulnerabilityScanner — 脆弱性スキャン関連、21 メソッド
  • client.tokenValidation — トークン検証ルール、13 メソッド
  • client.r2DataCatalog — R2 Data Catalog、11 メソッド
  • client.resourceTagging — リソースタグ付け、9 メソッド
  • client.organizations — 組織プロフィール・監査ログなど、8 メソッド
  • client.emailSending — メール送信エンドポイント、7 メソッド
  • client.connectivity — ディレクトリサービス API、5 メソッド
  • client.googleTagGateway — Google Tag Gateway 管理、2 メソッド
  • client.fraud — 不正検知 API、2 メソッド

削除された 17 個の HTTP エンドポイントは、abuse-reports・cloudforce-one・dlp/profiles/predefined・email-security/investigate・email-security/settings・intel/ip-list といったリソースに影響しているから、これらを使っているコードは移行前に必ずチェックが必要だよ。

メソッドのシグネチャも一部変わっていて、たとえば次のように引数の渡し方が変更されたところがあるの。

// v5.x
client.ai.toMarkdown.transform(file, { ...params });

// v6.0.0
client.ai.toMarkdown.transform({ ...params });

パス名の改称も入っていて、client.originTLSClientAuth.hostnames.certificates は client.originTLSClientAuth.zoneCertificates に、client.radar.netflows は client.radar.netFlows に変わったよ。あわせて 179 件の戻り値型変更(削除系メソッドが null 中心の型に変わったもの 133 件、ページネーション型の変更 17 件、命名変更 29 件)と、43 個の型の削除・統合も入っているみたい。

まとめ

  • Cloudflare TypeScript SDK が v6.0.0 にメジャーアップデート
  • Retry-After を 60 秒超でも尊重するように変更、空レスポンスは undefined を返すように変更、空文字列の環境変数は未設定扱いに変更
  • 17 個の HTTP エンドポイントが削除され、abuse-reports や email-security 関連などに影響
  • AI Search・Realtime Kit・Organizations など 11 個の新規トップレベルリソースが追加
  • メソッドのシグネチャ変更やパス名の改称もあり、179 件の戻り値型変更を含む

Cloudflare の API を TypeScript や JavaScript から触っている開発者は、アップグレード前に破壊的変更のリストを一度見比べておくのがおすすめだよ。特に Retry-After の挙動に自前で対処してたコードは、要チェックだね。

関連記事