From 3a32963b7825de784fa8052244156b50820379af Mon Sep 17 00:00:00 2001 From: Florian Klink Date: Tue, 12 Dec 2023 20:06:52 +0200 Subject: docs(tvix/castore): document expectations about DirectoryService 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 Autosubmit: flokli --- tvix/castore/src/directoryservice/mod.rs | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) (limited to 'tvix/castore') 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, 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; /// 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; /// Return whether the stream is closed or not. -- cgit 1.4.1