Improved Progress protocol (#143)

Description

This pull request addresses a series of issues related to the current implementation of the Progress protocol.

The first problem addressed was the lack of a parameter in UploadProgress to determine the total number of bytes being sent to the server. This limitation rendered the progress implementation significantly limited and purposeless.

The second problem involved a major refactoring of DownloadProgress, which previously required specifying the header key to determine the total number of bytes the client would receive from the server. The logic has now been internalized and utilizes the Content-Length header, which is the standard used by AsyncHTTPClient.

The third problem involved how RequestDL internally tracked the total number of bytes sent and received. The fix introduced several new properties that provide accurate information about the size of the data being sent and received.

This PR has some breaking changes:

UploadProgress

// Before
protocol UploadProgress {

    func upload(_ bytesLength: Int)
}

// After
protocol UploadProgress {

    func upload(_ chunkSize: Int, totalSize: Int)
}

DownloadProgress

// Before
protocol DownloadProgress {

    var contentLengthHeaderKey: String? { get }
    
    func download(_ part: Data, length: Int?)
}

// After
protocol DownloadProgress {

    func download(_ slice: Data, totalSize: Int)
}

Response

// Before
enum Response {
    case upload(Int)
    case download(ResponseHead, AsyncBytes)
}

// After
enum ResponseStep {
    case upload(UploadStep)
    case download(DownloadStep)
}

Fixes None

Type of change

New feature (non-breaking change which adds functionality)
Breaking change (fix or feature that would cause existing functionality to not work as expected)

Checklist

My code follows the code style of this project.
I have added tests to cover my changes.
All new and existing tests passed.
I have added/updated necessary comments/documentation.

RequestDL

Thanks to Mike Lewis, progress is seamlessly integrated into this library, providing a simple and streamlined experience.

RequestDL is a Swift package designed to simplify the process of performing network requests. It provides a set of tools, including the RequestTask protocol, which supports different types of requests, including DataTask, DownloadTask, and UploadTask.

One of the key features of RequestDL is its support for specifying properties of a request, such as Query, Payload, and Headers, among others. You can also use RequestTaskModifier and RequestTaskInterceptor to process the response after the request is complete, allowing for actions like decoding, mapping, error handling based on status codes, and logging responses in the console.

The Property protocol is another powerful feature that allows developers to implement custom properties to define various aspects of the request within a struct specification or using the @PropertyBuilder. This makes it easy to customize requests to meet specific needs.

Documentation

Installation

RequestDL can be installed using Swift Package Manager. To include it in your project, add the following dependency to your Package.swift file:

dependencies: [
    .package(url: "https://github.com/request-dl/request-dl.git", from: "2.3.0")
]

Usage

Using RequestDL is easy and intuitive. You can create network requests in a declarative way, specifying the properties of the request through the use of the Property protocol or using the @PropertyBuilder attribute.

Here’s an example of a simple DataTask that queries Google for the term “apple”, logs the response in the console, and ignores the HTTP’s response head:

try await DataTask {
    BaseURL("google.com")
    
    HeaderGroup {
        AcceptHeader(.json)
        CustomHeader(name: "xxx-api-key", value: token)
    }
    
    Query(name: "q", value: "apple")
}
.logInConsole(true)
.decode(GoogleResponse.self)
.extractPayload()
.result()

This code creates a DataTask with the BaseURL set to “google.com”, a HeaderGroup containing the “Accept” set to “application/json”, a “xxx-api-key” header set the API token, and a query parameter with the key “q” and the value “apple”. It then sets the logInConsole property to true, which will print the response in the console when the request is completed. It also decodes the response into an instance of GoogleResponse and then ignores it.

This is just a simple example of what RequestDL can do. Check out the documentation for more information on how to use it.

Versioning

We follow semantic versioning for this project. The version number is composed of three parts: MAJOR.MINOR.PATCH.

MAJOR version: Increments when there are incompatible changes and breaking changes. These changes may require updates to existing code and could potentially break backward compatibility.
MINOR version: Increments when new features or enhancements are added in a backward-compatible manner. It may include improvements, additions, or modifications to existing functionality.
The PATCH version includes bug fixes, patches, and safe modifications that address issues, bugs, or vulnerabilities without disrupting existing functionality. It may also include new features, but they must be implemented carefully to avoid breaking changes or compatibility issues.

It is recommended to review the release notes for each version to understand the specific changes and updates made in that particular release.

Contributing

If you find a bug or have an idea for a new feature, please open an issue or submit a pull request. We welcome contributions from the community!

Acknowledgments

This library owes a lot to the work of Carson Katri and his Swift package Request. Many of the core concepts and techniques used in RequestDL were inspired by Carson’s library, and the original implementation of RequestDL even used a fork of Carson’s library as its foundation.

Without Carson’s work, this library would not exist in its current form. Thank you, Carson, for your contributions to the Swift community and for inspiring the development of RequestDL.