feat(plugin): update handling of api gateway timeouts in serverless config

Author: vavasilva

README.md

@@ -1,16 +1,16 @@
 # Serverless API Gateway Integration Timeout
 
-A Serverless Framework plugin to modify the API Gateway integration timeout based on your AWS account's service quota.
+A lightweight Serverless Framework plugin that adds support for setting API Gateway integration timeouts directly in HTTP events.
 
 ## Problem
 
-By default, Amazon API Gateway has an integration timeout limit of 29 seconds (29,000 milliseconds). This can be too short for more complex or resource-intensive operations, especially for Generative AI workloads with Large Language Models (LLMs).
+By default, Amazon API Gateway has an integration timeout limit of 29 seconds (29,000 milliseconds). This can be too short for more complex or resource-intensive operations.
 
-As [announced in June 2024](https://aws.amazon.com/about-aws/whats-new/2024/06/amazon-api-gateway-integration-timeout-limit-29-seconds/), AWS now allows integration timeouts beyond 29 seconds for Regional and Private REST APIs, making it possible to support longer-running backend operations.
+While Lambda functions can have longer timeout values (up to 15 minutes), API Gateway will terminate the request if it exceeds its integration timeout. The Serverless Framework doesn't natively support setting this timeout directly in HTTP event definitions.
 
 ## Solution
 
-This plugin automatically updates the API Gateway integration timeout after deployment, allowing you to set integration timeout values for your API Gateway based on your account's service quota.
+This plugin extends the Serverless Framework's HTTP event schema to include a `timeout` property. It intercepts the API Gateway CloudFormation template generation to add the `TimeoutInMillis` property to your integrations.
 
 ## Installation
 
@@ -24,29 +24,35 @@ serverless plugin install -n serverless-api-gateway-integration-timeout
 
 ## Usage
 
-Add the plugin to your `serverless.yml` file:
+1. Add the plugin to your `serverless.yml` file:
 
 ```yaml
 plugins:
   - serverless-api-gateway-integration-timeout
 ```
 
-Configure the timeout in the custom section of your `serverless.yml`:
+2. Set the timeout directly in your HTTP events:
 
 ```yaml
-custom:
-  apiGatewayIntegrationTimeout: 60000  # Desired timeout in milliseconds
-  apiGatewayMaxTimeout: 60000  # Maximum timeout allowed by your AWS account's service quota
+functions:
+  myFunction:
+    handler: handler.myFunction
+    timeout: 60  # Lambda timeout in seconds
+    events:
+      - http:
+          path: /my-path
+          method: get
+          timeout: 60  # API Gateway timeout in seconds (converted to milliseconds)
 ```
 
-You can also set just the Lambda timeout in the provider section, and the plugin will automatically use that value (converted to milliseconds):
-
-```yaml
-provider:
-  timeout: 60  # Lambda timeout in seconds - will be used as 60000ms for API Gateway
-```
+## Important Notes
 
-If no timeout is specified, the plugin will default to a timeout of 29,000 milliseconds (29 seconds).
+- The `timeout` value in HTTP events is in **seconds**. It will be automatically converted to milliseconds.
+- The maximum allowed timeout depends on your AWS account's service quota limit
+  - Standard limit: 29 seconds (29,000 milliseconds)
+  - Extended limit: May be increased up to 60 or 120 seconds, depending on your account
+- The plugin works with these integration types: `AWS`, `AWS_PROXY`, and `LAMBDA`
+- The plugin modifies the CloudFormation template during deployment, so it only works with `serverless deploy`
 
 ## Service Quota and Maximum Timeout
 
@@ -60,67 +66,15 @@ To increase your service quota:
 2. Navigate to API Gateway service
 3. Request an increase for the "Integration timeout" quota
 
-## Configuration Options
-
-| Option | Description | Default |
-|--------|-------------|---------|
-| `apiGatewayIntegrationTimeout` | The desired timeout in milliseconds | 29000 or provider.timeout * 1000 |
-| `apiGatewayMaxTimeout` | The maximum timeout allowed by your AWS account's service quota | 29000 |
-| `apiGatewayId` | Optional: Manually specify your API Gateway ID | - |
-
-## Timeout Order of Precedence
-
-The plugin determines the timeout value to set in the following order:
-
-1. `custom.apiGatewayIntegrationTimeout` if defined
-2. `provider.timeout` * 1000 (converting from seconds to milliseconds) if defined
-3. Default value of 29000ms if neither of the above is defined
-
-## Troubleshooting
-
-### Error: Timeout should be between 50 ms and 60000 ms
-
-This error occurs when your requested timeout exceeds your account's service quota. To resolve this:
-
-1. Check your current service quota in the AWS console
-2. Set the `apiGatewayMaxTimeout` parameter to match your account's limit:
-
-```yaml
-custom:
-  apiGatewayIntegrationTimeout: 60000  # Your desired timeout
-  apiGatewayMaxTimeout: 60000  # Set to your account's maximum limit
-```
-
-The plugin will automatically adjust your timeout if it exceeds the maximum value.
+## How It Works
 
-### Error: Could not find REST API ID
+The plugin works by:
 
-If you encounter the error `Could not find REST API ID in CloudFormation stack outputs`, this usually happens when:
+1. Extending the Serverless Framework's HTTP event schema to include a `timeout` property
+2. Finding the API Gateway compiler plugin instance
+3. Monkey-patching the `getMethodIntegration` method to include the `TimeoutInMillis` property when generating the CloudFormation template
 
-1. You're using multiple API Gateway instances
-2. You're using a custom naming convention for your API Gateway
-3. Your serverless deployment doesn't use CloudFormation outputs for the API Gateway
-
-The plugin will attempt to find your API Gateway by:
-1. First checking the CloudFormation stack outputs for the API ID
-2. If not found, it will try to find the API Gateway by its name (service-stage)
-
-If it still cannot find your API Gateway, you can manually specify the API ID in your serverless.yml:
-
-```yaml
-custom:
-  apiGatewayIntegrationTimeout: 60000  # Desired timeout
-  apiGatewayId: abcdef123  # Your API Gateway ID
-```
-
-## Important Notes
-
-- This plugin only works with full deployments (`serverless deploy`), as it needs to modify the API Gateway after deployment.
-- The plugin runs during the `after:deploy:deploy` lifecycle hook.
-- The default integration timeout in API Gateway is 29,000 milliseconds (29 seconds).
-- Integration timeouts above 29 seconds require a service quota increase for your AWS account.
-- The minimum integration timeout allowed by AWS is 50 milliseconds.
-- After modifying the timeout, the plugin creates a new deployment to apply the changes.
+This approach is lightweight and doesn't require any post-deployment modifications to the API Gateway.
 
 ## Example
 
@@ -133,30 +87,62 @@ provider:
   name: aws
   runtime: nodejs18.x
   region: us-east-1
-  timeout: 60  # Lambda timeout in seconds - will also be used for API Gateway
 
 plugins:
   - serverless-api-gateway-integration-timeout
 
-custom:
-  # Explicitly set API Gateway timeout if needed
-  # apiGatewayIntegrationTimeout: 60000  # 60 seconds
-  
-  # Set the maximum allowed by your account's service quota
-  apiGatewayMaxTimeout: 60000  # Your account's limit
-  
-  # Optional: Specify API Gateway ID manually if needed
-  # apiGatewayId: abcdef123
-
 functions:
-  processData:
-    handler: handler.processData
+  processingFunction:
+    handler: handler.process
     timeout: 60  # Lambda timeout in seconds
     events:
       - http:
           path: /process
           method: post
-          cors: true
+          integration: AWS_PROXY
+          timeout: 60  # API Gateway timeout in seconds
+  
+  reportFunction:
+    handler: handler.report
+    timeout: 29  # Lambda timeout in seconds
+    events:
+      - http:
+          path: /report/{id}
+          method: get
+          timeout: 29  # API Gateway timeout in seconds
+```
+
+Example `handler.js`:
+
+```javascript
+'use strict';
+
+module.exports.process = async (event) => {
+  // This function can run for up to 60 seconds
+  // API Gateway will wait for up to 60 seconds for a response
+  await new Promise(resolve => setTimeout(resolve, 50000));
+  
+  return {
+    statusCode: 200,
+    body: JSON.stringify({
+      message: 'Process completed successfully',
+    }),
+  };
+};
+
+module.exports.report = async (event) => {
+  // This function can run for up to 29 seconds
+  // API Gateway will wait for up to 29 seconds for a response
+  await new Promise(resolve => setTimeout(resolve, 25000));
+  
+  return {
+    statusCode: 200,
+    body: JSON.stringify({
+      message: 'Report generated successfully',
+      reportId: event.pathParameters.id,
+    }),
+  };
+};
 ```
 
 ## License

index.js

@@ -1,5 +1,5 @@
 'use strict';
 
-const UpdateAPIGatewayIntegrationTimeout = require('./src/updateAPIGatewayIntegrationTimeout');
+const IntegrationTimeout = require('./src/updateAPIGatewayIntegrationTimeout');
 
-module.exports = UpdateAPIGatewayIntegrationTimeout;
+module.exports = IntegrationTimeout;

package.json

@@ -1,7 +1,7 @@
 {
   "name": "serverless-api-gateway-integration-timeout",
-  "version": "1.0.7",
-  "description": "Serverless Framework plugin to update API Gateway integration timeout based on AWS service quota",
+  "version": "2.0.0",
+  "description": "Serverless Framework plugin to set API Gateway integration timeout directly in http events",
   "main": "index.js",
   "scripts": {
     "test": "echo \"Error: no test specified\" && exit 1"