HTTP/2

稳定性：2 - 稳定

node:http2 模块提供了 HTTP/2 协议的实现。 可以通过以下方式访问：

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

Node.js 可能在构建时未包含对 node:crypto 模块的支持。在这种情况下，尝试从 node:http2 import 或调用 require('node:http2') 将导致抛出错误。

使用 CommonJS 时，可以使用 try/catch 捕获抛出的错误：

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

使用词法 ESM import 关键字时，只有在尝试加载模块之前（例如，使用预加载模块）注册了 process.on('uncaughtException') 的处理程序，才能捕获错误。

使用 ESM 时，如果代码可能在未启用 crypto 支持的 Node.js 构建上运行，请考虑使用 import() 函数而不是词法 import 关键字：

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

核心 API 提供了一个专门围绕 HTTP/2 协议功能支持设计的底层接口。它 specifically not 设计用于与现有的 HTTP/1 模块 API 兼容。但是，兼容性 API 是设计的。

http2 核心 API 在客户端和服务器之间比 http API 更加对称。例如，大多数事件，如 'error'、'connect' 和 'stream'，既可以由客户端代码发出，也可以由服务器端代码发出。

以下说明了使用核心 API 的简单 HTTP/2 服务器。由于没有已知支持 [未加密 HTTP/2][HTTP/2 Unencrypted] 的浏览器，因此在与浏览器客户端通信时必须使用 http2.createSecureServer()。

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

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

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

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

server.listen(8443);

要为此示例生成证书和密钥，请运行：

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

以下说明了 HTTP/2 客户端：

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

• 继承：{EventEmitter}

http2.Http2Session 类的实例表示 HTTP/2 客户端和服务器之间的活动通信会话。此类的实例 not 旨在由用户代码直接构造。

每个 Http2Session 实例将根据其是作为服务器还是客户端运行而表现出略微不同的行为。http2session.type 属性可用于确定 Http2Session 运行的模式。在服务器端，用户代码很少有机会直接使用 Http2Session 对象，大多数操作通常通过与 Http2Server 或 Http2Stream 对象的交互进行。

用户代码不会直接创建 Http2Session 实例。服务器端 Http2Session 实例由 Http2Server 实例在收到新的 HTTP/2 连接时创建。客户端 Http2Session 实例使用 http2.connect() 方法创建。

每个 Http2Session 实例在创建时都恰好关联一个 net.Socket 或 tls.TLSSocket。当 Socket 或 Http2Session 被销毁时，两者都将被销毁。

由于 HTTP/2 协议施加的特定序列化和处理要求，不建议用户代码从绑定到 Http2Session 的 Socket 实例读取数据或向其写入数据。这样做可能会使 HTTP/2 会话进入不确定状态，导致会话和套接字无法使用。

一旦 Socket 绑定到 Http2Session，用户代码应仅依赖 Http2Session 的 API。

一旦 Http2Session 被销毁，就会发出 'close' 事件。其监听器不接受任何参数。

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

一旦 Http2Session 成功连接到远程对等方并且可以开始通信，就会发出 'connect' 事件。

用户代码通常不会直接监听此事件。

当处理 Http2Session 期间发生错误时，会发出 'error' 事件。

当尝试在会话上发送帧时发生错误，会发出 'frameError' 事件。如果无法发送的帧与特定的 Http2Stream 关联，则会尝试在 Http2Stream 上发出 'frameError' 事件。

如果 'frameError' 事件与流关联，则流将在 'frameError' 事件之后立即关闭并销毁。如果事件不与流关联，则 Http2Session 将在 'frameError' 事件之后立即关闭。

当收到 GOAWAY 帧时，会发出 'goaway' 事件。

当发出 'goaway' 事件时，Http2Session 实例将自动关闭。

• settings {HTTP/2 设置对象} 收到的 SETTINGS 帧的副本。

当收到确认 SETTINGS 帧时，会发出 'localSettings' 事件。

当使用 http2session.settings() 提交新设置时，修改后的设置直到发出 'localSettings' 事件后才生效。

session.settings({ enablePush: false });

session.on('localSettings', (settings) => {
  /* 使用新设置 */
});

• payload {Buffer} PING 帧 8 字节负载

每当从连接的对等方收到 PING 帧时，就会发出 'ping' 事件。

• settings {HTTP/2 设置对象} 收到的 SETTINGS 帧的副本。

当从连接的对等方收到新的 SETTINGS 帧时，会发出 'remoteSettings' 事件。

session.on('remoteSettings', (settings) => {
  /* 使用新设置 */
});

• stream {Http2Stream} 流的引用
• headers {HTTP/2 头对象} 描述头的对象
• flags <number> 关联的数字标志
• rawHeaders {HTTP/2 原始头} 包含原始头的数组

当创建新的 Http2Stream 时，会发出 'stream' 事件。

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' 事件注册处理程序，如下例所示：

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

即使 HTTP/2 流和网络套接字不是 1:1 对应，网络错误也会销毁每个单独的流，并且必须在流级别处理，如上所示。

在使用 http2session.setTimeout() 方法为此 Http2Session 设置超时周期后，如果在配置的毫秒数后 Http2Session 上没有活动，则会发出 'timeout' 事件。其监听器不接受任何参数。

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

• 类型：<string> | <undefined>

如果 Http2Session 尚未连接到套接字，值将为 undefined，如果 Http2Session 未连接到 TLSSocket，则为 h2c，否则将返回连接的 TLSSocket 自身的 alpnProtocol 属性的值。

http2session.close(callback?): void

优雅地关闭 Http2Session，允许任何现有流自行完成，并防止创建新的 Http2Stream 实例。一旦关闭，如果没有打开的 Http2Stream 实例，可能 会调用 http2session.destroy()。

如果指定，callback 函数将注册为 'close' 事件的处理程序。

• 类型：<boolean>

如果此 Http2Session 实例已关闭，则为 true，否则为 false。

• 类型：<boolean>

如果此 Http2Session 实例仍在连接中，则为 true，将在发出 connect 事件和/或调用 http2.connect 回调之前设置为 false。

http2session.destroy(error?, code?): void

立即终止 Http2Session 和关联的 net.Socket 或 tls.TLSSocket。

一旦销毁，Http2Session 将发出 'close' 事件。如果 error 不为 undefined，则会在 'close' 事件之前立即发出 'error' 事件。

如果有任何与 Http2Session 关联的剩余打开的 Http2Streams，它们也将被销毁。

• 类型：<boolean>

如果此 Http2Session 实例已被销毁且不再可使用，则为 true，否则为 false。

• 类型：<boolean> | <undefined>

如果 Http2Session 会话套接字尚未连接，则值为 undefined，如果 Http2Session 与 TLSSocket 连接，则为 true，如果 Http2Session 连接到任何其他类型的套接字或流，则为 false。

http2session.goaway(code?, lastStreamID?, opaqueData?): void

向连接的对等方传输 GOAWAY 帧，without 关闭 Http2Session。

• 类型：{HTTP/2 设置对象}

一个无原型的对象，描述此 Http2Session 的当前本地设置。本地设置是 this Http2Session 实例本地的。

• 类型：<string[]> | <undefined>

如果 Http2Session 连接到 TLSSocket，originSet 属性将返回一个 Array，包含 Http2Session 可被视为权威的源。

originSet 属性仅在使用安全 TLS 连接时可用。

• 类型：<boolean>

指示 Http2Session 当前是否正在等待发送的 SETTINGS 帧的确认。在调用 http2session.settings() 方法后将为 true。一旦所有发送的 SETTINGS 帧都被确认，将为 false。

http2session.ping(payload?, callback): void

向连接的 HTTP/2 对等方发送 PING 帧。必须提供 callback 函数。如果发送了 PING，该方法将返回 true，否则返回 false。

未完成的（未确认的）ping 的最大数量由 maxOutstandingPings 配置选项确定。默认最大值为 10。

如果提供，payload 必须是包含 8 字节数据的 Buffer、TypedArray 或 DataView，这些数据将随 PING 传输并在 ping 确认时返回。

回调将被调用三个参数：一个错误参数，如果 PING 成功确认则为 null，一个 duration 参数，报告从发送 ping 到收到确认经过的毫秒数，以及一个包含 8 字节 PING 负载的 Buffer。

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

如果未指定 payload 参数，默认负载将是标记 PING 持续时间开始的 64 位时间戳（小端序）。

http2session.ref(): void

在此 Http2Session 实例的底层 net.Socket 上调用 ref()。

• 类型：{HTTP/2 设置对象}

一个无原型的对象，描述此 Http2Session 的当前远程设置。远程设置由 connected HTTP/2 对等方设置。

http2session.setLocalWindowSize(windowSize): void

设置本地端点的窗口大小。 windowSize 是要设置的总窗口大小，而不是增量。

import { createServer } from 'node:http2';

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

  // 设置本地窗口大小为 2 ** 20
  session.setLocalWindowSize(expectedWindowSize);
});

对于 http2 客户端，正确的事件是 'connect' 或 'remoteSettings'。

http2session.setTimeout(msecs, callback): void

用于设置一个回调函数，当 Http2Session 在 msecs 毫秒后没有活动时调用该函数。给定的 callback 注册为 'timeout' 事件的监听器。

• 类型：<net.Socket> | <tls.TLSSocket>

返回一个 Proxy 对象，充当 net.Socket（或 tls.TLSSocket），但将可用方法限制为与 HTTP/2 一起使用安全的方法。

destroy、emit、end、pause、read、resume 和 write 将抛出代码为 ERR_HTTP2_NO_SOCKET_MANIPULATION 的错误。有关更多信息，请参阅 [Http2Session 和套接字][]。

setTimeout 方法将在此 Http2Session 上调用。

所有其他交互将直接路由到套接字。

提供有关 Http2Session 当前状态的各种信息。

• 类型：<Object>
  Attributes

  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?): void

• settings {HTTP/2 设置对象}
• callback <Function> 会话连接后或如果会话已连接则立即调用的回调。
  Attributes

  err:<Error> | <null>

  settings:

  {HTTP/2 设置对象} 更新的  settings 对象。

  duration:<integer>

更新此 Http2Session 的当前本地设置，并向连接的 HTTP/2 对等方发送新的 SETTINGS 帧。

一旦调用，当会话等待远程对等方确认新设置时，http2session.pendingSettingsAck 属性将为 true。

新设置直到收到 SETTINGS 确认并发出 'localSettings' 事件后才生效。在确认仍在 pending 时，可以发送多个 SETTINGS 帧。

• 类型：<number>

如果此 Http2Session 实例是服务器，则 http2session.type 将等于 http2.constants.NGHTTP2_SESSION_SERVER，如果实例是客户端，则为 http2.constants.NGHTTP2_SESSION_CLIENT。

http2session.unref(): void

在此 Http2Session 实例的底层 net.Socket 上调用 unref()。

• 继承：{Http2Session}

serverhttp2session.altsvc(alt, originOrStream): void

向连接的客户端提交 ALTSVC 帧（由 RFC 7838 定义）。

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

发送带有特定流 ID 的 ALTSVC 帧表示替代服务与给定 Http2Stream 的源关联。

alt 和源字符串 must 仅包含 ASCII 字节，并严格解释为 ASCII 字节序列。特殊值 'clear' 可用于清除先前为给定域设置的任何替代服务。

当为 originOrStream 参数传递字符串时，它将被解析为 URL 并派生源。例如，HTTP URL 'https://example.org/foo/bar' 的源是 ASCII 字符串 'https://example.org'。如果给定字符串无法解析为 URL 或无法派生有效源，将抛出错误。

URL 对象或任何具有 origin 属性的对象都可以作为 originOrStream 传递，在这种情况下，将使用 origin 属性的值。origin 属性的值 must 是正确序列化的 ASCII 源。

alt 参数的格式由 RFC 7838 严格定义为 ASCII 字符串，包含与特定主机和端口关联的“替代”协议的逗号分隔列表。

例如，值 'h2="example.org:81"' 表示 HTTP/2 协议在主机 'example.org' 的 TCP/IP 端口 81 上可用。主机和端口 must 包含在引号（"）字符内。

可以指定多个替代方案，例如：'h2="example.org:81", h2=":82"'。

协议标识符（示例中的 'h2'）可以是任何有效的 ALPN 协议 ID。

Node.js 实现不验证这些值的语法，并按用户提供的或从对等方接收的原样传递。

serverhttp2session.origin(...origins): void

• origins { string | URL | Object } 一个或多个作为单独参数传递的 URL 字符串。

向连接的客户端提交 ORIGIN 帧（由 RFC 8336 定义），以宣传服务器能够提供权威响应的源集。

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

当字符串作为 origin 传递时，它将被解析为 URL 并派生源。例如，HTTP URL 'https://example.org/foo/bar' 的源是 ASCII 字符串 'https://example.org'。如果给定字符串无法解析为 URL 或无法派生有效源，将抛出错误。

URL 对象或任何具有 origin 属性的对象都可以作为 origin 传递，在这种情况下，将使用 origin 属性的值。origin 属性的值 must 是正确序列化的 ASCII 源。

或者，在使用 http2.createSecureServer() 方法创建新的 HTTP/2 服务器时，可以使用 origins 选项：

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

• 继承：{Http2Session}

每当客户端收到 ALTSVC 帧时，就会发出 'altsvc' 事件。事件发出时带有 ALTSVC 值、源和流 ID。如果 ALTSVC 帧中未提供 origin，origin 将为空字符串。

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

每当客户端收到 ORIGIN 帧时，就会发出 'origin' 事件。事件发出时带有 origin 字符串数组。http2session.originSet 将更新为包括收到的源。

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

'origin' 事件仅在使用安全 TLS 连接时发出。

clienthttp2session.request(headers, options?): void

• headers {HTTP/2 头对象|HTTP/2 原始头}

• options <Object>

  Attributes

  endStream:<boolean>

  如果  Http2Stream writable 端应最初关闭，则为 true ，例如发送不应期望负载主体的 GET 请求时。

  exclusive:<boolean>

  当为  true 且 parent 标识父流时，创建的流成为父流的唯一直接依赖项，所有其他现有依赖项成为新创建流的依赖项。 默认： false 。

  parent:<number>

  指定新创建的流所依赖的流的数字标识符。

  waitForTrailers:<boolean>

  当为  true 时， Http2Stream 将在发送最终 DATA 帧后发出 'wantTrailers' 事件。

  signal:<AbortSignal>

  可用于中止正在进行的请求的 AbortSignal。

• 返回：{ClientHttp2Stream}

仅对于 HTTP/2 客户端 Http2Session 实例，http2session.request() 创建并返回一个 Http2Stream 实例，可用于向连接的服务器发送 HTTP/2 请求。

当首次创建 ClientHttp2Session 时，套接字可能尚未连接。如果在此期间调用 clienthttp2session.request()，实际请求将推迟到套接字准备就绪。如果在实际请求执行之前 session 关闭，将抛出 ERR_HTTP2_GOAWAY_SESSION。

此方法仅在 http2session.type 等于 http2.constants.NGHTTP2_SESSION_CLIENT 时可用。

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

当设置 options.waitForTrailers 选项时，'wantTrailers' 事件在排队要发送的最后一块负载数据后立即发出。然后可以调用 http2stream.sendTrailers() 方法向对等方发送尾随头。

当设置 options.waitForTrailers 时，Http2Stream 在传输最终 DATA 帧时不会自动关闭。用户代码必须调用 http2stream.sendTrailers() 或 http2stream.close() 来关闭 Http2Stream。

当 options.signal 设置为 AbortSignal 然后在相应的 AbortController 上调用 abort 时，请求将发出带有 AbortError 错误的 'error' 事件。

:method 和 :path 伪头未在 headers 中指定，它们分别默认为：

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

• 继承：<stream.Duplex>

Http2Stream 类的每个实例表示 Http2Session 实例上的双向 HTTP/2 通信流。任何单个 Http2Session 在其生命周期内最多可以有 2³¹-1 个 Http2Stream 实例。

用户代码不会直接构造 Http2Stream 实例。相反，这些实例是通过 Http2Session 实例创建、管理并提供给用户代码的。在服务器上，Http2Stream 实例是响应传入的 HTTP 请求（并通过 'stream' 事件交给用户代码）创建的，或者响应调用 http2stream.pushStream() 方法创建的。在客户端，当调用 http2session.request() 方法时，或响应传入的 'push' 事件时，创建并返回 Http2Stream 实例。

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

在服务器端，ServerHttp2Stream 的实例在以下情况下创建：

• 收到带有以前未使用的流 ID 的新 HTTP/2 HEADERS 帧；
• 调用 http2stream.pushStream() 方法。

在客户端，当调用 http2session.request() 方法时，创建 ClientHttp2Stream 的实例。

在客户端，如果父 Http2Session 尚未完全建立，http2session.request() 返回的 Http2Stream 实例可能无法立即使用。在这种情况下，在 Http2Stream 上调用的操作将被缓冲，直到发出 'ready' 事件。用户代码应该很少（如果有）需要直接处理 'ready' 事件。Http2Stream 的就绪状态可以通过检查 http2stream.id 的值来确定。如果值为 undefined，则流尚未准备好使用。

所有 Http2Stream 实例在以下情况下被销毁：

• 连接的对等方收到流的 RST_STREAM 帧，并且（仅对于客户端流）已读取 pending 数据。
• 调用 http2stream.close() 方法，并且（仅对于客户端流）已读取 pending 数据。
• 调用 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 实例一旦销毁就不再可用。

每当 Http2Stream 实例在通信中途异常中止时，就会发出 'aborted' 事件。其监听器不接受任何参数。

仅当 Http2Stream writable 端尚未结束时，才会发出 'aborted' 事件。

当 Http2Stream 被销毁时，会发出 'close' 事件。一旦发出此事件，Http2Stream 实例就不再可用。

可以使用 http2stream.rstCode 属性检索关闭流时使用的 HTTP/2 错误代码。如果代码是除 NGHTTP2_NO_ERROR (0) 之外的任何值，则也将发出 'error' 事件。

当处理 Http2Stream 期间发生错误时，会发出 'error' 事件。

当尝试发送帧时发生错误，会发出 'frameError' 事件。调用时，处理函数将接收一个标识帧类型的整数参数，和一个标识错误代码的整数参数。Http2Stream 实例将在 'frameError' 事件发出后立即销毁。

当 Http2Stream 已打开，已分配 id，并且可以使用时，会发出 'ready' 事件。监听器不接受任何参数。

当使用 http2stream.setTimeout() 设置的毫秒数内此 Http2Stream 未收到活动时，会发出 'timeout' 事件。其监听器不接受任何参数。

• headers {HTTP/2 头对象} 描述头的对象
• flags <number> 关联的数字标志

当收到与尾随头字段关联的头块时，会发出 'trailers' 事件。监听器回调被传递 [HTTP/2 头对象][] 和与头关联的标志。

如果在收到尾随头之前调用 http2stream.end() 且未读取或监听传入数据，则可能不会发出此事件。

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

当 Http2Stream 已排队要在帧上发送的最终 DATA 帧并且 Http2Stream 准备好发送尾随头时，会发出 'wantTrailers' 事件。发起请求或响应时，必须设置 waitForTrailers 选项才能发出此事件。

• 类型：<boolean>

如果 Http2Stream 实例异常中止，则设置为 true。设置时，将已发出 'aborted' 事件。

• 类型：<number>

此属性显示当前缓冲要写入的字符数。有关详细信息，请参阅 net.Socket.bufferSize。

http2stream.close(code, callback?): void

通过向连接的 HTTP/2 对等方发送 RST_STREAM 帧来关闭 Http2Stream 实例。

• 类型：<boolean>

如果 Http2Stream 实例已关闭，则设置为 true。

• 类型：<boolean>

如果 Http2Stream 实例已被销毁且不再可用，则设置为 true。

• 类型：<boolean>

如果在收到的请求或响应 HEADERS 帧中设置了 END_STREAM 标志，则设置为 true，表示不应接收额外数据，并且 Http2Stream 的 readable 端将关闭。

• 类型：<number> | <undefined>

此 Http2Stream 实例的数字流标识符。如果尚未分配流标识符，则设置为 undefined。

• 类型：<boolean>

如果 Http2Stream 实例尚未分配数字流标识符，则设置为 true。

http2stream.priority(options): void

稳定性：0 - 已弃用：RFC 9113 中已弃用对优先级信令的支持，Node.js 中不再支持。

空方法，仅用于保持一些向后兼容性。

• 类型：<number>

设置为在从连接的对等方收到 RST_STREAM 帧、调用 http2stream.close() 或 http2stream.destroy() 后销毁 Http2Stream 时报告的 RST_STREAM 错误代码。如果 Http2Stream 尚未关闭，则为 undefined。

• 类型：{HTTP/2 头对象}

包含为此 Http2Stream 发送的出站头的对象。

• 类型：{HTTP/2 头对象[]}

包含为此 Http2Stream 发送的出站信息（额外）头的对象数组。

• 类型：{HTTP/2 头对象}

包含为此 HttpStream 发送的出站尾随头的对象。

• 类型：{Http2Session}

对拥有此 Http2Stream 的 Http2Session 实例的引用。Http2Stream 实例销毁后，值将为 undefined。

http2stream.setTimeout(msecs, callback): void

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

提供有关 Http2Stream 当前状态的各种信息。

• 类型：<Object>
  Attributes

  localWindowSize:<number>

  连接的对等方可以为此  Http2Stream 发送的字节数，而无需接收 WINDOW_UPDATE 。

  state:<number>

  由  nghttp2 确定的 Http2Stream 的底层当前状态的标志。

  localClose:<number>

  如果此  Http2Stream 已在本地关闭，则为 1 。

  remoteClose:<number>

  如果此  Http2Stream 已在远程关闭，则为 1 。

  sumDependencyWeight:<number>

  遗留属性，始终设置为  0 。

  weight:<number>

  遗留属性，始终设置为  16 。

此 Http2Stream 的当前状态。

http2stream.sendTrailers(headers): void

• headers {HTTP/2 头对象}

向连接的 HTTP/2 对等方发送尾随 HEADERS 帧。此方法将导致 Http2Stream 立即关闭，并且必须仅在发出 'wantTrailers' 事件后调用。发送请求或发送响应时，必须设置 options.waitForTrailers 选项，以便在最终 DATA 帧后保持 Http2Stream 打开，以便可以发送尾随头。

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

HTTP/1 规范禁止尾随头包含 HTTP/2 伪头字段（例如 ':method'、':path' 等）。

• 继承 {Http2Stream}

ClientHttp2Stream 类是 Http2Stream 的扩展，仅在 HTTP/2 客户端上使用。客户端上的 Http2Stream 实例提供仅在客户端上相关的事件，如 'response' 和 'push'。

当服务器发送 100 Continue 状态时发出，通常是因为请求包含 Expect: 100-continue。这是客户端应发送请求主体的指令。

• headers {HTTP/2 头对象}
• flags <number>
• rawHeaders {HTTP/2 原始头}

当收到流的额外头块时，会发出 'headers' 事件，例如收到 1xx 信息头块时。监听器回调被传递 [HTTP/2 头对象][]、与头关联的标志以及原始格式的头（请参阅 [HTTP/2 原始头][]）。

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

• headers {HTTP/2 头对象}
• flags <number>

当收到服务器推送流的响应头时，会发出 'push' 事件。监听器回调被传递 [HTTP/2 头对象][] 和与头关联的标志。

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

• headers {HTTP/2 头对象}
• flags <number>
• rawHeaders {HTTP/2 原始头}

当从连接的 HTTP/2 服务器收到此流的响应 HEADERS 帧时，会发出 'response' 事件。监听器被调用三个参数：一个包含收到的 [HTTP/2 头对象][] 的 Object、与头关联的标志以及原始格式的头（请参阅 [HTTP/2 原始头][]）。

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

• 继承：{Http2Stream}

ServerHttp2Stream 类是 Http2Stream 的扩展， 仅用于 HTTP/2 服务器。服务器上的 Http2Stream 实例 提供额外的方法，例如 http2stream.pushStream() 和 http2stream.respond()，这些方法仅与服务器相关。

http2stream.additionalHeaders(headers): void

• headers {HTTP/2 头对象}

向连接的 HTTP/2 对等方发送一个额外的信息性 HEADERS 帧。

• 类型：<boolean>

如果头已发送则为 true，否则为 false（只读）。

• 类型：<boolean>

只读属性，映射到远程客户端最近一个 SETTINGS 帧的 SETTINGS_ENABLE_PUSH 标志。 如果远程对等方接受推送流，则为 true，否则为 false。 同一 Http2Session 中的每个 Http2Stream 的设置都相同。

http2stream.pushStream(headers, options?, callback): void

• headers {HTTP/2 头对象}
• options <Object>
  Attributes

  exclusive:<boolean>

  当为  true 且 parent 标识父流时， 创建的流将成为父流的唯一直接依赖项， 所有其他现有依赖项将成为新创建流的依赖项。 默认值： false 。

  parent:<number>

  指定新创建流所依赖的流的数字标识符。
• callback <Function> 一旦推送流被发起即调用的回调。
  Attributes

  err:<Error>

  pushStream:

  {ServerHttp2Stream} 返回的  pushStream 对象。

  headers:

  {HTTP/2 头对象}  pushStream 发起时使用的头对象。

发起一个推送流。回调被调用时，为推送流创建的新 Http2Stream 实例作为第二个参数传递，或者将 Error 作为第一个参数传递。

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

在 HEADERS 帧中不允许设置推送流的权重。 将 weight 值传递给 http2stream.priority 并将 silent 选项设置为 true，以启用并发流之间的服务器端带宽平衡。

不允许在推送流内部调用 http2stream.pushStream()， 否则会抛出错误。

http2stream.respond(headers?, options?): void

• headers {HTTP/2 头对象|HTTP/2 原始头}
• options <Object>
  Attributes

  endStream:<boolean>

  设置为  true 以指示响应将不包含 负载数据。

  waitForTrailers:<boolean>

  当为  true 时， Http2Stream 将在发送最后一个 DATA 帧后发出 'wantTrailers' 事件。

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

发起一个响应。当设置了 options.waitForTrailers 选项时， 'wantTrailers' 事件将在排队等待发送的最后一块负载数据后立即发出。 然后可以使用 http2stream.sendTrailers() 方法向对等方发送尾部头字段。

当设置了 options.waitForTrailers 时，Http2Stream 不会在传输最终 DATA 帧时自动关闭。用户代码必须调用 http2stream.sendTrailers() 或 http2stream.close() 来关闭 Http2Stream。

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

http2stream.respondWithFD(fd, headers?, options?): void

发起一个响应，其数据从给定的文件描述符中读取。不对给定的文件描述符执行 验证。如果尝试使用文件描述符读取数据时发生错误，Http2Stream 将 使用标准的 INTERNAL_ERROR 代码通过 RST_STREAM 帧关闭。

使用时，Http2Stream 对象的 Duplex 接口将自动关闭。

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

可以指定可选的 options.statCheck 函数，让用户代码有机会 根据给定 fd 的 fs.Stat 详细信息设置额外的内容头。如果提供了 statCheck 函数，http2stream.respondWithFD() 方法将执行 fs.fstat() 调用来收集提供的文件描述符的详细信息。

offset 和 length 选项可用于将响应限制为特定的范围子集。 例如，这可用于支持 HTTP Range 请求。

流关闭时不会关闭文件描述符或 FileHandle， 因此一旦不再需要，就需要手动关闭它。 不支持并发地对多个流使用相同的文件描述符， 这可能会导致数据丢失。支持在流完成后重用文件描述符。

当设置了 options.waitForTrailers 选项时，'wantTrailers' 事件 将在排队等待发送的最后一块负载数据后立即发出。 然后可以使用 http2stream.sendTrailers() 方法向对等方发送尾部 头字段。

当设置了 options.waitForTrailers 时，Http2Stream 不会在传输最终 DATA 帧时自动关闭。用户代码_必须_调用 http2stream.sendTrailers() 或 http2stream.close() 来关闭 Http2Stream。

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

http2stream.respondWithFile(path, headers?, options?): void

发送常规文件作为响应。path 必须指定一个常规文件， 否则将在 Http2Stream 对象上发出 'error' 事件。

使用时，Http2Stream 对象的 Duplex 接口将自动关闭。

可以指定可选的 options.statCheck 函数，让用户代码有机会 根据给定文件的 fs.Stat 详细信息设置额外的内容头：

如果尝试读取文件数据时发生错误，Http2Stream 将 使用标准的 INTERNAL_ERROR 代码通过 RST_STREAM 帧关闭。 如果定义了 onError 回调，则将调用它。否则 流将被销毁。

使用文件路径的示例：

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

options.statCheck 函数也可用于通过返回 false 来取消发送操作。 例如，条件请求可以检查 stat 结果以确定文件是否已被修改，从而返回适当的 304 响应：

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

content-length 头字段将自动设置。

offset 和 length 选项可用于将响应限制为特定的范围子集。 例如，这可用于支持 HTTP Range 请求。

options.onError 函数也可用于处理在开始交付文件之前可能发生的 所有错误。默认行为是销毁流。

当设置了 options.waitForTrailers 选项时，'wantTrailers' 事件 将在排队等待发送的最后一块负载数据后立即发出。 然后可以使用 http2stream.sendTrailers() 方法向对等方发送尾部 头字段。

当设置了 options.waitForTrailers 时，Http2Stream 不会在传输最终 DATA 帧时自动关闭。用户代码必须调用 http2stream.sendTrailers() 或 http2stream.close() 来关闭 Http2Stream。

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

• 继承：<net.Server>

Http2Server 的实例是使用 http2.createServer() 函数创建的。Http2Server 类不是由 node:http2 模块直接导出的。

如果注册了 'request' 监听器或 http2.createServer() 提供了回调函数，则每次收到带有 HTTP Expect: 100-continue 的请求时都会发出 'checkContinue' 事件。如果未监听此事件，服务器将自动响应状态 100 Continue（视情况而定）。

处理此事件涉及调用 response.writeContinue()（如果客户端 应继续发送请求体），或生成适当的 HTTP 响应（例如 400 Bad Request）（如果客户端不应继续发送 请求体）。

当发出并处理此事件时，'request' 事件将 不会发出。

当建立新的 TCP 流时发出此事件。socket 通常是 net.Socket 类型的对象。 通常用户不希望访问此事件。

用户也可以显式发出此事件以将连接注入 HTTP 服务器。在这种情况下，可以传递任何 Duplex 流。

每次有请求时发出。每个会话可能有多个请求。 请参阅 [兼容 API][]。

• session {ServerHttp2Session}

当 Http2Server 创建新的 Http2Session 时发出 'session' 事件。

当与 Http2Server 关联的 Http2Session 对象发出 'error' 事件时， 发出 'sessionError' 事件。

• stream {Http2Stream} 流的引用
• headers {HTTP/2 头对象} 描述头的对象
• flags <number> 关联的数字标志
• rawHeaders {HTTP/2 原始头} 包含原始头的数组

当与服务器关联的 Http2Session 发出 'stream' 事件时， 发出 'stream' 事件。

另请参阅 Http2Session 的 'stream' 事件。

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

当服务器在 http2server.setTimeout() 设置的给定毫秒数内没有活动时， 发出 'timeout' 事件。 默认值： 0（无超时）

server.close(callback?): void

停止服务器建立新会话。由于 HTTP/2 会话的持久性，这并不能防止创建新的请求流。要优雅地关闭服务器， 请在所有活动会话上调用 http2session.close()。

如果提供了 callback，则直到所有活动会话都已关闭才会调用它， 尽管服务器已经停止允许新会话。有关更多详细信息，请参阅 net.Server.close()。

server[Symbol.asyncDispose](): void

调用 server.close() 并返回一个 promise，当服务器 已关闭时该 promise 会兑现。

server.setTimeout(msecs?, callback?): void

用于设置 http2 服务器请求的超时值， 并设置一个回调函数，当 Http2Server 在 msecs 毫秒后没有活动时 调用该函数。

给定的回调注册为 'timeout' 事件的监听器。

如果 callback 不是函数，将抛出新的 ERR_INVALID_ARG_TYPE 错误。

• 类型：<number> 超时（毫秒）。默认值： 0（无超时）

在假定套接字超时之前的不活动毫秒数。

值为 0 将禁用传入连接的超时行为。

套接字超时逻辑是在连接时设置的，因此更改此 值仅影响服务器的新连接，不影响任何现有连接。

server.updateSettings(settings?): void

• settings {HTTP/2 设置对象}

用于使用提供的设置更新服务器。

对于无效的 settings 值抛出 ERR_HTTP2_INVALID_SETTING_VALUE。

对于无效的 settings 参数抛出 ERR_INVALID_ARG_TYPE。

• 继承：<tls.Server>

Http2SecureServer 的实例是使用 http2.createSecureServer() 函数创建的。Http2SecureServer 类不是 由 node:http2 模块直接导出的。

如果注册了 'request' 监听器或 http2.createSecureServer() 提供了回调函数，则每次收到带有 HTTP Expect: 100-continue 的请求时都会发出 'checkContinue' 事件。如果未监听此事件，服务器将自动响应状态 100 Continue（视情况而定）。

处理此事件涉及调用 response.writeContinue()（如果客户端 应继续发送请求体），或生成适当的 HTTP 响应（例如 400 Bad Request）（如果客户端不应继续发送 请求体）。

当发出并处理此事件时，'request' 事件将 不会发出。

当建立新的 TCP 流时发出此事件，在 TLS 握手开始之前。socket 通常是 net.Socket 类型的对象。 通常用户不希望访问此事件。

用户也可以显式发出此事件以将连接注入 HTTP 服务器。在这种情况下，可以传递任何 Duplex 流。

每次有请求时发出。每个会话可能有多个请求。 请参阅 [兼容 API][]。

• session {ServerHttp2Session}

当 Http2SecureServer 创建新的 Http2Session 时发出 'session' 事件。

当与 Http2SecureServer 关联的 Http2Session 对象发出 'error' 事件时， 发出 'sessionError' 事件。

• stream {Http2Stream} 流的引用
• headers {HTTP/2 头对象} 描述头的对象
• flags <number> 关联的数字标志
• rawHeaders {HTTP/2 原始头} 包含原始头的数组

当与服务器关联的 Http2Session 发出 'stream' 事件时， 发出 'stream' 事件。

另请参阅 Http2Session 的 'stream' 事件。

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

当服务器在 http2secureServer.setTimeout() 设置的给定毫秒数内没有活动时， 发出 'timeout' 事件。 默认值： 2 分钟。

当连接的客户端未能协商允许的协议（即 HTTP/2 或 HTTP/1.1）时， 发出 'unknownProtocol' 事件。事件处理程序 接收套接字进行处理。如果未为此事件注册监听器， 则连接终止。可以使用传递给 http2.createSecureServer() 的 'unknownProtocolTimeout' 选项指定超时。

在早期版本的 Node.js 中，如果 allowHTTP1 为 false 且在 TLS 握手期间客户端未发送 ALPN 扩展或发送的 ALPN 扩展不包含 HTTP/2 (h2)，则会发出此事件。 较新版本的 Node.js 仅当 allowHTTP1 为 false 且客户端 未发送 ALPN 扩展时才发出此事件。如果客户端发送的 ALPN 扩展 不包含 HTTP/2（如果 allowHTTP1 为 true 则也不包含 HTTP/1.1）， TLS 握手将失败，并且不会建立安全连接。

请参阅 [兼容 API][]。

server.close(callback?): void

停止服务器建立新会话。由于 HTTP/2 会话的持久性，这并不能防止创建新的请求流。要优雅地关闭服务器， 请在所有活动会话上调用 http2session.close()。

如果提供了 callback，则直到所有活动会话都已关闭才会调用它， 尽管服务器已经停止允许新会话。有关更多详细信息，请参阅 tls.Server.close()。

server.setTimeout(msecs?, callback?): void

用于设置 http2 安全服务器请求的超时值， 并设置一个回调函数，当 Http2SecureServer 在 msecs 毫秒后没有活动时 调用该函数。

给定的回调注册为 'timeout' 事件的监听器。

如果 callback 不是函数，将抛出新的 ERR_INVALID_ARG_TYPE 错误。

• 类型：<number> 超时（毫秒）。默认值： 0（无超时）

在假定套接字超时之前的不活动毫秒数。

值为 0 将禁用传入连接的超时行为。

套接字超时逻辑是在连接时设置的，因此更改此 值仅影响服务器的新连接，不影响任何现有连接。

server.updateSettings(settings?): void

• settings {HTTP/2 设置对象}

用于使用提供的设置更新服务器。

对于无效的 settings 值抛出 ERR_HTTP2_INVALID_SETTING_VALUE。

对于无效的 settings 参数抛出 ERR_INVALID_ARG_TYPE。

http2.createServer(options?, onRequestHandler?): void