[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[lsd0004] branch master updated: -API description
From: |
gnunet |
Subject: |
[lsd0004] branch master updated: -API description |
Date: |
Thu, 10 Mar 2022 08:26:46 +0100 |
This is an automated email from the git hooks/post-receive script.
grothoff pushed a commit to branch master
in repository lsd0004.
The following commit(s) were added to refs/heads/master by this push:
new 566b586 -API description
566b586 is described below
commit 566b5860a276fa7b5affa13ff2000dbe87299785
Author: Christian Grothoff <grothoff@gnunet.org>
AuthorDate: Thu Mar 10 08:26:40 2022 +0100
-API description
---
draft-schanzen-r5n.xml | 63 ++++++++++++++++++++++++++------------------------
1 file changed, 33 insertions(+), 30 deletions(-)
diff --git a/draft-schanzen-r5n.xml b/draft-schanzen-r5n.xml
index 542d019..d1de3c7 100644
--- 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>
--
To stop receiving notification emails like this one, please contact
gnunet@gnunet.org.
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- [lsd0004] branch master updated: -API description,
gnunet <=