vtex-io-service-paths-and-cdn

VTEX IO サービスパスと CDN の動作

このスキルを使う場面

VTEX IO バックエンドの service.json ルートを定義または変更し、そのエンドポイントのデータに応じて、エッジ（CDN）が適切な Cookieを転送し、適切なキャッシュを適用する必要がある場合に、このスキルを使います。

• ルートのパスプレフィックスとして、public、segment（/_v/segment/...）、private（/_v/private/...）のどれを選ぶか
• HTTP レスポンスに Cache-Control（および関連ヘッダー）を設定し、public キャッシュの動作をデータの範囲（匿名ユーザー、セグメント、認証済みの購入者）に合わせる方法
• ルートが vtex_session または vtex_segment Cookie を受け取らない理由の説明
• Cookie が見つからない場合の CloudFront またはエッジの動作のトラブルシューティング（公式のトラブルシューティングを参照）

次の場合は、このスキルを使わないでください。

• アプリケーションレベルの LRU キャッシュ、VBase、または stale-while-revalidate のオーケストレーション → vtex-io-application-performance を使用
• GraphQL フィールドレベルの @cacheControl のみ → このスキルと併せて vtex-io-graphql-api を使用

判断ルール

• パスは service.json の routes の下で宣言します。選択したプレフィックス（/yourPath、/_v/segment/yourPath、/_v/private/yourPath）によって、Cookie の転送と、VTEX がエッジでサービスレスポンスをキャッシュできるかどうかが決まります。Service path patterns の表を参照してください。
• Public（{yourPath}）：アプリがリクエスト Cookie を受け取る保証はありません。可能な場合、エッジはレスポンスをキャッシュすることがあります。購入者間で共有しても安全な静的な参照データなど、ユーザー固有ではないデータに使用します。
• Segment（/_v/segment/{yourPath}）：アプリは vtex_segment を受け取ります。エッジはセグメントごとにキャッシュします。通貨、地域、販売チャネルなど、レスポンスがセグメントには依存するものの、認証済みのユーザー ID には依存しない場合に使用します。
• Private（/_v/private/{yourPath}）：アプリは vtex_segment と vtex_session を受け取ります。エッジはサービスレスポンスをキャッシュしません。注文、住所、プロフィールなど、ユーザー ID またはセッションに紐づくデータに使用します。
• レスポンスの Cache-Control は、データの分類と整合させる必要があります。契約上明示的に設計されている場合（不変の公開アセットなど）を除き、秘密情報、ユーザーごとのデータ、または認可の判断を含むペイロードに対して、CDN／共有キャッシュを指示してはいけません。判断に迷う場合は、private パスを選択し、購入者固有の JSON には no-store または private のキャッシュディレクティブを使用してください。
• Cookie とパス、セッションの関係については、Sessions System overview を読んでください。

厳守事項

制約：private または認証スコープのペイロードに public パスやセグメントキャッシュされるパスを使用しない

認証済み購入者のデータ、PII、または認可に関わる JSON を返すルートで、public パスや、あるユーザーのデータを別のユーザーに提供する可能性があるエッジキャッシュレスポンスに依存してはいけません。

重要な理由 — エッジは、想定するセッションコンテキストなしにキャッシュまたはルーティングすることがあります。データの分類を誤ると、ユーザー間またはセグメント間で情報が漏えいする可能性があります。

検出方法 — public パス配下のルートが、注文履歴、住所、トークン、またはアカウント固有のフィールドを返している場合。または、そのようなペイロードに対して Cache-Control が長期間の public キャッシュを示している場合。

正しい方法 — ルートに /_v/private/...（または vtex_session を受け取るパターン）を使用し、適切な Cache-Control を設定します（キャッシュできない JSON API には private, no-store など）。注：パスプレフィックス（/_v/private/）は CDN と Cookie の動作を制御します。一方、"public": true フィールドは、ルートの呼び出しに VTEX 認証トークンが必要かどうかを制御します。この2つは相互に独立しています。

{
  "routes": {
    "myOrders": {
      "path": "/_v/private/my-app/orders",
      "public": true
    }
  }
}

誤り — GET /my-app/orders を、/_v/private/ または /_v/segment/ のプレフィックスがない public パスとして公開し、ブラウザーのセッションが常にサービスから見えると想定して、ユーザーごとの JSON を返すこと。

推奨パターン

1. パスのプレフィックスを選ぶ前に、レスポンスを（匿名、セグメント、認証済み）に分類します。
2. Service path patternsに従って、public／segment／privateに割り当てます。
3. プラットフォームが対応している場合は、レスポンスヘッダーを明示的に設定します。分類（public immutable、private、no-store）と**Cache-Control**を一致させます。
4. セキュリティまたはコンプライアンス上、privateに保つ必要があるパスは文書化し、ストアフロントやBFFが誤ってリンクキャッシュしないようにします。

よくある失敗パターン

• publicルートでCookieを前提にする — publicパスでは、サービスがvtex_sessionを確実に受け取れるとは限らず、ID処理が断続的に失敗します。
• パーソナライズされたJSONをエッジでキャッシュする — ユーザー固有のレスポンスに、privateパスと適切なキャッシュポリシーを設定せず、長いmax-ageを指定します。
• 異なる関心事を混在させる — 1つのルートがpublicなカタログデータとprivateなアカウントデータの両方を返します。エンドポイントを分けるか、privateにしてサーバー側で認証チェックを行います。
• セグメントを無視する — 通貨またはセグメントによって異なる価格やプロモーションがpublicパスで提供され、誤ったセグメント向けにキャッシュされます。

レビューチェックリスト

• 各ルートのパスプレフィックス（public／/_v/segment／/_v/private）は、公式の表にあるCookieとキャッシュ動作に基づいて適切に選ばれていますか？
• 購入者固有または認証に関するレスポンスのルートは、private（または他の方法で保護）になっており、不適切にエッジキャッシュ可能な状態になっていませんか？
• Cache-Control（および関連）ヘッダーは、データの機密性と一致していますか？
• クライアントからの並列呼び出しでは、ペイロードの種類ごとに正しいパスを使用していますか？

関連スキル

• vtex-io-application-performance — アプリケーションのパフォーマンス（LRU、VBase、AppSettings、並列フェッチ、テナントキー）
• vtex-io-service-apps — service.jsonとServiceエントリー
• vtex-io-graphql-api — GraphQLキャッシュと@cacheControl
• headless-caching-strategy — ストアフロント／BFFのキャッシュ

参考資料

• Service path patterns — パス形式、Cookie、キャッシュ、ユースケース
• Sessions System overview — vtex_segment、vtex_session、セッションの動作
• App Development — VTEX IOアプリ開発ハブ
• VTEX IO Engineering guidelines — スケーラビリティとIO開発のプラクティス