Modificar mensajes WebSocket

Edita, descarta o envía mensajes WebSocket (WS/WSS) sobre la marcha con onWebsocket en Scripting de Proxyman. Funciona en ambas direcciones, con mensajes de texto y binarios.

1. ¿Qué es?

Con la opción Modify WebSocket Messages, la función onWebsocket() de un script puede cambiar los mensajes WebSocket sobre la marcha. Con unas pocas líneas de JavaScript, puedes:

• Editar un mensaje, por ejemplo, cambiar un campo JSON o reemplazar texto.
• Descartar un mensaje, para que el otro extremo nunca lo vea.
• Enviar un mensaje nuevo al cliente o al servidor.
• Cerrar el WebSocket en ambos extremos.

Funciona con WS y WSS, en ambas direcciones: del cliente al servidor y del servidor al cliente.

información

Modify WebSocket Messages está disponible en Proxyman para macOS 26.2.0 o posterior y en Proxyman para Windows/Linux 26.1.0 o posterior. No está disponible en iOS.

El servidor envía un precio real de BTC, pero la app recibe $1. Un mensaje con una contraseña se descarta, y la app recibe una advertencia del script.

2. El problema

Las apps de chat, trading, juegos y paneles en vivo usan WebSocket para recibir datos en tiempo real. Probarlas es difícil:

• No puedes controlar el servidor. Envía datos reales. Para que envíe un caso límite, como un precio de 0 o un mensaje de error, habría que cambiar el código del servidor.
• Algunos casos son difíciles de reproducir. Un mensaje perdido, una respuesta extraña o una conexión caída rara vez ocurren cuando los necesitas.
• Otras herramientas no pueden modificar mensajes. Breakpoint y Map Local actúan sobre el handshake HTTP, no sobre los mensajes que vienen después. Sin esta opción, onWebsocket() solo lee los mensajes.

3. Beneficios

• Prueba todos los mensajes que tu app debe gestionar, sin cambiar el servidor.
• Simula una respuesta del servidor: responde a un mensaje del cliente con sendToClient(). El servidor nunca lo recibe.
• Oculta datos sensibles o bloquea eventos de analítica antes de que lleguen al servidor.
• Simula una conexión caída para comprobar cómo se reconecta tu app.
• Solo el WebSocket que coincide con la regla espera al script. El resto del tráfico sigue fluyendo.

4. ¿Cómo se usa?

1. Captura tu conexión WebSocket. Para wss://, activa SSL Proxying para el dominio, como con HTTPS.
2. Haz clic derecho en el flujo ws:// o wss:// -> Tools -> Scripting…. Proxyman crea una regla con la URL rellenada y un script con onWebsocket().
3. Deja marcada la casilla Request y marca Modify WebSocket Messages.
4. Escribe tu código de onWebsocket() y pulsa Save & Activate (⌘S, o Ctrl+S en Windows/Linux).
5. Vuelve a conectar el WebSocket. Proxyman lee la opción cuando el WebSocket se conecta, no en cada mensaje.

Marca Modify WebSocket Messages en el Script Editor

Este script convierte cada precio de BTC del servidor en $1 y descarta un mensaje del cliente que contiene una contraseña:

function onWebsocket(context, url, request, response, message) {
  // Only change text messages. Binary, ping, pong, and close messages pass through
  if (message.type !== "text") {
    return message;
  }

  const json = JSON.parse(message.data);

  // 1. Server -> client: every BTC price becomes $1
  if (message.from === "server" && json.type === "price") {
    json.price = 1;
    json.note = "edited by Proxyman";
    message.data = JSON.stringify(json);
    return message;
  }

  // 2. Client -> server: drop a message with a password, and warn the client
  if (message.from === "client" && json.text.includes("password")) {
    sendToClient(JSON.stringify({ type: "warning", text: "Proxyman blocked a password" }));
    return null;
  }

  // 3. Everything else: send it as it is
  return message;
}

La pestaña Websocket muestra los mensajes editados, los mensajes enviados por el script y los mensajes descartados:

Mensajes editados y descartados en la pestaña Websocket

Para una guía paso a paso con un servidor WebSocket local que puedes ejecutar tú mismo, lee Cómo modificar mensajes WebSocket con Scripting.

5. Qué devuelve onWebsocket()

Cuando la opción está activada, Proxyman retiene cada mensaje de texto y binario hasta que onWebsocket() devuelva un resultado. Lo que devuelvas determina qué pasa:

En onWebsocket()	Resultado
return message	Envía el mensaje, con tus cambios.
return null	Descarta el mensaje. El otro extremo nunca lo recibe.
Sin return	Envía el mensaje original.
abort()	Cierra el WebSocket en ambos extremos.
sendToClient(data) / sendToServer(data)	Envía un mensaje nuevo. Un String envía un mensaje de texto, y un Uint8Array envía un mensaje binario.

El objeto message tiene:

Campo	Valor
message.from	"client" o "server".
message.type	"text", "binary", "ping", "pong" o "close".
message.data	El texto del mensaje. Cámbialo para editar un mensaje de texto.
message.rawData	Los bytes de un mensaje binario, como Uint8Array. Asigna un nuevo Uint8Array para editar un mensaje binario.
message.closeCode	Un número, disponible solo en los mensajes de cierre, como 1000.

Consulta Scripting con WebSocket para ver los demás argumentos.

información

La opción viene desactivada por defecto. Cuando está desactivada, onWebsocket() funciona como antes: solo lee los mensajes y nunca los retrasa.

6. Plantillas

No hace falta escribir el script desde cero. En el Script Editor, haz clic en Templates y busca «websocket»:

• Log WebSocket Messages: muestra cada mensaje en el Console Log. Solo lee los mensajes.
• Modify JSON WebSocket Messages: cambia un campo de los mensajes JSON que envía el servidor.
• Replace Text in WebSocket Messages: busca y reemplaza texto en ambas direcciones.
• Drop WebSocket Messages: descarta los mensajes que coinciden con una expresión regular, por ejemplo, los eventos de analítica.
• Reply to a WebSocket Message: responde a un mensaje del cliente con sendToClient(). El servidor nunca lo recibe.
• Simulate a WebSocket Disconnect: cierra el WebSocket después de unos cuantos mensajes.

Haz clic en Replace para usar una plantilla. Proxyman también marca las casillas que necesita, incluida Modify WebSocket Messages.

Plantillas de WebSocket en el Script Editor

Hay más ejemplos en la página Snippet Code.

7. Cosas que conviene saber

• Puedes editar y descartar mensajes de texto y binarios. Los mensajes ping, pong y close siempre se envían: onWebsocket() puede leerlos, pero se ignora lo que devuelve.
• Un mensaje conserva su tipo: no puedes convertir un mensaje de texto en uno binario.
• Si tu script lanza un error o no devuelve un resultado en 30 segundos, Proxyman envía el mensaje original y muestra el error en el Console Log.
• El código fuera de onWebsocket() se ejecuta una vez por conexión, así que un contador al inicio del script cuenta los mensajes de cada conexión.
• Los mensajes enviados con sendToClient() y sendToServer() no vuelven a ejecutar onWebsocket(), así que un script que responde no puede entrar en un bucle infinito.
• Cuando varios scripts con esta opción coinciden con el mismo WebSocket, se ejecutan en orden: cada uno recibe lo que devolvió el anterior. Un mensaje descartado no llega a los siguientes scripts.
• Un mensaje de más de 16 MB se envía tal cual, sin pasar por el script.
• Se admiten funciones async, así que puedes usar await y $http en onWebsocket().
• Los agentes de IA pueden crear la misma regla con Proxyman MCP: create_scripting_rule acepta modify_websocket_messages: true.

8. Solución de problemas

Los mensajes no cambian

• Marca Modify WebSocket Messages y, luego, pulsa Save & Activate (⌘S, o Ctrl+S en Windows/Linux).
• Vuelve a conectar el WebSocket. La opción se lee cuando el WebSocket se conecta.
• Deja marcada Request o Response. Una regla con ambas desmarcadas no se ejecuta en absoluto, incluido onWebsocket().
• Devuelve message después de cambiarlo. Sin un return, Proxyman envía el mensaje original.
• Abre el Console Log en el Script Editor y busca errores.

No veo mi WebSocket en Proxyman

Sigue la guía de WebSocket para tu plataforma. Muchas apps y librerías omiten el proxy para localhost.