docs(store/protos): update comment on blobstore Read and Put r/5840

Further emphasize Read() can be used to ask for blobs OR chunks, and
that clients usually want to stat and then request (smaller) chunks,
rather than reading whole blobs.

Also clarify that the chunking used to send BlobChunks over has nothing
to do with the chunk sizes communicated in a Stat() request.

Change-Id: Ia615d190aae570611de2655b11342a14d0b75976
Reviewed-on: https://cl.tvl.fyi/c/depot/+/8028
Reviewed-by: tazjin <tazjin@tvl.su>
Tested-by: BuildkiteCI

3 files changed, 56 insertions, 8 deletions

diff --git a/tvix/store/protos/rpc_blobstore.pb.go b/tvix/store/protos/rpc_blobstore.pb.go
index 426a2836df..853a040130 100644
--- a/tvix/store/protos/rpc_blobstore.pb.go
+++ b/tvix/store/protos/rpc_blobstore.pb.go
@@ -161,7 +161,7 @@ type ReadBlobRequest struct {
 	sizeCache     protoimpl.SizeCache
 	unknownFields protoimpl.UnknownFields
 
-	// The blake3 digest of the blob requested
+	// The blake3 digest of the blob or chunk requested
 	Digest []byte `protobuf:"bytes,1,opt,name=digest,proto3" json:"digest,omitempty"`
 }
 
diff --git a/tvix/store/protos/rpc_blobstore.proto b/tvix/store/protos/rpc_blobstore.proto
index e0b700f2d0..c0665e821a 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;
 }
 
diff --git a/tvix/store/protos/rpc_blobstore_grpc.pb.go b/tvix/store/protos/rpc_blobstore_grpc.pb.go
index f952e78d5a..25b3c0006a 100644
--- a/tvix/store/protos/rpc_blobstore_grpc.pb.go
+++ b/tvix/store/protos/rpc_blobstore_grpc.pb.go
@@ -29,10 +29,26 @@ type BlobServiceClient interface {
 	// If there's no more granular chunking available, the response will simply
 	// contain a single chunk.
 	Stat(ctx context.Context, in *StatBlobRequest, opts ...grpc.CallOption) (*BlobMeta, error)
-	// 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.
 	Read(ctx context.Context, in *ReadBlobRequest, opts ...grpc.CallOption) (BlobService_ReadClient, error)
 	// 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.
 	Put(ctx context.Context, opts ...grpc.CallOption) (BlobService_PutClient, error)
 }
 
@@ -130,10 +146,26 @@ type BlobServiceServer interface {
 	// If there's no more granular chunking available, the response will simply
 	// contain a single chunk.
 	Stat(context.Context, *StatBlobRequest) (*BlobMeta, error)
-	// 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.
 	Read(*ReadBlobRequest, BlobService_ReadServer) error
 	// 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.
 	Put(BlobService_PutServer) error
 	mustEmbedUnimplementedBlobServiceServer()
 }