8. Error Handling (Gestione degli errori)

8.1 Handling Errors in UTF-8-Encoded Data (Gestione degli errori nei dati codificati UTF-8)

Quando si riceve un frame Text (Opcode 0x1), i dati del payload devono essere testo codificato UTF-8 valido.

Validazione UTF-8

Le implementazioni DEVONO validare che i dati di testo ricevuti siano UTF-8 valido.

function isValidUTF8(buffer) {
  try {
    // Node.js genera un errore su UTF-8 non valido
    const str = buffer.toString('utf8');
    // Verificare la conversione di andata e ritorno
    return Buffer.from(str, 'utf8').equals(buffer);
  } catch (e) {
    return false;
  }
}

ws.on('message', (data, isBinary) => {
  if (!isBinary && !isValidUTF8(data)) {
    // Codice di chiusura 1007 = Dati di payload del frame non validi
    ws.close(1007, 'Invalid UTF-8 in text frame');
  }
});

Processo di gestione degli errori

Quando viene rilevato UTF-8 non valido:

1. Interrompere l'elaborazione del messaggio
2. Inviare frame Close con codice di stato 1007
3. Chiudere la connessione

Altri errori comuni

Violazioni del protocollo

Tipo di errore	Codice di chiusura	Gestione
Frame client non mascherato ricevuto	1002	Chiudere immediatamente la connessione
Frame server mascherato ricevuto	1002	Chiudere immediatamente la connessione
Opcode non valido	1002	Chiudere immediatamente la connessione
Frame di controllo frammentato	1002	Chiudere immediatamente la connessione
Frame di controllo superiore a 125 byte	1002	Chiudere immediatamente la connessione
UTF-8 non valido	1007	Inviare frame Close poi chiudere
Messaggio troppo grande	1009	Inviare frame Close poi chiudere

Best practice per la gestione degli errori

ws.on('error', (error) => {
  console.error('Errore WebSocket:', error);
  // Registrare l'errore
  // Notificare il sistema di monitoraggio
});

ws.on('close', (code, reason) => {
  if (code !== 1000 && code !== 1001) {
    console.error(`Chiusura anomala: ${code} - ${reason}`);
    // Implementare la logica di riconnessione
    setTimeout(() => reconnect(), 5000);
  }
});

Link di riferimento

• Capitolo precedente: 7. Closing the Connection (Chiusura della connessione)
• Capitolo successivo: 9. Extensions (Estensioni)

---