Use a higher-level protocol for encoding/decoding.

Lukasa · Lukasa · commit 246d886cf78f · 2020-07-27T08:07:46.000+01:00
Motivation:

Right now we disambiguate the multiple top-level SH types by using three
separate entry points on the encoder/decoder. This isn't great: it
forces that information to be known statically at compile time, making
it much harder to write generic APIs that use structured header fields.

Modifications:

- Provide a new protocol, `StructuredHeaderField`, that must be used for
  the top-level `Codable` object.
- Provide `StructuredHeaderFieldType` to communicate the types of
  structured header fields.
- Remove the multiple entry points.
- Update the tests.

Result:

Types will encode what kind of structured header field they are.
diff --git a/README.md b/README.md
@@ -41,19 +41,25 @@ In most cases users should prefer to use `CodableStructuredHeaders` unless they
 ```swift
 let field = Array("Sec-CH-Example, Sec-CH-Example-2".utf8)
 
+struct AcceptCH: StructuredHeaderField {
+    static let structuredFiedType: StructuredHeaderFieldType = .list
+    
+    var items: [String]
+}
+
 // Decoding
 let decoder = StructuredFieldDecoder()
-let parsed = try decoder.decodeListField([String].self, from: field)
+let parsed = try decoder.decode(AcceptCH.self, from: field)
 
 // Encoding
 let encoder = StructuredFieldEncoder()
-let serialized = try encoder.encodeListField(["Sec-CH-Example", "Sec-CH-Example-2"])
+let serialized = try encoder.encode(AcceptCH(items: ["Sec-CH-Example", "Sec-CH-Example-2"]))
 ```
 
 However, structured header fields can be substantially more complex. Structured header fields can make use of 4 containers and 6 base item types. The containers are:
 
-1. Dictionaries. These are top-level elements and associate token keys with values. The values may be items, or may be inner lists, and each value may also have parameters associated with them. `CodableStructuredHeaders` can model dictionaries as either Swift objects (where the property names are dictionary keys), or as Swift dictionaries.
-2. Lists. These are top-level elements, providing a sequence of items or inner lists. Each item or inner list may have parameters associated with them. `CodableStructuredHeaders` models these as Swift `Array`s where the entries are items of some kind.
+1. Dictionaries. These are top-level elements and associate token keys with values. The values may be items, or may be inner lists, and each value may also have parameters associated with them. `CodableStructuredHeaders` can model dictionaries as either Swift objects (where the property names are dictionary keys).
+2. Lists. These are top-level elements, providing a sequence of items or inner lists. Each item or inner list may have parameters associated with them. `CodableStructuredHeaders` models these as Swift objects with one key, `items`, that must be a collection of entries.
 3. Inner Lists. These are lists that may be sub-entries of a dictionary or a list. The list entries are items, which may have parameters associated with them: additionally, an inner list may have parameters associated with itself as well. `CodableStructuredHeaders` models these as either Swift `Array`s _or_, if it's important to extract parameters, as a two-field Swift `struct` where one field is called `items` and contains an `Array`, and other field is called `parameters` and contains a dictionary.
 4. Parameters. Parameters associated token keys with items without parameters. These are used to store metadata about objects within a field. `CodableStructuredHeaders` models these as either Swift objects (where the property names are the parameter keys) or as Swift dictionaries.
 
@@ -68,6 +74,8 @@ The base types are:
 
 For any Structured Header Field Item, the item may either be represented directly by the appropriate type, or by a Swift struct with two properties: `item` and `parameters`. This latter mode is how parameters on a given item may be captured.
 
+The top-level structured header field must identify what kind of header field it corresponds to: `.item`, `.list`, or `.dictionary`. This is inherent in the type of the field and will be specified in the relevant field specification.
+
 ## Lower Levels
 
 In some cases the Codable interface will not be either performant enough or powerful enough for the intended use-case. In cases like this, users can use the types in the `StructuredHeaders` module instead.
diff --git a/Sources/CodableStructuredHeaders/Encoder/StructuredFieldEncoder.swift b/Sources/CodableStructuredHeaders/Encoder/StructuredFieldEncoder.swift
@@ -38,13 +38,30 @@ extension StructuredFieldEncoder {
 }
 
 extension StructuredFieldEncoder {
+    /// Attempt to encode an object into a structured header field.
+    ///
+    /// - parameters:
+    ///     - data: The object to encode.
+    /// - throws: If the header field could not be encoded, or could not be serialized.
+    /// - returns: The bytes representing the HTTP structured header field.
+    public func encode<StructuredField: StructuredHeaderField>(_ data: StructuredField) throws -> [UInt8] {
+        switch StructuredField.structuredFieldType {
+        case .item:
+            return try self.encodeItemField(data)
+        case .list:
+            return try self.encodeListField(data)
+        case .dictionary:
+            return try self.encodeDictionaryField(data)
+        }
+    }
+
     /// Attempt to encode an object into a structured header dictionary field.
     ///
     /// - parameters:
     ///     - data: The object to encode.
     /// - throws: If the header field could not be encoded, or could not be serialized.
     /// - returns: The bytes representing the HTTP structured header field.
-    public func encodeDictionaryField<StructuredField: Encodable>(_ data: StructuredField) throws -> [UInt8] {
+    private func encodeDictionaryField<StructuredField: Encodable>(_ data: StructuredField) throws -> [UInt8] {
         let serializer = StructuredFieldSerializer()
         let encoder = _StructuredFieldEncoder(serializer, keyEncodingStrategy: self.keyEncodingStrategy)
         return try encoder.encodeDictionaryField(data)
@@ -56,7 +73,7 @@ extension StructuredFieldEncoder {
     ///     - data: The object to encode.
     /// - throws: If the header field could not be encoded, or could not be serialized.
     /// - returns: The bytes representing the HTTP structured header field.
-    public func encodeListField<StructuredField: Encodable>(_ data: StructuredField) throws -> [UInt8] {
+    private func encodeListField<StructuredField: Encodable>(_ data: StructuredField) throws -> [UInt8] {
         let serializer = StructuredFieldSerializer()
         let encoder = _StructuredFieldEncoder(serializer, keyEncodingStrategy: self.keyEncodingStrategy)
         return try encoder.encodeListField(data)
@@ -68,7 +85,7 @@ extension StructuredFieldEncoder {
     ///     - data: The object to encode.
     /// - throws: If the header field could not be encoded, or could not be serialized.
     /// - returns: The bytes representing the HTTP structured header field.
-    public func encodeItemField<StructuredField: Encodable>(_ data: StructuredField) throws -> [UInt8] {
+    private func encodeItemField<StructuredField: Encodable>(_ data: StructuredField) throws -> [UInt8] {
         let serializer = StructuredFieldSerializer()
         let encoder = _StructuredFieldEncoder(serializer, keyEncodingStrategy: self.keyEncodingStrategy)
         return try encoder.encodeItemField(data)
@@ -635,7 +652,7 @@ extension _StructuredFieldEncoder {
             try self.encode(value, forKey: key)
         default:
             // Ok, we don't know what this is. This can only happen for a dictionary, or
-            // for anything with parameters, or for inner lists.
+            // for anything with parameters, or for lists, or for inner lists.
             switch self.currentStackEntry.storage {
             case .dictionaryHeader:
                 // Ah, this is a dictionary, good to know. Initialize the storage, keep going.
@@ -686,7 +703,18 @@ extension _StructuredFieldEncoder {
                     throw StructuredHeaderError.invalidTypeForItem
                 }
 
-            case .listHeader, .list, .itemHeader, .bareInnerList,
+            case .listHeader:
+                switch key {
+                case "items":
+                    // Ok, we're a list. Good to know.
+                    self.push(key: .init(stringValue: key), newStorage: .list([]))
+                    try value.encode(to: self)
+                    try self.pop()
+                default:
+                    throw StructuredHeaderError.invalidTypeForItem
+                }
+
+            case .list, .itemHeader, .bareInnerList,
                  .parameters:
                 throw StructuredHeaderError.invalidTypeForItem
             }
@@ -794,6 +822,9 @@ extension _StructuredFieldEncoder {
                 map[key.stringValue] = .item(Item(item))
                 self = .dictionary(map)
 
+            case (.listHeader, .list(let list)) where key.stringValue == "items":
+                self = .list(list)
+
             case (.listHeader, .innerList(let innerList)) where key.intValue != nil:
                 self = .list([.innerList(innerList)])
 
diff --git a/Tests/StructuredHeadersTests/StructuredFieldDecoderTests.swift b/Tests/StructuredHeadersTests/StructuredFieldDecoderTests.swift
@@ -31,7 +31,7 @@ struct ListyDictionaryParameterisedList: Codable, Equatable {
     var parameters: ListyDictionaryFieldParameters
 }
 
-fileprivate struct Item<Base: Codable & Equatable>: StructuredHeaderField, Equatable {
+struct ItemField<Base: Codable & Equatable>: StructuredHeaderField, Equatable {
     static var structuredFieldType: StructuredHeaderFieldType {
         return .item
     }
@@ -43,7 +43,7 @@ fileprivate struct Item<Base: Codable & Equatable>: StructuredHeaderField, Equat
     }
 }
 
-fileprivate struct List<Base: Codable & Equatable>: StructuredHeaderField, Equatable {
+struct List<Base: Codable & Equatable>: StructuredHeaderField, Equatable {
     static var structuredFieldType: StructuredHeaderFieldType {
         return .list
     }
@@ -55,6 +55,26 @@ fileprivate struct List<Base: Codable & Equatable>: StructuredHeaderField, Equat
     }
 }
 
+struct DictionaryField<Key: Codable & Hashable, Value: Codable & Equatable>: StructuredHeaderField, Equatable {
+    static var structuredFieldType: StructuredHeaderFieldType {
+        return .dictionary
+    }
+
+    var items: [Key: Value]
+
+    init(_ items: [Key: Value]) {
+        self.items = items
+    }
+
+    func encode(to encoder: Encoder) throws {
+        try self.items.encode(to: encoder)
+    }
+
+    init(from decoder: Decoder) throws {
+        self.items = try .init(from: decoder)
+    }
+}
+
 /// An example ListyDictionary structured header field.
 ///
 /// An example of this field is: 'primary=bar;q=1.0, secondary=baz;q=0.5;fallback=last, acceptablejurisdictions=(AU;q=1.0 GB;q=0.9 FR);fallback=primary'
@@ -95,16 +115,16 @@ final class StructuredFieldDecoderTests: XCTestCase {
     func testCanDecodeIntegersInVariousWays() throws {
         let headerField = "5;bar=baz"
 
-        XCTAssertEqual(Item(UInt8(5)), try StructuredFieldDecoder().decode(from: Array(headerField.utf8)))
-        XCTAssertEqual(Item(Int8(5)), try StructuredFieldDecoder().decode(from: Array(headerField.utf8)))
-        XCTAssertEqual(Item(UInt16(5)), try StructuredFieldDecoder().decode(from: Array(headerField.utf8)))
-        XCTAssertEqual(Item(Int16(5)), try StructuredFieldDecoder().decode(from: Array(headerField.utf8)))
-        XCTAssertEqual(Item(UInt32(5)), try StructuredFieldDecoder().decode(from: Array(headerField.utf8)))
-        XCTAssertEqual(Item(Int32(5)), try StructuredFieldDecoder().decode(from: Array(headerField.utf8)))
-        XCTAssertEqual(Item(UInt64(5)), try StructuredFieldDecoder().decode(from: Array(headerField.utf8)))
-        XCTAssertEqual(Item(Int64(5)), try StructuredFieldDecoder().decode(from: Array(headerField.utf8)))
-        XCTAssertEqual(Item(UInt(5)), try StructuredFieldDecoder().decode(from: Array(headerField.utf8)))
-        XCTAssertEqual(Item(Int(5)), try StructuredFieldDecoder().decode(from: Array(headerField.utf8)))
+        XCTAssertEqual(ItemField(UInt8(5)), try StructuredFieldDecoder().decode(from: Array(headerField.utf8)))
+        XCTAssertEqual(ItemField(Int8(5)), try StructuredFieldDecoder().decode(from: Array(headerField.utf8)))
+        XCTAssertEqual(ItemField(UInt16(5)), try StructuredFieldDecoder().decode(from: Array(headerField.utf8)))
+        XCTAssertEqual(ItemField(Int16(5)), try StructuredFieldDecoder().decode(from: Array(headerField.utf8)))
+        XCTAssertEqual(ItemField(UInt32(5)), try StructuredFieldDecoder().decode(from: Array(headerField.utf8)))
+        XCTAssertEqual(ItemField(Int32(5)), try StructuredFieldDecoder().decode(from: Array(headerField.utf8)))
+        XCTAssertEqual(ItemField(UInt64(5)), try StructuredFieldDecoder().decode(from: Array(headerField.utf8)))
+        XCTAssertEqual(ItemField(Int64(5)), try StructuredFieldDecoder().decode(from: Array(headerField.utf8)))
+        XCTAssertEqual(ItemField(UInt(5)), try StructuredFieldDecoder().decode(from: Array(headerField.utf8)))
+        XCTAssertEqual(ItemField(Int(5)), try StructuredFieldDecoder().decode(from: Array(headerField.utf8)))
     }
 
     func testOutOfRangeNumbersAreReported() throws {
@@ -113,41 +133,41 @@ final class StructuredFieldDecoderTests: XCTestCase {
         // rather than crashing for all non-Int64 types. (Ignoring Int/UInt due to their platform
         // dependence)
         let headerField = "-999999999999999;bar=baz"
-        let expected = Item(Int64(-999_999_999_999_999))
-
-        XCTAssertThrowsError(try StructuredFieldDecoder().decode(Item<Int8>.self, from: Array(headerField.utf8)))
-        XCTAssertThrowsError(try StructuredFieldDecoder().decode(Item<UInt8>.self, from: Array(headerField.utf8)))
-        XCTAssertThrowsError(try StructuredFieldDecoder().decode(Item<Int16>.self, from: Array(headerField.utf8)))
-        XCTAssertThrowsError(try StructuredFieldDecoder().decode(Item<UInt16>.self, from: Array(headerField.utf8)))
-        XCTAssertThrowsError(try StructuredFieldDecoder().decode(Item<Int32>.self, from: Array(headerField.utf8)))
-        XCTAssertThrowsError(try StructuredFieldDecoder().decode(Item<UInt32>.self, from: Array(headerField.utf8)))
-        XCTAssertThrowsError(try StructuredFieldDecoder().decode(Item<UInt64>.self, from: Array(headerField.utf8)))
+        let expected = ItemField(Int64(-999_999_999_999_999))
+
+        XCTAssertThrowsError(try StructuredFieldDecoder().decode(ItemField<Int8>.self, from: Array(headerField.utf8)))
+        XCTAssertThrowsError(try StructuredFieldDecoder().decode(ItemField<UInt8>.self, from: Array(headerField.utf8)))
+        XCTAssertThrowsError(try StructuredFieldDecoder().decode(ItemField<Int16>.self, from: Array(headerField.utf8)))
+        XCTAssertThrowsError(try StructuredFieldDecoder().decode(ItemField<UInt16>.self, from: Array(headerField.utf8)))
+        XCTAssertThrowsError(try StructuredFieldDecoder().decode(ItemField<Int32>.self, from: Array(headerField.utf8)))
+        XCTAssertThrowsError(try StructuredFieldDecoder().decode(ItemField<UInt32>.self, from: Array(headerField.utf8)))
+        XCTAssertThrowsError(try StructuredFieldDecoder().decode(ItemField<UInt64>.self, from: Array(headerField.utf8)))
         XCTAssertEqual(expected, try StructuredFieldDecoder().decode(from: Array(headerField.utf8)))
     }
 
     func testDoubleAndFloatInterchangeable() throws {
         let headerField = "5.0;bar=baz"
 
-        XCTAssertEqual(Item(Float(5.0)), try StructuredFieldDecoder().decode(from: Array(headerField.utf8)))
-        XCTAssertEqual(Item(Double(5.0)), try StructuredFieldDecoder().decode(from: Array(headerField.utf8)))
+        XCTAssertEqual(ItemField(Float(5.0)), try StructuredFieldDecoder().decode(from: Array(headerField.utf8)))
+        XCTAssertEqual(ItemField(Double(5.0)), try StructuredFieldDecoder().decode(from: Array(headerField.utf8)))
     }
 
     func testAskingForTheWrongType() throws {
         let headerField = "gzip"
         let intField = "5"
 
-        XCTAssertThrowsError(try StructuredFieldDecoder().decode(Item<Int8>.self, from: Array(headerField.utf8)))
-        XCTAssertThrowsError(try StructuredFieldDecoder().decode(Item<UInt8>.self, from: Array(headerField.utf8)))
-        XCTAssertThrowsError(try StructuredFieldDecoder().decode(Item<Int16>.self, from: Array(headerField.utf8)))
-        XCTAssertThrowsError(try StructuredFieldDecoder().decode(Item<UInt16>.self, from: Array(headerField.utf8)))
-        XCTAssertThrowsError(try StructuredFieldDecoder().decode(Item<Int32>.self, from: Array(headerField.utf8)))
-        XCTAssertThrowsError(try StructuredFieldDecoder().decode(Item<UInt32>.self, from: Array(headerField.utf8)))
-        XCTAssertThrowsError(try StructuredFieldDecoder().decode(Item<Int64>.self, from: Array(headerField.utf8)))
-        XCTAssertThrowsError(try StructuredFieldDecoder().decode(Item<UInt64>.self, from: Array(headerField.utf8)))
-        XCTAssertThrowsError(try StructuredFieldDecoder().decode(Item<Double>.self, from: Array(headerField.utf8)))
-        XCTAssertThrowsError(try StructuredFieldDecoder().decode(Item<Float>.self, from: Array(headerField.utf8)))
-        XCTAssertThrowsError(try StructuredFieldDecoder().decode(Item<Bool>.self, from: Array(headerField.utf8)))
-        XCTAssertThrowsError(try StructuredFieldDecoder().decode(Item<String>.self, from: Array(intField.utf8)))
+        XCTAssertThrowsError(try StructuredFieldDecoder().decode(ItemField<Int8>.self, from: Array(headerField.utf8)))
+        XCTAssertThrowsError(try StructuredFieldDecoder().decode(ItemField<UInt8>.self, from: Array(headerField.utf8)))
+        XCTAssertThrowsError(try StructuredFieldDecoder().decode(ItemField<Int16>.self, from: Array(headerField.utf8)))
+        XCTAssertThrowsError(try StructuredFieldDecoder().decode(ItemField<UInt16>.self, from: Array(headerField.utf8)))
+        XCTAssertThrowsError(try StructuredFieldDecoder().decode(ItemField<Int32>.self, from: Array(headerField.utf8)))
+        XCTAssertThrowsError(try StructuredFieldDecoder().decode(ItemField<UInt32>.self, from: Array(headerField.utf8)))
+        XCTAssertThrowsError(try StructuredFieldDecoder().decode(ItemField<Int64>.self, from: Array(headerField.utf8)))
+        XCTAssertThrowsError(try StructuredFieldDecoder().decode(ItemField<UInt64>.self, from: Array(headerField.utf8)))
+        XCTAssertThrowsError(try StructuredFieldDecoder().decode(ItemField<Double>.self, from: Array(headerField.utf8)))
+        XCTAssertThrowsError(try StructuredFieldDecoder().decode(ItemField<Float>.self, from: Array(headerField.utf8)))
+        XCTAssertThrowsError(try StructuredFieldDecoder().decode(ItemField<Bool>.self, from: Array(headerField.utf8)))
+        XCTAssertThrowsError(try StructuredFieldDecoder().decode(ItemField<String>.self, from: Array(intField.utf8)))
     }
 
     func testDecodingTopLevelItemWithParameters() throws {
@@ -227,7 +247,7 @@ final class StructuredFieldDecoderTests: XCTestCase {
     func testDecodingBinaryAsTopLevelData() throws {
         let headerField = ":AQIDBA==:"
         XCTAssertEqual(
-            Item(Data([1, 2, 3, 4])),
+            ItemField(Data([1, 2, 3, 4])),
             try StructuredFieldDecoder().decode(from: Array(headerField.utf8))
         )
     }
@@ -320,7 +340,7 @@ final class StructuredFieldDecoderTests: XCTestCase {
     func testDecodingDecimalAsTopLevelData() throws {
         let headerField = "987654321.123"
         XCTAssertEqual(
-            Item(Decimal(string: "987654321.123")!),
+            ItemField(Decimal(string: "987654321.123")!),
             try StructuredFieldDecoder().decode(from: Array(headerField.utf8))
         )
     }
diff --git a/Tests/StructuredHeadersTests/StructuredFieldEncoderTests.swift b/Tests/StructuredHeadersTests/StructuredFieldEncoderTests.swift
