aws-sdk 2.0.1 → 2.0.5

package/dist-tools/.eslintrc

@@ -0,0 +1,10 @@
+{
+  "env": {
+    "node": true
+  },
+  "rules": {
+    "quotes": [2, "single"],
+    "strict": 0,
+    "curly": 0
+  }
+}

package/dist-tools/browser-builder.js

@@ -0,0 +1,142 @@
+#!/usr/bin/env node
+
+var fs = require('fs');
+var path = require('path');
+
+var CacheStrategy = require('./strategies/cache');
+var DefaultStrategy = require('./strategies/default');
+
+var defaultServices = 'cloudwatch,dynamodb,kinesis,s3,sqs,sns,sts';
+var sanitizeRegex = /[^a-zA-Z0-9,-]/;
+
+function Builder(options) {
+  this.setDefaultOptions(options);
+  this.serviceCode = [];
+  this.builtServices = {};
+  this.buildStrategy = this.options.cache ?
+    new CacheStrategy(this) : new DefaultStrategy(this);
+}
+
+Builder.prototype.setDefaultOptions = function(options) {
+  this.options = options || {};
+  this.options.libPath = this.options.libPath || this.getRootPath();
+  this.options.cacheRoot = this.options.cacheRoot ||
+    path.join(this.options.libPath, 'dist-tools', 'cache');
+  this.options.cache = this.options.cache || false;
+  this.options.writeCache = this.options.writeCache || false;
+  this.options.minify = this.options.minify || false;
+  this.options.minifyOptions = this.options.minifyOptions || {compress: false};
+};
+
+Builder.prototype.getRootPath = function() {
+  return path.join(__dirname, '..');
+};
+
+Builder.prototype.cachePath = function(path) {
+  var fullPath = this.options.cacheRoot;
+  if (path) {
+    fullPath += '/' + path + (this.options.minify ? '.min' : '') + '.js';
+  }
+
+  return fullPath;
+};
+
+Builder.prototype.cacheExists = function(path) {
+  return fs.existsSync(this.cachePath(path));
+};
+
+Builder.prototype.buildService = function(name, usingDefaultServices) {
+  var match = name.match(/^(.+?)(?:-(.+?))?$/);
+  var service = match[1], version = match[2] || 'latest';
+  var contents = [];
+  var lines, err;
+
+  if (!this.builtServices[service]) {
+    this.builtServices[service] = {};
+
+    lines = this.buildStrategy.getServiceHeader(service);
+    if (lines === null) {
+      if (!usingDefaultServices) {
+        err = new Error('Invalid module: ' + service);
+        err.name = 'InvalidModuleError';
+        throw err;
+      }
+    } else {
+      contents.push(lines);
+    }
+  }
+
+  if (!this.builtServices[service][version]) {
+    this.builtServices[service][version] = true;
+
+    lines = this.buildStrategy.getService(service, version);
+    if (lines === null) {
+      if (!usingDefaultServices) {
+        err = new Error('Invalid module: ' + service + '-' + version);
+        err.name = 'InvalidModuleError';
+        throw err;
+      }
+    } else {
+      contents.push(lines);
+    }
+  }
+
+  return contents.join('\n');
+};
+
+Builder.prototype.addServices = function(services) {
+  var usingDefaultServices = false;
+  if (!services) {
+    usingDefaultServices = true;
+    services = defaultServices;
+  }
+  if (services.match(sanitizeRegex)) {
+    throw new Error('Incorrectly formatted service names');
+  }
+
+  var invalidModules = [];
+  var stsIncluded = false;
+  services.split(',').sort().forEach(function(name) {
+    if (name.match(/^sts\b/) || name === 'all') stsIncluded = true;
+    try {
+      this.serviceCode.push(this.buildService(name, usingDefaultServices));
+    } catch (e) {
+      if (e.name === 'InvalidModuleError') invalidModules.push(name);
+      else throw e;
+    }
+  }.bind(this));
+
+  if (!stsIncluded) {
+    this.serviceCode.push(this.buildService('sts'));
+  }
+
+  if (invalidModules.length > 0) {
+    throw new Error('Missing modules: ' + invalidModules.join(', '));
+  }
+
+  return this;
+};
+
+Builder.prototype.build = function(callback) {
+  this.buildStrategy.getCore(function(err, core) {
+    callback(err, err ? null : (core + ';' + this.serviceCode.join('\n')));
+  }.bind(this));
+};
+
+// run if we called this tool directly
+if (require.main === module) {
+  var options = {
+    minify: process.env.MINIFY ? true : false,
+    cache: process.env.CACHE ? true : false,
+    writeCache: process.env.WRITE_CACHE ? true : false,
+    cacheRoot: process.env.CACHE_ROOT,
+    libPath: process.env.LIB_PATH
+  };
+  var services = process.argv[2] || process.env.SERVICES;
+  new Builder(options).addServices(services).build(function (err, code) {
+    if (err) console.error(err.message);
+    else console.log(code);
+  });
+}
+
+module.exports = Builder;

package/dist-tools/strategies/cache.js

@@ -0,0 +1,68 @@
+var fs = require('fs');
+
+function CacheStrategy(builder) {
+  this.builder = builder;
+  this.cacheRoot = this.builder.options.cacheRoot;
+  this.minify = this.builder.options.minify;
+
+  this.loadServices();
+  if (!this.builder.cacheExists()) {
+    fs.mkdirSync(this.builder.cachePath());
+  }
+}
+
+CacheStrategy.prototype.loadServices = function() {
+  this.services = {};
+  fs.readdirSync(this.cacheRoot).forEach(function(file) {
+    var match = file.match(/^([^_-]+)-(latest|\d+-\d+-\d+)\.(?:min\.)?js$/);
+    if (match) {
+      var service = match[1], version = match[2];
+      if (!this.services[service]) this.services[service] = {};
+      this.services[service][version] = service + '-' + version;
+    }
+  }.bind(this));
+};
+
+CacheStrategy.prototype.getServiceHeader = function(service) {
+  if (service === 'all') {
+    return Object.keys(this.services).map(function (name) {
+      return this.getServiceHeader(name);
+    }.bind(this)).join('\n');
+  }
+
+  if (this.services[service] && this.builder.cacheExists(service)) {
+    return this.read(service);
+  }
+  return null;
+};
+
+CacheStrategy.prototype.getService = function(service, version) {
+  if (service === 'all') {
+    return Object.keys(this.services).map(function (name) {
+      return this.getService(name);
+    }.bind(this)).join('\n');
+  }
+
+  var versions = this.services[service];
+  if (versions) {
+    var file = versions[version || 'latest'];
+    if (file && this.builder.cacheExists(file)) {
+      return this.read(file);
+    }
+  }
+  return null;
+};
+
+CacheStrategy.prototype.getCore = function(callback) {
+  if (this.builder.cacheExists('_core')) {
+    callback(null, this.read('_core'));
+  } else {
+    callback(new Error('Core not found.'));
+  }
+};
+
+CacheStrategy.prototype.read = function(path) {
+  return fs.readFileSync(this.builder.cachePath(path)).toString();
+};
+
+module.exports = CacheStrategy;

package/dist-tools/strategies/default.js

@@ -0,0 +1,165 @@
+var fs = require('fs');
+var util = require('util');
+var path = require('path');
+
+function DefaultStrategy(builder) {
+  this.builder = builder;
+  this.libPath = this.builder.options.libPath;
+  this.isCached = this.builder.options.writeCache;
+  this.isMinified = this.builder.options.minify;
+  this.minifyOptions = this.builder.options.minifyOptions || {};
+  this.minifyOptions.fromString = true;
+  this.AWS = require(this.libPath + '/lib/aws');
+  this.apis = require('aws-sdk-apis');
+  this.license = [
+    '// AWS SDK for JavaScript v' + this.AWS.VERSION,
+    '// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.',
+    '// License at https://sdk.amazonaws.com/js/BUNDLE_LICENSE.txt'
+  ].join('\n') + '\n';
+  this.setServiceClasses();
+
+  if (this.isCached && !this.builder.cacheExists()) {
+    fs.mkdirSync(this.builder.cachePath());
+  }
+}
+
+DefaultStrategy.prototype.setServiceClasses = function() {
+  this.serviceClasses = {};
+  this.AWS.util.each.call(this, this.AWS, function(name, serviceClass) {
+    if (serviceClass.serviceIdentifier) {
+      this.serviceClasses[serviceClass.serviceIdentifier] = serviceClass;
+    }
+  });
+};
+
+DefaultStrategy.prototype.minify = function(code) {
+  var uglify = require('uglify-js');
+  var minified = uglify.minify(code, this.minifyOptions);
+  return minified.code;
+};
+
+DefaultStrategy.prototype.stripComments = function(code) {
+  var lines = code.split(/\r?\n/);
+  var multiLine = false;
+  lines = lines.map(function (line) {
+    var rLine = line;
+    if (line.match(/^\s*\/\//)) {
+      rLine = null;
+    } else if (line.match(/^\s*\/\*/)) {
+      multiLine = true;
+      rLine = null;
+    }
+
+    if (multiLine) {
+      var multiLineEnd = line.match(/\*\/(.*)/);
+      if (multiLineEnd) {
+        multiLine = false;
+        rLine = multiLineEnd[1];
+      } else {
+        rLine = null;
+      }
+    }
+
+    return rLine;
+  }).filter(function(l) { return l !== null; });
+
+  var newCode = lines.join('\n');
+  newCode = newCode.replace(/\/\*\*[\s\S]+?Copyright\s+.+?Amazon[\s\S]+?\*\//g, '');
+  return newCode;
+};
+
+DefaultStrategy.prototype.getServiceHeader = function(service) {
+  if (service === 'all') {
+    return Object.keys(this.serviceClasses).map(function(service) {
+      return this.getServiceHeader(service);
+    }.bind(this)).join('\n');
+  }
+
+  var file = util.format(
+    'AWS.%s = AWS.Service.defineService(\'%s\');\n',
+    this.apis.serviceName(service), service);
+  var svcPath = this.libPath + '/lib/services/' + service + '.js';
+  if (fs.existsSync(svcPath)) {
+    var lines = fs.readFileSync(svcPath).toString().split(/\r?\n/);
+    file += lines.map(function (line) {
+      line = line.replace(/^var\s*.*\s*=\s*require\s*\(.+\).*/, '');
+      line = line.replace(/^module.exports\s*=.*/, '');
+      return line;
+    }).join('\n');
+  }
+
+  if (this.isMinified) file = this.minify(file);
+  else file = this.stripComments(file);
+
+  if (this.isCached) {
+    fs.writeFileSync(this.builder.cachePath(service), file);
+  }
+
+  return file;
+};
+
+DefaultStrategy.prototype.getService = function(service, version) {
+  if (service === 'all') {
+    return Object.keys(this.serviceClasses).map(function(service) {
+      var out = this.serviceClasses[service].apiVersions.map(function(version) {
+        if (version.indexOf('*') >= 0) return null;
+        return this.getService(service, version);
+      }.bind(this)).filter(function(c) { return c !== null; }).join('\n');
+
+      if (this.isCached) {
+        // build 'latest', but don't add it to code (for caching)
+        this.getService(service, 'latest');
+      }
+
+      return out;
+    }.bind(this)).join('\n');
+  }
+
+  var svc, api;
+  if (!this.serviceClasses[service]) {
+    return null;
+  }
+
+  try {
+    var ClassName = this.serviceClasses[service];
+    svc = new ClassName({apiVersion: version, endpoint: 'localhost'});
+    api = this.apis.load(service, svc.api.apiVersion);
+  } catch (e) {
+    return null;
+  }
+
+  var line = util.format(
+    'AWS.Service.defineServiceApi(AWS.%s, "%s", %s);',
+    this.apis.serviceName(service), svc.api.apiVersion, JSON.stringify(api));
+
+  if (this.isCached) {
+    fs.writeFileSync(this.builder.cachePath(service + '-' + version), line);
+  }
+
+  return line;
+};
+
+DefaultStrategy.prototype.getCore = function(callback) {
+  var img = require('browserify/node_modules/insert-module-globals');
+  img.vars.process = function() { return '{browser:true}'; };
+
+  var browserify = require('browserify');
+  var opts = { basedir: this.libPath };
+  browserify(opts).add('./lib/browser').
+      ignore('domain').bundle(function (err, data) {
+    if (err) return callback(err);
+
+    var code = (data || '').toString();
+    if (this.isMinified) code = this.minify(code);
+    else code = this.stripComments(code);
+
+    code = this.license + code;
+    if (this.isCached) {
+      fs.writeFileSync(this.builder.cachePath('_core'), code);
+    }
+
+    callback(null, code);
+  }.bind(this));
+};
+
+module.exports = DefaultStrategy;

package/dist-tools/test/browser-builder.mocha.spec.coffee

@@ -0,0 +1,182 @@
+helpers = require('./helpers')
+Builder = helpers.Builder
+exec = require('child_process').exec
+fs = require('fs')
+expect = helpers.chai.expect
+
+describe 'Builder', ->
+  describe 'addServices', ->
+    builder = null
+    code = null
+    beforeEach -> builder = new helpers.Builder
+
+    add = (services) ->
+      builder.addServices(services)
+      code = builder.serviceCode.join('\n')
+
+    assertServiceAdded = (klass, version) ->
+      version = version || new helpers.AWS[klass](endpoint: 'localhost').api.apiVersion;
+      expect(code).to.match(new RegExp('AWS\\.' + klass +
+        ' = AWS\\.Service\\.defineService\\(\'' +
+        helpers.AWS[klass].serviceIdentifier + '\''))
+      expect(code).to.match(new RegExp(
+        'AWS\\.Service\\.defineServiceApi\\(AWS\\.' +
+        klass + ', "' + version + '",'))
+
+    assertBundleFailed = (services, errMsg) ->
+      expect(-> builder.addServices(services)).to.throw(errMsg)
+
+    it 'accepts comma delimited services by name', ->
+      add 's3,cloudwatch'
+      assertServiceAdded 'S3'
+      assertServiceAdded 'CloudWatch'
+      assertServiceAdded 'STS' # STS always added
+
+    it 'uses latest service version if version suffix is not supplied', ->
+      add 'rds'
+      assertServiceAdded 'RDS'
+
+    it 'accepts fully qualified service-version pair', ->
+      add 'rds-2013-09-09'
+      assertServiceAdded 'RDS', '2013-09-09'
+
+    it 'accepts "all" for all services', ->
+      add 'all'
+      Object.keys(builder.buildStrategy.serviceClasses).forEach (s) ->
+        name = builder.buildStrategy.apis.serviceName(s)
+        assertServiceAdded(name)
+
+    it 'throws an error if the service does not exist', ->
+      assertBundleFailed 'invalidmodule', 'Missing modules: invalidmodule'
+
+    it 'throws an error if the service version does not exist', ->
+      services = 's3-1999-01-01'
+      msg = 'Missing modules: s3-1999-01-01'
+      assertBundleFailed(services, msg)
+
+    it 'groups multiple errors into one error object', ->
+      services = 's3-1999-01-01,invalidmodule,dynamodb-01-01-01'
+      msg = 'Missing modules: dynamodb-01-01-01, invalidmodule, s3-1999-01-01'
+      assertBundleFailed(services, msg)
+
+    it 'throws an opaque error if special characters are found (/, ., *)', ->
+      msg = 'Incorrectly formatted service names'
+      assertBundleFailed('path/to/service', msg)
+      assertBundleFailed('to/../../../root', msg)
+      assertBundleFailed('*.js', msg)
+      assertBundleFailed('a.b', msg)
+      assertBundleFailed('a=b', msg)
+      assertBundleFailed('!d', msg)
+      assertBundleFailed('valid1,valid2,invalid.module', msg)
+
+  describe 'build', ->
+    bundleCache = {}
+    data = null
+
+    beforeEach -> data = ''
+
+    buildBundle = (services, opts, code, cb) ->
+      cacheKey = JSON.stringify(services: services, options: opts)
+      if bundleCache[cacheKey]
+        result = null
+        if code
+          result = helpers.evalCode(code, bundleCache[cacheKey])
+        return cb(null, result)
+
+      opts = opts || {}
+      new Builder(opts).addServices(services).build (err, d) ->
+        data = d
+        bundleCache[cacheKey] = data
+        result = null
+        if !err && code
+          result = helpers.evalCode(code, data)
+        cb(err, result)
+
+    it 'defaults to no minification', ->
+      buildBundle null, null, 'window.AWS', (err, AWS) ->
+        expect(data).to.match(/Copyright Amazon\.com/i)
+
+    it 'can be minified (slow)', ->
+      buildBundle null, minify: true, null, ->
+        expect(data).to.match(/Copyright Amazon\.com/i) # has license
+        expect(data).to.match(/function \w\(\w,\w,\w\)\{function \w\(\w,\w\)\{/)
+
+    it 'can build default services into bundle', ->
+      buildBundle null, null, 'window.AWS', (err, AWS) ->
+        expect(new AWS.S3().api.apiVersion).to.equal(new helpers.AWS.S3().api.apiVersion)
+        expect(new AWS.DynamoDB().api.apiVersion).to.equal(new helpers.AWS.DynamoDB().api.apiVersion)
+        expect(new AWS.STS().api.apiVersion).to.equal(new helpers.AWS.STS().api.apiVersion)
+
+    it 'can build all services into bundle', ->
+      buildBundle 'all', null, 'window.AWS', (err, AWS) ->
+        Object.keys(helpers.AWS).forEach (k) ->
+          if k.serviceIdentifier
+            expect(typeof AWS[k]).to.equal('object')
+
+    describe 'cached writer', ->
+      it 'writes core and services to disk', (done) ->
+        root = __dirname + '/tmpcache/'
+        builder = new Builder(writeCache: true, cacheRoot: root)
+        builder.addServices('s3').build ->
+          try
+            ['s3.js', 's3-latest.js', '_core.js'].forEach (item) ->
+              expect(fs.existsSync(root + item)).to.equal(true, item + ' exists?')
+          finally
+            exec('rm -rf ' + root, done)
+
+      it 'writes minified core and services to disk', (done) ->
+        root = __dirname + '/tmpcache/'
+        builder = new Builder(writeCache: true, cacheRoot: root, minify: true)
+        builder.addServices('s3').build ->
+          try
+            ['s3.min.js', 's3-latest.min.js', '_core.min.js'].forEach (item) ->
+              expect(fs.existsSync(root + item)).to.equal(true, item + ' exists?')
+          finally
+            exec('rm -rf ' + root, done)
+
+    describe 'cached loading', ->
+      root = __dirname + '/tmpcache/'
+
+      it 'sets up cache', (done) ->
+        builder = new Builder(writeCache: true, cacheRoot: root)
+        builder.addServices('s3').build(done)
+
+      it 'loads from cache', ->
+        builder = new Builder(cache: true, cacheRoot: root)
+        builder.addServices('all').build (err, code) ->
+          expect(code).to.contain('AWS.S3 = ')
+
+      it 'fails if cache item is missing', ->
+        builder = new Builder(cache: true, cacheRoot: root)
+        expect(-> builder.addServices('kinesis')).to.throw('Missing modules: kinesis')
+
+      it 'fails to load from core if core is missing', (done) ->
+        exec 'rm ' + root + '_core.js', ->
+          builder = new Builder(cache: true, cacheRoot: root)
+          builder.addServices('s3').build (err, data) ->
+            expect(err.message).to.equal('Core not found.')
+            expect(data).to.equal(null)
+            done()
+
+      it 'removes cache', (done) ->
+        exec('rm -rf ' + root, done)
+
+    describe 'as executable', ->
+      cwd = __dirname + '/../'
+      script = './browser-builder.js '
+
+      it 'uses first argument to get services list', (done)  ->
+        exec script + 'iam-2010-05-08', cwd: cwd, maxBuffer: 999999999, (e, out) ->
+          expect(out).to.match(/Copyright Amazon\.com/i)
+          expect(out).to.contain('"2010-05-08"')
+          expect(out).not.to.contain('"2006-03-01"')
+          done()
+
+      it 'uses MINIFY environment variable to set minification mode', (done) ->
+        env = JSON.parse(JSON.stringify(process.env))
+        env.MINIFY = '1'
+        exec script, cwd: cwd, maxBuffer: 999999999, (e, out) ->
+          expect(out).to.match(/Copyright Amazon\.com/i)
+          expect(out).to.match(/function \w\(\w,\w,\w\)\{function \w\(\w,\w\)\{/)
+          expect(out).to.contain('"2006-03-01"')
+          done()

package/dist-tools/test/helpers.coffee

@@ -0,0 +1,16 @@
+fs = require('fs')
+
+evalCode = (code, preamble) ->
+  eval """
+    (function() {
+      var window = GLOBAL;
+      #{preamble};
+      return #{code};
+    })();
+  """
+
+module.exports =
+  AWS: require('../../lib/aws')
+  Builder: require('../browser-builder')
+  chai: require('chai')
+  evalCode: evalCode

package/doc-src/guide/browser-building.md

@@ -0,0 +1,93 @@
+# @title Building the SDK for the Browser
+
+# Building the SDK for Use in the Browser
+
+This section explains how you can create your own build of the AWS SDK for
+JavaScript. If you are working with the SDK outside of an environment that
+enforces CORS in your browser and want access to the full gamut of services
+provided by the **AWS SDK for JavaScript**, it is possible to build a custom
+copy of the SDK locally by cloning the repository and running the same build
+tools used to generate the default hosted version of the SDK. This chapter
+outlines the steps to build the SDK on your own with extra services and API
+versions.
+
+## Setting Up
+
+In order to build the SDK, you first need to clone the Git repository containing
+the SDK source. These instructions assume you have [Git](http://git-scm.org) and
+a version of [Node.js](http://nodejs.org) installed on your machine.
+
+First, clone the repository from GitHub and cd into the directory:
+
+```bash
+git clone git://github.com/aws/aws-sdk-js
+cd aws-sdk-js
+```
+
+After you have cloned the repository, you need to download the dependency modules
+for both the SDK and build tool:
+
+```bash
+npm install
+```
+
+You should now be able to build a packaged version of the SDK.
+
+## Building
+
+The builder tool is found in `dist-tools/browser-builder.js`. You can run
+this script by typing:
+
+```bash
+node dist-tools/browser-builder.js > aws-sdk.js
+```
+
+This will build to the file `aws-sdk.js`. By default this package includes
+only the services documented in the {file:browser-services.md Working With Services}
+chapter. Building custom services is discussed later in this chapter. Note
+also that by default, this file is uncompressed.
+
+### Minifying Output
+
+The builder tool can also compress output. To do this, set the `MINIFY`
+environment variable like so:
+
+```bash
+MINIFY=1 node dist-tools/browser-builder.js > aws-sdk.js
+```
+
+### Building Specific Services and API Versions
+
+#### Selecting Services to Build
+
+When building via the builder tool, you can select which services you want to
+build into the SDK. To select services, specify the names of the services
+delimited by commas as arguments to the tool on the command-line. For example,
+to build only Amazon S3 and Amazon EC2, use the following command:
+
+```bash
+node dist-tools/browser-builder.js s3,ec2 > aws-sdk-s3-ec2.js
+```
+
+#### Selecting API Versions
+
+You can also select specific API versions of services when building
+by suffixing the version name after the service identifier. For example, to
+build both API versions of Amazon DynamoDB, you could use the following
+command:
+
+```bash
+node dist-tools/browser-builder.js dynamodb-2011-12-05,dynamodb-2012-08-10
+```
+
+Available service identifiers and API versions can be found by looking at the
+file list in https://github.com/aws/aws-sdk-js/tree/master/lib/services/api
+
+#### Building All Services
+
+Finally, you can build **all services** (and API versions) by passing "all"
+as a command-line argument:
+
+```bash
+node dist-tools/browser-builder.js all > aws-sdk-full.js
+```