added iOS source code
[wl-app.git] / iOS / Pods / Alamofire / Source / MultipartFormData.swift
1 //
2 //  MultipartFormData.swift
3 //
4 //  Copyright (c) 2014-2017 Alamofire Software Foundation (http://alamofire.org/)
5 //
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:
12 //
13 //  The above copyright notice and this permission notice shall be included in
14 //  all copies or substantial portions of the Software.
15 //
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
22 //  THE SOFTWARE.
23 //
24
25 import Foundation
26
27 #if os(iOS) || os(watchOS) || os(tvOS)
28 import MobileCoreServices
29 #elseif os(macOS)
30 import CoreServices
31 #endif
32
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.
38 ///
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.
41 ///
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 {
46
47     // MARK: - Helper Types
48
49     struct EncodingCharacters {
50         static let crlf = "\r\n"
51     }
52
53     struct BoundaryGenerator {
54         enum BoundaryType {
55             case initial, encapsulated, final
56         }
57
58         static func randomBoundary() -> String {
59             return String(format: "alamofire.boundary.%08x%08x", arc4random(), arc4random())
60         }
61
62         static func boundaryData(forBoundaryType boundaryType: BoundaryType, boundary: String) -> Data {
63             let boundaryText: String
64
65             switch boundaryType {
66             case .initial:
67                 boundaryText = "--\(boundary)\(EncodingCharacters.crlf)"
68             case .encapsulated:
69                 boundaryText = "\(EncodingCharacters.crlf)--\(boundary)\(EncodingCharacters.crlf)"
70             case .final:
71                 boundaryText = "\(EncodingCharacters.crlf)--\(boundary)--\(EncodingCharacters.crlf)"
72             }
73
74             return boundaryText.data(using: String.Encoding.utf8, allowLossyConversion: false)!
75         }
76     }
77
78     class BodyPart {
79         let headers: HTTPHeaders
80         let bodyStream: InputStream
81         let bodyContentLength: UInt64
82         var hasInitialBoundary = false
83         var hasFinalBoundary = false
84
85         init(headers: HTTPHeaders, bodyStream: InputStream, bodyContentLength: UInt64) {
86             self.headers = headers
87             self.bodyStream = bodyStream
88             self.bodyContentLength = bodyContentLength
89         }
90     }
91
92     // MARK: - Properties
93
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)"
96
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 } }
99
100     /// The boundary used to separate the body parts in the encoded form data.
101     public let boundary: String
102
103     private var bodyParts: [BodyPart]
104     private var bodyPartError: AFError?
105     private let streamBufferSize: Int
106
107     // MARK: - Lifecycle
108
109     /// Creates a multipart form data object.
110     ///
111     /// - returns: The multipart form data object.
112     public init() {
113         self.boundary = BoundaryGenerator.randomBoundary()
114         self.bodyParts = []
115
116         ///
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
120         ///
121
122         self.streamBufferSize = 1024
123     }
124
125     // MARK: - Body Parts
126
127     /// Creates a body part from the data and appends it to the multipart form data object.
128     ///
129     /// The body part data will be encoded using the following format:
130     ///
131     /// - `Content-Disposition: form-data; name=#{name}` (HTTP Header)
132     /// - Encoded data
133     /// - Multipart form boundary
134     ///
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)
141
142         append(stream, withLength: length, headers: headers)
143     }
144
145     /// Creates a body part from the data and appends it to the multipart form data object.
146     ///
147     /// The body part data will be encoded using the following format:
148     ///
149     /// - `Content-Disposition: form-data; name=#{name}` (HTTP Header)
150     /// - `Content-Type: #{generated mimeType}` (HTTP Header)
151     /// - Encoded data
152     /// - Multipart form boundary
153     ///
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)
161
162         append(stream, withLength: length, headers: headers)
163     }
164
165     /// Creates a body part from the data and appends it to the multipart form data object.
166     ///
167     /// The body part data will be encoded using the following format:
168     ///
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
173     ///
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)
182
183         append(stream, withLength: length, headers: headers)
184     }
185
186     /// Creates a body part from the file and appends it to the multipart form data object.
187     ///
188     /// The body part data will be encoded using the following format:
189     ///
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
194     ///
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.
198     ///
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
204
205         if !fileName.isEmpty && !pathExtension.isEmpty {
206             let mime = mimeType(forPathExtension: pathExtension)
207             append(fileURL, withName: name, fileName: fileName, mimeType: mime)
208         } else {
209             setBodyPartError(withReason: .bodyPartFilenameInvalid(in: fileURL))
210         }
211     }
212
213     /// Creates a body part from the file and appends it to the multipart form data object.
214     ///
215     /// The body part data will be encoded using the following format:
216     ///
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
221     ///
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)
228
229         //============================================================
230         //                 Check 1 - is file URL?
231         //============================================================
232
233         guard fileURL.isFileURL else {
234             setBodyPartError(withReason: .bodyPartURLInvalid(url: fileURL))
235             return
236         }
237
238         //============================================================
239         //              Check 2 - is file URL reachable?
240         //============================================================
241
242         do {
243             let isReachable = try fileURL.checkPromisedItemIsReachable()
244             guard isReachable else {
245                 setBodyPartError(withReason: .bodyPartFileNotReachable(at: fileURL))
246                 return
247             }
248         } catch {
249             setBodyPartError(withReason: .bodyPartFileNotReachableWithError(atURL: fileURL, error: error))
250             return
251         }
252
253         //============================================================
254         //            Check 3 - is file URL a directory?
255         //============================================================
256
257         var isDirectory: ObjCBool = false
258         let path = fileURL.path
259
260         guard FileManager.default.fileExists(atPath: path, isDirectory: &isDirectory) && !isDirectory.boolValue else {
261             setBodyPartError(withReason: .bodyPartFileIsDirectory(at: fileURL))
262             return
263         }
264
265         //============================================================
266         //          Check 4 - can the file size be extracted?
267         //============================================================
268
269         let bodyContentLength: UInt64
270
271         do {
272             guard let fileSize = try FileManager.default.attributesOfItem(atPath: path)[.size] as? NSNumber else {
273                 setBodyPartError(withReason: .bodyPartFileSizeNotAvailable(at: fileURL))
274                 return
275             }
276
277             bodyContentLength = fileSize.uint64Value
278         }
279         catch {
280             setBodyPartError(withReason: .bodyPartFileSizeQueryFailedWithError(forURL: fileURL, error: error))
281             return
282         }
283
284         //============================================================
285         //       Check 5 - can a stream be created from file URL?
286         //============================================================
287
288         guard let stream = InputStream(url: fileURL) else {
289             setBodyPartError(withReason: .bodyPartInputStreamCreationFailed(for: fileURL))
290             return
291         }
292
293         append(stream, withLength: bodyContentLength, headers: headers)
294     }
295
296     /// Creates a body part from the stream and appends it to the multipart form data object.
297     ///
298     /// The body part data will be encoded using the following format:
299     ///
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
304     ///
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.
310     public func append(
311         _ stream: InputStream,
312         withLength length: UInt64,
313         name: String,
314         fileName: String,
315         mimeType: String)
316     {
317         let headers = contentHeaders(withName: name, fileName: fileName, mimeType: mimeType)
318         append(stream, withLength: length, headers: headers)
319     }
320
321     /// Creates a body part with the headers, stream and length and appends it to the multipart form data object.
322     ///
323     /// The body part data will be encoded using the following format:
324     ///
325     /// - HTTP headers
326     /// - Encoded stream data
327     /// - Multipart form boundary
328     ///
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)
335     }
336
337     // MARK: - Data Encoding
338
339     /// Encodes all the appended body parts into a single `Data` value.
340     ///
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.
344     ///
345     /// - throws: An `AFError` if encoding encounters an error.
346     ///
347     /// - returns: The encoded `Data` if encoding is successful.
348     public func encode() throws -> Data {
349         if let bodyPartError = bodyPartError {
350             throw bodyPartError
351         }
352
353         var encoded = Data()
354
355         bodyParts.first?.hasInitialBoundary = true
356         bodyParts.last?.hasFinalBoundary = true
357
358         for bodyPart in bodyParts {
359             let encodedData = try encode(bodyPart)
360             encoded.append(encodedData)
361         }
362
363         return encoded
364     }
365
366     /// Writes the appended body parts into the given file URL.
367     ///
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.
370     ///
371     /// - parameter fileURL: The file URL to write the multipart form data into.
372     ///
373     /// - throws: An `AFError` if encoding encounters an error.
374     public func writeEncodedData(to fileURL: URL) throws {
375         if let bodyPartError = bodyPartError {
376             throw bodyPartError
377         }
378
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))
383         }
384
385         guard let outputStream = OutputStream(url: fileURL, append: false) else {
386             throw AFError.multipartEncodingFailed(reason: .outputStreamCreationFailed(for: fileURL))
387         }
388
389         outputStream.open()
390         defer { outputStream.close() }
391
392         self.bodyParts.first?.hasInitialBoundary = true
393         self.bodyParts.last?.hasFinalBoundary = true
394
395         for bodyPart in self.bodyParts {
396             try write(bodyPart, to: outputStream)
397         }
398     }
399
400     // MARK: - Private - Body Part Encoding
401
402     private func encode(_ bodyPart: BodyPart) throws -> Data {
403         var encoded = Data()
404
405         let initialData = bodyPart.hasInitialBoundary ? initialBoundaryData() : encapsulatedBoundaryData()
406         encoded.append(initialData)
407
408         let headerData = encodeHeaders(for: bodyPart)
409         encoded.append(headerData)
410
411         let bodyStreamData = try encodeBodyStream(for: bodyPart)
412         encoded.append(bodyStreamData)
413
414         if bodyPart.hasFinalBoundary {
415             encoded.append(finalBoundaryData())
416         }
417
418         return encoded
419     }
420
421     private func encodeHeaders(for bodyPart: BodyPart) -> Data {
422         var headerText = ""
423
424         for (key, value) in bodyPart.headers {
425             headerText += "\(key): \(value)\(EncodingCharacters.crlf)"
426         }
427         headerText += EncodingCharacters.crlf
428
429         return headerText.data(using: String.Encoding.utf8, allowLossyConversion: false)!
430     }
431
432     private func encodeBodyStream(for bodyPart: BodyPart) throws -> Data {
433         let inputStream = bodyPart.bodyStream
434         inputStream.open()
435         defer { inputStream.close() }
436
437         var encoded = Data()
438
439         while inputStream.hasBytesAvailable {
440             var buffer = [UInt8](repeating: 0, count: streamBufferSize)
441             let bytesRead = inputStream.read(&buffer, maxLength: streamBufferSize)
442
443             if let error = inputStream.streamError {
444                 throw AFError.multipartEncodingFailed(reason: .inputStreamReadFailed(error: error))
445             }
446
447             if bytesRead > 0 {
448                 encoded.append(buffer, count: bytesRead)
449             } else {
450                 break
451             }
452         }
453
454         return encoded
455     }
456
457     // MARK: - Private - Writing Body Part to Output Stream
458
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)
464     }
465
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)
469     }
470
471     private func writeHeaderData(for bodyPart: BodyPart, to outputStream: OutputStream) throws {
472         let headerData = encodeHeaders(for: bodyPart)
473         return try write(headerData, to: outputStream)
474     }
475
476     private func writeBodyStream(for bodyPart: BodyPart, to outputStream: OutputStream) throws {
477         let inputStream = bodyPart.bodyStream
478
479         inputStream.open()
480         defer { inputStream.close() }
481
482         while inputStream.hasBytesAvailable {
483             var buffer = [UInt8](repeating: 0, count: streamBufferSize)
484             let bytesRead = inputStream.read(&buffer, maxLength: streamBufferSize)
485
486             if let streamError = inputStream.streamError {
487                 throw AFError.multipartEncodingFailed(reason: .inputStreamReadFailed(error: streamError))
488             }
489
490             if bytesRead > 0 {
491                 if buffer.count != bytesRead {
492                     buffer = Array(buffer[0..<bytesRead])
493                 }
494
495                 try write(&buffer, to: outputStream)
496             } else {
497                 break
498             }
499         }
500     }
501
502     private func writeFinalBoundaryData(for bodyPart: BodyPart, to outputStream: OutputStream) throws {
503         if bodyPart.hasFinalBoundary {
504             return try write(finalBoundaryData(), to: outputStream)
505         }
506     }
507
508     // MARK: - Private - Writing Buffered Data to Output Stream
509
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)
513
514         return try write(&buffer, to: outputStream)
515     }
516
517     private func write(_ buffer: inout [UInt8], to outputStream: OutputStream) throws {
518         var bytesToWrite = buffer.count
519
520         while bytesToWrite > 0, outputStream.hasSpaceAvailable {
521             let bytesWritten = outputStream.write(buffer, maxLength: bytesToWrite)
522
523             if let error = outputStream.streamError {
524                 throw AFError.multipartEncodingFailed(reason: .outputStreamWriteFailed(error: error))
525             }
526
527             bytesToWrite -= bytesWritten
528
529             if bytesToWrite > 0 {
530                 buffer = Array(buffer[bytesWritten..<buffer.count])
531             }
532         }
533     }
534
535     // MARK: - Private - Mime Type
536
537     private func mimeType(forPathExtension pathExtension: String) -> String {
538         if
539             let id = UTTypeCreatePreferredIdentifierForTag(kUTTagClassFilenameExtension, pathExtension as CFString, nil)?.takeRetainedValue(),
540             let contentType = UTTypeCopyPreferredTagWithClass(id, kUTTagClassMIMEType)?.takeRetainedValue()
541         {
542             return contentType as String
543         }
544
545         return "application/octet-stream"
546     }
547
548     // MARK: - Private - Content Headers
549
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)\"" }
553
554         var headers = ["Content-Disposition": disposition]
555         if let mimeType = mimeType { headers["Content-Type"] = mimeType }
556
557         return headers
558     }
559
560     // MARK: - Private - Boundary Encoding
561
562     private func initialBoundaryData() -> Data {
563         return BoundaryGenerator.boundaryData(forBoundaryType: .initial, boundary: boundary)
564     }
565
566     private func encapsulatedBoundaryData() -> Data {
567         return BoundaryGenerator.boundaryData(forBoundaryType: .encapsulated, boundary: boundary)
568     }
569
570     private func finalBoundaryData() -> Data {
571         return BoundaryGenerator.boundaryData(forBoundaryType: .final, boundary: boundary)
572     }
573
574     // MARK: - Private - Errors
575
576     private func setBodyPartError(withReason reason: AFError.MultipartEncodingFailureReason) {
577         guard bodyPartError == nil else { return }
578         bodyPartError = AFError.multipartEncodingFailed(reason: reason)
579     }
580 }