GCS uploading: disable chunked transfer encoding if contentLength is set

[stephenplusplus]

Fixes #601

• Review
• Tests

With this change, when a user provides a contentLength property with the metadata to createWriteStream(), the upload will switch to non-chunked.

Because this is a stream, request wants to default to chunked transfer encoding. Normally with streams, we don't know the length of the content until it's fully received. However, when we do (see the use case in #601), there is an added expense for using a chunked transfer.

To accomplish this, some maybe not-so-pretty techniques were used. I wanted to open this PR before I go too much further to see if anyone knows of other options to get what we're after.

[gmiroshnykov]

Oh, I thought it would be way easier to implement :(
I didn't know request doesn't allow streams with chunked: false multipart requests.
But it kinda makes sense as you have to do all the plumbing and figuring out individual parts' Content-Lengths on your own.

I'd say the increase in code complexity is not worth it.

Maybe instead it makes more sense to provide a new API for simple (single part) uploads and let a user set metadata in a separate request if it's needed?

[stephenplusplus]

That makes sense. I just pushed an update:

// Disable multipart:
file.createWriteStream({
  simple: true
});

// Disable chunked:
file.createWriteStream({
  simple: true,
  metadata: {
    contentLength: 238497
  }
});

With simple: true, only metadata.contentType and metadata.contentLength are honored. If the user set others, they're just ignored.

This API change feels a little weird... ideally, the user doesn't have to study or care about the "simple", "multipart", and "resumable" upload techniques. If we were to just add a new method, I'd be worried that having multiple ways to do similar things would lead to choice overload and confusion.

What if we automatically used a simple upload and set the Content-Length header anytime the user provides metadata.contentLength and no other metadata properties than contentType-- basically, the second example above without simple: true. We would not allow the user to explicitly choose between simple or multipart; I see that more as an implementation detail for our library to cover up. We can just use our documentation to show an example of how we support non-chunked, and support more advanced needs that way.

// @callmehiphop thoughts?

[stephenplusplus]

The tricky part for me to dance around is the metadata; if a user sets a contentLength, that doesn't mean they want to avoid chunked transfer encoding and drop the rest of their metadata. Having a setting for what upload technique to use feels a bit too advanced and still doesn't lead to a clean implementation.

I'm thinking this might be a little too far on the micro-optimization side for our "easy to approach" library to support. I'm going to close this for now, but if anyone can argue otherwise or provide a more straightforward solution than I could come up with, please discuss here or on #601.