[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[lsd0004] 02/03: Move overlay API example to appendix
|
From: |
gnunet |
|
Subject: |
[lsd0004] 02/03: Move overlay API example to appendix |
|
Date: |
Sat, 24 Dec 2022 07:11:54 +0100 |
This is an automated email from the git hooks/post-receive script.
martin-schanzenbach pushed a commit to branch master
in repository lsd0004.
commit a30b12ede79e38375d6a20ae24b02a991e05aecf
Author: Martin Schanzenbach <schanzen@gnunet.org>
AuthorDate: Sat Dec 24 14:59:04 2022 +0900
Move overlay API example to appendix
---
draft-schanzen-r5n.xml | 323 +++++++++++++++++++++++++------------------------
1 file changed, 164 insertions(+), 159 deletions(-)
diff --git a/draft-schanzen-r5n.xml b/draft-schanzen-r5n.xml
index 0ed3898..51a0ca3 100644
--- a/draft-schanzen-r5n.xml
+++ b/draft-schanzen-r5n.xml
@@ -279,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),
@@ -353,163 +357,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>
@@ -2885,5 +2733,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.