mirror of
https://github.com/Grasscutters/mitmproxy.git
synced 2024-11-23 16:17:49 +00:00
372 lines
11 KiB
HTML
372 lines
11 KiB
HTML
{% extends "frame.html" %}
|
|
{% block body %}
|
|
|
|
<div class="page-header">
|
|
<h1>
|
|
pathod
|
|
<small>A pathological web daemon.</small>
|
|
</h1>
|
|
</div>
|
|
|
|
<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:</p>
|
|
|
|
<pre class="example">http://localhost:9999/p/200</pre>
|
|
|
|
<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:</p>
|
|
|
|
<pre class="terminal">pathod -a "/foo=200"</pre>
|
|
|
|
<p>Here, "/foo" a regex specifying the anchor path, and the part after the "=" is
|
|
a response specifier.</p>
|
|
|
|
<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:</p>
|
|
|
|
<pre class="example">http://localhost:9999</pre>
|
|
|
|
|
|
<section id="specifying_responses">
|
|
|
|
<div class="page-header">
|
|
<h1>Specifying Responses</h1>
|
|
</div>
|
|
|
|
<p>The general form of a response is as follows:
|
|
|
|
<pre class="example">code[MESSAGE]:[colon-separated list of features]</pre></p>
|
|
|
|
<p>Here's the simplest possible response specification, returning just an HTTP 200
|
|
OK message with no headers and no content:
|
|
|
|
<pre class="example">200</pre></p>
|
|
|
|
<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 class="example">200"YAY"</pre>
|
|
|
|
<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>
|
|
|
|
<pre class="example">200@100k,ascii_letters</pre>
|
|
|
|
<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:</p>
|
|
|
|
<pre class="example">200:b@1m</pre>
|
|
|
|
<p>And this is the same response with an ETag header added:</p>
|
|
|
|
<pre class="example">200:b@1m:h"Etag"="foo"</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 class="example">200:b@1m:h@1k,ascii_letters="foo"</pre>
|
|
|
|
<p>A few specific headers have shortcuts, because they're used so often. The
|
|
shortcut for the content-type header is "c":</p>
|
|
|
|
<pre class="example">200:b@1m:c"text/json"</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 class="example">200:b@1m:p120,50</pre>
|
|
|
|
<p>If that's not long enough, we can tell pathod to hang forever:</p>
|
|
|
|
<pre class="example">200:b@1m:p120,f</pre>
|
|
|
|
<p>Or to send all data, and then hang without disconnecting:</p>
|
|
|
|
<pre class="example">200:b@1m:p120,a</pre>
|
|
|
|
<p>We can also ask pathod to hang randomly:</p>
|
|
|
|
<pre class="example">200:b@1m:pr,a</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 class="example">200:b@1m:d50</pre>
|
|
|
|
<p>Or randomly:</p>
|
|
|
|
<pre class="example">200:b@1m:dr</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 class="example">200:b@1m:p10,10:p20,10:d5000</pre>
|
|
|
|
|
|
<h2>Response Features</h2>
|
|
|
|
<table class="table table-bordered">
|
|
<tbody >
|
|
<tr>
|
|
<td>
|
|
hKEY=VALUE
|
|
</td>
|
|
<td>
|
|
Set a header. Both KEY and VALUE are full <a href=#valuespec>Value Specifiers</a>.
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>
|
|
bVALUE
|
|
</td>
|
|
<td>
|
|
Set the body. VALUE is a <a href=#valuespec>Value
|
|
Specifier</a>. When the body is set, pathod will
|
|
automatically set the appropriate Content-Length header.
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>
|
|
cVALUE
|
|
</td>
|
|
<td>
|
|
A shortcut for setting the Content-Type header. Equivalent to:
|
|
|
|
<pre>h"Content-Type"=VALUE</pre>
|
|
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>
|
|
iOFFSET,VALUE
|
|
</td>
|
|
<td>
|
|
Inject the specified value at the offset. OFFSET can be an
|
|
integer, or "r" to generate a random offset or "a" for an
|
|
offset just after all data has been sent.
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>
|
|
lVALUE
|
|
</td>
|
|
<td>
|
|
A shortcut for setting the Location header. Equivalent to:
|
|
|
|
<pre>h"Location"=VALUE</pre>
|
|
|
|
</td>
|
|
</tr>
|
|
|
|
|
|
<tr>
|
|
<td>
|
|
dOFFSET
|
|
</td>
|
|
<td>
|
|
Disconnect after OFFSET bytes. The offset can also be "r", in which case pathod
|
|
will disconnect at a random point in the response.
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>
|
|
pSECONDS,OFFSET
|
|
</td>
|
|
<td>
|
|
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.
|
|
</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
|
|
<a id="valuespec"></a>
|
|
<h2>VALUE Specifiers</h2>
|
|
|
|
<h3>Literals</h3>
|
|
|
|
<p>Literal values are specified as a quoted strings: </p>
|
|
|
|
<pre class="example">"foo"</pre>
|
|
|
|
<p>Either single or double quotes are accepted, and quotes can be escaped with
|
|
backslashes within the string:</p>
|
|
|
|
<pre class="example">'fo\'o'</pre>
|
|
|
|
<p>Literal values can contain Python-style backslash escape sequences:</p>
|
|
|
|
<pre class="example">'foo\r\nbar'</pre>
|
|
|
|
|
|
<h3>Files</h3>
|
|
|
|
<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>
|
|
|
|
<pre class="example">pathod -d ~/myassets</pre>
|
|
|
|
<p>All paths are relative paths under this directory. File loads are indicated by
|
|
starting the value specifier with the left angle bracket:
|
|
|
|
<pre class="example"><my/path</pre></p>
|
|
|
|
<p>The path value can also be a quoted string, with the same syntax as literals:</p>
|
|
|
|
<pre class="example"><"my/path"</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:
|
|
|
|
<pre class="example">@100</pre></p>
|
|
|
|
<p>You can use standard suffixes to indicate larger values. Here, for instance, is
|
|
a specifier for generating 100 megabytes:</p>
|
|
|
|
<pre class="example">@100m</pre>
|
|
|
|
<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">
|
|
<tbody >
|
|
<tr>
|
|
<td>b</td> <td>1024**0 (bytes)</td>
|
|
</tr>
|
|
<tr>
|
|
<td>k</td> <td>1024**1 (kilobytes)</td>
|
|
</tr>
|
|
<tr>
|
|
<td>m</td> <td>1024**2 (megabytes)</td>
|
|
</tr>
|
|
<tr>
|
|
<td>g</td> <td>1024**3 (gigabytes)</td>
|
|
</tr>
|
|
<tr>
|
|
<td>t</td> <td>1024**4 (terabytes)</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
|
|
<p>Data types are separated from the size specification by a comma. This
|
|
specification generates 100mb of ASCII:</p>
|
|
|
|
<pre class="example">@100m,ascii</pre>
|
|
|
|
<p>Supported data types are:</p>
|
|
|
|
|
|
<ul>
|
|
<li>ascii</li>
|
|
<li>ascii_letters</li>
|
|
<li>ascii_lowercase</li>
|
|
<li>ascii_uppercase</li>
|
|
<li>bytes</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>
|
|
</ul>
|
|
|
|
</section>
|
|
|
|
|
|
<section id="api">
|
|
<div class="page-header">
|
|
<h1>API</h1>
|
|
</div>
|
|
|
|
<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">
|
|
<tbody >
|
|
<tr>
|
|
<td>
|
|
/api/clear_log
|
|
</td>
|
|
<td>
|
|
A POST to this URL clears the log buffer.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
/api/info
|
|
</td>
|
|
<td>
|
|
Basic version and configuration info.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
/api/log
|
|
</td>
|
|
<td>
|
|
Returns the current log buffer. At the moment the buffer size is 500 entries -
|
|
when the log grows larger than this, older entries are discarded. The returned
|
|
data is a JSON dictionary, with the form:
|
|
|
|
<pre>{ 'log': [ ENTRIES ] } </pre>
|
|
|
|
You can preview the JSON data returned for a log entry through the built-in web
|
|
interface.
|
|
</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</section>
|
|
|
|
<section>
|
|
<div class="page-header">
|
|
<h1>Error Responses</h1>
|
|
</div>
|
|
|
|
<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>
|
|
|
|
<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>
|
|
|
|
{% endblock %}
|