Add policyUUIDs to request struct, plus fix deserialization bug (#42)

1. Migrate from deprecated config field to policy in text scan requests
2. Add policyUUIDs field to text scan request struct. Current maximum supported length is 1, support for more coming in the future.
3. Fix bug with Jackson ObjectMapper -- we should be ignoring unrecognized fields.

Author: evanfuller

src/main/java/ai/nightfall/scan/NightfallClient.java

@@ -14,6 +14,7 @@
 import ai.nightfall.scan.model.ScanTextResponse;
 import ai.nightfall.scan.model.UploadFileChunkRequest;
 import com.fasterxml.jackson.core.JsonProcessingException;
+import com.fasterxml.jackson.databind.DeserializationFeature;
 import com.fasterxml.jackson.databind.ObjectMapper;
 import okhttp3.Call;
 import okhttp3.ConnectionPool;
@@ -43,7 +44,8 @@
  */
 public class NightfallClient implements Closeable {
 
-    private static final ObjectMapper objectMapper = new ObjectMapper();
+    private static final ObjectMapper objectMapper = new ObjectMapper()
+            .configure(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES, false);
     private static final long wakeupDurationMillis = Duration.ofSeconds(15).toMillis();
     private static final int DEFAULT_RETRY_COUNT = 5;
     private static final String API_HOST = "https://api.nightfall.ai";

src/main/java/ai/nightfall/scan/model/DetectorMetadata.java

@@ -1,5 +1,6 @@
 package ai.nightfall.scan.model;
 
+import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
 import com.fasterxml.jackson.annotation.JsonProperty;
 
 import java.util.UUID;
@@ -8,6 +9,7 @@
  * A container for minimal information representing a detector. A detector may be uniquely identified by its UUID;
  * the name field helps provide human-readability.
  */
+@JsonIgnoreProperties(ignoreUnknown = true)
 public class DetectorMetadata {
 
     @JsonProperty("name")

src/main/java/ai/nightfall/scan/model/Finding.java

@@ -1,5 +1,6 @@
 package ai.nightfall.scan.model;
 
+import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
 import com.fasterxml.jackson.annotation.JsonProperty;
 
 import java.util.List;
@@ -8,6 +9,7 @@
 /**
  * An object representing an occurrence of a configured detector (i.e. finding) in the provided data.
  */
+@JsonIgnoreProperties(ignoreUnknown = true)
 public class Finding {
     @JsonProperty("finding")
     private String finding;

src/main/java/ai/nightfall/scan/model/Location.java

@@ -1,10 +1,12 @@
 package ai.nightfall.scan.model;
 
+import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
 import com.fasterxml.jackson.annotation.JsonProperty;
 
 /**
  * An object representing where a finding was discovered in content.
  */
+@JsonIgnoreProperties(ignoreUnknown = true)
 public class Location {
 
     @JsonProperty("byteRange")

src/main/java/ai/nightfall/scan/model/ScanFileResponse.java

@@ -1,12 +1,14 @@
 package ai.nightfall.scan.model;
 
+import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
 import com.fasterxml.jackson.annotation.JsonProperty;
 
 import java.util.UUID;
 
 /**
  * The object returned by the Nightfall API when an (asynchronous) file scan request was successfully triggered.
  */
+@JsonIgnoreProperties(ignoreUnknown = true)
 public class ScanFileResponse {
 
     @JsonProperty("id")

src/main/java/ai/nightfall/scan/model/ScanTextRequest.java

@@ -3,6 +3,7 @@
 import com.fasterxml.jackson.annotation.JsonProperty;
 
 import java.util.List;
+import java.util.UUID;
 
 /**
  * An object representing a request to scan inline plaintext with the Nightfall API.
@@ -11,19 +12,34 @@ public class ScanTextRequest {
     @JsonProperty("payload")
     private List<String> payload;
 
-    @JsonProperty("config")
-    private ScanTextConfig config;
+    @JsonProperty("policy")
+    private ScanTextConfig policy;
+
+    @JsonProperty("policyUUIDs")
+    private List<UUID> policyUUIDs;
 
     /**
      * Create a request to scan the provided <code>payload</code> against the provided scanning
-     * configuration <code>config</code>.
+     * <code>policy</code>.
+     *
+     * @param payload the content to scan
+     * @param policy the configuration to use to scan the content
+     */
+    public ScanTextRequest(List<String> payload, ScanTextConfig policy) {
+        this.payload = payload;
+        this.policy = policy;
+    }
+
+    /**
+     * Create a request to scan the provided <code>payload</code> against the provided
+     * <code>policyUUIDs</code>.
      *
      * @param payload the content to scan
-     * @param config the configuration to use to scan the content
+     * @param policyUUIDs a list of UUIDs referring to pre-created policies to-be-used when scanning. Maximum 1.
      */
-    public ScanTextRequest(List<String> payload, ScanTextConfig config) {
+    public ScanTextRequest(List<String> payload, List<UUID> policyUUIDs) {
         this.payload = payload;
-        this.config = config;
+        this.policyUUIDs = policyUUIDs;
     }
 
     /**
@@ -45,20 +61,56 @@ public void setPayload(List<String> payload) {
     }
 
     /**
-     * Get the request scan configuration.
+     * Get the request scan policy. Same as <code>getPolicy</code>, just provided for backwards compatibility.
      *
      * @return the configuration to use to scan the <code>payload</code> data
      */
     public ScanTextConfig getConfig() {
-        return config;
+        return getPolicy();
     }
 
     /**
-     * Set the request scan configuration.
+     * Get the request scan policy.
+     *
+     * @return the configuration to use to scan the <code>payload</code> data
+     */
+    public ScanTextConfig getPolicy() {
+        return policy;
+    }
+
+    /**
+     * Set the request scan policy. Same as <code>setPolicy</code>, just provided for backwards compatibility.
      *
      * @param config the configuration to use to scan the <code>payload</code> data
      */
     public void setConfig(ScanTextConfig config) {
-        this.config = config;
+        setPolicy(config);
+    }
+
+    /**
+     * Set the request scan policy.
+     *
+     * @param policy the configuration to use to scan the <code>payload</code> data
+     */
+    public void setPolicy(ScanTextConfig policy) {
+        this.policy = policy;
+    }
+
+    /**
+     * Get the policy UUIDs to use when performing a scan.
+     *
+     * @return the policy UUIDs.
+     */
+    public List<UUID> getPolicyUUIDs() {
+        return policyUUIDs;
+    }
+
+    /**
+     * Set the policy UUIDs to use when performing a scan.
+     *
+     * @param policyUUIDs the policy UUIDs.
+     */
+    public void setPolicyUUIDs(List<UUID> policyUUIDs) {
+        this.policyUUIDs = policyUUIDs;
     }
 }

src/main/java/ai/nightfall/scan/model/ScanTextResponse.java

@@ -1,5 +1,6 @@
 package ai.nightfall.scan.model;
 
+import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
 import com.fasterxml.jackson.annotation.JsonProperty;
 
 import java.util.List;
@@ -9,6 +10,7 @@
  * corresponds one-to-one with the input request <code>payload</code>, so all findings stored in a given sub-list
  * refer to matches that occurred in the <code>i</code>th index of the request payload.
  */
+@JsonIgnoreProperties(ignoreUnknown = true)
 public class ScanTextResponse {
     @JsonProperty("findings")
     private List<List<Finding>> findings;

src/test/java/ai/nightfall/scan/NightfallClientTest.java

@@ -58,6 +58,24 @@ public void testScanText_HappyPath() {
         }
     }
 
+    @Test
+    public void testScanText_IgnoresUnrecognizedProperties() {
+        try (MockWebServer server = new MockWebServer()) {
+            // deserializer should not throw an exception just because of the unrecognized key `foo`
+            server.enqueue(new MockResponse().setBody("{\"findings\": [[]], \"foo\": \"bar\"}"));
+
+            List<List<Finding>> expectedFindings = Arrays.asList(Collections.emptyList());
+            NightfallClient c = new NightfallClient(getRequestURL(server), "key", 1, getHttpClient());
+            RedactionConfig defRedCfg = new RedactionConfig(new SubstitutionConfig("REDACTED"));
+            ScanTextConfig cfg = new ScanTextConfig(Arrays.asList(UUID.fromString("c08c6c43-85ca-40e5-8f46-7d1cf1e176a3")), Collections.emptyList(), 20, defRedCfg);
+            ScanTextRequest req = new ScanTextRequest(null, cfg);
+            ScanTextResponse resp = c.scanText(req);
+            assertEquals(expectedFindings, resp.getFindings());
+        } catch (IOException e) {
+            fail("IOException during test: " + e.getMessage());
+        }
+    }
+
     @Test
     public void testScanText_NullRequestArg() {
         assertThrows(IllegalArgumentException.class, () -> {
@@ -80,7 +98,7 @@ public MockResponse dispatch(@NotNull RecordedRequest r) {
                 });
 
                 NightfallClient c = new NightfallClient(getRequestURL(server), "key", 1, getHttpClient());
-                ScanTextRequest req = new ScanTextRequest(null, null);
+                ScanTextRequest req = new ScanTextRequest(null, (ScanTextConfig) null);
                 c.scanText(req);
                 fail("did not expect scanText to succeed");
             } catch (IOException e) {
@@ -109,7 +127,7 @@ public MockResponse dispatch(@NotNull RecordedRequest r) {
 
             List<List<Finding>> expectedFindings = Arrays.asList(Arrays.asList());
             NightfallClient c = new NightfallClient(getRequestURL(server), "key", 1, getHttpClient());
-            ScanTextRequest req = new ScanTextRequest(null, null);
+            ScanTextRequest req = new ScanTextRequest(null, (ScanTextConfig) null);
             ScanTextResponse resp = c.scanText(req);
             assertEquals(expectedFindings, resp.getFindings());
             assertEquals(reqCount[0], 3); // validate that rate limit responses were actually returned
@@ -135,7 +153,7 @@ public void testScanText_InternalException() {
                         .build().url().toString();
 
                 NightfallClient c = new NightfallClient(serverURL, "key", 1, getHttpClient());
-                ScanTextRequest req = new ScanTextRequest(null, null);
+                ScanTextRequest req = new ScanTextRequest(null, (ScanTextConfig) null);
                 c.scanText(req);
                 fail("did not expect scanText to succeed");
             } catch (IOException e) {
@@ -173,7 +191,7 @@ public MockResponse dispatch(@NotNull RecordedRequest r) {
                         .build().url().toString();
 
                 NightfallClient c = new NightfallClient(serverURL, "key", 1, getHttpClient());
-                ScanTextRequest req = new ScanTextRequest(null, null);
+                ScanTextRequest req = new ScanTextRequest(null, (ScanTextConfig) null);
                 c.scanText(req);
                 fail("did not expect scanText to succeed");
             } catch (IOException e) {