From 37e880b3990e2729d857b0f3a24f80d45116b7f0 Mon Sep 17 00:00:00 2001 From: Aldo Cortesi Date: Sun, 29 Apr 2012 18:56:49 +1200 Subject: [PATCH] Add a rendered version of the docs to the web app. --- README.mkd | 2 + libpathod/templates/help.html | 252 +++++++++++++++++++++++++++++++++- todo | 3 +- 3 files changed, 254 insertions(+), 3 deletions(-) diff --git a/README.mkd b/README.mkd index 9c333a40d..ecbf32109 100644 --- a/README.mkd +++ b/README.mkd @@ -126,12 +126,14 @@ Set a header. Both KEY and VALUE are full _Value Specifiers_. Set the body. VALUE is a _Value Specifier_. When the body is set, Pathod will automatically set the appropriate Content-Length header. + #### cVALUE A shortcut for setting the Content-Type header. Equivalent to: h"Content-Type"=VALUE + #### lVALUE A shortcut for setting the Location header. Equivalent to: diff --git a/libpathod/templates/help.html b/libpathod/templates/help.html index 20d884c5a..3ab48c954 100644 --- a/libpathod/templates/help.html +++ b/libpathod/templates/help.html @@ -1,4 +1,254 @@ {% extends frame.html %} {% block body %} -

Help

+ + +

Pathod

+ +

Pathod is a pathological HTTP/S daemon, useful for testing and torturing client +software. At Pathod's core is a small, terse language for crafting HTTP +responses. The simplest way to use Pathod is to fire up the daemon, and specify +the respnse behaviour you want using this language in the request URL. Here's a +minimal example:

+ +
http://localhost:9999/p/200
+
+ +

Everything below the magic "/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 --anchor "/foo=200"
+
+ +

Here, the part before the "=" is a regex specifying the anchor path, and the +part after is a response specifier.

+ +

Pathod also has a nifty built-in web interface, which exposes activity logs, +online help and various other goodies. Try it by visiting the server root:

+ +
http://localhost:9999
+
+ +

Specifying Responses

+ +

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 Value Specifier, 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-separateed 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 +shorcut 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
+
+ +

Features

+ +

hKEY=VALUE

+ +

Set a header. Both KEY and VALUE are full Value Specifiers.

+ +

bVALUE

+ +

Set the body. VALUE is a Value Specifier. When the body is set, Pathod will +automatically set the appropriate Content-Length header.

+ +

cVALUE

+ +

A shortcut for setting the Content-Type header. Equivalent to:

+ +
h"Content-Type"=VALUE
+
+ +

lVALUE

+ +

A shortcut for setting the Location header. Equivalent to:

+ +
h"Content-Type"=VALUE
+
+ +

dOFFSET

+ +

Disconnect after OFFSET bytes. The offset can also be "r", in which case Pathod +will disconnect at a random point in the response.

+ +

pSECONDS,OFFSET

+ +

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.

+ +

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
+
+ +

The supported suffixes are:

+ +
b = 1024**0 (bytes)
+k = 1024**1 (kilobytes)
+m = 1024**2 (megabytes)
+g = 1024**3 (gigabytes)
+t = 1024**4 (terabytes)
+
+ +

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
+
+ {% end %} diff --git a/todo b/todo index b9ac5c4be..2f3845adc 100644 --- a/todo +++ b/todo @@ -1,8 +1,7 @@ 0.1: - Test pause at 0 bytes - - Web help document - - README + - Web status and explain - API - Logs, log reset, log retrieval - Anchor management