WebTransportReceiveStream.getStats() — Methode · JavaScript-Referenz

Signatur

WebTransportReceiveStream.prototype.getStats()

Beschreibung

Die Methode getStats() der Schnittstelle WebTransportReceiveStream gibt ein Promise zurück. Es wird mit einem Objekt erfüllt, das Statistiken zum aktuellen eingehenden Stream enthält. Ein WebTransportReceiveStream ist ein ReadableStream. Er begegnet dir als eingehender unidirektionaler Stream über WebTransport.incomingUnidirectionalStreams oder als readable-Seite eines WebTransportBidirectionalStream.

Das Statistikobjekt (WebTransportReceiveStreamStats) enthält unter anderem:

bytesReceived: Anzahl der Bytes, die über das Netzwerk für diesen Stream angekommen sind. Mitgezählt werden nur Bytes bis zum ersten fehlenden Byte, also ohne Lücken.
bytesRead: Anzahl der Bytes, die die Anwendung bereits aus dem Stream gelesen hat.
timestamp: Zeitpunkt der Erfassung als DOMHighResTimeStamp. In älteren Fassungen der Spezifikation enthalten, in neueren entfernt.

Die Methode eignet sich für Fortschrittsanzeigen, Diagnose und Leistungsmessung. Die Differenz bytesReceived - bytesRead zeigt zum Beispiel, wie viele Daten im Puffer warten, weil die Anwendung sie noch nicht gelesen hat. Wird diese Zahl dauerhaft größer, verarbeitet die Anwendung die Daten zu langsam (Rückstau).

Rückgabewert

Typ

Promise<WebTransportReceiveStreamStats>

Beschreibung

Ein Promise, das mit einem Objekt erfüllt wird, das u. a. die Eigenschaften bytesReceived und bytesRead (jeweils number) enthält, in manchen Implementierungen zusätzlich timestamp.

Beispiele

Statistiken eines eingehenden unidirektionalen Streams abfragen

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

const streams = transport.incomingUnidirectionalStreams.getReader();
const { value: receiveStream, done } = await streams.read();

if (!done) {
  const reader = receiveStream.getReader();
  // Einen Datenblock lesen
  await reader.read();

  const stats = await receiveStream.getStats();
  console.log(`Empfangen: ${stats.bytesReceived} Bytes`);
  console.log(`Gelesen:   ${stats.bytesRead} Bytes`);
}

Empfangen: 4096 Bytes Gelesen: 4096 Bytes

Fortschritt beim Lesen eines bidirektionalen Streams protokollieren

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

const { readable, writable } = await transport.createBidirectionalStream();

// Anfrage an den Server senden
const writer = writable.getWriter();
await writer.write(new TextEncoder().encode('GET datei.bin'));
await writer.close();

const reader = readable.getReader();
while (true) {
  const { done } = await reader.read();
  if (done) break;
  const { bytesReceived, bytesRead } = await readable.getStats();
  console.log(`Fortschritt: ${bytesRead} gelesen, ${bytesReceived - bytesRead} gepuffert`);
}

Fortschritt: 16384 gelesen, 0 gepuffert Fortschritt: 32768 gelesen, 8192 gepuffert ...

Mit Feature-Erkennung absichern

const logStats = async (stream) => {
  if (typeof stream.getStats !== 'function') {
    console.warn('getStats() wird in diesem Browser nicht unterstützt');
    return null;
  }
  try {
    const stats = await stream.getStats();
    console.table(stats);
    return stats;
  } catch (err) {
    console.error('Statistiken nicht verfügbar:', err);
    return null;
  }
};

// Aufruf z. B. mit einem eingehenden Stream: await logStats(receiveStream);

// Wichtig · Fallstricke

Experimentell und kaum verfügbar: Nach aktuellem Stand unterstützt nur Firefox (ab etwa Version 115) diese Methode. Chromium-Browser unterstützen WebTransport selbst, aber nicht getStats() auf Streams. Deshalb vor dem Aufruf immer mit typeof stream.getStats === 'function' prüfen.
Die Spezifikation ändert sich noch: Die Eigenschaft timestamp wurde aus neueren Entwürfen entfernt. Verlasse dich nicht darauf, dass bestimmte Felder vorhanden sind.
Die Werte sind eine Momentaufnahme. Sie ändern sich laufend, solange Daten ankommen. Wenn du häufig abfragst (etwa bei jedem Lesevorgang), kostet das Rechenzeit. Für Fortschrittsanzeigen genügt oft ein Intervall.
bytesReceived zählt nur lückenlos empfangene Bytes. Pakete, die bei QUIC außer der Reihe ankommen, erscheinen erst, wenn die davor fehlenden Daten eingetroffen sind.
WebTransport funktioniert nur in sicheren Kontexten (HTTPS) und setzt einen HTTP/3-fähigen Server voraus. In Web Workern ist WebTransport ebenfalls nutzbar.

Siehe auch

WebTransportReceiveStream WebTransportSendStream.getStats() WebTransport.getStats() WebTransport.incomingUnidirectionalStreams WebTransportBidirectionalStream ReadableStream WebTransportSendStream.getWriter()