Grasscutters/mitmproxy
3
0
Fork 0
mirror of https://github.com/Grasscutters/mitmproxy.git synced 2024-11-27 02:24:18 +00:00
Code Issues Projects Releases Wiki Activity

Convert documentation to HTML, fix styling.

Browse Source
This commit is contained in:
Aldo Cortesi 2012-07-20 23:19:58 +12:00
parent 21ef35fd28
commit 2bdbbaa8af
3 changed files with 277 additions and 247 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

19
libpathod/static/pathod.css Normal file
View File

@ -0,0 +1,19 @@
section {
margin-top: 50px;
}
.example {
margin-top: 10px;
margin-bottom: 10px;
}
.terminal {
margin-top: 10px;
margin-bottom: 10px;
background: #000;
color: #fff;
}

272
libpathod/templates/docs_pathod.html
View File

@ -1,5 +1,6 @@
{% extends "frame.html" %}
{% block body %}
<div class="page-header">
<h1>
pathod
@ -7,121 +8,122 @@
</h1>
</div>
At pathod's heart is a small, terse language for crafting HTTP responses,
<p>At pathod's heart is a small, terse language for crafting HTTP responses,
designed to be easy to specify in a request URL. The simplest way to use
pathod is to fire up the daemon, and specify the response behaviour you
want using this language in the request URL. Here's a minimal example:
want using this language in the request URL. Here's a minimal example:</p>
http://localhost:9999/p/200
<pre class="example">http://localhost:9999/p/200</pre>
Everything after the "/p/" path component is a response specifier - in this
<p>Everything after the "/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:
whenever a matching URL is requested:</p>
pathod -a "/foo=200"
<pre class="terminal">pathod -a "/foo=200"</pre>
Here, "/foo" a regex specifying the anchor path, and the part after the "=" is
a response specifier.
<p>Here, "/foo" a regex specifying the anchor path, and the part after the "=" is
a response specifier.</p>
pathod also has a nifty built-in web interface, which lets you play with
<p>pathod also has a nifty built-in web interface, which lets you play with
the language by previewing responses, exposes activity logs, online help and
various other goodies. Try it by visiting the server root:
various other goodies. Try it by visiting the server root:</p>
http://localhost:9999
<pre class="example">http://localhost:9999</pre>
<section id="specifying_responses">
<div class="page-header">
<div class="page-header">
<h1>Specifying Responses</h1>
</div>
</div>
The general form of a response is as follows:
<p>The general form of a response is as follows:
code[MESSAGE]:[colon-separated list of features]
<pre class="example">code[MESSAGE]:[colon-separated list of features]</pre></p>
Here's the simplest possible response specification, returning just an HTTP 200
OK message with no headers and no content:
<p>Here's the simplest possible response specification, returning just an HTTP 200
OK message with no headers and no content:
200
<pre class="example">200</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>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>
200"YAY"
<pre class="example">200"YAY"</pre>
The quoted string here is an example of a <a href=#valuespec>Value
Specifier</a>, 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>The quoted string here is an example of a <a href=#valuespec>Value
Specifier</a>, 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>
200@100k,ascii_letters
<pre class="example">200@100k,ascii_letters</pre>
Full documentation on the value specification syntax can be found in the next
section.
<p>Full documentation on the value specification syntax can be found in the next
section.
Following the response code specifier is a colon-separated list of features.
For instance, this specifies a response with a body consisting of 1 megabyte of
random data:
Following the response code specifier is a colon-separated list of features.
For instance, this specifies a response with a body consisting of 1 megabyte of
random data:</p>
200:b@1m
<pre class="example">200:b@1m</pre>
And this is the same response with an ETag header added:
<p>And this is the same response with an ETag header added:</p>
200:b@1m:h"Etag"="foo"
<pre class="example">200:b@1m:h"Etag"="foo"</pre>
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>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>
200:b@1m:h@1k,ascii_letters="foo"
<pre class="example">200:b@1m:h@1k,ascii_letters="foo"</pre>
A few specific headers have shortcuts, because they're used so often. The
shortcut for the content-type header is "c":
<p>A few specific headers have shortcuts, because they're used so often. The
shortcut for the content-type header is "c":</p>
200:b@1m:c"text/json"
<pre class="example">200:b@1m:c"text/json"</pre>
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>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>
200:b@1m:p120,50
<pre class="example">200:b@1m:p120,50</pre>
If that's not long enough, we can tell pathod to hang forever:
<p>If that's not long enough, we can tell pathod to hang forever:</p>
200:b@1m:p120,f
<pre class="example">200:b@1m:p120,f</pre>
Or to send all data, and then hang without disconnecting:
<p>Or to send all data, and then hang without disconnecting:</p>
200:b@1m:p120,a
<pre class="example">200:b@1m:p120,a</pre>
We can also ask pathod to hang randomly:
<p>We can also ask pathod to hang randomly:</p>
200:b@1m:pr,a
<pre class="example">200:b@1m:pr,a</pre>
There is a similar mechanism for dropping connections mid-response. So, we can
tell pathod to disconnect after sending 50 bytes:
<p>There is a similar mechanism for dropping connections mid-response. So, we can
tell pathod to disconnect after sending 50 bytes:</p>
200:b@1m:d50
<pre class="example">200:b@1m:d50</pre>
Or randomly:
<p>Or randomly:</p>
200:b@1m:dr
<pre class="example">200:b@1m:dr</pre>
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>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>
200:b@1m:p10,10:p20,10:d5000
<pre class="example">200:b@1m:p10,10:p20,10:d5000</pre>
## Response Features
<h2>Response Features</h2>
<table class="table table-bordered table-condensed">
<table class="table table-bordered">
<tbody >
<tr>
<td>
@ -162,7 +164,7 @@ once at 10 bytes and once at 20, then disconnects at 5000:
<td>
A shortcut for setting the Location header. Equivalent to:
<pre>h"Content-Type"=VALUE</pre>
<pre>h"Location"=VALUE</pre>
</td>
</tr>
@ -189,62 +191,60 @@ once at 10 bytes and once at 20, then disconnects at 5000:
</td>
</tr>
</tbody>
</table>
</table>
<a id="valuespec"></a>
## VALUE Specifiers
<a id="valuespec"></a>
<h2>VALUE Specifiers</h2>
There are three different flavours of value specification.
<h3>Literals</h3>
### Literal
<p>Literal values are specified as a quoted strings: </p>
Literal values are specified as a quoted strings:
<pre class="example">"foo"</pre>
"foo"
<p>Either single or double quotes are accepted, and quotes can be escaped with
backslashes within the string:</p>
Either single or double quotes are accepted, and quotes can be escaped with
backslashes within the string:
'fo\'o'
<pre class="example">'fo\'o'</pre>
### Files
<h3>Files</h3>
You can load a value from a specified file path. To do so, you have to specify
a _staticdir_ option to pathod on the command-line, like so:
<p>You can load a value from a specified file path. To do so, you have to specify
a _staticdir_ option to pathod on the command-line, like so: </p>
pathod -d ~/myassets
<pre class="example">pathod -d ~/myassets</pre>
All paths are relative paths under this directory. File loads are indicated by
starting the value specifier with the left angle bracket:
<p>All paths are relative paths under this directory. File loads are indicated by
starting the value specifier with the left angle bracket:
<my/path
<pre class="example">&lt;my/path</pre></p>
The path value can also be a quoted string, with the same syntax as literals:
<p>The path value can also be a quoted string, with the same syntax as literals:</p>
<"my/path"
<pre class="example">&lt;"my/path"</pre>
### Generated values
<h3>Generated values</h3>
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>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>
Here's a value specifier for generating 100 bytes:
<p>Here's a value specifier for generating 100 bytes:
@100
<pre class="example">@100</pre></p>
You can use standard suffixes to indicate larger values. Here, for instance, is
a specifier for generating 100 megabytes:
<p>You can use standard suffixes to indicate larger values. Here, for instance, is
a specifier for generating 100 megabytes:</p>
@100m
<pre class="example">@100m</pre>
Data is generated and served efficiently - if you really want to send a
terabyte of data to a client, pathod can do it. The supported suffixes are:
<p>Data is generated and served efficiently - if you really want to send a
terabyte of data to a client, pathod can do it. The supported suffixes are:</p>
<table class="table table-bordered table-condensed">
<table class="table table-bordered">
<tbody >
<tr>
<td>b</td> <td>1024**0 (bytes)</td>
@ -262,41 +262,46 @@ terabyte of data to a client, pathod can do it. The supported suffixes are:
<td>t</td> <td>1024**4 (terabytes)</td>
</tr>
</tbody>
</table>
</table>
Data types are separated from the size specification by a comma. This
specification generates 100mb of ASCII:
<p>Data types are separated from the size specification by a comma. This
specification generates 100mb of ASCII:</p>
@100m,ascii
<pre class="example">@100m,ascii</pre>
Supported data types are:
<p>Supported data types are:</p>
- ascii_letters
- ascii_lowercase
- ascii_uppercase
- digits
- hexdigits
- letters
- lowercase
- octdigits
- printable
- punctuation
- uppercase
- whitespace
- ascii
- bytes
<ul>
<li>ascii_letters</li>
<li>ascii_lowercase</li>
<li>ascii_uppercase</li>
<li>digits</li>
<li>hexdigits</li>
<li>letters</li>
<li>lowercase</li>
<li>octdigits</li>
<li>printable</li>
<li>punctuation</li>
<li>uppercase</li>
<li>whitespace</li>
<li>ascii</li>
<li>bytes</li>
</ul>
</section>
<div class="page-header">
<section id="api">
<div class="page-header">
<h1>API</h1>
</div>
</div>
pathod exposes a simple API, intended to make it possible to drive and
inspect the daemon remotely for use in unit testing and the like.
<p>pathod exposes a simple API, intended to make it possible to drive and
inspect the daemon remotely for use in unit testing and the like. </p>
<table class="table table-bordered table-condensed">
<table class="table table-bordered">
<tbody >
<tr>
<td>
@ -330,17 +335,22 @@ inspect the daemon remotely for use in unit testing and the like.
</td>
</tr>
</tbody>
</table>
</table>
</section>
<div class="page-header">
<section>
<div class="page-header">
<h1>Error Responses</h1>
</div>
</div>
To let users distinguish crafted responses from internal pathod responses,
pathod uses the non-standard 800 response code to indicate errors. For example,
a request to:
<p>To let users distinguish crafted responses from internal pathod responses,
pathod uses the non-standard 800 response code to indicate errors. For example,
a request to:</p>
http://localhost:9999/p/foo
<pre class="example">http://localhost:9999/p/foo</pre>
<p>... will return an 800 response, because "foo" is not a valid page specifier.</p>
</section>
... will return an 800 response, because "foo" is not a valid page specifier.
{% endblock %}

1
libpathod/templates/frame.html
View File

@ -4,6 +4,7 @@
<meta charset="utf-8">
<title>pathod</title>
<link href="/static/bootstrap.min.css" rel="stylesheet">
<link href="/static/pathod.css" rel="stylesheet">
<link href="/static/syntax.css" rel="stylesheet">
<script src="/static/jquery-1.7.2.min.js"></script>
<script src="/static/bootstrap.min.js"></script>