WebTransport：WebTransport() 构造函数

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)。如果任何哈希值匹配，浏览器就知道服务器拥有受信任的证书，并将照常连接。如果为空，则用户代理将使用与正常获取操作相同的 PKI 证书验证过程。

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

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

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

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

algorithm

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

value

包含哈希值的ArrayBuffer 或TypedArray。

NotSupportedError DOMException

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

SyntaxError

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

TypeError

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

此示例显示了如何仅使用 URL 构造 WebTransport，等待其连接，然后监视传输并在其关闭时报告。

首先，我们定义一个 async 方法，该方法接收一个 URL 并使用它来构造 WebTransport 对象。没有指定构造函数选项，因此连接使用默认选项：专用连接、不需要支持不可靠的传输、默认拥塞控制以及与服务器的正常 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