Signatur
Beschreibung
Die schreibgeschützte Eigenschaft receivedAlert eines RTCError-Objekts enthält die numerische AlertDescription eines fatalen DTLS-Alerts, den die Gegenstelle einer WebRTC-Verbindung geschickt hat. Die Codes stammen aus der TLS-Spezifikation (RFC 5246 bzw. RFC 8446). Beispiele sind 40 (handshake_failure), 42 (bad_certificate) und 80 (internal_error).
Einen Wert hat die Eigenschaft nur, wenn errorDetail den Wert "dtls-failure" hat und der Fehler durch einen empfangenen Alert ausgelöst wurde. In allen anderen Fällen ist sie null. Das Gegenstück ist sentAlert: Es enthält den Alert, den der lokale Peer gesendet hat.
In der Praxis bekommt man ein RTCError über die Eigenschaft error eines RTCErrorEvent. Dieses Ereignis wird z. B. beim error-Event eines RTCDtlsTransport oder eines RTCDataChannel ausgelöst. receivedAlert ist vor allem für Diagnose und Protokollierung nützlich. Damit lässt sich feststellen, ob die Gegenstelle etwa ein Zertifikat oder einen Fingerabdruck abgelehnt hat.
Rückgabewert
unsigned long) mit dem Code der DTLS-AlertDescription, die vom entfernten Peer empfangen wurde. null, wenn es kein empfangener DTLS-Alert war.Beispiele
DTLS-Fehler am Transport protokollieren
const pc = new RTCPeerConnection();
// Nach dem Aushandeln: DTLS-Transport des ersten Senders beobachten
pc.addEventListener('connectionstatechange', () => {
const transport = pc.getSenders()[0]?.transport;
if (!transport || transport.onerror) return;
transport.onerror = (event) => {
const { error } = event;
if (error.errorDetail === 'dtls-failure') {
if (error.receivedAlert !== null) {
console.warn(`Gegenstelle meldet DTLS-Alert ${error.receivedAlert}`);
} else if (error.sentAlert !== null) {
console.warn(`Lokal gesendeter DTLS-Alert ${error.sentAlert}`);
}
}
};
});Alert-Codes in lesbaren Text übersetzen
const DTLS_ALERTS = {
10: 'unexpected_message',
20: 'bad_record_mac',
40: 'handshake_failure',
42: 'bad_certificate',
45: 'certificate_expired',
48: 'unknown_ca',
70: 'protocol_version',
80: 'internal_error'
};
const describeReceivedAlert = (rtcError) =>
rtcError.receivedAlert === null
? 'kein empfangener Alert'
: DTLS_ALERTS[rtcError.receivedAlert] ?? `unbekannt (${rtcError.receivedAlert})`;
// Zum Testen ein RTCError manuell erzeugen
const err = new RTCError(
{ errorDetail: 'dtls-failure', receivedAlert: 40 },
'DTLS-Handshake fehlgeschlagen'
);
console.log(describeReceivedAlert(err));Fehler eines RTCDataChannel auswerten
const pc = new RTCPeerConnection();
const channel = pc.createDataChannel('chat');
channel.addEventListener('error', (event) => {
const { errorDetail, receivedAlert, message } = event.error;
console.error('DataChannel-Fehler:', errorDetail, message);
if (receivedAlert !== null) {
// z. B. an ein Monitoring-Backend senden
navigator.sendBeacon('/rtc-log', JSON.stringify({ errorDetail, receivedAlert }));
}
});// Wichtig · Fallstricke
- Nur bei
errorDetail === "dtls-failure"relevant. Bei allen anderen Fehlerarten ist der Wert immernull. Vergleiche daher mit!== nullund nicht mit einer bloßen Wahrheitsprüfung. Der Code0(close_notify) wäre falsy, ist aber kein fataler Alert. receivedAlertundsentAlertschließen sich praktisch aus: Entweder hat die Gegenstelle den Alert gesendet oder der lokale Peer.- Die Eigenschaft ist schreibgeschützt. Werte lassen sich nur über das Optionsobjekt des Konstruktors
new RTCError(init, message)setzen, was z. B. für Tests nützlich ist. - Kompatibilität:
RTCErrorwird von Chromium-Browsern und Safari unterstützt, von Firefox derzeit nicht. Prüfe vorher mit'RTCError' in window, ob die Schnittstelle verfügbar ist. - Der Alert-Code ist eine Diagnoseangabe. Er sagt nichts darüber aus, warum die Gegenstelle abgelehnt hat, etwa bei einem falschen Fingerabdruck in der SDP. Zeige Endnutzern keine rohen Codes an.