エッジ機能

エッジ関数は Kapsule のエッジネットワーク上で実行される小さな JavaScript ハンドラーで、リクエストがプロジェクトに到達する前に実行されます。これにより、アプリへのラウンドトリップなしにリダイレクト、ヘッダー注入、A/B ルーティング、ボットフィルタリングを実行できます。このガイドでは、エッジ関数の書き方、受け入れられるエントリーポイント形式、パスマッチング、複数の関数の相互作用、デプロイ、および関数が例外をスローした場合の動作について説明します。

どこに配置されるか

Orbit でプロジェクトを開き、Edge functions タブをクリックします。すべての関数はプロジェクトに属し、ステータスバッジ LIVE、PAUSED、NOT DEPLOYED、DEPLOY FAILED 付きでリストされます。

関数の作成

1. New function をクリックします。
2. Name に入力します（最大 120 文字）。
3. Path pattern に入力します。この関数が実行される URL パターンです。
4. Trigger を選択します。Request（オリジン前）、Response（オリジン後）、または Both。
5. Environment scope を選択します。All environments、Production only、または Preview only。
6. Function body にハンドラーを書き込みます。
7. Save をクリックして、Deploy to edge をクリックします。

request オブジェクトは常にスコープ内にあり、ソースは 64 KB に制限されます。

ハンドラーの書き方

エッジでリクエストに答えるために Response を返します。何も返さないか undefined を返すと、リクエストはプロジェクトにそのまま渡されます。

export default {
  async fetch(request) {
    const url = new URL(request.url)

    // Redirect /old to /new
    if (url.pathname === '/old') {
      return new Response(null, {
        status: 301,
        headers: { Location: '/new' },
      })
    }

    // Returning nothing passes through to the origin
  },
}

名前付き関数形式も機能します:

export default async function handler(request) {
  // Add a security header to every response
  const response = await fetch(request)
  const headers = new Headers(response.headers)
  headers.set('X-Frame-Options', 'DENY')
  return new Response(response.body, { status: response.status, headers })
}

サポートされているエントリーポイント形式

パスパターン

Path pattern は、どのリクエストが関数を実行するかを決定します。/ で始まる必要があり、最大 2048 文字まで可能です。* は任意の一連の文字にマッチし、? は単一の文字にマッチします。ワイルドカードのないパターンはそのパス自体とその下のすべてにマッチします。

request オブジェクト

request は標準的な Fetch API Request です。URL、メソッド、ヘッダー、ボディを読み取ることができます:

export default {
  async fetch(request) {
    const url    = new URL(request.url)
    const cookie = request.headers.get('cookie') ?? ''
    const ua     = request.headers.get('user-agent') ?? ''

    if (ua.includes('BadBot')) {
      return new Response('Forbidden', { status: 403 })
    }
  },
}

一般的なパターン

古い URL をリダイレクトする

export default {
  async fetch(request) {
    const url = new URL(request.url)
    const redirects = {
      '/old-about':   '/about',
      '/old-contact': '/contact',
    }
    const dest = redirects[url.pathname]
    if (dest) return Response.redirect(url.origin + dest, 301)
  },
}

単純なパスツーパスの移動が少数の場合は、代わりに組み込みのリダイレクトエンジンを使用してください。コードは必要なく、設定は Settings で行われます。Configuring Redirects and Rewrites を参照してください。

セキュリティヘッダーを追加する

export default async function handler(request) {
  const response = await fetch(request)
  const headers = new Headers(response.headers)
  headers.set('X-Frame-Options', 'DENY')
  headers.set('X-Content-Type-Options', 'nosniff')
  headers.set('Referrer-Policy', 'strict-origin-when-cross-origin')
  return new Response(response.body, {
    status: response.status,
    statusText: response.statusText,
    headers,
  })
}

静的なヘッダールールではコードも必要ありません。Settings には、HSTS、CSP、no-embed、no-sniff、referrer policy、CORS のクイック追加プリセット付きのレスポンスヘッダーセクションがあります。

A/B ルーティング

export default {
  async fetch(request) {
    const url     = new URL(request.url)
    const variant = Math.random() < 0.5 ? 'a' : 'b'
    url.searchParams.set('variant', variant)
    return fetch(url.toString(), request)
  },
}

環境スコープ

複数の関数の相互作用

プロジェクトのすべての有効な関数は、作成順に評価されます。各リクエストに対して、エッジはリストを調べて、パスパターンがリクエストパスにマッチし、スコープが環境をカバーしている最初の関数を実行します。

• その関数が Response を返す場合、それが送信され、評価は停止します。
• 何も返さない場合、評価は次のマッチング関数に続きます。
• どれもが Response を返さない場合、リクエストはプロジェクトに通常どおり送信されます。

つまり、早期に作成された広い /* 関数は、Response を返す場合、後で作成されたより狭い関数をシャドウできます。特定のものを最初に作成するか、広いものが処理しないパスには何も返さないようにしてください。

デプロイ

Deploy to edge をクリックします。デプロイは、現在のデータベースの状態からエッジネットワーク全体の単一の結合ルーターを再生成するため、関数を有効化、無効化、編集、または削除するとすべてが再公開されます。変更は通常数秒以内に有効になります。

各関数行は Deploy log を保持し、最後のデプロイのステップを表示し、失敗した場合はエラーが表示される DEPLOY FAILED バッジを持ちます。

Pause は関数を削除せずにルーターから外すため、動作が不安定な関数をバックアウトする最速の方法です。Resume はそれを戻します。

関数が例外をスロー した場合

関数内の例外はエッジでキャッチされます。エラーはログされ、リクエストは関数が何も返さなかった場合と同じようにプロジェクトにフォールスルーします。

制限事項

• プロジェクトあたり最大 20 個の関数。21 番目は却下されます。
• 関数あたり最大 64 KB のソース。
• 名前は最大 120 文字、パスパターンは最大 2048 文字です。

関連読資料

• Configuring Redirects and Rewrites, パスルールのノーコードオプション
• Deploying Your Project
• Branch Preview Deployments in Orbit 本番環境に到達する前に関数をテストするため