Add a way to get progress of uploading.

[taish]

See: #186

Introduction

Add progressHandler(bytesSent:totalBytesSent:totalBytesExpectedToSend:) parameter in Session.send for getting progress of uploading.

While the upload is in progress, progressHandler closure in Session.send is periodically called.

Therefore you can get information of uploading about didSendBodyData totalBytesSent totalBytesExpectedToSend.

These parameters are defined by urlSession(_:task:didSendBodyData:totalBytesSent:totalBytesExpectedToSend:) in URLSessionTaskDelegate.

Example

Session.send(request, 
    progressHandler: { bytesSent, totalBytesSent, totalBytesExpectedToSend in
        let progress = Float(totalBytesSent) / Float(totalBytesExpectedToSend)
        print(String(format: "%.2f", progress * 100) + "%")
    },
    handler: { result in
        ...
    }
)

Suffering

In unit test about urlSession(_:task:didSendBodyData:totalBytesSent:totalBytesExpectedToSend:) delegate method in URLSessionTaskDelegate, unwillingly sending an real HTTP request...

I couldn't stub because this delegate method will never be called when you stub the request using subclass of URLProtocol.
https://developer.apple.com/library/content/samplecode/CustomHTTPProtocol/Listings/Read_Me_About_CustomHTTPProtocol_txt.html

So sorry about making your tests higher the likelihood fail randomly 😢

After long consideration, I came up with a better way to stable test.
That way is building mocking webserver in local for testing HTTP clients.
This solution is used by okhttp (HTTP client library for java).
https://github.com/square/okhttp/tree/master/mockwebserver

But I don't think that it is a serious problem.
Therefore I don't implement but only introduce 😉

[ishkawa]

Thank you for the great contribution 👍

Since it introduces tiny breaking change in SessionAdapter protocol, I would like to merge this into develop/4.0. I left 1 small note about naming on your commit, please check it 🙏

[ishkawa]

I think handler should be renamed as completionHandler so that users can understand the difference between progressHandler and completionHandler.

[taish]

Fixed!

[ishkawa]

I agree with you on testing the progress delegate method. I understand that there're many limitations on NSURLProtocol, and I think your decision is very reasonable.

Thank you for searching and introducing the solution!

[ishkawa]

💯

[taish]

thank you for reviewing!! 😄
I changed the base branch into develop/4.0.