refactor: convert "import" to "from" methods (#2456)

Implement and apply the following awslint rules:

- `awslint:from-method`: resources should have at least one static "from" method
- `awslint:from-signature`: enforce method signature
- `awslint:from-attributes`: a `fromAttributes` static method can be used to import from more than a single attribute
- `awslint:from-attributes-struct`: `fromFooAttributes` should accept a `FooAttributes` struct as input
- `awslint:no-static-import`: forbids a static `import` (deprecation helper rule)
- `awslint:attribute-tag`: all resource attributes should have an "@Attribute" doc tag
- `awslint:attribute-readonly`: all attributes must be readonly properties

Many resources now have an additional `fromFooArn` or `fromFooName` for importing from the intrinsic attribute.

Misc:
- Deprecate `Token.unresolved` in favor of `Token.isToken` (more idiomatic).
- Added eager resolution of `Fn.select` and `Fn.split` in case they receive concrete values
- Refactoring of awslint (decouple "resource" from "cfn-resource").
- Added `iam.Grant.drop` which allows "dropping" a grant on the floor for imported resources

NOTE: many of the new methods do not have inline documentation. We will address this in a subsequent pass that will be focused on docs.

Fixes #2450 
Fixes #2428 
Fixes #2424
Fixes #2429 
Fixes #2425
Fixes #2422
Fixes #2423
Fixes #89

BREAKING CHANGE: all `Foo.import` static methods are now `Foo.fromFooAttributes`
* All `FooImportProps` structs are now called `FooAttributes`
* `stepfunctions.StateMachine.export` has been removed.
* `ses.ReceiptRule.name` is now `ses.ReceiptRule.receiptRuleName`
* `ses.ReceiptRuleSet.name` is now `ses.ReceiptRuleSet.receiptRuleSetName`
* `secretsmanager.AttachedSecret` is now called `secretsmanager.SecretTargetAttachment` to match service semantics
* `ecr.Repository.export` has been removed
* `s3.Bucket.bucketUrl` is now called `s3.Bucket.bucketWebsiteUrl`
* `lambda.Version.functionVersion` is now called `lambda.Version.version`
* `ec2.SecurityGroup.groupName` is now `ec2.SecurityGroup.securityGroupName`
* `cognito.UserPoolClient.clientId` is now `cognito.UserPoolClient.userPoolClientId`
* `apigateway.IRestApiResource` is now `apigateway.IResource`
* `apigateway.IResource.resourcePath` is now `apigateway.IResource.path`
* `apigateway.IResource.resourceApi` is now `apigateway.IResource.restApi`

Author: Elad Ben-Israel

packages/@aws-cdk/app-delivery/test/test.pipeline-deploy-stack-action.ts

@@ -327,7 +327,7 @@ function createSelfUpdatingStack(pipelineStack: cdk.Stack): SelfUpdatingPipeline
   });
 
   // simple source
-  const bucket = s3.Bucket.import( pipeline, 'PatternBucket', { bucketArn: 'arn:aws:s3:::totally-fake-bucket' });
+  const bucket = s3.Bucket.fromBucketArn( pipeline, 'PatternBucket', 'arn:aws:s3:::totally-fake-bucket');
   const sourceOutput = new codepipeline.Artifact('SourceOutput');
   const sourceAction = new cpactions.S3SourceAction({
     actionName: 'S3Source',

packages/@aws-cdk/assets/lib/asset.ts

@@ -122,9 +122,7 @@ export class Asset extends cdk.Construct {
     const s3Filename = cdk.Fn.select(1, cdk.Fn.split(cxapi.ASSET_PREFIX_SEPARATOR, keyParam.stringValue)).toString();
     this.s3ObjectKey = `${this.s3Prefix}${s3Filename}`;
 
-    this.bucket = s3.Bucket.import(this, 'AssetBucket', {
-      bucketName: this.s3BucketName
-    });
+    this.bucket = s3.Bucket.fromBucketName(this, 'AssetBucket', this.s3BucketName);
 
     // form the s3 URL of the object key
     this.s3Url = this.bucket.urlForObject(this.s3ObjectKey);

packages/@aws-cdk/aws-apigateway/lib/deployment.ts

@@ -55,6 +55,7 @@ export interface DeploymentProps  {
  * automatically for the `restApi.latestDeployment` deployment.
  */
 export class Deployment extends Resource {
+  /** @attribute */
   public readonly deploymentId: string;
   public readonly api: IRestApi;
 

packages/@aws-cdk/aws-apigateway/lib/integrations/lambda.ts

@@ -55,7 +55,7 @@ export class LambdaIntegration extends AwsIntegration {
     super.bind(method);
     const principal = new iam.ServicePrincipal('apigateway.amazonaws.com');
 
-    const desc = `${method.httpMethod}.${method.resource.resourcePath.replace(/\//g, '.')}`;
+    const desc = `${method.httpMethod}.${method.resource.path.replace(/\//g, '.')}`;
 
     this.handler.addPermission(`ApiPermission.${desc}`, {
       principal,

packages/@aws-cdk/aws-apigateway/lib/method.ts

@@ -3,7 +3,7 @@ import { CfnMethod, CfnMethodProps } from './apigateway.generated';
 import { ConnectionType, Integration } from './integration';
 import { MockIntegration } from './integrations/mock';
 import { MethodResponse } from './methodresponse';
-import { IRestApiResource } from './resource';
+import { IResource } from './resource';
 import { RestApi } from './restapi';
 import { validateHttpMethod } from './util';
 
@@ -66,7 +66,7 @@ export interface MethodProps {
    * The resource this method is associated with. For root resource methods,
    * specify the `RestApi` object.
    */
-  readonly resource: IRestApiResource;
+  readonly resource: IResource;
 
   /**
    * The HTTP method ("GET", "POST", "PUT", ...) that clients use to call this method.
@@ -85,16 +85,18 @@ export interface MethodProps {
 }
 
 export class Method extends Resource {
+  /** @attribute */
   public readonly methodId: string;
+
   public readonly httpMethod: string;
-  public readonly resource: IRestApiResource;
+  public readonly resource: IResource;
   public readonly restApi: RestApi;
 
   constructor(scope: Construct, id: string, props: MethodProps) {
     super(scope, id);
 
     this.resource = props.resource;
-    this.restApi = props.resource.resourceApi;
+    this.restApi = props.resource.restApi;
     this.httpMethod = props.httpMethod.toUpperCase();
 
     validateHttpMethod(this.httpMethod);
@@ -120,9 +122,9 @@ export class Method extends Resource {
 
     this.methodId = resource.ref;
 
-    props.resource.resourceApi._attachMethod(this);
+    props.resource.restApi._attachMethod(this);
 
-    const deployment = props.resource.resourceApi.latestDeployment;
+    const deployment = props.resource.restApi.latestDeployment;
     if (deployment) {
       deployment.node.addDependency(resource);
       deployment.addToLogicalId({ method: methodProps });
@@ -136,6 +138,8 @@ export class Method extends Resource {
    *
    * NOTE: {stage} will refer to the `restApi.deploymentStage`, which will
    * automatically set if auto-deploy is enabled.
+   *
+   * @attribute
    */
   public get methodArn(): string {
     if (!this.restApi.deploymentStage) {
@@ -145,15 +149,15 @@ export class Method extends Resource {
     }
 
     const stage = this.restApi.deploymentStage.stageName.toString();
-    return this.restApi.executeApiArn(this.httpMethod, this.resource.resourcePath, stage);
+    return this.restApi.executeApiArn(this.httpMethod, this.resource.path, stage);
   }
 
   /**
    * Returns an execute-api ARN for this method's "test-invoke-stage" stage.
    * This stage is used by the AWS Console UI when testing the method.
    */
   public get testMethodArn(): string {
-    return this.restApi.executeApiArn(this.httpMethod, this.resource.resourcePath, 'test-invoke-stage');
+    return this.restApi.executeApiArn(this.httpMethod, this.resource.path, 'test-invoke-stage');
   }
 
   private renderIntegration(integration?: Integration): CfnMethod.IntegrationProperty {

packages/@aws-cdk/aws-apigateway/lib/resource.ts

@@ -1,14 +1,14 @@
-import { Construct, IResource, Resource as ResourceConstruct } from '@aws-cdk/cdk';
+import { Construct, IResource as IResourceBase, Resource as ResourceConstruct } from '@aws-cdk/cdk';
 import { CfnResource, CfnResourceProps } from './apigateway.generated';
 import { Integration } from './integration';
 import { Method, MethodOptions } from './method';
 import { RestApi } from './restapi';
 
-export interface IRestApiResource extends IResource {
+export interface IResource extends IResourceBase {
   /**
    * The parent of this resource or undefined for the root resource.
    */
-  readonly parentResource?: IRestApiResource;
+  readonly parentResource?: IResource;
 
   /**
    * The rest API that this resource is part of.
@@ -18,17 +18,18 @@ export interface IRestApiResource extends IResource {
    * hash to determine the ID of the deployment. This allows us to automatically update
    * the deployment when the model of the REST API changes.
    */
-  readonly resourceApi: RestApi;
+  readonly restApi: RestApi;
 
   /**
    * The ID of the resource.
+   * @attribute
    */
   readonly resourceId: string;
 
   /**
    * The full path of this resuorce.
    */
-  readonly resourcePath: string;
+  readonly path: string;
 
   /**
    * An integration to use as a default for all methods created within this
@@ -67,7 +68,7 @@ export interface IRestApiResource extends IResource {
    * @param pathPart The path part of the child resource
    * @returns the child resource or undefined if not found
    */
-  getResource(pathPart: string): IRestApiResource | undefined;
+  getResource(pathPart: string): IResource | undefined;
 
   /**
    * Adds a greedy proxy resource ("{proxy+}") and an ANY method to this route.
@@ -105,19 +106,19 @@ export interface ResourceProps extends ResourceOptions {
    * The parent resource of this resource. You can either pass another
    * `Resource` object or a `RestApi` object here.
    */
-  readonly parent: IRestApiResource;
+  readonly parent: IResource;
 
   /**
    * A path name for the resource.
    */
   readonly pathPart: string;
 }
 
-export abstract class ResourceBase extends ResourceConstruct implements IRestApiResource {
-  public abstract readonly parentResource?: IRestApiResource;
-  public abstract readonly resourceApi: RestApi;
+export abstract class ResourceBase extends ResourceConstruct implements IResource {
+  public abstract readonly parentResource?: IResource;
+  public abstract readonly restApi: RestApi;
   public abstract readonly resourceId: string;
-  public abstract readonly resourcePath: string;
+  public abstract readonly path: string;
   public abstract readonly defaultIntegration?: Integration;
   public abstract readonly defaultMethodOptions?: MethodOptions;
 
@@ -139,7 +140,7 @@ export abstract class ResourceBase extends ResourceConstruct implements IRestApi
     return new ProxyResource(this, '{proxy+}', { parent: this, ...options });
   }
 
-  public getResource(pathPart: string): IRestApiResource | undefined {
+  public getResource(pathPart: string): IResource | undefined {
     return this.children[pathPart];
   }
 
@@ -153,8 +154,8 @@ export abstract class ResourceBase extends ResourceConstruct implements IRestApi
     }
 
     if (path.startsWith('/')) {
-      if (this.resourcePath !== '/') {
-        throw new Error(`Path may start with "/" only for the resource, but we are at: ${this.resourcePath}`);
+      if (this.path !== '/') {
+        throw new Error(`Path may start with "/" only for the resource, but we are at: ${this.path}`);
       }
 
       // trim trailing "/"
@@ -177,10 +178,11 @@ export abstract class ResourceBase extends ResourceConstruct implements IRestApi
 }
 
 export class Resource extends ResourceBase {
-  public readonly parentResource?: IRestApiResource;
-  public readonly resourceApi: RestApi;
+  public readonly parentResource?: IResource;
+  public readonly restApi: RestApi;
   public readonly resourceId: string;
-  public readonly resourcePath: string;
+  public readonly path: string;
+
   public readonly defaultIntegration?: Integration;
   public readonly defaultMethodOptions?: MethodOptions;
 
@@ -196,21 +198,21 @@ export class Resource extends ResourceBase {
     }
 
     const resourceProps: CfnResourceProps = {
-      restApiId: props.parent.resourceApi.restApiId,
+      restApiId: props.parent.restApi.restApiId,
       parentId: props.parent.resourceId,
       pathPart: props.pathPart
     };
     const resource = new CfnResource(this, 'Resource', resourceProps);
 
     this.resourceId = resource.resourceId;
-    this.resourceApi = props.parent.resourceApi;
+    this.restApi = props.parent.restApi;
 
     // render resource path (special case for root)
-    this.resourcePath = props.parent.resourcePath;
-    if (!this.resourcePath.endsWith('/')) { this.resourcePath += '/'; }
-    this.resourcePath += props.pathPart;
+    this.path = props.parent.path;
+    if (!this.path.endsWith('/')) { this.path += '/'; }
+    this.path += props.pathPart;
 
-    const deployment = props.parent.resourceApi.latestDeployment;
+    const deployment = props.parent.restApi.latestDeployment;
     if (deployment) {
       deployment.node.addDependency(resource);
       deployment.addToLogicalId({ resource: resourceProps });
@@ -231,7 +233,7 @@ export interface ProxyResourceProps extends ResourceOptions {
    * The parent resource of this resource. You can either pass another
    * `Resource` object or a `RestApi` object here.
    */
-  readonly parent: IRestApiResource;
+  readonly parent: IResource;
 
   /**
    * Adds an "ANY" method to this resource. If set to `false`, you will have to explicitly
@@ -270,7 +272,7 @@ export class ProxyResource extends Resource {
   public addMethod(httpMethod: string, integration?: Integration, options?: MethodOptions): Method {
     // In case this proxy is mounted under the root, also add this method to
     // the root so that empty paths are proxied as well.
-    if (this.parentResource && this.parentResource.resourcePath === '/') {
+    if (this.parentResource && this.parentResource.path === '/') {
       this.parentResource.addMethod(httpMethod);
     }
     return super.addMethod(httpMethod, integration, options);

packages/@aws-cdk/aws-apigateway/lib/restapi.ts

@@ -1,13 +1,13 @@
 import iam = require('@aws-cdk/aws-iam');
-import { CfnOutput, Construct, IResource, Resource } from '@aws-cdk/cdk';
+import { CfnOutput, Construct, IResource as IResourceBase, Resource } from '@aws-cdk/cdk';
 import { CfnAccount, CfnRestApi } from './apigateway.generated';
 import { Deployment } from './deployment';
 import { Integration } from './integration';
 import { Method, MethodOptions } from './method';
-import { IRestApiResource, ResourceBase, ResourceOptions } from './resource';
+import { IResource, ResourceBase, ResourceOptions } from './resource';
 import { Stage, StageOptions } from './stage';
 
-export interface RestApiImportProps {
+export interface RestApiAttributes {
   /**
    * The REST API ID of an existing REST API resource.
    */
@@ -19,22 +19,18 @@ export interface RestApiImportProps {
   readonly restApiRootResourceId?: string;
 }
 
-export interface IRestApi extends IResource {
+export interface IRestApi extends IResourceBase {
   /**
    * The ID of this API Gateway RestApi.
+   * @attribute
    */
   readonly restApiId: string;
 
-  /**
-   * The resource ID of the root resource.
-   */
-  readonly restApiRootResourceId: string;
-
   /**
    * Exports a REST API resource from this stack.
    * @returns REST API props that can be imported to another stack.
    */
-  export(): RestApiImportProps;
+  export(): RestApiAttributes;
 }
 
 export interface RestApiProps extends ResourceOptions {
@@ -165,20 +161,11 @@ export interface RestApiProps extends ResourceOptions {
  * public endpoint.
  */
 export class RestApi extends Resource implements IRestApi {
-  /**
-   * Imports an existing REST API resource.
-   * @param scope Parent construct
-   * @param id Construct ID
-   * @param props Imported rest API properties
-   */
-  public static import(scope: Construct, id: string, props: RestApiImportProps): IRestApi {
-    class Import extends Construct implements IRestApi {
-      public restApiId = props.restApiId;
-      public get restApiRootResourceId() {
-        if (!props.restApiRootResourceId) { throw new Error(`Imported REST API does not have "restApiRootResourceId"`); }
-        return props.restApiRootResourceId;
-      }
-      public export() { return props; }
+
+  public static fromRestApiId(scope: Construct, id: string, restApiId: string): IRestApi {
+    class Import extends Resource implements IRestApi {
+      public readonly restApiId = restApiId;
+      public export(): RestApiAttributes { return { restApiId }; }
     }
 
     return new Import(scope, id);
@@ -191,6 +178,8 @@ export class RestApi extends Resource implements IRestApi {
 
   /**
    * The resource ID of the root resource.
+   *
+   * @attribute
    */
   public readonly restApiRootResourceId: string;
 
@@ -216,7 +205,7 @@ export class RestApi extends Resource implements IRestApi {
    *    api.root.addResource('friends').addMethod('GET', getFriendsHandler); // "GET /friends"
    *
    */
-  public readonly root: IRestApiResource;
+  public readonly root: IResource;
 
   private readonly methods = new Array<Method>();
 
@@ -252,7 +241,7 @@ export class RestApi extends Resource implements IRestApi {
    * Exports a REST API resource from this stack.
    * @returns REST API props that can be imported to another stack.
    */
-  public export(): RestApiImportProps {
+  public export(): RestApiAttributes {
     return {
       restApiId: new CfnOutput(this, 'RestApiId', { value: this.restApiId }).makeImportValue().toString()
     };
@@ -402,10 +391,10 @@ export enum EndpointType {
 }
 
 class RootResource extends ResourceBase {
-  public readonly parentResource?: IRestApiResource;
-  public readonly resourceApi: RestApi;
+  public readonly parentResource?: IResource;
+  public readonly restApi: RestApi;
   public readonly resourceId: string;
-  public readonly resourcePath: string;
+  public readonly path: string;
   public readonly defaultIntegration?: Integration | undefined;
   public readonly defaultMethodOptions?: MethodOptions | undefined;
 
@@ -415,8 +404,8 @@ class RootResource extends ResourceBase {
     this.parentResource = undefined;
     this.defaultIntegration = props.defaultIntegration;
     this.defaultMethodOptions = props.defaultMethodOptions;
-    this.resourceApi = api;
+    this.restApi = api;
     this.resourceId = resourceId;
-    this.resourcePath = '/';
+    this.path = '/';
   }
 }

packages/@aws-cdk/aws-apigateway/lib/stage.ts

@@ -133,6 +133,9 @@ export interface MethodDeploymentOptions {
 }
 
 export class Stage extends Resource {
+  /**
+   * @attribute
+   */
   public readonly stageName: string;
 
   private readonly restApi: IRestApi;