1 files changed, 19 insertions, 3 deletions
diff --git a/tvix/store/protos/rpc_blobstore.proto b/tvix/store/protos/rpc_blobstore.proto
index e0b700f2d0da..c0665e821ae5 100644
--- a/tvix/store/protos/rpc_blobstore.proto
+++ b/tvix/store/protos/rpc_blobstore.proto
@@ -15,11 +15,27 @@ service BlobService {
     // contain a single chunk.
     rpc Stat(StatBlobRequest) returns (BlobMeta);
 
-    // Read returns a stream of BlobChunk, which is just a stream of bytes - not necessarily
-    // using the chunking that's returned in the reply of a Stat() call.
+    // Read returns a stream of BlobChunk, which is just a stream of bytes with
+    // the digest specified in ReadBlobRequest.
+    //
+    // The server may decide on whatever chunking it may seem fit as a size for
+    // the individual BlobChunk sent in the response stream.
+    //
+    // It specifically is NOT necessarily using chunk sizes communicated in a
+    // previous Stat request.
+    //
+    // It's up to the specific store to decide on whether it allows Read on a
+    // Blob at all, or only on smaller chunks communicated in a Stat() call
+    // first.
+    //
+    // Clients are enouraged to Stat() first, and then only read the individual
+    // chunks they don't have yet.
     rpc Read(ReadBlobRequest) returns (stream BlobChunk);
 
     // Put uploads a Blob, by reading a stream of bytes.
+    //
+    // The way the data is chunked up in individual BlobChunk messages sent in
+    // the stream has no effect on how the server ends up chunking blobs up.
     rpc Put(stream BlobChunk) returns (PutBlobResponse);
 }
 
@@ -57,7 +73,7 @@ message BlobMeta {
 }
 
 message ReadBlobRequest {
-    // The blake3 digest of the blob requested
+    // The blake3 digest of the blob or chunk requested
     bytes digest = 1;
 }