commit 90bf72e5e98a0534d9b24e52c3b0c33b20344151
parent 34d4fc56a3a058ce2e30b71d262f5724d99bd163
Author: Christian Grothoff <grothoff@gnunet.org>
Date: Sun, 20 Aug 2023 16:11:12 +0200
minor edits, comments on questions
Diffstat:
1 file changed, 68 insertions(+), 38 deletions(-)
diff --git a/draft-schanzen-r5n.xml b/draft-schanzen-r5n.xml
@@ -337,34 +337,48 @@ gnunet+tcp://12.3.4.5/
<section>
<name>Overview</name>
<t>
- In R<sup>5</sup>N peers communicate with each other in order to realize and
- maintain two basic operations of a distributed hash table:
+ In R<sup>5</sup>N peers communicate with each other to provide
+ the two fundamental operations of any distributed hash table:
</t>
<ul>
<li>
- PUT: This operation stores a block payload on one or more peers with
- the goal of making the block availiable for queries using the GET operation.
+ <tt>PUT</tt>: This operation stores a <em>Block</em>
+ under a <em>Key</em> on one or more <em>Peer</em>s with
+ the goal of making the <em>Block</em> availiable for queries using the <tt>GET</tt> operation.
In the classical definition of a dictionary interface, this operation would be
called "insert".
</li>
<li>
- GET: This operation queries the network of peers for blocks
- previously stored under or near the key.
+ <tt>GET</tt>: This operation queries the network of peers for any number of <em>Block</em>s
+ previously stored under or near a <em>Key</em>.
In the classical definition of a dictionary interface, this operation would be
called "find".
</li>
</ul>
<t>
- 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"/>.
+ 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),
- R<sup>5</sup>N operates in a very similar fashion to a dictionary data structure.
+ A <em>Peer</em> does not necessarily need to expose the above
+ operations to <em>Application</em>s, but it commonly will. A
+ <em>Peer</em> that does not expose the above operations could
+ be a host purely used for <em>Bootstrapping</em>,
+ <em>Routing</em> or supporting
+ the overlay network with resources.
+ </t>
+ <t>
+ Similarly, there could be hosts on the network that
+ participate in the DHT but do not route traffic or store
+ data. Examples for such hosts would be mobile devices with
+ limited bandwidth, battery and storage capacity. Such hosts
+ may be used to run applications that use the DHT. However, we
+ will not refer to such hosts as <em>Peer</em>s.
+ </t>
+ <t>
+ In a trivial scenario where there is only one <em>Peer</em> (on the local host),
+ R<sup>5</sup>N operates similarly to a dictionary data structure.
However, the default use case is one where nodes communicate directly and
indirectly in order to realize a distributed storage mechanism.
This communication requires a lower-level peer addressing and message transport
@@ -382,27 +396,32 @@ gnunet+tcp://12.3.4.5/
</t>
<!-- consider moving some of this back into sec considerations -->
<t>
- Specifics about the protocols of the underlays providing
- connectivity or the applications using the DHT are out of
- the scope of this document.
+ Specifics about the protocols of the underlays implementing
+ the <em>Underlay Interface</em> or the <em>Application</em>s
+ using the DHT are out of the scope of this document.
</t>
<t>
- In order to establish an initial connection to a network of R<sup>5</sup>N
- peers, at least one initial, addressable peer is required as part of the bootstrapping process.
- Further peers, including neighbors, are then learned via a peer discovery
- process as defined in <xref target="find_peer"/>.
+ To establish an initial connection to a network of
+ R<sup>5</sup>N peers, at least one initial, addressable
+ <em>Peer</em> is required as part of the
+ <em>Bootstrapping</em> process. Further <em>Peer</em>s,
+ including <em>Neighbor</em>s, are then learned via a peer
+ discovery process as defined in <xref target="find_peer"/>.
</t>
<t>
- Across this document, the functional components of an R<sup>5</sup>N
- 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.
+ Across this document, the functional components of an
+ R<sup>5</sup>N implementation are divided into
+ <em>Routing</em> (<xref target="routing"/>), <em>Message
+ Processing</em> (<xref target="p2p_messages"/>) and
+ <em>Block</em> processing (<xref target="blockstorage"/>).
+ <em>Application</em>s that require application-specific
+ <em>Block</em> payloads are expected to register a
+ <em>Block-Type</em> in the GANA <em>Block-Type</em> 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>
<figure anchor="figure_r5n_arch" title="The R5N architecture.">
<artwork><