HTTP/2

[履歴]

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

[安定版: 2 - 安定版]

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

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

node:http2モジュールは、HTTP/2プロトコルの実装を提供します。これは次のようにアクセスできます。

const http2 = require('node:http2')

crypto サポートが利用できない場合の確認

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!')
}

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

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

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

コア API

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

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

サーバー側の例

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

ESM

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 は Duplex
  stream.respond({
    'content-type': 'text/html; charset=utf-8',
    ':status': 200,
  })
  stream.end('<h1>Hello World</h1>')
})

server.listen(8443)

CJS

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 は Duplex
  stream.respond({
    'content-type': 'text/html; charset=utf-8',
    ':status': 200,
  })
  stream.end('<h1>Hello World</h1>')
})

server.listen(8443)

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

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

クライアント側の例

以下は、HTTP/2 クライアントの例です。

ESM

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

CJS

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

• 拡張: <EventEmitter>

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

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

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

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

イベント: 'error'

追加: v8.4.0

• error <Error>

'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 フレームを受信したときに発生します。

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

イベント: 'localSettings'

追加: v8.4.0

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

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

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

session.settings({ enablePush: false })

session.on('localSettings', settings => {
  /* 新しい設定を使用する */
})

イベント: 'ping'

追加: v10.12.0

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

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

イベント: 'remoteSettings'

追加: v8.4.0

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

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

session.on('remoteSettings', settings => {
  /* 新しい設定を使用する */
})

イベント: 'stream'

追加: v8.4.0

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

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

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' イベントのハンドラーを登録します。

ESM

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)

CJS

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' イベントが発行されます。そのリスナーは引数を予期しません。

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

http2session.alpnProtocol

追加: v9.4.0

• <string> | <undefined>

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

http2session.close([callback])

追加: v9.4.0

• callback <Function>

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

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

http2session.closed

追加: v9.4.0

• <boolean>

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

http2session.connecting

追加: v10.0.0

• <boolean>

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

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

追加: v8.4.0

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

Http2Session と関連付けられた net.Socket または tls.TLSSocket を直ちに終了します。

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

Http2Session に関連付けられたオープンな Http2Stream が残っている場合、それらも破棄されます。

http2session.destroyed

追加: v8.4.0

• <boolean>

この Http2Session インスタンスが破棄され、もはや使用してはならない場合は true、それ以外の場合は false になります。

http2session.encrypted

追加: v9.4.0

• <boolean> | <undefined>

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

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

追加: v9.4.0

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

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

http2session.localSettings

追加: v8.4.0

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

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

http2session.originSet

追加: v9.4.0

• <string[]> | <undefined>

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

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

http2session.pendingSettingsAck

追加: v8.4.0

• <boolean>

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

http2session.ping([payload, ]callback)

[履歴]

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

• 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()}'`)
  }
})

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

http2session.ref()

追加: v9.4.0

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

http2session.remoteSettings

追加: v8.4.0

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

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

http2session.setLocalWindowSize(windowSize)

追加: v15.3.0, v14.18.0

• windowSize <number>

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

ESM

import { createServer } from 'node:http2'

const server = createServer()
const expectedWindowSize = 2 ** 20
server.on('session', session => {
  // ローカルウィンドウサイズを2 ** 20に設定
  session.setLocalWindowSize(expectedWindowSize)
})

CJS

const http2 = require('node:http2')

const server = http2.createServer()
const expectedWindowSize = 2 ** 20
server.on('session', session => {
  // ローカルウィンドウサイズを2 ** 20に設定
  session.setLocalWindowSize(expectedWindowSize)
})

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

http2session.setTimeout(msecs, callback)

[履歴]

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

• msecs <number>
• callback <Function>

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

http2session.socket

追加: v8.4.0

• <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

追加: 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.0	callback 引数に無効なコールバックを渡すと、ERR_INVALID_CALLBACK ではなく ERR_INVALID_ARG_TYPE がスローされるようになりました。
v8.4.0	v8.4.0 で追加されました。

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

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

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

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

http2session.type

追加: v8.4.0

• <数値>

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

http2session.unref()

追加: v9.4.0

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

クラス: ServerHttp2Session

追加: v8.4.0

• 拡張: <Http2Session>

serverhttp2session.altsvc(alt, originOrStream)

追加: v9.4.0

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

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

ESM

import { createServer } from 'node:http2'

const server = createServer()
server.on('session', session => {
  // オリジン 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)
})

CJS

const http2 = require('node:http2')

const server = http2.createServer()
server.on('session', session => {
  // オリジン 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 およびオリジン文字列には 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

• origins <string> | <URL> | <Object> 複数の URL 文字列を個別の引数として渡します。

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

ESM

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

CJS

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 サーバーを作成するときに使用できます。

ESM

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

CJS

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

• 拡張: <Http2Session>

イベント: 'altsvc'

追加: v9.4.0

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

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

ESM

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

CJS

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

• origins <string[]>

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

ESM

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

CJS

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

追加: v8.4.0

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

• options <Object>

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

ESM

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', () => {
    /* .. */
  })
})

CJS

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

• 継承: <stream.Duplex>

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' ヘッダーを使用して文字エンコーディングを設定してください。

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 インスタンスは、もはや使用できません。

イベント: 'aborted'

追加: v8.4.0

'aborted' イベントは、Http2Stream インスタンスが通信中に異常終了するたびに発行されます。そのリスナーは引数を期待しません。

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

イベント: 'close'

追加: v8.4.0

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

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

イベント: 'error'

追加: v8.4.0

• error <Error>

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

イベント: 'frameError'

追加: v8.4.0

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

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

イベント: 'ready'

追加: v8.4.0

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

イベント: 'timeout'

追加: v8.4.0

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

イベント: 'trailers'

追加: v8.4.0

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

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

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

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

イベント: 'wantTrailers'

追加: v10.0.0

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

http2stream.aborted

追加: v8.4.0

• <<boolean>>

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

http2stream.bufferSize

追加: v11.2.0, v10.16.0

• <<number>>

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

http2stream.close(code[, callback])

[履歴]

バージョン	変更点
v18.0.0	callback 引数に無効なコールバックを渡すと、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

• <<boolean>>

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

http2stream.destroyed

追加: v8.4.0

• <<boolean>>

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

http2stream.endAfterHeaders

追加: v10.11.0

• <boolean>

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

http2stream.id

追加: v8.4.0

• <number> | <undefined>

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

http2stream.pending

追加: v9.4.0

• <boolean>

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

http2stream.priority(options)

追加: v8.4.0

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

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

http2stream.rstCode

追加: v8.4.0

• <number>

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

http2stream.sentHeaders

追加: v9.5.0

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

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

http2stream.sentInfoHeaders

追加: v9.5.0

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

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

http2stream.sentTrailers

追加: v9.5.0

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

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

http2stream.session

追加: v8.4.0

• <Http2Session>

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

http2stream.setTimeout(msecs, callback)

[履歴]

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

• msecs <number>
• callback <Function>

ESM

import { connect, constants } from 'node:http2'
const client = connect('http://example.org:8000')
const { NGHTTP2_CANCEL } = constants
const req = client.request({ ':path': '/' })

// 5秒間アクティビティがない場合、ストリームをキャンセルします
req.setTimeout(5000, () => req.close(NGHTTP2_CANCEL))

CJS

const http2 = require('node:http2')
const client = http2.connect('http://example.org:8000')
const { NGHTTP2_CANCEL } = http2.constants
const req = client.request({ ':path': '/' })

// 5秒間アクティビティがない場合、ストリームをキャンセルします
req.setTimeout(5000, () => req.close(NGHTTP2_CANCEL))

http2stream.state

追加: 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)

追加: v10.0.0

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

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

ESM

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

CJS

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

• <Http2Stream> を拡張

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

イベント: 'continue'

追加: v8.5.0

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

イベント: 'headers'

追加: v8.4.0

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

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

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

イベント: 'push'

追加: v8.4.0

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

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

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

イベント: 'response'

追加: v8.4.0

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

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

ESM

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

CJS

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

• 拡張: <Http2Stream>

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

http2stream.additionalHeaders(headers)

追加: v8.4.0

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

接続された HTTP/2 ピアに追加のインフォメーション HEADERS フレームを送信します。

http2stream.headersSent

追加: v8.4.0

• <boolean>

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

http2stream.pushAllowed

追加: v8.4.0

• <boolean>

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

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

[履歴]

バージョン	変更
v18.0.0	callback 引数に無効なコールバックを渡すと、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> プッシュストリームが開始された後に呼び出されるコールバック。

  • err <Error>
  • pushStream <ServerHttp2Stream> 返された pushStream オブジェクト。
  • headers <HTTP/2 ヘッダーオブジェクト> pushStream が開始されたヘッダーオブジェクト。

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

ESM

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

CJS

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 に設定して http2stream.priority に weight 値を渡します。

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

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

[履歴]

バージョン	変更点
v14.5.0, v12.19.0	date ヘッダーの明示的な設定を許可。
v8.4.0	v8.4.0 で追加

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

ESM

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

CJS

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

ESM

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

CJS

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.0	fd オプションに FileHandle を指定できるようになりました。
v10.0.0	通常のファイルに限らず、任意の読み取り可能なファイル記述子がサポートされるようになりました。
v8.4.0	v8.4.0 で追加されました。

• 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 インターフェースは自動的に閉じられます。

ESM

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

CJS

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

ESM

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

CJS

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.0	v8.4.0 で追加。

• 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 は通常のファイルを指定する必要があり、そうでない場合は Http2Stream オブジェクトで 'error' イベントが発行されます。

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

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

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

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

ESM

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

CJS

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 レスポンスを返すことができます。

ESM

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

CJS

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

ESM

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

CJS

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

• 拡張: <net.Server>

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

イベント: 'checkContinue'

追加: v8.5.0

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

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

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

このイベントが発行され、処理された場合、'request'イベントは発行されません。

イベント: 'connection'

追加: v8.4.0

• socket <stream.Duplex>

このイベントは、新しい TCP ストリームが確立されたときに発行されます。socketは通常、net.Socket型のオブジェクトです。通常、ユーザーはこのイベントにアクセスしたくないでしょう。

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

イベント: 'request'

追加: v8.4.0

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

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

イベント: 'session'

追加: v8.4.0

• session <ServerHttp2Session>

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

イベント: 'sessionError'

追加: v8.4.0

• error <Error>
• session <ServerHttp2Session>

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

イベント: 'stream'

追加: v8.4.0

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

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

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

ESM

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

CJS

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

イベント: 'timeout'

[履歴]

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

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

server.close([callback])

追加: v8.4.0

• callback <Function>

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

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

server[Symbol.asyncDispose]()

追加: v20.4.0

[安定性: 1 - 実験的]

安定性: 1 安定性: 1 - 実験的

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

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

[履歴]

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

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

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 <HTTP/2 設定オブジェクト>

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

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

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

クラス: Http2SecureServer

追加: v8.4.0

• 拡張: <tls.Server>

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

イベント: 'checkContinue'

追加: v8.5.0

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

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

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

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

イベント: 'connection'

追加: v8.4.0

• socket <stream.Duplex>

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

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

イベント: 'request'

追加: v8.4.0

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

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

イベント: 'session'

追加: v8.4.0

• session <ServerHttp2Session>

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

イベント: 'sessionError'

追加: v8.4.0

• error <Error>
• session <ServerHttp2Session>

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

イベント: 'stream'

追加: v8.4.0

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

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

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

ESM

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

CJS

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

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

追加: v8.4.0

• callback <Function>

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

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

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

[履歴]

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

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

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 <HTTP/2 設定オブジェクト>

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

無効なsettings値の場合、ERR_HTTP2_INVALID_SETTING_VALUEがスローされます。

無効なsettings引数の場合、ERR_INVALID_ARG_TYPEがスローされます。

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

[履歴]

バージョン	変更点
v23.0.0	streamResetBurstとstreamResetRateが追加されました。
v13.0.0	PADDING_STRATEGY_CALLBACKは、PADDING_STRATEGY_ALIGNEDの提供と同等になり、selectPaddingは削除されました。
v13.3.0, v12.16.0	デフォルトが 100 のmaxSessionRejectedStreamsオプションが追加されました。
v13.3.0, v12.16.0	デフォルトが 1000 のmaxSessionInvalidFramesオプションが追加されました。
v12.4.0	optionsパラメーターが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.0	Http1IncomingMessageと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> 整数値の配列は、受信したリモート設定の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()の使用が必要です。

ESM

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)

CJS

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.0	PADDING_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.0	Http2Session の起動時に 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> 未確認の未処理のピングの最大数を設定します。デフォルト: 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 インスタンスを返します。

ESM

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

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

// セキュアな HTTP/2 サーバーを作成します
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)

CJS

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

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

// セキュアな HTTP/2 サーバーを作成します
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])

[履歴]

バージョン	変更点
v13.0.0	PADDING_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 インスタンスを返します。

ESM

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

/* クライアントを使用 */

client.close()

CJS

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

/* クライアントを使用 */

client.close()

http2.constants

追加: v8.4.0

RST_STREAMとGOAWAYのエラーコード

値	名前	定数
0x00	エラーなし	http2.constants.NGHTTP2_NO_ERROR
0x01	プロトコルエラー	http2.constants.NGHTTP2_PROTOCOL_ERROR
0x02	内部エラー	http2.constants.NGHTTP2_INTERNAL_ERROR
0x03	フロー制御エラー	http2.constants.NGHTTP2_FLOW_CONTROL_ERROR
0x04	設定タイムアウト	http2.constants.NGHTTP2_SETTINGS_TIMEOUT
0x05	ストリームが閉じられた	http2.constants.NGHTTP2_STREAM_CLOSED
0x06	フレームサイズエラー	http2.constants.NGHTTP2_FRAME_SIZE_ERROR
0x07	ストリームが拒否された	http2.constants.NGHTTP2_REFUSED_STREAM
0x08	キャンセル	http2.constants.NGHTTP2_CANCEL
0x09	圧縮エラー	http2.constants.NGHTTP2_COMPRESSION_ERROR
0x0a	接続エラー	http2.constants.NGHTTP2_CONNECT_ERROR
0x0b	落ち着いてください	http2.constants.NGHTTP2_ENHANCE_YOUR_CALM
0x0c	不十分なセキュリティ	http2.constants.NGHTTP2_INADEQUATE_SECURITY
0x0d	HTTP/1.1 が必須	http2.constants.NGHTTP2_HTTP_1_1_REQUIRED

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

http2.getDefaultSettings()

追加: v8.4.0

• 返します: <HTTP/2 設定オブジェクト>

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

http2.getPackedSettings([settings])

追加: v8.4.0

• settings <HTTP/2 設定オブジェクト>
• 返します: <Buffer>

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

ESM

import { getPackedSettings } from 'node:http2'

const packed = getPackedSettings({ enablePush: false })

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

CJS

const http2 = require('node:http2')

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

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

http2.getUnpackedSettings(buf)

追加: v8.4.0

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

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

http2.performServerHandshake(socket[, options])

追加: v21.7.0, v20.12.0

• socket <stream.Duplex>

• options <Object>

  • ...: http2.createServer() のオプションを指定できます。

• 戻り値: <ServerHttp2Session>

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

http2.sensitiveHeaders

追加: v15.0.0, v14.18.0

• <symbol>

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

ヘッダーオブジェクト

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

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ヘッダーの場合、値は '; 'で結合されます。
• 他のすべてのヘッダーの場合、値は ', 'で結合されます。

ESM

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

CJS

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]プロパティに追加します。

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ヘッダーなど）では、このフラグが自動的に設定されます。

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

設定オブジェクト

[履歴]

バージョン	変更
v12.12.0	maxConcurrentStreams設定がより厳格になりました。
v8.9.3	maxHeaderListSize設定が厳密に適用されるようになりました。
v8.4.0	追加: v8.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> Http2Sessionインスタンスで HTTP/2 プッシュストリームを許可する場合はtrueを指定します。デフォルト: true。
• initialWindowSize <number> ストリームレベルのフロー制御で送信者の初期ウィンドウサイズをバイト単位で指定します。最小許容値は 0 です。最大許容値は 2^32-1 です。デフォルト: 65535。
• maxFrameSize <number> 最大フレームペイロードのサイズをバイト単位で指定します。最小許容値は 16,384 です。最大許容値は 2^24-1 です。デフォルト: 16384。
• maxConcurrentStreams <number> Http2Sessionで許可される同時ストリームの最大数を指定します。デフォルト値はなく、理論的には、Http2Sessionでいつでも同時に 2^32-1 ストリームを開くことができることを意味します。最小値は 0 です。最大許容値は 2^32-1 です。デフォルト: 4294967295。
• maxHeaderListSize <number> 受け入れられるヘッダーリストの最大サイズ（非圧縮オクテット）を指定します。最小許容値は 0 です。最大許容値は 2^32-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 の範囲の整数である必要があります。ノードですでに処理されている設定タイプ（つまり、現在 6 よりも大きい必要があります）であってはなりませんが、エラーではありません。値は、0 から 2^32-1 の範囲の符号なし整数である必要があります。現在、最大 10 個のカスタム設定がサポートされています。これは、SETTINGS の送信、またはサーバーまたはクライアントオブジェクトのremoteCustomSettingsオプションで指定された設定値の受信でのみサポートされています。設定が将来の node バージョンでネイティブにサポートされる場合、設定 ID にcustomSettingsメカニズムをネイティブに処理される設定のインターフェイスと混在させないでください。

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

エラー処理

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/1 の実装よりも HTTP ヘッダー名と値の無効な文字の処理が厳格になっています。

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

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

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

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

クライアントでのプッシュストリーム

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

ESM

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': '/' })

CJS

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 サーバー：

ESM

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)

CJS

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 プロキシ：

ESM

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)

CJS

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 クライアント：

ESM

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

CJS

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 プロトコル" 拡張を定義しており、他の通信プロトコル (WebSocket など) のトンネルとして CONNECT メソッドを使用して Http2Stream の使用をブートストラップするために使用できます。

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

ESM

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

CJS

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

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

ESM

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' })
    // ...
  }
})

CJS

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 サーバーを作成します。

ESM

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

CJS

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

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

ESM

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

CJS

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 の両方で同じように機能します。

クラス: http2.Http2ServerRequest

追加バージョン: v8.4.0

• 拡張: <stream.Readable>

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

イベント: 'aborted'

追加: v8.4.0

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

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

イベント: 'close'

追加: v8.4.0

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

request.aborted

追加: v10.1.0

• <boolean>

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

request.authority

追加: v8.4.0

• <string>

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

request.complete

追加: v12.10.0

• <boolean>

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

request.connection

追加: v8.4.0

非推奨: v13.0.0 以降

[安定性: 0 - 非推奨]

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

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

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

request.destroy([error])

追加: v8.4.0

• error <Error>

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

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

request.headers

追加: v8.4.0

• <Object>

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

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

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

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

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

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

request.httpVersion

追加: v8.4.0

• <string>

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

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

request.method

追加: v8.4.0

• <string>

リクエストメソッドを文字列として表します。読み取り専用です。例: 'GET'、'DELETE'。

request.rawHeaders

追加: v8.4.0

• <string[]>

生のリクエスト/レスポンスヘッダーリストが、受信したとおりに正確に示されます。

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

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

// 次のような内容が出力されます:
//
// [ '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

追加: v8.4.0

• <string[]>

受信したとおりの、生の要求/応答トレーラーのキーと値。'end' イベントでのみ設定されます。

request.scheme

追加: v8.4.0

• <string>

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

request.setTimeout(msecs, callback)

追加: v8.4.0

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

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

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

request.socket

追加: v8.4.0

• <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

追加: v8.4.0

• <Http2Stream>

リクエストをサポートする Http2Stream オブジェクト。

request.trailers

追加: v8.4.0

• <Object>

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

request.url

追加: v8.4.0

• <string>

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

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

この場合、request.url は以下のようになります：

'/status?name=ryan'

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

クラス: http2.Http2ServerResponse

追加: v8.4.0

• 拡張: <Stream>

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

イベント: 'close'

追加: v8.4.0

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

イベント: 'finish'

追加: v8.4.0

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

このイベントの後、レスポンスオブジェクトではそれ以上のイベントが発生しません。

response.addTrailers(headers)

追加: v8.4.0

• headers <Object>

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

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

response.appendHeader(name, value)

追加: v21.7.0, v20.12.0

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

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

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

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

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

// "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を使用してください。

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

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

response.createPushResponse(headers, callback)

[履歴]

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

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

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

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

[履歴]

バージョン	変更点
v10.0.0	このメソッドは ServerResponse への参照を返すようになりました。
v8.4.0	追加: v8.4.0

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

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

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

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

response.finished

追加: v8.4.0

非推奨: v13.4.0, v12.16.0 以降

[安定性: 0 - 非推奨]

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

• <boolean>

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

response.getHeader(name)

追加: v8.4.0

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

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

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

response.getHeaderNames()

追加: v8.4.0

• 戻り値: <string[]>

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

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

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

response.getHeaders()

追加: v8.4.0

• 戻り値: <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'] }

response.hasHeader(name)

追加: v8.4.0

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

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

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

response.headersSent

追加: v8.4.0

• <boolean>

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

response.removeHeader(name)

追加: v8.4.0

• name <string>

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

response.removeHeader('Content-Encoding')

response.req

追加: v15.7.0

• <http2.Http2ServerRequest>

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

response.sendDate

追加: v8.4.0

• <boolean>

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

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

response.setHeader(name, value)

追加: v8.4.0

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

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

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

または

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

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

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

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

追加: v8.4.0

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

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

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

response.socket

追加: v8.4.0

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

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

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

ESM

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)

CJS

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

• <number>

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

response.statusCode = 404

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

response.statusMessage

追加: v8.4.0

• <string>

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

response.stream

追加: v8.4.0

• <Http2Stream>

レスポンスを裏付ける Http2Stream オブジェクト。

response.writableEnded

追加: v12.9.0

• <boolean>

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

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

追加: v8.4.0

• 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()

追加: v8.4.0

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

response.writeEarlyHints(hints)

追加: v18.11.0

• 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,
})

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

[履歴]

バージョン	変更点
v11.10.0, v10.17.0	end() とのチェーンを可能にするために writeHead() から this を返します。
v8.4.0	追加: v8.4.0

• 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',
})

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

// 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 インスタンスの基本的なパフォーマンスメトリクスを収集するために使用できます。

ESM

import { PerformanceObserver } from 'node:perf_hooks'

const obs = new PerformanceObserver(items => {
  const entry = items.getEntries()[0]
  console.log(entry.entryType) // 'http2' を出力
  if (entry.name === 'Http2Session') {
    // エントリには、Http2Session に関する統計が含まれます。
  } else if (entry.name === 'Http2Stream') {
    // エントリには、Http2Stream に関する統計が含まれます。
  }
})
obs.observe({ entryTypes: ['http2'] })

CJS

const { PerformanceObserver } = require('node:perf_hooks')

const obs = new PerformanceObserver(items => {
  const entry = items.getEntries()[0]
  console.log(entry.entryType) // 'http2' を出力
  if (entry.name === 'Http2Session') {
    // エントリには、Http2Session に関する統計が含まれます。
  } else if (entry.name === 'Http2Stream') {
    // エントリには、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を直接使用する場合）、フォールバック動作を自分で実装する必要があります。