[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[lsd0004] branch master updated (b20dba0 -> 9456947)
|
From: |
gnunet |
|
Subject: |
[lsd0004] branch master updated (b20dba0 -> 9456947) |
|
Date: |
Sat, 24 Dec 2022 07:11:52 +0100 |
This is an automated email from the git hooks/post-receive script.
martin-schanzenbach pushed a change to branch master
in repository lsd0004.
from b20dba0 More bloom filter wording
new 0487d9d Define initiator
new a30b12e Move overlay API example to appendix
new 9456947 More on blocks in overview
The 3 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails. The revisions
listed as "add" were already present in the repository and have only
been added to this reference.
Summary of changes:
draft-schanzen-r5n.xml | 340 +++++++++++++++++++++++++------------------------
1 file changed, 177 insertions(+), 163 deletions(-)
diff --git a/draft-schanzen-r5n.xml b/draft-schanzen-r5n.xml
index b9f8a82..788dfc9 100644
--- a/draft-schanzen-r5n.xml
+++ b/draft-schanzen-r5n.xml
@@ -190,11 +190,16 @@
It includes logic for enforcing storage quotas, caching strategies and
data validation.
</dd>
- <dt>Block-Type:</dt>
+ <dt>Block-Type</dt>
<dd>
A unique 32-bit value identifying the data format of a <tt>Block</tt>.
- Block-Types are either private or allocated by GANA (see
- <xref target="gana"/>).
+ Block-Types are either private or registered in the GANA block type
registry (see
+ <xref target="gana_block_type"/>).
+ </dd>
+ <dt>Initiator</dt>
+ <dd>
+ The peer that initially creates and sends a GetMessage (<xref
target="p2p_get"/>) or
+ PutMessage message (<xref target="p2p_put"/>).
</dd>
<dt>Key</dt>
<dd>
@@ -274,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),
@@ -292,7 +301,7 @@
It also serves as a set of requirements of possible transport
mechanisms that
can be used to implement R<sup>5</sup>N with.
That being said, common transport protocols such as TCP/IP or UDP/IP
and their
- interfaces are suitable R<sup>5N</sup> underlays used by existing
+ interfaces are suitable R<sup>5</sup>N underlays used by existing
implementations.
</t>
<!-- consider moving some of this back into sec considerations -->
@@ -318,6 +327,10 @@
implementation are divided into routing (<xref target="routing"/>),
message processing (<xref target="p2p_messages"/>) and
block processing (<xref target="blockstorage"/>).
+ Applications that require application-specific block payloads are
expected to
+ register a block type in the GANA block type registry (<xref
target="gana_block_type"/>)
+ and provide a specification of the associated block operations (<xref
target="block_functions"/>).
+ to implementors of R<sup>5</sup>N.
<xref target="figure_r5n_arch"/> illustrates the architectural
overview of
R<sup>5</sup>N.
</t>
@@ -348,163 +361,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>
@@ -2880,5 +2737,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>
--
To stop receiving notification emails like this one, please contact
gnunet@gnunet.org.
- [lsd0004] branch master updated (b20dba0 -> 9456947),
gnunet <=