added iOS source code
[wl-app.git] / iOS / Pods / Alamofire / Source / ParameterEncoding.swift
1 //
2 //  ParameterEncoding.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 /// HTTP method definitions.
28 ///
29 /// See https://tools.ietf.org/html/rfc7231#section-4.3
30 public enum HTTPMethod: String {
31     case options = "OPTIONS"
32     case get     = "GET"
33     case head    = "HEAD"
34     case post    = "POST"
35     case put     = "PUT"
36     case patch   = "PATCH"
37     case delete  = "DELETE"
38     case trace   = "TRACE"
39     case connect = "CONNECT"
40 }
41
42 // MARK: -
43
44 /// A dictionary of parameters to apply to a `URLRequest`.
45 public typealias Parameters = [String: Any]
46
47 /// A type used to define how a set of parameters are applied to a `URLRequest`.
48 public protocol ParameterEncoding {
49     /// Creates a URL request by encoding parameters and applying them onto an existing request.
50     ///
51     /// - parameter urlRequest: The request to have parameters applied.
52     /// - parameter parameters: The parameters to apply.
53     ///
54     /// - throws: An `AFError.parameterEncodingFailed` error if encoding fails.
55     ///
56     /// - returns: The encoded request.
57     func encode(_ urlRequest: URLRequestConvertible, with parameters: Parameters?) throws -> URLRequest
58 }
59
60 // MARK: -
61
62 /// Creates a url-encoded query string to be set as or appended to any existing URL query string or set as the HTTP
63 /// body of the URL request. Whether the query string is set or appended to any existing URL query string or set as
64 /// the HTTP body depends on the destination of the encoding.
65 ///
66 /// The `Content-Type` HTTP header field of an encoded request with HTTP body is set to
67 /// `application/x-www-form-urlencoded; charset=utf-8`. Since there is no published specification for how to encode
68 /// collection types, the convention of appending `[]` to the key for array values (`foo[]=1&foo[]=2`), and appending
69 /// the key surrounded by square brackets for nested dictionary values (`foo[bar]=baz`).
70 public struct URLEncoding: ParameterEncoding {
71
72     // MARK: Helper Types
73
74     /// Defines whether the url-encoded query string is applied to the existing query string or HTTP body of the
75     /// resulting URL request.
76     ///
77     /// - methodDependent: Applies encoded query string result to existing query string for `GET`, `HEAD` and `DELETE`
78     ///                    requests and sets as the HTTP body for requests with any other HTTP method.
79     /// - queryString:     Sets or appends encoded query string result to existing query string.
80     /// - httpBody:        Sets encoded query string result as the HTTP body of the URL request.
81     public enum Destination {
82         case methodDependent, queryString, httpBody
83     }
84
85     // MARK: Properties
86
87     /// Returns a default `URLEncoding` instance.
88     public static var `default`: URLEncoding { return URLEncoding() }
89
90     /// Returns a `URLEncoding` instance with a `.methodDependent` destination.
91     public static var methodDependent: URLEncoding { return URLEncoding() }
92
93     /// Returns a `URLEncoding` instance with a `.queryString` destination.
94     public static var queryString: URLEncoding { return URLEncoding(destination: .queryString) }
95
96     /// Returns a `URLEncoding` instance with an `.httpBody` destination.
97     public static var httpBody: URLEncoding { return URLEncoding(destination: .httpBody) }
98
99     /// The destination defining where the encoded query string is to be applied to the URL request.
100     public let destination: Destination
101
102     // MARK: Initialization
103
104     /// Creates a `URLEncoding` instance using the specified destination.
105     ///
106     /// - parameter destination: The destination defining where the encoded query string is to be applied.
107     ///
108     /// - returns: The new `URLEncoding` instance.
109     public init(destination: Destination = .methodDependent) {
110         self.destination = destination
111     }
112
113     // MARK: Encoding
114
115     /// Creates a URL request by encoding parameters and applying them onto an existing request.
116     ///
117     /// - parameter urlRequest: The request to have parameters applied.
118     /// - parameter parameters: The parameters to apply.
119     ///
120     /// - throws: An `Error` if the encoding process encounters an error.
121     ///
122     /// - returns: The encoded request.
123     public func encode(_ urlRequest: URLRequestConvertible, with parameters: Parameters?) throws -> URLRequest {
124         var urlRequest = try urlRequest.asURLRequest()
125
126         guard let parameters = parameters else { return urlRequest }
127
128         if let method = HTTPMethod(rawValue: urlRequest.httpMethod ?? "GET"), encodesParametersInURL(with: method) {
129             guard let url = urlRequest.url else {
130                 throw AFError.parameterEncodingFailed(reason: .missingURL)
131             }
132
133             if var urlComponents = URLComponents(url: url, resolvingAgainstBaseURL: false), !parameters.isEmpty {
134                 let percentEncodedQuery = (urlComponents.percentEncodedQuery.map { $0 + "&" } ?? "") + query(parameters)
135                 urlComponents.percentEncodedQuery = percentEncodedQuery
136                 urlRequest.url = urlComponents.url
137             }
138         } else {
139             if urlRequest.value(forHTTPHeaderField: "Content-Type") == nil {
140                 urlRequest.setValue("application/x-www-form-urlencoded; charset=utf-8", forHTTPHeaderField: "Content-Type")
141             }
142
143             urlRequest.httpBody = query(parameters).data(using: .utf8, allowLossyConversion: false)
144         }
145
146         return urlRequest
147     }
148
149     /// Creates percent-escaped, URL encoded query string components from the given key-value pair using recursion.
150     ///
151     /// - parameter key:   The key of the query component.
152     /// - parameter value: The value of the query component.
153     ///
154     /// - returns: The percent-escaped, URL encoded query string components.
155     public func queryComponents(fromKey key: String, value: Any) -> [(String, String)] {
156         var components: [(String, String)] = []
157
158         if let dictionary = value as? [String: Any] {
159             for (nestedKey, value) in dictionary {
160                 components += queryComponents(fromKey: "\(key)[\(nestedKey)]", value: value)
161             }
162         } else if let array = value as? [Any] {
163             for value in array {
164                 components += queryComponents(fromKey: "\(key)[]", value: value)
165             }
166         } else if let value = value as? NSNumber {
167             if value.isBool {
168                 components.append((escape(key), escape((value.boolValue ? "1" : "0"))))
169             } else {
170                 components.append((escape(key), escape("\(value)")))
171             }
172         } else if let bool = value as? Bool {
173             components.append((escape(key), escape((bool ? "1" : "0"))))
174         } else {
175             components.append((escape(key), escape("\(value)")))
176         }
177
178         return components
179     }
180
181     /// Returns a percent-escaped string following RFC 3986 for a query string key or value.
182     ///
183     /// RFC 3986 states that the following characters are "reserved" characters.
184     ///
185     /// - General Delimiters: ":", "#", "[", "]", "@", "?", "/"
186     /// - Sub-Delimiters: "!", "$", "&", "'", "(", ")", "*", "+", ",", ";", "="
187     ///
188     /// In RFC 3986 - Section 3.4, it states that the "?" and "/" characters should not be escaped to allow
189     /// query strings to include a URL. Therefore, all "reserved" characters with the exception of "?" and "/"
190     /// should be percent-escaped in the query string.
191     ///
192     /// - parameter string: The string to be percent-escaped.
193     ///
194     /// - returns: The percent-escaped string.
195     public func escape(_ string: String) -> String {
196         let generalDelimitersToEncode = ":#[]@" // does not include "?" or "/" due to RFC 3986 - Section 3.4
197         let subDelimitersToEncode = "!$&'()*+,;="
198
199         var allowedCharacterSet = CharacterSet.urlQueryAllowed
200         allowedCharacterSet.remove(charactersIn: "\(generalDelimitersToEncode)\(subDelimitersToEncode)")
201
202         var escaped = ""
203
204         //==========================================================================================================
205         //
206         //  Batching is required for escaping due to an internal bug in iOS 8.1 and 8.2. Encoding more than a few
207         //  hundred Chinese characters causes various malloc error crashes. To avoid this issue until iOS 8 is no
208         //  longer supported, batching MUST be used for encoding. This introduces roughly a 20% overhead. For more
209         //  info, please refer to:
210         //
211         //      - https://github.com/Alamofire/Alamofire/issues/206
212         //
213         //==========================================================================================================
214
215         if #available(iOS 8.3, *) {
216             escaped = string.addingPercentEncoding(withAllowedCharacters: allowedCharacterSet) ?? string
217         } else {
218             let batchSize = 50
219             var index = string.startIndex
220
221             while index != string.endIndex {
222                 let startIndex = index
223                 let endIndex = string.index(index, offsetBy: batchSize, limitedBy: string.endIndex) ?? string.endIndex
224                 let range = startIndex..<endIndex
225
226                 let substring = string[range]
227
228                 escaped += substring.addingPercentEncoding(withAllowedCharacters: allowedCharacterSet) ?? String(substring)
229
230                 index = endIndex
231             }
232         }
233
234         return escaped
235     }
236
237     private func query(_ parameters: [String: Any]) -> String {
238         var components: [(String, String)] = []
239
240         for key in parameters.keys.sorted(by: <) {
241             let value = parameters[key]!
242             components += queryComponents(fromKey: key, value: value)
243         }
244         return components.map { "\($0)=\($1)" }.joined(separator: "&")
245     }
246
247     private func encodesParametersInURL(with method: HTTPMethod) -> Bool {
248         switch destination {
249         case .queryString:
250             return true
251         case .httpBody:
252             return false
253         default:
254             break
255         }
256
257         switch method {
258         case .get, .head, .delete:
259             return true
260         default:
261             return false
262         }
263     }
264 }
265
266 // MARK: -
267
268 /// Uses `JSONSerialization` to create a JSON representation of the parameters object, which is set as the body of the
269 /// request. The `Content-Type` HTTP header field of an encoded request is set to `application/json`.
270 public struct JSONEncoding: ParameterEncoding {
271
272     // MARK: Properties
273
274     /// Returns a `JSONEncoding` instance with default writing options.
275     public static var `default`: JSONEncoding { return JSONEncoding() }
276
277     /// Returns a `JSONEncoding` instance with `.prettyPrinted` writing options.
278     public static var prettyPrinted: JSONEncoding { return JSONEncoding(options: .prettyPrinted) }
279
280     /// The options for writing the parameters as JSON data.
281     public let options: JSONSerialization.WritingOptions
282
283     // MARK: Initialization
284
285     /// Creates a `JSONEncoding` instance using the specified options.
286     ///
287     /// - parameter options: The options for writing the parameters as JSON data.
288     ///
289     /// - returns: The new `JSONEncoding` instance.
290     public init(options: JSONSerialization.WritingOptions = []) {
291         self.options = options
292     }
293
294     // MARK: Encoding
295
296     /// Creates a URL request by encoding parameters and applying them onto an existing request.
297     ///
298     /// - parameter urlRequest: The request to have parameters applied.
299     /// - parameter parameters: The parameters to apply.
300     ///
301     /// - throws: An `Error` if the encoding process encounters an error.
302     ///
303     /// - returns: The encoded request.
304     public func encode(_ urlRequest: URLRequestConvertible, with parameters: Parameters?) throws -> URLRequest {
305         var urlRequest = try urlRequest.asURLRequest()
306
307         guard let parameters = parameters else { return urlRequest }
308
309         do {
310             let data = try JSONSerialization.data(withJSONObject: parameters, options: options)
311
312             if urlRequest.value(forHTTPHeaderField: "Content-Type") == nil {
313                 urlRequest.setValue("application/json", forHTTPHeaderField: "Content-Type")
314             }
315
316             urlRequest.httpBody = data
317         } catch {
318             throw AFError.parameterEncodingFailed(reason: .jsonEncodingFailed(error: error))
319         }
320
321         return urlRequest
322     }
323
324     /// Creates a URL request by encoding the JSON object and setting the resulting data on the HTTP body.
325     ///
326     /// - parameter urlRequest: The request to apply the JSON object to.
327     /// - parameter jsonObject: The JSON object to apply to the request.
328     ///
329     /// - throws: An `Error` if the encoding process encounters an error.
330     ///
331     /// - returns: The encoded request.
332     public func encode(_ urlRequest: URLRequestConvertible, withJSONObject jsonObject: Any? = nil) throws -> URLRequest {
333         var urlRequest = try urlRequest.asURLRequest()
334
335         guard let jsonObject = jsonObject else { return urlRequest }
336
337         do {
338             let data = try JSONSerialization.data(withJSONObject: jsonObject, options: options)
339
340             if urlRequest.value(forHTTPHeaderField: "Content-Type") == nil {
341                 urlRequest.setValue("application/json", forHTTPHeaderField: "Content-Type")
342             }
343
344             urlRequest.httpBody = data
345         } catch {
346             throw AFError.parameterEncodingFailed(reason: .jsonEncodingFailed(error: error))
347         }
348
349         return urlRequest
350     }
351 }
352
353 // MARK: -
354
355 /// Uses `PropertyListSerialization` to create a plist representation of the parameters object, according to the
356 /// associated format and write options values, which is set as the body of the request. The `Content-Type` HTTP header
357 /// field of an encoded request is set to `application/x-plist`.
358 public struct PropertyListEncoding: ParameterEncoding {
359
360     // MARK: Properties
361
362     /// Returns a default `PropertyListEncoding` instance.
363     public static var `default`: PropertyListEncoding { return PropertyListEncoding() }
364
365     /// Returns a `PropertyListEncoding` instance with xml formatting and default writing options.
366     public static var xml: PropertyListEncoding { return PropertyListEncoding(format: .xml) }
367
368     /// Returns a `PropertyListEncoding` instance with binary formatting and default writing options.
369     public static var binary: PropertyListEncoding { return PropertyListEncoding(format: .binary) }
370
371     /// The property list serialization format.
372     public let format: PropertyListSerialization.PropertyListFormat
373
374     /// The options for writing the parameters as plist data.
375     public let options: PropertyListSerialization.WriteOptions
376
377     // MARK: Initialization
378
379     /// Creates a `PropertyListEncoding` instance using the specified format and options.
380     ///
381     /// - parameter format:  The property list serialization format.
382     /// - parameter options: The options for writing the parameters as plist data.
383     ///
384     /// - returns: The new `PropertyListEncoding` instance.
385     public init(
386         format: PropertyListSerialization.PropertyListFormat = .xml,
387         options: PropertyListSerialization.WriteOptions = 0)
388     {
389         self.format = format
390         self.options = options
391     }
392
393     // MARK: Encoding
394
395     /// Creates a URL request by encoding parameters and applying them onto an existing request.
396     ///
397     /// - parameter urlRequest: The request to have parameters applied.
398     /// - parameter parameters: The parameters to apply.
399     ///
400     /// - throws: An `Error` if the encoding process encounters an error.
401     ///
402     /// - returns: The encoded request.
403     public func encode(_ urlRequest: URLRequestConvertible, with parameters: Parameters?) throws -> URLRequest {
404         var urlRequest = try urlRequest.asURLRequest()
405
406         guard let parameters = parameters else { return urlRequest }
407
408         do {
409             let data = try PropertyListSerialization.data(
410                 fromPropertyList: parameters,
411                 format: format,
412                 options: options
413             )
414
415             if urlRequest.value(forHTTPHeaderField: "Content-Type") == nil {
416                 urlRequest.setValue("application/x-plist", forHTTPHeaderField: "Content-Type")
417             }
418
419             urlRequest.httpBody = data
420         } catch {
421             throw AFError.parameterEncodingFailed(reason: .propertyListEncodingFailed(error: error))
422         }
423
424         return urlRequest
425     }
426 }
427
428 // MARK: -
429
430 extension NSNumber {
431     fileprivate var isBool: Bool { return CFBooleanGetTypeID() == CFGetTypeID(self) }
432 }