[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[lsd0004] 03/03: take pass at terminology, suggest changes to disambigua
|
From: |
gnunet |
|
Subject: |
[lsd0004] 03/03: take pass at terminology, suggest changes to disambiguate 'address' |
|
Date: |
Sun, 20 Aug 2023 15:21:15 +0200 |
This is an automated email from the git hooks/post-receive script.
grothoff pushed a commit to branch master
in repository lsd0004.
commit 34d4fc56a3a058ce2e30b71d262f5724d99bd163
Author: Christian Grothoff <grothoff@gnunet.org>
AuthorDate: Sun Aug 20 15:21:05 2023 +0200
take pass at terminology, suggest changes to disambiguate 'address'
---
draft-schanzen-r5n.xml | 95 +++++++++++++++++++++++++++-----------------------
1 file changed, 51 insertions(+), 44 deletions(-)
diff --git a/draft-schanzen-r5n.xml b/draft-schanzen-r5n.xml
index a46db61..1601264 100644
--- a/draft-schanzen-r5n.xml
+++ b/draft-schanzen-r5n.xml
@@ -194,12 +194,12 @@
<t>
is a UTF-8 <xref target="RFC3629"/> URI
<xref target="RFC3986"/> which can be
- used to contact a peer.
+ used to contact a <em>Peer</em>.
An example of an addressing scheme used in
this document is "r5n+ip+tcp", which refers to a standard TCP/IP
socket
connection. The "hier"-part of the URI must provide a suitable
address for the given addressing scheme.
- The following are non-normative examples of address strings:
+ The following are non-normative examples of <em>Address</em> strings:
</t>
<figure title="Example Address URIs.">
<artwork name="" type="" align="left" alt=""><![CDATA[
@@ -211,119 +211,126 @@ gnunet+tcp://12.3.4.5/
</dd>
<dt>Applications</dt>
<dd>
- Applications are components which directly use the DHT overlay
- interfaces. Possible applications include the GNU Name System
+ <em>Application</em>s are higher-layer components which directly use
the DHT overlay
+ interfaces. Possible <em>Application</em>s include the GNU Name System
<xref target="I-D.schanzen-gns"/> and the GNUnet
Confidential Ad-hoc Decentralized End-to-End Transport (CADET)
<xref target="cadet"/>.
</dd>
<dt>Application API</dt>
<dd>
- The application API exposes the core operations of the DHT overlay
- to applications.
- This includes storing blocks in the DHT and retrieving blocks from the
DHT.
+ The <em>Application API</em> exposes the core operations of the DHT
overlay
+ to <em>Applications</em>.
+ This includes storing <em>Block</em>s in the DHT and retrieving
+ <em>Block</em>s from the DHT.
</dd>
<dt>Block</dt>
<dd>
Variable-size unit of payload stored in the DHT
- under a <tt>Key</tt>.
+ under a <em>Key</em>.
In the context of "key-value stores" this
- refers to "value" stored under a key.
+ refers to "value" stored under a <em>Key</em>.
</dd>
<dt>Block Storage</dt>
<dd>
- The <tt>Block Storage</tt> component is used to persist and manage
- <tt>Block</tt> data by peers.
+ The <em>Block Storage</em> component is used to persist and manage
+ <em>Block</em>s stored by <em>Peer</em>s.
It includes logic for enforcing storage quotas, caching strategies and
- data validation.
+ <em>Block</em> validation.
</dd>
<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 registered in the GANA block type
registry (see
+ A unique 32-bit value identifying the data format of a <em>Block</em>.
+ <em>Block-Types</em> are either private or registered in the GANA
block type registry (see
<xref target="gana_block_type"/>).
</dd>
<dt>Bootstrapping</dt>
<dd>
- Bootstrapping is the initial process of establishing a connection to
the peer-to-peer
+ <em>Bootstrapping</em> is the initial process of establishing a
connection
+ to the peer-to-peer
network.
- This initially requires an initial, non-empty set of reachable peers
and corresponding
- addresses supported by the implementation to connect to.
+ This initially requires an initial, non-empty set of reachable
<em>Peer</em>s and corresponding
+ <em>Address</em>es supported by the implementation to connect to.
</dd>
<dt>Initiator</dt>
<dd>
- The peer that initially creates and sends a DHT protocol message
(<xref target="p2p_hello"/>,
+ The <em>Peer</em> that initially creates and sends a DHT protocol
message (<xref target="p2p_hello"/>,
<xref target="p2p_put"/>, <xref target="p2p_get"/>, <xref
target="p2p_result"/>).
</dd>
<dt>HELLO block</dt>
<dd>
- A <tt>HELLO</tt> block is a block with a dedicated block type and is
specified in this document.
- The <tt>HELLO</tt> block is used to store and retrieve Peer addresses.
+ A <tt>HELLO block</tt> is a <em>Block</em> with a <em>Block-Type</em>
<tt>DHT_HELLO</tt> (13).
+ A <tt>HELLO block</tt> is used to store and retrieve
<em>Address</em>es of a <em>Peer</em>.
In this document, <tt>HELLO</tt> blocks are used by the peer discovery
mechanism.
</dd>
<dt>HELLO URL</dt>
<dd>
- <tt>HELLO</tt> URLs are <tt>HELLO</tt> blocks in a URL representation.
- They can used for out-of-band exchanges of peer information and are
used for
- address update signalling messages to neighbours. Example HELLO URLs
and their
+ <tt>HELLO</tt> URLs are <tt>HELLO</tt> blocks represented as URLs.
+ They can used for out-of-band exchanges of <em>Peer</em>
<em>Address</em>
+ information and are used for
+ address update signalling messages to <em>Neighbours</em>. Example
HELLO URLs and their
format can be found in <xref target="hello_url"/>.
</dd>
<dt>Key</dt>
<dd>
512-bit identifier of a location in the DHT. Multiple <tt>Block</tt>s
can be
- stored under the same key. <tt>Peer Addresses</tt> are valid keys.
+ stored under the same <em>Key</em>. A <em>Peer Address</em> is also a
<tt>Key</tt>.
In the context of "key-value stores" this
- refers to "key" under which values (blocks) are stored.
+ refers to "key" under which values (<em>Block</em>s) are
stored.
</dd>
<dt>Message Processing</dt>
<dd>
- The Message Processing component processes requests from and
- generates responses to applications and the underlay network.
+ The <em>Message Processing</em> component of the DHT implementation
processes
+ requests from and generates responses to <em>Application</em>s
+ and the <em>Underlay Interface</em>.
</dd>
<dt>Neighbor</dt>
<dd>
- A neighbor is a peer which is directly able to communicate
- with our peer via the <tt>Underlay Interface</tt>.
+ A neighbor is a <em>Peer</em> which is directly able to communicate
+ with our <em>Peer</em> via the <em>Underlay Interface</em>.
</dd>
<dt>Peer</dt>
<dd>
- A host that is participating in the overlay. Peers are
+ A host that is participating in the overlay by running an
implementation
+ of the DHT protocol. Each participating host is
responsible for holding some portion of the data that has been
stored in the overlay, and they are responsible for routing
- messages on behalf of other hosts as needed by the Routing
- Algorithm.
+ messages on behalf of other <em>Peer</em>s as needed by the <em>Routing
+ Algorithm</em>.
</dd>
+ <!-- FIXME: this overloads the term 'address'. We should use 'Peer
Identity'! -->
<dt>Peer Address</dt>
<dd>
- The <tt>Peer Address</tt> is the identifier used on the Overlay
- to address a peer.
- It is a SHA-512 hash of the <tt>Peer ID</tt>.
+ The <em>Peer Address</em> is the identifier used on the overlay
+ to identify a <em>Peer</em>. It is a SHA-512 hash of the <tt>Peer
ID</tt>.
</dd>
+ <!-- FIXME: this obscures the public key nature. We should use "Peer
Public Key"! -->
<dt>Peer ID</dt>
<dd>
- The <tt>Peer ID</tt> is the public key which is used to authenticate
- a peer in the underlay.
- The Peer ID is the public key of the corresponding
+ The <em>Peer ID</em> is the public key which is used to authenticate
+ a <em>Peer</em> in the underlay.
+ The <em>Peer ID</em> is the public key of the corresponding
Ed25519<xref target="ed25519" /> peer private key.
</dd>
<dt>Routing</dt>
<dd>
- The Routing component includes the routing table as well as
- routing and peer selection logic. It facilitates the R<sup>5</sup>N
routing
+ The <em>Routing</em> component includes the routing table as well as
+ routing and <em>Peer</em> selection logic. It facilitates the
R<sup>5</sup>N routing
algorithm with required data structures and algorithms.
</dd>
<dt>Responsible Peer</dt>
<dd>
- The peer <tt>N</tt> that is responsible for a specific key <tt>K</tt>,
as
+ The <em>Peer</em> <tt>N</tt> that is responsible for a specific key
<tt>K</tt>, as
defined by the <tt>SelectClosestPeer(K, P)</tt> algorithm (see
<xref target="routing"/>.
</dd>
<dt>Underlay Interface</dt>
<dd>
- The Underlay Interface is an abstraction layer on top of the
- supported links of a peer. Peers may be linked by a variety of
+ The <em>Underlay Interface</em> is an abstraction layer on top of the
+ supported links of a <em>Peer</em>. Peers may be linked by a variety of
different transports, including "classical" protocols such as
- TCP, UDP and TLS or advanced protocols such as GNUnet, I2P or Tor.
+ TCP, UDP and TLS or higher-layer protocols such as GNUnet, I2P or Tor.
+ <!-- FIXME: add references to GNUnet/I2P/Tor here! -->
</dd>
</dl>
</section>
--
To stop receiving notification emails like this one, please contact
gnunet@gnunet.org.