feat: allow CloudFormation overrides

- We keep having to add new options to the config when someone needs to use an option in the CloudFormation template we haven't mapped yet
- This should future proof the plugin to allow users to just pass whatever they need through to override the generated template
- Eventually we could also deprecate and remove some of the other options that could just be overrides
- Fixes #213

Author: Sean Dawson

README.md

@@ -60,6 +60,25 @@ functions:
               - dog
               - cat
 
+            # Overrides for generated CloudFormation templates
+            # Mirrors the CloudFormation docs but uses camel case instead of title case
+            #
+            # https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-sqs-queues.html
+            mainQueueOverride:
+              maximumMessageSize: 1024
+              ...
+            deadLetterQueueOverride:
+              maximumMessageSize: 1024
+              ...
+            # https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-lambda-eventsourcemapping.html
+            eventSourceMappingOverride:
+              sourceAccessConfigurations:
+                - Type: SASL_SCRAM_256_AUTH
+                  URI: arn:aws:secretsmanager:us-east-1:01234567890:secret:MyBrokerSecretName
+            # https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-sns-subscription.html
+            subscriptionOverride:
+              region: ap-southeast-2
+
 resources:
   Resources:
     Topic:
@@ -70,3 +89,26 @@ resources:
 plugins:
   - "@agiledigital/serverless-sns-sqs-lambda"
 ```
+
+### CloudFormation Overrides
+
+If you would like to override a part of the CloudFormation template
+that is generated by this plugin, you can pass raw CloudFormation
+to the override config options outlined above.
+
+The configuration must be provided with camel case keys,
+but apart from that, you can use the CloudFormation config
+as specified by AWS.
+
+For example, if you wanted to override the maximumMessageSize for the main queue
+you could find the "MaximumMessageSize" config option in the [AWS documentation](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-sqs-queues.html)
+make the key camel case ("maximumMessageSize") and pass it into the override section:
+
+```yaml
+    events:
+      - snsSqs:
+          name: Example
+          ...
+          mainQueueOverride:
+            maximumMessageSize: 1024
+````

agiledigital-serverless-sns-sqs-lambda-v0.4.0.tgz

@@ -28,6 +28,22 @@ functions:
               - dog
               - cat
 
+          # Overrides for generated CloudFormation templates
+          # Mirrors the CloudFormation docs but uses camel case instead of title case
+          #
+          #
+          # https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-sqs-queues.html
+          mainQueueOverride:
+            maximumMessageSize: 1024
+          deadLetterQueueOverride:
+            maximumMessageSize: 2048
+          # https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-lambda-eventsourcemapping.html
+          eventSourceMappingOverride:
+            enabled: false
+          # https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-sns-subscription.html
+          subscriptionOverride:
+            rawMessageDelivery: true
+
 resources:
   Resources:
     Topic:

example-service/serverless.yml

@@ -2,6 +2,8 @@
 /* eslint-disable @typescript-eslint/explicit-module-boundary-types */
 /* eslint-disable @typescript-eslint/no-explicit-any */
 
+import { JsonObject } from "type-fest";
+
 /**
  * Defines the structure of the config object
  * that is passed to the main functions to
@@ -22,6 +24,11 @@ type Config = {
   visibilityTimeout: number;
   rawMessageDelivery: boolean;
   filterPolicy: any;
+
+  mainQueueOverride: JsonObject,
+  deadLetterQueueOverride: JsonObject,
+  eventSourceMappingOverride: JsonObject,
+  subscriptionOverride: JsonObject,
 };
 
 /**
@@ -47,9 +54,16 @@ const parseIntOr = (intString, defaultInt) => {
  *
  * @param {string} camelCase camelCase string
  */
-const pascalCase = camelCase =>
+const pascalCase = (camelCase: string): string =>
   camelCase.slice(0, 1).toUpperCase() + camelCase.slice(1);
 
+
+const pascalCaseAllKeys = (jsonObject: JsonObject): JsonObject =>
+  Object.keys(jsonObject).reduce((acc, key) => ({
+    ...acc,
+    [pascalCase(key)]: jsonObject[key]
+  }), {})
+
 /**
  * The ServerlessSnsSqsLambda plugin looks for functions that contain an
  * `snsSqs` event and adds the necessary resources for the Lambda to subscribe
@@ -200,6 +214,25 @@ Usage
               pet:
                 - dog
                 - cat
+
+            # Overrides for generated CloudFormation templates
+            # Mirrors the CloudFormation docs but uses camel case instead of title case
+            #
+            #
+            # https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-sqs-queues.html
+            mainQueueOverride:
+              maximumMessageSize: 1024
+              ...
+            deadLetterQueueOverride:
+              maximumMessageSize: 1024
+              ...
+            # https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-lambda-eventsourcemapping.html
+            eventSourceMappingOverride:
+              bisectBatchOnFunctionError: true
+            # https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-sns-subscription.html
+            subscriptionOverride:
+              rawMessageDelivery: true
+
 `);
     }
 
@@ -221,7 +254,11 @@ Usage
       rawMessageDelivery:
         config.rawMessageDelivery !== undefined
           ? config.rawMessageDelivery
-          : false
+          : false,
+      mainQueueOverride: config.mainQueueOverride ?? {},
+      deadLetterQueueOverride: config.deadLetterQueueOverride ?? {},
+      eventSourceMappingOverride: config.eventSourceMappingOverride ?? {},
+      subscriptionOverride: config.subscriptionOverride ?? {},
     };
   }
 
@@ -235,7 +272,7 @@ Usage
    */
   addEventSourceMapping(
     template,
-    { funcName, name, batchSize, maximumBatchingWindowInSeconds, enabled }: Config
+    { funcName, name, batchSize, maximumBatchingWindowInSeconds, enabled, eventSourceMappingOverride }: Config
   ) {
     const enabledWithDefault = enabled !== undefined ? enabled : true;
     template.Resources[`${funcName}EventSourceMappingSQS${name}Queue`] = {
@@ -246,7 +283,8 @@ Usage
         MaximumBatchingWindowInSeconds: maximumBatchingWindowInSeconds !== undefined ? maximumBatchingWindowInSeconds : 0,
         EventSourceArn: { "Fn::GetAtt": [`${name}Queue`, "Arn"] },
         FunctionName: { "Fn::GetAtt": [`${funcName}LambdaFunction`, "Arn"] },
-        Enabled: enabledWithDefault ? "True" : "False"
+        Enabled: enabledWithDefault ? "True" : "False",
+        ...pascalCaseAllKeys(eventSourceMappingOverride)
       }
     };
   }
@@ -266,7 +304,8 @@ Usage
       prefix,
       kmsMasterKeyId,
       kmsDataKeyReusePeriodSeconds,
-      deadLetterMessageRetentionPeriodSeconds
+      deadLetterMessageRetentionPeriodSeconds,
+      deadLetterQueueOverride
     }
   ) {
     template.Resources[`${name}DeadLetterQueue`] = {
@@ -287,7 +326,8 @@ Usage
           ? {
               MessageRetentionPeriod: deadLetterMessageRetentionPeriodSeconds
             }
-          : {})
+          : {}),
+        ...pascalCaseAllKeys(deadLetterQueueOverride)
       }
     };
   }
@@ -308,7 +348,8 @@ Usage
       maxRetryCount,
       kmsMasterKeyId,
       kmsDataKeyReusePeriodSeconds,
-      visibilityTimeout
+      visibilityTimeout,
+      mainQueueOverride
     }: Config
   ) {
     template.Resources[`${name}Queue`] = {
@@ -335,7 +376,8 @@ Usage
           ? {
               VisibilityTimeout: visibilityTimeout
             }
-          : {})
+          : {}),
+        ...pascalCaseAllKeys(mainQueueOverride)
       }
     };
   }
@@ -379,7 +421,7 @@ Usage
    */
   addTopicSubscription(
     template,
-    { name, topicArn, filterPolicy, rawMessageDelivery }: Config
+    { name, topicArn, filterPolicy, rawMessageDelivery, subscriptionOverride}: Config
   ) {
     template.Resources[`Subscribe${name}Topic`] = {
       Type: "AWS::SNS::Subscription",
@@ -392,7 +434,8 @@ Usage
           ? {
               RawMessageDelivery: rawMessageDelivery
             }
-          : {})
+          : {}),
+        ...pascalCaseAllKeys(subscriptionOverride)
       }
     };
   }

lib/serverless-sns-sqs-lambda.ts

@@ -40,6 +40,7 @@
     "serverless": "^2.19.0",
     "ts-jest": "^26.4.3",
     "type-coverage": "^2.14.0",
+    "type-fest": "^1.0.2",
     "typescript": "^4.0.5"
   },
   "peerDependencies": {

package.json

@@ -10255,6 +10255,11 @@ type-fest@^0.8.1:
   resolved "https://registry.yarnpkg.com/type-fest/-/type-fest-0.8.1.tgz#09e249ebde851d3b1e48d27c105444667f17b83d"
   integrity sha512-4dbzIzqvjtgiM5rw1k5rEHtBANKmdudhGyBEajN01fEyhaAIhsoKNy6y7+IN93IfpFtwY9iqi7kD+xwKhQsNJA==
 
+type-fest@^1.0.2:
+  version "1.0.2"
+  resolved "https://registry.yarnpkg.com/type-fest/-/type-fest-1.0.2.tgz#3f9c39982859f385c77c38b7e5f1432b8a3661c6"
+  integrity sha512-a720oz3Kjbp3ll0zkeN9qjRhO7I34MKMhPGQiQJAmaZQZQ1lo+NWThK322f7sXV+kTg9B1Ybt16KgBXWgteT8w==
+
 type@^1.0.1:
   version "1.2.0"
   resolved "https://registry.yarnpkg.com/type/-/type-1.2.0.tgz#848dd7698dafa3e54a6c479e759c4bc3f18847a0"