Add Serverless instanceId concept

docs/providers/aws/guide/resources.md

@@ -52,12 +52,12 @@ You can overwrite/attach any kind of resource to your CloudFormation stack. You
 
 To have consistent naming in the CloudFormation Templates that get deployed we use a standard pattern:
 
-`{Function Name}{Cloud Formation Resource Type}{Resource Name}{SequentialID or Random String}`
+`{Function Name}{Cloud Formation Resource Type}{Resource Name}{SequentialID, instanceId or Random String}`
 
 * `Function Name` - This is optional for Resources that should be recreated when the function name gets changed. Those resources are also called *function bound*
 * `Cloud Formation Resource Type` - E.g., S3Bucket
 * `Resource Name` - An identifier for the specific resource, e.g. for an S3 Bucket the configured bucket name.
-* `SequentialID or Random String` - For a few resources we need to add an optional sequential id or random string to identify them
+* `SequentialID, instanceId or Random String` - For a few resources we need to add an optional sequential id, the Serverless instanceId (accessible via `${sls:instanceId}`) or a random string to identify them
 
 All resource names that are deployed by Serverless have to follow this naming scheme. The only exception (for backwards compatibility reasons) is the S3 Bucket that is used to upload artifacts so they can be deployed to your function.
 
@@ -81,7 +81,7 @@ If you are unsure how a resource is named, that you want to reference from your
 |ApiGateway::Resource   | ApiGatewayResource{normalizedPath}                      | ApiGatewayResourceUsers       |
 |ApiGateway::Method     | ApiGatewayMethod{normalizedPath}{normalizedMethod}      | ApiGatewayMethodUsersGet      |
 |ApiGateway::Authorizer | {normalizedFunctionName}ApiGatewayAuthorizer            | HelloApiGatewayAuthorizer     |
-|ApiGateway::Deployment | ApiGatewayDeployment{randomNumber}                      | ApiGatewayDeployment12356789  |
+|ApiGateway::Deployment | ApiGatewayDeployment{instanceId}                      | ApiGatewayDeployment12356789  |
 |ApiGateway::ApiKey     | ApiGatewayApiKey{SequentialID}                          | ApiGatewayApiKey1             |
 |ApiGateway::UsagePlan  | ApiGatewayUsagePlan                          | ApiGatewayUsagePlan             |
 |ApiGateway::UsagePlanKey     | ApiGatewayUsagePlanKey{SequentialID}                          | ApiGatewayUsagePlanKey1             |

docs/providers/aws/guide/variables.md

@@ -33,6 +33,7 @@ You can define your own variable syntax (regex) if it conflicts with CloudFormat
 
 ## Current variable sources:
 
+- [Serverless Core variables](#referencing-serverless-core-variables)
 - [Environment variables](#referencing-environment-variables)
 - [CLI options](#referencing-cli-options)
 - [Other properties defined in `serverless.yml`](#reference-properties-in-serverlessyml)
@@ -103,6 +104,27 @@ resources:
 
 In the above example you're setting a global schedule for all functions by referencing the `globalSchedule` property in the same `serverless.yml` file. This way, you can easily change the schedule for all functions whenever you like.
 
+## Referencing Serverless Core Variables
+Serverless initializes core variables which are used internally by the Framework itself. Those values are exposed via the Serverless Variables system and can be re-used with the `{sls:}` variable prefix.
+
+The following variables are available:
+
+**instanceId**
+
+A random id which will be generated whenever the Serverless CLI is run. This value can be used when predictable random variables are required.
+
+```yml
+service: new-service
+provider: aws
+
+functions:
+  func1:
+    name: function-1
+    handler: handler.func1
+    environment:
+      APIG_DEPLOYMENT_ID: ApiGatewayDeployment${sls:instanceId}
+```
+
 ## Referencing Environment Variables
 To reference environment variables, use the `${env:SOME_VAR}` syntax in your `serverless.yml` configuration file.  It is valid to use the empty string in place of `SOME_VAR`.  This looks like "`${env:}`" and the result of declaring this in your `serverless.yml` is to embed the complete `process.env` object (i.e. all the variables defined in your environment).
 
@@ -296,7 +318,7 @@ functions:
     name: hello
     handler: handler.hello
 custom:
-  supersecret: 
+  supersecret:
     num: 1
     str: secret
     arr:

lib/Serverless.js

@@ -48,6 +48,9 @@ class Serverless {
   }
 
   init() {
+    // create an instanceId (can be e.g. used when a predictable random value is needed)
+    this.instanceId = (new Date()).getTime().toString();
+
     // create a new CLI instance
     this.cli = new this.classes.CLI(this);
 

lib/Serverless.test.js

@@ -125,6 +125,10 @@ describe('Serverless', () => {
       serverless.pluginManager.updateAutocompleteCacheFile.restore();
     });
 
+    it('should set an instanceId', () => serverless.init().then(() => {
+      expect(serverless.instanceId).to.match(/\d/);
+    }));
+
     it('should create a new CLI instance', () => serverless.init().then(() => {
       expect(serverless.cli).to.be.instanceof(CLI);
     }));

lib/classes/Variables.js

@@ -47,6 +47,7 @@ class Variables {
     this.deepRefSyntax = RegExp(/(\${)?deep:\d+(\.[^}]+)*()}?/);
     this.overwriteSyntax = RegExp(/\s*(?:,\s*)+/g);
     this.fileRefSyntax = RegExp(/^file\(([^?%*:|"<>]+?)\)/g);
+    this.slsRefSyntax = RegExp(/^sls:/g);
     this.envRefSyntax = RegExp(/^env:/g);
     this.optRefSyntax = RegExp(/^opt:/g);
     this.selfRefSyntax = RegExp(/^self:/g);
@@ -516,7 +517,9 @@ class Variables {
     if (this.tracker.contains(variableString)) {
       ret = this.tracker.get(variableString, propertyString);
     } else {
-      if (variableString.match(this.envRefSyntax)) {
+      if (variableString.match(this.slsRefSyntax)) {
+        ret = this.getValueFromSls(variableString);
+      } else if (variableString.match(this.envRefSyntax)) {
         ret = this.getValueFromEnv(variableString);
       } else if (variableString.match(this.optRefSyntax)) {
         ret = this.getValueFromOptions(variableString);
@@ -547,6 +550,15 @@ class Variables {
     return ret;
   }
 
+  getValueFromSls(variableString) {
+    let valueToPopulate = {};
+    const requestedSlsVar = variableString.split(':')[1];
+    if (requestedSlsVar === 'instanceId') {
+      valueToPopulate = this.serverless.instanceId;
+    }
+    return BbPromise.resolve(valueToPopulate);
+  }
+
   getValueFromEnv(variableString) { // eslint-disable-line class-methods-use-this
     const requestedEnvVar = variableString.split(':')[1];
     let valueToPopulate;

lib/classes/Variables.test.js

@@ -1328,97 +1328,119 @@ module.exports = {
   });
 
   describe('#getValueFromSource()', () => {
-    it('should call getValueFromEnv if referencing env var', () => {
-      const getValueFromEnvStub = sinon.stub(serverless.variables, 'getValueFromEnv')
+    const variableValue = 'variableValue';
+    let getValueFromSlsStub;
+    let getValueFromEnvStub;
+    let getValueFromOptionsStub;
+    let getValueFromSelfStub;
+    let getValueFromFileStub;
+    let getValueFromCfStub;
+    let getValueFromS3Stub;
+    let getValueFromSsmStub;
+
+    beforeEach(() => {
+      getValueFromSlsStub = sinon.stub(serverless.variables, 'getValueFromSls')
+        .resolves('variableValue');
+      getValueFromEnvStub = sinon.stub(serverless.variables, 'getValueFromEnv')
+        .resolves('variableValue');
+      getValueFromOptionsStub = sinon.stub(serverless.variables, 'getValueFromOptions')
+        .resolves('variableValue');
+      getValueFromSelfStub = sinon.stub(serverless.variables, 'getValueFromSelf')
+        .resolves('variableValue');
+      getValueFromFileStub = sinon.stub(serverless.variables, 'getValueFromFile')
         .resolves('variableValue');
-      return serverless.variables.getValueFromSource('env:TEST_VAR').should.be.fulfilled
+      getValueFromCfStub = sinon.stub(serverless.variables, 'getValueFromCf')
+        .resolves('variableValue');
+      getValueFromS3Stub = sinon.stub(serverless.variables, 'getValueFromS3')
+        .resolves('variableValue');
+      getValueFromSsmStub = sinon.stub(serverless.variables, 'getValueFromSsm')
+        .resolves('variableValue');
+    });
+
+    afterEach(() => {
+      serverless.variables.getValueFromSls.restore();
+      serverless.variables.getValueFromEnv.restore();
+      serverless.variables.getValueFromOptions.restore();
+      serverless.variables.getValueFromSelf.restore();
+      serverless.variables.getValueFromFile.restore();
+      serverless.variables.getValueFromCf.restore();
+      serverless.variables.getValueFromS3.restore();
+      serverless.variables.getValueFromSsm.restore();
+    });
+
+    it('should call getValueFromSls if referencing sls var', () => serverless.variables
+      .getValueFromSource('sls:instanceId').should.be.fulfilled
         .then((valueToPopulate) => {
-          expect(valueToPopulate).to.equal('variableValue');
+          expect(valueToPopulate).to.equal(variableValue);
+          expect(getValueFromSlsStub).to.have.been.called;
+          expect(getValueFromSlsStub).to.have.been.calledWith('sls:instanceId');
+        }));
+
+    it('should call getValueFromEnv if referencing env var', () => serverless.variables
+      .getValueFromSource('env:TEST_VAR').should.be.fulfilled
+        .then((valueToPopulate) => {
+          expect(valueToPopulate).to.equal(variableValue);
           expect(getValueFromEnvStub).to.have.been.called;
           expect(getValueFromEnvStub).to.have.been.calledWith('env:TEST_VAR');
-        })
-        .finally(() => getValueFromEnvStub.restore());
-    });
+        }));
 
-    it('should call getValueFromOptions if referencing an option', () => {
-      const getValueFromOptionsStub = sinon
-        .stub(serverless.variables, 'getValueFromOptions')
-        .resolves('variableValue');
-      return serverless.variables.getValueFromSource('opt:stage').should.be.fulfilled
+    it('should call getValueFromOptions if referencing an option', () => serverless.variables
+      .getValueFromSource('opt:stage').should.be.fulfilled
         .then((valueToPopulate) => {
-          expect(valueToPopulate).to.equal('variableValue');
+          expect(valueToPopulate).to.equal(variableValue);
           expect(getValueFromOptionsStub).to.have.been.called;
           expect(getValueFromOptionsStub).to.have.been.calledWith('opt:stage');
-        })
-        .finally(() => getValueFromOptionsStub.restore());
-    });
+        }));
 
-    it('should call getValueFromSelf if referencing from self', () => {
-      const getValueFromSelfStub = sinon.stub(serverless.variables, 'getValueFromSelf')
-        .resolves('variableValue');
-      return serverless.variables.getValueFromSource('self:provider').should.be.fulfilled
+    it('should call getValueFromSelf if referencing from self', () => serverless.variables
+      .getValueFromSource('self:provider').should.be.fulfilled
         .then((valueToPopulate) => {
-          expect(valueToPopulate).to.equal('variableValue');
+          expect(valueToPopulate).to.equal(variableValue);
           expect(getValueFromSelfStub).to.have.been.called;
           expect(getValueFromSelfStub).to.have.been.calledWith('self:provider');
-        })
-        .finally(() => getValueFromSelfStub.restore());
-    });
+        }));
 
-    it('should call getValueFromFile if referencing from another file', () => {
-      const getValueFromFileStub = sinon.stub(serverless.variables, 'getValueFromFile')
-        .resolves('variableValue');
-      return serverless.variables.getValueFromSource('file(./config.yml)').should.be.fulfilled
+    it('should call getValueFromFile if referencing from another file', () => serverless.variables
+      .getValueFromSource('file(./config.yml)').should.be.fulfilled
         .then((valueToPopulate) => {
-          expect(valueToPopulate).to.equal('variableValue');
+          expect(valueToPopulate).to.equal(variableValue);
           expect(getValueFromFileStub).to.have.been.called;
           expect(getValueFromFileStub).to.have.been.calledWith('file(./config.yml)');
-        })
-        .finally(() => getValueFromFileStub.restore());
-    });
+        }));
 
-    it('should call getValueFromCf if referencing CloudFormation Outputs', () => {
-      const getValueFromCfStub = sinon.stub(serverless.variables, 'getValueFromCf')
-        .resolves('variableValue');
-      return serverless.variables.getValueFromSource('cf:test-stack.testOutput').should.be.fulfilled
+    it('should call getValueFromCf if referencing CloudFormation Outputs', () => serverless
+      .variables.getValueFromSource('cf:test-stack.testOutput').should.be.fulfilled
         .then((valueToPopulate) => {
-          expect(valueToPopulate).to.equal('variableValue');
+          expect(valueToPopulate).to.equal(variableValue);
           expect(getValueFromCfStub).to.have.been.called;
           expect(getValueFromCfStub).to.have.been.calledWith('cf:test-stack.testOutput');
-        })
-        .finally(() => getValueFromCfStub.restore());
-    });
+        }));
 
-    it('should call getValueFromS3 if referencing variable in S3', () => {
-      const getValueFromS3Stub = sinon.stub(serverless.variables, 'getValueFromS3')
-        .resolves('variableValue');
-      return serverless.variables.getValueFromSource('s3:test-bucket/path/to/key')
+    it('should call getValueFromS3 if referencing variable in S3', () => serverless.variables
+      .getValueFromSource('s3:test-bucket/path/to/key')
         .should.be.fulfilled
         .then((valueToPopulate) => {
-          expect(valueToPopulate).to.equal('variableValue');
+          expect(valueToPopulate).to.equal(variableValue);
           expect(getValueFromS3Stub).to.have.been.called;
           expect(getValueFromS3Stub).to.have.been.calledWith('s3:test-bucket/path/to/key');
-        })
-        .finally(() => getValueFromS3Stub.restore());
-    });
+        }));
 
-    it('should call getValueFromSsm if referencing variable in SSM', () => {
-      const getValueFromSsmStub = sinon.stub(serverless.variables, 'getValueFromSsm')
-        .resolves('variableValue');
-      return serverless.variables.getValueFromSource('ssm:/test/path/to/param')
+    it('should call getValueFromSsm if referencing variable in SSM', () => serverless.variables
+      .getValueFromSource('ssm:/test/path/to/param')
         .should.be.fulfilled
         .then((valueToPopulate) => {
-          expect(valueToPopulate).to.equal('variableValue');
+          expect(valueToPopulate).to.equal(variableValue);
           expect(getValueFromSsmStub).to.have.been.called;
           expect(getValueFromSsmStub).to.have.been.calledWith('ssm:/test/path/to/param');
-        })
-        .finally(() => getValueFromSsmStub.restore());
-    });
+        }));
+
     it('should reject invalid sources', () =>
       serverless.variables.getValueFromSource('weird:source')
         .should.be.rejectedWith(serverless.classes.Error));
+
     describe('caching', () => {
       const sources = [
+        { function: 'getValueFromSls', variableString: 'sls:instanceId' },
         { function: 'getValueFromEnv', variableString: 'env:NODE_ENV' },
         { function: 'getValueFromOptions', variableString: 'opt:stage' },
         { function: 'getValueFromSelf', variableString: 'self:provider' },
@@ -1429,23 +1451,31 @@ module.exports = {
       ];
       sources.forEach((source) => {
         it(`should only call ${source.function} once, returning the cached value otherwise`, () => {
-          const value = 'variableValue';
-          const getValueFunctionStub = sinon.stub(serverless.variables, source.function)
-            .resolves(value);
+          const getValueFunctionStub = serverless.variables[source.function];
           return BbPromise.all([
-            serverless.variables.getValueFromSource(source.variableString).should.become(value),
+            serverless.variables.getValueFromSource(source.variableString)
+              .should.become(variableValue),
             BbPromise.delay(100).then(() =>
-              serverless.variables.getValueFromSource(source.variableString).should.become(value)),
+              serverless.variables.getValueFromSource(source.variableString)
+                .should.become(variableValue)),
           ]).then(() => {
             expect(getValueFunctionStub).to.have.been.calledOnce;
             expect(getValueFunctionStub).to.have.been.calledWith(source.variableString);
-          }).finally(() =>
-            getValueFunctionStub.restore());
+          });
         });
       });
     });
   });
 
+  describe('#getValueFromSls()', () => {
+    it('should get variable from Serverless Framework provided variables', () => {
+      serverless.instanceId = 12345678;
+      return serverless.variables.getValueFromSls('sls:instanceId').then((valueToPopulate) => {
+        expect(valueToPopulate).to.equal(12345678);
+      });
+    });
+  });
+
   describe('#getValueFromEnv()', () => {
     it('should get variable from environment variables', () => {
       process.env.TEST_VAR = 'someValue';

lib/plugins/aws/lib/naming.js

@@ -193,8 +193,8 @@ module.exports = {
     return `${this.getNormalizedWebsocketsRouteKey(route)}WebsocketsRoute`;
   },
 
-  getWebsocketsDeploymentLogicalId() {
-    return `WebsocketsDeployment${(new Date()).getTime().toString()}`;
+  getWebsocketsDeploymentLogicalId(id) {
+    return `WebsocketsDeployment${id}`;
   },
 
   getWebsocketsStageLogicalId() {
@@ -213,8 +213,8 @@ module.exports = {
     }
     return `${this.provider.getStage()}-${this.provider.serverless.service.service}`;
   },
-  generateApiGatewayDeploymentLogicalId() {
-    return `ApiGatewayDeployment${(new Date()).getTime().toString()}`;
+  generateApiGatewayDeploymentLogicalId(id) {
+    return `ApiGatewayDeployment${id}`;
   },
   getRestApiLogicalId() {
     return 'ApiGatewayRestApi';

lib/plugins/aws/lib/naming.test.js

@@ -283,8 +283,8 @@ describe('#naming()', () => {
 
   describe('#getWebsocketsDeploymentLogicalId()', () => {
     it('should return the websockets deployment logical id', () => {
-      expect(sdk.naming.getWebsocketsDeploymentLogicalId())
-        .to.match(/WebsocketsDeployment.+/);
+      expect(sdk.naming.getWebsocketsDeploymentLogicalId(1234))
+        .to.equal('WebsocketsDeployment1234');
     });
   });
 
@@ -318,10 +318,9 @@ describe('#naming()', () => {
   });
 
   describe('#generateApiGatewayDeploymentLogicalId()', () => {
-    it('should return ApiGatewayDeployment with a date based suffix', () => {
-      expect(sdk.naming.generateApiGatewayDeploymentLogicalId()
-        .match(/ApiGatewayDeployment(.*)/).length)
-        .to.be.greaterThan(1);
+    it('should return ApiGatewayDeployment with a suffix', () => {
+      expect(sdk.naming.generateApiGatewayDeploymentLogicalId(1234))
+        .to.equal('ApiGatewayDeployment1234');
     });
   });
 

lib/plugins/aws/package/compile/events/apiGateway/lib/deployment.js

@@ -6,7 +6,7 @@ const BbPromise = require('bluebird');
 module.exports = {
   compileDeployment() {
     this.apiGatewayDeploymentLogicalId = this.provider.naming
-      .generateApiGatewayDeploymentLogicalId();
+      .generateApiGatewayDeploymentLogicalId(this.serverless.instanceId);
 
     _.merge(this.serverless.service.provider.compiledCloudFormationTemplate.Resources, {
       [this.apiGatewayDeploymentLogicalId]: {