Adds putFileHandle and putFileHandleAsync

[mattcomi]

This adds ability to upload from FileHandle which makes it possible to upload large files from an iOS file extension.

Uploading a large (+100MB) file from an app extension isn't currently possible. StorageReference has putData and putFile on its public interface. putData won't work because an app extension has a 120MB memory limit and putFile doesn't work in app extensions.

Under the hood, FirebaseStorage uses GTMSessionUploadFetcher to perform uploads. The GTMSessionUploadFetcher supports upload from FileHandle.

This PR exposes that ability to StorageReference. See #12579.

[google-cla]

Thanks for your pull request! It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

View this failed invocation of the CLA check for more information.

For the most up to date status, view the checks section at the bottom of the pull request.

[paulb777]

Thanks! This looks like a nice API addition.

I'll run this through our internal API review process and let you know how it goes.

[mattcomi]

@paulb777 Thanks for the feedback! I made the requested changes and ran the integration tests locally.

[paulb777]

Thanks @mattcomi! I've kicked off the internal API review process and see if we can get it through in time for our next release.

[paulb777]

After discussion with the team, we've decided we don't want to add new Objective-C APIs, since we want to encourage Swift adoption and minimize are ObjC API footprint.

Would you remove the @objc attributes, Objective C API test changes, and __putFileHandle?

Thanks!

[mattcomi]

Done 👍 Also, without needing to support Objective-C support, we can use Swift default parameters. This means there is no longer a need for the two separate overloads putFileHandle:metadata: and putFileHandle:metadata:completion:.

[ncooke3]

Hi @mattcomi, do you think the use case here could be addressed by using FileHandle as an implementation detail of the existing putFile API? So, you pass in the URL you'd like to upload, and Firebase Storage would create a FileHandle using the initForReading initializer for the given URL, and pass it to GTMSessionFetcher.

The advantage here is that the existing putFile API becomes more robust and a new API is not needed. But, this idea breaks down in the event that you are passing around FileHandles in your app already (as opposed to URLs) because it doesn't look like there is a good way to go from FileHandle → URL. Thoughts?

[mattcomi]

@ncooke3 thanks for the feedback! You raised a great point and I was able to revise my approach with something dramatically simpler.

I investigated exactly why FileHandle works in app extensions but URL does not. The reason is that GTMSessionUploadFetcher uses a background session when it is init with URL, but not when init with Data or a FileHandle. This is why the putFile documentation says "putData should be used instead of putFile in Extensions." The fix is for UploadStorageTask to disable useBackgroundSession when it is being used within an app extension.

Let me know what you think of this alternate approach. It does have the limitation you describe: when passed a FileHandle, the developer has no way of reverse solving its URL, but I've certainly never faced this problem personally.

Sidenote: One advantage I originally thought FileHandle would offer is the ability to upload from a pipe or a socket, but this isn't possible because GTMSessionUploadFetcher tries to seekToEndOfFile and this is an exception unless the FileHandle is init from a file.

[ncooke3]

LGTM after the suggested changes. Thank you, @mattcomi!