Document that DotExpandingXContentParser outputs duplicate keys (#85063)

When we are expanding dots in fields names as part of parsing incoming documents, we may end up exposing duplicate keys,
as multiple fields with dots in their names may share parts of their path, and the resulting objects are not merged with one another.
This is ok as long as what's being parsed is not loaded into a map.

This commit documents this behaviour and modifies the corresponding parser to throw exception when one of the methods that parse into a map is called.
Also, a new test is added to DotExpandingXContentParserTests, although DocumentParserTests already has specific test for this scenario.

Author: javanna

libs/x-content/src/main/java/org/elasticsearch/xcontent/DotExpandingXContentParser.java

@@ -8,15 +8,23 @@
 
 package org.elasticsearch.xcontent;
 
+import org.elasticsearch.core.CheckedFunction;
+
 import java.io.IOException;
 import java.util.ArrayDeque;
 import java.util.Deque;
+import java.util.List;
+import java.util.Map;
+import java.util.function.Supplier;
 
 /**
  * An XContentParser that reinterprets field names containing dots as an object structure.
  *
  * A field name named {@code "foo.bar.baz":...} will be parsed instead as {@code 'foo':{'bar':{'baz':...}}}.
  * The token location is preserved so that error messages refer to the original content being parsed.
+ * This parser can output duplicate keys, but that is fine given that it's used for document parsing. The mapping
+ * lookups will return the same mapper/field type, and we never load incoming documents in a map where duplicate
+ * keys would end up overriding each other.
  */
 public class DotExpandingXContentParser extends FilterXContentParserWrapper {
 
@@ -75,6 +83,37 @@ private void expandDots() throws IOException {
         protected XContentParser delegate() {
             return parsers.peek();
         }
+
+        @Override
+        public Map<String, Object> map() throws IOException {
+            throw new UnsupportedOperationException();
+        }
+
+        @Override
+        public Map<String, Object> mapOrdered() throws IOException {
+            throw new UnsupportedOperationException();
+        }
+
+        @Override
+        public Map<String, String> mapStrings() throws IOException {
+            throw new UnsupportedOperationException();
+        }
+
+        @Override
+        public <T> Map<String, T> map(Supplier<Map<String, T>> mapFactory, CheckedFunction<XContentParser, T, IOException> mapValueParser)
+            throws IOException {
+            throw new UnsupportedOperationException();
+        }
+
+        @Override
+        public List<Object> list() throws IOException {
+            throw new UnsupportedOperationException();
+        }
+
+        @Override
+        public List<Object> listOrderedMap() throws IOException {
+            throw new UnsupportedOperationException();
+        }
     }
 
     private static String[] splitAndValidatePath(String fullFieldPath) {

libs/x-content/src/test/java/org/elasticsearch/xcontent/DotExpandingXContentParserTests.java

@@ -19,11 +19,13 @@ public class DotExpandingXContentParserTests extends ESTestCase {
     private void assertXContentMatches(String dotsExpanded, String withDots) throws IOException {
         XContentParser inputParser = createParser(JsonXContent.jsonXContent, withDots);
         XContentParser expandedParser = DotExpandingXContentParser.expandDots(inputParser);
+        expandedParser.allowDuplicateKeys(true);
 
         XContentBuilder actualOutput = XContentBuilder.builder(JsonXContent.jsonXContent).copyCurrentStructure(expandedParser);
         assertEquals(dotsExpanded, Strings.toString(actualOutput));
 
         XContentParser expectedParser = createParser(JsonXContent.jsonXContent, dotsExpanded);
+        expectedParser.allowDuplicateKeys(true);
         XContentParser actualParser = DotExpandingXContentParser.expandDots(createParser(JsonXContent.jsonXContent, withDots));
         XContentParser.Token currentToken;
         while ((currentToken = actualParser.nextToken()) != null) {
@@ -101,6 +103,13 @@ public void testTrailingDotsAreStripped() throws IOException {
 
     }
 
+    public void testDuplicateKeys() throws IOException {
+        assertXContentMatches("""
+            {"test":{"with":{"dots1":"value1"}},"test":{"with":{"dots2":"value2"}}}""", """
+            { "test.with.dots1" : "value1",
+              "test.with.dots2" : "value2"}""");
+    }
+
     public void testSkipChildren() throws IOException {
         XContentParser parser = DotExpandingXContentParser.expandDots(createParser(JsonXContent.jsonXContent, """
             { "test.with.dots" : "value", "nodots" : "value2" }"""));