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 协议功能支持设计的底层接口。它特别不是为与现有的 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 是一个双工流
  stream.respond({
    'content-type': 'text/html; charset=utf-8',
    ':status': 200,
  });
  stream.end('<h1>Hello World</h1>');
});

server.listen(8443);

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 是一个双工流
  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();

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

• 继承：EventEmitter

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

每个 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' 事件。其监听器不接受任何参数。

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

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

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

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

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

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

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

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

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

session.settings({ enablePush: false });

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

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

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

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

当创建新的 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);

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 对应，网络错误也会销毁每个单独的流，并且必须在流级别处理，如上所示。

在使用 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 帧，而不 关闭 Http2Session。

• 类型：HTTP/2 Settings Object

一个无原型的对象，描述此 Http2Session 的当前本地设置。本地设置是 此 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 Settings Object

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

http2session.setLocalWindowSize(windowSize): void

设置本地端点的连接级窗口大小。 windowSize 是要设置的总窗口大小，而非增量值。

增大窗口会立即生效，但减小窗口只有在对等方已获知的窗口被消耗后才会生效，因为已公布的窗口无法撤回。若要从连接开始就使用小于默认值的窗口，请在创建服务器或客户端会话时设置 connectionWindowSize 选项。

import { createServer } from 'node:http2';

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

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

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

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

• 类型：net.Socket | tls.TLSSocket

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

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

destroy、setTimeout、ref 和 unref 方法将在此 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

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

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

新设置直到收到 SETTINGS 确认并发出 'localSettings' 事件后才生效。在确认仍处于等待状态时，可以发送多个 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);
});

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

const server = http2.createServer();
server.on('session', (session) => {
  // 为源 https://example.org:80 设置 altsvc
  session.altsvc('h2=":8000"', 'https://example.org:80');
});

server.on('stream', (stream) => {
  // 为特定流设置 altsvc
  stream.session.altsvc('h2=":8000"', stream.id);
});

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

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

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

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

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

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

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

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

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

serverhttp2session.origin(...origins): void

向连接的客户端提交 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');
});

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 选项：

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

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

• 继承：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);
});

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 帧时，就会发出 '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]);
});

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

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

当首次创建 ClientHttp2Session 时，套接字可能尚未连接。如果在此期间调用 clienthttp2session.request()，实际请求将推迟到套接字准备就绪为止。

如果会话在请求创建之前变得不可用，返回的流将异步发出 ERR_HTTP2_GOAWAY_SESSION 或 ERR_HTTP2_INVALID_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', () => { /* .. */ });
});

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

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

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

当设置 options.waitForTrailers 时，Http2Stream 在传输最终 DATA 帧时不会自动关闭。用户代码必须调用 http2stream.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 实例都会被销毁：

• 双方发送 END_STREAM（一次干净交换）。
• 对端发送 RST_STREAM 帧。
• 本地调用 http2stream.close()、http2stream.destroy() 或 http2session.destroy()。

对于干净交换和干净取消，销毁会延迟到所有待处理的 'end' 和 'finish' 事件触发之后。销毁时，如果尚未发送，会尝试向已连接的对端发送 RST_STREAM 帧。

销毁时总会发出 'close'。如果各自的一半在销毁前已完成，则会触发 'end' 和 'finish'。当销毁携带错误时会触发 'error'——要么通过 http2stream.destroy(err)，要么在对端在发送 END_STREAM 之前重置了流。

在 Http2Stream 被销毁后，http2stream.destroyed 属性将为 true，http2stream.rstCode 属性将指定 RST_STREAM 错误代码。Http2Stream 实例一旦销毁就不再可用。

稳定性：0 - 已弃用。请改用 'close' 和 'error'，再加上 stream.destroyed。

当 Http2Stream 在可写侧通过 .end() 结束之前关闭时，会发出此事件（或通过 respond({ endStream: true }) 自动结束）。监听器不接收任何参数。

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

关闭流时使用的 HTTP/2 错误代码可以通过 http2stream.rstCode 属性获取。

当处理 Http2Stream 时发生错误，会发出此事件。这包括在可读侧尚未完全传递时到达的对端发起重置：干净的重置代码（NGHTTP2_NO_ERROR 或 NGHTTP2_CANCEL）会表现为 ERR_HTTP2_STREAM_ABORTED，其他任何代码则表现为 ERR_HTTP2_STREAM_ERROR。

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

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

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

当收到与尾随头字段相关联的一组标头时，会发出 'trailers' 事件。监听器回调会接收 [HTTP/2 Headers Object][]、与标头关联的标志，以及原始格式的标头（参见 [HTTP/2 Raw Headers][]）。

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

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

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

• 类型：boolean

稳定性：0 - 已弃用

如果 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 的可读端将关闭。

• 类型：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 Headers Object

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

• 类型：Object[]

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

• 类型：HTTP/2 Headers Object

包含为此 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));

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 当前状态的各种信息。

• 类型：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

向连接的 HTTP/2 对等方发送尾随头帧。此方法将导致 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');
});

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' 等）。

• 继承 Http2Stream

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

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

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

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

当收到服务器推送流的响应头时，会触发 'push' 事件。监听器回调会接收 [HTTP/2 头对象][]、与这些头部相关联的标志，以及原始格式的头部（请参见 [HTTP/2 原始头][]）。

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

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

如果在响应到达时没有附加 'response' 监听器，响应体将会被完全丢弃（流会在不发出提示的情况下继续恢复）。但是，如果添加了 'response' 监听器，则必须消费来自响应对象的数据——可以在每次发生 'readable' 事件时调用 response.read()，也可以添加 'data' 处理器，或者调用 .resume() 方法。在数据被消费之前，'end' 事件不会触发。另外，在数据被读取之前，它会占用内存，最终可能导致“进程内存不足”错误。

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

• 继承：Http2Stream

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

http2stream.additionalHeaders(headers): void

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

• 类型：boolean

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

• 类型：boolean

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

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

发起一个推送流。回调被调用时，为推送流创建的新 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');
});

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

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

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

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

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

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

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

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

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