commit 566b5860a276fa7b5affa13ff2000dbe87299785
parent ba1936d7c92d579345f7ff25a05bcae48366a11a
Author: Christian Grothoff <grothoff@gnunet.org>
Date: Thu, 10 Mar 2022 08:26:40 +0100
-API description
Diffstat:
1 file changed, 33 insertions(+), 30 deletions(-)
diff --git a/draft-schanzen-r5n.xml b/draft-schanzen-r5n.xml
@@ -325,26 +325,26 @@ Connectivity | |Underlay| |Underlay|
A basic GET procedure may be exposed as:
</t>
<t>
- <tt>GET(Query-Key) -> Results as List</tt>
+ <tt>GET(Query-Key, Block-Type) -> Results as List</tt>
</t>
<t>
- The procedure requires at least a Query-Key to initiate a lookup:
+ The procedure typically takes at least two arguments to initiate a lookup:
</t>
<dl>
<dt><tt>QueryKey</tt>:</dt>
<dd>
the 512-bit key to look for in the DHT.
</dd>
+ <dt>Block-Type:</dt>
+ <dd>
+ the type of block to look for, possibly "any".
+ </dd>
</dl>
<t>
- The procedure may allow a set of optional parameters in order to
+ The GET procedure may allow a set of optional parameters in order to
control or modify the query:
</t>
<dl>
- <dt>Block-Type:</dt>
- <dd>
- the type of block to look for, possibly "any".
- </dd>
<dt>Replication-Level:</dt>
<dd>
An integer which controls how many nearest peers the request
@@ -371,14 +371,16 @@ Connectivity | |Underlay| |Underlay|
</dd>
<dt>Result-Filter:</dt>
<dd>
- allows to indicate results which are not relevant anymore to the
+ allows applications to indicate results which are not relevant anymore to the
caller (see <xref target="result_bloomfilter"/>).
</dd>
</dl>
<t>
- If the procedure is implemented synchronuously, it may return a list
- of results. If it is implemented asynchronuously, it may return
- individual results. A single result commonly consists of:</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>
@@ -386,7 +388,7 @@ Connectivity | |Underlay| |Underlay|
</dd>
<dt>Block-Data:</dt>
<dd>
- the block payload. Contents are defined by the Block-Type.
+ the block payload. Contents are specific to the <tt>Block-Type</tt>.
</dd>
<dt>Expiration:</dt>
<dd>
@@ -394,18 +396,23 @@ Connectivity | |Underlay| |Underlay|
</dd>
<dt>Key:</dt>
<dd>
- the key of the result. This may be different from the
- Query-Key, for example if a flag for approximate matches was
- set.
+ the key under which the block was stored. This may be different from the
+ key that was queried if the flag for approximate matches was set.
</dd>
<dt>GET-Path:</dt>
<dd>
- is a signed path the query took through the network.
+ is a signed path the query took through the network. Only available if
+ the flag for tracking the path was set by the peer calling
+ the PUT procedure.
</dd>
<dt>PUT-Path:</dt>
<dd>
is a signed path the PUT-Request of this data took through the
- network.
+ network. Only available if the flag for tracking the path
+ was set for the GET procedure.
+ 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>
@@ -415,26 +422,26 @@ Connectivity | |Underlay| |Underlay|
A PUT procedure may be exposed as:
</t>
<t>
- <tt>PUT(Key, Block)</tt>
+ <tt>PUT(Key, Block-Type, Block-Expiration, Block)</tt>
</t>
<t>
- The procedure takes at least two parameters:
+ The procedure typically takes at least four parameters:
</t>
<dl>
<dt>Key:</dt>
<dd>the key under which to store the block.</dd>
- <dt>Block:</dt>
+ <dt>Block-Type:</dt>
+ <dd>the type of the block to store.</dd>
+ <dt>Block-Expiration:</dt>
+ <dd>when should the block expire.</dd>
+ <dt>Block-Data:</dt>
<dd>the block to store.</dd>
</dl>
<t>
- The procedure may allow a set of optional parameters in order to
+ The PUT procedure may allow a set of optional parameters in order to
control or modify the query:
</t>
<dl>
- <dt>Block-Type:</dt>
- <dd>
- the type of the block to store.
- </dd>
<dt>Replication-Level:</dt>
<dd>
An integer which controls how many nearest peers the request
@@ -447,13 +454,9 @@ Connectivity | |Underlay| |Underlay|
Any combination of flags as defined in <xref target="route_flags"/>
may be specified.
</dd>
- <dt>Block-Expiration</dt>
- <dd>
- is the requested expiration date for the block payload.
- </dd>
</dl>
<t>
- The procedure does not necessarily output any information.
+ The PUT procedure does not necessarily yield any information.
</t>
</section>
</section>
