WebTransport: конструктор WebTransport()

Конструктор WebTransport() создаёт новый экземпляр объекта WebTransport.

url

Строка, представляющая URL HTTP/3 сервера для подключения. Схема должна быть HTTPS, а номер порта необходимо указать явно.

options Необязательно

Объект, который может содержать следующие свойства:

allowPooling Необязательно

Логическое значение. Если true, соединение сети для этого WebTransport может быть разделено с пулом других сессий HTTP/3. По умолчанию значение false, и соединение не может быть разделено.

congestionControl Необязательно

Строка, указывающая предпочтение приложения, чтобы алгоритм управления заторами при отправке данных по этому соединению был настроен на пропускную способность или низкую задержку. Это подсказка для пользовательского агента. Допустимые значения: default (по умолчанию), throughput, и low-latency.

requireUnreliable Необязательно

Логическое значение. Если true, соединение не может быть установлено по протоколу HTTP/2, если соединение HTTP/3 невозможно. По умолчанию значение false.

serverCertificateHashes Необязательно

Массив объектов, каждый из которых определяет значение хэша сертификата сервера вместе с именем алгоритма, который использовался для его генерации. Этот параметр поддерживается только для транспортов, использующих отдельные подключения (allowPooling равно false).

Если указано, браузер попытается аутентифицировать сертификат, предоставленный сервером, по предоставленным значениям хэша сертификата(ов), чтобы подключиться, вместо использования веб-инфраструктуры открытых ключей (PKI). Если совпадают какие-либо хэши, браузер знает, что сервер обладает надёжным сертификатом, и подключится как обычно. Если массив пуст, пользовательский агент использует те же процедуры проверки сертификатов PKI, которые он использовал бы для обычной операции fetch.

Эта функция позволяет разработчикам подключаться к серверам WebTransport, которые обычно сталкиваются с проблемами получения общедоступного сертификата, например, к хостам, которые не являются публично доступными, или к временным хостам, например, виртуальным машинам.

Примечание: Веб-приложение, как правило, получает хэши от надёжного посредника. Например, вы можете использовать облачный провайдер для предоставления виртуальных машин, на которых работают ваши серверы WebTransport. Провайдер имеет надёжный доступ к серверу и может запросить его сертификат, сгенерировать хэши и предоставить их приложению через API (который опосредуется через PKI) или консоль облачного сервиса. Теперь веб-приложение может напрямую подключиться к серверу, размещённому на виртуальной машине, используя предоставленные хэши, даже если сама виртуальная машина не имеет долгоживущего сертификата 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

Выбрасывается, если serverCertificateHashes установлено для подключения, не использующего отдельные подключения (другими словами, если allowPooling равно true).

В этом примере показано, как создать WebTransport с использованием только URL, дождаться его подключения и отслеживать транспорт, сообщая о его закрытии.

Сначала мы определяем метод async, который принимает URL и использует его для создания объекта WebTransport. Параметры конструктора не указаны, поэтому подключение использует параметры по умолчанию: выделенное подключение, поддержка ненадежных переводов не требуется, управление заторами по умолчанию и обычная веб-аутентификация PKI сервера. Обратите внимание, что схема должна быть HTTPS, а номер порта необходимо указать явно.

После выполнения обещания WebTransport.ready вы можете начать использовать подключение.

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. Ошибки, возвращаемые операциями WebTransport, имеют тип WebTransportError и содержат дополнительные данные помимо стандартного набора DOMException.

Метод closeTransport() ниже показывает, как это сделать. Внутри блока try...catch он использует await для ожидания выполнения или отклонения обещания closed и затем сообщает, было ли подключение закрыто преднамеренно или из-за ошибки.

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

В примере ниже показан код для создания WebTransport, который задаёт параметр serverCertificateHashes. В этом случае массив содержит два хэша, оба закодированы с использованием алгоритма SHA-256. Обратите внимание, что параметр allowPooling должен быть false (по умолчанию).

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

• Использование WebTransport
• API WebSockets
• API потоков
• WebTransport через HTTP/3