wattanx I am a cat.

h3 v2 で変わるリクエストとレスポンスの扱い

2026/11/15

wattanx

はじめに

Nitro v3 では、HTTP リクエストの処理を担う h3 が v2 に変わります。

この記事では、h3 v1 から v2 へ移行するときに確認したい、リクエストとレスポンスの扱いを整理します。

Web 標準の API を基盤にした入出力

h3 v1 も複数の JavaScript ランタイムに対応していました。v1 では event.node.req / event.node.res という Node.js のリクエスト・レスポンスを中心に扱い、Node.js の HTTP API を使えない環境では node-mock-http で互換オブジェクトを用意していました。

h3 v2 は Request、Response、Headers、URL など、Web 標準の API を基盤としています。ハンドラーは event.req(Request)からリクエストを読み取り、h3 はハンドラーが返した値を Response に変換します。Node.js 上では、srvx が Node.js の HTTP API と Web 標準の API の間を変換します。

リクエストの読み方とレスポンスの返し方

h3 v2 のハンドラーでは、リクエストの情報を event.req から読み取り、レスポンスのステータスやヘッダーを event.res に設定します。

たとえば、h3 v1 でヘッダー操作のヘルパーを使っていたコードは、v2 では Headers の API で書けます。

// h3 v1
import { defineEventHandler, getHeader, setHeader } from "h3";

export default defineEventHandler((event) => {
  const language = getHeader(event, "accept-language");
  setHeader(event, "x-example", "h3");

  return { language };
});
// h3 v2
import { defineHandler } from "h3";

export default defineHandler((event) => {
  const language = event.req.headers.get("accept-language");
  event.res.headers.set("x-example", "h3");

  return { language };
});

getHeader / setHeader / appendHeader や defineEventHandler は、v2 でも非推奨の API として残っているため、すぐに動かなくなるわけではありません。新しいコードでは、上の例のように event.req.headers / event.res.headers と defineHandler を使います。

リクエストを読む

event.req は Web 標準の Request です。ヘッダーと同じく、メソッドも Request の API で読み取ります。URL は、Web 標準の URL である event.url から読み取ります。クエリパラメータや body は、v1 と同じく getQuery や readBody で読み取れます。

たとえば、メソッド、パス、クエリパラメータ、JSON の body を読むコードは次のようになります。

// h3 v1
import { defineEventHandler, getQuery, readBody } from "h3";

export default defineEventHandler(async (event) => {
  const method = event.method;
  const path = event.path;
  const page = getQuery(event).page;
  const body = await readBody(event);

  return { method, path, page, body };
});
// h3 v2
import { defineHandler, getQuery, readBody } from "h3";

export default defineHandler(async (event) => {
  const method = event.req.method;
  const path = event.url.pathname + event.url.search;
  const page = getQuery(event).page;
  const body = await readBody(event);

  return { method, path, page, body };
});
  • メソッド: event.method の代わりに event.req.method
  • パス: event.path の代わりに event.url.pathname + event.url.search

レスポンスを返す

event.res は、最終的なレスポンスに反映するステータスやヘッダーを準備しておくためのオブジェクトです。v1 の event.node.res(Node.js の ServerResponse)とは違い、write() や end() は持っていません。

v1 では、次のように event.node.res へレスポンスを直接書き込むこともできました。

// h3 v1
import { defineEventHandler } from "h3";

export default defineEventHandler((event) => {
  event.node.res.statusCode = 200;
  event.node.res.setHeader("content-type", "text/plain");
  event.node.res.write("Hello, ");
  event.node.res.end("h3!");
});

v2 では、文字列やオブジェクトを返す場合、ステータスとヘッダーを event.res に設定し、body はハンドラーから return します。h3 は、返り値と event.res に設定した内容から Response を作ります。Response を返す場合やエラーを throw する場合の書き方は、「ステータスとヘッダーを書く場所」で説明します。

// h3 v2
import { defineHandler } from "h3";

export default defineHandler((event) => {
  event.res.status = 200;
  event.res.headers.set("content-type", "text/plain");

  return "Hello, h3!";
});

write() を何度も呼んで少しずつ送っていた処理は、ReadableStream を作って return する形に書き換えます。上の v1 の例と同じく、"Hello, " と "h3!" を2回に分けて送る場合は次のようになります。

// h3 v2
import { defineHandler } from "h3";

export default defineHandler((event) => {
  event.res.headers.set("content-type", "text/plain");

  const encoder = new TextEncoder();
  const stream = new ReadableStream({
    start(controller) {
      controller.enqueue(encoder.encode("Hello, "));
      controller.enqueue(encoder.encode("h3!"));
      controller.close();
    },
  });

  return stream;
});

controller.enqueue() に渡したデータが、v1 の write() で書き込んでいたチャンクにあたります。controller.close() でストリームを閉じると、レスポンスが終了します。

v1 の send* も、値や Response を return する形に書き換えます(基本的には非推奨で、一部の API は削除されているため)。置き換え先は、Response Handling - H3 を参照してください。

たとえば、リダイレクトは sendRedirect(event, ...) から次のように変更します。

// h3 v2
import { defineHandler, redirect } from "h3";

export default defineHandler(() => {
  return redirect("/new-page", 302);
});

Node.js の API が必要な場合

event.node.req / event.node.res は非推奨です。Node.js 固有の API が必要な場合は、event.runtime.node から req / res を参照します。どちらも Node.js 上で動かしている場合にだけ使えます。

エラーの返し方とヘッダーを書く場所

v2 では、エラーはハンドラーから throw で返します。また、ステータスやヘッダーを書く場所は、ハンドラーが返す値によって変わります。

HTTPError でエラーを返す

エラーには HTTPError を使います。createError も非推奨として残っていますが、新しいコードでは new HTTPError(...) を使います。

// h3 v2
import { defineHandler, HTTPError } from "h3";

export default defineHandler(() => {
  throw new HTTPError({
    status: 404,
    statusText: "Not Found",
    message: "The requested article does not exist.",
  });
});

推奨されるフィールド名は status / statusText です。v2 でも statusCode / statusMessage は非推奨として受け付けますが、新しいコードでは status / statusText を使います。

statusText は HTTP レスポンスのステータスに添える短いテキストです。ドキュメントでは最大 512〜1024 文字とされており、詳しい説明はレスポンス body の message に書きます。

HTTPError 以外のエラーは、unhandled なエラーとして扱われます。unhandled なエラーでは、セキュリティのため、JSON レスポンスに含まれる message / data / body / stack の詳細が隠されます(Unhandled Errors - H3)。

ステータスとヘッダーを書く場所

h3 のドキュメントでは、ハンドラーが返す値によって、ステータスやヘッダーを書く場所を使い分けることを勧めています。

返す値ステータスとヘッダーを書く場所
文字列やオブジェクトevent.res.status / event.res.headers
Response返す Response
エラー(throw)new HTTPError({ status, headers })

Response を返す場合は、ヘッダーも Response に直接書きます。event.res.headers に値があると、h3 は返された Response をそのまま使わず、ヘッダーをマージした新しい Response を作り直すためです。

// h3 v2
import { defineHandler } from "h3";

export default defineHandler(() => {
  return new Response("Hello, h3!", {
    headers: {
      "content-type": "text/plain",
      "cache-control": "no-store",
    },
  });
});

全部 Response にまとめたほうがわかりやすくないかと思ってましたが、h3 では次の理由から、すべてのハンドラーで Response を返す形にはしにくくなっています。

  • h3 のユーティリティは event.res に書き込みます。たとえば handleCors は、CORS のヘッダーを event.res.headers に設定します。ハンドラーが Response を返しても、こうしたヘッダーとのマージは起こります。
  • Node.js 上では、送信の処理が増えます。文字列を返すと body を 1 回で書き出せますが、ネイティブの Response を返すと body を ReadableStream から読み出しながら書き出します(「Web の Response を Node.js の ServerResponse へ書き出す」を参照)。
  • エラーは HTTPError を throw して返します。ステータスが 400 以上の Response を返しても、h3 はエラーとして扱わないため、onError などのエラー処理は呼ばれません。

event.res と返す値が重なった場合

event.res に設定した値と、ハンドラーが返す値が重なった場合は、次のように扱われます。

  • Response をそのまま返すと、event.res.status に設定したステータスは捨てられ、返した Response のステータスが使われます。ヘッダーはマージされ、同じ名前のヘッダーは event.res.headers に設定したほうが優先されます。ただし、set-cookie は上書きせず追加されます(h3 の mergeHeaders のソースコード)。
  • 返した Response のステータスが 400 以上の場合は、event.res.headers ではなく、event.res.errHeaders に設定したヘッダーだけがマージされます。
  • エラーを throw すると、event.res.status と event.res.headers に設定した値は捨てられます。エラー時に付けたいヘッダーは、new HTTPError({ headers }) か event.res.errHeaders で指定します。

たとえば、成功時はキャッシュさせ、エラー時はキャッシュさせないように、event.res.headers と event.res.errHeaders に別々の値を設定してからエラーを throw するとします。

// h3 v2
import { defineHandler, HTTPError } from "h3";

export default defineHandler((event) => {
  event.res.headers.set("cache-control", "max-age=60");
  event.res.errHeaders.set("cache-control", "no-store");

  throw new HTTPError({
    status: 404,
    message: "The requested article does not exist.",
  });
});

このレスポンスの cache-control は、event.res.headers の max-age=60 ではなく、event.res.errHeaders の no-store になります。

ただし、エラーのレスポンスに付けるヘッダーは new HTTPError({ headers }) で指定するのが基本で、errHeaders は CORS のヘッダーのように、エラーになるかどうかがわかる前に付けておきたいヘッダーのための最終手段です。h3 の handleCors も、CORS のヘッダーを event.res.headers と event.res.errHeaders の両方に設定しています(h3 の setCorsHeaders のソースコード)。

srvx が Node.js の HTTP API を Web 標準の API につなぐ仕組み

h3 v2 のアプリは、Web 標準の Request を受け取って Response を返す app.fetch() を持っています。event.req は、app.fetch() に引数として渡された Request です。ハンドラーが返した値は、h3 が Response に変換し、app.fetch() の戻り値として返します。

しかし、Node.js の node:http では、リクエストとレスポンスの扱い方が異なります。createServer() に渡したハンドラーは、リクエストを IncomingMessage(req)として受け取り、レスポンスは ServerResponse(res)に書き込んで送信します。

// node:http
import { createServer } from "node:http";

createServer((req, res) => {
  // req(IncomingMessage)からリクエストを読む
  console.log(req.method, req.url);

  // res(ServerResponse)にステータスとヘッダーを書き込む
  res.writeHead(200, { "content-type": "text/plain" });

  // body を書き込み、レスポンスを終える
  res.write("Hello, node:http!");
  res.end();
}).listen(3000);

node:http が Request を渡したり、Response を受け取って送信したりするわけではありません。では、Node.js 上で h3 を動かすとき、IncomingMessage から Request を作り、返した Response を送信しているのは誰でしょうか。

この間をつないでいるのが srvx です。Node.js 上で h3 を動かすときに使う serve() や toNodeHandler() は、内部で srvx を使っています。srvx は Node.js の入出力にアダプターを挟み、ハンドラーを Request を受け取って Response を返す形で実行します。

たとえば toNodeHandler() は、h3 のアプリを createServer() に渡せる (req, res) のハンドラーで包みます。

// h3 v2
import { createServer } from "node:http";
import { H3, toNodeHandler } from "h3";

const app = new H3().get("/", () => "Hello, h3!");

createServer(toNodeHandler(app)).listen(3000);

serve() を使う場合は、この createServer() の呼び出しも srvx が行います。

toNodeHandler() が返すハンドラーの中身をコードで表すと、次のようになります。これは srvx v1.0.8 の実装をもとに、型やエラー処理などを省いた疑似コードです。

function toNodeHandler(fetchHandler) {
  // createServer() に渡す (req, res) のハンドラーを返す
  return async (nodeReq, nodeRes) => {
    // Node.js のリクエストを Web Request として扱う
    const request = new NodeRequest({ req: nodeReq, res: nodeRes });

    // h3 の app.fetch() などが Web Response を返す
    const response = await fetchHandler(request);

    // Web Response の内容を Node.js のレスポンスへ書き出す
    await sendNodeResponse(nodeRes, response);
  };
}

Node.js のリクエストを NodeRequest で包む

NodeRequest は元の IncomingMessage を保持し、getter やメソッドを通して Web 標準の API を提供します。必要な値を参照した時点で処理することで、変換にかかるコストを抑えています。

NodeRequest外側は Web 標準の Request、中身は元の req
req元のまま保持している
IncomingMessagenode:http の req
methodPOST
url/api/users
headers
hostlocalhost:3000
content-typeapplication/json
読み取りストリーム{"name":"wattanx"}
Web 標準の API
url"http://localhost:3000/api/users"
headers.get("content-type")"application/json"
bodyReadableStream
json(){ name: "wattanx" }
Node.js の HTTP サーバーが受け取ったリクエスト。これが IncomingMessage(req)
  • request.headers.get(name) は、通常は元の req.headers から値を読みます。ヘッダー名の大文字・小文字や重複などを処理し、必要に応じてネイティブの Headers を生成します。
  • request.url は、Node.js 側のパスやホストなどの情報から完全な URL を組み立てます。
  • request.body にアクセスすると、Node.js の読み取りストリームを Readable.toWeb() で Web の ReadableStream として扱えるようにします。
  • request.json() には、body を直接読み取って JSON.parse() する経路もあります。ストリームやネイティブの Request がすでに作られている場合は、そちらを使います。

Node.js 上で動かす場合、event.req の実体はこの NodeRequest です。NodeRequest が Request と同じ API を持っているので、アプリケーション側は Node.js 上でも event.req.headers.get() や event.req.json() と書けます。その内側で、srvx が IncomingMessage からデータを取り出しています。

Web の Response を Node.js の ServerResponse へ書き出す

ハンドラーから返った Response は、srvx の sendNodeResponse が Node.js の res に書き出します。ステータスとヘッダーは writeHead() に渡し、body は形式によって書き出し方が変わります。

ハンドラーが文字列や Buffer を返した場合、h3 は srvx の FastResponse を作ります。FastResponse は Response と同じ API を持つクラスで、Node.js 上では body を元の文字列や Buffer のまま持ちます。そのため srvx は、res.write("Hello, h3!") のように 1 回で書き出して end() します。

ハンドラーが ReadableStream やネイティブの Response を返した場合、body は ReadableStream なので、srvx はチャンクを読み取って res.write() に渡します。res.write() が false を返したら、drain イベントを待ってから次のチャンクを読みます。これがバックプレッシャーへの対応です。最後に res.end() で終了します。

バックプレッシャーとは?

バックプレッシャーとは、データを処理する側のペースに合わせて、送り込む量や速さを抑える仕組みです。

クライアントがデータを読まずに受信バッファが埋まると、TCP のフロー制御によってサーバーの OS は送信を止めます。すると、Node.js の書き込みバッファに送信待ちのデータがたまっていきます。res.write() は、このたまった量がしきい値(highWaterMark)を超えると false を返します。

この srvx の処理では、res.write() が false なら次のチャンクを読まず、drain を待って再開します。ここでの false は書き込み失敗ではなく、「追加を待って」という合図です。渡したチャンク自体はバッファに入っていて、捨てられたわけではありません。

Responseハンドラーが返した Web の Response
status200
content-typetext/plain
body: ReadableStreamchunk1chunk2chunk3
まだ読み取っていない
ハンドラーが返した Response を、Node.js の res へ書き出します
ServerResponsenode:http の res
送信バッファ送信が進むと減る
highWaterMark
res.writeHead(200, headers)
res.write(chunk1)→ true
res.write(chunk2)→ true
'drain' を待っている
res.write(chunk3)→ true
res.end()
受信側

まとめ

h3 v1 から v2 への主な書き換えをまとめると、次のようになります。

対象h3 v1h3 v2
リクエストヘッダーgetHeader(event, name)event.req.headers.get(name)
レスポンスヘッダーsetHeader(event, name, value) / appendHeader(event, name, value)event.res.headers.set(name, value) / event.res.headers.append(name, value)
URLevent.pathevent.url.pathname + event.url.search
メソッドevent.methodevent.req.method
レスポンスsend(event, value) / sendStream(event, stream) など値、Response、ストリームを return
エラーcreateError(...) / sendError(event, error)throw new HTTPError(...)
Node.js 固有の APIevent.node.req / event.node.resevent.runtime.node.req / event.runtime.node.res(Node.js 上でのみ使用)

h3 v2 のハンドラーは、Web 標準の Request を読み、値や Response を返す形で書きます。ステータスやヘッダーは、返す値に合わせて event.res、返す Response、HTTPError のいずれかに設定します。

Node.js 上では、srvx が IncomingMessage を NodeRequest で包んで event.req として渡し、返した Response を ServerResponse へ書き出します。Node.js の API との変換を srvx が受け持つので、アプリケーションのコードは実行環境によらず同じ書き方になります。

参考リンク