Coerce requests from string or buffer.

[lukesneeringer]

Hey @jgeewax, @stephenplusplus, @jmdobry, (cc: @remi)
Background: JJ pinged me a couple weeks ago asking about the breaking changes between Vision 0.11.6 and 0.12.0. Essentially, we went from "we accept a string with the URL" to "send a big object". In the change moving to 0.12.0, our single-feature methods take the image object, but as part of GCN #2553 and GCN #2555, we actually are moving it to having to send the entire request structure:

client.faceDetection({image: {source: {imageUri: 'gs://...'}}}).then(response => {
  ...
});

The reason why we were doing this was to alter the request structure as little as possible to ensure forward compatibility. JJ asked, essentially, "For the simplest of cases...you only want to specify an image, why can you not detect non-objects and convert appropriately?" For example:

client.faceDetection('gs://...').then(response => { ... });

I responded, honestly, "Because I did not think of that at the time." I was focused on modifying the request as little as possible and only stripping out the feature flag and moving it over to the method, but the proposal has a lot of value. It does still mean that if you want to specify anything else at all (e.g. the imageContext case), you have to send the full AnnotateImageRequest structure, but that is where we are landing anyway.

We merged the (breaking) fix from GCN #2555 but never actually launched it, so when we launch this repo-migration, there will be a breaking change involved. JJ's proposed fix here is additive, but it would be nice if we could reduce randomization on users as much as possible. I need to put a bow on this release soon to accommodate the v1p1beta1 release.

I have whipped up what the code (and docs) would essentially need to be if we did this. Is this something everyone would be happy with? If so, I will get the appropriate tests and such in place.

Fixes #2.

[stephenplusplus]

Cool, and props to all for making sure the code is as friendly as it can be. 🍻

The one thing I'm not sure about with the code in this PR is how it rewrites the request object temporarily; only to be changed a few lines deeper. I think our original implementation could probably still work: https://github.com/GoogleCloudPlatform/google-cloud-node/blob/d511c762b625ed54e12c8da3e4e9ed0be083a779/packages/vision/src/index.js#L1719. It even supports Storage#File instances.

[jmdobry]

Need to npm run prettier if you haven't already.

[lukesneeringer]

Need to npm run prettier if you haven't already.

Yeah, I was more wanting to run the concept past stakeholders.

[jmdobry]

lgtm apart from my requested changes

[lukesneeringer]

Okay, I will test (and write tests) tomorrow morning.

[lukesneeringer]

@jmdobry @stephenplusplus This is now ready for review. System tests pass locally.

[lukesneeringer]

The one thing I'm not sure about with the code in this PR is how it rewrites the request object temporarily; only to be changed a few lines deeper.

I looked at the previous code but decided to leave it as is. The existing code supports an extra case that the previous code did not (specifying the buffer in the 0.12.0 style).

I do agree that the former support for a Storage#file object has value and I would not be opposed to adding that.

[jmdobry]

Could you also update samples/quickstart.js and samples/detect.js to use the simpler interface?