storage: add storage class enums

[callmehiphop]

Closes #779

Implemented per conversation in original issue, however it might be better to group these together for documentation purposes. The current implementation creates links for both dra and nearline, where I imagine it would be better to lump them together into a single property to consolidate the documentation on storage classes.

e.g.

var metadata = {
  storageClass: gcs.type.nearline
};

[stephenplusplus]

Thanks for doing this!

Even though I wanted all lowercase, I'm not sure that was a good call. Constants always want to be loud, and we already have gcs.acl.READER_ROLE and such. Should we maybe do that here: gcs.storageClass.DRA?

Another thing, ACLs are available for buckets and files, so it made sense to have them sit atop both at the Storage class level. With storageClass, however, this is only used when creating a bucket. Should it be localized as such: gcs.bucket.storageClass.DRA?

Example:

var gcloud = require('gcloud');
var gcs = gcloud.gcs({ projectId: 'grape-spaceship-123' });

gcs.createBucket({
  storageClass: gcs.bucket.storageClass.DRA
}, function(err, bucket, apiResponse) {});

I really don't prefer this constant system over just a property on the metadata object:

var gcloud = require('gcloud');
var gcs = gcloud.gcs({ projectId: 'grape-spaceship-123' });

gcs.createBucket({
  dra: true
}, function(err, bucket, apiResponse) {});

Or best-guessing from storageClass input:

var gcloud = require('gcloud');
var gcs = gcloud.gcs({ projectId: 'grape-spaceship-123' });

gcs.createBucket({
  storageClass: 'dra' // => we expand this to `DURABLE_REDUCED_AVAILABILITY`
}, function(err, bucket, apiResponse) {});

@jgeewax which approach do you think is best here?

[callmehiphop]

So I ended up just uppercasing the constant names to DRA and NEARLINE, somehow this magically hoisted the property names in the documentation, so I think this is the way to go.

gcs.createBucket({
  storageClass: gcs.DRA
}, callback);

[stephenplusplus]

I strongly think we should go with the second suggestion above. That's the easiest solution for the user, and won't inflate our API. These constants only affect createBucket and can only be used there.

[callmehiphop]

I think we could easily support both? If we use the metadata property version we'll still need to have an alias to the expanded version.

What are your feelings on something like

Storage.DRA = 'DURABLE_REDUCED_AVAILABILITY';

Storage.prototype.createBucket = function(name, metadata, callback) {
  var body = extend(metadata, { name: name });
  ['dra', 'nearline'].forEach(function(storageClass) {
    if (body[storageClass]) {
      delete body[storageClass];
      body.storageClass = Storage[storageClass.toUpperCase()];
    }
  });
  this.makeReq_('POST, '', null, body, callback);
};

[stephenplusplus]

I still think it's overkill. We can keep the expanded version in a map local to the createBucket function. This is a very small use case, I don't think we should stuff random metadata properties on the "global" Storage class.

[callmehiphop]

@stephenplusplus Ok, I changed it to metadata properties. I updated the documentation to show they are optional properties and added links to the official doc for each. I also added a couple of unit tests for each.

Would you prefer reduce over forEach?

[stephenplusplus]

Yay! Can you just add "@"resources for https://cloud.google.com/storage/docs/storage-classes, Nearline, and DRA?

[stephenplusplus]

I think how you have it is good. I would have probably just done:

if (body.dra) {
  body.storageClass = 'DUR...';
  delete body.dra;
}

if (body.nearline) {
  body.storageClass = 'NEARLINE';
  delete body.nearline;
}

So any fanciness you have is good with me :)

[callmehiphop]

Yay! Can you just add "@"resources for https://cloud.google.com/storage/docs/storage-classes, Nearline, and DRA?

done!

[stephenplusplus]

Thanks!