agent-claw: automated task changes

cdk/node_modules/aws-cdk-lib/aws-lambda-destinations/README.md

@@ -0,0 +1,150 @@
+# Amazon Lambda Destinations Library
+
+
+This library provides constructs for adding destinations to a Lambda function.
+Destinations can be added by specifying the `onFailure` or `onSuccess` props when creating a function or alias.
+
+## Destinations
+
+The following destinations are supported
+
+* Lambda function
+* SQS queue - Only standard SQS queues are supported for failure destinations, FIFO queues are not supported.
+* SNS topic
+* EventBridge event bus
+* S3 bucket
+
+Example with a SNS topic for successful invocations:
+
+```ts
+// An sns topic for successful invocations of a lambda function
+import * as sns from 'aws-cdk-lib/aws-sns';
+
+const myTopic = new sns.Topic(this, 'Topic');
+
+const myFn = new lambda.Function(this, 'Fn', {
+  runtime: lambda.Runtime.NODEJS_LATEST,
+  handler: 'index.handler',
+  code: lambda.Code.fromAsset(path.join(__dirname, 'lambda-handler')),
+  // sns topic for successful invocations
+  onSuccess: new destinations.SnsDestination(myTopic),
+})
+```
+
+Example with a SQS queue for unsuccessful invocations:
+
+```ts
+// An sqs queue for unsuccessful invocations of a lambda function
+import * as sqs from 'aws-cdk-lib/aws-sqs';
+
+const deadLetterQueue = new sqs.Queue(this, 'DeadLetterQueue');
+
+const myFn = new lambda.Function(this, 'Fn', {
+  runtime: lambda.Runtime.NODEJS_LATEST,
+  handler: 'index.handler',
+  code: lambda.Code.fromInline('// your code'),
+  // sqs queue for unsuccessful invocations
+  onFailure: new destinations.SqsDestination(deadLetterQueue),
+});
+```
+
+See also [Configuring Destinations for Asynchronous Invocation](https://docs.aws.amazon.com/lambda/latest/dg/invocation-async.html#invocation-async-destinations).
+
+### Invocation record
+
+When a lambda function is configured with a destination, an invocation record is created by the Lambda service
+when the lambda function completes. The invocation record contains the details of the function, its context, and
+the request and response payloads.
+
+The following example shows the format of the invocation record for a successful invocation:
+
+```json
+{
+	"version": "1.0",
+	"timestamp": "2019-11-24T23:08:25.651Z",
+	"requestContext": {
+		"requestId": "c2a6f2ae-7dbb-4d22-8782-d0485c9877e2",
+		"functionArn": "arn:aws:lambda:sa-east-1:123456789123:function:event-destinations:$LATEST",
+		"condition": "Success",
+		"approximateInvokeCount": 1
+	},
+	"requestPayload": {
+		"Success": true
+	},
+	"responseContext": {
+		"statusCode": 200,
+		"executedVersion": "$LATEST"
+	},
+	"responsePayload": "<data returned by the function here>"
+}
+```
+
+In case of failure, the record contains the reason and error object:
+
+```json
+{
+  "version": "1.0",
+  "timestamp": "2019-11-24T21:52:47.333Z",
+  "requestContext": {
+    "requestId": "8ea123e4-1db7-4aca-ad10-d9ca1234c1fd",
+    "functionArn": "arn:aws:lambda:sa-east-1:123456678912:function:event-destinations:$LATEST",
+    "condition": "RetriesExhausted",
+    "approximateInvokeCount": 3
+  },
+  "requestPayload": {
+    "Success": false
+  },
+  "responseContext": {
+    "statusCode": 200,
+    "executedVersion": "$LATEST",
+    "functionError": "Handled"
+  },
+  "responsePayload": {
+    "errorMessage": "Failure from event, Success = false, I am failing!",
+    "errorType": "Error",
+    "stackTrace": [ "exports.handler (/var/task/index.js:18:18)" ]
+  }
+}
+```
+
+#### Destination-specific JSON format
+
+* For SNS/SQS (`SnsDestionation`/`SqsDestination`), the invocation record JSON is passed as the `Message` to the destination.
+* For Lambda (`LambdaDestination`), the invocation record JSON is passed as the payload to the function.
+* For EventBridge (`EventBridgeDestination`), the invocation record JSON is passed as the `detail` in the PutEvents call.
+The value for the event field `source` is `lambda`, and the value for the event field `detail-type`
+is either 'Lambda Function Invocation Result - Success' or 'Lambda Function Invocation Result – Failure',
+depending on whether the lambda function invocation succeeded or failed. The event field `resource`
+contains the function and destination ARNs. See [AWS Events](https://docs.aws.amazon.com/eventbridge/latest/userguide/aws-events.html)
+for the different event fields.
+* For S3 (`S3Destination`), the invocation record json is stored as a `File` in the destination bucket. The path of a destination 
+payload file in the configured bucket is `aws/lambda/async/<function-name>/YYYY/MM/DD/YYYY-MM-DDTHH.MM.SS-<Random UUID>`. 
+
+### Auto-extract response payload with lambda destination
+
+The `responseOnly` option of `LambdaDestination` allows to auto-extract the response payload from the
+invocation record:
+
+```ts
+// Auto-extract response payload with a lambda destination
+declare const destinationFn: lambda.Function;
+
+const sourceFn = new lambda.Function(this, 'Source', {
+  runtime: lambda.Runtime.NODEJS_LATEST,
+  handler: 'index.handler',
+  code: lambda.Code.fromAsset(path.join(__dirname, 'lambda-handler')),
+  // auto-extract on success
+  onSuccess: new destinations.LambdaDestination(destinationFn, {
+    responseOnly: true,
+  }),
+})
+```
+
+In the above example, `destinationFn` will be invoked with the payload returned by `sourceFn`
+(`responsePayload` in the invocation record, not the full record).
+
+When used with `onFailure`, the destination function is invoked with the error object returned
+by the source function.
+
+Using the `responseOnly` option allows to easily chain asynchronous Lambda functions without
+having to deal with data extraction in the runtime code.