Harden response parsing and thread-safety; release v1.5.15

Response decoding now tolerates wrong-typed fields the same way it
already tolerated missing ones: a scalar field arriving as an
object/array, a numeric field (score, audio_id) arriving as a
non-numeric string, or a provider block arriving as a bare string all
degrade the affected field to null instead of failing the whole
response. Genuinely undecodable JSON, transport errors, and
status=error bodies still surface as before.

Sub-client accessors (streams, customCatalog, advanced) are now
synchronized so concurrent first access returns a single shared
instance.

Bump README install snippets and the SDK version to 1.5.15.

Author: AudD-music

README.md

@@ -17,7 +17,7 @@ Maven:
 <dependency>
   <groupId>io.audd</groupId>
   <artifactId>audd</artifactId>
-  <version>1.5.7</version>
+  <version>1.5.15</version>
 </dependency>
 ```
 
@@ -26,7 +26,7 @@ Get your API token at [dashboard.audd.io](https://dashboard.audd.io).
 Gradle (Kotlin DSL):
 
 ```kotlin
-implementation("io.audd:audd:1.5.7")
+implementation("io.audd:audd:1.5.15")
 ```
 
 Java 11+. Modular consumers: `requires io.audd;`.

pom.xml

@@ -6,7 +6,7 @@
 
   <groupId>io.audd</groupId>
   <artifactId>audd</artifactId>
-  <version>1.5.14</version>
+  <version>1.5.15</version>
   <packaging>jar</packaging>
 
   <name>AudD Java SDK</name>

src/main/java/io/audd/AudD.java

@@ -219,7 +219,7 @@ public List<EnterpriseMatch> recognizeEnterprise(Object source, EnterpriseOption
         return out;
     }
 
-    public Streams streams() {
+    public synchronized Streams streams() {
         if (streams == null) {
             streams = new Streams(http, readPolicy, mutatingPolicy, apiToken::get, onDeprecation, apiBase);
         }
@@ -250,7 +250,7 @@ public void setApiToken(String newToken) {
         enterpriseHttp.setApiToken(newToken);
     }
 
-    public CustomCatalog customCatalog() {
+    public synchronized CustomCatalog customCatalog() {
         if (customCatalog == null) {
             // Custom-catalog upload is metered. Auto-retry on a transport
             // failure could double-charge for the same audio fingerprinting,
@@ -266,7 +266,7 @@ public CustomCatalog customCatalog() {
         return customCatalog;
     }
 
-    public Advanced advanced() {
+    public synchronized Advanced advanced() {
         if (advanced == null) {
             // C2: Advanced uses RECOGNITION policy (find_lyrics is metered).
             advanced = new Advanced(http, recognitionPolicy, onDeprecation, apiBase);

src/main/java/io/audd/internal/Json.java

@@ -1,7 +1,14 @@
 package io.audd.internal;
 
+import com.fasterxml.jackson.core.JsonParser;
+import com.fasterxml.jackson.core.JsonToken;
+import com.fasterxml.jackson.databind.DeserializationContext;
 import com.fasterxml.jackson.databind.DeserializationFeature;
+import com.fasterxml.jackson.databind.JavaType;
 import com.fasterxml.jackson.databind.ObjectMapper;
+import com.fasterxml.jackson.databind.deser.DeserializationProblemHandler;
+
+import java.io.IOException;
 
 /**
  * Shared, leniently-configured {@link ObjectMapper} for all response parsing.
@@ -42,15 +49,97 @@ public static ObjectMapper mapper() {
      * </ul>
      */
     public static ObjectMapper newLenientMapper() {
-        return new ObjectMapper()
+        ObjectMapper mapper = new ObjectMapper()
             .configure(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES, false)
             .configure(DeserializationFeature.FAIL_ON_NULL_FOR_PRIMITIVES, false)
             .configure(DeserializationFeature.FAIL_ON_MISSING_CREATOR_PROPERTIES, false)
+            .configure(DeserializationFeature.FAIL_ON_INVALID_SUBTYPE, false)
             .configure(DeserializationFeature.FAIL_ON_NUMBERS_FOR_ENUMS, false)
             .configure(DeserializationFeature.READ_UNKNOWN_ENUM_VALUES_AS_NULL, true)
             .configure(DeserializationFeature.ACCEPT_SINGLE_VALUE_AS_ARRAY, true)
             .configure(DeserializationFeature.UNWRAP_SINGLE_VALUE_ARRAYS, true)
             .configure(DeserializationFeature.ACCEPT_EMPTY_STRING_AS_NULL_OBJECT, true)
             .configure(DeserializationFeature.ACCEPT_EMPTY_ARRAY_AS_NULL_OBJECT, true);
+        mapper.addHandler(lenientProblemHandler());
+        return mapper;
+    }
+
+    /**
+     * A last line of defence for shape drift that the feature flags above don't
+     * cover: a field typed as a scalar arriving as an object/array (e.g.
+     * {@code spotify.name} as an object), a numeric field arriving as a
+     * non-numeric string ({@code score}/{@code audio_id} as {@code "n/a"}), a
+     * provider block arriving as a bare string, or an object key that can't be
+     * coerced. In every such case we skip the offending value and degrade the
+     * field to {@code null} instead of letting the whole response fail to
+     * decode. Only genuinely undecodable JSON, transport errors, {@code
+     * status=error} bodies, and caller-input errors are allowed to surface.
+     */
+    private static DeserializationProblemHandler lenientProblemHandler() {
+        return new DeserializationProblemHandler() {
+            /** Scalar-typed field arriving as an object/array (or any wrong token). */
+            @Override
+            public Object handleUnexpectedToken(DeserializationContext ctxt, JavaType targetType,
+                                                JsonToken t, JsonParser p, String failureMsg) throws IOException {
+                skipCurrentValue(p, t);
+                return null;
+            }
+
+            /** Numeric field arriving as a non-numeric string ({@code "n/a"}). */
+            @Override
+            public Object handleWeirdStringValue(DeserializationContext ctxt, Class<?> targetType,
+                                                 String valueToConvert, String failureMsg) {
+                return null;
+            }
+
+            /** String field arriving as a number that can't be coerced, etc. */
+            @Override
+            public Object handleWeirdNativeValue(DeserializationContext ctxt, JavaType targetType,
+                                                 Object valueToConvert, JsonParser p) {
+                return null;
+            }
+
+            /** A number that overflows / can't map to the target numeric type. */
+            @Override
+            public Object handleWeirdNumberValue(DeserializationContext ctxt, Class<?> targetType,
+                                                 Number valueToConvert, String failureMsg) {
+                return null;
+            }
+
+            /** A map key that can't be coerced to the key type — drop that entry. */
+            @Override
+            public Object handleWeirdKey(DeserializationContext ctxt, Class<?> rawKeyType,
+                                         String keyValue, String failureMsg) {
+                return null;
+            }
+
+            /** Concrete type has no usable constructor for the incoming shape. */
+            @Override
+            public Object handleMissingInstantiator(DeserializationContext ctxt, Class<?> instClass,
+                                                    com.fasterxml.jackson.databind.deser.ValueInstantiator valueInsta,
+                                                    JsonParser p, String msg) throws IOException {
+                skipCurrentValue(p, p.currentToken());
+                return null;
+            }
+
+            /** Construction of a value threw — degrade rather than propagate. */
+            @Override
+            public Object handleInstantiationProblem(DeserializationContext ctxt, Class<?> instClass,
+                                                     Object argument, Throwable t) {
+                return null;
+            }
+        };
+    }
+
+    /**
+     * Advance the parser past the value currently under the cursor so decoding
+     * of sibling fields can continue. For a START_OBJECT/START_ARRAY this skips
+     * the whole subtree; for a scalar the cursor already sits on the value and
+     * needs no further advance.
+     */
+    private static void skipCurrentValue(JsonParser p, JsonToken t) throws IOException {
+        if (t == JsonToken.START_OBJECT || t == JsonToken.START_ARRAY) {
+            p.skipChildren();
+        }
     }
 }

src/main/java/io/audd/internal/UserAgent.java

@@ -2,7 +2,7 @@
 
 /** SDK identifier sent on every request. */
 public final class UserAgent {
-    public static final String SDK_VERSION = "1.5.14";
+    public static final String SDK_VERSION = "1.5.15";
 
     private UserAgent() {}
 

src/test/java/io/audd/AudDTest.java

@@ -194,4 +194,14 @@ void hierarchicalSubclients_areLazilyCreated() {
         assertThat(audd.customCatalog()).isNotNull();
         assertThat(audd.advanced()).isNotNull();
     }
+
+    @Test
+    void offsetToSeconds_parsesOffsetsOverOneHour() {
+        // "01:02:03" -> 1h 2m 3s = 3723s. Regression: hours must be honoured.
+        assertThat(AudD.offsetToSeconds("01:02:03")).isEqualTo(3723.0);
+        assertThat(AudD.offsetToSeconds("10:00:00")).isEqualTo(36000.0);
+        assertThat(AudD.offsetToSeconds("00:42")).isEqualTo(42.0);
+        assertThat(AudD.offsetToSeconds("90")).isEqualTo(90.0);
+        assertThat(AudD.offsetToSeconds("garbage")).isNull();
+    }
 }

src/test/java/io/audd/models/EnterpriseLenientParseTest.java

@@ -74,4 +74,62 @@ void enterpriseResponse_withEmptyAndAbsentArrays_doesNotThrow() {
             assertThat(c.songs()).isNull();
         }).doesNotThrowAnyException();
     }
+
+    @Test
+    void enterpriseSong_withScoreAsNonNumericString_degradesToNull() throws Exception {
+        // score wired as a non-numeric string must degrade to null, not throw.
+        String json = "{\"songs\":[{\"artist\":\"x\",\"title\":\"y\",\"score\":\"n/a\"}]}";
+
+        EnterpriseChunkResult chunk = M.readValue(json, EnterpriseChunkResult.class);
+        EnterpriseMatch m = chunk.songs().get(0);
+        assertThat(m.artist()).isEqualTo("x");
+        assertThat(m.score()).isNull();
+    }
+
+    @Test
+    void enterpriseSong_withProviderBlockAsString_degradesAndKeepsSiblings() throws Exception {
+        // A nested provider-shaped field arriving as a bare string is skipped;
+        // the rest of the song still decodes.
+        String json = "{\"songs\":[{\"artist\":\"x\",\"title\":\"y\","
+            + "\"start_offset\":1500,\"apple_music\":\"unavailable\"}]}";
+
+        EnterpriseChunkResult chunk = M.readValue(json, EnterpriseChunkResult.class);
+        EnterpriseMatch m = chunk.songs().get(0);
+        assertThat(m.title()).isEqualTo("y");
+        assertThat(m.startOffset()).isEqualTo(1500);
+    }
+
+    @Test
+    void recognitionResult_withAudioIdAsNonNumericString_degradesToNull() throws Exception {
+        String json = "{\"artist\":\"a\",\"title\":\"t\",\"audio_id\":\"not-a-number\"}";
+
+        RecognitionResult r = M.readValue(json, RecognitionResult.class);
+        assertThat(r.artist()).isEqualTo("a");
+        assertThat(r.audioId()).isNull();
+    }
+
+    @Test
+    void recognitionResult_withSpotifyNameAsObject_degradesFieldNotWholeBlock() throws Exception {
+        // spotify.name (a String field) arrives as an object: skip the offending
+        // value, keep the rest of the spotify block and the outer result.
+        String json = "{\"artist\":\"a\",\"title\":\"t\",\"spotify\":{"
+            + "\"id\":\"abc123\",\"name\":{\"unexpected\":\"object\"},\"popularity\":77}}";
+
+        RecognitionResult r = M.readValue(json, RecognitionResult.class);
+        assertThat(r.title()).isEqualTo("t");
+        assertThat(r.spotify()).isNotNull();
+        assertThat(r.spotify().name()).isNull();
+        assertThat(r.spotify().id).isEqualTo("abc123");
+        assertThat(r.spotify().popularity).isEqualTo(77);
+    }
+
+    @Test
+    void recognitionResult_withSpotifyBlockAsString_degradesToNull() throws Exception {
+        // Whole spotify object typed as a scalar arriving as a string.
+        String json = "{\"artist\":\"a\",\"title\":\"t\",\"spotify\":\"n/a\"}";
+
+        RecognitionResult r = M.readValue(json, RecognitionResult.class);
+        assertThat(r.artist()).isEqualTo("a");
+        assertThat(r.spotify()).isNull();
+    }
 }