Move overlay API example to appendix

1 files changed, 164 insertions, 159 deletions

diff --git a/draft-schanzen-r5n.xml b/draft-schanzen-r5n.xml
index 0ed3898..51a0ca3 100644
--- a/draft-schanzen-r5n.xml
+++ b/draft-schanzen-r5n.xml
@@ -279,8 +279,12 @@
         </li>
       </ul>
       <t>
-        The specific semantics of the above operations as provided by R<sup>5</sup>N
-        for applications are defined in <xref target="overlay"/>.
+        A peer or its implementation does not necessarily need to expose the above operations
+        to applications but it commonly will.
+        For example, the peer could be a server purely used for bootstrapping, routing or
+        supporting the overlay network with resources.
+        An example for possible semantics of the above operations provided as an API to applications by an
+        implementation are outlined in <xref target="overlay"/>.
       </t>
       <t>
         In a trivial scenario where there is only one peer (the local host),
@@ -353,163 +357,7 @@ Connectivity | |Underlay|  |Underlay|
         </artwork>
       </figure>
     </section>
-    <section anchor="overlay" numbered="true" toc="default">
-      <name>Overlay Operations</name>
-      <t>
-        An implementation of this specification commonly exposes the two overlay
-        operations "GET" and "PUT".
-        The following are non-normative examples of APIs for those operations.
-        Their behaviour is described prosaically in order to give implementers a fuller
-        picture of the protocol.
-      </t>
-      <section>
-        <name>GET operation</name>
-        <t>
-          A basic GET operation interface may be exposed as:
-        </t>
-        <t>
-          <tt>GET(Query-Key, Block-Type) -> Results as List</tt>
-        </t>
-        <t>
-          The procedure typically takes at least two arguments to initiate a lookup:
-        </t>
-        <dl>
-          <dt><tt>QueryKey</tt>:</dt>
-          <dd>
-            is the 512-bit key to look for in the DHT.
-          </dd>
-          <dt>Block-Type:</dt>
-          <dd>
-            is the type of block to look for, possibly "any".
-          </dd>
-        </dl>
-        <t>
-          The GET procedure may allow a set of optional parameters in order to
-          control or modify the query:
-        </t>
-        <dl>
-          <dt>Replication-Level:</dt>
-          <dd>
-            is an integer which controls how many nearest peers the request
-            should reach.
-          </dd>
-          <dt>Flags:</dt>
-          <dd>
-            is a 16-bit vector which indicates certain
-            processing requirements for messages.
-            Any combination of flags as defined in <xref target="route_flags"/>
-            may be specified.
-          </dd>
-          <dt>eXtended-Query (XQuery):</dt>
-          <dd>
-            is medatadata which may be
-            required depending on the respective <tt>Block-Type</tt>.
-            A <tt>Block-Type</tt> must define if the <tt>XQuery</tt> can or must
-            be used and what the specific format of its contents should be.
-            Extended queries are in general used to implement domain-specific filters.
-            These might be particularly useful in combination with FindApproximate
-            to add a well-defined filter by an application-specific distance.
-            Regardless, the DHT does not define any particular semantics for an XQuery.
-            See also <xref target="blockstorage"/>.
-          </dd>
-          <dt>Result-Filter:</dt>
-          <dd>
-            is data for a <tt>Block-type</tt>-specific filter
-	    which allows applications to
-	    indicate results which are
-	    not relevant anymore to the
-            caller (see <xref target="result_filter"/>).
-          </dd>
-        </dl>
-        <t>
-          The GET procedure should be implemented as an asynchronous
-	  operation that returns individual results as they are found
-	  in the DHT.  It should terminate only once the application
-	  explicitly cancels the operation.  A single result commonly
-	  consists of:</t>
-        <dl>
-          <dt>Block-Type:</dt>
-          <dd>
-            is the desired type of block in the result.
-          </dd>
-          <dt>Block-Data:</dt>
-          <dd>
-            is the application-specific block payload. Contents are specific to the <tt>Block-Type</tt>.
-          </dd>
-          <dt>Block-Expiration:</dt>
-          <dd>
-            is the expiration time of the block. After this time, the result should no
-	    longer be used.
-          </dd>
-          <dt>Key:</dt>
-          <dd>
-            is the key under which the block was stored. This may be different from the
-            key that was queried if the flag FindApproximate was set.
-          </dd>
-          <dt>GET-Path:</dt>
-          <dd>
-            is a signed path of the IDs of peers which the query
-	    traversed through the network. The DHT will try to make
-	    the path available if the <tt>RecordRoute</tt> flag was set by
-	    the application calling the PUT procedure. The reported
-	    path may have been silently truncated from the beginning.
-          </dd>
-          <dt>PUT-Path:</dt>
-          <dd>
-            is a signed path of the IDs of peers which the
-	    result message traversed.  The DHT will try to make the
-	    path available if the <tt>RecordRoute</tt> flag was set for the GET procedure.
-	    The reported path may have been silently truncated from the beginning.
-	    As the block was cached by the node at the end of this
-	    path, this path is more likely to be stale compared to the
-	    <tt>GET-Path</tt>.
-          </dd>
-        </dl>
-      </section>
-      <section>
-        <name>PUT operation</name>
-        <t>
-          A PUT operation interface may be exposed as:
-        </t>
-        <t>
-          <tt>PUT(Key, Block-Type, Block-Expiration, Block-Data)</tt>
-        </t>
-        <t>
-          The procedure typically takes at least four parameters:
-        </t>
-        <dl>
-          <dt>Key:</dt>
-          <dd>is the key under which to store the block.</dd>
-          <dt>Block-Type:</dt>
-          <dd>is the type of the block to store.</dd>
-          <dt>Block-Expiration:</dt>
-          <dd>specifies when the block should expire.</dd>
-          <dt>Block-Data:</dt>
-          <dd>is the application-specific payload of the block to store.</dd>
-        </dl>
-        <t>
-          The PUT procedure may allow a set of optional parameters in order to
-          control or modify the query:
-        </t>
-        <dl>
-          <dt>Replication-Level:</dt>
-          <dd>
-            is an integer which controls how many nearest peers the request
-            should reach.
-          </dd>
-          <dt>Flags:</dt>
-          <dd>
-            is a bit-vector which indicates certain
-            processing requirements for messages.
-            Any combination of flags as defined in <xref target="route_flags"/>
-            may be specified.
-          </dd>
-        </dl>
-        <t>
-          The PUT procedure does not necessarily yield any information.
-        </t>
-      </section>
-    </section>
+    
     <section anchor="underlay" numbered="true" toc="default">
       <name>Underlay</name>
       <t>
@@ -2885,5 +2733,162 @@ Type    | Name            | References | Description
         Otherwise, the element is not considered to be in the Bloom filter.
       </t>
     </section>
+  <section anchor="overlay" numbered="true" toc="default">
+      <name>Overlay Operations</name>
+      <t>
+        An implementation of this specification commonly exposes the two overlay
+        operations "GET" and "PUT".
+        The following are non-normative examples of APIs for those operations.
+        Their behaviour is described prosaically in order to give implementers a fuller
+        picture of the protocol.
+      </t>
+      <section>
+        <name>GET operation</name>
+        <t>
+          A basic GET operation interface may be exposed as:
+        </t>
+        <t>
+          <tt>GET(Query-Key, Block-Type) -> Results as List</tt>
+        </t>
+        <t>
+          The procedure typically takes at least two arguments to initiate a lookup:
+        </t>
+        <dl>
+          <dt><tt>QueryKey</tt>:</dt>
+          <dd>
+            is the 512-bit key to look for in the DHT.
+          </dd>
+          <dt>Block-Type:</dt>
+          <dd>
+            is the type of block to look for, possibly "any".
+          </dd>
+        </dl>
+        <t>
+          The GET procedure may allow a set of optional parameters in order to
+          control or modify the query:
+        </t>
+        <dl>
+          <dt>Replication-Level:</dt>
+          <dd>
+            is an integer which controls how many nearest peers the request
+            should reach.
+          </dd>
+          <dt>Flags:</dt>
+          <dd>
+            is a 16-bit vector which indicates certain
+            processing requirements for messages.
+            Any combination of flags as defined in <xref target="route_flags"/>
+            may be specified.
+          </dd>
+          <dt>eXtended-Query (XQuery):</dt>
+          <dd>
+            is medatadata which may be
+            required depending on the respective <tt>Block-Type</tt>.
+            A <tt>Block-Type</tt> must define if the <tt>XQuery</tt> can or must
+            be used and what the specific format of its contents should be.
+            Extended queries are in general used to implement domain-specific filters.
+            These might be particularly useful in combination with FindApproximate
+            to add a well-defined filter by an application-specific distance.
+            Regardless, the DHT does not define any particular semantics for an XQuery.
+            See also <xref target="blockstorage"/>.
+          </dd>
+          <dt>Result-Filter:</dt>
+          <dd>
+            is data for a <tt>Block-type</tt>-specific filter
+	    which allows applications to
+	    indicate results which are
+	    not relevant anymore to the
+            caller (see <xref target="result_filter"/>).
+          </dd>
+        </dl>
+        <t>
+          The GET procedure should be implemented as an asynchronous
+	  operation that returns individual results as they are found
+	  in the DHT.  It should terminate only once the application
+	  explicitly cancels the operation.  A single result commonly
+	  consists of:</t>
+        <dl>
+          <dt>Block-Type:</dt>
+          <dd>
+            is the desired type of block in the result.
+          </dd>
+          <dt>Block-Data:</dt>
+          <dd>
+            is the application-specific block payload. Contents are specific to the <tt>Block-Type</tt>.
+          </dd>
+          <dt>Block-Expiration:</dt>
+          <dd>
+            is the expiration time of the block. After this time, the result should no
+	    longer be used.
+          </dd>
+          <dt>Key:</dt>
+          <dd>
+            is the key under which the block was stored. This may be different from the
+            key that was queried if the flag FindApproximate was set.
+          </dd>
+          <dt>GET-Path:</dt>
+          <dd>
+            is a signed path of the IDs of peers which the query
+	    traversed through the network. The DHT will try to make
+	    the path available if the <tt>RecordRoute</tt> flag was set by
+	    the application calling the PUT procedure. The reported
+	    path may have been silently truncated from the beginning.
+          </dd>
+          <dt>PUT-Path:</dt>
+          <dd>
+            is a signed path of the IDs of peers which the
+	    result message traversed.  The DHT will try to make the
+	    path available if the <tt>RecordRoute</tt> flag was set for the GET procedure.
+	    The reported path may have been silently truncated from the beginning.
+	    As the block was cached by the node at the end of this
+	    path, this path is more likely to be stale compared to the
+	    <tt>GET-Path</tt>.
+          </dd>
+        </dl>
+      </section>
+      <section>
+        <name>PUT operation</name>
+        <t>
+          A PUT operation interface may be exposed as:
+        </t>
+        <t>
+          <tt>PUT(Key, Block-Type, Block-Expiration, Block-Data)</tt>
+        </t>
+        <t>
+          The procedure typically takes at least four parameters:
+        </t>
+        <dl>
+          <dt>Key:</dt>
+          <dd>is the key under which to store the block.</dd>
+          <dt>Block-Type:</dt>
+          <dd>is the type of the block to store.</dd>
+          <dt>Block-Expiration:</dt>
+          <dd>specifies when the block should expire.</dd>
+          <dt>Block-Data:</dt>
+          <dd>is the application-specific payload of the block to store.</dd>
+        </dl>
+        <t>
+          The PUT procedure may allow a set of optional parameters in order to
+          control or modify the query:
+        </t>
+        <dl>
+          <dt>Replication-Level:</dt>
+          <dd>
+            is an integer which controls how many nearest peers the request
+            should reach.
+          </dd>
+          <dt>Flags:</dt>
+          <dd>
+            is a bit-vector which indicates certain
+            processing requirements for messages.
+            Any combination of flags as defined in <xref target="route_flags"/>
+            may be specified.
+          </dd>
+        </dl>
+        <t>
+          The PUT procedure does not necessarily yield any information.
+        </t>
+      </section>
+    </section>
   </back>
 </rfc>