config.js (21710B)
1 var AWS = require('./core'); 2 require('./credentials'); 3 require('./credentials/credential_provider_chain'); 4 var PromisesDependency; 5 6 /** 7 * The main configuration class used by all service objects to set 8 * the region, credentials, and other options for requests. 9 * 10 * By default, credentials and region settings are left unconfigured. 11 * This should be configured by the application before using any 12 * AWS service APIs. 13 * 14 * In order to set global configuration options, properties should 15 * be assigned to the global {AWS.config} object. 16 * 17 * @see AWS.config 18 * 19 * @!group General Configuration Options 20 * 21 * @!attribute credentials 22 * @return [AWS.Credentials] the AWS credentials to sign requests with. 23 * 24 * @!attribute region 25 * @example Set the global region setting to us-west-2 26 * AWS.config.update({region: 'us-west-2'}); 27 * @return [AWS.Credentials] The region to send service requests to. 28 * @see http://docs.amazonwebservices.com/general/latest/gr/rande.html 29 * A list of available endpoints for each AWS service 30 * 31 * @!attribute maxRetries 32 * @return [Integer] the maximum amount of retries to perform for a 33 * service request. By default this value is calculated by the specific 34 * service object that the request is being made to. 35 * 36 * @!attribute maxRedirects 37 * @return [Integer] the maximum amount of redirects to follow for a 38 * service request. Defaults to 10. 39 * 40 * @!attribute paramValidation 41 * @return [Boolean|map] whether input parameters should be validated against 42 * the operation description before sending the request. Defaults to true. 43 * Pass a map to enable any of the following specific validation features: 44 * 45 * * **min** [Boolean] — Validates that a value meets the min 46 * constraint. This is enabled by default when paramValidation is set 47 * to `true`. 48 * * **max** [Boolean] — Validates that a value meets the max 49 * constraint. 50 * * **pattern** [Boolean] — Validates that a string value matches a 51 * regular expression. 52 * * **enum** [Boolean] — Validates that a string value matches one 53 * of the allowable enum values. 54 * 55 * @!attribute computeChecksums 56 * @return [Boolean] whether to compute checksums for payload bodies when 57 * the service accepts it (currently supported in S3 only). 58 * 59 * @!attribute convertResponseTypes 60 * @return [Boolean] whether types are converted when parsing response data. 61 * Currently only supported for JSON based services. Turning this off may 62 * improve performance on large response payloads. Defaults to `true`. 63 * 64 * @!attribute correctClockSkew 65 * @return [Boolean] whether to apply a clock skew correction and retry 66 * requests that fail because of an skewed client clock. Defaults to 67 * `false`. 68 * 69 * @!attribute sslEnabled 70 * @return [Boolean] whether SSL is enabled for requests 71 * 72 * @!attribute s3ForcePathStyle 73 * @return [Boolean] whether to force path style URLs for S3 objects 74 * 75 * @!attribute s3BucketEndpoint 76 * @note Setting this configuration option requires an `endpoint` to be 77 * provided explicitly to the service constructor. 78 * @return [Boolean] whether the provided endpoint addresses an individual 79 * bucket (false if it addresses the root API endpoint). 80 * 81 * @!attribute s3DisableBodySigning 82 * @return [Boolean] whether to disable S3 body signing when using signature version `v4`. 83 * Body signing can only be disabled when using https. Defaults to `true`. 84 * 85 * @!attribute useAccelerateEndpoint 86 * @note This configuration option is only compatible with S3 while accessing 87 * dns-compatible buckets. 88 * @return [Boolean] Whether to use the Accelerate endpoint with the S3 service. 89 * Defaults to `false`. 90 * 91 * @!attribute retryDelayOptions 92 * @example Set the base retry delay for all services to 300 ms 93 * AWS.config.update({retryDelayOptions: {base: 300}}); 94 * // Delays with maxRetries = 3: 300, 600, 1200 95 * @example Set a custom backoff function to provide delay values on retries 96 * AWS.config.update({retryDelayOptions: {customBackoff: function(retryCount) { 97 * // returns delay in ms 98 * }}}); 99 * @note This works with all services except DynamoDB. 100 * @return [map] A set of options to configure the retry delay on retryable errors. 101 * Currently supported options are: 102 * 103 * * **base** [Integer] — The base number of milliseconds to use in the 104 * exponential backoff for operation retries. Defaults to 100 ms. 105 * * **customBackoff ** [function] — A custom function that accepts a retry count 106 * and returns the amount of time to delay in milliseconds. The `base` option will be 107 * ignored if this option is supplied. 108 * 109 * @!attribute httpOptions 110 * @return [map] A set of options to pass to the low-level HTTP request. 111 * Currently supported options are: 112 * 113 * * **proxy** [String] — the URL to proxy requests through 114 * * **agent** [http.Agent, https.Agent] — the Agent object to perform 115 * HTTP requests with. Used for connection pooling. Defaults to the global 116 * agent (`http.globalAgent`) for non-SSL connections. Note that for 117 * SSL connections, a special Agent object is used in order to enable 118 * peer certificate verification. This feature is only supported in the 119 * Node.js environment. 120 * * **timeout** [Integer] — The number of milliseconds to wait before 121 * giving up on a connection attempt. Defaults to two minutes (120000). 122 * * **xhrAsync** [Boolean] — Whether the SDK will send asynchronous 123 * HTTP requests. Used in the browser environment only. Set to false to 124 * send requests synchronously. Defaults to true (async on). 125 * * **xhrWithCredentials** [Boolean] — Sets the "withCredentials" 126 * property of an XMLHttpRequest object. Used in the browser environment 127 * only. Defaults to false. 128 * @!attribute logger 129 * @return [#write,#log] an object that responds to .write() (like a stream) 130 * or .log() (like the console object) in order to log information about 131 * requests 132 * 133 * @!attribute systemClockOffset 134 * @return [Number] an offset value in milliseconds to apply to all signing 135 * times. Use this to compensate for clock skew when your system may be 136 * out of sync with the service time. Note that this configuration option 137 * can only be applied to the global `AWS.config` object and cannot be 138 * overridden in service-specific configuration. Defaults to 0 milliseconds. 139 * 140 * @!attribute signatureVersion 141 * @return [String] the signature version to sign requests with (overriding 142 * the API configuration). Possible values are: 'v2', 'v3', 'v4'. 143 * 144 * @!attribute signatureCache 145 * @return [Boolean] whether the signature to sign requests with (overriding 146 * the API configuration) is cached. Only applies to the signature version 'v4'. 147 * Defaults to `true`. 148 */ 149 AWS.Config = AWS.util.inherit({ 150 /** 151 * @!endgroup 152 */ 153 154 /** 155 * Creates a new configuration object. This is the object that passes 156 * option data along to service requests, including credentials, security, 157 * region information, and some service specific settings. 158 * 159 * @example Creating a new configuration object with credentials and region 160 * var config = new AWS.Config({ 161 * accessKeyId: 'AKID', secretAccessKey: 'SECRET', region: 'us-west-2' 162 * }); 163 * @option options accessKeyId [String] your AWS access key ID. 164 * @option options secretAccessKey [String] your AWS secret access key. 165 * @option options sessionToken [AWS.Credentials] the optional AWS 166 * session token to sign requests with. 167 * @option options credentials [AWS.Credentials] the AWS credentials 168 * to sign requests with. You can either specify this object, or 169 * specify the accessKeyId and secretAccessKey options directly. 170 * @option options credentialProvider [AWS.CredentialProviderChain] the 171 * provider chain used to resolve credentials if no static `credentials` 172 * property is set. 173 * @option options region [String] the region to send service requests to. 174 * See {region} for more information. 175 * @option options maxRetries [Integer] the maximum amount of retries to 176 * attempt with a request. See {maxRetries} for more information. 177 * @option options maxRedirects [Integer] the maximum amount of redirects to 178 * follow with a request. See {maxRedirects} for more information. 179 * @option options sslEnabled [Boolean] whether to enable SSL for 180 * requests. 181 * @option options paramValidation [Boolean|map] whether input parameters 182 * should be validated against the operation description before sending 183 * the request. Defaults to true. Pass a map to enable any of the 184 * following specific validation features: 185 * 186 * * **min** [Boolean] — Validates that a value meets the min 187 * constraint. This is enabled by default when paramValidation is set 188 * to `true`. 189 * * **max** [Boolean] — Validates that a value meets the max 190 * constraint. 191 * * **pattern** [Boolean] — Validates that a string value matches a 192 * regular expression. 193 * * **enum** [Boolean] — Validates that a string value matches one 194 * of the allowable enum values. 195 * @option options computeChecksums [Boolean] whether to compute checksums 196 * for payload bodies when the service accepts it (currently supported 197 * in S3 only) 198 * @option options convertResponseTypes [Boolean] whether types are converted 199 * when parsing response data. Currently only supported for JSON based 200 * services. Turning this off may improve performance on large response 201 * payloads. Defaults to `true`. 202 * @option options correctClockSkew [Boolean] whether to apply a clock skew 203 * correction and retry requests that fail because of an skewed client 204 * clock. Defaults to `false`. 205 * @option options s3ForcePathStyle [Boolean] whether to force path 206 * style URLs for S3 objects. 207 * @option options s3BucketEndpoint [Boolean] whether the provided endpoint 208 * addresses an individual bucket (false if it addresses the root API 209 * endpoint). Note that setting this configuration option requires an 210 * `endpoint` to be provided explicitly to the service constructor. 211 * @option options s3DisableBodySigning [Boolean] whether S3 body signing 212 * should be disabled when using signature version `v4`. Body signing 213 * can only be disabled when using https. Defaults to `true`. 214 * 215 * @option options retryDelayOptions [map] A set of options to configure 216 * the retry delay on retryable errors. Currently supported options are: 217 * 218 * * **base** [Integer] — The base number of milliseconds to use in the 219 * exponential backoff for operation retries. Defaults to 100 ms. 220 * * **customBackoff ** [function] — A custom function that accepts a retry count 221 * and returns the amount of time to delay in milliseconds. The `base` option will be 222 * ignored if this option is supplied. 223 * @option options httpOptions [map] A set of options to pass to the low-level 224 * HTTP request. Currently supported options are: 225 * 226 * * **proxy** [String] — the URL to proxy requests through 227 * * **agent** [http.Agent, https.Agent] — the Agent object to perform 228 * HTTP requests with. Used for connection pooling. Defaults to the global 229 * agent (`http.globalAgent`) for non-SSL connections. Note that for 230 * SSL connections, a special Agent object is used in order to enable 231 * peer certificate verification. This feature is only available in the 232 * Node.js environment. 233 * * **timeout** [Integer] — Sets the socket to timeout after timeout 234 * milliseconds of inactivity on the socket. Defaults to two minutes 235 * (120000). 236 * * **xhrAsync** [Boolean] — Whether the SDK will send asynchronous 237 * HTTP requests. Used in the browser environment only. Set to false to 238 * send requests synchronously. Defaults to true (async on). 239 * * **xhrWithCredentials** [Boolean] — Sets the "withCredentials" 240 * property of an XMLHttpRequest object. Used in the browser environment 241 * only. Defaults to false. 242 * @option options apiVersion [String, Date] a String in YYYY-MM-DD format 243 * (or a date) that represents the latest possible API version that can be 244 * used in all services (unless overridden by `apiVersions`). Specify 245 * 'latest' to use the latest possible version. 246 * @option options apiVersions [map<String, String|Date>] a map of service 247 * identifiers (the lowercase service class name) with the API version to 248 * use when instantiating a service. Specify 'latest' for each individual 249 * that can use the latest available version. 250 * @option options logger [#write,#log] an object that responds to .write() 251 * (like a stream) or .log() (like the console object) in order to log 252 * information about requests 253 * @option options systemClockOffset [Number] an offset value in milliseconds 254 * to apply to all signing times. Use this to compensate for clock skew 255 * when your system may be out of sync with the service time. Note that 256 * this configuration option can only be applied to the global `AWS.config` 257 * object and cannot be overridden in service-specific configuration. 258 * Defaults to 0 milliseconds. 259 * @option options signatureVersion [String] the signature version to sign 260 * requests with (overriding the API configuration). Possible values are: 261 * 'v2', 'v3', 'v4'. 262 * @option options signatureCache [Boolean] whether the signature to sign 263 * requests with (overriding the API configuration) is cached. Only applies 264 * to the signature version 'v4'. Defaults to `true`. 265 */ 266 constructor: function Config(options) { 267 if (options === undefined) options = {}; 268 options = this.extractCredentials(options); 269 270 AWS.util.each.call(this, this.keys, function (key, value) { 271 this.set(key, options[key], value); 272 }); 273 }, 274 275 /** 276 * @!group Managing Credentials 277 */ 278 279 /** 280 * Loads credentials from the configuration object. This is used internally 281 * by the SDK to ensure that refreshable {Credentials} objects are properly 282 * refreshed and loaded when sending a request. If you want to ensure that 283 * your credentials are loaded prior to a request, you can use this method 284 * directly to provide accurate credential data stored in the object. 285 * 286 * @note If you configure the SDK with static or environment credentials, 287 * the credential data should already be present in {credentials} attribute. 288 * This method is primarily necessary to load credentials from asynchronous 289 * sources, or sources that can refresh credentials periodically. 290 * @example Getting your access key 291 * AWS.config.getCredentials(function(err) { 292 * if (err) console.log(err.stack); // credentials not loaded 293 * else console.log("Access Key:", AWS.config.credentials.accessKeyId); 294 * }) 295 * @callback callback function(err) 296 * Called when the {credentials} have been properly set on the configuration 297 * object. 298 * 299 * @param err [Error] if this is set, credentials were not successfuly 300 * loaded and this error provides information why. 301 * @see credentials 302 * @see Credentials 303 */ 304 getCredentials: function getCredentials(callback) { 305 var self = this; 306 307 function finish(err) { 308 callback(err, err ? null : self.credentials); 309 } 310 311 function credError(msg, err) { 312 return new AWS.util.error(err || new Error(), { 313 code: 'CredentialsError', message: msg 314 }); 315 } 316 317 function getAsyncCredentials() { 318 self.credentials.get(function(err) { 319 if (err) { 320 var msg = 'Could not load credentials from ' + 321 self.credentials.constructor.name; 322 err = credError(msg, err); 323 } 324 finish(err); 325 }); 326 } 327 328 function getStaticCredentials() { 329 var err = null; 330 if (!self.credentials.accessKeyId || !self.credentials.secretAccessKey) { 331 err = credError('Missing credentials'); 332 } 333 finish(err); 334 } 335 336 if (self.credentials) { 337 if (typeof self.credentials.get === 'function') { 338 getAsyncCredentials(); 339 } else { // static credentials 340 getStaticCredentials(); 341 } 342 } else if (self.credentialProvider) { 343 self.credentialProvider.resolve(function(err, creds) { 344 if (err) { 345 err = credError('Could not load credentials from any providers', err); 346 } 347 self.credentials = creds; 348 finish(err); 349 }); 350 } else { 351 finish(credError('No credentials to load')); 352 } 353 }, 354 355 /** 356 * @!group Loading and Setting Configuration Options 357 */ 358 359 /** 360 * @overload update(options, allowUnknownKeys = false) 361 * Updates the current configuration object with new options. 362 * 363 * @example Update maxRetries property of a configuration object 364 * config.update({maxRetries: 10}); 365 * @param [Object] options a map of option keys and values. 366 * @param [Boolean] allowUnknownKeys whether unknown keys can be set on 367 * the configuration object. Defaults to `false`. 368 * @see constructor 369 */ 370 update: function update(options, allowUnknownKeys) { 371 allowUnknownKeys = allowUnknownKeys || false; 372 options = this.extractCredentials(options); 373 AWS.util.each.call(this, options, function (key, value) { 374 if (allowUnknownKeys || Object.prototype.hasOwnProperty.call(this.keys, key) || 375 AWS.Service.hasService(key)) { 376 this.set(key, value); 377 } 378 }); 379 }, 380 381 /** 382 * Loads configuration data from a JSON file into this config object. 383 * @note Loading configuration will reset all existing configuration 384 * on the object. 385 * @!macro nobrowser 386 * @param path [String] the path relative to your process's current 387 * working directory to load configuration from. 388 * @return [AWS.Config] the same configuration object 389 */ 390 loadFromPath: function loadFromPath(path) { 391 this.clear(); 392 393 var options = JSON.parse(AWS.util.readFileSync(path)); 394 var fileSystemCreds = new AWS.FileSystemCredentials(path); 395 var chain = new AWS.CredentialProviderChain(); 396 chain.providers.unshift(fileSystemCreds); 397 chain.resolve(function (err, creds) { 398 if (err) throw err; 399 else options.credentials = creds; 400 }); 401 402 this.constructor(options); 403 404 return this; 405 }, 406 407 /** 408 * Clears configuration data on this object 409 * 410 * @api private 411 */ 412 clear: function clear() { 413 /*jshint forin:false */ 414 AWS.util.each.call(this, this.keys, function (key) { 415 delete this[key]; 416 }); 417 418 // reset credential provider 419 this.set('credentials', undefined); 420 this.set('credentialProvider', undefined); 421 }, 422 423 /** 424 * Sets a property on the configuration object, allowing for a 425 * default value 426 * @api private 427 */ 428 set: function set(property, value, defaultValue) { 429 if (value === undefined) { 430 if (defaultValue === undefined) { 431 defaultValue = this.keys[property]; 432 } 433 if (typeof defaultValue === 'function') { 434 this[property] = defaultValue.call(this); 435 } else { 436 this[property] = defaultValue; 437 } 438 } else if (property === 'httpOptions' && this[property]) { 439 // deep merge httpOptions 440 this[property] = AWS.util.merge(this[property], value); 441 } else { 442 this[property] = value; 443 } 444 }, 445 446 /** 447 * All of the keys with their default values. 448 * 449 * @constant 450 * @api private 451 */ 452 keys: { 453 credentials: null, 454 credentialProvider: null, 455 region: null, 456 logger: null, 457 apiVersions: {}, 458 apiVersion: null, 459 endpoint: undefined, 460 httpOptions: { 461 timeout: 120000 462 }, 463 maxRetries: undefined, 464 maxRedirects: 10, 465 paramValidation: true, 466 sslEnabled: true, 467 s3ForcePathStyle: false, 468 s3BucketEndpoint: false, 469 s3DisableBodySigning: true, 470 computeChecksums: true, 471 convertResponseTypes: true, 472 correctClockSkew: false, 473 customUserAgent: null, 474 dynamoDbCrc32: true, 475 systemClockOffset: 0, 476 signatureVersion: null, 477 signatureCache: true, 478 retryDelayOptions: { 479 base: 100 480 }, 481 useAccelerateEndpoint: false 482 }, 483 484 /** 485 * Extracts accessKeyId, secretAccessKey and sessionToken 486 * from a configuration hash. 487 * 488 * @api private 489 */ 490 extractCredentials: function extractCredentials(options) { 491 if (options.accessKeyId && options.secretAccessKey) { 492 options = AWS.util.copy(options); 493 options.credentials = new AWS.Credentials(options); 494 } 495 return options; 496 }, 497 498 /** 499 * Sets the promise dependency the SDK will use wherever Promises are returned. 500 * @param [Constructor] dep A reference to a Promise constructor 501 */ 502 setPromisesDependency: function setPromisesDependency(dep) { 503 PromisesDependency = dep; 504 var constructors = [AWS.Request, AWS.Credentials, AWS.CredentialProviderChain]; 505 if (AWS.S3 && AWS.S3.ManagedUpload) constructors.push(AWS.S3.ManagedUpload); 506 AWS.util.addPromises(constructors, dep); 507 }, 508 509 /** 510 * Gets the promise dependency set by `AWS.config.setPromisesDependency`. 511 */ 512 getPromisesDependency: function getPromisesDependency() { 513 return PromisesDependency; 514 } 515 }); 516 517 /** 518 * @return [AWS.Config] The global configuration object singleton instance 519 * @readonly 520 * @see AWS.Config 521 */ 522 AWS.config = new AWS.Config();