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

암호화 지원이 없는지 확인

node:crypto 모듈에 대한 지원 없이 Node.js를 빌드하는 것이 가능합니다. 이러한 경우 node:http2에서 import하거나 require('node:http2')를 호출하려고 하면 오류가 발생합니다.

CommonJS를 사용하는 경우 try/catch를 사용하여 발생하는 오류를 catch할 수 있습니다.

let http2
try {
  http2 = require('node:http2')
} catch (err) {
  console.error('http2 지원이 비활성화되었습니다!')
}

어휘적 ESM import 키워드를 사용하는 경우 모듈을 로드하려는 시도 전에 process.on('uncaughtException')에 대한 핸들러를 등록(예: 프리로드 모듈 사용)한 경우에만 오류를 catch할 수 있습니다.

ESM을 사용하는 경우 코드가 암호화 지원이 활성화되지 않은 Node.js 빌드에서 실행될 가능성이 있는 경우 어휘적 import 키워드 대신 import() 함수를 사용하는 것을 고려하십시오.

let http2
try {
  http2 = await import('node:http2')
} catch (err) {
  console.error('http2 지원이 비활성화되었습니다!')
}

코어 API

코어 API는 HTTP/2 프로토콜 기능 지원을 위해 특별히 설계된 저수준 인터페이스를 제공합니다. 기존 HTTP/1 모듈 API와의 호환성을 위해 특별히 설계되지 않았습니다. 그러나 호환성 API는 그렇습니다.

http2 코어 API는 클라이언트와 서버 간에 http API보다 훨씬 더 대칭적입니다. 예를 들어, 'error', 'connect' 및 'stream'과 같은 대부분의 이벤트는 클라이언트 측 코드 또는 서버 측 코드에서 모두 발생할 수 있습니다.

서버측 예제

다음은 Core API를 사용하는 간단한 HTTP/2 서버를 보여줍니다. 암호화되지 않은 HTTP/2를 지원하는 브라우저가 없으므로, 브라우저 클라이언트와 통신할 때는 http2.createSecureServer()를 사용해야 합니다.

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 is a 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 is a 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 인스턴스는 생성될 때 정확히 하나의 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 <정수> 프레임 유형.
• code <정수> 오류 코드.
• id <정수> 스트림 ID(프레임이 스트림과 연결되지 않은 경우 0).

'frameError' 이벤트는 세션에서 프레임을 보내려고 할 때 오류가 발생하면 발생합니다. 보낼 수 없는 프레임이 특정 Http2Stream과 연결된 경우, Http2Stream에서 'frameError' 이벤트를 발생시키려고 시도합니다.

'frameError' 이벤트가 스트림과 연결된 경우, 스트림은 'frameError' 이벤트 직후에 즉시 닫히고 삭제됩니다. 이벤트가 스트림과 연결되지 않은 경우, Http2Session은 'frameError' 이벤트 직후에 즉시 종료됩니다.

이벤트: 'goaway'

추가됨: v8.8.0

• errorCode <숫자> GOAWAY 프레임에 지정된 HTTP/2 오류 코드.
• lastStreamID <숫자> 원격 피어가 성공적으로 처리한 마지막 스트림의 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 <숫자> 관련 숫자 플래그입니다.
• rawHeaders <배열> 각각의 값 다음에 해당하는 원시 헤더 이름을 포함하는 배열입니다.

'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가 undefined가 아닌 경우 기본값은 INTERNAL_ERROR이고, 그렇지 않으면 NO_ERROR입니다.

Http2Session과 관련된 net.Socket 또는 tls.TLSSocket을 즉시 종료합니다.

삭제된 후 Http2Session은 'close' 이벤트를 발생시킵니다. error가 undefined가 아닌 경우 '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가 throw됩니다.
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가 제공되는 경우 Buffer, TypedArray 또는 DataView여야 하며, PING과 함께 전송되고 ping 승인과 함께 반환되는 8바이트의 데이터를 포함해야 합니다.

콜백은 세 가지 인수를 사용하여 호출됩니다. PING이 성공적으로 승인된 경우 null이 되는 오류 인수, ping이 전송된 시점부터 승인이 수신될 때까지 경과된 밀리초 수를 보고하는 duration 인수, 8바이트 PING 페이로드가 포함된 Buffer입니다.

session.ping(Buffer.from('abcdefgh'), (err, duration, payload) => {
  if (!err) {
    console.log(`Ping이 ${duration}밀리초 안에 승인되었습니다`)
    console.log(`페이로드 '${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 <숫자>

로컬 엔드포인트의 창 크기를 설정합니다. 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를 throw합니다.
v8.4.0	추가됨: v8.4.0

• msecs <숫자>
• callback <함수>

msecs 밀리초 후에 Http2Session에서 활동이 없을 때 호출되는 콜백 함수를 설정하는 데 사용됩니다. 지정된 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을 사용하여 오류를 throw합니다. 자세한 내용은 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를 throw합니다.
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 <문자열> RFC 7838에 정의된 대체 서비스 구성에 대한 설명입니다.
• originOrStream <숫자> | <문자열> | <URL> | <객체> 원본을 지정하는 URL 문자열(또는 origin 속성이 있는 객체) 또는 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로 구문 분석할 수 없거나 유효한 원본을 파생할 수 없는 경우 오류가 발생합니다.

origin 속성이 있는 URL 객체 또는 객체를 originOrStream으로 전달할 수 있습니다. 이 경우 origin 속성의 값이 사용됩니다. origin 속성의 값은 올바르게 직렬화된 ASCII 원본이어야 합니다.

대체 서비스 지정

alt 매개변수의 형식은 RFC 7838에 의해 특정 호스트와 포트에 연결된 "대체" 프로토콜의 쉼표로 구분된 목록을 포함하는 ASCII 문자열로 엄격하게 정의됩니다.

예를 들어, 'h2="example.org:81"' 값은 TCP/IP 포트 81의 호스트 'example.org'에서 HTTP/2 프로토콜을 사용할 수 있음을 나타냅니다. 호스트와 포트는 반드시 따옴표(") 안에 포함되어야 합니다.

여러 대체값을 지정할 수 있습니다. 예: '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 원본이어야 합니다.

또는 http2.createSecureServer() 메서드를 사용하여 새 HTTP/2 서버를 만들 때 origins 옵션을 사용할 수 있습니다.

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 값, origin 및 stream 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은 수신된 origin을 포함하도록 업데이트됩니다.

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 <객체>

  • endStream <부울> GET 요청처럼 페이로드 본문을 기대하지 않는 경우와 같이 Http2Stream 쓰기 가능 측면을 처음에 닫아야 하는 경우 true입니다.
  • exclusive <부울> true이고 parent가 상위 스트림을 식별하는 경우 생성된 스트림은 상위 스트림의 유일한 직접 종속 항목이 되고, 다른 모든 기존 종속 항목은 새로 생성된 스트림의 종속 항목이 됩니다. 기본값: false.
  • parent <숫자> 새로 생성된 스트림이 종속된 스트림의 숫자 식별자를 지정합니다.
  • weight <숫자> 같은 parent를 가진 다른 스트림과 관련하여 스트림의 상대적 종속성을 지정합니다. 값은 1과 256 (포함) 사이의 숫자입니다.
  • waitForTrailers <부울> true인 경우 Http2Stream은 마지막 DATA 프레임이 전송된 후 'wantTrailers' 이벤트를 방출합니다.
  • signal <AbortSignal> 진행 중인 요청을 중단하는 데 사용할 수 있는 AbortSignal입니다.

• 반환값: <ClientHttp2Stream>

HTTP/2 클라이언트 Http2Session 인스턴스에만 해당하는 http2session.request()는 연결된 서버에 HTTP/2 요청을 보내는 데 사용할 수 있는 Http2Stream 인스턴스를 생성하고 반환합니다.

ClientHttp2Session이 처음 생성될 때 소켓이 아직 연결되지 않았을 수 있습니다. 이때 clienthttp2session.request()를 호출하면 소켓이 준비될 때까지 실제 요청이 지연됩니다. 실제 요청이 실행되기 전에 session이 닫히면 ERR_HTTP2_GOAWAY_SESSION이 throw됩니다.

이 메서드는 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가 설정된 경우 마지막 DATA 프레임이 전송될 때 Http2Stream이 자동으로 닫히지 않습니다. 사용자 코드는 http2stream.sendTrailers() 또는 http2stream.close()를 호출하여 Http2Stream을 닫아야 합니다.

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가 throw됩니다.
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 플래그가 설정되어 추가 데이터를 수신할 필요가 없으며 Http2Stream의 읽기 가능한 쪽이 닫힘을 나타내는 경우 true로 설정합니다.

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가 throw됩니다.
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

요청에 Expect: 100-continue가 포함되어 있기 때문에 서버가 100 Continue 상태를 보낼 때 발생합니다. 이는 클라이언트가 요청 본문을 보내야 한다는 지시입니다.

이벤트: 'headers'

추가됨: v8.4.0

• headers <HTTP/2 헤더 객체>
• flags <숫자>

'headers' 이벤트는 1xx 정보 헤더 블록이 수신될 때와 같이 스트림에 대한 추가 헤더 블록이 수신될 때 발생합니다. 리스너 콜백에는 HTTP/2 헤더 객체와 헤더와 관련된 플래그가 전달됩니다.

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

이벤트: 'push'

추가됨: v8.4.0

• headers <HTTP/2 헤더 객체>
• flags <숫자>

'push' 이벤트는 서버 푸시 스트림에 대한 응답 헤더가 수신될 때 발생합니다. 리스너 콜백에는 HTTP/2 헤더 객체와 헤더와 관련된 플래그가 전달됩니다.

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

이벤트: 'response'

추가됨: v8.4.0

• headers <HTTP/2 헤더 객체>
• flags <숫자>

'response' 이벤트는 연결된 HTTP/2 서버에서 이 스트림에 대한 응답 HEADERS 프레임이 수신되었을 때 발생합니다. 리스너는 수신된 HTTP/2 헤더 객체가 포함된 Object와 헤더와 관련된 플래그라는 두 개의 인수를 사용하여 호출됩니다.

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를 throw합니다.
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이 시작된 헤더 객체.

푸시 스트림을 시작합니다. 콜백은 두 번째 인수로 전달된 푸시 스트림에 대해 생성된 새로운 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	날짜 헤더 명시적으로 설정 허용
v8.4.0	추가됨: v8.4.0

• headers <HTTP/2 헤더 객체>
• options <객체>
  • endStream <부울> 응답에 페이로드 데이터가 포함되지 않음을 나타내려면 true로 설정합니다.
  • waitForTrailers <부울> 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.sendTrailers() 또는 http2stream.close()를 호출하여 Http2Stream을 닫아야 합니다.

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 <숫자> | <FileHandle> 읽기 가능한 파일 디스크립터.
• headers <HTTP/2 헤더 객체>
• options <객체>
  • statCheck <함수>
  • waitForTrailers <불리언> true일 경우, Http2Stream은 최종 DATA 프레임이 전송된 후 'wantTrailers' 이벤트를 방출합니다.
  • offset <숫자> 읽기를 시작할 오프셋 위치.
  • length <숫자> fd에서 전송할 데이터의 양.

주어진 파일 디스크립터에서 데이터를 읽는 응답을 시작합니다. 주어진 파일 디스크립터에 대한 유효성 검사는 수행되지 않습니다. 파일 디스크립터를 사용하여 데이터를 읽는 동안 오류가 발생하면 표준 INTERNAL_ERROR 코드를 사용하여 RST_STREAM 프레임을 사용하여 Http2Stream이 닫힙니다.

사용될 때, 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가 설정되면 최종 DATA 프레임이 전송될 때 Http2Stream이 자동으로 닫히지 않습니다. 사용자 코드는 http2stream.sendTrailers() 또는 http2stream.close()를 호출하여 Http2Stream을 닫아야 합니다.

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 <문자열> | <Buffer> | <URL>
• headers <HTTP/2 헤더 객체>
• options <객체>
  • statCheck <함수>
  • onError <함수> 전송 전 오류 발생 시 호출되는 콜백 함수.
  • waitForTrailers <불리언> true일 경우, Http2Stream은 최종 DATA 프레임이 전송된 후 'wantTrailers' 이벤트를 방출합니다.
  • offset <숫자> 읽기를 시작할 오프셋 위치.
  • length <숫자> fd에서 전송할 데이터 양.

일반 파일을 응답으로 보냅니다. path는 일반 파일을 지정해야 하며, 그렇지 않으면 Http2Stream 객체에서 'error' 이벤트가 방출됩니다.

사용 시 Http2Stream 객체의 Duplex 인터페이스는 자동으로 닫힙니다.

선택적 options.statCheck 함수는 사용자 코드에 주어진 파일의 fs.Stat 세부 정보에 따라 추가 콘텐츠 헤더를 설정할 수 있는 기회를 제공합니다.

파일 데이터를 읽는 동안 오류가 발생하면 표준 INTERNAL_ERROR 코드를 사용하는 RST_STREAM 프레임을 사용하여 Http2Stream이 닫힙니다. 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.sendTrailers() 또는 http2stream.close()를 호출하여 Http2Stream을 닫아야 합니다.

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 <숫자> 관련 숫자 플래그
• rawHeaders <배열> 각 값 앞에 해당 헤더 이름이 포함된 배열

'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 <함수>

새 세션을 설정하는 것을 서버에서 중지합니다. 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가 throw됩니다.
v13.0.0	기본 제한 시간이 120초에서 0(제한 시간 없음)으로 변경되었습니다.
v8.4.0	추가됨: v8.4.0

• msecs <숫자> 기본값: 0(제한 시간 없음)
• callback <함수>
• 반환값: <Http2Server>

http2 서버 요청에 대한 제한 시간 값을 설정하고, msecs 밀리초 후에 Http2Server에서 활동이 없을 때 호출되는 콜백 함수를 설정하는 데 사용됩니다.

주어진 콜백은 'timeout' 이벤트에 대한 리스너로 등록됩니다.

callback이 함수가 아닌 경우 새 ERR_INVALID_ARG_TYPE 오류가 throw됩니다.

server.timeout

[이력]

버전	변경 사항
v13.0.0	기본 제한 시간이 120초에서 0(제한 시간 없음)으로 변경되었습니다.
v8.4.0	추가됨: v8.4.0

• <숫자> 밀리초 단위의 제한 시간. 기본값: 0(제한 시간 없음)

소켓이 제한 시간이 초과되었다고 간주되기 전까지의 비활동 밀리초 수입니다.

0 값은 들어오는 연결에 대한 제한 시간 동작을 비활성화합니다.

소켓 제한 시간 로직은 연결 시 설정되므로 이 값을 변경해도 서버에 대한 기존 연결에는 영향을 미치지 않고 새로운 연결에만 영향을 미칩니다.

server.updateSettings([settings])

추가됨: v15.1.0, v14.17.0

• settings <HTTP/2 설정 개체>

제공된 설정으로 서버를 업데이트하는 데 사용됩니다.

잘못된 settings 값에 대해 ERR_HTTP2_INVALID_SETTING_VALUE를 throw합니다.

잘못된 settings 인수에 대해 ERR_INVALID_ARG_TYPE를 throw합니다.

클래스: 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 잘못된 요청)을 생성해야 합니다.

이 이벤트가 발생하고 처리되면 '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 <숫자> 관련 숫자 플래그
• rawHeaders <배열> 각 값 앞에 해당 헤더 이름이 나열된 배열

'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() [/api/http2#http2createsecureserveroptions-onrequesthandler]에 전달된 '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를 throw합니다.
v8.4.0	추가됨: v8.4.0

• msecs <숫자> 기본값: 120000 (2분)
• callback <함수>
• 반환값: <Http2SecureServer>

http2 보안 서버 요청에 대한 시간 초과 값을 설정하고, msecs 밀리초 후에 Http2SecureServer에 활동이 없을 때 호출되는 콜백 함수를 설정하는 데 사용됩니다.

주어진 콜백은 'timeout' 이벤트에 대한 리스너로 등록됩니다.

callback이 함수가 아닌 경우 새 ERR_INVALID_ARG_TYPE 오류가 throw됩니다.

server.timeout

[히스토리]

버전	변경 사항
v13.0.0	기본 시간 초과가 120초에서 0(시간 초과 없음)으로 변경되었습니다.
v8.4.0	추가됨: v8.4.0

• <숫자> 밀리초 단위의 시간 초과. 기본값: 0(시간 초과 없음)

소켓이 시간 초과된 것으로 간주되기 전의 비활동 밀리초 수입니다.

값이 0이면 들어오는 연결에 대한 시간 초과 동작이 비활성화됩니다.

소켓 시간 초과 로직은 연결 시 설정되므로 이 값을 변경해도 서버에 대한 기존 연결이 아니라 새 연결에만 영향을 미칩니다.

server.updateSettings([settings])

추가됨: v15.1.0, v14.17.0

• settings <HTTP/2 설정 객체>

제공된 설정으로 서버를 업데이트하는 데 사용됩니다.

잘못된 settings 값에 대해 ERR_HTTP2_INVALID_SETTING_VALUE를 throw합니다.

잘못된 settings 인수에 대해 ERR_INVALID_ARG_TYPE를 throw합니다.

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 <객체>

  • maxDeflateDynamicTableSize <숫자> 헤더 필드를 디플레이트하기 위한 최대 동적 테이블 크기를 설정합니다. 기본값: 4Kib.

  • maxSettings <숫자> SETTINGS 프레임당 최대 설정 항목 수를 설정합니다. 허용되는 최소값은 1입니다. 기본값: 32.

  • maxSessionMemory<숫자> Http2Session이 사용할 수 있는 최대 메모리를 설정합니다. 값은 메가바이트 단위로 표현됩니다(예: 1은 1메가바이트). 허용되는 최소값은 1입니다. 이것은 크레딧 기반 제한이며, 기존 Http2Stream으로 인해 이 제한을 초과할 수 있지만, 이 제한을 초과하는 동안에는 새 Http2Stream 인스턴스가 거부됩니다. 현재 Http2Stream 세션 수, 헤더 압축 테이블의 현재 메모리 사용량, 전송 대기 중인 현재 데이터 및 확인되지 않은 PING 및 SETTINGS 프레임은 모두 현재 제한에 포함됩니다. 기본값: 10.

  • maxHeaderListPairs <숫자> 최대 헤더 항목 수를 설정합니다. 이것은 node:http 모듈의 server.maxHeadersCount 또는 request.maxHeadersCount와 유사합니다. 최소값은 4입니다. 기본값: 128.

  • maxOutstandingPings <숫자> 확인되지 않은 미결제 ping의 최대 수를 설정합니다. 기본값: 10.

  • maxSendHeaderBlockLength <숫자> 직렬화된 압축된 헤더 블록의 최대 허용 크기를 설정합니다. 이 제한을 초과하는 헤더를 보내려고 하면 'frameError' 이벤트가 발생하고 스트림이 닫히고 삭제됩니다. 이것은 헤더의 전체 블록에 대한 최대 허용 크기를 설정하지만, nghttp2(내부 http2 라이브러리)는 각 압축 해제된 키/값 쌍에 대해 65536의 제한이 있습니다.

  • paddingStrategy <숫자> 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 <숫자> SETTINGS 프레임이 수신된 것처럼 원격 피어에 대한 최대 동시 스트림 수를 설정합니다. 원격 피어가 maxConcurrentStreams에 대한 자체 값을 설정하면 덮어써집니다. 기본값: 100.

  • maxSessionInvalidFrames <정수> 세션이 닫히기 전에 허용되는 잘못된 프레임의 최대 수를 설정합니다. 각 거부는 피어에게 더 이상 스트림을 열지 말라고 알려주는 NGHTTP2_ENHANCE_YOUR_CALM 오류와 연결됩니다. 따라서 스트림을 계속 열면 잘못된 피어의 징후로 간주됩니다. 기본값: 1000.

  • maxSessionRejectedStreams <정수> 세션이 닫히기 전에 허용되는 생성 시 거부된 스트림의 최대 수를 설정합니다. 각 거부는 피어에게 더 이상 스트림을 열지 말라고 알려주는 NGHTTP2_ENHANCE_YOUR_CALM 오류와 연결됩니다. 따라서 스트림을 계속 열면 잘못된 피어의 징후로 간주됩니다. 기본값: 100.

  • settings <HTTP/2 설정 객체> 연결 시 원격 피어로 보낼 초기 설정입니다.

  • streamResetBurst <숫자> 및 streamResetRate <숫자> 들어오는 스트림 재설정(RST_STREAM 프레임)에 대한 속도 제한을 설정합니다. 효과를 보려면 두 설정을 모두 설정해야 하며, 기본값은 각각 1000과 33입니다.

  • remoteCustomSettings <배열> 정수 값 배열은 수신된 remoteSettings의 CustomSettings 속성에 포함된 설정 유형을 결정합니다. 허용되는 설정 유형에 대한 자세한 내용은 Http2Settings 객체의 CustomSettings 속성을 참조하십시오.

  • Http1IncomingMessage <http.IncomingMessage> HTTP/1 대체에 사용할 IncomingMessage 클래스를 지정합니다. 원래 http.IncomingMessage를 확장하는 데 유용합니다. 기본값: http.IncomingMessage.

  • Http1ServerResponse <http.ServerResponse> HTTP/1 대체에 사용할 ServerResponse 클래스를 지정합니다. 원래 http.ServerResponse를 확장하는 데 유용합니다. 기본값: http.ServerResponse.

  • Http2ServerRequest <http2.Http2ServerRequest> 사용할 Http2ServerRequest 클래스를 지정합니다. 원래 Http2ServerRequest를 확장하는 데 유용합니다. 기본값: Http2ServerRequest.

  • Http2ServerResponse <http2.Http2ServerResponse> 사용할 Http2ServerResponse 클래스를 지정합니다. 원래 Http2ServerResponse를 확장하는 데 유용합니다. 기본값: Http2ServerResponse.

  • unknownProtocolTimeout <숫자> 'unknownProtocol'이 발생했을 때 서버가 대기해야 하는 시간 초과를 밀리초 단위로 지정합니다. 그때까지 소켓이 삭제되지 않으면 서버가 소켓을 삭제합니다. 기본값: 10000.

  • ...: 모든 net.createServer() 옵션을 제공할 수 있습니다.

• onRequestHandler <함수> 호환성 API 참조

• 반환값: <Http2Server>

Http2Session 인스턴스를 생성하고 관리하는 net.Server 인스턴스를 반환합니다.

암호화되지 않은 HTTP/2를 지원하는 것으로 알려진 브라우저가 없으므로(암호화되지 않은 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> true로 설정하면 HTTP/2를 지원하지 않는 들어오는 클라이언트 연결이 HTTP/1.x로 다운그레이드됩니다. 'unknownProtocol' 이벤트를 참조하십시오. ALPN 협상을 참조하십시오. 기본값: false.

  • maxDeflateDynamicTableSize <number> 헤더 필드 압축을 위한 최대 동적 테이블 크기를 설정합니다. 기본값: 4Kib.

  • maxSettings <number> SETTINGS 프레임당 최대 설정 항목 수를 설정합니다. 허용되는 최소값은 1입니다. 기본값: 32.

  • maxSessionMemory<number> Http2Session이 사용할 수 있는 최대 메모리를 설정합니다. 값은 메가바이트 단위로 표현됩니다(예: 1은 1메가바이트). 허용되는 최소값은 1입니다. 이것은 크레딧 기반 제한이며, 기존 Http2Stream으로 인해 이 제한을 초과할 수 있지만, 이 제한을 초과하는 동안에는 새 Http2Stream 인스턴스가 거부됩니다. 현재 Http2Stream 세션 수, 헤더 압축 테이블의 현재 메모리 사용량, 전송 대기 중인 현재 데이터, 승인되지 않은 PING 및 SETTINGS 프레임은 모두 현재 제한에 포함됩니다. 기본값: 10.

  • maxHeaderListPairs <number> 최대 헤더 항목 수를 설정합니다. node:http 모듈의 server.maxHeadersCount 또는 request.maxHeadersCount와 유사합니다. 최소값은 4입니다. 기본값: 128.

  • maxOutstandingPings <number> 승인되지 않은 미결제 ping의 최대 수를 설정합니다. 기본값: 10.

  • maxSendHeaderBlockLength <number> 직렬화된 압축된 헤더 블록의 허용되는 최대 크기를 설정합니다. 이 제한을 초과하는 헤더를 보내려고 하면 'frameError' 이벤트가 발생하고 스트림이 닫히고 파괴됩니다.

  • paddingStrategy <number> HEADERS 및 DATA 프레임에 사용할 패딩 양을 결정하는 데 사용되는 전략입니다. 기본값: http2.constants.PADDING_STRATEGY_NONE. 값은 다음 중 하나일 수 있습니다.

  • http2.constants.PADDING_STRATEGY_NONE: 패딩이 적용되지 않습니다.

  • http2.constants.PADDING_STRATEGY_MAX: 내부 구현에서 결정된 최대 패딩량이 적용됩니다.

  • http2.constants.PADDING_STRATEGY_ALIGNED: 총 프레임 길이(9바이트 헤더 포함)가 8의 배수가 되도록 충분한 패딩을 적용하려고 시도합니다. 각 프레임에 대해 현재 흐름 제어 상태 및 설정에 따라 결정되는 최대 허용 패딩 바이트 수가 있습니다. 이 최대값이 정렬에 필요한 계산된 양보다 작으면 최대값이 사용되고 총 프레임 길이는 반드시 8바이트로 정렬되지 않습니다.

  • peerMaxConcurrentStreams <number> SETTINGS 프레임을 수신한 것처럼 원격 피어에 대한 최대 동시 스트림 수를 설정합니다. 원격 피어가 maxConcurrentStreams에 대한 자체 값을 설정하면 재정의됩니다. 기본값: 100.

  • maxSessionInvalidFrames <integer> 세션이 닫히기 전에 허용되는 잘못된 프레임의 최대 수를 설정합니다. 기본값: 1000.

  • maxSessionRejectedStreams <integer> 세션이 닫히기 전에 허용되는 생성 시 거부된 스트림의 최대 수를 설정합니다. 각 거부는 피어에게 더 이상 스트림을 열지 말라고 알려주는 NGHTTP2_ENHANCE_YOUR_CALM 오류와 연결되므로, 스트림을 계속 여는 것은 잘못된 피어의 징후로 간주됩니다. 기본값: 100.

  • settings <HTTP/2 설정 객체> 연결 시 원격 피어로 보낼 초기 설정입니다.

  • remoteCustomSettings <Array> 정수 값 배열은 수신된 remoteSettings의 customSettings 속성에 포함된 설정 유형을 결정합니다. 허용되는 설정 유형에 대한 자세한 내용은 Http2Settings 객체의 customSettings 속성을 참조하십시오.

  • ...: 모든 tls.createServer() 옵션을 제공할 수 있습니다. 서버의 경우 ID 옵션(pfx 또는 key/cert)이 일반적으로 필요합니다.

  • origins <string[]> 새 서버 Http2Session 생성 직후 ORIGIN 프레임 내에서 보낼 원본 문자열 배열입니다.

  • unknownProtocolTimeout <number> 'unknownProtocol' 이벤트가 발생했을 때 서버가 대기해야 하는 시간 제한을 밀리초 단위로 지정합니다. 지정된 시간 내에 소켓이 파괴되지 않으면 서버가 소켓을 파괴합니다. 기본값: 10000.

• onRequestHandler <Function> 호환성 API 참조

• 반환값: <Http2SecureServer>

Http2Session 인스턴스를 생성하고 관리하는 tls.Server 인스턴스를 반환합니다.

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 <문자열> | <URL> 연결할 원격 HTTP/2 서버입니다. http:// 또는 https:// 접두사, 호스트 이름 및 IP 포트(기본 포트가 아닌 포트를 사용하는 경우)를 포함하는 최소한의 유효한 URL 형식이어야 합니다. URL의 사용자 정보(사용자 ID 및 암호), 경로, 쿼리 문자열 및 조각 세부 정보는 무시됩니다.

• options <객체>

  • maxDeflateDynamicTableSize <숫자> 헤더 필드를 압축 해제하기 위한 최대 동적 테이블 크기를 설정합니다. 기본값: 4Kib.

  • maxSettings <숫자> SETTINGS 프레임당 최대 설정 항목 수를 설정합니다. 허용되는 최소값은 1입니다. 기본값: 32.

  • maxSessionMemory<숫자> Http2Session이 사용할 수 있는 최대 메모리를 설정합니다. 값은 메가바이트 단위로 표현됩니다(예: 1은 1메가바이트). 허용되는 최소값은 1입니다. 이는 크레딧 기반 제한이며, 기존 Http2Stream으로 인해 이 제한을 초과할 수 있지만, 이 제한을 초과하는 동안에는 새 Http2Stream 인스턴스가 거부됩니다. 현재 Http2Stream 세션 수, 헤더 압축 테이블의 현재 메모리 사용량, 전송 대기 중인 현재 데이터 및 승인되지 않은 PING 및 SETTINGS 프레임이 모두 현재 제한에 포함됩니다. 기본값: 10.

  • maxHeaderListPairs <숫자> 최대 헤더 항목 수를 설정합니다. node:http 모듈의 server.maxHeadersCount 또는 request.maxHeadersCount와 유사합니다. 최소값은 1입니다. 기본값: 128.

  • maxOutstandingPings <숫자> 승인되지 않은 미결제 ping의 최대 수를 설정합니다. 기본값: 10.

  • maxReservedRemoteStreams <숫자> 클라이언트가 특정 시점에 허용할 예약된 푸시 스트림의 최대 수를 설정합니다. 현재 예약된 푸시 스트림의 수가 이 제한을 초과하면 서버에서 보낸 새로운 푸시 스트림은 자동으로 거부됩니다. 허용되는 최소값은 0입니다. 허용되는 최대값은 2-1입니다. 음수 값은 이 옵션을 허용되는 최대값으로 설정합니다. 기본값: 200.

  • maxSendHeaderBlockLength <숫자> 직렬화되고 압축된 헤더 블록의 허용되는 최대 크기를 설정합니다. 이 제한을 초과하는 헤더를 보내려고 하면 'frameError' 이벤트가 발생하고 스트림이 닫히고 삭제됩니다.

  • paddingStrategy <숫자> 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 <숫자> SETTINGS 프레임이 수신된 것처럼 원격 피어의 최대 동시 스트림 수를 설정합니다. 원격 피어가 maxConcurrentStreams에 대한 자체 값을 설정하면 재정의됩니다. 기본값: 100.

  • protocol <문자열> authority에 설정되지 않은 경우 연결할 프로토콜입니다. 값은 'http:' 또는 'https:'일 수 있습니다. 기본값: 'https:'

  • settings <HTTP/2 설정 객체> 연결 시 원격 피어로 보낼 초기 설정입니다.

  • remoteCustomSettings <배열> 정수 값 배열은 수신된 remoteSettings의 CustomSettings 속성에 포함된 설정 유형을 결정합니다. 허용되는 설정 유형에 대한 자세한 내용은 Http2Settings 객체의 CustomSettings 속성을 참조하십시오.

  • createConnection <함수> connect에 전달된 URL 인스턴스와 options 객체를 수신하고 이 세션의 연결로 사용할 모든 Duplex 스트림을 반환하는 선택적 콜백입니다.

  • ...: 모든 net.connect() 또는 tls.connect() 옵션을 제공할 수 있습니다.

  • unknownProtocolTimeout <숫자> 'unknownProtocol' 이벤트가 발생할 때 서버가 대기해야 하는 시간 제한(밀리초)을 지정합니다. 그 시간 내에 소켓이 파괴되지 않으면 서버가 소켓을 파괴합니다. 기본값: 10000.

• listener <함수> 'connect' 이벤트의 일회성 리스너로 등록됩니다.

• 반환값: <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

http2server.setTimeout()을 사용하여 설정된 밀리초 동안 서버에서 활동이 없으면 'timeout' 이벤트가 방출됩니다.

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'))
// 출력: AAIAAAAA

CJS

const http2 = require('node:http2')

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

console.log(packed.toString('base64'))
// 출력: 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 객체의 자체 속성으로 표현됩니다. 속성 키는 소문자로 직렬화됩니다. 속성 값은 문자열이어야 하며(문자열이 아닌 경우 문자열로 강제 변환됨) 또는 문자열의 Array(헤더 필드당 둘 이상의 값을 보내기 위해)여야 합니다.

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-1입니다. 기본값: 4096.
• enablePush <boolean> Http2Session 인스턴스에서 HTTP/2 Push 스트림을 허용할지 여부를 true로 지정합니다. 기본값: true.
• initialWindowSize <number> 스트림 수준 흐름 제어를 위한 보내는 쪽의 초기 창 크기를 바이트 단위로 지정합니다. 허용되는 최소값은 0입니다. 허용되는 최대값은 2-1입니다. 기본값: 65535.
• maxFrameSize <number> 가장 큰 프레임 페이로드의 크기를 바이트 단위로 지정합니다. 허용되는 최소값은 16,384입니다. 허용되는 최대값은 2-1입니다. 기본값: 16384.
• maxConcurrentStreams <number> Http2Session에서 허용되는 동시 스트림의 최대 수를 지정합니다. 기본값이 없으므로 이론적으로는 Http2Session에서 언제든지 최대 2-1개의 스트림을 동시에 열 수 있습니다. 최소값은 0입니다. 허용되는 최대값은 2-1입니다. 기본값: 4294967295.
• maxHeaderListSize <number> 허용되는 헤더 목록의 최대 크기(압축되지 않은 바이트)를 지정합니다. 허용되는 최소값은 0입니다. 허용되는 최대값은 2-1입니다. 기본값: 65535.
• maxHeaderSize <number> maxHeaderListSize의 별칭입니다.
• enableConnectProtocol<boolean> RFC 8441에서 정의한 "확장 연결 프로토콜"을 활성화할지 여부를 true로 지정합니다. 이 설정은 서버에서 보낸 경우에만 의미가 있습니다. 특정 Http2Session에 대해 enableConnectProtocol 설정이 활성화되면 비활성화할 수 없습니다. 기본값: false.
• customSettings <Object> 아직 노드 및 기본 라이브러리에 구현되지 않은 추가 설정을 지정합니다. 객체의 키는 [RFC 7540]에서 설정한 "HTTP/2 SETTINGS" 레지스트리에 정의된 설정 유형의 숫자 값을 정의하고, 값은 설정의 실제 숫자 값을 정의합니다. 설정 유형은 1부터 2^16-1까지의 정수여야 합니다. 현재 노드에서 처리하는 설정 유형이어서는 안 됩니다. 즉, 현재는 6보다 커야 하지만 오류는 아닙니다. 값은 0부터 2^32-1까지의 부호 없는 정수여야 합니다. 현재 최대 10개의 사용자 지정 설정이 지원됩니다. SETTINGS 전송 또는 서버 또는 클라이언트 객체의 remoteCustomSettings 옵션에 지정된 설정 값 수신에만 지원됩니다. 향후 노드 버전에서 설정이 기본적으로 지원되는 경우 customSettings 메커니즘을 설정 ID에 대해 기본적으로 처리되는 설정의 인터페이스와 혼합하지 마십시오.

설정 객체의 모든 추가 속성은 무시됩니다.

오류 처리

node:http2 모듈을 사용할 때 발생할 수 있는 여러 유형의 오류 조건이 있습니다.

잘못된 인수, 옵션 또는 설정 값이 전달되면 유효성 검사 오류가 발생합니다. 이러한 오류는 항상 동기식 throw를 통해 보고됩니다.

잘못된 시점에 작업을 시도할 때(예: 스트림이 닫힌 후 데이터를 전송하려고 시도할 때) 상태 오류가 발생합니다. 이러한 오류는 오류가 발생한 위치와 시점에 따라 Http2Stream, Http2Session 또는 HTTP/2 서버 객체의 동기식 throw 또는 'error' 이벤트를 통해 보고됩니다.

HTTP/2 세션이 예기치 않게 실패하면 내부 오류가 발생합니다. 이러한 오류는 Http2Session 또는 HTTP/2 서버 객체의 'error' 이벤트를 통해 보고됩니다.

다양한 HTTP/2 프로토콜 제약 조건이 위반되면 프로토콜 오류가 발생합니다. 이러한 오류는 오류가 발생한 위치와 시점에 따라 Http2Stream, Http2Session 또는 HTTP/2 서버 객체의 동기식 throw 또는 'error' 이벤트를 통해 보고됩니다.

헤더 이름 및 값의 잘못된 문자 처리

HTTP/2 구현은 HTTP 헤더 이름 및 값의 잘못된 문자 처리에 대해 HTTP/1 구현보다 더 엄격한 처리를 적용합니다.

헤더 필드 이름은 대소문자를 구분하지 않으며 와이어를 통해 소문자 문자열로만 전송됩니다. Node.js에서 제공하는 API는 헤더 이름을 대소문자 혼합 문자열(예: Content-Type)로 설정할 수 있지만 전송 시 소문자(예: content-type)로 변환합니다.

헤더 필드 이름은 다음 ASCII 문자 중 하나 이상만 포함해야 합니다. 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(`서버가 말합니다: ${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(`서버가 말합니다: ${data}`)
  client.close()
})
req.end('Jane')

확장된 CONNECT 프로토콜

RFC 8441은 다른 통신 프로토콜(예: WebSockets)에 대한 터널로 CONNECT 메서드를 사용하여 Http2Stream의 사용을 부트스트래핑하는 데 사용될 수 있는 HTTP/2에 대한 "확장된 CONNECT 프로토콜" 확장을 정의합니다.

확장된 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'와 마찬가지로 이 이벤트는 응답당 한 번만 발생합니다.

request.aborted

추가됨: v10.1.0

• <boolean>

request.aborted 속성은 요청이 중단된 경우 true가 됩니다.

request.authority

추가됨: v8.4.0

• <string>

요청 권한 의사 헤더 필드입니다. 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

[Stable: 0 - 더 이상 사용되지 않음]

Stable: 0 Stability: 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는 두 번째 정수입니다.

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) 역할을 하는 Proxy 객체를 반환하지만 HTTP/2 로직을 기반으로 getter, setter 및 메서드를 적용합니다.

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 코드를 포함하는 오류를 throw합니다. 자세한 내용은 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' 이벤트의 두 번째 매개변수로 전달됩니다.

이벤트: 'close'

추가됨: v8.4.0

response.end()가 호출되거나 플러시되기 전에 기본 Http2Stream이 종료되었음을 나타냅니다.

이벤트: '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

[Stable: 0 - 더 이상 사용되지 않음]

Stable: 0 Stability: 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()을 호출하고 성공하면 주어진 Http2Stream을 새로 생성된 Http2ServerResponse에 콜백 매개변수로 래핑합니다. Http2ServerRequest가 닫히면 ERR_HTTP2_INVALID_STREAM 오류와 함께 콜백이 호출됩니다.

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

[이력]

버전	변경 사항
v10.0.0	이 메서드는 이제 ServerResponse에 대한 참조를 반환합니다.
v8.4.0	추가됨: v8.4.0

• data <문자열> | <Buffer> | <Uint8Array>
• encoding <문자열>
• callback <함수>
• 반환값: <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를 사용하십시오.

• <불리언>

응답이 완료되었는지 여부를 나타내는 불리언 값입니다. false로 시작합니다. response.end()가 실행된 후에는 값이 true가 됩니다.

response.getHeader(name)

추가됨: v8.4.0

• name <문자열>
• 반환값: <문자열>

클라이언트에 아직 전송되지 않았지만 이미 대기열에 추가된 헤더를 읽습니다. 이름은 대소문자를 구분하지 않습니다.

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.0.4

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

net.Socket (또는 tls.TLSSocket) 역할을 하는 Proxy 객체를 반환하지만 HTTP/2 로직을 기반으로 getter, setter 및 메서드를 적용합니다.

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 코드로 오류를 throw합니다. 자세한 내용은 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가 문자열인 경우 두 번째 매개변수는 바이트 스트림으로 인코딩하는 방법을 지정합니다. 기본적으로 encoding은 'utf8'입니다. callback은 이 데이터 청크가 플러시될 때 호출됩니다.

이는 원시 HTTP 본문이며, 사용될 수 있는 상위 수준의 다중 부분 본문 인코딩과는 아무런 관련이 없습니다.

response.write()가 처음 호출될 때, 버퍼링된 헤더 정보와 본문의 첫 번째 청크를 클라이언트로 전송합니다. response.write()가 두 번째로 호출될 때, 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	writeHead()에서 this를 반환하여 end()와의 체이닝을 허용합니다.
v8.4.0	추가됨: v8.4.0

• statusCode <number>
• statusMessage <string>
• headers <Object> | <Array>
• 반환값: <http2.Http2ServerResponse>

요청에 대한 응답 헤더를 전송합니다. 상태 코드는 404와 같은 3자리 HTTP 상태 코드입니다. 마지막 인수인 headers는 응답 헤더입니다.

Http2ServerResponse에 대한 참조를 반환하므로 호출을 체이닝할 수 있습니다.

HTTP/1과의 호환성을 위해 사람이 읽을 수 있는 statusMessage를 두 번째 인수로 전달할 수 있습니다. 그러나 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()가 호출되기 전에 메시지에서 최대 한 번 호출될 수 있습니다.

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가 throw됩니다.

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') {
    // Entry에는 Http2Session에 대한 통계가 포함되어 있습니다.
  } else if (entry.name === 'Http2Stream') {
    // Entry에는 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') {
    // Entry에는 Http2Session에 대한 통계가 포함되어 있습니다.
  } else if (entry.name === 'Http2Stream') {
    // Entry에는 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를 직접 사용하는 경우)는 대체 동작을 직접 구현해야 합니다.