Skip to content

Commit 89a58d7

Browse files
cortesicortesi
committed
Start on scripting documentation and examples.
1 parent 98a7aac commit 89a58d7

8 files changed

Lines changed: 95 additions & 14 deletions

File tree

‎doc-src/index.html‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -11,9 +11,9 @@
1111
<li><a href="@!urlTo("anticache.html")!@">Anticache</a></li>
1212
<li><a href="@!urlTo("filters.html")!@">Filter expressions</a></li>
1313
</ul>
14-
<li><a href="@!urlTo("scripts.html")!@">Scripting API</a></li>
14+
<li><a href="@!urlTo("scripts.html")!@">Scripts</a></li>
1515
<ul>
16-
<li><a href="@!urlTo("scripts/flows.html")!@">Introduction to flows</a></li>
16+
<li><a href="@!urlTo("scripts/examples.html")!@">Examples</a></li>
1717
<li><a href="@!urlTo("scripts/api.html")!@">API</a></li>
1818
</ul>
1919
<li><a href="@!urlTo("ssl.html")!@">SSL interception</a></li>

‎doc-src/index.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -75,7 +75,7 @@ def example(s):
7575
Page("sticky.html", "Sticky cookies and auth"),
7676
Page("anticache.html", "Anticache"),
7777
Page("filters.html", "Filter expressions"),
78-
Page("scripts.html", "External scripts"),
78+
Page("scripts.html", "Scripts"),
7979
Directory("scripts"),
8080
Page("ssl.html", "SSL interception"),
8181
Directory("certinstall"),

‎doc-src/scripts.html‎

Lines changed: 40 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,46 @@
11

2-
Both __mitmproxy__ and __mitmdump__ allow you to modify requests and responses
3-
with external scripts. This is often done through the __--reqscript__ and
4-
__--respscript__ options
2+
__mitmproxy__ has a powerful event-drive scripting API, that allows you to
3+
modify flows on-the-fly or rewrite previously saved flows locally.
4+
5+
6+
## Events
7+
8+
<table>
9+
<tr>
10+
<td>start(ctx)</td>
11+
<td>Called once on startup, before any other events.</td>
12+
</tr>
13+
<tr>
14+
<td>clientconnect(ctx, ClientConnect)</td>
15+
<td>Called when a client initiates a connection to the proxy. Note that
16+
a connection can correspond to multiple HTTP requests.</td>
17+
</tr>
18+
<tr>
19+
<td>request(ctx, Flow)</td>
20+
<td>Called when a client request has been received.</td>
21+
</tr>
22+
<tr>
23+
<td>response(ctx, Flow)</td>
24+
<td>Called when a server response has been received.</td>
25+
</tr>
26+
<tr>
27+
<td>error(ctx, Flow)</td>
28+
<td>Called when a flow error has occured, e.g. invalid server
29+
responses, or interrupted connections. This is distinct from a valid
30+
server HTTP error response, which is simply a response with an HTTP
31+
error code. </td>
32+
</tr>
33+
<tr>
34+
<td>clientdisconnect(ctx, ClientDisconnect)</td>
35+
<td>Called when a client disconnects from the proxy.</td>
36+
</tr>
37+
<tr>
38+
<td>done(ctx)</td>
39+
<td>Called once on script shutdown, after any other events.</td>
40+
</tr>
41+
</table>
542

643

7-
The script interface is simple - scripts simply read,
8-
modify and return a single __libmproxy.flow.Flow__ object, using the methods
9-
defined in the __libmproxy.script__ module. Scripts must be executable.
10-
11-
!example("examples/simple_script")!$
1244

1345

1446

‎doc-src/scripts/examples.html‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
2+
## Stub script
3+
4+
$!example("examples/stub.py")!$

‎doc-src/scripts/flows.html‎

Whitespace-only changes.

‎doc-src/scripts/index.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
from countershape import Page
22

33
pages = [
4-
Page("flows.html", "Introduction to flows"),
4+
Page("examples.html", "Examples"),
55
Page("api.html", "API"),
66
]

‎examples/add_header.py‎

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,6 @@
1-
#!/usr/bin/env python
21
"""
32
This script adds a new header to all responses.
43
"""
5-
from libmproxy import script
64

75
def response(ctx, f):
86
f.response.headers["newheader"] = ["foo"]

‎examples/stub.py‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
"""
2+
This is a script stub, with empty definitions for all events.
3+
"""
4+
5+
def start(ctx):
6+
"""
7+
Called once on script startup, before any other events.
8+
"""
9+
pass
10+
11+
def clientconnect(ctx, client_connect):
12+
"""
13+
Called when a client initiates a connection to the proxy. Note that a
14+
connection can correspond to multiple HTTP requests
15+
"""
16+
pass
17+
18+
def request(ctx, flow):
19+
"""
20+
Called when a client request has been received.
21+
"""
22+
23+
def response(ctx, flow):
24+
"""
25+
Called when a server response has been received.
26+
"""
27+
pass
28+
29+
def error(ctx, flow):
30+
"""
31+
Called when a flow error has occured, e.g. invalid server responses, or
32+
interrupted connections. This is distinct from a valid server HTTP error
33+
response, which is simply a response with an HTTP error code.
34+
"""
35+
pass
36+
37+
def clientdisconnect(ctx, client_disconnect):
38+
"""
39+
Called when a client disconnects from the proxy.
40+
"""
41+
pass
42+
43+
def done(ctx):
44+
"""
45+
Called once on script shutdown, after any other events.
46+
"""
47+
pass

0 commit comments

Comments
 (0)