RTCError.sentAlert — Eigenschaft · JavaScript-Referenz

Signatur

RTCError.sentAlert

Beschreibung

Die Eigenschaft sentAlert des Interfaces RTCError enthält die numerische Kennung eines DTLS-Alerts, den der lokale Browser während des Verbindungsaufbaus oder -betriebs an den entfernten Peer gesendet hat. DTLS (Datagram Transport Layer Security) sichert in WebRTC sowohl die Medienschlüssel (DTLS-SRTP) als auch Datenkanäle (SCTP über DTLS) ab.

Ein Wert ist nur gesetzt, wenn RTCError.errorDetail den Wert "dtls-failure" hat und der Fehler von der lokalen Seite ausging. Hat stattdessen der entfernte Peer einen Alert geschickt, steht die Nummer in RTCError.receivedAlert. In allen anderen Fällen ist sentAlert null.

Die Alert-Nummern stammen aus dem TLS-Alert-Register (RFC 5246 / RFC 8446), zum Beispiel 40 (handshake_failure), 42 (bad_certificate), 48 (unknown_ca), 70 (protocol_version) oder 80 (internal_error). Nützlich ist die Eigenschaft vor allem für Diagnose, Protokollierung und Telemetrie, wenn eine WebRTC-Verbindung schon beim DTLS-Handshake scheitert, etwa wegen inkompatibler Cipher-Suites oder ungültiger Zertifikate.

An ein RTCError-Objekt kommt man meist über das error-Ereignis eines RTCDtlsTransport oder RTCDataChannel. Dort ist es als event.error im RTCErrorEvent enthalten.

Rückgabewert

Typ

number | null

Beschreibung

Eine vorzeichenlose Ganzzahl (unsigned long) mit der gesendeten DTLS-Alert-Nummer, oder null, wenn kein ausgehender DTLS-Alert zum Fehler gehört.

Beispiele

DTLS-Fehler am Transport protokollieren

const pc = new RTCPeerConnection();
pc.addTransceiver('audio');

// Nach setLocalDescription ist der DTLS-Transport verfügbar
await pc.setLocalDescription();
const dtls = pc.getSenders()[0].transport;

dtls.addEventListener('error', (event) => {
  const err = event.error; // RTCError
  if (err.errorDetail === 'dtls-failure') {
    if (err.sentAlert !== null) {
      console.warn(`Lokal gesendeter DTLS-Alert: ${err.sentAlert}`);
    } else if (err.receivedAlert !== null) {
      console.warn(`Vom Peer empfangener DTLS-Alert: ${err.receivedAlert}`);
    }
  }
});

Lokal gesendeter DTLS-Alert: 42

Alert-Nummer in lesbaren Namen übersetzen

const TLS_ALERTS = {
  0: 'close_notify',
  10: 'unexpected_message',
  20: 'bad_record_mac',
  40: 'handshake_failure',
  42: 'bad_certificate',
  45: 'certificate_expired',
  48: 'unknown_ca',
  50: 'decode_error',
  51: 'decrypt_error',
  70: 'protocol_version',
  80: 'internal_error'
};

const describeSentAlert = (rtcError) => {
  const code = rtcError.sentAlert;
  if (code === null) return 'kein ausgehender DTLS-Alert';
  return `${code} (${TLS_ALERTS[code] ?? 'unbekannt'})`;
};

// Beispiel mit einem simulierten Fehlerobjekt
console.log(describeSentAlert({ sentAlert: 40 }));
console.log(describeSentAlert({ sentAlert: null }));

40 (handshake_failure) kein ausgehender DTLS-Alert

Fehler eines Datenkanals an die Telemetrie senden

const pc = new RTCPeerConnection();
const channel = pc.createDataChannel('chat');

channel.onerror = (event) => {
  const { errorDetail, sentAlert, receivedAlert, message } = event.error;
  navigator.sendBeacon('/telemetry/webrtc', JSON.stringify({
    errorDetail,
    sentAlert,      // null, falls nicht zutreffend
    receivedAlert,
    message,
    zeit: new Date().toISOString()
  }));
};

// Wichtig · Fallstricke

Nur bei errorDetail === "dtls-failure" sinnvoll: Bei allen anderen Fehlerarten (z. B. "sctp-failure", "data-channel-failure", "fingerprint-failure") ist sentAlert null. Vergleiche immer strikt mit null, nicht über Truthiness: Der Alert 0 (close_notify) ist zwar ein gültiger Wert, würde bei if (err.sentAlert) aber übersehen.
sentAlert und receivedAlert auseinanderhalten: sentAlert bedeutet, dass die lokale Seite den Fehler erkannt und gemeldet hat. Die Ursache liegt dann oft beim Gegenüber, zum Beispiel ein ungültiges Zertifikat oder eine nicht passende Cipher-Suite.
Schreibgeschützt: Eine Zuweisung wird still ignoriert bzw. löst im Strict Mode einen TypeError aus.
Browser-Kompatibilität: RTCError gibt es in Chromium-Browsern und in neueren Safari-Versionen. Firefox unterstützt es derzeit nicht. Prüfe daher per Feature-Erkennung ('RTCError' in window) und rechne damit, dass ein DTLS-Fehler je nach Browser nur über connectionState === "failed" sichtbar wird.
Datenschutz: Alert-Nummern verraten keine sensiblen Nutzerdaten und sind daher gut für Telemetrie geeignet. Sende aber nicht ungeprüft das komplette Fehlerobjekt samt SDP an Dritte.

Siehe auch

RTCError RTCError.receivedAlert RTCError.errorDetail RTCErrorEvent RTCDtlsTransport