diff options
Diffstat (limited to 'doc-src')
| -rw-r--r-- | doc-src/_nav.html | 1 | ||||
| -rw-r--r-- | doc-src/features/index.py | 1 | ||||
| -rw-r--r-- | doc-src/features/responsestreaming.html | 50 | ||||
| -rw-r--r-- | doc-src/scripting/inlinescripts.html | 10 |
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) |