Document embedded response specification.

3 files changed, 75 insertions, 29 deletions

diff --git a/libpathod/templates/about.html b/libpathod/templates/about.html
index 0eae4865..9a695a6a 100644
--- a/libpathod/templates/about.html
+++ b/libpathod/templates/about.html
@@ -1,5 +1,5 @@
 {% extends "frame.html" %}
-{% block body %}  
+{% block body %}
 
 
 <section>
@@ -19,7 +19,6 @@
             <ul>
                 <li>email: <a href="mailto:aldo@corte.si">aldo@corte.si</a></li>
                 <li>twitter: <a href="http://twitter.com/cortesi">@cortesi</a></li>
-                <li>app.net: <a href="https://alpha.app.net/cortesi">@cortesi</a></li>
                 <li>github: <a href="https://github.com/cortesi">github.com/cortesi</a></li>
             </ul>
         </div>
@@ -28,4 +27,4 @@
 </section>
 
 
-{% endblock %}  
+{% endblock %}
diff --git a/libpathod/templates/docs_lang.html b/libpathod/templates/docs_lang.html
index 7cb3fc5f..116dab87 100644
--- a/libpathod/templates/docs_lang.html
+++ b/libpathod/templates/docs_lang.html
@@ -1,5 +1,5 @@
 {% extends "docframe.html" %}
-{% block body %}  
+{% block body %}
 
 <div class="page-header">
    <h1>
@@ -16,7 +16,7 @@
 <div class="tab-content">
     <div class="tab-pane active" id="specifying_responses">
         <p>The general form of a response is as follows:</p>
-            
+
         <pre class="example">code:[colon-separated list of features]</pre></p>
 
         <table class="table table-bordered">
@@ -40,14 +40,14 @@
                 <tr>
                     <td> d<a href="#offsetspec">OFFSET</a> </td>
                     <td>
-                        Disconnect after OFFSET bytes. 
+                        Disconnect after OFFSET bytes.
                     </td>
                 </tr>
 
                 <tr>
                     <td> h<a href="#valuespec">VALUE</a>=<a href="#valuespec">VALUE</a> </td>
                     <td>
-                        Set a header. 
+                        Set a header.
                     </td>
                 </tr>
 
@@ -55,7 +55,7 @@
                 <tr>
                     <td> i<a href="#offsetspec">OFFSET</a>,<a href="#valuespec">VALUE</a> </td>
                     <td>
-                        Inject the specified value at the offset. 
+                        Inject the specified value at the offset.
                     </td>
                 </tr>
 
@@ -71,7 +71,7 @@
                     <td> m<a href="#valuespec">VALUE</a> </td>
                     <td>
                         HTTP Reason message. Automatically chosen according to
-                        the response code if not specified. 
+                        the response code if not specified.
                     </td>
                 </tr>
 
@@ -79,7 +79,7 @@
                     <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. 
+                        be an integer or "f" to pause forever.
                     </td>
                 </tr>
 
@@ -98,7 +98,7 @@
 
     <div class="tab-pane" id="specifying_requests">
         <p>The general form of a request is as follows:</p>
-            
+
         <pre class="example">method:path:[colon-separated list of features]</pre></p>
 
         <table class="table table-bordered">
@@ -122,21 +122,21 @@
                 <tr>
                     <td> d<a href="#offsetspec">OFFSET</a> </td>
                     <td>
-                        Disconnect after OFFSET bytes. 
+                        Disconnect after OFFSET bytes.
                     </td>
                 </tr>
 
                 <tr>
                     <td> h<a href="#valuespec">VALUE</a>=<a href="#valuespec">VALUE</a> </td>
                     <td>
-                        Set a header. 
+                        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. 
+                        Inject the specified value at the offset.
                     </td>
                 </tr>
 
@@ -144,7 +144,7 @@
                     <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. 
+                        be an integer or "f" to pause forever.
                     </td>
                 </tr>
 
@@ -157,6 +157,14 @@
                 </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>
@@ -196,9 +204,9 @@
             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> 
+                <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>
@@ -229,7 +237,7 @@
 
         <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>
@@ -244,7 +252,7 @@
         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
@@ -333,4 +341,4 @@
         </table>
 </section>
 
-{% endblock %}  
+{% endblock %}
diff --git a/libpathod/templates/docs_pathoc.html b/libpathod/templates/docs_pathoc.html
index 424af414..76018530 100644
--- a/libpathod/templates/docs_pathoc.html
+++ b/libpathod/templates/docs_pathoc.html
@@ -1,5 +1,5 @@
 {% extends "docframe.html" %}
-{% block body %}  
+{% block body %}
 <div class="page-header">
    <h1>
         pathoc
@@ -20,14 +20,14 @@ the command-line help:</p>
     <div class="page-header">
        <h1>Getting Started</h1>
     </div>
-    
+
     <p>The basic pattern for pathoc commands is as follows: </p>
 
     <pre class="terminal">pathoc hostname request [request ...]</pre>
 
     <p>That is, we specify the hostname to connect to, followed by one or more
     requests. Lets start with a simple example:</p>
-        
+
     <pre class="terminal">&gt; pathoc google.com get:/
 &lt;&lt; 301 Moved Permanently: 219 bytes</pre>
 
@@ -47,7 +47,7 @@ the command-line help:</p>
     <div class="page-header">
        <h1>Multiple Requests</h1>
     </div>
-    
+
     <p>There are two ways to tell pathoc to issue multiple requests. The first
     is to specify them on the command-line, like so:</p>
 
@@ -58,8 +58,8 @@ the command-line help:</p>
     <p> In this case, pathoc issues the specified requests over the same TCP
     connection - so in the above example only one connection is made to
     google.com </p>
-    
-    <p> The other way to issue multiple requets is to use the <b>-n</b> flag:</p> 
+
+    <p> The other way to issue multiple requets is to use the <b>-n</b> flag:</p>
 
     <pre class="terminal">&gt; pathoc -n 2 google.com get:/
 &lt;&lt; 301 Moved Permanently: 219 bytes
@@ -102,7 +102,7 @@ the command-line help:</p>
         enter a state where it's awaiting more input from the client. This is
         where the <b>-t</b> option comes in, which sets a timeout that causes
         pathoc to disconnect after two seconds. </li>
-    
+
         <li> The <b>-n</b> option tells pathoc to repeat the request 1000
         times.</li>
 
@@ -149,4 +149,43 @@ the command-line help:</p>
 </section>
 
 
-{% endblock %}  
+<section>
+    <div class="page-header">
+       <h1>Embedded response specification</h1>
+    </div>
+
+    <p>One interesting feature of the Request sppecification language is that
+    you can embed a response specifcation in it, which is then added to the
+    request path. Here's an example:</p>
+
+    <pre class="terminal">&gt; pathoc localhost:9999 "get:/p/:s'401:ir,@1'" </pre>
+
+    <p> This crafts a request that connects to the pathod server, and which then
+    crafts a response that generates a 401, with one random byte embedded at a
+    random point. The response specification is parsed and expanded by pathoc,
+    so you see syntax errors immediately. This really becomes handy when
+    combined with the <b>-e</b> flag to show the expanded request:
+
+    <pre class="terminal">&gt; > pathoc -e localhost:9999 "get:/p/:s'401:ir,@1'"
+>> Spec: get:/p/:s'401:i15,\'o\':h\'Content-Length\'=\'0\'':h'Content-Length'='0'
+<< 401 Unoauthorized: 0 bytes </pre>
+
+    <p> Note that the embedded response has been resolved <i>before</i> being
+    sent to the server, so that "ir,@1" (embed a random byte at a random
+    location) has become "i15,\'o\'" (embed the character "o" at offset 15). You
+    now have a pathoc request specification that is precisely reproducable, even
+    with random components. This feature comes in terribly handy when testing a
+    proxy, since you can now drive the server repsonse completely from the
+    client, and have a complete log of reproducible requests to analyse
+    afterwards.</p>
+
+</section>
+
+
+
+
+
+
+
+
+{% endblock %}