Edge Workers の概要とクイックスタート

Edge Workers は、CDN のエッジノードで実行される JavaScript 関数です。リクエストがエッジに到達してセキュリティチェックを通過すると、ルートに一致する Worker が、キャッシュ検索およびオリジンへのリクエスト送信より前に実行されます。Worker では、次のことができます。

• 直接応答: オリジンにアクセスせず、カスタムコンテンツやリダイレクトを返します。
• オリジンへのリクエストの書き換え: リクエストヘッダーを追加・上書きし（必要に応じてメソッドとパスも変更）、その後オリジンに転送します。
• パススルー: 何も変更せず、ドメインの通常の設定でリクエストを処理します。

プログラミングモデルは Cloudflare Workers に準拠しています。export default { fetch(request, env, ctx) } をエクスポートし、Response を返します。実行ごとに新しい独立したサンドボックスが使用されます。リクエスト間でグローバル状態は共有されません。

#コンソールのページ

#クイックスタート

#ステップ1: Worker を作成する

1. CDN → Workers を開き、右上の Worker を作成 をクリックします。
2. 必須の 名前 と、任意の 説明 を入力します。
3. テンプレートから開始 ドロップダウンからサンプルを選択すると、エディターに読み込めます。カスタム応答、リダイレクト、認証トークン、暗号ツール、fetch パススルーなどのサンプルがあります。または、以下の例を貼り付けます。
4. 有効化 スイッチがオンになっていることを確認し、保存更改 をクリックします。

保存後、エディターに Worker の詳細ページが開き、上部にバージョン番号が表示されます。新しいコードを保存するたびに、バージョンが1つ上がります。

#ステップ2: コードを記述する

この最小限の例では、/hello に対してエッジから JSON を返します。それ以外のパスは、通常どおりオリジンに転送されます。

export default {
  async fetch(request, env, ctx) {
    // request.url may be "/hello?x=1" or a full URL, so extract the path
    const path = request.url.replace(/^https?:\/\/[^\/]+/, "").split("?")[0];

    if (path === "/hello") {
      return Response.json({
        message: "Hello from the edge",
        host: request.headers.get("host"),
        method: request.method,
      });
    }

    // Not handled here: pass through to the origin
    return { action: "continue" };
  },
};

#ステップ3: ドメインに紐付ける

1. CDN → CDN ドメイン を開き、ドメインを選択して Worker タブに切り替えます。
2. 関連付けを追加 をクリックします。ダイアログで次を設定します。
   • Worker を選択: 作成した Worker を選択します。有効な Workers のみが表示されます。
   • ルーティングモード: たとえば /hello、またはすべてのパスを対象にする場合は /* を指定します。ルールは後述します。
   • 優先度: 0～999。数値が大きいほど優先されます。
   • 有効化: オンのままにします。
3. 保存 をクリックします。設定は自動でエッジに配信され、通常はまもなく反映されます。

#ステップ4: テストする

curl -i https://www.example.com/hello

上記の JSON とともに 200 が返れば、Worker は稼働しています。他のパスは、紐付けを追加する前と同じように動作するはずです。

#プログラミングインターフェース

#エントリーポイント

推奨する形式は export default { fetch(request, env, ctx) { ... } } です。fetch は通常の関数でも async 関数でも構いません。プラットフォームは export default function (request) {} と、グローバルな function handler(request) {} にも対応しています。

#リクエストオブジェクト

#戻り値

たとえば、次の Worker は、オリジンへのリクエストに A/B バケットを示すヘッダーを付与します。

export default {
  fetch(request) {
    const cookie = request.headers.get("cookie") || "";
    const m = /ab_bucket=(A|B)/.exec(cookie);
    const bucket = m ? m[1] : (Math.random() < 0.5 ? "A" : "B");
    return { action: "rewrite", headers: { "x-ab-bucket": bucket } };
  },
};

#利用可能なグローバル

• fetch(url, init): パブリックな HTTP/HTTPS アドレスにサブリクエストを送信し、status、ok、headers、text()、json() を持つ Promise<Response> を返します。return fetch(url) で結果をクライアントに直接返せます。
• Headers、Request、Response、TextEncoder / TextDecoder、btoa / atob。
• crypto.subtle.digest、crypto.subtle.importKey / sign / verify (HMAC)、crypto.getRandomValues、crypto.randomUUID、および16進数文字列を返すヘルパーの crypto.md5()、crypto.sha1()、crypto.sha256()、crypto.hmac()。

サブリクエストの制限:

• ポート80と443への http/https のみ利用できます。
• プライベート、ループバック、リンクローカルのアドレスは常に拒否されます。
• リダイレクトは最大3回まで追跡します。各サブリクエストは10秒でタイムアウトし、応答本文の上限は 8 MiB です。

#ルートパターン

ルートパターンは、ホスト名やクエリ文字列を除いた、リクエストのパスのみと照合されます。パス全体に一致する必要があります。

• * は、/ を含む任意の文字列に一致するため、複数のディレクトリ階層にまたがって一致します。** も * と同じ動作です。
• ? は任意の1文字に一致します。
• 空のパターン、*、/* はすべてのパスに一致します。

1つのリクエストで実行される Worker は最大1つです。 複数の紐付けが一致する場合、優先度が最も高いものだけが実行されます。重複する紐付けには、異なる優先度を設定してください。

#リソース制限

#エラーとデバッグ

Worker が例外をスローした場合、構文エラーがある場合、タイムアウトした場合、制限を超えた場合、プラットフォームはフェイルオープンで動作します。Worker が紐付けられていない場合と同様に、リクエストはオリジンへ転送され、エラーページは表示されません。期待した結果が得られない場合は、まずコードが正しく動作するか確認してください。

#有効化・無効化・削除

• Workers 一覧で Worker を 無効化 すると、すべてのドメインで実行が停止します。ドメインの Worker タブで、個別の紐付けのみを無効にすることもできます。
• Worker を削除すると、紐付けられていたすべてのドメインで実行が停止します。
• 新しいコードを保存すると、その Worker に紐付けられたすべてのドメインが自動で更新されます。

#プランと上限

ドメインあたりの Worker ルート（紐付け）の数は、そのドメインに紐付けられた CDN プランによって異なります。執筆時点では、CDN Starter、Professional、Enterprise プランはいずれもドメインあたり5件まで利用できます。最新の値はプランページを参照してください。上限に達すると、コンソールに「Worker ルートの上限に達しました」という通知が表示されます。さらに追加するには、プランをアップグレードするか、既存の紐付けを削除してください。

#API による Workers の管理

コンソールの各操作は、ユーザー API 呼び出しに対応しています。Authorization: Bearer <token> ヘッダーにログイントークンを指定して認証します。

# Create a Worker (include an "id" field to update an existing one)
curl -X POST https://api.yeap.cloud/api/user/cdn/workers/save \
  -H "Authorization: Bearer <token>" -H "Content-Type: application/json" \
  -d '{"name":"hello","code":"export default { fetch(){ return new Response(\"hi\"); } };","enabled":true}'

# Bind it to a domain
curl -X POST https://api.yeap.cloud/api/user/cdn/domains/www.example.com/workers/save \
  -H "Authorization: Bearer <token>" -H "Content-Type: application/json" \
  -d '{"worker_id":123,"route_pattern":"/hello","priority":10,"enabled":true}'

その他のエンドポイント:

• Workers: GET /api/user/cdn/workers（一覧）、GET /api/user/cdn/workers/detail?id=（コードを含む詳細）、POST /api/user/cdn/workers/toggle、DELETE /api/user/cdn/workers/delete（JSON 本文 {"id":...}）。
• ドメインの紐付け: GET /api/user/cdn/domains/<domain>/workers、POST .../workers/toggle、DELETE .../workers/delete。

#現在対応していない機能

• リクエスト本文の読み取り。
• コンソールでの Worker の環境変数や KV の設定（env は空のオブジェクトです）。
• オリジンが返した応答の変更。「応答ヘッダーの書き換え」テンプレートは現在機能しません。応答ヘッダーを追加するには、ドメインのルール機能を使用してください。
• ctx.waitUntil() に渡すバックグラウンド処理。応答の送信後に実行される保証はありません。
• 実行ログとオンラインデバッグ。