Add interfaces for the build event protocol

Bazel in the will provide a machine-readable stream of important build
events. These interfaces set up the framework and expectations about
the produced events and the entities distributing those events.

--
Change-Id: If2c3b2e11c31b0136b57eadeef2d2f8f8fe5e2e7
Reviewed-on: https://bazel-review.googlesource.com/#/c/6272
MOS_MIGRATED_REVID=134522369

5 files changed, 203 insertions, 0 deletions

diff --git a/src/main/java/com/google/devtools/build/lib/BUILD b/src/main/java/com/google/devtools/build/lib/BUILD
index 244ec20d82..eb7c8d7828 100644
--- a/src/main/java/com/google/devtools/build/lib/BUILD
+++ b/src/main/java/com/google/devtools/build/lib/BUILD
@@ -294,6 +294,18 @@ java_library(
     ],
 )
 
+# External build-event reporting infrastructure
+java_library(
+    name = "buildeventstream",
+    srcs = glob(["buildeventstream/*.java"]),
+    deps = [
+        "//src/main/java/com/google/devtools/build/lib/buildeventstream/proto:build_event_stream_java_proto",
+        "//src/main/java/com/google/devtools/build/lib/cmdline",
+        "//third_party:jsr305",
+        "//third_party/protobuf",
+    ],
+)
+
 ########################################################################
 #
 # The "foundation" library (concurrent, events, util, vfs, inmemoryfs, options)
diff --git a/src/main/java/com/google/devtools/build/lib/buildeventstream/BuildEvent.java b/src/main/java/com/google/devtools/build/lib/buildeventstream/BuildEvent.java
new file mode 100644
index 0000000000..901586fa40
--- /dev/null
+++ b/src/main/java/com/google/devtools/build/lib/buildeventstream/BuildEvent.java
@@ -0,0 +1,31 @@
+// Copyright 2016 The Bazel Authors. All rights reserved.
+//
+// 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.
+
+package com.google.devtools.build.lib.buildeventstream;
+
+/**
+ * Interface for objects that can be posted on the public event stream.
+ *
+ * <p>Objects posted on the build-event stream will implement this interface. This allows
+ * pass-through of events, as well as proper chaining of events.
+ */
+public interface BuildEvent extends ChainableEvent {
+  /**
+   * Provide a binary representation of the event.
+   *
+   * <p>Provide a presentation of the event according to the specified binary format, as appropriate
+   * protocol buffer.
+   */
+  BuildEventStreamProtos.BuildEvent asStreamProto();
+}
diff --git a/src/main/java/com/google/devtools/build/lib/buildeventstream/BuildEventId.java b/src/main/java/com/google/devtools/build/lib/buildeventstream/BuildEventId.java
new file mode 100644
index 0000000000..644760b2fd
--- /dev/null
+++ b/src/main/java/com/google/devtools/build/lib/buildeventstream/BuildEventId.java
@@ -0,0 +1,76 @@
+// Copyright 2016 The Bazel Authors. All rights reserved.
+//
+// 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.
+
+package com.google.devtools.build.lib.buildeventstream;
+
+import com.google.protobuf.TextFormat;
+import java.io.Serializable;
+import java.util.Objects;
+import javax.annotation.concurrent.Immutable;
+
+/**
+ * Class of identifiers for publically posted events.
+ *
+ * <p>Since event identifiers need to be created before the actual event, the event IDs are highly
+ * structured so that equal identifiers can easily be generated. The main way of pregenerating event
+ * identifiers that do not accidentally coincide is by providing a target or a target pattern;
+ * therefore, those (if provided) are made specially visible.
+ */
+@Immutable
+public final class BuildEventId implements Serializable {
+  private final BuildEventStreamProtos.BuildEventId protoid;
+
+  private BuildEventId(BuildEventStreamProtos.BuildEventId protoid) {
+    this.protoid = protoid;
+  }
+
+  @Override
+  public int hashCode() {
+    return Objects.hash(protoid);
+  }
+
+  @Override
+  public boolean equals(Object other) {
+    if (other == null || !other.getClass().equals(getClass())) {
+      return false;
+    }
+    BuildEventId that = (BuildEventId) other;
+    return Objects.equals(this.protoid, that.protoid);
+  }
+
+  @Override
+  public String toString() {
+    return "BuildEventId {" + TextFormat.printToString(protoid) + "}";
+  }
+
+  public BuildEventStreamProtos.BuildEventId asStreamProto() {
+    return protoid;
+  }
+
+  public static BuildEventId unknownBuildEventId(String details) {
+    BuildEventStreamProtos.BuildEventId.UnknownBuildEventId id =
+        BuildEventStreamProtos.BuildEventId.UnknownBuildEventId.newBuilder()
+            .setDetails(details)
+            .build();
+    return new BuildEventId(
+        BuildEventStreamProtos.BuildEventId.newBuilder().setUnknown(id).build());
+  }
+
+  public static BuildEventId progressId(int count) {
+    BuildEventStreamProtos.BuildEventId.ProgressId id =
+        BuildEventStreamProtos.BuildEventId.ProgressId.newBuilder().setOpaqueCount(count).build();
+    return new BuildEventId(
+        BuildEventStreamProtos.BuildEventId.newBuilder().setProgress(id).build());
+  }
+}
diff --git a/src/main/java/com/google/devtools/build/lib/buildeventstream/BuildEventTransport.java b/src/main/java/com/google/devtools/build/lib/buildeventstream/BuildEventTransport.java
new file mode 100644
index 0000000000..f539e3affc
--- /dev/null
+++ b/src/main/java/com/google/devtools/build/lib/buildeventstream/BuildEventTransport.java
@@ -0,0 +1,34 @@
+// Copyright 2016 The Bazel Authors. All rights reserved.
+//
+// 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.
+
+package com.google.devtools.build.lib.buildeventstream;
+
+import java.io.IOException;
+
+/** Interface for transports of the build-event stream. */
+public interface BuildEventTransport {
+
+  /**
+   * Ensure that the event will eventually be reported to the receiver this object is a transport
+   * for; the transport is responsible that events arrive at the endpoint in the order they are sent
+   * by invocations of this method.
+   */
+  void sendBuildEvent(BuildEvent event) throws IOException;
+
+  /**
+   * Close all open resources, if any. This method will be called on the transport after all events
+   * have been sent. If a transport is stateless, it is correct to do nothing.
+   */
+  void close() throws IOException;
+}
diff --git a/src/main/java/com/google/devtools/build/lib/buildeventstream/ChainableEvent.java b/src/main/java/com/google/devtools/build/lib/buildeventstream/ChainableEvent.java
new file mode 100644
index 0000000000..3fdf22c3ba
--- /dev/null
+++ b/src/main/java/com/google/devtools/build/lib/buildeventstream/ChainableEvent.java
@@ -0,0 +1,50 @@
+// Copyright 2016 The Bazel Authors. All rights reserved.
+//
+// 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.
+
+package com.google.devtools.build.lib.buildeventstream;
+
+import java.util.Collection;
+
+/**
+ * Interface for objects organised in a DAG-like fashion.
+ *
+ * <p>When objects that are naturally organised in a directed acyclic graph are sent sequentially
+ * over some channel, the graph-structure needs to represented in some way. We chose the
+ * representation that each node knows its immediate sucessor nodes (rather than its predecessors)
+ * to suit the * properties of the event stream: new parents of a node might be discovered late,
+ * e.g., if a test suite is only expanded after one of its tests is already finished as it was also
+ * needed for another target.
+ */
+public interface ChainableEvent {
+
+  /**
+   * Provide the identifier of the event.
+   *
+   * <p>Event identifiers have to be unique within the set of events belonging to the same build
+   * invocation.
+   */
+  BuildEventId getEventId();
+
+  /**
+   * Provide the children of the event.
+   *
+   * <p>It is a requirement of a well-formed event stream that for every event that does not
+   * indicate the beginning of a new build, at least one parent be present before the event itself.
+   * However, more parents might appear later in the stream (e.g., if a test suite expanded later
+   * discovers that a test that is already completed belongs to it).
+   *
+   * <p>A build-event stream is finished if and only if all announced children have occurred.
+   */
+  Collection<BuildEventId> getChildrenEvents();
+}