Start on scripting documentation and examples.

doc-src/index.html

@@ -11,9 +11,9 @@
         <li><a href="@!urlTo("anticache.html")!@">Anticache</a></li>
         <li><a href="@!urlTo("filters.html")!@">Filter expressions</a></li>
     </ul>
-    <li><a href="@!urlTo("scripts.html")!@">Scripting API</a></li>
+    <li><a href="@!urlTo("scripts.html")!@">Scripts</a></li>
         <ul>
-            <li><a href="@!urlTo("scripts/flows.html")!@">Introduction to flows</a></li>
+            <li><a href="@!urlTo("scripts/examples.html")!@">Examples</a></li>
             <li><a href="@!urlTo("scripts/api.html")!@">API</a></li>
         </ul>
     <li><a href="@!urlTo("ssl.html")!@">SSL interception</a></li>

doc-src/index.py

@@ -75,7 +75,7 @@ pages = [
     Page("sticky.html", "Sticky cookies and auth"),
     Page("anticache.html", "Anticache"),
     Page("filters.html", "Filter expressions"),
-    Page("scripts.html", "External scripts"),
+    Page("scripts.html", "Scripts"),
     Directory("scripts"),
     Page("ssl.html", "SSL interception"),
     Directory("certinstall"),

doc-src/scripts.html

@@ -1,14 +1,46 @@
 
-Both __mitmproxy__ and __mitmdump__ allow you to modify requests and responses
-with external scripts. This is often done through the __--reqscript__ and
-__--respscript__ options
+__mitmproxy__ has a powerful event-drive scripting API, that allows you to
+modify flows on-the-fly or rewrite previously saved flows locally. 
 
 
-The script interface is simple - scripts simply read,
-modify and return a single __libmproxy.flow.Flow__ object, using the methods
-defined in the __libmproxy.script__ module. Scripts must be executable.
+## Events
+
+<table>
+    <tr>
+        <td>start(ctx)</td>
+        <td>Called once on startup, before any other events.</td>
+    </tr>
+    <tr>
+        <td>clientconnect(ctx, ClientConnect)</td>
+        <td>Called when a client initiates a connection to the proxy. Note that
+        a connection can correspond to multiple HTTP requests.</td>
+    </tr>
+    <tr>
+        <td>request(ctx, Flow)</td>
+        <td>Called when a client request has been received.</td>
+    </tr>
+    <tr>
+        <td>response(ctx, Flow)</td>
+        <td>Called when a server response has been received.</td>
+    </tr>
+    <tr>
+        <td>error(ctx, Flow)</td>
+        <td>Called when a flow error has occured, 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. </td>
+    </tr>
+    <tr>
+        <td>clientdisconnect(ctx, ClientDisconnect)</td>
+        <td>Called when a client disconnects from the proxy.</td>
+    </tr>
+    <tr>
+        <td>done(ctx)</td>
+        <td>Called once on script shutdown, after any other events.</td>
+    </tr>
+</table>
+
 
-!example("examples/simple_script")!$
 
 
 

doc-src/scripts/examples.html

@@ -0,0 +1,4 @@
+
+## Stub script
+
+$!example("examples/stub.py")!$

doc-src/scripts/index.py

@@ -1,6 +1,6 @@
 from countershape import Page
 
 pages = [
-    Page("flows.html", "Introduction to flows"),
+    Page("examples.html", "Examples"),
     Page("api.html", "API"),
 ]