From 31ee4607c892f85c5d139e54acbc3ca4f9fb6bcb Mon Sep 17 00:00:00 2001 From: Maximilian Hils Date: Mon, 7 Sep 2015 10:30:40 +0200 Subject: remove old docs --- doc-src/scripting/inlinescripts.html | 177 ----------------------------------- 1 file changed, 177 deletions(-) delete mode 100644 doc-src/scripting/inlinescripts.html (limited to 'doc-src/scripting/inlinescripts.html') 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: - -
-> mitmdump -s add_header.py
-
- -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: - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
libmproxy.proxy.server.ConnectionHandlerDescribes a proxy client connection session. Always has a client_conn attribute, might have a server_conn - attribute. -
libmproxy.proxy.connection.ClientConnectionDescribes a client connection.
libmproxy.proxy.connection.ServerConnectionDescribes a server connection.
libmproxy.protocol.http.HTTPFlowA collection of objects representing a single HTTP transaction.
libmproxy.protocol.http.HTTPResponseAn HTTP response.
libmproxy.protocol.http.HTTPRequestAn HTTP request.
libmproxy.protocol.primitives.ErrorA communications error.
libmproxy.script.ScriptContext A handle for interacting with mitmproxy's from within scripts.
netlib.odict.ODictA 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).
netlib.certutils.SSLCertExposes information SSL certificates.
- -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: - -
-> pydoc libmproxy.protocol.http.HTTPRequest
-
- - -## 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 libmproxy.script.concurrent 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. -mitmdump -s "script.py --foo 42". 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. -s "foo.py - 42"). Consequently, the script path needs to be wrapped in a separate pair of quotes if it contains spaces: --s "'./foo bar/baz.py' 42". -- cgit v1.2.3