Clarify `WriteRequest.write_offset` spec for compressed blobs (#193)

* Fix incorrect protobuf spec

The CAS compression spec currently states that WriteRequest.write_offset
is the offset in the uncompressed blob, but it does not match Google's
implementation on the client or server side.

The original intention was to encode each chunk, but having the entire
stream compressed seems better also because it allows the
reading-from-data-source-eg-disk and writing-to-CAS to happen
concurrently.

* clarify

* Clarify that WriteRequest.write_offset refers to uncompressed blob
only in the first request.

* Clarify further

* The previous

* Ack nonsensical semantics

* nit

* nit

* Remove a promise

1 files changed, 8 insertions, 2 deletions

diff --git a/build/bazel/remote/execution/v2/remote_execution.proto b/build/bazel/remote/execution/v2/remote_execution.proto
index ad5b17e..235a9f3 100644
--- a/build/bazel/remote/execution/v2/remote_execution.proto
+++ b/build/bazel/remote/execution/v2/remote_execution.proto
@@ -238,8 +238,14 @@ service ActionCache {
 //   the uploaded data once uncompressed, and MUST return an
 //   `INVALID_ARGUMENT` error in the case of mismatch.
 //
-// Note that when writing compressed blobs, the `WriteRequest.write_offset`
-// refers to the offset in the uncompressed form of the blob.
+// Note that when writing compressed blobs, the `WriteRequest.write_offset` in
+// the initial request in a stream refers to the offset in the uncompressed form
+// of the blob. In subsequent requests, `WriteRequest.write_offset` MUST be the
+// sum of the first request's 'WriteRequest.write_offset' and the total size of
+// all the compressed data bundles in the previous requests.
+// Note that this mixes an uncompressed offset with a compressed byte length,
+// which is nonsensical, but it is done to fit the semantics of the existing
+// ByteStream protocol.
 //
 // Uploads of the same data MAY occur concurrently in any form, compressed or
 // uncompressed.