parse-community / Parse-Swift

The Swift SDK for Parse Platform (iOS, macOS, watchOS, tvOS, Linux, Android, Windows)

MIT License

306 stars 69 forks source link

New Pull Request Checklist

[x] I am not disclosing a vulnerability.
[x] I am creating this PR in reference to an issue.

Issue Description

410 added the `ParseFileTransferable` protocol which allows developers to upload `ParseFile`'s directly to different file storage mediums as oppose to uploading to a Parse Server. In order for developers to take advantage of the `ParseFileTransferable` protocol, they have to understand the response type a Parse Server will send and structure the response of the uploaded file accordingly.

If the Swift SDK provided a set of helper methods, it would remove the developer needing to understand server and client responses and ease the process.

Related issue: #n/a

Approach

Add the following helper methods: makeSuccessfulUploadResponse() and makeDummyUploadTask()

/**
     Compose a valid file upload response with a name and url.

     Use this method after uploading a file to any file storage to
     respond to the Swift SDK upload request.
     - parameter name: The name of the file.
     - parameter url: The url of the file that was stored.
     - returns: A tuple of `(Data, HTTPURLResponse?)` where `Data` is the
     JSON encoded file upload response and `HTTPURLResponse` is the metadata
     associated with the response to the load request.
     */
    func makeSuccessfulUploadResponse(_ name: String, url: URL) throws -> (Data, HTTPURLResponse?)

    /**
     Compose a dummy upload task.

     Use this method if you do not need the Parse Swift SDK to start
     your upload task for you.
     - returns: A dummy upload task that starts an upload of zero bytes
     to localhost.
     - throws: An error of type `ParseError`.
     */
    func makeDummyUploadTask() throws -> URLSessionUploadTask

Example

// Initialize the Swift SDK with your class
ParseSwift.initialize(configuration: .init(applicationId: "applicationId",
                               clientKey: "clientKey",
                               masterKey: "masterKey",
                               serverURL: url,
                               parseFileTransfer: MyFileTransferAdapter())) // Pass an instance of your conforming adapter

// Defined in some other file
class MyFileTransferAdapter: ParseFileTransferable {

        func upload(with request: URLRequest,
                    from bodyData: Data?,
                    completion: @escaping (Data?, URLResponse?, URLRequest?, Error?) -> Void) throws -> URLSessionUploadTask {
            try storageUpload(completion: completion)
        }

        func upload(with request: URLRequest,
                    fromFile fileURL: URL,
                    // swiftlint:disable:next line_length
                    completion: @escaping (Data?, URLResponse?, URLRequest?, Error?) -> Void) throws -> URLSessionUploadTask {
            try storageUpload(completion: completion)
        }

        func storageUpload(completion: @escaping (Data?,
                                               URLResponse?,
                                               URLRequest?,
                                               Error?) -> Void) throws -> URLSessionUploadTask {

            // Dispatch is only here to simulate some delay, this would be the upload to your preferred storage
            DispatchQueue.main.asyncAfter(deadline: .now() + 3) {
                do {
                   // Use the new helper method to create a proper response for your uploaded file name and url
                   let response = try makeSuccessfulUploadResponse(name, url: url)
                   completion(response.0, response.1, nil, nil)
                } catch {
                   completion(nil, nil, nil, error)
                }

            }
            // If you don't have a URLSessionUploadTask, use the new dummy method to create a fake one and return it.
            return try makeDummyUploadTask()
        }
}

TODOs before merging

[x] Fix a small bug where some url responses that threw errors were being cached
[x] Add tests
[x] Add entry to changelog
[x] Add changes to documentation (guides, repository pages, in-code descriptions)

Codecov Report

Base: 89.96% // Head: 89.98% // Increases project coverage by +0.02% :tada:

Coverage data is based on head (f739b77) compared to base (9ab5271). Patch coverage: 96.61% of modified lines in pull request are covered.

Additional details and impacted files

```diff @@ Coverage Diff @@ ## main #411 +/- ## ========================================== + Coverage 89.96% 89.98% +0.02% ========================================== Files 159 159 Lines 15286 15323 +37 ========================================== + Hits 13752 13789 +37 Misses 1534 1534 ``` | [Impacted Files](https://codecov.io/gh/parse-community/Parse-Swift/pull/411?src=pr&el=tree&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=parse-community) | Coverage Δ | | |---|---|---| | [Sources/ParseSwift/API/Responses.swift](https://codecov.io/gh/parse-community/Parse-Swift/pull/411/diff?src=pr&el=tree&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=parse-community#diff-U291cmNlcy9QYXJzZVN3aWZ0L0FQSS9SZXNwb25zZXMuc3dpZnQ=) | `95.00% <ø> (ø)` | | | [...s/ParseSwift/Protocols/ParseFileTransferable.swift](https://codecov.io/gh/parse-community/Parse-Swift/pull/411/diff?src=pr&el=tree&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=parse-community#diff-U291cmNlcy9QYXJzZVN3aWZ0L1Byb3RvY29scy9QYXJzZUZpbGVUcmFuc2ZlcmFibGUuc3dpZnQ=) | `96.00% <95.65%> (-4.00%)` | :arrow_down: | | [Sources/ParseSwift/Extensions/URLSession.swift](https://codecov.io/gh/parse-community/Parse-Swift/pull/411/diff?src=pr&el=tree&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=parse-community#diff-U291cmNlcy9QYXJzZVN3aWZ0L0V4dGVuc2lvbnMvVVJMU2Vzc2lvbi5zd2lmdA==) | `82.14% <97.22%> (+1.22%)` | :arrow_up: | | [Sources/ParseSwift/Objects/ParseUser.swift](https://codecov.io/gh/parse-community/Parse-Swift/pull/411/diff?src=pr&el=tree&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=parse-community#diff-U291cmNlcy9QYXJzZVN3aWZ0L09iamVjdHMvUGFyc2VVc2VyLnN3aWZ0) | `87.09% <0.00%> (-0.18%)` | :arrow_down: | | [Sources/ParseSwift/API/API+Command.swift](https://codecov.io/gh/parse-community/Parse-Swift/pull/411/diff?src=pr&el=tree&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=parse-community#diff-U291cmNlcy9QYXJzZVN3aWZ0L0FQSS9BUEkrQ29tbWFuZC5zd2lmdA==) | `89.61% <0.00%> (+0.20%)` | :arrow_up: | | [Sources/ParseSwift/Types/ParseFile.swift](https://codecov.io/gh/parse-community/Parse-Swift/pull/411/diff?src=pr&el=tree&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=parse-community#diff-U291cmNlcy9QYXJzZVN3aWZ0L1R5cGVzL1BhcnNlRmlsZS5zd2lmdA==) | `89.41% <0.00%> (+0.68%)` | :arrow_up: | Help us with your feedback. Take ten seconds to tell us [how you rate us](https://about.codecov.io/nps?utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=parse-community). Have a feature suggestion? [Share it here.](https://app.codecov.io/gh/feedback/?utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=parse-community)