From 00603021d9d486e3e16511eee273d26f59a3ab10 Mon Sep 17 00:00:00 2001 From: Aldo Cortesi Date: Sun, 16 Oct 2016 20:21:43 +1300 Subject: [PATCH] docs: concurrency, developing scripts --- docs/scripting/overview.rst | 39 ++++++++++++++++++------------------ mitmproxy/builtins/script.py | 2 +- release/README.mkd | 11 ---------- 3 files changed, 20 insertions(+), 32 deletions(-) diff --git a/docs/scripting/overview.rst b/docs/scripting/overview.rst index 744f5eb43..5966eb1de 100644 --- a/docs/scripting/overview.rst +++ b/docs/scripting/overview.rst @@ -105,38 +105,37 @@ flow loaded from disk will trigger `requestheaders traffic using scripts. For example, we can invoke the replacer script from above on saved traffic as follows: ->>> mitmdump -dd -s "./arguments.py html faketml" +>>> mitmdump -dd -s "./arguments.py html fakehtml" -r saved -w changed +This command starts the ``arguments`` script, reads all the flows from +``saved`` transforming them in the process, then writes them all to +``changed``. - - - -:py:class:`~mitmproxy.models.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 :ref:`here `). 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**, **responseheaders**, **response**, **error**, **done**. -If the flow doesn't have a **response** or **error** associated with it, the matching events will -be skipped. +The mitmproxy console tool provides interactive ways to run transforming +scripts on flows - for instance, you can run a one-shot script on a single flow +through the ``|`` (pipe) shortcut. Concurrency ----------- -We have a single flow primitive, so when a script is blocking, other requests -are not processed. While that's usually a very desirable behaviour, blocking -scripts can be run threaded by using the :py:obj:`mitmproxy.script.concurrent` -decorator. +The mitmproxy script mechanism is single threaded, and the proxy blocks while +script handlers execute. This hugely simplifies the most common case, where +handlers are light-weight and the blocking doesn't have a performance impact. +It's possible to implement a concurrent mechanism on top of the blocking +framework, and mitmproxy includes a handy example of this that is fit for most +purposes. You can use it as follows: .. literalinclude:: ../../examples/nonblocking.py :caption: :src:`examples/nonblocking.py` :language: python - Developing scripts ------------------ + +Mitmprxoy monitors scripts for modifications, and reloads them on change. When +this happens, the script is shut down (the `done `_ event is +called), and the new instance is started up as if the script had just been +loaded (the `start `_ and `configure +`_ events are called). diff --git a/mitmproxy/builtins/script.py b/mitmproxy/builtins/script.py index 5c375d27d..9bf25703e 100644 --- a/mitmproxy/builtins/script.py +++ b/mitmproxy/builtins/script.py @@ -267,7 +267,7 @@ class ScriptLoader(): ochain = ctx.master.addons.chain pos = ochain.index(self) - ctx.master.addons.chain = ochain[:pos+1] + ordered + ochain[pos+1:] + ctx.master.addons.chain = ochain[:pos + 1] + ordered + ochain[pos + 1:] for s in newscripts: ctx.master.addons.startup(s) diff --git a/release/README.mkd b/release/README.mkd index 7754125d0..8d63b8f33 100644 --- a/release/README.mkd +++ b/release/README.mkd @@ -1,15 +1,4 @@ -General build and release utilities for the mitmproxy, netlib and pathod -projects. These tools assume a directory structure with all repositories at the -same level, for example: - - /src - /mitmproxy - /netlib - /pathod - /release - - # Release policies - By default, every release is a new minor (`0.x`) release and it will be