Support the UFC CDN response contract

Author: leoromanovsky

products/feature-flagging/feature-flagging-api/README.md

@@ -88,13 +88,16 @@ OTEL_EXPORTER_OTLP_PROTOCOL=grpc
 - `DD_FEATURE_FLAGS_CONFIGURATION_SOURCE=agentless` uses the Datadog agentless
   backend. Set `DD_FEATURE_FLAGS_CONFIGURATION_SOURCE_AGENTLESS_BASE_URL` to a
   different HTTP backend while keeping agentless delivery semantics. A bare
-  host uses the standard server-distribution path; a URL with a path is used as
+  host uses the standard rules-based server path; a URL with a path is used as
   the exact UFC endpoint. Configured URLs are opaque: the SDK does not add the
   Datadog-managed `dd_env` query parameter, so custom backends must include any
   required tenant or environment scope in the configured URL. The derived
-  Datadog-managed endpoint is intended for supported commercial sites; use an
-  explicit base URL elsewhere. Agentless responses do not have an SDK-imposed
-  payload-size limit. `remote_config` uses the existing Agent Remote
+  Datadog-managed endpoint is
+  `https://ufc-server.ff-cdn.<site>/api/v2/feature-flagging/config/rules-based/server`
+  and expects UFC under the JSON:API `data.attributes` response member. It is
+  intended for supported commercial sites; use an explicit base URL elsewhere.
+  Agentless responses do not have an SDK-imposed payload-size limit.
+  `remote_config` uses the existing Agent Remote
   Configuration path. `offline` is reserved for startup-provided UFC bytes;
   until those bytes are implemented, no network source starts and evaluations
   use defaults.

products/feature-flagging/feature-flagging-lib/src/main/java/com/datadog/featureflag/AgentlessConfigurationSource.java

@@ -35,9 +35,8 @@
 final class AgentlessConfigurationSource implements ConfigurationSourceService {
   private static final Logger LOGGER = LoggerFactory.getLogger(AgentlessConfigurationSource.class);
 
-  // TODO before merge: confirm the final backend route with the server-distribution API owners.
-  private static final String DATADOG_API_SERVER_DISTRIBUTION_PATH =
-      "/api/v2/feature-flagging/config/server-distribution";
+  private static final String DATADOG_UFC_RULES_BASED_SERVER_PATH =
+      "/api/v2/feature-flagging/config/rules-based/server";
   private static final int MAX_ATTEMPTS = 3;
   private static final int MINUTES_BETWEEN_WARNINGS = 5;
   private static final long FIRST_RETRY_MIN_MILLIS = 2_000;
@@ -255,8 +254,9 @@ private boolean apply(final UfcHttpResponse response) {
     final ServerConfiguration configuration;
     try {
       configuration =
-          RemoteConfigServiceImpl.UniversalFlagConfigDeserializer.INSTANCE.deserialize(
-              response.body);
+          RemoteConfigServiceImpl.UniversalFlagConfigDeserializer.INSTANCE.deserializeApiResponse(
+              response.body,
+              config.getFeatureFlaggingConfigurationSourceAgentlessBaseUrl() != null);
     } catch (final IOException | RuntimeException e) {
       LOGGER.debug("Feature Flagging HTTP configuration source returned malformed UFC payload", e);
       return false;
@@ -295,7 +295,7 @@ private static HttpUrl endpointFromConfiguredBaseUrl(final String configuredBase
     if ("/".equals(parsed.encodedPath()) || parsed.encodedPath().isEmpty()) {
       return parsed
           .newBuilder()
-          .addPathSegments(DATADOG_API_SERVER_DISTRIBUTION_PATH.substring(1))
+          .addPathSegments(DATADOG_UFC_RULES_BASED_SERVER_PATH.substring(1))
           .build();
     }
     return parsed;
@@ -305,8 +305,8 @@ private static HttpUrl datadogApiServerDistributionEndpoint(final Config config)
     final HttpUrl.Builder endpoint =
         new HttpUrl.Builder()
             .scheme("https")
-            .host("api." + config.getSite())
-            .addPathSegments(DATADOG_API_SERVER_DISTRIBUTION_PATH.substring(1));
+            .host("ufc-server.ff-cdn." + config.getSite())
+            .addPathSegments(DATADOG_UFC_RULES_BASED_SERVER_PATH.substring(1));
     final String env = config.getEnv();
     if (env != null && !env.isEmpty()) {
       endpoint.addQueryParameter("dd_env", env);

products/feature-flagging/feature-flagging-lib/src/main/java/com/datadog/featureflag/RemoteConfigServiceImpl.java

@@ -66,17 +66,47 @@ public void accept(
   static class UniversalFlagConfigDeserializer
       implements ConfigurationDeserializer<ServerConfiguration> {
 
+    private static final String UNIVERSAL_FLAG_CONFIGURATION_TYPE = "universal-flag-configuration";
     static final UniversalFlagConfigDeserializer INSTANCE = new UniversalFlagConfigDeserializer();
 
     private static final Moshi MOSHI =
         new Moshi.Builder().add(Date.class, new DateAdapter()).add(FlagMapAdapter.FACTORY).build();
     private static final JsonAdapter<ServerConfiguration> V1_ADAPTER =
         MOSHI.adapter(ServerConfiguration.class);
+    private static final Type API_RESPONSE_TYPE =
+        Types.newParameterizedType(Map.class, String.class, Object.class);
+    private static final JsonAdapter<Map<String, Object>> API_RESPONSE_ADAPTER =
+        MOSHI.adapter(API_RESPONSE_TYPE);
 
     @Override
     public ServerConfiguration deserialize(final byte[] content) throws IOException {
       return V1_ADAPTER.fromJson(Okio.buffer(Okio.source(new ByteArrayInputStream(content))));
     }
+
+    @Nullable
+    ServerConfiguration deserializeApiResponse(
+        final byte[] content, final boolean allowRawConfiguration) throws IOException {
+      final Map<String, Object> response =
+          API_RESPONSE_ADAPTER.fromJson(
+              Okio.buffer(Okio.source(new ByteArrayInputStream(content))));
+      if (response != null && response.containsKey("data")) {
+        final Object data = response.get("data");
+        if (!(data instanceof Map)) {
+          return null;
+        }
+        final Map<?, ?> dataAttributes = (Map<?, ?>) data;
+        return UNIVERSAL_FLAG_CONFIGURATION_TYPE.equals(dataAttributes.get("type"))
+            ? validConfiguration(V1_ADAPTER.fromJsonValue(dataAttributes.get("attributes")))
+            : null;
+      }
+      return allowRawConfiguration ? validConfiguration(deserialize(content)) : null;
+    }
+
+    @Nullable
+    private static ServerConfiguration validConfiguration(
+        @Nullable final ServerConfiguration configuration) {
+      return configuration != null && configuration.flags != null ? configuration : null;
+    }
   }
 
   static class FlagMapAdapter extends JsonAdapter<Map<String, Flag>> {

products/feature-flagging/feature-flagging-lib/src/test/java/com/datadog/featureflag/AgentlessConfigurationSourceTest.java

@@ -51,7 +51,7 @@
 
 @ExtendWith(MockitoExtension.class)
 class AgentlessConfigurationSourceTest {
-  private static final String CONFIG_PATH = "/api/v2/feature-flagging/config/server-distribution";
+  private static final String CONFIG_PATH = "/api/v2/feature-flagging/config/rules-based/server";
 
   @Mock private FeatureFlaggingGateway.ConfigListener listener;
 
@@ -62,33 +62,33 @@ void cleanup() {
   }
 
   @Test
-  void derivesDatadogApiServerDistributionEndpointFromSiteAndEnv() {
+  void derivesDatadogUfcCdnEndpointFromSiteAndEnv() {
     final Config config = config("datad0g.com", "staging env");
 
     assertEquals(
-        "https://api.datad0g.com/api/v2/feature-flagging/config/server-distribution?dd_env=staging%20env",
+        "https://ufc-server.ff-cdn.datad0g.com/api/v2/feature-flagging/config/rules-based/server?dd_env=staging%20env",
         AgentlessConfigurationSource.endpoint(config).toString());
   }
 
   @Test
-  void derivesDatadogApiServerDistributionEndpointWithoutEnv() {
+  void derivesDatadogUfcCdnEndpointWithoutEnv() {
     assertEquals(
-        "https://api.datadoghq.com/api/v2/feature-flagging/config/server-distribution",
+        "https://ufc-server.ff-cdn.datadoghq.com/api/v2/feature-flagging/config/rules-based/server",
         AgentlessConfigurationSource.endpoint(config("datadoghq.com", "")).toString());
     assertEquals(
-        "https://api.datadoghq.com/api/v2/feature-flagging/config/server-distribution",
+        "https://ufc-server.ff-cdn.datadoghq.com/api/v2/feature-flagging/config/rules-based/server",
         AgentlessConfigurationSource.endpoint(config("datadoghq.com", null)).toString());
   }
 
   @Test
-  void appendsServerDistributionPathToConfiguredAgentlessBaseUrl() {
+  void appendsRulesBasedServerPathToConfiguredAgentlessBaseUrl() {
     final Config config = config();
     lenient()
         .when(config.getFeatureFlaggingConfigurationSourceAgentlessBaseUrl())
         .thenReturn("http://mock-backend:8080");
 
     assertEquals(
-        "http://mock-backend:8080/api/v2/feature-flagging/config/server-distribution",
+        "http://mock-backend:8080/api/v2/feature-flagging/config/rules-based/server",
         AgentlessConfigurationSource.endpoint(config).toString());
   }
 
@@ -116,7 +116,7 @@ void rejectsInvalidConfiguredAgentlessBaseUrl() {
   }
 
   @Test
-  void rejectsInvalidDatadogApiServerDistributionEndpoint() {
+  void rejectsInvalidDatadogUfcCdnEndpoint() {
     assertThrows(
         IllegalArgumentException.class,
         () -> AgentlessConfigurationSource.endpoint(config("datadoghq.com:bad", "")));
@@ -359,18 +359,43 @@ void realHttpClientTimesOutDelayedResponse() throws Exception {
   }
 
   @Test
-  void appliesAcceptedUfcThroughGatewayAndSendsApiKey() throws Exception {
+  void appliesAcceptedJsonApiUfcThroughGatewayAndSendsApiKey() throws Exception {
     final FakeClient client = new FakeClient(response(200, "etag-a", emptyConfig()));
     final AgentlessConfigurationSource service = service(client);
+    final ArgumentCaptor<ServerConfiguration> configuration =
+        ArgumentCaptor.forClass(ServerConfiguration.class);
     FeatureFlaggingGateway.addConfigListener(listener);
 
     assertTrue(service.pollOnce());
 
-    verify(listener).accept(any(ServerConfiguration.class));
+    verify(listener).accept(configuration.capture());
+    assertEquals("2026-07-15T19:57:07.219869778Z", configuration.getValue().createdAt);
+    assertNull(configuration.getValue().format);
+    assertEquals("Staging", configuration.getValue().environment.name);
+    assertTrue(configuration.getValue().flags.isEmpty());
     assertEquals("test-api-key", client.requests.get(0).apiKey);
     assertNull(client.requests.get(0).etag);
   }
 
+  @Test
+  void appliesRawUfcFromConfiguredCompatibilityEndpoint() throws Exception {
+    final FakeClient client = new FakeClient(response(200, "etag-a", emptyConfigAttributes()));
+    final Config config = config();
+    lenient()
+        .when(config.getFeatureFlaggingConfigurationSourceAgentlessBaseUrl())
+        .thenReturn("http://compatibility-backend/custom/ufc");
+    final AgentlessConfigurationSource service = service(client, config);
+    final ArgumentCaptor<ServerConfiguration> configuration =
+        ArgumentCaptor.forClass(ServerConfiguration.class);
+    FeatureFlaggingGateway.addConfigListener(listener);
+
+    assertTrue(service.pollOnce());
+
+    verify(listener).accept(configuration.capture());
+    assertEquals("Staging", configuration.getValue().environment.name);
+    assertTrue(configuration.getValue().flags.isEmpty());
+  }
+
   @Test
   void ignoresBlankEtag() throws Exception {
     final FakeClient client =
@@ -486,10 +511,19 @@ void rejectsForbiddenNonOkMissingBodyAndNullConfiguration() throws Exception {
             response(404, null, null),
             response(600, null, null),
             response(200, null, null),
-            response(200, null, "null"));
+            response(200, null, "null"),
+            response(200, null, jsonApiResponse("other-configuration", emptyConfigAttributes())),
+            response(200, null, "{\"data\":null}"),
+            response(
+                200, null, "{\"data\":{\"id\":\"1\",\"type\":\"universal-flag-configuration\"}}"),
+            response(200, null, emptyConfigAttributes()));
     final AgentlessConfigurationSource service = service(client);
     FeatureFlaggingGateway.addConfigListener(listener);
 
+    assertFalse(service.pollOnce());
+    assertFalse(service.pollOnce());
+    assertFalse(service.pollOnce());
+    assertFalse(service.pollOnce());
     assertFalse(service.pollOnce());
     assertFalse(service.pollOnce());
     assertFalse(service.pollOnce());
@@ -902,6 +936,16 @@ private static AgentlessConfigurationSource service(final FakeClient client) {
     return service(client, delay -> {}, () -> 1.0);
   }
 
+  private static AgentlessConfigurationSource service(
+      final FakeClient client, final Config config) {
+    return new AgentlessConfigurationSource(
+        HttpUrl.get("http://localhost" + CONFIG_PATH),
+        config,
+        30_000,
+        client,
+        Executors.newSingleThreadScheduledExecutor());
+  }
+
   private static AgentlessConfigurationSource service(
       final FakeClient client,
       final AgentlessConfigurationSource.RetrySleeper retrySleeper,
@@ -943,19 +987,32 @@ private static AgentlessConfigurationSource.UfcHttpResponse response(
   }
 
   private static String emptyConfig() {
+    return jsonApiResponse("universal-flag-configuration", emptyConfigAttributes());
+  }
+
+  private static String emptyConfigAttributes() {
     return "{"
-        + "\"createdAt\":\"2024-04-17T19:40:53.716Z\","
-        + "\"format\":\"SERVER\","
-        + "\"environment\":{\"name\":\"Test\"},"
+        + "\"createdAt\":\"2026-07-15T19:57:07.219869778Z\","
+        + "\"environment\":{\"name\":\"Staging\"},"
         + "\"flags\":{}"
         + "}";
   }
 
+  private static String jsonApiResponse(final String type, final String attributes) {
+    return "{\"data\":{"
+        + "\"id\":\"1\","
+        + "\"type\":\""
+        + type
+        + "\","
+        + "\"attributes\":"
+        + attributes
+        + "}}";
+  }
+
   private static String largeConfig(final int flagCount) {
     final StringBuilder json =
         new StringBuilder(
-            "{\"createdAt\":\"2024-04-17T19:40:53.716Z\","
-                + "\"format\":\"SERVER\","
+            "{\"createdAt\":\"2026-07-15T19:57:07.219869778Z\","
                 + "\"environment\":{\"name\":\"Large Test\"},"
                 + "\"flags\":{");
     for (int index = 0; index < flagCount; index++) {
@@ -972,7 +1029,7 @@ private static String largeConfig(final int flagCount) {
                   + "\"variations\":{\"on\":{\"key\":\"on\",\"value\":\"on\"}},"
                   + "\"allocations\":[]}");
     }
-    return json.append("}}").toString();
+    return jsonApiResponse("universal-flag-configuration", json.append("}}").toString());
   }
 
   private static void awaitCalls(final FakeClient client, final int count) throws Exception {