fix(directory): align Directory facets

Author: nkavian

odp-directory/README.md

@@ -50,8 +50,8 @@ either InFlow or Solana through MPP. A payment filter with no options matches an
 advertises that payment protocol.
 
 The response includes structured facets for enrollment protocols, keywords, operations, payment
-protocols, and payment options. Use them to refine a user or Agent query without downloading a
-global vocabulary.
+protocols, payment options, and trust protocols. Use them to refine a user or Agent query without
+downloading a global vocabulary.
 
 Compatible results may advertise protocol names unknown to this library. The client filters those
 descriptors and preserves recognized enrollment, payment, and trust descriptors, including TAP.

odp-directory/src/main/java/org/offeringprotocol/odp/directory/DirectoryClient.java

@@ -178,7 +178,14 @@ static DirectoryModels.SearchPage decodeSearchPage(String json) {
             if (value == null) {
                 throw new IllegalArgumentException("Directory response is empty");
             }
-            return OdpJson.treeToValue(value, DirectoryModels.SearchPage.class);
+            DirectoryModels.SearchPage page = OdpJson.treeToValue(value, DirectoryModels.SearchPage.class);
+            if (page.facets() != null
+                    && page.facets().trust().stream()
+                            .anyMatch(facet -> facet.value() == null
+                                    || !"tap".equals(facet.value().name()))) {
+                throw new IllegalArgumentException("Directory trust facets are invalid");
+            }
+            return page;
         } catch (IllegalArgumentException exception) {
             throw new IllegalArgumentException("Directory response is invalid", exception);
         }

odp-directory/src/main/java/org/offeringprotocol/odp/directory/DirectoryModels.java

@@ -2,6 +2,7 @@
 
 import com.fasterxml.jackson.annotation.JsonAnyGetter;
 import com.fasterxml.jackson.annotation.JsonAnySetter;
+import com.fasterxml.jackson.annotation.JsonInclude;
 import com.fasterxml.jackson.annotation.JsonProperty;
 import java.time.Instant;
 import java.util.Collections;
@@ -24,16 +25,33 @@ public record SearchRequest(String query, ServiceFilters filters, Integer limit)
         }
     }
 
+    @JsonInclude(JsonInclude.Include.NON_EMPTY)
     public record ServiceFilters(
             List<ServiceDocument.EnrollmentProtocol> enrollment,
             List<String> keywords,
             List<OperationFilter> operations,
-            List<PaymentFilter> payments) {
+            List<PaymentFilter> payments,
+            List<ServiceDocument.TrustProtocol> trust) {
+        public ServiceFilters(
+                List<ServiceDocument.EnrollmentProtocol> enrollment,
+                List<String> keywords,
+                List<OperationFilter> operations,
+                List<PaymentFilter> payments) {
+            this(enrollment, keywords, operations, payments, null);
+        }
+
         public ServiceFilters {
+            if (trust != null
+                    && (trust.size() != 1
+                            || trust.get(0) == null
+                            || !"tap".equals(trust.get(0).name()))) {
+                throw new IllegalArgumentException("trust must contain exactly one tap descriptor");
+            }
             enrollment = enrollment == null ? List.of() : List.copyOf(enrollment);
             keywords = keywords == null ? List.of() : List.copyOf(keywords);
             operations = operations == null ? List.of() : List.copyOf(operations);
             payments = payments == null ? List.of() : List.copyOf(payments);
+            trust = trust == null ? List.of() : List.copyOf(trust);
         }
     }
 
@@ -77,13 +95,24 @@ public record Facets(
             List<Facet<String>> keywords,
             List<Facet<OperationDescriptor>> operations,
             List<Facet<ServiceDocument.PaymentProtocol>> payments,
-            @JsonProperty("payment_options") List<Facet<PaymentOptionFacetValue>> paymentOptions) {
+            @JsonProperty("payment_options") List<Facet<PaymentOptionFacetValue>> paymentOptions,
+            List<Facet<ServiceDocument.TrustProtocol>> trust) {
+        public Facets(
+                List<Facet<ServiceDocument.EnrollmentProtocol>> enrollment,
+                List<Facet<String>> keywords,
+                List<Facet<OperationDescriptor>> operations,
+                List<Facet<ServiceDocument.PaymentProtocol>> payments,
+                List<Facet<PaymentOptionFacetValue>> paymentOptions) {
+            this(enrollment, keywords, operations, payments, paymentOptions, null);
+        }
+
         public Facets {
             enrollment = enrollment == null ? List.of() : List.copyOf(enrollment);
             keywords = keywords == null ? List.of() : List.copyOf(keywords);
             operations = operations == null ? List.of() : List.copyOf(operations);
             payments = payments == null ? List.of() : List.copyOf(payments);
             paymentOptions = paymentOptions == null ? List.of() : List.copyOf(paymentOptions);
+            trust = trust == null ? List.of() : List.copyOf(trust);
         }
     }
 

odp-directory/src/test/java/org/offeringprotocol/odp/directory/DirectoryClientTest.java

@@ -4,8 +4,10 @@
 import static org.junit.jupiter.api.Assertions.assertNull;
 import static org.junit.jupiter.api.Assertions.assertThrows;
 
+import java.util.Collections;
 import java.util.List;
 import org.junit.jupiter.api.Test;
+import org.offeringprotocol.odp.core.OdpJson;
 import org.offeringprotocol.odp.core.ServiceDocument;
 
 class DirectoryClientTest {
@@ -23,6 +25,24 @@ void selectsOnlyCanonicalEnvironments() {
     @Test
     void rejectsInvalidSearchLimitsBeforeTransport() {
         assertThrows(IllegalArgumentException.class, () -> new DirectoryModels.SearchRequest("plants", null, 101));
+        assertThrows(
+                IllegalArgumentException.class,
+                () -> new DirectoryModels.ServiceFilters(
+                        null, null, null, null, List.of(new ServiceDocument.TrustProtocol("mpp"))));
+        assertThrows(
+                IllegalArgumentException.class,
+                () -> new DirectoryModels.ServiceFilters(null, null, null, null, List.of()));
+        assertThrows(
+                IllegalArgumentException.class,
+                () -> new DirectoryModels.ServiceFilters(null, null, null, null, Collections.singletonList(null)));
+    }
+
+    @Test
+    void omitsUnusedFiltersFromRequests() {
+        DirectoryModels.ServiceFilters filters = new DirectoryModels.ServiceFilters(
+                null, List.of("gpu"), null, null, List.of(new ServiceDocument.TrustProtocol("tap")));
+
+        assertEquals("{\"keywords\":[\"gpu\"],\"trust\":[{\"name\":\"tap\"}]}", OdpJson.write(filters));
     }
 
     @Test
@@ -53,4 +73,20 @@ void filtersUnknownProtocolsFromDirectoryResults() {
         assertNull(protocols.enrollment());
         assertNull(page.items().get(1).protocols());
     }
+
+    @Test
+    void decodesTypedTrustFacets() {
+        DirectoryModels.SearchPage page = DirectoryClient.decodeSearchPage("""
+                {"items":[],"facets":{"trust":[{"value":{"name":"tap"},"count":2}]}}
+                """);
+
+        assertEquals(
+                List.of(new DirectoryModels.Facet<>(new ServiceDocument.TrustProtocol("tap"), 2)),
+                page.facets().trust());
+
+        assertThrows(
+                IllegalArgumentException.class,
+                () -> DirectoryClient.decodeSearchPage(
+                        "{\"items\":[],\"facets\":{\"trust\":[{\"value\":{\"name\":\"mpp\"},\"count\":2}]}}"));
+    }
 }