diff options
| -rw-r--r-- | doc-src/index.html | 4 | ||||
| -rw-r--r-- | doc-src/index.py | 2 | ||||
| -rw-r--r-- | doc-src/scripts.html | 48 | ||||
| -rw-r--r-- | doc-src/scripts/examples.html | 4 | ||||
| -rw-r--r-- | doc-src/scripts/flows.html | 0 | ||||
| -rw-r--r-- | doc-src/scripts/index.py | 2 | ||||
| -rw-r--r-- | examples/add_header.py | 2 | ||||
| -rw-r--r-- | examples/stub.py | 47 |
8 files changed, 95 insertions, 14 deletions
diff --git a/doc-src/index.html b/doc-src/index.html index 4638b091..cb331ab9 100644 --- a/doc-src/index.html +++ b/doc-src/index.html @@ -11,9 +11,9 @@ <li><a href="@!urlTo("anticache.html")!@">Anticache</a></li> <li><a href="@!urlTo("filters.html")!@">Filter expressions</a></li> </ul> - <li><a href="@!urlTo("scripts.html")!@">Scripting API</a></li> + <li><a href="@!urlTo("scripts.html")!@">Scripts</a></li> <ul> - <li><a href="@!urlTo("scripts/flows.html")!@">Introduction to flows</a></li> + <li><a href="@!urlTo("scripts/examples.html")!@">Examples</a></li> <li><a href="@!urlTo("scripts/api.html")!@">API</a></li> </ul> <li><a href="@!urlTo("ssl.html")!@">SSL interception</a></li> diff --git a/doc-src/index.py b/doc-src/index.py index 05254234..34704f7e 100644 --- a/doc-src/index.py +++ b/doc-src/index.py @@ -75,7 +75,7 @@ pages = [ Page("sticky.html", "Sticky cookies and auth"), Page("anticache.html", "Anticache"), Page("filters.html", "Filter expressions"), - Page("scripts.html", "External scripts"), + Page("scripts.html", "Scripts"), Directory("scripts"), Page("ssl.html", "SSL interception"), Directory("certinstall"), diff --git a/doc-src/scripts.html b/doc-src/scripts.html index 2514923e..990ca070 100644 --- a/doc-src/scripts.html +++ b/doc-src/scripts.html @@ -1,14 +1,46 @@ -Both __mitmproxy__ and __mitmdump__ allow you to modify requests and responses -with external scripts. This is often done through the __--reqscript__ and -__--respscript__ options +__mitmproxy__ has a powerful event-drive scripting API, that allows you to +modify flows on-the-fly or rewrite previously saved flows locally. + + +## Events + +<table> + <tr> + <td>start(ctx)</td> + <td>Called once on startup, before any other events.</td> + </tr> + <tr> + <td>clientconnect(ctx, ClientConnect)</td> + <td>Called when a client initiates a connection to the proxy. Note that + a connection can correspond to multiple HTTP requests.</td> + </tr> + <tr> + <td>request(ctx, Flow)</td> + <td>Called when a client request has been received.</td> + </tr> + <tr> + <td>response(ctx, Flow)</td> + <td>Called when a server response has been received.</td> + </tr> + <tr> + <td>error(ctx, Flow)</td> + <td>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. </td> + </tr> + <tr> + <td>clientdisconnect(ctx, ClientDisconnect)</td> + <td>Called when a client disconnects from the proxy.</td> + </tr> + <tr> + <td>done(ctx)</td> + <td>Called once on script shutdown, after any other events.</td> + </tr> +</table> -The script interface is simple - scripts simply read, -modify and return a single __libmproxy.flow.Flow__ object, using the methods -defined in the __libmproxy.script__ module. Scripts must be executable. - -!example("examples/simple_script")!$ diff --git a/doc-src/scripts/examples.html b/doc-src/scripts/examples.html new file mode 100644 index 00000000..bfa1f8d7 --- /dev/null +++ b/doc-src/scripts/examples.html @@ -0,0 +1,4 @@ + +## Stub script + +$!example("examples/stub.py")!$ diff --git a/doc-src/scripts/flows.html b/doc-src/scripts/flows.html deleted file mode 100644 index e69de29b..00000000 --- a/doc-src/scripts/flows.html +++ /dev/null diff --git a/doc-src/scripts/index.py b/doc-src/scripts/index.py index 805a17d9..987cf840 100644 --- a/doc-src/scripts/index.py +++ b/doc-src/scripts/index.py @@ -1,6 +1,6 @@ from countershape import Page pages = [ - Page("flows.html", "Introduction to flows"), + Page("examples.html", "Examples"), Page("api.html", "API"), ] diff --git a/examples/add_header.py b/examples/add_header.py index dab33c8c..6ddeab3d 100644 --- a/examples/add_header.py +++ b/examples/add_header.py @@ -1,8 +1,6 @@ -#!/usr/bin/env python """ This script adds a new header to all responses. """ -from libmproxy import script def response(ctx, f): f.response.headers["newheader"] = ["foo"] diff --git a/examples/stub.py b/examples/stub.py new file mode 100644 index 00000000..f235ea85 --- /dev/null +++ b/examples/stub.py @@ -0,0 +1,47 @@ +""" + This is a script stub, with empty definitions for all events. +""" + +def start(ctx): + """ + Called once on script startup, before any other events. + """ + pass + +def clientconnect(ctx, client_connect): + """ + Called when a client initiates a connection to the proxy. Note that a + connection can correspond to multiple HTTP requests + """ + pass + +def request(ctx, flow): + """ + Called when a client request has been received. + """ + +def response(ctx, flow): + """ + Called when a server response has been received. + """ + pass + +def 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. + """ + pass + +def clientdisconnect(ctx, client_disconnect): + """ + Called when a client disconnects from the proxy. + """ + pass + +def done(ctx): + """ + Called once on script shutdown, after any other events. + """ + pass |