storage: pass metadata during stream upload

[stephenplusplus]

Fixes #368

Looks like there are two concepts of metadata in an Object response (seen here),

1. metadata, such as etag, selfLink, contentType, updated, kind, id, etc.
2. custom metadata, embedded within metadata.metadata

This PR fixes the way in which the insert API receives the request body from us , so that custom properties can be set as we say they are during a file upload.

However, that would stop a user from specifying other, non-custom, metadata properties. Maybe we should just change the docs to say "custom metadata properties go inside a metadata object", e.g.

var options = {
  metadata: {
    contentType: 'content-type',
    metadata: {
      custom: 'metadata'
    }
  }
}

bucket.upload("/file/path.txt", options, //...

bucket.file("file.txt").createWriteStream(options)

I'm talking myself out of thinking this PR is a good idea. Halp!

[ryanseys]

metadata.metadata is annoying but that's how it's documented :(

Maybe we should just change the docs to say "custom metadata properties go inside a metadata object"

Yes. They also can know this from just reading the docs. The outer "metadata" is actually just request body in this case so maybe we can clarify this when we change the docs. One is "User-provided metadata" and the other is "Google provided metadata" (???) I think that might help, but yeah, annoying.

[dhermes]

I'm quite interested in what you decide. We (gcloud-python) currently have a property for each key in the dictionary and I am debating just throwing it out and using the dictionary as-is.

The metadata.metadata concept makes me sad all day, but the API is "set in stone" at this point.

[ryanseys]

So wait, what other properties go on the same level as the outer metadata object as seen at #368 (comment) ?

[stephenplusplus]

I believe we should keep things as-is (close this PR). metadata.metadata is a bit silly, but if that's what the API wants, I don't think we can get around it.

[ryanseys]

Agreed. Is that what this PR aims to accomplish right now?

[stephenplusplus]

Yeah, it just unboxed the metadata = { metadata: {} } object to send just the custom part. I thought it was a bug I was fixing, but it's just a quirk.

[wong2]

ha, it wasted me hours to figure out the silly file.setMetadata({metadata: {}}, ...) api

[jgeewax]

Hey @wong2 : Can you help us understand what we could've done different to avoid wasting time?

[wong2]

@jgeewax sorry for my previous impolite comment, you've documented it, it's my fault for not noticing it.

[jgeewax]

@wong2 No problem at all -- just wanted to make sure make sure it wasn't something we could make better ! :)

[wong2]

@jgeewax maybe you can add a more obvious notice aboout this in the document?