Opamp client api

opamp-client/build.gradle.kts

@@ -1,5 +1,6 @@
 plugins {
   id("otel.java-conventions")
+  id("com.google.protobuf") version "0.9.4"
 }
 
 description = "Client implementation of the OpAMP spec."
@@ -9,3 +10,25 @@ java {
   sourceCompatibility = JavaVersion.VERSION_1_8
   targetCompatibility = JavaVersion.VERSION_1_8
 }
+
+tasks.withType<JavaCompile>().configureEach {
+  with(options) {
+    // Suppressing warnings about the usage of deprecated methods.
+    // This is needed because the Protobuf plugin (com.google.protobuf) generates code that uses deprecated methods.
+    compilerArgs.add("-Xlint:-deprecation")
+  }
+}
+
+val protobufVersion = "4.28.2"
+
+protobuf {
+  protoc {
+    artifact = "com.google.protobuf:protoc:$protobufVersion"
+  }
+}
+
+dependencies {
+  implementation("com.google.protobuf:protobuf-java:$protobufVersion")
+  annotationProcessor("com.google.auto.value:auto-value")
+  compileOnly("com.google.auto.value:auto-value-annotations")
+}

opamp-client/src/main/java/io/opentelemetry/opamp/client/internal/OpampClient.java

@@ -0,0 +1,97 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.opamp.client.internal;
+
+import io.opentelemetry.opamp.client.internal.response.MessageData;
+import opamp.proto.Opamp;
+
+public interface OpampClient {
+
+  /**
+   * Starts the client and begin attempts to connect to the Server. Once connection is established
+   * the client will attempt to maintain it by reconnecting if the connection is lost. All failed
+   * connection attempts will be reported via {@link Callback#onConnectFailed(OpampClient,
+   * Throwable)} callback.
+   *
+   * <p>This method does not wait until the connection to the Server is established and will likely
+   * return before the connection attempts are even made.
+   *
+   * <p>This method may be called only once.
+   *
+   * @param callback The Callback to which the Client will notify about any Server requests and
+   *     responses.
+   */
+  void start(Callback callback);
+
+  /**
+   * Stops the client. May be called only after {@link #start(OpampClient.Callback)}. May be called
+   * only once. After this call returns successfully it is guaranteed that no callbacks will be
+   * called. Once stopped, the client cannot be started again.
+   */
+  void stop();
+
+  /**
+   * Sets the current remote config status which will be sent in the next agent to server request.
+   *
+   * @param remoteConfigStatus The new remote config status.
+   */
+  void setRemoteConfigStatus(Opamp.RemoteConfigStatus remoteConfigStatus);
+
+  /**
+   * Sets the current effective config which will be sent in the next agent to server request.
+   *
+   * @param effectiveConfig The new effective config.
+   */
+  void setEffectiveConfig(Opamp.EffectiveConfig effectiveConfig);
+
+  interface Callback {
+    /**
+     * Called when the connection is successfully established to the Server. May be called after
+     * {@link #start(OpampClient.Callback)} is called and every time a connection is established to
+     * the Server. For WebSocket clients this is called after the handshake is completed without any
+     * error. For HTTP clients this is called for any request if the response status is OK.
+     *
+     * @param client The relevant {@link OpampClient} instance.
+     */
+    void onConnect(OpampClient client);
+
+    /**
+     * Called when the connection to the Server cannot be established. May be called after {@link
+     * #start(OpampClient.Callback)} is called and tries to connect to the Server. May also be
+     * called if the connection is lost and reconnection attempt fails.
+     *
+     * @param client The relevant {@link OpampClient} instance.
+     * @param throwable The exception.
+     */
+    void onConnectFailed(OpampClient client, Throwable throwable);
+
+    /**
+     * Called when the Server reports an error in response to some previously sent request. Useful
+     * for logging purposes. The Agent should not attempt to process the error by reconnecting or
+     * retrying previous operations. The client handles the ErrorResponse_UNAVAILABLE case
+     * internally by performing retries as necessary.
+     *
+     * @param client The relevant {@link OpampClient} instance.
+     * @param errorResponse The error returned by the Server.
+     */
+    void onErrorResponse(OpampClient client, Opamp.ServerErrorResponse errorResponse);
+
+    /**
+     * Called when the Agent receives a message that needs processing. See {@link MessageData}
+     * definition for the data that may be available for processing. During onMessage execution the
+     * {@link OpampClient} functions that change the status of the client may be called, e.g. if
+     * RemoteConfig is processed then {@link
+     * #setRemoteConfigStatus(opamp.proto.Opamp.RemoteConfigStatus)} should be called to reflect the
+     * processing result. These functions may also be called after onMessage returns. This is
+     * advisable if processing can take a long time. In that case returning quickly is preferable to
+     * avoid blocking the {@link OpampClient}.
+     *
+     * @param client The relevant {@link OpampClient} instance.
+     * @param messageData The server response data that needs processing.
+     */
+    void onMessage(OpampClient client, MessageData messageData);
+  }
+}

opamp-client/src/main/java/io/opentelemetry/opamp/client/internal/response/MessageData.java

@@ -0,0 +1,32 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.opamp.client.internal.response;
+
+import com.google.auto.value.AutoValue;
+import io.opentelemetry.opamp.client.internal.OpampClient;
+import javax.annotation.Nullable;
+import opamp.proto.Opamp;
+
+/**
+ * Data class provided in {@link OpampClient.Callback#onMessage(OpampClient, MessageData)} with
+ * Server's provided status changes.
+ */
+@AutoValue
+public abstract class MessageData {
+  @Nullable
+  public abstract Opamp.AgentRemoteConfig getRemoteConfig();
+
+  public static Builder builder() {
+    return new AutoValue_MessageData.Builder();
+  }
+
+  @AutoValue.Builder
+  public abstract static class Builder {
+    public abstract Builder setRemoteConfig(Opamp.AgentRemoteConfig remoteConfig);
+
+    public abstract MessageData build();
+  }
+}

opamp-client/src/main/proto/anyvalue.proto

@@ -0,0 +1,67 @@
+// Copyright 2019, OpenTelemetry 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.
+
+// This file is copied and modified from https://github.com/open-telemetry/opentelemetry-proto/blob/main/opentelemetry/proto/common/v1/common.proto
+// Modifications:
+//  - Removal of unneeded InstrumentationLibrary and StringKeyValue messages.
+//  - Change of go_package to reference a package in this repo.
+//  - Removal of gogoproto usage.
+
+syntax = "proto3";
+
+package opamp.proto;
+
+option go_package = "github.com/open-telemetry/opamp-go/protobufs";
+
+// AnyValue is used to represent any type of attribute value. AnyValue may contain a
+// primitive value such as a string or integer or it may contain an arbitrary nested
+// object containing arrays, key-value lists and primitives.
+message AnyValue {
+  // The value is one of the listed fields. It is valid for all values to be unspecified
+  // in which case this AnyValue is considered to be "null".
+  oneof value {
+    string string_value = 1;
+    bool bool_value = 2;
+    int64 int_value = 3;
+    double double_value = 4;
+    ArrayValue array_value = 5;
+    KeyValueList kvlist_value = 6;
+    bytes bytes_value = 7;
+  }
+}
+
+// ArrayValue is a list of AnyValue messages. We need ArrayValue as a message
+// since oneof in AnyValue does not allow repeated fields.
+message ArrayValue {
+  // Array of values. The array may be empty (contain 0 elements).
+  repeated AnyValue values = 1;
+}
+
+// KeyValueList is a list of KeyValue messages. We need KeyValueList as a message
+// since `oneof` in AnyValue does not allow repeated fields. Everywhere else where we need
+// a list of KeyValue messages (e.g. in Span) we use `repeated KeyValue` directly to
+// avoid unnecessary extra wrapping (which slows down the protocol). The 2 approaches
+// are semantically equivalent.
+message KeyValueList {
+  // A collection of key/value pairs of key-value pairs. The list may be empty (may
+  // contain 0 elements).
+  repeated KeyValue values = 1;
+}
+
+// KeyValue is a key-value pair that is used to store Span attributes, Link
+// attributes, etc.
+message KeyValue {
+  string key = 1;
+  AnyValue value = 2;
+}