From cd0e2f18e6626f5d02ab749a001934a016eee966 Mon Sep 17 00:00:00 2001 From: Aldo Cortesi Date: Fri, 5 Aug 2011 13:26:39 +1200 Subject: First draft of scripting docs. --- doc-src/scripts.html | 96 ++++++++++++++++++++++++++++++++-------------------- 1 file changed, 60 insertions(+), 36 deletions(-) (limited to 'doc-src/scripts.html') diff --git a/doc-src/scripts.html b/doc-src/scripts.html index 990ca070..af140901 100644 --- a/doc-src/scripts.html +++ b/doc-src/scripts.html @@ -1,47 +1,71 @@ -__mitmproxy__ has a powerful event-drive scripting API, that allows you to -modify flows on-the-fly or rewrite previously saved flows locally. +__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. ## Events - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
start(ctx)Called once on startup, before any other events.
clientconnect(ctx, ClientConnect)Called when a client initiates a connection to the proxy. Note that - a connection can correspond to multiple HTTP requests.
request(ctx, Flow)Called when a client request has been received.
response(ctx, Flow)Called when a server response has been received.
error(ctx, Flow)Called when a flow error has occured, 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.
clientdisconnect(ctx, ClientDisconnect)Called when a client disconnects from the proxy.
done(ctx)Called once on script shutdown, after any other events.
+### start(ScriptContext) + +Called once on startup, before any other events. + + +###clientconnect(ScriptContext, ClientConnect) + +Called when a client initiates a connection to the proxy. Note that +a connection can correspond to multiple HTTP requests. + + +###request(ScriptContext, Flow) + +Called when a client request has been received. The __Flow__ object is +guaranteed to have a non-None __request__ attribute. + + +### response(ScriptContext, Flow) + +Called when a server response has been received. The __Flow__ object is +guaranteed to have non-None __request__ and __response__ attributes. + + +### error(ScriptContext, Flow) + +Called when a flow error has occured, 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 __Flow__ +object is guaranteed to have non-None __request__ and __error__ attributes. + + +### clientdisconnect(ScriptContext, ClientDisconnect) + +Called when a client disconnects from the proxy. +### done(ScriptContext) +Called once on script shutdown, after any other events. +## Scripts on saved flows +There are a few circumstances in which a script may run on Flows that are +already complete. For example, you could 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). This 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__, __response__, __error__, __done__. If +the flow doesn't have a __response__ or __error__ associated with it, the +matching event will be skipped. -- cgit v1.2.3