region option

Readme.md

@@ -28,6 +28,22 @@ By default knox will send all requests to the global endpoint
 is. But if you want to manually set the endpoint (for performance reasons) you
 can do it with the `endpoint` option.
 
+For your convenience when using buckets not in the US Standard region, you can specify the `region` option. When you do so, the `endpoint` hostname is automatically assembled. 
+
+As of this writing, valid values for the `region` option are:
+
+* US Standard (default): `us-standard`
+* US West (Oregon): `us-west-2`
+* US West (Northern California): `us-west-1`
+* EU (Ireland): `eu-west-1`
+* Asia Pacific (Singapore): `ap-southeast-1`
+* Asia Pacific (Tokyo): `ap-northeast-1`
+* South America (Sao Paulo): `sa-east-1`
+
+If new regions are added later, their subdomain names will also work when passed as the `region` option. [See the AWS endpoint documentation](http://docs.amazonwebservices.com/general/latest/gr/rande.html#s3_region) for the latest list.
+
+**Convenience APIs such as `putFile` and `putStream` currently do not work as expected with buckets in regions other than US Standard unless you explicitly specify the region option.** This will eventually be addressed by resolving [issue #66](/~https://github.com/LearnBoost/knox/issues/66), however for performance reasons it is always best to specify the region option anyway.
+
 ### PUT
 
 If you want to directly upload some strings to S3, you can use the `Client#put`

lib/client.js

@@ -66,7 +66,16 @@ var Client = module.exports = exports = function Client(options) {
       'for details.');
   }
 
-  this.endpoint = options.bucket + '.s3.amazonaws.com';
+  var domain = 's3.amazonaws.com';
+  if (options.region) {
+    if (options.region === 'us-standard') {
+      // Pesky inconsistency
+      domain = 's3.amazonaws.com';
+    } else {
+      domain = 's3-' + options.region + '.amazonaws.com';
+    }
+  }
+  this.endpoint = options.bucket + '.' + domain;
   this.secure = 'undefined' == typeof options.port;
   utils.merge(this, options);
 

test/knox.test.js

@@ -13,9 +13,22 @@ var knox = require('..')
 try {
   var auth = JSON.parse(fs.readFileSync('auth', 'ascii'));
   var client = knox.createClient(auth);
+  auth.bucket = auth.bucketUsWest2;
+  // Without this we get a 307 redirect 
+  // that putFile can't handle (issue #66). Later
+  // when there is an implementation of #66 we can test
+  // both with and without this option present, but it's
+  // always a good idea for performance
+  auth.region = 'us-west-2';
+  var clientUsWest2 = knox.createClient(auth);
 } catch (err) {
+  console.log(err);
   console.error('The tests require ./auth to contain a JSON string with');
-  console.error('`key, secret, and bucket in order to run tests.');
+  console.error('key, secret, bucket and bucketUsWest2 in order to run tests.');
+  console.error('Both bucket and bucketUsWest2 must exist and should not');
+  console.error('contain anything you want to keep. bucket2 should be');
+  console.error('created in the us-west-2 (Oregon) region, not the default');
+  console.error('region.');
   process.exit(1);
 }
 
@@ -70,6 +83,28 @@ module.exports = {
     assert.equal('s3-eu-west-1.amazonaws.com', client.endpoint);
   },
 
+  'test .createClient() region is us-west-1': function(){
+    var client = knox.createClient({
+        key: 'foobar'
+      , secret: 'baz'
+      , bucket: 'misc'
+      , region: 'us-west-1'
+    });
+
+    assert.equal('misc.s3-us-west-1.amazonaws.com', client.endpoint);
+  },
+
+  'test .createClient() region explicitly us-standard': function(){
+    var client = knox.createClient({
+        key: 'foobar'
+      , secret: 'baz'
+      , bucket: 'misc'
+      , region: 'us-standard'
+    });
+
+    assert.equal('misc.s3.amazonaws.com', client.endpoint);
+  },
+
   'test .putFile()': function(done){
     var n = 0;
     client.putFile(jsonFixture, '/test/user2.json', function(err, res){
@@ -82,6 +117,18 @@ module.exports = {
     });
   },
 
+  'test .putFile() in us-west-2': function(done){
+    var n = 0;
+    clientUsWest2.putFile(jsonFixture, '/test/user2.json', function(err, res){
+      assert.ok(!err, 'putFile() got an error!');
+      assert.equal(200, res.statusCode);
+      client.get('/test/user2.json').on('response', function(res){
+        assert.equal('application/json', res.headers['content-type']);
+        done();
+      }).end();
+    });
+  },
+
   'test .putFile() "progress" event': function(done){
     var progressHappened = false;
     var file = client.putFile(jsonFixture, '/test/user2.json', function(err, res){