Index: client/proto/bytestream.proto |
diff --git a/client/proto/bytestream.proto b/client/proto/bytestream.proto |
new file mode 100644 |
index 0000000000000000000000000000000000000000..ca7365144eae6b23af93e72681acfbcba9ab9082 |
--- /dev/null |
+++ b/client/proto/bytestream.proto |
@@ -0,0 +1,173 @@ |
+// Copyright 2016 Google Inc. |
+// |
+// Licensed under the Apache License, Version 2.0 (the "License"); |
+// you may not use this file except in compliance with the License. |
+// You may obtain a copy of the License at |
+// |
+// http://www.apache.org/licenses/LICENSE-2.0 |
+// |
+// Unless required by applicable law or agreed to in writing, software |
+// distributed under the License is distributed on an "AS IS" BASIS, |
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
+// See the License for the specific language governing permissions and |
+// limitations under the License. |
+ |
+syntax = "proto3"; |
+ |
+package google.bytestream; |
+ |
+// #### Introduction |
+// |
+// The Byte Stream API enables a client to read and write a stream of bytes to |
+// and from a resource. Resources have names, and these names are supplied in |
+// the API calls below to identify the resource that is being read from or |
+// written to. |
+// |
+// All implementations of the Byte Stream API export the interface defined here: |
+// |
+// * `Read()`: Reads the contents of a resource. |
+// |
+// * `Write()`: Writes the contents of a resource. The client can call `Write()` |
+// multiple times with the same resource and can check the status of the write |
+// by calling `QueryWriteStatus()`. |
+// |
+// #### Service parameters and metadata |
+// |
+// The ByteStream API provides no direct way to access/modify any metadata |
+// associated with the resource. |
+// |
+// #### Errors |
+// |
+// The errors returned by the service are in the Google canonical error space. |
+service ByteStream { |
+ // `Read()` is used to retrieve the contents of a resource as a sequence |
+ // of bytes. The bytes are returned in a sequence of responses, and the |
+ // responses are delivered as the results of a server-side streaming RPC. |
+ rpc Read(ReadRequest) returns (stream ReadResponse); |
+ |
+ // `Write()` is used to send the contents of a resource as a sequence of |
+ // bytes. The bytes are sent in a sequence of request protos of a client-side |
+ // streaming RPC. |
+ // |
+ // A `Write()` action is resumable. If there is an error or the connection is |
+ // broken during the `Write()`, the client should check the status of the |
+ // `Write()` by calling `QueryWriteStatus()` and continue writing from the |
+ // returned `committed_size`. This may be less than the amount of data the |
+ // client previously sent. |
+ // |
+ // Calling `Write()` on a resource name that was previously written and |
+ // finalized could cause an error, depending on whether the underlying service |
+ // allows over-writing of previously written resources. |
+ // |
+ // When the client closes the request channel, the service will respond with |
+ // a `WriteResponse`. The service will not view the resource as `complete` |
+ // until the client has sent a `WriteRequest` with `finish_write` set to |
+ // `true`. Sending any requests on a stream after sending a request with |
+ // `finish_write` set to `true` will cause an error. The client **should** |
+ // check the `WriteResponse` it receives to determine how much data the |
+ // service was able to commit and whether the service views the resource as |
+ // `complete` or not. |
+ rpc Write(stream WriteRequest) returns (WriteResponse); |
+ |
+ // `QueryWriteStatus()` is used to find the `committed_size` for a resource |
+ // that is being written, which can then be used as the `write_offset` for |
+ // the next `Write()` call. |
+ // |
+ // If the resource does not exist (i.e., the resource has been deleted, or the |
+ // first `Write()` has not yet reached the service), this method returns the |
+ // error `NOT_FOUND`. |
+ // |
+ // The client **may** call `QueryWriteStatus()` at any time to determine how |
+ // much data has been processed for this resource. This is useful if the |
+ // client is buffering data and needs to know which data can be safely |
+ // evicted. For any sequence of `QueryWriteStatus()` calls for a given |
+ // resource name, the sequence of returned `committed_size` values will be |
+ // non-decreasing. |
+ rpc QueryWriteStatus(QueryWriteStatusRequest) returns (QueryWriteStatusResponse); |
+} |
+ |
+// Request object for ByteStream.Read. |
+message ReadRequest { |
+ // The name of the resource to read. |
+ string resource_name = 1; |
+ |
+ // The offset for the first byte to return in the read, relative to the start |
+ // of the resource. |
+ // |
+ // A `read_offset` that is negative or greater than the size of the resource |
+ // will cause an `OUT_OF_RANGE` error. |
+ int64 read_offset = 2; |
+ |
+ // The maximum number of `data` bytes the server is allowed to return in the |
+ // sum of all `ReadResponse` messages. A `read_limit` of zero indicates that |
+ // there is no limit, and a negative `read_limit` will cause an error. |
+ // |
+ // If the stream returns fewer bytes than allowed by the `read_limit` and no |
+ // error occurred, the stream includes all data from the `read_offset` to the |
+ // end of the resource. |
+ int64 read_limit = 3; |
+} |
+ |
+// Response object for ByteStream.Read. |
+message ReadResponse { |
+ // A portion of the data for the resource. The service **may** leave `data` |
+ // empty for any given `ReadResponse`. This enables the service to inform the |
+ // client that the request is still live while it is running an operation to |
+ // generate more data. |
+ bytes data = 10; |
+} |
+ |
+// Request object for ByteStream.Write. |
+message WriteRequest { |
+ // The name of the resource to write. This **must** be set on the first |
+ // `WriteRequest` of each `Write()` action. If it is set on subsequent calls, |
+ // it **must** match the value of the first request. |
+ string resource_name = 1; |
+ |
+ // The offset from the beginning of the resource at which the data should be |
+ // written. It is required on all `WriteRequest`s. |
+ // |
+ // In the first `WriteRequest` of a `Write()` action, it indicates |
+ // the initial offset for the `Write()` call. The value **must** be equal to |
+ // the `committed_size` that a call to `QueryWriteStatus()` would return. |
+ // |
+ // On subsequent calls, this value **must** be set and **must** be equal to |
+ // the sum of the first `write_offset` and the sizes of all `data` bundles |
+ // sent previously on this stream. |
+ // |
+ // An incorrect value will cause an error. |
+ int64 write_offset = 2; |
+ |
+ // If `true`, this indicates that the write is complete. Sending any |
+ // `WriteRequest`s subsequent to one in which `finish_write` is `true` will |
+ // cause an error. |
+ bool finish_write = 3; |
+ |
+ // A portion of the data for the resource. The client **may** leave `data` |
+ // empty for any given `WriteRequest`. This enables the client to inform the |
+ // service that the request is still live while it is running an operation to |
+ // generate more data. |
+ bytes data = 10; |
+} |
+ |
+// Response object for ByteStream.Write. |
+message WriteResponse { |
+ // The number of bytes that have been processed for the given resource. |
+ int64 committed_size = 1; |
+} |
+ |
+// Request object for ByteStream.QueryWriteStatus. |
+message QueryWriteStatusRequest { |
+ // The name of the resource whose write status is being requested. |
+ string resource_name = 1; |
+} |
+ |
+// Response object for ByteStream.QueryWriteStatus. |
+message QueryWriteStatusResponse { |
+ // The number of bytes that have been processed for the given resource. |
+ int64 committed_size = 1; |
+ |
+ // `complete` is `true` only if the client has sent a `WriteRequest` with |
+ // `finish_write` set to true, and the server has processed that request. |
+ bool complete = 2; |
+} |