2 // MultipartFormData.swift
4 // Copyright (c) 2014-2017 Alamofire Software Foundation (http://alamofire.org/)
6 // Permission is hereby granted, free of charge, to any person obtaining a copy
7 // of this software and associated documentation files (the "Software"), to deal
8 // in the Software without restriction, including without limitation the rights
9 // to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
10 // copies of the Software, and to permit persons to whom the Software is
11 // furnished to do so, subject to the following conditions:
13 // The above copyright notice and this permission notice shall be included in
14 // all copies or substantial portions of the Software.
16 // THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
17 // IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
18 // FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
19 // AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
20 // LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
21 // OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
27 #if os(iOS) || os(watchOS) || os(tvOS)
28 import MobileCoreServices
33 /// Constructs `multipart/form-data` for uploads within an HTTP or HTTPS body. There are currently two ways to encode
34 /// multipart form data. The first way is to encode the data directly in memory. This is very efficient, but can lead
35 /// to memory issues if the dataset is too large. The second way is designed for larger datasets and will write all the
36 /// data to a single file on disk with all the proper boundary segmentation. The second approach MUST be used for
37 /// larger datasets such as video content, otherwise your app may run out of memory when trying to encode the dataset.
39 /// For more information on `multipart/form-data` in general, please refer to the RFC-2388 and RFC-2045 specs as well
40 /// and the w3 form documentation.
42 /// - https://www.ietf.org/rfc/rfc2388.txt
43 /// - https://www.ietf.org/rfc/rfc2045.txt
44 /// - https://www.w3.org/TR/html401/interact/forms.html#h-17.13
45 open class MultipartFormData {
47 // MARK: - Helper Types
49 struct EncodingCharacters {
50 static let crlf = "\r\n"
53 struct BoundaryGenerator {
55 case initial, encapsulated, final
58 static func randomBoundary() -> String {
59 return String(format: "alamofire.boundary.%08x%08x", arc4random(), arc4random())
62 static func boundaryData(forBoundaryType boundaryType: BoundaryType, boundary: String) -> Data {
63 let boundaryText: String
67 boundaryText = "--\(boundary)\(EncodingCharacters.crlf)"
69 boundaryText = "\(EncodingCharacters.crlf)--\(boundary)\(EncodingCharacters.crlf)"
71 boundaryText = "\(EncodingCharacters.crlf)--\(boundary)--\(EncodingCharacters.crlf)"
74 return boundaryText.data(using: String.Encoding.utf8, allowLossyConversion: false)!
79 let headers: HTTPHeaders
80 let bodyStream: InputStream
81 let bodyContentLength: UInt64
82 var hasInitialBoundary = false
83 var hasFinalBoundary = false
85 init(headers: HTTPHeaders, bodyStream: InputStream, bodyContentLength: UInt64) {
86 self.headers = headers
87 self.bodyStream = bodyStream
88 self.bodyContentLength = bodyContentLength
94 /// The `Content-Type` header value containing the boundary used to generate the `multipart/form-data`.
95 open lazy var contentType: String = "multipart/form-data; boundary=\(self.boundary)"
97 /// The content length of all body parts used to generate the `multipart/form-data` not including the boundaries.
98 public var contentLength: UInt64 { return bodyParts.reduce(0) { $0 + $1.bodyContentLength } }
100 /// The boundary used to separate the body parts in the encoded form data.
101 public let boundary: String
103 private var bodyParts: [BodyPart]
104 private var bodyPartError: AFError?
105 private let streamBufferSize: Int
109 /// Creates a multipart form data object.
111 /// - returns: The multipart form data object.
113 self.boundary = BoundaryGenerator.randomBoundary()
117 /// The optimal read/write buffer size in bytes for input and output streams is 1024 (1KB). For more
118 /// information, please refer to the following article:
119 /// - https://developer.apple.com/library/mac/documentation/Cocoa/Conceptual/Streams/Articles/ReadingInputStreams.html
122 self.streamBufferSize = 1024
125 // MARK: - Body Parts
127 /// Creates a body part from the data and appends it to the multipart form data object.
129 /// The body part data will be encoded using the following format:
131 /// - `Content-Disposition: form-data; name=#{name}` (HTTP Header)
133 /// - Multipart form boundary
135 /// - parameter data: The data to encode into the multipart form data.
136 /// - parameter name: The name to associate with the data in the `Content-Disposition` HTTP header.
137 public func append(_ data: Data, withName name: String) {
138 let headers = contentHeaders(withName: name)
139 let stream = InputStream(data: data)
140 let length = UInt64(data.count)
142 append(stream, withLength: length, headers: headers)
145 /// Creates a body part from the data and appends it to the multipart form data object.
147 /// The body part data will be encoded using the following format:
149 /// - `Content-Disposition: form-data; name=#{name}` (HTTP Header)
150 /// - `Content-Type: #{generated mimeType}` (HTTP Header)
152 /// - Multipart form boundary
154 /// - parameter data: The data to encode into the multipart form data.
155 /// - parameter name: The name to associate with the data in the `Content-Disposition` HTTP header.
156 /// - parameter mimeType: The MIME type to associate with the data content type in the `Content-Type` HTTP header.
157 public func append(_ data: Data, withName name: String, mimeType: String) {
158 let headers = contentHeaders(withName: name, mimeType: mimeType)
159 let stream = InputStream(data: data)
160 let length = UInt64(data.count)
162 append(stream, withLength: length, headers: headers)
165 /// Creates a body part from the data and appends it to the multipart form data object.
167 /// The body part data will be encoded using the following format:
169 /// - `Content-Disposition: form-data; name=#{name}; filename=#{filename}` (HTTP Header)
170 /// - `Content-Type: #{mimeType}` (HTTP Header)
171 /// - Encoded file data
172 /// - Multipart form boundary
174 /// - parameter data: The data to encode into the multipart form data.
175 /// - parameter name: The name to associate with the data in the `Content-Disposition` HTTP header.
176 /// - parameter fileName: The filename to associate with the data in the `Content-Disposition` HTTP header.
177 /// - parameter mimeType: The MIME type to associate with the data in the `Content-Type` HTTP header.
178 public func append(_ data: Data, withName name: String, fileName: String, mimeType: String) {
179 let headers = contentHeaders(withName: name, fileName: fileName, mimeType: mimeType)
180 let stream = InputStream(data: data)
181 let length = UInt64(data.count)
183 append(stream, withLength: length, headers: headers)
186 /// Creates a body part from the file and appends it to the multipart form data object.
188 /// The body part data will be encoded using the following format:
190 /// - `Content-Disposition: form-data; name=#{name}; filename=#{generated filename}` (HTTP Header)
191 /// - `Content-Type: #{generated mimeType}` (HTTP Header)
192 /// - Encoded file data
193 /// - Multipart form boundary
195 /// The filename in the `Content-Disposition` HTTP header is generated from the last path component of the
196 /// `fileURL`. The `Content-Type` HTTP header MIME type is generated by mapping the `fileURL` extension to the
197 /// system associated MIME type.
199 /// - parameter fileURL: The URL of the file whose content will be encoded into the multipart form data.
200 /// - parameter name: The name to associate with the file content in the `Content-Disposition` HTTP header.
201 public func append(_ fileURL: URL, withName name: String) {
202 let fileName = fileURL.lastPathComponent
203 let pathExtension = fileURL.pathExtension
205 if !fileName.isEmpty && !pathExtension.isEmpty {
206 let mime = mimeType(forPathExtension: pathExtension)
207 append(fileURL, withName: name, fileName: fileName, mimeType: mime)
209 setBodyPartError(withReason: .bodyPartFilenameInvalid(in: fileURL))
213 /// Creates a body part from the file and appends it to the multipart form data object.
215 /// The body part data will be encoded using the following format:
217 /// - Content-Disposition: form-data; name=#{name}; filename=#{filename} (HTTP Header)
218 /// - Content-Type: #{mimeType} (HTTP Header)
219 /// - Encoded file data
220 /// - Multipart form boundary
222 /// - parameter fileURL: The URL of the file whose content will be encoded into the multipart form data.
223 /// - parameter name: The name to associate with the file content in the `Content-Disposition` HTTP header.
224 /// - parameter fileName: The filename to associate with the file content in the `Content-Disposition` HTTP header.
225 /// - parameter mimeType: The MIME type to associate with the file content in the `Content-Type` HTTP header.
226 public func append(_ fileURL: URL, withName name: String, fileName: String, mimeType: String) {
227 let headers = contentHeaders(withName: name, fileName: fileName, mimeType: mimeType)
229 //============================================================
230 // Check 1 - is file URL?
231 //============================================================
233 guard fileURL.isFileURL else {
234 setBodyPartError(withReason: .bodyPartURLInvalid(url: fileURL))
238 //============================================================
239 // Check 2 - is file URL reachable?
240 //============================================================
243 let isReachable = try fileURL.checkPromisedItemIsReachable()
244 guard isReachable else {
245 setBodyPartError(withReason: .bodyPartFileNotReachable(at: fileURL))
249 setBodyPartError(withReason: .bodyPartFileNotReachableWithError(atURL: fileURL, error: error))
253 //============================================================
254 // Check 3 - is file URL a directory?
255 //============================================================
257 var isDirectory: ObjCBool = false
258 let path = fileURL.path
260 guard FileManager.default.fileExists(atPath: path, isDirectory: &isDirectory) && !isDirectory.boolValue else {
261 setBodyPartError(withReason: .bodyPartFileIsDirectory(at: fileURL))
265 //============================================================
266 // Check 4 - can the file size be extracted?
267 //============================================================
269 let bodyContentLength: UInt64
272 guard let fileSize = try FileManager.default.attributesOfItem(atPath: path)[.size] as? NSNumber else {
273 setBodyPartError(withReason: .bodyPartFileSizeNotAvailable(at: fileURL))
277 bodyContentLength = fileSize.uint64Value
280 setBodyPartError(withReason: .bodyPartFileSizeQueryFailedWithError(forURL: fileURL, error: error))
284 //============================================================
285 // Check 5 - can a stream be created from file URL?
286 //============================================================
288 guard let stream = InputStream(url: fileURL) else {
289 setBodyPartError(withReason: .bodyPartInputStreamCreationFailed(for: fileURL))
293 append(stream, withLength: bodyContentLength, headers: headers)
296 /// Creates a body part from the stream and appends it to the multipart form data object.
298 /// The body part data will be encoded using the following format:
300 /// - `Content-Disposition: form-data; name=#{name}; filename=#{filename}` (HTTP Header)
301 /// - `Content-Type: #{mimeType}` (HTTP Header)
302 /// - Encoded stream data
303 /// - Multipart form boundary
305 /// - parameter stream: The input stream to encode in the multipart form data.
306 /// - parameter length: The content length of the stream.
307 /// - parameter name: The name to associate with the stream content in the `Content-Disposition` HTTP header.
308 /// - parameter fileName: The filename to associate with the stream content in the `Content-Disposition` HTTP header.
309 /// - parameter mimeType: The MIME type to associate with the stream content in the `Content-Type` HTTP header.
311 _ stream: InputStream,
312 withLength length: UInt64,
317 let headers = contentHeaders(withName: name, fileName: fileName, mimeType: mimeType)
318 append(stream, withLength: length, headers: headers)
321 /// Creates a body part with the headers, stream and length and appends it to the multipart form data object.
323 /// The body part data will be encoded using the following format:
326 /// - Encoded stream data
327 /// - Multipart form boundary
329 /// - parameter stream: The input stream to encode in the multipart form data.
330 /// - parameter length: The content length of the stream.
331 /// - parameter headers: The HTTP headers for the body part.
332 public func append(_ stream: InputStream, withLength length: UInt64, headers: HTTPHeaders) {
333 let bodyPart = BodyPart(headers: headers, bodyStream: stream, bodyContentLength: length)
334 bodyParts.append(bodyPart)
337 // MARK: - Data Encoding
339 /// Encodes all the appended body parts into a single `Data` value.
341 /// It is important to note that this method will load all the appended body parts into memory all at the same
342 /// time. This method should only be used when the encoded data will have a small memory footprint. For large data
343 /// cases, please use the `writeEncodedDataToDisk(fileURL:completionHandler:)` method.
345 /// - throws: An `AFError` if encoding encounters an error.
347 /// - returns: The encoded `Data` if encoding is successful.
348 public func encode() throws -> Data {
349 if let bodyPartError = bodyPartError {
355 bodyParts.first?.hasInitialBoundary = true
356 bodyParts.last?.hasFinalBoundary = true
358 for bodyPart in bodyParts {
359 let encodedData = try encode(bodyPart)
360 encoded.append(encodedData)
366 /// Writes the appended body parts into the given file URL.
368 /// This process is facilitated by reading and writing with input and output streams, respectively. Thus,
369 /// this approach is very memory efficient and should be used for large body part data.
371 /// - parameter fileURL: The file URL to write the multipart form data into.
373 /// - throws: An `AFError` if encoding encounters an error.
374 public func writeEncodedData(to fileURL: URL) throws {
375 if let bodyPartError = bodyPartError {
379 if FileManager.default.fileExists(atPath: fileURL.path) {
380 throw AFError.multipartEncodingFailed(reason: .outputStreamFileAlreadyExists(at: fileURL))
381 } else if !fileURL.isFileURL {
382 throw AFError.multipartEncodingFailed(reason: .outputStreamURLInvalid(url: fileURL))
385 guard let outputStream = OutputStream(url: fileURL, append: false) else {
386 throw AFError.multipartEncodingFailed(reason: .outputStreamCreationFailed(for: fileURL))
390 defer { outputStream.close() }
392 self.bodyParts.first?.hasInitialBoundary = true
393 self.bodyParts.last?.hasFinalBoundary = true
395 for bodyPart in self.bodyParts {
396 try write(bodyPart, to: outputStream)
400 // MARK: - Private - Body Part Encoding
402 private func encode(_ bodyPart: BodyPart) throws -> Data {
405 let initialData = bodyPart.hasInitialBoundary ? initialBoundaryData() : encapsulatedBoundaryData()
406 encoded.append(initialData)
408 let headerData = encodeHeaders(for: bodyPart)
409 encoded.append(headerData)
411 let bodyStreamData = try encodeBodyStream(for: bodyPart)
412 encoded.append(bodyStreamData)
414 if bodyPart.hasFinalBoundary {
415 encoded.append(finalBoundaryData())
421 private func encodeHeaders(for bodyPart: BodyPart) -> Data {
424 for (key, value) in bodyPart.headers {
425 headerText += "\(key): \(value)\(EncodingCharacters.crlf)"
427 headerText += EncodingCharacters.crlf
429 return headerText.data(using: String.Encoding.utf8, allowLossyConversion: false)!
432 private func encodeBodyStream(for bodyPart: BodyPart) throws -> Data {
433 let inputStream = bodyPart.bodyStream
435 defer { inputStream.close() }
439 while inputStream.hasBytesAvailable {
440 var buffer = [UInt8](repeating: 0, count: streamBufferSize)
441 let bytesRead = inputStream.read(&buffer, maxLength: streamBufferSize)
443 if let error = inputStream.streamError {
444 throw AFError.multipartEncodingFailed(reason: .inputStreamReadFailed(error: error))
448 encoded.append(buffer, count: bytesRead)
457 // MARK: - Private - Writing Body Part to Output Stream
459 private func write(_ bodyPart: BodyPart, to outputStream: OutputStream) throws {
460 try writeInitialBoundaryData(for: bodyPart, to: outputStream)
461 try writeHeaderData(for: bodyPart, to: outputStream)
462 try writeBodyStream(for: bodyPart, to: outputStream)
463 try writeFinalBoundaryData(for: bodyPart, to: outputStream)
466 private func writeInitialBoundaryData(for bodyPart: BodyPart, to outputStream: OutputStream) throws {
467 let initialData = bodyPart.hasInitialBoundary ? initialBoundaryData() : encapsulatedBoundaryData()
468 return try write(initialData, to: outputStream)
471 private func writeHeaderData(for bodyPart: BodyPart, to outputStream: OutputStream) throws {
472 let headerData = encodeHeaders(for: bodyPart)
473 return try write(headerData, to: outputStream)
476 private func writeBodyStream(for bodyPart: BodyPart, to outputStream: OutputStream) throws {
477 let inputStream = bodyPart.bodyStream
480 defer { inputStream.close() }
482 while inputStream.hasBytesAvailable {
483 var buffer = [UInt8](repeating: 0, count: streamBufferSize)
484 let bytesRead = inputStream.read(&buffer, maxLength: streamBufferSize)
486 if let streamError = inputStream.streamError {
487 throw AFError.multipartEncodingFailed(reason: .inputStreamReadFailed(error: streamError))
491 if buffer.count != bytesRead {
492 buffer = Array(buffer[0..<bytesRead])
495 try write(&buffer, to: outputStream)
502 private func writeFinalBoundaryData(for bodyPart: BodyPart, to outputStream: OutputStream) throws {
503 if bodyPart.hasFinalBoundary {
504 return try write(finalBoundaryData(), to: outputStream)
508 // MARK: - Private - Writing Buffered Data to Output Stream
510 private func write(_ data: Data, to outputStream: OutputStream) throws {
511 var buffer = [UInt8](repeating: 0, count: data.count)
512 data.copyBytes(to: &buffer, count: data.count)
514 return try write(&buffer, to: outputStream)
517 private func write(_ buffer: inout [UInt8], to outputStream: OutputStream) throws {
518 var bytesToWrite = buffer.count
520 while bytesToWrite > 0, outputStream.hasSpaceAvailable {
521 let bytesWritten = outputStream.write(buffer, maxLength: bytesToWrite)
523 if let error = outputStream.streamError {
524 throw AFError.multipartEncodingFailed(reason: .outputStreamWriteFailed(error: error))
527 bytesToWrite -= bytesWritten
529 if bytesToWrite > 0 {
530 buffer = Array(buffer[bytesWritten..<buffer.count])
535 // MARK: - Private - Mime Type
537 private func mimeType(forPathExtension pathExtension: String) -> String {
539 let id = UTTypeCreatePreferredIdentifierForTag(kUTTagClassFilenameExtension, pathExtension as CFString, nil)?.takeRetainedValue(),
540 let contentType = UTTypeCopyPreferredTagWithClass(id, kUTTagClassMIMEType)?.takeRetainedValue()
542 return contentType as String
545 return "application/octet-stream"
548 // MARK: - Private - Content Headers
550 private func contentHeaders(withName name: String, fileName: String? = nil, mimeType: String? = nil) -> [String: String] {
551 var disposition = "form-data; name=\"\(name)\""
552 if let fileName = fileName { disposition += "; filename=\"\(fileName)\"" }
554 var headers = ["Content-Disposition": disposition]
555 if let mimeType = mimeType { headers["Content-Type"] = mimeType }
560 // MARK: - Private - Boundary Encoding
562 private func initialBoundaryData() -> Data {
563 return BoundaryGenerator.boundaryData(forBoundaryType: .initial, boundary: boundary)
566 private func encapsulatedBoundaryData() -> Data {
567 return BoundaryGenerator.boundaryData(forBoundaryType: .encapsulated, boundary: boundary)
570 private func finalBoundaryData() -> Data {
571 return BoundaryGenerator.boundaryData(forBoundaryType: .final, boundary: boundary)
574 // MARK: - Private - Errors
576 private func setBodyPartError(withReason reason: AFError.MultipartEncodingFailureReason) {
577 guard bodyPartError == nil else { return }
578 bodyPartError = AFError.multipartEncodingFailed(reason: reason)