docs(tvix/castore/directorysvc): K/V is not necessarily flat r/7570

Some implementations of DirectoryService might not allow retrieval of
intermediate Directory nodes, that are not at the "root".

Think about an object store implementation. The client is doing a
get_recursive anyways to reduce the number of roundtrips.

By documenting the fact we don't need to support looking up intermediate
Directory messages, we can just batch all directories into the same
object, keyed by the root.

Change-Id: I019d720186d03c4125cec9191e93d20586a20963
Reviewed-on: https://cl.tvl.fyi/c/depot/+/10988
Autosubmit: flokli <flokli@flokli.de>
Reviewed-by: tazjin <tazjin@tvl.su>
Tested-by: BuildkiteCI

1 files changed, 5 insertions, 0 deletions

diff --git a/tvix/castore/protos/rpc_directory.proto b/tvix/castore/protos/rpc_directory.proto
index 7fccb6c75e34..f4f41c433a76 100644
--- a/tvix/castore/protos/rpc_directory.proto
+++ b/tvix/castore/protos/rpc_directory.proto
@@ -14,6 +14,11 @@ service DirectoryService {
   // Keep in mind multiple DirectoryNodes in different parts of the graph might
   // have the same digest if they have the same underlying contents,
   // so sending subsequent ones can be omitted.
+  //
+  // It is okay for certain implementations to only allow retrieval of
+  // Directory digests that are at the "root", aka the last element that's
+  // sent in a Put. This makes sense for implementations bundling closures of
+  // directories together in batches.
   rpc Get(GetDirectoryRequest) returns (stream Directory);
 
   // Put uploads a graph of Directory messages.