From a2f0dd8c403f7caad5658c40ab58ffbe35944fe5 Mon Sep 17 00:00:00 2001 From: Google APIs Date: Tue, 25 Apr 2017 14:01:52 -0700 Subject: [PATCH] Synchronize new proto changes. --- google/devtools/build/v1/build_events.proto | 202 ++++++++++++++++++ google/devtools/build/v1/build_status.proto | 63 ++++++ .../build/v1/publish_build_event.proto | 136 ++++++++++++ 3 files changed, 401 insertions(+) create mode 100644 google/devtools/build/v1/build_events.proto create mode 100644 google/devtools/build/v1/build_status.proto create mode 100644 google/devtools/build/v1/publish_build_event.proto diff --git a/google/devtools/build/v1/build_events.proto b/google/devtools/build/v1/build_events.proto new file mode 100644 index 00000000..e745aee8 --- /dev/null +++ b/google/devtools/build/v1/build_events.proto @@ -0,0 +1,202 @@ +// Copyright 2017 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.devtools.build.v1; + +import "google/api/annotations.proto"; +import "google/devtools/build/v1/build_status.proto"; +import "google/protobuf/any.proto"; +import "google/protobuf/timestamp.proto"; +import "google/protobuf/wrappers.proto"; +import "google/rpc/status.proto"; + +option cc_enable_arenas = true; +option go_package = "google.golang.org/genproto/googleapis/devtools/build/v1;build"; +option java_multiple_files = true; +option java_outer_classname = "BuildEventProto"; +option java_package = "com.google.devtools.build.v1"; + + +// An event representing some state change that occured in the build. This +// message does not include field for uniquely identifying an event. +message BuildEvent { + // Notification that the build system has attempted to run the build tool. + message InvocationAttemptStarted { + // The number of the invocation attempt, starting at 1 and increasing by 1 + // for each new attempt. Can be used to determine if there is a later + // invocation attempt replacing the current one a client is processing. + int64 attempt_number = 1; + } + + // Notification that an invocation attempt has finished. + message InvocationAttemptFinished { + // The status of the build request. + // If OK, the build request was run, though this does not mean the + // requested build tool succeeded. "exit_code" will be set to the + // exit code of the build tool. + // If not OK, the build request was not successfully executed. + // "exit_code" will not be set. + google.rpc.Status status = 1; + + // The exit code of the build tool. + google.protobuf.Int32Value exit_code = 2; + + // Final status of the invocation. + BuildStatus invocation_status = 3; + } + + // Notification that the build request is enqueued. It could happen when + // a new build request is inserted into the build queue, or when a + // build request is put back into the build queue due to a previous build + // failure. + message BuildEnqueued { + + } + + // Notification that the build request has finished, and no further + // invocations will occur. Note that this applies to the entire Build. + // Individual invocations trigger InvocationFinished when they finish. + message BuildFinished { + // Final status of the build. + BuildStatus status = 1; + } + + // Textual output written to standard output or standard error. + message ConsoleOutput { + // The output stream type. + ConsoleOutputStream type = 1; + + // The output stream content. + oneof output { + // Regular UTF-8 output; normal text. + string text_output = 2; + + // Used if the output is not UTF-8 text (for example, a binary proto). + bytes binary_output = 3; + } + } + + // Notification of the end of a build event stream published by a build + // component other than CONTROLLER (See StreamId.BuildComponents). + message BuildComponentStreamFinished { + // How did the event stream finish. + enum FinishType { + // Unknown or unspecified; callers should never set this value. + FINISH_TYPE_UNSPECIFIED = 0; + + // Set by the event publisher to indicate a build event stream is + // finished. + FINISHED = 1; + + // Set by the WatchBuild RPC server when the publisher of a build event + // stream stops publishing events without publishing a + // BuildComponentStreamFinished event whose type equals FINISHED. + EXPIRED = 2; + } + + // How the event stream finished. + FinishType type = 1; + } + + // The timestamp of this event. + google.protobuf.Timestamp event_time = 1; + + // ////////////////////////////////////////////////////////////////////////// + // Events that indicate a state change of a build request in the build + // queue. + oneof event { + // An invocation attempt has started. + InvocationAttemptStarted invocation_attempt_started = 51; + + // An invocation attempt has finished. + InvocationAttemptFinished invocation_attempt_finished = 52; + + // The build is enqueued (just inserted to the build queue or put back + // into the build queue due to a previous build failure). + BuildEnqueued build_enqueued = 53; + + // The build has finished. Set when the build is terminated. + BuildFinished build_finished = 55; + + // An event containing printed text. + ConsoleOutput console_output = 56; + + // Indicates the end of a build event stream (with the same StreamId) from + // a build component executing the requested build task. + // *** This field does not indicate the WatchBuild RPC is finished. *** + BuildComponentStreamFinished component_stream_finished = 59; + + // Structured build event generated by Bazel about its execution progress. + google.protobuf.Any bazel_event = 60; + + // An event that contains supplemental tool-specific information about + // build execution. + google.protobuf.Any build_execution_event = 61; + + // An event that contains supplemental tool-specific information about + // source fetching. + google.protobuf.Any source_fetch_event = 62; + } +} + +// Unique identifier for a build event stream. +message StreamId { + // Which build component generates this event stream. Each build component + // may generate one event stream. + enum BuildComponent { + // Unknown or unspecified; callers should never set this value. + UNKNOWN_COMPONENT = 0; + + // A component that coordinates builds. + CONTROLLER = 1; + + // A component that runs executables needed to complete a build. + WORKER = 2; + + // A component that builds something. + TOOL = 3; + + DEPRECATED = 4; + } + + int64 project_number = 5; + + // The id of a Build message. + string build_id = 1; + + // The unique invocation ID within this build. + // It should be the same as {invocation} (below) during the migration. + string invocation_id = 6; + + // The component that emitted this event. + BuildComponent component = 3; + + // The unique invocation ID within this build. + // It should be the same as {invocation_id} below during the migration. + string invocation = 4; +} + +// The type of console output stream. +enum ConsoleOutputStream { + // Unspecified or unknown. + UNKNOWN = 0; + + // Normal output stream. + STDOUT = 1; + + // Error output stream. + STDERR = 2; +} diff --git a/google/devtools/build/v1/build_status.proto b/google/devtools/build/v1/build_status.proto new file mode 100644 index 00000000..3c2cbb7e --- /dev/null +++ b/google/devtools/build/v1/build_status.proto @@ -0,0 +1,63 @@ +// Copyright 2017 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.devtools.build.v1; + +import "google/api/annotations.proto"; +import "google/protobuf/any.proto"; + +option cc_enable_arenas = true; +option go_package = "google.golang.org/genproto/googleapis/devtools/build/v1;build"; +option java_multiple_files = true; +option java_outer_classname = "BuildStatusProto"; +option java_package = "com.google.devtools.build.v1"; + + +// Status used for both invocation attempt and overall build completion. +message BuildStatus { + // The end result of the Build. + enum Result { + // Unspecified or unknown. + UNKNOWN_STATUS = 0; + + // Build was successful and tests (if requested) all pass. + COMMAND_SUCCEEDED = 1; + + // Build error and/or test failure. + COMMAND_FAILED = 2; + + // Unable to obtain a result due to input provided by the user. + USER_ERROR = 3; + + // Unable to obtain a result due to a failure within the build system. + SYSTEM_ERROR = 4; + + // Build required too many resources, such as build tool RAM. + RESOURCE_EXHAUSTED = 5; + + // An invocation attempt time exceeded its deadline. + INVOCATION_DEADLINE_EXCEEDED = 6; + + // Build request time exceeded the request_deadline + REQUEST_DEADLINE_EXCEEDED = 8; + + // The build was cancelled by a call to CancelBuild. + CANCELLED = 7; + } + + // The end result. + Result result = 1; +} diff --git a/google/devtools/build/v1/publish_build_event.proto b/google/devtools/build/v1/publish_build_event.proto new file mode 100644 index 00000000..7589602a --- /dev/null +++ b/google/devtools/build/v1/publish_build_event.proto @@ -0,0 +1,136 @@ +// Copyright 2017 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.devtools.build.v1; + +import "google/api/annotations.proto"; +import "google/api/auth.proto"; +import "google/devtools/build/v1/build_events.proto"; +import "google/protobuf/any.proto"; +import "google/protobuf/duration.proto"; +import "google/protobuf/empty.proto"; + +option cc_enable_arenas = true; +option go_package = "google.golang.org/genproto/googleapis/devtools/build/v1;build"; +option java_multiple_files = true; +option java_outer_classname = "BackendProto"; +option java_package = "com.google.devtools.build.v1"; + + +// A service for publishing BuildEvents. BuildEvents are generated by Build +// Systems to record actions taken during a Build. Events occur in streams, +// are identified by a StreamId, and ordered by sequence number in a stream. +// +// A Build may contain several streams of BuildEvents, depending on the systems +// that are involved in the Build. Some BuildEvents are used to declare the +// beginning and end of major portions of a Build; these are called +// LifecycleEvents, and are used (for example) to indicate the beginning or end +// of a Build, and the beginning or end of an Invocation attempt (there can be +// more than 1 Invocation in a Build if, for example, a failure occurs somewhere +// and it needs to be retried). +// +// Other, build-tool events represent actions taken by the Build tool, such as +// target objects produced via compilation, tests run, et cetera. There could be +// more than one build tool stream for an invocation attempt of a build. +service PublishBuildEvent { + // Publish a build event stating the new state of a build (typically from the + // build queue). If the event is a BuildEnqueued event, also register the new + // build request ID and its build type to BES. + // + // The backend will persist the event and deliver it to registered frontend + // jobs immediately without batching. + // + // The commit status of the request is reported by the RPC's util_status() + // function. The error code is the canoncial error code defined in + // //util/task/codes.proto. + rpc PublishLifecycleEvent(PublishLifecycleEventRequest) returns (google.protobuf.Empty) { + option (google.api.http) = { post: "/v1/lifecycleEvents:publish" body: "*" }; + } + + // Publish build tool events belonging to the same stream to a backend job + // using bidirectional streaming. + rpc PublishBuildToolEventStream(stream OrderedBuildEvent) returns (stream PublishBuildToolEventStreamResponse) { + option (google.api.http) = { post: "/v1/events:publish" body: "*" }; + } +} + +// Publishes 'lifecycle events' that update the high-level state of a build: +// - BuildEnqueued: When a build is scheduled. +// - InvocationAttemptStarted: When work for a build starts; there can be +// multiple invocations for a build (e.g. retries). +// - InvocationAttemptCompleted: When work for a build finishes. +// - BuildFinished: When a build is finished. +message PublishLifecycleEventRequest { + // The service level of the build request. Backends only uses this value when + // the BuildEnqueued event is published to determine what level of service + // this build should receive. + enum ServiceLevel { + // Non-interactive builds can tolerate longer event latencies. This is the + // default ServiceLevel if callers do not specify one. + NONINTERACTIVE = 0; + + // The events of an interactive build should be delivered with low latency. + INTERACTIVE = 1; + } + + // The interactivity of this build. + ServiceLevel service_level = 1; + + // The lifecycle build event. If this is a build tool event, the RPC will fail + // with INVALID_REQUEST. + OrderedBuildEvent build_event = 2; + + // If the next event for this build or invocation (depending on the event + // type) hasn't been published after this duration from when {build_event} + // is written to BES, consider this stream expired. If this field is not set, + // BES backend will use its own default value. + google.protobuf.Duration stream_timeout = 3; + + // Additional information about a build request. These are define by the event + // publishers, and the Build Event Service does not validate or interpret + // them. They are used while notifying internal systems of new builds and + // invocations if the OrderedBuildEvent.event type is + // BuildEnqueued/InvocationAttemptStarted. + repeated string notification_keywords = 4; + + // This field identifies which project (if any) the build is associated with. + string project_id = 6; +} + +// States which event has been committed. Any failure to commit will cause +// RPC errors, hence not recorded by this proto. +message PublishBuildToolEventStreamResponse { + // The stream that contains this event. + StreamId stream_id = 1; + + // The sequence number of this event that has been committed. + int64 sequence_number = 2; +} + +// Build event with contextual information about the stream it belongs to and +// its position in that stream. +message OrderedBuildEvent { + // Which build event stream this event belongs to. + StreamId stream_id = 1; + + // The position of this event in the stream. The sequence numbers for a build + // event stream should be a sequence of consecutive natural numbers starting + // from one. (1, 2, 3, ...) + int64 sequence_number = 2; + + // The actual event. + BuildEvent event = 3; +}