Node.js v26.0.0 文档

HTTP/2#

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

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

确定加密支持是否不可用#

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

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

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

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

使用 ESM 时，如果代码有可能在未启用加密支持的 Node.js 版本上运行，请考虑使用 import() 函数，而不是词法 import 关键字。

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

核心 API#

核心 API 提供了一种专门围绕 HTTP/2 协议功能支持设计的底层接口。它专门不旨在与现有的 HTTP/1 模块 API 兼容。然而，兼容性 API 则提供了这种兼容性。

与 http API 相比，http2 核心 API 在客户端和服务端之间具有更强的对称性。例如，大多数事件（如 'error'、'connect' 和 'stream'）既可以由客户端代码触发，也可以由服务端代码触发。

服务端示例#

以下示例展示了使用核心 API 的简单 HTTP/2 服务器。由于目前没有任何已知浏览器支持 非加密 HTTP/2，因此在与浏览器客户端通信时，必须使用 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 is a Duplex
  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 is a Duplex
  stream.respond({
    'content-type': 'text/html; charset=utf-8',
    ':status': 200,
  });
  stream.end('<h1>Hello World</h1>');
});

server.listen(8443);
copy

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

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

客户端示例#

以下示例展示了一个 HTTP/2 客户端

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

const client = connect('https://: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://:8443', {
  ca: fs.readFileSync('localhost-cert.pem'),
});
client.on('error', (err) => console.error(err));

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

req.on('response', (headers, flags) => {
  for (const name in headers) {
    console.log(`${name}: ${headers[name]}`);
  }
});

req.setEncoding('utf8');
let data = '';
req.on('data', (chunk) => { data += chunk; });
req.on('end', () => {
  console.log(`\n${data}`);
  client.close();
});
req.end();
copy

类：Http2Session#

• 扩展自：<EventEmitter>

http2.Http2Session 类的实例表示 HTTP/2 客户端和服务端之间的活动通信会话。此类实例不建议直接由用户代码创建。

每个 Http2Session 实例的行为根据它是作为服务端还是客户端运行而略有不同。可以使用 http2session.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'#

当 Http2Session 被销毁后，会触发 'close' 事件。其监听器不需要任何参数。

事件：'connect'#

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

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

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

事件：'error'#

• error <Error>

当 Http2Session 处理过程中发生错误时，会触发 'error' 事件。

事件：'frameError'#

• type <integer> 帧类型。
• code <integer> 错误代码。
• id <integer> 流 ID（如果帧与流无关，则为 0）。

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

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

事件：'goaway'#

• errorCode <number> GOAWAY 帧中指定的 HTTP/2 错误代码。
• lastStreamID <number> 远程对等方成功处理的最后一个流的 ID（如果未指定 ID，则为 0）。
• opaqueData <Buffer> 如果 GOAWAY 帧中包含额外的不透明数据，将传入一个包含该数据的 Buffer 实例。

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

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

事件：'localSettings'#

• settings <HTTP/2 Settings Object> 收到的 SETTINGS 帧的副本。

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

当使用 http2session.settings() 提交新设置时，修改后的设置在 'localSettings' 事件触发前不会生效。

session.settings({ enablePush: false });

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

事件：'ping'#

• payload <Buffer> PING 帧的 8 字节有效负载

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

事件：'remoteSettings'#

• settings <HTTP/2 Settings Object> 收到的 SETTINGS 帧的副本。

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

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

事件：'stream'#

• stream <Http2Stream> 对流的引用
• headers <HTTP/2 Headers Object> 描述请求头的对象
• flags <number> 关联的数值标志
• rawHeaders {HTTP/2 Raw Headers} 包含原始头信息的数组

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

在服务端，用户代码通常不会直接监听此事件，而是注册一个监听器来处理由 http2.createServer() 和 http2.createSecureServer() 返回的 net.Server 或 tls.Server 实例触发的 'stream' 事件，如下例所示。

import { createServer } from 'node:http2';

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

// Create an unencrypted HTTP/2 server
const server = http2.createServer();

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

server.listen(8000);
copy

尽管 HTTP/2 流和网络套接字不是 1:1 的对应关系，但网络错误会销毁每个独立的流，因此必须在流级别进行处理，如上所示。

事件：'timeout'#

在使用 http2session.setTimeout() 方法设置此 Http2Session 的超时时间后，如果 Http2Session 在配置的毫秒数内没有活动，则会触发 'timeout' 事件。其监听器不需要任何参数。

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

http2session.alpnProtocol#

• 类型：<string> | <undefined>

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

http2session.close([callback])#

• callback <Function>

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

如果指定，callback 函数将作为 'close' 事件的监听器注册。

http2session.closed#

• 类型：<boolean>

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

http2session.connecting#

• 类型：<boolean>

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

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

• error <Error> 如果 Http2Session 因错误而被销毁，则传入一个 Error 对象。
• code <number> 在最终 GOAWAY 帧中发送的 HTTP/2 错误代码。如果未指定且 error 不为 undefined，则默认为 INTERNAL_ERROR，否则默认为 NO_ERROR。

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

销毁后，Http2Session 将触发 'close' 事件。如果 error 不为 undefined，则在 'close' 事件之前立即触发 'error' 事件。

如果 Http2Session 中仍有任何打开的 Http2Stream，它们也将被销毁。

http2session.destroyed#

• 类型：<boolean>

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

http2session.encrypted#

• 类型：<boolean> | <undefined>

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

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

• code <number> HTTP/2 错误代码
• lastStreamID <number> 最后一个处理的 Http2Stream 的数字 ID
• opaqueData <Buffer> | <TypedArray> | <DataView> 包含要随 GOAWAY 帧携带的额外数据的 TypedArray 或 DataView 实例。

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

http2session.localSettings#

• 类型：<HTTP/2 Settings Object>

一个描述此 Http2Session 当前本地设置的无原型对象。这些本地设置仅针对此 Http2Session 实例。

http2session.originSet#

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

如果 Http2Session 连接到 TLSSocket，originSet 属性将返回一个数组，其中包含此 Http2Session 可被视为权威源的所有源。

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

http2session.pendingSettingsAck#

• 类型：<boolean>

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

http2session.ping([payload, ]callback)#

• payload <Buffer> | <TypedArray> | <DataView> 可选的 ping 有效负载。
• callback <Function>
• 返回：<boolean>

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

待处理（未确认）ping 的最大数量由 maxOutstandingPings 配置选项决定。默认最大值为 10。

如果提供 payload，它必须是包含 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()}'`);
  }
});
copy

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

http2session.ref()#

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

http2session.remoteSettings#

• 类型：<HTTP/2 Settings Object>

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

http2session.setLocalWindowSize(windowSize)#

• windowSize <number>

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

import { createServer } from 'node:http2';

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

  // Set local window size to be 2 ** 20
  session.setLocalWindowSize(expectedWindowSize);
});
const http2 = require('node:http2');

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

  // Set local window size to be 2 ** 20
  session.setLocalWindowSize(expectedWindowSize);
});
copy

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

http2session.setTimeout(msecs, callback)#

• msecs <number>
• callback <Function>

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

http2session.socket#

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

返回一个充当 net.Socket（或 tls.TLSSocket）的 Proxy 对象，但限制了可用方法，仅允许安全用于 HTTP/2 的方法。

destroy、emit、end、pause、read、resume 和 write 将抛出代码为 ERR_HTTP2_NO_SOCKET_MANIPULATION 的错误。更多信息请参见 Http2Session 与套接字。

setTimeout 方法将在此 Http2Session 上调用。

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

http2session.state#

提供有关 Http2Session 当前状态的杂项信息。

• 类型：<Object>
• effectiveLocalWindowSize <number> 此 Http2Session 的当前本地（接收）流控制窗口大小。
• effectiveRecvDataLength <number> 自上次流控制 WINDOW_UPDATE 以来已接收的当前字节数。
• nextStreamID <number> 下次由该 Http2Session 创建新 Http2Stream 时使用的数字标识符。
• localWindowSize <number> 远程对等方在未收到 WINDOW_UPDATE 的情况下可以发送的字节数。
• lastProcStreamID <number> 最近接收到 HEADERS 或 DATA 帧的 Http2Stream 的数字 ID。
• remoteWindowSize <number> 此 Http2Session 在未收到 WINDOW_UPDATE 的情况下可以发送的字节数。
• outboundQueueSize <number> 此 Http2Session 出站队列中当前的帧数。
• deflateDynamicTableSize <number> 出站头压缩状态表的当前字节大小。
• inflateDynamicTableSize <number> 入站头压缩状态表的当前字节大小。

描述此 Http2Session 当前状态的对象。

http2session.settings([settings][, callback])#

• settings <HTTP/2 Settings Object>
• callback <Function> 在会话连接后或如果会话已连接则立即调用的回调。
  • err <Error> | <null>
  • settings <HTTP/2 Settings Object> 更新后的 settings 对象。
  • duration <integer>

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

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

新设置在收到 SETTINGS 确认并触发 'localSettings' 事件之前不会生效。可以在确认仍在等待时发送多个 SETTINGS 帧。

http2session.type#

• 类型：<number>

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

http2session.unref()#

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

类：ServerHttp2Session#

• 继承：<Http2Session>

serverhttp2session.altsvc(alt, originOrStream)#

• alt <string> RFC 7838 定义的替代服务配置描述。
• originOrStream <number> | <string> | <URL> | <Object> 指定源的 URL 字符串（或带有 origin 属性的 Object），或者是由 http2stream.id 属性给出的活动 Http2Stream 的数字标识符。

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

import { createServer } from 'node:http2';

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

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

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

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

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

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

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

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

指定替代服务#

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

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

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

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

Node.js 实现不对这些值的语法进行验证，而是按用户提供或从对等方接收的方式直接传递。

serverhttp2session.origin(...origins)#

• 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');
});
const http2 = require('node:http2');
const options = getSecureOptionsSomehow();
const server = http2.createSecureServer(options);
server.on('stream', (stream) => {
  stream.respond();
  stream.end('ok');
});
server.on('session', (session) => {
  session.origin('https://example.com', 'https://example.org');
});
copy

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

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

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

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

类：ClientHttp2Session#

• 继承：<Http2Session>

事件：'altsvc'#

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

每当客户端收到 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);
});
copy

事件：'origin'#

• origins <string[]>

每当客户端收到 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]);
});
copy

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

clienthttp2session.request(headers[, options])#

• headers <HTTP/2 Headers Object>

• options <Object>

  • endStream <boolean> 如果 Http2Stream 的可写端应最初关闭（例如发送不期望有效负载主体的 GET 请求时），则为 true。
  • 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://: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://:1234');
const {
  HTTP2_HEADER_PATH,
  HTTP2_HEADER_STATUS,
} = http2.constants;

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

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

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

当使用 AbortSignal 设置 options.signal 并在对应的 AbortController 上调用 abort 时，该请求将触发带有 AbortError 错误的 'error' 事件。

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

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

类：Http2Stream#

• 继承：<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 的可写端用于向已连接的对等方发送数据，而可读端用于接收已连接的对等方发送的数据。

Http2Stream 的默认文本字符编码为 UTF-8。使用 Http2Stream 发送文本时，请使用 'content-type' 请求头来设置字符编码。

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

Http2Stream 生命周期#

创建#

在服务端，ServerHttp2Stream 实例的创建方式如下：

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

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

在客户端，如果父 Http2Session 尚未完全建立，则 http2session.request() 返回的 Http2Stream 实例可能无法立即使用。在这种情况下，对 Http2Stream 的操作将被缓冲，直到触发 'ready' 事件。用户代码几乎不需要处理 'ready' 事件。可以通过检查 http2stream.id 的值来确定 Http2Stream 的就绪状态。如果该值为 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'#

每当 Http2Stream 实例在通信过程中异常中止时，都会触发 'aborted' 事件。其监听器不需要任何参数。

'aborted' 事件仅在 Http2Stream 的可写端尚未结束时触发。

事件: 'close'#

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

关闭流时使用的 HTTP/2 错误代码可以通过 http2stream.rstCode 属性检索。如果代码不是 NGHTTP2_NO_ERROR (0) 的任何其他值，则也会触发 'error' 事件。

事件: 'error'#

• error <Error>

当 Http2Stream 处理过程中发生错误时，会触发 'error' 事件。

事件：'frameError'#

• type <integer> 帧类型。
• code <integer> 错误代码。
• id <integer> 流 ID（如果帧与流无关，则为 0）。

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

事件：'ready'#

当 Http2Stream 已打开、已分配 id 并可以使用时，会触发 'ready' 事件。监听器不需要任何参数。

事件：'timeout'#

当在此 Http2Stream 上超过使用 http2stream.setTimeout() 设置的毫秒数未收到活动时，会触发 'timeout' 事件。其监听器不需要任何参数。

事件：'trailers'#

• headers <HTTP/2 Headers Object> 描述请求头的对象
• flags <number> 关联的数值标志

当收到与尾部请求头字段关联的一块请求头时，会触发 'trailers' 事件。监听器回调函数会接收到 HTTP/2 Headers 对象以及与这些请求头关联的标志。

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

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

事件：'wantTrailers'#

当 Http2Stream 已将最终 DATA 帧排队等待发送，并且 Http2Stream 准备好发送尾部请求头时，会触发 'wantTrailers' 事件。在发起请求或响应时，必须设置 waitForTrailers 选项才会触发此事件。

http2stream.aborted#

• 类型：<boolean>

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

http2stream.bufferSize#

• 类型：<number>

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

http2stream.close(code[, callback])#

• code <number> 标识错误代码的无符号 32 位整数。默认值： http2.constants.NGHTTP2_NO_ERROR (0x00)。
• callback <Function> 注册为监听 'close' 事件的可选函数。

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

http2stream.closed#

• 类型：<boolean>

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

http2stream.destroyed#

• 类型：<boolean>

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

http2stream.endAfterHeaders#

• 类型：<boolean>

如果收到的请求或响应 HEADERS 帧中设置了 END_STREAM 标志，则设置为 true，这表示不应再接收其他数据，且 Http2Stream 的可读端将关闭。

http2stream.id#

• 类型：<number> | <undefined>

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

http2stream.pending#

• 类型：<boolean>

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

http2stream.priority(options)#

空方法，仅为保持向后兼容性而存在。

http2stream.rstCode#

• 类型：<number>

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

http2stream.sentHeaders#

• 类型：<HTTP/2 Headers Object>

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

http2stream.sentInfoHeaders#

• 类型：<HTTP/2 Headers Object[]>

包含为此 Http2Stream 发送的出站信息性（附加）请求头的对象数组。

http2stream.sentTrailers#

• 类型：<HTTP/2 Headers Object>

包含为此 HttpStream 发送的出站尾部请求头的对象。

http2stream.session#

• 类型：<Http2Session>

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

http2stream.setTimeout(msecs, callback)#

• msecs <number>
• callback <Function>

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

// Cancel the stream if there's no activity after 5 seconds
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': '/' });

// Cancel the stream if there's no activity after 5 seconds
req.setTimeout(5000, () => req.close(NGHTTP2_CANCEL));
copy

http2stream.state#

提供有关 Http2Stream 当前状态的杂项信息。

• 类型：<Object>
• localWindowSize <number> 已连接的对等方在未收到 WINDOW_UPDATE 的情况下可以为该 Http2Stream 发送的字节数。
• state <number> 指示 nghttp2 所确定的 Http2Stream 底层当前状态的标志。
• localClose <number> 如果此 Http2Stream 已在本地关闭，则为 1。
• remoteClose <number> 如果此 Http2Stream 已在远程关闭，则为 1。
• sumDependencyWeight <number> 旧属性，始终设置为 0。
• weight <number> 旧属性，始终设置为 16。

此 Http2Stream 的当前状态。

http2stream.sendTrailers(headers)#

• headers <HTTP/2 Headers Object>

向已连接的 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');
});
const http2 = require('node:http2');
const server = http2.createServer();
server.on('stream', (stream) => {
  stream.respond(undefined, { waitForTrailers: true });
  stream.on('wantTrailers', () => {
    stream.sendTrailers({ xyz: 'abc' });
  });
  stream.end('Hello World');
});
copy

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

类：ClientHttp2Stream#

• 继承 <Http2Stream>

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

事件：'continue'#

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

事件：'headers'#

• headers <HTTP/2 Headers Object>
• flags <number>
• rawHeaders {HTTP/2 Raw Headers}

当收到流的额外请求头块时触发 'headers' 事件，例如收到一块 1xx 信息性请求头时。监听器回调函数会接收到 HTTP/2 Headers 对象、与这些请求头关联的标志以及原始格式的请求头（参见 HTTP/2 原始请求头）。

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

事件：'push'#

• headers <HTTP/2 Headers Object>
• flags <number>

当收到服务端推送流的响应请求头时触发 'push' 事件。监听器回调函数会接收到 HTTP/2 Headers 对象以及与这些请求头关联的标志。

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

事件：'response'#

• headers <HTTP/2 Headers Object>
• flags <number>
• rawHeaders {HTTP/2 Raw Headers}

当从此流中收到已连接 HTTP/2 服务器发送的响应 HEADERS 帧时触发 'response' 事件。监听器以三个参数调用：包含已接收 HTTP/2 Headers 对象的 Object、与这些请求头关联的标志以及原始格式的请求头（参见 HTTP/2 原始请求头）。

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

类：ServerHttp2Stream#

• 继承：<Http2Stream>

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

http2stream.additionalHeaders(headers)#

• headers <HTTP/2 Headers Object>

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

http2stream.headersSent#

• 类型：<boolean>

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

http2stream.pushAllowed#

• 类型：<boolean>

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

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

• headers <HTTP/2 Headers Object>
• options <Object>
• exclusive <boolean> 当为 true 且 parent 标识了父流时，所创建的流将成为父流的唯一直接依赖项，所有其他现有的依赖项将成为新创建流的依赖项。默认值： false。
• parent <number> 指定新创建的流所依赖的流的数字标识符。

启动推送流。回调函数以第二个参数传入为推送流创建的新 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');
});
copy

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

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

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

• headers <HTTP/2 Headers Object>
• options <Object>
• 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');
});
const http2 = require('node:http2');
const server = http2.createServer();
server.on('stream', (stream) => {
  stream.respond({ ':status': 200 });
  stream.end('some data');
});
copy

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

设置 options.waitForTrailers 后，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');
});
copy

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

• fd <number> | <FileHandle> 可读文件描述符。
• headers <HTTP/2 Headers Object>
• options <Object>
• statCheck <Function>
• waitForTrailers <boolean> 当为 true 时，Http2Stream 将在发送最后一个 DATA 帧后触发 'wantTrailers' 事件。
• offset <number> 开始读取的偏移位置。
• length <number> 从 fd 读取的数据量。

启动一个从给定文件描述符读取数据的响应。不对给定的文件描述符执行验证。如果尝试使用文件描述符读取数据时发生错误，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));
});
const http2 = require('node:http2');
const fs = require('node:fs');

const server = http2.createServer();
server.on('stream', (stream) => {
  const fd = fs.openSync('/some/file', 'r');

  const stat = fs.fstatSync(fd);
  const headers = {
    'content-length': stat.size,
    'last-modified': stat.mtime.toUTCString(),
    'content-type': 'text/plain; charset=utf-8',
  };
  stream.respondWithFD(fd, headers);
  stream.on('close', () => fs.closeSync(fd));
});
copy

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

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

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

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

设置 options.waitForTrailers 后，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));
});
const http2 = require('node:http2');
const fs = require('node:fs');

const server = http2.createServer();
server.on('stream', (stream) => {
  const fd = fs.openSync('/some/file', 'r');

  const stat = fs.fstatSync(fd);
  const headers = {
    'content-length': stat.size,
    'last-modified': stat.mtime.toUTCString(),
    'content-type': 'text/plain; charset=utf-8',
  };
  stream.respondWithFD(fd, headers, { waitForTrailers: true });
  stream.on('wantTrailers', () => {
    stream.sendTrailers({ ABC: 'some value to send' });
  });

  stream.on('close', () => fs.closeSync(fd));
});
copy

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

• path <string> | <Buffer> | <URL>
• headers <HTTP/2 Headers Object>
• options <Object>
• statCheck <Function>
• onError <Function> 在发送前发生错误时调用的回调函数。
• waitForTrailers <boolean> 当为 true 时，Http2Stream 将在发送最后一个 DATA 帧后触发 'wantTrailers' 事件。
• offset <number> 开始读取的偏移位置。
• length <number> 从 fd 读取的数据量。

将常规文件作为响应发送。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() can throw if the stream has been destroyed by
    // the other side.
    try {
      if (err.code === 'ENOENT') {
        stream.respond({ ':status': 404 });
      } else {
        stream.respond({ ':status': 500 });
      }
    } catch (err) {
      // Perform actual error handling.
      console.error(err);
    }
    stream.end();
  }

  stream.respondWithFile('/some/file',
                         { 'content-type': 'text/plain; charset=utf-8' },
                         { statCheck, onError });
});
const http2 = require('node:http2');
const server = http2.createServer();
server.on('stream', (stream) => {
  function statCheck(stat, headers) {
    headers['last-modified'] = stat.mtime.toUTCString();
  }

  function onError(err) {
    // stream.respond() can throw if the stream has been destroyed by
    // the other side.
    try {
      if (err.code === 'ENOENT') {
        stream.respond({ ':status': 404 });
      } else {
        stream.respond({ ':status': 500 });
      }
    } catch (err) {
      // Perform actual error handling.
      console.error(err);
    }
    stream.end();
  }

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

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

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

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

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

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

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

设置 options.waitForTrailers 后，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' });
  });
});
const http2 = require('node:http2');
const server = http2.createServer();
server.on('stream', (stream) => {
  stream.respondWithFile('/some/file',
                         { 'content-type': 'text/plain; charset=utf-8' },
                         { waitForTrailers: true });
  stream.on('wantTrailers', () => {
    stream.sendTrailers({ ABC: 'some value to send' });
  });
});
copy

类：Http2Server#

• 继承自：<net.Server>

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

事件：'checkContinue'#

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

如果注册了 'request' 监听器或为 http2.createServer() 提供了回调函数，则每当收到带有 HTTP Expect: 100-continue 的请求时，就会触发 'checkContinue' 事件。如果没有监听此事件，服务器将根据需要自动响应 100 Continue 状态。

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

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

事件：'connection'#

• socket <stream.Duplex>

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

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

事件：'request'#

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

每次有请求时触发。每个会话可能有多个请求。请参阅兼容性 API。

事件：'session'#

• session <ServerHttp2Session>

当 Http2Server 创建新的 Http2Session 时，会触发 'session' 事件。

事件：'sessionError'#

• error <Error>
• session <ServerHttp2Session>

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

事件：'stream'#

• stream <Http2Stream> 对流的引用
• headers <HTTP/2 Headers Object> 描述请求头的对象
• flags <number> 关联的数值标志
• rawHeaders {HTTP/2 Raw Headers} 包含原始头信息的数组

当与服务器关联的 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');
});
const http2 = require('node:http2');
const {
  HTTP2_HEADER_METHOD,
  HTTP2_HEADER_PATH,
  HTTP2_HEADER_STATUS,
  HTTP2_HEADER_CONTENT_TYPE,
} = http2.constants;

const server = http2.createServer();
server.on('stream', (stream, headers, flags) => {
  const method = headers[HTTP2_HEADER_METHOD];
  const path = headers[HTTP2_HEADER_PATH];
  // ...
  stream.respond({
    [HTTP2_HEADER_STATUS]: 200,
    [HTTP2_HEADER_CONTENT_TYPE]: 'text/plain; charset=utf-8',
  });
  stream.write('hello ');
  stream.end('world');
});
copy

事件：'timeout'#

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

server.close([callback])#

• callback <Function>

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

如果提供了 callback，则在所有活动会话关闭之前它不会被调用，尽管服务器已经停止接受新会话。有关更多详细信息，请参阅 net.Server.close()。

server[Symbol.asyncDispose]()#

调用 server.close() 并返回一个 Promise，该 Promise 在服务器关闭时兑现。

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

• msecs <number> 默认： 0（无超时）
• callback <Function>
• 返回：<Http2Server>

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

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

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

server.timeout#

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

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

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

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

server.updateSettings([settings])#

• settings <HTTP/2 Settings Object>

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

对于无效的 settings 值，抛出 ERR_HTTP2_INVALID_SETTING_VALUE。

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

类：Http2SecureServer#

• 继承自：<tls.Server>

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

事件：'checkContinue'#

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

如果注册了 'request' 监听器或为 http2.createSecureServer() 提供了回调函数，则每当收到带有 HTTP Expect: 100-continue 的请求时，就会触发 'checkContinue' 事件。如果没有监听此事件，服务器将根据需要自动响应 100 Continue 状态。

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

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

事件：'connection'#

• socket <stream.Duplex>

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

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

事件：'request'#

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

每次有请求时触发。每个会话可能有多个请求。请参阅兼容性 API。

事件：'session'#

• session <ServerHttp2Session>

当 Http2SecureServer 创建新的 Http2Session 时，会触发 'session' 事件。

事件：'sessionError'#

• error <Error>
• session <ServerHttp2Session>

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

事件：'stream'#

• stream <Http2Stream> 对流的引用
• headers <HTTP/2 Headers Object> 描述请求头的对象
• flags <number> 关联的数值标志
• rawHeaders {HTTP/2 Raw Headers} 包含原始头信息的数组

当与服务器关联的 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');
});
const http2 = require('node:http2');
const {
  HTTP2_HEADER_METHOD,
  HTTP2_HEADER_PATH,
  HTTP2_HEADER_STATUS,
  HTTP2_HEADER_CONTENT_TYPE,
} = http2.constants;

const options = getOptionsSomehow();

const server = http2.createSecureServer(options);
server.on('stream', (stream, headers, flags) => {
  const method = headers[HTTP2_HEADER_METHOD];
  const path = headers[HTTP2_HEADER_PATH];
  // ...
  stream.respond({
    [HTTP2_HEADER_STATUS]: 200,
    [HTTP2_HEADER_CONTENT_TYPE]: 'text/plain; charset=utf-8',
  });
  stream.write('hello ');
  stream.end('world');
});
copy

事件：'timeout'#

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

事件：'unknownProtocol'#

• socket <stream.Duplex>

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

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

请参阅兼容性 API。

server.close([callback])#

• callback <Function>

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

如果提供了 callback，则在所有活动会话关闭之前它不会被调用，尽管服务器已经停止接受新会话。有关更多详细信息，请参阅 tls.Server.close()。

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

• msecs <number> 默认： 120000（2 分钟）
• callback <Function>
• 返回：<Http2SecureServer>

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

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

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

server.timeout#

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

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

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

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

server.updateSettings([settings])#

• settings <HTTP/2 Settings Object>

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

对于无效的 settings 值，抛出 ERR_HTTP2_INVALID_SETTING_VALUE。

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

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

• options <Object>
• maxDeflateDynamicTableSize <number> 设置用于压缩头字段的动态表最大大小。默认： 4Kib。
• maxSettings <number> 设置每个 SETTINGS 帧的最大设置条目数。允许的最小值为 1。默认： 32。
• maxSessionMemory <number> 设置 Http2Session 允许使用的最大内存。该值以兆字节为单位，例如 1 等于 1 兆字节。允许的最小值为 1。这是一个基于信用的限制，现有的 Http2Stream 可能会导致超过此限制，但在超过此限制时，新的 Http2Stream 实例将被拒绝。当前 Http2Stream 会话的数量、头压缩表的当前内存使用量、排队等待发送的数据以及未确认的 PING 和 SETTINGS 帧都计入当前限制。默认： 10。
• maxHeaderListPairs <number> 设置头条目的最大数量。这类似于 node:http 模块中的 server.maxHeadersCount 或 request.maxHeadersCount。最小值为 4。默认： 128。
• maxOutstandingPings <number> 设置未完成的、未确认的 ping 的最大数量。默认： 10。
• maxSendHeaderBlockLength <number> 设置序列化、压缩后的头块允许的最大大小。尝试发送超过此限制的头将导致触发 'frameError' 事件，并且流将被关闭和销毁。虽然这设置了整个头块允许的最大大小，但 nghttp2（内部 http2 库）对每个解压缩的键/值对有 65536 的限制。
• paddingStrategy <number> 用于确定 HEADERS 和 DATA 帧使用的填充量的策略。默认： http2.constants.PADDING_STRATEGY_NONE。值可以是以下之一：
  • http2.constants.PADDING_STRATEGY_NONE：不应用填充。
  • http2.constants.PADDING_STRATEGY_MAX：应用由内部实现确定的最大填充量。
  • http2.constants.PADDING_STRATEGY_ALIGNED：尝试应用足够的填充，以确保总帧长度（包括 9 字节的头）是 8 的倍数。对于每个帧，都有一个由当前流量控制状态和设置确定的最大允许填充字节数。如果此最大值小于确保对齐所需的计算量，则使用最大值，总帧长度不一定按 8 字节对齐。
• peerMaxConcurrentStreams <number> 为远程对等方设置最大并发流数，就好像已收到 SETTINGS 帧一样。如果远程对等方设置了自己的 maxConcurrentStreams 值，将被覆盖。默认： 100。
• maxSessionInvalidFrames <integer> 设置在关闭会话之前将容忍的无效帧的最大数量。默认： 1000。
• maxSessionRejectedStreams <integer> 设置在关闭会话之前将容忍的、在创建时被拒绝的流的最大数量。每次拒绝都与 NGHTTP2_ENHANCE_YOUR_CALM 错误相关联，该错误应告诉对等方不要再打开任何流，因此继续打开流被视为对等方行为不当的标志。默认： 100。
• settings <HTTP/2 Settings Object> 连接时发送给远程对等方的初始设置。
• streamResetBurst <number> 和 streamResetRate <number> 设置传入流重置（RST_STREAM 帧）的速率限制。必须同时设置这两个设置才能生效，默认值分别为 1000 和 33。
• remoteCustomSettings <Array> 整数值数组确定设置类型，这些类型包含在接收到的 remoteSettings 的 CustomSettings 属性中。请参阅 Http2Settings 对象的 CustomSettings 属性以获取有关允许的设置类型的更多信息。
• Http1IncomingMessage <http.IncomingMessage> 指定用于 HTTP/1 回退的 IncomingMessage 类。对于扩展原始 http.IncomingMessage 非常有用。默认： http.IncomingMessage。已弃用。 使用 http1Options.IncomingMessage 代替。请参阅 DEP0202。
• Http1ServerResponse <http.ServerResponse> 指定用于 HTTP/1 回退的 ServerResponse 类。对于扩展原始 http.ServerResponse 非常有用。默认： http.ServerResponse。已弃用。 使用 http1Options.ServerResponse 代替。请参阅 DEP0202。
• http1Options <Object> 当 allowHTTP1 为 true 时，用于配置 HTTP/1 回退的选项对象。这些选项传递给底层的 HTTP/1 服务器。请参阅 http.createServer() 以了解可用选项。其中包括以下内容：
  • IncomingMessage <http.IncomingMessage> 指定用于 HTTP/1 回退的 IncomingMessage 类。默认： http.IncomingMessage。
  • ServerResponse <http.ServerResponse> 指定用于 HTTP/1 回退的 ServerResponse 类。默认： http.ServerResponse。
  • keepAliveTimeout <number> 在写入最后一个响应后，服务器需要等待额外传入数据的无活动毫秒数，在此之后套接字将被销毁。默认： 5000。
• Http2ServerRequest <http2.Http2ServerRequest> 指定要使用的 Http2ServerRequest 类。对于扩展原始 Http2ServerRequest 非常有用。默认： Http2ServerRequest。
• Http2ServerResponse <http2.Http2ServerResponse> 指定要使用的 Http2ServerResponse 类。对于扩展原始 Http2ServerResponse 非常有用。默认： Http2ServerResponse。
• unknownProtocolTimeout <number> 指定当触发 'unknownProtocol' 事件时，服务器应等待的超时时间（毫秒）。如果在该时间之后套接字尚未被销毁，服务器将销毁它。默认： 10000。
• strictFieldWhitespaceValidation <boolean> 如果为 true，则根据 RFC-9113 开启对 HTTP/2 头字段名称和值的前导和尾随空格的严格验证。默认： true。
• strictSingleValueFields <boolean> 如果为 true，则对定义为仅有一个值的头和尾部使用严格验证，如果提供了多个值，则抛出错误。默认： true。
• ...options <Object> 可以提供任何 net.createServer() 选项。