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.xml200
1 files changed, 110 insertions, 90 deletions
diff --git a/draft-schanzen-r5n.xml b/draft-schanzen-r5n.xml
index b346566..5218e94 100644
--- a/draft-schanzen-r5n.xml
+++ b/draft-schanzen-r5n.xml
@@ -258,96 +258,6 @@ PUT(key[, options], BLOCK)
258 </t> 258 </t>
259 </section> 259 </section>
260 </section> 260 </section>
261 <section anchor="blockstorage" numbered="true" toc="default">
262 <name>Block Storage</name>
263 <section>
264 <name>Block Processing</name>
265 <dl>
266 <dt>OK_MORE</dt>
267 <dd>Valid result, and there may be more.</dd>
268 <dt>OK_LAST</dt>
269 <dd>Last possible valid result.</dd>
270 <dt>OK_DUPLICATE</dt>
271 <dd>Valid result, but duplicate.</dd>
272 <dt>RESULT_INVALID</dt>
273 <dd>Invalid result. Block does not match query. Value = 4.</dd>
274 <dt>RESULT_IRRELEVANT</dt>
275 <dd>Block does not match xquery. Valid result, but not relevant for the request.</dd>
276 <dt>REQUEST_VALID</dt>
277 <dd>Query is valid, no reply given.</dd>
278 <dt>REQUEST_INVALID</dt>
279 <dd>
280 Query format does not match block type. For example, xquery not
281 given or xquery_size not appropriate for type.
282 </dd>
283 <dt>TYPE_NOT_SUPPORTED</dt>
284 <dd>Specified block type not supported by this implementation. FIXME: We may not need this for the spec.</dd>
285 </dl>
286 </section>
287 <section anchor="block_functions">
288 <name>Block Functions</name>
289 <t>
290 Any block type implementation MUST implement the following functions.
291 </t>
292 <dl>
293 <dt>Evaluate-BlockRequest</dt>
294 <dd>
295 is used to evaluate the request for a block. It is used as part of
296 GET message processing, where the block payload is still unkown,
297 but the block XQUERY (FIXME: Undefined here) and key can and should
298 be verified, if possible.
299 </dd>
300 <dt>Evaluate-BlockReply</dt>
301 <dd>
302 is used to evaluate a block including its key and payload.
303 It is used as part of PUT and RESULT message processing.
304 An implementation MAY also use evaluate locally stored blocks
305 (FIXME again?) before passing it to other peers or the Overlay.
306 </dd>
307 <dt>Get-BlockKey</dt>
308 <dd>
309 is used to synthesize the block key from the block payload
310 and metadata. It is used as part of PUT message processing.
311 (FIXME: The implementation currently does PUT block key validation
312 and then Block Evaluate-BlockReply ONLY for RegEx...)
313 </dd>
314 </dl>
315 </section>
316 <section>
317 <name>Block Types</name>
318 <t>
319 Applications can and should define their own block types.
320 The block type determines the format and handling of the block
321 payload by peers in PUT and RESULT messages.
322 Block types MUST be registered with GANA <xref target="gana"/>.
323 </t>
324 <t>
325 For bootstrapping and peer discovery, the DHT implementation uses
326 its own block type called "HELLO". A block with this block type
327 contains the peer ID of the peer initiating the GET request.
328 </t>
329 <section>
330 <name>HELLO</name>
331 <t>
332 The HELLO block type wire format is illustrated in
333 <xref target="figure_hellobt"/>. A block of type HELLO MUST NOT
334 include extended query data (xquery). Any implementation
335 encountering a HELLO block with xquery data MUST consider the
336 block invalid and ignore it.
337 </t>
338 <t>
339 A HELLO reply block MAY be empty. Otherwise, it contains the
340 HELLO URI of a peer.
341 </t>
342 <figure anchor="figure_hellobt">
343 <artwork name="" type="" align="left" alt=""><![CDATA[
344 FIXME: Wire format
345 ]]></artwork>
346 </figure>
347 </section>
348 </section>
349 </section>
350
351 <section anchor="underlay" numbered="true" toc="default"> 261 <section anchor="underlay" numbered="true" toc="default">
352 <name>Underlay</name> 262 <name>Underlay</name>
353 <t> 263 <t>
@@ -1063,6 +973,116 @@ END
1063 </section> 973 </section>
1064 </section> 974 </section>
1065 </section> 975 </section>
976 <section anchor="blockstorage" numbered="true" toc="default">
977 <name>Block Storage</name>
978 <section>
979 <name>Block Processing</name>
980 <t>RequestEvaluationResult</t>
981 <dl>
982 <dt>REQUEST_VALID</dt>
983 <dd>Query is valid, no reply given.</dd>
984 <dt>REQUEST_INVALID</dt>
985 <dd>
986 Query format does not match block type. For example, XQuery not
987 given or of size of XQuery is not appropriate for type.
988 </dd>
989 </dl>
990 <t>ReplyEvaluationResult</t>
991 <dl>
992 <dt>OK_MORE</dt>
993 <dd>Valid result, and there may be more.</dd>
994 <dt>OK_LAST</dt>
995 <dd>Last possible valid result.</dd>
996 <dt>OK_DUPLICATE</dt>
997 <dd>Valid result, but duplicate.</dd>
998 <dt>RESULT_INVALID</dt>
999 <dd>Invalid result. Block does not match query. Value = 4.</dd>
1000 <dt>RESULT_IRRELEVANT</dt>
1001 <dd>Block does not match xquery. Valid result, but not relevant for the request.</dd>
1002 </dl>
1003 </section>
1004 <section anchor="block_functions">
1005 <name>Block Functions</name>
1006 <t>
1007 Any block type implementation MUST implement the following functions.
1008 </t>
1009 <dl>
1010 <dt>ValidateBlockQuery(Key, XQuery) -> QueryEvaluationResult</dt>
1011 <dd>
1012 is used to evaluate the request for a block. It is used as part of
1013 <tt>GetMessage</tt> processing, where the block payload is still unkown,
1014 but the block <tt>XQuery</tt> (FIXME: Undefined here) and <tt>Key</tt> can and
1015 MUST be verified, if possible.
1016 </dd>
1017 <dt>ValidateBlockStoreRequest(PutMessage, Key) -> StoreRequestEvaluationResult</dt>
1018 <dd>
1019 is used to evaluate a block including its key and payload.
1020 It is used as part of <tt>PutMessage</tt> processing.
1021 The validation MUST include a check of the block payload against the
1022 <tt>Key</tt> under which it is requested to be stored.
1023 </dd>
1024 <dt>ValidateBlockReply(ResultMessage, XQuery, Key) -> ReplyEvaluationResult</dt>
1025 <dd>
1026 is used to evaluate a block including its <tt>Key</tt> and payload.
1027 It is used as part <tt>ResultMessage</tt> processing.
1028 The validation of a <tt>ResultMessage</tt> requires a pending local query
1029 or a previously routed request of another peer and its associated
1030 XQuery data and Key.
1031 The validation MUST include a check of the block payload against the
1032 key under which it is requested to be stored.
1033 </dd>
1034 <dt>DeriveBlockKey(Block) -> Key</dt>
1035 <dd>
1036 is used to synthesize the block key from the block payload
1037 and metadata. It is used as part of FIND-PEER message processing.
1038 </dd>
1039 <dt>FilterResult(Block, XQuery, Key) -> ReplyEvaluationResult</dt>
1040 <dd>
1041 is used to filter results stored in the local block storage for local
1042 queries. Locally stored blocks from previously observed
1043 <tt>ResultMessages</tt> and <tt>PutMessages</tt> MAY use this
1044 function instead of <tt>ValidateBlockReply</tt> in order to
1045 avoid revalidation of the block and only perform filtering based on
1046 request parameters.
1047 </dd>
1048 </dl>
1049 </section>
1050 <section>
1051 <name>Block Types</name>
1052 <t>
1053 Applications can and should define their own block types.
1054 The block type determines the format and handling of the block
1055 payload by peers in PUT and RESULT messages.
1056 Block types MUST be registered with GANA <xref target="gana"/>.
1057 </t>
1058 <t>
1059 For bootstrapping and peer discovery, the DHT implementation uses
1060 its own block type called "HELLO". A block with this block type
1061 contains the peer ID of the peer initiating the GET request.
1062 </t>
1063 <section>
1064 <name>HELLO</name>
1065 <t>
1066 The HELLO block type wire format is illustrated in
1067 <xref target="figure_hellobt"/>. A block of type HELLO MUST NOT
1068 include extended query data (xquery). Any implementation
1069 encountering a HELLO block with xquery data MUST consider the
1070 block invalid and ignore it.
1071 </t>
1072 <t>
1073 A HELLO reply block MAY be empty. Otherwise, it contains the
1074 HELLO URI of a peer.
1075 </t>
1076 <figure anchor="figure_hellobt">
1077 <artwork name="" type="" align="left" alt=""><![CDATA[
1078 FIXME: Wire format
1079 ]]></artwork>
1080 </figure>
1081 </section>
1082 </section>
1083 </section>
1084
1085
1066 <section> 1086 <section>
1067 <name>Bootstrapping</name> 1087 <name>Bootstrapping</name>
1068 <t> 1088 <t>