From a5567094ace40527f912b4e9f90d71635d50eb6d Mon Sep 17 00:00:00 2001 From: Aldo Cortesi Date: Sat, 18 Apr 2015 17:04:24 +1200 Subject: [PATCH] Document embedded response specification. --- libpathod/templates/about.html | 5 +-- libpathod/templates/docs_lang.html | 44 +++++++++++++--------- libpathod/templates/docs_pathoc.html | 55 ++++++++++++++++++++++++---- 3 files changed, 75 insertions(+), 29 deletions(-) diff --git a/libpathod/templates/about.html b/libpathod/templates/about.html index 0eae48654..9a695a6a8 100644 --- a/libpathod/templates/about.html +++ b/libpathod/templates/about.html @@ -1,5 +1,5 @@ {% extends "frame.html" %} -{% block body %} +{% block body %}
@@ -19,7 +19,6 @@ @@ -28,4 +27,4 @@
-{% endblock %} +{% endblock %} diff --git a/libpathod/templates/docs_lang.html b/libpathod/templates/docs_lang.html index 7cb3fc5f0..116dab879 100644 --- a/libpathod/templates/docs_lang.html +++ b/libpathod/templates/docs_lang.html @@ -1,5 +1,5 @@ {% extends "docframe.html" %} -{% block body %} +{% block body %}

@@ -16,7 +16,7 @@

The general form of a response is as follows:

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

@@ -40,14 +40,14 @@ @@ -55,7 +55,7 @@ @@ -71,7 +71,7 @@ @@ -79,7 +79,7 @@ @@ -98,7 +98,7 @@

The general form of a request is as follows:

- + 
method:path:[colon-separated list of features]

dOFFSET - Disconnect after OFFSET bytes. + Disconnect after OFFSET bytes.
hVALUE=VALUE - Set a header. + Set a header.
iOFFSET,VALUE - Inject the specified value at the offset. + Inject the specified value at the offset.
mVALUE HTTP Reason message. Automatically chosen according to - the response code if not specified. + the response code if not specified.
pOFFSET,SECONDS 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.
@@ -122,21 +122,21 @@ @@ -144,7 +144,7 @@ @@ -156,6 +156,14 @@ + + + + + @@ -196,9 +204,9 @@ injections or other transforms are applied. They have 3 flavors:

    -
  • An integer byte offset
    • -
  • r for a random location
    • -
  • a for the end of the message
    • +
  • An integer byte offset
    • +
  • r for a random location
    • +
  • a for the end of the message
@@ -229,7 +237,7 @@

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:

@@ -244,7 +252,7 @@ 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 @@ -333,4 +341,4 @@

dOFFSET - Disconnect after OFFSET bytes. + Disconnect after OFFSET bytes.
hVALUE=VALUE - Set a header. + Set a header.
iOFFSET,VALUE - Inject the specified value at the offset. + Inject the specified value at the offset.
pOFFSET,SECONDS 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.
sVALUE + An embedded Response specification, appended to the path + of the request. +
uVALUE
uSHORTCUT
-{% endblock %} +{% endblock %} diff --git a/libpathod/templates/docs_pathoc.html b/libpathod/templates/docs_pathoc.html index 424af4145..760185304 100644 --- a/libpathod/templates/docs_pathoc.html +++ b/libpathod/templates/docs_pathoc.html @@ -1,5 +1,5 @@ {% extends "docframe.html" %} -{% block body %} +{% block body %}

pathoc @@ -20,14 +20,14 @@ the command-line help:

Getting Started

- +

The basic pattern for pathoc commands is as follows: 

pathoc hostname request [request ...]

That is, we specify the hostname to connect to, followed by one or more requests. Lets start with a simple example:

- + 
> pathoc google.com get:/
 << 301 Moved Permanently: 219 bytes
@@ -47,7 +47,7 @@ the command-line help:

Multiple Requests

- +

There are two ways to tell pathoc to issue multiple requests. The first is to specify them on the command-line, like so:

@@ -58,8 +58,8 @@ the command-line help:

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

- -

The other way to issue multiple requets is to use the -n flag:

+ +

The other way to issue multiple requets is to use the -n flag:

> pathoc -n 2 google.com get:/
 << 301 Moved Permanently: 219 bytes
@@ -102,7 +102,7 @@ the command-line help:

         enter a state where it's awaiting more input from the client. This is
         where the -t option comes in, which sets a timeout that causes
         pathoc to disconnect after two seconds. 
-    
+
         
  •  The -n option tells pathoc to repeat the request 1000
         times.
    • 
 
@@ -149,4 +149,43 @@ the command-line help:
    
 
 
 
-{% endblock %}  
+
    
+    
    
+       
    Embedded response specification
    
+    
    
+
+    
    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:
    
+
+    
    > pathoc localhost:9999 "get:/p/:s'401:ir,@1'" 
    
+
+    
     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 -e flag to show the expanded request:
+
+    
    > > 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 
    
+
+    
     Note that the embedded response has been resolved before 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.
    
+
+
    
+
+
+
+
+
+
+
+
+{% endblock %}