websocket: add event documentation

docs/scripting/events.rst

@@ -158,12 +158,15 @@ HTTP Events
 WebSocket Events
 -----------------
 
+These events are called only after a connection made an HTTP upgrade with
+"101 Switching Protocols". No further HTTP-related events after the handshake
+are issued, only new WebSocket messages are called.
+
 .. list-table::
     :widths: 40 60
     :header-rows: 0
 
     *   - .. py:function:: websocket_handshake(flow)
-
         - Called when a client wants to establish a WebSocket connection. The
           WebSocket-specific headers can be manipulated to manipulate the
           handshake. The ``flow`` object is guaranteed to have a non-None
@@ -173,6 +176,36 @@ WebSocket Events
             The flow containing the HTTP WebSocket handshake request. The
             object is guaranteed to have a non-None ``request`` attribute.
 
+    *   - .. py:function:: websocket_start(flow)
+        - Called when WebSocket connection is established after a successful
+          handshake.
+
+          *flow*
+            A ``models.WebSocketFlow`` object.
+
+    *   - .. py:function:: websocket_message(flow)
+
+        - Called when a WebSocket message is received from the client or server. The
+          sender and receiver are identifiable. The most recent message will be
+          ``flow.messages[-1]``. The message is user-modifiable. Currently there are
+          two types of messages, corresponding to the BINARY and TEXT frame types.
+
+          *flow*
+            A ``models.WebSocketFlow`` object.
+
+    *   - .. py:function:: websocket_end(flow)
+        - Called when WebSocket connection ends.
+
+          *flow*
+            A ``models.WebSocketFlow`` object.
+
+    *   - .. py:function:: websocket_error(flow)
+        - Called when a WebSocket error occurs - e.g. the connection closing
+          unexpectedly.
+
+          *flow*
+            A ``models.WebSocketFlow`` object.
+
 
 TCP Events
 ----------
@@ -185,6 +218,22 @@ connections.
     :widths: 40 60
     :header-rows: 0
 
+
+    *   - .. py:function:: tcp_start(flow)
+        - Called when TCP streaming starts.
+
+          *flow*
+            A ``models.TCPFlow`` object.
+
+    *   - .. py:function:: tcp_message(flow)
+
+        - Called when a TCP payload is received from the client or server. The
+          sender and receiver are identifiable. The most recent message will be
+          ``flow.messages[-1]``. The message is user-modifiable.
+
+          *flow*
+            A ``models.TCPFlow`` object.
+
     *   - .. py:function:: tcp_end(flow)
         - Called when TCP streaming ends.
 
@@ -197,18 +246,3 @@ connections.
 
           *flow*
             A ``models.TCPFlow`` object.
-
-    *   - .. py:function:: tcp_message(flow)
-
-        - Called a TCP payload is received from the client or server. The
-          sender and receiver are identifiable. The most recent message will be
-          ``flow.messages[-1]``. The message is user-modifiable.
-
-          *flow*
-            A ``models.TCPFlow`` object.
-
-    *   - .. py:function:: tcp_start(flow)
-        - Called when TCP streaming starts.
-
-          *flow*
-            A ``models.TCPFlow`` object.