commit a3015eabf4e87eeedaab1a41972c897189872561
parent aa55c2cbde372b3367b2d1bad38be5da547848e7
Author: Martin Schanzenbach <schanzen@gnunet.org>
Date: Wed, 12 Jan 2022 21:47:21 +0100
some procedure stuff
Diffstat:
1 file changed, 81 insertions(+), 30 deletions(-)
diff --git a/draft-schanzen-r5n.xml b/draft-schanzen-r5n.xml
@@ -296,33 +296,39 @@ Connectivity | |Underlay| |Underlay|
A basic GET procedure may be exposed as:
</t>
<t>
- <tt>GET(QueryKey) -> Results as List</tt>
+ <tt>GET(Query-Key) -> Results as List</tt>
</t>
<t>
- The procedure takes a single inputargument : The <tt>QueryKey</tt>.
- It initiates a lookup for this key in the DHT and - if the procedure
- is implemented synchronuously - returns a list of results.
+ The procedure requires at least a Query-Key to initiate a lookup:
+ </t>
+ <dl>
+ <dt><tt>QueryKey</tt>:</dt>
+ <dd>
+ the key to look for in the DHT.
+ </dd>
+ </dl>
+ <t>
The 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.
+ the type of block to look for.
</dd>
<dt>Replication-Level:</dt>
<dd>
An integer which controls how many nearest peers the request
should reach.
</dd>
- <dt>Route-Options</dt>
+ <dt>Route-Options:</dt>
<dd>
Flags that are used in order to indicate certain
processing requirements for messages.
Any combination of options as defined in <xref target="route_options"/>
may be specified.
</dd>
- <dt>XQuery</dt>
+ <dt>Extended-Query:</dt>
<dd>
is extended query medatadata which may be
required depending on the respective <tt>Block-Type</tt>.
@@ -330,48 +336,92 @@ Connectivity | |Underlay| |Underlay|
be used and what the specific format of its contents should be.
See also <xref target="block_types"/>.
</dd>
+ <dt>Result-Filter:</dt>
+ <dd>
+ allows to indicate results which are not relevant anymore to the
+ caller (see <xref target="p2p_bf"/>).
+ </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>
+ <dl>
+ <dt>Block-Type:</dt>
+ <dd>
+ the type of block in the result.
+ </dd>
+ <dt>Block-Data:</dt>
+ <dd>
+ the block payload. Contents are defined by the Block-Type.
+ </dd>
+ <dt>Expiration:</dt>
+ <dd>
+ the duration of validity of the result.
+ </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.
+ </dd>
+ <dt>GET-Path:</dt>
+ <dd>
+ is a signed path the query took through the network.
+ </dd>
+ <dt>PUT-Path:</dt>
+ <dd>
+ is a signed path the PUT-Request of this data took through the
+ network.
+ </dd>
</dl>
- <t>
- As the time it takes for results to arrive may vary an implementation
- may either return a list of results after a timeout or allow the
- caller to provide a callback function which is called for any result
- received from the DHT until the procedure is cancelled.
- </t>
</section>
<section>
<name>The PUT procedure</name>
<t>
- The PUT procedure is defined as follows:
+ A PUT procedure may be exposed as:
</t>
<t>
- <tt>PUT(Key, Block, BlockType[, PutParams])</tt>
+ <tt>PUT(Key, Block)</tt>
</t>
<t>
- The procedure takes three mandatory arguments.
- The first argument is the query
- key under which the block is to be stored.
- The second parameter is the block payload.
- The third parameter is the type of the block payload.
- Block types are defined in <xref target="block_types"/>.
- The PUT procedure also allows an optional <tt>PutParams</tt>
- parameter.
+ The procedure takes at least two parameters:
</t>
<dl>
- <dt>ReplicationLevel</dt>
- <dd>The default setting of this parameter is X (FIXME).</dd>
- <dt>RouteOptions</dt>
+ <dt>Key:</dt>
+ <dd>the key under which to store the block.</dd>
+ <dt>Block:</dt>
+ <dd>the block to store.</dd>
+ </dl>
+ <t>
+ The procedure may allow a set of optional parameters in order to
+ control or modify the query:
+ </t>
+ <dl>
+ <dt>Block-Type:</dt>
<dd>
- are used in order to indicate certain
+ the type of the block to store.
+ </dd>
+ <dt>Replication-Level:</dt>
+ <dd>
+ An integer which controls how many nearest peers the request
+ should reach.
+ </dd>
+ <dt>Route-Options:</dt>
+ <dd>
+ Flags that are used in order to indicate certain
processing requirements for messages.
Any combination of options as defined in <xref target="route_options"/>
- may be specificied.
- The default setting of this parameter is that no option is set.
+ may be specified.
</dd>
- <dt>Expiration</dt>
+ <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.
+ </t>
</section>
</section>
<section anchor="underlay" numbered="true" toc="default">
@@ -671,6 +721,7 @@ Connectivity | |Underlay| |Underlay|
</section>
<section anchor="p2p_bf" numbered="true" toc="default">
<name>Bloomfilter</name>
+ <!-- FIXME: also discuss result BF -->
<t>
In order to prevent circular routes, GET and PUT messages contain
a 128-bit Bloom filter (m=128). The Bloom filter is used to detect duplicate
