response streaming doc

4 files changed, 63 insertions, 1 deletions

diff --git a/doc-src/_nav.html b/doc-src/_nav.html
index ddc27dca..cd70cc25 100644
--- a/doc-src/_nav.html
+++ b/doc-src/_nav.html
@@ -19,6 +19,7 @@
         $!nav("sticky.html", this, state)!$
         $!nav("reverseproxy.html", this, state)!$
         $!nav("upstreamcerts.html", this, state)!$
+        $!nav("responsestreaming.html", this, state)!$
 
     <li class="nav-header">Installing Certificates</li>
         $!nav("ssl.html", this, state)!$
diff --git a/doc-src/features/index.py b/doc-src/features/index.py
index 0618681f..b4d441d1 100644
--- a/doc-src/features/index.py
+++ b/doc-src/features/index.py
@@ -12,4 +12,5 @@ pages = [
     Page("replacements.html", "Replacements"),
     Page("reverseproxy.html", "Reverse proxy mode"),
     Page("upstreamcerts.html", "Upstream Certs"),
+    Page("responsestreaming.html", "Response Streaming"),
 ]
diff --git a/doc-src/features/responsestreaming.html b/doc-src/features/responsestreaming.html
new file mode 100644
index 00000000..176fa4ae
--- /dev/null
+++ b/doc-src/features/responsestreaming.html
@@ -0,0 +1,52 @@
+
+By default, mitmproxy will read the entire response, perform any indicated
+manipulations on it and then send the (possibly modified) response back to
+the client.  In some cases this is undesirable and you may wish to "stream"
+the reponse back to the client.  When streaming is enabled, the response is
+not buffered but is instead sent directly back to the client.  (If HTTP
+chunked transfer encoding is enabled, the response will be streamed
+back one chunk at a time.) This is especially useful for large binary files,
+which are often not what you are trying to inspect, and while buffering
+cause browser slows.
+
+Streaming can be enabled on the command line for all responses which are
+greater than a certain size.  Note that the SIZE argument below can accept
+the usual prefixes (m, k, etc.)
+
+<table class="table">
+    <tbody>
+        <tr>
+            <th width="20%">command-line</th>
+            <td>
+                <ul>
+                    <li>--stream SIZE</li>
+                </ul>
+            </td>
+        </tr>
+    </tbody>
+</table>
+
+<div class="page-header">
+    <h1>Customizing Response Streaming</h1>
+</div>
+
+You can also use an inline script hook to write code to customize exactly
+which responses are streamed.
+
+The basic concept is simple:
+
+$!example("examples/stream.py")!$
+
+See [inline scripts](@!urlTo("scripting/inlinescripts.html")!@) for more
+info on how to make and use inline scripts in general.
+
+<div class="page-header">
+    <h1>Things to Know</h1>
+</div>
+
+When response streaming is enabled, streamed response content will not be
+recorded with the -w parameter.
+
+Portions of the code which would have otherwise performed changes
+on the response body will instead see an empty response body
+and any attempts to modify it will be ignored.
diff --git a/doc-src/scripting/inlinescripts.html b/doc-src/scripting/inlinescripts.html
index 32a98e99..65090cfb 100644
--- a/doc-src/scripting/inlinescripts.html
+++ b/doc-src/scripting/inlinescripts.html
@@ -46,12 +46,20 @@ a connection can correspond to multiple HTTP requests.
 Called when a client request has been received. The __Flow__ object is
 guaranteed to have a non-None __request__ attribute.
 
+### responseheaders(ScriptContext, Flow)
+
+Called when the headers of a server response have been received.
+This will always be called before the response hook.
+The __Flow__ object is guaranteed to have non-None __request__ and
+__response__ attributes.  __response.content__ will not be valid,
+as the response body has not been read yet.
 
 ### response(ScriptContext, Flow)
 
 Called when a server response has been received. The __Flow__ object is
 guaranteed to have non-None __request__ and __response__ attributes.
-
+Note that if response streaming is enabled for this response,
+__response.content__ will not contain the response body.
 
 ### error(ScriptContext, Flow)