add NPE validation to RequestHeaders

Author: MarketDataDev03

CHANGELOG.md

@@ -16,6 +16,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   literal value `abc # prod`, which passes `validateApiKey` (printable ASCII)
   and surfaces later as a confusing `AuthenticationError` far from the .env
   source that caused it.
+- `RequestHeaders` canonical constructor now rejects a `null` `headers` map
+  with a clear `NullPointerException` naming the field, replacing the bare
+  `Map.copyOf(null)` NPE that left consumers hunting for the offending
+  argument. The wire-format deserializer additionally intercepts a top-level
+  JSON `null` body via `JsonDeserializer#getNullValue` and surfaces it as a
+  `ParseError` carrying the endpoint URL, status, and request id — preventing
+  a malformed `/headers/` response from manifesting as an opaque NPE further
+  down the call stack.
 
 ### Added
 - Project scaffold per ADRs 001–007: Gradle Kotlin DSL build, JDK 17 toolchain,

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

@@ -4,6 +4,7 @@
 import com.fasterxml.jackson.core.type.TypeReference;
 import com.fasterxml.jackson.databind.DeserializationContext;
 import com.fasterxml.jackson.databind.JsonDeserializer;
+import com.fasterxml.jackson.databind.JsonMappingException;
 import com.marketdata.sdk.utilities.RequestHeaders;
 import java.io.IOException;
 import java.util.Map;
@@ -14,6 +15,14 @@
  * record at the Jackson layer rather than via an annotation on the record (per ADR-007: response
  * records don't carry {@code @JsonDeserialize}; deserializers register programmatically on the
  * parser's {@code ObjectMapper}).
+ *
+ * <p>A literal JSON {@code null} body — or any other path that would leave the parser holding a
+ * {@code null} map — is short-circuited to a {@link JsonMappingException} so {@link
+ * JsonResponseParser} surfaces it as a {@link com.marketdata.sdk.exception.ParseError} with the
+ * request's URL/status/id attached. Without the guard, Jackson would return {@code null} from the
+ * top-level {@code readValue} (via {@link #getNullValue}, its standard null-routing seam) and the
+ * NPE would surface much later — uncaught by the parser's {@code catch (IOException)} and far less
+ * useful to a consumer trying to diagnose a malformed response.
  */
 final class RequestHeadersDeserializer extends JsonDeserializer<RequestHeaders> {
 
@@ -22,6 +31,25 @@ final class RequestHeadersDeserializer extends JsonDeserializer<RequestHeaders>
   @Override
   public RequestHeaders deserialize(JsonParser p, DeserializationContext ctxt) throws IOException {
     Map<String, String> raw = p.readValueAs(MAP_OF_STRINGS);
+    if (raw == null) {
+      // Defense in depth: a top-level JSON null is intercepted by getNullValue(ctxt) below before
+      // deserialize() is ever called, so this branch is reachable only via a pathological future
+      // Jackson behavior. Better to fail with a clean JsonMappingException than to let the null
+      // reach the record's requireNonNull and bypass the parser's IOException catch.
+      throw JsonMappingException.from(p, "expected a JSON object for /headers/ body, got null map");
+    }
     return new RequestHeaders(raw);
   }
+
+  /**
+   * Jackson routes a top-level JSON {@code null} through this seam instead of calling {@link
+   * #deserialize}. Default behavior returns {@code null}; we instead throw so the wire-null case
+   * produces a {@link com.marketdata.sdk.exception.ParseError} with the endpoint URL in scope,
+   * matching the failure shape of any other malformed body.
+   */
+  @Override
+  public RequestHeaders getNullValue(DeserializationContext ctxt) throws JsonMappingException {
+    throw JsonMappingException.from(
+        ctxt, "expected a JSON object for /headers/ body, got JSON null");
+  }
 }

src/main/java/com/marketdata/sdk/utilities/RequestHeaders.java

@@ -1,6 +1,7 @@
 package com.marketdata.sdk.utilities;
 
 import java.util.Map;
+import java.util.Objects;
 
 /**
  * Response shape for {@code GET /headers/} — the request headers echoed back by the server (with
@@ -10,11 +11,16 @@
  * surfaces them.
  *
  * @param headers all headers the server received, lower-cased keys to values. The map is
- *     defensively copied and immutable.
+ *     defensively copied and immutable. Never {@code null} — the package is {@code @NullMarked},
+ *     and the canonical constructor rejects a {@code null} argument with a {@link
+ *     NullPointerException} naming the field. The wire-format deserializer pre-checks for a JSON
+ *     {@code null} token and surfaces a {@link com.marketdata.sdk.exception.ParseError} instead, so
+ *     consumers never see a bare NPE from the wire path.
  */
 public record RequestHeaders(Map<String, String> headers) {
 
   public RequestHeaders {
+    Objects.requireNonNull(headers, "headers");
     headers = Map.copyOf(headers);
   }
 }

src/test/java/com/marketdata/sdk/RequestHeadersTest.java

@@ -0,0 +1,60 @@
+package com.marketdata.sdk;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
+
+import com.marketdata.sdk.utilities.RequestHeaders;
+import java.util.HashMap;
+import java.util.Map;
+import org.junit.jupiter.api.Test;
+
+/**
+ * Focused tests for the {@link RequestHeaders} record's canonical constructor. The wire-level path
+ * (a server returning a JSON-{@code null} body) is exercised end-to-end in {@link
+ * UtilitiesResourceTest}; this class documents the public-API contract that consumers see when
+ * constructing the record directly.
+ */
+class RequestHeadersTest {
+
+  @Test
+  void constructorRejectsNullMapWithNamedFieldMessage() {
+    // The package is @NullMarked, so `null` violates the public contract. Pre-checking with
+    // requireNonNull yields a clear "headers" message; without it, Map.copyOf(null) throws a bare
+    // NPE that leaves the consumer hunting for which constructor argument was null.
+    assertThatThrownBy(() -> new RequestHeaders(null))
+        .isInstanceOf(NullPointerException.class)
+        .hasMessageContaining("headers");
+  }
+
+  @Test
+  void constructorAcceptsEmptyMap() {
+    // An empty map is a legitimate (if unusual) value — Map.copyOf preserves emptiness and the
+    // result is still immutable.
+    RequestHeaders rh = new RequestHeaders(Map.of());
+
+    assertThat(rh.headers()).isEmpty();
+  }
+
+  @Test
+  void constructorDefensivelyCopiesTheInputMap() {
+    // Map.copyOf snapshots the input. A consumer mutating the original after construction must
+    // not be able to mutate the record's view — this is the defensive-copy guarantee the Javadoc
+    // promises.
+    Map<String, String> mutable = new HashMap<>();
+    mutable.put("accept", "*/*");
+    RequestHeaders rh = new RequestHeaders(mutable);
+
+    mutable.put("authorization", "Bearer leaked");
+
+    assertThat(rh.headers()).containsOnlyKeys("accept");
+  }
+
+  @Test
+  void headersAccessorReturnsImmutableView() {
+    // The Map.copyOf result is unmodifiable; consumers attempting to mutate get UOE rather than
+    // silently corrupting the record's invariant.
+    RequestHeaders rh = new RequestHeaders(Map.of("accept", "*/*"));
+
+    assertThat(rh.headers()).isUnmodifiable();
+  }
+}

src/test/java/com/marketdata/sdk/UtilitiesResourceTest.java

@@ -274,6 +274,25 @@ void headersSyncUnwrapsAuthenticationFailureFromCompletionException() {
     assertThatThrownBy(utilities::headers).isInstanceOf(AuthenticationError.class);
   }
 
+  /**
+   * A literal JSON {@code null} body for {@code /headers/} must surface as a {@link
+   * com.marketdata.sdk.exception.ParseError} carrying the request URL, status, and id — never as a
+   * raw {@code NullPointerException} from the {@link RequestHeaders} canonical constructor. The
+   * {@link RequestHeadersDeserializer} pre-check converts the null token into a {@code
+   * JsonMappingException}, which {@link JsonResponseParser} wraps with the support context.
+   */
+  @Test
+  void headersJsonNullBodySurfacesParseErrorNotNpe() {
+    CapturingClient client =
+        new CapturingClient(200, "null".getBytes(), HttpHeaders.of(Map.of(), (a, b) -> true));
+    UtilitiesResource utilities = resourceWith(client);
+
+    assertThatThrownBy(utilities::headers)
+        .isInstanceOf(com.marketdata.sdk.exception.ParseError.class)
+        .hasMessageContaining("/headers/")
+        .hasMessageContaining("JSON null");
+  }
+
   // ---------- stub HttpClient ----------
 
   private static final class CapturingClient extends TestHttpClients.StubHttpClient {