mitmproxy/libpathod/templates/docs_pathod.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=/docs/language#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:p50,120</pre>

    <p>If that's not long enough, we can tell pathod to hang forever:</p>

    <pre class="example">200:b@1m:pf,120</pre>

    <p>Or to send all data, and then hang without disconnecting:</p>

    <pre class="example">200:b@1m:pa,120</pre>

    <p>We can also ask pathod to hang randomly:</p>

    <pre class="example">200:b@1m:pr,10</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>




<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>Pathod uses the non-standard 800 response code to indicate internal
    errors, to distinguish them from crafted responses. 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 %}