Proyectos de Subversion Iphone Microlearning

//

//  Request.swift

//

//  Copyright (c) 2014-2020 Alamofire Software Foundation (http://alamofire.org/)

//

//  Permission is hereby granted, free of charge, to any person obtaining a copy

//  of this software and associated documentation files (the "Software"), to deal

//  in the Software without restriction, including without limitation the rights

//  to use, copy, modify, merge, publish, distribute, sublicense, and/or sell

//  copies of the Software, and to permit persons to whom the Software is

//  furnished to do so, subject to the following conditions:

//

//  The above copyright notice and this permission notice shall be included in

//  all copies or substantial portions of the Software.

//

//  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR

//  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,

//  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE

//  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER

//  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,

//  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN

//  THE SOFTWARE.

//

import Foundation

/// `Request` is the common superclass of all Alamofire request types and provides common state, delegate, and callback

/// handling.

public class Request {

    /// State of the `Request`, with managed transitions between states set when calling `resume()`, `suspend()`, or

    /// `cancel()` on the `Request`.

    public enum State {

        /// Initial state of the `Request`.

        case initialized

        /// `State` set when `resume()` is called. Any tasks created for the `Request` will have `resume()` called on

        /// them in this state.

        case resumed

        /// `State` set when `suspend()` is called. Any tasks created for the `Request` will have `suspend()` called on

        /// them in this state.

        case suspended

        /// `State` set when `cancel()` is called. Any tasks created for the `Request` will have `cancel()` called on

        /// them. Unlike `resumed` or `suspended`, once in the `cancelled` state, the `Request` can no longer transition

        /// to any other state.

        case cancelled

        /// `State` set when all response serialization completion closures have been cleared on the `Request` and

        /// enqueued on their respective queues.

        case finished

        /// Determines whether `self` can be transitioned to the provided `State`.

        func canTransitionTo(_ state: State) -> Bool {

            switch (self, state) {

            case (.initialized, _):

                return true

            case (_, .initialized), (.cancelled, _), (.finished, _):

                return false

            case (.resumed, .cancelled), (.suspended, .cancelled), (.resumed, .suspended), (.suspended, .resumed):

                return true

            case (.suspended, .suspended), (.resumed, .resumed):

                return false

            case (_, .finished):

                return true

            }

        }

    }

    // MARK: - Initial State

    /// `UUID` providing a unique identifier for the `Request`, used in the `Hashable` and `Equatable` conformances.

    public let id: UUID

    /// The serial queue for all internal async actions.

    public let underlyingQueue: DispatchQueue

    /// The queue used for all serialization actions. By default it's a serial queue that targets `underlyingQueue`.

    public let serializationQueue: DispatchQueue

    /// `EventMonitor` used for event callbacks.

    public let eventMonitor: EventMonitor?

    /// The `Request`'s interceptor.

    public let interceptor: RequestInterceptor?

    /// The `Request`'s delegate.

    public private(set) weak var delegate: RequestDelegate?

    // MARK: - Mutable State

    /// Type encapsulating all mutable state that may need to be accessed from anything other than the `underlyingQueue`.

    struct MutableState {

        /// State of the `Request`.

        var state: State = .initialized

        /// `ProgressHandler` and `DispatchQueue` provided for upload progress callbacks.

        var uploadProgressHandler: (handler: ProgressHandler, queue: DispatchQueue)?

        /// `ProgressHandler` and `DispatchQueue` provided for download progress callbacks.

        var downloadProgressHandler: (handler: ProgressHandler, queue: DispatchQueue)?

        /// `RedirectHandler` provided for to handle request redirection.

        var redirectHandler: RedirectHandler?

        /// `CachedResponseHandler` provided to handle response caching.

        var cachedResponseHandler: CachedResponseHandler?

        /// Queue and closure called when the `Request` is able to create a cURL description of itself.

        var cURLHandler: (queue: DispatchQueue, handler: (String) -> Void)?

        /// Queue and closure called when the `Request` creates a `URLRequest`.

        var urlRequestHandler: (queue: DispatchQueue, handler: (URLRequest) -> Void)?

        /// Queue and closure called when the `Request` creates a `URLSessionTask`.

        var urlSessionTaskHandler: (queue: DispatchQueue, handler: (URLSessionTask) -> Void)?

        /// Response serialization closures that handle response parsing.

        var responseSerializers: [() -> Void] = []

        /// Response serialization completion closures executed once all response serializers are complete.

        var responseSerializerCompletions: [() -> Void] = []

        /// Whether response serializer processing is finished.

        var responseSerializerProcessingFinished = false

        /// `URLCredential` used for authentication challenges.

        var credential: URLCredential?

        /// All `URLRequest`s created by Alamofire on behalf of the `Request`.

        var requests: [URLRequest] = []

        /// All `URLSessionTask`s created by Alamofire on behalf of the `Request`.

        var tasks: [URLSessionTask] = []

        /// All `URLSessionTaskMetrics` values gathered by Alamofire on behalf of the `Request`. Should correspond

        /// exactly the the `tasks` created.

        var metrics: [URLSessionTaskMetrics] = []

        /// Number of times any retriers provided retried the `Request`.

        var retryCount = 0

        /// Final `AFError` for the `Request`, whether from various internal Alamofire calls or as a result of a `task`.

        var error: AFError?

        /// Whether the instance has had `finish()` called and is running the serializers. Should be replaced with a

        /// representation in the state machine in the future.

        var isFinishing = false

        /// Actions to run when requests are finished. Use for concurrency support.

        var finishHandlers: [() -> Void] = []

    }

    /// Protected `MutableState` value that provides thread-safe access to state values.

    @Protected

    fileprivate var mutableState = MutableState()

    /// `State` of the `Request`.

    public var state: State { $mutableState.state }

    /// Returns whether `state` is `.initialized`.

    public var isInitialized: Bool { state == .initialized }

    /// Returns whether `state is `.resumed`.

    public var isResumed: Bool { state == .resumed }

    /// Returns whether `state` is `.suspended`.

    public var isSuspended: Bool { state == .suspended }

    /// Returns whether `state` is `.cancelled`.

    public var isCancelled: Bool { state == .cancelled }

    /// Returns whether `state` is `.finished`.

    public var isFinished: Bool { state == .finished }

    // MARK: Progress

    /// Closure type executed when monitoring the upload or download progress of a request.

    public typealias ProgressHandler = (Progress) -> Void

    /// `Progress` of the upload of the body of the executed `URLRequest`. Reset to `0` if the `Request` is retried.

    public let uploadProgress = Progress(totalUnitCount: 0)

    /// `Progress` of the download of any response data. Reset to `0` if the `Request` is retried.

    public let downloadProgress = Progress(totalUnitCount: 0)

    /// `ProgressHandler` called when `uploadProgress` is updated, on the provided `DispatchQueue`.

    private var uploadProgressHandler: (handler: ProgressHandler, queue: DispatchQueue)? {

        get { $mutableState.uploadProgressHandler }

        set { $mutableState.uploadProgressHandler = newValue }

    }

    /// `ProgressHandler` called when `downloadProgress` is updated, on the provided `DispatchQueue`.

    fileprivate var downloadProgressHandler: (handler: ProgressHandler, queue: DispatchQueue)? {

        get { $mutableState.downloadProgressHandler }

        set { $mutableState.downloadProgressHandler = newValue }

    }

    // MARK: Redirect Handling

    /// `RedirectHandler` set on the instance.

    public private(set) var redirectHandler: RedirectHandler? {

        get { $mutableState.redirectHandler }

        set { $mutableState.redirectHandler = newValue }

    }

    // MARK: Cached Response Handling

    /// `CachedResponseHandler` set on the instance.

    public private(set) var cachedResponseHandler: CachedResponseHandler? {

        get { $mutableState.cachedResponseHandler }

        set { $mutableState.cachedResponseHandler = newValue }

    }

    // MARK: URLCredential

    /// `URLCredential` used for authentication challenges. Created by calling one of the `authenticate` methods.

    public private(set) var credential: URLCredential? {

        get { $mutableState.credential }

        set { $mutableState.credential = newValue }

    }

    // MARK: Validators

    /// `Validator` callback closures that store the validation calls enqueued.

    @Protected

    fileprivate var validators: [() -> Void] = []

    // MARK: URLRequests

    /// All `URLRequests` created on behalf of the `Request`, including original and adapted requests.

    public var requests: [URLRequest] { $mutableState.requests }

    /// First `URLRequest` created on behalf of the `Request`. May not be the first one actually executed.

    public var firstRequest: URLRequest? { requests.first }

    /// Last `URLRequest` created on behalf of the `Request`.

    public var lastRequest: URLRequest? { requests.last }

    /// Current `URLRequest` created on behalf of the `Request`.

    public var request: URLRequest? { lastRequest }

    /// `URLRequest`s from all of the `URLSessionTask`s executed on behalf of the `Request`. May be different from

    /// `requests` due to `URLSession` manipulation.

    public var performedRequests: [URLRequest] { $mutableState.read { $0.tasks.compactMap(\.currentRequest) } }

    // MARK: HTTPURLResponse

    /// `HTTPURLResponse` received from the server, if any. If the `Request` was retried, this is the response of the

    /// last `URLSessionTask`.

    public var response: HTTPURLResponse? { lastTask?.response as? HTTPURLResponse }

    // MARK: Tasks

    /// All `URLSessionTask`s created on behalf of the `Request`.

    public var tasks: [URLSessionTask] { $mutableState.tasks }

    /// First `URLSessionTask` created on behalf of the `Request`.

    public var firstTask: URLSessionTask? { tasks.first }

    /// Last `URLSessionTask` crated on behalf of the `Request`.

    public var lastTask: URLSessionTask? { tasks.last }

    /// Current `URLSessionTask` created on behalf of the `Request`.

    public var task: URLSessionTask? { lastTask }

    // MARK: Metrics

    /// All `URLSessionTaskMetrics` gathered on behalf of the `Request`. Should correspond to the `tasks` created.

    public var allMetrics: [URLSessionTaskMetrics] { $mutableState.metrics }

    /// First `URLSessionTaskMetrics` gathered on behalf of the `Request`.

    public var firstMetrics: URLSessionTaskMetrics? { allMetrics.first }

    /// Last `URLSessionTaskMetrics` gathered on behalf of the `Request`.

    public var lastMetrics: URLSessionTaskMetrics? { allMetrics.last }

    /// Current `URLSessionTaskMetrics` gathered on behalf of the `Request`.

    public var metrics: URLSessionTaskMetrics? { lastMetrics }

    // MARK: Retry Count

    /// Number of times the `Request` has been retried.

    public var retryCount: Int { $mutableState.retryCount }

    // MARK: Error

    /// `Error` returned from Alamofire internally, from the network request directly, or any validators executed.

    public fileprivate(set) var error: AFError? {

        get { $mutableState.error }

        set { $mutableState.error = newValue }

    }

    /// Default initializer for the `Request` superclass.

    ///

    /// - Parameters:

    ///   - id:                 `UUID` used for the `Hashable` and `Equatable` implementations. `UUID()` by default.

    ///   - underlyingQueue:    `DispatchQueue` on which all internal `Request` work is performed.

    ///   - serializationQueue: `DispatchQueue` on which all serialization work is performed. By default targets

    ///                         `underlyingQueue`, but can be passed another queue from a `Session`.

    ///   - eventMonitor:       `EventMonitor` called for event callbacks from internal `Request` actions.

    ///   - interceptor:        `RequestInterceptor` used throughout the request lifecycle.

    ///   - delegate:           `RequestDelegate` that provides an interface to actions not performed by the `Request`.

    init(id: UUID = UUID(),

         underlyingQueue: DispatchQueue,

         serializationQueue: DispatchQueue,

         eventMonitor: EventMonitor?,

         interceptor: RequestInterceptor?,

         delegate: RequestDelegate) {

        self.id = id

        self.underlyingQueue = underlyingQueue

        self.serializationQueue = serializationQueue

        self.eventMonitor = eventMonitor

        self.interceptor = interceptor

        self.delegate = delegate

    }

    // MARK: - Internal Event API

    // All API must be called from underlyingQueue.

    /// Called when an initial `URLRequest` has been created on behalf of the instance. If a `RequestAdapter` is active,

    /// the `URLRequest` will be adapted before being issued.

    ///

    /// - Parameter request: The `URLRequest` created.

    func didCreateInitialURLRequest(_ request: URLRequest) {

        dispatchPrecondition(condition: .onQueue(underlyingQueue))

        $mutableState.write { $0.requests.append(request) }

        eventMonitor?.request(self, didCreateInitialURLRequest: request)

    }

    /// Called when initial `URLRequest` creation has failed, typically through a `URLRequestConvertible`.

    ///

    /// - Note: Triggers retry.

    ///

    /// - Parameter error: `AFError` thrown from the failed creation.

    func didFailToCreateURLRequest(with error: AFError) {

        dispatchPrecondition(condition: .onQueue(underlyingQueue))

        self.error = error

        eventMonitor?.request(self, didFailToCreateURLRequestWithError: error)

        callCURLHandlerIfNecessary()

        retryOrFinish(error: error)

    }

    /// Called when a `RequestAdapter` has successfully adapted a `URLRequest`.

    ///

    /// - Parameters:

    ///   - initialRequest: The `URLRequest` that was adapted.

    ///   - adaptedRequest: The `URLRequest` returned by the `RequestAdapter`.

    func didAdaptInitialRequest(_ initialRequest: URLRequest, to adaptedRequest: URLRequest) {

        dispatchPrecondition(condition: .onQueue(underlyingQueue))

        $mutableState.write { $0.requests.append(adaptedRequest) }

        eventMonitor?.request(self, didAdaptInitialRequest: initialRequest, to: adaptedRequest)

    }

    /// Called when a `RequestAdapter` fails to adapt a `URLRequest`.

    ///

    /// - Note: Triggers retry.

    ///

    /// - Parameters:

    ///   - request: The `URLRequest` the adapter was called with.

    ///   - error:   The `AFError` returned by the `RequestAdapter`.

    func didFailToAdaptURLRequest(_ request: URLRequest, withError error: AFError) {

        dispatchPrecondition(condition: .onQueue(underlyingQueue))

        self.error = error

        eventMonitor?.request(self, didFailToAdaptURLRequest: request, withError: error)

        callCURLHandlerIfNecessary()

        retryOrFinish(error: error)

    }

    /// Final `URLRequest` has been created for the instance.

    ///

    /// - Parameter request: The `URLRequest` created.

    func didCreateURLRequest(_ request: URLRequest) {

        dispatchPrecondition(condition: .onQueue(underlyingQueue))

        $mutableState.read { state in

            state.urlRequestHandler?.queue.async { state.urlRequestHandler?.handler(request) }

        }

        eventMonitor?.request(self, didCreateURLRequest: request)

        callCURLHandlerIfNecessary()

    }

    /// Asynchronously calls any stored `cURLHandler` and then removes it from `mutableState`.

    private func callCURLHandlerIfNecessary() {

        $mutableState.write { mutableState in

            guard let cURLHandler = mutableState.cURLHandler else { return }

            cURLHandler.queue.async { cURLHandler.handler(self.cURLDescription()) }

            mutableState.cURLHandler = nil

        }

    }

    /// Called when a `URLSessionTask` is created on behalf of the instance.

    ///

    /// - Parameter task: The `URLSessionTask` created.

    func didCreateTask(_ task: URLSessionTask) {

        dispatchPrecondition(condition: .onQueue(underlyingQueue))

        $mutableState.write { state in

            state.tasks.append(task)

            guard let urlSessionTaskHandler = state.urlSessionTaskHandler else { return }

            urlSessionTaskHandler.queue.async { urlSessionTaskHandler.handler(task) }

        }

        eventMonitor?.request(self, didCreateTask: task)

    }

    /// Called when resumption is completed.

    func didResume() {

        dispatchPrecondition(condition: .onQueue(underlyingQueue))

        eventMonitor?.requestDidResume(self)

    }

    /// Called when a `URLSessionTask` is resumed on behalf of the instance.

    ///

    /// - Parameter task: The `URLSessionTask` resumed.

    func didResumeTask(_ task: URLSessionTask) {

        dispatchPrecondition(condition: .onQueue(underlyingQueue))

        eventMonitor?.request(self, didResumeTask: task)

    }

    /// Called when suspension is completed.

    func didSuspend() {

        dispatchPrecondition(condition: .onQueue(underlyingQueue))

        eventMonitor?.requestDidSuspend(self)

    }

    /// Called when a `URLSessionTask` is suspended on behalf of the instance.

    ///

    /// - Parameter task: The `URLSessionTask` suspended.

    func didSuspendTask(_ task: URLSessionTask) {

        dispatchPrecondition(condition: .onQueue(underlyingQueue))

        eventMonitor?.request(self, didSuspendTask: task)

    }

    /// Called when cancellation is completed, sets `error` to `AFError.explicitlyCancelled`.

    func didCancel() {

        dispatchPrecondition(condition: .onQueue(underlyingQueue))

        error = error ?? AFError.explicitlyCancelled

        eventMonitor?.requestDidCancel(self)

    }

    /// Called when a `URLSessionTask` is cancelled on behalf of the instance.

    ///

    /// - Parameter task: The `URLSessionTask` cancelled.

    func didCancelTask(_ task: URLSessionTask) {

        dispatchPrecondition(condition: .onQueue(underlyingQueue))

        eventMonitor?.request(self, didCancelTask: task)

    }

    /// Called when a `URLSessionTaskMetrics` value is gathered on behalf of the instance.

    ///

    /// - Parameter metrics: The `URLSessionTaskMetrics` gathered.

    func didGatherMetrics(_ metrics: URLSessionTaskMetrics) {

        dispatchPrecondition(condition: .onQueue(underlyingQueue))

        $mutableState.write { $0.metrics.append(metrics) }

        eventMonitor?.request(self, didGatherMetrics: metrics)

    }

    /// Called when a `URLSessionTask` fails before it is finished, typically during certificate pinning.

    ///

    /// - Parameters:

    ///   - task:  The `URLSessionTask` which failed.

    ///   - error: The early failure `AFError`.

    func didFailTask(_ task: URLSessionTask, earlyWithError error: AFError) {

        dispatchPrecondition(condition: .onQueue(underlyingQueue))

        self.error = error

        // Task will still complete, so didCompleteTask(_:with:) will handle retry.

        eventMonitor?.request(self, didFailTask: task, earlyWithError: error)

    }

    /// Called when a `URLSessionTask` completes. All tasks will eventually call this method.

    ///

    /// - Note: Response validation is synchronously triggered in this step.

    ///

    /// - Parameters:

    ///   - task:  The `URLSessionTask` which completed.

    ///   - error: The `AFError` `task` may have completed with. If `error` has already been set on the instance, this

    ///            value is ignored.

    func didCompleteTask(_ task: URLSessionTask, with error: AFError?) {

        dispatchPrecondition(condition: .onQueue(underlyingQueue))

        self.error = self.error ?? error

        validators.forEach { $0() }

        eventMonitor?.request(self, didCompleteTask: task, with: error)

        retryOrFinish(error: self.error)

    }

    /// Called when the `RequestDelegate` is going to retry this `Request`. Calls `reset()`.

    func prepareForRetry() {

        dispatchPrecondition(condition: .onQueue(underlyingQueue))

        $mutableState.write { $0.retryCount += 1 }

        reset()

        eventMonitor?.requestIsRetrying(self)

    }

    /// Called to determine whether retry will be triggered for the particular error, or whether the instance should

    /// call `finish()`.

    ///

    /// - Parameter error: The possible `AFError` which may trigger retry.

    func retryOrFinish(error: AFError?) {

        dispatchPrecondition(condition: .onQueue(underlyingQueue))

        guard let error = error, let delegate = delegate else { finish(); return }

        delegate.retryResult(for: self, dueTo: error) { retryResult in

            switch retryResult {

            case .doNotRetry:

                self.finish()

            case let .doNotRetryWithError(retryError):

                self.finish(error: retryError.asAFError(orFailWith: "Received retryError was not already AFError"))

            case .retry, .retryWithDelay:

                delegate.retryRequest(self, withDelay: retryResult.delay)

            }

        }

    }

    /// Finishes this `Request` and starts the response serializers.

    ///

    /// - Parameter error: The possible `Error` with which the instance will finish.

    func finish(error: AFError? = nil) {

        dispatchPrecondition(condition: .onQueue(underlyingQueue))

        guard !$mutableState.isFinishing else { return }

        $mutableState.isFinishing = true

        if let error = error { self.error = error }

        // Start response handlers

        processNextResponseSerializer()

        eventMonitor?.requestDidFinish(self)

    }

    /// Appends the response serialization closure to the instance.

    ///

    ///  - Note: This method will also `resume` the instance if `delegate.startImmediately` returns `true`.

    ///

    /// - Parameter closure: The closure containing the response serialization call.

    func appendResponseSerializer(_ closure: @escaping () -> Void) {

        $mutableState.write { mutableState in

            mutableState.responseSerializers.append(closure)

            if mutableState.state == .finished {

                mutableState.state = .resumed

            }

            if mutableState.responseSerializerProcessingFinished {

                underlyingQueue.async { self.processNextResponseSerializer() }

            }

            if mutableState.state.canTransitionTo(.resumed) {

                underlyingQueue.async { if self.delegate?.startImmediately == true { self.resume() } }

            }

        }

    }

    /// Returns the next response serializer closure to execute if there's one left.

    ///

    /// - Returns: The next response serialization closure, if there is one.

    func nextResponseSerializer() -> (() -> Void)? {

        var responseSerializer: (() -> Void)?

        $mutableState.write { mutableState in

            let responseSerializerIndex = mutableState.responseSerializerCompletions.count

            if responseSerializerIndex < mutableState.responseSerializers.count {

                responseSerializer = mutableState.responseSerializers[responseSerializerIndex]

            }

        }

        return responseSerializer

    }

    /// Processes the next response serializer and calls all completions if response serialization is complete.

    func processNextResponseSerializer() {

        guard let responseSerializer = nextResponseSerializer() else {

            // Execute all response serializer completions and clear them

            var completions: [() -> Void] = []

            $mutableState.write { mutableState in

                completions = mutableState.responseSerializerCompletions

                // Clear out all response serializers and response serializer completions in mutable state since the

                // request is complete. It's important to do this prior to calling the completion closures in case

                // the completions call back into the request triggering a re-processing of the response serializers.

                // An example of how this can happen is by calling cancel inside a response completion closure.

                mutableState.responseSerializers.removeAll()

                mutableState.responseSerializerCompletions.removeAll()

                if mutableState.state.canTransitionTo(.finished) {

                    mutableState.state = .finished

                }

                mutableState.responseSerializerProcessingFinished = true

                mutableState.isFinishing = false

            }

            completions.forEach { $0() }

            // Cleanup the request

            cleanup()

            return

        }

        serializationQueue.async { responseSerializer() }

    }

    /// Notifies the `Request` that the response serializer is complete.

    ///

    /// - Parameter completion: The completion handler provided with the response serializer, called when all serializers

    ///                         are complete.

    func responseSerializerDidComplete(completion: @escaping () -> Void) {

        $mutableState.write { $0.responseSerializerCompletions.append(completion) }

        processNextResponseSerializer()

    }

    /// Resets all task and response serializer related state for retry.

    func reset() {

        error = nil

        uploadProgress.totalUnitCount = 0

        uploadProgress.completedUnitCount = 0

        downloadProgress.totalUnitCount = 0

        downloadProgress.completedUnitCount = 0

        $mutableState.write { state in

            state.isFinishing = false

            state.responseSerializerCompletions = []

        }

    }

    /// Called when updating the upload progress.

    ///

    /// - Parameters:

    ///   - totalBytesSent: Total bytes sent so far.

    ///   - totalBytesExpectedToSend: Total bytes expected to send.

    func updateUploadProgress(totalBytesSent: Int64, totalBytesExpectedToSend: Int64) {

        uploadProgress.totalUnitCount = totalBytesExpectedToSend

        uploadProgress.completedUnitCount = totalBytesSent

        uploadProgressHandler?.queue.async { self.uploadProgressHandler?.handler(self.uploadProgress) }

    }

    /// Perform a closure on the current `state` while locked.

    ///

    /// - Parameter perform: The closure to perform.

    func withState(perform: (State) -> Void) {

        $mutableState.withState(perform: perform)

    }

    // MARK: Task Creation

    /// Called when creating a `URLSessionTask` for this `Request`. Subclasses must override.

    ///

    /// - Parameters:

    ///   - request: `URLRequest` to use to create the `URLSessionTask`.

    ///   - session: `URLSession` which creates the `URLSessionTask`.

    ///

    /// - Returns:   The `URLSessionTask` created.

    func task(for request: URLRequest, using session: URLSession) -> URLSessionTask {

        fatalError("Subclasses must override.")

    }

    // MARK: - Public API

    // These APIs are callable from any queue.

    // MARK: State

    /// Cancels the instance. Once cancelled, a `Request` can no longer be resumed or suspended.

    ///

    /// - Returns: The instance.

    @discardableResult

    public func cancel() -> Self {

        $mutableState.write { mutableState in

            guard mutableState.state.canTransitionTo(.cancelled) else { return }

            mutableState.state = .cancelled

            underlyingQueue.async { self.didCancel() }

            guard let task = mutableState.tasks.last, task.state != .completed else {

                underlyingQueue.async { self.finish() }

                return

            }

            // Resume to ensure metrics are gathered.

            task.resume()

            task.cancel()

            underlyingQueue.async { self.didCancelTask(task) }

        }

        return self

    }

    /// Suspends the instance.

    ///

    /// - Returns: The instance.

    @discardableResult

    public func suspend() -> Self {

        $mutableState.write { mutableState in

            guard mutableState.state.canTransitionTo(.suspended) else { return }

            mutableState.state = .suspended

            underlyingQueue.async { self.didSuspend() }

            guard let task = mutableState.tasks.last, task.state != .completed else { return }

            task.suspend()

            underlyingQueue.async { self.didSuspendTask(task) }

        }

        return self

    }

    /// Resumes the instance.

    ///

    /// - Returns: The instance.

    @discardableResult

    public func resume() -> Self {

        $mutableState.write { mutableState in

            guard mutableState.state.canTransitionTo(.resumed) else { return }

            mutableState.state = .resumed

            underlyingQueue.async { self.didResume() }

            guard let task = mutableState.tasks.last, task.state != .completed else { return }

            task.resume()

            underlyingQueue.async { self.didResumeTask(task) }

        }

        return self

    }

    // MARK: - Closure API

    /// Associates a credential using the provided values with the instance.

    ///

    /// - Parameters:

    ///   - username:    The username.

    ///   - password:    The password.

    ///   - persistence: The `URLCredential.Persistence` for the created `URLCredential`. `.forSession` by default.

    ///

    /// - Returns:       The instance.

    @discardableResult

    public func authenticate(username: String, password: String, persistence: URLCredential.Persistence = .forSession) -> Self {

        let credential = URLCredential(user: username, password: password, persistence: persistence)

        return authenticate(with: credential)

    }

    /// Associates the provided credential with the instance.

    ///

    /// - Parameter credential: The `URLCredential`.

    ///

    /// - Returns:              The instance.

    @discardableResult

    public func authenticate(with credential: URLCredential) -> Self {

        $mutableState.credential = credential

        return self

    }

    /// Sets a closure to be called periodically during the lifecycle of the instance as data is read from the server.

    ///

    /// - Note: Only the last closure provided is used.

    ///

    /// - Parameters:

    ///   - queue:   The `DispatchQueue` to execute the closure on. `.main` by default.

    ///   - closure: The closure to be executed periodically as data is read from the server.

    ///

    /// - Returns:   The instance.

    @discardableResult

    public func downloadProgress(queue: DispatchQueue = .main, closure: @escaping ProgressHandler) -> Self {

        $mutableState.downloadProgressHandler = (handler: closure, queue: queue)

        return self

    }

    /// Sets a closure to be called periodically during the lifecycle of the instance as data is sent to the server.

    ///

    /// - Note: Only the last closure provided is used.

    ///

    /// - Parameters:

    ///   - queue:   The `DispatchQueue` to execute the closure on. `.main` by default.

    ///   - closure: The closure to be executed periodically as data is sent to the server.

    ///

    /// - Returns:   The instance.

    @discardableResult

    public func uploadProgress(queue: DispatchQueue = .main, closure: @escaping ProgressHandler) -> Self {

        $mutableState.uploadProgressHandler = (handler: closure, queue: queue)

        return self

    }

    // MARK: Redirects

    /// Sets the redirect handler for the instance which will be used if a redirect response is encountered.

    ///

    /// - Note: Attempting to set the redirect handler more than once is a logic error and will crash.

    ///

    /// - Parameter handler: The `RedirectHandler`.

    ///

    /// - Returns:           The instance.

    @discardableResult

    public func redirect(using handler: RedirectHandler) -> Self {

        $mutableState.write { mutableState in

            precondition(mutableState.redirectHandler == nil, "Redirect handler has already been set.")

            mutableState.redirectHandler = handler

        }

        return self

    }

    // MARK: Cached Responses

    /// Sets the cached response handler for the `Request` which will be used when attempting to cache a response.

    ///

    /// - Note: Attempting to set the cache handler more than once is a logic error and will crash.

    ///

    /// - Parameter handler: The `CachedResponseHandler`.

    ///

    /// - Returns:           The instance.

    @discardableResult

    public func cacheResponse(using handler: CachedResponseHandler) -> Self {

        $mutableState.write { mutableState in

            precondition(mutableState.cachedResponseHandler == nil, "Cached response handler has already been set.")

            mutableState.cachedResponseHandler = handler

        }

        return self

    }

    // MARK: - Lifetime APIs

    /// Sets a handler to be called when the cURL description of the request is available.

    ///

    /// - Note: When waiting for a `Request`'s `URLRequest` to be created, only the last `handler` will be called.

    ///

    /// - Parameters:

    ///   - queue:   `DispatchQueue` on which `handler` will be called.

    ///   - handler: Closure to be called when the cURL description is available.

    ///

    /// - Returns:           The instance.

    @discardableResult

    public func cURLDescription(on queue: DispatchQueue, calling handler: @escaping (String) -> Void) -> Self {

        $mutableState.write { mutableState in

            if mutableState.requests.last != nil {

                queue.async { handler(self.cURLDescription()) }

            } else {

                mutableState.cURLHandler = (queue, handler)

            }

        }

        return self

    }

    /// Sets a handler to be called when the cURL description of the request is available.

    ///

    /// - Note: When waiting for a `Request`'s `URLRequest` to be created, only the last `handler` will be called.

    ///

    /// - Parameter handler: Closure to be called when the cURL description is available. Called on the instance's

    ///                      `underlyingQueue` by default.

    ///

    /// - Returns:           The instance.

    @discardableResult

    public func cURLDescription(calling handler: @escaping (String) -> Void) -> Self {

        $mutableState.write { mutableState in

            if mutableState.requests.last != nil {

                underlyingQueue.async { handler(self.cURLDescription()) }

            } else {

                mutableState.cURLHandler = (underlyingQueue, handler)

            }

        }

        return self

    }

    /// Sets a closure to called whenever Alamofire creates a `URLRequest` for this instance.

    ///

    /// - Note: This closure will be called multiple times if the instance adapts incoming `URLRequest`s or is retried.

    ///

    /// - Parameters:

    ///   - queue:   `DispatchQueue` on which `handler` will be called. `.main` by default.

    ///   - handler: Closure to be called when a `URLRequest` is available.

    ///

    /// - Returns:   The instance.

    @discardableResult

    public func onURLRequestCreation(on queue: DispatchQueue = .main, perform handler: @escaping (URLRequest) -> Void) -> Self {

        $mutableState.write { state in

            if let request = state.requests.last {

                queue.async { handler(request) }

            }

            state.urlRequestHandler = (queue, handler)

        }

        return self

    }

    /// Sets a closure to be called whenever the instance creates a `URLSessionTask`.

    ///

    /// - Note: This API should only be used to provide `URLSessionTask`s to existing API, like `NSFileProvider`. It

    ///         **SHOULD NOT** be used to interact with tasks directly, as that may be break Alamofire features.

    ///         Additionally, this closure may be called multiple times if the instance is retried.

    ///

    /// - Parameters:

    ///   - queue:   `DispatchQueue` on which `handler` will be called. `.main` by default.

    ///   - handler: Closure to be called when the `URLSessionTask` is available.

    ///

    /// - Returns:   The instance.

    @discardableResult

    public func onURLSessionTaskCreation(on queue: DispatchQueue = .main, perform handler: @escaping (URLSessionTask) -> Void) -> Self {

        $mutableState.write { state in

            if let task = state.tasks.last {

                queue.async { handler(task) }

            }

            state.urlSessionTaskHandler = (queue, handler)

        }

        return self

    }

    // MARK: Cleanup

    /// Adds a `finishHandler` closure to be called when the request completes.

    ///

    /// - Parameter closure: Closure to be called when the request finishes.

    func onFinish(perform finishHandler: @escaping () -> Void) {

        guard !isFinished else { finishHandler(); return }

        $mutableState.write { state in

            state.finishHandlers.append(finishHandler)

        }

    }

    /// Final cleanup step executed when the instance finishes response serialization.

    func cleanup() {

        delegate?.cleanup(after: self)

        let handlers = $mutableState.finishHandlers

        handlers.forEach { $0() }

        $mutableState.write { state in

            state.finishHandlers.removeAll()

        }

    }

}

// MARK: - Protocol Conformances

extension Request: Equatable {

    public static func ==(lhs: Request, rhs: Request) -> Bool {

        lhs.id == rhs.id

    }

}

extension Request: Hashable {

    public func hash(into hasher: inout Hasher) {

        hasher.combine(id)

    }

}

extension Request: CustomStringConvertible {

    /// A textual representation of this instance, including the `HTTPMethod` and `URL` if the `URLRequest` has been

    /// created, as well as the response status code, if a response has been received.

    public var description: String {

        guard let request = performedRequests.last ?? lastRequest,

              let url = request.url,

              let method = request.httpMethod else { return "No request created yet." }

        let requestDescription = "\(method) \(url.absoluteString)"

        return response.map { "\(requestDescription) (\($0.statusCode))" } ?? requestDescription

    }

}

extension Request {

    /// cURL representation of the instance.

    ///

    /// - Returns: The cURL equivalent of the instance.

    public func cURLDescription() -> String {

        guard

            let request = lastRequest,

            let url = request.url,

            let host = url.host,

            let method = request.httpMethod else { return "$ curl command could not be created" }

        var components = ["$ curl -v"]

        components.append("-X \(method)")

        if let credentialStorage = delegate?.sessionConfiguration.urlCredentialStorage {

            let protectionSpace = URLProtectionSpace(host: host,

                                                     port: url.port ?? 0,

                                                     protocol: url.scheme,

                                                     realm: host,

                                                     authenticationMethod: NSURLAuthenticationMethodHTTPBasic)

            if let credentials = credentialStorage.credentials(for: protectionSpace)?.values {

                for credential in credentials {

                    guard let user = credential.user, let password = credential.password else { continue }

                    components.append("-u \(user):\(password)")

                }

            } else {

                if let credential = credential, let user = credential.user, let password = credential.password {

                    components.append("-u \(user):\(password)")

                }

            }

        }

        if let configuration = delegate?.sessionConfiguration, configuration.httpShouldSetCookies {

            if

                let cookieStorage = configuration.httpCookieStorage,