# AmazonSQS CloudEvents Sample


## Prerequisites

### Security and access configuration

Add the [AWS Access Key ID and AWS Secret Access Key](https://docs.aws.amazon.com/general/latest/gr/aws-sec-cred-types.html#access-keys-and-secret-access-keys) to the following environment variables:

* Access Key ID in `AWS_ACCESS_KEY_ID`
* Secret Access Key in `AWS_SECRET_ACCESS_KEY`
* Default Region in `AWS_REGION`

See also [AWS Account Identifiers](https://docs.aws.amazon.com/general/latest/gr/acct-identifiers.html), [Managing Access Keys for an AWS Account](https://docs.aws.amazon.com/general/latest/gr/managing-aws-access-keys.html), and [IAM Security Credentials](https://console.aws.amazon.com/iam/home#/security_credential).

See also [AWS Regions](https://docs.aws.amazon.com/general/latest/gr/rande.html) for a list of available regions.

### S3 configuration

The S3 bucket should be configured to generate notifications that are ultimately delivered to the SQS queue matching the endpoint. The following is a sample configuration that can be used to generate S3 notifications:

- Configure an S3 bucket to [send notifications to SQS](https://docs.aws.amazon.com/AmazonS3/latest/userguide/notification-how-to-event-types-and-destinations.html#supported-notification-event-types)
- Create an [Amazon EventBridge Pipe](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-pipes-event-target.html) that picks up the messages from the SQS queue
- Configure the Amazon EventBridge Pipe to [transform](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-pipes-input-transformation.html) messages to the CloudEvents schema as specified in the [CloudEvents specification](https://github.com/cloudevents/spec/blob/main/cloudevents/adapters/aws-s3.md)
- Configure the Amazon EventBridge Pipe to call AWS Lambda that would enrich messages with the proper `content-type` property and send them to the SQS queue matching the endpoint

## Code walk-through

This sample shows an endpoint receiving a CloudEvents message from the Amazon Simple Queue Service (Amazon SQS)

* The `Endpoint` defines the schema for the CloudEvents message.
* The `Endpoint` enables CloudEvents support and configures the type mapping.
* The `Endpoint` configures the serializer to support fields and properties with different casing.
* The `Endpoint` receives the message and calls the proper handler.

### CloudEvents message schema

The message schema is defined as follows:

<!-- snippet: sqs-cloudevents-message-definition -->

```cs
public class AwsBlobNotification :
    IMessage
{
    public string Key { get; set; }
    public int Size { get; set; }
    public string ETag { get; set; }
    public string Sequencer { get; set; }
}
```

<!-- endsnippet -->

This schema must match the schema of the [notification generated by S3](https://docs.aws.amazon.com/AmazonS3/latest/userguide/notification-how-to-event-types-and-destinations.html#supported-notification-event-types).

### CloudEvents support configuration

CloudEvents support must be explicitly enabled:

<!-- snippet: sqs-cloudevents-configuration -->

```cs
var cloudEventsConfiguration = endpointConfiguration.EnableCloudEvents();
```

<!-- endsnippet -->

The configuration includes the type mapping to match the message's content-type with the .NET types representing the incoming messages:

<!-- snippet: sqs-cloudevents-typemapping -->

```cs
cloudEventsConfiguration.TypeMappings["ObjectCreated:Put"] = [typeof(AwsBlobNotification)];
```

<!-- endsnippet -->

To handle the JSON structured messages that do not have the `Content-Type` header set properly, enable the Permissive mode:

<!-- snippet: sqs-cloudevents-json-permissive -->

```cs
cloudEventsConfiguration.EnvelopeUnwrappers.Find<CloudEventJsonStructuredEnvelopeUnwrapper>()?.EnvelopeHandlingMode = JsonStructureEnvelopeHandlingMode.Permissive;
```

<!-- endsnippet -->

To support the differences between uppercase letters and lowercase letters in the schema definition and content, the serializer is configured to use case insensitive mapping:

<!-- snippet: sqs-cloudevents-serialization -->

```cs
endpointConfiguration.UseSerialization<SystemJsonSerializer>().Options(new JsonSerializerOptions
{
    PropertyNameCaseInsensitive = true,
    IncludeFields = true
});
```

<!-- endsnippet -->


### Running the sample

1. Run the sample.
2. Generate the `ObjectCreated:Put` event by creating a new file in the S3 bucket.
3. Observe that the sample prints out the URL of the newly created file.