RTCError.sctpCauseCode — Eigenschaft · JavaScript-Referenz

Signatur

RTCError.sctpCauseCode

Beschreibung

Die schreibgeschützte Eigenschaft sctpCauseCode des Interfaces RTCError gibt den numerischen SCTP-Ursachencode zurück. Er erklärt, warum die SCTP-Verhandlung bzw. die SCTP-Assoziation fehlgeschlagen ist. WebRTC-Datenkanäle (RTCDataChannel) laufen über SCTP (über DTLS). Scheitert dort etwas auf Protokollebene, bekommt der Fehler diesen Code aus dem SCTP-Standard.

Einen Wert hat die Eigenschaft nur, wenn RTCError.errorDetail den Wert "sctp-failure" hat. Bei allen anderen Fehlerarten, etwa "dtls-failure" oder "data-channel-failure", ist sie null. Die Codes stammen aus RFC 4960, Abschnitt 3.3.10 und späteren Erweiterungen. Beispiele sind 1 (ungültige Stream-ID), 12 (vom Nutzer ausgelöster Abbruch, „User Initiated Abort“) und 13 (Protokollverletzung).

Meistens liest man die Eigenschaft im error-Event eines RTCDataChannel aus. Das Event ist ein RTCErrorEvent, und seine Eigenschaft error enthält das RTCError-Objekt. Nützlich ist der Code für Diagnose, Logging und Telemetrie, zum Beispiel um einen regulären Abbruch durch die Gegenstelle von einem echten Protokollproblem zu unterscheiden.

Rückgabewert

Typ

number | null

Beschreibung

Ein vorzeichenloser Ganzzahlwert mit dem SCTP-Ursachencode, wenn errorDetail === "sctp-failure" gilt, sonst null.

Beispiele

SCTP-Fehler im error-Event eines Datenkanals auswerten

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

channel.addEventListener("error", (event) => {
  const err = event.error; // RTCError
  if (err.errorDetail === "sctp-failure") {
    console.warn(`SCTP-Fehler, Ursachencode: ${err.sctpCauseCode}`);
  } else {
    console.warn(`Anderer Fehler: ${err.errorDetail}`);
  }
});

SCTP-Fehler, Ursachencode: 12 // wenn die Gegenstelle die Assoziation abbricht

Ursachencode in lesbaren Text umwandeln

const SCTP_CAUSES = {
  1: "Ungültige Stream-ID",
  2: "Fehlender Pflichtparameter",
  3: "Veraltetes Cookie",
  4: "Keine Ressourcen mehr",
  5: "Adresse nicht auflösbar",
  6: "Unbekannter Chunk-Typ",
  7: "Ungültiger Pflichtparameter",
  8: "Unbekannte Parameter",
  9: "Keine Nutzdaten",
  10: "Cookie beim Herunterfahren empfangen",
  11: "Neustart der Assoziation mit neuen Adressen",
  12: "Vom Nutzer ausgelöster Abbruch",
  13: "Protokollverletzung"
};

const describeSctpError = (err) =>
  err.sctpCauseCode == null
    ? "Kein SCTP-Fehler"
    : SCTP_CAUSES[err.sctpCauseCode] ?? `Unbekannter Code ${err.sctpCauseCode}`;

channel.onerror = (event) => {
  console.log(describeSctpError(event.error));
};

Vom Nutzer ausgelöster Abbruch

RTCError zum Testen selbst erzeugen

if ("RTCError" in window) {
  const err = new RTCError(
    { errorDetail: "sctp-failure", sctpCauseCode: 13 },
    "Simulierte Protokollverletzung"
  );
  console.log(err.name, err.errorDetail, err.sctpCauseCode);

  const other = new RTCError({ errorDetail: "dtls-failure" });
  console.log(other.sctpCauseCode);
} else {
  console.log("RTCError wird nicht unterstützt");
}

OperationError sctp-failure 13 null

// Wichtig · Fallstricke

Nur bei "sctp-failure" gesetzt: Bei allen anderen Werten von errorDetail ist die Eigenschaft null. Prüfe sie deshalb mit == null bzw. ??. Eine Prüfung wie if (err.sctpCauseCode) reicht nicht, weil sie null und 0 gleich behandelt.
Browser-Kompatibilität: RTCError und RTCErrorEvent gibt es in Chromium-Browsern (Chrome, Edge, Opera) und in neueren Safari-Versionen. Firefox unterstützt sie derzeit nicht. Dort ist das error-Event von Datenkanälen ein allgemeines Event ohne error-Eigenschaft. Mache vorher eine Feature-Erkennung mit "RTCError" in window oder event.error?.sctpCauseCode.
Der Code 12 (User Initiated Abort) steht oft für ein normales Schließen oder Neuladen auf der Gegenstelle. Er muss also kein echter Fehler sein. Werte ihn in der Telemetrie deshalb getrennt aus.
Die Eigenschaft ist schreibgeschützt. Zu Testzwecken kannst du den Wert nur über das Optionsobjekt des Konstruktors new RTCError() setzen.

Siehe auch

RTCError RTCError.errorDetail RTCErrorEvent RTCDataChannel RTCSctpTransport RTCError.sdpLineNumber