Add events for sniffing the WebSocket data

Add on_socket_raw_receive and on_socket_raw_send events for sniffing the
data being received and sent on the websocket. Useful for debugging and
logging websocket messages received and sent on the link to Discord's
servers.

2 files changed, 42 insertions, 0 deletions

diff --git a/discord/client.py b/discord/client.py
index 1df0c812..5d29de7e 100644
--- a/discord/client.py
+++ b/discord/client.py
@@ -93,7 +93,12 @@ class WebSocket(WebSocketBaseClient):
     def handshake_ok(self):
         pass
 
+    def send(self, payload, binary=False):
+        self.dispatch('socket_raw_send', payload, binary)
+        WebSocketBaseClient.send(self, payload, binary)
+
     def received_message(self, msg):
+        self.dispatch('socket_raw_receive', msg)
         response = json.loads(str(msg))
         log.debug('WebSocket Event: {}'.format(response))
         if response.get('op') != 0:
diff --git a/docs/api.rst b/docs/api.rst
index b8d91275..f60f2bea 100644
--- a/docs/api.rst
+++ b/docs/api.rst
@@ -102,6 +102,43 @@ to handle it, which defaults to log a traceback and ignore the exception.
 
     :param response: The received message response after gone through ``json.loads``.
 
+.. function:: on_socket_raw_receive(msg)
+
+    Called whenever a message is received from the websocket, before
+    it's processed. Unlike ``on_socket_response`` this event is always
+    dispatched when a message is received and the passed data is not
+    processed in any way.
+
+    This is only really useful for grabing the websocket stream and
+    debugging purposes.
+
+    :param msg: The message passed on from the ws4py library. Can be an
+        instance of either ws4py.messaging.TextMessage, or
+        ws4py.messaging.BinaryMessage.
+
+.. function:: on_socket_raw_send(payload, binary=False)
+
+    Called whenever a send operation is done on the websocket before the
+    message is sent. The passed parameter is the message that is to
+    sent to the websocket.
+
+    This is only really useful for grabing the websocket stream and
+    debugging purposes.
+
+    .. note::
+
+        If the ``payload`` parameter is mutable, and modified during the
+        execution of this event, then the actual data sent out on the
+        websocket will be mangled. This is especially true if
+        ``payload`` is a generator, as reading them modifies their
+        state.
+
+    :param payload: The message that is about to be passed on to the
+        ws4py library. It can be any of a string, a bytearray, an
+        instance of ws4py.message.Message and a generator.
+    :param bool binary: True if the message being sent out is marked as
+        binary.
+
 .. function:: on_message_delete(message)
               on_message_edit(before, after)