diff options
author | Maximilian Hils <git@maximilianhils.com> | 2015-09-07 10:30:40 +0200 |
---|---|---|
committer | Maximilian Hils <git@maximilianhils.com> | 2015-09-07 10:30:40 +0200 |
commit | 31ee4607c892f85c5d139e54acbc3ca4f9fb6bcb (patch) | |
tree | 873629c79b60b0ac0a7dbb458fe6ad82c2e042ef /doc-src/scripting/inlinescripts.html | |
parent | b4013659a81a48908eb3e060f04143ba1f9689bb (diff) | |
download | mitmproxy-31ee4607c892f85c5d139e54acbc3ca4f9fb6bcb.tar.gz mitmproxy-31ee4607c892f85c5d139e54acbc3ca4f9fb6bcb.tar.bz2 mitmproxy-31ee4607c892f85c5d139e54acbc3ca4f9fb6bcb.zip |
remove old docs
Diffstat (limited to 'doc-src/scripting/inlinescripts.html')
-rw-r--r-- | doc-src/scripting/inlinescripts.html | 177 |
1 files changed, 0 insertions, 177 deletions
diff --git a/doc-src/scripting/inlinescripts.html b/doc-src/scripting/inlinescripts.html deleted file mode 100644 index 7cd6af25..00000000 --- a/doc-src/scripting/inlinescripts.html +++ /dev/null @@ -1,177 +0,0 @@ -__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. - -We can now run this script using mitmdump or mitmproxy as follows: - -<pre class="terminal"> -> mitmdump -s add_header.py -</pre> - -The new header will be added to all responses passing through the proxy. - -## Example Scripts - -mitmproxy comes with a variety of example inline scripts, which demonstrate -many basic tasks. We encourage you to either browse them locally or in our -[GitHub repo](https://github.com/mitmproxy/mitmproxy/tree/master/examples). - - -## Events - -### start(ScriptContext, argv) - -Called once on startup, before any other events. - - -### clientconnect(ScriptContext, ConnectionHandler) - -Called when a client initiates a connection to the proxy. Note that -a connection can correspond to multiple HTTP requests. - -### serverconnect(ScriptContext, ConnectionHandler) - -Called when the proxy initiates a connection to the target server. Note that -a connection can correspond to multiple HTTP requests. - -### request(ScriptContext, HTTPFlow) - -Called when a client request has been received. The __HTTPFlow__ object is -guaranteed to have a non-None __request__ attribute. - -### responseheaders(ScriptContext, HTTPFlow) - -Called when the headers of a server response have been received. -This will always be called before the response hook. -The __HTTPFlow__ object is guaranteed to have non-None __request__ and -__response__ attributes. __response.content__ will be None, -as the response body has not been read yet. - -### response(ScriptContext, HTTPFlow) - -Called when a server response has been received. The __HTTPFlow__ 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, HTTPFlow) - -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 __HTTPFlow__ -object is guaranteed to have non-None __request__ and __error__ attributes. - - -### clientdisconnect(ScriptContext, ConnectionHandler) - -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="table"> - <tr> - <th>libmproxy.proxy.server.ConnectionHandler</th> - <td>Describes a proxy client connection session. Always has a client_conn attribute, might have a server_conn - attribute. - </td> - </tr> - <tr> - <th>libmproxy.proxy.connection.ClientConnection</th> - <td>Describes a client connection.</td> - </tr> - <tr> - <th>libmproxy.proxy.connection.ServerConnection</th> - <td>Describes a server connection.</td> - </tr> - <tr> - <th>libmproxy.protocol.http.HTTPFlow</th> - <td>A collection of objects representing a single HTTP transaction.</td> - </tr> - <tr> - <th>libmproxy.protocol.http.HTTPResponse</th> - <td>An HTTP response.</td> - </tr> - <tr> - <th>libmproxy.protocol.http.HTTPRequest</th> - <td>An HTTP request.</td> - </tr> - <tr> - <th>libmproxy.protocol.primitives.Error</th> - <td>A communications error.</td> - </tr> - <tr> - <th>libmproxy.script.ScriptContext</th> - <td> A handle for interacting with mitmproxy's from within scripts.</td> - </tr> - <tr> - <th>netlib.odict.ODict</th> - - <td>A dictionary-like object for managing sets of key/value data. There - is also a variant called ODictCaseless that ignores key case for some - calls (used mainly for headers).</td> - </tr> - <tr> - <th>netlib.certutils.SSLCert</th> - <td>Exposes information SSL certificates.</td> - </tr> -</table> - -The canonical API documentation is the code, which you can browse locally or in our -[GitHub repo](https://github.com/mitmproxy/mitmproxy). -You can view the API documentation using pydoc (which is installed with Python by default), like this: - -<pre class="terminal"> -> pydoc libmproxy.protocol.http.HTTPRequest -</pre> - - -## Running scripts in parallel - -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 <code>libmproxy.script.concurrent</code> decorator. -If your script does not block, you should avoid the overhead of the decorator. - -$!example("examples/nonblocking.py")!$ - -## Make scripts configurable with arguments - -Sometimes, you want to pass runtime arguments to the inline script. This can be simply done by surrounding the script call with quotes, e.g. -<code>mitmdump -s "script.py --foo 42"</code>. The arguments are then exposed in the start event: - -$!example("examples/modify_response_body.py")!$ - -## 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__, __responseheaders__, __response__, __error__, __done__. If -the flow doesn't have a __response__ or __error__ associated with it, the -matching events will be skipped. - -## Spaces in the script path -By default, spaces are interpreted as separator between the inline script and its arguments (e.g. <code>-s "foo.py - 42"</code>). Consequently, the script path needs to be wrapped in a separate pair of quotes if it contains spaces: -<code>-s "'./foo bar/baz.py' 42"</code>. |