Doc reorg.

doc-src/index.html

@@ -15,7 +15,11 @@
         <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")!@">Scripts</a></li>
+    <li>Scripting mitmproxy</li>
+        <ul>
+            <li><a href="@!urlTo("scripting/inlinescripts.html")!@">Inline Scripts</a></li>
+            <li><a href="@!urlTo("scripting/libmproxy.html")!@">libmproxy</a></li>
+        </ul>
     <li><a href="@!urlTo("ssl.html")!@">Setting up SSL interception</a></li>
         <ul>
             <li><a href="@!urlTo("certinstall/firefox.html")!@">Firefox</a></li>
@@ -24,7 +28,6 @@
             <li><a href="@!urlTo("certinstall/ios.html")!@">iPhone/iPad</a></li>
             <li><a href="@!urlTo("certinstall/android.html")!@">Android</a></li>
         </ul>
-     <li><a href="@!urlTo("library.html")!@">libmproxy</a></li>
      <li>Tutorials</li>
         <ul>
             <li> <a href="@!urlTo("tutorials/30second.html")!@">Client replay: a 30 second example</a> </li>
@@ -33,5 +36,3 @@
      <li><a href="@!urlTo("faq.html")!@">FAQ</a></li>
      <li><a href="@!urlTo("admin.html")!@">Administrivia</a></li>
 </ul>
-
-

doc-src/index.py

@@ -79,10 +79,10 @@ pages = [
     Page("reverseproxy.html", "Reverse proxy mode"),
     Page("anticache.html", "Anticache"),
     Page("filters.html", "Filter expressions"),
-    Page("scripts.html", "Scripts"),
+    Page("scripting.html", "Scripts"),
+    Directory("scripting"),
     Page("ssl.html", "Setting up SSL interception"),
     Directory("certinstall"),
-    Page("library.html", "libmproxy: mitmproxy as a library"),
     Directory("tutorials"),
     Page("faq.html", "FAQ"),
     Page("admin.html", "Administrivia")

doc-src/scripting/index.py

@@ -0,0 +1,6 @@
+from countershape import Page
+
+pages = [
+    Page("inlinescripts.html", "Inline Scripts"),
+    Page("libmproxy.html", "libmproxy")
+]

doc-src/scripting/inlinescripts.html

@@ -0,0 +1,129 @@
+
+__mitmproxy__ has a powerful scripting API that allows you to modify flows
+on-the-fly or rewrite previously saved flows locally. 
+
+The mitmproxy scripting API is event driven - a script is simply a Python
+module that exposes a set of event methods. Here's a complete mitmproxy script
+that adds a new header to every HTTP response before it is returned to the
+client:
+
+$!example("examples/add_header.py")!$
+
+The first argument to each event method is an instance of ScriptContext that
+lets the script interact with the global mitmproxy state. The __response__
+event also gets an instance of Flow, which we can use to manipulate the
+response itself.
+
+
+## Events
+
+### start(ScriptContext)
+
+Called once on startup, before any other events.
+
+
+###clientconnect(ScriptContext, ClientConnect)
+
+Called when a client initiates a connection to the proxy. Note that
+a connection can correspond to multiple HTTP requests.
+
+
+###request(ScriptContext, Flow)
+
+Called when a client request has been received. The __Flow__ object is
+guaranteed to have a non-None __request__ attribute.
+
+
+### response(ScriptContext, Flow)
+
+Called when a server response has been received. The __Flow__ object is
+guaranteed to have non-None __request__ and __response__ attributes.
+
+
+### error(ScriptContext, Flow)
+
+Called when a flow 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. The __Flow__
+object is guaranteed to have non-None __request__ and __error__ attributes.
+
+
+### clientdisconnect(ScriptContext, ClientDisconnect)
+
+Called when a client disconnects from the proxy.
+
+### done(ScriptContext)
+
+Called once on script shutdown, after any other events.
+
+
+## API
+
+The main classes you will deal with in writing mitmproxy scripts are:
+
+<table class="kvtable">
+    <tr>
+        <th>libmproxy.flow.ClientConnection</th>
+        <td>Describes a client connection.</td>
+    </tr>
+    <tr>
+        <th>libmproxy.flow.ClientDisconnection</th>
+        <td>Describes a client disconnection.</td>
+    </tr>
+    <tr>
+        <th>libmproxy.flow.Error</th>
+        <td>A communications error.</td>
+    </tr>
+    <tr>
+        <th>libmproxy.flow.Flow</th>
+        <td>A collection of objects representing a single HTTP transaction.</td>
+    </tr>
+    <tr>
+        <th>libmproxy.flow.Headers</th>
+        <td>HTTP headers for a request or response.</td>
+    </tr>
+    <tr>
+        <th>libmproxy.flow.ODict</th>
+
+        <td>A dictionary-like object for managing sets of key/value data. There
+        is also a variant called CaselessODict that ignores key case for some
+        calls (used mainly for headers).</td>
+    </tr>
+    <tr>
+        <th>libmproxy.flow.Response</th>
+        <td>An HTTP response.</td>
+    </tr>
+    <tr>
+        <th>libmproxy.flow.Request</th>
+        <td>An HTTP request.</td>
+    </tr>
+    <tr>
+        <th>libmproxy.flow.ScriptContext</th>
+        <td> A handle for interacting with mitmproxy's from within scripts.  </td>
+    </tr>
+    <tr>
+        <th>libmproxy.certutils.SSLCert</th>
+        <td>Exposes information SSL certificates.</td>
+    </tr>
+</table>
+
+The canonical API documentation is the code. You can view the API documentation
+using pydoc (which is installed with Python by default), like this:
+
+<pre class="terminal">
+> pydoc libmproxy.flow.Request
+</pre>
+
+
+## Running scripts on saved flows
+
+Sometimes, we want to run a script on __Flow__ objects that are already
+complete.  This happens when you start a script, and then load a saved set of
+flows from a file (see the "scripted data transformation" example on the
+[mitmdump](@!urlTo("mitmdump.html")!@) page). It also happens when you run a
+one-shot script on a single flow through the _|_ (pipe) shortcut in mitmproxy.
+
+In this case, there are no client connections, and the events are run in the
+following order: __start__, __request__, __response__, __error__, __done__.  If
+the flow doesn't have a __response__ or __error__ associated with it, the
+matching event will be skipped. 

doc-src/scripting/libmproxy.html

@@ -0,0 +1,12 @@
+
+All of mitmproxy's basic functionality is exposed through the __libmproxy__
+library. The example below shows a simple implementation of the "sticky cookie"
+functionality included in the interactive mitmproxy program. Traffic is
+monitored for __cookie__ and __set-cookie__ headers, and requests are rewritten
+to include a previously seen cookie if they don't already have one. In effect,
+this lets you log in to a site using your browser, and then make subsequent
+requests using a tool like __curl__, which will then seem to be part of the
+authenticated session.
+
+$!example("examples/stickycookies")!$
+