API WebTransport

API WebTransport представляет собой современное обновление WebSockets, передающее данные между клиентом и сервером с использованием HTTP/3 Transport. WebTransport поддерживает несколько потоков, однонаправленные потоки и доставку в произвольном порядке. Он обеспечивает надёжную передачу через потоки и ненадежную передачу через дейтаграммы наподобие UDP.

HTTP/3 разрабатывается с 2018 года. Он основан на протоколе QUIC от Google (который, в свою очередь, основан на UDP) и исправляет несколько проблем, связанных с классическим протоколом TCP, на котором основаны HTTP и WebSockets.

Это включает:

Блокировка начала очереди

HTTP/2 позволяет мультиплексирование, поэтому одно соединение может одновременно передавать несколько ресурсов. Однако, если один ресурс не работает, все остальные ресурсы на этом соединении приостанавливаются до тех пор, пока не будут повторно переданы все недостающие пакеты. При использовании QUIC затронут только неработающий ресурс.

Более высокая производительность

QUIC в многих отношениях эффективнее TCP. QUIC может сам обрабатывать функции безопасности, а не передавать ответственность другим протоколам, таким как TLS — что означает меньше циклов. И потоки обеспечивают более эффективную передачу, чем более старый механизм пакетов. Это может значительно повлиять на производительность, особенно в сетях с высоким временем задержки.

Лучшие переходы между сетями

QUIC использует уникальный идентификатор соединения для обработки источника и получателя каждого запроса — для обеспечения правильной доставки пакетов. Этот идентификатор может сохраняться между различными сетями, что означает, что, например, загрузка может продолжаться без прерывания, если вы переключитесь с Wi-Fi на мобильную сеть. HTTP/2, с другой стороны, использует IP-адреса в качестве идентификаторов, поэтому переходы между сетями могут быть проблематичными.

Ненадёжная передача

HTTP/3 поддерживает ненадежную передачу данных с помощью дейтаграмм.

API WebTransport предоставляет низкоуровневый доступ к двустороннему общению через HTTP/3, используя преимущества вышеперечисленного и поддерживая как надёжную, так и ненадежную передачу данных.

Чтобы открыть соединение с сервером HTTP/3, передайте его URL-адрес в конструктор WebTransport(). Обратите внимание, что схема должна быть HTTPS, а номер порта должен быть явно указан. После выполнения обещания WebTransport.ready вы можете начать использовать соединение.

Также обратите внимание, что вы можете отреагировать на закрытие соединения, дождавшись выполнения обещания WebTransport.closed. Ошибки, возвращаемые операциями WebTransport, имеют тип WebTransportError и содержат дополнительные данные помимо стандартного набора DOMException.

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

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

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

  // ...
}

// ...

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}.`);
  }
}

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

Ненадёжная передача данных обрабатывается свойством WebTransport.datagrams — оно возвращает объект WebTransportDatagramDuplexStream, содержащий всё необходимое для отправки дейтаграмм на сервер и получения их обратно.

Свойство WebTransportDatagramDuplexStream.writable возвращает объект WritableStream, к которому можно получить доступ через писатель для отправки данных на сервер:

const writer = transport.datagrams.writable.getWriter();
const data1 = new Uint8Array([65, 66, 67]);
const data2 = new Uint8Array([68, 69, 70]);
writer.write(data1);
writer.write(data2);

Свойство WebTransportDatagramDuplexStream.readable возвращает объект ReadableStream, который можно использовать для получения данных от сервера:

async function readData() {
  const reader = transport.datagrams.readable.getReader();
  while (true) {
    const { value, done } = await reader.read();
    if (done) {
      break;
    }
    // value is a Uint8Array.
    console.log(value);
  }
}

«Надёжная» передача означает, что гарантируется передача данных и их порядок. Это обеспечивает более медленную доставку (хотя и быстрее, чем с WebSockets), и это необходимо в ситуациях, когда важны надёжность и порядок (например, в приложениях чата).

При использовании надёжной передачи через потоки вы также можете установить относительный приоритет разных потоков в рамках одного транспорта.

Чтобы открыть однонаправленный поток с пользовательского агента, используйте метод WebTransport.createUnidirectionalStream() для получения ссылки на WritableStream. Отсюда вы можете получить писатель для записи данных в поток и отправки на сервер.

async function writeData() {
  const stream = await transport.createUnidirectionalStream();
  const writer = stream.writable.getWriter();
  const data1 = new Uint8Array([65, 66, 67]);
  const data2 = new Uint8Array([68, 69, 70]);
  writer.write(data1);
  writer.write(data2);

  try {
    await writer.close();
    console.log("All data has been sent.");
  } catch (error) {
    console.error(`An error occurred: ${error}`);
  }
}

Обратите также внимание на использование метода WritableStreamDefaultWriter.close() для закрытия связанного HTTP/3 соединения после отправки всех данных.

Если сервер открывает однонаправленный поток для передачи данных клиенту, к нему можно получить доступ на клиенте через свойство WebTransport.incomingUnidirectionalStreams, которое возвращает ReadableStream объектов WebTransportReceiveStream. Их можно использовать для чтения экземпляров Uint8Array, отправленных сервером.

В этом случае, первым делом необходимо создать функцию для чтения WebTransportReceiveStream. Эти объекты наследуют от класса ReadableStream, поэтому могут использоваться точно так же:

async function readData(receiveStream) {
  const reader = receiveStream.getReader();
  while (true) {
    const { done, value } = await reader.read();
    if (done) {
      break;
    }
    // value is a Uint8Array
    console.log(value);
  }
}

Затем вызовите WebTransport.incomingUnidirectionalStreams и получите ссылку на доступный для чтения объект в возвращаемом ReadableStream, а затем используйте этот объект для чтения данных с сервера. Каждый фрагмент — WebTransportReceiveStream, и мы используем функцию readFrom() для их чтения:

async function receiveUnidirectional() {
  const uds = transport.incomingUnidirectionalStreams;
  const reader = uds.getReader();
  while (true) {
    const { done, value } = await reader.read();
    if (done) {
      break;
    }
    // value is an instance of WebTransportReceiveStream
    await readData(value);
  }
}

Двусторонняя передача

Чтобы открыть двусторонний поток с пользовательского агента, используйте метод WebTransport.createBidirectionalStream() для получения ссылки на WebTransportBidirectionalStream. Он содержит свойства readable и writable, возвращающие ссылки на экземпляры WebTransportReceiveStream и WebTransportSendStream , которые можно использовать для чтения и записи на сервер.

async function setUpBidirectional() {
  const stream = await transport.createBidirectionalStream();
  // stream is a WebTransportBidirectionalStream
  // stream.readable is a WebTransportReceiveStream
  const readable = stream.readable;
  // stream.writable is a WebTransportSendStream
  const writable = stream.writable;

  ...
}

Чтение из WebTransportReceiveStream может быть выполнено следующим образом:

async function readData(readable) {
  const reader = readable.getReader();
  while (true) {
    const { value, done } = await reader.read();
    if (done) {
      break;
    }
    // value is a Uint8Array.
    console.log(value);
  }
}

Запись в WebTransportSendStream может быть выполнено следующим образом:

async function writeData(writable) {
  const writer = writable.getWriter();
  const data1 = new Uint8Array([65, 66, 67]);
  const data2 = new Uint8Array([68, 69, 70]);
  writer.write(data1);
  writer.write(data2);
}

Если сервер открывает двусторонний поток для передачи данных клиенту и получения данных от него, к нему можно получить доступ через свойство WebTransport.incomingBidirectionalStreams, которое возвращает ReadableStream объектов WebTransportBidirectionalStream. Каждый из них можно использовать для чтения и записи экземпляров Uint8Array, как показано выше. Однако, как и в примере с однонаправленным потоком, вам сначала нужна функция для чтения двустороннего потока:

async function receiveBidirectional() {
  const bds = transport.incomingBidirectionalStreams;
  const reader = bds.getReader();
  while (true) {
    const { done, value } = await reader.read();
    if (done) {
      break;
    }
    // value is an instance of WebTransportBidirectionalStream
    await readData(value.readable);
    await writeData(value.writable);
  }
}

WebTransport

Предоставляет возможность пользовательскому агенту подключаться к серверу HTTP/3, инициировать надежный и ненадежный транспорт в одном или обоих направлениях и закрывать соединение, когда оно больше не требуется.

WebTransportBidirectionalStream

Представляет двунаправленный поток, созданный сервером или клиентом, который может использоваться для надежного транспорта. Предоставляет доступ к ReadableStream для чтения входящих данных и WritableStream для записи исходящих данных.

WebTransportDatagramDuplexStream

Представляет дуплексный поток, который может использоваться для ненадежного транспорта датаграмм между клиентом и сервером. Предоставляет доступ к ReadableStream для чтения входящих датаграмм, WritableStream для записи исходящих датаграмм, а также различные настройки и статистику, связанные с потоком.

WebTransportError

Представляет ошибку, связанную с API WebTransport, которая может возникнуть из-за ошибок сервера, проблем с подключением к сети или операций прерывания, инициированных клиентом (например, возникающих из вызова WritableStream.abort()).

WebTransportReceiveStream

Предоставляет функции потоковой передачи для входящего одностороннего или двунаправленного WebTransport потока WebTransport.

WebTransportSendStream

Предоставляет функции потоковой передачи для исходящего одностороннего или двунаправленного WebTransport потока WebTransport.

Для ознакомления с полными примерами, см.:

• Клиент WebTransport через HTTP/3
• WebTransport (BYOB) Эхо с WebCodecs в рабочем потоке

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