| // Copyright 2020 The Bazel Authors. |
| // |
| // 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. |
| |
| // Log Stream API |
| |
| syntax = "proto3"; |
| |
| package build.bazel.remote.logstream.v1; |
| |
| option csharp_namespace = "Build.Bazel.Remote.LogStream.v1"; |
| option go_package = "github.com/bazelbuild/remote-apis/build/bazel/remote/logstream/v1;remotelogstream"; |
| option java_multiple_files = true; |
| option java_outer_classname = "RemoteLogStreamProto"; |
| option java_package = "build.bazel.remote.logstream.v1"; |
| option objc_class_prefix = "RL"; |
| |
| |
| // #### Introduction |
| // |
| // The Log Stream API manages LogStream resources which are used to stream |
| // writes and reads of an ordered sequence of bytes of unknown eventual length. |
| // |
| // Note that this is an API Interface and not an API Service, per the definitions |
| // at: https://cloud.google.com/apis/design/glossary |
| // |
| // Log Stream API supports the reading of unfinalized LogStreams either by |
| // seeking or in "tail" mode, for example by end-users browsing to a build |
| // result UI interested in seeing logs from a build action as soon as they are |
| // (or as they become) available. |
| // |
| // Reads and Writes of LogStreams are done via the Byte Stream API: |
| // https://cloud.google.com/dataproc/docs/reference/rpc/google.bytestream |
| // https://github.com/googleapis/googleapis/blob/master/google/bytestream/bytestream.proto |
| // |
| // #### Writing LogStreams |
| // |
| // LogStreams are written to via the Byte Stream API's `Write` RPC. Bytes |
| // written to LogStreams are expected to be committed and available for reading |
| // within a reasonable period of time (implementation-defined). Committed bytes |
| // to a LogStream cannot be overwritten, and finalized LogStreams - indicated by |
| // setting `finish_write` field in the final WriteRequest - also cannot be |
| // appended to. |
| // |
| // When calling the Byte Stream API's `Write` RPC to write LogStreams, writers |
| // must pass the `write_resource_name` of a LogStream as |
| // `ByteStream.WriteRequest.resource_name` rather than the LogStream's `name`. |
| // Separate resource names for reading and writing allows for broadcasting the |
| // read resource name widely while simultaneously ensuring that only writer(s) |
| // with knowledge of the write resource name may have written bytes to the |
| // LogStream. |
| // |
| // #### Reading LogStreams |
| // |
| // Use the Byte Stream API's `Read` RPC to read LogStreams. When reading |
| // finalized LogStreams the server will stream all contents of the LogStream |
| // starting at `ByteStream.ReadRequest.read_offset`. |
| // |
| // When reading unfinalized LogStreams the server must keep the streaming |
| // `ByteStream.Read` RPC open and send `ByteStream.ReadResponse` messages as |
| // more bytes become available or the LogStream is finalized. |
| // |
| // #### Example Multi-Party Read/Write Flow |
| // |
| // 1. LogStream Writer calls `CreateLogStream` |
| // 2. LogStream Writer publishes `LogStream.name` |
| // 3. LogStream Writer calls `ByteStream.Write` with |
| // `LogStream.write_resource_name` as |
| // `ByteStream.WriteRequest.resource_name`, |
| // `ByteStream.WriteRequest.finish_write`=false. |
| // 4. LogStream Reader(s) call `ByteStream.Read` with the published |
| // `LogStream.name` as `ByteStream.ReadRequest.resource_name`. |
| // 5. LogStream Service streams all committed bytes to LogStream Reader(s), |
| // leave the stream open. |
| // 6. LogStream Writer calls `ByteStream.Write` with |
| // `LogStream.write_resource_name` as |
| // `ByteStream.WriteRequest.resource_name`, |
| // `ByteStream.WriteRequest.finish_write`=true. |
| // 7. LogStream Service streams all remaining bytes to LogStream Reader(s), |
| // terminates the stream. |
| service LogStreamService { |
| // Create a LogStream which may be written to. |
| // |
| // The returned LogStream resource name will include a `write_resource_name` |
| // which is the resource to use when writing to the LogStream. |
| // Callers of CreateLogStream are expected to NOT publish the |
| // `write_resource_name`. |
| rpc CreateLogStream(CreateLogStreamRequest) returns (LogStream) {} |
| } |
| |
| // Contains all information necessary to create a new LogStream resource. |
| message CreateLogStreamRequest { |
| // Required. The parent resource of the created LogStream. |
| // The list of valid types of parent resources of LogStreams is up to the |
| // implementing server. |
| // Example: projects/123 |
| string parent = 1; |
| } |
| |
| // A handle to a log (an ordered sequence of bytes). |
| message LogStream { |
| // Structured name of the resource in the format: |
| // {parent=**}/logstreams/{logstream_id} |
| // Example: projects/123/logstreams/456-def |
| // Attempting to call the Byte Stream API's `Write` RPC with a LogStream's |
| // `name` as the value for `ByteStream.Write.resource_name` is an error. |
| string name = 1; |
| |
| // Resource name to pass to `ByteStream.Write` in the format: |
| // {parent=**}/logstreams/{logstream_id}/{write_token} |
| // Example: projects/123/logstreams/456-def/789-ghi |
| // Attempting to call the Byte Stream API's `Read` RPC with a LogStream's |
| // `write_resource_name` as the value for `ByteStream.Write.resource_name` |
| // is an error. |
| // |
| // `write_resource_name` is separate from `name` to ensure that only the |
| // intended writers can write to a given LogStream. Writers must address write |
| // operations to the `write_resource_name`, not the `name`, and must have |
| // permission to write LogStreams. `write_resource_name` embeds a secret token |
| // and should be protected accordingly; a mishandled `write_resource_name` can |
| // result in unintended writers corrupting the LogStream. Therefore, the field |
| // should be excluded from calls to any calls which retrieve LogStream |
| // metadata (i.e.: `GetLogStream`). |
| // |
| // Bytes written to this resource must to be readable when `ByteStream.Read` |
| // is called with the `name` resource. |
| // Reading a write_resource_name must return an INVALID_ARGUMENT error. |
| string write_resource_name = 2; |
| } |