Signatur
Beschreibung
Die schreibgeschützte Eigenschaft bufferedAmount einer WebSocket-Instanz gibt an, wie viele Bytes Anwendungsdaten durch Aufrufe von send() gepuffert sind und noch nicht über das Netzwerk verschickt wurden. Sobald die Daten gesendet sind, sinkt der Wert wieder. Wird die Verbindung geschlossen, wird der Wert nicht auf 0 zurückgesetzt. Ruft man send() nach dem Schließen weiter auf, steigt der Wert trotzdem weiter an.
Die Eigenschaft ist das wichtigste Werkzeug für eine einfache Flusskontrolle auf der Sendeseite: send() blockiert nie und liefert keinen Rückgabewert. Wer große Datenmengen schnell hintereinander verschickt (etwa beim Hochladen von Dateien in Blöcken, bei Echtzeit-Telemetrie oder beim Streaming), kann den Pufferspeicher des Browsers deshalb unbemerkt volllaufen lassen. Prüft man bufferedAmount vor jedem Senden, lässt sich das Tempo an die tatsächliche Übertragungsrate anpassen.
Typische Muster sind: Daten nur senden, wenn der Puffer unter einem Schwellenwert liegt; veraltete Aktualisierungen (z. B. Mauspositionen) verwerfen, solange noch etwas im Puffer liegt; oder das Senden per Polling mit setTimeout bzw. requestAnimationFrame verzögern, bis der Puffer leer ist.
Rückgabewert
unsigned long) mit der Anzahl der gepufferten, noch nicht gesendeten Bytes. Protokoll-Overhead wie Framing oder Kompression wird dabei nicht mitgezählt.Beispiele
Pufferstand nach dem Senden auslesen
const ws = new WebSocket('wss://echo.websocket.org');
ws.addEventListener('open', () => {
console.log('Vorher:', ws.bufferedAmount);
ws.send('x'.repeat(1_000_000)); // 1 MB Text
console.log('Direkt danach:', ws.bufferedAmount);
setTimeout(() => {
console.log('Nach 1 s:', ws.bufferedAmount);
}, 1000);
});Veraltete Echtzeit-Updates verwerfen
const ws = new WebSocket('wss://example.com/cursor');
// Mausposition nur senden, wenn der Puffer leer ist –
// sonst wäre das Update beim Eintreffen ohnehin veraltet.
document.addEventListener('mousemove', (event) => {
if (ws.readyState !== WebSocket.OPEN) return;
if (ws.bufferedAmount === 0) {
ws.send(JSON.stringify({ x: event.clientX, y: event.clientY }));
}
});Datei blockweise mit Flusskontrolle hochladen
const HIGH_WATER_MARK = 1024 * 1024; // 1 MB
const CHUNK_SIZE = 64 * 1024; // 64 KB
const waitForDrain = (ws) =>
new Promise((resolve) => {
const check = () => {
if (ws.bufferedAmount < HIGH_WATER_MARK) resolve();
else setTimeout(check, 50);
};
check();
});
const uploadFile = async (ws, file) => {
for (let offset = 0; offset < file.size; offset += CHUNK_SIZE) {
await waitForDrain(ws);
const chunk = await file.slice(offset, offset + CHUNK_SIZE).arrayBuffer();
ws.send(chunk);
console.log(`Gesendet: ${Math.min(offset + CHUNK_SIZE, file.size)} / ${file.size}`);
}
};
// Nutzung:
// const ws = new WebSocket('wss://example.com/upload');
// ws.binaryType = 'arraybuffer';
// ws.onopen = () => uploadFile(ws, input.files[0]);// Wichtig · Fallstricke
- Kein Ereignis beim Leeren: Es gibt kein Event, das meldet, wann der Puffer leer ist. Man muss den Wert selbst abfragen (Polling). Wer echten Gegendruck (Backpressure) braucht, kann die neuere
WebSocketStream-API nutzen. Sie ist aber bislang nur in Chromium-Browsern verfügbar. - Kein Zurücksetzen beim Schließen: Nach
close()oder einem Verbindungsabbruch bleibt der Wert bestehen. Weiteresend()-Aufrufe erhöhen ihn sogar, obwohl nichts mehr gesendet wird. Prüfen Sie deshalb immer zusätzlichreadyState === WebSocket.OPEN. - Nur Nutzdaten: Gezählt werden nur die Bytes der Anwendungsdaten, also UTF-8-kodierte Zeichenketten bzw. Binärdaten. Framing, TLS und Kompression (
permessage-deflate) werden nicht berücksichtigt. - Überlauf: Wird der interne Puffer zu groß, kann der Browser die Verbindung schließen. Bei großen Datenmengen deshalb immer einen Schwellenwert verwenden.
- Die Eigenschaft ist schreibgeschützt; Zuweisungen werden ignoriert, im Strict Mode ohne Fehler. Sie wird von allen modernen Browsern unterstützt, auch in Web Workern.