WebTransportSendStream.getStats() — Methode · JavaScript-Referenz

Signatur

WebTransportSendStream.prototype.getStats()

Beschreibung

Die Methode getStats() gehört zum Interface WebTransportSendStream. Dieses Interface ist ein WritableStream, über den Daten zu einem WebTransport-Server gesendet werden. Die Methode gibt ein Promise zurück. Es wird mit einem Statistik-Objekt erfüllt, das den Zustand dieses einen Streams zum Zeitpunkt der Abfrage beschreibt.

Das Objekt enthält diese Felder:

timestamp: Zeitpunkt der Erfassung als DOMHighResTimeStamp.
bytesWritten: Anzahl der Bytes, die die Anwendung in den Stream geschrieben hat. Dazu zählen auch Bytes, die noch im Puffer liegen.
bytesSent: Anzahl der Bytes, die tatsächlich über das Netzwerk gesendet wurden. Erneute Übertragungen werden nicht mitgezählt.
bytesAcknowledged: Anzahl der Bytes, deren Empfang der Server bestätigt hat (fortlaufend ab Stream-Anfang).

Aus dem Vergleich der Werte lässt sich ablesen, wie viel noch gepuffert ist (bytesWritten - bytesSent) und wie viel unterwegs ist (bytesSent - bytesAcknowledged). Das hilft bei Upload-Fortschrittsanzeigen, bei der Flusskontrolle in der Anwendung und bei der Fehlersuche an langsamen Verbindungen.

Einen WebTransportSendStream bekommt man über WebTransport.createUnidirectionalStream() oder über die Eigenschaft writable eines WebTransportBidirectionalStream. Statistiken für die ganze Verbindung liefert dagegen WebTransport.getStats().

Rückgabewert

Typ

Promise<WebTransportSendStreamStats>

Beschreibung

Ein Promise, das mit einem Objekt erfüllt wird. Es enthält die Felder timestamp, bytesWritten, bytesSent und bytesAcknowledged.

Beispiele

Statistiken eines unidirektionalen Streams abfragen

const transport = new WebTransport('https://example.com:4433/upload');
await transport.ready;

const stream = await transport.createUnidirectionalStream();
const writer = stream.getWriter();
await writer.write(new TextEncoder().encode('Hallo Server!'));

const stats = await stream.getStats();
console.log(`Geschrieben: ${stats.bytesWritten}, gesendet: ${stats.bytesSent}, bestätigt: ${stats.bytesAcknowledged}`);

Geschrieben: 13, gesendet: 13, bestätigt: 0

Upload-Fortschritt anhand bestätigter Bytes anzeigen

const uploadFile = async (transport, file, onProgress) => {
  const stream = await transport.createUnidirectionalStream();
  const writer = stream.getWriter();

  // Regelmäßig den Fortschritt abfragen
  const timer = setInterval(async () => {
    const { bytesAcknowledged } = await stream.getStats();
    onProgress(Math.round((bytesAcknowledged / file.size) * 100));
  }, 250);

  try {
    const reader = file.stream().getReader();
    for (;;) {
      const { value, done } = await reader.read();
      if (done) break;
      await writer.write(value);
    }
    await writer.close();
  } finally {
    clearInterval(timer);
  }
};

// Nutzung:
// await uploadFile(transport, input.files[0], (p) => console.log(`${p} %`));

12 % 47 % 89 % 100 %

Pufferstand im bidirektionalen Stream mit Feature-Erkennung prüfen

const logBuffer = async (sendStream) => {
  if (typeof sendStream.getStats !== 'function') {
    console.warn('getStats() wird in diesem Browser nicht unterstützt');
    return;
  }
  const s = await sendStream.getStats();
  console.log({
    gepuffert: s.bytesWritten - s.bytesSent,
    unterwegs: s.bytesSent - s.bytesAcknowledged,
    zeitpunkt: s.timestamp.toFixed(1)
  });
};

const transport = new WebTransport('https://example.com:4433/chat');
await transport.ready;
const bidi = await transport.createBidirectionalStream();
await bidi.writable.getWriter().write(new Uint8Array(4096));
await logBuffer(bidi.writable);

{ gepuffert: 0, unterwegs: 4096, zeitpunkt: '1532.7' }

// Wichtig · Fallstricke

Browser-Unterstützung: Die Methode ist experimentell. Firefox (ab Version 114) unterstützt sie, Chromium-basierte Browser bisher nicht, obwohl sie WebTransport selbst unterstützen. Vor dem Aufruf deshalb immer per Feature-Erkennung (typeof stream.getStats === 'function') prüfen.
Nur in sicheren Kontexten: WebTransport steht nur unter HTTPS zur Verfügung. Die API ist auch in Web Workern nutzbar.
Die Werte sind eine Momentaufnahme. Beim Abfragen in kurzen Abständen (Polling) sollte die Frequenz moderat bleiben, damit der Hauptthread nicht unnötig belastet wird.
bytesAcknowledged kann deutlich hinter bytesSent zurückliegen, vor allem bei hoher Latenz. Für eine verlässliche Fortschrittsanzeige ist bytesAcknowledged trotzdem besser geeignet als bytesWritten.
Die Feldnamen haben sich zwischen Entwürfen der Spezifikation geändert. Auf fehlende Felder sollte der Code robust reagieren, etwa mit stats.bytesAcknowledged ?? 0.

Siehe auch

WebTransportSendStream WebTransport.getStats() WebTransport.createUnidirectionalStream() WebTransportBidirectionalStream WritableStream WebTransportReceiveStream.getStats()