mitmproxy/libpathod/templates/docs_lang.html

{% extends "docframe.html" %}
{% block body %}

<div class="page-header">
   <h1>
        Language Spec
        <small>The mini-language at the heart of pathoc and pathod.</small>
    </h1>
</div>

<ul class="nav nav-tabs">
  <li class="active" ><a href="#specifying_requests" data-toggle="tab">HTTP Requests</a></li>
  <li><a href="#specifying_responses" data-toggle="tab">HTTP Responses</a></li>
  <li><a href="#websockets" data-toggle="tab">Websocket Frames</a></li>
</ul>

<div class="tab-content">
    <div class="tab-pane" id="specifying_responses">

        <pre class="example">code:[colon-separated list of features]</pre></p>

        <table class="table table-bordered">
            <tbody >
                <tr>
                    <td> code </td>
                    <td>
                        <p>An integer specifying the HTTP response code.</p>

                        <p>The special method <b>ws</b> creates a valid
                        websocket upgrade response (code 101), and moves pathod
                        to websocket mode. Apart from that, websocket responses
                        are just like any other, and all aspects of the
                        response can be over-ridden.</p>
                    </td>
                </tr>

                <tr>
                    <td> b<a href="#valuespec">VALUE</a> </td>
                    <td>
                        Set the body. The appropriate Content-Length header is
                        added automatically unless the "r" flag is set.
                    </td>
                </tr>

                <tr>
                    <td> c<a href="#valuespec">VALUE</a> </td>
                    <td>
                        A shortcut for setting the Content-Type header. Equivalent to
                        h"Content-Type"=VALUE
                    </td>
                </tr>

                <tr>
                    <td> d<a href="#offsetspec">OFFSET</a> </td>
                    <td>
                        Disconnect after OFFSET bytes.
                    </td>
                </tr>

                <tr>
                    <td> h<a href="#valuespec">VALUE</a>=<a href="#valuespec">VALUE</a> </td>
                    <td>
                        Set a header.
                    </td>
                </tr>


                <tr>
                    <td> i<a href="#offsetspec">OFFSET</a>,<a href="#valuespec">VALUE</a> </td>
                    <td>
                        Inject the specified value at the offset.
                    </td>
                </tr>

                <tr>
                    <td> l<a href="#valuespec">VALUE</a> </td>
                    <td>
                        A shortcut for setting the Location header. Equivalent to
                        h"Location"=VALUE
                    </td>
                </tr>

                <tr>
                    <td> m<a href="#valuespec">VALUE</a> </td>
                    <td>
                        HTTP Reason message. Automatically chosen according to
                        the response code if not specified.
                    </td>
                </tr>

                <tr>
                    <td> p<a href="#offsetspec">OFFSET</a>,SECONDS </td>
                    <td>
                        Pause for SECONDS seconds after OFFSET bytes. SECONDS can
                        be an integer or "f" to pause forever.
                    </td>
                </tr>

                <tr>
                    <td> r </td>
                    <td>
                        Set the "raw" flag on this response. Pathod will not
                        calculate a Content-Length header if a body is set, or add
                        a Date header to the response.
                    </td>
                </tr>
            </tbody>
        </table>
    </div>


    <div class="tab-pane active" id="specifying_requests">

        <pre class="example">method:path:[colon-separated list of features]</pre></p>

        <table class="table table-bordered">
            <tbody >

                <tr>
                    <td> method </td>
                    <td>

                        <p>A <a href="#valuespec">VALUE</a> specifying the HTTP
                        method to use. Standard methods do not need to be
                        enclosed in quotes, while non-standard methods can be
                        specified as quoted strings.</p>

                        <p>The special method <b>ws</b> creates a valid
                        websocket upgrade GET request, and signals to pathoc to
                        switch to websocket recieve mode if the server responds
                        correctly. Apart from that, websocket requests are just
                        like any other, and all aspects of the request can be
                        over-ridden.</p>
                    </td>
                </tr>

                <tr>
                    <td> b<a href="#valuespec">VALUE</a> </td>
                    <td>
                        Set the body. The appropriate Content-Length header is
                        added automatically unless the "r" flag is set.
                    </td>
                </tr>

                <tr>
                    <td> c<a href="#valuespec">VALUE</a> </td>
                    <td>
                        A shortcut for setting the Content-Type header. Equivalent to
                        h"Content-Type"=VALUE
                    </td>
                </tr>

                <tr>
                    <td> d<a href="#offsetspec">OFFSET</a> </td>
                    <td>
                        Disconnect after OFFSET bytes.
                    </td>
                </tr>

                <tr>
                    <td> h<a href="#valuespec">VALUE</a>=<a href="#valuespec">VALUE</a> </td>
                    <td>
                        Set a header.
                    </td>
                </tr>

                <tr>
                    <td> i<a href="#offsetspec">OFFSET</a>,<a href="#valuespec">VALUE</a> </td>
                    <td>
                        Inject the specified value at the offset.
                    </td>
                </tr>

                <tr>
                    <td> p<a href="#offsetspec">OFFSET</a>,SECONDS </td>
                    <td>
                        Pause for SECONDS seconds after OFFSET bytes. SECONDS can
                        be an integer or "f" to pause forever.
                    </td>
                </tr>

                <tr>
                    <td> r </td>
                    <td>
                        Set the "raw" flag on this response. Pathod will not
                        calculate a Content-Length header if a body is set.
                    </td>
                </tr>

                <tr>
                    <td> s<a href="#valuespec">VALUE</a> </td>
                    <td>
                        An embedded Response specification, appended to the path
                        of the request.
                    </td>
                </tr>

                <tr>
                    <td> u<a href="#valuespec">VALUE</a> <br> uSHORTCUT </td>

                    <td>

                        Set a User-Agent header on this request. You can
                        specify either a complete <a
                        href="#valuespec">VALUE</a>, or a User-Agent shortcut:

                        <table class="table table-condensed">
                        {% for i in uastrings %}
                            <tr>
                                <td><b>{{ i[1] }}</b></td>
                                <td>{{ i[0] }}</td>
                            </tr>
                        {% endfor %}
                        </table>

                    </td>
                </tr>
            </tbody>
        </table>
    </div>

    <div class="tab-pane" id="websockets">

        <pre class="example">wf:[colon-separated list of features]</pre></p>

        <table class="table table-bordered">
            <tbody >

                <tr>
                    <td> b<a href="#valuespec">VALUE</a> </td>
                    <td>
                        Set the frame payload. If a masking key is present, the
                        value is encoded automatically.
                    </td>
                </tr>
                
                <tr>
                    <td> d<a href="#offsetspec">OFFSET</a> </td>
                    <td>
                        Disconnect after OFFSET bytes.
                    </td>
                </tr>

                <tr>
                    <td> i<a href="#offsetspec">OFFSET</a>,<a href="#valuespec">VALUE</a> </td>
                    <td>
                        Inject the specified value at the offset.
                    </td>
                </tr>

                <tr>
                    <td> p<a href="#offsetspec">OFFSET</a>,SECONDS </td>
                    <td>
                        Pause for SECONDS seconds after OFFSET bytes. SECONDS can
                        be an integer or "f" to pause forever.
                    </td>
                </tr>

            </tbody>
        </table>


    </div>

</div>



<section id="specifying_requests">
    <div class="page-header">
       <h1>Features</h1>
    </div>

        <a id="offsetspec"></a>
        <h2>OFFSET</h2>

            <p>Offsets are calculated relative to the base message, before any
            injections or other transforms are applied. They have 3 flavors:</p>

            <ul>
                <li>An integer byte offset </li>
                <li><b>r</b> for a random location</li>
                <li><b>a</b> for the end of the message</li>
            </ul>

        <a id="valuespec"></a>
        <h2>VALUE</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">&lt;my/path</pre></p>

        <p>The path value can also be a quoted string, with the same syntax as literals:</p>

        <pre class="example">&lt;"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>

        <table class="table table-bordered">
            <tbody >
                <tr>
                    <td>ascii</td>
                    <td>All ASCII characters</td>
                </tr>
                <tr>
                    <td>ascii_letters</td>
                    <td>A-Za-z</td>
                </tr>
                <tr>
                    <td>ascii_lowercase</td>
                    <td>a-z</td>
                </tr>
                <tr>
                    <td>ascii_uppercase</td>
                    <td>A-Z</td>
                </tr>
                <tr>
                    <td>bytes</td>
                    <td>All 256 byte values</td>
                </tr>
                <tr>
                    <td>digits</td>
                    <td>0-9</td>
                </tr>
                <tr>
                    <td>hexdigits</td>
                    <td>0-f</td>
                </tr>
                <tr>
                    <td>octdigits</td>
                    <td>0-7</td>
                </tr>
                <tr>
                    <td>punctuation</td>
                    <td>
                        <pre>!"#$%&\'()*+,-./:;<=>?@[\\]^_`{|}~</pre>
                    </td>
                </tr>
                <tr>
                    <td>whitespace</td>
                    <td>
                        <pre>\t\n\x0b\x0c\r and space</pre>
                    </td>
                </tr>
            </tbody>
        </table>
</section>

{% endblock %}