iDoc.dev

日本語

English
简体中文
Español
Français
Português
Deutsch
Italiano
한국어
Русский
العربية

日本語

English
简体中文
Español
Français
Português
Deutsch
Italiano
한국어
Русский
العربية

テーマ

HTTP/2 ​

[履歴]

バージョン変更点
v15.0.0host ヘッダー（:authority の有無に関わらず）を持つリクエストの送受信が可能になりました。
v15.3.0, v14.17.0AbortSignal でリクエストを中断できるようになりました。
v10.10.0HTTP/2 が安定版になりました。以前は実験的でした。
v8.4.0追加: v8.4.0

[安定版: 2 - 安定]

安定版: 2 安定性: 2 - 安定

ソースコード: lib/http2.js

node:http2 モジュールは、HTTP/2 プロトコルの実装を提供します。以下を使用してアクセスできます。

js
const http2 = require('node:http2');

crypto サポートが利用できない場合の判断 ​

Node.js は、node:crypto モジュールのサポートを含めずにビルドされる可能性があります。そのような場合、node:http2 から import しようとしたり、require('node:http2') を呼び出そうとすると、エラーがスローされます。

CommonJS を使用する場合、スローされたエラーは try/catch を使用してキャッチできます。

js
let http2;
try {
  http2 = require('node:http2');
} catch (err) {
  console.error('http2 のサポートは無効です！');
}

字句 ESM import キーワードを使用する場合、エラーは、モジュールをロードする試行を行う 前 に process.on('uncaughtException') のハンドラーが登録されている場合にのみキャッチできます（たとえば、プリロードモジュールを使用）。

ESM を使用する場合、コードが crypto サポートが有効になっていない Node.js のビルドで実行される可能性がある場合は、字句 import キーワードの代わりに import() 関数を使用することを検討してください。

js
let http2;
try {
  http2 = await import('node:http2');
} catch (err) {
  console.error('http2 のサポートは無効です！');
}

コア API ​

コア API は、HTTP/2 プロトコルの機能をサポートするために特別に設計された低レベルのインターフェイスを提供します。既存の HTTP/1 モジュール API との互換性は 意図されていません。ただし、互換性 API は互換性があります。

http2 コア API は、http API よりもクライアントとサーバーの間で非常に対称的です。たとえば、'error'、'connect'、'stream' などのほとんどのイベントは、クライアント側のコードまたはサーバー側のコードのいずれかによって発生する可能性があります。

サーバー側の例 ​

以下は、Core API を使用したシンプルな HTTP/2 サーバーを示しています。暗号化されていない HTTP/2をサポートするブラウザーは知られていないため、ブラウザーのクライアントと通信する場合は、http2.createSecureServer() の使用が必須です。

js
import { createSecureServer } from 'node:http2';
import { readFileSync } from 'node:fs';

const server = createSecureServer({
  key: readFileSync('localhost-privkey.pem'),
  cert: readFileSync('localhost-cert.pem'),
});

server.on('error', (err) => console.error(err));

server.on('stream', (stream, headers) => {
  // stream is a Duplex
  stream.respond({
    'content-type': 'text/html; charset=utf-8',
    ':status': 200,
  });
  stream.end('<h1>Hello World</h1>');
});

server.listen(8443);
js
const http2 = require('node:http2');
const fs = require('node:fs');

const server = http2.createSecureServer({
  key: fs.readFileSync('localhost-privkey.pem'),
  cert: fs.readFileSync('localhost-cert.pem'),
});
server.on('error', (err) => console.error(err));

server.on('stream', (stream, headers) => {
  // stream is a Duplex
  stream.respond({
    'content-type': 'text/html; charset=utf-8',
    ':status': 200,
  });
  stream.end('<h1>Hello World</h1>');
});

server.listen(8443);

この例の証明書と鍵を生成するには、以下を実行します。

bash
openssl req -x509 -newkey rsa:2048 -nodes -sha256 -subj '/CN=localhost' \
  -keyout localhost-privkey.pem -out localhost-cert.pem

クライアント側の例 ​

以下は、HTTP/2 クライアントを示しています。

js
import { connect } from 'node:http2';
import { readFileSync } from 'node:fs';

const client = connect('https://localhost:8443', {
  ca: readFileSync('localhost-cert.pem'),
});
client.on('error', (err) => console.error(err));

const req = client.request({ ':path': '/' });

req.on('response', (headers, flags) => {
  for (const name in headers) {
    console.log(`${name}: ${headers[name]}`);
  }
});

req.setEncoding('utf8');
let data = '';
req.on('data', (chunk) => { data += chunk; });
req.on('end', () => {
  console.log(`\n${data}`);
  client.close();
});
req.end();
js
const http2 = require('node:http2');
const fs = require('node:fs');

const client = http2.connect('https://localhost:8443', {
  ca: fs.readFileSync('localhost-cert.pem'),
});
client.on('error', (err) => console.error(err));

const req = client.request({ ':path': '/' });

req.on('response', (headers, flags) => {
  for (const name in headers) {
    console.log(`${name}: ${headers[name]}`);
  }
});

req.setEncoding('utf8');
let data = '';
req.on('data', (chunk) => { data += chunk; });
req.on('end', () => {
  console.log(`\n${data}`);
  client.close();
});
req.end();

クラス: Http2Session ​

追加: v8.4.0

http2.Http2Session クラスのインスタンスは、HTTP/2 クライアントとサーバー間のアクティブな通信セッションを表します。このクラスのインスタンスは、ユーザーコードによって直接構築されることを意図していません。

各 Http2Session インスタンスは、サーバーまたはクライアントとして動作しているかどうかに応じて、わずかに異なる動作を示します。http2session.type プロパティを使用して、Http2Session が動作しているモードを判断できます。サーバー側では、ユーザーコードが Http2Session オブジェクトを直接操作する機会はほとんどなく、通常、ほとんどのアクションは Http2Server または Http2Stream オブジェクトとのやり取りを通じて行われます。

ユーザーコードは Http2Session インスタンスを直接作成しません。サーバー側の Http2Session インスタンスは、新しい HTTP/2 接続が受信されると、Http2Server インスタンスによって作成されます。クライアント側の Http2Session インスタンスは、http2.connect() メソッドを使用して作成されます。

Http2Session とソケット ​

すべての Http2Session インスタンスは、作成時に正確に 1 つの net.Socket または tls.TLSSocket に関連付けられています。Socket または Http2Session のいずれかが破棄されると、両方とも破棄されます。

HTTP/2 プロトコルによって課せられる特定のシリアライズおよび処理要件のため、ユーザーコードが Http2Session にバインドされた Socket インスタンスからデータを読み取ったり、データを書き込んだりすることはお勧めしません。そうすることで、HTTP/2 セッションが不定状態になり、セッションとソケットが使用できなくなる可能性があります。

Socket が Http2Session にバインドされたら、ユーザーコードは Http2Session の API のみに依存する必要があります。

イベント: 'close' ​

追加: v8.4.0

'close' イベントは、Http2Session が破棄されると発生します。リスナーは引数を想定していません。

イベント: 'connect' ​

追加: v8.4.0

'connect' イベントは、Http2Session がリモートピアに正常に接続され、通信を開始できると発生します。

ユーザーコードは通常、このイベントを直接リッスンしません。

イベント: 'error' ​

追加: v8.4.0

'error' イベントは、Http2Session の処理中にエラーが発生したときに発生します。

イベント: 'frameError' ​

追加: v8.4.0

  • type <integer> フレームタイプ。
  • code <integer> エラーコード。
  • id <integer> ストリーム ID (またはフレームがストリームに関連付けられていない場合は 0)。

'frameError' イベントは、セッションでフレームを送信しようとしたときにエラーが発生した場合に発生します。送信できなかったフレームが特定の Http2Stream に関連付けられている場合、Http2Stream で 'frameError' イベントを発生させる試みが行われます。

'frameError' イベントがストリームに関連付けられている場合、ストリームは 'frameError' イベントの直後に閉じられ、破棄されます。イベントがストリームに関連付けられていない場合、Http2Session は 'frameError' イベントの直後にシャットダウンされます。

イベント: 'goaway' ​

追加: v8.4.0

  • errorCode <number> GOAWAY フレームで指定された HTTP/2 エラーコード。
  • lastStreamID <number> リモートピアが正常に処理した最後のストリームの ID (または ID が指定されていない場合は 0)。
  • opaqueData <Buffer> 追加の不透明なデータが GOAWAY フレームに含まれている場合は、そのデータを含む Buffer インスタンスが渡されます。

'goaway' イベントは、GOAWAY フレームを受信したときに発生します。

Http2Session インスタンスは、'goaway' イベントが発生すると自動的にシャットダウンされます。

Event: 'localSettings' ​

追加: v8.4.0

'localSettings'イベントは、確認応答SETTINGSフレームが受信されたときに発行されます。

新しい設定を送信するためにhttp2session.settings()を使用する場合、変更された設定は'localSettings'イベントが発行されるまで有効になりません。

js
session.settings({ enablePush: false });

session.on('localSettings', (settings) => {
  /* Use the new settings */
});

Event: 'ping' ​

追加: v10.12.0

  • payload <Buffer> PINGフレームの8バイトのペイロード

'ping'イベントは、接続されたピアからPINGフレームが受信されるたびに発行されます。

Event: 'remoteSettings' ​

追加: v8.4.0

'remoteSettings'イベントは、新しいSETTINGSフレームが接続されたピアから受信されたときに発行されます。

js
session.on('remoteSettings', (settings) => {
  /* Use the new settings */
});

Event: 'stream' ​

追加: v8.4.0

'stream'イベントは、新しいHttp2Streamが作成されたときに発行されます。

js
session.on('stream', (stream, headers, flags) => {
  const method = headers[':method'];
  const path = headers[':path'];
  // ...
  stream.respond({
    ':status': 200,
    'content-type': 'text/plain; charset=utf-8',
  });
  stream.write('hello ');
  stream.end('world');
});

サーバー側では、通常、ユーザーコードはこのイベントを直接リッスンしません。代わりに、以下の例のように、http2.createServer()およびhttp2.createSecureServer()によって返されるnet.Serverまたはtls.Serverインスタンスによって発行される'stream'イベントのハンドラーを登録します。

js
import { createServer } from 'node:http2';

// 暗号化されていないHTTP/2サーバーを作成
const server = createServer();

server.on('stream', (stream, headers) => {
  stream.respond({
    'content-type': 'text/html; charset=utf-8',
    ':status': 200,
  });
  stream.on('error', (error) => console.error(error));
  stream.end('<h1>Hello World</h1>');
});

server.listen(8000);
js
const http2 = require('node:http2');

// 暗号化されていないHTTP/2サーバーを作成
const server = http2.createServer();

server.on('stream', (stream, headers) => {
  stream.respond({
    'content-type': 'text/html; charset=utf-8',
    ':status': 200,
  });
  stream.on('error', (error) => console.error(error));
  stream.end('<h1>Hello World</h1>');
});

server.listen(8000);

HTTP/2ストリームとネットワークソケットは1対1の対応関係にはありませんが、ネットワークエラーは個々のストリームを破棄し、上記のようにストリームレベルで処理する必要があります。

イベント: 'timeout' ​

追加: v8.4.0

http2session.setTimeout() メソッドを使用してこの Http2Session のタイムアウト期間を設定した後、設定されたミリ秒数が経過しても Http2Session でアクティビティがない場合、'timeout' イベントが発生します。リスナーは引数を期待しません。

js
session.setTimeout(2000);
session.on('timeout', () => { /* .. */ });

http2session.alpnProtocol ​

追加: v9.4.0

Http2Session がまだソケットに接続されていない場合、値は undefined になります。Http2Session が TLSSocket に接続されていない場合は h2c になり、接続された TLSSocket 自身の alpnProtocol プロパティの値を返します。

http2session.close([callback]) ​

追加: v9.4.0

Http2Session を正常に閉じます。既存のストリームが独自に完了することを許可し、新しい Http2Stream インスタンスが作成されないようにします。閉じられると、オープンな Http2Stream インスタンスがない場合、http2session.destroy() が呼び出される 可能性があります。

指定された場合、callback 関数は 'close' イベントのハンドラーとして登録されます。

http2session.closed ​

追加: v9.4.0

この Http2Session インスタンスが閉じられている場合は true、そうでない場合は false になります。

http2session.connecting ​

追加: v10.0.0

この Http2Session インスタンスがまだ接続中の場合は true になり、connect イベントの発生前および/または http2.connect コールバックの呼び出し前に false に設定されます。

http2session.destroy([error][, code]) ​

追加: v8.4.0

  • error <Error> Http2Session がエラーにより破棄されている場合は Error オブジェクト。
  • code <number> 最後の GOAWAY フレームで送信する HTTP/2 エラーコード。指定されておらず、error が undefined でない場合、デフォルトは INTERNAL_ERROR になり、それ以外の場合はデフォルトで NO_ERROR になります。

Http2Session および関連する net.Socket または tls.TLSSocket を即座に終了します。

破棄されると、Http2Session は 'close' イベントを発生させます。error が undefined でない場合、'close' イベントの直前に 'error' イベントが発生します。

Http2Session に関連付けられている未処理の Http2Stream が残っている場合、それらも破棄されます。

http2session.destroyed ​

Added in: v8.4.0

この Http2Session インスタンスが破棄されていて、もはや使用すべきでない場合は true、そうでなければ false になります。

http2session.encrypted ​

Added in: v9.4.0

Http2Session セッションソケットがまだ接続されていない場合、値は undefined、Http2Session が TLSSocket で接続されている場合は true、Http2Session が他の種類のソケットまたはストリームに接続されている場合は false になります。

http2session.goaway([code[, lastStreamID[, opaqueData]]]) ​

Added in: v9.4.0

  • code <number> HTTP/2 エラーコード
  • lastStreamID <number> 最後に処理された Http2Stream の数値 ID
  • opaqueData <Buffer> | <TypedArray> | <DataView> GOAWAY フレーム内に格納される追加データを含む TypedArray または DataView インスタンス。

Http2Session をシャットダウンせずに、接続されたピアに GOAWAY フレームを送信します。

http2session.localSettings ​

Added in: v8.4.0

この Http2Session の現在のローカル設定を記述するプロトタイプのないオブジェクト。 ローカル設定は、この Http2Session インスタンスにローカルです。

http2session.originSet ​

Added in: v9.4.0

Http2Session が TLSSocket に接続されている場合、originSet プロパティは Http2Session が権威があると見なされる可能性のあるオリジンの Array を返します。

originSet プロパティは、セキュアな TLS 接続を使用している場合にのみ使用できます。

http2session.pendingSettingsAck ​

Added in: v8.4.0

Http2Sessionが送信されたSETTINGSフレームの確認応答を現在待機しているかどうかを示します。http2session.settings()メソッドを呼び出した後、trueになります。送信されたすべてのSETTINGSフレームが確認応答されると、falseになります。

http2session.ping([payload, ]callback) ​

[History]

VersionChanges
v18.0.0callback引数に無効なコールバックを渡すと、ERR_INVALID_CALLBACKの代わりにERR_INVALID_ARG_TYPEがスローされるようになりました。
v8.9.3Added in: v8.9.3

接続されたHTTP/2ピアにPINGフレームを送信します。callback関数を指定する必要があります。このメソッドは、PINGが送信された場合はtrue、それ以外の場合はfalseを返します。

未処理（未確認応答）のpingの最大数は、maxOutstandingPings構成オプションによって決定されます。デフォルトの最大値は10です。

指定された場合、payloadは、PINGとともに送信され、ping確認応答とともに返される8バイトのデータを含むBuffer、TypedArray、またはDataViewである必要があります。

コールバックは、3つの引数で呼び出されます。PINGが正常に確認応答された場合はnullになるエラー引数、pingの送信から確認応答の受信までの経過時間をミリ秒単位で報告するduration引数、および8バイトのPINGペイロードを含むBufferです。

js
session.ping(Buffer.from('abcdefgh'), (err, duration, payload) => {
  if (!err) {
    console.log(`Ping acknowledged in ${duration} milliseconds`);
    console.log(`With payload '${payload.toString()}'`);
  }
});

payload引数が指定されていない場合、デフォルトのペイロードは、PING期間の開始を示す64ビットのタイムスタンプ（リトルエンディアン）になります。

http2session.ref() ​

Added in: v9.4.0

このHttp2Sessionインスタンスの基になるnet.Socketでref()を呼び出します。

http2session.remoteSettings ​

Added in: v8.4.0

このHttp2Sessionの現在のリモート設定を記述するプロトタイプのないオブジェクト。リモート設定は、接続されたHTTP/2ピアによって設定されます。

http2session.setLocalWindowSize(windowSize) ​

Added in: v15.3.0, v14.18.0

ローカルエンドポイントのウィンドウサイズを設定します。windowSizeは、設定するウィンドウサイズの合計であり、デルタではありません。

js
import { createServer } from 'node:http2';

const server = createServer();
const expectedWindowSize = 2 ** 20;
server.on('session', (session) => {

  // Set local window size to be 2 ** 20
  session.setLocalWindowSize(expectedWindowSize);
});
js
const http2 = require('node:http2');

const server = http2.createServer();
const expectedWindowSize = 2 ** 20;
server.on('session', (session) => {

  // Set local window size to be 2 ** 20
  session.setLocalWindowSize(expectedWindowSize);
});

http2クライアントの場合、適切なイベントは'connect'または'remoteSettings'のいずれかです。

http2session.setTimeout(msecs, callback) ​

[履歴]

バージョン変更点
v18.0.0callback引数に無効なコールバックを渡すと、ERR_INVALID_CALLBACKの代わりにERR_INVALID_ARG_TYPEがスローされるようになりました。
v8.4.0Added in: v8.4.0

msecsミリ秒後にHttp2Sessionでアクティビティがない場合に呼び出されるコールバック関数を設定するために使用されます。指定されたcallbackは、'timeout'イベントのリスナーとして登録されます。

http2session.socket ​

追加: v8.4.0

net.Socket (または tls.TLSSocket) として動作する Proxy オブジェクトを返しますが、HTTP/2 で安全に使用できるメソッドに利用可能なメソッドを制限します。

destroy、emit、end、pause、read、resume、write は、コード ERR_HTTP2_NO_SOCKET_MANIPULATION でエラーをスローします。詳細については、Http2Session とソケット を参照してください。

setTimeout メソッドは、この Http2Session で呼び出されます。

他のすべてのインタラクションはソケットに直接ルーティングされます。

http2session.state ​

追加: v8.4.0

Http2Session の現在の状態に関するさまざまな情報を提供します。

  • <Object>
    • effectiveLocalWindowSize <number> Http2Session の現在のローカル（受信）フロー制御ウィンドウサイズ。
    • effectiveRecvDataLength <number> 最後のフロー制御 WINDOW_UPDATE 以降に受信された現在のバイト数。
    • nextStreamID <number> 次回この Http2Session によって新しい Http2Stream が作成されるときに使用される数値識別子。
    • localWindowSize <number> リモートピアが WINDOW_UPDATE を受信せずに送信できるバイト数。
    • lastProcStreamID <number> HEADERS または DATA フレームが最後に受信された Http2Stream の数値 ID。
    • remoteWindowSize <number> この Http2Session が WINDOW_UPDATE を受信せずに送信できるバイト数。
    • outboundQueueSize <number> この Http2Session のアウトバウンドキュー内にある現在のフレーム数。
    • deflateDynamicTableSize <number> アウトバウンドヘッダー圧縮状態テーブルの現在のサイズ（バイト単位）。
    • inflateDynamicTableSize <number> インバウンドヘッダー圧縮状態テーブルの現在のサイズ（バイト単位）。

この Http2Session の現在のステータスを記述するオブジェクト。

http2session.settings([settings][, callback]) ​

[履歴]

バージョン変更
v18.0.0callback 引数に無効なコールバックを渡すと、ERR_INVALID_CALLBACK ではなく ERR_INVALID_ARG_TYPE がスローされるようになりました。
v8.4.0追加: v8.4.0

この Http2Session の現在のローカル設定を更新し、接続された HTTP/2 ピアに新しい SETTINGS フレームを送信します。

一度呼び出すと、リモートピアが新しい設定を確認するのをセッションが待機している間、http2session.pendingSettingsAck プロパティは true になります。

新しい設定は、SETTINGS 確認応答を受信し、'localSettings' イベントが発生するまで有効になりません。 確認応答が保留中の場合でも、複数の SETTINGS フレームを送信できます。

http2session.type ​

追加: v8.4.0

http2session.type は、この Http2Session インスタンスがサーバーである場合は http2.constants.NGHTTP2_SESSION_SERVER と等しくなり、インスタンスがクライアントである場合は http2.constants.NGHTTP2_SESSION_CLIENT と等しくなります。

http2session.unref() ​

追加: v9.4.0

この Http2Session インスタンスの基になる net.Socket で unref() を呼び出します。

クラス: ServerHttp2Session ​

追加: v8.4.0

serverhttp2session.altsvc(alt, originOrStream) ​

追加: v9.4.0

  • alt <string> RFC 7838 で定義されている代替サービス構成の説明。
  • originOrStream <number> | <string> | <URL> | <Object> オリジンを指定するURL文字列（またはoriginプロパティを持つObject）、あるいは、http2stream.idプロパティで与えられるアクティブなHttp2Streamの数値識別子。

接続されたクライアントに、RFC 7838 で定義されている ALTSVC フレームを送信します。

js
import { createServer } from 'node:http2';

const server = createServer();
server.on('session', (session) => {
  // origin https://example.org:80 の altsvc を設定
  session.altsvc('h2=":8000"', 'https://example.org:80');
});

server.on('stream', (stream) => {
  // 特定のストリームの altsvc を設定
  stream.session.altsvc('h2=":8000"', stream.id);
});
js
const http2 = require('node:http2');

const server = http2.createServer();
server.on('session', (session) => {
  // origin https://example.org:80 の altsvc を設定
  session.altsvc('h2=":8000"', 'https://example.org:80');
});

server.on('stream', (stream) => {
  // 特定のストリームの altsvc を設定
  stream.session.altsvc('h2=":8000"', stream.id);
});

特定のストリーム ID で ALTSVC フレームを送信すると、代替サービスが指定された Http2Stream のオリジンに関連付けられていることを示します。

alt および origin 文字列は ASCII バイトのみ を含める必要があり、ASCII バイトのシーケンスとして厳密に解釈されます。 特定のドメインに対して以前に設定された代替サービスをクリアするために、特別な値 'clear' を渡すことができます。

originOrStream 引数に文字列が渡されると、URLとして解析され、オリジンが導出されます。 たとえば、HTTP URL 'https://example.org/foo/bar' のオリジンは、ASCII 文字列 'https://example.org' です。 指定された文字列をURLとして解析できない場合、または有効なオリジンを導出できない場合、エラーがスローされます。

URL オブジェクト、または origin プロパティを持つオブジェクトは、originOrStream として渡すことができ、その場合、origin プロパティの値が使用されます。 origin プロパティの値は、適切にシリアライズされた ASCII オリジン でなければなりません。

代替サービスの指定 ​

alt パラメーターの形式は、特定のホストとポートに関連付けられた「代替」プロトコルのコンマ区切りリストを含む ASCII 文字列として、RFC 7838 によって厳密に定義されています。

たとえば、値 'h2="example.org:81"' は、HTTP/2 プロトコルが TCP/IP ポート 81 でホスト 'example.org' で利用可能であることを示します。ホストとポートは、引用符 (") 文字で囲む 必要があります。

複数の代替を指定できます。例：'h2="example.org:81", h2=":82"'。

プロトコル識別子 (例の 'h2') は、有効な ALPN プロトコル ID にすることができます。

これらの値の構文は、Node.js 実装によって検証されず、ユーザーによって提供されるか、ピアから受信されたとおりに渡されます。

serverhttp2session.origin(...origins) ​

追加: v10.12.0

サーバーが権威ある応答を提供できるオリジンのセットをアドバタイズするために、接続されたクライアントに ORIGIN フレーム (RFC 8336 で定義) を送信します。

js
import { createSecureServer } from 'node:http2';
const options = getSecureOptionsSomehow();
const server = createSecureServer(options);
server.on('stream', (stream) => {
  stream.respond();
  stream.end('ok');
});
server.on('session', (session) => {
  session.origin('https://example.com', 'https://example.org');
});
js
const http2 = require('node:http2');
const options = getSecureOptionsSomehow();
const server = http2.createSecureServer(options);
server.on('stream', (stream) => {
  stream.respond();
  stream.end('ok');
});
server.on('session', (session) => {
  session.origin('https://example.com', 'https://example.org');
});

文字列が origin として渡されると、URL として解析され、オリジンが派生します。たとえば、HTTP URL 'https://example.org/foo/bar' のオリジンは、ASCII 文字列 'https://example.org' です。指定された文字列を URL として解析できない場合、または有効なオリジンを派生できない場合は、エラーがスローされます。

URL オブジェクト、または origin プロパティを持つ任意のオブジェクトを origin として渡すことができます。その場合、origin プロパティの値が使用されます。origin プロパティの値は、適切にシリアル化された ASCII オリジン である必要 があります。

あるいは、origins オプションは、http2.createSecureServer() メソッドを使用して新しい HTTP/2 サーバーを作成するときに使用できます。

js
import { createSecureServer } from 'node:http2';
const options = getSecureOptionsSomehow();
options.origins = ['https://example.com', 'https://example.org'];
const server = createSecureServer(options);
server.on('stream', (stream) => {
  stream.respond();
  stream.end('ok');
});
js
const http2 = require('node:http2');
const options = getSecureOptionsSomehow();
options.origins = ['https://example.com', 'https://example.org'];
const server = http2.createSecureServer(options);
server.on('stream', (stream) => {
  stream.respond();
  stream.end('ok');
});

クラス: ClientHttp2Session ​

追加: v8.4.0

イベント: 'altsvc' ​

追加: v9.4.0

'altsvc' イベントは、クライアントが ALTSVC フレームを受信するたびに発生します。イベントは、ALTSVC の値、オリジン、およびストリーム ID とともに発生します。ALTSVC フレームに origin が提供されない場合、origin は空の文字列になります。

js
import { connect } from 'node:http2';
const client = connect('https://example.org');

client.on('altsvc', (alt, origin, streamId) => {
  console.log(alt);
  console.log(origin);
  console.log(streamId);
});
js
const http2 = require('node:http2');
const client = http2.connect('https://example.org');

client.on('altsvc', (alt, origin, streamId) => {
  console.log(alt);
  console.log(origin);
  console.log(streamId);
});

イベント: 'origin' ​

追加: v10.12.0

'origin' イベントは、クライアントが ORIGIN フレームを受信するたびに発生します。イベントは、origin 文字列の配列とともに発生します。http2session.originSet は、受信したオリジンを含むように更新されます。

js
import { connect } from 'node:http2';
const client = connect('https://example.org');

client.on('origin', (origins) => {
  for (let n = 0; n < origins.length; n++)
    console.log(origins[n]);
});
js
const http2 = require('node:http2');
const client = http2.connect('https://example.org');

client.on('origin', (origins) => {
  for (let n = 0; n < origins.length; n++)
    console.log(origins[n]);
});

'origin' イベントは、セキュアな TLS 接続を使用している場合にのみ発生します。

clienthttp2session.request(headers[, options]) ​

Added in: v8.4.0

  • headers <HTTP/2 Headers Object>

  • options <Object>

    • endStream <boolean> Http2Stream の 書き込み可能 側を最初に閉じる必要がある場合は true。ペイロード本体を予期すべきでない GET リクエストを送信する場合など。
    • exclusive <boolean> true であり、parent が親ストリームを識別する場合、作成されたストリームは親の唯一の直接の依存関係になり、他の既存の依存関係は新しく作成されたストリームの依存関係になります。デフォルト: false。
    • parent <number> 新しく作成されたストリームが依存するストリームの数値識別子を指定します。
    • weight <number> 同じ parent を持つ他のストリームとの関係におけるストリームの相対的な依存関係を指定します。値は 1 から 256 (両端を含む) までの数値です。
    • waitForTrailers <boolean> true の場合、Http2Stream は、最後の DATA フレームが送信された後、'wantTrailers' イベントを発行します。
    • signal <AbortSignal> 進行中のリクエストを中断するために使用できる AbortSignal。

  • Returns: <ClientHttp2Stream>

HTTP/2 クライアントの Http2Session インスタンスのみの場合、http2session.request() は、接続されたサーバーに HTTP/2 リクエストを送信するために使用できる Http2Stream インスタンスを作成して返します。

ClientHttp2Session が最初に作成されるとき、ソケットはまだ接続されていない可能性があります。この間に clienthttp2session.request() が呼び出された場合、実際のリクエストはソケットの準備が整うまで延期されます。実際のリクエストが実行される前に session が閉じられた場合、ERR_HTTP2_GOAWAY_SESSION がスローされます。

このメソッドは、http2session.type が http2.constants.NGHTTP2_SESSION_CLIENT と等しい場合にのみ使用できます。

js
import { connect, constants } from 'node:http2';
const clientSession = connect('https://localhost:1234');
const {
  HTTP2_HEADER_PATH,
  HTTP2_HEADER_STATUS,
} = constants;

const req = clientSession.request({ [HTTP2_HEADER_PATH]: '/' });
req.on('response', (headers) => {
  console.log(headers[HTTP2_HEADER_STATUS]);
  req.on('data', (chunk) => { /* .. */ });
  req.on('end', () => { /* .. */ });
});
js
const http2 = require('node:http2');
const clientSession = http2.connect('https://localhost:1234');
const {
  HTTP2_HEADER_PATH,
  HTTP2_HEADER_STATUS,
} = http2.constants;

const req = clientSession.request({ [HTTP2_HEADER_PATH]: '/' });
req.on('response', (headers) => {
  console.log(headers[HTTP2_HEADER_STATUS]);
  req.on('data', (chunk) => { /* .. */ });
  req.on('end', () => { /* .. */ });
});

options.waitForTrailers オプションが設定されている場合、送信されるペイロードデータの最後のチャンクをキューに入れた直後に、'wantTrailers' イベントが発行されます。その後、http2stream.sendTrailers() メソッドを呼び出して、トレーラーヘッダーをピアに送信できます。

options.waitForTrailers が設定されている場合、Http2Stream は最後の DATA フレームが送信されても自動的に閉じません。ユーザーコードは、Http2Stream を閉じるために http2stream.sendTrailers() または http2stream.close() のいずれかを呼び出す必要があります。

options.signal が AbortSignal で設定され、対応する AbortController で abort が呼び出されると、リクエストは AbortError エラーとともに 'error' イベントを発行します。

:method および :path 擬似ヘッダーが headers 内で指定されていない場合、それぞれデフォルトで次のようになります。

  • :method = 'GET'
  • :path = /

クラス: Http2Stream ​

追加: v8.4.0

Http2Streamクラスの各インスタンスは、Http2Sessionインスタンスを介した双方向のHTTP/2通信ストリームを表します。単一のHttp2Sessionは、そのライフサイクル全体で最大2-1個のHttp2Streamインスタンスを持つことができます。

ユーザーコードはHttp2Streamインスタンスを直接構築しません。代わりに、これらはHttp2Sessionインスタンスを通じて作成、管理され、ユーザーコードに提供されます。サーバーでは、Http2Streamインスタンスは、受信HTTPリクエスト（および'stream'イベントを介してユーザーコードに引き渡される）に応答して、またはhttp2stream.pushStream()メソッドの呼び出しに応答して作成されます。クライアントでは、Http2Streamインスタンスは、http2session.request()メソッドが呼び出されたとき、または受信'push'イベントに応答して作成され、返されます。

Http2Streamクラスは、ServerHttp2StreamクラスおよびClientHttp2Streamクラスの基底クラスであり、それぞれサーバー側またはクライアント側で個別に使用されます。

すべてのHttp2Streamインスタンスは、Duplexストリームです。DuplexのWritable側は、接続されたピアにデータを送信するために使用され、Readable側は、接続されたピアから送信されたデータを受信するために使用されます。

Http2Streamのデフォルトのテキスト文字エンコーディングはUTF-8です。Http2Streamを使用してテキストを送信する場合は、'content-type'ヘッダーを使用して文字エンコーディングを設定します。

js
stream.respond({
  'content-type': 'text/html; charset=utf-8',
  ':status': 200,
});

Http2Streamのライフサイクル ​

作成 ​

サーバー側では、ServerHttp2Streamのインスタンスは、次のいずれかの場合に作成されます。

  • 以前に使用されていないストリームIDを持つ新しいHTTP/2 HEADERSフレームを受信した場合。
  • http2stream.pushStream()メソッドが呼び出された場合。

クライアント側では、ClientHttp2Streamのインスタンスは、http2session.request()メソッドが呼び出されたときに作成されます。

クライアントでは、http2session.request()によって返されるHttp2Streamインスタンスは、親Http2Sessionがまだ完全に確立されていない場合、すぐには使用できない場合があります。そのような場合、Http2Streamで呼び出された操作は、'ready'イベントが発行されるまでバッファリングされます。ユーザーコードは、'ready'イベントを直接処理する必要はほとんどありません。Http2Streamの準備完了状態は、http2stream.idの値を確認することで判断できます。値がundefinedの場合、ストリームはまだ使用できません。

破棄 ​

すべての Http2Stream インスタンスは、以下のいずれかの時に破棄されます。

  • ストリームに対する RST_STREAM フレームが接続されたピアによって受信され、（クライアントストリームの場合のみ）保留中のデータが読み込まれたとき。
  • http2stream.close() メソッドが呼び出され、（クライアントストリームの場合のみ）保留中のデータが読み込まれたとき。
  • http2stream.destroy() または http2session.destroy() メソッドが呼び出されたとき。

Http2Stream インスタンスが破棄されると、接続されたピアに RST_STREAM フレームを送信しようとします。

Http2Stream インスタンスが破棄されると、'close' イベントが発生します。Http2Stream は stream.Duplex のインスタンスであるため、ストリームデータが現在流れている場合は 'end' イベントも発生します。http2stream.destroy() が最初の引数として Error を渡して呼び出された場合は、'error' イベントも発生する可能性があります。

Http2Stream が破棄された後、http2stream.destroyed プロパティは true になり、http2stream.rstCode プロパティは RST_STREAM エラーコードを指定します。Http2Stream インスタンスは、破棄されると使用できなくなります。

Event: 'aborted' ​

Added in: v8.4.0

'aborted' イベントは、Http2Stream インスタンスが通信の途中で異常に中断された場合に常に発生します。そのリスナーは引数を期待しません。

'aborted' イベントは、Http2Stream の書き込み可能側が終了していない場合にのみ発生します。

Event: 'close' ​

Added in: v8.4.0

'close' イベントは、Http2Stream が破棄されると発生します。このイベントが発生すると、Http2Stream インスタンスは使用できなくなります。

ストリームを閉じるときに使用された HTTP/2 エラーコードは、http2stream.rstCode プロパティを使用して取得できます。コードが NGHTTP2_NO_ERROR（0）以外の値である場合、'error' イベントも発生します。

Event: 'error' ​

Added in: v8.4.0

'error' イベントは、Http2Stream の処理中にエラーが発生した場合に発生します。

イベント: 'frameError' ​

追加: v8.4.0

  • type <integer> フレームの種類。
  • code <integer> エラーコード。
  • id <integer> ストリームID（フレームがストリームに関連付けられていない場合は0）。

'frameError'イベントは、フレームの送信を試みているときにエラーが発生した場合に発生します。 呼び出されると、ハンドラー関数はフレームタイプを識別する整数引数と、エラーコードを識別する整数引数を受け取ります。 'frameError'イベントが発生した直後にHttp2Streamインスタンスは破棄されます。

イベント: 'ready' ​

追加: v8.4.0

'ready'イベントは、Http2Streamが開かれ、idが割り当てられ、使用できるようになったときに発生します。 リスナーは引数を期待しません。

イベント: 'timeout' ​

追加: v8.4.0

'timeout'イベントは、http2stream.setTimeout()を使用して設定されたミリ秒数以内に、このHttp2Streamでアクティビティが受信されなかった場合に発生します。 そのリスナーは引数を期待しません。

イベント: 'trailers' ​

追加: v8.4.0

'trailers'イベントは、トレーラーヘッダーフィールドに関連付けられたヘッダーのブロックを受信したときに発生します。 リスナーコールバックには、HTTP/2ヘッダーオブジェクトとヘッダーに関連付けられたフラグが渡されます。

トレーラーを受信する前にhttp2stream.end()が呼び出され、受信データが読み取られていないか、リッスンされていない場合、このイベントは発生しない可能性があります。

js
stream.on('trailers', (headers, flags) => {
  console.log(headers);
});

イベント: 'wantTrailers' ​

追加: v10.0.0

Http2Streamがフレーム上で送信される最後のDATAフレームをキューに入れ、Http2Streamがトレーラーヘッダーを送信する準備ができている場合に、'wantTrailers'イベントが発行されます。リクエストまたはレスポンスを開始するときに、このイベントを発行するには、waitForTrailersオプションを設定する必要があります。

http2stream.aborted ​

追加: v8.4.0

Http2Streamインスタンスが異常終了した場合、trueに設定されます。設定されている場合、'aborted'イベントが発行されています。

http2stream.bufferSize ​

追加: v11.2.0, v10.16.0

このプロパティは、書き込まれるために現在バッファリングされている文字数を示します。詳細については、net.Socket.bufferSizeを参照してください。

http2stream.close(code[, callback]) ​

[履歴]

バージョン変更
v18.0.0callback引数に無効なコールバックを渡すと、ERR_INVALID_CALLBACKではなくERR_INVALID_ARG_TYPEがスローされるようになりました。
v8.4.0追加: v8.4.0
  • code <number> エラーコードを識別する符号なし32ビット整数。デフォルト: http2.constants.NGHTTP2_NO_ERROR (0x00)。
  • callback <Function> 'close'イベントをリッスンするために登録されたオプションの関数。

接続されたHTTP/2ピアにRST_STREAMフレームを送信することにより、Http2Streamインスタンスを閉じます。

http2stream.closed ​

追加: v9.4.0

Http2Streamインスタンスが閉じられている場合、trueに設定されます。

http2stream.destroyed ​

追加: v8.4.0

Http2Streamインスタンスが破棄され、使用できなくなった場合、trueに設定されます。

http2stream.endAfterHeaders ​

Added in: v10.11.0

受信したリクエストまたはレスポンスの HEADERS フレームで END_STREAM フラグが設定されている場合に true に設定します。これは追加のデータを受信すべきではなく、Http2Stream の読み取り可能な側が閉じられることを示します。

http2stream.id ​

Added in: v8.4.0

この Http2Stream インスタンスの数値ストリーム識別子。ストリーム識別子がまだ割り当てられていない場合は undefined に設定されます。

http2stream.pending ​

Added in: v9.4.0

Http2Stream インスタンスにまだ数値ストリーム識別子が割り当てられていない場合は true に設定されます。

http2stream.priority(options) ​

Added in: v8.4.0

  • options <Object>
    • exclusive <boolean> true で、parent が親ストリームを識別する場合、このストリームは親の唯一の直接の依存関係になり、他の既存の依存関係はすべてこのストリームの依存関係になります。 デフォルト: false。
    • parent <number> このストリームが依存するストリームの数値識別子を指定します。
    • weight <number> 同じ parent を持つ他のストリームに対するストリームの相対的な依存関係を指定します。値は 1 から 256 (両端を含む) の間の数値です。
    • silent <boolean> true の場合、接続されたピアに PRIORITY フレームを送信せずに、ローカルで優先度を変更します。

この Http2Stream インスタンスの優先度を更新します。

http2stream.rstCode ​

Added in: v8.4.0

Http2Streamが、接続されたピアからRST_STREAMフレームを受信した後、http2stream.close()を呼び出すか、http2stream.destroy()を呼び出して破棄された場合に報告されるRST_STREAM エラーコードに設定されます。 Http2Streamが閉じられていない場合は、undefinedになります。

http2stream.sentHeaders ​

Added in: v9.5.0

このHttp2Streamに送信された送信ヘッダーを含むオブジェクト。

http2stream.sentInfoHeaders ​

Added in: v9.5.0

このHttp2Streamに送信された送信情報（追加）ヘッダーを含むオブジェクトの配列。

http2stream.sentTrailers ​

Added in: v9.5.0

このHttpStreamに送信された送信トレーラーを含むオブジェクト。

http2stream.session ​

Added in: v8.4.0

このHttp2Streamを所有するHttp2Sessionインスタンスへの参照。 Http2Streamインスタンスが破棄された後、値はundefinedになります。

http2stream.setTimeout(msecs, callback) ​

[History]

VersionChanges
v18.0.0callback引数に無効なコールバックを渡すと、ERR_INVALID_CALLBACKではなくERR_INVALID_ARG_TYPEがスローされるようになりました。
v8.4.0Added in: v8.4.0
js
import { connect, constants } from 'node:http2';
const client = connect('http://example.org:8000');
const { NGHTTP2_CANCEL } = constants;
const req = client.request({ ':path': '/' });

// Cancel the stream if there's no activity after 5 seconds
req.setTimeout(5000, () => req.close(NGHTTP2_CANCEL));
js
const http2 = require('node:http2');
const client = http2.connect('http://example.org:8000');
const { NGHTTP2_CANCEL } = http2.constants;
const req = client.request({ ':path': '/' });

// Cancel the stream if there's no activity after 5 seconds
req.setTimeout(5000, () => req.close(NGHTTP2_CANCEL));

http2stream.state ​

Added in: v8.4.0

Http2Streamの現在の状態に関する雑多な情報を提供します。

  • <Object>
    • localWindowSize <number> 接続されたピアが WINDOW_UPDATE を受信せずに、この Http2Stream に対して送信できるバイト数。
    • state <number> nghttp2 によって決定される、Http2Stream の低レベルの現在の状態を示すフラグ。
    • localClose <number> この Http2Stream がローカルで閉じられている場合は 1。
    • remoteClose <number> この Http2Stream がリモートで閉じられている場合は 1。
    • sumDependencyWeight <number> PRIORITY フレームを使用して指定された、この Http2Stream に依存するすべての Http2Stream インスタンスの重みの合計。
    • weight <number> この Http2Stream の優先度の重み。

この Http2Stream の現在の状態。

http2stream.sendTrailers(headers) ​

Added in: v10.0.0

末尾の HEADERS フレームを接続された HTTP/2 ピアに送信します。このメソッドは Http2Stream を直ちに閉じ、'wantTrailers' イベントが発行された後にのみ呼び出す必要があります。リクエストの送信時またはレスポンスの送信時に、トレーラーを送信できるように、最後の DATA フレームの後に Http2Stream を開いたままにするには、options.waitForTrailers オプションを設定する必要があります。

js
import { createServer } from 'node:http2';
const server = createServer();
server.on('stream', (stream) => {
  stream.respond(undefined, { waitForTrailers: true });
  stream.on('wantTrailers', () => {
    stream.sendTrailers({ xyz: 'abc' });
  });
  stream.end('Hello World');
});
js
const http2 = require('node:http2');
const server = http2.createServer();
server.on('stream', (stream) => {
  stream.respond(undefined, { waitForTrailers: true });
  stream.on('wantTrailers', () => {
    stream.sendTrailers({ xyz: 'abc' });
  });
  stream.end('Hello World');
});

HTTP/1 仕様では、トレーラーに HTTP/2 疑似ヘッダーフィールド (例: ':method', ':path', など) を含めることは禁止されています。

クラス: ClientHttp2Stream ​

追加: v8.4.0

ClientHttp2Streamクラスは、HTTP/2クライアントでのみ使用されるHttp2Streamの拡張です。クライアント上のHttp2Streamインスタンスは、クライアントにのみ関連する'response'や'push'などのイベントを提供します。

イベント: 'continue' ​

追加: v8.5.0

通常、リクエストにExpect: 100-continueが含まれているため、サーバーが100 Continueステータスを送信したときに発生します。これは、クライアントがリクエストボディを送信する必要があるという指示です。

イベント: 'headers' ​

追加: v8.4.0

'headers'イベントは、1xxのインフォメーションヘッダーのブロックが受信された場合など、ストリームに追加のヘッダーブロックが受信されたときに発生します。リスナーコールバックには、HTTP/2 Headers Objectとヘッダーに関連付けられたフラグが渡されます。

js
stream.on('headers', (headers, flags) => {
  console.log(headers);
});

イベント: 'push' ​

追加: v8.4.0

'push'イベントは、サーバープッシュストリームのレスポンスヘッダーが受信されたときに発生します。リスナーコールバックには、HTTP/2 Headers Objectとヘッダーに関連付けられたフラグが渡されます。

js
stream.on('push', (headers, flags) => {
  console.log(headers);
});

イベント: 'response' ​

追加: v8.4.0

'response'イベントは、接続されたHTTP/2サーバーからこのストリームのレスポンスHEADERSフレームを受信したときに発生します。リスナーは、受信したHTTP/2 Headers Objectを含むObjectと、ヘッダーに関連付けられたフラグの2つの引数で呼び出されます。

js
import { connect } from 'node:http2';
const client = connect('https://localhost');
const req = client.request({ ':path': '/' });
req.on('response', (headers, flags) => {
  console.log(headers[':status']);
});
js
const http2 = require('node:http2');
const client = http2.connect('https://localhost');
const req = client.request({ ':path': '/' });
req.on('response', (headers, flags) => {
  console.log(headers[':status']);
});

クラス: ServerHttp2Stream ​

追加: v8.4.0

ServerHttp2Stream クラスは、HTTP/2 サーバーでのみ排他的に使用される Http2Stream の拡張です。サーバー上の Http2Stream インスタンスは、http2stream.pushStream() や http2stream.respond() などのサーバーでのみ関連する追加のメソッドを提供します。

http2stream.additionalHeaders(headers) ​

追加: v8.4.0

追加の通知 HEADERS フレームを接続された HTTP/2 ピアに送信します。

http2stream.headersSent ​

追加: v8.4.0

ヘッダーが送信された場合は true、それ以外の場合は false (読み取り専用)。

http2stream.pushAllowed ​

追加: v8.4.0

リモートクライアントの最新の SETTINGS フレームの SETTINGS_ENABLE_PUSH フラグにマッピングされた読み取り専用プロパティ。リモートピアがプッシュストリームを受け入れる場合は true、それ以外の場合は false になります。設定は、同じ Http2Session 内のすべての Http2Stream で同じです。

http2stream.pushStream(headers[, options], callback) ​

[履歴]

バージョン変更
v18.0.0callback 引数に無効なコールバックを渡すと、ERR_INVALID_CALLBACK ではなく ERR_INVALID_ARG_TYPE がスローされるようになりました。
v8.4.0追加: v8.4.0

  • headers <HTTP/2 ヘッダーオブジェクト>

  • options <Object>

    • exclusive <boolean> true であり、parent が親ストリームを識別する場合、作成されたストリームは親の唯一の直接依存関係になり、他の既存の依存関係は新しく作成されたストリームの依存関係になります。デフォルト: false。
    • parent <number> 新しく作成されたストリームが依存するストリームの数値識別子を指定します。

  • callback <Function> プッシュストリームが開始されると呼び出されるコールバック。

プッシュストリームを開始します。コールバックは、プッシュストリーム用に作成された新しい Http2Stream インスタンスが 2 番目の引数として渡されるか、Error が最初の引数として渡されて呼び出されます。

js
import { createServer } from 'node:http2';
const server = createServer();
server.on('stream', (stream) => {
  stream.respond({ ':status': 200 });
  stream.pushStream({ ':path': '/' }, (err, pushStream, headers) => {
    if (err) throw err;
    pushStream.respond({ ':status': 200 });
    pushStream.end('some pushed data');
  });
  stream.end('some data');
});
js
const http2 = require('node:http2');
const server = http2.createServer();
server.on('stream', (stream) => {
  stream.respond({ ':status': 200 });
  stream.pushStream({ ':path': '/' }, (err, pushStream, headers) => {
    if (err) throw err;
    pushStream.respond({ ':status': 200 });
    pushStream.end('some pushed data');
  });
  stream.end('some data');
});

プッシュストリームの重みを HEADERS フレームで設定することはできません。サーバー側の同時ストリーム間の帯域幅バランシングを有効にするには、silent オプションを true に設定して、weight 値を http2stream.priority に渡します。

プッシュされたストリーム内から http2stream.pushStream() を呼び出すことは許可されておらず、エラーがスローされます。

http2stream.respond([headers[, options]]) ​

[履歴]

バージョン変更
v14.5.0, v12.19.0明示的に日付ヘッダーを設定できるようになりました。
v8.4.0追加: v8.4.0
  • headers <HTTP/2 Headers Object>
  • options <Object>
    • endStream <boolean> レスポンスにペイロードデータが含まれないことを示す場合は、true に設定します。
    • waitForTrailers <boolean> true の場合、Http2Stream は最後の DATA フレームが送信された後に 'wantTrailers' イベントを発生させます。
js
import { createServer } from 'node:http2';
const server = createServer();
server.on('stream', (stream) => {
  stream.respond({ ':status': 200 });
  stream.end('some data');
});
js
const http2 = require('node:http2');
const server = http2.createServer();
server.on('stream', (stream) => {
  stream.respond({ ':status': 200 });
  stream.end('some data');
});

レスポンスを開始します。 options.waitForTrailers オプションが設定されている場合、送信されるペイロードデータの最後のチャンクをキューに入れた直後に 'wantTrailers' イベントが発生します。 その後、http2stream.sendTrailers() メソッドを使用して、トレーラーヘッダーフィールドをピアに送信できます。

options.waitForTrailers が設定されている場合、Http2Stream は最後の DATA フレームが送信されたときに自動的に閉じません。 ユーザーコードは、http2stream.sendTrailers() または http2stream.close() のいずれかを呼び出して、Http2Stream を閉じる必要があります。

js
import { createServer } from 'node:http2';
const server = createServer();
server.on('stream', (stream) => {
  stream.respond({ ':status': 200 }, { waitForTrailers: true });
  stream.on('wantTrailers', () => {
    stream.sendTrailers({ ABC: 'some value to send' });
  });
  stream.end('some data');
});
js
const http2 = require('node:http2');
const server = http2.createServer();
server.on('stream', (stream) => {
  stream.respond({ ':status': 200 }, { waitForTrailers: true });
  stream.on('wantTrailers', () => {
    stream.sendTrailers({ ABC: 'some value to send' });
  });
  stream.end('some data');
});

http2stream.respondWithFD(fd[, headers[, options]]) ​

[履歴]

バージョン変更
v14.5.0, v12.19.0明示的な日付ヘッダーの設定を許可。
v12.12.0fd オプションが FileHandle になることが可能に。
v10.0.0必ずしも通常のファイルである必要はなく、読み取り可能なファイル記述子がサポートされるようになりました。
v8.4.0追加: v8.4.0

指定されたファイル記述子からデータが読み取られるレスポンスを開始します。 指定されたファイル記述子に対して検証は実行されません。 ファイル記述子を使用してデータを読み取ろうとしているときにエラーが発生した場合、Http2Stream は標準の INTERNAL_ERROR コードを使用して RST_STREAM フレームで閉じられます。

使用すると、Http2Stream オブジェクトの Duplex インターフェイスは自動的に閉じられます。

js
import { createServer } from 'node:http2';
import { openSync, fstatSync, closeSync } from 'node:fs';

const server = createServer();
server.on('stream', (stream) => {
  const fd = openSync('/some/file', 'r');

  const stat = fstatSync(fd);
  const headers = {
    'content-length': stat.size,
    'last-modified': stat.mtime.toUTCString(),
    'content-type': 'text/plain; charset=utf-8',
  };
  stream.respondWithFD(fd, headers);
  stream.on('close', () => closeSync(fd));
});
js
const http2 = require('node:http2');
const fs = require('node:fs');

const server = http2.createServer();
server.on('stream', (stream) => {
  const fd = fs.openSync('/some/file', 'r');

  const stat = fs.fstatSync(fd);
  const headers = {
    'content-length': stat.size,
    'last-modified': stat.mtime.toUTCString(),
    'content-type': 'text/plain; charset=utf-8',
  };
  stream.respondWithFD(fd, headers);
  stream.on('close', () => fs.closeSync(fd));
});

オプションの options.statCheck 関数を指定すると、ユーザーコードは指定された fd の fs.Stat の詳細に基づいて追加のコンテンツヘッダーを設定する機会を得られます。 statCheck 関数が指定されている場合、http2stream.respondWithFD() メソッドは fs.fstat() 呼び出しを実行して、指定されたファイル記述子の詳細を収集します。

offset および length オプションを使用して、応答を特定の範囲のサブセットに制限できます。 これは、たとえば、HTTP Range リクエストをサポートするために使用できます。

ファイル記述子または FileHandle はストリームが閉じられたときに閉じられないため、不要になったら手動で閉じる必要があります。 複数のストリームで同じファイル記述子を同時に使用することはサポートされておらず、データが失われる可能性があります。 ストリームが終了した後、ファイル記述子を再利用することはサポートされています。

options.waitForTrailers オプションが設定されている場合、送信されるペイロードデータの最後のチャンクをキューに入れた直後に 'wantTrailers' イベントが発生します。 次に、http2stream.sendTrailers() メソッドを使用して、末尾のヘッダーフィールドをピアに送信できます。

options.waitForTrailers が設定されている場合、最後の DATA フレームが送信されても Http2Stream は自動的に閉じられません。 ユーザーコードは、Http2Stream を閉じるために、http2stream.sendTrailers() または http2stream.close() のいずれかを必ず呼び出す必要があります。

js
import { createServer } from 'node:http2';
import { openSync, fstatSync, closeSync } from 'node:fs';

const server = createServer();
server.on('stream', (stream) => {
  const fd = openSync('/some/file', 'r');

  const stat = fstatSync(fd);
  const headers = {
    'content-length': stat.size,
    'last-modified': stat.mtime.toUTCString(),
    'content-type': 'text/plain; charset=utf-8',
  };
  stream.respondWithFD(fd, headers, { waitForTrailers: true });
  stream.on('wantTrailers', () => {
    stream.sendTrailers({ ABC: 'some value to send' });
  });

  stream.on('close', () => closeSync(fd));
});
js
const http2 = require('node:http2');
const fs = require('node:fs');

const server = http2.createServer();
server.on('stream', (stream) => {
  const fd = fs.openSync('/some/file', 'r');

  const stat = fs.fstatSync(fd);
  const headers = {
    'content-length': stat.size,
    'last-modified': stat.mtime.toUTCString(),
    'content-type': 'text/plain; charset=utf-8',
  };
  stream.respondWithFD(fd, headers, { waitForTrailers: true });
  stream.on('wantTrailers', () => {
    stream.sendTrailers({ ABC: 'some value to send' });
  });

  stream.on('close', () => fs.closeSync(fd));
});

http2stream.respondWithFile(path[, headers[, options]]) ​

[沿革]

バージョン変更点
v14.5.0, v12.19.0明示的に日付ヘッダーを設定できるようにしました。
v10.0.0必ずしも通常のファイルである必要はなく、読み取り可能なファイルがサポートされるようになりました。
v8.4.0v8.4.0 で追加されました

通常のファイルをレスポンスとして送信します。 path は通常のファイルを指定する必要があります。そうでない場合、Http2Stream オブジェクトで 'error' イベントが発生します。

使用すると、Http2Stream オブジェクトの Duplex インターフェースは自動的に閉じられます。

オプションの options.statCheck 関数を指定して、ユーザーコードが指定されたファイルの fs.Stat の詳細に基づいて追加のコンテンツヘッダーを設定する機会を与えることができます。

ファイルデータの読み取りを試行中にエラーが発生した場合、Http2Stream は標準の INTERNAL_ERROR コードを使用して RST_STREAM フレームを使用して閉じられます。 onError コールバックが定義されている場合は、それが呼び出されます。それ以外の場合、ストリームは破棄されます。

ファイルパスを使用する例:

js
import { createServer } from 'node:http2';
const server = createServer();
server.on('stream', (stream) => {
  function statCheck(stat, headers) {
    headers['last-modified'] = stat.mtime.toUTCString();
  }

  function onError(err) {
    // stream.respond() は、ストリームが相手側によって破棄された場合にスローされる可能性があります。
    try {
      if (err.code === 'ENOENT') {
        stream.respond({ ':status': 404 });
      } else {
        stream.respond({ ':status': 500 });
      }
    } catch (err) {
      // 実際のエラー処理を実行します。
      console.error(err);
    }
    stream.end();
  }

  stream.respondWithFile('/some/file',
                         { 'content-type': 'text/plain; charset=utf-8' },
                         { statCheck, onError });
});
js
const http2 = require('node:http2');
const server = http2.createServer();
server.on('stream', (stream) => {
  function statCheck(stat, headers) {
    headers['last-modified'] = stat.mtime.toUTCString();
  }

  function onError(err) {
    // stream.respond() は、ストリームが相手側によって破棄された場合にスローされる可能性があります。
    try {
      if (err.code === 'ENOENT') {
        stream.respond({ ':status': 404 });
      } else {
        stream.respond({ ':status': 500 });
      }
    } catch (err) {
      // 実際のエラー処理を実行します。
      console.error(err);
    }
    stream.end();
  }

  stream.respondWithFile('/some/file',
                         { 'content-type': 'text/plain; charset=utf-8' },
                         { statCheck, onError });
});

options.statCheck 関数を使用して、false を返すことによって送信操作をキャンセルすることもできます。 たとえば、条件付きリクエストは stat 結果をチェックして、ファイルが変更されたかどうかを判断し、適切な 304 レスポンスを返すことができます。

js
import { createServer } from 'node:http2';
const server = createServer();
server.on('stream', (stream) => {
  function statCheck(stat, headers) {
    // stat をここでチェックします...
    stream.respond({ ':status': 304 });
    return false; // 送信操作をキャンセルします
  }
  stream.respondWithFile('/some/file',
                         { 'content-type': 'text/plain; charset=utf-8' },
                         { statCheck });
});
js
const http2 = require('node:http2');
const server = http2.createServer();
server.on('stream', (stream) => {
  function statCheck(stat, headers) {
    // stat をここでチェックします...
    stream.respond({ ':status': 304 });
    return false; // 送信操作をキャンセルします
  }
  stream.respondWithFile('/some/file',
                         { 'content-type': 'text/plain; charset=utf-8' },
                         { statCheck });
});

content-length ヘッダーフィールドは自動的に設定されます。

offset および length オプションを使用して、レスポンスを特定の範囲サブセットに制限できます。 たとえば、これは HTTP Range リクエストをサポートするために使用できます。

options.onError 関数を使用して、ファイルの配信が開始される前に発生する可能性のあるすべてのエラーを処理することもできます。 デフォルトの動作は、ストリームを破棄することです。

options.waitForTrailers オプションが設定されている場合、送信されるペイロードデータの最後のチャンクをキューに入れた直後に 'wantTrailers' イベントが発行されます。 次に、http2stream.sendTrailers() メソッドを使用して、トレーラーヘッダーフィールドをピアに送信できます。

options.waitForTrailers が設定されている場合、最後の DATA フレームが送信されても Http2Stream は自動的に閉じません。 ユーザーコードは、Http2Stream を閉じるために http2stream.sendTrailers() または http2stream.close() のいずれかを呼び出す必要があります。

js
import { createServer } from 'node:http2';
const server = createServer();
server.on('stream', (stream) => {
  stream.respondWithFile('/some/file',
                         { 'content-type': 'text/plain; charset=utf-8' },
                         { waitForTrailers: true });
  stream.on('wantTrailers', () => {
    stream.sendTrailers({ ABC: 'some value to send' });
  });
});
js
const http2 = require('node:http2');
const server = http2.createServer();
server.on('stream', (stream) => {
  stream.respondWithFile('/some/file',
                         { 'content-type': 'text/plain; charset=utf-8' },
                         { waitForTrailers: true });
  stream.on('wantTrailers', () => {
    stream.sendTrailers({ ABC: 'some value to send' });
  });
});

クラス: Http2Server ​

追加: v8.4.0

Http2Serverのインスタンスは、http2.createServer()関数を使用して作成されます。Http2Serverクラスは、node:http2モジュールによって直接エクスポートされません。

イベント: 'checkContinue' ​

追加: v8.5.0

'request'リスナーが登録されている場合、またはhttp2.createServer()にコールバック関数が提供されている場合、HTTP Expect: 100-continueを含むリクエストを受信するたびに、'checkContinue'イベントが発生します。このイベントがリッスンされない場合、サーバーはステータス100 Continueで適切に自動的に応答します。

このイベントを処理するには、クライアントがリクエストボディの送信を継続する必要がある場合はresponse.writeContinue()を呼び出すか、クライアントがリクエストボディの送信を継続する必要がない場合は適切なHTTP応答（例：400 Bad Request）を生成します。

このイベントが発生して処理される場合、'request'イベントは発生しません。

イベント: 'connection' ​

追加: v8.4.0

このイベントは、新しいTCPストリームが確立されたときに発生します。socketは通常、net.Socket型のオブジェクトです。通常、ユーザーはこのイベントにアクセスする必要はありません。

このイベントは、HTTPサーバーに接続を注入するために、ユーザーが明示的に発生させることもできます。その場合、任意のDuplexストリームを渡すことができます。

イベント: 'request' ​

追加: v8.4.0

リクエストがあるたびに発生します。セッションごとに複数のリクエストがある場合があります。互換性APIを参照してください。

イベント: 'session' ​

追加: v8.4.0

'session' イベントは、新しい Http2Session が Http2Server によって作成されたときに発生します。

イベント: 'sessionError' ​

追加: v8.4.0

'sessionError' イベントは、Http2Server に関連付けられた Http2Session オブジェクトによって 'error' イベントが発生したときに発生します。

イベント: 'stream' ​

追加: v8.4.0

  • stream <Http2Stream> ストリームへの参照
  • headers <HTTP/2 Headers Object> ヘッダーを記述するオブジェクト
  • flags <number> 関連付けられた数値フラグ
  • rawHeaders <Array> 生のヘッダー名とそれぞれの値を含む配列。

'stream' イベントは、サーバーに関連付けられた Http2Session によって 'stream' イベントが発生したときに発生します。

Http2Session の 'stream' イベントも参照してください。

js
import { createServer, constants } from 'node:http2';
const {
  HTTP2_HEADER_METHOD,
  HTTP2_HEADER_PATH,
  HTTP2_HEADER_STATUS,
  HTTP2_HEADER_CONTENT_TYPE,
} = constants;

const server = createServer();
server.on('stream', (stream, headers, flags) => {
  const method = headers[HTTP2_HEADER_METHOD];
  const path = headers[HTTP2_HEADER_PATH];
  // ...
  stream.respond({
    [HTTP2_HEADER_STATUS]: 200,
    [HTTP2_HEADER_CONTENT_TYPE]: 'text/plain; charset=utf-8',
  });
  stream.write('hello ');
  stream.end('world');
});
js
const http2 = require('node:http2');
const {
  HTTP2_HEADER_METHOD,
  HTTP2_HEADER_PATH,
  HTTP2_HEADER_STATUS,
  HTTP2_HEADER_CONTENT_TYPE,
} = http2.constants;

const server = http2.createServer();
server.on('stream', (stream, headers, flags) => {
  const method = headers[HTTP2_HEADER_METHOD];
  const path = headers[HTTP2_HEADER_PATH];
  // ...
  stream.respond({
    [HTTP2_HEADER_STATUS]: 200,
    [HTTP2_HEADER_CONTENT_TYPE]: 'text/plain; charset=utf-8',
  });
  stream.write('hello ');
  stream.end('world');
});

Event: 'timeout' ​

[履歴]

バージョン変更点
v13.0.0デフォルトのタイムアウトが 120 秒から 0 (タイムアウトなし) に変更されました。
v8.4.0Added in: v8.4.0

'timeout' イベントは、http2server.setTimeout() を使用して設定されたミリ秒数でサーバーにアクティビティがない場合に発生します。デフォルト: 0 (タイムアウトなし)

server.close([callback]) ​

Added in: v8.4.0

サーバーが新しいセッションを確立するのを停止します。これにより、HTTP/2 セッションの永続的な性質により、新しいリクエストストリームが作成されるのを防ぐことはできません。サーバーを正常にシャットダウンするには、すべてのアクティブなセッションで http2session.close() を呼び出します。

callback が提供されている場合、サーバーが新しいセッションを許可することをすでに停止していても、すべてのアクティブなセッションが閉じられるまで呼び出されません。詳細については、net.Server.close() を参照してください。

server[Symbol.asyncDispose]() ​

Added in: v20.4.0

[安定度: 1 - 試験的]

安定度: 1 安定度: 1 - 試験的

server.close() を呼び出し、サーバーが閉じたときに解決される Promise を返します。

server.setTimeout([msecs][, callback]) ​

[履歴]

バージョン変更点
v18.0.0callback 引数に無効なコールバックを渡すと、ERR_INVALID_CALLBACK ではなく ERR_INVALID_ARG_TYPE がスローされるようになりました。
v13.0.0デフォルトのタイムアウトが 120 秒から 0 (タイムアウトなし) に変更されました。
v8.4.0Added in: v8.4.0

http2 サーバーのリクエストのタイムアウト値を設定するために使用し、msecs ミリ秒後に Http2Server でアクティビティがない場合に呼び出されるコールバック関数を設定します。

指定されたコールバックは、'timeout' イベントのリスナーとして登録されます。

callback が関数でない場合、新しい ERR_INVALID_ARG_TYPE エラーがスローされます。

server.timeout ​

[沿革]

バージョン変更
v13.0.0デフォルトのタイムアウトが 120 秒から 0 (タイムアウトなし) に変更されました。
v8.4.0追加: v8.4.0
  • <number> タイムアウトまでの時間 (ミリ秒単位)。デフォルト: 0 (タイムアウトなし)

ソケットがタイムアウトしたと見なされるまでの非アクティブな時間 (ミリ秒単位)。

0 の値を指定すると、受信接続でのタイムアウト動作が無効になります。

ソケットのタイムアウトロジックは接続時に設定されるため、この値を変更しても、サーバーへの新しい接続にのみ影響し、既存の接続には影響しません。

server.updateSettings([settings]) ​

追加: v15.1.0, v14.17.0

提供された設定でサーバーを更新するために使用されます。

無効な settings 値の場合、ERR_HTTP2_INVALID_SETTING_VALUE をスローします。

無効な settings 引数の場合、ERR_INVALID_ARG_TYPE をスローします。

クラス: Http2SecureServer ​

追加: v8.4.0

Http2SecureServer のインスタンスは、http2.createSecureServer() 関数を使用して作成されます。Http2SecureServer クラスは、node:http2 モジュールによって直接エクスポートされません。

イベント: 'checkContinue' ​

追加: v8.5.0

'request' リスナーが登録されているか、http2.createSecureServer() にコールバック関数が指定されている場合、HTTP Expect: 100-continue を持つリクエストを受信するたびに 'checkContinue' イベントが発生します。このイベントがリッスンされていない場合、サーバーは必要に応じてステータス 100 Continue で自動的に応答します。

このイベントを処理するには、クライアントがリクエスト本文を送信し続ける場合は response.writeContinue() を呼び出し、クライアントがリクエスト本文を送信し続けるべきでない場合は適切な HTTP 応答 (例: 400 Bad Request) を生成します。

このイベントが発生して処理される場合、'request' イベントは発生しません。

イベント: 'connection' ​

追加: v8.4.0

このイベントは、TLSハンドシェイクが始まる前に、新しいTCPストリームが確立されたときに発生します。socketは通常、net.Socket 型のオブジェクトです。通常、ユーザーはこのイベントにアクセスする必要はありません。

このイベントは、HTTPサーバーに接続を注入するために、ユーザーによって明示的に発生させることもできます。その場合、任意の Duplex ストリームを渡すことができます。

イベント: 'request' ​

追加: v8.4.0

リクエストがあるたびに発生します。セッションごとに複数のリクエストがある場合があります。互換性 API を参照してください。

イベント: 'session' ​

追加: v8.4.0

'session' イベントは、Http2Session が Http2SecureServer によって作成されたときに発生します。

イベント: 'sessionError' ​

追加: v8.4.0

'sessionError' イベントは、Http2SecureServer に関連付けられた Http2Session オブジェクトによって 'error' イベントが発生したときに発生します。

イベント: 'stream' ​

追加: v8.4.0

'stream' イベントは、サーバーに関連付けられた Http2Session によって 'stream' イベントが発生したときに発生します。

Http2Session の 'stream' イベント も参照してください。

js
import { createSecureServer, constants } from 'node:http2';
const {
  HTTP2_HEADER_METHOD,
  HTTP2_HEADER_PATH,
  HTTP2_HEADER_STATUS,
  HTTP2_HEADER_CONTENT_TYPE,
} = constants;

const options = getOptionsSomehow();

const server = createSecureServer(options);
server.on('stream', (stream, headers, flags) => {
  const method = headers[HTTP2_HEADER_METHOD];
  const path = headers[HTTP2_HEADER_PATH];
  // ...
  stream.respond({
    [HTTP2_HEADER_STATUS]: 200,
    [HTTP2_HEADER_CONTENT_TYPE]: 'text/plain; charset=utf-8',
  });
  stream.write('hello ');
  stream.end('world');
});
js
const http2 = require('node:http2');
const {
  HTTP2_HEADER_METHOD,
  HTTP2_HEADER_PATH,
  HTTP2_HEADER_STATUS,
  HTTP2_HEADER_CONTENT_TYPE,
} = http2.constants;

const options = getOptionsSomehow();

const server = http2.createSecureServer(options);
server.on('stream', (stream, headers, flags) => {
  const method = headers[HTTP2_HEADER_METHOD];
  const path = headers[HTTP2_HEADER_PATH];
  // ...
  stream.respond({
    [HTTP2_HEADER_STATUS]: 200,
    [HTTP2_HEADER_CONTENT_TYPE]: 'text/plain; charset=utf-8',
  });
  stream.write('hello ');
  stream.end('world');
});

イベント: 'timeout' ​

追加: v8.4.0

'timeout' イベントは、http2secureServer.setTimeout() で設定されたミリ秒数だけサーバー上でアクティビティがない場合に発生します。 デフォルト: 2 分。

イベント: 'unknownProtocol' ​

[履歴]

バージョン変更点
v19.0.0クライアントが TLS ハンドシェイク中に ALPN 拡張を送信しなかった場合にのみ、このイベントが発生します。
v8.4.0追加: v8.4.0

'unknownProtocol' イベントは、接続クライアントが許可されたプロトコル (HTTP/2 または HTTP/1.1) のネゴシエーションに失敗した場合に発生します。イベントハンドラーは処理のためにソケットを受け取ります。このイベントに対してリスナーが登録されていない場合、接続は終了されます。タイムアウトは、http2.createSecureServer() に渡される 'unknownProtocolTimeout' オプションを使用して指定できます。

Node.js の以前のバージョンでは、allowHTTP1 が false であり、TLS ハンドシェイク中に、クライアントが ALPN 拡張を送信しないか、HTTP/2 (h2) を含まない ALPN 拡張を送信した場合に、このイベントが発生していました。新しいバージョンの Node.js では、allowHTTP1 が false であり、クライアントが ALPN 拡張を送信しない場合にのみ、このイベントが発生します。クライアントが HTTP/2 (または allowHTTP1 が true の場合は HTTP/1.1) を含まない ALPN 拡張を送信した場合、TLS ハンドシェイクは失敗し、セキュアな接続は確立されません。

互換性 API を参照してください。

server.close([callback]) ​

追加: v8.4.0

サーバーが新しいセッションを確立するのを停止します。これは、HTTP/2 セッションの永続的な性質により、新しいリクエストストリームの作成を妨げるものではありません。サーバーを正常にシャットダウンするには、すべてのアクティブなセッションで http2session.close() を呼び出してください。

callback が提供されている場合、サーバーが新しいセッションを許可しなくなっていても、すべてのアクティブなセッションが閉じられるまで呼び出されません。詳細については、tls.Server.close() を参照してください。

server.setTimeout([msecs][, callback]) ​

[履歴]

バージョン変更点
v18.0.0callback 引数に無効なコールバックを渡すと、ERR_INVALID_CALLBACK ではなく ERR_INVALID_ARG_TYPE がスローされるようになりました。
v8.4.0追加: v8.4.0

http2 セキュアサーバーリクエストのタイムアウト値を設定するために使用され、msecs ミリ秒後に Http2SecureServer でアクティビティがない場合に呼び出されるコールバック関数を設定します。

指定されたコールバックは、'timeout' イベントのリスナーとして登録されます。

callback が関数でない場合、新しい ERR_INVALID_ARG_TYPE エラーがスローされます。

server.timeout ​

[履歴]

バージョン変更点
v13.0.0デフォルトのタイムアウトが 120 秒から 0 (タイムアウトなし) に変更されました。
v8.4.0追加: v8.4.0
  • <number> タイムアウト時間 (ミリ秒単位)。 デフォルト: 0 (タイムアウトなし)

ソケットがタイムアウトしたと見なされるまでの非アクティブ時間 (ミリ秒単位)。

値が 0 の場合、受信接続でのタイムアウト動作が無効になります。

ソケットのタイムアウトロジックは接続時に設定されるため、この値を変更しても、既存の接続には影響せず、サーバーへの新しい接続にのみ影響します。

server.updateSettings([settings]) ​

追加: v15.1.0, v14.17.0

指定された設定でサーバーを更新するために使用されます。

無効な settings 値に対して ERR_HTTP2_INVALID_SETTING_VALUE をスローします。

無効な settings 引数に対して ERR_INVALID_ARG_TYPE をスローします。

http2.createServer([options][, onRequestHandler]) ​

[履歴]

バージョン変更点
v23.0.0streamResetBurst と streamResetRate が追加されました。
v13.0.0PADDING_STRATEGY_CALLBACK は、PADDING_STRATEGY_ALIGNED を指定するのと同じになり、selectPadding は削除されました。
v13.3.0, v12.16.0デフォルト値が 100 の maxSessionRejectedStreams オプションが追加されました。
v13.3.0, v12.16.0デフォルト値が 1000 の maxSessionInvalidFrames オプションが追加されました。
v12.4.0options パラメーターが net.createServer() オプションをサポートするようになりました。
v15.10.0, v14.16.0, v12.21.0, v10.24.0デフォルト値が 10000 の unknownProtocolTimeout オプションが追加されました。
v14.4.0, v12.18.0, v10.21.0デフォルト値が 32 の maxSettings オプションが追加されました。
v9.6.0Http1IncomingMessage および Http1ServerResponse オプションが追加されました。
v8.9.3デフォルトの制限が 10 の maxOutstandingPings オプションが追加されました。
v8.9.3デフォルトの制限が 128 ヘッダーペアの maxHeaderListPairs オプションが追加されました。
v8.4.0追加: v8.4.0

  • options <Object>

    • maxDeflateDynamicTableSize <number> ヘッダーフィールドをデフレートするための最大動的テーブルサイズを設定します。 デフォルト: 4Kib。

    • maxSettings <number> SETTINGS フレームごとの設定エントリの最大数を設定します。 許可される最小値は 1 です。 デフォルト: 32。

    • maxSessionMemory <number> Http2Session が使用を許可されている最大メモリを設定します。 値はメガバイト数で表されます (例: 1 は 1 メガバイトに相当します)。 許可される最小値は 1 です。 これはクレジットベースの制限であり、既存の Http2Stream によってこの制限を超える可能性がありますが、この制限を超えている間は新しい Http2Stream インスタンスは拒否されます。 現在の Http2Stream セッション数、ヘッダー圧縮テーブルの現在のメモリ使用量、送信待ちの現在のデータ、および未確認の PING および SETTINGS フレームはすべて、現在の制限にカウントされます。 デフォルト: 10。

    • maxHeaderListPairs <number> ヘッダーエントリの最大数を設定します。 これは、node:http モジュールの server.maxHeadersCount または request.maxHeadersCount と似ています。 最小値は 4 です。 デフォルト: 128。

    • maxOutstandingPings <number> 未処理の、未確認の ping の最大数を設定します。 デフォルト: 10。

    • maxSendHeaderBlockLength <number> シリアル化され、圧縮されたヘッダーのブロックの最大許容サイズを設定します。 この制限を超えるヘッダーを送信しようとすると、'frameError' イベントが発生し、ストリームが閉じられ、破棄されます。 これはヘッダーのブロック全体の最大許容サイズを設定しますが、nghttp2 (内部 http2 ライブラリ) には、圧縮されていないキーと値のペアごとに 65536 の制限があります。

    • paddingStrategy <number> HEADERS フレームと DATA フレームに使用するパディングの量を決定するために使用される戦略。 デフォルト: http2.constants.PADDING_STRATEGY_NONE。 値は次のいずれかになります。

    • http2.constants.PADDING_STRATEGY_NONE: パディングは適用されません。

    • http2.constants.PADDING_STRATEGY_MAX: 内部実装によって決定される、最大量のパディングが適用されます。

    • http2.constants.PADDING_STRATEGY_ALIGNED: 合計フレーム長 (9 バイトのヘッダーを含む) が 8 の倍数になるように、十分なパディングを適用しようとします。 各フレームについて、現在のフロー制御の状態と設定によって決定される、パディングバイトの最大許容数があります。 この最大値が、アライメントを保証するために必要な計算量よりも小さい場合、最大値が使用され、合計フレーム長が必ずしも 8 バイトでアライメントされるとは限りません。

    • peerMaxConcurrentStreams <number> SETTINGS フレームを受信したかのように、リモートピアの同時ストリームの最大数を設定します。 リモートピアが maxConcurrentStreams の独自の値を設定している場合、上書きされます。 デフォルト: 100。

    • maxSessionInvalidFrames <integer> セッションが閉じられるまでに許容される無効なフレームの最大数を設定します。 デフォルト: 1000。

    • maxSessionRejectedStreams <integer> セッションが閉じられるまでに許容される、作成時に拒否されたストリームの最大数を設定します。 各拒否は、ピアにこれ以上ストリームを開かないように指示する必要がある NGHTTP2_ENHANCE_YOUR_CALM エラーに関連付けられています。したがって、ストリームを開き続けることは、誤った動作をするピアの兆候と見なされます。 デフォルト: 100。

    • settings <HTTP/2 設定オブジェクト> 接続時にリモートピアに送信する初期設定。

    • streamResetBurst <number> および streamResetRate <number> 受信ストリームリセット (RST_STREAM フレーム) のレート制限を設定します。 いずれかの効果を得るには、両方の設定を設定する必要があり、デフォルトはそれぞれ 1000 と 33 です。

    • remoteCustomSettings <Array> 整数の値の配列は、受信した remoteSettings の CustomSettings プロパティに含まれる設定タイプを決定します。 許可される設定タイプに関する詳細については、Http2Settings オブジェクトの CustomSettings プロパティを参照してください。

    • Http1IncomingMessage <http.IncomingMessage> HTTP/1 フォールバックに使用される IncomingMessage クラスを指定します。 元の http.IncomingMessage を拡張するのに役立ちます。 デフォルト: http.IncomingMessage。

    • Http1ServerResponse <http.ServerResponse> HTTP/1 フォールバックに使用される ServerResponse クラスを指定します。 元の http.ServerResponse を拡張するのに役立ちます。 デフォルト: http.ServerResponse。

    • Http2ServerRequest <http2.Http2ServerRequest> 使用する Http2ServerRequest クラスを指定します。 元の Http2ServerRequest を拡張するのに役立ちます。 デフォルト: Http2ServerRequest。

    • Http2ServerResponse <http2.Http2ServerResponse> 使用する Http2ServerResponse クラスを指定します。 元の Http2ServerResponse を拡張するのに役立ちます。 デフォルト: Http2ServerResponse。

    • unknownProtocolTimeout <number> サーバーが 'unknownProtocol' が発行されたときに待機する必要があるタイムアウトをミリ秒単位で指定します。 その時間までにソケットが破棄されていない場合、サーバーはそれを破棄します。 デフォルト: 10000。

    • ...: net.createServer() オプションはすべて指定できます。

  • onRequestHandler <Function> 互換性 API を参照してください

  • 戻り値: <Http2Server>

Http2Session インスタンスを作成および管理する net.Server インスタンスを返します。

暗号化されていない HTTP/2 をサポートする既知のブラウザがないため、ブラウザクライアントと通信する場合は http2.createSecureServer() の使用が必要です。

js
import { createServer } from 'node:http2';

// 暗号化されていない HTTP/2 サーバーを作成します。
// 暗号化されていない HTTP/2 をサポートする既知のブラウザがないため、
// ブラウザクライアントと通信する場合は `createSecureServer()` の使用が必要です。
const server = createServer();

server.on('stream', (stream, headers) => {
  stream.respond({
    'content-type': 'text/html; charset=utf-8',
    ':status': 200,
  });
  stream.end('<h1>Hello World</h1>');
});

server.listen(8000);
js
const http2 = require('node:http2');

// 暗号化されていない HTTP/2 サーバーを作成します。
// 暗号化されていない HTTP/2 をサポートする既知のブラウザがないため、
// ブラウザクライアントと通信する場合は `http2.createSecureServer()` の使用が必要です。
const server = http2.createServer();

server.on('stream', (stream, headers) => {
  stream.respond({
    'content-type': 'text/html; charset=utf-8',
    ':status': 200,
  });
  stream.end('<h1>Hello World</h1>');
});

server.listen(8000);

http2.createSecureServer(options[, onRequestHandler]) ​

[履歴]

バージョン変更
v13.0.0PADDING_STRATEGY_CALLBACK が PADDING_STRATEGY_ALIGNED の提供と同等になり、selectPadding が削除されました。
v13.3.0, v12.16.0デフォルト値が 100 の maxSessionRejectedStreams オプションが追加されました。
v13.3.0, v12.16.0デフォルト値が 1000 の maxSessionInvalidFrames オプションが追加されました。
v15.10.0, v14.16.0, v12.21.0, v10.24.0デフォルト値が 10000 の unknownProtocolTimeout オプションが追加されました。
v14.4.0, v12.18.0, v10.21.0デフォルト値が 32 の maxSettings オプションが追加されました。
v10.12.0Http2Session の起動時に ORIGIN フレームを自動的に送信する origins オプションが追加されました。
v8.9.3デフォルトの制限値が 10 の maxOutstandingPings オプションが追加されました。
v8.9.3デフォルトの制限値が 128 ヘッダーペアの maxHeaderListPairs オプションが追加されました。
v8.4.0追加: v8.4.0

  • options <Object>

    • allowHTTP1 <boolean> HTTP/2 をサポートしていない着信クライアント接続は、true に設定すると HTTP/1.x にダウングレードされます。'unknownProtocol' イベントを参照してください。ALPN ネゴシエーション を参照してください。デフォルト: false。
    • maxDeflateDynamicTableSize <number> ヘッダーフィールドをデフレートするための最大動的テーブルサイズを設定します。デフォルト: 4Kib。
    • maxSettings <number> SETTINGS フレームあたりの設定エントリの最大数を設定します。許可される最小値は 1 です。デフォルト: 32。
    • maxSessionMemory <number> Http2Session が使用できる最大メモリを設定します。値はメガバイト単位で表されます。たとえば、1 は 1 メガバイトに相当します。許可される最小値は 1 です。これはクレジットベースの制限であり、既存の Http2Stream がこの制限を超える可能性がありますが、この制限を超えている間は新しい Http2Stream インスタンスは拒否されます。現在の Http2Stream セッション数、ヘッダー圧縮テーブルの現在のメモリ使用量、送信キューに入れられた現在のデータ、および未確認の PING および SETTINGS フレームはすべて、現在の制限に対してカウントされます。デフォルト: 10。
    • maxHeaderListPairs <number> ヘッダーエントリの最大数を設定します。これは、node:http モジュールの server.maxHeadersCount または request.maxHeadersCount と同様です。最小値は 4 です。デフォルト: 128。
    • maxOutstandingPings <number> 未処理で未確認の ping の最大数を設定します。デフォルト: 10。
    • maxSendHeaderBlockLength <number> シリアル化された圧縮ヘッダーブロックの最大許容サイズを設定します。この制限を超えるヘッダーを送信しようとすると、'frameError' イベントが発生し、ストリームが閉じて破棄されます。
    • paddingStrategy <number> HEADERS および DATA フレームに使用するパディングの量を決定するために使用される戦略。デフォルト: http2.constants.PADDING_STRATEGY_NONE。値は次のいずれかになります。
    • http2.constants.PADDING_STRATEGY_NONE: パディングは適用されません。
    • http2.constants.PADDING_STRATEGY_MAX: 内部実装によって決定されるパディングの最大量が適用されます。
    • http2.constants.PADDING_STRATEGY_ALIGNED: 9 バイトのヘッダーを含む合計フレーム長が 8 の倍数になるように、十分なパディングを適用しようとします。フレームごとに、現在のフロー制御の状態と設定によって決定される、許可されるパディングバイトの最大数があります。この最大値がアライメントを保証するために必要な計算された量よりも小さい場合、最大値が使用され、合計フレーム長は必ずしも 8 バイトでアライメントされません。
    • peerMaxConcurrentStreams <number> SETTINGS フレームを受信した場合と同様に、リモートピアの同時ストリームの最大数を設定します。リモートピアが maxConcurrentStreams の独自の値に設定すると、オーバーライドされます。デフォルト: 100。
    • maxSessionInvalidFrames <integer> セッションが閉じられるまでに許容される無効なフレームの最大数を設定します。デフォルト: 1000。
    • maxSessionRejectedStreams <integer> セッションが閉じられるまでに許容される、作成時に拒否されたストリームの最大数を設定します。各拒否は NGHTTP2_ENHANCE_YOUR_CALM エラーに関連付けられており、ピアにこれ以上ストリームを開かないように指示する必要があります。したがって、ストリームを開き続けることは、不正なピアの兆候と見なされます。デフォルト: 100。
    • settings <HTTP/2 設定オブジェクト> 接続時にリモートピアに送信する初期設定。
    • remoteCustomSettings <Array> 整数の値の配列は、受信した remoteSettings の customSettings プロパティに含まれる設定タイプを決定します。許可される設定タイプについては、Http2Settings オブジェクトの customSettings プロパティを参照してください。
    • ...: tls.createServer() オプションはすべて指定できます。サーバーの場合、ID オプション (pfx または key/cert) は通常必要です。
    • origins <string[]> 新しいサーバー Http2Session の作成直後に ORIGIN フレーム内で送信するオリジン文字列の配列。
    • unknownProtocolTimeout <number> サーバーが 'unknownProtocol' イベントが発行されたときに待機する必要があるタイムアウトをミリ秒単位で指定します。ソケットがその時間までに破棄されていない場合、サーバーはそれを破棄します。デフォルト: 10000。

  • onRequestHandler <Function> 互換性 API を参照してください。

  • 戻り値: <Http2SecureServer>

Http2Session インスタンスを作成および管理する tls.Server インスタンスを返します。

js
import { createSecureServer } from 'node:http2';
import { readFileSync } from 'node:fs';

const options = {
  key: readFileSync('server-key.pem'),
  cert: readFileSync('server-cert.pem'),
};

// Create a secure HTTP/2 server
const server = createSecureServer(options);

server.on('stream', (stream, headers) => {
  stream.respond({
    'content-type': 'text/html; charset=utf-8',
    ':status': 200,
  });
  stream.end('<h1>Hello World</h1>');
});

server.listen(8443);
js
const http2 = require('node:http2');
const fs = require('node:fs');

const options = {
  key: fs.readFileSync('server-key.pem'),
  cert: fs.readFileSync('server-cert.pem'),
};

// Create a secure HTTP/2 server
const server = http2.createSecureServer(options);

server.on('stream', (stream, headers) => {
  stream.respond({
    'content-type': 'text/html; charset=utf-8',
    ':status': 200,
  });
  stream.end('<h1>Hello World</h1>');
});

server.listen(8443);

http2.connect(authority[, options][, listener]) ​

[History]

VersionChanges
v13.0.0PADDING_STRATEGY_CALLBACK が PADDING_STRATEGY_ALIGNED を提供するのと同じになり、selectPadding が削除されました。
v15.10.0, v14.16.0, v12.21.0, v10.24.0デフォルト値が 10000 の unknownProtocolTimeout オプションが追加されました。
v14.4.0, v12.18.0, v10.21.0デフォルト値が 32 の maxSettings オプションが追加されました。
v8.9.3デフォルト制限が 10 の maxOutstandingPings オプションが追加されました。
v8.9.3デフォルト制限が 128 ヘッダーペアの maxHeaderListPairs オプションが追加されました。
v8.4.0追加: v8.4.0

  • authority <string> | <URL> 接続先のリモート HTTP/2 サーバー。これは、http:// または https:// プレフィックス、ホスト名、および IP ポート（デフォルト以外のポートが使用されている場合）を持つ最小限の有効な URL の形式である必要があります。URL のユーザー情報（ユーザー ID とパスワード）、パス、クエリストリング、およびフラグメントの詳細は無視されます。

  • options <Object>

    • maxDeflateDynamicTableSize <number> ヘッダーフィールドをデフレートするための最大の動的テーブルサイズを設定します。デフォルト: 4Kib。

    • maxSettings <number> SETTINGS フレームあたりの設定エントリの最大数を設定します。許容される最小値は 1 です。デフォルト: 32。

    • maxSessionMemory<number> Http2Session が使用できる最大のメモリを設定します。値はメガバイト数で表されます（例：1 は 1 メガバイトに相当）。許容される最小値は 1 です。これはクレジットベースの制限であり、既存の Http2Stream によってこの制限を超える可能性がありますが、この制限を超えている間は新しい Http2Stream インスタンスは拒否されます。現在の Http2Stream セッション数、ヘッダー圧縮テーブルの現在のメモリ使用量、送信待ちの現在のデータ、未確認の PING および SETTINGS フレームはすべて、現在の制限にカウントされます。デフォルト: 10。

    • maxHeaderListPairs <number> ヘッダーエントリの最大数を設定します。これは、node:http モジュールの server.maxHeadersCount または request.maxHeadersCount と同様です。最小値は 1 です。デフォルト: 128。

    • maxOutstandingPings <number> 未処理の、未確認の ping の最大数を設定します。デフォルト: 10。

    • maxReservedRemoteStreams <number> クライアントが任意の時点で受け入れる予約済みプッシュストリームの最大数を設定します。現在予約されているプッシュストリームの数がこの制限に達すると、サーバーから送信された新しいプッシュストリームは自動的に拒否されます。許容される最小値は 0 です。許容される最大値は 2-1 です。負の値はこのオプションを許容される最大値に設定します。デフォルト: 200。

    • maxSendHeaderBlockLength <number> シリアライズされ、圧縮されたヘッダーのブロックに対して許可される最大サイズを設定します。この制限を超えるヘッダーを送信しようとすると、'frameError' イベントが発行され、ストリームが閉じられて破棄されます。

    • paddingStrategy <number> HEADERS および DATA フレームに使用するパディングの量を決定するために使用される戦略。デフォルト: http2.constants.PADDING_STRATEGY_NONE。値は次のいずれかになります。

    • http2.constants.PADDING_STRATEGY_NONE: パディングは適用されません。

    • http2.constants.PADDING_STRATEGY_MAX: 内部実装によって決定される、最大のパディング量が適用されます。

    • http2.constants.PADDING_STRATEGY_ALIGNED: 9 バイトのヘッダーを含む合計フレーム長が 8 の倍数になるように、十分なパディングを適用しようとします。各フレームには、現在のフロー制御の状態と設定によって決定される、許可されるパディングバイトの最大数があります。この最大数が、アラインメントを確保するために必要な計算量よりも少ない場合、最大値が使用され、合計フレーム長が必ずしも 8 バイトでアラインメントされるとは限りません。

    • peerMaxConcurrentStreams <number> リモートピアの同時ストリームの最大数を、SETTINGS フレームを受信したかのように設定します。リモートピアが maxConcurrentStreams の独自の値​​を設定している場合は、オーバーライドされます。デフォルト: 100。

    • protocol <string> authority で設定されていない場合、接続に使用するプロトコル。値は 'http:' または 'https:' のいずれかになります。デフォルト: 'https:'

    • settings <HTTP/2 設定オブジェクト> 接続時にリモートピアに送信する初期設定。

    • remoteCustomSettings <Array> 整数の値の配列は、受信した remoteSettings の CustomSettings プロパティに含まれる設定タイプを決定します。許可される設定タイプに関する詳細については、Http2Settings オブジェクトの CustomSettings プロパティを参照してください。

    • createConnection <Function> connect に渡された URL インスタンスと options オブジェクトを受け取り、このセッションの接続として使用される任意の Duplex ストリームを返すオプションのコールバック。

    • ...: 任意の net.connect() または tls.connect() オプションを指定できます。

    • unknownProtocolTimeout <number> 'unknownProtocol' イベントが発行されたときにサーバーが待機する必要があるタイムアウトをミリ秒単位で指定します。ソケットがその時間までに破棄されていない場合、サーバーはそれを破棄します。デフォルト: 10000。

  • listener <Function> 'connect' イベントの 1 回限りのリスナーとして登録されます。

  • 戻り値: <ClientHttp2Session>

ClientHttp2Session インスタンスを返します。

js
import { connect } from 'node:http2';
const client = connect('https://localhost:1234');

/* Use the client */

client.close();
js
const http2 = require('node:http2');
const client = http2.connect('https://localhost:1234');

/* Use the client */

client.close();

http2.constants ​

Added in: v8.4.0

RST_STREAMとGOAWAYのエラーコード ​

値名前定数
0x00No Errorhttp2.constants.NGHTTP2_NO_ERROR
0x01Protocol Errorhttp2.constants.NGHTTP2_PROTOCOL_ERROR
0x02Internal Errorhttp2.constants.NGHTTP2_INTERNAL_ERROR
0x03Flow Control Errorhttp2.constants.NGHTTP2_FLOW_CONTROL_ERROR
0x04Settings Timeouthttp2.constants.NGHTTP2_SETTINGS_TIMEOUT
0x05Stream Closedhttp2.constants.NGHTTP2_STREAM_CLOSED
0x06Frame Size Errorhttp2.constants.NGHTTP2_FRAME_SIZE_ERROR
0x07Refused Streamhttp2.constants.NGHTTP2_REFUSED_STREAM
0x08Cancelhttp2.constants.NGHTTP2_CANCEL
0x09Compression Errorhttp2.constants.NGHTTP2_COMPRESSION_ERROR
0x0aConnect Errorhttp2.constants.NGHTTP2_CONNECT_ERROR
0x0bEnhance Your Calmhttp2.constants.NGHTTP2_ENHANCE_YOUR_CALM
0x0cInadequate Securityhttp2.constants.NGHTTP2_INADEQUATE_SECURITY
0x0dHTTP/1.1 Requiredhttp2.constants.NGHTTP2_HTTP_1_1_REQUIRED
'timeout' イベントは、http2server.setTimeout() を使用して設定された指定されたミリ秒数、サーバーでアクティビティがない場合に発生します。

http2.getDefaultSettings() ​

Added in: v8.4.0

Http2Session インスタンスのデフォルト設定を含むオブジェクトを返します。このメソッドは呼び出されるたびに新しいオブジェクトインスタンスを返すため、返されたインスタンスは安全に使用するために変更できます。

http2.getPackedSettings([settings]) ​

Added in: v8.4.0

HTTP/2 仕様で指定されている、指定されたHTTP/2設定のシリアル化された表現を含む Buffer インスタンスを返します。これは HTTP2-Settings ヘッダーフィールドで使用することを目的としています。

js
import { getPackedSettings } from 'node:http2';

const packed = getPackedSettings({ enablePush: false });

console.log(packed.toString('base64'));
// Prints: AAIAAAAA
js
const http2 = require('node:http2');

const packed = http2.getPackedSettings({ enablePush: false });

console.log(packed.toString('base64'));
// Prints: AAIAAAAA

http2.getUnpackedSettings(buf) ​

Added in: v8.4.0

http2.getPackedSettings() によって生成された、指定された Buffer からデシリアライズされた設定を含む、HTTP/2 設定オブジェクト を返します。

http2.performServerHandshake(socket[, options]) ​

Added in: v21.7.0, v20.12.0

既存のソケットから HTTP/2 サーバーセッションを作成します。

http2.sensitiveHeaders ​

Added in: v15.0.0, v14.18.0

このシンボルは、機密と見なされるヘッダーのリストを提供するために、配列値を持つ HTTP/2 ヘッダーオブジェクトのプロパティとして設定できます。詳細については、機密ヘッダー を参照してください。

ヘッダーオブジェクト ​

ヘッダーは、JavaScript オブジェクトの独自のプロパティとして表されます。プロパティキーは小文字にシリアライズされます。プロパティ値は文字列である必要があります (そうでない場合は文字列に強制変換されます)。または、文字列の Array (ヘッダーフィールドごとに複数の値を送信するため) である必要があります。

js
const headers = {
  ':status': '200',
  'content-type': 'text-plain',
  'ABC': ['has', 'more', 'than', 'one', 'value'],
};

stream.respond(headers);

コールバック関数に渡されるヘッダーオブジェクトは、null プロトタイプを持ちます。これは、Object.prototype.toString() や Object.prototype.hasOwnProperty() などの通常の JavaScript オブジェクトメソッドが機能しないことを意味します。

受信ヘッダーの場合:

  • :status ヘッダーは number に変換されます。
  • :status、:method、:authority、:scheme、:path、:protocol、age、authorization、access-control-allow-credentials、access-control-max-age、access-control-request-method、content-encoding、content-language、content-length、content-location、content-md5、content-range、content-type、date、dnt、etag、expires、from、host、if-match、if-modified-since、if-none-match、if-range、if-unmodified-since、last-modified、location、max-forwards、proxy-authorization、range、referer、retry-after、tk、upgrade-insecure-requests、user-agent、または x-content-type-options の重複は破棄されます。
  • set-cookie は常に配列です。重複は配列に追加されます。
  • 重複する cookie ヘッダーの場合、値は '; ' で結合されます。
  • 他のすべてのヘッダーの場合、値は ', ' で結合されます。
js
import { createServer } from 'node:http2';
const server = createServer();
server.on('stream', (stream, headers) => {
  console.log(headers[':path']);
  console.log(headers.ABC);
});
js
const http2 = require('node:http2');
const server = http2.createServer();
server.on('stream', (stream, headers) => {
  console.log(headers[':path']);
  console.log(headers.ABC);
});

センシティブなヘッダー ​

HTTP2ヘッダーはセンシティブとしてマークできます。これは、HTTP/2ヘッダー圧縮アルゴリズムがそれらをインデックスしないことを意味します。これは、エントロピーが低く、攻撃者にとって価値があると見なされる可能性があるヘッダー値（例：CookieやAuthorization）にとって意味があります。これを実現するには、ヘッダー名を配列として[http2.sensitiveHeaders]プロパティに追加します。

js
const headers = {
  ':status': '200',
  'content-type': 'text-plain',
  'cookie': 'some-cookie',
  'other-sensitive-header': 'very secret data',
  [http2.sensitiveHeaders]: ['cookie', 'other-sensitive-header'],
};

stream.respond(headers);

Authorizationや短いCookieヘッダーなど、一部のヘッダーでは、このフラグは自動的に設定されます。

このプロパティは、受信したヘッダーにも設定されます。これには、自動的にマークされたものを含め、センシティブとしてマークされたすべてのヘッダーの名前が含まれます。

Settingsオブジェクト ​

[履歴]

バージョン変更
v12.12.0maxConcurrentStreams設定がより厳密になりました。
v8.9.3maxHeaderListSize設定が厳密に適用されるようになりました。
v8.4.0v8.4.0で追加

http2.getDefaultSettings()、http2.getPackedSettings()、http2.createServer()、http2.createSecureServer()、http2session.settings()、http2session.localSettings、およびhttp2session.remoteSettings APIは、Http2Sessionオブジェクトの構成設定を定義するオブジェクトを返すか、入力として受信します。これらのオブジェクトは、次のプロパティを含む通常のJavaScriptオブジェクトです。

  • headerTableSize <number> ヘッダー圧縮に使用される最大バイト数を指定します。許可される最小値は0です。許可される最大値は2^32-1です。 デフォルト: 4096。
  • enablePush <boolean> HTTP/2プッシュストリームをHttp2Sessionインスタンスで許可する場合はtrueを指定します。 デフォルト: true。
  • initialWindowSize <number> ストリームレベルのフロー制御のために、送信者の初期ウィンドウサイズをバイト単位で指定します。許可される最小値は0です。許可される最大値は2^32-1です。 デフォルト: 65535。
  • maxFrameSize <number> 最大フレームペイロードのサイズをバイト単位で指定します。許可される最小値は16,384です。許可される最大値は2^24-1です。 デフォルト: 16384。
  • maxConcurrentStreams <number> Http2Sessionで許可される同時ストリームの最大数を指定します。デフォルト値はありません。これは、少なくとも理論的には、Http2Sessionで任意の時点で2^31-1ストリームを同時に開くことができることを意味します。最小値は0です。許可される最大値は2^31-1です。 デフォルト: 4294967295。
  • maxHeaderListSize <number> 受け入れられるヘッダーリストの最大サイズ（圧縮されていないオクテット）を指定します。許可される最小値は0です。許可される最大値は2^32-1です。 デフォルト: 65535。
  • maxHeaderSize <number> maxHeaderListSizeのエイリアス。
  • enableConnectProtocol <boolean> RFC 8441で定義されている「拡張コネクトプロトコル」を有効にする場合はtrueを指定します。この設定は、サーバーから送信された場合にのみ意味があります。特定のHttp2SessionでenableConnectProtocol設定が有効になると、無効にすることはできません。 デフォルト: false。
  • customSettings <Object> ノードおよび基盤となるライブラリにまだ実装されていない追加の設定を指定します。オブジェクトのキーは、設定タイプの数値（[RFC 7540]によって確立された「HTTP/2 SETTINGS」レジストリで定義されている）を定義し、値は設定の実際の数値を定義します。設定タイプは、1から2^16-1の範囲の整数でなければなりません。ノードですでに処理されている設定タイプ、つまり現在6よりも大きいものであってはなりませんが、エラーではありません。値は、0から2^32-1の範囲の符号なし整数である必要があります。現在、最大10個のカスタム設定がサポートされています。これは、SETTINGSの送信、またはサーバーまたはクライアントオブジェクトのremoteCustomSettingsオプションで指定された設定値の受信でのみサポートされています。設定が将来のノードバージョンでネイティブにサポートされる場合に備えて、ネイティブに処理される設定のインターフェイスで、設定IDのcustomSettingsメカニズムを混在させないでください。

settingsオブジェクトのその他すべてのプロパティは無視されます。

エラー処理 ​

node:http2 モジュールを使用する際に発生する可能性のあるエラー条件はいくつかあります。

検証エラーは、不正な引数、オプション、または設定値が渡された場合に発生します。これらは常に同期的な throw によって報告されます。

状態エラーは、誤ったタイミングでアクションが試行された場合に発生します（たとえば、ストリームが閉じた後にストリームでデータを送信しようとするなど）。これらは、エラーが発生する場所とタイミングに応じて、同期的な throw または Http2Stream、Http2Session、または HTTP/2 Server オブジェクトの 'error' イベントを介して報告されます。

内部エラーは、HTTP/2 セッションが予期せず失敗した場合に発生します。これらは、Http2Session または HTTP/2 Server オブジェクトの 'error' イベントを介して報告されます。

プロトコルエラーは、さまざまな HTTP/2 プロトコルの制約に違反した場合に発生します。これらは、エラーが発生する場所とタイミングに応じて、同期的な throw または Http2Stream、Http2Session、または HTTP/2 Server オブジェクトの 'error' イベントを介して報告されます。

ヘッダー名と値における無効な文字の処理 ​

HTTP/2 の実装では、HTTP ヘッダー名と値における無効な文字の処理が HTTP/1 の実装よりも厳密になっています。

ヘッダーフィールド名は大文字と小文字を区別しません。また、ワイヤ上では厳密に小文字の文字列として送信されます。Node.js によって提供される API では、ヘッダー名を混合ケースの文字列（例：Content-Type）として設定できますが、送信時に小文字（例：content-type）に変換されます。

ヘッダーフィールド名には、次の ASCII 文字の 1 つ以上のみを含める必要があります：a-z、A-Z、0-9、!、#、$、%、&、'、*、+、-、.、^、_、`（バッククォート）、|、および ~。

HTTP ヘッダーフィールド名内で無効な文字を使用すると、プロトコルエラーが報告されてストリームが閉じられます。

ヘッダーフィールド値はより寛容に処理されますが、HTTP 仕様の要件に従って、改行文字またはキャリッジリターン文字を含めるべきではなく、US-ASCII 文字に制限する必要があります。

クライアントでプッシュストリームをプッシュする ​

クライアントでプッシュされたストリームを受信するには、ClientHttp2Session で 'stream' イベントのリスナーを設定します。

js
import { connect } from 'node:http2';

const client = connect('http://localhost');

client.on('stream', (pushedStream, requestHeaders) => {
  pushedStream.on('push', (responseHeaders) => {
    // レスポンスヘッダーを処理する
  });
  pushedStream.on('data', (chunk) => { /* プッシュされたデータを処理する */ });
});

const req = client.request({ ':path': '/' });
js
const http2 = require('node:http2');

const client = http2.connect('http://localhost');

client.on('stream', (pushedStream, requestHeaders) => {
  pushedStream.on('push', (responseHeaders) => {
    // レスポンスヘッダーを処理する
  });
  pushedStream.on('data', (chunk) => { /* プッシュされたデータを処理する */ });
});

const req = client.request({ ':path': '/' });

CONNECT メソッドのサポート ​

CONNECT メソッドは、HTTP/2 サーバーが TCP/IP 接続のプロキシとして使用されることを許可するために使用されます。

シンプルな TCP サーバー：

js
import { createServer } from 'node:net';

const server = createServer((socket) => {
  let name = '';
  socket.setEncoding('utf8');
  socket.on('data', (chunk) => name += chunk);
  socket.on('end', () => socket.end(`hello ${name}`));
});

server.listen(8000);
js
const net = require('node:net');

const server = net.createServer((socket) => {
  let name = '';
  socket.setEncoding('utf8');
  socket.on('data', (chunk) => name += chunk);
  socket.on('end', () => socket.end(`hello ${name}`));
});

server.listen(8000);

HTTP/2 CONNECT プロキシ：

js
import { createServer, constants } from 'node:http2';
const { NGHTTP2_REFUSED_STREAM, NGHTTP2_CONNECT_ERROR } = constants;
import { connect } from 'node:net';

const proxy = createServer();
proxy.on('stream', (stream, headers) => {
  if (headers[':method'] !== 'CONNECT') {
    // CONNECT リクエストのみを受け入れる
    stream.close(NGHTTP2_REFUSED_STREAM);
    return;
  }
  const auth = new URL(`tcp://${headers[':authority']}`);
  // ホスト名とポートが、このプロキシが接続するべきものかどうかを検証することを強くお勧めします。
  const socket = connect(auth.port, auth.hostname, () => {
    stream.respond();
    socket.pipe(stream);
    stream.pipe(socket);
  });
  socket.on('error', (error) => {
    stream.close(NGHTTP2_CONNECT_ERROR);
  });
});

proxy.listen(8001);
js
const http2 = require('node:http2');
const { NGHTTP2_REFUSED_STREAM } = http2.constants;
const net = require('node:net');

const proxy = http2.createServer();
proxy.on('stream', (stream, headers) => {
  if (headers[':method'] !== 'CONNECT') {
    // CONNECT リクエストのみを受け入れる
    stream.close(NGHTTP2_REFUSED_STREAM);
    return;
  }
  const auth = new URL(`tcp://${headers[':authority']}`);
  // ホスト名とポートが、このプロキシが接続するべきものかどうかを検証することを強くお勧めします。
  const socket = net.connect(auth.port, auth.hostname, () => {
    stream.respond();
    socket.pipe(stream);
    stream.pipe(socket);
  });
  socket.on('error', (error) => {
    stream.close(http2.constants.NGHTTP2_CONNECT_ERROR);
  });
});

proxy.listen(8001);

HTTP/2 CONNECT クライアント：

js
import { connect, constants } from 'node:http2';

const client = connect('http://localhost:8001');

// CONNECT リクエストでは ':path' および ':scheme' ヘッダーを指定してはいけません
// そうしないとエラーがスローされます。
const req = client.request({
  ':method': 'CONNECT',
  ':authority': 'localhost:8000',
});

req.on('response', (headers) => {
  console.log(headers[constants.HTTP2_HEADER_STATUS]);
});
let data = '';
req.setEncoding('utf8');
req.on('data', (chunk) => data += chunk);
req.on('end', () => {
  console.log(`The server says: ${data}`);
  client.close();
});
req.end('Jane');
js
const http2 = require('node:http2');

const client = http2.connect('http://localhost:8001');

// CONNECT リクエストでは ':path' および ':scheme' ヘッダーを指定してはいけません
// そうしないとエラーがスローされます。
const req = client.request({
  ':method': 'CONNECT',
  ':authority': 'localhost:8000',
});

req.on('response', (headers) => {
  console.log(headers[http2.constants.HTTP2_HEADER_STATUS]);
});
let data = '';
req.setEncoding('utf8');
req.on('data', (chunk) => data += chunk);
req.on('end', () => {
  console.log(`The server says: ${data}`);
  client.close();
});
req.end('Jane');

拡張 CONNECT プロトコル ​

RFC 8441 は、HTTP/2 に対する "拡張 CONNECT プロトコル" 拡張を定義しています。これは、他の通信プロトコル (WebSockets など) のトンネルとして CONNECT メソッドを使用して Http2Stream の使用を開始するために使用できます。

拡張 CONNECT プロトコルの使用は、HTTP/2 サーバーが enableConnectProtocol 設定を使用することによって有効になります。

js
import { createServer } from 'node:http2';
const settings = { enableConnectProtocol: true };
const server = createServer({ settings });
js
const http2 = require('node:http2');
const settings = { enableConnectProtocol: true };
const server = http2.createServer({ settings });

クライアントが拡張 CONNECT を使用できることを示す SETTINGS フレームをサーバーから受信すると、':protocol' HTTP/2 疑似ヘッダーを使用する CONNECT リクエストを送信できます。

js
import { connect } from 'node:http2';
const client = connect('http://localhost:8080');
client.on('remoteSettings', (settings) => {
  if (settings.enableConnectProtocol) {
    const req = client.request({ ':method': 'CONNECT', ':protocol': 'foo' });
    // ...
  }
});
js
const http2 = require('node:http2');
const client = http2.connect('http://localhost:8080');
client.on('remoteSettings', (settings) => {
  if (settings.enableConnectProtocol) {
    const req = client.request({ ':method': 'CONNECT', ':protocol': 'foo' });
    // ...
  }
});

互換性 API ​

互換性 API は、HTTP/2 を使用する際に HTTP/1 と同様の開発者体験を提供し、HTTP/1 と HTTP/2 の両方をサポートするアプリケーションを開発できるようにすることを目的としています。この API は、HTTP/1 の パブリック API のみを対象としています。ただし、多くのモジュールは内部メソッドまたは状態を使用しており、それらは完全に異なる実装であるため、サポートされていません。

次の例は、互換性 API を使用して HTTP/2 サーバーを作成します。

js
import { createServer } from 'node:http2';
const server = createServer((req, res) => {
  res.setHeader('Content-Type', 'text/html');
  res.setHeader('X-Foo', 'bar');
  res.writeHead(200, { 'Content-Type': 'text/plain; charset=utf-8' });
  res.end('ok');
});
js
const http2 = require('node:http2');
const server = http2.createServer((req, res) => {
  res.setHeader('Content-Type', 'text/html');
  res.setHeader('X-Foo', 'bar');
  res.writeHead(200, { 'Content-Type': 'text/plain; charset=utf-8' });
  res.end('ok');
});

HTTPS および HTTP/2 サーバーを混在させて作成するには、ALPN ネゴシエーション セクションを参照してください。非 TLS HTTP/1 サーバーからのアップグレードはサポートされていません。

HTTP/2 互換性 API は、Http2ServerRequest および Http2ServerResponse で構成されています。これらは HTTP/1 との API 互換性を目指していますが、プロトコル間の違いを隠蔽していません。例として、HTTP コードのステータスメッセージは無視されます。

ALPN ネゴシエーション ​

ALPN ネゴシエーションにより、同じソケット上で HTTPS と HTTP/2 の両方をサポートできます。 req および res オブジェクトは HTTP/1 または HTTP/2 のいずれかであり、アプリケーションは HTTP/1 の公開 API のみに制限し、HTTP/2 のより高度な機能を使用できるかどうかを検出する必要があります。

次の例は、両方のプロトコルをサポートするサーバーを作成します。

js
import { createSecureServer } from 'node:http2';
import { readFileSync } from 'node:fs';

const cert = readFileSync('./cert.pem');
const key = readFileSync('./key.pem');

const server = createSecureServer(
  { cert, key, allowHTTP1: true },
  onRequest,
).listen(8000);

function onRequest(req, res) {
  // HTTPS リクエストか HTTP/2 かを検出します
  const { socket: { alpnProtocol } } = req.httpVersion === '2.0' ?
    req.stream.session : req;
  res.writeHead(200, { 'content-type': 'application/json' });
  res.end(JSON.stringify({
    alpnProtocol,
    httpVersion: req.httpVersion,
  }));
}
js
const { createSecureServer } = require('node:http2');
const { readFileSync } = require('node:fs');

const cert = readFileSync('./cert.pem');
const key = readFileSync('./key.pem');

const server = createSecureServer(
  { cert, key, allowHTTP1: true },
  onRequest,
).listen(4443);

function onRequest(req, res) {
  // HTTPS リクエストか HTTP/2 かを検出します
  const { socket: { alpnProtocol } } = req.httpVersion === '2.0' ?
    req.stream.session : req;
  res.writeHead(200, { 'content-type': 'application/json' });
  res.end(JSON.stringify({
    alpnProtocol,
    httpVersion: req.httpVersion,
  }));
}

'request' イベントは、HTTPS と HTTP/2 の両方で同じように動作します。

Class: http2.Http2ServerRequest ​

追加: v8.4.0

Http2ServerRequest オブジェクトは、http2.Server または http2.SecureServer によって作成され、'request' イベントの最初の引数として渡されます。 リクエストのステータス、ヘッダー、およびデータにアクセスするために使用できます。

イベント: 'aborted' ​

追加: v8.4.0

'aborted' イベントは、Http2ServerRequestインスタンスが通信中に異常に中断された場合に発生します。

'aborted' イベントは、Http2ServerRequestの書き込み側がまだ終了していない場合にのみ発生します。

イベント: 'close' ​

追加: v8.4.0

基になるHttp2Streamが閉じられたことを示します。 'end' と同様に、このイベントはレスポンスごとに一度だけ発生します。

request.aborted ​

追加: v10.1.0

リクエストが中断された場合、request.abortedプロパティはtrueになります。

request.authority ​

追加: v8.4.0

リクエストのオーソリティ擬似ヘッダーフィールド。 HTTP/2 ではリクエストで :authority または host のいずれかを設定できるため、この値は、req.headers[':authority'] が存在する場合はそこから導出されます。 そうでない場合は、req.headers['host'] から導出されます。

request.complete ​

追加: v12.10.0

リクエストが完了、中断、または破棄された場合、request.completeプロパティはtrueになります。

request.connection ​

追加: v8.4.0

非推奨: v13.0.0 から

[安定性: 0 - 非推奨]

安定性: 0 安定性: 0 - 非推奨。 request.socket を使用してください。

request.socket を参照してください。

request.destroy([error]) ​

追加: v8.4.0

Http2ServerRequest を受信した Http2Stream で destroy() を呼び出します。 error が指定された場合、'error' イベントが発生し、error がイベントのリスナーに引数として渡されます。

ストリームがすでに破棄されている場合は何も行いません。

request.headers ​

Added in: v8.4.0

リクエスト/レスポンスヘッダーオブジェクト。

ヘッダー名と値のキーと値のペア。ヘッダー名は小文字化されます。

js
// 以下のような内容が出力されます:
//
// { 'user-agent': 'curl/7.22.0',
//   host: '127.0.0.1:8000',
//   accept: '*/*' }
console.log(request.headers);

HTTP/2 ヘッダーオブジェクト を参照してください。

HTTP/2 では、リクエストパス、ホスト名、プロトコル、およびメソッドは、: 文字で始まる特別なヘッダーとして表されます (例: ':path')。これらの特別なヘッダーは request.headers オブジェクトに含まれます。これらの特別なヘッダーを誤って変更しないように注意する必要があります。変更するとエラーが発生する可能性があります。たとえば、リクエストからすべてのヘッダーを削除するとエラーが発生します。

js
removeAllHeaders(request.headers);
assert(request.url);   // :path ヘッダーが削除されたため失敗します

request.httpVersion ​

Added in: v8.4.0

サーバーリクエストの場合、クライアントによって送信された HTTP バージョン。クライアントレスポンスの場合、接続先のサーバーの HTTP バージョン。 '2.0' を返します。

また、message.httpVersionMajor は最初の整数であり、message.httpVersionMinor は 2 番目の整数です。

request.method ​

Added in: v8.4.0

文字列としてのリクエストメソッド。読み取り専用。例: 'GET', 'DELETE'。

request.rawHeaders ​

Added in: v8.4.0

受信したとおりの未加工のリクエスト/レスポンスヘッダーのリスト。

キーと値は同じリストにあります。これはタプルのリスト ではありません。したがって、偶数番号のオフセットはキー値であり、奇数番号のオフセットは関連付けられた値です。

ヘッダー名は小文字化されず、重複はマージされません。

js
// 以下のような内容が出力されます:
//
// [ 'user-agent',
//   'this is invalid because there can be only one',
//   'User-Agent',
//   'curl/7.22.0',
//   'Host',
//   '127.0.0.1:8000',
//   'ACCEPT',
//   '*/*' ]
console.log(request.rawHeaders);

request.rawTrailers ​

Added in: v8.4.0

生のリクエスト/レスポンスのトレーラーキーと値は、受信したとおりに正確に表現されます。 'end' イベントでのみ設定されます。

request.scheme ​

Added in: v8.4.0

ターゲットURLのスキーム部分を示すリクエストスキームの疑似ヘッダーフィールド。

request.setTimeout(msecs, callback) ​

Added in: v8.4.0

Http2Stream のタイムアウト値を msecs に設定します。callback が指定された場合、レスポンスオブジェクトの 'timeout' イベントのリスナーとして追加されます。

リクエスト、レスポンス、またはサーバーに 'timeout' リスナーが追加されていない場合、Http2Stream はタイムアウト時に破棄されます。ハンドラーがリクエスト、レスポンス、またはサーバーの 'timeout' イベントに割り当てられている場合、タイムアウトしたソケットは明示的に処理する必要があります。

request.socket ​

Added in: v8.4.0

net.Socket (または tls.TLSSocket) として機能する Proxy オブジェクトを返しますが、HTTP/2 ロジックに基づいてゲッター、セッター、およびメソッドを適用します。

destroyed、readable、および writable プロパティは、request.stream から取得され、request.stream に設定されます。

destroy、emit、end、on、および once メソッドは、request.stream で呼び出されます。

setTimeout メソッドは、request.stream.session で呼び出されます。

pause、read、resume、および write は、コード ERR_HTTP2_NO_SOCKET_MANIPULATION でエラーをスローします。詳細については、Http2Session とソケット を参照してください。

他のすべてのインタラクションはソケットに直接ルーティングされます。TLS サポートを使用すると、request.socket.getPeerCertificate() を使用して、クライアントの認証の詳細を取得できます。

request.stream ​

Added in: v8.4.0

リクエストをバックアップするHttp2Streamオブジェクト。

request.trailers ​

Added in: v8.4.0

リクエスト/レスポンスのトレーラーオブジェクト。'end'イベントでのみ設定されます。

request.url ​

Added in: v8.4.0

リクエストURL文字列。これには、実際のHTTPリクエストに存在するURLのみが含まれます。リクエストが次のとおりである場合：

GET /status?name=ryan HTTP/1.1 Accept: text/plain

次に、`request.url`は次のようになります。

```js [ESM]
'/status?name=ryan'

URLをその部分に解析するには、new URL()を使用できます。

bash
$ node
> new URL('/status?name=ryan', 'http://example.com')
URL {
  href: 'http://example.com/status?name=ryan',
  origin: 'http://example.com',
  protocol: 'http:',
  username: '',
  password: '',
  host: 'example.com',
  hostname: 'example.com',
  port: '',
  pathname: '/status',
  search: '?name=ryan',
  searchParams: URLSearchParams { 'name' => 'ryan' },
  hash: ''
}

クラス: http2.Http2ServerResponse ​

Added in: v8.4.0

このオブジェクトは、ユーザーではなくHTTPサーバーによって内部的に作成されます。これは、'request'イベントへの2番目のパラメータとして渡されます。

イベント: 'close' ​

Added in: v8.4.0

基になるHttp2Streamが、response.end()が呼び出されるか、フラッシュできるようになる前に終了したことを示します。

イベント: 'finish' ​

Added in: v8.4.0

レスポンスが送信されたときに発生します。より具体的には、このイベントは、レスポンスヘッダーと本文の最後のセグメントが、ネットワーク経由で送信するためにHTTP/2多重化に引き渡されたときに発生します。これは、クライアントがまだ何かを受信したことを意味するものではありません。

このイベントの後、レスポンスオブジェクトでイベントが発生することはもうありません。

response.addTrailers(headers) ​

追加: v8.4.0

このメソッドは、HTTPトレーラーヘッダー（メッセージの最後にあるヘッダー）をレスポンスに追加します。

無効な文字を含むヘッダーフィールド名または値を設定しようとすると、TypeErrorがスローされます。

response.appendHeader(name, value) ​

追加: v21.7.0, v20.12.0

ヘッダーオブジェクトに単一のヘッダー値を追加します。

値が配列の場合、これはこのメソッドを複数回呼び出すのと同じです。

ヘッダーに以前の値がない場合、これはresponse.setHeader()を呼び出すのと同じです。

無効な文字を含むヘッダーフィールド名または値を設定しようとすると、TypeErrorがスローされます。

js
// "set-cookie: a" および "set-cookie: b" を含むヘッダーを返します
const server = http2.createServer((req, res) => {
  res.setHeader('set-cookie', 'a');
  res.appendHeader('set-cookie', 'b');
  res.writeHead(200);
  res.end('ok');
});

response.connection ​

追加: v8.4.0

非推奨: v13.0.0 以降

[安定版: 0 - 非推奨]

安定版: 0 安定度: 0 - 非推奨。 response.socketを使用してください。

response.socketを参照してください。

response.createPushResponse(headers, callback) ​

[履歴]

バージョン変更
v18.0.0callback引数に無効なコールバックを渡すと、ERR_INVALID_CALLBACKではなくERR_INVALID_ARG_TYPEがスローされるようになりました。
v8.4.0追加: v8.4.0
  • headers <HTTP/2 ヘッダーオブジェクト> ヘッダーを記述するオブジェクト
  • callback <Function> http2stream.pushStream()が終了したとき、またはプッシュされたHttp2Streamの作成試行が失敗または拒否されたとき、あるいはhttp2stream.pushStream()メソッドを呼び出す前にHttp2ServerRequestの状態が閉じられた場合に一度呼び出されます

与えられたヘッダーでhttp2stream.pushStream()を呼び出し、成功した場合に、新しく作成されたHttp2ServerResponse上の与えられたHttp2Streamをコールバックパラメータとしてラップします。 Http2ServerRequestが閉じられると、コールバックはエラーERR_HTTP2_INVALID_STREAMで呼び出されます。

response.end([data[, encoding]][, callback]) ​

[History]

VersionChanges
v10.0.0このメソッドは ServerResponse への参照を返すようになりました。
v8.4.0Added in: v8.4.0

このメソッドは、すべてのレスポンスヘッダーとボディが送信されたことをサーバーに通知します。サーバーは、このメッセージが完了したと見なす必要があります。メソッド response.end() は、各レスポンスで呼び出す必要があります。

data が指定されている場合、response.write(data, encoding) を呼び出した後に response.end(callback) を呼び出すのと同じです。

callback が指定されている場合、レスポンスストリームが終了したときに呼び出されます。

response.finished ​

Added in: v8.4.0

Deprecated since: v13.4.0, v12.16.0

[Stable: 0 - Deprecated]

Stable: 0 Stability: 0 - Deprecated. response.writableEnded を使用してください。

レスポンスが完了したかどうかを示すブール値。最初は false です。response.end() が実行されると、値は true になります。

response.getHeader(name) ​

Added in: v8.4.0

すでにキューに入れられているが、クライアントに送信されていないヘッダーを読み出します。名前は大文字と小文字を区別しません。

js
const contentType = response.getHeader('content-type');

response.getHeaderNames() ​

Added in: v8.4.0

現在の送信ヘッダーの一意な名前を含む配列を返します。 すべてのヘッダー名は小文字です。

js
response.setHeader('Foo', 'bar');
response.setHeader('Set-Cookie', ['foo=bar', 'bar=baz']);

const headerNames = response.getHeaderNames();
// headerNames === ['foo', 'set-cookie']

response.getHeaders() ​

Added in: v8.4.0

現在の送信ヘッダーのシャローコピーを返します。 シャローコピーが使用されるため、さまざまなヘッダー関連の http モジュールメソッドを追加で呼び出すことなく、配列値を変更できます。 返されるオブジェクトのキーはヘッダー名であり、値はそれぞれのヘッダー値です。 すべてのヘッダー名は小文字です。

response.getHeaders() メソッドによって返されるオブジェクトは、JavaScript の Object からプロトタイプ的に継承しません。 これは、obj.toString()、obj.hasOwnProperty() などの典型的な Object メソッドが定義されておらず、動作しないことを意味します。

js
response.setHeader('Foo', 'bar');
response.setHeader('Set-Cookie', ['foo=bar', 'bar=baz']);

const headers = response.getHeaders();
// headers === { foo: 'bar', 'set-cookie': ['foo=bar', 'bar=baz'] }

response.hasHeader(name) ​

Added in: v8.4.0

name で識別されるヘッダーが現在の送信ヘッダーに設定されている場合は true を返します。 ヘッダー名の大文字と小文字は区別されません。

js
const hasContentType = response.hasHeader('content-type');

response.headersSent ​

Added in: v8.4.0

ヘッダーが送信された場合は true、そうでない場合は false（読み取り専用）。

response.removeHeader(name) ​

Added in: v8.4.0

暗黙的な送信のためにキューに入れられたヘッダーを削除します。

js
response.removeHeader('Content-Encoding');

response.req ​

Added in: v15.7.0

元の HTTP2 request オブジェクトへの参照。

response.sendDate ​

Added in: v8.4.0

true の場合、Date ヘッダーがヘッダーにまだ存在しない場合、自動的に生成され、レスポンスで送信されます。デフォルトは true です。

これはテストでのみ無効にする必要があります。HTTP ではレスポンスに Date ヘッダーが必要です。

response.setHeader(name, value) ​

Added in: v8.4.0

暗黙的なヘッダーに対して単一のヘッダー値を設定します。このヘッダーが送信されるヘッダーに既に存在する場合、その値は置き換えられます。同じ名前で複数のヘッダーを送信するには、文字列の配列を使用します。

js
response.setHeader('Content-Type', 'text/html; charset=utf-8');

または

js
response.setHeader('Set-Cookie', ['type=ninja', 'language=javascript']);

無効な文字を含むヘッダーフィールド名または値を設定しようとすると、TypeError がスローされます。

ヘッダーが response.setHeader() で設定されている場合、それらは response.writeHead() に渡されたヘッダーとマージされ、response.writeHead() に渡されたヘッダーが優先されます。

js
// content-type = text/plain を返します
const server = http2.createServer((req, res) => {
  res.setHeader('Content-Type', 'text/html; charset=utf-8');
  res.setHeader('X-Foo', 'bar');
  res.writeHead(200, { 'Content-Type': 'text/plain; charset=utf-8' });
  res.end('ok');
});

response.setTimeout(msecs[, callback]) ​

Added in: v8.4.0

Http2Stream のタイムアウト値を msecs に設定します。callback が提供された場合、レスポンスオブジェクトの 'timeout' イベントのリスナーとして追加されます。

リクエスト、レスポンス、またはサーバーに 'timeout' リスナーが追加されていない場合、Http2Stream はタイムアウト時に破棄されます。ハンドラーがリクエスト、レスポンス、またはサーバーの 'timeout' イベントに割り当てられている場合、タイムアウトしたソケットは明示的に処理する必要があります。

response.socket ​

Added in: v8.4.0

net.Socket (または tls.TLSSocket) として動作する Proxy オブジェクトを返しますが、HTTP/2 ロジックに基づいてゲッター、セッター、およびメソッドを適用します。

destroyed、readable、および writable プロパティは、response.stream から取得され、設定されます。

destroy、emit、end、on、および once メソッドは、response.stream で呼び出されます。

setTimeout メソッドは、response.stream.session で呼び出されます。

pause、read、resume、および write は、コード ERR_HTTP2_NO_SOCKET_MANIPULATION でエラーをスローします。詳細については、Http2Session とソケット を参照してください。

他のすべてのインタラクションは、ソケットに直接ルーティングされます。

js
import { createServer } from 'node:http2';
const server = createServer((req, res) => {
  const ip = req.socket.remoteAddress;
  const port = req.socket.remotePort;
  res.end(`Your IP address is ${ip} and your source port is ${port}.`);
}).listen(3000);
js
const http2 = require('node:http2');
const server = http2.createServer((req, res) => {
  const ip = req.socket.remoteAddress;
  const port = req.socket.remotePort;
  res.end(`Your IP address is ${ip} and your source port is ${port}.`);
}).listen(3000);

response.statusCode ​

追加: v8.4.0

暗黙的なヘッダーを使用している場合（response.writeHead()を明示的に呼び出さない場合）、このプロパティは、ヘッダーがフラッシュされるときにクライアントに送信されるステータスコードを制御します。

js
response.statusCode = 404;

レスポンスヘッダーがクライアントに送信された後、このプロパティは送信されたステータスコードを示します。

response.statusMessage ​

追加: v8.4.0

ステータスメッセージは HTTP/2 でサポートされていません (RFC 7540 8.1.2.4)。 空の文字列を返します。

response.stream ​

追加: v8.4.0

レスポンスをサポートする Http2Stream オブジェクト。

response.writableEnded ​

追加: v12.9.0

response.end() が呼び出された後 true になります。 このプロパティは、データがフラッシュされたかどうかを示すものではありません。代わりに writable.writableFinished を使用してください。

response.write(chunk[, encoding][, callback]) ​

追加: v8.4.0

このメソッドが呼び出され、response.writeHead() が呼び出されていない場合、暗黙的なヘッダーモードに切り替わり、暗黙的なヘッダーをフラッシュします。

これは、レスポンスボディのチャンクを送信します。 このメソッドは、ボディの連続した部分を提供するために複数回呼び出すことができます。

node:http モジュールでは、リクエストが HEAD リクエストの場合、レスポンスボディは省略されます。 同様に、204 および 304 レスポンスには、メッセージボディを含めてはなりません。

chunk は文字列またはバッファにすることができます。 chunk が文字列の場合、2 番目のパラメータは、それをバイトストリームにエンコードする方法を指定します。 デフォルトでは、encoding は 'utf8' です。 データチャンクがフラッシュされると callback が呼び出されます。

これは生の HTTP ボディであり、使用される可能性のある高レベルのマルチパートボディエンコーディングとは関係ありません。

response.write() が最初に呼び出されると、バッファリングされたヘッダー情報とボディの最初のチャンクがクライアントに送信されます。 2 回目に response.write() が呼び出されると、Node.js はデータがストリーミングされるとみなし、新しいデータを個別に送信します。 つまり、レスポンスはボディの最初のチャンクまでバッファリングされます。

データ全体がカーネルバッファに正常にフラッシュされた場合は true を返します。 データの一部またはすべてがユーザメモリにキューイングされた場合は false を返します。 バッファが再び空になると、'drain' が発行されます。

response.writeContinue() ​

Added in: v8.4.0

リクエストボディを送信する必要があることを示すステータス 100 Continue をクライアントに送信します。Http2Server および Http2SecureServer の 'checkContinue' イベントを参照してください。

response.writeEarlyHints(hints) ​

Added in: v18.11.0

ユーザーエージェントがリンクされたリソースをプリロード/プリコネクトできることを示す、Linkヘッダーを持つステータス 103 Early Hints をクライアントに送信します。hints は、early hintsメッセージとともに送信されるヘッダーの値を含むオブジェクトです。

例

js
const earlyHintsLink = '</styles.css>; rel=preload; as=style';
response.writeEarlyHints({
  'link': earlyHintsLink,
});

const earlyHintsLinks = [
  '</styles.css>; rel=preload; as=style',
  '</scripts.js>; rel=preload; as=script',
];
response.writeEarlyHints({
  'link': earlyHintsLinks,
});

response.writeHead(statusCode[, statusMessage][, headers]) ​

[History]

VersionChanges
v11.10.0, v10.17.0end() とのチェーンを可能にするために、writeHead() から this を返します。
v8.4.0Added in: v8.4.0

リクエストに応答ヘッダーを送信します。ステータスコードは、404 のような3桁のHTTPステータスコードです。最後の引数 headers は、応答ヘッダーです。

Http2ServerResponse への参照を返し、呼び出しをチェーンできるようにします。

HTTP/1 との互換性のために、人間が読める statusMessage を2番目の引数として渡すことができます。ただし、statusMessage は HTTP/2 内では意味がないため、引数は効果がなく、プロセスの警告が発生します。

js
const body = 'hello world';
response.writeHead(200, {
  'Content-Length': Buffer.byteLength(body),
  'Content-Type': 'text/plain; charset=utf-8',
});

Content-Length は文字数ではなくバイト数で指定します。Buffer.byteLength() API を使用して、指定されたエンコーディングのバイト数を決定できます。送信メッセージでは、Node.js は Content-Length と送信される本文の長さが等しいかどうかを確認しません。ただし、メッセージを受信するとき、Node.js は Content-Length が実際のペイロードサイズと一致しない場合に、メッセージを自動的に拒否します。

このメソッドは、response.end() が呼び出される前に、メッセージに対して最大で1回呼び出すことができます。

response.write() または response.end() がこれを呼び出す前に呼び出された場合、暗黙的/可変ヘッダーが計算され、この関数が呼び出されます。

ヘッダーが response.setHeader() で設定されている場合、response.writeHead() に渡されたヘッダーとマージされ、response.writeHead() に渡されたヘッダーが優先されます。

js
// content-type = text/plain を返します
const server = http2.createServer((req, res) => {
  res.setHeader('Content-Type', 'text/html; charset=utf-8');
  res.setHeader('X-Foo', 'bar');
  res.writeHead(200, { 'Content-Type': 'text/plain; charset=utf-8' });
  res.end('ok');
});

無効な文字を含むヘッダーフィールド名または値を設定しようとすると、TypeError がスローされます。

HTTP/2 パフォーマンスメトリクスの収集 ​

Performance Observer APIを使用すると、各Http2SessionおよびHttp2Streamインスタンスの基本的なパフォーマンスメトリクスを収集できます。

js
import { PerformanceObserver } from 'node:perf_hooks';

const obs = new PerformanceObserver((items) => {
  const entry = items.getEntries()[0];
  console.log(entry.entryType);  // prints 'http2'
  if (entry.name === 'Http2Session') {
    // Entry contains statistics about the Http2Session
  } else if (entry.name === 'Http2Stream') {
    // Entry contains statistics about the Http2Stream
  }
});
obs.observe({ entryTypes: ['http2'] });
js
const { PerformanceObserver } = require('node:perf_hooks');

const obs = new PerformanceObserver((items) => {
  const entry = items.getEntries()[0];
  console.log(entry.entryType);  // prints 'http2'
  if (entry.name === 'Http2Session') {
    // Entry contains statistics about the Http2Session
  } else if (entry.name === 'Http2Stream') {
    // Entry contains statistics about the Http2Stream
  }
});
obs.observe({ entryTypes: ['http2'] });

PerformanceEntryのentryTypeプロパティは、'http2'と等しくなります。

PerformanceEntryのnameプロパティは、'Http2Stream'または'Http2Session'のいずれかと等しくなります。

nameがHttp2Streamと等しい場合、PerformanceEntryには次の追加プロパティが含まれます。

  • bytesRead <number> このHttp2Streamで受信したDATAフレームのバイト数。
  • bytesWritten <number> このHttp2Streamで送信したDATAフレームのバイト数。
  • id <number> 関連付けられたHttp2Streamの識別子
  • timeToFirstByte <number> PerformanceEntryのstartTimeから最初のDATAフレームの受信までの経過ミリ秒数。
  • timeToFirstByteSent <number> PerformanceEntryのstartTimeから最初のDATAフレームの送信までの経過ミリ秒数。
  • timeToFirstHeader <number> PerformanceEntryのstartTimeから最初のヘッダーの受信までの経過ミリ秒数。

nameがHttp2Sessionと等しい場合、PerformanceEntryには次の追加プロパティが含まれます。

  • bytesRead <number> このHttp2Sessionで受信したバイト数。
  • bytesWritten <number> このHttp2Sessionで送信したバイト数。
  • framesReceived <number> Http2Sessionが受信したHTTP/2フレームの数。
  • framesSent <number> Http2Sessionが送信したHTTP/2フレームの数。
  • maxConcurrentStreams <number> Http2Sessionの有効期間中に同時に開かれたストリームの最大数。
  • pingRTT <number> PINGフレームの送信とその応答の受信からの経過ミリ秒数。 PINGフレームがHttp2Sessionで送信された場合にのみ存在します。
  • streamAverageDuration <number> すべてのHttp2Streamインスタンスの平均期間（ミリ秒単位）。
  • streamCount <number> Http2Sessionによって処理されたHttp2Streamインスタンスの数。
  • type <string> Http2Sessionのタイプを識別するための'server'または'client'。

:authority と host に関する注意 ​

HTTP/2 では、リクエストに :authority 疑似ヘッダーまたは host ヘッダーのいずれかが必要です。HTTP/2 リクエストを直接構築する場合は :authority を優先し、(例えばプロキシなどで) HTTP/1 から変換する場合は host を優先します。

互換性 API は、:authority が存在しない場合、host にフォールバックします。詳細については、request.authority を参照してください。ただし、互換性 API を使用しない場合 (または req.headers を直接使用する場合) は、フォールバック動作を自分で実装する必要があります。