S3 Managed Upload Support

doc-src/guide/browser-examples.md

@@ -45,6 +45,14 @@ Amazon S3 bucket:
 
 ### Uploading data into an object
 
+<p class="note">
+  In order to upload files in the browser, you should ensure that you
+  have configured CORS for your Amazon S3 bucket and exposed the "ETag"
+  header via the <code>&lt;ExposeHeader&gt;ETag&lt;/ExposeHeader&gt;</code>
+  declaration. See the {file:browser-configuring.md Configuring} section
+  for more information on configuring CORS for an Amazon S3 bucket.
+</p>
+
 The following example will upload the contents of a `<textarea>` tag to an
 object in S3:
 
@@ -62,14 +70,22 @@ object in S3:
         results.innerHTML = '';
 
         var params = {Key: 'data.txt', Body: textarea.value};
-        bucket.putObject(params, function (err, data) {
+        bucket.upload(params, function (err, data) {
           results.innerHTML = err ? 'ERROR!' : 'SAVED.';
         });
       }, false);
     </script>
 
 ### Uploading a local file using the File API
 
+<p class="note">
+  In order to upload files in the browser, you should ensure that you
+  have configured CORS for your Amazon S3 bucket and exposed the "ETag"
+  header via the <code>&lt;ExposeHeader&gt;ETag&lt;/ExposeHeader&gt;</code>
+  declaration. See the {file:browser-configuring.md Configuring} section
+  for more information on configuring CORS for an Amazon S3 bucket.
+</p>
+
 The following example uses the [HTML5 File API](http://www.w3.org/TR/FileAPI/)
 to upload a file on disk to S3:
 
@@ -89,7 +105,7 @@ to upload a file on disk to S3:
           results.innerHTML = '';
 
           var params = {Key: file.name, ContentType: file.type, Body: file};
-          bucket.putObject(params, function (err, data) {
+          bucket.upload(params, function (err, data) {
             results.innerHTML = err ? 'ERROR!' : 'UPLOADED.';
           });
         } else {

doc-src/guide/node-examples.md

@@ -38,8 +38,8 @@ AWS.config.region = 'us-west-2';
 // Make sure to change the bucket name from "myBucket" to something unique.
 var s3bucket = new AWS.S3({params: {Bucket: 'myBucket'}});
 s3bucket.createBucket(function() {
-  var data = {Key: 'myKey', Body: 'Hello!'};
-  s3bucket.putObject(data, function(err, data) {
+  var params = {Key: 'myKey', Body: 'Hello!'};
+  s3bucket.upload(params, function(err, data) {
     if (err) {
       console.log("Error uploading data: ", err);
     } else {
@@ -104,20 +104,35 @@ s3.listBuckets(function(err, data) {
 });
 ```
 
-### Amazon S3: Create a New Bucket and Object (createBucket, putObject)
+### Amazon S3: Create a New Bucket and Object (createBucket, upload)
 
 The following example puts the string 'Hello!' inside the
 object 'myKey' of bucket 'myBucket':
 
 ```javascript
 var s3 = new AWS.S3({params: {Bucket: 'myBucket', Key: 'myKey'}});
 s3.createBucket(function() {
-  s3.putObject({Body: 'Hello!'}, function() {
+  s3.upload({Body: 'Hello!'}, function() {
     console.log("Successfully uploaded data to myBucket/myKey");
   });
 });
 ```
 
+### Amazon S3: Uploading an arbitrarily sized stream (upload)
+
+The following example gzips a large file and uploads it to S3 as a stream:
+
+```javascript
+var fs = require('fs');
+var zlib = require('zlib');
+
+var body = fs.createReadStream('bigfile').pipe(zlib.createGzip());
+var s3obj = new AWS.S3({params: {Bucket: 'myBucket', Key: 'myKey'}});
+s3obj.upload({Body: body}).
+  on('httpUploadProgress', function(evt) { console.log(evt); }).
+  send(function(err, data) { console.log(err, data) });
+```
+
 ### Amazon S3: Streaming Objects to Files on Disk (getObject)
 
 You can use the `createReadStream()` method on a request object to

features/s3/managed_upload.feature

@@ -0,0 +1,12 @@
+# language: en
+@s3 @managed_upload
+Feature: S3 Managed Upload
+
+  Scenario: Uploading a large buffer
+    When I use S3 managed upload to upload a large buffer
+    Then the multipart upload should succeed
+
+  Scenario: Uploading a large stream
+    When I use S3 managed upload to upload a large stream
+    Then the multipart upload should succeed
+    And I should get progress events

features/s3/step_definitions/managed_upload.js

@@ -0,0 +1,64 @@
+module.exports = function () {
+  this.Before("@s3", "@managed_upload", function (callback) {
+
+    // execute only once
+    if (this.mgrBucket) {
+      callback();
+      return;
+    }
+
+    this.mgrBucket = this.uniqueName('aws-sdk-js-integration');
+    this.s3.createBucket({Bucket:this.mgrBucket}, callback);
+  });
+
+  this.AfterAll(function (callback) {
+    var self = this;
+    this.s3.listObjects({Bucket:this.mgrBucket}, function(err, data) {
+      data.Contents.forEach(function(object) {
+        self.s3.deleteObject({Bucket:self.mgrBucket,Key:object.Key}).send();
+      });
+      setTimeout(function() {
+        self.s3.deleteBucket({Bucket:self.mgrBucket}, callback);
+      }, 1000);
+    });
+  });
+
+  this.When(/^I use S3 managed upload to upload a large buffer$/, function (callback) {
+    var self = this;
+    var buffer = new Buffer(1024 * 1024 * 12);
+    var params = {Bucket: self.mgrBucket, Key: 'largebuffer', Body: buffer};
+    self.s3.upload(params, function (err, data) {
+      self.error = err;
+      self.data = data;
+      callback();
+    });
+  });
+
+  this.Then(/^the multipart upload should succeed$/, function (callback) {
+    this.assert.equal(this.error, null);
+    this.assert.equal(typeof this.data.Location, 'string');
+    callback();
+  });
+
+  this.When(/^I use S3 managed upload to upload a large stream$/, function (callback) {
+    var self = this;
+    var stream = this.AWS.util.buffer.toStream(new Buffer(1024 * 1024 * 12));
+    var params = {Bucket: self.mgrBucket, Key: 'largestream', Body: stream};
+
+    self.progressEvents = [];
+    var progress = function(info) {
+      self.progressEvents.push(info);
+    }
+
+    self.s3.upload(params).on('httpUploadProgress', progress).send(function (err, data) {
+      self.error = err;
+      self.data = data;
+      callback();
+    });
+  });
+
+  this.Then(/^I should get progress events$/, function (callback) {
+    this.assert.compare(this.progressEvents.length, '>', 0);
+    callback();
+  });
+};