Add type configuration support to the typescript cli plugin (#67)

Author: duncangrant

.gitignore

@@ -139,3 +139,5 @@ tests/**/*.d.ts
 # Node.js
 node_modules/
 coverage/
+
+*.iml

.pre-commit-config.yaml

@@ -7,8 +7,8 @@ repos:
   - repo: https://github.com/ambv/black
     rev: stable
     hooks:
-    - id: black
-      # language_version: python3.6
+      - id: black
+        # language_version: python3.6
   - repo: https://github.com/pre-commit/pre-commit-hooks
     rev: v2.0.0
     hooks:

README.md

@@ -17,9 +17,9 @@ If you are using this package to build resource providers for CloudFormation, in
 
 **Prerequisites**
 
- - Python version 3.6 or above
- - [SAM CLI](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/serverless-sam-cli-install.html)
- - Your choice of TypeScript IDE
+- Python version 3.6 or above
+- [SAM CLI](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/serverless-sam-cli-install.html)
+- Your choice of TypeScript IDE
 
 **Installation**
 
@@ -75,6 +75,19 @@ pip3 install \
 
 That ensures neither is accidentally installed from PyPI.
 
+For changes to the typescript library "@amazon-web-services-cloudformation/cloudformation-cli-typescript-lib" pack up the compiled javascript:
+
+```shell
+npm run build
+npm pack
+```
+
+You can then install this in a cfn resource project using:
+
+```shell
+npm install ../path/to/cloudformation-cli-typescript-plugin/amazon-web-services-cloudformation-cloudformation-cli-typescript-lib-1.0.1.tgz
+```
+
 Linting and running unit tests is done via [pre-commit](https://pre-commit.com/), and so is performed automatically on commit after being installed (`pre-commit install`). The continuous integration also runs these checks. Manual options are available so you don't have to commit:
 
 ```shell

python/rpdk/typescript/codegen.py

@@ -161,13 +161,24 @@ def generate(self, project):
 
         models = resolve_models(project.schema)
 
+        if project.configuration_schema:
+            configuration_models = resolve_models(
+                project.configuration_schema, "TypeConfigurationModel"
+            )
+        else:
+            configuration_models = {"TypeConfigurationModel": {}}
+
+        models.update(configuration_models)
+
         path = self.package_root / "models.ts"
         LOG.debug("Writing file: %s", path)
         template = self.env.get_template("models.ts")
+
         contents = template.render(
             lib_name=SUPPORT_LIB_NAME,
             type_name=project.type_name,
             models=models,
+            contains_type_configuration=project.configuration_schema,
             primaryIdentifier=project.schema.get("primaryIdentifier", []),
             additionalIdentifiers=project.schema.get("additionalIdentifiers", []),
         )
@@ -176,6 +187,8 @@ def generate(self, project):
         LOG.debug("Generate complete")
 
     def _pre_package(self, build_path):
+        # Caller should own/delete this, not us.
+        # pylint: disable=consider-using-with
         f = TemporaryFile("w+b")
 
         # pylint: disable=unexpected-keyword-arg

python/rpdk/typescript/templates/handlers.ts

@@ -11,7 +11,7 @@ import {
     ResourceHandlerRequest,
     SessionProxy,
 } from '{{lib_name}}';
-import { ResourceModel } from './models';
+import { ResourceModel, TypeConfigurationModel } from './models';
 
 interface CallbackContext extends Record<string, any> {}
 
@@ -25,14 +25,17 @@ class Resource extends BaseResource<ResourceModel> {
      * @param request The request object for the provisioning request passed to the implementor
      * @param callbackContext Custom context object to allow the passing through of additional
      * state or metadata between subsequent retries
+     * @param typeConfiguration Configuration data for this resource type, in the given account
+     * and region
      * @param logger Logger to proxy requests to default publishers
      */
     @handlerEvent(Action.Create)
     public async create(
         session: Optional<SessionProxy>,
         request: ResourceHandlerRequest<ResourceModel>,
         callbackContext: CallbackContext,
-        logger: LoggerProxy
+        logger: LoggerProxy,
+        typeConfiguration: TypeConfigurationModel,
     ): Promise<ProgressEvent<ResourceModel, CallbackContext>> {
         const model = new ResourceModel(request.desiredResourceState);
         const progress = ProgressEvent.progress<ProgressEvent<ResourceModel, CallbackContext>>(model);
@@ -63,14 +66,17 @@ class Resource extends BaseResource<ResourceModel> {
      * @param request The request object for the provisioning request passed to the implementor
      * @param callbackContext Custom context object to allow the passing through of additional
      * state or metadata between subsequent retries
+     * @param typeConfiguration Configuration data for this resource type, in the given account
+     * and region
      * @param logger Logger to proxy requests to default publishers
      */
     @handlerEvent(Action.Update)
     public async update(
         session: Optional<SessionProxy>,
         request: ResourceHandlerRequest<ResourceModel>,
         callbackContext: CallbackContext,
-        logger: LoggerProxy
+        logger: LoggerProxy,
+        typeConfiguration: TypeConfigurationModel,
     ): Promise<ProgressEvent<ResourceModel, CallbackContext>> {
         const model = new ResourceModel(request.desiredResourceState);
         const progress = ProgressEvent.progress<ProgressEvent<ResourceModel, CallbackContext>>(model);
@@ -88,14 +94,17 @@ class Resource extends BaseResource<ResourceModel> {
      * @param request The request object for the provisioning request passed to the implementor
      * @param callbackContext Custom context object to allow the passing through of additional
      * state or metadata between subsequent retries
+     * @param typeConfiguration Configuration data for this resource type, in the given account
+     * and region
      * @param logger Logger to proxy requests to default publishers
      */
     @handlerEvent(Action.Delete)
     public async delete(
         session: Optional<SessionProxy>,
         request: ResourceHandlerRequest<ResourceModel>,
         callbackContext: CallbackContext,
-        logger: LoggerProxy
+        logger: LoggerProxy,
+        typeConfiguration: TypeConfigurationModel,
     ): Promise<ProgressEvent<ResourceModel, CallbackContext>> {
         const model = new ResourceModel(request.desiredResourceState);
         const progress = ProgressEvent.progress<ProgressEvent<ResourceModel, CallbackContext>>();
@@ -112,14 +121,17 @@ class Resource extends BaseResource<ResourceModel> {
      * @param request The request object for the provisioning request passed to the implementor
      * @param callbackContext Custom context object to allow the passing through of additional
      * state or metadata between subsequent retries
+     * @param typeConfiguration Configuration data for this resource type, in the given account
+     * and region
      * @param logger Logger to proxy requests to default publishers
      */
     @handlerEvent(Action.Read)
     public async read(
         session: Optional<SessionProxy>,
         request: ResourceHandlerRequest<ResourceModel>,
         callbackContext: CallbackContext,
-        logger: LoggerProxy
+        logger: LoggerProxy,
+        typeConfiguration: TypeConfigurationModel,
     ): Promise<ProgressEvent<ResourceModel, CallbackContext>> {
         const model = new ResourceModel(request.desiredResourceState);
         // TODO: put code here
@@ -135,14 +147,17 @@ class Resource extends BaseResource<ResourceModel> {
      * @param request The request object for the provisioning request passed to the implementor
      * @param callbackContext Custom context object to allow the passing through of additional
      * state or metadata between subsequent retries
+     * @param typeConfiguration Configuration data for this resource type, in the given account
+     * and region
      * @param logger Logger to proxy requests to default publishers
      */
     @handlerEvent(Action.List)
     public async list(
         session: Optional<SessionProxy>,
         request: ResourceHandlerRequest<ResourceModel>,
         callbackContext: CallbackContext,
-        logger: LoggerProxy
+        logger: LoggerProxy,
+        typeConfiguration: TypeConfigurationModel,
     ): Promise<ProgressEvent<ResourceModel, CallbackContext>> {
         const model = new ResourceModel(request.desiredResourceState);
         // TODO: put code here
@@ -154,7 +169,8 @@ class Resource extends BaseResource<ResourceModel> {
     }
 }
 
-export const resource = new Resource(ResourceModel.TYPE_NAME, ResourceModel);
+// @ts-ignore // if running against v1.0.1 or earlier of plugin the 5th argument is not known but best to ignored (runtime code may warn)
+export const resource = new Resource(ResourceModel.TYPE_NAME, ResourceModel, null, null, TypeConfigurationModel)!;
 
 // Entrypoint for production usage after registered in CloudFormation
 export const entrypoint = resource.entrypoint;

src/exceptions.ts

@@ -22,6 +22,15 @@ export class NotUpdatable extends BaseHandlerException {}
 
 export class InvalidRequest extends BaseHandlerException {}
 
+export class InvalidTypeConfiguration extends BaseHandlerException {
+    constructor(typeName: string, reason: string) {
+        super(
+            `Invalid TypeConfiguration provided for type '${typeName}'. Reason: ${reason}`,
+            HandlerErrorCode.InvalidTypeConfiguration
+        );
+    }
+}
+
 export class AccessDenied extends BaseHandlerException {}
 
 export class InvalidCredentials extends BaseHandlerException {}

src/interface.ts

@@ -160,6 +160,7 @@ export enum HandlerErrorCode {
     ServiceInternalError = 'ServiceInternalError',
     NetworkFailure = 'NetworkFailure',
     InternalFailure = 'InternalFailure',
+    InvalidTypeConfiguration = 'InvalidTypeConfiguration',
 }
 
 export interface Credentials {
@@ -261,6 +262,7 @@ export class RequestData<T = Dict> extends BaseDto {
     @Expose() providerCredentials?: Credentials;
     @Expose() previousResourceProperties?: T;
     @Expose() previousStackTags?: Dict<string>;
+    @Expose() typeConfiguration?: Dict<string>;
 }
 
 export class HandlerRequest<ResourceT = Dict, CallbackT = Dict> extends BaseDto {

src/resource.ts

@@ -2,7 +2,12 @@ import 'reflect-metadata';
 import { boundMethod } from 'autobind-decorator';
 
 import { AwsTaskWorkerPool, ProgressEvent, SessionProxy } from './proxy';
-import { BaseHandlerException, InternalFailure, InvalidRequest } from './exceptions';
+import {
+    BaseHandlerException,
+    InternalFailure,
+    InvalidRequest,
+    InvalidTypeConfiguration,
+} from './exceptions';
 import {
     Action,
     BaseModel,
@@ -40,14 +45,17 @@ const MUTATING_ACTIONS: [Action, Action, Action] = [
     Action.Delete,
 ];
 
-export type HandlerSignature<T extends BaseModel> = Callable<
-    [Optional<SessionProxy>, any, Dict, LoggerProxy],
+export type HandlerSignature<
+    T extends BaseModel,
+    TypeConfiguration extends BaseModel
+> = Callable<
+    [Optional<SessionProxy>, any, Dict, LoggerProxy, TypeConfiguration],
     Promise<ProgressEvent<T>>
 >;
-export class HandlerSignatures<T extends BaseModel> extends Map<
-    Action,
-    HandlerSignature<T>
-> {}
+export class HandlerSignatures<
+    T extends BaseModel,
+    TypeConfiguration extends BaseModel
+> extends Map<Action, HandlerSignature<T, TypeConfiguration>> {}
 class HandlerEvents extends Map<Action, string | symbol> {}
 
 /**
@@ -88,7 +96,10 @@ function ensureSerialize<T extends BaseModel>(toResponse = false): MethodDecorat
     };
 }
 
-export abstract class BaseResource<T extends BaseModel = BaseModel> {
+export abstract class BaseResource<
+    T extends BaseModel = BaseModel,
+    TypeConfiguration extends BaseModel = BaseModel
+> {
     protected loggerProxy: LoggerProxy;
     protected metricsPublisherProxy: MetricsPublisherProxy;
 
@@ -112,10 +123,13 @@ export abstract class BaseResource<T extends BaseModel = BaseModel> {
         public readonly typeName: string,
         public readonly modelTypeReference: Constructor<T>,
         protected readonly workerPool?: AwsTaskWorkerPool,
-        private handlers?: HandlerSignatures<T>
+        private handlers?: HandlerSignatures<T, TypeConfiguration>,
+        public readonly typeConfigurationTypeReference?: Constructor<TypeConfiguration> & {
+            deserialize: Function;
+        }
     ) {
         this.typeName = typeName || '';
-        this.handlers = handlers || new HandlerSignatures<T>();
+        this.handlers = handlers || new HandlerSignatures<T, TypeConfiguration>();
 
         this.lambdaLogger = console;
         this.platformLoggerProxy = new LoggerProxy();
@@ -294,8 +308,8 @@ export abstract class BaseResource<T extends BaseModel = BaseModel> {
 
     public addHandler = (
         action: Action,
-        f: HandlerSignature<T>
-    ): HandlerSignature<T> => {
+        f: HandlerSignature<T, TypeConfiguration>
+    ): HandlerSignature<T, TypeConfiguration> => {
         this.handlers.set(action, f);
         return f;
     };
@@ -304,13 +318,16 @@ export abstract class BaseResource<T extends BaseModel = BaseModel> {
         session: Optional<SessionProxy>,
         request: BaseResourceHandlerRequest<T>,
         action: Action,
-        callbackContext: Dict
+        callbackContext: Dict,
+        typeConfiguration?: TypeConfiguration
     ): Promise<ProgressEvent<T>> => {
         const actionName = action == null ? '<null>' : action.toString();
         if (!this.handlers.has(action)) {
             throw new Error(`Unknown action ${actionName}`);
         }
-        const handleRequest: HandlerSignature<T> = this.handlers.get(action);
+        const handleRequest: HandlerSignature<T, TypeConfiguration> = this.handlers.get(
+            action
+        );
         // We will make the callback context and resource states readonly
         // to avoid modification at a later time
         deepFreeze(callbackContext);
@@ -320,7 +337,8 @@ export abstract class BaseResource<T extends BaseModel = BaseModel> {
             session,
             request,
             callbackContext,
-            this.loggerProxy || this.platformLoggerProxy
+            this.loggerProxy || this.platformLoggerProxy,
+            typeConfiguration
         );
         this.log(`[${action}] handler invoked`);
         if (handlerResponse != null) {
@@ -473,6 +491,27 @@ export abstract class BaseResource<T extends BaseModel = BaseModel> {
         }
     };
 
+    private castTypeConfigurationRequest = (
+        request: HandlerRequest
+    ): TypeConfiguration => {
+        try {
+            if (!this.typeConfigurationTypeReference) {
+                if (request.requestData.typeConfiguration) {
+                    throw new InternalFailure(
+                        'Type configuration supplied but running with legacy version of code which does not support type configuration.'
+                    );
+                }
+                return null;
+            }
+            return this.typeConfigurationTypeReference.deserialize(
+                request.requestData.typeConfiguration
+            );
+        } catch (err) {
+            this.log('Invalid Type Configuration');
+            throw new InvalidTypeConfiguration(this.typeName, `${err} (${err.name}`);
+        }
+    };
+
     // @ts-ignore
     public async entrypoint(
         eventData: any | Dict,
@@ -500,6 +539,8 @@ export abstract class BaseResource<T extends BaseModel = BaseModel> {
             const [callerCredentials, providerCredentials] = credentials;
             const request = this.castResourceRequest(event);
 
+            const typeConfiguration = this.castTypeConfigurationRequest(event);
+
             let streamName = `${event.awsAccountId}-${event.region}`;
             if (event.stackId && request.logicalResourceIdentifier) {
                 streamName = `${event.stackId}/${request.logicalResourceIdentifier}`;
@@ -550,7 +591,8 @@ export abstract class BaseResource<T extends BaseModel = BaseModel> {
                     this.callerSession,
                     request,
                     action,
-                    callback
+                    callback,
+                    typeConfiguration
                 );
             } catch (err) {
                 error = err;