Normalize Fee extension XML tags in EPP response (#2953)

* Normalize Fee extension XML tags in EPP response

Nomulus currently supports multiple versions of the Fee extensions. Our
current tooling requires that each version must use a unique namespace
tag, e.g., fee11, fee12, etc.

Some client registrars are sensitive to the tag literal used by the
version of the extension they use. For example, a few registrars
currently using v0.6 have requested that the `fee` literal be used
on the versions they currently use. With registrars upgrading at their
own schedule, this kind of requests are impossible to satisfy.

This PR instroduces a namespace normalizer class for EPP responses. The
key optimization is that each EPP response never mixes multiple versions
of a service extension. Therefore we can define a canonical tag for each
extension, and change the tag of the extension in use in a response to
that. This normalizer only handles Fee extensions right now, but the
idea can be extended to others if use cases come up.

This normalizer will be applied to all flows in a future PR.

* Addressing reviews

* A faster implementation with regex.

b/478848482

Author: weiminyu

core/src/main/java/google/registry/flows/FeeExtensionXmlTagNormalizer.java

@@ -0,0 +1,128 @@
+// Copyright 2026 The Nomulus Authors. All Rights Reserved.
+//
+// Licensed 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
+//
+//     http://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 google.registry.flows;
+
+package google.registry.flows;
+
+import static google.registry.model.eppcommon.ProtocolDefinition.ServiceExtension.FEE_0_11;
+import static google.registry.model.eppcommon.ProtocolDefinition.ServiceExtension.FEE_0_12;
+import static google.registry.model.eppcommon.ProtocolDefinition.ServiceExtension.FEE_0_6;
+import static google.registry.model.eppcommon.ProtocolDefinition.ServiceExtension.FEE_1_00;
+
+import com.google.common.annotations.VisibleForTesting;
+import com.google.common.collect.ImmutableSet;
+import google.registry.model.eppcommon.EppXmlTransformer;
+import google.registry.model.eppcommon.ProtocolDefinition.ServiceExtension;
+import java.util.Optional;
+import java.util.regex.Matcher;
+import java.util.regex.Pattern;
+import java.util.stream.Collectors;
+
+/**
+ * Normalizes Fee extension namespace tags in EPP XML response messages.
+ *
+ * <p>Nomulus currently supports multiple versions of the Fee extension. With the current XML
+ * tooling, the namespace of every version is included in each EPP response, and as a result must
+ * use a unique XML tag. E.g., fee for extension v0.6, and fee12 for extension v0.12.
+ *
+ * <p>Some registrars are not XML namespace-aware and rely on the XML tags being specific literals.
+ * This makes it difficult to perform seamless rollout of new versions: if Nomulus reassigns a tag
+ * literal to a different version, it effectively forces all these registrars to upgrade at the time
+ * of the deployment.
+ *
+ * <p>This class can be used to normalize the namespace tag in EPP responses. Since every response
+ * message may use at most one version of the Fee extension, we can remove declared but unused
+ * versions from the message, thus freeing up the canonical tag ('fee') for the active version.
+ */
+public class FeeExtensionXmlTagNormalizer {
+
+  // So far we only have Fee extensions to process
+  private static final String CANONICAL_FEE_TAG = "fee";
+
+  private static final ImmutableSet<ServiceExtension> FEE_EXTENSIONS =
+      ImmutableSet.of(FEE_0_6, FEE_0_11, FEE_0_12, FEE_1_00);
+
+  private static final Pattern FEE_EXTENSION_IN_USE_PATTERN =
+      Pattern.compile(feeExtensionInUseRegex());
+
+  @VisibleForTesting
+  static String feeExtensionInUseRegex() {
+    return FEE_EXTENSIONS.stream()
+        .map(ServiceExtension::getXmlTag)
+        .map(tag -> String.format("\\b(%s):", tag))
+        .collect(Collectors.joining("|"));
+  }
+
+  /**
+   * Returns a EPP response that uses the canonical tag ({@code fee}) for the fee extension.
+   *
+   * <p>This method replaces any versioned tag, e.g., {@code fee12} with the canonical tag. It also
+   * removes unused namespace declarations and update the tag in the remaining declaration.
+   *
+   * <p>The input {@code xml} must be an EPP response message generated by the {@link
+   * EppXmlTransformer}. With this assumption, we can use regular expressions which is 10X faster
+   * than XML stream parsers.
+   */
+  public static String normalize(String xml) {
+    Optional<String> maybeFeeTagInUse = findFeeExtensionInUse(xml);
+    if (maybeFeeTagInUse.isEmpty()) {
+      return xml;
+    }
+    String feeTagInUse = maybeFeeTagInUse.get();
+    String normalized = xml;
+    for (ServiceExtension serviceExtension : FEE_EXTENSIONS) {
+      if (serviceExtension.getXmlTag().equals(feeTagInUse)) {
+        normalized = normalizeExtensionInUse(feeTagInUse, serviceExtension.getUri(), normalized);
+      } else {
+        normalized =
+            removeUnusedExtension(
+                serviceExtension.getXmlTag(), serviceExtension.getUri(), normalized);
+      }
+    }
+    return normalized;
+  }
+
+  static String removeUnusedExtension(String tag, String uri, String xml) {
+    String declaration = String.format("xmlns:%s=\"%s\"", tag, uri);
+    // There must be a leading whitespace, and it can be safely removed with the declaration.
+    return xml.replaceAll(String.format("\\s%s", declaration), "");
+  }
+
+  static String normalizeExtensionInUse(String tagInUse, String uriInUse, String xml) {
+    if (tagInUse.equals(CANONICAL_FEE_TAG)) {
+      return xml;
+    }
+    // Change the tag in the namespace declaration:
+    String currentDeclaration = String.format("xmlns:%s=\"%s\"", tagInUse, uriInUse);
+    String desiredDeclaraion = String.format("xmlns:fee=\"%s\"", uriInUse);
+    // The new tag at each site of use, with trailing colon:
+    String newTagWithColon = CANONICAL_FEE_TAG + ":";
+    return xml.replaceAll(String.format("\\b%s:", tagInUse), newTagWithColon)
+        .replaceAll(currentDeclaration, desiredDeclaraion);
+  }
+
+  static Optional<String> findFeeExtensionInUse(String xml) {
+    Matcher matcher = FEE_EXTENSION_IN_USE_PATTERN.matcher(xml);
+
+    if (!matcher.find()) {
+      return Optional.empty();
+    }
+    // We know only one extension is in use, so we can return on the first match
+    for (int i = 1; i <= matcher.groupCount(); i++) {
+      if (matcher.group(i) != null) {
+        return Optional.of(matcher.group(i));
+      }
+    }
+    throw new IllegalStateException("Should not reach here. Bad FEE_EXTENSION_IN_USE_PATTERN?");
+  }
+}

core/src/main/java/google/registry/model/eppcommon/ProtocolDefinition.java

@@ -18,6 +18,7 @@
 import static com.google.common.collect.Maps.uniqueIndex;
 
 import com.google.common.annotations.VisibleForTesting;
+import com.google.common.base.VerifyException;
 import com.google.common.collect.ImmutableMap;
 import com.google.common.collect.ImmutableSet;
 import google.registry.model.domain.fee06.FeeCheckCommandExtensionV06;
@@ -87,6 +88,7 @@ public enum ServiceExtension {
     private final Class<? extends CommandExtension> commandExtensionClass;
     private final Class<? extends ResponseExtension> responseExtensionClass;
     private final String uri;
+    private final String xmlTag;
     private final ServiceExtensionVisibility visibility;
 
     ServiceExtension(
@@ -96,6 +98,7 @@ public enum ServiceExtension {
       this.commandExtensionClass = commandExtensionClass;
       this.responseExtensionClass = responseExtensionClass;
       this.uri = getCommandExtensionUri(commandExtensionClass);
+      this.xmlTag = getCommandExtensionXmlTag(commandExtensionClass);
       this.visibility = visibility;
     }
 
@@ -111,11 +114,27 @@ public String getUri() {
       return uri;
     }
 
+    public String getXmlTag() {
+      return xmlTag;
+    }
+
     /** Returns the namespace URI of the command extension class. */
     public static String getCommandExtensionUri(Class<? extends CommandExtension> clazz) {
       return clazz.getPackage().getAnnotation(XmlSchema.class).namespace();
     }
 
+    /** Returns the XML tag for this extension in the response message. */
+    public static String getCommandExtensionXmlTag(Class<? extends CommandExtension> clazz) {
+      var xmlSchema = clazz.getPackage().getAnnotation(XmlSchema.class);
+      var xmlns = xmlSchema.xmlns();
+      if (xmlns == null || xmlns.length != 1) {
+        throw new VerifyException(
+            String.format(
+                "Expecting exactly one NS declaration in %s", clazz.getPackage().getName()));
+      }
+      return xmlns[0].prefix();
+    }
+
     public boolean isVisible() {
       return switch (visibility) {
         case ALL -> true;

core/src/test/java/google/registry/flows/FeeExtensionXmlTagNormalizerTest.java

@@ -0,0 +1,78 @@
+// Copyright 2026 The Nomulus Authors. All Rights Reserved.
+//
+// Licensed 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
+//
+//     http://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 google.registry.flows;
+
+package google.registry.flows;
+
+import static com.google.common.truth.Truth.assertThat;
+import static google.registry.flows.FeeExtensionXmlTagNormalizer.feeExtensionInUseRegex;
+import static google.registry.flows.FeeExtensionXmlTagNormalizer.normalize;
+import static google.registry.model.eppcommon.EppXmlTransformer.validateOutput;
+import static google.registry.testing.TestDataHelper.loadFile;
+
+import java.util.stream.Stream;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.params.ParameterizedTest;
+import org.junit.jupiter.params.provider.Arguments;
+import org.junit.jupiter.params.provider.MethodSource;
+
+class FeeExtensionXmlTagNormalizerTest {
+
+  @Test
+  void feeExtensionInUseRegex_correct() {
+    assertThat(feeExtensionInUseRegex())
+        .isEqualTo("\\b(fee):|\\b(fee11):|\\b(fee12):|\\b(fee_1_00):");
+  }
+
+  @Test
+  void normalize_noFeeExtensions() throws Exception {
+    String xml = loadFile(getClass(), "domain_create.xml");
+    String normalized = normalize(xml);
+    assertThat(normalized).isEqualTo(xml);
+  }
+
+  @ParameterizedTest(name = "normalize_withFeeExtension-{0}")
+  @MethodSource("provideTestCombinations")
+  @SuppressWarnings("unused") // Parameter 'name' is part of test case name
+  void normalize_withFeeExtension(String name, String inputXmlFilename, String expectedXmlFilename)
+      throws Exception {
+    String original = loadFile(getClass(), inputXmlFilename);
+    String normalized = normalize(original);
+    String expected = loadFile(getClass(), expectedXmlFilename);
+    // Verify that expected xml is syntatically correct.
+    validateOutput(expected);
+
+    assertThat(normalized).isEqualTo(expected);
+  }
+
+  @SuppressWarnings("unused")
+  static Stream<Arguments> provideTestCombinations() {
+    return Stream.of(
+        Arguments.of(
+            "v06",
+            "domain_check_fee_response_raw_v06.xml",
+            "domain_check_fee_response_normalized_v06.xml"),
+        Arguments.of(
+            "v11",
+            "domain_check_fee_response_raw_v11.xml",
+            "domain_check_fee_response_normalized_v11.xml"),
+        Arguments.of(
+            "v12",
+            "domain_check_fee_response_raw_v12.xml",
+            "domain_check_fee_response_normalized_v12.xml"),
+        Arguments.of(
+            "stdv1",
+            "domain_check_fee_response_raw_stdv1.xml",
+            "domain_check_fee_response_normalized_stdv1.xml"));
+  }
+}

core/src/test/resources/google/registry/flows/domain_check_fee_response_normalized_stdv1.xml

@@ -0,0 +1,48 @@
+<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+<epp xmlns="urn:ietf:params:xml:ns:epp-1.0" xmlns:domain="urn:ietf:params:xml:ns:domain-1.0" xmlns:contact="urn:ietf:params:xml:ns:contact-1.0" xmlns:fee="urn:ietf:params:xml:ns:epp:fee-1.0" xmlns:rgp="urn:ietf:params:xml:ns:rgp-1.0" xmlns:bulkToken="urn:google:params:xml:ns:bulkToken-1.0" xmlns:launch="urn:ietf:params:xml:ns:launch-1.0" xmlns:secDNS="urn:ietf:params:xml:ns:secDNS-1.1" xmlns:host="urn:ietf:params:xml:ns:host-1.0">
+    <response>
+        <result code="1000">
+            <msg>Command completed successfully</msg>
+        </result>
+        <resData>
+            <domain:chkData>
+                <domain:cd>
+                    <domain:name avail="false">example.tld</domain:name>
+                    <domain:reason>Reserved; alloc. token required</domain:reason>
+                </domain:cd>
+            </domain:chkData>
+        </resData>
+        <extension>
+            <fee:chkData>
+                <fee:currency>USD</fee:currency>
+                <fee:cd>
+                    <fee:objID>example.tld</fee:objID>
+                    <fee:class>reserved</fee:class>
+                    <fee:command name="create">
+                        <fee:period unit="y">1</fee:period>
+                    </fee:command>
+                </fee:cd>
+                <fee:cd>
+                    <fee:objID>example.tld</fee:objID>
+                    <fee:class>premium</fee:class>
+                    <fee:command name="renew">
+                        <fee:period unit="y">1</fee:period>
+                        <fee:fee description="renew">499.00</fee:fee>
+                    </fee:command>
+                </fee:cd>
+                <fee:cd>
+                    <fee:objID>example.tld</fee:objID>
+                    <fee:class>premium</fee:class>
+                    <fee:command name="transfer">
+                        <fee:period unit="y">1</fee:period>
+                        <fee:fee description="renew">499.00</fee:fee>
+                    </fee:command>
+                </fee:cd>
+            </fee:chkData>
+        </extension>
+        <trID>
+            <clTRID>ff25dfc7-2025-469a-baec-bedde73e74de</clTRID>
+            <svTRID>k5VIs5JMR1SRbx3TY6pAxQ==-2c52e</svTRID>
+        </trID>
+    </response>
+</epp>

core/src/test/resources/google/registry/flows/domain_check_fee_response_normalized_v06.xml

@@ -0,0 +1,51 @@
+<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+<epp xmlns="urn:ietf:params:xml:ns:epp-1.0" xmlns:domain="urn:ietf:params:xml:ns:domain-1.0" xmlns:contact="urn:ietf:params:xml:ns:contact-1.0" xmlns:fee="urn:ietf:params:xml:ns:fee-0.6" xmlns:rgp="urn:ietf:params:xml:ns:rgp-1.0" xmlns:bulkToken="urn:google:params:xml:ns:bulkToken-1.0" xmlns:launch="urn:ietf:params:xml:ns:launch-1.0" xmlns:secDNS="urn:ietf:params:xml:ns:secDNS-1.1" xmlns:host="urn:ietf:params:xml:ns:host-1.0">
+    <response>
+        <result code="1000">
+            <msg>Command completed successfully</msg>
+        </result>
+        <resData>
+            <domain:chkData>
+                <domain:cd>
+                    <domain:name avail="true">example.tld</domain:name>
+                </domain:cd>
+            </domain:chkData>
+        </resData>
+        <extension>
+            <fee:chkData>
+                <fee:cd>
+                    <fee:name>example.tld</fee:name>
+                    <fee:currency>USD</fee:currency>
+                    <fee:command>create</fee:command>
+                    <fee:period unit="y">1</fee:period>
+                    <fee:fee description="create">10.00</fee:fee>
+                </fee:cd>
+                <fee:cd>
+                    <fee:name>example.tld</fee:name>
+                    <fee:currency>USD</fee:currency>
+                    <fee:command>renew</fee:command>
+                    <fee:period unit="y">1</fee:period>
+                    <fee:fee description="renew">12.00</fee:fee>
+                </fee:cd>
+                <fee:cd>
+                    <fee:name>example.tld</fee:name>
+                    <fee:currency>USD</fee:currency>
+                    <fee:command>transfer</fee:command>
+                    <fee:period unit="y">1</fee:period>
+                    <fee:fee description="renew">12.00</fee:fee>
+                </fee:cd>
+                <fee:cd>
+                    <fee:name>example.tld</fee:name>
+                    <fee:currency>USD</fee:currency>
+                    <fee:command>restore</fee:command>
+                    <fee:period unit="y">1</fee:period>
+                    <fee:fee description="restore">50.00</fee:fee>
+                </fee:cd>
+            </fee:chkData>
+        </extension>
+        <trID>
+            <clTRID>trid</clTRID>
+            <svTRID>PAYQRVV3Q4eeq5B5FMvtmQ==-3406e2</svTRID>
+        </trID>
+    </response>
+</epp>

core/src/test/resources/google/registry/flows/domain_check_fee_response_normalized_v11.xml

@@ -0,0 +1,32 @@
+<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+<epp xmlns="urn:ietf:params:xml:ns:epp-1.0" xmlns:domain="urn:ietf:params:xml:ns:domain-1.0" xmlns:contact="urn:ietf:params:xml:ns:contact-1.0" xmlns:rgp="urn:ietf:params:xml:ns:rgp-1.0" xmlns:bulkToken="urn:google:params:xml:ns:bulkToken-1.0" xmlns:fee="urn:ietf:params:xml:ns:fee-0.11" xmlns:launch="urn:ietf:params:xml:ns:launch-1.0" xmlns:secDNS="urn:ietf:params:xml:ns:secDNS-1.1" xmlns:host="urn:ietf:params:xml:ns:host-1.0">
+    <response>
+        <result code="1000">
+            <msg>Command completed successfully</msg>
+        </result>
+        <resData>
+            <domain:chkData>
+                <domain:cd>
+                    <domain:name avail="true">example.tld</domain:name>
+                </domain:cd>
+            </domain:chkData>
+        </resData>
+        <extension>
+            <fee:chkData>
+                <fee:cd avail="true">
+                    <fee:object>
+                        <domain:name>example.tld</domain:name>
+                    </fee:object>
+                    <fee:command>create</fee:command>
+                    <fee:currency>USD</fee:currency>
+                    <fee:period unit="y">1</fee:period>
+                    <fee:fee description="create">59.00</fee:fee>
+                    <fee:class>premium</fee:class>
+                </fee:cd>
+            </fee:chkData>
+        </extension>
+        <trID>
+            <svTRID>zpFtnGFRSKi9GbnQgwWvHQ==-398f30</svTRID>
+        </trID>
+    </response>
+</epp>