diff options
Diffstat (limited to 'draft-schanzen-r5n.xml')
-rw-r--r-- | draft-schanzen-r5n.xml | 323 |
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> |