protocol/spec.tex: Clarify generic datastore vs. content-addressable …

…blockstore

Copy the AllKeys() method from the blockstore [1] to the datastore
[2].  You can't implement it efficiently using the existing datastore
interface, so I don't know how you'd add it on top of a generic
datastore that lacked such a method.  We don't want to encourage
drilling down through layers and using what should be internal
implementation details.

The previous paragraph explained why we need an AllKeys() method in
the datastore.  We also need to expose AllKeys() in the blockstore
interface, so we can build garbage collection and similar logic on top
of the blockstore, without having to drill down to the datastore layer
to write those tools (see, for example, the IRC discussion from [3]
through [4]).

Also remove the Key argument from the blockstore's Put().  The backing
datastore need not be content-addressable, but I think we want to
require content-addressability for the block store.  However,
multihash gives us some choices for the hash function and digest size,
so the blockstore's Put does accept those (and then it computes the
hash internally).

Besides requiring content-addressability, I'd also require the
blockstore to only store serialized Merkle objects.  That makes
deserializing the content easier, and we've worked hard to make Merkle
objects sufficiently general that they should suffice for any data we
want to put into the blockstore.

I've also tried to clarify that the exchange-server doesn't have the
potentially expensive AllKeys() method by explicitly listing the
methods it does have.  We probably also want to extend the Get(Key)
response with optional "will send" and cancel information.  See the
optimistic transmission graphic in [5] for more on this.

[1]: https://gist.github.com/jbenet/d1fedddfef85f0c4efd5#file-modules-go-L162
[2]: https://gist.github.com/jbenet/d1fedddfef85f0c4efd5#file-modules-go-L122
[3]: https://botbot.me/freenode/ipfs/2015-06-23/?msg=42683298&page=4
[4]: https://botbot.me/freenode/ipfs/2015-06-23/?msg=42688156&page=4
[5]: ipfs#7 (comment)

License: MIT
Signed-off-by: W. Trevor King <[email protected]>

protocol/stack.tex

@@ -174,23 +174,33 @@
   };
   \draw[process,->] (block) -- (multihash);
 
-  \node[interface] (datastore) [right=of multihash] {
-    \href{https://gist.github.com/jbenet/d1fedddfef85f0c4efd5}{Datastore} \\
-    \method{Put}{\target{Key}{datastore-key}, \target{Value}{datastore-value}}{} \\
-    \method{Get}{Key}{Value} \\
+  \node[interface] (blockstore) [right=of multihash] {
+    \href{https://gist.github.com/jbenet/d1fedddfef85f0c4efd5}{Blockstore} \\
+    \method{Put}{\target{Value}{blockstore-value}, Hash, DigestSize}{} \\
+    \method{Get}{\target{Key}{blockstore-key}}{Value} \\
     \method{Has}{Key}{bool} \\
-    \method{Delete}{Key}{}
+    \method{Delete}{Key}{} \\
+    \method{AllKeys}{}{KeyIterator}
   };
-  \draw[use,bend right] (multihash) to (datastore-key);
-  \draw[use,bend right] (block) to (datastore-value);
+  \draw[use,bend right] (multihash) to (blockstore-key);
+  \draw[use,bend right] (block) to (blockstore-value);
 
-  \node[interface] (blockstore) [above=of datastore] {
-    \href{https://gist.github.com/jbenet/d1fedddfef85f0c4efd5}{Blockstore} \\
+  \node[interface] (datastore) [below=of blockstore] {
+    \href{https://gist.github.com/jbenet/d1fedddfef85f0c4efd5}{Datastore} \\
+    \method{Put}{Key, Value}{} \\
+    \method{Get}{Key}{Value} \\
+    \method{Has}{Key}{bool} \\
+    \method{Delete}{Key}{} \\
     \method{AllKeys}{}{KeyIterator}
   };
   \draw[extend] (datastore) -- (blockstore);
 
-  \node[interface] (notifier) [right=0.3 of datastore] {
+  \node[actor] (garbage-collector) [above left=0.3 of blockstore] {
+    \href{GC spec?  Example?}{Garbage collector}
+  };
+  \draw[use] (blockstore) -- (garbage-collector);
+
+  \node[interface] (notifier) [right=0.3 of blockstore] {
     \href{https://gist.github.com/jbenet/d1fedddfef85f0c4efd5}{Notifier} \\
     \method{Notifiees}{}{NotifieeIterator} \\
     \method{AddNotifiee}{Notifiee}{} \\
@@ -199,6 +209,10 @@
 
   \node[actor] (exchange-server) [above=of blockstore] {
     \href{https://gist.github.com/jbenet/d1fedddfef85f0c4efd5}{Exchange server} \\
+    \method{Put}{Value, Hash, DigestSize}{} \\
+    \method{Get}{Key}{Value} \\
+    \method{Has}{Key}{bool} \\
+    \method{Delete}{Key}{} \\
     \event{BlockPut} \\
     \event{NewBlockPut} \\
     \event{BlockDeleted}