Feature - Robust Validation

[cnoon]

This PR splits up validation between Request subclasses and adds Data? or URL? parameters to the Validation closure.

Motivation

Previously, the Validation closure only exposed the optional request and response parameters making it difficult to customize validations in inline closures that were not custom extensions in the Request class. You didn’t have access to the actual response data. This was limiting in certain cases where you want to create a custom validation error that includes the error message buried in the server data. The only way you could do this previously was to write an extension on Request.

Another limitation was that the Validation closure did not expose the destinationURL for a DownloadRequest incase you needed to inspect the data in some special scenario.

One final reason to change up the design was that all validate methods could be chained on any Request. This doesn't make sense for StreamRequest types.

Solution

Modifying the validation system to accomplish all the goals stated above meant rethinking the majority of the design and splitting it up between subclasses.

Data Request

The Validation closure exposed on the DataRequest class is now as follows:

extension DataRequest {
    public typealias Validation = (URLRequest?, HTTPURLResponse, Data?) -> ValidationResult
}

By exposing the Data? property directly in the closure, you no longer have to write an extension on Request to access it. Now you can do something like this:

let urlString = "https://httpbin.org/get"

// When
Alamofire.request("https://httpbin.org/get", withMethod: .get)
    .validate { request, response, data in
        guard data != nil else { return .failure(ValidationError.missingData) }
        return .success
    }
    .response { response in
        debugPrint(response)
    }

This will be helpful in those cases where you would like to create a custom error that includes the error message from the server that's buried in the data.

Download Request

The Validation closure exposed on the DownloadRequest class is now as follows:

extension DownloadRequest {
    public typealias Validation = (URLRequest?, HTTPURLResponse, URL?) -> ValidationResult
}

The URL? parameter allows you to access the response data downloaded from the server and stored in the destinationURL. This allows you to inspect the data inside the file if you've determined you need to in order to create a custom error.

let fileURL = URL(fileURLWithPath: FileManager.documentsDirectory + "/test_response.json")

Alamofire.download(urlString, to: { _, _ in fileURL }, withMethod: .get)
    .validate { request, response, fileURL in
        guard let fileURL = fileURL else { return .failure(ValidationError.missingFile) }

        do {
            let _ = try Data(contentsOf: fileURL)
            return .success
        } catch {
            return .failure(ValidationError.fileReadFailed)
        }
    }
    .response { response in
        debugPrint(response)
    }

DRY by Design

Since the default validation methods supported in AF are the same between data and download requests, I decided to DRY things up by pulling the validation logic out into a fileprivate set of extensions on Request. This is very similar to how the response serialization logic was DRY'd up as well.

Session Manager

I also snuck in commit c46bc01 into this PR that updates the SessionManager to leverage the new TaskConvertible conformance to generate the URLSessionTask instances. This cleans up a bunch of duplicated logic that I should have caught in the earlier PRs. This commit doesn't change any functionality, just DRYs things up a bit.

---

Summary

These changes allow inline validation closures to be much more powerful, eliminates chaining validation APIs on StreamRequest instances, and exposes the destinationURL directly to the inline closure. We'll want to update the Validation section of the README to include examples of best practices here.

We need to make sure people understand they shouldn't parse the response data unless they know they're in a failure case where they want to dig the error message out.

[cnoon]

cc @jshier and @kcharwood for review.

[jshier]

I've always wondered whether we want to expose this publicly, as it seems useful for users to be able to parse MIME types themselves, similar to URL encoding methods.

[cnoon]

I'd vote for keeping it hidden until someone actually requests it. I haven't thought this myself yet.

[jshier]

@cnoon Review complete. Great changes! Just some minor comments.

[cnoon]

Thanks for the review @jshier! All the comments have been addressed, I'm going to go ahead and move this one through.

[A1iAshoor]

Thanks so much, we need this so bad in swift 2.2 otherwise we'll be forced to switch to swift 3 and da heck we're gonna get by doing this for big project