Add automatic SQS request batching support component: sqs

[khc41]

📢 Type of change

• Bugfix
• New feature
• Enhancement
• Refactoring

📜 Description

Added automatic SQS batching support using AWS SDK's SqsAsyncBatchManager.

This feature enables automatic request batching for SQS operations to improve performance and reduce AWS API calls. When enabled, Spring Cloud AWS automatically wraps the SqsAsyncClient with a BatchingSqsClientAdapter that uses SqsAsyncBatchManager internally.

Key Features:

• Automatic batching for sendMessage, receiveMessage, deleteMessage, and changeMessageVisibility operations
• Configurable batch size, frequency, and timeout settings
• Full Spring Boot auto-configuration support
• Transparent integration with existing SqsTemplate and @SqsListener code
• Smart attribute handling to avoid AWS SDK batching bypass

Configuration Example:

spring.cloud.aws.sqs.batch.enabled=true
spring.cloud.aws.sqs.batch.max-number-of-messages=10
spring.cloud.aws.sqs.batch.send-batch-frequency=PT0.2S

Important: Operations are processed asynchronously. Applications should handle returned CompletableFuture objects to detect actual transmission errors.

💡 Motivation and Context

AWS SDK 2.28.0+ introduced automatic request batching capabilities that can significantly improve SQS performance and reduce costs by combining multiple API calls into fewer requests.

Previously, users had to manually implement batching logic or use explicit batch operations. This change enables declarative batching at the configuration level, providing:

• Improved performance: Reduced network overhead and latency
• Cost reduction: Fewer API calls mean lower AWS charges
• Better resource utilization: More efficient use of network and AWS resources
• Zero code changes: Existing applications work without modification

This addresses the community request for supporting AWS SDK's new automatic batching feature in Spring Cloud AWS.

💚 How did you test it?

Unit Tests:

• BatchingSqsClientAdapterTests: Comprehensive testing of all adapter methods with mock SqsAsyncBatchManager
• Verified proper delegation of all SQS operations and error handling

Integration Tests:

• BatchingSqsClientAdapterIntegrationTests: Real SQS environment testing with LocalStack
• Verified actual message sending, receiving, deleting, and visibility changes
• Tested batching efficiency with multiple concurrent operations

Auto-Configuration Tests:

• Extended SqsAutoConfigurationTest with comprehensive batch configuration testing
• Verified conditional bean creation based on spring.cloud.aws.sqs.batch.enabled
• Tested all configuration properties mapping and validation

📝 Checklist

• I reviewed submitted code
• I added tests to verify changes
• I updated reference documentation to reflect the change
• All tests passing
• No breaking changes

🔮 Next steps

This implementation provides full support for AWS SDK's automatic batching capabilities. Future enhancements could include:

• Metrics and monitoring integration for batch performance
• Advanced batching strategies based on message types
• Enhanced observability for batching operations

Related AWS SDK Documentation: Use automatic request batching for Amazon SQS

Resolves #1355

[tomazfernandes]

Hi @khc41, thanks again for the PR.

I’ve taken a closer look and wanted to share some thoughts.

Overall, I think adding support for batching via the new AWS SDK implementation is a valuable direction. That said, I believe the best path forward would be to scope the integration a bit more narrowly than what’s currently proposed.

Listener Use Case

For the @SqsListener flow, batching is already handled internally via receiveMessageBatch, and additional asynchronous batching layers would introduce complexity to an already nuanced runtime, with limited performance benefits in most scenarios.

Template and Custom Flows

The value of batching is clearer for SqsTemplate and similar client-side usage. For example, users sending one message at a time could benefit from reduced API calls without needing to change their application code.

Focus on the Adapter

To me, the most compelling piece in this PR is the BatchingSqsClientAdapter. It offers a clean way to wrap the SDK's batching client and expose it via the SqsAsyncClient interface, making it easy to plug into SqsTemplate or custom use cases.

I’d suggest focusing the contribution around:

• Providing the adapter as a supported utility
• Documenting how users can configure SqsAsyncBatchManager and wrap it
• Calling out caveats for using it with the listener
• Avoiding autoconfiguration for now, so users can configure the manager using the AWS API. We can always add support later.

This direction keeps the structure composable and aligned with the framework’s current architecture, while still enabling users to adopt the batching client where it makes the most impact.

Happy to hear your thoughts, and open to adjustments if you see strong use cases on the listener side.

Thanks again for all the work on this!

[khc41]

Hi @tomazfernandes,

Thank you for your thoughtful and detailed feedback. I completely agree with your suggestions.

You've made an excellent point about the @SqsListener use case; the added complexity likely outweighs the benefits since it already handles batching internally. Focusing on SqsTemplate and custom flows is the right direction.

As you proposed, I will update the PR to:

• Remove the auto-configuration part.
• Remove the related batch properties (in SqsProperties) and associated tests.
• Keep the BatchingSqsClientAdapter as the main contribution.
• Enhance the documentation (e.g., in sqs.adoc) to guide users on manually configuring the SqsAsyncBatchManager and the adapter.
• Add the recommended caveats for using it with @SqsListener.

Thanks again for the great guidance! I'll push the changes soon.

[khc41]

Hi @tomazfernandes,

Thank you again for the detailed feedback. I've pushed the updates to align with your suggestions.

The PR is now focused on providing the BatchingSqsClientAdapter and includes documentation on how to configure it manually, along with the recommended caveats.
The auto-configuration parts have been removed as discussed.

I'd appreciate it if you could take another look when you have a moment. Thanks!

[khc41]

Hi @tomazfernandes,

After giving it some more thought, I wanted to leave a comment to explain the reasoning behind guiding users to use @qualifier in the documentation.

My concern is that if the BatchingSqsClientAdapter were registered as the primary SqsAsyncClient bean, it could unintentionally affect other components, most notably the @SqsListener infrastructure. While the AWS SDK documentation states that receiveMessage can be bypassed under certain conditions, other operations in the listener's lifecycle, such as deleteMessage or changeMessageVisibility, would still risk being batched.

Therefore, I concluded that explicitly separating them using @qualifier is the safest and most predictable approach. I believe this aligns well with your previous feedback, but please let me know if you have a different perspective.

I'd appreciate it if you could take a look when you have a moment.
Thanks again for your time!

[tomazfernandes]

Hey @khc41, thanks for the updates.

I've left a couple of comments - would you be able to run a couple of tests to assert the exact behavior for sending and receiving messages, so we can document it?

Let me know if it makes sense to you, thanks.

[tomazfernandes]

How about we call out earlier that this feature is mostly intended to be used with the SqsTemplate rather than a general client to be used as a default bean, including in @SqsListener?

[khc41]

Updated the docs with this note at the beginning of the section

Please note that this feature is primarily intended for use with SqsTemplate and is not recommended for use with `@SqsListener due to the complexities involved in message acknowledgment and processing.

[tomazfernandes]

This is actually standard behavior for sendAsync operations, so I wonder what's the specific behavior for this client.

For instance, if we execute a send operation and join the thread, will it wait until sendRequestFrequency to complete the Future?

Also, this part of the documentation states: When you poll the SqsAsyncBatchManager#receiveMessage method in your application, the batch manager fetches messages from its internal buffer, which the SDK automatically updates in the background.

I would assume this background buffering would only start after the first call to receiveMessage, but that's worth checking as well.

[khc41]

You're right. This is standard for sendAsync, but here's the specific behavior for this batching client:

• For send operations: Yes, .join() waits until the sendRequestFrequency to complete the Future. Verified this with the new integration test shouldSendMessageJoinCompletesAfterFrequency.
• For receiveMessage buffering: Your assumption is correct. It starts only after the first call to receiveMessage. Confirmed via AWS SDK source code (buffer is created on demand via computeIfAbsent), but testing directly is challenging due to internal implementation. Here's the relevant snippet:

public CompletableFuture<ReceiveMessageResponse> batchRequest(ReceiveMessageRequest request) {
    String ineligibleReason = this.checkBatchingEligibility(request);
    if (ineligibleReason == null) {
        return ((ReceiveBatchManager)this.receiveBatchManagerMap.computeIfAbsent(this.generateBatchKey(request), (key) -> this.createReceiveBatchManager(request))).processRequest(request);
    } else {
        log.debug(() -> String.format("Batching skipped. Reason: %s", ineligibleReason));
        return this.sqsClient.receiveMessage(request);
    }
}

[khc41]

Hi @tomazfernandes,

Got it, thanks for the feedback. I'll run those tests to clarify the behavior and update the docs accordingly.
Will push the changes soon.

[khc41]

Hi @tomazfernandes,

Thanks again for the detailed feedback. I've pushed the updates addressing all your points.

Here's a quick summary of what's changed:

• Documentation: Updated the sqs.adoc file to clarify that the batching feature is primarily intended for SqsTemplate.
• sendAsync Behavior: Added the new shouldSendMessageJoinCompletesAfterFrequency test to verify that .join() indeed waits for the sendRequestFrequency.
• receiveMessage Buffering: Confirmed your assumption about the lazy initialization of the background buffer. I've left a more detailed reply with a code snippet on your original comment.

I'd appreciate it if you could take another look when you have a moment.
Thanks again for your time!

[tomazfernandes]

This will be included in the upcoming 4.0.0 release.

[tomazfernandes]

Looks great @khc41, just a couple of small comments and we should be good to merge.

Feel free to add a sample if you'd like, but that's optional.

Thanks!

[khc41]

Thanks @tomazfernandes!
I've applied the suggestions for the docs.
Really appreciate you guiding me through this, it was a great experience.

[tomazfernandes]

Thanks for the updates @khc41!

There's a failing test in the CI though, could you take a look please?
https://github.com/awspring/spring-cloud-aws/actions/runs/18650390676/job/53667193416?pr=1438

[khc41]

Hi @tomazfernandes,

I've pushed a fix for the flaky CI test. It was a timing issue caused by Thread.sleep.

I replaced all Thread.sleep calls with SQS Long Polling (waitTimeSeconds(10)) to make the tests reliable. This should fix the build.

Could you please take another look when you have a moment?

Thanks!

[tomazfernandes]

Thanks for the PR @khc41! Looking forward to more!