storage: support creating resumable upload uris

lib/storage/file.js

@@ -112,7 +112,7 @@ function File(bucket, name, options) {
    *
    * var myFile = gcs.bucket('my-bucket').file('my-file');
    *
-   *  myFile.acl.add({
+   * myFile.acl.add({
    *   entity: 'allUsers',
    *   role: gcs.acl.READER_ROLE
    * }, function(err, aclObject) {});
@@ -563,6 +563,51 @@ File.prototype.createReadStream = function(options) {
   return throughStream;
 };
 
+/**
+ * Create a unique resumable upload session URI. This is the first step when
+ * performing a resumable upload.
+ *
+ * See the [Resumable upload guide](https://cloud.google.com/storage/docs/json_api/v1/how-tos/upload#resumable)
+ * for more on how the entire process works.
+ *
+ * <h4>Note</h4>
+ *
+ * If you are just looking to perform a resumable upload without worrying about
+ * any of the details, see {module:storage/createWriteStream}. Resumable uploads
+ * are performed by default.
+ *
+ * @resource [Resumable upload guide]{@link https://cloud.google.com/storage/docs/json_api/v1/how-tos/upload#resumable}
+ *
+ * @param {object=} metadata - Optional metadata to set on the file.
+ * @param {function} callback - The callback function.
+ * @param {?error} callback.err - An error returned while making this request
+ * @param {string} callback.uri - The resumable upload's unique session URI.
+ *
+ * @example
+ * var bucket = gcs.bucket('my-bucket');
+ * var file = bucket.file('large-file.zip');
+ *
+ * file.createResumableUpload(function(err, uri) {
+ *   if (!err) {
+ *     // `uri` can be used to PUT data to.
+ *   }
+ * });
+ */
+File.prototype.createResumableUpload = function(metadata, callback) {
+  if (is.fn(metadata)) {
+    callback = metadata;
+    metadata = {};
+  }
+
+  resumableUpload.createURI({
+    authClient: this.bucket.storage.makeAuthorizedRequest_.authClient,
+    bucket: this.bucket.name,
+    file: this.name,
+    generation: this.generation,
+    metadata: metadata || {}
+  }, callback);
+};
+
 /**
  * Create a writable stream to overwrite the contents of the file in your
  * bucket.
@@ -1318,6 +1363,8 @@ File.prototype.makePublic = function(callback) {
 /**
  * This creates a gcs-resumable-upload upload stream.
  *
+ * @resource [gcs-resumable-upload]{@link https://github.com/stephenplusplus/gcs-resumable-upload}
+ *
  * @param {Duplexify} stream - Duplexify stream of data to pipe to the file.
  * @param {object=} metadata - Optional metadata to set on the file.
  *

package.json

@@ -55,7 +55,7 @@
     "duplexify": "^3.2.0",
     "extend": "^2.0.0",
     "gce-images": "^0.1.0",
-    "gcs-resumable-upload": "^0.1.0",
+    "gcs-resumable-upload": "^0.2.1",
     "google-auto-auth": "^0.2.0",
     "hash-stream-validation": "^0.1.0",
     "is": "^3.0.1",

test/storage/file.js

@@ -62,6 +62,15 @@ var resumableUpload = require('gcs-resumable-upload');
 function fakeResumableUpload() {
   return (resumableUploadOverride || resumableUpload).apply(null, arguments);
 }
+fakeResumableUpload.createURI = function() {
+  var createURI = resumableUpload.createURI;
+
+  if (resumableUploadOverride && resumableUploadOverride.createURI) {
+    createURI = resumableUploadOverride.createURI;
+  }
+
+  return createURI.apply(null, arguments);
+};
 
 describe('File', function() {
   var File;
@@ -833,6 +842,45 @@ describe('File', function() {
     });
   });
 
+  describe('createResumableUpload', function() {
+    it('should not require metadata', function(done) {
+      resumableUploadOverride = {
+        createURI: function(opts, callback) {
+          assert.deepEqual(opts.metadata, {});
+          callback();
+        }
+      };
+
+      file.createResumableUpload(done);
+    });
+
+    it('should create a resumable upload URI', function(done) {
+      var metadata = {
+        contentType: 'application/json'
+      };
+
+      file.generation = 3;
+
+      resumableUploadOverride = {
+        createURI: function(opts, callback) {
+          var bucket = file.bucket;
+          var storage = bucket.storage;
+          var authClient = storage.makeAuthorizedRequest_.authClient;
+
+          assert.strictEqual(opts.authClient, authClient);
+          assert.strictEqual(opts.bucket, bucket.name);
+          assert.strictEqual(opts.file, file.name);
+          assert.strictEqual(opts.generation, file.generation);
+          assert.strictEqual(opts.metadata, metadata);
+
+          callback();
+        }
+      };
+
+      file.createResumableUpload(metadata, done);
+    });
+  });
+
   describe('createWriteStream', function() {
     var METADATA = { a: 'b', c: 'd' };