improve scripting docs

6 files changed, 113 insertions, 96 deletions

diff --git a/examples/addons/events-http-specific.py b/examples/addons/events-http-specific.py
new file mode 100644
index 00000000..37d9f91a
--- /dev/null
+++ b/examples/addons/events-http-specific.py
@@ -0,0 +1,42 @@
+import mitmproxy.http
+
+
+class Events:
+    # HTTP lifecycle
+    def http_connect(self, flow: mitmproxy.http.HTTPFlow):
+        """
+            An HTTP CONNECT request was received. Setting a non 2xx response on
+            the flow will return the response to the client abort the
+            connection. CONNECT requests and responses do not generate the usual
+            HTTP handler events. CONNECT requests are only valid in regular and
+            upstream proxy modes.
+        """
+
+    def requestheaders(self, flow: mitmproxy.http.HTTPFlow):
+        """
+            HTTP request headers were successfully read. At this point, the body
+            is empty.
+        """
+
+    def request(self, flow: mitmproxy.http.HTTPFlow):
+        """
+            The full HTTP request has been read.
+        """
+
+    def responseheaders(self, flow: mitmproxy.http.HTTPFlow):
+        """
+            HTTP response headers were successfully read. At this point, the body
+            is empty.
+        """
+
+    def response(self, flow: mitmproxy.http.HTTPFlow):
+        """
+            The full HTTP response has been read.
+        """
+
+    def error(self, flow: mitmproxy.http.HTTPFlow):
+        """
+            An HTTP error has occurred, e.g. invalid server responses, or
+            interrupted connections. This is distinct from a valid server HTTP
+            error response, which is simply a response with an HTTP error code.
+        """
diff --git a/examples/addons/events-tcp-specific.py b/examples/addons/events-tcp-specific.py
new file mode 100644
index 00000000..d150d0f9
--- /dev/null
+++ b/examples/addons/events-tcp-specific.py
@@ -0,0 +1,25 @@
+import mitmproxy.tcp
+
+
+class Events:
+    # TCP lifecycle
+    def tcp_start(self, flow: mitmproxy.tcp.TCPFlow):
+        """
+            A TCP connection has started.
+        """
+
+    def tcp_message(self, flow: mitmproxy.tcp.TCPFlow):
+        """
+            A TCP connection has received a message. The most recent message
+            will be flow.messages[-1]. The message is user-modifiable.
+        """
+
+    def tcp_error(self, flow: mitmproxy.tcp.TCPFlow):
+        """
+            A TCP error has occurred.
+        """
+
+    def tcp_end(self, flow: mitmproxy.tcp.TCPFlow):
+        """
+            A TCP connection has ended.
+        """
diff --git a/examples/addons/events-websocket-specific.py b/examples/addons/events-websocket-specific.py
new file mode 100644
index 00000000..60069fdb
--- /dev/null
+++ b/examples/addons/events-websocket-specific.py
@@ -0,0 +1,36 @@
+import mitmproxy.http
+import mitmproxy.websocket
+
+
+class Events:
+    # Websocket lifecycle
+    def websocket_handshake(self, flow: mitmproxy.http.HTTPFlow):
+        """
+            Called when a client wants to establish a WebSocket connection. The
+            WebSocket-specific headers can be manipulated to alter the
+            handshake. The flow object is guaranteed to have a non-None request
+            attribute.
+        """
+
+    def websocket_start(self, flow: mitmproxy.websocket.WebSocketFlow):
+        """
+            A websocket connection has commenced.
+        """
+
+    def websocket_message(self, flow: mitmproxy.websocket.WebSocketFlow):
+        """
+            Called when a WebSocket message is received from the client or
+            server. 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.
+        """
+
+    def websocket_error(self, flow: mitmproxy.websocket.WebSocketFlow):
+        """
+            A websocket connection has had an error.
+        """
+
+    def websocket_end(self, flow: mitmproxy.websocket.WebSocketFlow):
+        """
+            A websocket connection has ended.
+        """
diff --git a/examples/addons/events.py b/examples/addons/events.py
index f83c8f11..958e7d39 100644
--- a/examples/addons/events.py
+++ b/examples/addons/events.py
@@ -10,99 +10,6 @@ import mitmproxy.proxy.protocol
 
 
 class Events:
-    # HTTP lifecycle
-    def http_connect(self, flow: mitmproxy.http.HTTPFlow):
-        """
-            An HTTP CONNECT request was received. Setting a non 2xx response on
-            the flow will return the response to the client abort the
-            connection. CONNECT requests and responses do not generate the usual
-            HTTP handler events. CONNECT requests are only valid in regular and
-            upstream proxy modes.
-        """
-
-    def requestheaders(self, flow: mitmproxy.http.HTTPFlow):
-        """
-            HTTP request headers were successfully read. At this point, the body
-            is empty.
-        """
-
-    def request(self, flow: mitmproxy.http.HTTPFlow):
-        """
-            The full HTTP request has been read.
-        """
-
-    def responseheaders(self, flow: mitmproxy.http.HTTPFlow):
-        """
-            HTTP response headers were successfully read. At this point, the body
-            is empty.
-        """
-
-    def response(self, flow: mitmproxy.http.HTTPFlow):
-        """
-            The full HTTP response has been read.
-        """
-
-    def error(self, flow: mitmproxy.http.HTTPFlow):
-        """
-            An HTTP error has occurred, e.g. invalid server responses, or
-            interrupted connections. This is distinct from a valid server HTTP
-            error response, which is simply a response with an HTTP error code.
-        """
-
-    # TCP lifecycle
-    def tcp_start(self, flow: mitmproxy.tcp.TCPFlow):
-        """
-            A TCP connection has started.
-        """
-
-    def tcp_message(self, flow: mitmproxy.tcp.TCPFlow):
-        """
-            A TCP connection has received a message. The most recent message
-            will be flow.messages[-1]. The message is user-modifiable.
-        """
-
-    def tcp_error(self, flow: mitmproxy.tcp.TCPFlow):
-        """
-            A TCP error has occurred.
-        """
-
-    def tcp_end(self, flow: mitmproxy.tcp.TCPFlow):
-        """
-            A TCP connection has ended.
-        """
-
-    # Websocket lifecycle
-    def websocket_handshake(self, flow: mitmproxy.http.HTTPFlow):
-        """
-            Called when a client wants to establish a WebSocket connection. The
-            WebSocket-specific headers can be manipulated to alter the
-            handshake. The flow object is guaranteed to have a non-None request
-            attribute.
-        """
-
-    def websocket_start(self, flow: mitmproxy.websocket.WebSocketFlow):
-        """
-            A websocket connection has commenced.
-        """
-
-    def websocket_message(self, flow: mitmproxy.websocket.WebSocketFlow):
-        """
-            Called when a WebSocket message is received from the client or
-            server. 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.
-        """
-
-    def websocket_error(self, flow: mitmproxy.websocket.WebSocketFlow):
-        """
-            A websocket connection has had an error.
-        """
-
-    def websocket_end(self, flow: mitmproxy.websocket.WebSocketFlow):
-        """
-            A websocket connection has ended.
-        """
-
     # Network lifecycle
     def clientconnect(self, layer: mitmproxy.proxy.protocol.Layer):
         """
diff --git a/examples/complex/websocket_inject_message.py b/examples/complex/websocket_inject_message.py
index e9c3ea0c..38be5555 100644
--- a/examples/complex/websocket_inject_message.py
+++ b/examples/complex/websocket_inject_message.py
@@ -13,7 +13,7 @@ class InjectWebSocketMessage:
         i = 0
         while not flow.ended and not flow.error:
             await asyncio.sleep(5)
-            flow.inject_message(flow.client_conn, 'This is the #{} an injected message!'.format(i))
+            flow.inject_message(flow.client_conn, 'This is the #{} injected message!'.format(i))
             i += 1
 
     def websocket_start(self, flow):
diff --git a/examples/simple/websocket_messages.py b/examples/simple/websocket_messages.py
index 719e7b10..071ea21f 100644
--- a/examples/simple/websocket_messages.py
+++ b/examples/simple/websocket_messages.py
@@ -6,8 +6,15 @@ def websocket_message(flow):
     # get the latest message
     message = flow.messages[-1]
 
-    # simply print the content of the message
-    ctx.log.info(message.content)
+    # was the message sent from the client or server?
+    if message.from_client:
+        ctx.log.info("Client sent a message: {}".format(message.content))
+    else:
+        ctx.log.info("Server sent a message: {}".format(message.content))
 
     # manipulate the message content
     message.content = re.sub(r'^Hello', 'HAPPY', message.content)
+
+    if 'FOOBAR' in message.content:
+        # kill the message and not send it to the other endpoint
+        message.kill()