CloseEvent.wasClean — Eigenschaft · JavaScript-Referenz

Signatur

CloseEvent.wasClean

Beschreibung

Die schreibgeschützte Eigenschaft wasClean der Schnittstelle CloseEvent liefert true, wenn die Verbindung ordnungsgemäß geschlossen wurde, also Client und Server den WebSocket-Closing-Handshake vollständig ausgetauscht haben. Bei false wurde die Verbindung abrupt unterbrochen – etwa durch Netzwerkabbruch, Serverabsturz, Timeout oder einen fehlgeschlagenen Verbindungsaufbau.

In der Praxis nutzt man wasClean im close-Ereignis eines WebSocket, um zu entscheiden, ob eine automatische Wiederverbindung sinnvoll ist oder ob die Sitzung absichtlich beendet wurde. Zusammen mit CloseEvent.code und CloseEvent.reason ergibt sich ein vollständiges Bild des Verbindungsendes.

Wichtig: wasClean sagt nur etwas über den Ablauf des Schließens aus, nicht darüber, ob der Grund „gut“ war. Auch ein Server, der sauber mit Code 1008 (Richtlinienverstoß) schließt, erzeugt wasClean === true. Bei unsauberem Abbruch ist der Code typischerweise 1006.

Beispiele

Verbindungsende auswerten

const socket = new WebSocket('wss://echo.websocket.org');

socket.addEventListener('close', (event) => {
  if (event.wasClean) {
    console.log(`Sauber geschlossen: Code ${event.code}, Grund: ${event.reason || '–'}`);
  } else {
    console.warn(`Verbindung abgebrochen (Code ${event.code})`);
  }
});

// Nach 2 Sekunden sauber beenden
setTimeout(() => socket.close(1000, 'Fertig'), 2000);

Sauber geschlossen: Code 1000, Grund: Fertig

Automatische Wiederverbindung nur bei Abbruch

const connect = (url, attempt = 0) => {
  const ws = new WebSocket(url);

  ws.onopen = () => {
    attempt = 0;
    console.log('Verbunden');
  };

  ws.onclose = (event) => {
    if (event.wasClean) {
      console.log('Sitzung regulär beendet – keine Wiederverbindung.');
      return;
    }
    // Exponentielles Backoff, max. 30 s
    const delay = Math.min(30000, 1000 * 2 ** attempt);
    console.warn(`Abbruch (Code ${event.code}), neuer Versuch in ${delay} ms`);
    setTimeout(() => connect(url, attempt + 1), delay);
  };

  return ws;
};

connect('wss://example.com/live');

Abbruch (Code 1006), neuer Versuch in 1000 ms

CloseEvent manuell erzeugen (z. B. für Tests)

const evt = new CloseEvent('close', { wasClean: false, code: 1006, reason: '' });
console.log(evt.wasClean, evt.code);

// Standardwert, wenn nicht angegeben
console.log(new CloseEvent('close').wasClean);

false 1006 false

// Wichtig · Fallstricke

Schreibgeschützt: Zuweisungen wie event.wasClean = true werden ignoriert (im Strict Mode TypeError). Der Wert lässt sich nur über das Init-Objekt von new CloseEvent() setzen; Standard ist false.
Nicht mit Erfolg verwechseln: Ein sauber geschlossener Kanal kann trotzdem einen Fehlergrund haben (z. B. Code 1008 oder 1011). Für die Entscheidungslogik immer auch code prüfen.
Fehlgeschlagener Verbindungsaufbau: Scheitert der Handshake (falsche URL, CORS/Origin-Ablehnung, TLS-Fehler), feuert zuerst error, danach close mit wasClean === false und Code 1006. Details zum Fehler gibt der Browser aus Sicherheitsgründen nicht preis.
Kompatibilität: In allen modernen Browsern sowie in Node.js ab Version 22 (globales WebSocket/CloseEvent) verfügbar.

Siehe auch

CloseEvent.reason CloseEvent.code MouseEvent.screenX MouseEvent.screenY BlobEvent.data