storage: support resumable uploads

lib/common/util.js

@@ -147,6 +147,7 @@ function ApiError(errorBody) {
   this.errors = errorBody.errors;
   this.code = errorBody.code;
   this.message = errorBody.message;
+  this.response = errorBody.response;
 }
 
 util.inherits(ApiError, Error);
@@ -180,7 +181,8 @@ function handleResp(err, resp, body, callback) {
     callback(new ApiError({
       errors: [],
       code: resp.statusCode,
-      message: body || 'Error during request.'
+      message: body || 'Error during request.',
+      response: resp
     }));
     return;
   }

lib/storage/bucket.js

@@ -49,6 +49,15 @@ var util = require('../common/util.js');
  */
 var STORAGE_BASE_URL = 'https://www.googleapis.com/storage/v1/b';
 
+/**
+ * The size of a file (in bytes) must be greater than this number to
+ * automatically trigger a resumable upload.
+ *
+ * @const {number}
+ * @private
+ */
+var RESUMABLE_THRESHOLD = 5000000;
+
 /**
  * Create a Bucket object to interact with a Google Cloud Storage bucket.
  *
@@ -311,14 +320,27 @@ Bucket.prototype.setMetadata = function(metadata, callback) {
  *
  * @param {string} localPath - The fully qualified path to the file you wish to
  *     upload to your bucket.
- * @param {string=|module:storage/file=} destination - The place to save your
- *     file. If given a string, the file will be uploaded to the bucket using
- *     the string as a filename. When given a File object, your local file will
- *     be uploaded to the File object's bucket and under the File object's name.
- *     Lastly, when this argument is omitted, the file is uploaded to your
+ * @param {object=} options - Configuration options.
+ * @param {string|module:storage/file} options.destination - The place to save
+ *     your file. If given a string, the file will be uploaded to the bucket
+ *     using the string as a filename. When given a File object, your local file
+ *     will be uploaded to the File object's bucket and under the File object's
+ *     name. Lastly, when this argument is omitted, the file is uploaded to your
  *     bucket using the name of the local file.
- * @param {object=} metadata - Metadata to set for your file.
+ * @param {object=} options.metadata - Metadata to set for your file.
+ * @param {boolean=} options.resumable - Force a resumable upload. (default:
+ *     true for files larger than 5MB). Read more about resumable uploads
+ *     [here](http://goo.gl/1JWqCF). NOTE: This behavior is only possible with
+ *     this method, and not {module:storage/file#createWriteStream}. When
+ *     working with streams, the file format and size is unknown until it's
+ *     completely consumed. Because of this, it's best for you to be explicit
+ *     for what makes sense given your input.
  * @param {function} callback - The callback function.
+ * @param {string|boolean} options.validation - Possible values: `"md5"`,
+ *     `"crc32c"`, or `false`. By default, data integrity is validated with an
+ *     MD5 checksum for maximum reliability. CRC32c will provide better
+ *     performance with less reliability. You may also choose to skip validation
+ *     completely, however this is **not recommended**.
  *
  * @example
  * //-
@@ -334,8 +356,19 @@ Bucket.prototype.setMetadata = function(metadata, callback) {
  * //-
  * // It's not always that easy. You will likely want to specify the filename
  * // used when your new file lands in your bucket.
+ * //
+ * // You may also want to set metadata or customize other options.
  * //-
- * bucket.upload('/local/path/image.png', 'new-image.png', function(err, file) {
+ * var options = {
+ *   destination: 'new-image.png',
+ *   resumable: true,
+ *   validation: 'crc32c',
+ *   metadata: {
+ *     event: 'Fall trip to the zoo'
+ *   }
+ * };
+ *
+ * bucket.upload('/local/path/image.png', options, function(err, file) {
  *   // Your bucket now contains:
  *   // - "new-image.png" (with the contents of `/local/path/image.png')
  *
@@ -346,45 +379,37 @@ Bucket.prototype.setMetadata = function(metadata, callback) {
  * // You may also re-use a File object, {module:storage/file}, that references
  * // the file you wish to create or overwrite.
  * //-
- * var file = bucket.file('existing-file.png');
- * bucket.upload('/local/path/image.png', file, function(err, newFile) {
+ * var options = {
+ *   destination: bucket.file('existing-file.png'),
+ *   resumable: false
+ * };
+ *
+ * bucket.upload('/local/path/image.png', options, function(err, newFile) {
  *   // Your bucket now contains:
  *   // - "existing-file.png" (with the contents of `/local/path/image.png')
  *
  *   // Note:
  *   // The `newFile` parameter is equal to `file`.
  * });
  */
-Bucket.prototype.upload = function(localPath, destination, metadata, callback) {
-  var name;
-  var newFile;
-  switch (arguments.length) {
-    case 4:
-      break;
-    case 3:
-      callback = metadata;
-      if (util.is(destination, 'object')) {
-        metadata = destination;
-      } else {
-        metadata = {};
-      }
-      /* falls through */
-    default:
-      callback = callback || destination;
-      name = path.basename(localPath);
-      break;
+Bucket.prototype.upload = function(localPath, options, callback) {
+  if (util.is(options, 'function')) {
+    callback = options;
+    options = {};
   }
-  metadata = metadata || {};
-  callback = callback || util.noop;
-  if (util.is(destination, 'string')) {
-    name = destination;
-  }
-  if (destination instanceof File) {
-    name = destination.name;
-    newFile = destination;
+
+  var newFile;
+  if (options.destination instanceof File) {
+    newFile = options.destination;
+  } else if (util.is(options.destination, 'string')) {
+    // Use the string as the name of the file.
+    newFile = this.file(options.destination);
+  } else {
+    // Resort to using the name of the incoming file.
+    newFile = this.file(path.basename(localPath));
   }
-  newFile = newFile || this.file(name);
 
+  var metadata = options.metadata || {};
   var contentType = mime.lookup(localPath);
   if (contentType && !metadata.contentType) {
     metadata.contentType = contentType;
@@ -395,12 +420,36 @@ Bucket.prototype.upload = function(localPath, destination, metadata, callback) {
     metadata.contentType += '; charset=' + charset;
   }
 
-  fs.createReadStream(localPath)
-    .pipe(newFile.createWriteStream(metadata))
-    .on('error', callback)
-    .on('complete', function() {
-      callback(null, newFile);
+  var resumable;
+  if (util.is(options.resumable, 'boolean')) {
+    resumable = options.resumable;
+    upload();
+  } else {
+    // Determine if the upload should be resumable if it's over the threshold.
+    fs.stat(localPath, function(err, fd) {
+      if (err) {
+        callback(err);
+        return;
+      }
+
+      resumable = fd.size > RESUMABLE_THRESHOLD;
+
+      upload();
     });
+  }
+
+  function upload() {
+    fs.createReadStream(localPath)
+      .pipe(newFile.createWriteStream({
+        validation: options.validation,
+        resumable: resumable,
+        metadata: metadata
+      }))
+      .on('error', callback)
+      .on('complete', function() {
+        callback(null, newFile);
+      });
+  }
 };
 
 /**