From 2bdbbaa8afb80ff1a59542f011fa87ffdfaf7b16 Mon Sep 17 00:00:00 2001 From: Aldo Cortesi Date: Fri, 20 Jul 2012 23:19:58 +1200 Subject: Convert documentation to HTML, fix styling. --- libpathod/static/pathod.css | 19 ++ libpathod/templates/docs_pathod.html | 536 ++++++++++++++++++----------------- libpathod/templates/frame.html | 1 + 3 files changed, 293 insertions(+), 263 deletions(-) create mode 100644 libpathod/static/pathod.css (limited to 'libpathod') diff --git a/libpathod/static/pathod.css b/libpathod/static/pathod.css new file mode 100644 index 00000000..3e24dd7d --- /dev/null +++ b/libpathod/static/pathod.css @@ -0,0 +1,19 @@ + + +section { + margin-top: 50px; + +} + +.example { + margin-top: 10px; + margin-bottom: 10px; + +} + +.terminal { + margin-top: 10px; + margin-bottom: 10px; + background: #000; + color: #fff; +} diff --git a/libpathod/templates/docs_pathod.html b/libpathod/templates/docs_pathod.html index f3dabd5e..1527f851 100644 --- a/libpathod/templates/docs_pathod.html +++ b/libpathod/templates/docs_pathod.html @@ -1,5 +1,6 @@ {% extends "frame.html" %} {% block body %} +

pathod @@ -7,340 +8,349 @@

-At pathod's heart is a small, terse language for crafting HTTP responses, +

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: +want using this language in the request URL. Here's a minimal example:

- http://localhost:9999/p/200 +
http://localhost:9999/p/200
-Everything after the "/p/" path component is a response specifier - in this +

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: +whenever a matching URL is requested:

- pathod -a "/foo=200" +
pathod -a "/foo=200"
-Here, "/foo" a regex specifying the anchor path, and the part after the "=" is -a response specifier. +

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 +

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

Specifying Responses

+
- 200"YAY" +

The general form of a response is as follows: + + 

code[MESSAGE]:[colon-separated list of features]

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

Here's the simplest possible response specification, returning just an HTTP 200 + OK message with no headers and no content: + + 

200

- 200@100k,ascii_letters +

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:

-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"YAY"
- 200:b@1m +

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:

-And this is the same response with an ETag header added: + 
200@100k,ascii_letters
- 200:b@1m:h"Etag"="foo" +

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:

-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
- 200:b@1m:h@1k,ascii_letters="foo" +

And this is the same response with an ETag header added:

-A few specific headers have shortcuts, because they're used so often. The -shortcut for the content-type header is "c": + 
200:b@1m:h"Etag"="foo"
- 200:b@1m:c"text/json" +

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:

-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:h@1k,ascii_letters="foo"
- 200:b@1m:p120,50 +

A few specific headers have shortcuts, because they're used so often. The + shortcut for the content-type header is "c":

-If that's not long enough, we can tell pathod to hang forever: + 
200:b@1m:c"text/json"
- 200:b@1m:p120,f +

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):

-Or to send all data, and then hang without disconnecting: + 
200:b@1m:p120,50
- 200:b@1m:p120,a +

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

-We can also ask pathod to hang randomly: + 
200:b@1m:p120,f
- 200:b@1m:pr,a +

Or to send all data, and then hang without disconnecting:

-There is a similar mechanism for dropping connections mid-response. So, we can -tell pathod to disconnect after sending 50 bytes: + 
200:b@1m:p120,a
- 200:b@1m:d50 +

We can also ask pathod to hang randomly:

-Or randomly: + 
200:b@1m:pr,a
- 200:b@1m:dr +

There is a similar mechanism for dropping connections mid-response. So, we can + tell pathod to disconnect after sending 50 bytes:

-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:d50
- 200:b@1m:p10,10:p20,10:d5000 +

Or randomly:

+ 
200:b@1m:dr
-## Response Features +

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
- - - - - - - + -Literal values are specified as a quoted strings: + + + + - 'fo\'o' + + + + -### Files + + + + + +
- 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: +

Response Features

- 
h"Content-Type"=VALUE
+ + + + + + - - + + + + - - - + + - - - - - - - - - - - - - -
+ 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. +
- lVALUE - - A shortcut for setting the Location header. Equivalent to: +
+ cVALUE + + A shortcut for setting the Content-Type 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 +
+ lVALUE + + A shortcut for setting the Location header. Equivalent to: - "foo" + 
h"Location"=VALUE
-Either single or double quotes are accepted, and quotes can be escaped with -backslashes within the string: +
+ 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. +
-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: + +

VALUE Specifiers

- pathod -d ~/myassets +

Literals

-All paths are relative paths under this directory. File loads are indicated by -starting the value specifier with the left angle bracket: - - Literal values are specified as a quoted strings:

-The path value can also be a quoted string, with the same syntax as literals: + 
"foo"
- <"my/path" +

Either single or double quotes are accepted, and quotes can be escaped with + backslashes within the string:

+ 
'fo\'o'
-### 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". +

Files

-Here's a value specifier for generating 100 bytes: - - @100 +

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:

-You can use standard suffixes to indicate larger values. Here, for instance, is -a specifier for generating 100 megabytes: + 
pathod -d ~/myassets
- @100m +

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:

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

API

-
- -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. - - - - - - - - - - - - - - - - - -
- /api/clear_log - - A POST to this URL clears the log buffer. -
- /api/info - - Basic version and configuration info. -
- /api/log - - 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: - - 
{ 'log': [ ENTRIES ] }
- - You can preview the JSON data returned for a log entry through the built-in web - interface. -
- -
-

Error Responses

-
+
+
+

API

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

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.

- http://localhost:9999/p/foo -... will return an 800 response, because "foo" is not a valid page specifier. + + + + + + + + + + + + + + + +
+ /api/clear_log + + A POST to this URL clears the log buffer. +
+ /api/info + + Basic version and configuration info. +
+ /api/log + + 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: + + 
{ 'log': [ ENTRIES ] }
+ + You can preview the JSON data returned for a log entry through the built-in web + interface. +
+
+ +
+
+

Error Responses

+
+ +

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 %} diff --git a/libpathod/templates/frame.html b/libpathod/templates/frame.html index a83f8f38..daf3e2ae 100644 --- a/libpathod/templates/frame.html +++ b/libpathod/templates/frame.html @@ -4,6 +4,7 @@ pathod + -- cgit v1.2.3