chore: flagd constructor refactoring (#294)

Signed-off-by: Kavindu Dodanduwa <[email protected]>

Author: Kavindu-Dodan

providers/flagd/README.md

@@ -17,50 +17,92 @@ A feature flag daemon with a Unix philosophy.
 
 ## Usage
 
-The `FlagdProvider` communicates with flagd via the gRPC protocol. Instantiate a new FlagdProvider instance, and configure the OpenFeature SDK to use it:
+The `FlagdProvider` communicates with flagd via the gRPC protocol. Instantiate a new FlagdProvider instance, and
+configure the OpenFeature SDK to use it:
 
 ```java
-FlagdProvider provider = new FlagdProvider();
-OpenFeatureAPI.getInstance().setProvider(provider);
+// Create a flagd instance with default options
+FlagdProvider flagd = new FlagdProvider();
+// Set flagd as the OpenFeature Provider
+OpenFeatureAPI.getInstance().setProvider(flagd);
 ```
 
-Options can be defined in the constructor or as environment variables, with constructor options having the highest precedence.
+Options can be defined in the constructor or as environment variables, with constructor options having the highest
+precedence.
 
-| Option name           | Environment variable name       | Type    | Default   | Values        |
-| --------------------- | ------------------------------- | ------- | --------- | ------------- |
-| host                  | FLAGD_HOST                      | string  | localhost |               |
-| port                  | FLAGD_PORT                      | number  | 8013      |               |
-| tls                   | FLAGD_TLS                       | boolean | false     |               |
-| socketPath            | FLAGD_SOCKET_PATH               | string  | -         |               |
-| certPath              | FLAGD_SERVER_CERT_PATH          | string  | -         |               |
-| cache                 | FLAGD_CACHE                     | string  | lru       | lru,disabled  |
-| maxCacheSize          | FLAGD_MAX_CACHE_SIZE            | int     | 1000      |               |
-| maxEventStreamRetries | FLAGD_MAX_EVENT_STREAM_RETRIES  | int     | 5         |               |
+Default options can be overridden through a `FlagdOptions` based constructor or set to be picked up from the environment
+variables.
+
+### Supported environmental variables
+
+| Option name           | Environment variable name      | Type    | Default   | Values       |
+|-----------------------|--------------------------------|---------|-----------|--------------|
+| host                  | FLAGD_HOST                     | string  | localhost |              |
+| port                  | FLAGD_PORT                     | number  | 8013      |              |
+| tls                   | FLAGD_TLS                      | boolean | false     |              |
+| socketPath            | FLAGD_SOCKET_PATH              | string  | null      |              |
+| certPath              | FLAGD_SERVER_CERT_PATH         | string  | null      |              |
+| cache                 | FLAGD_CACHE                    | string  | lru       | lru,disabled |
+| maxCacheSize          | FLAGD_MAX_CACHE_SIZE           | int     | 1000      |              |
+| maxEventStreamRetries | FLAGD_MAX_EVENT_STREAM_RETRIES | int     | 5         |              |
+
+### OpenTelemetry support
+
+OpenTelemetry support can be enabled either through [automatic instrumentation](https://opentelemetry.io/docs/instrumentation/java/automatic/) 
+or with [manual instrumentation](https://opentelemetry.io/docs/instrumentation/java/manual/). 
+
+For manual instrumentation, flagd provider can be constructed with an `OpenTelemetry` instance.
+
+```java
+FlagdOptions options = 
+        FlagdOptions.builder()
+                    .openTelemetry(openTelemetry)
+                    .build();
+
+FlagdProvider flagdProvider = new FlagdProvider(options);
+```
+
+Please refer [OpenTelemetry example](https://opentelemetry.io/docs/instrumentation/java/manual/#example) for best 
+practice guideline.
+
+Telemetry configuration combined with [flagd telemetry ](https://github.com/open-feature/flagd/blob/main/docs/configuration/flagd_telemetry.md)
+allows distributed tracing.
 
 ### Unix socket support
 
-Unix socket communication with flag is facilitated via usage of the linux-native `epoll` library on `linux-x86_64` only (ARM support is pending relase of `netty-transport-native-epoll` v5). Unix sockets are not supported on other platforms or architectures.
+Unix socket communication with flag is facilitated via usage of the linux-native `epoll` library on `linux-x86_64`
+only (ARM support is pending relase of `netty-transport-native-epoll` v5). Unix sockets are not supported on other
+platforms or architectures.
 
 ### Reconnection
 
-Reconnection is supported by the underlying GRPCBlockingStub. If connection to flagd is lost, it will reconnect automatically.
+Reconnection is supported by the underlying GRPCBlockingStub. If connection to flagd is lost, it will reconnect
+automatically.
 
 ### Deadline (gRPC call timeout)
 
 The deadline for an individual flag evaluation can be configured by calling `setDeadline(< deadline in millis >)`.
-If the gRPC call is not completed within this deadline, the gRPC call is terminated with the error `DEADLINE_EXCEEDED` and the evaluation will default.
+If the gRPC call is not completed within this deadline, the gRPC call is terminated with the error `DEADLINE_EXCEEDED`
+and the evaluation will default.
 The default deadline is 500ms, though evaluations typically take on the order of 10ms.
 
 ### TLS
 
 Though not required in deployments where flagd runs on the same host as the workload, TLS is available.
 
-:warning: Note that there's a [vulnerability](https://security.snyk.io/vuln/SNYK-JAVA-IONETTY-1042268) in [netty](https://github.com/netty/netty), a transitive dependency of the underlying gRPC libraries used in the flagd-provider that fails to correctly validate certificates. This will be addressed in netty v5.
+:warning: Note that there's a [vulnerability](https://security.snyk.io/vuln/SNYK-JAVA-IONETTY-1042268)
+in [netty](https://github.com/netty/netty), a transitive dependency of the underlying gRPC libraries used in the
+flagd-provider that fails to correctly validate certificates. This will be addressed in netty v5.
 
 ## Caching
 
-The provider attempts to establish a connection to flagd's event stream (up to 5 times by default). If the connection is successful and caching is enabled each flag returned with reason `STATIC` is cached until an event is received concerning the cached flag (at which point it is removed from cache).
+The provider attempts to establish a connection to flagd's event stream (up to 5 times by default). If the connection is
+successful and caching is enabled each flag returned with reason `STATIC` is cached until an event is received
+concerning the cached flag (at which point it is removed from cache).
 
-On invocation of a flag evaluation (if caching is available) an attempt is made to retrieve the entry from cache, if found the flag is returned with reason `CACHED`.
+On invocation of a flag evaluation (if caching is available) an attempt is made to retrieve the entry from cache, if
+found the flag is returned with reason `CACHED`.
 
-By default, the provider is configured to use [least recently used (lru)](https://commons.apache.org/proper/commons-collections/apidocs/org/apache/commons/collections4/map/LRUMap.html) caching with up to 1000 entries.
+By default, the provider is configured to
+use [least recently used (lru)](https://commons.apache.org/proper/commons-collections/apidocs/org/apache/commons/collections4/map/LRUMap.html)
+caching with up to 1000 entries.

providers/flagd/pom.xml

@@ -10,7 +10,7 @@
     </parent>
     <groupId>dev.openfeature.contrib.providers</groupId>
     <artifactId>flagd</artifactId>
-    <version>0.5.8-snapshot</version> <!--x-release-please-version -->
+    <version>0.5.8</version> <!--x-release-please-version -->
 
     <name>flagd</name>
     <description>FlagD provider for Java</description>

providers/flagd/src/main/java/dev/openfeature/contrib/providers/flagd/Config.java

@@ -0,0 +1,46 @@
+package dev.openfeature.contrib.providers.flagd;
+
+final class Config {
+    static final String DEFAULT_PORT = "8013";
+    static final String DEFAULT_TLS = "false";
+    static final String DEFAULT_HOST = "localhost";
+
+    static final int DEFAULT_DEADLINE = 500;
+    static final int DEFAULT_MAX_CACHE_SIZE = 1000;
+
+    static final String HOST_ENV_VAR_NAME = "FLAGD_HOST";
+    static final String PORT_ENV_VAR_NAME = "FLAGD_PORT";
+    static final String TLS_ENV_VAR_NAME = "FLAGD_TLS";
+    static final String SOCKET_PATH_ENV_VAR_NAME = "FLAGD_SOCKET_PATH";
+    static final String SERVER_CERT_PATH_ENV_VAR_NAME = "FLAGD_SERVER_CERT_PATH";
+    static final String CACHE_ENV_VAR_NAME = "FLAGD_CACHE";
+    static final String MAX_CACHE_SIZE_ENV_VAR_NAME = "FLAGD_MAX_CACHE_SIZE";
+    static final String MAX_EVENT_STREAM_RETRIES_ENV_VAR_NAME = "FLAGD_MAX_EVENT_STREAM_RETRIES";
+
+    static final String STATIC_REASON = "STATIC";
+    static final String CACHED_REASON = "CACHED";
+
+    static final String FLAG_KEY_FIELD = "flag_key";
+    static final String CONTEXT_FIELD = "context";
+    static final String VARIANT_FIELD = "variant";
+    static final String VALUE_FIELD = "value";
+    static final String REASON_FIELD = "reason";
+
+    static final String LRU_CACHE = "lru";
+    static final String DEFAULT_CACHE = LRU_CACHE;
+
+    static final int DEFAULT_MAX_EVENT_STREAM_RETRIES = 5;
+    static final int BASE_EVENT_STREAM_RETRY_BACKOFF_MS = 1000;
+
+    static String fallBackToEnvOrDefault(String key, String defaultValue) {
+        return System.getenv(key) != null ? System.getenv(key) : defaultValue;
+    }
+
+    static int fallBackToEnvOrDefault(String key, int defaultValue) {
+        try {
+            return System.getenv(key) != null ? Integer.parseInt(System.getenv(key)) : defaultValue;
+        } catch (Exception e) {
+            return defaultValue;
+        }
+    }
+}

providers/flagd/src/main/java/dev/openfeature/contrib/providers/flagd/EventStreamCallback.java

@@ -4,7 +4,7 @@
  * Defines behaviour required of event stream callbacks.
  */
 interface EventStreamCallback {
-    void setEventStreamAlive(Boolean alive);
+    void setEventStreamAlive(boolean alive);
 
     void restartEventStream() throws Exception;
 }

providers/flagd/src/main/java/dev/openfeature/contrib/providers/flagd/EventStreamObserver.java

@@ -11,8 +11,8 @@
  */
 @Slf4j
 public class EventStreamObserver implements StreamObserver<EventStreamResponse> {
-    private EventStreamCallback callback;
-    private FlagdCache cache;
+    private final EventStreamCallback callback;
+    private final FlagdCache cache;
 
     private static final String configurationChange = "configuration_change";
     private static final String providerReady = "provider_ready";

providers/flagd/src/main/java/dev/openfeature/contrib/providers/flagd/FlagdCache.java

@@ -7,14 +7,15 @@
 
 import dev.openfeature.sdk.ProviderEvaluation;
 
+import static dev.openfeature.contrib.providers.flagd.Config.LRU_CACHE;
+
 /**
  * Exposes caching mechanism for flag evaluations.
  */
 public class FlagdCache {
     private Map<String,ProviderEvaluation<? extends Object>> store;
     private Boolean enabled = false;
 
-    static final String LRU_CACHE = "lru";
     static final String DISABLED = "disabled";
 
     FlagdCache(String cache, int maxCacheSize) {
@@ -27,8 +28,7 @@ public class FlagdCache {
                 return;
             case LRU_CACHE:
             default:
-                this.store = Collections
-                        .synchronizedMap(new LRUMap<String, ProviderEvaluation<? extends Object>>(maxCacheSize));
+                this.store = Collections.synchronizedMap(new LRUMap<>(maxCacheSize));
         }
 
         this.enabled = true;

providers/flagd/src/main/java/dev/openfeature/contrib/providers/flagd/FlagdGrpcInterceptor.java

@@ -11,6 +11,7 @@
 import io.opentelemetry.context.Context;
 import io.opentelemetry.context.propagation.TextMapSetter;
 
+import javax.annotation.Nonnull;
 import javax.annotation.Nullable;
 
 /**
@@ -22,7 +23,7 @@ final class FlagdGrpcInterceptor implements ClientInterceptor {
 
     private final OpenTelemetry openTelemetry;
 
-    FlagdGrpcInterceptor(final OpenTelemetry openTelemetry) {
+    FlagdGrpcInterceptor(@Nonnull final OpenTelemetry openTelemetry) {
         this.openTelemetry = openTelemetry;
     }
 
@@ -32,7 +33,8 @@ final class FlagdGrpcInterceptor implements ClientInterceptor {
         final ClientCall<ReqT, RespT> call = channel.newCall(methodDescriptor, callOptions);
 
         return new ForwardingClientCall.SimpleForwardingClientCall<ReqT, RespT>(call) {
-            @Override public void start(Listener<RespT> responseListener, Metadata headers) {
+            @Override
+            public void start(Listener<RespT> responseListener, Metadata headers) {
                 openTelemetry.getPropagators().getTextMapPropagator().inject(Context.current(), headers, SETTER);
                 super.start(responseListener, headers);
             }
@@ -43,7 +45,8 @@ final class FlagdGrpcInterceptor implements ClientInterceptor {
      * Setter implements TextMapSetter with carrier check.
      */
     static class Setter implements TextMapSetter<Metadata> {
-        @Override public void set(@Nullable Metadata carrier, String key, String value) {
+        @Override
+        public void set(@Nullable Metadata carrier, String key, String value) {
             if (carrier == null) {
                 return;
             }

providers/flagd/src/main/java/dev/openfeature/contrib/providers/flagd/FlagdOptions.java

@@ -0,0 +1,86 @@
+package dev.openfeature.contrib.providers.flagd;
+
+import io.opentelemetry.api.OpenTelemetry;
+import lombok.Builder;
+import lombok.Getter;
+
+import static dev.openfeature.contrib.providers.flagd.Config.CACHE_ENV_VAR_NAME;
+import static dev.openfeature.contrib.providers.flagd.Config.DEFAULT_CACHE;
+import static dev.openfeature.contrib.providers.flagd.Config.DEFAULT_HOST;
+import static dev.openfeature.contrib.providers.flagd.Config.DEFAULT_MAX_CACHE_SIZE;
+import static dev.openfeature.contrib.providers.flagd.Config.DEFAULT_MAX_EVENT_STREAM_RETRIES;
+import static dev.openfeature.contrib.providers.flagd.Config.DEFAULT_PORT;
+import static dev.openfeature.contrib.providers.flagd.Config.DEFAULT_TLS;
+import static dev.openfeature.contrib.providers.flagd.Config.HOST_ENV_VAR_NAME;
+import static dev.openfeature.contrib.providers.flagd.Config.MAX_CACHE_SIZE_ENV_VAR_NAME;
+import static dev.openfeature.contrib.providers.flagd.Config.MAX_EVENT_STREAM_RETRIES_ENV_VAR_NAME;
+import static dev.openfeature.contrib.providers.flagd.Config.PORT_ENV_VAR_NAME;
+import static dev.openfeature.contrib.providers.flagd.Config.SERVER_CERT_PATH_ENV_VAR_NAME;
+import static dev.openfeature.contrib.providers.flagd.Config.SOCKET_PATH_ENV_VAR_NAME;
+import static dev.openfeature.contrib.providers.flagd.Config.TLS_ENV_VAR_NAME;
+import static dev.openfeature.contrib.providers.flagd.Config.fallBackToEnvOrDefault;
+
+
+/**
+ * FlagdOptions is a builder to build flagd provider options.
+ * */
+@Builder
+@Getter
+@SuppressWarnings("PMD.TooManyStaticImports")
+public class FlagdOptions {
+
+    /**
+     * flagd connection host.
+     * */
+    @Builder.Default
+    private String host = fallBackToEnvOrDefault(HOST_ENV_VAR_NAME, DEFAULT_HOST);
+
+    /**
+     * flagd connection port.
+     * */
+    @Builder.Default
+    private int port = Integer.parseInt(fallBackToEnvOrDefault(PORT_ENV_VAR_NAME, DEFAULT_PORT));
+
+    /**
+     * Use TLS connectivity.
+     * */
+    @Builder.Default
+    private boolean tls = Boolean.parseBoolean(fallBackToEnvOrDefault(TLS_ENV_VAR_NAME, DEFAULT_TLS));
+
+    /**
+     * TLS certificate overriding if TLS connectivity is used.
+     * */
+    @Builder.Default
+    private String certPath = fallBackToEnvOrDefault(SERVER_CERT_PATH_ENV_VAR_NAME, null);
+
+    /**
+     * Unix socket path to flagd.
+     * */
+    @Builder.Default
+    private String socketPath = fallBackToEnvOrDefault(SOCKET_PATH_ENV_VAR_NAME, null);
+
+    /**
+     * Cache type to use. Supports - lru, disabled.
+     * */
+    @Builder.Default
+    private String cacheType = fallBackToEnvOrDefault(CACHE_ENV_VAR_NAME, DEFAULT_CACHE);
+
+    /**
+     * Max cache size.
+     * */
+    @Builder.Default
+    private int maxCacheSize = fallBackToEnvOrDefault(MAX_CACHE_SIZE_ENV_VAR_NAME, DEFAULT_MAX_CACHE_SIZE);
+
+    /**
+     * Max event stream connection retries.
+     * */
+    @Builder.Default
+    private int maxEventStreamRetries =
+            fallBackToEnvOrDefault(MAX_EVENT_STREAM_RETRIES_ENV_VAR_NAME, DEFAULT_MAX_EVENT_STREAM_RETRIES);
+
+    /**
+     * Inject OpenTelemetry for the library runtime. Providing sdk will initiate distributed tracing for flagd grpc
+     * connectivity.
+     * */
+    private OpenTelemetry openTelemetry;
+}