From 0958f39f408f1d8583ab90ff54cc539abb99d90a Mon Sep 17 00:00:00 2001 From: Maximilian Hils Date: Thu, 17 Jun 2021 15:53:22 +0200 Subject: [PATCH 1/3] add upgrade docs for mitmproxy 7 --- docs/src/content/addons-api-changelog.md | 46 ++++++++++++++++++++++++ 1 file changed, 46 insertions(+) create mode 100644 docs/src/content/addons-api-changelog.md diff --git a/docs/src/content/addons-api-changelog.md b/docs/src/content/addons-api-changelog.md new file mode 100644 index 000000000..91c29d3d6 --- /dev/null +++ b/docs/src/content/addons-api-changelog.md @@ -0,0 +1,46 @@ +--- +title: "API Changelog" +layout: single +menu: + addons: + weight: 9 +--- + +# API Changelog + +We try to avoid them, but this page lists breaking changes in the mitmproxy addon API. + +## mitmproxy 7.0 + +#### Connection Events + +We've revised mitmproxy's connection-specific event hooks as part of the new proxy core. See the new +[event hook documentation]({{< relref "addons-api#ConnectionEvents" >}}) for details. As the passed objects are slightly +different now, we've also taken this opportunity to introduce a consistent event names: + +| mitmproxy 6 | mitmproxy 7 | +|--|--| +| `clientconnect` | `client_connected` | +| `clientdisconnect` | `client_disconnected` | +| ❌ | `server_connect` | +| `serverconnect` | `server_connected` | +| `serverdisconnect` | `server_disconnected` | + +#### Logging + +The `log` event has been renamed to `add_log`. This fixes a consistent source of errors where users imported +modules with the name "log", which were then inadvertedly picked up. + +#### Contentviews + +Contentviews now implement `render_priority` instead of `should_render`. This enables additional specialization, for +example one can now write contentviews that pretty-print only specific JSON responses. +See the [contentview.py]({{< relref "addons-examples#contentview" >}}) example for details. + +#### WebSocket Flows + +mitmproxy 6 had a custom WebSocketFlow class, which had +[ugly co-dependencies with the related HTTPFlow](https://github.com/mitmproxy/mitmproxy/issues/4425). Long story short, +WebSocketFlow is no more and instead HTTPFlow has a neat +[`.websocket` attribute]({{< relref "api/mitmproxy.http.md#HTTPFlow.websocket" >}}). All WebSocket flows are now passed +the originating `HTTPFlow` with this attribute set. From f342061319b3f961a225de07340ee8c236e09086 Mon Sep 17 00:00:00 2001 From: Maximilian Hils Date: Thu, 17 Jun 2021 20:15:29 +0200 Subject: [PATCH 2/3] Update addons-api-changelog.md --- docs/src/content/addons-api-changelog.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/src/content/addons-api-changelog.md b/docs/src/content/addons-api-changelog.md index 91c29d3d6..2bbf51a04 100644 --- a/docs/src/content/addons-api-changelog.md +++ b/docs/src/content/addons-api-changelog.md @@ -18,12 +18,12 @@ We've revised mitmproxy's connection-specific event hooks as part of the new pro [event hook documentation]({{< relref "addons-api#ConnectionEvents" >}}) for details. As the passed objects are slightly different now, we've also taken this opportunity to introduce a consistent event names: -| mitmproxy 6 | mitmproxy 7 | -|--|--| -| `clientconnect` | `client_connected` | +| mitmproxy 6 | mitmproxy 7 | +| ------------------ | --------------------- | +| `clientconnect` | `client_connected` | | `clientdisconnect` | `client_disconnected` | -| ❌ | `server_connect` | -| `serverconnect` | `server_connected` | +| ❌ | `server_connect` | +| `serverconnect` | `server_connected` | | `serverdisconnect` | `server_disconnected` | #### Logging @@ -43,4 +43,4 @@ mitmproxy 6 had a custom WebSocketFlow class, which had [ugly co-dependencies with the related HTTPFlow](https://github.com/mitmproxy/mitmproxy/issues/4425). Long story short, WebSocketFlow is no more and instead HTTPFlow has a neat [`.websocket` attribute]({{< relref "api/mitmproxy.http.md#HTTPFlow.websocket" >}}). All WebSocket flows are now passed -the originating `HTTPFlow` with this attribute set. +the originating `HTTPFlow` with this attribute set. As always, existing dumpfiles are automatically converted on load. From a33ab986ba1284027263770d3758cb93a4d01da5 Mon Sep 17 00:00:00 2001 From: Maximilian Hils Date: Tue, 22 Jun 2021 16:51:33 +0200 Subject: [PATCH 3/3] revise based on @prinzhorn's feedback --- docs/src/content/addons-api-changelog.md | 24 +++++++++++++++++++++--- 1 file changed, 21 insertions(+), 3 deletions(-) diff --git a/docs/src/content/addons-api-changelog.md b/docs/src/content/addons-api-changelog.md index 2bbf51a04..2ebca9d94 100644 --- a/docs/src/content/addons-api-changelog.md +++ b/docs/src/content/addons-api-changelog.md @@ -14,9 +14,18 @@ We try to avoid them, but this page lists breaking changes in the mitmproxy addo #### Connection Events -We've revised mitmproxy's connection-specific event hooks as part of the new proxy core. See the new -[event hook documentation]({{< relref "addons-api#ConnectionEvents" >}}) for details. As the passed objects are slightly -different now, we've also taken this opportunity to introduce a consistent event names: +We've revised mitmproxy's connection-specific event hooks as part of the new proxy core. The `.client_conn` and +`.server_conn` objects have major API changes across the board. See the new +[event hook documentation]({{< relref "addons-api#ConnectionEvents" >}}) for details. + +| Attribute | Client (v6) | Server (v6) | mitmproxy v7 | +|----------------|-------------|-------------------|--------------| +| Remote IP:Port | `.address` | `.ip_address` | `.peername` | +| Local IP:Port | ❌ | `.source_address` | `.sockname` | +| Remote Domain | N/A | `.address` | `.address` | + + +As the passed objects are different now, we've also taken this opportunity to introduce more consistent event names: | mitmproxy 6 | mitmproxy 7 | | ------------------ | --------------------- | @@ -44,3 +53,12 @@ mitmproxy 6 had a custom WebSocketFlow class, which had WebSocketFlow is no more and instead HTTPFlow has a neat [`.websocket` attribute]({{< relref "api/mitmproxy.http.md#HTTPFlow.websocket" >}}). All WebSocket flows are now passed the originating `HTTPFlow` with this attribute set. As always, existing dumpfiles are automatically converted on load. + +#### Certificates + +mitmproxy now uses `cryptography` instead of `pyOpenSSL` to generate certificates. As a consequence, the API of +`mitmproxy.certs` has changed. + +#### HTTP Headers + +`mitmproxy.net.http.Headers` -> `mitmproxy.http.Headers` for consistency.