about summary refs log tree commit diff
diff options
context:
space:
mode:
authorFlorian Klink <flokli@flokli.de>2023-12-12T18·06+0200
committerclbot <clbot@tvl.fyi>2023-12-13T19·57+0000
commit3a32963b7825de784fa8052244156b50820379af (patch)
treeba4d09c1761ddbe7b5d27479844b3c1e331783fb
parentd236b089162780ed1ed3bb1ef80cd4065de142f2 (diff)
docs(tvix/castore): document expectations about DirectoryService r/7215
Namely, all trait implementations should reject invalid data being fed,
and detect invalid data being returned.

b/355 tracks writing some more tests for this, to ensure we're compliant
with this.

Change-Id: I3b05752932837ce208785efb21ffc21508b4b33a
Reviewed-on: https://cl.tvl.fyi/c/depot/+/10338
Tested-by: BuildkiteCI
Reviewed-by: grfn <grfn@gws.fyi>
Autosubmit: flokli <flokli@flokli.de>
-rw-r--r--tvix/castore/src/directoryservice/mod.rs8
1 files changed, 7 insertions, 1 deletions
diff --git a/tvix/castore/src/directoryservice/mod.rs b/tvix/castore/src/directoryservice/mod.rs
index aaa0b1437f43..508c9a0be320 100644
--- a/tvix/castore/src/directoryservice/mod.rs
+++ b/tvix/castore/src/directoryservice/mod.rs
@@ -22,10 +22,12 @@ pub use self::traverse::descend_to;
 #[async_trait]
 pub trait DirectoryService: Send + Sync {
     /// Looks up a single Directory message by its digest.
+    /// The returned Directory message *must* be valid.
     /// In case the directory is not found, Ok(None) is returned.
     async fn get(&self, digest: &B3Digest) -> Result<Option<proto::Directory>, Error>;
     /// Uploads a single Directory message, and returns the calculated
-    /// digest, or an error.
+    /// digest, or an error. An error *must* also be returned if the message is
+    /// not valid.
     async fn put(&self, directory: proto::Directory) -> Result<B3Digest, Error>;
 
     /// Looks up a closure of [proto::Directory].
@@ -37,6 +39,8 @@ pub trait DirectoryService: Send + Sync {
     /// and the box allows different underlying stream implementations to be returned since
     /// Rust doesn't support this as a generic in traits yet. This is the same thing that
     /// [async_trait] generates, but for streams instead of futures.
+    ///
+    /// The individual Directory messages *must* be valid.
     fn get_recursive(
         &self,
         root_directory_digest: &B3Digest,
@@ -66,6 +70,8 @@ pub trait DirectoryPutter: Send {
     async fn put(&mut self, directory: proto::Directory) -> Result<(), Error>;
 
     /// Close the stream, and wait for any errors.
+    /// If there's been any invalid Directory message uploaded, and error *must*
+    /// be returned.
     async fn close(&mut self) -> Result<B3Digest, Error>;
 
     /// Return whether the stream is closed or not.