commit 47c99fda35f19ec09921d1b44ea722f11a62ae5a
parent 566b5860a276fa7b5affa13ff2000dbe87299785
Author: Christian Grothoff <grothoff@gnunet.org>
Date: Thu, 10 Mar 2022 10:27:20 +0100
-improve english and consistency
Diffstat:
1 file changed, 24 insertions(+), 17 deletions(-)
diff --git a/draft-schanzen-r5n.xml b/draft-schanzen-r5n.xml
@@ -364,7 +364,7 @@ Connectivity | |Underlay| |Underlay|
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 approximate queries
+ 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"/>.
@@ -390,26 +390,30 @@ Connectivity | |Underlay| |Underlay|
<dd>
the block payload. Contents are specific to the <tt>Block-Type</tt>.
</dd>
- <dt>Expiration:</dt>
+ <dt>Block-Expiration:</dt>
<dd>
- the duration of validity of the result.
+ the expiration time of the block. After this time, the result should no
+ longer be used.
</dd>
<dt>Key:</dt>
<dd>
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.
+ key that was queried if the flag FindApproximate was set.
</dd>
<dt>GET-Path:</dt>
<dd>
- 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.
+ 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 RecordRoute 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 the PUT-Request of this data took through the
- network. Only available if the flag for tracking the path
- was set for the GET procedure.
+ 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 RecordRoute 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>.
@@ -422,7 +426,7 @@ Connectivity | |Underlay| |Underlay|
A PUT procedure may be exposed as:
</t>
<t>
- <tt>PUT(Key, Block-Type, Block-Expiration, Block)</tt>
+ <tt>PUT(Key, Block-Type, Block-Expiration, Block-Data)</tt>
</t>
<t>
The procedure typically takes at least four parameters:
@@ -813,16 +817,16 @@ Connectivity | |Underlay| |Underlay|
value in NBO...-->
</t>
<dl>
- <dt>0: Demultiplex-Everywhere</dt>
+ <dt>0: DemultiplexEverywhere</dt>
<dd>
indicates that each peer along the way should process the request.
</dd>
- <dt>1: Record-Route</dt>
+ <dt>1: RecordRoute</dt>
<dd>
indicates to keep track of the route that the message takes
in the P2P network.
</dd>
- <dt>2: Find-Approximate</dt>
+ <dt>2: FindApproximate</dt>
<dd>
This is a special flag which modifies the message processing to
allow approximate results.
@@ -1589,7 +1593,8 @@ Connectivity | |Underlay| |Underlay|
Any block type implementation <bcp14>MUST</bcp14> implement the following functions.
</t>
<dl>
- <dt>ValidateBlockQuery(Key, XQuery) -> RequestEvaluationResult</dt>
+ <dt>ValidateBlockQuery(Key, XQuery)
+ -> RequestEvaluationResult</dt>
<dd>
is used to evaluate the request for a block. It is used as part of
<tt>GetMessage</tt> processing, where the block payload is still unkown,
@@ -1597,14 +1602,16 @@ Connectivity | |Underlay| |Underlay|
and <tt>Key</tt> can and
<bcp14>MUST</bcp14> be verified, if possible.
</dd>
- <dt>ValidateBlockStoreRequest(Block, Key) -> RequestEvaluationResult</dt>
+ <dt>ValidateBlockStoreRequest(Block, Key)
+ -> RequestEvaluationResult</dt>
<dd>
is used to evaluate a block including its key and payload.
It is used as part of <tt>PutMessage</tt> processing.
The validation <bcp14>MUST</bcp14> include a check of the block payload against the
<tt>Key</tt> under which it is requested to be stored.
</dd>
- <dt>ValidateBlockReply(Block, XQuery, Key) -> ReplyEvaluationResult</dt>
+ <dt>ValidateBlockReply(Block, XQuery, Key)
+ -> ReplyEvaluationResult</dt>
<dd>
is used to evaluate a block including its <tt>Key</tt> and payload.
It is used as part <tt>ResultMessage</tt> processing.
