iOS/Pods/Alamofire/Source/SessionManager.swift

   1 //
   2 //  SessionManager.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 /// Responsible for creating and managing `Request` objects, as well as their underlying `NSURLSession`.
  28 open class SessionManager {
  29
  30     // MARK: - Helper Types
  31
  32     /// Defines whether the `MultipartFormData` encoding was successful and contains result of the encoding as
  33     /// associated values.
  34     ///
  35     /// - Success: Represents a successful `MultipartFormData` encoding and contains the new `UploadRequest` along with
  36     ///            streaming information.
  37     /// - Failure: Used to represent a failure in the `MultipartFormData` encoding and also contains the encoding
  38     ///            error.
  39     public enum MultipartFormDataEncodingResult {
  40         case success(request: UploadRequest, streamingFromDisk: Bool, streamFileURL: URL?)
  41         case failure(Error)
  42     }
  43
  44     // MARK: - Properties
  45
  46     /// A default instance of `SessionManager`, used by top-level Alamofire request methods, and suitable for use
  47     /// directly for any ad hoc requests.
  48     open static let `default`: SessionManager = {
  49         let configuration = URLSessionConfiguration.default
  50         configuration.httpAdditionalHeaders = SessionManager.defaultHTTPHeaders
  51
  52         return SessionManager(configuration: configuration)
  53     }()
  54
  55     /// Creates default values for the "Accept-Encoding", "Accept-Language" and "User-Agent" headers.
  56     open static let defaultHTTPHeaders: HTTPHeaders = {
  57         // Accept-Encoding HTTP Header; see https://tools.ietf.org/html/rfc7230#section-4.2.3
  58         let acceptEncoding: String = "gzip;q=1.0, compress;q=0.5"
  59
  60         // Accept-Language HTTP Header; see https://tools.ietf.org/html/rfc7231#section-5.3.5
  61         let acceptLanguage = Locale.preferredLanguages.prefix(6).enumerated().map { index, languageCode in
  62             let quality = 1.0 - (Double(index) * 0.1)
  63             return "\(languageCode);q=\(quality)"
  64         }.joined(separator: ", ")
  65
  66         // User-Agent Header; see https://tools.ietf.org/html/rfc7231#section-5.5.3
  67         // Example: `iOS Example/1.0 (org.alamofire.iOS-Example; build:1; iOS 10.0.0) Alamofire/4.0.0`
  68         let userAgent: String = {
  69             if let info = Bundle.main.infoDictionary {
  70                 let executable = info[kCFBundleExecutableKey as String] as? String ?? "Unknown"
  71                 let bundle = info[kCFBundleIdentifierKey as String] as? String ?? "Unknown"
  72                 let appVersion = info["CFBundleShortVersionString"] as? String ?? "Unknown"
  73                 let appBuild = info[kCFBundleVersionKey as String] as? String ?? "Unknown"
  74
  75                 let osNameVersion: String = {
  76                     let version = ProcessInfo.processInfo.operatingSystemVersion
  77                     let versionString = "\(version.majorVersion).\(version.minorVersion).\(version.patchVersion)"
  78
  79                     let osName: String = {
  80                         #if os(iOS)
  81                             return "iOS"
  82                         #elseif os(watchOS)
  83                             return "watchOS"
  84                         #elseif os(tvOS)
  85                             return "tvOS"
  86                         #elseif os(macOS)
  87                             return "OS X"
  88                         #elseif os(Linux)
  89                             return "Linux"
  90                         #else
  91                             return "Unknown"
  92                         #endif
  93                     }()
  94
  95                     return "\(osName) \(versionString)"
  96                 }()
  97
  98                 let alamofireVersion: String = {
  99                     guard
 100                         let afInfo = Bundle(for: SessionManager.self).infoDictionary,
 101                         let build = afInfo["CFBundleShortVersionString"]
 102                     else { return "Unknown" }
 103
 104                     return "Alamofire/\(build)"
 105                 }()
 106
 107                 return "\(executable)/\(appVersion) (\(bundle); build:\(appBuild); \(osNameVersion)) \(alamofireVersion)"
 108             }
 109
 110             return "Alamofire"
 111         }()
 112
 113         return [
 114             "Accept-Encoding": acceptEncoding,
 115             "Accept-Language": acceptLanguage,
 116             "User-Agent": userAgent
 117         ]
 118     }()
 119
 120     /// Default memory threshold used when encoding `MultipartFormData` in bytes.
 121     open static let multipartFormDataEncodingMemoryThreshold: UInt64 = 10_000_000
 122
 123     /// The underlying session.
 124     open let session: URLSession
 125
 126     /// The session delegate handling all the task and session delegate callbacks.
 127     open let delegate: SessionDelegate
 128
 129     /// Whether to start requests immediately after being constructed. `true` by default.
 130     open var startRequestsImmediately: Bool = true
 131
 132     /// The request adapter called each time a new request is created.
 133     open var adapter: RequestAdapter?
 134
 135     /// The request retrier called each time a request encounters an error to determine whether to retry the request.
 136     open var retrier: RequestRetrier? {
 137         get { return delegate.retrier }
 138         set { delegate.retrier = newValue }
 139     }
 140
 141     /// The background completion handler closure provided by the UIApplicationDelegate
 142     /// `application:handleEventsForBackgroundURLSession:completionHandler:` method. By setting the background
 143     /// completion handler, the SessionDelegate `sessionDidFinishEventsForBackgroundURLSession` closure implementation
 144     /// will automatically call the handler.
 145     ///
 146     /// If you need to handle your own events before the handler is called, then you need to override the
 147     /// SessionDelegate `sessionDidFinishEventsForBackgroundURLSession` and manually call the handler when finished.
 148     ///
 149     /// `nil` by default.
 150     open var backgroundCompletionHandler: (() -> Void)?
 151
 152     let queue = DispatchQueue(label: "org.alamofire.session-manager." + UUID().uuidString)
 153
 154     // MARK: - Lifecycle
 155
 156     /// Creates an instance with the specified `configuration`, `delegate` and `serverTrustPolicyManager`.
 157     ///
 158     /// - parameter configuration:            The configuration used to construct the managed session.
 159     ///                                       `URLSessionConfiguration.default` by default.
 160     /// - parameter delegate:                 The delegate used when initializing the session. `SessionDelegate()` by
 161     ///                                       default.
 162     /// - parameter serverTrustPolicyManager: The server trust policy manager to use for evaluating all server trust
 163     ///                                       challenges. `nil` by default.
 164     ///
 165     /// - returns: The new `SessionManager` instance.
 166     public init(
 167         configuration: URLSessionConfiguration = URLSessionConfiguration.default,
 168         delegate: SessionDelegate = SessionDelegate(),
 169         serverTrustPolicyManager: ServerTrustPolicyManager? = nil)
 170     {
 171         self.delegate = delegate
 172         self.session = URLSession(configuration: configuration, delegate: delegate, delegateQueue: nil)
 173
 174         commonInit(serverTrustPolicyManager: serverTrustPolicyManager)
 175     }
 176
 177     /// Creates an instance with the specified `session`, `delegate` and `serverTrustPolicyManager`.
 178     ///
 179     /// - parameter session:                  The URL session.
 180     /// - parameter delegate:                 The delegate of the URL session. Must equal the URL session's delegate.
 181     /// - parameter serverTrustPolicyManager: The server trust policy manager to use for evaluating all server trust
 182     ///                                       challenges. `nil` by default.
 183     ///
 184     /// - returns: The new `SessionManager` instance if the URL session's delegate matches; `nil` otherwise.
 185     public init?(
 186         session: URLSession,
 187         delegate: SessionDelegate,
 188         serverTrustPolicyManager: ServerTrustPolicyManager? = nil)
 189     {
 190         guard delegate === session.delegate else { return nil }
 191
 192         self.delegate = delegate
 193         self.session = session
 194
 195         commonInit(serverTrustPolicyManager: serverTrustPolicyManager)
 196     }
 197
 198     private func commonInit(serverTrustPolicyManager: ServerTrustPolicyManager?) {
 199         session.serverTrustPolicyManager = serverTrustPolicyManager
 200
 201         delegate.sessionManager = self
 202
 203         delegate.sessionDidFinishEventsForBackgroundURLSession = { [weak self] session in
 204             guard let strongSelf = self else { return }
 205             DispatchQueue.main.async { strongSelf.backgroundCompletionHandler?() }
 206         }
 207     }
 208
 209     deinit {
 210         session.invalidateAndCancel()
 211     }
 212
 213     // MARK: - Data Request
 214
 215     /// Creates a `DataRequest` to retrieve the contents of the specified `url`, `method`, `parameters`, `encoding`
 216     /// and `headers`.
 217     ///
 218     /// - parameter url:        The URL.
 219     /// - parameter method:     The HTTP method. `.get` by default.
 220     /// - parameter parameters: The parameters. `nil` by default.
 221     /// - parameter encoding:   The parameter encoding. `URLEncoding.default` by default.
 222     /// - parameter headers:    The HTTP headers. `nil` by default.
 223     ///
 224     /// - returns: The created `DataRequest`.
 225     @discardableResult
 226     open func request(
 227         _ url: URLConvertible,
 228         method: HTTPMethod = .get,
 229         parameters: Parameters? = nil,
 230         encoding: ParameterEncoding = URLEncoding.default,
 231         headers: HTTPHeaders? = nil)
 232         -> DataRequest
 233     {
 234         var originalRequest: URLRequest?
 235
 236         do {
 237             originalRequest = try URLRequest(url: url, method: method, headers: headers)
 238             let encodedURLRequest = try encoding.encode(originalRequest!, with: parameters)
 239             return request(encodedURLRequest)
 240         } catch {
 241             return request(originalRequest, failedWith: error)
 242         }
 243     }
 244
 245     /// Creates a `DataRequest` to retrieve the contents of a URL based on the specified `urlRequest`.
 246     ///
 247     /// If `startRequestsImmediately` is `true`, the request will have `resume()` called before being returned.
 248     ///
 249     /// - parameter urlRequest: The URL request.
 250     ///
 251     /// - returns: The created `DataRequest`.
 252     @discardableResult
 253     open func request(_ urlRequest: URLRequestConvertible) -> DataRequest {
 254         var originalRequest: URLRequest?
 255
 256         do {
 257             originalRequest = try urlRequest.asURLRequest()
 258             let originalTask = DataRequest.Requestable(urlRequest: originalRequest!)
 259
 260             let task = try originalTask.task(session: session, adapter: adapter, queue: queue)
 261             let request = DataRequest(session: session, requestTask: .data(originalTask, task))
 262
 263             delegate[task] = request
 264
 265             if startRequestsImmediately { request.resume() }
 266
 267             return request
 268         } catch {
 269             return request(originalRequest, failedWith: error)
 270         }
 271     }
 272
 273     // MARK: Private - Request Implementation
 274
 275     private func request(_ urlRequest: URLRequest?, failedWith error: Error) -> DataRequest {
 276         var requestTask: Request.RequestTask = .data(nil, nil)
 277
 278         if let urlRequest = urlRequest {
 279             let originalTask = DataRequest.Requestable(urlRequest: urlRequest)
 280             requestTask = .data(originalTask, nil)
 281         }
 282
 283         let underlyingError = error.underlyingAdaptError ?? error
 284         let request = DataRequest(session: session, requestTask: requestTask, error: underlyingError)
 285
 286         if let retrier = retrier, error is AdaptError {
 287             allowRetrier(retrier, toRetry: request, with: underlyingError)
 288         } else {
 289             if startRequestsImmediately { request.resume() }
 290         }
 291
 292         return request
 293     }
 294
 295     // MARK: - Download Request
 296
 297     // MARK: URL Request
 298
 299     /// Creates a `DownloadRequest` to retrieve the contents the specified `url`, `method`, `parameters`, `encoding`,
 300     /// `headers` and save them to the `destination`.
 301     ///
 302     /// If `destination` is not specified, the contents will remain in the temporary location determined by the
 303     /// underlying URL session.
 304     ///
 305     /// If `startRequestsImmediately` is `true`, the request will have `resume()` called before being returned.
 306     ///
 307     /// - parameter url:         The URL.
 308     /// - parameter method:      The HTTP method. `.get` by default.
 309     /// - parameter parameters:  The parameters. `nil` by default.
 310     /// - parameter encoding:    The parameter encoding. `URLEncoding.default` by default.
 311     /// - parameter headers:     The HTTP headers. `nil` by default.
 312     /// - parameter destination: The closure used to determine the destination of the downloaded file. `nil` by default.
 313     ///
 314     /// - returns: The created `DownloadRequest`.
 315     @discardableResult
 316     open func download(
 317         _ url: URLConvertible,
 318         method: HTTPMethod = .get,
 319         parameters: Parameters? = nil,
 320         encoding: ParameterEncoding = URLEncoding.default,
 321         headers: HTTPHeaders? = nil,
 322         to destination: DownloadRequest.DownloadFileDestination? = nil)
 323         -> DownloadRequest
 324     {
 325         do {
 326             let urlRequest = try URLRequest(url: url, method: method, headers: headers)
 327             let encodedURLRequest = try encoding.encode(urlRequest, with: parameters)
 328             return download(encodedURLRequest, to: destination)
 329         } catch {
 330             return download(nil, to: destination, failedWith: error)
 331         }
 332     }
 333
 334     /// Creates a `DownloadRequest` to retrieve the contents of a URL based on the specified `urlRequest` and save
 335     /// them to the `destination`.
 336     ///
 337     /// If `destination` is not specified, the contents will remain in the temporary location determined by the
 338     /// underlying URL session.
 339     ///
 340     /// If `startRequestsImmediately` is `true`, the request will have `resume()` called before being returned.
 341     ///
 342     /// - parameter urlRequest:  The URL request
 343     /// - parameter destination: The closure used to determine the destination of the downloaded file. `nil` by default.
 344     ///
 345     /// - returns: The created `DownloadRequest`.
 346     @discardableResult
 347     open func download(
 348         _ urlRequest: URLRequestConvertible,
 349         to destination: DownloadRequest.DownloadFileDestination? = nil)
 350         -> DownloadRequest
 351     {
 352         do {
 353             let urlRequest = try urlRequest.asURLRequest()
 354             return download(.request(urlRequest), to: destination)
 355         } catch {
 356             return download(nil, to: destination, failedWith: error)
 357         }
 358     }
 359
 360     // MARK: Resume Data
 361
 362     /// Creates a `DownloadRequest` from the `resumeData` produced from a previous request cancellation to retrieve
 363     /// the contents of the original request and save them to the `destination`.
 364     ///
 365     /// If `destination` is not specified, the contents will remain in the temporary location determined by the
 366     /// underlying URL session.
 367     ///
 368     /// If `startRequestsImmediately` is `true`, the request will have `resume()` called before being returned.
 369     ///
 370     /// On the latest release of all the Apple platforms (iOS 10, macOS 10.12, tvOS 10, watchOS 3), `resumeData` is broken
 371     /// on background URL session configurations. There's an underlying bug in the `resumeData` generation logic where the
 372     /// data is written incorrectly and will always fail to resume the download. For more information about the bug and
 373     /// possible workarounds, please refer to the following Stack Overflow post:
 374     ///
 375     ///    - http://stackoverflow.com/a/39347461/1342462
 376     ///
 377     /// - parameter resumeData:  The resume data. This is an opaque data blob produced by `URLSessionDownloadTask`
 378     ///                          when a task is cancelled. See `URLSession -downloadTask(withResumeData:)` for
 379     ///                          additional information.
 380     /// - parameter destination: The closure used to determine the destination of the downloaded file. `nil` by default.
 381     ///
 382     /// - returns: The created `DownloadRequest`.
 383     @discardableResult
 384     open func download(
 385         resumingWith resumeData: Data,
 386         to destination: DownloadRequest.DownloadFileDestination? = nil)
 387         -> DownloadRequest
 388     {
 389         return download(.resumeData(resumeData), to: destination)
 390     }
 391
 392     // MARK: Private - Download Implementation
 393
 394     private func download(
 395         _ downloadable: DownloadRequest.Downloadable,
 396         to destination: DownloadRequest.DownloadFileDestination?)
 397         -> DownloadRequest
 398     {
 399         do {
 400             let task = try downloadable.task(session: session, adapter: adapter, queue: queue)
 401             let download = DownloadRequest(session: session, requestTask: .download(downloadable, task))
 402
 403             download.downloadDelegate.destination = destination
 404
 405             delegate[task] = download
 406
 407             if startRequestsImmediately { download.resume() }
 408
 409             return download
 410         } catch {
 411             return download(downloadable, to: destination, failedWith: error)
 412         }
 413     }
 414
 415     private func download(
 416         _ downloadable: DownloadRequest.Downloadable?,
 417         to destination: DownloadRequest.DownloadFileDestination?,
 418         failedWith error: Error)
 419         -> DownloadRequest
 420     {
 421         var downloadTask: Request.RequestTask = .download(nil, nil)
 422
 423         if let downloadable = downloadable {
 424             downloadTask = .download(downloadable, nil)
 425         }
 426
 427         let underlyingError = error.underlyingAdaptError ?? error
 428
 429         let download = DownloadRequest(session: session, requestTask: downloadTask, error: underlyingError)
 430         download.downloadDelegate.destination = destination
 431
 432         if let retrier = retrier, error is AdaptError {
 433             allowRetrier(retrier, toRetry: download, with: underlyingError)
 434         } else {
 435             if startRequestsImmediately { download.resume() }
 436         }
 437
 438         return download
 439     }
 440
 441     // MARK: - Upload Request
 442
 443     // MARK: File
 444
 445     /// Creates an `UploadRequest` from the specified `url`, `method` and `headers` for uploading the `file`.
 446     ///
 447     /// If `startRequestsImmediately` is `true`, the request will have `resume()` called before being returned.
 448     ///
 449     /// - parameter file:    The file to upload.
 450     /// - parameter url:     The URL.
 451     /// - parameter method:  The HTTP method. `.post` by default.
 452     /// - parameter headers: The HTTP headers. `nil` by default.
 453     ///
 454     /// - returns: The created `UploadRequest`.
 455     @discardableResult
 456     open func upload(
 457         _ fileURL: URL,
 458         to url: URLConvertible,
 459         method: HTTPMethod = .post,
 460         headers: HTTPHeaders? = nil)
 461         -> UploadRequest
 462     {
 463         do {
 464             let urlRequest = try URLRequest(url: url, method: method, headers: headers)
 465             return upload(fileURL, with: urlRequest)
 466         } catch {
 467             return upload(nil, failedWith: error)
 468         }
 469     }
 470
 471     /// Creates a `UploadRequest` from the specified `urlRequest` for uploading the `file`.
 472     ///
 473     /// If `startRequestsImmediately` is `true`, the request will have `resume()` called before being returned.
 474     ///
 475     /// - parameter file:       The file to upload.
 476     /// - parameter urlRequest: The URL request.
 477     ///
 478     /// - returns: The created `UploadRequest`.
 479     @discardableResult
 480     open func upload(_ fileURL: URL, with urlRequest: URLRequestConvertible) -> UploadRequest {
 481         do {
 482             let urlRequest = try urlRequest.asURLRequest()
 483             return upload(.file(fileURL, urlRequest))
 484         } catch {
 485             return upload(nil, failedWith: error)
 486         }
 487     }
 488
 489     // MARK: Data
 490
 491     /// Creates an `UploadRequest` from the specified `url`, `method` and `headers` for uploading the `data`.
 492     ///
 493     /// If `startRequestsImmediately` is `true`, the request will have `resume()` called before being returned.
 494     ///
 495     /// - parameter data:    The data to upload.
 496     /// - parameter url:     The URL.
 497     /// - parameter method:  The HTTP method. `.post` by default.
 498     /// - parameter headers: The HTTP headers. `nil` by default.
 499     ///
 500     /// - returns: The created `UploadRequest`.
 501     @discardableResult
 502     open func upload(
 503         _ data: Data,
 504         to url: URLConvertible,
 505         method: HTTPMethod = .post,
 506         headers: HTTPHeaders? = nil)
 507         -> UploadRequest
 508     {
 509         do {
 510             let urlRequest = try URLRequest(url: url, method: method, headers: headers)
 511             return upload(data, with: urlRequest)
 512         } catch {
 513             return upload(nil, failedWith: error)
 514         }
 515     }
 516
 517     /// Creates an `UploadRequest` from the specified `urlRequest` for uploading the `data`.
 518     ///
 519     /// If `startRequestsImmediately` is `true`, the request will have `resume()` called before being returned.
 520     ///
 521     /// - parameter data:       The data to upload.
 522     /// - parameter urlRequest: The URL request.
 523     ///
 524     /// - returns: The created `UploadRequest`.
 525     @discardableResult
 526     open func upload(_ data: Data, with urlRequest: URLRequestConvertible) -> UploadRequest {
 527         do {
 528             let urlRequest = try urlRequest.asURLRequest()
 529             return upload(.data(data, urlRequest))
 530         } catch {
 531             return upload(nil, failedWith: error)
 532         }
 533     }
 534
 535     // MARK: InputStream
 536
 537     /// Creates an `UploadRequest` from the specified `url`, `method` and `headers` for uploading the `stream`.
 538     ///
 539     /// If `startRequestsImmediately` is `true`, the request will have `resume()` called before being returned.
 540     ///
 541     /// - parameter stream:  The stream to upload.
 542     /// - parameter url:     The URL.
 543     /// - parameter method:  The HTTP method. `.post` by default.
 544     /// - parameter headers: The HTTP headers. `nil` by default.
 545     ///
 546     /// - returns: The created `UploadRequest`.
 547     @discardableResult
 548     open func upload(
 549         _ stream: InputStream,
 550         to url: URLConvertible,
 551         method: HTTPMethod = .post,
 552         headers: HTTPHeaders? = nil)
 553         -> UploadRequest
 554     {
 555         do {
 556             let urlRequest = try URLRequest(url: url, method: method, headers: headers)
 557             return upload(stream, with: urlRequest)
 558         } catch {
 559             return upload(nil, failedWith: error)
 560         }
 561     }
 562
 563     /// Creates an `UploadRequest` from the specified `urlRequest` for uploading the `stream`.
 564     ///
 565     /// If `startRequestsImmediately` is `true`, the request will have `resume()` called before being returned.
 566     ///
 567     /// - parameter stream:     The stream to upload.
 568     /// - parameter urlRequest: The URL request.
 569     ///
 570     /// - returns: The created `UploadRequest`.
 571     @discardableResult
 572     open func upload(_ stream: InputStream, with urlRequest: URLRequestConvertible) -> UploadRequest {
 573         do {
 574             let urlRequest = try urlRequest.asURLRequest()
 575             return upload(.stream(stream, urlRequest))
 576         } catch {
 577             return upload(nil, failedWith: error)
 578         }
 579     }
 580
 581     // MARK: MultipartFormData
 582
 583     /// Encodes `multipartFormData` using `encodingMemoryThreshold` and calls `encodingCompletion` with new
 584     /// `UploadRequest` using the `url`, `method` and `headers`.
 585     ///
 586     /// It is important to understand the memory implications of uploading `MultipartFormData`. If the cummulative
 587     /// payload is small, encoding the data in-memory and directly uploading to a server is the by far the most
 588     /// efficient approach. However, if the payload is too large, encoding the data in-memory could cause your app to
 589     /// be terminated. Larger payloads must first be written to disk using input and output streams to keep the memory
 590     /// footprint low, then the data can be uploaded as a stream from the resulting file. Streaming from disk MUST be
 591     /// used for larger payloads such as video content.
 592     ///
 593     /// The `encodingMemoryThreshold` parameter allows Alamofire to automatically determine whether to encode in-memory
 594     /// or stream from disk. If the content length of the `MultipartFormData` is below the `encodingMemoryThreshold`,
 595     /// encoding takes place in-memory. If the content length exceeds the threshold, the data is streamed to disk
 596     /// during the encoding process. Then the result is uploaded as data or as a stream depending on which encoding
 597     /// technique was used.
 598     ///
 599     /// If `startRequestsImmediately` is `true`, the request will have `resume()` called before being returned.
 600     ///
 601     /// - parameter multipartFormData:       The closure used to append body parts to the `MultipartFormData`.
 602     /// - parameter encodingMemoryThreshold: The encoding memory threshold in bytes.
 603     ///                                      `multipartFormDataEncodingMemoryThreshold` by default.
 604     /// - parameter url:                     The URL.
 605     /// - parameter method:                  The HTTP method. `.post` by default.
 606     /// - parameter headers:                 The HTTP headers. `nil` by default.
 607     /// - parameter encodingCompletion:      The closure called when the `MultipartFormData` encoding is complete.
 608     open func upload(
 609         multipartFormData: @escaping (MultipartFormData) -> Void,
 610         usingThreshold encodingMemoryThreshold: UInt64 = SessionManager.multipartFormDataEncodingMemoryThreshold,
 611         to url: URLConvertible,
 612         method: HTTPMethod = .post,
 613         headers: HTTPHeaders? = nil,
 614         encodingCompletion: ((MultipartFormDataEncodingResult) -> Void)?)
 615     {
 616         do {
 617             let urlRequest = try URLRequest(url: url, method: method, headers: headers)
 618
 619             return upload(
 620                 multipartFormData: multipartFormData,
 621                 usingThreshold: encodingMemoryThreshold,
 622                 with: urlRequest,
 623                 encodingCompletion: encodingCompletion
 624             )
 625         } catch {
 626             DispatchQueue.main.async { encodingCompletion?(.failure(error)) }
 627         }
 628     }
 629
 630     /// Encodes `multipartFormData` using `encodingMemoryThreshold` and calls `encodingCompletion` with new
 631     /// `UploadRequest` using the `urlRequest`.
 632     ///
 633     /// It is important to understand the memory implications of uploading `MultipartFormData`. If the cummulative
 634     /// payload is small, encoding the data in-memory and directly uploading to a server is the by far the most
 635     /// efficient approach. However, if the payload is too large, encoding the data in-memory could cause your app to
 636     /// be terminated. Larger payloads must first be written to disk using input and output streams to keep the memory
 637     /// footprint low, then the data can be uploaded as a stream from the resulting file. Streaming from disk MUST be
 638     /// used for larger payloads such as video content.
 639     ///
 640     /// The `encodingMemoryThreshold` parameter allows Alamofire to automatically determine whether to encode in-memory
 641     /// or stream from disk. If the content length of the `MultipartFormData` is below the `encodingMemoryThreshold`,
 642     /// encoding takes place in-memory. If the content length exceeds the threshold, the data is streamed to disk
 643     /// during the encoding process. Then the result is uploaded as data or as a stream depending on which encoding
 644     /// technique was used.
 645     ///
 646     /// If `startRequestsImmediately` is `true`, the request will have `resume()` called before being returned.
 647     ///
 648     /// - parameter multipartFormData:       The closure used to append body parts to the `MultipartFormData`.
 649     /// - parameter encodingMemoryThreshold: The encoding memory threshold in bytes.
 650     ///                                      `multipartFormDataEncodingMemoryThreshold` by default.
 651     /// - parameter urlRequest:              The URL request.
 652     /// - parameter encodingCompletion:      The closure called when the `MultipartFormData` encoding is complete.
 653     open func upload(
 654         multipartFormData: @escaping (MultipartFormData) -> Void,
 655         usingThreshold encodingMemoryThreshold: UInt64 = SessionManager.multipartFormDataEncodingMemoryThreshold,
 656         with urlRequest: URLRequestConvertible,
 657         encodingCompletion: ((MultipartFormDataEncodingResult) -> Void)?)
 658     {
 659         DispatchQueue.global(qos: .utility).async {
 660             let formData = MultipartFormData()
 661             multipartFormData(formData)
 662
 663             var tempFileURL: URL?
 664
 665             do {
 666                 var urlRequestWithContentType = try urlRequest.asURLRequest()
 667                 urlRequestWithContentType.setValue(formData.contentType, forHTTPHeaderField: "Content-Type")
 668
 669                 let isBackgroundSession = self.session.configuration.identifier != nil
 670
 671                 if formData.contentLength < encodingMemoryThreshold && !isBackgroundSession {
 672                     let data = try formData.encode()
 673
 674                     let encodingResult = MultipartFormDataEncodingResult.success(
 675                         request: self.upload(data, with: urlRequestWithContentType),
 676                         streamingFromDisk: false,
 677                         streamFileURL: nil
 678                     )
 679
 680                     DispatchQueue.main.async { encodingCompletion?(encodingResult) }
 681                 } else {
 682                     let fileManager = FileManager.default
 683                     let tempDirectoryURL = URL(fileURLWithPath: NSTemporaryDirectory())
 684                     let directoryURL = tempDirectoryURL.appendingPathComponent("org.alamofire.manager/multipart.form.data")
 685                     let fileName = UUID().uuidString
 686                     let fileURL = directoryURL.appendingPathComponent(fileName)
 687
 688                     tempFileURL = fileURL
 689
 690                     var directoryError: Error?
 691
 692                     // Create directory inside serial queue to ensure two threads don't do this in parallel
 693                     self.queue.sync {
 694                         do {
 695                             try fileManager.createDirectory(at: directoryURL, withIntermediateDirectories: true, attributes: nil)
 696                         } catch {
 697                             directoryError = error
 698                         }
 699                     }
 700
 701                     if let directoryError = directoryError { throw directoryError }
 702
 703                     try formData.writeEncodedData(to: fileURL)
 704
 705                     let upload = self.upload(fileURL, with: urlRequestWithContentType)
 706
 707                     // Cleanup the temp file once the upload is complete
 708                     upload.delegate.queue.addOperation {
 709                         do {
 710                             try FileManager.default.removeItem(at: fileURL)
 711                         } catch {
 712                             // No-op
 713                         }
 714                     }
 715
 716                     DispatchQueue.main.async {
 717                         let encodingResult = MultipartFormDataEncodingResult.success(
 718                             request: upload,
 719                             streamingFromDisk: true,
 720                             streamFileURL: fileURL
 721                         )
 722
 723                         encodingCompletion?(encodingResult)
 724                     }
 725                 }
 726             } catch {
 727                 // Cleanup the temp file in the event that the multipart form data encoding failed
 728                 if let tempFileURL = tempFileURL {
 729                     do {
 730                         try FileManager.default.removeItem(at: tempFileURL)
 731                     } catch {
 732                         // No-op
 733                     }
 734                 }
 735
 736                 DispatchQueue.main.async { encodingCompletion?(.failure(error)) }
 737             }
 738         }
 739     }
 740
 741     // MARK: Private - Upload Implementation
 742
 743     private func upload(_ uploadable: UploadRequest.Uploadable) -> UploadRequest {
 744         do {
 745             let task = try uploadable.task(session: session, adapter: adapter, queue: queue)
 746             let upload = UploadRequest(session: session, requestTask: .upload(uploadable, task))
 747
 748             if case let .stream(inputStream, _) = uploadable {
 749                 upload.delegate.taskNeedNewBodyStream = { _, _ in inputStream }
 750             }
 751
 752             delegate[task] = upload
 753
 754             if startRequestsImmediately { upload.resume() }
 755
 756             return upload
 757         } catch {
 758             return upload(uploadable, failedWith: error)
 759         }
 760     }
 761
 762     private func upload(_ uploadable: UploadRequest.Uploadable?, failedWith error: Error) -> UploadRequest {
 763         var uploadTask: Request.RequestTask = .upload(nil, nil)
 764
 765         if let uploadable = uploadable {
 766             uploadTask = .upload(uploadable, nil)
 767         }
 768
 769         let underlyingError = error.underlyingAdaptError ?? error
 770         let upload = UploadRequest(session: session, requestTask: uploadTask, error: underlyingError)
 771
 772         if let retrier = retrier, error is AdaptError {
 773             allowRetrier(retrier, toRetry: upload, with: underlyingError)
 774         } else {
 775             if startRequestsImmediately { upload.resume() }
 776         }
 777
 778         return upload
 779     }
 780
 781 #if !os(watchOS)
 782
 783     // MARK: - Stream Request
 784
 785     // MARK: Hostname and Port
 786
 787     /// Creates a `StreamRequest` for bidirectional streaming using the `hostname` and `port`.
 788     ///
 789     /// If `startRequestsImmediately` is `true`, the request will have `resume()` called before being returned.
 790     ///
 791     /// - parameter hostName: The hostname of the server to connect to.
 792     /// - parameter port:     The port of the server to connect to.
 793     ///
 794     /// - returns: The created `StreamRequest`.
 795     @discardableResult
 796     @available(iOS 9.0, macOS 10.11, tvOS 9.0, *)
 797     open func stream(withHostName hostName: String, port: Int) -> StreamRequest {
 798         return stream(.stream(hostName: hostName, port: port))
 799     }
 800
 801     // MARK: NetService
 802
 803     /// Creates a `StreamRequest` for bidirectional streaming using the `netService`.
 804     ///
 805     /// If `startRequestsImmediately` is `true`, the request will have `resume()` called before being returned.
 806     ///
 807     /// - parameter netService: The net service used to identify the endpoint.
 808     ///
 809     /// - returns: The created `StreamRequest`.
 810     @discardableResult
 811     @available(iOS 9.0, macOS 10.11, tvOS 9.0, *)
 812     open func stream(with netService: NetService) -> StreamRequest {
 813         return stream(.netService(netService))
 814     }
 815
 816     // MARK: Private - Stream Implementation
 817
 818     @available(iOS 9.0, macOS 10.11, tvOS 9.0, *)
 819     private func stream(_ streamable: StreamRequest.Streamable) -> StreamRequest {
 820         do {
 821             let task = try streamable.task(session: session, adapter: adapter, queue: queue)
 822             let request = StreamRequest(session: session, requestTask: .stream(streamable, task))
 823
 824             delegate[task] = request
 825
 826             if startRequestsImmediately { request.resume() }
 827
 828             return request
 829         } catch {
 830             return stream(failedWith: error)
 831         }
 832     }
 833
 834     @available(iOS 9.0, macOS 10.11, tvOS 9.0, *)
 835     private func stream(failedWith error: Error) -> StreamRequest {
 836         let stream = StreamRequest(session: session, requestTask: .stream(nil, nil), error: error)
 837         if startRequestsImmediately { stream.resume() }
 838         return stream
 839     }
 840
 841 #endif
 842
 843     // MARK: - Internal - Retry Request
 844
 845     func retry(_ request: Request) -> Bool {
 846         guard let originalTask = request.originalTask else { return false }
 847
 848         do {
 849             let task = try originalTask.task(session: session, adapter: adapter, queue: queue)
 850
 851             request.delegate.task = task // resets all task delegate data
 852
 853             request.retryCount += 1
 854             request.startTime = CFAbsoluteTimeGetCurrent()
 855             request.endTime = nil
 856
 857             task.resume()
 858
 859             return true
 860         } catch {
 861             request.delegate.error = error.underlyingAdaptError ?? error
 862             return false
 863         }
 864     }
 865
 866     private func allowRetrier(_ retrier: RequestRetrier, toRetry request: Request, with error: Error) {
 867         DispatchQueue.utility.async { [weak self] in
 868             guard let strongSelf = self else { return }
 869
 870             retrier.should(strongSelf, retry: request, with: error) { shouldRetry, timeDelay in
 871                 guard let strongSelf = self else { return }
 872
 873                 guard shouldRetry else {
 874                     if strongSelf.startRequestsImmediately { request.resume() }
 875                     return
 876                 }
 877
 878                 DispatchQueue.utility.after(timeDelay) {
 879                     guard let strongSelf = self else { return }
 880
 881                     let retrySucceeded = strongSelf.retry(request)
 882
 883                     if retrySucceeded, let task = request.task {
 884                         strongSelf.delegate[task] = request
 885                     } else {
 886                         if strongSelf.startRequestsImmediately { request.resume() }
 887                     }
 888                 }
 889             }
 890         }
 891     }
 892 }