docs(tvix/castore/blobsvc): fix doc comments on trait r/7468

The readers implement AsyncRead/AsyncSeek, not their sync counterparts.
Also update expectations around chunks.

Change-Id: Ic266688039d80d16d33f651b96ce2bcdedecfa00
Reviewed-on: https://cl.tvl.fyi/c/depot/+/10734
Autosubmit: flokli <flokli@flokli.de>
Tested-by: BuildkiteCI
Reviewed-by: Connor Brewster <cbrewster@hey.com>

1 files changed, 14 insertions, 10 deletions

diff --git a/tvix/castore/src/blobservice/mod.rs b/tvix/castore/src/blobservice/mod.rs
index 348f87fb962e..fa6b87926ba1 100644
--- a/tvix/castore/src/blobservice/mod.rs
+++ b/tvix/castore/src/blobservice/mod.rs
@@ -24,19 +24,22 @@ pub use self::sled::SledBlobService;
 
 /// The base trait all BlobService services need to implement.
 /// It provides functions to check whether a given blob exists,
-/// a way to get a [io::Read] to a blob, and a method to initiate writing a new
-/// Blob, which will return something implmenting io::Write, and providing a
-/// close funtion, to finalize a blob and get its digest.
+/// a way to read (and seek) a blob, and a method to create a blobwriter handle,
+/// which will implement a writer interface, and also provides a close funtion,
+/// to finalize a blob and get its digest.
 #[async_trait]
 pub trait BlobService: Send + Sync {
     /// Check if the service has the blob, by its content hash.
+    /// On implementations returning chunks, this must also work for chunks.
     async fn has(&self, digest: &B3Digest) -> io::Result<bool>;
 
     /// Request a blob from the store, by its content hash.
+    /// On implementations returning chunks, this must also work for chunks.
     async fn open_read(&self, digest: &B3Digest) -> io::Result<Option<Box<dyn BlobReader>>>;
 
     /// Insert a new blob into the store. Returns a [BlobWriter], which
-    /// implements [io::Write] and a [BlobWriter::close].
+    /// implements [tokio::io::AsyncWrite] and a [BlobWriter::close] to finalize
+    /// the blob and get its digest.
     async fn open_write(&self) -> Box<dyn BlobWriter>;
 
     /// Return a list of chunks for a given blob.
@@ -44,20 +47,21 @@ pub trait BlobService: Send + Sync {
     /// The former return value is sent in case the blob is not present at all,
     /// while the second one is sent in case there's no more granular chunks (or
     /// the backend does not support chunking).
-    /// A default implementation signalling the backend does not support
-    /// chunking is provided.
+    /// A default implementation checking for existence and then returning it
+    /// does not have more granular chunks available is provided.
     async fn chunks(&self, digest: &B3Digest) -> io::Result<Option<Vec<ChunkMeta>>> {
         if !self.has(digest).await? {
             return Ok(None);
         } else {
-            // default implementation, signalling the backend does not support chunking.
+            // default implementation, signalling the backend does not have more
+            // granular chunks available.
             return Ok(Some(vec![]));
         }
     }
 }
 
-/// A [tokio::io::AsyncWrite] that you need to close() afterwards, and get back
-/// the digest of the written blob.
+/// A [tokio::io::AsyncWrite] that the user needs to close() afterwards for persist.
+/// On success, it returns the digest of the written blob.
 #[async_trait]
 pub trait BlobWriter: tokio::io::AsyncWrite + Send + Sync + Unpin + 'static {
     /// Signal there's no more data to be written, and return the digest of the
@@ -67,7 +71,7 @@ pub trait BlobWriter: tokio::io::AsyncWrite + Send + Sync + Unpin + 'static {
     async fn close(&mut self) -> io::Result<B3Digest>;
 }
 
-/// A [tokio::io::AsyncRead] that also allows seeking.
+/// BlobReader is a [tokio::io::AsyncRead] that also allows seeking.
 pub trait BlobReader: tokio::io::AsyncRead + tokio::io::AsyncSeek + Send + Unpin + 'static {}
 
 /// A [`io::Cursor<Vec<u8>>`] can be used as a BlobReader.