feat(lambda): function construct exposes configured timeout (#17594)

Supersedes #17000.

I didn't realise that the "allow edits by maintainers" was not supported under organisation accounts, so I've forked under my account instead. Otherwise, these changes are the same as the linked PR.

Thanks! 👍 

----

*By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license*

Author: ben-eb

packages/@aws-cdk/aws-lambda/README.md

@@ -119,6 +119,38 @@ myRole.addManagedPolicy(iam.ManagedPolicy.fromAwsManagedPolicyName("service-role
 myRole.addManagedPolicy(iam.ManagedPolicy.fromAwsManagedPolicyName("service-role/AWSLambdaVPCAccessExecutionRole")); // only required if your function lives in a VPC
 ```
 
+## Function Timeout
+
+AWS Lambda functions have a default timeout of 3 seconds, but this can be increased
+up to 15 minutes. The timeout is available as a property of `Function` so that
+you can reference it elsewhere in your stack. For instance, you could use it to create
+a CloudWatch alarm to report when your function timed out:
+
+```ts
+import * as cdk from '@aws-cdk/core';
+import * as cloudwatch from '@aws-cdk/aws-cloudwatch';
+
+const fn = new lambda.Function(this, 'MyFunction', {
+   runtime: lambda.Runtime.NODEJS_12_X,
+   handler: 'index.handler',
+   code: lambda.Code.fromAsset(path.join(__dirname, 'lambda-handler')),
+   timeout: cdk.Duration.minutes(5),
+});
+
+if (fn.timeout) {
+   new cloudwatch.Alarm(this, `MyAlarm`, {
+      metric: fn.metricDuration().with({
+         statistic: 'Maximum',
+      }),
+      evaluationPeriods: 1,
+      datapointsToAlarm: 1,
+      threshold: fn.timeout.toMilliseconds(),
+      treatMissingData: cloudwatch.TreatMissingData.IGNORE,
+      alarmName: 'My Lambda Timeout',
+   });
+}
+```
+
 ## Resource-based Policies
 
 AWS Lambda supports resource-based policies for controlling access to Lambda

packages/@aws-cdk/aws-lambda/lib/function.ts

@@ -577,6 +577,12 @@ export class Function extends FunctionBase {
    * The architecture of this Lambda Function (this is an optional attribute and defaults to X86_64).
    */
   public readonly architecture?: Architecture;
+
+  /**
+   * The timeout configured for this lambda.
+   */
+  public readonly timeout?: Duration;
+
   public readonly permissionsNode = this.node;
 
 
@@ -725,6 +731,7 @@ export class Function extends FunctionBase {
     });
 
     this.runtime = props.runtime;
+    this.timeout = props.timeout;
 
     this.architecture = props.architecture;
 

packages/@aws-cdk/aws-lambda/test/function.test.ts

@@ -1842,6 +1842,39 @@ describe('function', () => {
     });
   });
 
+  describe('lambda.Function timeout', () => {
+    test('should be a cdk.Duration when defined', () => {
+      // GIVEN
+      const stack = new cdk.Stack();
+
+      // WHEN
+      const { timeout } = new lambda.Function(stack, 'MyFunction', {
+        handler: 'foo',
+        runtime: lambda.Runtime.NODEJS_12_X,
+        code: lambda.Code.fromAsset(path.join(__dirname, 'handler.zip')),
+        timeout: cdk.Duration.minutes(2),
+      });
+
+      // THEN
+      expect(timeout).toEqual(cdk.Duration.minutes(2));
+    });
+
+    test('should be optional', () => {
+      // GIVEN
+      const stack = new cdk.Stack();
+
+      // WHEN
+      const { timeout } = new lambda.Function(stack, 'MyFunction', {
+        handler: 'foo',
+        runtime: lambda.Runtime.NODEJS_12_X,
+        code: lambda.Code.fromAsset(path.join(__dirname, 'handler.zip')),
+      });
+
+      // THEN
+      expect(timeout).not.toBeDefined();
+    });
+  });
+
   describe('currentVersion', () => {
     // see test.function-hash.ts for more coverage for this
     test('logical id of version is based on the function hash', () => {