summaryrefslogtreecommitdiff
path: root/draft-schanzen-r5n.xml
diff options
context:
space:
mode:
Diffstat (limited to 'draft-schanzen-r5n.xml')
-rw-r--r--draft-schanzen-r5n.xml323
1 files 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 @@
279 </li> 279 </li>
280 </ul> 280 </ul>
281 <t> 281 <t>
282 The specific semantics of the above operations as provided by R<sup>5</sup>N 282 A peer or its implementation does not necessarily need to expose the above operations
283 for applications are defined in <xref target="overlay"/>. 283 to applications but it commonly will.
284 For example, the peer could be a server purely used for bootstrapping, routing or
285 supporting the overlay network with resources.
286 An example for possible semantics of the above operations provided as an API to applications by an
287 implementation are outlined in <xref target="overlay"/>.
284 </t> 288 </t>
285 <t> 289 <t>
286 In a trivial scenario where there is only one peer (the local host), 290 In a trivial scenario where there is only one peer (the local host),
@@ -353,163 +357,7 @@ Connectivity | |Underlay| |Underlay|
353 </artwork> 357 </artwork>
354 </figure> 358 </figure>
355 </section> 359 </section>
356 <section anchor="overlay" numbered="true" toc="default"> 360
357 <name>Overlay Operations</name>
358 <t>
359 An implementation of this specification commonly exposes the two overlay
360 operations "GET" and "PUT".
361 The following are non-normative examples of APIs for those operations.
362 Their behaviour is described prosaically in order to give implementers a fuller
363 picture of the protocol.
364 </t>
365 <section>
366 <name>GET operation</name>
367 <t>
368 A basic GET operation interface may be exposed as:
369 </t>
370 <t>
371 <tt>GET(Query-Key, Block-Type) -> Results as List</tt>
372 </t>
373 <t>
374 The procedure typically takes at least two arguments to initiate a lookup:
375 </t>
376 <dl>
377 <dt><tt>QueryKey</tt>:</dt>
378 <dd>
379 is the 512-bit key to look for in the DHT.
380 </dd>
381 <dt>Block-Type:</dt>
382 <dd>
383 is the type of block to look for, possibly "any".
384 </dd>
385 </dl>
386 <t>
387 The GET procedure may allow a set of optional parameters in order to
388 control or modify the query:
389 </t>
390 <dl>
391 <dt>Replication-Level:</dt>
392 <dd>
393 is an integer which controls how many nearest peers the request
394 should reach.
395 </dd>
396 <dt>Flags:</dt>
397 <dd>
398 is a 16-bit vector which indicates certain
399 processing requirements for messages.
400 Any combination of flags as defined in <xref target="route_flags"/>
401 may be specified.
402 </dd>
403 <dt>eXtended-Query (XQuery):</dt>
404 <dd>
405 is medatadata which may be
406 required depending on the respective <tt>Block-Type</tt>.
407 A <tt>Block-Type</tt> must define if the <tt>XQuery</tt> can or must
408 be used and what the specific format of its contents should be.
409 Extended queries are in general used to implement domain-specific filters.
410 These might be particularly useful in combination with FindApproximate
411 to add a well-defined filter by an application-specific distance.
412 Regardless, the DHT does not define any particular semantics for an XQuery.
413 See also <xref target="blockstorage"/>.
414 </dd>
415 <dt>Result-Filter:</dt>
416 <dd>
417 is data for a <tt>Block-type</tt>-specific filter
418 which allows applications to
419 indicate results which are
420 not relevant anymore to the
421 caller (see <xref target="result_filter"/>).
422 </dd>
423 </dl>
424 <t>
425 The GET procedure should be implemented as an asynchronous
426 operation that returns individual results as they are found
427 in the DHT. It should terminate only once the application
428 explicitly cancels the operation. A single result commonly
429 consists of:</t>
430 <dl>
431 <dt>Block-Type:</dt>
432 <dd>
433 is the desired type of block in the result.
434 </dd>
435 <dt>Block-Data:</dt>
436 <dd>
437 is the application-specific block payload. Contents are specific to the <tt>Block-Type</tt>.
438 </dd>
439 <dt>Block-Expiration:</dt>
440 <dd>
441 is the expiration time of the block. After this time, the result should no
442 longer be used.
443 </dd>
444 <dt>Key:</dt>
445 <dd>
446 is the key under which the block was stored. This may be different from the
447 key that was queried if the flag FindApproximate was set.
448 </dd>
449 <dt>GET-Path:</dt>
450 <dd>
451 is a signed path of the IDs of peers which the query
452 traversed through the network. The DHT will try to make
453 the path available if the <tt>RecordRoute</tt> flag was set by
454 the application calling the PUT procedure. The reported
455 path may have been silently truncated from the beginning.
456 </dd>
457 <dt>PUT-Path:</dt>
458 <dd>
459 is a signed path of the IDs of peers which the
460 result message traversed. The DHT will try to make the
461 path available if the <tt>RecordRoute</tt> flag was set for the GET procedure.
462 The reported path may have been silently truncated from the beginning.
463 As the block was cached by the node at the end of this
464 path, this path is more likely to be stale compared to the
465 <tt>GET-Path</tt>.
466 </dd>
467 </dl>
468 </section>
469 <section>
470 <name>PUT operation</name>
471 <t>
472 A PUT operation interface may be exposed as:
473 </t>
474 <t>
475 <tt>PUT(Key, Block-Type, Block-Expiration, Block-Data)</tt>
476 </t>
477 <t>
478 The procedure typically takes at least four parameters:
479 </t>
480 <dl>
481 <dt>Key:</dt>
482 <dd>is the key under which to store the block.</dd>
483 <dt>Block-Type:</dt>
484 <dd>is the type of the block to store.</dd>
485 <dt>Block-Expiration:</dt>
486 <dd>specifies when the block should expire.</dd>
487 <dt>Block-Data:</dt>
488 <dd>is the application-specific payload of the block to store.</dd>
489 </dl>
490 <t>
491 The PUT procedure may allow a set of optional parameters in order to
492 control or modify the query:
493 </t>
494 <dl>
495 <dt>Replication-Level:</dt>
496 <dd>
497 is an integer which controls how many nearest peers the request
498 should reach.
499 </dd>
500 <dt>Flags:</dt>
501 <dd>
502 is a bit-vector which indicates certain
503 processing requirements for messages.
504 Any combination of flags as defined in <xref target="route_flags"/>
505 may be specified.
506 </dd>
507 </dl>
508 <t>
509 The PUT procedure does not necessarily yield any information.
510 </t>
511 </section>
512 </section>
513 <section anchor="underlay" numbered="true" toc="default"> 361 <section anchor="underlay" numbered="true" toc="default">
514 <name>Underlay</name> 362 <name>Underlay</name>
515 <t> 363 <t>
@@ -2885,5 +2733,162 @@ Type | Name | References | Description
2885 Otherwise, the element is not considered to be in the Bloom filter. 2733 Otherwise, the element is not considered to be in the Bloom filter.
2886 </t> 2734 </t>
2887 </section> 2735 </section>
2736 <section anchor="overlay" numbered="true" toc="default">
2737 <name>Overlay Operations</name>
2738 <t>
2739 An implementation of this specification commonly exposes the two overlay
2740 operations "GET" and "PUT".
2741 The following are non-normative examples of APIs for those operations.
2742 Their behaviour is described prosaically in order to give implementers a fuller
2743 picture of the protocol.
2744 </t>
2745 <section>
2746 <name>GET operation</name>
2747 <t>
2748 A basic GET operation interface may be exposed as:
2749 </t>
2750 <t>
2751 <tt>GET(Query-Key, Block-Type) -> Results as List</tt>
2752 </t>
2753 <t>
2754 The procedure typically takes at least two arguments to initiate a lookup:
2755 </t>
2756 <dl>
2757 <dt><tt>QueryKey</tt>:</dt>
2758 <dd>
2759 is the 512-bit key to look for in the DHT.
2760 </dd>
2761 <dt>Block-Type:</dt>
2762 <dd>
2763 is the type of block to look for, possibly "any".
2764 </dd>
2765 </dl>
2766 <t>
2767 The GET procedure may allow a set of optional parameters in order to
2768 control or modify the query:
2769 </t>
2770 <dl>
2771 <dt>Replication-Level:</dt>
2772 <dd>
2773 is an integer which controls how many nearest peers the request
2774 should reach.
2775 </dd>
2776 <dt>Flags:</dt>
2777 <dd>
2778 is a 16-bit vector which indicates certain
2779 processing requirements for messages.
2780 Any combination of flags as defined in <xref target="route_flags"/>
2781 may be specified.
2782 </dd>
2783 <dt>eXtended-Query (XQuery):</dt>
2784 <dd>
2785 is medatadata which may be
2786 required depending on the respective <tt>Block-Type</tt>.
2787 A <tt>Block-Type</tt> must define if the <tt>XQuery</tt> can or must
2788 be used and what the specific format of its contents should be.
2789 Extended queries are in general used to implement domain-specific filters.
2790 These might be particularly useful in combination with FindApproximate
2791 to add a well-defined filter by an application-specific distance.
2792 Regardless, the DHT does not define any particular semantics for an XQuery.
2793 See also <xref target="blockstorage"/>.
2794 </dd>
2795 <dt>Result-Filter:</dt>
2796 <dd>
2797 is data for a <tt>Block-type</tt>-specific filter
2798 which allows applications to
2799 indicate results which are
2800 not relevant anymore to the
2801 caller (see <xref target="result_filter"/>).
2802 </dd>
2803 </dl>
2804 <t>
2805 The GET procedure should be implemented as an asynchronous
2806 operation that returns individual results as they are found
2807 in the DHT. It should terminate only once the application
2808 explicitly cancels the operation. A single result commonly
2809 consists of:</t>
2810 <dl>
2811 <dt>Block-Type:</dt>
2812 <dd>
2813 is the desired type of block in the result.
2814 </dd>
2815 <dt>Block-Data:</dt>
2816 <dd>
2817 is the application-specific block payload. Contents are specific to the <tt>Block-Type</tt>.
2818 </dd>
2819 <dt>Block-Expiration:</dt>
2820 <dd>
2821 is the expiration time of the block. After this time, the result should no
2822 longer be used.
2823 </dd>
2824 <dt>Key:</dt>
2825 <dd>
2826 is the key under which the block was stored. This may be different from the
2827 key that was queried if the flag FindApproximate was set.
2828 </dd>
2829 <dt>GET-Path:</dt>
2830 <dd>
2831 is a signed path of the IDs of peers which the query
2832 traversed through the network. The DHT will try to make
2833 the path available if the <tt>RecordRoute</tt> flag was set by
2834 the application calling the PUT procedure. The reported
2835 path may have been silently truncated from the beginning.
2836 </dd>
2837 <dt>PUT-Path:</dt>
2838 <dd>
2839 is a signed path of the IDs of peers which the
2840 result message traversed. The DHT will try to make the
2841 path available if the <tt>RecordRoute</tt> flag was set for the GET procedure.
2842 The reported path may have been silently truncated from the beginning.
2843 As the block was cached by the node at the end of this
2844 path, this path is more likely to be stale compared to the
2845 <tt>GET-Path</tt>.
2846 </dd>
2847 </dl>
2848 </section>
2849 <section>
2850 <name>PUT operation</name>
2851 <t>
2852 A PUT operation interface may be exposed as:
2853 </t>
2854 <t>
2855 <tt>PUT(Key, Block-Type, Block-Expiration, Block-Data)</tt>
2856 </t>
2857 <t>
2858 The procedure typically takes at least four parameters:
2859 </t>
2860 <dl>
2861 <dt>Key:</dt>
2862 <dd>is the key under which to store the block.</dd>
2863 <dt>Block-Type:</dt>
2864 <dd>is the type of the block to store.</dd>
2865 <dt>Block-Expiration:</dt>
2866 <dd>specifies when the block should expire.</dd>
2867 <dt>Block-Data:</dt>
2868 <dd>is the application-specific payload of the block to store.</dd>
2869 </dl>
2870 <t>
2871 The PUT procedure may allow a set of optional parameters in order to
2872 control or modify the query:
2873 </t>
2874 <dl>
2875 <dt>Replication-Level:</dt>
2876 <dd>
2877 is an integer which controls how many nearest peers the request
2878 should reach.
2879 </dd>
2880 <dt>Flags:</dt>
2881 <dd>
2882 is a bit-vector which indicates certain
2883 processing requirements for messages.
2884 Any combination of flags as defined in <xref target="route_flags"/>
2885 may be specified.
2886 </dd>
2887 </dl>
2888 <t>
2889 The PUT procedure does not necessarily yield any information.
2890 </t>
2891 </section>
2892 </section>
2888 </back> 2893 </back>
2889</rfc> 2894</rfc>