Change Configuration.java to object instance & correct README

Author: MarketDataDev03

README.md

@@ -107,14 +107,10 @@ The seven permitted subtypes — `AuthenticationError`, `BadRequestError`,
 The repo uses **Gradle (Kotlin DSL)** with a version catalog at
 [`gradle/libs.versions.toml`](gradle/libs.versions.toml).
 
-The Gradle wrapper jar is **not** committed. Bootstrap once with a
-locally installed Gradle (≥ 8.10):
-
-```bash
-gradle wrapper --gradle-version 8.12
-```
-
-After that, use the wrapper for everything:
+The Gradle wrapper is committed (`gradlew`, `gradlew.bat`,
+`gradle/wrapper/gradle-wrapper.jar`, `gradle/wrapper/gradle-wrapper.properties`),
+so any JDK 17+ environment can build the project without a separate Gradle
+install — the wrapper downloads the right Gradle version on first run.
 
 ```bash
 ./gradlew build               # compile + unit tests + spotless + jacoco

src/main/java/com/marketdata/sdk/MarketDataClient.java

@@ -49,13 +49,14 @@ public final class MarketDataClient implements AutoCloseable {
   private final boolean validateOnStartup;
 
   private MarketDataClient(Builder builder) {
-    this.token = Configuration.resolve(builder.apiKey, EnvVars.TOKEN);
+    Configuration config = Configuration.loadFromProcess();
+    this.token = config.resolve(builder.apiKey, EnvVars.TOKEN);
     this.baseUrl =
         trimTrailingSlash(
-            Configuration.resolveOrDefault(
+            config.resolveOrDefault(
                 builder.baseUrl, EnvVars.BASE_URL, Configuration.DEFAULT_BASE_URL));
     this.apiVersion =
-        Configuration.resolveOrDefault(
+        config.resolveOrDefault(
             builder.apiVersion, EnvVars.API_VERSION, Configuration.DEFAULT_API_VERSION);
     this.demoMode = this.token == null;
     this.validateOnStartup = builder.validateOnStartup;

src/main/java/com/marketdata/sdk/internal/Configuration.java

@@ -12,39 +12,49 @@
  * Resolves SDK configuration values per the cascade in SDK requirements §4: {@code explicit value →
  * MARKETDATA_* env var → .env file in CWD → built-in default}.
  *
- * <p>The {@code .env} file is read lazily from the current working directory when an env-backed
- * value is requested. Lines starting with {@code #} are treated as comments; surrounding single or
- * double quotes on values are stripped.
+ * <p>The only public construction path is {@link #loadFromProcess()}, which snapshots the live
+ * environment and the {@code .env} file once. The constructor is strictly private — there is no
+ * production-callable backdoor for injecting arbitrary maps. Tests reach the private constructor
+ * via reflection (see {@code ConfigurationTest}); this is by design so a developer can't
+ * accidentally take a shortcut around the canonical load path.
  */
 public final class Configuration {
 
   public static final String DEFAULT_BASE_URL = "https://api.marketdata.app";
   public static final String DEFAULT_API_VERSION = "v1";
+  private static final Path DEFAULT_DOTENV_PATH = Paths.get(".env");
 
-  private Configuration() {}
+  private final Map<String, String> systemEnv;
+  private final Map<String, String> dotEnv;
+
+  private Configuration(Map<String, String> systemEnv, Map<String, String> dotEnv) {
+    this.systemEnv = Map.copyOf(systemEnv);
+    this.dotEnv = Map.copyOf(dotEnv);
+  }
 
   /**
-   * Returns the first non-blank value among {@code explicit}, the named environment variable, and
-   * the {@code .env} file entry — or {@code null} if none is set.
+   * Production factory: snapshots {@code System.getenv()} and reads {@code ./.env} once. Call
+   * during client construction.
    */
-  public static @Nullable String resolve(@Nullable String explicit, String envKey) {
+  public static Configuration loadFromProcess() {
+    return new Configuration(System.getenv(), readDotEnvFile(DEFAULT_DOTENV_PATH));
+  }
+
+  /** Cascade: explicit → system env → .env → {@code null}. */
+  public @Nullable String resolve(@Nullable String explicit, String envKey) {
     if (isPresent(explicit)) {
       return explicit;
     }
-    String fromSystem = System.getenv(envKey);
+    String fromSystem = systemEnv.get(envKey);
     if (isPresent(fromSystem)) {
       return fromSystem;
     }
-    String fromDotEnv = readDotEnv().get(envKey);
+    String fromDotEnv = dotEnv.get(envKey);
     return isPresent(fromDotEnv) ? fromDotEnv : null;
   }
 
-  /**
-   * Same as {@link #resolve(String, String)} but falls back to the supplied default when the
-   * cascade yields nothing.
-   */
-  public static String resolveOrDefault(
-      @Nullable String explicit, String envKey, String defaultValue) {
+  /** Same as {@link #resolve} but returns {@code defaultValue} when the cascade yields nothing. */
+  public String resolveOrDefault(@Nullable String explicit, String envKey, String defaultValue) {
     String resolved = resolve(explicit, envKey);
     return resolved != null ? resolved : defaultValue;
   }
@@ -53,8 +63,12 @@ private static boolean isPresent(@Nullable String value) {
     return value != null && !value.isBlank();
   }
 
-  private static Map<String, String> readDotEnv() {
-    Path path = Paths.get(".env");
+  /**
+   * Reads a {@code .env}-style file: lines like {@code KEY=value}, {@code #} for comments,
+   * surrounding single or double quotes stripped. Package-private so tests can target an arbitrary
+   * {@link Path} (e.g. inside a JUnit {@code @TempDir}) instead of CWD.
+   */
+  static Map<String, String> readDotEnvFile(Path path) {
     if (!Files.isRegularFile(path)) {
       return Map.of();
     }

src/test/java/com/marketdata/sdk/internal/ConfigurationTest.java

@@ -0,0 +1,142 @@
+package com.marketdata.sdk.internal;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+import java.io.IOException;
+import java.lang.reflect.Constructor;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.util.Map;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.io.TempDir;
+
+class ConfigurationTest {
+
+  /**
+   * Reflection bridge to {@code Configuration}'s private constructor. Tests need to inject custom
+   * environment maps; production code cannot — that's the entire point of keeping the constructor
+   * private. Encapsulating the reflection here keeps individual tests clean.
+   */
+  private static Configuration newConfig(
+      Map<String, String> systemEnv, Map<String, String> dotEnv) {
+    try {
+      Constructor<Configuration> ctor =
+          Configuration.class.getDeclaredConstructor(Map.class, Map.class);
+      ctor.setAccessible(true);
+      return ctor.newInstance(systemEnv, dotEnv);
+    } catch (ReflectiveOperationException e) {
+      throw new IllegalStateException(
+          "Could not construct Configuration via reflection — has the private ctor signature"
+              + " changed?",
+          e);
+    }
+  }
+
+  @Test
+  void explicitWinsOverEverything() {
+    Configuration config =
+        newConfig(
+            Map.of("MARKETDATA_TOKEN", "from-env"), Map.of("MARKETDATA_TOKEN", "from-dotenv"));
+
+    assertThat(config.resolve("explicit-value", "MARKETDATA_TOKEN")).isEqualTo("explicit-value");
+  }
+
+  @Test
+  void envVarWinsOverDotEnv() {
+    Configuration config =
+        newConfig(
+            Map.of("MARKETDATA_TOKEN", "from-env"), Map.of("MARKETDATA_TOKEN", "from-dotenv"));
+
+    assertThat(config.resolve(null, "MARKETDATA_TOKEN")).isEqualTo("from-env");
+  }
+
+  @Test
+  void fallsBackToDotEnvWhenEnvVarMissing() {
+    Configuration config = newConfig(Map.of(), Map.of("MARKETDATA_TOKEN", "from-dotenv"));
+
+    assertThat(config.resolve(null, "MARKETDATA_TOKEN")).isEqualTo("from-dotenv");
+  }
+
+  @Test
+  void blankExplicitDoesNotCount() {
+    Configuration config = newConfig(Map.of("MARKETDATA_TOKEN", "from-env"), Map.of());
+
+    assertThat(config.resolve("   ", "MARKETDATA_TOKEN")).isEqualTo("from-env");
+  }
+
+  @Test
+  void blankEnvVarFallsThroughToDotEnv() {
+    Configuration config =
+        newConfig(Map.of("MARKETDATA_TOKEN", "  "), Map.of("MARKETDATA_TOKEN", "from-dotenv"));
+
+    assertThat(config.resolve(null, "MARKETDATA_TOKEN")).isEqualTo("from-dotenv");
+  }
+
+  @Test
+  void resolveReturnsNullWhenAllSourcesEmpty() {
+    Configuration config = newConfig(Map.of(), Map.of());
+
+    assertThat(config.resolve(null, "MARKETDATA_TOKEN")).isNull();
+  }
+
+  @Test
+  void resolveOrDefaultReturnsDefaultWhenAllEmpty() {
+    Configuration config = newConfig(Map.of(), Map.of());
+
+    assertThat(config.resolveOrDefault(null, "MARKETDATA_BASE_URL", "https://default"))
+        .isEqualTo("https://default");
+  }
+
+  @Test
+  void resolveOrDefaultPrefersResolvedValue() {
+    Configuration config = newConfig(Map.of("MARKETDATA_BASE_URL", "https://explicit"), Map.of());
+
+    assertThat(config.resolveOrDefault(null, "MARKETDATA_BASE_URL", "https://default"))
+        .isEqualTo("https://explicit");
+  }
+
+  // ---------- .env file parsing ----------
+
+  @Test
+  void readsAndParsesDotEnvFile(@TempDir Path tmp) throws IOException {
+    Path dotenv = tmp.resolve(".env");
+    Files.writeString(
+        dotenv,
+        """
+        # comment line — should be ignored
+        MARKETDATA_TOKEN=plain-token
+        MARKETDATA_BASE_URL="https://staging.example.com"
+        QUOTED_SINGLE='single-quoted'
+        EMPTY_VALUE=
+
+        # blank line above
+        BAD_LINE_NO_EQUALS
+        =BAD_LINE_NO_KEY
+        """);
+
+    Map<String, String> parsed = Configuration.readDotEnvFile(dotenv);
+
+    assertThat(parsed)
+        .containsEntry("MARKETDATA_TOKEN", "plain-token")
+        .containsEntry("MARKETDATA_BASE_URL", "https://staging.example.com")
+        .containsEntry("QUOTED_SINGLE", "single-quoted")
+        .containsEntry("EMPTY_VALUE", "")
+        .doesNotContainKey("# comment line — should be ignored")
+        .doesNotContainKey("BAD_LINE_NO_EQUALS");
+  }
+
+  @Test
+  void missingDotEnvReturnsEmpty(@TempDir Path tmp) {
+    assertThat(Configuration.readDotEnvFile(tmp.resolve(".env"))).isEmpty();
+  }
+
+  @Test
+  void dotEnvParsingIntegratesWithCascade(@TempDir Path tmp) throws IOException {
+    Path dotenv = tmp.resolve(".env");
+    Files.writeString(dotenv, "MARKETDATA_TOKEN=from-real-dotenv\n");
+
+    Configuration config = newConfig(Map.of(), Configuration.readDotEnvFile(dotenv));
+
+    assertThat(config.resolve(null, "MARKETDATA_TOKEN")).isEqualTo("from-real-dotenv");
+  }
+}