WebTransport: метод createUnidirectionalStream()

Метод createUnidirectionalStream() интерфейса WebTransport асинхронно открывает однонаправленный поток.

Метод возвращает Promise, который разрешается в объект WritableStream, который можно использовать для надёжной записи данных на сервер.

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

Относительный порядок, в котором очереди байтов из созданных потоков должны быть отправлены, может быть задан с помощью параметра sendOrder. Если параметр установлен, очереди байтов в потоках с более высоким порядком отправки гарантированно будут отправлены перед очередями байтов в потоках с более низким порядком отправки. Если порядок не задан, порядок, в котором байты отправляются, зависит от реализации. Однако, даже если байты из потоков с более высоким порядком отправки отправляются первыми, они могут не прибыть первыми.

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

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

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

Целочисленное значение, определяющее приоритет отправки этого потока относительно других потоков, для которых значение было задано. Очереди байтов отправляются первыми для потоков с более высоким значением. Если не задано, порядок отправки зависит от реализации.

A Promise, который разрешается в объект WebTransportSendStream (это объект WritableStream).

InvalidStateError DOMException

Выбрасывается, если createUnidirectionalStream() вызывается, когда WebTransport закрыт или произошла ошибка.

Используйте метод createUnidirectionalStream() для получения ссылки на WritableStream. Из него вы можете получить writer для записи данных в поток и отправки их на сервер.

Используйте метод close() полученного WritableStreamDefaultWriter для закрытия связанного HTTP/3 соединения. Браузер пытается отправить все ожидающие данные перед фактическим закрытием связанного соединения.

async function writeData() {
  const stream = await transport.createUnidirectionalStream({
    sendOrder: "596996858",
  });
  const writer = stream.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.abort() для прерывания потока. При использовании abort(), браузер может отбросить любые ожидающие данные, которые ещё не были отправлены.

// ...

const stream = await transport.createUnidirectionalStream();
const writer = stream.getWriter();

// ...

writer.write(...);
writer.write(...);
await writer.abort();
// Not all the data may have been written.

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