Validate supported fields for xDS

it/xds-client/src/test/resources/META-INF/services/com.linecorp.armeria.xds.validator.XdsValidatorIndex

@@ -0,0 +1 @@
+com.linecorp.armeria.xds.api.StrictXdsValidatorIndex

it/xds-no-validation/src/test/java/com/linecorp/armeria/xds/it/NoopXdsValidatorIndex.java

@@ -16,11 +16,14 @@
 
 package com.linecorp.armeria.xds.it;
 
+import com.google.protobuf.Message;
+
 import com.linecorp.armeria.xds.validator.XdsValidatorIndex;
 
 public class NoopXdsValidatorIndex implements XdsValidatorIndex {
+
     @Override
-    public void assertValid(Object message) {
+    public void assertValid(Message message) {
     }
 
     @Override

xds-api/src/main/java/com/linecorp/armeria/xds/api/DefaultXdsValidatorIndex.java

@@ -16,40 +16,36 @@
 
 package com.linecorp.armeria.xds.api;
 
+import static java.util.Objects.requireNonNull;
+
+import com.google.protobuf.Message;
+
 import com.linecorp.armeria.common.annotation.UnstableApi;
 import com.linecorp.armeria.xds.validator.XdsValidatorIndex;
 
-import io.envoyproxy.pgv.ReflectiveValidatorIndex;
-import io.envoyproxy.pgv.ValidationException;
-import io.envoyproxy.pgv.Validator;
-import io.envoyproxy.pgv.ValidatorIndex;
-
 /**
- * The default validator which uses reflection in conjunction with pgv to validate messages.
+ * The default validator which applies pgv (protoc-gen-validate) structural validation
+ * and warns usage of unsupported fields.
  */
 @UnstableApi
-public final class DefaultXdsValidatorIndex implements ValidatorIndex, XdsValidatorIndex {
+public final class DefaultXdsValidatorIndex implements XdsValidatorIndex {
+
+    private static final DefaultXdsValidatorIndex INSTANCE = new DefaultXdsValidatorIndex();
 
-    private final ValidatorIndex delegate;
+    private final PgvValidator pgvValidator = PgvValidator.of();
+    private final SupportedFieldValidator supportedFieldValidator = SupportedFieldValidator.of();
 
     /**
-     * Creates a validator.
+     * Returns the default singleton instance.
      */
-    public DefaultXdsValidatorIndex() {
-        delegate = new ReflectiveValidatorIndex();
-    }
-
-    @Override
-    public <T> Validator<T> validatorFor(Class clazz) {
-        return delegate.validatorFor(clazz);
+    public static DefaultXdsValidatorIndex of() {
+        return INSTANCE;
     }
 
     @Override
-    public void assertValid(Object message) {
-        try {
-            validatorFor(message).assertValid(message);
-        } catch (ValidationException e) {
-            throw new IllegalArgumentException(e);
-        }
+    public void assertValid(Message message) {
+        requireNonNull(message, "message");
+        pgvValidator.assertValid(message);
+        supportedFieldValidator.validate(message);
     }
 }

xds-api/src/main/java/com/linecorp/armeria/xds/api/PgvValidator.java

@@ -0,0 +1,59 @@
+/*
+ * Copyright 2025 LY Corporation
+ *
+ * LY Corporation licenses this file to you under the Apache License,
+ * version 2.0 (the "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at:
+ *
+ *   https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+ * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+ * License for the specific language governing permissions and limitations
+ * under the License.
+ */
+
+package com.linecorp.armeria.xds.api;
+
+import com.google.protobuf.Message;
+
+import com.linecorp.armeria.common.annotation.UnstableApi;
+import com.linecorp.armeria.xds.validator.XdsValidationException;
+
+import io.envoyproxy.pgv.ReflectiveValidatorIndex;
+import io.envoyproxy.pgv.ValidationException;
+import io.envoyproxy.pgv.ValidatorIndex;
+
+/**
+ * Validates xDS protobuf messages using pgv (protoc-gen-validate) structural validation.
+ */
+@UnstableApi
+public final class PgvValidator {
+
+    private static final PgvValidator INSTANCE = new PgvValidator();
+
+    private final ValidatorIndex delegate = new ReflectiveValidatorIndex();
+
+    private PgvValidator() {}
+
+    /**
+     * Returns the singleton {@link PgvValidator} instance.
+     */
+    public static PgvValidator of() {
+        return INSTANCE;
+    }
+
+    /**
+     * Validates the given message using pgv structural validation.
+     *
+     * @throws XdsValidationException if validation fails
+     */
+    public void assertValid(Message message) {
+        try {
+            delegate.validatorFor(message).assertValid(message);
+        } catch (ValidationException e) {
+            throw XdsValidationException.of(message, e);
+        }
+    }
+}

xds-api/src/main/java/com/linecorp/armeria/xds/api/StrictXdsValidatorIndex.java

@@ -0,0 +1,64 @@
+/*
+ * Copyright 2025 LY Corporation
+ *
+ * LY Corporation licenses this file to you under the Apache License,
+ * version 2.0 (the "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at:
+ *
+ *   https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+ * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+ * License for the specific language governing permissions and limitations
+ * under the License.
+ */
+
+package com.linecorp.armeria.xds.api;
+
+import static java.util.Objects.requireNonNull;
+
+import java.util.ArrayList;
+import java.util.List;
+
+import com.google.protobuf.Message;
+
+import com.linecorp.armeria.common.annotation.UnstableApi;
+import com.linecorp.armeria.xds.validator.XdsValidationException;
+import com.linecorp.armeria.xds.validator.XdsValidatorIndex;
+
+/**
+ * A strict {@link XdsValidatorIndex} that composes pgv (protoc-gen-validate) structural validation
+ * with supported-field validation. All unsupported field violations are collected and reported
+ * together in a single {@link XdsValidationException}.
+ *
+ * <p>This validator is intended for use in test environments via SPI to catch unsupported
+ * field usage early. Its {@link #priority()} is {@code 1}, which is higher than
+ * {@link DefaultXdsValidatorIndex} ({@code 0}), so it wins SPI selection when present
+ * on the classpath.
+ */
+@UnstableApi
+public final class StrictXdsValidatorIndex implements XdsValidatorIndex {
+
+    private final PgvValidator pgvValidator = PgvValidator.of();
+
+    @Override
+    public void assertValid(Message message) {
+        requireNonNull(message, "message");
+        pgvValidator.assertValid(message);
+        final List<String> violations = new ArrayList<>();
+        final SupportedFieldValidator validator =
+                SupportedFieldValidator.of((descriptorName, fieldPath, value) ->
+                        violations.add(descriptorName + ": " + fieldPath));
+        validator.validate(message);
+        if (!violations.isEmpty()) {
+            throw XdsValidationException.of(
+                    message, "Unsupported xDS fields detected: " + String.join(", ", violations));
+        }
+    }
+
+    @Override
+    public int priority() {
+        return 1;
+    }
+}

xds-api/src/main/java/com/linecorp/armeria/xds/api/SupportedFieldValidator.java

@@ -37,13 +37,22 @@
 import com.linecorp.armeria.common.annotation.UnstableApi;
 
 /**
- * Validates protobuf messages against the {@code (armeria.xds.supported)} field annotation.
- * Any set field that lacks the annotation is reported as an unsupported field violation.
- * The validator walks recursively into supported message-typed fields.
+ * Validates protobuf messages against the {@code (armeria.xds.supported.field)} and
+ * {@code (armeria.xds.supported.oneof_field)} annotations. Any set field whose number is not listed
+ * is reported as an unsupported field violation. The validator walks recursively into supported
+ * message-typed fields.
  *
- * <p>Currently, supported fields are annotated inline on each field declaration in the proto files, e.g.:
+ * <p>Supported fields are annotated in the proto files, e.g.:
  * <pre>{@code
- * string exact = 1 [(armeria.xds.supported) = true];
+ * message Address {
+ *   option (armeria.xds.supported.field) = 2;
+ *   string address = 2;
+ *
+ *   oneof port_specifier {
+ *     option (armeria.xds.supported.oneof_field) = 3;
+ *     uint32 port_value = 3;
+ *   }
+ * }
  * }</pre>
  */
 @UnstableApi
@@ -162,7 +171,10 @@ private void validateFieldValue(FieldDescriptor fd, Object value,
     }
 
     private static boolean unsupportedEnumValue(EnumValueDescriptor ev) {
-        return !ev.getOptions().getExtension(SupportedFieldProto.supportedValue);
+        final List<Integer> supportedValues =
+                ev.getType().getOptions().getExtension(SupportedFieldProto.supported.enumValue);
+        // If no enum values are annotated, treat as "no opinion" — skip validation.
+        return !supportedValues.isEmpty() && !supportedValues.contains(ev.getNumber());
     }
 
     private static boolean unsupportedPackage(String pkg) {
@@ -171,9 +183,15 @@ private static boolean unsupportedPackage(String pkg) {
 
     private Set<FieldDescriptor> supportedFields(Descriptors.Descriptor descriptor) {
         return supportedFieldsCache.computeIfAbsent(descriptor, d -> {
+            final Set<Integer> supportedNumbers = new HashSet<>(
+                    d.getOptions().getExtension(SupportedFieldProto.supported.field));
+            for (Descriptors.OneofDescriptor oneof : d.getOneofs()) {
+                supportedNumbers.addAll(
+                        oneof.getOptions().getExtension(SupportedFieldProto.supported.oneofField));
+            }
             final Set<FieldDescriptor> result = new HashSet<>();
             for (FieldDescriptor fd : d.getFields()) {
-                if (fd.getOptions().getExtension(SupportedFieldProto.supported)) {
+                if (supportedNumbers.contains(fd.getNumber())) {
                     result.add(fd);
                 }
             }

xds-api/src/main/java/com/linecorp/armeria/xds/api/UnsupportedFieldHandler.java

@@ -20,6 +20,7 @@
 import static java.util.Objects.requireNonNull;
 
 import com.linecorp.armeria.common.annotation.UnstableApi;
+import com.linecorp.armeria.xds.validator.XdsValidationException;
 
 /**
  * A handler that is invoked when unsupported xDS fields are detected in a protobuf message.
@@ -59,11 +60,11 @@ static UnsupportedFieldHandler warn() {
     }
 
     /**
-     * Returns a handler that throws an {@link IllegalArgumentException} on the first unsupported field.
+     * Returns a handler that throws an {@link XdsValidationException} on the first unsupported field.
      */
     static UnsupportedFieldHandler reject() {
         return (descriptorName, fieldPath, value) -> {
-            throw new IllegalArgumentException(
+            throw XdsValidationException.of(
                     "Unsupported xDS field detected in " + descriptorName + ": " + fieldPath);
         };
     }

xds-api/src/main/proto/armeria/xds/supported.proto

@@ -6,11 +6,26 @@ option java_outer_classname = "SupportedFieldProto";
 
 import "google/protobuf/descriptor.proto";
 
-extend google.protobuf.FieldOptions {
-  optional bool supported = 50000;
-}
+// Enclosing message so that option usage reads as
+// `(armeria.xds.supported.field)`, `(armeria.xds.supported.oneof_field)`,
+// and `(armeria.xds.supported.enum_value)`.
+message supported {
+  extend google.protobuf.MessageOptions {
+    // Field numbers of supported fields in this message.
+    // Place each `option (armeria.xds.supported.field) = <field_number>;`
+    // directly above the corresponding field declaration.
+    repeated int32 field = 50000;
+  }
+
+  extend google.protobuf.OneofOptions {
+    // Field numbers of supported oneof members.
+    // Place each `option (armeria.xds.supported.oneof_field) = <field_number>;`
+    // directly above the corresponding field inside a oneof block.
+    repeated int32 oneof_field = 50000;
+  }
 
-extend google.protobuf.EnumValueOptions {
-  // Distinct name from the FieldOptions extension to avoid Java codegen name collision.
-  optional bool supported_value = 50000;
+  extend google.protobuf.EnumOptions {
+    // Enum value numbers of supported values in this enum.
+    repeated int32 enum_value = 50000;
+  }
 }

xds-api/src/main/proto/envoy/config/bootstrap/v3/bootstrap.proto

@@ -29,6 +29,8 @@ import "udpa/annotations/status.proto";
 import "udpa/annotations/versioning.proto";
 import "validate/validate.proto";
 
+import "armeria/xds/supported.proto";
+
 option java_package = "io.envoyproxy.envoy.config.bootstrap.v3";
 option java_outer_classname = "BootstrapProto";
 option java_multiple_files = true;
@@ -52,16 +54,19 @@ message Bootstrap {
 
     // Static :ref:`Listeners <envoy_v3_api_msg_config.listener.v3.Listener>`. These listeners are
     // available regardless of LDS configuration.
+    option (armeria.xds.supported.field) = 1;
     repeated listener.v3.Listener listeners = 1;
 
     // If a network based configuration source is specified for :ref:`cds_config
     // <envoy_v3_api_field_config.bootstrap.v3.Bootstrap.DynamicResources.cds_config>`, it's necessary
     // to have some initial cluster definitions available to allow Envoy to know
     // how to speak to the management server.
+    option (armeria.xds.supported.field) = 2;
     repeated cluster.v3.Cluster clusters = 2;
 
     // These static secrets can be used by :ref:`SdsSecretConfig
     // <envoy_v3_api_msg_extensions.transport_sockets.tls.v3.SdsSecretConfig>`
+    option (armeria.xds.supported.field) = 3;
     repeated envoy.extensions.transport_sockets.tls.v3.Secret secrets = 3;
   }
 
@@ -74,6 +79,7 @@ message Bootstrap {
 
     // All :ref:`Listeners <envoy_v3_api_msg_config.listener.v3.Listener>` are provided by a single
     // :ref:`LDS <arch_overview_dynamic_config_lds>` configuration source.
+    option (armeria.xds.supported.field) = 1;
     core.v3.ConfigSource lds_config = 1;
 
     // xdstp:// resource locator for listener collection.
@@ -83,6 +89,7 @@ message Bootstrap {
     // All post-bootstrap :ref:`Cluster <envoy_v3_api_msg_config.cluster.v3.Cluster>` definitions are
     // provided by a single :ref:`CDS <arch_overview_dynamic_config_cds>`
     // configuration source.
+    option (armeria.xds.supported.field) = 2;
     core.v3.ConfigSource cds_config = 2;
 
     // xdstp:// resource locator for cluster collection.
@@ -96,6 +103,7 @@ message Bootstrap {
     // :ref:`ConfigSources <envoy_v3_api_msg_config.core.v3.ConfigSource>` that have
     // the :ref:`ads <envoy_v3_api_field_config.core.v3.ConfigSource.ads>` field set will be
     // streamed on the ADS channel.
+    option (armeria.xds.supported.field) = 3;
     core.v3.ApiConfigSource ads_config = 3;
   }
 
@@ -147,6 +155,7 @@ message Bootstrap {
 
   // Node identity to present to the management server and for instance
   // identification purposes (e.g. in generated headers).
+  option (armeria.xds.supported.field) = 1;
   core.v3.Node node = 1;
 
   // A list of :ref:`Node <envoy_v3_api_msg_config.core.v3.Node>` field names
@@ -184,13 +193,16 @@ message Bootstrap {
   repeated string node_context_params = 26;
 
   // Statically specified resources.
+  option (armeria.xds.supported.field) = 2;
   StaticResources static_resources = 2;
 
   // xDS configuration sources.
+  option (armeria.xds.supported.field) = 3;
   DynamicResources dynamic_resources = 3;
 
   // Configuration for the cluster manager which owns all upstream clusters
   // within the server.
+  option (armeria.xds.supported.field) = 4;
   ClusterManager cluster_manager = 4;
 
   // Health discovery service config option.
@@ -485,6 +497,7 @@ message ClusterManager {
   // <envoy_v3_api_field_config.bootstrap.v3.Bootstrap.StaticResources.clusters>`. This is unrelated to
   // the :option:`--service-cluster` option which does not `affect zone aware
   // routing <https://github.com/envoyproxy/envoy/issues/774>`_.
+  option (armeria.xds.supported.field) = 1;
   string local_cluster_name = 1;
 
   // Optional global configuration for outlier detection.