Merge pull request #122 from mfogel/feat/s3-templates

Feature: support for s3 request & response templates

Author: horike37

README.md

@@ -19,10 +19,12 @@ This Serverless Framework plugin supports the AWS service proxy integration feat
     - [Customizing responses](#customizing-responses)
   - [S3](#s3)
     - [Customizing request parameters](#customizing-request-parameters-1)
+    - [Customizing request templates](#customizing-request-templates)
     - [Customize the Path Override in API Gateway](#customize-the-path-override-in-api-gateway)
       - [Can use greedy, for deeper Folders](#can-use-greedy--for-deeper-folders)
-  - [SNS](#sns)
     - [Customizing responses](#customizing-responses-1)
+  - [SNS](#sns)
+    - [Customizing responses](#customizing-responses-2)
   - [DynamoDB](#dynamodb)
   - [EventBridge](#eventbridge)
 - [Common API Gateway features](#common-api-gateway-features)
@@ -293,6 +295,29 @@ custom:
           'integration.request.header.cache-control': "'public, max-age=31536000, immutable'"
 ```
 
+#### Customizing request templates
+
+If you'd like use custom [API Gateway request templates](https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-override-request-response-parameters.html), you can do so like so:
+
+```yml
+custom:
+  apiGatewayServiceProxies:
+    - s3:
+        path: /s3
+        method: get
+        action: GetObject
+        bucket:
+          Ref: S3Bucket
+        request:
+          template:
+            application/json: |
+              #set ($specialStuff = $context.request.header.x-special)
+              #set ($context.requestOverride.path.object = $specialStuff.replaceAll('_', '-'))
+              {}
+```
+
+Note that if the client does not provide a `Content-Type` header in the request, [ApiGateway defaults to `application/json`](https://docs.aws.amazon.com/apigateway/latest/developerguide/integration-passthrough-behaviors.html).
+
 #### Customize the Path Override in API Gateway
 
 Added the new customization parameter that lets the user set a custom Path Override in API Gateway other than the `{bucket}/{object}`
@@ -351,6 +376,33 @@ custom:
 
 This will translate for example `/s3/a/b/c` to `a/b/c.xml`
 
+#### Customizing responses
+
+You can get a simple customization of the responses by providing a template for the possible responses. The template is assumed to be `application/json`.
+
+```yml
+custom:
+  apiGatewayServiceProxies:
+    - s3:
+        path: /s3
+        method: post
+        action: PutObject
+        bucket:
+          Ref: S3Bucket
+        key: static-key.json
+        response:
+          template:
+            # `success` is used when the integration response is 200
+            success: |-
+              { "message: "accepted" }
+            # `clientError` is used when the integration response is 400
+            clientError: |-
+              { "message": "there is an error in your request" }
+            # `serverError` is used when the integration response is 500
+            serverError: |-
+              { "message": "there was an error handling your request" }
+```
+
 ### SNS
 
 Sample syntax for SNS proxy in `serverless.yml`.

lib/apiGateway/schema.js

@@ -256,15 +256,24 @@ const proxiesSchemas = {
         .valid('GetObject', 'PutObject', 'DeleteObject')
         .required(),
       bucket: stringOrRef.required(),
-      // don't accept a key when requestParameters has a 'integration.request.path.object' property
-      key: Joi.when('requestParameters', {
-        is: requestParameters
-          .keys({ 'integration.request.path.object': Joi.string().required() })
-          .required(),
-        then: Joi.forbidden(),
-        otherwise: key.required()
+      // key is
+      //   - optional when using a request mapping template
+      //   - forbidden if requestParameter has a 'integration.request.path.object' property
+      //   - otherwise required
+      key: Joi.when('request', {
+        is: request.required(),
+        then: key,
+        otherwise: Joi.when('requestParameters', {
+          is: requestParameters
+            .keys({ 'integration.request.path.object': Joi.string().required() })
+            .required(),
+          then: Joi.forbidden(),
+          otherwise: key.required()
+        })
       }),
-      requestParameters
+      requestParameters,
+      request,
+      response: extendedResponse
     })
   }),
   sns: Joi.object({

lib/apiGateway/validate.test.js

@@ -1331,6 +1331,20 @@ describe('#validateServiceProxies()', () => {
         'integration.request.header.cache-control': "'public, max-age=31536000, immutable'"
       })
     })
+
+    it('should not throw if request template is defined and key is not defined', () => {
+      shouldSucceed('request', { template: {} }, 'key')
+    })
+
+    it('should not throw if request template is defined and key is defined', () => {
+      shouldSucceed('request', { template: {} })
+    })
+
+    it('should not throw if response template is defined', () => {
+      shouldSucceed('response', { template: {} })
+      shouldSucceed('response', { template: { clientError: 'not empty' } })
+      shouldSucceed('response', { template: { success: 'a', clientError: 'b', serverError: 'c' } })
+    })
   })
 
   describe('sns', () => {

lib/package/s3/compileMethodsToS3.js

@@ -119,6 +119,11 @@ module.exports = {
     }
   },
 
+  getS3IntegrationResponseTemplate(http, statusType) {
+    const template = _.get(http, ['response', 'template', statusType])
+    return Object.assign({}, template && { 'application/json': template })
+  },
+
   getS3MethodIntegration(http) {
     const bucket = http.bucket
     const httpMethod = this.getIntegrationHttpMethod(http)
@@ -159,25 +164,32 @@ module.exports = {
       RequestParameters: _.merge(requestParams, http.requestParameters)
     }
 
+    const customRequestTemplates = _.get(http, ['request', 'template'])
+
+    if (!_.isEmpty(customRequestTemplates)) {
+      integration.PassthroughBehavior = 'NEVER'
+      integration.RequestTemplates = customRequestTemplates
+    }
+
     const integrationResponse = {
       IntegrationResponses: [
         {
           StatusCode: 400,
           SelectionPattern: '4\\d{2}',
           ResponseParameters: {},
-          ResponseTemplates: {}
+          ResponseTemplates: this.getS3IntegrationResponseTemplate(http, 'clientError')
         },
         {
           StatusCode: 500,
           SelectionPattern: '5\\d{2}',
           ResponseParameters: {},
-          ResponseTemplates: {}
+          ResponseTemplates: this.getS3IntegrationResponseTemplate(http, 'serverError')
         },
         {
           StatusCode: 200,
           SelectionPattern: '2\\d{2}',
           ResponseParameters: responseParams,
-          ResponseTemplates: {}
+          ResponseTemplates: this.getS3IntegrationResponseTemplate(http, 'success')
         }
       ]
     }