storage/bucket: add label accessor methods

packages/storage/src/bucket.js

@@ -627,6 +627,75 @@ Bucket.prototype.deleteFiles = function(query, callback) {
   });
 };
 
+
+/**
+ * Delete one or more labels from this bucket.
+ *
+ * @param {string=|string[]=} labels - The labels to delete. If no labels are
+ *     provided, all of the labels are removed.
+ * @param {function} callback - The callback function.
+ * @param {?error} callback.err - An error returned while making this request.
+ * @param {object} callback.metadata - The bucket's metadata.
+ *
+ * @example
+ * //-
+ * // Delete all of the labels from this bucket.
+ * //-
+ * bucket.deleteLabels(function(err, metadata) {});
+ *
+ * //-
+ * // Delete a single label.
+ * //-
+ * bucket.deleteLabels('labelone', function(err, metadata) {});
+ *
+ * //-
+ * // Delete a specific set of labels.
+ * //-
+ * bucket.deleteLabels([
+ *   'labelone',
+ *   'labeltwo'
+ * ], function(err, metadata) {});
+ *
+ * //-
+ * // If the callback is omitted, we'll return a Promise.
+ * //-
+ * bucket.deleteLabels().then(function(data) {
+ *   var metadata = data[0];
+ * });
+ */
+Bucket.prototype.deleteLabels = function(labels, callback) {
+  var self = this;
+
+  if (is.fn(labels)) {
+    callback = labels;
+    labels = [];
+  }
+
+  labels = arrify(labels);
+
+  if (labels.length === 0) {
+    this.getLabels(function(err, labels) {
+      if (err) {
+        callback(err);
+        return;
+      }
+
+      deleteLabels(Object.keys(labels));
+    });
+  } else {
+    deleteLabels(labels);
+  }
+
+  function deleteLabels(labels) {
+    var nullLabelMap = labels.reduce(function(nullLabelMap, labelKey) {
+      nullLabelMap[labelKey] = null;
+      return nullLabelMap;
+    }, {});
+
+    self.setLabels(nullLabelMap, callback);
+  }
+};
+
 /**
  * Create a File object. See {module:storage/file} to see how to handle
  * the different use cases you may have.
@@ -794,6 +863,43 @@ Bucket.prototype.getFiles = function(query, callback) {
  */
 Bucket.prototype.getFilesStream = common.paginator.streamify('getFiles');
 
+/**
+ * Get the labels from this bucket.
+ *
+ * @param {function} callback - The callback function.
+ * @param {?error} callback.err - An error returned while making this request.
+ * @param {object} callback.labels - The labels currently set on this bucket.
+ *
+ * @example
+ * bucket.getLabels(function(err, labels) {
+ *   if (err) {
+ *     // Error handling omitted.
+ *   }
+ *
+ *   // labels = {
+ *   //   label: 'labelValue',
+ *   //   ...
+ *   // }
+ * });
+ *
+ * //-
+ * // If the callback is omitted, we'll return a Promise.
+ * //-
+ * bucket.getLabels().then(function(data) {
+ *   var labels = data[0];
+ * });
+ */
+Bucket.prototype.getLabels = function(callback) {
+  this.getMetadata(function(err, metadata) {
+    if (err) {
+      callback(err);
+      return;
+    }
+
+    callback(null, metadata.labels || {});
+  });
+};
+
 /**
  * Make the bucket listing private.
  *
@@ -1031,6 +1137,41 @@ Bucket.prototype.makePublic = function(options, callback) {
   }
 };
 
+/**
+ * Set labels on the bucket.
+ *
+ * This makes an underlying call to {module:storage/bucket#setMetadata}, which
+ * is a PATCH request. This means an individual label can be overwritten, but
+ * unmentioned labels will not be touched.
+ *
+ * @param {type} labels - Labels to set on the bucket.
+ * @param {function} callback - The callback function.
+ * @param {?error} callback.err - An error returned while making this request.
+ * @param {object} callback.metadata - The bucket's metadata.
+ *
+ * @example
+ * var labels = {
+ *   labelone: 'labelonevalue',
+ *   labeltwo: 'labeltwovalue'
+ * };
+ *
+ * bucket.setLabels(labels, function(err, metadata) {
+ *   if (!err) {
+ *     // Labels set successfully.
+ *   }
+ * });
+ *
+ * //-
+ * // If the callback is omitted, we'll return a Promise.
+ * //-
+ * bucket.setLabels(labels).then(function(data) {
+ *   var metadata = data[0];
+ * });
+ */
+Bucket.prototype.setLabels = function(labels, callback) {
+  this.setMetadata({labels}, callback);
+};
+
 /**
  * Upload a file to the bucket. This is a convenience method that wraps
  * {module:storage/file#createWriteStream}.

packages/storage/system-test/storage.js

@@ -19,6 +19,7 @@
 var assert = require('assert');
 var async = require('async');
 var crypto = require('crypto');
+var extend = require('extend');
 var fs = require('fs');
 var normalizeNewline = require('normalize-newline');
 var path = require('path');
@@ -629,6 +630,89 @@ describe('storage', function() {
         done();
       });
     });
+
+    describe('labels', function() {
+      var LABELS = {
+        label: 'labelvalue', // no caps or spaces allowed (?)
+        labeltwo: 'labelvaluetwo'
+      };
+
+      beforeEach(function(done) {
+        bucket.deleteLabels(done);
+      });
+
+      it('should set labels', function(done) {
+        bucket.setLabels(LABELS, function(err) {
+          assert.ifError(err);
+
+          bucket.getLabels(function(err, labels) {
+            assert.ifError(err);
+            assert.deepStrictEqual(labels, LABELS);
+            done();
+          });
+        });
+      });
+
+      it('should update labels', function(done) {
+        var newLabels = {
+          siblinglabel: 'labelvalue'
+        };
+
+        bucket.setLabels(LABELS, function(err) {
+          assert.ifError(err);
+
+          bucket.setLabels(newLabels, function(err) {
+            assert.ifError(err);
+
+            bucket.getLabels(function(err, labels) {
+              assert.ifError(err);
+              assert.deepStrictEqual(labels, extend({}, LABELS, newLabels));
+              done();
+            });
+          });
+        });
+      });
+
+      it('should delete a single label', function(done) {
+        if (LABELS.length <= 1) {
+          done(new Error('Maintainer Error: `LABELS` needs 2 labels.'));
+          return;
+        }
+
+        var labelKeyToDelete = Object.keys(LABELS)[0];
+
+        bucket.setLabels(LABELS, function(err) {
+          assert.ifError(err);
+
+          bucket.deleteLabels(labelKeyToDelete, function(err) {
+            assert.ifError(err);
+
+            bucket.getLabels(function(err, labels) {
+              assert.ifError(err);
+
+              var expectedLabels = extend({}, LABELS);
+              delete expectedLabels[labelKeyToDelete];
+
+              assert.deepStrictEqual(labels, expectedLabels);
+
+              done();
+            });
+          });
+        });
+      });
+
+      it('should delete all labels', function(done) {
+        bucket.deleteLabels(function(err) {
+          assert.ifError(err);
+
+          bucket.getLabels(function(err, labels) {
+            assert.ifError(err);
+            assert.deepStrictEqual(labels, {});
+            done();
+          });
+        });
+      });
+    });
   });
 
   // RE: https://github.com/GoogleCloudPlatform/google-cloud-node/issues/2224