Add multipart request support

Author: Jeehut

Sources/HandySwift/Types/RESTClient.swift

@@ -73,16 +73,23 @@ public final class RESTClient: Sendable {
       case json(Encodable & Sendable)
       case string(String)
       case form([URLQueryItem])
+      case multipart([MultipartItem], requestID: UUID)
 
       var contentType: String {
          switch self {
-         case .binary: return "application/octet-stream"
-         case .json: return "application/json"
-         case .string: return "text/plain"
-         case .form: return "application/x-www-form-urlencoded"
+         case .binary: "application/octet-stream"
+         case .json: "application/json"
+         case .string: "text/plain"
+         case .form: "application/x-www-form-urlencoded"
+         case .multipart(_, let requestID): "multipart/form-data; boundary=handy-swift-boundary-\(requestID.uuidString)"
          }
       }
 
+      /// Creates a multipart body with a generated UUID for request identification.
+      public static func multipart(_ items: [MultipartItem]) -> Body {
+         .multipart(items, requestID: UUID())
+      }
+
       func httpData(jsonEncoder: JSONEncoder) throws -> Data {
          switch self {
          case .binary(let data):
@@ -98,10 +105,98 @@ public final class RESTClient: Sendable {
             var urlComponents = URLComponents(string: "https://example.com")!
             urlComponents.queryItems = queryItems
             return Data(urlComponents.percentEncodedQuery!.utf8)
+
+         case .multipart(let items, let requestID):
+            let boundaryString = "handy-swift-boundary-\(requestID.uuidString)"
+            var body = Data()
+
+            for item in items {
+               // Add boundary separator
+               body.append(Data("--\(boundaryString)\r\n".utf8))
+
+               // Add Content-Disposition header
+               var contentDisposition = "Content-Disposition: form-data; name=\"\(item.name)\""
+
+               switch item.value {
+               case .text(let text):
+                  body.append(Data("\(contentDisposition)\r\n\r\n".utf8))
+                  body.append(Data(text.utf8))
+
+               case .data(let data, let fileName, let mimeType):
+                  if let fileName = fileName {
+                     contentDisposition += "; filename=\"\(fileName)\""
+                  }
+                  body.append(Data("\(contentDisposition)\r\n".utf8))
+
+                  if let mimeType = mimeType {
+                     body.append(Data("Content-Type: \(mimeType)\r\n".utf8))
+                  }
+
+                  body.append(Data("\r\n".utf8))
+                  body.append(data)
+
+               case .json(let json):
+                  body.append(Data("\(contentDisposition)\r\n".utf8))
+                  body.append(Data("Content-Type: application/json\r\n\r\n".utf8))
+                  let jsonData = try jsonEncoder.encode(json)
+                  body.append(jsonData)
+               }
+
+               body.append(Data("\r\n".utf8))
+            }
+
+            // Add final boundary
+            body.append(Data("--\(boundaryString)--\r\n".utf8))
+
+            return body
          }
       }
    }
 
+   /// A name-value pair for multipart/form-data requests, following the URLQueryItem pattern.
+   /// Used to construct multipart request bodies in a type-safe, explorable way.
+   ///
+   /// Example usage:
+   /// ```swift
+   /// let multipartItems: [RESTClient.MultipartItem] = [
+   ///     .init(name: "model", value: .text("gpt-image-1")),
+   ///     .init(name: "prompt", value: .text("Generate a liquid glass icon")),
+   ///     .init(name: "image", value: .data(imageData, fileName: "input.png", mimeType: "image/png"))
+   /// ]
+   /// ```
+   public struct MultipartItem: Sendable {
+      /// The name of the form field.
+      public let name: String
+
+      /// The value of the form field, which can be text, binary data, or JSON.
+      public let value: MultipartValue
+
+      /// Creates a new multipart item with the specified name and value.
+      /// - Parameters:
+      ///   - name: The name of the form field
+      ///   - value: The value of the form field
+      public init(name: String, value: MultipartValue) {
+         self.name = name
+         self.value = value
+      }
+   }
+
+   /// The value types supported in multipart/form-data requests.
+   public enum MultipartValue: Sendable {
+      /// A plain text value.
+      case text(String)
+
+      /// Binary data with optional filename and MIME type.
+      /// - Parameters:
+      ///   - data: The binary data to include
+      ///   - fileName: Optional filename for the uploaded file
+      ///   - mimeType: Optional MIME type (e.g., "image/png", "application/json")
+      case data(Data, fileName: String?, mimeType: String?)
+
+      /// A JSON-encodable value that will be serialized to JSON.
+      case json(Encodable & Sendable)
+   }
+
    public protocol RequestPlugin: Sendable {
       func apply(to request: inout URLRequest)
    }

Tests/HandySwiftTests/Types/RESTClientTests.swift

@@ -0,0 +1,83 @@
+import Foundation
+import Testing
+
+@testable import HandySwift
+
+@Suite("RESTClient Tests")
+struct RESTClientTests {
+
+   @Test("Complete multipart form-data integration")
+   func completeMultipartFormDataIntegration() throws {
+      struct TestModel: Codable, Sendable {
+         let name: String
+         let value: Int
+      }
+
+      let imageData = Data(repeating: 0xFF, count: 100)
+      let testModel = TestModel(name: "test", value: 42)
+
+      let multipartItems: [RESTClient.MultipartItem] = [
+         .init(name: "model", value: .text("gpt-image-1")),
+         .init(name: "prompt", value: .text("Generate a liquid glass icon")),
+         .init(name: "image", value: .data(imageData, fileName: "input.png", mimeType: "image/png")),
+         .init(name: "settings", value: .json(testModel)),
+         .init(name: "file_no_meta", value: .data(Data("content".utf8), fileName: nil, mimeType: nil)),
+      ]
+
+      let body = RESTClient.Body.multipart(multipartItems)
+      let contentType = body.contentType
+      let httpData = try body.httpData(jsonEncoder: JSONEncoder())
+      let dataString = String(decoding: httpData, as: UTF8.self)
+
+      // Extract boundary for testing
+      #expect(contentType.hasPrefix("multipart/form-data; boundary="))
+      let boundary = String(contentType.dropFirst("multipart/form-data; boundary=".count))
+      #expect(boundary.hasPrefix("handy-swift-boundary-"))
+
+      // Build expected multipart structure with actual binary data
+      let imageDataString = String(decoding: imageData, as: UTF8.self)  // Convert the actual imageData to string
+      let expectedStructure = """
+         --\(boundary)\r
+         Content-Disposition: form-data; name="model"\r
+         \r
+         gpt-image-1\r
+         --\(boundary)\r
+         Content-Disposition: form-data; name="prompt"\r
+         \r
+         Generate a liquid glass icon\r
+         --\(boundary)\r
+         Content-Disposition: form-data; name="image"; filename="input.png"\r
+         Content-Type: image/png\r
+         \r
+         \(imageDataString)\r
+         --\(boundary)\r
+         Content-Disposition: form-data; name="settings"\r
+         Content-Type: application/json\r
+         \r
+         {"name":"test","value":42}\r
+         --\(boundary)\r
+         Content-Disposition: form-data; name="file_no_meta"\r
+         \r
+         content\r
+         --\(boundary)--\r
+
+         """
+
+      // Verify the complete structure matches exactly what we expect
+      #expect(dataString == expectedStructure)
+
+      // Additional RFC 2046 compliance checks
+      #expect(dataString.contains("\r\n"))
+      #expect(!dataString.replacingOccurrences(of: "\r\n", with: "").contains("\n"))
+      #expect(dataString.hasSuffix("--\(boundary)--\r\n"))
+
+      // Verify boundary consistency and uniqueness
+      #expect(dataString.components(separatedBy: "--\(boundary)").count >= 6)  // 5 items + final boundary
+
+      let body2 = RESTClient.Body.multipart(multipartItems)
+      let boundary2 = String(body2.contentType.dropFirst("multipart/form-data; boundary=".count))
+      #expect(boundary != boundary2)  // Different instances have unique boundaries
+
+      #expect(body.contentType == body.contentType)  // Same instance maintains consistent boundary
+   }
+}