1// Copyright 2016 Google Inc. 2// 3// Licensed under the Apache License, Version 2.0 (the "License"); 4// you may not use this file except in compliance with the License. 5// You may obtain a copy of the License at 6// 7// http://www.apache.org/licenses/LICENSE-2.0 8// 9// Unless required by applicable law or agreed to in writing, software 10// distributed under the License is distributed on an "AS IS" BASIS, 11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12// See the License for the specific language governing permissions and 13// limitations under the License. 14 15syntax = "proto3"; 16 17package google.bytestream; 18 19option go_package = "google.golang.org/genproto/googleapis/bytestream;bytestream"; 20option java_outer_classname = "ByteStreamProto"; 21option java_package = "com.google.bytestream"; 22 23// #### Introduction 24// 25// The Byte Stream API enables a client to read and write a stream of bytes to 26// and from a resource. Resources have names, and these names are supplied in 27// the API calls below to identify the resource that is being read from or 28// written to. 29// 30// All implementations of the Byte Stream API export the interface defined here: 31// 32// * `Read()`: Reads the contents of a resource. 33// 34// * `Write()`: Writes the contents of a resource. The client can call `Write()` 35// multiple times with the same resource and can check the status of the write 36// by calling `QueryWriteStatus()`. 37// 38// #### Service parameters and metadata 39// 40// The ByteStream API provides no direct way to access/modify any metadata 41// associated with the resource. 42// 43// #### Errors 44// 45// The errors returned by the service are in the Google canonical error space. 46service ByteStream { 47 // `Read()` is used to retrieve the contents of a resource as a sequence 48 // of bytes. The bytes are returned in a sequence of responses, and the 49 // responses are delivered as the results of a server-side streaming RPC. 50 rpc Read(ReadRequest) returns (stream ReadResponse); 51 52 // `Write()` is used to send the contents of a resource as a sequence of 53 // bytes. The bytes are sent in a sequence of request protos of a client-side 54 // streaming RPC. 55 // 56 // A `Write()` action is resumable. If there is an error or the connection is 57 // broken during the `Write()`, the client should check the status of the 58 // `Write()` by calling `QueryWriteStatus()` and continue writing from the 59 // returned `committed_size`. This may be less than the amount of data the 60 // client previously sent. 61 // 62 // Calling `Write()` on a resource name that was previously written and 63 // finalized could cause an error, depending on whether the underlying service 64 // allows over-writing of previously written resources. 65 // 66 // When the client closes the request channel, the service will respond with 67 // a `WriteResponse`. The service will not view the resource as `complete` 68 // until the client has sent a `WriteRequest` with `finish_write` set to 69 // `true`. Sending any requests on a stream after sending a request with 70 // `finish_write` set to `true` will cause an error. The client **should** 71 // check the `WriteResponse` it receives to determine how much data the 72 // service was able to commit and whether the service views the resource as 73 // `complete` or not. 74 rpc Write(stream WriteRequest) returns (WriteResponse); 75 76 // `QueryWriteStatus()` is used to find the `committed_size` for a resource 77 // that is being written, which can then be used as the `write_offset` for 78 // the next `Write()` call. 79 // 80 // If the resource does not exist (i.e., the resource has been deleted, or the 81 // first `Write()` has not yet reached the service), this method returns the 82 // error `NOT_FOUND`. 83 // 84 // The client **may** call `QueryWriteStatus()` at any time to determine how 85 // much data has been processed for this resource. This is useful if the 86 // client is buffering data and needs to know which data can be safely 87 // evicted. For any sequence of `QueryWriteStatus()` calls for a given 88 // resource name, the sequence of returned `committed_size` values will be 89 // non-decreasing. 90 rpc QueryWriteStatus(QueryWriteStatusRequest) 91 returns (QueryWriteStatusResponse); 92} 93 94// Request object for ByteStream.Read. 95message ReadRequest { 96 // The name of the resource to read. 97 string resource_name = 1; 98 99 // The offset for the first byte to return in the read, relative to the start 100 // of the resource. 101 // 102 // A `read_offset` that is negative or greater than the size of the resource 103 // will cause an `OUT_OF_RANGE` error. 104 int64 read_offset = 2; 105 106 // The maximum number of `data` bytes the server is allowed to return in the 107 // sum of all `ReadResponse` messages. A `read_limit` of zero indicates that 108 // there is no limit, and a negative `read_limit` will cause an error. 109 // 110 // If the stream returns fewer bytes than allowed by the `read_limit` and no 111 // error occurred, the stream includes all data from the `read_offset` to the 112 // end of the resource. 113 int64 read_limit = 3; 114} 115 116// Response object for ByteStream.Read. 117message ReadResponse { 118 // A portion of the data for the resource. The service **may** leave `data` 119 // empty for any given `ReadResponse`. This enables the service to inform the 120 // client that the request is still live while it is running an operation to 121 // generate more data. 122 bytes data = 10; 123} 124 125// Request object for ByteStream.Write. 126message WriteRequest { 127 // The name of the resource to write. This **must** be set on the first 128 // `WriteRequest` of each `Write()` action. If it is set on subsequent calls, 129 // it **must** match the value of the first request. 130 string resource_name = 1; 131 132 // The offset from the beginning of the resource at which the data should be 133 // written. It is required on all `WriteRequest`s. 134 // 135 // In the first `WriteRequest` of a `Write()` action, it indicates 136 // the initial offset for the `Write()` call. The value **must** be equal to 137 // the `committed_size` that a call to `QueryWriteStatus()` would return. 138 // 139 // On subsequent calls, this value **must** be set and **must** be equal to 140 // the sum of the first `write_offset` and the sizes of all `data` bundles 141 // sent previously on this stream. 142 // 143 // An incorrect value will cause an error. 144 int64 write_offset = 2; 145 146 // If `true`, this indicates that the write is complete. Sending any 147 // `WriteRequest`s subsequent to one in which `finish_write` is `true` will 148 // cause an error. 149 bool finish_write = 3; 150 151 // A portion of the data for the resource. The client **may** leave `data` 152 // empty for any given `WriteRequest`. This enables the client to inform the 153 // service that the request is still live while it is running an operation to 154 // generate more data. 155 bytes data = 10; 156} 157 158// Response object for ByteStream.Write. 159message WriteResponse { 160 // The number of bytes that have been processed for the given resource. 161 int64 committed_size = 1; 162} 163 164// Request object for ByteStream.QueryWriteStatus. 165message QueryWriteStatusRequest { 166 // The name of the resource whose write status is being requested. 167 string resource_name = 1; 168} 169 170// Response object for ByteStream.QueryWriteStatus. 171message QueryWriteStatusResponse { 172 // The number of bytes that have been processed for the given resource. 173 int64 committed_size = 1; 174 175 // `complete` is `true` only if the client has sent a `WriteRequest` with 176 // `finish_write` set to true, and the server has processed that request. 177 bool complete = 2; 178} 179