Fetch APIの内部（リクエスト/レスポンスとボディストリーム）

fetch() は「URL を渡すと Promise が返る便利関数」に見えますが、その下には Fetch 標準が定義する厳密なオブジェクトモデルとアルゴリズムがあります。実務でぶつかる「レスポンスを 2 回読もうとして落ちる」「mode と credentials を混同して CORS で詰まる」「中断したつもりが通信が走り続ける」といった事故は、すべて内部設計を知れば予防できます。ここでは Request/Response の不変性、mode／credentials、ボディの一度きり消費、そして AbortController による中断を原理から見ていきます。

Request と Response は何が不変か

fetch(input, init) を呼ぶと、ブラウザはまず引数から Request オブジェクトを構築します。new Request(url, init) を自分で作って渡すこともでき、fetch は内部的に常にこの Request を経由します。Request と Response の重要な性質は、ボディ以外のメタデータが実質イミュータブルである点です。method・url・mode・credentials・headers などは、構築時に確定したら後から書き換えるための setter を持ちません。

const req = new Request('/api/items', { method: 'POST', mode: 'cors' });
req.method = 'GET';        // 黙って無視される（書き換わらない）
console.log(req.method);   // "POST"

// 変更したいときは「元を種にして新インスタンス」を作る
const req2 = new Request(req, { method: 'GET' });

この不変設計には理由があります。fetch は内部でリダイレクト追跡やリトライ、Service Worker による横取りなどで Request を複数回使い回す可能性があり、途中で属性が書き換わると取得アルゴリズムの一貫性が崩れます。だから「改変は新インスタンス」という関数型的な作法が標準で強制されています。例外は Headers オブジェクトで、これは append／set／delete を持つ可変コンテナですが、Request/Response にいったん紐づいた後はガードがかかり、種別によっては変更が拒否されます。

mode：同一オリジン制約と読めるレスポンス

mode は「このリクエストがクロスオリジン制約とどう向き合うか」を決める軸です。値は same-origin／cors／no-cors／navigate の 4 つ（navigate はブラウザのページ遷移用で、スクリプトからは通常指定しません）。前提として 同一オリジンポリシーとサイト分離の信頼境界 と CORS の仕組み を押さえておくと、各モードの意味がつながります。

fetch の既定 mode は cors です。クロスオリジンに cors で投げると、ブラウザはサーバーの Access-Control-Allow-Origin 等を検査し、許可されればレスポンスを読めます。一方 no-cors は「送るが読まない」ための特殊モードで、返るのは opaque レスポンスです。status は 0、ヘッダは空に見え、本文も読めません。<img> や <script> 相当の「副作用だけ欲しい」用途や、Service Worker が中身を見ずにキャッシュへ放り込む場合に使います。no-cors を「CORS エラーを消す呪文」と誤解して使うと、読めないレスポンスが返るだけで何も解決しません。

credentials：資格情報を送るかは別の軸

credentials は mode とは独立した別の軸で、Cookie・TLS クライアント証明書・HTTP 認証といった資格情報をリクエストに乗せ、レスポンスの Set-Cookie を反映するかを制御します。値は omit／same-origin／include の 3 つです。Cookie の挙動そのものは別記事に譲りますが、ここで重要なのは「mode: cors だから Cookie が飛ぶ」わけではない、という点です。

fetch の既定は same-origin です。したがってクロスオリジンの認証付き API を叩くときは、明示的に credentials: 'include' を指定しないと Cookie が送られません。さらにサーバー側も Access-Control-Allow-Credentials: true を返し、かつ Access-Control-Allow-Origin を * ではなく具体的なオリジンにする必要があります。クライアントの include とサーバーの 2 条件が揃って初めて、クロスオリジンで資格情報付きリクエストが成立します。

ボディは一度きり：bodyUsed とストリーム

Request/Response のボディは、内部的に ReadableStream です。ストリームは「一度流れたら戻れない」一方向のデータソースで、ここから Fetch API のもっとも有名な制約が生まれます。ボディは一度しか読めない――これがネットワークのバックプレッシャと省メモリを両立させる設計です。本文全体をメモリに溜め込まず、到着したチャンクから順に消費できる代わりに、巻き戻しはできません。

res.json()／res.text()／res.arrayBuffer()／res.blob()／res.formData() はいずれもストリームを最後まで読み切ってロックを掛ける操作です。一度どれかを呼ぶと内部フラグ bodyUsed が true になり、二度目の読み取りは TypeError で失敗します。

const res = await fetch('/api/data');
const a = await res.json();     // ストリームを読み切る → bodyUsed = true
const b = await res.json();     // TypeError: body stream already read

同じレスポンスを 2 通りに解釈したい、あるいは読みつつキャッシュにも保存したい場合は、読む前に clone() します。clone() はストリームを 2 本に分岐（tee）し、それぞれ独立に一度ずつ読めるようにします。ただし分岐した 2 本の消費速度が大きくずれると、速い側のために遅い側の未読チャンクをバッファし続けるため、メモリを食う点に注意します。

const res = await fetch('/api/data');
const forCache = res.clone();          // 読む前に分岐（tee）
await cache.put('/api/data', forCache); // 片方はキャッシュへ
const json = await res.json();          // もう片方はアプリで利用

低レベルに res.body（ReadableStream）へ直接アクセスし、getReader() で read() ループを回せば、チャンク到着のたびに処理できます。巨大ファイルの進捗表示や、サーバー送信のストリーミング応答（行区切り JSON など）を全体待ちせずに逐次処理する用途で効きます。

const res = await fetch('/large');
const reader = res.body.getReader();    // ストリームをロック
let received = 0;
while (true) {
  const { done, value } = await reader.read(); // value は Uint8Array チャンク
  if (done) break;
  received += value.length;             // 進捗を逐次更新できる
}

AbortController：中断の内部動作

fetch は途中でキャンセルする手段を引数に持たないため、中断は AbortController 経由で行います。仕組みはシグナル伝播です。コントローラの signal（AbortSignal）を fetch(url, { signal }) に渡しておき、controller.abort() を呼ぶと次の連鎖が起きます。

1. signal.aborted が true になり、signal 上で abort イベントが発火する。
2. fetch はこのイベントを内部で監視しており、進行中の取得処理を停止し、返した Promise を AbortError（DOMException） で reject する。
3. レスポンスボディの読み取り中であれば、その ReadableStream もエラーで閉じられ、read() ループは中断される。

const controller = new AbortController();
const t = setTimeout(() => controller.abort(), 5000); // 5秒でタイムアウト中断

try {
  const res = await fetch('/slow', { signal: controller.signal });
  const data = await res.json();
  clearTimeout(t);
} catch (e) {
  if (e.name === 'AbortError') {
    // 中断された（タイムアウト or ユーザー操作）。通信は実際に止まっている
  } else {
    throw e; // それ以外は本物のネットワーク/パースエラー
  }
}

ここで本質的なのは、abort() が単に Promise を捨てるのではなく、進行中のネットワーク取得そのものを止める点です。すでに送出済みのバイトは取り消せませんが、未受信のレスポンス受信は打ち切られ、リソースが解放されます。Promise.race で「遅い fetch を無視する」だけの実装は、裏で通信が走り続けて帯域とコネクションを浪費しますが、AbortController は実際に止めます。

AbortSignal は使い捨てである点も重要です。一度 abort 済みのシグナルは永続的に aborted のままなので、リトライのたびに新しい AbortController を作り直す必要があります。既に aborted なシグナルを fetch に渡すと、取得は始まる前に即 AbortError で reject されます。なお、よくある「N 秒でタイムアウト」は AbortSignal.timeout(ms) で簡潔に書け、複数シグナルの統合は AbortSignal.any([...]) で行えます。

イベントループとの関係

fetch が返す Promise や、ストリームの read() が返す Promise の解決は、すべて イベントループとマイクロタスク の上で進みます。ネットワーク完了やチャンク到着は内部的にタスクとしてキューに積まれ、その後の .then／await 継続はマイクロタスクとして処理されます。await res.json() が「一見ブロックしている」ように見えても、実体はストリーム読み取りの非同期継続がイベントループに乗っているだけで、その間メインスレッドは他のタスクを処理できます。中断時の AbortError reject も同じ仕組みで、abort イベント発火 → Promise reject → catch 継続というマイクロタスクの連鎖として観測されます。

まとめ