clean up

Clarified the requirements for chunked uploads in the RPC documentation.

Author: tyler-french

build/bazel/remote/execution/v2/remote_execution.proto

@@ -440,7 +440,7 @@ service ContentAddressableStorage {
     option (google.api.http) = { get: "/v2/{instance_name=**}/blobs/{root_digest.hash}/{root_digest.size_bytes}:getTree" };
   }
 
-  // Split retrieves information about how a blob is split into chunks.
+  // SplitBlob retrieves information about how a blob is split into chunks.
   //
   // This call returns information about how a blob is split into chunks, and
   // returns a list of the chunk digests. Using the returned list of chunk digests,
@@ -450,10 +450,9 @@ service ContentAddressableStorage {
   // available in the CAS.
   //
   // This API can be used to reduce the required data to download a large blob
-  // from CAS if chunks from earlier downloads of a different version of this
-  // blob are locally available. For this procedure to work properly, blobs
-  // SHOULD be split in a content-defined way, rather than with fixed-sized
-  // chunking.
+  // from CAS if some chunks from similar blobs are locally available. For this 
+  // procedure to work properly, blobs should be split in a content-defined way, 
+  // rather than with fixed-sized chunking.
   //
   // If a split request is answered successfully, a client can expect the
   // following guarantees from the server:
@@ -501,20 +500,17 @@ service ContentAddressableStorage {
     option (google.api.http) = { get: "/v2/{instance_name=**}/blobs/{blob_digest.hash}/{blob_digest.size_bytes}:splitBlob" };
   }
 
-  // Splice tells the CAS how chunks can compose a blob.
+  // SpliceBlob tells the CAS how chunks can compose a blob.
   //
   // This is the complementary operation to the
   // [ContentAddressableStorage.SplitBlob][build.bazel.remote.execution.v2.ContentAddressableStorage.SplitBlob]
   // function to handle the chunked upload of large blobs to save upload
   // traffic.
   //
   // When uploading a large blob using chunked upload, clients MUST first upload
-  // all chunks to the CAS, then call this RPC to store how those chunks compose
-  // the original blob. The chunks referenced in the manifest SHOULD be available
-  // in the CAS before calling this RPC. The original blob does not need to be
-  // available: the correctness of the manifest can be validated from manifest
-  // correctness and by verifying that the chunks assembled match the original
-  // digest.
+  // all chunks to the CAS, then call this RPC to tell the server how those chunks 
+  // compose the original blob. The chunks referenced in SpliceBlob call SHOULD be 
+  // available in the CAS before calling this RPC.
   //
   // If a client needs to upload a large blob and is able to split a blob into
   // chunks in such a way that reusable chunks are obtained, e.g., by means of
@@ -538,17 +534,14 @@ service ContentAddressableStorage {
   // construct the blob from chunks is available. In such cases, the lifetime of
   // that blob or the chunks SHOULD be extended as usual. If the client-specified
   // blob is not already in the CAS, the server SHOULD verify that the digest of
-  // the newly created blob matches the digest specified by the client, and reject
-  // the request if they differ.
+  // the newly created blob assembled from chunks matches the digest specified by 
+  // the client, and reject the request if they differ.
   //
   // When blob splitting and splicing is used at the same time, the clients and
   // the server SHOULD agree out-of-band upon a chunking algorithm used by both
   // parties to benefit from each others chunk data and avoid unnecessary data
   // duplication.
   //
-  // After a successful SpliceBlob call, a subsequent SplitBlob call for the same
-  // blob digest SHOULD retrieve the same list of chunk digests.
-  //
   // Errors:
   //
   // * `NOT_FOUND`: At least one of the blob chunks is not present in the CAS.
@@ -2020,6 +2013,8 @@ message SpliceBlobRequest {
   //  2. It allows servers with different storage backends to dispatch the
   //     request to the correct storage backend based on the size and/or the
   //     hash of the blob.
+  //  3. It allows the server to check if existing chunking information is 
+  //     available for the blob.
   Digest blob_digest = 2;
 
   // The ordered list of digests of the chunks which need to be concatenated to