Node.js v21.7.2 ドキュメント

暗号サポートが利用できないかどうかの判定#

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

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

let http2;
try {
  http2 = require('node:http2');
} catch (err) {
  console.error('http2 support is disabled!');
} copy

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

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

let http2;
try {
  http2 = await import('node:http2');
} catch (err) {
  console.error('http2 support is disabled!');
} copy

コア API#

コア API は、HTTP/2 プロトコル機能のサポートを中心に特別に設計された低レベルインターフェースを提供します。これは、既存の HTTP/1 モジュール API との互換性を考慮していないものです。ただし、互換性 API はそうです。

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

サーバー側の例#

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

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); copy

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

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

クライアント側の例#

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

const http2 = require('node:http2');
const fs = require('node:fs');
const client = http2.connect('https://127.0.0.1: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(); copy

クラス: Http2Session#

• 拡張: <EventEmitter>

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

各 Http2Session インスタンスは、サーバーとして動作しているかクライアントとして動作しているかによって、わずかに異なる動作を示します。Http2Session が動作しているモードを判断するために、http2session.type プロパティを使用できます。サーバー側では、ユーザーコードが 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'#

'close'イベントは、Http2Sessionが破棄されると一度だけ発行されます。リスナーは引数を期待しません。

イベント: 'connect'#

• session <Http2Session>
• socket <net.Socket>

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

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

イベント: 'error'#

• error <Error>

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

イベント: 'frameError'#

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

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

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

イベント: 'goaway'#

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

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

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

イベント: 'localSettings'#

• settings <HTTP/2 設定オブジェクト> 受信したSETTINGSフレームのコピー。

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

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

session.settings({ enablePush: false });

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

イベント: 'ping'#

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

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

イベント: 'remoteSettings'#

• settings <HTTP/2 設定オブジェクト> 受信したSETTINGSフレームのコピー。

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

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

イベント: 'stream'#

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

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

const http2 = require('node:http2');
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');
}); copy

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

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

// Create an unencrypted HTTP/2 server
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); copy

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

イベント: 'timeout'#

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

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

http2session.alpnProtocol#

• <string> | <undefined>

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

http2session.close([callback])#

• callback <Function>

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

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

http2session.closed#

• <boolean>

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

http2session.connecting#

• <boolean>

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

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

• 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に関連付けられているオープンなHttp2Streamsが残っている場合、それらも破棄されます。

http2session.destroyed#

• <boolean>

このHttp2Sessionインスタンスが破棄されていて使用できなくなった場合はtrue、それ以外の場合はfalseになります。

http2session.encrypted#

• <boolean> | <undefined>

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

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

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

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

http2session.localSettings#

• <HTTP/2 設定オブジェクト>

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

http2session.originSet#

• <string[]> | <undefined>

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

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

http2session.pendingSettingsAck#

• <boolean>

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

http2session.ping([payload, ]callback)#

• payload <Buffer> | <TypedArray> | <DataView> オプションの ping ペイロード。
• callback <Function>
• 戻り値: <boolean>

接続された 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) で呼び出されます。

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

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

http2session.ref()#

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

http2session.remoteSettings#

• <HTTP/2 設定オブジェクト>

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

http2session.setLocalWindowSize(windowSize)#

• windowSize <number>

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

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);
}); copy

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

http2session.setTimeout(msecs, callback)#

• msecs <number>
• callback <Function>

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

http2session.socket#

• <net.Socket> | <tls.TLSSocket>

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

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

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

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

http2session.state#

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])#

• settings <HTTP/2 設定オブジェクト>
• callback <Function> セッションが接続されたら、またはセッションが既に接続されている場合はすぐに呼び出されるコールバック。
  • err <Error> | <null>
  • settings <HTTP/2 設定オブジェクト> 更新された settings オブジェクト。
  • duration <integer>

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

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

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

http2session.type#

• <number>

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

http2session.unref()#

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

クラス: ServerHttp2Session#

• 拡張: <Http2Session>

serverhttp2session.altsvc(alt, originOrStream)#

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

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

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

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

server.on('stream', (stream) => {
  // Set altsvc for a specific stream
  stream.session.altsvc('h2=":8000"', stream.id);
}); copy

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

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

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

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

代替サービスの指定#

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

たとえば、値'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)#

• origins <string> | <URL> | <Object> 個別の引数として渡される1つ以上のURL文字列。

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

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');
}); copy

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

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

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

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');
}); copy

クラス: ClientHttp2Session#

• 拡張: <Http2Session>

イベント: 'altsvc'#

• alt <string>
• origin <string>
• streamId <number>

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

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);
}); copy

イベント: 'origin'#

• origins <string[]>

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

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]);
}); copy

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

clienthttp2session.request(headers[, options])#

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

• options <Object>

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

• 戻り値: <ClientHttp2Stream>

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

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

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

const http2 = require('node:http2');
const clientSession = http2.connect('https://127.0.0.1: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', () => { /* .. */ });
}); copy

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

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

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

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

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

クラス: Http2Stream#

• 拡張: <stream.Duplex>

Http2Streamクラスの各インスタンスは、Http2Sessionインスタンス上の双方向HTTP/2通信ストリームを表します。1つの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' ヘッダーを使用して文字エンコーディングを設定してください。

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

Http2Stream のライフサイクル#

作成#

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

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

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

クライアント側では、親の Http2Session がまだ完全に確立されていない場合、http2session.request() によって返される Http2Stream インスタンスはすぐには使用できない場合があります。そのような場合、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 インスタンスは、破棄されると使用できなくなります。

イベント: 'aborted'#

'aborted' イベントは、Http2Stream インスタンスが通信中に異常に中断されたときに常に発行されます。リスナーは引数を予期しません。

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

イベント: 'close'#

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

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

イベント: 'error'#

• error <Error>

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

イベント: 'frameError'#

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

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

イベント: 'ready'#

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

イベント: 'timeout'#

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

イベント: 'trailers'#

• headers <HTTP/2 ヘッダーオブジェクト> ヘッダーを記述するオブジェクト
• flags <number> 関連する数値フラグ

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

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

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

イベント: 'wantTrailers'#

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

http2stream.aborted#

• <boolean>

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

http2stream.bufferSize#

• <number>

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

http2stream.close(code[, callback])#

• code <number> エラーコードを識別する符号なし 32 ビット整数。デフォルト: http2.constants.NGHTTP2_NO_ERROR (0x00)。
• callback <Function> 'close' イベントをリッスンするために登録されたオプションの関数。

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

http2stream.closed#

• <boolean>

Http2Stream インスタンスが閉じられた場合は true に設定されます。

http2stream.destroyed#

• <boolean>

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

http2stream.endAfterHeaders#

• <boolean>

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

http2stream.id#

• <number> | <undefined>

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

http2stream.pending#

• <boolean>

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

http2stream.priority(options)#

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

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

http2stream.rstCode#

• <number>

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

http2stream.sentHeaders#

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

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

http2stream.sentInfoHeaders#

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

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

http2stream.sentTrailers#

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

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

http2stream.session#

• <Http2Session>

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

http2stream.setTimeout(msecs, callback)#

• msecs <number>
• callback <Function>

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)); copy

http2stream.state#

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)#

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

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

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');
}); copy

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

クラス: ClientHttp2Stream#

• <Http2Stream> を拡張します。

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

イベント: 'continue'#

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

イベント: 'headers'#

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

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

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

イベント: 'push'#

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

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

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

イベント: 'response'#

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

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

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

クラス: ServerHttp2Stream#

• 拡張: <Http2Stream>

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

http2stream.additionalHeaders(headers)#

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

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

http2stream.headersSent#

• <boolean>

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

http2stream.pushAllowed#

• <boolean>

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

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

• headers <HTTP/2 ヘッダーオブジェクト>
• options <Object>
  • exclusive <boolean> trueで、parentが親ストリームを識別する場合、作成されたストリームは親の唯一の直接依存関係となり、他の既存の依存関係はすべて新しく作成されたストリームの依存関係になります。 **デフォルト:** false。
  • parent <number> 新しく作成されたストリームが依存するストリームの数値識別子を指定します。
• callback <Function> プッシュストリームが開始された後に呼び出されるコールバック。
  • err <Error>
  • pushStream <ServerHttp2Stream> 返される pushStream オブジェクト。
  • headers <HTTP/2 ヘッダーオブジェクト> pushStream が開始されたヘッダーオブジェクト。

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

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');
}); copy

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

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

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

• headers <HTTP/2 ヘッダーオブジェクト>
• options <Object>
  • endStream <boolean> レスポンスにペイロードデータが含まれないことを示す場合は true に設定します。
  • waitForTrailers <boolean> trueの場合、最後のDATAフレームが送信された後、Http2Streamは'wantTrailers'イベントを発行します。

const http2 = require('node:http2');
const server = http2.createServer();
server.on('stream', (stream) => {
  stream.respond({ ':status': 200 });
  stream.end('some data');
}); copy

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

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

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');
}); copy

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

• fd <number> | <FileHandle> 読み取り可能なファイル記述子。
• headers <HTTP/2 ヘッダーオブジェクト>
• options <Object>
  • statCheck <Function>
  • waitForTrailers <boolean> trueの場合、最後のDATAフレームが送信された後、Http2Streamは'wantTrailers'イベントを発行します。
  • offset <number> 読み取りを開始するオフセット位置。
  • length <number> fd から送信するデータ量。

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

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

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));
}); copy

オプションの 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() のいずれかを呼び出す必要があります。

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));
}); copy

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

• path <string> | <Buffer> | <URL>
• headers <HTTP/2 ヘッダーオブジェクト>
• options <Object>
  • statCheck <Function>
  • onError <Function> 送信する前にエラーが発生した場合に呼び出されるコールバック関数。
  • waitForTrailers <boolean> trueの場合、最後のDATAフレームが送信された後、Http2Streamは'wantTrailers'イベントを発行します。
  • offset <number> 読み取りを開始するオフセット位置。
  • length <number> fd から送信するデータ量。

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

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

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

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

ファイルパスを使用した例

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() can throw if the stream has been destroyed by
    // the other side.
    try {
      if (err.code === 'ENOENT') {
        stream.respond({ ':status': 404 });
      } else {
        stream.respond({ ':status': 500 });
      }
    } catch (err) {
      // Perform actual error handling.
      console.error(err);
    }
    stream.end();
  }

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

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

const http2 = require('node:http2');
const server = http2.createServer();
server.on('stream', (stream) => {
  function statCheck(stat, headers) {
    // Check the stat here...
    stream.respond({ ':status': 304 });
    return false; // Cancel the send operation
  }
  stream.respondWithFile('/some/file',
                         { 'content-type': 'text/plain; charset=utf-8' },
                         { statCheck });
}); copy

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

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

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

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

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

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' });
  });
}); copy

クラス: Http2Server#

• 拡張: <net.Server>

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

イベント: 'checkContinue'#

• request <http2.Http2ServerRequest>
• response <http2.Http2ServerResponse>

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

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

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

イベント: 'connection'#

• socket <stream.Duplex>

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

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

イベント: 'request'#

• request <http2.Http2ServerRequest>
• response <http2.Http2ServerResponse>

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

イベント: 'session'#

• session <ServerHttp2Session>

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

イベント: 'sessionError'#

• error <Error>
• session <ServerHttp2Session>

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

イベント: 'stream'#

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

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

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

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');
}); copy

イベント: 'timeout'#

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

server.close([callback])#

• callback <Function>

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

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

server[Symbol.asyncDispose]()#

server.close() を呼び出し、サーバーが閉じられたときに完了するプロミスを返します。

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

• msecs <number> デフォルト: 0 (タイムアウトなし)
• callback <Function>
• 返値: <Http2Server>

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

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

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

server.timeout#

• <number> タイムアウトまでのミリ秒数。デフォルト: 0 (タイムアウトなし)

ソケットがタイムアウトしたとみなされるまでの非アクティブなミリ秒数。

0 の値は、受信接続でのタイムアウト動作を無効にします。

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

server.updateSettings([settings])#

• settings <HTTP/2 設定オブジェクト>

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

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

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

クラス: Http2SecureServer#

• 拡張: <tls.Server>

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

イベント: 'checkContinue'#

• request <http2.Http2ServerRequest>
• response <http2.Http2ServerResponse>

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

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

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

イベント: 'connection'#

• socket <stream.Duplex>

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

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

イベント: 'request'#

• request <http2.Http2ServerRequest>
• response <http2.Http2ServerResponse>

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

イベント: 'session'#

• session <ServerHttp2Session>

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

イベント: 'sessionError'#

• error <Error>
• session <ServerHttp2Session>

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

イベント: 'stream'#

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

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

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

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');
}); copy

イベント: 'timeout'#

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

イベント: 'unknownProtocol'#

• socket <stream.Duplex>

'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])#

• callback <Function>

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

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

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

• msecs <number> デフォルト: 120000 (2 分)
• callback <Function>
• 返値: <Http2SecureServer>

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

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

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

server.timeout#

• <number> タイムアウトまでのミリ秒数。デフォルト: 0 (タイムアウトなし)

ソケットがタイムアウトしたとみなされるまでの非アクティブなミリ秒数。

0 の値は、受信接続でのタイムアウト動作を無効にします。

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

server.updateSettings([settings])#

• settings <HTTP/2 設定オブジェクト>

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

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

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

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

• 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> 未確認の未処理のピングの最大数を設定します。デフォルト: 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 設定オブジェクト> 接続時にリモートピアに送信する初期設定。
  • remoteCustomSettings <Array> 整数の配列値は設定タイプを決定します。これは、受信したリモート設定の 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() を使用する必要があります。

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

// Create an unencrypted HTTP/2 server.
// Since there are no browsers known that support
// unencrypted HTTP/2, the use of `http2.createSecureServer()`
// is necessary when communicating with browser clients.
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); copy

http2.createSecureServer(options[, onRequestHandler])#

• 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> 未確認の未処理のピングの最大数を設定します。デフォルト: 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> 整数の配列値は設定タイプを決定します。これは、受信したリモート設定の customSettings プロパティに含まれます。許可される設定タイプに関する詳細については、Http2Settings オブジェクトの customSettings プロパティを参照してください。
  • ...: tls.createServer() のオプションはすべて指定できます。サーバーの場合、ID オプション（pfx または key/cert）が通常必要です。
  • origins <string[]> 新しいサーバー Http2Session の作成直後に ORIGIN フレーム内で送信するオリジン文字列の配列。
  • unknownProtocolTimeout <number> 'unknownProtocol' イベントが発行されたときにサーバーが待機する必要があるタイムアウトをミリ秒単位で指定します。その時間までにソケットが破棄されていない場合、サーバーはそれを破棄します。デフォルト: 10000。
• onRequestHandler <Function> 互換性 API を参照してください
• 返値: <Http2SecureServer>

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

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); copy

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

• 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> 未確認の未処理のピングの最大数を設定します。デフォルト: 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> 整数の配列値は設定タイプを決定します。これは、受信したリモート設定の CustomSettings プロパティに含まれます。許可される設定タイプに関する詳細については、Http2Settings オブジェクトの CustomSettings プロパティを参照してください。
  • createConnection <Function> connect に渡された URL インスタンスと options オブジェクトを受け取り、このセッションの接続として使用される Duplex ストリームを返すオプションのコールバック。
  • ...: net.connect() または tls.connect() のオプションを任意に指定できます。
  • unknownProtocolTimeout <number> 'unknownProtocol' イベントが発行されたときにサーバーが待機する必要があるタイムアウトをミリ秒単位で指定します。その時間までにソケットが破棄されていない場合、サーバーはそれを破棄します。デフォルト: 10000。
• listener <Function> 'connect' イベントの 1 回限りのリスナーとして登録されます。
• 戻り値: <ClientHttp2Session>

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

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

/* Use the client */

client.close(); copy

http2.constants#

RST_STREAM および GOAWAY のエラーコード#

'timeout' イベントは、http2server.setTimeout() を使用して設定された指定されたミリ秒数の間、サーバーでアクティビティがない場合に発生します。

http2.getDefaultSettings()#

• 戻り値: <HTTP/2 設定オブジェクト>

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

http2.getPackedSettings([settings])#

• settings <HTTP/2 設定オブジェクト>
• 戻り値: <Buffer>

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

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

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

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

http2.getUnpackedSettings(buf)#

• buf <Buffer> | <TypedArray> パックされた設定。
• 戻り値: <HTTP/2 設定オブジェクト>

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

http2.performServerHandshake(socket[, options])#

• socket <stream.Duplex>
• options <Object>
  • ...: http2.createServer() のオプションを任意に指定できます。
• 戻り値: <ServerHttp2Session>

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

http2.sensitiveHeaders#

• <symbol>

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

ヘッダーオブジェクト#

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

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

stream.respond(headers); copy

コールバック関数に渡されるヘッダーオブジェクトは、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 ヘッダーの場合、値は '; ' で結合されます。
• 他のすべてのヘッダーの場合、値は ', ' で結合されます。

const http2 = require('node:http2');
const server = http2.createServer();
server.on('stream', (stream, headers) => {
  console.log(headers[':path']);
  console.log(headers.ABC);
}); copy

機密ヘッダー#

HTTP2 ヘッダーは機密としてマークできます。これは、HTTP/2 ヘッダー圧縮アルゴリズムがそれらを決してインデックス付けしないことを意味します。これは、エントロピーが低く、攻撃者にとって価値がある可能性があるヘッダー値、たとえば Cookie または Authorization にとって意味がある場合があります。これを実現するには、ヘッダー名を配列として [http2.sensitiveHeaders] プロパティに追加します

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); copy

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

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

設定オブジェクト#

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

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

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

エラー処理#

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

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

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

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

プロトコルエラーは、さまざまなHTTP/2プロトコルの制約に違反した場合に発生します。これらのエラーは、エラーが発生する場所とタイミングに応じて、同期的なthrowまたはHttp2Stream、Http2Session、またはHTTP/2サーバーオブジェクトの'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'イベントのリスナーを設定します。

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

const client = http2.connect('https://127.0.0.1');

client.on('stream', (pushedStream, requestHeaders) => {
  pushedStream.on('push', (responseHeaders) => {
    // Process response headers
  });
  pushedStream.on('data', (chunk) => { /* handle pushed data */ });
});

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

CONNECTメソッドのサポート#

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

シンプルなTCPサーバー

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); copy

HTTP/2 CONNECTプロキシ

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') {
    // Only accept CONNECT requests
    stream.close(NGHTTP2_REFUSED_STREAM);
    return;
  }
  const auth = new URL(`tcp://${headers[':authority']}`);
  // It's a very good idea to verify that hostname and port are
  // things this proxy should be connecting to.
  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); copy

HTTP/2 CONNECTクライアント

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

const client = http2.connect('https://127.0.0.1:8001');

// Must not specify the ':path' and ':scheme' headers
// for CONNECT requests or an error will be thrown.
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'); copy

拡張されたCONNECTプロトコル#

RFC 8441は、HTTP/2への「拡張CONNECTプロトコル」拡張を定義しており、CONNECTメソッドを他の通信プロトコル（WebSocketなど）のトンネルとして使用してHttp2Streamの使用をブートストラップするために使用できます。

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

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

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

const http2 = require('node:http2');
const client = http2.connect('https://127.0.0.1:8080');
client.on('remoteSettings', (settings) => {
  if (settings.enableConnectProtocol) {
    const req = client.request({ ':method': 'CONNECT', ':protocol': 'foo' });
    // ...
  }
}); copy

互換性API#

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

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

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');
}); copy

混合の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のより高度な機能を使用できるかどうかを検出する必要があります。

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

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) {
  // Detects if it is a HTTPS request or 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,
  }));
} copy

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

クラス: http2.Http2ServerRequest#

• 拡張: <stream.Readable>

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

イベント: 'aborted'#

Http2ServerRequestインスタンスが通信中に異常に中断されると、常に'aborted'イベントが発行されます。

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

イベント: 'close'#

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

request.aborted#

• <boolean>

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

request.authority#

• <string>

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

request.complete#

• <boolean>

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

request.connection#

• <net.Socket> | <tls.TLSSocket>

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

request.destroy([error])#

• error <Error>

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

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

request.headers#

• <Object>

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

ヘッダー名と値のキーと値のペア。ヘッダー名は小文字です。

// Prints something like:
//
// { 'user-agent': 'curl/7.22.0',
//   host: '127.0.0.1:8000',
//   accept: '*/*' }
console.log(request.headers); copy

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

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

removeAllHeaders(request.headers);
assert(request.url);   // Fails because the :path header has been removed copy

request.httpVersion#

• <string>

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

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

request.method#

• <string>

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

request.rawHeaders#

• <string[]>

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

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

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

// Prints something like:
//
// [ '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); copy

request.rawTrailers#

• <string[]>

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

request.scheme#

• <string>

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

request.setTimeout(msecs, callback)#

• msecs <number>
• callback <Function>
• 戻り値: <http2.Http2ServerRequest>

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

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

request.socket#

• <net.Socket> | <tls.TLSSocket>

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

destroyed、readable、およびwritableプロパティは、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#

• <Http2Stream>

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

request.trailers#

• <Object>

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

request.url#

• <string>

リクエストURL文字列。これは、実際のHTTPリクエストに存在するURLのみを含みます。リクエストが

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

の場合、request.urlは

'/status?name=ryan' copy

になります。URLをその構成要素に解析するには、new URL()を使用できます。

$ 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: ''
} copy

クラス: http2.Http2ServerResponse#

• 拡張: <Stream>

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

イベント: 'close'#

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

イベント: 'finish'#

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

このイベントの後、レスポンスオブジェクトでイベントは発生しなくなります。

response.addTrailers(headers)#

• headers <Object>

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

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

response.appendHeader(name, value)#

• name <string>
• value <string> | <string[]>

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

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

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

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

// Returns headers including "set-cookie: a" and "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');
}); copy

response.connection#

• <net.Socket> | <tls.TLSSocket>

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

response.createPushResponse(headers, callback)#

• headers <HTTP/2 ヘッダーオブジェクト> ヘッダーを記述するオブジェクト
• callback <Function> http2stream.pushStream()が完了したとき、またはプッシュされたHttp2Streamの作成試行が失敗または拒否されたとき、あるいはHttp2ServerRequestの状態がhttp2stream.pushStream()メソッドを呼び出す前に閉じられたときに1回呼び出されます
  • err <Error>
  • res <http2.Http2ServerResponse> 新しく作成されたHttp2ServerResponseオブジェクト

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

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

• data <string> | <Buffer> | <Uint8Array>
• encoding <string>
• callback <Function>
• 戻り値: <this>

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

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

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

response.finished#

• <boolean>

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

response.getHeader(name)#

• name <string>
• 戻り値: <string>

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

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

response.getHeaderNames()#

• 戻り値: <string[]>

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

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

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

response.getHeaders()#

• 戻り値: <Object>

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

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

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'] } copy

response.hasHeader(name)#

• name <string>
• 戻り値: <boolean>

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

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

response.headersSent#

• <boolean>

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

response.removeHeader(name)#

• name <string>

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

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

response.req#

• <http2.Http2ServerRequest>

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

response.sendDate#

• <boolean>

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

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

response.setHeader(name, value)#

• name <string>
• value <string> | <string[]>

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

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

または

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

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

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

// Returns 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');
}); copy

response.setTimeout(msecs[, callback])#

• msecs <number>
• callback <Function>
• 戻り値: <http2.Http2ServerResponse>

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

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

response.socket#

• <net.Socket> | <tls.TLSSocket>

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

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とソケットを参照してください。

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

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); copy

response.statusCode#

• <number>

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

response.statusCode = 404; copy

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

response.statusMessage#

• <string>

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

response.stream#

• <Http2Stream>

レスポンスをバックアップする Http2Stream オブジェクト。

response.writableEnded#

• <boolean>

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

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

• chunk <string> | <Buffer> | <Uint8Array>
• encoding <string>
• callback <Function>
• 戻り値: <boolean>

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

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

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

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

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

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

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

response.writeContinue()#

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

response.writeEarlyHints(hints)#

• hints <Object>

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

例

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,
}); copy

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

• statusCode <number>
• statusMessage <string>
• headers <Object> | <Array>
• 戻り値: <http2.Http2ServerResponse>

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

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

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

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

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()に渡されたヘッダーが優先されます。

// Returns 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');
}); copy

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

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

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

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'] }); copy

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 を直接使用する場合）、フォールバック動作を自分で実装する必要があります。