[lsd0004] 03/03: Rewrite architecture and structure into an overview

[gnunet]

This is an automated email from the git hooks/post-receive script.

martin-schanzenbach pushed a commit to branch master
in repository lsd0004.

commit a1beda531e0f6d6e138d5a14cf774ee933f2b32a
Author: Martin Schanzenbach <schanzen@gnunet.org>
AuthorDate: Fri Dec 23 19:13:06 2022 +0900

    Rewrite architecture and structure into an overview
---
 draft-schanzen-r5n.xml | 105 ++++++++++++++++++++++++++++++-------------------
 1 file changed, 65 insertions(+), 40 deletions(-)

diff --git a/draft-schanzen-r5n.xml b/draft-schanzen-r5n.xml
index 04d0210..384872b 100644
--- a/draft-schanzen-r5n.xml
+++ b/draft-schanzen-r5n.xml
@@ -254,39 +254,75 @@
     </dl>
     </section>
     <section>
-      <name>Structure of This Document</name>
+      <name>Overview</name>
       <t>
-          <xref target="terminology"/> gives an overview of the terminology 
used in
-    this document.
-    <xref target="architecture"/> then describes the overall architecture and
-    the scope of this specification.
-    <xref target="overlay"/> describes the application API, which clarifies
-    the semantics provided by R<sup>5</sup>N for applications
-    and thus is crucial as it motivates the rest of the design.
-    <xref target="underlay"/> describes the underlay interface. This is the
-    abstraction that applications must provide to R<sup>5</sup>N
-    and thus a prerequisite for using the DHT.
-    Before a DHT is usable, it must be bootstrapped.
-    Bootstrapping is described in <xref target="bootstrapping"/>.
-    Bloom filters, a key data structure used in various
-    places, are introduced in <xref target="bloom_filters" />
-    The central operation of a DHT is routing, which is
-    detailed in <xref target="routing"/>. The processing of the various
-    network messages is described in <xref target="p2p_messages"/>.  Handling
-    of Blocks, including validation and storage are described
-    in <xref target="blockstorage"/>. General security considerations are 
detailed
-    in <xref target="security" />. IANA and GANA registry updates are listed
-    in <xref target="iana" /> and <xref target="gana"/>. The document 
concludes with test
-    vectors in <xref target="testvectors"/> and appendices with references.
+        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:
       </t>
-    </section>
-    <section anchor="architecture" numbered="true" toc="default">
-      <name>Architecture</name>
+      <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.
+          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.
+          In the classical definition of a dictionary interface, this 
operation would be
+          called "find".
+        </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"/>.
+        The handling of blocks and their validation and storage is defined in
+        <xref target="blockstorage".
+      </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.
+        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
+        mechanism such as TCP/IP.
+        R<sup>5</sup>N is agnostic to the underlying transport protocol which 
is why
+        this document defines a common addressing and messaging interface in
+        <xref target="underlay"/>.
+        The interface provided by this underlay is used across the 
specification of the
+        R<sup>5</sup>N protocol.
+        It also serves as a set of requirements of possible transport 
mechanism that
+        can be used to implement R<sup>5</sup>N on.
+        That being said, common transport protocols such as TCP/IP or UDP/IP 
are
+        supported.
+      </t>
+      <!-- consider moving some of this back into sec considerations -->
       <t>
-        R<sup>5</sup>N is an overlay network with a pluggable transport layer.
-        The following figure shows the R<sup>5</sup>N architecture.
+        Specifics about the protocols of the underlays providing
+       connectivity or the applications using the DHT are out of
+       the scope of this document.  However, we note that peers
+       implementing disjoint sets of underlay protocols may
+       experience difficulties communicating (unless other peers
+       bridge the respective underlays). Similarly, peers that
+       do not support a particular application will not be able
+       to validate application-specific payloads and may thus be
+       tricked into storing or forwarding corrupt blocks.
       </t>
-      <figure title="The R5N Architecture.">
+      <t>
+        In order to establish an initial connection to a network of 
R<sup>5</sup>N
+        peers, an initial, addressable bootstrap peer is required.
+        Further peers, including neighbors, are then learned via a 
bootstrapping
+        process as defined in <xref target="bootstrapping"/>.
+      </t>
+      <t>
+        Across this document, the functional components of an R<sup>5</sup>N
+        implementation are divided into block processing (<xref 
target="blockstorage"),
+        message processing (<xref target="p2p_messages") and routing
+        (<xref target="routing").
+        <xref taget="figure_r5n_arch" illustrates the architectural overview of
+        R<sup>5</sup>N.
+      </t>
+      <figure anchor="figure_r5n_arch" title="The R5N architecture.">
         <artwork><![CDATA[
              |  +-----------------+  +-------+
 Applications |  | GNU Name System |  | CADET |  ...
@@ -312,17 +348,6 @@ Connectivity | |Underlay|  |Underlay|
 ]]>
         </artwork>
       </figure>
-      <t>
-        Specifics about the protocols of the underlays providing
-       connectivity or the applications using the DHT are out of
-       the scope of this document.  However, we note that peers
-       implementing disjoint sets of underlay protocols may
-       experience difficulties communicating (unless other peers
-       bridge the respective underlays). Similarly, peers that
-       do not support a particular application will not be able
-       to validate application-specific payloads and may thus be
-       tricked into storing or forwarding corrupt blocks.
-      </t>
     </section>
     <section anchor="overlay" numbered="true" toc="default">
       <name>Application API</name>

-- 
To stop receiving notification emails like this one, please contact
gnunet@gnunet.org.