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 }