From 982508d30f887b4fe8b2a855792ae1e33f378222 Mon Sep 17 00:00:00 2001 From: Aldo Cortesi Date: Thu, 22 Feb 2018 17:21:34 +1300 Subject: All new documentation This patch does a lot. - Ditch sphinx in favor of hugo. This gives us complete control of the layout and presentation of our docs. Henceforth, docs will be hosted on our website rather than ReadTheDocs. - Create a simple, clean doc layout and theme. - Remove large parts of the documentaion. I've ditched anything that was a) woefully out of date, b) too detailed, or c) too hard to maintain in the long term. - Huge updates to the docs themselves: completely rewrite addons documentation, add docs for core concepts like commands and options, and revise and tweak a lot of the existing docs. With this patch, we're also changing the way we publish and maintain the docs. From now on, we don't publish docs for every release. Instead, the website will contain ONE set of docs for each major release. The online docs will be updated if needed as minor releases are made. Docs are free to improve during minor releases, but anything that changes behaviour sufficiently to require a doc change warrants a new major release. This also leaves us free to progressively update and improve docs out of step with our release cadence. With this new scheme, I feel CI over the docs is less important. I've removed it for now, but won't object if someone wants to add it back in. --- docs/src/content/addons-overview.md | 74 +++++++++++++++++++++++++++++++++++++ 1 file changed, 74 insertions(+) create mode 100644 docs/src/content/addons-overview.md (limited to 'docs/src/content/addons-overview.md') diff --git a/docs/src/content/addons-overview.md b/docs/src/content/addons-overview.md new file mode 100644 index 00000000..6aa1207e --- /dev/null +++ b/docs/src/content/addons-overview.md @@ -0,0 +1,74 @@ +--- +title: "Addons" +menu: + addons: + weight: 1 +--- + +# Addons + +Mitmproxy's addon mechanism consists of a set of APIs that support components of +any complexity. Addons interact with mitmproxy by responding to **events**, +which allow them to hook into and change mitmproxy's behaviour. They are +configured through **[options]({{< relref concepts-options >}})**, which can be +set in mitmproxy's config file, changed interactively by users, or passed on the +command-line. Finally, they can expose **commands**, which allows users to +invoke their actions either directly or by binding them to keys in the +interactive tools. + +Addons are an exceptionally powerful part of mitmproxy. In fact, much of +mitmproxy's own functionality is defined in [a suite of built-in +addons](https://github.com/mitmproxy/mitmproxy/tree/master/mitmproxy/addons), +implementing everything from functionality like [anticaching]({{< relref +"overview-features#anticache" >}}) and [sticky cookies]({{< relref +"overview-features#sticky-cookies" >}}) to our onboarding webapp. The built-in +addons make for instructive reading, and you will quickly see that quite complex +functionality can often boil down to a very small, completely self-contained +modules. Mitmproxy provides the exact same set of facilities it uses for its own +functionality to third-party scripters and extenders. + +This document will show you how to build addons using **events**, **options** +and **commands**. However, this is not an API manual, and the mitmproxy source +code remains the canonical reference. One easy way to explore the API from the +command-line is to use [pydoc](https://docs.python.org/3/library/pydoc.html). +Here, for example, is a command that shows the API documentation for the +mitmproxy's HTTP flow classes: + +{{< highlight bash >}} +pydoc mimtproxy.http +{{< /highlight >}} + +You will be referring to the mitmproxy API documentation frequently, so keep +**pydoc** or an equivalent handy. + +# Anatomy of an addon + +{{< example src="examples/addons/anatomy.py" lang="py" >}} + +Above is a simple addon that keeps track of the number of flows (or more +specifically HTTP requests) we've seen. Every time it sees a new flow, it uses +mitmproxy's internal logging mechanism to announce its tally. The output can be +found in the event log in the interactive tools, or on the console in mitmdump. + +Take it for a spin and make sure that it does what it's supposed to, by loading +it into your mitmproxy tool of choice. We'll use mitmpdump in these examples, +but the flag is identical for all tools: + +{{< highlight bash >}} +> mitmdump -s ./anatomy.py +{{< /highlight >}} + +Here are a few things to note about the code above: + +- Mitmproxy picks up the contents of the `addons` global list and loads what it + finds into the addons mechanism. +- Addons are just objects - in this case our addon is an instance of `Counter`. +- The `request` method is an example of an **event**. Addons simply implement a + method for each event they wan to handle. Each event has a signature + consisting of arguments that are passed to the method. For `request`, this is + an instance of `mitmproxy.http.HTTPFlow`. +- Finally, the `ctx` module is a holdall module that exposes a set of standard + objects that are commonly used in addons. We could pass a `ctx` object as the + first parameter to every event, but we've found it neater to just expose it as + an importable global. In this case, we're using the `ctx.log` object to do our + logging. \ No newline at end of file -- cgit v1.2.3