diff options
author | Aldo Cortesi <aldo@nullcube.com> | 2012-04-29 18:56:49 +1200 |
---|---|---|
committer | Aldo Cortesi <aldo@nullcube.com> | 2012-04-29 18:56:49 +1200 |
commit | 37e880b3990e2729d857b0f3a24f80d45116b7f0 (patch) | |
tree | 9214f79c37bee8bd69ce9bf11cd16bdc7fa152fb | |
parent | d5aa88e0920b1d86edbc2bcf049e4c13f6c9bdc9 (diff) | |
download | mitmproxy-37e880b3990e2729d857b0f3a24f80d45116b7f0.tar.gz mitmproxy-37e880b3990e2729d857b0f3a24f80d45116b7f0.tar.bz2 mitmproxy-37e880b3990e2729d857b0f3a24f80d45116b7f0.zip |
Add a rendered version of the docs to the web app.
-rw-r--r-- | README.mkd | 2 | ||||
-rw-r--r-- | libpathod/templates/help.html | 252 | ||||
-rw-r--r-- | todo | 3 |
3 files changed, 254 insertions, 3 deletions
@@ -126,12 +126,14 @@ Set a header. Both KEY and VALUE are full _Value Specifiers_. Set the body. VALUE is a _Value Specifier_. When the body is set, Pathod will automatically set the appropriate Content-Length header. + #### cVALUE A shortcut for setting the Content-Type header. Equivalent to: h"Content-Type"=VALUE + #### lVALUE A shortcut for setting the Location header. Equivalent to: diff --git a/libpathod/templates/help.html b/libpathod/templates/help.html index 20d884c5..3ab48c95 100644 --- a/libpathod/templates/help.html +++ b/libpathod/templates/help.html @@ -1,4 +1,254 @@ {% extends frame.html %} {% block body %} - <h1> Help </h1> +<!-- Text below generated with "markdown2 README.mkd" --> + +<h1>Pathod</h1> + +<p>Pathod is a pathological HTTP/S daemon, useful for testing and torturing client +software. At Pathod's core is a small, terse language for crafting HTTP +responses. The simplest way to use Pathod is to fire up the daemon, and specify +the respnse behaviour you want using this language in the request URL. Here's a +minimal example:</p> + +<pre><code>http://localhost:9999/p/200 +</code></pre> + +<p>Everything below the magic "/p/" path component is a response specifier - in +this case just a vanilla 200 OK response. See the docs below to get (much) +fancier. You can also add anchors to the Pathod server that serve a fixed +response whenever a matching URL is requested:</p> + +<pre><code>pathod --anchor "/foo=200" +</code></pre> + +<p>Here, the part before the "=" is a regex specifying the anchor path, and the +part after is a response specifier.</p> + +<p>Pathod also has a nifty built-in web interface, which exposes activity logs, +online help and various other goodies. Try it by visiting the server root:</p> + +<pre><code>http://localhost:9999 +</code></pre> + +<h1>Specifying Responses</h1> + +<p>The general form of a response is as follows:</p> + +<pre><code>code[MESSAGE]:[colon-separated list of features] +</code></pre> + +<p>Here's the simplest possible response specification, returning just an HTTP 200 +OK message with no headers and no content:</p> + +<pre><code>200 +</code></pre> + +<p>We can embellish this a bit by specifying an optional custom HTTP response +message (if we don't, Pathod automatically creates an appropriate one). By +default for a 200 response code the message is "OK", but we can change it like +this:</p> + +<pre><code>200"YAY" +</code></pre> + +<p>The quoted string here is an example of a Value Specifier, a syntax that is +used throughout the Pathod response specification language. In this case, the +quotes mean we're specifying a literal string, but there are many other fun +things we can do. For example, we can tell Pathod to generate 100k of random +ASCII letters instead:</p> + +<pre><code>200@100k,ascii_letters +</code></pre> + +<p>Full documentation on the value specification syntax can be found in the next +section. </p> + +<p>Following the response code specifier is a colon-separateed list of features. +For instance, this specifies a response with a body consisting of 1 megabyte of +random data:</p> + +<pre><code>200:b@1m +</code></pre> + +<p>And this is the same response with an ETag header added:</p> + +<pre><code>200:b@1m:h"Etag"="foo" +</code></pre> + +<p>Both the header name and the header value are full value specifiers. Here's the +same response again, but with a 1k randomly generated header name:</p> + +<pre><code>200:b@1m:h@1k,ascii_letters="foo" +</code></pre> + +<p>A few specific headers have shortcuts, because they're used so often. The +shorcut for the content-type header is "c":</p> + +<pre><code>200:b@1m:c"text/json" +</code></pre> + +<p>That's it for the basic response definition. Now we can start mucking with the +responses to break clients. One common hard-to-test circumstance is hangs or +slow responses. Pathod has a pause operator that you can use to define +precisely when and how long the server should hang. Here, for instance, we hang +for 120 seconds after sending 50 bytes (counted from the first byte of the HTTP +response):</p> + +<pre><code>200:b@1m:p120,50 +</code></pre> + +<p>If that's not long enough, we can tell Pathod to hang forever:</p> + +<pre><code>200:b@1m:p120,f +</code></pre> + +<p>Or to send all data, and then hang without disconnecting:</p> + +<pre><code>200:b@1m:p120,a +</code></pre> + +<p>We can also ask Pathod to hang randomly:</p> + +<pre><code>200:b@1m:pr,a +</code></pre> + +<p>There is a similar mechanism for dropping connections mid-response. So, we can +tell Pathod to disconnect after sending 50 bytes:</p> + +<pre><code>200:b@1m:d50 +</code></pre> + +<p>Or randomly:</p> + +<pre><code>200:b@1m:dr +</code></pre> + +<p>All of these features can be combined. Here's a response that pauses twice, +once at 10 bytes and once at 20, then disconnects at 5000:</p> + +<pre><code>200:b@1m:p10,10:p20,10:d5000 +</code></pre> + +<h1>Features</h1> + +<h4>hKEY=VALUE</h4> + +<p>Set a header. Both KEY and VALUE are full <em>Value Specifiers</em>. </p> + +<h4>bVALUE</h4> + +<p>Set the body. VALUE is a <em>Value Specifier</em>. When the body is set, Pathod will +automatically set the appropriate Content-Length header.</p> + +<h4>cVALUE</h4> + +<p>A shortcut for setting the Content-Type header. Equivalent to:</p> + +<pre><code>h"Content-Type"=VALUE +</code></pre> + +<h4>lVALUE</h4> + +<p>A shortcut for setting the Location header. Equivalent to:</p> + +<pre><code>h"Content-Type"=VALUE +</code></pre> + +<h4>dOFFSET</h4> + +<p>Disconnect after OFFSET bytes. The offset can also be "r", in which case Pathod +will disconnect at a random point in the response.</p> + +<h4>pSECONDS,OFFSET</h4> + +<p>Pause for SECONDS seconds after OFFSET bytes. SECONDS can also be "f" to pause +forever. OFFSET can also be "r" to generate a random offset, or "a" for an +offset just after all data has been sent.</p> + +<h1>Value Specifiers</h1> + +<p>There are three different flavours of value specification. </p> + +<h3>Literal</h3> + +<p>Literal values are specified as a quoted strings: </p> + +<pre><code>"foo" +</code></pre> + +<p>Either single or double quotes are accepted, and quotes can be escaped with +backslashes within the string:</p> + +<pre><code>'fo\'o' +</code></pre> + +<h3>Files</h3> + +<p>You can load a value from a specified file path. To do so, you have to specify +a <em>staticdir</em> option to Pathod on the command-line, like so: </p> + +<pre><code>pathod -d ~/myassets +</code></pre> + +<p>All paths are relative paths under this directory. File loads are indicated by +starting the value specifier with the left angle bracket:</p> + +<pre><code><my/path +</code></pre> + +<p>The path value can also be a quoted string, with the same syntax as literals:</p> + +<pre><code><"my/path" +</code></pre> + +<h3>Generated values</h3> + +<p>An @-symbol lead-in specifies that generated data should be used. There are two +components to a generator specification - a size, and a data type. By default +Pathod assumes a data type of "bytes". </p> + +<p>Here's a value specifier for generating 100 bytes:</p> + +<pre><code>@100 +</code></pre> + +<p>You can use standard suffixes to indicate larger values. Here, for instance, is +a specifier for generating 100 megabytes:</p> + +<pre><code>@100m +</code></pre> + +<p>The supported suffixes are:</p> + +<pre><code>b = 1024**0 (bytes) +k = 1024**1 (kilobytes) +m = 1024**2 (megabytes) +g = 1024**3 (gigabytes) +t = 1024**4 (terabytes) +</code></pre> + +<p>Data types are separated from the size specification by a comma. This +specification generates 100mb of ASCII:</p> + +<pre><code>@100m,ascii +</code></pre> + +<p>Supported data types are:</p> + +<pre><code>ascii_letters +ascii_lowercase +ascii_uppercase +digits +hexdigits +letters +lowercase +octdigits +printable +punctuation +uppercase +whitespace +ascii +bytes +</code></pre> + {% end %} @@ -1,8 +1,7 @@ 0.1: - Test pause at 0 bytes - - Web help document - - README + - Web status and explain - API - Logs, log reset, log retrieval - Anchor management |