[Runtime] Add support of deepObject style in query params

### Motivation

The runtime changes for:
apple/swift-openapi-generator#259

### Modifications

Added `deepObject` style to serializer & parser in order to support nested keys
on query parameters.

### Result

Support nested keys on query parameters.

### Test Plan

These are just the runtime changes, tested together with generated
changes.

Author: kstefanou52

Sources/OpenAPIRuntime/Conversion/CurrencyExtensions.swift

@@ -29,7 +29,9 @@ extension ParameterStyle {
     ) {
         let resolvedStyle = style ?? .defaultForQueryItems
         let resolvedExplode = explode ?? ParameterStyle.defaultExplodeFor(forStyle: resolvedStyle)
-        guard resolvedStyle == .form else {
+        switch resolvedStyle {
+        case .form, .deepObject: break
+        default:
             throw RuntimeError.unsupportedParameterStyle(
                 name: name,
                 location: .query,

Sources/OpenAPIRuntime/Conversion/ParameterStyles.swift

@@ -26,6 +26,11 @@
     ///
     /// Details: https://datatracker.ietf.org/doc/html/rfc6570#section-3.2.2
     case simple
+    
+    /// The deepObject style.
+    ///
+    /// Details: https://spec.openapis.org/oas/v3.1.0.html#style-values
+    case deepObject
 }
 
 extension ParameterStyle {
@@ -53,6 +58,7 @@ extension URICoderConfiguration.Style {
         switch style {
         case .form: self = .form
         case .simple: self = .simple
+        case .deepObject: self = .deepObject
         }
     }
 }

Sources/OpenAPIRuntime/URICoder/Common/URICoderConfiguration.swift

@@ -25,6 +25,9 @@ struct URICoderConfiguration {
 
         /// A style for form-based URI expansion.
         case form
+        
+        /// A style for nested variable expansion
+        case deepObject
     }
 
     /// A character used to escape the space character.

Sources/OpenAPIRuntime/URICoder/Parsing/URIParser.swift

@@ -43,6 +43,9 @@ private enum ParsingError: Swift.Error {
 
     /// A malformed key-value pair was detected.
     case malformedKeyValuePair(Raw)
+    
+    /// An invalid configuration was detected.
+    case invalidConfiguration(String)
 }
 
 // MARK: - Parser implementations
@@ -61,13 +64,18 @@ extension URIParser {
             switch configuration.style {
             case .form: return [:]
             case .simple: return ["": [""]]
+            case .deepObject: return [:]
             }
         }
         switch (configuration.style, configuration.explode) {
         case (.form, true): return try parseExplodedFormRoot()
         case (.form, false): return try parseUnexplodedFormRoot()
         case (.simple, true): return try parseExplodedSimpleRoot()
         case (.simple, false): return try parseUnexplodedSimpleRoot()
+        case (.deepObject, true): return try parseExplodedDeepObjectRoot()
+        case (.deepObject, false):
+            let reason = "Deep object style is only valid with explode set to true"
+            throw ParsingError.invalidConfiguration(reason)
         }
     }
 
@@ -205,6 +213,43 @@ extension URIParser {
             }
         }
     }
+    
+    /// Parses the root node assuming the raw string uses the deepObject style
+    /// and the explode parameter is enabled.
+    /// - Returns: The parsed root node.
+    /// - Throws: An error if parsing fails.
+    private mutating func parseExplodedDeepObjectRoot() throws -> URIParsedNode {
+        try parseGenericRoot { data, appendPair in
+            let keyValueSeparator: Character = "="
+            let pairSeparator: Character = "&"
+            let nestedKeyStartingCharacter: Character = "["
+            let nestedKeyEndingCharacter: Character = "]"
+            
+            func nestedKey(from deepObjectKey: String.SubSequence) -> Raw {
+                var unescapedDeepObjectKey = Substring(deepObjectKey.removingPercentEncoding ?? "")
+                let topLevelKey = unescapedDeepObjectKey.parseUpToCharacterOrEnd(nestedKeyStartingCharacter)
+                let nestedKey = unescapedDeepObjectKey.parseUpToCharacterOrEnd(nestedKeyEndingCharacter)
+                return nestedKey.isEmpty ? topLevelKey : nestedKey
+            }
+            
+            while !data.isEmpty {
+                let (firstResult, firstValue) = data.parseUpToEitherCharacterOrEnd(
+                    first: keyValueSeparator,
+                    second: pairSeparator
+                )
+                
+                guard case .foundFirst = firstResult else {
+                    throw ParsingError.malformedKeyValuePair(firstValue)
+                }
+                // Hit the key/value separator, so a value will follow.
+                let secondValue = data.parseUpToCharacterOrEnd(pairSeparator)
+                let key = nestedKey(from: firstValue)
+                let value = secondValue
+                
+                appendPair(key, [value])
+            }
+        }
+    }
 }
 
 // MARK: - URIParser utilities

Sources/OpenAPIRuntime/URICoder/Serialization/URISerializer.swift

@@ -69,6 +69,12 @@ extension URISerializer {
 
         /// Nested containers are not supported.
         case nestedContainersNotSupported
+        
+        /// Deep object arrays are not supported.
+        case deepObjectsArrayNotSupported
+        
+        /// An invalid configuration was detected.
+        case invalidConfiguration(String)
     }
 
     /// Computes an escaped version of the provided string.
@@ -117,6 +123,7 @@ extension URISerializer {
             switch configuration.style {
             case .form: keyAndValueSeparator = "="
             case .simple: keyAndValueSeparator = nil
+            case .deepObject: keyAndValueSeparator = "="
             }
             try serializePrimitiveKeyValuePair(primitive, forKey: key, separator: keyAndValueSeparator)
         case .array(let array): try serializeArray(array.map(unwrapPrimitiveValue), forKey: key)
@@ -180,6 +187,8 @@ extension URISerializer {
         case (.simple, _):
             keyAndValueSeparator = nil
             pairSeparator = ","
+        case (.deepObject, _):
+            throw SerializationError.deepObjectsArrayNotSupported
         }
         func serializeNext(_ element: URIEncodedNode.Primitive) throws {
             if let keyAndValueSeparator {
@@ -228,8 +237,18 @@ extension URISerializer {
         case (.simple, false):
             keyAndValueSeparator = ","
             pairSeparator = ","
+        case (.deepObject, true):
+            keyAndValueSeparator = "="
+            pairSeparator = "&"
+        case (.deepObject, false):
+            let reason = "Deep object style is only valid with explode set to true"
+            throw SerializationError.invalidConfiguration(reason)
         }
 
+        func serializeNestedKey(_ elementKey: String, forKey rootKey: String) -> String {
+            guard case .deepObject = configuration.style else { return elementKey }
+            return rootKey + "[" + elementKey + "]"
+        }
         func serializeNext(_ element: URIEncodedNode.Primitive, forKey elementKey: String) throws {
             try serializePrimitiveKeyValuePair(element, forKey: elementKey, separator: keyAndValueSeparator)
         }
@@ -238,10 +257,13 @@ extension URISerializer {
             data.append(containerKeyAndValue)
         }
         for (elementKey, element) in sortedDictionary.dropLast() {
-            try serializeNext(element, forKey: elementKey)
+            try serializeNext(element, forKey: serializeNestedKey(elementKey, forKey: key))
             data.append(pairSeparator)
         }
-        if let (elementKey, element) = sortedDictionary.last { try serializeNext(element, forKey: elementKey) }
+        
+        if let (elementKey, element) = sortedDictionary.last {
+            try serializeNext(element, forKey: serializeNestedKey(elementKey, forKey: key))
+        }
     }
 }
 

Tests/OpenAPIRuntimeTests/URICoder/Encoding/Test_URIEncoder.swift

@@ -23,4 +23,12 @@ final class Test_URIEncoder: Test_Runtime {
         let encodedString = try encoder.encode(Foo(bar: "hello world"), forKey: "root")
         XCTAssertEqual(encodedString, "bar=hello+world")
     }
+    
+    func testNestedEncoding() throws {
+        struct Foo: Encodable { var bar: String }
+        let serializer = URISerializer(configuration: .deepObjectExplode)
+        let encoder = URIEncoder(serializer: serializer)
+        let encodedString = try encoder.encode(Foo(bar: "hello world"), forKey: "root")
+        XCTAssertEqual(encodedString, "root%5Bbar%5D=hello%20world")
+    }
 }

Tests/OpenAPIRuntimeTests/URICoder/Parsing/Test_URIParser.swift

@@ -17,7 +17,7 @@ import XCTest
 final class Test_URIParser: Test_Runtime {
 
     let testedVariants: [URICoderConfiguration] = [
-        .formExplode, .formUnexplode, .simpleExplode, .simpleUnexplode, .formDataExplode, .formDataUnexplode,
+        .formExplode, .formUnexplode, .simpleExplode, .simpleUnexplode, .formDataExplode, .formDataUnexplode, .deepObjectExplode
     ]
 
     func testParsing() throws {
@@ -29,7 +29,8 @@ final class Test_URIParser: Test_Runtime {
                     simpleExplode: .custom("", value: ["": [""]]),
                     simpleUnexplode: .custom("", value: ["": [""]]),
                     formDataExplode: "empty=",
-                    formDataUnexplode: "empty="
+                    formDataUnexplode: "empty=",
+                    deepObjectExplode: "empty="
                 ),
                 value: ["empty": [""]]
             ),
@@ -40,7 +41,8 @@ final class Test_URIParser: Test_Runtime {
                     simpleExplode: .custom("", value: ["": [""]]),
                     simpleUnexplode: .custom("", value: ["": [""]]),
                     formDataExplode: "",
-                    formDataUnexplode: ""
+                    formDataUnexplode: "",
+                    deepObjectExplode: ""
                 ),
                 value: [:]
             ),
@@ -51,7 +53,8 @@ final class Test_URIParser: Test_Runtime {
                     simpleExplode: .custom("fred", value: ["": ["fred"]]),
                     simpleUnexplode: .custom("fred", value: ["": ["fred"]]),
                     formDataExplode: "who=fred",
-                    formDataUnexplode: "who=fred"
+                    formDataUnexplode: "who=fred",
+                    deepObjectExplode: "who=fred"
                 ),
                 value: ["who": ["fred"]]
             ),
@@ -62,7 +65,8 @@ final class Test_URIParser: Test_Runtime {
                     simpleExplode: .custom("Hello%20World", value: ["": ["Hello World"]]),
                     simpleUnexplode: .custom("Hello%20World", value: ["": ["Hello World"]]),
                     formDataExplode: "hello=Hello+World",
-                    formDataUnexplode: "hello=Hello+World"
+                    formDataUnexplode: "hello=Hello+World",
+                    deepObjectExplode: "hello=Hello%20World"
                 ),
                 value: ["hello": ["Hello World"]]
             ),
@@ -73,7 +77,8 @@ final class Test_URIParser: Test_Runtime {
                     simpleExplode: .custom("red,green,blue", value: ["": ["red", "green", "blue"]]),
                     simpleUnexplode: .custom("red,green,blue", value: ["": ["red", "green", "blue"]]),
                     formDataExplode: "list=red&list=green&list=blue",
-                    formDataUnexplode: "list=red,green,blue"
+                    formDataUnexplode: "list=red,green,blue",
+                    deepObjectExplode: "list=red&list=green&list=blue"
                 ),
                 value: ["list": ["red", "green", "blue"]]
             ),
@@ -93,7 +98,8 @@ final class Test_URIParser: Test_Runtime {
                     formDataUnexplode: .custom(
                         "keys=comma,%2C,dot,.,semi,%3B",
                         value: ["keys": ["comma", ",", "dot", ".", "semi", ";"]]
-                    )
+                    ), 
+                    deepObjectExplode: "comma=%2C&dot=.&semi=%3B"
                 ),
                 value: ["semi": [";"], "dot": ["."], "comma": [","]]
             ),
@@ -133,6 +139,7 @@ extension Test_URIParser {
             static let simpleUnexplode: Self = .init(name: "simpleUnexplode", config: .simpleUnexplode)
             static let formDataExplode: Self = .init(name: "formDataExplode", config: .formDataExplode)
             static let formDataUnexplode: Self = .init(name: "formDataUnexplode", config: .formDataUnexplode)
+            static let deepObjectExplode: Self = .init(name: "deepObjectExplode", config: .deepObjectExplode)
         }
         struct Variants {
 
@@ -161,6 +168,7 @@ extension Test_URIParser {
             var simpleUnexplode: Input
             var formDataExplode: Input
             var formDataUnexplode: Input
+            var deepObjectExplode: Input
         }
         var variants: Variants
         var value: URIParsedNode

Tests/OpenAPIRuntimeTests/URICoder/Serialization/Test_URISerializer.swift

@@ -31,7 +31,8 @@ final class Test_URISerializer: Test_Runtime {
                     simpleExplode: "",
                     simpleUnexplode: "",
                     formDataExplode: "empty=",
-                    formDataUnexplode: "empty="
+                    formDataUnexplode: "empty=",
+                    deepObjectExplode: "empty="
                 )
             ),
             makeCase(
@@ -43,7 +44,8 @@ final class Test_URISerializer: Test_Runtime {
                     simpleExplode: "fred",
                     simpleUnexplode: "fred",
                     formDataExplode: "who=fred",
-                    formDataUnexplode: "who=fred"
+                    formDataUnexplode: "who=fred",
+                    deepObjectExplode: "who=fred"
                 )
             ),
             makeCase(
@@ -55,7 +57,8 @@ final class Test_URISerializer: Test_Runtime {
                     simpleExplode: "1234",
                     simpleUnexplode: "1234",
                     formDataExplode: "x=1234",
-                    formDataUnexplode: "x=1234"
+                    formDataUnexplode: "x=1234",
+                    deepObjectExplode: "x=1234"
                 )
             ),
             makeCase(
@@ -67,7 +70,8 @@ final class Test_URISerializer: Test_Runtime {
                     simpleExplode: "12.34",
                     simpleUnexplode: "12.34",
                     formDataExplode: "x=12.34",
-                    formDataUnexplode: "x=12.34"
+                    formDataUnexplode: "x=12.34",
+                    deepObjectExplode: "x=12.34"
                 )
             ),
             makeCase(
@@ -79,7 +83,8 @@ final class Test_URISerializer: Test_Runtime {
                     simpleExplode: "true",
                     simpleUnexplode: "true",
                     formDataExplode: "enabled=true",
-                    formDataUnexplode: "enabled=true"
+                    formDataUnexplode: "enabled=true",
+                    deepObjectExplode: "enabled=true"
                 )
             ),
             makeCase(
@@ -91,7 +96,8 @@ final class Test_URISerializer: Test_Runtime {
                     simpleExplode: "Hello%20World",
                     simpleUnexplode: "Hello%20World",
                     formDataExplode: "hello=Hello+World",
-                    formDataUnexplode: "hello=Hello+World"
+                    formDataUnexplode: "hello=Hello+World",
+                    deepObjectExplode: "hello=Hello%20World"
                 )
             ),
             makeCase(
@@ -103,7 +109,8 @@ final class Test_URISerializer: Test_Runtime {
                     simpleExplode: "red,green,blue",
                     simpleUnexplode: "red,green,blue",
                     formDataExplode: "list=red&list=green&list=blue",
-                    formDataUnexplode: "list=red,green,blue"
+                    formDataUnexplode: "list=red,green,blue",
+                    deepObjectExplode: nil
                 )
             ),
             makeCase(
@@ -118,7 +125,8 @@ final class Test_URISerializer: Test_Runtime {
                     simpleExplode: "comma=%2C,dot=.,semi=%3B",
                     simpleUnexplode: "comma,%2C,dot,.,semi,%3B",
                     formDataExplode: "comma=%2C&dot=.&semi=%3B",
-                    formDataUnexplode: "keys=comma,%2C,dot,.,semi,%3B"
+                    formDataUnexplode: "keys=comma,%2C,dot,.,semi,%3B",
+                    deepObjectExplode: "keys%5Bcomma%5D=%2C&keys%5Bdot%5D=.&keys%5Bsemi%5D=%3B"
                 )
             ),
         ]
@@ -140,6 +148,9 @@ final class Test_URISerializer: Test_Runtime {
             try testVariant(.simpleUnexplode, testCase.variants.simpleUnexplode)
             try testVariant(.formDataExplode, testCase.variants.formDataExplode)
             try testVariant(.formDataUnexplode, testCase.variants.formDataUnexplode)
+            if let deepObjectExplode = testCase.variants.deepObjectExplode {
+                try testVariant(.deepObjectExplode, deepObjectExplode)
+            }
         }
     }
 }
@@ -156,6 +167,7 @@ extension Test_URISerializer {
             static let simpleUnexplode: Self = .init(name: "simpleUnexplode", config: .simpleUnexplode)
             static let formDataExplode: Self = .init(name: "formDataExplode", config: .formDataExplode)
             static let formDataUnexplode: Self = .init(name: "formDataUnexplode", config: .formDataUnexplode)
+            static let deepObjectExplode: Self = .init(name: "deepObjectExplode", config: .deepObjectExplode)
         }
         struct Variants {
             var formExplode: String
@@ -164,6 +176,7 @@ extension Test_URISerializer {
             var simpleUnexplode: String
             var formDataExplode: String
             var formDataUnexplode: String
+            var deepObjectExplode: String?
         }
         var value: URIEncodedNode
         var key: String