Merge branch 'stream'

Conflicts:
	libmproxy/protocol/http.py

4 files changed, 61 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..d20af65c
--- /dev/null
+++ b/doc-src/features/responsestreaming.html
@@ -0,0 +1,50 @@
+By using mitmproxy's streaming feature, response contents can be passed to the client incrementally before they have been fully received by the proxy.
+This is especially useful for large binary files such as videos, where buffering the whole file slows down the client's browser.
+
+By default, mitmproxy will read the entire response, perform any indicated
+manipulations on it and then send the (possibly modified) response 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 on the proxy but directly sent back to the client instead.
+
+<h2>On the command-line</h2>
+
+Streaming can be enabled on the command line for all response bodies exceeding a certain size.  The SIZE argument understands
+k/m/g suffixes, e.g. 3m for 3 megabytes.
+
+<table class="table">
+    <tbody>
+    <tr>
+        <th width="20%">command-line</th>
+        <td>
+            --stream SIZE
+        </td>
+    </tr>
+    </tbody>
+</table>
+
+
+<h2>Caveats</h2>
+
+When response streaming is enabled, <strong>streamed response contents will not be
+    recorded or preserved in any way.</strong>
+
+When response streaming is enabled, the response body cannot be modified.
+
+<h2>Customizing Response Streaming</h2>
+
+You can also use an <a href="@!urlTo("scripting/inlinescripts.html")!@">inline script</a> to customize exactly
+which responses are streamed.
+
+Responses that should be tagged for streaming by setting their respective .stream attribute to True:
+
+$!example("examples/stream.py")!$
+
+
+<h2>Implementation Details</h2>
+
+When response streaming is enabled, portions of the code which would have otherwise performed changes
+on the response body will see an empty response body instead (<code>libmproxy.protocol.http.CONTENT_MISSING</code>). Any modifications will be ignored.
+
+Streamed responses are usually sent in chunks of 4096 bytes. If the response is sent with a <code>Transfer-Encoding:
+    chunked</code> header, the response will be streamed one chunk at a time.
\ No newline at end of file
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)