Configuring AWS SQS for Martini

Amazon Web Services (AWS) Simple Queue Service (SQS) offers a reliable, highly scalable hosted queue for storing messages as they travel between applications or microservices. Integrating AWS SQS with Martini allows developers to seamlessly connect their applications within the AWS ecosystem, enabling efficient message processing with minimal coding. Martini utilizes the AWS SQS SDK to poll and retrieve messages from queues, facilitating smooth communication between services.

Endpoint Definitions

Endpoint Type

aws-sqs-listener

Endpoint Configuration

Below are the configurations available for an AWS SQS listener endpoint in Martini:

Name	Required	Description
`queueName`	Yes	The name of the AWS SQS queue to be polled.
`pollTimeInSeconds`	No	The interval in seconds between polling requests. Defaults to 10. A higher value can reduce AWS costs.
`maxNumberOfMessage`	No	The maximum number of messages to poll in a single request. Defaults to 10.
`autoDelete`	No	Whether to delete the message automatically after the workflow or service completes successfully. Defaults to `true`. Set to `false` to delete it manually with the `deleteMessage` callback. Existing configurations without this property behave as `true`.
`awsCredentialOption`	Yes	Credential option for AWS authentication. `DEFAULT` utilizes the AWS credential provider chain. `BASIC` requires specifying `awsAccessKeyId`, `awsSecretKey`, and `awsSessionToken` in the endpoint properties.
`awsAccessKeyId`	No	Required if `awsCredentialOption` is set to `BASIC`. Specifies the AWS Access Key ID.
`awsSecretKey`	No	Required if `awsCredentialOption` is set to `BASIC`. Specifies the AWS Secret Access Key.
`awsSessionToken`	No	Required if `awsCredentialOption` is set to `BASIC`. Specifies the AWS Session Token. Can be left empty.
`messageAttributes`	Yes	A comma-separated list of message attributes to fetch during polling.

Endpoint Specific Properties

These properties are specific to messages retrieved from AWS SQS:

Name	Type	Description
`body`	String	The body of the AWS SQS message.
`message`	com.amazonaws.services.sqs.model.Message Object	The AWS SQS message object, containing all details of the message.
`messageAttributes`	Model Array	An array of key-value pairs representing the message attributes.
`messageId`	String	The unique identifier of the AWS SQS message.
`queueName`	String	The name of the AWS SQS queue being polled.
`receiptHandle`	String	The receipt handle of the AWS SQS message, used for message deletion or change visibility.

See AWS SQS Message API Reference - Official AWS documentation for message field descriptions and usage.

Message deletion and redelivery

For workflow and service message deletion behavior (autoDelete and manual deleteMessage acknowledgement), see AWS SQS Trigger.

At the SQS queue level, configure redelivery and dead-letter queue (DLQ) routing in the queue redrive policy. maxReceiveCount determines when SQS moves a repeatedly received message to the DLQ. Without a DLQ, SQS continues redelivery until the message is deleted or its retention period expires.

Usage and Testing

This section guides you through the setup and testing of an AWS SQS Endpoint within Martini, including creating a new package and endpoint, and verifying message receipt.

1. Setup an AWS SQS Queue in AWS Console

Before integrating AWS SQS with Martini, create and configure your SQS queue in the AWS Console. Ensure you have the correct permissions and settings for your application's requirements.

2. Create a New Package and AWS SQS Endpoint

Without a graphical interface for this setup, you'll define your endpoint configuration in XML. This XML snippet defines an AWS SQS listener endpoint, specifying necessary credentials and configurations:

<endpoint type="aws-sqs-listener" name="MyEndpoint" service="Test/Test" enabled="true" modifiable="true">
    <properties>
        <property name="track">false</property>
        <property name="documentType">AWS Sqs Listener</property>
        <property name="replicated">true</property>
        <property name="queueName">ToroQueue</property>
        <property name="pollTimeInSeconds">10</property>
        <property name="maxNumberOfMessage">10</property>
        <property name="awsCredentialOption">BASIC</property>
        <property name="awsRegion">us-east-1</property>
        <property name="awsAccessKeyId">[YourAWSAccessKeyId]</property>
        <property name="awsSecretKey">[YourAWSSecretKey]</property>
        <property name="awsSessionToken">[YourAWSSessionToken]</property>
        <property name="messageAttributes">test1,test2</property>
    </properties>
</endpoint>

Ensure you replace [YourAWSAccessKeyId], [YourAWSSecretKey], and [YourAWSSessionToken] with your actual AWS credentials. If you prefer to use the default AWS credential provider chain, replace the BASIC credential option with DEFAULT and omit the AWS credential properties.

Alternatively, you can upload a pre-configured package, such as new-package.zip, which follows the same configuration principles outlined above.

3. Start the Endpoint

After defining your AWS SQS listener endpoint, start it within Martini. Verify that it's operational and ready to receive messages.

4. Send a Message to the Queue

Utilize the AWS Console to send a test message to your SQS queue. This step is crucial for validating the endpoint's ability to receive messages.

5. Verify Message Receipt

Upon sending a message, monitor Martini to confirm that it successfully receives the message. The receipt of the message will be indicated through the logging of different properties associated with the message, demonstrating the endpoint's operational status.