gateway-workers

Gateway Workers

Worker を実装する前に、現在のForward ガイドを確認してください。このガイドでは、Gateway が許可された HTTP トラフィックで Worker を呼び出す方法を定義しています。セットアップ、API ペイロード、制限を記憶に頼ってプロジェクトにコピーするのではなく、以下の該当ページを参照してください。

ワークフロー

1. 既存の Worker を調査し、必要な変換、合成レスポンス、またはバックグラウンドタスクに適したWorker テンプレートを選択します。
2. cloudflare:workers からインポートした WorkerEntrypoint を継承する、名前付きの GatewayMiddleware クラスをエクスポートします。handle(request, context, next) を実装し、Response を返します。Gateway は RPC を通じてこのメソッドを呼び出します。デフォルトの fetch() ハンドラーだけでは、Forward の契約を実装したことにはなりません。
3. TypeScript の場合は、選択したテンプレートに記載されている現在のパッケージのインストール方法と型のインポート手順に従ってください。
4. 2 番目の引数をGateway コンテキストに使用します。このコンテキストは元のリクエストを記述し、Worker がリクエストを変更しても変わりません。これを this.ctx（Workers の実行コンテキスト）および this.env（バインディング）と混同しないでください。
5. next(request) を最大 1 回呼び出してユーザーのリクエストを続行するか、呼び出さずに合成レスポンスを返します。next() は常に元の宛先を対象とします。宛先の URL またはホストを変更しても無視され、リダイレクト、再試行、ファンアウトには使用できません。別の宛先にリクエストを送信するには fetch() を使用してください。これにより独立したサブリクエストが作成され、ユーザーの Gateway ポリシーやエグレス設定は継承されません。

コンテキスト

公開されている型とコンテキストのリファレンスを使用して、フィールド名と利用可否を確認してください。偽の値となるアイデンティティ（!identity）は匿名として扱い、任意のポスチャ値にはガードを設けてください。await context.identity() または await context.devicePosture() は必要な場合にのみ呼び出してください。どちらのゲッターも拒否されることがあります。取得時の失敗と値の欠落を個別に捕捉し、Worker がそれらに依存する場合の処理を決定してください。クライアントが指定したアイデンティティヘッダーではなく、Gateway が提供するアイデンティティを使用してください。

Gateway の動作

• 最初に一致した Forward ポリシーのみが Worker を呼び出します。Worker が呼び出されたことは、ボディの検査が成功したことを意味しません。Forward ガイドの検査順序に従ってください。
• Gateway は合成レスポンスを含む最終レスポンスを検査します。変更されたリクエストのバイト列は、オリジンに到達する前に再検査されません。
• トラフィックを選択する前に、Forward ガイドの制限を確認してください。HTTPS には復号が必要です。WebSocket は Worker を迂回し、一致した Workers VPC トラフィックは破棄されます。Worker の呼び出しに失敗した場合は、フェイルクローズになります。

検証

インストール済みの Gateway 型に対して型チェックを行い、名前付き RPC エントリーポイントをテストしてください。継続呼び出しが 0 回または 1 回であることと、Worker が使用するコンテキスト値をテストに含めます。次に、スコープを限定した Gateway Forward ポリシーを通じて、許可されたリクエストをテストしてください。デフォルトの fetch() ハンドラーへの直接リクエストでは、Gateway 経由の経路は検証できません。選択したテンプレートのテスト手順と、Forward ガイドのトラブルシューティング手順に従ってください。

レスポンスとストリーミングのルールを確認してください。最終ステータスは 200 から 599 の範囲で返し、HEAD リクエストまたはステータス 204、205、304 の場合はボディを返さず、ボディはバッファリングせずにストリーミングしてください。

関連スキル

• cloudflare-one：ゲートウェイポリシーの設計、トラフィック経路、ID、TLS、ロールアウト。
• workers-best-practices：ストリーミング、バインディング、生成される環境型、バックグラウンド処理、可観測性、ランタイムテスト。
• CLI の選択：プロジェクトのセットアップとデプロイには、既存の cf-cli または wrangler スキルを選択します。