WebTransport: WebTransport() 构造函数

语法

new WebTransport(url)
new WebTransport(url, options)

参数

url

一个表示要连接的 HTTP/3 服务器的 URL 的字符串。协议必须是 HTTPS，并且需要显式指定端口号。

options 可选

一个可能具有以下属性的对象

allowPooling 可选

一个布尔值。如果为 true，则此 WebTransport 的网络连接可以与其他 HTTP/3 会话池共享。默认值为 false，连接不可共享。

congestionControl 可选

一个字符串，指示应用程序在通过此连接发送数据时使用的拥塞控制算法是偏向吞吐量还是低延迟。这是用户代理的提示。允许的值为：default（默认）、throughput 和 low-latency。

requireUnreliable 可选

一个布尔值。如果为 true，如果无法建立 HTTP/3 连接，则无法通过 HTTP/2 建立连接。默认值为 false。

serverCertificateHashes 可选

一个对象数组，每个对象定义服务器证书的哈希值以及用于生成该哈希值的算法名称。此选项仅支持使用专用连接的传输（allowPooling 为 false）。

如果指定，浏览器将尝试使用提供的证书哈希值来验证服务器提供的证书，而不是使用 Web 公共密钥基础设施（PKI）。如果任何哈希值匹配，浏览器将知道服务器拥有受信任的证书，并将正常连接。如果为空，用户代理将使用与普通 fetch 操作相同的 PKI 证书验证过程。

此功能允许开发人员连接到通常难以获取公开受信任证书的 WebTransport 服务器，例如不可公开路由的主机或短暂主机（如虚拟机）。

注意： Web 应用程序通常会从受信任的中间服务器获取哈希值。例如，您可以使用云提供商来提供运行 WebTransport 服务器的 VM。提供商可以信任地访问服务器，请求其证书，生成哈希值，并通过 API（通过 PKI 媒介）或云控制台将这些哈希值提供给应用程序。现在，Web 应用程序可以使用提供的哈希值直接连接到 VM 托管的服务器，即使 VM 本身没有长期 TLS 证书。

证书必须是 X.509v3 证书，其有效期小于 2 周，并且当前时间必须在该有效期内。证书中公钥的格式取决于实现，但至少应包含 ECDSA 和 secp256r1（NIST P-256）命名组，并且不得包含 RSA 密钥。因此，ECSDA 密钥是可互操作的默认公钥格式。用户代理可能会添加更多要求；如果已知，将在 浏览器兼容性 部分列出。

数组中的每个对象都有以下属性

algorithm

一个值为 sha-256（不区分大小写）的字符串。请注意，此字符串表示用于验证哈希的算法，并且任何使用未知算法的哈希都将被忽略。在撰写本文时，SHA-256 是规范中列出的唯一哈希算法。

value

一个包含哈希值的 ArrayBuffer 或 TypedArray。

异常

NotSupportedError DOMException

如果指定了 serverCertificateHashes 但传输协议不支持此功能，则会抛出此异常。

SyntaxError

如果指定的 url 无效、协议不是 HTTPS 或 URL 包含片段，则会抛出此异常。

TypeError

如果为非专用连接（即 allowPooling 为 true）设置了 serverCertificateHashes，则会抛出此异常。

示例

使用默认选项连接

此示例展示了如何仅使用 URL 构建 WebTransport，等待其连接，然后监视传输并报告其关闭情况。

首先，我们定义一个接受 URL 并使用它来构造 WebTransport 对象的 async 方法。未指定构造函数选项，因此连接使用默认选项：专用连接、不支持不可靠传输、默认拥塞控制以及与服务器的正常 Web PKI 身份验证。请注意，协议必须是 HTTPS，并且需要显式指定端口号。

一旦 WebTransport.ready Promise fulfilled，您就可以开始使用连接了。

async function initTransport(url) {
  // Initialize transport connection
  const transport = new WebTransport(url);

  // The connection can be used once ready fulfills
  await transport.ready;
  return transport;
}

可以通过等待 WebTransport.closed Promise fulfilled 来响应连接关闭。WebTransport 操作返回的错误属于 WebTransportError 类型，并且在标准 DOMException 集之上包含额外数据。

下面的 closeTransport() 方法展示了如何做到这一点。在 try...catch 块中，它使用 await 来等待 closed Promise fulfilled 或 rejected，然后报告连接是意外关闭还是由于错误关闭。

async function closeTransport(transport) {
  // Respond to connection closing
  try {
    await transport.closed;
    console.log(`The HTTP/3 connection to ${url} closed gracefully.`);
  } catch (error) {
    console.error(`The HTTP/3 connection to ${url} closed due to ${error}.`);
  }
}

我们可以像下面这样在自己的异步函数中调用上面的异步函数。

// Use the transport
async function useTransport(url) {
  const transport = await initTransport(url);

  // Use the transport object to send and receive data
  // …

  // When done, close the transport
  await closeTransport(transport);
}

const url = "https://example.com:4999/wt";
useTransport(url);

使用服务器证书哈希进行连接

下面的示例显示了用于构造指定 serverCertificateHashes 选项的 WebTransport 的代码。在这种情况下，数组包含两个哈希，都使用 SHA-256 算法编码。请注意，allowPooling 选项必须为 false（默认值）。

const transport = new WebTransport(url, {
  serverCertificateHashes: [
    {
      algorithm: "sha-256",
      value: "5a155927eba7996228455e4721e6fe5f739ae15db6915d765e5db302b4f8a274",
    },
    {
      algorithm: "sha-256",
      value: "7d7094e7a8d3097feff3b5ee84fa5cab58e4de78f38bcfdee5ea8b51f4bfa8fd",
    },
  ],
});

规范

浏览器兼容性

另见

• 使用 WebTransport
• WebSockets API
• Streams API
• 基于 HTTP/3 的 WebTransport