diff options
Diffstat (limited to 'libpathod/templates/docs_pathod.html')
| -rw-r--r-- | libpathod/templates/docs_pathod.html | 346 |
1 files changed, 346 insertions, 0 deletions
diff --git a/libpathod/templates/docs_pathod.html b/libpathod/templates/docs_pathod.html new file mode 100644 index 00000000..f3dabd5e --- /dev/null +++ b/libpathod/templates/docs_pathod.html @@ -0,0 +1,346 @@ +{% extends "frame.html" %} +{% block body %} +<div class="page-header"> + <h1> + pathod + <small>A pathological web daemon.</small> + </h1> +</div> + +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: + + http://localhost:9999/p/200 + +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: + + pathod -a "/foo=200" + +Here, "/foo" a regex specifying the anchor path, and the part after the "=" is +a response specifier. + +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: + + http://localhost:9999 + + + +<div class="page-header"> + <h1>Specifying Responses</h1> +</div> + +The general form of a response is as follows: + + code[MESSAGE]:[colon-separated list of features] + +Here's the simplest possible response specification, returning just an HTTP 200 +OK message with no headers and no content: + + 200 + +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: + + 200"YAY" + +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: + + 200@100k,ascii_letters + +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: + + 200:b@1m + +And this is the same response with an ETag header added: + + 200:b@1m:h"Etag"="foo" + +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: + + 200:b@1m:h@1k,ascii_letters="foo" + +A few specific headers have shortcuts, because they're used so often. The +shortcut for the content-type header is "c": + + 200:b@1m:c"text/json" + +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): + + 200:b@1m:p120,50 + +If that's not long enough, we can tell pathod to hang forever: + + 200:b@1m:p120,f + +Or to send all data, and then hang without disconnecting: + + 200:b@1m:p120,a + +We can also ask pathod to hang randomly: + + 200:b@1m:pr,a + +There is a similar mechanism for dropping connections mid-response. So, we can +tell pathod to disconnect after sending 50 bytes: + + 200:b@1m:d50 + +Or randomly: + + 200:b@1m:dr + +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: + + 200:b@1m:p10,10:p20,10:d5000 + + +## Response Features + +<table class="table table-bordered table-condensed"> + <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> + lVALUE + </td> + <td> + A shortcut for setting the Location header. Equivalent to: + + <pre>h"Content-Type"=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> +## VALUE Specifiers + +There are three different flavours of value specification. + +### Literal + +Literal values are specified as a quoted strings: + + "foo" + +Either single or double quotes are accepted, and quotes can be escaped with +backslashes within the string: + + 'fo\'o' + + +### Files + +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: + + pathod -d ~/myassets + +All paths are relative paths under this directory. File loads are indicated by +starting the value specifier with the left angle bracket: + + <my/path + +The path value can also be a quoted string, with the same syntax as literals: + + <"my/path" + + +### Generated values + +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". + +Here's a value specifier for generating 100 bytes: + + @100 + +You can use standard suffixes to indicate larger values. Here, for instance, is +a specifier for generating 100 megabytes: + + @100m + +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: + + +<table class="table table-bordered table-condensed"> + <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> + +Data types are separated from the size specification by a comma. This +specification generates 100mb of ASCII: + + @100m,ascii + +Supported data types are: + + +- ascii_letters +- ascii_lowercase +- ascii_uppercase +- digits +- hexdigits +- letters +- lowercase +- octdigits +- printable +- punctuation +- uppercase +- whitespace +- ascii +- bytes + + +<div class="page-header"> + <h1>API</h1> +</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. + + +<table class="table table-bordered table-condensed"> + <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> + +<div class="page-header"> + <h1>Error Responses</h1> +</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: + + http://localhost:9999/p/foo + +... will return an 800 response, because "foo" is not a valid page specifier. +{% endblock %} |