diff --git a/lib/storage/file.js b/lib/storage/file.js index cecb109af6c..dfeb29fc17c 100644 --- a/lib/storage/file.js +++ b/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. + * + *

Note

+ * + * 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. * diff --git a/package.json b/package.json index dd09070a2cf..c285ca6e6f1 100644 --- a/package.json +++ b/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", diff --git a/test/storage/file.js b/test/storage/file.js index 3886faff4f2..3511d554f31 100644 --- a/test/storage/file.js +++ b/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' };