WebSocket.protocol — Eigenschaft · JavaScript-Referenz

Signatur

WebSocket.protocol

Beschreibung

Beim Erzeugen eines WebSocket kann der Client im zweiten Konstruktor-Argument ein oder mehrere Subprotokolle angeben, z. B. "graphql-transport-ws", "mqtt" oder eine eigene Versionskennung wie "chat.v2". Diese werden im HTTP-Header Sec-WebSocket-Protocol an den Server geschickt. Der Server wählt davon höchstens eines aus und schickt es in seiner Handshake-Antwort zurück.

protocol enthält genau dieses vom Server bestätigte Subprotokoll. Solange die Verbindung noch nicht offen ist (readyState === WebSocket.CONNECTING), ist der Wert ein leerer String. Nach dem open-Ereignis steht der endgültige Wert fest. Hat der Server kein Subprotokoll gewählt, bleibt er ebenfalls leer.

Die Eigenschaft ist praktisch für Versionsverhandlung und Protokollwahl: Der Client bietet mehrere Varianten an und passt anschließend das Nachrichtenformat oder die Verarbeitungslogik an das an, was der Server tatsächlich unterstützt.

Rückgabewert

Typ

string

Beschreibung

Name des vom Server gewählten Subprotokolls oder ein leerer String "", wenn noch keine Verbindung besteht oder kein Subprotokoll ausgehandelt wurde.

Beispiele

Ausgehandeltes Subprotokoll nach dem Verbindungsaufbau auslesen

const socket = new WebSocket('wss://echo.example.com/socket', ['chat.v2', 'chat.v1']);

// Vor dem Handshake noch leer
console.log(`Vor open: "${socket.protocol}"`);

socket.addEventListener('open', () => {
  console.log(`Server hat gewählt: ${socket.protocol}`);
});

Vor open: "" Server hat gewählt: chat.v2

Nachrichtenformat je nach Protokollversion wählen

const socket = new WebSocket('wss://api.example.com/live', ['chat.v2', 'chat.v1']);

const encoders = {
  'chat.v2': (text) => JSON.stringify({ type: 'message', payload: { text } }),
  'chat.v1': (text) => text // v1 erwartet reinen Text
};

socket.addEventListener('open', () => {
  const encode = encoders[socket.protocol];

  if (!encode) {
    console.warn('Kein unterstütztes Subprotokoll ausgehandelt – Verbindung wird geschlossen.');
    socket.close(1002, 'Unsupported protocol');
    return;
  }

  socket.send(encode('Hallo zusammen!'));
  console.log(`Gesendet über ${socket.protocol}`);
});

Gesendet über chat.v2

GraphQL-over-WebSocket: Protokoll prüfen

const connectGraphQL = (url) => new Promise((resolve, reject) => {
  const socket = new WebSocket(url, 'graphql-transport-ws');

  socket.addEventListener('open', () => {
    if (socket.protocol !== 'graphql-transport-ws') {
      socket.close();
      reject(new Error(`Unerwartetes Protokoll: "${socket.protocol}"`));
      return;
    }
    socket.send(JSON.stringify({ type: 'connection_init' }));
    resolve(socket);
  });

  socket.addEventListener('error', () => reject(new Error('Verbindung fehlgeschlagen')));
});

const run = async () => {
  try {
    const socket = await connectGraphQL('wss://graphql.example.com/graphql');
    console.log('Verbunden mit', socket.protocol);
  } catch (err) {
    console.error(err.message);
  }
};

run();

Verbunden mit graphql-transport-ws

// Wichtig · Fallstricke

Erst nach open aussagekräftig: Vor Abschluss des Handshakes ist protocol immer "". Prüfungen gehören daher in den open-Handler.
Schreibgeschützt: Eine Zuweisung wie socket.protocol = "x" wird ignoriert (im Strict Mode TypeError). Subprotokolle lassen sich nur über den Konstruktor anbieten.
Server muss mitspielen: Schickt der Client Subprotokolle, der Server antwortet aber mit einem Wert, der nicht angeboten wurde, bricht der Browser die Verbindung ab (error, dann close). Antwortet der Server ganz ohne Sec-WebSocket-Protocol, lassen manche Browser die Verbindung mit leerem protocol zu – deshalb den Wert immer selbst prüfen.
Gültige Namen: Subprotokoll-Namen dürfen nicht doppelt vorkommen und müssen gültige HTTP-Tokens sein (keine Leerzeichen, Kommas usw.). Sonst wirft der Konstruktor einen SyntaxError.
Keine Sicherheitsgrenze: Das Subprotokoll ist kein Authentifizierungsmechanismus. Tokens im Sec-WebSocket-Protocol-Header zu schmuggeln ist zwar verbreitet, landet aber leicht in Logs von Proxys und Servern.
Wird in allen modernen Browsern sowie in Node.js ab Version 22 (globales WebSocket) unterstützt.

Siehe auch

WebSocket WebSocket.extensions WebSocket.readyState WebSocket.prototype.close() SVGAElement.protocol