Move docs into pathod server.

5 files changed, 451 insertions, 20 deletions

diff --git a/libpathod/templates/docs_pathoc.html b/libpathod/templates/docs_pathoc.html
new file mode 100644
index 00000000..01e41894
--- /dev/null
+++ b/libpathod/templates/docs_pathoc.html
@@ -0,0 +1,13 @@
+{% extends "frame.html" %}
+{% block body %}  
+<div class="page-header">
+   <h1>
+        pathoc
+        <small>A perverse HTTP client.</small>
+    </h1>
+</div>
+
+pathoc hostname get:"/foo/bar":h"foo"="bar" get:/wah:b@1m
+
+pathoc --ssl hostname get:"/foo/bar":h"foo"="bar" get:"/wah":b@1m
+{% endblock %}  
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 %}  
diff --git a/libpathod/templates/docs_test.html b/libpathod/templates/docs_test.html
new file mode 100644
index 00000000..27129f1c
--- /dev/null
+++ b/libpathod/templates/docs_test.html
@@ -0,0 +1,9 @@
+{% extends "frame.html" %}
+{% block body %}  
+<div class="page-header">
+   <h1>
+        libpathod.test
+        <small>Using pathod and pathoc in your unit tests.</small>
+    </h1>
+</div>
+{% endblock %}  
diff --git a/libpathod/templates/frame.html b/libpathod/templates/frame.html
index 3dd7fbf8..a83f8f38 100644
--- a/libpathod/templates/frame.html
+++ b/libpathod/templates/frame.html
@@ -2,38 +2,68 @@
 <html lang="en">
   <head>
     <meta charset="utf-8">
-    <title>Pathod</title>
+    <title>pathod</title>
     <link href="/static/bootstrap.min.css" rel="stylesheet">
+    <link href="/static/syntax.css" rel="stylesheet">
     <script src="/static/jquery-1.7.2.min.js"></script>
-    <style>
-        body {
-            padding-top: 45px;
-        }
+    <script src="/static/bootstrap.min.js"></script>
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <meta name="description" content="">
+    <meta name="author" content="">
+    <style type="text/css">
+      body {
+        padding-top: 60px;
+        padding-bottom: 40px;
+      }
     </style>
+    <!-- Le HTML5 shim, for IE6-8 support of HTML5 elements -->
+    <!--[if lt IE 9]>
+      <script src="http://html5shim.googlecode.com/svn/trunk/html5.js"></script>
+    <![endif]-->
   </head>
 
   <body>
     <div class="navbar navbar-fixed-top">
       <div class="navbar-inner">
         <div class="container">
-          <a class="brand" href="/">Pathod</a>
-          <ul class="nav">
-            <li {% if section== "main" %} class="active" {% endif %}><a href="/">Main</a></li>
-            <li {% if section== "log" %} class="active" {% endif %}><a href="/log">Log</a></li>
-            <li {% if section== "help" %} class="active" {% endif %}><a href="/help">Help</a></li>
-          </ul>
+          <a class="btn btn-navbar" data-toggle="collapse" data-target=".nav-collapse">
+            <span class="icon-bar"></span>
+            <span class="icon-bar"></span>
+            <span class="icon-bar"></span>
+          </a>
+          <a class="brand" href="/index.html">pathod</a>
+          <div class="nav-collapse">
+            <ul class="nav">
+              <li {% if section== "main" %} class="active" {% endif %}><a href="/">home</a></li>
+              <li {% if section== "log" %} class="active" {% endif %}><a href="/log">log</a></li>
+              <li class="dropdown {% if section== "docs" %}active{% endif %}">
+                <a class="dropdown-toggle" data-toggle="dropdown">
+                    docs
+                    <b class="caret"></b>
+                </a>
+                <ul class="dropdown-menu">
+                      <li><a href="/docs/pathod">pathod</a></li>
+                      <li><a href="/docs/pathoc">pathoc</a></li>
+                      <li><a href="/docs/test">libpathod.test</a></li>
+                </ul>
+              </li>
+            </ul>
+          </div>
         </div>
       </div>
     </div>
 
     <div class="container">
-        
-        {% block body %}  
-        {% endblock %}  
-
-    <hr>
-    <p>by <a href="http://corte.si">Aldo Cortesi</a> </p>
-    </div> <!-- /container -->
-
+      <div class="row">
+            <div class="span12">
+                {% block body %}  
+                {% endblock %}  
+            </div>
+      </div>
+      <hr>
+      <footer>
+        <p>&copy; Aldo Cortesi 2012</p>
+      </footer>
+    </div>
   </body>
 </html>
diff --git a/libpathod/templates/index.html b/libpathod/templates/index.html
index 07145b85..268bc7a5 100644
--- a/libpathod/templates/index.html
+++ b/libpathod/templates/index.html
@@ -1,4 +1,37 @@
 {% extends "frame.html" %}
 {% block body %}  
-    {% include "previewform.html" %}
+{% include "previewform.html" %}
+
+<div class="hero-unit">
+<h1>Tools for testing and torturing HTTP clients, servers and proxies.</h1>
+</div>
+
+<div class="row">
+    <div class="span4">
+        <div class="well">
+            <h1> <a href="/docs/pathod">pathod</a> </h1>
+
+            A pathological web daemon.
+
+        </div>
+    </div>
+    <div class="span4">
+        <div class="well">
+            <h1> <a href="/docs/pathoc">pathoc</a> </h1>
+
+            A perverse HTTP client.
+
+        </div>
+    </div>
+    <div class="span4">
+        <div class="well">
+            <h1> <a href="/docs/test">libpathod.test</a> </h1>
+
+            Using pathod and pathoc in your unit tests.
+
+        </div>
+    </div>
+</div>
+
+
 {% endblock %}