From 3cb459d56daeae8fd2b923c27f39ca5595a50e7b Mon Sep 17 00:00:00 2001 From: Thomas Kriechbaumer Date: Thu, 17 Aug 2017 10:18:05 +0200 Subject: [PATCH] docs++: add individual protocol pages --- docs/features/passthrough.rst | 4 ++-- docs/index.rst | 10 +++++++++- docs/protocols/http1.rst | 15 +++++++++++++++ docs/protocols/http2.rst | 16 ++++++++++++++++ docs/{features => protocols}/tcpproxy.rst | 6 +++--- docs/protocols/websocket.rst | 17 +++++++++++++++++ docs/scripting/events.rst | 2 +- 7 files changed, 63 insertions(+), 7 deletions(-) create mode 100644 docs/protocols/http1.rst create mode 100644 docs/protocols/http2.rst rename docs/{features => protocols}/tcpproxy.rst (93%) create mode 100644 docs/protocols/websocket.rst diff --git a/docs/features/passthrough.rst b/docs/features/passthrough.rst index 00462e9d9..dbaf35061 100644 --- a/docs/features/passthrough.rst +++ b/docs/features/passthrough.rst @@ -13,7 +13,7 @@ mechanism: away. Note that mitmproxy's "Limit" option is often the better alternative here, as it is not affected by the limitations listed below. -If you want to peek into (SSL-protected) non-HTTP connections, check out the :ref:`tcpproxy` +If you want to peek into (SSL-protected) non-HTTP connections, check out the :ref:`tcp_proxy` feature. If you want to ignore traffic from mitmproxy's processing because of large response bodies, take a look at the :ref:`streaming` feature. @@ -88,7 +88,7 @@ Here are some other examples for ignore patterns: .. seealso:: - - :ref:`tcpproxy` + - :ref:`tcp_proxy` - :ref:`streaming` - mitmproxy's "Limit" feature diff --git a/docs/index.rst b/docs/index.rst index 7cf593ff2..8dba4d04d 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -20,6 +20,15 @@ mitmweb config +.. toctree:: + :hidden: + :caption: Protocols + + protocols/http1 + protocols/http2 + protocols/websocket + protocols/tcpproxy + .. toctree:: :hidden: :caption: Features @@ -36,7 +45,6 @@ features/streaming features/socksproxy features/sticky - features/tcpproxy features/upstreamproxy features/upstreamcerts diff --git a/docs/protocols/http1.rst b/docs/protocols/http1.rst new file mode 100644 index 000000000..21e68785e --- /dev/null +++ b/docs/protocols/http1.rst @@ -0,0 +1,15 @@ +.. _http1_protocol: + +HTTP/1.0 and HTTP/1.1 +=========================== + +.. seealso:: + + - `RFC7230: HTTP/1.1: Message Syntax and Routing `_ + - `RFC7231: HTTP/1.1: Semantics and Content `_ + +HTTP/1.0 and HTTP/1.1 support in mitmproxy is based on our custom HTTP stack, +which takes care of all semantics and on-the-wire parsing/serialization tasks. + +mitmproxy currently does not support HTTP trailers - but if you want to send +us a PR, we promise to take look! diff --git a/docs/protocols/http2.rst b/docs/protocols/http2.rst new file mode 100644 index 000000000..b3268ae5b --- /dev/null +++ b/docs/protocols/http2.rst @@ -0,0 +1,16 @@ +.. _http2_protocol: + +HTTP/2 +====== + +.. seealso:: + + - `RFC7540: Hypertext Transfer Protocol Version 2 (HTTP/2) `_ + +HTTP/2 support in mitmproxy is based on the amazing work by the python-hyper +community with the `hyper-h2 `_ +project. It fully encapsulates the internal state of HTTP/2 connections and +provides an easy-to-use event-based API. + +mitmproxy currently does not support HTTP/2 trailers - but if you want to send +us a PR, we promise to take look! diff --git a/docs/features/tcpproxy.rst b/docs/protocols/tcpproxy.rst similarity index 93% rename from docs/features/tcpproxy.rst rename to docs/protocols/tcpproxy.rst index cba374e3d..772485732 100644 --- a/docs/features/tcpproxy.rst +++ b/docs/protocols/tcpproxy.rst @@ -1,7 +1,7 @@ -.. _tcpproxy: +.. _tcp_proxy: -TCP Proxy -========= +TCP Proxy / Fallback +==================== In case mitmproxy does not handle a specific protocol, you can exempt hostnames from processing, so that mitmproxy acts as a generic TCP forwarder. diff --git a/docs/protocols/websocket.rst b/docs/protocols/websocket.rst new file mode 100644 index 000000000..85cff3aca --- /dev/null +++ b/docs/protocols/websocket.rst @@ -0,0 +1,17 @@ +.. _websocket_protocol: + +WebSocket +========= + +.. seealso:: + + - `RFC6455: The WebSocket Protocol `_ + - `RFC7692: Compression Extensions for WebSocket `_ + +WebSocket support in mitmproxy is based on the amazing work by the python-hyper +community with the `wsproto `_ +project. It fully encapsulates WebSocket frames/messages/connections and +provides an easy-to-use event-based API. + +mitmproxy fully supports the compression extension for WebSocket messages, +provided by wsproto. diff --git a/docs/scripting/events.rst b/docs/scripting/events.rst index 8f9463ffe..9e84dacfe 100644 --- a/docs/scripting/events.rst +++ b/docs/scripting/events.rst @@ -211,7 +211,7 @@ TCP Events ---------- These events are called only if the connection is in :ref:`TCP mode -`. So, for instance, TCP events are not called for ordinary HTTP/S +`. So, for instance, TCP events are not called for ordinary HTTP/S connections. .. list-table::