From b4715e60d43a7dd6ff5a6da1495023eeab80048b Mon Sep 17 00:00:00 2001
From: "W. Trevor King" <wking@tremily.us>
Date: Tue, 23 Jun 2015 12:57:38 -0700
Subject: [PATCH] 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]: https://github.com/ipfs/specs/pull/7#discussion_r31356057

License: MIT
Signed-off-by: W. Trevor King <wking@tremily.us>
---
 protocol/stack.tex | 34 ++++++++++++++++++++++++----------
 1 file changed, 24 insertions(+), 10 deletions(-)

diff --git a/protocol/stack.tex b/protocol/stack.tex
index 5b232a94e..c8fa9380f 100644
--- a/protocol/stack.tex
+++ b/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}