adapt abstract store interface

Author: jstriebel

docs/protocol/core/v3.0.rst

@@ -1191,6 +1191,22 @@ one such pair for any given `key`. I.e., a store is a mapping from
 keys to values. It is also assumed that keys are case sensitive, i.e.,
 the keys "foo" and "FOO" are different.
 
+To read and write partial values, a `range` specifies two integers
+`range_start` and `range_length`, that specify a part of the value
+starting at byte `range_start` (inclusive) and having a length of
+`range_length` bytes. `range_length` may be none, indicating all
+available data until the end of the referenced value. For example
+`range` ``[0, none]`` specifies the full value. Stores that do not
+support partial access can still answer the requests using cutouts
+of full values. It is recommended that the implementation of the
+``get_multi``, ``set_multi`` and ``remove_multi`` methods is made
+optional, providing fallbacks for them by default. However, it is
+recommended to supply those operations where possible for efficiency.
+Also, the ``get``, ``set`` and ``erase`` can easily be mapped onto
+their `multi` counterparts. Therefore, it is also recommended to
+supply fallbacks for those if the `multi` operations can be implemented.
+An entity containing those fallbacks could be named ``MultiStore``.
+
 The store interface also defines some operations involving
 `prefixes`. In the context of this interface, a prefix is a string
 containing only characters that are valid for use in `keys` and ending
@@ -1209,18 +1225,38 @@ A **readable store** supports the following operation:
     | Parameters: `key`
     | Output: `value`
 
+``get_multi`` - Retrieve possibly partial `values` from given `key_ranges`.
+
+    | Parameters: `key_ranges`: ordered set of `key`, `range` pairs,
+    |   a `key` may occur multiple times with different `ranges`
+    | Output: list of `values`, in the order of the `key_ranges`
+
 A **writeable store** supports the following operations:
 
 ``set`` - Store a (`key`, `value`) pair.
 
     | Parameters: `key`, `value`
     | Output: none
 
+``set_multi`` - Store `values` at a given `key`, starting at byte `range_start`.
+
+    | Parameters: `key_start_values`: set of `key`,
+    |   `range_start`, `value` triples, a `key` may occur multiple
+    |   times with different `range_starts`, `range_starts` with
+    |   length of the respective `value` must not specify overlapping
+    |   ranges for the same `key`
+    | Output: none
+
 ``erase`` - Erase the given key/value pair from the store.
 
     | Parameters: `key`
     | Output: none
 
+``erase_multi`` - Erase the given key/value pair from the store.
+
+    | Parameters: `keys`: set of `keys`
+    | Output: none
+
 ``erase_prefix`` - Erase all keys with the given prefix from the store:
 
     | Parameter: `prefix`