CORSプリフライトの判定アルゴリズムと単純リクエスト

CORS でいちばん混乱を生むのは「いつ OPTIONS が飛ぶのか」です。GET は素通りするのに JSON の POST だけ事前確認が走る、独自ヘッダを1つ足した途端に往復が増える――これらは気分やブラウザの機嫌ではなく、Fetch 標準が定める単純リクエスト（CORS-safelisted request）かどうかの厳密な判定で決まっています。ここではその判定アルゴリズムと、プリフライト発火後に走る Access-Control-* ヘッダの照合手続き、そして Access-Control-Max-Age によるキャッシュの効き方を、原理から正確に追います。前提となる仕組みは CORS（オリジン間リソース共有） と 同一オリジンポリシーとサイト分離の信頼境界 を押さえておくとつながります。

単純リクエストの厳密な条件

「単純リクエスト」は俗称で、標準では各条件の論理積で定義されます。次のすべてを満たすときだけ、リクエストは単純とみなされ、プリフライトを伴いません。

ここで言う CORS-safelisted ヘッダは、Accept・Accept-Language・Content-Language・Content-Type・Range（一部制約付き）など、ブラウザが昔から <form> 送信で付けてきた安全なヘッダの集合です。Authorization や X-Requested-With のような追加ヘッダは、たとえ1つでもこの集合の外なのでプリフライトを誘発します。

Content-Type には特に注意が要ります。safelisted と認められるのは値が application/x-www-form-urlencoded ・ multipart/form-data ・ text/plain のいずれかのときだけです。application/json はこの3種に含まれないため、JSON ボディの POST は他がすべて単純でも必ずプリフライトされます。「GET は通るのに POST だけ落ちる」の正体はほぼこれです。

プリフライト発火の境界

ブラウザは実際のリクエストを送る前に、内部で「このリクエストは単純か」を評価します。判定の擬似コードはおおむね次の形です。波括弧の集合は安全のためインラインコードで示します。

needsPreflight(req):
  if req.method not in {GET, HEAD, POST}: return true
  for h in req.headers:
    if h not in CORS_SAFELISTED: return true
  ct = req.headers["Content-Type"]
  if ct and parse(ct) not in
     {application/x-www-form-urlencoded, multipart/form-data, text/plain}:
    return true
  if req.usesReadableStreamBody or req.hasNonSafelistedSemantics: return true
  return false

この関数が true を返すと、ブラウザは本番リクエストの前に OPTIONS を1本送ります。重要なのは、この判定はクロスオリジンのときだけ意味を持つ点です。同一オリジンへの fetch では同一オリジンポリシーの制約自体がかからないため、needsPreflight の結果に関わらず OPTIONS は発生しません。プリフライトはあくまで「別オリジンに、単純でないリクエストを送ってよいか」をサーバーに事前確認する手続きです。

OPTIONS の中身と照合手続き

プリフライトの OPTIONS には本文がなく、代わりに「これから何を送りたいか」を申告するリクエストヘッダが乗ります。サーバーはこれを見て Access-Control-Allow-* で可否を返し、ブラウザがその応答を照合します。

OPTIONS /items/1 HTTP/1.1
Origin: https://app.example.com
Access-Control-Request-Method: PUT
Access-Control-Request-Headers: content-type, authorization

HTTP/1.1 204 No Content
Access-Control-Allow-Origin: https://app.example.com
Access-Control-Allow-Methods: GET, POST, PUT, DELETE
Access-Control-Allow-Headers: Content-Type, Authorization
Access-Control-Allow-Credentials: true
Access-Control-Max-Age: 600

ブラウザ側の照合アルゴリズムは次のように進みます。1つでも不成立なら本番には進まず、CORS エラーになります。

照合の細部にいくつか落とし穴があります。Access-Control-Request-Headers の値は小文字に正規化され、ソートされて送られます。サーバーが Allow-Headers で返す名前は大文字小文字を区別せず突き合わされますが、値そのものは省略できません。クライアントが申告したヘッダのうち1つでも Allow-Headers に欠けると照合は失敗します。また Allow-Methods / Allow-Headers には *（ワイルドカード）も使えますが、資格情報付きリクエストでは * は文字どおりの記号として扱われ、ワイルドカードの意味を失います。Cookie を送るなら具体名で列挙する必要があります。

Access-Control-Max-Age とキャッシュ

毎リクエストごとに OPTIONS を往復させると、レイテンシが単純に2倍近くになります。これを抑えるのが Access-Control-Max-Age で、プリフライト結果をプリフライトキャッシュに保持する秒数を指定します。キャッシュが有効な間、ブラウザは同じ条件のプリフライトを省略し、本番だけを送ります。

キャッシュのキーは「オリジン」「リクエスト URL」「メソッド」「申告ヘッダの集合」の組です。したがって URL が違えば別エントリですし、同じ URL でもメソッドやヘッダの組が変われば再びプリフライトが走ります。実務では「GET には OPTIONS が出ないのに、新しい独自ヘッダを足した瞬間に1回だけ OPTIONS が復活した」という挙動として観測されます。

プリフライトキャッシュは HTTP キャッシュ とは別物で、Cache-Control や中間プロキシのキャッシュとは独立にブラウザ内部で管理されます。エントリは資格情報モードごとにも分かれるため、credentials: 'include' の有無が違えば別キャッシュです。

実装側の最短経路

呼び出し側のコードからは、プリフライトの有無はほぼ自動で決まります。明示的に OPTIONS を書くことはなく、ブラウザが needsPreflight を評価して必要なら挿入します。

// JSON の PUT → Content-Type が application/json かつ PUT なので必ずプリフライト
const res = await fetch("https://api.example.com/items/1", {
  method: "PUT",
  headers: {
    "Content-Type": "application/json", // 3種の外 → 単純でない
    "Authorization": "Bearer ...",       // safelisted 外 → 単純でない
  },
  credentials: "include",                // Cookie を送るなら指定
  body: JSON.stringify({ name: "demo" }),
});

逆に、どうしてもプリフライトを避けたい局面（計測ビーコン等で往復を1回に抑えたい等）では、text/plain で送り独自ヘッダを付けないことで単純リクエストに収める設計が取れます。ただしサーバー側で本文を JSON として解釈する手当てが要り、可読性とのトレードオフになります。mode と credentials の独立した軸については Fetch API の内部 で詳しく扱っています。

まとめ